@geraldmaron/construct 1.4.2 → 1.5.1

package/lib/opencode-runtime-plugin.mjs

@@ -3,6 +3,8 @@
  *
  * Intercepts OpenCode session events (session.created, session.idle, session.error),
  * records each as a telemetry trace, and applies model fallback on rate-limit errors.
+ * Also flags model-attempted calls to tools OpenCode rejects as unavailable
+ * (construct-2q2m) into the shared tool-failures observation log.
  */
 import { existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from "node:fs";
 import { loadRegistry } from './registry/loader.mjs';
@@ -11,6 +13,7 @@ import { dirname, join, resolve } from "node:path";
 import { spawnSync } from "node:child_process";
 import { randomUUID } from "node:crypto";
 import { findOpenCodeConfigPath } from "./opencode-config.mjs";
+import { isPlaceholder } from "./providers/credential-sources.mjs";
 import { classifyProviderFailure, readCurrentModels, resolveExecutionContractModelMetadata, resolveFallbackAction, selectModelTierForWorkCategory } from "./model-router.mjs";
 import { resolveRuntimePromptMetadata } from "./prompt-composer.js";
 import { enrichMetadataWithPrompt } from "./prompt-metadata.mjs";
@@ -30,6 +33,7 @@ import { syncModelPricing, refreshPricingCatalog } from "./telemetry/model-prici
 import { estimateUsageCost } from "./telemetry/model-pricing-catalog.mjs";
 import { buildSessionPrelude } from "./intake/session-prelude.mjs";
 import { doctorRoot } from './config/xdg.mjs';
+import { recordToolFailure } from "./mcp/tool-recovery.mjs";
 
 const EFFICIENCY_SESSION_IDLE_RESET_MS = 2 * 60 * 60 * 1000;
 const EFFICIENCY_REPEATED_READ_THRESHOLD = 5;
@@ -59,6 +63,119 @@ const RATE_LIMIT_PATTERNS = [
   /no such model/i,
 ];
 
+// construct-2q2m: OpenCode's own tool resolution (packages/opencode/src/session/llm/request.ts,
+// resolveTools) filters disabled/denied tools out of the schema before the model ever sees them,
+// so a model-hallucinated call to a tool name outside that resolved set has no single documented
+// error shape in this repo's OpenCode source audit (docs/notes/research/2026-06-construct-audit/
+// 20-opencode-ecosystem.md) — it is an AI-SDK/provider-level rejection, not an OpenCode permission
+// deny (which instead flows through permission.ask and stays in-schema). These patterns match the
+// Vercel AI SDK's NoSuchToolError phrasing plus common "tool not found" provider error text, so at
+// least one branch catches whichever shape OpenCode actually surfaces. Unverified against a live
+// OpenCode session — see detectUnavailableToolRejections doc comment.
+const UNAVAILABLE_TOOL_PATTERNS = [
+  /\bno such tool\b/i,
+  /\bunknown tool\b/i,
+  /\bunavailable tool\b/i,
+  /\btool\b[^.\n]{0,60}\b(?:not found|not available|not registered|not permitted|does not exist)\b/i,
+  /\bNoSuchToolError\b/i,
+  /is not a (?:known|recognized|valid|registered) tool/i,
+];
+
+function textLooksLikeUnavailableTool(text) {
+  return typeof text === "string" && text.length > 0 && UNAVAILABLE_TOOL_PATTERNS.some((pattern) => pattern.test(text));
+}
+
+function toolNameFromPart(part) {
+  if (!part || typeof part !== "object") return null;
+  const typ = typeof part.type === "string" ? part.type.toLowerCase() : "";
+  if (typ === "tool" || typ === "tool-call" || typ === "tool_call") {
+    return stripPlaceholder(part.tool || part.toolName || part.name) || null;
+  }
+  if (typ === "tool-invocation" || typ === "tool_invocation") {
+    const invocation = part.toolInvocation || part;
+    return stripPlaceholder(invocation.toolName || invocation.tool || invocation.name) || null;
+  }
+  return null;
+}
+
+function toolPartErrorText(part) {
+  if (!part || typeof part !== "object") return "";
+  const typ = typeof part.type === "string" ? part.type.toLowerCase() : "";
+  if (typ === "tool" || typ === "tool-call" || typ === "tool_call") {
+    return flatten(part.state?.error ?? part.state?.message ?? "");
+  }
+  if (typ === "tool-invocation" || typ === "tool_invocation") {
+    const invocation = part.toolInvocation || part;
+    return flatten(invocation.error ?? invocation.state?.error ?? "");
+  }
+  return "";
+}
+
+function toolPartIsErrorState(part) {
+  const typ = typeof part?.type === "string" ? part.type.toLowerCase() : "";
+  if (typ === "tool" || typ === "tool-call" || typ === "tool_call") {
+    const status = part.state?.status ?? part.state;
+    return status === "error";
+  }
+  if (typ === "tool-invocation" || typ === "tool_invocation") {
+    const invocation = part.toolInvocation || part;
+    return invocation?.state === "error" || invocation?.status === "error";
+  }
+  return false;
+}
+
+// Detects a model-attempted call to a tool OpenCode rejects as unavailable, from
+// either a session.error event or an error-state tool part inside message.updated.
+// Returns one hit per match; each hit best-effort resolves the tool name (null when
+// the raw text does not identify it structurally). Hits append to the shared
+// tool-failures observation log (lib/mcp/tool-recovery.mjs) so both this host-side
+// signal and construct-mcp's own server-side tool-name-miss capture feed the same
+// learning-loop aggregation (summarizeToolFailures).
+//
+// Pattern-matched against documented AI-SDK/provider error phrasing rather than a
+// live OpenCode session; construct-2q2m's open item is confirming the real event
+// shape and, if it differs, adjusting the patterns/field lookups above.
+
+export function detectUnavailableToolRejections(event) {
+  if (event?.type === "session.error") {
+    const error = event?.error && typeof event.error === "object" ? event.error : {};
+    const text = flatten([error.message, error.name, error.code, event?.message]);
+    if (!textLooksLikeUnavailableTool(text)) return [];
+    return [{
+      tool: stripPlaceholder(error.tool || error.toolName) || null,
+      source: "session.error",
+      text: text.slice(0, 500),
+    }];
+  }
+  if (event?.type === "message.updated") {
+    const info = event?.properties?.info;
+    const parts = Array.isArray(info?.parts) ? info.parts : [];
+    const hits = [];
+    for (const part of parts) {
+      if (!toolPartIsErrorState(part)) continue;
+      const text = toolPartErrorText(part);
+      if (!textLooksLikeUnavailableTool(text)) continue;
+      hits.push({ tool: toolNameFromPart(part), source: "message.part", text: text.slice(0, 500) });
+    }
+    return hits;
+  }
+  return [];
+}
+
+export function recordUnavailableToolRejections(event, { toolkitDir = process.env.CX_TOOLKIT_DIR, env = process.env } = {}) {
+  const hits = detectUnavailableToolRejections(event);
+  if (!hits.length) return hits;
+  const rootDir = toolkitDir || env.CX_TOOLKIT_DIR || process.cwd();
+  for (const hit of hits) {
+    recordToolFailure(rootDir, {
+      tool: hit.tool || "(unknown)",
+      code: "opencode_tool_unavailable",
+      message: hit.text,
+    });
+  }
+  return hits;
+}
+
 const RUNTIME_TRACE_EVENTS = new Set([
   "session.created",
   "session.idle",
@@ -787,14 +904,14 @@ function writeState(payload, env = process.env) {
   writeFileSync(statePath, JSON.stringify(payload, null, 2));
 }
 
-function readOpenRouterApiKey(configPath = findOpenCodeConfigPath(), env = process.env) {
+export function readOpenRouterApiKey(configPath = findOpenCodeConfigPath(), env = process.env) {
   if (env.OPENROUTER_API_KEY) return env.OPENROUTER_API_KEY;
   try {
     const config = JSON.parse(readFileSync(configPath, "utf8"));
     const auth = config?.provider?.openrouter?.options?.headers?.Authorization;
     if (typeof auth !== "string") return "";
     const key = auth.replace(/^Bearer\s+/i, "").trim();
-    if (!key || key.includes("__OPENROUTER_API_KEY__")) return "";
+    if (isPlaceholder(key)) return "";
     return key;
   } catch {
     return "";
@@ -916,6 +1033,7 @@ export function createConstructOpenCodePlugin({
       await safe(() => emitRuntimeTrace(event, { client, env }), "legacy-trace", client);
       await safe(() => emitSessionPrelude(event, { client, env, cwd: toolkitDir }), "session-prelude", client);
       await maybeApplyModelFallback(event, { client, env, toolkitDir, configPath });
+      await safe(() => recordUnavailableToolRejections(event, { toolkitDir, env }), "tool-miss-capture", client);
       try {
         const { warnings } = trackReadEfficiencyFromMessage(event, { env, cwd: toolkitDir || process.cwd() });
         for (const message of warnings) {

package/lib/oracle/actions.mjs

@@ -5,10 +5,16 @@
  * sync (Construct tool repo only). Approve actions queue to
  * <project>/.cx/oracle/pending.jsonl. High-severity gaps auto-raise beads
  * when enabled. Denied actions are skipped.
+ *
+ * triagePending() flushes an accumulated pending.jsonl backlog to one
+ * representative row per dedupKey (pending or already-expired; approved
+ * rows are left untouched), archiving every superseded row to
+ * pending-archive.jsonl so the original set stays recoverable.
  */
 
 import fs from 'node:fs';
 import path from 'node:path';
+import crypto from 'node:crypto';
 import { spawnSync } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 
@@ -27,19 +33,59 @@ function pendingPath(projectDir) {
   return path.join(projectDir, '.cx', 'oracle', 'pending.jsonl');
 }
 
+function pendingArchivePath(projectDir) {
+  return path.join(projectDir, '.cx', 'oracle', 'pending-archive.jsonl');
+}
+
+// Recurring machine-generated decisions (re-run tests / review contract
+// violations / rebuild the dependency matrix) are symptoms of noisy
+// producers, not decisions in their own right — approving the survivor
+// clears the queue but does not fix the producer. Surfacing the linkage on
+// the survivor keeps that distinction visible to whoever reviews the triage
+// output.
+
+const RECURRING_PRODUCER_LINKAGE = [
+  { pattern: /re-run affected tests/i, linkedTo: ['construct-r8wr.6'] },
+  { pattern: /review recent contract violations/i, linkedTo: ['construct-r8wr.1'] },
+  { pattern: /rebuild the dependency matrix/i, linkedTo: ['construct-r8wr.6'] },
+];
+
+function producerLinkageFor(summary) {
+  const match = RECURRING_PRODUCER_LINKAGE.find((entry) => entry.pattern.test(summary || ''));
+  return match ? match.linkedTo : undefined;
+}
+
+const ORACLE_PENDING_MAX = 50;
+const ORACLE_PENDING_TTL_MS = 7 * 24 * 60 * 60 * 1000;
+
 function ensureOracleDir(projectDir) {
   const dir = path.join(projectDir, '.cx', 'oracle');
   if (!fs.existsSync(dir)) fs.mkdirSync(dir, { recursive: true });
   return dir;
 }
 
-function appendPending(projectDir, record) {
-  ensureOracleDir(projectDir);
-  const line = JSON.stringify({ ...record, queuedAt: new Date().toISOString() }) + '\n';
-  fs.appendFileSync(pendingPath(projectDir), line, 'utf8');
+function sha256(input) {
+  return crypto.createHash('sha256').update(input).digest('hex');
+}
+
+function normalizeSummary(summary) {
+  return String(summary || '').trim().toLowerCase().replace(/\s+/g, ' ');
+}
+
+function pendingTarget(record = {}) {
+  return record.target
+    || record.signOff?.id
+    || record.context?.signOff?.id
+    || record.context?.remediationRoute?.primary
+    || '';
 }
 
-export function listPending(projectDir) {
+function pendingDedupKey(record = {}) {
+  const parts = [record.kind || '', pendingTarget(record), normalizeSummary(record.summary)];
+  return `oracle:${sha256(parts.join('\u0000')).slice(0, 16)}`;
+}
+
+function readPendingRecords(projectDir) {
   const file = pendingPath(projectDir);
   if (!fs.existsSync(file)) return [];
   return fs.readFileSync(file, 'utf8')
@@ -49,15 +95,165 @@ export function listPending(projectDir) {
     .filter(Boolean);
 }
 
+function sweepPendingRecords(records, now = Date.now()) {
+  let changed = false;
+  const next = records.map((record) => {
+    const dedupKey = record.dedupKey || pendingDedupKey(record);
+    if (record.dedupKey !== dedupKey) changed = true;
+    const count = Number.isFinite(record.count) && record.count > 0 ? record.count : 1;
+    const firstSeenAt = record.firstSeenAt || record.queuedAt || new Date(now).toISOString();
+    const lastSeenAt = record.lastSeenAt || record.queuedAt || firstSeenAt;
+    const updated = {
+      ...record,
+      dedupKey,
+      count,
+      firstSeenAt,
+      lastSeenAt,
+    };
+    const ageMs = now - Date.parse(lastSeenAt);
+    if (updated.status === 'pending' && Number.isFinite(ageMs) && ageMs > ORACLE_PENDING_TTL_MS) {
+      updated.status = 'expired';
+      updated.expiredAt = new Date(now).toISOString();
+      updated.expiredReason = 'ttl';
+      changed = true;
+    }
+    return updated;
+  });
+
+  const activePending = next
+    .filter((record) => record.status === 'pending')
+    .sort((a, b) => Date.parse(b.lastSeenAt || b.queuedAt || 0) - Date.parse(a.lastSeenAt || a.queuedAt || 0));
+
+  for (const overflow of activePending.slice(ORACLE_PENDING_MAX)) {
+    if (overflow.status !== 'pending') continue;
+    overflow.status = 'expired';
+    overflow.expiredAt = new Date(now).toISOString();
+    overflow.expiredReason = 'cap';
+    changed = true;
+  }
+
+  return { records: next, changed };
+}
+
 function rewritePending(projectDir, pending) {
   const file = pendingPath(projectDir);
+  ensureOracleDir(projectDir);
   fs.writeFileSync(file, pending.map((p) => JSON.stringify(p)).join('\n') + (pending.length ? '\n' : ''), 'utf8');
 }
 
+function enqueuePending(projectDir, record, now = Date.now()) {
+  const { records, changed } = sweepPendingRecords(readPendingRecords(projectDir), now);
+  const dedupKey = pendingDedupKey(record);
+  const queuedAt = new Date(now).toISOString();
+  const existing = records.find((entry) => entry.status === 'pending' && entry.dedupKey === dedupKey);
+  if (existing) {
+    existing.summary = record.summary;
+    existing.signOff = record.signOff;
+    existing.context = record.context;
+    existing.classification = record.classification;
+    existing.target = pendingTarget(record);
+    existing.count = (Number.isFinite(existing.count) ? existing.count : 1) + 1;
+    existing.lastSeenAt = queuedAt;
+    rewritePending(projectDir, records);
+    return existing;
+  }
+  const pending = {
+    ...record,
+    id: record.id || `oracle-${dedupKey.slice('oracle:'.length)}`,
+    dedupKey,
+    count: 1,
+    queuedAt,
+    firstSeenAt: queuedAt,
+    lastSeenAt: queuedAt,
+    target: pendingTarget(record),
+  };
+  rewritePending(projectDir, changed ? records.concat(pending) : [...records, pending]);
+  return pending;
+}
+
+export function listPending(projectDir, { includeExpired = false, now = Date.now() } = {}) {
+  const { records, changed } = sweepPendingRecords(readPendingRecords(projectDir), now);
+  if (changed) rewritePending(projectDir, records);
+  return records.filter((record) => includeExpired || record.status !== 'expired');
+}
+
+/**
+ * Flush the pending.jsonl backlog to one representative row per dedupKey.
+ * Groups every non-approved row (pending or expired — a backlog that has
+ * already TTL/cap-expired is still a backlog) by dedupKey, keeps the
+ * most-recently-seen row as the survivor with an accumulated
+ * occurrenceCount, and archives every other row in the group to
+ * pending-archive.jsonl with a supersededBy/supersededAt trail. Approved
+ * rows are real decisions already made and are left untouched.
+ */
+export function triagePending(projectDir, { dryRun = false, now = Date.now() } = {}) {
+  const { records } = sweepPendingRecords(readPendingRecords(projectDir), now);
+  const protectedRecords = records.filter((r) => r.status === 'approved');
+  const eligible = records.filter((r) => r.status !== 'approved');
+
+  const groups = new Map();
+  for (const record of eligible) {
+    const key = record.dedupKey || pendingDedupKey(record);
+    if (!groups.has(key)) groups.set(key, []);
+    groups.get(key).push(record);
+  }
+
+  const survivors = [];
+  const supersededRows = [];
+  const archivedAt = new Date(now).toISOString();
+
+  for (const group of groups.values()) {
+    const sorted = [...group].sort((a, b) => {
+      const bySeen = Date.parse(b.lastSeenAt || b.queuedAt || 0) - Date.parse(a.lastSeenAt || a.queuedAt || 0);
+      if (bySeen !== 0) return bySeen;
+      return (b.count || 1) - (a.count || 1);
+    });
+    const [representative, ...rest] = sorted;
+    const occurrenceCount = group.reduce((sum, r) => sum + (Number.isFinite(r.count) && r.count > 0 ? r.count : 1), 0);
+    const linkedTo = producerLinkageFor(representative.summary);
+
+    survivors.push({
+      ...representative,
+      count: occurrenceCount,
+      occurrenceCount,
+      ...(rest.length ? { supersededIds: rest.map((r) => r.id) } : {}),
+      ...(linkedTo ? { producerLinkage: linkedTo } : {}),
+    });
+
+    for (const row of rest) {
+      supersededRows.push({
+        ...row,
+        supersededBy: representative.id,
+        supersededAt: archivedAt,
+        supersededReason: 'duplicate-content-key',
+      });
+    }
+  }
+
+  if (!dryRun) {
+    if (supersededRows.length) {
+      ensureOracleDir(projectDir);
+      const archiveFile = pendingArchivePath(projectDir);
+      const lines = supersededRows.map((r) => JSON.stringify(r)).join('\n') + '\n';
+      fs.appendFileSync(archiveFile, lines, 'utf8');
+    }
+    rewritePending(projectDir, [...protectedRecords, ...survivors]);
+  }
+
+  return {
+    dryRun,
+    uniqueCount: survivors.length,
+    superseded: supersededRows.length,
+    survivors,
+    supersededRows,
+  };
+}
+
 export async function approvePending(projectDir, id, { execute = true, rootDir, homeDir, dryRun = false } = {}) {
-  const pending = listPending(projectDir);
+  const pending = listPending(projectDir, { includeExpired: true });
   const match = pending.find((p) => p.id === id);
   if (!match) return { ok: false, reason: 'not-found' };
+  if (match.status === 'expired') return { ok: false, reason: 'expired', action: match };
   if (match.status === 'approved' && match.executedAt) {
     return { ok: true, already: true, action: match };
   }
@@ -147,9 +343,7 @@ export async function runOracleTick({ rootDir, projectDir, homeDir, dryRun = fal
       executed.push({ ...rec, classification, result });
       continue;
     }
-    const id = `oracle-${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
     const pending = {
-      id,
       kind: rec.kind,
       summary: rec.summary,
       classification,
@@ -157,8 +351,8 @@ export async function runOracleTick({ rootDir, projectDir, homeDir, dryRun = fal
       signOff: rec.signOff ?? signOffMetadata({ id: rec.kind }, projectDir),
       context: { ...rec },
     };
-    if (!dryRun) appendPending(projectDir, pending);
-    queued.push(pending);
+    const persisted = dryRun ? pending : enqueuePending(projectDir, pending);
+    queued.push(persisted);
   }
 
   const tick = {

package/lib/oracle/cli.mjs

@@ -1,7 +1,7 @@
 /**
  * lib/oracle/cli.mjs — CLI handlers for `construct oracle <subcommand>`.
  *
- * Subcommands: start, status, review, pending, approve, gaps, reconcile.
+ * Subcommands: start, status, review, pending, approve, gaps, reconcile, triage.
  */
 
 import fs from 'node:fs';
@@ -17,7 +17,7 @@ import {
   readLastTick,
   KILLSWITCH_ENV,
 } from './index.mjs';
-import { runOracleTick, listPending, approvePending, defaultRootDir } from './actions.mjs';
+import { runOracleTick, listPending, approvePending, triagePending, defaultRootDir } from './actions.mjs';
 import { collectOracleGaps, formatOracleGapsReport } from './gaps.mjs';
 import { reconcileOracleHygieneBeads } from './reconcile.mjs';
 import { doctorRoot } from '../config/xdg.mjs';
@@ -153,6 +153,26 @@ function cmdGaps(args, { projectDir }) {
   return 0;
 }
 
+function cmdTriage(args, { projectDir }) {
+  const dryRun = args.includes('--dry-run');
+  const json = args.includes('--json');
+  const result = triagePending(projectDir, { dryRun });
+  if (json) {
+    process.stdout.write(JSON.stringify(result, null, 2) + '\n');
+    return 0;
+  }
+  process.stdout.write(
+    `Oracle triage${dryRun ? ' (dry-run)' : ''}: ${result.uniqueCount} unique decision(s), ${result.superseded} superseded\n`,
+  );
+  for (const s of result.survivors) {
+    process.stdout.write(`  ${s.id} [${s.status}] x${s.occurrenceCount}: ${s.summary}\n`);
+    if (s.producerLinkage) {
+      process.stdout.write(`    producer linkage: ${s.producerLinkage.join(', ')} (approving this does not fix the producer)\n`);
+    }
+  }
+  return 0;
+}
+
 async function cmdReconcile(args, { projectDir }) {
   const dryRun = args.includes('--dry-run');
   const json = args.includes('--json');
@@ -194,9 +214,10 @@ export async function runOracleCli(args, opts = {}) {
     case 'approve': return cmdApprove(subArgs, { projectDir, rootDir, homeDir });
     case 'gaps': return cmdGaps(subArgs, { projectDir });
     case 'reconcile': return cmdReconcile(subArgs, { projectDir });
+    case 'triage': return cmdTriage(subArgs, { projectDir });
     default:
       process.stderr.write(
-        'Usage: construct oracle <start|status|review|pending|approve|gaps|reconcile> [--json] [--dry-run] [--foreground] [--no-execute]\n',
+        'Usage: construct oracle <start|status|review|pending|approve|gaps|reconcile|triage> [--json] [--dry-run] [--foreground] [--no-execute]\n',
       );
       if (sub && sub !== '--help' && sub !== '-h') {
         process.stderr.write(`Unknown subcommand: ${sub}\n`);

package/lib/oracle/dispatch.mjs

@@ -1,5 +1,6 @@
 /**
- * lib/oracle/dispatch.mjs — cx-oracle routing artifacts (deterministic, LLM-free).
+ * lib/oracle/dispatch.mjs — fleet-health routing artifacts for cx-orchestrator's
+ * absorbed cx-oracle duty (deterministic, LLM-free; construct-rf26.11).
  *
  * Writes audit markdown under .cx/oracle/routing/ for approve-gated dispatch.
  * Optional high-severity auto-artifact on tick when gaps are load-bearing.

package/lib/oracle/execute.mjs

@@ -159,11 +159,11 @@ export async function executeApprovedAction(action, { rootDir, projectDir, homeD
       });
     case 'trace-review':
       return dispatchRemediation({
-        action, projectDir, homeDir, personaId: 'cx-trace-reviewer', eventType: 'outcomes.degraded',
+        action, projectDir, homeDir, personaId: 'cx-reviewer', eventType: 'outcomes.degraded',
       });
     case 'doctor-followup':
       return dispatchRemediation({
-        action, projectDir, homeDir, personaId: 'cx-sre', eventType: 'service.down',
+        action, projectDir, homeDir, personaId: 'cx-operations', eventType: 'service.down',
       });
     case 'executive-signoff-required':
     case 'structure-cleanup-proposal':

package/lib/oracle/gaps.mjs

@@ -10,10 +10,10 @@ import { isVerdictOnlyGap, autoRaiseEnabledForGap } from './policy.mjs';
 
 const HYGIENE_HINTS = {
   'beads-hygiene': 'Run `construct beads drift` to inspect stuck/stale beads.',
-  'workflow-misaligned': 'Run `construct workflow init` or `construct init` to align workflow state.',
+  'workflow-misaligned': 'Run `construct workflow new` or `construct init` to align workflow state.',
   'propagation-stale': 'Run `construct sync` to refresh platform propagation.',
-  'census-stale': 'Run `construct census` to refresh the fleet census.',
-  'outcomes-missing': 'Run `construct outcomes aggregate` when outcome data is available.',
+  'census-stale': 'Run `node scripts/alignment/census.mjs` to refresh the fleet census.',
+  'outcomes-missing': 'Run `construct oracle` action `outcomes-aggregate` when outcome data is available.',
 };
 
 /**

package/lib/oracle/heartbeat.mjs

@@ -0,0 +1,53 @@
+/**
+ * lib/oracle/heartbeat.mjs — oracle producer liveness from the last-tick record.
+ *
+ * The oracle daemon records last-tick.json when a tick completes and idles itself
+ * out after a few no-work ticks, so a stale tick on its own is not death — it is a
+ * dead-producer signal only when oracle work is actually waiting (pending approvals
+ * or unaddressed gaps). Consumers therefore pair heartbeatFreshness with a pending
+ * count; this module owns only the age check. It is deliberately distinct from
+ * verdictFreshness in lib/intake/session-prelude.mjs, which ages the verdict's own
+ * `at` (is the answer current) rather than the producer's tick `at` (is anything
+ * still generating answers). formatAge is shared with the verdict path.
+ */
+
+import { readLastTick } from './index.mjs';
+
+// Six missed 5-minute intervals clears the daemon's idle-shutdown window before a
+// stale tick is treated as a stalled producer, so a briefly-quiet daemon is never
+// mislabelled dead.
+export const ORACLE_TICK_INTERVAL_MS = 5 * 60_000;
+export const HEARTBEAT_STALE_MS = ORACLE_TICK_INTERVAL_MS * 6;
+
+export function formatAge(ageMs) {
+  if (!Number.isFinite(ageMs)) return 'unknown';
+  const hours = Math.floor(ageMs / (60 * 60 * 1000));
+  if (hours < 1) return '<1h';
+  if (hours < 24) return `${hours}h`;
+  return `${Math.floor(hours / 24)}d`;
+}
+
+// Missing or unparseable `at` resolves to Infinity — stale, never fresh — so an
+// absent tick record reads as a stalled producer rather than a healthy one.
+
+export function heartbeatFreshness(lastTick, now = Date.now()) {
+  const at = lastTick?.at;
+  const parsed = at ? Date.parse(at) : NaN;
+  const ageMs = Number.isFinite(parsed) ? now - parsed : Infinity;
+  return {
+    ageMs,
+    stale: !Number.isFinite(ageMs) || ageMs > HEARTBEAT_STALE_MS,
+    asOf: Number.isFinite(parsed) ? new Date(parsed).toISOString() : null,
+  };
+}
+
+// Honors the oracle off-switch so a deliberately disabled daemon is never flagged.
+
+export function readHeartbeatStatus({ homeDir, env = process.env } = {}) {
+  if (env?.CONSTRUCT_ORACLE === 'off' || env?.CONSTRUCT_ORACLE === '0') {
+    return { enabled: false, lastTick: null, ageMs: null, stale: false, asOf: null };
+  }
+  const lastTick = readLastTick(homeDir);
+  const { ageMs, stale, asOf } = heartbeatFreshness(lastTick);
+  return { enabled: true, lastTick, ageMs, stale, asOf };
+}