@fitlab-ai/agent-infra 0.9.15 → 0.11.0

package/lib/task/short-id.ts

@@ -329,14 +329,18 @@ function mutateShortIdRegistryAt(
   activeDir: string,
   width: number,
   taskId: string,
-  requested: ShortIdMutationEffect
+  requested: ShortIdMutationEffect,
+  onlyReleaseWhenInactive = false,
+  pruneOrphans = true
 ): ShortIdMutationResult {
   const registryPath = path.join(activeDir, REGISTRY_NAME);
   return withRegistryLock(activeDir, () => {
     const registry = readRegistryStrict(registryPath, width);
     const original = JSON.stringify(registry.ids);
-    for (const [key, candidate] of Object.entries(registry.ids)) {
-      if (candidate !== taskId && !fs.existsSync(path.join(activeDir, candidate, 'task.md'))) delete registry.ids[key];
+    if (pruneOrphans) {
+      for (const [key, candidate] of Object.entries(registry.ids)) {
+        if (candidate !== taskId && !fs.existsSync(path.join(activeDir, candidate, 'task.md'))) delete registry.ids[key];
+      }
     }
     const existing = Object.entries(registry.ids).find(([, candidate]) => candidate === taskId);
     let result: ShortIdMutationResult;
@@ -356,8 +360,13 @@ function mutateShortIdRegistryAt(
         result = { effect: 'allocated', shortId: key, changed: true };
       }
     } else if (requested === 'release') {
-      if (!existing) result = { effect: 'unchanged', shortId: null, changed: false };
-      else { delete registry.ids[existing[0]]; result = { effect: 'released', shortId: existing[0], changed: true }; }
+      const taskIsActive = fs.existsSync(path.join(activeDir, taskId, 'task.md'));
+      if (!existing || (onlyReleaseWhenInactive && taskIsActive)) {
+        result = { effect: 'unchanged', shortId: existing?.[0] ?? null, changed: false };
+      } else {
+        delete registry.ids[existing[0]];
+        result = { effect: 'released', shortId: existing[0], changed: true };
+      }
     } else result = { effect: 'unchanged', shortId: existing ? existing[0] : null, changed: false };
     const changed = original !== JSON.stringify(registry.ids);
     if (changed) writeRegistry(registryPath, registry);
@@ -365,6 +374,18 @@ function mutateShortIdRegistryAt(
   });
 }
 
+function releaseStaleShortIdRegistry(repoRoot: string, taskId: string): ShortIdMutationResult {
+  const activeDir = path.join(repoRoot, '.agents', 'workspace', 'active');
+  return mutateShortIdRegistryAt(
+    activeDir,
+    configuredShortIdLength(repoRoot),
+    taskId,
+    'release',
+    true,
+    false
+  );
+}
+
 function executeShortIdCommand(request: ShortIdCommandRequest): ShortIdCommandResult {
   try {
     if (!Number.isInteger(request.shortIdLength) || request.shortIdLength < 1) {
@@ -550,6 +571,7 @@ export {
   inspectShortIdRegistry,
   configuredShortIdLength,
   mutateShortIdRegistry,
+  releaseStaleShortIdRegistry,
   executeShortIdCommand
 };
 export type {

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

@@ -293,7 +293,7 @@ function withTaskExecutionLock<T>(
     return value;
   } catch (error) {
     if (error instanceof TaskExecutionLockError) throw error;
-    if (error instanceof Error && error.name === 'OrchestrationStateError') throw error;
+    if (error instanceof Error && ['OrchestrationStateError', 'ArtifactRecoveryError'].includes(error.name)) throw error;
     throw new TaskExecutionLockError(
       'ORCHESTRATION_LOCK_FAILED',
       'lifecycle task lock operation failed',

package/lib/task/verification-engine.ts

@@ -48,6 +48,7 @@ import { manualValidationFinalSummaryProjectionMatches } from "./manual-validati
 import { readManualValidationCompletion } from "./manual-validation-completion.ts";
 import { sha256File } from "./artifact-receipts.ts";
 import { summaryCommentState } from "../platform/pr-summary.ts";
+import { taskIssueIdentity } from "../platform/task-identities.ts";
 
 const TASK_ENUMS = {
   type: ["feature", "bugfix", "refactor", "docs", "chore"],
@@ -100,8 +101,6 @@ const sharedUtils = {
   failResult,
   blockedResult,
   safeStat,
-  parseIssueNumber,
-  parsePrNumber
 };
 
 async function runCheck(type: any, context: any, shared: any): Promise<any> {
@@ -361,8 +360,8 @@ function checkTaskMeta({ taskDir, config, repositoryRoot }: any): any {
     );
   }
 
-  if (config.require_issue_number && !parseIssueNumber(metadata.issue_number)) {
-    return failResult("task-meta", "Expected a valid issue_number in task metadata");
+  if (config.require_platform_issue_identity && !taskIssueIdentity(metadata)) {
+    return failResult("task-meta", "Expected a valid platform_issue_identity in task metadata");
   }
 
   if (config.require_completed_at && isBlank(metadata.completed_at)) {
@@ -1376,19 +1375,6 @@ function getCheckedRequirements(content: any): any {
     .map((match: any) => match[1].trim());
 }
 
-function parseIssueNumber(value: any): any {
-  if (isBlank(value) || value === "N/A") {
-    return null;
-  }
-
-  const match = String(value).match(/\d+/);
-  return match ? Number(match[0]) : null;
-}
-
-function parsePrNumber(value: any): any {
-  return parseIssueNumber(value);
-}
-
 // === Utilities ===
 
 function normalizeContent(text: any): any {

package/lib/task/verification-types.ts

@@ -11,8 +11,6 @@ export type VerificationShared = {
   failResult: (type: string, message: string, failType?: string) => VerificationCheckResult;
   blockedResult: (type: string, message: string, failType?: string) => VerificationCheckResult;
   safeStat: (filePath: string) => fs.Stats | null;
-  parseIssueNumber: (value: unknown) => number | null;
-  parsePrNumber: (value: unknown) => number | null;
 };
 
 type VerificationStatus = 'pass' | 'fail' | 'blocked';

package/lib/task/workflow-command.ts

@@ -1,8 +1,9 @@
 export const TASK_WORKFLOW_COMMANDS = Object.freeze({
   'artifact-inspect': ['task-artifact', 'inspect'],
   'artifact-init': ['task-artifact', 'init'],
-  'artifact-repair': ['task-artifact', 'repair'],
+  'artifact-preflight': ['task-artifact', 'preflight'],
   'artifact-finalize-local': ['task-artifact', 'finalize-local'],
+  'review-preflight': ['task-review', 'preflight'],
   'review-finalize-summary': ['task-review', 'finalize-summary'],
   event: ['task-event', null],
   'ledger-finding-response': ['task-ledger', 'finding-respond'],

package/lib/task/workflow-dispatch.ts

@@ -0,0 +1,171 @@
+import { reconcileTaskInvalidation } from './invalidation-command.ts';
+import { applyLedgerIntent } from './ledger-intents.ts';
+import type { LedgerIntent } from './ledger-intents.ts';
+import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
+import type { TaskWorkflowOperation } from './workflow-command.ts';
+import { applyWorkflowWarningIntent } from './workflow-warning-intents.ts';
+import type { WorkflowWarningIntent } from './workflow-warning-intents.ts';
+
+export type WorkflowDispatchResult = Readonly<Record<string, unknown>>;
+
+type OptionValues = Readonly<Record<string, string | boolean>>;
+type DispatchFailure = Readonly<{
+  status: 'failed';
+  changed: false;
+  error: Readonly<{ code: string; message: string }>;
+}>;
+
+function failed(code: string, message: string): DispatchFailure {
+  return { status: 'failed', changed: false, error: { code, message } };
+}
+
+function isFailure(value: unknown): value is DispatchFailure {
+  return Boolean(value) && typeof value === 'object' && (value as { status?: unknown }).status === 'failed';
+}
+
+function options(
+  args: readonly string[],
+  allowed: Readonly<Record<string, string>>
+): OptionValues | DispatchFailure {
+  const values: Record<string, string | boolean> = {};
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (flag === '--dry-run') {
+      if (!Object.hasOwn(allowed, flag) || values[flag] !== undefined) return failed('TASK_WORKFLOW_PAYLOAD_INVALID', `invalid option '${flag}'`);
+      values[flag] = true;
+      continue;
+    }
+    const key = allowed[flag];
+    if (!key || values[flag] !== undefined) return failed('TASK_WORKFLOW_PAYLOAD_INVALID', `invalid option '${flag}'`);
+    const value = args[++index];
+    if (value === undefined || value.startsWith('--')) return failed('TASK_WORKFLOW_PAYLOAD_INVALID', `option '${flag}' requires a value`);
+    if (flag === '--needs-implementation' && value !== 'true' && value !== 'false') {
+      return failed('TASK_WORKFLOW_PAYLOAD_INVALID', "option '--needs-implementation' must be true or false");
+    }
+    values[flag] = value;
+  }
+  return values;
+}
+
+function value(values: OptionValues, flag: string): string | undefined {
+  const candidate = values[flag];
+  return typeof candidate === 'string' ? candidate : undefined;
+}
+
+function required(values: OptionValues, flags: readonly string[]): DispatchFailure | null {
+  const missing = flags.find((flag) => value(values, flag) === undefined);
+  return missing ? failed('TASK_WORKFLOW_PAYLOAD_INVALID', `option '${missing}' is required`) : null;
+}
+
+function resultForLock(error: unknown): WorkflowDispatchResult {
+  if (error instanceof TaskExecutionLockError) return failed(error.code, error.message);
+  throw error;
+}
+
+function ledgerIntent(operation: TaskWorkflowOperation, args: readonly string[]): LedgerIntent | DispatchFailure {
+  const [taskRef, kind] = args;
+  const mappings: Partial<Record<TaskWorkflowOperation, {
+    kind: LedgerIntent['kind']; required: readonly string[]; flags: Readonly<Record<string, string>>;
+  }>> = {
+    'ledger-finding-response': {
+      kind: 'finding-respond', required: ['--id', '--round', '--status', '--evidence'],
+      flags: { '--id': 'id', '--round': 'round', '--status': 'status', '--evidence': 'evidence', '--dry-run': 'dryRun' }
+    },
+    'ledger-finding-review': {
+      kind: 'finding-review', required: ['--id', '--status', '--evidence'],
+      flags: { '--id': 'id', '--status': 'status', '--evidence': 'evidence', '--needs-implementation': 'needsImplementation', '--dry-run': 'dryRun' }
+    },
+    'ledger-finding-upsert': {
+      kind: 'finding-upsert', required: ['--stage', '--review-artifact', '--ordinal', '--severity', '--evidence'],
+      flags: { '--stage': 'stage', '--review-artifact': 'reviewArtifact', '--ordinal': 'ordinal', '--severity': 'severity', '--evidence': 'evidence', '--dry-run': 'dryRun' }
+    },
+    'decision-next-id': { kind: 'decision-next-id', required: [], flags: {} },
+    'decision-upsert': {
+      kind: 'decision-upsert', required: ['--id', '--stage', '--artifact'],
+      flags: { '--id': 'id', '--stage': 'stage', '--artifact': 'artifact', '--needs-implementation': 'needsImplementation', '--dry-run': 'dryRun' }
+    }
+  };
+  const mapping = mappings[operation];
+  if (!mapping || !taskRef || kind === undefined) return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'task workflow ledger request is invalid');
+  const values = options(args, mapping.flags);
+  if (isFailure(values)) return values;
+  const missing = required(values, mapping.required);
+  if (missing) return missing;
+  const dryRun = values['--dry-run'] === true;
+  if (mapping.kind === 'decision-next-id') return { kind: mapping.kind, taskRef };
+  if (mapping.kind === 'finding-respond') return {
+    kind: mapping.kind, taskRef, id: value(values, '--id')!, round: Number(value(values, '--round')),
+    status: value(values, '--status') as never, evidence: value(values, '--evidence')!, ...(dryRun ? { dryRun } : {})
+  } as LedgerIntent;
+  if (mapping.kind === 'finding-review') return {
+    kind: mapping.kind, taskRef, id: value(values, '--id')!, status: value(values, '--status') as never,
+    evidence: value(values, '--evidence')!, ...(value(values, '--needs-implementation') === 'true' ? { needsImplementation: true } : {}),
+    ...(dryRun ? { dryRun } : {})
+  } as LedgerIntent;
+  if (mapping.kind === 'finding-upsert') return {
+    kind: mapping.kind, taskRef, stage: value(values, '--stage') as never, reviewArtifact: value(values, '--review-artifact')!,
+    ordinal: Number(value(values, '--ordinal')), severity: value(values, '--severity') as never, evidence: value(values, '--evidence')!,
+    ...(dryRun ? { dryRun } : {})
+  } as LedgerIntent;
+  return {
+    kind: mapping.kind, taskRef, id: value(values, '--id')!, stage: value(values, '--stage') as never,
+    artifact: value(values, '--artifact')!, ...(value(values, '--needs-implementation') === 'true' ? { needsImplementation: true } : {}),
+    ...(dryRun ? { dryRun } : {})
+  } as LedgerIntent;
+}
+
+function warningIntent(args: readonly string[]): WorkflowWarningIntent | DispatchFailure {
+  const [taskRef, kind] = args;
+  if (!taskRef || kind !== 'add') return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'task workflow warning request is invalid');
+  const values = options(args, {
+    '--step': 'step', '--severity': 'severity', '--code': 'code', '--target': 'target',
+    '--message': 'message', '--action': 'action', '--dry-run': 'dryRun'
+  });
+  if (isFailure(values)) return values;
+  const missing = required(values, ['--step', '--severity', '--code', '--target', '--message', '--action']);
+  if (missing) return missing;
+  return {
+    kind: 'add', taskRef, step: value(values, '--step')!, severity: value(values, '--severity') as never,
+    code: value(values, '--code')!, target: value(values, '--target')!, message: value(values, '--message')!,
+    action: value(values, '--action')!, ...(values['--dry-run'] === true ? { dryRun: true } : {})
+  } as WorkflowWarningIntent;
+}
+
+/**
+ * The caller has already selected and authorized the execution boundary.
+ * This function deliberately invokes task domains in that process: starting a
+ * second CLI process would discard the broker binding and could misclassify a
+ * sandbox process with cleared environment variables as direct-host.
+ */
+export function dispatchWorkflowCommand(
+  repoRoot: string,
+  operation: TaskWorkflowOperation,
+  args: readonly string[]
+): WorkflowDispatchResult {
+  const taskRef = args[0];
+  if (!taskRef) return failed('TASK_WORKFLOW_PAYLOAD_INVALID', 'task ref is required');
+  try {
+    if (operation === 'invalidation-reconcile') {
+      const values = options(args, { '--max-targets': 'maxTargets', '--dry-run': 'dryRun' });
+      if (isFailure(values)) return values;
+      const maxTargets = value(values, '--max-targets');
+      if (maxTargets !== undefined && (!Number.isSafeInteger(Number(maxTargets)) || Number(maxTargets) < 1)) {
+        return failed('TASK_WORKFLOW_PAYLOAD_INVALID', '--max-targets must be a positive integer');
+      }
+      return withTaskExecutionLock(repoRoot, taskRef, 'task-invalidation.reconcile', () => reconcileTaskInvalidation(taskRef, {
+        repoRoot, ...(maxTargets === undefined ? {} : { maxTargets: Number(maxTargets) }),
+        ...(values['--dry-run'] === true ? { dryRun: true } : {})
+      }));
+    }
+    if (operation === 'warning-add') {
+      const intent = warningIntent(args);
+      if (isFailure(intent)) return intent;
+      return withTaskExecutionLock(repoRoot, taskRef, 'task-warning.add', () => applyWorkflowWarningIntent(intent, { repoRoot }));
+    }
+    const intent = ledgerIntent(operation, args);
+    if (isFailure(intent)) return intent;
+    return withTaskExecutionLock(repoRoot, taskRef, `task-ledger.${intent.kind}`, () => applyLedgerIntent(intent, { repoRoot }));
+  } catch (error) {
+    return resultForLock(error);
+  }
+}

package/lib/version.ts

@@ -1,5 +1,4 @@
 import { existsSync, readFileSync } from 'node:fs';
-import semver from 'semver';
 
 const packageJsonUrl = [
   new URL('../package.json', import.meta.url),
@@ -13,22 +12,9 @@ if (!packageJsonUrl) {
 const { version } = JSON.parse(readFileSync(packageJsonUrl, 'utf8'));
 const VERSION = `v${version}`;
 const AGENT_INFRA_VERSION_PATTERN = /^v\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
-const LEGACY_COMPATIBILITY_CUTOFF_VERSION = '1.0.0';
 
 function isValidAgentInfraVersion(value: unknown): value is string {
   return typeof value === 'string' && AGENT_INFRA_VERSION_PATTERN.test(value);
 }
 
-function isLegacyCompatibilityEnabled(runtimeVersion = VERSION): boolean {
-  const normalized = runtimeVersion.startsWith('v') ? runtimeVersion.slice(1) : runtimeVersion;
-  const parsed = semver.valid(normalized);
-  return parsed !== null && semver.lt(parsed, LEGACY_COMPATIBILITY_CUTOFF_VERSION);
-}
-
-function legacyCompatibilityError(resource: string, runtimeVersion = VERSION): Error & { code: string } {
-  return Object.assign(new Error(
-    `PLATFORM_IDENTITY_LEGACY_UNSUPPORTED: ${resource} requires migration to the current schema before v${LEGACY_COMPATIBILITY_CUTOFF_VERSION} runtime ${runtimeVersion}`
-  ), { code: 'PLATFORM_IDENTITY_LEGACY_UNSUPPORTED' });
-}
-
-export { LEGACY_COMPATIBILITY_CUTOFF_VERSION, VERSION, isLegacyCompatibilityEnabled, isValidAgentInfraVersion, legacyCompatibilityError };
+export { VERSION, isValidAgentInfraVersion };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fitlab-ai/agent-infra",
-  "version": "0.9.15",
+  "version": "0.11.0",
   "description": "Bootstrap tool for AI multi-tool collaboration infrastructure — works with Claude Code, Codex, Antigravity CLI, and OpenCode",
   "license": "MIT",
   "type": "module",

package/templates/.agents/rules/create-issue.en.md

@@ -9,6 +9,6 @@ agent-infra-internal platform-issue create {task-id} --agent {standard-agent-tok
 agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} --status waiting-for-triage --assignees current --milestone initial --issue-type --fields
 ```
 
-The core reads only persisted task identity, title, type, description, and requirements, and reuses deterministic `ai task issue-body` rendering. It owns template selection, upstream/capabilities, duplicate prevention, POST outcome boundaries, response validation, and atomic `issue_number` binding.
+The core reads only persisted task identity, title, type, description, and requirements, and reuses deterministic `ai task issue-body` rendering. It owns template selection, upstream/capabilities, duplicate prevention, POST outcome boundaries, response validation, and atomic `platform_issue_identity` binding.
 
 `planned|applied|no-op|degraded` exit 0, `failed` exits 1, and `blocked` exits 2. Callers must not fall back to direct platform CLI or GraphQL orchestration.

package/templates/.agents/rules/create-issue.zh-CN.md

@@ -8,7 +8,7 @@
 agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
 ```
 
-命令只从已落盘 task.md 读取身份、标题、类型、描述与需求，并复用 `ai task issue-body` 的确定性正文渲染。它负责模板选择、upstream/capability、已有绑定检查、非幂等 POST 边界、响应身份校验及通过任务写入内核回写 `issue_number`。
+命令只从已落盘 task.md 读取身份、标题、类型、描述与需求，并复用 `ai task issue-body` 的确定性正文渲染。它负责模板选择、upstream/capability、已有绑定检查、非幂等 POST 边界、响应身份校验及通过任务写入内核回写 `platform_issue_identity`。
 
 创建后的初始元数据使用同一适配层同步：
 

package/templates/.agents/rules/issue-sync.en.md

@@ -11,20 +11,30 @@
 | `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
 | `summary` | `<!-- sync-issue:{task-id}:summary -->` |
 | `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+| `recoveryAction` | `<!-- sync-issue:{task-id}:recovery-action:{action-id} -->` |
+| `recoveryPrepare` | `<!-- sync-issue:{task-id}:recovery-prepare:{commit-id} -->` |
+| `recoveryCommit` | `<!-- sync-issue:{task-id}:recovery-commit:{commit-id} -->` |
 
-`pr-review` content is synced only as an Issue artifact comment (via the `artifact` / `artifactChunk` markers) and is never a `restore-task` recovery source; restore still accepts only an Issue number and reads only registered Issue markers, with no PR source.
+`pr-review` content is synced only as an Issue artifact comment (via the `artifact` / `artifactChunk` markers) and is never a `restore-task` recovery source; restore still accepts only an Issue token and reads only registered Issue markers, with no PR source.
 
 Comments use `platform-comment`; Issue resources use `platform-issue`:
 
 ```bash
+agent-infra-internal platform-comment list --issue <issue-token> [--cwd <path>]
+agent-infra-internal platform-comment recover --issue <issue-token> --task-id <TASK-id> \
+  --output <.agents/workspace/.restore-staging-*/task.md> [--cwd <path>]
 agent-infra-internal platform-issue inspect {task-id}
 agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
-agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {standard-agent-token}
+agent-infra-internal platform-issue bind {task-id} --issue {issue-token} --agent {standard-agent-token}
 agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} {desired-state-flags}
 ```
 
 The core owns status/in labels, assignees, milestones, Issue Type, pinned fields, requirements, state, capabilities, dry-run, retries, errors, and idempotency. Omitted flags preserve values; `none` explicitly clears them. Status labels converge to at most one, and ambiguous requirement identity fails closed.
 
+The task comment synchronizes only a deterministic current-task projection. Process sections such as the Activity Log, Artifact Lifecycle Receipts, and invalidation records are carried by the recovery transaction. Byte preflight and platform verification consume the same final rendered UTF-8 body.
+
+Recovery comments use `recovery-action`, `recovery-prepare`, and `recovery-commit` markers with a stable recovery id and a body file. Task sync publishes prepare, action, a task snapshot that is written and re-read, and then commit. Replaying identical content is a no-op; conflicting immutable content fails with `RECOVERY_IMMUTABLE_CONFLICT`. Restore accepts only an author-consistent, complete, phase/digest/marker-valid transaction bound to the current task comment body SHA-256.
+
 PR event `in:` synchronization uses `agent-infra-internal platform-pr sync-in-labels --pr <N> [--cwd <path>]`. PR files are the event evidence; a unique closing Issue is written and re-read before the PR. Zero or multiple closing Issues update only the PR and return `degraded`; unknown side effects or failed convergence return `blocked` with `IN_LABEL_SYNC_PARTIAL`.
 
 `planned|applied|no-op|degraded` exit 0; `failed` exits 1; `blocked` exits 2.

package/templates/.agents/rules/issue-sync.zh-CN.md

@@ -13,10 +13,13 @@
 | `artifactChunk` | `<!-- sync-issue:{task-id}:{artifact-stem}:{part}/{total} -->` |
 | `summary` | `<!-- sync-issue:{task-id}:summary -->` |
 | `cancel` | `<!-- sync-issue:{task-id}:cancel -->` |
+| `recoveryAction` | `<!-- sync-issue:{task-id}:recovery-action:{action-id} -->` |
+| `recoveryPrepare` | `<!-- sync-issue:{task-id}:recovery-prepare:{commit-id} -->` |
+| `recoveryCommit` | `<!-- sync-issue:{task-id}:recovery-commit:{commit-id} -->` |
 
 `prSummary` 属于 `.agents/rules/pr-sync.md`，本规则不实现 PR 聚合。
 
-`pr-review` 原文只通过 `artifact` / `artifactChunk` marker 同步为 Issue artifact 评论，不作为 `restore-task` 恢复来源；恢复仍只接受 Issue 编号并只读注册的 Issue marker，不新增 PR 来源。
+`pr-review` 原文只通过 `artifact` / `artifactChunk` marker 同步为 Issue artifact 评论，不作为 `restore-task` 恢复来源；恢复仍只接受 Issue 原始 token 并只读注册的 Issue marker，不新增 PR 来源。
 
 ## 平台 intent
 
@@ -24,15 +27,20 @@
 
 ```bash
 agent-infra-internal platform-context resolve [--cwd <path>]
-agent-infra-internal platform-comment list --issue <N> [--cwd <path>]
+agent-infra-internal platform-comment list --issue <issue-token> [--cwd <path>]
+agent-infra-internal platform-comment recover --issue <issue-token> --task-id <TASK-id> \
+  --output <.agents/workspace/.restore-staging-*/task.md> [--cwd <path>]
 agent-infra-internal platform-comment owner <task-ref>
 agent-infra-internal platform-comment sync <task-ref> \
-  --kind task|artifact|summary|cancel --agent {standard-agent-token} \
+  --kind task|artifact|summary|cancel|recovery-action|recovery-prepare|recovery-commit --agent {standard-agent-token} \
   [--artifact <canonical.md>] [--body-file <path|->] [--backfill]
 ```
 
 - `applied|no-op|degraded` → exit 0；`failed` → exit 1；`blocked` → exit 2。
-- task 评论保持 `<details>` frontmatter 可逆格式；artifact 原文内联并在超过 profile 上限时使用 `artifactChunk`。
+- task 评论保持 `<details>` frontmatter 可逆格式，只同步确定性的当前任务投影；活动日志、产物生命周期收据、失效记录等过程章节由 recovery 事务保存。artifact 原文内联并在超过 profile 上限时使用 `artifactChunk`。
+- 长度预检与 platform verification 使用同一最终渲染正文的 UTF-8 字节数。正文超限时失败关闭；本地 task 文件不会被截断。
+
+恢复评论使用 `recovery-action`、`recovery-prepare` 和 `recovery-commit` marker，并携带稳定 recovery id 和 body file。task 同步按 prepare、action、task snapshot 写入并复读、commit 的顺序发布。相同内容重放返回 `no-op`；已有恢复 marker 的正文不同返回 `RECOVERY_IMMUTABLE_CONFLICT`。restore 只接受作者一致、分片完整、phase/摘要/marker 匹配且绑定当前 task 评论正文 SHA-256 的完整事务。
 - 相同 intent 重放必须收敛为 `no-op`；重复 marker 返回 `COMMENT_MARKER_CONFLICT` 且不写入。
 - 外部贡献者锁定统一使用 `platform-comment owner`；不同作者且无 triage 时返回 `COMMENT_OWNER_CONFLICT`。
 
@@ -59,7 +67,7 @@ agent-infra-internal task-warning {task-id} add \
 ```bash
 agent-infra-internal platform-issue inspect {task-id}
 agent-infra-internal platform-issue create {task-id} --agent {standard-agent-token}
-agent-infra-internal platform-issue bind {task-id} --issue {number} --agent {standard-agent-token}
+agent-infra-internal platform-issue bind {task-id} --issue {issue-token} --agent {standard-agent-token}
 agent-infra-internal platform-issue sync {task-id} --agent {standard-agent-token} {desired-state-flags}
 ```
 

package/templates/.agents/rules/local-artifact-repair.en.md

@@ -1,57 +1,65 @@
-# General Rule - Model-Driven Local Artifact Repair
+# General Rule - Model-Driven Local Artifact Recovery
 
-This rule applies when `analyze-task`, `plan-task`, or `code-task` handles **the same controlled local artifact** before its completed event, and when `review-analysis`, `review-plan`, or `review-code` handles a finalizer failure for **the same controlled review artifact**. It does not apply to `task.md`, the ledger, receipts, source code, Git, platform resources, or lifecycle state.
+This rule covers the pre-completion gate for `analyze-task`, `plan-task`, and `code-task`, plus the summary finalizers for the three review skills. It handles one canonical artifact in the current task directory only. It does not authorize changes to `task.md`, ledgers, receipts, source code, Git, platform resources, or lifecycle state.
 
-## Pre-completion gate for analysis, plan, and code artifacts
+## Pre-completion gate
 
-- `analyze-task`, `plan-task`, and `code-task` must call `task-artifact ... finalize-local` before publishing a completed event; pass only that call's `artifactSha256` and `semanticDigest` to the completed event.
-- `finalize-local` does not modify the artifact or task state, but it writes a one-shot local provenance intent in the repository workspace. After `failed`, the model may make one minimal edit in the same artifact only when `repairable=true` and the diagnostic explicitly describes one provably safe structural operation (the current shared engine operations are `replace-line` and `insert-section`), then rerun the same call completely; count each byte-changing edit, up to 8.
-- The first repairable failure's semantic digest is retained in that intent; a later `passed` result must match the baseline, and the completed event must verify and atomically transition the same intent to `consumed` before writing `task.md` under the task lock. A consumption failure must not write the task; the consumed intent is durable and retryable, so no failure-prone post-write deletion is attempted. Do not replace a failed baseline with a newly computed digest or publish a completed event without the finalizer.
-- After `failed`, no progress, or a repeated diagnostic or fingerprint, do not publish a completed event. After `passed`, do not rescan or manually write summary data.
+- Run the applicable finalizer before a completed event; pass only that invocation's `artifactSha256` and `semanticDigest` to the event.
+- When artifact content is invalid, the finalizer returns a controlled `recovery` with a `recoveryId`, `candidatePath`, and baseline digests. The formal artifact remains unchanged until recovery commit.
+- After the mechanical safety gates pass, the model may edit only the returned `candidatePath`. After each byte-changing edit, rerun the complete finalizer with the same task, stage/family, artifact, and `--recovery-id`. Never edit the formal artifact directly and call it a candidate.
+- Preflight stable-reads and validates candidate `S`, then seals immutable digest-addressed generation `R`; candidate SHA is an observation rather than an edit guard.
+- Preflight publishes active `R` through `preflight-ready → preflight-commit-started → preflight-passed`; the business finalizer publishes `F` through `full-finalizer-ready → commit-started → passed` and reuses `R` when `F=R`.
+- Candidate-only is a protocol authorization boundary, not OS isolation: a same-UID process with arbitrary host filesystem write access may tamper with recovery internals. Identity, fingerprint, and state checks detect such anomalies and fail closed, but the protocol does not claim an independent security principal or cross-platform isolation.
 
-## Authorization Boundary
+## Authorization boundary
 
-- The finalizer only reads facts, validates state, normalizes successful results, and performs atomic writes. It does not maintain a recoverable-error allowlist, infer repairability, or choose report content to delete.
-- The initial finalizer call is not counted as a repair attempt. Editing is allowed only after the mechanical safety gates pass and the model explicitly determines that the current problem can be solved by a minimal, explainable artifact change.
-- The model may edit only the one ordinary local artifact declared by the current skill, and the file must be inside the current task directory. It must not edit `task.md`, the review disagreement ledger, receipts, source code, other reports, or remote resources.
-- `changed=false`, an error code, or a format shape is diagnostic evidence, not automatic authorization. The model must judge each case using the complete diagnostic, artifact content, and context.
+- The finalizer and recovery core validate identity, state, permissions, stable reads, complete artifact semantics, and fingerprints. They do not infer repairability or expose a text-operation allow-list.
+- The model may edit only the one ordinary artifact declared by the current skill. It must not edit `task.md`, ledgers, receipts, source code, other reports, or remote resources.
+- `changed=false`, an error code, or a format shape is diagnostic evidence, not edit authorization. Stop on unproven human-decision semantics, concurrency, permission, I/O, identity, provenance, or unknown state.
 
-## Non-bypassable Mechanical Safety Gates
+## Non-bypassable mechanical gates
 
-Before every model edit, confirm that:
+Before every candidate edit, confirm that:
 
-1. the finalizer returned a failure and no artifact operation was committed;
-2. the task, stage, artifact, review round, identity, and provenance still match;
-3. the target is an ordinary file inside the current task directory, with no concurrency conflict, permission error, I/O uncertainty, or target replacement;
-4. the change does not alter human-decision semantics, decision-detail or ledger identity, and does not involve task state, receipts, Git, platform, or any other external side effect. A known and verifiable pending human decision may remain when the model proves the edit is unrelated to that decision.
+1. the finalizer failed with the same controlled recovery context and nothing formal was committed;
+2. task, family/stage, round, artifact, request/authority, and baseline fingerprints still match;
+3. `candidatePath` is the ordinary file generated by the recovery core and the formal target has not changed externally;
+4. the edit does not change human-decision semantics, detail or ledger identity, and introduces no other side effect.
 
-If any condition fails, stop immediately without invoking a model edit. The model cannot bypass these gates.
+If any condition fails, stop without editing or publishing a completed event.
 
-## Dynamic Convergence Loop
+## Durable recovery states
 
-1. Run the initial finalizer with the fixed task, stage, artifact, and orchestrated intent.
-2. On success, use that complete result for the existing completion gates; do not rescan the ledger or write summary fields manually.
-3. On failure with the safety gates passed, let the model read the structured diagnostic, current artifact, and required context, then decide whether to repair or stop. It must explain the scope and reason for the proposed change.
-4. If the model continues, perform one minimal edit to the artifact. Increment `repairAttempts` only when the file bytes actually change, then rerun the same finalizer intent completely.
-5. Re-run every safety check after each retry. A new, independent problem still limited to the same artifact may be offered to the model for another decision; the previous repairability decision must not be reused automatically.
-6. Stop immediately when the model cannot establish safety or identifies an environment, permission, concurrency, identity, provenance, unknown-state, uncertain human-decision semantics/details, or other non-local problem. A known human decision is not itself a stop condition.
-7. Stop when the diagnostic or artifact fingerprint repeats, no byte-level progress occurs, or the model cannot propose a verifiable minimal change.
-8. Allow at most 8 actual artifact edits per skill invocation as an emergency circuit breaker. This cap only prevents infinite loops and resource exhaustion; it is not a normal business stop condition and does not mean that at most eight problems may be repaired. Preserve the final structured diagnostic when the cap is reached.
+| State | Formal artifact | Allowed action |
+| --- | --- | --- |
+| `awaiting-preflight-recovery` | baseline `B` | Edit `S`; stable-read, validate, and create `R` |
+| `preflight-ready` / `preflight-commit-started` | `B` or `R` | Reconcile/publish only active immutable `R` |
+| `preflight-passed` | `R` | Run the business finalizer for `F` |
+| `full-finalizer-ready` / `commit-started` | `R` or `F` | Reconcile/publish only pending immutable `F` |
+| `passed` | `F` | Completed event validates the final digest and consumes the intent |
+| `consumed` | `F` | Cleanup may reclaim the controlled staging and backup |
+| `aborted` | verified restored `B` | Preserve diagnostics; never fabricate success |
 
-The repair count exists only in the in-memory context of the current skill invocation. Do not write it to `task.md`, the ledger, or a public receipt. Do not create different normal budgets by error code, skill, or problem type.
+The intent is current-only schema version 4. Legacy schemas fail closed; do not add migration, adapters, or dual writes. Candidate, baseline, generation, and intent files live in controlled repo-local directories and use canonical recovery IDs, regular-file checks, stable reads, the task lock, and expected-value CAS. No cross-file atomicity is claimed; unknown combinations remain indeterminate and retain their evidence.
 
-## Shared Structural Engine
+## Dynamic convergence loop
 
-The report skeleton is created by `agent-infra-internal task-artifact {task-id} init --family {family} --artifact {artifact}`. The skeleton writes only identity, headings, and `artifact-section:{family}:{section-id}` markers; it does not represent semantic completion. The current skill must fill each slot with real content. When the finalizer returns one provably safe structural operation, use that result's SHA and semantic digest with `task-artifact {task-id} repair --family {family} --artifact {artifact} --expected-sha256 {artifact-sha256} --expected-semantic-digest {semantic-digest}`. Repair executes only the one operation from the shared engine, does not write `task.md`, the ledger, receipts, Git, or platform resources, and must be followed by a complete rerun of the original finalizer.
+1. Run the finalizer with the fixed invocation.
+2. If it fails and the gates pass, read the structured diagnostic and `candidatePath`, then make one minimal, explainable candidate edit.
+3. Confirm byte-level progress and rerun every finalizer check with the same `--recovery-id`.
+4. Stop on repeated diagnostics or fingerprints, no byte progress, unknown recovery state, or the eight-edit limit for the current invocation. Do not publish a completed event or generate a cross-stage next step.
 
-## Completion Events and User Output
+## Shared entry points
 
-- After the final complete finalizer result succeeds, publish the review completed event using that same result's provenance, ledger state, verdict, and counts. Generate cross-stage next-step commands only when `stageStatus.canAdvance=true` and the verdict is Approved; when `canAdvance=false`, still record the result and route to same-stage revision/review.
-- On failure, model stop, lack of progress, repeated diagnostics, or the emergency cap, do not publish a completed event, advance the lifecycle, generate cross-stage commands, or fabricate an approval.
-- Stopping advancement does not discard review results. User output must show the artifact path, the last safely readable summary/findings, actual `repairAttempts`, the last structured diagnostic, and the stop reason.
-- If the summary cannot be safely parsed, show only the artifact path and the raw structured diagnostic; do not infer counts or add a conclusion, and state that lifecycle advancement stopped while the artifact remains available.
-- A stop path may only suggest rerunning the current review skill or handling the issue manually. It must not invoke cross-stage helpers such as `code-task` or `complete-task`.
+The current entry points are `task-artifact ... inspect|init|finalize-local` and `task-review ... finalize-summary`. Recovery retries use the `recoveryId` returned by the finalizer, for example:
 
-## Lifecycle Isolation
+```text
+agent-infra-internal task-artifact {task-id} finalize-local --family code --artifact {code-artifact} --recovery-id {recovery-id}
+agent-infra-internal task-review {task-id} finalize-summary --stage code --artifact {review-artifact} --recovery-id {recovery-id}
+```
 
-`complete-task`, alert closing, task restoration, and other task-lifecycle/task-finalization entry points involve task state, receipts, remote results, or archival side effects and do not consume this rule. They retain their own hard-stop, same-intent retry, and unknown-state semantics.
+There is no `task-artifact repair`, `replace-line`, `insert-section`, or `repairable` authorization. The structural engine returns diagnostics and digests only; the current skill's gates and the model decide whether and how to edit the candidate.
+
+## Lifecycle isolation
+
+A completed event may legitimately modify `task.md`, but only after finalizer recovery is `passed` and digest, round, request, and authority all match. If authority consumption fails after the event write, retain the formal artifact and use the existing lifecycle recovery compensation; do not replay the completed write or roll back a passed artifact.