Skip to content

docs(rfc): resource control: CPU in the host posture, re-wakes while tight, add-only remote probe - #39344

Open
iamwhatever wants to merge 1 commit into
mainfrom
docs/rfc-resource-control
Open

iamwhatever wants to merge 1 commit into
mainfrom
docs/rfc-resource-control

Conversation

@iamwhatever

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: Record one reviewable design for the three resource-control gaps left after the host memory guard, so the owner's team can review it before any of it is built.

The host memory guard (#39188, merged; fast layer #39270 and slow layer #39289, open) protects one host's memory and disk. Three gaps remain:

  1. The host posture ignores CPU. _classify in src/kiro_crew/resource_status.py reads memory only; load_per_cpu is reported but never part of the posture, so a CPU-saturated host never wakes its conductor.
  2. The posture wake in feat(conductor): per-worker memory and disk view, posture-change wake, host-health rule #39289 fires only on a level change. A host that stays tight while free memory or disk keeps falling, or one worker that grows fast, never re-wakes the conductor until the host reaches critical, when the fast layer is already stopping trees.
  3. Remote and cloud resources (cloud machines, quotas, spend) are invisible. A conductor can only learn about them by spending a full model turn on every patrol to look.

Why it matters

Without (1) and (2), the conductor's "Keep the host healthy" rule from #39289 gets no chance to act gently before forced action. Without (3), every conductor that depends on cloud resources pays a model turn per patrol (12 an hour at the 300 s default) to watch them, or does not watch them at all.

Not a goal

  • Building anything: this PR is the RFC only.
  • Editing docs/request-for-change/rfc-host-memory-guard.md (docs(rfc): mark rfc-host-memory-guard accepted #39290 owns its Status line).
  • Any forced action on CPU load, a built-in cloud reader, spend enforcement, or acting on remote resources.

What changed (motivation → approach → change)

  • New docs/request-for-change/rfc-resource-control.md (status draft), which extends rfc-host-memory-guard.md:
    • §3: CPU joins the combined posture as a third input, using the 5-minute load per CPU (enter tight at 1.5, leave below 1.0), capped at tight. It never enters the memory posture, so the fast-layer trigger, the create refusal and the spawn floor cannot act on CPU.
    • §4: re-wake per step of decline while tight or critical (memory 1 GB / 0.5 GB, disk 2 / 1 points), and a per-worker wake (25% of RAM in any posture, +2 GB growth while tight). Both use readings the gateway already takes, make no model call, and charge existing hourly budgets (ITEM_PULLS_PER_HOUR, MAX_WAKES_PER_ITEM_PER_HOUR). A separate PR implements this section.
    • §5: a default-off, conductor-authored probe script for remote resources, with hard rules: add-only, fixed {"level", "reading"} schema, wake on level change only, sandboxed through the existing script-cron runner run_script_sandboxed, 20 s timeout, auto-disable after 5 failures, every registration announced with a digest, credentials only through the owner-approved, digest-pinned vault grant script crons already use. Covers file location, edit path, owner disable, threat model and a cost comparison against waking every patrol and against the monitor_start judge.
    • Non-goals, alternatives considered, rollout with exit criteria, test plan, open questions for the team.
  • docs/request-for-change/README.md: one index row for the new RFC.

Backwards compatibility

Compatible: docs only; no code, config key or persisted format changes.

Removes nothing: the PR adds one document and one index row.

Tests

Proof: not provable -- docs or config only

./scripts/docs-lint.sh passes locally ("All documentation checks passed").

Manual verification

Every code reference was read at dcc312174e (origin/main) and in the live diffs of #39270 and #39289; the RFC labels what is only in an open PR.

Real-machine verification

N/A -- the diff is a Markdown document and an index row; nothing in it runs.

Related Issues

Refs #22681. Extends #39188; builds on #39189, #39270, #39289.

Checklist

  • A Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...); PR Hygiene does not count commits
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 19, 2026 01:20
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 19, 2026
@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 6211951ce14f0f705fe1fee396ad741a88dd3451 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision 6211951ce14f0f705fe1fee396ad741a88dd3451 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Does not block merge.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of 6211951ce14f0f705fe1fee396ad741a88dd3451 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: this is a docs-only draft RFC, it removes nothing, and the design questions it raises are left for maintainers to accept.

[DESIGN-REVIEWED] 6211951

Description read

[DESCRIPTION-READ] 5234afff80afec0de9adca8ab7519dba84651306aa64ddd7608af628748ac3d7

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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 19, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of 6211951ce14f0f705fe1fee396ad741a88dd3451 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6211951

False positive or not applicable? A repository writer can comment:
/ai-review override gpt 6211951ce14f0f705fe1fee396ad741a88dd3451 false-positive: <reason, 20 to 500 characters>

@github-actions

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — 🔴 changes requested (blocking)

Reviewed 3f71bc6d68d6ede94d315094ec6a3901992dccd3 — this comment is updated in place on each push.

The RFC's §5.3 says <config_dir>/resource-probes/ is "the same tree that script crons use (<config_dir>/crons/)" and that the sandbox's path rules therefore "apply unchanged". It is a different directory, so the existing path rules do not cover it, and the security claims in §5.2 and §5.6 rest on that wrong premise.

BLOCKING — docs/request-for-change/rfc-resource-control.md:371

"This is the same tree that script crons use (<config_dir>/crons/), so the sandbox's path rules for agent-written scripts apply unchanged."

Trigger: An implementer follows §5.3 and puts a probe at <config_dir>/resource-probes/<board>.py. Rule 4 tells them to reuse run_script_sandboxed, and rule 8 tells them to reuse the cron secret-grant path. resolve_script_path (cron_script_paths.py) only accepts files under (config_dir() / "crons").resolve(). The grant body reader is also pinned to crons/ alone. On a granted run, run_script_sandboxed (cron_script.py:391-398) hides only config_dir() / "crons" and the script's own parent directory.

Outcome: The resolver refuses the probe script. A probe that needs a cloud credential can never receive the grant rule 8 promises. If the resolver is widened to make it run, a granted probe can still read and write the other boards' probe scripts, because the hide list was never extended to that tree. That is the mutable-sibling route the hide list exists to close.

Anchor: defect

Fix: Put probes under <config_dir>/crons/resource-probes/. Or state in §5.3 and in the test plan that the resolver's accepted roots, _read_script_body's pin and the granted-run hide list must each be extended to resource-probes/.

[BLOCK-MERGE] 3f71bc6
[OPUS-REVIEWED] 3f71bc6

Verdict parsed from the review's SHA-scoped output markers for commit 3f71bc6d68d6ede94d315094ec6a3901992dccd3.

False positive or not applicable? A repository writer can comment:
/ai-review override fable 3f71bc6d68d6ede94d315094ec6a3901992dccd3 false-positive: <reason, 20 to 500 characters>

…tight, add-only remote probe

Extends rfc-host-memory-guard without editing it. Proposes CPU load as a
posture input capped at tight, a re-wake per step of decline while tight or
critical and a per-worker growth wake inside the existing hourly wake budget,
and a default-off, add-only, sandboxed probe script the conductor writes to be
woken about remote or cloud resources.
@iamwhatever
iamwhatever force-pushed the docs/rfc-resource-control branch from 3f71bc6 to 6211951 Compare November 19, 2026 01:32
@iamwhatever

Copy link
Copy Markdown
Contributor Author

Opus 5.5 BLOCKING finding on 3f71bc6 (rfc-resource-control.md §5.3, probe path outside the script-cron tree): fixed in 6211951.

  • §5.3: probes now live at <config_dir>/crons/resource-probes/<board>.py, inside the script-cron tree, so the existing checks cover them with no new root: resolve_script_path (cron_script_paths.py) accepts only files under <config_dir>/crons/, _read_script_body (cron_script_grants.py) must resolve inside it, and a granted run_script_sandboxed run hides the whole <config_dir>/crons tree, so a granted probe cannot read or rewrite another board's probe. The RFC says the implementation must not widen any of the three.
  • Backward compatibility: the new tree is named as the crons/resource-probes/ sub-directory.
  • Test plan: new test 21 (path outside crons/ refused; a granted probe cannot touch another board's file). Rollout step 4 exit criteria now cite tests 14-22.

This branch has not been deployed

No deployments
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

readiness: checking Automated validation is still running

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant