@awak-app/simy-cli 0.7.46 → 0.7.48

package/src/session-supervision/claude-stream-owner.js

@@ -0,0 +1,266 @@
+import { randomUUID } from 'node:crypto';
+import { access, realpath } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { delimiter, isAbsolute, join } from 'node:path';
+import { createControllerStore } from './controller-store.js';
+import { createOperationJournal } from './operation-journal.js';
+import { openClaudeStreamTransport } from './claude-stream-transport.js';
+import { snapshotClaudeHumanCursor, validateClaudeStreamCursor } from './claude-sessions.js';
+
+const fail = code => Object.assign(new Error(code), { code });
+const same = (a, b) => JSON.stringify(a) === JSON.stringify(b);
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// Explicitly isolated native configuration is part of the saved policy. Resume
+// replays it exactly; an observed external transcript cannot manufacture it.
+export const CLAUDE_CONNECTED_ARGS = ['--setting-sources', '', '--settings', '{"disableAllHooks":true}',
+  '--strict-mcp-config', '--mcp-config', '{"mcpServers":{}}', '--disable-slash-commands'];
+
+export function createClaudeStreamOwner({ root, context, authorize, inspectProcess, executable,
+  openTransport = openClaudeStreamTransport, resolvePath = realpath, onChange = () => {}, now = Date.now,
+  snapshotCursor = snapshotClaudeHumanCursor, validateCursor = validateClaudeStreamCursor }) {
+  const store = createControllerStore(join(root, 'claude-stream-owners'));
+  const journal = createOperationJournal(join(root, 'claude-stream-operations'));
+  const live = new Map();
+  let queue = Promise.resolve(), stopped = false, revoking = false;
+  const enqueue = work => { const result = queue.catch(() => {}).then(work); queue = result; return result; };
+  const key = (scope, session) => JSON.stringify([scope, session]);
+  async function boundary(expected) {
+    if (stopped || revoking) throw fail('claude_owner_stopped');
+    await authorize();
+    if (stopped || revoking) throw fail('claude_owner_stopped');
+    const observed = await context();
+    if (stopped || revoking) throw fail('claude_owner_stopped');
+    const current = { scope: observed?.scope, epoch: observed?.epoch, account: observed?.account };
+    if (!current.scope || current.epoch === undefined || !current.account || expected && !same(current, expected)) throw fail('claude_owner_scope_changed');
+    return current;
+  }
+  async function load(identity, session) { return (await store.load(identity.scope)).claudeOwners?.[session]; }
+  async function save(identity, session, mutate) {
+    return store.change(identity.scope, state => {
+      state.claudeOwners ||= {};
+      const previous = state.claudeOwners[session];
+      const value = mutate(previous);
+      state.claudeOwners[session] = value;
+      return structuredClone(value);
+    });
+  }
+  const view = (record, transport) => {
+    if (!record) return null;
+    const native = transport?.snapshot(), owned = Boolean(native && native.state !== 'closed');
+    return { scope: record.identity.scope, session: record.session, cwd: record.cwd, model: record.model, pid: record.pid,
+      permissionMode: record.permissionMode, revision: record.revision, epoch: record.identity.epoch,
+      state: owned ? native.state : record.state, owned,
+      pendingRequestId: owned ? native.pendingRequestId ?? null : null,
+      receipt: record.receipt || null, result: record.result || null,
+      control: owned ? transport.pendingControl() : null };
+  };
+  async function selected(command) {
+    const identity = await boundary();
+    const record = await load(identity, command.session);
+    if (!record || !same(record.identity, identity) || command.expectedEpoch !== identity.epoch ||
+        command.expectedRevision !== record.revision) throw fail('claude_owner_changed');
+    const transport = live.get(key(identity.scope, command.session));
+    return { identity, record, transport };
+  }
+  async function open({ identity, record, resume }) {
+    // Persist the opening fence before creating a process. A crash in this
+    // interval is an unresolved owner, never permission to spawn a replacement.
+    record = await save(identity, record.session, () => ({ ...record, state: 'opening', revision: record.revision + 1 }));
+    let transport, capturedIdentity;
+    try {
+      await boundary(identity);
+      const command = await executable();
+      let nativeExecutable;
+      if (isAbsolute(command)) nativeExecutable = await resolvePath(command);
+      else {
+        for (const directory of (process.env.PATH || '').split(delimiter).filter(isAbsolute)) {
+          try { const candidate = join(directory, command); await access(candidate, constants.X_OK); nativeExecutable = await resolvePath(candidate); break; } catch {}
+        }
+      }
+      if (!nativeExecutable) throw fail('claude_stream_unavailable');
+      if (record.executable && record.executable !== nativeExecutable) throw fail('claude_owner_policy_changed');
+      transport = await openTransport({ executable: nativeExecutable, session: record.session, cwd: record.cwd,
+        model: record.model, permissionMode: record.permissionMode, resume, extraArgs: CLAUDE_CONNECTED_ARGS });
+      live.set(key(identity.scope, record.session), transport);
+      const pid = transport.snapshot().pid;
+      capturedIdentity = await inspectProcess(pid);
+      if (!pid || !capturedIdentity) throw fail('claude_owner_identity_unavailable');
+      await boundary(identity);
+      record = await save(identity, record.session, old => ({ ...old, executable: nativeExecutable, state: 'connected', pid, processIdentity: capturedIdentity, connectedAt: now() }));
+      const update = () => {
+        enqueue(async () => {
+          const cursor = lastResult ? await snapshotCursor(record) : null;
+          const current = await save(identity, record.session, old => ({ ...old,
+            state: transport.snapshot().state === 'closed' ? ['closed', 'stopped', 'revoked', 'unknown'].includes(old.state) ? old.state : 'closed_unexpected' : transport.snapshot().state,
+            revision: old.revision + (lastResult && lastResult.requestId !== old.result?.requestId ? 1 : 0),
+            cursor: cursor || old.cursor, receipt: lastReceipt || old.receipt, result: lastResult || old.result }));
+          onChange(view(current, transport));
+        }).catch(() => { /* A failed durable write cannot authorize a new send. */ });
+      };
+      let lastReceipt, lastResult;
+      transport.on('receipt', value => { lastReceipt = value; });
+      transport.on('result', value => { lastResult = value; });
+      transport.on('change', update);
+      onChange(view(record, transport));
+      return view(record, transport);
+    } catch (error) {
+      // Ownership begins at spawn, not at registration. Never drop a live
+      // handle merely because a bounded signal wait resolved. Unknown identity
+      // permits EOF only; escalation rechecks the captured identity per signal.
+      if (transport) {
+        transport.freeze?.('claude_stream_registration_failed');
+        transport.closeInput?.();
+        if (capturedIdentity) await terminateOwned(transport, { pid: transport.snapshot().pid, processIdentity: capturedIdentity }).catch(() => {});
+        else await transport.waitForExit?.(1000);
+        if (transport.snapshot().state === 'closed') live.delete(key(identity.scope, record.session));
+      }
+      const unknown = await save(identity, record.session, old => ({ ...old, state: 'unknown',
+        ...(transport ? { pid: transport.snapshot().pid, processIdentity: capturedIdentity || null } : {}) }));
+      onChange(view(unknown, live.get(key(identity.scope, record.session))));
+      throw error;
+    }
+  }
+  async function terminateOwned(transport, record, authorizeStop = async () => {}) {
+    const guard = async () => { await authorizeStop();
+      if (!record.processIdentity || await inspectProcess(record.pid) !== record.processIdentity) throw fail('claude_owner_changed'); };
+    if (transport.terminate) return transport.terminate({ beforeSignal: guard });
+    return transport.stop({ beforeStop: guard });
+  }
+  return {
+    async create({ cwd, model, permissionMode = 'manual', confirmedNew = false }) {
+      return enqueue(async () => {
+        if (confirmedNew !== true || !['manual', 'plan'].includes(permissionMode) || !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{1,150}$/.test(model || '')) throw fail('claude_owner_invalid_policy');
+        const identity = await boundary();
+        const record = { session: randomUUID(), cwd: await resolvePath(cwd), model, permissionMode,
+          identity, revision: 0, state: 'new', createdAt: now(), policyVersion: 1, nativeArgs: CLAUDE_CONNECTED_ARGS };
+        return open({ identity, record, resume: false });
+      });
+    },
+    async connect(command) {
+      return enqueue(async () => {
+        const { identity, record, transport } = await selected(command);
+        if (transport && transport.snapshot().state !== 'closed') return view(record, transport);
+        if (transport) live.delete(key(identity.scope, record.session));
+        if (record.state !== 'closed' || record.policyVersion !== 1 || !same(record.nativeArgs, CLAUDE_CONNECTED_ARGS) || !record.pid || !record.processIdentity ||
+            await inspectProcess(record.pid) !== '' || await resolvePath(record.cwd) !== record.cwd ||
+            record.result && (!record.cursor || !await validateCursor(record.cursor))) throw fail('claude_owner_not_proven_closed');
+        return open({ identity, record, resume: true });
+      });
+    },
+    async status(session) {
+      const identity = await boundary();
+      const record = await load(identity, session);
+      if (!record || !same(record.identity, identity)) return null;
+      return view(record, live.get(key(identity.scope, session)));
+    },
+    async list() {
+      const identity = await boundary();
+      return Object.values((await store.load(identity.scope)).claudeOwners || {}).filter(record => same(record.identity, identity))
+        .map(record => view(record, live.get(key(identity.scope, record.session))));
+    },
+    async send(command) {
+      if (!UUID.test(command.requestId || '') || typeof command.text !== 'string' || !command.text.trim() || command.text.length > 4000) throw fail('claude_guidance_invalid');
+      const { identity, record, transport } = await selected(command);
+      const operation = { ...command, provider: 'claude', action: 'session_guidance' };
+      const previous = await journal.begin(identity.scope, operation);
+      if (previous) { if (previous.ok) return previous.data; throw fail(previous.code); }
+      if (!transport) {
+        await journal.finish(identity.scope, operation, { ok: false, code: 'claude_stream_unavailable' });
+        throw fail('claude_stream_unavailable');
+      }
+      try {
+        const data = await transport.send({ requestId: command.requestId, text: `[SIMY user guidance ${command.requestId}]\n${command.text}`,
+          beforeWrite: async () => {
+            await boundary(identity);
+            const current = await load(identity, record.session);
+            if (current.revision !== record.revision || live.get(key(identity.scope, record.session)) !== transport ||
+                await inspectProcess(record.pid) !== record.processIdentity) throw fail('claude_owner_changed');
+            if (current.result && (!current.cursor || !await validateCursor(current.cursor))) {
+              transport.freeze?.('claude_owner_transcript_changed'); throw fail('claude_owner_transcript_changed');
+            }
+          } });
+        await journal.finish(identity.scope, operation, { ok: true, data });
+        return data;
+      } catch (error) {
+        await journal.finish(identity.scope, operation, { ok: false, code: error.code === 'claude_guidance_unknown' ? 'remote_operation_unknown' : error.code || 'claude_guidance_unknown' });
+        throw error;
+      }
+    },
+    async decide(command) {
+      const { identity, record, transport } = await selected(command);
+      if (!transport) throw fail('claude_stream_unavailable');
+      await transport.decide({ controlRequestId: command.controlRequestId, allow: command.allow,
+        beforeWrite: async () => {
+          await boundary(identity);
+          if ((await load(identity, record.session)).revision !== record.revision || await inspectProcess(record.pid) !== record.processIdentity) throw fail('claude_owner_changed');
+          if (record.cursor && !await validateCursor(record.cursor, transport.snapshot().pendingRequestId)) throw fail('claude_owner_transcript_changed');
+        } });
+      return view(record, transport);
+    },
+    async disconnect(command) {
+      return enqueue(async () => {
+        const { identity, record, transport } = await selected(command);
+        if (!transport || transport.snapshot().state !== 'idle') throw fail('claude_stream_busy');
+        await boundary(identity);
+        await transport.close();
+        if (await inspectProcess(record.pid) !== '') throw fail('claude_owner_not_proven_closed');
+        live.delete(key(identity.scope, record.session));
+        return view(await save(identity, record.session, old => ({ ...old, state: 'closed', revision: old.revision + 1, closedAt: now() })));
+      });
+    },
+    async stop(command, { authorize: authorizeStop = async () => {} } = {}) {
+      return enqueue(async () => {
+        if (command.confirmed !== true) throw fail('claude_owner_stop_confirmation_required');
+        // Local teardown cannot depend on a native credential that may have
+        // just been revoked. It grants no input or permission; the host still
+        // fences its controller scope and every signal verifies the exact PID.
+        const matches = [...live].filter(([entry]) => JSON.parse(entry)[1] === command.session);
+        if (matches.length !== 1) throw fail('claude_stream_unavailable');
+        const [entry, transport] = matches[0], [scope] = JSON.parse(entry);
+        const record = (await store.load(scope)).claudeOwners?.[command.session], identity = record?.identity;
+        if (!record || record.revision !== command.expectedRevision || identity.epoch !== command.expectedEpoch) throw fail('claude_owner_changed');
+        await terminateOwned(transport, record, authorizeStop);
+        if (await inspectProcess(record.pid) !== '') throw fail('claude_owner_not_proven_closed');
+        live.delete(key(identity.scope, record.session));
+        return view(await save(identity, record.session, old => ({ ...old, state: 'stopped', revision: old.revision + 1, closedAt: now() })));
+      });
+    },
+    busy: () => [...live.values()].some(transport => !['idle', 'closed'].includes(transport.snapshot().state)),
+    revoke() {
+      // Revocation grants no provider input or permission response. It only
+      // tears down children already registered to this exact execution owner,
+      // without requiring the credentials that have just been revoked.
+      revoking = true;
+      return enqueue(async () => {
+        for (const [entry, transport] of live) {
+          const [scope, session] = JSON.parse(entry);
+          const record = (await store.load(scope)).claudeOwners?.[session];
+          const observed = record && await inspectProcess(record.pid);
+          if (observed !== '' && (!record?.processIdentity || observed !== record.processIdentity)) throw fail('claude_owner_identity_unavailable');
+          if (observed !== '') await terminateOwned(transport, record);
+          if (await inspectProcess(record.pid) !== '') throw fail('claude_owner_not_proven_closed');
+          live.delete(entry);
+          const ended = await store.change(scope, state => {
+            const current = state.claudeOwners[session]; current.state = 'revoked'; current.revision++;
+            current.closedAt = now(); return structuredClone(current);
+          });
+          onChange(view(ended));
+        }
+      }).finally(() => { revoking = false; });
+    },
+    async close() {
+      if ([...live.values()].some(transport => !['idle', 'closed'].includes(transport.snapshot().state))) throw fail('claude_stream_busy');
+      // Orderly host shutdown records closure; unknown/crashed owners remain
+      // blocked and are never silently resumed by the next host.
+      for (const [entry, transport] of live) {
+        const [scope, session] = JSON.parse(entry);
+        await transport.close();
+        const record = (await store.load(scope)).claudeOwners?.[session];
+        const dead = record && await inspectProcess(record.pid) === '';
+        await store.change(scope, state => { const current = state.claudeOwners?.[session];
+          if (current && dead) { current.state = 'closed'; current.revision++; current.closedAt = now(); } });
+      }
+      stopped = true; await queue.catch(() => {}); await store.close(); await journal.close();
+    },
+  };
+}

package/src/session-supervision/claude-stream-presentation.js

@@ -0,0 +1,27 @@
+export function claudeStreamPresentation(candidate, owner) {
+  if (candidate.provider !== 'claude' || candidate.hostId && candidate.hostId !== 'local' || candidate.remoteHost || candidate.teamRemote ||
+      !owner || owner.session !== candidate.session || owner.cwd !== candidate.cwd) return candidate;
+  const { scope, ...connection } = owner;
+  const available = owner.owned === true && owner.state === 'idle';
+  const active = owner.owned === true && ['authorizing', 'working', 'awaiting_permission'].includes(owner.state);
+  const requestId = owner.pendingRequestId || (owner.state !== 'authorizing' ? owner.receipt?.requestId : null);
+  const currentReceipt = Boolean(requestId && owner.receipt?.requestId === requestId);
+  const currentResult = Boolean(requestId && owner.result?.requestId === requestId);
+  const pending = active || currentReceipt && !currentResult;
+  let state = currentResult ? 'observed' : 'not_sent';
+  if (pending) {
+    state = 'submitting';
+    if (currentReceipt && owner.receipt.state === 'unknown') state = 'unknown';
+    else if (currentReceipt && owner.receipt.providerReceiptConfirmed) state = 'submitted';
+  }
+  return { ...candidate, claudeConnection: connection,
+    originalSessionTarget: { kind: 'simy_claude_stream', session: owner.session, label: 'Open connected Claude conversation in SIMY' },
+    conversationPresentation: { ...candidate.conversationPresentation,
+      guidance: { available, ...(requestId ? { requestId } : {}),
+        state,
+        providerReceiptConfirmed: currentReceipt && owner.receipt.providerReceiptConfirmed === true,
+        providerExecutionConfirmed: currentResult && owner.result.providerExecutionConfirmed === true,
+        reason: available ? null : owner.owned ? owner.state : owner.state === 'closed' ? 'claude_connection_closed' : 'claude_owner_unproven',
+        ...(available ? { target: { provider: 'claude', session: owner.session, cwd: owner.cwd, runId: `claude-stream:${owner.session}`,
+          taskId: owner.session, revision: owner.revision, epoch: owner.epoch } } : {}) } } };
+}

package/src/session-supervision/claude-stream-transport.js

@@ -0,0 +1,188 @@
+import { EventEmitter } from 'node:events';
+import { spawn } from 'node:child_process';
+import { createHash } from 'node:crypto';
+
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const MODES = new Set(['manual', 'plan', 'acceptEdits']);
+const failure = code => Object.assign(new Error(code), { code });
+const digest = text => createHash('sha256').update(text).digest('hex');
+const userText = content => typeof content === 'string' ? content : Array.isArray(content) && content.every(v => v?.type === 'text' && typeof v.text === 'string')
+  ? content.map(v => v.text).join('') : null;
+
+// This object owns the provider's original stdin for its entire lifetime. It
+// never attaches to a terminal, forks a transcript, or resumes another writer.
+// The controller supplies an already-authorized immutable launch policy.
+export async function openClaudeStreamTransport({ executable, session, cwd, model, permissionMode,
+  resume = false, environment = process.env, spawnImpl = spawn, receiptTimeoutMs = 30_000,
+  maxLineBytes = 8 * 1024 * 1024, extraArgs = [] } = {}) {
+  if (typeof executable !== 'string' || !executable || !UUID.test(session || '') || typeof cwd !== 'string' || !cwd ||
+      !/^[a-zA-Z0-9][a-zA-Z0-9._:-]{1,150}$/.test(model || '') || !MODES.has(permissionMode)) throw failure('claude_stream_invalid_policy');
+  const args = ['-p', '--input-format', 'stream-json', '--output-format', 'stream-json', '--verbose', '--replay-user-messages',
+    '--permission-prompts', 'host', '--permission-prompt-tool=stdio', '--permission-mode', permissionMode, '--model', model,
+    resume ? '--resume' : '--session-id', session, ...extraArgs];
+  const child = spawnImpl(executable, args, { cwd, env: { ...environment }, stdio: ['pipe', 'pipe', 'pipe'], windowsHide: true });
+  const events = new EventEmitter(), requests = new Map(), toolUses = new Set();
+  let state = 'starting', buffer = Buffer.alloc(0), pending = null, control = null, closed = false, faulted = false, stderrSeen = false;
+  const snapshot = () => ({ session, pid: child.pid, state, model, permissionMode,
+    pendingRequestId: pending?.id ?? null, controlRequestId: control?.id ?? null, stderrSeen });
+  const publish = () => events.emit('change', snapshot());
+  const waitForExit = timeoutMs => closed ? Promise.resolve(true) : new Promise(resolve => {
+    const exited = () => { clearTimeout(timer); resolve(true); };
+    const timer = setTimeout(() => { child.removeListener('exit', exited); resolve(false); }, timeoutMs);
+    child.once('exit', exited);
+  });
+  function settleUnknown(code) {
+    if (closed) return;
+    faulted = true;
+    state = 'unavailable';
+    if (pending) {
+      pending.state = pending.attempted ? 'unknown' : 'cancelled';
+      clearTimeout(pending.timer); pending.reject(failure(pending.attempted ? 'claude_guidance_unknown' : code));
+      events.emit('receipt', { requestId: pending.id, session, state: pending.state, code });
+    }
+    publish();
+  }
+  function consume(row) {
+    if (closed || faulted) return;
+    if (row.session_id !== undefined && row.session_id !== session) { settleUnknown('claude_stream_session_mismatch'); return; }
+    if (row.type === 'control_request') {
+      if (typeof row.request_id !== 'string' || !row.request_id || row.request_id.length > 200 || control) { settleUnknown('claude_stream_control_invalid'); return; }
+      // No response is synthesized. Only an explicit controller/UI decision may
+      // answer this exact request; unsupported controls remain visibly blocked.
+      control = { id: row.request_id, request: row.request };
+      state = 'awaiting_permission'; events.emit('control', structuredClone(control)); publish(); return;
+    }
+    if (row.type === 'system' && row.subtype === 'init' && row.model && row.model !== model) {
+      settleUnknown('claude_stream_model_mismatch'); return;
+    }
+    if (row.type === 'user') {
+      const parts = row.message?.content;
+      // Native tool results share the user envelope but are not human-input
+      // acknowledgements. Accept only results for this turn's observed calls.
+      if (pending && row.session_id === session && Array.isArray(parts) && parts.length &&
+          parts.every(part => part?.type === 'tool_result' && toolUses.has(part.tool_use_id))) {
+        events.emit('toolResult', { requestId: pending.id, session }); return;
+      }
+      const request = requests.get(row.uuid);
+      if (!request || request !== pending || row.session_id !== session || row.parent_tool_use_id != null || userText(row.message?.content) !== request.text) {
+        settleUnknown('claude_stream_receipt_mismatch'); return;
+      }
+      request.state = 'received'; clearTimeout(request.timer);
+      const receipt = { state: 'received', requestId: request.id, session, pid: child.pid, providerReceiptConfirmed: true, providerExecutionConfirmed: false };
+      request.receipt = receipt; request.resolve(receipt); events.emit('receipt', receipt); publish(); return;
+    }
+    if (row.type === 'assistant' && pending) {
+      if (row.session_id !== session) { settleUnknown('claude_stream_session_mismatch'); return; }
+      pending.executionObserved = true;
+      for (const part of row.message?.content || []) if (part?.type === 'tool_use' && typeof part.id === 'string') toolUses.add(part.id);
+      events.emit('assistant', { requestId: pending.id, session, message: row.message }); return;
+    }
+    if (row.type === 'result' && pending) {
+      if (row.session_id !== session || pending.state !== 'received') { settleUnknown('claude_stream_receipt_mismatch'); return; }
+      const request = pending;
+      request.state = row.is_error ? 'failed' : 'completed';
+      request.result = { state: request.state, session, requestId: request.id,
+        providerReceiptConfirmed: true, providerExecutionConfirmed: request.executionObserved === true,
+        result: typeof row.result === 'string' ? row.result.slice(0, 131072) : null, isError: row.is_error === true };
+      pending = null; control = null; state = 'idle'; events.emit('result', request.result); publish();
+      toolUses.clear();
+    }
+  }
+  child.stdout.on('data', chunk => {
+    if (faulted || closed) return;
+    buffer = Buffer.concat([buffer, chunk]);
+    if (buffer.length > maxLineBytes && buffer.indexOf(10) < 0) { settleUnknown('claude_stream_output_limit'); return; }
+    let at;
+    while ((at = buffer.indexOf(10)) >= 0) {
+      const line = buffer.subarray(0, at); buffer = buffer.subarray(at + 1);
+      if (line.length > maxLineBytes) { settleUnknown('claude_stream_output_limit'); return; }
+      if (!line.length) continue;
+      try { consume(JSON.parse(line.toString('utf8'))); }
+      catch { settleUnknown('claude_stream_protocol_invalid'); return; }
+    }
+  });
+  child.stderr.on('data', () => { stderrSeen = true; });
+  child.stdin.on('error', () => settleUnknown('claude_stream_input_closed'));
+  child.on('error', () => settleUnknown('claude_stream_spawn_failed'));
+  child.on('exit', () => { settleUnknown('claude_stream_exited'); closed = true; state = 'closed'; publish(); });
+  await new Promise((resolve, reject) => {
+    const failed = () => { child.removeListener('spawn', spawned); reject(failure('claude_stream_spawn_failed')); };
+    const spawned = () => { child.removeListener('error', failed); if (closed) reject(failure('claude_stream_exited')); else resolve(); };
+    child.once('spawn', spawned); child.once('error', failed);
+  });
+  state = 'idle'; publish();
+  return Object.assign(events, {
+    snapshot,
+    async send({ requestId, text, beforeWrite = async () => {} }) {
+      if (!UUID.test(requestId || '') || typeof text !== 'string' || !text.trim() || text.length > 8192) throw failure('claude_guidance_invalid');
+      const previous = requests.get(requestId);
+      if (previous) {
+        if (previous.digest !== digest(text)) throw failure('claude_guidance_conflict');
+        if (previous.receipt) return previous.receipt;
+        throw failure(previous.state === 'unknown' ? 'claude_guidance_unknown' : 'claude_guidance_pending');
+      }
+      if (closed || state === 'unavailable' || !child.stdin.writable) throw failure('claude_stream_unavailable');
+      if (pending || control || state !== 'idle') throw failure('claude_stream_busy');
+      // Reserve the writer before awaiting the caller's final authorization.
+      state = 'authorizing'; publish();
+      try { await beforeWrite(); } catch (error) { if (state === 'authorizing') state = 'idle'; publish(); throw error; }
+      if (closed || state !== 'authorizing' || !child.stdin.writable) throw failure('claude_stream_unavailable');
+      const request = { id: requestId, text, digest: digest(text), state: 'submitting', attempted: false };
+      const received = new Promise((resolve, reject) => { request.resolve = resolve; request.reject = reject; });
+      requests.set(requestId, request); pending = request; state = 'working';
+      request.timer = setTimeout(() => settleUnknown('claude_stream_receipt_timeout'), receiptTimeoutMs);
+      request.timer.unref?.();
+      request.attempted = true;
+      try { child.stdin.write(JSON.stringify({ type: 'user', uuid: requestId, session_id: session, parent_tool_use_id: null,
+        message: { role: 'user', content: text } }) + '\n'); }
+      catch { settleUnknown('claude_stream_input_closed'); }
+      publish(); return received;
+    },
+    result: requestId => requests.get(requestId)?.result ?? null,
+    pendingControl: () => control ? structuredClone(control) : null,
+    freeze: code => settleUnknown(code || 'claude_stream_cleanup_unknown'),
+    closeInput: () => { child.stdin.end(); },
+    waitForExit: (timeoutMs = 1000) => waitForExit(timeoutMs),
+    async terminate({ beforeSignal, timeoutMs = 1000 }) {
+      settleUnknown('claude_stream_stopped'); child.stdin.end();
+      for (const signal of ['SIGINT', 'SIGTERM', 'SIGKILL']) {
+        if (closed) return;
+        await beforeSignal();
+        if (closed) return;
+        child.kill(signal);
+        if (await waitForExit(timeoutMs)) return;
+      }
+      throw failure('claude_stream_cleanup_unknown');
+    },
+    async stop({ beforeStop = async () => {} } = {}) {
+      await beforeStop();
+      if (closed) return;
+      // This signals only the process whose stdin this transport created.
+      // Any attempted message remains unknown; stopping never authorizes retry.
+      settleUnknown('claude_stream_stopped');
+      child.kill('SIGINT');
+      await new Promise(resolve => { const timer = setTimeout(resolve, 5000); timer.unref?.();
+        child.once('exit', () => { clearTimeout(timer); resolve(); }); });
+    },
+    async decide({ controlRequestId, allow, beforeWrite = async () => {} }) {
+      if (typeof allow !== 'boolean' || !control || control.id !== controlRequestId || state !== 'awaiting_permission' ||
+          control.request?.subtype !== 'can_use_tool') throw failure('claude_stream_control_changed');
+      if (control.request.requires_user_interaction === true || control.request.tool_name === 'AskUserQuestion') throw failure('claude_stream_control_interaction_required');
+      const current = control;
+      await beforeWrite();
+      if (control !== current || closed || state !== 'awaiting_permission') throw failure('claude_stream_control_changed');
+      child.stdin.write(JSON.stringify({ type: 'control_response', response: { subtype: 'success', request_id: current.id,
+        response: allow ? { behavior: 'allow', updatedInput: current.request.input } : { behavior: 'deny', message: 'The user declined this tool request.' } } }) + '\n');
+      control = null; state = pending ? 'working' : 'idle'; publish();
+    },
+    async close() {
+      if (closed) return;
+      settleUnknown('claude_stream_closing');
+      child.stdin.end();
+      // EOF is an orderly disconnect, not proof of exit. Only the owner can
+      // escalate with a fresh process-identity guard; keep unknown/busy if EOF
+      // does not reap this child.
+      if (!await waitForExit(5000)) throw failure('claude_stream_cleanup_unknown');
+    },
+  });
+}

package/src/session-supervision/codex-app-server.js

@@ -1,3 +1,4 @@
+import {collectNativeTurnObservation} from './native-turn-observer.js';
 import { agentRole } from '../codex-plugins/simy/hooks/loop-kernel.mjs';
 import { captureAcceptanceReads } from './acceptance-reads.js';
 import { providerFailureDiagnostic } from './provider-failure.js';
@@ -40,6 +41,11 @@ const ANALYSIS_MAX_WIRE_LINE = 8 * 1024 * 1024;
 // conversation. Explicit bindings remain visible through discoverSessions.
 const SOURCE_KINDS = ['cli', 'vscode', 'appServer'];
 
+// A cold app-server can expose another process's live turn as interrupted
+// before it has a terminal timestamp. Such a summary is not a settled boundary.
+const runningTurn = turn => ['inProgress', 'in_progress'].includes(turn?.status) ||
+  turn?.status === 'interrupted' && turn.completedAt === null;
+
 export class CodexAppServerError extends Error {
   constructor(code, message, diagnostic) {
     super(message);
@@ -427,7 +433,7 @@ export async function readCodexObservation(client, session, { deadline = Date.no
   try {
     const page = await client.request('thread/turns/list', { threadId: session, cursor: null, limit: 1, sortDirection: 'desc', itemsView: 'notLoaded' }, timeout());
     if (Array.isArray(page?.data) && page.data.length === 1 && ['inProgress', 'completed', 'interrupted', 'failed'].includes(page.data[0]?.status)) {
-      observation.isRunning = page.data[0].status === 'inProgress';
+      observation.isRunning = runningTurn(page.data[0]);
       if (typeof page.data[0].id === 'string' && page.data[0].id && page.data[0].id.length <= 160) observation.latestTurnId = page.data[0].id;
     }
   } catch (error) {
@@ -549,7 +555,7 @@ export async function readCodexConversation(candidate, { openClient = openCodexA
     if (metadata.cwd !== candidate.cwd) throw new CodexAppServerError('identity', 'Exact conversation identity is unavailable.');
     const providerGoal = await readCodexGoal(client, candidate.session);
     if (signal?.aborted) throw new CodexAppServerError('cancelled', 'Conversation analysis was cancelled.');
-    const terminal = turn => ['completed', 'interrupted', 'failed'].includes(turn?.status);
+    const terminal = turn => ['completed', 'interrupted', 'failed'].includes(turn?.status) && !runningTurn(turn);
     const turns = [];
     const turnIds = new Set(), cursors = new Set();
     let pageSize = ANALYSIS_PAGE_SIZE;
@@ -625,8 +631,8 @@ export async function readCodexConversation(candidate, { openClient = openCodexA
     // A display summary omits intermediate reasoning/tool context even when
     // every turn fits. Never represent it as the complete conversation; the
     // classifier must establish a self-contained objective from retained text.
-    const awaitingTurn = latestMetadata.isRunning === true || [...turns, ...verificationTurns].some(turn => ['inProgress', 'in_progress'].includes(turn?.status));
-    let incomplete = !settled.length || turns.some(turn => !terminal(turn) && !['inProgress', 'in_progress'].includes(turn?.status)), truncated = true;
+    const awaitingTurn = latestMetadata.isRunning === true || [...turns, ...verificationTurns].some(runningTurn);
+    let incomplete = !settled.length || turns.some(turn => !terminal(turn) && !runningTurn(turn)), truncated = true;
     for (const [index, turn] of settled.toReversed().entries()) {
       if (turn.itemsView === 'notLoaded') { truncated = true; if (turn === boundary) incomplete = true; continue; }
       if (turn.itemsView !== 'summary') throw new CodexAppServerError('context_unavailable', 'Codex did not return the requested conversation summaries.');
@@ -931,7 +937,12 @@ export async function executeCodexAppServer(record, { webOrigin, openClient = op
       const observations = run.managed.purpose?.enabled ? await observeExternal(run.managed, { cwd: executionCwd, signal,
         authorize: authorizeObservation,
         networkAllowed: observationNetworkAllowed }) : [];
-      reviewObservations = [...(run.managed.purpose?.evidence?.observations || []), ...observations].filter(item => Date.now() - item.at < 60_000);
+      const nativeObservations = reviewing ? await collectNativeTurnObservation(record, {root, client, signal, authorize: authorizePreparation}) : [];
+      reviewObservations = [...(run.managed.purpose?.evidence?.observations || []).filter(item => item.kind !== 'codex_native_history'), ...observations, ...nativeObservations].filter(item => Date.now() - item.at < 60_000);
+      if (nativeObservations.length) {
+        const evidence = {source: 'adapter_capture', actionId: decision.id, observations: nativeObservations};
+        await onEvidence(evidence); retainControllerEvidence(run.managed, evidence, Date.now());
+      }
       if (observations.length) {
         const evidence = { source: 'adapter_capture', actionId: decision.id, observations };
         await onEvidence(evidence);
@@ -1091,11 +1102,11 @@ export async function executeCodexAppServer(record, { webOrigin, openClient = op
             if (operationContext) {
               const currentManaged = root ? (await readRecord(root, record.provider, record.session))?.run?.managed : run.managed;
               if (reviewOperationContext(currentManaged || {})?.digest !== operationContext.digest)
-                throw new CodexAppServerError('cancelled', 'Captured operation history changed during review.');
+                throw new CodexAppServerError('review_history_changed', 'Captured operation history changed during review.');
             }
             const freshContext = await readCodexConversation(record, { openClient, signal });
             if (JSON.stringify(freshContext) !== JSON.stringify(sourceContext))
-              throw new CodexAppServerError('cancelled', 'Original conversation changed during answer review.');
+              throw new CodexAppServerError('review_context_changed', 'Original conversation changed during answer review.');
             const native = await readCodexSession(client, record.session, { signal });
             if (native.model !== run.managed.resumeModel || !native.nativeSandbox || !sameSandboxRights(native.nativeSandbox, dispatchMetadata.nativeSandbox))
               throw new CodexAppServerError('permission_narrowed', 'Original provider context changed during answer review.');
@@ -1165,7 +1176,18 @@ export async function executeCodexAppServer(record, { webOrigin, openClient = op
         if (localReads.some(prior => !fresh.some(item => item.id === prior.id && item.digest === prior.digest))) { review.passed = false; review.needsHuman = false; review.findings.push('An original file predicate changed during independent review; inspect its current result.'); localReads = []; }
         else localReads = fresh.filter(item => localReads.some(prior => prior.id === item.id && prior.digest === item.digest));
       }
-      review = assessIndependentInspection(review, { toolEvidence, observations: [...reviewObservations, ...localReads], criteria: effectiveAcceptanceCriteria(run.managed), flexible: flexibleReasoning(run.managed) });
+      if (reviewObservations.some(item => item.kind === 'codex_native_history')) {
+        const before = reviewObservations.filter(item => item.kind === 'codex_native_history');
+        const fresh = await collectNativeTurnObservation(record, {root, client, signal, authorize: authorizePreparation});
+        if (before.some(prior => prior.status !== 'observed' || !fresh.some(item => item.id === prior.id && item.status === 'observed' && item.digest === prior.digest))) {
+          review.passed = false; review.needsHuman = false;
+          review.findings.push('The complete original native turn history changed or became unavailable during review; inspect its actual current result without replaying the operation.');
+        }
+        reviewObservations = [...reviewObservations.filter(item => item.kind !== 'codex_native_history'), ...fresh];
+        const evidence = {source: 'adapter_capture', actionId: decision.id, reviewBatch: true, observations: reviewObservations};
+        await onEvidence(evidence); retainControllerEvidence(run.managed, evidence, Date.now());
+      }
+      review = assessIndependentInspection(review, { toolEvidence, observations: [...reviewObservations, ...localReads], criteria: effectiveAcceptanceCriteria(run.managed), flexible: flexibleReasoning(run.managed), record });
       review = await bindCompletionArtifacts(record, { ...review, workspaceDigest: boundAfter }, { authorize: authorizePreparation, signal });
       await checkAnswerContext?.();
       return { code: 0, dispatchAttemptId, verification: { ...review, contractDigest, source: 'independent_codex_session', session: targetSession, workspaceDigest: boundAfter }, usage, toolEvidence };

package/src/session-supervision/codex-app-tools-connection.js

@@ -0,0 +1,30 @@
+import {openAppTools} from '../codex-plugins/simy/native/app-tools.mjs';
+import {createHash,randomUUID} from 'node:crypto';
+import {stat,readFile,writeFile,mkdir,rename,realpath} from 'node:fs/promises';
+import {join,isAbsolute,dirname} from 'node:path';
+import {readRecord,automaticContinuationAllowed} from '../codex-plugins/simy/hooks/delivery-loop.mjs';
+const NODE='/Applications/ChatGPT.app/Contents/Resources/cua_node/bin/node';
+const SERVER='/Applications/ChatGPT.app/Contents/Resources/plugins/openai-bundled/plugins/codex-app-tools/server.mjs';
+const fail=code=>Object.assign(new Error(code),{code});
+const file=(root,session)=>join(root,'native-app-connections',createHash('sha256').update(session).digest('hex')+'.json');
+const identity=async path=>{const s=await stat(path);return [s.dev,s.ino,s.size,s.mtimeMs];};
+async function ownedPipe(path){if(!isAbsolute(path||''))throw fail('native_tools_attachment_missing');const s=await stat(path);if(!s.isSocket()||s.uid!==process.getuid())throw fail('native_tools_owner_mismatch');}
+export async function registerCodexAppToolsConnection({root,session,env=process.env}){
+ if(env.CODEX_THREAD_ID!==session)throw fail('native_tools_caller_mismatch');
+ await ownedPipe(env.CODEX_APP_TOOLS_PIPE_PATH);
+ const record=await readRecord(join(root,'delivery-hooks'),'codex',session);
+ if(!record?.run?.managed||!automaticContinuationAllowed(record))throw fail('native_tools_consent_required');
+ const attachment={schema:1,session,runId:record.run.id,taskId:record.run.managed.taskId,epoch:record.autoContinueEpoch,
+  pipe:env.CODEX_APP_TOOLS_PIPE_PATH,nodeIdentity:await identity(NODE),serverIdentity:await identity(SERVER),registeredAt:Date.now()};
+ const target=file(root,session);await mkdir(dirname(target),{recursive:true,mode:0o700});const temp=target+'.'+randomUUID();
+ await writeFile(temp,JSON.stringify(attachment),{mode:0o600});await rename(temp,target);
+ return {registered:true,session,runId:attachment.runId,taskId:attachment.taskId};
+}
+export async function openRegisteredCodexAppTools({root,record,signal}){
+ let a;try{a=JSON.parse(await readFile(file(dirname(root),record.session),'utf8'));}catch(e){if(e.code==='ENOENT')return null;throw e;}
+ if(a.schema!==1||a.session!==record.session||a.runId!==record.run.id||a.taskId!==record.run.managed.taskId||a.epoch!==record.autoContinueEpoch)throw fail('native_tools_attachment_changed');
+ if(await realpath(process.execPath)!==await realpath(NODE))throw fail('native_tools_runtime_required');
+ await ownedPipe(a.pipe);
+ if(JSON.stringify(await identity(NODE))!==JSON.stringify(a.nodeIdentity)||JSON.stringify(await identity(SERVER))!==JSON.stringify(a.serverIdentity))throw fail('native_tools_app_changed');
+ return openAppTools({record,signal,node:NODE,server:SERVER,pipe:a.pipe});
+}

package/src/session-supervision/conversation-presentation.js

@@ -1,3 +1,4 @@
+import {sessionGuidancePresentation} from './session-guidance.js';
 import { sessionWorkState, sessionWorkOwnership } from './work-state.js';
 import { deliveryDecisionRevision } from '../codex-plugins/simy/hooks/delivery-loop.mjs';
 import { pauseOrigin } from './autonomous-upgrade.js';
@@ -200,6 +201,7 @@ export function conversationPresentation(candidate = {}, projectedRun, { rawReco
     source(lastRaw?.result?.summary || lastRaw?.summary, 'record.run.managed.workHistory');
   return { schemaVersion: 1, target,
     readiness: ready, recovery, plan,
+    ...(managed.nativeConnectionObservation || managed.userGuidance ? {guidance: sessionGuidancePresentation(candidate, sameRaw ? rawRecord : null, now)} : {}),
     now: { state: text(work.state, 64), ownership, label: text(work.label, 200),
       reason: source(work.reason, 'candidate.workState.reason'), stale: work.stale === true, checkedAt: time(work.checkedAt), ownershipObservedAt: time(work.ownershipObservedAt), providerExecutionConfirmed: executionObserved },
     next: { ...(next || { text: null, source: null, truncated: false }), ...(nextCopy ? { copy: nextCopy } : {}), owner: nextOwner,