@fitlab-ai/agent-infra 0.9.14 → 0.9.15

package/dist/lib/internal/sandbox-control.js

@@ -1,10 +1,106 @@
-import { recoverSandboxControl, requestSandboxControl, requestSandboxTaskFinalization, requestSandboxTaskControl, SandboxControlClientError } from '../sandbox/control/client.js';
+import { createHash, randomUUID } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { recoverSandboxControl, requestSandboxControl, requestSandboxTaskFinalization, requestSandboxTaskControl, requestSandboxTaskWorkflow, resolveVisibleActiveShortId, SandboxControlClientError } from '../sandbox/control/client.js';
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { serveSandboxControl } from '../sandbox/control/server.js';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.js';
 import { controllerProofFromContext, verifyCodexSandboxControllerContextWithWarnings } from '../agent-clients/adapters/codex-lifecycle/sandbox-controller.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 import { parseTaskCreateResult, taskCreateExitCode } from '../task/create-service.js';
+import { createTaskWorkflowRequest } from '../sandbox/control/task-workflow.js';
+import { computeLifecycleBuildIdentity } from '../agent-clients/adapters/codex-lifecycle/build-identity.js';
+import { routeOrchestration } from '../task/orchestration.js';
+import { parseArtifactName } from '../task/artifact-name.js';
+function valueAfter(args, flag) {
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === flag)
+            return args[index + 1];
+        if (args[index]?.startsWith(`${flag}=`))
+            return args[index].slice(flag.length + 1);
+    }
+    return undefined;
+}
+function withoutValue(args, flag) {
+    const result = [];
+    for (let index = 0; index < args.length; index += 1) {
+        if (args[index] === flag) {
+            index += 1;
+            continue;
+        }
+        if (args[index]?.startsWith(`${flag}=`))
+            continue;
+        result.push(args[index]);
+    }
+    return result;
+}
+function lifecycleIds(authorityRef, taskId) {
+    const digest = (label) => createHash('sha256')
+        .update(`${label}\0${taskId}\0${authorityRef}`, 'utf8')
+        .digest('hex');
+    return { operationId: digest('operation'), lifecycleRequestId: digest('lifecycle-request') };
+}
+function lifecycleAuthorityIdentity(authorityRef, taskId, requestId, phase, family, artifact, round) {
+    const contextPath = process.env.AGENT_INFRA_CODEX_CONTROLLER_CONTEXT;
+    if (!authorityRef || !contextPath)
+        return undefined;
+    const routed = verifyCodexSandboxControllerContextWithWarnings(contextPath, { repoRoot: process.cwd() });
+    const buildIdentity = computeLifecycleBuildIdentity(process.cwd());
+    const hookDefinitionHash = createHash('sha256')
+        .update(readFileSync(path.join(process.cwd(), '.codex', 'hooks.json')))
+        .digest('hex');
+    const ids = lifecycleIds(authorityRef, taskId);
+    return {
+        version: 1,
+        requestId,
+        operationId: ids.operationId,
+        phase,
+        taskId,
+        family,
+        artifact,
+        round,
+        lifecycleRequestId: ids.lifecycleRequestId,
+        authorityRef,
+        expectedControlGeneration: routed.context.controlGeneration,
+        expectedControllerInstanceDigest: routed.context.controllerInstanceDigest,
+        expectedBuildIdentityDigest: createHash('sha256').update(JSON.stringify(buildIdentity)).digest('hex'),
+        expectedHookDefinitionHash: hookDefinitionHash
+    };
+}
+function lifecycleAuthoritySelector(args) {
+    if (!isCanonicalCodexPrepare(args))
+        return undefined;
+    const authorityRef = valueAfter(args, '--capability-ref');
+    const taskId = args[0];
+    if (!authorityRef || !taskId)
+        return undefined;
+    const routed = routeOrchestration(taskId);
+    if (!routed.next || !['analysis', 'plan', 'code'].includes(routed.next.stage))
+        return undefined;
+    return lifecycleAuthorityIdentity(authorityRef, taskId, randomUUID(), 'orchestration.prepare', routed.next.stage === 'analysis' ? 'analysis' : routed.next.stage === 'plan' ? 'plan' : 'code', routed.next.artifact, routed.next.round);
+}
+function lifecycleWorkflowAuthoritySelector(originalArgs, workflow) {
+    const authorityRef = valueAfter(originalArgs, '--capability-ref');
+    if (!authorityRef)
+        return undefined;
+    if (workflow.operation === 'artifact-finalize-local') {
+        const family = valueAfter(workflow.args, '--family');
+        const artifact = valueAfter(workflow.args, '--artifact');
+        const parsed = artifact ? parseArtifactName(artifact) : null;
+        if ((family !== 'analysis' && family !== 'plan' && family !== 'code')
+            || !parsed || parsed.family !== family)
+            return undefined;
+        return lifecycleAuthorityIdentity(authorityRef, workflow.taskId, workflow.id, 'artifact.finalize-local', family, artifact, parsed.round);
+    }
+    if (workflow.operation !== 'event')
+        return undefined;
+    const completed = /^(analysis|plan|code)\.completed$/u.exec(workflow.args[1] ?? '');
+    const artifact = valueAfter(workflow.args, '--artifact');
+    const parsed = artifact ? parseArtifactName(artifact) : null;
+    if (!completed || !parsed || parsed.family !== completed[1])
+        return undefined;
+    return lifecycleAuthorityIdentity(authorityRef, workflow.taskId, workflow.id, 'task-event.completed', completed[1], artifact, parsed.round);
+}
 function isCanonicalCodexPrepare(args) {
     if (args[1] !== 'prepare')
         return false;
@@ -144,6 +240,51 @@ async function sandboxControl(args) {
             sandboxFinalizationClient(commandArgs);
             return;
         }
+        if (family === 'task-workflow') {
+            const command = commandArgs[0];
+            const taskId = process.env.AGENT_INFRA_TASK_ID;
+            const generation = process.env.AGENT_INFRA_CONTROL_GENERATION;
+            if (!command || !taskId || !generation) {
+                process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'SANDBOX_CONTROL_REQUEST_INVALID', message: 'task-workflow requires a bound task and generation' } })}\n`);
+                process.exitCode = 1;
+                return;
+            }
+            let workflow;
+            try {
+                const args = withoutValue(commandArgs.slice(1), '--capability-ref');
+                if (/^\d+$/.test(args[0] ?? '')) {
+                    const resolved = resolveVisibleActiveShortId(args[0]);
+                    if (resolved !== taskId)
+                        throw new Error('SANDBOX_TASK_REF_MISMATCH');
+                    args[0] = resolved;
+                }
+                workflow = createTaskWorkflowRequest(command, args, taskId, generation);
+            }
+            catch (error) {
+                process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'SANDBOX_CONTROL_REQUEST_INVALID', message: error instanceof Error ? error.message : String(error) } })}\n`);
+                process.exitCode = 1;
+                return;
+            }
+            let response;
+            try {
+                const authority = lifecycleWorkflowAuthoritySelector(commandArgs, workflow);
+                response = requestSandboxTaskWorkflow({
+                    workflow,
+                    ...(authority ? { authority } : {})
+                });
+            }
+            catch (error) {
+                if (!(error instanceof SandboxControlClientError))
+                    throw error;
+                writeClientError(error);
+                process.exitCode = error.detail.retryable ? 75 : 1;
+                return;
+            }
+            process.stdout.write(response.stdout);
+            process.stderr.write(response.stderr);
+            process.exitCode = response.phase === 'rejected' ? response.error?.retryable ? 75 : 1 : response.exitCode ?? 1;
+            return;
+        }
         let response;
         try {
             if (family === 'task-orchestration' && isCanonicalCodexPrepare(commandArgs)) {
@@ -151,7 +292,13 @@ async function sandboxControl(args) {
                 const proof = contextPath
                     ? controllerProofFromContext(verifyCodexSandboxControllerContextWithWarnings(contextPath).context)
                     : null;
-                response = requestSandboxTaskControl({ family, args: commandArgs, controllerProof: proof });
+                const authority = lifecycleAuthoritySelector(commandArgs);
+                response = requestSandboxTaskControl({
+                    family,
+                    args: commandArgs,
+                    controllerProof: authority ? null : proof,
+                    ...(authority ? { authority } : {})
+                });
             }
             else {
                 response = requestSandboxControl({ family, args: commandArgs });

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

@@ -1,45 +1,6 @@
-import fs from 'node:fs';
-import path from 'node:path';
-import { resolveArtifactContext } from '../task/artifact-lifecycle.js';
-import { parseArtifactName } from '../task/artifact-lifecycle.js';
-import { locateActivityLog, pairEntries, startedBackedRows } from '../task/activity-log.js';
-import { finalizeLocalArtifact } from '../task/local-artifact-finalization.js';
-import { resolveTaskRef } from '../task/resolve-ref.js';
-import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
-import { getArtifactSchema } from '../task/artifact-schema.js';
-import { applyArtifactRepair, initializeArtifactSkeleton, inspectArtifactStructure } from '../task/artifact-operations.js';
+import { parseArtifactCommand, executeArtifactCommand } from '../task/artifact-command.js';
+import { ensureInternalHandlerRoute } from './cli-route-inventory.js';
 const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> repair --family <family> --artifact <artifact> --expected-sha256 <sha256> --expected-semantic-digest <digest>\n       agent-infra-internal task-artifact <N | TASK-id> finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, repair, or finalize a workflow artifact without changing task state.\n`;
-function failUsage(message) {
-    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_PAYLOAD_INVALID', message } })}\n`);
-    process.stderr.write(USAGE);
-    process.exitCode = 2;
-}
-function hasOpenLocalArtifactRound(taskDir, family, round) {
-    try {
-        const activity = locateActivityLog(fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8'));
-        if (!activity)
-            return false;
-        const label = family === 'analysis'
-            ? 'Analyze Task'
-            : family === 'review-analysis'
-                ? 'Review Analysis'
-                : family === 'plan'
-                    ? 'Plan Task'
-                    : family === 'review-plan'
-                        ? 'Review Plan'
-                        : family === 'code'
-                            ? 'Code Task'
-                            : 'Review Code';
-        const qualifier = family === 'code'
-            ? '(?:, (?:fix for review-code(?:-r\\d+)?\\.md|decision II-[1-9]\\d*))?'
-            : '';
-        const expected = new RegExp(`^${label} \\(Round ${round}${qualifier}\\)$`);
-        return startedBackedRows(pairEntries(activity.entries)).some((row) => expected.test(row.step) && !row.done);
-    }
-    catch {
-        return false;
-    }
-}
 function taskArtifact(args = []) {
     if (!ensureInternalHandlerRoute('task-artifact', args))
         return;
@@ -47,232 +8,24 @@ function taskArtifact(args = []) {
         process.stdout.write(USAGE);
         return;
     }
-    if (args.length < 2) {
-        failUsage('task ref and operation are required');
-        return;
-    }
-    const operation = args[1];
-    if (!internalHandlerRoute('task-artifact', 'inspect', operation ?? '')
-        && !internalHandlerRoute('task-artifact', 'init', operation ?? '')
-        && !internalHandlerRoute('task-artifact', 'repair', operation ?? '')
-        && !internalHandlerRoute('task-artifact', 'finalize-local', operation ?? '')) {
-        failUsage(`unknown operation '${operation}'`);
-        return;
-    }
-    let family = '';
-    let artifact = '';
-    let locale;
-    let expectedSha256 = '';
-    let expectedSemanticDigest = '';
-    const seen = new Set();
-    for (let index = 2; index < args.length; index += 1) {
-        const flag = args[index];
-        if (flag !== '--family' && flag !== '--artifact' && flag !== '--locale' && flag !== '--expected-sha256' && flag !== '--expected-semantic-digest') {
-            failUsage(`unknown option '${flag}'`);
-            return;
-        }
-        if (seen.has(flag)) {
-            failUsage(`duplicate option '${flag}'`);
-            return;
-        }
-        const value = args[++index];
-        if (!value || value.startsWith('--')) {
-            failUsage(`option '${flag}' requires a value`);
-            return;
-        }
-        seen.add(flag);
-        if (flag === '--family')
-            family = value;
-        else if (flag === '--artifact')
-            artifact = value;
-        else if (flag === '--locale') {
-            if (value !== 'zh-CN' && value !== 'en') {
-                failUsage("option '--locale' must be 'zh-CN' or 'en'");
-                return;
-            }
-            locale = value;
-        }
-        else if (flag === '--expected-sha256')
-            expectedSha256 = value;
-        else
-            expectedSemanticDigest = value;
-    }
-    if (!family) {
-        failUsage("option '--family' is required");
-        return;
-    }
-    if ((operation === 'init' || operation === 'repair' || operation === 'finalize-local') && !artifact) {
-        failUsage("option '--artifact' is required");
-        return;
-    }
-    if (internalHandlerRoute('task-artifact', 'inspect', operation ?? '')) {
-        if (artifact || locale || expectedSha256 || expectedSemanticDigest) {
-            failUsage("artifact options are only valid for init, repair, or finalize-local");
-            return;
-        }
-        const result = resolveArtifactContext(args[0], family);
-        const output = family === 'code' && result.codeMode ? {
-            ...result,
-            mode: result.codeMode.mode,
-            code_max: result.codeMode.codeMax,
-            rev_max: result.codeMode.reviewMax,
-            verdict: result.codeMode.verdict,
-            next_round: result.next?.round ?? null,
-            next_artifact: result.next?.name ?? null,
-            review_artifact: result.codeMode.reviewArtifact,
-            implementation_input: result.codeMode.implementationInput,
-            decision_id: result.codeMode.decisionId,
-            decision_evidence: result.codeMode.decisionEvidence,
-            message: result.codeMode.message
-        } : result;
-        process.stdout.write(`${JSON.stringify(output)}\n`);
-        if (result.status === 'refused')
-            process.exitCode = 1;
-        else if (result.status === 'failed')
-            process.exitCode = 2;
-        return;
-    }
-    if (internalHandlerRoute('task-artifact', 'init', operation ?? '')) {
-        if (expectedSha256 || expectedSemanticDigest) {
-            failUsage("repair baseline options are only valid for repair");
-            return;
-        }
-        const schema = getArtifactSchema(family);
-        const resolved = resolveTaskRef(args[0]);
-        if (!schema) {
-            failUsage(`init does not support artifact family '${family}'`);
-            return;
-        }
-        if (!resolved.ok) {
-            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } })}\n`);
-            process.exitCode = 1;
-            return;
-        }
-        const parsed = parseArtifactName(artifact);
-        if (!parsed || parsed.family !== family) {
-            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_INIT_CONTEXT_INVALID', message: `artifact '${artifact}' does not match ${family}` } })}\n`);
-            process.exitCode = 1;
-            return;
-        }
-        const context = resolveArtifactContext(args[0], family);
-        const isNextArtifact = context.status === 'ready' && context.next?.name === artifact;
-        const isCurrentOpenArtifact = context.status === 'ready'
-            && context.taskDir !== null
-            && hasOpenLocalArtifactRound(context.taskDir, family, parsed.round);
-        if (!isNextArtifact && !isCurrentOpenArtifact) {
-            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_INIT_CONTEXT_INVALID', message: context.error?.message ?? `artifact '${artifact}' is not the next ${family} artifact` } })}\n`);
-            process.exitCode = 1;
-            return;
-        }
-        if (!context.taskId || !context.taskDir) {
-            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_INIT_CONTEXT_INVALID', message: `artifact '${artifact}' does not match ${family}` } })}\n`);
-            process.exitCode = 1;
-            return;
-        }
-        try {
-            const existing = fs.lstatSync(path.join(resolved.taskDir, artifact));
-            if (existing.isSymbolicLink() || !existing.isFile()) {
-                process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_INIT_TARGET_INVALID', message: 'artifact target is not a regular file' } })}\n`);
-                process.exitCode = 1;
-                return;
-            }
-            const result = initializeArtifactSkeleton({ repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskDir: resolved.taskDir, family: schema.family, artifact, ...(locale ? { locale } : {}) });
-            process.stdout.write(`${JSON.stringify({ ...result, taskId: resolved.taskId, taskDir: resolved.taskDir, family, artifact })}\n`);
-            if (result.status === 'failed')
-                process.exitCode = 1;
-            return;
-        }
-        catch (error) {
-            if (error.code !== 'ENOENT') {
-                process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_INIT_TARGET_INVALID', message: String(error) } })}\n`);
-                process.exitCode = 1;
-                return;
-            }
-        }
-        const result = initializeArtifactSkeleton({
-            repoRoot: resolved.repoRoot,
-            taskId: context.taskId,
-            taskDir: context.taskDir,
-            family: schema.family,
-            artifact,
-            ...(locale ? { locale } : {})
-        });
-        process.stdout.write(`${JSON.stringify({ ...result, taskId: context.taskId, taskDir: context.taskDir, family, artifact })}\n`);
-        if (result.status === 'failed')
-            process.exitCode = 1;
-        return;
-    }
-    if (internalHandlerRoute('task-artifact', 'repair', operation ?? '')) {
-        if (locale) {
-            failUsage("option '--locale' is only valid for init");
-            return;
-        }
-        if (!/^[a-f0-9]{64}$/.test(expectedSha256) || !/^[a-f0-9]{64}$/.test(expectedSemanticDigest)) {
-            failUsage("repair requires lowercase 64-character '--expected-sha256' and '--expected-semantic-digest'");
-            return;
-        }
-        const schema = getArtifactSchema(family);
-        const resolved = resolveTaskRef(args[0]);
-        const parsed = parseArtifactName(artifact);
-        if (!schema || !parsed || parsed.family !== family) {
-            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_REPAIR_TARGET_INVALID', message: `artifact '${artifact}' does not match ${family}` } })}\n`);
-            process.exitCode = 1;
-            return;
-        }
-        if (!resolved.ok) {
-            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } })}\n`);
-            process.exitCode = 1;
-            return;
-        }
-        let content;
-        try {
-            content = fs.readFileSync(path.join(resolved.taskDir, artifact), 'utf8');
-        }
-        catch (error) {
-            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_REPAIR_TARGET_INVALID', message: String(error) } })}\n`);
-            process.exitCode = 1;
-            return;
-        }
-        const inspection = inspectArtifactStructure(content, schema);
-        if (!inspection.repair) {
-            process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, artifact, family, diagnostics: inspection.diagnostics, error: { code: 'ARTIFACT_REPAIR_UNSAFE', message: inspection.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ') || 'no deterministic structural repair is available' } })}\n`);
-            process.exitCode = 1;
-            return;
-        }
-        const result = applyArtifactRepair({
-            repoRoot: resolved.repoRoot,
-            taskId: resolved.taskId,
-            taskDir: resolved.taskDir,
-            family: schema.family,
-            artifact,
-            expectedSha256,
-            expectedSemanticDigest,
-            operation: inspection.repair
-        });
-        process.stdout.write(`${JSON.stringify({ ...result, taskId: resolved.taskId, taskDir: resolved.taskDir, family, artifact })}\n`);
-        if (result.status === 'failed')
-            process.exitCode = 1;
-        return;
-    }
-    const resolved = resolveTaskRef(args[0]);
-    const repositoryRoot = resolved.ok ? resolved.repoRoot : process.cwd();
-    if (!artifact) {
-        failUsage("option '--artifact' is required");
-        return;
+    let command;
+    try {
+        command = parseArtifactCommand(args);
     }
-    if (family !== 'analysis' && family !== 'plan' && family !== 'code') {
-        failUsage("finalize-local only supports 'analysis', 'plan', and 'code'");
+    catch (error) {
+        process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: {
+                code: 'ARTIFACT_PAYLOAD_INVALID', message: error instanceof Error ? error.message : String(error)
+            } })}\n`);
+        process.stderr.write(USAGE);
+        process.exitCode = 2;
         return;
     }
-    const result = finalizeLocalArtifact({
-        taskRef: args[0],
-        family: family,
-        artifact,
-        repoRoot: repositoryRoot
-    });
+    const result = executeArtifactCommand(command);
     process.stdout.write(`${JSON.stringify(result)}\n`);
-    if (result.status === 'failed')
+    if (result.status === 'refused')
         process.exitCode = 1;
+    else if (result.status === 'failed')
+        process.exitCode = command.operation === 'inspect' ? 2 : 1;
 }
 export { taskArtifact };
 //# sourceMappingURL=task-artifact.js.map

package/dist/lib/internal/task-create.js

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
+import { resolveSandboxControlTransport } from './task-operation-registry.js';
 import path from 'node:path';
-import { classifySandboxControlEnvironment, requestSandboxTaskCreate, SandboxControlClientError } from '../sandbox/control/client.js';
+import { requestSandboxTaskCreate, SandboxControlClientError } from '../sandbox/control/client.js';
 import { SANDBOX_CONTROL_MAX_BYTES } from '../sandbox/control/protocol.js';
 import { validateTaskCreateCandidate } from '../task/create.js';
 import { createTask, parseTaskCreateResult, projectTaskCreateResult, taskCreateExitCode, taskCreateFailure } from '../task/create-service.js';
@@ -54,12 +55,12 @@ async function taskCreate(args) {
         if (stat.size > SANDBOX_CONTROL_MAX_BYTES)
             throw new Error('TASK_CREATE_INPUT_TOO_LARGE: input exceeds the control limit');
         const candidate = validateTaskCreateCandidate(JSON.parse(fs.readFileSync(inputPath, 'utf8')));
-        const environment = classifySandboxControlEnvironment();
-        if (environment.kind === 'invalid') {
-            output(failed(environment.code ?? 'TASK_CONTROL_TRANSPORT_INVALID', environment.message ?? 'sandbox client control configuration is invalid'));
+        const environment = resolveSandboxControlTransport();
+        if (environment.kind === 'fail-closed') {
+            output(failed(environment.reasonCode ?? 'TASK_CONTROL_TRANSPORT_INVALID', 'sandbox client control configuration is invalid'));
             return;
         }
-        if (environment.kind === 'controlled') {
+        if (environment.kind === 'broker-client') {
             const response = requestSandboxTaskCreate({ candidate });
             if (response.phase === 'rejected') {
                 const accepted = response.error?.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN';

package/dist/lib/internal/task-event.js

@@ -18,6 +18,7 @@ const FLAGS = {
     '--verdict': 'verdict', '--blockers': 'blockers', '--major': 'major',
     '--minor': 'minor', '--manual-validation': 'manualValidation', '--files-modified': 'filesModified',
     '--tests-passed': 'testsPassed', '--summary-result': 'summaryResult',
+    '--transaction-id': 'transactionId', '--receipt-digest': 'receiptDigest', '--pr-head-sha': 'prHeadSha',
     '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
 };
 const NUMERIC = new Set(['round', 'question', 'blockers', 'major', 'minor', 'manualValidation', 'filesModified', 'testsPassed']);
@@ -26,53 +27,35 @@ function usageFailure(message) {
     process.stderr.write(USAGE);
     process.exitCode = 1;
 }
-async function taskEvent(args = []) {
-    if (!ensureInternalHandlerRoute('task-event', args))
-        return;
-    if (args[0] === '--help' || args[0] === '-h') {
-        process.stdout.write(USAGE);
-        return;
-    }
-    if (args.length < 2 || !internalHandlerRoute('task-event', 'event', args[1] ? 'event' : '')) {
-        usageFailure('task ref and event are required');
-        return;
-    }
+export function parseTaskEventRequest(args) {
+    if (args.length < 2)
+        throw new Error('task ref and event are required');
     const request = { taskRef: args[0], event: args[1], agent: '' };
     const seen = new Set();
     for (let index = 2; index < args.length; index += 1) {
         const flag = args[index];
         if (flag === '--orchestrated') {
-            if (seen.has(flag)) {
-                usageFailure(`duplicate option '${flag}'`);
-                return;
-            }
+            if (seen.has(flag))
+                throw new Error(`duplicate option '${flag}'`);
             seen.add(flag);
             request.orchestrated = true;
             continue;
         }
         if (flag === '--dry-run') {
-            if (seen.has(flag)) {
-                usageFailure(`duplicate option '${flag}'`);
-                return;
-            }
+            if (seen.has(flag))
+                throw new Error(`duplicate option '${flag}'`);
             seen.add(flag);
             request.dryRun = true;
             continue;
         }
         const key = FLAGS[flag];
-        if (!key) {
-            usageFailure(`unknown option '${flag}'`);
-            return;
-        }
-        if (seen.has(flag)) {
-            usageFailure(`duplicate option '${flag}'`);
-            return;
-        }
+        if (!key)
+            throw new Error(`unknown option '${flag}'`);
+        if (seen.has(flag))
+            throw new Error(`duplicate option '${flag}'`);
         const value = args[++index];
-        if (value === undefined || value.startsWith('--')) {
-            usageFailure(`option '${flag}' requires a value`);
-            return;
-        }
+        if (value === undefined || value.startsWith('--'))
+            throw new Error(`option '${flag}' requires a value`);
         seen.add(flag);
         if (NUMERIC.has(key))
             request[key] = Number(value);
@@ -82,14 +65,31 @@ async function taskEvent(args = []) {
             request[key] = value;
     }
     const agent = normalizeAgentToken(String(request.agent ?? ''));
-    if (!agent) {
-        usageFailure(`invalid --agent '${request.agent}': ${AGENT_USAGE_HINT}`);
-        return;
-    }
+    if (!agent)
+        throw new Error(`invalid --agent '${request.agent}': ${AGENT_USAGE_HINT}`);
     request.agent = agent;
     const dryRunConflict = overrideDryRunConflict(request);
-    if (dryRunConflict) {
-        usageFailure(dryRunConflict.message);
+    if (dryRunConflict)
+        throw new Error(dryRunConflict.message);
+    return request;
+}
+async function taskEvent(args = []) {
+    if (!ensureInternalHandlerRoute('task-event', args))
+        return;
+    if (args[0] === '--help' || args[0] === '-h') {
+        process.stdout.write(USAGE);
+        return;
+    }
+    if (!internalHandlerRoute('task-event', 'event', args[1] ? 'event' : '')) {
+        usageFailure('task ref and event are required');
+        return;
+    }
+    let request;
+    try {
+        request = parseTaskEventRequest(args);
+    }
+    catch (error) {
+        usageFailure(error instanceof Error ? error.message : String(error));
         return;
     }
     const resolved = resolveTaskRef(request.taskRef);