@yemi33/minions 0.1.2423 → 0.1.2425

package/docs/watches.md

@@ -31,7 +31,7 @@ Defined in `engine/shared.js` (`WATCH_STATUS`):
 | `active`    | Eligible for evaluation each tick                                       |
 | `paused`    | Skipped by `checkWatches`; persists indefinitely until resumed/deleted  |
 | `triggered` | Reserved status (set on demand by callers; not auto-applied)            |
-| `expired`   | Auto-set when `stopAfter` is reached, or on first trigger for absolute conditions when `stopAfter === 0`. The watch is left on disk for audit but no longer evaluated *(source: `engine/watches.js:507-508`)* |
+| `expired`   | Auto-set when `stopAfter` is reached, or on first trigger for absolute conditions when `stopAfter === 0`. The watch is left on disk for audit but no longer evaluated *(source: `engine/watches.js:499-513`)* |
 
 Pause/resume flips the `status` field via `POST /api/watches/update` *(source: `engine/watches.js` `updateWatch`, `dashboard.js` `handleWatchesUpdate`)*.
 
@@ -44,14 +44,14 @@ Defined in `engine/shared.js` (`WATCH_CONDITION`). Conditions split into two fam
 
 `merged`, `build-fail`, `build-pass`, `completed`, `failed`, `concluded`, `approved`, `rejected`, `ready-for-merge`, `retry-limit-reached`, `all-items-done`, `item-failed-n-times`.
 
-When `stopAfter === 0`, these are **fire-once** — the engine flips the watch to `expired` after the first trigger so a permanently-merged PR (or a permanently-true compound state assertion like `ready-for-merge`) doesn't keep notifying *(source: `engine/watches.js:507-508`)*.
+When `stopAfter === 0`, these are **fire-once** — the engine flips the watch to `expired` after the first trigger so a permanently-merged PR (or a permanently-true compound state assertion like `ready-for-merge`) doesn't keep notifying *(source: `engine/watches.js:499-513`)*.
 
 > **Per-target override (W-mp7hg58e000b5212):** the global `WATCH_ABSOLUTE_CONDITIONS` set is the legacy fallback. Each target type now declares its own `absoluteConditions: [...]` array in its spec; `registerTargetType` normalizes that into a `Set` that takes precedence at evaluation time. The plugin contract (see below) uses this to keep absolute-vs-change semantics local to each target type. Plugins that omit `absoluteConditions` get an empty set (all change-based).
 
 ### Change-based conditions
 `status-change`, `any`, `new-comments`, `vote-change`, `stage-complete`, `ran`, `enabled`, `disabled`, `activity-change`, plus the predicate conditions added under P-w4e2f6a1 / P-w5b8d2c9 for the `pr`, `work-item`, `plan`, and `pipeline` target types (`head-commit-change`, `mergeable-flipped`, `behind-master`, `draft-flipped`, `stalled`, `dependency-met`, `stage-advanced`, `stuck-in-stage`). See `engine/shared.js` `WATCH_CONDITION` for the canonical enum.
 
-These compare the live entity against the watch's `_lastState` snapshot and run forever when `stopAfter === 0`. Baseline `_lastState` is captured on the first check so the very next change triggers the watch *(source: `engine/watches.js:434, 520`)*.
+These compare the live entity against the watch's `_lastState` snapshot and run forever when `stopAfter === 0`. Baseline `_lastState` is captured on the first check so the very next change triggers the watch *(source: `engine/watches.js:436-440, 558-559`)*.
 
 ### Tick-counted conditions
 `stalled`, `stuck-in-stage` — require N consecutive unchanged captures (default `WATCH_STALLED_DEFAULT_TICKS = 12`, `WATCH_STUCK_STAGE_DEFAULT_TICKS = 12`, both in `engine/shared.js`). Counters (`_unchangedTicks`, `_stuckStageTicks`) are recomputed inside `_captureState` by comparing the fresh snapshot against `prevState`.
@@ -69,24 +69,27 @@ Compound state-assertion predicates (`ready-for-merge`, `retry-limit-reached`, `
 
 ## Target Types — `TARGET_TYPES` Registry
 
-Target-type behavior in `engine/watches.js` is **data-driven via a registry** *(source: `engine/watches.js:124-153`)*. Each spec must provide:
+Target-type behavior in `engine/watches.js` is **data-driven via a registry** *(source: `engine/watches.js:122-174`)*. Each spec uses the following fields; entries are required unless marked optional:
 
 - `label` — human name shown in dashboard pickers
-- `description` — short help text
+- `description` — **(optional)** short help text; defaults to `''` in `listTargetTypes()`
 - `conditions` — non-empty array of accepted condition keys (also acts as the per-type allowlist)
-- `absoluteConditions` — *(optional)* subset of `conditions` that fire-once when `stopAfter === 0`; defaults to `[]` (all conditions treated as change-based)
-- `fetchEntity(target, state)` — entity-or-null lookup
-- `captureState(entity)` — snapshot used for change-detection diffs
-- `evaluate(condition, entity, prevState, target)` — returns `{ triggered, message }`
-- `isTerminalForCondition(condition, entity, prevState)` — *(optional)* W-mqa63opd000ha836. When a watch's `condition` cannot possibly fire again because the target reached a permanent terminal state (e.g. a PR was merged/closed/abandoned and the watch is on `build-fail`/`build-pass`/`vote-change`/`new-comments`/`head-commit-change`/`mergeable-flipped`/`behind-master`/`ready-for-merge`/`draft-flipped`), return `true` and the engine auto-expires the watch instead of polling forever. Default returns `false` so existing target types keep current behavior. The main check-loop guard only invokes this when `triggerCount > 0` **or** the prev-state status already matched the current entity status — so a watch armed on an already-terminal PR with `condition: merged` still gets its one shot via the absolute-condition fire-once path *(source: `engine/watches.js:157-160,542-549`)*.
+- `absoluteConditions` — *(optional)* `Set` of condition keys that fire-once when `stopAfter === 0`; defaults to empty set (all conditions treated as change-based)
+- `fetchEntity(target, state)` — entity-or-null lookup; must return the fetched resource or null
+- `captureState(entity, prevState)` — snapshot object used for change-detection diffs; `prevState` parameter lets counters and custom fields carry across checks
+- `evaluate(condition, entity, prevState, target)` — returns `{ triggered: boolean, message: string }`; core condition-check logic
+- `isTerminalForCondition(condition, entity, prevState)` — *(optional)* W-mqa63opd000ha836. When a watch's `condition` cannot possibly fire again because the target reached a permanent terminal state (e.g. a PR was merged/closed/abandoned and the watch is on `build-fail`, `build-pass`, `vote-change`, `new-comments`, `head-commit-change`, `mergeable-flipped`, `behind-master`, `ready-for-merge`, or `draft-flipped`), return `true` and the engine auto-expires the watch. Default returns `false` so existing target types keep polling forever. The main check loop invokes this only when `triggerCount > 0` **or** the prev-state status already matched current entity — so a watch armed on an already-terminal PR with `condition: merged` still fires once via the absolute-condition fire-once path *(source: `engine/watches.js:150-158, 537-550`)*.
+- `contextVars(entity, prevState, newState)` — *(optional)* returns object with extra action-template variables contributed by the target type (e.g., `{ httpStatus: 200, prevExtracted: 'foo' }`)
 
-The registry IS the allowlist for `createWatch` and `/api/watches/target-types`; the old hardcoded "pr or work-item" check is gone. Add a new target type at runtime with `registerTargetType(type, spec)` and look one up with `getTargetType(type)`. `listTargetTypes()` returns the serializable form used by the dashboard *(source: `engine/watches.js:124-174`)*.
+The registry IS the allowlist for `createWatch` and `/api/watches/target-types`; the old hardcoded "pr or work-item" check is gone. Add a new target type at runtime with `registerTargetType(type, spec)` and look one up with `getTargetType(type)`. `listTargetTypes()` returns the serializable form used by the dashboard *(source: `engine/watches.js:122-174`)*.
 
 ### User-extensible via `watches.d/` (W-mp7hg58e000b5212)
 
-At engine boot, every `*.js` file in `<MINIONS_DIR>/watches.d/` is auto-loaded **after** the built-in registrations *(source: `engine/watches.js:1319-1354`)*, so plugins can both add new target types and override built-ins. A plugin file exports either `{ name, spec }` or an array of such objects. Failures are logged-and-skipped — one bad plugin must not break boot or block other plugins. Reloads require an engine restart.
+At engine boot, every `*.js` file in `<MINIONS_DIR>/watches.d/` is auto-loaded **after** the built-in registrations *(source: `engine/watches.js:1401-1436`)*, so plugins can both add new target types and override built-ins. A plugin file exports either `{ name, spec }` or an array of such objects. Failures are logged-and-skipped — one bad plugin must not break boot or block other plugins. Reloads require an engine restart.
 
-Canonical example: `watches.d/http.js` (W-mp7i22mu00191b07) — a generic HTTP poller covering the full plugin contract including `extractState` (custom snapshot fields not on the entity itself) and `extendTemplateVars` (custom action-template vars like `{{httpStatus}}`, `{{prevExtracted}}`).
+Canonical example: `watches.d/http.js` (W-mp7i22mu00191b07) — a generic HTTP poller covering the full plugin contract including `captureState` (custom snapshot fields) and `contextVars` (custom action-template vars like `{{httpStatus}}`, `{{prevExtracted}}`).
+
+This source checkout also includes `ado-author-prs`, `gh-author-prs`, and `teams-channel` plugins under `watches.d/`. They are dynamically loaded plugins, not members of the eight built-in target types; `GET /api/watches/target-types` is the authoritative list for the running installation.
 
 ### Built-in target types
 
@@ -103,11 +106,11 @@ The eight built-ins are registered at module load *(source: `engine/watches.js`
 | `dispatch`    | Dispatch entry id                    | `completed`, `failed`, `status-change`, `any`                              | Looks across `pending` / `active` / `completed` lists |
 | `agent`       | Agent id                             | `activity-change`, `status-change`, `any`                                  | `activity-change` fires only on transitions in/out of `'working'` |
 
-`evaluateWatch` dispatches to `tt.evaluate(...)`; unknown target types return `"Unknown target type: ..."` and unknown conditions return `"Unknown condition: ..."` — both are non-triggering *(source: `engine/watches.js:318-371`)*.
+`evaluateWatch` dispatches to `tt.evaluate(...)`; unknown target types return `"Unknown target type: ..."` and unknown conditions return `"Unknown condition: ..."` — both are non-triggering *(source: `engine/watches.js:320-365`)*.
 
 ### Plugin folder (`watches.d/`) — user-extensible target types
 
-W-mp7hg58e000b5212 added a **plugin folder** so operators can register new target types without editing engine source. At engine boot, `engine/watches.js` scans `<MINIONS_DIR>/watches.d/*.js` *after* the eight built-ins are registered (so plugins can override a built-in by re-using its key — last-write-wins) and calls `registerTargetType()` for each export *(source: `engine/watches.js:1319-1354`)*.
+W-mp7hg58e000b5212 added a **plugin folder** so operators can register new target types without editing engine source. At engine boot, `engine/watches.js` scans `<MINIONS_DIR>/watches.d/*.js` *after* the eight built-ins are registered (so plugins can override a built-in by re-using its key — last-write-wins) and calls `registerTargetType()` for each export *(source: `engine/watches.js:1401-1436`)*.
 
 Each `watches.d/<name>.js` file must export `{ name, spec }` (or an array of those):
 
@@ -120,10 +123,11 @@ module.exports = {
     conditions: ['status-change', 'value-equals'],
     absoluteConditions: ['value-equals'],          // optional, defaults to []
     fetchEntity(target, state) { /* sync entity lookup */ },
-    captureState(entity) { /* snapshot for diffs */ },
+    captureState(entity, prevState) { /* snapshot for diffs */ },
     evaluate(condition, entity, prevState, target) {
       return { triggered: <bool>, message: '...' };
     },
+    contextVars(entity, prevState, newState) { return {}; }, // optional
   },
 };
 ```
@@ -134,7 +138,7 @@ Resolution is `path.join(shared.MINIONS_DIR, 'watches.d')` so it works in both d
 
 ## Tick Integration
 
-`engine.js` calls `checkWatches(config, state)` every `ENGINE_DEFAULTS.watchPollEvery` ticks (default 18 ⇒ ~3 min at the default 10s tick) inside its own `safe('checkWatches', ...)` block *(source: `engine.js:7439-7470`)*. The engine builds the state object from cached project files + module reads:
+`engine.js` calls `checkWatches(config, state)` every `ENGINE_DEFAULTS.watchPollEvery` ticks (default 18 ⇒ ~3 min at the default 10s tick) inside its own `safe('checkWatches', ...)` block *(source: `engine.js:11286-11328`)*. The engine builds the state object from cached project files + module reads:
 
 ```
 {
@@ -150,16 +154,16 @@ Resolution is `path.join(shared.MINIONS_DIR, 'watches.d')` so it works in both d
 1. Skips paused/expired watches and any watch checked within its `interval`.
 2. Captures a baseline `_lastState` on first check (so change conditions have something to diff).
 3. Calls `evaluateWatch(watch, state)`.
-4. On trigger: increments `triggerCount`, sets `last_triggered`, queues an inbox notification (if `notify === 'inbox'`), and snapshots an action task for any configured `watch.action`.
+4. On trigger: increments `triggerCount`, sets `last_triggered`, and snapshots an effective action when notification or follow-up work is configured. When `notify === 'inbox'` and the watch has an owner, an implicit `{ type: 'notify' }` action step is prepended before any configured `watch.action`; without that implicit step, a single explicit action keeps its object shape.
 5. Applies fire-once / `stopAfter` expiration.
 6. On non-trigger: writes a per-poll inbox note when `onNotMet === 'notify'`.
 7. Refreshes `_lastState` for the next check.
 
-I/O happens **outside the lock**: notifications via `writeToInbox`, follow-up actions via `_runActionTask` (`Promise` per action, failures isolated). Each action's result is persisted back onto the watch as `_lastActionResult` in a follow-up locked write *(source: `engine/watches.js:562+` `_runActionTask`)*.
+I/O happens **outside the lock**. Trigger actions, including the implicit inbox notification, run through `_runActionTask`. Only `onNotMet === 'notify'` polling notes use the direct notification queue and `writeToInbox`. Each action result is persisted back onto the watch as `_lastActionResult` in a follow-up locked write. An implicit notify makes the effective action array-shaped, so its result uses the `type: 'chain'` / `steps[]` shape; an explicit action without an implicit notify preserves the legacy single-action result shape *(source: `engine/watches.js:459-495,515-521,601-684`)*.
 
 ## Follow-Up Actions on Trigger
 
-`watch.action` is an optional structured action that runs after the inbox notification fires. Action types live in a sibling registry in `engine/watch-actions.js` and are validated at create/update time *(source: `engine/watches.js:184-248` `createWatch`, `engine/watch-actions.js:56` `registerActionType`)*. `GET /api/watches/action-types` returns the live list for dashboard pickers.
+`watch.action` is an optional structured action (or action chain). When the implicit inbox notification is enabled, configured actions follow it in the same effective chain. Action types live in a sibling registry in `engine/watch-actions.js` and are validated at create/update time *(source: `engine/watches.js:189-245` `createWatch`, `engine/watch-actions.js:95-105` `registerActionType`)*. `GET /api/watches/action-types` returns the live list for dashboard pickers.
 
 ### Built-in actions
 
@@ -167,10 +171,10 @@ I/O happens **outside the lock**: notifications via `writeToInbox`, follow-up ac
 |------------------------|-----------------------------------------------------------------------------------------------|
 | `notify`               | Explicit inbox write; lets you customize `owner`/`body` instead of the default trigger string |
 | `dispatch-work-item`   | Add a new project or central work item with `createdBy: "watch:<id>"`  |
-| `run-skill`            | Wrapper around `dispatch-work-item` that asks the agent to run a specific `.claude` skill     |
+| `run-skill`            | Wrapper around `dispatch-work-item` that asks the agent to run a named runtime-native skill  |
 | `webhook`              | `http`/`https` request to an arbitrary URL (10s safety timeout, JSON or string body)          |
 | `minions-api`          | Loopback call to the in-process dashboard at `http://127.0.0.1:${shared.readDashboardPortFile(MINIONS_DIR)?.port \|\| 7331}` (reads the bound-port beacon file, not the `MINIONS_PORT` env, so it still resolves after an `EADDRINUSE` port scan) — `endpoint` must start with `/api/`; sets `X-Minions-Internal: 1`; returns `{ok, status, summary, response}` for chain-step templating |
-| `cancel-work-item`     | Flip a WI to `WI_STATUS.CANCELLED` across all known work-items files                          |
+| `cancel-work-item`     | Flip a WI to `WI_STATUS.CANCELLED` across central and configured-project SQL scopes           |
 | `trigger-pipeline`     | Start a new pipeline run (skipped if the pipeline already has an active run)                  |
 | `archive-plan`         | Set PRD `status="archived"` + `archivedAt`                                                    |
 | `resume-plan`          | Set PRD `status=PLAN_STATUS.ACTIVE` and clear `planStale`                                     |
@@ -180,7 +184,7 @@ Constants live in `WATCH_ACTION_TYPE` (`engine/shared.js`); handlers in `engine/
 
 ### Templating
 
-Action params support `{{var}}` substitution from the trigger context *(source: `engine/watch-actions.js:145-220`)*. Built-in vars from `buildTriggerContext`:
+Action params support `{{var}}` substitution from the trigger context *(source: `engine/watch-actions.js:133-230`)*. Built-in vars from `buildTriggerContext`:
 
 - Always: `target`, `targetType`, `condition`, `watchId`, `triggerCount`, `message`
 - All scalar fields from `newState` (e.g. `status`, `buildStatus`, `reviewStatus`, `lastRun`)
@@ -190,13 +194,13 @@ Unknown vars are left as `{{var}}` so callers can detect them downstream.
 
 ### Failure isolation
 
-Action handlers must return `{ ok: false, summary }` rather than throw — `runWatchAction` wraps them in try/catch as a backstop *(source: `engine/watch-actions.js:223-270`)*. A bad action never blocks other watches in the same tick, and the failed result is persisted onto the watch as `_lastActionResult` for debugging. Multi-step action chains run via `runWatchActionChain` *(source: `engine/watch-actions.js:271+`)* — each step's `{ok, summary, result}` is templated into the next step's params as `{{steps.N.result.<field>}}`.
+Action handlers must return `{ ok: false, summary }` rather than throw — `runWatchAction` wraps them in try/catch as a backstop *(source: `engine/watch-actions.js:262-293`)*. A bad action never blocks other watches in the same tick, and the failed result is persisted onto the watch as `_lastActionResult` for debugging. Multi-step action chains run via `runWatchActionChain` *(source: `engine/watch-actions.js:310-355`)* — each step's `{ok, summary, result}` is templated into the next step's params as `{{steps.N.result.<field>}}`.
 
 ## Dashboard Surface
 
 | Route                          | Method | Handler                       | Purpose                                                                 |
 |--------------------------------|--------|-------------------------------|-------------------------------------------------------------------------|
-| `/watches`                     | GET    | `dashboard/pages/watches.html` | Watches page (sidebar link in `dashboard/layout.html:75`)               |
+| `/watches`                     | GET    | `dashboard/pages/watches.html` | Watches page (sidebar link in `dashboard/layout.html:111`)              |
 | `/api/watches`                 | GET    | `handleWatchesList`           | List all watches                                                        |
 | `/api/watches/target-types`    | GET    | `handleWatchesTargetTypes`    | Live registry from `listTargetTypes()` — used by the create-watch modal |
 | `/api/watches/action-types`    | GET    | `handleWatchesActionTypes`    | Live registry from `listActionTypes()`                                  |
@@ -212,7 +216,7 @@ The CC state preamble injects a `Watches: <count>` line via `getWatches()` so th
 
 ## Command Center Integration
 
-CC creates, pauses, resumes, and deletes watches by calling the REST API directly via its `Bash` tool — the older `===ACTIONS===` `create-watch`/`delete-watch`/`pause-watch`/`resume-watch` actions have been retired *(source: `test/unit.test.js:16976-17008`, `test/unit/watches-module.test.js:673`)*. To use a watch from CC chat, ask it something like:
+CC creates, pauses, resumes, and deletes watches by calling the REST API directly via its `Bash` tool — the older `===ACTIONS===` `create-watch`/`delete-watch`/`pause-watch`/`resume-watch` actions have been retired *(source: `test/unit.test.js:21048-21052`, `test/unit/watches-module.test.js:1699`)*. To use a watch from CC chat, ask it something like:
 
 > "Watch PR 1234 for build-pass and dispatch a verify work-item when it fires."
 
@@ -223,9 +227,10 @@ CC will discover the endpoints from `GET /api/routes` and `POST /api/watches` wi
 When a watch fires:
 
 - The SQL watch record gets `triggerCount++`, `last_triggered=<ISO>`, `_lastTriggerMessage=<message>`, and a refreshed `_lastState`.
-- An inbox file lands at `notes/inbox/<owner>/watch-<watchId>-<n>.md` (when `notify === 'inbox'`).
-- If `action` is set, a follow-up runs (work item, webhook POST, plan archive, ...) and writes `_lastActionResult` (`{ type, ok, summary, dispatchedItemId?, at }`) back onto the watch.
-- The SQL engine log gets `Watch triggered: <id> — <message>` and `Watch <id> action <type>: <summary>`.
+- When `notify === 'inbox'`, the engine prepends an implicit `{type: 'notify'}` action to the action chain (if present) or runs notify standalone, so the inbox alert participates in action-chain execution and `_lastActionResult` *(source: `engine/watches.js:459-496`)*. This is the **trigger-time notify**, paired with an optional explicit `action`.
+- When `onNotMet === 'notify'` (and the condition has NOT yet fired), the engine instead queues a direct poll notification outside the action chain — independent of any `action` field *(source: `engine/watches.js:515-521`)*. This is a separate **onNotMet-notify**, useful for "still watching, condition not met yet" progress updates.
+- If an action runs, `_lastActionResult` stores either the single-action shape (`{ type, ok, summary, dispatchedItemId, at }`) or the chain shape (`{ type: "chain", ok, summary, aborted, steps, at }`).
+- The SQL engine log gets `Watch triggered: <id> — <message>` and `Watch <id> action <type-or-chain[N]>: <summary>`.
 
 Absolute conditions firing under `stopAfter === 0` flip `status` to `expired`; `stopAfter > 0` flips it to `expired` once `triggerCount >= stopAfter`.
 
@@ -242,7 +247,7 @@ Absolute conditions firing under `stopAfter === 0` flip `status` to `expired`; `
 | `_lastActionResult.ok === false` with `"unknown action type"`           | The `action.type` isn't registered. List with `listActionTypes()` / `GET /api/watches/action-types` |
 | Webhook action returns `"only http/https allowed"`                      | URLs must use `http://` or `https://` schemes; other protocols are rejected by design *(source: `engine/watch-actions.js` `WEBHOOK` handler)* |
 | Trigger fires but follow-up `dispatch-work-item` is missing              | Check the engine log for `Watch <id> action <type>: <summary>`. Common reasons: missing `title`, a project-scope write failed, or the WI landed in the central scope because no project was specified |
-| Watch `_lastActionResult` shows `"timeout"` for webhook                 | Webhooks have a 10s safety timeout to keep the watches tick fast *(source: `engine/watch-actions.js:482-484`)* |
+| Watch `_lastActionResult` shows `"timeout"` for webhook                 | Webhooks have a 10s safety timeout to keep the watches tick fast *(source: `engine/watch-actions.js:550-553`)* |
 | `checkWatches` block crashes silently                                   | Wrapped in `safe('checkWatches', ...)` so one failure doesn't abort the tick. Inspect the engine log for `Watch check error (<id>)` lines. Regression #1088: the block must use `getProjects(config)`, never the long-removed `PROJECTS` constant |
 
 ## See Also

package/docs/worktree-lifecycle.md

@@ -9,7 +9,7 @@ Lifecycle keeps the cross-cutting invariants; the detail lives here.
 > Source of truth: `engine/worktree-pool.js`, `engine/shared.js#removeWorktree`
 > + `_retryFsOp`, `engine.js` (`_quarantineDirtyWorktree`,
 > `_killGitDescendantsForWorktree`, `pruneOrphanWorktrees*`, `gcDispatchWorktreeIfOrphan`),
-> `engine/cleanup.js`. Last verified: 2026-06-09.
+> `engine/cleanup.js`. Last verified: 2026-07-23.
 
 ## Operator-checkout boundary
 
@@ -30,6 +30,17 @@ legacy processes are terminated and retried. Worktree setup may update shared Gi
 but it never checks out, resets, cleans, writes files, or removes
 `.git/index.lock` in the operator checkout.
 
+Before allocating a branch-bearing worktree-mode dispatch, the engine compares
+the target branch's `git worktree list --porcelain` holder against every
+configured `localPath`, including overlapping nested-project layouts. A match
+keeps the dispatch and source work item pending with
+`_pendingReason: "worktree_branch_held"` and `_worktreeBranchHeld`
+branch/path diagnostics; it consumes no retry and is re-checked each tick.
+Releasing the branch clears the diagnostic and dispatches automatically.
+`spawnAgent` repeats the probe, and the `git worktree add` error handler applies
+the same deferral if the checkout acquires the branch in the remaining race
+window. Neither path runs an agent in or changes the operator checkout.
+
 Worktrees that host live `managed_spawn` or `keep_processes` cwd records are
 anchored across dispatch-end, periodic, boot, in-root, and out-of-root GC.
 Anchor comparisons use canonical filesystem paths so junction/case aliases do
@@ -38,17 +49,28 @@ not make a live service's worktree look orphaned.
 ## Live-worktree guard (W-mq5rwwss000f30a7)
 
 **Invariant:** every code path that wipes, renames, or recycles a worktree
-MUST call `shared.isWorktreePathLive(path, { db?, excludeDispatchId? })`
+MUST call `shared.isWorktreePathLive(path, { db?, excludeDispatchId?, excludeSpawnLeaseId? })`
 first and skip on `true`. Originally added after W-mq5n1zx5000hcfb5 — an
 agent's worktree was wiped 4× consecutively by the reaper while the
 dispatch was still active.
 
 - **Backed by SQL** against `dispatches` (status IN ('pending','active')),
   reading `json_extract(data, '$.worktreePath')` with a `data.meta.worktreePath`
-  fallback. The pending → active transition persists `item.worktreePath`
-  on the dispatch row so the guard has a path to correlate.
+  fallback. `_claimSpawnAttemptLease` first persists `_spawnLeaseId`, owner PID,
+  and claim time on the pending row; `_persistSpawnWorktreePath` then records
+  the path before runtime activation. Setup is protected while still pending,
+  and leased pending rows count against dispatch capacity.
 - **Fails OPEN** (returns `true`) when SQLite is unreachable or the query
   throws — better to leak a worktree than nuke an agent's unpushed work.
+- **Scoped exclusions:** normal owner cleanup may pass `excludeDispatchId`.
+  Spawn-time quarantine also passes `excludeSpawnLeaseId`; the dispatch row is
+  excluded only when its persisted lease matches. A stale tick carrying an old
+  lease therefore sees a successor lease as live and cannot rename its
+  worktree.
+- **Generation check:** `_isSpawnAttemptCurrent` revalidates both
+  `tickGeneration` and the persisted lease throughout worktree setup.
+  `_quarantineDirtyWorktree` repeats that check before destructive stages and
+  returns `{ skipped: true, staleLease: true }` after ownership changes.
 - **Wired sites:** `shared.removeWorktree` (accepts `{ excludeDispatchId }`
   forwarded to the guard); pool-return chain in `engine.js`
   (`excludeDispatchId: id` so the dispatch can clean up its own worktree);
@@ -85,6 +107,32 @@ that intentionally preserve an existing branch continue using that branch
 unchanged. Warm-pool borrowing keeps its existing fetch-and-checkout of
 `origin/<mainBranch>`.
 
+## Creation integrity gate (#905)
+
+`engine.js#runWorktreeAdd` treats every nonzero `git worktree add` result as a
+potentially corrupt partial checkout. Before retrying, it checks the live-path
+guard, removes locked/initializing Git metadata with double force, removes any
+remaining directory through the shared Windows file-lock retry helper, prunes,
+and proves that neither the path nor its worktree registration remains. A retry
+uses a generation-suffixed candidate path rather than the failed path.
+An unregistered candidate directory is cleaned before fresh creation only when
+it carries the engine ownership marker. An unmarked pre-existing directory is
+treated as foreign, preserved, and bypassed with a generation-suffixed candidate
+path. Periodic GC treats generation-suffixed candidates as owned by the live
+dispatch until the exact path is persisted.
+
+A zero exit code is necessary but not sufficient. Before the candidate is
+persisted as the dispatch worktree or an agent can start, it must:
+
+- appear at the intended canonical path in `git worktree list --porcelain`;
+- resolve its own top level and HEAD consistently with that registration;
+- match the requested branch (or detached state) and pre-resolved target commit;
+- return a clean `git --no-optional-locks status --porcelain`.
+
+Validation failures follow the same cleanup-and-fresh-retry path. The former
+`recoverPartialWorktree` fallback was removed: a command that returned nonzero
+is never accepted merely because the leftover directory answers `rev-parse`.
+
 ## Ownership marker is never "dirty" (#284)
 
 The reused-worktree preflight (`assertCleanSharedWorktree`) builds its
@@ -123,10 +171,32 @@ quarantine fallback; transient probe, fetch, auth, and push failures leave clean
 ahead commits in place for retry. Recoverable
 `refs/minions/quarantine/*` and `refs/minions/quarantine-wip/*` refs are listed
 on Dashboard → Engine under **Quarantined Work**.
+Periodic cleanup deletes these recovery refs after 10 days. This is intentionally
+longer than the 24-hour quarantine-directory retention window: the refs preserve
+committed HEAD and WIP snapshots after the directory itself is removed, while
+still preventing recovery refs from growing without bound.
+
+At dispatch close, an error result is inspected before orphan GC. A clean branch
+that is aligned with origin (or successfully pushed there) remains removable.
+Dirty files, unpushed commits that cannot be pushed, and indeterminate branch
+state go through `_quarantineDirtyWorktree` first; dispatch-end GC is skipped
+unless that inspection proves removal safe. The quarantine live guard receives
+`excludeDispatchId` so the ending dispatch may preserve its own worktree while
+any sibling live claimant still blocks rename/removal. This also covers exit
+code `0` that becomes an error only after the required completion report or PR
+contract is validated.
+
+Process-anchored failed worktrees are snapshotted without moving the live
+directory. If both that WIP snapshot and the protection-marker write fail, the
+dispatch stays active with `_worktreeProtectionDeferred` instead of becoming
+terminal. The active SQL dispatch row remains a fail-open GC claim after the
+process anchor expires. Timeout recovery then retries preservation; only a
+durable recovery ref or protected quarantine allows terminalization and later
+periodic cleanup.
 
 When `discoverFromWorkItems` finds a worktree in a `WORKTREE_DIRTY`,
 `WORKTREE_DIVERGENT`, or post-stuck state, `_quarantineDirtyWorktree`
-moves it to `<root>/.quarantined/<basename>-<utc>` and lets the next tick
+moves it to `<path>-quarantine-<epoch-ms>` and lets the next tick
 recreate a clean worktree. Six layered defenses cover the Windows EBUSY
 race when git status descendants still hold packfile handles
 (W-mq5n1zx5000hcfb5; PR #3156).
@@ -172,6 +242,12 @@ command when `preserved`, a `⚠️` warning when `failed`, or an explicit "noth
 to preserve" note when `clean` — so a human never has to guess which bucket a
 given quarantine landed in.
 
+If either the committed backup ref or an uncommitted WIP ref cannot be created,
+the quarantined directory is the only recovery artifact. The engine stamps
+`.minions-quarantine-protected` into that directory, and the central
+`shared.removeWorktree` primitive refuses to delete it. An operator must inspect
+and remove that quarantine manually after recovering the files.
+
 ### Layer 1b — `--no-optional-locks` on every status probe (load-bearing)
 
 `_statusPorcelainCmd()` emits `git --no-optional-locks status …`. Skips
@@ -289,7 +365,10 @@ layers.
 
 ## Periodic prune (W-mq5o6bvy000x7191)
 
-`pruneWorktreesPeriodic` runs `pruneOrphanWorktrees` (in-root) +
+`pruneWorktreesPeriodic` runs `reconcileStaleWorktreeDirectories`
+(physical directories absent from Git's registry),
+`reclaimMissingDirWorktrees` (registry entries with a missing backing
+directory), `pruneOrphanWorktrees` (in-root), and
 `pruneOrphanWorktreesFromGitRegistry` (out-of-root via
 `git worktree list --porcelain`) per project at
 `ENGINE_DEFAULTS.worktreePruneIntervalTicks` cadence — catches Windows
@@ -297,6 +376,36 @@ EPERM/EBUSY stragglers that the dispatch-end GC couldn't reap and sweeps
 the `git worktree list` registry for OUT-of-root entries the in-root
 scanner is blind to.
 
+The filesystem reconciliation pass is deliberately fail-closed and distinct
+from dispatch-oriented GC. It lists every repo sharing a configured worktree
+root before deleting anything; if any list fails, the whole shared root is
+left untouched and the failure is logged/reported in sweep diagnostics. This
+pass never deletes registered paths, but only `locked` / `initializing`
+registrations are protected from the downstream dispatch-oriented pruner.
+Unlocked registrations can therefore be removed there when unclaimed, while
+non-terminal SQL claims, pool/managed-process/keep-process anchors, detected
+CWD holders, protected quarantines, and unrelated infrastructure directories
+remain protected. Deletion requires either `.minions-worktree` or the narrow
+legacy proof used for old Windows residue: a `W-*` basename plus a `.git` file
+pointing inside one of the project's common `.git/worktrees` directories.
+Ordinary unregistered residue is eligible after 2h; unprotected
+`-quarantine-<epoch-ms>` residue after 24h. Protected quarantine directories
+remain until manual recovery because they are the only durable copy of work
+whose backup ref could not be created.
+
+`runCleanup` delegates its configured-root orphan pass to the same reconciler;
+the former fail-open duplicate scan and generic age/count-cap deletion are
+retired. Its remaining PR-terminal cleanup is narrower: only a currently
+registered, unlocked, marker-owned worktree whose PR is still merged or
+abandoned can be removed, after fresh SQL-live, process-anchor/CWD-holder, and
+protected-quarantine checks.
+
+Both removal pruners check exact persisted path ownership through
+`shared.isWorktreePathLive` before calling `removeWorktree`. A live claim is
+an expected `skipped` outcome, not a failed removal, and is retried on the next
+sweep after the dispatch becomes terminal. Aggregate logs report mutually
+meaningful `removed`, `skipped`, `preserved`, and `failed` counts.
+
 ### Scratch-dir skip and bounded reaper (PR #388)
 
 The worktree root (`<localPath>/../worktrees/`) is a **shared namespace**: it
@@ -331,7 +440,7 @@ When adding new code that enumerates the worktree root directory, apply
 `shared.isWorktreeRootInfraEntry(name)` to skip dot-prefixed entries before
 calling any `removeWorktree` path.
 
-### Ownership marker — out-of-root GC only touches engine worktrees (W-mqecdoot)
+### Ownership marker — periodic GC only touches engine worktrees (W-mqecdoot)
 
 A project repo's `git worktree list` includes EVERY worktree registered
 against it — including ones a developer created by hand
@@ -341,14 +450,35 @@ live dispatch / pool / managed-spawn, **deleting human worktrees
 mid-edit**. The fix: the engine stamps a `.minions-worktree` ownership
 marker (`shared.WORKTREE_OWNER_MARKER`) into every worktree it creates
 (`shared.writeWorktreeOwnerMarker`, called right after `git worktree add`
-in `engine.js#runWorktreeAdd`). `pruneOrphanWorktreesFromGitRegistry`
-now requires `shared.hasWorktreeOwnerMarker(path)` before evicting an
-out-of-root worktree — **no marker → foreign → kept and never
+in `engine.js#runWorktreeAdd`). Both in-root and out-of-root removal pruners
+require `shared.hasWorktreeOwnerMarker(path)` before eviction —
+**no marker → foreign → kept and never
 escalated** (fail-open: leak a dir rather than nuke unpushed work). The
 trailing `git worktree prune --expire=now` (drops registry entries whose
 dirs are already gone) still runs regardless of ownership. The marker is
 gitignored so it never shows up in any worktree's `git status`.
 
+`shared.removeWorktree` remembers whether the marker existed before removal.
+If git and filesystem fallbacks partially delete an owned worktree but leave a
+locked husk, it restores the marker so the next periodic sweep can retry.
+Previously unmarked paths are never marked by this recovery.
+
+### Checkout free-space preflight
+
+`engine.worktreeMinFreeSpaceBytes` defaults to 10 GiB (`0` disables) and is
+editable in Dashboard -> Settings -> Worker Pool & Worktrees. Allocation and a
+second spawn-time race check call `engine/worktree-preflight.js` before any
+`git worktree add`. The probe uses the nearest existing ancestor when the
+configured worktree root has not been created yet.
+
+Below the threshold, the existing dispatch remains pending with
+`_pendingReason: "worktree_low_disk_space"` and structured
+`_worktreeDiskPreflight` fields (`requiredBytes`, `availableBytes`,
+`worktreeRoot`, `probePath`, `checkedAt`, `message`). A statfs/probe error uses
+`worktree_disk_probe_failed` and also fails closed. Both paths write a deduped
+inbox alert, start no process or checkout, consume no retry, and are re-checked
+on every allocation tick.
+
 ### Locked-`initializing` missing-dir reclaim (W-mqifblkf00149df5)
 
 A third pruner, `worktree-gc.js#reclaimMissingDirWorktrees`, closes a
@@ -378,6 +508,11 @@ single `-f` errors `cannot remove a locked working tree`) followed by
    (`shared.isWorktreePathLive`, fail-open: skip/leak rather than nuke); and
 3. it is not the main checkout (`path === project root`).
 
+The missing-dir pass runs before either removal pruner mutates the shared
+porcelain snapshot. If a concurrent cleanup wins the race anyway, a failed
+remove is re-listed and treated as success only when the registration is
+already absent.
+
 The same `remove -f -f` reaper (`engine.js#pruneStaleWorktreeForBranch`) is
 also wired into **both** spawn-time worktree-creation recovery paths —
 `_branchOnRemote === true` AND the fresh-create `else` branch — so a
@@ -434,9 +569,12 @@ Windows-only; three layers, each fail-open:
 
 1. POSIX is a no-op (the `EBUSY` race is Windows-specific).
 2. Master switch `engine.statusProbeKillDescendantsWin32` (default ON).
-3. `shared.isWorktreePathLive(path, { excludeDispatchId })` must be false —
-   fail-open: on a live claim OR on a SQL error / throw the WHOLE reap is
-   SKIPPED (leak a worktree rather than nuke a live agent's unpushed work).
+3. `shared.isWorktreePathLive(path, { excludeDispatchId, excludeSpawnLeaseId? })`
+   must be false. Spawn-attempt-owned cleanup passes both exclusions, so the
+   dispatch row is excluded only when its persisted lease matches; a stale
+   attempt cannot exclude a successor row with the same dispatch id. Fail-open:
+   on a live claim OR on a SQL error / throw the WHOLE reap is SKIPPED (leak a
+   worktree rather than nuke a live agent's unpushed work).
    This check is **re-run at kill time** before Layer 2 (W-mqinlicl): the PEB
    probe can take several seconds, and liveness flips on the engine tick — a
    "not live" snapshot from the top of the function is unsafe to kill on.

package/engine/acp-transport.js

@@ -303,6 +303,7 @@ class Worker {
     this.runtime = resolveWorkerRuntime(runtime);
     this.id = id;
     this.model = model;
+    this.currentModel = null;
     this.effort = effort;
     this.mcpServers = mcpServers || [];
     this.mcpServersHash = mcpServersHash;