@awak-app/simy-cli 0.7.15 → 0.7.17

package/src/orchestrator/recovery.js

@@ -1,4 +1,4 @@
-import { suggestedProviderTokenBudget } from "./budget.js";
+import { suggestedProviderTokenBudget, MAX_PROVIDER_TOKEN_BUDGET } from "./budget.js";
 
 const RECOVERABLE_STATES = new Set(["waiting_human", "blocked", "failed"]);
 
@@ -13,7 +13,7 @@ export function recoveryContractForEvent({ snapshot, state, message, detail = {}
     schema_version: 1,
     state,
     reason_code: reasonCode,
-    user_message: recoveryMessage(reasonCode),
+    user_message: isSafetyCeiling(reasonCode) ? safetyCeilingRecoveryMessage(reasonCode, detail.budget) : recoveryMessage(reasonCode),
     primary_action_id: actions[0].id,
     actions,
     technical_details: {
@@ -22,6 +22,9 @@ export function recoveryContractForEvent({ snapshot, state, message, detail = {}
       max_attempts: positiveInteger(snapshot?.charter?.max_attempts),
       provider_token_budget: positiveInteger(snapshot?.charter?.token_budget),
       provider_tokens_used: nonNegativeInteger(detail?.budget?.tokens_used),
+      provider_token_ceiling: positiveInteger(detail?.budget?.hard_token_ceiling),
+      attempt_ceiling: positiveInteger(detail?.budget?.hard_attempt_ceiling),
+      continuation_policy: clean(detail?.budget?.continuation_policy) || null,
       token_budget: positiveInteger(snapshot?.charter?.token_budget),
       retry_budget: nonNegativeInteger(snapshot?.charter?.retry_budget),
       tokens_used: nonNegativeInteger(detail?.budget?.tokens_used),
@@ -115,6 +118,7 @@ function recoveryReasonCode(state, message, detail) {
     return "retry_strategy_unchanged";
   }
   if (code === "outcome_assessment_unavailable") return "outcome_assessment_unavailable";
+  if (["provider_token_ceiling_reached", "attempt_ceiling_reached"].includes(code)) return code;
   if (code === "token_budget_exhausted") return "token_budget_exhausted";
   if (code === "retry_budget_exhausted") return "retry_budget_exhausted";
   const findings = strings(detail.finding_codes);
@@ -138,6 +142,25 @@ function recoveryReasonCode(state, message, detail) {
   return "local_orchestration_failed";
 }
 
+function isSafetyCeiling(code) {
+  return ["provider_token_ceiling_reached", "attempt_ceiling_reached"].includes(code);
+}
+
+export function safetyCeilingRecoveryMessage(code, budget = {}) {
+  const token = code === "provider_token_ceiling_reached";
+  const limit = token ? budget?.hard_token_ceiling : budget?.hard_attempt_ceiling;
+  const used = token ? budget?.tokens_used : (budget?.retries_used ?? 0) + 1;
+  const maximum = token ? MAX_PROVIDER_TOKEN_BUDGET : 100;
+  const base = `SIMY retained this same run's work and usage. The ${token ? "Provider token" : "executor attempt"} safety ceiling prevents another call. Increasing a notification threshold alone does not permit another call. `;
+  if (budget?.continuation_policy !== "progress") {
+    return base + "The bounded policy does not permit a same-run safety extension. Keep this run and review its remaining acceptance conditions with the operator; guidance alone cannot resume provider work.";
+  }
+  if (!Number.isFinite(limit) || !Number.isFinite(used) || limit >= maximum || used >= maximum) {
+    return base + `The validated maximum is ${maximum.toLocaleString("en-US")}; no larger same-run ceiling is available. Preserve evidence and review remaining work with the operator; guidance alone cannot resume provider work.`;
+  }
+  return base + `Review remaining acceptance conditions and explicitly increase the relevant ceiling above both recorded usage and its current limit, up to ${maximum.toLocaleString("en-US")}. Then continue this same run. Extension never resets usage or resumes work, and other approvals remain required.`;
+}
+
 function recoveryMessage(reasonCode) {
   const messages = {
     repository_authorization_required:
@@ -198,6 +221,13 @@ function recoveryActions(reasonCode, budget = null) {
       newRunAction(),
     ];
   }
+  if (isSafetyCeiling(reasonCode)) {
+    return [guidanceAction(
+      "review_safety_ceiling",
+      "Review this run's safety ceiling",
+      safetyCeilingRecoveryMessage(reasonCode, budget),
+    )];
+  }
   if (reasonCode === "token_budget_exhausted") {
     const suggestedBudget = suggestedProviderTokenBudget(budget);
     if (!suggestedBudget || budget?.retry_exhausted === true) return [newRunAction()];

package/src/orchestrator/ux-specification.js

@@ -1,3 +1,4 @@
+import { experienceInstruction } from '../codex-plugins/simy/hooks/user-experience.mjs';
 import { fileURLToPath } from "node:url";
 import { section } from "./shared.js";
 
@@ -5,16 +6,6 @@ export const UX_SPECIFICATION_PATH = fileURLToPath(
   new URL("./delivery/references/ux-specification.md", import.meta.url),
 );
 
-export function buildUxSpecificationInstruction({ auditor = false } = {}) {
-  return section("ux_specification_contract", [
-    `Apply the same behavioral-completeness standard throughout requirements, design, implementation mapping, verification, review, release, closure and handoff. Read: ${UX_SPECIFICATION_PATH}`,
-    "Describe observable interaction units, not feature inventories. Reuse stable acceptance IDs. For each unit specify actor/goal, context/preconditions, trigger/reachable entry, perceived information, available action/choice/control, system response/state transition, usable outcome/postconditions, next action/handoff, alternative/failure/recovery paths, and verification oracle/provenance. Treat these as semantic obligations in the existing specification, not new CLI JSON fields.",
-    "Decompose when actor, precondition, decision, observable state, postcondition or recovery differs materially, or when any clause could fail independently. Link predecessors/successors and preserve end-to-end criteria. Derive branches and applicable constraints from authoritative requirements and observed system boundaries; do not invent scenarios, defaults, thresholds or product policy to fill gaps.",
-    "Description is sufficient only when another implementer can derive the intended behavior and an independent verifier can determine pass/fail without guessing a material requirement. Review source coverage, causal continuity, branch closure, controllability, observability, traceability, consistency and epistemic separation. Word count, row count and verbosity are not quality thresholds.",
-    "Keep required/intended/observed/assumed/unknown distinct. Unknown facts stay explicit with affected IDs and resolution evidence; a reversible missing requirement decision is resolved by grounded AI inference and a recorded assumption, while missing runtime evidence blocks the affected verification claim. Genuine non-applicability needs a source and reason, not an empty cell.",
-    "Persist the complete contract in the canonical specification and link the same IDs from summaries, matrices, PRs and receipts. Summaries may shorten repetition but must not replace or drop behavioral obligations, unresolved gaps or evidence. A phase change revalidates affected descriptions and results; plans never become observed proof by wording alone.",
-    auditor
-      ? "Remain read-only. Independently derive coverage from original sources, identify any material behavior that still requires guessing, and report affected criterion IDs and required clarification/evidence as findings. Do not infer completeness from filled fields or copied executor claims."
-      : "Before dependent implementation, resolve material specification ambiguity with source research, a reversible default and verification; reserve needs_decision for irreversible or explicitly user-reserved decisions; continue independent work. Before verification or completion, repair missing descriptions/evidence rather than relabeling incomplete UX as complete. This procedural contract does not add automatic schema or GitHub enforcement.",
-  ].join("\n"));
+export function buildUxSpecificationInstruction() {
+  return section("requested_outcome", experienceInstruction + '\n' + 'Make the requested experience easy, accurate and concise. Resolve material ambiguity by inspecting the existing product and trying a reversible change. Exercise the actual user flow, including relevant errors and recovery. Specify only what helps implementation or use; no compulsory interaction-unit forms, traceability matrices or twelve-view reviews.');
 }

package/src/provider-delegation.js

@@ -0,0 +1,336 @@
+import { StringDecoder } from 'node:string_decoder';
+import { isAbsolute } from 'node:path';
+import { matchesPairedNativeAccount } from './native-provider-identity.js';
+import { readRecord } from './codex-plugins/simy/hooks/delivery-loop.mjs';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { readClaudeSession } from './session-supervision/claude-sessions.js';
+import { EventEmitter } from 'node:events';
+import { PassThrough } from 'node:stream';
+import { realpath } from 'node:fs/promises';
+import { PROVIDER_LINKS } from './provider-links.js';
+import { normalizeProviderModelSelection } from './provider-model-selection.js';
+import { resolveDesktopExecutorCommand } from './desktop-executor.js';
+import { openCodexAppServer, readCodexSession } from './session-supervision/codex-app-server.js';
+
+const NATIVE_SESSION_MODES = Object.freeze({ codex: 'existing', claude: 'fork' });
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const fail = code => Object.assign(new Error(`Provider delegation unavailable: ${code}.`), { code });
+const identifier = value => typeof value === 'string' && value.trim() && value.length <= 256;
+
+// Routing identifiers and provider-reported account email, never credentials. API models stay in Crew's
+// registry/gateway and SIMY conversation; this native adapter does not invent
+// local executables or sessions for them.
+export function normalizeProviderDelegation(value, { provider, model } = {}) {
+  if (value == null) return null;
+  if (!value || typeof value !== 'object' || Array.isArray(value) ||
+      value.schema_version !== 'provider_delegation.v1' || value.provider !== provider ||
+      value.model !== model || !identifier(value.model) || !identifier(value.origin_task_id) ||
+      !identifier(value.origin_conversation_id) || !identifier(value.request_id) ||
+      !identifier(value.account_id) || !UUID.test(value.session_id || '') ||
+      !['existing', 'fork'].includes(value.session_mode)) throw fail('invalid_provider_delegation');
+  normalizeProviderModelSelection({ model: value.model });
+  if (!PROVIDER_LINKS.includes(provider)) throw fail('crew_gateway_required');
+  if (!Object.hasOwn(NATIVE_SESSION_MODES, provider)) throw fail('native_adapter_unavailable');
+  if (provider === 'claude' && value.session_mode !== 'fork') throw fail('claude_exact_session_writer_unavailable');
+  if (provider === 'claude' && value.allow_new_task !== true) throw fail('new_task_permission_required');
+  if (provider === 'codex' && value.session_mode !== 'existing') throw fail('unsupported_session_mode');
+  return Object.freeze(Object.fromEntries(['schema_version', 'provider', 'model', 'account_id', 'session_id', 'session_mode',
+    'origin_task_id', 'origin_conversation_id', 'request_id', 'allow_new_task', 'allow_new_task_request_id'].filter(key => value[key] !== undefined).map(key => [key, value[key]])));
+}
+
+// Accept P01's exact target shape at the existing Local Task boundary. A
+// target alone carries no task/session execution authority and cannot silently
+// fall back to a fresh native invocation.
+export function providerDelegationFromRequest(body, requestId) {
+  const target = body.delegation_target;
+  if (!body.delegation) {
+    if (target) throw fail('delegation_context_required');
+    return null;
+  }
+  const value = { ...body.delegation };
+  if (target) {
+    if (target.transport !== 'native') throw fail('crew_gateway_required');
+    for (const field of ['provider', 'model', 'account_id', 'session_id']) {
+      if (value[field] !== undefined && value[field] !== target[field]) throw fail('delegation_target_mismatch');
+      value[field] = target[field];
+    }
+  }
+  if (value.request_id !== requestId) throw fail('delegation_request_mismatch');
+  const normalized = normalizeProviderDelegation(value, { provider: body.backend, model: body.model });
+  if (body.native_identity && normalized.session_mode === 'fork' && normalized.allow_new_task_request_id !== requestId)
+    throw fail('native_new_task_permission_required');
+  return normalized;
+}
+
+export function providerDelegationTarget(value) {
+  return value ? Object.fromEntries(['provider', 'model', 'account_id', 'session_id'].map(key => [key, value[key]]).concat([['transport', 'native']])) : null;
+}
+
+export function providerDelegationCoverage(capabilities = []) {
+  return capabilities.map(item => {
+    const native = item.transport !== 'api' && PROVIDER_LINKS.includes(item.provider);
+    const mode = Object.hasOwn(NATIVE_SESSION_MODES, item.provider) ? NATIVE_SESSION_MODES[item.provider] : null;
+    return { provider: item.provider, readiness: item.readiness,
+      execution_target: native ? 'local' : 'crew_gateway',
+      session_mode: native ? mode : 'simy_context',
+      ...(native && mode ? { supported_session_modes: [mode],
+        continuation_mode: mode === 'existing' ? 'same_session' : 'fresh_explicit_fork',
+        cancel_scope: mode === 'existing' ? 'owned_turn' : 'owned_fork_process',
+        disconnect_recovery: 'hold_unknown_without_replay' } : {}),
+      limitation: !native ? 'requires_crew_gateway' : !mode ? 'native_adapter_unavailable' :
+        item.provider === 'claude' ? 'exact_session_writer_unavailable' : null };
+  });
+}
+
+export async function resolveDelegatedProviderCommand(input, { openClient = openCodexAppServer,
+  resolveCommand = resolveDesktopExecutorCommand, readClaude = readClaudeSession,
+  supervisionRoot, pairedDeviceId, providerLinkEpoch,
+  onWorkspaceAuthorized = null,
+  readSupervision = target => readRecord(supervisionRoot, target.provider, target.session_id),
+  inspectClaudeAccount = async bin => JSON.parse((await promisify(execFile)(bin, ['auth', 'status', '--json'], { timeout: 5000, maxBuffer: 65536 })).stdout) } = {}) {
+  const selection = normalizeProviderDelegation(input.delegation, { provider: input.backend, model: input.model });
+  const accountMatches = email => input.nativeIdentity ? matchesPairedNativeAccount(input.nativeIdentity,
+    { deviceId: pairedDeviceId, provider: selection.provider, email, connectionEpoch: providerLinkEpoch ?? null }) && input.nativeIdentity.account_id === selection.account_id
+    : email === selection.account_id;
+  if (!selection) return resolveCommand(input);
+  let claudeCommand;
+  if (selection.provider === 'claude') {
+    if (input.nativeIdentity && selection.allow_new_task_request_id !== selection.request_id) throw fail('new_task_permission_required');
+    claudeCommand = await resolveCommand(input);
+    if (claudeCommand.verification === 'explicit_command_override') throw fail('provider_selection_unverifiable');
+    // Keep ordinary provider approval. Never use the desktop adapter's legacy
+    // skip-permissions flag for a delegation.
+    claudeCommand.args = ['-p', input.instruction, '--output-format', 'stream-json', '--verbose',
+      '--model', selection.model, '--resume', selection.session_id, '--fork-session',
+      '--permission-mode', input.permissionMode === 'read_only' ? 'plan' : 'default'];
+  }
+  return { bin: 'codex-app-server', args: [], env: {}, backend: input.backend,
+    spawn() {
+      const child = new EventEmitter();
+      child.stdout = new PassThrough(); child.stderr = new PassThrough();
+      const controller = new AbortController();
+      let ownedChild;
+      child.kill = signal => {
+        const alreadyAborted = controller.signal.aborted;
+        controller.abort(Object.assign(fail('provider_cancelled'), { nativeSignal: signal || 'SIGINT' }));
+        // Abort invokes the owned Claude listener exactly once. Only a later
+        // escalation forwards another signal; Codex owns an RPC turn instead.
+        if (alreadyAborted) ownedChild?.kill(signal);
+        return true;
+      };
+      // Match the existing process interface; stopLocalTask only signals this
+      // owned turn through kill(), never an original session process.
+      setImmediate(async () => {
+        try {
+          const emit = event => child.stdout.write(`${JSON.stringify(event)}\n`);
+          if (selection.provider === 'claude') await runClaudeDelegation({ ...input, selection,
+            command: claudeCommand, readClaude, inspectClaudeAccount, accountMatches, signal: controller.signal, emit, onChild: value => { ownedChild = value; } });
+          else await runCodexDelegation({ ...input, selection, signal: controller.signal, openClient, emit, readSupervision, accountMatches, onWorkspaceAuthorized });
+          child.stdout.end(); child.stderr.end(); child.emit('close', 0);
+        } catch (error) {
+          const message = fail(error.code || 'provider_result_unknown').message;
+          child.stdout.write(`${JSON.stringify({ type: 'simy.delegation.state', state: error.delegationState || (selection.provider === 'claude' && !ownedChild ? 'failed' : 'result_unknown') })}\n`);
+          child.stdout.end(`${JSON.stringify(selection.provider === 'claude' ?
+            { type: 'result', is_error: true, result: message } : { type: 'turn.failed', error: { message } })}\n`);
+          child.stderr.end(); child.emit('close', 1);
+        }
+      });
+      return child;
+    },
+  };
+}
+
+async function runCodexDelegation({ selection, instruction, getInstruction, repositoryPath, permissionMode, signal, openClient, emit, beforeDispatch, readSupervision, accountMatches, nativeIdentity, workspaceMode, onWorkspaceAuthorized, dispatchNative = send => send() }) {
+  if (signal.aborted) throw Object.assign(fail('provider_cancelled'), { delegationState: 'stopped' });
+  const preserveSupervision = async () => {
+    if ((await readSupervision(selection))?.run) throw fail('existing_supervised_task');
+  };
+  let client;
+  try { await preserveSupervision(); client = await openClient({}); }
+  catch (error) { error.delegationState = 'failed'; throw error; }
+  let turnId, starting, primaryError, completed = false, unsubscribe = () => {};
+  try {
+    signal.throwIfAborted();
+    const account = await client.request('account/read', { refreshToken: false });
+    if (!accountMatches(account.account?.email)) throw fail('provider_account_mismatch');
+    const metadata = await readCodexSession(client, selection.session_id, { signal });
+    if (metadata.isRunning === true) throw fail('provider_session_busy');
+    const configuration = await client.request('thread/resume', { threadId: selection.session_id, excludeTurns: true });
+    if (configuration.thread?.id !== selection.session_id || configuration.model !== selection.model ||
+        !configuration.cwd || await realpath(configuration.cwd) !== await realpath(nativeIdentity ? metadata.cwd : repositoryPath) ||
+        workspaceMode === 'repository' && await realpath(configuration.cwd) !== await realpath(repositoryPath)) throw fail('provider_session_mismatch');
+    // Do not mutate provider permissions. An incompatible requested scope must
+    // be resolved in the original provider, never silently widened here.
+    if (permissionMode === 'read_only' ? configuration.sandbox?.type !== 'readOnly' :
+        configuration.sandbox?.type !== 'workspaceWrite' || configuration.sandbox.networkAccess !== false) throw fail('provider_permission_mismatch');
+    if (configuration.sandbox?.type === 'workspaceWrite') {
+      const roots = configuration.sandbox.writableRoots ?? [];
+      if (!Array.isArray(roots) || roots.some(root => typeof root !== 'string' || !isAbsolute(root))) throw fail('provider_permission_mismatch');
+      await onWorkspaceAuthorized?.([configuration.cwd, ...roots]);
+    }
+    await beforeDispatch?.();
+    signal.throwIfAborted();
+    await preserveSupervision();
+    const currentAccount = await client.request('account/read', { refreshToken: false });
+    if (!accountMatches(currentAccount.account?.email)) throw fail('provider_account_mismatch');
+    await beforeDispatch?.();
+    signal.throwIfAborted();
+    const currentInstruction = getInstruction ? await getInstruction() : instruction;
+    if (typeof currentInstruction !== 'string' || !currentInstruction.trim()) throw fail('provider_instruction_unavailable');
+    await new Promise((resolve, reject) => {
+      let started = false, hasResult = false, settled = false;
+      let cleanup = () => {};
+      const finish = error => {
+        if (settled) return;
+        settled = true; cleanup();
+        if (error) reject(error); else resolve();
+      };
+      const buffered = [];
+      const consume = (method, params, requestId) => {
+        if (settled) return;
+        if (params.threadId !== selection.session_id || (params.turnId || params.turn?.id) !== turnId) return;
+        if (requestId !== undefined) {
+          emit({ type: 'simy.delegation.question', question: { ...params, method }, request_id: requestId });
+          finish(fail('provider_input_required')); return;
+        }
+        if (method === 'item/completed' && params.item?.type === 'agentMessage' && typeof params.item.text === 'string') {
+          hasResult ||= Boolean(params.item.text.trim());
+          emit({ type: 'item.completed', item: { type: 'agent_message', text: params.item.text } });
+        }
+        if (method === 'turn/completed') {
+          completed = true;
+          if (params.turn.status === 'completed' && hasResult) finish();
+          else finish(fail('provider_turn_failed'));
+        }
+      };
+      unsubscribe = client.onNotification((method, params, requestId) => {
+        if (!started) { if (buffered.length < 100) buffered.push([method, params, requestId]); return; }
+        consume(method, params, requestId);
+      });
+      const cancelled = () => finish(fail('provider_cancelled'));
+      signal.addEventListener('abort', cancelled, { once: true });
+      const closed = () => finish(fail('provider_result_unknown'));
+      client.child.once('close', closed);
+      cleanup = () => { signal.removeEventListener('abort', cancelled); client.child.off('close', closed); };
+      // The official provider writer lock acquired by thread/resume arbitrates
+      // races with the original app. No busy fallback, steer, or second task.
+      if (signal.aborted) { finish(fail('provider_cancelled')); return; }
+      starting = dispatchNative(() => client.request('turn/start', { threadId: selection.session_id, model: selection.model,
+        input: [{ type: 'text', text: currentInstruction }] })).then(response => {
+        turnId = response?.turn?.id; started = true;
+        if (!turnId) finish(fail('provider_result_unknown'));
+        else { emit({ type: 'thread.started', thread_id: selection.session_id }); for (const event of buffered) consume(...event); }
+      }, finish);
+    });
+    emit({ type: 'turn.completed' });
+  } catch (error) {
+    primaryError = error;
+    if (!starting || completed) error.delegationState = 'failed';
+    throw error;
+  } finally {
+    unsubscribe();
+    // A cancelled request may have been accepted before its response arrived.
+    // Collect that exact ID before interrupting; never issue another start.
+    if (starting && !turnId) await starting.catch(() => {});
+    if (turnId && !completed && !client.closed) {
+      try {
+        await client.request('turn/interrupt', { threadId: selection.session_id, turnId }, 2000);
+        if (primaryError?.code === 'provider_input_required') primaryError.delegationState = 'needs_user';
+        if (primaryError?.code === 'provider_cancelled') primaryError.delegationState = 'stopped';
+      } catch {
+        if (primaryError) primaryError.delegationState = 'result_unknown';
+      }
+    }
+    // Transport cleanup cannot erase a known terminal result or primary error.
+    try { await client.close(); } catch { /* The submitted turn is never replayed. */ }
+  }
+}
+
+async function runClaudeDelegation({ selection, repositoryPath, command, readClaude,
+  inspectClaudeAccount, signal, emit, beforeDispatch, onChild, accountMatches, nativeIdentity, workspaceMode, dispatchNative = send => send() }) {
+  signal.throwIfAborted();
+  const metadata = await readClaude(selection.session_id);
+  if (!metadata?.cwd || (!nativeIdentity || workspaceMode === 'repository') && await realpath(metadata.cwd) !== await realpath(repositoryPath)) throw fail('provider_session_mismatch');
+  const nativeCwd = await realpath(metadata.cwd);
+  const account = await inspectClaudeAccount(command.bin);
+  if (account.loggedIn !== true || !accountMatches(account.email)) throw fail('provider_account_mismatch');
+  await beforeDispatch?.();
+  signal.throwIfAborted();
+  // Recheck the official identity after asynchronous lease/link guards, just as
+  // the Codex adapter does. A selected account cannot change while waiting.
+  const currentAccount = await inspectClaudeAccount(command.bin);
+  if (currentAccount.loggedIn !== true || !accountMatches(currentAccount.email)) throw fail('provider_account_mismatch');
+  await beforeDispatch?.();
+  signal.throwIfAborted();
+  await new Promise((resolve, reject) => {
+    let pending = '', terminal = false, nativeSession = null, question = false, terminalFailed = false, invalidStream = false, settled = false;
+    const decoder = new StringDecoder('utf8');
+    const child = dispatchNative(() => command.spawn(command.bin, command.args, { cwd: nativeCwd,
+      env: { ...process.env, ...command.env }, stdio: ['ignore', 'pipe', 'pipe'] }));
+    // This is only the newly forked process; the original owner is never signalled.
+    onChild?.(child);
+    const cancel = () => child.kill(signal.reason?.nativeSignal || 'SIGINT');
+    signal.addEventListener('abort', cancel, { once: true });
+    const cleanup = () => signal.removeEventListener('abort', cancel);
+    child.stderr?.resume();
+    const consume = line => {
+      let event; try { event = JSON.parse(line); } catch { return; }
+      if (!event || typeof event !== 'object' || Array.isArray(event)) return;
+      if (event.type === 'system' && event.subtype === 'init') {
+        if (!UUID.test(event.session_id || '') || event.session_id === selection.session_id || event.model !== selection.model ||
+            nativeSession && nativeSession !== event.session_id) {
+          invalidStream = true; child.kill('SIGINT'); return;
+        }
+        nativeSession = event.session_id;
+        emit({ type: 'simy.delegation.session', session_id: nativeSession });
+      }
+      if (!nativeSession || event.session_id && event.session_id !== nativeSession) return;
+      if (event.type === 'result') {
+        const denials = Array.isArray(event.permission_denials) ? event.permission_denials : [];
+        const questions = denials.flatMap(item => Array.isArray(item?.tool_input?.questions) ? item.tool_input.questions : []);
+        const message = questions.map(item => item?.question).filter(item => typeof item === 'string').join('\n') ||
+          (typeof event.result === 'string' && event.result.trim() ? event.result : null) ||
+          (Array.isArray(event.errors) ? event.errors.filter(item => typeof item === 'string').join('\n') : '') ||
+          denials.map(item => item?.tool_input?.description || item?.tool_input?.command).filter(item => typeof item === 'string').join('\n');
+        terminal = typeof event.result === 'string' && Boolean(event.result.trim()) || denials.length > 0 ||
+          Array.isArray(event.errors) && event.errors.some(item => typeof item === 'string' && item.trim());
+        terminalFailed = event.is_error === true || String(event.subtype || '').startsWith('error');
+        if (denials.length && !message) invalidStream = true;
+        if (denials.length && message) {
+          question = true;
+          emit({ type: 'simy.delegation.question', question: { message, permission_denials: denials, ...(questions.length ? { questions } : {}) } });
+          event.is_error = true;
+        }
+      }
+      if (event.type === 'result' && typeof event.result === 'string')
+        emit({ type: 'assistant', message: { content: [{ type: 'text', text: event.result }] } });
+      emit(event);
+    };
+    child.stdout.on('data', chunk => {
+      if (settled) return;
+      pending += decoder.write(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+      if (Buffer.byteLength(pending) > 256 * 1024) { invalidStream = true; child.kill('SIGINT'); return; }
+      const lines = pending.split('\n'); pending = lines.pop();
+      for (const line of lines) consume(line);
+    });
+    child.once('error', error => { if (settled) return; settled = true; cleanup(); const failure = fail('provider_result_unknown');
+      if (['ENOENT', 'EACCES'].includes(error?.code) && !child.pid) failure.delegationState = 'failed';
+      reject(failure); });
+    child.once('close', (code, closeSignal) => {
+      if (settled) return; settled = true;
+      cleanup();
+      pending += decoder.end();
+      if (!invalidStream && pending.trim()) consume(pending);
+      const rejectState = (reason, state) => reject(Object.assign(fail(reason), { delegationState: state }));
+      if (invalidStream || !nativeSession) rejectState('provider_result_unknown', 'result_unknown');
+      else if (signal.aborted) rejectState('provider_cancelled',
+        code === 130 || closeSignal === 'SIGINT' ? 'stopped' : 'result_unknown');
+      else if (question && terminal) rejectState('provider_input_required', 'needs_user');
+      else if (terminalFailed && terminal) rejectState('provider_turn_failed', 'failed');
+      else if (code !== 0 || !terminal) rejectState('provider_result_unknown', 'result_unknown');
+      else resolve();
+    });
+    if (signal.aborted) cancel();
+  });
+}

package/src/runner.js

@@ -1,3 +1,4 @@
+import { safetyCeilingRecoveryMessage } from "./orchestrator/recovery.js";
 import { captureDispatchProvenance } from './update-detachment/provenance.js';
 import { captureDispatchOwner, assertTaskAdmission, dispatchWithFence, observeDispatchEvent, queueDispatchReceipt } from './update-detachment/dispatch-gate.js';
 import { execFile, execFileSync } from "node:child_process";
@@ -258,7 +259,9 @@ export function restoreRun({ snapshot, session, apiOrigin, localPath = null, loc
     (persistedState === "failed" && restoredSnapshot.metadata?.controller_result_recovery)
     ? persistedState : null;
   const objectiveCheck = verifyObjective(restoredSnapshot.charter);
-  const savedGoalUnproven = (persistedState === "merge_ready" || persistedState === "pr_ready_for_review") &&
+  // Snapshots predating this flag still carry the original review requirement.
+  const savedGoalUnproven = restoredSnapshot.charter.independent_review_required !== false &&
+    (persistedState === "merge_ready" || persistedState === "pr_ready_for_review") &&
     !hasUserOutcomeProof(restoredSnapshot.attempts?.at(-1)?.independent_audit?.coverage_review);
   const objectiveUnverified = !objectiveCheck.valid || objectiveCheck.legacy || savedGoalUnproven;
   const restoredState = restoredFromState || objectiveUnverified ? "waiting_human" : persistedState;
@@ -459,7 +462,7 @@ export async function increaseLocalCodingRunProviderTokenBudget(run, value) {
   }
   const currentBudget = refreshBudgetState(run.snapshot);
   if (currentBudget.retry_exhausted) {
-    throw new Error("The Agentic Loop run also used its retry budget. Start a new run to continue.");
+    throw new Error(safetyCeilingRecoveryMessage("attempt_ceiling_reached", currentBudget));
   }
   const previousBudget = currentBudget.token_budget;
   const previousAudit = run.snapshot.final_audit;

package/src/session-supervision/acceptance-reads.js

@@ -0,0 +1,34 @@
+import { open, realpath } from 'node:fs/promises';
+import { constants } from 'node:fs';
+import { resolve, relative, isAbsolute } from 'node:path';
+import { createHash } from 'node:crypto';
+import { evidenceExcerpt } from '../codex-plugins/simy/hooks/purpose-evidence.mjs';
+
+// Read only original file predicates in the authorized task directory. These
+// are current independent controller reads, not worker claims or authored proof.
+export async function captureAcceptanceReads(cwd, criteria, { signal } = {}) {
+  const root = await realpath(cwd), rows = [], seen = new Set(); let retained = 0;
+  for (const criterion of criteria) {
+    signal?.throwIfAborted();
+    const check = criterion.check, target = check?.exactPath || check?.path;
+    if (!['file_equals', 'file_contains', 'file_exists'].includes(check?.type) || typeof target !== 'string' || !target || seen.has(target) || rows.length >= 8) continue;
+    seen.add(target); let handle;
+    try {
+      const path = await realpath(resolve(root, target)), within = relative(root, path);
+      if (!within || within === '..' || within.startsWith('../') || within.startsWith('..\\') || isAbsolute(within)) continue;
+      handle = await open(path, constants.O_RDONLY | (constants.O_NOFOLLOW || 0));
+      const info = await handle.stat(); if (!info.isFile() || info.size > 32768 || retained + info.size > 65536) continue;
+      const data = Buffer.alloc(32769), { bytesRead } = await handle.read(data, 0, data.length, 0);
+      if (bytesRead > 32768) continue;
+      const body = data.subarray(0, bytesRead); retained += bytesRead;
+      const digest = createHash('sha256').update(body).digest('hex');
+      rows.push({ id: `file:${target}`, source: 'controller_file_read', status: 'observed', at: Date.now(), digest,
+        recipe: { type: 'file_read', path: target }, observation: evidenceExcerpt(bytesRead ? body.toString('utf8') : JSON.stringify({ byteLength: 0, content: '' }), 4000) });
+    } catch { signal?.throwIfAborted(); /* Missing/large/unreadable files stay unverified; tool investigation remains available. */ }
+    finally { await handle?.close(); }
+  }
+  return rows;
+}
+export const currentAcceptanceRead = (item, now) => item?.source === 'controller_file_read' && item.status === 'observed' &&
+  item.recipe?.type === 'file_read' && typeof item.recipe.path === 'string' && Number.isFinite(item.at) && item.at <= now && now - item.at < 60000 &&
+  /^[a-f0-9]{64}$/.test(item.digest) && typeof item.observation?.text === 'string';

package/src/session-supervision/artifact-observer.js

@@ -0,0 +1,138 @@
+import { createHash } from 'node:crypto';
+import { lstat, realpath, readFile, mkdtemp, writeFile, rm } from 'node:fs/promises';
+import { tmpdir } from 'node:os';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { PNG } from 'pngjs';
+import { canonicalize } from '../sqm/canonical.js';
+
+const exec = promisify(execFile);
+const collectedManifests = new WeakSet();
+const digest = bytes => `sha256:${createHash('sha256').update(bytes).digest('hex')}`;
+const fail = code => Object.assign(new Error(code), { code });
+const hashPattern = /^sha256:[a-f0-9]{64}$/;
+
+// These are explicit read contracts, never commands or permission grants. A trusted
+// controller supplies both the contract and authorize; worker manifests are not input.
+export async function observeArtifacts(contract, { root, authorize, signal, adapters = {}, now = Date.now } = {}) {
+  if (!contract?.revision || !Array.isArray(contract.targets) || !contract.targets.length ||
+      new Set(contract.targets.map(t => t.id)).size !== contract.targets.length) throw fail('invalid_contract');
+  if (typeof authorize !== 'function') throw fail('authorization_required');
+  const snapshot = structuredClone(contract);
+  const contractDigest = digest(canonicalize(snapshot));
+  const targets = [];
+  for (const target of snapshot.targets) {
+    if (!target.id || !target.requirementId || !target.destination || !hashPattern.test(target.digest) ||
+        !Number.isSafeInteger(target.unitCount) || target.unitCount < 1 ||
+        !Array.isArray(target.expectedText) || target.expectedText.length !== target.unitCount ||
+        target.expectedText.some(text => typeof text !== 'string' || !text.trim())) throw fail('invalid_target');
+    await authorize(target); signal?.throwIfAborted();
+    let observation;
+    try {
+      const adapter = Object.hasOwn(adapters, target.kind) ? adapters[target.kind] :
+        ['file', 'code', 'pdf', 'pptx'].includes(target.kind) ? localArtifactAdapter : null;
+      if (typeof adapter !== 'function') throw fail('unsupported_kind');
+      observation = await adapter(target, { root, signal, authorize });
+      const units = observation.units || [];
+      const complete = units.length === target.unitCount && new Set(units.map(u => u.index)).size === target.unitCount &&
+        units.every(u => Number.isSafeInteger(u.index) && u.index >= 1 && u.index <= target.unitCount &&
+          u.read === true && hashPattern.test(u.digest) &&
+          (!['pdf', 'pptx'].includes(target.kind) || u.rendered === true && hashPattern.test(u.renderDigest)));
+      const reasons = [];
+      if (observation.destination !== target.destination) reasons.push('destination_mismatch');
+      if (observation.digest !== target.digest) reasons.push('revision_mismatch');
+      if (!complete || observation.unitCount !== target.unitCount) reasons.push('incomplete_coverage');
+      if (complete && units.some(u => typeof u.text !== 'string' || !u.text.includes(target.expectedText[u.index - 1]))) reasons.push('content_mismatch');
+      observation = { ...observation, status: reasons.length ? 'unmet' : 'verified', reasons };
+    } catch (error) {
+      signal?.throwIfAborted();
+      observation = { status: 'unconfirmed', reasons: [error.code === 'ENOENT' ? 'reader_or_renderer_unavailable' :
+        ['unsupported_kind', 'outside_root', 'not_regular_file', 'too_large', 'invalid_pdf', 'changed_during_read'].includes(error.code) ? error.code : 'observation_failed'] };
+    }
+    await authorize(target); signal?.throwIfAborted();
+    targets.push({ ...observation, id: target.id, requirementId: target.requirementId, kind: target.kind,
+      evidenceKind: ['pdf', 'pptx'].includes(target.kind) ? 'artifact_render_readback' : 'artifact_readback',
+      source: 'controller_read_only_observer', observedAt: now() });
+  }
+  const status = targets.some(t => t.status === 'unmet') ? 'unmet' : targets.every(t => t.status === 'verified') ? 'verified' : 'unconfirmed';
+  const manifest = { schemaVersion: 1, revision: snapshot.revision, contractDigest, status,
+    expectedCount: snapshot.targets.length, inspectedCount: targets.filter(t => t.units?.length).length, targets,
+    scope: 'declared_destination_bytes_unit_coverage_and_text_only' };
+  const result = { ...manifest, digest: digest(canonicalize(manifest)) };
+  collectedManifests.add(result);
+  return result;
+}
+
+async function scopedRead(root, destination) {
+  const base = await realpath(root);
+  const requested = path.resolve(base, destination);
+  const resolved = await realpath(requested);
+  if (!resolved.startsWith(`${base}${path.sep}`)) throw fail('outside_root');
+  const stat = await lstat(requested);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw fail('not_regular_file');
+  if (stat.size > 32 * 1024 * 1024) throw fail('too_large');
+  const bytes = await readFile(resolved);
+  if (bytes.length > 32 * 1024 * 1024) throw fail('too_large');
+  return bytes;
+}
+
+export async function localArtifactAdapter(target, { root, signal, authorize, execute = exec } = {}) {
+  const bytes = await scopedRead(root, target.destination);
+  const sourceDigest = digest(bytes);
+  let units;
+  if (target.kind === 'file' || target.kind === 'code') {
+    const text = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    units = [{ index: 1, read: true, digest: sourceDigest, text }];
+  } else if (target.kind === 'pdf' || target.kind === 'pptx') {
+    // Render an immutable snapshot; never allow document content to choose commands.
+    const temp = await mkdtemp(path.join(tmpdir(), 'simy-artifact-observer-'));
+    try {
+      const input = path.join(temp, 'input.pdf');
+      const options = { signal, timeout: 30000, maxBuffer: 4 * 1024 * 1024, env: { ...process.env, LC_ALL: 'C' } };
+      let slideCount = null;
+      if (target.kind === 'pptx') {
+        const presentation = path.join(temp, 'input.pptx');
+        await writeFile(presentation, bytes, { mode: 0o600 });
+        const listing = await execute('unzip', ['-Z1', presentation], options);
+        slideCount = listing.stdout.split(/\r?\n/).filter(name => /^ppt\/slides\/slide[1-9]\d*\.xml$/.test(name)).length;
+        if (!slideCount || slideCount > 500) throw fail('invalid_pdf');
+        await authorize(target); signal?.throwIfAborted();
+        await execute('soffice', [`-env:UserInstallation=${pathToFileURL(path.join(temp, 'profile')).href}`,
+          '--headless', '--convert-to', 'pdf:impress_pdf_Export:{"ExportHiddenSlides":{"type":"boolean","value":"true"}}',
+          '--outdir', temp, presentation], { ...options, timeout: 60000 });
+      } else await writeFile(input, bytes, { mode: 0o600 });
+      const info = await execute('pdfinfo', [input], options);
+      const count = Number(info.stdout.match(/^Pages:\s+(\d+)\s*$/m)?.[1]);
+      if (!Number.isSafeInteger(count) || count < 1 || count > 500 || slideCount !== null && count !== slideCount) throw fail('invalid_pdf');
+      units = [];
+      for (let index = 1; index <= count; index++) {
+        await authorize(target); signal?.throwIfAborted();
+        const prefix = path.join(temp, `page-${index}`);
+        await execute('pdftoppm', ['-f', String(index), '-l', String(index), '-singlefile', '-scale-to', '1200', '-png', input, prefix], options);
+        const png = await readFile(`${prefix}.png`);
+        const image = PNG.sync.read(png);
+        if (!image.width || !image.height) throw fail('invalid_pdf');
+        const { stdout: text } = await execute('pdftotext', ['-f', String(index), '-l', String(index), input, '-'], options);
+        units.push({ index, read: true, rendered: true, digest: digest(text), renderDigest: digest(png), text });
+      }
+    } finally { await rm(temp, { recursive: true, force: true }); }
+  } else throw fail('unsupported_kind');
+  if (digest(await scopedRead(root, target.destination)) !== sourceDigest) throw fail('changed_during_read');
+  return { destination: target.destination, digest: sourceDigest, unitCount: units.length, units };
+}
+
+// Only consume an in-memory controller-produced manifest after current-contract
+// comparison. The digest detects corruption, not authenticity of a worker JSON file.
+export function artifactRequirementEvidence(manifest, contract) {
+  if (!manifest || !collectedManifests.has(manifest)) return [];
+  const { digest: claimed, ...payload } = manifest;
+  if (claimed !== digest(canonicalize(payload)) || manifest.contractDigest !== digest(canonicalize(contract)) ||
+      manifest.revision !== contract.revision || manifest.status !== 'verified' ||
+      manifest.expectedCount !== contract.targets.length || manifest.targets.length !== contract.targets.length) return [];
+  return manifest.targets.map(target => ({ requirementId: target.requirementId, observations: [{
+    ref: `artifact:${target.id}`, target: target.destination, digest: target.digest,
+    scope: manifest.scope,
+  }] }));
+}