@fitlab-ai/agent-infra 0.9.8 → 0.9.10

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,34 @@ 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.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 +489,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 +1636,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 +1654,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.10",
   "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,18 +20,17 @@ 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. To run the CLI from the current checkout, invoke the build output directly and compare its version with the package version. Do not run `npm link` on the host: it writes to npm's global prefix and can shadow a stable installation managed by Homebrew or npm.
 
 ```bash
-npm link
-ai version --raw
+node ./dist/bin/cli.js version --raw
 node -p "'v' + require('./package.json').version"
 ```
 

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

@@ -20,18 +20,17 @@ 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 选择。如需运行当前检出的 CLI，请直接执行构建产物并比较当前版本与包版本。不要在宿主机上执行 `npm link`：它会写入 npm 全局前缀，并可能遮蔽由 Homebrew 或 npm 安装的稳定版。
 
 ```bash
-npm link
-ai version --raw
+node ./dist/bin/cli.js version --raw
 node -p "'v' + require('./package.json').version"
 ```
 

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

@@ -12,6 +12,7 @@ so you can quickly find "which ones to read" without opening each file.
 - [`next-step-output.md`](next-step-output.md) — "Next step" output rules: task short-id rendering and the `Completed at` trailer.
 - [`version-stamp.md`](version-stamp.md) — How and when to stamp `agent_infra_version`.
 - [`debugging-guide.md`](debugging-guide.md) — Structured debugging flow: gather evidence → form hypothesis → verify hypothesis → fix the root cause; no blind patch-and-retry.
+- [`compatibility-policy.md`](compatibility-policy.md) — Compatibility by exception: admission evidence, implementation boundaries, exit conditions, and lifecycle review requirements.
 
 ## Issue / PR
 

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

@@ -11,6 +11,7 @@
 - [`next-step-output.md`](next-step-output.md) — 「下一步」输出规则：任务短号渲染与 `Completed at` 收尾行。
 - [`version-stamp.md`](version-stamp.md) — `agent_infra_version` 版本戳的取值命令与写入时机。
 - [`debugging-guide.md`](debugging-guide.md) — 结构化调试流程：收集证据→形成假设→验证假设→修复根因，禁止盲目改代码重试。
+- [`compatibility-policy.md`](compatibility-policy.md) — 兼容性默认关闭：准入证据、实现边界、退出条件与生命周期审查要求。
 
 ## Issue / PR
 

package/templates/.agents/rules/compatibility-policy.en.md

@@ -0,0 +1,39 @@
+# Compatibility Policy
+
+This rule governs compatibility decisions during analysis, planning, implementation, and review. Support the current contract by default. Compatibility is an exception budget that requires evidence and an exit condition; it is not a synonym for safety.
+
+## What Counts as Compatibility
+
+Compatibility logic includes accepting or writing multiple generations of schemas, fields, states, or commands; retaining legacy aliases, adapters, wrappers, or shims; migrating data in the normal runtime path; falling back to different semantics based on an old format; or maintaining parallel facts and tests for old callers.
+
+Current-operation idempotency and crash recovery, explicit platform or permission capability branches, fail-closed handling of unknown state, and user-required public multi-version contracts are not inherently legacy compatibility. Do not use those labels to expand support for an old protocol.
+
+## Admission Gate
+
+Add or extend compatibility only when the task or an existing public contract explicitly requires it and the artifact records all four items:
+
+1. **Subject**: concrete consumers, released versions, or stored data still using the old contract.
+2. **Necessity**: why an atomic cutover, one-time conversion, or actionable failure is insufficient.
+3. **Window**: a version, date, or verifiable endpoint for the compatibility period.
+4. **Exit**: removal conditions, ownership, and the code, tests, and documentation to delete.
+
+If any item is missing, compatibility is unauthorized scope expansion. Implement the current contract, fail closed with an actionable repair message for old input, or perform an explicit one-time conversion outside the main path.
+
+## Implementation Boundaries
+
+- Keep one canonical write format and one source of truth. Do not dual-write, maintain shadow state, or try the new path before silently falling back to the old path.
+- Concentrate an approved conversion at one boundary and immediately enter the current model; business logic must not understand several historical versions.
+- Use warnings only when the primary action remains correct and the user can retry an ancillary operation. Never hide uncertainty about identity, authorization, data interpretation, or side-effect correctness.
+- When removing an old capability, remove its adapters, branches, fixtures, tests, and migration documentation together. Do not add negative tests that permanently remember deleted behavior.
+- Never guess the meaning of unknown state. Preserve it, stop writes, and provide rebuild or manual-repair guidance.
+
+## Lifecycle Requirements
+
+- **Analysis**: separate explicit compatibility requirements from model speculation and identify real consumers or stored data. State current-only when evidence is absent.
+- **Plan**: for approved compatibility, identify the boundary, single conversion point, window, and deletion plan. Do not present a compatibility layer as the default low-risk option.
+- **Implementation**: implement only the approved compatibility budget. Do not preserve an unapproved old branch “just in case.”
+- **Review**: verify the four admission items, single source of truth, and exit condition. Flag unauthorized compatibility, indefinite shims, dual writes, and runtime-path migrations as scope and maintainability problems.
+
+## Existing Compatibility Logic
+
+During an ordinary task, record out-of-scope compatibility logic and its risk without deleting it. A dedicated simplification task should first inventory consumers and stored data, then process items in this order: remove now, warn then remove, retain temporarily.