@yemi33/minions 0.1.2352 → 0.1.2354

package/dashboard.js

@@ -6993,10 +6993,13 @@ const server = http.createServer(async (req, res) => {
 
       let result = null;
       let agentChanged = false;
-      // Set inside the source-file lock below when a project move is needed;
-      // inserted into the target file's own lock scope afterward so we never
-      // hold both files' locks at once.
+      // Set inside the source-file lock below when a project move is
+      // needed. W-mrbbmltq000fce9f: the move itself (target push + source
+      // removal) is executed AFTER this lock releases, target-write-first,
+      // so a failure never straddles "spliced from source, not yet in
+      // target" — see the two-phase block below.
       let movedItem = null;
+      let needsMove = false;
       mutateJsonFileLocked(wiPath, (items) => {
         if (!Array.isArray(items)) items = [];
         const idx = items.findIndex(i => i.id === id);
@@ -7034,29 +7037,78 @@ const server = http.createServer(async (req, res) => {
         }
         item.updatedAt = new Date().toISOString();
 
-        // W-mrazefzz000358e3 — actually MOVE the item between work-items.json
-        // files when the resolved target differs from where it lives today,
-        // rather than just stamping item.project in place. Only trip this
-        // when the resolved wiPath actually changes — re-assigning the same
-        // project the item already lives in is a no-op move.
+        // W-mrazefzz000358e3 — a cross-project move actually MOVEs the item
+        // between work-items.json files when the resolved target differs
+        // from where it lives today, rather than just stamping item.project
+        // in place. Only trip this when the resolved wiPath actually
+        // changes — re-assigning the same project the item already lives in
+        // is a no-op move.
+        //
+        // W-mrbbmltq000fce9f — do NOT splice the item out of the source
+        // array here. Doing the splice-then-push as two independent locked
+        // calls (the historical bug) means a target-write failure after
+        // this callback commits leaves the item spliced from source and
+        // never written to target: silently lost from both stores. Instead
+        // only STAGE the move — clone the (already field-edited) item with
+        // its new `project` value — and leave the source array untouched.
+        // The actual splice happens in a later, separate lock, only once
+        // the target push below has durably committed.
         if (projectMove && path.resolve(projectMove.wiPath) !== path.resolve(wiPath)) {
-          if (projectMove.projectName) item.project = projectMove.projectName;
-          else delete item.project;
-          movedItem = item;
-          items.splice(idx, 1);
+          needsMove = true;
+          movedItem = { ...item };
+          if (projectMove.projectName) movedItem.project = projectMove.projectName;
+          else delete movedItem.project;
         }
 
-        result = { code: 200, body: { ok: true, item } };
+        result = { code: 200, body: { ok: true, item: needsMove ? movedItem : item } };
         return items;
       });
       if (!result) return jsonReply(res, 500, { error: 'unexpected state' });
 
-      if (movedItem) {
-        mutateJsonFileLocked(projectMove.wiPath, (targetItems) => {
-          if (!Array.isArray(targetItems)) targetItems = [];
-          targetItems.push(movedItem);
-          return targetItems;
-        });
+      if (needsMove && result.code === 200) {
+        try {
+          // Phase 1 of the move: durably write the item into the TARGET
+          // store first. If this throws (lock timeout, storage error,
+          // process crash), the source store still holds the item
+          // untouched (aside from the field edits already committed above)
+          // — nothing to roll back, nothing lost.
+          mutateJsonFileLocked(projectMove.wiPath, (targetItems) => {
+            if (!Array.isArray(targetItems)) targetItems = [];
+            targetItems.push(movedItem);
+            return targetItems;
+          });
+        } catch (targetErr) {
+          return jsonReply(res, 500, {
+            error: `project move failed while writing to target store; item left unchanged in its original project: ${targetErr.message}`,
+          });
+        }
+
+        try {
+          // Phase 2: the target write is confirmed durable — now it's safe
+          // to remove the item from the source store.
+          mutateJsonFileLocked(wiPath, (items) => {
+            if (!Array.isArray(items)) items = [];
+            const spliceIdx = items.findIndex(i => i.id === id);
+            if (spliceIdx !== -1) items.splice(spliceIdx, 1);
+            return items;
+          });
+        } catch (spliceErr) {
+          // Removing from source failed AFTER the target write already
+          // committed. Compensate by removing the item from the target
+          // store again, so the item ends up in exactly one store (its
+          // original) instead of duplicated across two.
+          try {
+            mutateJsonFileLocked(projectMove.wiPath, (targetItems) => {
+              if (!Array.isArray(targetItems)) targetItems = [];
+              const ti = targetItems.findIndex(i => i.id === id);
+              if (ti !== -1) targetItems.splice(ti, 1);
+              return targetItems;
+            });
+          } catch { /* best-effort rollback; surfaced via the 500 below regardless */ }
+          return jsonReply(res, 500, {
+            error: `project move failed while removing from source store; move was rolled back: ${spliceErr.message}`,
+          });
+        }
       }
 
       // Clear stale pending dispatch entries outside lock

package/docs/README.md

@@ -30,6 +30,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [harness-mode.md](harness-mode.md) — Tri-Agent Harness Mode (`harness_mode: "tri_agent"` on scheduled tasks): Planner → Generator → Evaluator loop that iterates a shared on-disk artifact until a rubric passes or the iteration cap fires.
 - [harness-propagation.md](harness-propagation.md) — How user-level and project-local harness assets (skills, slash-commands, MCP config, `CLAUDE.md` / `AGENTS.md`) propagate into an agent's worktree via `--add-dir`, the `harnessPropagateProjectLocal` flag, and the project-local-on-main worktree-visibility footgun.
 - [harness-transparency.md](harness-transparency.md) — The `harnessUsed` self-report contract: capture (agent reports the skills / MCPs / commands / docs it used) → ground (engine cross-checks against `_harnessPropagated` and annotates `grounded:true\|false`, never dropping) → surface (PR comment, final agent note, work-item modal).
+- [kb-dedup-duplicate-pair-investigation.md](kb-dedup-duplicate-pair-investigation.md) — Investigation-only pass diffing suspected duplicate KB filename groups (content-hash dedup for agent-authored reviews/build-reports) to confirm true full-body duplication before any fix is proposed.
 - [kb-sweep.md](kb-sweep.md) — Knowledge-base consolidation sweep (hash dedup → LLM batch dedup/reclassify → per-entry compress) and the detached runner that keeps it alive across `minions restart`.
 - [keep-processes.md](keep-processes.md) — `meta.keep_processes` sidecar contract: when to use it vs managed-spawn, sidecar schema, caps, and the [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) lifecycle.
 - [live-checkout-mode.md](live-checkout-mode.md) — Per-project opt-in `checkoutMode: 'live'`: skips `git worktree add` and dispatches in-place inside `project.localPath` for `repo`-managed trees, submodule-heavy repos, deep Windows paths, and native build state. Includes the refuse-on-dirty contract and the per-project mutating-concurrency cap of 1.
@@ -46,6 +47,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [rfc-completion-json.md](rfc-completion-json.md) — RFC for replacing stdout regex-scraping with a structured `completion.json` control-plane protocol.
 - [runtime-adapters.md](runtime-adapters.md) — Runtime adapter contract (`engine/runtimes/*`): how the engine talks to Claude Code, Copilot CLI, and future CLIs through a single capability-flagged interface.
 - [self-improvement.md](self-improvement.md) — The six self-improvement mechanisms (learnings inbox, per-agent history, review feedback, quality metrics, etc.) that form Minions' continuous feedback loop.
+- [shared-lifecycle-module-map.md](shared-lifecycle-module-map.md) — Documentation-only module-boundary audit of `engine/shared.js` / `engine/lifecycle.js`: function inventory, cross-file call graph, and a proposed split map (no code moved).
 - [skills.md](skills.md) — Skill block format: how agents emit reusable `\`\`\`skill` blocks and how the engine extracts them into native personal-skill directories.
 - [slim-ux/concepts.md](slim-ux/concepts.md) — Slim-UX design notes: simplified surface concepts driving the project picker, inline project link, and decoupled folder picker.
 - [slim-ux/architecture-suggestions.md](slim-ux/architecture-suggestions.md) — Slim-UX follow-up architecture suggestions paired with `concepts.md`.

package/docs/kb-dedup-duplicate-pair-investigation.md

@@ -0,0 +1,138 @@
+# KB Duplicate-Entry Investigation (P-mrb8yg9x001jc364)
+
+Investigation-only pass (per architecture-meeting scoping) diffing suspected
+duplicate KB filename groups to confirm true full-body duplication vs.
+distinct events sharing a naming pattern, before any fix is proposed.
+
+## Background
+
+`engine/consolidation.js:1156-1290` content-hashes and dedups
+engine-authored SYSTEM ALERTS (via `shared.isEngineSystemAlert` +
+`alertHash` frontmatter, see `_alertHashExists`) at **write time** —
+recurring identical alerts never get a `-2`/`-3` full-body copy. Agent-authored
+review/build-report notes have no equivalent write-time guard: they fall
+through the plain `shared.uniquePath(...)` branch (`consolidation.js:1267`),
+so any note that gets classified into `knowledge/<category>/` twice under the
+same computed filename (`${date}-${agent}-${titleSlug}.md`) always produces a
+full-body `-2`/`-3` copy at consolidation time.
+
+Separately, `engine/kb-sweep.js` Pass 1 (`_hashDedup`, `kb-sweep.js:34-37,
+155-176`) content-hashes **every** KB entry regardless of category and
+archives byte-identical duplicates to `knowledge/_swept/`, keeping the most
+recent. This pass is category-agnostic and *would* catch true agent-authored
+duplicates too — but it only runs on a schedule (`AUTO_SWEEP_INTERVAL_MS = 4h`,
+`kb-sweep.js:26`, or on-demand via the dashboard), not at consolidation time.
+
+## Method
+
+Diffed 3 suspected duplicate-filename groups directly on disk (byte compare
+via `fc.exe /b`, line diff via `Compare-Object`, frontmatter inspection,
+file timestamps, and cross-reference against `engine/kb-sweep-state.json`'s
+last-completed-sweep timestamp).
+
+## Findings
+
+### Pair 1 — `knowledge/reviews/2026-07-07-ripley-review-…-740-fix-contam{,-2,-3}.md` (TRUE DUPLICATE, -2/-3 only)
+
+- `-2.md` and `-3.md` are **byte-identical** (`fc.exe /b` → "no differences").
+  Both carry `source: ripley-ripley-review-mrb701ph0008506d-2026-07-07-2200.md`
+  in their `classifyToKnowledgeBase`-added frontmatter and wrap the same
+  embedded note (`id: NOTE-mrb701pz0009ed9c`).
+- Created at `15:06:22` and `15:09:14` (same day, ~3 min apart) — i.e. the
+  *same* inbox note (`ripley-ripley-review-mrb701ph0008506d-2026-07-07-2200.md`)
+  was independently classified into KB twice by `classifyToKnowledgeBase`,
+  producing a `uniquePath` collision on the computed filename and hence a
+  full-body `-3` copy of `-2`.
+- The base file (no suffix, `15:05:43`) is a **different, earlier, distinct
+  write** — different frontmatter shape entirely (`id/agent/date/pr/repo/
+  branch/verdict`, no `source:`/`category:`/`reusable:` fields that
+  `classifyToKnowledgeBase` always adds) and different body formatting
+  (`## Verdict: APPROVE` vs. `**Verdict:** APPROVE`, different bullet
+  structure). It is **not** part of the `-2`/`-3` duplicate chain — it's a
+  separate KB write that happens to share a title-derived filename stem.
+- **Verdict: -2 and -3 are a true, confirmed full-body duplicate pair. The
+  base file is a distinct entry, not a duplicate.**
+
+### Pair 2 — `knowledge/build-reports/2026-07-07-dallas-validate-fix-contaminated-originalref-in-live-chec{,-2,-3}.md` (TRUE DUPLICATE, -2/-3 only)
+
+- Same pattern as Pair 1: `-2.md` and `-3.md` are byte-identical
+  (`fc.exe /b` → "no differences"), both stamped
+  `source: dallas-W-mrb6tfdn000oebc8-2026-07-07-2200.md` and wrapping the
+  same embedded note (`id: NOTE-mrb707jk000b1903`), created `15:17:51` and
+  `15:19:02` (~70s apart).
+- The base file (`15:16:29`, 4451 bytes vs. 5373 bytes for -2/-3) again has
+  the plain original-note frontmatter (`id/agent/date/task`, no
+  `source:`/`category:`/`reusable:`) and is shorter/differently-worded —
+  a distinct earlier write, not part of the duplicate chain.
+- **Verdict: -2 and -3 are a true, confirmed full-body duplicate pair. The
+  base file is a distinct entry, not a duplicate.**
+
+### Pair 3 — `knowledge/project-notes/2026-07-07-engine-engine-skipped-worktree-wipe-live-dispatch-guard-f{,-2…-38}.md` (NOT DUPLICATES — confirmed distinct)
+
+- ~40 files share the `…-live-dispatch-guard-f[-N]` filename stem. Sampled
+  `-f-27.md`: frontmatter carries `alertHash: 9bc818d6…` and
+  `source: engine-worktree-skip-live-W-mrb6tlze000pc39d-2026-07-07.md` — a
+  **distinct** work-item ID (`W-mrb6tlze000pc39d`) from other members of the
+  group (confirmed against `notes.md`/`knowledge/project-notes` entries
+  referencing different `W-…` IDs, e.g. `W-mrb70qnx000o59d5`,
+  `W-mrb7gwha001073e6`).
+- These are engine-authored SYSTEM ALERTS (`shared.isEngineSystemAlert`
+  matches), so each is content-hashed and given a distinct `alertHash`
+  frontmatter value per distinct incident. `_alertHashExists`
+  (`consolidation.js:1188-1200`) already prevents a same-hash alert from
+  producing a duplicate — the large `-2…-38` filename fan-out here reflects
+  ~40 **genuinely distinct** live-dispatch-guard incidents (one per
+  worktree/dispatch), not 40 copies of one incident. `uniquePath` is doing
+  exactly what it should: disambiguating distinct events that happen to
+  share a human-readable title.
+- **Verdict: confirmed NOT duplicates. The existing engine-alert dedup path
+  (W-mr3pi9de) is working correctly here.**
+
+## Root cause (confirmed, not yet fixed — out of scope for this pass)
+
+1. `classifyToKnowledgeBase` (`consolidation.js:1231-1298`) has **no
+   write-time content-hash guard for agent-authored notes** — only
+   `isEngineSystemAlert` entries get one. When the same inbox note is
+   classified into KB more than once (e.g. a PR reviewed by two
+   independent dispatches within the same day, each producing its own
+   inbox note that hashes/formats similarly — or, per the `-2`/`-3`
+   evidence above, the identical inbox note re-processed), each pass
+   writes a fresh, full-body `-N` copy via `shared.uniquePath`.
+2. `engine/kb-sweep.js` Pass 1 (`_hashDedup`) *does* eventually catch and
+   archive these byte-identical copies (category-agnostic, keeps most
+   recent) — but only on its own schedule (`AUTO_SWEEP_INTERVAL_MS = 4h`
+   default, `kb-sweep.js:26`) or on manual trigger, not at consolidation
+   time.
+3. Cross-checked against `engine/kb-sweep-state.json`: the last completed
+   sweep finished `2026-07-07T21:49:00Z` (`14:49` local); both confirmed
+   duplicate pairs above were created *after* that sweep completed
+   (`15:05`-`15:19` local), so neither had yet had a chance to be caught by
+   the next scheduled run at the time of this investigation. This is
+   consistent with the sweep design, not a sweep bug — but it does mean a
+   duplicate pair can sit in `knowledge/<category>/` (and get injected into
+   every agent prompt that primes from `knowledge/`) for up to ~4h before
+   Pass 1 removes it.
+
+## Recommendation (not implemented — meeting scoped this as investigation-only)
+
+The `-2`/`-3` case is real and reproducible, but bounded by the existing
+sweep's 4h cadence — a same-day double-classification costs extra disk +
+prompt-priming tokens for at most one sweep interval, not indefinitely. A
+future fix should extend the existing `alertHash`-style write-time
+content-hash dedup in `classifyToKnowledgeBase` to non-system-alert items
+too (skip the `uniquePath` full-body write when a byte-identical KB entry
+already exists in the target category), rather than relying solely on the
+delayed sweep pass. Distinct-event fan-out (Pair 3 pattern) must be
+preserved — any fix must key on content hash, not filename/title
+similarity, since many genuinely distinct events share a title stem.
+
+## Sources
+
+- `engine/consolidation.js:1156-1300` (`isEngineSystemAlert`/`alertHash`
+  dedup, `classifyToKnowledgeBase`)
+- `engine/kb-sweep.js:20-37,155-176` (`_hashEntry`, `_hashDedup`, sweep
+  interval constant)
+- `engine/kb-sweep-state.json` (`completedAtIso: 2026-07-07T21:49:00.186Z`)
+- `knowledge/reviews/2026-07-07-ripley-review-github-opg-microsoft-minions-740-fix-contam{,-2,-3}.md`
+- `knowledge/build-reports/2026-07-07-dallas-validate-fix-contaminated-originalref-in-live-chec{,-2,-3}.md`
+- `knowledge/project-notes/2026-07-07-engine-engine-skipped-worktree-wipe-live-dispatch-guard-f{,-2…-38}.md`

package/docs/kb-sweep.md

@@ -58,7 +58,11 @@ Because originals are archived to `_swept/` (same 30-day retention as every othe
 
 ### Pass 2 — LLM Batch Sweep
 
-The remaining survivors are sent to Claude Haiku in batches of `LLM_BATCH_SIZE = 30` (source: [`engine/kb-sweep.js:29`](../engine/kb-sweep.js#L29)). Each batch prompt asks for three lists in JSON:
+Survivors are split into **changed** and **unchanged** entries before anything is sent to the LLM (source: [`engine/kb-sweep.js`](../engine/kb-sweep.js) `_classifyLlmScanFreshness`). An entry is `unchanged` only if it carries the `_llmScannedAt` frontmatter marker (`LLM_SCAN_FLAG_KEY`) AND its `mtime` hasn't advanced past that timestamp — the same mtime-gated pattern Pass 3 uses for `_swept`. Everything else (never scanned, or edited/reclassified since its last scan) is `changed`.
+
+Only the `changed` entries are batched to Claude Haiku in groups of `LLM_BATCH_SIZE = 30` (source: [`engine/kb-sweep.js:29`](../engine/kb-sweep.js#L29)) with **full content**. `unchanged` entries are still appended to every prompt as a lightweight roster (title/date/category only, no content) so cross-entry duplicate detection against the whole KB stays correct — a changed entry can still be flagged as a duplicate of an older, already-scanned one — without re-spending tokens re-analyzing entries nothing has touched. If there are zero `changed` entries, the pass makes no LLM calls at all. This fixed an unbounded-cost bug where every 4h sweep cycle re-sent the *entire* KB manifest regardless of what had changed since the prior cycle (source: PR #738).
+
+Each batch prompt asks for three lists in JSON:
 
 | Field | What the LLM looks for |
 |-------|------------------------|
@@ -68,10 +72,14 @@ The remaining survivors are sent to Claude Haiku in batches of `LLM_BATCH_SIZE =
 
 Each action archives the file via the same `_archiveKbFile()` helper used by Pass 1; reclassification rewrites the `category:` frontmatter line and moves the file into the new category directory (source: [`engine/kb-sweep.js:323-340`](../engine/kb-sweep.js#L323)).
 
+**Duplicate-pair guard.** `duplicates` entries are only actioned if the pair references at least one index the LLM actually content-analyzed this batch (i.e. a member of `changedIdx`); a pair where every referenced index is roster-only (`unchangedIdx`) is skipped with a warning instead of archived, since that would mean acting on a hallucinated or stale LLM reference rather than a real comparison (source: [`engine/kb-sweep.js`](../engine/kb-sweep.js) `_applyLlmPlan`, PR #739).
+
 Reclassification targets are validated against `shared.KB_CATEGORIES` (`architecture`, `conventions`, `project-notes`, `build-reports`, `reviews` — source: [`engine/shared.js`](../engine/shared.js) `KB_CATEGORIES`); unknown categories are silently dropped.
 
 If a batch returns invalid JSON or the runtime is unavailable, that batch is skipped with a warning and the rest of the sweep continues (source: [`engine/kb-sweep.js:203-215`](../engine/kb-sweep.js#L203)).
 
+`_llmScannedAt` is stamped on every analyzed entry only at the very end of the whole sweep — after Pass 3's rewrite — to avoid a same-run mtime race with the rewrite pass's own content edit (source: [`engine/kb-sweep.js`](../engine/kb-sweep.js), stamping step called from `runKbSweep`).
+
 ### Pass 2.5 — Age-Based TTL Expiry (secondary safety net)
 
 Cheap, deterministic. No LLM call. With Pass 1.5 now collapsing the bulk of the boilerplate structurally, this pass is a **secondary safety net**: it archives genuinely stale one-off notes that never clustered into a large enough group to be consolidated (e.g. a lone failure class that only occurred twice in a week). The dedup and rewrite passes can only reclaim *duplicate* or *empty* entries, so an age cutoff is still the backstop for long-tail one-offs.
@@ -103,6 +111,10 @@ Survivors of Passes 1, 1.5, and 2 that are still on disk get rewritten one entry
 
 After a successful rewrite, the entry's frontmatter gains a `_swept: <ISO timestamp>` key (source: [`engine/kb-sweep.js:293`](../engine/kb-sweep.js#L293)).
 
+## The `_llmScannedAt` Frontmatter Flag
+
+Mirrors `_swept` but gates Pass 2 instead of Pass 3: an entry with `_llmScannedAt` set and an mtime that hasn't advanced past it is treated as `unchanged` and skipped from full-content LLM analysis on the next sweep (roster-only context still applies — see Pass 2 above). Editing an entry (or a category reclassify) bumps its mtime past the stamp, so the next sweep re-analyzes it. The key is exported as `LLM_SCAN_FLAG_KEY` (source: [`engine/kb-sweep.js:32`](../engine/kb-sweep.js#L32)).
+
 ## The `_swept` Frontmatter Flag
 
 `_swept` makes Pass 3 idempotent across runs. Semantics:

package/docs/live-checkout-mode.md

@@ -64,11 +64,13 @@ By default the dirty tree refusal (Guarantee 2) is terminal — the engine never
 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`.
 
-This is **DESTRUCTIVE** — it permanently discards the operator's uncommitted changes in the live checkout. As of W-mqzbbhn2 it is **ON by default**: discarding disposable dirt via reset-to-remote keeps live-checkout branches aligned with origin instead of accumulating `minions: auto-save agent WIP` commits on every dirty exit. Set `liveCheckoutAutoReset: false` (per-project or fleet-wide) to restore the terminal dirty-tree refusal for live checkouts whose local drift you want preserved.
+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.
 
 - **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.
+
 #### 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.
@@ -185,6 +187,7 @@ Live-mode agents run **in-place** in the operator's checkout, so when a dispatch
 - **Retry-with-backoff on the WIP auto-save commit (#608).** The `git add -A` + `git commit` above (and the equivalent self-heal commit described below) go through `_commitAgentWipWithRetry`: a bounded retry (3 attempts, linear backoff) that fires only when the commit fails with an `index.lock` / "another git process" message — i.e. a transient collision with a concurrent git invocation — never on a genuine failure like "nothing to commit". Previously a single failed attempt (e.g. a `.git/index.lock` race) silently aborted the auto-save, leaving the tree dirty on the agent branch and letting the pollution below take hold.
 - **Orphaned-agent-branch self-heal at dispatch start (#608).** If dispatch-end restore is ever skipped or interrupted (crash, forced kill, an engine restart racing the restore), the *next* dispatch for that project can start with HEAD already sitting on a stray `work/<wi-id>` branch from the previous run — and, before this fix, `prepareLiveCheckout`'s dirty-tree check ran *before* `originalRef` was even captured, so the function returned `{ reason: 'dirty' }` immediately and the branch was never noticed or cleaned, silently repeating for every subsequent dispatch. `prepareLiveCheckout` now recognizes this case: if the tree is still dirty after the existing auto-clean-artifacts recheck, and the current branch (read from the already-fetched `git status --porcelain -b` header, no extra git call) matches the `work/<id>` naming convention (`_looksLikeAgentBranch`) and differs from this dispatch's own target branch, the WIP is committed onto that stray branch (again via `_commitAgentWipWithRetry`) and HEAD is switched back to `mainRef` before the normal flow continues. This only ever touches a branch matching the engine's own naming convention — an operator's own feature branch (e.g. `feature/x`) is never mistaken for engine litter and is left untouched.
 - **AUTO-RESTORE (best-effort, never `--force`).** At dispatch-end `restoreLiveCheckoutAtDispatchEnd` issues a **plain** `git checkout <originalRef>` — no `--force`, no `-B`, no reset, no clean, no stash. It no-ops when there is nothing to restore: no captured `originalRef`, the agent branch *is* the original ref, or HEAD already sits on the original ref (matched against the branch name *or* the raw sha so the detached-HEAD case is recognized). It is strictly best-effort: every error is swallowed and logged, and a restore never alters the dispatch result.
+- **Read-site trust invariant (P-mrb8yg9x001hfa9f audit).** `restoreLiveCheckoutAtDispatchEnd` never re-derives or re-validates `originalRef` itself — it does not call `_looksLikeAgentBranch` or otherwise probe for contamination; it simply checks out whatever ref it is handed. This is safe *only* because `prepareLiveCheckout`'s own originalRef-contamination invariant (W-mrb6an8300058fd8, §"Original-ref capture" above) already corrects `originalRef` to `mainRef` at capture time whenever HEAD was on a stray engine-managed branch, for both the existing-branch (4b) and new-branch/STALE-BASE-GUARD (4d) code paths — and `engine.js` persists that corrected value verbatim (`engine.js:3106-3122`) for every restore call site (`onAgentClose`, the `engine/cli.js` restart re-attach path, and the `engine/timeout.js` reaping paths) to consume as-is. If the write-side correction in `prepareLiveCheckout` ever regressed, restore would silently check the operator back out onto the contaminated branch, since it has no independent check of its own to catch that. Characterized end-to-end in `test/unit/prepare-live-checkout.test.js` (chains `prepareLiveCheckout` → `restoreLiveCheckoutAtDispatchEnd` for both the 4b and 4d paths).
 - **Fallback notify (only when a safe switch is impossible).** If git declines the plain checkout — most likely because the agent left uncommitted changes a checkout would overwrite — the refusal is **honored**: the tree is left exactly as the agent left it and a deduped `live-checkout-branch-<dispatchId>` inbox alert tells the operator how to switch back manually (`git -C <localPath> checkout <originalRef>`). The engine never forces the switch. An **unexpected** restore error (git missing, repo corruption, a GVFS blob fetch on the switch-back) now also writes this alert, so a non-refusal failure never silently strands the tree.
 - **Terminal-failure alert.** When the dispatch ends in a non-success terminal state, a deduped `live-checkout-failed-<dispatchId>` inbox alert is written so the operator knows a live-mode run failed inside their own checkout (where any partial work is visible). This is independent of the restore and fires even when the restore itself succeeds.
 
@@ -294,7 +297,7 @@ The engine has no opinion about local branches; this hygiene is the operator's r
 Live-checkout mode is deliberately small. These are NOT supported and will not be added:
 
 - **No `auto` mode.** The choice between `worktree` and `live` is per-project and operator-set. The engine will not auto-detect submodules / `repo` workspaces and silently switch modes.
-- **No auto-stash on dirty refusal _by default_.** Out of the box the engine refuses and exits; it never `git stash`es to "make room" for a dispatch, because that silently mutates the operator's tree and conflates engine state with operator state. The operator can **opt in** per-project (`project.liveCheckoutAutoStash`) or fleet-wide (`engine.liveCheckoutAutoStash`) to auto-stash instead of refusing — see [2b](#2b-opt-in-auto-stash-on-dirty-w-mqtvnnj1000357fa). Even then the engine never **pops** the stash on the operator's behalf. (The `liveCheckoutAutoReset` escape hatch — ON by default as of W-mqzbbhn2 — **discards** rather than stashes; set it to `false` per-project / fleet-wide to keep the terminal dirty-tree refusal. See [§2b](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).)
+- **No auto-stash on dirty refusal _by default_.** Out of the box the engine refuses and exits; it never `git stash`es to "make room" for a dispatch, because that silently mutates the operator's tree and conflates engine state with operator state. The operator can **opt in** per-project (`project.liveCheckoutAutoStash`) or fleet-wide (`engine.liveCheckoutAutoStash`) to auto-stash instead of refusing — see [2b](#2b-opt-in-auto-stash-on-dirty-w-mqtvnnj1000357fa). Even then the engine never **pops** the stash on the operator's behalf. (The `liveCheckoutAutoReset` escape hatch — **OFF by default** as of W-mrawgw4q000a6bff, and even when enabled now only runs as a last-resort fallback *after* auto-stash fails or is disabled — **discards** rather than stashes; set it to `true` per-project / fleet-wide to opt in. See [§2b](#2b-opt-in-auto-reset-on-dirty-livecheckoutautoreset-w-mqvejug6000eeb20).)
 - **No concurrent dispatches per project.** The cap is 1; raising it would require per-WI subdirectories, which live mode explicitly does not provide.
 - **No per-WI subdirectory isolation.** Live mode is one-checkout-per-project by design. If you need isolation, use `checkoutMode: 'worktree'` (the default).
 - **No per-WI override.** `checkoutMode` is per-project only. There is no `meta.checkoutMode` on a work item that overrides the project setting.
@@ -306,7 +309,7 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | File | Purpose |
 |---|---|
 | `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 (ON as of W-mqzbbhn2). Gates the dirty-tree auto-reset in `prepareLiveCheckout` (W-mqvejug6000eeb20). |
+| `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` — `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). |
@@ -324,7 +327,7 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | `engine/create-pr-worktree.js` — `prepareCreatePrWorktree` step-4 restore | `reset --hard HEAD` (not the index-leaking `checkout -- .`) + retried untracked removal + `liveTreeDirty` surfaced + `shared.removeWorktree` teardown (PL-live-checkout-reliability-hardening). |
 | `engine/pr-action.js` — `buildCreatePrFollowups({ …, mainBranch })` live-mode message | CC "Create PR" chip instruction. In live mode the PR is ALWAYS built on a fresh branch off `origin/<mainBranch>` (stash → fetch → `checkout -B` → pop → commit → push → PR → restore), never reusing the current branch as the base; stop-on-stash-pop-conflict. `dashboard.js` `POST /api/pr-action/offer-create-pr` resolves `mainBranch` via `shared.resolveMainBranch` and threads it in (W-mr3jbpru). |
 | `dashboard/js/settings.js` — checkoutMode dropdown + chip + `set-liveCheckoutAutoReset` fleet toggle | Operator-facing UI; the fleet-wide auto-reset toggle persists to `engine.liveCheckoutAutoReset` (per-project UI deferred — config.json only) (P-a3f9b207; auto-reset toggle W-mqvejug6000eeb20). |
-| `test/unit/{resolve-spawn-paths-live-mode,prepare-live-checkout,spawn-agent-live-mode-wiring,live-checkout-auto-stash}.test.js` | Wiring and contract tests (P-a3f9b208; auto-stash helpers W-mqtvnnj1000357fa). |
+| `test/unit/{resolve-spawn-paths-live-mode,prepare-live-checkout,spawn-agent-live-mode-wiring,live-checkout-auto-stash,live-checkout-stash-before-reset}.test.js` | Wiring and contract tests (P-a3f9b208; auto-stash helpers W-mqtvnnj1000357fa; stash-before-reset ordering W-mrawgw4q000a6bff). |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` | Non-retryable refusal class. |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION` | Non-retryable refusal class for a mid-operation / detached-HEAD operator tree (in-progress merge/rebase/cherry-pick/revert/bisect or detached HEAD), distinct from the dirty-tree class. Emitted by `spawnAgent`'s mid-op / detached-HEAD refusal block (P-a7f3c1d9; wired P-c5a1f3b8). |
 | `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_BLOB_FETCH` | Non-retryable refusal class for an existing-branch checkout that could not hydrate the tree on a blobless GVFS partial clone (auth-less cache fetch, headless) — deterministic, so excluded from mechanical retry (PL-live-checkout-reliability-hardening). |