@yemi33/minions 0.1.2321 → 0.1.2323

package/dashboard.js

@@ -3959,6 +3959,7 @@ function _buildSyntheticActionResultsForTurn(turnId, message, requestedAt) {
     if (entry.id) result.id = entry.id;
     if (entry.project) result.project = entry.project;
     if (entry.path) result.path = entry.path;
+    if (entry.duplicate) result.duplicate = true;
     if (Array.isArray(entry.followups) && entry.followups.length) result.followups = entry.followups;
     results.push(result);
   }
@@ -6914,6 +6915,14 @@ const server = http.createServer(async (req, res) => {
       const createResult = createWorkItemWithDedup(wiPath, item);
       if (!createResult.created) {
         const duplicateId = createResult.duplicateOf || createResult.item?.id;
+        // W-mr466ocx000l1191 — record the CC turn creation on the dedup path
+        // too. The API call still succeeded (ok:true) from the caller's
+        // perspective; without this, a CC turn that dispatches a work item
+        // matching an existing one silently loses its confirmation chip
+        // (_buildSyntheticActionResultsForTurn drains an empty list for the
+        // turn, so donePayload.actions/actionResults come back empty even
+        // though the LLM's tool call succeeded).
+        recordCcTurnIfPresent(req, { kind: 'work-item', id: duplicateId, title: item.title, project: item.project || null, duplicate: true });
         return jsonReply(res, 200, { ok: true, id: duplicateId, duplicate: true, duplicateOf: duplicateId });
       }
       recordCcTurnIfPresent(req, { kind: 'work-item', id, title: item.title, project: item.project || null });
@@ -13902,6 +13911,55 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       return jsonReply(res, 200, { ok: true, cleared: cause, prId });
     }},
 
+    // Issue #671 — sibling to clear-paused-cause above, but for the
+    // headSha-keyed `_buildFixIneffective` ("infra issue suspected") pause
+    // (see engine/lifecycle.js#recordBuildFixIneffective), which is tracked
+    // separately from `_noOpFixes` and so isn't reachable via the endpoint
+    // above. Once a fresh CI build is queued against a rebased/retried head,
+    // this lets an operator clear the stale pause without hand-editing
+    // pull-requests.json.
+    { method: 'POST', path: '/api/pull-requests/clear-build-fix-ineffective', desc: 'Resume a paused build-fix-ineffective ("infra issue suspected") pause (issue #671) — clears _buildFixIneffective so BUILD_FAILURE auto-fix dispatch can resume', params: 'prId (canonical host:slug#number), headSha? (optional — if provided, must match the paused record\'s headSha or the clear is rejected as stale)', handler: async (req, res) => {
+      const body = await readBody(req);
+      const prId = typeof body?.prId === 'string' ? body.prId.trim() : '';
+      const headSha = typeof body?.headSha === 'string' ? body.headSha.trim() : '';
+      if (!prId) return jsonReply(res, 400, { error: 'prId required' });
+      reloadConfig();
+      const lifecycle = require('./engine/lifecycle');
+      const prPaths = [
+        ...shared.getProjects(CONFIG).map(p => shared.projectPrPath(p)),
+        shared.centralPullRequestsPath(MINIONS_DIR),
+      ];
+      let prFound = false;
+      let recordCleared = false;
+      let staleHead = false;
+      for (const prPath of prPaths) {
+        if (recordCleared || staleHead) break;
+        shared.mutatePullRequests(prPath, (prs) => {
+          if (!Array.isArray(prs)) return prs;
+          const target = prs.find(p => p && p.id === prId);
+          if (!target) return prs;
+          prFound = true;
+          const record = target._buildFixIneffective;
+          if (!record || typeof record !== 'object') return prs;
+          // If the caller told us which head they saw the pause on (the
+          // dashboard chip stamps this at render time), refuse to clear a
+          // pause that has since moved on to a different head — that would
+          // silently apply a stale click's intent to a newer commit.
+          if (headSha && record.headSha && record.headSha !== headSha) {
+            staleHead = true;
+            return prs;
+          }
+          recordCleared = lifecycle.clearBuildFixIneffective(target);
+          return prs;
+        });
+      }
+      if (!prFound) return jsonReply(res, 404, { error: `PR ${prId} not found` });
+      if (staleHead) return jsonReply(res, 409, { error: `build-fix-ineffective pause on PR ${prId} is for a different head than provided — refresh and retry` });
+      if (!recordCleared) return jsonReply(res, 400, { error: `PR ${prId} has no tracked build-fix-ineffective pause` });
+      invalidateStatusCache();
+      return jsonReply(res, 200, { ok: true, cleared: 'build-fix-ineffective', prId });
+    }},
+
     // ─── P-f3c9d0e7: convenience pause/resume endpoints ─────────────────────
     // Single-call wrappers over `POST /api/settings { engine: { <flag>: bool } }`
     // for the two operator kill-switches:

package/docs/harness-transparency.md

@@ -62,6 +62,21 @@ flagged un-grounded downstream. This capture is observability only — it does
 **not** change which dirs are propagated at spawn time, and any failure here is
 non-fatal (the spawn proceeds).
 
+**Monorepo sub-project contributes `--add-dir` roots (P-f52d81ba).** The `addDirs` set
+folded into the manifest includes the project-local harness dirs propagated for
+the dispatch. When the engine auto-derives a dominant sub-project (see
+[project-skills.md → Monorepo sub-project scoping](project-skills.md#monorepo-sub-project-scoping)),
+those sub-project-scoped `--project-harness-dir` roots flow into `propagatedProjectHarnessDirs`
+→ `addDirs` → the `_harnessPropagated` manifest. The clip that selects them is
+the **same** `shared.filterProjectHarnessDirsForWorkdir` used for an explicit
+`meta.workdir` — `spawnAgent` passes `workdir: validatedWorkdir || _effectiveSubproject
+|| null`, so an explicit `meta.workdir` wins, else the auto-derived sub-project's
+first-level segment clips the surface, else no clip (whole-project harness).
+Because the manifest captures the same sub-project-clipped roots the agent was actually
+handed, a self-reported skill usage against a sub-project's skill (e.g.
+`ocm/.claude/skills/…`) still grounds `true` — grounding stays faithful under
+sub-project scoping instead of falsely flagging the sub-project's own skills.
+
 The grounding cross-check (P-c6f5e8b3) runs in `engine/lifecycle.js`
 `runPostCompletionHooks` once the completion report is parsed and nonce-trusted:
 `shared.groundHarnessUsed(completionReport.harnessUsed, _harnessPropagated)`
@@ -170,7 +185,8 @@ evaluation pass) can see what tooling drove a dispatch:
 ## Related
 
 - `engine/shared.js` — `HARNESS_USED_KINDS`, `HARNESS_USED_MAX_ENTRIES`,
-  `HARNESS_USED_MAX_FIELD_LEN`, `normalizeHarnessUsed()`, `groundHarnessUsed()`
+  `HARNESS_USED_MAX_FIELD_LEN`, `normalizeHarnessUsed()`, `groundHarnessUsed()`,
+  `filterProjectHarnessDirsForWorkdir()` (the sub-project/workdir clip)
 - `engine/queries.js` — `buildHarnessPropagatedManifest()`,
   `getUserHarnesses()`, `getProjectHarnesses()`
 - `engine/lifecycle.js` — `resolveHarnessPropagated()` + the grounding

package/docs/project-skills.md

@@ -46,6 +46,67 @@ The walk is **cheap and bounded** — preserve every guardrail in
 - ≤ 50 nested areas probed
 - Missing worktree / unreadable → `[]` (never throws)
 
+## Monorepo sub-project scoping
+
+P-f52d81ba. In a monorepo, a dispatch usually touches one sub-project (`ocm/`,
+`loop/`, `officemobile/`, …) even though discovery walks every sub-project's
+`.claude/skills`. Scoping surfaces that sub-project's skills **first** without hiding
+the rest, so an `ocm/`-focused agent isn't forced to scroll past `loop/` tooling
+to find the relevant pack.
+
+**Changed-path → sub-project detection.** `detectDominantSubproject({ projectPath,
+changedPaths })` (engine/discover-project-skills.js) counts the changed paths
+per first-level directory, keyed on the POSIX first segment. It reuses
+`_listAreas` for the authoritative set of valid sub-projects, so a stray first segment
+that isn't a real top-level dir never counts. It returns `{ subproject, matched,
+total, confident }`. The engine feeds it changed paths from:
+
+- **spawnAgent** (async, authoritative): `git diff --name-only <mainBranch>...HEAD`
+  in the current dispatch's worktree — never a parent/follow-up's stale diff.
+- **renderProjectWorkItemPromptForAgent** (`_deriveDominantSubprojectSync`, build-time
+  fallback with no git access): the work item's `references[*].path`.
+
+**Dominant-sub-project plurality threshold.** `detectDominantSubproject` only reports a sub-project
+as `confident` when the top sub-project holds **≥ 60%** of the sub-project-matched files **and**
+**≥ 2** files (`dominantSubprojectMinRatio` / `dominantSubprojectMinFiles` in `DEFAULTS`,
+overridable via `opts`). Ties break alphabetically for determinism. An empty,
+mixed, or no-known-sub-project diff returns `{ subproject: null, confident: false }` →
+flat discovery (today's global name-sort). This is deliberately conservative:
+a weakly-dominant or split diff falls back to flat surfacing rather than
+mis-scoping to the wrong sub-project.
+
+**Explicit `meta.workdir` wins over auto-detection.** When the operator declares
+`meta.workdir` on the work item, the effective sub-project is its first path segment —
+no diff work is done. Auto-detection only runs when `meta.workdir` is absent.
+The async git-diff-derived sub-project (threaded into the shared-branch re-render via
+`options.dominantSubproject`) overrides the sync `references`-derived guess.
+
+**Prioritized, not exclusive, surfacing.** The effective sub-project is threaded through
+`playbook.js` as `scopeSubproject` into `discoverProjectSkillsWithDiagnostics`. When
+set, entries under `<scopeSubproject>/` lead the list (name-sorted within the group),
+then root-level entries, then other-sub-project entries. **Discovery still walks
+everything — no skills are dropped; only ordering changes.** An empty/unset
+`scopeSubproject` reduces byte-for-byte to the historical global name-then-path sort.
+
+**Configurable per-surface cap.** `ENGINE_DEFAULTS.projectSkillMaxFilesPerSurface`
+(default **200**) caps how many skill packs / command files are read per surface
+(root `.claude/skills`, each `<area>/.claude/skills`, …). `playbook.js` threads
+it into the discovery `opts`; when no override is supplied the module falls back
+to its own `DEFAULTS.maxFilesPerSurface` (50). It's raised well above the
+fallback so large monorepo sub-projects (e.g. an `ocm/.claude/skills` with ~80 packs)
+don't silently drop the most-relevant skills. Entries are alphabetically sorted
+**before** the cap is applied, so the surviving subset is deterministic across
+runs and OSes rather than FS-readdir-order-dependent.
+
+**Truncation diagnostics.** `discoverProjectSkillsWithDiagnostics` returns
+`{ entries, truncations }` where each truncation is `{ surface, dir, scanned,
+total }` — recorded when a surface's `total` file count exceeds `scanned`
+(i.e. the cap dropped entries). `playbook.js` logs a `warn` when any surface
+truncates and stashes the diagnostics so `spawnAgent` can persist the detected
+sub-project (`_dominantSubproject`) and truncations (`_skillDiscoveryTruncations`) onto the
+dispatch record for later grounding/observability. Overflow is thus **observable**
+instead of silent.
+
 ## The intent vocabulary (CLOSED)
 
 | Intent | What belongs here |

package/engine/consolidation.js

@@ -1153,6 +1153,52 @@ function hasReusableSignal(content) {
   return REUSABLE_SIGNAL_RE.test(content || '');
 }
 
+// ── Engine-alert KB dedup (W-mr3pi9de, sibling of W-mr3lokxs) ────────────────
+// Recurring engine-system alerts (e.g. the worktree-skip-live guard firing
+// across many different worktrees, or the same live-checkout-dirty incident
+// firing every tick) used to be written as full-size KB copies with -2/-3/…
+// numeric suffixes via uniquePath, multiplying storage N times per day.
+// Instead we content-hash each alert and skip writing when a same-hash entry
+// already exists in the target category. The hash is stored in the entry's
+// frontmatter (`alertHash:`) so future passes can dedup against it cheaply.
+
+// Normalized, length-bounded content hash. Collapses whitespace so trivially
+// re-rendered dumps (e.g. differing timestamps) still collapse to one hash.
+function _alertContentHash(content) {
+  const raw = String(content || '');
+  const normalized = raw.replace(/\s+/g, ' ').trim().slice(0, 4000);
+  return crypto.createHash('sha256').update(normalized + ':' + raw.length).digest('hex');
+}
+
+// Read only the leading bytes of a file (frontmatter lives at the very top) so
+// scanning a directory that also holds huge legacy full-body dumps never loads
+// those multi-MB bodies into memory.
+function _readFileHead(fp, bytes = 512) {
+  let fd;
+  try {
+    fd = fs.openSync(fp, 'r');
+    const buf = Buffer.alloc(bytes);
+    const n = fs.readSync(fd, buf, 0, bytes, 0);
+    return buf.slice(0, n).toString('utf8');
+  } catch { return ''; }
+  finally { if (fd !== undefined) { try { fs.closeSync(fd); } catch { /* best-effort */ } } }
+}
+
+// Does an existing KB entry in `dir` already carry this alertHash frontmatter?
+function _alertHashExists(dir, hash) {
+  if (!hash || !dir || !fs.existsSync(dir)) return false;
+  let files;
+  try { files = fs.readdirSync(dir); } catch { return false; }
+  const re = new RegExp(`^alertHash:\\s*${hash}\\s*$`, 'm');
+  for (const f of files) {
+    if (!f.endsWith('.md')) continue;
+    const head = _readFileHead(path.join(dir, f));
+    const fm = head.match(/^---\r?\n([\s\S]*?)\r?\n---/);
+    if (fm && re.test(fm[1])) return true;
+  }
+  return false;
+}
+
 /**
  * Build a condensed KB stub for narrowly-scoped, one-off notes instead of
  * duplicating the full body (issue #604 — classifyToKnowledgeBase was copying
@@ -1223,18 +1269,32 @@ async function classifyToKnowledgeBase(items, config) {
     // Reserve full-body KB copies for content that's actually general/reusable
     // (patterns, conventions, gotchas); narrowly-scoped one-off notes get a
     // condensed stub + link back to the archived note instead (issue #604).
-    const reusable = category === 'conventions' || hasReusableSignal(content);
+    //
+    // W-mr3pi9de — engine-authored system alerts (worktree-skip-live guard
+    // fires, dirty-tree refusals, blocked dispatches, managed-spawn failures)
+    // are operational noise, NEVER durable reusable knowledge. Force them
+    // non-reusable regardless of category or any incidental heading-shaped
+    // line in the body that would otherwise trip hasReusableSignal, and
+    // content-hash-dedup recurring identical/near-identical incidents instead
+    // of appending -2/-3 full copies with a colliding title.
+    const isSystemAlert = shared.isEngineSystemAlert(item.name, content);
+    const reusable = !isSystemAlert && (category === 'conventions' || hasReusableSignal(content));
     const archiveRelPath = `notes/archive/${dateStamp()}-${item.name}`;
     const kbBody = reusable
       ? content
       : buildCondensedKbBody(content, titleMatch ? titleMatch[0] : null, archiveRelPath);
 
-    const frontmatter = `---\nsource: ${item.name}\nagent: ${agent}\ncategory: ${category}\ndate: ${dateStamp()}\nreusable: ${reusable}\n---\n\n`;
-    try {
-      safeWrite(kbPath, frontmatter + kbBody);
-      classified++;
-    } catch (err) {
-      log('warn', `Failed to classify ${item.name} to knowledge base: ${err.message}`);
+    const alertHash = isSystemAlert ? _alertContentHash(content) : null;
+    if (isSystemAlert && _alertHashExists(categoryDirs[category], alertHash)) {
+      log('info', `KB dedup: skipping recurring engine-alert ${item.name} — duplicate of an existing knowledge/${category} entry`);
+    } else {
+      const frontmatter = `---\nsource: ${item.name}\nagent: ${agent}\ncategory: ${category}\ndate: ${dateStamp()}\nreusable: ${reusable}${isSystemAlert ? `\nalertHash: ${alertHash}` : ''}\n---\n\n`;
+      try {
+        safeWrite(kbPath, frontmatter + kbBody);
+        classified++;
+      } catch (err) {
+        log('warn', `Failed to classify ${item.name} to knowledge base: ${err.message}`);
+      }
     }
 
     // Per-agent memory routing — strict superset of broadcast consolidation.
@@ -1397,4 +1457,6 @@ module.exports = {
   NOTES_MAX_BYTES,
   hasReusableSignal,
   buildCondensedKbBody,
+  _alertContentHash,
+  _alertHashExists,
 };

package/engine/discover-project-skills.js

@@ -62,6 +62,8 @@ const DEFAULTS = {
   docsScanMaxBytes: 32 * 1024, // CLAUDE.md / copilot-instructions.md top window
   walltimeMs: 250,           // bail rather than block dispatch on pathological FS
   maxAreas: 50,              // cap how many <area>/ dirs we'll probe for nested .claude
+  dominantSubprojectMinRatio: 0.6, // detectDominantSubproject: top sub-project must hold >= this share of sub-project-matched files
+  dominantSubprojectMinFiles: 2,   // detectDominantSubproject: top sub-project must have >= this many matched files
 };
 
 // Intent vocabulary — CLOSED. Each entry maps an intent to the keyword/regex
@@ -169,21 +171,44 @@ function classifyIntents({ name = '', description = '', extra = '', explicit = [
   return intents;
 }
 
+// Record that a scanned surface exceeded opts.maxFilesPerSurface so callers can
+// surface an overflow diagnostic instead of silently dropping entries.
+function _recordTruncation(truncations, surface, projectPath, dir, scanned, total) {
+  if (!Array.isArray(truncations)) return;
+  if (total <= scanned) return;
+  truncations.push({
+    surface,
+    dir: path.relative(projectPath, dir).split(path.sep).join('/'),
+    scanned,
+    total,
+  });
+}
+
 // Walk <baseDir>/.claude/skills/*\/SKILL.md
-function _discoverSkillsAt(baseDir, projectPath, opts, deadline, originLabel) {
+function _discoverSkillsAt(baseDir, projectPath, opts, deadline, originLabel, truncations) {
   const out = [];
   const skillsDir = path.join(baseDir, '.claude', 'skills');
   let entries;
   try { entries = fs.readdirSync(skillsDir, { withFileTypes: true }); } catch { return out; }
+  // Stable alphabetical sort by entry name BEFORE applying the
+  // maxFilesPerSurface cap so the surviving subset is deterministic and
+  // reproducible across runs / OSes (raw readdir order is FS-dependent, so
+  // capping pre-sort silently dropped a non-deterministic slice).
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  const cap = opts.maxFilesPerSurface;
   let scanned = 0;
+  let total = 0;
   for (const ent of entries) {
-    if (scanned >= opts.maxFilesPerSurface) break;
     if (_now() > deadline) break;
     if (!ent.isDirectory()) continue;
     const skillPath = path.join(skillsDir, ent.name, 'SKILL.md');
     let stat;
     try { stat = fs.statSync(skillPath); } catch { continue; }
     if (!stat.isFile()) continue;
+    total += 1;
+    // Beyond the cap we still count `total` (for an accurate overflow
+    // diagnostic) but stop reading/emitting entries.
+    if (scanned >= cap) continue;
     scanned += 1;
     const head = _safeReadHead(skillPath, opts.maxBytesPerFile);
     if (!head) continue;
@@ -202,21 +227,28 @@ function _discoverSkillsAt(baseDir, projectPath, opts, deadline, originLabel) {
       _originLabel: originLabel,
     });
   }
+  _recordTruncation(truncations, 'skill', projectPath, skillsDir, scanned, total);
   return out;
 }
 
 // Walk <baseDir>/.claude/commands/*.md
-function _discoverCommandsAt(baseDir, projectPath, opts, deadline, originLabel) {
+function _discoverCommandsAt(baseDir, projectPath, opts, deadline, originLabel, truncations) {
   const out = [];
   const cmdDir = path.join(baseDir, '.claude', 'commands');
   let entries;
   try { entries = fs.readdirSync(cmdDir, { withFileTypes: true }); } catch { return out; }
+  // Stable alphabetical sort by entry name BEFORE applying the
+  // maxFilesPerSurface cap (see _discoverSkillsAt for the determinism rationale).
+  entries.sort((a, b) => a.name.localeCompare(b.name));
+  const cap = opts.maxFilesPerSurface;
   let scanned = 0;
+  let total = 0;
   for (const ent of entries) {
-    if (scanned >= opts.maxFilesPerSurface) break;
     if (_now() > deadline) break;
     if (!ent.isFile()) continue;
     if (!/\.md$/i.test(ent.name)) continue;
+    total += 1;
+    if (scanned >= cap) continue;
     scanned += 1;
     const base = ent.name.replace(/\.md$/i, '');
     const cmdPath = path.join(cmdDir, ent.name);
@@ -232,6 +264,7 @@ function _discoverCommandsAt(baseDir, projectPath, opts, deadline, originLabel)
       _originLabel: originLabel,
     });
   }
+  _recordTruncation(truncations, 'command', projectPath, cmdDir, scanned, total);
   return out;
 }
 
@@ -306,25 +339,138 @@ function _listAreas(projectPath, opts, deadline) {
 }
 
 /**
+ * Pure dominant-sub-project (area) detector.
+ *
+ * Given a set of changed paths, decide whether a single first-level project
+ * sub-project (e.g. `ocm/`, `loop/`, `officemobile/`) dominates the diff strongly
+ * enough that skill discovery / harness surfacing should be scoped to it.
+ * Reuses `_listAreas` for the authoritative set of valid sub-projects (sorted,
+ * dot-dir / node_modules filtered, capped at opts.maxAreas) so a stray first
+ * path segment that is NOT a real top-level directory never counts as a sub-project.
+ *
+ * Purity: no engine state, no fs beyond the single `_listAreas` readdir. The
+ * result is fully determined by (projectPath's first-level dirs, changedPaths,
+ * opts) — unit-testable against a fixture.
+ *
+ * @param {object} args
+ * @param {string} args.projectPath — absolute path to the project worktree / checkout
+ * @param {string[]} args.changedPaths — repo-relative changed file paths (any separator)
+ * @param {object} [args.opts] — override thresholds / caps (mostly for tests)
+ * @returns {{subproject:string|null, matched:number, total:number, confident:boolean}}
+ *   total    — count of changed paths considered
+ *   matched  — count of changed paths that fall under a known sub-project
+ *   subproject — the dominant sub-project when `confident`, else null (flat-discovery fallback)
+ *   confident — top sub-project holds >= minRatio of matched files AND >= minFiles files
+ */
+function detectDominantSubproject(args) {
+  const projectPath = args && args.projectPath;
+  const changedPaths = args && args.changedPaths;
+  const opts = Object.assign({}, DEFAULTS, (args && args.opts) || {});
+
+  const total = Array.isArray(changedPaths) ? changedPaths.length : 0;
+  if (!projectPath || typeof projectPath !== 'string' || total === 0) {
+    return { subproject: null, matched: 0, total, confident: false };
+  }
+
+  const deadline = _now() + Math.max(1, opts.walltimeMs);
+  const subprojects = new Set(_listAreas(projectPath, opts, deadline));
+  if (subprojects.size === 0) {
+    return { subproject: null, matched: 0, total, confident: false };
+  }
+
+  // Count changed files per known sub-project, keyed on the normalized first segment.
+  const counts = new Map();
+  let matched = 0;
+  for (const raw of changedPaths) {
+    if (typeof raw !== 'string' || raw.length === 0) continue;
+    // Normalize to POSIX and strip leading ./ and / so the first segment is
+    // the true top-level directory.
+    let p = raw.replace(/\\/g, '/');
+    while (p.startsWith('./')) p = p.slice(2);
+    while (p.startsWith('/')) p = p.slice(1);
+    const seg = p.split('/')[0];
+    if (!seg || !subprojects.has(seg)) continue;
+    matched += 1;
+    counts.set(seg, (counts.get(seg) || 0) + 1);
+  }
+
+  if (matched === 0) {
+    return { subproject: null, matched: 0, total, confident: false };
+  }
+
+  // Dominant sub-project = highest count; ties broken alphabetically for determinism.
+  let topSubproject = null;
+  let topCount = -1;
+  for (const [sub, count] of counts) {
+    if (count > topCount || (count === topCount && (topSubproject === null || sub.localeCompare(topSubproject) < 0))) {
+      topSubproject = sub;
+      topCount = count;
+    }
+  }
+
+  const minRatio = typeof opts.dominantSubprojectMinRatio === 'number' ? opts.dominantSubprojectMinRatio : DEFAULTS.dominantSubprojectMinRatio;
+  const minFiles = typeof opts.dominantSubprojectMinFiles === 'number' ? opts.dominantSubprojectMinFiles : DEFAULTS.dominantSubprojectMinFiles;
+  const confident = topCount >= minFiles && (topCount / matched) >= minRatio;
+
+  return { subproject: confident ? topSubproject : null, matched, total, confident };
+}
+
+// Normalize a caller-supplied scopeSubproject into a bare POSIX first-level dir name
+// (backslashes → slashes, leading/trailing slashes + whitespace stripped).
+// Returns '' when unset/empty so the sort can cheaply skip scope grouping.
+function _normalizeScopeSubproject(scopeSubproject) {
+  if (typeof scopeSubproject !== 'string') return '';
+  return scopeSubproject.replace(/\\/g, '/').replace(/^\/+/, '').replace(/\/+$/, '').trim();
+}
+
+// The project sub-project an entry's (repo-relative POSIX) path lives under, or
+// null for root-level entries. Sub-project skill/command paths look like
+// `<area>/.claude/…`; root skills/commands (`.claude/…`) and root docs
+// (`CLAUDE.md`, `.github/copilot-instructions.md`) have no owning sub-project.
+function _entrySubproject(entryPath) {
+  const m = /^([^/]+)\/\.claude\//.exec(String(entryPath || '').replace(/\\/g, '/'));
+  return m ? m[1] : null;
+}
+
+// Scope-ordering group for a scopeSubproject-aware sort. Lower ranks lead the list:
+//   0 = entry is under <scopeSubproject>/, 1 = root-level, 2 = other-sub-project.
+function _scopeGroup(entryPath, scopeSubproject) {
+  const p = String(entryPath || '').replace(/\\/g, '/');
+  if (scopeSubproject && (p === scopeSubproject || p.startsWith(scopeSubproject + '/'))) return 0;
+  return _entrySubproject(p) === null ? 1 : 2;
+}
+
+/**
+ * Diagnostics-returning discovery. Same walk as discoverProjectSkills but also
+ * reports per-surface overflow records so callers can tell when a directory
+ * exceeded opts.maxFilesPerSurface (and therefore had entries dropped) instead
+ * of silently losing them.
+ *
  * @param {object} args
  * @param {string} args.projectPath — absolute path to the project worktree / checkout
+ * @param {string} [args.scopeSubproject] — when set/non-empty, surface entries under
+ *   `<scopeSubproject>/` FIRST (name-sorted within group), then root-level entries,
+ *   then other-sub-project entries. Discovery still walks everything (no skills
+ *   dropped); only ordering changes. Unset/empty ⇒ today's global name-sort.
  * @param {object} [args.opts] — override defaults (mostly for tests)
- * @returns {Array<{kind:string,name:string,path:string,oneLineDescription:string,intents:string[]}>}
+ * @returns {{entries:Array<{kind:string,name:string,path:string,oneLineDescription:string,intents:string[]}>, truncations:Array<{surface:string,dir:string,scanned:number,total:number}>}}
  */
-function discoverProjectSkills(args) {
+function discoverProjectSkillsWithDiagnostics(args) {
   const projectPath = args && args.projectPath;
-  if (!projectPath || typeof projectPath !== 'string') return [];
-  try { if (!fs.statSync(projectPath).isDirectory()) return []; } catch { return []; }
+  if (!projectPath || typeof projectPath !== 'string') return { entries: [], truncations: [] };
+  try { if (!fs.statSync(projectPath).isDirectory()) return { entries: [], truncations: [] }; } catch { return { entries: [], truncations: [] }; }
 
+  const scopeSubproject = _normalizeScopeSubproject(args.scopeSubproject);
   const opts = Object.assign({}, DEFAULTS, args.opts || {});
   const deadline = _now() + Math.max(1, opts.walltimeMs);
 
   const seenKey = new Set(); // dedupe across surfaces by `${kind}:${name}`
   const seenSlash = new Set();
   const all = [];
+  const truncations = [];
 
   // 1. Root-level skills.
-  for (const entry of _discoverSkillsAt(projectPath, projectPath, opts, deadline, 'root')) {
+  for (const entry of _discoverSkillsAt(projectPath, projectPath, opts, deadline, 'root', truncations)) {
     const key = `skill:${entry.name}`;
     if (seenKey.has(key)) continue;
     seenKey.add(key);
@@ -332,7 +478,7 @@ function discoverProjectSkills(args) {
   }
 
   // 2. Root-level commands.
-  for (const entry of _discoverCommandsAt(projectPath, projectPath, opts, deadline, 'root')) {
+  for (const entry of _discoverCommandsAt(projectPath, projectPath, opts, deadline, 'root', truncations)) {
     const key = `command:${entry.name}`;
     if (seenKey.has(key)) continue;
     seenKey.add(key);
@@ -348,7 +494,7 @@ function discoverProjectSkills(args) {
     for (const area of areas) {
       if (_now() > deadline) break;
       const areaBase = path.join(projectPath, area);
-      for (const entry of _discoverSkillsAt(areaBase, projectPath, opts, deadline, `area:${area}`)) {
+      for (const entry of _discoverSkillsAt(areaBase, projectPath, opts, deadline, `area:${area}`, truncations)) {
         const key = `skill:${entry.name}`;
         if (seenKey.has(key)) continue;
         seenKey.add(key);
@@ -360,7 +506,7 @@ function discoverProjectSkills(args) {
       // half-scanned area: doing so drops commands while keeping skills from
       // the same area, causing test/prod divergence under load (PR-82 blind spot
       // regression, CI failure yemi33#28135287117).
-      for (const entry of _discoverCommandsAt(areaBase, projectPath, opts, deadline, `area:${area}`)) {
+      for (const entry of _discoverCommandsAt(areaBase, projectPath, opts, deadline, `area:${area}`, truncations)) {
         const key = `command:${entry.name}`;
         if (seenKey.has(key)) continue;
         seenKey.add(key);
@@ -379,15 +525,39 @@ function discoverProjectSkills(args) {
     all.push(entry);
   }
 
-  // Deterministic ordering: alphabetical by name, then by path as tiebreaker
-  // so prompt rendering is stable across runs and OSes (readdir order varies).
+  // Deterministic ordering. When a scopeSubproject is set, entries under
+  // `<scopeSubproject>/` lead the list, then root-level, then other-sub-project entries;
+  // within each group the original name-then-path sort applies. When scopeSubproject
+  // is empty the group ranks are all equal so this reduces byte-for-byte to the
+  // historical global name-then-path sort (no regression for existing callers).
   all.sort((a, b) => {
+    if (scopeSubproject) {
+      const ga = _scopeGroup(a.path, scopeSubproject);
+      const gb = _scopeGroup(b.path, scopeSubproject);
+      if (ga !== gb) return ga - gb;
+    }
     if (a.name !== b.name) return a.name.localeCompare(b.name);
     return String(a.path || '').localeCompare(String(b.path || ''));
   });
 
   // Strip the internal _originLabel before returning (debugging-only).
-  return all.map(({ _originLabel, ...rest }) => rest); // eslint-disable-line no-unused-vars
+  const entries = all.map(({ _originLabel, ...rest }) => rest); // eslint-disable-line no-unused-vars
+  return { entries, truncations };
+}
+
+/**
+ * @param {object} args
+ * @param {string} args.projectPath — absolute path to the project worktree / checkout
+ * @param {string} [args.scopeSubproject] — when set/non-empty, surface entries under
+ *   `<scopeSubproject>/` first, then root-level, then other-sub-project entries (see
+ *   discoverProjectSkillsWithDiagnostics). Unset/empty ⇒ global name-sort.
+ * @param {object} [args.opts] — override defaults (mostly for tests)
+ * @returns {Array<{kind:string,name:string,path:string,oneLineDescription:string,intents:string[]}>}
+ */
+function discoverProjectSkills(args) {
+  // Delegates to the diagnostics variant and returns only the entries array so
+  // existing array-returning callers keep working unchanged.
+  return discoverProjectSkillsWithDiagnostics(args).entries;
 }
 
 /**
@@ -478,6 +648,7 @@ function renderReviewSkillsBlock(entries) {
 
 module.exports = {
   discoverProjectSkills,
+  discoverProjectSkillsWithDiagnostics,
   filterByIntents,
   renderProjectSkillsBlock,
   classifyIntents,
@@ -494,5 +665,9 @@ module.exports = {
     _parseExplicitIntents,
     _extractSlashCommandsFromDoc,
     _listAreas,
+    detectDominantSubproject,
+    _normalizeScopeSubproject,
+    _entrySubproject,
+    _scopeGroup,
   },
 };

package/engine/lifecycle.js

@@ -2943,6 +2943,18 @@ function recordPrNoOpFixAttempt(target, cause, source, dispatchItem, branchChang
   return target._noOpFixes[cause];
 }
 
+// #671 — Clears the `_buildFixIneffective` ("infra issue suspected") pause so
+// BUILD_FAILURE auto-fix dispatch can resume. Distinct from
+// `clearPrNoOpFixAttempt` (below) because this pause is headSha-keyed rather
+// than cause-keyed — see `recordBuildFixIneffective` / `shared.isBuildFixIneffectivePaused`.
+// Returns true when a record was actually removed so callers (the dashboard
+// resume endpoint) can distinguish "cleared" from "nothing to clear".
+function clearBuildFixIneffective(target) {
+  if (!target?._buildFixIneffective) return false;
+  delete target._buildFixIneffective;
+  return true;
+}
+
 function clearPrNoOpFixAttempt(target, cause) {
   if (!target?._noOpFixes || !target._noOpFixes[cause]) return;
   delete target._noOpFixes[cause];
@@ -6821,6 +6833,9 @@ module.exports = {
   // Issue #2969 — exported so dashboard.js can clear a paused cause from the
   // resume endpoint.
   clearPrNoOpFixAttempt,
+  // Issue #671 — exported so dashboard.js can clear the build-fix-ineffective
+  // ("infra issue suspected") pause from the resume endpoint.
+  clearBuildFixIneffective,
   // W-mpx44p05000ze8d8 — exported so engine/ado.js + engine/github.js can
   // drop stale `_noOpFixes` records during their PR status poll, and so
   // unit tests can exercise the sweep helper directly.