Repository navigation
refactor(acp): bind AcpRuntime spawn, kill and session-start owners - #22085
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Check that Suggestions
[DESIGN-REVIEWED] d5a4aff Description read[DESCRIPTION-READ] e0d08634e4fc4b73218fc003c541b6361ca124f5c3dbb6ffec5c0b0ea39938c3 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 Spawn and session start are availability paths. Before merge, check the move audit's claim that 225 of 229 units moved unchanged and the other 4 are facade glue only. What this change shipsInventory (10 items) — 10 justifiedIntent: get
[FIRST-PRINCIPLES-REVIEWED] d5a4aff Description read[DESCRIPTION-READ] 4b295cb84814db90b3e01e42376d1da074af75292dac81589a953bc5decfd223 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 Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
|
|
9f64956 to
c7a9754
Compare
|
|
c7a9754 to
707aa09
Compare
|
|
707aa09 to
86fbee5
Compare
|
|
|
Holding at This PR moves AcpRuntime's process-tree kill, spawn admission and sandbox cleanup into new owners. It also swaps the facade's forwarding class for Blockers:
A rebased head needs a fresh review. — crew-pr-reviewer (r112) |
AcpRuntime's process-tree teardown, child launch and handshake, spawn entry, and session/new and session/load setup move into six acp/runtime_* owner modules. Each moved member is a module-level function there that takes self, and the class binds it by name, so the instance keeps its state and every patch, __new__ build and unbound call reaches the same function. The facade keeps every binding and its forward table and switches to kiro_crew._facade_mirror, so a patch through kiro_crew.acp.runtime still reaches the moved code. Part of #20192
86fbee5 to
d5a4aff
Compare
|
Problem / Motivation
Goal: Bring
src/kiro_crew/acp/runtime.pytoward the 2,000-line cap with no behaviour change: the first of two PRs, movingAcpRuntime's spawn, process-tree teardown and session-start behaviour into owner modules the class binds by name.acp/runtime.pyis 9,176 lines, and one class (AcpRuntime, 7,909 lines) is most of it. It is one of the files the line-cap guard lists as over the cap (.github/file-line-cap-baseline.txt). It also changes often (20 commits in the last week), so every feature PR that touches the multiplexed runtime edits a file far past the size where a reviewer can hold it.Why it matters
The 2,000-line cap is the repository's rule (AGENTS.md,
scripts/check_file_line_cap.py). Left alone,runtime.pykeeps growing, every runtime fix lands in a 9,000-line diff context, and the session-start and spawn code, where most of the recent fixes landed, stays mixed with the reader loop, the wire and the death attribution.Not a goal
runtime.pystays over the cap after this one, so its line-cap row stays as main has it.AcpRuntime's public or private surface, its constructor, its properties or its class constants.What changed (motivation → approach → change)
runtime.pyis over the cap because one class holds everything, and a class cannot be split by moving definitions. The approach is the oneacp/client.pyandacp/session_handle.pyalready use (binding, KC28 L33): each moved member's body becomes a module-level function in an owner module, withselfas its first parameter, and the class binds it by name (spawn = _rt_entry.spawn). The instance keeps all of the runtime's state, so a patch of a method on the class or an instance, anAcpRuntime.__new__build and an unboundAcpRuntime.m(stub, ...)call all still reach the one function._own_methodsrestores each bound function's__qualname__and drops its type-checker-onlyselfannotation, so task reprs andinspect.signatureread as before. It matches the explicit_MEMBER_OWNERSset rather than a module-name prefix, becauseruntime_models,runtime_process_treeandruntime_startshare theruntime_prefix and are not owners (the dashboard's exportedown_methodsmatches only its own package).This PR moves the six owners that hold the file's most-edited code: the process tree and kill, the child launch and its handshake, the spawn entry, and the three session-start owners (what a session is built from,
session/new,session/load). The module-level helpers only they read move with them. The facade switches from its own forwarding class tokiro_crew._facade_mirror, keeping its forward table unchanged, so a patch throughkiro_crew.acp.runtimestill reaches every module that holds the moved code.acp/runtime_tree_kill.pykillacp/runtime_spawn_launch.pyinitializehandshake, failed-start guardacp/runtime_spawn_entry.pyspawnunder cold-start admission, the re-derive retry, the reviveacp/runtime_session_setup.pysession/newandsession/loadare built from and checked againstacp/runtime_session_create.pysession/newend to endacp/runtime_session_load.pysession/loadend to endTests that read
runtime.py's text now read it joined with these owners (or the one owner that holds the pinned code), with every assertion unchanged; the owning spec (acp-client.md) gains the runtime owner table, and the docs that named where the moved code is defined now name its owner.Backwards compatibility
Compatible: every name
kiro_crew.acp.runtimebound before stays bound to the same object (test_every_base_import_stays_bound_on_the_facadeandtest/campaign_facade_inventories/kiro_crew.acp.runtime.jsonpin it), everyAcpRuntimemember keeps its name, kind, coroutine-ness and signature (the member inventory pins it), and a write through the facade reaches every owner that reads the name.Reader: src/kiro_crew/acp/runtime_spawn_launch.py:_spawn_admitted -- chat -- the
extra_hidden_dirs=plan.extra_hidden_dirslaunch argument moved verbatim with_spawn_admitted; the runtime spawn hands the sandbox the same credential mask (test_acp_harness_contract.py::test_the_spawn_mask_reaches_the_sandbox)Reader: src/kiro_crew/acp/runtime.py:AcpRuntime -- subagent -- the class is the same object with the same members; session.py, session_provider.py, providers/acp_runtime_start.py and review_pool.py import it from the facade unchanged (test_runtime_bindings.py::test_every_inventory_member_is_still_on_the_class)
Tests
test/test_runtime_bindings.py(new) pins the binding contract: the 156-member inventory (every member stays, with its kind, coroutine-ness, signature digest and owner; a member added later needs no row), each bound member is its owner's function with the BASE__qualname__,typing.get_type_hintsresolves for the class ({}, as on main) and for every member, the fields a moved member assigns first are declared for type checkers only (a mutation that turns them into runtime annotations goes red), no owner keeps an unboundselffunction or needs its class body (zero-argumentsuper(),__class__, name mangling, with a planted self-test), no owner imports the facade at run time and owners import only owners listed before them, each owner's docstring names the fields it writes and reads, owners log underkiro_crew.acp.runtime, moved exceptions keep the facade as their__module__, every name the test trees patch through the facade reaches every owner reading it (with a self-test that the scan can fail), the mirror forwards exactly the old forward table, and every import the facade binds is accounted for: a BASE name, the glue's, a name an owner defines, or one the facade's or an owner's code reads (thesetup.cfgF401 row's stand-in; a planted self-test shows an unread import and an owner import of a name that owner does not define are reported, and a read one is not).test/test_runtime_bindings.py(257 tests) passed 5 runs at-n0and one at-n 3; it sleeps on nothing and orders nothing it did not define.Manual verification
N/A — a pure move: the existing runtime suite drives every moved body, and the binding guards pin the contract.
Move audit
src/kiro_crew/acp/runtime.py: 9176 -> 5195 lines; moved 54.68% (python-ast)(move_audit.py, raw: it counts every moved member as changed because its first parameter gains the type-checkerself: AcpRuntimeannotation and black re-indents its docstring).inspect.cleandoc, theselfannotation and a dropped@staticmethodundone): 229 units, 225 moved unchanged, 4 changed, all facade glue:_ReExportModule(replaced by_facade_mirror), theif not TYPE_CHECKING:__getattr__(declines the names the mirror serves),_EXPORTS(bound empty, filled from the mirror), the class swap._INITIALIZE_TIMEOUTcomment says "the plain request budget (_REQUEST_TIMEOUT)" instead of "the plain budget above" (that constant stays inruntime.py); one# type: ignore[union-attr](_mirrored_session_mcp) and one# type: ignore[misc](the_adoptclosure in_collect_late_start), each with a two-line reason: an owner is type-checked before the class that binds it, so mypy checks those closures on their own and loses themirror is None/late_adopter is not Nonenarrowing their enclosing function establishes.@_own_methods, anif TYPE_CHECKING:block declaring the three fields a moved member assigns first (_native_skill_projection,_skill_projection_generation,_spawn_skill_projection; mypy sees them, and the class carries no annotations at run time, sotyping.get_type_hints(AcpRuntime)is{}as on main), and the binding block.Upstream code this PR carries
create_session,_collect_late_start,_finish_create_session,load_session: therequest_sent_atstamp and its hand-on) and addedAcpRuntime._start_mount_check. The split takes every body from the base it runs on, so those edits sit in their owners as main has them;_start_mount_checkis bound fromacp/runtime_session_setup.py, beside_guard_unresolved_mcp_refs, the other check both session starts run on what they were built from.session_handle_class.pyin the facade docstring; those lines are kept.Diff layout (L36)
Every changed file adds the same lines under git's default diff and
--minimal(runtime.py: +160/-4141 both). Total diff 635,597 bytes.CI path references
None: no workflow path filter or explicit file list names
runtime.pyoracp/**.Logger names
Owners log under
logging.getLogger("kiro_crew.acp.runtime"), the literal name (39caplogsites and 5record.name ==filters read it, andruntime_start.pyalready does the same); the facade keepslogging.getLogger(__name__), the same logger object.Known limits
_own_methodsrestores the bound function's own__qualname__(AcpRuntime._collect_late_start), not its closures', so the closure in_collect_late_startis_collect_late_start.<locals>._adoptwhere BASE hadAcpRuntime._collect_late_start.<locals>._adopt.__code__.co_qualnameis its owner-level name (create_session, BASEAcpRuntime.create_session), and a log record it emits carries the owner inmodule,filenameandpathname(runtime_session_create);record.namestayskiro_crew.acp.runtime.%(name)sonly, and no test, filter or repr keys on a closure qualname orco_qualnameof these functions (the binding guard pinsco_qualnameto the owner-level name on purpose).Edits outside the claim (granted)
setup.cfg: one per-filesrc/kiro_crew/acp/runtime.py: F401row with its reason (the facade keeps every import it bound;test_runtime_bindings.py's import check, with a planted self-test, stands in for it: each import is a BASE name, glue, owner-defined, or read by the family's code).test/test_worker_agent_spawn_gate.py:_gate_callsalso reads a module-level function when called withclass_name=None, and is called on the owner of_resolve_spawn_plan; assertion and message unchanged. Mutations: removing the gate call fromruntime_spawn_launch.pyturns it red, and a gate planted inKiroHarness.resolve_spawnstill turns it red through the class path.test/test_facade_mirror_guards.py:_OWN_CREATE_GUARDSgainskiro_crew.acp.runtime→test/test_acp_refactor_create_guard.py, the guard that already covers this facade's forwards.Source pins re-pointed (L30 / L40(8)); every assertion unchanged
Text joins of
runtime.pywith_RUNTIME_OWNERS(or the one owner holding the pinned code): test_acp_liveness_remote_flat.py, test_acp_mcp_ref_guard.py (3), test_acp_runtime_load_session.py, test_acp_sandbox_init_classification.py (2; one window's end marker re-pointed to the unit that follows the failed-start helpers in their owner), test_browser_cli_launch.py, test_tool_call_classification_kas.py, test_worker_agent_load_bracket.py (3), test_windows_cleanup_capacity.py, test_acp_client_capabilities.py (3), test_per_runtime_process_resources.py (3), test_reconcile_sandbox_tool_exclusion.py, test_mcp_remote_header_secret_refs.py. Rows and paths: test_secc_poc_scratch_owner_symlink.pySPAWNERS, test_worker_agent_spawn_gate.py (seam caller), test_harness_parity.py (_RUNTIME_PATH_MODULES+ 3 identity rows), test_deny_bounded_write.py (SITES+ 6 empty owner rows), test_agent_admission_paths_ratchet.py (keys), test_kill_chokepoint_ratchet.py (kill). Comment: test_acp_refactor_facade.py:1801-1811 (the shared-binding readers now live in owners). Each re-pointed pin has a mutation that breaks the construct in its new home and turns the pin red (31 distinct mutations, all red).Citations edited (L29, SD27)
src/kiro_crew/acp/client_start.py: three commentsacp/runtime.py→acp/runtime_spawn_launch.py(the twin guard, the liveness anchor, the owner-marker join).src/kiro_crew/constants.py: theINITIALIZE_TIMEOUT_SECScomment namesacp.runtime_spawn_launch, where_INITIALIZE_TIMEOUTand its reasoning now live.acp-client.md(runtime owner block),harness-parity.mdH6,code-style.mdanderror-handling.md(where the binding and session-start errors live),agent-spec-fields.md(2 rows),rfc-leaked-runtime-reclaim.md,rfc-overload-resilience.md(E11create_session),rfc-resumable-subagent-sessions.md(5 stale line cites → symbols; their 4line-refrows deleted from.github/docs-lint-baseline.txtby hand).session_pid_tracking.py_replace_child_pidsnameskiro_crew.acp.runtime.AcpRuntime._snapshot_descendants, a class-attribute path the binding keeps;_untrack_root_by_identitynamesacp/runtime.pyas the caller that logs a full retirement,_retire_tracking_after_exit, which stays inruntime.pyin this PR.Gates run locally
kiro_crew.acp.runtime/AcpRuntime, the tree-scan fences, the mirror and facade guards, and the mount-check tests),-n 3: 18,048 passed, 48 skipped, 0 failed.scripts/local-gate.py --dry-runselects 1,298 backend and 535 frontend files (the bare stemruntime), so it was not run whole._start_mount_checkjoined session_setup; the mount-check tests drive it): tree_kill 95.1%, spawn_launch 91.7%, spawn_entry 97.3%, session_setup 85.9%, session_create 95.1%, session_load 88.1%; runtime.py 94.4%.mypy src/kiro_crew(fresh cache): no issues in 3,211 files. black / isort / flake8 on every changed file, comment-history, brand, harness parity, line cap (0 failures), subprocess-encoding, black gate, woke, take-away (2 Reader lines), PR template check, docs_lint, flake-pattern ratchet, campaign inventory check: all pass. semgrep 1.78 with the CI configs and--baseline-commit: 0 findings, no parse error.git archiveof this commit imports the facade and all six owners under an isolated home.Related Issues
Part of #20192
Follow-up: #22257 (the shared _own_methods helper)
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.