@fitlab-ai/agent-infra 0.11.10 → 0.11.11

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);

package/dist/lib/sandbox/environment.js

@@ -0,0 +1,150 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readSandboxControlIdentitySentinel } from './control/identity-sentinel.js';
+export const SANDBOX_CONTROL_STATUS_MOUNT = '/run/agent-infra/control-status';
+const TASK_MARKER_KEYS = [
+    'AGENT_INFRA_SANDBOX',
+    'AGENT_INFRA_TASK_ID',
+    'AGENT_INFRA_CONTROL_TOKEN',
+    'AGENT_INFRA_CONTROL_GENERATION',
+    'AGENT_INFRA_CONTROL_DIR',
+    'AGENT_INFRA_CONTROL_STATUS_DIR',
+    'AGENT_INFRA_RUNTIME_DIR'
+];
+const TASK_CONTROL_MARKER_KEYS = [
+    'AGENT_INFRA_CONTROL_TOKEN',
+    'AGENT_INFRA_CONTROL_GENERATION',
+    'AGENT_INFRA_CONTROL_DIR',
+    'AGENT_INFRA_CONTROL_STATUS_DIR'
+];
+const TASK_CONTROL_CONFIG_KEYS = [
+    ...TASK_CONTROL_MARKER_KEYS,
+    'AGENT_INFRA_CONTROL_ROOT_ID'
+];
+function nativeDirectoryProbe(candidate) {
+    if (process.platform === 'linux') {
+        try {
+            // Linux sandboxes use this fixed mount as a host/sandbox trust anchor.
+            // Do not let a preload replace the ordinary node:fs probe and select host routing.
+            const binding = process.binding('fs');
+            if (!Function.prototype.toString.call(binding.internalModuleStat).includes('[native code]'))
+                return 'unknown';
+            const result = binding.internalModuleStat(candidate);
+            if (result === 1)
+                return 'present';
+            if (result === -2)
+                return 'absent';
+            return 'unknown';
+        }
+        catch {
+            return 'unknown';
+        }
+    }
+    try {
+        const stat = fs.lstatSync(candidate);
+        return stat.isDirectory() && !stat.isSymbolicLink() ? 'present' : 'unknown';
+    }
+    catch (error) {
+        if (error && typeof error === 'object' && 'code' in error
+            && (error.code === 'ENOENT' || error.code === 'ENOTDIR'))
+            return 'absent';
+        return 'unknown';
+    }
+}
+export function sandboxTaskMarkerState(env) {
+    const present = (key) => Boolean(env[key]);
+    const sandbox = env.AGENT_INFRA_SANDBOX === '1';
+    const taskId = present('AGENT_INFRA_TASK_ID');
+    const controls = TASK_CONTROL_MARKER_KEYS.every(present);
+    const runtime = present('AGENT_INFRA_RUNTIME_DIR');
+    const any = TASK_MARKER_KEYS.some(present);
+    if (!any)
+        return 'none';
+    if (!sandbox || !controls)
+        return 'incomplete';
+    if (taskId && runtime)
+        return 'task-bound';
+    if (!taskId && !runtime)
+        return 'branch-only';
+    return 'incomplete';
+}
+export function hasTaskBoundMarker(env = process.env) {
+    return sandboxTaskMarkerState(env) === 'task-bound';
+}
+export function hasSandboxControlMarker(env = process.env) {
+    return TASK_CONTROL_MARKER_KEYS.some((key) => Boolean(env[key]));
+}
+export function resolveSandboxControlTransport(env = process.env, options = {}) {
+    const markerState = sandboxTaskMarkerState(env);
+    const hasAnyMarker = markerState !== 'none'
+        || Boolean(env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING)
+        || Boolean(env.AGENT_INFRA_EXECUTOR_MANIFEST);
+    const fixedStatusDir = options.statusMountPath ?? SANDBOX_CONTROL_STATUS_MOUNT;
+    const fixedStatusProbe = path.isAbsolute(fixedStatusDir)
+        ? nativeDirectoryProbe(fixedStatusDir) : 'absent';
+    if (fixedStatusProbe === 'unknown') {
+        return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_UNAVAILABLE' };
+    }
+    const fixedStatusMounted = fixedStatusProbe === 'present';
+    if (!hasAnyMarker) {
+        return fixedStatusMounted
+            ? { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' }
+            : { kind: 'direct-host', reasonCode: null };
+    }
+    if (markerState === 'incomplete') {
+        return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' };
+    }
+    const hasCompleteConfig = TASK_CONTROL_CONFIG_KEYS.every((key) => Boolean(env[key]));
+    if (!hasCompleteConfig) {
+        return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' };
+    }
+    const configuredStatusDir = env.AGENT_INFRA_CONTROL_STATUS_DIR;
+    const configuredStatusProbe = configuredStatusDir && path.isAbsolute(configuredStatusDir)
+        ? nativeDirectoryProbe(configuredStatusDir) : 'absent';
+    if (configuredStatusProbe === 'unknown') {
+        return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_UNAVAILABLE' };
+    }
+    const statusDir = configuredStatusDir && path.isAbsolute(configuredStatusDir)
+        ? configuredStatusProbe === 'present' ? configuredStatusDir : null
+        : fixedStatusMounted ? fixedStatusDir : null;
+    const statusMounted = statusDir !== null;
+    if (env.AGENT_INFRA_EXECUTOR_MANIFEST || env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING) {
+        return { kind: 'fail-closed', reasonCode: 'TASK_CONTROL_TRANSPORT_INVALID' };
+    }
+    const taskBound = Boolean(env.AGENT_INFRA_TASK_ID);
+    const runtime = Boolean(env.AGENT_INFRA_RUNTIME_DIR);
+    if (statusMounted) {
+        let sentinel;
+        try {
+            sentinel = readSandboxControlIdentitySentinel(statusDir);
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : '';
+            return { kind: 'fail-closed', reasonCode: message.endsWith('MISSING')
+                    ? 'SANDBOX_CONTROL_IDENTITY_MISSING'
+                    : 'SANDBOX_CONTROL_IDENTITY_MALFORMED' };
+        }
+        if (sentinel.generation !== env.AGENT_INFRA_CONTROL_GENERATION) {
+            return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_GENERATION_MISMATCH' };
+        }
+        if (sentinel.controlRootId !== env.AGENT_INFRA_CONTROL_ROOT_ID) {
+            return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_ROOT_ID_MISMATCH' };
+        }
+        if (sentinel.mode === 'task-bound'
+            && (sentinel.taskId !== env.AGENT_INFRA_TASK_ID || !runtime)) {
+            return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_TOPOLOGY_MISMATCH' };
+        }
+        if (sentinel.mode === 'branch-only' && (taskBound || runtime)) {
+            return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_TOPOLOGY_MISMATCH' };
+        }
+        return { kind: options.localWorkflow ? 'sandbox-local' : 'broker-client', reasonCode: null };
+    }
+    return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_MISSING' };
+}
+export function isSandbox(env = process.env, options = {}) {
+    const decision = resolveSandboxControlTransport(env, options);
+    if (decision.kind === 'fail-closed')
+        throw new Error(decision.reasonCode ?? 'TASK_CONTROL_TRANSPORT_INVALID');
+    return decision.kind !== 'direct-host';
+}
+//# sourceMappingURL=environment.js.map

package/dist/lib/sandbox/recovery.js

@@ -567,6 +567,13 @@ function expectedMounts(params) {
         hostPaths: toolConfigDirCandidates(tool, config.project, branch),
         expectedRW: true
     }));
+    const hostState = tools.flatMap((tool) => (tool.hostStateMounts ?? []).map(({ hostSubdir, containerSubpath }) => ({
+        path: path.posix.join(tool.containerMount, containerSubpath),
+        expectedType: 'bind',
+        hostPaths: toolConfigDirCandidates(tool, config.project, branch)
+            .map((candidate) => path.join(candidate, hostSubdir)),
+        expectedRW: true
+    })));
     const staging = tools.flatMap((tool) => (tool.tmpfs?.seed ?? []).flatMap((seedEntry, index) => {
         const stagingPath = `/run/agent-infra/tmpfs-seeds/${tool.id}/${index}`;
         if (!actualMounts.has(stagingPath))
@@ -583,6 +590,7 @@ function expectedMounts(params) {
         ...core,
         ...persistentTools,
         ...live,
+        ...hostState,
         ...staging,
         ...tools
             .filter((tool) => tool.tmpfs)

package/dist/lib/sandbox/workspace-identity.js

@@ -79,20 +79,6 @@ export function resolveSandboxTarget(requestedRef, repoRoot) {
     }
     return { requestedRef, branch: requestedRef, workspace: { mode: 'branch-only' } };
 }
-export function resolveSandboxReentryContext(params) {
-    if (params.target.workspace.mode !== 'branch-only'
-        || params.containerWorkspace.mode !== 'task-bound') {
-        return { workspace: params.target.workspace, reentry: 'standard' };
-    }
-    const task = resolveTaskWorkspace(params.containerWorkspace.taskId, params.repoRoot);
-    if (task.state !== 'completed' || task.branch !== params.target.branch) {
-        return { workspace: params.target.workspace, reentry: 'standard' };
-    }
-    return {
-        workspace: { mode: 'task-bound', taskId: task.taskId },
-        reentry: 'completed'
-    };
-}
 export function resolveSandboxCleanupTarget(requestedRef, repoRoot, options = {}) {
     if (isRemovedHashShortIdInput(requestedRef)) {
         throw new Error(`Invalid task short id '${requestedRef}': task short ids must use bare digits`);

package/dist/lib/sandbox/workspace-view.js

@@ -1,6 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { resolveTaskWorkspace } from './task-resolver.js';
 import { createSandboxControlIdentitySentinel, writeSandboxControlIdentitySentinel } from './control/identity-sentinel.js';
 export const SANDBOX_WORKSPACE_VIEW_STATES = Object.freeze([
     'active',
@@ -73,15 +74,38 @@ function assertSafeMountTargetPath(target, worktreeRoot, canonicalWorktreeRoot)
 export function assertSandboxTaskSource(repoRoot, taskId) {
     if (!/^TASK-\d{8}-\d{6}$/.test(taskId))
         throw new Error('SANDBOX_TASK_SOURCE_INVALID');
-    const activeRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace', 'active'));
-    const source = path.join(activeRoot, taskId);
+    const activeSource = path.join(repoRoot, '.agents', 'workspace', 'active', taskId);
+    try {
+        const stat = fs.lstatSync(activeSource);
+        if (!stat.isDirectory() || stat.isSymbolicLink()) {
+            throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${activeSource} must be a real directory`);
+        }
+        const canonical = fs.realpathSync.native(activeSource);
+        const activeRoot = fs.realpathSync.native(path.dirname(activeSource));
+        const workspaceRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace'));
+        const relative = path.relative(workspaceRoot, canonical);
+        if (path.dirname(canonical) !== activeRoot || relative.startsWith('..') || path.isAbsolute(relative)) {
+            throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${activeSource} escapes the task workspace`);
+        }
+        return canonical;
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    const task = resolveTaskWorkspace(taskId, repoRoot);
+    const source = task.state === 'archive'
+        ? path.dirname(path.dirname(task.taskMd))
+        : path.dirname(task.taskMd);
     const stat = fs.lstatSync(source);
     if (!stat.isDirectory() || stat.isSymbolicLink()) {
         throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${source} must be a real directory`);
     }
     const canonical = fs.realpathSync.native(source);
-    if (path.dirname(canonical) !== activeRoot) {
-        throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${source} escapes the active workspace`);
+    const workspaceRoot = fs.realpathSync.native(path.join(repoRoot, '.agents', 'workspace'));
+    const relative = path.relative(workspaceRoot, canonical);
+    if (path.basename(canonical) !== taskId || relative.startsWith('..') || path.isAbsolute(relative)) {
+        throw new Error(`SANDBOX_TASK_SOURCE_INVALID: ${source} escapes the task workspace`);
     }
     return canonical;
 }
@@ -114,10 +138,13 @@ export function materializeSandboxWorkspaceView(params) {
         fs.mkdirSync(hostPath, { recursive: true, mode: 0o700 });
     }
     const active = path.join(root, 'active');
+    const shortId = params.identity.mode === 'task-bound' && 'shortId' in params.identity
+        ? params.identity.shortId
+        : null;
     const registry = {
         version: 1,
-        ids: params.identity.mode === 'task-bound'
-            ? { [params.identity.shortId]: params.identity.taskId }
+        ids: shortId !== null && params.identity.mode === 'task-bound'
+            ? { [shortId]: params.identity.taskId }
             : {}
     };
     fs.writeFileSync(path.join(active, '.short-ids.json'), `${JSON.stringify(registry)}\n`, {

package/dist/lib/task/artifact-command.js

@@ -14,7 +14,7 @@ export function parseArtifactCommand(args) {
     }
     const fields = {};
     const allowed = {
-        inspect: ['--family', '--source-finding', '--source-artifact', '--source-sha256'],
+        inspect: ['--family', '--reason-code', '--source-finding', '--source-artifact', '--source-sha256'],
         init: ['--family', '--artifact', '--locale'],
         'preflight': ['--family', '--artifact'],
         'finalize-local': ['--family', '--artifact']
@@ -37,9 +37,13 @@ export function parseArtifactCommand(args) {
     const locale = fields['--locale'];
     if (locale !== undefined && locale !== 'zh-CN' && locale !== 'en')
         throw new Error("option '--locale' must be 'zh-CN' or 'en'");
+    const reasonCode = fields['--reason-code'];
+    if (reasonCode !== undefined && !['user-request', 'new-requirement', 'upstream-fact-doubt', 'review-finding', 'manual-review-supplement', 'retry', 'validation-rerun'].includes(reasonCode)) {
+        throw new Error("option '--reason-code' is invalid");
+    }
     return {
         taskRef, operation: operation, family: fields['--family'] ?? '',
-        artifact: fields['--artifact'] ?? '', locale,
+        artifact: fields['--artifact'] ?? '', locale, reasonCode: reasonCode,
         sourceFinding: fields['--source-finding'], sourceArtifact: fields['--source-artifact'],
         sourceSha256: fields['--source-sha256']
     };
@@ -51,6 +55,7 @@ export function executeArtifactCommand(command, options = {}) {
     if (operation === 'inspect') {
         const result = resolveArtifactContext(taskRef, family, {
             repoRoot: options.repoRoot,
+            reasonCode: command.reasonCode,
             sourceFinding: command.sourceFinding,
             sourceArtifact: command.sourceArtifact,
             sourceSha256: command.sourceSha256

package/dist/lib/task/artifact-lifecycle.js

@@ -292,7 +292,8 @@ const OPTIONAL_CONTEXT = {
 function hasSelectionEvidence(content, family, options, context, pathState) {
     if (options.sourceFinding && options.sourceArtifact && options.sourceSha256)
         return true;
-    if (options.reasonCode === 'new-requirement' || options.reasonCode === 'upstream-fact-doubt')
+    if (options.reasonCode === 'new-requirement' || options.reasonCode === 'upstream-fact-doubt'
+        || family === 'review-code' && options.reasonCode === 'manual-review-supplement')
         return true;
     if ((family === 'plan' || family === 'code') && context.latest) {
         const latestInputs = Object.fromEntries(context.inputs.map((input) => [input.family, input.name]));

package/dist/lib/task/capabilities.js

@@ -17,7 +17,7 @@ import { inspectArtifactDirectory } from './artifact-lifecycle.js';
 import { executionInputsMatchLatest as executionReceiptsMatchLatest } from './execution-inputs.js';
 const ARTIFACT_AUDIT_FAMILIES = new Set(['analysis', 'review-analysis', 'plan', 'review-plan', 'code', 'review-code']);
 const REASONS = new Set([
-    'user-request', 'new-requirement', 'upstream-fact-doubt', 'review-finding', 'retry', 'validation-rerun'
+    'user-request', 'new-requirement', 'upstream-fact-doubt', 'review-finding', 'manual-review-supplement', 'retry', 'validation-rerun'
 ]);
 function deny(reasonCode, ...evidence) {
     return { allowed: false, reasonCode, evidence };
@@ -40,6 +40,9 @@ function canStart(action, facts, trigger) {
         return deny('TRIGGER_REQUEST_ID_REQUIRED');
     if (!REASONS.has(trigger.reasonCode))
         return deny('TRIGGER_REASON_INVALID');
+    if (trigger.reasonCode === 'manual-review-supplement' && (action !== 'review-code' || trigger.initiator !== 'human')) {
+        return deny('MANUAL_REVIEW_SUPPLEMENT_REQUIRES_HUMAN_REVIEW_CODE');
+    }
     if (trigger.sourceArtifact && !trigger.sourceSha256)
         return deny('SOURCE_ARTIFACT_HASH_REQUIRED');
     if (trigger.sourceSha256 && !trigger.sourceArtifact)