@fitlab-ai/agent-infra 0.9.12 → 0.9.13

package/lib/internal/platform-pr.ts

@@ -8,24 +8,27 @@ import {
   inspectPlatformPullRequest,
   resolveExternalPullRequest,
   skipPlatformPullRequestFact,
-  syncPlatformPullRequest
+  syncPlatformPullRequest,
+  syncPlatformPullRequestInLabels
 } from '../platform/pull-requests.ts';
 import type { PullRequestResult } from '../platform/pull-requests.ts';
-import { summaryContext, syncPullRequestSummary } from '../platform/pr-summary.ts';
+import { reportWrite, summaryContext, syncPullRequestSummary } from '../platform/pr-summary.ts';
 import type { PlatformResult } from '../platform/types.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-pr inspect <task-ref> [--cwd <path>]
-       agent-infra-internal platform-pr resolve-external <task-ref> --agent <agent> [--pr <N>] [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr resolve-external <task-ref> --agent <agent> [--pr <token>] [--dry-run] [--cwd <path>]
        agent-infra-internal platform-pr create <task-ref> --agent <agent> --base <branch> --head <branch> --title-file <path|-> --body-file <path|-> [--draft] [--dry-run] [--cwd <path>]
-       agent-infra-internal platform-pr bind <task-ref> --pr <N> --agent <agent> [--dry-run] [--cwd <path>]
+       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 summary-context <task-ref> [--cwd <path>]
-       agent-infra-internal platform-pr summary-sync <task-ref> --agent <agent> --body-file <path|-> --result <pr_created|pr_reused|no_op> [--dry-run] [--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> [--strict] [--dry-run] [--cwd <path>]
 `;
 
-const BOOLEAN_FLAGS = new Set(['--draft', '--dry-run', '--metadata', '--closing-issue']);
-const VALUE_FLAGS = new Set(['--cwd', '--agent', '--base', '--head', '--title-file', '--body-file', '--pr', '--result']);
+const BOOLEAN_FLAGS = new Set(['--draft', '--dry-run', '--metadata', '--closing-issue', '--strict']);
+const VALUE_FLAGS = new Set(['--cwd', '--agent', '--base', '--head', '--title-file', '--body-file', '--change-report-file', '--mechanical-file', '--precheck-file', '--pr', '--result']);
 
 function key(flag: string): string {
   return flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
@@ -63,10 +66,22 @@ function readFile(value: string, cwd: string): string {
   return value === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, value), 'utf8');
 }
 
-function platformPr(args: string[] = []): void {
+async function platformPr(args: string[] = []): Promise<void> {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
-  if (!operation || !['inspect', 'resolve-external', 'create', 'bind', 'skip', 'sync', 'summary-context', 'summary-sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (!operation || !['inspect', 'resolve-external', 'create', 'bind', 'skip', 'sync', 'sync-in-labels', 'summary-context', 'change-report', 'summary-sync'].includes(operation)) { fail('a valid operation is required'); return; }
+  if (operation === 'sync-in-labels') {
+    const parsed = parse(args, 1);
+    if (parsed.error) { fail(parsed.error); return; }
+    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; }
+    const cwd = path.resolve(typeof values.cwd === 'string' ? values.cwd : process.cwd());
+    finish(await syncPlatformPullRequestInLabels(pr, { cwd, dryRun: values.dryRun === true }));
+    return;
+  }
   const taskRef = args[1];
   if (!taskRef || taskRef.startsWith('--')) { fail(`${operation} requires a task ref`); return; }
   const parsed = parse(args, 2);
@@ -80,19 +95,28 @@ function platformPr(args: string[] = []): void {
     bind: ['cwd', 'agent', 'pr', 'dryRun'],
     skip: ['cwd', 'agent', 'dryRun'],
     sync: ['cwd', 'agent', 'metadata', 'closingIssue', 'result', 'dryRun'],
+    'sync-in-labels': ['cwd', 'pr', 'dryRun'],
     'summary-context': ['cwd'],
-    'summary-sync': ['cwd', 'agent', 'bodyFile', 'result', 'dryRun']
+    'change-report': ['cwd', 'agent', 'mechanicalFile', 'precheckFile', 'dryRun'],
+    'summary-sync': ['cwd', 'agent', 'bodyFile', 'changeReportFile', 'result', 'dryRun', 'strict']
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
-  if (operation === 'inspect') { finish(inspectPlatformPullRequest(taskRef, { cwd })); return; }
-  if (operation === 'summary-context') { finish(summaryContext(taskRef, { cwd })); return; }
+  if (operation === 'inspect') { finish(await inspectPlatformPullRequest(taskRef, { cwd })); return; }
+  if (operation === 'summary-context') { finish(await summaryContext(taskRef, { cwd })); return; }
   if (typeof values.agent !== 'string' || !values.agent) { fail(`${operation} requires --agent`); return; }
   const agent = normalizeAgentToken(values.agent);
   if (!agent) { fail(`invalid --agent '${values.agent}': ${AGENT_USAGE_HINT}`); return; }
   values.agent = agent;
+  if (operation === 'change-report') {
+    if (typeof values.mechanicalFile !== 'string' || typeof values.precheckFile !== 'string') { fail('change-report requires --mechanical-file and --precheck-file'); return; }
+    finish(await reportWrite(taskRef, {
+      cwd, agent: values.agent, mechanicalFile: values.mechanicalFile, precheckFile: values.precheckFile, dryRun: values.dryRun === true
+    }));
+    return;
+  }
   if (operation === 'skip') {
-    finish(skipPlatformPullRequestFact(taskRef, { cwd, agent, dryRun: values.dryRun === true }));
+    finish(await skipPlatformPullRequestFact(taskRef, { cwd, agent, dryRun: values.dryRun === true }));
     return;
   }
   const primaryResult = values.result === undefined ? undefined : values.result;
@@ -101,28 +125,29 @@ function platformPr(args: string[] = []): void {
     return;
   }
   if (operation === 'resolve-external') {
-    const pr = values.pr === undefined ? undefined : Number(values.pr);
-    if (pr !== undefined && (!Number.isInteger(pr) || pr <= 0)) { fail('resolve-external requires a positive --pr'); return; }
-    finish(resolveExternalPullRequest(taskRef, { cwd, agent: values.agent, pr, dryRun: values.dryRun === true }));
+    const pr = values.pr === undefined ? undefined : values.pr;
+    if (pr !== undefined && (typeof pr !== 'string' || !pr)) { fail('resolve-external requires --pr <token>'); return; }
+    finish(await resolveExternalPullRequest(taskRef, { cwd, agent: values.agent, pr, dryRun: values.dryRun === true }));
     return;
   }
   if (operation === 'bind') {
-    const pr = Number(values.pr);
-    if (!Number.isInteger(pr) || pr <= 0) { fail('bind requires a positive --pr'); return; }
-    finish(bindPlatformPullRequest(taskRef, { cwd, agent: values.agent, pr, dryRun: values.dryRun === true }));
+    const pr = values.pr;
+    if (typeof pr !== 'string' || !pr) { fail('bind requires --pr <token>'); return; }
+    finish(await bindPlatformPullRequest(taskRef, { cwd, agent: values.agent, pr, dryRun: values.dryRun === true }));
     return;
   }
   if (operation === 'sync') {
     if (values.metadata !== true && values.closingIssue !== true) { fail('sync requires --metadata or --closing-issue'); return; }
     if (!primaryResult) { fail('sync requires --result pr_created, pr_reused, or no_op'); return; }
-    finish(syncPlatformPullRequest(taskRef, { cwd, agent: values.agent, metadata: values.metadata === true, closingIssue: values.closingIssue === true, primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true }));
+    finish(await syncPlatformPullRequest(taskRef, { cwd, agent: values.agent, metadata: values.metadata === true, closingIssue: values.closingIssue === true, primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true }));
     return;
   }
   if (operation === 'summary-sync') {
     if (typeof values.bodyFile !== 'string') { fail('summary-sync requires --body-file'); return; }
+    if (typeof values.changeReportFile !== 'string') { fail('summary-sync requires --change-report-file'); return; }
     if (!primaryResult) { fail('summary-sync requires --result pr_created, pr_reused, or no_op'); return; }
     try {
-      finish(syncPullRequestSummary(taskRef, { cwd, agent: values.agent, body: readFile(values.bodyFile, cwd), primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true }));
+      finish(await syncPullRequestSummary(taskRef, { cwd, agent: values.agent, body: readFile(values.bodyFile, cwd), changeReportFile: values.changeReportFile, primaryResult: primaryResult as 'pr_created' | 'pr_reused' | 'no_op', dryRun: values.dryRun === true, strict: values.strict === true }));
     } catch (error) {
       fail(`unable to read body file: ${error instanceof Error ? error.message : String(error)}`);
     }
@@ -133,7 +158,7 @@ function platformPr(args: string[] = []): void {
     return;
   }
   try {
-    finish(createPlatformPullRequest(taskRef, {
+    finish(await createPlatformPullRequest(taskRef, {
       cwd, agent: values.agent, base: values.base, head: values.head,
       title: readFile(values.titleFile, cwd), body: readFile(values.bodyFile, cwd),
       draft: values.draft === true, dryRun: values.dryRun === true

package/lib/internal/platform-release-notes.ts

@@ -36,14 +36,14 @@ function finish(result: { status: string; [key: string]: unknown }): void {
   process.exitCode = result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0;
 }
 
-function platformReleaseNotes(args: string[] = []): void {
+async function platformReleaseNotes(args: string[] = []): Promise<void> {
   const [action, ...rest] = args;
   if (action === 'context') {
     const parsed = parseOptions(rest, ['--cwd', '--history-limit', '--from-tag', '--to-tag', '--branch']);
     if (!parsed) return finish(invalidInput('invalid context options'));
     const cwd = path.resolve(parsed.values.get('--cwd') || process.cwd());
     const historyRaw = parsed.values.get('--history-limit') ?? null;
-    finish(releaseNoteContext({
+    finish(await releaseNoteContext({
       fromTag: parsed.values.get('--from-tag') || '',
       toTag: parsed.values.get('--to-tag') || '',
       branch: parsed.values.get('--branch') || '',
@@ -80,7 +80,7 @@ function platformReleaseNotes(args: string[] = []): void {
       fs.writeFileSync(resolvedNotesPath, fs.readFileSync(0));
     }
     try {
-      finish(publishReleaseNotes({
+      finish(await publishReleaseNotes({
         tag: parsed.values.get('--tag') || '',
         title: parsed.values.get('--title') || parsed.values.get('--tag') || '',
         notesFile: resolvedNotesPath,

package/lib/internal/pr-review-grade.ts

@@ -13,7 +13,7 @@ import { inspectPlatformPullRequestByNumber } from '../platform/pull-requests.ts
 import { verifyInProcess } from '../task/verification-engine.ts';
 
 const USAGE = `Usage: agent-infra-internal pr-review-grade decide --input-file <path|-> [--cwd <path>]
-       agent-infra-internal pr-review-grade resolve-host --pr <N> [--cwd <path>]
+       agent-infra-internal pr-review-grade resolve-host --pr <token> [--cwd <path>]
        agent-infra-internal pr-review-grade verify-artifact --artifact-file <path> [--cwd <path>]
 `;
 
@@ -49,7 +49,7 @@ function readInput(value: string, cwd: string): string {
   return value === '-' ? fs.readFileSync(0, 'utf8') : fs.readFileSync(path.resolve(cwd, value), 'utf8');
 }
 
-function prReviewGrade(args: string[] = []): void {
+async function prReviewGrade(args: string[] = []): Promise<void> {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const operation = args[0];
   if (!operation || !['decide', 'resolve-host', 'verify-artifact'].includes(operation)) { fail('a valid operation is required'); return; }
@@ -85,9 +85,9 @@ function prReviewGrade(args: string[] = []): void {
   }
 
   if (operation === 'resolve-host') {
-    const pr = Number(values.pr);
-    if (!Number.isInteger(pr) || pr <= 0) { fail('resolve-host requires a positive --pr'); return; }
-    const inspected = inspectPlatformPullRequestByNumber(pr, { cwd });
+    const pr = typeof values.pr === 'string' ? values.pr : '';
+    if (!pr) { fail('resolve-host requires --pr <token>'); return; }
+    const inspected = await inspectPlatformPullRequestByNumber(pr, { cwd });
     if (!inspected.pullRequest) {
       finish({
         status: 'failed', changed: false, host: null, candidates: [], closingIssues: [],
@@ -95,12 +95,14 @@ function prReviewGrade(args: string[] = []): void {
       }, inspected.status === 'blocked' ? 2 : 1);
       return;
     }
+    const prNumber = inspected.pullRequest.number;
+    const prIdentity = inspected.pullRequest.identity || { kind: 'number' as const, value: prNumber };
     const closingIssues = extractClosingIssueNumbers(inspected.pullRequest.body);
-    const candidates = collectHostCandidates({ prNumber: pr, closingIssues, workspaceRoot: cwd });
+    const candidates = collectHostCandidates({ prNumber, prIdentity, closingIssues, workspaceRoot: cwd });
     const host: HostResolution = resolveHostFromCandidates(candidates);
     finish({
       status: 'ok', changed: false,
-      pr: { number: pr, baseSha: inspected.pullRequest.base.sha, headSha: inspected.pullRequest.head.sha, state: inspected.pullRequest.state },
+      pr: { number: prNumber, identity: prIdentity, baseSha: inspected.pullRequest.base.sha, headSha: inspected.pullRequest.head.sha, state: inspected.pullRequest.state },
       closingIssues, candidates, host,
       taskIssueMatches: deriveTaskIssueMatches(host, closingIssues), error: null
     });
@@ -111,7 +113,7 @@ function prReviewGrade(args: string[] = []): void {
   const artifactPath = path.resolve(cwd, values.artifactFile);
   let result: Record<string, unknown>;
   try {
-    result = verifyInProcess({
+    result = await verifyInProcess({
       mode: 'checks',
       skillName: 'review-pr',
       taskDir: path.dirname(artifactPath),

package/lib/internal/release-workflow.ts

@@ -251,7 +251,7 @@ async function inspectFacts(cwd: string, version: string): Promise<ReleaseFacts>
   const local = inspectLocalReleaseFacts(cwd, version);
   const remoteBranch = branch ? git(cwd, ['ls-remote', '--heads', 'origin', branch]) : null;
   const remoteTag = git(cwd, ['ls-remote', '--tags', 'origin', `refs/tags/${tag}`]);
-  const platform = inspectPlatformRelease(tag, { cwd });
+  const platform = await inspectPlatformRelease(tag, { cwd });
   const npm = await inspectNpmChannel(pkg.name, version);
   const formulaUrl = `https://raw.githubusercontent.com/${config.org}/homebrew-tap/main/Formula/${config.project}.rb`;
   const homebrew = await inspectHomebrewChannel(formulaUrl, version);
@@ -262,7 +262,7 @@ async function inspectFacts(cwd: string, version: string): Promise<ReleaseFacts>
     localTagAncestor: local.localTagAncestor,
     localTagConflict: local.localTagConflict,
     remoteBranch: Boolean(remoteBranch && remoteBranch.split(/\s+/)[0] === head), remoteTag: Boolean(remoteTag),
-    githubRelease: platform.platform.type !== 'github'
+    githubRelease: platform.error?.code === 'PLATFORM_CAPABILITY_UNSUPPORTED'
       ? true
       : platform.status === 'blocked' ? null : Boolean(platform.release?.published),
     npm: npm.published, homebrew: homebrew.published, smoke,
@@ -324,7 +324,7 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
   }
   if (action === 'prepare') {
     if (before.phase !== 'unprepared') {
-      const milestones = reconcileReleaseMilestones(version, { cwd });
+      const milestones = await reconcileReleaseMilestones(version, { cwd });
       process.stdout.write(`${JSON.stringify({ ...milestones, snapshot: before })}\n`);
       process.exitCode = milestones.status === 'failed' ? 1 : milestones.status === 'blocked' ? 2 : 0;
       return;
@@ -344,7 +344,7 @@ async function releaseWorkflow(args: string[] = []): Promise<void> {
     const committed = commitExplicitPaths({ cwd, paths: changedPaths(cwd), message: `chore: release v${version}` });
     if (committed.status === 'failed') { process.stdout.write(`${JSON.stringify(committed)}\n`); process.exitCode = 1; return; }
     const tagged = command(cwd, 'git', ['tag', '-a', `v${version}`, '-m', `Release v${version}`]);
-    const milestones = tagged.status === 0 ? reconcileReleaseMilestones(version, { cwd }) : null;
+    const milestones = tagged.status === 0 ? await reconcileReleaseMilestones(version, { cwd }) : null;
     const snapshot = releaseSnapshot(version, await inspectFacts(cwd, version));
     const failed = tagged.status !== 0 || milestones?.status === 'failed';
     const blocked = milestones?.status === 'blocked';

package/lib/internal/sandbox-control.ts

@@ -1,4 +1,5 @@
 import {
+  recoverSandboxControl,
   requestSandboxControl,
   requestSandboxTaskFinalization,
   requestSandboxTaskControl,
@@ -39,6 +40,11 @@ function finalizationErrorStatus(error: { retryable: boolean; code: string }): F
   return error.retryable ? 'blocked' : 'failed';
 }
 
+function writeClientError(error: SandboxControlClientError): void {
+  process.stderr.write(`${error.detail.message}\n`);
+  if (error.requestId) process.stderr.write(`SANDBOX_CONTROL_REQUEST_ID: ${error.requestId}\n`);
+}
+
 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 };
@@ -60,7 +66,7 @@ function sandboxFinalizationClient(args: string[]): void {
   } catch (error) {
     if (!(error instanceof SandboxControlClientError)) throw error;
     writeFinalizationEnvelope(finalizationErrorStatus(error.detail), error.accepted, error.detail);
-    process.stderr.write(`${error.detail.message}\n`);
+    writeClientError(error);
     process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : error.detail.retryable ? 2 : 1;
     return;
   }
@@ -107,6 +113,24 @@ async function sandboxControl(args: string[]): Promise<void> {
     await runSandboxControlExecutor(request, nonce);
     return;
   }
+  if (operation === 'recover') {
+    if (rest.length !== 1 || !rest[0]) throw new Error('sandbox-control recover requires <request-id>');
+    let response;
+    try {
+      response = recoverSandboxControl(rest[0]);
+    } catch (error) {
+      if (!(error instanceof SandboxControlClientError)) throw error;
+      writeClientError(error);
+      process.exitCode = error.detail.code === 'SANDBOX_CONTROL_RESULT_UNKNOWN' ? 1 : 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;
+  }
   if (operation === 'client') {
     const [family = '', ...commandArgs] = rest;
     if (family === 'task-finalization') {
@@ -126,7 +150,7 @@ async function sandboxControl(args: string[]): Promise<void> {
       }
     } catch (error) {
       if (!(error instanceof SandboxControlClientError)) throw error;
-      process.stderr.write(`${error.detail.message}\n`);
+      writeClientError(error);
       process.exitCode = error.detail.retryable ? 75 : 1;
       return;
     }
@@ -140,7 +164,7 @@ async function sandboxControl(args: string[]): Promise<void> {
     }
     return;
   }
-  throw new Error('Usage: agent-infra-internal sandbox-control serve --manifest <path> | execute --request <path> --nonce <nonce> | client <family> [args...]');
+  throw new Error('Usage: agent-infra-internal sandbox-control serve --manifest <path> | execute --request <path> --nonce <nonce> | client <family> [args...] | recover <request-id>');
 }
 
 export { sandboxControl };

package/lib/internal/task-activity.ts

@@ -43,7 +43,7 @@ function usageFailure(message: string): void {
   process.exitCode = 1;
 }
 
-function taskActivity(args: string[] = []): void {
+async function taskActivity(args: string[] = []): Promise<void> {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   const [taskRef, kind] = args;
   if (!taskRef || taskRef.startsWith('--') || !kind || !OPERATIONS.has(kind)) {
@@ -94,11 +94,11 @@ function taskActivity(args: string[] = []): void {
   let result;
   let humanOverride: unknown = null;
   try {
-    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-activity.${kind}`, () => {
+    result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-activity.${kind}`, async () => {
       let current = applyPrReviewActivityIntent(values as PrReviewActivityIntent, { lockAlreadyHeld: true });
       if (current.status !== 'failed' || !values.overrideTicket) return current;
       if (!values.overrideTarget || !values.overrideScope) { usageFailure('override ticket requires target and scope'); return current; }
-      const consumed = consumeHumanOverride({
+      const consumed = await consumeHumanOverride({
         taskRef, ticketId: String(values.overrideTicket),
         failureId: failureId('activity-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
         target: String(values.overrideTarget), scope: String(values.overrideScope)

package/lib/internal/task-artifact.ts

@@ -1,6 +1,10 @@
 import { resolveArtifactContext } from '../task/artifact-lifecycle.ts';
+import { finalizeLocalArtifact } from '../task/local-artifact-finalization.ts';
+import type { LocalArtifactFamily } from '../task/local-artifact-finalization.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { loadVerificationConfig } from '../task/verification-config.ts';
 
-const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n\nInspect one workflow artifact family and print a read-only JSON context.\n`;
+const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect workflow artifact context or finalize a local analysis/plan/code artifact without changing task state.\n`;
 
 function failUsage(message: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ARTIFACT_PAYLOAD_INVALID', message } })}\n`);
@@ -11,37 +15,76 @@ function failUsage(message: string): void {
 function taskArtifact(args: string[] = []): void {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   if (args.length < 2) { failUsage('task ref and operation are required'); return; }
-  if (args[1] !== 'inspect') { failUsage(`unknown operation '${args[1]}'`); return; }
+  const operation = args[1];
+  if (operation !== 'inspect' && operation !== 'finalize-local') { failUsage(`unknown operation '${operation}'`); return; }
   let family = '';
+  let artifact = '';
   const seen = new Set<string>();
   for (let index = 2; index < args.length; index += 1) {
     const flag = args[index]!;
-    if (flag !== '--family') { failUsage(`unknown option '${flag}'`); return; }
+    if (flag !== '--family' && flag !== '--artifact') { 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);
-    family = value;
+    if (flag === '--family') family = value;
+    else artifact = value;
   }
   if (!family) { failUsage("option '--family' is required"); 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;
+  if (operation === 'inspect') {
+    if (artifact) { failUsage("option '--artifact' is only valid for 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;
+  }
+  const resolved = resolveTaskRef(args[0]!);
+  const repositoryRoot = resolved.ok ? resolved.repoRoot : process.cwd();
+  if (!artifact) { failUsage("option '--artifact' is required"); return; }
+  if (family !== 'analysis' && family !== 'plan' && family !== 'code') {
+    failUsage("finalize-local only supports 'analysis', 'plan', and 'code'");
+    return;
+  }
+  const skillName = family === 'analysis' ? 'analyze-task' : family === 'plan' ? 'plan-task' : 'code-task';
+  let config: { requiredSections?: readonly string[]; requiredPatterns?: readonly string[] } = {};
+  try {
+    const loaded = loadVerificationConfig(repositoryRoot, skillName);
+    const artifactConfig = loaded.checks.artifact;
+    if (artifactConfig && typeof artifactConfig === 'object' && !Array.isArray(artifactConfig)) {
+      const sections = artifactConfig.required_sections;
+      const patterns = artifactConfig.required_patterns;
+      config = {
+        requiredSections: Array.isArray(sections) ? sections.filter((value): value is string => typeof value === 'string') : undefined,
+        requiredPatterns: Array.isArray(patterns) ? patterns.filter((value): value is string => typeof value === 'string') : undefined
+      };
+    }
+  } catch {
+    // Isolated fixture repositories may not contain the project's verification config.
+  }
+  const result = finalizeLocalArtifact({
+    taskRef: args[0]!,
+    family: family as LocalArtifactFamily,
+    artifact,
+    repoRoot: repositoryRoot,
+    ...config
+  });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  if (result.status === 'failed') process.exitCode = 1;
 }
 
 export { taskArtifact };

package/lib/internal/task-create.ts

@@ -18,7 +18,7 @@ function output(result: TaskCreateResult): void {
   process.exitCode = result.status === 'blocked' ? 2 : result.status === 'failed' ? 1 : 0;
 }
 
-function taskCreate(args: string[]): void {
+async function taskCreate(args: string[]): Promise<void> {
   const inputIndex = args.indexOf('--input');
   const input = inputIndex >= 0 ? args[inputIndex + 1] : undefined;
   if (!input || args.length !== 2 || inputIndex !== 0) {
@@ -46,7 +46,7 @@ function taskCreate(args: string[]): void {
       process.exitCode = response.exitCode;
       return;
     }
-    output(createTask(candidate, { repoRoot: process.cwd() }));
+    output(await createTask(candidate, { repoRoot: process.cwd() }));
   } catch (error) {
     if (error instanceof SandboxControlClientError) {
       output(failed(error.detail.code, error.detail.message, error.detail.retryable));

package/lib/internal/task-event.ts

@@ -13,6 +13,9 @@ Events: ${eventCatalog.join(', ')}
 
 const FLAGS: Record<string, keyof TaskEventRequest> = {
   '--agent': 'agent', '--round': 'round', '--question': 'question', '--artifact': 'artifact',
+  '--artifact-sha256': 'artifactSha256', '--semantic-digest': 'semanticDigest',
+  '--initiator': 'initiator', '--request-id': 'requestId', '--reason-code': 'reasonCode',
+  '--source-finding': 'sourceFinding', '--source-artifact': 'sourceArtifact', '--source-sha256': 'sourceSha256',
   '--fix-for': 'fixFor', '--implementation-input': 'implementationInput',
   '--verdict': 'verdict', '--blockers': 'blockers', '--major': 'major',
   '--minor': 'minor', '--manual-validation': 'manualValidation', '--files-modified': 'filesModified',
@@ -27,7 +30,7 @@ function usageFailure(message: string): void {
   process.exitCode = 1;
 }
 
-function taskEvent(args: string[] = []): void {
+async function taskEvent(args: string[] = []): Promise<void> {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
   if (args.length < 2) { usageFailure('task ref and event are required'); return; }
   const request: TaskEventRequest = { taskRef: args[0]!, event: args[1]!, agent: '' };
@@ -66,14 +69,14 @@ function taskEvent(args: string[] = []): void {
   let result;
   let humanOverride: unknown = null;
   try {
-    result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, () => {
+    result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, async () => {
       let current = applyTaskEvent(request, { lockAlreadyHeld: true });
       const values = request as Record<string, unknown>;
       if (current.status !== 'failed' || !values.overrideTicket) return current;
       if (!values.overrideTarget || !values.overrideScope) {
         return { ...current, humanOverride: { status: 'failed', error: { code: 'OVERRIDE_PAYLOAD_INVALID', message: 'override ticket requires target and scope' } } } as typeof current & { humanOverride: unknown };
       }
-      const consumed = consumeHumanOverride({
+      const consumed = await consumeHumanOverride({
         taskRef: request.taskRef,
         ticketId: String(values.overrideTicket),
         failureId: failureId('task-event', current.error?.code ?? 'EVENT_TRANSITION_INVALID'),

package/lib/internal/task-finalization.ts

@@ -14,7 +14,7 @@ function envelope(
   status: 'completed' | 'failed' | 'blocked' | 'unknown',
   changed: boolean,
   accepted: boolean,
-  result: ReturnType<typeof applyTaskFinalization> | null,
+  result: Awaited<ReturnType<typeof applyTaskFinalization>> | null,
   error: FinalizationError | null
 ): string {
   return `${JSON.stringify({ version: 1, status, changed, accepted, result, error })}\n`;
@@ -36,7 +36,7 @@ function parseFailure(error: unknown): string {
   return message.replace(/^TASK_CONTROL_OPERATION_INVALID: /u, '');
 }
 
-function taskFinalization(args: string[] = []): void {
+async function taskFinalization(args: string[] = []): Promise<void> {
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
 
   let operation;
@@ -71,7 +71,7 @@ function taskFinalization(args: string[] = []): void {
     ...operation,
     request: { ...operation.request, taskRef: resolved.taskId }
   };
-  const result = dispatchTaskControlOperation(
+  const result = await dispatchTaskControlOperation(
     createDirectHostExecutionContext({ repoRoot }),
     boundOperation
   );

package/lib/internal/task-invalidation.ts

@@ -0,0 +1,39 @@
+import { reconcileTaskInvalidation } from '../task/invalidation-command.ts';
+import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-invalidation <task-ref> reconcile [--max-targets <n>] [--dry-run]\n';
+
+function taskInvalidation(args: string[] = []): void {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  const taskRef = args[0];
+  if (!taskRef || args[1] !== 'reconcile') {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'INVALIDATION_PAYLOAD_INVALID', message: 'task ref and reconcile are required' } })}\n`);
+    process.stderr.write(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+  let maxTargets: number | undefined;
+  let dryRun = false;
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--dry-run') { if (dryRun) { process.exitCode = 1; return; } dryRun = true; continue; }
+    if (flag !== '--max-targets') { process.exitCode = 1; return; }
+    const value = Number(args[++index]);
+    if (!Number.isInteger(value) || value < 1 || maxTargets !== undefined) { process.exitCode = 1; return; }
+    maxTargets = value;
+  }
+  const resolved = resolveTaskRef(taskRef);
+  if (!resolved.ok) { process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } })}\n`); process.exitCode = 1; return; }
+  try {
+    const result = withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-invalidation.reconcile', () => reconcileTaskInvalidation(taskRef, { ...(maxTargets === undefined ? {} : { maxTargets }), dryRun }));
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed') process.exitCode = 1;
+  } catch (error) {
+    if (!(error instanceof TaskExecutionLockError)) throw error;
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: error.code, message: error.message } })}\n`);
+    process.exitCode = 1;
+  }
+}
+
+export { taskInvalidation };