@fitlab-ai/agent-infra 0.9.8 → 0.9.9

package/lib/task/short-id.ts

@@ -201,6 +201,10 @@ type RegistrySchema = {
   ids: Record<string, string>;
 };
 
+type ShortIdRegistryInspection =
+  | { status: 'valid'; shortIds: Map<string, string> }
+  | { status: 'missing' | 'invalid'; error: { code: string; message: string } };
+
 type ShortIdMutationEffect = 'alloc' | 'release' | 'none';
 type ShortIdMutationResult = {
   effect: 'allocated' | 'released' | 'unchanged';
@@ -446,6 +450,64 @@ function loadShortIdByTaskId(repoRoot: string): Map<string, string> {
   return map;
 }
 
+function inspectShortIdRegistry(repoRoot: string): ShortIdRegistryInspection {
+  const registryPath = path.join(repoRoot, '.agents', 'workspace', 'active', REGISTRY_NAME);
+  if (!fs.existsSync(registryPath)) {
+    return {
+      status: 'missing',
+      error: {
+        code: 'SHORT_ID_REGISTRY_NOT_FOUND',
+        message: 'canonical short-id registry is missing'
+      }
+    };
+  }
+
+  let raw: string;
+  try {
+    raw = fs.readFileSync(registryPath, 'utf8');
+  } catch {
+    return {
+      status: 'invalid',
+      error: {
+        code: 'SHORT_ID_REGISTRY_READ_FAILED',
+        message: 'canonical short-id registry is unreadable'
+      }
+    };
+  }
+
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(raw);
+  } catch {
+    return {
+      status: 'invalid',
+      error: {
+        code: 'SHORT_ID_REGISTRY_INVALID_JSON',
+        message: 'canonical short-id registry contains invalid JSON'
+      }
+    };
+  }
+
+  try {
+    const registry = validateRegistry(parsed, registryPath, configuredShortIdLength(repoRoot));
+    const shortIds = new Map<string, string>();
+    for (const [key, taskId] of Object.entries(registry.ids)) shortIds.set(taskId, key);
+    return { status: 'valid', shortIds };
+  } catch (error) {
+    return {
+      status: 'invalid',
+      error: {
+        code: typeof (error as { code?: unknown }).code === 'string'
+          ? (error as { code: string }).code
+          : 'SHORT_ID_REGISTRY_INVALID_SCHEMA',
+        message: (error as { code?: unknown }).code === 'SHORT_ID_REGISTRY_DUPLICATE_TASK'
+          ? 'canonical short-id registry contains duplicate task entries'
+          : 'canonical short-id registry has invalid schema'
+      }
+    };
+  }
+}
+
 /**
  * Resolve a branch to its active-task short id (`NN`), or `null` when no
  * active task is bound to that branch.
@@ -485,6 +547,7 @@ export {
   resolveShortIdReadOnly,
   lookupShortIdByBranch,
   loadShortIdByTaskId,
+  inspectShortIdRegistry,
   configuredShortIdLength,
   mutateShortIdRegistry,
   executeShortIdCommand
@@ -497,5 +560,6 @@ export type {
   ShortIdMutationEffect,
   ShortIdMutationResult,
   ShortIdCommandRequest,
-  ShortIdCommandResult
+  ShortIdCommandResult,
+  ShortIdRegistryInspection
 };

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

@@ -272,6 +272,7 @@ function withTaskExecutionLock<T>(
     return callback();
   } catch (error) {
     if (error instanceof TaskExecutionLockError) throw error;
+    if (error instanceof Error && error.name === 'OrchestrationStateError') throw error;
     throw new TaskExecutionLockError(
       'ORCHESTRATION_LOCK_FAILED',
       'lifecycle task lock operation failed',
@@ -294,5 +295,13 @@ function withTaskExecutionLock<T>(
   }
 }
 
-export { TaskExecutionLockError, lockKey, mapLinkError, withTaskExecutionLock };
+function withRepositoryMutationLock<T>(
+  repoRoot: string,
+  callback: () => T,
+  options: TaskExecutionLockOptions = {}
+): T {
+  return withTaskExecutionLock(repoRoot, '__repository_mutation__', 'repository-mutation', callback, options);
+}
+
+export { TaskExecutionLockError, lockKey, mapLinkError, withRepositoryMutationLock, withTaskExecutionLock };
 export type { LinkDisposition, LinkOperation, TaskExecutionLockErrorCode, TaskExecutionLockOptions, TaskExecutionLockOwner };

package/lib/task/verification-engine.ts

@@ -27,6 +27,7 @@ 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";
+import { OrchestrationStateError, readRun } from "./orchestration.ts";
 
 const TASK_ENUMS = {
   type: ["feature", "bugfix", "refactor", "docs", "chore"],
@@ -123,6 +124,8 @@ function runCheck(type: any, context: any, shared: any): any {
       return checkReviewFact(context);
     case "post-review-commit":
       return checkPostReviewCommit(context);
+    case "required-pr-delivery":
+      return checkRequiredPrDelivery(context);
     case "orchestration-state":
       return checkOrchestrationState(context);
     case "orchestration-evidence":
@@ -142,40 +145,19 @@ function runCheck(type: any, context: any, shared: any): any {
   }
 }
 
-function isFailClosedLegacyPause(run: any): boolean {
-  if (
-    run.schemaVersion !== 1
-    || run.status !== 'paused'
-    || run.pause?.recoverable !== false
-    || !exactText(run.pause?.message)
-    || !Array.isArray(run.receipts)
-  ) {
-    return false;
-  }
-  if (run.pause.code === 'ORCHESTRATION_HISTORICAL_EFFORT_UNVERIFIED') {
-    return run.receipts.length > 0 && run.pendingDelegation === null;
-  }
-  if (run.pause.code === 'ORCHESTRATION_DELEGATION_BUSY') {
-    return run.pendingDelegation != null && run.pendingDelegation.status !== 'sealed';
-  }
-  return false;
-}
-
 function checkOrchestrationState({ taskDir }: any): any {
   const file = path.join(taskDir, 'orchestration.json');
   const stat = safeStat(file);
   if (!stat?.isFile()) return failResult('orchestration-state', 'orchestration.json is missing');
   let run: any;
   try {
-    run = JSON.parse(fs.readFileSync(file, 'utf8'));
+    run = readRun(taskDir);
   } catch (error) {
-    return failResult('orchestration-state', `Invalid orchestration.json: ${String(error)}`);
+    const message = error instanceof OrchestrationStateError ? error.message : String(error);
+    return failResult('orchestration-state', `Invalid orchestration.json: ${message}`);
   }
-  if (isFailClosedLegacyPause(run)) {
-    return passResult('orchestration-state', 'Legacy orchestration run is safely paused');
-  }
-  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 || !['paused', 'completed'].includes(run.status)) {
+    return failResult('orchestration-state', `Expected paused or completed run, received '${run?.status ?? 'missing'}'`);
   }
   if (run.status === 'paused' && (!run.pause?.code || !run.pause?.message)) {
     return failResult('orchestration-state', 'Paused run requires a stable pause code and message');
@@ -242,12 +224,10 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
   if (!stat?.isFile()) return failResult('orchestration-evidence', 'orchestration.json is missing');
   let run: any;
   try {
-    run = JSON.parse(fs.readFileSync(file, 'utf8'));
+    run = readRun(taskDir);
   } catch (error) {
-    return failResult('orchestration-evidence', `Invalid orchestration.json: ${String(error)}`);
-  }
-  if (isFailClosedLegacyPause(run)) {
-    return passResult('orchestration-evidence', 'Legacy orchestration evidence is preserved in a fail-closed pause');
+    const message = error instanceof OrchestrationStateError ? error.message : String(error);
+    return failResult('orchestration-evidence', `Invalid orchestration.json: ${message}`);
   }
   const policy = run.modelPolicy;
   if (
@@ -269,30 +249,8 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
     return failResult('orchestration-evidence', 'Run model policy source or recovery history is invalid');
   }
   for (const recovery of run.recoveryHistory) {
-    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;
-    const validClaudeCodeRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED_NO_MIGRATION'
-      && recovery.previousSchemaVersion === 3
+    const validClaudeCodeRecovery = recovery.code === 'CLIENT_CAPABILITY_ENABLED'
       && recovery.previousStatus === 'paused'
       && recovery.previousPause?.code === 'ORCHESTRATION_CLIENT_UNSUPPORTED'
       && recovery.client === 'claude-code'
@@ -304,9 +262,8 @@ function checkOrchestrationEvidence({ taskDir }: any): any {
       && guards?.receiptCount === 0
       && guards?.pendingDelegation === false
       && guards?.commitAuthorizationUnused === true
-      && guards?.completionEvidenceAbsent === true
-      && guards?.commitIntentAbsent === true;
-    if (!validModelRecovery && !validCapabilityRecovery && !validClaudeCodeRecovery) {
+      && guards?.completionEvidenceAbsent === true;
+    if (!validClaudeCodeRecovery) {
       return failResult('orchestration-evidence', 'Run recovery history contains invalid provenance');
     }
   }
@@ -376,12 +333,37 @@ 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 activatedCodex = ['activated', 'stage-completed', 'sealed', 'consumed'].includes(receipt.status);
         const host = receipt.hostEvidence;
+        const provenance = receipt.lifecycleProvenance;
         if (
-          host?.kind !== 'codex-lifecycle-v1'
-          || !exactText(host.hookDefinitionHash)
-          || !Number.isSafeInteger(host.startRevision)
-          || host.startRevision < 1
+          !provenance
+          || (activatedCodex && (
+            host?.kind !== 'codex-lifecycle-v2'
+            || host.protocolVersion !== provenance.protocolVersion
+            || host.packageVersion !== provenance.packageVersion
+            || host.internalExecutableBuildHash !== provenance.internalExecutableBuildHash
+            || host.lifecycleContractHash !== provenance.lifecycleContractHash
+            || host.hookDefinitionHash !== provenance.hookDefinitionHash
+            || host.hookSource !== provenance.hookSource
+            || host.hookSourcePathDigest !== provenance.hookSourcePathDigest
+            || host.hookSourceHash !== provenance.hookSourceHash
+            || host.capabilitySessionId !== provenance.capabilitySessionId
+            || receipt.parentId !== provenance.capabilitySessionId
+            || host.capabilityTurnId !== provenance.capabilityTurnId
+            || host.controllerInstanceDigest !== provenance.controllerInstanceDigest
+            || host.controlGeneration !== provenance.controlGeneration
+            || host.spawnToolUseId === provenance.capabilityToolUseId
+            || !exactText(host.spawnToolUseId)
+            || !Number.isFinite(Date.parse(host.spawnObservedAt ?? ''))
+            || !Number.isFinite(Date.parse(receipt.spawnDispatchedAt ?? ''))
+            || !Number.isFinite(Date.parse(receipt.activationDeadlineAt ?? ''))
+            || Date.parse(host.spawnObservedAt ?? '') < Date.parse(receipt.spawnDispatchedAt ?? '')
+            || Date.parse(host.spawnObservedAt ?? '') > Date.parse(receipt.activationDeadlineAt ?? '')
+            || !exactText(host.hookDefinitionHash)
+            || !Number.isSafeInteger(host.startRevision)
+            || host.startRevision < 1
+          ))
         ) {
           return failResult('orchestration-evidence', `Receipt '${receipt.id ?? '(unknown)'}' has invalid Codex start evidence`);
         }
@@ -510,6 +492,63 @@ function checkTaskMeta({ taskDir, config }: any): any {
   );
 }
 
+function checkRequiredPrDelivery({ taskDir, repositoryRoot, mode }: any): any {
+  const task = loadTask(taskDir);
+  if (!task.ok) return failResult('required-pr-delivery', task.message);
+  let projectConfig: any = {};
+  try {
+    const file = path.join(repositoryRoot, '.agents', '.airc.json');
+    if (safeStat(file)?.isFile()) projectConfig = JSON.parse(fs.readFileSync(file, 'utf8')) as any;
+  } catch {
+    return failResult('required-pr-delivery', 'Project configuration is invalid');
+  }
+  const flow = projectConfig.prFlow;
+  const status = String(task.metadata.pr_status || 'pending');
+  const prNumber = parsePrNumber(task.metadata.pr_number);
+  if (flow === 'disabled') return passResult('required-pr-delivery', 'Pull request delivery is disabled by project policy');
+  if (flow === 'required' && (status !== 'created' || prNumber === null)) {
+    return failResult('required-pr-delivery', 'Project policy requires a bound pull request before completion');
+  }
+  if (flow !== 'required' && status === 'pending') {
+    return failResult('required-pr-delivery', 'Pull request delivery is pending; create a PR or explicitly skip it');
+  }
+  if (status === 'created' && prNumber === null) {
+    return failResult('required-pr-delivery', 'Task claims a created pull request without a valid pr_number');
+  }
+  if (flow === 'required') {
+    if (mode === 'gate') {
+      return passResult('required-pr-delivery', 'Bound pull request shape is valid; merged-state inspection is reserved for hard preflight');
+    }
+    const inspected = inspectPlatformPullRequest(task.metadata.id, { cwd: repositoryRoot });
+    if (inspected.status === 'blocked') {
+      return blockedResult(
+        'required-pr-delivery',
+        inspected.error?.message || 'Unable to inspect the required pull request',
+        inspected.error?.code || 'PR_INSPECTION_BLOCKED'
+      );
+    }
+    const pullRequest = inspected.pullRequest;
+    const repository = inspected.platform.repository?.toLowerCase() || '';
+    const taskBranch = String(task.metadata.branch || '').trim();
+    if (inspected.status !== 'no-op' || !pullRequest || pullRequest.number !== prNumber) {
+      return failResult('required-pr-delivery', 'Bound pull request identity could not be verified');
+    }
+    if (
+      !repository
+      || pullRequest.repository.toLowerCase() !== repository
+      || pullRequest.base.repository.toLowerCase() !== repository
+      || (taskBranch && pullRequest.head.ref !== taskBranch)
+    ) {
+      return failResult('required-pr-delivery', 'Bound pull request identity does not match the task');
+    }
+    if (pullRequest.state !== 'closed' || !pullRequest.mergedAt || !pullRequest.mergeCommitSha) {
+      return failResult('required-pr-delivery', 'Project policy requires the bound pull request to be merged');
+    }
+    return passResult('required-pr-delivery', `Pull request delivery policy satisfied (merged PR #${prNumber})`);
+  }
+  return passResult('required-pr-delivery', `Pull request delivery policy satisfied (${status})`);
+}
+
 function validateTaskBranch(metadata: any): any {
   if (isBlank(metadata.branch)) {
     return null;
@@ -1600,7 +1639,14 @@ function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks: reque
     const checks = [];
     for (const [type, checkConfig] of Object.entries(verifyConfig.checks || {})) {
       if (checkConfig === null) continue;
-      const result = runCheck(type, { skillName, taskDir: path.resolve(taskDir), artifactFile, config: checkConfig }, shared);
+      const result = runCheck(type, {
+        mode,
+        skillName,
+        taskDir: path.resolve(taskDir),
+        artifactFile,
+        repositoryRoot: repoRoot,
+        config: checkConfig
+      }, shared);
       checks.push(result);
       if (result.status === "blocked") break;
     }
@@ -1611,7 +1657,16 @@ function verifyInProcess({ mode, skillName, taskDir, artifactFile, checks: reque
   const config = (verifyConfig.checks || {})[type];
   if (config === undefined) return { skill: skillName, ...failResult(type, `Unknown check type '${type}' for skill '${skillName}'.`) };
   if (config === null) return { skill: skillName, ...passResult(type, `Check '${type}' is disabled for skill '${skillName}'.`) };
-  return { skill: skillName, ...runCheck(type, { skillName, taskDir: path.resolve(taskDir), artifactFile, config }, shared) };
+  return {
+    skill: skillName,
+    ...runCheck(type, {
+      skillName,
+      taskDir: path.resolve(taskDir),
+      artifactFile,
+      repositoryRoot: repoRoot,
+      config
+    }, shared)
+  };
 }
 
 export { verifyInProcess };

package/lib/task/verification.ts

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

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

@@ -12,6 +12,7 @@ import type { WorkflowWarning } from './workflow-warnings.ts';
 import { captureTaskWriteMetadata, writeTask } from './write.ts';
 import type { TaskMutation, TaskOperationSummary, TaskWriteOptions } from './write.ts';
 import { allowsManualOverride } from './guard-override.ts';
+import { retryHintForWarning, type OperationWarning } from './operation-outcome.ts';
 
 type WarningSeverity = 'IMPORTANT' | 'ACTION_REQUIRED';
 type WarningStatus = 'open' | 'resolved' | 'ignored';
@@ -28,6 +29,12 @@ type WorkflowWarningIntentResult = {
   error: { code: string; message: string } | null;
 };
 
+type FinalizationWarningProjectionResult = Readonly<{
+  status: 'applied' | 'no-op' | 'failed';
+  changed: boolean;
+  error: { code: string; message: string } | null;
+}>;
+
 function failed(intent: WorkflowWarningIntent, code: string, message: string, taskId: string | null = null, entityId: string | null = null): WorkflowWarningIntentResult {
   return { status: 'failed', changed: false, intent: intent.kind, taskId, entityId, before: null, after: null, warnings: [], operations: [], error: { code, message } };
 }
@@ -140,5 +147,53 @@ function applyWorkflowWarningIntent(intent: WorkflowWarningIntent, options: Task
   };
 }
 
-export { applyWorkflowWarningIntent };
-export type { WarningSeverity, WarningStatus, WorkflowWarningIntent, WorkflowWarningIntentResult };
+function projectFinalizationWarning(
+  taskRef: string,
+  warning: OperationWarning & { status: 'open' | 'resolved'; resolvedAt: string | null },
+  options: TaskWriteOptions = {}
+): FinalizationWarningProjectionResult {
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return { status: 'failed', changed: false, error: { code: resolved.code, message: resolved.message } };
+  if (resolved.state !== 'completed') return { status: 'failed', changed: false, error: { code: 'TASK_STATE_MISMATCH', message: `task ${resolved.taskId} is ${resolved.state}, expected completed` } };
+  let content: string;
+  let rows: WorkflowWarning[];
+  try {
+    content = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    rows = parseWorkflowWarnings(content);
+  } catch (error) {
+    return { status: 'failed', changed: false, error: { code: 'WARNING_DOCUMENT_INVALID', message: error instanceof Error ? error.message : String(error) } };
+  }
+  const metadata = (options.metadataProvider ?? captureTaskWriteMetadata)();
+  const existing = rows.find((row) => row.step === warning.step && row.code === warning.code && row.target === warning.target);
+  const after: WorkflowWarning = existing
+    ? {
+      ...existing,
+      severity: warning.severity,
+      status: warning.status,
+      message: warning.message,
+      action: retryHintForWarning(warning),
+      resolvedAt: warning.resolvedAt || (warning.status === 'resolved' ? metadata.timestamp : ''),
+      resolution: warning.status === 'resolved' ? 'Resolved by a successful finalization retry' : ''
+    }
+    : {
+      id: nextWarningId(rows), time: metadata.timestamp, step: warning.step,
+      severity: warning.severity, code: warning.code, status: warning.status,
+      target: warning.target, message: warning.message, action: retryHintForWarning(warning),
+      resolvedAt: warning.resolvedAt || '', resolution: warning.status === 'resolved' ? 'Resolved by a successful finalization retry' : ''
+    };
+  if (existing && JSON.stringify(existing) === JSON.stringify(after)) return { status: 'no-op', changed: false, error: null };
+  const written = writeTask({
+    taskRef: resolved.taskId,
+    expectedState: 'completed',
+    mutations: [...sectionMutation(content), rowMutation(after)]
+  }, {
+    ...options,
+    taskLocation: { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskMdPath: resolved.taskMdPath, state: 'completed' },
+    metadataProvider: () => metadata
+  });
+  if (written.status === 'failed') return { status: 'failed', changed: false, error: { code: written.error.code, message: written.error.message } };
+  return { status: written.status === 'applied' ? 'applied' : 'no-op', changed: written.changed, error: null };
+}
+
+export { applyWorkflowWarningIntent, projectFinalizationWarning };
+export type { FinalizationWarningProjectionResult, WarningSeverity, WarningStatus, WorkflowWarningIntent, WorkflowWarningIntentResult };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.8",
+  "version": "0.9.9",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",
@@ -54,7 +54,7 @@
     "yaml": "^2.9.0"
   },
   "scripts": {
-    "build": "tsc -p tsconfig.json && node scripts/build.js && node scripts/build-inline.js",
+    "build": "node scripts/run-build.js",
     "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",

package/templates/.agents/QUICKSTART.en.md

@@ -20,14 +20,14 @@ This makes Git invoke the hooks in the project repository's `.git-hooks/` direct
 
 ## Development Checkout CLI Alignment
 
-When developing agent-infra from a source checkout, install dependencies and rebuild the local CLI before running lifecycle orchestration:
+When developing the agent-infra CLI from a source checkout, install dependencies and rebuild it as needed:
 
 ```bash
 npm install
 npm run build
 ```
 
-Lifecycle hooks prefer the checkout's `dist/bin/internal-cli.js` when it exists and fall back to `agent-infra-internal` on `PATH` otherwise. Rebuild after CLI source changes. If shell commands must also resolve to this checkout, link it and compare the active version with the package version:
+Lifecycle hooks always invoke `agent-infra-internal` through `PATH`; they do not implicitly switch to checkout source or `dist`. In a Codex sandbox, the controller's `PATH`-first shim is authoritative and binds the controller's selected executable. Skills, rules, hooks, and task data continue to come from the current checkout. The commands above develop the CLI itself and do not change hook executable selection. If shell commands must also resolve to this checkout, link it and compare the active version with the package version:
 
 ```bash
 npm link

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

@@ -20,14 +20,14 @@ git config core.hooksPath .git-hooks
 
 ## 开发检出中的 CLI 对齐
 
-从源码检出开发 agent-infra 时，请先安装依赖并重新构建本地 CLI，再运行生命周期编排：
+从源码检出开发 agent-infra CLI 时，请按需安装依赖并重新构建 CLI：
 
 ```bash
 npm install
 npm run build
 ```
 
-本地 `dist/bin/internal-cli.js` 存在时，生命周期 hook 会优先使用它；不存在时则回退到 `PATH` 上的 `agent-infra-internal`。修改 CLI 源码后需要重新构建。如果 shell 命令也必须解析到当前检出，请建立链接并比较当前版本与包版本：
+生命周期 hook 始终通过 `PATH` 调用 `agent-infra-internal`，不会隐式切换到当前检出的 source 或 `dist`。在 Codex sandbox 中，controller 放在 `PATH` 首位的 shim 是权威入口，并绑定 controller 选定的 executable。skills、rules、hooks 和任务数据仍从当前检出读取。上面的命令只用于开发 CLI 本身，不会改变 hook 的 executable 选择。如果 shell 命令也必须解析到当前检出，请建立链接并比较当前版本与包版本：
 
 ```bash
 npm link

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

@@ -1,13 +1,9 @@
 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] : '';
@@ -17,22 +13,6 @@ if (client !== 'claude-code' && client !== 'codex') {
 }
 
 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' };
 }
 
@@ -125,7 +105,7 @@ process.stdin.on('end', () => {
         input: JSON.stringify(normalized),
         shell,
         stdio: ['pipe', 'pipe', 'pipe'],
-        timeout: 15_000
+        timeout: 30_000
       });
       process.stdout.write(output);
     } catch (error) {

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

@@ -10,7 +10,7 @@
 
 ## Recovery
 
-`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.
+`orchestration.json` is the detailed state source. A current run persists complete policy, append-only recovery, build/contract/hook-source/controller provenance, and activation monotonic timestamps. Readers accept only the complete structure emitted by the current writer; unknown fields, missing fields, invalid provenance, and old runs fail closed without rewriting. Finish or clear every active run before upgrading agent-infra. An expired prepared orphan may be explicitly recovered only with the exact task fingerprint, no consumed authorization, and no matching unconsumed active lifecycle evidence.
 
 ## Codex Host and Capability
 

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

@@ -10,7 +10,7 @@
 
 ## 恢复语义
 
-`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 一律失败关闭。
+`orchestration.json` 是详细状态源。current run 保存完整策略、append-only 恢复历史、build/contract/hook source/controller provenance 与 activation 单调时钟。读取时只接受当前 writer 的完整结构；未知字段、缺失字段、非法 provenance 或旧 run 一律失败关闭且不改写。升级 agent-infra 前必须完成或清空所有 active run。prepared orphan 只允许在 deadline 已过、task fingerprint 精确不变、无 authorization 消耗且无匹配的未消费 active lifecycle evidence 时显式恢复。
 
 ## Codex 宿主与 capability
 

package/templates/.agents/rules/task-management.en.md

@@ -28,7 +28,7 @@ Map user intent to the corresponding workflow command:
 - Historical `gemini` / `gemini-cli` remain read-only for `ai task log` rendering and are not writable
 - Manual-step exception: no matter which agent is used, a human-made decision is always declared as `human`
 
-The six internal commands (`task-event` / `task-lifecycle` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`) hard-validate `--agent` against a whitelist: they accept a short token, a long name, or `human`, and reject non-standard values with the matching `*_PAYLOAD_INVALID` error; long names are normalized to the short token before being persisted or forwarded. The `ai task log` renderer keeps unknown tokens grouped as `human` but appends a visible `(unknown)` marker.
+The seven internal commands (`task-event` / `task-lifecycle` / `task-finalization` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`) hard-validate `--agent` against a whitelist: they accept a short token, a long name, or `human`, and reject non-standard values with the matching `*_PAYLOAD_INVALID` error; long names are normalized to the short token before being persisted or forwarded. The `ai task log` renderer keeps unknown tokens grouped as `human` but appends a visible `(unknown)` marker.
 
 ## State Snapshot and Completion Verification Entrypoints
 
@@ -68,7 +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.
+- **Commit execution boundary**: the commit skill must not hand-write task Activity Log, review anchors, receipts, or checkpoints. Task-bound direct and orchestrated modes both call the single `commit-operation.execute`; taskless direct is allowed only for `TASK_CONTEXT_NOT_FOUND` and creates no task-state side effects.
 - `{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

@@ -28,7 +28,7 @@
 - 历史 `gemini` / `gemini-cli` 仅保留 `ai task log` 渲染兼容，不接受写入
 - 人工步骤例外：无论使用哪个 Agent，只要是人做的决定，统一声明 `human`
 
-六个内部命令（`task-event` / `task-lifecycle` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`）对 `--agent` 做白名单硬校验：接受短名、长名或 `human`，非标准值返回对应 `*_PAYLOAD_INVALID` 错误；长名在落库/透传前归一化为短名。渲染端 `ai task log` 对无法识别的 token 保留 `human` 归类并附加 `(unknown)` 标记。
+七个内部命令（`task-event` / `task-lifecycle` / `task-finalization` / `platform-issue` / `platform-comment` / `platform-pr` / `task-orchestration`）对 `--agent` 做白名单硬校验：接受短名、长名或 `human`，非标准值返回对应 `*_PAYLOAD_INVALID` 错误；长名在落库/透传前归一化为短名。渲染端 `ai task log` 对无法识别的 token 保留 `human` 归类并附加 `(unknown)` 标记。
 
 ## 状态快照与完成验证入口
 
@@ -70,7 +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 只闭合活动日志，不构成提交成功证据。
+- **Commit 执行边界**：commit 技能不得手写 task Activity Log、review anchor、receipt 或 checkpoint。task-bound direct 与 orchestrated 都调用唯一 `commit-operation.execute`；taskless direct 只在 `TASK_CONTEXT_NOT_FOUND` 时允许，且不产生任务状态副作用。
 - `{基名}` 指该 SKILL 既有 done 条目的 action 文本，含 `(Round {N})`（如 `Plan Task (Round 1)`）。
   started 与 done 共用同一 `{基名}` 才能配对。