@yemi33/minions 0.1.2372 → 0.1.2374

package/engine/cleanup.js

@@ -1387,25 +1387,37 @@ async function runCleanup(config, verbose = false) {
     log('info', `Cleanup: cleared ${cleaned.doneRetryCounts} stale retry count(s) from done work items`);
   }
   // PRD items (missing_features[].status)
+  // Read+mutate+write happens inside prdStore.mutatePrd's single transaction
+  // (not readPrd -> mutate-in-JS -> writePrd) so a concurrent writer (another
+  // engine tick, a dashboard API request, or a second process) can't have its
+  // changes clobbered by this pass's stale in-memory copy (lost-update race —
+  // writePrd's _upsertPrd does a full-column data=? replace, not a merge).
   try {
     const prdStore = require('./prd-store');
     const prdFiles = prdStore.listPrdRows().filter(row => !row.archived).map(row => row.filename);
     for (const pf of prdFiles) {
       const prdPath = path.join(PRD_DIR, pf);
-      const prd = prdStore.readPrd(prdPath);
+      // Cheap out-of-transaction peek to skip PRDs that clearly need no work;
+      // the authoritative decision (and the write) happens inside mutatePrd.
+      const peek = prdStore.readPrd(prdPath);
+      const needsMigration = peek?.missing_features?.some(feat =>
+        LEGACY_DONE_ALIASES.has(feat.status) || feat.status === LEGACY_NEEDS_REVIEW_STATUS);
+      if (!needsMigration) continue;
       let migrated = 0;
-      if (prd?.missing_features) {
-        for (const feat of prd.missing_features) {
-          if (LEGACY_DONE_ALIASES.has(feat.status)) {
-            feat.status = shared.WI_STATUS.DONE;
-            migrated++;
-          } else if (feat.status === LEGACY_NEEDS_REVIEW_STATUS) {
-            feat.status = shared.WI_STATUS.FAILED;
-            migrated++;
+      prdStore.mutatePrd(prdPath, (prd) => {
+        if (prd?.missing_features) {
+          for (const feat of prd.missing_features) {
+            if (LEGACY_DONE_ALIASES.has(feat.status)) {
+              feat.status = shared.WI_STATUS.DONE;
+              migrated++;
+            } else if (feat.status === LEGACY_NEEDS_REVIEW_STATUS) {
+              feat.status = shared.WI_STATUS.FAILED;
+              migrated++;
+            }
           }
         }
-      }
-      if (migrated > 0) prdStore.writePrd(prdPath, prd);
+        return prd;
+      });
       if (migrated > 0) {
         log('info', `Migrated ${migrated} legacy PRD item status(es) in ${pf}`);
       }
@@ -1413,6 +1425,8 @@ async function runCleanup(config, verbose = false) {
   } catch (e) { log('warn', 'migrate PRD legacy statuses: ' + e.message); }
 
   // Reset orphaned PRD item statuses — dispatched/failed with no matching work item (#779)
+  // Same lost-update concern as above: use prdStore.mutatePrd so the read,
+  // in-JS mutation, and write are one atomic transaction.
   cleaned.orphanedPrdStatuses = 0;
   try {
     const wiIds = new Set(
@@ -1426,16 +1440,17 @@ async function runCleanup(config, verbose = false) {
       const peek = prdStore.readPrd(prdPath);
       if (!peek?.missing_features) continue;
       let reset = 0;
-      const prd = peek;
-      if (prd?.missing_features) {
-        for (const feat of prd.missing_features) {
-          if ((feat.status === shared.WI_STATUS.DISPATCHED || feat.status === shared.WI_STATUS.FAILED) && !wiIds.has(feat.id)) {
-            feat.status = shared.WI_STATUS.PENDING;
-            reset++;
+      prdStore.mutatePrd(prdPath, (prd) => {
+        if (prd?.missing_features) {
+          for (const feat of prd.missing_features) {
+            if ((feat.status === shared.WI_STATUS.DISPATCHED || feat.status === shared.WI_STATUS.FAILED) && !wiIds.has(feat.id)) {
+              feat.status = shared.WI_STATUS.PENDING;
+              reset++;
+            }
           }
         }
-      }
-      if (reset > 0) prdStore.writePrd(prdPath, prd);
+        return prd;
+      });
       if (reset > 0) {
         log('info', `Reset ${reset} orphaned PRD item status(es) → pending in ${pf}`);
         cleaned.orphanedPrdStatuses += reset;

package/engine/cli.js

@@ -614,6 +614,25 @@ const commands = {
       let reattached = 0;
       for (const item of activeOnStart) {
         const agentId = item.agent;
+
+        // P-3f5b7d26 — a pooled dispatch (engine.js#spawnAgent, item.pooled
+        // persisted at dispatch-time) can NEVER be reattached, regardless of
+        // what the PID file says. The ACP worker child
+        // (engine/acp-transport.js#spawnAcp) is not spawned with
+        // `detached: true` like the cold-spawn path, and even on the rare
+        // chance its OS process survived the restart, the freshly-started
+        // engine's engine/agent-worker-pool.js always cold-starts with an
+        // empty worker set — there is no in-process handle whose stdio could
+        // be reconnected to that PID. Treating a live-but-orphaned worker PID
+        // as "still running" here would silently hang the dispatch forever
+        // instead of routing it to the standard "agent died mid-run, mark for
+        // retry" path (timeout.js's confirmedDeadAtRestart handling below).
+        if (item.pooled) {
+          e.engineRestartGraceExempt.add(item.id);
+          e.log('info', `Restart: ${agentId} (${item.id}) was a pooled dispatch — not reattachable, marking for retry`);
+          continue;
+        }
+
         let agentPid = readDispatchPid(item.id);
 
         if (!agentPid) {

package/engine/db/migrations/019-inbox-entries.js

@@ -0,0 +1,37 @@
+// engine/db/migrations/019-inbox-entries.js
+//
+// Creates the `inbox_entries` table: persistent store for operator and agent
+// inbox messages, decoupled from the runtime work-item/dispatch lifecycle.
+//
+// Schema: columns, types, constraints, and indexing strategy documented in
+// docs/design-inbox-entries-schema.md
+
+module.exports = {
+  version: 19,
+  description: 'inbox_entries: operator/agent message queue with full schema + indexes',
+  up(db) {
+    db.exec(`
+      CREATE TABLE inbox_entries (
+        id                  TEXT PRIMARY KEY,
+        recipient_session_id TEXT NOT NULL,
+        sender_id           TEXT NOT NULL,
+        sender_name         TEXT NOT NULL,
+        sender_type         TEXT NOT NULL,
+        interaction_id      TEXT NOT NULL,
+        sequence            INTEGER NOT NULL DEFAULT 0,
+        summary             TEXT NOT NULL,
+        content             TEXT NOT NULL,
+        unread              INTEGER NOT NULL DEFAULT 1,
+        sent_at             INTEGER NOT NULL,
+        read_at             INTEGER,
+        notified_at         INTEGER
+      );
+
+      CREATE INDEX idx_inbox_recipient_sent 
+        ON inbox_entries(recipient_session_id, sent_at DESC);
+
+      CREATE INDEX idx_inbox_interaction 
+        ON inbox_entries(interaction_id);
+    `);
+  },
+};

package/engine/inbox-store.js

@@ -0,0 +1,276 @@
+// engine/inbox-store.js — SQL-backed inbox_entries table handlers.
+//
+// Provides read/write helpers for the operator and agent inbox message queue.
+// Inboxes are decoupled from the runtime work-item/dispatch lifecycle and
+// support threading via interaction_id, unread tracking, and time-ordered display.
+//
+// Schema: docs/design-inbox-entries-schema.md
+
+const crypto = require('node:crypto');
+const { getDb, withTransaction } = require('./db');
+
+// In-process monotonic counter. Millisecond timestamps are too coarse to
+// disambiguate bursts of createInboxEntry() calls for the same
+// recipient+sender pair (e.g. rapid consolidation/notification writes), and
+// the caller-supplied `sequence` field is not guaranteed to be unique either
+// (it defaults to 0 and callers are not required to increment it). The
+// counter guarantees every id generated within this process is distinct even
+// when Date.now() does not advance between calls.
+let _inboxIdCounter = 0;
+
+// Generate a likely-unique inbox entry ID:
+// <recipient>-<timestamp>-<sender>-<seq>-<counter>-<random>
+// `sequence` is preserved for callers that pass a meaningful value; the
+// monotonic counter + random suffix are what actually make the id
+// collision-proof, independent of clock resolution or caller behavior.
+function _generateInboxId(recipientSessionId, senderId, sequence) {
+  const now = Date.now();
+  _inboxIdCounter = (_inboxIdCounter + 1) % 0x1000000;
+  const rand = crypto.randomBytes(4).toString('hex');
+  return `${recipientSessionId}-${now}-${senderId}-${sequence}-${_inboxIdCounter.toString(36)}-${rand}`;
+}
+
+// Read all inbox entries for a given recipient session, ordered by time descending.
+function _readInboxEntriesFromSql(db, { recipientSessionId } = {}) {
+  let query = 'SELECT * FROM inbox_entries';
+  const params = [];
+  if (recipientSessionId) {
+    query += ' WHERE recipient_session_id = ?';
+    params.push(recipientSessionId);
+  }
+  query += ' ORDER BY sent_at DESC';
+  return db.prepare(query).all(...params);
+}
+
+// Read unread count for a recipient.
+function getInboxUnreadCount(recipientSessionId) {
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+  const row = db.prepare('SELECT COUNT(*) AS count FROM inbox_entries WHERE recipient_session_id = ? AND unread = 1')
+    .get(recipientSessionId);
+  return row ? row.count : 0;
+}
+
+// Read all inbox entries for a recipient session.
+function getInboxForSession(recipientSessionId, { limit = null, offset = 0 } = {}) {
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+  let query = 'SELECT * FROM inbox_entries WHERE recipient_session_id = ? ORDER BY sent_at DESC';
+  const params = [recipientSessionId];
+  if (limit) {
+    query += ' LIMIT ? OFFSET ?';
+    params.push(limit, offset);
+  }
+  return db.prepare(query).all(...params);
+}
+
+// Read a single inbox entry by ID.
+function getInboxEntryById(id) {
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+  return db.prepare('SELECT * FROM inbox_entries WHERE id = ?').get(id);
+}
+
+// Create a new inbox entry. Returns the entry object.
+function createInboxEntry({
+  recipientSessionId,
+  senderId,
+  senderName,
+  senderType,
+  interactionId,
+  summary,
+  content,
+  sequence = 0,
+}) {
+  if (!recipientSessionId || !senderId || !senderName || !senderType || !interactionId || !summary || !content) {
+    throw new Error('inbox-store: missing required fields for createInboxEntry');
+  }
+  if (!['agent', 'system', 'operator'].includes(senderType)) {
+    throw new Error(`inbox-store: invalid senderType "${senderType}"`);
+  }
+
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+
+  const MAX_ID_COLLISION_RETRIES = 5;
+
+  return withTransaction(db, () => {
+    const now = Date.now();
+    const insert = db.prepare(`
+      INSERT INTO inbox_entries
+        (id, recipient_session_id, sender_id, sender_name, sender_type, interaction_id,
+         sequence, summary, content, unread, sent_at, read_at, notified_at)
+      VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, 1, ?, NULL, NULL)
+    `);
+
+    // _generateInboxId() is collision-proof in practice (monotonic
+    // per-process counter + random suffix), but retry-on-conflict is kept as
+    // defense-in-depth against an id collision from any other source (e.g. a
+    // pre-existing row imported/replayed from another process) rather than
+    // letting a rare UNIQUE-constraint failure crash the caller.
+    let id;
+    for (let attempt = 0; attempt < MAX_ID_COLLISION_RETRIES; attempt++) {
+      id = _generateInboxId(recipientSessionId, senderId, sequence);
+      try {
+        insert.run(id, recipientSessionId, senderId, senderName, senderType, interactionId, sequence, summary, content, now);
+        break;
+      } catch (e) {
+        const isUniqueViolation = e && (e.code === 'ERR_SQLITE_ERROR' || e.errcode === 1555 || /UNIQUE constraint failed/.test(e.message || ''));
+        if (!isUniqueViolation || attempt === MAX_ID_COLLISION_RETRIES - 1) throw e;
+        // Regenerate and retry — the monotonic counter guarantees the next
+        // attempt produces a different id.
+      }
+    }
+
+    return getInboxEntryById(id);
+  });
+}
+
+// Mark one or more inbox entries as read.
+function markInboxEntriesAsRead(entryIds) {
+  if (!Array.isArray(entryIds) || !entryIds.length) return { wrote: false };
+
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    const now = Date.now();
+    const placeholders = entryIds.map(() => '?').join(',');
+    const query = `UPDATE inbox_entries SET unread = 0, read_at = ? WHERE id IN (${placeholders})`;
+    const stmt = db.prepare(query);
+    const result = stmt.run(now, ...entryIds);
+    return { wrote: result.changes > 0 };
+  });
+}
+
+// Mark one or more inbox entries as unread.
+function markInboxEntriesAsUnread(entryIds) {
+  if (!Array.isArray(entryIds) || !entryIds.length) return { wrote: false };
+
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    const placeholders = entryIds.map(() => '?').join(',');
+    const query = `UPDATE inbox_entries SET unread = 1, read_at = NULL WHERE id IN (${placeholders})`;
+    const stmt = db.prepare(query);
+    const result = stmt.run(...entryIds);
+    return { wrote: result.changes > 0 };
+  });
+}
+
+// Mark all inbox entries for a recipient as read.
+function markAllInboxAsRead(recipientSessionId) {
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    const now = Date.now();
+    const result = db.prepare(
+      'UPDATE inbox_entries SET unread = 0, read_at = ? WHERE recipient_session_id = ? AND unread = 1'
+    ).run(now, recipientSessionId);
+    return { wrote: result.changes > 0 };
+  });
+}
+
+// Delete an inbox entry by ID.
+function deleteInboxEntry(id) {
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    const result = db.prepare('DELETE FROM inbox_entries WHERE id = ?').run(id);
+    return { wrote: result.changes > 0 };
+  });
+}
+
+// Delete multiple inbox entries by ID.
+function deleteInboxEntries(entryIds) {
+  if (!Array.isArray(entryIds) || !entryIds.length) return { wrote: false };
+
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    const placeholders = entryIds.map(() => '?').join(',');
+    const query = `DELETE FROM inbox_entries WHERE id IN (${placeholders})`;
+    const result = db.prepare(query).run(...entryIds);
+    return { wrote: result.changes > 0 };
+  });
+}
+
+// Delete all unread entries older than a given timestamp (in milliseconds).
+// Used for cleanup/archival.
+function deleteInboxEntriesOlderThan(timestampMs, { unreadOnly = false } = {}) {
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    let query = 'DELETE FROM inbox_entries WHERE sent_at < ?';
+    const params = [timestampMs];
+    if (unreadOnly) {
+      query += ' AND unread = 1';
+    }
+    const result = db.prepare(query).run(...params);
+    return { wrote: result.changes > 0, deletedCount: result.changes };
+  });
+}
+
+// Retrieve inbox entries grouped by interaction_id.
+function getInboxByInteraction(interactionId) {
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+  return db.prepare('SELECT * FROM inbox_entries WHERE interaction_id = ? ORDER BY sent_at ASC')
+    .all(interactionId);
+}
+
+// Retrieve all unread entries for all recipients.
+function getAllUnreadInboxEntries() {
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+  return db.prepare('SELECT * FROM inbox_entries WHERE unread = 1 ORDER BY sent_at DESC').all();
+}
+
+// Update the notified_at timestamp for an entry (marks when a notification was sent).
+function markInboxEntryNotified(id) {
+  let db;
+  try { db = getDb(); }
+  catch (e) { throw new Error(`inbox-store: SQLite unavailable (${e.message})`); }
+
+  return withTransaction(db, () => {
+    const now = Date.now();
+    const result = db.prepare('UPDATE inbox_entries SET notified_at = ? WHERE id = ?').run(now, id);
+    return { wrote: result.changes > 0 };
+  });
+}
+
+module.exports = {
+  // Read operations
+  getInboxUnreadCount,
+  getInboxForSession,
+  getInboxEntryById,
+  getInboxByInteraction,
+  getAllUnreadInboxEntries,
+
+  // Write operations
+  createInboxEntry,
+  markInboxEntriesAsRead,
+  markInboxEntriesAsUnread,
+  markAllInboxAsRead,
+  markInboxEntryNotified,
+  deleteInboxEntry,
+  deleteInboxEntries,
+  deleteInboxEntriesOlderThan,
+};

package/engine/live-checkout.js

@@ -395,6 +395,27 @@ function _defaultResolveAutoBaseRepair(localPath) {
   }
 }
 
+// W-mrdlcud2000e630e — production default for resolving the live-checkout
+// auto-freshen decision when the caller (engine.js spawnAgent) does not pass an
+// explicit `autoFreshen` boolean. Mirrors `_defaultResolveAutoReset` /
+// `_defaultResolveAutoBaseRepair`: self-resolve from config.json by matching the
+// project on `localPath`, defer to `shared.resolveLiveCheckoutAutoFreshen`. Runs
+// only on the new-branch-fork path when HEAD is on mainRef (cold, not hot).
+// Fails CLOSED — any config read error returns false so a glitch can never
+// silently trigger the one sanctioned live-mode fetch.
+function _defaultResolveAutoFreshen(localPath) {
+  try {
+    const config = shared.safeJson(path.join(shared.MINIONS_DIR, 'config.json')) || {};
+    const projects = shared.getProjects(config);
+    const norm = (p) => path.resolve(String(p || '')).replace(/\\/g, '/').toLowerCase();
+    const target = norm(localPath);
+    const project = projects.find((p) => p && p.localPath && norm(p.localPath) === target) || null;
+    return shared.resolveLiveCheckoutAutoFreshen(project, config.engine);
+  } catch {
+    return false;
+  }
+}
+
 // W-mqvejug6000eeb20 — production default inbox-note writer for the auto-reset
 // audit trail. Lazily required to avoid a load-order cycle (dispatch.js does not
 // require live-checkout.js, but the lazy require keeps this module importable in
@@ -443,6 +464,110 @@ async function _resolveMainRefForRestore({ git, baseOpts, mainRef, autoBaseRepai
   }
 }
 
+// W-mrdlcud2000e630e — AUTO-FRESHEN (opt-in). The ONE sanctioned live-mode fetch.
+// Called from prepareLiveCheckout BEFORE the STALE-BASE GUARD, only when: the
+// tree is clean (Step 1 already bailed on a dirty tree), no mid-operation state
+// (Step 2), HEAD is on `mainRef`, and this is NOT an allowNonMainBase
+// (PR-targeted / shared-branch) dispatch. Fetches `origin <mainRef>` then
+// fast-forwards the local `mainRef` to `origin/<mainRef>` ONLY in the strictly
+// safe case — ZERO commits ahead of origin (i.e. NOT the stale-base-with-
+// unpushed-commits case, which must keep hitting the guard's refusal) AND
+// strictly behind. A `--ff-only` merge can never rewrite history or drop local
+// commits (there are none ahead). Every failure path (fetch error, divergence
+// unknown, ahead>0, up-to-date, ff refusal) returns WITHOUT mutating so the
+// caller falls through to the pre-existing stale-base check unchanged
+// ("fail open"). Best-effort audit: a low-noise inbox note + info log record the
+// before/after SHA only when a freshen actually happened (never on every
+// dispatch). Never throws.
+async function _maybeAutoFreshenLocalMain(opts = {}) {
+  const { git, baseOpts, mainRef, branchName, logFn, wiId, dispatchId, writeNote } = opts;
+  const log = (typeof logFn === 'function') ? logFn : () => {};
+  // Step 1: the ONE sanctioned live-mode fetch. Fail OPEN on any error.
+  try {
+    await git(['fetch', 'origin', mainRef], baseOpts);
+  } catch (fetchErr) {
+    log(
+      `[live-checkout] auto-freshen: 'git fetch origin ${mainRef}' failed ` +
+      `(${String((fetchErr && fetchErr.message) || fetchErr).slice(0, 200)}); ` +
+      `failing open to the existing stale-base check with the un-fetched local ref.`,
+      'warn'
+    );
+    return { freshened: false, reason: 'fetch-failed' };
+  }
+  // Step 2: compute divergence against the freshly-updated origin/<mainRef>.
+  let ahead = -1;
+  let behind = -1;
+  try {
+    const aheadRaw = await git(['rev-list', '--count', `refs/remotes/origin/${mainRef}..${mainRef}`], baseOpts);
+    ahead = parseInt((typeof aheadRaw === 'string' ? aheadRaw : '').trim(), 10);
+    if (Number.isNaN(ahead)) ahead = -1;
+    const behindRaw = await git(['rev-list', '--count', `${mainRef}..refs/remotes/origin/${mainRef}`], baseOpts);
+    behind = parseInt((typeof behindRaw === 'string' ? behindRaw : '').trim(), 10);
+    if (Number.isNaN(behind)) behind = -1;
+  } catch {
+    log(
+      `[live-checkout] auto-freshen: could not compute divergence of local '${mainRef}' vs 'origin/${mainRef}' ` +
+      `after fetch; proceeding to the existing stale-base check.`,
+      'debug'
+    );
+    return { freshened: false, reason: 'divergence-unknown' };
+  }
+  // Step 3: only the strictly-safe case. ahead>0 must fall through UNTOUCHED to
+  // the STALE-BASE GUARD refusal; up-to-date/behind-unknown needs no freshen.
+  if (ahead !== 0 || behind <= 0) {
+    return { freshened: false, reason: ahead > 0 ? 'ahead' : 'up-to-date' };
+  }
+  let beforeSha = '';
+  let afterSha = '';
+  try {
+    const beforeRaw = await git(['rev-parse', '--verify', '--quiet', `refs/heads/${mainRef}`], baseOpts);
+    beforeSha = (typeof beforeRaw === 'string' ? beforeRaw : '').trim();
+  } catch { /* best-effort — informational only */ }
+  // Step 4: fast-forward-only. HEAD is on mainRef (caller-gated), so a plain
+  // `git merge --ff-only origin/<mainRef>` advances the checked-out base. If it
+  // unexpectedly fails (e.g. a race committed onto local mainRef between the
+  // ahead-count and here), FAIL OPEN — the stale-base guard below still protects
+  // against forking off a contaminated base.
+  try {
+    await git(['merge', '--ff-only', `refs/remotes/origin/${mainRef}`], baseOpts);
+  } catch (ffErr) {
+    log(
+      `[live-checkout] auto-freshen: fast-forward of '${mainRef}' to 'origin/${mainRef}' failed ` +
+      `(${String((ffErr && ffErr.message) || ffErr).slice(0, 200)}); failing open to the existing stale-base check.`,
+      'warn'
+    );
+    return { freshened: false, reason: 'ff-failed' };
+  }
+  try {
+    const afterRaw = await git(['rev-parse', '--verify', '--quiet', `refs/heads/${mainRef}`], baseOpts);
+    afterSha = (typeof afterRaw === 'string' ? afterRaw : '').trim();
+  } catch { /* best-effort — informational only */ }
+  log(
+    `[live-checkout] auto-freshen: fast-forwarded local '${mainRef}' ${behind} commit(s) ` +
+    `from ${beforeSha.slice(0, 12) || '(unknown)'} to ${afterSha.slice(0, 12) || '(unknown)'} ` +
+    `(origin/${mainRef}) before forking '${branchName}' (liveCheckoutAutoFreshen).`,
+    'info'
+  );
+  // Best-effort low-noise audit trail. Only fires on an actual freshen (rare),
+  // so it never alert-spams a healthy dispatch. Never throws.
+  try {
+    const write = (typeof writeNote === 'function') ? writeNote : _defaultWriteInboxNote;
+    const slug = `live-checkout-autofreshen-${wiId || dispatchId || 'unknown'}`;
+    const body = [
+      `# Live-checkout auto-freshen of '${mainRef}'`,
+      '',
+      `The live-checkout base branch \`${mainRef}\` was behind \`origin/${mainRef}\` by ${behind} commit(s)`,
+      `with no local-ahead commits, so \`liveCheckoutAutoFreshen\` fast-forwarded it before forking`,
+      `\`${branchName}\`. This is a non-destructive \`--ff-only\` update (no history rewrite, no lost work):`,
+      '',
+      `- before: \`${beforeSha || '(unknown)'}\``,
+      `- after:  \`${afterSha || '(unknown)'}\` (= \`origin/${mainRef}\`)`,
+    ].join('\n');
+    write(slug, body);
+  } catch { /* best-effort audit note */ }
+  return { freshened: true, before: beforeSha, after: afterSha, behind };
+}
+
 async function prepareLiveCheckout(opts = {}) {
   const {
     localPath,
@@ -466,11 +591,18 @@ async function prepareLiveCheckout(opts = {}) {
                      // defers to `_resolveAutoBaseRepair`. When enabled, the
                      // wrong-base recovery may materialize a local base branch from
                      // `refs/remotes/origin/<mainRef>` (no fetch) instead of failing.
+    autoFreshen, // W-mrdlcud2000e630e: tri-state. `true`/`false` short-circuits
+                 // config resolution; `undefined` (the engine.js call shape)
+                 // defers to `_resolveAutoFreshen`. When enabled AND HEAD is on
+                 // mainRef with zero local-ahead commits but behind origin, the
+                 // ONE sanctioned live-mode `git fetch origin <mainRef>` +
+                 // `--ff-only` fast-forward runs before the stale-base guard.
     _git,       // private injection for testing — defaults to shared.shellSafeGit
     _exists,    // private injection for testing — defaults to fs.existsSync
     _rm,        // private injection for testing — defaults to fs.rmSync (recursive, force)
     _resolveAutoReset, // private injection for testing — defaults to config-based resolver
     _resolveAutoBaseRepair, // private injection for testing — defaults to config-based resolver
+    _resolveAutoFreshen, // private injection for testing — defaults to config-based resolver
     _writeInboxNote,   // private injection for testing — defaults to dispatch.writeInboxAlert
     _sleep,            // private injection for testing — defaults to a real setTimeout-based sleep
   } = opts;
@@ -1082,6 +1214,41 @@ async function prepareLiveCheckout(opts = {}) {
   }
 
 
+  // ── Step 4d-freshen: AUTO-FRESHEN (opt-in, W-mrdlcud2000e630e). ────────
+  // BEFORE the STALE-BASE GUARD, optionally fast-forward the local base branch
+  // to origin/<mainRef> so the new branch forks off the freshest safe base.
+  // This is the ONE sanctioned live-mode fetch (issue #226 otherwise forbids
+  // fetching live checkouts to preserve operator control over history rewrites).
+  //
+  // Scope mirrors the STALE-BASE GUARD's skip conditions EXACTLY: it runs only
+  // when HEAD is on mainRef (`curBranch === mainRef` — the base we fork off) and
+  // this is NOT an allowNonMainBase (PR-targeted fix / shared-branch
+  // continuation) dispatch. The dirty-tree bail (Step 1) and mid-operation
+  // preflight (Step 2) have already run, so a dirty or mid-operation tree never
+  // reaches here — the freshen is never attempted on one.
+  //
+  // The helper only fast-forwards in the strictly-safe case (zero commits ahead
+  // of origin AND behind origin); the ahead>0 stale-base case is left UNTOUCHED
+  // so the guard below still refuses it. A `--ff-only` update can never rewrite
+  // history or drop local commits, and any fetch/network/ff failure fails OPEN
+  // to the un-freshened stale-base check. Applies uniformly to plain live mode
+  // and hybrid mode's liveValidation dispatch (both reuse this preflight).
+  if (!allowNonMainBase && curBranch && curBranch === mainRef) {
+    let wantFreshen = false;
+    if (typeof autoFreshen === 'boolean') {
+      wantFreshen = autoFreshen;
+    } else {
+      const resolver = (typeof _resolveAutoFreshen === 'function') ? _resolveAutoFreshen : _defaultResolveAutoFreshen;
+      try { wantFreshen = !!resolver(localPath); } catch { wantFreshen = false; }
+    }
+    if (wantFreshen) {
+      await _maybeAutoFreshenLocalMain({
+        git, baseOpts, mainRef, branchName, logFn, wiId, dispatchId,
+        writeNote: (typeof _writeInboxNote === 'function') ? _writeInboxNote : undefined,
+      });
+    }
+  }
+
   // ── 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
@@ -1877,6 +2044,7 @@ module.exports = {
   _looksLikeAgentBranch,
   _extractBranchFromPorcelainHeader,
   _commitAgentWipWithRetry,
+  _maybeAutoFreshenLocalMain,
   capDirtyFileLines,
   DIRTY_ALERT_MAX_LINES,
   LIVE_CHECKOUT_AUTO_CLEAN_PATTERNS,