Skip to content

docs(session): name the ownership gate as the sweep authority - #18217

Merged
buluoray merged 1 commit into
mainfrom
fix/session-sweep-authority-doc-14726
Oct 9, 2026
Merged

buluoray merged 1 commit into
mainfrom
fix/session-sweep-authority-doc-14726

Conversation

@buluoray

@buluoray buluoray commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: session.md tells 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

  • Gating the dead-gateway root reclaims (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.
  • A new reconciler spec. runtime-ownership.md on main already covers runtime_reconcile: both directions, the kill-arm conjunction, the per-pass kill budget, the unowned_alive / owned_dead counters, and both ownership tables. session.md already defers to it.

What changed (motivation → approach → change)

  • Symptom: the issue's clearing criterion 1. session.md's sweep text still treats the shield as the authority.
  • Root cause: the child-PID section ("Detection") already names the gate and the barrier, but the "Orphan Sweep Active Set" and "Reclaim identity" sections were never brought in line. Criteria 2 and 3 are already met on origin/main by runtime-ownership.md, in ## Reconciliation: the kernel against the registry and ## The one kill gate.
  • Change (docs only, docs/system-specs/modules/session.md):
    • "Orphan Sweep Active Set" gets a new paragraph. The active set is a pre-filter. SessionCleanup._kill_authorized asks authorize_runtime_kill per 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_barriers commits a barrier per pid before the kill phase and releases it in a finally. Only pids the barrier grants are signalled. The paragraph links the gate and reconciler sections of runtime-ownership.md.
    • "Reclaim identity" now says the argv identity test is the whole authority only for the dead-gateway root reclaims. On the periodic sweep it is a precondition.
  • I checked every claim against 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 that session_pid.py calls authorize_runtime_kill only 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.sh passes ("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.md closes #14726, given that criteria 2 and 3 are already met by runtime-ownership.md on 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • 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; see the Licensing section of CONTRIBUTING.md.

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
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Oct 8, 2026
@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision f928604ff68cb88f57c15cc2b41d821991ee6cb7 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ⏭️ skipped

Revision f928604ff68cb88f57c15cc2b41d821991ee6cb7 ships no reviewable capability (docs, tests or generated files only), so there is nothing to inventory. Advisory — does not block merge.

@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] f928604

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable f928604ff68cb88f57c15cc2b41d821991ee6cb7: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] f928604

False positive or not applicable? A repository writer can comment:
/ai-review override gpt f928604ff68cb88f57c15cc2b41d821991ee6cb7: <one-sentence reason>

@github-actions

github-actions Bot commented Oct 8, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of f928604ff68cb88f57c15cc2b41d821991ee6cb7 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

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 .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.

@buluoray
buluoray marked this pull request as ready for review October 8, 2026 23:51
@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners October 8, 2026 23:51
@buluoray
buluoray requested a review from CrysisDeu October 8, 2026 23:51
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Oct 8, 2026

@CrysisDeu CrysisDeu left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Approving at f928604. Read the full diff plus the owning spec; no findings.

@buluoray
buluoray enabled auto-merge (squash) October 9, 2026 05:27
@buluoray
buluoray merged commit 58830fa into main Oct 9, 2026
148 of 150 checks passed
@buluoray
buluoray deleted the fix/session-sweep-authority-doc-14726 branch October 9, 2026 05:28
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

session.md's sweep contract is stale and the runtime reconciler has no owning spec

2 participants