Repository navigation
fix: warn at start-up when a container limit pins memory at critical - #38371
bolichen97 wants to merge 1 commit into
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. This is one cause-naming start-up log line that changes no behaviour. The fix that scales the thresholds was ruled out by the maintainer decision on #37490 and is listed under Not a goal. What this change shipsInventory (3 items) — 3 justifiedIntent: an operator running in a small container learns once at start-up why memory reads critical and which settings to lower. FIX.
[FIRST-PRINCIPLES-REVIEWED] 191abd4 Description read[DESCRIPTION-READ] e769131d112ad2071a65b717b8022a517ff0ddc0d0ac6687d6c70e4f0cda307d That sha256 names the PR description this verdict read. Recompute it with |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: this is one log line at start-up, read-only and never awaited, and it takes nothing away. Notes
[DESIGN-REVIEWED] 191abd4 Description read[DESCRIPTION-READ] be9a24eda90289fdb1d3923e16a22bbb0e9bb54e2d4f047c60424a25984a97b7 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 |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
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: |
The available-memory figure is clamped to the container's cgroup headroom, so in a container whose memory limit is at or under the absolute agent.resource_critical_gb it can never rise above that threshold: with the defaults the posture reads critical for good and no sub-agent can start. Nothing told the operator why or what to change. At start-up the gateway logs one warning, in the background and never awaited, when the tightest container memory limit is at or under the raw configured critical threshold, naming the limit and the settings to lower. No threshold or gate changes.
069d607 to
191abd4
Compare
Problem / Motivation
Goal: A gateway running in a container whose memory limit is at or under
agent.resource_critical_gbsays so once at start-up and names the settings to lower.In a container limited to 2 GB, the free-memory reading can never rise above 2 GB, and
agent.resource_critical_gbis 2 GB by default. So the memory posture readscriticalfrom the first second, background helpers are refused, the spawn gate sits at its floor, and with the defaultagent.spawn_min_memory_gbno sub-agent can start. The log never said why, or which settings to change.Why it matters
In a 2 GB container the memory reading can never rise above the critical threshold, so the posture reads critical for good and, with the defaults, no sub-agent can start; nothing told the operator why or what to change.
Not a goal
What changed (motivation → approach → change)
The operator gets one warning at start-up that names the cause and the fix. Nothing else behaves differently.
resource_status_container_limit.pymodule (a sibling ofresource_status_agent_ceiling.py, sinceresource_status.pyis past the 1,600-line target) checks the tightest container memory limit against the rawagent.resource_critical_gb, the value the spawn gate reads. When the limit is at or under it, it logs: "The container memory limit (2.0 GB) is at or under agent.resource_critical_gb (2.0 GB), so available memory can never rise above it. For a container this small, lower agent.resource_critical_gb, agent.resource_pressure_gb and agent.spawn_min_memory_gb."gateway_runtime/process_entry.py) schedules it the way the plain-text credentials notice is scheduled, in the background and never awaited, so the dashboard binds no later.resource_critical_gbhelp text inconfig/sections_agent.py(andconfig-baseline.json) anddocs/architecture/resource-protection.mdsay a container at or under the threshold gets this warning.Backwards compatibility
Compatible: the only addition is one log line at start-up; no threshold, gate, config key or refusal text changes.
Removes nothing: the diff only adds a background log notice, a help-text sentence and a doc sentence.
Tests
test/test_resource_status.py::test_container_limit_at_critical_logs_one_startup_warningdrives the start-up scheduler with the cgroup reading patched, so the real host is never read:resource_critical_gbset to 0: no warning;resource_pressure_gb1.0 withresource_critical_gb2.0 under a 2 GB limit: still one warning, because the spawn gate compares the raw critical value.Proof: PROVEN test/test_resource_status.py::test_container_limit_at_critical_logs_one_startup_warning[2-None-None-True], test/test_resource_status.py::test_container_limit_at_critical_logs_one_startup_warning[8-None-None-False], test/test_resource_status.py::test_container_limit_at_critical_logs_one_startup_warning[None-None-None-False], test/test_resource_status.py::test_container_limit_at_critical_logs_one_startup_warning[2-1.0-2.0-True], test/test_resource_status.py::test_container_limit_at_critical_logs_one_startup_warning[2-None-0.0-False] (head 191abd4)
prove.py ran on a Linux host against tree
2ed5359c1ea2, the tree of this head.Determinism: the five cases passed 5 runs in a row, the whole file passed in reversed node order (160 passed), and it passed again under
-n auto --dist loadgroup --max-worker-restart=2(160 passed). No sleeps and no fixed short wait: the test awaits the notice task withkiro_crew.testing.wait.await_until. The flake-pattern ratchet passed, and so did the wait-discipline ratchet in its committed-baseline and pull-request modes.Gates on that host: all 66 entries of the repository's gate profile, each run as written, exited 0. They include
flake8,isort,mypy src/kiro_crew/(no issues in 4899 source files), the docs lint, the website build,tsc, eslint and the bundle checks, the backend related tests (22 files: 1917 passed, 1 skipped) and the frontend related tests (15625 passed). Also clean: the semgrep rules on the diff (0 findings),scripts/generate_config_baseline.pywith no diff, and a merge check against currentmain(clean).Manual verification
Host: Ubuntu 24.04.5 LTS, cgroup v2. Each run was a real isolated gateway (its own
KIROCREW_HOME,HOMEandKIRO_HOMEundermktemp -d, a free 127.0.0.1 port) started insidesystemd-run --user --scope -p MemoryMax=<N> -p MemorySwapMax=0, and stopped by its own PID.Before the fix, 2 GB scope:
resource_status.probe()readavailable_gb=1.87, posture='critical'. The gateway became ready (health 200) and logged no line naming the limit or any setting.With the fix, 2 GB scope, exactly one line:
With the fix, 8 GB scope (happy path): the gateway became ready and logged no such line (probe:
available_gb7.91, postureample).Related Issues
Closes #37490
Sibling sweep
Swept: git grep -nE "resource_critical_gb|spawn_min_memory_gb|_container_cgroup_reading" -- src/kiro_crew
Siblings: none -- the posture, the adaptive gate and the spawn floor all read the same container-capped figure, and this one notice names all three settings
Pattern harvest
Not generalizable: a one-off mismatch between a fixed GB default and a container limit at or under it; the maintainer decision keeps the thresholds fixed, so the remedy is this one start-up notice rather than a rule.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license; see the Licensing section of CONTRIBUTING.md.