@geraldmaron/construct 1.4.2 → 1.5.1

package/examples/distribution/sources/deck-one-pager.md

@@ -60,6 +60,6 @@ One token set across all distributable formats:
 
 - Export: `construct export … --to=pptx`
 - Regenerate: `npm run examples:deck`
-- Matrix: [Document I/O reference](/guides/reference/document-io)
+- Matrix: [Document I/O reference](../../../docs/guides/reference/document-io.md)
 
 Review outputs in `.tmp/distribution-examples/`.

package/lib/acp/server.mjs

@@ -12,6 +12,10 @@
  * methods: `initialize`, `session/new`, `session/prompt`, `session/cancel`;
  * progress streams as `session/update` notifications. The prompt bridges to
  * planRun/executeRun and forwards run-lifecycle events as agent message chunks.
+ *
+ * `fetchImpl` is injectable (mirrors lib/orchestration/worker.mjs) and threads
+ * straight through to executeRun, so a test can drive the provider backend
+ * without a live key or a real network call.
  */
 
 import { createInterface } from 'node:readline';
@@ -20,16 +24,26 @@ const PROTOCOL_VERSION = 1;
 
 function describeEvent(event) {
   if (event.type === 'planned') return `Planned ${event.tasks ?? ''} specialist task(s).`;
-  if (event.type === 'running') return 'Running orchestration…';
-  if (event.type === 'task') return `· ${event.role ?? 'task'} — ${event.status ?? ''}`;
-  if (event.type === 'completed') return `Completed: ${event.status ?? 'done'}.`;
+  if (event.type === 'running') return `Running orchestration… (workerBackend=${event.workerBackend ?? 'inline'})`;
+  if (event.type === 'task') return `· ${event.role ?? 'task'} — ${event.status ?? ''}${event.executor ? ` (${event.executor})` : ''}`;
+  if (event.type === 'completed') {
+    const status = event.status ?? 'done';
+    if (status === 'completed') return 'Completed (specialist tasks executed).';
+    if (status === 'completed-prepare-only') return 'Completed (tasks prepared only — no specialist execution).';
+    if (status === 'completed-with-failures') return 'Completed with failures (some tasks failed).';
+    if (status === 'degraded') return 'Degraded — the run could not fully execute; see the summary.';
+    if (status === 'cancelled') return 'Cancelled.';
+    return `Completed: ${status}.`;
+  }
   if (event.type === 'error') return `Error: ${event.error?.message ?? 'run failed'}.`;
   return null;
 }
 
 function summarize(run) {
-  const tasks = (run.tasks || []).map((t) => `- ${t.role} (${t.status})`).join('\n');
-  return `Orchestration ${run.status} — executionMode=${run.execution?.executionMode}.\n${tasks}`;
+  const tasks = (run.tasks || []).map((t) => `- ${t.role} (${t.status}${t.executor ? `, ${t.executor}` : ''})`).join('\n');
+  const exec = run.execution || {};
+  const degraded = run.degraded ? ` — degraded: ${run.degradationReason}` : '';
+  return `Orchestration ${run.status} — executionMode=${exec.executionMode}, workerBackend=${run.workerBackend}${degraded}.\n${tasks}`;
 }
 
 function textFromPrompt(prompt) {
@@ -37,7 +51,7 @@ function textFromPrompt(prompt) {
   return prompt.filter((b) => b && b.type === 'text' && typeof b.text === 'string').map((b) => b.text).join('\n').trim();
 }
 
-export function runAcpServer({ input, output, env = process.env, defaultCwd = process.cwd() } = {}) {
+export function runAcpServer({ input, output, env = process.env, defaultCwd = process.cwd(), fetchImpl } = {}) {
   const sessions = new Map();
   let sessionCounter = 0;
 
@@ -63,7 +77,7 @@ export function runAcpServer({ input, output, env = process.env, defaultCwd = pr
         const line = describeEvent(event);
         if (line) update(sessionId, line);
       });
-      const run = await executeRun(session.cwd, planned.runId, { env, workerBackend: 'inline' });
+      const run = await executeRun(session.cwd, planned.runId, { env, fetchImpl });
       off();
       update(sessionId, summarize(run));
       respond(id, { stopReason: isCancelRequested(planned.runId) ? 'cancelled' : 'end_turn' });

package/lib/adapters-sync.mjs

@@ -12,6 +12,7 @@ import { fileURLToPath } from 'node:url';
 import { detectHostCapabilities } from './host-capabilities.mjs';
 import { isConstructPackageRepo } from './host-disposition.mjs';
 import { stageProjectAdapters } from './install/stage-project.mjs';
+import { isMainModule } from './roots.mjs';
 
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PKG_ROOT = path.resolve(MODULE_DIR, '..');
@@ -58,7 +59,7 @@ export function runAdaptersScript({ cwd = process.cwd(), hosts = null } = {}) {
   return result.synced ? 0 : 1;
 }
 
-if (import.meta.url === `file://${process.argv[1]}`) {
+if (isMainModule(import.meta.url)) {
   const args = new Set(process.argv.slice(2));
   const forceAll = args.has('--all-hosts');
   const hosts = forceAll ? resolveAdapterHosts({ forceAll: true }) : null;

package/lib/audit-trail.mjs

@@ -17,14 +17,31 @@
  * the damaged prefix as immutable legacy and re-bases the live chain;
  * verifyChain validates only from the last boundary forward. See
  * docs/guides/concepts/observability.md.
+ *
+ * Every record passes through redactRecord before the chain hash is computed
+ * (redact-then-sign), so prev_line_hash always chains off the redacted form —
+ * a secret can never enter the signed chain even transiently. Redaction
+ * covers: (a) values resolved by lib/providers/secret-resolver.mjs, consulted
+ * read-only via its resolved-cache snapshot; (b) common token shapes (Bearer,
+ * ghp_, xoxb/xoxp/xoxa, sk-, op://); (c) custom patterns registered with
+ * configureRedactionPatterns. Matches are replaced with `<redacted:kind>`;
+ * the pass itself is audited as a count, never the matched text.
+ *
+ * LMCP-H5: checkAuditSinkAvailable performs a real write-probe against the
+ * audit directory (mkdir + append + unlink a sidecar file) so a caller can
+ * distinguish "sink healthy" from "sink down" (read-only filesystem, missing
+ * mount, permissions) before deciding whether to proceed. Enterprise mode's
+ * mandatory-audit gate (lib/policy/audit-gate.mjs) fails closed on this
+ * check; solo/team never call it.
  */
-import { readFileSync, existsSync, statSync, mkdirSync } from 'node:fs';
+import { readFileSync, existsSync, statSync, mkdirSync, appendFileSync, unlinkSync } from 'node:fs';
 import { createHash } from 'node:crypto';
 import { join, dirname } from 'node:path';
 
 import { appendBounded, readLastLineAcrossSegments } from './logging/rotate.mjs';
 import { withFileLockSync } from './storage/file-lock.mjs';
 import { doctorRoot } from './config/xdg.mjs';
+import { __resolvedSecretValues } from './providers/secret-resolver.mjs';
 
 const AUDIT_FILE = join(doctorRoot(), 'audit-trail.jsonl');
 
@@ -32,17 +49,183 @@ function sha256(input) {
   return createHash('sha256').update(input).digest('hex');
 }
 
+export class AuditSinkUnavailableError extends Error {
+  constructor(message, { file, reason } = {}) {
+    super(message);
+    this.name = 'AuditSinkUnavailableError';
+    this.file = file ?? null;
+    this.reason = reason ?? null;
+  }
+}
+
+// A real write-probe, not a stat/existsSync check: a directory can exist and
+// still refuse writes (read-only remount, quota, permission drop after
+// mkdir). Writing and removing a sidecar file physically exercises the same
+// path appendAuditRecord will take next, so "available" here means the next
+// real append is actually expected to succeed.
+
+export function checkAuditSinkAvailable({ file = AUDIT_FILE } = {}) {
+  const dir = dirname(file);
+  const probePath = join(dir, `.audit-sink-probe-${process.pid}-${Date.now()}`);
+  try {
+    mkdirSync(dir, { recursive: true });
+    appendFileSync(probePath, 'probe\n', 'utf8');
+    unlinkSync(probePath);
+    return { available: true, reason: null };
+  } catch (err) {
+    return { available: false, reason: err?.code || err?.message || 'unknown-error' };
+  }
+}
+
+// Built-in token shapes seen in the wild across providers: generic Bearer
+// headers, GitHub PATs (ghp_), Slack bot/user/app tokens (xoxb/xoxp/xoxa),
+// OpenAI-style secret keys (sk-), and 1Password references (op://...). Each
+// pattern is tagged with a `kind` so the replacement reads `<redacted:kind>`
+// rather than a single opaque marker, which keeps audit records diagnosable.
+
+const BUILTIN_PATTERNS = [
+  { kind: 'bearer-token', re: /\bBearer\s+[A-Za-z0-9\-._~+/]+=*/g },
+  { kind: 'github-token', re: /\bghp_[A-Za-z0-9]{20,}\b/g },
+  { kind: 'slack-token', re: /\bxox[bpa]-[A-Za-z0-9-]{10,}\b/g },
+  { kind: 'api-key', re: /\bsk-[A-Za-z0-9]{16,}\b/g },
+  { kind: 'op-reference', re: /\bop:\/\/[^\s'"]+/g },
+];
+
+// Custom patterns a caller wires in at startup (e.g. an org-specific token
+// shape). Kept process-local and additive over BUILTIN_PATTERNS; never
+// persisted, so a test or embedder can register/reset freely.
+
+let customPatterns = [];
+
+/**
+ * Register additional redaction patterns beyond the built-in token shapes.
+ * Each entry is `{ kind, re }` where `re` is a global RegExp. Replaces the
+ * full custom set on every call so a caller can reconfigure cleanly.
+ *
+ * @param {{kind:string, re:RegExp}[]} patterns
+ */
+export function configureRedactionPatterns(patterns = []) {
+  customPatterns = Array.isArray(patterns) ? patterns.filter((p) => p && p.re instanceof RegExp && typeof p.kind === 'string') : [];
+}
+
+export function __resetRedactionPatterns() {
+  customPatterns = [];
+}
+
+// Secret values below this length are excluded from the known-value pass:
+// short resolved values (flags, single-char tokens) produce false-positive
+// redactions in ordinary prose.
+
+const MIN_KNOWN_SECRET_LENGTH = 8;
+
+function escapeRegExp(str) {
+  return str.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+
+// A resolved secret is redacted by exact substring match, not by first
+// hashing the haystack — a hash comparison can only ever confirm equality of
+// two already-known values, never locate an unknown-length substring inside
+// arbitrary free text. Instead, the "hashed comparison" the caller performs
+// (recorded in the audit count, see below) is against sha256(value) so the
+// count event that leaves the process never carries a byte of the plaintext,
+// even though the in-process match itself must touch the plaintext to redact
+// it — the same value already lives in secret-resolver's own cache in-process.
+
+function knownSecretPatterns() {
+  const values = __resolvedSecretValues().filter(
+    (v) => typeof v === 'string' && v.length >= MIN_KNOWN_SECRET_LENGTH,
+  );
+  return values.map((value) => ({
+    kind: 'known-secret',
+    re: new RegExp(escapeRegExp(value), 'g'),
+    hash: sha256(value),
+  }));
+}
+
+// lib/providers/secret-audit-wiring.mjs already records the op:// reference
+// itself (never the resolved value) under these exact key names as its
+// value-free diagnostic contract — a bare op://vault/item/field pointer is
+// not a secret, so the op-reference pattern must not clobber it there. Any
+// other field carrying an op:// string (a tool result body, a raw env dump)
+// is still redacted.
+
+const OP_REF_EXEMPT_KEYS = new Set(['ref']);
+
+// Walk every string reachable in `value`, applying every pattern in turn and
+// replacing matches with `<redacted:kind>`. Returns the redacted clone plus a
+// count-only tally (kind → number of matches) so the caller can audit that
+// redaction occurred without ever recording the matched text.
+
+function redactString(str, patterns, tally) {
+  let out = str;
+  for (const { kind, re } of patterns) {
+    re.lastIndex = 0;
+    const matches = out.match(re);
+    if (matches && matches.length) {
+      tally[kind] = (tally[kind] || 0) + matches.length;
+      out = out.replace(re, `<redacted:${kind}>`);
+    }
+  }
+  return out;
+}
+
+function redactValue(value, patterns, tally, key = null) {
+  if (typeof value === 'string') {
+    if (key && OP_REF_EXEMPT_KEYS.has(key)) {
+      const rest = patterns.filter((p) => p.kind !== 'op-reference');
+      return redactString(value, rest, tally);
+    }
+    return redactString(value, patterns, tally);
+  }
+  if (Array.isArray(value)) return value.map((v) => redactValue(v, patterns, tally));
+  if (value && typeof value === 'object') {
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+      // Schema-marked redacted:true fields are already elided upstream by the
+      // caller's own schema; this pass is a second, pattern-based net over
+      // whatever free-text fields (detail, args, result, payload) remain.
+      out[k] = redactValue(v, patterns, tally, k);
+    }
+    return out;
+  }
+  return value;
+}
+
+/**
+ * Redact known secret values and token-shaped strings from an audit record.
+ * Runs BEFORE the chain hash is computed so the signature always covers the
+ * redacted form (redact-then-sign). Returns `{ record, tally }` where tally
+ * is a count-only map of kind → matches (never the matched text).
+ *
+ * @param {object} partial
+ * @returns {{record: object, tally: Record<string, number>}}
+ */
+export function redactRecord(partial) {
+  const patterns = [...BUILTIN_PATTERNS, ...customPatterns, ...knownSecretPatterns()];
+  const tally = {};
+  const record = redactValue(partial, patterns, tally);
+  return { record, tally };
+}
+
 // prev_line_hash and the append must be one atomic step or concurrent writers
 // race; the file lock serializes them across processes.
 
 export function appendAuditRecord(partial, { file = AUDIT_FILE } = {}) {
+  const { record: redacted, tally } = redactRecord(partial);
+
+  // Redaction is itself audited as a count only — never the secret — folded
+  // into the record's own field before it is hashed and written, so the
+  // signed line and the returned record always agree.
+
+  if (Object.keys(tally).length) redacted.redaction_counts = tally;
+
   return withFileLockSync(file, () => {
     let prev = null;
     try {
       const last = readLastLineAcrossSegments(file);
       if (last !== null) prev = sha256(last);
     } catch { /* first record, or unreadable tail */ }
-    const record = { ...partial, prev_line_hash: prev };
+    const record = { ...redacted, prev_line_hash: prev };
     mkdirSync(dirname(file), { recursive: true });
     appendBounded('audit-trail', file, JSON.stringify(record) + '\n');
     return record;

package/lib/beads/auto-close.mjs

@@ -21,6 +21,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { isMainModule } from '../roots.mjs';
 
 const CLOSES_RE = /\b(?:closes?|close|fix(?:es)?|fixed|resolves?|resolved)\s+(construct-[a-z0-9]+)/gi;
 
@@ -105,7 +106,7 @@ export async function runAutoClose({ range, runner = spawnSync } = {}) {
 }
 
 // CLI entry: read --range, run, print summary.
-const invokedDirectly = import.meta.url === `file://${process.argv[1]}`;
+const invokedDirectly = isMainModule(import.meta.url);
 if (invokedDirectly) {
   const args = process.argv.slice(2);
   const rangeArg = args.find((a) => a.startsWith('--range='));

package/lib/beads/drift.mjs

@@ -25,6 +25,7 @@
  */
 
 import { spawnSync } from 'node:child_process';
+import { isMainModule } from '../roots.mjs';
 
 const DEFAULT_STALE_OPEN_DAYS = 14;
 const DEFAULT_STUCK_IN_PROGRESS_DAYS = 3;
@@ -166,7 +167,7 @@ export function formatDriftReport(report) {
 }
 
 // CLI: print report, exit non-zero when thresholds breached unless --report-only.
-const invokedDirectly = import.meta.url === `file://${process.argv[1]}`;
+const invokedDirectly = isMainModule(import.meta.url);
 if (invokedDirectly) {
   const args = process.argv.slice(2);
   const json = args.includes('--json');

package/lib/bridges/copilot-proxy.mjs

@@ -23,18 +23,33 @@ async function getCopilotToken() {
   }
 }
 
-const server = http.createServer(async (req, res) => {
-  // CORS
-  res.setHeader('Access-Control-Allow-Origin', '*');
-  res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
-  res.setHeader('Access-Control-Allow-Headers', '*');
+// Fail closed: the bridge fronts the user's Copilot entitlement, so every request
+// must carry the per-launch bearer token service-manager injects, and an unconfigured
+// token means no access at all. No CORS headers are emitted — the only legitimate
+// caller is a loopback server process (OpenCode), never a browser page, so a wildcard
+// Access-Control-Allow-Origin would just let any open tab drive the entitlement.
+
+const EXPECTED_TOKEN = process.env.CONSTRUCT_COPILOT_BRIDGE_TOKEN || null;
+
+function isAuthorized(req) {
+  if (!EXPECTED_TOKEN) return false;
+  const match = String(req.headers.authorization || '').match(/^Bearer\s+(.+)$/i);
+  return Boolean(match) && match[1] === EXPECTED_TOKEN;
+}
 
+const server = http.createServer(async (req, res) => {
   if (req.method === 'OPTIONS') {
     res.writeHead(204);
     res.end();
     return;
   }
 
+  if (!isAuthorized(req)) {
+    res.writeHead(401, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ error: 'Unauthorized: missing or invalid bridge bearer token.' }));
+    return;
+  }
+
   if (req.url === '/v1/chat/completions' && req.method === 'POST') {
     const token = await getCopilotToken();
     if (!token) {

package/lib/certification/skill-inventory.mjs

@@ -13,6 +13,7 @@ import { createHash } from 'node:crypto';
 import { artifactTypes, loadArtifactManifest } from '../artifact-manifest.mjs';
 import { validateSkillEffectiveness } from '../validators/skill-effectiveness.mjs';
 import { collectScopeRoleIds } from '../scopes/enrich.mjs';
+import { bindingForSpecialist } from '../roles/flavor-bindings.mjs';
 
 function findConstructRoot(startPath = process.cwd()) {
   let current = path.resolve(startPath);
@@ -95,7 +96,7 @@ function verificationHooks(meta, body) {
 }
 
 function resolveOwners(skillId, { registry, declaredSkills, ownerBases }) {
-  if (skillId.startsWith('brand/')) return ['cx-docs-keeper'];
+  if (skillId.startsWith('brand/')) return ['cx-operations'];
   const owners = new Set();
   for (const agent of Object.values(registry.specialists ?? {})) {
     if ((agent.skills ?? []).includes(skillId)) owners.add(`cx-${agent.name}`);
@@ -107,6 +108,14 @@ function resolveOwners(skillId, { registry, declaredSkills, ownerBases }) {
     }
     if (!owners.size) owners.add(`scope-role:${base}`);
   }
+  // A roles/*.md overlay's base name is not always a live specialist name —
+  // some overlays are skill bundles loaded onto a differently-named anchor.
+  // lib/roles/flavor-bindings.mjs is the source of truth for which
+  // specialist actually loads a given overlay; fall back to it here.
+  if (base && owners.size === 0) {
+    const binding = bindingForSpecialist(base);
+    if (binding?.specialistId) owners.add(binding.specialistId);
+  }
   if (declaredSkills.has(skillId) && owners.size === 0) {
     for (const agent of Object.values(registry.specialists ?? {})) {
       if ((agent.skills ?? []).includes(skillId)) owners.add(`cx-${agent.name}`);

package/lib/cli/approvals.mjs

@@ -0,0 +1,147 @@
+/**
+ * lib/cli/approvals.mjs — `construct approvals` CLI handler.
+ *
+ * Loads the ApprovalQueue from the appropriate persistence path and
+ * implements list / approve / deny / status subcommands.
+ *
+ * `approve` is the operator's decision point and the sole production drain
+ * for J6 governed write intents: once a record whose tool names a known
+ * governed provider (jira/github/confluence) is approved, the control plane
+ * (lib/writes/control-plane.mjs) executes it through the J2 envelope — the
+ * only place recommend becomes execute. Non-write-intent approvals (embed
+ * tool proposals) are left for their own runtime to act on and are not
+ * touched here.
+ */
+
+import { ApprovalQueue } from '../embed/approval-queue.mjs';
+import { getDeploymentMode } from '../deployment-mode.mjs';
+import { executeApprovedWriteIntent } from '../writes/control-plane.mjs';
+import { parseWriteIntentToolName, KNOWN_PROVIDERS } from '../writes/write-intent.mjs';
+
+/**
+ * Run the approvals CLI command.
+ * @param {string[]} args
+ * @param {object} ctx
+ * @param {string} ctx.rootDir
+ * @param {string} ctx.homeDir
+ * @param {object} ctx.env
+ * @param {Function} ctx.println
+ * @param {Function} ctx.errorln
+ * @returns {number} exit code
+ */
+export async function runApprovalsCli(args, { rootDir, homeDir, env, println, errorln }) {
+  const sub = args[0];
+  if (!sub || sub === '--help' || sub === '-h') {
+    println('Usage: construct approvals <list|approve|deny|status>');
+    println('');
+    println('Subcommands:');
+    println('  list              List pending approvals');
+    println('  approve <id>      Approve a pending approval by id');
+    println('  deny <id>         Deny a pending approval by id');
+    println('  status <id>       Show full status of a specific approval');
+    return 0;
+  }
+
+  const deploymentMode = getDeploymentMode(env, { cwd: rootDir });
+  const persistPath = ApprovalQueue.resolvePersistPath(rootDir, deploymentMode);
+  const queue = new ApprovalQueue({ persistPath });
+
+  if (sub === 'list') {
+    const pending = queue.getPending();
+    if (pending.length === 0) {
+      println('No pending approvals.');
+      return 0;
+    }
+    for (const r of pending) {
+      const rb = r.requestedBy || {};
+      const by = rb.role || rb.userId || rb.serviceId || 'unknown';
+      println(`${r.approvalId}`);
+      println(`  tool:        ${r.toolCall?.tool || '?'}`);
+      println(`  requestedAt: ${r.requestedAt}`);
+      println(`  requestedBy: ${by}`);
+      println(`  expiresAt:   ${r.expiresAt}`);
+      println('');
+    }
+    return 0;
+  }
+
+  if (sub === 'approve') {
+    const id = args[1];
+    if (!id) {
+      errorln('Usage: construct approvals approve <id>');
+      return 1;
+    }
+    try {
+      const record = queue.approve(id, {
+        decidedBy: {
+          role: process.env.CONSTRUCT_ROLE || 'cli-operator',
+          userId: process.env.USER || process.env.USERNAME || null,
+          source: 'cli',
+        },
+      });
+      println(`Approved: ${record.approvalId} (tool: ${record.toolCall?.tool})`);
+
+      // Only a governed write intent (tool "<provider>.<kind>" naming a known
+      // governed provider) is executed here; anything else is another
+      // runtime's proposal and stays untouched.
+
+      const parsed = parseWriteIntentToolName(record.toolCall?.tool);
+      if (parsed && KNOWN_PROVIDERS.includes(parsed.providerId)) {
+        try {
+          const result = await executeApprovedWriteIntent(record, { rootDir });
+          println(`Executed ${parsed.providerId}.${parsed.writeKind} via control plane (status: ${result?.status ?? 'unknown'})`);
+        } catch (execErr) {
+          errorln(`Approved, but control-plane execution failed: ${execErr.message}`);
+          return 1;
+        }
+      }
+      return 0;
+    } catch (err) {
+      errorln(`Error: ${err.message}`);
+      return 1;
+    }
+  }
+
+  if (sub === 'deny') {
+    const id = args[1];
+    if (!id) {
+      errorln('Usage: construct approvals deny <id> [--reason=...]');
+      return 1;
+    }
+    const reasonFlag = args.find((a) => a.startsWith('--reason='));
+    const reason = reasonFlag ? reasonFlag.slice('--reason='.length) : 'denied by operator';
+    try {
+      const record = queue.deny(id, {
+        decidedBy: {
+          role: process.env.CONSTRUCT_ROLE || 'cli-operator',
+          userId: process.env.USER || process.env.USERNAME || null,
+          source: 'cli',
+        },
+        reason,
+      });
+      println(`Denied: ${record.approvalId} (reason: ${reason})`);
+      return 0;
+    } catch (err) {
+      errorln(`Error: ${err.message}`);
+      return 1;
+    }
+  }
+
+  if (sub === 'status') {
+    const id = args[1];
+    if (!id) {
+      errorln('Usage: construct approvals status <id>');
+      return 1;
+    }
+    const record = queue.getById(id);
+    if (!record) {
+      errorln(`Approval not found: ${id}`);
+      return 1;
+    }
+    println(JSON.stringify(record, null, 2));
+    return 0;
+  }
+
+  errorln(`Unknown approvals subcommand: ${sub}. Available: list, approve, deny, status`);
+  return 1;
+}