@yemi33/minions 0.1.2178 → 0.1.2179

package/dashboard-build.js

@@ -21,9 +21,24 @@ function buildDashboardHtml() {
   const css = safeRead(path.join(dashDir, 'styles.css'));
 
   const pages = ['home', 'work', 'prs', 'plans', 'inbox', 'tools', 'schedule', 'watches', 'pipelines', 'meetings', 'qa', 'engine'];
+  // Sub-fragments substituted into a parent page at assembly time via
+  // <!-- __MARKER__ --> tokens. Lets large panels live in their own
+  // fragment file without inflating the parent page. P-d4e5f6a7 introduced
+  // engine-memory-panel.html as the first such sub-fragment; add more here
+  // by mapping marker -> fragment basename.
+  const pageSubFragments = {
+    engine: { '<!-- __ENGINE_MEMORY_PANEL__ -->': 'engine-memory-panel' },
+  };
   let pageHtml = '';
   for (const p of pages) {
-    const content = safeRead(path.join(dashDir, 'pages', p + '.html'));
+    let content = safeRead(path.join(dashDir, 'pages', p + '.html'));
+    const subs = pageSubFragments[p];
+    if (subs) {
+      for (const [marker, basename] of Object.entries(subs)) {
+        const fragment = safeRead(path.join(dashDir, 'pages', basename + '.html'));
+        content = content.replace(marker, () => fragment);
+      }
+    }
     const activeClass = p === 'home' ? ' active' : '';
     pageHtml += `    <div class="page${activeClass}" id="page-${p}">\n${content}\n    </div>\n\n`;
   }
@@ -32,7 +47,7 @@ function buildDashboardHtml() {
     'utils', 'state', 'features-client', 'render-utils', 'detail-panel', 'live-stream',
     'render-agents', 'render-dispatch', 'render-work-items', 'render-prd',
     'render-prs', 'render-plans', 'render-inbox', 'render-kb', 'render-skills',
-    'render-other', 'render-managed', 'render-schedules', 'render-watches', 'render-pipelines', 'render-meetings', 'render-pinned',
+    'render-other', 'render-managed', 'memory-panel', 'render-schedules', 'render-watches', 'render-pipelines', 'render-meetings', 'render-pinned',
     'command-parser', 'command-input', 'command-center', 'command-history',
     'confirm-dialog', 'modal', 'modal-qa', 'settings', 'qa', 'fre', 'refresh'
   ];

package/dashboard.js

@@ -43,6 +43,7 @@ const steeringStore = require('./engine/steering-store');
 const projectDiscovery = require('./engine/project-discovery');
 const features = require('./engine/features');
 const ccWorkerPool = require('./engine/cc-worker-pool');
+const diagnosticsMemory = require('./engine/diagnostics-memory');
 const os = require('os');
 
 const { safeRead, safeReadOrNull, safeReadDir, safeWrite, safeJson, safeJsonObj, safeJsonArr, safeJsonNoRestore, safeUnlink, mutateJsonFileLocked, mutateTextFileLocked, mutateControl, mutateCooldowns, mutateWorkItems, getProjects: _getProjects, DONE_STATUSES, WI_STATUS, WORK_TYPE, WORKTREE_REQUIRING_TYPES, reopenWorkItem } = shared;
@@ -104,6 +105,75 @@ const KB_PINS_PATH = shared.PINNED_ITEMS_PATH;
 const DASHBOARD_BROWSER_PRESENCE_PATH = path.join(ENGINE_DIR, 'dashboard-browser.json');
 const DASHBOARD_BROWSER_PRESENCE_MAX_AGE_MS = 45000;
 
+// P-c3d4e5f6 — diagnostics-memory dashboard surface.
+// The engine writes its latest sample to engine/diagnostics-memory.json on
+// every memoryBaselineEveryTicks ticks; the dashboard reads it for
+// /api/diagnostics/memory and accumulates polled engine samples into its
+// own ring buffer (separate from diagnosticsMemory's own dashboard-self
+// buffer) for /api/diagnostics/memory/history?process=engine. Both rings
+// are in-process — restarting the dashboard zeroes them.
+const DIAGNOSTICS_MEMORY_SIDECAR_PATH = path.join(ENGINE_DIR, 'diagnostics-memory.json');
+const DIAGNOSTICS_MEMORY_STALE_MS = 5 * 60 * 1000;
+const DIAGNOSTICS_MEMORY_SAMPLE_INTERVAL_MS = 60000;
+const DIAGNOSTICS_MEMORY_ENGINE_RING_CAP = 1440;
+const _engineMemoryRing = [];
+let _lastEngineSampleCapturedAt = 0;
+let _memorySamplerStop = null;
+
+// Pure: assemble the /api/diagnostics/memory payload from already-read
+// inputs. Exported for direct unit testing — handler callers feed it the
+// live dashboard sample + the sidecar contents + Date.now().
+function _buildMemoryDiagnostics({ dashboardSample, engineSample, now } = {}) {
+  const _now = Number.isFinite(now) ? now : Date.now();
+  const dashboard = dashboardSample && typeof dashboardSample === 'object' ? dashboardSample : null;
+  // engineSample may be the literal object from the sidecar OR null/{} when
+  // the sidecar is missing/unparseable. Treat anything without a finite
+  // capturedAt as stale (covers both "file missing" and "ancient sample").
+  let engine = null;
+  let engineStale = true;
+  if (engineSample && typeof engineSample === 'object' && Number.isFinite(engineSample.capturedAt)) {
+    engine = engineSample;
+    engineStale = (_now - engineSample.capturedAt) > DIAGNOSTICS_MEMORY_STALE_MS;
+  }
+  return { dashboard, engine, engineStale };
+}
+
+// Pure: slice the requested ring buffer. Returns up to `limit` newest
+// samples (oldest first). `limit` defaults to the full buffer when missing
+// or non-positive (matches diagnosticsMemory.getHistory semantics).
+function _buildMemoryHistory({ ring, limit } = {}) {
+  if (!Array.isArray(ring)) return [];
+  const n = ring.length;
+  if (!Number.isInteger(limit) || limit <= 0 || limit >= n) return ring.slice();
+  return ring.slice(n - limit);
+}
+
+// Read the engine sidecar and, when it carries a never-seen-before
+// capturedAt, push it onto the engine-side ring buffer. Dedup is by
+// capturedAt so re-reads between engine baseline ticks don't bloat the
+// ring. Best-effort: any failure leaves the ring untouched.
+function _pollAndAccumulateEngineSample() {
+  let sample;
+  try { sample = safeJsonObj(DIAGNOSTICS_MEMORY_SIDECAR_PATH); }
+  catch { return; }
+  if (!sample || typeof sample !== 'object') return;
+  if (!Number.isFinite(sample.capturedAt)) return;
+  if (sample.capturedAt === _lastEngineSampleCapturedAt) return;
+  _lastEngineSampleCapturedAt = sample.capturedAt;
+  _engineMemoryRing.push(sample);
+  while (_engineMemoryRing.length > DIAGNOSTICS_MEMORY_ENGINE_RING_CAP) _engineMemoryRing.shift();
+}
+
+function _resetDiagnosticsMemoryForTesting() {
+  _engineMemoryRing.length = 0;
+  _lastEngineSampleCapturedAt = 0;
+  if (_memorySamplerStop) {
+    try { _memorySamplerStop(); } catch { /* ignore */ }
+    _memorySamplerStop = null;
+  }
+  try { diagnosticsMemory._resetForTest(); } catch { /* ignore */ }
+}
+
 function ensureConfiguredProjectStateFiles() {
   for (const p of PROJECTS) {
     const root = p.localPath ? path.resolve(p.localPath) : null;
@@ -387,6 +457,25 @@ function inferActionPrRecord(action, prs, project = null) {
 }
 
 function copyWorkItemPrFields(item, input, pr = null) {
+  // W-mqbaby2a000pa8ee: Gate the LOOSE description/title scan in
+  // `shared.extractWorkItemPrRef` on `type: "fix"`. Without this gate,
+  // an implement/explore/test WI that merely mentions an existing PR
+  // in prose ("Class bug surfaced today on pull request 130") gets
+  // `targetPr` / `pr_id` / `prNumber` stamped, the engine then treats
+  // the WI as a fix against that PR, the PR-branch lookup fails, and
+  // the dispatch silently skips with `_pendingReason: null` forever.
+  //
+  // Structured PR pointers (`targetPr` / `pr_id` / `prUrl` / `prNumber` /
+  // `references[].url` / `meta.pr_followup.parent_pr_url`) are explicit
+  // operator intent — they stamp on EVERY type. An explicit `pr` record
+  // (caller already resolved the PR) also bypasses the gate. Only the
+  // last-resort description/title regex scan is type-gated.
+  if (!pr) {
+    const structuredRef = shared.extractStructuredWorkItemPrRef(input);
+    if (!structuredRef && String(item?.type || '').toLowerCase() !== WORK_TYPE.FIX) {
+      return;
+    }
+  }
   const prRef = getWorkItemPrRef(input);
   if (!prRef && !pr) return;
   const prNumber = pr ? shared.getPrNumber(pr) : shared.getPrNumber(prRef);
@@ -1958,6 +2047,7 @@ function _buildStatusSlowState() {
       const branchMismatch = !!(mainBranch && status.remoteDefaultBranch && mainBranch !== status.remoteDefaultBranch);
       return {
         name: p.name,
+        displayName: shared.projectDisplayName(p),
         path: p.localPath,
         description: p.description || '',
         ...status,
@@ -3497,13 +3587,25 @@ function getWorkItemPrRef(input) {
   // the dispatch to the existing PR branch instead of a fresh `work/<wi-id>`
   // parallel branch (issue #2999 / W-mpx6i5kh000ac040).
   //
-  // ASYMMETRY (W-mq18ec6h000p7b87): the engine's pr_not_found *gate* uses
-  // the strict `shared.extractStructuredWorkItemPrRef` — gate uses
-  // structured-only; stamp uses loose. Rationale: operators creating fix
-  // WIs via API often paste the PR URL in description prose and expect
-  // `targetPr` to get auto-stamped here (best-effort, reversible). The gate
-  // blocks dispatch and must require explicit operator intent (a structured
-  // field) before doing so.
+  // STRUCTURED-vs-LOOSE SPLIT (W-mq18ec6h000p7b87): two extractors exist —
+  //   - `shared.extractStructuredWorkItemPrRef`: structured fields +
+  //     `references[].url` + `meta.pr_followup.parent_pr_url`. NO scan.
+  //   - `shared.extractWorkItemPrRef` (this helper): structured walk + a
+  //     last-resort first-paragraph/title scan.
+  // The engine's `pr_not_found` dispatch gate uses the structured-only
+  // variant. The original design intent was that the stamp path could
+  // afford to be loose because gating would still require explicit
+  // operator intent.
+  //
+  // FIX-TYPE 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
+  // get stamped from structured fields (incl. references/follow-up).
+  // See the comment block on `copyWorkItemPrFields` above for details.
   return shared.extractWorkItemPrRef(input);
 }
 
@@ -9548,6 +9650,12 @@ What would you like to discuss or change? When you're happy, say "approve" and I
       for (const key of Object.keys(childEnv)) {
         if (key === 'CLAUDECODE' || key.startsWith('CLAUDE_CODE') || key.startsWith('CLAUDECODE_')) delete childEnv[key];
       }
+      // W-mqb9y83o — suppress auto-open in the respawned dashboard. The
+      // restart endpoint is fired by CC or the dashboard UI; the operator
+      // already has a tab open (that's how they hit the button), so the
+      // post-restart hook must not pop a second one. Hard kill-switch read
+      // by bin/minions.js#spawnFullStackAndVerify.
+      childEnv.MINIONS_NO_AUTO_OPEN = '1';
       const proc = cpSpawn(process.execPath, [minionsBin, 'restart'], {
         cwd: MINIONS_DIR, stdio: 'ignore', detached: true, env: childEnv, windowsHide: true,
       });
@@ -10121,6 +10229,58 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     } catch (e) { return jsonReply(res, e.statusCode || 500, { error: e.message }); }
   }
 
+  // P-c3d4e5f6 — /api/diagnostics/memory.
+  // Returns the latest in-process dashboard sample, the latest engine
+  // sample (read fresh from engine/diagnostics-memory.json via safeJsonObj),
+  // and an engineStale boolean. Engine staleness is true when the sidecar
+  // is missing/unparseable OR its capturedAt is > 5 min old. The handler
+  // does one small JSON read and one in-process sample — < 10ms warm.
+  function handleDiagnosticsMemory(req, res) {
+    try {
+      let dashboardSample = null;
+      try { dashboardSample = diagnosticsMemory.sampleSelf({ label: 'dashboard' }); }
+      catch { /* leave dashboardSample null on sampler failure */ }
+      const engineSample = safeJsonObj(DIAGNOSTICS_MEMORY_SIDECAR_PATH);
+      const payload = _buildMemoryDiagnostics({
+        dashboardSample,
+        engineSample,
+        now: Date.now(),
+      });
+      return jsonReply(res, 200, payload, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
+  // P-c3d4e5f6 — /api/diagnostics/memory/history?process=engine|dashboard&limit=N.
+  // process=dashboard returns the diagnosticsMemory module's own ring
+  // buffer (populated by startPeriodicSampling on dashboard boot).
+  // process=engine returns the dashboard's accumulated polled snapshots
+  // of engine/diagnostics-memory.json — engine.js only persists the
+  // latest sample to the sidecar, so engine-side history is rebuilt by
+  // the dashboard's poller (dedup by capturedAt). Limit defaults to the
+  // full buffer when missing / non-positive.
+  function handleDiagnosticsMemoryHistory(req, res) {
+    try {
+      const u = new URL(req.url, 'http://x');
+      const proc = (u.searchParams.get('process') || '').trim().toLowerCase();
+      const limitRaw = u.searchParams.get('limit');
+      const limitParsed = limitRaw == null || limitRaw === '' ? null : parseInt(limitRaw, 10);
+      const limit = Number.isInteger(limitParsed) && limitParsed > 0 ? limitParsed : null;
+      let samples;
+      if (proc === 'dashboard') {
+        samples = diagnosticsMemory.getHistory(limit ? { limit } : {});
+      } else if (proc === 'engine') {
+        samples = _buildMemoryHistory({ ring: _engineMemoryRing, limit });
+      } else {
+        return jsonReply(res, 400, { error: 'process must be one of: engine, dashboard' }, req);
+      }
+      return jsonReply(res, 200, { process: proc, count: samples.length, samples }, req);
+    } catch (e) {
+      return jsonReply(res, 500, { error: e.message }, req);
+    }
+  }
+
   // Slim UX surface for the experimental redesigned dashboard.
   // The markup/CSS/JS live as fragments under dashboard/slim/ (layout.html +
   // styles.css + body.html + js/*.js) and are assembled by buildSlimHtml() —
@@ -12497,6 +12657,9 @@ What would you like to discuss or change? When you're happy, say "approve" and I
     { method: 'POST', path: '/api/diagnostics/refresh', desc: 'Append a dashboard refresh-diagnostic ring buffer batch to engine/dashboard-diagnostics.log (rotated at 1 MB)', params: 'entries[]', handler: handleDiagnosticsRefresh },
     // Diagnostics — per-org ADO throttle state (W-mq03l6zh0006f0a1-d).
     { method: 'GET', path: '/api/diagnostics/ado-throttle', desc: 'Snapshot of per-org ADO throttle tracker state — { orgs: { [orgBase]: { throttled, retryAfter, consecutiveHits } } }. Falls back to a single `global` key when running against pre-per-org engines.', handler: handleDiagnosticsAdoThrottle },
+    // Diagnostics — engine + dashboard memory baseline (P-c3d4e5f6).
+    { method: 'GET', path: '/api/diagnostics/memory', desc: 'Latest in-process dashboard memory sample plus the most-recent engine sample read from engine/diagnostics-memory.json. engineStale=true when the sidecar is missing or its capturedAt is > 5 min old.', handler: handleDiagnosticsMemory },
+    { method: 'GET', path: '/api/diagnostics/memory/history', desc: 'In-memory ring buffer of memory samples. process=dashboard returns the dashboard\'s own collector (populated by startPeriodicSampling on boot). process=engine returns the dashboard\'s polled accumulation of engine/diagnostics-memory.json — engine.js only persists the latest sample to the sidecar, so engine-side history is rebuilt by the dashboard poller (dedup by capturedAt). Optional limit caps returned newest-N samples.', params: 'process (engine|dashboard), limit?', handler: handleDiagnosticsMemoryHistory },
   ];
 
   // ── Route Dispatcher ────────────────────────────────────────────────────────
@@ -12695,6 +12858,11 @@ module.exports = {
   refreshStatusAsync,
   handleStatus: _handleStatusRequest,
   invalidateStatusCache,
+  // exported for testing — see test/unit/status-snapshot-budget.test.js (P-f2a3b4c5).
+  // The slim snapshot builder is the synchronous assembler used by getStatusJson()
+  // and refreshStatusAsync(); the budget test calls it directly to measure byte
+  // size and rebuild-time without standing up an HTTP server.
+  getStatus,
   // Raw state-file passthrough — exported for direct unit testing.
   handleStateRead,
   STATE_READ_ALLOWED_DIRS,
@@ -12717,6 +12885,18 @@ module.exports = {
   // route's `builder` closure (getWorkItems().map(slimWorkItemForList)).
   _slimWorkItemForList: slimWorkItemForList,
   _WORK_ITEMS_SLIM_DESCRIPTION_CAP: WORK_ITEMS_SLIM_DESCRIPTION_CAP,
+  // P-c3d4e5f6 — diagnostics-memory dashboard surface (handlers live in
+  // the request-dispatch closure; expose the pure builders + constants so
+  // unit tests can exercise the staleness gate and history slicing
+  // without binding a server.)
+  _buildMemoryDiagnostics,
+  _buildMemoryHistory,
+  _pollAndAccumulateEngineSample,
+  _resetDiagnosticsMemoryForTesting,
+  DIAGNOSTICS_MEMORY_SIDECAR_PATH,
+  DIAGNOSTICS_MEMORY_STALE_MS,
+  DIAGNOSTICS_MEMORY_SAMPLE_INTERVAL_MS,
+  DIAGNOSTICS_MEMORY_ENGINE_RING_CAP,
 };
 
 // Start the HTTP server only when run directly (node dashboard.js).
@@ -12807,15 +12987,19 @@ if (require.main === module) {
     Promise.resolve(queries.getKnowledgeBaseEntries())
       .catch(err => console.warn(`[dashboard] KB cache warm failed: ${err && err.message}`));
 
-    // Auto-open the browser unless suppressed. `minions restart` and the
-    // upgrade path set MINIONS_NO_AUTO_OPEN=1 because the CLI orchestrates the
-    // open itself after observing whether an existing tab reconnected.
-    if (!process.env.MINIONS_NO_AUTO_OPEN) {
-      const result = shared.openUrlInBrowser(`http://localhost:${PORT}`);
-      if (!result.ok) {
-        console.log(`  Could not auto-open browser: ${result.error}`);
-        console.log(`  Please open http://localhost:${PORT} manually.`);
-      }
+    // Auto-open the browser. `minions restart` and the upgrade path set
+    // MINIONS_NO_AUTO_OPEN=1 because the CLI orchestrates the open itself
+    // after observing whether an existing tab reconnected; the primitive
+    // (engine/shared.js#openUrlInBrowser) now owns the env-var check and
+    // emits a debug-level SUPPRESSED log entry so we can prove the kill-
+    // switch is firing.
+    const result = shared.openUrlInBrowser(`http://localhost:${PORT}`, {
+      reason: 'dashboard-self-open',
+      callerHint: 'dashboard.js:13124',
+    });
+    if (!result.ok && !result.suppressed) {
+      console.log(`  Could not auto-open browser: ${result.error}`);
+      console.log(`  Please open http://localhost:${PORT} manually.`);
     }
 
     // Warm the CC runtime binary cache off the request path so the first CC /
@@ -12871,12 +13055,39 @@ if (require.main === module) {
       }
     }, 30000).unref();
     console.log(`  Engine watchdog: active (checks every 30s)`);
+
+    // ─── Diagnostics: dashboard memory sampler (P-c3d4e5f6) ─────────────────
+    // Drive the diagnosticsMemory ring buffer for /api/diagnostics/memory and
+    // /api/diagnostics/memory/history?process=dashboard. The internal
+    // setInterval already calls recordSample for us; the onSample callback
+    // doubles as the engine-sidecar poller so /…/history?process=engine
+    // accumulates one entry per fresh engine MEMORY_BASELINE write
+    // (deduplicated by capturedAt).
+    try {
+      _memorySamplerStop = diagnosticsMemory.startPeriodicSampling({
+        intervalMs: DIAGNOSTICS_MEMORY_SAMPLE_INTERVAL_MS,
+        onSample: () => { try { _pollAndAccumulateEngineSample(); } catch { /* swallow */ } },
+      });
+      // Seed the engine ring immediately so the first call to
+      // /api/diagnostics/memory/history?process=engine right after boot
+      // already returns the latest sidecar sample without waiting a full
+      // sampling interval.
+      try { _pollAndAccumulateEngineSample(); } catch { /* swallow */ }
+    } catch (e) {
+      console.warn(`[dashboard] memory sampler failed to start: ${e && e.message}`);
+    }
   })();
 
   // ── Graceful shutdown: flush debounced writes + clear runtime port file ──
   function _gracefulShutdown() {
     try { flushPendingDocSessions(); } catch {}
     try { shared.clearDashboardPortFile(MINIONS_DIR); } catch {}
+    // P-c3d4e5f6 — stop the diagnostics-memory sampler cleanly so the
+    // setInterval handle doesn't keep the event loop alive on SIGTERM.
+    if (_memorySamplerStop) {
+      try { _memorySamplerStop(); } catch { /* swallow */ }
+      _memorySamplerStop = null;
+    }
   }
   server.on('close', () => _gracefulShutdown());
   process.on('SIGTERM', () => { _gracefulShutdown(); process.exit(0); });

package/docs/branch-derivation.md

@@ -44,6 +44,18 @@ When a ref is detected, `copyWorkItemPrFields` stamps
 `targetPr` / `pr_id` / `prNumber`, `item.branch` is unset, and
 `discoverFromWorkItems` reuses the PR's source branch.
 
+**Type gate (W-mqbaby2a000pa8ee).** The loose description/title scan
+(step 4 above) only stamps on `type: "fix"` WIs. Non-fix WIs
+(implement / explore / test / review / …) only get stamped from
+structured fields (steps 1-3). Without this gate, an implement WI
+whose description merely mentions an existing PR in prose
+("Class bug surfaced today on pull request 130") would silently
+get `targetPr` / `pr_id` / `prNumber` stamped, route through the
+PR-fix dispatch path, fail the PR-branch lookup, and stick in
+`_pendingReason: null` forever. Structured intent
+(`targetPr` / `prUrl` / `references[].url` / etc.) still stamps on
+every type — only the loose regex scan is gated.
+
 ## Structured-vs-loose split (W-mq18ec6h000p7b87)
 
 The PR-ref extractor has **two** variants — pick the right one for the
@@ -52,7 +64,7 @@ call site:
 | Helper | What it walks | Used by | Why |
 |--------|---------------|---------|-----|
 | `shared.extractStructuredWorkItemPrRef(item)` | Structured fields + `references[*].url` + `meta.pr_followup.parent_pr_url`. **No** description / title scan. | `engine.js#getStructuredWorkItemPrRef` → `pr_not_found` dispatch gate. | Gating blocks dispatch and MUST require explicit operator intent. A description like "see PR #3015 for context" must NOT trip the gate. |
-| `shared.extractWorkItemPrRef(item)` | Structured walk + last-resort description / title scan. | `engine.js#getWorkItemPrRef` (branch derivation, prompt PR context, `resolveWorkItemPrRecord`); `dashboard.js#getWorkItemPrRef` (POST `/api/work-items` create-time `targetPr` stamping). | Callers downgrade gracefully when no PR record matches; stamp path preserves the operator UX of pasting a PR URL into description prose and getting `targetPr` auto-stamped. |
+| `shared.extractWorkItemPrRef(item)` | Structured walk + last-resort description / title scan. | `engine.js#getWorkItemPrRef` (branch derivation, prompt PR context, `resolveWorkItemPrRecord`); `dashboard.js#getWorkItemPrRef` (POST `/api/work-items` create-time `targetPr` stamping, **type-gated on `fix` — W-mqbaby2a000pa8ee**). | Callers downgrade gracefully when no PR record matches; stamp path preserves the operator UX of pasting a PR URL into description prose and getting `targetPr` auto-stamped on `type: "fix"` WIs. |
 
 **Rule of thumb: gate uses structured-only; stamp uses loose.**
 Stamping is best-effort and reversible; gating blocks dispatch and should

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,
+};