axstack 0.20.7 → 0.20.9

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.20.7",
+  "version": "0.20.9",
   "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/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.
@@ -54,12 +59,44 @@ state and require exit proof for that exact terminal incarnation. A task
 terminal, manual chat, unexpected terminal, failed close, or uncertain exit
 remains protected.
 
-After receipt and continuity readback, if the only remaining Git dirt is the
-verified archived untracked evidence, compare its current bytes with the
-manifest again and unlink only those exact regular evidence files individually.
-Never remove tracked or unknown files, directories, or any path whose hash now
-differs. Re-read Git and native state; any remaining or uncertain dirt holds
-retirement.
+After receipt and continuity readback, invoke the same installed helper with
+the same identity and complete `--file` set, plus the recorded manifest hash:
+
+```sh
+bun scripts/archive-evidence.js \
+  --source-root <absolute-worktree-or-evidence-root> \
+  --archive-root <absolute-private-archive-root> \
+  --repo <owner/repository> --pr <number> --head <40-character-sha> \
+  --dispatch <exact-dispatch-id> \
+  --file <classified-relative-file> [--file <classified-relative-file> ...] \
+  --operation retire --manifest-hash <recorded-64-character-sha256>
+```
+
+Use the corresponding `--run` and `--task` identity for a non-PR archive. The
+retirement operation independently verifies the immutable private archive, its
+exact identity and complete file set, the caller-recorded manifest hash, the
+exact Git top-level and HEAD, and every remaining source file. It refuses
+tracked, staged, or unclassified dirt; changed bytes; unsafe or overlapping
+roots; symlinks; hard links; and non-regular files. It applies exact unlinks only
+to matching listed files and never removes directories.
+
+Record the retirement receipt's `removed`, `alreadyAbsent`, and `pending` file
+sets. A repeat invocation reconciles already absent files without changing the
+manifest. A partial or failed invocation preserves the archive; resolve its
+exact hold and retry the same operation until `pending` is empty. Never replace
+this operation with a shell loop, broad deletion, force, or a waiver.
+
+Re-read Git and native state after successful retirement. Any remaining or
+uncertain dirt holds worktree removal. Settlement, liveness/no-writer proof,
+useful-work and publication checks, evidence classification, and removal
+authority remain driver decisions; archive or retirement success proves none of
+them.
+
+Before native worktree removal, verify the effective **Archive Script**
+provenance. An unknown hook or a required hook whose provenance is not trusted
+holds removal. Record its native outcome as exactly `unconfigured`, `passed`,
+`failed`, or `unknown`; only `unconfigured` or a trusted `passed` outcome may
+advance, while `failed` and `unknown` preserve the resource.
 
 Only then use the version-matched Orca guide's native worktree cleanup operation
 with the exact workspace identity. Never use shell recursive deletion and never

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

@@ -7,6 +7,7 @@ import {
   readFile,
   rename,
   rm,
+  unlink,
   writeFile,
 } from 'node:fs/promises';
 
@@ -68,22 +69,41 @@ 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', 'operation', 'manifest-hash'].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}`);
   }
+  values.operation ??= 'archive';
   if (values.files.length === 0) fail('at least one --file is required');
   if (!isAbsolute(values['source-root']) || !isAbsolute(values['archive-root'])) {
     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');
+  if (!['archive', 'retire'].includes(values.operation)) fail('operation must be archive or retire');
+  if (values.operation === 'retire' && !/^[0-9a-f]{64}$/.test(values['manifest-hash'] ?? '')) {
+    fail('retirement requires an exact lowercase --manifest-hash');
+  }
+  if (values.operation === 'archive' && values['manifest-hash'] !== undefined) {
+    fail('--manifest-hash applies only to retirement');
+  }
   values.files = [...new Set(values.files)].sort();
   for (const file of values.files) {
     const parts = file.split('/');
@@ -201,6 +221,203 @@ async function verifyArchive(archiveDir, identity, collected) {
   };
 }
 
+function sameJson(left, right) {
+  return JSON.stringify(left) === JSON.stringify(right);
+}
+
+async function verifyRetirementArchive(archiveRoot, archiveDir, identity, files, manifestHash) {
+  const archiveRel = relative(archiveRoot, archiveDir);
+  let current = archiveRoot;
+  for (const part of ['', ...archiveRel.split('/')]) {
+    if (part) current = join(current, part);
+    const st = await assertRealPath(current, 'directory');
+    if ((st.mode & 0o077) !== 0) fail(`archive permissions are not private: ${current}`);
+  }
+
+  const manifestPath = join(archiveDir, 'manifest.json');
+  const manifestStat = await assertRealPath(manifestPath, 'file');
+  if (manifestStat.nlink !== 1) fail(`refusing hard-linked archive file: ${manifestPath}`);
+  if ((manifestStat.mode & 0o077) !== 0) fail(`archive manifest permissions are not private: ${manifestPath}`);
+  const manifestBytes = await readFile(manifestPath);
+  if (sha256(manifestBytes) !== manifestHash) fail('recorded manifest hash mismatch');
+
+  let manifest;
+  try {
+    manifest = JSON.parse(manifestBytes.toString());
+  } catch {
+    fail(`invalid archive manifest: ${manifestPath}`);
+  }
+  if (manifest.version !== 1 || !sameJson(manifest.identity, identity)) {
+    fail(`archive manifest identity mismatch: ${manifestPath}`);
+  }
+  const manifestFiles = Object.keys(manifest.files ?? {}).sort();
+  if (!sameJson(manifestFiles, files)) fail(`archive manifest file set mismatch: ${manifestPath}`);
+  if (!manifestBytes.equals(Buffer.from(JSON.stringify(manifest, null, 2) + '\n'))) {
+    fail(`archive manifest bytes are not canonical: ${manifestPath}`);
+  }
+
+  const filesRoot = join(archiveDir, 'files');
+  const filesRootStat = await assertRealPath(filesRoot, 'directory');
+  if ((filesRootStat.mode & 0o077) !== 0) fail(`archive permissions are not private: ${filesRoot}`);
+  for (const rel of files) {
+    const expected = manifest.files[rel];
+    if (!expected || !/^[0-9a-f]{64}$/.test(expected.sha256) || !Number.isSafeInteger(expected.size) || expected.size < 0) {
+      fail(`invalid archive manifest entry: ${rel}`);
+    }
+    await assertNoSymlinkComponents(filesRoot, rel);
+    const archived = join(filesRoot, rel);
+    const st = await assertRealPath(archived, 'file');
+    if (st.nlink !== 1) fail(`refusing hard-linked archive file: ${archived}`);
+    if ((st.mode & 0o077) !== 0) fail(`archived evidence permissions are not private: ${archived}`);
+    const bytes = await readFile(archived);
+    if (bytes.length !== expected.size || sha256(bytes) !== expected.sha256) {
+      fail(`archived evidence hash mismatch: ${rel}`);
+    }
+  }
+  const actualFiles = await listArchiveFiles(archiveDir);
+  const expectedFiles = ['manifest.json', ...files.map((rel) => `files/${rel}`)].sort();
+  if (!sameJson(actualFiles, expectedFiles)) fail(`archive contains unexpected or missing files: ${archiveDir}`);
+  return { archiveDir, manifestPath, manifestHash, files: files.length, manifest };
+}
+
+function gitOutput(sourceRoot, args) {
+  const result = Bun.spawnSync(['git', '-C', sourceRoot, ...args], { stdout: 'pipe', stderr: 'pipe' });
+  if (result.exitCode !== 0) {
+    fail(`git ${args.join(' ')} failed: ${result.stderr.toString().trim() || `exit ${result.exitCode}`}`);
+  }
+  return result.stdout.toString();
+}
+
+async function inspectSource(sourceRoot, rel) {
+  let current = sourceRoot;
+  const parts = rel.split('/');
+  for (let index = 0; index < parts.length; index += 1) {
+    current = join(current, parts[index]);
+    const st = await lstat(current, { bigint: true }).catch((err) => {
+      if (err?.code === 'ENOENT') return null;
+      throw err;
+    });
+    if (!st) return null;
+    if (st.isSymbolicLink()) fail(`refusing symlink: ${current}`);
+    if (index < parts.length - 1 && !st.isDirectory()) fail(`not a directory: ${current}`);
+    if (index === parts.length - 1) {
+      if (!st.isFile()) fail(`not a regular file: ${current}`);
+      if (st.nlink !== 1n) fail(`refusing hard-linked source file: ${current}`);
+      const bytes = await readFile(current);
+      const after = await lstat(current, { bigint: true }).catch((err) => {
+        if (err?.code === 'ENOENT') fail(`source changed during verification: ${rel}`);
+        throw err;
+      });
+      for (const key of ['dev', 'ino', 'size', 'mtimeNs', 'nlink']) {
+        if (st[key] !== after[key]) fail(`source changed during verification: ${rel}`);
+      }
+      return {
+        bytes,
+        sha256: sha256(bytes),
+        size: bytes.length,
+        fingerprint: Object.fromEntries(
+          ['dev', 'ino', 'size', 'mtimeNs', 'ctimeNs', 'nlink'].map((key) => [key, after[key]]),
+        ),
+      };
+    }
+  }
+}
+
+function sameSource(left, right) {
+  return left.size === right.size &&
+    left.sha256 === right.sha256 &&
+    Object.keys(left.fingerprint).every((key) => left.fingerprint[key] === right.fingerprint[key]);
+}
+
+async function verifyRetirementSource(sourceRoot, head, files, manifest) {
+  await assertSafeAncestors(sourceRoot);
+  await assertRealPath(sourceRoot, 'directory');
+  const topLevel = resolve(gitOutput(sourceRoot, ['rev-parse', '--show-toplevel']).trim());
+  if (topLevel !== sourceRoot) fail(`source root is not the exact Git top-level: ${sourceRoot}`);
+  const actualHead = gitOutput(sourceRoot, ['rev-parse', 'HEAD']).trim();
+  if (actualHead !== head) fail(`Git HEAD mismatch: expected ${head}, found ${actualHead}`);
+
+  const states = {};
+  for (const rel of files) {
+    const state = await inspectSource(sourceRoot, rel);
+    if (state && (state.size !== manifest.files[rel].size || state.sha256 !== manifest.files[rel].sha256)) {
+      fail(`source evidence hash mismatch: ${rel}`);
+    }
+    states[rel] = state;
+  }
+
+  const expectedUntracked = new Set(files.filter((rel) => states[rel]));
+  const statusEntries = gitOutput(sourceRoot, [
+    'status', '--porcelain=v1', '-z', '--untracked-files=all', '--ignored=no',
+  ]).split('\0').filter(Boolean);
+  for (const entry of statusEntries) {
+    const code = entry.slice(0, 2);
+    const rel = entry.slice(3);
+    if (code !== '??' || !expectedUntracked.delete(rel)) {
+      fail(`tracked, staged, or unclassified Git dirt: ${rel || '(unknown)'}`);
+    }
+  }
+  if (expectedUntracked.size > 0) {
+    fail(`source evidence is not classified as untracked: ${[...expectedUntracked].sort()[0]}`);
+  }
+  return states;
+}
+
+async function retireEvidence(args, sourceRoot, archiveRoot, archiveDir, identity) {
+  const archive = await verifyRetirementArchive(
+    archiveRoot, archiveDir, identity, args.files, args['manifest-hash'],
+  );
+  const states = await verifyRetirementSource(sourceRoot, args.head, args.files, archive.manifest);
+  const removed = [];
+  const alreadyAbsent = args.files.filter((rel) => !states[rel]);
+
+  for (const rel of args.files) {
+    if (!states[rel]) continue;
+    const current = await inspectSource(sourceRoot, rel);
+    if (!current || !sameSource(current, states[rel])) fail(`source changed before retirement: ${rel}`);
+  }
+
+  for (let index = 0; index < args.files.length; index += 1) {
+    const rel = args.files[index];
+    if (!states[rel]) continue;
+    const current = await inspectSource(sourceRoot, rel);
+    if (!current || !sameSource(current, states[rel])) {
+      fail(`source changed before retirement: ${rel}`);
+    }
+    try {
+      await unlink(join(sourceRoot, rel));
+    } catch (err) {
+      const pending = args.files.slice(index).filter((file) => states[file]);
+      console.log(JSON.stringify({
+        status: 'partial',
+        archiveDir: archive.archiveDir,
+        manifestPath: archive.manifestPath,
+        manifestHash: archive.manifestHash,
+        files: archive.files,
+        removed,
+        alreadyAbsent,
+        pending,
+      }));
+      fail(`retirement stopped at ${rel}: ${err.message}`);
+    }
+    if (await lstat(join(sourceRoot, rel)).catch((err) => err?.code === 'ENOENT' ? null : Promise.reject(err))) {
+      fail(`source still exists after unlink: ${rel}`);
+    }
+    removed.push(rel);
+  }
+
+  console.log(JSON.stringify({
+    status: 'retired',
+    archiveDir: archive.archiveDir,
+    manifestPath: archive.manifestPath,
+    manifestHash: archive.manifestHash,
+    files: archive.files,
+    removed,
+    alreadyAbsent,
+    pending: [],
+  }));
+}
+
 async function listArchiveFiles(root, prefix = '') {
   const files = [];
   const entries = await readdir(join(root, prefix), { withFileTypes: true });
@@ -227,19 +444,24 @@ async function main() {
     archiveToSource === '' || (!archiveToSource.startsWith('..') && !isAbsolute(archiveToSource))
   ) 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);
+  if (args.operation === 'retire') {
+    await retireEvidence(args, sourceRoot, archiveRoot, archiveDir, identity);
+    return;
+  }
+
+  const collected = await collectSource(sourceRoot, args.files);
   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,108 @@
+---
+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.
+   When archived evidence is the last dirt, use the evidence archive helper's
+   manifest-bound retirement operation and require an empty pending set; never
+   unlink through prose or a shell loop. Verify the effective Archive Script
+   provenance before native removal: an unknown or required-but-untrusted hook
+   holds. Record its native outcome as `unconfigured`, `passed`, `failed`, or
+   `unknown`; only `unconfigured` or trusted `passed` may advance. Account for
+   branch-deletion side effects explicitly, then re-list both native workspaces
+   and Git refs. A failed or unknown hook outcome 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.