axstack 0.20.5 → 0.20.7

package/README.md

@@ -112,6 +112,9 @@ session in an isolated workspace and admits at most five executing PR jobs per
 lane, fewer under resource pressure. Waiting PRs remain tracked without consuming
 execution slots, so a large open-PR backlog does not require an idle agent per PR.
 Completed passes save continuity and retire their own verified resources.
+Held jobs preserve evidence, use private worktree-local temporary paths, and
+release capacity only after native descendant settlement. Uncertain execution
+teardown pauses the lane; settled evidence cleanup does not occupy a slot.
 
 Scheduling is opt-in and requires host-specific runtime validation before
 activation. Installing Axstack does not turn it on. Repairs are limited to

package/docs/workflows.md

@@ -200,6 +200,28 @@ 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
+reconciliation. Permission prompts and provider safety refusals are incomplete
+holds, never bypass or cross-model retry signals. The coordinator preserves the
+evidence, settles the exact owned tree through Orca's supported lifecycle, and
+releases capacity only after native settlement is verified. Unresolved execution
+teardown pauses the lane; retained evidence or cleanup metadata does not consume
+a slot after positive full-tree settlement. Once settled, an unchanged held
+event remains deduplicated while unrelated eligible PRs continue.
+
 Requested reviews cover any accessible repository; automatic repairs retain
 their `defi-com/monorepo` and `defi-com/mobile` scope. Orca owns schedules,
 sessions, Tasks, and Dispatches. Axstack adds no custom scheduler, queue engine,
@@ -216,6 +238,11 @@ after manager self-close, with an authorized deduplicated Telegram notification.
 The current operational contract is
 `skills/axstack/references/automations.md`.
 
+These documents and their source-contract tests define expected decisions.
+Scenario fixtures are behavioral-evaluation inputs, not model-evaluation
+results, and neither form is live proof; activation still requires the native
+canary described by the operational contract.
+
 ## Run record and evidence
 
 Substantive delegated or resumable work uses one compact `progress.md` rooted at

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.20.5",
+  "version": "0.20.7",
   "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
@@ -79,7 +111,9 @@ After cleanup, re-list and count only the earlier pass workspaces still remainin
 If three or more unreclaimed
 earlier pass workspaces remain, disable only this automation through the native
 CLI, verify the disabled setting, save/report the cleanup hold, and admit no new
-PR jobs. Also pause on a confirmed cleanup failure or unresolved lane ownership.
+PR jobs. Also pause on a confirmed earlier-manager retirement failure or
+unresolved lane ownership. A settled PR-job worktree retained for evidence is a
+cleanup hold, not unsettled execution or lane ownership.
 Already-dispatched passes still reconcile and retire only their own safe resources;
 this threshold is a stop condition, not an atomic hard cap on in-flight creations.
 An uncertain disable is a reported failure, not proof scheduling stopped. Resume
@@ -145,6 +179,13 @@ handles the current actionable event, returns exact receipts, then settles.
 Settlement returns continuity to the manager rather than retaining an idle PR
 coordinator. Reviewers retain the isolation required by `axstack-review`.
 
+Give each job a private job-local temporary directory under its per-PR
+worktree, following the ownership, containment, and cleanup checks in the
+[runtime boundary](orca-runtime.md#reviewer-workspaces-and-evidence). Never
+delete through a broad `TMPDIR` glob, sweep a shared temporary root, or wipe a
+general cache. Preserve evidence and any temporary path whose ownership or
+containment is uncertain.
+
 An unchanged exact head and unchanged event identity creates no job; an
 unchanged exact head with a new event identity remains actionable. Event
 identity includes the applicable review ID and body digest, check identity and
@@ -155,6 +196,39 @@ head, base, event identity, mode, owner and worker receipts, candidate,
 publication receipt, hold, and next action. GitHub remains authoritative for
 open state, revisions, reviews, checks, and merge state.
 
+## Held job settlement
+
+Use native runtime inspection, not saved prose or silence, to identify an
+actual hold and bind it to the exact Task, Dispatch, terminal, event, and
+evidence. Permission prompts and provider safety refusals are incomplete held
+outcomes: do not answer or bypass them, retry their content through another
+model, or claim completion. Do not forge `worker_done`. Record the held event
+identity and its resume condition in durable continuity. An unchanged hold creates no new job, no
+retry, and no repeated notification; a changed event is reconsidered against
+the original authority rather than assumed safe.
+
+Preserve the prompt or refusal evidence, then follow the version-matched
+orchestration recovery and cleanup guidance for every owned descendant. Use
+only supported native lifecycle actions and receipt-supplied next actions;
+saved status, contact loss, and a coordinator narrative do not settle a worker.
+Unknown or user-owned work is never a kill target. Do not release the PR slot
+until native state verifies settlement of the coordinator and every descendant.
+Unrelated eligible PRs continue after the tree is verified settled, while the
+held PR waits durably for its resume condition.
+
+Execution settlement and cleanup retention are separate. Positive full-tree
+process exit plus native Task and Dispatch settlement frees the slot. Retained
+metadata does not occupy an execution slot: preserve it and its evidence for
+reconciliation without reviving the failed job. Likewise, an archive hold
+blocks workspace removal, not settled execution capacity; record the cleanup
+hold, preserve the workspace, and let unrelated eligible PRs continue.
+
+An active, unknown, protected, or unverifiable coordinator or descendant is
+different: preserve its evidence and keep its slot occupied. Unresolved
+execution teardown, or failure to retire the manager pass itself, pauses the
+lane before another pass can admit work rather than accumulating active passes
+or claiming capacity from an uncertain process tree.
+
 When the current event is handled, settle and release owned native resources.
 Preserve dirty worktrees, unpushed candidates, unarchived review evidence, pending
 external results, and user-owned work until durability and ownership are
@@ -255,7 +329,9 @@ unarchived evidence, children, user-owned work, unknown files, or unexplained
 dirty source. A verified evidence archive does not require otherwise clean Git
 state, but every remaining change must still be positively classified and safe;
 unknown dirt blocks removal. Never use recursive shell deletion. Failed cleanup
-remains recorded, not silently forgotten.
+remains recorded, not silently forgotten. Failed PR-job workspace cleanup stays
+a cleanup hold after execution settles; failed or unverifiable manager-pass
+retirement pauses the lane instead of allowing active passes to accumulate.
 
 The activation canary must additionally prove distinct workspace IDs per pass,
 cross-workspace lane admission, self-retirement and absence after client reconnect,

package/skills/axstack/references/orca-runtime.md

@@ -68,8 +68,11 @@ An `input_accepted` stage proves only that input reached the terminal. Require
 started, and verify the requested role independently before trusting its work.
 A workspace trust, hook review, permission, authentication, or model prompt is
 a visible hold. Never answer a trust or permission prompt on the worker's
-behalf. Preserve the attempt and use only the runtime guide's inspection and
-recovery procedure; reconcile before retry so no duplicate writer starts.
+behalf. A permission prompt or provider safety refusal is a held, incomplete
+outcome, never consent or completion. Never bypass or retry it through another
+model. Preserve the attempt and its evidence, then use only
+the runtime guide's inspection and recovery procedure; reconcile before any
+authorized retry so no duplicate writer starts.
 
 ## Reviewer workspaces and evidence
 
@@ -84,8 +87,13 @@ Keep reviewer-authored reports, probes, and logs inside the reviewer's worktree
 in an untracked, dispatch-specific artifact directory, not in `/tmp` or a
 provider scratch directory. Name its absolute path in the brief and completion
 receipt; keep tracked candidate files read-only and do not commit artifacts.
-For test tools that need temporary files, use a worktree-local temporary
-directory where supported; incidental tool-managed caches are not review evidence.
+For tools that need temporary files, create one worktree-local, task- and
+dispatch-specific directory with mode `0700`, and scope `TMPDIR` to the owned
+command where supported. Before use or cleanup, validate that its real path is
+inside the exact worktree, is not a symbolic link, and matches the recorded
+owner. Remove only that exact validated owned path, with no glob or parent-root
+deletion; never wipe a general cache. Uncertain temporary files are preserved
+for later reconciliation. Incidental tool-managed caches are not review evidence.
 Before removing a reviewer worktree, preserve its report and supporting evidence
 in the driver's Orca workspace and update the run record's paths. Terminal
 release alone is not permission to discard evidence or remove the worktree.