@yemi33/minions 0.1.1748 → 0.1.1750

package/CHANGELOG.md

@@ -1,5 +1,10 @@
 # Changelog
 
+## 0.1.1750 (2026-05-06)
+
+### Fixes
+- lock doc-chat into plain-response mode (no tool calls) (#2127)
+
 ## 0.1.1748 (2026-05-06)
 
 ### Fixes

package/dashboard.js

@@ -268,6 +268,30 @@ function resolveWorkItemsCreateTarget(projectName, projects = PROJECTS) {
     wiPath: targetProject ? shared.projectWorkItemsPath(targetProject) : path.join(MINIONS_DIR, 'work-items.json'),
   };
 }
+
+/**
+ * Aggregate archived work items from the central archive plus every project
+ * archive. Each item is tagged with `_source` (`'central'` or the project name)
+ * so the UI can group/filter. Reads via `safeJsonArr` — a corrupt archive
+ * surfaces a logged parse failure and contributes zero items, instead of
+ * throwing 500 or silently dropping the file.
+ *
+ * Exported for testing (P-h3arch-8c19).
+ */
+function collectArchivedWorkItems(minionsDir = MINIONS_DIR, projects = PROJECTS) {
+  const archived = [];
+  const centralPath = path.join(minionsDir, 'work-items-archive.json');
+  for (const item of safeJsonArr(centralPath)) {
+    archived.push({ ...item, _source: 'central' });
+  }
+  for (const project of projects) {
+    const archPath = shared.projectWorkItemsPath(project).replace('.json', '-archive.json');
+    for (const item of safeJsonArr(archPath)) {
+      archived.push({ ...item, _source: project.name });
+    }
+  }
+  return archived;
+}
 function linkPullRequestForTracking({ url, title, project: projectName, autoObserve, context, workItemId }, config = CONFIG, options = {}) {
   if (!url) {
     const err = new Error('url required');
@@ -1137,8 +1161,14 @@ function _filterCcTabSessions(sessions) {
 }
 
 function _readCcTabSessions({ prune = true } = {}) {
-  const sessions = _filterCcTabSessions(shared.safeJsonArr(CC_SESSIONS_PATH));
-  if (prune) safeWrite(CC_SESSIONS_PATH, sessions);
+  if (!prune) return _filterCcTabSessions(shared.safeJsonArr(CC_SESSIONS_PATH));
+  // P-c2sess-1d8e: read+filter+write atomically under the file lock so a
+  // concurrent tab upsert/delete cannot lose entries to last-write-wins.
+  let sessions;
+  mutateJsonFileLocked(CC_SESSIONS_PATH, (raw) => {
+    sessions = _filterCcTabSessions(raw);
+    return sessions;
+  }, { defaultValue: [] });
   return sessions;
 }
 
@@ -2148,6 +2178,7 @@ async function executeDocChatActions(actions) {
 // Session store for doc modals — keyed by filePath or title, persisted to disk
 const CC_SESSIONS_PATH = path.join(ENGINE_DIR, 'cc-sessions.json');
 const DOC_SESSIONS_PATH = path.join(ENGINE_DIR, 'doc-sessions.json');
+const CC_SESSION_PATH = path.join(ENGINE_DIR, 'cc-session.json');
 const DOC_SESSION_TTL_MS = shared.ENGINE_DEFAULTS.docSessionTtlMs;
 const DOC_SESSION_MAX_ENTRIES = shared.ENGINE_DEFAULTS.docSessionMaxEntries;
 const docSessions = new Map(); // key → { sessionId, lastActiveAt, turnCount }
@@ -2196,7 +2227,8 @@ function persistDocSessions() {
   pruneDocSessions();
   const obj = {};
   for (const [key, s] of docSessions) obj[key] = s;
-  safeWrite(DOC_SESSIONS_PATH, obj);
+  // P-c2sess-1d8e: lock against engine/cleanup.js's cap-trim RMW.
+  mutateJsonFileLocked(DOC_SESSIONS_PATH, () => obj, { defaultValue: {} });
 }
 
 const _docSessionPruneTimer = setInterval(() => {
@@ -2261,7 +2293,7 @@ function updateSession(store, key, sessionId, existing) {
       turnCount: (existing ? ccSession.turnCount : 0) + 1,
       _promptHash: _ccPromptHash,
     };
-    safeWrite(path.join(ENGINE_DIR, 'cc-session.json'), ccSession);
+    mutateJsonFileLocked(CC_SESSION_PATH, () => ccSession, { defaultValue: {} });
   } else if (key) {
     const prev = docSessions.get(key);
     docSessions.set(key, {
@@ -2335,7 +2367,7 @@ async function ccCall(message, { store = 'cc', sessionKey, extraContext, label =
     // Invalidate the dead session so future calls don't try to resume it
     if (store === 'cc') {
       ccSession = { sessionId: null, createdAt: null, lastActiveAt: null, turnCount: 0 };
-      safeWrite(path.join(ENGINE_DIR, 'cc-session.json'), ccSession);
+      mutateJsonFileLocked(CC_SESSION_PATH, () => ccSession, { defaultValue: {} });
     } else if (sessionKey) {
       docSessions.delete(sessionKey);
       schedulePersistDocSessions();
@@ -2423,7 +2455,7 @@ async function ccCallStreaming(message, { store = 'cc', sessionKey, extraContext
     sessionId = null;
     if (store === 'cc') {
       ccSession = { sessionId: null, createdAt: null, lastActiveAt: null, turnCount: 0 };
-      safeWrite(path.join(ENGINE_DIR, 'cc-session.json'), ccSession);
+      mutateJsonFileLocked(CC_SESSION_PATH, () => ccSession, { defaultValue: {} });
     } else if (sessionKey) {
       docSessions.delete(sessionKey);
       schedulePersistDocSessions();
@@ -2614,8 +2646,11 @@ async function ccDocCall({ message, document, title, filePath, selection, canEdi
       store: 'doc', sessionKey,
       extraContext, label: 'doc-chat',
       timeout: DOC_CHAT_TIMEOUT_MS,
-      allowedTools: canEdit ? 'Read,Write,Edit,Glob,Grep' : 'Read,Glob,Grep',
-      maxTurns: canEdit ? 25 : 10,
+      // Match Command Center's full tool surface and turn budget so doc-chat
+      // can take action (read/write/edit/dispatch) instead of being limited
+      // to Q&A. The doc-chat sysprompt still scopes orchestration to explicit
+      // requests, and ---DOCUMENT--- remains the only document edit channel.
+      allowedTools: 'Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch',
       skipStatePreamble: true,
       systemPrompt: DOC_CHAT_SYSTEM_PROMPT,
       ...(model ? { model } : {}),
@@ -2670,8 +2705,10 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
       store: 'doc', sessionKey,
       extraContext, label: 'doc-chat',
       timeout: DOC_CHAT_TIMEOUT_MS,
-      allowedTools: canEdit ? 'Read,Write,Edit,Glob,Grep' : 'Read,Glob,Grep',
-      maxTurns: canEdit ? 25 : 10,
+      // Match Command Center's full tool surface — see ccDocCall for
+      // rationale. Both wrappers must share the same policy so the streaming
+      // variant doesn't diverge from the non-streaming one.
+      allowedTools: 'Bash,Read,Write,Edit,Glob,Grep,WebFetch,WebSearch',
       skipStatePreamble: true,
       systemPrompt: DOC_CHAT_SYSTEM_PROMPT,
       ...(model ? { model } : {}),
@@ -2713,12 +2750,31 @@ async function ccDocCallStreaming({ message, document, title, filePath, selectio
 function readBody(req) {
   return new Promise((resolve, reject) => {
     let body = '';
+    // P-c1read-7b3c: aborted closure flag prevents OOM from a misbehaving local
+    // client streaming forever after rejection. The data handler MUST early-return
+    // when aborted is true so no further chunks are appended.
+    let aborted = false;
     const timeout = setTimeout(() => {
+      // Set aborted FIRST so any late-arriving chunk (already in flight) is
+      // dropped by the data handler instead of growing body unbounded.
+      aborted = true;
       req.destroy();
       reject(new Error('Request body timeout after 30s'));
     }, 30000);
-    req.on('data', chunk => { body += chunk; if (body.length > 1e6) { clearTimeout(timeout); reject(new Error('Too large')); } });
+    req.on('data', chunk => {
+      if (aborted) return;
+      body += chunk;
+      if (body.length > 1e6) {
+        // Order matters: set aborted first so any in-flight chunk early-returns,
+        // then clear the timer, tear down the socket, and surface the failure.
+        aborted = true;
+        clearTimeout(timeout);
+        req.destroy();
+        reject(new Error('Too large'));
+      }
+    });
     req.on('end', () => {
+      if (aborted) return;
       clearTimeout(timeout);
       let parsed;
       try { parsed = JSON.parse(body); } catch(e) { reject(e); return; }
@@ -2732,7 +2788,11 @@ function readBody(req) {
       }
       resolve(parsed);
     });
-    req.on('error', (e) => { clearTimeout(timeout); reject(e); });
+    req.on('error', (e) => {
+      if (aborted) return;
+      clearTimeout(timeout);
+      reject(e);
+    });
   });
 }
 
@@ -3296,18 +3356,10 @@ const server = http.createServer(async (req, res) => {
 
   async function handleWorkItemsArchiveList(req, res) {
     try {
-      let allArchived = [];
-      // Central archive
-      const centralPath = path.join(MINIONS_DIR, 'work-items-archive.json');
-      const central = safeRead(centralPath);
-      if (central) { try { allArchived.push(...JSON.parse(central).map(i => ({ ...i, _source: 'central' }))); } catch {} }
-      // Project archives
-      for (const project of PROJECTS) {
-        const archPath = shared.projectWorkItemsPath(project).replace('.json', '-archive.json');
-        const content = safeRead(archPath);
-        if (content) { try { allArchived.push(...JSON.parse(content).map(i => ({ ...i, _source: project.name }))); } catch {} }
-      }
-      return jsonReply(res, 200, allArchived);
+      // collectArchivedWorkItems uses safeJsonArr (typed default + logged parse
+      // failure), so a corrupt archive file is surfaced via console.error and
+      // contributes zero items instead of taking down the whole listing.
+      return jsonReply(res, 200, collectArchivedWorkItems(MINIONS_DIR, PROJECTS));
     } catch (e) { console.error('Archive fetch error:', e.message); return jsonReply(res, e.statusCode || 500, { error: e.message }); }
   }
 
@@ -5320,7 +5372,11 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       const result = removeProject(target, { keepData: body.keepData === true, purge: body.purge === true });
       if (!result.ok) return jsonReply(res, result.error?.includes('No project') ? 404 : 400, result);
       reloadConfig();
-      invalidateStatusCache();
+      // includeSlow: getStatus() caches the projects[] field in slow state (60s
+      // TTL) — without flushing it, the removed project keeps appearing under
+      // status.projects for up to a minute even though PROJECTS in memory is
+      // already up to date.
+      invalidateStatusCache({ includeSlow: true });
       return jsonReply(res, 200, result);
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
@@ -5390,7 +5446,8 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       try { if (live.abortFn) live.abortFn(); } catch {}
       _clearCcLiveStream(tabId);
     }
-    safeWrite(path.join(ENGINE_DIR, 'cc-session.json'), ccSession);
+    // P-c2sess-1d8e: lock single-session reset against concurrent updateSession writes.
+    mutateJsonFileLocked(CC_SESSION_PATH, () => ccSession, { defaultValue: {} });
     return jsonReply(res, 200, { ok: true });
   }
 
@@ -5419,9 +5476,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
   async function handleCCSessionDelete(req, res, match) {
     const id = match?.[1];
     if (!id) return jsonReply(res, 400, { error: 'id required' });
-    const sessions = _readCcTabSessions();
-    const filtered = sessions.filter(s => s.id !== id);
-    safeWrite(CC_SESSIONS_PATH, filtered);
+    // P-c2sess-1d8e: one locked RMW so a concurrent upsert from the streaming
+    // handler cannot resurrect the deleted tab between read and write.
+    mutateJsonFileLocked(CC_SESSIONS_PATH, (raw) => {
+      const sessions = _filterCcTabSessions(raw);
+      return sessions.filter(s => s.id !== id);
+    }, { defaultValue: [] });
     return jsonReply(res, 200, { ok: true });
   }
 
@@ -5773,20 +5833,24 @@ What would you like to discuss or change? When you're happy, say "approve" and I
         const _persistTabId = body.tabId;
         if (_persistTabId && responseSessionId) {
           try {
-            const sessions = _readCcTabSessions();
-            const existing = sessions.find(s => s.id === _persistTabId);
+            // P-c2sess-1d8e: one locked RMW so concurrent multi-tab streams can't
+            // race on read+modify+write — both upsert paths share the lock.
             const preview = (body.message || '').slice(0, 80);
-            if (existing) {
-              existing.sessionId = responseSessionId;
-              existing.lastActiveAt = new Date(now).toISOString();
-              existing.turnCount = sessionReset ? 1 : (existing.turnCount || 0) + 1;
-              existing.preview = preview;
-              existing._promptHash = _ccPromptHash;
-              existing.runtime = currentRuntime;
-            } else {
-              sessions.push({ id: _persistTabId, title: (body.message || 'New chat').slice(0, 40), sessionId: responseSessionId, createdAt: new Date(now).toISOString(), lastActiveAt: new Date(now).toISOString(), turnCount: 1, preview, _promptHash: _ccPromptHash, runtime: currentRuntime });
-            }
-            safeWrite(CC_SESSIONS_PATH, sessions);
+            mutateJsonFileLocked(CC_SESSIONS_PATH, (raw) => {
+              const sessions = _filterCcTabSessions(raw);
+              const existing = sessions.find(s => s.id === _persistTabId);
+              if (existing) {
+                existing.sessionId = responseSessionId;
+                existing.lastActiveAt = new Date(now).toISOString();
+                existing.turnCount = sessionReset ? 1 : (existing.turnCount || 0) + 1;
+                existing.preview = preview;
+                existing._promptHash = _ccPromptHash;
+                existing.runtime = currentRuntime;
+              } else {
+                sessions.push({ id: _persistTabId, title: (body.message || 'New chat').slice(0, 40), sessionId: responseSessionId, createdAt: new Date(now).toISOString(), lastActiveAt: new Date(now).toISOString(), turnCount: 1, preview, _promptHash: _ccPromptHash, runtime: currentRuntime });
+              }
+              return sessions;
+            }, { defaultValue: [] });
           } catch { /* non-critical */ }
         }
 
@@ -7329,6 +7393,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 // Production entry points use the closures directly; tests import via require('./dashboard').
 module.exports = {
   getMcpServers,
+  readBody,
   _filterCcTabSessions,
   _getVersionCheckInterval,
   _parseWatchInterval,
@@ -7345,6 +7410,7 @@ module.exports = {
   _findDuplicateWorkItemCreate: findDuplicateWorkItemCreate,
   _createWorkItemWithDedup: createWorkItemWithDedup,
   _resolveWorkItemsCreateTarget: resolveWorkItemsCreateTarget,
+  _collectArchivedWorkItems: collectArchivedWorkItems,
   _createPipelineFromAction: createPipelineFromAction,
   executeCCActions,
   buildCCStatePreamble,

package/engine/cleanup.js

@@ -687,21 +687,21 @@ async function runCleanup(config, verbose = false) {
   // silently invalidate live chat tabs the user expects to keep.
   cleaned.ccSessions = 0;
 
-  // 10b. Prune doc-chat sessions — cap at 100 entries, remove oldest beyond cap
+  // 10b. Prune doc-chat sessions — cap at 100 entries, remove oldest beyond cap.
+  // P-c2sess-1d8e: read+sort+write must run atomically under the file lock so a
+  // concurrent dashboard persistDocSessions can't race the cap-trim.
   cleaned.docSessions = 0;
   try {
     const docSessionsPath = path.join(ENGINE_DIR, 'doc-sessions.json');
-    const docSessions = safeJson(docSessionsPath);
-    if (docSessions && typeof docSessions === 'object') {
+    const DOC_SESSIONS_CAP = 100;
+    mutateJsonFileLocked(docSessionsPath, (docSessions) => {
+      if (!docSessions || typeof docSessions !== 'object' || Array.isArray(docSessions)) return docSessions;
       const entries = Object.entries(docSessions);
-      const DOC_SESSIONS_CAP = 100;
-      if (entries.length > DOC_SESSIONS_CAP) {
-        entries.sort((a, b) => new Date(b.lastActiveAt || 0) - new Date(a.lastActiveAt || 0));
-        const keep = Object.fromEntries(entries.slice(0, DOC_SESSIONS_CAP));
-        cleaned.docSessions = entries.length - DOC_SESSIONS_CAP;
-        safeWrite(docSessionsPath, keep);
-      }
-    }
+      if (entries.length <= DOC_SESSIONS_CAP) return docSessions;
+      entries.sort((a, b) => new Date(b.lastActiveAt || 0) - new Date(a.lastActiveAt || 0));
+      cleaned.docSessions = entries.length - DOC_SESSIONS_CAP;
+      return Object.fromEntries(entries.slice(0, DOC_SESSIONS_CAP));
+    }, { defaultValue: {}, skipWriteIfUnchanged: true });
   } catch (e) { log('warn', 'prune doc-sessions: ' + e.message); }
 
   // 11. Cap cooldowns.json — keep at most 500 entries (on top of 24h TTL in cooldown.js)

package/engine/copilot-models.json

@@ -1,5 +1,5 @@
 {
   "runtime": "copilot",
   "models": null,
-  "cachedAt": "2026-05-06T18:53:33.751Z"
+  "cachedAt": "2026-05-06T20:21:49.605Z"
 }

package/engine/meeting.js

@@ -6,7 +6,7 @@
 const fs = require('fs');
 const path = require('path');
 const shared = require('./shared');
-const { safeJson, safeWrite, safeRead, uid, log, ts, ENGINE_DEFAULTS, WORK_TYPE, DISPATCH_RESULT } = shared;
+const { safeJson, uid, log, ts, ENGINE_DEFAULTS, WORK_TYPE, DISPATCH_RESULT } = shared;
 const queries = require('./queries');
 const { getDispatch, getConfig } = queries;
 const { renderPlaybook } = require('./playbook');
@@ -349,9 +349,57 @@ function getMeeting(id) {
   return m;
 }
 
-function saveMeeting(meeting) {
+/**
+ * Read-modify-write helper for meetings/<id>.json under a file lock.
+ *
+ * Mirrors the mutateDispatch / mutateWorkItems / mutatePullRequests pattern.
+ * Use this for ANY change to a meeting's persisted state — bare safeWrite
+ * losses concurrent agent findings (every meeting round writes from a
+ * separate agent process).
+ *
+ * `fn` receives the parsed meeting object (with default fields populated like
+ * getMeeting), or `null` when the file is absent. Return the mutated meeting
+ * to persist it; return `null`/`undefined` to skip the write (the underlying
+ * mutateJsonFileLocked handles the no-op via skipWriteIfUnchanged).
+ *
+ * CRITICAL: keep `fn` fast. Never spawn agents, kill processes, run git
+ * commands, or `await` inside the callback — the lock is held for the
+ * duration of the synchronous call. Do that work BEFORE or AFTER mutateMeeting.
+ */
+function mutateMeeting(id, fn) {
   if (!fs.existsSync(MEETINGS_DIR)) fs.mkdirSync(MEETINGS_DIR, { recursive: true });
-  safeWrite(path.join(MEETINGS_DIR, meeting.id + '.json'), meeting);
+  const filePath = path.join(MEETINGS_DIR, id + '.json');
+  let userResult;
+  shared.mutateJsonFileLocked(filePath, (data) => {
+    const isMeeting = data && typeof data === 'object' && !Array.isArray(data) && data.id;
+    const meeting = isMeeting ? data : null;
+    if (meeting) {
+      // Match getMeeting()'s default-field normalization.
+      if (!meeting.findings) meeting.findings = {};
+      if (!meeting.debate) meeting.debate = {};
+      if (!meeting.humanNotes) meeting.humanNotes = [];
+      if (!meeting.participants) meeting.participants = [];
+      if (!meeting.transcript) meeting.transcript = [];
+      if (!meeting.roundFailures || typeof meeting.roundFailures !== 'object') meeting.roundFailures = {};
+    }
+    userResult = fn(meeting);
+    if (userResult === undefined || userResult === null) {
+      // Skip-write: return original data so JSON.stringify equality holds
+      // and mutateJsonFileLocked's skipWriteIfUnchanged guard takes effect.
+      return data;
+    }
+    return userResult;
+  }, { defaultValue: {}, skipWriteIfUnchanged: true });
+  return userResult === undefined ? null : userResult;
+}
+
+/**
+ * Persist a meeting object as-is. Thin wrapper over mutateMeeting so every
+ * write goes through the file lock — covers the create-new-file path
+ * (createMeeting) and any tests that pre-seed meeting state.
+ */
+function saveMeeting(meeting) {
+  return mutateMeeting(meeting.id, () => meeting);
 }
 
 function createMeeting({ title, agenda, participants }) {
@@ -529,92 +577,98 @@ function discoverMeetingWork(config) {
  * Called from runPostCompletionHooks when type === 'meeting'.
  */
 function collectMeetingFindings(meetingId, agentId, roundName, output, structuredCompletion = null, expectedRound = null, completionInfo = {}) {
-  const meeting = getMeeting(meetingId);
-  if (!meeting) return;
-  if (isTerminalMeetingStatus(meeting.status)) {
-    log('info', `Ignoring late findings from ${agentId} for completed meeting ${meetingId}`);
-    return;
-  }
-
-  const expectedStatus = expectedMeetingStatusForRound(roundName);
-  if (!expectedStatus) {
-    log('warn', `Meeting ${meetingId}: ignoring ${agentId} output for unknown round "${roundName || '(empty)'}"`);
-    return;
-  }
-  if (meeting.status !== expectedStatus) {
-    log('info', `Ignoring stale ${roundName} output from ${agentId} for meeting ${meetingId} currently ${meeting.status}`);
-    return;
-  }
-  if (expectedRound !== null && expectedRound !== undefined && Number(meeting.round || 1) !== Number(expectedRound)) {
-    log('info', `Ignoring stale round ${expectedRound} output from ${agentId} for meeting ${meetingId} currently on round ${meeting.round || 1}`);
-    return;
-  }
-  if (hasRoundTerminalOutcome(meeting, roundName, agentId, meeting.round)) {
-    log('info', `Ignoring duplicate ${roundName} output from ${agentId} for meeting ${meetingId}`);
-    return;
-  }
-
+  // Resolve content OUTSIDE the lock — file reads (note artifacts) and stream
+  // parsing are slow and lock callbacks must stay fast.
   const content = resolveMeetingContributionContent(output, structuredCompletion);
   const completionSucceeded = completionInfo?.success !== false;
 
-  if (!completionSucceeded || isEmptyMeetingContent(content)) {
-    const failures = getRoundFailures(meeting, roundName, meeting.round, true);
-    const reason = !completionSucceeded
-      ? (completionInfo?.reason || completionInfo?.completionStatus || 'Agent failed before completing the meeting round')
-      : 'Agent produced empty meeting output';
-    failures[agentId] = {
-      reason,
-      content: content || completionInfo?.summary || '',
-      submittedAt: ts(),
-    };
-    meeting.transcript.push({
-      round: meeting.round,
-      agent: agentId,
-      type: 'failure',
-      content: reason,
-      at: ts(),
-    });
-    log('warn', `Meeting ${meetingId}: agent ${agentId} failed ${roundName} — ${reason}`);
-    advanceMeetingIfRoundComplete(meeting, roundName, meetingId);
-    saveMeeting(meeting);
-    return;
-  }
+  let concludedMeeting = null;
+  let configForInbox = null;
 
-  if (roundName === 'investigate') {
-    meeting.findings[agentId] = { content, submittedAt: ts() };
-    meeting.transcript.push({ round: meeting.round, agent: agentId, type: 'finding', content, at: ts() });
-  } else if (roundName === 'debate') {
-    meeting.debate[agentId] = { content, submittedAt: ts() };
-    meeting.transcript.push({ round: meeting.round, agent: agentId, type: 'debate', content, at: ts() });
-  } else if (roundName === 'conclude') {
-    meeting.conclusion = { content, agent: agentId, submittedAt: ts() };
-    meeting.transcript.push({ round: meeting.round, agent: agentId, type: 'conclusion', content, at: ts() });
-    meeting.status = 'completed';
-    meeting.completedAt = ts();
+  mutateMeeting(meetingId, (meeting) => {
+    if (!meeting) return null; // file missing — nothing to do
+    if (isTerminalMeetingStatus(meeting.status)) {
+      log('info', `Ignoring late findings from ${agentId} for completed meeting ${meetingId}`);
+      return null;
+    }
+
+    const expectedStatus = expectedMeetingStatusForRound(roundName);
+    if (!expectedStatus) {
+      log('warn', `Meeting ${meetingId}: ignoring ${agentId} output for unknown round "${roundName || '(empty)'}"`);
+      return null;
+    }
+    if (meeting.status !== expectedStatus) {
+      log('info', `Ignoring stale ${roundName} output from ${agentId} for meeting ${meetingId} currently ${meeting.status}`);
+      return null;
+    }
+    if (expectedRound !== null && expectedRound !== undefined && Number(meeting.round || 1) !== Number(expectedRound)) {
+      log('info', `Ignoring stale round ${expectedRound} output from ${agentId} for meeting ${meetingId} currently on round ${meeting.round || 1}`);
+      return null;
+    }
+    if (hasRoundTerminalOutcome(meeting, roundName, agentId, meeting.round)) {
+      log('info', `Ignoring duplicate ${roundName} output from ${agentId} for meeting ${meetingId}`);
+      return null;
+    }
+
+    if (!completionSucceeded || isEmptyMeetingContent(content)) {
+      const failures = getRoundFailures(meeting, roundName, meeting.round, true);
+      const reason = !completionSucceeded
+        ? (completionInfo?.reason || completionInfo?.completionStatus || 'Agent failed before completing the meeting round')
+        : 'Agent produced empty meeting output';
+      failures[agentId] = {
+        reason,
+        content: content || completionInfo?.summary || '',
+        submittedAt: ts(),
+      };
+      meeting.transcript.push({
+        round: meeting.round,
+        agent: agentId,
+        type: 'failure',
+        content: reason,
+        at: ts(),
+      });
+      log('warn', `Meeting ${meetingId}: agent ${agentId} failed ${roundName} — ${reason}`);
+      advanceMeetingIfRoundComplete(meeting, roundName, meetingId);
+      return meeting;
+    }
+
+    if (roundName === 'investigate') {
+      meeting.findings[agentId] = { content, submittedAt: ts() };
+      meeting.transcript.push({ round: meeting.round, agent: agentId, type: 'finding', content, at: ts() });
+    } else if (roundName === 'debate') {
+      meeting.debate[agentId] = { content, submittedAt: ts() };
+      meeting.transcript.push({ round: meeting.round, agent: agentId, type: 'debate', content, at: ts() });
+    } else if (roundName === 'conclude') {
+      meeting.conclusion = { content, agent: agentId, submittedAt: ts() };
+      meeting.transcript.push({ round: meeting.round, agent: agentId, type: 'conclusion', content, at: ts() });
+      meeting.status = 'completed';
+      meeting.completedAt = ts();
+      // Defer inbox write until AFTER the lock releases — writeToInbox hits
+      // the filesystem (slug dedup, write) and must not block other writers.
+      concludedMeeting = meeting;
+      try { configForInbox = queries.getConfig(); } catch { configForInbox = { agents: {} }; }
+      return meeting;
+    }
 
-    // Write transcript to inbox so agents learn from it (slug-based dedup)
+    advanceMeetingIfRoundComplete(meeting, roundName, meetingId);
+    return meeting;
+  });
+
+  if (concludedMeeting) {
     try {
-      const config = queries.getConfig();
-      writeMeetingTranscriptToInbox(meeting, meetingId, config.agents || {});
+      writeMeetingTranscriptToInbox(concludedMeeting, meetingId, (configForInbox && configForInbox.agents) || {});
     } catch (e) { log('warn', `Meeting ${meetingId} inbox write: ${e.message}`); }
-
     log('info', `Meeting ${meetingId} completed — transcript written to inbox`);
-    saveMeeting(meeting);
-    return;
   }
-
-  advanceMeetingIfRoundComplete(meeting, roundName, meetingId);
-
-  saveMeeting(meeting);
 }
 
 function addMeetingNote(meetingId, note) {
-  const meeting = getMeeting(meetingId);
-  if (!meeting) return null;
-  meeting.humanNotes.push(note);
-  meeting.transcript.push({ round: meeting.round, agent: 'human', type: 'note', content: note, at: ts() });
-  saveMeeting(meeting);
-  return meeting;
+  return mutateMeeting(meetingId, (meeting) => {
+    if (!meeting) return null;
+    meeting.humanNotes.push(note);
+    meeting.transcript.push({ round: meeting.round, agent: 'human', type: 'note', content: note, at: ts() });
+    return meeting;
+  });
 }
 
 function _killMeetingDispatches(meetingId) {
@@ -672,44 +726,60 @@ function _killMeetingDispatches(meetingId) {
 }
 
 function advanceMeetingRound(meetingId) {
-  const meeting = getMeeting(meetingId);
-  if (!meeting || meeting.status === 'completed' || meeting.status === 'archived') return null;
+  // Pre-check (read-only) so we don't kill dispatches for a meeting that's
+  // already terminal. The authoritative status check still runs INSIDE the
+  // lock below.
+  const existing = getMeeting(meetingId);
+  if (!existing || existing.status === 'completed' || existing.status === 'archived') return null;
+
+  // CRITICAL: kill BEFORE acquiring the meeting lock. _killMeetingDispatches
+  // takes the dispatch.json lock and shells out to kill processes — never
+  // run that under the meeting lock (per CLAUDE.md, lock callbacks must
+  // stay fast and never spawn / kill / await).
   _killMeetingDispatches(meetingId);
-  if (meeting.status === 'investigating') { meeting.status = 'debating'; meeting.round = 2; }
-  else if (meeting.status === 'debating') { meeting.status = 'concluding'; meeting.round = 3; }
-  else if (meeting.status === 'concluding') { meeting.status = 'completed'; meeting.completedAt = ts(); }
-  else return meeting; // no change
-  meeting.roundStartedAt = ts();
-  saveMeeting(meeting);
-  return meeting;
+
+  return mutateMeeting(meetingId, (meeting) => {
+    if (!meeting || meeting.status === 'completed' || meeting.status === 'archived') return null;
+    if (meeting.status === 'investigating') { meeting.status = 'debating'; meeting.round = 2; }
+    else if (meeting.status === 'debating') { meeting.status = 'concluding'; meeting.round = 3; }
+    else if (meeting.status === 'concluding') { meeting.status = 'completed'; meeting.completedAt = ts(); }
+    else return meeting; // unknown active status — no state change, but report current
+    meeting.roundStartedAt = ts();
+    return meeting;
+  });
 }
 
 function endMeeting(meetingId) {
-  const meeting = getMeeting(meetingId);
-  if (!meeting) return null;
+  // See advanceMeetingRound — kill happens BEFORE the meeting lock so dispatch
+  // teardown / process kills never run inside our lock callback.
+  const existing = getMeeting(meetingId);
+  if (!existing) return null;
   _killMeetingDispatches(meetingId);
-  meeting.status = 'completed';
-  meeting.completedAt = ts();
-  saveMeeting(meeting);
-  return meeting;
+
+  return mutateMeeting(meetingId, (meeting) => {
+    if (!meeting) return null;
+    meeting.status = 'completed';
+    meeting.completedAt = ts();
+    return meeting;
+  });
 }
 
 function archiveMeeting(id) {
-  const meeting = getMeeting(id);
-  if (!meeting) return null;
-  meeting.status = 'archived';
-  meeting.archivedAt = ts();
-  saveMeeting(meeting);
-  return meeting;
+  return mutateMeeting(id, (meeting) => {
+    if (!meeting) return null;
+    meeting.status = 'archived';
+    meeting.archivedAt = ts();
+    return meeting;
+  });
 }
 
 function unarchiveMeeting(id) {
-  const meeting = getMeeting(id);
-  if (!meeting || meeting.status !== 'archived') return null;
-  meeting.status = 'completed';
-  delete meeting.archivedAt;
-  saveMeeting(meeting);
-  return meeting;
+  return mutateMeeting(id, (meeting) => {
+    if (!meeting || meeting.status !== 'archived') return null;
+    meeting.status = 'completed';
+    delete meeting.archivedAt;
+    return meeting;
+  });
 }
 
 function deleteMeeting(id) {
@@ -717,6 +787,9 @@ function deleteMeeting(id) {
   const filePath = path.join(MEETINGS_DIR, id + '.json');
   if (!fs.existsSync(filePath)) return false;
   fs.unlinkSync(filePath);
+  // mutateMeeting writes a .backup sidecar; safeJson auto-restores from it
+  // when the primary is missing, so deletion must also drop the backup.
+  try { fs.unlinkSync(filePath + '.backup'); } catch { /* sidecar may not exist */ }
   return true;
 }
 
@@ -733,68 +806,86 @@ function checkMeetingTimeouts(config) {
   const hardTimeout = (config.engine || {}).meetingRoundHardTimeout
     || ENGINE_DEFAULTS.meetingRoundHardTimeout;
 
-  for (const meeting of meetings) {
-    if (isTerminalMeetingStatus(meeting.status)) continue;
-    if (!ACTIVE_MEETING_STATUSES.has(meeting.status)) continue;
-    if (!meeting.roundStartedAt) continue;
+  for (const snapshot of meetings) {
+    if (isTerminalMeetingStatus(snapshot.status)) continue;
+    if (!ACTIVE_MEETING_STATUSES.has(snapshot.status)) continue;
+    if (!snapshot.roundStartedAt) continue;
 
-    const roundStartedMs = new Date(meeting.roundStartedAt).getTime();
+    const roundStartedMs = new Date(snapshot.roundStartedAt).getTime();
     if (!Number.isFinite(roundStartedMs)) continue;
     const elapsed = Date.now() - roundStartedMs;
     if (elapsed < timeout) continue;
 
-    const respondedCount = meeting.status === 'investigating'
-      ? Object.keys(meeting.findings || {}).length
-      : meeting.status === 'debating'
-        ? Object.keys(meeting.debate || {}).length
-        : 0;
-    const totalCount = meeting.participants.length;
-
-    const roundName = meeting.status === 'investigating'
-      ? 'investigate'
-      : meeting.status === 'debating'
-        ? 'debate'
-        : 'conclude';
-
-    if (roundName !== 'conclude') {
-      if (allParticipantsFinishedRound(meeting, roundName, meeting.round)) {
-        log('warn', `Meeting ${meeting.id}: round ${meeting.round} timed out after ${Math.round(elapsed / 60000)}min but all participants are terminal — advancing`);
-        meeting.transcript.push({ round: meeting.round, agent: 'system', type: 'timeout', content: `Round ${meeting.round} timed out after all participants finished`, at: ts() });
-        advanceMeetingIfRoundComplete(meeting, roundName, meeting.id, config);
-        saveMeeting(meeting);
-      } else if (elapsed >= hardTimeout) {
-        const failures = getRoundFailures(meeting, roundName, meeting.round, true);
-        const stalled = (meeting.participants || []).filter(p => !hasRoundTerminalOutcome(meeting, roundName, p, meeting.round));
-        const reason = `Hard meeting timeout after ${Math.round(elapsed / 60000)}min — agent did not produce ${roundName} output`;
-        for (const agentId of stalled) {
-          failures[agentId] = { reason, content: '', submittedAt: ts() };
-          meeting.transcript.push({ round: meeting.round, agent: agentId, type: 'failure', content: reason, at: ts() });
+    // Re-evaluate the timeout transition under the file lock to avoid lost
+    // updates if an agent finalised mid-tick. Helpers (advanceMeetingIfRoundComplete
+    // etc.) operate on the locked-and-rehydrated meeting object.
+    mutateMeeting(snapshot.id, (meeting) => {
+      if (!meeting) return null;
+      if (isTerminalMeetingStatus(meeting.status)) return null;
+      if (!ACTIVE_MEETING_STATUSES.has(meeting.status)) return null;
+      // Use the latest roundStartedAt — the round may have advanced inside
+      // a concurrent collectMeetingFindings call between snapshot and lock.
+      const liveStartedMs = new Date(meeting.roundStartedAt || 0).getTime();
+      if (!Number.isFinite(liveStartedMs)) return null;
+      const liveElapsed = Date.now() - liveStartedMs;
+      if (liveElapsed < timeout) return null;
+
+      const respondedCount = meeting.status === 'investigating'
+        ? Object.keys(meeting.findings || {}).length
+        : meeting.status === 'debating'
+          ? Object.keys(meeting.debate || {}).length
+          : 0;
+      const totalCount = meeting.participants.length;
+
+      const roundName = meeting.status === 'investigating'
+        ? 'investigate'
+        : meeting.status === 'debating'
+          ? 'debate'
+          : 'conclude';
+
+      if (roundName !== 'conclude') {
+        if (allParticipantsFinishedRound(meeting, roundName, meeting.round)) {
+          log('warn', `Meeting ${meeting.id}: round ${meeting.round} timed out after ${Math.round(liveElapsed / 60000)}min but all participants are terminal — advancing`);
+          meeting.transcript.push({ round: meeting.round, agent: 'system', type: 'timeout', content: `Round ${meeting.round} timed out after all participants finished`, at: ts() });
+          advanceMeetingIfRoundComplete(meeting, roundName, meeting.id, config);
+          return meeting;
+        } else if (liveElapsed >= hardTimeout) {
+          const failures = getRoundFailures(meeting, roundName, meeting.round, true);
+          const stalled = (meeting.participants || []).filter(p => !hasRoundTerminalOutcome(meeting, roundName, p, meeting.round));
+          const reason = `Hard meeting timeout after ${Math.round(liveElapsed / 60000)}min — agent did not produce ${roundName} output`;
+          for (const agentId of stalled) {
+            failures[agentId] = { reason, content: '', submittedAt: ts() };
+            meeting.transcript.push({ round: meeting.round, agent: agentId, type: 'failure', content: reason, at: ts() });
+          }
+          log('warn', `Meeting ${meeting.id}: round ${meeting.round} hit hard timeout after ${Math.round(liveElapsed / 60000)}min — marking ${stalled.length}/${totalCount} non-responders as failed and advancing`);
+          meeting.transcript.push({ round: meeting.round, agent: 'system', type: 'timeout', content: `Round ${meeting.round} hard timeout — ${stalled.length} non-responder(s) marked failed`, at: ts() });
+          advanceMeetingIfRoundComplete(meeting, roundName, meeting.id, config);
+          return meeting;
+        } else {
+          log('warn', `Meeting ${meeting.id}: round ${meeting.round} timed out after ${Math.round(liveElapsed / 60000)}min — waiting for all participants to finish (${respondedCount}/${totalCount} succeeded)`);
+          return null; // observational only — no state change
+        }
+      } else if (meeting.status === 'concluding') {
+        if (liveElapsed >= hardTimeout) {
+          const reason = `Hard meeting timeout after ${Math.round(liveElapsed / 60000)}min — conclusion agent did not produce output`;
+          const failures = getRoundFailures(meeting, 'conclude', meeting.round, true);
+          const conclusionAgent = (meeting.participants || []).find(p => !hasRoundTerminalOutcome(meeting, 'conclude', p, meeting.round)) || meeting.participants?.[0] || 'system';
+          failures[conclusionAgent] = { reason, content: '', submittedAt: ts() };
+          meeting.transcript.push({ round: meeting.round, agent: conclusionAgent, type: 'failure', content: reason, at: ts() });
+          log('warn', `Meeting ${meeting.id}: conclusion round hit hard timeout after ${Math.round(liveElapsed / 60000)}min — synthesising fallback conclusion`);
+          advanceMeetingIfRoundComplete(meeting, 'conclude', meeting.id, config);
+          return meeting;
+        } else {
+          log('warn', `Meeting ${meeting.id}: conclusion round timed out after ${Math.round(liveElapsed / 60000)}min — waiting for the conclusion agent to finish`);
+          return null;
         }
-        log('warn', `Meeting ${meeting.id}: round ${meeting.round} hit hard timeout after ${Math.round(elapsed / 60000)}min — marking ${stalled.length}/${totalCount} non-responders as failed and advancing`);
-        meeting.transcript.push({ round: meeting.round, agent: 'system', type: 'timeout', content: `Round ${meeting.round} hard timeout — ${stalled.length} non-responder(s) marked failed`, at: ts() });
-        advanceMeetingIfRoundComplete(meeting, roundName, meeting.id, config);
-        saveMeeting(meeting);
-      } else {
-        log('warn', `Meeting ${meeting.id}: round ${meeting.round} timed out after ${Math.round(elapsed / 60000)}min — waiting for all participants to finish (${respondedCount}/${totalCount} succeeded)`);
-      }
-    } else if (meeting.status === 'concluding') {
-      if (elapsed >= hardTimeout) {
-        const reason = `Hard meeting timeout after ${Math.round(elapsed / 60000)}min — conclusion agent did not produce output`;
-        const failures = getRoundFailures(meeting, 'conclude', meeting.round, true);
-        const conclusionAgent = (meeting.participants || []).find(p => !hasRoundTerminalOutcome(meeting, 'conclude', p, meeting.round)) || meeting.participants?.[0] || 'system';
-        failures[conclusionAgent] = { reason, content: '', submittedAt: ts() };
-        meeting.transcript.push({ round: meeting.round, agent: conclusionAgent, type: 'failure', content: reason, at: ts() });
-        log('warn', `Meeting ${meeting.id}: conclusion round hit hard timeout after ${Math.round(elapsed / 60000)}min — synthesising fallback conclusion`);
-        advanceMeetingIfRoundComplete(meeting, 'conclude', meeting.id, config);
-        saveMeeting(meeting);
-      } else {
-        log('warn', `Meeting ${meeting.id}: conclusion round timed out after ${Math.round(elapsed / 60000)}min — waiting for the conclusion agent to finish`);
       }
-    }
+      return null;
+    });
   }
 }
 module.exports = {
-  MEETINGS_DIR, getMeetings, getMeeting, saveMeeting, createMeeting,
+  MEETINGS_DIR, getMeetings, getMeeting, saveMeeting, mutateMeeting, createMeeting,
   discoverMeetingWork, collectMeetingFindings, checkMeetingTimeouts,
   addMeetingNote, advanceMeetingRound, endMeeting, archiveMeeting, unarchiveMeeting, deleteMeeting,
   EMPTY_OUTPUT_PATTERNS,

package/engine/queries.js

@@ -626,30 +626,32 @@ function getPullRequests(config) {
   const projectByName = new Map(projects.map(p => [p.name, p]));
   const allPrs = [];
   const seenIds = new Set();
-  // Single pass over projects/* — configured projects use their full config
-  // (prUrlBase fill-in, _project name); unconfigured subdirs are tagged _ghost
-  // so engine code can filter them out. Mirrors what shared.getPrLinks scans,
-  // so PRD links and PR records stay in sync after a project is removed.
+  // Single pass over projects/* intersected with the configured project list.
+  // Filesystem dirs not in CONFIG.projects (e.g. a leftover .minions/projects/
+  // <removedName>/ recreated by a stale code path between archive and reload)
+  // are skipped so removed projects can't resurrect themselves through the
+  // status payload. Hidden dirs (.archived sidecar) are also skipped defensively
+  // — they live as siblings under projects/ and would otherwise be enumerated.
   let projectDirs = [];
   try {
     projectDirs = fs.readdirSync(path.join(MINIONS_DIR, 'projects'), { withFileTypes: true })
-      .filter(d => d.isDirectory()).map(d => d.name);
+      .filter(d => d.isDirectory() && !d.name.startsWith('.')).map(d => d.name);
   } catch { /* projects dir missing */ }
   for (const dirName of projectDirs) {
-    const project = projectByName.get(dirName) || null;
-    const prPath = project ? projectPrPath(project) : path.join(MINIONS_DIR, 'projects', dirName, 'pull-requests.json');
+    const project = projectByName.get(dirName);
+    if (!project) continue; // unconfigured/removed — don't surface
+    const prPath = projectPrPath(project);
     const prs = readJsonNoRestore(prPath);
     if (!Array.isArray(prs)) continue;
     shared.normalizePrRecords(prs, project);
-    const base = project?.prUrlBase || '';
+    const base = project.prUrlBase || '';
     for (const pr of prs) {
       if (!pr?.id || seenIds.has(pr.id)) continue;
-      if (project && !pr.url && base) {
+      if (!pr.url && base) {
         const prNumber = shared.getPrNumber(pr);
         if (prNumber != null) pr.url = base + prNumber;
       }
-      pr._project = project ? (project.name || 'Project') : dirName;
-      if (!project) pr._ghost = true;
+      pr._project = project.name || 'Project';
       allPrs.push(pr);
       seenIds.add(pr.id);
     }

package/engine/scheduler.js

@@ -51,26 +51,51 @@ function resolveScheduleTemplateVars(str) {
 // Parse a single cron field into a matcher function.
 // field: e.g., "*", "5", "1,3,5", "*/15"
 // min/max: valid range (0-59 for minute, 0-23 for hour, 0-6 for dow)
+//
+// Bounds policy (P-h4cron-2ab8): out-of-range fields produce a matcher that
+// never fires (`() => false`), rather than null. This keeps the function's
+// contract (always returns a function) and matches existing behavior for
+// other invalid forms (`*/0`, `*/abc`, unparseable syntax). parseCronExpr
+// still returns its wrapper object — but its `.matches()` returns false for
+// every Date when any field is out of range, so the schedule never fires.
+// This catches typos like minute=99, hour=24, dow=9 that today are accepted
+// as exact-value matchers and silently never trigger.
 function parseCronField(field, min, max) {
   field = field.trim();
   if (field === '*') return () => true;
 
-  // Step: */N
+  const hasMin = typeof min === 'number';
+  const hasMax = typeof max === 'number';
+
+  // Step: */N — step must be > 0 AND not exceed the field's max.
+  // A step larger than max either matches only val=0 (e.g., */60 for minute)
+  // or nothing meaningful — treat as never-fires for predictability.
   if (field.startsWith('*/')) {
     const step = parseInt(field.slice(2), 10);
     if (isNaN(step) || step <= 0) return () => false;
+    if (hasMax && step > max) return () => false;
     return (val) => val % step === 0;
   }
 
-  // List: N,M,O
+  // List: N,M,O — drop NaN entries AND entries outside [min, max] before
+  // building the Set. A list with no surviving entries falls through to the
+  // empty-Set matcher, which never matches anything.
   if (field.includes(',')) {
-    const values = new Set(field.split(',').map(v => parseInt(v.trim(), 10)).filter(v => !isNaN(v)));
+    const values = new Set(
+      field
+        .split(',')
+        .map(v => parseInt(v.trim(), 10))
+        .filter(v => !isNaN(v) && (!hasMin || v >= min) && (!hasMax || v <= max))
+    );
     return (val) => values.has(val);
   }
 
-  // Single value: N
+  // Single value: N — out-of-range exact values never fire.
   const exact = parseInt(field, 10);
-  if (!isNaN(exact)) return (val) => val === exact;
+  if (!isNaN(exact)) {
+    if ((hasMin && exact < min) || (hasMax && exact > max)) return () => false;
+    return (val) => val === exact;
+  }
 
   return () => false;
 }

package/engine/shared.js

@@ -180,33 +180,52 @@ function safeReadDir(dir) {
 }
 
 function safeJson(p) {
+  // Split the read from the parse so we can distinguish "file missing" (normal
+  // pre-create state — silent) from "file present but corrupt JSON" (real
+  // integrity failure — must log). Without this split a `JSON.parse(read)` in
+  // a single try/catch silently hides corruption (P-h3arch-8c19).
+  let primaryRaw = null;
+  let primaryRead = false;
   try {
-    return JSON.parse(fs.readFileSync(p, 'utf8'));
+    primaryRaw = fs.readFileSync(p, 'utf8');
+    primaryRead = true;
   } catch {
-    // Primary file missing or corrupted — try restoring from .backup sidecar
-    const backupPath = p + '.backup';
+    // ENOENT / EACCES / etc — fall through to backup attempt without logging.
+  }
+  if (primaryRead) {
     try {
-      const backupData = JSON.parse(fs.readFileSync(backupPath, 'utf8'));
-      // Backup is valid — restore it to the primary file (atomic via safeWrite)
-      console.log(`[safeJson] restored ${path.basename(p)} from .backup sidecar`);
-      try {
-        safeWrite(p, backupData);
-        // Verify the restored file matches expected content
-        const verifyData = JSON.parse(fs.readFileSync(p, 'utf8'));
-        if (JSON.stringify(verifyData) !== JSON.stringify(backupData)) {
-          console.error(`[safeJson] CRITICAL: backup restore verification failed for ${p} — written data does not match backup`);
-        }
-      } catch (restoreErr) {
-        // Restore-to-primary is best-effort — backupData is already parsed and valid.
-        // Don't throw: disk-full / permission errors should not discard valid data.
-        console.error(`[safeJson] restore write failed for ${p}: ${restoreErr.message}`);
+      return JSON.parse(primaryRaw);
+    } catch (parseErr) {
+      // File existed but JSON was unparseable — surface so silent corruption
+      // doesn't accumulate. Callers (incl. safeJsonArr / safeJsonObj wrappers)
+      // rely on this log to satisfy the "typed default + logged parse failure"
+      // contract documented in CLAUDE.md.
+      console.error(`[safeJson] parse failure for ${path.basename(p)}: ${parseErr.message}`);
+    }
+  }
+  // Primary missing or corrupted — try restoring from .backup sidecar.
+  const backupPath = p + '.backup';
+  try {
+    const backupData = JSON.parse(fs.readFileSync(backupPath, 'utf8'));
+    // Backup is valid — restore it to the primary file (atomic via safeWrite)
+    console.log(`[safeJson] restored ${path.basename(p)} from .backup sidecar`);
+    try {
+      safeWrite(p, backupData);
+      // Verify the restored file matches expected content
+      const verifyData = JSON.parse(fs.readFileSync(p, 'utf8'));
+      if (JSON.stringify(verifyData) !== JSON.stringify(backupData)) {
+        console.error(`[safeJson] CRITICAL: backup restore verification failed for ${p} — written data does not match backup`);
       }
-      return backupData;
-    } catch (outerErr) {
-      // Let CRITICAL errors propagate — callers must know about data integrity failures
-      if (outerErr.message && outerErr.message.includes('CRITICAL')) throw outerErr;
-      return null;
+    } catch (restoreErr) {
+      // Restore-to-primary is best-effort — backupData is already parsed and valid.
+      // Don't throw: disk-full / permission errors should not discard valid data.
+      console.error(`[safeJson] restore write failed for ${p}: ${restoreErr.message}`);
     }
+    return backupData;
+  } catch (outerErr) {
+    // Let CRITICAL errors propagate — callers must know about data integrity failures
+    if (outerErr.message && outerErr.message.includes('CRITICAL')) throw outerErr;
+    return null;
   }
 }
 
@@ -1480,9 +1499,22 @@ function projectRoot(project) {
 
 // All project state files live centrally in .minions/projects/{name}/
 // No state files in project repos — avoids worktree/git interference.
+//
+// projectStateDir is path-only (no fs side effects) — safe to call with stale
+// project references after `removeProject` archived the data dir. Write paths
+// (safeWrite, withFileLock, mutateJsonFileLocked) already mkdir the parent dir
+// at write time, so the dir is created lazily only when something is actually
+// written. Use projectStateDirEnsure() when a caller specifically needs the
+// directory to exist before doing its own fs ops.
 function projectStateDir(project) {
   const name = project.name || path.basename(project.localPath);
-  const dir = path.join(MINIONS_DIR, 'projects', name);
+  return path.join(MINIONS_DIR, 'projects', name);
+}
+
+// Same as projectStateDir() but mkdirs the directory. Use when the caller does
+// raw fs ops (writeFileSync etc.) that don't already create the parent dir.
+function projectStateDirEnsure(project) {
+  const dir = projectStateDir(project);
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   return dir;
 }
@@ -2841,6 +2873,7 @@ module.exports = {
   getProjects,
   projectRoot,
   projectStateDir,
+  projectStateDirEnsure,
   projectWorkItemsPath,
   projectPrPath,
   resolveProjectForPrPath, // exported for testing

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yemi33/minions",
-  "version": "0.1.1748",
+  "version": "0.1.1750",
   "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"