@ijfw/memory-server 1.4.3 → 1.5.0

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`);

package/src/codex-agents.js

@@ -1,7 +1,33 @@
-import { existsSync, mkdirSync, readFileSync } from 'node:fs';
-import { join, resolve } from 'node:path';
+import { existsSync, mkdirSync, readFileSync, realpathSync } from 'node:fs';
+import { isAbsolute, join, relative, resolve } from 'node:path';
 import { writeAtomic } from './lib/atomic-io.js';
 
+// F-FUN-7 (audit-MED-teams-#8): role-type → Codex tool allowlist. Honors
+// the principle of least authority: research roles read only, review roles
+// read+edit, software/lead/qa get the full toolbelt, book/content roles get
+// Read/Write/Edit (they author durable text artifacts). Unknown role types
+// fall back to the conservative software set so a missing entry never
+// silently downgrades a charter we already accepted.
+export const ROLE_TOOL_ALLOWLIST = Object.freeze({
+  research:   ['Read'],
+  review:     ['Read', 'Edit'],
+  software:   ['Read', 'Write', 'Edit', 'Bash'],
+  lead:       ['Read', 'Write', 'Edit', 'Bash'],
+  qa:         ['Read', 'Write', 'Edit', 'Bash'],
+  book:       ['Read', 'Write', 'Edit'],
+  content:    ['Read', 'Write', 'Edit'],
+  design:     ['Read', 'Write', 'Edit'],
+  business:   ['Read', 'Write', 'Edit'],
+  education:  ['Read', 'Write', 'Edit'],
+  operations: ['Read', 'Write', 'Edit', 'Bash'],
+});
+
+export function toolsForRoleType(roleType) {
+  const fallback = ROLE_TOOL_ALLOWLIST.software;
+  if (!roleType || typeof roleType !== 'string') return fallback;
+  return ROLE_TOOL_ALLOWLIST[roleType] || fallback;
+}
+
 export function renderCodexAgentToml(role, bundle = {}) {
   assertRole(role);
   const charter = bundle.charter || bundle;
@@ -23,6 +49,12 @@ export function renderCodexAgentToml(role, bundle = {}) {
     lines.push(`model_reasoning_effort = ${tomlString(codexConfig.model_reasoning_effort.trim())}`);
   }
 
+  // F-FUN-7 (audit-MED-teams-#8): emit a role-type-keyed tools allowlist. The
+  // Codex agent runtime honors this as the per-agent toolbelt; research roles
+  // get read-only, software/lead/qa get the full set, etc.
+  const tools = toolsForRoleType(role.role_type);
+  lines.push(`tools = ${tomlStringArray(tools)}`);
+
   lines.push(`developer_instructions = ${tomlMultiline(instructions)}`);
   return `${lines.join('\n')}\n`;
 }
@@ -37,21 +69,75 @@ export function syncCodexAgents(projectRoot = process.cwd(), options = {}) {
   const agentsDir = join(root, '.codex', 'agents');
   mkdirSync(agentsDir, { recursive: true, mode: 0o700 });
 
+  // F-SEC-3 (audit-MED-teams-#12): symlink-realpath containment gate. If the
+  // .codex/agents/ target was swapped for a symlink that points outside the
+  // project root, writing into it would let a hostile project escape its
+  // own boundary. realpathSync resolves the link, and we require the
+  // resolved path to live inside the realpath'd project root.
+  const containment = assertAgentsDirContained(root, agentsDir);
+  if (!containment.ok) {
+    return { ok: false, error: containment.error, agentsDir, agentFiles: [], detail: containment.detail };
+  }
+  const safeAgentsDir = containment.realpath;
+
   const agentFiles = [];
+  let skipped = 0;
   for (const role of bundle.charter.roles) {
-    const agentPath = join(agentsDir, `${codexAgentFilename(role.name)}.toml`);
-    writeAtomic(agentPath, renderCodexAgentToml(role, bundle), { mode: 0o600 });
+    const agentPath = join(safeAgentsDir, `${codexAgentFilename(role.name)}.toml`);
+    const rendered = renderCodexAgentToml(role, bundle);
+    // F-SPD-3 (audit-MED-teams-#11): content-hash skip. Reading the existing
+    // file is cheap (TOML agent files are small) and avoids touching mtime
+    // when nothing changed -- which in turn keeps downstream watchers and
+    // Codex-side hot-reloaders from doing redundant work.
+    if (existsSync(agentPath)) {
+      let existing = '';
+      try { existing = readFileSync(agentPath, 'utf8'); } catch { existing = ''; }
+      if (existing === rendered) {
+        agentFiles.push(agentPath);
+        skipped += 1;
+        continue;
+      }
+    }
+    writeAtomic(agentPath, rendered, { mode: 0o600 });
     agentFiles.push(agentPath);
   }
 
   return {
     ok: true,
-    agentsDir,
+    agentsDir: safeAgentsDir,
     agentFiles,
     count: agentFiles.length,
+    skipped,
   };
 }
 
+// F-SEC-3: contain `.codex/agents/` to the project root. Returns the
+// realpath-resolved agents dir so callers write through the resolved path
+// (defence-in-depth: if a future writer re-uses `agentsDir` we still touch
+// the same vetted location).
+function assertAgentsDirContained(projectRoot, agentsDir) {
+  let resolvedRoot;
+  let resolvedAgents;
+  try {
+    resolvedRoot = realpathSync(projectRoot);
+  } catch (err) {
+    return { ok: false, error: 'project-realpath-failed', detail: String(err?.message || err) };
+  }
+  try {
+    resolvedAgents = realpathSync(agentsDir);
+  } catch (err) {
+    // Newly-created dir may not yet have a resolvable realpath if a parent
+    // is a symlink; fall back to the un-resolved path for containment but
+    // verify the parent is contained.
+    return { ok: false, error: 'agents-realpath-failed', detail: String(err?.message || err) };
+  }
+  const rel = relative(resolvedRoot, resolvedAgents);
+  if (rel === '' || rel.startsWith('..') || isAbsolute(rel)) {
+    return { ok: false, error: 'agents-escapes-project', detail: `agentsDir=${resolvedAgents} root=${resolvedRoot}` };
+  }
+  return { ok: true, realpath: resolvedAgents };
+}
+
 function readTeamBundle(root) {
   const charterPath = join(root, '.ijfw', 'team', 'charter.json');
   if (!existsSync(charterPath)) return null;
@@ -168,6 +254,11 @@ function tomlString(value) {
   return JSON.stringify(String(value));
 }
 
+function tomlStringArray(values) {
+  const items = list(values).map((v) => tomlString(String(v)));
+  return `[${items.join(', ')}]`;
+}
+
 function tomlMultiline(value) {
   return `"""\n${String(value).replace(/"""/g, '\\"\\"\\"')}\n"""`;
 }

package/src/cost/aggregator.js

@@ -124,29 +124,59 @@ export function buildCostReport(days, observations = []) {
   };
 }
 
+// v1.5.0 audit-LOW-tok-L3: memoize buildBreakdown per (dim, days, bucket).
+// Dashboards call this endpoint repeatedly on a 10s tick across four
+// dimensions; each call re-reads ~3 platforms of transcript JSON. Within
+// a 60-second time bucket the result is functionally identical, so cache
+// it. TTL is short enough that newly-arriving turns surface within one
+// dashboard refresh interval.
+const BREAKDOWN_CACHE_TTL_MS = 60_000;
+const _breakdownCache = new Map();
+
+function _bucketKey(dim, days, now = Date.now()) {
+  const bucket = Math.floor(now / BREAKDOWN_CACHE_TTL_MS);
+  return `${dim}|${days ?? 'all'}|${bucket}`;
+}
+
+// Test helper: clear the memoization cache.
+export function _resetBreakdownCache() { _breakdownCache.clear(); }
+
 /**
  * Build a breakdown grouped by a dimension.
  * dim: 'platform' | 'session' | 'model' | 'tool'
  */
 export function buildBreakdown(dim, days, _observations = []) {
+  const key = _bucketKey(dim, days);
+  const cached = _breakdownCache.get(key);
+  if (cached) return cached;
+
   const raw   = readAllTurns(days);
   const turns = annotateCosts(raw);
 
   const groups = {};
   for (const t of turns) {
-    const key = t[dim] || 'unknown';
-    if (!groups[key]) groups[key] = { key, cost_usd: 0, theoretical_cost_usd: 0, input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, count: 0 };
-    groups[key].cost_usd             += t.cost_usd;
-    groups[key].theoretical_cost_usd += t.theoretical_cost_usd || 0;
-    groups[key].input_tokens         += t.input_tokens || 0;
-    groups[key].output_tokens        += t.output_tokens || 0;
-    groups[key].cache_read_tokens    += t.cache_read_tokens || 0;
-    groups[key].count++;
+    const k = t[dim] || 'unknown';
+    if (!groups[k]) groups[k] = { key: k, cost_usd: 0, theoretical_cost_usd: 0, input_tokens: 0, output_tokens: 0, cache_read_tokens: 0, count: 0 };
+    groups[k].cost_usd             += t.cost_usd;
+    groups[k].theoretical_cost_usd += t.theoretical_cost_usd || 0;
+    groups[k].input_tokens         += t.input_tokens || 0;
+    groups[k].output_tokens        += t.output_tokens || 0;
+    groups[k].cache_read_tokens    += t.cache_read_tokens || 0;
+    groups[k].count++;
   }
 
   // Sort by theoretical cost so Max-session breakdowns still rank by usage
   // intensity even when cost_usd is uniformly zero.
-  return Object.values(groups).sort((a, b) => b.theoretical_cost_usd - a.theoretical_cost_usd);
+  const result = Object.values(groups).sort((a, b) => b.theoretical_cost_usd - a.theoretical_cost_usd);
+
+  // Bound the cache: keep at most 32 entries (4 dims * 8 window/bucket combos).
+  // Eviction is opportunistic on insert -- O(1) amortised.
+  if (_breakdownCache.size >= 32) {
+    const firstKey = _breakdownCache.keys().next().value;
+    if (firstKey !== undefined) _breakdownCache.delete(firstKey);
+  }
+  _breakdownCache.set(key, result);
+  return result;
 }
 
 /**