@ijfw/memory-server 1.4.4 → 1.5.1

package/src/audit-roster.js

@@ -12,6 +12,38 @@
 // gets filtered as "self."
 
 import { spawnSync } from 'node:child_process';
+import { getLatestModel } from './model-refresh.js';
+
+// ---------------------------------------------------------------------------
+// v1.5.0 F5 -- audit-rotation v0 schema (schema-only; runtime ships in v1.6.0)
+// ---------------------------------------------------------------------------
+//
+// We are NOT shipping rotation logic in v1.5.0. We are shipping the schema
+// commitment so callers / future code have a stable contract to encode
+// against. Auto-rotation flips on in v1.6.0 once we have telemetry to
+// decide rotation policy (cost-weighted, win-rate-weighted, round-robin).
+//
+// Contract:
+//   - ROTATION_SCHEMA_VERSION = 1: any future schema change bumps this
+//     integer; consumers MUST refuse to apply policy from a higher version
+//     than they support.
+//   - defaultRotationPolicy = 'manual': v0 behavior is "no rotation;
+//     caller (or operator) picks the auditor explicitly via pickAuditors
+//     `only:` or default-priority strategy." Other policy values reserved
+//     for v1.6.0: 'round-robin', 'cost-weighted', 'win-rate-weighted'.
+//
+// Shape (reserved; not consumed yet):
+//   {
+//     schema: ROTATION_SCHEMA_VERSION,
+//     policy: defaultRotationPolicy,
+//     window_days: 7,        // reserved -- look-back for win-rate
+//     min_picks_per_auditor: 1, // reserved -- floor on usage
+//     last_rotated: <ISO>,   // reserved -- persistence anchor
+//   }
+//
+/** @typedef {{ schema: number, policy: string, window_days?: number, min_picks_per_auditor?: number, last_rotated?: string }} RotationPolicy */
+export const ROTATION_SCHEMA_VERSION = 1;
+export const defaultRotationPolicy = 'manual';
 
 export const ROSTER = [
   {
@@ -19,7 +51,22 @@ export const ROSTER = [
     family: 'openai',
     model: '',
     name: 'Codex CLI',
+    // Prompt-via-stdin path. Proven working 2026-05-18 with codex-cli 0.130.0.
     invoke: 'codex exec --skip-git-repo-check --sandbox read-only -c approval_policy="never" -c mcp_servers.ijfw-memory.enabled=false -',
+    // Dedicated review subcommand path. Use when an audit target is a git ref
+    // (HEAD~N, branch name, or commit SHA). The -c mcp_servers.ijfw-memory.enabled=false
+    // override is LOAD-BEARING: without it, codex review hangs indefinitely on
+    // the ijfw_memory_prelude MCP tool autostart (cycle: codex spawns IJFW MCP
+    // server, prelude tool waits on a response, IJFW MCP server is itself the
+    // child of the codex session). Verified 2026-05-18, codex-cli 0.130.0.
+    // {REF} is the substitution token the caller swaps for the base git ref.
+    reviewInvoke: 'codex review --base {REF} -c approval_policy="never" -c mcp_servers.ijfw-memory.enabled=false',
+    // 8 min default per-auditor budget for review work. codex review against
+    // HEAD~5 with MCP disabled completed in ~75s during S7 reproduction;
+    // larger diffs and reasoning-heavy targets need headroom. The existing
+    // PROVIDER_TIMEOUT_MS['codex'] in cross-orchestrator.js is 120s (2 min),
+    // which is fine for exec-mode quick prompts but too tight for review.
+    timeoutMs: 8 * 60 * 1000,
     note: 'Different training lineage; fast on review tasks. The - flag reads prompt from stdin. --skip-git-repo-check bypasses the trusted-directory gate added in codex-cli 0.118.0. --sandbox read-only blocks file WRITES on the host (verified Codex 0.122.0: `echo > /tmp/x` returns `operation not permitted`); it does NOT block shell exec or subprocess launching -- a `read-only` sandbox can still run `ls`, `curl`, or `gemini`. The defense against codex going meta and shelling out to other auditors is the prompt-layer "Operating constraints" block in cross-dispatcher.js buildRequest, not the sandbox flag. The model layer additionally refuses to read explicitly-secret files like ~/.ssh/id_rsa or ~/.codex/auth.json even when prompt-injected to do so. The visibility surface in cross-orchestrator-cli.js cmdCross catches any residual silent failure. approval_policy="never" auto-approves without an interactive prompt. mcp_servers.ijfw-memory.enabled=false disables IJFW MCP for this session because Codex in `codex exec` mode under a non-bypass sandbox auto-cancels MCP tool calls -- the cancellation noise wastes tokens and the audit does not need IJFW memory recall (the brief contains the full target inline).',
     // CODEX_SESSION_ID is set by codex itself when running INSIDE a codex
     // session; CODEX_HOME is a config-path env var that's set whenever codex
@@ -28,7 +75,11 @@ export const ROSTER = [
     // installed but where the caller is something else (Claude Code, Cursor,
     // etc.). Surface noted by carrmjw during the qwen roster review (#11).
     detect: (env) => Boolean(env.CODEX_SESSION_ID) || /codex/i.test(env._ || ''),
-    apiFallback: { provider: 'openai', model: 'gpt-4o-mini', authEnv: 'OPENAI_API_KEY', endpoint: 'https://api.openai.com/v1/chat/completions' },
+    // model is resolved at call-time via model-refresh.js (24h-cached probe of
+    // /v1/models). Hardcoded value below is the offline fallback only.
+    get apiFallback() {
+      return { provider: 'openai', model: getLatestModel('openai'), authEnv: 'OPENAI_API_KEY', endpoint: 'https://api.openai.com/v1/chat/completions' };
+    },
   },
   {
     id: 'gemini',
@@ -38,7 +89,10 @@ export const ROSTER = [
     invoke: 'gemini',
     note: 'Strong on security + architectural patterns. Auto-detects piped stdin for headless mode.',
     detect: (env) => Boolean(env.GEMINI_CLI || env.GOOGLE_CLOUD_PROJECT_GEMINI) || /gemini-cli/i.test(env._ || ''),
-    apiFallback: { provider: 'google', model: 'gemini-2.0-flash', authEnv: 'GEMINI_API_KEY', endpoint: 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent' },
+    // model is resolved at call-time via model-refresh.js (24h-cached probe).
+    get apiFallback() {
+      return { provider: 'google', model: getLatestModel('google'), authEnv: 'GEMINI_API_KEY', endpoint: 'https://generativelanguage.googleapis.com/v1beta/models/{model}:generateContent' };
+    },
   },
   {
     id: 'qwen',
@@ -108,7 +162,10 @@ export const ROSTER = [
     invoke: 'claude -p',
     note: 'Anthropic; useful when you want a second Claude pass in a fresh session.',
     detect: (env) => Boolean(env.CLAUDECODE || env.CLAUDE_CODE_ENTRYPOINT || env.CLAUDE_PLUGIN_ROOT),
-    apiFallback: { provider: 'anthropic', model: 'claude-haiku-4-5-20251001', authEnv: 'ANTHROPIC_API_KEY', endpoint: 'https://api.anthropic.com/v1/messages' },
+    // model is resolved at call-time via model-refresh.js (24h-cached probe).
+    get apiFallback() {
+      return { provider: 'anthropic', model: getLatestModel('anthropic'), authEnv: 'ANTHROPIC_API_KEY', endpoint: 'https://api.anthropic.com/v1/messages' };
+    },
   },
 ];
 
@@ -122,9 +179,27 @@ export function detectSelf(env = process.env) {
 
 // Probe whether the auditor's CLI is on PATH. Cached per process.
 // Exported so tests can prime the cache for deterministic behavior.
+//
+// v1.5.0 audit-LOW-trident-L1: cache entries now carry a timestamp and
+// expire after 5 minutes. A long-running orchestrator session that installs
+// an auditor mid-session (e.g. `npm install -g @google/gemini-cli`) was
+// otherwise stuck with the stale "not installed" verdict for the rest of
+// the process lifetime. 5min is comfortably longer than a typical Trident
+// fan-out (which probes every auditor up front) but short enough that a
+// mid-session install is detected on the next round.
 export const _installedCache = new Map();
+const INSTALLED_CACHE_TTL_MS = 5 * 60 * 1000;
 export function isInstalled(id) {
-  if (_installedCache.has(id)) return _installedCache.get(id);
+  const cached = _installedCache.get(id);
+  if (cached !== undefined) {
+    // Legacy entries (primed by tests as a raw boolean) are honoured
+    // forever — tests rely on that contract. New entries carry {value, ts}.
+    if (typeof cached === 'boolean') return cached;
+    if (cached && typeof cached === 'object' && cached.ts + INSTALLED_CACHE_TTL_MS > Date.now()) {
+      return cached.value;
+    }
+    // expired — fall through to re-probe
+  }
   const entry = ROSTER.find(e => e.id === id);
   if (!entry) return false;
   // First word of invoke is the binary; the rest are args.
@@ -133,7 +208,7 @@ export function isInstalled(id) {
   // works reliably across macOS + Linux. spawnSync exit code = 0 → present.
   const r = spawnSync('bash', ['-lc', `command -v ${JSON.stringify(bin)} >/dev/null 2>&1`], { timeout: 2000 });
   const installed = r.status === 0;
-  _installedCache.set(id, installed);
+  _installedCache.set(id, { value: installed, ts: Date.now() });
   return installed;
 }
 

package/src/blackboard.js

@@ -4,12 +4,28 @@
 // small and dependency-free: tasks/claims are atomic JSON, notes are append-only
 // JSONL, and handoff is plain markdown.
 
-import { appendFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { appendFileSync, existsSync, mkdirSync, readFileSync, statSync, writeFileSync } from 'node:fs';
 import { join, resolve } from 'node:path';
 import { writeAtomic, readSafe, withLock } from './lib/atomic-io.js';
+import { rotateJsonlIfNeeded } from './lib/jsonl-rotation.js';
 
 export const BLACKBOARD_VERSION = 1;
 
+// F-REL-1 (H5.3): default claim TTL = 30 minutes. Subagents that go silent
+// (the wayland 5/8-subagent failure mode) leave their claims forever
+// without this. Configurable via the `ttlMs` option on evictOrphanedClaims
+// and via the `--ttl-min N` CLI flag on `ijfw swarm evict-orphans`.
+export const DEFAULT_CLAIM_TTL_MS = 30 * 60 * 1000;
+
+// v1.5.0 audit-LOW-teams-#16: hard cap on tasks.json + claims.json
+// serialized size. A runaway producer (bug or attacker) could otherwise
+// grow either file unboundedly and starve the project's disk + slow every
+// read of the cache to a crawl. 4MB is comfortably above any legitimate
+// swarm workload (thousands of tasks) but well below "fill up the disk"
+// territory; refusing the write here keeps the previous on-disk state
+// intact (atomic writes only swap on success, so the old file survives).
+export const MAX_BB_FILE_BYTES = 4_000_000;
+
 export function blackboardPaths(projectRoot = process.cwd()) {
   const root = resolve(projectRoot);
   const dir = join(root, '.ijfw', 'blackboard');
@@ -60,7 +76,21 @@ function readJson(path, fallback, validator) {
 
 function writeJson(path, data) {
   data.updated_at = nowIso();
-  return writeAtomic(path, `${JSON.stringify(data, null, 2)}\n`, { mode: 0o600 });
+  const serialized = `${JSON.stringify(data, null, 2)}\n`;
+  // v1.5.0 audit-LOW-teams-#16: enforce the size cap on the write path
+  // only -- existing readers (readBlackboard / pathsOverlap / etc.) are
+  // unaffected so a legacy oversized file remains readable. Throwing here
+  // preserves the previous on-disk state because writeAtomic only swaps
+  // after a successful tmp-write.
+  const bytes = Buffer.byteLength(serialized, 'utf8');
+  if (bytes > MAX_BB_FILE_BYTES) {
+    throw new Error(
+      `blackboard: refusing to write ${path} -- serialized size ${bytes} bytes ` +
+      `exceeds cap ${MAX_BB_FILE_BYTES} bytes (audit-LOW-teams-#16). Trim ` +
+      `tasks/claims (e.g. archive completed tasks) before retrying.`,
+    );
+  }
+  return writeAtomic(path, serialized, { mode: 0o600 });
 }
 
 function readJsonl(path, limit = 5) {
@@ -76,6 +106,10 @@ function readJsonl(path, limit = 5) {
 }
 
 function appendJsonlUnlocked(path, entry) {
+  // F-PRF-1 (audit-MED-teams-#10): rotate large JSONL files in place before
+  // appending. The rotator is a no-op when the file is under the 4MB
+  // threshold, so this stays a hot-path-friendly stat() in the common case.
+  try { rotateJsonlIfNeeded(path); } catch { /* rotation is best-effort */ }
   appendFileSync(path, `${JSON.stringify(entry)}\n`, { encoding: 'utf8', mode: 0o600 });
   return entry;
 }
@@ -110,10 +144,53 @@ export function initBlackboard(projectRoot = process.cwd()) {
   return { ok: true, dir: paths.dir };
 }
 
+// F-SPD-2 (audit-MED-teams-#9): mtime cache for readBlackboard. Re-parsing
+// tasks.json + claims.json on every status/listSwarmTasks call shows up in
+// hot-path traces (planner + dispatcher both call this). The cache is keyed
+// on the resolved project dir and remembers the mtimeMs of both JSON files.
+// On a hit we return the previously-parsed JSON shape; on miss we re-parse
+// and refresh the cache. JSONL recent-tails are NOT cached -- they are
+// append-only and the LRU is intentionally narrow.
+const BLACKBOARD_READ_CACHE = new Map();
+const BLACKBOARD_READ_CACHE_MAX = 32;
+
+function blackboardFileMtime(path) {
+  try {
+    return statSync(path).mtimeMs;
+  } catch {
+    return 0;
+  }
+}
+
+function getCachedJson(cacheKey, path, mtime, fallback, validator) {
+  const cached = BLACKBOARD_READ_CACHE.get(cacheKey);
+  if (cached && cached.path === path && cached.mtime === mtime && mtime > 0) {
+    return cached.value;
+  }
+  const value = readJson(path, fallback, validator);
+  BLACKBOARD_READ_CACHE.set(cacheKey, { path, mtime, value });
+  // Lightweight LRU eviction: drop oldest entry when over cap.
+  if (BLACKBOARD_READ_CACHE.size > BLACKBOARD_READ_CACHE_MAX) {
+    const firstKey = BLACKBOARD_READ_CACHE.keys().next().value;
+    if (firstKey !== undefined) BLACKBOARD_READ_CACHE.delete(firstKey);
+  }
+  return value;
+}
+
+// Exposed for tests + cache invalidation hooks. Clears all memoised entries.
+export function _resetBlackboardReadCache() {
+  BLACKBOARD_READ_CACHE.clear();
+}
+
 export function readBlackboard(projectRoot = process.cwd()) {
   const paths = blackboardPaths(projectRoot);
-  const tasks = readJson(paths.tasks, defaultTasks, validTasks);
-  const claims = readJson(paths.claims, defaultClaims, validClaims);
+  // F-SPD-2: mtime-keyed memo. When tasks.json + claims.json are unchanged
+  // we skip JSON.parse entirely. mtime===0 forces a miss so transient stat
+  // failures degrade to the un-cached path safely.
+  const tasksMtime = blackboardFileMtime(paths.tasks);
+  const claimsMtime = blackboardFileMtime(paths.claims);
+  const tasks = getCachedJson(`${paths.root}::tasks`, paths.tasks, tasksMtime, defaultTasks, validTasks);
+  const claims = getCachedJson(`${paths.root}::claims`, paths.claims, claimsMtime, defaultClaims, validClaims);
   return {
     paths,
     tasks,
@@ -207,6 +284,36 @@ function commonPrefixBeforeGlob(pattern) {
   return idx === -1 ? pattern : pattern.slice(0, idx);
 }
 
+// v1.5.0 N4.obs M7: explicit path-segment overlap detection.
+//
+// The old prefix check was `right.startsWith(lp)` which falsely overlapped
+// e.g. `src` with `srcfoo`. Real path containment requires either an exact
+// match OR a `/` separator immediately after the shorter prefix (so `src/`
+// is the prefix of `src/foo`, but `src` does NOT contain `srcfoo`).
+//
+// `commonPrefixBeforeGlob` is preserved for glob handling -- it returns the
+// literal head of a glob pattern (`src/*.js` -> `src/`). When that head
+// already ends with `/`, we compare directly; when it doesn't (no glob in
+// the pattern at all), we require a trailing-slash match below.
+//
+// Same-string comparison short-circuits at the top, so `src` vs `src`
+// remains overlap-true.
+function segmentOverlap(prefix, candidate) {
+  if (!prefix || !candidate) return false;
+  if (prefix === candidate) return true;
+  // Treat the prefix as a directory prefix: candidate must start with
+  // `prefix` AND the next character must be `/`. This rejects the
+  // `srcfoo`-vs-`src` false positive.
+  if (prefix.endsWith('/')) {
+    // Glob-derived prefix already includes the separator; plain prefix match
+    // is the right semantics.
+    return candidate === prefix.slice(0, -1) || candidate.startsWith(prefix);
+  }
+  return candidate.length > prefix.length
+    && candidate.startsWith(prefix)
+    && candidate.charAt(prefix.length) === '/';
+}
+
 function pathsOverlap(a, b) {
   if (!a.length || !b.length) return false;
   for (const left of a) {
@@ -214,8 +321,8 @@ function pathsOverlap(a, b) {
       if (left === right) return true;
       const lp = commonPrefixBeforeGlob(left);
       const rp = commonPrefixBeforeGlob(right);
-      if (lp && right.startsWith(lp)) return true;
-      if (rp && left.startsWith(rp)) return true;
+      if (segmentOverlap(lp, right)) return true;
+      if (segmentOverlap(rp, left)) return true;
     }
   }
   return false;
@@ -236,6 +343,9 @@ export function claimArtifact(projectRoot, input) {
     const current = readJson(paths.claims, defaultClaims, validClaims).data;
     const artifactId = String(input.artifact_id || input.artifact || '').trim();
     const agent = String(input.agent || input.owner || '').trim();
+    const ttlMs = Number.isFinite(input.ttlMs) && input.ttlMs > 0
+      ? Math.floor(input.ttlMs)
+      : DEFAULT_CLAIM_TTL_MS;
     const next = {
       id: input.id || `${artifactId}:${agent}`,
       artifact_id: artifactId,
@@ -243,6 +353,13 @@ export function claimArtifact(projectRoot, input) {
       paths: normalizePaths(input.paths),
       status: 'active',
       claimed_at: nowIso(),
+      // F-REL-1: TTL is stored on the claim so per-claim overrides survive
+      // a config reload and the evictor doesn't need the original config.
+      ttl_ms: ttlMs,
+      // heartbeat_at is OPTIONAL -- subagents that don't ping fall back to
+      // claimed_at as the freshness anchor. Initialised null so the field
+      // always exists in the JSON shape (no schema migration needed).
+      heartbeat_at: null,
       note: input.note ? String(input.note) : undefined,
     };
     if (!next.artifact_id) return { ok: false, error: 'artifact-required' };
@@ -265,6 +382,90 @@ export function claimArtifact(projectRoot, input) {
   }).result ?? { ok: false, error: 'locked' };
 }
 
+/**
+ * v1.5.0 audit-LOW-teams-#17: bulk-claim API.
+ *
+ * Acquire claims for N artifacts under ONE lock + ONE writeJson, instead of
+ * N round-trips through `claimArtifact`. The dispatcher fanned-out batch case
+ * (e.g. wave fan-out reserves 10+ artifacts at once) previously hit the lock
+ * 10+ times with serialised disk writes between each.
+ *
+ * Semantics:
+ *   - All-or-nothing: any single conflict ABORTS the batch and reports the
+ *     conflicting artifact_id + the existing claim. No partial commits.
+ *   - Same conflict rules as claimArtifact (artifact_id equal OR paths
+ *     overlap, scoped to a different agent).
+ *   - Per-item agent override: each item may set its own `agent`. When
+ *     omitted, the top-level `agent` is used.
+ *
+ * @param {string} projectRoot
+ * @param {Array<{artifact_id: string, paths?: string[], agent?: string, ttlMs?: number, note?: string}>} items
+ * @param {{agent?: string}} [defaults]
+ * @returns {{ok: true, claims: object[]} | {ok: false, error: string, artifact_id?: string, conflicts?: object[]}}
+ */
+export function claimArtifacts(projectRoot, items, defaults = {}) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  if (!Array.isArray(items) || items.length === 0) {
+    return { ok: false, error: 'items-required' };
+  }
+  return withLock(paths.lock, () => {
+    const current = readJson(paths.claims, defaultClaims, validClaims).data;
+    const accepted = [];
+    // Track NEW claims so they conflict-check against each other (same wave
+    // calling claim_a + claim_b where they overlap is still a conflict).
+    const pendingClaims = [];
+    for (const input of items) {
+      const artifactId = String(input.artifact_id || input.artifact || '').trim();
+      const agent = String(input.agent || defaults.agent || input.owner || '').trim();
+      const ttlMs = Number.isFinite(input.ttlMs) && input.ttlMs > 0
+        ? Math.floor(input.ttlMs)
+        : DEFAULT_CLAIM_TTL_MS;
+      const next = {
+        id: input.id || `${artifactId}:${agent}`,
+        artifact_id: artifactId,
+        agent,
+        paths: normalizePaths(input.paths),
+        status: 'active',
+        claimed_at: nowIso(),
+        ttl_ms: ttlMs,
+        heartbeat_at: null,
+        note: input.note ? String(input.note) : undefined,
+      };
+      if (!next.artifact_id) return { ok: false, error: 'artifact-required' };
+      if (!next.agent) return { ok: false, error: 'owner-required' };
+
+      // Conflict-check against existing AND already-accepted pending claims.
+      const combined = { claims: [...current.claims, ...pendingClaims] };
+      const conflicts = claimConflicts(combined, next);
+      if (conflicts.length) {
+        return { ok: false, error: 'conflict', artifact_id: next.artifact_id, conflicts };
+      }
+      pendingClaims.push(next);
+      accepted.push(next);
+    }
+    // Drop any prior duplicates (same artifact_id + agent) — matches
+    // claimArtifact semantics where a re-claim by the same agent is idempotent.
+    for (const next of accepted) {
+      current.claims = current.claims.filter(
+        (claim) => !(claimArtifactId(claim) === next.artifact_id && claimAgent(claim) === next.agent),
+      );
+      current.claims.push(next);
+    }
+    writeJson(paths.claims, current);
+    for (const next of accepted) {
+      appendJsonlUnlocked(paths.events, blackboardEventEntry({
+        type: 'claim.acquired',
+        actor: next.agent,
+        artifact_ids: [next.artifact_id],
+        message: `Claimed ${next.artifact_id} (bulk)`,
+        data: { paths: next.paths, bulk: true },
+      }));
+    }
+    return { ok: true, claims: accepted };
+  }).result ?? { ok: false, error: 'locked' };
+}
+
 export function releaseClaim(projectRoot, input) {
   const paths = blackboardPaths(projectRoot);
   ensureDir(paths);
@@ -295,6 +496,97 @@ export function releaseClaim(projectRoot, input) {
   }).result ?? { ok: false, error: 'locked' };
 }
 
+/**
+ * F-REL-1 (H5.3): heartbeat ping. Subagents call this to extend their claim
+ * TTL without releasing + reclaiming. Heartbeat is matched by claim id
+ * (preferred) or by (artifact_id, agent) tuple. Returns the updated claim
+ * so the caller can verify the new heartbeat_at.
+ */
+export function updateClaimHeartbeat(projectRoot, input) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  return withLock(paths.lock, () => {
+    const current = readJson(paths.claims, defaultClaims, validClaims).data;
+    const claimId = input.claim_id || input.id ? String(input.claim_id || input.id).trim() : null;
+    const artifactId = input.artifact_id || input.artifact ? String(input.artifact_id || input.artifact).trim() : null;
+    const agent = input.agent || input.owner ? String(input.agent || input.owner).trim() : null;
+    if (!claimId && !(artifactId && agent)) {
+      return { ok: false, error: 'claim-or-tuple-required' };
+    }
+    let updated = null;
+    current.claims = current.claims.map((claim) => {
+      if (claim.status !== 'active') return claim;
+      const matchesById = claimId && claim.id === claimId;
+      const matchesByTuple = !claimId && claimArtifactId(claim) === artifactId && claimAgent(claim) === agent;
+      if (!matchesById && !matchesByTuple) return claim;
+      updated = { ...claim, heartbeat_at: nowIso() };
+      return updated;
+    });
+    if (!updated) return { ok: false, error: 'claim-not-found' };
+    writeJson(paths.claims, current);
+    return { ok: true, claim: updated };
+  }).result ?? { ok: false, error: 'locked' };
+}
+
+/**
+ * F-REL-1 (H5.3): orphan evictor. Walks active claims, releases any whose
+ * freshness anchor (max(claimed_at, heartbeat_at)) is older than ttlMs.
+ * Returns evicted claim IDs so the caller can log + report. Default TTL is
+ * 30 minutes, matching DEFAULT_CLAIM_TTL_MS.
+ *
+ * Per-claim ttl_ms (recorded at claim time) is honoured when present; the
+ * options.ttlMs is a fallback for legacy claims written before the TTL
+ * field existed.
+ */
+export function evictOrphanedClaims(projectRoot, options = {}) {
+  const paths = blackboardPaths(projectRoot);
+  ensureDir(paths);
+  const fallbackTtl = Number.isFinite(options.ttlMs) && options.ttlMs > 0
+    ? Math.floor(options.ttlMs)
+    : DEFAULT_CLAIM_TTL_MS;
+  const now = Number.isFinite(options.nowMs) ? Number(options.nowMs) : Date.now();
+  return withLock(paths.lock, () => {
+    const current = readJson(paths.claims, defaultClaims, validClaims).data;
+    const evicted = [];
+    current.claims = current.claims.map((claim) => {
+      if (claim.status !== 'active') return claim;
+      const claimedAt = parseIso(claim.claimed_at);
+      const heartbeatAt = parseIso(claim.heartbeat_at);
+      const anchor = Math.max(claimedAt || 0, heartbeatAt || 0);
+      if (!anchor) return claim; // unparseable timestamps -- leave alone, don't false-evict
+      const ttl = Number.isFinite(claim.ttl_ms) && claim.ttl_ms > 0 ? claim.ttl_ms : fallbackTtl;
+      if (now - anchor <= ttl) return claim;
+      evicted.push({
+        id: claim.id,
+        artifact_id: claimArtifactId(claim),
+        agent: claimAgent(claim),
+        age_ms: now - anchor,
+        ttl_ms: ttl,
+      });
+      return { ...claim, status: 'expired', expired_at: nowIso(), eviction_reason: 'ttl-exceeded' };
+    });
+    if (evicted.length > 0) {
+      writeJson(paths.claims, current);
+      for (const item of evicted) {
+        appendJsonlUnlocked(paths.events, blackboardEventEntry({
+          type: 'claim.evicted',
+          actor: 'ijfw',
+          artifact_ids: [item.artifact_id],
+          message: `Evicted orphan claim ${item.id} (age ${Math.round(item.age_ms / 1000)}s > ttl ${Math.round(item.ttl_ms / 1000)}s)`,
+          data: { id: item.id, agent: item.agent, age_ms: item.age_ms, ttl_ms: item.ttl_ms },
+        }));
+      }
+    }
+    return { ok: true, evicted, evicted_ids: evicted.map((item) => item.id), count: evicted.length };
+  }).result ?? { ok: false, error: 'locked' };
+}
+
+function parseIso(value) {
+  if (!value || typeof value !== 'string') return 0;
+  const ms = Date.parse(value);
+  return Number.isFinite(ms) ? ms : 0;
+}
+
 export function addBlackboardNote(projectRoot, input) {
   const paths = blackboardPaths(projectRoot);
   ensureDir(paths);

package/src/cli-run.js

@@ -10,20 +10,34 @@
  *   long-lived MCP server. A 30-line shim that imports dispatchRun directly
  *   keeps the dependency chain trivial: bash -> node -> dispatch/*.js.
  *
+ *   v1.5.0 T12 extends this shim with the `state:<verb>` colon-namespace —
+ *   the CLI face of the state-SDK (contract §0). The same shim now lets
+ *   external tooling reach `query(verb, payload, ctx)` from bash, e.g.
+ *   shell-hook state writes (T11) and the e2e-smoke `state:workflow.get` gate.
+ *
  * Usage:
  *   node cli-run.js <namespace>:<command> [--project-root <dir>] [args...]
  *
  * Examples:
  *   node cli-run.js domain-manifest:load --project-root /path/to/proj
  *   node cli-run.js extension:deploy-lazy --project-root /path/to/proj
+ *   node cli-run.js state:workflow.get '{}'
+ *   node cli-run.js state:workflow.set-phase '{"phase":"build"}'
  *
  * Contract:
- *   - Always exits 0 on a successful dispatch (even when the dispatched
- *     command reports ok:false -- that's a *result*, not a shim failure).
+ *   - Prints the JSON-stringified result to stdout.
  *   - Exits 2 on argv-shape errors (missing colon expression).
  *   - Exits 3 on a thrown error inside the dispatcher.
- *   - Prints the JSON-stringified result to stdout. stderr stays empty on
- *     the happy path so the session-start log isn't polluted.
+ *   - For the `state:` namespace: exits 0 on `ok:true`, non-zero on
+ *     `ok:false` so shell callers can branch on `$?` without re-parsing
+ *     the JSON. The non-zero exit is paired with a stderr line carrying
+ *     the result's `error` for log readability.
+ *   - For every other namespace (compute/index/detect/graph/override/
+ *     extension/domain-manifest): exits 0 on a successful dispatch even
+ *     when the dispatched command reports ok:false — that is a *result*,
+ *     not a shim failure (legacy behaviour preserved).
+ *   - stderr stays empty on the happy path so the session-start log isn't
+ *     polluted.
  *
  * Discipline:
  *   - Built-in Node only. No new deps.
@@ -80,7 +94,21 @@ async function main() {
     const result = await dispatchRun(parsed, {
       projectRoot: projectRoot || process.env.IJFW_PROJECT_DIR || process.cwd(),
     });
-    process.stdout.write(JSON.stringify(result == null ? { ok: false, error: 'dispatch returned null (unknown namespace)' } : result) + '\n');
+    const payload = result == null
+      ? { ok: false, error: 'dispatch returned null (unknown namespace)' }
+      : result;
+    process.stdout.write(JSON.stringify(payload) + '\n');
+    // T12: the `state:` namespace honours `ok:true/false` as the process
+    // exit code so bash callers can `if ijfw state:foo ...; then` without
+    // re-parsing the JSON. Other namespaces keep the legacy always-0 contract
+    // — a dispatched compute:python script with exit_code=1 is a *result*,
+    // not a shim failure, and the existing session-start hooks rely on that.
+    if (parsed.namespace === 'state' && payload && payload.ok === false) {
+      if (payload.error) {
+        process.stderr.write(`cli-run: state:${parsed.command || '<verb>'}: ${payload.error}\n`);
+      }
+      process.exit(1);
+    }
     process.exit(0);
   } catch (err) {
     process.stderr.write(`cli-run: dispatch threw: ${err && err.message ? err.message : String(err)}\n`);