Repository navigation
feat(doctor): add a Temp directories row (tmpfs/no swap/low headroom) - #22672
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the row is read-only and advisory, reuses the existing mount resolver and swap reader, and leaves the exit code alone. Notes
[DESIGN-REVIEWED] d01d651 Description read[DESCRIPTION-READ] a18b80b626aa6054806be060e98a28a89667112c245594409eab55f72ad4861b That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The new row is read-only and advisory, it reuses the existing mount resolver and swap reader, and it does not re-measure the space and inode figures the Runtime tmpfs row already owns. Notes
What this change shipsInventory (6 items) — 3 justifiedIntent: the operator can see what filesystem backs their temp dir and gets a warning before tmpfs with no swap, or an age-based sweep, silently breaks work. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] d01d651 Description read[DESCRIPTION-READ] 13484d45d5eb90b651362fa0ee6028ffbcf995376bd9cb8fd49f6fe5e7c40219 That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
Opus 5.5 Review — ✅ no blocking findingsReviewed Review detailsNo findings. Notes:
[OPUS-REVIEWED] d01d651 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
423acdd to
c9b9e1f
Compare
c9b9e1f to
e7b0f8f
Compare
|
e7b0f8f to
5212113
Compare
5212113 to
88424d4
Compare
88424d4 to
3a365be
Compare
3a365be to
50d1188
Compare
|
50d1188 to
0ea8a5f
Compare
0ea8a5f to
38a2c22
Compare
aec8293 to
d4c9483
Compare
|
d4c9483 to
c7dcbaa
Compare
|
|
The red Coverage Gate on this head is not this PR's. It is the repo-wide regression tracked in #22697: on a backend-only diff the frontend-lint job is skipped, which poisons |
c7dcbaa to
d01d651
Compare
|
Rebased: main moved c7dcbaa's base (098bc0a) -> a8fe017. #25423 (merged) reworked the Runtime tmpfs row to measure /tmp and the process temp roots; this PR's diff is unchanged except one block-comment line and the body's motivation, which now describe that row accurately. Same 7 files; CI re-running. |
bolichen97
left a comment
There was a problem hiding this comment.
Good to ship. The new Temp directories row is read-only and advisory, never touches the exit code, and reuses the existing mount resolver and swap reader.
Head reviewed: d01d651. Readiness is passed, every check on this head is green, and all AI lanes pass with no BLOCK. Linked issue is tier T2.
What I verified at this head:
- Read every hunk in all 7 files.
- Ran the new row on a real Linux host. It printed the path, the filesystem type and the ageing line, and added no issue.
_tmpfiles_agesreturned True for/tmpand/var/tmpon that host's stock tmpfiles config. - Ran
TestTempDirectories,TestTmpfilesAgesandtest/test_taskq_store.py: 29 passed. - Security: the only new spawn is
systemd-tmpfiles --cat-config, resolved throughtrusted_system_bin, fixed argv, 5s timeout, stdout read only. No auth, trust boundary, sandbox, approval or secret change.
Two non-blocking notes:
taskq/store.pyline 248: no test pins the>to>=tie-break. I reverted it to>locally andtest/test_cli_doctor.pyplustest/test_taskq_store.pystill passed (208 passed). A small test with two/proc/mountslines at the same mount point (ext4 then tmpfs on/tmp) that expectstmpfswould pin it for both callers. A follow-up is fine.- The PR title still says "low headroom", but the row deliberately does not measure space or inodes. Dropping that word from the title would make the squash commit match the change.
Problem / Motivation
Goal:
kirocrew doctortells the operator what kind of filesystem their gateway's temp directory is, and warns before it fails work silently.The gateway, crons and CLI commands all write scratch to one temp directory (
TMPDIR). The existing "Runtime tmpfs" row warns when that directory runs low on space or inodes, but nothing shows the operator what it is: whether it is RAM-backed, whether swap can absorb a spike, or whether atmpfiles.drule deletes files there by age.Why it matters
The failure modes are silent and hard to diagnose. A RAM-backed temp dir with no swap throttles under memory pressure with
oom_killat 0 (#6788); an inode-exhausted temp dir returnsENOSPCwhile 90% of its bytes are free; andsystemd-tmpfilescan delete a run's work after 10 days. One doctor line turns each of these into one obvious message with a named workaround.Not a goal
tempfileresolution.What changed (motivation → approach → change)
Operators had no line naming what filesystem backs the temp directory their tools write scratch to, so a tmpfs-with-no-swap stall or a
systemd-tmpfilesage-sweep that deleted work looked like an unexplained failure.The approach adds only what the doctor does not already show, and reuses existing code for the rest. The directory is
tempfile.gettempdir()— with noTMPDIRset, the system default (/tmp), which a gateway installed without aTMPDIRoverride also uses. The filesystem type comes from the repo's existing mount-table resolver,taskq/store.py's_linux_mount_type(no second parser is added); swap comes from the existing_swap_total_kib(). One best-effort probe is added indoctor_checks/resources.py:_tmpfiles_ages()askssystemd-tmpfiles --cat-config(binary resolved through the trusted-bin pin, 5s cap) whether a rule ages the dir, returning unknown rather than guessing on anx/Xexclusion that covers the dir or a glob that could reach it.The new
_doctor_temp_directoriesrow indoctor_checks/resources.pyprints the path, filesystem and ageing, and warns — without touching the exit code — only when the dir is tmpfs with no swap: a RAM-backed temp dir with no release valve throttles under memory pressure. It deliberately does NOT re-measure space or inodes (the existing "Runtime tmpfs" row already warns on those for this exact directory, since it measures/tmpand the temp roots the process resolves,tempfile.gettempdir()included) and does NOT re-print the swap total (the Memory Pressure section already shows it). It names the directory it actually resolved rather than claiming to read the gateway service'sTMPDIR: this probe reads the CLI process's own environment and mount namespace, so a service given a divergentTMPDIRis not visible to it._linux_mount_type's longest-mount tie-break changes from>to>=so that, among stacked mounts at the same point, the visible topmost one wins (a tmpfs over an ext4/tmpreads as tmpfs) — a one-character correctness fix that also benefits its existing taskq caller. Every probe degrades to an informational line on failure, and the whole row reports the path plus "not applicable" on macOS and Windows.cli_doctor.pywires the row into the report orchestration and forwards the helper through its facade.Backwards compatibility
Compatible: the change adds a new read-only doctor row and one probe helper, and makes
_linux_mount_type's mount-point tie-break prefer the topmost of equal-depth stacked mounts (>to>=) — a correctness fix for an over-mounted path that changes no result where mounts are not stacked. No existing row, threshold ortempfileresolution changes.Removes nothing: the row is purely additive and no path, record, key or capability is removed or tightened.
Tests
New tests live in
test/test_cli_doctor.py; the doctor facade ratchet updated istest/test_cli_doctor_refactor_facade.pyand the report ratchettest/test_cli_doctor_refactor_report.py; the spawn-audit allowlist intest/spawn_audit_helpers.pygains the new probe. The reused resolvertaskq/store.py::_linux_mount_typekeeps its existing coverage intest/test_taskq_store.py.TestTempDirectories— the row passes on a healthy disk-backed dir; warns (and never adds an issue) only on tmpfs-with-no-swap; stays quiet on tmpfs-with-swap and on a disk-backed dir regardless of swap; never prints space/inodes (the Runtime tmpfs row's job) and never re-prints swap; reports ageing, unreadable-mount-table and unknown-tmpfiles informationally; prints path + "not applicable" and runs no Linux probe off Linux; and degrades cleanly whengettempdir()raises.TestTmpfilesAges— an age rule on the temp dir or a parent isTrue; a rule on a subdir or elsewhere, or with no age field, isFalse; anx/Xexclusion covering the dir, or a glob that could reach it, isNone(unknown); an exclusion strictly below the dir does not suppress a parent ageing rule; comments/blanks are ignored; an absent tool, non-zero exit or probe failure isNone.test_spawn_audit.py— thesystemd-tmpfiles --cat-configprobe is added to the benign-spawn allowlist as a fixed-argv, read-only, trusted-bin-resolved system query, alongside the existing doctor probes.Manual verification
Ran the row against the real host: it resolved the temp directory in use, reported
xfson its device and no ageing rule, fired no warning, and left the issues list empty — confirming the advisory, exit-code-neutral contract end to end.Screenshots / video
N/A — backend-only diagnostic row with no frontend or user-visible UI surface.
Related Issues
Closes #17126
Checklist