@yemi33/minions 0.1.2345 → 0.1.2347

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