@yemi33/minions 0.1.2380 → 0.1.2381

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/engine/dispatch.js

@@ -53,6 +53,8 @@ const NON_MUTATING_DISPATCH_TYPES = new Set([
 // PR source branch always differs and causes phantom auto-cancellation (#369).
 const PR_BRANCH_TARGETED_TYPES = new Set([
   WORK_TYPE.FIX,
+  WORK_TYPE.BUILD_FIX_COMPLEX,
+  WORK_TYPE.TEST,
   WORK_TYPE.VERIFY,
   WORK_TYPE.DECOMPOSE,
 ]);
@@ -148,7 +150,7 @@ function getPrDispatchDedupeKey(entry) {
   if (!entry?.type) return null;
   const targetKey = getPrDispatchTargetKey(entry);
   if (!targetKey) return null;
-  const type = entry.type === WORK_TYPE.FIX ? WORK_TYPE.FIX : entry.type;
+  const type = shared.isFixLikeWorkType(entry.type) ? WORK_TYPE.FIX : entry.type;
   return `${targetKey}:${type}`;
 }
 
@@ -197,7 +199,7 @@ function findActivePrOrBranchLock(dispatch, item) {
   // PR-target dedup is FIX-only: a FIX shouldn't stack on top of another FIX
   // for the same PR, but a REVIEW + FIX pair targeting the same PR is the
   // normal review-then-fix flow and must not be dedup'd here.
-  if (item?.type === WORK_TYPE.FIX) {
+  if (shared.isFixLikeWorkType(item?.type)) {
     const prTargetKey = getPrDispatchTargetKey(item);
     if (prTargetKey) {
       const existing = active.find(d => getPrDispatchTargetKey(d) === prTargetKey);
@@ -703,7 +705,7 @@ async function pruneStalePrDispatchesAsync(config = queries.getConfig()) {
   for (const entry of pending) {
     const reason = reasonsById.get(entry.id);
     if (!reason) continue;
-    if (entry.type !== WORK_TYPE.FIX || !_MERGED_OR_ABANDONED_REASON_RE.test(reason)) continue;
+    if (!shared.isFixLikeWorkType(entry.type) || !_MERGED_OR_ABANDONED_REASON_RE.test(reason)) continue;
     try {
       const wi = _resolveWorkItemForPrunedEntry(entry);
       const scopePaths = shared.extractScopeFilePathsFromWorkItem(wi);

package/engine/lifecycle.js

@@ -1559,7 +1559,7 @@ function isPrAttachmentRequired(type, item, meta = {}) {
   // PR — the agent updates meta.pr in place. The meta.pr short-circuit beats
   // the explicit-flag fallthrough so a legacy requiresPr:true fix doesn't
   // trigger the contract when there's already a PR attached.
-  if ((type === WORK_TYPE.FIX || type === WORK_TYPE.TEST) && meta?.pr) return false;
+  if ((shared.isFixLikeWorkType(type) || type === WORK_TYPE.TEST) && meta?.pr) return false;
 
   // Standalone test work is usually pure build/run/verify. It should only be
   // PR-required when the caller explicitly marks it as file-changing work.
@@ -1568,7 +1568,7 @@ function isPrAttachmentRequired(type, item, meta = {}) {
   return explicit
     || type === WORK_TYPE.IMPLEMENT
     || type === WORK_TYPE.IMPLEMENT_LARGE
-    || type === WORK_TYPE.FIX;
+    || shared.isFixLikeWorkType(type);
 }
 
 function readOptionalJsonStrict(filePath, label, validate) {
@@ -5494,7 +5494,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   // Auto-recover: if a failed implement/fix/test agent created PRs, it likely succeeded before the failure surfaced.
   // P-d2a8f6c1: skip auto-recovery for nonce-mismatched dispatches — a forged
   // report shouldn't be able to ride PRs into a "done" status.
-  const prCreatingType = type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || type === WORK_TYPE.FIX || type === WORK_TYPE.TEST;
+  const prCreatingType = type === WORK_TYPE.IMPLEMENT || type === WORK_TYPE.IMPLEMENT_LARGE || shared.isFixLikeWorkType(type) || type === WORK_TYPE.TEST;
   const autoRecovered = !nonceMismatch && !agentReportedFailure && !isSuccess && prsCreatedCount > 0 && prCreatingType && !!meta?.item?.id;
   if (autoRecovered) {
     log('info', `Auto-recovery: agent failed but created ${prsCreatedCount} PR(s) — upgrading ${meta.item.id} to done`);
@@ -5792,14 +5792,16 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
       try { stampPrdItemWorkItemId(meta.item.id, meta.item.sourcePlan); } catch (err) { log('warn', `stampPrdItemWorkItemId: ${err.message}`); }
     }
     promoteCompletionArtifacts(meta, agentId, dispatchItem.id, structuredCompletion, { resultSummary });
-    // M003 — auto-dispatch a live-validation WI when a coding WI completes.
-    try { autoDispatchLiveValidationWi(meta, config); } catch (err) { log('warn', `autoDispatchLiveValidationWi: ${err.message}`); }
     // P-mqyp0009y025z6a7 — goal invalidation: cancel any pending/queued WIs
     // listed in the completion report's optional `invalidates[]` field.
     if (structuredCompletion && Array.isArray(structuredCompletion.invalidates) && structuredCompletion.invalidates.length > 0) {
       try { applyGoalInvalidation(meta.item.id, structuredCompletion.invalidates, config); } catch (err) { log('warn', `applyGoalInvalidation: ${err.message}`); }
     }
   }
+  if (effectiveSuccess && !skipDoneStatus) {
+    // Coding WIs and direct PR-sourced fix dispatches share this follow-up path.
+    try { autoDispatchLiveValidationWi(meta, config, dispatchItem); } catch (err) { log('warn', `autoDispatchLiveValidationWi: ${err.message}`); }
+  }
   // Failure retry is handled by completeDispatch in dispatch.js — not duplicated here.
   // Only clear _decomposing flag on failure so decompose items don't get permanently stuck.
   if (!effectiveSuccess && meta?.item?.id && type === WORK_TYPE.DECOMPOSE) {
@@ -5994,7 +5996,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
 
   let prFixBranchChange = null;
   let prFixBuildStillFailing = null;
-  if (type === WORK_TYPE.FIX && effectiveSuccess && meta?.pr?.id) {
+  if (shared.isFixLikeWorkType(type) && effectiveSuccess && meta?.pr?.id) {
     try {
       prFixBranchChange = await detectPrFixBranchChange(meta, config);
     } catch (err) {
@@ -6136,7 +6138,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
   } else if (type === WORK_TYPE.REVIEW) {
     log('warn', `Skipping PR review metadata update for ${meta?.pr?.id || meta?.pr?.url || '(unknown PR)'} because review dispatch ${dispatchItem.id} did not complete cleanly`);
   }
-  if (type === WORK_TYPE.FIX && effectiveSuccess) {
+  if (shared.isFixLikeWorkType(type) && effectiveSuccess) {
     updatePrAfterFix(meta?.pr, meta?.project, meta?.source, {
       branchChanged: fixCompletionChangedBranch(structuredCompletion),
       automationCauseKey: meta?.automationCauseKey,
@@ -6173,7 +6175,7 @@ async function runPostCompletionHooks(dispatchItem, agentId, code, stdout, confi
         }
       } catch (err) { log('warn', `PRD sync after fix: ${err.message}`); }
     }
-  } else if (type === WORK_TYPE.FIX && meta?.pr?.id) {
+  } else if (shared.isFixLikeWorkType(type) && meta?.pr?.id) {
     // W-mph6br6a0006a2b9 (F9): the fix dispatch did not complete cleanly
     // (agent crash, non-zero exit, hard contract failure, or nonce mismatch),
     // so updatePrAfterFix above was skipped. Without a write here the PR's
@@ -6800,37 +6802,9 @@ function collapseAllDuplicatePrRecords(config) {
 // a coding WI (not one of the validation types itself). Skips if the coding WI
 // has no PR.
 //
-// W-mrdq22j700056c6c — gated to real code-authoring completions only. Only
-// item.type in {implement, implement:large, fix} ever spawns a follow-up
-// validation WI. Every other work-item type (review, test, verify, setup,
-// explore, ask, docs, decompose, ...) is excluded even when it resolves a PR
-// ref and autoDispatch is on, because those completions don't author a code
-// diff worth re-validating — e.g. a `review` dispatch that merely comments on
-// someone else's PR previously spawned a spurious "Validate: Review opg PR
-// #792 ..." follow-up. See the ELIGIBLE_TYPES check below.
-//
-// Files exactly ONE validation WI per coding-WI completion (W-mrhybval0001).
-// `liveValidation.type` still governs CHECKOUT ROUTING — the set of work-item
-// types that run in-place on the live checkout (see resolveCheckoutMode's
-// membership check) — but auto-validation no longer fans that array out into
-// one validation WI per type. That earlier behavior (W-mr2m1ute000a9c01)
-// conflated "which types run live" with "how many validation tasks to file";
-// a multi-select routing config would silently spawn N validation WIs after
-// every coding completion. Validation is a single downstream step, so we
-// collapse to one WI.
-//
-// liveValidation.type may be a single string (legacy / back-compat) or an
-// array of strings (multi-select hybrid types). We choose ONE validation type
-// for the single WI. It MUST be a member of lvTypes, otherwise resolveCheckoutMode
-// would route the validation WI to a worktree instead of the live checkout
-// (defeating hybrid validation). Preference order: the canonical `test` type
-// when configured, else the first configured live type. The completing item's
-// own type is excluded so a validation-type WI can't recursively validate
-// itself (anti-loop).
-//
-// Only these item.type values ever trigger this hook (see ELIGIBLE_TYPES
-// below) — real code-authoring completions, not review/test/verify/setup/
-// explore/ask/docs/decompose completions.
+// Only real code-authoring completions trigger the hook. The follow-up is
+// always a canonical `test` WI with the PR-focused `build-and-test` playbook;
+// liveValidation.type controls routing, not the semantic type of the task.
 //
 // Deduplicates per codingWiId: any non-terminal WI with
 // meta.liveValidationFor === codingWiId blocks a second dispatch, so only one
@@ -6852,22 +6826,30 @@ function collapseAllDuplicatePrRecords(config) {
 // verify, setup, explore, ask, docs, decompose, ...) is excluded even when it
 // resolves a PR ref, because those completions don't author a code diff
 // worth re-validating.
-const ELIGIBLE_LIVE_VALIDATION_TYPES = new Set([WORK_TYPE.IMPLEMENT, WORK_TYPE.IMPLEMENT_LARGE, WORK_TYPE.FIX]);
+const ELIGIBLE_LIVE_VALIDATION_TYPES = new Set([
+  WORK_TYPE.IMPLEMENT,
+  WORK_TYPE.IMPLEMENT_LARGE,
+  WORK_TYPE.FIX,
+  WORK_TYPE.BUILD_FIX_COMPLEX,
+]);
 
-function autoDispatchLiveValidationWi(meta, config) {
-  const item = meta?.item;
-  if (!item?.id || !item?.type) return;
+function autoDispatchLiveValidationWi(meta, config, dispatchItem = null) {
+  const item = meta?.item || null;
+  const sourceType = item?.type || dispatchItem?.type || null;
+  const sourceKey = item?.id || dispatchItem?.id || null;
+  if (!sourceKey || !sourceType) return;
+  if (!item && !meta?.pr) return;
 
   // Never re-trigger off the completion of a WI that was itself auto-created
   // as a live-validation follow-up — that's what causes the infinite
   // "Validate: Validate: ..." cascade (W-mr9u39az000db5c2 / issue #708).
-  if (item.meta && item.meta.liveValidationFor) return;
+  if (item?.meta && item.meta.liveValidationFor) return;
 
-  // W-mrdq22j700056c6c — only implement/implement:large/fix completions ever
+  // Only implement/implement:large/fix/build-fix-complex completions ever
   // author a real code diff worth validating. Review, test, verify, setup,
   // explore, ask, docs, decompose, etc. completions must never spawn a
   // "Validate: ..." follow-up, even when they resolve a PR reference.
-  if (!ELIGIBLE_LIVE_VALIDATION_TYPES.has(item.type)) return;
+  if (!ELIGIBLE_LIVE_VALIDATION_TYPES.has(sourceType)) return;
 
   // Issue #716 — QA Session infrastructure WIs (SETUP/DRAFT/EXECUTE, tagged
   // via meta.sessionId and always dispatched with skipPr:true) never own a
@@ -6877,7 +6859,7 @@ function autoDispatchLiveValidationWi(meta, config) {
   // for all three phases) spawns spurious "Validate: QA Session ..." WIs the
   // moment any PR reference resolves against it (see the skipPr guard below
   // resolveWorkItemPrRecord in engine.js for the matching pre-dispatch fix).
-  if (item.skipPr || (item.meta && item.meta.sessionId)) return;
+  if (item?.skipPr || (item?.meta && item.meta.sessionId)) return;
 
   const projectName = meta?.project?.name;
   if (!projectName) return;
@@ -6887,23 +6869,8 @@ function autoDispatchLiveValidationWi(meta, config) {
   const project = projects.find(p => p && p.name === projectName);
   if (!project) return;
 
-  const lv = project.liveValidation;
-  if (!lv || lv.autoDispatch !== true || !lv.type) return;
-
-  const lvTypes = Array.isArray(lv.type) ? lv.type : [lv.type];
-
-  // Candidate validation types = configured live types minus the completing
-  // item's own type (avoid an infinite validate-the-validation loop).
-  const candidates = lvTypes.filter(t => t && t !== item.type);
-  if (candidates.length === 0) return;
-
-  // Collapse to a SINGLE validation type: prefer the canonical `test` type when
-  // it is a configured live type, else the first configured live type. Either
-  // way the chosen type is a member of lvTypes, so the validation WI routes to
-  // the live checkout (not a worktree).
-  const validationType = candidates.includes(WORK_TYPE.TEST)
-    ? WORK_TYPE.TEST
-    : candidates[0];
+  const validationType = shared.resolveLiveValidationAutoDispatchType(project);
+  if (!validationType) return;
 
   // Resolve PR reference: prefer the canonical stamped _pr field (set by
   // stampWiPrRef which runs earlier in runPostCompletionHooks), then fall
@@ -6915,11 +6882,22 @@ function autoDispatchLiveValidationWi(meta, config) {
   // (W-mq18ec6h000p7b87) and would otherwise let a non-fix WI (e.g.
   // 'implement'/'docs') that merely *mentions* an unrelated PR number in
   // prose trigger a live-validation dispatch against the wrong PR.
-  const prRef = item._pr || item._prUrl || shared.extractStructuredWorkItemPrRef(item) || null;
+  const prRef = item
+    ? (item._pr || item._prUrl || shared.extractStructuredWorkItemPrRef(item) || null)
+    : (meta?.pr || null);
   if (!prRef) return;
 
-  const codingWiId = item.id;
-  const wiScope = resolveWorkItemScope(meta);
+  const prUrl = item?._prUrl || (typeof prRef === 'object'
+    ? (prRef.url || prRef.webUrl || prRef.remoteUrl || null)
+    : (/^https?:\/\//i.test(String(prRef)) ? String(prRef) : null));
+  const prId = typeof prRef === 'object'
+    ? (prRef.id || prRef.pr_id || prRef.prId || prRef.pullRequestId || shared.getPrNumber(prRef))
+    : String(prRef);
+  const prTarget = prUrl || (prId != null ? String(prId) : null);
+  if (!prTarget) return;
+
+  const codingWiId = sourceKey;
+  const wiScope = item ? resolveWorkItemScope(meta) : projectName;
   if (!wiScope) return;
 
   try {
@@ -6942,7 +6920,7 @@ function autoDispatchLiveValidationWi(meta, config) {
         return items;
       }
 
-      const proposedTitle = 'Validate: ' + (item.title || codingWiId);
+      const proposedTitle = 'Validate: ' + (item?.title || meta?.pr?.title || codingWiId);
       // Defense-in-depth (belt-and-suspenders alongside the meta.liveValidationFor
       // guard above): never create a doubly-nested "Validate: Validate: ..."
       // title even if some future caller manages to invoke this function
@@ -6957,11 +6935,20 @@ function autoDispatchLiveValidationWi(meta, config) {
         title: proposedTitle,
         type: validationType,
         status: WI_STATUS.PENDING,
-        depends_on: [codingWiId],
-        references: [prRef],
-        meta: { liveValidationFor: codingWiId, liveValidationType: validationType },
+        depends_on: item?.id ? [codingWiId] : [],
+        targetPr: prTarget,
+        pr_id: prId != null ? String(prId) : prTarget,
+        references: prUrl
+          ? [{ url: prUrl, label: 'Source PR' }]
+          : [prTarget],
+        meta: {
+          liveValidationFor: codingWiId,
+          liveValidationType: validationType,
+          playbook: 'build-and-test',
+          ...(dispatchItem?.id ? { sourceDispatchId: dispatchItem.id } : {}),
+        },
         project: projectName,
-        priority: item.priority || 'medium',
+        priority: item?.priority || 'medium',
         created: ts(),
         createdBy: 'lifecycle:live-validation-auto-dispatch',
       };