Repository navigation
docs(session): name the ownership gate as the sweep authority - #18217
Conversation
The Orphan Sweep Active Set section described the live-pid shield as what protects a pid. The periodic PID sweep and the orphan MCP sweep now ask authorize_runtime_kill per pid at the decision point and signal only under a committed teardown barrier, so the shield is a pre-filter. State that, name the lease and tenancy tables the gate refuses on, say that a refusal withholds one pid without aborting the pass, and link the reconciler's contract in runtime-ownership.md. Correct Reclaim identity, which called the argv identity test the whole authority for both sweeps: it is the whole authority only for the dead-gateway root reclaims, which do not ask the gate. Closes #14726
UX Review (Opus 5.5) — ⏭️ skippedRevision |
First Principles Review (Opus 5.5) — ⏭️ skippedRevision |
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: |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing to check. [DESIGN-REVIEWED] f928604 Description read[DESCRIPTION-READ] adfa7d61ba1659dd26249cb0792a8708731858889da7782e179ecc7416a2b67a 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 |
Problem / Motivation
Goal:
session.mdtells the next person who touches a PID sweep what actually authorizes a signal, so they don't add a kill path that trusts the live-pid shield alone.The "Orphan Sweep Active Set" section still describes the live-pid shield (the active set gathered before the scan) as the thing that protects a pid. Since #14510, the periodic PID sweep and the orphan MCP sweep ask the ownership gate (
authorize_runtime_kill) per pid at the decision point and signal only under a committed tenancy teardown barrier. The section mentions neither the gate, the tenancy table, nor the barrier. "Reclaim identity" goes further and calls the argv identity test (_is_managed_agent_process) the whole authority for both sweeps.Why it matters
A stale contract is worse than a missing one. Someone who reads this section will think the shield is the authority, and a new kill path built on that reading reintroduces the defect #14510 fixed. The kill-chokepoint ratchet counts calls to the kill primitives. It cannot catch a new caller that consults the wrong authority.
Not a goal
cleanup_orphaned_session_roots,cleanup_orphaned_sessions). They do not call the gate today. This PR documents that as it is and changes no code.runtime-ownership.mdon main already coversruntime_reconcile: both directions, the kill-arm conjunction, the per-pass kill budget, theunowned_alive/owned_deadcounters, and both ownership tables.session.mdalready defers to it.What changed (motivation → approach → change)
session.md's sweep text still treats the shield as the authority.origin/mainbyruntime-ownership.md, in## Reconciliation: the kernel against the registryand## The one kill gate.docs/system-specs/modules/session.md):SessionCleanup._kill_authorizedasksauthorize_runtime_killper pid after the phase-2 re-check. The gate refuses while either the lease table (RuntimeOwnership) or the tenancy table (RuntimeTenancy) claims the pid. A gate that raises counts as a refusal. A refusal drops that one pid and the pass continues.teardown_barrierscommits a barrier per pid before the kill phase and releases it in afinally. Only pids the barrier grants are signalled. The paragraph links the gate and reconciler sections ofruntime-ownership.md.origin/main@ c990f85:session_cleanup.py(_kill_authorized,_sweep_periodic_pids,_sweep_untracked_mcps),process_identity.teardown_barriers,runtime_ownership.RuntimeOwnership/RuntimeTenancy/authorize_runtime_kill. I also confirmed thatsession_pid.pycallsauthorize_runtime_killonly from_sync_kill_provider.Backwards compatibility
Compatible: documentation only. No code, config or behaviour changes.
Removes nothing: the edit adds paragraphs and corrects one sentence. No section, anchor or documented capability is removed.
Tests
N/A. Docs-only change, no code under test.
bash scripts/docs-lint.shpasses ("All documentation checks passed"), and none of its identifier warnings names a symbol this diff adds.Manual verification
I read each cited symbol in source at the base SHA (listed above). No runtime behaviour to exercise.
Related Issues
Closes #14726
Pattern harvest
Not generalizable: a one-off case of a spec section that a behaviour change did not update. The review lanes already flag stale owning specs, which is how this issue was filed.
Decision for the owner
The decision is whether this doc-only fix to
session.mdcloses #14726, given that criteria 2 and 3 are already met byruntime-ownership.mdon main. This draft says yes, and it states as fact that the dead-gateway root reclaims do not ask the ownership gate, without changing that code, because whether they should is a separate design call.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.