@fitlab-ai/agent-infra 0.9.4 → 0.9.5

package/lib/task/orchestration.ts

@@ -36,6 +36,8 @@ import {
   diffWorkspaceSnapshots
 } from './workspace-snapshot.ts';
 import type { RepositorySnapshot } from './workspace-snapshot.ts';
+import type { WorkspaceSnapshotContext } from './workspace-snapshot.ts';
+import { assertGitRepositoryBinding } from '../git/worktree-identity.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import {
   CommitIntentError,
@@ -55,6 +57,12 @@ import {
 } from './commit-finalization.ts';
 import type { CommitFinalizationInspection } from './commit-finalization.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
+import {
+  appendActivityEntry,
+  commitAttemptStartedNote,
+  locateActivityLog,
+  pairEntries
+} from './activity-log.ts';
 
 type OrchestrationStatus = 'running' | 'paused' | 'completed';
 type LegacyOrchestrationModelPolicy = Readonly<{
@@ -147,12 +155,13 @@ type OrchestrationCompletionPlanResult = Readonly<{
 }>;
 type OrchestrationOptions = {
   repoRoot?: string;
+  gitWorktreeRoot?: string;
   id?: () => string;
   now?: () => string;
   maxSteps?: number;
   client?: AgentClientId;
   modelPolicy?: OrchestrationModelPolicy;
-  captureWorkspace?: (repoRoot: string, taskId: string | null) => string;
+  captureWorkspace?: (context: WorkspaceSnapshotContext) => string;
   captureRepository?: (repoRoot: string) => RepositorySnapshot;
   inspectPullRequest?: (taskId: string, options: { cwd: string }) => Readonly<{
     status: string;
@@ -188,6 +197,7 @@ type CommitIntentResult = Readonly<{
     committedHead: string | null;
     needsAnchor: boolean;
     needsLog: boolean;
+    attempt: Readonly<{ attempt: string; baseline: string; agent: string }> | null;
   }>;
   token?: string;
   error: Readonly<{ code: string; message: string }> | null;
@@ -259,6 +269,11 @@ function repositoryHead(repoRoot: string): string {
   }).trim();
 }
 
+function gitRootFor(stateRoot: string, options: OrchestrationOptions): string {
+  if (!options.gitWorktreeRoot) return stateRoot;
+  return assertGitRepositoryBinding(stateRoot, options.gitWorktreeRoot).worktreeRoot;
+}
+
 function isAncestor(repoRoot: string, ancestor: string, descendant: string): boolean {
   return spawnSync('git', ['merge-base', '--is-ancestor', ancestor, descendant], {
     cwd: repoRoot,
@@ -287,7 +302,8 @@ function commitFinalizationView(inspection: CommitFinalizationInspection): NonNu
     currentHead: inspection.currentHead,
     committedHead: inspection.committedHead,
     needsAnchor: inspection.needsAnchor,
-    needsLog: inspection.needsLog
+    needsLog: inspection.needsLog,
+    attempt: inspection.attempt
   };
 }
 
@@ -607,6 +623,12 @@ function routeFromFacts(taskDir: string): Omit<OrchestrationNext, 'requestedMode
 function routeOrchestration(taskRef: string, options: OrchestrationOptions = {}): OrchestrationResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return failed(resolved.code, resolved.message, resolved.taskId);
+  let gitRoot: string;
+  try {
+    gitRoot = gitRootFor(resolved.repoRoot, options);
+  } catch (error) {
+    return failed('ORCHESTRATION_WORKTREE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+  }
   let content: string;
   try {
     content = fs.readFileSync(resolved.taskMdPath, 'utf8');
@@ -677,7 +699,7 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
     const capture = options.captureRepository ?? captureRepositorySnapshot;
     let before: RepositorySnapshot;
     try {
-      before = capture(resolved.repoRoot);
+      before = capture(gitRoot);
     } catch (error) {
       return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
@@ -693,7 +715,7 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
       options.inspectPullRequest ?? inspectPlatformPullRequest;
     let inspection: ReturnType<NonNullable<OrchestrationOptions['inspectPullRequest']>>;
     try {
-      inspection = inspect(resolved.taskId, { cwd: resolved.repoRoot });
+      inspection = inspect(resolved.taskId, { cwd: gitRoot });
     } catch (error) {
       return failed('ORCHESTRATION_PR_INSPECTION_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
@@ -714,7 +736,7 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
 
     let after: RepositorySnapshot;
     try {
-      after = capture(resolved.repoRoot);
+      after = capture(gitRoot);
     } catch (error) {
       return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
     }
@@ -748,16 +770,119 @@ function routeOrchestration(taskRef: string, options: OrchestrationOptions = {})
   return { status: 'running', changed: false, taskId: resolved.taskId, run, next, error: null };
 }
 
+function appendCommitActivity(
+  resolved: Extract<ReturnType<typeof resolveTaskRef>, { ok: true }>,
+  step: string,
+  agent: string,
+  note: string
+): Readonly<{ code: string; message: string }> | null {
+  const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  const activity = locateActivityLog(taskContent);
+  if (!activity) return { code: 'ORCHESTRATION_TASK_INVALID', message: 'task activity log is missing or ambiguous' };
+  const metadata = captureTaskWriteMetadata();
+  const written = writeTask({
+    taskRef: resolved.taskId,
+    expectedState: 'active',
+    mutations: [{
+      kind: 'section',
+      aliases: ['活动日志', 'Activity Log'],
+      heading: activity.heading,
+      body: appendActivityEntry(activity, { time: metadata.timestamp, step, agent, note })
+    }]
+  }, { repoRoot: resolved.repoRoot, metadataProvider: () => metadata });
+  return written.status === 'failed' ? written.error : null;
+}
+
+function startCommitAttempt(
+  taskRef: string,
+  input: Readonly<{ agent: string }>,
+  options: OrchestrationOptions = {}
+): CommitIntentResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+  try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
+    return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-attempt.start', () => {
+      if (fs.existsSync(commitIntentPath(resolved.taskDir))) {
+        return commitIntentFailed('ORCHESTRATION_COMMIT_INTENT_BUSY', 'an active commit intent already exists', resolved.taskId);
+      }
+      const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+      const activity = locateActivityLog(taskContent);
+      if (!activity) return commitIntentFailed('ORCHESTRATION_TASK_INVALID', 'task activity log is missing or ambiguous', resolved.taskId);
+      const open = pairEntries(activity.entries).filter((row) => row.step === 'Commit' && row.started !== '' && row.done === '');
+      if (open.length > 0) {
+        return commitIntentFailed('ORCHESTRATION_COMMIT_ATTEMPT_BUSY', 'an open Commit activity entry already exists', resolved.taskId);
+      }
+      const currentHead = repositoryHead(gitRoot);
+      const attempt = (options.id ?? randomUUID)();
+      const error = appendCommitActivity(resolved, 'Commit [started]', input.agent, commitAttemptStartedNote({
+        attempt,
+        baseline: currentHead,
+        agent: input.agent
+      }));
+      if (error) return commitIntentFailed(error.code, error.message, resolved.taskId);
+      const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+      return {
+        status: 'ready', changed: true, taskId: resolved.taskId, intent: null,
+        finalization: commitFinalizationView(inspection), error: null
+      };
+    });
+  } catch (error) {
+    return mapCommitIntentError(error, resolved.taskId);
+  }
+}
+
+function terminateCommitAttempt(
+  taskRef: string,
+  input: Readonly<{ attempt: string; agent: string; code: string }>,
+  options: OrchestrationOptions = {}
+): CommitIntentResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
+  try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
+    return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-attempt.terminate', () => {
+      if (fs.existsSync(commitIntentPath(resolved.taskDir))) {
+        return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'an active commit intent must be aborted or recovered first', resolved.taskId);
+      }
+      const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+      if (
+        inspection.disposition !== 'retryable-start'
+        || inspection.attempt?.attempt !== input.attempt
+        || inspection.attempt.agent !== input.agent
+        || inspection.attempt.baseline !== inspection.currentHead
+      ) {
+        return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'commit attempt identity or repository HEAD has drifted', resolved.taskId);
+      }
+      const error = appendCommitActivity(
+        resolved,
+        'Commit [aborted]',
+        input.agent,
+        `aborted; attempt=${input.attempt}; code=${input.code}`
+      );
+      if (error) return commitIntentFailed(error.code, error.message, resolved.taskId);
+      return {
+        status: 'ready', changed: true, taskId: resolved.taskId, intent: null,
+        finalization: commitFinalizationView(inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId)),
+        error: null
+      };
+    });
+  } catch (error) {
+    return mapCommitIntentError(error, resolved.taskId);
+  }
+}
+
 function beginCommitIntent(
   taskRef: string,
-  input: Readonly<{ agent: string; orchestrated: boolean; baselineHead: string }>,
+  input: Readonly<{ agent: string; orchestrated: boolean; baselineHead: string; attempt: string }>,
   options: OrchestrationOptions = {}
 ): CommitIntentResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
   try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
     return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.begin', () => {
-      const currentHead = repositoryHead(resolved.repoRoot);
+      const currentHead = repositoryHead(gitRoot);
       if (currentHead !== input.baselineHead) {
         return commitIntentFailed('ORCHESTRATION_COMMIT_BASELINE_MISMATCH', 'baseline HEAD does not match the repository HEAD', resolved.taskId);
       }
@@ -769,7 +894,19 @@ function beginCommitIntent(
         }
         return commitIntentFailed('ORCHESTRATION_COMMIT_INTENT_BUSY', 'an active commit intent already exists', resolved.taskId);
       }
-
+      const attemptInspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+      if (
+        attemptInspection.disposition !== 'retryable-start'
+        || attemptInspection.attempt?.attempt !== input.attempt
+        || attemptInspection.attempt.agent !== input.agent
+        || attemptInspection.attempt.baseline !== input.baselineHead
+      ) {
+        return commitIntentFailed(
+          'ORCHESTRATION_COMMIT_ATTEMPT_MISMATCH',
+          'commit begin requires one matching retryable Commit attempt',
+          resolved.taskId
+        );
+      }
       const runFile = orchestrationPath(resolved.taskDir);
       let run: OrchestrationRun | null = null;
       let sourceRunBytes: string | null = null;
@@ -883,13 +1020,14 @@ function checkpointCommitIntent(
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
   try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
     return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.checkpoint', () => {
       const intent = readCommitIntent(resolved.taskDir, resolved.taskId, input.token);
-      const currentHead = repositoryHead(resolved.repoRoot);
+      const currentHead = repositoryHead(gitRoot);
       if (currentHead !== input.head) {
         return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'checkpoint HEAD does not match the repository HEAD', resolved.taskId);
       }
-      if (input.kind === 'committed' && !isAncestor(resolved.repoRoot, intent.baselineHead, input.head)) {
+      if (input.kind === 'committed' && !isAncestor(gitRoot, intent.baselineHead, input.head)) {
         return commitIntentFailed('ORCHESTRATION_COMMIT_RECOVERY_REQUIRED', 'committed HEAD does not descend from the baseline', resolved.taskId);
       }
       if (input.kind === 'pushed') {
@@ -1016,9 +1154,10 @@ function completeCommitIntent(
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
   try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
     return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.complete', () => {
       readCommitIntent(resolved.taskDir, resolved.taskId, input.token);
-      const inspection = inspectCommitFinalization(resolved.taskDir, resolved.repoRoot, resolved.taskId);
+      const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
       return finalizeCommitIntentUnlocked(resolved, inspection, input.agent, () => {
         removeCommitIntent(resolved.taskDir, resolved.taskId, input.token);
       });
@@ -1036,8 +1175,15 @@ function recoverCommitIntent(
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
   try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
     return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.recover', () => {
-      const inspection = inspectCommitFinalization(resolved.taskDir, resolved.repoRoot, resolved.taskId);
+      const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
+      if (inspection.disposition === 'retryable-start') {
+        return {
+          status: 'ready', changed: false, taskId: resolved.taskId, intent: null,
+          finalization: commitFinalizationView(inspection), error: null
+        };
+      }
       if (inspection.disposition === 'prepared' && inspection.intentDigest) {
         removeCommitIntentByDigest(resolved.taskDir, resolved.taskId, inspection.intentDigest);
         return { status: 'ready', changed: true, taskId: resolved.taskId, intent: null, error: null };
@@ -1066,9 +1212,10 @@ function abortCommitIntent(
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
   try {
+    const gitRoot = gitRootFor(resolved.repoRoot, options);
     return withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'commit-intent.abort', () => {
       const intent = readCommitIntent(resolved.taskDir, resolved.taskId, input.token);
-      const currentHead = repositoryHead(resolved.repoRoot);
+      const currentHead = repositoryHead(gitRoot);
       if (
         intent.phase !== 'prepared'
         || intent.pushEvidence !== null
@@ -1088,7 +1235,13 @@ function abortCommitIntent(
 function statusCommitIntent(taskRef: string, options: OrchestrationOptions = {}): CommitIntentResult {
   const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
   if (!resolved.ok) return commitIntentFailed(resolved.code, resolved.message, resolved.taskId);
-  const inspection = inspectCommitFinalization(resolved.taskDir, resolved.repoRoot, resolved.taskId);
+  let gitRoot: string;
+  try {
+    gitRoot = gitRootFor(resolved.repoRoot, options);
+  } catch (error) {
+    return commitIntentFailed('ORCHESTRATION_WORKTREE_INVALID', error instanceof Error ? error.message : String(error), resolved.taskId);
+  }
+  const inspection = inspectCommitFinalization(resolved.taskDir, gitRoot, resolved.taskId);
   return {
     status: 'ready',
     changed: false,
@@ -1156,7 +1309,11 @@ function prepareOrchestrationDelegationUnlocked(
   }
   let beforeFingerprint: string;
   try {
-    beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(resolved.repoRoot, resolved.taskId);
+    beforeFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
+      gitRoot: gitRootFor(resolved.repoRoot, options),
+      stateRoot: resolved.repoRoot,
+      taskId: resolved.taskId
+    });
   } catch (error) {
     return failed('ORCHESTRATION_SNAPSHOT_FAILED', error instanceof Error ? error.message : String(error), resolved.taskId);
   }
@@ -1280,9 +1437,14 @@ function sealMatchingOrchestrationDelegation(
   }
   const repoRoot = options.repoRoot ?? process.cwd();
   try {
+    const gitRoot = gitRootFor(repoRoot, options);
     const snapshotTaskId = receipt.workspaceSnapshotScope === 'task' ? receipt.taskId : null;
-    const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)(repoRoot, snapshotTaskId);
-    const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(repoRoot, receipt.beforeFingerprint, afterFingerprint);
+    const afterFingerprint = (options.captureWorkspace ?? captureWorkspaceSnapshot)({
+      gitRoot,
+      stateRoot: repoRoot,
+      taskId: snapshotTaskId
+    });
+    const changedPaths = (options.diffWorkspace ?? diffWorkspaceSnapshots)(gitRoot, receipt.beforeFingerprint, afterFingerprint);
     return sealOrchestrationDelegation(matched.taskId, {
       childId: event.childId,
       exitCode: 0,
@@ -1474,8 +1636,10 @@ export {
   routeOrchestration,
   sealMatchingOrchestrationDelegation,
   sealOrchestrationDelegation,
+  startCommitAttempt,
   statusCommitIntent,
-  statusOrchestration
+  statusOrchestration,
+  terminateCommitAttempt
 };
 export type {
   CommitIntentResult,

package/lib/task/review-fingerprint.ts

@@ -3,6 +3,13 @@ import path from "node:path";
 
 import { artifactName, maxRound } from "./review-artifacts.ts";
 
+type ReviewedGitTree = string & { readonly __reviewedGitTree: unique symbol };
+const REVIEWED_TREE_RE = /^[a-f0-9]{40,64}$/;
+
+export function parseReviewedGitTree(value: string): ReviewedGitTree | null {
+  return REVIEWED_TREE_RE.test(value) ? value as ReviewedGitTree : null;
+}
+
 // Paths excluded from the post-review coverage gate. Fail-closed: the gate
 // covers ALL tracked changes by default. This default denylist is EMPTY —
 // projects opt into exclusions explicitly via review.post_review_exclude_globs.
@@ -71,6 +78,8 @@ export function extractReviewedSnapshotTree(content: string): string {
   return match ? match[1]!.trim().replace(/`/g, "") : "";
 }
 
+export type { ReviewedGitTree };
+
 export function parseReviewVerdict(content: string): string {
   const match = String(content).match(/^[-*]?\s*\*\*(?:总体结论|Overall Verdict)\*\*[:：]\s*(.*?)\s*$/m);
   return match ? match[1]!.trim() : "";

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.5",
   "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,12 +1,15 @@
 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 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);
 }
@@ -27,9 +30,50 @@ 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;
+  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 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 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
+    };
+    const args = ['codex-lifecycle', 'hook-event', '--event', hook];
+    try {
+      const useLocal = existsSync(localInternalCli);
+      const command = useLocal ? process.execPath : 'agent-infra-internal';
+      const commandArgs = useLocal ? [localInternalCli, ...args] : args;
+      const output = execFileSync(command, commandArgs, {
+        encoding: 'utf8',
+        input: JSON.stringify(normalized),
+        shell: !useLocal && process.platform === 'win32',
+        stdio: ['pipe', 'pipe', 'pipe'],
+        timeout: 5_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;
+  }
   const start = hook.includes('start');
   const stop = hook.includes('stop');
   if (!start && !stop) {

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)