@fitlab-ai/agent-infra 0.11.2 → 0.11.4

package/lib/task/review-finalization.ts

@@ -16,7 +16,6 @@ import { allowsManualOverride } from './guard-override.ts';
 import type { ManualOverrideCapability } from './guard-override.ts';
 import { getArtifactSchema } from './artifact-schema.ts';
 import { canonicalSemanticDigest, inspectArtifactContract, sha256Content } from './artifact-operations.ts';
-import { expectedQualificationRelations, validateQualificationAudit } from './qualification-audit.ts';
 
 type ReviewFinalizationErrorCode =
   | ResolveTaskRefErrorCode
@@ -30,7 +29,6 @@ type ReviewFinalizationErrorCode =
   | 'REVIEW_SUMMARY_PLACEHOLDER_INVALID'
   | 'REVIEW_SUMMARY_COUNT_MISMATCH'
   | 'REVIEW_ARTIFACT_STRUCTURE_INVALID'
-  | 'REVIEW_ARTIFACT_QUALIFICATION_INVALID'
   | 'REVIEW_DECISION_DETAIL_INVALID'
   | 'REVIEW_ARTIFACT_CONFLICT'
   | 'REVIEW_PROVENANCE_INVALID'
@@ -143,10 +141,8 @@ function preflightReviewSummaryUnlocked(
   const publicationError = validateArtifactPublication(resolved.taskDir, spec.family, request.artifact);
   if (publicationError) return preflightFailed(request, 'REVIEW_ARTIFACT_IDENTITY_INVALID', publicationError.message, resolved.taskId);
 
-  let taskContent: string;
   let content: string;
   try {
-    taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
     const validated = validateCompletedArtifact(resolved.taskDir, spec.family, request.artifact);
     if (!validated.ok) return preflightFailed(request, validated.error.code === 'ARTIFACT_NOT_REGULAR' ? 'REVIEW_ARTIFACT_NOT_REGULAR' : 'REVIEW_ARTIFACT_IDENTITY_INVALID', validated.error.message, resolved.taskId);
     content = fs.readFileSync(validated.artifact.path, 'utf8');
@@ -163,21 +159,12 @@ function preflightReviewSummaryUnlocked(
   const semanticDigest = canonicalSemanticDigest(content);
   const detail = inspectDecisionDetailDuplicates(content);
   const structure = inspectArtifactContract(content, getArtifactSchema(spec.family)!);
-  const expected = expectedQualificationRelations(taskContent, spec.family);
-  if (!expected.ok) return preflightFailed(request, 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', `${expected.code}: ${expected.message}`, resolved.taskId, { artifactSha256, semanticDigest });
-  const qualification = validateQualificationAudit(taskContent, content, {
-    family: spec.family,
-    artifact: request.artifact,
-    expectedUpstreamRelations: expected.relations
-  });
-  const qualificationError = qualification.ok ? null : qualification;
-  if (!detail.ok || !structure.ok || qualificationError) {
+  if (!detail.ok || !structure.ok) {
     const diagnostics = [
       ...(!detail.ok ? [`${detail.code}: ${detail.message}`] : []),
-      ...structure.diagnostics.map((item) => `${item.code}: ${item.message}`),
-      ...(qualificationError ? [`${qualificationError.code}: ${qualificationError.message}`] : [])
+      ...structure.diagnostics.map((item) => `${item.code}: ${item.message}`)
     ].join('; ');
-    return preflightFailed(request, !detail.ok ? 'REVIEW_DECISION_DETAIL_INVALID' : !structure.ok ? 'REVIEW_ARTIFACT_STRUCTURE_INVALID' : 'REVIEW_ARTIFACT_QUALIFICATION_INVALID', diagnostics, resolved.taskId, {
+    return preflightFailed(request, !detail.ok ? 'REVIEW_DECISION_DETAIL_INVALID' : 'REVIEW_ARTIFACT_STRUCTURE_INVALID', diagnostics, resolved.taskId, {
       artifactSha256, semanticDigest,
     });
   }

package/lib/task/rework-intent.ts

@@ -1,9 +1,14 @@
 const REWORK_INTENT_HEADINGS = ['返工意图', 'Rework Intent'] as const;
 const REWORK_INTENT_COLUMNS = [
+  'intent_id', 'finding_id', 'source_artifact', 'source_sha256', 'target',
+  'classification', 'evidence_digest', 'task_fact_digest', 'status', 'declared_at', 'consumed_at'
+] as const;
+const LEGACY_REWORK_INTENT_COLUMNS = [
   'intent_id', 'finding_id', 'source_artifact', 'source_sha256', 'target',
   'status', 'declared_at', 'consumed_at'
 ] as const;
-type ReworkTarget = 'analysis' | 'plan' | 'code';
+type ReworkTarget = 'analysis' | 'plan' | 'code' | 'pause';
+type ReworkClassification = 'scope-or-requirement' | 'design' | 'implementation' | 'human-decision' | 'insufficient-evidence';
 type ReworkIntentStatus = 'pending' | 'consumed' | 'superseded';
 type ReworkIntent = {
   intentId: string;
@@ -11,6 +16,9 @@ type ReworkIntent = {
   sourceArtifact: string;
   sourceSha256: string;
   target: ReworkTarget;
+  classification?: ReworkClassification;
+  evidenceDigest?: string;
+  taskFactDigest?: string;
   status: ReworkIntentStatus;
   declaredAt: string;
   consumedAt: string;
@@ -66,15 +74,19 @@ function parseReworkIntentDocument(content: string): ReworkIntentParseResult {
       const row = Object.fromEntries(REWORK_INTENT_COLUMNS.map((column, index) => [column, values[index]!])) as Record<string, string>;
       if (!/^RI-[1-9]\d*$/.test(row.intent_id!)) throw new Error(`invalid intent id '${row.intent_id}'`);
       if (!/^(AN|PL|CD)-[1-9]\d*$/.test(row.finding_id!)) throw new Error(`invalid finding id '${row.finding_id}'`);
-      if (!['analysis', 'plan', 'code'].includes(row.target!)) throw new Error(`invalid rework target '${row.target}'`);
+      if (!['analysis', 'plan', 'code', 'pause'].includes(row.target!)) throw new Error(`invalid rework target '${row.target}'`);
+      if (!['scope-or-requirement', 'design', 'implementation', 'human-decision', 'insufficient-evidence'].includes(row.classification!)) throw new Error(`invalid rework classification '${row.classification}'`);
       if (!['pending', 'consumed', 'superseded'].includes(row.status!)) throw new Error(`invalid rework status '${row.status}'`);
       if (!/^[a-f0-9]{64}$/.test(row.source_sha256!)) throw new Error(`invalid source hash for '${row.intent_id}'`);
+      if (!/^[a-f0-9]{64}$/.test(row.evidence_digest!) || !/^[a-f0-9]{64}$/.test(row.task_fact_digest!)) throw new Error(`invalid semantic digest for '${row.intent_id}'`);
       if (!row.source_artifact || !row.declared_at) throw new Error(`rework intent '${row.intent_id}' has invalid required fields`);
       const terminal = row.status === 'consumed' || row.status === 'superseded';
       if (terminal !== Boolean(row.consumed_at)) throw new Error(`rework intent '${row.intent_id}' has invalid consumed_at`);
       return {
         intentId: row.intent_id!, findingId: row.finding_id!, sourceArtifact: row.source_artifact!,
         sourceSha256: row.source_sha256!, target: row.target as ReworkTarget,
+        classification: row.classification as ReworkClassification,
+        evidenceDigest: row.evidence_digest!, taskFactDigest: row.task_fact_digest!,
         status: row.status as ReworkIntentStatus, declaredAt: row.declared_at!, consumedAt: row.consumed_at!
       } satisfies ReworkIntent;
     });
@@ -96,7 +108,10 @@ function renderReworkIntents(intents: readonly ReworkIntent[]): string {
     `| ${REWORK_INTENT_COLUMNS.map(() => '---').join(' | ')} |`,
     ...intents.map((intent) => `| ${[
       intent.intentId, intent.findingId, intent.sourceArtifact, intent.sourceSha256,
-      intent.target, intent.status, intent.declaredAt, intent.consumedAt
+      intent.target, intent.classification ?? (intent.target === 'analysis' ? 'scope-or-requirement' : intent.target === 'plan' ? 'design' : intent.target === 'code' ? 'implementation' : 'insufficient-evidence'),
+      intent.evidenceDigest ?? requireDigest(`${intent.findingId}|${intent.sourceArtifact}|${intent.sourceSha256}`),
+      intent.taskFactDigest ?? requireDigest(`current|${intent.findingId}|${intent.target}`),
+      intent.status, intent.declaredAt, intent.consumedAt
     ].map(escape).join(' | ')} |`)
   ].join('\n');
 }
@@ -104,11 +119,63 @@ function renderReworkIntents(intents: readonly ReworkIntent[]): string {
 function upsertReworkIntent(intents: readonly ReworkIntent[], intent: ReworkIntent): { changed: boolean; intents: readonly ReworkIntent[] } {
   const existing = intents.find((candidate) => candidate.intentId === intent.intentId);
   if (!existing) return { changed: true, intents: [...intents, intent] };
-  const identity = (value: ReworkIntent) => [value.intentId, value.findingId, value.sourceArtifact, value.sourceSha256, value.target];
+  const identity = (value: ReworkIntent) => [value.intentId, value.findingId, value.sourceArtifact, value.sourceSha256, value.target, value.classification, value.evidenceDigest, value.taskFactDigest];
   if (JSON.stringify(identity(existing)) !== JSON.stringify(identity(intent))) throw new Error(`intent '${intent.intentId}' identity conflicts with existing state`);
   return { changed: false, intents };
 }
 
+function consumeHumanDecisionReworkIntents(
+  intents: readonly ReworkIntent[],
+  findingId: string,
+  consumedAt: string
+): { changed: boolean; intents: readonly ReworkIntent[] } {
+  let changed = false;
+  const next = intents.map((intent) => {
+    if (intent.status !== 'pending' || intent.target !== 'pause' || intent.classification !== 'human-decision' || intent.findingId !== findingId) return intent;
+    changed = true;
+    return { ...intent, status: 'consumed' as const, consumedAt };
+  });
+  return { changed, intents: next };
+}
+
+function parseLegacyReworkIntentDocument(content: string): ReworkIntentParseResult {
+  // TODO(compat): Remove this explicit decoder once no task contains the eight-column rework-intent header.
+  const body = sectionBody(content);
+  if (body === null) return { ok: false, code: 'TASK_REWORK_INTENT_INVALID', message: 'legacy rework intent section is missing' };
+  const lines = body.split(/\r?\n/).filter((line) => line.trim());
+  const header = lines[0] ? cells(lines[0]) : null;
+  const separator = lines[1] ? cells(lines[1]) : null;
+  if (!header || !separator || header.length !== LEGACY_REWORK_INTENT_COLUMNS.length || !header.every((value, index) => value === LEGACY_REWORK_INTENT_COLUMNS[index])) {
+    return { ok: false, code: 'TASK_REWORK_INTENT_INVALID', message: 'rework intent section is not the known legacy table' };
+  }
+  try {
+    const intents = lines.slice(2).map((line) => {
+      const values = cells(line);
+      if (!values || values.length !== LEGACY_REWORK_INTENT_COLUMNS.length) throw new Error('legacy rework intent row has the wrong column count');
+      const row = Object.fromEntries(LEGACY_REWORK_INTENT_COLUMNS.map((column, index) => [column, values[index]!])) as Record<string, string>;
+      if (!/^RI-[1-9]\d*$/.test(row.intent_id!) || !/^(AN|PL|CD)-[1-9]\d*$/.test(row.finding_id!)) throw new Error('legacy rework intent identity is invalid');
+      if (!['analysis', 'plan', 'code'].includes(row.target!) || !['pending', 'consumed', 'superseded'].includes(row.status!)) throw new Error('legacy rework intent state is invalid');
+      if (!/^[a-f0-9]{64}$/.test(row.source_sha256!)) throw new Error('legacy rework intent source hash is invalid');
+      const legacyDigest = (value: string) => requireDigest(value);
+      const classification: ReworkClassification = row.target === 'analysis' ? 'scope-or-requirement' : row.target === 'plan' ? 'design' : 'implementation';
+      return {
+        intentId: row.intent_id!, findingId: row.finding_id!, sourceArtifact: row.source_artifact!, sourceSha256: row.source_sha256!,
+        target: row.target as ReworkTarget, classification,
+        evidenceDigest: legacyDigest(`${row.finding_id}|${row.source_artifact}|${row.source_sha256}`),
+        taskFactDigest: legacyDigest(`legacy|${row.finding_id}|${row.target}`),
+        status: row.status as ReworkIntentStatus, declaredAt: row.declared_at!, consumedAt: row.consumed_at!
+      } satisfies ReworkIntent;
+    });
+    return { ok: true, present: true, intents };
+  } catch (error) {
+    return { ok: false, code: 'TASK_REWORK_INTENT_INVALID', message: error instanceof Error ? error.message : String(error) };
+  }
+}
+
+function requireDigest(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
 function consumeReworkIntents(
   intents: readonly ReworkIntent[],
   target: ReworkTarget,
@@ -161,5 +228,8 @@ export {
   consumeReworkIntents,
   supersedeReworkIntents,
   upsertReworkIntent
+  , consumeHumanDecisionReworkIntents
+  , parseLegacyReworkIntentDocument
 };
-export type { ReworkIntent, ReworkIntentParseResult, ReworkIntentStatus, ReworkTarget };
+export type { ReworkClassification, ReworkIntent, ReworkIntentParseResult, ReworkIntentStatus, ReworkTarget };
+import { createHash } from 'node:crypto';

package/lib/task/verification-engine.ts

@@ -40,7 +40,6 @@ import type { OrchestrationRun } from "./orchestration.ts";
 import { resolveDeliveryTarget } from "./delivery-target.ts";
 import { readPrDeliveryFact } from "./pr-delivery-fact.ts";
 import { validateLocalArtifact } from "./local-artifact-finalization.ts";
-import { validateQualificationAudit } from "./qualification-audit.ts";
 import { getArtifactSchema } from "./artifact-schema.ts";
 import { inspectArtifactContract } from "./artifact-operations.ts";
 import type { VerificationShared } from "./verification-types.ts";
@@ -78,7 +77,6 @@ const BRANCH_SLUG_PATTERN = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 
 // Review disagreement ledger (see .agents/rules/review-handshake.md).
 const LEDGER_SECTION_NAMES = ["审查分歧账本", "Review Disagreement Ledger"];
-const DEFAULT_MAX_HANDSHAKE_ROUNDS = 3;
 const POST_REVIEW_COMMIT_STAGE = "post-review-commit";
 const SHA_PATTERN = /^[0-9a-f]{7,40}$/i;
 
@@ -511,19 +509,6 @@ function checkArtifact({ taskDir, config, artifactFile, skillName }: any): any {
   }
 
   const content = fs.readFileSync(artifactPath, "utf8");
-  let taskContent = "";
-  const taskPath = path.join(taskDir, "task.md");
-  if (fs.existsSync(taskPath)) {
-    try {
-      taskContent = fs.readFileSync(taskPath, "utf8");
-    } catch (error) {
-      return failResult("artifact", `Cannot read task qualification contract: ${error instanceof Error ? error.message : String(error)}`);
-    }
-  }
-  if (taskContent && /^review-(?:analysis|plan|code)$/.test(skillName)) {
-    const qualification = validateQualificationAudit(taskContent, content, { artifact: path.basename(artifactPath) });
-    if (!qualification.ok) return failResult("artifact", `${path.basename(artifactPath)} has qualification audit errors: ${qualification.code}: ${qualification.message}`);
-  }
   const schemaFamily = skillName === "analyze-task"
     ? "analysis"
     : skillName === "review-analysis"
@@ -547,9 +532,7 @@ function checkArtifact({ taskDir, config, artifactFile, skillName }: any): any {
   }
   if (localFamily) {
     const local = validateLocalArtifact(content, {
-      family: localFamily,
-      ...(taskContent ? { taskContent } : {}),
-      artifact: path.basename(artifactPath)
+      family: localFamily
     });
     if (!local.ok) {
       return failResult(
@@ -818,12 +801,11 @@ function checkReviewLedger({ taskDir, config, repositoryRoot }: any): any {
   }
 
   const stageScope = Array.isArray(config.stage_scope) ? config.stage_scope : null;
-  const maxRounds = Number(resolveReviewSetting(config, "maxHandshakeRounds", DEFAULT_MAX_HANDSHAKE_ROUNDS, repositoryRoot));
   const problems = [];
   let inScopeCount = 0;
 
   for (const row of rows) {
-    const { id, stage, round: roundRaw, status, evidence } = row;
+    const { id, stage, status, evidence } = row;
     const stageScoped = stageScope ? stageScope.includes(stage) : true;
     // post-review-commit exemption rows are consumed by the post-review-commit
     // check, not enforced here.
@@ -843,15 +825,6 @@ function checkReviewLedger({ taskDir, config, repositoryRoot }: any): any {
     if (status !== "open" && evidence === "") {
       problems.push(`${id}: status '${status}' requires evidence`);
     }
-    const round = Number.parseInt(roundRaw!, 10);
-    if (
-      Number.isFinite(round) &&
-      round >= maxRounds &&
-      !LEDGER_TERMINAL.has(status!) &&
-      status !== "needs-human-decision"
-    ) {
-      problems.push(`${id}: round ${round} reached limit ${maxRounds} without convergence; escalate to needs-human-decision`);
-    }
     if (!LEDGER_TERMINAL.has(status!)) {
       problems.push(`${id}: unresolved (status '${status}')`);
     }
@@ -1194,7 +1167,8 @@ function checkReviewFact({ taskDir, artifactFile, repositoryRoot }: any): any {
   let targetHead;
   let diffBase;
   try {
-    gitRoot = execFileSync("git", ["-C", taskDir, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+    const taskRepositoryRoot = execFileSync("git", ["-C", taskDir, "rev-parse", "--show-toplevel"], { encoding: "utf8" }).trim();
+    gitRoot = reviewWorktreeForTask(taskRepositoryRoot, String(task.metadata.branch || "").trim()) ?? taskRepositoryRoot;
     head = execFileSync("git", ["-C", gitRoot, "rev-parse", "HEAD"], { encoding: "utf8" }).trim();
     const target = resolveDeliveryTarget(gitRoot, { remote: deliveryRemote, baseRef: deliveryBaseRef });
     if (!target.ok) throw new Error(target.message);
@@ -1275,6 +1249,21 @@ function checkReviewFact({ taskDir, artifactFile, repositoryRoot }: any): any {
   );
 }
 
+function reviewWorktreeForTask(repositoryRoot: string, branch: string): string | null {
+  if (!branch) return null;
+  const expectedRef = `refs/heads/${branch}`;
+  const records = execFileSync("git", ["-C", repositoryRoot, "worktree", "list", "--porcelain"], {
+    encoding: "utf8",
+    stdio: ["pipe", "pipe", "pipe"]
+  }).trim().split(/\r?\n\r?\n/);
+  for (const record of records) {
+    const worktree = /^worktree (.+)$/m.exec(record)?.[1];
+    const branchRef = /^branch (.+)$/m.exec(record)?.[1];
+    if (worktree && branchRef === expectedRef) return worktree;
+  }
+  throw new Error(`Task branch '${branch}' is not checked out in a registered worktree`);
+}
+
 function resolvePostReviewBaseline({ gitRoot, lastReviewedCommit, reviewArtifact }: any): any {
   if (SHA_PATTERN.test(lastReviewedCommit) && gitCommitExists(gitRoot, lastReviewedCommit)) {
     return { ok: true, sha: lastReviewedCommit };

package/lib/task/verification.ts

@@ -15,7 +15,7 @@ type VerificationEvent =
   | 'review-analysis.completed' | 'plan.completed' | 'review-plan.completed'
   | 'code.completed' | 'review-code.completed' | 'manual-validation.completed' | 'validation-run.completed'
   | 'block-task.completed' | 'cancel-task.completed' | 'commit.completed'
-  | 'complete-task.preflight' | 'complete-task.hard-preflight' | 'complete-task.completed'
+  | 'complete-task.preflight' | 'complete-task.hard-preflight' | 'complete-task.prepared' | 'complete-task.completed'
   | 'create-pr.completed' | 'create-task.completed'
   | 'import-codescan.completed' | 'import-dependabot.completed'
   | 'import-issue.completed' | 'watch-pr.completed'
@@ -71,6 +71,7 @@ const VERIFICATION_CATALOG: Readonly<Record<VerificationEvent, VerificationSpec>
   'commit.completed': gate('commit', 'active'),
   'complete-task.preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
   'complete-task.hard-preflight': { skill: 'complete-task', expectedState: 'active', mode: 'checks', checks: ['required-pr-delivery'] },
+  'complete-task.prepared': gate('complete-task', 'active'),
   'complete-task.completed': gate('complete-task', 'completed'),
   'create-pr.completed': gate('create-pr', 'active'),
   'create-task.completed': gate('create-task', 'active'),

package/lib/task/workflow-warning-intents.ts

@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 
 import { resolveTaskRef } from './resolve-ref.ts';
+import { parseTaskFrontmatter } from './frontmatter.ts';
 import {
   WORKFLOW_WARNING_COLUMNS,
   WORKFLOW_WARNING_HEADINGS,
@@ -137,11 +138,18 @@ function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: Task
 function projectFinalizationWarning(
   taskRef: string,
   warning: OperationWarning & { status: 'open' | 'resolved'; resolvedAt: string | null },
-  options: TaskWriteOptions = {}
+  options: TaskWriteOptions & { resolution?: 'passed' | 'superseded' } = {}
 ): FinalizationWarningProjectionResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return { status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } };
-  if (resolved.state !== 'completed') return { status: 'failed', changed: false, error: { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected completed` } };
+  let prepared = resolved.state === 'completed';
+  if (!prepared && resolved.state === 'active') {
+    try { prepared = parseTaskFrontmatter(fs.readFileSync(resolved.taskMdPath, 'utf8')).status === 'completed'; }
+    catch { prepared = false; }
+  }
+  if (!prepared) {
+    return { status: 'failed', changed: false, error: { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected a prepared or completed task` } };
+  }
   let content: string;
   let rows: WorkflowWarning[];
   try {
@@ -160,22 +168,26 @@ function projectFinalizationWarning(
       message: warning.message,
       action: retryHintForWarning(warning),
       resolvedAt: warning.resolvedAt || (warning.status === 'resolved' ? metadata.timestamp : ''),
-      resolution: warning.status === 'resolved' ? 'Resolved by a successful finalization retry' : ''
+      resolution: warning.status === 'resolved'
+        ? options.resolution === 'superseded' ? 'Superseded by a later verification observation' : 'Resolved by a successful finalization retry'
+        : ''
     }
     : {
       id: nextWarningId(rows), time: metadata.timestamp, step: warning.step,
       severity: warning.severity, code: warning.code, status: warning.status,
       target: warning.target, message: warning.message, action: retryHintForWarning(warning),
-      resolvedAt: warning.resolvedAt || '', resolution: warning.status === 'resolved' ? 'Resolved by a successful finalization retry' : ''
+      resolvedAt: warning.resolvedAt || '', resolution: warning.status === 'resolved'
+        ? options.resolution === 'superseded' ? 'Superseded by a later verification observation' : 'Resolved by a successful finalization retry'
+        : ''
     };
   if (existing && JSON.stringify(existing) === JSON.stringify(after)) return { status: 'no-op', changed: false, error: null };
   const written = writeTask({
     taskRef: resolved.taskId,
-    expectedState: 'completed',
+    expectedState: resolved.state,
     mutations: [...sectionMutation(content), rowMutation(after)]
   }, {
     ...options,
-    taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: 'completed' },
+    taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state },
     metadataProvider: () => metadata
   });
   if (written.status === 'failed') return { status: 'failed', changed: false, error: { code: written.error.code, message: written.error.message } };

package/lib/task/workspace-snapshot.ts

@@ -42,7 +42,8 @@ function captureWorktreeTree(repoRoot: string, forcedPath: string | null): strin
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-orchestration-index-'));
   const indexFile = path.join(tempDir, 'index');
   try {
-    git(repoRoot, indexFile, ['read-tree', 'HEAD']);
+    try { git(repoRoot, indexFile, ['read-tree', 'HEAD']); }
+    catch { git(repoRoot, indexFile, ['read-tree', '--empty']); }
     git(repoRoot, indexFile, ['add', '-A', '--', ':/']);
     if (forcedPath && fs.existsSync(path.join(repoRoot, forcedPath))) {
       git(repoRoot, indexFile, ['add', '-f', '--', forcedPath]);
@@ -138,5 +139,5 @@ function diffWorkspaceSnapshots(repoRoot: string, before: string, after: string)
   return [...changed].sort();
 }
 
-export { captureRepositorySnapshot, captureWorkspaceSnapshot, diffWorkspaceSnapshots };
+export { captureRepositorySnapshot, captureWorkspaceSnapshot, captureWorktreeTree, diffWorkspaceSnapshots };
 export type { OrchestrationWorkspaceFingerprint, RepositorySnapshot, WorkspaceSnapshotContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.11.2",
+  "version": "0.11.4",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/rules/lifecycle-orchestration.en.md

@@ -12,19 +12,33 @@
 
 `orchestration.json` records stages, model policy, child identity, and actual outcomes. Records use the current structure; trusted local operators may correct them and rerun validation. Existing task write locks and atomic writes protect updates.
 
-## Codex Host
+## Current Host
 
-- Use native spawn, wait, and App Server results from the current host; forward task operations through the existing broker.
+- Use native spawn, wait, and App Server results from the current host. A task-bound sandbox executes ordinary task orchestration locally in the current worktree.
+- Codex controller `open`, `verify`, and `close` remain restricted broker operations. After `open`, complete typed `verify` with the same lease proof before accepting the task, control-generation, and controller-instance binding.
 - Prepare validates the current task, model policy, and host preflight. Start and terminal records associate observed parent/child identity; failure must not be recorded as success.
-- Local execution does not require capability, controller attestation, or one-use consumption authority. Do not add automatic child discovery, spawn under a new lock protocol, orphan recovery, or a dedicated recovery protocol.
+- Client-specific preflight, event sources, and stop-evidence validation belong to the client adapter. The common orchestrator calls only the shared capability and contains no client-ID branches.
+
+## Activated Delegation Recovery
+
+- Before `begin-or-resume`, the orchestrator calls internal `task-lifecycle <task> recover-started --agent <client> --auto`. This entry is not user-facing and never infers child termination from missing liveness evidence.
+- The client adapter declares recovery support and validates trusted stop evidence for the current pending delegation. Unsupported adapters and runs without an activated pending delegation return `no-op`; uncertain termination fails closed.
+- Recovery consumes stop evidence, saves an aborted receipt while clearing pending, then appends the Activity Log terminal row. If the run save succeeds and the log write fails, the next invocation appends only the missing row.
+- Routing continues only after `no-op` or `applied`. Lost control responses are not reconstructed; the next operator invocation relies on the idempotent persisted state.
+
+## Current-only Cutover and Rollback
+
+- Enter a quiet window before cutover: let in-flight orchestration intents return, stop the wrapper/controller, and preserve the worktree, task/run/orchestration state, receipts, registration, and audit. For an unknown result, inspect local `status`/`route` before using existing recover/advance semantics; do not replay an old broker request.
+- Deploy or roll back the CLI, broker, controller adapter, and protocol as one versioned unit. After stopping the old container/broker, rebuild and run `ai sandbox start --recreate <task-ref>` to resume with a new control generation; never reuse an old token, proof, or request.
+- On either the new or rolled-back version, first confirm the same task through `status`/`route`, then require a successful typed controller `open`→`verify`. Keep the quiet window and evidence intact if any check fails; do not mix component versions or rewrite domain facts.
 
 ## Model Policy
 
 - A new run persists model and reasoning effort for both roles. Explicit policy is atomic across all four role fields; only a fully absent explicit policy may fall back to the current client's `agentClients[].orchestration`.
 - Route resolves requested model/effort by role, and prepare matches both before snapshotting. Native spawn must not inherit session defaults.
-- Native start records host-observed actual model/effort. Each mismatch needs its own fallback reason (the claude-code path may leave this blank and follow the recording rules instead), and requested values must never be fabricated as actual evidence.
+- Native start records host-observed actual model/effort. Fields declared unobservable by the adapter follow the recording rules; each observable mismatch needs its own fallback reason, and requested values must never be fabricated as actual evidence.
 - Model selection is labeled as a complete catalog, partial catalog, or interactive-only guidance; a local override enum must not be presented as complete.
-- claude-code's requested reasoning effort does not yet support per-role dispatch (concurrent tasks would race on a shared file); `delegationEvidence.actualReasoningEffort` is declared `spawn-ack`, meaning it is only recorded when honestly observed in a native spawn lifecycle event (Start/Stop) — it is not a promise of per-role dispatch and does not gate activation.
+- An adapter must declare any policy field it cannot dispatch per role. Values observed in host events are actual evidence only; they do not promise dispatch or gate activation.
 
 ## Stable Pause Conditions
 

package/templates/.agents/rules/lifecycle-orchestration.zh-CN.md

@@ -12,19 +12,33 @@
 
 `orchestration.json` 记录阶段、模型策略、child 身份及实际执行结果。记录必须符合当前结构；本地操作者可直接修正后重新校验。已有任务写锁与原子写入继续保护写操作。
 
-## Codex 宿主
+## 当前宿主
 
-- 使用当前宿主的原生 spawn、wait 与 App Server 结果；任务操作通过现有 broker 转发。
+- 使用当前宿主的原生 spawn、wait 与 App Server 结果；task-bound sandbox 在当前 worktree 本地执行普通任务编排。
+- Codex controller 的 `open`、`verify`、`close` 继续通过受限 broker 执行。`open` 后必须用同一 lease proof 完成 typed `verify`，再接受 task、control generation 和 controller instance 绑定。
 - prepare 校验当前任务、模型策略与宿主 preflight。启动和完成记录关联实际 parent/child 身份，失败不得写成成功。
-- 不要求 capability、controller attestation 或一次性消费授权本地实现；不新增 child 自动发现、锁内启动交接、孤立 child 恢复或专用恢复协议。
+- 客户端特有的 preflight、事件来源与停止证据校验由客户端适配器实现；公共总控只调用统一能力。不得在公共流程中新增客户端 ID 分支。
+
+## Activated delegation 自动恢复
+
+- 总控在 `begin-or-resume` 前调用内部 `task-lifecycle <task> recover-started --agent <client> --auto`。该入口不公开给用户，也不从缺少存活证据推断 child 已终止。
+- 客户端适配器决定是否支持恢复，并验证当前 pending delegation 的可信停止证据；不支持或没有 activated pending 时返回 `no-op`，无法确认停止时失败关闭。
+- 恢复按固定顺序消费停止证据、保存 aborted receipt 并清除 pending，再写 Activity Log 结束记录。任务状态已保存而日志未写时，下次调用只补日志。
+- 只有 `no-op` 或 `applied` 才能继续 route。控制响应丢失时不重建恢复结果；下一次人为调用依靠幂等状态继续。
+
+## Current-only 切换与回滚
+
+- 切换前进入静默窗口：等待在途编排 intent 返回，停止 wrapper/controller，并保留 worktree、task/run/orchestration 状态、receipts、registration 与 audit。结果未知时先用本地 `status`/`route` 判断 domain 是否已提交，再按现有 recover/advance 语义处理；旧 broker request 不重放。
+- CLI、broker、controller adapter 和协议必须作为同一版本单元部署或回退。停止旧 container/broker 后执行 rebuild 与 `ai sandbox start --recreate <task-ref>`，以新 control generation 恢复执行；旧 token、proof 和 request 不得复用。
+- 新版本或回退版本都必须先核对同一任务的 `status`/`route`，再要求 controller typed `open`→`verify` 成功。任一检查失败时继续保持静默并保留证据，不局部混用组件或改写 domain 事实。
 
 ## 模型策略
 
 - 新 run 必须固化 executor/reviewer 各自的 model 与 reasoning effort；显式策略必须四字段原子完整，完全没有显式字段时才读取当前 client 的 `agentClients[].orchestration`。重入不得静默改写策略。
 - route 按 role 返回 requested model/effort，prepare 必须在工作区快照前精确匹配两者；原生 spawn 不能继承会话默认值。
-- 原生 start 必须记录宿主观察到的 actual model/effort。任一字段与 requested 不同时必须记录独立 fallback reason（claude-code 路径下允许留空，按记录规则处理）；requested 值不得补造 actual 证据。
+- 原生 start 必须记录宿主观察到的 actual model/effort。适配器声明无法观察的字段按记录规则处理；任一可观察字段与 requested 不同时必须记录独立 fallback reason，requested 值不得补造 actual 证据。
 - 模型选择能力必须标记 complete catalog、partial catalog 或 interactive-only guidance；局部 override 枚举不得冒充完整目录。
-- claude-code 的 requested reasoning effort 暂不支持按角色下发（跨任务共享文件存在写入竞态）；`delegationEvidence.actualReasoningEffort` 声明为 `spawn-ack`，语义为"仅能在宿主原生 spawn 生命周期事件（Start/Stop）里如实观察到时记录，不构成按角色下发的承诺，也不构成放行门禁"。
+- 客户端无法按角色下发的策略字段必须由适配器明确声明；宿主事件中观察到的值只作为实际证据，不构成下发承诺或放行门禁。
 
 ## 稳定暂停条件
 

package/templates/.agents/rules/review-handshake.en.md

@@ -29,11 +29,11 @@ After the executor gives `adjusted` / `refuted` / `cannot-judge`, the reviewer m
 - **Hold with new evidence** → set back to `open` (with new evidence, returned to the executor).
 - **Escalate to human** → set to `needs-human-decision`.
 
-## Convergence termination (loop guard)
+## Evidence-driven rework convergence
 
-- The per-finding handshake round limit is `MAX_HANDSHAKE_ROUNDS`, default **3**, overridable via `review.maxHandshakeRounds` in `.agents/.airc.json`.
-- When a finding's `round` reaches the limit without entering a terminal state, it must be forced to `needs-human-decision`; the gate rejects rows that hit the limit without escalating.
-- `needs-human-decision` keeps blocking completion until a human records a ruling in the task.md `## 人工裁决` section and flips the row to `human-decided`.
+- The first Changes Requested verdict permits an ordinary revision. After one revision-review cycle, another Changes Requested verdict must classify the problem as scope or requirements, design, implementation, human decision, or insufficient evidence before another executor artifact is created.
+- Classification binds the finding, source review SHA, and stable task-fact digest. Artifact names, rounds, and retry counts are not evidence by themselves.
+- Human choice and insufficient evidence pause stably; implementation can continue when new decisive evidence exists. Retry count alone never forces a human escalation.
 
 ## Same-model convergence-bias mitigation (documentation-level discipline)
 

package/templates/.agents/rules/review-handshake.zh-CN.md

@@ -29,11 +29,11 @@
 - **补充新证据后坚持** → 账本置回 `open`（带新证据，回到执行方）。
 - **升级人工裁决** → 账本置 `needs-human-decision`。
 
-## 收敛终止语义（防死循环）
+## 证据驱动的返工收敛
 
-- 单条 finding 的握手轮次上限 `MAX_HANDSHAKE_ROUNDS`，默认 **3**，可在 `.agents/.airc.json` 的 `review.maxHandshakeRounds` 覆盖。
-- 某条 finding 的 `round` 达到上限仍未进入终态，必须强制置 `needs-human-decision`；gate 会拦截"达限却未升级"的行。
-- `needs-human-decision` 持续阻塞完成，直到人工在 task.md `## 人工裁决` 段记录裁定并把该行翻为 `human-decided`。
+- 首次 Changes Requested 允许正常修订。完成一次修订—复审后再次收到 Changes Requested 时，必须在下一执行产物前把问题分类为范围或需求、方案、实现、人工裁决或证据不足。
+- 分类必须绑定 finding、来源审查 SHA 和稳定任务事实摘要。文件名、artifact round 或返工次数本身不构成新证据。
+- 人工选择或证据不足进入稳定暂停；具有新决定性证据的实现缺陷可以继续修订。不得仅因次数达到阈值强制升级人工裁决。
 
 ## 同源模型收敛偏差缓解（文档级纪律）
 

package/templates/.agents/skills/analyze-task/SKILL.en.md

@@ -13,6 +13,10 @@ If the entry operands contain `--orchestrated`, bind `{execution-flag}` to `--or
 
 ## Boundary / Critical Rules
 
+### Flow decision
+
+The analysis artifact must record the selected path, factual basis, unmet higher-path conditions, and factual upgrade triggers in `## Flow Decision`. The path is streamlined, standard, or full; file count, module count, and speculative risk cannot upgrade it by themselves.
+
 ### Persisted Report Evidence
 
 Before generating the analysis report, read `.agents/rules/evidence-reporting.md`. Record the command, target scope, status or structured result, actual result, and uncovered parts for state checks and successful checks; include decisive raw excerpts only for failures, blocking conditions, or disputes.
@@ -61,7 +65,7 @@ If `task.md` is missing, tell the user to create or import the task first.
 
 ### 2. Resolve the Analysis Context
 
-Run `agent-infra-internal task-artifact {task-id} inspect --family analysis`. Continue only for `ready`; take `{analysis-round}` / `{analysis-artifact}` from `next.round` / `next.name` and revision inputs from `inputs`. Do not scan rounds or construct names in the skill.
+Run `agent-infra-internal task-artifact {task-id} inspect --family analysis`. Continue only for `ready`. When `selection.disposition` is `reuse`, reuse `selection.artifact`, do not run started/init or write a new artifact, and continue directly to completion verification and next-step guidance. Otherwise take `{analysis-round}` / `{analysis-artifact}` from `next.round` / `next.name` and revision inputs from `inputs`. Do not scan rounds or construct names in the skill.
 
 ### 3. Read Task Context
 
@@ -261,7 +265,10 @@ Keep the gate output in your reply as fresh evidence. Do not claim completion wi
 > Before rendering next steps, read `.agents/rules/next-step-output.md`, invoke the shared helper only for the selected scenario, and insert its stdout at `{next-step-commands}`.
 
 Output format:
-Populate `{next-step-commands}` for this scenario by running `agent-infra-internal agent-client next-steps --skill review-analysis --task-ref {task-ref}`.
+Select one command from the canonical path to populate `{next-step-commands}`:
+- Streamlined: `agent-infra-internal agent-client next-steps --skill code-task --task-ref {task-ref}`
+- Standard: `agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}`
+- Full: `agent-infra-internal agent-client next-steps --skill review-analysis --task-ref {task-ref}`
 
 ```
 Analysis complete for task {task-id}.
@@ -274,7 +281,7 @@ Summary:
 Output file:
 - Analysis report: .agents/workspace/active/{task-id}/{analysis-artifact}
 
-Next step - review the analysis:
+Next step - continue on the selected path:
 {next-step-commands}
 ```
 
@@ -292,7 +299,7 @@ Next step - review the analysis:
 
 ## STOP
 
-After completing the checklist, **stop immediately**. Wait for the user to review the analysis result and manually invoke the `plan-task` skill.
+After completing the checklist, **stop immediately**. Wait for the user to invoke the next stage selected above.
 
 ## Notes
 

package/templates/.agents/skills/analyze-task/SKILL.zh-CN.md

@@ -13,6 +13,10 @@ description: >
 
 ## 行为边界 / 关键规则
 
+### 流程裁定
+
+分析产物必须在 `## 流程裁定` 中记录本任务路径、判定依据、未满足的更高路径条件和事实型升级触发条件。路径仅可为精简、标准或完整；文件数、模块数和推测性风险不能单独升级路径。
+
 ### 持久化报告证据
 
 生成分析报告时，先读取 `.agents/rules/evidence-reporting.md`。状态核对和成功检查记录命令、目标范围、状态/结构化结果、实际结果和未覆盖部分；失败、阻塞或争议才附决定性原文摘录。
@@ -64,7 +68,7 @@ agent-infra-internal task-event {task-id} analyze.started --agent {standard-agen
 
 ### 2. 解析分析上下文
 
-运行 `agent-infra-internal task-artifact {task-id} inspect --family analysis`。仅当结果为 `ready` 时继续；从 `next.round` / `next.name` 记录 `{analysis-round}` / `{analysis-artifact}`，从 `inputs` 读取修订上下文。不得自行扫描轮次或拼装文件名。随后执行 started 事件，并以事件返回的 `artifactContext` 复核同一身份。
+运行 `agent-infra-internal task-artifact {task-id} inspect --family analysis`。仅当结果为 `ready` 时继续。若 `selection.disposition` 为 `reuse`，复用 `selection.artifact`，不得执行 started、init 或写入新产物，并直接进入完成校验与下一步提示。其他状态从 `next.round` / `next.name` 记录 `{analysis-round}` / `{analysis-artifact}`，从 `inputs` 读取修订上下文；不得自行扫描轮次或拼装文件名。随后执行 started 事件，并以事件返回的 `artifactContext` 复核同一身份。
 
 ### 3. 阅读任务上下文
 
@@ -261,7 +265,10 @@ agent-infra-internal task-verify {task-id} analyze.completed --artifact {analysi
 > 渲染下一步前先读取 `.agents/rules/next-step-output.md`，仅为已选场景调用统一 helper，并将 stdout 填入 `{next-step-commands}`。
 
 输出格式：
-使用 `agent-infra-internal agent-client next-steps --skill review-analysis --task-ref {task-ref}` 生成本场景的 `{next-step-commands}`。
+按分析中的规范路径选择一条命令生成 `{next-step-commands}`：
+- 精简路径：`agent-infra-internal agent-client next-steps --skill code-task --task-ref {task-ref}`
+- 标准路径：`agent-infra-internal agent-client next-steps --skill plan-task --task-ref {task-ref}`
+- 完整路径：`agent-infra-internal agent-client next-steps --skill review-analysis --task-ref {task-ref}`
 
 ```
 任务 {task-id} 分析完成。
@@ -274,7 +281,7 @@ agent-infra-internal task-verify {task-id} analyze.completed --artifact {analysi
 产出文件：
 - 分析报告：.agents/workspace/active/{task-id}/{analysis-artifact}
 
-下一步 - 审查需求分析：
+下一步 - 按所选路径继续：
 {next-step-commands}
 ```
 
@@ -292,7 +299,7 @@ agent-infra-internal task-verify {task-id} analyze.completed --artifact {analysi
 
 ## 停止
 
-完成检查清单后，**立即停止**。等待用户审查分析结果并手动调用 `plan-task` 技能。
+完成检查清单后，**立即停止**。等待用户调用上述所选路径的下一阶段。
 
 ## 注意事项