@yemi33/minions 0.1.2345 → 0.1.2346

package/dashboard.js

@@ -10050,13 +10050,28 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         },
         onDone: () => {
           _emitTimingLog(_lifecycle, _tSessionReady, Date.now(), 'done');
-          resolveResult({ text: accumulated, sessionId: sessionHandle.sessionId, code: 0, usage: {}, raw: accumulated, stderr: '' });
+          // W-mrax0he4000kc90d — resolve with ONLY the trailing segment's
+          // text, not the full accumulated turn. ccSegmentsFinalize's
+          // contract (dashboard/js/render-utils.js) is that its finalText
+          // argument is the trailing/last text segment only — the same
+          // contract onChunk already honors via `accumulated.slice(segmentStart)`
+          // (W-mqvakva3000i3325). Resolving with the full multi-segment
+          // `accumulated` buffer here welds every earlier segment onto the
+          // end of the message via _ccSegMergeText's "distinct — never weld"
+          // branch, visibly duplicating the whole prior turn for any
+          // response with >=1 mid-turn tool call. `raw` still carries the
+          // full turn (logging/telemetry only — never rendered).
+          resolveResult({ text: accumulated.slice(segmentStart), sessionId: sessionHandle.sessionId, code: 0, usage: {}, raw: accumulated, stderr: '' });
         },
         onError: (err) => {
           _emitTimingLog(_lifecycle, _tSessionReady, Date.now(), cancelled ? 'cancelled' : 'error');
           if (cancelled) {
+            // Same trailing-segment contract as onDone above — a mid-stream
+            // cancel (e.g. user hits "stop") can still reach the SSE 'done'
+            // frame with text accumulated so far, so it must not leak the
+            // full multi-segment buffer either.
             resolveResult({
-              text: accumulated,
+              text: accumulated.slice(segmentStart),
               sessionId: sessionHandle.sessionId,
               code: 0,
               usage: {},
@@ -10599,7 +10614,14 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           finishMissingRuntime(result, liveState);
           return;
         }
-        if (!result.text || result.error) {
+        // W-mrax0he4000kc90d — `result.text` from the pool path is now the
+        // TRAILING segment only (see _invokeCcStreamViaPool's onDone), which
+        // is legitimately empty when a turn ends right on a tool call with
+        // no closing prose. That's a real success, not "no output" — so also
+        // check `result.raw` (always the full accumulated turn) before
+        // treating an empty `text` as a failure. A genuinely empty turn has
+        // both text and raw empty.
+        if ((!result.text && !result.raw) || result.error) {
           if (req.destroyed) {
             _ccStreamEnded = true;
             _logCcStreamEnd(_ccTelemetry, 'llm-empty-client-gone', { code: result.code });

package/docs/README.md

@@ -40,6 +40,7 @@ Architecture, design proposals, and lifecycle references for people working on t
 - [pr-comment-followup.md](pr-comment-followup.md) — PR-comment follow-up dispatch contract: fix/review agents may spin off a new WI via `POST /api/work-items` with `meta.pr_followup` instead of broadening the current PR or rebutting the comment.
 - [pr-review-fix-loop.md](pr-review-fix-loop.md) — How the engine moves a PR from creation through review, fix dispatch, and re-review, including stale-status guards.
 - [project-skills.md](project-skills.md) — Project-local skill discovery (`.claude/skills/`, `.claude/commands/`, `CLAUDE.md` / `.github/copilot-instructions.md` slash-command mentions): how dispatched agents see and steer toward purpose-built tooling the project ships, plus the intent-vocabulary contract.
+- [proposals/repo-pool-for-live-checkout.md](proposals/repo-pool-for-live-checkout.md) — Review-only artifact reproducing the approved plan + PRD for a repo pool covering live-checkout projects (multi-enlistment dispatch), so the design has a git-tracked surface for human comment before the dependent implementation work items land as code PRs.
 - [qa-runbook-lifecycle.md](qa-runbook-lifecycle.md) — End-to-end QA runbook lifecycle (W-mpeiwz6k0005bf34): runbook + run-record storage, `POST /api/qa/runbooks/run` dispatch into the `qa-validate` playbook, artifact contract, and how the `/qa` page mirrors managed-spawn observability.
 - [qa-runbooks.md](qa-runbooks.md) — Per-project QA runbook schema, storage layout (`projects/<name>/runbooks/<id>.json`), CRUD endpoints, run-record lifecycle, and the `qa-validate` agent sidecar contract.
 - [rfc-completion-json.md](rfc-completion-json.md) — RFC for replacing stdout regex-scraping with a structured `completion.json` control-plane protocol.

package/docs/completion-reports.md

@@ -278,6 +278,7 @@ Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated s
 |---|---|---|
 | `config-error` | CLI not found, exit code 78, malformed config | Never retry |
 | `permission-blocked` | Trust gate, permission denied, auth failure | Never retry |
+| `auth` | Git/network credential failure (e.g. ADO bearer-token acquire or GCM prompt) — structural | Never retry |
 | `merge-conflict` | Git merge conflict in worktree or dependency | Retry same agent |
 | `build-failure` | Compilation, lint, or test failure introduced by the agent | Retry same agent |
 | `timeout` | Hard runtime timeout or stale-orphan timeout | Retry with fresh session |
@@ -288,8 +289,30 @@ Defined in `engine/shared.js` as `FAILURE_CLASS`. Use the canonical hyphenated s
 | `max-turns` | Claude CLI `error_max_turns` — work in progress | Retry same agent |
 | `completion-nonce-mismatch` | Completion JSON missing or mismatched `nonce` (forged completion). See [Trust boundary](#trust-boundary). | Never retry (untrusted) |
 | `worktree-preflight` | Pre-spawn worktree validation rejected the dispatch (nested-in-project, drive-root collapse, missing base). See [Pre-spawn preflight vs agent failure](#pre-spawn-preflight-vs-agent-failure). | Never retry |
+| `worktree-dirty` | Reused worktree had uncommitted edits the engine could not auto-heal (#2996) | Never retry this dispatch (fresh worktree next cycle) |
+| `worktree-divergent` | Reused worktree's local branch was ahead of origin — unsafe to reset (#2996) | Never retry this dispatch (worktree quarantined) |
+| `worktree-quarantine-env-blocked` | Quarantine rename failed because the OS wouldn't release the worktree dir (Windows EBUSY/EPERM/EACCES) | Retry — re-queued without bumping the per-agent retry counter |
+| `dependency-merge-setup` | Dependency pre-merge plumbing (stash/status/reset) failed before a real file conflict was verified | Retry — fresh worktree can recover |
+| `invalid-keep-processes-workdir` | `keep-pids.json` declared a cwd that isn't a real git worktree | Never retry until the agent reruns in a real worktree |
+| `invalid-keep-processes-schema` | `keep-pids.json` failed schema validation (pids-missing, ttl-too-long, etc.) | Never retry until the agent fixes the file |
+| `invalid-managed-spawn` | `agents/<id>/managed-spawn.json` failed the validator (bad schema, workdir, allowlist, healthcheck shape) | Never retry as-is — agent must fix the file |
+| `managed-spawn-healthcheck-failed` | A managed-spawn spec spawned but failed its healthcheck within `timeout_s`; failing PIDs killed, siblings kept alive | Flag for human review (log tail in inbox alert) |
+| `injection-flagged` | Agent set `securityFlags.injectionAttempt:true` after spotting a prompt-injection attempt in an `<UNTRUSTED-INPUT>` fence | Never retry — human reviews the source |
 | `live-checkout-dirty` | Live-checkout project tree had uncommitted changes; engine refused to spawn in-place. See [Pre-spawn preflight vs agent failure](#pre-spawn-preflight-vs-agent-failure). | Never retry |
+| `live-checkout-failed` | `prepareLiveCheckout` threw before spawn (helper guard, ref validation, transient git error) — distinct from confirmed-dirty | Retry with bounded backoff (up to `maxRetries`) |
+| `live-checkout-mid-operation` | Operator tree is mid-operation (in-progress merge/rebase/cherry-pick/bisect) or detached HEAD | Never retry — operator must finish/abort first |
+| `live-checkout-blob-fetch` | `git checkout` failed materializing the tree on a blobless/GVFS-partial clone — deterministic, not transient | Never retry — operator hydrates the branch with their own credentials |
+| `live-checkout-worktree-conflict` | Target branch is already checked out in a second worktree elsewhere — structural, doesn't clear on retry | Never retry — operator removes/reassigns the other worktree |
+| `live-checkout-wrong-base` | New-branch fork requested but operator HEAD is on an unrelated branch, not the project base | Never retry — operator checks out `mainRef` first (or enable `liveCheckoutAutoBaseRepair`) |
+| `invalid-workdir` | Dispatch carried a `meta.workdir` override that failed validation (absolute path, `..` segment, escape, etc.) | Never retry until the WI's `meta.workdir` is fixed |
+| `model-unavailable` | Requested model returned `overloaded_error` / 503 / service unavailable | Retry — engine swaps in the runtime-appropriate fallback model |
 | `workspace-manifest-repo-forbidden` | Dispatch routed an agent to a repo not in its `workspace_manifest.allowed_repos`. See [Pre-spawn preflight vs agent failure](#pre-spawn-preflight-vs-agent-failure). | Never retry |
+| `workspace-manifest-tool-forbidden` | Out-of-scope tool call caught by manifest enforcement at the runtime gate | Never retry as-is |
+| `workspace-manifest-url-forbidden` | Out-of-scope external URL fetch caught by manifest enforcement | Never retry as-is |
+| `spawn-phase-stall` | Process spawned and ran startup-only events (MCP init/hooks) but never emitted real task progress before the grace window | Retry — fresh session clears a transient MCP wedge |
+| `output-truncated` | Agent streamed more stdout than the engine's hard capture cap before the terminal `result` event arrived | Never retry — agent must reduce output volume or split the task |
+| `verify-missing-pr` | A verify WI exited `done` but no PR was attached | Retry — agent may have phantom-crashed before pushing |
+| `project_not_found` | A work item's `project` field names a project that isn't configured | Never retry until the WI's `project` field or config is fixed |
 | `unknown` | Unclassified failure | Default retry logic |
 
 Use `"N/A"` when `status` is `success` or `partial` without a failure.

package/docs/kb-sweep.md

@@ -4,31 +4,61 @@ How the `knowledge/` directory stays curated, deduplicated, and small enough to
 
 ## What the Sweep Does
 
-The KB sweep is a 3-pass cycle implemented in [`engine/kb-sweep.js`](../engine/kb-sweep.js) that prunes duplicate, 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/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.
 
 ```
 Entries in knowledge/<category>/*.md
-  → Pass 1: Hash dedup        (cheap, no LLM)
-  → Pass 2: LLM batch sweep   (Haiku, batches of 30)
-  → Pass 2.5: Age-TTL expiry  (per-category, no LLM)
-  → Pass 3: Per-entry rewrite (Haiku, concurrency 5)
-  → Prune _swept/ archive     (>30 days)
+  → Pass 1:   Hash dedup             (cheap, no LLM)
+  → Pass 1.5: Structural consolidation (cheap, no LLM — PRIMARY balloon fix)
+  → Pass 2:   LLM batch sweep        (Haiku, batches of 30)
+  → Pass 2.5: Age-TTL expiry         (per-category, no LLM — secondary safety net)
+  → Pass 3:   Per-entry rewrite      (Haiku, concurrency 5)
+  → Prune _swept/ archive            (>30 days)
   → Invalidate KB cache, write engine/kb-swept.json
 ```
 
-## The 3-Pass Cycle
+> **Why consolidation is the primary fix.** Hash dedup only catches *near-exact* re-postings, and the LLM batch pass only compares entries *within* a 30-entry batch. The dominant balloon source — hundreds of one-off boilerplate notes (agent-failure dumps, no-op / merge-conflict fix reports) that differ only by work-item / date / dispatch id — is never collapsed by those passes: each note is unique by PR#/date and is spread across dozens of batches. Pass 1.5 groups those notes *structurally* and rolls each large group into a single recoverable digest, shrinking the KB even for **recent** entries. The age-TTL pass (2.5) is retained only as a secondary safety net for genuinely stale one-offs that never clustered into a digest.
+
+## The Pass Cycle
 
 ### Pass 1 — Hash Dedup
 
 Cheap, deterministic. No LLM call.
 
-For every entry, compute `sha256(normalize(content).slice(0,500) + ':' + content.length)` (source: [`engine/kb-sweep.js:29`](../engine/kb-sweep.js#L29)). 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 (source: [`engine/kb-sweep.js:84-105`](../engine/kb-sweep.js#L84)).
+For every entry, compute `sha256(normalize(content).slice(0,500) + ':' + content.length)` (source: [`engine/kb-sweep.js:33-35`](../engine/kb-sweep.js#L33)). 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:60-69`](../engine/kb-sweep.js#L60), called at [`:165`](../engine/kb-sweep.js#L165)).
 
 This catches near-identical re-postings across batches that the LLM pass might miss because they land in different batches.
 
+### Pass 1.5 — Structural Consolidation (primary balloon fix)
+
+Cheap, deterministic. No LLM call. This is the pass that actually stops `knowledge/` from ballooning: it collapses **structural duplication**, not just exact duplication.
+
+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`).
+
+- **Signature** = `category :: agent :: kind :: time-bucket`. `kind` is derived from the note (source: [`engine/kb-sweep.js`](../engine/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.
+- **Time-bucket** = the start date of the `periodDays` window the note's authored date falls in (default one digest per agent/kind per **week** — source: `_periodBucket`).
+- **Digest** is written to `<category>/_digest-<agent>-<kind>-<period>.md` with `source: kb-consolidation` and a `_digest:` frontmatter flag. Its body is a compact roll-up table (one row per collapsed note: date, work item, dispatch, failureClass, one-line reason, and the original filename for recovery). Re-running the sweep **merges** new rows into the existing digest keyed on the original filename, so repeated sweeps accumulate rather than clobber.
+- **Digests are never re-consolidated or rewritten** — `_isDigestEntry()` excludes them from Pass 1.5 grouping and from the Pass 3 rewrite (which would otherwise destroy the table).
+
+Only categories in `ENGINE_DEFAULTS.kbConsolidation.categories` are eligible; durable categories (`architecture`, `conventions`) and per-agent memory (`knowledge/agents/`, never scanned) are never consolidated. Config is overridable per-fleet via `config.engine.kbConsolidation` (merged over the defaults):
+
+| Key | Default | Meaning |
+|-----|---------|---------|
+| `enabled` | `true` | Set `false` (or `categories: []`) to disable the pass. |
+| `categories` | `['project-notes', 'build-reports', 'reviews']` | Only these are consolidated. |
+| `minGroupSize` | `5` | A group collapses only once it reaches this many near-duplicate notes. |
+| `periodDays` | `7` | One digest per (agent, kind) per this many days. |
+
+Because originals are archived to `_swept/` (same 30-day retention as every other pass), consolidation is fully recoverable for ~30 days.
+
 ### 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:25`](../engine/kb-sweep.js#L25)). Each batch prompt asks for three lists in JSON:
+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:
 
 | Field | What the LLM looks for |
 |-------|------------------------|
@@ -36,15 +66,15 @@ The remaining survivors are sent to Claude Haiku in batches of `LLM_BATCH_SIZE =
 | `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:243-279`](../engine/kb-sweep.js#L243)).
+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)).
 
 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:139-151`](../engine/kb-sweep.js#L139)).
+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)).
 
-### Pass 2.5 — Age-Based TTL Expiry
+### Pass 2.5 — Age-Based TTL Expiry (secondary safety net)
 
-Cheap, deterministic. No LLM call. This pass is what keeps the KB from ballooning indefinitely: the dedup and rewrite passes can only reclaim *duplicate* or *empty* entries, but the highest-volume categories (`project-notes`, `build-reports`, `reviews`) are dominated by **one-off, PR/incident-scoped notes** that are each unique by PR#/date. Nothing in Passes 1–3 can ever remove them, so without an age cutoff they accumulate forever.
+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:
 
@@ -64,30 +94,30 @@ Because expiry archives to `_swept/` (subject to the same 30-day retention as ev
 
 ### Pass 3 — Per-Entry Rewrite
 
-Survivors of Passes 1 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:26`](../engine/kb-sweep.js#L26)). Each 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/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:
 
 - 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:229`](../engine/kb-sweep.js#L229)).
+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 `_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:229`](../engine/kb-sweep.js#L229)).
-- **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:196-202`](../engine/kb-sweep.js#L196)).
+- **Set** to `new Date().toISOString()` whenever the rewrite pass successfully rewrites the body (source: [`engine/kb-sweep.js:293`](../engine/kb-sweep.js#L293)).
+- **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:260-264`](../engine/kb-sweep.js#L260)).
 - **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: [`engine/kb-sweep.js:27,429`](../engine/kb-sweep.js#L27)).
+The flag key is exported as `SWEPT_FLAG_KEY` for tests (source: defined [`engine/kb-sweep.js:31`](../engine/kb-sweep.js#L31), exported [`:785`](../engine/kb-sweep.js#L785)).
 
 ## 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:23,69-81`](../engine/kb-sweep.js#L23)).
+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)).
 
 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.
 
@@ -100,7 +130,7 @@ The dashboard exposes two endpoints:
 | `POST` | `/api/knowledge/sweep` | Start a sweep in the background. Returns `202 { ok: true, started: true }` (source: [`dashboard.js:7351`](../dashboard.js#L7351), [`dashboard.js:4285`](../dashboard.js#L4285)). |
 | `GET`  | `/api/knowledge/sweep/status` | Poll `{ inFlight, startedAt, lastResult, lastCompletedAt }` (source: [`dashboard.js:7352`](../dashboard.js#L7352), [`dashboard.js:4335`](../dashboard.js#L4335)). |
 
-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:345-356`](../engine/kb-sweep.js#L345)).
+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:555-561`](../engine/kb-sweep.js#L555)).
 
 ```bash
 # Trigger a sweep
@@ -116,7 +146,7 @@ curl http://localhost:7331/api/knowledge/sweep/status
 
 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:4306-4311`](../dashboard.js#L4306)).
 
-The guard auto-releases when the sweep has been running longer than `staleGuardMs(entryCount)` — `max(30 min, 1 s × entryCount)` — which protects against a dashboard process that died mid-sweep leaving the flag stuck (source: [`engine/kb-sweep.js:413-417`](../engine/kb-sweep.js#L413), [`dashboard.js:4286-4305`](../dashboard.js#L4286)).
+The guard auto-releases when the sweep has been running longer than `staleGuardMs(entryCount)` — `max(30 min, 1 s × entryCount)` — which protects against a dashboard process that died mid-sweep leaving the flag stuck (source: [`engine/kb-sweep.js:758-761`](../engine/kb-sweep.js#L758), [`dashboard.js:4286-4305`](../dashboard.js#L4286)).
 
 ### Persistent State
 
@@ -133,7 +163,7 @@ Sweep state is mirrored to `engine/kb-sweep-state.json` so the dashboard can rec
 { "status": "failed", "startedAt": ..., "completedAt": ..., "error": "..." }
 ```
 
-Memory still wins when present; the disk file is a fallback (source: [`engine/kb-sweep.js:298-320`](../engine/kb-sweep.js#L298), [`dashboard.js:4296-4354`](../dashboard.js#L4296)). A separate `engine/kb-swept.json` is written after each successful sweep with the human-readable summary line shown by the dashboard's "swept N days ago" badge (source: [`engine/kb-sweep.js:407`](../engine/kb-sweep.js#L407)).
+Memory still wins when present; the disk file is a fallback (source: [`engine/kb-sweep.js:372-410`](../engine/kb-sweep.js#L372) `readSweepLiveness()`, [`dashboard.js:4296-4354`](../dashboard.js#L4296)). A separate `engine/kb-swept.json` is written after each successful sweep with the human-readable summary line shown by the dashboard's "swept N days ago" badge (source: [`engine/kb-sweep.js:626`](../engine/kb-sweep.js#L626)).
 
 ## Automatic Periodic Sweep (opt-in)
 
@@ -164,6 +194,9 @@ The KB page is refreshed by the dashboard's main refresh loop **every third tick
   entriesBefore, entriesAfter,
   bytesBefore,  bytesAfter,
   hashDuplicatesArchived,  // Pass 1
+  notesConsolidated,       // Pass 1.5 (boilerplate notes rolled into digests)
+  consolidationGroups,     // Pass 1.5 (groups collapsed)
+  digestsWritten,          // Pass 1.5 (digest files written/updated)
   llmDuplicatesArchived,   // Pass 2 (within-batch dupes)
   staleRemoved,            // Pass 2 (LLM-flagged removals)
   ageExpired,              // Pass 2.5 (per-category age-TTL archival)
@@ -172,11 +205,11 @@ The KB page is refreshed by the dashboard's main refresh loop **every third tick
   rewriteBytesBefore, rewriteBytesAfter,
   sweptArchivePruned,      // Files purged from _swept/ (>30 days)
   durationMs,
-  summary: '<n> hash-dup, <n> llm-dup, <n> stale, <n> age-expired, <n> reclassified, <n> rewritten (<bytes> saved)',
+  summary: '<n> hash-dup, <n> consolidated (<n> digests), <n> llm-dup, <n> stale, <n> age-expired, <n> reclassified, <n> rewritten (<bytes> saved)',
 }
 ```
 
-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:408`](../engine/kb-sweep.js#L408)).
+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:627`](../engine/kb-sweep.js#L627)).
 
 ## What NOT to Do
 

package/docs/live-checkout-mode.md

@@ -18,9 +18,9 @@ The default `worktree` mode spawns each dispatch inside its own git worktree und
 
 For these repos, the operator usually already has one canonical checkout that builds correctly. Live-checkout mode lets the agent dispatch into that checkout instead of cloning a side-by-side copy.
 
-## Contract (five guarantees)
+## Contract (six guarantees)
 
-Live mode is opinionated about what the engine will and will not do to the operator's tree. The contract has five guarantees; the engine enforces all five and fails dispatches that would violate them.
+Live mode is opinionated about what the engine will and will not do to the operator's tree. The contract has six guarantees; the engine enforces all six and fails dispatches that would violate them.
 
 ### 1. Per-project mutating-concurrency cap of 1
 
@@ -125,7 +125,28 @@ Pool short-circuits live in `engine.js:1368` and `engine/cleanup.js`; both gate
 
 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.
 
-### 6. Refuse on stale non-main base when forking a new branch (W-mr3lunnq000o9f41)
+### 6. STALE-BASE GUARD — refuse to fork off a diverged local base (W-mr98op8w000ma4ad)
+
+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).
+
+It survives the dirty check (Guarantee 2) because the contamination is **committed**, not uncommitted, and it cannot be caught by a "HEAD is on the wrong branch" check because here HEAD **is** on `mainRef`.
+
+The guard detects it **without a fetch** (preserving issue #226's no-forced-fetch guarantee) by comparing the local `refs/heads/<mainRef>` tip against the **already-present** `refs/remotes/origin/<mainRef>` remote-tracking ref:
+
+```
+git rev-list --count refs/remotes/origin/<mainRef>..<mainRef>   # > 0 ⇒ local base is ahead / contaminated
+```
+
+A count `> 0` returns `{ ok:false, reason:'stale-main', mainRef, ahead, localMainSha, originMainSha, branch, originalRef, originalRefType }`. Being merely *behind* `origin/<mainRef>` (fewer commits) is **not** flagged — that just yields a branch off an older tip, not contamination — so only the local-ahead side is counted. The guard **skips** (proceeds normally) when:
+
+- HEAD is not on `mainRef` (the fork base is something the operator/engine deliberately parked there — out of scope);
+- no local `origin/<mainRef>` remote-tracking ref exists (local-only / no-remote repo — comparison would require the forbidden fetch, and the contamination class only exists when an origin baseline is present to diverge from);
+- the divergence count cannot be computed (a transient `rev-list` failure must not become a permanent refusal).
+
+`spawnAgent` completes the dispatch non-retryably with the dedicated **`FAILURE_CLASS.LIVE_CHECKOUT_STALE_BASE`** (`'live-checkout-stale-base'`; in `dispatch.js`'s `neverRetry` set) plus a `live-checkout-stale-base-<wi-id>` inbox alert and a `_pendingReason: 'live_checkout_stale_base'` stamp — instead of `LIVE_CHECKOUT_FAILED` (retryable) retry-storming an identical structural failure to `maxRetries`. The engine **never** resets, cleans, or rebases the operator's local `mainRef` — surfacing it as a refusal keeps history rewrites in the operator's hands, consistent with the dirty and mid-operation refusals. The alert's recovery guidance offers two paths: salvage the extra commits onto their own branch then `git reset --hard origin/<mainRef>`, or discard them with the same reset — either leaves `mainRef` matching `origin/<mainRef>` so the next dispatch forks off a clean base.
+
+
+### 7. Refuse on stale non-main base when forking a new branch (W-mr3lunnq000o9f41)
 
 When a live-checkout dispatch needs a **new** branch, `git checkout -b <branch>` seeds it from the operator's **current HEAD** (issue #226 — live mode never fetches `origin/<mainRef>` to avoid auth-less GVFS blob fetches). That is safe only when HEAD is already on the project's base branch. If a human — or a prior dispatch — left the operator checkout sitting on some unrelated topic/feature branch, the new branch (and therefore its PR) would silently inherit **every commit already on that topic branch**. This is scope contamination baked into git history, not a stray uncommitted diff, so it survives the dirty-tree (Guarantee 2) and mid-operation (Guarantee 5) preflights, which only check for uncommitted changes / in-progress ops, never *"is HEAD on the expected base?"*. The motivating incident is ADO PR `!5411214`, which silently carried ~22 unrelated OCM files the PR author disavowed.
 
@@ -136,12 +157,12 @@ Immediately before the new-branch `git checkout -b`, `prepareLiveCheckout` compa
 - **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.
 
-#### 6a. Opt-in auto-base-repair (`liveCheckoutAutoBaseRepair`, W-mr3lunnq000o9f41)
+#### 7a. Opt-in auto-base-repair (`liveCheckoutAutoBaseRepair`, W-mr3lunnq000o9f41)
 
 The fail-closed refusal above is safe but forces a manual `git checkout <mainRef>` before every re-dispatch. Enabling **`liveCheckoutAutoBaseRepair`** (per-project `project.liveCheckoutAutoBaseRepair` > fleet-wide `engine.liveCheckoutAutoBaseRepair` > **`false`**, resolved by `shared.resolveLiveCheckoutAutoBaseRepair`) lets the engine self-heal the *missing-local-base* case:
 
 - When HEAD is off-base **and** there is no local `refs/heads/<mainRef>` **but** a `refs/remotes/origin/<mainRef>` remote-tracking ref exists, the guard materializes a local base branch from it — `git branch --no-track <mainRef> refs/remotes/origin/<mainRef>` — then proceeds exactly like the local-base path (plain `git checkout <mainRef>`, then fork).
-- **Issue #226 is preserved:** `origin/<mainRef>` is consumed as a **local ref** — there is **no `git fetch`**. `origin/<mainRef>` is the *correct* project base, so there is **no scope-contamination risk** (the entire point of Guarantee 6 survives — it never forks off the stale topic HEAD).
+- **Issue #226 is preserved:** `origin/<mainRef>` is consumed as a **local ref** — there is **no `git fetch`**. `origin/<mainRef>` is the *correct* project base, so there is **no scope-contamination risk** (the entire point of Guarantee 7 survives — it never forks off the stale topic HEAD).
 - **Bounded, degrades safely:** the subsequent `git checkout <mainRef>` may hydrate blobs on a partial clone (the one operation issue #226 flagged as hang-prone in headless sessions). It is bounded by the git-wrapper timeout; on failure/hang it falls through to the **same** fail-closed `wrong-base` refusal — strictly no worse than the non-repair path.
 - **Still fail-closed** when neither a local base nor an `origin/<mainRef>` tracking ref exists, or when the base checkout itself fails. Default **OFF**.
 
@@ -308,6 +329,7 @@ Live-checkout mode is deliberately small. These are NOT supported and will not b
 | `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.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. |

package/engine/dispatch.js

@@ -749,6 +749,7 @@ function isRetryableFailureReason(reason = '', failureClass = '') {
       FAILURE_CLASS.LIVE_CHECKOUT_MID_OPERATION, // P-a7f3c1d9 — live-checkout refused to spawn because the operator tree is mid-operation (in-progress merge/rebase/cherry-pick/bisect or detached HEAD); mechanical retry won't fix it (operator must finish/abort the op or checkout a branch)
       FAILURE_CLASS.LIVE_CHECKOUT_BLOB_FETCH, // PL-live-checkout-reliability-hardening — live-checkout `git checkout <existing-branch>` failed hydrating the tree through the auth-less GVFS cache server (blobless partial clone, headless); deterministic, so mechanical retry just reproduces it (operator must hydrate the branch with their own creds, then re-dispatch)
       FAILURE_CLASS.LIVE_CHECKOUT_WORKTREE_CONFLICT, // W-mr28h2j2000y0de1 — live-checkout `git checkout <existing-branch>` failed because that branch is already checked out in another worktree; structural conflict, so mechanical retry just reproduces it (operator must `git worktree remove` the other tree or finish its WIP, then re-dispatch)
+      FAILURE_CLASS.LIVE_CHECKOUT_STALE_BASE, // W-mr98op8w000ma4ad — live-checkout STALE-BASE GUARD refused to fork a new branch off a local mainRef that has diverged from origin/<mainRef> with unpushed commits; contaminated local base does not change on retry (operator must reconcile the local base branch — the engine never resets it — then re-dispatch)
       FAILURE_CLASS.LIVE_CHECKOUT_WRONG_BASE, // W-mr3lunnq000o9f41 — live-checkout refused to fork a new branch because the operator HEAD is on an unrelated branch (not the project base) and no local base ref was usable; forking off it would bake that branch's commits into the new PR (scope contamination). Deterministic — mechanical retry reproduces it (operator must `git checkout <mainRef>`, then re-dispatch)
       FAILURE_CLASS.OUTPUT_TRUNCATED, // P-8e4c2a17 — agent stdout exceeded the hard capture cap before the terminal result event; mechanical retry just reproduces the overflow (agent must reduce output volume or the task must be split)
     ]);

package/engine/kb-sweep.js

@@ -121,6 +121,11 @@ function _entryAgeMs(entry, now) {
  * (absent from the TTL map) are never touched. Pinned entries are already
  * excluded upstream (they never enter the manifest), and knowledge/agents/ is
  * never scanned into the manifest at all — so per-agent memory is inherently safe.
+ * Consolidation digests are also exempt — like the rewrite pass (`_isDigestEntry`
+ * guard below), a digest's `date` frontmatter is inherited from the old
+ * period-bucket of the boilerplate notes it rolled up, not its own write time, so
+ * age-based TTL would silently archive a freshly-written digest on the very next
+ * sweep if it were not excluded here.
  *
  * @returns {{ expired:number, survivors:object[] }}
  */
@@ -132,6 +137,7 @@ function _expireByAge(manifest, opts = {}) {
   let expired = 0;
   const survivors = [];
   for (const e of manifest) {
+    if (_isDigestEntry(e)) { survivors.push(e); continue; }
     const ttlDays = ttlByCategory[e.category];
     if (!ttlDays) { survivors.push(e); continue; }
     if (_entryAgeMs(e, now) <= ttlDays * DAY_MS) { survivors.push(e); continue; }
@@ -168,6 +174,252 @@ function _hashDedup(manifest, opts = {}) {
   return { survivors, archived };
 }
 
+// ── Structural consolidation (W-mr973knu) ───────────────────────────────────
+// The primary fix for the ballooning KB. Hash-dedup only catches near-exact
+// duplicates and the LLM batch pass only compares entries *within* a 30-entry
+// batch, so the dominant cost — hundreds of one-off boilerplate notes (agent
+// failure dumps, no-op / merge-conflict fix reports) that differ only by
+// WI/date/dispatch id — is never collapsed: each is unique by PR#/date and
+// spread across dozens of batches. This pass groups those boilerplate notes by
+// a *structural* signature (category + agent + kind + time bucket) rather than
+// by content, and rolls each large group into a single recoverable digest,
+// archiving the originals to knowledge/_swept/. It runs on RECENT entries too,
+// so it shrinks the KB continuously instead of merely aging files out.
+
+const CONSOLIDATION_DIGEST_PREFIX = '_digest-';
+const CONSOLIDATION_DIGEST_FLAG = '_digest'; // frontmatter marker on a digest (never re-consolidated / re-written)
+const DAY_MS = 24 * 60 * 60 * 1000;
+
+/**
+ * Resolve the effective structural-consolidation config, merging
+ * `opts.engineConfig.kbConsolidation` over `ENGINE_DEFAULTS.kbConsolidation`.
+ * `enabled` is false when no categories are configured or an explicit
+ * `enabled: false` override is present.
+ */
+function _resolveConsolidationConfig(opts = {}) {
+  const defaults = (shared.ENGINE_DEFAULTS && shared.ENGINE_DEFAULTS.kbConsolidation) || {};
+  const override = (opts.engineConfig && opts.engineConfig.kbConsolidation) || {};
+  const merged = { ...defaults, ...override };
+  const categories = Array.isArray(merged.categories)
+    ? merged.categories.filter(c => typeof c === 'string' && c)
+    : [];
+  const minGroupSize = Number(merged.minGroupSize);
+  const periodDays = Number(merged.periodDays);
+  return {
+    enabled: merged.enabled !== false && categories.length > 0,
+    categories: new Set(categories),
+    minGroupSize: Number.isFinite(minGroupSize) && minGroupSize >= 2 ? Math.floor(minGroupSize) : 5,
+    periodDays: Number.isFinite(periodDays) && periodDays > 0 ? periodDays : 7,
+  };
+}
+
+/** First `^key: value$` match anywhere in the entry content (handles the
+ *  double-frontmatter shape of agent-authored notes). '' when absent. */
+function _extractHeadField(content, key) {
+  const re = new RegExp('^' + key.replace(/[.*+?^${}()|[\]\\]/g, '\\$&') + ':\\s*(.+)$', 'm');
+  const m = String(content || '').match(re);
+  return m ? m[1].trim() : '';
+}
+
+/** True when an entry is itself a consolidation digest — such entries are never
+ *  re-grouped and never rewritten. */
+function _isDigestEntry(entry) {
+  if (!entry) return false;
+  if (typeof entry.file === 'string' && entry.file.startsWith(CONSOLIDATION_DIGEST_PREFIX)) return true;
+  if (entry._digest) return true;
+  const content = entry.content || '';
+  if (_extractHeadField(content, CONSOLIDATION_DIGEST_FLAG)) return true;
+  if (_extractHeadField(content, 'source') === 'kb-consolidation') return true;
+  return false;
+}
+
+/**
+ * Classify an entry into a consolidatable "kind", or null when it is not
+ * boilerplate we roll up (unique/durable notes are left alone). Kinds target
+ * the two dominant balloon sources: agent-failure dumps (keyed by failureClass)
+ * and no-op / merge-conflict fix reports.
+ * @returns {{ key:string, label:string }|null}
+ */
+function _consolidationKind(entry) {
+  const content = entry.content || '';
+  const failureClass = _extractHeadField(content, 'failureClass');
+  if (failureClass) return { key: `failure-${failureClass}`, label: `${failureClass} failures` };
+  const result = _extractHeadField(content, 'result');
+  const title = String(entry.title || '').toLowerCase();
+  if (/\berror\b/i.test(result) || /agent fail/.test(title)) {
+    return { key: 'failure-unknown', label: 'agent failures' };
+  }
+  if (/\bno-?op\b/.test(title)) return { key: 'noop', label: 'no-op dispatches' };
+  if (/merge.?conflict/.test(title)) return { key: 'merge-conflict', label: 'merge-conflict fixes' };
+  return null;
+}
+
+/** ISO date (YYYY-MM-DD) of the start of the `periodDays` bucket an entry falls
+ *  in, from its authored date (mtime fallback). 'undated' when neither known. */
+function _periodBucket(entry, periodDays) {
+  const parsed = typeof entry.date === 'string' && entry.date ? Date.parse(entry.date) : NaN;
+  const ms = Number.isFinite(parsed)
+    ? parsed
+    : (Number.isFinite(entry.mtimeMs) && entry.mtimeMs > 0 ? entry.mtimeMs : NaN);
+  if (!Number.isFinite(ms)) return 'undated';
+  const dayIdx = Math.floor(ms / DAY_MS);
+  const startMs = Math.floor(dayIdx / periodDays) * periodDays * DAY_MS;
+  return new Date(startMs).toISOString().slice(0, 10);
+}
+
+function _slugify(s) {
+  return String(s || '').toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '').slice(0, 48) || 'x';
+}
+
+function _digestFileName(agent, kindKey, period) {
+  return `${CONSOLIDATION_DIGEST_PREFIX}${_slugify(agent)}-${_slugify(kindKey)}-${period}.md`;
+}
+
+/** Extract the compact per-note fields that become one digest table row. */
+function _digestRow(entry) {
+  const content = entry.content || '';
+  const wi = _extractHeadField(content, 'sourceItem')
+    || (content.match(/\bW-[a-z0-9]{6,}/i) || [''])[0]
+    || '';
+  const dispatch = _extractHeadField(content, 'dispatchId');
+  const failureClass = _extractHeadField(content, 'failureClass');
+  let reason = _extractHeadField(content, 'Reason') || _extractHeadField(content, 'reason');
+  if (!reason) {
+    const rm = content.match(/(?:^|\n)\s*(?:\*\*)?Reason:(?:\*\*)?\s*(.+)/i);
+    if (rm) reason = rm[1];
+  }
+  if (!reason) {
+    // First prose line after the last frontmatter block / heading.
+    const body = content.replace(/^---\n[\s\S]*?\n---\n?/g, '').replace(/^#.*$/m, '');
+    const line = (body.split('\n').find(l => l.trim() && !l.trim().startsWith('#')) || '').trim();
+    reason = line;
+  }
+  reason = String(reason || '').replace(/\|/g, '\\|').replace(/\s+/g, ' ').trim().slice(0, 160);
+  return {
+    date: entry.date || '',
+    wi,
+    dispatch,
+    failureClass,
+    reason: reason || '—',
+    file: entry.file,
+  };
+}
+
+/** Parse the `source file` column out of an existing digest so re-runs merge
+ *  rather than clobber. Returns a Map<sourceFile, rowLine>. */
+function _readExistingDigestRows(digestPath) {
+  const rows = new Map();
+  const content = safeReadOrNull(digestPath);
+  if (!content) return rows;
+  for (const line of content.split('\n')) {
+    if (!line.startsWith('| ')) continue;
+    const cells = line.split('|').map(c => c.trim());
+    // columns: '' | date | work item | dispatch | failureClass | reason | source file | ''
+    const src = cells[cells.length - 2];
+    if (!src || src === 'source file' || /^-+$/.test(src)) continue;
+    rows.set(src, line);
+  }
+  return rows;
+}
+
+function _formatDigestRowLine(r) {
+  return `| ${r.date} | ${r.wi || '—'} | ${r.dispatch || '—'} | ${r.failureClass || '—'} | ${r.reason} | ${r.file} |`;
+}
+
+function _buildDigestContent(group, rowLines, count) {
+  const fm = [
+    `category: ${group.category}`,
+    `agent: ${group.agent}`,
+    `date: ${group.period}`,
+    `${CONSOLIDATION_DIGEST_FLAG}: ${new Date().toISOString()}`,
+    'source: kb-consolidation',
+    `_consolidatedCount: ${count}`,
+  ].join('\n');
+  const header = `# Consolidated: ${group.agent} — ${group.kind.label} (from ${group.period})`;
+  const intro = `Rolled up ${count} near-identical ${group.kind.label} note(s) into this single digest. `
+    + 'Originals were archived to `knowledge/_swept/` (recoverable for 30 days). '
+    + 'Each row is one collapsed note; recover a specific one from `_swept/` by its `source file`.';
+  const table = [
+    '| date | work item | dispatch | failureClass | reason | source file |',
+    '|------|-----------|----------|--------------|--------|-------------|',
+    ...rowLines,
+  ].join('\n');
+  return `---\n${fm}\n---\n\n${header}\n\n${intro}\n\n${table}\n`;
+}
+
+/**
+ * Structural consolidation pass. Groups boilerplate transient-category notes by
+ * (category, agent, kind, time-bucket) and collapses any group of at least
+ * `minGroupSize` into a single recoverable digest, archiving the originals.
+ * Digests, durable categories, pinned entries (already filtered upstream), and
+ * unclassifiable/unique notes are left untouched.
+ *
+ * @returns {{ survivors:object[], consolidated:number, groupsCollapsed:number, digestsWritten:number }}
+ */
+function _structuralConsolidate(manifest, opts = {}) {
+  const cfg = _resolveConsolidationConfig(opts);
+  if (!cfg.enabled) {
+    return { survivors: manifest.slice(), consolidated: 0, groupsCollapsed: 0, digestsWritten: 0 };
+  }
+  const groups = new Map(); // groupKey → { agent, category, kind, period, entries[] }
+  const survivors = [];
+  for (const e of manifest) {
+    if (!cfg.categories.has(e.category) || _isDigestEntry(e)) { survivors.push(e); continue; }
+    const kind = _consolidationKind(e);
+    if (!kind) { survivors.push(e); continue; }
+    const agent = e.agent || 'unknown';
+    const period = _periodBucket(e, cfg.periodDays);
+    const groupKey = `${e.category}::${agent}::${kind.key}::${period}`;
+    if (!groups.has(groupKey)) groups.set(groupKey, { agent, category: e.category, kind, period, entries: [] });
+    groups.get(groupKey).entries.push(e);
+  }
+
+  let consolidated = 0, groupsCollapsed = 0, digestsWritten = 0;
+  for (const g of groups.values()) {
+    if (g.entries.length < cfg.minGroupSize) { survivors.push(...g.entries); continue; }
+    g.entries.sort((a, b) => (b.date || '').localeCompare(a.date || '') || (b.mtimeMs - a.mtimeMs));
+
+    if (opts.dryRun) {
+      consolidated += g.entries.length;
+      groupsCollapsed++;
+      digestsWritten++;
+      // Nothing archived in dryRun — the originals remain on disk.
+      survivors.push(...g.entries);
+      continue;
+    }
+
+    const digestFile = _digestFileName(g.agent, g.kind.key, g.period);
+    const digestPath = path.join(KB_DIR, g.category, digestFile);
+    // Merge with any prior digest for this exact group so repeated sweeps
+    // accumulate rows instead of clobbering earlier ones.
+    const merged = _readExistingDigestRows(digestPath);
+    for (const e of g.entries) {
+      const r = _digestRow(e);
+      merged.set(r.file, _formatDigestRowLine(r));
+    }
+    const rowLines = [...merged.values()];
+    const digestContent = _buildDigestContent(g, rowLines, rowLines.length);
+    try {
+      const dir = path.dirname(digestPath);
+      if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
+      safeWrite(digestPath, digestContent);
+      digestsWritten++;
+    } catch (err) {
+      log('warn', `[kb-sweep] consolidate write ${g.category}/${digestFile}: ${err.message}`);
+      survivors.push(...g.entries); // write failed — keep originals visible
+      continue;
+    }
+    let collapsed = 0;
+    for (const e of g.entries) {
+      const fp = path.join(KB_DIR, e.category, e.file);
+      if (!fs.existsSync(fp)) continue;
+      if (_archiveKbFile(fp, `structurally consolidated into ${g.category}/${digestFile}`)) { consolidated++; collapsed++; }
+    }
+    if (collapsed > 0) groupsCollapsed++;
+  }
+  return { survivors, consolidated, groupsCollapsed, digestsWritten };
+}
+
 /** Batched LLM sweep — finds within-batch dupes, reclassifies, removes stale. */
 async function _llmBatchSweep(manifest, callLLM, trackEngineUsage, opts = {}) {
   const plan = { duplicates: [], reclassify: [], remove: [] };
@@ -252,6 +504,9 @@ ${body}`;
 
   const candidates = [];
   for (const e of survivors) {
+    // Never rewrite a consolidation digest — the rewrite template would destroy
+    // its roll-up table.
+    if (_isDigestEntry(e)) continue;
     const fp = path.join(KB_DIR, e.category, e.file);
     const content = safeRead(fp);
     if (content == null) continue;
@@ -540,6 +795,9 @@ async function _runKbSweepImpl(opts = {}) {
     llmDuplicatesArchived: 0,
     staleRemoved: 0,
     ageExpired: 0,
+    notesConsolidated: 0,
+    consolidationGroups: 0,
+    digestsWritten: 0,
     reclassified: 0,
     rewritten: 0,
     rewriteBytesBefore: 0,
@@ -579,27 +837,41 @@ async function _runKbSweepImpl(opts = {}) {
   const { survivors: afterHash, archived: hashArchived } = _hashDedup(manifest, opts);
   summary.hashDuplicatesArchived = hashArchived;
 
+  // 1.5. Structural consolidation (W-mr973knu) — PRIMARY balloon fix. Collapse
+  // large groups of near-identical boilerplate notes (agent-failure dumps, no-op
+  // / merge-conflict reports) into one recoverable digest per (agent, kind,
+  // week). Runs on recent entries too, so it shrinks the KB continuously rather
+  // than merely aging files out. Downstream passes operate on the survivors so
+  // the LLM/rewrite passes no longer waste calls on the collapsed notes.
+  const consolidateResult = _structuralConsolidate(afterHash, opts);
+  summary.notesConsolidated = consolidateResult.consolidated;
+  summary.consolidationGroups = consolidateResult.groupsCollapsed;
+  summary.digestsWritten = consolidateResult.digestsWritten;
+  const afterConsolidate = consolidateResult.survivors.filter(
+    e => e._digest || fs.existsSync(path.join(KB_DIR, e.category, e.file)),
+  );
+
   // 2. LLM batch sweep — within-batch dupes + reclassify + remove stale
   // Only runs against survivors, but we need indices that match the LIST sent to the LLM
-  const llmManifest = afterHash;
+  const llmManifest = afterConsolidate;
   const plan = await _llmBatchSweep(llmManifest, callLLM, trackEngineUsage, opts);
   const llmActions = _applyLlmPlan(plan, llmManifest, opts);
   summary.llmDuplicatesArchived = llmActions.merged;
   summary.staleRemoved = llmActions.removed;
   summary.reclassified = llmActions.reclassified;
 
-  // 2.5. Age-based TTL expiry (W-mr48yth5) — archive transient-category entries
-  // older than their per-category TTL to knowledge/_swept/. This is the pass that
-  // keeps PR/incident-scoped one-off notes (project-notes, build-reports, reviews)
-  // from accumulating indefinitely — dedup/rewrite can't reclaim them because each
-  // is unique by PR#/date. Durable categories (no TTL) are untouched.
-  const survivingAfterLlm = afterHash.filter(e => fs.existsSync(path.join(KB_DIR, e.category, e.file)));
+  // 2.5. Age-based TTL expiry (W-mr48yth5) — SECONDARY safety net. Archives
+  // transient-category entries older than their per-category TTL to
+  // knowledge/_swept/. Structural consolidation above is the primary reducer;
+  // this catches genuinely stale one-offs that never clustered into a digest.
+  // Durable categories (no TTL) are untouched.
+  const survivingAfterLlm = afterConsolidate.filter(e => fs.existsSync(path.join(KB_DIR, e.category, e.file)));
   const ageResult = _expireByAge(survivingAfterLlm, opts);
   summary.ageExpired = ageResult.expired;
 
   // 3. Per-entry rewrite (compress + normalize)
-  // Filter to entries that survived hash + LLM + age passes (still on disk)
-  const stillOnDisk = afterHash.filter(e => fs.existsSync(path.join(KB_DIR, e.category, e.file)));
+  // Filter to entries that survived hash + consolidation + LLM + age passes (still on disk)
+  const stillOnDisk = afterConsolidate.filter(e => fs.existsSync(path.join(KB_DIR, e.category, e.file)));
   const rewriteResult = await _rewritePass(stillOnDisk, callLLM, trackEngineUsage, opts);
   summary.rewritten = rewriteResult.processed;
   summary.rewriteBytesBefore = rewriteResult.bytesBefore;
@@ -620,7 +892,7 @@ async function _runKbSweepImpl(opts = {}) {
   }
 
   summary.durationMs = Date.now() - t0;
-  summary.summary = `${summary.hashDuplicatesArchived} hash-dup, ${summary.llmDuplicatesArchived} llm-dup, ${summary.staleRemoved} stale, ${summary.ageExpired} age-expired, ${summary.reclassified} reclassified, ${summary.rewritten} rewritten (${(summary.bytesBefore - summary.bytesAfter).toLocaleString()} bytes saved)`;
+  summary.summary = `${summary.hashDuplicatesArchived} hash-dup, ${summary.notesConsolidated} consolidated (${summary.digestsWritten} digests), ${summary.llmDuplicatesArchived} llm-dup, ${summary.staleRemoved} stale, ${summary.ageExpired} age-expired, ${summary.reclassified} reclassified, ${summary.rewritten} rewritten (${(summary.bytesBefore - summary.bytesAfter).toLocaleString()} bytes saved)`;
 
   if (!opts.dryRun) {
     try { shared.mutateKbSwept(() => ({ timestamp: ts(), summary: summary.summary, detail: summary })); } catch { /* ignore */ }
@@ -781,6 +1053,17 @@ module.exports = {
   _entryAgeMs,
   _resolveTtlByCategory,
   _archiveKbFile,
+  _expireByAge,
+  _entryAgeMs,
+  _resolveTtlByCategory,
+  _structuralConsolidate,
+  _resolveConsolidationConfig,
+  _consolidationKind,
+  _periodBucket,
+  _digestRow,
+  _isDigestEntry,
+  _extractHeadField,
+  CONSOLIDATION_DIGEST_PREFIX,
   COMPRESS_THRESHOLD_BYTES,
   SWEPT_FLAG_KEY,
 };

package/engine/live-checkout.js

@@ -39,25 +39,30 @@
  *           NO fast-forward, NO reset). The operator owns the checkout
  *           state per the live-checkout contract; the engine never
  *           overwrites local commits.
- *        b. rev-parse fails → branch is new → fork it. STALE-BASE GUARD
- *           (W-mr3lunnq000o9f41) runs first, UNLESS `allowNonMainBase` is set
- *           (PR-targeted fixes / shared-branch continuations opt out — they
- *           intend to keep building on a non-main branch): if HEAD's branch is
- *           NOT the project base (`mainRef`), forking off it would silently bake
- *           every commit already on that branch into the new branch and its PR
- *           (the ADO PR 5411214 scope-contamination incident — survives the
- *           dirty/mid-operation preflights because it is committed history, not
- *           an uncommitted diff). Recovery is LOCAL-ONLY (preserves issue #226's
- *           no-forced-fetch guarantee): if `refs/heads/<mainRef>` exists locally,
- *           PLAIN-checkout it (no fetch/reset/--force) and fork off it; else
- *           FAIL CLOSED with { ok:false, reason:'wrong-base' }. When HEAD is
- *           already on `mainRef` (or the guard is bypassed) →
- *           `git checkout -b <branchName>` from the CURRENT HEAD (NOT
- *           origin/<mainRef>). In live mode the operator's checked-out HEAD IS
- *           the baseline; branching off origin/<mainRef> forces on-demand blob
- *           fetching on blobless partial clones (Scalar/GVFS-managed ADO repos),
- *           which fails in headless mode because the GVFS cache server receives
- *           no auth and credential.helper is disabled. See issue #226.
+ *        b. rev-parse fails → branch is new → fork it. Two ordered guards run
+ *           before the fork:
+ *             i.  WRONG-BASE GUARD (W-mr3lunnq000o9f41) — UNLESS `allowNonMainBase`
+ *                 is set (PR-targeted fixes / shared-branch continuations opt out):
+ *                 if HEAD's branch is NOT the project base (`mainRef`), forking off
+ *                 it would silently bake every commit already on that branch into
+ *                 the new branch and its PR (the ADO PR 5411214 scope-contamination
+ *                 incident). Recovery is LOCAL-ONLY (issue #226's no-forced-fetch
+ *                 guarantee): if `refs/heads/<mainRef>` exists locally, PLAIN-checkout
+ *                 it (no fetch/reset/--force) and fork off it; else (optionally after
+ *                 opt-in auto-base-repair materializes a local `<mainRef>` from the
+ *                 existing `refs/remotes/origin/<mainRef>` ref, W-mr3lunnq000o9f41)
+ *                 FAIL CLOSED with { ok:false, reason:'wrong-base' }.
+ *             ii. STALE-BASE GUARD (W-mr98op8w000ma4ad) — runs once HEAD is confirmed
+ *                 on `mainRef` (either it started there, or guard i left it there):
+ *                 if the local `mainRef` tip has diverged from `origin/<mainRef>`
+ *                 with unpushed commits, bail with { ok:false, reason:'stale-main', ... }
+ *                 rather than fork a contaminated base (see RETURN SHAPES).
+ *           When both guards pass, `git checkout -b <branchName>` is created from
+ *           the CURRENT HEAD (NOT origin/<mainRef>). In live mode the operator's
+ *           checked-out HEAD IS the baseline; branching off origin/<mainRef> forces
+ *           on-demand blob fetching on blobless partial clones (Scalar/GVFS-managed
+ *           ADO repos), which fails in headless mode because the GVFS cache server
+ *           receives no auth and credential.helper is disabled. See issue #226.
  *   5. Returns { ok:true, branch, created:boolean, originalRef, originalRefType }.
  *
  * RETURN SHAPES:
@@ -80,6 +85,19 @@
  *     (W-mr28h2j2000y0de1) — the target branch is already checked out in another
  *     worktree; `git checkout <branch>` refuses deterministically. Non-retryable
  *     at the caller — a human/engine must remove or reassign the other worktree.
+ *   { ok:false, reason:'stale-main', mainRef, ahead, localMainSha, originMainSha, branch, originalRef, originalRefType }
+ *     (W-mr98op8w000ma4ad — STALE-BASE GUARD) — a NEW branch was about to be
+ *     forked off the current HEAD while HEAD sits on the project base ref
+ *     (mainRef), but the LOCAL mainRef tip has diverged from origin/<mainRef>
+ *     with `ahead` unpushed commit(s). Forking would silently inherit that
+ *     committed contamination into the new branch and its PR. Detected without a
+ *     fetch (issue #226) by comparing local `refs/heads/<mainRef>` against the
+ *     EXISTING `refs/remotes/origin/<mainRef>` ref via
+ *     `git rev-list --count origin/<mainRef>..<mainRef>`. The guard is SKIPPED
+ *     (proceeds normally) when HEAD is not on mainRef, when the origin/<mainRef>
+ *     remote-tracking ref is absent (local-only/no-remote repo), or when the
+ *     rev-list count cannot be computed (transient). Non-retryable at the caller
+ *     — a human must reconcile the local base branch; the engine never resets it.
  *
  * NOTE: `mainRef` is still accepted (and validated) for caller-contract
  * stability, but it is NOT used to seed the new branch in live mode — HEAD
@@ -565,13 +583,32 @@ async function prepareLiveCheckout(opts = {}) {
           return { ok: false, reason: 'dirty', dirtyFiles, branchInfo };
         }
 
-        if (typeof log === 'function') {
-          log(`live-checkout auto-reset: discarding ${dirtyFiles.length} dirty path(s) on '${branchName}' via fetch + reset --hard origin/${branchName}`);
-        }
+        // W-mrav3u0c0008ce38 — live-checkout WI types that never push a branch
+        // (setup/test/verify live-validation dispatches on checkoutMode:'live'
+        // or hybrid liveValidation projects) leave `origin/<branchName>`
+        // unresolvable, so a bare `reset --hard origin/<branchName>` fails every
+        // time with "ambiguous argument … unknown revision" and the tree stays
+        // dirty forever. Probe `origin/<branchName>` first (after the fetch, so
+        // it reflects the latest remote state); only fall back to
+        // `origin/<mainRef>` when that branch genuinely doesn't exist upstream.
+        // PR-continuation flows (fix/implement WIs resuming an existing pushed
+        // branch) keep resetting to `origin/<branchName>` exactly as before.
         let resetOk = true;
+        let resetTarget = `origin/${branchName}`;
         try {
           await git(['fetch', 'origin'], baseOpts);
-          await git(['reset', '--hard', `origin/${branchName}`], baseOpts);
+          try {
+            await git(['rev-parse', '--verify', resetTarget], baseOpts);
+          } catch {
+            resetTarget = `origin/${mainRef}`;
+            if (typeof log === 'function') {
+              log(`live-checkout auto-reset: origin/${branchName} does not exist (never pushed) — falling back to '${resetTarget}'`);
+            }
+          }
+          if (typeof log === 'function') {
+            log(`live-checkout auto-reset: discarding ${dirtyFiles.length} dirty path(s) on '${branchName}' via fetch + reset --hard ${resetTarget}`);
+          }
+          await git(['reset', '--hard', resetTarget], baseOpts);
         } catch (e) {
           resetOk = false;
           if (typeof log === 'function') {
@@ -613,7 +650,7 @@ async function prepareLiveCheckout(opts = {}) {
             '',
             `⚠️ The live-checkout tree at \`${localPath}\` was dirty at dispatch time and`,
             '`liveCheckoutAutoReset` is enabled, so it was force-reset to',
-            `\`origin/${branchName}\`. **The following uncommitted changes were DISCARDED**`,
+            `\`${resetTarget}\`. **The following uncommitted changes were DISCARDED**`,
             '(recover from `git reflog` / `git fsck --lost-found` if needed):',
             '',
             '```',
@@ -949,6 +986,102 @@ async function prepareLiveCheckout(opts = {}) {
     }
   }
 
+
+  // ── Step 4d: STALE-BASE GUARD (W-mr98op8w000ma4ad). ───────────────────
+  // We are about to fork a NEW branch off the CURRENT HEAD. In the common
+  // live-mode case HEAD sits on the project base ref (mainRef). Step 1 (dirty
+  // check) and Step 2 (mid-operation/detached preflight) both passed, but a
+  // CLEAN tree can still hide COMMITTED contamination: a prior/parallel
+  // dispatch (or a human) may have left extra commits on the local mainRef
+  // branch that were never pushed to origin/<mainRef>. `git checkout -b` would
+  // then silently inherit those commits into the new branch (and its PR) — the
+  // exact scope-contamination class this guard prevents (original incident ADO
+  // PR 5411214; recurrence on AB#12016662 / ADO PR 5419146, ~20 unrelated OCM
+  // files baked into a 2-file a11y fix). This survives the dirty check (the
+  // contamination is COMMITTED, not uncommitted) and — unlike a HEAD parked on
+  // some OTHER branch — cannot be spotted by a headBranch !== mainRef check,
+  // because here headBranch IS mainRef.
+  //
+  // Detect it by comparing the local mainRef tip against the EXISTING
+  // origin/<mainRef> remote-tracking ref (NO fetch — issue #226's
+  // no-forced-fetch guarantee): any commit reachable from local mainRef but not
+  // from origin/<mainRef> (`git rev-list --count origin/<mainRef>..<mainRef>` >
+  // 0) means the base is contaminated with unpushed commits. Local mainRef
+  // being merely BEHIND origin (fewer commits) is fine — that just yields a
+  // branch based on an older tip, not contamination — so we count only the
+  // local-ahead side, not strict equality.
+  //
+  // Scope: only when HEAD is actually on mainRef (that IS the base we fork
+  // off). If HEAD is on some other branch the operator/engine deliberately
+  // parked it there (e.g. the orphan-branch self-heal above) — out of scope.
+  //
+  // AMBIGUITY / local-only repos: if the origin/<mainRef> remote-tracking ref
+  // does not exist locally we CANNOT compare without fetching, which #226
+  // forbids. Rather than fail closed on legitimate local-only / no-remote repos
+  // (which have no origin ref by design and for which forking off HEAD is the
+  // only and expected behavior), we SKIP the check and log. Failing closed
+  // there would regress those setups; the contamination class this targets only
+  // exists when an origin baseline is present to diverge from. A transient
+  // rev-list failure (origin ref present but the count could not be computed)
+  // likewise proceeds without the check rather than converting a transient git
+  // hiccup into a permanent non-retryable refusal.
+  if (curBranch && curBranch === mainRef) {
+    let originMainSha = '';
+    try {
+      const originRaw = await git(['rev-parse', '--verify', '--quiet', `refs/remotes/origin/${mainRef}`], baseOpts);
+      originMainSha = (typeof originRaw === 'string' ? originRaw : '').trim();
+    } catch {
+      originMainSha = ''; // remote-tracking ref absent → ambiguous, skip below
+    }
+    if (originMainSha) {
+      let aheadCount = -1;
+      try {
+        const cntRaw = await git(['rev-list', '--count', `refs/remotes/origin/${mainRef}..${mainRef}`], baseOpts);
+        aheadCount = parseInt((typeof cntRaw === 'string' ? cntRaw : '').trim(), 10);
+        if (Number.isNaN(aheadCount)) aheadCount = -1;
+      } catch {
+        aheadCount = -1; // rev-list failed → transient/ambiguous; proceed without the check
+      }
+      if (aheadCount > 0) {
+        let localMainSha = '';
+        try {
+          const localRaw = await git(['rev-parse', '--verify', '--quiet', `refs/heads/${mainRef}`], baseOpts);
+          localMainSha = (typeof localRaw === 'string' ? localRaw : '').trim();
+        } catch { /* best-effort — informational only */ }
+        logFn(
+          `[live-checkout] STALE-BASE GUARD: refusing to fork '${branchName}' off local '${mainRef}' — ` +
+          `local '${mainRef}' is ${aheadCount} commit(s) ahead of 'origin/${mainRef}' (unpushed/contaminated base). ` +
+          `A human must reconcile the local base branch before dispatch; the engine never resets it for you.`,
+          'warn'
+        );
+        return {
+          ok: false,
+          reason: 'stale-main',
+          mainRef,
+          ahead: aheadCount,
+          localMainSha,
+          originMainSha,
+          branch: branchName,
+          originalRef,
+          originalRefType,
+        };
+      }
+      if (aheadCount < 0) {
+        logFn(
+          `[live-checkout] STALE-BASE GUARD: could not compute divergence of local '${mainRef}' vs 'origin/${mainRef}' ` +
+          `(rev-list failed); proceeding without the base-divergence check.`,
+          'debug'
+        );
+      }
+    } else {
+      logFn(
+        `[live-checkout] STALE-BASE GUARD: no local 'origin/${mainRef}' remote-tracking ref — ` +
+        `skipping base-divergence check (local-only/no-remote repo; #226 no-fetch).`,
+        'debug'
+      );
+    }
+  }
+
   // Create from HEAD — now guaranteed to be the project base branch unless
   // allowNonMainBase bypassed the guard. NOT origin/<mainRef>: in live mode the
   // operator's HEAD is the baseline, and seeding from a remote ref forces

package/engine/shared.js

@@ -3193,6 +3193,24 @@ const ENGINE_DEFAULTS = {
     'build-reports': 14,
     'reviews': 30,
   },
+  // W-mr973knu — structural consolidation for the KB sweep (PRIMARY balloon
+  // fix; TTL above is the secondary safety net). The sweep groups boilerplate
+  // transient-category notes by (category, agent, kind, time-bucket) — where
+  // kind is the agent-failure `failureClass`, or a no-op / merge-conflict fix
+  // report — and rolls any group of at least `minGroupSize` notes into a single
+  // recoverable digest (`_digest-<agent>-<kind>-<period>.md`), archiving the
+  // originals to knowledge/_swept/. Unlike TTL expiry this collapses RECENT
+  // duplication too, so the KB shrinks continuously instead of only aging out.
+  // Only `categories` listed here are consolidated; durable categories
+  // (architecture, conventions) and per-agent memory are never touched.
+  // config.engine.kbConsolidation is merged over these defaults; set
+  // `enabled: false` or `categories: []` to disable.
+  kbConsolidation: {
+    enabled: true,
+    categories: ['project-notes', 'build-reports', 'reviews'],
+    minGroupSize: 5, // collapse a group only once it reaches this many near-duplicate notes
+    periodDays: 7,   // one digest per (agent, kind) per this many days
+  },
   // W-mqtvnnj1000357fa — fleet-wide fallback for live-checkout auto-stash. When
   // true, a dirty live-checkout tree is `git stash push --include-untracked`'d
   // before dispatch instead of failing with FAILURE_CLASS.LIVE_CHECKOUT_DIRTY,
@@ -4698,12 +4716,19 @@ function mutateWatches(mutator) {
 function mutateMetrics(mutator) {
   const metricsPath = path.join(MINIONS_DIR, 'engine', 'metrics.json');
   const store = require('./metrics-store');
+  // W-mradg74d000rfd45 — the JSON mirror is now written INSIDE
+  // applyMetricsMutation's SQL transaction (before commit), not here
+  // after the fact. Mirroring post-commit left a cross-process window
+  // where a sibling process (dashboard vs. engine — separate Node
+  // processes, each with its own in-memory mirror-hash cache) could
+  // observe the newly committed SQL rows before the JSON file caught up
+  // and read stale/missing metrics off the sidecar. See
+  // metrics-store.js#applyMetricsMutation for the full rationale.
   const { wrote, result } = store.applyMetricsMutation((m) => {
     if (!m || typeof m !== 'object') m = {};
     return mutator(m) || m;
-  });
+  }, { mirrorPath: metricsPath });
   if (wrote) {
-    try { store._mirrorJsonFromSql(metricsPath); } catch { /* mirror best-effort */ }
     try { require('./db-events').emitStateEvent('metrics'); } catch { /* optional */ }
   }
   return result;
@@ -4877,6 +4902,7 @@ const FAILURE_CLASS = {
   LIVE_CHECKOUT_MID_OPERATION: 'live-checkout-mid-operation', // P-a7f3c1d9 (live-checkout dispatch mode): spawnAgent could not switch/create the target branch in project.localPath because the operator tree is mid-operation — an in-progress merge/rebase/cherry-pick/bisect or a detached HEAD. Distinct from LIVE_CHECKOUT_DIRTY (uncommitted changes): here the tree may be clean but the branch op cannot proceed. Engine refuses to spawn (it never runs `git reset`/`git clean`/`git rebase --abort` against the operator tree). Non-retryable — operator must finish or abort the in-progress operation, or checkout a branch, before re-dispatch.
   LIVE_CHECKOUT_BLOB_FETCH: 'live-checkout-blob-fetch', // PL-live-checkout-reliability-hardening (live-checkout dispatch mode): `git checkout <existing-branch>` in project.localPath failed because the tree could not be materialized — on a Scalar/GVFS-managed ADO partial (blobless) clone, switching onto a branch whose tree differs from HEAD hydrates the changed paths' blobs through the GVFS cache server (`*.gvfscache.dev.azure.com`), a different endpoint than the main git remote that receives NO auth in the headless engine shell, so the fetch fails DETERMINISTICALLY. Distinct from LIVE_CHECKOUT_FAILED (transient) because retrying reproduces it identically — surfaced once as an operator-actionable refusal instead of retry-storming to the cap. Non-retryable — the operator hydrates the branch once with their own credentials (`git checkout <branch>` interactively, or `scalar prefetch` / `git -C <repo> fetch`), then re-dispatches. The engine NEVER forces, resets, cleans, or stashes the operator tree, and best-effort switches HEAD back to the original ref so the tree is not stranded half-populated.
   LIVE_CHECKOUT_WORKTREE_CONFLICT: 'live-checkout-worktree-conflict', // W-mr28h2j2000y0de1 (live-checkout dispatch mode): `git checkout <existing-branch>` in project.localPath failed because that exact branch is ALSO checked out in a SECOND worktree elsewhere (a leftover from a prior isolated-worktree dispatch, a manually-created worktree, or a stale worktree left by a checkoutMode change). git refuses deterministically with `fatal: '<branch>' is already used by worktree at '<path>'`. Distinct from LIVE_CHECKOUT_FAILED (transient) because this is a STRUCTURAL conflict — it does NOT clear on retry, ever, until a human or the engine removes/reassigns the other worktree; retrying just reproduces it identically and burns maxRetries. Non-retryable — the operator either `git worktree remove <path>` (freeing the branch) if that worktree is stale, or finishes/commits/pushes from it directly if it holds real WIP. The engine NEVER forces, resets, cleans, or stashes the operator tree, and best-effort switches HEAD back to the original ref so the tree is not stranded.
+  LIVE_CHECKOUT_STALE_BASE: 'live-checkout-stale-base', // W-mr98op8w000ma4ad (live-checkout dispatch mode, STALE-BASE GUARD): spawnAgent was about to fork a NEW branch off the operator's current HEAD while HEAD sits on the project base ref (mainRef), but the LOCAL mainRef tip has DIVERGED from origin/<mainRef> with unpushed commit(s) (`git rev-list --count origin/<mainRef>..<mainRef>` > 0). Forking would silently inherit that COMMITTED contamination into the new branch and its PR — the exact scope-contamination class first seen on ADO PR 5411214 and recurring on AB#12016662 / ADO PR 5419146. Survives the dirty check (contamination is committed, not uncommitted) and cannot be caught by a headBranch !== mainRef check (headBranch IS mainRef here). Detected WITHOUT a fetch (issue #226) via the existing origin/<mainRef> remote-tracking ref. Distinct from LIVE_CHECKOUT_FAILED (transient) because the contaminated local base does NOT change on retry — it reproduces identically until a human reconciles the local base branch. Non-retryable — the engine NEVER resets/cleans the operator's local mainRef; the operator must reconcile it (push/reset/rebase their own way), then re-dispatch. The guard SKIPS (proceeds normally) when HEAD is not on mainRef, when no local origin/<mainRef> ref exists (local-only/no-remote repo), or when the divergence count cannot be computed.
   LIVE_CHECKOUT_WRONG_BASE: 'live-checkout-wrong-base', // W-mr3lunnq000o9f41 (live-checkout dispatch mode): a NEW-branch fork was requested but the operator's checkout HEAD is on an unrelated topic/feature branch, NOT the project base (mainRef), and prepareLiveCheckout could not switch to a LOCAL base ref (no `refs/heads/<mainRef>`, or the local checkout itself failed). Forking off the stale HEAD would silently bake every commit already on that branch into the new branch AND its PR — committed-history scope contamination that survives the dirty/mid-operation preflights (the ADO PR 5411214 incident: ~22 unrelated OCM files, author-disavowed). The engine never fetches origin/<mainRef> in live mode (issue #226) so it cannot self-heal a missing local base. Non-retryable — the operator must `git checkout <mainRef>` in the operator checkout before re-dispatch. Does NOT fire for PR-targeted fixes or shared-branch continuations (those pass allowNonMainBase, intentionally continuing a non-main branch), nor when HEAD is already on mainRef, nor when a local mainRef ref exists (the guard switches to it and forks cleanly). OPT-IN AUTO-RECOVERY (`liveCheckoutAutoBaseRepair`, per-project > fleet-wide, default OFF): when enabled AND a `refs/remotes/origin/<mainRef>` remote-tracking ref exists, the guard materializes a local `<mainRef>` branch from it (a LOCAL ref op — still no `git fetch`, issue #226 preserved; origin/<mainRef> IS the base so no contamination) and forks cleanly instead of failing — eliminating the manual `git checkout <mainRef>` step. Still fails closed when neither a local base nor an origin-tracking base ref exists, or when the base checkout itself fails/hangs.
   INVALID_WORKDIR: 'invalid-workdir',     // P-714ef144: dispatch carried a meta.workdir override that failed validation — non-string, absolute path, drive-letter prefix, null byte, ".." segment, or post-resolve containment escape against project.localPath / worktree root. Engine refuses to spawn (the subpath would either be unreachable on disk or point outside the operator's allowed surface). Non-retryable — operator must fix the WI's meta.workdir before re-dispatch. Inbox alert lists the offending value + the resolved-vs-base mismatch.
   MODEL_UNAVAILABLE: 'model-unavailable', // W-mpg6isvy000xca4d: requested model returned overloaded_error / 503 / service_unavailable. Retriable — engine swaps in the runtime-appropriate fallback model on next spawn (Claude leans on --fallback-model already plumbed; Copilot overrides --model with engine.copilotFallbackModel).

package/engine.js

@@ -2934,6 +2934,83 @@ async function spawnAgent(dispatchItem, config) {
       cleanupTempAgent(agentId);
       return null;
     }
+    // W-mr98op8w000ma4ad: STALE-BASE GUARD refusal. prepareLiveCheckout was about
+    // to fork a NEW branch off the operator's current HEAD while HEAD sits on the
+    // project base ref (mainRef), but the LOCAL mainRef tip has diverged from
+    // origin/<mainRef> with unpushed commit(s). Forking would silently bake that
+    // committed contamination into the new branch and its PR (the scope-leak class
+    // first seen on ADO PR 5411214, recurring on AB#12016662 / ADO PR 5419146).
+    // Deterministic — a contaminated local base reproduces identically on retry —
+    // so it gets its own non-retryable FAILURE_CLASS instead of LIVE_CHECKOUT_FAILED's
+    // bounded retry-storm. The engine NEVER resets/cleans the operator's local
+    // mainRef; the operator must reconcile it themselves, then re-dispatch.
+    if (_liveResult && _liveResult.ok === false && _liveResult.reason === 'stale-main') {
+      const _staleMainRef = typeof _liveResult.mainRef === 'string' && _liveResult.mainRef ? _liveResult.mainRef : 'main';
+      const _staleAhead = Number.isFinite(_liveResult.ahead) ? _liveResult.ahead : 0;
+      const _localSha = typeof _liveResult.localMainSha === 'string' && _liveResult.localMainSha ? _liveResult.localMainSha : '(unknown)';
+      const _originSha = typeof _liveResult.originMainSha === 'string' && _liveResult.originMainSha ? _liveResult.originMainSha : '(unknown)';
+      const _alertBody = [
+        '# Live-checkout blocked: local base branch has diverged (stale/contaminated base)',
+        '',
+        `**Project:** ${project.name || '(unknown)'}`,
+        `**Local path:** ${cwd}`,
+        `**New branch (refused):** ${branchName}`,
+        `**Base ref:** ${_staleMainRef}`,
+        `**Local ${_staleMainRef}:** ${_localSha}`,
+        `**origin/${_staleMainRef}:** ${_originSha}`,
+        `**Unpushed commits on local ${_staleMainRef}:** ${_staleAhead}`,
+        `**Work item:** ${_wiIdForAlert}`,
+        `**Dispatch:** ${id}`,
+        '',
+        `The engine refused to fork \`${branchName}\` off local \`${_staleMainRef}\` because your local \`${_staleMainRef}\` is **${_staleAhead} commit(s) ahead of \`origin/${_staleMainRef}\`**. Those commits were never pushed — forking a new branch (and its PR) off this base would silently inherit them, contaminating an otherwise-clean change with unrelated commits. The working tree was clean (no uncommitted changes), so the dirty check could not catch this: the contamination is COMMITTED. Your tree was left untouched — the engine never resets, cleans, or rebases your \`${_staleMainRef}\`.`,
+        '',
+        '## Recovery',
+        '',
+        `Reconcile your local \`${_staleMainRef}\` so it no longer carries unpushed commits, then re-dispatch. Pick ONE, depending on whether those commits are real work:`,
+        '',
+        `1. **If the extra commits are real work you want to keep** — move them onto their own branch, then reset \`${_staleMainRef}\` to the remote:`,
+        '',
+        '```',
+        `git -C "${cwd}" branch salvage-${_staleMainRef} ${_staleMainRef}`,
+        `git -C "${cwd}" checkout ${_staleMainRef}`,
+        `git -C "${cwd}" reset --hard origin/${_staleMainRef}`,
+        '```',
+        '',
+        `2. **If the extra commits are leftover junk** (e.g. a prior dispatch's abandoned WIP) — discard them by resetting \`${_staleMainRef}\` to the remote (this DISCARDS those commits):`,
+        '',
+        '```',
+        `git -C "${cwd}" checkout ${_staleMainRef}`,
+        `git -C "${cwd}" reset --hard origin/${_staleMainRef}`,
+        '```',
+        '',
+        `The salvage branch in option 1 keeps the commits recoverable; both leave \`${_staleMainRef}\` matching \`origin/${_staleMainRef}\` so the next dispatch forks off a clean base.`,
+      ].join('\n');
+      try { writeInboxAlert(`live-checkout-stale-base-${_wiIdForAlert}`, _alertBody); }
+      catch (e) { log('warn', `live-checkout: writeInboxAlert failed: ${e.message}`); }
+      try {
+        const _wiPath = resolveWorkItemPath(dispatchItem.meta);
+        if (_wiPath && dispatchItem.meta?.item?.id) {
+          mutateJsonFileLocked(_wiPath, (data) => {
+            if (!Array.isArray(data)) return data;
+            const wi = data.find(i => i && i.id === dispatchItem.meta.item.id);
+            if (wi) wi._pendingReason = 'live_checkout_stale_base';
+            return data;
+          });
+        }
+      } catch (e) { log('warn', `live-checkout: failed to stamp _pendingReason: ${e.message}`); }
+      const _shortMsg = `live-checkout blocked: local ${_staleMainRef} is ${_staleAhead} commit(s) ahead of origin/${_staleMainRef} (would contaminate ${branchName})`;
+      log('error', `spawnAgent: ${_shortMsg}`);
+      _cleanupPromptFiles();
+      completeDispatch(
+        id,
+        DISPATCH_RESULT.ERROR,
+        _shortMsg.slice(0, 800),
+        `Live-checkout STALE-BASE GUARD: forking ${branchName} off local ${_staleMainRef} would inherit ${_staleAhead} unpushed commit(s) not on origin/${_staleMainRef}. Deterministic — operator must reconcile the local base branch (the engine never resets it) before re-dispatch. Retrying is provably useless.`,
+        { failureClass: FAILURE_CLASS.LIVE_CHECKOUT_STALE_BASE, agentRetryable: false },
+      );
+      cleanupTempAgent(agentId);
+      return null;
+    }
     log('info', `live-checkout: ${_liveResult.created ? 'created' : 'switched to'} branch ${branchName} in ${cwd} (in-place; no worktree)`);
     // PL-live-checkout-reliability-hardening: a clean spawn clears the two-strike
     // dirty counter so a project that was transiently dirty once isn't treated as

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.2345",
+  "version": "0.1.2346",
   "description": "Multi-agent AI dev team that runs from ~/.minions/ — five autonomous agents share a single engine, dashboard, and knowledge base",
   "bin": {
     "minions": "bin/minions.js"