@yemi33/minions 0.1.2380 → 0.1.2382

package/dashboard.js

@@ -421,8 +421,14 @@ function mergeSettingsConfigUpdate(current, candidate, body, patch = {}) {
       // `candidate` in handleSettingsUpdate) is silently dropped on the way
       // through mergeSettingsConfigUpdate → mutateDashboardConfig and never
       // reaches disk — the endpoint would return 200 but persist nothing.
+      const modeWasRequested = Object.prototype.hasOwnProperty.call(update, 'checkoutMode')
+        || Object.prototype.hasOwnProperty.call(update, 'worktreeMode');
       if (Object.prototype.hasOwnProperty.call(candidateProject, 'checkoutMode')) {
         currentProject.checkoutMode = candidateProject.checkoutMode;
+      } else if (Object.prototype.hasOwnProperty.call(candidateProject, 'worktreeMode')) {
+        currentProject.checkoutMode = shared.resolveCheckoutMode(candidateProject);
+      } else if (!modeWasRequested && Object.prototype.hasOwnProperty.call(currentProject, 'worktreeMode')) {
+        currentProject.checkoutMode = shared.resolveCheckoutMode(currentProject);
       } else {
         delete currentProject.checkoutMode;
       }
@@ -832,7 +838,7 @@ async function copyWorkItemPrFields(item, input, pr = null, opts = {}) {
     if (structuredRef) {
       prRef = structuredRef; // explicit operator intent — trusted, no verification
     } else {
-      if (String(item?.type || '').toLowerCase() !== WORK_TYPE.FIX) return;
+      if (!shared.isFixLikeWorkType(String(item?.type || '').toLowerCase())) return;
       const looseRef = getWorkItemPrRef(input);
       if (!looseRef) return;
       // issue #246 — confirm the loose ref is a PR (not an issue) before stamping.
@@ -1649,13 +1655,23 @@ const PLANS_DIR = path.join(MINIONS_DIR, 'plans');
 // W-mpetru8a000s123a — /api/plans cache. Dashboard auto-polls every 4s; the
 // pre-cache cold path walked 4 directories (plans/, prd/, archive variants),
 // sync-stat'd every file, and parsed/regex-scanned each .md → 2-3s blocking.
-// 5s TTL means external .md edits surface within 5s. Mutation handlers must
-// call invalidatePlansCache() for immediate visibility.
+// 30s TTL keeps the full markdown/SQL rollup off the 4s browser poll cadence.
+// Mutation handlers call invalidatePlansCache() for immediate visibility;
+// out-of-process edits surface within 30s.
 let _plansCache = null;
 let _plansCacheTs = 0;
-const PLANS_CACHE_TTL_MS = 5000;
+const PLANS_CACHE_TTL_MS = 30000;
 function invalidatePlansCache() { _plansCache = null; _plansCacheTs = 0; }
 
+async function _mapInBatches(items, batchSize, mapper) {
+  const result = [];
+  for (let start = 0; start < items.length; start += batchSize) {
+    result.push(...await Promise.all(items.slice(start, start + batchSize).map(mapper)));
+    if (start + batchSize < items.length) await _yieldEventLoop();
+  }
+  return result;
+}
+
 function statePathExists(filePath) {
   return fs.existsSync(filePath);
 }
@@ -2538,26 +2554,7 @@ function _buildStatusSlowState() {
         ...status,
         mainBranch,
         branchMismatch,
-        // P-a3f9b209 / W-mqgzcrln002613b3 — surface the per-project dispatch
-        // mode so the Projects view can render a "Worktrees" vs "Live checkout"
-        // pill. resolveCheckoutMode honors the legacy worktreeMode field and
-        // defaults to 'worktree' when unset (matches engine spawn behavior).
-        checkoutMode: shared.resolveCheckoutMode(p),
-        // Surface the hybrid live-validation type (when configured) so the
-        // Projects view can render a distinct "Hybrid" pill: coding WIs author
-        // in isolated worktrees while only the named validation type runs
-        // in-place on the live checkout. Only meaningful when checkoutMode is
-        // 'live'; null otherwise (full-live or worktree projects).
-        liveValidationType: (shared.resolveCheckoutMode(p) === 'live' && p.liveValidation && p.liveValidation.type)
-          ? p.liveValidation.type
-          : null,
-        // W-mr2q361a00097e5c — surface liveValidation.autoDispatch alongside
-        // .type so the hybrid picker can preselect the "auto-validate"
-        // checkbox and the pill can visibly distinguish manual vs
-        // auto-validating hybrid projects. Only meaningful when checkoutMode
-        // is 'live'; false otherwise (matches the implicit today-default of
-        // autoDispatch being absent/false).
-        liveValidationAutoDispatch: !!(shared.resolveCheckoutMode(p) === 'live' && p.liveValidation && p.liveValidation.autoDispatch === true),
+        ..._projectCheckoutConfigView(p),
       };
     }),
     autoMode: {
@@ -2974,15 +2971,35 @@ async function _freshnessEntryMtimeMs(fp, depth) {
   return max;
 }
 
+const FRESHNESS_MTIME_CACHE_TTL_MS = 1000;
+const _freshnessMtimeCache = new Map();
+
 async function _maxInputMtimeMs(inputs) {
+  const key = inputs.map(fp => path.resolve(fp)).sort().join('\0');
+  const now = Date.now();
+  const cached = _freshnessMtimeCache.get(key);
+  if (cached && now - cached.createdAt < FRESHNESS_MTIME_CACHE_TTL_MS) {
+    return cached.promise;
+  }
   // Directory mtime only advances on add/remove, not in-place edits. Walk two
   // levels so prd/<plan>.json and agents/<id>/live-output.log both bust ETags.
   // Deeper steering edits still rely on add/remove cadence, matching the prior
   // bounded walk.
-  const mtimes = await Promise.all(
+  const promise = Promise.all(
     inputs.map(fp => _freshnessEntryMtimeMs(fp, 2)),
-  );
-  return Math.floor(mtimes.reduce((max, mtime) => Math.max(max, mtime), 0));
+  ).then(mtimes => Math.floor(mtimes.reduce((max, mtime) => Math.max(max, mtime), 0)));
+  _freshnessMtimeCache.set(key, { createdAt: now, promise });
+  if (_freshnessMtimeCache.size > 100) {
+    for (const [cacheKey, entry] of _freshnessMtimeCache) {
+      if (now - entry.createdAt >= FRESHNESS_MTIME_CACHE_TTL_MS) _freshnessMtimeCache.delete(cacheKey);
+    }
+  }
+  try {
+    return await promise;
+  } catch (err) {
+    if (_freshnessMtimeCache.get(key)?.promise === promise) _freshnessMtimeCache.delete(key);
+    throw err;
+  }
 }
 async function serveFreshJson(req, res, opts) {
   const inputs = Array.isArray(opts && opts.inputs) ? opts.inputs : [];
@@ -3174,7 +3191,20 @@ function handleStateRead(req, res) {
   res.setHeader('Content-Type', _stateReadContentType(path.extname(resolved)));
   try {
     const stream = fs.createReadStream(resolved);
+    // HANDLE-LEAK GUARD (#858): destroy the read stream if the client aborts or
+    // the connection closes before the pipe drains. Without this, an aborted
+    // GET /state/notes.md leaks the open file handle indefinitely (confirmed
+    // via handle64: dashboard held a handle on notes.md for 2+ hours). On
+    // Windows that lingering handle makes the engine's consolidation
+    // renameSync throw EPERM, which used to crash-loop the whole daemon.
+    const destroyStream = () => { if (!stream.destroyed) stream.destroy(); };
+    if (typeof res.on === 'function') res.on('close', destroyStream);
+    if (typeof req.on === 'function') {
+      req.on('close', destroyStream);
+      req.on('aborted', destroyStream);
+    }
     stream.on('error', (err) => {
+      destroyStream();
       if (!res.headersSent) {
         res.statusCode = 500;
         res.setHeader('Content-Type', 'application/json');
@@ -4113,20 +4143,40 @@ function _resetPreambleCache() {
   _preambleCacheTs = 0;
 }
 
-// Compact one-word-ish label for a project's effective dispatch checkout mode,
-// for CC state surfaces (preamble + refresh). 'worktree' | 'live' |
-// 'hybrid (live-validation: <type>)' so CC can see at a glance whether a project
-// authors in isolated worktrees, runs in-place on the operator tree, or splits
-// the two (coding → worktree, validation type → live). See resolveCheckoutMode.
+function _projectLiveValidationTypeValue(p) {
+  const types = shared.resolveLiveValidationTypes(p);
+  if (types.length === 0) return null;
+  return Array.isArray(p?.liveValidation?.type) ? types : types[0];
+}
+
+function _projectCheckoutConfigView(p) {
+  const checkoutMode = shared.resolveCheckoutMode(p);
+  return {
+    checkoutMode,
+    liveValidationType: checkoutMode === 'live' ? _projectLiveValidationTypeValue(p) : null,
+    liveValidationInvalid: checkoutMode === 'live' && shared.isLiveValidationConfigInvalid(p),
+    liveValidationAutoDispatch: !!shared.resolveLiveValidationAutoDispatchType(p),
+  };
+}
+
+// Compact checkout-mode label for Command Center state surfaces.
 function _projectCheckoutModeLabel(p) {
-  const mode = shared.resolveCheckoutMode(p);
-  if (mode === 'live' && p && p.liveValidation && p.liveValidation.type) {
-    // liveValidation.type may be a single string (legacy) or an array of
-    // strings (W-mr2m1ute000a9c01 — multi-select hybrid types); render all.
-    const types = Array.isArray(p.liveValidation.type) ? p.liveValidation.type : [p.liveValidation.type];
+  const {
+    checkoutMode,
+    liveValidationType,
+    liveValidationInvalid,
+  } = _projectCheckoutConfigView(p);
+  if (liveValidationInvalid) {
+    const effectiveTypes = liveValidationType
+      ? (Array.isArray(liveValidationType) ? liveValidationType : [liveValidationType])
+      : [];
+    return `hybrid (invalid liveValidation; effective live types: ${effectiveTypes.join(', ') || 'none'})`;
+  }
+  if (checkoutMode === 'live' && liveValidationType) {
+    const types = Array.isArray(liveValidationType) ? liveValidationType : [liveValidationType];
     return `hybrid (live-validation: ${types.join(', ')})`;
   }
-  return mode;
+  return checkoutMode;
 }
 
 function buildCCStatePreamble() {
@@ -4299,13 +4349,13 @@ function getWorkItemPrRef(input) {
   // afford to be loose because gating would still require explicit
   // operator intent.
   //
-  // FIX-TYPE GATE on the stamp path (W-mqbaby2a000pa8ee): in practice
+  // FIX-LIKE GATE on the stamp path (W-mqbaby2a000pa8ee): in practice
   // the asymmetry leaked — the loose stamp writes to `item.pr_id` (a
   // canonical structured field), and the strict gate later reads
   // `item.pr_id` and sees the loose stamp AS IF it were structured
   // intent. To stop that leak without changing the loose detector
   // (which has other legitimate callers), `copyWorkItemPrFields` now
-  // gates the loose result on `item.type === "fix"`. Non-fix WIs only
+  // gates the loose result through `isFixLikeWorkType`. Other WIs only
   // get stamped from structured fields (incl. references/follow-up).
   // See the comment block on `copyWorkItemPrFields` above for details.
   return shared.extractWorkItemPrRef(input);
@@ -7681,7 +7731,7 @@ const server = http.createServer(async (req, res) => {
       { dir: path.join(PLANS_DIR, 'archive'), archived: true },
     ]) {
       const allFiles = (await fsp.readdir(dir).catch(() => [])).filter(f => f.endsWith('.md'));
-      const dirResults = await Promise.all(allFiles.map(async f => {
+      const dirResults = await _mapInBatches(allFiles, 25, async f => {
         const filePath = path.join(dir, f);
         const [content, stat] = await Promise.all([
           fsp.readFile(filePath, 'utf8').catch(() => ''),
@@ -7718,10 +7768,20 @@ const server = http.createServer(async (req, res) => {
           revisionFeedback: null,
           version: versionMatch ? parseInt(versionMatch[1]) : null,
         };
-      }));
+      });
       for (const r of dirResults) if (r) plans.push(r);
     }
 
+    const sourcePlanMtimes = new Map();
+    const sourcePlanNames = [...new Set(prdRows
+      .filter(row => !row.archived && row.plan?.source_plan)
+      .map(row => row.plan.source_plan))];
+    const sourceStats = await _mapInBatches(sourcePlanNames, 25, async sourcePlan => {
+      const stat = await fsp.stat(path.join(PLANS_DIR, sourcePlan)).catch(() => null);
+      return [sourcePlan, stat ? Math.floor(stat.mtimeMs) : null];
+    });
+    for (const [sourcePlan, mtimeMs] of sourceStats) sourcePlanMtimes.set(sourcePlan, mtimeMs);
+
     // --- PRD JSON records (prd/*.json + prd/archive/*.json, SQL-backed) ---
     for (const row of prdRows) {
       const plan = row.plan;
@@ -7735,11 +7795,9 @@ const server = http.createServer(async (req, res) => {
       // so the Plans tab does not silently mirror a stale-but-cached false.
       let freshStale = false;
       if (!archived && plan.source_plan) {
-        try {
-          const sourceMtime = Math.floor(fs.statSync(path.join(PLANS_DIR, plan.source_plan)).mtimeMs);
-          const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
-          if (recorded && sourceMtime > recorded) freshStale = true;
-        } catch { /* source plan may have been deleted/renamed */ }
+        const sourceMtime = sourcePlanMtimes.get(plan.source_plan);
+        const recorded = plan.sourcePlanModifiedAt ? new Date(plan.sourcePlanModifiedAt).getTime() : null;
+        if (recorded && sourceMtime != null && sourceMtime > recorded) freshStale = true;
       }
       // P-e8d49105 — _projects rollup feeds the plan-card multi-badge
       // path in dashboard/js/render-plans.js. For PRD JSONs, walk
@@ -10835,19 +10893,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
           name: p.name,
           localPath: p.localPath || null,
           mainBranch: p.mainBranch || null,
-          // P-a3f9b207 — surface checkoutMode so the Settings UI can pre-fill
-          // the per-project dropdown. resolveCheckoutMode honors the legacy
-          // worktreeMode field; 'worktree' (default) or 'live'.
-          checkoutMode: shared.resolveCheckoutMode(p),
-          // W-mr9mx93d000x1dda — surface the hybrid liveValidation config
-          // (type(s) + autoDispatch) so the Settings → Projects checkout-mode
-          // control can pre-fill its Hybrid sub-panel authoritatively (mirrors
-          // the /api/status project mapping the Projects-bar picker reads).
-          // Only meaningful under checkoutMode:'live'; null/false otherwise.
-          liveValidationType: (shared.resolveCheckoutMode(p) === 'live' && p.liveValidation && p.liveValidation.type)
-            ? p.liveValidation.type
-            : null,
-          liveValidationAutoDispatch: !!(shared.resolveCheckoutMode(p) === 'live' && p.liveValidation && p.liveValidation.autoDispatch === true),
+          ..._projectCheckoutConfigView(p),
           // W-mqtvnnj1000357fa — surface the RAW per-project auto-stash override
           // (true / false / undefined) so the Settings UI can pre-select the
           // tri-state dropdown. Undefined means "use fleet default"
@@ -11767,6 +11813,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
             age_minutes: ageMinutes,
           };
         }
+
         return {
           agentId: rec.agentId,
           valid: true,
@@ -11790,6 +11837,18 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }
   }
 
+  async function handleWorktreeQuarantineRefs(req, res) {
+    try {
+      const { listQuarantineRefs } = require('./engine/quarantine-refs');
+      return jsonReply(res, 200, {
+        items: await listQuarantineRefs(PROJECTS),
+        generatedAt: new Date().toISOString(),
+      }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
   async function handleKeepProcessesKill(req, res) {
     try {
       const body = await readBody(req);
@@ -13184,6 +13243,7 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     }},
     { method: 'GET', path: '/api/health', desc: 'Lightweight health check for monitoring', handler: handleHealth },
     { method: 'GET', path: '/api/keep-processes', desc: 'List all active agents/<id>/keep-pids.json entries (W-mp68q6ke0010de68)', handler: handleKeepProcessesList },
+    { method: 'GET', path: '/api/worktree-quarantine-refs', desc: 'List recoverable refs/minions/quarantine/* and quarantine-wip/* refs across configured projects', handler: handleWorktreeQuarantineRefs },
     { method: 'POST', path: '/api/keep-processes/kill', desc: 'Kill a single kept PID and remove it from the agent\'s keep-pids.json', params: 'agentId, pid', handler: handleKeepProcessesKill },
     // P-4b8d2e57 (managed-spawn item 4): engine-managed long-running services.
     // List/by-name return ETag + honor If-None-Match → 304. Kill removes from
@@ -14772,7 +14832,8 @@ if (require.main === module) {
     // supervisor) discovers it instead of guessing 7331. The original
     // server.on('error') one-shot exit is replaced by the retry loop — only
     // non-EADDRINUSE errors abort.
-    const maxScan = shared.DASHBOARD_PORT_SCAN_MAX || 100;
+    const requireRequestedPort = process.env.MINIONS_REQUIRE_DASHBOARD_PORT === '1';
+    const maxScan = requireRequestedPort ? 1 : (shared.DASHBOARD_PORT_SCAN_MAX || 100);
     let listenErr = null;
     for (let attempt = 0; attempt < maxScan; attempt++) {
       const tryPort = REQUESTED_PORT + attempt;
@@ -14798,7 +14859,10 @@ if (require.main === module) {
     }
     if (listenErr) {
       if (listenErr.code === 'EADDRINUSE') {
-        console.error(`\n  No free port in [${REQUESTED_PORT}..${REQUESTED_PORT + maxScan - 1}]. Free one and retry.\n`);
+        const range = requireRequestedPort
+          ? String(REQUESTED_PORT)
+          : `[${REQUESTED_PORT}..${REQUESTED_PORT + maxScan - 1}]`;
+        console.error(`\n  No free dashboard port at ${range}. Free it and retry.\n`);
       } else {
         console.error(listenErr);
       }

package/docs/README.md

@@ -29,6 +29,7 @@ Hands-on stories and distribution guides for people running or evaluating Minion
 Architecture, design proposals, and lifecycle references for people working on the engine, dashboard, or playbooks.
 
 - [branch-derivation.md](branch-derivation.md) — Engine-side branch fallback (`work/<wi-id>`) vs. agent-authored long form, the structured-vs-loose PR-pointer extractors, and the canonical PR-fix duplication incident.
+- [claude-md-propagation.md](claude-md-propagation.md) — Propagating repo-authored `CLAUDE.md` instructions to runtimes that don't auto-load it (Copilot/Codex): the `claudeMdNativeDiscovery` capability flag, the bounded nearest-applicable walk-up discovery, the `propagateClaudeMdForNonClaudeRuntimes` config knob, and why it's orthogonal to each runtime's native `AGENTS.md` discovery.
 - [command-center.md](command-center.md) — Command Center (CC) chat panel: configured-runtime sessions, resume semantics, system-prompt invalidation, and per-tab session storage.
 - [specs/agent-rename.md](specs/agent-rename.md) — Design spec for **agent rename & name decoupling** — the prerequisite for the Role/Agent Library. Formalizes the stable opaque agent id, makes charters name-agnostic, and adds `POST /api/agents/rename` (display name + emoji). Feature-flagged (`agent-rename`) and fully backward-compatible.
 - [specs/agent-configurability.md](specs/agent-configurability.md) — Design spec for the user-configurable Role / Agent Library, feature-flagged behind `agent-library` and fully backward-compatible. Builds on `agent-rename.md`. Role = the reusable durable charter; agent = a thin instance (identity + variable expertise + role pointer). Phase 0 renames `skills`→`expertise`; Phase 1 exposes/edits role charters + per-agent expertise; Phase 2 adds role/agent CRUD with builtin delete-protection.

package/docs/claude-md-propagation.md

@@ -0,0 +1,118 @@
+# CLAUDE.md propagation to non-Claude runtimes
+
+**Work item:** W-mrdon0pe000l045a
+**Config flag:** `engine.propagateClaudeMdForNonClaudeRuntimes` (default `true`)
+**Per-project override:** `project.propagateClaudeMdForNonClaudeRuntimes`
+**Module:** `engine/claude-md-context.js` · **Injection:** `engine/playbook.js`
+
+## Problem
+
+`CLAUDE.md` auto-discovery is a **Claude-Code-CLI-only** convention — the `claude`
+binary reads repo-authored `CLAUDE.md` files itself at startup (unless `--bare`).
+The **Copilot** and **Codex** runtimes have **no equivalent auto-load** for
+`CLAUDE.md` at all. So repo-authored `CLAUDE.md` files — which frequently carry
+load-bearing "must be kept in sync" instructions and name blessed tooling — are
+structurally invisible to a Copilot/Codex-based fleet.
+
+### Motivating incident
+
+`W-mrdkv6zc00071fef` (a `fluidclientframework.android` dependency bump in
+`office/src`) missed a **third** sync-point file (`settings.gradle.kts:116`) that
+`loop/app/android/android/CLAUDE.md` explicitly warns about, and that
+`updateDeps.bat` (named in that same `CLAUDE.md`) would have caught via its build
+verification step. Neither the implementer nor the reviewer ever saw that file's
+content because Copilot has no `CLAUDE.md` auto-load mechanism. Propagating
+`CLAUDE.md` content directly addresses recurrence of this bug class.
+
+## Relationship to Copilot's native `AGENTS.md` discovery (NOT the same gap)
+
+Copilot has its **own native `AGENTS.md` auto-load**, which (post-#817, "Delegate
+repository harness discovery to native runtimes") Minions leaves to the runtime
+CLI itself rather than suppressing or synthesizing.
+
+`CLAUDE.md` propagation is **independent and additive**:
+
+- `CLAUDE.md` carries **zero split-brain risk** for Copilot/Codex, because those
+  runtimes **never read it themselves** — there is nothing to conflict with.
+- Therefore propagation is **orthogonal** to Copilot's native `AGENTS.md`
+  discovery: whether or not the runtime loads its own `AGENTS.md` has **no
+  effect** on `CLAUDE.md` propagation.
+
+| Concern | Owner | What governs it |
+|---------|-------|-----------------|
+| Copilot's OWN `AGENTS.md` auto-load | the Copilot CLI (native) | delegated to the runtime; Minions does not suppress or synthesize it |
+| Repo `CLAUDE.md` invisible to non-Claude runtimes | `propagateClaudeMdForNonClaudeRuntimes` | injects a "Project instructions (CLAUDE.md)" prompt layer |
+
+## Capability flag
+
+Each runtime adapter (`engine/runtimes/<name>.js`) declares
+`capabilities.claudeMdNativeDiscovery`:
+
+| Runtime | `claudeMdNativeDiscovery` | Propagation |
+|---------|---------------------------|-------------|
+| `claude` | `true` | **skipped** — the Claude CLI already reads CLAUDE.md; re-injecting would double it |
+| `copilot` | `false` | **injected** |
+| `codex` | `false` | **injected** |
+
+Unknown runtimes are treated as **not** auto-discovering (propagate), since an
+unrecognized runtime is far more likely to lack native CLAUDE.md loading than to
+have it. Engine code gates on the capability flag, never on `runtime.name`.
+
+## Bounded discovery algorithm
+
+`office/src` is a huge monorepo — a full tree walk collecting every `CLAUDE.md`
+is not viable. Instead the module mirrors how a human/tool resolves "nearest
+applicable instructions":
+
+1. **Collect path hints** for the dispatch (`engine.js#_deriveClaudeMdPathHints`):
+   `item.meta.workdir` and `item.references[*].path`.
+2. **Walk UP** from each hint directory toward the **project root**, `stat`-ing
+   `CLAUDE.md` at each ancestor level (`discoverClaudeMdFiles`).
+3. **Always include the project-root `CLAUDE.md`** as a fallback — if there are
+   no path hints, at minimum the project root is checked (discovery is never
+   skipped entirely).
+4. **Nearest-wins ordering:** deepest directory first, project root last, so the
+   most specific instructions lead.
+5. **Bounds (cheap by construction):**
+   - `MAX_WALK_DEPTH = 24` ancestor levels per hint (deep-path guard),
+   - `MAX_FILES = 8` total collected files,
+   - path-traversal guard — hints that escape the project root are dropped,
+   - the walk **never ascends above the project root**.
+
+This only `stat`s `CLAUDE.md` at a small number of ancestor directories, so it
+does not meaningfully slow dispatch even in a monorepo.
+
+## Injection & byte cap
+
+`engine/playbook.js#renderPlaybook` adds `CLAUDE.md` propagation as a context
+layer alongside the existing `pinned.md` → `notes.md` →
+`knowledge/agents/<agentId>.md` layers:
+
+- Header: `## Project instructions (CLAUDE.md)`, with a short provenance note so
+  the agent understands why it appears and that "keep in sync" rules are
+  authoritative.
+- Content is wrapped in an `<UNTRUSTED-INPUT>` fence (repo-authored, semi-trusted).
+- Each file is labeled by its repo-relative path (`### <relPath>`).
+- The whole block is capped at `ENGINE_DEFAULTS.maxNotesPromptBytes` (the same
+  budget the sibling notes / agent-memory layers use), so it can never balloon a
+  prompt on a large monorepo. Individual files are truncated with a
+  "read the full file if needed" marker when they exceed the remaining budget.
+
+Injection only happens when **all** hold:
+
+1. the resolved runtime's `claudeMdNativeDiscovery` is falsy (Copilot/Codex),
+2. `resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine)` returns true,
+3. the project has a `localPath`, and
+4. at least one non-empty `CLAUDE.md` was discovered.
+
+## Config resolution
+
+`shared.resolvePropagateClaudeMdForNonClaudeRuntimes(project, engine)`:
+
+1. per-project boolean `project.propagateClaudeMdForNonClaudeRuntimes`, else
+2. fleet-wide boolean `engine.propagateClaudeMdForNonClaudeRuntimes`, else
+3. hardcoded default `true`.
+
+Only an explicit boolean counts as "set" at either level (undefined/null/string
+fall through). Editable from **Settings → Copilot Tuning → "Propagate CLAUDE.md
+to non-Claude runtimes"** or via `POST /api/settings`.

package/docs/engine-restart.md

@@ -70,6 +70,16 @@ If an agent is killed as an orphan and the work item retries, cooldowns use expo
 
 The engine.js *process itself* (not an agent) can crash and get auto-respawned by three independent mechanisms: `engine/supervisor.js#checkEngine` (dead-PID), `engine/supervisor.js#checkEngineHung` (stale-heartbeat), and `engine/watchdog.js` (OS-scheduled external recovery); `dashboard.js`'s in-process 30s watchdog also auto-restarts on a dead PID (the user-triggered Restart Engine button is excluded). Each successful respawn calls `shared.recordEngineRespawn(source)`, which appends `{ts, source}` to `control.json`'s `engineRespawns[]` (rolling window, default `CRASH_LOOP_WINDOW_MS` = 10 min). Once respawns within the window reach `CRASH_LOOP_THRESHOLD` (default 3), `control.crashLoopAlert` is set (dashboard-visible via `/api/status`) and a deduped (one-per-day) `notes/inbox/` alert is written; the alert clears automatically once the window rolls past the incident. Override the window/threshold via `MINIONS_CRASH_LOOP_WINDOW_MS` / `MINIONS_CRASH_LOOP_THRESHOLD` env vars.
 
+### 7. Exclusive Restart Topology
+
+Managed dashboard spawns must bind the requested port; automatic fallback remains available only for standalone `node dashboard.js` use. Before a supervisor respawn, every matching stale daemon is killed and confirmed dead. If any PID survives, the supervisor skips the replacement and retries on its next tick instead of creating a second engine or a dashboard on another port.
+
+`minions restart` verifies ownership of the exact engine, dashboard, and supervisor PIDs it spawned and rejects duplicate daemon processes. A failed verification tears down the partial stack and leaves `stop-intent.json` set so watchdogs cannot race another replacement into the failed topology.
+
+PID-bearing file locks are reaped immediately when their recorded owner is dead. The five-minute stale threshold remains for legacy locks without owner metadata and the longer safety window remains for live holders.
+
+Dashboard hot polling avoids recurring event-loop stalls: freshness-directory walks are coalesced briefly, plan scans are cached for 30 seconds and processed in cooperative batches, and quarantine-ref Git reads run asynchronously in parallel.
+
 ## Safe Restart Pattern
 
 ```bash