axstack 0.11.6 → 0.12.0

package/package.json

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

@@ -11,7 +11,7 @@ Pair A/B is retired for this contract; its artefacts remain untouched.
 
 - **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
+  Run, checks each selected PR's head out into a free project-local slot, dispatches the
   matching Axstack agent, reconciles completions and decisions, then exits. The
   driver is the automation session itself, with no `axstack-monitor` or
   `axstack-owner` role row. It never performs review or repair in its own
@@ -97,8 +97,8 @@ The driver performs this order and exits:
    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; 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
+   under "Run directory" below, which proves the slot disposable before
+   resetting 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
@@ -124,6 +124,36 @@ The driver performs this order and exits:
 
 ## Dispatch and repair selection
 
+Claude Code trusts a folder per git toplevel and stops at its "Quick safety
+check" dialog otherwise, and the driver never answers that dialog for a
+worker. So workers run in a fixed pool: every allowlisted project has
+exactly two slot worktrees, `slot-1` and `slot-2`, its Orca child worktrees
+created once, parented to the project's primary worktree, and trusted once
+by the user through that dialog. The driver never creates or removes a
+worktree and never writes `~/.claude.json`. A slot is free when no live
+dispatch marker names it, it is not in `retained_slots[]`, no terminal is
+listed in it, and its tree is clean; no free slot in the project defers the
+PR to `deferred[]` like a budget, not a hold. Taking a slot fetches the head into the project clone,
+checks the slot out detached at the pinned head, and verifies HEAD equals
+it; the marker's worktree is the slot path. Trusting a folder activates the
+full project surface: its `.claude/settings.json` and the hooks it defines,
+its `.mcp.json` servers, marketplace plugin auto-install, and `CLAUDE.md`;
+a hostile branch's hooks or MCP servers would run the moment the folder
+opens. So the worker is launched in Claude Code's own isolation mode,
+`--safe-mode`, through `terminal create` and `worker-start --terminal`,
+since `worker-start` cannot pass argv. Safe mode is the binary's sanctioned
+"all customizations disabled" path: no `CLAUDE.md`, skills, plugins, hooks,
+MCP servers, custom commands or agents load from anywhere, project or user;
+built-in tools and authentication are untouched, and the brief loads the
+skill files it needs by path. The driver confirms readiness from the
+rendered frame — `wait.satisfied`, the prompt marker present, the dialog
+absent — before dispatching; a dialog on a slot means the slot is not
+trusted: the slot is named in a health line, the PR is deferred, nothing is
+dispatched. What remains live is the repository's files as data the worker
+reads and the commands the worker itself chooses to run, which it already
+runs today; nothing from the branch loads, executes, or is offered for
+invocation on its own.
+
 Every selected PR receives one dispatch marker with task id, dispatch id,
 worktree, head, `started_at`, reservation (`verdict` or `repair`), and trigger:
 `{kind: check, name, app_id}` or `{kind: review, review_id, digest}`. There is at
@@ -147,10 +177,10 @@ An own PR needs repair when either trigger applies:
    triggers again subject to the 24 h cap.
 
 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 that
-project's primary worktree so it appears under the project it serves, and
-dispatch one `axstack-watch` agent in authored repair mode. Its
+selection of the lowest own PR in its stack that needs repair. Take a free
+slot of that project (its slots are parented to that project's primary
+worktree, so the work appears under the project it serves) at the exact
+head, 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.
@@ -172,8 +202,8 @@ and head. Budget exhaustion records the count and is not a hold.
 
 ## Agents and verdicts
 
-Every agent works in its own project-local Orca child worktree at the exact
-head and reports only through the Orca worker protocol.
+Every agent works in a project-local slot worktree checked out detached at
+the exact head and reports only through the Orca worker protocol.
 
 Peer review runs the two isolated configured reviewers on the identical brief,
 then the Luna gate. `APPROVE` requires complete exact-head/base reviews, gate
@@ -312,12 +342,12 @@ is no gate for health findings.
 ## Run directory
 
 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
+project worktree: no project owns the automation, and every slot 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
+proves the slot 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
@@ -327,21 +357,27 @@ targeted fetch of that exact remote branch into a per-dispatch ref, never
 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
+Only then it closes any terminal tab still listed, resets the slot to the
+pinned head, clears untracked artefacts, and verifies the slot is clean, so
+it is back in the pool. 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:
+are cleared; a candidate there is already pushed or token-held. A slot
+whose release is settled but whose HEAD cannot be proven disposable, and an
+abandoned slot that is dirty or holds an unproven candidate, are both
+**retained**: named in one `health[]` line with path and SHA, and blocking
+only that PR with the user as owner. Retention is mechanical on both paths:
+the driver appends `retained_slots[]` `{slot, pr, head, reason}`, which the
+free predicate excludes for every PR — a clean, terminal-less slot holding
+an unpushed candidate would otherwise look free — and an entry is cleared
+only by the user after reconciling the candidate. A dirty slot or a 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,
   draft, checks, reviews, last_self_review}}`, `dispatch_markers[]` (`pr`,
   `task_id`, `dispatch_id`, `worktree`, `head`, `started_at`, `reservation`,
   `trigger`), `deferred[]`, `pending_settlement[]`,
+  `retained_slots[]` (`slot`, `pr`, `head`, `reason`),
   `repair_caps{url: {expires_at}}`, `abandon_count{head: n}`,
   `processed_reviews[]` (`review_id`, `pr`, `head`, `digest`),
   `deploy_on_push{repo: [branches]}`,
@@ -383,12 +419,12 @@ delivery uses [axstack-relay](../../axstack-relay/SKILL.md).
   `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
+  refused after the slot was checked out, 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.
+  head and `git status --porcelain` must be empty, and then the slot is simply
+  free again in the same tick; there is nothing to remove.
   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