@ijfw/memory-server 1.4.4 → 1.5.1

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,7 +1,7 @@
 {
   "name": "@ijfw/memory-server",
-  "version": "1.4.4",
-  "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.",
+  "version": "1.5.1",
+  "description": "Cross-platform persistent memory server for IJFW. 13 MCP tools (memory + admin/update). Works with 15 platforms: 14 via MCP (Claude Code, Codex, Gemini CLI, Cursor, Windsurf, Copilot, Hermes, Wayland, OpenCode, QwenCode, Cline, KimiCode, OpenClaw, Antigravity) plus Aider via the rules-only tier.",
   "author": "Sean Donahoe",
   "license": "MIT",
   "type": "module",
@@ -14,7 +14,10 @@
   "scripts": {
     "start": "node src/server.js",
     "dev": "node --watch src/server.js",
-    "test": "node test.js"
+    "test": "node test.js && node --experimental-sqlite --test --test-force-exit test-*.js",
+    "test:smoke": "node test.js",
+    "test:full": "node --experimental-sqlite --test --test-force-exit test-*.js",
+    "test:graders": "node test/grade-symbol-graph-spec.js && node test/grade-symbol-graph-consistency.js && node test/grade-cascading-staleness.js && node test/grade-project-types.js"
   },
   "engines": {
     "node": ">=18.0.0"

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