@ijfw/memory-server 1.4.3 → 1.5.0

package/src/cross-orchestrator-cli.js

@@ -14,6 +14,7 @@ import { homedir } from 'node:os';
 import { spawnSync } from 'node:child_process';
 import { writeAtomic } from './lib/atomic-io.js';
 import { runCrossOp } from './cross-orchestrator.js';
+import { chunkText, mergeFindings, CHUNKER_DEFAULTS } from './cross-audit-chunker.js';
 import { readReceipts, purgeReceipts } from './receipts.js';
 import { renderHeroLine } from './hero-line.js';
 import { ROSTER, isInstalled, isReachable } from './audit-roster.js';
@@ -21,16 +22,27 @@ import { aggregatePortfolioFindings } from './cross-project-search.js';
 import { runImport, runImportAll, listImporters } from './importers/cli.js';
 import { validateToken } from './lib/token.js';
 import { isVersionStringValid } from './lib/npm-view.js';
+import { verifyShasumCrossSource } from './lib/shasum-verify.js';
 import {
   addBlackboardNote,
   blackboardStatus,
   claimArtifact,
+  DEFAULT_CLAIM_TTL_MS,
+  evictOrphanedClaims,
   initBlackboard,
   readBlackboard,
   releaseClaim,
+  updateClaimHeartbeat,
   writeHandoff,
 } from './blackboard.js';
 import { createTeamAssembly, readTeamAssembly } from './team/generator.js';
+import {
+  addTeamRole,
+  checkTeamAssembly,
+  listTeamRoles,
+  removeTeamRole,
+  swapTeamRole,
+} from './team/modify.js';
 import {
   blockSwarmTask,
   buildSwarmPlan,
@@ -274,17 +286,19 @@ function parseCrossAlias(mode, args) {
   let only = null;
   let confirm = false;
   let expand = false;
+  let chunk = false;
   const positional = [];
   for (let i = 1; i < args.length; i++) {
     const arg = args[i];
     if (arg === '--confirm') confirm = true;
     else if (arg === '--expand') expand = true;
+    else if (arg === '--chunk') chunk = true; // v1.5.1 H1.6 — wire chunker
     else if (arg === '--with' && args[i + 1]) only = args[++i];
     else if (arg.startsWith('--with=')) only = arg.slice('--with='.length);
     else if (!arg.startsWith('--')) positional.push(arg);
   }
   const target = mode === 'research' ? positional.join(' ').trim() : positional[0];
-  return { cmd: 'cross', mode, target: target || undefined, only, confirm, expand };
+  return { cmd: 'cross', mode, target: target || undefined, only, confirm, expand, chunk };
 }
 
 function parseCommandAlias(args) {
@@ -396,6 +410,23 @@ function parseArgsInner(args) {
     return { cmd: 'design', sub: args[1] || 'status' };
   }
 
+  // v1.5.0 wire-W1.D — `ijfw ui-review --spec <path> --scope <dirs>`
+  if (args[0] === 'ui-review') {
+    const opts = { cmd: 'ui-review', spec: null, scope: null, write: true, gcSketches: false, peerInputs: null };
+    for (let i = 1; i < args.length; i++) {
+      const a = args[i];
+      if ((a === '--spec' || a === '-s') && args[i + 1]) { opts.spec = args[++i]; }
+      else if (a.startsWith('--spec=')) opts.spec = a.slice('--spec='.length);
+      else if ((a === '--scope' || a === '-S') && args[i + 1]) { opts.scope = args[++i]; }
+      else if (a.startsWith('--scope=')) opts.scope = a.slice('--scope='.length);
+      else if (a === '--no-write') opts.write = false;
+      else if (a === '--gc-sketches') opts.gcSketches = true;
+      else if ((a === '--peer-inputs') && args[i + 1]) { opts.peerInputs = args[++i]; }
+      else if (a.startsWith('--peer-inputs=')) opts.peerInputs = a.slice('--peer-inputs='.length);
+    }
+    return opts;
+  }
+
   if (args[0] === 'blackboard') {
     return { cmd: 'blackboard', sub: args[1] || 'status' };
   }
@@ -464,14 +495,16 @@ function parseArgsInner(args) {
     let only = null;
     let confirm = false;
     let expand = false;
+    let chunk = false;
 
     for (let i = 3; i < args.length; i++) {
       if (args[i] === '--confirm') { confirm = true; }
       else if (args[i] === '--expand') { expand = true; }
+      else if (args[i] === '--chunk') { chunk = true; } // v1.5.1 H1.6 — wire chunker
       else if (args[i] === '--with' && args[i + 1]) { only = args[++i]; }
     }
 
-    return { cmd: 'cross', mode, target, only, confirm, expand };
+    return { cmd: 'cross', mode, target, only, confirm, expand, chunk };
   }
 
   return { cmd: 'unknown', raw: args[0] };
@@ -877,6 +910,15 @@ function cmdPurgeReceipts(projectDir) {
 // ranges, and non-existent paths pass through unchanged.
 const TARGET_FILE_SIZE_CAP = 64 * 1024; // 64 KB -- leaves prompt headroom
 
+// r17.1 — size thresholds for pre-flight advisory. Inputs under WARN are
+// silent; WARN..CAP get a one-line "this might be slow" advisory; CAP..MAX
+// get a "this WILL be truncated, consider chunking" warning before we fire
+// any auditor (so the user can cancel rather than burn wall time). Anything
+// over MAX would be silently truncated by resolveTarget anyway — the
+// pre-flight check makes that loud.
+const TARGET_FILE_SIZE_WARN = 32 * 1024;
+const TARGET_FILE_SIZE_MAX  = 256 * 1024; // beyond this, advise chunking explicitly
+
 export function resolveTarget(raw, opts = {}) {
   const cap = typeof opts.sizeCap === 'number' ? opts.sizeCap : TARGET_FILE_SIZE_CAP;
   if (typeof raw !== 'string' || !raw) return raw;
@@ -921,7 +963,44 @@ export function resolveTarget(raw, opts = {}) {
   return `File: ${raw}\n\n${contents}`;
 }
 
-async function cmdCross({ mode, target, only, confirm, expand }) {
+// v1.5.1 H1.6 — chunked-dispatch helpers (audit finding token-optimization.md
+// HIGH-H4 + trident.md HIGH-1, 2/2 consensus). The chunker has shipped (with
+// tests) since r17.1 but was never wired into the CLI. `--chunk` now triggers
+// per-chunk dispatch through runCrossOp + a final Jaccard-dedupe merge.
+
+/**
+ * Decide whether a target absolute path is large enough to benefit from
+ * chunking. Exported for unit-tests.
+ */
+export function shouldChunkFile(absPath, opts = {}) {
+  const threshold = typeof opts.threshold === 'number' ? opts.threshold : TARGET_FILE_SIZE_CAP;
+  try {
+    const st = statSync(absPath);
+    if (!st.isFile()) return false;
+    return st.size > threshold;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Read a file and produce the per-chunk target strings the auditors will see.
+ * Each chunk is annotated with its index so cross-chunk findings can be
+ * reconciled. Exported for unit-tests.
+ */
+export function buildChunkedTargets(absPath, rawTarget, opts = {}) {
+  const content = readFileSync(absPath, 'utf8');
+  const chunks = chunkText(content, opts);
+  return chunks.map((c, i) => ({
+    chunkIndex: i,
+    total: chunks.length,
+    bytesStart: c.start,
+    bytesEnd: c.end,
+    target: `File: ${rawTarget} [chunk ${i + 1}/${chunks.length}, bytes ${c.start}-${c.end}]\n\n${c.text}`,
+  }));
+}
+
+async function cmdCross({ mode, target, only, confirm, expand, chunk }) {
   const VALID_MODES = ['audit', 'research', 'critique'];
   if (!mode || !VALID_MODES.includes(mode)) {
     console.error(`ijfw cross requires a mode: ${VALID_MODES.join(', ')}. Example: ijfw cross audit <file>`);
@@ -935,6 +1014,114 @@ async function cmdCross({ mode, target, only, confirm, expand }) {
   // Issue #6 fix: substitute file contents for path string when target is a
   // regular file. Keep the raw target for the user-facing echo line.
   const rawTarget = target;
+
+  // r17.1 — pre-flight size advisory. Run BEFORE resolveTarget truncates,
+  // so the user sees the real number and can decide to abort + chunk the
+  // input themselves rather than getting a silently-truncated audit.
+  // r17-M3: resolve relative paths against cwd FIRST, matching the same
+  // resolution resolveTarget() uses. Without this, `ijfw cross audit foo.md`
+  // (a relative path that exists) would skip the advisory because
+  // existsSync(rawTarget) probes against the wrong cwd-anchor.
+  try {
+    let probePath = null;
+    if (typeof rawTarget === 'string' && rawTarget.length < 4096) {
+      const resolved = isAbsolute(rawTarget) ? rawTarget : resolve(process.cwd(), rawTarget);
+      if (existsSync(resolved)) probePath = resolved;
+    }
+    if (probePath) {
+      const st = statSync(probePath);
+      if (st.isFile()) {
+        if (st.size > TARGET_FILE_SIZE_MAX) {
+          console.log('');
+          console.log(`Heads up -- target is ${(st.size / 1024).toFixed(1)} KB, larger than the ${(TARGET_FILE_SIZE_MAX / 1024).toFixed(0)} KB recommended max.`);
+          console.log(`Auditors will see only the first ${(TARGET_FILE_SIZE_CAP / 1024).toFixed(0)} KB (truncated). For full coverage, chunk the target into smaller files and audit each, OR pass --chunk to auto-split (see \`ijfw cross --help\`).`);
+        } else if (st.size > TARGET_FILE_SIZE_CAP) {
+          console.log('');
+          console.log(`Note: target is ${(st.size / 1024).toFixed(1)} KB; auditors will see the first ${(TARGET_FILE_SIZE_CAP / 1024).toFixed(0)} KB and a truncation marker. Findings beyond that point will be missed.`);
+        } else if (st.size > TARGET_FILE_SIZE_WARN) {
+          console.log('');
+          console.log(`Note: target is ${(st.size / 1024).toFixed(1)} KB; expect a slower wall time (gemini in particular may push the 90s budget).`);
+        }
+      }
+    }
+  } catch { /* statSync failure is non-fatal; size advisory is best-effort */ }
+
+  // v1.5.1 H1.6 — chunked dispatch path. When --chunk is set AND the target
+  // is a file larger than the size cap, split via the cross-audit-chunker
+  // (boundary-aware, 10% overlap, Jaccard-dedupe merge) and dispatch each
+  // chunk through runCrossOp separately. Merge findings at the end. Opt-in
+  // because cost scales linearly with chunk count.
+  if (chunk) {
+    let absPath = null;
+    try {
+      if (typeof rawTarget === 'string' && rawTarget.length < 4096) {
+        const resolved = isAbsolute(rawTarget) ? rawTarget : resolve(process.cwd(), rawTarget);
+        if (existsSync(resolved) && statSync(resolved).isFile()) absPath = resolved;
+      }
+    } catch { /* */ }
+
+    if (!absPath) {
+      console.log('');
+      console.log('--chunk requires a file target. Topics, git ranges, and missing paths cannot be chunked.');
+      // Fall through to normal path -- --chunk silently no-ops for non-files
+    } else if (!shouldChunkFile(absPath)) {
+      console.log('');
+      console.log(`--chunk: target is ${(statSync(absPath).size / 1024).toFixed(1)} KB, under the ${(TARGET_FILE_SIZE_CAP / 1024).toFixed(0)} KB chunk threshold; running single-pass audit instead.`);
+      // Fall through to normal path
+    } else {
+      const chunks = buildChunkedTargets(absPath, rawTarget);
+      console.log('');
+      console.log(`--chunk: splitting ${rawTarget} into ${chunks.length} chunks (≈${(CHUNKER_DEFAULTS.chunkSize / 1024).toFixed(0)} KB each, ${(CHUNKER_DEFAULTS.overlap / 1024).toFixed(0)} KB overlap).`);
+      console.log(`Trident dispatches: ${chunks.length} × per-chunk audit. Cost scales linearly.`);
+
+      const perChunkResults = [];
+      const auditorIds = new Set();
+      const projectDir = process.cwd();
+      let firedAny = false;
+      for (const { chunkIndex, total, target: chunkTarget } of chunks) {
+        console.log('');
+        console.log(`[chunk ${chunkIndex + 1}/${total}] dispatching...`);
+        try {
+          const r = await runCrossOp({
+            mode, target: chunkTarget, projectDir,
+            runStamp: new Date().toISOString(), only, confirm, expand,
+          });
+          const findings = Array.isArray(r.merged) ? r.merged : [];
+          perChunkResults.push({ chunkIndex, findings });
+          for (const p of (r.picks || [])) auditorIds.add(p.id);
+          if ((r.picks || []).length > 0) firedAny = true;
+          console.log(`[chunk ${chunkIndex + 1}/${total}] ${findings.length} finding(s) from ${(r.picks || []).length} auditor(s).`);
+        } catch (err) {
+          console.log(`[chunk ${chunkIndex + 1}/${total}] dispatch error: ${err.message}`);
+          perChunkResults.push({ chunkIndex, findings: [] });
+        }
+      }
+
+      const merged = mergeFindings(perChunkResults);
+      console.log('');
+      console.log(`=== Chunked audit complete: ${merged.length} unique finding(s) across ${chunks.length} chunks ===`);
+      console.log(`Auditors fired (union): ${[...auditorIds].join(', ') || '(none)'}`);
+      if (!firedAny) {
+        console.log('No auditors fired -- run `ijfw doctor` to see the install hints.');
+        process.exit(2); // r17.1 — degraded exit code
+      }
+      for (const f of merged) {
+        const sev = (f.severity || 'note').toUpperCase();
+        const cluster = f.clusterSize > 1 ? ` [×${f.clusterSize}]` : '';
+        const tgt = f.target ? ` ${f.target} —` : '';
+        // v1.5.0 wire-W4: widen field fallback to cover description/issue/
+        // detail/note/summary keys auditors emit. Closes the r19 "(no detail)"
+        // dropout that made adjudication a guessing game.
+        const text = f.finding || f.text || f.message ||
+                     f.description || f.issue ||
+                     f.detail || f.details || f.note || f.summary ||
+                     '(no detail)';
+        console.log(`  ${sev}${cluster}${tgt} ${text}`);
+      }
+      return;
+    }
+  }
+
   target = resolveTarget(target);
 
   // Polish 6: pre-flight reachability check. If no auditor is wired, give a
@@ -1006,6 +1193,18 @@ async function cmdCross({ mode, target, only, confirm, expand }) {
   printFindings(mode, merged);
 
   console.log('\nReceipt logged -- run `ijfw status` to see it.');
+
+  // r17.1 — structured exit code so CI scripts + orchestrator-LLM callers
+  // can detect degraded runs without scraping console output.
+  //   exit 0  — all picks contributed productively
+  //   exit 2  — at least one pick didn't contribute (timeout / failure / aborted)
+  //   exit 3  — zero picks contributed productively (INCONCLUSIVE verdict)
+  // exit 1 is reserved for argv / usage errors (already used above).
+  if (auditorResults && Array.isArray(auditorResults)) {
+    const productive = auditorResults.filter(r => r.counted === true || r.status === null || r.status === 'fallback-used');
+    if (productive.length === 0) process.exit(3);
+    if (productive.length < auditorResults.length) process.exit(2);
+  }
 }
 
 // ---------------------------------------------------------------------------
@@ -1314,16 +1513,100 @@ function cmpSemver(a, b) {
 
 function readState() { return readJsonSafe(join(ijfwHome(), 'state.json')) || {}; }
 function readSettings() { return readJsonSafe(join(ijfwHome(), 'settings.json')) || {}; }
-function writeStateFields(updates) {
-  const path = join(ijfwHome(), 'state.json');
-  const state = Object.assign(readState(), updates);
+
+// v1.5.0 audit M11 (F-REL-1): writeStateFields was best-effort — readState +
+// merge + writeAtomic was a TOCTOU window where a parallel `ijfw update`
+// completion could clobber another writer's `last_applied_version`. If the
+// write failed silently, the re-entrancy guard (last_applied_version >=
+// last_latest_seen) would never fire and every subsequent session would
+// nag-loop until manual `ijfw doctor`.
+//
+// Fix: serialise read-modify-write under a sync directory lock so the merge
+// happens against the latest disk state. We use a tiny inlined sync version
+// of `withFsLock` (mkdir-with-EEXIST is atomic on POSIX + NTFS) rather than
+// importing the async `fs-lock.js` — this whole CLI is sync top-to-bottom and
+// converting just-this-callsite to async would force every caller to await.
+//
+// On lock-acquire failure we still attempt the write (better than refusing to
+// persist) and surface the lock failure as a clearer error.
+const STATE_LOCK_DIR = () => join(ijfwHome(), '.state.lock');
+const STATE_LOCK_ACQUIRE_TIMEOUT_MS = 5000;
+const STATE_LOCK_STALE_MS = 30000;
+const STATE_LOCK_BACKOFF_START_MS = 25;
+const STATE_LOCK_BACKOFF_MAX_MS = 250;
+
+function withStateLockSync(fn) {
+  const lockDir = STATE_LOCK_DIR();
+  // Ensure parent exists; tolerate races.
+  try { mkdirSync(dirname(lockDir), { recursive: true, mode: 0o700 }); } catch { /* */ }
+
+  const deadline = Date.now() + STATE_LOCK_ACQUIRE_TIMEOUT_MS;
+  let staleRecoveryUsed = false;
+  let backoff = STATE_LOCK_BACKOFF_START_MS;
+  let acquired = false;
+
+  while (Date.now() < deadline) {
+    try {
+      mkdirSync(lockDir, { recursive: false });
+      acquired = true;
+      break;
+    } catch (err) {
+      if (err && err.code !== 'EEXIST') {
+        // Real FS error (EACCES, ENOENT on parent we couldn't create) —
+        // surface so the caller can fall back to best-effort write.
+        throw err;
+      }
+      // Stale recovery: if the lock dir is older than STATE_LOCK_STALE_MS,
+      // a previous holder crashed mid-write. Remove + retry once.
+      if (!staleRecoveryUsed) {
+        try {
+          const st = statSync(lockDir);
+          if (Date.now() - st.mtimeMs > STATE_LOCK_STALE_MS) {
+            staleRecoveryUsed = true;
+            rmSync(lockDir, { recursive: true, force: true });
+            continue;
+          }
+        } catch { /* lock vanished mid-stat; retry */ }
+      }
+      // Bounded busy-wait. Sync sleep via Atomics is heavy; use a tight loop
+      // with deadline check (typical contention is microseconds in practice).
+      const waitUntil = Date.now() + Math.min(backoff, STATE_LOCK_BACKOFF_MAX_MS, deadline - Date.now());
+      // eslint-disable-next-line no-empty
+      while (Date.now() < waitUntil) {}
+      backoff = Math.min(backoff * 2, STATE_LOCK_BACKOFF_MAX_MS);
+    }
+  }
+
+  if (!acquired) {
+    // Couldn't acquire — fall back to caller's fn anyway. Better to risk a
+    // racy write than to lose the re-entrancy guard entry.
+    try { return fn(); }
+    finally { /* no lock to release */ }
+  }
+
   try {
-    writeAtomic(path, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
-  } catch (e) {
-    console.error(`could not persist state.json: ${e.message}`);
+    return fn();
+  } finally {
+    try { rmSync(lockDir, { recursive: true, force: true }); } catch { /* */ }
   }
 }
 
+function writeStateFields(updates) {
+  const path = join(ijfwHome(), 'state.json');
+  withStateLockSync(() => {
+    // Re-read INSIDE the lock so we don't merge against a stale snapshot.
+    const state = Object.assign(readState(), updates);
+    try {
+      writeAtomic(path, JSON.stringify(state, null, 2) + '\n', { mode: 0o600 });
+    } catch (e) {
+      // M11: persist failure is now visible AND surfaces which field would
+      // not propagate. Re-entrancy guard relies on last_applied_version;
+      // log explicitly so `ijfw doctor` / a user reading logs can spot it.
+      console.error(`could not persist state.json (re-entrancy guard may not fire next session): ${e.message}`);
+    }
+  });
+}
+
 function cmdUpdateCheck() {
   const state = readState();
   const current = state.installed_version || '0.0.0';
@@ -1370,6 +1653,19 @@ function cmdUpdateVerify() {
   } else {
     console.log(`  provenance: NOT VERIFIED (audit signatures exited ${sig.status})`);
   }
+  // Second factor: shasum cross-verify (F-SEC-7). Dry-run: report but don't
+  // exit non-zero -- caller is asking "what would happen if I updated?", and
+  // the interactive flow already fails closed on mismatch.
+  const shasumDry = verifyShasumCrossSource(r.version);
+  if (shasumDry.mode === 'verified') {
+    console.log(`  shasum cross-verify: VERIFIED (${shasumDry.npmShasum.slice(0, 12)}...)`);
+  } else if (shasumDry.mode === 'mismatch') {
+    console.log(`  shasum cross-verify: MISMATCH (npm=${shasumDry.npmShasum} release=${shasumDry.releaseShasum}) -- install would be REFUSED`);
+  } else if (shasumDry.mode === 'advisory') {
+    console.log(`  shasum cross-verify: ADVISORY (${shasumDry.message})`);
+  } else {
+    console.log(`  shasum cross-verify: ERROR (${shasumDry.message})`);
+  }
   console.log('Verification complete.');
   process.exit(0);
 }
@@ -1545,6 +1841,37 @@ function cmdUpdateInteractive(opts = {}) {
       return 1;
     }
   }
+  // Shasum cross-verify (F-SEC-7): independent second factor on top of
+  // npm-side signatures. Fetches the GitLab release asset shasum and
+  // compares it against npm's dist.shasum for the same version. Mismatch
+  // means we refuse to install; advisory (release shasum unavailable)
+  // requires explicit --yes to proceed.
+  const shasum = verifyShasumCrossSource(r.version);
+  if (shasum.mode === 'verified') {
+    console.log(`  Shasum: verified (${shasum.npmShasum.slice(0, 12)}...)`);
+  } else if (shasum.mode === 'mismatch') {
+    console.error('  Shasum: MISMATCH -- refusing install.');
+    console.error(`    npm     : ${shasum.npmShasum}`);
+    console.error(`    release : ${shasum.releaseShasum}`);
+    console.error('  The npm tarball does NOT match the GitLab release asset.');
+    console.error('  This could indicate a compromised registry or release. Aborting.');
+    return 1;
+  } else if (shasum.mode === 'error') {
+    console.error(`  Shasum: error -- ${shasum.message}`);
+    console.error('  Refusing install: cannot establish second-factor integrity.');
+    return 1;
+  } else if (shasum.mode === 'advisory') {
+    console.error(`  Shasum: ADVISORY -- ${shasum.message}`);
+    if (!opts.yes) {
+      console.error('  Continuing requires --yes (acknowledge missing release shasum).');
+      return 1;
+    }
+    console.error('  Proceeding due to --yes; release shasum could not be verified.');
+  } else {
+    // Unknown mode: fail closed.
+    console.error(`  Shasum: unknown mode "${shasum.mode}" -- refusing install.`);
+    return 1;
+  }
   // Method dispatch
   const method = state.install_method || 'manual';
   console.log(`  install_method: ${method}`);
@@ -1637,8 +1964,17 @@ function cmdUpdateInteractive(opts = {}) {
     console.error(`Update did not complete (exit ${installRes.status}). State not written.`);
     return 1;
   }
-  // Persist both fields atomically -- single write avoids concurrent-reader inconsistency
-  writeStateFields({ last_applied_version: r.version, installed_version: r.version });
+  // Persist both fields atomically -- single write avoids concurrent-reader inconsistency.
+  // last_good_shasum records the shasum we just successfully cross-verified +
+  // installed (per docs/SECURITY.md "last_good_shasum is a one-way 'what did
+  // we actually install' record"). Only written when shasum was actually
+  // verified (mode === 'verified'); advisory paths leave the previous value
+  // so we don't poison the record with an unverified hash.
+  const stateUpdate = { last_applied_version: r.version, installed_version: r.version };
+  if (shasum && shasum.mode === 'verified' && shasum.npmShasum) {
+    stateUpdate.last_good_shasum = shasum.npmShasum;
+  }
+  writeStateFields(stateUpdate);
   console.log('');
   console.log(`IJFW updated to v${r.version}. Run \`ijfw status\` to confirm.`);
   return 0;
@@ -2059,6 +2395,8 @@ if (isMainModule) {
     cmdDashboard(parsed.sub);
   } else if (parsed.cmd === 'design') {
     cmdDesign(parsed.sub);
+  } else if (parsed.cmd === 'ui-review') {
+    cmdUiReview(parsed).catch(err => { console.error(err.message); process.exit(1); });
   } else if (parsed.cmd === 'blackboard') {
     cmdBlackboard(parsed.sub);
   } else if (parsed.cmd === 'team') {
@@ -2158,6 +2496,69 @@ function openDesignUrl(url) {
   return res.status ?? 0;
 }
 
+// v1.5.0 wire-W1.D — `ijfw ui-review` production CLI. Wires the 7-pillar
+// audit runner into a user-facing command. Args:
+//   --spec <UI-SPEC.md path>           required
+//   --scope <comma-sep dirs>           required (e.g. "src,components")
+//   --no-write                         skip writing UI-REVIEW.md (preview mode)
+//   --gc-sketches                      run sketches-gc as the finalizer
+//   --peer-inputs <json-path>          optional axe / lighthouse / playwright
+//                                      pre-computed outputs (JSON file)
+//   --json                             machine-readable output (skip narrative)
+async function cmdUiReview(parsed) {
+  if (!parsed.spec) {
+    console.error('Usage: ijfw ui-review --spec <UI-SPEC.md> --scope <dirs> [--no-write] [--gc-sketches] [--peer-inputs <path>]');
+    process.exit(1);
+  }
+  if (!parsed.scope) {
+    console.error('ui-review: --scope is required (comma-separated dirs, e.g. "src,components")');
+    process.exit(1);
+  }
+  const specPath = isAbsolute(parsed.spec) ? parsed.spec : resolve(process.cwd(), parsed.spec);
+  if (!existsSync(specPath)) {
+    console.error(`ui-review: UI-SPEC not found at ${specPath}`);
+    process.exit(1);
+  }
+
+  let peerInputs = {};
+  if (parsed.peerInputs) {
+    const ppath = isAbsolute(parsed.peerInputs) ? parsed.peerInputs : resolve(process.cwd(), parsed.peerInputs);
+    try { peerInputs = JSON.parse(readFileSync(ppath, 'utf8')); }
+    catch (err) {
+      console.error(`ui-review: failed to read --peer-inputs JSON: ${err.message}`);
+      process.exit(1);
+    }
+  }
+
+  const { runUiReview } = await import('./lib/ui-review-runner.js');
+  const result = await runUiReview({
+    uiSpecPath: specPath,
+    sourceScope: parsed.scope,
+    projectRoot: process.cwd(),
+    peerInputs,
+    write: parsed.write !== false,
+    gcSketches: !!parsed.gcSketches,
+  });
+
+  if (parsed.json) {
+    console.log(JSON.stringify({
+      topVerdict: result.topVerdict,
+      pillarVerdicts: result.pillarVerdicts,
+      reviewPath: result.reviewPath,
+      parallel: result.parallel,
+    }, null, 2));
+  } else {
+    console.log(`UI review: top-level ${result.topVerdict}`);
+    for (const [pillar, verdict] of Object.entries(result.pillarVerdicts)) {
+      console.log(`  - ${pillar.padEnd(12)} ${verdict}`);
+    }
+    if (result.reviewPath) console.log(`Review written to: ${result.reviewPath}`);
+    console.log(`Parallel grader run: wall=${result.parallel.wallMs}ms parallelism=${result.parallel.parallelism}`);
+  }
+  // Exit code: PASS=0, FLAG=0 (advisory), BLOCK=2 (ship-blocker)
+  process.exit(result.topVerdict === 'BLOCK' ? 2 : 0);
+}
+
 function cmdDesign(sub) {
   const contentDir = join(homedir(), '.ijfw', 'design-companion', 'content');
   mkdirSync(contentDir, { recursive: true });
@@ -2369,8 +2770,11 @@ function cmdTeam(sub) {
   if (sub === 'init' || sub === 'create') {
     const archetype = optionValue(args, ['--archetype', '--type', '-t']);
     const teamName = optionValue(args, ['--name']);
+    // F-FUN-1: --brief lets the Discovery hand-off carry domain signal
+    // when filesystem detection would otherwise collapse to mixed/unknown.
+    const brief = optionValue(args, ['--brief', '-b']) || '';
     const force = args.includes('--force');
-    const result = createTeamAssembly(process.cwd(), { archetype, teamName, force });
+    const result = createTeamAssembly(process.cwd(), { archetype, teamName, brief, force });
     if (!result.ok) {
       if (result.error === 'exists') {
         console.error('Team assembly already exists. Re-run with --force to replace .ijfw/team/charter.json and workflow.json.');
@@ -2405,7 +2809,101 @@ function cmdTeam(sub) {
     process.exit(0);
   }
 
-  console.log('Usage: ijfw team init [--archetype <type>] [--name <team-name>] [--force] | status');
+  // F-FUN-4 (audit-MED-teams-#7): ijfw team list -- enumerate roles.
+  if (sub === 'list') {
+    const result = listTeamRoles(process.cwd());
+    if (!result.ok) {
+      console.error(`team list failed: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(`Team: ${result.team_name || '(unnamed)'}`);
+    if (result.project_archetypes.length) console.log(`Archetypes: ${result.project_archetypes.join(', ')}`);
+    console.log(`Roles (${result.roles.length}):`);
+    for (const role of result.roles) {
+      console.log(`  - ${role.name} [${role.role_type}] model=${role.model} effort=${role.effort}`);
+    }
+    process.exit(0);
+  }
+
+  // F-FUN-4: ijfw team add <role-name> --charter <path>
+  if (sub === 'add') {
+    const name = args[0] && !args[0].startsWith('--') ? args[0] : null;
+    const charterPath = optionValue(args, ['--charter', '-c']);
+    if (!charterPath) {
+      console.error('Usage: ijfw team add <role-name> --charter <path-to-role.json>');
+      process.exit(1);
+    }
+    const result = addTeamRole(process.cwd(), { charterPath });
+    if (!result.ok) {
+      console.error(`team add failed: ${result.error}`);
+      if (result.errors) result.errors.forEach((e) => console.error(`  - ${e}`));
+      process.exit(1);
+    }
+    console.log(`Added role: ${result.role.name}`);
+    if (name && name !== result.role.name) {
+      console.log(`  note: charter declared name "${result.role.name}", ignoring CLI argument "${name}"`);
+    }
+    if (result.codex?.ok) console.log(`Codex agents resynced: ${result.codex.count} (${result.codex.skipped ?? 0} unchanged)`);
+    process.exit(0);
+  }
+
+  // F-FUN-4: ijfw team remove <role-name>
+  if (sub === 'remove' || sub === 'rm') {
+    const name = args[0] && !args[0].startsWith('--') ? args[0] : null;
+    if (!name) {
+      console.error('Usage: ijfw team remove <role-name>');
+      process.exit(1);
+    }
+    const result = removeTeamRole(process.cwd(), { name });
+    if (!result.ok) {
+      console.error(`team remove failed: ${result.error}`);
+      if (result.errors) result.errors.forEach((e) => console.error(`  - ${e}`));
+      process.exit(1);
+    }
+    console.log(`Removed role: ${result.removed}`);
+    if (result.codex?.ok) console.log(`Codex agents resynced: ${result.codex.count} (${result.codex.skipped ?? 0} unchanged)`);
+    process.exit(0);
+  }
+
+  // F-FUN-4: ijfw team swap <old-role-name> --charter <path>
+  if (sub === 'swap') {
+    const oldName = args[0] && !args[0].startsWith('--') ? args[0] : null;
+    const charterPath = optionValue(args, ['--charter', '-c']);
+    if (!oldName || !charterPath) {
+      console.error('Usage: ijfw team swap <old-role-name> --charter <path-to-role.json>');
+      process.exit(1);
+    }
+    const result = swapTeamRole(process.cwd(), { oldName, charterPath });
+    if (!result.ok) {
+      console.error(`team swap failed: ${result.error}`);
+      if (result.errors) result.errors.forEach((e) => console.error(`  - ${e}`));
+      process.exit(1);
+    }
+    console.log(`Swapped ${result.swapped.old} -> ${result.swapped.new}`);
+    if (result.codex?.ok) console.log(`Codex agents resynced: ${result.codex.count} (${result.codex.skipped ?? 0} unchanged)`);
+    process.exit(0);
+  }
+
+  // F-FUN-5 (audit-MED-teams-#13): ijfw team check -- standalone validator.
+  if (sub === 'check' || sub === 'validate') {
+    const report = checkTeamAssembly(process.cwd());
+    if (report.ok) {
+      console.log(`Team assembly OK: ${report.role_count} role(s), ${report.artifact_count} artifact(s)`);
+      process.exit(0);
+    }
+    console.error('Team assembly has issues:');
+    if (!report.has_charter || !report.charter.ok) {
+      console.error('  charter.json:');
+      for (const err of report.charter.errors) console.error(`    - ${err}`);
+    }
+    if (!report.has_workflow || !report.workflow.ok) {
+      console.error('  workflow.json:');
+      for (const err of report.workflow.errors) console.error(`    - ${err}`);
+    }
+    process.exit(1);
+  }
+
+  console.log('Usage: ijfw team init [--archetype <type>] [--name <team-name>] [--force] | status | list | add <role> --charter <path> | remove <role> | swap <old> --charter <path> | check');
   process.exit(1);
 }
 
@@ -2730,7 +3228,45 @@ function cmdSwarm(sub) {
     process.exit(0);
   }
 
-  console.log('Usage: ijfw swarm plan | prepare [--append] [--reviews] | tasks | prompt <task-id> [--codex] | start <task-id> [--owner <agent>] | complete <task-id> [--message <text>] | block <task-id> --message <why> | ready <task-id> | status');
+  // F-REL-1 (H5.3): orphan eviction. Walks active claims and releases any
+  // whose freshness anchor (claimed_at or heartbeat_at) is older than the
+  // TTL. Default TTL is 30 minutes; override with --ttl-min N.
+  if (sub === 'evict-orphans' || sub === 'evict') {
+    const minRaw = optionValue(args, ['--ttl-min', '--ttl', '-t']);
+    const min = Number.parseFloat(minRaw);
+    const ttlMs = Number.isFinite(min) && min > 0 ? Math.floor(min * 60 * 1000) : DEFAULT_CLAIM_TTL_MS;
+    const result = evictOrphanedClaims(process.cwd(), { ttlMs });
+    if (!result.ok) {
+      console.log(`Swarm evict halted: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(`Evicted ${result.count} orphan claim(s) (TTL ${Math.round(ttlMs / 60000)}min)`);
+    for (const item of result.evicted) {
+      console.log(`  ${item.id} (${item.agent} -> ${item.artifact_id}, age ${Math.round(item.age_ms / 1000)}s)`);
+    }
+    process.exit(0);
+  }
+
+  // F-REL-1 (H5.3): manual heartbeat ping. Subagents normally invoke this
+  // via the programmatic surface (updateClaimHeartbeat); the CLI form is
+  // for forensic dogfooding from tests + the dashboard preview.
+  if (sub === 'heartbeat') {
+    const taskOrClaim = args[0];
+    const owner = optionValue(args.slice(1), ['--owner', '-o']);
+    const claimId = optionValue(args.slice(1), ['--claim', '--id']);
+    const input = claimId
+      ? { claim_id: claimId }
+      : { artifact_id: taskOrClaim, agent: owner };
+    const result = updateClaimHeartbeat(process.cwd(), input);
+    if (!result.ok) {
+      console.log(`Heartbeat halted: ${result.error}`);
+      process.exit(1);
+    }
+    console.log(`Heartbeat ${result.claim.id} at ${result.claim.heartbeat_at}`);
+    process.exit(0);
+  }
+
+  console.log('Usage: ijfw swarm plan | prepare [--append] [--reviews] | tasks | prompt <task-id> [--codex] | start <task-id> [--owner <agent>] | complete <task-id> [--message <text>] | block <task-id> --message <why> | ready <task-id> | status | evict-orphans [--ttl-min N] | heartbeat <artifact-id> --owner <agent>');
   process.exit(1);
 }