@inixiative/agent-session 0.1.0 → 0.3.0

package/src/claude-code-session.ts

@@ -1,3 +1,13 @@
+import {
+  claudeRateLimitSnapshot,
+  claudeUsageSnapshot,
+  type LimitSnapshot,
+  mergeLimits,
+} from './limits';
+import { retainEvidence } from './retained-evidence';
+import { TRANSPORTS } from './transport';
+import { TurnState } from './turn-state';
+
 // ---------------------------------------------------------------------------
 // ClaudeCodeSession — long-lived Claude Code process with full event capture
 // ---------------------------------------------------------------------------
@@ -32,22 +42,26 @@
 // transport. Normal messages go through stdin.
 // ---------------------------------------------------------------------------
 
+import { parseClaudeUsage } from './claude-usage';
 import type {
   BeforeSendHook,
   HarnessSession,
+  NativeInterruptOutcome,
+  SessionArtifact,
   SessionEvent,
   SessionEventHandler,
   SessionResult,
-  SessionArtifact,
-} from "./harness-session";
+  SessionSendOptions,
+  SessionTokens,
+} from './harness-session';
 
 // Re-export types so existing import paths keep working
 export type {
+  SessionArtifact,
   SessionEvent,
   SessionEventKind,
   SessionResult,
-  SessionArtifact,
-} from "./harness-session";
+} from './harness-session';
 
 // ---------------------------------------------------------------------------
 // Configuration
@@ -66,7 +80,7 @@ export interface ClaudeCodeSessionConfig {
   /** Working directory for the session. */
   cwd?: string;
   /** Max agentic turns per message. Defaults to 25. */
-  maxTurns?: number;
+  maxTurns?: number | null;
   /** Permission mode. Defaults to "bypassPermissions". */
   permissionMode?: string;
   /** Default per-send timeout in ms. Defaults to 600000 (10 min). */
@@ -86,6 +100,19 @@ export interface ClaudeCodeSessionConfig {
    * Foundry thread that was previously mapped to this external ID.
    */
   externalSessionId?: string;
+  /**
+   * Environment merged over process.env (e.g. CLAUDE_CONFIG_DIR for a profile).
+   * ANTHROPIC_API_KEY and ANTHROPIC_AUTH_TOKEN are always removed: this
+   * transport runs on the CLI's subscription login.
+   */
+  env?: Record<string, string | undefined>;
+  /**
+   * Launch without callable tools, MCP servers, slash commands or user
+   * settings (`--safe-mode --tools "" --strict-mcp-config …`). For decisions.
+   */
+  textOnly?: boolean;
+  /** False adds `--no-session-persistence` (nothing written to history; cannot be resumed). Default true. */
+  persistSession?: boolean;
   /**
    * Override for the process spawner. Defaults to Bun.spawn. Tests inject a
    * fake subprocess that emulates the claude CLI's stream-json protocol.
@@ -104,6 +131,8 @@ export interface ClaudeCodeSessionConfig {
 // ---------------------------------------------------------------------------
 
 interface QueuedTurn {
+  onAdmission?: SessionSendOptions['onAdmission'];
+  evidence: TurnState;
   message: string;
   timeout: number;
   resolve: (result: SessionResult) => void;
@@ -123,24 +152,118 @@ export interface PipedSubprocess {
   kill(): void;
 }
 
+// ---------------------------------------------------------------------------
+// Public tool-result content contract (stream-json `user` tool_result blocks).
+//
+// A string content is the public output verbatim. An array keeps the text
+// blocks (joined with one newline, as before) and, separately, the exact
+// `tool_name` strings of `tool_reference` blocks (Anthropic tool search returns
+// discovered tools as references, not text). Every other block, and any
+// malformed text/reference block, is omitted explicitly: `toolOutputOmitted` is
+// set and `toolOutputOmittedTypes` lists known public type labels or
+// "unsupported". Nothing else from a block is copied, so private or unexpected
+// fields never enter the public event. Reference-only output is NOT a success
+// claim; the consuming guard judges ownership and ordering.
+// ---------------------------------------------------------------------------
+const KNOWN_NON_TEXT_RESULT_TYPES = new Set([
+  'image',
+  'audio',
+  'document',
+  'resource',
+  'resource_link',
+]);
+
+function publicToolResultContent(
+  content: unknown,
+): Pick<
+  SessionEvent,
+  'toolOutput' | 'toolReferences' | 'toolOutputOmitted' | 'toolOutputOmittedTypes'
+> {
+  if (typeof content === 'string') return { toolOutput: content };
+  if (content === undefined || content === null) return {};
+  const omittedTypes: string[] = [];
+  const omit = (type: unknown) => {
+    const label =
+      typeof type === 'string' && KNOWN_NON_TEXT_RESULT_TYPES.has(type) ? type : 'unsupported';
+    if (!omittedTypes.includes(label)) omittedTypes.push(label);
+  };
+  if (!Array.isArray(content)) {
+    omit(undefined);
+    return { toolOutputOmitted: true, toolOutputOmittedTypes: Object.freeze(omittedTypes) };
+  }
+  const texts: string[] = [],
+    references: string[] = [];
+  for (const block of content) {
+    const b =
+      block !== null && typeof block === 'object' && !Array.isArray(block)
+        ? (block as Record<string, unknown>)
+        : undefined;
+    if (b?.type === 'text' && typeof b.text === 'string') texts.push(b.text);
+    else if (
+      b?.type === 'tool_reference' &&
+      typeof b.tool_name === 'string' &&
+      b.tool_name.length > 0
+    )
+      references.push(b.tool_name);
+    else omit(b?.type);
+  }
+  return {
+    toolOutput: texts.join('\n'),
+    ...(references.length ? { toolReferences: Object.freeze([...references]) } : {}),
+    ...(omittedTypes.length
+      ? { toolOutputOmitted: true, toolOutputOmittedTypes: Object.freeze(omittedTypes) }
+      : {}),
+  };
+}
+
+/** Claude CLI flags for a tool-free session (the same launch Foundry uses for text-only auxiliaries). */
+export const CLAUDE_TEXT_ONLY_ARGS: readonly string[] = [
+  '--safe-mode',
+  '--tools',
+  '',
+  '--strict-mcp-config',
+  '--mcp-config',
+  '{"mcpServers":{}}',
+  '--disable-slash-commands',
+  '--no-chrome',
+];
+
 export class ClaudeCodeSession implements HarnessSession {
+  get transport() {
+    return TRANSPORTS['claude-cli'];
+  }
   // -- Config --
   private _bin: string;
   private _model: string;
   private _effort?: string;
   private _cwd: string;
-  private _maxTurns: number;
+  readonly admissionProtocol = 'prewrite-v1' as const;
+  readonly turnBudgetProtocol = 'optional-max-turns-v1' as const;
+  inspectAttempt(admissionId: string) {
+    return this._attempts.find((attempt) => attempt.admissionId === admissionId)?.snapshot();
+  }
+  private _maxTurns: number | null;
   private _permissionMode: string;
   private _defaultTimeout: number;
   private _baseContext?: string;
   private _forking = false;
-  private _spawn?: ClaudeCodeSessionConfig["spawn"];
+  private _awaitingForkIdentity = false;
+  private _spawn?: ClaudeCodeSessionConfig['spawn'];
+  private _env?: ClaudeCodeSessionConfig['env'];
+  private _textOnly: boolean;
+  private _persistSession: boolean;
+  private _limits?: LimitSnapshot;
+  private _controlSeq = 0;
+  private _control = new Map<
+    string,
+    { resolve(response: Record<string, unknown>): void; reject(error: Error): void }
+  >();
 
   // -- Process --
   // Bun.spawn's return type is a union; we always use stdin:"pipe"/stdout:"pipe"/stderr:"pipe"
   // so we know the concrete types at runtime.
   private _proc: PipedSubprocess | null = null;
-  private _stderr = "";
+  private _stderr = '';
 
   // -- Session state --
   /**
@@ -151,55 +274,92 @@ export class ClaudeCodeSession implements HarnessSession {
    */
   private _externalSessionId?: string;
   private _alive = false;
+  private _endEmitted = false;
   private _eventLog: SessionEvent[] = [];
   private _handlers: SessionEventHandler[] = [];
+  private _observerFailures = { synchronous: 0, asynchronous: 0 };
   private _beforeSendHooks: BeforeSendHook[] = [];
   private _turns = 0;
-  private _totalTokens = { input: 0, output: 0 };
+  private _totalTokens: SessionTokens = { input: 0, output: 0 };
   private _startedAt: number;
   /**
-   * Whether we've already seen a system/init event on the stream. If a second
-   * one arrives it signals a mid-session restart — Claude Code's auto-compact
-   * kills and resumes the session, which reproduces the init event. We use
-   * this to emit `session_compact` so the FlowOrchestrator can invalidate
-   * the Librarian's injection ledger.
+   * Native uuids of explicit compaction boundaries already emitted. Claude emits a
+   * `system/init` per admission on one binding, so a repeated init is configuration
+   * evidence, never proof of compaction or restart. Only the explicit
+   * `system/compact_boundary` envelope is a compaction, and a repeat is a duplicate
+   * only when it carries the same native uuid; text-equal boundaries without one
+   * are distinct compactions.
    */
-  private _sawInit = false;
+  private _seenBoundaries = new Set<string>();
 
   // -- Turn queue --
   private _queue: QueuedTurn[] = [];
+  private _attempts: TurnState[] = [];
+  private _seenTerminals = new Set<string>();
   private _inflight: QueuedTurn | null = null;
-  private _turnEvents: SessionEvent[] = [];
-  private _resultText = "";
   private _turnTimer: ReturnType<typeof setTimeout> | null = null;
 
   constructor(config?: ClaudeCodeSessionConfig) {
-    const bin = config?.bin ?? "claude";
-    if (!/^[a-zA-Z0-9_.\/\\-]+$/.test(bin)) {
+    const bin = config?.bin ?? 'claude';
+    if (!/^[a-zA-Z0-9_./\\-]+$/.test(bin)) {
       throw new Error(`Invalid claude CLI binary path: "${bin}"`);
     }
     this._bin = bin;
-    this._model = config?.model ?? "sonnet";
+    this._model = config?.model ?? 'sonnet';
     this._effort = config?.effort;
     this._cwd = config?.cwd ?? process.cwd();
-    this._maxTurns = config?.maxTurns ?? 25;
-    this._permissionMode = config?.permissionMode ?? "bypassPermissions";
+    // Undefined retains standalone legacy behavior; null explicitly omits the CLI cap.
+    if (
+      config?.maxTurns !== undefined &&
+      config.maxTurns !== null &&
+      (!Number.isSafeInteger(config.maxTurns) || config.maxTurns < 1)
+    ) {
+      throw new Error('maxTurns must be a positive safe integer or null (unbounded)');
+    }
+    this._maxTurns = config?.maxTurns === undefined ? 25 : config.maxTurns;
+    this._permissionMode = config?.permissionMode ?? 'bypassPermissions';
     this._defaultTimeout = config?.timeout ?? 600_000;
     this._baseContext = config?.baseContext;
     this._externalSessionId = config?.externalSessionId;
     this._spawn = config?.spawn;
+    this._env = config?.env;
+    this._textOnly = config?.textOnly ?? false;
+    this._persistSession = config?.persistSession ?? true;
     this._startedAt = Date.now();
   }
 
+  /** Latest account limits observed on this session (stream or poll). */
+  get limits(): LimitSnapshot | undefined {
+    return this._limits;
+  }
+
   // ---------------------------------------------------------------------------
   // Accessors
   // ---------------------------------------------------------------------------
 
-  get alive(): boolean { return this._alive; }
-  get externalSessionId(): string | undefined { return this._externalSessionId; }
-  get events(): readonly SessionEvent[] { return this._eventLog; }
-  get turns(): number { return this._turns; }
-  get totalTokens(): Readonly<{ input: number; output: number }> {
+  get accounting() {
+    return 'observed-only' as const;
+  }
+  get attempts() {
+    return this._attempts.map((a) => a.snapshot());
+  }
+  get diagnostics() {
+    return Object.freeze({ observerFailures: Object.freeze({ ...this._observerFailures }) });
+  }
+
+  get alive(): boolean {
+    return this._alive;
+  }
+  get externalSessionId(): string | undefined {
+    return this._externalSessionId;
+  }
+  get events(): readonly SessionEvent[] {
+    return Object.freeze([...this._eventLog]);
+  }
+  get turns(): number {
+    return this._turns;
+  }
+  get totalTokens(): Readonly<SessionTokens> {
     return { ...this._totalTokens };
   }
 
@@ -234,7 +394,7 @@ export class ClaudeCodeSession implements HarnessSession {
    */
   async push(payload: { kind: string; text: string }): Promise<void> {
     this._emit({
-      kind: "error",
+      kind: 'error',
       timestamp: Date.now(),
       text: `push_ignored: kind=${payload.kind} — stream-json stdin has no OOB channel`,
       raw: payload,
@@ -246,67 +406,89 @@ export class ClaudeCodeSession implements HarnessSession {
   // ---------------------------------------------------------------------------
 
   async start(): Promise<void> {
-    if (this._proc) throw new Error("Session already started");
+    if (this._attempts.some((a) => a.dispatch === 'attempted' && a.nativeOutcome === 'unknown'))
+      throw new Error('Native outcome unresolved; automatic resume is blocked');
+    if (this._proc) throw new Error('Session already started');
 
     const args = this._buildSpawnArgs();
 
     // Strip API key env vars — CLI uses subscription auth
     const env: Record<string, string | undefined> = {
       ...process.env,
-      DISABLE_AUTOUPDATER: "1",
+      ...this._env,
+      DISABLE_AUTOUPDATER: '1',
     };
     delete env.ANTHROPIC_API_KEY;
     delete env.ANTHROPIC_AUTH_TOKEN;
+    for (const key of Object.keys(env)) if (env[key] === undefined) delete env[key];
 
     if (this._spawn) {
       this._proc = this._spawn([this._bin, ...args], { cwd: this._cwd, env });
     } else {
       this._proc = Bun.spawn([this._bin, ...args], {
         cwd: this._cwd,
-        stdin: "pipe",
-        stdout: "pipe",
-        stderr: "pipe",
+        stdin: 'pipe',
+        stdout: 'pipe',
+        stderr: 'pipe',
         env,
       }) as unknown as PipedSubprocess;
     }
 
     this._alive = true;
-    this._emit({ kind: "session_start", timestamp: Date.now() });
+    this._endEmitted = false;
+    this._emit({ kind: 'session_start', timestamp: Date.now() });
 
     // Background readers — run for session lifetime (don't await)
-    this._readStdout();
+    const proc = this._proc;
+    const stdoutDone = this._readStdout(proc);
     this._readStderr();
 
     // Monitor process exit for cleanup
-    this._proc.exited.then((code) => {
-      if (!this._alive) return;
+    proc.exited.then(async (code) => {
+      if (this._proc !== proc || !this._alive) return;
       this._alive = false;
+      await stdoutDone; // Drain buffered terminal evidence before interpreting process exit.
       const errMsg = this._stderr.trim()
         ? `Process exited (code ${code}): ${this._stderr.trim().slice(0, 500)}`
         : `Process exited with code ${code}`;
       this._rejectInflight(new Error(errMsg));
-      this._rejectQueue(new Error("Session ended"));
-      this._emit({ kind: "session_end", timestamp: Date.now() });
+      this._rejectQueue(new Error('Session ended'));
+      this._rejectControl(new Error('Session ended'));
+      this._emit({ kind: 'session_end', timestamp: Date.now(), transportOutcome: 'failed' });
     });
   }
 
+  private _rejectControl(error: Error): void {
+    for (const pending of this._control.values()) pending.reject(error);
+    this._control.clear();
+  }
+
   // ---------------------------------------------------------------------------
   // send() — write message to stdin, resolve on result event
   // ---------------------------------------------------------------------------
 
-  async send(
-    message: string,
-    opts?: { timeout?: number },
-  ): Promise<SessionResult> {
+  async send(message: string, opts?: SessionSendOptions): Promise<SessionResult> {
     // Auto-restart after interrupt / process death (crash recovery via --resume).
     // _externalSessionId persists across process lifetimes, so start() will
     // include --resume <id> in spawn args.
+    if (
+      this._attempts.some(
+        (a) =>
+          a.dispatch === 'attempted' &&
+          a.nativeOutcome === 'unknown' &&
+          (!this._alive || a.localOutcome !== 'pending'),
+      )
+    ) {
+      const blocked = new TurnState();
+      this._attempts.push(blocked);
+      throw blocked.fail(new Error('Native outcome unresolved; send not dispatched'), 'blocked');
+    }
     if (!this._proc && this._externalSessionId) {
       await this.start();
     }
 
-    if (!this._proc) throw new Error("Session not started — call start() first");
-    if (!this._alive) throw new Error("Session ended");
+    if (!this._proc) throw new Error('Session not started — call start() first');
+    if (!this._alive) throw new Error('Session ended');
 
     const timeout = opts?.timeout ?? this._defaultTimeout;
 
@@ -319,7 +501,25 @@ export class ClaudeCodeSession implements HarnessSession {
     }
 
     return new Promise<SessionResult>((resolve, reject) => {
-      const turn: QueuedTurn = { message: transformed, timeout, resolve, reject };
+      const evidence = new TurnState();
+      this._attempts.push(evidence);
+      const turn: QueuedTurn = {
+        evidence,
+        message: transformed,
+        timeout,
+        resolve,
+        reject,
+        onAdmission: opts?.onAdmission,
+      };
+      if (!this._alive || (this._inflight && this._inflight.evidence.localOutcome !== 'pending')) {
+        reject(
+          evidence.fail(
+            new Error('Previous native work unresolved; send not dispatched'),
+            'blocked',
+          ),
+        );
+        return;
+      }
 
       if (!this._inflight) {
         this._dispatchTurn(turn);
@@ -333,14 +533,18 @@ export class ClaudeCodeSession implements HarnessSession {
   // fork() — branch from current conversation state
   // ---------------------------------------------------------------------------
 
-  fork(opts?: { cwd?: string; baseContext?: string }): ClaudeCodeSession {
+  fork(opts?: {
+    cwd?: string;
+    baseContext?: string;
+    persistSession?: boolean;
+    spawn?: ClaudeCodeSessionConfig['spawn'];
+  }): ClaudeCodeSession {
+    if (this._inflight) throw new Error('Cannot fork while native ownership is unresolved');
     if (!this._externalSessionId) {
-      throw new Error(
-        "Cannot fork — no external session ID yet (send at least one message first)",
-      );
+      throw new Error('Cannot fork — no external session ID yet (send at least one message first)');
     }
 
-    const forked = new ClaudeCodeSession({
+    const forked = this._construct({
       bin: this._bin,
       model: this._model,
       effort: this._effort,
@@ -350,23 +554,109 @@ export class ClaudeCodeSession implements HarnessSession {
       timeout: this._defaultTimeout,
       baseContext: opts?.baseContext ?? this._baseContext,
       externalSessionId: this._externalSessionId,
-      spawn: this._spawn,
+      spawn: opts?.spawn ?? this._spawn,
+      env: this._env,
+      textOnly: this._textOnly,
+      persistSession: opts?.persistSession ?? this._persistSession,
     });
     forked._forking = true;
     return forked;
   }
 
+  /** Construct a sibling session (fork). Subclasses keep their own transport. */
+  protected _construct(config: ClaudeCodeSessionConfig): ClaudeCodeSession {
+    return new ClaudeCodeSession(config);
+  }
+
   // ---------------------------------------------------------------------------
-  // interrupt() — cancel the in-flight turn (best-effort)
+  // interrupt() — reject the local waiter; native cancellation is unacknowledged
   // ---------------------------------------------------------------------------
 
   interrupt(): void {
     if (!this._inflight) return;
 
-    this._rejectInflight(new Error("Turn interrupted"));
+    this._rejectInflight(
+      new Error('Local waiter interrupted; native cancellation unacknowledged'),
+      'interrupt-request',
+    );
+
+    // Native ownership is retained. Waiting sends are rejected without dispatch.
+  }
+
+  /**
+   * Native interrupt through the CLI control protocol. Resolves "acknowledged"
+   * once the CLI confirms and the turn's own terminal arrives (the send()
+   * settles through that terminal, normally as a failed/interrupted outcome).
+   */
+  async interruptNative(opts?: { timeoutMs?: number }): Promise<NativeInterruptOutcome> {
+    const turn = this._inflight;
+    if (turn?.evidence.dispatch !== 'attempted' || turn.evidence.nativeOutcome !== 'unknown')
+      return 'no-turn';
+    const deadline = Date.now() + (opts?.timeoutMs ?? 5_000);
+    try {
+      await this._controlRequest({ subtype: 'interrupt' }, Math.max(1, deadline - Date.now()));
+    } catch {
+      return 'unacknowledged';
+    }
+    while (turn.evidence.nativeOutcome === 'unknown' && this._alive && Date.now() < deadline)
+      await Bun.sleep(10);
+    return turn.evidence.nativeOutcome === 'unknown' ? 'unacknowledged' : 'acknowledged';
+  }
 
-    // Process continues running. When it emits the orphaned result,
-    // _processLine dispatches the next queued turn (if any).
+  /** Account limits via the CLI control protocol (`get_usage`); no model turn. Requires a started session. */
+  async readLimits(opts?: { timeoutMs?: number }): Promise<LimitSnapshot | undefined> {
+    const response = await this._controlRequest(
+      { subtype: 'get_usage' },
+      opts?.timeoutMs ?? 10_000,
+    );
+    const snapshot = claudeUsageSnapshot(response.response);
+    if (snapshot) this._observeLimits(snapshot);
+    return snapshot;
+  }
+
+  private _controlRequest(
+    request: Record<string, unknown>,
+    timeoutMs: number,
+  ): Promise<Record<string, unknown>> {
+    if (!this._proc || !this._alive) return Promise.reject(new Error('Session not running'));
+    const requestId = `agent-session-${++this._controlSeq}-${crypto.randomUUID()}`;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        this._control.delete(requestId);
+        reject(new Error(`Control request ${String(request.subtype)} timed out`));
+      }, timeoutMs);
+      this._control.set(requestId, {
+        resolve: (value) => {
+          clearTimeout(timer);
+          resolve(value);
+        },
+        reject: (error) => {
+          clearTimeout(timer);
+          reject(error);
+        },
+      });
+      try {
+        this._proc!.stdin.write(
+          `${JSON.stringify({ type: 'control_request', request_id: requestId, request })}\n`,
+        );
+        this._proc!.stdin.flush();
+      } catch (error) {
+        this._control.delete(requestId);
+        clearTimeout(timer);
+        reject(error as Error);
+      }
+    });
+  }
+
+  private _observeLimits(snapshot: LimitSnapshot): void {
+    this._limits = mergeLimits(this._limits, snapshot);
+    this._emit({
+      kind: 'rate_limit',
+      timestamp: Date.now(),
+      correlation: 'unknown',
+      unattributedReason: 'account-status',
+      limits: this._limits,
+    });
   }
 
   // ---------------------------------------------------------------------------
@@ -382,14 +672,23 @@ export class ClaudeCodeSession implements HarnessSession {
       this._turnTimer = null;
     }
 
-    this._rejectInflight(new Error("Session killed"));
-    this._rejectQueue(new Error("Session killed"));
+    this._rejectInflight(new Error('Session killed; native outcome may remain unknown'), 'killed');
+    this._rejectQueue(new Error('Session killed'));
+    this._rejectControl(new Error('Session killed'));
 
-    try { this._proc.stdin.end(); } catch { /* already closed */ }
-    try { this._proc.kill(); } catch { /* already dead */ }
+    try {
+      this._proc.stdin.end();
+    } catch {
+      /* already closed */
+    }
+    try {
+      this._proc.kill();
+    } catch {
+      /* already dead */
+    }
     this._proc = null;
 
-    this._emit({ kind: "session_end", timestamp: Date.now() });
+    this._emit({ kind: 'session_end', timestamp: Date.now() });
   }
 
   // ---------------------------------------------------------------------------
@@ -399,14 +698,17 @@ export class ClaudeCodeSession implements HarnessSession {
   artifact(): SessionArtifact {
     return {
       externalSessionId: this._externalSessionId,
+      attempts: this.attempts,
+      accounting: 'observed-only',
+      diagnostics: this.diagnostics,
       events: [...this._eventLog],
       startedAt: this._startedAt,
       endedAt: this._alive ? undefined : Date.now(),
       turns: this._turns,
       totalTokens: { ...this._totalTokens },
-      toolCalls: this._eventLog.filter((e) => e.kind === "tool_use").length,
-      toolResults: this._eventLog.filter((e) => e.kind === "tool_result").length,
-      errors: this._eventLog.filter((e) => e.kind === "error").length,
+      toolCalls: this._eventLog.filter((e) => e.kind === 'tool_use').length,
+      toolResults: this._eventLog.filter((e) => e.kind === 'tool_result').length,
+      errors: this._eventLog.filter((e) => e.kind === 'error').length,
     };
   }
 
@@ -416,29 +718,62 @@ export class ClaudeCodeSession implements HarnessSession {
 
   private _dispatchTurn(turn: QueuedTurn): void {
     this._inflight = turn;
-    this._turnEvents = [];
-    this._resultText = "";
+    if (turn.onAdmission) {
+      Promise.resolve()
+        .then(() => turn.onAdmission!(turn.evidence.snapshot()))
+        .then(() => {
+          if (this._inflight === turn && this._alive && turn.evidence.localOutcome === 'pending')
+            this._writeTurn(turn);
+          else if (this._inflight === turn && turn.evidence.dispatch === 'not-dispatched') {
+            this._inflight = null;
+            this._processNextTurn();
+          }
+        })
+        .catch((error) => {
+          turn.reject(
+            turn.evidence.fail(
+              error instanceof Error ? error : new Error(String(error)),
+              'registration',
+            ),
+          );
+          if (this._inflight === turn) {
+            this._inflight = null;
+            this._processNextTurn();
+          }
+        });
+      return;
+    }
+    this._writeTurn(turn);
+  }
+
+  private _writeTurn(turn: QueuedTurn): void {
+    turn.evidence.dispatch = 'attempted';
 
     // Wire format validated empirically against claude 2.1.114:
     // {type:"user", message:{role,content:[{type:"text",text}]}}
     // Alternative shapes ({type:"user_message"}, {role,content}) are silently dropped.
-    const payload = JSON.stringify({
-      type: "user",
+    const payload = `${JSON.stringify({
+      type: 'user',
       message: {
-        role: "user",
-        content: [{ type: "text", text: turn.message }],
+        role: 'user',
+        content: [{ type: 'text', text: turn.message }],
       },
-    }) + "\n";
-    this._proc!.stdin.write(payload);
-    this._proc!.stdin.flush();
+    })}\n`;
+    try {
+      this._proc!.stdin.write(payload);
+      this._proc!.stdin.flush();
+    } catch (err) {
+      this._rejectInflight(err as Error);
+      return;
+    }
 
     // Timeout guard
     if (turn.timeout > 0) {
       this._turnTimer = setTimeout(() => {
         this._turnTimer = null;
-        this._rejectInflight(new Error(`Turn timed out after ${turn.timeout}ms`));
+        this._rejectInflight(new Error(`Turn timed out after ${turn.timeout}ms`), 'timeout');
         // Don't dispatch next — process may still be working on this turn.
-        // Next queued turn dispatches when the orphaned result arrives.
+        // A late terminal updates this admission; waiting sends are not replayed.
       }, turn.timeout);
     }
   }
@@ -451,41 +786,56 @@ export class ClaudeCodeSession implements HarnessSession {
       this._turnTimer = null;
     }
 
+    const a = this._inflight.evidence;
+    if (a.nativeOutcome === 'unknown') return;
     this._turns++;
-    const result: SessionResult = {
-      content: this._resultText,
-      events: [...this._turnEvents],
-      tokens: this._turnEvents.find((e) => e.tokens)?.tokens,
-      externalSessionId: this._externalSessionId,
-    };
-    this._inflight.resolve(result);
+    if (a.localOutcome === 'pending') {
+      a.localOutcome = 'resolved';
+      this._inflight.resolve(a.result(this._externalSessionId));
+    }
     this._inflight = null;
 
     this._processNextTurn();
   }
 
   private _processNextTurn(): void {
-    if (this._queue.length > 0 && this._alive) {
+    if (!this._inflight && this._queue.length > 0 && this._alive) {
       const next = this._queue.shift()!;
       this._dispatchTurn(next);
     }
   }
 
-  private _rejectInflight(err: Error): void {
+  private _rejectInflight(
+    err: Error,
+    reason: import('./harness-session').SessionAttempt['localFailure'] = 'transport',
+  ): void {
     if (!this._inflight) return;
-
     if (this._turnTimer) {
       clearTimeout(this._turnTimer);
       this._turnTimer = null;
     }
+    const a = this._inflight.evidence;
+    if ((reason === 'transport' || reason === 'killed') && a.transportOutcome === 'open')
+      a.transportOutcome = reason === 'killed' ? 'closed' : 'failed';
+    if (a.localOutcome === 'pending') this._inflight.reject(a.fail(err, reason));
+    this._rejectQueue(
+      reason === 'killed'
+        ? err
+        : new Error('Previous native work unresolved; queued send not dispatched'),
+    );
+  }
 
-    this._inflight.reject(err);
-    this._inflight = null;
+  private _transportFailure(err: Error): void {
+    this._alive = false;
+    this._rejectInflight(err);
+    this._rejectQueue(err);
+    this._rejectControl(err);
+    this._emit({ kind: 'session_end', timestamp: Date.now(), transportOutcome: 'failed' });
   }
 
   private _rejectQueue(err: Error): void {
     for (const turn of this._queue) {
-      turn.reject(err);
+      turn.reject(turn.evidence.fail(err, 'blocked'));
     }
     this._queue = [];
   }
@@ -494,10 +844,10 @@ export class ClaudeCodeSession implements HarnessSession {
   // Private — stdout reader (background, runs for session lifetime)
   // ---------------------------------------------------------------------------
 
-  private async _readStdout(): Promise<void> {
-    const reader = this._proc!.stdout.getReader();
+  private async _readStdout(proc: PipedSubprocess): Promise<void> {
+    const reader = proc.stdout.getReader();
     const decoder = new TextDecoder();
-    let buffer = "";
+    let buffer = '';
 
     try {
       while (true) {
@@ -505,21 +855,29 @@ export class ClaudeCodeSession implements HarnessSession {
         if (done) break;
 
         buffer += decoder.decode(value, { stream: true });
-        const lines = buffer.split("\n");
+        const lines = buffer.split('\n');
         buffer = lines.pop()!; // Keep incomplete line in buffer
 
         for (const line of lines) {
           if (!line.trim()) continue;
-          this._processLine(line);
+          if (this._proc === proc || !this._proc) this._processLine(line);
         }
       }
 
       // Flush remaining buffer
-      if (buffer.trim()) {
+      if (buffer.trim() && (this._proc === proc || !this._proc)) {
         this._processLine(buffer);
       }
+      if (this._proc === proc && this._alive)
+        this._transportFailure(
+          new Error(
+            this._stderr.trim()
+              ? `Native stdout closed: ${this._stderr.trim().slice(0, 500)}`
+              : 'Native stdout closed',
+          ),
+        );
     } catch (err) {
-      this._rejectInflight(err as Error);
+      if (this._proc === proc) this._transportFailure(err as Error);
     }
   }
 
@@ -536,7 +894,9 @@ export class ClaudeCodeSession implements HarnessSession {
         if (done) break;
         this._stderr += decoder.decode(value, { stream: true });
       }
-    } catch { /* ignore */ }
+    } catch {
+      /* ignore */
+    }
   }
 
   // ---------------------------------------------------------------------------
@@ -553,61 +913,184 @@ export class ClaudeCodeSession implements HarnessSession {
 
     const raw = msg as Record<string, unknown>;
 
+    // Control-protocol traffic belongs to the local client, never to an admission.
+    if (raw.type === 'control_response') {
+      const response = raw.response as Record<string, unknown> | undefined;
+      const id = typeof response?.request_id === 'string' ? response.request_id : undefined;
+      const pending = id ? this._control.get(id) : undefined;
+      if (pending && id) {
+        this._control.delete(id);
+        if (response?.subtype === 'success') pending.resolve(response);
+        else
+          pending.reject(
+            new Error(
+              typeof response?.error === 'string' ? response.error : 'Control request failed',
+            ),
+          );
+      }
+      return;
+    }
+    if (raw.type === 'control_request') {
+      // No client-side handlers (can_use_tool, hooks) are registered on this transport.
+      const id = typeof raw.request_id === 'string' ? raw.request_id : undefined;
+      if (id && this._proc) {
+        try {
+          this._proc.stdin.write(
+            `${JSON.stringify({
+              type: 'control_response',
+              response: { subtype: 'error', request_id: id, error: 'Unsupported by this client' },
+            })}\n`,
+          );
+          this._proc.stdin.flush();
+        } catch {
+          /* transport failure surfaces on the stream */
+        }
+      }
+      this._unattributed(raw, 'unrecognized-event');
+      return;
+    }
+
+    if (
+      this._awaitingForkIdentity &&
+      raw.type === 'system' &&
+      raw.subtype === 'init' &&
+      typeof raw.session_id === 'string'
+    ) {
+      this._externalSessionId = raw.session_id;
+      this._awaitingForkIdentity = false;
+    }
+    // A foreign session or repeated result UUID cannot own the current admission.
+    if (
+      typeof raw.session_id === 'string' &&
+      this._externalSessionId &&
+      raw.session_id !== this._externalSessionId
+    ) {
+      this._unattributed(raw, 'foreign-session');
+      return;
+    }
+    const terminalKey =
+      raw.type === 'result' && typeof raw.uuid === 'string' ? raw.uuid : undefined;
+    if (terminalKey && this._seenTerminals.has(terminalKey)) {
+      this._unattributed(raw, 'duplicate-terminal');
+      return;
+    }
     // Capture the runtime's native session ID the first time we see it.
     // Subsequent messages echo the same ID; we keep our initial capture
     // (for resumed sessions, the config-supplied ID should match).
-    if (typeof raw.session_id === "string" && !this._externalSessionId) {
+    if (typeof raw.session_id === 'string' && !this._externalSessionId) {
       this._externalSessionId = raw.session_id;
     }
 
-    // Compaction detection: a system/init message arriving after we've
-    // already seen one means the Claude Code session was restarted mid-run.
-    // Auto-compact works by killing and resuming the session, which fires
-    // a new init event. This tells the FlowOrchestrator that the session's
-    // in-memory state was summarized — the Librarian ledger is stale.
-    if (raw.type === "system" && (raw.subtype === "init" || raw.subtype === "compact_boundary")) {
-      if (this._sawInit && raw.subtype === "init") {
-        this._emit({
-          kind: "session_compact",
-          timestamp: Date.now(),
-          externalSessionId: this._externalSessionId,
-          compactionSource: "claude-code",
-          raw,
-        });
-      } else if (raw.subtype === "compact_boundary") {
-        this._emit({
-          kind: "session_compact",
-          timestamp: Date.now(),
-          externalSessionId: this._externalSessionId,
-          compactionSource: "claude-code",
-          raw,
-        });
+    // Lifecycle/configuration envelopes belong to the session, not to whichever
+    // admission is in flight. Every init is preserved once with its binding; it is
+    // never attributed to a turn and never compared against an earlier init to infer
+    // compaction or restart. Only an explicit compact_boundary is a compaction, and
+    // it is emitted exactly once per native uuid with this session's provenance.
+    // Foreign bindings were already refused above and cannot invalidate this owner.
+    if (raw.type === 'system' && raw.subtype === 'init') {
+      this._unattributed(raw, 'session-configuration');
+      return;
+    }
+    if (raw.type === 'system' && raw.subtype === 'compact_boundary') {
+      const boundaryKey = typeof raw.uuid === 'string' ? raw.uuid : undefined;
+      if (boundaryKey && this._seenBoundaries.has(boundaryKey)) {
+        this._unattributed(raw, 'duplicate-boundary');
+        return;
       }
-      this._sawInit = true;
+      if (boundaryKey) this._seenBoundaries.add(boundaryKey);
+      this._emit({
+        kind: 'session_compact',
+        timestamp: Date.now(),
+        correlation: 'unknown',
+        nativeSessionId:
+          typeof raw.session_id === 'string' ? raw.session_id : this._externalSessionId,
+        externalSessionId: this._externalSessionId,
+        compactionSource: 'claude-code',
+        raw,
+      });
+      return;
     }
 
+    // Account limits are account-level evidence, never part of an admission's output.
+    if (raw.type === 'rate_limit_event') {
+      const snapshot = claudeRateLimitSnapshot(raw.rate_limit_info);
+      if (snapshot) this._observeLimits(snapshot);
+      else this._unattributed(raw, 'account-status');
+      return;
+    }
+
+    const turn = this._inflight;
+    if (!turn) {
+      if (terminalKey) this._seenTerminals.add(terminalKey);
+      this._unattributed(raw, 'no-admission');
+      return;
+    }
+    const a = turn.evidence;
+    a.identity = {
+      ...a.identity,
+      nativeSessionId:
+        typeof raw.session_id === 'string' ? raw.session_id : a.identity.nativeSessionId,
+      correlation: 'ordered-stream',
+    };
+    const terminal = raw.type === 'result';
+    if (terminal) {
+      if (terminalKey) this._seenTerminals.add(terminalKey);
+      const subtype = typeof raw.subtype === 'string' ? raw.subtype : undefined;
+      const reason = typeof raw.terminal_reason === 'string' ? raw.terminal_reason : undefined;
+      const status =
+        typeof raw.api_error_status === 'number' && Number.isFinite(raw.api_error_status)
+          ? raw.api_error_status
+          : undefined;
+      // Match Foundry's provider precedence. An optimistic subtype cannot erase
+      // an explicit native error; local transport/RPC errors do not enter here.
+      const failed =
+        raw.is_error === true ||
+        subtype?.startsWith('error_') ||
+        (status !== undefined && status >= 400) ||
+        reason === 'api_error';
+      a.nativeOutcome = failed ? 'failed' : subtype === 'success' ? 'completed' : 'unknown';
+      a.terminal = {
+        type: 'result',
+        eventId: terminalKey,
+        subtype,
+        reason,
+        apiErrorStatus: status,
+      };
+    }
+    const message = raw.message as Record<string, unknown> | undefined;
     const classified = this._classify(raw);
+    if (!classified.length) this._unattributed(raw, 'unrecognized-event');
     for (const event of classified) {
-      this._emit(event);
-      this._turnEvents.push(event);
-
-      if (event.kind === "result") {
-        this._resultText = event.text ?? "";
-      }
-      if (event.tokens) {
-        this._totalTokens.input += event.tokens.input;
-        this._totalTokens.output += event.tokens.output;
+      const e = a.record({
+        ...event,
+        messageId: typeof message?.id === 'string' ? message.id : undefined,
+        ...(terminal ? { nativeOutcome: a.nativeOutcome, terminal: a.terminal } : {}),
+      });
+      // Native result usage is authoritative for the whole turn. Request
+      // snapshots can repeat across content blocks and must not be added again.
+      if (e.kind === 'result' && e.tokens) {
+        for (const key of [
+          'input',
+          'output',
+          'cacheRead',
+          'cacheWrite',
+          'cacheWrite5m',
+          'cacheWrite1h',
+          'thinking',
+        ] as const) {
+          const value = e.tokens[key];
+          if (value !== undefined) this._totalTokens[key] = (this._totalTokens[key] ?? 0) + value;
+        }
       }
+      this._emit(e);
     }
-
-    // Result event resolves the pending turn (or dispatches next if orphaned)
-    if (raw.type === "result") {
-      if (this._inflight) {
-        this._resolveTurn();
-      } else {
-        // Orphaned result from interrupted/timed-out turn — dispatch next
-        this._processNextTurn();
-      }
+    if (terminal) {
+      if (a.nativeOutcome !== 'unknown') this._resolveTurn();
+      else
+        this._rejectInflight(
+          new Error('Native result has no recognized terminal status'),
+          'unrecognized-terminal',
+        );
     }
   }
 
@@ -619,31 +1102,39 @@ export class ClaudeCodeSession implements HarnessSession {
     // --print + --input-format stream-json = multi-turn stream over stdin
     // --output-format stream-json requires --verbose
     const args: string[] = [
-      "--print",
-      "--verbose",
-      "--input-format", "stream-json",
-      "--output-format", "stream-json",
-      "--model", this._model,
-      ...(this._effort ? ["--effort", this._effort] : []),
-      "--max-turns", String(this._maxTurns),
-      "--permission-mode", this._permissionMode,
-      "--include-hook-events",
+      '--print',
+      '--verbose',
+      '--input-format',
+      'stream-json',
+      '--output-format',
+      'stream-json',
+      '--model',
+      this._model,
+      ...(this._effort ? ['--effort', this._effort] : []),
+      ...(this._maxTurns === null ? [] : ['--max-turns', String(this._maxTurns)]),
+      '--permission-mode',
+      this._permissionMode,
+      '--include-hook-events',
     ];
 
     // Resume for fork or crash recovery. _externalSessionId is set from
     // config (crash recovery / fork) or from the stream. Either way, if
     // it's present at spawn time, we --resume.
+    if (this._textOnly) args.push(...CLAUDE_TEXT_ONLY_ARGS);
+    if (!this._persistSession) args.push('--no-session-persistence');
+
     if (this._externalSessionId) {
-      args.push("--resume", this._externalSessionId);
+      args.push('--resume', this._externalSessionId);
       if (this._forking) {
-        args.push("--fork-session");
+        args.push('--fork-session');
+        this._awaitingForkIdentity = true;
         this._forking = false;
       }
     }
 
     // Stable base context injected once at process startup
     if (this._baseContext) {
-      args.push("--append-system-prompt", this._baseContext);
+      args.push('--append-system-prompt', this._baseContext);
     }
 
     return args;
@@ -659,55 +1150,72 @@ export class ClaudeCodeSession implements HarnessSession {
 
     const type = msg.type as string | undefined;
 
-    if (type === "assistant") {
+    if (type === 'assistant') {
       const message = msg.message as Record<string, unknown> | undefined;
+      const tokens = parseClaudeUsage(message?.usage);
+      if (tokens) {
+        // Preserve the envelope (message/request IDs, model and usage tags),
+        // including when a process dies before the terminal result arrives.
+        events.push({ kind: 'usage', timestamp: ts, tokens, raw: msg });
+      }
       const content = message?.content;
       if (!Array.isArray(content)) return events;
 
       for (const block of content) {
         const blockType = (block as Record<string, unknown>).type as string;
 
-        if (blockType === "text") {
-          const text = (block as Record<string, unknown>).text as
-            | string
-            | undefined;
+        if (blockType === 'text') {
+          const text = (block as Record<string, unknown>).text as string | undefined;
           if (text) {
-            events.push({ kind: "text", timestamp: ts, text, raw: block });
+            events.push({ kind: 'text', timestamp: ts, text, raw: block });
           }
-        } else if (blockType === "tool_use") {
+        } else if (blockType === 'tool_use') {
           events.push({
-            kind: "tool_use",
+            kind: 'tool_use',
             timestamp: ts,
+            callId: typeof block.id === 'string' ? block.id : undefined,
+            itemId: typeof block.id === 'string' ? block.id : undefined,
             toolName: (block as Record<string, unknown>).name as string,
-            toolInput: (block as Record<string, unknown>).input as Record<
-              string,
-              unknown
-            >,
+            toolInput: (block as Record<string, unknown>).input as Record<string, unknown>,
             raw: block,
           });
-        } else if (blockType === "thinking") {
+        } else if (blockType === 'thinking') {
           const b = block as Record<string, unknown>;
           events.push({
-            kind: "thinking",
+            kind: 'thinking',
             timestamp: ts,
             text: (b.thinking ?? b.text ?? b.content) as string | undefined,
             raw: block,
           });
         }
       }
-    } else if (type === "tool") {
+    } else if (type === 'user') {
+      const message = msg.message as Record<string, unknown> | undefined;
+      if (Array.isArray(message?.content))
+        for (const block of message.content) {
+          if (block?.type !== 'tool_result') continue;
+          events.push({
+            kind: 'tool_result',
+            timestamp: ts,
+            callId: typeof block.tool_use_id === 'string' ? block.tool_use_id : undefined,
+            ...publicToolResultContent(block.content),
+            toolError: block.is_error === true,
+            raw: block,
+          });
+        }
+    } else if (type === 'tool') {
       // Tool result — what the tool returned
       const content = msg.content;
       if (Array.isArray(content)) {
         for (const block of content) {
           const b = block as Record<string, unknown>;
           events.push({
-            kind: "tool_result",
+            kind: 'tool_result',
             timestamp: ts,
             toolOutput:
-              typeof b.text === "string"
+              typeof b.text === 'string'
                 ? b.text
-                : typeof b.content === "string"
+                : typeof b.content === 'string'
                   ? b.content
                   : JSON.stringify(block),
             toolError: b.is_error === true,
@@ -716,39 +1224,27 @@ export class ClaudeCodeSession implements HarnessSession {
         }
       } else if (content != null) {
         events.push({
-          kind: "tool_result",
+          kind: 'tool_result',
           timestamp: ts,
-          toolOutput:
-            typeof content === "string" ? content : JSON.stringify(content),
+          toolOutput: typeof content === 'string' ? content : JSON.stringify(content),
           raw: content,
         });
       }
-    } else if (type === "result") {
-      const usage = msg.usage as
-        | Record<string, number>
-        | undefined;
+    } else if (type === 'result') {
       events.push({
-        kind: "result",
+        kind: 'result',
         timestamp: ts,
-        text: (msg.result as string) ?? "",
+        text: (msg.result as string) ?? '',
         externalSessionId: msg.session_id as string | undefined,
-        tokens: usage
-          ? {
-              input: usage.input_tokens ?? 0,
-              output: usage.output_tokens ?? 0,
-            }
-          : undefined,
+        tokens: parseClaudeUsage(msg.usage),
         raw: msg,
       });
-    } else if (type === "error") {
+    } else if (type === 'error') {
       const error = msg.error as Record<string, unknown> | undefined;
       events.push({
-        kind: "error",
+        kind: 'error',
         timestamp: ts,
-        text:
-          (error?.message as string) ??
-          (msg.message as string) ??
-          JSON.stringify(msg),
+        text: (error?.message as string) ?? (msg.message as string) ?? JSON.stringify(msg),
         raw: msg,
       });
     }
@@ -763,16 +1259,40 @@ export class ClaudeCodeSession implements HarnessSession {
   // Private — emit
   // ---------------------------------------------------------------------------
 
+  private _unattributed(
+    raw: Record<string, unknown>,
+    reason: NonNullable<SessionEvent['unattributedReason']>,
+  ): void {
+    const message = raw.message as Record<string, unknown> | undefined;
+    // Preserve the original envelope once, without synthesizing admission/native ownership.
+    this._emit({
+      kind: 'native_status',
+      timestamp: Date.now(),
+      correlation: 'unknown',
+      unattributedReason: reason,
+      nativeSessionId: typeof raw.session_id === 'string' ? raw.session_id : undefined,
+      messageId: typeof message?.id === 'string' ? message.id : undefined,
+      raw,
+    });
+  }
+
   private _emit(event: SessionEvent): void {
+    event = retainEvidence(event);
+    if (event.kind === 'session_end') {
+      if (this._endEmitted) return;
+      this._endEmitted = true;
+    }
     this._eventLog.push(event);
     for (const handler of this._handlers) {
       try {
-        handler(event);
-      } catch (err) {
-        console.warn(
-          "[ClaudeCodeSession] handler error:",
-          (err as Error).message,
-        );
+        const observation: unknown = handler(event);
+        if (observation && typeof (observation as PromiseLike<unknown>).then === 'function') {
+          void Promise.resolve(observation).catch(() => {
+            this._observerFailures.asynchronous++;
+          });
+        }
+      } catch {
+        this._observerFailures.synchronous++;
       }
     }
   }