@fitlab-ai/agent-infra 0.9.5 → 0.9.7

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)) {
@@ -268,14 +269,29 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
     return failResult('orchestration-evidence', 'Run model policy source or recovery history is invalid');
   }
   for (const recovery of run.recoveryHistory) {
-    if (
-      recovery.code !== 'MODEL_POLICY_SUPPLEMENTED'
-      || recovery.previousSchemaVersion !== 1
-      || recovery.receiptCount !== 0
-      || recovery.pendingDelegation !== false
-      || !exactText(recovery.recoveredAt)
-      || !recovery.policySource
-    ) {
+    const validModelRecovery = recovery.code === 'MODEL_POLICY_SUPPLEMENTED'
+      && recovery.previousSchemaVersion === 1
+      && recovery.receiptCount === 0
+      && recovery.pendingDelegation === false
+      && exactText(recovery.recoveredAt)
+      && recovery.policySource;
+    const guards = recovery.guards;
+    const validCapabilityRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED'
+      && recovery.previousSchemaVersion === 2
+      && recovery.previousStatus === 'paused'
+      && recovery.previousPause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
+      && recovery.client === 'codex'
+      && 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) {
       return failResult('orchestration-evidence', 'Run recovery history contains invalid provenance');
     }
   }
@@ -333,6 +349,25 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
       ) {
         return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has an unrelated reasoning-effort fallback reason`);
       }
+      if (receipt.client === 'codex') {
+        const host = receipt.hostEvidence;
+        if (
+          host?.kind !== 'codex-lifecycle-v1'
+          || !exactText(host.hookDefinitionHash)
+          || !Number.isSafeInteger(host.startRevision)
+          || host.startRevision < 1
+        ) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid Codex start evidence`);
+        }
+        if (['sealed', 'consumed'].includes(receipt.status) && (
+          !Number.isSafeInteger(host.stopRevision)
+          || host.stopRevision <= host.startRevision
+          || host.consumer !== receipt.id
+          || !exactText(host.consumedAt)
+        )) {
+          return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid Codex consumed stop evidence`);
+        }
+      }
     }
   }
   if (run.receipts.some((receipt: any) => receipt.status !== 'consumed')) {
@@ -1036,11 +1071,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);
     }
@@ -1110,11 +1147,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)}`
     );
   }
 
@@ -1124,18 +1161,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

@@ -11,7 +11,7 @@ import type { TaskWorkspaceState } from './resolve-ref.ts';
 type VerificationEvent =
   | 'analyze.awaiting-input' | 'analyze.completed'
   | 'review-analysis.completed' | 'plan.completed' | 'review-plan.completed'
-  | 'code.completed' | 'review-code.completed' | 'manual-validation.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.completed'
   | 'create-pr.completed' | 'create-task.completed'
@@ -62,6 +62,7 @@ const VERIFICATION_CATALOG: Readonly<Record<VerificationEvent, VerificationSpec>
   'code.completed': gate('code-task', 'active', 'code'),
   'review-code.completed': gate('review-code', 'active', 'review-code'),
   'manual-validation.completed': gate('complete-manual-validation', 'active', 'manual-validation'),
+  'validation-run.completed': gate('run-manual-validation', 'active', 'validation-run'),
   'block-task.completed': gate('block-task', 'blocked'),
   'cancel-task.completed': gate('cancel-task', 'completed'),
   'commit.completed': gate('commit', 'active'),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.5",
+  "version": "0.9.7",
   "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

@@ -5,6 +5,8 @@ import { readFileSync } from 'node:fs';
 import { fileURLToPath } from 'node:url';
 
 const MAX_INPUT_BYTES = 64 * 1024;
+const repoPackageJson = fileURLToPath(new URL('../../package.json', import.meta.url));
+const sourceInternalCli = fileURLToPath(new URL('../../bin/internal-cli.ts', import.meta.url));
 const localInternalCli = fileURLToPath(new URL('../../dist/bin/internal-cli.js', import.meta.url));
 const codexHooks = fileURLToPath(new URL('../../.codex/hooks.json', import.meta.url));
 const clientIndex = process.argv.indexOf('--client');
@@ -13,6 +15,49 @@ if (client !== 'claude-code' && client !== 'codex') {
   process.stderr.write('Lifecycle delegation hook requires a supported --client value\n');
   process.exit(1);
 }
+
+function internalCliInvocation(args) {
+  let isAgentInfraSourceCheckout = false;
+  try {
+    isAgentInfraSourceCheckout = JSON.parse(readFileSync(repoPackageJson, 'utf8')).name === '@fitlab-ai/agent-infra';
+  } catch {
+    // Installed project hooks do not require a repository package.json.
+  }
+  if (isAgentInfraSourceCheckout && existsSync(sourceInternalCli)) {
+    return {
+      command: process.execPath,
+      commandArgs: ['--experimental-strip-types', sourceInternalCli, ...args],
+      shell: false
+    };
+  }
+  if (existsSync(localInternalCli)) {
+    return { command: process.execPath, commandArgs: [localInternalCli, ...args], shell: false };
+  }
+  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) => {
@@ -34,15 +79,29 @@ process.stdin.on('end', () => {
   const explicitPhase = phaseIndex >= 0 ? process.argv[phaseIndex + 1] : '';
   const hook = String(explicitPhase || event.hook_event_name || event.event || '').toLowerCase();
   const toolInput = event.tool_input && typeof event.tool_input === 'object' ? event.tool_input : {};
+  const toolName = String(event.tool_name || event.tool || '').toLowerCase();
+  let toolResponse = {};
+  try {
+    toolResponse = typeof event.tool_response === 'string'
+      ? JSON.parse(event.tool_response)
+      : (event.tool_response || {});
+  } catch {
+    // Core ignores opaque tool responses; only the host timeout bit is forwarded.
+  }
   const nativeAgent = event.agent_name || event.agent_type || event.agent?.name
     || toolInput.agent_type || toolInput.agent || toolInput.name;
-  if (!String(nativeAgent || '').startsWith('agent-infra-lifecycle-')) process.exit(0);
   if (client === 'codex') {
     const phases = new Set(['pre-tool', 'subagent-start', 'post-tool', 'subagent-stop']);
     if (!phases.has(hook)) {
       process.stderr.write('Managed Codex lifecycle hook event has an unknown type\n');
       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 && !capabilityToken) process.exit(0);
     const hookDefinitionHash = createHash('sha256').update(readFileSync(codexHooks)).digest('hex');
     const normalized = {
       sessionId: String(event.session_id || ''),
@@ -52,19 +111,21 @@ process.stdin.on('end', () => {
       nativeAgent: String(nativeAgent),
       requestedModel: String(toolInput.model || ''),
       requestedReasoningEffort: String(toolInput.reasoning_effort || toolInput.reasoningEffort || ''),
-      hookDefinitionHash
+      hookDefinitionHash,
+      toolName,
+      taskName: String(toolInput.task_name || ''),
+      transcriptPath: String(event.transcript_path || '')
     };
-    const args = ['codex-lifecycle', 'hook-event', '--event', hook];
+    if (capabilityToken) normalized.capabilityToken = capabilityToken;
+    const args = ['codex-lifecycle', 'hook-event', '--event', hook, '--bridge', 'true'];
     try {
-      const useLocal = existsSync(localInternalCli);
-      const command = useLocal ? process.execPath : 'agent-infra-internal';
-      const commandArgs = useLocal ? [localInternalCli, ...args] : args;
+      const { command, commandArgs, shell } = internalCliInvocation(args);
       const output = execFileSync(command, commandArgs, {
         encoding: 'utf8',
         input: JSON.stringify(normalized),
-        shell: !useLocal && process.platform === 'win32',
+        shell,
         stdio: ['pipe', 'pipe', 'pipe'],
-        timeout: 5_000
+        timeout: 15_000
       });
       process.stdout.write(output);
     } catch (error) {
@@ -74,6 +135,7 @@ process.stdin.on('end', () => {
     }
     return;
   }
+  if (!/^agent-infra-lifecycle-(executor|reviewer)$/.test(String(nativeAgent || ''))) process.exit(0);
   const start = hook.includes('start');
   const stop = hook.includes('stop');
   if (!start && !stop) {
@@ -102,12 +164,10 @@ process.stdin.on('end', () => {
     );
   }
   try {
-    const useLocal = existsSync(localInternalCli);
-    const command = useLocal ? process.execPath : 'agent-infra-internal';
-    const commandArgs = useLocal ? [localInternalCli, ...args] : args;
+    const { command, commandArgs, shell } = internalCliInvocation(args);
     const output = execFileSync(command, commandArgs, {
       encoding: 'utf8',
-      shell: !useLocal && process.platform === 'win32',
+      shell,
       stdio: ['ignore', 'pipe', 'pipe']
     });
     process.stdout.write(output);

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

@@ -5,12 +5,18 @@
 - 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.
 - 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. 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
 

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

@@ -5,12 +5,18 @@
 - 总控只路由和委派；阶段技能仍是业务规则与产物格式的单一事实源。
 - 每个阶段和每轮返工都创建 fresh executor；每轮审查创建 fresh reviewer，禁止 follow-up 复用。
 - reviewer 只能写当前审查产物和核心生成的任务元数据。业务代码、HEAD 或暂存区变化会使 receipt 失效。
-- active run 中只有一个 pending delegation。缺失、错配、fork、重放、hook 不可用或工作区漂移一律暂停。
+- active run 中只有一个 pending delegation。child 必须在任何阶段副作用前通过 activation barrier；缺失、超时、错配、fork、重放、hook 不可用或工作区漂移一律暂停。
 - 首版成功终点是一次通过既有安全门禁的 `commit`；不创建 PR、不监控 checks、不执行 `complete-task`。
 
 ## 恢复语义
 
-`orchestration.json` 是详细状态源。v2 run 保存完整策略、来源与 append-only 恢复历史。只有无 pending delegation 且零历史 receipt 的 v1 run 可在补齐完整策略后原地升级；任一历史 receipt 因缺 effort 证据保持暂停。其他阻塞、未封存 receipt 或基线漂移继续保持暂停。迁移是 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 使用。
 
 ## 模型策略
 

package/templates/.agents/rules/no-mid-flow-questions.en.md

@@ -47,6 +47,7 @@ SKILLs currently covered by this exemption:
 
 - `release`: may confirm publish after presenting the latest release snapshot
 - `create-release-note`: may confirm publish after presenting exact staged notes and their digest
+- `post-release`: may confirm a normal push after preparing the local post commit and presenting the complete `postConfirmation` and digest
 
 ### Exemption 5: Complete model policy missing at lifecycle start
 

package/templates/.agents/rules/no-mid-flow-questions.zh-CN.md

@@ -47,6 +47,7 @@
 
 - `release`：展示最新 release snapshot 后确认是否 publish
 - `create-release-note`：展示 stage 后的精确 notes 与摘要后确认是否 publish
+- `post-release`：完成本地 post commit 并展示完整 `postConfirmation` 与摘要后确认是否普通 push
 
 ### 例外 5：生命周期启动缺少完整模型策略
 

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`。
 
 ## 快照与监控
 

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

@@ -94,7 +94,9 @@ When an executor judges an item to be a key design decision that needs human rul
 - The `complete-task` `post-review-commit` gate uses only B. When B is absent, malformed, or missing as a Git object, it reports `reviewed snapshot was not anchored` and never falls back to R.
 - If new commits touch code / rule paths after B, the gate blocks and requires a fresh `review-code`. Automatic exceptions are limited to: (1) a bound platform change request (PR/MR) is merged and its platform adapter supplies an authoritative snapshot plus remote Git evidence refs; the gate fetches the reviewed head and target branch into an isolated temporary repository and proves B is the original change-request head, its merge commit is in authoritative target history, its reviewed changes exactly match the normalized patch of a single-parent squash commit, and its protected paths have no later commits; or (2) no valid change request, exactly one protected-path commit after B, that commit is a single-parent local rewrite in HEAD history, it has the same full tree or protected content as B, and no protected-path commits follow it. An unsupported adapter capability, missing required platform / Git evidence, or Git credentials that cannot read those remote refs fails closed.
 - Required checks remain a pre-merge responsibility of branch protection / rulesets and the `review-code` / `watch-pr` routes. The post-review-commit gate still applies the applicable strict, PR-squash, or local-rewrite equivalence independently.
-- **Exemption**: append a ledger row `| PRC-1 | post-review-commit | - | - | human-decided | <ruling note> |` recording that a human explicitly allowed those commits without re-review.
+- **Exemption**: the canonical row is `| PRC-1 | post-review-commit | - | - | human-decided | <ruling note> |`. The id must be `PRC-N`, round and severity must be `-`, status must be `human-decided`, and evidence must be non-empty single-line text that records the ruling reason and applicable commit scope. Any malformed post-review row fails closed.
+- A merged-PR human exemption may override only the stable `PR_MERGE_IDENTITY_INVALID` failure. Blocked results, missing evidence, content/topology/target-history mismatches, and all other failed codes must not consume PRC. The passing result must preserve the original failure code/message and every consumed PRC id/evidence, and must not describe the result as automatic equivalence.
+- task.md is the persistent source of truth. Before preflight, the platform summary mirrors an existing warning or, without one, states only that the ruling awaits verification. After the exemption gate passes, the caller uses the gate output to complete the original-failure evidence and updates the same summary marker in place. The summary also mirrors the ruling reason, commit scope, human identity, and time from task.md.
 
 ## Gate behavior cheat sheet
 

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

@@ -94,7 +94,9 @@
 - `complete-task` 的 `post-review-commit` gate 只使用 B；B 缺失、畸形或对象不存在时报告 `reviewed snapshot was not anchored`，不得回退 R。
 - 若 B 之后代码 / 规则路径出现新提交，gate 会拦截，要求重新 `review-code`。自动例外仅限两类：(1) 绑定的平台变更请求（PR/MR）已合并，且平台适配器提供权威快照与远端 Git 证据引用；gate 在隔离的临时仓库中抓取受审查 head 与目标分支，证明 B 是原变更请求 head、merge commit 位于权威目标分支历史中、受审查变更与单父 squash commit 的规范化补丁完全一致，并且 merge 后受保护路径没有新提交；(2) 无有效变更请求，B 后恰有一个受保护路径提交，该提交是本地 HEAD 历史中的单父重写，且它与 B 的完整 tree 相同或受保护内容相同，重写后也没有受保护路径提交。适配器不支持该能力，缺少所需平台 / Git 证据，或当前 Git 凭据不能读取这些远端 refs 时 fail closed。
 - 全部 PR checks 由合并前的 `review-code` / `watch-pr` 路由负责，其中 required checks 仍受分支保护 / ruleset 强制。post-review-commit 仍独立执行适用的严格 / PR squash / 本地重写等价判定。
-- **豁免**：在账本追加一行 `| PRC-1 | post-review-commit | - | - | human-decided | <裁定说明> |`，记录人工明确允许该批提交免复审。
+- **豁免**：canonical 行形状为 `| PRC-1 | post-review-commit | - | - | human-decided | <裁定说明> |`。id 必须为 `PRC-N`，round/severity 必须为 `-`，status 必须为 `human-decided`，evidence 必须为非空单行文本并记录裁定理由与适用提交范围；任何不符合形状的 post-review 行均 fail closed。
+- merged-PR 人工豁免只可覆盖稳定的 `PR_MERGE_IDENTITY_INVALID`；blocked、证据缺失、内容/拓扑/目标历史不一致及其他 failed code 不得消费 PRC。通过消息必须保留原 failure code/message 与所消费的 PRC id/evidence，且不得表述为自动等价成功。
+- task.md 是持久化事实源。平台摘要在 preflight 前镜像既有 warning，或在无 warning 时只声明裁决待验证；人工豁免 gate 通过后，再以 gate 输出补齐原始失败并原地更新同一 summary marker。摘要同时镜像 task.md 中的裁决理由、提交范围、人工身份与时间。
 
 ## gate 行为速查
 

package/templates/.agents/skills/code-task/reference/dual-mode.en.md

@@ -10,6 +10,8 @@ agent-infra-internal task-artifact {task-id} inspect --family code
 
 The core scans `plan.md` / `plan-r{N}.md`, `review-plan.md` / `review-plan-r{N}.md`, `code.md` / `code-r{N}.md`, and `review-code.md` / `review-code-r{N}.md` in the task directory.
 
+`code.started` persists the plan identity and SHA-256 for the round in task.md frontmatter. `code.completed` must read the canonical plan from the implementation report's `Plan Input` field and match both that start context and the current latest plan; missing, mismatched, or changed input fails closed.
+
 ## Eight Branches
 
 > Branches are evaluated top-down in this table; the first match returns and skips later rows.
@@ -17,7 +19,7 @@ The core scans `plan.md` / `plan-r{N}.md`, `review-plan.md` / `review-plan-r{N}.
 | Condition | mode | exit | Behavior |
 |---|---|---:|---|
 | no code artifact, and the latest review-plan is exactly `Approved` and references the latest plan | `init` | 0 | initial implementation, output `code.md`; a missing matching approval or `Approved-with-issues` returns an error |
-| latest review-plan is exactly `Approved`, references the latest plan, and is newer than the latest code | `init` | 0 | enter a new implementation round. `Approved-with-issues` remains parse-compatible for history but is not cross-stage approval |
+| latest review-plan is exactly `Approved`, references the latest plan, and the latest code completion receipt does not bind the same plan digest | `init` | 0 | enter a new implementation round. `Approved-with-issues` remains parse-compatible for history but is not cross-stage approval; missing or invalid receipts fail closed |
 | `rev_max < code_max` | `error` | 2 | latest code round is unreviewed; run `review-code` first |
 | latest review-code is Approved and a pending implementation input was decided after that review completed | `decision` | 0 | select the earliest `II-N` and enter decision-driven implementation; false/not-required and consumed inputs do not trigger |
 | latest review-code is Approved with 0/0/0 | `refused` | 1 | already approved; do not run `code-task` again |

package/templates/.agents/skills/code-task/reference/dual-mode.zh-CN.md

@@ -10,6 +10,8 @@ agent-infra-internal task-artifact {task-id} inspect --family code
 
 核心扫描任务目录中的 `plan.md` / `plan-r{N}.md`、`review-plan.md` / `review-plan-r{N}.md`、`code.md` / `code-r{N}.md` 和 `review-code.md` / `review-code-r{N}.md`。
 
+`code.started` 会在 task.md frontmatter 中绑定本轮方案文件及其 SHA-256。`code.completed` 必须从实现报告的“方案输入”/“Plan Input”字段读取 canonical plan，并同时匹配该开始上下文和当前最新 plan；缺失、身份不一致或内容变化均失败关闭。
+
 ## 8 个分支
 
 > 分支按表中自上而下的顺序评估，命中即返回；后续分支不再判定。
@@ -17,7 +19,7 @@ agent-infra-internal task-artifact {task-id} inspect --family code
 | 条件 | mode | exit | 行为 |
 |---|---|---:|---|
 | 无 code 产物，且最新 review-plan 精确为 `Approved` 并引用最新 plan | `init` | 0 | 初次实现，产物为 `code.md`；缺少匹配审批或为 `Approved-with-issues` 时返回 error |
-| 最新 review-plan 精确为 `Approved`，且其「审查输入」/「Review Input」字段引用最新 plan，mtime 又晚于最新 code | `init` | 0 | plan 已在 code 之后获批；进入新一轮实现。`Approved-with-issues` 仅保留历史解析兼容，不构成跨阶段批准 |
+| 最新 review-plan 精确为 `Approved`，且其「审查输入」/「Review Input」字段引用最新 plan，而最新 code 的完成 receipt 未绑定相同 plan 摘要 | `init` | 0 | plan 内容在 code 输入之后获批；进入新一轮实现。`Approved-with-issues` 仅保留历史解析兼容，不构成跨阶段批准；缺失或无效 receipt 失败关闭 |
 | `rev_max < code_max` | `error` | 2 | 最新代码未审查，先运行 `review-code` |
 | 最新 review-code 为 Approved 且存在审查完成后产生的 pending 实现输入 | `decision` | 0 | 选择最早 `II-N`，进入裁决驱动实现；false/not-required 与 consumed 输入不触发 |
 | 最新 review-code 为 Approved 且 0/0/0 | `refused` | 1 | 已通过，无需再次运行 `code-task` |