@ijfw/memory-server 1.3.0

package/src/api-client.js

@@ -0,0 +1,190 @@
+// api-client.js -- API-key fallback for cross-audit/research/critique.
+//
+// Uses Node 19+ native fetch (Undici). Zero external deps.
+// Each provider gets its own request builder; the caller treats the
+// returned text like CLI stdout.
+
+import { getTemplate } from './cross-dispatcher.js';
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+// ---------------------------------------------------------------------------
+// Provider request builders
+// ---------------------------------------------------------------------------
+
+// Optional `endpoint` argument lets OpenAI-compatible providers (Qwen via
+// DashScope, Together, Groq, etc.) reuse the same request/response shape
+// while pointing at their own URL. When omitted, falls back to OpenAI's
+// canonical chat-completions endpoint.
+function buildOpenAI(system, user, model, key, timeoutMs, endpoint) {
+  return {
+    url: endpoint || 'https://api.openai.com/v1/chat/completions',
+    options: {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'Authorization': `Bearer ${key}`,
+      },
+      body: JSON.stringify({
+        model,
+        messages: [
+          { role: 'system', content: system },
+          { role: 'user',   content: user   },
+        ],
+      }),
+      signal: AbortSignal.timeout(timeoutMs),
+    },
+  };
+}
+
+function buildGemini(system, user, model, key, timeoutMs, endpoint) {
+  // 1.2.5: defensive guard against missing endpoint (B3.1) -- the roster entry
+  // always supplies one for provider:'google', but the runtime guard means a
+  // misconfigured fallback fails with a clear error instead of TypeError.
+  if (!endpoint || typeof endpoint !== 'string') {
+    throw new Error('buildGemini: apiFallback.endpoint is required for provider="google"');
+  }
+  // 1.2.5: drop the redundant ?key= URL parameter (B3.2). Auth flows entirely
+  // through the x-goog-api-key header below; the URL form was redundant +
+  // slightly leakier (logs / proxies can capture URLs more easily than headers).
+  const url = endpoint.replace('{model}', model);
+  return {
+    url,
+    options: {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-goog-api-key': key,
+      },
+      body: JSON.stringify({
+        systemInstruction: { parts: [{ text: system }] },
+        contents: [{ role: 'user', parts: [{ text: user }] }],
+      }),
+      signal: AbortSignal.timeout(timeoutMs),
+    },
+  };
+}
+
+// Sonnet 4.5 prompt-caching threshold: 1024 tokens (rough: chars / 4).
+const CACHE_TOKEN_THRESHOLD = 1024;
+
+function buildAnthropic(system, user, model, key, timeoutMs) {
+  const promptChars = system.length + user.length;
+  const estimatedTokens = Math.floor(promptChars / 4);
+  const cacheEligible = estimatedTokens >= CACHE_TOKEN_THRESHOLD;
+
+  const systemBlock = cacheEligible
+    ? [{ type: 'text', text: system, cache_control: { type: 'ephemeral' } }]
+    : system;
+
+  return {
+    url: 'https://api.anthropic.com/v1/messages',
+    options: {
+      method: 'POST',
+      headers: {
+        'Content-Type': 'application/json',
+        'x-api-key': key,
+        'anthropic-version': '2023-06-01',
+        'anthropic-beta': 'prompt-caching-2024-07-31',
+      },
+      body: JSON.stringify({
+        model,
+        max_tokens: 4096,
+        system: systemBlock,
+        messages: [{ role: 'user', content: user }],
+      }),
+      signal: AbortSignal.timeout(timeoutMs),
+    },
+    _cacheEligible: cacheEligible,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Text extractor -- normalises the three provider response shapes
+// ---------------------------------------------------------------------------
+
+function extractText(provider, json) {
+  // openai-compat (Qwen via DashScope, Together, Groq, etc.) reuses the
+  // OpenAI chat-completions response shape, so the extractor is shared.
+  if (provider === 'openai' || provider === 'openai-compat') {
+    return json?.choices?.[0]?.message?.content ?? '';
+  }
+  if (provider === 'google') {
+    return json?.candidates?.[0]?.content?.parts?.[0]?.text ?? '';
+  }
+  if (provider === 'anthropic') {
+    const block = (json?.content ?? []).find(b => b.type === 'text');
+    return block?.text ?? '';
+  }
+  return '';
+}
+
+function extractCacheStats(json, cacheEligible) {
+  if (!cacheEligible) {
+    return {
+      cache_eligible: false,
+      cache_eligible_reason: 'prompt < 1024 tokens',
+    };
+  }
+  const usage = json?.usage ?? {};
+  return {
+    cache_creation_input_tokens: usage.cache_creation_input_tokens ?? 0,
+    cache_read_input_tokens: usage.cache_read_input_tokens ?? 0,
+    cache_eligible: true,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Main export
+// ---------------------------------------------------------------------------
+
+// runViaApi(pick, mode, angle, target, env, timeoutMs?, abortSignal?)
+// 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) {
+  const fb = pick.apiFallback;
+  if (!fb) return { status: 'failed', error: 'no API fallback configured', model: '' };
+
+  const key = env[fb.authEnv];
+  if (!key) return { status: 'failed', error: `${fb.authEnv} not set`, model: fb.model };
+
+  const { system, format } = getTemplate(mode, angle);
+  const user = `${format}\n\n## Target\n\n${target}`;
+
+  // Combine caller abort signal with our per-call timeout signal.
+  const timeoutSig = AbortSignal.timeout(timeoutMs);
+  const combinedSignal = abortSignal ? AbortSignal.any([timeoutSig, abortSignal]) : timeoutSig;
+
+  let req;
+  if (fb.provider === 'openai') {
+    req = buildOpenAI(system, user, fb.model, key, timeoutMs);
+  } else if (fb.provider === 'openai-compat') {
+    // OpenAI-compatible endpoints (Qwen via DashScope, Together, Groq, etc.)
+    // share the chat-completions request/response shape and only differ on URL.
+    req = buildOpenAI(system, user, fb.model, key, timeoutMs, fb.endpoint);
+  } 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);
+  } else {
+    return { status: 'failed', error: `unknown provider: ${fb.provider}`, model: fb.model };
+  }
+  // Override signal to use the combined abort signal.
+  req.options.signal = combinedSignal;
+
+  try {
+    const res = await fetch(req.url, req.options);
+    if (!res.ok) {
+      const body = await res.text().catch(() => '');
+      return { status: 'failed', error: `HTTP ${res.status}: ${body.slice(0, 300)}`, model: fb.model };
+    }
+    const json = await res.json();
+    const raw = extractText(fb.provider, json);
+    if (fb.provider === 'anthropic') {
+      const cache_stats = extractCacheStats(json, req._cacheEligible);
+      return { status: 'ok', raw, model: fb.model, cache_stats };
+    }
+    return { status: 'ok', raw, model: fb.model };
+  } catch (err) {
+    return { status: 'failed', error: err.message ?? String(err), model: fb.model };
+  }
+}

package/src/audit-roster.js

@@ -0,0 +1,315 @@
+// --- Cross-audit roster (P5 followup) ---
+//
+// Who can we ask for a second opinion? This module knows the roster of
+// audit-capable CLI tools, fingerprints the currently-running caller via
+// env vars, AND probes whether each CLI is actually installed on PATH.
+//
+// Donahoe principle: never trust a single AI; run through (at least) three.
+// Caller is one. We aim to suggest two reviewers -- the Trident.
+//
+// Detection is conservative: we'd rather show all options than silently
+// exclude a valid one. If we genuinely can't tell who's calling, nothing
+// gets filtered as "self."
+
+import { spawnSync } from 'node:child_process';
+
+export const ROSTER = [
+  {
+    id: 'codex',
+    family: 'openai',
+    model: '',
+    name: 'Codex CLI',
+    invoke: 'codex exec --skip-git-repo-check --sandbox read-only -c approval_policy="never" -c mcp_servers.ijfw-memory.enabled=false -',
+    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
+    // is *installed* (not just when active), so checking it here would falsely
+    // self-exclude codex from every Trident run on machines that have codex
+    // 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' },
+  },
+  {
+    id: 'gemini',
+    family: 'google',
+    model: '',
+    name: 'Gemini CLI',
+    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' },
+  },
+  {
+    id: 'qwen',
+    family: 'oss',
+    model: '',
+    name: 'Qwen Code',
+    invoke: 'qwen -p',
+    note: 'Apache-2.0 weights (Qwen3-Coder-480B-A35B), agentic-tuned (~67% SWE-Bench Verified). Fork of gemini-cli; supports qwen-oauth (free Coding Plan tier), plus openai/anthropic/gemini auth-types via `qwen auth`. Diversity value for Trident: third independent training lineage outside openai/google.',
+    detect: (env) => Boolean(env.QWEN_SESSION) || /(?:^|\W)qwen(?:\W|$)/i.test(env._ || ''),
+    apiFallback: { provider: 'openai-compat', model: 'qwen3-coder-plus', authEnv: 'DASHSCOPE_API_KEY', endpoint: 'https://dashscope-intl.aliyuncs.com/compatible-mode/v1/chat/completions' },
+  },
+  {
+    id: 'deepseek',
+    family: 'oss',
+    model: '',
+    name: 'DeepSeek',
+    invoke: 'deepseek',
+    note: 'DeepSeek-V4 (Chinese open-source lineage, MIT-licensed weights). Distinct training data and posttraining recipe from openai/google/anthropic, which is exactly what the Trident wants for adversarial review. No first-party canonical CLI -- multiple third-party CLIs exist; API path via DeepSeek Platform is the load-bearing one for this entry. Pricing is among the cheapest of any reasoning-capable model on the roster.',
+    detect: () => false,
+    apiFallback: { provider: 'openai-compat', model: 'deepseek-v4-pro', authEnv: 'DEEPSEEK_API_KEY', endpoint: 'https://api.deepseek.com/v1/chat/completions' },
+  },
+  {
+    id: 'kimi',
+    family: 'oss',
+    model: '',
+    name: 'Kimi (Moonshot)',
+    invoke: 'kimi',
+    note: 'Moonshot AI Kimi K2 series (Chinese open-source lineage, separate from DeepSeek). Long-context strength makes it useful for whole-file or whole-module audits where context window matters. OpenAI-compatible API via platform.moonshot.ai. Detection is left at false because no canonical session env var ships with Kimi today -- prefer double-coverage over false self-exclusion.',
+    detect: () => false,
+    apiFallback: { provider: 'openai-compat', model: 'kimi-k2.6', authEnv: 'MOONSHOT_API_KEY', endpoint: 'https://api.moonshot.ai/v1/chat/completions' },
+  },
+  {
+    id: 'opencode',
+    family: 'oss',
+    model: '',
+    name: 'opencode',
+    invoke: 'opencode',
+    note: 'OSS / local-friendly; good when privacy matters.',
+    detect: (env) => Boolean(env.OPENCODE_SESSION || env.OPENCODE_HOME),
+    apiFallback: null,
+  },
+  {
+    id: 'aider',
+    family: 'oss',
+    model: '',
+    name: 'Aider',
+    invoke: 'aider --message',
+    note: 'Code-focused peer; terse + diff-aware.',
+    detect: (env) => Boolean(env.AIDER_SESSION) || /aider/i.test(env._ || ''),
+    apiFallback: null,
+  },
+  {
+    id: 'copilot',
+    family: 'openai',
+    model: '',
+    name: 'Copilot CLI',
+    invoke: 'gh copilot suggest',
+    note: 'Convenient if gh CLI is already authenticated.',
+    detect: (env) => Boolean(env.GH_COPILOT_TOKEN || env.COPILOT_CLI_SESSION),
+    apiFallback: null,
+  },
+  {
+    id: 'claude',
+    family: 'anthropic',
+    model: '',
+    name: 'Claude Code',
+    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' },
+  },
+];
+
+// Returns the id of the current caller, or null if unknown.
+export function detectSelf(env = process.env) {
+  for (const entry of ROSTER) {
+    try { if (entry.detect(env)) return entry.id; } catch { /* ignore */ }
+  }
+  return null;
+}
+
+// Probe whether the auditor's CLI is on PATH. Cached per process.
+// Exported so tests can prime the cache for deterministic behavior.
+export const _installedCache = new Map();
+export function isInstalled(id) {
+  if (_installedCache.has(id)) return _installedCache.get(id);
+  const entry = ROSTER.find(e => e.id === id);
+  if (!entry) return false;
+  // First word of invoke is the binary; the rest are args.
+  const bin = entry.invoke.split(/\s+/)[0];
+  // POSIX `command -v` is the portable existence check; bash builtin form
+  // 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);
+  return installed;
+}
+
+// Check reachability: CLI (PATH probe) and/or API (env key present).
+// Returns { cli: bool, api: bool, any: bool }. Does not touch isInstalled signature.
+export function isReachable(id, env = process.env) {
+  const entry = ROSTER.find(e => e.id === id);
+  if (!entry) return { cli: false, api: false, any: false };
+  const cli = isInstalled(id);
+  const api = Boolean(entry.apiFallback && env[entry.apiFallback.authEnv]);
+  return { cli, api, any: cli || api };
+}
+
+// Returns roster entries with isSelf + installed flags resolved.
+export function rosterWithStatus(env = process.env) {
+  const self = detectSelf(env);
+  return ROSTER.map(e => ({ ...e, isSelf: e.id === self, installed: isInstalled(e.id) }));
+}
+
+// The Trident: pick up to N (default 2) installed, non-self auditors in
+// roster priority order. Returns { picks: [], missing: [], note: string }.
+//   - picks: chosen auditor entries, ready to invoke
+//   - missing: roster entries we'd have liked but aren't installed
+//   - note: human-readable advisory (Donahoe trident reminder when only 1)
+export function pickAuditors({ count = 2, env = process.env, only = null, strategy = 'priority' } = {}) {
+  const all = rosterWithStatus(env);
+  // Annotate a pick with preferredSource:'api' when reachable only via API key.
+  function annotatePick(e) {
+    const reach = isReachable(e.id, env);
+    if (!reach.cli && reach.api) return { ...e, preferredSource: 'api' };
+    return e;
+  }
+
+  if (only) {
+    const ids = String(only).split(/[ ,]+/).map(s => s.toLowerCase()).filter(Boolean);
+    const picks = ids.map(id => all.find(e => e.id === id)).filter(Boolean);
+    // Self-exclusion applies to --with too -- the Trident's value is
+    // multi-lineage diversity, so requesting the caller's own family ID
+    // collapses to a single-source review. Surface it instead of running it.
+    const selfPicks = picks.filter(e => e.isSelf);
+    const nonSelfPicks = picks.filter(e => !e.isSelf);
+    const reachablePicks = nonSelfPicks.filter(e => isReachable(e.id, env).any);
+    const unreachable = nonSelfPicks.filter(e => !isReachable(e.id, env).any);
+    const missing = [...unreachable, ...selfPicks];
+    const noteParts = [];
+    if (unreachable.length) noteParts.push(`Requested but not reachable: ${unreachable.map(e => e.id).join(', ')}.`);
+    if (selfPicks.length) noteParts.push(`Skipped self-audit on ${selfPicks.map(e => e.id).join(', ')} -- pass a different auditor for cross-lineage review.`);
+    return {
+      picks: reachablePicks.map(annotatePick),
+      missing,
+      note: noteParts.join(' '),
+    };
+  }
+
+  if (strategy === 'diversity') {
+    const selfId = detectSelf(env);
+    const selfEntry = ROSTER.find(e => e.id === selfId);
+    const callerFamily = selfEntry ? selfEntry.family : null;
+
+    // Reachable (CLI or API) non-self entries, grouped by family
+    const eligible = all.filter(e => !e.isSelf && isReachable(e.id, env).any);
+    const byFamily = (fam) => eligible.filter(e => e.family === fam);
+
+    const TARGET_FAMILIES = ['openai', 'google'];
+    const picks = [];
+    const picked = new Set();
+    const missing = [];
+    const nudges = [];
+
+    for (const fam of TARGET_FAMILIES) {
+      if (fam === callerFamily) {
+        // Caller is in this family -- pick next-best family (oss, or other non-self)
+        const backfill = eligible.find(e => !picked.has(e.id) && e.family !== callerFamily);
+        if (backfill) {
+          picks.push(annotatePick(backfill));
+          picked.add(backfill.id);
+          nudges.push(`No ${fam}-family auditor outside caller -- using ${backfill.id} (${backfill.family}) as stand-in. Install a ${fam === 'openai' ? 'google' : 'openai'}-family auditor for full Trident diversity.`);
+        } else {
+          missing.push({ family: fam, reason: `no reachable auditor in family ${fam}` });
+        }
+        continue;
+      }
+      const candidates = byFamily(fam);
+      if (candidates.length > 0) {
+        const pick = candidates.find(e => !picked.has(e.id));
+        if (pick) {
+          picks.push(annotatePick(pick));
+          picked.add(pick.id);
+        } else {
+          // All family members already picked -- leave slot missing
+          missing.push({ family: fam, reason: `all reachable auditors in family ${fam} already selected` });
+        }
+      } else {
+        // No reachable member of this family -- backfill from oss or any remaining non-self
+        const backfill = eligible.find(e => !picked.has(e.id) && e.family !== callerFamily && !TARGET_FAMILIES.includes(e.family));
+        missing.push({ family: fam, reason: `no reachable auditor in family ${fam}` });
+        if (backfill) {
+          picks.push(annotatePick(backfill));
+          picked.add(backfill.id);
+          nudges.push(`No ${fam}-family auditor reachable -- using ${backfill.id} (${backfill.family}) as stand-in. Install gemini (google) or codex/copilot (openai) for full Trident lineage diversity.`);
+        }
+      }
+    }
+
+    // If we still have fewer than 2 picks, backfill from any remaining eligible
+    if (picks.length < 2) {
+      for (const e of eligible) {
+        if (picks.length >= 2) break;
+        if (!picked.has(e.id)) {
+          picks.push(annotatePick(e));
+          picked.add(e.id);
+        }
+      }
+    }
+
+    const baseNote = picks.length === 0
+      ? 'No external auditors reachable. Install codex, gemini, opencode, aider, or copilot (or set OPENAI_API_KEY / GEMINI_API_KEY) to use cross-audit.'
+      : picks.length < 2
+        ? `Donahoe Trident principle: cross-audit works best with two top-tier AIs reviewing alongside the caller. Only ${picks.length} reachable (${picks.map(e => e.id).join(', ')}); install another to triangulate findings.`
+        : '';
+    const note = [baseNote, ...nudges].filter(Boolean).join(' ');
+    return { picks, missing, note };
+  }
+
+  // Default: priority strategy
+  const eligible = all.filter(e => !e.isSelf && isReachable(e.id, env).any);
+  const picks = eligible.slice(0, count).map(annotatePick);
+  const wantMore = count - picks.length;
+  let note = '';
+  if (picks.length === 0) {
+    note = 'No external auditors reachable. Install codex, gemini, opencode, aider, or copilot (or set OPENAI_API_KEY / GEMINI_API_KEY) to use cross-audit.';
+  } else if (picks.length < count) {
+    note = `Donahoe Trident principle: cross-audit works best with two top-tier AIs reviewing alongside the caller. Only ${picks.length} reachable (${picks.map(e => e.id).join(', ')}); ${wantMore} short. Install another to triangulate findings -- single-reviewer audits miss what overlap would catch.`;
+  }
+  return { picks, missing: all.filter(e => !e.isSelf && !isReachable(e.id, env).any), note };
+}
+
+// Returns roster entries, marking self and filtering when requested.
+//   { excludeSelf: bool, only: string | null }
+export function rosterFor({ excludeSelf = true, only = null, env = process.env } = {}) {
+  const self = detectSelf(env);
+  let list = ROSTER.map(e => ({ ...e, isSelf: e.id === self }));
+  if (only) {
+    const match = list.find(e => e.id === only.toLowerCase());
+    return match ? [match] : [];
+  }
+  if (excludeSelf && self) list = list.filter(e => !e.isSelf);
+  return list;
+}
+
+// Pick the top default auditor: highest-priority non-self entry that is
+// actually reachable via CLI or API key. Returning a non-reachable pick used
+// to give callers a misleading "ready" answer that fell over on first invoke.
+export function defaultAuditor(env = process.env) {
+  const list = rosterFor({ excludeSelf: true, env });
+  const reachable = list.find(e => isReachable(e.id, env).any);
+  return reachable || list[0] || null;
+}
+
+// Pretty-print the roster for user consumption. Now shows install status
+// and self marker so the user sees instantly what's actionable.
+export function formatRoster(env = process.env) {
+  const self = detectSelf(env);
+  const all = rosterWithStatus(env);
+  const lines = [];
+  for (const e of all) {
+    // 'ready' covers CLI-installed AND API-only-reachable (e.g., user has
+    // OPENAI_API_KEY set but no codex binary on PATH). Previously this only
+    // checked installed and would suggest "install" even when the API path
+    // would have worked.
+    const reach = isReachable(e.id, env);
+    const role = e.isSelf ? 'self    ' : (reach.any ? 'ready   ' : 'install ');
+    lines.push(`  ${e.id.padEnd(9)} ${role}-- ${e.name} (${e.invoke}) -- ${e.note}`);
+  }
+  const header = self
+    ? `Detected caller: ${self}. Roster (ready = installed + non-self):`
+    : `Caller unknown -- full roster:`;
+  return header + '\n' + lines.join('\n');
+}

package/src/caps.js

@@ -0,0 +1,37 @@
+// --- Storage caps (audit S1) ---
+// Prevents a single rogue call from bloating knowledge files to MB-scale
+// which would poison every future session-start read. Truncation uses a
+// visible marker so callers (and users inspecting memory) can tell data
+// was cut.
+//
+// Truncation is codepoint-aware: slicing by UTF-16 code units would cut
+// a surrogate pair mid-char and produce a dangling surrogate. We iterate
+// by codepoint via `Array.from` (equivalent to [...s]) to stay correct
+// on emoji, CJK, and combining sequences.
+
+export const CAP_CONTENT = 4096;
+export const CAP_WHY     = 1024;
+export const CAP_HOW     = 1024;
+export const CAP_SUMMARY = 120;
+
+const MARKER = '…[truncated]';
+
+function cap(s, limit) {
+  if (typeof s !== 'string' || !s) return '';
+  if (s.length <= limit) return s;
+  // s.length is in UTF-16 code units -- codepoint count is <= that. If the
+  // codepoint count is under the limit, return unchanged (no slice needed).
+  const codepoints = Array.from(s);
+  if (codepoints.length <= limit) return s;
+  const keep = Math.max(0, limit - MARKER.length);
+  return codepoints.slice(0, keep).join('') + MARKER;
+}
+
+export function applyCaps({ content, summary, why, how_to_apply } = {}) {
+  return {
+    content:      cap(content, CAP_CONTENT),
+    summary:      cap(summary, CAP_SUMMARY),
+    why:          cap(why, CAP_WHY),
+    how_to_apply: cap(how_to_apply, CAP_HOW),
+  };
+}

package/src/cold-scan-runner.mjs

@@ -0,0 +1,37 @@
+#!/usr/bin/env node
+// IJFW v1.3.0 Alpha -- A3 cold-scan runner.
+//
+// Tiny CLI adapter so the installer + hooks can spawn the detector as a
+// detached child. Reads --project-root, runs detect() + writeProjectType(),
+// exits 0 on completion. Any throw is swallowed so a broken scan never
+// surfaces a non-zero exit to the parent installer / hook.
+//
+// Usage:
+//   node cold-scan-runner.mjs --project-root <path> [--no-c9] [--max-files N]
+
+import { detect, writeProjectType } from './project-type-detector.js';
+
+const argv = process.argv.slice(2);
+const opts = { projectRoot: null, c9Available: true, maxFiles: null };
+for (let i = 0; i < argv.length; i++) {
+  const a = argv[i];
+  if (a === '--project-root') opts.projectRoot = argv[++i];
+  else if (a === '--no-c9') opts.c9Available = false;
+  else if (a === '--max-files') opts.maxFiles = Number(argv[++i]);
+}
+
+if (!opts.projectRoot) process.exit(0);
+
+try {
+  const result = detect(opts.projectRoot, {
+    c9Available: opts.c9Available,
+    maxFiles: opts.maxFiles || undefined,
+    sessionId: process.env.IJFW_SESSION_ID || null,
+  });
+  writeProjectType(opts.projectRoot, result);
+  process.exit(0);
+} catch {
+  // Cold scan is best-effort. The hoist treats a missing project.type as
+  // "silent skip", so failing here only delays detection to the next session.
+  process.exit(0);
+}