@fitlab-ai/agent-infra 0.11.3 → 0.11.5

package/README.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <strong>From issue to merged PR in 11 commands.</strong> Define a requirement, let AI handle analysis, planning, coding, and three-stage review — you only step in when it matters.
+  <strong>From issue to merged PR through a risk-selected lifecycle.</strong> Every task starts with analysis, and every implementation receives an independent code review.
 </p>
 
 <p align="center">
@@ -51,14 +51,22 @@ Once initialized, open the project in your AI TUI and install the latest skills:
 
 > AI reads `.agents/.airc.json`, auto-locates the installed template root, and syncs the latest skill manifests, managed files, and registry deterministically via `sync-templates.js`.
 
-**Scenario**: Issue #42 reports *"Login API returns 500 when email contains a plus sign"*. Here is the full fix lifecycle — AI does the heavy lifting, you stay in control:
+**Scenario**: Issue #42 reports *"Login API returns 500 when email contains a plus sign"*. Every task starts with analysis, which records one canonical path from observable facts:
+
+| Path | Stages | Use when |
+|------|--------|----------|
+| Streamlined | `analyze → code → review-code` | Scope and acceptance are clear, with no separate design or document-audit decision |
+| Standard | `analyze → plan → code → review-code` | The implementation needs an explicit cross-module contract, data flow, or test strategy |
+| Full | `analyze → review-analysis → plan → review-plan → code → review-code` | Concrete acceptance disputes, costly interface/schema/migration choices, or real external/security boundaries require independent review |
+
+File count, module count, or a merely possible risk does not select the full path. A later finding can return work to analysis, planning, or code when new evidence justifies it; independent `review-code` remains part of every path.
+
+Suppose the analysis selects the **standard path** because the application-layer boundary needs an explicit plan:
 
 ```bash
 /import-issue 42           # AI reads the issue, creates a task, extracts requirements
-/analyze-task --task <task-id>    # AI scans the codebase, finds the root cause, writes analysis.md
-/review-analysis --task <task-id> # An isolated reviewer checks the analysis
+/analyze-task --task <task-id>    # AI scans the codebase, records the selected path, writes analysis.md
 /plan-task --task <task-id>       # AI proposes a fix plan
-/review-plan --task <task-id>     # A fresh isolated reviewer checks the plan
 ```
 
 > **You review the plan and reply in natural language:**
@@ -79,7 +87,7 @@ Just fix it at the application layer in LoginService.
 /complete-task --task <task-id>   # task archived
 ```
 
-**11 commands. 1 natural-language correction. From issue to merged PR.** That is the entire SOP — programming can have a standard operating procedure too.
+**One analysis-selected path, one natural-language correction, and an independent code review.** The lifecycle keeps the evidence and review depth proportional to the task.
 
 Every command above works the same way in Claude Code, Codex, Antigravity CLI, and OpenCode. Switch tools mid-task — the workflow state follows. For what each skill does under the hood, see [Built-in AI Skills](./docs/en/skills.md).
 
@@ -193,8 +201,9 @@ The most-used lifecycle commands, in delivery order. The command prefix varies b
 |---------|---------|
 | `create-task` / `import-issue` | Start a task from a description or a GitHub Issue |
 | `run-task` | Resume the lifecycle with fresh isolated executors/reviewers when the selected client exposes verified actual model/effort evidence; Codex now has an experimental Hooks + App Server evidence channel, but orchestration remains disabled until that channel is connected to delegation receipts |
-| `analyze-task` → `review-analysis` | Capture scope and risks, then review the analysis |
-| `plan-task` → `review-plan` | Design the approach, then review the plan |
+| `analyze-task` | Capture scope and risks, then select the streamlined, standard, or full path |
+| `review-analysis` | Review the analysis when the selected full path requires an independent requirement checkpoint |
+| `plan-task` / `review-plan` | Design the approach on standard/full paths; independently review it only on the full path |
 | `code-task` → `review-code` | Implement and test; `code-task` creates a local checkpoint, then a structured review checks that checkpoint |
 | `create-pr` → `complete-task` | Publish the approved checkpoint to the task-bound target branch, then archive after merge and final gates |
 

package/README.zh-CN.md

@@ -9,7 +9,7 @@
 </p>
 
 <p align="center">
-  <strong>从 Issue 到合并 PR，只需 11 条命令。</strong> 定义需求，让 AI 完成分析、方案设计、编码与三阶段审查 —— 你只需在关键节点介入。
+  <strong>从 Issue 到合并 PR，由风险选择相称的生命周期。</strong> 每个任务都先分析，每份实现都接受独立代码审查。
 </p>
 
 <p align="center">
@@ -50,14 +50,22 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 
 > AI 读取 `.agents/.airc.json`，自动定位已安装的模板根目录，并通过 `sync-templates.js` 确定性地同步最新的 skill 清单、managed 文件和注册表。
 
-**场景**：Issue #42 报告 *"登录接口在邮箱包含加号时返回 500"*。以下是完整的修复流程 —— AI 执行主要工作，你掌控方向：
+**场景**：Issue #42 报告 *"登录接口在邮箱包含加号时返回 500"*。每个任务都从分析开始，并由分析根据可观察事实记录一条规范路径：
+
+| 路径 | 阶段 | 适用条件 |
+|------|------|----------|
+| 精简路径 | `analyze → code → review-code` | 范围和验收明确，不需要独立设计或文档审计决策 |
+| 标准路径 | `analyze → plan → code → review-code` | 实现需要明确跨模块契约、数据流或测试策略 |
+| 完整路径 | `analyze → review-analysis → plan → review-plan → code → review-code` | 存在具体的验收争议、高代价接口/schema/迁移选择，或真实外部/安全边界，需要独立审查 |
+
+文件数量、模块数量或可能存在的风险不能单独触发完整路径。后续 finding 只有在新证据成立时才会把工作返回分析、方案或实现阶段；每条路径都保留独立 `review-code`。
+
+假设分析认为应用层边界需要明确方案，因此选择**标准路径**：
 
 ```bash
 /import-issue 42           # AI 读取 Issue，创建任务，提取需求
-/analyze-task --task <task-id>    # AI 扫描代码库，定位根因，输出 analysis.md
-/review-analysis --task <task-id> # 隔离 reviewer 审查分析产物
+/analyze-task --task <task-id>    # AI 扫描代码库、记录所选路径，输出 analysis.md
 /plan-task --task <task-id>       # AI 提出修复方案
-/review-plan --task <task-id>     # fresh 隔离 reviewer 审查方案
 ```
 
 > **你审查方案后用自然语言回复：**
@@ -78,7 +86,7 @@ agent-infra 的目标就是把这层共享基础设施标准化。它为所有
 /complete-task --task <task-id>   # 任务归档
 ```
 
-**11 条命令，1 次自然语言纠正，从 Issue 到合并 PR。** 这就是完整的 SOP —— 编程也可以有标准作业流程。
+**一条由分析选择的路径、一次自然语言纠正和一次独立代码审查。** 生命周期会让证据与审查深度和任务风险相称。
 
 以上每条命令在 Claude Code、Codex、Antigravity CLI、OpenCode 中完全通用。任务进行到一半切换工具，工作流状态照常延续。每个 skill 背后做了什么，见 [内置 AI Skills](./docs/zh-CN/skills.md)。
 
@@ -192,8 +200,9 @@ ai agent-client configure
 |------|------|
 | `create-task` / `import-issue` | 从描述或 GitHub Issue 创建任务 |
 | `run-task` | 当所选客户端能提供已验证的 actual model/effort 证据时，用 fresh 隔离 executor/reviewer 续跑生命周期；Codex 现已具备实验性的 Hooks + App Server 证据通道，但在该通道接入 delegation receipt 前仍不会启用 orchestration |
-| `analyze-task` → `review-analysis` | 明确范围与风险，再审查分析 |
-| `plan-task` → `review-plan` | 设计实现路径，再审查方案 |
+| `analyze-task` | 明确范围与风险，再选择精简、标准或完整路径 |
+| `review-analysis` | 仅在完整路径需要独立需求检查点时审查分析 |
+| `plan-task` / `review-plan` | 标准和完整路径需要设计方案；只有完整路径独立审查方案 |
 | `code-task` → `review-code` | 实现并测试；`code-task` 创建本地 checkpoint，再由结构化审查检视该 checkpoint |
 | `create-pr` → `complete-task` | 将已通过审查的 checkpoint 发布到任务绑定目标分支，并在合并和最终门禁通过后归档 |
 

package/dist/bin/internal-cli.js

@@ -50,7 +50,7 @@ function taskControlTransportFailure(message, code = 'TASK_CONTROL_TRANSPORT_INV
 let controlRouted = false;
 if (!taskViewGuardFailed && !markerlessHelp && (taskControlCommand || taskWorkflowCommand || manualValidationWorkflowCommand)) {
     const transport = resolveSandboxControlTransport(process.env, {
-        localWorkflow: command === 'task-orchestration' || taskWorkflowCommand || manualValidationWorkflowCommand
+        localWorkflow: command === 'task-orchestration' || command === 'task-finalization' || taskWorkflowCommand || manualValidationWorkflowCommand
     });
     switch (transport.kind) {
         case 'fail-closed': {
@@ -240,11 +240,6 @@ if (!controlRouted && !taskViewGuardFailed && internalRouteRegistered)
             await taskFinalization(process.argv.slice(3));
             break;
         }
-        case 'task-override': {
-            const { taskOverride } = await import('../lib/internal/task-override.js');
-            await taskOverride(process.argv.slice(3));
-            break;
-        }
         case 'task-short-id': {
             const { taskShortId } = await import('../lib/internal/task-short-id.js');
             taskShortId(process.argv.slice(3));

package/dist/lib/decide.js

@@ -2,15 +2,11 @@ import { VERSION } from './version.js';
 import { parseTaskScope } from './task/command-options.js';
 import { applyHumanDecision } from './task/decision-intents.js';
 import { canonicalTimestamp } from './task/write.js';
-import { consumeHumanOverride, failureId } from './task/human-override.js';
 import { resolveTaskContext } from './task/resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task/task-execution-lock.js';
 function parseDecisionParts(parts) {
     const decision = [];
     let needsImplementation;
-    let overrideTicket;
-    let overrideTarget;
-    let overrideScope;
     for (let index = 0; index < parts.length; index += 1) {
         const part = parts[index];
         if (part === '--needs-implementation') {
@@ -22,16 +18,8 @@ function parseDecisionParts(parts) {
             }
             needsImplementation = value === 'true';
         }
-        else if (part === '--override-ticket' || part === '--override-target' || part === '--override-scope') {
-            const value = parts[++index];
-            if (!value)
-                throw new Error(`${part} requires a value`);
-            if (part === '--override-ticket')
-                overrideTicket = value;
-            else if (part === '--override-target')
-                overrideTarget = value;
-            else
-                overrideScope = value;
+        else if (part?.startsWith('--')) {
+            throw new Error(`unknown option '${part}'`);
         }
         else {
             decision.push(parts[index]);
@@ -39,7 +27,7 @@ function parseDecisionParts(parts) {
     }
     if (decision.length === 0)
         throw new Error('decision content is required');
-    return { decision: decision.join(' '), needsImplementation, overrideTicket, overrideTarget, overrideScope };
+    return { decision: decision.join(' '), needsImplementation };
 }
 export async function decide(args, options = {}) {
     let scope;
@@ -94,32 +82,7 @@ export async function decide(args, options = {}) {
             metadataProvider: () => ({ timestamp: now, agentInfraVersion: options.version ?? VERSION })
         };
         let result;
-        const execute = async () => {
-            let current = applyHumanDecision(request, writeOptions);
-            if (current.status !== 'failed' || !parsedDecision.overrideTicket)
-                return current;
-            if (!parsedDecision.overrideTarget || !parsedDecision.overrideScope)
-                throw new Error('override ticket requires --override-target and --override-scope');
-            const consumed = await consumeHumanOverride({
-                taskRef: resolved.taskId,
-                ticketId: parsedDecision.overrideTicket,
-                failureId: failureId('decision-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
-                target: parsedDecision.overrideTarget,
-                scope: parsedDecision.overrideScope
-            }, {
-                ...writeOptions,
-                effectExecutor: (capability) => {
-                    const retried = applyHumanDecision(request, { ...writeOptions, manualOverride: capability });
-                    current = retried;
-                    return retried.status === 'failed' || retried.status === 'planned'
-                        ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no decision effect was committed' : `${retried.error?.code ?? 'DECISION_FAILED'}: ${retried.error?.message ?? 'manual decision effect failed'}` }
-                        : null;
-                }
-            });
-            if (consumed.status === 'failed')
-                throw new Error(consumed.error.message);
-            return current;
-        };
+        const execute = async () => applyHumanDecision(request, writeOptions);
         result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-decision', execute);
         if (result.error)
             throw new Error(result.error.message);

package/dist/lib/git/branch-worktree.js

@@ -0,0 +1,45 @@
+import { execFileSync } from 'node:child_process';
+function gitText(repositoryRoot, args) {
+    try {
+        return execFileSync('git', ['-C', repositoryRoot, ...args], {
+            encoding: 'utf8',
+            stdio: ['ignore', 'pipe', 'pipe']
+        }).trim();
+    }
+    catch {
+        return null;
+    }
+}
+function verifiedWorktreeRoot(candidate, expectedBranch, expectedCommonDirectory) {
+    const commonDirectory = gitText(candidate, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    if (commonDirectory !== expectedCommonDirectory)
+        return null;
+    const root = gitText(candidate, ['rev-parse', '--show-toplevel']);
+    if (!root)
+        return null;
+    const branch = gitText(root, ['symbolic-ref', '--short', 'HEAD']);
+    return branch === expectedBranch ? root : null;
+}
+export function resolveBranchWorktree(repositoryRoot, expectedBranch) {
+    const commonDirectory = gitText(repositoryRoot, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    if (!commonDirectory)
+        return null;
+    const currentRoot = verifiedWorktreeRoot(repositoryRoot, expectedBranch, commonDirectory);
+    if (currentRoot)
+        return currentRoot;
+    const records = gitText(repositoryRoot, ['worktree', 'list', '--porcelain']);
+    if (!records)
+        return null;
+    const expectedRef = `refs/heads/${expectedBranch}`;
+    for (const record of records.split(/\r?\n\r?\n/)) {
+        const candidate = /^worktree (.+)$/m.exec(record)?.[1];
+        const branch = /^branch (.+)$/m.exec(record)?.[1];
+        if (candidate && branch === expectedRef) {
+            const verifiedRoot = verifiedWorktreeRoot(candidate, expectedBranch, commonDirectory);
+            if (verifiedRoot)
+                return verifiedRoot;
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=branch-worktree.js.map

package/dist/lib/internal/cli-route-inventory.js

@@ -50,7 +50,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
     'pr-review-grade': ['decide', 'resolve-host', 'verify-artifact'],
     'platform-checks': ['inspect', 'watch', 'resolve-run', 'logs'],
     'task-context': ['resolve'],
-    'task-ledger': ['decision-next-id', 'stage-status', 'finding-upsert', 'finding-respond', 'finding-review', 'decision-upsert', 'rework-intent-upsert'],
+    'task-ledger': ['decision-next-id', 'stage-status', 'finding-upsert', 'finding-respond', 'finding-review', 'decision-upsert', 'rework-intent-upsert', 'rework-intent-rebuild'],
     'task-warning': ['list', 'add', 'set-status'],
     'task-activity': ['pr-review-inspect', 'pr-review-start', 'pr-review-complete', 'pr-review-terminate'],
     'task-artifact': ['inspect', 'init', 'preflight', 'finalize-local'],
@@ -58,7 +58,6 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
     'task-review': ['preflight', 'finalize-summary'],
     'task-event': ['event'],
     'task-invalidation': ['reconcile'],
-    'task-override': ['diagnose', 'issue', 'consume'],
     'task-lifecycle': ['intent'],
     'task-finalization': ['complete'],
     'task-short-id': ['list', 'list-verify', 'alloc', 'release', 'resolve'],
@@ -105,8 +104,6 @@ export function internalRouteSelector(command, args) {
         return args[1] ?? '';
     if (command === 'task-invalidation')
         return args[1] ?? '';
-    if (command === 'task-override')
-        return args[1] ?? '';
     if (command === 'task-artifact')
         return args[1] ?? '';
     if (command === 'platform-pr-review' && first(args) === 'publish') {

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

@@ -1,5 +1,4 @@
 import { applyPrReviewActivityIntent, inspectPrReviewActivity } from '../task/activity-intent.js';
-import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
@@ -18,15 +17,14 @@ const FLAGS = {
     '--major': 'major',
     '--minor': 'minor',
     '--outcome': 'outcome',
-    '--reason': 'reason',
-    '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
+    '--reason': 'reason'
 };
 const COMMON = ['agent', 'artifact', 'head'];
 const ALLOWED = {
     'pr-review-inspect': new Set(['kind', 'taskRef']),
-    'pr-review-start': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope']),
-    'pr-review-complete': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'verdict', 'blockers', 'major', 'minor', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope']),
-    'pr-review-terminate': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'outcome', 'reason', 'dryRun', 'overrideTicket', 'overrideTarget', 'overrideScope'])
+    'pr-review-start': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'dryRun']),
+    'pr-review-complete': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'verdict', 'blockers', 'major', 'minor', 'dryRun']),
+    'pr-review-terminate': new Set(['kind', 'taskRef', 'agent', 'artifact', 'head', 'outcome', 'reason', 'dryRun'])
 };
 function usageFailure(message) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'ACTIVITY_PAYLOAD_INVALID', message } })}\n`);
@@ -109,43 +107,14 @@ async function taskActivity(args = []) {
             return;
         }
     }
-    const dryRunConflict = overrideDryRunConflict(values);
-    if (dryRunConflict) {
-        usageFailure(dryRunConflict.message);
-        return;
-    }
     const resolved = resolveTaskRef(taskRef);
     if (!resolved.ok) {
         usageFailure(resolved.message);
         return;
     }
     let result;
-    let humanOverride = null;
     try {
-        result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-activity.${kind}`, async () => {
-            let current = applyPrReviewActivityIntent(values, { 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 = 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)
-            }, {
-                effectExecutor: (capability) => {
-                    const retried = applyPrReviewActivityIntent(values, { lockAlreadyHeld: true, manualOverride: capability });
-                    current = retried;
-                    return retried.status === 'failed' || retried.status === 'planned'
-                        ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no activity effect was committed' : `${retried.error?.code ?? 'ACTIVITY_FAILED'}: ${retried.error?.message ?? 'manual activity effect failed'}` }
-                        : null;
-                }
-            });
-            humanOverride = consumed;
-            return current;
-        });
+        result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-activity.${kind}`, async () => applyPrReviewActivityIntent(values, { lockAlreadyHeld: true }));
     }
     catch (error) {
         if (!(error instanceof TaskExecutionLockError))
@@ -154,10 +123,8 @@ async function taskActivity(args = []) {
         process.exitCode = 1;
         return;
     }
-    process.stdout.write(`${JSON.stringify(humanOverride ? { ...result, humanOverride } : result)}\n`);
-    const overrideFailed = Boolean(humanOverride && typeof humanOverride === 'object' &&
-        humanOverride.status === 'failed');
-    if (result.status === 'failed' || overrideFailed)
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed')
         process.exitCode = 1;
 }
 export { taskActivity };

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

@@ -1,6 +1,6 @@
 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> preflight|finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, preflight, or finalize a workflow artifact without changing task state.\n`;
+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`;
 function taskArtifact(args = []) {
     if (!ensureInternalHandlerRoute('task-artifact', args))
         return;

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

@@ -1,6 +1,5 @@
 import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.js';
 import { applyTaskEvent, eventCatalog } from '../task/events.js';
-import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
@@ -18,8 +17,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'
+    '--transaction-id': 'transactionId', '--receipt-digest': 'receiptDigest', '--pr-head-sha': 'prHeadSha'
 };
 const NUMERIC = new Set(['round', 'question', 'blockers', 'major', 'minor', 'manualValidation', 'filesModified', 'testsPassed']);
 function usageFailure(message) {
@@ -68,9 +66,6 @@ export function parseTaskEventRequest(args) {
     if (!agent)
         throw new Error(`invalid --agent '${request.agent}': ${AGENT_USAGE_HINT}`);
     request.agent = agent;
-    const dryRunConflict = overrideDryRunConflict(request);
-    if (dryRunConflict)
-        throw new Error(dryRunConflict.message);
     return request;
 }
 async function taskEvent(args = []) {
@@ -99,34 +94,8 @@ async function taskEvent(args = []) {
         return;
     }
     let result;
-    let humanOverride = null;
     try {
-        result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, async () => {
-            let current = applyTaskEvent(request, { lockAlreadyHeld: true });
-            const values = request;
-            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' } } };
-            }
-            const consumed = await consumeHumanOverride({
-                taskRef: request.taskRef,
-                ticketId: String(values.overrideTicket),
-                failureId: failureId('task-event', current.error?.code ?? 'EVENT_TRANSITION_INVALID'),
-                target: String(values.overrideTarget),
-                scope: String(values.overrideScope)
-            }, {
-                effectExecutor: (capability) => {
-                    const retried = applyTaskEvent(request, { lockAlreadyHeld: true, manualOverride: capability });
-                    current = retried;
-                    return retried.status === 'failed' || retried.status === 'planned'
-                        ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no task event was committed' : `${retried.error?.code ?? 'EVENT_FAILED'}: ${retried.error?.message ?? 'manual task event effect failed'}` }
-                        : null;
-                }
-            });
-            humanOverride = consumed;
-            return current;
-        });
+        result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-event.${request.event}`, async () => applyTaskEvent(request, { lockAlreadyHeld: true }));
     }
     catch (error) {
         if (!(error instanceof TaskExecutionLockError))
@@ -135,10 +104,8 @@ async function taskEvent(args = []) {
         process.exitCode = 1;
         return;
     }
-    process.stdout.write(`${JSON.stringify(humanOverride ? { ...result, humanOverride } : result)}\n`);
-    const overrideFailed = Boolean(humanOverride && typeof humanOverride === 'object' &&
-        humanOverride.status === 'failed');
-    if (result.status === 'failed' || overrideFailed)
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed')
         process.exitCode = 1;
 }
 export { taskEvent };

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

@@ -1,6 +1,10 @@
 import { createDirectHostExecutionContext, dispatchTaskControlOperation, parseTaskControlOperation } from '../task/control-authority.js';
-import { applyTaskFinalization } from '../task/finalization.js';
+import { applyTaskFinalization, bindTaskFinalizationReceipt, prepareTaskFinalization } from '../task/finalization.js';
+import { publishTaskFinalizationHandoff } from '../task/finalization-handoff.js';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.js';
+import { verifyTaskEvent } from '../task/verification.js';
+import { resolveSandboxControlTransport } from './task-operation-registry.js';
+import { requestSandboxTaskFinalization, SandboxControlClientError } from '../sandbox/control/client.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
 const USAGE = 'Usage: agent-infra-internal task-finalization <N | TASK-id> complete --agent <agent>\n';
 function envelope(status, changed, accepted, result, error) {
@@ -59,7 +63,50 @@ async function taskFinalization(args = []) {
         ...operation,
         request: { ...operation.request, taskRef: resolved.taskId }
     };
+    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);
+                }
+            });
+            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
+                : { 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;
+            return;
+        }
+    }
     const result = await dispatchTaskControlOperation(createDirectHostExecutionContext({ repoRoot }), boundOperation);
+    if (result.status === 'prepared') {
+        const detail = {
+            code: 'TASK_FINALIZATION_DIRECT_COMMIT_REQUIRED',
+            message: 'direct finalization prepared external work without committing the lifecycle transition',
+            retryable: false
+        };
+        process.stdout.write(envelope('failed', result.changed, true, result, detail));
+        process.exitCode = 1;
+        return;
+    }
     process.stdout.write(envelope(result.status, result.changed, true, result, result.error));
     process.exitCode = exitCode(result.status);
 }

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

@@ -1,21 +1,20 @@
 import fs from 'node:fs';
 import { applyLedgerIntent } from '../task/ledger-intents.js';
-import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.js';
 import { LEDGER_SECTION_MISSING_CODE, LEDGER_SECTION_MISSING_MESSAGE, isReviewStage, parseLedgerDocument, summarizeLedgerStage, validateLedgerRows } from '../task/ledger.js';
 import { resolveTaskRef } from '../task/resolve-ref.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.js';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.js';
-const USAGE = `Usage: agent-infra-internal task-ledger <task-ref> <intent> [intent flags] [--dry-run]\n\nIntents: finding-upsert, finding-respond, finding-review, decision-next-id, decision-upsert, rework-intent-upsert, stage-status\n`;
+const USAGE = `Usage: agent-infra-internal task-ledger <task-ref> <intent> [intent flags] [--dry-run]\n\nIntents: finding-upsert, finding-respond, finding-review, decision-next-id, decision-upsert, rework-intent-upsert, rework-intent-rebuild, stage-status\n`;
 const FLAGS = {
     '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal',
     '--severity': 'severity', '--evidence': 'evidence', '--id': 'id', '--round': 'round',
     '--status': 'status', '--artifact': 'artifact', '--needs-implementation': 'needsImplementation',
     '--intent-id': 'intentId', '--finding-id': 'findingId', '--source-artifact': 'sourceArtifact',
-    '--source-sha256': 'sourceSha256', '--target': 'target',
-    '--override-ticket': 'overrideTicket', '--override-target': 'overrideTarget', '--override-scope': 'overrideScope'
+    '--source-sha256': 'sourceSha256', '--classification': 'classification'
 };
 const NUMERIC = new Set(['ordinal', 'round']);
 const BOOLEAN = new Set(['needsImplementation']);
+const REWORK_CLASSIFICATIONS = new Set(['scope-or-requirement', 'design', 'implementation', 'human-decision', 'insufficient-evidence']);
 function usageFailure(message) {
     process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LEDGER_PAYLOAD_INVALID', message } })}\n`);
     process.stderr.write(USAGE);
@@ -40,6 +39,7 @@ async function taskLedger(args = []) {
         internalHandlerRoute('task-ledger', 'decision-next-id', kind),
         internalHandlerRoute('task-ledger', 'decision-upsert', kind),
         internalHandlerRoute('task-ledger', 'rework-intent-upsert', kind),
+        internalHandlerRoute('task-ledger', 'rework-intent-rebuild', kind),
         internalHandlerRoute('task-ledger', 'stage-status', kind)
     ].some(Boolean)) {
         usageFailure(`unknown ledger intent '${kind}'`);
@@ -85,17 +85,16 @@ async function taskLedger(args = []) {
         'finding-review': ['id', 'status', 'evidence'],
         'decision-next-id': [],
         'decision-upsert': ['id', 'stage', 'artifact'],
-        'rework-intent-upsert': ['intentId', 'findingId', 'sourceArtifact', 'sourceSha256', 'target'],
+        'rework-intent-upsert': ['intentId', 'findingId', 'sourceArtifact', 'sourceSha256', 'classification'],
+        'rework-intent-rebuild': [],
         'stage-status': ['stage']
     };
     const optional = {
         'finding-review': ['needsImplementation'],
-        'decision-upsert': ['needsImplementation']
+        'decision-upsert': ['needsImplementation'],
+        'rework-intent-rebuild': ['findingId', 'sourceArtifact', 'sourceSha256', 'classification']
     };
-    const overrideFields = kind === 'stage-status' || kind === 'decision-next-id' || kind === 'rework-intent-upsert'
-        ? []
-        : ['overrideTicket', 'overrideTarget', 'overrideScope'];
-    const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind], ...(optional[kind] ?? []), ...overrideFields]);
+    const allowed = new Set(['kind', 'taskRef', 'dryRun', ...required[kind], ...(optional[kind] ?? [])]);
     const unexpected = Object.keys(values).find((key) => !allowed.has(key));
     const missing = required[kind].find((key) => values[key] === undefined);
     if (unexpected) {
@@ -106,9 +105,8 @@ async function taskLedger(args = []) {
         usageFailure(`${kind} requires '${missing}'`);
         return;
     }
-    const dryRunConflict = overrideDryRunConflict(values);
-    if (dryRunConflict) {
-        usageFailure(dryRunConflict.message);
+    if (values.classification !== undefined && !REWORK_CLASSIFICATIONS.has(String(values.classification))) {
+        usageFailure(`invalid rework classification '${values.classification}'`);
         return;
     }
     if (kind === 'stage-status') {
@@ -151,34 +149,8 @@ async function taskLedger(args = []) {
         return;
     }
     let result;
-    let humanOverride = null;
     try {
-        result = await withTaskExecutionLock(lockResolved.repoRoot, lockResolved.taskId, `task-ledger.${kind}`, async () => {
-            let current = applyLedgerIntent(values);
-            if (current.status !== 'failed' || !values.overrideTicket)
-                return current;
-            if (!values.overrideTarget || !values.overrideScope) {
-                usageFailure('override ticket requires target and scope');
-                return current;
-            }
-            const consumed = await consumeHumanOverride({
-                taskRef,
-                ticketId: String(values.overrideTicket),
-                failureId: failureId('ledger-intent', current.error?.code ?? 'TASK_STATE_MISMATCH'),
-                target: String(values.overrideTarget),
-                scope: String(values.overrideScope)
-            }, {
-                effectExecutor: (capability) => {
-                    const retried = applyLedgerIntent(values, { manualOverride: capability });
-                    current = retried;
-                    return retried.status === 'failed'
-                        ? { code: 'OVERRIDE_EFFECT_FAILED', message: `${retried.error?.code ?? 'LEDGER_FAILED'}: ${retried.error?.message ?? 'manual ledger effect failed'}` }
-                        : null;
-                }
-            });
-            humanOverride = consumed;
-            return current;
-        });
+        result = await withTaskExecutionLock(lockResolved.repoRoot, lockResolved.taskId, `task-ledger.${kind}`, async () => applyLedgerIntent(values));
     }
     catch (error) {
         if (!(error instanceof TaskExecutionLockError))
@@ -187,10 +159,8 @@ async function taskLedger(args = []) {
         process.exitCode = 1;
         return;
     }
-    process.stdout.write(`${JSON.stringify(humanOverride ? { ...result, humanOverride } : result)}\n`);
-    const overrideFailed = Boolean(humanOverride && typeof humanOverride === 'object' &&
-        humanOverride.status === 'failed');
-    if (result.status === 'failed' || overrideFailed)
+    process.stdout.write(`${JSON.stringify(result)}\n`);
+    if (result.status === 'failed')
         process.exitCode = 1;
 }
 export { taskLedger };