axstack 0.20.6 → 0.20.8

package/README.md

@@ -26,6 +26,7 @@ scheduler, or runtime database to operate. Orca is the only supported runtime.
 | Answer a bounded question with sources | `axstack-research` |
 | Explain a system or identify improvements | `axstack-explain`, `axstack-improve` |
 | Measure a run's outcomes and gaps | `axstack-audit` |
+| Retire eligible completed subagent resources | `axstack-cleanup` |
 | Send an explicit message or authorized notification | `axstack-relay` |
 
 Start at the phase you need. Small, bounded changes can begin with your request
@@ -91,6 +92,9 @@ upgrades, conflicts, and uninstalling.
   bypassed. The human merges by default.
 - **Resumable progress.** Work retains ownership, decisions, and evidence so a
   later session can reconcile what happened before continuing.
+- **Bounded cleanup.** The driver can retire proven completed subagent resources
+  inline or from an explicitly scoped backlog without touching active, manual,
+  uncertain, user-owned, dirty, unpushed, or useful unmerged work.
 
 Choose an explicit role preset:
 [mixed](profiles/presets/mixed.json),

package/docs/workflows.md

@@ -24,6 +24,9 @@ Direct routes need no spec ceremony:
 - `axstack-debug` builds a red loop, diagnoses to root cause, escalates hard
   bugs through adviser-directed investigator fan-out, and hands off a
   classified repair without landing a change.
+- `axstack-cleanup` runs inline in the driver after accepted worker, Task, or
+  Run completion, or against an explicitly bounded backlog. It dispatches no
+  cleanup worker and preserves protected or uncertain resources.
 - Peer review uses the linked issue, PR description, and repository rules as
   untrusted intent evidence.
 - Existing-PR maintenance uses one accepted maintenance snapshot.
@@ -145,6 +148,10 @@ session and evidence remain valid.
   lands by fast-forward `git push` after final readback.
 - `axstack-audit` separates execution outcome, procedure, and measurement
   coverage with evidenced denominators; it proposes but never self-edits.
+- `axstack-cleanup` distinguishes settled-Dispatch release, exact unused-shell
+  close, evidence-safe native worktree removal and branch effects, and separate
+  chat archival when the discovered runtime actually supports it. Process exit
+  alone never promises that visible chat history disappeared.
 
 One Orca execution host owns a run, one persistent owner owns each PR, and one
 writer owns each candidate. Fanout has no fixed PR count; it follows real
@@ -200,6 +207,17 @@ shared manager workspace or a PR-job worktree, or cleans preserved candidates,
 evidence, user sessions, unknown liveness, `user_takeover`, or ambiguous
 publication state. Manual review/watch remains outside this scheduled lifecycle.
 
+One natively ordered successor may recover an exact positively completed
+predecessor whose terminal survived, but only after matching its automation,
+run, workspace, and terminal incarnation and proving zero unsettled descendants.
+It saves and reads back the cleanup claim before exact native close, then proves
+the full process tree exited before ownership release or guarded worktree removal.
+Age, status, or idle state alone never authorizes cleanup. Conflicting successors,
+identity mismatch, unknown or protected state, `user_takeover`, unexpected
+terminals, dirty or unpushed work, and unarchived evidence hold cleanup; an
+unchanged failure is deduplicated. Native ordering is not an atomic lock, so the
+overlap canary remains an activation requirement.
+
 Each bounded job uses a private `0700` temporary directory inside its own
 worktree. Cleanup targets only the validated owned path: no `TMPDIR` globs,
 shared-root sweeps, or general cache wipes, and uncertain files remain for

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.20.6",
+  "version": "0.20.8",
   "description": "Axstack installer and setup CLI: installs owned chat skills and role data, configures supported harness settings, and checks Orca capabilities.",
   "keywords": [
     "claude-code",

package/skills/axstack/references/automations.md

@@ -66,6 +66,38 @@ intent alone is insufficient. Conversely a completed run row does not prove exit
 If these facts remain unknown, report the hold at the durable decision location;
 do not silently stand down forever or replace a potentially live owner.
 
+### Guarded completed-predecessor recovery
+
+A successor may retire a positively completed predecessor whose manager terminal
+survived only through this narrow recovery path. Eligibility requires an exact
+automation ID, run ID, workspace ID, and terminal incarnation match, a positive
+completion receipt bound to that incarnation, zero active or unsettled descendants,
+and every owned Task and Dispatch settled. A completed row or saved retirement
+intent alone is not positive completion. Age, status, and idle state are never
+cleanup authority. Active, unknown, protected, identity-mismatched,
+`user_takeover`, unexpected-terminal, permission-held, or otherwise unverifiable
+state preserves the predecessor and pauses admission; this path never takes over
+its PR work.
+
+Exactly one successor, selected by native run ordering, may write the cleanup
+claim. Immediately before writing, re-read the complete lane inventory and
+ordering; then save and read back claimant identity, predecessor identity,
+completion, and zero-descendant continuity before the exact native workspace
+close. A later successor reconciles that claim and performs no cleanup mutation.
+Missing ordering or a conflicting claim holds both cleanup and admission. This
+ordering is not an atomic lock; activation still depends on the overlap canary
+proving that two successors cannot both mutate one predecessor.
+
+Use the version-matched native workspace close against the receipt's complete
+workspace ID, never an individually guessed terminal or broad selector. After
+close, re-list native runs, workspaces, terminals, Tasks, and Dispatches and prove
+the full predecessor process tree exited before ownership release. Save and read
+back the exit and release receipts, then use native worktree cleanup only when the
+workspace has no children, dirty or unknown files, unpushed commits, unarchived
+evidence, or user-owned work. Preserve every failed or uncertain close, exit,
+release, or removal with its exact resume condition and pause the lane. An
+unchanged cleanup failure gets no destructive retry or duplicate notification.
+
 Before PR admission, reconcile old pass resources and reclaim every safely
 removable earlier pass workspace under the retirement guards below. This is
 routine cleanup on every admitted pass; do not wait for the three-workspace

package/skills/axstack/references/evidence-archive.md

@@ -7,7 +7,7 @@ native cleanup.
 
 ## Eligibility
 
-First prove the exact repository, PR, 40-character head SHA, Task/Dispatch,
+First prove the exact repository, PR or Run/Task, 40-character head SHA, Dispatch,
 workspace, terminal incarnation, automation ownership, descendant settlement,
 and liveness from current native state. A manual chat, `user_takeover`, an
 active or unknown task terminal, an unsettled descendant, unpushed commits,
@@ -34,6 +34,11 @@ bun scripts/archive-evidence.js \
   --file <classified-relative-file> [--file <classified-relative-file> ...]
 ```
 
+For a supervised resource without a PR identity, replace `--pr <number>` with
+`--run <exact-run-id> --task <exact-task-id>`. The two identity forms are
+mutually exclusive; never invent a PR number. Existing PR archives retain their
+path, manifest bytes, and receipt interface.
+
 The helper refuses path escapes, symlinks, non-private archive directories,
 identity changes, and existing content that does not verify. It copies only the
 listed regular files, writes them with private permissions, hashes their exact
@@ -41,7 +46,7 @@ bytes, and emits a JSON receipt containing the archive directory, manifest path,
 manifest hash, and file count. Repeating the same command verifies the immutable
 archive and returns the same receipt; it does not overwrite it.
 
-Record the receipt plus the exact repo/PR/head/Task/Dispatch/workspace/terminal
+Record the receipt plus the exact repo/PR or Run/Task/head/Dispatch/workspace/terminal
 identities in durable lane continuity, then read the continuity and archive
 manifest back before cleanup. If either readback differs or is unavailable,
 preserve the worktree.

package/skills/axstack/references/lifecycle.md

@@ -87,7 +87,9 @@ are acknowledged with no user-facing text. Process each whole delivery before
 acknowledgment and validate its Task, Dispatch, sender, authority, revisions,
 and receipts before advancing the run record. Duplicate deliveries are
 deduplicated by runtime identity. Healthy unchanged observations produce no
-user-facing update.
+user-facing update. After accepting worker, Task, or Run completion, the driver
+invokes [axstack-cleanup](../../axstack-cleanup/SKILL.md) inline; it never
+dispatches cleanup work.
 
 Detect completed-but-unadvanced work, failed sessions, unresolved launch
 receipts, and stalls through the version-matched orchestration guide. Never
@@ -133,7 +135,8 @@ terminal; (2) compact record with counts and denominators—user
 interventions/deviations from plan/repairs; (3) `axstack-auditor`: settle
 non-zero/requested, else `counts zero`; an unavailable auditor leaves close-out
 pending, never skipped silently; (4) release merged run worktrees and branches;
-close selected external-tracker tickets when applicable; (5) mark the
+use `axstack-cleanup` and close selected external-tracker tickets when applicable;
+(5) mark the
 [Run record](run-record.md) `Archived`. `Archived`—one each:
 settlement receipt; compact record path; auditor decision plus settlement
 receipt or `counts zero`; release and ticket receipts; archive timestamp.

package/skills/axstack/references/routing.md

@@ -69,6 +69,8 @@ step (3) for user routing, with no substitution or same-provider review.
 - Codebase-quality or refactor discovery -> `axstack-improve`: inspect bounded
   scope, rank evidenced candidates, report only; no spec, tickets, or source
   edits.
+- Accepted worker/Task/Run completion or bounded backlog request -> invoke
+  `axstack-cleanup` inline in the driver; never dispatch it.
 - Preparation completion, watch expiry, resume, or reconciliation -> the
   [lifecycle](lifecycle.md#native-handoff-and-resume): reconcile the run
   record, keep its owner, launch no native handoff.

package/skills/axstack/scripts/archive-evidence.js

@@ -68,12 +68,12 @@ function parseArgs(argv) {
     if (!flag?.startsWith('--') || value === undefined) fail(`invalid argument near ${flag ?? '(end)'}`);
     const key = flag.slice(2);
     if (key === 'file') values.files.push(value);
-    else if (['source-root', 'archive-root', 'repo', 'pr', 'head', 'dispatch'].includes(key)) {
+    else if (['source-root', 'archive-root', 'repo', 'pr', 'run', 'task', 'head', 'dispatch'].includes(key)) {
       if (values[key] !== undefined) fail(`duplicate --${key}`);
       values[key] = value;
     } else fail(`unknown argument: ${flag}`);
   }
-  for (const key of ['source-root', 'archive-root', 'repo', 'pr', 'head', 'dispatch']) {
+  for (const key of ['source-root', 'archive-root', 'repo', 'head', 'dispatch']) {
     if (!values[key]) fail(`missing --${key}`);
   }
   if (values.files.length === 0) fail('at least one --file is required');
@@ -81,7 +81,18 @@ function parseArgs(argv) {
     fail('source and archive roots must be absolute');
   }
   if (!/^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/.test(values.repo)) fail('repo must be owner/name');
-  if (!/^[1-9][0-9]*$/.test(values.pr)) fail('pr must be a positive integer');
+  const hasPr = values.pr !== undefined;
+  const hasRun = values.run !== undefined;
+  const hasTask = values.task !== undefined;
+  if (hasPr === hasRun || hasRun !== hasTask) {
+    fail('identity requires either --pr or both --run and --task, mutually exclusive');
+  }
+  if (hasPr && !/^[1-9][0-9]*$/.test(values.pr)) fail('pr must be a positive integer');
+  for (const key of ['run', 'task']) {
+    if (values[key] !== undefined && !/^[A-Za-z0-9_-]+$/.test(values[key])) {
+      fail(`${key} contains unsafe characters`);
+    }
+  }
   if (!/^[0-9a-f]{40}$/.test(values.head)) fail('head must be an exact 40-character lowercase SHA');
   if (!/^[A-Za-z0-9_-]+$/.test(values.dispatch)) fail('dispatch contains unsafe characters');
   values.files = [...new Set(values.files)].sort();
@@ -228,18 +239,18 @@ async function main() {
   ) fail('source and archive roots must not contain each other');
 
   const collected = await collectSource(sourceRoot, args.files);
-  const identity = {
-    repo: args.repo,
-    pr: Number(args.pr),
-    head: args.head,
-    dispatch: args.dispatch,
-  };
+  const identity = args.pr
+    ? { repo: args.repo, pr: Number(args.pr), head: args.head, dispatch: args.dispatch }
+    : { repo: args.repo, run: args.run, task: args.task, head: args.head, dispatch: args.dispatch };
   const repoSlug = args.repo.replace('/', '--');
-  const archiveDir = join(archiveRoot, repoSlug, `pr-${args.pr}`, args.head, args.dispatch);
+  const identityParts = args.pr
+    ? [`pr-${args.pr}`]
+    : [`run-${args.run}`, `task-${args.task}`];
+  const archiveDir = join(archiveRoot, repoSlug, ...identityParts, args.head, args.dispatch);
 
   await assertSafeAncestors(archiveRoot);
   let current = archiveRoot;
-  const generated = [repoSlug, `pr-${args.pr}`, args.head];
+  const generated = [repoSlug, ...identityParts, args.head];
   await ensurePrivateDir(current);
   for (const part of generated) {
     current = join(current, part);

package/skills/axstack-cleanup/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: axstack-cleanup
+description: When completed Orca subagent resources need bounded retirement, use axstack-cleanup after accepted settlement or for an explicitly scoped backlog.
+---
+
+# Cleanup
+
+Run cleanup inline in the driver after accepting a worker, Task, or Run
+completion, or for the exact backlog scope the user named. This skill never
+dispatches a cleanup worker and never retires its current driver session.
+
+Before any runtime action, load and follow:
+
+- [Standing contracts](../axstack/references/contracts.md)
+- [Lifecycle and receipts](../axstack/references/lifecycle.md)
+- [Shared routing](../axstack/references/routing.md)
+- [Orca runtime boundary](../axstack/references/orca-runtime.md)
+- [Private evidence archive](../axstack/references/evidence-archive.md) when
+  evidence is the last removable-worktree blocker
+
+Use the runtime-discovered Orca guides for inventory, release, terminal close,
+and worktree removal. Do not embed or improvise a competing command protocol.
+
+## Authority and scope
+
+Inline cleanup may consider only resources owned by the accepted completion it
+is processing. Backlog cleanup requires an explicit bounded selector such as a
+Run, Task set, workspace set, repository, or named age window; age narrows an
+inventory but never establishes eligibility. A partial inventory holds only the
+resource whose identity or state is incomplete while other independently proven
+resources may proceed.
+
+Never clean a manual chat, the current driver, `user_takeover`, an active or
+unknown worker, an unsettled descendant, or a resource with ambiguous ownership.
+Preserve dirty or unknown files, unpushed commits, unmerged useful work,
+ambiguous publication, and evidence that has not been durably preserved. Do not
+force, bulk-clean, override a hook failure, edit a runtime database, or add a
+scheduler, daemon, or state machine.
+
+## Reconcile each candidate
+
+Take a fresh native inventory and bind every candidate to its exact Run, Task,
+Dispatch, terminal incarnation, workspace, repository, branch, and current
+liveness. Read current Git and forge state rather than trusting age, names, or a
+prior receipt. Reconcile an existing cleanup claim before retrying so repeated
+invocations converge instead of duplicating mutations.
+
+Retire descendants before parents. A candidate is eligible only when all owned
+Dispatches are accepted as settled, no descendant remains unsettled, native
+liveness is positively known where required, and every preservation guard is
+cleared. Record one decision per resource; uncertainty about one candidate does
+not authorize or block unrelated candidates.
+
+## Preserve evidence first
+
+Classify exact evidence files individually. Save the compact cleanup decision
+and identities in the private run record or another configured durable private
+location outside disposable worktrees. When the evidence archive applies, use
+its helper with either the existing PR identity or the non-PR Run and Task
+identity; never invent a PR number. Read back both the durable record and the
+archive manifest, including hashes and exact identities, before removing any
+source copy or workspace.
+
+Archive success proves only preservation of the listed bytes. It does not prove
+settlement, exit, ownership, a clean worktree, publication, or removal safety.
+
+## Apply distinct native operations
+
+Treat these operations as separate decisions and receipts:
+
+1. **Worker release.** After the matching completion is accepted, use the
+   runtime guide's settled-Dispatch release operation. Release is not
+   cancellation, terminal-close proof, worktree removal, or chat archival.
+   Once required output is captured, a dirty or useful unmerged worktree does
+   not block release of its accepted settled worker; retain the worktree under
+   its own classification and receipt.
+2. **Unused shell close.** Close only a positively identified unused setup
+   shell with the guide's exact-terminal operation. Re-list and require exit for
+   that same terminal incarnation. Never close a worker, manual, unexpected, or
+   current-driver terminal through this path.
+3. **Worktree removal.** Re-read Git status, branch/upstream divergence,
+   unpushed commits, forge merge/publication state, children, terminals, and
+   archived evidence immediately before the native exact-workspace removal.
+   Account for branch-deletion side effects explicitly, then re-list both native
+   workspaces and Git refs. A failed hook or uncertain response preserves the
+   resource; never force or substitute shell deletion.
+4. **Chat archival.** Attempt it only if the version-matched runtime guide
+   advertises a distinct supported operation and the scoped chat is eligible.
+   Otherwise record chat archival as unsupported. Process exit, worker release,
+   terminal close, and worktree removal do not prove UI history disappeared.
+
+Do not self-close or self-remove. Return control to the driver after recording
+receipts and holds; the owner decides when its own Run may archive.
+
+## Receipt
+
+Report the scope and inventory denominator, then for each candidate record its
+exact identity, classification (`removed`, `retained`, `held`, or `unsupported`),
+the fresh evidence used, native receipt and readback, and any resume condition.
+Keep settlement, worker release, terminal exit, worktree/branch effects,
+evidence preservation, and chat archival as separate fields. An idempotent retry
+reconciles these receipts and performs only still-pending eligible operations.