axstack 0.11.3 → 0.11.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "axstack",
-  "version": "0.11.3",
+  "version": "0.11.6",
   "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

@@ -9,8 +9,8 @@ Pair A/B is retired for this contract; its artefacts remain untouched.
 
 ## Roles and authority
 
-- **driver** — every 15 minutes, fresh Opus session in the dedicated Axstack
-  automations worktree. It discovers GitHub work, binds the persistent Orca
+- **driver** — every 15 minutes, fresh Opus session in the host's `root`
+  folder workspace, which is not a git repository and belongs to no project. It discovers GitHub work, binds the persistent Orca
   Run, creates one project-local child worktree per selected PR, dispatches the
   matching Axstack agent, reconciles completions and decisions, then exits. The
   driver is the automation session itself, with no `axstack-monitor` or
@@ -75,7 +75,8 @@ Read `cursor.json` and `decisions/`. Work is due for:
 - a `deferred[]` entry whose head still matches discovery;
 - an expired repair cap;
 - a dispatch marker older than 3 h;
-- an unsettled Orca delivery in `pending_settlement[]`.
+- an unsettled Orca delivery in `pending_settlement[]`;
+- a `runtime_refusal` record, because its re-test needs a launched tick.
 
 An `open` decision is not due. Write `pending.json` with the fingerprint,
 `observed_at`, `seen[]`, full discovery list, and hashed subset. Append
@@ -94,16 +95,21 @@ The driver performs this order and exits:
    dispatches nothing.
 2. Bind the persistent Run with `orca orchestration run-use` and read the
    inbox. For a `worker_done` matching a live marker, verify the review id at
-   the bound head, push range, or opened token. Release the worker; remove its
-   child worktree only after confirmed process exit and accepted settlement;
-   then clear the marker. Unverifiable delivery stays in
+   the bound head, push range, or opened token. Release the worker; once its
+   release receipt is settled and the process has exited, run the cleanup
+   under "Run directory" below, which proves the worktree disposable before
+   removing it; then clear the marker. Unverifiable delivery stays in
    `pending_settlement[]` and blocks only that PR.
 3. Consume decisions as their sole consumer under "Decision tokens" below.
 4. Reconcile every marker older than 3 h. A live worker gets `worker-stop`; an
    exited worker gets `worker-abandon`. Unknown liveness or user takeover
-   retains worktree and marker and blocks only that PR. After confirmed
-   abandon, remove the worktree, append one health line, increment the head's
-   `abandon_count`, and drop that head so normal selection retries once. For a
+   retains worktree and marker and blocks only that PR. An abandon is
+   confirmed by its accepted abandon receipt plus proven process exit; there
+   is no release receipt on this path. After confirmed abandon, run the same
+   cleanup under "Run directory" below with its extra clean-tree condition — a
+   dirty or unproven worktree is retained, not removed — append one health
+   line, increment the head's `abandon_count`, and drop that head so normal
+   selection retries once. For a
    review-triggered dispatch, use the marker's `trigger` to remove exactly its
    review id and digest from `processed_reviews[]`. A second abandon at that
    head is a user-owned hold.
@@ -112,7 +118,9 @@ The driver performs this order and exits:
    marker. Dispatch within the repair and review rules below.
 6. Promote the `pending.json` fingerprint verbatim, because it records
    observation rather than completion. Write `tick_done_at` and
-   `tick_outcome: ok`, then exit.
+   `tick_outcome: ok`, then close your own terminal tab and exit: each tick is
+   a fresh session and there is no hygiene sweep, so a tab left open outlives
+   the tick as a stray terminal in the root workspace.
 
 ## Dispatch and repair selection
 
@@ -140,8 +148,9 @@ An own PR needs repair when either trigger applies:
 
 Repair also requires no deploy-on-push head branch, no live repair cap, and
 selection of the lowest own PR in its stack that needs repair. Create a child
-worktree in that project's clone at the exact head, parented to the driver
-worktree, and dispatch one `axstack-watch` agent in authored repair mode. Its
+worktree in that project's clone at the exact head, parented to that
+project's primary worktree so it appears under the project it serves, and
+dispatch one `axstack-watch` agent in authored repair mode. Its
 brief contains only the triggering checks or review findings. Each open
 descendant records one user-owned `pending restack` hold until it stops needing
 repair. The 24 h cap starts at dispatch and an abandon does not refund it.
@@ -302,8 +311,31 @@ is no gate for health findings.
 
 ## Run directory
 
-One `.git/axstack/runs/<run id>/` directory under the Axstack git-common-dir
-contains:
+The driver and watchdog run from the host's `root` folder workspace, not a
+project worktree: no project owns the automation, and every child worktree
+belongs to the project it serves. That workspace is not a git repository, so
+the run directory is private host state, one
+`~/.local/share/axstack/runs/<run id>/` directory. Settlement leaves nothing
+behind, but never destroys work. Before any destructive step the driver
+proves the child is disposable: the worker is settled — on the release path
+a settled release receipt, on the abandon path an accepted abandon receipt,
+either with proven process exit; pending or unknown stops here — the
+worktree's HEAD is either the pinned head or a candidate that is durably
+reachable — pushed to the head branch, tested only after a successful
+targeted fetch of that exact remote branch into a per-dispatch ref, never
+`FETCH_HEAD`, so neither a stale tracking ref nor a concurrent fetch in the
+shared clone can fake durability, a failed fetch retaining the worktree — or held by a
+`refs/axstack/decisions/<token>` ref in the project clone; and, on the
+abandon path, the worktree has no uncommitted changes.
+Only then it closes any terminal tab still listed, clears untracked
+artefacts, removes the child worktree and its directory, deletes the branch
+the worktree created, and verifies the directory is gone. On the settled path
+the worker has finished, so untracked files are artefacts by definition and
+are cleared; a candidate there is already pushed or token-held. An abandoned
+worktree that is dirty or holds an unproven candidate is **retained**, named
+in one `health[]` line with its path and SHA, and blocks only that PR with
+the user as owner. A worktree, directory, branch, or terminal that outlives
+its dispatch without such a retention record is a health finding. The run directory contains:
 
 - `cursor.json` — driver only, with these exact keys: `fingerprint`,
   `tick_started_at`, `tick_done_at`, `tick_outcome`, `prs{url: {head, base,
@@ -313,7 +345,9 @@ contains:
   `repair_caps{url: {expires_at}}`, `abandon_count{head: n}`,
   `processed_reviews[]` (`review_id`, `pr`, `head`, `digest`),
   `deploy_on_push{repo: [branches]}`,
-  `legacy_automation_reviews[]`, `health[]`;
+  `legacy_automation_reviews[]`, `health[]`,
+  `runtime_refusal{code, first_seen, last_seen}` (absent when no runtime
+  hold is open);
 - `pending.json`, `precheck.log` — driver precheck only;
 - `decisions/<token>.json` — writers assigned by the lifecycle table;
 - `watchdog.log` and `watchdog-state.json` (occurrence `first_observed` values
@@ -325,9 +359,11 @@ Timestamps are UTC `YYYY-MM-DDTHH:MM:SSZ`; an unparsable timestamp is an
 `error` for the precheck and `unknown` for the watchdog, never silently
 ignored.
 
-Orca run history is the authoritative log. The launch worktree is a dedicated
-Axstack worktree where nobody develops. The current `defi-automations`
-worktree retires with the old pair. Keep this notification-policy edge in the
+Orca run history is the authoritative log. The launch workspace is the host's
+`root` folder workspace, not a project worktree: nobody develops there, it is
+not a git repository, and no project owns the automation. The briefs and the
+escalation template are read from the axstack checkout at an absolute path
+given in the prompt, never relative to the launch workspace. Keep this notification-policy edge in the
 run record: `Notification policy` authorizes the token and watchdog sends;
 delivery uses [axstack-relay](../../axstack-relay/SKILL.md).
 
@@ -338,7 +374,34 @@ delivery uses [axstack-relay](../../axstack-relay/SKILL.md).
 - Enumerate deploy-on-push branches from both repair repositories before
   enabling and store them in `cursor.json`; re-check on allowlist changes.
 - A later tick observing resolution or an explicit user decision clears a
-  hold. Silence never clears one.
+  hold. Silence never clears one. For a hold caused by an Orca runtime
+  refusal — a sub-worker dispatch rejected for depth, a launch capability the
+  runtime declines — observing resolution means re-attempting the refused
+  operation, once per tick, on the next eligible PR: success clears the hold.
+  The hold is keyed on Orca's structured error code (for the depth case,
+  `nested_worker_depth_exceeded`), stored in `cursor.json` as
+  `runtime_refusal {code, first_seen, last_seen}`; the same code keeps the
+  hold and updates `last_seen` without a new health line, a different code is
+  a new finding. Prose is never the key. When `worker-start` itself is
+  refused after the child worktree was created, there is no worker, so the
+  settlement proof does not apply; the driver reads the receipt's `failedStage`
+  and `residualResources` first. With no Dispatch and no residual resources
+  the no-worker branch applies: the worktree's HEAD must equal the pinned
+  head and `git status --porcelain` must be empty, and only then does the
+  driver remove the worktree, its directory and branch in the same tick.
+  With a Dispatch or any residual resource the failed start owns runtime
+  state, and retaining alone is not recovery: the driver follows the
+  runtime's recovery guide. With a Dispatch: `worker-list` for that run, and
+  the row's `nextAction` is an object `{kind, argv}` — a non-empty `argv` is
+  run verbatim through the same Orca executable and nothing else, while
+  `kind: none` authorizes no action beyond inspection and retention. With
+  residual resources but no Dispatch there is no row: the mutation itself is
+  recovered through `request-show` on the receipt's request id. The no-worker
+  branch applies only after the resources are proven gone. It never retries
+  in the same tick. Anything unproven retains the worktree with a health line
+  naming the stage and the resources. Persisted configuration such
+  as `orca-data.json` is never evidence either way; it is a snapshot that
+  lags the live setting, and the driver never reads it.
 
 ## Cutover