@yemi33/minions 0.1.2447 → 0.1.2449

package/docs/kb-sweep.md

@@ -4,7 +4,7 @@ How the `knowledge/` directory stays curated, deduplicated, and small enough to
 
 ## What the Sweep Does
 
-The KB sweep is a multi-pass cycle implemented in [`engine/kb-sweep.js`](../engine/kb-sweep.js) that prunes duplicate, boilerplate, stale, and oversized entries from `knowledge/`. It runs asynchronously, archives (rather than deletes) what it removes, and writes a `_swept` frontmatter flag so the expensive rewrite pass is idempotent.
+The KB sweep is a multi-pass cycle implemented in [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) that prunes duplicate, boilerplate, stale, and oversized entries from `knowledge/`. It runs asynchronously, archives (rather than deletes) what it removes, and writes a `_swept` frontmatter flag so the expensive rewrite pass is idempotent.
 
 ```
 Entries in knowledge/<category>/*.md
@@ -25,7 +25,7 @@ Entries in knowledge/<category>/*.md
 
 Cheap, deterministic. No LLM call.
 
-For every entry, compute `sha256(normalize(content).slice(0,500) + ':' + content.length)` (source: [`engine/kb-sweep.js:34-37`](../engine/kb-sweep.js#L34)). Group by hash. When two or more entries collide, keep the most recent (by `date:` frontmatter, then mtime) and archive the rest into `knowledge/_swept/` with a `<!-- swept: ... | reason: hash-duplicate of ... -->` header via `_archiveKbFile()` (source: [`engine/kb-sweep.js:61-70`](../engine/kb-sweep.js#L61), called at [`:172`](../engine/kb-sweep.js#L172)).
+For every entry, compute `sha256(normalize(content).slice(0,500) + ':' + content.length)` (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_hashEntry`). Group by hash. When two or more entries collide, keep the most recent (by `date:` frontmatter, then mtime) and archive the rest into `knowledge/_swept/` with a `<!-- swept: ... | reason: hash-duplicate of ... -->` header via `_archiveKbFile()` (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_archiveKbFile`, called from `_hashDedup`).
 
 This catches near-identical re-postings across batches that the LLM pass might miss because they land in different batches.
 
@@ -35,9 +35,9 @@ Cheap, deterministic. No LLM call. This is the pass that actually stops `knowled
 
 The highest-volume category (`project-notes`) is dominated by near-identical boilerplate — e.g. hundreds of `# Agent Failed: …` dumps that differ only by work-item id, date, and dispatch id (a single agent/failure-class pair like `dallas` / `live-checkout-failed` can account for hundreds of files). Hash dedup can't collapse them (the leading bytes differ) and the LLM batch pass can't either (they're scattered across dozens of 30-entry batches). Left alone they survive every other pass forever.
 
-Pass 1.5 groups eligible entries by a **structural signature** and rolls any group of at least `minGroupSize` notes into a single digest, archiving the originals to `knowledge/_swept/` (source: [`engine/kb-sweep.js`](../engine/kb-sweep.js) `_structuralConsolidate`).
+Pass 1.5 groups eligible entries by a **structural signature** and rolls any group of at least `minGroupSize` notes into a single digest, archiving the originals to `knowledge/_swept/` (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_structuralConsolidate`).
 
-- **Signature** = `category :: agent :: kind :: time-bucket`. `kind` is derived from the note (source: [`engine/kb-sweep.js`](../engine/kb-sweep.js) `_consolidationKind`):
+- **Signature** = `category :: agent :: kind :: time-bucket`. `kind` is derived from the note (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_consolidationKind`):
   - `failure-<failureClass>` when the note carries a `failureClass:` (or `result: error`) — the agent-failure dumps.
   - `noop` / `merge-conflict` when the title matches a no-op or merge-conflict fix report.
   - Any note that doesn't match a boilerplate kind returns `null` and is **left untouched** — unique, valuable notes are never grouped.
@@ -58,9 +58,9 @@ Because originals are archived to `_swept/` (same 30-day retention as every othe
 
 ### Pass 2 — LLM Batch Sweep
 
-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`.
+Survivors are split into **changed** and **unchanged** entries before anything is sent to the LLM (source: [`engine/memory/kb-sweep.js`](../engine/memory/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).
+Only the `changed` entries are batched to Claude Haiku in groups of `LLM_BATCH_SIZE = 30` (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `LLM_BATCH_SIZE`) 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:
 
@@ -70,23 +70,23 @@ Each batch prompt asks for three lists in JSON:
 | `reclassify` | Entries in the wrong category. Returned as `{index, from, to, reason}`. |
 | `remove`     | Stale or empty entries (boilerplate, "no changes needed", bail-out notes). Returned as `{index, reason}`. |
 
-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:661-717`](../engine/kb-sweep.js#L661)).
+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/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_applyLlmPlan`).
 
-**changedIdx guard.** All three actions are only actioned against indices the LLM actually content-analyzed this batch (i.e. members of `changedIdx`). `remove` and `reclassify` require their own referenced `index` to be in `changedIdx`; a `duplicates` pair is actioned if the pair references at least one index in `changedIdx` (a pair where every referenced index is roster-only, `unchangedIdx`, is skipped). Roster-only entries are sent to the LLM with title/date/category only (no content — see the "existing entries" roster section), so an index outside `changedIdx` cannot have been genuinely compared/analyzed this batch; acting on it 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, W-mrc9y5y000063033).
+**changedIdx guard.** All three actions are only actioned against indices the LLM actually content-analyzed this batch (i.e. members of `changedIdx`). `remove` and `reclassify` require their own referenced `index` to be in `changedIdx`; a `duplicates` pair is actioned if the pair references at least one index in `changedIdx` (a pair where every referenced index is roster-only, `unchangedIdx`, is skipped). Roster-only entries are sent to the LLM with title/date/category only (no content — see the "existing entries" roster section), so an index outside `changedIdx` cannot have been genuinely compared/analyzed this batch; acting on it would mean acting on a hallucinated or stale LLM reference rather than a real comparison (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_applyLlmPlan`, PR #739, W-mrc9y5y000063033).
 
-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.
+Reclassification targets are validated against `shared.KB_CATEGORIES` (`architecture`, `conventions`, `project-notes`, `build-reports`, `reviews` — source: [`engine/core/shared.js`](../engine/core/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:521-540`](../engine/kb-sweep.js#L521)).
+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/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_llmBatchSweep`).
 
-`_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`).
+`_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/memory/kb-sweep.js`](../engine/memory/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.
 
-For every surviving entry, the pass computes the entry's age and archives it to `knowledge/_swept/` when it exceeds that category's TTL (source: [`engine/kb-sweep.js`](../engine/kb-sweep.js) `_expireByAge`). Two safety properties:
+For every surviving entry, the pass computes the entry's age and archives it to `knowledge/_swept/` when it exceeds that category's TTL (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_expireByAge`). Two safety properties:
 
-- **Age is taken from the authored date** (`YYYY-MM-DD-` filename prefix / `date:` frontmatter), *not* mtime — so the Pass 3 rewrite touching a file does not reset its clock and let a stale entry live forever. When no date is parseable it falls back to mtime; when neither exists the entry is treated as fresh and never age-expired (source: [`engine/kb-sweep.js`](../engine/kb-sweep.js) `_entryAgeMs`).
+- **Age is taken from the authored date** (`YYYY-MM-DD-` filename prefix / `date:` frontmatter), *not* mtime — so the Pass 3 rewrite touching a file does not reset its clock and let a stale entry live forever. When no date is parseable it falls back to mtime; when neither exists the entry is treated as fresh and never age-expired (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_entryAgeMs`).
 - **Only categories with a positive TTL are eligible.** Durable categories (`architecture`, `conventions`) are absent from the default map and are never age-expired. Per-agent memory under `knowledge/agents/` is never even scanned into the manifest (it's not in `KB_CATEGORIES`), and pinned entries are excluded upstream — so none of them can be aged out.
 
 The TTL map is `ENGINE_DEFAULTS.kbCategoryTtlDays`, overridable per-fleet via `config.engine.kbCategoryTtlDays` (merged over the defaults; set a category to `0` to disable expiry for it):
@@ -102,34 +102,34 @@ Because expiry archives to `_swept/` (subject to the same 30-day retention as ev
 
 ### Pass 3 — Per-Entry Rewrite
 
-Survivors of Passes 1, 1.5, and 2 that are still on disk get rewritten one entry at a time, with up to `NORMALIZE_CONCURRENCY = 5` parallel workers (source: [`engine/kb-sweep.js:30`](../engine/kb-sweep.js#L30)). Consolidation digests are excluded (rewriting would destroy their roll-up table). Each remaining entry is sent to Haiku with a fixed template prompt that:
+Survivors of Passes 1, 1.5, and 2 that are still on disk get rewritten one entry at a time, with up to `NORMALIZE_CONCURRENCY = 5` parallel workers (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `NORMALIZE_CONCURRENCY`). Consolidation digests are excluded (rewriting would destroy their roll-up table). Each remaining entry is sent to Haiku with a fixed template prompt that:
 
 - Caps output at ~800 words.
 - Forces the structure `## Summary` → `## Key Findings` → `## Action Items` (omit if none) → `## References` (omit if none).
 - Preserves all `file:line` references and code snippets.
 - Drops boilerplate (full dates, agent IDs in the body, narrative scaffolding).
 
-After a successful rewrite, the entry's frontmatter gains a `_swept: <ISO timestamp>` key (source: [`engine/kb-sweep.js:647-649`](../engine/kb-sweep.js#L647)).
+After a successful rewrite, the entry's frontmatter gains a `_swept: <ISO timestamp>` key (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_rewritePass`).
 
 ## 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)).
+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/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `LLM_SCAN_FLAG_KEY`).
 
 ## The `_swept` Frontmatter Flag
 
 `_swept` makes Pass 3 idempotent across runs. Semantics:
 
-- **Set** to `new Date().toISOString()` whenever the rewrite pass successfully rewrites the body (source: [`engine/kb-sweep.js:647-649`](../engine/kb-sweep.js#L647)).
-- **Skipped** by Pass 3 on subsequent sweeps as long as the file's `mtimeMs` is `<= sweptAt + 1000` ms (1 s grace for FS timestamp jitter — source: [`engine/kb-sweep.js:614-621`](../engine/kb-sweep.js#L614)).
+- **Set** to `new Date().toISOString()` whenever the rewrite pass successfully rewrites the body (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_rewritePass`).
+- **Skipped** by Pass 3 on subsequent sweeps as long as the file's `mtimeMs` is `<= sweptAt + 1000` ms (1 s grace for FS timestamp jitter — source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_rewritePass`).
 - **Re-processed** if the file is edited after the sweep flag was set (mtime exceeds the grace window).
 
 Hash dedup (Pass 1) and the LLM sweep (Pass 2) ignore `_swept` — those passes act on metadata and similarity, not on whether the entry was previously rewritten.
 
-The flag key is exported as `SWEPT_FLAG_KEY` for tests (source: defined [`engine/kb-sweep.js:31`](../engine/kb-sweep.js#L31), exported [`:1198`](../engine/kb-sweep.js#L1198)).
+The flag key is exported as `SWEPT_FLAG_KEY` for tests (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `SWEPT_FLAG_KEY`, re-exported from `module.exports`).
 
 ## 30-Day Archive Retention
 
-Archived entries land in `knowledge/_swept/` with their original filename (deduped via `shared.uniquePath()` if it collides). They're not deleted immediately — `_pruneOldSwept()` runs at the end of every sweep and removes any file whose `mtimeMs` is older than `SWEPT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000` (30 days — source: [`engine/kb-sweep.js:25`](../engine/kb-sweep.js#L25), pruning function [`:72-84`](../engine/kb-sweep.js#L72)).
+Archived entries land in `knowledge/_swept/` with their original filename (deduped via `shared.uniquePath()` if it collides). They're not deleted immediately — `_pruneOldSwept()` runs at the end of every sweep and removes any file whose `mtimeMs` is older than `SWEPT_RETENTION_MS = 30 * 24 * 60 * 60 * 1000` (30 days — source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `SWEPT_RETENTION_MS`, pruning function `_pruneOldSwept`).
 
 This gives humans a recovery window: if a sweep archives something useful, you have ~30 days to copy it back out of `_swept/` before it's permanently pruned.
 
@@ -139,10 +139,10 @@ The dashboard exposes two endpoints:
 
 | Method | Path | Purpose |
 |--------|------|---------|
-| `POST` | `/api/knowledge/sweep` | Start a sweep in the background. Returns `202 { ok: true, started: true }` (source: [`dashboard.js:14205`](../dashboard.js#L14205), handler [`:7642`](../dashboard.js#L7642)). |
-| `GET`  | `/api/knowledge/sweep/status` | Poll `{ inFlight, startedAt, lastResult, lastCompletedAt }` (source: [`dashboard.js:14206`](../dashboard.js#L14206), handler [`:7680`](../dashboard.js#L7680)). |
+| `POST` | `/api/knowledge/sweep` | Start a sweep in the background. Returns `202 { ok: true, started: true }` (source: [`dashboard.js`](../dashboard.js) route registry, handler `handleKnowledgeSweep`). |
+| `GET`  | `/api/knowledge/sweep/status` | Poll `{ inFlight, startedAt, lastResult, lastCompletedAt }` (source: [`dashboard.js`](../dashboard.js) route registry, handler `handleKnowledgeSweepStatus`). |
 
-POST body is optional. Pass `{ "pinnedKeys": ["knowledge/conventions/foo.md", ...] }` to add request-level pins on top of `pinned.md`. Pinned entries are excluded from every pass (source: [`engine/kb-sweep.js:933-944`](../engine/kb-sweep.js#L933)).
+POST body is optional. Pass `{ "pinnedKeys": ["knowledge/conventions/foo.md", ...] }` to add request-level pins on top of `pinned.md`. Pinned entries are excluded from every pass (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `_runKbSweepImpl`).
 
 ```bash
 # Trigger a sweep
@@ -156,9 +156,9 @@ curl http://localhost:7331/api/knowledge/sweep/status
 
 ### Concurrency Guard
 
-Only one sweep runs at a time. The POST handler refuses to start a second sweep with `{ ok: true, alreadyRunning: true, startedAt }` while one is in flight (source: [`dashboard.js:7654-7665`](../dashboard.js#L7654)).
+Only one sweep runs at a time. The POST handler refuses to start a second sweep with `{ ok: true, alreadyRunning: true, startedAt }` while one is in flight (source: [`dashboard.js`](../dashboard.js) `handleKnowledgeSweep`).
 
-The guard auto-releases when the runner PID is dead or the sweep exceeds `staleGuardMs(entryCount)` — `max(30 min, 1 s × entryCount)` (source: [`engine/kb-sweep.js:747-778`](../engine/kb-sweep.js#L747), [`dashboard.js:7654-7660`](../dashboard.js#L7654)).
+The guard auto-releases when the runner PID is dead or the sweep exceeds `staleGuardMs(entryCount)` — `max(30 min, 1 s × entryCount)` (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `staleGuardMs` + `readSweepLiveness`, consumed by [`dashboard.js`](../dashboard.js) `handleKnowledgeSweep`).
 
 ### Persistent State
 
@@ -175,13 +175,13 @@ Sweep liveness is coordinated through `engine/kb-sweep-state.json` so the dashbo
 { "status": "failed", "startedAt": ..., "completedAt": ..., "error": "..." }
 ```
 
-The state file plus runner PID liveness is the source of truth; the detached runner has no dashboard-owned in-memory lifecycle (source: [`engine/kb-sweep.js:747-778`](../engine/kb-sweep.js#L747), [`dashboard.js:7642-7654`](../dashboard.js#L7642)). A separate `engine/kb-swept.json` is written after each successful non-dry-run sweep with the human-readable summary shown by the dashboard's "swept N days ago" badge (source: [`engine/kb-sweep.js:1019-1024`](../engine/kb-sweep.js#L1019)).
+The state file plus runner PID liveness is the source of truth; the detached runner has no dashboard-owned in-memory lifecycle (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `readSweepLiveness` + `_writeSweepState`, [`dashboard.js`](../dashboard.js) `handleKnowledgeSweep`). A separate `engine/kb-swept.json` is written after each successful non-dry-run sweep with the human-readable summary shown by the dashboard's "swept N days ago" badge (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `runKbSweep` → `shared.mutateKbSwept`).
 
 ## Automatic Periodic Sweep
 
-The engine tick loop can also auto-spawn the KB sweep without dashboard interaction. Gated by `engine.autoConsolidateMemory` (default `true`; set `false` to disable — source: [`engine/shared.js`](../engine/shared.js) `ENGINE_DEFAULTS.autoConsolidateMemory`):
+The engine tick loop can also auto-spawn the KB sweep without dashboard interaction. Gated by `engine.autoConsolidateMemory` (default `true`; set `false` to disable — source: [`engine/core/shared.js`](../engine/core/shared.js) `ENGINE_DEFAULTS.autoConsolidateMemory`):
 
-- When `engine.autoConsolidateMemory: true`, every tick the engine consults `shouldAutoSweep()` from [`engine/kb-sweep.js`](../engine/kb-sweep.js) and, when the 4-hour cadence has elapsed since the last completion, calls `spawnSweepRunnerDetached()` to fire-and-forget a fresh `engine/kb-sweep-runner.js` process (source: [`engine.js`](../engine.js) tick step 2.1).
+- When `engine.autoConsolidateMemory: true`, every tick the engine consults `shouldAutoSweep()` from [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) and, when the 4-hour cadence has elapsed since the last completion, calls `spawnSweepRunnerDetached()` to fire-and-forget a fresh `engine/memory/kb-sweep-runner.js` process (source: [`engine.js`](../engine.js) tick step 2.1).
 - The inbox→`notes.md` consolidation runs every tick *regardless* of this flag via `consolidateInbox()`; `autoConsolidateMemory` controls **only** the heavier `knowledge/` sweep.
 - The detached runner survives `minions restart` (same pattern used by the manual trigger), and the in-flight guard above prevents overlap with manual sweeps.
 
@@ -189,12 +189,12 @@ The engine tick loop can also auto-spawn the KB sweep without dashboard interact
 
 The KB page surfaces sweep state in two places:
 
-1. **Trigger button** (`kbSweep()` in [`dashboard/js/render-kb.js:185`](../dashboard/js/render-kb.js#L185)) posts to `/api/knowledge/sweep` with the user's pinned keys and shows an immediate "queued" toast. If the response says `alreadyRunning`, the toast switches to "already running (Xm elapsed) — let it finish first".
-2. **`#kb-swept-time` indicator** renders `swept N days ago · now sweeping (Xm)` (source: [`dashboard/js/render-kb.js:87-97`](../dashboard/js/render-kb.js#L87)). The `sweepInFlight` and `sweepStartedAt` fields come from `GET /api/knowledge` (source: [`dashboard.js:7568-7572`](../dashboard.js#L7568)).
+1. **Trigger button** (`kbSweep()` in [`dashboard/js/render-kb.js`](../dashboard/js/render-kb.js)) posts to `/api/knowledge/sweep` with the user's pinned keys and shows an immediate "queued" toast. If the response says `alreadyRunning`, the toast switches to "already running (Xm elapsed) — let it finish first".
+2. **`#kb-swept-time` indicator** renders `swept N days ago · now sweeping (Xm)` (source: [`dashboard/js/render-kb.js`](../dashboard/js/render-kb.js), `kb-swept-time` element). The `sweepInFlight` and `sweepStartedAt` fields come from `GET /api/knowledge` (source: [`dashboard.js`](../dashboard.js) `handleKnowledgeList`).
 
 ### Polling
 
-The KB page is refreshed on every dashboard status cycle (~4 s) in [`dashboard/js/refresh.js:1035-1045`](../dashboard/js/refresh.js#L1035). There is no separate sweep-status polling timer and no auto-stop — the in-flight badge keeps refreshing for as long as the user has the dashboard open and the sweep is running. Sweeps can take many minutes for a large KB; the persistent `engine/kb-sweep-state.json` flag plus the indefinite refresh loop are what let the indicator survive dashboard restarts and arbitrarily long sweeps.
+The KB page is refreshed on every dashboard status cycle (~4 s) via `refreshKnowledgeBase()` in [`dashboard/js/refresh.js`](../dashboard/js/refresh.js). There is no separate sweep-status polling timer and no auto-stop — the in-flight badge keeps refreshing for as long as the user has the dashboard open and the sweep is running. Sweeps can take many minutes for a large KB; the persistent `engine/kb-sweep-state.json` flag plus the indefinite refresh loop are what let the indicator survive dashboard restarts and arbitrarily long sweeps.
 
 ## Result Summary
 
@@ -221,7 +221,7 @@ The KB page is refreshed on every dashboard status cycle (~4 s) in [`dashboard/j
 }
 ```
 
-After a non-dry-run sweep, `queries.invalidateKnowledgeBaseCache()` is called so the next `/api/knowledge` read sees the new state (source: [`engine/kb-sweep.js:1022-1024`](../engine/kb-sweep.js#L1022)).
+After a non-dry-run sweep, `queries.invalidateKnowledgeBaseCache()` is called so the next `/api/knowledge` read sees the new state (source: [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) `runKbSweep`).
 
 ## What NOT to Do
 
@@ -240,9 +240,9 @@ The archive directory `knowledge/_swept/` is also off-limits to manual edits —
 
 ## Related Files
 
-- [`engine/kb-sweep.js`](../engine/kb-sweep.js) — implementation
-- [`engine/queries.js`](../engine/queries.js) — `getKnowledgeBaseEntries()`, `invalidateKnowledgeBaseCache()`
+- [`engine/memory/kb-sweep.js`](../engine/memory/kb-sweep.js) — implementation
+- [`engine/core/queries.js`](../engine/core/queries.js) — `getKnowledgeBaseEntries()`, `invalidateKnowledgeBaseCache()`
 - [`dashboard.js`](../dashboard.js) — `handleKnowledgeSweep`, `handleKnowledgeSweepStatus`, `handleKnowledgeList`
 - [`dashboard/js/render-kb.js`](../dashboard/js/render-kb.js) — UI trigger and indicator
 - [`dashboard/js/refresh.js`](../dashboard/js/refresh.js) — refresh cadence (every status cycle)
-- [`engine/shared.js`](../engine/shared.js) — `KB_CATEGORIES`, `getPinnedItems()`, `uniquePath()`
+- [`engine/core/shared.js`](../engine/core/shared.js) — `KB_CATEGORIES`, `getPinnedItems()`, `uniquePath()`

package/docs/keep-processes.md

@@ -35,7 +35,7 @@ Set `meta.keep_processes: true` on the WI; agent writes `agents/<id>/keep-pids.j
 ## Lifecycle
 
 - **Validation:** sidecar shape + workdir checked in `onAgentClose`. Failure → non-retryable `failure_class: invalid-keep-processes-{workdir,schema}`.
-- **Sweep:** [`engine/keep-process-sweep.js`](../engine/keep-process-sweep.js) reaps at boot and every 180 ticks. Dead PIDs are pruned; expired TTL → process killed via `shared.killGracefully` then `killImmediate`.
+- **Sweep:** [`engine/processes/keep-process-sweep.js`](../engine/processes/keep-process-sweep.js) reaps at boot and every 180 ticks. Dead PIDs are pruned; expired TTL routes through the identity-verified `engine.keep-process.ttl` termination site.
 - **No healthcheck:** unlike managed-spawn, `keep_processes` does not gate WI completion on first-healthy. If the child crashes immediately the agent still succeeds — by design (ad-hoc helper semantics).
 
 ## Caps

package/docs/live-checkout-mode.md

@@ -34,9 +34,9 @@ Implementation: `engine.js` builds a `liveProjectsInUse` set from the active dis
 
 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` 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:
+Before spawning, `engine/worktrees/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.
+- Non-retryable `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` (added to `engine/orchestration/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>`.
@@ -48,14 +48,14 @@ Outside the explicit auto-stash and auto-reset policies, the engine never resets
 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:
 
 - 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**.
+- When enabled and the tree is dirty, `spawnAgent` delegates the whole flow to `engine/worktrees/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.
 - The engine **never pops the stash** automatically — that is the operator's choice. The stash name is logged and noted so the operator can `git stash pop` (or `git stash apply`) in `project.localPath` manually.
 
 #### 2a. Thrown pre-spawn failures are retryable, NOT dirty (#305)
 
-A thrown error from `prepareLiveCheckout` — a required-arg/ref-validation guard, or a transient `git status`/`rev-parse`/`checkout`/`symbolic-ref` failure — is **not** proof that the operator tree is dirty. `spawnAgent`'s `catch` block therefore completes the dispatch with the **separate** `FAILURE_CLASS.LIVE_CHECKOUT_FAILED` (`'live-checkout-failed'`), which is deliberately **excluded** from `engine/dispatch.js`'s `neverRetry` set. The dispatcher auto-retries with bounded backoff up to `ENGINE_DEFAULTS.maxRetries`, so racy branch-lock handoff, a just-finished sibling dispatch, or transient git state recovers on the next attempt **without a manual `/api/work-items/retry`**. Genuinely terminal underlying reasons (auth, validation) still short-circuit via the reason-string check in `isRetryableFailureReason`. No dirty-files inbox alert is written and no `_pendingReason: 'live_checkout_dirty'` stamp is applied for this path — those belong to the confirmed-dirty result above.
+A thrown error from `prepareLiveCheckout` — a required-arg/ref-validation guard, or a transient `git status`/`rev-parse`/`checkout`/`symbolic-ref` failure — is **not** proof that the operator tree is dirty. `spawnAgent`'s `catch` block therefore completes the dispatch with the **separate** `FAILURE_CLASS.LIVE_CHECKOUT_FAILED` (`'live-checkout-failed'`), which is deliberately **excluded** from `engine/orchestration/dispatch.js`'s `neverRetry` set. The dispatcher auto-retries with bounded backoff up to `ENGINE_DEFAULTS.maxRetries`, so racy branch-lock handoff, a just-finished sibling dispatch, or transient git state recovers on the next attempt **without a manual `/api/work-items/retry`**. Genuinely terminal underlying reasons (auth, validation) still short-circuit via the reason-string check in `isRetryableFailureReason`. No dirty-files inbox alert is written and no `_pendingReason: 'live_checkout_dirty'` stamp is applied for this path — those belong to the confirmed-dirty result above.
 
 > **`git status --porcelain` maxBuffer (W-mqvejug6000eeb20).** All read-only git probes in `prepareLiveCheckout` / `restoreLiveCheckoutAtDispatchEnd` run with a 50 MB `maxBuffer` (`LIVE_CHECKOUT_GIT_MAX_BUFFER`, threaded through `baseOpts`). A live tree with thousands of dirty/untracked paths could otherwise overflow `execFile`'s 1 MB default and reject with `ERR_CHILD_PROCESS_STDOUT_MAXBUFFER` — a *thrown* error that mis-classified as a transient retryable `LIVE_CHECKOUT_FAILED` (per 2a) and retry-stormed to the cap instead of being surfaced as the dirty tree it actually was. A caller-supplied `gitOpts.maxBuffer` still wins (spread after the default).
 
@@ -121,7 +121,7 @@ Like the blob-fetch case this is **structural, not transient** — it does *not*
 
 Live mode shares one checkout per project. There is no pool to recycle, no quarantine directory, no per-WI subdirectory under the project root. The mutating-concurrency cap (Guarantee 1) is the only isolation mechanism: agents take turns in the same directory.
 
-Pool short-circuits in `engine.js` and `engine/cleanup.js` gate on `worktreePath` truthiness and `!liveMode`, so borrow / return / orphan-GC execute zero git commands for live projects.
+Pool short-circuits in `engine.js` and `engine/orchestration/cleanup.js` gate on `worktreePath` truthiness and `!liveMode`, so borrow / return / orphan-GC execute zero git commands for live projects.
 
 ### 5. Refuse on mid-operation / detached HEAD (engine never aborts the operator's in-progress op)
 
@@ -130,11 +130,11 @@ Pool short-circuits in `engine.js` and `engine/cleanup.js` gate on `worktreePath
 - **In-progress git operation.** The git dir is resolved robustly via `git rev-parse --git-dir` (so submodule / gitdir-file / `repo`-managed trees — the setups that motivate live mode — are covered; a *failure* to resolve the git dir now throws → retryable `LIVE_CHECKOUT_FAILED` rather than silently probing a fabricated `<localPath>/.git` and missing the operation). Sentinel paths under it are probed: `MERGE_HEAD` → merge, `rebase-merge/` & `rebase-apply/` → rebase, `CHERRY_PICK_HEAD` → cherry-pick, `REVERT_HEAD` → revert, **`BISECT_LOG` → bisect**. First hit returns `{ ok:false, reason:'mid-operation', op, details }`.
 - **Detached HEAD.** `git symbolic-ref -q HEAD` exiting with **code 1** returns `{ ok:false, reason:'detached-head', sha }` (sha from `git rev-parse HEAD`). Branching off a detached HEAD would strand the operator's anonymous commits. A *transient* `symbolic-ref` failure (spawn error / timeout, no exit-1) is **not** treated as a detached HEAD — it rethrows → retryable `LIVE_CHECKOUT_FAILED` — so an on-a-branch tree that hit a hiccup is never permanently refused.
 
-Either condition fails the dispatch non-retryably with `FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION` (`'live-checkout-mid-operation'`; added to `engine/dispatch.js`'s neverRetry set alongside `LIVE_CHECKOUT_DIRTY`). `spawnAgent` writes a `live-checkout-blocked-<wi-id>` inbox alert and stamps the work item `_pendingReason: 'live_checkout_mid_operation'` (or `'live_checkout_detached_head'` for the detached case). The recovery guidance tells the operator to finish or abort the in-progress op with their own commands (`git <op> --continue` / `git <op> --abort`), or checkout a branch, then re-dispatch. The engine never runs `git reset`, `git clean`, `git stash`, `git rebase --abort`, or moves HEAD on the operator's behalf.
+Either condition fails the dispatch non-retryably with `FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION` (`'live-checkout-mid-operation'`; added to `engine/orchestration/dispatch.js`'s neverRetry set alongside `LIVE_CHECKOUT_DIRTY`). `spawnAgent` writes a `live-checkout-blocked-<wi-id>` inbox alert and stamps the work item `_pendingReason: 'live_checkout_mid_operation'` (or `'live_checkout_detached_head'` for the detached case). The recovery guidance tells the operator to finish or abort the in-progress op with their own commands (`git <op> --continue` / `git <op> --abort`), or checkout a branch, then re-dispatch. The engine never runs `git reset`, `git clean`, `git stash`, `git rebase --abort`, or moves HEAD on the operator's behalf.
 
 ### 6. STALE-BASE GUARD — refuse to fork off a diverged local base (W-mr98op8w000ma4ad)
 
-**W-mrcifup2000c218a — detected at ALLOCATION time first.** Same as Guarantee 2, the stale-base condition is now checked BEFORE dispatch by `engine/live-checkout.js#checkLiveCheckoutStaleBase` (a cheap, read-only, fetch-free `git rev-list --count origin/<mainRef>..<mainRef>` probe, mirroring the in-spawn check below) in the dispatch-existing-pending loop. A stale hit stamps `_pendingReason: 'live_checkout_stale_base'` and leaves the item pending — no retry consumed, no terminal failure — re-checked every tick, instead of the pre-fix behavior of failing non-retryably on the very first hit. A `live-checkout-stale-base-<wi-id>` inbox alert is written (deduped per day) so the condition is still surfaced to a human. The in-spawn refusal documented below is now a defense-in-depth fallback for the race window between the pre-check and the actual `git checkout -b`, not the common path — it still fails non-retryably when it fires, because a stale base found there is still deterministic and un-recoverable by a bare retry.
+**W-mrcifup2000c218a — detected at ALLOCATION time first.** Same as Guarantee 2, the stale-base condition is now checked BEFORE dispatch by `engine/worktrees/live-checkout.js#checkLiveCheckoutStaleBase` (a cheap, read-only, fetch-free `git rev-list --count origin/<mainRef>..<mainRef>` probe, mirroring the in-spawn check below) in the dispatch-existing-pending loop. A stale hit stamps `_pendingReason: 'live_checkout_stale_base'` and leaves the item pending — no retry consumed, no terminal failure — re-checked every tick, instead of the pre-fix behavior of failing non-retryably on the very first hit. A `live-checkout-stale-base-<wi-id>` inbox alert is written (deduped per day) so the condition is still surfaced to a human. The in-spawn refusal documented below is now a defense-in-depth fallback for the race window between the pre-check and the actual `git checkout -b`, not the common path — it still fails non-retryably when it fires, because a stale base found there is still deterministic and un-recoverable by a bare retry.
 
 A **clean** tree can still hide **committed** contamination. When `prepareLiveCheckout` is about to create a **new** branch (`git checkout -b <branch>`) off the operator's current HEAD, and HEAD is sitting on the project base ref (`mainRef`, the common case), the local `mainRef` branch may carry commits that were never pushed to `origin/<mainRef>` — e.g. leftover in-progress work from a prior dispatch on a live-mode project (capped to one mutating dispatch, but shared across many sequential dispatches), an interrupted process, or a bad rebase. Forking a new branch off that base silently inherits those commits into the branch **and its PR**. This is exactly the scope-contamination class first seen on ADO PR 5411214 and recurring on AB#12016662 / ADO PR 5419146 (~20 unrelated OCM files baked into an otherwise-clean 2-file a11y fix).
 
@@ -191,7 +191,7 @@ Immediately before the new-branch `git checkout -b`, `prepareLiveCheckout` compa
 - **The base is per-project, NOT a hardcoded `'main'`.** `spawnAgent` resolves `mainRef` via `shared.resolveMainBranch(cwd, project.mainBranch)` (`engine.js`), which honors the project's configured `mainBranch`, else auto-detects `refs/remotes/origin/HEAD`, else falls back to `main`. Repos whose default branch is **not** `main` — e.g. Office Android development, whose harness (`claude.md`) documents a `lkg/main/android` base — are handled by setting `project.mainBranch: "lkg/main/android"` (or by having `origin/HEAD` point at it); the guard then keys on that branch. The word "main" in this guarantee is shorthand for *"the project's resolved base branch,"* never the literal string.
 - **HEAD already on `mainRef`** → forks normally; the guard never probes the base ref.
 - **HEAD off-base, local `refs/heads/<mainRef>` exists** → PLAIN `git checkout <mainRef>` (no fetch, no reset, no `--force` — the tree was verified clean at Guarantee 2), then forks off it. No auth-less GVFS blob fetch is forced in the common case.
-- **HEAD off-base, no usable local `mainRef`** (fresh-clone edge case) — or the local checkout itself fails — → **fail closed** with `{ ok:false, reason:'wrong-base' }` **unless auto-base-repair is enabled (see §6a).** The caller refuses **non-retryably** with `FAILURE_CLASS.LIVE_CHECKOUT_WRONG_BASE` (`'live-checkout-wrong-base'`; added to `engine/dispatch.js`'s neverRetry set), writes an inbox alert naming the off-base HEAD, the expected base, and the exact `git checkout <mainRef>` recovery command, and stamps the work item `_pendingReason`. This mirrors the dirty / mid-operation philosophy of refusing on ambiguous operator state rather than silently forking off the wrong base.
+- **HEAD off-base, no usable local `mainRef`** (fresh-clone edge case) — or the local checkout itself fails — → **fail closed** with `{ ok:false, reason:'wrong-base' }` **unless auto-base-repair is enabled (see §6a).** The caller refuses **non-retryably** with `FAILURE_CLASS.LIVE_CHECKOUT_WRONG_BASE` (`'live-checkout-wrong-base'`; added to `engine/orchestration/dispatch.js`'s neverRetry set), writes an inbox alert naming the off-base HEAD, the expected base, and the exact `git checkout <mainRef>` recovery command, and stamps the work item `_pendingReason`. This mirrors the dirty / mid-operation philosophy of refusing on ambiguous operator state rather than silently forking off the wrong base.
 
 #### 7a. Opt-in auto-base-repair (`liveCheckoutAutoBaseRepair`, W-mr3lunnq000o9f41)
 
@@ -221,7 +221,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).
+- **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/operations/cli.js` restart re-attach path, and the `engine/orchestration/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.
 
@@ -360,38 +360,38 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 - **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.
 - **No auto-pull / no fast-forward on existing branches.** See Guarantee 3. If a PR branch is checked out locally at a different SHA than `origin/<branch>`, the operator resolves it manually.
-- **No special timeout / kill handling.** Live-mode dispatches are killed by PID exactly like isolated-mode dispatches (`engine/timeout.js` header comment). The engine sends SIGTERM/SIGKILL to the tracked process and never touches the working tree to deliver the kill. (Dispatch-end auto-restore still runs afterward — a plain branch switch back to the operator's original ref, never a reset/clean/stash; see [Dispatch-end auto-restore](#dispatch-end-auto-restore).)
+- **No special timeout / kill handling.** Live-mode dispatches are killed by PID exactly like isolated-mode dispatches (`engine/orchestration/timeout.js` header comment). The engine sends SIGTERM/SIGKILL to the tracked process and never touches the working tree to deliver the kill. (Dispatch-end auto-restore still runs afterward — a plain branch switch back to the operator's original ref, never a reset/clean/stash; see [Dispatch-end auto-restore](#dispatch-end-auto-restore).)
 
 ## Related code
 
 | 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 (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 dispatches; project-bound worktree-mode read-only types request detached worktree placement. |
-| `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` | 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 persisted-record restore wrapper; requires explicit live provenance plus current live configuration and fails closed for worktree mode. |
+| `engine/core/shared.js` — `CHECKOUT_MODES`, `validateCheckoutMode`, `resolveCheckoutMode`, `isLiveCheckoutProject` | Enum + validator + back-compat resolver (P-a3f9b201; consolidated W-mqiaw974). |
+| `engine/core/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/core/shared.js` — `resolveSpawnPaths` | Returns `{ cwd: localPath, worktreeRootDir: null, liveMode: true }` for live dispatches; project-bound worktree-mode read-only types request detached worktree placement. |
+| `engine/worktrees/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/worktrees/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/worktrees/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/worktrees/live-checkout.js` — `maybeRestoreLiveCheckoutFromRecord` | Shared persisted-record restore wrapper; requires explicit live provenance plus current live configuration and fails closed for worktree mode. |
 | `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). |
 | `engine.js` — `spawnAgent` originalRef persistence | Persists `originalRef` / `originalRefType` onto the dispatch record via `mutateDispatch` so restore survives an engine restart (P-c5a1f3b8). |
 | `engine.js` — `onAgentClose` live-mode restore wiring | Calls `restoreLiveCheckoutAtDispatchEnd` on every terminal result (P-d9e6b2c4). |
-| `engine/cli.js` — orphan / reattach restore | Fires the dispatch-end restore (via `maybeRestoreLiveCheckoutFromRecord`) from the persisted record on the engine-restart completion path (P-d9e6b2c4; unified PL-live-checkout-reliability-hardening). |
-| `engine/timeout.js` — `completeFromOutput` + orphan-sweep restore | Fires `maybeRestoreLiveCheckoutFromRecord` when a re-attached live dispatch is reaped post-restart — closes the gap where these paths had no restore wiring (PL-live-checkout-reliability-hardening). |
-| `engine/lifecycle.js` — `autoDispatchLiveValidationWi` | Creates PR-targeted validation WIs and transactionally deduplicates them by source WI plus canonical PR identity/head across central and project scopes. |
+| `engine/operations/cli.js` — orphan / reattach restore | Fires the dispatch-end restore (via `maybeRestoreLiveCheckoutFromRecord`) from the persisted record on the engine-restart completion path (P-d9e6b2c4; unified PL-live-checkout-reliability-hardening). |
+| `engine/orchestration/timeout.js` — `completeFromOutput` + orphan-sweep restore | Fires `maybeRestoreLiveCheckoutFromRecord` when a re-attached live dispatch is reaped post-restart — closes the gap where these paths had no restore wiring (PL-live-checkout-reliability-hardening). |
+| `engine/orchestration/lifecycle.js` — `autoDispatchLiveValidationWi` | Creates PR-targeted validation WIs and transactionally deduplicates them by source WI plus canonical PR identity/head across central and project scopes. |
 | `engine.js` — dispatcher `liveProjectsInUse` set | Per-project mutating-concurrency cap (P-a3f9b205). |
 | `engine.js` — worktree-pool / orphan-GC short-circuits | `worktreePath===null` no-ops in live mode (P-a3f9b206). |
-| `engine/cleanup.js` — `runPeriodicWorktreeSweep` live filter | Excludes live-checkout projects from the registry-derived periodic worktree GC so the operator's primary checkout never enters the GC decision surface (PL-live-checkout-reliability-hardening). |
-| `engine/create-pr-worktree.js` — `prepareCreatePrWorktree` | Copies pre-existing operator changes into an isolated worktree and returns `sourceCheckoutPreserved: true`; never resets, cleans, checks out, or deletes source files. |
-| `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). |
+| `engine/orchestration/cleanup.js` — `runPeriodicWorktreeSweep` live filter | Excludes live-checkout projects from the registry-derived periodic worktree GC so the operator's primary checkout never enters the GC decision surface (PL-live-checkout-reliability-hardening). |
+| `engine/worktrees/create-pr.js` — `prepareCreatePrWorktree` | Copies pre-existing operator changes into an isolated worktree and returns `sourceCheckoutPreserved: true`; never resets, cleans, checks out, or deletes source files. |
+| `engine/providers/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,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). |
-| `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_WORKTREE_CONFLICT` | Non-retryable refusal class for an existing-branch checkout that refused because the branch is already checked out in another worktree — structural, so excluded from mechanical retry (W-mr28h2j2000y0de1). |
-| `engine/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_STALE_BASE` | Non-retryable refusal class for a new-branch fork whose local `mainRef` base has diverged from `origin/<mainRef>` with unpushed commits (STALE-BASE GUARD) — detected fetch-free via `git rev-list --count origin/<mainRef>..<mainRef>`; deterministic, so excluded from mechanical retry (W-mr98op8w000ma4ad). |
+| `engine/core/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_DIRTY` | Non-retryable refusal class. |
+| `engine/core/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/core/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). |
+| `engine/core/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_WORKTREE_CONFLICT` | Non-retryable refusal class for an existing-branch checkout that refused because the branch is already checked out in another worktree — structural, so excluded from mechanical retry (W-mr28h2j2000y0de1). |
+| `engine/core/shared.js` — `FAILURE_CLASS.LIVE_CHECKOUT_STALE_BASE` | Non-retryable refusal class for a new-branch fork whose local `mainRef` base has diverged from `origin/<mainRef>` with unpushed commits (STALE-BASE GUARD) — detected fetch-free via `git rev-list --count origin/<mainRef>..<mainRef>`; deterministic, so excluded from mechanical retry (W-mr98op8w000ma4ad). |
 | `engine.js` — `_liveCheckoutDirtyAttempts` counter | Dedicated two-strike dirty memory (survives the discovery + retry `_pendingReason` scrubs that defeated #434); first dirty failure retries once, second fails non-retryably (PL-live-checkout-reliability-hardening) — **unless** `liveCheckoutAutoReset`/`liveCheckoutAutoStash` is enabled, in which case the two-strike cap is skipped entirely and the dirty failure stays retryable up to `maxRetries` (W-mqzmkoqt000hbca2, #582). |
-| `engine/dispatch.js` — `isRetryableFailureReason` neverRetry | Excludes `LIVE_CHECKOUT_DIRTY`, `LIVE_CHECKOUT_MID_OPERATION`, `LIVE_CHECKOUT_BLOB_FETCH`, and `LIVE_CHECKOUT_WORKTREE_CONFLICT` from mechanical retry. |
-| `engine/timeout.js` header comment | Confirms no special live-mode kill handling. |
+| `engine/orchestration/dispatch.js` — `isRetryableFailureReason` neverRetry | Excludes `LIVE_CHECKOUT_DIRTY`, `LIVE_CHECKOUT_MID_OPERATION`, `LIVE_CHECKOUT_BLOB_FETCH`, and `LIVE_CHECKOUT_WORKTREE_CONFLICT` from mechanical retry. |
+| `engine/orchestration/timeout.js` header comment | Confirms no special live-mode kill handling. |

package/docs/managed-spawn.md

@@ -1,7 +1,7 @@
 # Managed-spawn primitive
 
 > Engine-owned long-running services with sidecar declaration, healthcheck-gated dispatch SUCCESS, and dashboard discovery.
-> Module: [`engine/managed-spawn.js`](../engine/managed-spawn.js) · Dashboard panel: `/engine` → "Managed Processes".
+> Module: [`engine/processes/managed-spawn.js`](../engine/processes/managed-spawn.js) · Dashboard panel: `/engine` → "Managed Processes".
 
 ## Why this exists
 
@@ -57,7 +57,7 @@ The sidecar lives at `<MINIONS_DIR>/agents/<agentId>/managed-spawn.json` and is
 }
 ```
 
-The renderer in [`buildManagedSpawnHint`](../engine/managed-spawn.js) emits this exact shape (with allowlist + cap reminders) into the agent's prompt whenever the work item has `meta.managed_spawn: true`. Treat the rendered hint as the source of truth — if this doc and the hint drift, the hint wins.
+The renderer in [`buildManagedSpawnHint`](../engine/processes/managed-spawn.js) emits this exact shape (with allowlist + cap reminders) into the agent's prompt whenever the work item has `meta.managed_spawn: true`. Treat the rendered hint as the source of truth — if this doc and the hint drift, the hint wins.
 
 For an opted-in dispatch, the sidecar is mandatory. Completion acceptance reads
 only the canonical running agent's directory and requires `written_by` and
@@ -147,7 +147,7 @@ Not every managed-spawn target is a TCP-bound HTTP dev server. Native mobile/des
 }
 ```
 
-Known device-farm tooling: `adb` and `emulator` are both on the managed-spawn executable allowlist (device/emulator shell + install + logcat; `emulator -list-avds` discovers configured AVDs before picking one). `maestro` is a declarative mobile UI-flow runner already wired in as a built-in QA runner adapter (`engine/qa-runners.js`) for the DRAFT/EXECUTE phases — it is not itself on the managed-spawn `cmd`/healthcheck allowlist. The full worked example — including `ttl_minutes`, `attrs`, `written_by`/`wi_id` — is inlined in [`buildManagedSpawnHint`](../engine/managed-spawn.js).
+Known device-farm tooling: `adb` and `emulator` are both on the managed-spawn executable allowlist (device/emulator shell + install + logcat; `emulator -list-avds` discovers configured AVDs before picking one). `maestro` is a declarative mobile UI-flow runner already wired in as a built-in QA runner adapter (`engine/qa-runners/`) for the DRAFT/EXECUTE phases — it is not itself on the managed-spawn `cmd`/healthcheck allowlist. The full worked example — including `ttl_minutes`, `attrs`, `written_by`/`wi_id` — is inlined in [`buildManagedSpawnHint`](../engine/processes/managed-spawn.js).
 
 ### Non-PATH native launcher binaries (e.g. Android SDK's `emulator.exe` / `adb.exe`)
 
@@ -219,7 +219,7 @@ Single quotes (`'…'`) work the same way. No `powershell -Command "& '<path>' <
 Background work the engine does without further agent involvement:
 - **Per-tick** (cadence `engine.managedSpawn.sweepEvery: 30`, ~30 min): `sweepManagedSpawn()` drops dead-PID rows, kills + unlinks TTL-expired specs, rotates `managed-logs/<name>.log` past `logRotateBytes` (10MB).
 - **Per-engine-boot**: `bootReconcileManagedSpawn()` (timeout-bounded by `bootReconcileMaxMs: 2000` ms) drops dead PIDs, kills expired, runs one immediate healthcheck per survivor.
-- **Per-project-removal**: `removeManagedSpecsForProject(name)` (called from `engine/projects.js removeProject`) kills + unlinks specs whose `owner_project` matches.
+- **Per-project-removal**: `removeManagedSpecsForProject(name)` (called from `engine/planning/projects.js removeProject`) identity-verifies each matching process before terminating it; records whose identity cannot be observed are preserved and reported instead of risking a recycled-PID kill, while a PID whose live identity conclusively proves it is *not* the recorded child (it started after that child did) has its stale record dropped without any kill.
 
 ## WI 1 (build) → WI 2 (test) chained-validation pattern
 
@@ -235,7 +235,7 @@ The canonical use case: split a build + smoke-test workflow across two work item
 **WI 2 — test against the live service:**
 - `dependencies: [WI-1-id]` (engine won't dispatch until WI 1 is SUCCESS)
 - `meta.managed_spawn: false` (or omit — no new specs to write)
-- Playbook auto-inject (from `engine/playbook.js`) ships a `## Live managed processes for project <name>` block in WI 2's prompt with WI 1's specs' `name`, `pid`, `attrs`, `log_path`, `ttl_expires_at`, and base URL.
+- Playbook auto-inject (from `engine/agents/playbook.js`) ships a `## Live managed processes for project <name>` block in WI 2's prompt with WI 1's specs' `name`, `pid`, `attrs`, `log_path`, `ttl_expires_at`, and base URL.
 - WI 2 reads `attrs.base_url` from its prompt context, hits the live service, runs whatever test it needs to.
 
 Outcome: if WI 2 fails, the spec stays alive (TTL-managed) and the next dispatch of WI 2 reuses the same instance — no rebuild churn. If WI 1 fails healthcheck, WI 2 never dispatches; you fix WI 1 and retry.
@@ -266,8 +266,12 @@ single integer from 1 byte through 1 MiB (default 64 KiB).
 
 Both controls bind the request to the selected row's `pid` + `started_at`
 generation and verify the live OS process start identity before killing. A
-concurrent replacement, recycled PID, or failed kill returns `409` without
-deleting the surviving generation; restart also reserves the name before
+concurrent replacement, an unobservable identity, or a failed kill returns `409`
+without deleting the surviving generation. A **recycled** PID is different: when
+the live identity conclusively shows the process started after our recorded
+child, the row is stale rather than live, so it is dropped (kill returns
+`killed: false`) and the foreign PID is never signalled; restart also reserves
+the name before
 spawning so concurrent calls cannot orphan duplicate generations. Engine batch
 spawns use the same reservation protocol, first-health and boot-probe writes
 must match the reserved generation, and failed rollback kills remain as
@@ -281,7 +285,7 @@ Killing a spec from outside Minions (raw `Stop-Process`) leaves a stale SQL row
 
 ## Configuration
 
-All knobs live under `engine.managedSpawn` in `engine/shared.js` (`ENGINE_DEFAULTS.managedSpawn`). Override per install via `config.json`:
+All knobs live under `engine.managedSpawn` in `engine/core/shared.js` (`ENGINE_DEFAULTS.managedSpawn`). Override per install via `config.json`:
 
 | Key | Default | Notes |
 |---|---|---|
@@ -308,7 +312,7 @@ All knobs live under `engine.managedSpawn` in `engine/shared.js` (`ENGINE_DEFAUL
 | Dispatch ERROR `failure_class: invalid-managed-spawn` | Sidecar schema/allowlist violation | Read inbox alert; the validator includes a precise reason. Non-retryable — fix and re-dispatch. |
 | Dispatch ERROR `failure_class: managed-spawn-healthcheck-failed` | The target exited before first health, or `timeout_s` elapsed before it became healthy | Check the reported code/signal and bounded `engine/managed-logs/<name>.log` tail. Sibling spawns are left alive. |
 | WI shows yellow `⚠ managed-spawn: N/M healthy` chip on dashboard | Partial healthcheck failure: ≥1 spec passed, ≥1 failed. WI keeps `status: done` (the agent's primary work — getting an accepted sidecar — succeeded); annotation `_managedSpawnPartial = { healthy, failed[{name, reason, log_tail}], evaluated_at }` lives on the WI. Click the row to see per-spec failure reasons + last 20 log lines. Dispatch is still recorded ERROR with `failure_class: managed-spawn-healthcheck-failed`. Restart the failing spec via `POST /api/managed-processes/restart` once you've fixed the root cause (often: workspace deps not installed; see smoke-test rule in the hint). W-mpbpexrg00110661. |
-| Spec gone after `minions restart` | The tracked Node launcher died or boot reconciliation dropped its PID | Inspect the managed log and verify `engine/managed-spawn-launcher.js` remained the process-tree root until the target exited. |
+| Spec gone after `minions restart` | The tracked Node launcher died or boot reconciliation dropped its PID | Inspect the managed log and verify `engine/processes/managed-spawn-launcher.js` remained the process-tree root until the target exited. |
 | Spec listed `alive: true, healthy: false` for >30s | Healthcheck loop self-detected service degradation | The spec did not pass a subsequent healthcheck. Inspect the service; restart via API once recovered. |
 | Stale row sticks around with dead PID | Spec killed outside Minions | Wait one sweep cycle (~30 min) or call `POST /api/managed-processes/kill` manually. |
 
@@ -323,15 +327,15 @@ All knobs live under `engine.managedSpawn` in `engine/shared.js` (`ENGINE_DEFAUL
 
 | File | Purpose |
 |---|---|
-| `engine/managed-spawn.js` | Schema, validator, spawn, healthcheck, sweep, state-file I/O. All pure helpers; no side effects on import. |
+| `engine/processes/managed-spawn.js` | Schema, validator, spawn, healthcheck, sweep, state-file I/O. All pure helpers; no side effects on import. |
 | `engine.js` `onAgentClose` (line ~2247) | Acceptance gate (item 2) + healthcheck gate (item 3) wired into dispatch result. |
 | `engine.js` `tickInner` (line ~5687) | Per-30-tick `sweepManagedSpawn()` invocation. |
-| `engine/cli.js` | Boot-path `bootReconcileManagedSpawn()` invocation. |
-| `engine/playbook.js` | Auto-inject `## Live managed processes` block + `managed_spawn` hint section. |
-| `engine/projects.js` `removeProject` | `removeManagedSpecsForProject` cleanup hook. |
+| `engine/operations/cli.js` | Boot-path `bootReconcileManagedSpawn()` invocation. |
+| `engine/agents/playbook.js` | Auto-inject `## Live managed processes` block + `managed_spawn` hint section. |
+| `engine/planning/projects.js` `removeProject` | `removeManagedSpecsForProject` cleanup hook. |
 | `dashboard.js` | 5 routes (`/api/managed-processes`, `…/by-name/<n>`, `…/kill`, `…/restart`, `…/log-stream/<n>`). |
 | `dashboard/js/render-managed.js` + `dashboard/pages/engine.html` | "Managed Processes" panel + log-viewer modal. |
-| `engine/shared.js` `ENGINE_DEFAULTS.managedSpawn` | All configurable knobs in one place. |
+| `engine/core/shared.js` `ENGINE_DEFAULTS.managedSpawn` | All configurable knobs in one place. |
 
 ## Plan items
 

package/docs/named-agents.md

@@ -48,7 +48,7 @@ The full per-agent config shape supported under `config.agents.<id>`:
 ### Three-tier resolution chain
 
 Most knobs resolve **per-agent override → `engine.*` fleet default → runtime default**.
-The resolver helpers live in [`engine/shared.js`](../engine/shared.js):
+The resolver helpers live in [`engine/core/shared.js`](../engine/core/shared.js):
 
 | Helper | Chain |
 |--------|-------|
@@ -73,7 +73,7 @@ but only as the middle tier.
 ### Workspace manifest (optional)
 
 `agents.<id>.workspace_manifest` declares declarative permission scoping. Shape and
-defaults (`WORKSPACE_MANIFEST_DEFAULTS` in `engine/shared.js`):
+defaults (`WORKSPACE_MANIFEST_DEFAULTS` in `engine/core/shared.js`):
 
 | Key | Default | Effect |
 |-----|---------|--------|
@@ -82,7 +82,7 @@ defaults (`WORKSPACE_MANIFEST_DEFAULTS` in `engine/shared.js`):
 | `allowed_external_urls` | `null` (permissive) | URL allow-list (supports `*.example.com` wildcards). |
 | `memory_scope` | `'shared'` | One of `private`, `shared`, `read-only-shared`. |
 
-Enforcement helpers (also in `engine/shared.js`): `validateWorkspaceManifest`,
+Enforcement helpers (also in `engine/core/shared.js`): `validateWorkspaceManifest`,
 `resolveAgentManifest`, `agentCanUseRepo`, and `mergeManifestAllowedTools`. Today the
 engine actively enforces (a) the
 **repo gate** at dispatch time in `engine.js spawnAgent`
@@ -146,7 +146,7 @@ alternate is available it stays with the same agent and dedups an engine inbox n
 `agentLock: true` (or `hardAgent: true`) hard-pins the agent and bypasses reassignment —
 operator intent wins. The counter is cleared on successful completion alongside
 `_retryCount`. Helpers: `bumpAgentRetryCount`, `getAgentRetryCount`,
-`resolveMaxRetriesPerAgent` in `engine/shared.js`.
+`resolveMaxRetriesPerAgent` in `engine/core/shared.js`.
 
 ## 4. How skills are defined
 
@@ -163,7 +163,7 @@ an `expertise ?? skills` fallback — see [`docs/deprecated.json`](deprecated.js
 **(b) Real runtime skills** — `SKILL.md` files the runtime CLI actually loads. These are
 auto-extracted from agent output: when an agent emits a fenced ```` ```skill ```` block
 (with YAML frontmatter carrying at least a `name`), `extractSkillsFromOutput` in
-[`engine/lifecycle.js`](../engine/lifecycle.js) writes it out. The engine also scans
+[`engine/orchestration/lifecycle.js`](../engine/orchestration/lifecycle.js) writes it out. The engine also scans
 `notes/inbox/` notes for skill blocks, since agents often write them there instead of stdout.
 
 - **`scope: minions`** (the default when `scope` is omitted) → written to the runtime's
@@ -198,7 +198,7 @@ convention is documented in
 [`knowledge/agents/README.md`](../knowledge/agents/README.md).
 
 **Written exclusively by the consolidation pipeline.** `appendToAgentMemory` in
-[`engine/consolidation.js`](../engine/consolidation.js) routes each `notes/inbox/` finding
+[`engine/memory/consolidation.js`](../engine/memory/consolidation.js) routes each `notes/inbox/` finding
 to its author's file. Authorship comes from the inbox note's YAML frontmatter `agent:`
 field, with the **filename prefix** (`<agent>-…md`) as fallback (`extractInboxAgent`). Key
 properties:
@@ -213,7 +213,7 @@ properties:
   set; `temp-*` ids are skipped. This is a strict superset of broadcast consolidation: the
   shared `notes.md` digest still happens; per-agent routing is *in addition*.
 
-**Prompt memory modes.** [`engine/playbook.js`](../engine/playbook.js) always
+**Prompt memory modes.** [`engine/agents/playbook.js`](../engine/agents/playbook.js) always
 places non-empty `pinned.md` first. Default active retrieval then injects a
 bounded `Relevant Memory` pack when it finds evidence. If retrieval is disabled,
 shadowed, empty, or fails, the engine instead injects bounded `notes.md` followed