@fitlab-ai/agent-infra 0.9.13 → 0.9.14

package/dist/lib/sandbox/control/task-view.js

@@ -0,0 +1,183 @@
+import fs from 'node:fs';
+import path from 'node:path';
+export const SANDBOX_TASK_VIEW_STATES = ['not-applicable', 'current', 'finalized-stale', 'unknown'];
+export const SANDBOX_TASK_VIEW_SOURCES = ['active', 'completed', 'unknown'];
+function invalidView(message) {
+    return new Error(`SANDBOX_TASK_VIEW_INVALID: ${message}`);
+}
+function receiptIdentity(value, generation, requestId) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const receipt = value;
+    const binding = receipt.controlBinding;
+    if (!binding || typeof binding !== 'object' || Array.isArray(binding))
+        return null;
+    const controlBinding = binding;
+    if (receipt.version !== 2 || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
+        || !Number.isSafeInteger(receipt.revision) || receipt.revision < 0
+        || receipt.lifecycle !== 'done'
+        || controlBinding.generation !== generation
+        || typeof controlBinding.requestId !== 'string'
+        || !/^[a-f0-9-]{16,64}$/u.test(controlBinding.requestId)
+        || (requestId !== undefined && controlBinding.requestId !== requestId))
+        return null;
+    return {
+        receiptId: receipt.receiptId,
+        revision: receipt.revision,
+        generation,
+        requestId: controlBinding.requestId
+    };
+}
+export function parseSandboxTaskView(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw invalidView('taskView must be an object');
+    const view = value;
+    const receipt = view.receipt === null ? null : parseSandboxTaskViewReceipt(view.receipt);
+    if (!SANDBOX_TASK_VIEW_STATES.includes(view.state)
+        || (view.taskId !== null && typeof view.taskId !== 'string')
+        || (view.observedSource !== null && !SANDBOX_TASK_VIEW_SOURCES.includes(view.observedSource))
+        || (view.reasonCode !== null && typeof view.reasonCode !== 'string')
+        || (view.receipt !== null && receipt === null)) {
+        throw invalidView('taskView schema is invalid');
+    }
+    if (view.state === 'not-applicable' && (view.taskId !== null || view.observedSource !== null || view.receipt !== null)) {
+        throw invalidView('not-applicable taskView cannot carry task evidence');
+    }
+    if (view.state === 'current' && (view.taskId === null || view.observedSource === null)) {
+        throw invalidView('current taskView requires taskId and observedSource');
+    }
+    if (view.state === 'current' && view.observedSource === 'completed' && view.receipt === null) {
+        throw invalidView('completed current taskView requires receipt');
+    }
+    if (view.state === 'finalized-stale' && (view.taskId === null || view.receipt === null)) {
+        throw invalidView('finalized-stale taskView requires taskId and receipt');
+    }
+    return view;
+}
+function parseSandboxTaskViewReceipt(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return null;
+    const receipt = value;
+    if (Object.keys(receipt).sort().join(',') !== 'generation,receiptId,requestId,revision'
+        || typeof receipt.receiptId !== 'string' || receipt.receiptId.length === 0
+        || !Number.isSafeInteger(receipt.revision) || receipt.revision < 0
+        || typeof receipt.generation !== 'string' || receipt.generation.length === 0
+        || typeof receipt.requestId !== 'string' || !/^[a-f0-9-]{16,64}$/u.test(receipt.requestId))
+        return null;
+    return receipt;
+}
+export function taskViewForManifest(params) {
+    if (params.mode !== 'task-bound' || !params.taskId) {
+        return { state: 'not-applicable', taskId: null, observedSource: null, receipt: null, reasonCode: null };
+    }
+    const active = path.join(params.repoRoot, '.agents', 'workspace', 'active', params.taskId, 'task.md');
+    const completed = path.join(params.repoRoot, '.agents', 'workspace', 'completed', params.taskId, 'task.md');
+    const activeExists = fs.existsSync(active);
+    const completedExists = fs.existsSync(completed);
+    if (activeExists === completedExists) {
+        return {
+            state: 'unknown', taskId: params.taskId,
+            observedSource: activeExists ? 'unknown' : null,
+            receipt: null, reasonCode: activeExists ? 'SANDBOX_TASK_VIEW_SOURCE_CONFLICT' : 'SANDBOX_TASK_VIEW_SOURCE_MISSING'
+        };
+    }
+    const source = completedExists ? 'completed' : 'active';
+    const receipt = receiptIdentity(params.receipt, params.generation);
+    const receiptProvided = params.receipt !== undefined && params.receipt !== null;
+    if (source === 'completed' && receipt) {
+        return { state: 'current', taskId: params.taskId, observedSource: source, receipt, reasonCode: null };
+    }
+    if (source === 'active' && receipt) {
+        return {
+            state: 'finalized-stale', taskId: params.taskId, observedSource: source, receipt,
+            reasonCode: 'SANDBOX_TASK_VIEW_SOURCE_STALE'
+        };
+    }
+    if (receiptProvided) {
+        return {
+            state: 'unknown', taskId: params.taskId, observedSource: source, receipt: null,
+            reasonCode: 'SANDBOX_TASK_VIEW_RECEIPT_INVALID'
+        };
+    }
+    if (source === 'active') {
+        return { state: 'current', taskId: params.taskId, observedSource: source, receipt: null, reasonCode: null };
+    }
+    return {
+        state: 'unknown', taskId: params.taskId, observedSource: source, receipt: null,
+        reasonCode: 'SANDBOX_TASK_VIEW_EVIDENCE_UNAVAILABLE'
+    };
+}
+export function projectSandboxTaskView(input) {
+    if (input.mode !== 'task-bound' || !input.taskId) {
+        return { state: 'not-applicable', taskId: null, observedSource: null, receipt: null, reasonCode: null };
+    }
+    const receipt = receiptIdentity(input.receipt, input.generation, input.requestId);
+    if (input.source === 'completed' && receipt && input.sourceMatches) {
+        return { state: 'current', taskId: input.taskId, observedSource: 'completed', receipt, reasonCode: null };
+    }
+    if (receipt && input.source === 'active' && !input.sourceMatches) {
+        return { state: 'finalized-stale', taskId: input.taskId, observedSource: 'active', receipt, reasonCode: 'SANDBOX_TASK_VIEW_SOURCE_STALE' };
+    }
+    if (!receipt && input.source === 'active' && input.sourceMatches) {
+        return { state: 'current', taskId: input.taskId, observedSource: 'active', receipt: null, reasonCode: null };
+    }
+    return {
+        state: 'unknown',
+        taskId: input.taskId,
+        observedSource: input.source,
+        receipt,
+        reasonCode: receipt ? 'SANDBOX_TASK_VIEW_SOURCE_UNCONFIRMED' : 'SANDBOX_TASK_VIEW_EVIDENCE_UNAVAILABLE'
+    };
+}
+export function taskViewAfterFinalization(params) {
+    const receipt = receiptIdentity(params.receipt, params.generation, params.requestId);
+    if (!receipt) {
+        return {
+            state: 'unknown', taskId: params.taskId, observedSource: 'unknown', receipt: null,
+            reasonCode: 'SANDBOX_TASK_VIEW_RECEIPT_INVALID'
+        };
+    }
+    return {
+        state: 'finalized-stale', taskId: params.taskId, observedSource: 'active', receipt,
+        reasonCode: 'SANDBOX_TASK_VIEW_FINALIZED'
+    };
+}
+export function mergeSandboxTaskView(canonical, previous) {
+    if (previous.state !== 'finalized-stale' && previous.state !== 'unknown')
+        return canonical;
+    return previous;
+}
+export function accessSandboxTaskView(view, effect) {
+    if (effect === 'diagnostic' || effect === 'cleanup' || effect === 'recovery') {
+        return { allowed: true, state: view.state, reasonCode: view.reasonCode, message: null };
+    }
+    if (view.state === 'current' && view.observedSource === 'active') {
+        return { allowed: true, state: view.state, reasonCode: null, message: null };
+    }
+    const reasonCode = view.state === 'current'
+        ? 'SANDBOX_TASK_VIEW_COMPLETED_READ_ONLY'
+        : view.reasonCode ?? `SANDBOX_TASK_VIEW_${view.state.toUpperCase().replaceAll('-', '_')}`;
+    return {
+        allowed: false,
+        state: view.state,
+        reasonCode,
+        message: view.state === 'unknown'
+            ? 'task view cannot be confirmed; inspect status, recover the original request, or explicitly clean up the sandbox'
+            : view.state === 'finalized-stale'
+                ? 'task view is finalized/stale; exit or clean up the sandbox, or use a validated re-entry'
+                : 'completed task views are read-only'
+    };
+}
+export function taskViewFromStatus(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw invalidView('status must be an object');
+    const status = value;
+    if (status.version !== 3)
+        throw invalidView('status version is unsupported');
+    const taskView = parseSandboxTaskView(status.taskView);
+    if (taskView.receipt && taskView.receipt.generation !== status.generation) {
+        throw invalidView('taskView receipt generation does not match status generation');
+    }
+    return taskView;
+}
+//# sourceMappingURL=task-view.js.map

package/dist/lib/sandbox/engines/authority.js

@@ -0,0 +1,289 @@
+import { createHash } from 'node:crypto';
+import { runProbe } from '../shell.js';
+import { getAdapter } from './index.js';
+function digest(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (!value || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    return `{${Object.entries(value)
+        .sort(([left], [right]) => left.localeCompare(right))
+        .map(([key, entry]) => `${JSON.stringify(key)}:${canonical(entry)}`)
+        .join(',')}}`;
+}
+function text(value) {
+    return typeof value === 'string' ? value : value?.toString('utf8') ?? '';
+}
+function safeEndpoint(value) {
+    if (!value)
+        return 'docker-default';
+    try {
+        const parsed = new URL(value);
+        const hasUnreplayableParts = Boolean(parsed.username || parsed.password || parsed.search || parsed.hash);
+        parsed.username = '';
+        parsed.password = '';
+        parsed.search = '';
+        parsed.hash = '';
+        const normalized = parsed.toString().replace(/\/$/u, '');
+        return hasUnreplayableParts
+            ? `${normalized}#<redacted>`
+            : normalized;
+    }
+    catch {
+        const normalized = value
+            .replace(/\/\/[^/@]+@/u, '//<redacted>@')
+            .replace(/[?&](?:token|password|secret|key)=[^&]*/giu, '');
+        return /[@?#]/u.test(value) ? `${normalized.replace(/[?#].*$/u, '')}#<redacted>` : normalized;
+    }
+}
+function lockDomainFor(engine, endpoint) {
+    return digest(`${process.platform}\0${process.arch}\0${engine}\0${endpoint}`);
+}
+function contextRoute(context) {
+    return {
+        kind: 'context',
+        selector: { context },
+        endpoint: `docker-context://${context}`,
+        command: (args) => ({ cmd: 'docker', args: ['--context', context, ...args] })
+    };
+}
+function endpointRoute(endpoint, rawEndpoint, unreplayable) {
+    return {
+        kind: 'endpoint',
+        selector: {
+            source: 'DOCKER_HOST',
+            endpoint,
+            ...(unreplayable ? { unreplayable } : {})
+        },
+        endpoint,
+        command: (args) => ({ cmd: 'docker', args: ['--host', rawEndpoint, ...args] })
+    };
+}
+function tlsEnvironmentReason(env) {
+    return env.DOCKER_TLS_VERIFY || env.DOCKER_CERT_PATH || env.DOCKER_TLS
+        ? 'tls-environment'
+        : undefined;
+}
+function routeFor(engine, env) {
+    const context = getAdapter(engine).dockerContext;
+    if (context) {
+        return contextRoute(context);
+    }
+    if (env.DOCKER_CONTEXT) {
+        return contextRoute(env.DOCKER_CONTEXT);
+    }
+    if (env.DOCKER_HOST) {
+        return endpointRoute(safeEndpoint(env.DOCKER_HOST), env.DOCKER_HOST, tlsEnvironmentReason(env));
+    }
+    return contextRoute('default');
+}
+function validRouteName(value) {
+    return /^[A-Za-z0-9][A-Za-z0-9_.@/-]*$/u.test(value);
+}
+function resolveWslDistro(probe, timeoutMs, explicit) {
+    if (explicit) {
+        if (!validRouteName(explicit))
+            throw new Error('SANDBOX_AUTHORITY_ROUTE_CAPTURE_FAILED');
+        return explicit;
+    }
+    const result = probe('wsl.exe', ['--list', '--verbose'], timeoutMs === undefined ? {} : { timeout: timeoutMs });
+    if (result.status !== 0)
+        throw new Error('SANDBOX_AUTHORITY_ROUTE_CAPTURE_FAILED');
+    const output = text(result.stdout).replace(/\0/gu, '').replace(/\r/gu, '');
+    const defaultLine = output.split('\n').find((line) => /^\s*\*\s+/u.test(line));
+    const distro = defaultLine?.replace(/^\s*\*\s+/u, '').replace(/\s+(?:Running|Stopped)\s+\d+\s*$/iu, '').trim();
+    if (!distro || !validRouteName(distro))
+        throw new Error('SANDBOX_AUTHORITY_ROUTE_CAPTURE_FAILED');
+    return distro;
+}
+function wslRoute(distro, context, env) {
+    const endpoint = env.DOCKER_HOST
+        ? safeEndpoint(env.DOCKER_HOST)
+        : `wsl://${distro}/${context ?? 'default'}`;
+    const unreplayable = tlsEnvironmentReason(env)
+        ?? (endpoint.includes('<redacted>') ? 'ambient-endpoint-secret' : undefined);
+    return {
+        kind: 'wsl2',
+        selector: {
+            distro,
+            ...(context ? { context } : {}),
+            ...(unreplayable ? { unreplayable } : {}),
+            ...(env.DOCKER_HOST ? { endpoint } : {})
+        },
+        endpoint,
+        command: (args) => ({
+            cmd: 'wsl.exe',
+            args: [
+                '--distribution', distro,
+                '--exec', 'docker',
+                ...(context ? ['--context', context] : []),
+                ...(env.DOCKER_HOST ? ['--host', env.DOCKER_HOST] : []),
+                ...args
+            ]
+        })
+    };
+}
+function currentWslRoute(env, probe, timeoutMs) {
+    const distro = resolveWslDistro(probe, timeoutMs, env.WSL_DISTRO_NAME);
+    let context = env.DOCKER_CONTEXT;
+    if (!context && !env.DOCKER_HOST) {
+        const result = probe('wsl.exe', ['--distribution', distro, '--exec', 'docker', 'context', 'show'], timeoutMs === undefined ? {} : { timeout: timeoutMs });
+        context = text(result.stdout).trim();
+        if (result.status !== 0 || !validRouteName(context)) {
+            throw new Error('SANDBOX_AUTHORITY_ROUTE_CAPTURE_FAILED');
+        }
+    }
+    return wslRoute(distro, context, env);
+}
+function routeFromEvidence(evidence) {
+    return {
+        kind: evidence.routeKind,
+        selector: evidence.routeSelector,
+        endpoint: evidence.normalizedEndpoint,
+        command: (args) => commandForSandboxAuthority(evidence, 'docker', args)
+    };
+}
+function currentContextRoute(engine, env, probe, timeoutMs) {
+    const configured = routeFor(engine, env);
+    if (configured.kind !== 'context' || configured.selector.context !== 'default')
+        return configured;
+    if (env.DOCKER_CONTEXT || env.DOCKER_HOST || getAdapter(engine).dockerContext)
+        return configured;
+    const result = probe('docker', ['context', 'show'], timeoutMs === undefined ? {} : { timeout: timeoutMs });
+    const context = text(result.stdout).trim();
+    if (result.status !== 0 || !/^[A-Za-z0-9][A-Za-z0-9_.@/-]*$/u.test(context)) {
+        throw new Error('SANDBOX_AUTHORITY_ROUTE_CAPTURE_FAILED');
+    }
+    return contextRoute(context);
+}
+/** Build a command using only the route persisted with the sandbox authority. */
+export function commandForSandboxAuthority(evidence, cmd, args = []) {
+    if (cmd !== 'docker') {
+        throw new Error('SANDBOX_AUTHORITY_ROUTE_UNSUPPORTED');
+    }
+    if (evidence.routeKind === 'context') {
+        const context = evidence.routeSelector.context;
+        if (!context)
+            throw new Error('SANDBOX_AUTHORITY_ROUTE_INVALID');
+        return { cmd, args: ['--context', context, ...args] };
+    }
+    if (evidence.routeKind === 'endpoint') {
+        const endpoint = evidence.routeSelector.endpoint;
+        if (!endpoint || endpoint.includes('<redacted>') || evidence.routeSelector.unreplayable) {
+            throw new Error('SANDBOX_AUTHORITY_ROUTE_UNREPLAYABLE');
+        }
+        return { cmd, args: ['--host', endpoint, ...args] };
+    }
+    if (evidence.routeKind === 'wsl2') {
+        const distro = evidence.routeSelector.distro;
+        const context = evidence.routeSelector.context;
+        const endpoint = evidence.routeSelector.endpoint;
+        if (!distro || evidence.routeSelector.unreplayable || endpoint?.includes('<redacted>')) {
+            throw new Error('SANDBOX_AUTHORITY_ROUTE_UNREPLAYABLE');
+        }
+        return {
+            cmd: 'wsl.exe',
+            args: [
+                '--distribution', distro,
+                '--exec', cmd,
+                ...(context ? ['--context', context] : []),
+                ...(endpoint && !endpoint.startsWith('wsl://') ? ['--host', endpoint] : []),
+                ...args
+            ]
+        };
+    }
+    return { cmd, args: ['--context', 'default', ...args] };
+}
+export function authorityVersionArgs() {
+    return ['version', '--format', '{{json .Server}}'];
+}
+export function captureSandboxAuthority(engine, options = {}) {
+    const env = options.env ?? process.env;
+    const probe = options.probe ?? runProbe;
+    const route = options.route
+        ? routeFromEvidence(options.route)
+        : engine === 'wsl2'
+            ? currentWslRoute(env, probe, options.timeoutMs)
+            : currentContextRoute(engine, env, probe, options.timeoutMs);
+    function probeJson(args) {
+        const command = options.route
+            ? commandForSandboxAuthority(options.route, 'docker', args)
+            : route.command(args);
+        try {
+            const response = probe(command.cmd, command.args, options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs });
+            if (response.status !== 0)
+                throw new Error('SANDBOX_AUTHORITY_CAPTURE_FAILED');
+            return JSON.parse(text(response.stdout).trim());
+        }
+        catch {
+            throw new Error('SANDBOX_AUTHORITY_CAPTURE_FAILED');
+        }
+    }
+    const server = probeJson(authorityVersionArgs());
+    if (!server || typeof server !== 'object' || Array.isArray(server)) {
+        throw new Error('SANDBOX_AUTHORITY_CAPTURE_FAILED');
+    }
+    const record = server;
+    const api = typeof record.ApiVersion === 'string' ? /^(\d+)\.(\d+)$/u.exec(record.ApiVersion) : null;
+    if (!api)
+        throw new Error('SANDBOX_AUTHORITY_CAPTURE_FAILED');
+    // Docker version exposes API metadata; the daemon ID belongs to Docker info.
+    const serverId = probeJson(['info', '--format', '{{json .ID}}']);
+    if (typeof serverId !== 'string' || !serverId.trim())
+        throw new Error('SANDBOX_AUTHORITY_CAPTURE_FAILED');
+    const normalizedEndpoint = route.endpoint;
+    const evidenceWithoutFingerprint = {
+        version: 1,
+        provider: engine,
+        lockDomain: options.lockDomain ?? options.route?.lockDomain ?? lockDomainFor(engine, normalizedEndpoint),
+        routeKind: route.kind,
+        routeSelector: route.selector,
+        normalizedEndpoint,
+        endpointFingerprint: digest(normalizedEndpoint),
+        daemonIdentity: { kind: 'docker-server-id', fingerprint: digest(serverId) },
+        apiVersion: { major: Number(api[1]), minor: Number(api[2]) }
+    };
+    return {
+        ...evidenceWithoutFingerprint,
+        authorityFingerprint: digest(canonical(evidenceWithoutFingerprint))
+    };
+}
+export function verifySandboxAuthority(expected, actual) {
+    if (!expected)
+        return { state: 'unknown', reason: 'SANDBOX_AUTHORITY_EVIDENCE_MISSING' };
+    if (!actual)
+        return { state: 'unknown', reason: 'SANDBOX_AUTHORITY_UNAVAILABLE' };
+    if (expected.authorityFingerprint !== actual.authorityFingerprint
+        || expected.lockDomain !== actual.lockDomain
+        || expected.routeKind !== actual.routeKind
+        || expected.endpointFingerprint !== actual.endpointFingerprint
+        || expected.daemonIdentity.fingerprint !== actual.daemonIdentity.fingerprint) {
+        return { state: 'conflict', reason: 'SANDBOX_AUTHORITY_DRIFT' };
+    }
+    return { state: 'verified' };
+}
+export function isSandboxAuthorityEvidence(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const evidence = value;
+    const selector = evidence.routeSelector;
+    const daemon = evidence.daemonIdentity;
+    const api = evidence.apiVersion;
+    return evidence.version === 1
+        && typeof evidence.provider === 'string'
+        && /^[a-f0-9]{64}$/u.test(evidence.lockDomain)
+        && ['default', 'context', 'endpoint', 'wsl2'].includes(evidence.routeKind)
+        && !!selector && typeof selector === 'object' && !Array.isArray(selector)
+        && Object.values(selector).every((entry) => typeof entry === 'string')
+        && typeof evidence.normalizedEndpoint === 'string'
+        && /^[a-f0-9]{64}$/u.test(evidence.endpointFingerprint)
+        && !!daemon && daemon.kind === 'docker-server-id'
+        && /^[a-f0-9]{64}$/u.test(daemon.fingerprint)
+        && !!api && Number.isSafeInteger(api.major) && api.major >= 0
+        && Number.isSafeInteger(api.minor) && api.minor >= 0
+        && /^[a-f0-9]{64}$/u.test(evidence.authorityFingerprint);
+}
+//# sourceMappingURL=authority.js.map

package/dist/lib/sandbox/engines/docker-exact-discovery.js

@@ -0,0 +1,97 @@
+import { commandForEngine, runProbe } from '../shell.js';
+import { commandForSandboxAuthority } from './authority.js';
+const FULL_CONTAINER_ID = /^[a-f0-9]{64}$/u;
+function outputText(value) {
+    return typeof value === 'string' ? value : value?.toString('utf8') ?? '';
+}
+function unknown(reason) {
+    return { state: 'unknown', reason };
+}
+export function buildExactContainerListArgs(id) {
+    if (!FULL_CONTAINER_ID.test(id))
+        throw new Error('SANDBOX_CONTAINER_ID_NOT_FULL');
+    return ['container', 'ls', '--all', '--no-trunc', '--filter', `id=${id}`, '--format', '{{.ID}}'];
+}
+function buildExactContainerInspectArgs(id) {
+    return ['container', 'inspect', '--format', '{{json .}}', id];
+}
+function runDockerProbe(engine, args, options) {
+    const command = options.authority
+        ? commandForSandboxAuthority(options.authority, 'docker', args)
+        : commandForEngine(engine, 'docker', args);
+    return (options.probe ?? runProbe)(command.cmd, command.args, options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs });
+}
+function parseExactList(stdout, expectedId) {
+    const rows = stdout.split(/\r?\n/u).map((row) => row.trim()).filter(Boolean);
+    if (rows.length === 0)
+        return 'empty';
+    if (rows.length !== 1)
+        return 'exact container query returned multiple rows';
+    if (!FULL_CONTAINER_ID.test(rows[0]))
+        return 'exact container query returned a malformed ID';
+    if (rows[0] !== expectedId)
+        return 'conflict';
+    return 'present';
+}
+function parseExactInspect(stdout, expectedId) {
+    let value;
+    try {
+        value = JSON.parse(stdout);
+    }
+    catch {
+        return unknown('exact container inspection returned malformed JSON');
+    }
+    if (!value || typeof value !== 'object' || Array.isArray(value)) {
+        return unknown('exact container inspection returned an incomplete object');
+    }
+    const inspected = value;
+    if (inspected.Id !== expectedId || typeof inspected.State?.Running !== 'boolean'
+        || !inspected.Config?.Labels || typeof inspected.Config.Labels !== 'object'
+        || Array.isArray(inspected.Config.Labels)) {
+        return unknown('exact container inspection identity is incomplete');
+    }
+    const rawLabels = inspected.Config.Labels;
+    if (Object.values(rawLabels).some((value) => typeof value !== 'string')) {
+        return unknown('exact container inspection labels are malformed');
+    }
+    return {
+        state: 'found',
+        id: expectedId,
+        running: inspected.State.Running,
+        labels: { ...rawLabels },
+        evidence: 'exact-present'
+    };
+}
+export function discoverExactContainer(engine, id, options = {}) {
+    if (!FULL_CONTAINER_ID.test(id))
+        return unknown('container identity is not a full 64-character ID');
+    let listed;
+    try {
+        listed = runDockerProbe(engine, buildExactContainerListArgs(id), options);
+    }
+    catch {
+        return unknown('exact container query failed before producing a result');
+    }
+    if (listed.status !== 0) {
+        return unknown(`exact container query exited with ${listed.status ?? 'unknown status'}`);
+    }
+    const listState = parseExactList(outputText(listed.stdout), id);
+    if (listState === 'empty')
+        return { state: 'absent', id, evidence: 'exact-empty' };
+    if (listState === 'conflict')
+        return { state: 'conflict', reason: 'exact container query returned a different ID' };
+    if (listState !== 'present')
+        return unknown(listState);
+    let inspected;
+    try {
+        inspected = runDockerProbe(engine, buildExactContainerInspectArgs(id), options);
+    }
+    catch {
+        return unknown('exact container inspection failed before producing a result');
+    }
+    if (inspected.status !== 0) {
+        return unknown(`exact container inspection exited with ${inspected.status ?? 'unknown status'}`);
+    }
+    return parseExactInspect(outputText(inspected.stdout).trim(), id);
+}
+//# sourceMappingURL=docker-exact-discovery.js.map

package/dist/lib/sandbox/index.js

@@ -1,3 +1,4 @@
+import { PUBLIC_CLI_ROUTE_SELECTORS } from '../internal/cli-route-inventory.js';
 const USAGE = `Usage: ai sandbox <command> [options]
 
 Commands:
@@ -26,6 +27,7 @@ Commands:
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
 
 Run 'ai sandbox <command> --help' for details.`;
+const SANDBOX_OPERATIONS = PUBLIC_CLI_ROUTE_SELECTORS.sandbox;
 export async function runSandbox(args) {
     const [subcommand, ...rest] = args;
     if (!subcommand) {
@@ -37,6 +39,9 @@ export async function runSandbox(args) {
         process.stdout.write(`${USAGE}\n`);
         return;
     }
+    if (!SANDBOX_OPERATIONS.includes(subcommand)) {
+        throw new Error(`Unknown sandbox command: ${subcommand}`);
+    }
     switch (subcommand) {
         case 'create': {
             const { create } = await import('./commands/create.js');

package/dist/lib/sandbox/recovery.js

@@ -1,3 +1,4 @@
+import { prepareCompletedReentry, publishCompletedReentry, waitForCompletedReentry } from './control/completed-reentry.js';
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
@@ -441,7 +442,7 @@ function recoveryTaskSources(repoRoot, taskId) {
     }
     return { mountPaths, accessiblePaths: [completedSource] };
 }
-function startCompletedSandboxContainer(params) {
+export function startCompletedSandboxContainer(params) {
     const taskSources = recoveryTaskSources(params.config.repoRoot, params.taskId);
     const completedSource = taskSources.accessiblePaths[0];
     const activeRoot = path.join(params.config.repoRoot, '.agents', 'workspace', 'active');
@@ -879,7 +880,17 @@ export async function ensureSandboxReady(params) {
             throw new Error('Explicit container recreation requested.');
         }
         if (!params.row.running) {
+            let completedReentry = null;
             if (params.reentry === 'completed' && params.workspace?.mode === 'task-bound') {
+                const control = sandboxControlPaths({
+                    base: params.config.controlBase, project: params.config.project,
+                    container: params.row.name, identity: params.workspace
+                });
+                const manifest = readSandboxControlManifest(control.manifestPath);
+                if (manifest.taskId !== params.workspace.taskId || manifest.branch !== params.branch) {
+                    throw new Error('SANDBOX_COMPLETED_REENTRY_EVIDENCE_INVALID');
+                }
+                completedReentry = { manifest, evidence: await prepareCompletedReentry(manifest) };
                 startCompletedSandboxContainer({
                     config: params.config,
                     engine: params.engine,
@@ -943,6 +954,15 @@ export async function ensureSandboxReady(params) {
             if (final.findings.length > 0) {
                 throw new Error(describeFindings(final.findings));
             }
+            if (completedReentry) {
+                const { manifest, evidence } = completedReentry;
+                const current = await prepareCompletedReentry(manifest);
+                if (JSON.stringify(current) !== JSON.stringify(evidence)) {
+                    throw new Error('SANDBOX_COMPLETED_REENTRY_EVIDENCE_INVALID');
+                }
+                publishCompletedReentry(manifest, evidence);
+                await waitForCompletedReentry(manifest, evidence);
+            }
             return { container: params.row.name, path: 'recovered', warnings };
         }
         const initial = assess({

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

@@ -195,7 +195,8 @@ export function finalizeSandboxControlManifest(setup, identity) {
     const manifest = {
         ...setup.manifestDraft,
         engine: identity.engine,
-        containerIdentity: { id: identity.id, labels: { ...identity.labels } }
+        containerIdentity: { id: identity.id, labels: { ...identity.labels } },
+        authorityEvidence: identity.authorityEvidence
     };
     const temporary = `${setup.manifestPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
     try {

package/dist/lib/sandbox/worktree-safety.js

@@ -387,7 +387,10 @@ function verifyWorktreePermit(permit, options = {}) {
         : inspectWorktree(permit.snapshot.worktree, options);
     if (current.status === 'failed')
         throw new Error(`Unable to verify worktree permit: ${current.message}`);
-    if (current.snapshot.identity !== permit.snapshot.identity || (permit.mode === 'clean' && current.status !== 'clean')) {
+    const sameTarget = current.snapshot.worktree === permit.snapshot.worktree
+        && current.snapshot.branch === permit.snapshot.branch;
+    if (!sameTarget || (permit.mode === 'clean'
+        && (current.snapshot.identity !== permit.snapshot.identity || current.status !== 'clean'))) {
         throw new Error(`Worktree changed after authorization: ${permit.snapshot.worktree}`);
     }
     return current.snapshot;