@yemi33/minions 0.1.2380 → 0.1.2382

package/docs/live-checkout-mode.md

@@ -20,34 +20,34 @@ For these repos, the operator usually already has one canonical checkout that bu
 
 ## Contract (six guarantees)
 
-Live mode is opinionated about what the engine will and will not do to the operator's tree. The contract has six guarantees; the engine enforces all six and fails dispatches that would violate them.
+Live mode is opinionated about what the engine will and will not do to the operator's tree. The contract has six guarantees; the engine enforces them by recovering when explicitly configured, otherwise leaving blocked work pending or failing closed.
 
 ### 1. Per-project mutating-concurrency cap of 1
 
-Only one mutating dispatch (fix / implement / review / test / verify / decompose / docs) runs per live-mode project at a time. Read-only types (meeting / ask / explore / plan / plan-to-prd) are excluded from the cap because they never write to disk.
+Only one worktree-requiring dispatch (fix / build-fix-complex / implement / review / test / verify / decompose / setup / docs) runs per live-mode project at a time. Read-only types (meeting / ask / explore / plan / plan-to-prd) are excluded from the cap because they never write to disk.
 
 Implementation: `engine.js` builds a `liveProjectsInUse` set from the active dispatch list at every allocation pass and per-tick re-annotation; pending items whose project is already in the set are skipped with a `skipReason` and re-tried on the next tick. (`engine.js:7198`, `engine.js:7460`.)
 
-### 2. Refuse-on-dirty (engine never resets the operator tree)
+### 2. Dirty-tree policy
 
-**W-mrcifup2000c218a — detected at ALLOCATION time first.** Before a live-mode work item is even dispatched, `engine.js`'s dispatch-existing-pending loop calls `engine/live-checkout.js#checkLiveCheckoutDirty` (a cheap, read-only, non-mutating `git status --porcelain=v1 -b` probe — same command, same auto-cleanable-artifact allowance as the in-spawn check below) in the same pass that already gates on `live_checkout_busy`. A dirty hit stamps `_pendingReason: 'live_checkout_dirty'` on the pending item and `continue`s — **no dispatch attempt, no retry consumed, no failure recorded** — exactly like the busy gate. The item is re-checked every tick and dispatches normally the moment the tree is clean. A `live-checkout-dirty-<wi-id>` inbox alert is written (deduped per day, same as the in-spawn alert below) so a persistent dirty condition is still surfaced to a human even though the WI itself stays pending.
+**W-mrcifup2000c218a — detected at ALLOCATION time first.** The allocator runs a cheap read-only dirty probe. When both auto-stash and auto-reset are disabled, a dirty hit stamps `_pendingReason: 'live_checkout_dirty'`, writes a deduped inbox alert, and leaves the WI pending without consuming a retry. When either recovery policy is enabled, dirt alone does not block allocation so `spawnAgent` can perform the configured recovery; the independent stale-base precheck still blocks committed base drift.
 
 The in-spawn check below remains as a **defense-in-depth fallback** for the race window between the allocation-time probe and the actual git operations inside `spawnAgent` (e.g. the tree goes dirty in the few seconds between the pre-check and the spawn) — it is now the *exception* path, not the common path.
 
-Before spawning, `engine/live-checkout.js#prepareLiveCheckout` runs `git status --porcelain` from `project.localPath`. Any output (staged, unstaged, untracked) **returns** an explicit `{ ok:false, reason:'dirty', dirtyFiles:[…] }` result (it does NOT throw), which refuses the dispatch immediately:
+Before spawning, `engine/live-checkout.js#prepareLiveCheckout` first refuses an in-progress repository operation or detached HEAD, captures the original ref, then runs `git status --porcelain` from `project.localPath`. Any dirty output (staged, unstaged, untracked) **returns** an explicit `{ ok:false, reason:'dirty', dirtyFiles:[…] }` result unless explicit reset recovery is requested. `spawnAgent` uses that result to run auto-stash first and optional auto-reset second. Only when configured recovery is unavailable or fails does the confirmed-dirty result become a dispatch refusal:
 
 - Non-retryable `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` (added to `engine/dispatch.js`'s `neverRetry` set so the dispatcher never re-spawns mechanically). **Reserved for this confirmed-dirty result only** — a thrown helper/git error is `LIVE_CHECKOUT_FAILED`, see below (#305). **Auto-cleanup exception (W-mqzmkoqt000hbca2, #582):** when `liveCheckoutAutoReset` or `liveCheckoutAutoStash` is enabled (per-project or fleet-wide), `spawnAgent` treats the dirty refusal as retryable instead — the engine re-cleans the tree on every attempt, so the two-strike cap below is skipped and the dispatch keeps retrying up to the normal `maxRetries` cap. The `dispatch.js` `neverRetry` entry is kept only as a defensive fallback for callers that omit the explicit `agentRetryable` override.
 - Inbox alert written via `dispatch.writeInboxAlert('live-checkout-dirty-<wi-id>', body)`. The body lists the dirty files verbatim from `git status --porcelain`.
 - Work item stamped with `_pendingReason: 'live_checkout_dirty'` so the dashboard surfaces the block.
 - Completion summary: `live-checkout refused: N dirty file(s) in <localPath>`.
 
-The engine never calls `git reset --hard`, `git clean -fd`, or any other state-mutating command against the operator's checkout — not at spawn, not at cleanup, not on timeout, not on engine restart. The dispatch-scoped cleanup paths (`worktreePool.returnToPool`, `worktree-gc.gcDispatchWorktreeIfOrphan`, `_quarantineDirtyWorktree`) are naturally no-ops because `worktreePath` stays `null` end-to-end (`engine.js:1219`). The **periodic** worktree GC, however, is NOT `worktreePath`-gated — it derives its targets from `git worktree list --porcelain`, which for a live project returns the operator's *own* primary checkout. So `engine/cleanup.js#runPeriodicWorktreeSweep` now **filters out live-checkout projects entirely** (`shared.isLiveCheckoutProject`) before handing the list to the three pruners (PL-live-checkout-reliability-hardening), keeping the operator's real checkout out of the GC decision surface rather than relying only on the pruners' path-equality + ownership-marker gates. (The one **opt-in** exception is auto-stash — see [2b](#2b-opt-in-auto-stash-on-dirty-w-mqtvnnj1000357fa) — which the operator explicitly enables and which the engine never reverses on the operator's behalf.)
+Outside the explicit auto-stash and auto-reset policies, the engine never resets, cleans, or stashes the operator checkout. Dispatch-scoped cleanup paths are no-ops because `worktreePath` stays null, and periodic worktree GC filters live-checkout projects out entirely.
 
-#### 2b. Opt-in auto-stash on dirty (W-mqtvnnj1000357fa)
+#### 2b. Auto-stash on dirty (W-mqtvnnj1000357fa)
 
-By default the dirty refusal above stands. When the operator opts in, the engine instead **stashes** the dirty changes so the dispatch can proceed without manual intervention:
+Auto-stash is **ON by default**. The engine stashes dirty changes so dispatch can proceed without manual intervention; operators can opt out per project or fleet-wide:
 
-- **Enable** via per-project `project.liveCheckoutAutoStash: true` (takes priority) or the fleet-wide fallback `engine.liveCheckoutAutoStash: true` (default `false`). Resolution is `engine/live-checkout.js#resolveLiveCheckoutAutoStash` — an explicit per-project boolean wins; otherwise the engine value applies; otherwise `false`. Both are surfaced as Settings toggles (the per-project control is a tri-state *Use fleet default / On / Off* select; the fleet-wide one lives under **Settings → Worktrees**).
+- Configure via per-project `project.liveCheckoutAutoStash` (takes priority) or fleet-wide `engine.liveCheckoutAutoStash` (default `true`). Both are surfaced in Settings.
 - When enabled and the tree is dirty, `spawnAgent` delegates the whole flow to `engine/live-checkout.js#applyLiveCheckoutAutoStash`, which calls `performLiveCheckoutAutoStash` to run `git stash push --include-untracked -m "minions-auto-stash-<dispatchId>-<timestamp>"` in `project.localPath` (`--include-untracked` so the `??` files that `git status --porcelain` counts as dirty are parked too). The stash git command runs **outside any file lock**.
 - On stash **success** the helper re-runs `prepareLiveCheckout` (the tree is now clean), clears any stale `_pendingReason: 'live_checkout_dirty'` stamp (via the injected `clearDirtyStamp` callback), writes a `live-checkout-autostash-<wi-id>` inbox note with the stash name + manual-pop guidance, and returns `{ outcome:'stashed', liveResult }` so dispatch proceeds. If the re-preflight throws, it returns `{ outcome:'threw', error }` and `spawnAgent` fails the dispatch as `LIVE_CHECKOUT_FAILED`.
 - On stash **failure** the error is surfaced (logged, never swallowed), the helper returns `{ outcome:'unchanged', liveResult }`, and the dispatch falls through to the normal retry-once-then-fail dirty path above.
@@ -61,25 +61,26 @@ A thrown error from `prepareLiveCheckout` — a required-arg/ref-validation guar
 
 #### 2b. Opt-in auto-reset on dirty (`liveCheckoutAutoReset`, W-mqvejug6000eeb20)
 
-By default the dirty tree refusal (Guarantee 2) is terminal — the engine never touches the operator's uncommitted work. **Opt in** to automatic recovery with `liveCheckoutAutoReset`. When enabled, a dirty live tree is **force-reset to the remote** instead of refusing the dispatch:
+Auto-stash is the default non-destructive recovery. `liveCheckoutAutoReset` is an additional **opt-in, destructive fallback** used only when auto-stash is disabled, skipped, or fails and the tree remains dirty. It removes uncommitted WIP without changing the current branch or any commit:
 
 1. `prepareLiveCheckout` detects the dirty tree (same porcelain preflight as Guarantee 2).
 2. It resolves the effective flag via `shared.resolveLiveCheckoutAutoReset(project, engine)` — **per-project `project.liveCheckoutAutoReset` (boolean) wins**, else the fleet-wide `engine.liveCheckoutAutoReset`, else `false`. (engine.js does not thread project/engine config into the helper, so the production path self-resolves by loading `config.json` and matching the project by `localPath`; it **fails closed** to `false` on any config read error so a glitch can never silently trigger a destructive reset.)
-3. If ON: `git fetch origin` + `git reset --hard origin/<branch>`, then **re-run the porcelain preflight once**. If the tree is now clean, dispatch proceeds normally. If the reset failed or the tree is *still* dirty, it falls back to the safe `{ ok:false, reason:'dirty' }` refusal — the engine never dispatches onto an unexpected tree.
-4. On a successful reset it writes a single `live-checkout-autoreset-<wiId>` inbox note listing **exactly which paths were discarded**, so the operator can recover them from `git reflog` / `git fsck --lost-found`.
+3. Before mutation, `prepareLiveCheckout` refuses an in-progress merge/rebase/cherry-pick/revert/bisect or detached HEAD.
+4. If ON: `git reset --hard HEAD` discards tracked index/worktree changes and `git clean -fd` removes ordinary untracked files. The helper then **always re-runs the porcelain preflight once**, even when either command reports an error, because a failed command may have partially changed the tree. If the tree is verified clean, dispatch proceeds normally. Otherwise it returns the safe `{ ok:false, reason:'dirty' }` refusal with the actual remaining paths when available.
+5. Every destructive attempt writes a uniquely keyed `live-checkout-autoreset-<attempt>-<dispatch-or-WI-id>` inbox note recording each command outcome plus the before/after dirty paths, including partial failures.
 
-This is **DESTRUCTIVE** — it permanently discards the operator's uncommitted changes in the live checkout. As of W-mqzbbhn2 it was **ON by default**; as of **W-mrawgw4q000a6bff it is OFF by default again** (`ENGINE_DEFAULTS.liveCheckoutAutoReset: false`) — the destructive-by-default behavior caused unwanted data loss when an operator had legitimate local drift they expected the engine to leave alone. Set `liveCheckoutAutoReset: true` (per-project or fleet-wide) to opt back in to reset-to-remote recovery.
+This is **DESTRUCTIVE** — tracked WIP and untracked files can be permanently unrecoverable. It does **not** fetch, switch branches, reset to a remote ref, or erase local commits; the stale-base guard still refuses a local base with unpushed committed drift. As of W-mqzbbhn2 it was **ON by default**; as of **W-mrawgw4q000a6bff it is OFF by default again** (`ENGINE_DEFAULTS.liveCheckoutAutoReset: false`). Set `liveCheckoutAutoReset: true` (per-project or fleet-wide) to opt back in.
 
 - **Fleet-wide:** Dashboard → Settings → `Live-checkout auto-reset (fleet-wide)` (`engine.liveCheckoutAutoReset`).
 - **Per-project override:** set `liveCheckoutAutoReset: true|false` on the project object in `config.json` (see the config snippet under *Enabling live mode*). A per-project boolean overrides the fleet-wide default for that project. *(Per-project Settings-UI persistence is deferred — the per-project override is config.json-only for now.)*
 
-**Precedence when both `liveCheckoutAutoStash` and `liveCheckoutAutoReset` are enabled (W-mrawgw4q000a6bff).** `engine.js spawnAgent` now tries the **non-destructive** auto-stash first: it resolves `liveCheckoutAutoStash` up front and, if enabled, calls the initial `prepareLiveCheckout` with `autoReset` forced `false` so the destructive reset never runs before stash gets a chance. `applyLiveCheckoutAutoStash` then attempts the stash (see [2b auto-stash](#2b-opt-in-auto-stash-on-dirty-w-mqtvnnj1000357fa) above) and its own internal re-preflight also forces `autoReset: false`. Only if the stash itself fails or was skipped (`outcome:'unchanged'`) **and** the tree is still confirmed dirty **and** `resolveLiveCheckoutAutoReset` resolves `true` does `spawnAgent` invoke `prepareLiveCheckout` a second time with `autoReset: true` as an explicit, last-resort destructive fallback. **Behavior change:** previously (reset-before-stash, reset ON by default) the common both-enabled case force-reset the branch to origin on every dirty dispatch; now the branch is only synced to origin when stash fails — the common case just parks the dirty changes non-destructively and leaves the branch where it was. There is deliberately **no automatic `git merge --ff-only origin/<branch>`** after a successful stash — auto-stash's contract is "park changes so dispatch proceeds," not "sync to origin"; that stronger guarantee remains `liveCheckoutAutoReset`'s job, available as an explicit opt-in fallback.
+**Precedence when both `liveCheckoutAutoStash` and `liveCheckoutAutoReset` are enabled (W-mrawgw4q000a6bff).** `engine.js spawnAgent` tries the **non-destructive** auto-stash first: it resolves `liveCheckoutAutoStash` up front and, if enabled, calls the initial `prepareLiveCheckout` with `autoReset` forced `false`. `applyLiveCheckoutAutoStash` attempts the stash and its own internal re-preflight also forces `autoReset: false`. Only if the stash fails or is skipped (`outcome:'unchanged'`), the tree remains dirty, and `resolveLiveCheckoutAutoReset` resolves `true` does `spawnAgent` invoke `prepareLiveCheckout` again with `autoReset: true`. Neither recovery policy syncs the branch to origin.
 
 #### 2c. Stale `.git/index.lock` self-heal (W-mr3tayu4)
 
 Before any preflight git command runs, `prepareLiveCheckout` calls the shared, age-gated `shared.removeStaleIndexLock(localPath)` to clear a leftover `.git/index.lock` from a crashed/killed git process. Live mode never resets/cleans the operator tree, so nothing else would clear it, and — since `LIVE_CHECKOUT_FAILED` is retryable — every automatic retry used to hit the same stale lock and fail identically forever until an operator deleted it by hand. The remover only touches locks older than 5 minutes, so a lock held by a currently-running git process is never removed out from under it. `engine.js`'s own worktree-mode lock cleanup now delegates to the same shared helper.
 
-### 3. No auto-pull, no `--force`, no fast-forward
+### 3. No implicit remote sync or force checkout
 
 After the clean-tree check, `prepareLiveCheckout`:
 
@@ -247,7 +248,7 @@ This mirrors, in CC-instruction form, what `prepareLiveCheckout` enforces engine
 
 1. Open the Minions dashboard → **Settings** → **Projects** → expand the target project.
 2. Set **Checkout mode** → **Live checkout**. A yellow warning chip appears immediately:
-   > ⚠ Live mode: dispatches run directly in this repo's checkout. Only one mutating dispatch runs at a time. Dirty working trees block dispatch — commit or stash before running.
+   > ⚠ Live mode: dispatches run directly in this repo's checkout. Only one mutating dispatch runs at a time. Dirty-tree behavior follows the auto-stash/reset settings.
 3. Click **Save**. The dashboard POSTs the change through `mergeSettingsConfigUpdate`; `shared.validateCheckoutMode` rejects anything other than `'worktree'` or `'live'` with HTTP 400 (the legacy `'isolated'` value is silently coerced to `'worktree'`).
 
 ### Enabling live mode (config.json)
@@ -258,10 +259,9 @@ This mirrors, in CC-instruction form, what `prepareLiveCheckout` enforces engine
     "name": "android-aosp",
     "localPath": "/home/yemi/aosp",
     "checkoutMode": "live",
-    // "liveCheckoutAutoReset": true,  // OPT-IN, DESTRUCTIVE — on a dirty tree,
-    //   git fetch origin + git reset --hard origin/<branch> instead of refusing
-    //   (discards uncommitted operator changes; logs a live-checkout-autoreset
-    //   inbox note). Overrides the fleet-wide engine.liveCheckoutAutoReset.
+    // "liveCheckoutAutoReset": true,  // OPT-IN, DESTRUCTIVE fallback — if
+    //   auto-stash is disabled/fails, reset tracked WIP to HEAD and clean
+    //   untracked files (preserves branch + commits; logs an inbox note).
     // …
   }]
 }
@@ -269,11 +269,30 @@ This mirrors, in CC-instruction form, what `prepareLiveCheckout` enforces engine
 
 Absent / `null` / `''` reads as `'worktree'` (the default) — explicit is preferred. A legacy `"worktreeMode": "live"` is still honored (and `"worktreeMode": "isolated"` reads as `'worktree'`), but new configs should use `checkoutMode`.
 
+### Enabling hybrid validation
+
+Hybrid mode routes only selected canonical work-item types on the live checkout; every unselected type uses an isolated worktree. The normal configuration selects `test` and optionally creates one PR-targeted validation WI automatically:
+
+```jsonc
+{
+  "projects": [{
+    "name": "android-aosp",
+    "checkoutMode": "live",
+    "liveValidation": {
+      "type": "test",
+      "autoDispatch": true
+    }
+  }]
+}
+```
+
+`type` may be a string or array, but every entry must be a live-capable canonical `WORK_TYPE`. `build-and-test` is a playbook alias and is normalized to `test` only for backward compatibility. `autoDispatch` must be boolean and requires `test` in the configured types; the generated WI has type `test`, carries structured `targetPr` / `pr_id` / URL-reference fields, targets the source PR branch, and renders the `build-and-test` playbook. Successful direct PR-backed `fix` and `build-fix-complex` dispatches, including human-feedback fixes, use the dispatch ID as their dedup key and do not add a nonexistent WI dependency.
+
 ### Enabling auto-stash on dirty (config.json)
 
 ```jsonc
 {
-  // Fleet-wide fallback (default false) — applies to every live project that
+  // Fleet-wide fallback (default true) — applies to every live project that
   // doesn't set its own override.
   "engine": { "liveCheckoutAutoStash": true },
   "projects": [{
@@ -287,11 +306,11 @@ Absent / `null` / `''` reads as `'worktree'` (the default) — explicit is prefe
 }
 ```
 
-With auto-stash on, a dirty tree is `git stash push --include-untracked`'d before dispatch instead of refusing (see [2b](#2b-opt-in-auto-stash-on-dirty-w-mqtvnnj1000357fa)). The engine never pops the stash — recover with `git stash pop` manually.
+With auto-stash on, a dirty tree is `git stash push --include-untracked`'d before dispatch instead of refusing (see [2b](#2b-auto-stash-on-dirty-w-mqtvnnj1000357fa)). The engine never pops the stash — recover with `git stash pop` manually.
 
 ### Recovering from `live_checkout_dirty` refusal
 
-When dispatch is blocked by a dirty tree, the dashboard shows the work item as pending with `_pendingReason: 'live_checkout_dirty'` and an inbox alert lists the dirty files. (To make the engine *auto-recover* from this instead of refusing — at the cost of discarding the dirty changes — enable [opt-in auto-reset](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).) From the project checkout:
+When dispatch is blocked by a dirty tree, the dashboard shows the work item as pending with `_pendingReason: 'live_checkout_dirty'` and an inbox alert lists the dirty files. Enable auto-stash for non-destructive automatic recovery; enable [auto-reset](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20) only as a destructive fallback. To recover manually from the project checkout:
 
 ```bash
 # Option A — preserve work for later
@@ -305,7 +324,7 @@ git checkout -- .
 git clean -fd
 ```
 
-Then re-dispatch. The next tick will re-pick the pending work item; nothing else needs clearing on the engine side (the inbox alert is informational only).
+The next tick automatically re-picks the pending work item; nothing needs clearing on the engine side.
 
 ### Branch-leak mitigation
 
@@ -344,9 +363,9 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | `engine/shared.js` — `CHECKOUT_MODES`, `validateCheckoutMode`, `resolveCheckoutMode`, `isLiveCheckoutProject` | Enum + validator + back-compat resolver (P-a3f9b201; consolidated W-mqiaw974). |
 | `engine/shared.js` — `resolveLiveCheckoutAutoReset` + `ENGINE_DEFAULTS.liveCheckoutAutoReset` | Pure precedence resolver (per-project boolean > fleet-wide engine default > false) + the fleet-wide default (OFF as of W-mrawgw4q000a6bff — was ON as of W-mqzbbhn2). Gates the dirty-tree auto-reset in `prepareLiveCheckout` (W-mqvejug6000eeb20); in `engine.js spawnAgent` only fires as a fallback after auto-stash fails/is disabled (W-mrawgw4q000a6bff). |
 | `engine/shared.js` — `resolveSpawnPaths` | Returns `{ cwd: localPath, worktreeRootDir: null, liveMode: true }` for live projects (P-a3f9b202). |
-| `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper: dirty check, mid-operation / detached-HEAD preflight (incl. `BISECT_LOG`; throw-on-git-dir-failure; exit-1-only detached), original-ref capture, **already-on-branch fast path**, `refs/heads/<branch>` existence check, branch resolution from HEAD (no fetch — issue #226), **no-half-switch + `blob-fetch`/`worktree-conflict` classification** for partial-clone hydration failures and cross-worktree branch conflicts, **opt-in dirty auto-reset** (`git fetch origin` + `reset --hard origin/<branch>` + re-check + `live-checkout-autoreset-<wiId>` note when `liveCheckoutAutoReset` is on), **50 MB git maxBuffer** (P-a3f9b203; preflight + capture P-b2e8d4a6; hardening PL-live-checkout-reliability-hardening; auto-reset + maxBuffer W-mqvejug6000eeb20). |
+| `engine/live-checkout.js` — `prepareLiveCheckout` | Pure helper by default: pre-mutation mid-operation / detached-HEAD preflight, original-ref capture, dirty check, **already-on-branch fast path**, `refs/heads/<branch>` existence check, branch resolution from HEAD (no fetch — issue #226), **no-half-switch + `blob-fetch`/`worktree-conflict` classification**, and opt-in destructive WIP cleanup (`reset --hard HEAD` + `clean -fd` + re-check + audit note) that preserves the branch and committed history. Git probes use a **50 MB maxBuffer**. |
 | `engine/live-checkout.js` — `restoreLiveCheckoutAtDispatchEnd` | Dispatch-end auto-restore (plain `git checkout <originalRef>`, never `--force`/reset/clean/stash, best-effort) + **self-healing dirty recovery** (auto-commit agent WIP onto the agent branch) + `live-checkout-failed-<dispatchId>` terminal-failure alert + `live-checkout-branch-<dispatchId>` fallback notify (now also on unexpected restore errors) (P-d9e6b2c4; self-heal PL-live-checkout-reliability-hardening). |
-| `engine/live-checkout.js` — `resolveLiveCheckoutAutoStash`, `performLiveCheckoutAutoStash`, `applyLiveCheckoutAutoStash` | Opt-in auto-stash: resolver (per-project boolean wins, else `engine.liveCheckoutAutoStash`, else false) + `git stash push --include-untracked` runner returning `{ ok, stashMessage, error? }` (never throws on git failure) + the `applyLiveCheckoutAutoStash` orchestrator (stash → re-preflight → clear retry stamp → operator inbox note) returning a `{ outcome:'unchanged'\|'stashed'\|'threw' }` discriminant. Engine never auto-pops (W-mqtvnnj1000357fa). |
+| `engine/live-checkout.js` — `resolveLiveCheckoutAutoStash`, `performLiveCheckoutAutoStash`, `applyLiveCheckoutAutoStash` | Auto-stash resolver (per-project boolean, then fleet setting, then default true) + `git stash push --include-untracked` runner + stash/re-preflight orchestration. Engine never auto-pops (W-mqtvnnj1000357fa). |
 | `engine/live-checkout.js` — `maybeRestoreLiveCheckoutFromRecord` | Shared wrapper that fires the dispatch-end restore from a persisted dispatch record; used by `cli.js` + both `timeout.js` reaping paths so a restart-spanning live dispatch is never stranded (PL-live-checkout-reliability-hardening). |
 | `engine.js` — `spawnAgent` live-mode block | Calls `prepareLiveCheckout`, delegates opt-in auto-stash to `applyLiveCheckoutAutoStash` on a dirty tree (W-mqtvnnj1000357fa), handles dirty / throw branches, gates `git worktree add` on `!liveMode` (P-a3f9b204). |
 | `engine.js` — `spawnAgent` mid-op / detached-HEAD refusal block | Emits `LIVE_CHECKOUT_MID_OPERATION`, writes `live-checkout-blocked-<wi-id>` alert, stamps `_pendingReason: 'live_checkout_mid_operation'` / `'live_checkout_detached_head'` (P-c5a1f3b8). |

package/docs/worktree-lifecycle.md

@@ -77,6 +77,15 @@ distinguishes the **original worktree-preflight issue** from a
 
 ## Quarantine path (dirty / divergent)
 
+Before quarantine, a reused worktree that is filesystem-clean and strictly
+ahead of `origin/<branch>` is pushed fast-forward to origin. Dispatch close
+and stale-orphan cleanup run the same preservation check before pool return or
+worktree removal. Dirty trees and branches confirmed behind origin retain the
+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**.
+
 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

package/engine/claude-md-context.js

@@ -0,0 +1,195 @@
+/**
+ * engine/claude-md-context.js — CLAUDE.md propagation for non-Claude runtimes.
+ *
+ * W-mrdon0pe000l045a. CLAUDE.md auto-discovery is a Claude-Code-CLI-only
+ * convention (the claude binary reads CLAUDE.md itself at startup). Copilot and
+ * Codex have NO equivalent auto-load, so repo-authored CLAUDE.md files — which
+ * frequently carry load-bearing "must be kept in sync" rules and name blessed
+ * tooling — are structurally invisible to a Copilot/Codex-based fleet.
+ *
+ * This module discovers the *nearest applicable* CLAUDE.md files for a dispatch
+ * (bounded walk-UP from path hints toward the project root — NOT a full monorepo
+ * walk) and renders them into a prompt block. engine/playbook.js injects that
+ * block as a "Project instructions (CLAUDE.md)" context layer, gated on the
+ * runtime capability `claudeMdNativeDiscovery` (skip when true → Claude) and the
+ * `propagateClaudeMdForNonClaudeRuntimes` config flag.
+ *
+ * The whole point is to be CHEAP: it only stats CLAUDE.md at each ancestor
+ * directory of a small set of hint dirs (capped depth + capped file count), so
+ * it never walks a huge monorepo like office/src.
+ *
+ * This module is pure file discovery + string building — no engine state, no
+ * locking, no writes.
+ */
+
+const fs = require('fs');
+const path = require('path');
+const { truncateTextBytes, ENGINE_DEFAULTS } = require('./shared');
+
+const CLAUDE_MD_FILENAME = 'CLAUDE.md';
+// Cap the number of CLAUDE.md files collected across all hints — defense against
+// a dispatch with many path hints spread across a deep tree.
+const MAX_FILES = 8;
+// Cap the walk-up depth from any single hint dir — defense for pathological deep
+// Windows paths so a single hint can't spin the loop unbounded.
+const MAX_WALK_DEPTH = 24;
+// Byte cap for the whole injected block. Reuses the same budget the sibling
+// notes / agent-memory context layers use (maxNotesPromptBytes), so CLAUDE.md
+// propagation can never balloon a prompt on a large monorepo.
+const DEFAULT_MAX_BYTES = ENGINE_DEFAULTS.maxNotesPromptBytes;
+
+function _pathEq(a, b) {
+  if (process.platform === 'win32') return a.toLowerCase() === b.toLowerCase();
+  return a === b;
+}
+
+// Is `target` inside (or equal to) `root`?
+function _isWithin(root, target) {
+  const rel = path.relative(root, target);
+  return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
+}
+
+/**
+ * Normalize a hint (a file OR directory, relative-to-root OR absolute) into an
+ * absolute directory contained within `root`. Returns null when the hint
+ * escapes the project root (path traversal guard). Non-existent hints are still
+ * resolved structurally (extension ⇒ file ⇒ parent dir; otherwise dir).
+ */
+function _hintToDir(root, hint) {
+  if (!hint || typeof hint !== 'string' || !hint.trim()) return null;
+  const cleaned = hint.trim();
+  let abs = path.isAbsolute(cleaned) ? cleaned : path.join(root, cleaned);
+  abs = path.resolve(abs);
+  if (!_isWithin(root, abs)) return null;
+  try {
+    const st = fs.statSync(abs);
+    if (st.isDirectory()) return abs;
+    return path.dirname(abs);
+  } catch {
+    // Doesn't exist on disk — infer file vs dir from a trailing extension.
+    return path.extname(abs) ? path.dirname(abs) : abs;
+  }
+}
+
+/**
+ * Discover CLAUDE.md files by walking UP from each hint directory to the project
+ * root, plus the project root itself as a guaranteed fallback. Returns entries
+ * ordered nearest-first (deepest directory first, project root last) so the
+ * caller renders "nearest wins" — the most specific instructions lead.
+ *
+ * @param {{ projectRoot: string, pathHints?: string[] }} opts
+ * @returns {{ absPath: string, relPath: string, depth: number }[]}
+ */
+function discoverClaudeMdFiles({ projectRoot, pathHints = [] } = {}) {
+  if (!projectRoot || typeof projectRoot !== 'string') return [];
+  const root = path.resolve(projectRoot);
+  try { if (!fs.statSync(root).isDirectory()) return []; } catch { return []; }
+
+  // Starting dirs: each valid hint dir, then the root itself (fallback so the
+  // project-root CLAUDE.md is always considered even with zero hints).
+  const startDirs = [];
+  for (const h of Array.isArray(pathHints) ? pathHints : []) {
+    const d = _hintToDir(root, h);
+    if (d) startDirs.push(d);
+  }
+  startDirs.push(root);
+
+  const found = new Map(); // absPath -> { depth, rel }
+  for (const start of startDirs) {
+    let dir = start;
+    let steps = 0;
+    while (steps <= MAX_WALK_DEPTH) {
+      const candidate = path.join(dir, CLAUDE_MD_FILENAME);
+      if (!found.has(candidate)) {
+        try {
+          if (fs.statSync(candidate).isFile()) {
+            const rel = path.relative(root, dir);
+            const depth = (rel === '' || rel === '.') ? 0 : rel.split(/[\\/]/).length;
+            found.set(candidate, { depth });
+          }
+        } catch { /* no CLAUDE.md at this level */ }
+      }
+      if (_pathEq(dir, root)) break;      // stop at project root (never above)
+      const parent = path.dirname(dir);
+      if (_pathEq(parent, dir)) break;    // filesystem-root guard
+      if (!_isWithin(root, parent)) break;
+      dir = parent;
+      steps++;
+    }
+  }
+
+  const entries = Array.from(found.entries()).map(([absPath, meta]) => ({
+    absPath,
+    relPath: (path.relative(root, absPath) || CLAUDE_MD_FILENAME).replace(/\\/g, '/'),
+    depth: meta.depth,
+  }));
+  // nearest-first: deepest dir first; stable tiebreak on relPath for determinism.
+  entries.sort((a, b) => (b.depth - a.depth) || a.relPath.localeCompare(b.relPath));
+  return entries.slice(0, MAX_FILES);
+}
+
+/**
+ * Build the CLAUDE.md propagation block (inner content, no outer header/fence —
+ * engine/playbook.js owns those). Reads each discovered file, labels it by its
+ * repo-relative path, and truncates to stay within `maxBytes` total. Returns
+ * `{ block, files }` where `block` is '' when nothing was found or all files
+ * were empty.
+ *
+ * @param {{ projectRoot: string, pathHints?: string[], maxBytes?: number }} opts
+ */
+function buildClaudeMdPropagationBlock({ projectRoot, pathHints = [], maxBytes = DEFAULT_MAX_BYTES } = {}) {
+  const files = discoverClaudeMdFiles({ projectRoot, pathHints });
+  if (files.length === 0) return { block: '', files: [] };
+
+  const cap = Math.max(256, Number(maxBytes) || DEFAULT_MAX_BYTES);
+  const parts = [];
+  const included = [];
+  let used = 0;
+
+  for (const f of files) {
+    let content;
+    try { content = fs.readFileSync(f.absPath, 'utf8'); } catch { continue; }
+    if (!content || !content.trim()) continue;
+
+    const heading = `\n\n### ${f.relPath}\n\n`;
+    const headingBytes = Buffer.byteLength(heading, 'utf8');
+    const remaining = cap - used - headingBytes;
+    if (remaining <= 0) break; // no room even for the next heading
+
+    const body = truncateTextBytes(content, remaining, '\n\n_...CLAUDE.md truncated (read the full file if needed)_');
+    parts.push(heading + body);
+    used += headingBytes + Buffer.byteLength(body, 'utf8');
+    included.push(f.relPath);
+    if (used >= cap) break;
+  }
+
+  if (parts.length === 0) return { block: '', files: [] };
+  return { block: parts.join('').replace(/^\n+/, ''), files: included };
+}
+
+/**
+ * Does the named runtime auto-discover CLAUDE.md natively? Reads the adapter's
+ * `capabilities.claudeMdNativeDiscovery`. Unknown runtimes return false ("does
+ * NOT auto-discover") so propagation is the safe additive default — an
+ * unrecognized runtime is far more likely to lack native CLAUDE.md loading than
+ * to have it.
+ */
+function runtimeAutoDiscoversClaudeMd(cliName) {
+  try {
+    const { resolveRuntime } = require('./runtimes');
+    const rt = resolveRuntime(cliName);
+    return !!(rt && rt.capabilities && rt.capabilities.claudeMdNativeDiscovery);
+  } catch {
+    return false;
+  }
+}
+
+module.exports = {
+  CLAUDE_MD_FILENAME,
+  MAX_FILES,
+  MAX_WALK_DEPTH,
+  DEFAULT_MAX_BYTES,
+  discoverClaudeMdFiles,
+  buildClaudeMdPropagationBlock,
+  runtimeAutoDiscoversClaudeMd,
+};

package/engine/consolidation.js

@@ -85,6 +85,34 @@ function _readNotesForAppendOrNull() {
   return fs.existsSync(NOTES_PATH) ? null : '';
 }
 
+// Resiliently write notes.md from inside a consolidation lock callback.
+// CRASH GUARD (#858): safeWrite -> renameSync throws EPERM on Windows when
+// notes.md is held open by another process (e.g. a leaked dashboard
+// /state/notes.md read stream). That throw used to propagate out of the
+// async consolidateWithLLM(...) chain / the regex-fallback timer callback with
+// NO surrounding try/catch, becoming an UNHANDLED PROMISE REJECTION (or an
+// uncaught timer exception) that killed the whole engine daemon. Supervisor
+// respawned it, but pooled Copilot ACP agents cannot reattach across restart,
+// so every in-flight agent was orphaned.
+//
+// This wraps safeWrite in shared._retryFsOp (extra exponential-backoff retries
+// on EPERM/EBUSY/EACCES on top of safeWrite's own short retry loop) AND a
+// try/catch, so a transient lock retries then DEFERS: returns false so the
+// caller leaves the inbox notes in place for the next tick instead of crashing.
+// Returns true on success, false if the write could not be completed.
+function _writeNotesOrDefer(content, label) {
+  try {
+    // Keep the in-lock retry budget small (safeWrite already retries EPERM ~5x
+    // internally): a few extra exponential-backoff attempts cover a slightly
+    // longer transient hold without stalling the consolidation lock.
+    shared._retryFsOp(() => safeWrite(NOTES_PATH, content), `write notes.md (${label})`, { attempts: 3, baseMs: 100 });
+    return true;
+  } catch (err) {
+    log('warn', `${label}: notes.md write failed after retries (${err?.code || ''} ${err?.message || err}) \u2014 deferring, inbox notes left for next cycle`);
+    return false;
+  }
+}
+
 // Per-agent memory files live under knowledge/agents/<agent>.md and are
 // injected into individual agent prompts (in addition to the broadcast
 // notes.md). See knowledge/agents/README.md for the convention.
@@ -971,7 +999,17 @@ function consolidateWithLLM(items, existingNotes, files, config) {
     fallbackDone = true;
     if (message) log('warn', message);
     if (err?.message) log('debug', `LLM error: ${err.message}`);
-    consolidateWithRegex(items, files, config);
+    // CRASH GUARD (#858): _fallback runs from a promise .catch AND from a
+    // setTimeout callback. An uncaught throw from consolidateWithRegex in the
+    // timer path is an uncaught exception that kills the daemon; in the .catch
+    // path it is an unhandled rejection. The notes.md write already defers on
+    // lock contention, but keep a top-level guard so no other regex-fallback
+    // failure can ever crash the engine — leave inbox notes for the next tick.
+    try {
+      consolidateWithRegex(items, files, config);
+    } catch (e) {
+      log('warn', `Regex consolidation fallback failed (${e?.code || ''} ${e?.message || e}) \u2014 inbox notes left for next cycle`);
+    }
   }
 
   const llmCall = callLLM(prompt, sysPrompt, {
@@ -1033,7 +1071,9 @@ function consolidateWithLLM(items, existingNotes, files, config) {
         // DATA-LOSS GUARD: cap size but archive the overflow instead of
         // silently discarding it (see _capNotesPreservingOverflow).
         const newContent = _capNotesPreservingOverflow(current + entry);
-        safeWrite(NOTES_PATH, newContent);
+        // CRASH GUARD (#858): defer (return false) on a transient write lock
+        // instead of throwing out of this async chain and crashing the daemon.
+        if (!_writeNotesOrDefer(newContent, 'LLM consolidation')) return false;
         return true;
       });
       if (!wrote) {
@@ -1169,7 +1209,10 @@ function consolidateWithRegex(items, files, config) {
     }
     // DATA-LOSS GUARD: cap size but archive the overflow (see LLM path).
     const newContent = _capNotesPreservingOverflow(current + entry);
-    safeWrite(NOTES_PATH, newContent);
+    // CRASH GUARD (#858): defer (return false) on a transient write lock
+    // instead of throwing out of this synchronous fallback (invoked from a
+    // timer callback and a promise .catch) and crashing the daemon.
+    if (!_writeNotesOrDefer(newContent, 'Regex consolidation')) return false;
     return true;
   });
   if (!wrote) {
@@ -1530,4 +1573,5 @@ module.exports = {
   buildCondensedKbBody,
   _alertContentHash,
   _alertHashExists,
+  _writeNotesOrDefer,
 };

package/engine/db/migrations/026-pre-dispatch-rejections.js

@@ -0,0 +1,55 @@
+function _parseObject(raw) {
+  try {
+    const value = JSON.parse(raw);
+    return value && typeof value === 'object' && !Array.isArray(value) ? value : null;
+  } catch {
+    return null;
+  }
+}
+
+module.exports = {
+  version: 26,
+  description: 'normalize exhausted pre-dispatch rejections out of execution failures',
+  up(db) {
+    const rows = db.prepare(`
+      SELECT rowid, data
+      FROM work_items
+      WHERE status = 'failed' AND archived = 0
+    `).all();
+    const update = db.prepare(`
+      UPDATE work_items
+      SET status = 'pending', data = ?, updated_at = ?
+      WHERE rowid = ? AND archived = 0
+    `);
+    const now = Date.now();
+    for (const row of rows) {
+      const item = _parseObject(row.data);
+      if (!item || item._failureClass !== 'pre-dispatch-eval-stuck') continue;
+      const evaluation = item._preDispatchEval && typeof item._preDispatchEval === 'object'
+        ? item._preDispatchEval
+        : {};
+      const evaluatedAt = evaluation.evaluatedAt || item.failedAt || new Date(now).toISOString();
+      const history = Array.isArray(evaluation.history) ? evaluation.history : [];
+      if (history.length === 0 && evaluation.reason) {
+        history.push({
+          reason: evaluation.reason,
+          evaluatedAt,
+          description: evaluation.description || '',
+        });
+      }
+      item.status = 'pending';
+      item._pendingReason = 'pre_dispatch_eval_rejected';
+      item._preDispatchEval = {
+        ...evaluation,
+        valid: false,
+        exhausted: true,
+        exhaustedAt: evaluation.exhaustedAt || evaluatedAt,
+        history,
+      };
+      delete item._failureClass;
+      delete item.failReason;
+      delete item.failedAt;
+      update.run(JSON.stringify(item), now, row.rowid);
+    }
+  },
+};