@fitlab-ai/agent-infra 0.9.4 → 0.9.6

package/lib/task/verification-engine.ts

@@ -268,14 +268,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 +348,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')) {

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/lib/task/workspace-snapshot.ts

@@ -1,3 +1,4 @@
+import { createHash } from 'node:crypto';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -18,6 +19,25 @@ type RepositorySnapshot = Readonly<{
   worktreeTree: string;
 }>;
 
+type WorkspaceSnapshotContext = Readonly<{
+  gitRoot: string;
+  stateRoot: string;
+  taskId: string | null;
+}>;
+
+type TaskFileFingerprint = Readonly<{
+  path: string;
+  mode: number;
+  kind: 'file' | 'symlink';
+  sha256: string;
+}>;
+
+type OrchestrationWorkspaceFingerprint = Readonly<{
+  version: 2;
+  gitTree: string;
+  taskFiles: readonly TaskFileFingerprint[];
+}>;
+
 function captureWorktreeTree(repoRoot: string, forcedPath: string | null): string {
   const tempDir = fs.mkdtempSync(path.join(os.tmpdir(), 'agent-infra-orchestration-index-'));
   const indexFile = path.join(tempDir, 'index');
@@ -33,13 +53,72 @@ function captureWorktreeTree(repoRoot: string, forcedPath: string | null): strin
   }
 }
 
-function captureWorkspaceSnapshot(repoRoot: string, taskId: string | null): string {
+function captureLegacyWorkspaceSnapshot(repoRoot: string, taskId: string | null): string {
   const workspaceRelative = taskId
     ? `.agents/workspace/active/${taskId}`
     : '.agents/workspace/active';
   return captureWorktreeTree(repoRoot, workspaceRelative);
 }
 
+function taskFileFingerprints(stateRoot: string, taskId: string | null): TaskFileFingerprint[] {
+  const activeRoot = path.join(stateRoot, '.agents', 'workspace', 'active');
+  const roots = taskId ? [path.join(activeRoot, taskId)] : [activeRoot];
+  const records: TaskFileFingerprint[] = [];
+  const visit = (absolute: string, relative: string): void => {
+    const stat = fs.lstatSync(absolute);
+    if (stat.isDirectory()) {
+      for (const name of fs.readdirSync(absolute).sort()) {
+        visit(path.join(absolute, name), path.posix.join(relative, name));
+      }
+      return;
+    }
+    if (!stat.isFile() && !stat.isSymbolicLink()) return;
+    const content = stat.isSymbolicLink()
+      ? Buffer.from(fs.readlinkSync(absolute))
+      : fs.readFileSync(absolute);
+    records.push({
+      path: relative,
+      mode: stat.mode & 0o777,
+      kind: stat.isSymbolicLink() ? 'symlink' : 'file',
+      sha256: createHash('sha256').update(content).digest('hex')
+    });
+  };
+  for (const root of roots) {
+    if (!fs.existsSync(root)) continue;
+    const relative = path.posix.join('.agents/workspace/active', path.relative(activeRoot, root).split(path.sep).join('/'));
+    visit(root, relative.replace(/\/$/, ''));
+  }
+  return records.sort((left, right) => left.path.localeCompare(right.path));
+}
+
+function encodeWorkspaceFingerprint(value: OrchestrationWorkspaceFingerprint): string {
+  return `ws2:${Buffer.from(JSON.stringify(value)).toString('base64url')}`;
+}
+
+function decodeWorkspaceFingerprint(value: string): OrchestrationWorkspaceFingerprint | null {
+  if (!value.startsWith('ws2:')) return null;
+  try {
+    const parsed = JSON.parse(Buffer.from(value.slice(4), 'base64url').toString('utf8')) as OrchestrationWorkspaceFingerprint;
+    if (parsed.version !== 2 || !/^[a-f0-9]{40,64}$/.test(parsed.gitTree) || !Array.isArray(parsed.taskFiles)) {
+      throw new Error('invalid workspace fingerprint fields');
+    }
+    return parsed;
+  } catch (error) {
+    throw new Error(`ORCHESTRATION_SNAPSHOT_FAILED: ${error instanceof Error ? error.message : String(error)}`);
+  }
+}
+
+function captureWorkspaceSnapshot(context: WorkspaceSnapshotContext): string;
+function captureWorkspaceSnapshot(repoRoot: string, taskId: string | null): string;
+function captureWorkspaceSnapshot(contextOrRoot: WorkspaceSnapshotContext | string, taskId?: string | null): string {
+  if (typeof contextOrRoot === 'string') return captureLegacyWorkspaceSnapshot(contextOrRoot, taskId ?? null);
+  return encodeWorkspaceFingerprint({
+    version: 2,
+    gitTree: captureWorktreeTree(contextOrRoot.gitRoot, null),
+    taskFiles: taskFileFingerprints(contextOrRoot.stateRoot, contextOrRoot.taskId)
+  });
+}
+
 function captureRepositorySnapshot(repoRoot: string): RepositorySnapshot {
   return {
     head: git(repoRoot, null, ['rev-parse', 'HEAD']).trim(),
@@ -49,9 +128,24 @@ function captureRepositorySnapshot(repoRoot: string): RepositorySnapshot {
 }
 
 function diffWorkspaceSnapshots(repoRoot: string, before: string, after: string): string[] {
-  const output = git(repoRoot, null, ['diff', '--name-only', '-z', before, after]);
-  return output.split('\0').filter(Boolean);
+  const beforeV2 = decodeWorkspaceFingerprint(before);
+  const afterV2 = decodeWorkspaceFingerprint(after);
+  if ((beforeV2 === null) !== (afterV2 === null)) {
+    throw new Error('ORCHESTRATION_SNAPSHOT_FAILED: workspace fingerprint versions cannot be mixed');
+  }
+  if (!beforeV2 || !afterV2) {
+    const output = git(repoRoot, null, ['diff', '--name-only', '-z', before, after]);
+    return output.split('\0').filter(Boolean);
+  }
+  const output = git(repoRoot, null, ['diff', '--name-only', '-z', beforeV2.gitTree, afterV2.gitTree]);
+  const changed = new Set(output.split('\0').filter(Boolean));
+  const beforeFiles = new Map(beforeV2.taskFiles.map((record) => [record.path, JSON.stringify(record)]));
+  const afterFiles = new Map(afterV2.taskFiles.map((record) => [record.path, JSON.stringify(record)]));
+  for (const filePath of new Set([...beforeFiles.keys(), ...afterFiles.keys()])) {
+    if (beforeFiles.get(filePath) !== afterFiles.get(filePath)) changed.add(filePath);
+  }
+  return [...changed].sort();
 }
 
 export { captureRepositorySnapshot, captureWorkspaceSnapshot, diffWorkspaceSnapshots };
-export type { RepositorySnapshot };
+export type { OrchestrationWorkspaceFingerprint, RepositorySnapshot, WorkspaceSnapshotContext };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.4",
+  "version": "0.9.6",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -58,13 +58,13 @@
     "demo:regen": "sh scripts/demo-regen.sh",
     "prepare": "git config core.hooksPath .git-hooks || true",
     "typecheck": "tsc -p tsconfig.test.json --noEmit && tsc -p tsconfig.jschecks.json --noEmit",
-    "test:smoke": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\"",
-    "test:core": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
-    "test:integration": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/integration/**/*.test.ts\" \"tests/e2e/**/*.test.ts\"",
+    "test:smoke": "node scripts/run-tests.js \"tests/unit/**/*.test.ts\"",
+    "test:core": "node scripts/run-tests.js \"tests/unit/**/*.test.ts\" \"tests/integration/**/*.test.ts\"",
+    "test:integration": "node scripts/run-tests.js \"tests/integration/**/*.test.ts\" \"tests/e2e/**/*.test.ts\"",
     "check": "npm run typecheck && npm test",
-    "test": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\"",
-    "test:coverage": "npm run build && node --experimental-strip-types --no-warnings --test --experimental-test-coverage \"--test-coverage-exclude=tests/**\" --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov \"tests/**/*.test.ts\"",
-    "prepublishOnly": "npm run build && node --experimental-strip-types --no-warnings --test \"tests/**/*.test.ts\""
+    "test": "node scripts/run-tests.js \"tests/**/*.test.ts\"",
+    "test:coverage": "node scripts/run-tests.js --experimental-test-coverage \"--test-coverage-exclude=tests/**\" --test-reporter=spec --test-reporter-destination=stdout --test-reporter=lcov --test-reporter-destination=coverage.lcov \"tests/**/*.test.ts\"",
+    "prepublishOnly": "node scripts/run-tests.js \"tests/**/*.test.ts\""
   },
   "devDependencies": {
     "@types/cross-spawn": "^6.0.6",

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

@@ -1,15 +1,41 @@
 import { execFileSync } from 'node:child_process';
+import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
+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');
 const client = clientIndex >= 0 ? process.argv[clientIndex + 1] : '';
-if (client !== 'claude-code') {
+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' };
+}
+
 let input = '';
 process.stdin.setEncoding('utf8');
 process.stdin.on('data', (chunk) => {
@@ -27,9 +53,65 @@ process.stdin.on('end', () => {
     process.stderr.write('Lifecycle delegation hook received invalid JSON\n');
     process.exit(1);
   }
-  const hook = String(event.hook_event_name || event.event || '').toLowerCase();
-  const nativeAgent = event.agent_name || event.agent_type || event.agent?.name;
-  if (!String(nativeAgent || '').startsWith('agent-infra-lifecycle-')) process.exit(0);
+  const phaseIndex = process.argv.indexOf('--event');
+  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 (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 parentReconcile = hook === 'post-tool'
+      && toolName === 'collaborationwait_agent'
+      && toolResponse.timed_out !== true;
+    if (!managedAgent && !parentReconcile) process.exit(0);
+    const hookDefinitionHash = createHash('sha256').update(readFileSync(codexHooks)).digest('hex');
+    const normalized = {
+      sessionId: String(event.session_id || ''),
+      turnId: String(event.turn_id || ''),
+      toolUseId: String(event.tool_use_id || ''),
+      childThreadId: String(event.agent_id || event.child_id || event.thread_id || event.tool_response?.agent_id || ''),
+      nativeAgent: String(nativeAgent),
+      requestedModel: String(toolInput.model || ''),
+      requestedReasoningEffort: String(toolInput.reasoning_effort || toolInput.reasoningEffort || ''),
+      hookDefinitionHash,
+      toolName,
+      taskName: String(toolInput.task_name || ''),
+      transcriptPath: String(event.transcript_path || '')
+    };
+    const args = ['codex-lifecycle', 'hook-event', '--event', hook, '--bridge', 'true'];
+    try {
+      const { command, commandArgs, shell } = internalCliInvocation(args);
+      const output = execFileSync(command, commandArgs, {
+        encoding: 'utf8',
+        input: JSON.stringify(normalized),
+        shell,
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 15_000
+      });
+      process.stdout.write(output);
+    } catch (error) {
+      if (error.stdout) process.stdout.write(String(error.stdout));
+      if (error.stderr) process.stderr.write(String(error.stderr));
+      process.exit(typeof error.status === 'number' ? error.status : 1);
+    }
+    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) {
@@ -58,12 +140,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

@@ -10,7 +10,7 @@
 
 ## 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 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.
 
 ## Model Policy
 

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

@@ -10,7 +10,7 @@
 
 ## 恢复语义
 
-`orchestration.json` 是详细状态源。v2 run 保存完整策略、来源与 append-only 恢复历史。只有无 pending delegation 且零历史 receipt 的 v1 run 可在补齐完整策略后原地升级；任一历史 receipt 因缺 effort 证据保持暂停。其他阻塞、未封存 receipt 或基线漂移继续保持暂停。迁移是 forward-only，旧二进制不得推进 v2 active run。
+`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。
 
 ## 模型策略
 

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/task-management.en.md

@@ -68,6 +68,7 @@ The six internal commands (`task-event` / `task-lifecycle` / `platform-issue` /
   `- {time} — **{base} [started]** by {agent} — started`
 - **done line** (written when the step completes, unchanged from today): the action is the base itself:
   `- {time} — **{base}** by {agent} — {completion summary}`
+- **Commit-specific attempt**: the commit skill must not hand-write started. `commit-start` writes a structured `Commit [started]` with `attempt`, `baseline`, and `agent` under the task lock; `commit-terminate` writes the matching `Commit [aborted]` when an attempt is abandoned before side effects. Aborted closes activity only and is never successful commit evidence.
 - `{base}` is that skill's existing done action text, including `(Round {N})` (e.g. `Plan Task (Round 1)`). started and done must share the same `{base}` to pair.
 
 **Pairing and rendering** (`ai task log`): a started entry pairs with the next same-`{base}` done entry onto one row (repeated executions of the same base pair FIFO by ascending time). The STARTED column shows the start time, DONE the completion time; started with no done = in progress (DONE shows `(in progress)`); done with no started (legacy logs) = a standalone completed row. All three shapes are valid and never error.

package/templates/.agents/rules/task-management.zh-CN.md

@@ -70,6 +70,7 @@
   `- {time} — **{基名} [started]** by {agent} — started`
 - **done 行**（步骤完成时写，与现状一致）：action 即基名本身：
   `- {time} — **{基名}** by {agent} — {完成说明}`
+- **Commit 专用 attempt**：commit 技能不得手写 started。`commit-start` 在任务锁内写入带 `attempt`、`baseline`、`agent` 的结构化 `Commit [started]`；无副作用放弃时由 `commit-terminate` 写匹配的 `Commit [aborted]`。aborted 只闭合活动日志，不构成提交成功证据。
 - `{基名}` 指该 SKILL 既有 done 条目的 action 文本，含 `(Round {N})`（如 `Plan Task (Round 1)`）。
   started 与 done 共用同一 `{基名}` 才能配对。
 

package/templates/.agents/skills/commit/SKILL.en.md

@@ -31,17 +31,11 @@ Direct invocation still requires explicit user authorization. An orchestrated in
 
 Without explicit task scope, only `TASK_CONTEXT_NOT_FOUND` may continue through the existing bare-commit path. Detached HEAD, damaged candidates, or multiple matches are ambiguity errors. Any explicit task-scope failure is fatal.
 
-## Step Start: Recover First, Then Write the started Marker
+## Step Start: Recover or Create a Controlled Attempt
 
-When `{task-id}` is resolved, call `commit-status` first. For `recoverable` / `prepared`, call `commit-recover --agent {standard-agent-token}` without adding a second started entry or repeating Git side effects. Fail closed for `invalid` / `conflict` / `orphaned-start`; only `idle` enters the normal flow.
+When `{task-id}` is resolved, call `commit-status` first. Finalize `recoverable`; safely clear `prepared` and query status again; reuse `retryable-start` through `commit-recover --agent {standard-agent-token}`. Fail closed for `invalid` / `conflict` / `orphaned-start`. For `idle`, call `commit-start --agent {standard-agent-token}` so the core atomically writes the structured started entry and returns its attempt/baseline.
 
-Before checking local modifications, append a started marker to task.md `## Activity Log` (same base action as this step's done entry plus a ` [started]` suffix, note `started`):
-
-```
-- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Commit [started]** by {agent} — started
-```
-
-`ai task log` pairs it with the done entry written when the commit completes onto one row (in progress → done). Format and pairing rules: see the "Activity Log started / done dual-marker convention" in `.agents/rules/task-management.md`. Only write it when this task has a task.md (a bare commit with no task context may skip it).
+Read `{commit-attempt}` only from structured `commit-start` / `commit-recover` output. Never hand-write, copy, or guess an attempt. A bare commit without task context skips this protocol.
 
 ## 1. Check Local Modifications (CRITICAL)
 

package/templates/.agents/skills/commit/SKILL.zh-CN.md

@@ -31,21 +31,17 @@ description: >
 
 未显式指定 task scope 时，只有 `TASK_CONTEXT_NOT_FOUND` 可继续既有纯提交路径；detached HEAD、损坏候选或多匹配属于歧义，必须失败。显式 task scope 解析失败时一律失败。
 
-## 步骤开始：先恢复，再写 started 标记
+## 步骤开始：恢复或创建受控 attempt
 
 已解析出 `{task-id}` 时，先调用 `agent-infra-internal task-orchestration {task-id} commit-status`：
 
-- `recoverable` / `prepared`：调用 `commit-recover --agent {standard-agent-token}`；不得追加第二条 started、重复 commit 或重复 push。recoverable 完成后直接进入同步与完成校验；prepared 清理后复用既有 open started 并继续正常提交。
+- `recoverable`：调用 `commit-recover --agent {standard-agent-token}` 完成收尾，不得重复 commit 或 push。
+- `prepared`：调用 `commit-recover --agent {standard-agent-token}` 安全清理 intent，再次查询 status 并复用返回的 `retryable-start` attempt。
+- `retryable-start`：调用 `commit-recover --agent {standard-agent-token}` 取得原 attempt，不追加第二条 started。
 - `invalid` / `conflict` / `orphaned-start`：输出结构化 code 与状态证据并停止。
-- `idle`：继续下方正常流程。
+- `idle`：调用 `commit-start --agent {standard-agent-token}`，由核心在任务锁内原子写入结构化 started 并返回 attempt/baseline。
 
-开始检查本地修改之前，向 task.md `## 活动日志` 追加一条 started 标记（与本步骤 done 条目同基名 + ` [started]` 后缀，note 用 `started`）：
-
-```
-- {YYYY-MM-DD HH:mm:ss±HH:MM} — **Commit [started]** by {agent} — started
-```
-
-`ai task log` 会把它与提交完成时写入的 done 条目配对成一行（进行中 → 已完成）。格式与配对规则见 `.agents/rules/task-management.md` 的「Activity Log started / done 双标记约定」。仅当本任务存在 task.md 时写入（无任务上下文的纯提交可跳过）。
+只从 `commit-start` / `commit-recover` 的结构化输出读取 `{commit-attempt}`；不得手写、复制或猜测 attempt。无任务上下文的纯提交跳过本协议。
 
 ## 1. 检查本地修改（关键）
 

package/templates/.agents/skills/commit/reference/commit-orchestration.en.md

@@ -9,12 +9,12 @@ This protocol applies only when `{task-id}` was resolved. A taskless Git-only co
 
 ## Begin before side effects
 
-Call `commit-status` whenever the commit skill starts. For `recoverable` / `prepared`, call `commit-recover --agent {standard-agent-token}`; fail closed for every other non-`idle` state. The recovery intent accepts no token, head, or `--orchestrated` flag.
+Call `commit-status` whenever the commit skill starts. Use `commit-recover --agent {standard-agent-token}` for `recoverable` / `prepared` / `retryable-start`; use `commit-start --agent {standard-agent-token}` for `idle`; fail closed for every other state. Read `commit_attempt` only from `finalization.attempt.attempt` in start/recover output.
 
 After read-only preparation of status, copyright, message, review snapshot, and push routing, record `baseline_head=$(git rev-parse HEAD)` and run this before any commit, push, success log, or platform success sync:
 
 ```bash
-commit_intent_result=$(agent-infra-internal task-orchestration {task-id} commit-begin --agent {standard-agent-token} {execution-flag} --baseline-head "$baseline_head")
+commit_intent_result=$(agent-infra-internal task-orchestration {task-id} commit-begin --agent {standard-agent-token} {execution-flag} --baseline-head "$baseline_head" --attempt "$commit_attempt")
 commit_intent_token=$(printf '%s' "$commit_intent_result" | node -e 'let input = ""; process.stdin.on("data", chunk => input += chunk).on("end", () => process.stdout.write(JSON.parse(input).token))')
 ```
 
@@ -44,6 +44,7 @@ After the committed/pushed checkpoint and before task synchronization or `task-v
 agent-infra-internal task-orchestration {task-id} commit-complete --token "$commit_intent_token" --agent {standard-agent-token}
 ```
 
-- Before the first side effect, abort only while HEAD still equals the baseline by using `commit-abort --token ... --expected-head ...`.
+- If an intent exists but no side effect occurred, use `commit-abort --token ... --expected-head ...` while HEAD still equals baseline; when abandoning the attempt, then close it with `commit-terminate --attempt "$commit_attempt" --agent {standard-agent-token} --code <STABLE_CODE>`.
+- If begin failed before intent creation, retain the attempt for retry or terminate it only while HEAD is unchanged.
 - After a commit or push, never abort. Retain the intent and use `commit-status` / `commit-recover` for cross-session recovery.
 - Stop when `commit-complete` fails. Do not repeat commit/push or mark a run complete without its full receipt lifecycle.

package/templates/.agents/skills/commit/reference/commit-orchestration.zh-CN.md

@@ -9,18 +9,18 @@
 
 ## 副作用前 begin
 
-每次进入 commit 技能先调用 `commit-status`。`recoverable` / `prepared` 调用以下无 token 恢复入口，其他非 `idle` 状态 fail closed：
+每次进入 commit 技能先调用 `commit-status`。`recoverable` / `prepared` / `retryable-start` 调用以下无 token 恢复入口，`idle` 调用 `commit-start --agent {standard-agent-token}`；其他状态 fail closed：
 
 ```bash
 agent-infra-internal task-orchestration {task-id} commit-recover --agent {standard-agent-token}
 ```
 
-恢复入口只接受 `--agent`；不得传 token、head 或 `--orchestrated`。recoverable 会幂等补齐 task/run 并最后删除 intent；prepared 仅在 HEAD=baseline 且恰有一个 open Commit started 时安全清理，随后复用该 started 继续正常流程。
+恢复入口只接受 `--agent`；不得传 token、head 或 `--orchestrated`。从 start/recover 结构化输出读取 `finalization.attempt.attempt` 为 `commit_attempt`，不得手写 attempt。
 
 完成状态、版权、提交信息、review snapshot 和 push 场景的只读准备后，记录 `baseline_head=$(git rev-parse HEAD)`，并在任何 commit、push、任务成功日志或平台成功同步之前调用：
 
 ```bash
-commit_intent_result=$(agent-infra-internal task-orchestration {task-id} commit-begin --agent {standard-agent-token} {execution-flag} --baseline-head "$baseline_head")
+commit_intent_result=$(agent-infra-internal task-orchestration {task-id} commit-begin --agent {standard-agent-token} {execution-flag} --baseline-head "$baseline_head" --attempt "$commit_attempt")
 commit_intent_token=$(printf '%s' "$commit_intent_result" | node -e 'let input = ""; process.stdin.on("data", chunk => input += chunk).on("end", () => process.stdout.write(JSON.parse(input).token))')
 ```
 
@@ -50,6 +50,7 @@ committed/pushed checkpoint 完成后、任务同步与 `task-verify commit.comp
 agent-infra-internal task-orchestration {task-id} commit-complete --token "$commit_intent_token" --agent {standard-agent-token}
 ```
 
-- 第一个副作用前失败时，仅可在 HEAD 仍等于 baseline 时调用 `commit-abort --token ... --expected-head ...`。
+- begin 已创建 intent、但第一个副作用前失败时，先在 HEAD 仍等于 baseline 时调用 `commit-abort --token ... --expected-head ...`；若本轮明确放弃，再调用 `commit-terminate --attempt "$commit_attempt" --agent {standard-agent-token} --code <STABLE_CODE>` 闭合 started。
+- begin 在 intent 创建前失败时可保留 attempt 供下次复用；明确放弃时仅可在 HEAD 未漂移时调用 `commit-terminate`。
 - commit 或 push 发生后失败时不得 abort；保留 intent，并调用 `commit-status` 输出不含 token/digest 的恢复证据。跨会话重跑通过 `commit-recover` 收尾。
 - `commit-complete` 失败时停止。不得重复执行 commit/push，也不得把缺少完整 receipt 生命周期的 run 标记为完成。