Repository navigation
fix(acp): judge the macOS runtime ceilings by phys_footprint, not ps RSS - #15766
Conversation
On macOS the background runtime's 500 MiB ceiling never fired. The tree sum behind AcpRuntime._is_stale read `ps -Ao pid=,ppid=,rss=`, and ps RSS counts only pages resident right now. macOS compresses and swaps idle memory aggressively, and an idle runtime that has grown consists mostly of exactly those pages. One Mac measured the gateway at 124 MB of RSS against 1983 MB of footprint (16x), with two idle runtimes holding 462 MB of footprint for hours. Add platform_compat.proc_phys_footprint_bytes_for_pid. It reads ri_phys_footprint through proc_pid_rusage(RUSAGE_INFO_V2): no subprocess, no entitlement for a same-uid pid. It is configured separately on the shared libproc handle, so a libproc without that symbol still serves the proc_pidinfo probes. On macOS the tree sum, and the single-pid read, measure each pid by its footprint, falling back to that pid's ps RSS only when the footprint cannot be read. The ps snapshot still provides the tree shape, in one walk. Backport of #15760 to release/0.8.0.
ad8c296 to
b562e2c
Compare
First Principles Review (Fable 5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS The What this change shipsInventory (7 items) — 7 justifiedIntent: FIX — on macOS the background runtime's 500 MiB ceiling never fires because
Counts run: [FIRST-PRINCIPLES-REVIEWED] b562e2c |
GPT 5.6 Review —
|
Design Review (Fable 5) — 🔴 BLOCK (blocking)Design-level review of Design-Verdict: BLOCK A darwin-only ABI read ships to release/0.8.0 unverified: no macOS lane runs on release-branch PRs, and no real Mac ran it. BlockersHand-pinned [DESIGN-REVIEWED] b562e2c |
Opus 5 Review — ✅ no blocking findingsReviewed Review detailsNo findings worth blocking; one advisory below. FINDING — docs/system-specs/common/platform-compat.md:71 — the new row names [OPUS-REVIEWED] b562e2c Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
|
/ai-review override design b562e2c: maintainer decision (bolichen): accept. Release-branch PRs have no macOS lane, but the darwin ABI read is byte-identical to #15760, whose ci:macos run executed TestTheRealDarwinAbi green on a real Mac; the insider release run builds and signs macOS artifacts before any promotion. |
Human judgment recorded@bolichen97 marked the gpt AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Human judgment recorded, but the following reviewer lane(s) could not be re-run automatically: GPT 5.6. Re-run the lane's latest workflow run for |
Human judgment recorded@bolichen97 marked the design AI finding as false positive, not applicable, or explicitly accepted for
This decision applies only to this commit. A new push requires a new judgment. |
|
Human judgment recorded, but the following reviewer lane(s) could not be re-run automatically: Design Review. Re-run the lane's latest workflow run for |
Problem / Motivation
Goal: on macOS, the background runtime's memory ceiling judges the memory the OS actually charges the runtime, so a runtime that has grown past it is recycled.
On macOS the 500 MiB ceiling (
AcpRuntime._is_stale) never fires (#15757). From one 16 GB Mac:psRSS against 1983 MB ofphys_footprint(16x);Why it matters
The ceiling is the only bound on a background runtime that keeps getting reused, and on macOS it is effectively disabled. Memory the runtime holds compressed or swapped is invisible to it, and that is exactly the memory jetsam counts when it kills processes on a full Mac. The Sessions panel's macOS memory figure, which reads the same tree sum, under-reports the same way.
Not a goal
test_bg_runtime_idle_recycle.py::test_a_fresh_idle_runtime_is_left_alonepins the opposite ("idle is not a reason to recycle, staleness is"). Changing that is a maintainer decision, recorded on macOS: background runtime memory ceiling reads ps RSS, which omits compressed pages, so it never fires #15757.get_session_rss_mbreturns 0 on macOS).What changed (motivation → approach → change)
Symptom: a macOS runtime holding gigabytes is never judged stale.
Root cause: on darwin,
_get_rss_tree_mbinsrc/kiro_crew/acp/runtime.pysummedps -Ao pid=,ppid=,rss=, and_get_rss_mbreadps -o rss=.psRSS counts only resident pages. macOS compresses and swaps idle memory aggressively, which is what an idle grown runtime mostly consists of.phys_footprint, which includes those pages.Change:
src/kiro_crew/platform_compat.pygainsproc_phys_footprint_bytes_for_pid(pid), which readsri_phys_footprintviaproc_pid_rusage(pid, RUSAGE_INFO_V2). It needs no subprocess and no entitlement for a same-uid pid, and it answersNoneoff macOS or when unreadable. The struct layout (16-byte uuid, then 18 uint64s, footprint the 8th) is pinned by a test.proc_pid_rusageis configured separately on the sharedlibprochandle, so alibprocwithout it still serves everyproc_pidinfoprobe.psRSS only when the footprint cannot be read. Thepssnapshot still provides the tree shape in one memoized walk, and the depth bound is unchanged._get_rss_mbprefers the footprint too.docs/system-specs/common/platform-compat.mdgets a new helper row;docs/system-specs/modules/session.mddocuments the staleness measurement.Backwards compatibility
Compatible: same function signatures and units (MiB). On macOS the figure is now the footprint, so the ceiling can fire where it could not before. That is the intended fix, and a runtime with sessions is still only parked, never killed under a co-tenant.
Tests
test/test_macos_phys_footprint.py(13 tests):libproc, both read as None;libprocwithoutproc_pid_rusagestill serves the shared handle;_is_stale()return"rss", and a small footprint does not.Existing fixtures that pin the
pspath now pin the footprint off. Otherwise a real Mac would answer for a same-uid pid the fake table names. On this branch the only such fixture is intest/test_macos_process_table.py.Regression proof: with
runtime_process_tree.pyreverted and the tests kept, 5 fail. The related files (session memory, bg-runtime recycle, platform_compat, process tree, facade, spawn audit) pass: 1180 passed.Manual verification
Not run on a real Mac: this host is Linux, so the libproc call is exercised through a fake library that fills a real
ctypesbuffer, which is the established pattern for the other_darwin_*probes. A reviewer on macOS can comparepython3 -c "from kiro_crew import platform_compat as p, os; print(p.proc_phys_footprint_bytes_for_pid(os.getpid()))"with Activity Monitor's Memory column for that python process.Gates:
check_subprocess_encoding,check_comment_historyand the harness-parity gate.vector_memory_runtime/lessons.py:1206, fixed by fix(memory): read turn_lessons' row-token helper through text_scoring #15737.scripts/local-gate.py: 43540 passed, with 6 failures that fail identically on pristined5bdff64e0:test_fold_cataloguex3 (fix(crew-log): regenerate the fold catalogue for the subagents fold #15744);test_vector_memory_composition_contractx2 (fix(memory): read turn_lessons' row-token helper through text_scoring #15737);test_servicex1, host-dependentsystemctl.Related Issues
Backport of #15760 to
release/0.8.0. Refs #15757.Conflict resolved: on this branch the process-tree helpers still live in
src/kiro_crew/acp/runtime.py(acp/runtime_process_tree.pyand the refactor facade tests arrived on main later). So the same two hunks (_get_rss_mband the macOS tree sum) are applied there, andtest/test_acp_refactor_*are not carried. The new tests, together with the macOS process table, platform_compat, bg-runtime recycle, session-memory and spawn-audit suites, pass here (877).test/test_acp_runtime.pyhas 3 reds under-n 6that fail identically on pristinerelease/0.8.0@ f8d6039 and pass serially.Pattern harvest
Rule candidate: review-prompt
Pattern: a macOS memory ceiling that reads
psRSS; on macOS the figure the OS acts on isphys_footprint, and RSS can understate it by an order of magnitude.Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement