@fitlab-ai/agent-infra 0.9.6 → 0.9.8

package/lib/task/review-finalization.ts

@@ -11,6 +11,8 @@ import { resolveTaskRef } from './resolve-ref.ts';
 import { validateLifecycleExecution } from './lifecycle-execution.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import type { ResolveTaskRefErrorCode } from './resolve-ref.ts';
+import { allowsManualOverride } from './guard-override.ts';
+import type { ManualOverrideCapability } from './guard-override.ts';
 
 type ReviewFinalizationErrorCode =
   | ResolveTaskRefErrorCode
@@ -62,6 +64,8 @@ type ReviewFinalizationOptions = {
   repoRoot?: string;
   randomSuffix?: () => string;
   fileSystem?: Partial<ReviewFileSystem>;
+  manualOverride?: ManualOverrideCapability;
+  lockAlreadyHeld?: boolean;
 };
 
 const STAGES: Record<ReviewStage, { family: 'review-analysis' | 'review-plan' | 'review-code'; action: string }> = {
@@ -127,7 +131,7 @@ function finalizeReviewSummaryUnlocked(
   }
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(request, resolved.code, resolved.message, resolved.taskId);
-  if (resolved.state !== 'active') {
+  if (resolved.state !== 'active' && !allowsManualOverride(options.manualOverride, 'review-finalization', 'TASK_STATE_MISMATCH')) {
     return failed(request, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   }
   const parsedArtifact = parseArtifactName(request.artifact);
@@ -275,7 +279,7 @@ function finalizeReviewSummary(
   request: ReviewFinalizationRequest,
   options: ReviewFinalizationOptions = {}
 ): ReviewFinalizationResult {
-  if (request.dryRun) return finalizeReviewSummaryUnlocked(request, options);
+  if (request.dryRun || options.lockAlreadyHeld) return finalizeReviewSummaryUnlocked(request, options);
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return finalizeReviewSummaryUnlocked(request, options);
   try {

package/lib/task/sections.ts

@@ -73,7 +73,7 @@ class DocumentMutationError extends Error {
 
 function parseTable(
   content: string,
-  input: { sectionAliases: readonly string[]; columns: readonly string[] }
+  input: { sectionAliases: readonly string[]; columns: readonly string[]; keyColumn?: string }
 ): ParsedTable | null {
   validateAliases(input.sectionAliases, 'table section aliases');
   if (
@@ -83,6 +83,10 @@ function parseTable(
   ) {
     throw new DocumentMutationError('MUTATION_INVALID', 'table columns are invalid');
   }
+  const keyColumn = input.keyColumn ?? input.columns[0]!;
+  if (!input.columns.includes(keyColumn)) {
+    throw new DocumentMutationError('MUTATION_INVALID', 'table key column is invalid');
+  }
   const sections = matchingSections(content, input.sectionAliases);
   if (sections.length === 0) return null;
   if (sections.length > 1) {
@@ -125,7 +129,7 @@ function parseTable(
       column,
       decodeCell(parsed.cells[columnIndex]!).trim()
     ]));
-    const key = values[input.columns[0]!]!;
+    const key = values[keyColumn]!;
     if (seen.has(key)) {
       throw new DocumentMutationError('TABLE_DUPLICATE_KEY', `duplicate table key '${key}'`);
     }

package/lib/task/task-execution-lock.ts

@@ -4,6 +4,7 @@ import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 
 import { getProcessStartTime, processIdentityMatches } from '../server/process-state.ts';
+import type { ProcessIdentity } from '../server/process-state.ts';
 
 type TaskExecutionLockErrorCode =
   | 'ORCHESTRATION_LOCK_BUSY'
@@ -11,9 +12,9 @@ type TaskExecutionLockErrorCode =
   | 'ORCHESTRATION_LOCK_FAILED';
 
 type TaskExecutionLockOwner = Readonly<{
-  version: 1;
+  version: 2;
   pid: number;
-  startTime: string;
+  startTime: number;
   token: string;
   owner: string;
   canonicalRepoRoot: string;
@@ -28,8 +29,8 @@ type TaskExecutionLockOptions = Readonly<{
   lockRoot?: string;
   token?: () => string;
   now?: () => string;
-  getStartTime?: (pid: number) => string | null;
-  identityMatches?: (record: { version: 1; pid: number; startTime: string }) => boolean;
+  getStartTime?: (pid: number) => number | null;
+  identityMatches?: (identity: ProcessIdentity) => boolean;
   linkSync?: (existingPath: string, newPath: string) => void;
 }>;
 
@@ -84,11 +85,12 @@ function parseOwner(raw: string, key: string): TaskExecutionLockOwner {
     const value = JSON.parse(raw) as Partial<TaskExecutionLockOwner> | null;
     if (
       value !== null
-      && value.version === 1
+      && value.version === 2
       && Number.isSafeInteger(value.pid)
       && (value.pid ?? 0) > 0
-      && typeof value.startTime === 'string'
-      && value.startTime.length > 0
+      && typeof value.startTime === 'number'
+      && Number.isSafeInteger(value.startTime)
+      && value.startTime >= 0
       && typeof value.token === 'string'
       && value.token.length > 0
       && typeof value.owner === 'string'
@@ -164,7 +166,7 @@ function reclaimStaleLock(
 function cleanStaleCandidates(
   lockRoot: string,
   key: string,
-  identityMatches: (record: { version: 1; pid: number; startTime: string }) => boolean
+  identityMatches: (identity: ProcessIdentity) => boolean
 ): void {
   const prefix = `${key}.candidate.`;
   for (const name of fs.readdirSync(lockRoot)) {
@@ -211,7 +213,7 @@ function withTaskExecutionLock<T>(
     );
   }
   const owner: TaskExecutionLockOwner = {
-    version: 1,
+    version: 2,
     pid: process.pid,
     startTime,
     token,

package/lib/task/verification-engine.ts

@@ -23,6 +23,7 @@ import { resolveReviewedHeadRelation } from "../platform/merged-pr-equivalence.t
 import { resolveLocalReviewedCommitRelation } from "../git/reviewed-commit-equivalence.ts";
 import { parseTypedTaskFrontmatter } from "./frontmatter.ts";
 import { parseLedger, summarizeLedgerStage, validateLedgerRows } from "./ledger.ts";
+import type { LedgerRow } from "./ledger.ts";
 import { equalCounts, parseReviewSummary } from "./review-artifacts.ts";
 import { loadVerificationConfig } from "./verification-config.ts";
 import { snapshotReview } from "../git/review-snapshot.ts";
@@ -173,7 +174,7 @@ function checkOrchestrationState({ taskDir }: any): any {
   if (isFailClosedLegacyPause(run)) {
     return passResult('orchestration-state', 'Legacy orchestration run is safely paused');
   }
-  if (run.schemaVersion !== 2 || !['paused', 'completed'].includes(run.status)) {
+  if (![2, 3].includes(run.schemaVersion) || !['paused', 'completed'].includes(run.status)) {
     return failResult('orchestration-state', `Expected paused or completed run, received '${run.status}'`);
   }
   if (run.status === 'paused' && (!run.pause?.code || !run.pause?.message)) {
@@ -290,7 +291,22 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
       && guards?.commitAuthorizationUnused === true
       && guards?.completionEvidenceAbsent === true
       && guards?.commitIntentAbsent === true;
-    if (!validModelRecovery && !validCapabilityRecovery) {
+    const validClaudeCodeRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED_NO_MIGRATION'
+      && recovery.previousSchemaVersion === 3
+      && recovery.previousStatus === 'paused'
+      && recovery.previousPause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
+      && recovery.client === 'claude-code'
+      && recovery.resultingStatus === 'running'
+      && exactText(recovery.recoveredAt)
+      && guards?.stepCount === 0
+      && guards?.nextStage === null
+      && guards?.baselineEmpty === true
+      && guards?.receiptCount === 0
+      && guards?.pendingDelegation === false
+      && guards?.commitAuthorizationUnused === true
+      && guards?.completionEvidenceAbsent === true
+      && guards?.commitIntentAbsent === true;
+    if (!validModelRecovery && !validCapabilityRecovery && !validClaudeCodeRecovery) {
       return failResult('orchestration-evidence', 'Run recovery history contains invalid provenance');
     }
   }
@@ -321,29 +337,40 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
     }
     const activated = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
     if (activated) {
-      if (!exactText(receipt.actualModel)) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+      const isClaudeCode = receipt.client === 'claude-code';
+      if (!isClaudeCode) {
+        if (!exactText(receipt.actualModel)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual model`);
+        }
+        if (!exactText(receipt.actualReasoningEffort)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+        }
       }
-      if (!exactText(receipt.actualReasoningEffort)) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has no host-observed actual reasoning effort`);
+      // parentId/childId 校验对所有 client 保持统一（不新增分支）；spawnMode 检查按 client 判断
+      if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId) {
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid delegation identity`);
       }
-      if (!exactText(receipt.parentId) || !exactText(receipt.childId) || receipt.parentId === receipt.childId || receipt.spawnMode !== 'fresh') {
+      if (!isClaudeCode && receipt.spawnMode !== 'fresh') {
         return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid fresh delegation identity`);
       }
-      if (receipt.actualModel !== receipt.requestedModel && !exactText(receipt.modelFallbackReason)) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
-      }
-      if (receipt.actualModel === receipt.requestedModel && receipt.modelFallbackReason !== null) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
+      if (receipt.actualModel != null && receipt.actualModel !== receipt.requestedModel) {
+        if (!isClaudeCode && !exactText(receipt.modelFallbackReason)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' model fallback is not justified`);
+        }
       }
       if (
-        receipt.actualReasoningEffort !== receipt.requestedReasoningEffort
-        && !exactText(receipt.reasoningEffortFallbackReason)
+        (receipt.actualModel == null || receipt.actualModel === receipt.requestedModel)
+        && receipt.modelFallbackReason !== null
       ) {
-        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+        return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated model fallback reason`);
+      }
+      if (receipt.actualReasoningEffort != null && receipt.actualReasoningEffort !== receipt.requestedReasoningEffort) {
+        if (!isClaudeCode && !exactText(receipt.reasoningEffortFallbackReason)) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' reasoning-effort fallback is not justified`);
+        }
       }
       if (
-        receipt.actualReasoningEffort === receipt.requestedReasoningEffort
+        (receipt.actualReasoningEffort == null || receipt.actualReasoningEffort === receipt.requestedReasoningEffort)
         && receipt.reasoningEffortFallbackReason !== null
       ) {
         return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated reasoning-effort fallback reason`);
@@ -901,7 +928,7 @@ function checkReviewLedger({ taskDir, config }: any): any {
   }
 
   const stageScope = Array.isArray(config.stage_scope) ? config.stage_scope : null;
-  const maxRounds = Number(resolveReviewSetting(config, "max_handshake_rounds", DEFAULT_MAX_HANDSHAKE_ROUNDS));
+  const maxRounds = Number(resolveReviewSetting(config, "maxHandshakeRounds", DEFAULT_MAX_HANDSHAKE_ROUNDS));
   const problems = [];
   let inScopeCount = 0;
 
@@ -1070,11 +1097,13 @@ function checkPostReviewCommit({ taskDir, config }: any): any {
         return blockedResult("post-review-commit", relation.message, relation.code);
       }
       if (relation.status === "strict") {
-        return failResult(
-          "post-review-commit",
-          "Merged PR evidence did not establish squash merge equivalence",
-          "PR_MERGE_IDENTITY_INVALID"
-        );
+        return resolvePostReviewIdentityFailure(task.content, {
+          code: "PR_MERGE_IDENTITY_INVALID",
+          message: "Merged PR evidence did not establish squash merge equivalence"
+        });
+      }
+      if (relation.code === "PR_MERGE_IDENTITY_INVALID") {
+        return resolvePostReviewIdentityFailure(task.content, relation);
       }
       return failResult("post-review-commit", relation.message, relation.code);
     }
@@ -1144,11 +1173,11 @@ function checkPostReviewCommit({ taskDir, config }: any): any {
   }
 
   const exemption = resolvePostReviewExemption(task.content);
-  if (!exemption.ok) return failResult("post-review-commit", exemption.message);
-  if (exemption.exempt) {
+  if (!exemption.ok) return failResult("post-review-commit", exemption.message, exemption.code);
+  if (exemption.exemptions.length > 0) {
     return passResult(
       "post-review-commit",
-      `${commits.length} post-review commit(s) covered by a human-decided exemption`
+      `${commits.length} post-review commit(s) covered by a human-decided exemption: ${formatPostReviewExemptions(exemption.exemptions)}`
     );
   }
 
@@ -1158,18 +1187,50 @@ function checkPostReviewCommit({ taskDir, config }: any): any {
   );
 }
 
+function resolvePostReviewIdentityFailure(
+  content: string,
+  failure: { code: string; message: string }
+): any {
+  const exemption = resolvePostReviewExemption(content);
+  if (!exemption.ok) {
+    return failResult("post-review-commit", exemption.message, exemption.code);
+  }
+  if (exemption.exemptions.length === 0) {
+    return failResult("post-review-commit", failure.message, failure.code);
+  }
+  return passResult(
+    "post-review-commit",
+    `Human-decided post-review exemption overrode ${failure.code}: ${failure.message}; ${formatPostReviewExemptions(exemption.exemptions)}`
+  );
+}
+
+function formatPostReviewExemptions(exemptions: readonly LedgerRow[]): string {
+  return exemptions.map((row) => `${row.id}: ${row.evidence}`).join("; ");
+}
+
 function resolvePostReviewExemption(content: string):
-  | { ok: true; exempt: boolean }
-  | { ok: false; message: string } {
+  | { ok: true; exemptions: readonly LedgerRow[] }
+  | { ok: false; code: "POST_REVIEW_EXEMPTION_INVALID"; message: string } {
   try {
+    const rows = parseLedger(content);
+    const invalid = validateLedgerRows(rows);
+    if (invalid) {
+      return {
+        ok: false,
+        code: "POST_REVIEW_EXEMPTION_INVALID",
+        message: `${invalid.code}: ${invalid.message}`
+      };
+    }
     return {
       ok: true,
-      exempt: parseLedger(content).some(
-        (row) => row.stage === POST_REVIEW_COMMIT_STAGE && row.status === "human-decided"
-      )
+      exemptions: rows.filter((row) => row.stage === POST_REVIEW_COMMIT_STAGE)
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      code: "POST_REVIEW_EXEMPTION_INVALID",
+      message: `Invalid disagreement ledger: ${error instanceof Error ? error.message : String(error)}`
     };
-  } catch {
-    return { ok: false, message: "Invalid disagreement ledger" };
   }
 }
 

package/lib/task/verification.ts

@@ -7,6 +7,8 @@ import { parseArtifactName } from './artifact-lifecycle.ts';
 import type { ArtifactFamily } from './artifact-lifecycle.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import type { TaskWorkspaceState } from './resolve-ref.ts';
+import { allowsManualOverride } from './guard-override.ts';
+import type { ManualOverrideCapability } from './guard-override.ts';
 
 type VerificationEvent =
   | 'analyze.awaiting-input' | 'analyze.completed'
@@ -48,6 +50,7 @@ type TaskVerificationResult = {
 type VerificationOptions = {
   repoRoot?: string;
   engine?: typeof verifyInProcess;
+  manualOverride?: ManualOverrideCapability;
 };
 
 const gate = (skill: string, expectedState: VerificationSpec['expectedState'], artifactFamily?: ArtifactFamily): VerificationSpec => ({
@@ -93,7 +96,7 @@ function verifyTaskEvent(request: { taskRef: string; event: string; artifact?: s
   const resolved = resolveTaskRef(request.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failure(request, resolved.code, resolved.message, { taskId: resolved.taskId, skill: spec.skill, mode: spec.mode });
   const identity = { taskId: resolved.taskId, taskDir: resolved.taskDir, taskState: resolved.state, skill: spec.skill, mode: spec.mode } as const;
-  if (resolved.state !== spec.expectedState) {
+  if (resolved.state !== spec.expectedState && !allowsManualOverride(options.manualOverride, 'task-verify', 'VERIFY_TASK_STATE_MISMATCH')) {
     return failure(request, 'VERIFY_TASK_STATE_MISMATCH', `event '${request.event}' requires workspace '${spec.expectedState}', received '${resolved.state}'`, identity);
   }
   if (spec.artifactFamily) {
@@ -111,11 +114,22 @@ function verifyTaskEvent(request: { taskRef: string; event: string; artifact?: s
   if (spec.mode === 'gate') {
     const payload = engine({ mode: 'gate', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [], repositoryRoot: resolved.repoRoot }) as Record<string, unknown>;
     const status = payload.gate as 'pass' | 'fail' | 'blocked';
+    if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
+      invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, gate: 'pass', humanOverride: 'human-approved', originalGate: status } });
+      return {
+        status: 'pass', changed: false, event: request.event, requestRef: request.taskRef,
+        ...identity, artifact: request.artifact ?? null, invocations, error: null
+      };
+    }
     invocations.push({ status, exitCode: ({ pass: 0, fail: 1, blocked: 2 } as const)[status], payload });
   } else {
     for (const check of spec.checks ?? []) {
       const payload = engine({ mode: 'checks', skillName: spec.skill, taskDir: resolved.taskDir, artifactFile: request.artifact, checks: [check], repositoryRoot: resolved.repoRoot }) as Record<string, unknown>;
       const status = payload.status as 'pass' | 'fail' | 'blocked';
+      if (status !== 'pass' && allowsManualOverride(options.manualOverride, 'verification-engine', status === 'blocked' ? 'CHECK_BLOCKED' : 'CHECK_FAILED')) {
+        invocations.push({ status: 'pass', exitCode: 0, payload: { ...payload, status: 'pass', humanOverride: 'human-approved', originalStatus: status } });
+        break;
+      }
       invocations.push({ status, exitCode: ({ pass: 0, fail: 1, blocked: 2 } as const)[status], payload });
       if (status !== 'pass') break;
     }

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

@@ -11,6 +11,7 @@ import {
 import type { WorkflowWarning } from './workflow-warnings.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
+import { allowsManualOverride } from './guard-override.ts';
 
 type WarningSeverity = 'IMPORTANT' | 'ACTION_REQUIRED';
 type WarningStatus = 'open' | 'resolved' | 'ignored';
@@ -79,7 +80,8 @@ function rowMutation(row: WorkflowWarning): TaskMutation {
 function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: TaskWriteOptions = {}): WorkflowWarningIntentResult {
   const resolved = resolveTaskRef(intent.taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(intent, resolved.code, resolved.message, resolved.taskId);
-  if (resolved.state !== 'active') return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
+  const stateOverride = allowsManualOverride(options.manualOverride, 'workflow-warning', 'TASK_STATE_MISMATCH');
+  if (resolved.state !== 'active' && !stateOverride) return failed(intent, 'TASK_STATE_MISMATCH', `task ${resolved.taskId} is ${resolved.state}, expected active`, resolved.taskId);
   let content: string;
   let rows: WorkflowWarning[];
   try {
@@ -125,7 +127,7 @@ function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: Task
   }
 
   const writeResult = writeTask({
-    taskRef: intent.taskRef, expectedState: 'active', mutations: [...sectionMutation(content), rowMutation(after)], dryRun: intent.dryRun
+    taskRef: intent.taskRef, expectedState: stateOverride ? resolved.state : 'active', mutations: [...sectionMutation(content), rowMutation(after)], dryRun: intent.dryRun
   }, {
     ...options,
     taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: resolved.state },

package/lib/task/write.ts

@@ -12,6 +12,8 @@ import type {
   ResolveTaskRefErrorCode,
   TaskWorkspaceState
 } from './resolve-ref.ts';
+import { allowsManualOverride } from './guard-override.ts';
+import type { ManualOverrideCapability } from './guard-override.ts';
 import { mutateTableRow, upsertSection } from './sections.ts';
 import type {
   TableRowDeleteMutation,
@@ -156,6 +158,7 @@ type TaskWriteOptions = {
   metadataProvider?: () => TaskWriteMetadata;
   randomSuffix?: () => string;
   fileSystem?: Partial<TaskFileSystem>;
+  manualOverride?: ManualOverrideCapability;
 };
 
 const DEFAULT_FILE_SYSTEM: TaskFileSystem = {
@@ -241,7 +244,7 @@ function writeTask(request: TaskWriteRequest, options: TaskWriteOptions = {}): T
     taskMdPath: resolved.taskMdPath,
     actualState: resolved.state
   };
-  if (resolved.state !== request.expectedState) {
+  if (resolved.state !== request.expectedState && !allowsManualOverride(options.manualOverride, 'task.write', 'TASK_STATE_MISMATCH')) {
     return failure(
       request,
       identity,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.6",
+  "version": "0.9.8",
   "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/README.en.md

@@ -47,6 +47,13 @@ This dual-config approach ensures every AI tool receives appropriate project con
   settings.json                 # Claude settings
 ```
 
+The whole `.agents/workspace/` tree is runtime-only and git-ignored. `active/`
+contains current tasks, `blocked/` contains paused tasks, `completed/` contains
+finished tasks, and `archive/` stores archived history. Runtime logs and process
+evidence may also be created below this root. Do not place content here that must
+be shared through Git; collaboration rules, templates, and workflows belong in
+the version-controlled `.agents/` tree.
+
 ## Collaboration Model
 
 The multi-AI collaboration follows a structured workflow:

package/templates/.agents/README.zh-CN.md

@@ -47,6 +47,11 @@
   settings.json                 # Claude 设置
 ```
 
+整个 `.agents/workspace/` 目录树都只保存运行时数据，并被 git ignore。`active/`
+保存当前任务，`blocked/` 保存暂停任务，`completed/` 保存已完成任务，`archive/`
+保存归档历史；运行时日志和过程证据也可能出现在该根目录下。不要在这里存放必须
+通过 Git 共享的内容；协作规则、模板和工作流应放在受版本控制的 `.agents/` 目录中。
+
 ## 协作模型
 
 多 AI 协作遵循结构化工作流：

package/templates/.agents/hooks/lifecycle-delegation.js

@@ -36,6 +36,28 @@ function internalCliInvocation(args) {
   return { command: 'agent-infra-internal', commandArgs: args, shell: process.platform === 'win32' };
 }
 
+function findCapabilityToken(value, depth = 0) {
+  if (depth > 5 || value == null) return '';
+  if (typeof value === 'string') {
+    const match = /agent-infra-codex-capability:([A-Za-z0-9_-]{20,})/.exec(value);
+    return match?.[1] || '';
+  }
+  if (Array.isArray(value)) {
+    for (const entry of value) {
+      const found = findCapabilityToken(entry, depth + 1);
+      if (found) return found;
+    }
+    return '';
+  }
+  if (typeof value === 'object') {
+    for (const entry of Object.values(value)) {
+      const found = findCapabilityToken(entry, depth + 1);
+      if (found) return found;
+    }
+  }
+  return '';
+}
+
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => {
@@ -75,10 +97,11 @@ process.stdin.on('end', () => {
       process.exit(1);
     }
     const managedAgent = /^agent-infra-lifecycle-(executor|reviewer)$/.test(String(nativeAgent || ''));
+    const capabilityToken = hook === 'post-tool' ? findCapabilityToken(toolResponse) : '';
     const parentReconcile = hook === 'post-tool'
       && toolName === 'collaborationwait_agent'
       && toolResponse.timed_out !== true;
-    if (!managedAgent && !parentReconcile) process.exit(0);
+    if (!managedAgent && !parentReconcile && !capabilityToken) process.exit(0);
     const hookDefinitionHash = createHash('sha256').update(readFileSync(codexHooks)).digest('hex');
     const normalized = {
       sessionId: String(event.session_id || ''),
@@ -93,6 +116,7 @@ process.stdin.on('end', () => {
       taskName: String(toolInput.task_name || ''),
       transcriptPath: String(event.transcript_path || '')
     };
+    if (capabilityToken) normalized.capabilityToken = capabilityToken;
     const args = ['codex-lifecycle', 'hook-event', '--event', hook, '--bridge', 'true'];
     try {
       const { command, commandArgs, shell } = internalCliInvocation(args);
@@ -123,11 +147,11 @@ process.stdin.on('end', () => {
     args.push(
       '--native-agent', String(nativeAgent),
       '--child-id', String(event.child_id || event.agent_id || event.thread_id || ''),
-      '--parent-id', String(event.parent_id || event.parent_session_id || event.session_id || ''),
-      '--spawn-mode', String(event.spawn_mode || (client === 'claude-code' ? 'fresh' : ''))
+      '--parent-id', String(event.parent_id || event.parent_session_id || event.session_id || '')
     );
+    if (event.spawn_mode) args.push('--spawn-mode', String(event.spawn_mode));
     if (event.model) args.push('--actual-model', String(event.model));
-    const actualEffort = event.actual_reasoning_effort || event.reasoning_effort || event.model_reasoning_effort;
+    const actualEffort = event.effort?.level || event.actual_reasoning_effort || event.reasoning_effort || event.model_reasoning_effort;
     if (actualEffort) args.push('--actual-reasoning-effort', String(actualEffort));
     if (event.model_fallback_reason) args.push('--model-fallback-reason', String(event.model_fallback_reason));
     if (event.reasoning_effort_fallback_reason) {
@@ -138,6 +162,11 @@ process.stdin.on('end', () => {
       '--native-agent', String(nativeAgent),
       '--child-id', String(event.child_id || event.agent_id || event.thread_id || '')
     );
+    if (client === 'claude-code') {
+      if (event.model) args.push('--actual-model', String(event.model));
+      const actualEffort = event.effort?.level || event.actual_reasoning_effort || event.reasoning_effort;
+      if (actualEffort) args.push('--actual-reasoning-effort', String(actualEffort));
+    }
   }
   try {
     const { command, commandArgs, shell } = internalCliInvocation(args);

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

@@ -5,19 +5,26 @@
 - The orchestrator only routes and delegates. Stage skills remain the single source of truth for behavior and artifacts.
 - Every stage and rework round uses a fresh executor. Every review uses a fresh reviewer; follow-up reuse is forbidden.
 - A reviewer may only write its review artifact and core-generated task metadata. Business-code, HEAD, or index changes invalidate the receipt.
-- An active run has one pending delegation. Missing, mismatched, forked, replayed, hook-less, or drifted evidence pauses the run.
+- An active run has one pending delegation. The child must pass the activation barrier before any stage side effect. Missing, late, mismatched, forked, replayed, hook-less, or drifted evidence pauses the run (on the claude-code path, missing or mismatched model/effort evidence, and fork/spawn-mode evidence this host structurally does not provide, follow the recording rules in `.agents/skills/run-task/reference/host-validation.md` instead and are exempt from this; missing or mismatched `parentId`/`childId` still pauses).
 - The first release ends after one existing safely gated `commit`; it does not create a PR, monitor checks, or complete the task.
 
 ## Recovery
 
-`orchestration.json` is the detailed state source. A v2 run persists complete policy, source, and append-only recovery history. Only a v1 run with no pending delegation and zero receipts may be upgraded in place after supplying a complete policy; any historical receipt stays paused because effort is unverifiable. A historical Codex `ORCHESTRATION_CLIENT_UNSUPPORTED` v2 pause appends `CLIENT_CAPABILITY_ENABLED` and resumes only when step count, next stage, baseline, receipts, pending delegation, commit authorization, completion evidence, and commit intent all prove that execution never advanced; unknown or non-empty evidence preserves the pause. Migration is forward-only: old binaries must not advance active v2 runs.
+`orchestration.json` is the detailed state source. A v3 run persists complete policy, append-only recovery, build/contract/hook-source/controller provenance, and activation monotonic timestamps. Historical v2 state is read-compatible, but new Codex delegations require v3. An expired prepared orphan may be explicitly recovered only with the exact task fingerprint, no commit intent or consumed authorization, and no matching unconsumed active lifecycle evidence. Unknown schemas and incomplete active v3 state fail closed.
+
+## Codex Host and Capability
+
+- Direct-host accepts only trusted project or managed lifecycle hooks. A task-bound sandbox requires a controlled nested controller and isolated `CODEX_HOME`; only user hooks bound to that controller context are accepted. Ordinary user/plugin hooks are not evidence.
+- The controller starts a nested loop only after control generation, task binding, Codex version, closed bundle, build/contract manifest, profiles, and hook discovery pass. Both bypass flags are restricted to this task-bound launch path.
+- Every prepare arms a one-use capability attested by the current loop's real PostToolUse. Atomic consumption binds task/session/build/controller and retains only a redacted tombstone.
 
 ## 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, and requested values must never be fabricated as actual evidence.
+- 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.
 - 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.
 
 ## Stable Pause Conditions
 

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

@@ -5,19 +5,26 @@
 - 总控只路由和委派；阶段技能仍是业务规则与产物格式的单一事实源。
 - 每个阶段和每轮返工都创建 fresh executor；每轮审查创建 fresh reviewer，禁止 follow-up 复用。
 - reviewer 只能写当前审查产物和核心生成的任务元数据。业务代码、HEAD 或暂存区变化会使 receipt 失效。
-- active run 中只有一个 pending delegation。缺失、错配、fork、重放、hook 不可用或工作区漂移一律暂停。
+- active run 中只有一个 pending delegation。child 必须在任何阶段副作用前通过 activation barrier；缺失、超时、错配、fork、重放、hook 不可用或工作区漂移一律暂停（claude-code 路径下 model/effort 证据的缺失或错配、以及该宿主结构上不提供的 fork/spawn-mode 证据，按 `.agents/skills/run-task/reference/host-validation.md` 的记录规则处理，不在此列；`parentId`/`childId` 的缺失或错配仍然暂停）。
 - 首版成功终点是一次通过既有安全门禁的 `commit`；不创建 PR、不监控 checks、不执行 `complete-task`。
 
 ## 恢复语义
 
-`orchestration.json` 是详细状态源。v2 run 保存完整策略、来源与 append-only 恢复历史。只有无 pending delegation 且零历史 receipt 的 v1 run 可在补齐完整策略后原地升级；任一历史 receipt 因缺 effort 证据保持暂停。Codex 的历史 `ORCHESTRATION_CLIENT_UNSUPPORTED` v2 pause 仅在 stepCount、nextStage、baseline、receipts、pending delegation、commit authorization、completion evidence 与 commit intent 全部证明从未推进时追加 `CLIENT_CAPABILITY_ENABLED` 并恢复；任一未知或非空证据保持原暂停。迁移是 forward-only，旧二进制不得推进 v2 active run。
+`orchestration.json` 是详细状态源。v3 run 保存完整策略、append-only 恢复历史、build/contract/hook source/controller provenance 与 activation 单调时钟。只有无 pending delegation 且零历史 receipt 的 v1 run 可在补齐完整策略后升级；历史 v2 状态仅兼容读取，新的 Codex delegation 必须写 v3。prepared orphan 只允许在 deadline 已过、task fingerprint 精确不变、无 commit intent/authorization 消耗且无匹配的未消费 active lifecycle evidence 时显式恢复。迁移是 forward-only，未知 schema 或缺 provenance 的 active v3 一律失败关闭。
+
+## Codex 宿主与 capability
+
+- direct-host 只接受 trusted project 或 managed lifecycle hooks。task-bound sandbox 必须由受控 nested controller 建立隔离 `CODEX_HOME`，仅接受绑定 controller context 的 user hooks；普通 user/plugin hook 不得成为证据源。
+- controller 只有在 control generation、task binding、Codex 版本、closed bundle、build/contract manifest、profile 与 hook discovery 全部通过后才能启动 nested loop。两个 bypass 参数只允许出现在该 task-bound 启动路径。
+- 每次 prepare 前必须 arm 一次性 capability，并由同一当前 loop 的真实 PostToolUse attestation；token 原子消费后保留去敏 tombstone，不能重放或跨 task/session/build/controller 使用。
 
 ## 模型策略
 
 - 新 run 必须固化 executor/reviewer 各自的 model 与 reasoning effort；显式策略必须四字段原子完整，完全没有显式字段时才读取当前 client 的 `agentClients[].orchestration`。重入不得静默改写策略。
 - route 按 role 返回 requested model/effort，prepare 必须在工作区快照前精确匹配两者；原生 spawn 不能继承会话默认值。
-- 原生 start 必须记录宿主观察到的 actual model/effort。任一字段与 requested 不同时必须记录独立 fallback reason；requested 值不得补造 actual 证据。
+- 原生 start 必须记录宿主观察到的 actual model/effort。任一字段与 requested 不同时必须记录独立 fallback reason（claude-code 路径下允许留空，按记录规则处理）；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/pr-checks-commands.github.en.md

@@ -1,6 +1,6 @@
 # GitHub PR Readiness Intents
 
-The GitHub adapter requires `gh >= 2.16.0`. Platform context checks this dependency before any GitHub API, PR, or checks operation. Projects that do not select GitHub neither probe nor depend on `gh`.
+The GitHub adapter requires `gh >= 2.72.0`. Platform context checks this dependency before any GitHub API, PR, or checks operation. Projects that do not select GitHub neither probe nor depend on `gh`.
 
 ```bash
 agent-infra-internal platform-checks inspect {task-id}

package/templates/.agents/rules/pr-checks-commands.github.zh-CN.md

@@ -2,7 +2,7 @@
 
 PR 全部 checks 的获取、轮询 deadline、失败 run/job 定位和日志获取统一由 typed internal intent 执行。SKILL/模型只负责失败分类、根因分析、最小修复和授权后的提交推送。
 
-GitHub adapter 要求 `gh >= 2.16.0`。平台上下文会在任何 GitHub API、PR 或 checks 操作前检查该依赖；未选择 GitHub 平台时不探测也不依赖 `gh`。
+GitHub adapter 要求 `gh >= 2.72.0`。平台上下文会在任何 GitHub API、PR 或 checks 操作前检查该依赖；未选择 GitHub 平台时不探测也不依赖 `gh`。
 
 ## 快照与监控