@yemi33/minions 0.1.2178 → 0.1.2180

package/docs/harness-propagation.md

@@ -0,0 +1,273 @@
+# Harness Propagation
+
+> Status: contract doc for the **seamless user/repo harness invocation** plan
+> (`plans/seamless-user-repo-harness-invocation.md`, PRD
+> `prd/minions-opg-2026-06-10-4.json`). This is the foundation item — it nails
+> down the *current* propagation surfaces and the worktree footgun so the
+> rest of the plan can extend them without reinventing the contract. Read this
+> before adding a new adapter method, a new asset kind, or a new opt-out flag.
+
+## What is a "harness"
+
+In this doc, "harness" means any user-installed or repo-local asset that the
+runtime CLI auto-discovers when it starts:
+
+- **Skills** — `SKILL.md` files the CLI loads as reusable workflows.
+- **Slash commands** — `*.md` files the CLI exposes as `/command-name`.
+- **MCP servers** — JSON config entries that point at a stdio/HTTP server.
+
+A harness is "propagated" when it reaches a dispatched agent without the user
+having to register it again in Minions. The single-line goal: *if it works
+when you type the same task into `claude` / `copilot` / `codex` in this repo
+on this machine, it works when Minions dispatches the same task here.*
+
+## The four propagation mechanisms
+
+Every asset reaches the agent through exactly one of these mechanisms today.
+No engine code branches on `runtime.name` for any of them — the runtime
+adapter answers the contract questions and the engine fans out.
+
+### 1. Runtime native discovery (no engine code involved)
+
+The CLI reads its own config and indexes its own asset dirs on every spawn.
+Minions does not copy, symlink, or aggregate user-level assets — it just
+makes sure the relevant dirs are *readable* from the agent's cwd (see
+mechanism #3 below). The actual loading is the CLI's job.
+
+| Runtime | User skills | User commands | User MCP servers |
+|---------|-------------|---------------|------------------|
+| Claude (`engine/runtimes/claude.js`) | `~/.claude/skills`, `~/.agents/skills`, plus `~/.claude/plugins/<…>/skills` | `~/.claude/commands`, plugin `commands/` | `~/.claude.json → mcpServers` |
+| Copilot (`engine/runtimes/copilot.js`) | `~/.copilot/skills`, `~/.agents/skills`, `~/.copilot/installed-plugins/<…>/skills` | `~/.copilot/commands` *(probe)* | `~/.copilot/mcp-config.json → mcpServers` |
+| Codex (`engine/runtimes/codex.js`) | `~/.agents/skills`, `/etc/codex/skills` | not yet supported by CLI | not yet a stable contract |
+
+The first column is the source of truth for "where does the CLI look on
+this machine?". The dashboard's tooling page mirrors this via
+`engine/queries.js → collectSkillFiles / collectCommandFiles`.
+
+### 2. Cwd routing (`shared.resolveSpawnPaths`)
+
+`engine/shared.js → resolveSpawnPaths(project, type, MINIONS_DIR)` decides
+what the agent's `cwd` is:
+
+- **Read-only types** (`meeting`, `ask`, `explore`, `plan-to-prd`, `plan`)
+  → `cwd = project.localPath` (the operator's main checkout — sees
+  uncommitted files).
+- **Code-mutating types** (`implement`, `fix`, `review`, `test`, `verify`,
+  `decompose`, `docs`) → `cwd = <worktree>` (a fresh `git worktree add`
+  checked out at branch tip — only sees committed files).
+
+Cwd routing matters because every CLI's native discovery is **rooted at
+cwd**. Project-scope skills like `<repo>/.claude/skills/foo/SKILL.md` are
+loaded by the CLI only if `<cwd>/.claude/skills/foo/SKILL.md` exists at
+spawn time. See *The worktree-uncommitted footgun* below.
+
+Live-checkout mode (`project.worktreeMode: 'live'`) collapses both branches
+to `cwd = project.localPath` for every dispatch type, so the agent sees
+the operator's working tree as-is (including uncommitted assets). The
+tradeoff is single-mutating-dispatch concurrency per project — see
+`docs/live-checkout-mode.md`.
+
+### 3. `--add-dir` (`engine/spawn-agent.js → computeAddDirs`)
+
+`computeAddDirs({ runtime, minionsDir, homeDir })` builds the list of
+absolute dirs the CLI is allowed to read **outside** its cwd. The current
+list:
+
+1. `minionsDir` — always first, so playbooks, system prompt, and skill
+   index are reachable from any worktree.
+2. Every existing dir returned by `runtime.getUserAssetDirs({ homeDir })`
+   for the resolved runtime — e.g. `~/.claude` + `~/.agents` for Claude,
+   `~/.copilot` + `~/.agents` for Copilot, `~/.codex` + `~/.agents` for
+   Codex.
+
+Non-existent dirs are dropped (Claude CLI rejects unknown `--add-dir`
+entries) and the list is deduped by resolved path.
+
+`--add-dir` is the **only** mechanism today that crosses the worktree
+boundary. It does not (yet) cover project-local-but-uncommitted assets —
+that's plan item #5 (`harnessPropagateProjectLocal`).
+
+### 4. MCP suppression flags
+
+Two flags strip otherwise-inherited MCP / instruction surfaces; everything
+else flows through implicitly because the CLI reads its native config on
+every spawn:
+
+- `engine.copilotDisableBuiltinMcps` (default `true`) → `--disable-builtin-mcps`
+  on Copilot. Strips Copilot's built-in `github-mcp-server` so dispatched
+  agents do not try to open a parallel PR through the bundled MCP while
+  Minions is already managing the PR via the host integration.
+- `engine.copilotSuppressAgentsMd` (default `true`) → `--no-custom-instructions`
+  on Copilot. Strips project `AGENTS.md` auto-load so Minions playbook
+  prompts are not silently overridden by repo-local instructions.
+
+There is no equivalent flag for stripping user-level skills, user-level
+slash commands, or user-level MCPs. The current posture is "always inherit"
+— `engine.hermeticHarness` (P-49e1c8b7, default `false`) is the per-fleet /
+per-agent opt-out. When TRUE:
+
+- `--add-dir` collapses to exactly `[minionsDir]` — every dir from
+  `runtime.getUserAssetDirs({ homeDir })` is dropped.
+- `harnessPropagateProjectLocal` is skipped — no `--project-harness-dir`
+  flags emitted.
+- `claudePreApproveWorkspaceMcps` is skipped — workspace `.mcp.json`
+  servers are not pre-approved in `~/.claude.json`.
+
+The flag is **independent** of `copilotDisableBuiltinMcps` and
+`copilotSuppressAgentsMd` — those keep their existing semantics so an
+operator can run hermetic Claude *and* keep Copilot's built-in MCPs off
+or AGENTS.md auto-load suppressed without re-thinking each lever. Per-agent
+override at `agent.hermeticHarness` (resolved via
+`shared.resolveAgentHermeticHarness(agent, engine)`, mirrors
+`shared.resolveAgentBareMode`).
+
+## The worktree-uncommitted footgun
+
+The single biggest behavioral wrinkle for new contributors:
+
+1. The operator drops an experimental skill at
+   `<repo>/.claude/skills/bar/SKILL.md` on their main checkout.
+2. The skill works fine when invoked by hand:
+   `cd <repo>; claude "use the bar skill"` — Claude's auto-discovery
+   sees it because cwd is the main checkout.
+3. The operator dispatches an `implement` work item against the same repo.
+4. The engine runs `git worktree add <wt> origin/<branch>` (uncommitted
+   files do not appear in a fresh worktree), then spawns the agent with
+   `cwd = <wt>`.
+5. Claude's discovery now happens at `<wt>` — `.claude/skills/bar/` is
+   absent. The agent silently underperforms with no error message.
+
+Read-only dispatch types (`meeting`, `ask`, `explore`, `plan-to-prd`,
+`plan`) do **not** hit this footgun, because their cwd is
+`project.localPath`. Mutating types do.
+
+`--add-dir` is not currently extended to cover this case (plan item #5),
+so the only workarounds today are:
+
+- **Commit it.** The skill becomes visible to every dispatch and every
+  teammate, with the usual reviewability tradeoff.
+- **Move it user-scope.** Drop it under `~/.claude/skills/bar/` instead —
+  the CLI's user-skill discovery still works inside a worktree because
+  `--add-dir` attaches `~/.claude`.
+- **Flip to live-checkout mode.** Set `project.worktreeMode = 'live'` on
+  the project so every dispatch runs in `project.localPath`. Caveats in
+  `docs/live-checkout-mode.md`.
+
+The dashboard tooling page does not yet surface this gap; that's plan
+item #8 ("Harness diagnostics" panel). Until then, run
+`minions doctor --harness` to get the per-runtime view of which dirs the
+engine actually surfaces, and check that flagged "missing" entries
+actually match the assets you expected to inherit.
+
+## `minions doctor --harness`
+
+One-shot CLI diagnostic that prints, per registered runtime, every dir
+or file the engine would surface to a spawned agent under its scope label.
+Implemented in `engine/preflight.js → runHarnessDoctor(minionsHome)` and
+wired into `bin/minions.js` and `engine/cli.js` as the `--harness` mode
+of the existing `minions doctor` command.
+
+### What it prints
+
+```
+Minions Harness Propagation
+  Runtime: claude
+    User asset dirs (--add-dir to agents):
+      ✓ /home/you/.claude                                [user]
+      ✓ /home/you/.agents                                [user]
+    Skill roots (CLI native discovery):
+      ✓ /home/you/.claude/skills                         [user]
+      ✓ /home/you/.agents/skills                         [user]
+      ⚠ /repo/.claude/skills                             [project:myrepo]   (missing on disk)
+      ✓ /repo/.agents/skills                             [project:myrepo]
+    Skill write targets (auto-extract destinations):
+      ✓ /home/you/.claude/skills                         [personal]
+      ✓ /repo/.claude/skills                             [project:myrepo]
+  Runtime: copilot
+    User asset dirs (--add-dir to agents):
+      ✓ /home/you/.copilot                               [user]
+      ✓ /home/you/.agents                                [user]
+    …
+  Worktree --add-dir snapshot (engine fleet default: copilot):
+    ✓ /home/you/.minions                                 [minions]
+    ✓ /home/you/.copilot                                 [user]
+    ✓ /home/you/.agents                                  [user]
+  All harness paths surveyed. Missing on-disk paths are warnings, not failures —
+  they're listed so you can decide whether to create the dir, populate it, or
+  ignore it for this host.
+```
+
+### Exit behavior
+
+The command exits **0 on a healthy host** even if some scoped paths do
+not exist on disk. The whole point is to surface "what would the engine
+attach today?" — a user that does not run Codex may legitimately have
+no `~/.codex` dir, and that is not a failure. Exits non-zero only on a
+true runtime/config error (e.g. registry refuses to resolve a known
+runtime, or `config.json` is unparseable).
+
+### When to run it
+
+- After installing a new skill / command / MCP and "it didn't take" on
+  the next dispatched agent — confirm Minions actually surfaces that dir
+  for the runtime you're dispatching with.
+- After changing `engine.defaultCli` — different runtimes have different
+  asset dirs; the `Worktree --add-dir snapshot` block reflects the fleet
+  default.
+- After re-cloning a repo with `<repo>/.claude/skills/` — the diagnostic
+  shows whether the project-scope path is on disk.
+- Before reporting "agent ignored my skill" — half the time the answer is
+  visible in the diagnostic output.
+
+It does **not** check whether the assets *load successfully* inside the
+CLI (no parse of `SKILL.md`, no MCP handshake). For loadability,
+inspect the dashboard tooling page or run an `ask` dispatch and watch
+the live output.
+
+## Adapter contract summary
+
+The runtime adapters answer these questions. The engine never special-cases
+a runtime by name — it only calls these methods on the resolved adapter.
+
+| Method | Signature | Used by |
+|--------|-----------|---------|
+| `getUserAssetDirs({ homeDir })` | → `string[]` | `engine/spawn-agent.js → computeAddDirs`; `runHarnessDoctor` |
+| `getSkillRoots({ homeDir, project? })` | → `[{ scope, dir, projectName? }]` | `engine/queries.js → collectSkillFiles`; `runHarnessDoctor` |
+| `getSkillWriteTargets({ homeDir, project? })` | → `{ personal, project? }` | `engine/lifecycle.js → extractSkillsFromOutput`; `runHarnessDoctor` |
+| `getCommandRoots({ homeDir, project? })` | → `[{ scope, dir, projectName? }]` | `engine/queries.js → collectCommandFiles` (via `getProjectHarnesses` for project scope); `runHarnessDoctor` |
+| `getMcpConfigPaths({ homeDir, project? })` | → `[{ scope, file, projectName? }]` | `runHarnessDoctor`; planned: `engine/queries.js → getStatusSlowStateMtimePaths` |
+
+`runHarnessDoctor` renders all five surfaces as "Slash commands" and "MCP
+config files" sections alongside the existing User asset dirs / Skill
+roots / Skill write targets blocks. Adapters that don't yet have a stable
+CLI contract for a surface (today: Codex for both commands and MCP,
+Copilot for project-scope commands) return `[]` so consumers can iterate
+runtimes generically without per-runtime branching.
+
+`engine/queries.js` exposes two shared helpers — `getUserHarnesses(homeDir)`
+and `getProjectHarnesses(project)` — that iterate every registered runtime
+via `engine/runtimes.listRuntimes()` + `resolveRuntime()` and union the
+`getSkillRoots` / `getCommandRoots` / `getMcpConfigPaths` contributions,
+deduped by absolute path. The same physical dir contributed by multiple
+adapters (e.g. `~/.agents/skills` exposed by Claude, Copilot, and Codex)
+surfaces once with a `runtimes: [name, ...]` provenance array. Use them
+from dashboard / diagnostics consumers instead of re-walking adapters by
+hand; `collectSkillFiles` / `collectCommandFiles` already do.
+
+> **Follow-up.** `getStatusSlowStateMtimePaths` still hardcodes the
+> per-runtime MCP file paths; refactoring it to consume
+> `getUserHarnesses(...).mcps` + `getProjectHarnesses(...).mcps` is
+> tracked separately so the slow-state mtime tracker automatically picks
+> up new adapters.
+
+## Related docs
+
+- `docs/runtime-adapters.md` — full adapter interface table.
+- `docs/live-checkout-mode.md` — `project.worktreeMode: 'live'`
+  contract (alternative to the worktree-add-dir story for repos where
+  worktrees are unworkable).
+- `docs/skills.md` — skill block format and auto-extraction targets.
+- `plans/seamless-user-repo-harness-invocation.md` — full multi-item plan
+  this doc is the foundation of.
+- `CLAUDE.md` → "Agent Spawn" + "Adapter Contract" — load-bearing
+  invariants the propagation contract piggy-backs on.

package/docs/human-vs-automated.md

@@ -15,7 +15,7 @@
 | Metrics | Engine (auto-collect) | Engine | You (view) | — |
 | Error recovery | Engine (detect) | — | You (retry/delete) | You |
 | Project linking | You (`minions add/scan`) | — | — | — |
-| MCP servers | You (`~/.claude.json`) | Inherited by agents | — | — |
+| MCP servers / Skills / Commands | You (native CLI config) | Inherited by agents | — | — (opt-out via `hermeticHarness`) |
 
 ## The Two Human Gates
 

package/docs/runtime-adapters.md

@@ -174,6 +174,11 @@ user sees outside Minions. The cross-runtime portable location
 `~/.agents/skills` is included by every adapter that opts into it (Copilot today;
 add it to new adapters when the runtime can read directly from there).
 
+For a full per-runtime survey of which dirs the engine actually surfaces today
+— grouped by scope label and with on-disk-missing flags — run
+`minions doctor --harness`; the diagnostic and the propagation contract it
+codifies are documented in [`docs/harness-propagation.md`](./harness-propagation.md).
+
 ## The "No Runtime-Name Branching" Rule
 
 The whole point of this layer: **engine code MUST gate behavior on

package/engine/cli.js

@@ -247,8 +247,8 @@ const CLI_COMMAND_DOCS = Object.freeze({
   kill:       { args: '',                      summary: 'Kill all active agents, reset to pending' },
   complete:   { args: '<dispatch-id>',         summary: 'Mark a dispatch as done' },
   cleanup:    { args: '',                      summary: 'Clean temp files, worktrees, zombies' },
-  'mcp-sync': { args: '',                      summary: 'Sync MCP servers from ~/.claude.json' },
-  doctor:     { args: '',                      summary: 'Check prerequisites and runtime health' },
+  'mcp-sync': { args: '',                      summary: 'Print harness propagation diagnostic (same source as `minions doctor --harness`; read-only, no writes)' },
+  doctor:     { args: '[--harness]',           summary: 'Check prerequisites and runtime health (--harness: print harness propagation diagnostic)' },
   config:     { args: 'set-cli <R> [--model M]', summary: 'Persist defaultCli/defaultModel without starting' },
   pr:         { args: 'comment <repo> <prNumber> --agent <id> --kind <k> [--wi <id>] [--body-file <f>|--body <text>]', summary: 'Post a marker-prepended PR comment via gh' },
   bridge:     { args: 'status|health|enable|disable',         summary: 'Constellation bridge: toggle and inspect the read-only cross-repo feed' },
@@ -1356,6 +1356,7 @@ const commands = {
     const flagFields = [
       'claudeBareMode', 'claudeFallbackModel',
       'copilotDisableBuiltinMcps', 'copilotSuppressAgentsMd', 'copilotStreamMode', 'copilotReasoningSummaries',
+      'harnessPropagateProjectLocal', 'claudePreApproveWorkspaceMcps', 'hermeticHarness',
       'maxBudgetUsd', 'disableModelDiscovery',
       'ccUseWorkerPool',
     ];
@@ -1854,11 +1855,29 @@ const commands = {
   },
 
   'mcp-sync'() {
-    console.log('MCP servers are read directly from ~/.claude.json — no sync needed.');
+    // P-90a37c52 — repurposed as a harness diagnostic printer. Same source
+    // as `minions doctor --harness` (engine/preflight.js → runHarnessDoctor)
+    // but stays exit 0 regardless of the diagnostic's hardError signal, so
+    // callers that scripted around the legacy `mcp-sync` (which was a pure
+    // print + exit 0) don't have their automation flipped. For an exit
+    // code that reflects harness health, use `minions doctor --harness`.
+    //
+    // Stays a no-op: no writes to ~/.claude.json, no state mutation. The
+    // legacy "Sync MCP servers from ~/.claude.json — no sync needed."
+    // message is replaced by the structured per-runtime propagation survey.
+    const { runHarnessDoctor } = require('./preflight');
+    runHarnessDoctor(MINIONS_DIR);
   },
 
-  doctor() {
-    const { doctor } = require('./preflight');
+  doctor(...doctorArgs) {
+    const { doctor, runHarnessDoctor } = require('./preflight');
+    if (doctorArgs.includes('--harness')) {
+      // P-a3f9b2c1 — harness propagation diagnostic. See
+      // docs/harness-propagation.md and the parallel branch in bin/minions.js.
+      const ok = runHarnessDoctor(MINIONS_DIR);
+      if (!ok) process.exit(1);
+      return;
+    }
     return doctor(MINIONS_DIR).then(ok => {
       if (!ok) process.exit(1);
     });

package/engine/diagnostics-memory.js

@@ -0,0 +1,190 @@
+/**
+ * engine/diagnostics-memory.js — In-process memory + event-loop + GC sampler.
+ *
+ * P-a1b2c3d4 (memory + perf audit plan). Importable from both engine.js and
+ * dashboard.js — each Node process gets its own module-scope state (event-loop
+ * histogram, GC counters, ring buffer). No I/O; persistence is the caller's
+ * responsibility (see P-b2c3d4e5).
+ *
+ * Exports:
+ *   - sampleSelf({ label }) → snapshot object with RSS / heap / event-loop /
+ *     GC counters / pid / uptime / capturedAt.
+ *   - getHistory({ limit }) → up-to-`limit` samples from the ring buffer
+ *     (oldest first), defaults to all 1440.
+ *   - recordSample(sample) → append to the ring buffer; rotates at the cap.
+ *   - startPeriodicSampling({ intervalMs, onSample }) → setInterval-driven
+ *     sampler; returns a stop() function. Dashboard.js uses this on boot;
+ *     engine.js drives sampling from its own tick instead.
+ *
+ * Zero deps — all Node built-ins. The event-loop histogram is a
+ * `monitorEventLoopDelay({ resolution: 20 })` singleton lazily enabled on the
+ * first `sampleSelf()` call. The PerformanceObserver subscribes to
+ * `entryTypes: ['gc']` and accumulates pause times into module-scope counters.
+ */
+
+const v8 = require('v8');
+const { monitorEventLoopDelay, PerformanceObserver, constants } = require('perf_hooks');
+
+const RING_BUFFER_CAP = 1440;
+const HISTOGRAM_RESOLUTION_MS = 20;
+const NS_PER_MS = 1e6;
+
+const ringBuffer = [];
+
+let eventLoopHistogram = null;
+let gcObserver = null;
+let gcPausesTotalMs = 0;
+let gcCount = 0;
+let lastGcPauseMs = 0;
+let lastGcKind = null;
+
+const GC_KIND_NAMES = {
+  [constants.NODE_PERFORMANCE_GC_MAJOR]: 'major',
+  [constants.NODE_PERFORMANCE_GC_MINOR]: 'minor',
+  [constants.NODE_PERFORMANCE_GC_INCREMENTAL]: 'incremental',
+  [constants.NODE_PERFORMANCE_GC_WEAKCB]: 'weakcb',
+};
+
+function _ensureHistogramStarted() {
+  if (eventLoopHistogram) return eventLoopHistogram;
+  eventLoopHistogram = monitorEventLoopDelay({ resolution: HISTOGRAM_RESOLUTION_MS });
+  eventLoopHistogram.enable();
+  return eventLoopHistogram;
+}
+
+function _ensureGcObserverStarted() {
+  if (gcObserver) return gcObserver;
+  gcObserver = new PerformanceObserver((list) => {
+    for (const entry of list.getEntries()) {
+      // entry.duration is in ms (fractional). entry.kind / entry.detail.kind
+      // is the numeric NODE_PERFORMANCE_GC_* constant.
+      const pauseMs = Number(entry.duration) || 0;
+      gcPausesTotalMs += pauseMs;
+      gcCount += 1;
+      lastGcPauseMs = pauseMs;
+      const kindNum = (entry.detail && entry.detail.kind) || entry.kind || null;
+      lastGcKind = (kindNum != null && GC_KIND_NAMES[kindNum]) || (kindNum != null ? String(kindNum) : null);
+    }
+  });
+  gcObserver.observe({ entryTypes: ['gc'], buffered: false });
+  // Don't keep the event loop alive just to observe GC.
+  if (typeof gcObserver.unref === 'function') gcObserver.unref();
+  return gcObserver;
+}
+
+function _nsToMs(ns) {
+  if (!Number.isFinite(ns) || ns <= 0) return 0;
+  return ns / NS_PER_MS;
+}
+
+function _readEventLoopLag(hist) {
+  // hist.percentile(p) throws when the histogram is empty (no recorded
+  // samples yet). Guard so the first sampleSelf() call after process start
+  // returns zeros instead of throwing.
+  let p50 = 0, p99 = 0, max = 0;
+  try {
+    if (hist && typeof hist.percentile === 'function') {
+      const c = typeof hist.count === 'number' ? hist.count : (hist.totalCount || 0);
+      if (c > 0) {
+        p50 = _nsToMs(hist.percentile(50));
+        p99 = _nsToMs(hist.percentile(99));
+        max = _nsToMs(hist.max);
+      }
+    }
+  } catch {
+    // Empty / not-yet-populated histogram. Leave zeros.
+  }
+  return { p50, p99, max };
+}
+
+function sampleSelf({ label = null } = {}) {
+  const hist = _ensureHistogramStarted();
+  _ensureGcObserverStarted();
+
+  const mem = process.memoryUsage();
+  const heap = v8.getHeapStatistics();
+  const lag = _readEventLoopLag(hist);
+
+  return {
+    rss: mem.rss,
+    heapUsed: mem.heapUsed,
+    heapTotal: mem.heapTotal,
+    external: mem.external,
+    arrayBuffers: mem.arrayBuffers || 0,
+    heapSizeLimit: heap.heap_size_limit,
+    eventLoopLagP50: lag.p50,
+    eventLoopLagP99: lag.p99,
+    eventLoopLagMax: lag.max,
+    lastGcPauseMs,
+    lastGcKind,
+    gcPausesTotalMs,
+    gcCount,
+    uptime: process.uptime(),
+    pid: process.pid,
+    label,
+    capturedAt: Date.now(),
+  };
+}
+
+function recordSample(sample) {
+  if (!sample || typeof sample !== 'object') return;
+  ringBuffer.push(sample);
+  while (ringBuffer.length > RING_BUFFER_CAP) ringBuffer.shift();
+}
+
+function getHistory({ limit } = {}) {
+  const n = ringBuffer.length;
+  if (!Number.isInteger(limit) || limit <= 0 || limit >= n) {
+    return ringBuffer.slice();
+  }
+  return ringBuffer.slice(n - limit);
+}
+
+function startPeriodicSampling({ intervalMs = 60000, onSample = null } = {}) {
+  if (!Number.isFinite(intervalMs) || intervalMs <= 0) {
+    throw new Error('startPeriodicSampling: intervalMs must be a positive number');
+  }
+  const handle = setInterval(() => {
+    let sample;
+    try {
+      sample = sampleSelf({ label: 'periodic' });
+    } catch {
+      return;
+    }
+    recordSample(sample);
+    if (typeof onSample === 'function') {
+      try { onSample(sample); } catch { /* swallow — sampler must not crash on callback errors */ }
+    }
+  }, intervalMs);
+  if (typeof handle.unref === 'function') handle.unref();
+  return function stop() {
+    clearInterval(handle);
+  };
+}
+
+function _resetForTest() {
+  ringBuffer.length = 0;
+  if (eventLoopHistogram && typeof eventLoopHistogram.disable === 'function') {
+    try { eventLoopHistogram.disable(); } catch {}
+  }
+  eventLoopHistogram = null;
+  if (gcObserver && typeof gcObserver.disconnect === 'function') {
+    try { gcObserver.disconnect(); } catch {}
+  }
+  gcObserver = null;
+  gcPausesTotalMs = 0;
+  gcCount = 0;
+  lastGcPauseMs = 0;
+  lastGcKind = null;
+}
+
+module.exports = {
+  sampleSelf,
+  getHistory,
+  recordSample,
+  startPeriodicSampling,
+  // Constants for callers that need to know the cap up front.
+  RING_BUFFER_CAP,
+  // exported for testing
+  _resetForTest,
+};

package/engine/lifecycle.js

@@ -915,9 +915,30 @@ function syncPrsFromOutput(output, agentId, meta, config, opts = {}) {
     (projects.length === 1 ? projects[0] : null);
   const useCentral = !defaultProject;
 
-  // Match each PR to its correct project by finding which repo URL appears near the PR number in output
+  // Match each PR to its correct project. W-mqba5ulq000nd255 — primary
+  // strategy is canonical scope: parse the evidence URL into a host scope
+  // (e.g. `github:opg-microsoft/minions`) and find the configured project
+  // whose `getProjectPrScope` matches. This routes the record into the
+  // correctly-scoped project file even when the dispatching agent ran
+  // against a different project (the cross-project PR case that previously
+  // produced stale `_invalidProjectScope` stubs in the wrong file). Falls
+  // back to the legacy substring match (handles legacy non-canonical
+  // configs), then to a repoName-by-_git fallback, then to the dispatching
+  // project (which will get the `_invalidProjectScope` stamp via
+  // normalizePrRecord — preserving today's tracking behavior for orphan /
+  // unknown-owner URLs).
   function resolveProjectForPr(prId) {
     const evidenceUrl = prEvidence.get(prId) || '';
+    // Scope match wins. Use the most-specific URL available: prefer the
+    // direct evidence URL captured alongside the PR id; fall back to the
+    // generic stdout scan if that's empty.
+    const urlScope = shared.getPrScopeInfo(null, evidenceUrl)?.scope || '';
+    if (urlScope) {
+      for (const p of projects) {
+        const projScope = shared.getProjectPrScope(p);
+        if (projScope && projScope === urlScope) return p;
+      }
+    }
     const evidenceText = `${outputText}\n${evidenceUrl}`;
     for (const p of projects) {
       if (!p.prUrlBase) continue;
@@ -5474,6 +5495,94 @@ function diagnoseEmptyOutput(failureClass, code, elapsedMs) {
   return `[empty-output: process exited in ${elapsedMs}ms \u2014 possible causes: machine sleep, network unavailability, auth failure]`;
 }
 
+// W-mqba5ulq000nd255 — Reconciliation sweep: delete PR records flagged with
+// `_invalidProjectScope: { reason: "pr_scope_mismatch" }` IFF a sibling
+// record for the same canonical pr.id exists in another project whose scope
+// matches the PR URL (i.e. the correctly-scoped project owns the canonical
+// record). Sibling-less mismatches are preserved as tracking. Runs once per
+// tick from engine.js after the ADO/GitHub reconcile polls finish.
+//
+// Returns { pruned, scanned } so the engine tick can log a summary line.
+function pruneScopeMismatchDuplicatePrs(config) {
+  config = config || getConfig();
+  const projects = shared.getProjects(config) || [];
+  if (projects.length === 0) return { pruned: 0, scanned: 0 };
+
+  // Map project name -> canonical scope so we can find which project IS the
+  // correctly-scoped owner for a given mismatch record.
+  const scopeByProject = new Map();
+  const projectByScope = new Map();
+  for (const p of projects) {
+    if (!p || !p.name) continue;
+    const sc = shared.getProjectPrScope(p);
+    if (!sc) continue;
+    scopeByProject.set(p.name, sc);
+    projectByScope.set(sc, p);
+  }
+
+  // Index all PRs by canonical id across all projects (post-_scope decoration).
+  const store = require('./pull-requests-store');
+  const allPrs = store.readAllPullRequests() || [];
+  const byId = new Map();
+  for (const pr of allPrs) {
+    if (!pr || !pr.id) continue;
+    if (!byId.has(pr.id)) byId.set(pr.id, []);
+    byId.get(pr.id).push(pr);
+  }
+
+  // Build per-project delete sets keyed by id, so we batch one mutation per
+  // affected project file.
+  const deletesByProject = new Map(); // projectName -> Set(prId)
+  let scanned = 0;
+  let pruned = 0;
+
+  for (const records of byId.values()) {
+    if (records.length < 2) continue;
+    for (const rec of records) {
+      scanned++;
+      if (!rec._invalidProjectScope || rec._invalidProjectScope.reason !== 'pr_scope_mismatch') continue;
+      const correctScope = rec._invalidProjectScope.prScope;
+      if (!correctScope) continue;
+      const correctProject = projectByScope.get(correctScope);
+      if (!correctProject) continue; // no configured project owns the URL — keep as tracking
+      // Sibling check: is there a record under the correct scope for the same id?
+      const sibling = records.find(r => r !== rec && r._scope === correctProject.name);
+      if (!sibling) continue;
+      // Safe to prune.
+      const owningScope = rec._scope;
+      if (!owningScope || owningScope === 'central') continue;
+      if (!deletesByProject.has(owningScope)) deletesByProject.set(owningScope, new Set());
+      deletesByProject.get(owningScope).add(rec.id);
+    }
+  }
+
+  if (deletesByProject.size === 0) return { pruned: 0, scanned };
+
+  for (const [projectName, idsToDelete] of deletesByProject) {
+    const project = projects.find(p => p.name === projectName);
+    if (!project) continue;
+    const prPath = projectPrPath(project);
+    try {
+      shared.mutatePullRequests(prPath, (prs) => {
+        const before = prs.length;
+        const next = prs.filter(p => !idsToDelete.has(p?.id));
+        const deleted = before - next.length;
+        if (deleted > 0) {
+          pruned += deleted;
+          for (const id of idsToDelete) {
+            log('info', `[pull-requests] pruned scope-mismatch duplicate ${id} from project=${projectName} (sibling exists in correctly-scoped project)`);
+          }
+        }
+        return next;
+      });
+    } catch (err) {
+      log('warn', `pruneScopeMismatchDuplicatePrs: failed to mutate ${projectName}: ${err?.message || err}`);
+    }
+  }
+
+  return { pruned, scanned };
+}
+
 module.exports = {
   checkPlanCompletion,
   archivePlan,
@@ -5482,6 +5591,7 @@ module.exports = {
   syncPrdItemStatus,
   reconcilePrdStatuses,
   syncPrsFromOutput,
+  pruneScopeMismatchDuplicatePrs,
   updatePrAfterReview,
   updatePrAfterFix,
   updatePrAfterFixError,