@fitlab-ai/agent-infra 0.11.9 → 0.11.11

package/dist/lib/task/verification-engine.js

@@ -19,7 +19,7 @@ import { inspectDecisionDetailDuplicates } from "./decision-details.js";
 import { parseImplementationInputs } from "./implementation-inputs.js";
 import { scanVisibleMarkdown } from "./markdown.js";
 import { loadVerificationConfig } from "./verification-config.js";
-import { inspectActivityLog } from "./activity-log.js";
+import { inspectActivityLog, pairEntries } from "./activity-log.js";
 import { parseWorkflowWarnings } from "./workflow-warnings.js";
 import { OrchestrationStateError, readRun } from "./orchestration.js";
 import { readPrDeliveryFact } from "./pr-delivery-fact.js";
@@ -30,9 +30,11 @@ import { normalizeVerificationRecord } from './gate-policy.js';
 import { manualValidationFinalSummaryProjectionMatches } from "./manual-validation-receipt.js";
 import { readManualValidationCompletion } from "./manual-validation-completion.js";
 import { sha256File } from "./artifact-receipts.js";
+import { inspectArtifactDirectory } from "./artifact-lifecycle.js";
+import { parseArtifactName } from "./artifact-name.js";
 import { summaryCommentState } from "../platform/pr-summary.js";
 import { taskIssueIdentity } from "../platform/task-identities.js";
-import { hasArtifactCompletionFact, hasArtifactCompletionLog } from './completion-facts.js';
+import { hasArtifactCompletionFact, hasArtifactCompletionLog, parseCompletionFacts } from './completion-facts.js';
 import { inspectReviewIdentity } from './review-identity.js';
 const TASK_ENUMS = {
     type: ["feature", "bugfix", "refactor", "docs", "chore"],
@@ -264,7 +266,7 @@ function checkOrchestrationEvidence({ taskDir }) {
     return passResult('orchestration-evidence', 'Persisted orchestration model and delegation evidence is internally consistent');
 }
 // === Check Functions ===
-function checkTaskMeta({ taskDir, config, repositoryRoot }) {
+function checkTaskMeta({ taskDir, config, repositoryRoot, skillName, artifactFile }) {
     const task = loadTask(taskDir);
     if (!task.ok) {
         return failResult("task-meta", task.message);
@@ -306,7 +308,22 @@ function checkTaskMeta({ taskDir, config, repositoryRoot }) {
     }
     const expectedStep = config.expected_step;
     if (expectedStep && metadata.current_step !== expectedStep) {
-        return failResult("task-meta", `Expected current_step '${expectedStep}', got '${metadata.current_step || "(empty)"}'`);
+        let validLifecycleArtifact = false;
+        if (currentTask) {
+            const activityConfig = loadVerificationConfig(repositoryRoot, skillName).checks?.["activity-log"];
+            const { section, invalidEntries } = inspectActivityLog(task.content);
+            if (activityConfig && section && invalidEntries.length === 0) {
+                let latestAction = "";
+                for (const entry of section.entries) {
+                    if (!ACTIVITY_LOG_STARTED_RE.test(entry.step))
+                        latestAction = entry.step;
+                }
+                validLifecycleArtifact = checkArtifactLifecycleActivityLog(taskDir, artifactFile, skillName, activityConfig, task, section.entries, latestAction)?.status === "pass";
+            }
+        }
+        if (!validLifecycleArtifact) {
+            return failResult("task-meta", `Expected current_step '${expectedStep}', got '${metadata.current_step || "(empty)"}'`);
+        }
     }
     const expectedStatus = config.expected_status;
     if (expectedStatus && metadata.status !== expectedStatus) {
@@ -604,7 +621,73 @@ function checkImplementationInput({ taskDir, artifactFile }) {
     }
     return passResult("implementation-input", `${actionDecision} matches Activity Log, report, and task table`);
 }
-function checkActivityLog({ taskDir, config }) {
+const ARTIFACT_ACTIVITY_STAGES = {
+    "analyze-task": { family: "analysis", event: "analyze.completed" },
+    "plan-task": { family: "plan", event: "plan.completed" },
+    "review-analysis": { family: "review-analysis", event: "review-analysis.completed" },
+    "review-plan": { family: "review-plan", event: "review-plan.completed" },
+    "code-task": { family: "code", event: "code.completed" },
+    "review-code": { family: "review-code", event: "review-code.completed" }
+};
+function checkArtifactLifecycleActivityLog(taskDir, artifactFile, skillName, config, task, entries, latestAction) {
+    const stage = ARTIFACT_ACTIVITY_STAGES[skillName];
+    if (!stage)
+        return null;
+    const inventory = inspectArtifactDirectory(taskDir, stage.family);
+    if (inventory.status !== "ready" || !inventory.latest) {
+        return failResult("activity-log", `Current ${stage.family} artifact is unavailable: ${inventory.error?.message ?? "no artifact exists"}`);
+    }
+    const output = artifactFile || inventory.latest.name;
+    if (output !== inventory.latest.name) {
+        return failResult("activity-log", `Artifact '${output}' is not the current ${stage.family} artifact; rerun ${skillName} for '${inventory.latest.name}'`);
+    }
+    const identity = parseArtifactName(output);
+    if (!identity || identity.family !== stage.family) {
+        return failResult("activity-log", `Artifact '${output}' does not belong to ${stage.family}`);
+    }
+    if (!hasArtifactCompletionFact(task.content, path.join(taskDir, output), stage.event)) {
+        return failResult("activity-log", `Completion fact for '${output}' is missing or stale; rerun ${skillName} to record a current completion`);
+    }
+    const frontmatter = parseTypedTaskFrontmatter(task.content);
+    const fact = parseCompletionFacts(frontmatter.completion_facts).find((item) => item.event === stage.event && item.output === output);
+    if (!fact)
+        return failResult("activity-log", `Completion fact for '${output}' is missing; rerun ${skillName}`);
+    if (!Array.isArray(fact.lifecycleInputs)) {
+        return failResult("activity-log", `Completion fact for '${output}' has no input snapshot; rerun ${skillName}`);
+    }
+    for (const input of fact.lifecycleInputs) {
+        if (!input || typeof input.name !== "string" || !/^[a-f0-9]{64}$/u.test(input.sha256)) {
+            return failResult("activity-log", `Completion fact for '${output}' has an invalid input snapshot; rerun ${skillName}`);
+        }
+        const inputIdentity = parseArtifactName(input.name);
+        if (!inputIdentity)
+            return failResult("activity-log", `Completion fact for '${output}' has invalid input '${input.name}'; rerun ${skillName}`);
+        const inputInventory = inspectArtifactDirectory(taskDir, inputIdentity.family);
+        if (inputInventory.status !== "ready" || inputInventory.latest?.name !== input.name
+            || sha256File(path.join(taskDir, input.name)) !== input.sha256) {
+            return failResult("activity-log", `Input '${input.name}' changed or is no longer current; rerun ${skillName} to refresh '${output}'`);
+        }
+    }
+    const expectedAction = new RegExp(config.expected_action_pattern);
+    const roundAction = entries.find((entry) => {
+        if (ACTIVITY_LOG_STARTED_RE.test(entry.step))
+            return false;
+        if (!expectedAction.test(entry.step))
+            return false;
+        expectedAction.lastIndex = 0;
+        const actionRound = /\(Round (\d+)/.exec(entry.step)?.[1];
+        return actionRound === String(identity.round) && entry.note.includes(`→ ${output}`);
+    });
+    if (!roundAction) {
+        return failResult("activity-log", `No completed Activity Log row records '${output}' for ${skillName} Round ${identity.round}`);
+    }
+    if (skillName === "plan-task" && /^(?:Human Decision|Decision)\b/.test(latestAction)
+        && expectedAction.test(latestAction)) {
+        return passResult("activity-log", `Plan completion '${output}' is current; latest action '${latestAction}' is a human decision`);
+    }
+    return passResult("activity-log", `Current ${stage.family} completion '${output}' is valid for Round ${identity.round}`);
+}
+function checkActivityLog({ taskDir, config, skillName, artifactFile }) {
     const task = loadTask(taskDir);
     if (!task.ok) {
         return failResult("activity-log", task.message);
@@ -638,6 +721,9 @@ function checkActivityLog({ taskDir, config }) {
             doneActions.push(action);
         }
     }
+    const artifactLifecycleResult = checkArtifactLifecycleActivityLog(taskDir, artifactFile, skillName, config, task, entries, latestAction);
+    if (artifactLifecycleResult)
+        return artifactLifecycleResult;
     if (config.expected_action_pattern && !new RegExp(config.expected_action_pattern).test(latestAction)) {
         const expected = new RegExp(config.expected_action_pattern);
         let index = doneActions.length - 1;
@@ -799,7 +885,10 @@ async function checkManualValidation({ taskDir, repositoryRoot }) {
     const inspectedLog = inspectActivityLog(task.content);
     if (!inspectedLog.section)
         return failResult("manual-validation", "Activity Log is missing or invalid");
-    const reviewDoneIndex = inspectedLog.section.entries.findIndex((entry) => entry.step === `Review Code (Round ${review.round})`);
+    const reviewRow = pairEntries(inspectedLog.section.entries).find((row) => row.step === `Review Code (Round ${review.round})` && row.started !== '' && row.done !== '');
+    const reviewDoneIndex = reviewRow
+        ? inspectedLog.section.entries.findIndex((entry) => entry.step === reviewRow.step && entry.time === reviewRow.done)
+        : -1;
     const completedIndex = inspectedLog.section.entries.findIndex((entry) => entry.step === "Complete Manual Validation"
         && entry.note.includes(`Manual validation passed → ${artifactName};`)
         && entry.note.includes(`transaction=${receipt.transactionId};`)

package/dist/lib/task/write.js

@@ -6,7 +6,6 @@ import { parseTypedTaskFrontmatter, updateTaskFrontmatter } from './frontmatter.
 import { resolveTaskRef } from './resolve-ref.js';
 import { mutateTableRow, upsertSection } from './sections.js';
 import { validateCurrentTaskContract } from './current-contract.js';
-import { invalidationBlocks, parseInvalidationDocument } from './invalidation.js';
 const DEFAULT_FILE_SYSTEM = {
     readFileSync: (file) => fs.readFileSync(file, 'utf8'),
     statModeSync: (file) => fs.statSync(file).mode,
@@ -91,16 +90,6 @@ function writeTaskCore(request, options = {}) {
         if (!contract.ok) {
             return failure(request, identity, contract.code, contract.message);
         }
-        if (invalidationBlocks(contract.invalidation)
-            && options.invalidationContext !== 'source-completion'
-            && options.invalidationContext !== 'reconcile') {
-            return failure(request, identity, 'TASK_INVALIDATION_BLOCKED', 'task has an incomplete artifact invalidation operation; reconcile it before writing downstream state');
-        }
-    }
-    else {
-        const invalidation = parseInvalidationDocument(original);
-        if (!invalidation.ok)
-            return failure(request, identity, 'TASK_INVALIDATION_INVALID', invalidation.message);
     }
     let candidate = original;
     const operations = [];

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.11.9",
-  "sourceInputHash": "17fe6c91408c93e3aa5185e816025d590ded7db7e6a305fdce00751e78723abc",
-  "internalExecutableBuildHash": "8de9870e4ece1050564d7a3e77ee211a789dd975e3f94593300b7362ed815a00"
+  "packageVersion": "0.11.11",
+  "sourceInputHash": "576098e3f88ceca11a0a0f94573a3ceca2b14c97b29a6b934ae07849e214c889",
+  "internalExecutableBuildHash": "065375c31d3564a65236fc43bad9947395ea0873ae2531d9b05f42956ef30f1e"
 }

package/lib/agent-clients/adapter.ts

@@ -1,3 +1,4 @@
+import path from 'node:path';
 import {
   AGENT_CLIENT_CAPABILITY_IDS,
   AGENT_CLIENT_SUPPORT_LEVELS,
@@ -216,6 +217,26 @@ function freezeTool(tool: SandboxTool): SandboxTool {
   if (!tool.containerMount.startsWith('/')) {
     throw new Error(`Sandbox tool '${tool.id}' containerMount must be absolute`);
   }
+  if (tool.hostStateMounts !== undefined && !Array.isArray(tool.hostStateMounts)) {
+    throw new Error(`Agent Client '${tool.id}' hostStateMounts must be an array`);
+  }
+  const hostStateMounts = tool.hostStateMounts?.map((entry) => {
+    if (!entry || typeof entry.hostSubdir !== 'string' || typeof entry.containerSubpath !== 'string') {
+      throw new Error(`Agent Client '${tool.id}' hostStateMounts must contain relative path pairs`);
+    }
+    for (const value of [entry.hostSubdir, entry.containerSubpath]) {
+      const normalized = path.posix.normalize(value);
+      if (
+        value === ''
+        || path.posix.isAbsolute(value)
+        || normalized === '..'
+        || normalized.startsWith('../')
+      ) {
+        throw new Error(`Agent Client '${tool.id}' hostStateMounts must stay within the tool directories`);
+      }
+    }
+    return Object.freeze({ ...entry });
+  });
   if (!tool.versionCmd) {
     throw new Error(`Sandbox tool '${tool.id}' requires versionCmd`);
   }
@@ -233,6 +254,7 @@ function freezeTool(tool: SandboxTool): SandboxTool {
     ...(tool.hostLiveMounts ? {
       hostLiveMounts: Object.freeze(tool.hostLiveMounts.map((entry) => Object.freeze({ ...entry })))
     } : {}),
+    ...(hostStateMounts ? { hostStateMounts: Object.freeze(hostStateMounts) } : {}),
     ...(tool.postSetupCmds ? { postSetupCmds: Object.freeze([...tool.postSetupCmds]) } : {}),
     ...(tool.tmpfs ? {
       tmpfs: Object.freeze({

package/lib/agent-clients/adapters/codex-sandbox.ts

@@ -285,6 +285,19 @@ const codexRecoveryChecks: readonly AgentClientSandboxRecoveryCheck[] = [
       path: '/home/devuser/.codex'
     }
   },
+  {
+    id: 'app-server-package-writable',
+    probe: {
+      script: 'probe="$1/.agent-infra-app-server-package-$$"; trap \'rm -f -- "$probe"\' EXIT; : > "$probe"',
+      args: ['/home/devuser/.codex/packages/app-server-daemon'],
+      user: 'devuser'
+    },
+    finding: {
+      repairKind: 'hard-failure',
+      message: 'Codex app-server package directory is not writable by devuser.',
+      path: '/home/devuser/.codex/packages/app-server-daemon'
+    }
+  },
   {
     id: 'prompts-link',
     when: {

package/lib/agent-clients/adapters/codex.ts

@@ -55,6 +55,10 @@ const codexAdapter = defineAgentClientAdapter({
       versionCmd: 'codex --version',
       setupHint: 'Run codex once inside the container and choose Device Code login if needed.',
       tmpfs: { size: '512m', seed: ['config.toml', 'model-catalogs'], exec: true },
+      hostStateMounts: [{
+        hostSubdir: 'packages/app-server-daemon',
+        containerSubpath: 'packages/app-server-daemon'
+      }],
       hostLiveMounts: [
         {
           hostPath: hostJoin(home, '.codex', 'auth.json'),

package/lib/git/workflow.ts

@@ -100,7 +100,7 @@ function commitExplicitPaths(input: { cwd: string; paths: readonly string[]; mes
     const tree = value(runner, input.cwd, ['write-tree']);
     if (tree !== input.expectedTree) return { status: 'failed' as const, changed: false, snapshot: inspectGitWorkflow(input.cwd, runner).snapshot, operations: [{ name: 'stage', status: 'applied' as const }], error: { code: 'GIT_TREE_MISMATCH', message: `Expected staged tree ${input.expectedTree}, received ${tree ?? 'unavailable'}` } };
   }
-  const commit = run(runner, input.cwd, ['commit', '-m', input.message]);
+  const commit = run(runner, input.cwd, ['commit', '--cleanup=verbatim', '-m', input.message]);
   const after = inspectGitWorkflow(input.cwd, runner);
   if (commit.status !== 0) return { status: 'failed' as const, changed: false, snapshot: after.snapshot, operations: [{ name: 'commit', status: 'failed' as const, message: commit.stderr.trim() }], error: { code: 'GIT_COMMIT_FAILED', message: commit.stderr.trim() } };
   return { status: 'applied' as const, changed: true, snapshot: after.snapshot, operations: [{ name: 'stage', status: 'applied' as const }, { name: 'commit', status: 'applied' as const }], error: null };

package/lib/internal/cli-route-inventory.ts

@@ -60,7 +60,6 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'task-orchestration': ['status', 'progress'],
   'task-review': ['preflight', 'finalize-summary'],
   'task-event': ['event'],
-  'task-invalidation': ['reconcile'],
   'task-lifecycle': ['intent'],
   'task-finalization': ['complete'],
   'task-platform-recovery': ['inspect', 'recover'],
@@ -98,7 +97,6 @@ export function internalRouteSelector(command: string, args: readonly string[]):
   if (command === 'task-short-id') return first(args) === 'list' && args.includes('--verify') ? 'list-verify' : first(args);
   if (command === 'task-orchestration') return args[1] === 'status' ? 'status' : args[1] ? 'progress' : '';
   if (command === 'task-review') return args[1] ?? '';
-  if (command === 'task-invalidation') return args[1] ?? '';
   if (command === 'task-artifact') return args[1] ?? '';
   if (command === 'platform-pr-review' && first(args) === 'publish') {
     const scope = optionValue(args, '--scope') ?? '';

package/lib/internal/manual-validation.ts

@@ -206,7 +206,7 @@ async function executeManualValidationTransactionLocked(
     if (transaction.phase === 'prepared') {
       const staged = await syncPullRequestSummary(taskRef, {
         cwd, client: options.client, agent, body: pendingBody, changeReportFile: path.resolve(cwd, values.changeReportFile!), primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', strict: true,
-        manualValidation: { phase: 'pending' }, lockAlreadyHeld: true
+        manualValidation: { phase: 'pending', transactionId: transaction.transactionId }, lockAlreadyHeld: true
       });
       if (!['applied', 'no-op'].includes(staged.status)) transactionFailure(staged.error ?? { code: 'MANUAL_VALIDATION_TRANSACTION_FAILED', message: 'pending summary staging failed' });
       transitionAndPersist('summary-staged');
@@ -264,7 +264,7 @@ async function executeManualValidationTransactionLocked(
       try {
         await syncPullRequestSummary(taskRef, {
           cwd, client: options.client, agent, body: pendingBody, changeReportFile: path.resolve(cwd, values.changeReportFile!), primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', strict: true,
-          manualValidation: { phase: 'pending' }, lockAlreadyHeld: true
+          manualValidation: { phase: 'pending', transactionId: transaction.transactionId }, lockAlreadyHeld: true
         });
       } catch {
         // Preserve recovery-required when pending compensation cannot be confirmed.

package/lib/internal/platform-pr.ts

@@ -22,7 +22,7 @@ const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd
        agent-infra-internal platform-pr bind <task-ref> --pr <token> --agent <agent> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr skip <task-ref> --agent <agent> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr sync <task-ref> --agent <agent> [--metadata] [--closing-issue] --result <pr_created|pr_reused|no_op> [--dry-run] [--cwd <path>]
-       agent-infra-internal platform-pr sync-in-labels --pr <N> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr sync-in-labels --pr <token> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr summary-context <task-ref> [--cwd <path>]
        agent-infra-internal platform-pr change-report <task-ref> --agent <agent> --mechanical-file <path> --precheck-file <path> [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> --change-report-file <path> --result <pr_created|pr_reused|no_op> [--manual-phase pending|final ...] [--strict] [--dry-run] [--cwd <path>]
@@ -89,10 +89,9 @@ async function platformPr(args: string[] = []): Promise<void> {
     const values = parsed.values;
     const unexpected = Object.keys(values).find((name) => !['cwd', 'pr', 'dryRun'].includes(name));
     if (unexpected) { fail(`sync-in-labels does not accept --${unexpected}`); return; }
-    const pr = Number(values.pr);
-    if (!Number.isInteger(pr) || pr <= 0) { fail('sync-in-labels requires a positive --pr'); return; }
+    if (typeof values.pr !== 'string' || !values.pr || values.pr.trim() !== values.pr) { fail('sync-in-labels requires a non-empty --pr token'); return; }
     const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
-    finish(await syncPlatformPullRequestInLabels(pr, { cwd, dryRun: values.dryRun === true }));
+    finish(await syncPlatformPullRequestInLabels(values.pr, { cwd, dryRun: values.dryRun === true }));
     return;
   }
   const taskRef = args[1];

package/lib/internal/sandbox-control.ts

@@ -9,6 +9,7 @@ import { serveSandboxControl } from '../sandbox/control/server.ts';
 import { runSandboxControlExecutor } from '../sandbox/control/executor.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 import { parseTaskCreateResult, taskCreateExitCode } from '../task/create-service.ts';
+import { serializeTaskFinalizationEnvelope, type TaskFinalizationEnvelope } from '../task/finalization-envelope.ts';
 
 type FinalizationStatus = 'completed' | 'failed' | 'blocked' | 'unknown';
 
@@ -16,10 +17,11 @@ function writeFinalizationEnvelope(
   status: FinalizationStatus,
   accepted: boolean,
   error: { code: string; message: string; retryable: boolean },
-  changed = false,
-  result: unknown = null
+  changed: boolean | null = false,
+  result: unknown = null,
+  requestId: string | null = null
 ): void {
-  process.stdout.write(`${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`);
+  process.stdout.write(serializeTaskFinalizationEnvelope({ status, changed, accepted, requestId, result, error }));
 }
 
 function finalizationErrorStatus(error: { retryable: boolean; code: string }): FinalizationStatus {
@@ -43,6 +45,28 @@ function recoveredExitCode(response: Awaited<ReturnType<typeof recoverSandboxCon
   return response.exitCode ?? 1;
 }
 
+function finalizationResponseOutput(response: Awaited<ReturnType<typeof requestSandboxTaskFinalization>>): string {
+  try {
+    const value = JSON.parse(response.stdout) as Partial<TaskFinalizationEnvelope>;
+    if (value.version === 2
+      && value.status
+      && ['completed', 'failed', 'blocked', 'unknown'].includes(value.status)
+      && (typeof value.changed === 'boolean' || value.changed === null)) {
+      return serializeTaskFinalizationEnvelope({
+        status: value.status,
+        changed: value.changed,
+        accepted: true,
+        requestId: response.id,
+        result: value.result ?? null,
+        error: value.error ?? null
+      });
+    }
+  } catch {
+    // Preserve non-envelope output for diagnostics from the executor.
+  }
+  return response.stdout;
+}
+
 function sandboxFinalizationClient(args: string[]): void {
   if (args.length !== 4 || !args[0] || args[1] !== 'complete' || args[2] !== '--agent' || !args[3]) {
     const error = { code: 'TASK_FINALIZATION_PAYLOAD_INVALID', message: 'task ref, complete intent, and --agent are required', retryable: false };
@@ -63,7 +87,8 @@ function sandboxFinalizationClient(args: string[]): void {
     response = requestSandboxTaskFinalization({ agent });
   } catch (error) {
     if (!(error instanceof SandboxControlClientError)) throw error;
-    writeFinalizationEnvelope(finalizationErrorStatus(error.detail), error.accepted, error.detail);
+    const status = finalizationErrorStatus(error.detail);
+    writeFinalizationEnvelope(status, error.accepted, error.detail, status === 'unknown' ? null : false, null, error.requestId);
     writeClientError(error);
     process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.detail.retryable ? 2 : 1;
     return;
@@ -74,12 +99,20 @@ function sandboxFinalizationClient(args: string[]): void {
       message: 'sandbox control rejected the finalization request',
       retryable: false
     };
-    writeFinalizationEnvelope(finalizationErrorStatus(error), error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN', error);
+    const status = finalizationErrorStatus(error);
+    writeFinalizationEnvelope(
+      status,
+      error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN',
+      error,
+      status === 'unknown' ? null : false,
+      null,
+      response.id
+    );
     process.stderr.write(`${error.message}\n`);
     process.exitCode = error.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.retryable ? 2 : 1;
     return;
   }
-  process.stdout.write(response.stdout);
+  process.stdout.write(finalizationResponseOutput(response));
   process.stderr.write(response.stderr);
   process.exitCode = response.exitCode ?? 1;
 }

package/lib/internal/task-artifact.ts

@@ -1,7 +1,7 @@
 import { parseArtifactCommand, executeArtifactCommand } from '../task/artifact-command.ts';
 import { ensureInternalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family> [--source-finding <id> --source-artifact <name> --source-sha256 <digest>]\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> preflight|finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, preflight, or finalize workflow artifact facts.\n`;
+const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family> [--reason-code <reason>] [--source-finding <id> --source-artifact <name> --source-sha256 <digest>]\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> preflight|finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, preflight, or finalize workflow artifact facts.\n`;
 
 
 function taskArtifact(args: string[] = []): void {

package/lib/internal/task-create.ts

@@ -7,7 +7,7 @@ import {
   SandboxControlClientError
 } from '../sandbox/control/client.ts';
 import { SANDBOX_CONTROL_MAX_BYTES } from '../sandbox/control/protocol.ts';
-import { validateTaskCreateCandidate } from '../task/create.ts';
+import { validateTaskCreateCandidate, type TaskCreateCandidateV1 } from '../task/create.ts';
 import {
   createTask,
   parseTaskCreateResult,
@@ -82,7 +82,20 @@ async function taskCreate(args: string[]): Promise<void> {
     const stat = fs.lstatSync(inputPath);
     if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('TASK_CREATE_INPUT_INVALID: input must be a regular file');
     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 inputContent = fs.readFileSync(inputPath, 'utf8');
+    let candidate: TaskCreateCandidateV1;
+    try {
+      candidate = validateTaskCreateCandidate(JSON.parse(inputContent));
+    } catch (error) {
+      const message = error instanceof Error ? error.message : String(error);
+      const code = /^([A-Z][A-Z0-9_]+)/.exec(message)?.[1] ?? 'TASK_CREATE_INPUT_INVALID';
+      output(failed(code, message, false, {
+        requestId: null,
+        accepted: false,
+        recovery: 'new-request-id'
+      }));
+      return;
+    }
     const environment = resolveSandboxControlTransport();
     if (environment.kind === 'fail-closed') {
       output(failed(environment.reasonCode ?? 'TASK_CONTROL_TRANSPORT_INVALID', 'sandbox client control configuration is invalid'));

package/lib/internal/task-finalization.ts

@@ -3,12 +3,11 @@ import {
   dispatchTaskControlOperation,
   parseTaskControlOperation
 } from '../task/control-authority.ts';
-import { applyTaskFinalization, bindTaskFinalizationReceipt, prepareTaskFinalization } from '../task/finalization.ts';
-import { publishTaskFinalizationHandoff } from '../task/finalization-handoff.ts';
+import { applyTaskFinalization } from '../task/finalization.ts';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
-import { verifyTaskEvent } from '../task/verification.ts';
 import { resolveSandboxControlTransport } from './task-operation-registry.ts';
 import { requestSandboxTaskFinalization, SandboxControlClientError } from '../sandbox/control/client.ts';
+import { serializeTaskFinalizationEnvelope } from '../task/finalization-envelope.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = 'Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n';
@@ -17,12 +16,13 @@ type FinalizationError = Readonly<{ code: string; message: string; retryable: bo
 
 function envelope(
   status: 'completed' | 'failed' | 'blocked' | 'unknown',
-  changed: boolean,
+  changed: boolean | null,
   accepted: boolean,
   result: Awaited<ReturnType<typeof applyTaskFinalization>> | null,
-  error: FinalizationError | null
+  error: FinalizationError | null,
+  requestId: string | null = null
 ): string {
-  return `${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`;
+  return serializeTaskFinalizationEnvelope({ status, changed, accepted, requestId, result, error });
 }
 
 function exitCode(status: 'completed' | 'failed' | 'blocked' | 'unknown'): number {
@@ -79,33 +79,23 @@ async function taskFinalization(args: string[] = []): Promise<void> {
   };
   const transport = resolveSandboxControlTransport(process.env, { localWorkflow: true });
   if (transport.kind === 'sandbox-local') {
-    const prepared = await prepareTaskFinalization(boundOperation.request, {
-      repoRoot,
-      preflight: (request, options) => verifyTaskEvent({ ...request, event: 'complete-task.hard-preflight' }, options)
-    });
-    if (prepared.status !== 'prepared') {
-      process.stdout.write(envelope(prepared.status, prepared.changed, true, prepared, prepared.error));
-      process.exitCode = exitCode(prepared.status);
-      return;
-    }
     try {
-      const response = requestSandboxTaskFinalization({
-        agent: boundOperation.request.agent,
-        prepareHandoff: (binding) => {
-          const receipt = bindTaskFinalizationReceipt(repoRoot, boundOperation.request.taskRef, binding);
-          return publishTaskFinalizationHandoff('/share/branch', receipt, binding);
-        }
-      });
+      const response = requestSandboxTaskFinalization({ agent: boundOperation.request.agent });
       process.stdout.write(response.stdout);
       process.stderr.write(response.stderr);
       process.exitCode = response.exitCode ?? 1;
       return;
     } catch (error) {
-      const detail = error instanceof SandboxControlClientError
-        ? error.detail
+      const clientError = error instanceof SandboxControlClientError ? error : null;
+      const detail = clientError
+        ? clientError.detail
         : { code: 'SANDBOX_CONTROL_CLIENT_FAILED', message: error instanceof Error ? error.message : String(error), retryable: false };
-      process.stdout.write(envelope(detail.retryable ? 'blocked' : 'failed', false, false, null, detail));
-      process.exitCode = detail.retryable ? 2 : 1;
+      const status = detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN'
+        ? 'unknown'
+        : detail.retryable ? 'blocked' : 'failed';
+      const changed = status === 'unknown' ? null : false;
+      process.stdout.write(envelope(status, changed, clientError?.accepted ?? false, null, detail, clientError?.requestId ?? null));
+      process.exitCode = exitCode(status);
       return;
     }
   }