elanous 0.2.35 → 0.2.36

package/src/task-orchestrator/surfaces/pod-si-warm-host.ts

@@ -0,0 +1,224 @@
+/** Adopt only transport-verified si-v1 bytes into the existing host collectors. */
+import { gzipSync } from 'node:zlib';
+import { createHash, randomUUID } from 'node:crypto';
+import { execFileSync } from 'node:child_process';
+import { readFileSync, realpathSync } from 'node:fs';
+import { join } from 'node:path';
+import { collectPodLedgers } from './pod-ledger-collect.js';
+import { collectPodArtifacts } from './pod-artifact-return.js';
+import { runLedgerDir, runLedgerPath } from '../../self-implement/run-ledger.js';
+import { effectiveInstanceRoot } from '../../instance/resolve.js';
+import { debug } from '../../debug/log.js';
+import { getUserConfig } from '../../user-config.js';
+import { normalizeFallbackChain } from '../../oauth/fallback-chain.js';
+import { classifyPodTerminal, applyPodTerminal, podTerminalPrBody,
+  type PrTerminalRecord } from '../../self-dev/draft-residue.js';
+import type { SiWarmCommand, SiWarmReply, SiWarmReturnedBytes } from './pod-si-warm-protocol.js';
+import { acquireSiWarmLease, type SiWarmAcquireResult } from './pod-si-warm-provider.js';
+import { hostCredentials, hostGrokCredentials, podChildLlmArgs, POD_JOB_DEADLINE_SECONDS,
+  type PodSpawnOptions } from './self-implement-pod.js';
+import type { SelfImplementJobSpawn } from './self-implement.js';
+import type { SelfImplementJobDone } from './self-implement.js';
+import type { SiWarmChildAttempt } from './self-implement-pod.js';
+import type { SiWarmRunnerPayload, SiWarmCredentialBundle } from './pod-si-warm-runner.js';
+
+const MAX_LEDGER_BYTES = 64 * 1024 * 1024;
+const strictBase64 = (value: unknown): Buffer => {
+  if (typeof value !== 'string' || value.length > MAX_LEDGER_BYTES * 2
+    || !/^(?:[A-Za-z0-9+/]{4})*(?:[A-Za-z0-9+/]{2}==|[A-Za-z0-9+/]{3}=)?$/.test(value))
+    throw new Error('si-v1 ledger base64 invalid');
+  const bytes = Buffer.from(value, 'base64');
+  if (bytes.toString('base64') !== value) throw new Error('si-v1 ledger base64 noncanonical');
+  return bytes;
+};
+
+function chunks(kind: 'ledger' | 'artifact', id: string, bytes: Uint8Array): string[] {
+  const encoded = gzipSync(bytes).toString('base64');
+  const size = 8000;
+  const total = Math.ceil(encoded.length / size);
+  const tag = kind === 'ledger' ? 'ELANOUS_RUN_LEDGER' : 'ELANOUS_POD_ARTIFACT';
+  return Array.from({ length: total }, (_, index) =>
+    `${tag} ${id} ${index + 1}/${total} ${encoded.slice(index * size, (index + 1) * size)}`);
+}
+
+/** Collector failures are adoption failures, so the consumer keeps the lease fenced. */
+export async function adoptSiWarmBytes(command: SiWarmCommand, _reply: SiWarmReply,
+  bytes: SiWarmReturnedBytes, paths: { ledgerDir?: string; artifactDir?: string } = {}): Promise<void> {
+  const ledgerRaw = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(bytes.ledger));
+  if (!Array.isArray(ledgerRaw) || ledgerRaw.length === 0 || ledgerRaw.length > 128)
+    throw new Error('si-v1 child ledger missing');
+  const ledgerLines: string[] = [];
+  const names = new Set<string>();
+  for (const row of ledgerRaw) {
+    if (!row || typeof row !== 'object' || Array.isArray(row)
+      || Object.keys(row).sort().join(',') !== 'bytes,name'
+      || typeof row.name !== 'string' || !row.name.endsWith('.jsonl'))
+      throw new Error('si-v1 ledger envelope invalid');
+    const runId = row.name.slice(0, -'.jsonl'.length);
+    runLedgerPath(runId);
+    if (runId !== command.runId) throw new Error('si-v1 child ledger run id mismatch');
+    if (names.has(runId)) throw new Error('si-v1 duplicate ledger');
+    names.add(runId);
+    ledgerLines.push(...chunks('ledger', runId, strictBase64(row.bytes)));
+  }
+  const artifactLines = bytes.artifacts.flatMap(item =>
+    chunks('artifact', Buffer.from(item.path).toString('base64url'), item.bytes));
+  const incomplete: string[] = [];
+  collectPodLedgers(ledgerLines.join('\n'), { dir: paths.ledgerDir ?? runLedgerDir(),
+    log: (_category, event, data) => {
+      if (event === 'ledger-collect-incomplete' || event === 'ledger-collect-skipped')
+        incomplete.push(`${event}:${data.runId ?? 'unknown'}`);
+    } });
+  collectPodArtifacts(artifactLines.join('\n'), { dir: paths.artifactDir ?? join(effectiveInstanceRoot(), 'pod-artifacts'),
+    job: `si-${command.executionKey.slice(0, 16)}`,
+    log: (_category, event, data) => {
+      if (event === 'artifact-collect-incomplete' || event === 'artifact-collect-skipped')
+        incomplete.push(`${event}:${data.path ?? 'unknown'}`);
+    } });
+  if (incomplete.length) throw new Error(`si-v1 adoption incomplete: ${incomplete.join(',').slice(0, 300)}`);
+}
+
+type ChildInput = Parameters<SelfImplementJobSpawn>[0];
+
+/** Reuse only the source and auth form the fixed worker currently supports. */
+export function siWarmEligible(input: ChildInput, options: PodSpawnOptions): boolean {
+  // Merge-ready children need the cold path's full host ACP/regate/land sequence.
+  // Until that sequence is shared, admit only draft-producing children.
+  return input.autoMerge === false && !input.after && !options.repairCommitOnly && !options.source
+    && (!options.provider || options.provider === 'openai-codex')
+    && (!options.accountBroker || !!options.rotationAccounts?.length)
+    && !options.extraArgs?.length && !options.passEnv?.length
+    && !options.skillEnv && !options.armEnv && !options.groundingUrl;
+}
+
+/** A warm draft has the same host-owned terminal record as a cold Job. */
+export async function postprocessSiWarmChild(input: ChildInput, result: SelfImplementJobDone,
+  attempt: SiWarmChildAttempt, options: PodSpawnOptions,
+  record: (terminal: PrTerminalRecord) => Promise<void> = async terminal => {
+    await applyPodTerminal(terminal, { ledgerRunId: attempt.command.runId,
+      ledgerDir: runLedgerDir() });
+  }): Promise<SelfImplementJobDone> {
+  const disposition = result.disposition;
+  if (!disposition) throw new Error('si-v1 host terminal disposition missing');
+  const terminal = classifyPodTerminal({ childRunId: disposition.childRunId ?? attempt.command.runId,
+    state: result.exitCode === 0 ? 'complete' : 'failed', disposition,
+    env: process.env, prBody: options.draftResidue ? undefined : podTerminalPrBody(disposition),
+    goalText: input.feature, at: new Date().toISOString() });
+  if (options.draftResidue) await options.draftResidue(terminal,
+    { ledgerRunId: attempt.command.runId, ledgerDir: runLedgerDir() });
+  else await record(terminal);
+  return result;
+}
+
+export function siWarmPayload(input: ChildInput, options: PodSpawnOptions, runId: string,
+  env: NodeJS.ProcessEnv = process.env): SiWarmRunnerPayload {
+  const requestedGoal = env.ELANOUS_POD_GOAL_DOC;
+  const authorOnPod = env.ELANOUS_POD_AUTHOR_ON_POD === '1' && !requestedGoal;
+  let goalDocument: string | undefined;
+  if (requestedGoal) {
+    if (!/^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/.test(requestedGoal)
+      || requestedGoal.split('/').includes('..')) throw new Error('si-v1 goal path invalid');
+    const root = realpathSync(process.cwd());
+    const path = realpathSync(join(root, requestedGoal));
+    if (!path.startsWith(`${root}/`)) throw new Error('si-v1 goal path escaped repo');
+    goalDocument = readFileSync(path, 'utf8');
+  }
+  const selfArgs = [
+    ...(input.base ? ['--base', input.base] : []),
+    ...(input.autoMerge ? ['--merge-by-host'] : []),
+    ...(input.autoReview ? ['--auto-review'] : []),
+    ...(input.openPr || (!input.autoMerge && !options.repairCommitOnly) ? ['--open-pr'] : []),
+    ...(input.draft === false ? ['--no-draft'] : []),
+    ...(options.hostSupervised ? ['--no-supervise'] : []),
+    ...(options.extraArgs ?? []),
+    ...podChildLlmArgs(options),
+  ];
+  const delegated = !!requestedGoal || authorOnPod;
+  const args = delegated ? [
+    ...(input.base ? ['--base', input.base] : []),
+    ...(input.autoMerge ? ['--merge-by-host'] : input.openPr ? ['--no-auto-merge'] : []),
+    ...(options.hostSupervised ? ['--no-supervise'] : []),
+    ...podChildLlmArgs(options),
+  ] : selfArgs;
+  return { mode: requestedGoal ? 'ask' : authorOnPod ? 'say' : 'self', feature: input.feature,
+    args, ...(goalDocument === undefined ? {} : { goalDocument }),
+    env: { ELANOUS_RUN_ID: runId,
+      ...(env.ELANOUS_DISPATCH_RECORDED === '1' ? { ELANOUS_DISPATCH_RECORDED: '1' } : {}),
+      ...(env.ELANOUS_HARNESS_SEAT ? { ELANOUS_HARNESS_SEAT: env.ELANOUS_HARNESS_SEAT } : {}) } };
+}
+
+/** Carry the same normalized child fallback config as a fresh Pod Job. */
+export function siWarmFallbackFiles(raw: unknown, grok: { grokAuth?: string; grokApiKey?: string } | null):
+  Record<string, string> {
+  // The fixed warm runner only carries Codex accounts and optional Grok credentials.
+  const available = normalizeFallbackChain(raw).chain.filter(step =>
+    step === 'codex-rotate' || (step === 'grok' && !!(grok?.grokAuth || grok?.grokApiKey)));
+  // A configured chain with no carryable provider cannot enter the warm worker.
+  // Its caller catches this before acquiring a lease and uses the cold Job path.
+  if (available.length === 0) throw new Error('no carryable warm fallback provider');
+  return {
+    'llm-fallback-config.json': JSON.stringify({ llm: { fallbackChain: available } }),
+    ...(grok?.grokAuth ? { 'grok-auth.json': grok.grokAuth } : {}),
+    ...(grok?.grokApiKey ? { 'grok-api-key': grok.grokApiKey } : {}),
+  };
+}
+
+export function siWarmExecutionKey(input: ChildInput, runId: string): string {
+  return createHash('sha256').update(JSON.stringify({ runId, spaceId: input.spaceId,
+    feature: input.feature, base: input.base, autoMerge: input.autoMerge,
+    autoReview: input.autoReview, openPr: input.openPr, draft: input.draft })).digest('hex');
+}
+
+/** Host-owned private input builder. A preparation failure happens before any Pod exec or lease. */
+export async function acquireSiWarmChild(input: ChildInput, options: PodSpawnOptions): Promise<SiWarmAcquireResult> {
+  if (!siWarmEligible(input, options)) return { status: 'no-entry', reason: 'invalid-input' };
+  let prepared: Parameters<typeof acquireSiWarmLease>[0];
+  try {
+    const sourceSha = execFileSync('git', ['rev-parse', '--verify', '--end-of-options', `${input.base ?? 'origin/HEAD'}^{commit}`],
+      { cwd: process.cwd(), encoding: 'utf8' }).trim();
+    if (!/^[a-f0-9]{40}$/.test(sourceSha)) return { status: 'no-entry', reason: 'invalid-input' };
+    const runId = `run-${randomUUID()}`;
+    const attemptId = `attempt-${randomUUID()}`;
+    const executionKey = siWarmExecutionKey(input, runId);
+    const plannedAccount = options.accountBroker?.() ?? options.account ?? 'team';
+    const rotation = options.rotationAccounts;
+    if (options.accountBroker && (!rotation?.includes(plannedAccount)
+      || new Set(rotation).size !== rotation.length))
+      return { status: 'no-entry', reason: 'invalid-input' };
+    const accounts = options.accountBroker
+      ? [plannedAccount, ...rotation!.filter(name => name !== plannedAccount)] : undefined;
+    const credentials = (options.credentials ?? hostCredentials)(plannedAccount);
+    const deadlineMs = (options.deadlineSeconds ?? POD_JOB_DEADLINE_SECONDS) * 1000;
+    const config = (options.fallbackConfig ?? getUserConfig)();
+    const fallback = normalizeFallbackChain(config.llm.fallbackChain).chain;
+    let grok: { grokAuth?: string; grokApiKey?: string } | null = null;
+    if (fallback.includes('grok')) {
+      try { grok = hostGrokCredentials({ minValidityMs: deadlineMs,
+        apiKeyOptIn: options.grokApiKeyOptIn === true }); }
+      catch { /* A missing or short-lived credential removes only this fallback step. */ }
+    }
+    const extraAccounts = accounts?.map((name, index) => index === 0
+      ? credentials : (options.credentials ?? hostCredentials)(name));
+    const bundle: SiWarmCredentialBundle = { files: {
+      ...(accounts ? Object.fromEntries(extraAccounts!.map((credential, index) =>
+        [`codex-${index}.json`, JSON.stringify({ elanousAuth: credential.elanousAuth,
+          codexAuth: credential.codexAuth })]))
+        : { 'elanous-auth.json': credentials.elanousAuth,
+          'codex-auth.json': credentials.codexAuth }),
+      'gh-token': credentials.ghToken,
+      ...siWarmFallbackFiles(config.llm.fallbackChain, grok) },
+    ...(accounts ? { accounts } : {}) };
+    const payload = Buffer.from(JSON.stringify(siWarmPayload(input, options, runId)));
+    const credentialBundle = Buffer.from(JSON.stringify(bundle));
+    const deadlineAt = Date.now() + deadlineMs;
+    prepared = { runId, attemptId, executionKey, sourceSha, deadlineAt,
+      payload, credentialBundle, adopt: adoptSiWarmBytes };
+  } catch (error) {
+    // Credential errors may contain private paths or tokens; log the class, not its raw text.
+    debug.log('pod.reuse', 'si-input-preparation-failed', {
+      reason: error instanceof Error ? error.name : 'unknown', spaceId: input.spaceId,
+    }, { level: 'warn' });
+    return { status: 'no-entry', reason: 'invalid-input' };
+  }
+  return acquireSiWarmLease(prepared);
+}

package/src/task-orchestrator/surfaces/pod-si-warm-protocol.ts

@@ -0,0 +1,201 @@
+/** si-task warm execution contract. The gate-v1 test replay wire remains independent. */
+import { createHash, timingSafeEqual } from 'node:crypto';
+import type { WarmWorkerKey } from './pod-warm-worker-protocol.js';
+
+const SHA = /^[a-f0-9]{40}$/;
+const DIGEST = /^[a-f0-9]{64}$/;
+const TOKEN = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const PATH = /^[A-Za-z0-9_.-]+(?:\/[A-Za-z0-9_.-]+)*$/;
+const MAX_ARTIFACTS = 256;
+const MAX_RESULT_BYTES = 64 * 1024 * 1024;
+const MAX_ARTIFACT_BYTES = 5 * 1024 * 1024;
+const MAX_ARTIFACT_TOTAL_BYTES = 20 * 1024 * 1024;
+
+/** The secret bundle travels on a separate private stdin channel, never in this command or its reply. */
+export interface SiWarmCommand {
+  protocol: 'si-v1';
+  runId: string;
+  attemptId: string;
+  executionKey: string;
+  sourceSha: string;
+  leaseId: string;
+  generation: number;
+  workerId: string;
+  podUid: string;
+  key: WarmWorkerKey;
+  envProfile: 'si-standard-v1';
+  deadlineAt: number;
+  payloadSha256: string;
+  credentialBundleSha256: string;
+}
+
+/** Metadata only. Terminal output and artifacts are transferred as separately verified bytes. */
+export interface SiWarmReply {
+  protocol: 'si-v1';
+  runId: string;
+  attemptId: string;
+  executionKey: string;
+  sourceSha: string;
+  leaseId: string;
+  generation: number;
+  workerId: string;
+  podUid: string;
+  key: WarmWorkerKey;
+  envProfile: 'si-standard-v1';
+  payloadSha256: string;
+  startedAt: number;
+  finishedAt: number;
+  exitCode: number;
+  terminalSha256: string;
+  ledgerSha256: string;
+  logSha256: string;
+  artifacts: readonly { path: string; sha256: string; bytes: number }[];
+}
+
+export interface SiWarmReturnedBytes {
+  terminal: Uint8Array;
+  ledger: Uint8Array;
+  log: Uint8Array;
+  artifacts: readonly { path: string; bytes: Uint8Array }[];
+}
+
+export type SiWarmValidationReason = 'match' | 'invalid-command' | 'invalid-reply' | 'identity'
+  | 'expired' | 'missing-output' | 'output-hash' | 'terminal';
+
+export interface SiWarmValidation {
+  reason: SiWarmValidationReason;
+  /** A matching failed child is still a measured result, never a reason to run a second Job. */
+  measured: boolean;
+  quarantineWorker: boolean;
+}
+
+const own = (value: unknown): Record<string, unknown> | null =>
+  value !== null && typeof value === 'object' && !Array.isArray(value) ? value as Record<string, unknown> : null;
+const fields = (value: Record<string, unknown>, keys: readonly string[]): boolean =>
+  Object.keys(value).length === keys.length && keys.every(key => Object.hasOwn(value, key));
+const str = (value: unknown): value is string => typeof value === 'string';
+const token = (value: unknown): value is string => str(value) && TOKEN.test(value);
+const digest = (value: unknown): value is string => str(value) && DIGEST.test(value);
+const safePath = (value: unknown): value is string => str(value) && PATH.test(value)
+  && value.split('/').every(part => part !== '.' && part !== '..');
+const integer = (value: unknown): value is number => typeof value === 'number' && Number.isSafeInteger(value);
+const finite = (value: unknown): value is number => typeof value === 'number' && Number.isFinite(value);
+const keyFields = ['context', 'imageDigest', 'lockHash', 'architecture'] as const;
+const commandFields = ['protocol', 'runId', 'attemptId', 'executionKey', 'sourceSha', 'leaseId',
+  'generation', 'workerId', 'podUid', 'key', 'envProfile', 'deadlineAt', 'payloadSha256',
+  'credentialBundleSha256'] as const;
+const replyFields = ['protocol', 'runId', 'attemptId', 'executionKey', 'sourceSha', 'leaseId',
+  'generation', 'workerId', 'podUid', 'key', 'envProfile', 'payloadSha256', 'startedAt',
+  'finishedAt', 'exitCode', 'terminalSha256', 'ledgerSha256', 'logSha256', 'artifacts'] as const;
+
+function validKey(raw: unknown): raw is WarmWorkerKey {
+  const key = own(raw);
+  return !!key && fields(key, keyFields) && token(key.context)
+    && str(key.imageDigest) && /^sha256:[a-f0-9]{64}$/.test(key.imageDigest)
+    && digest(key.lockHash) && token(key.architecture);
+}
+
+/** Reject unknown wire fields so credential text cannot be accepted as reply metadata. */
+export function parseSiWarmCommand(raw: unknown): SiWarmCommand | null {
+  const row = own(raw);
+  if (!row || !fields(row, commandFields) || row.protocol !== 'si-v1'
+    || ![row.runId, row.attemptId, row.leaseId, row.workerId].every(token)
+    || !digest(row.executionKey) || !str(row.sourceSha) || !SHA.test(row.sourceSha)
+    || !token(row.podUid) || !integer(row.generation) || row.generation < 1
+    || !validKey(row.key) || row.envProfile !== 'si-standard-v1'
+    || !finite(row.deadlineAt) || !digest(row.payloadSha256)
+    || !digest(row.credentialBundleSha256)) return null;
+  return raw as SiWarmCommand;
+}
+
+export function parseSiWarmReply(raw: unknown): SiWarmReply | null {
+  const row = own(raw);
+  if (!row || !fields(row, replyFields) || row.protocol !== 'si-v1'
+    || ![row.runId, row.attemptId, row.leaseId, row.workerId].every(token)
+    || !digest(row.executionKey) || !str(row.sourceSha) || !SHA.test(row.sourceSha)
+    || !token(row.podUid) || !integer(row.generation) || row.generation < 1
+    || !validKey(row.key) || row.envProfile !== 'si-standard-v1'
+    || !digest(row.payloadSha256) || !finite(row.startedAt) || row.startedAt < 0
+    || !finite(row.finishedAt) || row.finishedAt <= row.startedAt
+    || !integer(row.exitCode) || row.exitCode < 0
+    || !digest(row.terminalSha256) || !digest(row.ledgerSha256) || !digest(row.logSha256)
+    || !Array.isArray(row.artifacts) || row.artifacts.length > MAX_ARTIFACTS
+    || row.artifacts.some((part: unknown) => {
+      const item = own(part);
+      return !item || !fields(item, ['path', 'sha256', 'bytes']) || !safePath(item.path) || !digest(item.sha256)
+        || !integer(item.bytes) || item.bytes < 0 || item.bytes > MAX_ARTIFACT_BYTES;
+    }) || row.artifacts.reduce((sum: number, item: { bytes: number }) => sum + item.bytes, 0) > MAX_ARTIFACT_TOTAL_BYTES) return null;
+  return raw as SiWarmReply;
+}
+
+export function siWarmSha256(bytes: Uint8Array): string {
+  return createHash('sha256').update(bytes).digest('hex');
+}
+
+export function siWarmDigestMatches(bytes: Uint8Array, expected: string): boolean {
+  if (!digest(expected)) return false;
+  return timingSafeEqual(Buffer.from(siWarmSha256(bytes), 'hex'), Buffer.from(expected, 'hex'));
+}
+
+/** Validate the bytes that will enter the existing si-task result and artifact collectors. */
+export function assessSiWarmReply(commandRaw: unknown, replyRaw: unknown, returned: SiWarmReturnedBytes | null,
+  payload: Uint8Array, credentialBundle: Uint8Array): SiWarmValidation {
+  const fail = (reason: SiWarmValidationReason): SiWarmValidation => ({ reason, measured: false, quarantineWorker: true });
+  const command = parseSiWarmCommand(commandRaw);
+  if (!command || !siWarmDigestMatches(payload, command.payloadSha256)
+    || !siWarmDigestMatches(credentialBundle, command.credentialBundleSha256)) return fail('invalid-command');
+  const reply = parseSiWarmReply(replyRaw);
+  if (!reply) return fail('invalid-reply');
+  if (reply.runId !== command.runId || reply.attemptId !== command.attemptId
+    || reply.executionKey !== command.executionKey || reply.sourceSha !== command.sourceSha
+    || reply.leaseId !== command.leaseId || reply.generation !== command.generation
+    || reply.workerId !== command.workerId || reply.podUid !== command.podUid
+    || reply.envProfile !== command.envProfile || reply.payloadSha256 !== command.payloadSha256
+    || keyFields.some(field => reply.key[field] !== command.key[field])) return fail('identity');
+  if (reply.startedAt > reply.finishedAt || reply.finishedAt >= command.deadlineAt) return fail('expired');
+  if (!returned || !(returned.terminal instanceof Uint8Array)
+    || !(returned.ledger instanceof Uint8Array) || !(returned.log instanceof Uint8Array)
+    || !Array.isArray(returned.artifacts) || returned.artifacts.length !== reply.artifacts.length
+    || returned.terminal.byteLength === 0 || returned.ledger.byteLength === 0
+    || returned.terminal.byteLength > MAX_RESULT_BYTES || returned.ledger.byteLength > MAX_RESULT_BYTES
+    || returned.log.byteLength > MAX_RESULT_BYTES) return fail('missing-output');
+  if (!siWarmDigestMatches(returned.terminal, reply.terminalSha256)
+    || !siWarmDigestMatches(returned.ledger, reply.ledgerSha256)
+    || !siWarmDigestMatches(returned.log, reply.logSha256)) return fail('output-hash');
+  if (new Set(reply.artifacts.map(item => item.path)).size !== reply.artifacts.length) return fail('invalid-reply');
+  const actual = new Map<string, Uint8Array>();
+  for (const item of returned.artifacts) {
+    if (!item || !safePath(item.path)
+      || !(item.bytes instanceof Uint8Array) || actual.has(item.path)) return fail('missing-output');
+    actual.set(item.path, item.bytes);
+  }
+  for (const item of reply.artifacts) {
+    const bytes = actual.get(item.path);
+    if (!bytes) return fail('missing-output');
+    if (bytes.byteLength !== item.bytes || bytes.byteLength > MAX_RESULT_BYTES
+      || !siWarmDigestMatches(bytes, item.sha256)) return fail('output-hash');
+  }
+  try {
+    const terminal = JSON.parse(new TextDecoder('utf-8', { fatal: true }).decode(returned.terminal));
+    const row = own(terminal);
+    if (!row || typeof row.ok !== 'boolean' || !str(row.stage) || !row.stage) return fail('terminal');
+  } catch { return fail('terminal'); }
+  return { reason: 'match', measured: true, quarantineWorker: false };
+}
+
+export type SiWarmExecutionBoundary = 'not-entered' | 'exec-attempted';
+export type SiWarmNextStep = 'adopt-warm' | 'cold-job' | 'reconcile-only';
+
+/** A Pod exec may have made a PR even when its response was lost. Never launch a duplicate Job then. */
+export function decideSiWarmNextStep(input: {
+  boundary: SiWarmExecutionBoundary;
+  leaseFenced: boolean;
+  validation?: SiWarmValidation;
+}): { next: SiWarmNextStep; quarantineWorker: boolean } {
+  if (input.boundary === 'not-entered' && input.leaseFenced)
+    return { next: 'cold-job', quarantineWorker: false };
+  if (input.boundary === 'exec-attempted' && input.leaseFenced && input.validation?.measured
+    && input.validation.reason === 'match')
+    return { next: 'adopt-warm', quarantineWorker: false };
+  return { next: 'reconcile-only', quarantineWorker: true };
+}