@geraldmaron/construct 1.0.0 → 1.0.2

package/lib/research-lint.mjs

@@ -0,0 +1,164 @@
+/**
+ * lib/research-lint.mjs — enforce minimum structure for research and evidence artifacts.
+ *
+ * Validates markdown files under .cx/research/ and key .cx/knowledge/
+ * folders so weak or incomplete evidence docs are flagged before they become
+ * decision inputs. Backs `construct lint:research` and lightweight CI checks.
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+
+const RESEARCH_RELPATH = /^\.cx\/research\/.+\.md$/;
+const EVIDENCE_RELPATH = /^\.cx\/knowledge\/reference\/evidence-briefs\/.+\.md$/;
+const SIGNAL_RELPATH = /^\.cx\/knowledge\/external\/signals\/.+\.md$/;
+
+const REQUIRED_SECTIONS = {
+  research: ['Question', 'Method', 'Sources', 'Findings', 'Confidence', 'References'],
+  evidence: ['Decision this evidence informs', 'Evidence threshold', 'Sources', 'What we observed', 'Confidence', 'Recommendation'],
+  signal: ['Signal', 'Evidence', 'Why it matters', 'What would make this actionable', 'Follow-up'],
+};
+
+function relPath(rootDir, absPath) {
+  return path.relative(rootDir, absPath).replace(/\\/g, '/');
+}
+
+function artifactKind(rel) {
+  if (RESEARCH_RELPATH.test(rel)) return 'research';
+  if (EVIDENCE_RELPATH.test(rel)) return 'evidence';
+  if (SIGNAL_RELPATH.test(rel)) return 'signal';
+  return null;
+}
+
+function lineForMatch(content, pattern) {
+  const lines = content.split('\n');
+  for (let index = 0; index < lines.length; index += 1) {
+    if (pattern.test(lines[index])) return index + 1;
+  }
+  return 1;
+}
+
+function hasHeading(content, heading) {
+  const escaped = heading.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+  return new RegExp(`^##\\s+${escaped}\\s*$`, 'm').test(content);
+}
+
+function hasDateMetadata(content) {
+  return /^-\s+\*\*Date\*\*:\s+.+$/m.test(content)
+    || /\b(?:publication|access)\s+date\b/i.test(content)
+    || /\b\d{4}-\d{2}-\d{2}\b/.test(content);
+}
+
+function hasConfidenceCue(content) {
+  return /\bconfidence\b/i.test(content)
+    || /\bhigh\b|\bmedium\b|\blow\b/i.test(content)
+    || /\bweak signal\b|\bconfirmed\b|\binferred\b/i.test(content);
+}
+
+function hasSourceCue(content) {
+  return /\bsource\b/i.test(content)
+    || /\bhttps?:\/\//i.test(content)
+    || /\b\.cx\//.test(content)
+    || /\bdocs\//.test(content);
+}
+
+function hasObservationInferenceCue(content) {
+  return /\bobservation\b/i.test(content)
+    || /\binference\b/i.test(content)
+    || /\bwhat we observed\b/i.test(content);
+}
+
+export function lintResearchFile(filePath, { rootDir = process.cwd() } = {}) {
+  const rel = relPath(rootDir, filePath);
+  const kind = artifactKind(rel);
+  if (!kind) return { path: rel, kind: null, errors: [], warnings: [] };
+
+  let content = '';
+  try {
+    content = fs.readFileSync(filePath, 'utf8');
+  } catch {
+    return { path: rel, kind, errors: [{ line: 1, label: 'unable to read file' }], warnings: [] };
+  }
+
+  const errors = [];
+  const warnings = [];
+
+  for (const heading of REQUIRED_SECTIONS[kind]) {
+    if (!hasHeading(content, heading)) {
+      errors.push({
+        line: 1,
+        label: `missing required section: ${heading}`,
+      });
+    }
+  }
+
+  if (!hasSourceCue(content)) {
+    errors.push({
+      line: lineForMatch(content, /^##\s+Sources\s*$/m),
+      label: 'missing source references, links, or document paths',
+    });
+  }
+
+  if (!hasDateMetadata(content)) {
+    warnings.push({
+      line: 1,
+      label: 'missing explicit date or access-date basis',
+    });
+  }
+
+  if (!hasConfidenceCue(content)) {
+    errors.push({
+      line: 1,
+      label: 'missing confidence labeling or threshold language',
+    });
+  }
+
+  if ((kind === 'research' || kind === 'evidence') && !hasObservationInferenceCue(content)) {
+    warnings.push({
+      line: 1,
+      label: 'observation vs inference separation is not explicit',
+    });
+  }
+
+  return { path: rel, kind, errors, warnings };
+}
+
+function walkDir(dir, results = []) {
+  let entries;
+  try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return results; }
+  for (const entry of entries) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      if (['.git', 'node_modules', 'site', '.construct', '.claude'].includes(entry.name)) continue;
+      walkDir(full, results);
+    } else if (entry.isFile() && entry.name.endsWith('.md')) {
+      results.push(full);
+    }
+  }
+  return results;
+}
+
+export function lintResearchRepo({ rootDir = process.cwd() } = {}) {
+  const files = walkDir(rootDir).filter((filePath) => artifactKind(relPath(rootDir, filePath)));
+  const results = files.map((filePath) => lintResearchFile(filePath, { rootDir }));
+  return results.filter((result) => result.errors.length || result.warnings.length);
+}
+
+export function formatResearchLintResults(results) {
+  if (!results.length) return { output: '  ✓  No research artifact issues found.\n', exitCode: 0 };
+
+  const lines = [];
+  let errorCount = 0;
+  let warnCount = 0;
+  for (const { path: filePath, errors, warnings } of results) {
+    for (const { line, label } of errors) {
+      lines.push(`  error  ${filePath}:${line}  ${label}`);
+      errorCount += 1;
+    }
+    for (const { line, label } of warnings) {
+      lines.push(`  warn   ${filePath}:${line}  ${label}`);
+      warnCount += 1;
+    }
+  }
+  lines.push(`\n  ${errorCount} error(s), ${warnCount} warning(s)`);
+  return { output: `${lines.join('\n')}\n`, exitCode: errorCount > 0 ? 1 : 0 };
+}

package/lib/resources/budget.mjs

@@ -0,0 +1,259 @@
+/**
+ * lib/resources/budget.mjs — disk-budget enforcement for .cx/ assets.
+ *
+ * Construct generates data continuously: traces, intake archives, task
+ * graphs, worker logs, session records, backups. None of it has a
+ * natural ceiling, so left unchecked the .cx/ tree grows until it
+ * threatens the operator's disk. The budget primitive caps each
+ * category against a config-defined ceiling.
+ *
+ * Two enforcement modes:
+ *   - **Hard-reject** (traces, worker logs): observability is
+ *     replaceable. When the cap is hit, refuse new writes with a
+ *     typed error pointing at `construct prune` and the dashboard
+ *     budget page. Better to lose a trace than crash the operator's
+ *     machine.
+ *   - **Soft-warn** (intake archive, task graphs): R&D state is
+ *     load-bearing — never reject; emit a warning the operator can
+ *     see in the doctor surface, and pruning gets aggressive.
+ *
+ * Defaults live in DEFAULT_PROJECT_CONFIG.resources. The operator
+ * raises them in construct.config.json or via the dashboard. Doctor
+ * surfaces usage vs cap at 80% (warn) and 100% (fail).
+ */
+import fs from 'node:fs';
+import path from 'node:path';
+import { loadProjectConfig } from '../config/project-config.mjs';
+
+export const HARD_REJECT_CATEGORIES = new Set(['traces', 'worker-logs']);
+export const SOFT_WARN_CATEGORIES = new Set(['intake-archive', 'task-graphs', 'sessions', 'backups', 'handoffs']);
+
+const CATEGORY_PATHS = {
+  traces: '.cx/traces',
+  'worker-logs': '.cx/runtime/worker',
+  'intake-archive': '.cx/intake/processed',
+  'intake-skipped': '.cx/intake/skipped',
+  'task-graphs': '.cx/task-graphs',
+  sessions: '.cx/sessions',
+  backups: '.cx/backups',
+  handoffs: '.cx/handoffs',
+};
+
+function loadResourceBudgets(projectRoot, env) {
+  const { config } = loadProjectConfig(projectRoot, env);
+  return config?.resources ?? {};
+}
+
+function walkDirSize(dir) {
+  if (!fs.existsSync(dir)) return { bytes: 0, files: 0 };
+  let bytes = 0;
+  let files = 0;
+  for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+    const full = path.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      const r = walkDirSize(full);
+      bytes += r.bytes;
+      files += r.files;
+    } else {
+      try {
+        bytes += fs.statSync(full).size;
+        files += 1;
+      } catch { /* race — file disappeared */ }
+    }
+  }
+  return { bytes, files };
+}
+
+export function measureUsage(projectRoot, env = process.env) {
+  const budgets = loadResourceBudgets(projectRoot, env);
+  const result = { categories: {}, totalCxBytes: 0, totalCxCap: (budgets?.disk?.totalCxMaxMb ?? 2000) * 1024 * 1024 };
+  for (const [name, rel] of Object.entries(CATEGORY_PATHS)) {
+    const full = path.join(projectRoot, rel);
+    const { bytes, files } = walkDirSize(full);
+    result.categories[name] = {
+      bytes,
+      files,
+      path: rel,
+      enforcement: HARD_REJECT_CATEGORIES.has(name) ? 'hard-reject' : 'soft-warn',
+    };
+    result.totalCxBytes += bytes;
+  }
+  result.totalCxUsageRatio = result.totalCxCap > 0 ? result.totalCxBytes / result.totalCxCap : 0;
+  return result;
+}
+
+export function reserveOrReject(projectRoot, category, sizeBytes, env = process.env) {
+  if (!CATEGORY_PATHS[category]) {
+    return { ok: true, source: 'unknown-category' };
+  }
+  const usage = measureUsage(projectRoot, env);
+  const totalAfter = usage.totalCxBytes + sizeBytes;
+  if (totalAfter > usage.totalCxCap) {
+    if (HARD_REJECT_CATEGORIES.has(category)) {
+      return {
+        ok: false,
+        reason: 'budget-exceeded',
+        message: `.cx/ total ${Math.round(totalAfter / 1024 / 1024)}MB would exceed cap ${Math.round(usage.totalCxCap / 1024 / 1024)}MB — run \`construct prune\` or raise resources.disk.totalCxMaxMb`,
+      };
+    }
+    return {
+      ok: true,
+      warn: true,
+      reason: 'budget-warning',
+      message: `.cx/ usage at ${Math.round((totalAfter / usage.totalCxCap) * 100)}% — \`construct prune\` recommended`,
+    };
+  }
+  const ratio = totalAfter / usage.totalCxCap;
+  if (ratio > 0.8) {
+    return { ok: true, warn: true, reason: 'budget-warning', message: `.cx/ usage at ${Math.round(ratio * 100)}% of cap` };
+  }
+  return { ok: true };
+}
+
+export function planPrune(projectRoot, env = process.env, opts = {}) {
+  const budgets = loadResourceBudgets(projectRoot, env);
+  const disk = budgets?.disk ?? {};
+  const now = opts.now ?? Date.now();
+  const actions = [];
+
+  const tracesMaxDays = disk.tracesMaxDays ?? 30;
+  const tracesDir = path.join(projectRoot, '.cx/traces');
+  if (fs.existsSync(tracesDir)) {
+    const cutoff = now - tracesMaxDays * 24 * 60 * 60 * 1000;
+    for (const f of fs.readdirSync(tracesDir)) {
+      if (!f.endsWith('.jsonl')) continue;
+      const full = path.join(tracesDir, f);
+      const stat = fs.statSync(full);
+      if (stat.mtimeMs < cutoff) {
+        actions.push({ category: 'traces', path: full, reason: `older than ${tracesMaxDays}d`, bytes: stat.size });
+      }
+    }
+  }
+
+  const intakeDir = path.join(projectRoot, '.cx/intake/processed');
+  const intakeMaxItems = disk.intakeArchiveMaxItems ?? 500;
+  const intakeMaxDays = disk.intakeArchiveMaxDays ?? 90;
+  if (fs.existsSync(intakeDir)) {
+    const cutoff = now - intakeMaxDays * 24 * 60 * 60 * 1000;
+    const files = fs.readdirSync(intakeDir)
+      .filter((f) => f.endsWith('.json'))
+      .map((f) => {
+        const full = path.join(intakeDir, f);
+        const stat = fs.statSync(full);
+        return { path: full, mtimeMs: stat.mtimeMs, bytes: stat.size };
+      })
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (let i = 0; i < files.length; i++) {
+      const f = files[i];
+      if (i >= intakeMaxItems) {
+        actions.push({ category: 'intake-archive', path: f.path, reason: `exceeds ${intakeMaxItems} items`, bytes: f.bytes });
+      } else if (f.mtimeMs < cutoff) {
+        actions.push({ category: 'intake-archive', path: f.path, reason: `older than ${intakeMaxDays}d`, bytes: f.bytes });
+      }
+    }
+  }
+
+  const graphsDir = path.join(projectRoot, '.cx/task-graphs');
+  const graphsMaxItems = disk.taskGraphsMaxItems ?? 200;
+  const graphsMaxDays = disk.taskGraphsMaxDays ?? 90;
+  if (fs.existsSync(graphsDir)) {
+    const cutoff = now - graphsMaxDays * 24 * 60 * 60 * 1000;
+    const files = fs.readdirSync(graphsDir)
+      .filter((f) => f.endsWith('.json'))
+      .map((f) => {
+        const full = path.join(graphsDir, f);
+        const stat = fs.statSync(full);
+        return { path: full, mtimeMs: stat.mtimeMs, bytes: stat.size };
+      })
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (let i = 0; i < files.length; i++) {
+      const f = files[i];
+      if (i >= graphsMaxItems) {
+        actions.push({ category: 'task-graphs', path: f.path, reason: `exceeds ${graphsMaxItems} items`, bytes: f.bytes });
+      } else if (f.mtimeMs < cutoff) {
+        actions.push({ category: 'task-graphs', path: f.path, reason: `older than ${graphsMaxDays}d`, bytes: f.bytes });
+      }
+    }
+  }
+
+  const workerDir = path.join(projectRoot, '.cx/runtime/worker');
+  const workerMaxMb = disk.workerLogsMaxMb ?? 100;
+  const workerMaxDays = disk.workerLogsMaxDays ?? 14;
+  if (fs.existsSync(workerDir)) {
+    const cutoff = now - workerMaxDays * 24 * 60 * 60 * 1000;
+    const files = fs.readdirSync(workerDir)
+      .filter((f) => f.endsWith('.log'))
+      .map((f) => {
+        const full = path.join(workerDir, f);
+        const stat = fs.statSync(full);
+        return { path: full, mtimeMs: stat.mtimeMs, bytes: stat.size };
+      })
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    let totalBytes = 0;
+    for (const f of files) {
+      totalBytes += f.bytes;
+      const overSize = totalBytes > workerMaxMb * 1024 * 1024;
+      const overAge = f.mtimeMs < cutoff;
+      if (overSize) {
+        actions.push({ category: 'worker-logs', path: f.path, reason: `worker logs > ${workerMaxMb}MB cap`, bytes: f.bytes });
+      } else if (overAge) {
+        actions.push({ category: 'worker-logs', path: f.path, reason: `older than ${workerMaxDays}d`, bytes: f.bytes });
+      }
+    }
+  }
+
+  const handoffsDir = path.join(projectRoot, '.cx/handoffs');
+  const handoffsMaxItems = disk.handoffsMaxItems ?? 50;
+  const handoffsMaxDays = disk.handoffsMaxDays ?? 30;
+  if (fs.existsSync(handoffsDir)) {
+    const cutoff = now - handoffsMaxDays * 24 * 60 * 60 * 1000;
+    const files = fs.readdirSync(handoffsDir)
+      .filter((f) => f.endsWith('.md'))
+      .map((f) => {
+        const full = path.join(handoffsDir, f);
+        const stat = fs.statSync(full);
+        return { path: full, mtimeMs: stat.mtimeMs, bytes: stat.size };
+      })
+      .sort((a, b) => b.mtimeMs - a.mtimeMs);
+    for (let i = 0; i < files.length; i++) {
+      const f = files[i];
+      if (i >= handoffsMaxItems) {
+        actions.push({ category: 'handoffs', path: f.path, reason: `exceeds ${handoffsMaxItems} items`, bytes: f.bytes });
+      } else if (f.mtimeMs < cutoff) {
+        actions.push({ category: 'handoffs', path: f.path, reason: `older than ${handoffsMaxDays}d`, bytes: f.bytes });
+      }
+    }
+  }
+
+  const backupsRoot = path.join(projectRoot, '.cx/backups');
+  const backupsMaxDays = disk.backupsMaxDays ?? 60;
+  if (fs.existsSync(backupsRoot)) {
+    const cutoff = now - backupsMaxDays * 24 * 60 * 60 * 1000;
+    const walk = (dir) => {
+      for (const entry of fs.readdirSync(dir, { withFileTypes: true })) {
+        const full = path.join(dir, entry.name);
+        if (entry.isDirectory()) { walk(full); continue; }
+        const stat = fs.statSync(full);
+        if (stat.mtimeMs < cutoff) {
+          actions.push({ category: 'backups', path: full, reason: `older than ${backupsMaxDays}d`, bytes: stat.size });
+        }
+      }
+    };
+    walk(backupsRoot);
+  }
+
+  return actions;
+}
+
+export function executePrune(actions) {
+  const removed = [];
+  let bytesFreed = 0;
+  for (const a of actions) {
+    try {
+      fs.unlinkSync(a.path);
+      removed.push(a.path);
+      bytesFreed += a.bytes || 0;
+    } catch { /* race — already gone */ }
+  }
+  return { removed, bytesFreed };
+}

package/lib/role-preload.mjs

@@ -2,13 +2,21 @@
  * lib/role-preload.mjs — inline role anti-pattern files into specialist prompts at sync time.
  *
  * Specialist prompts carry a marker: **Role guidance**: call `get_skill("roles/NAME")` before drafting.
- * buildPrompt() in sync-agents.mjs replaces that marker with the role body so the content is always
- * present — no runtime get_skill dependency. Flavor overlays (e.g. engineer.ai) are concatenated
- * under the core role content.
+ *
+ * Default: on-demand. The directive stays in the prompt verbatim and the agent calls
+ * `get_skill("roles/NAME")` at runtime. All hosts Construct supports (Claude Code, OpenCode, Codex,
+ * Copilot) have the construct-mcp server exposing get_skill, so the runtime call is reliable.
+ * Saves ~1000+ words of prompt budget per agent by not inlining skills that may not be needed.
+ *
+ * Opt-in preload: when a registry entry sets `preloadRoleGuidance: true`, the role body is inlined
+ * at sync time. Use this only for agents deployed to hosts without reliable MCP access, or where the
+ * role content is load-bearing on every single invocation. See `rules/common/skill-composition.md`.
  */
 import fs from "node:fs";
 import path from "node:path";
 
+import { logSkillCall } from "./telemetry/skill-calls.mjs";
+
 export const ROLE_DIRECTIVE_RE = /^[ \t]*\*\*Role guidance\*\*:\s*call\s+`get_skill\("roles\/([^"]+)"\)`\s*before\s*drafting\.[ \t]*$/m;
 
 export const PROMPT_WORD_CAP = 3600;
@@ -23,13 +31,20 @@ function stripTopHeading(body) {
   return body.replace(/^#\s+[^\n]*\n+/, "").replace(/^Load this[^\n]*\n+/, "");
 }
 
-export function readRoleFile(root, name) {
+export function readRoleFile(root, name, opts = {}) {
   const p = path.join(root, "skills", "roles", `${name}.md`);
   if (!fs.existsSync(p)) return null;
-  return stripTopHeading(stripFrontmatter(fs.readFileSync(p, "utf8"))).trim();
+  const body = stripTopHeading(stripFrontmatter(fs.readFileSync(p, "utf8"))).trim();
+  logSkillCall({
+    skillId: `roles/${name}`,
+    source: opts.source || 'role-preload',
+    callerContext: opts.callerContext,
+  });
+  return body;
 }
 
-export function inlineRoleAntiPatterns(prompt, root, agentName = "(unknown)", warn = console.warn) {
+export function inlineRoleAntiPatterns(prompt, root, agentName = "(unknown)", warn = console.warn, opts = {}) {
+  if (!opts.preload) return prompt;
   const match = prompt.match(ROLE_DIRECTIVE_RE);
   if (!match) return prompt;
   const ref = match[1];

package/lib/roles/approval-surface.mjs

@@ -0,0 +1,54 @@
+/**
+ * lib/roles/approval-surface.mjs — visibility for approval-required actions.
+ *
+ * When a persona-tagged session hits an action that lands in the fence's
+ * `approvalRequired` bucket (commit, push, out-of-fence edit, etc.), this
+ * module appends a marker to ~/.cx/approval-pending.jsonl and emits an SSE
+ * toast through the embed notification bus. The user sees a dashboard toast
+ * instead of having to grep stderr.
+ *
+ * Best-effort: any failure is swallowed so guard hooks never get blocked by
+ * notification problems.
+ */
+
+import { existsSync, appendFileSync, mkdirSync } from 'node:fs';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+
+const PENDING_PATH = join(homedir(), '.cx', 'approval-pending.jsonl');
+
+function ensureDir() {
+  const dir = join(homedir(), '.cx');
+  if (!existsSync(dir)) mkdirSync(dir, { recursive: true });
+}
+
+export async function recordApprovalRequest({ personaId, action, target = '', reason = '', context = null }) {
+  if (process.env.CONSTRUCT_ROLES === 'off') return;
+  try {
+    ensureDir();
+    const entry = {
+      ts: Date.now(),
+      personaId,
+      cxId: `cx-${personaId}`,
+      action,
+      target: String(target).slice(0, 512),
+      reason,
+      context,
+    };
+    appendFileSync(PENDING_PATH, JSON.stringify(entry) + '\n');
+  } catch { /* best effort */ }
+
+  try {
+    const mod = await import('../embed/notifications.mjs');
+    if (typeof mod.emitEmbedNotification === 'function') {
+      mod.emitEmbedNotification({
+        type: 'warning',
+        source: 'roles',
+        message: `cx-${personaId} requesting approval: ${action} ${String(target).slice(0, 80)}`,
+        meta: { personaId, action, target, reason },
+      });
+    }
+  } catch { /* best effort */ }
+}
+
+export { PENDING_PATH };

package/lib/roles/cli.mjs

@@ -0,0 +1,118 @@
+/**
+ * lib/roles/cli.mjs — `construct role <subcommand>` handler.
+ *
+ * Subcommands:
+ *   list                — show pending role invocations
+ *   latest              — show the most recent unresolved invocation (full brief)
+ *   show <fingerprint>  — show one invocation by fingerprint
+ *   status              — show onboarded personas + their event types
+ *   reset               — clear the pending queue (manual recovery)
+ */
+
+import { listOnboardedPersonas, loadManifest } from './manifest.mjs';
+import { listPending, markResolved, resetPending } from './gateway.mjs';
+import { recent as recentEvents } from './event-bus.mjs';
+
+function fmtTime(ts) {
+  const d = new Date(ts);
+  return d.toISOString().replace('T', ' ').slice(0, 19);
+}
+
+function brief(entry, manifest) {
+  const fence = manifest?.fence || {};
+  const lines = [
+    `# Role invocation — ${entry.cxId}`,
+    `bd issue:   ${entry.bdIssueId || '(none)'}`,
+    `event:      ${entry.eventType}`,
+    `fingerprint: ${entry.fingerprint}`,
+    `queued at:  ${fmtTime(entry.ts)}`,
+    `summary:    ${entry.summary}`,
+    ``,
+    `## Fence`,
+    `allowedPaths:    ${(fence.allowedPaths || []).join(', ') || '(none)'}`,
+    `allowedLabels:   ${(fence.allowedBdLabels || []).join(', ') || '(none)'}`,
+    `allowedCommands: ${(fence.allowedCommands || []).join(', ') || '(none)'}`,
+    `approvalReq'd:   ${(fence.approvalRequired || []).join(', ') || '(none)'}`,
+    ``,
+    `## Handoff candidates`,
+    (manifest?.handoffCandidates || []).map((h) => `- cx-${h}`).join('\n') || '(none)',
+    ``,
+    `## To dispatch`,
+    `Run via existing Task path. Tell Construct:`,
+    `> Dispatch ${entry.cxId} for incident ${entry.bdIssueId} (fingerprint ${entry.fingerprint}).`,
+    `> Persona must stay inside fence above. Use \`next:cx-<role>\` bd label for handoff.`,
+  ];
+  return lines.join('\n');
+}
+
+export async function runCli(args) {
+  const sub = args[0] || 'list';
+
+  if (sub === 'list') {
+    const pending = listPending({ unresolved: true });
+    if (pending.length === 0) {
+      console.log('No pending role invocations.');
+      return 0;
+    }
+    console.log(`Pending role invocations: ${pending.length}`);
+    for (const p of pending) {
+      console.log(`  ${fmtTime(p.ts)}  ${p.cxId.padEnd(20)}  ${(p.bdIssueId || '-').padEnd(14)}  ${p.eventType.padEnd(28)}  ${p.summary}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'latest') {
+    const pending = listPending({ unresolved: true });
+    if (pending.length === 0) {
+      console.log('No pending role invocations.');
+      return 0;
+    }
+    const entry = pending[pending.length - 1];
+    const manifest = loadManifest(entry.personaId);
+    console.log(brief(entry, manifest));
+    return 0;
+  }
+
+  if (sub === 'show') {
+    const fp = args[1];
+    if (!fp) { console.error('Usage: construct role show <fingerprint>'); return 2; }
+    const pending = listPending({ unresolved: false });
+    const entry = pending.find((p) => p.fingerprint === fp || p.bdIssueId === fp);
+    if (!entry) { console.error(`No invocation found for ${fp}`); return 1; }
+    const manifest = loadManifest(entry.personaId);
+    console.log(brief(entry, manifest));
+    console.log('\n## Recent matching events');
+    for (const e of recentEvents({ fingerprint: entry.fingerprint, limit: 5 })) {
+      console.log(`  ${fmtTime(e.ts)}  ${e.type}  ${e.summary?.split('\n')[0] || ''}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'status') {
+    const onboarded = listOnboardedPersonas();
+    console.log(`Onboarded personas: ${onboarded.length}`);
+    for (const id of onboarded) {
+      const m = loadManifest(id);
+      console.log(`  cx-${id.padEnd(20)} events: ${(m.events || []).join(', ')}`);
+    }
+    return 0;
+  }
+
+  if (sub === 'resolve') {
+    const fp = args[1];
+    if (!fp) { console.error('Usage: construct role resolve <fingerprint>'); return 2; }
+    const ok = markResolved(fp);
+    console.log(ok ? `Resolved ${fp}` : `No matching pending entry for ${fp}`);
+    return ok ? 0 : 1;
+  }
+
+  if (sub === 'reset') {
+    resetPending();
+    console.log('Pending queue cleared.');
+    return 0;
+  }
+
+  console.error(`Unknown role subcommand: ${sub}`);
+  console.error('Usage: construct role [list|latest|show <fp>|status|resolve <fp>|reset]');
+  return 2;
+}