@fitlab-ai/agent-infra 0.9.10 → 0.9.12

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

@@ -5,6 +5,7 @@ import { hasPlatformCapability } from "./adapters.js";
 import { inspectRequiredChecks } from "./pr-checks.js";
 import { resolvePlatformContext } from "./context.js";
 import { resolveReviewedHeadRelation } from "./merged-pr-equivalence.js";
+import { readPrDeliveryFact } from "../task/pr-delivery-fact.js";
 const CHECK_TYPE = "required-checks";
 const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
 function validPrNumber(value) {
@@ -30,7 +31,13 @@ function readHead(repoRoot) {
 }
 export function evaluateRequiredChecks(context, shared) {
     const { metadata, localHead, inspection, prFlow } = context;
-    if (prFlow === "disabled" || metadata.pr_status === "skipped" || !validPrNumber(metadata.pr_number)) {
+    const factRead = readPrDeliveryFact(metadata);
+    if (factRead.status === "invalid") {
+        return shared.failResult(CHECK_TYPE, factRead.error.message, "check_failed");
+    }
+    const fact = factRead.status === "valid" ? factRead.fact : null;
+    const prNumber = fact?.state === "bound" ? fact.identity.number : null;
+    if (prFlow === "disabled" || fact?.state === "skipped" || !validPrNumber(prNumber)) {
         return shared.passResult(CHECK_TYPE, "Skipped: required checks are not applicable to this task");
     }
     const reviewedHead = String(metadata.last_reviewed_commit || "");
@@ -78,7 +85,11 @@ export function check({ taskDir }, shared) {
     if (!task.ok)
         return shared.failResult(CHECK_TYPE, task.message);
     const prFlow = readPrFlow(shared.repoRoot);
-    if (prFlow === "disabled" || task.metadata.pr_status === "skipped" || !validPrNumber(task.metadata.pr_number)) {
+    const factRead = readPrDeliveryFact(task.metadata);
+    if (factRead.status === "invalid")
+        return shared.failResult(CHECK_TYPE, factRead.error.message, "check_failed");
+    const bound = factRead.status === "valid" && factRead.fact.state === "bound";
+    if (prFlow === "disabled" || (factRead.status === "valid" && factRead.fact.state === "skipped") || !bound) {
         return evaluateRequiredChecks({ metadata: task.metadata, localHead: null, inspection: null, prFlow }, shared);
     }
     const platform = resolvePlatformContext({ cwd: shared.repoRoot });

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

@@ -9,6 +9,7 @@ import { inspectGitHubIssueMetadata, requirementSectionAnchors } from "./issues.
 import { listRemoteComments } from "./issue-comments.js";
 import { taskTypeLabel } from "./metadata-labels.js";
 import { inspectGitHubPullRequest } from "./pull-requests.js";
+import { readPrDeliveryFact } from "../task/pr-delivery-fact.js";
 const CHECK_TYPE = "platform-sync";
 const VERSION_LINE_REGEX = /^[0-9]+\.[0-9]+\.x$/;
 const FRONTMATTER_FIELD_MAP = {
@@ -127,12 +128,16 @@ function buildSyncContext({ taskDir, config, artifactFile }) {
         return { earlyReturn: failResult(CHECK_TYPE, task.message) };
     }
     const issueNumber = parseIssueNumber(task.metadata.issue_number);
-    const prNumber = parsePrNumber(task.metadata.pr_number);
+    const fact = readPrDeliveryFact(task.metadata);
+    if (fact.status === "invalid") {
+        return { earlyReturn: failResult(CHECK_TYPE, fact.error.message, "check_failed") };
+    }
+    const prNumber = fact.status === "valid" && fact.fact.state === "bound" ? fact.fact.identity.number : null;
     if (config.when === "issue_number_exists" && !issueNumber) {
         return { earlyReturn: passResult(CHECK_TYPE, "Skipped: task has no issue_number") };
     }
-    if (config.when === "pr_number_exists" && !prNumber) {
-        return { earlyReturn: passResult(CHECK_TYPE, "Skipped: task has no pr_number") };
+    if (config.when === "pr_fact_bound" && !prNumber) {
+        return { earlyReturn: passResult(CHECK_TYPE, "Skipped: task has no verified bound pull request") };
     }
     if (!issueNumber) {
         return { earlyReturn: passResult(CHECK_TYPE, "Skipped: platform-sync not required for this task") };
@@ -276,7 +281,7 @@ function fetchRemoteData(context) {
     if (context.prMarker) {
         if (!context.prNumber) {
             return {
-                earlyReturn: failResult(CHECK_TYPE, "Expected a valid pr_number for PR comment verification", "check_failed")
+                earlyReturn: failResult(CHECK_TYPE, "Expected a verified bound pull request for PR comment verification", "check_failed")
             };
         }
         const prCommentsResult = listRemoteComments(githubClient, context.upstreamRepo, context.prNumber, context.taskDir);

package/dist/lib/pr-review/evidence-grading.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { parseTaskFrontmatter } from '../task/frontmatter.js';
+import { parseTypedTaskFrontmatter } from '../task/frontmatter.js';
+import { readPrDeliveryFact } from '../task/pr-delivery-fact.js';
 export class HostResolutionError extends Error {
     code;
     constructor(code, message) {
@@ -38,7 +39,7 @@ export function extractClosingIssueNumbers(body) {
 /**
  * Scan `.agents/workspace/active/{task-id}/task.md` files for tasks bound to the
  * PR number or to one of the PR's closing issues. A task is emitted at most once;
- * a direct `pr_number` hit takes priority over the issue-number reverse lookup.
+ * a verified fact identity hit takes priority over the issue-number reverse lookup.
  */
 export function collectHostCandidates(input) {
     const activeRoot = path.join(input.workspaceRoot, '.agents', 'workspace', 'active');
@@ -62,9 +63,16 @@ export function collectHostCandidates(input) {
         catch {
             continue;
         }
-        const frontmatter = parseTaskFrontmatter(content);
+        let frontmatter;
+        try {
+            frontmatter = parseTypedTaskFrontmatter(content);
+        }
+        catch {
+            continue;
+        }
         const issueNumber = toPositiveNumber(frontmatter.issue_number);
-        const prNumber = toPositiveNumber(frontmatter.pr_number);
+        const fact = readPrDeliveryFact(frontmatter);
+        const prNumber = fact.status === 'valid' && fact.fact.state === 'bound' ? fact.fact.identity.number : null;
         if (prNumber === input.prNumber) {
             candidates.push({ taskId: entry.name, taskDir, issueNumber, prNumber });
         }

package/dist/lib/process-data/normalize.js

@@ -1,4 +1,5 @@
 import { sha256 } from './store.js';
+import { normalizeAgentToken } from '../agent-clients/tokens.js';
 const TASK_ID_RE = /TASK-\d{8}-\d{6}/;
 const ACTIVITY_RE = /^- (\d{4}-\d{2}-\d{2} [^ ]+) — \*\*(.+?)\*\* by ([^ ]+) — (.+)$/gm;
 const LEDGER_RE = /^\|\s*((?:AN|PL|CD)-\d+)\s*\|\s*(analysis|plan|code)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|\s*([^|]+?)\s*\|$/gm;
@@ -9,15 +10,7 @@ function recordId(kind, identity, suffix = '') {
 }
 function canonicalActor(raw) {
     const lowered = raw.toLowerCase();
-    const aliases = {
-        'claude-code': 'claude',
-        'antigravity-cli': 'antigravity',
-        'gemini-cli': 'gemini',
-        gemini: 'gemini'
-    };
-    if (['claude', 'codex', 'antigravity', 'opencode', 'cursor', 'human'].includes(lowered))
-        return lowered;
-    return aliases[lowered] ?? null;
+    return normalizeAgentToken(lowered);
 }
 function nextOccurrence(occurrences, identity) {
     const occurrence = (occurrences.get(identity) ?? 0) + 1;

package/dist/lib/run/host.js

@@ -1,26 +1,55 @@
 import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
-function resolveCommand(file) {
-    if (process.platform !== 'win32' || path.extname(file)) {
-        return file;
-    }
-    const pathValue = process.env.Path || process.env.PATH || '';
-    const extensions = (process.env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean);
-    for (const dir of pathValue.split(path.delimiter).filter(Boolean)) {
+function resolveCommandDetails(file, platform = process.platform, env = process.env) {
+    if (path.isAbsolute(file))
+        return { path: file, source: 'absolute' };
+    const pathValue = platform === 'win32'
+        ? env.Path || env.PATH || ''
+        : env.PATH || '';
+    const extensions = platform === 'win32'
+        ? (path.extname(file)
+            ? ['']
+            : (env.PATHEXT || '.COM;.EXE;.BAT;.CMD').split(';').filter(Boolean))
+        : [''];
+    for (const dir of pathValue.split(path.delimiter)) {
         for (const extension of extensions) {
-            const lowerCandidate = path.join(dir, `${file}${extension.toLowerCase()}`);
-            if (fs.existsSync(lowerCandidate))
-                return lowerCandidate;
-            const upperCandidate = path.join(dir, `${file}${extension.toUpperCase()}`);
-            if (fs.existsSync(upperCandidate))
-                return upperCandidate;
+            const candidates = extension
+                ? [`${file}${extension.toLowerCase()}`, `${file}${extension.toUpperCase()}`]
+                : [file];
+            for (const candidateName of candidates) {
+                const candidate = path.resolve(dir || '.', candidateName);
+                try {
+                    const stat = fs.statSync(candidate);
+                    if (!stat.isFile())
+                        continue;
+                    if (platform !== 'win32' && (stat.mode & 0o111) === 0)
+                        continue;
+                    return {
+                        path: candidate,
+                        source: dir ? 'path' : 'current-directory',
+                        pathEntry: dir
+                    };
+                }
+                catch {
+                    // Keep searching the remaining PATH entries.
+                }
+            }
         }
     }
-    return file;
+    return { path: file, source: 'unresolved' };
+}
+function resolveCommand(file, platform = process.platform, env = process.env) {
+    return resolveCommandDetails(file, platform, env).path;
+}
+function resolveCommandFromAbsolutePath(file, platform = process.platform, env = process.env) {
+    const resolution = resolveCommandDetails(file, platform, env);
+    return resolution.source === 'path' && resolution.pathEntry && path.isAbsolute(resolution.pathEntry)
+        ? resolution.path
+        : null;
 }
-function needsShell(file) {
-    return process.platform === 'win32' && /\.(?:bat|cmd)$/i.test(file);
+function needsShell(file, platform = process.platform) {
+    return platform === 'win32' && /\.(?:bat|cmd)$/i.test(file);
 }
 export async function runHostCommand(command) {
     const [file, ...args] = command;
@@ -36,4 +65,5 @@ export async function runHostCommand(command) {
         child.on('close', (exitCode, signal) => resolve({ exitCode, signal }));
     });
 }
+export { needsShell, resolveCommand, resolveCommandFromAbsolutePath };
 //# sourceMappingURL=host.js.map

package/dist/lib/sandbox/agent-client-reconciler.js

@@ -15,15 +15,6 @@ function agentInfraTool(home) {
         setupHint: 'Provides the ai and agent-infra CLI commands inside the sandbox.'
     };
 }
-function compatAgentClientState(tools) {
-    return Object.fromEntries(listAgentClientAdapters().map((adapter) => [
-        adapter.id,
-        {
-            enabled: true,
-            installInSandbox: tools.includes(adapter.id)
-        }
-    ]));
-}
 function stableValue(value) {
     if (Array.isArray(value)) {
         return value.map(stableValue);
@@ -96,7 +87,7 @@ function hooksByPhase(adapters) {
     ])));
 }
 function createSandboxCapabilityPlan(config) {
-    const state = config.agentClientState ?? compatAgentClientState(config.tools);
+    const state = config.agentClientState;
     const selectedAgentClients = listInstalledAgentClientAdapters(state);
     const context = { home: config.home, project: config.project };
     const selectedTools = selectedAgentClients.map((adapter) => adapter.sandbox.createTool(context));
@@ -113,8 +104,9 @@ function createSandboxCapabilityPlan(config) {
     const nonClientTools = [];
     const selectedCustomTools = [];
     for (const id of config.tools) {
-        if (isAgentClientId(id))
-            continue;
+        if (isAgentClientId(id)) {
+            throw new Error(`Agent Client '${id}' must be provided by agentClientState`);
+        }
         if (id === 'agent-infra') {
             if (!nonClientTools.some((tool) => tool.id === id)) {
                 nonClientTools.push(agentInfraTool(config.home));

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

@@ -17,7 +17,7 @@ import { parseSandboxWorkspaceIdentity, resolveSandboxTarget, sameSandboxWorkspa
 import { createSandboxCapabilityPlan, runSandboxHooks, runBoundedSandboxHookCommand } from '../agent-client-reconciler.js';
 import { resolveTools, tmpfsSeedStagingPath, tmpfsSeedTargetPath, toolConfigDirCandidates } from '../tools.js';
 import { assertFreshSandboxReady, hydrateTmpfsSeedEntries, prepareTmpfsMounts, startSandboxControlBroker } from '../recovery.js';
-import { acquireSandboxControlReplacement, assertSandboxControlCutoverSnapshot, beginSandboxControlReplacement, captureSandboxControlCutoverSnapshot, commitSandboxControlReplacement, quiesceSandboxControlRoot, recoverSandboxControlReplacement, readSandboxControlManifestForTransition } from '../control/lifecycle.js';
+import { acquireSandboxControlReplacement, assertSandboxControlCutoverSnapshot, beginSandboxControlReplacement, captureSandboxControlCutoverSnapshot, commitSandboxControlReplacement, quiesceSandboxControlRoot, recoverSandboxControlReplacement, readSandboxControlManifest } from '../control/lifecycle.js';
 import { inspectSandboxControlContainer } from '../control/container-identity.js';
 import { hostJoin, toEnginePath, volumeArg } from '../engines/wsl2-paths.js';
 import { sandboxCoreBindMounts } from '../mounts.js';
@@ -879,7 +879,7 @@ export async function create(args) {
                         const recoveryResult = await recoverSandboxControlReplacement(controlPaths.root, replacementLease);
                         const hadExistingControlRoot = hadControlRootBeforeAcquire || recoveryResult === 'restored';
                         const previousManifest = fs.existsSync(controlPaths.manifestPath)
-                            ? readSandboxControlManifestForTransition(controlPaths.manifestPath)
+                            ? readSandboxControlManifest(controlPaths.manifestPath)
                             : null;
                         if (hadExistingControlRoot) {
                             await quiesceSandboxControlRoot(controlPaths.root);
@@ -1031,7 +1031,7 @@ export async function create(args) {
                                 ...(target.workspace.mode === 'task-bound' ? { runtimeDir: control.runtimeDir } : {}),
                                 ...(target.workspace.mode === 'task-bound'
                                     ? {
-                                        taskSource: assertSandboxTaskSource(effectiveConfig.repoRoot, target.workspace.taskId),
+                                        taskSources: [assertSandboxTaskSource(effectiveConfig.repoRoot, target.workspace.taskId)],
                                         taskId: target.workspace.taskId
                                     }
                                     : {})

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

@@ -1,5 +1,5 @@
 import { loadConfig } from '../config.js';
-import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel } from '../constants.js';
+import { assertValidBranchName, containerNameCandidates, sandboxBranchLabel, sandboxLabel, sandboxTaskIdLabel, sandboxWorkspaceModeLabel } from '../constants.js';
 import { detectEngine } from '../engine.js';
 import { ensureSandboxReady } from '../recovery.js';
 import { createSandboxCapabilityPlan, runBoundedSandboxHookCommand, runSandboxHooks } from '../agent-client-reconciler.js';
@@ -9,7 +9,7 @@ import { redactCommandError } from '../redaction.js';
 import { runInteractiveWithClipboardBridge } from '../clipboard/bridge.js';
 import { detectHostTimezone } from '../host-timezone.js';
 import { fetchSandboxRows, selectSandboxContainer, } from './list-running.js';
-import { resolveSandboxTarget } from '../workspace-identity.js';
+import { resolveSandboxReentryContext, resolveSandboxTarget } from '../workspace-identity.js';
 const USAGE = `Usage: ai sandbox exec [--recreate] <branch | TASK-id | N> [cmd...]
 
 N references an active task short id from
@@ -81,16 +81,30 @@ export async function enter(args) {
     const target = resolveSandboxTarget(parsed.target, config.repoRoot);
     const branch = target.branch;
     assertValidBranchName(branch);
-    const { running, nonRunning } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config));
+    const { running, nonRunning } = fetchSandboxRows(engine, sandboxLabel(config), sandboxBranchLabel(config), {
+        mode: sandboxWorkspaceModeLabel(config),
+        taskId: sandboxTaskIdLabel(config)
+    });
     const found = selectSandboxContainer([...running, ...nonRunning], containerNameCandidates(config, branch));
     if (!found) {
         throw new Error(`No sandbox found for branch '${branch}'. Run 'ai sandbox create ${branch}' to create one.`);
     }
+    const containerWorkspace = found.workspaceMode === 'task-bound' && found.taskId
+        ? { mode: 'task-bound', taskId: found.taskId }
+        : found.workspaceMode === 'branch-only'
+            ? { mode: 'branch-only' }
+            : { mode: 'legacy-invalid' };
+    const reentry = resolveSandboxReentryContext({
+        target,
+        containerWorkspace,
+        repoRoot: config.repoRoot
+    });
     const ready = await ensureSandboxReady({
         config,
         engine,
         branch,
-        workspace: target.workspace,
+        workspace: reentry.workspace,
+        reentry: reentry.reentry,
         row: found,
         allowRecreate: parsed.recreate,
         recreate: async () => {

package/dist/lib/sandbox/config.js

@@ -4,7 +4,6 @@ import { homedir, platform } from 'node:os';
 import { execFileSync } from 'node:child_process';
 import pc from 'picocolors';
 import { normalizeAgentClients } from '../agent-clients/config.js';
-import { isAgentClientId } from '../agent-clients/types.js';
 import { validateSandboxEngine } from './engine.js';
 import { hostJoin } from './engines/wsl2-paths.js';
 import { findRuntimeEngineMismatches } from './runtime-engines.js';
@@ -48,15 +47,9 @@ function cloneDefaults() {
         vm: { ...DEFAULTS.vm }
     };
 }
-function resolveSandboxToolIds(sandbox, agentClients, defaults) {
+function resolveSandboxToolIds(sandbox, defaults) {
     if (Array.isArray(sandbox.tools)) {
-        const tools = sandbox.tools.filter((tool) => typeof tool === 'string');
-        return agentClients.source === 'canonical'
-            ? tools.filter((tool) => !isAgentClientId(tool))
-            : tools;
-    }
-    if (agentClients.remainingSandboxTools !== undefined) {
-        return [...agentClients.remainingSandboxTools];
+        return sandbox.tools.filter((tool) => typeof tool === 'string');
     }
     return [...defaults];
 }
@@ -71,10 +64,10 @@ export function loadConfig({ platformFn = platform, writeStderr = (chunk) => pro
         throw new Error('No .agents/.airc.json found. Run "ai init" first.');
     }
     const airc = JSON.parse(fs.readFileSync(configPath, 'utf8'));
-    const sandboxInput = airc.sandbox;
     const agentClients = normalizeAgentClients(airc);
     const defaults = cloneDefaults();
     const sandbox = airc.sandbox ?? {};
+    const delivery = airc.delivery ?? {};
     const engine = validateSandboxEngine(sandbox.engine ?? defaults.engine, { platformFn });
     const project = airc.project;
     if (!project || typeof project !== 'string') {
@@ -99,7 +92,7 @@ export function loadConfig({ platformFn = platform, writeStderr = (chunk) => pro
         }
     }
     const customTools = parseCustomTools(sandbox.customTools, { home });
-    const tools = resolveSandboxToolIds(sandbox, agentClients, defaults.tools);
+    const tools = resolveSandboxToolIds(sandbox, defaults.tools);
     return {
         repoRoot,
         configPath,
@@ -119,7 +112,10 @@ export function loadConfig({ platformFn = platform, writeStderr = (chunk) => pro
         tools,
         customTools,
         agentClientState: agentClients.state,
-        agentClientSource: agentClients.source,
+        delivery: {
+            remote: typeof delivery.remote === 'string' ? delivery.remote : 'origin',
+            baseRef: typeof delivery.baseRef === 'string' ? delivery.baseRef : 'main'
+        },
         refreshIntervalDays: asNonNegativeIntegerOrDefault(sandbox.refreshIntervalDays, defaults.refreshIntervalDays),
         dockerfile,
         vm: {

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

@@ -1,15 +1,32 @@
-import { spawn, spawnSync } from 'node:child_process';
+import { spawn } from 'node:child_process';
 import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { getProcessStartTime } from '../../server/process-state.js';
 import { createTask } from '../../task/create-service.js';
 import { applyTaskFinalization } from '../../task/finalization.js';
-import { verifyTaskEvent } from '../../task/verification.js';
-import { bindSandboxControlTask } from './protocol.js';
-import { atomicWriteJson, executionPath, terminateSandboxControlExecution } from './state.js';
+import { bindSandboxControlTask, validateSandboxControlRequest } from './protocol.js';
+import { atomicWriteJson, executionPath, readActiveLease, terminateSandboxControlExecution } from './state.js';
+import { createSandboxExecutorExecutionContext, dispatchTaskControlOperation, parseTaskControlOperation } from '../../task/control-authority.js';
+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';
+function sameBrokerOwner(left, right) {
+    return left.version === right.version
+        && left.pid === right.pid
+        && left.startTime === right.startTime
+        && left.brokerId === right.brokerId
+        && left.token === right.token
+        && left.generation === right.generation;
+}
+export function assertSandboxControlExecutorAuthority(manifest, gateOwner) {
+    const owner = assertSandboxControlBrokerOwner(manifest);
+    if (gateOwner && !sameBrokerOwner(owner, gateOwner)) {
+        throw new Error('SANDBOX_CONTROL_GATE_OWNER_MISMATCH');
+    }
+    if (readActiveLease(manifest))
+        throw new Error('SANDBOX_CONTROL_HANDOFF_ACTIVE');
+}
 function safeEnv(env) {
     return Object.fromEntries(Object.entries(env).filter(([key]) => !key.toUpperCase().startsWith('AGENT_INFRA_CONTROL_')));
 }
@@ -74,12 +91,15 @@ export async function prepareSandboxControlExecution(params) {
         start(canWrite = () => true) {
             if (!child.connected)
                 throw new Error('SANDBOX_CONTROL_EXECUTOR_GATE_CLOSED');
+            if (!canWrite())
+                throw new Error('SANDBOX_CONTROL_OWNER_LOST');
+            const gateOwner = assertSandboxControlBrokerOwner(params.manifest);
             if (!canWrite())
                 throw new Error('SANDBOX_CONTROL_OWNER_LOST');
             atomicWriteJson(executionPath(params.manifest, params.request.id), { ...execution, phase: 'running', updatedAt: Date.now() });
             if (!canWrite())
                 throw new Error('SANDBOX_CONTROL_OWNER_LOST');
-            child.send({ version: 1, nonce });
+            child.send({ version: 1, nonce, owner: gateOwner });
         },
         completion,
         terminate(updateState = true) {
@@ -104,11 +124,16 @@ function waitForGate(nonce, timeoutMs = 2_000) {
             clearTimeout(timer);
             process.off('disconnect', onDisconnect);
             const value = message;
-            if (!value || value.version !== 1 || value.nonce !== nonce) {
+            const owner = value?.owner;
+            if (!value || value.version !== 1 || value.nonce !== nonce
+                || !owner || owner.version !== 3 || !Number.isSafeInteger(owner.pid) || (owner.pid ?? 0) <= 0
+                || typeof owner.startTime !== 'number' || !Number.isSafeInteger(owner.startTime)
+                || typeof owner.brokerId !== 'string' || owner.brokerId.length === 0
+                || typeof owner.token !== 'string' || typeof owner.generation !== 'string') {
                 reject(new Error('SANDBOX_CONTROL_EXECUTOR_GATE_INVALID'));
                 return;
             }
-            resolve();
+            resolve(owner);
         });
     });
 }
@@ -139,6 +164,16 @@ function orchestrationFailure(code, message) {
         stderr: ''
     };
 }
+function lifecycleFailure(code, message) {
+    return {
+        exitCode: 1,
+        stdout: `${JSON.stringify({
+            status: 'failed', changed: false,
+            error: { code, message }
+        })}\n`,
+        stderr: ''
+    };
+}
 function finalizationResult(result) {
     const payload = {
         version: 1,
@@ -154,19 +189,7 @@ function finalizationResult(result) {
         stderr: ''
     };
 }
-function isCodexPrepare(args) {
-    if (args[1] !== 'prepare')
-        return false;
-    const values = [];
-    for (let index = 2; index < args.length; index += 1) {
-        if (args[index] === '--client')
-            values.push(args[index + 1] ?? '');
-        else if (args[index]?.startsWith('--client='))
-            values.push(args[index].slice('--client='.length));
-    }
-    return values.length === 1 && values[0] === 'codex';
-}
-export function executeRequest(manifest, manifestPath, request, options = {}) {
+export async function executeRequest(manifest, manifestPath, request, options = {}) {
     if (request.family === 'task-create') {
         const result = createTask(request.candidate, { repoRoot: manifest.repoRoot });
         return {
@@ -220,12 +243,41 @@ export function executeRequest(manifest, manifestPath, request, options = {}) {
         }
     }
     if (request.family === 'task-finalization') {
-        return finalizationResult(applyTaskFinalization({ taskRef: manifest.taskId, intent: 'complete', agent: request.agent }, { repoRoot: manifest.repoRoot, preflight: (input, options) => verifyTaskEvent({ ...input, event: 'complete-task.hard-preflight' }, options) }));
+        const operation = parseTaskControlOperation('task-finalization', [manifest.taskId, 'complete', '--agent', request.agent]);
+        if (operation.family !== 'task-finalization')
+            throw new Error('SANDBOX_CONTROL_FINALIZATION_OPERATION_INVALID');
+        const result = dispatchTaskControlOperation(createSandboxExecutorExecutionContext({
+            repoRoot: manifest.repoRoot,
+            worktreeRoot: manifest.worktreeRoot,
+            runtimeDir: manifest.runtimeDir,
+            taskId: manifest.taskId,
+            generation: manifest.generation,
+            manifestPath,
+            requestId: request.id
+        }), operation);
+        return finalizationResult(result);
     }
     const boundArgs = bindSandboxControlTask(request, manifest.taskId);
+    if (request.family === 'task-orchestration') {
+        boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
+    }
+    let operation;
+    try {
+        operation = parseTaskControlOperation(request.family, boundArgs);
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        const code = /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1] ?? 'TASK_CONTROL_OPERATION_INVALID';
+        return request.family === 'task-lifecycle'
+            ? lifecycleFailure('LIFECYCLE_PAYLOAD_INVALID', message)
+            : orchestrationFailure(code, message);
+    }
     let controllerBinding = null;
     if (request.family === 'task-orchestration') {
-        if (isCodexPrepare(request.args)) {
+        const codexPrepare = operation.family === 'task-orchestration'
+            && operation.intent === 'prepare'
+            && operation.input.client === 'codex';
+        if (codexPrepare) {
             if (!request.controllerProof) {
                 return orchestrationFailure('CODEX_SANDBOX_CONTROLLER_PROOF_REQUIRED', 'Codex prepare requires a current controller lease proof');
             }
@@ -247,33 +299,73 @@ export function executeRequest(manifest, manifestPath, request, options = {}) {
         else if (request.controllerProof !== null) {
             return orchestrationFailure('CODEX_SANDBOX_CONTROLLER_PROOF_INVALID', 'Controller proof is only accepted for canonical Codex prepare');
         }
-        boundArgs.push('--git-worktree-root', manifest.worktreeRoot);
     }
-    const result = (options.spawnDomain ?? spawnSync)(process.execPath, nodeEntryArgs(process.argv[1], [request.family, ...boundArgs]), {
-        cwd: manifest.repoRoot,
-        encoding: 'utf8',
-        env: {
-            ...safeEnv(process.env),
-            AGENT_INFRA_RUNTIME_DIR: manifest.runtimeDir,
-            ...(controllerBinding
-                ? { AGENT_INFRA_CONTROL_CONTROLLER_BINDING: JSON.stringify(controllerBinding) }
-                : {})
-        }
+    const context = createSandboxExecutorExecutionContext({
+        repoRoot: manifest.repoRoot,
+        worktreeRoot: manifest.worktreeRoot,
+        runtimeDir: manifest.runtimeDir,
+        taskId: manifest.taskId,
+        generation: manifest.generation,
+        manifestPath,
+        requestId: request.id,
+        ...(controllerBinding ? { controllerBinding } : {})
     });
-    return { exitCode: result.status ?? 1, stdout: result.stdout ?? '', stderr: result.stderr ?? '' };
+    const format = (value) => {
+        const result = value;
+        return {
+            exitCode: result.status === 'failed' ? 1 : 0,
+            stdout: `${JSON.stringify(value)}\n`,
+            stderr: ''
+        };
+    };
+    if (request.family === 'task-orchestration') {
+        if (operation.family !== 'task-orchestration')
+            throw new Error('SANDBOX_CONTROL_ORCHESTRATION_OPERATION_INVALID');
+        return format(await dispatchTaskControlOperation(context, operation));
+    }
+    if (operation.family !== 'task-lifecycle')
+        throw new Error('SANDBOX_CONTROL_LIFECYCLE_OPERATION_INVALID');
+    return format(dispatchTaskControlOperation(context, operation));
 }
 export async function runSandboxControlExecutor(requestPath, nonce) {
-    await waitForGate(nonce);
+    const gateOwner = await waitForGate(nonce);
     process.disconnect?.();
-    const root = fs.realpathSync.native(process.cwd());
-    const request = JSON.parse(fs.readFileSync(requestPath, 'utf8'));
     const manifestPath = process.env.AGENT_INFRA_EXECUTOR_MANIFEST;
     if (!manifestPath)
         throw new Error('SANDBOX_CONTROL_EXECUTOR_MANIFEST_MISSING');
-    const manifest = JSON.parse(fs.readFileSync(manifestPath, 'utf8'));
+    const manifest = readSandboxControlManifest(manifestPath);
+    const root = fs.realpathSync.native(process.cwd());
     if (fs.realpathSync.native(manifest.repoRoot) !== root)
         throw new Error('SANDBOX_CONTROL_EXECUTOR_ROOT_INVALID');
-    const result = executeRequest(manifest, manifestPath, request);
+    const raw = JSON.parse(fs.readFileSync(requestPath, 'utf8'));
+    const request = validateSandboxControlRequest(raw, manifest);
+    const requestDirectory = path.resolve(path.dirname(requestPath));
+    const processingDirectory = path.resolve(path.join(manifest.processingDir, request.id));
+    const channelRequestDirectory = path.resolve(path.join(manifest.channelDir, 'requests'));
+    if (requestDirectory !== processingDirectory && requestDirectory !== channelRequestDirectory) {
+        throw new Error('SANDBOX_CONTROL_EXECUTOR_REQUEST_INVALID');
+    }
+    let result;
+    try {
+        assertSandboxControlExecutorAuthority(manifest, gateOwner);
+        result = await executeRequest(manifest, manifestPath, request);
+    }
+    catch (error) {
+        const detail = error instanceof Error ? error.message : String(error);
+        const code = /^([A-Z][A-Z0-9_]+)/u.exec(detail)?.[1] ?? 'SANDBOX_CONTROL_EXECUTOR_FAILED';
+        result = request.family === 'task-finalization'
+            ? {
+                exitCode: 1,
+                stdout: `${JSON.stringify({
+                    version: 1, status: 'failed', changed: false, accepted: true, result: null,
+                    error: { code, message: detail, retryable: false }
+                })}\n`,
+                stderr: ''
+            }
+            : request.family === 'task-lifecycle'
+                ? lifecycleFailure(code, detail)
+                : orchestrationFailure(code, detail);
+    }
     process.stdout.write(result.stdout);
     process.stderr.write(result.stderr);
     process.exitCode = result.exitCode;