@fitlab-ai/agent-infra 0.9.5 → 0.9.7

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

@@ -0,0 +1,128 @@
+import fs from 'node:fs';
+import { createHash } from 'node:crypto';
+import { extractSection, findSectionHeading, parseTable } from './sections.js';
+const RECEIPT_SECTION_ALIASES = ['产物生命周期收据', 'Artifact Lifecycle Receipts'];
+const RECEIPT_COLUMNS = ['event', 'output', 'input', 'input_sha256', 'completed_at'];
+const RECEIPT_EVENTS = new Set([
+    'review-analysis.completed',
+    'review-plan.completed',
+    'review-code.completed',
+    'code.completed'
+]);
+const SHA256_RE = /^[a-f0-9]{64}$/;
+const ARTIFACT_NAME_RE = /^(analysis|review-analysis|plan|review-plan|code|review-code|manual-validation|validation-run|pr-review)(?:-r([2-9]|[1-9]\d+))?\.md$/;
+const RECEIPT_SHAPES = {
+    'review-analysis.completed': { output: 'review-analysis', input: 'analysis' },
+    'review-plan.completed': { output: 'review-plan', input: 'plan' },
+    'review-code.completed': { output: 'review-code', input: 'code' },
+    'code.completed': { output: 'code', input: 'plan' }
+};
+class ArtifactReceiptError extends Error {
+    code = 'ARTIFACT_RECEIPT_INVALID';
+    constructor(message) {
+        super(message);
+        this.name = 'ArtifactReceiptError';
+    }
+}
+function sha256Bytes(value) {
+    return createHash('sha256').update(value).digest('hex');
+}
+function sha256File(filePath) {
+    return sha256Bytes(fs.readFileSync(filePath));
+}
+function parseReceiptArtifactName(name) {
+    const match = ARTIFACT_NAME_RE.exec(name);
+    if (!match)
+        return null;
+    const roundText = match[2];
+    if (roundText !== undefined) {
+        const round = Number(roundText);
+        if (!Number.isSafeInteger(round) || String(round) !== roundText)
+            return null;
+    }
+    return { family: match[1] };
+}
+function validateReceiptShape(event, output, input) {
+    const outputIdentity = parseReceiptArtifactName(output);
+    const inputIdentity = parseReceiptArtifactName(input);
+    if (!outputIdentity || !inputIdentity)
+        throw new ArtifactReceiptError(`receipt artifact identity is invalid: ${output} -> ${input}`);
+    const shape = RECEIPT_SHAPES[event];
+    if (outputIdentity.family !== shape.output || inputIdentity.family !== shape.input) {
+        throw new ArtifactReceiptError(`receipt event '${event}' does not match ${output} -> ${input}`);
+    }
+}
+function parseArtifactReceipts(content) {
+    const section = extractSection(content, [...RECEIPT_SECTION_ALIASES]);
+    if (!section)
+        return { present: false, rows: [] };
+    let table;
+    try {
+        table = parseTable(content, {
+            sectionAliases: [...RECEIPT_SECTION_ALIASES],
+            columns: [...RECEIPT_COLUMNS],
+            keyColumn: 'output'
+        });
+    }
+    catch (error) {
+        throw new ArtifactReceiptError(error instanceof Error ? error.message : String(error));
+    }
+    if (!table)
+        throw new ArtifactReceiptError('receipt section has no receipt table');
+    const rows = table.rows.map((row) => {
+        const event = row.values.event ?? '';
+        const output = row.values.output ?? '';
+        const input = row.values.input ?? '';
+        const inputSha256 = row.values.input_sha256 ?? '';
+        const completedAt = row.values.completed_at ?? '';
+        if (!RECEIPT_EVENTS.has(event))
+            throw new ArtifactReceiptError(`unknown receipt event '${event}'`);
+        if (!output || !input)
+            throw new ArtifactReceiptError('receipt output and input are required');
+        validateReceiptShape(event, output, input);
+        if (!SHA256_RE.test(inputSha256))
+            throw new ArtifactReceiptError(`receipt digest for '${output}' is invalid`);
+        if (!completedAt || Number.isNaN(Date.parse(completedAt.replace(' ', 'T')))) {
+            throw new ArtifactReceiptError(`receipt completion time for '${output}' is invalid`);
+        }
+        return {
+            event: event,
+            output,
+            input,
+            inputSha256,
+            completedAt
+        };
+    });
+    return { present: true, rows };
+}
+function receiptForOutput(content, output) {
+    const parsed = parseArtifactReceipts(content);
+    return parsed.rows.find((row) => row.output === output) ?? null;
+}
+function upsertArtifactReceipt(content, receipt) {
+    if (!RECEIPT_EVENTS.has(receipt.event))
+        throw new ArtifactReceiptError(`unknown receipt event '${receipt.event}'`);
+    if (!receipt.output || !receipt.input)
+        throw new ArtifactReceiptError('receipt output and input are required');
+    validateReceiptShape(receipt.event, receipt.output, receipt.input);
+    if (!SHA256_RE.test(receipt.inputSha256))
+        throw new ArtifactReceiptError(`receipt digest for '${receipt.output}' is invalid`);
+    if (!receipt.completedAt || Number.isNaN(Date.parse(receipt.completedAt.replace(' ', 'T')))) {
+        throw new ArtifactReceiptError(`receipt completion time for '${receipt.output}' is invalid`);
+    }
+    const existing = parseArtifactReceipts(content).rows;
+    const previous = existing.find((row) => row.output === receipt.output);
+    if (previous && JSON.stringify(previous) !== JSON.stringify(receipt)) {
+        throw new ArtifactReceiptError(`receipt for '${receipt.output}' already exists with different evidence`);
+    }
+    const rows = previous ? existing : [...existing, receipt];
+    const heading = findSectionHeading(content, [...RECEIPT_SECTION_ALIASES]);
+    const body = [
+        `| ${RECEIPT_COLUMNS.join(' | ')} |`,
+        `| ${RECEIPT_COLUMNS.map(() => '---').join(' | ')} |`,
+        ...rows.map((row) => `| ${row.event} | ${row.output} | ${row.input} | ${row.inputSha256} | ${row.completedAt} |`)
+    ].join('\n');
+    return { aliases: [...RECEIPT_SECTION_ALIASES], heading, body };
+}
+export { ArtifactReceiptError, RECEIPT_SECTION_ALIASES, parseArtifactReceipts, receiptForOutput, sha256Bytes, sha256File, upsertArtifactReceipt };
+//# sourceMappingURL=artifact-receipts.js.map

package/dist/lib/task/codex-orchestration.js

@@ -0,0 +1,236 @@
+import fs from 'node:fs';
+import { preflightCodexLifecycleEvidence, resolveCodexSpawnedChild, resolveCodexTerminal, resolveCodexThread } from '../agent-clients/adapters/codex-lifecycle/app-server.js';
+import { createCodexLifecycleStore } from '../agent-clients/adapters/codex-lifecycle/store.js';
+import { createCodexCapabilityStore } from '../agent-clients/adapters/codex-lifecycle/capability-store.js';
+import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.js';
+import { verifyCodexSandboxControllerContext } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
+import { resolveTaskRef } from './resolve-ref.js';
+import { activateMatchingOrchestrationDelegation, hasActivatableOrchestrationDelegation, hasSealableOrchestrationDelegation, pauseMatchingOrchestrationDelegation, prepareOrchestrationDelegation, reconcileMatchingOrchestrationDelegation, sealMatchingOrchestrationDelegationWithHostEvidence } from './orchestration.js';
+function coreOptions(options) {
+    return { ...options.orchestrationOptions, repoRoot: options.repoRoot ?? options.orchestrationOptions?.repoRoot };
+}
+function bridgeFailure(code, message) {
+    return {
+        status: 'failed', changed: false, taskId: null, run: null, next: null,
+        error: { code, message }
+    };
+}
+function pauseBridge(code, message, options) {
+    const paused = pauseMatchingOrchestrationDelegation('codex', code, message, coreOptions(options));
+    return paused.error?.code === 'ORCHESTRATION_DELEGATION_MISSING'
+        ? bridgeFailure(code, message)
+        : paused;
+}
+function requiredStore(options) {
+    if (!options.store)
+        throw new Error('Codex lifecycle store is required for orchestration bridge events');
+    return options.store;
+}
+function controllerContext(taskId, repoRoot) {
+    const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+    return contextPath
+        ? verifyCodexSandboxControllerContext(contextPath, taskId, { repoRoot })
+        : null;
+}
+async function prepareCodexOrchestrationDelegation(taskRef, input, options = {}) {
+    if (input.client !== 'codex')
+        return prepareOrchestrationDelegation(taskRef, input, coreOptions(options));
+    try {
+        const repoRoot = options.repoRoot ?? process.cwd();
+        const resolved = resolveTaskRef(taskRef, { repoRoot });
+        if (!resolved.ok)
+            return bridgeFailure(resolved.code, resolved.message);
+        const preflight = await (options.preflight ?? preflightCodexLifecycleEvidence)(repoRoot);
+        if (!input.capabilityToken) {
+            return bridgeFailure('ORCHESTRATION_CODEX_CAPABILITY_REQUIRED', 'Codex prepare requires a current-session capability token');
+        }
+        const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(repoRoot);
+        const controller = controllerContext(resolved.taskId, repoRoot);
+        const capabilityStore = options.capabilityStore ?? createCodexCapabilityStore();
+        const consumed = capabilityStore.consume(input.capabilityToken, {
+            taskId: resolved.taskId,
+            hookDefinitionHash: preflight.hookDefinitionHash,
+            buildIdentity,
+            ...(controller ? { controller: {
+                    instanceDigest: controller.controllerInstanceDigest,
+                    controlGeneration: controller.controlGeneration
+                } } : {})
+        });
+        return prepareOrchestrationDelegation(taskRef, {
+            ...input,
+            lifecycleProvenance: {
+                ...consumed.buildIdentity,
+                hookDefinitionHash: preflight.hookDefinitionHash,
+                ...preflight.hookProvenance,
+                capabilitySessionId: consumed.sessionId,
+                capabilityTurnId: consumed.turnId,
+                capabilityToolUseId: consumed.toolUseId,
+                controllerInstanceDigest: controller?.controllerInstanceDigest ?? null,
+                controlGeneration: controller?.controlGeneration ?? null
+            }
+        }, coreOptions(options));
+    }
+    catch (error) {
+        return bridgeFailure(error instanceof Error && error.name.startsWith('CODEX_CAPABILITY_')
+            ? error.name
+            : 'ORCHESTRATION_CLIENT_PREFLIGHT_FAILED', error instanceof Error ? error.message : String(error));
+    }
+}
+async function activateCodexOrchestrationDelegation(childThreadId, options = {}) {
+    try {
+        if (!hasActivatableOrchestrationDelegation('codex', childThreadId, coreOptions(options))) {
+            return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+        }
+        const store = requiredStore(options);
+        const resolved = await (options.resolveThread ?? resolveCodexThread)(childThreadId);
+        store.apply(resolved.resolution.thread);
+        for (const reroute of resolved.reroutes)
+            store.apply(reroute);
+        store.apply(resolved.resolution.settings);
+        const record = store.read(childThreadId);
+        const evidence = record.state.startEvidence;
+        if (record.state.status !== 'start-ready' || !evidence) {
+            return pauseBridge('ORCHESTRATION_CODEX_START_EVIDENCE_INVALID', 'Codex lifecycle start evidence is not ready', options);
+        }
+        const repoRoot = options.repoRoot ?? process.cwd();
+        const preflight = await (options.preflight ?? preflightCodexLifecycleEvidence)(repoRoot, {
+            sessionId: evidence.parentThreadId,
+            turnId: evidence.parentTurnId,
+            toolUseId: evidence.spawnToolUseId
+        });
+        const buildIdentity = options.buildIdentity ?? computeLifecycleBuildIdentity(repoRoot);
+        const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+        const contextTaskId = contextPath
+            ? JSON.parse(fs.readFileSync(contextPath, 'utf8')).taskId
+            : null;
+        if (contextPath && typeof contextTaskId !== 'string') {
+            throw new Error('CODEX_SANDBOX_CONTROLLER_CONTEXT_INVALID');
+        }
+        const controller = contextPath
+            ? verifyCodexSandboxControllerContext(contextPath, contextTaskId, { repoRoot })
+            : null;
+        return activateMatchingOrchestrationDelegation('codex', {
+            nativeAgent: evidence.nativeAgent,
+            childId: evidence.childThreadId,
+            parentId: evidence.parentThreadId,
+            spawnMode: evidence.spawnMode,
+            actualModel: evidence.actualModel.value,
+            actualReasoningEffort: evidence.actualReasoningEffort.value,
+            ...(evidence.modelFallbackReason ? { modelFallbackReason: evidence.modelFallbackReason } : {}),
+            ...(evidence.reasoningEffortFallbackReason
+                ? { reasoningEffortFallbackReason: evidence.reasoningEffortFallbackReason }
+                : {}),
+            hostEvidence: {
+                kind: 'codex-lifecycle-v2',
+                hookDefinitionHash: evidence.hookDefinitionHash,
+                startRevision: record.revision,
+                ...buildIdentity,
+                ...preflight.hookProvenance,
+                capabilitySessionId: evidence.parentThreadId,
+                capabilityTurnId: evidence.parentTurnId,
+                spawnToolUseId: evidence.spawnToolUseId,
+                spawnObservedAt: record.spawnObservedAt ?? undefined,
+                controllerInstanceDigest: controller?.controllerInstanceDigest ?? null,
+                controlGeneration: controller?.controlGeneration ?? null
+            }
+        }, coreOptions(options));
+    }
+    catch (error) {
+        return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', error instanceof Error ? error.message : String(error), options);
+    }
+}
+async function activateCodexSpawnDelegation(spawn, options = {}) {
+    try {
+        const store = requiredStore(options);
+        const childThreadId = resolveCodexSpawnedChild(spawn.transcriptPath, spawn);
+        const resolved = await (options.resolveThread ?? resolveCodexThread)(childThreadId);
+        store.applyToSpawn(spawn, {
+            type: 'hook-child',
+            sessionId: spawn.sessionId,
+            turnId: spawn.turnId,
+            childThreadId,
+            parentThreadId: resolved.resolution.thread.parentThreadId,
+            nativeAgent: spawn.nativeAgent,
+            source: 'parent-rollout'
+        });
+        return activateCodexOrchestrationDelegation(childThreadId, {
+            ...options,
+            store,
+            resolveThread: async () => resolved
+        });
+    }
+    catch (error) {
+        return pauseBridge('ORCHESTRATION_CODEX_START_FAILED', error instanceof Error ? error.message : String(error), options);
+    }
+}
+async function sealCodexOrchestrationDelegation(childThreadId, options = {}) {
+    try {
+        if (!hasSealableOrchestrationDelegation('codex', childThreadId, coreOptions(options))) {
+            return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+        }
+        const store = requiredStore(options);
+        const existing = store.read(childThreadId);
+        if (!existing.consumer) {
+            store.apply(await (options.resolveTerminal ?? resolveCodexTerminal)(childThreadId));
+        }
+        const record = store.read(childThreadId);
+        const evidence = record.state.stopEvidence;
+        if (record.state.status !== 'stop-ready' || !evidence || !record.state.startEvidence) {
+            return pauseBridge('ORCHESTRATION_CODEX_STOP_EVIDENCE_INVALID', 'Codex lifecycle stop evidence is not ready', options);
+        }
+        return sealMatchingOrchestrationDelegationWithHostEvidence('codex', { nativeAgent: record.state.startEvidence.nativeAgent, childId: childThreadId }, (receipt) => {
+            const consumed = store.consume(childThreadId, receipt.id, receipt.hostEvidence?.hookDefinitionHash);
+            return {
+                stopRevision: consumed.revision,
+                consumer: consumed.consumer,
+                consumedAt: consumed.consumedAt
+            };
+        }, coreOptions(options));
+    }
+    catch (error) {
+        return pauseBridge('ORCHESTRATION_CODEX_STOP_FAILED', error instanceof Error ? error.message : String(error), options);
+    }
+}
+async function sealCodexParentDelegation(parentThreadId, options = {}) {
+    try {
+        const store = requiredStore(options);
+        const candidates = store.findByParent(parentThreadId);
+        if (!candidates.length)
+            return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+        for (const consumed of candidates.filter((record) => record.consumer)) {
+            const replayed = await sealCodexOrchestrationDelegation(consumed.state.startEvidence.childThreadId, options);
+            if (replayed.error?.code !== 'ORCHESTRATION_DELEGATION_MISSING')
+                return replayed;
+        }
+        const active = candidates.find((record) => !record.consumer);
+        if (!active)
+            return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'No matching Codex delegation is active');
+        const start = active.state.startEvidence;
+        const child = active.state.child;
+        if (!active.state.terminal) {
+            store.apply(await (options.resolveTerminal ?? resolveCodexTerminal)(start.childThreadId));
+        }
+        if (!store.read(start.childThreadId).state.stop) {
+            store.apply({
+                type: 'hook-stop',
+                sessionId: parentThreadId,
+                turnId: child.turnId,
+                childThreadId: start.childThreadId,
+                nativeAgent: start.nativeAgent,
+                source: 'parent-rollout'
+            });
+        }
+        return sealCodexOrchestrationDelegation(start.childThreadId, options);
+    }
+    catch (error) {
+        if (error instanceof Error && error.message === 'CODEX_TURN_NOT_TERMINAL') {
+            return bridgeFailure('ORCHESTRATION_DELEGATION_MISSING', 'The matching Codex child has not completed');
+        }
+        return pauseBridge('ORCHESTRATION_CODEX_STOP_FAILED', error instanceof Error ? error.message : String(error), options);
+    }
+}
+function reconcileCodexOrchestrationDelegation(childThreadId, options = {}) {
+    return reconcileMatchingOrchestrationDelegation('codex', childThreadId, coreOptions(options));
+}
+export { activateCodexOrchestrationDelegation, activateCodexSpawnDelegation, prepareCodexOrchestrationDelegation, reconcileCodexOrchestrationDelegation, sealCodexParentDelegation, sealCodexOrchestrationDelegation };
+//# sourceMappingURL=codex-orchestration.js.map

package/dist/lib/task/commands/status.js

@@ -59,6 +59,7 @@ const STAGE_ORDER = [
     'review-plan',
     'code',
     'review-code',
+    'validation-run',
     'task',
     'other'
 ];
@@ -72,6 +73,8 @@ function stageOf(name) {
         return 'review-plan';
     if (stem.startsWith('review-code'))
         return 'review-code';
+    if (stem.startsWith('validation-run'))
+        return 'validation-run';
     if (stem.startsWith('analysis'))
         return 'analysis';
     if (stem.startsWith('plan'))

package/dist/lib/task/commands/validate.js

@@ -0,0 +1,289 @@
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { loadConfig } from '../../sandbox/config.js';
+import { detectEngine } from '../../sandbox/engine.js';
+import { runEngine } from '../../sandbox/shell.js';
+import { sandboxBranchLabel, sandboxLabel } from '../../sandbox/constants.js';
+import { fetchSandboxRows, selectSandboxContainer } from '../../sandbox/commands/list-running.js';
+import { containerNameCandidates } from '../../sandbox/constants.js';
+import { resolveSandboxTarget } from '../../sandbox/workspace-identity.js';
+import { sandboxControlPaths } from '../../sandbox/workspace-view.js';
+import { appendSandboxControlAudit, readActiveLease, readSandboxControlStatus } from '../../sandbox/control/state.js';
+import { SANDBOX_CONTROL_FUTURE_SKEW_MS, SANDBOX_CONTROL_STATUS_STALE_MS } from '../../sandbox/control/protocol.js';
+import { getProcessStartTime } from '../../server/process-state.js';
+import { assertGitWorktreeBinding } from '../../git/worktree-identity.js';
+const USAGE = `Usage: ai task validate <branch | TASK-id | N> [--scope snapshot|inplace] [--timeout <ms>] [--format text|json] -- <command> [args...]`;
+const MAX_TIMEOUT_MS = 60 * 60 * 1000;
+const RECOVERY_GRACE_MS = 30_000;
+export function parseValidateArgs(args) {
+    if (args.includes('--help') || args.includes('-h')) {
+        return { target: '', scope: 'snapshot', timeoutMs: 300_000, format: 'text', command: [], help: true };
+    }
+    const separator = args.indexOf('--');
+    if (separator < 0)
+        throw new Error(`${USAGE}\nA literal -- must separate validation options from the command.`);
+    const optionArgs = args.slice(0, separator);
+    const command = args.slice(separator + 1);
+    let scope = 'snapshot';
+    let timeoutMs = 300_000;
+    let format = 'text';
+    const positionals = [];
+    for (let index = 0; index < optionArgs.length; index += 1) {
+        const arg = optionArgs[index];
+        if (arg === '--scope') {
+            const value = optionArgs[++index];
+            if (value !== 'snapshot' && value !== 'inplace')
+                throw new Error('validate --scope must be snapshot or inplace');
+            scope = value;
+        }
+        else if (arg === '--timeout') {
+            const value = Number(optionArgs[++index]);
+            if (!Number.isSafeInteger(value) || value <= 0 || value > MAX_TIMEOUT_MS)
+                throw new Error(`validate --timeout must be 1..${MAX_TIMEOUT_MS}`);
+            timeoutMs = value;
+        }
+        else if (arg === '--format') {
+            const value = optionArgs[++index];
+            if (value !== 'text' && value !== 'json')
+                throw new Error('validate --format must be text or json');
+            format = value;
+        }
+        else if (arg.startsWith('-')) {
+            throw new Error(`Unknown option: ${arg}`);
+        }
+        else {
+            positionals.push(arg);
+        }
+    }
+    if (positionals.length !== 1 || command.length === 0)
+        throw new Error(USAGE);
+    return { target: positionals[0], scope, timeoutMs, format, command, help: false };
+}
+function runValidationCommand(command, cwd, scope, timeoutMs, json) {
+    const [file, ...args] = command;
+    const result = spawnSync(file, args, {
+        cwd,
+        env: { ...process.env, AGENT_INFRA_VALIDATION_SCOPE: scope },
+        encoding: 'utf8',
+        timeout: timeoutMs,
+        stdio: ['inherit', 'pipe', 'pipe'],
+        shell: process.platform === 'win32' && /\.(?:bat|cmd)$/i.test(file)
+    });
+    if (json) {
+        if (result.stdout)
+            process.stderr.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+    }
+    else {
+        if (result.stdout)
+            process.stdout.write(result.stdout);
+        if (result.stderr)
+            process.stderr.write(result.stderr);
+    }
+    return { exitCode: result.status ?? 1, signal: result.signal ?? null };
+}
+function git(root, args) {
+    return execFileSync('git', args, { cwd: root, encoding: 'utf8', stdio: ['ignore', 'pipe', 'pipe'] }).trim();
+}
+function waitForState(statusDir, predicate, timeoutMs = 5_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const status = readSandboxControlStatus(statusDir);
+            if (predicate(status))
+                return;
+        }
+        catch {
+            // Atomic status publication may be between renames.
+        }
+        Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, 25);
+    }
+    throw new Error('SANDBOX_VALIDATION_BROKER_STATE_TIMEOUT');
+}
+function snapshotValidation(repoRoot, commit, options) {
+    const tempRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-validation-'));
+    const worktree = path.join(tempRoot, 'worktree');
+    let cleanup = 'not-created';
+    try {
+        git(repoRoot, ['worktree', 'add', '--detach', worktree, commit]);
+        cleanup = 'pending';
+        return { ...runValidationCommand(options.command, worktree, 'snapshot', options.timeoutMs, options.format === 'json'), cleanup: () => cleanup };
+    }
+    finally {
+        let cleanupError = null;
+        if (fs.existsSync(worktree)) {
+            try {
+                git(repoRoot, ['worktree', 'remove', '--force', worktree]);
+                cleanup = 'completed';
+            }
+            catch (error) {
+                cleanupError = error;
+            }
+        }
+        try {
+            git(repoRoot, ['worktree', 'prune']);
+        }
+        catch (error) {
+            cleanupError ??= error;
+        }
+        try {
+            fs.rmSync(tempRoot, { recursive: true, force: true });
+        }
+        catch (error) {
+            cleanupError ??= error;
+        }
+        if (cleanupError)
+            throw cleanupError;
+    }
+}
+function inplaceValidation(config, target, options) {
+    const engine = detectEngine(config);
+    const { running, nonRunning } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+    const row = selectSandboxContainer([...running, ...nonRunning], containerNameCandidates(config, target.branch));
+    if (!row)
+        throw new Error('SANDBOX_VALIDATION_CONTAINER_NOT_FOUND');
+    const control = sandboxControlPaths({
+        base: config.controlBase, project: config.project,
+        container: row.name, identity: target.workspace
+    });
+    const manifest = JSON.parse(fs.readFileSync(control.manifestPath, 'utf8'));
+    const initial = readSandboxControlStatus(control.statusDir);
+    const now = Date.now();
+    if (initial.generation !== manifest.generation
+        || now - initial.updatedAt > SANDBOX_CONTROL_STATUS_STALE_MS
+        || initial.updatedAt > now + SANDBOX_CONTROL_FUTURE_SKEW_MS) {
+        throw new Error('SANDBOX_VALIDATION_BROKER_STATUS_STALE');
+    }
+    if (initial.state !== 'healthy' || initial.activeRequestId !== null) {
+        throw new Error('SANDBOX_VALIDATION_BROKER_NOT_IDLE');
+    }
+    const startTime = getProcessStartTime(process.pid);
+    if (!startTime)
+        throw new Error('SANDBOX_VALIDATION_OWNER_IDENTITY_UNAVAILABLE');
+    const leasePath = path.join(control.root, 'lease.json');
+    const nonce = randomUUID();
+    const issuedAt = Date.now();
+    const lease = {
+        version: 2, generation: manifest.generation, nonce,
+        owner: { pid: process.pid, startTime }, issuedAt,
+        expiresAt: issuedAt + Math.min(options.timeoutMs + RECOVERY_GRACE_MS, MAX_TIMEOUT_MS + RECOVERY_GRACE_MS),
+        taskId: target.workspace.mode === 'task-bound' ? target.workspace.taskId : null,
+        branch: target.branch, reason: 'manual-validation'
+    };
+    const originalBranch = git(manifest.worktreeRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+    const originalHead = git(manifest.worktreeRoot, ['rev-parse', 'HEAD']);
+    fs.writeFileSync(leasePath, `${JSON.stringify(lease)}\n`, { flag: 'wx', mode: 0o600 });
+    let stopped = false;
+    let restored = false;
+    try {
+        appendSandboxControlAudit(manifest, 'lease-acquire', { ownerPid: process.pid });
+        waitForState(control.statusDir, (status) => status.state === 'parked' && status.reasonCode === 'SANDBOX_CONTROL_HANDOFF_ACTIVE');
+        if (row.running) {
+            runEngine(engine, 'docker', ['stop', row.name]);
+            stopped = true;
+        }
+        const refreshedRows = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+        const refreshed = selectSandboxContainer([...refreshedRows.running, ...refreshedRows.nonRunning], containerNameCandidates(config, target.branch));
+        if (!refreshed || refreshed.running)
+            throw new Error('SANDBOX_VALIDATION_CONTAINER_STILL_RUNNING');
+        const activeLease = readActiveLease(manifest);
+        if (!activeLease || activeLease.nonce !== nonce)
+            throw new Error('SANDBOX_VALIDATION_LEASE_OWNERSHIP_LOST');
+        assertGitWorktreeBinding(config.repoRoot, manifest.worktreeRoot, target.branch);
+        const result = runValidationCommand(options.command, manifest.worktreeRoot, 'inplace', options.timeoutMs, options.format === 'json');
+        return { ...result, cleanup: () => restored ? 'completed' : 'pending' };
+    }
+    finally {
+        const recoveryErrors = [];
+        try {
+            const currentBranch = git(manifest.worktreeRoot, ['symbolic-ref', '--quiet', '--short', 'HEAD']);
+            if (currentBranch !== originalBranch)
+                git(manifest.worktreeRoot, ['switch', originalBranch]);
+        }
+        catch {
+            try {
+                git(manifest.worktreeRoot, ['checkout', '--detach', originalHead]);
+                git(manifest.worktreeRoot, ['switch', originalBranch]);
+            }
+            catch (fallbackError) {
+                recoveryErrors.push(`git binding restore failed: ${fallbackError instanceof Error ? fallbackError.message : String(fallbackError)}`);
+            }
+        }
+        if (stopped) {
+            try {
+                runEngine(engine, 'docker', ['start', row.name]);
+            }
+            catch (error) {
+                recoveryErrors.push(`container start failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+        }
+        try {
+            const currentLease = JSON.parse(fs.readFileSync(leasePath, 'utf8'));
+            if (currentLease.nonce !== nonce)
+                throw new Error('SANDBOX_VALIDATION_LEASE_OWNERSHIP_LOST');
+        }
+        catch (error) {
+            recoveryErrors.push(error instanceof Error ? error.message : String(error));
+        }
+        if (recoveryErrors.length === 0) {
+            try {
+                fs.unlinkSync(leasePath);
+                appendSandboxControlAudit(manifest, 'lease-release', { ownerPid: process.pid });
+                waitForState(control.statusDir, (status) => status.state === 'healthy');
+                restored = true;
+            }
+            catch (error) {
+                try {
+                    if (!fs.existsSync(leasePath)) {
+                        fs.writeFileSync(leasePath, `${JSON.stringify(lease)}\n`, { flag: 'wx', mode: 0o600 });
+                    }
+                    appendSandboxControlAudit(manifest, 'lease-release-failed', { ownerPid: process.pid });
+                }
+                catch (leaseError) {
+                    recoveryErrors.push(`lease preservation failed: ${leaseError instanceof Error ? leaseError.message : String(leaseError)}`);
+                }
+                recoveryErrors.push(error instanceof Error ? error.message : String(error));
+            }
+        }
+        if (recoveryErrors.length > 0) {
+            throw new Error(`SANDBOX_VALIDATION_RECOVERY_INCOMPLETE: ${recoveryErrors.join('; ')}; run 'ai sandbox start ${target.branch}'`);
+        }
+    }
+}
+export async function validate(args) {
+    const options = parseValidateArgs(args);
+    if (options.help) {
+        process.stdout.write(`${USAGE}\n`);
+        return 0;
+    }
+    const config = loadConfig();
+    const target = resolveSandboxTarget(options.target, config.repoRoot);
+    const commit = git(config.repoRoot, ['rev-parse', target.branch]);
+    const startedAt = new Date().toISOString();
+    const result = options.scope === 'snapshot'
+        ? snapshotValidation(config.repoRoot, commit, options)
+        : inplaceValidation(config, target, options);
+    const evidence = {
+        version: 1,
+        taskId: target.workspace.mode === 'task-bound' ? target.workspace.taskId : null,
+        branch: target.branch,
+        scope: options.scope,
+        commit,
+        command: path.basename(options.command[0]),
+        startedAt,
+        completedAt: new Date().toISOString(),
+        exitCode: result.exitCode,
+        signal: result.signal,
+        cleanup: result.cleanup()
+    };
+    if (options.format === 'json')
+        process.stdout.write(`${JSON.stringify(evidence)}\n`);
+    else
+        process.stdout.write(`Validation ${result.exitCode === 0 ? 'passed' : 'failed'} (${options.scope}, ${evidence.command}, cleanup=${evidence.cleanup}).\n`);
+    return result.exitCode;
+}
+//# sourceMappingURL=validate.js.map