@fitlab-ai/agent-infra 0.11.9 → 0.11.11

package/dist/lib/sandbox/control/client.js

@@ -1,5 +1,4 @@
 import fs from 'node:fs';
-import { hasTaskBoundMarker } from '../../internal/task-operation-registry.js';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { SANDBOX_CONTROL_ADMISSION_WINDOW_MS, SANDBOX_CONTROL_MAX_BYTES, SANDBOX_CONTROL_STATUS_STALE_MS, isSandboxControlFamily } from './protocol.js';
@@ -8,7 +7,11 @@ import { readSandboxControlPayload, readSandboxControlStatus } from './state.js'
 import { accessSandboxTaskView, taskViewFromStatus } from './task-view.js';
 import { readSandboxControlIdentitySentinel } from './identity-sentinel.js';
 import { configuredShortIdLength, resolveShortIdReadOnly } from '../../task/short-id.js';
+import { hasTaskBoundMarker, isSandbox } from '../environment.js';
+import { loadConfig } from '../config.js';
+import { recoverSandboxControlFromHost } from './host-recovery.js';
 const SANDBOX_CONTROL_RESPONSE_SETTLE_MS = 250;
+const SANDBOX_TASK_FINALIZATION_RECOVERY_BUDGET_MS = 5 * 60_000;
 export class SandboxControlClientError extends Error {
     detail;
     accepted;
@@ -79,8 +82,10 @@ function preflight(statusDir, generation, taskViewEffect = null, now = Date.now(
     }
 }
 function taskViewEffectForRequest(request) {
-    if (request.family === 'task-lifecycle' || request.family === 'task-finalization')
+    if (request.family === 'task-lifecycle')
         return 'progress';
+    if (request.family === 'task-finalization')
+        return 'recovery';
     return null;
 }
 function parseResponse(raw, id, accepted = false) {
@@ -95,7 +100,7 @@ function parseResponse(raw, id, accepted = false) {
     }
     return response;
 }
-function readPublishedResponse(raw, id, channelDir, accepted = false) {
+function readPublishedResponse(raw, id, channelDir, accepted, generation) {
     const response = parseResponse(raw, id, accepted);
     if (response.outputState !== 'available')
         return response;
@@ -109,6 +114,7 @@ function readPublishedResponse(raw, id, channelDir, accepted = false) {
     }
     if (!response.payload || response.payload.version !== payload.version
         || response.payload.id !== payload.id || response.payload.generation !== payload.generation
+        || payload.generation !== generation
         || response.payload.stdoutBytes !== payload.stdoutBytes || response.payload.stderrBytes !== payload.stderrBytes
         || response.payload.stdoutSha256 !== payload.stdoutSha256 || response.payload.stderrSha256 !== payload.stderrSha256) {
         clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker payload reference is invalid', false, true, id);
@@ -213,7 +219,7 @@ function exchangeSandboxControl(request, params) {
             try {
                 // The request-specific terminal proves the broker claimed the request; preserve recovery evidence if marker cleanup won the race.
                 accepted = true;
-                response = readPublishedResponse(raw, request.id, channelDir, accepted);
+                response = readPublishedResponse(raw, request.id, channelDir, accepted, request.generation);
                 malformedResponseRaw = null;
             }
             catch (error) {
@@ -261,7 +267,40 @@ export function recoverSandboxControl(requestId, params = {}) {
     if (!/^[a-f0-9-]{16,64}$/u.test(requestId)) {
         clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'request id is invalid', false, true);
     }
-    const channelDir = params.channelDir ?? process.env.AGENT_INFRA_CONTROL_DIR ?? '/run/agent-infra/control';
+    try {
+        if (!isSandbox()) {
+            const config = loadConfig();
+            const response = recoverSandboxControlFromHost(requestId, {
+                managedRoot: path.join(config.controlBase, config.project),
+                timeoutMs: params.timeoutMs
+            });
+            if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') {
+                clientError('SANDBOX_CONTROL_RESULT_UNKNOWN', 'recovery evidence is unavailable; inspect domain state before retrying', false, true, requestId);
+            }
+            return response;
+        }
+        const channelDir = process.env.AGENT_INFRA_CONTROL_DIR;
+        const statusDir = process.env.AGENT_INFRA_CONTROL_STATUS_DIR;
+        const identity = readSandboxControlIdentitySentinel(statusDir);
+        return recoverSandboxControlFromChannel(requestId, {
+            channelDir, generation: identity.generation, timeoutMs: params.timeoutMs
+        });
+    }
+    catch (error) {
+        if (error instanceof SandboxControlClientError)
+            throw error;
+        const message = error instanceof Error ? error.message : String(error);
+        const code = /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1] ?? 'SANDBOX_CONTROL_RECOVERY_INVALID';
+        clientError(code, 'sandbox control recovery evidence is invalid or unavailable', false, true, requestId);
+    }
+}
+// Low-level channel reader for control integration tests and internal callers
+// that already hold a manifest-bound channel path.
+export function recoverSandboxControlFromChannel(requestId, params) {
+    if (!/^[a-f0-9-]{16,64}$/u.test(requestId)) {
+        clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'request id is invalid', false, true);
+    }
+    const { channelDir } = params;
     const responsePath = path.join(channelDir, 'responses', `${requestId}.json`);
     const deadline = Date.now() + (params.timeoutMs ?? 30_000);
     let accepted = false;
@@ -284,7 +323,7 @@ export function recoverSandboxControl(requestId, params = {}) {
             try {
                 // The request-specific terminal proves the broker claimed the request; preserve recovery evidence if marker cleanup won the race.
                 accepted = true;
-                response = readPublishedResponse(raw, requestId, channelDir, accepted);
+                response = readPublishedResponse(raw, requestId, channelDir, accepted, params.generation);
                 malformedResponseRaw = null;
             }
             catch (error) {
@@ -298,15 +337,24 @@ export function recoverSandboxControl(requestId, params = {}) {
                 else if (now - malformedResponseObservedAt >= SANDBOX_CONTROL_RESPONSE_SETTLE_MS) {
                     clientError('SANDBOX_CONTROL_RESPONSE_INVALID', 'broker response remained malformed', false, accepted, requestId);
                 }
-                sleep(25);
+                const remainingMs = deadline - Date.now();
+                if (remainingMs > 0)
+                    sleep(Math.min(25, Math.ceil(remainingMs)));
                 continue;
             }
-            if (response.phase === 'accepted')
+            if (response.phase === 'accepted') {
                 accepted = true;
-            else
+            }
+            else if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') {
+                accepted = true;
+            }
+            else {
                 return response;
+            }
         }
-        sleep(25);
+        const remainingMs = deadline - Date.now();
+        if (remainingMs > 0)
+            sleep(Math.min(25, Math.ceil(remainingMs)));
     }
     clientError('SANDBOX_CONTROL_RESULT_UNKNOWN', 'request did not produce a final result; inspect domain state before retrying', false, accepted, requestId);
 }
@@ -326,7 +374,7 @@ export function requestSandboxControl(params) {
     const auth = authority(params);
     const issuedAt = Date.now();
     const request = {
-        version: 3, id: randomUUID(), ...auth, issuedAt,
+        version: 4, id: randomUUID(), ...auth, issuedAt,
         expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
         family: params.family, args: params.args,
         controllerProcess: null,
@@ -341,9 +389,8 @@ export function requestSandboxTaskFinalization(params) {
     const auth = authority(params);
     const issuedAt = Date.now();
     const id = randomUUID();
-    const handoffSha256 = (params.prepareHandoff ?? (() => '0'.repeat(64)))({ generation: auth.generation, requestId: id });
     const request = {
-        version: 3,
+        version: 4,
         id,
         ...auth,
         issuedAt,
@@ -351,12 +398,47 @@ export function requestSandboxTaskFinalization(params) {
         family: 'task-finalization',
         operation: 'complete',
         agent,
-        handoffSha256,
         args: [],
         controllerProcess: null,
         controllerProof: null
     };
-    return exchangeSandboxControl(request, params);
+    let response;
+    try {
+        response = exchangeSandboxControl(request, params);
+    }
+    catch (error) {
+        if (!(error instanceof SandboxControlClientError)
+            || error.detail.code !== 'SANDBOX_CONTROL_RESULT_UNKNOWN'
+            || !error.accepted || !error.requestId)
+            throw error;
+        return recoverAcceptedTaskFinalization(error.requestId, params);
+    }
+    if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN') {
+        return recoverAcceptedTaskFinalization(response.id, params);
+    }
+    return response;
+}
+export function recoverAcceptedTaskFinalization(requestId, params, recover = recoverSandboxControl) {
+    const deadline = Date.now() + (params.recoveryBudgetMs ?? SANDBOX_TASK_FINALIZATION_RECOVERY_BUDGET_MS);
+    while (Date.now() < deadline) {
+        const timeoutMs = Math.min(30_000, deadline - Date.now());
+        if (timeoutMs <= 0)
+            break;
+        try {
+            const response = recover(requestId, { timeoutMs });
+            if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN')
+                continue;
+            return response;
+        }
+        catch (error) {
+            if (error instanceof SandboxControlClientError
+                && error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN'
+                && error.requestId === requestId)
+                continue;
+            throw error;
+        }
+    }
+    clientError('SANDBOX_CONTROL_RESULT_UNKNOWN', 'accepted finalization request remained unknown after the automatic recovery budget; inspect the receipt and resume by request id', false, true, requestId);
 }
 function exactKeys(value, keys) {
     return Object.keys(value).sort().join(',') === [...keys].sort().join(',');
@@ -456,7 +538,7 @@ function requestCodexController(params) {
     const auth = authority(params);
     const issuedAt = Date.now();
     const request = {
-        version: 3,
+        version: 4,
         id: randomUUID(),
         ...auth,
         issuedAt,
@@ -503,7 +585,7 @@ export function requestSandboxTaskCreate(params) {
     const auth = authority(params);
     const issuedAt = Date.now();
     const request = {
-        version: 3, id: randomUUID(), ...auth, issuedAt,
+        version: 4, id: randomUUID(), ...auth, issuedAt,
         expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
         family: 'task-create', candidate: params.candidate,
         controllerProcess: null,

package/dist/lib/sandbox/control/executor.js

@@ -2,10 +2,10 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
-import { homedir } from 'node:os';
 import { getProcessStartTime } from '../../server/process-state.js';
 import { createTask, projectTaskCreateResult, taskCreateExitCode, taskCreateFailure } from '../../task/create-service.js';
 import { applyTaskFinalization } from '../../task/finalization.js';
+import { serializeTaskFinalizationEnvelope } from '../../task/finalization-envelope.js';
 import { bindSandboxControlTask, validateSandboxControlRequest } from './protocol.js';
 import { atomicWriteJson, executionPath, readActiveLease, terminateSandboxControlExecution } from './state.js';
 import { requestAuditFields, resultAuditFields, appendDiagnosticAudit, createSandboxControlAuditContext, appendCriticalAudit, writeSandboxControlTransition } from './audit.js';
@@ -14,10 +14,6 @@ import { createSandboxExecutorExecutionContext, dispatchTaskControlOperation, pa
 import { assertSandboxControlBrokerOwner, readSandboxControlManifest } from './lifecycle.js';
 import { computeLifecycleBuildIdentity } from '../../agent-clients/adapters/codex-lifecycle/build-identity.js';
 import { closeCodexControllerRegistration, CodexControllerRegistrationError, openCodexControllerRegistration, resolveCodexControllerBinding } from './controller-registration.js';
-import { shareBranchDir } from '../constants.js';
-function handoffDirectory(manifest) {
-    return shareBranchDir({ shareBase: path.join(homedir(), '.agent-infra', 'share', manifest.project) }, manifest.branch);
-}
 function sameBrokerOwner(left, right) {
     return left.version === right.version
         && left.pid === right.pid
@@ -232,7 +228,7 @@ function finalizationResult(result) {
 async function executeRequestInner(manifest, manifestPath, request, options = {}) {
     if (request.family === 'task-create') {
         try {
-            const result = await createTask(request.candidate, { repoRoot: manifest.repoRoot });
+            const result = await (options.createTask ?? createTask)(request.candidate, { repoRoot: manifest.repoRoot });
             return taskCreateExecutionResult(projectTaskCreateResult(result, {
                 requestId: request.id,
                 accepted: true,
@@ -303,7 +299,7 @@ async function executeRequestInner(manifest, manifestPath, request, options = {}
         const parsed = parseTaskControlOperation('task-finalization', [manifest.taskId, 'complete', '--agent', request.agent]);
         if (parsed.family !== 'task-finalization')
             throw new Error('SANDBOX_CONTROL_FINALIZATION_OPERATION_INVALID');
-        const operation = { ...parsed, request: { ...parsed.request, handoffSha256: request.handoffSha256 } };
+        const operation = parsed;
         const result = dispatchTaskControlOperation(createSandboxExecutorExecutionContext({
             repoRoot: manifest.repoRoot,
             worktreeRoot: manifest.worktreeRoot,
@@ -311,8 +307,7 @@ async function executeRequestInner(manifest, manifestPath, request, options = {}
             taskId: manifest.taskId,
             generation: manifest.generation,
             manifestPath,
-            requestId: request.id,
-            handoffDirectory: handoffDirectory(manifest)
+            requestId: request.id
         }), operation);
         return finalizationResult(await result);
     }
@@ -333,8 +328,7 @@ async function executeRequestInner(manifest, manifestPath, request, options = {}
         taskId: manifest.taskId,
         generation: manifest.generation,
         manifestPath,
-        requestId: request.id,
-        handoffDirectory: handoffDirectory(manifest)
+        requestId: request.id
     });
     const format = (value) => {
         const result = value;
@@ -456,10 +450,14 @@ export async function runSandboxControlExecutor(requestPath, nonce) {
         result = request.family === 'task-finalization'
             ? {
                 exitCode: 1,
-                stdout: `${JSON.stringify({
-                    version: 1, status: 'failed', changed: false, accepted: true, result: null,
+                stdout: serializeTaskFinalizationEnvelope({
+                    status: code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 'unknown' : 'failed',
+                    changed: code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? null : false,
+                    accepted: true,
+                    requestId: request.id,
+                    result: null,
                     error: { code, message: detail, retryable: false }
-                })}\n`,
+                }),
                 stderr: ''
             }
             : request.family === 'task-create'

package/dist/lib/sandbox/control/host-recovery.js

@@ -0,0 +1,218 @@
+import { createHash } from 'node:crypto';
+import fs from 'node:fs';
+import path from 'node:path';
+import { readSandboxControlManifest } from './lifecycle.js';
+import { identityDigest } from './identity-sentinel.js';
+import { readSandboxControlPayload, readSandboxControlResultEvidence } from './state.js';
+import { taskCreateOutputUnavailableResult } from '../../task/create-service.js';
+const REQUEST_ID = /^[a-f0-9-]{16,64}$/u;
+function unknown(requestId) {
+    return {
+        version: 2, id: requestId, phase: 'rejected', exitCode: null, stdout: '', stderr: '',
+        error: { code: 'SANDBOX_CONTROL_RESULT_UNKNOWN', message: 'SANDBOX_CONTROL_RESULT_UNKNOWN: recovery evidence is unavailable', retryable: false },
+        outputState: 'unavailable', payload: null
+    };
+}
+function manifestDigest(manifest) {
+    return identityDigest({
+        version: 1, mode: manifest.mode, taskId: manifest.taskId,
+        generation: manifest.generation, controlRootId: manifest.controlRootId
+    });
+}
+function managedManifestPaths(managedRoot) {
+    if (!fs.existsSync(managedRoot))
+        return [];
+    const rootStat = fs.lstatSync(managedRoot);
+    if (!rootStat.isDirectory() || rootStat.isSymbolicLink())
+        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+    const result = [];
+    for (const container of fs.readdirSync(managedRoot, { withFileTypes: true })) {
+        if (!container.isDirectory() || container.isSymbolicLink())
+            continue;
+        const containerPath = path.join(managedRoot, container.name);
+        for (const identity of fs.readdirSync(containerPath, { withFileTypes: true })) {
+            if (!identity.isDirectory() || identity.isSymbolicLink() || !/^[a-f0-9]{16}$/u.test(identity.name))
+                continue;
+            result.push(path.join(containerPath, identity.name, 'manifest.json'));
+        }
+    }
+    return result;
+}
+function assertDirectory(directory) {
+    const stat = fs.lstatSync(directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink())
+        throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+}
+function readAudit(manifest) {
+    const root = path.dirname(path.resolve(manifest.publicStatusDir));
+    const records = [];
+    for (const file of [path.join(root, 'audit.ndjson.1'), path.join(root, 'audit.ndjson')]) {
+        if (!fs.existsSync(file))
+            continue;
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            throw new Error('SANDBOX_CONTROL_AUDIT_INVALID');
+        for (const line of fs.readFileSync(file, 'utf8').split('\n').filter(Boolean)) {
+            let value;
+            try {
+                value = JSON.parse(line);
+            }
+            catch {
+                throw new Error('SANDBOX_CONTROL_AUDIT_INVALID');
+            }
+            if (!value || typeof value !== 'object' || Array.isArray(value))
+                throw new Error('SANDBOX_CONTROL_AUDIT_INVALID');
+            records.push(value);
+        }
+    }
+    return records;
+}
+function auditProof(manifest, requestId) {
+    const digest = manifestDigest(manifest);
+    const related = readAudit(manifest).filter((record) => record.requestId === requestId);
+    for (const record of related) {
+        if (record.generation !== manifest.generation || record.identityDigest !== digest) {
+            throw new Error('SANDBOX_CONTROL_AUDIT_IDENTITY_MISMATCH');
+        }
+    }
+    if (!related.some((record) => record.event === 'accepted-authorized'
+        && record.version === 2 && record.phase === 'accepted-authorized'))
+        return [];
+    return related;
+}
+function publishedEvidence(records, generation) {
+    const publications = records.filter((record) => record.event === 'executor-result-published');
+    let selected = null;
+    let selectedSummary = null;
+    for (const record of publications) {
+        if (record.version !== 2 || record.requestGeneration !== generation
+            || !Number.isSafeInteger(record.exitCode)
+            || !Number.isSafeInteger(record.outputBytes) || !Number.isSafeInteger(record.errorBytes)
+            || typeof record.outputDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(record.outputDigest)
+            || typeof record.errorDigest !== 'string' || !/^[a-f0-9]{64}$/u.test(record.errorDigest)) {
+            throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_INVALID');
+        }
+        const summary = JSON.stringify([
+            record.requestFamily ?? null, record.requestGeneration, record.exitCode,
+            record.outputBytes, record.errorBytes, record.outputDigest, record.errorDigest
+        ]);
+        if (selectedSummary !== null && summary !== selectedSummary) {
+            throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_CONFLICT');
+        }
+        selected ??= record;
+        selectedSummary ??= summary;
+    }
+    return selected;
+}
+function verifiedResponse(manifest, requestId, records) {
+    assertDirectory(manifest.channelDir);
+    const responsesDir = path.join(manifest.channelDir, 'responses');
+    assertDirectory(responsesDir);
+    const responsePath = path.join(responsesDir, `${requestId}.json`);
+    if (!fs.existsSync(responsePath))
+        return null;
+    const responseStat = fs.lstatSync(responsePath);
+    if (!responseStat.isFile() || responseStat.isSymbolicLink())
+        throw new Error('SANDBOX_CONTROL_RESPONSE_INVALID');
+    const raw = fs.readFileSync(responsePath, 'utf8');
+    let response;
+    try {
+        response = JSON.parse(raw);
+    }
+    catch {
+        throw new Error('SANDBOX_CONTROL_RESPONSE_INVALID');
+    }
+    if (!response || response.version !== 2 || response.id !== requestId)
+        throw new Error('SANDBOX_CONTROL_RESPONSE_INVALID');
+    if (response.phase === 'accepted')
+        return null;
+    if (!['completed', 'rejected'].includes(response.phase))
+        throw new Error('SANDBOX_CONTROL_RESPONSE_INVALID');
+    if (response.phase === 'rejected' && response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN')
+        return unknown(requestId);
+    const evidencePath = path.join(manifest.processingDir, requestId, 'result.json');
+    const published = publishedEvidence(records, manifest.generation);
+    if (!published)
+        return unknown(requestId);
+    let evidence = null;
+    if (fs.existsSync(evidencePath)) {
+        evidence = readSandboxControlResultEvidence(evidencePath);
+        if (evidence.id !== requestId || evidence.generation !== manifest.generation
+            || evidence.exitCode !== published.exitCode || evidence.stdoutBytes !== published.outputBytes
+            || evidence.stderrBytes !== published.errorBytes || evidence.stdoutSha256 !== published.outputDigest
+            || evidence.stderrSha256 !== published.errorDigest)
+            throw new Error('SANDBOX_CONTROL_RESULT_EVIDENCE_INVALID');
+    }
+    if (response.phase !== 'completed' || response.exitCode !== published.exitCode || response.error !== null) {
+        throw new Error('SANDBOX_CONTROL_RESPONSE_INVALID');
+    }
+    if (response.outputState === undefined) {
+        const stdout = response.stdout;
+        const stderr = response.stderr;
+        if (response.payload !== undefined
+            || Buffer.byteLength(stdout, 'utf8') !== published.outputBytes
+            || Buffer.byteLength(stderr, 'utf8') !== published.errorBytes
+            || createHash('sha256').update(stdout, 'utf8').digest('hex') !== published.outputDigest
+            || createHash('sha256').update(stderr, 'utf8').digest('hex') !== published.errorDigest) {
+            throw new Error('SANDBOX_CONTROL_RESPONSE_INVALID');
+        }
+        return response;
+    }
+    if (response.outputState === 'available') {
+        const payload = readSandboxControlPayload(path.join(manifest.channelDir, 'responses', `${requestId}.payload.json`));
+        if (payload.id !== requestId || payload.generation !== manifest.generation
+            || payload.stdoutBytes !== published.outputBytes || payload.stderrBytes !== published.errorBytes
+            || payload.stdoutSha256 !== published.outputDigest || payload.stderrSha256 !== published.errorDigest
+            || response.payload?.id !== payload.id || response.payload?.generation !== payload.generation
+            || response.payload?.stdoutBytes !== payload.stdoutBytes || response.payload?.stderrBytes !== payload.stderrBytes
+            || response.payload?.stdoutSha256 !== payload.stdoutSha256 || response.payload?.stderrSha256 !== payload.stderrSha256) {
+            throw new Error('SANDBOX_CONTROL_RESPONSE_INVALID');
+        }
+        return { ...response, stdout: payload.stdout, stderr: payload.stderr };
+    }
+    const expectedStdout = published.requestFamily === 'task-create'
+        ? `${JSON.stringify(taskCreateOutputUnavailableResult(requestId))}\n`
+        : '';
+    if (response.outputState !== 'unavailable' || response.payload !== null
+        || response.stdout !== expectedStdout || response.stderr !== 'SANDBOX_CONTROL_OUTPUT_UNAVAILABLE: broker restarted after executor completion\n'
+        && response.stderr !== 'SANDBOX_CONTROL_OUTPUT_UNAVAILABLE: output payload was not retained\n') {
+        throw new Error('SANDBOX_CONTROL_RESPONSE_INVALID');
+    }
+    return response;
+}
+export function recoverSandboxControlFromHost(requestId, params) {
+    if (!REQUEST_ID.test(requestId))
+        throw new Error('SANDBOX_CONTROL_REQUEST_INVALID');
+    const deadline = Date.now() + (params.timeoutMs ?? 30_000);
+    let candidates = [];
+    while (Date.now() < deadline) {
+        candidates = [];
+        for (const manifestPath of managedManifestPaths(params.managedRoot)) {
+            let manifest;
+            try {
+                manifest = readSandboxControlManifest(manifestPath);
+            }
+            catch {
+                throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+            }
+            if (manifest.project !== path.basename(path.resolve(params.managedRoot)) || !manifest.generation) {
+                throw new Error('SANDBOX_CONTROL_MANIFEST_INVALID');
+            }
+            const records = auditProof(manifest, requestId);
+            if (records.length)
+                candidates.push({ manifest, records });
+        }
+        if (candidates.length > 1)
+            throw new Error('SANDBOX_CONTROL_RECOVERY_AMBIGUOUS');
+        if (candidates.length === 1) {
+            const response = verifiedResponse(candidates[0].manifest, requestId, candidates[0].records);
+            if (response)
+                return response;
+        }
+        const remainingMs = deadline - Date.now();
+        if (remainingMs > 0)
+            Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, Math.min(25, remainingMs));
+    }
+    return unknown(requestId);
+}
+//# sourceMappingURL=host-recovery.js.map

package/dist/lib/sandbox/control/protocol.js

@@ -111,7 +111,7 @@ export function validateSandboxControlRequest(value, manifest, options = {}) {
         fail('SANDBOX_CONTROL_REQUEST_INVALID', 'request must be an object');
     }
     const request = value;
-    if (request.version !== 3 || typeof request.id !== 'string'
+    if (request.version !== 4 || typeof request.id !== 'string'
         || !/^[a-f0-9-]{16,64}$/.test(request.id) || request.token !== manifest.token
         || typeof request.family !== 'string' || !isSandboxControlFamily(request.family)
         || !Number.isSafeInteger(request.issuedAt) || !Number.isSafeInteger(request.expiresAt))
@@ -158,12 +158,11 @@ export function validateSandboxControlRequest(value, manifest, options = {}) {
         return request;
     }
     if (request.family === 'task-finalization') {
-        const expected = ['agent', 'args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'handoffSha256', 'id', 'issuedAt', 'operation', 'token', 'version'];
+        const expected = ['agent', 'args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'operation', 'token', 'version'];
         if (Object.keys(request).sort().join(',') !== expected.sort().join(',')
             || request.operation !== 'complete'
             || !Array.isArray(request.args) || request.args.length !== 0
             || typeof request.agent !== 'string' || normalizeAgentToken(request.agent) !== request.agent
-            || typeof request.handoffSha256 !== 'string' || !/^[a-f0-9]{64}$/u.test(request.handoffSha256)
             || request.controllerProcess !== null || request.controllerProof !== null) {
             fail('SANDBOX_CONTROL_REQUEST_INVALID', 'task-finalization request schema or authorization is invalid');
         }

package/dist/lib/sandbox/control/server.js

@@ -20,8 +20,35 @@ import { nextSandboxControlBackoff } from './timing.js';
 import { readTaskFinalizationReceipt } from '../../task/finalization.js';
 import { readCodexControllerRegistration } from './controller-registration.js';
 import { validateSandboxControlIdentity } from './identity-sentinel.js';
-import { mergeSandboxTaskView, taskViewForManifest } from './task-view.js';
+import { mergeSandboxTaskView, taskViewAfterFinalization, taskViewForManifest } from './task-view.js';
 import { taskCreateOutputUnavailableResult } from '../../task/create-service.js';
+async function taskViewForFinalizationResult(manifest, request, result) {
+    if (request.family !== 'task-finalization' || result?.exitCode !== 0 || !manifest.taskId)
+        return null;
+    let receipt = null;
+    for (let attempt = 0; attempt < 100 && !receipt; attempt += 1) {
+        try {
+            receipt = readTaskFinalizationReceipt(manifest.repoRoot, manifest.taskId);
+        }
+        catch {
+            // A missing or temporarily moving task directory is retried before publishing completion.
+        }
+        if (!receipt)
+            await new Promise((resolve) => setTimeout(resolve, 10));
+    }
+    const finalized = taskViewAfterFinalization({
+        taskId: manifest.taskId,
+        generation: manifest.generation,
+        requestId: request.id,
+        receipt
+    });
+    if (finalized.state === 'unknown')
+        return finalized;
+    const canonical = taskViewForManifest({ ...manifest, receipt });
+    return canonical.state === 'current' && canonical.observedSource === 'completed'
+        ? canonical
+        : finalized;
+}
 function appendBrokerAudit(manifest, event, fields = {}) {
     appendDiagnosticAudit(manifest, event, { source: 'broker', ...fields });
 }
@@ -722,6 +749,7 @@ export async function serveSandboxControl(manifestPath, signal = new AbortContro
         // A fresh control root has no previous task-view projection.
     }
     let lastState = '';
+    let lastTaskView = '';
     let lastStatusAt = 0;
     let nextBindingCheckAt = 0;
     let nextContainerHeartbeatAt = Date.now() + timing.containerHeartbeatMs;
@@ -838,6 +866,11 @@ export async function serveSandboxControl(manifestPath, signal = new AbortContro
                 settledExecution = active;
                 active = null;
             }
+            const finalizationView = settledExecution
+                ? await taskViewForFinalizationResult(manifest, settledExecution.request, settledExecution.result)
+                : null;
+            if (finalizationView)
+                taskView = finalizationView;
             let reasonCode = null;
             try {
                 if (!brokerOwns())
@@ -881,9 +914,11 @@ export async function serveSandboxControl(manifestPath, signal = new AbortContro
             }
             const state = reasonCode ? 'parked' : active ? 'busy' : 'healthy';
             const stateKey = `${state}:${reasonCode ?? ''}:${active?.request.id ?? ''}`;
-            if (brokerOwns() && (stateKey !== lastState || now - lastStatusAt >= timing.controlTickMs)) {
+            const taskViewKey = JSON.stringify(taskView);
+            if (brokerOwns() && (stateKey !== lastState || taskViewKey !== lastTaskView || now - lastStatusAt >= timing.controlTickMs)) {
                 writeSandboxControlStatus(manifest, broker, state, reasonCode, active?.request.id ?? null, now, taskView);
                 lastStatusAt = now;
+                lastTaskView = taskViewKey;
             }
             if (brokerOwns() && stateKey !== lastState) {
                 appendBrokerAudit(manifest, 'broker-state', { state, reasonCode, requestId: active?.request.id ?? null });
@@ -1156,6 +1191,11 @@ export async function serveSandboxControl(manifestPath, signal = new AbortContro
                 }
             }
             if (owned && active.result && active.resultEvidenceWritten) {
+                const finalizationView = await taskViewForFinalizationResult(manifest, active.request, active.result);
+                if (finalizationView) {
+                    taskView = finalizationView;
+                    writeSandboxControlStatus(manifest, broker, 'healthy', null, null, Date.now(), taskView);
+                }
                 if (publishExecutionResult(manifest, active.request, active.result, brokerOwns)) {
                     if (brokerOwns()) {
                         removeAcceptedResponse(manifest, active.request.id);