@yemi33/minions 0.1.2424 → 0.1.2426

package/docs/visual-evidence-ci.md

@@ -0,0 +1,103 @@
+# PR visual evidence CI
+
+The OPG GitHub workflow captures matched dashboard screenshots for pull requests that change visual dashboard inputs. It compares live base and head checkouts; it never compares a committed demo image with a live PR.
+
+## Triggering
+
+`Visual evidence capture` runs automatically when a PR changes:
+
+- `dashboard/**`
+- `dashboard-build.js`
+- `docs/capture-demos.js`
+- `test/seed-demo-data.js`
+
+Add the `visual-evidence` label to opt in a visual change outside that list. Removing the label removes the opt-in. Backend, test-only, prose-only, and documentation-only PRs do not start browsers unless explicitly labeled.
+
+## Capture contract
+
+The capture workflow:
+
+1. Resolves the exact PR, repository, base, and head tuple from the trusted `pull_request_target` event and records it with the workflow run ID and attempt. The request builder comes from the exact `github.workflow_sha` revision, so an older PR base that predates the controller records a `controller-not-on-base` opt-out instead of failing the plan.
+2. Captures and uploads BEFORE in a base-only job.
+3. Starts the separate head job only after BEFORE has been uploaded, then runs the untrusted dashboard in a capability-dropped container with a read-only root/source/controller and one writable marker-owned state mount. The trusted host owns the browser and AFTER output.
+4. Seeds marker-owned state directories with the same deterministic demo fixture.
+5. Starts each checkout on the same port and captures it with the base branch's canonical [`capture-demos.js`](capture-demos.js).
+6. Uses Chromium at 1400x900, dark theme, `en-US`, UTC, reduced motion, and a fixed browser time.
+7. Requires the same ten non-empty PNG names on both sides.
+
+Startup, fixture, and capture logs are retained with the images. Partial output is never presented as a successful comparison: a failed AFTER side fails the run, and a failed BEFORE side degrades the run to an explicitly-labelled AFTER-only publication (see [Degraded AFTER-only runs](#degraded-after-only-runs)).
+
+## Artifacts and PR summary
+
+GitHub Actions stores five artifacts keyed by PR number and full head SHA:
+
+- capture-request metadata
+- BEFORE PNG set
+- AFTER PNG set
+- BEFORE logs and `result.json`
+- AFTER logs and `result.json`
+
+Artifacts expire after **14 days**. Each upload replaces its same-run name on a rerun, so a later attempt refreshes all five artifacts instead of colliding with the prior attempt. The trusted publisher creates or updates one `github-actions[bot]` comment with BEFORE/AFTER artifact links. All publisher jobs serialize globally through GitHub Actions' multi-entry concurrency queue before mutating PR comments, so a newly queued publisher does not replace an already-pending publication. Each publisher also checks the authoritative workflow-run order before changing comments. Older runs and attempts are suppressed even when a newer opt-out run left no summary. Results for an obsolete head are suppressed when a current result exists; an already-posted result is marked stale when its head no longer matches. If the current PR diff no longer requests visual evidence, the old bot summary is removed.
+
+## Degraded AFTER-only runs
+
+`capture-before` checks out `github.event.pull_request.base.sha` and runs the **base branch's** seed and capture code, not the pull request's. A defect already merged to `main` therefore breaks the BEFORE side of every PR opened against that base — including the PR that repairs the base, which could otherwise never show a green check.
+
+The BEFORE side is consequently non-blocking:
+
+- `capture-before` carries `continue-on-error: true` and is named `Capture BEFORE (base, non-blocking)`, the same convention `pr-tests.yml` uses for its non-blocking `perf-tests` job. The failure surfaces as a warning annotation plus a job summary that names the base SHA and states the run is AFTER-only; it does not present a blocking red check on the PR.
+- `Upload BEFORE screenshots` uses `if-no-files-found: warn`, so a crashed capture that wrote zero PNGs is reported once by the capture step instead of raising a second hard error. `Upload BEFORE capture logs` deliberately stays `if-no-files-found: error` — the logs directory is always written and is what makes the failure diagnosable.
+- `capture-after` is gated on `!cancelled() && needs.plan.outputs.capture == 'true'` instead of a successful `capture-before`, so the head-side capture still runs and uploads. The plan gate is re-asserted directly because it is no longer inherited through a green BEFORE job, and `!cancelled()` keeps a run superseded by `cancel-in-progress` from spending a full Docker and Playwright capture.
+
+The publisher degrades in step. When the run concludes successfully and the BEFORE PNG set is the *only* missing artifact, `assessArtifacts` returns `status: 'after-only'` and the bot comment is titled **"Visual evidence: AFTER only (BEFORE capture failed)"**. It states that this is not a BEFORE/AFTER comparison, renders the BEFORE cell as `capture failed - no screenshots`, and links the BEFORE logs for diagnosis. Any other gap — a missing AFTER set, missing BEFORE logs, duplicate artifacts, or a genuinely failed run — still reports the full failure summary. A reviewer is never handed a half-capture presented as a matched pair.
+
+Nothing about the security posture changes: the controller and base checkout still run from the trusted base ref with `persist-credentials: false`, `Verify exact base checkout` is unchanged, and untrusted head code gains no execution privileges.
+
+## Security boundary
+
+The workflow definition and capture-request builder run from the exact trusted `github.workflow_sha` revision through `pull_request_target`; detection and capture execution remain pinned to the PR's trusted base SHA. If that historical base does not contain the controller, detection suppresses both browser jobs while the trusted workflow revision still records the opt-out request artifact. Neither planning path loads controller code from the untrusted head. The workflow has only `contents: read` and `pull-requests: read`, checkout credentials are not persisted, and no write-capable token is available. BEFORE and AFTER use separate runners, and AFTER cannot start until the immutable BEFORE artifact has uploaded. The head dashboard runs without the Actions process environment, host process namespace, controller checkout, screenshot output, or Docker socket; its source/controller mounts and container root are read-only. The sole writable bind mount is marker-owned `/state`, and the container runs as the host UID:GID that owns it. Secret-shaped variables and GitHub Actions control-file variables are removed from host capture child processes.
+
+Comment publication happens later in `visual-evidence-publish.yml`, triggered by `workflow_run`. That job checks out only the repository default branch and requires a `pull_request_target` run from the trusted base repository. It downloads and parses only the trusted plan job's capture-request JSON, then binds its repository, workflow, stable run ID, PR, base, head repository, base branch, and full head SHA to the live run before writing. A request retained from an earlier attempt is valid for a selective rerun of that same run ID, while metadata claiming a future attempt is rejected. The run's `head_sha` is the captured PR head; publication does not depend on the optional `workflow_run.pull_requests` association. Screenshot and log artifacts remain link-only and are never downloaded or executed by the publisher.
+
+## Base-controller failure mode
+
+Because the seeder (`test/seed-demo-data.js`) and Playwright controller (`docs/capture-demos.js`) always execute from the base checkout, a break in either one is only observable once it is on `main`: every subsequent BEFORE capture fails, for every PR, and no change on a PR branch can repair it — the PR's own copy is never executed. Both files are also visual paths, so even a PR that fixes them triggers the broken capture. Since `capture-before` is non-blocking, the visible symptom is that every PR degrades to an AFTER-only publication (see [Degraded AFTER-only runs](#degraded-after-only-runs)) until the fix lands. Recovery is to land the fix on `main` (admin bypass) and then push to the affected PRs so a fresh `pull_request_target` event picks up a base SHA that contains it. `test/unit/visual-evidence-ci.test.js` runs the seeder's full seeding body so this class of break fails PR Tests before it can reach `main`.
+
+## Local reproduction
+
+Start from a trusted checkout of the base branch, never the pull request/head checkout. Resolve the exact full base and head SHAs independently, then use two disposable worktrees and keep output outside both:
+
+```bash
+BASE_WORKTREE=../visual-base
+HEAD_WORKTREE=../visual-head
+OUTPUT_ROOT=../visual-output
+git worktree add --detach "$BASE_WORKTREE" <full-base-sha>
+git worktree add --detach "$HEAD_WORKTREE" <full-head-sha>
+test "$(git -C "$BASE_WORKTREE" rev-parse HEAD)" = "<full-base-sha>"
+test "$(git -C "$HEAD_WORKTREE" rev-parse HEAD)" = "<full-head-sha>"
+npm --prefix "$BASE_WORKTREE" ci --ignore-scripts
+npm --prefix "$BASE_WORKTREE" exec -- playwright install chromium
+node "${BASE_WORKTREE}/.github/scripts/run-visual-evidence.js" \
+  --dashboard-runtime docker \
+  --controller-root "$BASE_WORKTREE" \
+  --base-root "$BASE_WORKTREE" \
+  --head-root "$HEAD_WORKTREE" \
+  --base-sha <full-base-sha> \
+  --head-sha <full-head-sha> \
+  --output-root "$OUTPUT_ROOT"
+```
+
+The PNGs land in `../visual-output/{before,after}` and logs in `../visual-output/logs`. Docker is the default dashboard runtime so neither dashboard checkout executes in the host Node process. The host still executes the runner, fixture seeder, and Playwright controller, all from the exact base worktree; the runner verifies that controller checkout against `--base-sha` before mutating output. `--dashboard-runtime process` is an explicit opt-in for code you trust. The output root must be new, empty, or carry the runner's `.minions-visual-evidence-output` ownership marker, and it must not overlap either checkout or the controller in either direction. Reruns clear only the known generated subdirectories beneath a valid marker-owned root. Remove the disposable worktrees with the normal `git worktree remove` command after inspection.
+
+## Complementary in-description embeds (agent-authored)
+
+The CI workflow above is one of **two** complementary visual-evidence surfaces; it is not the only one:
+
+- **`Visual evidence capture` (this workflow)** — an automated, sandboxed BEFORE/AFTER comparison posted by `github-actions[bot]`. It is untouched by the agent flow and remains the trusted comparison of record.
+- **Agent-embedded screenshots (additive, W-mrz1yc79)** — when a Minions dispatch makes a meaningful **visual/UI change** (dashboard pages, slim-ux, Settings, work-item/PR/plan views, badges, layout/CSS), the agent proactively captures screenshots and embeds them directly in the PR **description** (`![view (after)](url)`), rather than relying only on the bot. Backend-only, engine-logic, text/prose-only, analysis, and docs changes get no screenshots.
+
+The agent embed path does **not** replace or modify the CI workflow — the two coexist. Mechanics the agent uses (full recipe in `playbooks/_pr-description-audit.md` → "Screenshot handling"):
+
+- **GitHub:** raw PNGs are saved under `agents/<id>/screenshots/` (never `git add`ed), published as assets on a dedicated per-PR prerelease (`gh release create pr-<num>-visual … --prerelease`, or `gh release upload … --clobber` on re-dispatch), and embedded via each asset's `browser_download_url`. This works on private repos and never commits PNGs to the source branch. The upload uses a per-command `GH_TOKEN` for the repo owner's account (`opg-microsoft` → `yemishin_microsoft`, `yemi33` → `yemi33`) and never runs `gh auth switch`.
+- **Azure DevOps:** `PUT /pullRequests/<id>/attachments/<filename>` with the PNG bytes, then reference the returned URL.
+- **Degrade gracefully:** if the dev server won't start, the route 404s, Playwright is unavailable, or the upload fails, the agent skips without failing the work item and records the reason under `meta.descriptionAudit`.

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;