@fitlab-ai/agent-infra 0.11.4 → 0.11.6

package/dist/lib/platform/provider-validation.js

@@ -78,6 +78,14 @@ function arrayValue(value, label) {
         throw new Error(`${label} must be an array`);
     return value;
 }
+function positiveNumberValue(value, label) {
+    if (!Number.isSafeInteger(value) || Number(value) <= 0)
+        throw new Error(`${label} must be a positive integer`);
+    return Number(value);
+}
+function stringArray(value, label) {
+    return arrayValue(value, label).map((entry, index) => stringValue(entry, `${label}[${index}]`));
+}
 function stableUnique(values, key, label) {
     const seen = new Set();
     for (const value of values) {
@@ -88,6 +96,16 @@ function stableUnique(values, key, label) {
     }
     return [...values].sort((left, right) => key(left).localeCompare(key(right)));
 }
+function uniqueInOrder(values, key, label) {
+    const seen = new Set();
+    for (const value of values) {
+        const identityKey = key(value);
+        if (seen.has(identityKey))
+            throw new Error(`${label} contains duplicate identities`);
+        seen.add(identityKey);
+    }
+    return values;
+}
 function declaredIdentityKind(declaration, resourceKind) {
     const kind = declaration?.[resourceKind];
     return kind === 'id' || kind === 'number' || kind === 'key' ? kind : undefined;
@@ -358,21 +376,73 @@ function validateMetadata(value) {
 }
 function validateReleaseNotes(value, declaration) {
     const item = record(value, 'release notes');
-    exactKeys(item, ['history', 'mergedPullRequests', 'closingIssues', 'actors'], 'release notes');
+    exactKeys(item, ['history', 'commits', 'mergedPullRequests'], 'release notes');
+    const releaseAuthor = (raw, label) => {
+        if (raw === null)
+            return null;
+        const entry = record(raw, label);
+        exactKeys(entry, ['name', 'login', 'bot', 'resolution'], label);
+        if (typeof entry.bot !== 'boolean')
+            throw new Error(`${label}.bot must be boolean`);
+        if (!['platform-user', 'platform-noreply', 'unresolved'].includes(String(entry.resolution))) {
+            throw new Error(`${label}.resolution is invalid`);
+        }
+        return {
+            name: stringValue(entry.name, `${label}.name`, true),
+            login: nullableString(entry.login, `${label}.login`),
+            bot: entry.bot,
+            resolution: entry.resolution
+        };
+    };
+    const issue = (raw, label) => {
+        const entry = record(raw, label);
+        exactKeys(entry, ['id', 'identity', 'number', 'title', 'displayUrl', 'author'], label);
+        return {
+            id: stringValue(entry.id, `${label}.id`),
+            identity: identity(entry.identity, `${label}.identity`, declaredIdentityKind(declaration, 'issue')),
+            number: positiveNumberValue(entry.number, `${label}.number`),
+            title: stringValue(entry.title, `${label}.title`, true),
+            displayUrl: stringValue(entry.displayUrl, `${label}.displayUrl`, true),
+            author: releaseAuthor(entry.author, `${label}.author`)
+        };
+    };
     return {
-        history: stableUnique(arrayValue(item.history, 'release notes.history').map((raw) => {
+        history: uniqueInOrder(arrayValue(item.history, 'release notes.history').map((raw) => {
             const entry = record(raw, 'release notes.history[]');
-            exactKeys(entry, ['sha', 'message', 'authoredAt', 'author'], 'release notes.history[]');
-            return { sha: stringValue(entry.sha, 'history.sha'), message: stringValue(entry.message, 'history.message', true), authoredAt: utcTimestamp(entry.authoredAt, 'history.authoredAt'), author: author(entry.author, 'history.author') };
-        }), (entry) => entry.sha, 'release notes.history'),
-        mergedPullRequests: stableUnique(arrayValue(item.mergedPullRequests, 'release notes.mergedPullRequests').map((entry) => validateChangeRequest(entry, declaredIdentityKind(declaration, 'pull-request'), true)), (entry) => serializeResourceIdentity(entry.identity), 'release notes.mergedPullRequests'),
-        closingIssues: stableUnique(arrayValue(item.closingIssues, 'release notes.closingIssues').map((entry) => validateIssue(entry, declaredIdentityKind(declaration, 'issue'), true)), (entry) => serializeResourceIdentity(entry.identity), 'release notes.closingIssues'),
-        actors: stableUnique(arrayValue(item.actors, 'release notes.actors').map((entry) => {
-            const actor = author(entry, 'release notes.actor');
-            if (!actor)
-                throw new Error('release notes.actor must identify an actor');
-            return actor;
-        }), (entry) => entry.id || entry.name || '', 'release notes.actors')
+            exactKeys(entry, ['tag', 'body', 'url'], 'release notes.history[]');
+            return { tag: stringValue(entry.tag, 'history.tag'), body: stringValue(entry.body, 'history.body', true), url: nullableString(entry.url, 'history.url') };
+        }), (entry) => entry.tag, 'release notes.history'),
+        commits: stableUnique(arrayValue(item.commits, 'release notes.commits').map((raw) => {
+            const entry = record(raw, 'release notes.commits[]');
+            exactKeys(entry, ['sha', 'url', 'pullRequestNumbers', 'authors'], 'release notes.commits[]');
+            return {
+                sha: stringValue(entry.sha, 'commits.sha'),
+                url: nullableString(entry.url, 'commits.url'),
+                pullRequestNumbers: stableUnique(arrayValue(entry.pullRequestNumbers, 'commits.pullRequestNumbers').map((number) => positiveNumberValue(number, 'commits.pullRequestNumbers[]')), (number) => String(number), 'commits.pullRequestNumbers'),
+                authors: arrayValue(entry.authors, 'commits.authors').map((rawAuthor) => {
+                    const normalized = releaseAuthor(rawAuthor, 'commits.author');
+                    if (!normalized)
+                        throw new Error('commits.author must identify an author');
+                    return normalized;
+                })
+            };
+        }), (entry) => entry.sha, 'release notes.commits'),
+        mergedPullRequests: stableUnique(arrayValue(item.mergedPullRequests, 'release notes.mergedPullRequests').map((raw) => {
+            const entry = record(raw, 'release notes.mergedPullRequests[]');
+            exactKeys(entry, ['id', 'identity', 'number', 'title', 'body', 'mergedAt', 'displayUrl', 'labels', 'author', 'closingIssues'], 'release notes.mergedPullRequests[]');
+            return {
+                id: stringValue(entry.id, 'pullRequest.id'),
+                identity: identity(entry.identity, 'pullRequest.identity', declaredIdentityKind(declaration, 'pull-request')),
+                number: positiveNumberValue(entry.number, 'pullRequest.number'),
+                title: stringValue(entry.title, 'pullRequest.title', true),
+                body: stringValue(entry.body, 'pullRequest.body', true),
+                mergedAt: utcTimestamp(entry.mergedAt, 'pullRequest.mergedAt'),
+                displayUrl: stringValue(entry.displayUrl, 'pullRequest.displayUrl', true),
+                labels: stringArray(entry.labels, 'pullRequest.labels'),
+                author: releaseAuthor(entry.author, 'pullRequest.author'),
+                closingIssues: stableUnique(arrayValue(entry.closingIssues, 'pullRequest.closingIssues').map((entry) => issue(entry, 'pullRequest.closingIssues[]')), (entry) => serializeResourceIdentity(entry.identity), 'pullRequest.closingIssues')
+            };
+        }), (entry) => serializeResourceIdentity(entry.identity), 'release notes.mergedPullRequests')
     };
 }
 function utcTimestamp(value, label) {

package/dist/lib/platform/release-notes.js

@@ -154,16 +154,16 @@ async function releaseNoteContext(input, options = {}) {
         return { ...baseResult(platform.error.retryable ? 'blocked' : 'failed'), error: providerError(platform.error, 'PLATFORM_PROVIDER_OPERATION_FAILED') };
     const commits = commitFacts.map((commit) => {
         const seen = new Set();
-        const authors = platform.value.history.filter((item) => item.sha === commit.oid).flatMap((item) => item.author ? [item.author] : [])
-            .concat(platform.value.actors)
+        const facts = platform.value.commits.find((item) => item.sha === commit.oid);
+        const authors = (facts?.authors || [])
             .filter((actor) => {
-            const key = actor.id || actor.name || '';
+            const key = actor.login || actor.name;
             if (seen.has(key))
                 return false;
             seen.add(key);
             return true;
         });
-        return { ...commit, authors };
+        return { ...commit, url: facts?.url || null, pullRequestNumbers: facts?.pullRequestNumbers || [], authors };
     });
     const pullRequests = platform.value.mergedPullRequests
         .map((item) => ({
@@ -174,14 +174,13 @@ async function releaseNoteContext(input, options = {}) {
         url: item.displayUrl || '',
         mergedAt: item.mergedAt || '',
         labels: item.labels || [],
-        author: item.author ? { login: item.author.name || item.author.id || '', bot: false } : null,
-        closingIssues: platform.value.closingIssues.filter((issue) => issue.id === item.id).map((issue) => ({
+        author: item.author,
+        closingIssues: item.closingIssues.map((issue) => ({
             number: issue.number || resourceIdentityNumber(issue.identity) || 0,
             ...(issue.identity ? { identity: issue.identity } : {}),
             title: issue.title,
             url: issue.displayUrl || '',
-            labels: issue.labels || [],
-            author: issue.author ? { login: issue.author.name || issue.author.id || '', bot: false } : null
+            author: issue.author
         }))
     }))
         .sort((left, right) => left.number - right.number);

package/dist/lib/platform/verification-sync.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import process from "node:process";
 import { execFileSync } from "node:child_process";
+import { resolveBranchWorktree } from "../git/branch-worktree.js";
 import { resolvePlatformProviderContext } from "./context.js";
 import { hasCheckedRequirement, resolveRequirementSection } from "./issue-metadata.js";
 import { requirementSectionAnchors } from "./issues.js";
@@ -807,7 +808,10 @@ function computeExpectedInLabels(taskDir, repositoryLabels, mappingOverride, sha
         return { ok: false, type: "check_failed", message: "Task has no delivery_base_ref for in-label evidence" };
     }
     const branch = typeof task.metadata?.branch === "string" ? task.metadata.branch.trim() : "";
-    const gitCwd = branch ? worktreeForBranch(shared.repoRoot, branch) ?? taskDir : taskDir;
+    const gitCwd = branch ? resolveBranchWorktree(shared.repoRoot, branch) : taskDir;
+    if (!gitCwd) {
+        return { ok: false, type: "check_failed", message: `Task branch '${branch}' is not checked out in a usable worktree` };
+    }
     const changedFilesResult = gitText(["diff", `${baseRef}...HEAD`, "--name-only"], gitCwd);
     if (!changedFilesResult.ok) {
         return { ...changedFilesResult, type: "network_error" };
@@ -831,26 +835,6 @@ function computeExpectedInLabels(taskDir, repositoryLabels, mappingOverride, sha
     }
     return { ok: true, labels: planned.target, mode: "mapped" };
 }
-function worktreeForBranch(repositoryRoot, branch) {
-    try {
-        const records = execFileSync("git", ["worktree", "list", "--porcelain"], {
-            cwd: repositoryRoot,
-            encoding: "utf8",
-            stdio: ["pipe", "pipe", "pipe"]
-        }).trim().split(/\r?\n\r?\n/);
-        const expectedRef = `refs/heads/${branch}`;
-        for (const record of records) {
-            const worktree = /^worktree (.+)$/m.exec(record)?.[1];
-            const branchRef = /^branch (.+)$/m.exec(record)?.[1];
-            if (worktree && branchRef === expectedRef)
-                return worktree;
-        }
-    }
-    catch {
-        // Fall back to taskDir so ordinary in-repository task workspaces retain their behavior.
-    }
-    return null;
-}
 function loadInLabelMapping(shared) {
     const configPath = path.join(shared.repoRoot, ".agents", ".airc.json");
     if (!fs.existsSync(configPath)) {
@@ -888,36 +872,15 @@ function resolvePrHeadSha(context) {
     if (!branch) {
         return fallback();
     }
-    const worktreeList = gitText(["worktree", "list", "--porcelain"], context.taskDir);
-    if (!worktreeList.ok) {
-        return fallback();
-    }
-    const matchedWorktree = findWorktreeForBranch(worktreeList.value, branch);
+    const matchedWorktree = resolveBranchWorktree(context.taskDir, branch);
     if (!matchedWorktree) {
-        return fallback();
-    }
-    const headInWorktree = gitText(["rev-parse", "HEAD"], matchedWorktree);
-    if (!headInWorktree.ok) {
-        return fallback();
-    }
-    return headInWorktree;
-}
-function findWorktreeForBranch(porcelainOutput, branch) {
-    let currentWorktree = "";
-    for (const rawLine of String(porcelainOutput || "").split("\n")) {
-        const line = rawLine.trimEnd();
-        if (line.startsWith("worktree ")) {
-            currentWorktree = line.slice("worktree ".length).trim();
-            continue;
-        }
-        if (line.startsWith("branch refs/heads/")) {
-            const usedBranch = line.slice("branch refs/heads/".length).trim();
-            if (usedBranch === branch && currentWorktree) {
-                return currentWorktree;
-            }
-        }
+        return {
+            ok: false,
+            type: "check_failed",
+            message: `Task branch '${branch}' is not checked out in a usable worktree`
+        };
     }
-    return null;
+    return gitText(["rev-parse", "HEAD"], matchedWorktree);
 }
 function interpolate(template, taskDir, artifactFile) {
     const artifactStem = artifactFile ? path.basename(artifactFile, path.extname(artifactFile)) : "";

package/dist/lib/sandbox/capture.js

@@ -154,7 +154,7 @@ export async function runInSandbox(request, options = {}) {
             allowRecreate: request.recreate,
             recreate: async () => {
                 const { create } = await import('./commands/create.js');
-                await create([request.taskRef, '--no-refresh']);
+                await create([request.taskRef, '--no-refresh'], { runProjectInitCommand: false });
             }
         })).container;
     }

package/dist/lib/sandbox/commands/create.js

@@ -18,6 +18,7 @@ import { createSandboxCapabilityPlan, runSandboxHooks, runBoundedSandboxHookComm
 import { resolveTools, tmpfsSeedStagingPath, tmpfsSeedTargetPath, toolConfigDirCandidates } from '../tools.js';
 import { assertFreshSandboxReady, hydrateTmpfsSeedEntries, prepareTmpfsMounts, startSandboxControlBroker } from '../recovery.js';
 import { acquireSandboxControlReplacement, assertSandboxControlCutoverSnapshot, beginSandboxControlReplacement, captureSandboxControlCutoverSnapshot, commitSandboxControlReplacement, quiesceSandboxControlRoot, recoverSandboxControlReplacement, readSandboxControlManifest } from '../control/lifecycle.js';
+import { atomicWriteJson } from '../control/state.js';
 import { inspectSandboxControlContainer } from '../control/container-identity.js';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.js';
 import { sandboxCoreBindMounts } from '../mounts.js';
@@ -652,7 +653,24 @@ function readImageLabels(config, engine) {
         config.imageName
     ]));
 }
-export async function create(args) {
+function readProjectInitCommandDigest(controlRoot) {
+    const markerPath = path.join(controlRoot, 'project-init.json');
+    if (!fs.existsSync(markerPath))
+        return null;
+    try {
+        const marker = JSON.parse(fs.readFileSync(markerPath, 'utf8'));
+        return marker.version === 1 && typeof marker.commandSha256 === 'string' && /^[a-f0-9]{64}$/.test(marker.commandSha256)
+            ? marker.commandSha256
+            : null;
+    }
+    catch {
+        return null;
+    }
+}
+function writeProjectInitCommandDigest(controlRoot, commandSha256) {
+    atomicWriteJson(path.join(controlRoot, 'project-init.json'), { version: 1, commandSha256 });
+}
+export async function create(args, { runProjectInitCommand = true } = {}) {
     const { values, positionals } = parseArgs({
         args,
         allowPositionals: true,
@@ -720,6 +738,7 @@ export async function create(args) {
         identity: target.workspace
     });
     const worktree = worktreeCandidates.find((candidate) => fs.existsSync(candidate)) ?? worktreeCandidates[0] ?? '';
+    let worktreeCreated = false;
     const shareCommon = shareCommonDir(effectiveConfig);
     const shareBranch = shareBranchDir(effectiveConfig, branch);
     const preparedDockerfile = prepareDockerfile(effectiveConfig, capabilityPlan.image);
@@ -821,6 +840,7 @@ export async function create(args) {
                             toEnginePath(engine, worktree),
                             branch
                         ]);
+                        worktreeCreated = true;
                     }
                     else {
                         message(`Creating branch '${branch}' from '${baseBranch}'...`);
@@ -834,6 +854,7 @@ export async function create(args) {
                             toEnginePath(engine, worktree),
                             baseBranch
                         ]);
+                        worktreeCreated = true;
                     }
                     return `Worktree ready at ${worktree}`;
                 }
@@ -886,6 +907,7 @@ export async function create(args) {
                     let replacementCutover = null;
                     try {
                         const recoveryResult = await recoverSandboxControlReplacement(controlPaths.root, replacementLease);
+                        const previousProjectInitCommandDigest = readProjectInitCommandDigest(controlPaths.root);
                         const hadExistingControlRoot = hadControlRootBeforeAcquire || recoveryResult === 'restored';
                         const previousManifest = fs.existsSync(controlPaths.manifestPath)
                             ? readSandboxControlManifest(controlPaths.manifestPath)
@@ -1295,6 +1317,29 @@ export async function create(args) {
                             throw new Error(afterStartFailure.message
                                 ?? `Sandbox hook '${afterStartFailure.hookId}' failed.`);
                         }
+                        const initCommand = effectiveConfig.initCommand;
+                        const initCommandDigest = initCommand === null ? null : createHash('sha256').update(initCommand).digest('hex');
+                        const shouldRunProjectInitCommand = runProjectInitCommand
+                            && initCommand !== null
+                            && initCommandDigest !== null
+                            && (worktreeCreated || previousProjectInitCommandDigest !== initCommandDigest);
+                        let projectInitCompleted = !worktreeCreated
+                            && initCommandDigest !== null
+                            && previousProjectInitCommandDigest === initCommandDigest;
+                        if (shouldRunProjectInitCommand && initCommand !== null) {
+                            try {
+                                runVerboseEngine(engine, 'docker', [
+                                    'exec', '--workdir', '/workspace', container, 'bash', '-lc', initCommand
+                                ]);
+                                projectInitCompleted = true;
+                            }
+                            catch (error) {
+                                throw new Error(`Project initialization failed for '${branch}': ${error instanceof Error ? error.message : String(error)}`);
+                            }
+                        }
+                        if (projectInitCompleted && initCommandDigest !== null) {
+                            writeProjectInitCommandDigest(controlPaths.root, initCommandDigest);
+                        }
                         replacementLease.release();
                         replacementLeaseHeld = false;
                         return 'Container started';

package/dist/lib/sandbox/commands/enter.js

@@ -109,7 +109,7 @@ export async function enter(args) {
         allowRecreate: parsed.recreate,
         recreate: async () => {
             const { create } = await import('./create.js');
-            await create([target.requestedRef, '--no-refresh']);
+            await create([target.requestedRef, '--no-refresh'], { runProjectInitCommand: false });
         }
     });
     const container = ready.container;

package/dist/lib/sandbox/commands/start.js

@@ -65,7 +65,7 @@ export async function start(args) {
         forceRecreate: parsed.recreate,
         recreate: async () => {
             const { create } = await import('./create.js');
-            await create([target.requestedRef, '--no-refresh']);
+            await create([target.requestedRef, '--no-refresh'], { runProjectInitCommand: false });
         }
     });
     const message = ready.path === 'healthy'

package/dist/lib/sandbox/config.js

@@ -14,6 +14,7 @@ const DEFAULTS = Object.freeze({
     tools: ['agent-infra'],
     refreshIntervalDays: 7,
     dockerfile: null,
+    initCommand: null,
     vm: {
         cpu: null,
         memory: null,
@@ -44,6 +45,7 @@ function cloneDefaults() {
         tools: [...DEFAULTS.tools],
         refreshIntervalDays: DEFAULTS.refreshIntervalDays,
         dockerfile: DEFAULTS.dockerfile,
+        initCommand: DEFAULTS.initCommand,
         vm: { ...DEFAULTS.vm }
     };
 }
@@ -77,6 +79,13 @@ export function loadConfig({ platformFn = platform, writeStderr = (chunk) => pro
         ? [...sandbox.runtimes]
         : defaults.runtimes;
     const dockerfile = typeof sandbox.dockerfile === 'string' ? sandbox.dockerfile : defaults.dockerfile ?? null;
+    if (sandbox.initCommand !== undefined &&
+        (typeof sandbox.initCommand !== 'string' || sandbox.initCommand.trim().length === 0)) {
+        throw new Error('sandbox.initCommand must be a non-empty string when configured');
+    }
+    const initCommand = typeof sandbox.initCommand === 'string'
+        ? sandbox.initCommand
+        : null;
     if (!dockerfile) {
         let enginesNode;
         try {
@@ -118,6 +127,7 @@ export function loadConfig({ platformFn = platform, writeStderr = (chunk) => pro
         },
         refreshIntervalDays: asNonNegativeIntegerOrDefault(sandbox.refreshIntervalDays, defaults.refreshIntervalDays),
         dockerfile,
+        initCommand,
         vm: {
             cpu: asPositiveNumberOrNull(sandbox.vm?.cpu) ?? defaults.vm.cpu,
             memory: asPositiveNumberOrNull(sandbox.vm?.memory) ?? defaults.vm.memory,

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

@@ -340,15 +340,18 @@ export function requestSandboxTaskFinalization(params) {
         clientError('SANDBOX_CONTROL_REQUEST_INVALID', 'task-finalization agent is invalid', false);
     const auth = authority(params);
     const issuedAt = Date.now();
+    const id = randomUUID();
+    const handoffSha256 = (params.prepareHandoff ?? (() => '0'.repeat(64)))({ generation: auth.generation, requestId: id });
     const request = {
         version: 3,
-        id: randomUUID(),
+        id,
         ...auth,
         issuedAt,
         expiresAt: issuedAt + SANDBOX_CONTROL_ADMISSION_WINDOW_MS,
         family: 'task-finalization',
         operation: 'complete',
         agent,
+        handoffSha256,
         args: [],
         controllerProcess: null,
         controllerProof: null

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

@@ -2,6 +2,7 @@ import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
+import { homedir } from 'node:os';
 import { getProcessStartTime } from '../../server/process-state.js';
 import { createTask, projectTaskCreateResult, taskCreateExitCode, taskCreateFailure } from '../../task/create-service.js';
 import { applyTaskFinalization } from '../../task/finalization.js';
@@ -13,6 +14,10 @@ import { createSandboxExecutorExecutionContext, dispatchTaskControlOperation, pa
 import { assertSandboxControlBrokerOwner, readSandboxControlManifest } from './lifecycle.js';
 import { computeLifecycleBuildIdentity } from '../../agent-clients/adapters/codex-lifecycle/build-identity.js';
 import { closeCodexControllerRegistration, CodexControllerRegistrationError, openCodexControllerRegistration, resolveCodexControllerBinding } from './controller-registration.js';
+import { shareBranchDir } from '../constants.js';
+function handoffDirectory(manifest) {
+    return shareBranchDir({ shareBase: path.join(homedir(), '.agent-infra', 'share', manifest.project) }, manifest.branch);
+}
 function sameBrokerOwner(left, right) {
     return left.version === right.version
         && left.pid === right.pid
@@ -295,9 +300,10 @@ async function executeRequestInner(manifest, manifestPath, request, options = {}
         }
     }
     if (request.family === 'task-finalization') {
-        const operation = parseTaskControlOperation('task-finalization', [manifest.taskId, 'complete', '--agent', request.agent]);
-        if (operation.family !== 'task-finalization')
+        const parsed = parseTaskControlOperation('task-finalization', [manifest.taskId, 'complete', '--agent', request.agent]);
+        if (parsed.family !== 'task-finalization')
             throw new Error('SANDBOX_CONTROL_FINALIZATION_OPERATION_INVALID');
+        const operation = { ...parsed, request: { ...parsed.request, handoffSha256: request.handoffSha256 } };
         const result = dispatchTaskControlOperation(createSandboxExecutorExecutionContext({
             repoRoot: manifest.repoRoot,
             worktreeRoot: manifest.worktreeRoot,
@@ -305,7 +311,8 @@ async function executeRequestInner(manifest, manifestPath, request, options = {}
             taskId: manifest.taskId,
             generation: manifest.generation,
             manifestPath,
-            requestId: request.id
+            requestId: request.id,
+            handoffDirectory: handoffDirectory(manifest)
         }), operation);
         return finalizationResult(await result);
     }
@@ -326,7 +333,8 @@ async function executeRequestInner(manifest, manifestPath, request, options = {}
         taskId: manifest.taskId,
         generation: manifest.generation,
         manifestPath,
-        requestId: request.id
+        requestId: request.id,
+        handoffDirectory: handoffDirectory(manifest)
     });
     const format = (value) => {
         const result = value;

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

@@ -1152,17 +1152,25 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
     if (!manifest && brokerLive)
         throw new Error('SANDBOX_CONTROL_OWNER_MISMATCH');
     const platform = options.platform ?? process.platform;
+    const processControl = options.executionProcessControl ?? {
+        isAlive: (execution) => executionAlive(execution, platform, identityProbe),
+        terminate: (execution, phase) => phase === 'graceful'
+            ? terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false, identityProbe })
+            : terminateSandboxControlExecution(execution, {
+                platform, timeoutMs: Math.max(0, deadlineAt - Date.now()), deadlineAt, forceAt: Date.now(), identityProbe
+            })
+    };
     let executions = manifest ? readExecutions(manifest) : [];
     const owner = brokerLive ? broker : statusLive ? statusOwner : null;
     if (!owner) {
         if (manifest && !broker && !status)
             throw new Error('SANDBOX_CONTROL_OWNER_EVIDENCE_MISSING');
         for (const execution of executions) {
-            terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false, identityProbe });
+            processControl.terminate(execution, 'graceful');
         }
         const softDeadlineAt = Math.min(forceAt, Date.now() + Math.floor(Math.max(0, forceAt - Date.now()) / 2));
         while (Date.now() < softDeadlineAt) {
-            if (!executions.some((execution) => executionAlive(execution, platform, identityProbe)))
+            if (!executions.some((execution) => processControl.isAlive(execution)))
                 break;
             await new Promise((resolve) => setTimeout(resolve, 25));
         }
@@ -1171,29 +1179,26 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
         if (Date.now() >= deadlineAt)
             throw new Error('SANDBOX_CONTROL_QUIESCE_DEADLINE_EXCEEDED');
         for (const execution of executions) {
-            if (!terminateSandboxControlExecution(execution, {
-                platform, timeoutMs: Math.max(0, deadlineAt - Date.now()), deadlineAt, forceAt: Date.now(), identityProbe
-            })) {
+            if (!processControl.terminate(execution, 'force')) {
                 throw new Error(`SANDBOX_CONTROL_EXECUTION_STILL_RUNNING: ${execution.requestId}`);
             }
         }
-        if (executions.some((execution) => executionAlive(execution, platform, identityProbe))) {
+        if (executions.some((execution) => processControl.isAlive(execution))) {
             throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
         }
         return broker || status ? 'stale' : 'missing';
     }
-    const remaining = () => Math.max(0, deadlineAt - Date.now());
     signalOwner(owner, platform, false);
     for (const execution of executions) {
-        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, allowForce: false, identityProbe });
+        processControl.terminate(execution, 'graceful');
     }
     const softDeadlineAt = Math.min(forceAt, Date.now() + Math.floor(Math.max(0, forceAt - Date.now()) / 2));
     while (Date.now() < softDeadlineAt) {
-        if (!ownerLive(owner, identityProbe) && !executions.some((execution) => executionAlive(execution, platform, identityProbe)))
+        if (!ownerLive(owner, identityProbe) && !executions.some((execution) => processControl.isAlive(execution)))
             break;
         await new Promise((resolve) => setTimeout(resolve, 25));
     }
-    if (!ownerLive(owner, identityProbe) && !executions.some((execution) => executionAlive(execution, platform, identityProbe))) {
+    if (!ownerLive(owner, identityProbe) && !executions.some((execution) => processControl.isAlive(execution))) {
         return 'stopped';
     }
     if (manifest)
@@ -1201,17 +1206,17 @@ export async function quiesceSandboxControlRoot(root, options = {}) {
     if (Date.now() >= deadlineAt)
         throw new Error('SANDBOX_CONTROL_QUIESCE_DEADLINE_EXCEEDED');
     for (const execution of executions) {
-        terminateSandboxControlExecution(execution, { platform, timeoutMs: 0, deadlineAt, forceAt: Date.now(), identityProbe });
+        processControl.terminate(execution, 'force');
     }
     signalOwner(owner, platform, true);
     while (Date.now() < deadlineAt) {
-        if (!ownerLive(owner, identityProbe) && !executions.some((execution) => executionAlive(execution, platform, identityProbe)))
+        if (!ownerLive(owner, identityProbe) && !executions.some((execution) => processControl.isAlive(execution)))
             return 'stopped';
         await new Promise((resolve) => setTimeout(resolve, 25));
     }
     if (ownerLive(owner, identityProbe))
         throw new Error('SANDBOX_CONTROL_BROKER_STILL_RUNNING');
-    if (executions.some((execution) => executionAlive(execution, platform, identityProbe)))
+    if (executions.some((execution) => processControl.isAlive(execution)))
         throw new Error('SANDBOX_CONTROL_EXECUTION_STILL_RUNNING');
     return 'stopped';
 }

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

@@ -158,11 +158,12 @@ export function validateSandboxControlRequest(value, manifest, options = {}) {
         return request;
     }
     if (request.family === 'task-finalization') {
-        const expected = ['agent', 'args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'id', 'issuedAt', 'operation', 'token', 'version'];
+        const expected = ['agent', 'args', 'controllerProcess', 'controllerProof', 'expiresAt', 'family', 'generation', 'handoffSha256', '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');
         }