@yemi33/minions 0.1.2200 → 0.1.2201

package/dashboard.js

@@ -1579,10 +1579,11 @@ function _archivePrdPostProcess({ planFile, archivePath, planPath, plansDir, _mu
     try {
       const mdPath = path.join(plansDir, plan.source_plan);
       if (fs.existsSync(mdPath)) {
-        const planArchive = path.join(plansDir, 'archive');
-        if (!fs.existsSync(planArchive)) fs.mkdirSync(planArchive, { recursive: true });
-        fs.renameSync(mdPath, path.join(planArchive, plan.source_plan));
-        archivedSource = plan.source_plan;
+        // DATA-LOSS GUARD: moveFileNoClobber dedupes + retries so archiving a
+        // source plan can't overwrite a previously-archived plan of the same
+        // basename (and survives transient Windows file locks).
+        const mdDest = shared.moveFileNoClobber(mdPath, path.join(plansDir, 'archive'), plan.source_plan);
+        archivedSource = path.basename(mdDest);
       }
     } catch (e) {
       const warning = `Archive could not move source plan ${plan.source_plan}: ${e.message}`;
@@ -7033,7 +7034,10 @@ const server = http.createServer(async (req, res) => {
       const file = body.file || 'notes.md';
       // Only allow saving notes.md (prevent arbitrary file writes)
       if (file !== 'notes.md') return jsonReply(res, 400, { error: 'only notes.md can be edited' });
-      safeWrite(path.join(MINIONS_DIR, file), body.content);
+      // DATA-LOSS GUARD: write under the same lock the engine consolidation
+      // path holds (withFileLock(notes.md.lock)) so a concurrent consolidation
+      // flush in the engine process can't lose-update this save (and vice-versa).
+      shared.mutateTextFileLocked(path.join(MINIONS_DIR, file), () => body.content);
       return jsonReply(res, 200, { ok: true });
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
@@ -7774,9 +7778,12 @@ const server = http.createServer(async (req, res) => {
       if (!fs.existsSync(planPath)) return jsonReply(res, 404, { error: 'plan not found' });
 
       const archiveDir = isPrd ? path.join(PRD_DIR, 'archive') : path.join(PLANS_DIR, 'archive');
-      if (!fs.existsSync(archiveDir)) fs.mkdirSync(archiveDir, { recursive: true });
-      const archivePath = path.join(archiveDir, body.file);
-      fs.renameSync(planPath, archivePath);
+      // DATA-LOSS GUARD: moveFileNoClobber dedupes the destination so a same-
+      // basename collision (e.g. re-archiving a project's canonical
+      // <project>-<date> name, or the W-mq8qdai6 live↔archive collision class)
+      // can't silently destroy a previously-archived plan/PRD + its completed
+      // work-item history. Bumps to -2/-3 instead of overwriting.
+      const archivePath = shared.moveFileNoClobber(planPath, archiveDir, body.file);
 
       let archivedSource = null;
       let plan = {};
@@ -7839,9 +7846,11 @@ const server = http.createServer(async (req, res) => {
             console.warn(warning);
             continue;
           }
-          const prdArchivePath = path.join(prdArchiveDir, prdFile);
+          let prdArchivePath;
           try {
-            fs.renameSync(prdLivePath, prdArchivePath);
+            // DATA-LOSS GUARD: dedupe + retry so the cascade can't clobber a
+            // previously-archived PRD of the same basename.
+            prdArchivePath = shared.moveFileNoClobber(prdLivePath, prdArchiveDir, prdFile);
           } catch (e) {
             const warning = `Archive could not move PRD ${prdFile}: ${e.message}`;
             archiveWarnings.push(warning);
@@ -7906,18 +7915,21 @@ const server = http.createServer(async (req, res) => {
       const targetDir = isJson ? PRD_DIR : PLANS_DIR;
       const archivePath = path.join(targetDir, 'archive', body.file);
       if (!fs.existsSync(archivePath)) return jsonReply(res, 404, { error: 'File not found in archive' });
-      fs.renameSync(archivePath, path.join(targetDir, body.file));
+      // DATA-LOSS GUARD: restoring from archive must not clobber a LIVE plan/PRD
+      // of the same basename (renameSync overwrites). moveFileNoClobber bumps
+      // the restored name instead so the existing live file survives.
+      const liveDest = shared.moveFileNoClobber(archivePath, targetDir, body.file);
 
       // Also unarchive linked source plan
       let unarchivedSource = null;
       if (isJson) {
         try {
-          const prd = safeJson(path.join(targetDir, body.file));
+          const prd = safeJson(liveDest);
           if (prd?.source_plan) {
             const mdArchivePath = path.join(PLANS_DIR, 'archive', prd.source_plan);
             if (fs.existsSync(mdArchivePath)) {
-              fs.renameSync(mdArchivePath, path.join(PLANS_DIR, prd.source_plan));
-              unarchivedSource = prd.source_plan;
+              const liveMdDest = shared.moveFileNoClobber(mdArchivePath, PLANS_DIR, prd.source_plan);
+              unarchivedSource = path.basename(liveMdDest);
             }
           }
         } catch { /* optional */ }
@@ -7925,7 +7937,13 @@ const server = http.createServer(async (req, res) => {
 
       invalidateStatusCache();
       invalidatePlansCache();
-      return jsonReply(res, 200, { ok: true, unarchivedSource });
+      // `restoredAs` reflects the actual restored basename: moveFileNoClobber
+      // bumps to <name>-2 when a live file of the same name already exists, so
+      // the client isn't misled into expecting body.file when it differs.
+      const restoredAs = path.basename(liveDest);
+      const payload = { ok: true, unarchivedSource };
+      if (restoredAs !== body.file) payload.restoredAs = restoredAs;
+      return jsonReply(res, 200, payload);
     } catch (e) { return jsonReply(res, 400, { error: e.message }); }
   }
 
@@ -8384,19 +8402,25 @@ What would you like to discuss or change? When you're happy, say "approve" and I
 
       // Append to notes.md as a new team note
       const notesPath = path.join(MINIONS_DIR, 'notes.md');
-      let notes = safeRead(notesPath) || '# Minions Notes\n\n## Active Notes\n';
       const today = new Date().toISOString().slice(0, 10);
       const entry = `\n### ${today}: ${title}\n**By:** Persisted from inbox (${name})\n**What:** ${content.slice(0, 500)}\n\n---\n`;
-
-      const marker = '## Active Notes';
-      const idx = notes.indexOf(marker);
-      if (idx !== -1) {
-        const insertAt = idx + marker.length;
-        notes = notes.slice(0, insertAt) + '\n' + entry + notes.slice(insertAt);
-      } else {
-        notes += '\n' + entry;
-      }
-      safeWrite(notesPath, notes);
+      // DATA-LOSS GUARD: read-modify-write notes.md under the same lock the
+      // engine consolidation path holds. The previous unlocked read→splice→write
+      // could lose-update against a concurrent consolidation flush (the engine
+      // and dashboard are separate processes), silently dropping one note.
+      const NOTES_DEFAULT = '# Minions Notes\n\n## Active Notes\n';
+      shared.mutateTextFileLocked(notesPath, (prev) => {
+        let notes = prev || NOTES_DEFAULT;
+        const marker = '## Active Notes';
+        const idx = notes.indexOf(marker);
+        if (idx !== -1) {
+          const insertAt = idx + marker.length;
+          notes = notes.slice(0, insertAt) + '\n' + entry + notes.slice(insertAt);
+        } else {
+          notes += '\n' + entry;
+        }
+        return notes;
+      }, { defaultValue: NOTES_DEFAULT });
 
       // W-mq1j85cj00055a8f — rewrite WI references that pointed at the
       // now-archived inbox note to the persisted destination (notes.md).

package/engine/cli.js

@@ -1211,6 +1211,8 @@ const commands = {
 
     process.on('SIGTERM', () => gracefulShutdown('SIGTERM'));
     process.on('SIGINT', () => gracefulShutdown('SIGINT'));
+    // WAL checkpoint-on-exit is registered by engine/db getDb() itself (covers
+    // the engine daemon, dashboard, and CLI uniformly) — no hook needed here.
 
     // Crash handlers — log the error and exit cleanly so the process is detectable as crashed
     process.on('unhandledRejection', (reason) => {

package/engine/db/index.js

@@ -20,6 +20,20 @@ const fs = require('fs');
 let _db = null;
 let _dbPath = null;
 let _dbInitError = null;
+let _exitCheckpointRegistered = false;
+
+// DATA-LOSS GUARD: register a one-time process-exit hook that checkpoints +
+// closes the DB. Registered by getDb() on first successful open so EVERY DB
+// opener (engine daemon, dashboard, CLI) gets WAL durability on exit — not just
+// the engine CLI path. Idempotent: closeDb()'s `if (_db)` guard makes a later
+// graceful-shutdown close a no-op. Synchronous-only work (node:sqlite is sync),
+// which is all `process.on('exit')` permits.
+function _registerExitCheckpoint() {
+  if (_exitCheckpointRegistered) return;
+  _exitCheckpointRegistered = true;
+  try { process.on('exit', () => { try { closeDb(); } catch { /* best-effort */ } }); }
+  catch { /* env without process events */ }
+}
 
 function _resolveDbPath() {
   // Lazy-require shared/queries so this module can be safely required
@@ -129,6 +143,7 @@ function getDb() {
     if (lastErr) throw lastErr;
     const { runMigrations } = require('./migrate');
     runMigrations(_db);
+    _registerExitCheckpoint();
     return _db;
   } catch (e) {
     const nodeMajor = parseInt(String(process.versions.node).split('.')[0], 10);
@@ -142,7 +157,16 @@ function getDb() {
 
 // Force-close — used by tests + graceful shutdown. Safe to call when not open.
 function closeDb() {
-  if (_db) { try { _db.close(); } catch { /* already closed */ } _db = null; }
+  if (_db) {
+    // DATA-LOSS GUARD: under journal_mode=WAL + synchronous=NORMAL, committed
+    // transactions can live only in the -wal file until a checkpoint folds them
+    // into the main DB. Checkpoint on graceful close so a host crash / power loss
+    // after shutdown can't drop the most recent commits (and so the WAL doesn't
+    // grow unbounded). Best-effort — a failed checkpoint must not block close.
+    try { _db.exec('PRAGMA wal_checkpoint(TRUNCATE)'); } catch { /* best-effort */ }
+    try { _db.close(); } catch { /* already closed */ }
+    _db = null;
+  }
   _dbPath = null;
   _dbInitError = null;
 }

package/engine/lifecycle.js

@@ -432,8 +432,11 @@ function archivePlan(planFile, plan, projects, config) {
   if (!fs.existsSync(prdArchiveDir)) fs.mkdirSync(prdArchiveDir, { recursive: true });
   try {
     if (fs.existsSync(planPath)) {
-      fs.renameSync(planPath, path.join(prdArchiveDir, planFile));
-      log('info', `Archived completed PRD: prd/archive/${planFile}`);
+      // DATA-LOSS GUARD: moveFileNoClobber dedupes + retries so a same-basename
+      // collision can't silently overwrite a previously-archived PRD (+ its
+      // completed work-item history). renameSync clobbers on Windows.
+      const prdDest = shared.moveFileNoClobber(planPath, prdArchiveDir, planFile);
+      log('info', `Archived completed PRD: prd/archive/${path.basename(prdDest)}`);
     }
     // Remove .backup sidecar — if left behind, safeJson() would restore the pre-completion
     // snapshot (status: approved, no _completionNotified) on engine restart, re-triggering
@@ -457,8 +460,8 @@ function archivePlan(planFile, plan, projects, config) {
     const sourcePlanName = plan.source_plan || planFile.replace(/\.json$/, '.md');
     if (sourcePlanName && fs.existsSync(path.join(PLANS_DIR, sourcePlanName))) {
       try {
-        fs.renameSync(path.join(PLANS_DIR, sourcePlanName), path.join(planArchiveDir, sourcePlanName));
-        log('info', `Archived source plan: plans/archive/${sourcePlanName}`);
+        const mdDest = shared.moveFileNoClobber(path.join(PLANS_DIR, sourcePlanName), planArchiveDir, sourcePlanName);
+        log('info', `Archived source plan: plans/archive/${path.basename(mdDest)}`);
       } catch (err) { log('warn', `Failed to archive plan ${sourcePlanName}: ${err.message}`); }
     } else {
       // Fallback: match by content
@@ -467,8 +470,8 @@ function archivePlan(planFile, plan, projects, config) {
         const mdContent = shared.safeRead(path.join(PLANS_DIR, md)) || '';
         if (mdContent.includes(projectName) || mdContent.includes(plan.plan_summary?.slice(0, 40) || '___nomatch___')) {
           try {
-            fs.renameSync(path.join(PLANS_DIR, md), path.join(planArchiveDir, md));
-            log('info', `Archived source plan: plans/archive/${md}`);
+            const mdDest = shared.moveFileNoClobber(path.join(PLANS_DIR, md), planArchiveDir, md);
+            log('info', `Archived source plan: plans/archive/${path.basename(mdDest)}`);
           } catch (err) { log('warn', `Failed to archive plan ${md}: ${err.message}`); }
           break;
         }

package/engine/playbook.js

@@ -298,6 +298,13 @@ const PLAYBOOK_OPTIONAL_VARS = new Set([
   'existing_prd_json',    // only set when re-running plan-to-prd over an existing PRD
   'branch_strategy_hint', // only set for shared-branch plans
   'review_note',          // only set on fix/review tasks tied to a comment
+  // W-mqh08n0u002ha5c4 — shared-branch carve-out flag. Set to '1' by
+  // renderProjectWorkItemPromptForAgent only when the dispatched item is on a
+  // shared-branch plan; '' otherwise. Drives the {{#shared_branch}} /
+  // {{^shared_branch}} blocks in docs.md / test.md that suppress premature PR
+  // creation. Optional because every other playbook ignores it and the
+  // default state is the empty string (renders the non-shared branch).
+  'shared_branch',
   // P-4d6e2af3 — comma-separated list of target projects for cross-repo
   // plans. Only set in engine.js's WORK_TYPE.PLAN branch when the WI carries
   // item._targetProjects (≥2 entries from dashboard.js#buildPlanWorkItem).

package/engine/projects.js

@@ -261,8 +261,10 @@ function removeProject(target, options = {}) {
           const filenameMatch = f.toLowerCase().includes(lowerName);
           const content = filenameMatch ? '' : fs.readFileSync(fp, 'utf8');
           if (!filenameMatch && !projectLineRe.test(content)) continue;
-          fs.renameSync(fp, path.join(plansArchive, f));
-          summary.archivedPlans.push('plans/' + f);
+          // DATA-LOSS GUARD: dedupe + retry so re-removing a project (same plan
+          // basename) can't overwrite a previously-archived plan.
+          const planDest = shared.moveFileNoClobber(fp, plansArchive, f);
+          summary.archivedPlans.push('plans/' + path.basename(planDest));
         } catch { /* skip unreadable plan */ }
       }
     }

package/engine/shared.js

@@ -1872,6 +1872,30 @@ function uniquePath(filePath) {
   return `${base}-${Date.now()}${ext}`;
 }
 
+/**
+ * Move a file into `destDir` WITHOUT ever overwriting an existing file there —
+ * the canonical archive/restore data-loss guard. `fs.renameSync` clobbers its
+ * destination (silently, on Windows especially), so archiving a plan/PRD whose
+ * basename already exists in the archive dir, or restoring over a live file of
+ * the same name, would destroy the existing file (+ its history). This dedupes
+ * the destination basename via `uniquePath` (-2/-3/...) and wraps the rename in
+ * `_retryFsOp` so a transient Windows EPERM/EBUSY (AV / indexer lock) doesn't
+ * fail the move. Creates `destDir` if missing. Returns the final destination
+ * path actually written (caller derives the basename for logs/records).
+ *
+ * @param {string} srcPath  - file to move (caller ensures it exists)
+ * @param {string} destDir  - directory to move it into
+ * @param {string} [destName=path.basename(srcPath)] - basename to use at dest
+ * @returns {string} absolute destination path the file now lives at
+ */
+function moveFileNoClobber(srcPath, destDir, destName) {
+  const name = destName || path.basename(srcPath);
+  if (!fs.existsSync(destDir)) fs.mkdirSync(destDir, { recursive: true });
+  const dest = uniquePath(path.join(destDir, name));
+  _retryFsOp(() => fs.renameSync(srcPath, dest), `move ${name} -> archive`);
+  return dest;
+}
+
 function truncateTextBytes(text, maxBytes, suffix = '') {
   const value = text == null ? '' : String(text);
   if (!maxBytes || maxBytes <= 0) return '';
@@ -8213,6 +8237,7 @@ module.exports = {
   mutatePullRequests,
   uid,
   uniquePath,
+  moveFileNoClobber,
   isPlainObject,
   truncateTextBytes,
   tailTextBytes,

package/engine/work-items-store.js

@@ -117,13 +117,12 @@ function _resyncScopeIfJsonDiverged(db, scope) {
   const lastHash = _lastMirrorHashByScope.get(scope);
   if (currentHash == null) return;
   if (lastHash != null && currentHash === lastHash) return;
-  if (lastHash == null) {
-    const sqlHas = db.prepare('SELECT 1 FROM work_items WHERE scope = ? LIMIT 1').get(scope);
-    if (sqlHas) {
-      _lastMirrorHashByScope.set(scope, currentHash);
-      return;
-    }
-  }
+  // First touch in this process (lastHash == null): if SQL already holds rows
+  // for the scope, SQL is the established source of truth (post-Phase-9.4) —
+  // adopt the current JSON hash and DO NOT hydrate. Hydrating here would let a
+  // crash-stale / .backup-restored / git-checked-out older JSON mirror DELETE +
+  // overwrite newer SQL. Only an empty-in-SQL scope (genuine first-install
+  // migration) falls through to hydrate-from-JSON, which is purely additive.
   if (lastHash == null) {
     const sqlHas = db.prepare('SELECT 1 FROM work_items WHERE scope = ? LIMIT 1').get(scope);
     if (sqlHas) {

package/engine.js

@@ -6773,6 +6773,17 @@ function renderProjectWorkItemPromptForAgent(item, workType, agentId, config, pr
     project_path: root,
     worktree_path: worktreePath,
     commit_message: item.commitMessage || `feat: ${item.title || item.id}`,
+    // W-mqh08n0u002ha5c4 — shared-branch carve-out flag. On a shared-branch
+    // plan (branch_strategy: shared-branch) NO PR is opened until all plan
+    // items complete — the engine/verify flow opens the single aggregate PR.
+    // implement items already route to implement-shared.md (which omits PR
+    // creation); this flag lets non-implement playbooks (docs.md, test.md)
+    // suppress their own premature PR-creation step the same way via
+    // {{#shared_branch}} / {{^shared_branch}} conditional blocks. Truthy only
+    // when the item is genuinely on a shared branch (mirrors selectPlaybook's
+    // implement→implement-shared gate at engine/playbook.js). Default '' for
+    // parallel/PR-targeted dispatches keeps existing per-type PR behavior.
+    shared_branch: (item.branchStrategy === 'shared-branch' && item.featureBranch) ? '1' : '',
     notes_content: '',
     pr_id: item.pr_id || item._pr || item.targetPr || item.sourcePr || item.pr || '',
     pr_number: item.prNumber || item.pr_number || '',

package/package.json

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

package/playbooks/docs.md

@@ -90,6 +90,20 @@ the engine handles cleanup automatically.
 Commit only the doc files (and any helper assets they reference). Do not bundle
 unrelated code changes into a docs PR.
 
+{{#shared_branch}}
+```bash
+git add <doc files>
+git commit -m "{{commit_message}}"
+git push origin {{branch_name}}
+```
+
+This is part of a **shared-branch plan** — other plan items share `{{branch_name}}`.
+Push your commit to the shared branch and STOP. Do **NOT** create a PR — the engine
+opens one aggregate PR automatically when all plan items complete. Opening a PR now
+would be premature (other items are still in flight) and the early branch would collect
+merge conflicts from concurrent sibling pushes.
+{{/shared_branch}}
+{{^shared_branch}}
 ```bash
 git add <doc files>
 git commit -m "{{commit_message}}"
@@ -99,6 +113,7 @@ git push -u origin {{branch_name}}
 Create the PR for docs tasks — docs go through the same review flow as code.
 Use the appropriate repo-host tooling for PR creation. For Azure DevOps, prefer the
 `az` CLI first and use the ADO MCP only as a fallback.
+{{/shared_branch}}
 
 ## Rules
 
@@ -109,9 +124,17 @@ Use the appropriate repo-host tooling for PR creation. For Azure DevOps, prefer
 
 ## When to Stop
 
+{{#shared_branch}}
+Your task is complete once the doc accurately reflects current code, any doc-validation
+tests pass, and your commit is pushed to the shared branch `{{branch_name}}`. Do NOT
+create a PR — the engine creates one when all plan items are done. Do not continue
+editing adjacent docs that weren't part of the task.
+{{/shared_branch}}
+{{^shared_branch}}
 Your task is complete once the doc accurately reflects current code, the PR is created
 with the changed doc files, and any doc-validation tests pass. Do not continue editing
 adjacent docs that weren't part of the task.
+{{/shared_branch}}
 
 ## Team Decisions
 {{notes_content}}

package/playbooks/shared-rules.md

@@ -232,6 +232,12 @@ gh pr review <number> --comment --body-file <verdict.md> --repo OWNER/REPO   # f
 
 The marker is an HTML comment on its own line — GitHub's renderer strips it before display, so reviewers see nothing. The body round-trips verbatim through the API so the engine can match it.
 
+**Brand link (MANDATORY).** Whenever the visible body of a PR comment or review names "Minions" — e.g. "Fixed by Minions", "Reviewed by Minions", "Minions rebased this branch" — render that word as a markdown hyperlink to the Minions site:
+```
+[Minions](https://icy-water-0224cc51e.2.azurestaticapps.net/minions)
+```
+So write `Fixed by [Minions](https://icy-water-0224cc51e.2.azurestaticapps.net/minions)`, not a bare `Fixed by Minions`. This applies to GitHub and ADO comments alike. Do **not** link occurrences inside the HTML marker line, code blocks, or file paths — only the human-readable prose mention. Link the first occurrence per comment; subsequent repeats in the same comment may stay plain.
+
 ## GitHub Tooling and Auth
 
 For GitHub repo operations, use GitHub MCP tools or the `gh` CLI. Prefer commands such as `gh pr create`, `gh pr view`, `gh pr comment`, `gh pr review --comment`, `gh issue view`, and `gh run view`. **For comment / review posts, always go through `minions pr comment` or include the marker template above.**

package/playbooks/test.md

@@ -31,7 +31,12 @@ Builds, tests, dependency installs, and server startups can be silent for severa
 
 Work from the current project checkout prepared by the engine. Follow the repo's own instructions (`CLAUDE.md`, README, package files, Makefiles, project scripts) and run the smallest sensible set of commands that proves the requested behavior.
 
+{{#shared_branch}}
+This task is part of a **shared-branch plan** — other plan items share `{{branch_name}}`. If the task asks you to add or modify files, commit those focused changes and push them to the shared branch (`git push origin {{branch_name}}`), then STOP. Do **NOT** create a PR — the engine opens one aggregate PR automatically when all plan items complete. Creating a PR now would be premature and the early branch would collect merge conflicts from concurrent sibling pushes. For pure build/run/verify tasks, do not push.
+{{/shared_branch}}
+{{^shared_branch}}
 If the task asks you to add or modify files, commit those focused changes, push the branch, and create a PR using the same conventions as implement tasks. For pure build/run/verify tasks, do not push or create a PR.
+{{/shared_branch}}
 
 If a build or test fails, report the error clearly instead of fixing it unless the task explicitly asks for a fix.