shraga 0.1.110 → 0.1.112

package/dist/client/index.html

@@ -13,7 +13,7 @@
     <link rel="preconnect" href="https://fonts.googleapis.com" />
     <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin />
     <link href="https://fonts.googleapis.com/css2?family=Inter:wght@400;500;600&display=swap" rel="stylesheet" />
-    <script type="module" crossorigin src="/assets/index-BaZu5Ojo.js"></script>
+    <script type="module" crossorigin src="/assets/index-Dc1ljSt3.js"></script>
     <link rel="stylesheet" crossorigin href="/assets/index-DIMte_k6.css">
   </head>
   <body>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shraga",
-  "version": "0.1.110",
+  "version": "0.1.112",
   "description": "The teammate you delegate coding to — a self-hostable, multi-user AI coding agent web UI (Claude Code, with a pluggable engine seam).",
   "type": "module",
   "main": "./src/index.ts",
@@ -55,7 +55,7 @@
     "prepublishOnly": "bun run guard:publish && bun run build"
   },
   "dependencies": {
-    "@anthropic-ai/claude-agent-sdk": "^0.2.141",
+    "@anthropic-ai/claude-agent-sdk": "^0.3.272",
     "@livx.cc/mcp-firebase": "^0.1.14",
     "@radix-ui/react-accordion": "^1.2.2",
     "@radix-ui/react-dialog": "^1.1.4",

package/src/mcp-stdio-bridge.ts

@@ -4,6 +4,12 @@
 //      MCP_EXTRA_HEADERS — optional JSON object of extra headers sent with every request,
 //      for servers that need a second credential beyond the bearer token (e.g. an
 //      upstream app behind a proxy that gates its own admin ops on its own header).
+//      MCP_BRIDGE_TIMEOUT_MS — per-request bound for protocol calls (initialize, tools/list…), default 60s.
+//      MCP_BRIDGE_TOOL_TIMEOUT_MS — bound for tools/call, default 30min (a sync post_chat turn has no
+//      server-side wall clock). Without a bound, a frozen server hung the client forever on "connecting…".
+const envMs = (v: string | undefined, fallback: number) => (Number(v) > 0 ? Number(v) : fallback);
+const REQUEST_TIMEOUT_MS = envMs(process.env.MCP_BRIDGE_TIMEOUT_MS, 60_000);
+const TOOL_TIMEOUT_MS = envMs(process.env.MCP_BRIDGE_TOOL_TIMEOUT_MS, 30 * 60_000);
 const baseUrl = (process.env.SHRAGA_URL || process.env.MCP_URL || process.env.UNCLAW_URL || 'http://localhost:3033').replace(/\/$/, '');
 const mcpPath = process.env.SHRAGA_MCP_PATH || process.env.MCP_PATH || '/mcp';
 const apiKey = process.env.SHRAGA_API_KEY || process.env.MCP_API_KEY || process.env.UNCLAW_API_KEY;
@@ -33,11 +39,23 @@ async function sendMessage(message: any): Promise<void> {
   if (sessionId) headers['mcp-session-id'] = sessionId;
   Object.assign(headers, extraHeaders);
 
-  const res = await fetch(`${baseUrl}${mcpPath}`, {
-    method: 'POST',
-    headers,
-    body: JSON.stringify(message),
-  });
+  const limit = message?.method === 'tools/call' ? TOOL_TIMEOUT_MS : REQUEST_TIMEOUT_MS;
+  // The signal also bounds the body read below, not just the headers.
+  const signal = AbortSignal.timeout(limit);
+  let res: Response;
+  let text: string;
+  try {
+    res = await fetch(`${baseUrl}${mcpPath}`, {
+      method: 'POST',
+      headers,
+      body: JSON.stringify(message),
+      signal,
+    });
+    text = res.status === 204 ? '' : await res.text();
+  } catch (e: any) {
+    if (signal.aborted) throw new Error(`no response from ${baseUrl} for ${message?.method ?? 'message'} within ${limit}ms`);
+    throw e;
+  }
 
   // Capture session ID from server on initialize
   const newSession = res.headers.get('mcp-session-id');
@@ -49,7 +67,6 @@ async function sendMessage(message: any): Promise<void> {
 
   if (contentType.includes('text/event-stream')) {
     // SSE: parse and forward each data line
-    const text = await res.text();
     for (const line of text.split('\n')) {
       if (line.startsWith('data: ')) {
         const data = line.slice(6).trim();
@@ -58,9 +75,8 @@ async function sendMessage(message: any): Promise<void> {
         }
       }
     }
-  } else {
-    const body = await res.text();
-    if (body) process.stdout.write(body + '\n');
+  } else if (text) {
+    process.stdout.write(text + '\n');
   }
 }
 

package/src/server/claude.ts

@@ -3,7 +3,7 @@ import { summarizeText } from './summarize.ts';
 import { dataSync } from './data-sync.ts';
 import type { McpConfig } from './mcp.ts';
 import type { ClaudeAccountRef } from './claude-account.ts';
-import { loadConversation, saveConversation, appendMessage, getSession, setSessionDirectives, addTriggeredSkills, upsertSession, type ConvMessage, type ConvBlock } from './sessions.ts';
+import { loadConversation, saveConversation, appendMessage, getSession, setSessionDirectives, addTriggeredSkills, upsertSession, setClaudeResume, type ConvMessage, type ConvBlock } from './sessions.ts';
 import { createTurnAccumulator, type TurnStreamHooks } from './turn-stream.ts';
 import {
   resolveDefaultSkillsContent,
@@ -324,7 +324,10 @@ export async function* streamChat(opts: {
   const stickyNames = opts.sessionId ? getSession(opts.sessionId)?.triggeredSkills ?? [] : [];
   const newTriggerNames = discoveryEnabled ? matchTriggeredSkillNames(effectivePrompt, opts.context) : [];
   const triggeredNames = [...new Set([...stickyNames, ...newTriggerNames])];
-  const triggeredSkills = skillInjectionBlocks(triggeredNames);
+  // Per-name blocks so an engine that resumes across turns can send only newly triggered ones. Joined
+  // exactly as skillInjectionBlocks(triggeredNames) joins them, so contextBlock is byte-identical.
+  const triggeredSkillBlocks = triggeredNames.map((n) => [n, skillInjectionBlocks([n])] as const).filter(([, b]) => b);
+  const triggeredSkills = triggeredSkillBlocks.map(([, b]) => b).join('\n');
 
   // Per-skill turn budget. Resolved HERE, once every invoked skill is known (the slash command and
   // the triggered/sticky set), and GAP-FILLING only: an inline `[turns:N]` or a session-pinned
@@ -347,6 +350,11 @@ export async function* streamChat(opts: {
   const teamRoster = contacts.formatRoster();
   const userContextBlock = getUserContextBlock(contact);
   const contextBlock = [userBlock, userContextBlock, teamRoster, defaultSkills, triggeredSkills, skillIndex, mcpSkills, workspaceTree].filter(Boolean).join('\n');
+  const contextSections: Record<string, string> = Object.fromEntries(Object.entries({
+    user: userBlock, userContext: userContextBlock, roster: teamRoster, defaultSkills,
+    ...Object.fromEntries(triggeredSkillBlocks.map(([n, b]) => [`skill:${n}`, b])),
+    skillIndex, mcpSkills, workspace: workspaceTree,
+  }).filter(([, v]) => v));
 
   // Load conversation for the engine
   const sessionId = opts.sessionId ?? crypto.randomUUID();
@@ -388,11 +396,16 @@ export async function* streamChat(opts: {
     return;
   }
   console.log(`[stream] engine=${engine.name} user=${opts.uid} session=${sessionId}`);
+  // Another engine's turn never reaches the claude-code transcript, so a stored SDK-resume mapping is
+  // stale from here on — mark it; the claude-code engine then falls back to a fresh query (engine-switch).
+  const resumeState = getSession(sessionId)?.claudeResume;
+  if (engine.name !== 'claude-code' && resumeState && !resumeState.interruptedBy) setClaudeResume(sessionId, undefined, { interruptedBy: engine.name });
 
   yield* engine.stream({
     prompt: turnPrompt,
     conversation,
     contextBlock,
+    contextSections,
     attachments: opts.attachments,
     images: opts.images,
     sessionId,

package/src/server/data-sync.ts

@@ -213,30 +213,27 @@ export class DataSync {
     } catch (err) {
       console.error(`${TAG} Boot sync FAILED — serving stale data until the next pull:`, (err as Error).message);
     }
-    // Defer heavy sync I/O (reads all tracked files + execSync) to avoid blocking
-    // WS connections and page loads during startup.
+    // Defer the post-boot scans (both async, but they still read/spawn a lot) past startup
+    // traffic — WS connections and page loads.
     setTimeout(() => {
       this.scanForConflictMarkers()
         .catch(err => console.warn(`${TAG} Post-init conflict scan failed:`, (err as Error).message))
-        // execSync inside the audit blocks too — keep it off the scan's tick so the two
-        // never add up into one long freeze.
-        .then(() => new Promise<void>(r => setImmediate(r)))
         .then(() => this.runIntegrityAudit())
         .catch(err => console.warn(`${TAG} Post-init integrity audit failed:`, (err as Error).message));
     }, 60_000);
   }
 
-  /** Compare HEAD against HEAD~1 to catch regressions. Notifies owner — never auto-reverts. */
-  private runIntegrityAudit(): void {
+  /** Compare HEAD against HEAD~1 to catch regressions. Notifies owner — never auto-reverts.
+   *  Must stay async: the old execSync-per-file audit froze the event loop ~5 min on prod. */
+  private async runIntegrityAudit(): Promise<void> {
     try {
-      const { audit } = require('./integrity-audit.ts');
+      const { audit } = await import('./integrity-audit.ts');
       // Churn paths are exempt for the same reason the shrink guard exempts them: a per-run worker
        // log is written by one leg, rewritten by the next, and truncated whenever a run is killed
       // mid-write. "invalid-json" on one of those is the normal end of an interrupted run, not
       // corruption of shared data — and since the file stays in HEAD, the audit re-reported it on
       // every sync. The audit exists to catch contacts.json being gutted.
-      const issues = (audit('HEAD~1') as { kind: string; file: string; detail: string }[])
-        .filter(i => !isChurnPath(i.file));
+      const issues = (await audit('HEAD~1', DATA_DIR)).filter(i => !isChurnPath(i.file));
       if (issues.length) {
         console.warn(`${TAG} ⚠️ DATA INTEGRITY: ${issues.length} issue(s) detected after sync:`);
         for (const { kind, file, detail } of issues) {

package/src/server/directives.ts

@@ -4,6 +4,8 @@ export interface Directives {
   thinking?: 'adaptive' | 'enabled' | 'disabled';
   effort?: 'low' | 'medium' | 'high' | 'max';
   engine?: string;
+  /** claude-code SDK session resume for this conversation (overrides agent-config `sdkResume`). */
+  resume?: boolean;
 }
 
 export interface ParsedPrompt {
@@ -28,7 +30,7 @@ import { MODEL_ALIASES } from './model-aliases.ts';
 
 const DIRECTIVE_RE = /^\s*\[([^\]]*)\]\s*([\s\S]*)/;
 
-const DIRECTIVE_KEYS = ['model', 'turns', 'thinking', 'think', 'effort', 'engine'];
+const DIRECTIVE_KEYS = ['model', 'turns', 'thinking', 'think', 'effort', 'engine', 'resume'];
 
 /** MODEL_ALIASES only covers the bare Anthropic shorthands. A `provider/model` id
  *  (`cursor/composer-2.5`, `openai/gpt-5.6`) is already concrete — gating it on the alias table
@@ -179,6 +181,11 @@ function applyDirective(d: Directives, key: string, val: string): string | undef
     case 'engine':
       d.engine = val;
       break;
+    case 'resume':
+      if (['on', 'true', '1'].includes(val)) d.resume = true;
+      else if (['off', 'false', '0'].includes(val)) d.resume = false;
+      else console.warn(`[directives] Invalid resume value: "${val}"`);
+      break;
     default:
       console.warn(`[directives] Unknown directive key: "${key}"`);
   }

package/src/server/engine/claude-code.ts

@@ -8,7 +8,12 @@ import { listSkills } from '../skills.ts';
 import { loadAgents } from '../agents.ts';
 import { registerProactiveMessage } from '../slack/sessions.ts';
 import { registerPoll } from '../polls.ts';
-import { getSession, setSessionModel, getSessionModel, type ConvMessage } from '../sessions.ts';
+import { getSession, setSessionModel, getSessionModel, setClaudeResume, type ConvMessage } from '../sessions.ts';
+import {
+  isResumeEnabled, decideClaudeTurn, claudeConfigDir, findClaudeTranscript, shortHash, sectionHashes, speakerKey,
+  sectionsAfterSubmit, isResumeFailure, conversationSummaryKey, buildContextDelta, buildResumePrompt, renderConvMessage,
+  type TurnPath, type ClaudeResumeState,
+} from './claude-resume.ts';
 import { DEFAULT_MODEL } from '../directives.ts';
 import { resolveModelSwitch, MODEL_ALIASES } from '../model-aliases.ts';
 import type { WsEvent, AskQuestion, QuestionAnswers, QuestionHandler } from '../claude.ts';
@@ -95,15 +100,8 @@ function buildHistoryPrompt(conv: ConvMessage[], contextBlock: string, userPromp
   const parts: string[] = [];
   if (summary) parts.push(`<conversation_summary>\n${summary}\n</conversation_summary>`);
   for (const m of recent) {
-    const role = m.role === 'user' ? 'User' : 'Assistant';
-    const texts = m.blocks
-      .filter((b) => b.type === 'text' || b.type === 'context')
-      .map((b) => {
-        if (b.type === 'context') return `[${(b as any).label}]: ${(b as any).text}`;
-        return (b as { type: 'text'; text: string }).text;
-      })
-      .filter(Boolean);
-    if (texts.length) parts.push(`${role}: ${texts.join('\n')}`);
+    const line = renderConvMessage(m);
+    if (line) parts.push(line);
   }
 
   if (parts.length) {
@@ -117,10 +115,11 @@ function buildHistoryPrompt(conv: ConvMessage[], contextBlock: string, userPromp
  * Log prompt-cache effectiveness from the SDK result `usage`. The hit rate is
  * cache_read / (cache_read + cache_creation + uncached input) — a low rate over
  * many turns points to a silent prefix invalidator or sessions spread past the
- * 5-min cache TTL. Note: cross-turn history is re-sent uncached (single-shot
- * prompt per query, no SDK resume) — so hit rate tracks tool density per turn.
+ * 5-min cache TTL. `path` says how the prompt was built — `fresh` (history re-sent in one message),
+ * `resume` (SDK session resumed, only the new message sent) or `fallback:<reason>` (resume enabled but a
+ * fresh query ran) — so journal lines can be A/B-compared per path.
  */
-function logCacheUsage(usage: any, model: string): void {
+function logCacheUsage(usage: any, model: string, path: TurnPath): void {
   if (!usage) return;
   const read = usage.cache_read_input_tokens ?? 0;
   const created = usage.cache_creation_input_tokens ?? 0;
@@ -128,9 +127,47 @@ function logCacheUsage(usage: any, model: string): void {
   const totalIn = read + created + fresh;
   if (totalIn === 0) return;
   const hitRate = ((read / totalIn) * 100).toFixed(1);
-  console.log(`[claude] Cache: hit=${hitRate}% read=${read} write=${created} uncached=${fresh} out=${usage.output_tokens ?? 0} model=${model}`);
+  console.log(`[claude] Cache: hit=${hitRate}% read=${read} write=${created} uncached=${fresh} out=${usage.output_tokens ?? 0} model=${model} path=${path}`);
 }
 
+/** How one query attempt is built. `persist` is set when resume is enabled: after a query that produced
+ *  output, the CC session id + these facts are saved so the next turn can resume. */
+interface RunPlan {
+  path: TurnPath;
+  prompt: string;
+  accountDir: string | null;
+  resumeId?: string;
+  persist?: Omit<ClaudeResumeState, 'claudeSessionId' | 'model' | 'interruptedBy'>;
+  /** Resume only: section hashes to store once the prompt is submitted (see sectionsAfterSubmit). */
+  submitSections?: Record<string, string>;
+}
+
+/** Exit promises of CLI processes still running, per shraga session. A turn that took over a session (external
+ *  steer) can start while the aborted run's CLI is still exiting; resuming then would put two writers on one
+ *  transcript. */
+const liveCli = new Map<string, Set<Promise<void>>>();
+
+function trackCliExit(sessionId: string | undefined, child: { once: (event: string, fn: () => void) => unknown }): void {
+  if (!sessionId) return;
+  const set = liveCli.get(sessionId) ?? new Set();
+  liveCli.set(sessionId, set);
+  const exited = new Promise<void>((resolve) => { child.once('exit', resolve); child.once('error', resolve); });
+  set.add(exited);
+  void exited.then(() => { set.delete(exited); if (!set.size && liveCli.get(sessionId) === set) liveCli.delete(sessionId); });
+}
+
+/** true once every CLI process of the session has exited, false if one is still alive after `ms`. */
+async function cliExited(sessionId: string, ms: number): Promise<boolean> {
+  const set = liveCli.get(sessionId);
+  if (!set?.size) return true;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const timeout = new Promise<false>((r) => { timer = setTimeout(() => r(false), ms); });
+  try { return await Promise.race([Promise.all(set).then(() => true), timeout]); } finally { clearTimeout(timer); }
+}
+
+/** Events that prove a resumed query actually runs; until one arrives the attempt can still be retried fresh unseen. */
+const LIVE_EVENTS = new Set<WsEvent['type']>(['text_delta', 'thinking_delta', 'tool_use', 'tool_use_input', 'tool_result', 'tool_result_image', 'done']);
+
 /** SDK spawn hook: same call the SDK would make, plus `detached` (own process group). See the
  *  call site for why. Shape mirrors the SDK's own spawnLocalProcess return. */
 function spawnDetached(cfg: { command: string; args: string[]; cwd?: string; env: Record<string, string | undefined>; signal?: AbortSignal }) {
@@ -221,11 +258,75 @@ export class ClaudeCodeEngine implements AgentEngine {
     ];
   }
 
+  /** How long a resume-enabled turn waits for an earlier CLI process on the session to exit before going fresh. */
+  static cliExitWaitMs = 5_000;
+
   async *stream(opts: EngineStreamOpts): AsyncGenerator<WsEvent> {
+    let cliAlive = false;
+    if (opts.sessionId && isResumeEnabled(opts.directives, opts.config) && !(await cliExited(opts.sessionId, ClaudeCodeEngine.cliExitWaitMs))) {
+      cliAlive = true;
+      console.warn(`[claude] An earlier CLI process on session=${opts.sessionId} is still running after ${ClaudeCodeEngine.cliExitWaitMs}ms — not resuming its transcript`);
+    }
+    const plan = this.plan(opts, cliAlive);
+    if (plan.path !== 'resume') { yield* this.run(opts, plan); return; }
+    // Hold non-output events (init's model_resolved / switch notice) until the resumed query proves it
+    // runs, so a failed resume can be retried fresh with nothing duplicated on the user's side.
+    const attempt = this.run(opts, plan);
+    const held: WsEvent[] = [];
+    let live = false;
+    let r: IteratorResult<WsEvent, 'resume-failed' | void>;
+    try {
+      while (!(r = await attempt.next()).done) {
+        if (!live && !LIVE_EVENTS.has(r.value.type)) { held.push(r.value); continue; }
+        if (!live) { live = true; yield* held; }
+        yield r.value;
+      }
+    } finally {
+      await attempt.return(undefined);
+    }
+    if (r.value !== 'resume-failed') { if (!live) yield* held; return; }
+    console.warn(`[claude] Resume of ${plan.resumeId} failed before any output — retrying fresh in the same turn (session=${opts.sessionId})`);
+    setClaudeResume(opts.sessionId, undefined);
+    yield* this.run(opts, this.freshPlan(opts, plan.accountDir, 'fallback:resume-failed', plan.persist));
+  }
+
+  private freshPlan(opts: EngineStreamOpts, accountDir: string | null, path: TurnPath, persist?: RunPlan['persist']): RunPlan {
+    return {
+      path, accountDir,
+      prompt: buildHistoryPrompt(opts.conversation, opts.contextBlock, opts.prompt),
+      ...(persist ? { persist: { ...persist, sections: sectionHashes(opts.contextSections ?? { context: opts.contextBlock }), startedAt: Date.now() } } : {}),
+    };
+  }
+
+  /** Resume vs fresh, and why — see claude-resume.ts. */
+  private plan(opts: EngineStreamOpts, cliAlive: boolean): RunPlan {
+    const accountDir = claudeAccountDir(opts.userEmail);
+    if (!isResumeEnabled(opts.directives, opts.config)) return this.freshPlan(opts, accountDir, 'fresh');
+    const configDir = claudeConfigDir(accountDir);
+    const configDirHash = shortHash(configDir);
+    const state = opts.sessionId ? getSession(opts.sessionId)?.claudeResume : undefined;
+    const speaker = speakerKey(opts.uid, opts.userEmail);
+    const persist = { configDirHash, speaker, markId: opts.conversation.at(-1)?.id, summaryKey: conversationSummaryKey(opts.conversation), sections: {}, startedAt: Date.now() };
+    const decision = decideClaudeTurn({
+      enabled: true, state, conversation: opts.conversation, configDirHash, speaker, cliAlive, conversationReset: opts.conversationReset,
+      hasTranscript: (id) => !!findClaudeTranscript(id, configDir),
+    });
+    if (decision.path !== 'resume' || !state) return this.freshPlan(opts, accountDir, decision.path, persist);
+    const sections = opts.contextSections ?? { context: opts.contextBlock };
+    const hashes = sectionHashes(sections);
+    return {
+      path: 'resume', accountDir, resumeId: state.claudeSessionId,
+      prompt: buildResumePrompt(opts.prompt, decision.unseen, buildContextDelta(state.sections, sections)),
+      persist: { ...persist, sections: hashes, startedAt: state.startedAt },
+      submitSections: sectionsAfterSubmit(state.sections, hashes),
+    };
+  }
+
+  private async *run(opts: EngineStreamOpts, plan: RunPlan): AsyncGenerator<WsEvent, 'resume-failed' | void> {
     const { config, directives } = opts;
     const cwd = APP_ROOT;
 
-    const fullPrompt = buildHistoryPrompt(opts.conversation, opts.contextBlock, opts.prompt);
+    const fullPrompt = plan.prompt;
     const permMode = opts.onPermissionRequest ? 'default' : (config.permissionMode ?? 'acceptEdits');
 
     const sdkEnv: Record<string, string> = {};
@@ -247,8 +348,11 @@ export class ClaudeCodeEngine implements AgentEngine {
     const setIfBlank = (key: string, value: string) => { if (!sdkEnv[key]?.trim()) sdkEnv[key] = value; };
     setIfBlank('BASH_DEFAULT_TIMEOUT_MS', process.env.AGENT_SHELL_TIMEOUT_MS?.trim() || '60000');
     setIfBlank('BASH_MAX_TIMEOUT_MS', process.env.AGENT_SHELL_MAX_TIMEOUT_MS?.trim() || '600000');
+    // The subscription login's claude.ai connectors (Gmail/Calendar/… and this agent's own MCP) load
+    // regardless of settingSources; headless they are auth stubs or self-recursion. Our MCPs come from mcp-config.
+    setIfBlank('ENABLE_CLAUDEAI_MCP_SERVERS', 'false');
     // Per-user subscription (workspace/users/<contactId>/.claude): run on that login, never the box's credentials.
-    const accountDir = claudeAccountDir(opts.userEmail);
+    const accountDir = plan.accountDir;
     if (accountDir) applyClaudeAccount(sdkEnv, accountDir);
     // Which login this run is on (email/plan, never a token) — read lazily from the login's local
     // files, only once init proves the run is on a subscription login (see init below).
@@ -256,6 +360,10 @@ export class ClaudeCodeEngine implements AgentEngine {
     const accountRef = () => (accountRefP ??= claudeAccountRef(accountDir));
     let runAccount: ClaudeAccountRef | undefined;
     let sawInit = false;
+    // Did THIS attempt produce model output? Gates both the resume-failure retry and saving the session id
+    // (a resume that died on "No conversation found" can report a session id it never wrote a turn to).
+    let sawOutput = false;
+    let initModel: string | undefined;
     sdkEnv.INTERNAL_API_TOKEN = signInternalToken(opts.uid, opts.userEmail || 'unknown');
 
     const baseAllowed = config.allowedTools ?? DEFAULT_ALLOWED_TOOLS;
@@ -267,6 +375,10 @@ export class ClaudeCodeEngine implements AgentEngine {
       env: sdkEnv,
       allowedTools,
       cwd,
+      // Omitted = ALL sources, so the host's ~/.claude (CLAUDE.md, MCP instructions, hooks) rode into every
+      // query — ~24k tokens re-written to cache per fresh turn on a dev box. Keep 'project': the deployment
+      // ships its own .claude/skills (e.g. shraga-circles' video-ad-pipeline) that the agent relies on.
+      settingSources: ['project'],
       permissionMode: permMode === 'bypassPermissions' ? 'acceptEdits' : permMode,
       maxTurns,
       includePartialMessages: true,
@@ -350,13 +462,18 @@ export class ClaudeCodeEngine implements AgentEngine {
     const addonSuffix = getPromptSuffix(opts.turnHints);
     options['systemPrompt'] = `${IMMUTABLE_SYSTEM_PROMPT}\n\n${userPrompt}${addonSuffix ? `\n\n${addonSuffix}` : ''}`;
     if (opts.abortController) options['abortController'] = opts.abortController;
+    if (plan.resumeId) options['resume'] = plan.resumeId;
     // Spawn the CLI in its OWN process group. The service manager signals the whole JOB on restart
     // (`launchctl kickstart -k`, `systemctl restart`), so an inherited process group means the child
     // dies instantly with SIGTERM — surfacing mid-reply as `exited with code 143` and making the
     // server's 90s drain (gracefulShutdown) protect nothing: it only ever waited for a turn that was
     // already dead. Detached, the signal reaches the server alone and the drain can finish the turn.
     // Teardown is unaffected: the SDK still kills the child on abort/close and on process exit.
-    options['spawnClaudeCodeProcess'] = spawnDetached;
+    options['spawnClaudeCodeProcess'] = (cfg: Parameters<typeof spawnDetached>[0]) => {
+      const child = spawnDetached(cfg);
+      trackCliExit(opts.sessionId, child);
+      return child;
+    };
 
     // Passed as a FILE, never as `options.mcpServers` — the SDK would put the whole config (every MCP
     // server's credentials) on the CLI's argv, where `ps` / `/proc` / journald expose it. See
@@ -384,6 +501,8 @@ export class ClaudeCodeEngine implements AgentEngine {
         : fullPrompt;
 
     const q = query({ prompt, options: options as any });
+    // The CLI writes this prompt to the transcript before any output: from here a cancel can't un-deliver it.
+    if (plan.submitSections && opts.sessionId) setClaudeResume(opts.sessionId, undefined, { sections: plan.submitSections });
 
     let lastSessionId = '';
     let messageCount = 0;
@@ -442,6 +561,7 @@ export class ClaudeCodeEngine implements AgentEngine {
           // default only counts when the SDK says it resolved a login, not an API key.
           if ((authSource ?? (accountDir ? 'subscription' : undefined)) === 'subscription') runAccount = await accountRef();
           if (m.model) {
+            initModel = m.model;
             console.log(`[claude] Init model=${m.model}${m.model !== options['model'] ? ` (requested ${options['model']})` : ''}`);
             // If the user explicitly asked to switch models via a [directive], announce the change
             // inline so the response confirms the switch took effect.
@@ -487,7 +607,7 @@ export class ClaudeCodeEngine implements AgentEngine {
           const raw = m.subtype ?? 'unknown';
           const sub = raw === 'error_max_turns' || (raw === 'end_turn' && sdkTurns >= maxTurns) ? 'max_turns_reached' : raw;
           console.log(`[claude] Result: subtype=${m.subtype}→${sub} session=${lastSessionId} turns=${sdkTurns}/${maxTurns} cost=$${m.total_cost_usd?.toFixed(4) ?? '?'} msgs=${messageCount} deltas=${textDeltaCount} (${elapsed()})`);
-          logCacheUsage(m.usage, activeModel);
+          logCacheUsage(m.usage, activeModel, plan.path);
           if (outstandingTasks.size > 0) {
             if (!waitingForBg) {
               waitingForBg = true; clearBgTimer();
@@ -507,6 +627,12 @@ export class ClaudeCodeEngine implements AgentEngine {
           // `error_max_turns` also sets is_error but is a benign stop reason we already model.
           if ((m.is_error || m.api_error_status) && sub !== 'max_turns_reached') {
             const detail = typeof m.result === 'string' && m.result ? m.result : `api_error_status=${m.api_error_status ?? '?'}`;
+            // The CLI's reason ("No conversation found with session ID …") rides in `errors`, not `result`.
+            const reasons = Array.isArray(m.errors) && m.errors.length ? m.errors.join('; ') : detail;
+            if (plan.resumeId && !sawOutput && isResumeFailure(reasons)) {
+              console.error(`[claude] Resume error result (subtype=${raw}) — ${reasons}`);
+              return 'resume-failed';
+            }
             // A usage/rate-limit failure is about ONE login's quota — name it, or a routed user's own
             // exhausted Pro plan reads as the shared agent subscription being out.
             const limitHit = m.api_error_status === 429 || /\b(usage|rate.?limit(ed)?|hit your limit)\b/i.test(detail);
@@ -525,10 +651,12 @@ export class ClaudeCodeEngine implements AgentEngine {
         if (m.type === 'stream_event') {
           const event = m.event;
           if (event?.type === 'content_block_delta' && event.delta?.type === 'thinking_delta') {
+            sawOutput = true;
             yield { type: 'thinking_delta', text: event.delta.thinking };
           }
           if (event?.type === 'content_block_delta' && event.delta?.type === 'text_delta') {
             textDeltaCount++;
+            sawOutput = true;
             yield { type: 'text_delta', text: event.delta.text };
           }
           if (event?.type === 'content_block_start' && event.content_block?.type === 'tool_use') {
@@ -550,6 +678,7 @@ export class ClaudeCodeEngine implements AgentEngine {
 
         if (m.type === 'assistant' && Array.isArray(m.message?.content)) {
           turnCount++;
+          sawOutput = true;
           for (const block of m.message.content) {
             if (block.type === 'tool_use') {
               pendingToolUses.set(block.id, { tool: block.name, input: block.input });
@@ -638,6 +767,7 @@ export class ClaudeCodeEngine implements AgentEngine {
         return;
       }
       console.error(`[claude] Error after ${messageCount} msgs (${elapsed()}):`, err.message || err);
+      if (plan.resumeId && !sawOutput && isResumeFailure(err.message || String(err))) return 'resume-failed';
       yield { type: 'error', message: err.message || String(err) };
       return;
     } finally {
@@ -645,6 +775,11 @@ export class ClaudeCodeEngine implements AgentEngine {
       // The CLI has read the file by now (it loads MCP config at startup); holding it any longer just
       // widens the window in which the credentials sit on disk.
       mcpConfigFile?.cleanup();
+      // Save the mapping once this attempt really ran a turn (incl. an aborted one — the transcript holds it).
+      if (plan.persist && opts.sessionId && lastSessionId && sawOutput) {
+        setClaudeResume(opts.sessionId, { ...plan.persist, claudeSessionId: lastSessionId, ...(initModel ? { model: initModel } : {}) });
+        if (plan.resumeId && plan.resumeId !== lastSessionId) console.warn(`[claude] Resume returned a new session id ${lastSessionId} (was ${plan.resumeId})`);
+      }
     }
 
     const inferredReason = turnCount >= maxTurns ? 'max_turns_reached' : 'end_turn';