@ijfw/memory-server 1.4.4 → 1.5.0

package/fixtures/truncation-corpus/fx-05-error-terminated-03/meta.json

@@ -0,0 +1,18 @@
+{
+  "id": "fx-05-error-terminated-03",
+  "category": "error-terminated",
+  "waveId": "W20-errT-3",
+  "subId": "errT3",
+  "notes": "error-terminated with overwrite partial — rollback restores baseline",
+  "expectedDetection": {
+    "truncated": "error-terminated",
+    "reasonContains": "outcome='error'"
+  },
+  "expectedRecovery": {
+    "recovered": true
+  },
+  "expectedFinalState": {
+    ".ijfw/state/workflow.json": "{\"phase\":\"errT-pre-3\"}"
+  },
+  "expectedTerminalVerb": "subagent.post-done"
+}

package/fixtures/truncation-corpus/fx-05-error-terminated-03/snapshots/v-errT-3-partial.json

@@ -0,0 +1,11 @@
+{
+  "verbId": "v-errT-3-partial",
+  "targets": [
+    {
+      "relPath": ".ijfw/state/workflow.json",
+      "absPath": "<<ABS>>",
+      "existed": true,
+      "content": "{\"phase\":\"errT-pre-3\"}"
+    }
+  ]
+}

package/fixtures/truncation-corpus/fx-05-error-terminated-03/target/.ijfw/state/workflow.json

@@ -0,0 +1 @@
+{"phase":"errT-PARTIAL-3"}

package/fixtures/truncation-corpus/fx-05-error-terminated-04/events.jsonl

@@ -0,0 +1,2 @@
+{"seq":1,"verb":"subagent.checkpoint","subagentId":"errT4","ts":"2026-05-20T12:00:00.000Z","verbId":"v-errT-4-ckpt","outcome":"ok","payloadDigest":"sha256-fixture-v-errT-4-ckpt"}
+{"seq":2,"verb":"decision.add","subagentId":"errT4","ts":"2026-05-20T12:00:00.000Z","verbId":"v-errT-4-partial","outcome":"error","payloadDigest":"sha256-fixture-v-errT-4-partial"}

package/fixtures/truncation-corpus/fx-05-error-terminated-04/intent-journal.jsonl

@@ -0,0 +1,3 @@
+{"verb":"subagent.checkpoint","verbId":"v-errT-4-ckpt","phase":"begin","ts":"2026-05-20T12:00:00.000Z","targets":[".ijfw/wave-W20-errT-4/subagent-errT4.checkpoint.json"],"payloadDigest":"sha256-fixture-v-errT-4-ckpt","kind":"append","dedupKey":"dk-ckpt-errT-4"}
+{"verb":"subagent.checkpoint","verbId":"v-errT-4-ckpt","phase":"commit","ts":"2026-05-20T12:00:00.000Z","payloadDigest":"sha256-fixture-v-errT-4-ckpt","kind":"append","dedupKey":"dk-ckpt-errT-4"}
+{"verb":"decision.add","verbId":"v-errT-4-partial","phase":"begin","ts":"2026-05-20T12:00:00.000Z","targets":[".ijfw/blackboard/decisions.jsonl"],"payloadDigest":"sha256-fixture-v-errT-4-partial","kind":"append","dedupKey":"dk-errT-4"}

package/fixtures/truncation-corpus/fx-05-error-terminated-04/meta.json

@@ -0,0 +1,18 @@
+{
+  "id": "fx-05-error-terminated-04",
+  "category": "error-terminated",
+  "waveId": "W20-errT-4",
+  "subId": "errT4",
+  "notes": "error-terminated with append partial — seal-in-place preserves record",
+  "expectedDetection": {
+    "truncated": "error-terminated",
+    "reasonContains": "outcome='error'"
+  },
+  "expectedRecovery": {
+    "recovered": true
+  },
+  "expectedFinalState": {
+    ".ijfw/blackboard/decisions.jsonl": "{\"id\":\"d-errT-4\",\"text\":\"errT 4\",\"dedupKey\":\"dk-errT-4\"}\n"
+  },
+  "expectedTerminalVerb": "subagent.post-done"
+}

package/fixtures/truncation-corpus/fx-05-error-terminated-04/target/.ijfw/blackboard/decisions.jsonl

@@ -0,0 +1 @@
+{"id":"d-errT-4","text":"errT 4","dedupKey":"dk-errT-4"}

package/fixtures/truncation-corpus/fx-05-error-terminated-05/events.jsonl

@@ -0,0 +1,2 @@
+{"seq":1,"verb":"workflow.set-phase","subagentId":"errT5","ts":"2026-05-20T12:00:00.000Z","verbId":"v-errT-5-ok","outcome":"ok","payloadDigest":"sha256-fixture-v-errT-5-ok"}
+{"seq":2,"verb":"wave.advance","subagentId":"errT5","ts":"2026-05-20T12:00:00.000Z","verbId":"v-errT-5-partial","outcome":"error","payloadDigest":"sha256-fixture-v-errT-5-partial"}

package/fixtures/truncation-corpus/fx-05-error-terminated-05/intent-journal.jsonl

@@ -0,0 +1,3 @@
+{"verb":"workflow.set-phase","verbId":"v-errT-5-ok","phase":"begin","ts":"2026-05-20T12:00:00.000Z","targets":[".ijfw/state/workflow.json"],"payloadDigest":"sha256-fixture-v-errT-5-ok","kind":"overwrite"}
+{"verb":"workflow.set-phase","verbId":"v-errT-5-ok","phase":"commit","ts":"2026-05-20T12:00:00.000Z","payloadDigest":"sha256-fixture-v-errT-5-ok","kind":"overwrite"}
+{"verb":"wave.advance","verbId":"v-errT-5-partial","phase":"begin","ts":"2026-05-20T12:00:00.000Z","targets":[".ijfw/state/workflow.json"],"payloadDigest":"sha256-fixture-v-errT-5-partial","kind":"overwrite"}

package/fixtures/truncation-corpus/fx-05-error-terminated-05/meta.json

@@ -0,0 +1,18 @@
+{
+  "id": "fx-05-error-terminated-05",
+  "category": "error-terminated",
+  "waveId": "W20-errT-5",
+  "subId": "errT5",
+  "notes": "error-terminated with overwrite partial — rollback restores baseline",
+  "expectedDetection": {
+    "truncated": "error-terminated",
+    "reasonContains": "outcome='error'"
+  },
+  "expectedRecovery": {
+    "recovered": true
+  },
+  "expectedFinalState": {
+    ".ijfw/state/workflow.json": "{\"phase\":\"errT-pre-5\"}"
+  },
+  "expectedTerminalVerb": "subagent.post-done"
+}

package/fixtures/truncation-corpus/fx-05-error-terminated-05/snapshots/v-errT-5-partial.json

@@ -0,0 +1,11 @@
+{
+  "verbId": "v-errT-5-partial",
+  "targets": [
+    {
+      "relPath": ".ijfw/state/workflow.json",
+      "absPath": "<<ABS>>",
+      "existed": true,
+      "content": "{\"phase\":\"errT-pre-5\"}"
+    }
+  ]
+}

package/fixtures/truncation-corpus/fx-05-error-terminated-05/target/.ijfw/state/workflow.json

@@ -0,0 +1 @@
+{"phase":"errT-PARTIAL-5"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ijfw/memory-server",
-  "version": "1.4.4",
+  "version": "1.5.0",
   "description": "Cross-platform persistent memory server for IJFW. 10 MCP tools (memory + admin/update). Works with 13 MCP-using platforms (Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Copilot, Hermes, Wayland, OpenCode, QwenCode, Cline, KimiCode, OpenClaw) plus Aider via rules-only tier.",
   "author": "Sean Donahoe",
   "license": "MIT",

package/src/active-extension-writer.js

@@ -5,14 +5,38 @@
  * clears it on deactivate. Used by:
  *   - `ijfw_run extension:activate <name>` CLI command
  *   - installExtension when opts.activate is set
+ *
+ * v1.5.0 T10 — Migrated to the state-SDK. The legacy
+ * `writeFile`/`rename`/`unlink` direct-write path is replaced by a call to
+ * `query('extension.set-active', ...)`. The state-SDK is the single mutation
+ * surface for `~/.ijfw/state/active-extension.json`; this writer now adapts
+ * the SDK's verb-returns to the writer's `{ok, path, error}` /
+ * `{ok, removed}` external API so every existing caller keeps working without
+ * change (`extension-installer.js`, `dispatch/active-cli.js`,
+ * `dispatch/extension.js`, the test suite).
+ *
+ * Side-effects retained verbatim from the v1.4.0/W7.1 contract:
+ *   - quota counters are reset on activate (B16/SEC-M-02) and clear (B16) via
+ *     `resetExtensionQuotas` — best-effort, never blocks the verb result.
+ *   - B18 cross-IDE last-seen / divergence detection (`detectCrossIdeDivergence`)
+ *     stays as-is — it is a read-only consumer of the homedir state file and
+ *     does not need the SDK.
+ *   - `findInstalledManifest` stays as-is — it reads project/org/user-scope
+ *     manifest.json files; it is a read of installed extensions, not a write
+ *     to the homedir state file, so it is outside the state-SDK surface.
  */
 
 import { readFile, writeFile, unlink, mkdir, readdir, stat } from 'node:fs/promises';
+import { existsSync } from 'node:fs';
 import { join, dirname } from 'node:path';
 import { homedir } from 'node:os';
-import { randomBytes } from 'node:crypto';
 
 import { resetExtensionQuotas } from './extension-quota-tracker.js';
+// v1.5.0 audit-LOW-update-#13: shared tmp-suffix helper.
+import { tmpSuffix } from './lib/tmp-suffix.js';
+// v1.5.0 T10: route the canonical write/clear of ~/.ijfw/state/active-extension.json
+// through the state-SDK verb.
+import { query } from './orchestrator/state-sdk.js';
 
 const STATE_PATH_REL = ['.ijfw', 'state', 'active-extension.json'];
 
@@ -34,16 +58,37 @@ function stateDir(home) {
   return join(home || homedir(), '.ijfw', 'state');
 }
 
+/**
+ * Pick a state-SDK projectRoot to satisfy the verb's `ctx.projectRoot`
+ * requirement. The writer's external callers don't carry a project root
+ * (extension activation is a homedir-scoped operation), so we fall back to
+ * `process.cwd()`. The SDK uses this only for the intent-journal lock path
+ * (`<projectRoot>/.ijfw/state/intent-journal.jsonl`) — it never mutates any
+ * project file under it. opts.projectRoot, when supplied, takes precedence.
+ */
+function pickProjectRoot(opts) {
+  if (opts && typeof opts.projectRoot === 'string' && opts.projectRoot.length > 0) {
+    return opts.projectRoot;
+  }
+  return process.cwd();
+}
+
 /**
  * Write the active-extension state file from a manifest + scope.
- * Validates required fields before write. Atomic write via tmp+rename.
+ * Validates required fields before write. Atomic write via the state-SDK
+ * `extension.set-active` verb (tmp+rename via atomic-io).
  *
- * @param {{ name: string, permissions: { reads: string[], writes: string[] } }} manifest
+ * @param {{ name: string, permissions: { reads: string[], writes: string[] }, quotas?: object }} manifest
  * @param {'project'|'org'|'user'} scope
- * @param {{ homeDir?: string, ideId?: string|null }} [opts]
+ * @param {{ homeDir?: string, ideId?: string|null, projectRoot?: string }} [opts]
  * @returns {Promise<{ ok: boolean, path?: string, error?: string }>}
  */
 export async function writeActiveExtension(manifest, scope, opts = {}) {
+  // Validation — external API contract (returns ok:false, never throws).
+  // Mirrors the pre-v1.5.0 behavior so every existing caller keeps the same
+  // error-handling shape. The SDK verb would throw on the same inputs; the
+  // adapter catches that downstream too, but explicit pre-checks give the
+  // historical error messages.
   if (!manifest || typeof manifest !== 'object') {
     return { ok: false, error: 'manifest must be an object' };
   }
@@ -56,57 +101,73 @@ export async function writeActiveExtension(manifest, scope, opts = {}) {
   if (!manifest.permissions || typeof manifest.permissions !== 'object') {
     return { ok: false, error: 'manifest.permissions required' };
   }
-  const reads = Array.isArray(manifest.permissions.reads) ? manifest.permissions.reads : [];
-  const writes = Array.isArray(manifest.permissions.writes) ? manifest.permissions.writes : [];
-  const activatedAt = new Date().toISOString();
+
+  const home = opts && opts.homeDir ? opts.homeDir : (process.env.HOME || homedir());
+
   // B18: stamp activated_by_ide + activated_by_pid when ideId is provided.
   // Caller (CLI) is responsible for calling detectIde() and threading the
-  // value in. When opts.ideId is null/undefined, fields are omitted (so the
-  // file stays back-compatible with v1.4.1 readers).
+  // value in. When opts.ideId is null/undefined or invalid, fields are
+  // omitted (so the file stays back-compatible with v1.4.1 readers).
   const ideId = (typeof opts.ideId === 'string' && IDE_ID_PATTERN.test(opts.ideId))
     ? opts.ideId
     : null;
-  const out = {
+
+  // Normalize permissions + quotas in the manifest payload so the SDK verb
+  // sees the exact shape it expects. The verb itself filters quotas to
+  // positive integers — we leave that filtering to it (single writer rule).
+  const reads = Array.isArray(manifest.permissions.reads) ? manifest.permissions.reads : [];
+  const writes = Array.isArray(manifest.permissions.writes) ? manifest.permissions.writes : [];
+  const verbManifest = {
     name: manifest.name,
-    scope,
     permissions: { reads, writes },
-    activated_at: activatedAt,
   };
-  if (ideId) {
-    out.activated_by_ide = ideId;
-    out.activated_by_pid = process.pid;
-  }
-  // R12-H-01: persist manifest.quotas so the tier-2 hook
-  // (extension-permission-check.mjs) can enforce quotas on Edit/Write/Bash
-  // dispatch. Without this the tier-2 hook reads `active.quotas` as undefined
-  // and silently bypasses the v1.4.3 quota gate that the server-side
-  // gatePermissionAndQuota path enforces. Schema (extension-manifest-schema.js):
-  // optional object whose values are positive integers — currently
-  // max_files_written / max_bytes_written / max_wall_clock_ms (forward-compat:
-  // unknown dimensions are kept as-is — schema rejects unknowns at install).
   if (
     manifest.quotas !== undefined &&
     manifest.quotas !== null &&
     typeof manifest.quotas === 'object' &&
     !Array.isArray(manifest.quotas)
   ) {
-    const cleanQuotas = {};
-    let copied = 0;
-    for (const [k, v] of Object.entries(manifest.quotas)) {
-      if (typeof v === 'number' && Number.isFinite(v) && Number.isInteger(v) && v > 0) {
-        cleanQuotas[k] = v;
-        copied++;
-      }
-    }
-    if (copied > 0) out.quotas = cleanQuotas;
+    verbManifest.quotas = manifest.quotas;
   }
-  const home = opts && opts.homeDir ? opts.homeDir : (process.env.HOME || homedir());
-  const path = statePath(home);
-  await mkdir(dirname(path), { recursive: true });
-  const tmp = `${path}.tmp.${randomBytes(4).toString('hex')}`;
-  await writeFile(tmp, JSON.stringify(out, null, 2) + '\n', 'utf8');
-  const { rename } = await import('node:fs/promises');
-  await rename(tmp, path);
+
+  const payload = {
+    manifest: verbManifest,
+    scope,
+    homeDir: home,
+  };
+  if (ideId) {
+    payload.activated_by_ide = ideId;
+    payload.activated_by_pid = process.pid;
+  }
+
+  let result;
+  try {
+    result = await query('extension.set-active', payload, {
+      projectRoot: pickProjectRoot(opts),
+      homeDir: home,
+    });
+  } catch (err) {
+    // The SDK verb throws on protocol violations. Surface as the writer's
+    // {ok:false, error} contract so callers don't have to learn a new shape.
+    return { ok: false, error: err && err.message ? err.message : String(err) };
+  }
+  if (!result || result.ok !== true) {
+    return { ok: false, error: 'state-sdk extension.set-active returned non-ok' };
+  }
+
+  // Recover the activated_at timestamp the SDK stamped so we can pass it to
+  // resetExtensionQuotas (parity with the legacy writer's wall_clock_ms window).
+  // Best-effort: if the read fails, omit activated_at and the tracker resets
+  // counters without the window stamp.
+  let activatedAt;
+  try {
+    const raw = await readFile(result.path, 'utf8');
+    const parsed = JSON.parse(raw);
+    if (parsed && typeof parsed.activated_at === 'string') {
+      activatedAt = parsed.activated_at;
+    }
+  } catch { /* best-effort */ }
+
   // B16/SEC-M-02: reset quota counters on activate; stamp activated_at so
   // wall_clock_ms can be computed against this activation window.
   try {
@@ -115,21 +176,24 @@ export async function writeActiveExtension(manifest, scope, opts = {}) {
     // Quota reset failure must not block activation. Counters will self-heal
     // on next deactivate or the next activate of the same name.
   }
-  return { ok: true, path };
+
+  return { ok: true, path: result.path };
 }
 
 /**
  * Clear the active-extension state file. Idempotent -- succeeds if file is absent.
  *
- * @param {{ homeDir?: string }} [opts]
+ * @param {{ homeDir?: string, projectRoot?: string }} [opts]
  * @returns {Promise<{ ok: boolean, removed: boolean }>}
  */
 export async function clearActiveExtension(opts = {}) {
   const home = opts && opts.homeDir ? opts.homeDir : (process.env.HOME || homedir());
-  // B16/SEC-M-02: read the active extension name BEFORE unlinking so we can
-  // clear its quota counters. Best-effort: if the file is missing or
+
+  // B16/SEC-M-02: read the active extension name BEFORE clearing so we can
+  // reset its quota counters. Best-effort: if the file is missing or
   // malformed, deactivate still succeeds.
   let extName = null;
+  const wasPresent = existsSync(statePath(home));
   try {
     const raw = await readFile(statePath(home), 'utf8');
     const parsed = JSON.parse(raw);
@@ -139,27 +203,42 @@ export async function clearActiveExtension(opts = {}) {
   } catch {
     // ignore — extName stays null
   }
+
+  // Drive the canonical clear through the SDK verb (manifest:null is the
+  // documented clear semantics — see STATE-SDK-CONTRACT.md §7).
+  // The verb is idempotent on an absent file (best-effort unlink).
+  let verbOk = false;
   try {
-    await unlink(statePath(home));
-    if (extName) {
-      try {
-        await resetExtensionQuotas(extName, { homeDir: home });
-      } catch {
-        // best-effort
-      }
-    }
-    return { ok: true, removed: true };
-  } catch (err) {
-    if (err && err.code === 'ENOENT') {
-      if (extName) {
-        try {
-          await resetExtensionQuotas(extName, { homeDir: home });
-        } catch { /* best-effort */ }
-      }
-      return { ok: true, removed: false };
-    }
-    return { ok: false, removed: false };
+    const r = await query('extension.set-active', {
+      manifest: null,
+      // The verb requires a valid scope. 'project' is a safe sentinel — the
+      // clear branch does not consult `scope` for any state-file content
+      // (clear unlinks the file unconditionally). Any of the three valid
+      // values would work.
+      scope: 'project',
+      homeDir: home,
+    }, {
+      projectRoot: pickProjectRoot(opts),
+      homeDir: home,
+    });
+    verbOk = !!(r && r.ok);
+  } catch {
+    verbOk = false;
+  }
+
+  // Always reset quota counters if we know the ext name, regardless of
+  // whether the verb succeeded or the file was present — mirrors the
+  // legacy writer's ENOENT-tolerant best-effort reset.
+  if (extName) {
+    try {
+      await resetExtensionQuotas(extName, { homeDir: home });
+    } catch { /* best-effort */ }
+  }
+
+  if (verbOk) {
+    return { ok: true, removed: wasPresent };
   }
+  return { ok: false, removed: false };
 }
 
 /**
@@ -247,7 +326,8 @@ async function writeLastSeen(ideId, opts = {}) {
   try {
     await mkdir(dirname(path), { recursive: true });
     const body = JSON.stringify({ ide: ideId, last_seen_at: new Date().toISOString() }, null, 2) + '\n';
-    const tmp = `${path}.tmp.${randomBytes(4).toString('hex')}`;
+    // v1.5.0 audit-LOW-update-#13: tmpSuffix() replaces inline randomBytes call.
+    const tmp = `${path}.tmp.${tmpSuffix({ bytes: 4, includePid: false })}`;
     await writeFile(tmp, body, 'utf8');
     const { rename } = await import('node:fs/promises');
     await rename(tmp, path);

package/src/api-client.js

@@ -8,6 +8,19 @@ import { getTemplate } from './cross-dispatcher.js';
 
 const DEFAULT_TIMEOUT_MS = 30_000;
 
+// v1.5.0 audit-DISPUTED-1 — user-message cache_control threshold.
+//
+// Anthropic prompt-caching has a server-side minimum (~1024 tokens). We
+// gate the user-content-block split on a conservative 2KB byte cutoff so
+// short audits (which would never recover the cache-write overhead)
+// remain plain strings, while large diff/transcript targets (which DO
+// amortize the cache) get split into a cacheable prefix + ephemeral tail.
+//
+// Pairs with the H4.2 ordering invariant: cycleSummary (or any per-turn
+// content) MUST land AFTER the cacheable block so it never busts the
+// cache prefix. See ADJUDICATIONS.md DISPUTED-1.
+const CACHE_USER_THRESHOLD_BYTES = 2048;
+
 // ---------------------------------------------------------------------------
 // Provider request builders
 // ---------------------------------------------------------------------------
@@ -68,7 +81,7 @@ function buildGemini(system, user, model, key, timeoutMs, endpoint) {
 // Sonnet 4.5 prompt-caching threshold: 1024 tokens (rough: chars / 4).
 const CACHE_TOKEN_THRESHOLD = 1024;
 
-function buildAnthropic(system, user, model, key, timeoutMs) {
+function buildAnthropic(system, user, model, key, timeoutMs, cycleSummary = null) {
   const promptChars = system.length + user.length;
   const estimatedTokens = Math.floor(promptChars / 4);
   const cacheEligible = estimatedTokens >= CACHE_TOKEN_THRESHOLD;
@@ -77,6 +90,26 @@ function buildAnthropic(system, user, model, key, timeoutMs) {
     ? [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }]
     : system;
 
+  // v1.5.0 audit-DISPUTED-1 — user-message cache_control.
+  //
+  // When the user content is large enough to amortize the cache-write
+  // overhead, split into a content-blocks array: the stable target gets
+  // cache_control:{type:'ephemeral'}, and any per-turn tail (cycleSummary)
+  // follows as a plain text block so it never busts the cache prefix.
+  //
+  // Below the threshold we keep the legacy plain-string form -- no need
+  // to spend cache-write tokens we can't recover.
+  const userBytes = Buffer.byteLength(user, 'utf8');
+  let userContent;
+  if (userBytes >= CACHE_USER_THRESHOLD_BYTES) {
+    const cacheableBlock = { type: 'text', text: user, cache_control: { type: 'ephemeral' } };
+    userContent = cycleSummary
+      ? [cacheableBlock, { type: 'text', text: cycleSummary }]
+      : [cacheableBlock];
+  } else {
+    userContent = user;
+  }
+
   return {
     url: 'https://api.anthropic.com/v1/messages',
     options: {
@@ -91,7 +124,7 @@ function buildAnthropic(system, user, model, key, timeoutMs) {
         model,
         max_tokens: 4096,
         system: systemBlock,
-        messages: [{ role: 'user', content: user }],
+        messages: [{ role: 'user', content: userContent }],
       }),
       signal: AbortSignal.timeout(timeoutMs),
     },
@@ -138,9 +171,13 @@ function extractCacheStats(json, cacheEligible) {
 // Main export
 // ---------------------------------------------------------------------------
 
-// runViaApi(pick, mode, angle, target, env, timeoutMs?, abortSignal?)
+// runViaApi(pick, mode, angle, target, env, timeoutMs?, abortSignal?, opts?)
 // Returns { status: 'ok', raw, model } or { status: 'failed', error, model }.
-export async function runViaApi(pick, mode, angle, target, env = process.env, timeoutMs = DEFAULT_TIMEOUT_MS, abortSignal = null) {
+//
+// opts.cycleSummary (string|null): when set on Anthropic calls, lands in a
+// trailing ephemeral content block AFTER the cacheable user block so it
+// never busts the cache prefix. Ignored for non-Anthropic providers.
+export async function runViaApi(pick, mode, angle, target, env = process.env, timeoutMs = DEFAULT_TIMEOUT_MS, abortSignal = null, opts = {}) {
   const fb = pick.apiFallback;
   if (!fb) return { status: 'failed', error: 'no API fallback configured', model: '' };
 
@@ -149,6 +186,7 @@ export async function runViaApi(pick, mode, angle, target, env = process.env, ti
 
   const { system, format } = getTemplate(mode, angle);
   const user = `${format}\n\n## Target\n\n${target}`;
+  const cycleSummary = opts.cycleSummary ?? null;
 
   // Combine caller abort signal with our per-call timeout signal.
   const timeoutSig = AbortSignal.timeout(timeoutMs);
@@ -164,7 +202,7 @@ export async function runViaApi(pick, mode, angle, target, env = process.env, ti
   } else if (fb.provider === 'google') {
     req = buildGemini(system, user, fb.model, key, timeoutMs, fb.endpoint);
   } else if (fb.provider === 'anthropic') {
-    req = buildAnthropic(system, user, fb.model, key, timeoutMs);
+    req = buildAnthropic(system, user, fb.model, key, timeoutMs, cycleSummary);
   } else {
     return { status: 'failed', error: `unknown provider: ${fb.provider}`, model: fb.model };
   }

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;
 }