@fitlab-ai/agent-infra 0.9.15 → 0.11.0

package/lib/internal/platform-comment.ts

@@ -9,10 +9,12 @@ import {
 } from '../platform/issue-comments.ts';
 import type { CommentKind } from '../platform/issue-comments.ts';
 import type { PlatformResult } from '../platform/types.ts';
+import { recoverTaskFromComments } from '../platform/task-recovery.ts';
 import { backfillCompletionComments } from '../platform/completion-backfill.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-comment list --issue <token> [--cwd <path>]
+       agent-infra-internal platform-comment recover --issue <token> --task-id <TASK-id> --output <staging-task.md> [--cwd <path>]
        agent-infra-internal platform-comment owner <task-ref> [--cwd <path>]
        agent-infra-internal platform-comment backfill <task-ref> --agent <agent> [--cwd <path>]
        agent-infra-internal platform-comment sync <task-ref> --kind <kind> --agent <agent> [--artifact <file>] [--body-file <path|->] [--status-label <label>] [--backfill] [--cwd <path>]
@@ -35,7 +37,7 @@ function parseFlags(args: string[], start: number): { values: Record<string, str
   const seen = new Set<string>();
   for (let index = start; index < args.length; index += 1) {
     const flag = args[index]!;
-    if (!['--issue', '--cwd', '--kind', '--agent', '--artifact', '--body-file', '--status-label', '--backfill'].includes(flag)) {
+    if (!['--issue', '--task-id', '--output', '--cwd', '--kind', '--agent', '--artifact', '--body-file', '--status-label', '--backfill'].includes(flag)) {
       return { values, error: `unknown option '${flag}'` };
     }
     if (seen.has(flag)) return { values, error: `duplicate option '${flag}'` };
@@ -59,11 +61,12 @@ async function platformComment(args: string[] = []): Promise<void> {
   const operation = args[0];
   if (!operation || ![
     internalHandlerRoute('platform-comment', 'list', operation),
+    internalHandlerRoute('platform-comment', 'recover', operation),
     internalHandlerRoute('platform-comment', 'owner', operation),
     internalHandlerRoute('platform-comment', 'backfill', operation),
     internalHandlerRoute('platform-comment', 'sync', operation)
   ].some(Boolean)) { fail('a valid operation is required'); return; }
-  const hasTaskRef = operation !== 'list';
+  const hasTaskRef = operation !== 'list' && operation !== 'recover';
   const taskRef = hasTaskRef ? args[1] : undefined;
   if (hasTaskRef && (!taskRef || taskRef.startsWith('--'))) { fail(`${operation} requires a task ref`); return; }
   const parsed = parseFlags(args, hasTaskRef ? 2 : 1);
@@ -77,6 +80,54 @@ async function platformComment(args: string[] = []): Promise<void> {
     finish(await listPlatformComments(issue, cwd));
     return;
   }
+  if (internalHandlerRoute('platform-comment', 'recover', operation)) {
+    const issue = parsed.values.issue;
+    const taskId = parsed.values.taskId;
+    const output = parsed.values.output;
+    if (typeof issue !== 'string' || !issue || typeof taskId !== 'string' || !/^TASK-\d{8}-\d{6}$/.test(taskId)
+      || typeof output !== 'string' || !output) {
+      fail('recover requires --issue <token> --task-id <TASK-id> --output <staging-task.md>');
+      return;
+    }
+    const unexpected = Object.keys(parsed.values).find((key) => !['issue', 'taskId', 'output', 'cwd'].includes(key));
+    if (unexpected) { fail(`recover does not accept '--${unexpected}'`); return; }
+    const outputPath = path.resolve(cwd, output);
+    const workspaceDir = path.resolve(cwd, '.agents', 'workspace');
+    const stagingDir = path.dirname(outputPath);
+    const stagingParent = fs.existsSync(stagingDir) ? path.dirname(fs.realpathSync(stagingDir)) : '';
+    const realWorkspace = fs.existsSync(workspaceDir) ? fs.realpathSync(workspaceDir) : '';
+    if (path.basename(outputPath) !== 'task.md' || stagingParent !== realWorkspace
+      || !path.basename(stagingDir).startsWith('.restore-staging-') || !fs.existsSync(stagingDir)
+      || !fs.lstatSync(stagingDir).isDirectory() || fs.existsSync(outputPath)) {
+      fail('recover output must be a new task.md inside an existing .agents/workspace/.restore-staging-* directory');
+      return;
+    }
+    const listed = await listPlatformComments(issue, cwd);
+    if (listed.status === 'failed' || listed.status === 'blocked' || !listed.comments) { finish(listed); return; }
+    try {
+      const taskContent = recoverTaskFromComments({ taskId, comments: listed.comments });
+      fs.writeFileSync(outputPath, taskContent, { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+      finish({
+        ...listed,
+        status: 'applied',
+        changed: true,
+        operations: [{ name: `recovery:task:${taskId}`, status: 'applied', reasonCode: null }],
+        error: null
+      });
+    } catch (error) {
+      finish({
+        ...listed,
+        status: 'failed',
+        changed: false,
+        error: {
+          code: 'RECOVERY_EVIDENCE_MISSING',
+          message: error instanceof Error ? error.message : String(error),
+          retryable: false
+        }
+      });
+    }
+    return;
+  }
   if (internalHandlerRoute('platform-comment', 'owner', operation)) {
     const unexpected = Object.keys(parsed.values).find((key) => key !== 'cwd');
     if (unexpected) { fail(`owner does not accept '--${unexpected}'`); return; }

package/lib/internal/task-artifact.ts

@@ -1,7 +1,7 @@
 import { parseArtifactCommand, executeArtifactCommand } from '../task/artifact-command.ts';
 import { ensureInternalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> repair --family <family> --artifact <artifact> --expected-sha256 <sha256> --expected-semantic-digest <digest>\n       agent-infra-internal task-artifact <N | TASK-id> finalize-local --family <analysis|plan|code> --artifact <artifact>\n\nInspect, initialize, repair, or finalize a workflow artifact without changing task state.\n`;
+const USAGE = `Usage: agent-infra-internal task-artifact <N | TASK-id> inspect --family <family>\n       agent-infra-internal task-artifact <N | TASK-id> init --family <family> --artifact <artifact> [--locale <zh-CN|en>]\n       agent-infra-internal task-artifact <N | TASK-id> preflight|finalize-local --family <analysis|plan|code> --artifact <artifact> [--recovery-id <id>]\n\nInspect, initialize, preflight, or finalize a workflow artifact without changing task state.\n`;
 
 
 function taskArtifact(args: string[] = []): void {

package/lib/internal/task-finalization.ts

@@ -38,8 +38,8 @@ function parseFailure(error: unknown): string {
 }
 
 async function taskFinalization(args: string[] = []): Promise<void> {
-  if (!ensureInternalHandlerRoute('task-finalization', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (!ensureInternalHandlerRoute('task-finalization', args)) return;
 
   let operation;
   try {

package/lib/internal/task-lifecycle.ts

@@ -7,9 +7,10 @@ import {
 import { lifecycleIntentCatalog } from '../task/lifecycle.ts';
 import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
 import type { TaskLifecycleResult } from '../task/lifecycle.ts';
+import type { LifecycleRecoveryResult } from '../task/lifecycle-recovery.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nOverride: --override-ticket <ticket> --override-target <target> --override-scope <scope>\n`;
+const USAGE = `Usage: agent-infra-internal task-lifecycle <N | TASK-id> <intent> --agent <agent> [intent flags] [--dry-run]\n\nIntents: ${lifecycleIntentCatalog.join(', ')}\nrecover-started: --stage <stage> --round <round> --artifact <artifact> --reason <reason>\nOverride: --override-ticket <ticket> --override-target <target> --override-scope <scope>\n`;
 
 function usageFailure(message: string): void {
   process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'LIFECYCLE_PAYLOAD_INVALID', message } })}\n`);
@@ -23,8 +24,8 @@ function parseFailure(error: unknown): string {
 }
 
 async function taskLifecycle(args: string[] = []): Promise<void> {
-  if (!ensureInternalHandlerRoute('task-lifecycle', args)) return;
   if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (!ensureInternalHandlerRoute('task-lifecycle', args)) return;
 
   let operation;
   try {
@@ -61,9 +62,9 @@ async function taskLifecycle(args: string[] = []): Promise<void> {
   const result = await dispatchTaskControlOperation(
     createDirectHostExecutionContext({ repoRoot }),
     operation
-  ) as TaskLifecycleResult & { humanOverride?: unknown };
+  ) as (TaskLifecycleResult | LifecycleRecoveryResult) & { humanOverride?: unknown };
   process.stdout.write(`${JSON.stringify(result)}\n`);
-  if (result.status === 'failed') process.exitCode = 1;
+  if (result.status === 'failed' || result.status === 'owner-unknown' || result.status === 'conflict') process.exitCode = 1;
 }
 
 export { taskLifecycle };

package/lib/internal/task-operation-registry.ts

@@ -56,10 +56,6 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'sandbox-control', 'execute', 'non-task', 'progress', 'none'),
     descriptor('internal', 'sandbox-control', 'recover', 'conditional', 'recovery', 'delegated'),
     descriptor('internal', 'sandbox-control', 'client', 'conditional', 'progress', 'delegated'),
-    descriptor('internal', 'host-control', 'serve', 'non-task', 'progress', 'none'),
-    descriptor('internal', 'host-control', 'status', 'non-task', 'diagnostic', 'none'),
-    descriptor('internal', 'host-control', 'install', 'non-task', 'progress', 'none'),
-    descriptor('internal', 'host-control', 'uninstall', 'non-task', 'progress', 'none'),
     descriptor('internal', 'agent-client', 'next-steps', 'non-task', 'diagnostic', 'none'),
     descriptor('internal', 'agent-client', 'model-selection', 'non-task', 'diagnostic', 'none'),
     descriptor('internal', 'codex-lifecycle', 'preflight', 'non-task', 'diagnostic', 'none'),
@@ -91,6 +87,7 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'platform-metadata', 'init-milestones', 'non-task', 'remote-write', 'none'),
     descriptor('internal', 'platform-context', 'resolve', 'non-task', 'diagnostic', 'none'),
     descriptor('internal', 'platform-comment', 'list', 'non-task', 'diagnostic', 'none'),
+    descriptor('internal', 'platform-comment', 'recover', 'non-task', 'recovery', 'none'),
     descriptor('internal', 'platform-comment', 'owner', 'task-bound', 'diagnostic'),
     descriptor('internal', 'platform-comment', 'backfill', 'task-bound', 'remote-write'),
     descriptor('internal', 'platform-comment', 'sync', 'task-bound', 'remote-write'),
@@ -136,10 +133,11 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'task-activity', 'pr-review-terminate', 'task-bound', 'progress'),
     descriptor('internal', 'task-artifact', 'inspect', 'task-bound', 'diagnostic'),
     descriptor('internal', 'task-artifact', 'init', 'task-bound', 'artifact-write'),
-    descriptor('internal', 'task-artifact', 'repair', 'task-bound', 'artifact-write'),
+    descriptor('internal', 'task-artifact', 'preflight', 'task-bound', 'artifact-write'),
     descriptor('internal', 'task-artifact', 'finalize-local', 'task-bound', 'artifact-write'),
     descriptor('internal', 'task-orchestration', 'status', 'task-bound', 'diagnostic'),
     descriptor('internal', 'task-orchestration', 'progress', 'task-bound', 'progress'),
+    descriptor('internal', 'task-review', 'preflight', 'task-bound', 'artifact-write'),
     descriptor('internal', 'task-review', 'finalize-summary', 'task-bound', 'progress'),
     descriptor('internal', 'task-event', 'event', 'task-bound', 'progress'),
     descriptor('internal', 'task-invalidation', 'reconcile', 'task-bound', 'progress'),
@@ -219,7 +217,7 @@ export const TASK_OPERATION_DESCRIPTORS = Object.freeze([
 ]);
 
 export const INTERNAL_DISPATCHER_ROUTES = Object.freeze([
-  'task-create', 'task-qualification', 'sandbox-control', 'host-control', 'agent-client', 'codex-lifecycle', 'codex-sandbox-controller',
+  'task-create', 'task-qualification', 'sandbox-control', 'agent-client', 'codex-lifecycle', 'codex-sandbox-controller',
   'git-workflow', 'task-delivery', 'release-workflow', 'platform-release-notes', 'platform-security', 'platform-metadata', 'platform-context',
   'platform-comment', 'platform-issue', 'platform-pr', 'platform-pr-review', 'pr-review-grade',
   'platform-checks', 'task-context', 'task-ledger', 'task-warning', 'task-activity', 'task-artifact',
@@ -343,28 +341,39 @@ export function resolveSandboxControlTransport(
   env: NodeJS.ProcessEnv = process.env,
   options: Readonly<{ statusMountPath?: string }> = {}
 ): SandboxControlTransportDecision {
-  const configuredStatusDir = env.AGENT_INFRA_CONTROL_STATUS_DIR;
-  const fixedStatusDir = options.statusMountPath
-    ?? SANDBOX_CONTROL_STATUS_MOUNT;
   const hasAnyMarker = TASK_MARKER_KEYS.some((key) => Boolean(env[key]))
     || Boolean(env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING)
     || Boolean(env.AGENT_INFRA_EXECUTOR_MANIFEST);
-  const fixedStatusProbe = !env.AGENT_INFRA_TEST_HOST_CONTROL_ENDPOINT && path.isAbsolute(fixedStatusDir)
+  const fixedStatusDir = options.statusMountPath
+    ?? SANDBOX_CONTROL_STATUS_MOUNT;
+  const fixedStatusProbe = path.isAbsolute(fixedStatusDir)
     ? nativeDirectoryProbe(fixedStatusDir) : 'absent';
   if (fixedStatusProbe === 'unknown') {
     return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_UNAVAILABLE' };
   }
   const fixedStatusMounted = fixedStatusProbe === 'present';
+  // A fixed status mount is installed only in a task-bound sandbox. Its
+  // presence is not mutable by the sandbox process, so marker removal must
+  // never make that process look like a direct host invocation.
+  if (!hasAnyMarker) {
+    return fixedStatusMounted
+      ? { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' }
+      : { kind: 'direct-host', reasonCode: null };
+  }
+  const hasCompleteConfig = TASK_CONTROL_CONFIG_KEYS.every((key) => Boolean(env[key]));
+  if (!hasCompleteConfig) {
+    return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_CONFIGURATION_INCOMPLETE' };
+  }
+  const configuredStatusDir = env.AGENT_INFRA_CONTROL_STATUS_DIR;
   const configuredStatusProbe = configuredStatusDir && path.isAbsolute(configuredStatusDir)
     ? nativeDirectoryProbe(configuredStatusDir) : 'absent';
   if (configuredStatusProbe === 'unknown') {
     return { kind: 'fail-closed', reasonCode: 'SANDBOX_CONTROL_IDENTITY_UNAVAILABLE' };
   }
-  const statusDir = configuredStatusDir && path.isAbsolute(configuredStatusDir) && configuredStatusProbe === 'present'
-    ? configuredStatusDir
+  const statusDir = configuredStatusDir && path.isAbsolute(configuredStatusDir)
+    ? configuredStatusProbe === 'present' ? configuredStatusDir : null
     : fixedStatusMounted ? fixedStatusDir : null;
   const statusMounted = statusDir !== null;
-  const hasCompleteConfig = TASK_CONTROL_CONFIG_KEYS.every((key) => Boolean(env[key]));
   if (env.AGENT_INFRA_EXECUTOR_MANIFEST || env.AGENT_INFRA_CONTROL_CONTROLLER_BINDING) {
     return { kind: 'fail-closed', reasonCode: 'TASK_CONTROL_TRANSPORT_INVALID' };
   }

package/lib/internal/task-orchestration.ts

@@ -20,11 +20,11 @@ function parseFailure(error: unknown): string {
 }
 
 async function taskOrchestration(args: string[] = []): Promise<void> {
-  if (!ensureInternalHandlerRoute('task-orchestration', args)) return;
   if (args[0] === '--help' || args[0] === '-h') {
     process.stdout.write(USAGE);
     return;
   }
+  if (!ensureInternalHandlerRoute('task-orchestration', args)) return;
 
   const route = internalHandlerRoute('task-orchestration', 'status', args[1] ?? '')
     ? 'status'

package/lib/internal/task-review.ts

@@ -1,17 +1,17 @@
 import { parseReviewCommand } from '../task/review-command.ts';
-import { finalizeReviewSummary } from '../task/review-finalization.ts';
+import { finalizeReviewSummary, preflightReviewSummary } from '../task/review-finalization.ts';
 import { consumeHumanOverride, failureId, overrideDryRunConflict } from '../task/human-override.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from '../task/task-execution-lock.ts';
 import { ensureInternalHandlerRoute } from './cli-route-inventory.ts';
 
-const USAGE = 'Usage: agent-infra-internal task-review <task-ref> finalize-summary --stage <analysis|plan|code> --artifact <review-*.md> [--orchestrated] [--dry-run] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
+const USAGE = 'Usage: agent-infra-internal task-review <task-ref> <preflight|finalize-summary> --stage <analysis|plan|code> --artifact <review-*.md> [--recovery-id <id>] [--orchestrated] [--dry-run] [--override-ticket <ticket> --override-target <target> --override-scope <scope>]\n';
 
 function failUsage(message: string): void {
   process.stdout.write(`${JSON.stringify({
     status: 'failed',
     changed: false,
-    intent: 'finalize-summary',
+    intent: 'review-operation',
     error: { code: 'REVIEW_PAYLOAD_INVALID', message }
   })}\n`);
   process.stderr.write(USAGE);
@@ -27,7 +27,8 @@ async function taskReview(args: string[] = []): Promise<void> {
   let request;
   try { request = parseReviewCommand(args); }
   catch (error) { failUsage(error instanceof Error ? error.message : String(error)); return; }
-  const { stage, artifact, dryRun, orchestrated, overrideTicket, overrideTarget, overrideScope } = request;
+  const { stage, artifact, recoveryId, dryRun, orchestrated, overrideTicket, overrideTarget, overrideScope } = request;
+  const operation = args[1]!;
   const dryRunConflict = overrideDryRunConflict({ dryRun, overrideTicket, overrideTarget, overrideScope });
   if (dryRunConflict) { failUsage(dryRunConflict.message); return; }
   const resolved = resolveTaskRef(args[0]!);
@@ -35,8 +36,11 @@ async function taskReview(args: string[] = []): Promise<void> {
   let result;
   let humanOverride: unknown = null;
   try {
-    result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, 'task-review.finalize-summary', async () => {
-      let current = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, orchestrated, dryRun }, { lockAlreadyHeld: true });
+    result = await withTaskExecutionLock(resolved.repoRoot, resolved.taskId, `task-review.${operation}`, async () => {
+      let current = operation === 'preflight'
+        ? preflightReviewSummary({ taskRef: args[0]!, stage, artifact, recoveryId, orchestrated, dryRun }, { lockAlreadyHeld: true })
+        : finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, recoveryId, orchestrated, dryRun }, { lockAlreadyHeld: true });
+      if (operation === 'preflight') return current;
       if (current.status !== 'failed' || !overrideTicket) return current;
       if (!overrideTarget || !overrideScope) { failUsage('override ticket requires target and scope'); return current; }
       const consumed = await consumeHumanOverride({
@@ -45,7 +49,7 @@ async function taskReview(args: string[] = []): Promise<void> {
         target: overrideTarget, scope: overrideScope
       }, {
         effectExecutor: (capability) => {
-          const retried = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, orchestrated, dryRun }, { lockAlreadyHeld: true, manualOverride: capability });
+          const retried = finalizeReviewSummary({ taskRef: args[0]!, stage, artifact, recoveryId, orchestrated, dryRun }, { lockAlreadyHeld: true, manualOverride: capability });
           current = retried;
           return retried.status === 'failed' || retried.status === 'planned'
             ? { code: 'OVERRIDE_EFFECT_FAILED', message: retried.status === 'planned' ? 'producer returned planned; no review effect was committed' : `${retried.error?.code ?? 'REVIEW_FAILED'}: ${retried.error?.message ?? 'manual review effect failed'}` }

package/lib/platform/activity-recovery.ts

@@ -0,0 +1,179 @@
+import { createHash } from 'node:crypto';
+
+import { locateActivityLog } from '../task/activity-log.ts';
+import type { LogEntry } from '../task/activity-log.ts';
+
+const METADATA_PREFIX = '<!-- activity-recovery:v1:';
+const METADATA_SUFFIX = ' -->';
+
+type ActivityRecoveryRecord = {
+  version: 1;
+  taskId: string;
+  artifact?: string;
+  entries: LogEntry[];
+  sha256: string;
+};
+
+function canonicalJson(value: unknown): string {
+  if (value === null || typeof value !== 'object') return JSON.stringify(value);
+  if (Array.isArray(value)) return `[${value.map(canonicalJson).join(',')}]`;
+  const record = value as Record<string, unknown>;
+  return `{${Object.keys(record).sort().map((key) => `${JSON.stringify(key)}:${canonicalJson(record[key])}`).join(',')}}`;
+}
+
+function sha256(value: unknown): string {
+  return createHash('sha256').update(canonicalJson(value), 'utf8').digest('hex');
+}
+
+function baseStep(step: string): string {
+  return step.replace(/\s*\[(?:started|aborted)\]\s*$/, '');
+}
+
+function entriesForArtifact(taskContent: string, artifact: string): LogEntry[] {
+  const log = locateActivityLog(taskContent);
+  if (!log) return [];
+  const selected = new Set<number>();
+  for (let index = 0; index < log.entries.length; index += 1) {
+    const entry = log.entries[index]!;
+    if (!entry.note.includes(`→ ${artifact}`)) continue;
+    selected.add(index);
+    const step = baseStep(entry.step);
+    let startedAt = index;
+    for (let prior = index - 1; prior >= 0; prior -= 1) {
+      const candidate = log.entries[prior]!;
+      if (baseStep(candidate.step) !== step) continue;
+      if (/\[started\]\s*$/.test(candidate.step)) {
+        selected.add(prior);
+        startedAt = prior;
+      }
+      break;
+    }
+    if (/^code(?:-r\d+)?\.md$/.test(artifact)) {
+      for (let between = startedAt + 1; between < index; between += 1) {
+        if (baseStep(log.entries[between]!.step) === 'Commit') selected.add(between);
+      }
+    }
+  }
+  return log.entries.filter((_entry, index) => selected.has(index));
+}
+
+function recordForEntries(taskId: string, entries: readonly LogEntry[], artifact?: string): ActivityRecoveryRecord | null {
+  if (entries.length === 0) return null;
+  const base = { version: 1 as const, taskId, ...(artifact ? { artifact } : {}), entries: [...entries] };
+  return { ...base, sha256: sha256(base) };
+}
+
+function recordForArtifact(taskId: string, taskContent: string, artifact: string): ActivityRecoveryRecord | null {
+  return recordForEntries(taskId, entriesForArtifact(taskContent, artifact), artifact);
+}
+
+function entriesForTask(taskContent: string): LogEntry[] {
+  const log = locateActivityLog(taskContent);
+  if (!log) return [];
+  const linked = new Set(entriesForArtifactNames(log.entries));
+  return log.entries.filter((entry, index) => !linked.has(index)
+    && !['Create PR', 'Complete Task', 'Cancel Task'].includes(baseStep(entry.step)));
+}
+
+function entriesForSummary(taskContent: string): LogEntry[] {
+  const log = locateActivityLog(taskContent);
+  return log?.entries.filter((entry) => ['Create PR', 'Complete Task'].includes(baseStep(entry.step))) ?? [];
+}
+
+function entriesForCancel(taskContent: string): LogEntry[] {
+  const log = locateActivityLog(taskContent);
+  return log?.entries.filter((entry) => baseStep(entry.step) === 'Cancel Task') ?? [];
+}
+
+function recordForTask(taskId: string, taskContent: string): ActivityRecoveryRecord | null {
+  return recordForEntries(taskId, entriesForTask(taskContent));
+}
+
+function recordForSummary(taskId: string, taskContent: string): ActivityRecoveryRecord | null {
+  return recordForEntries(taskId, entriesForSummary(taskContent));
+}
+
+function recordForCancel(taskId: string, taskContent: string): ActivityRecoveryRecord | null {
+  return recordForEntries(taskId, entriesForCancel(taskContent));
+}
+
+function entriesForArtifactNames(entries: readonly LogEntry[]): number[] {
+  const selected = new Set<number>();
+  for (let index = 0; index < entries.length; index += 1) {
+    const entry = entries[index]!;
+    const artifact = /→ ([A-Za-z0-9][A-Za-z0-9._-]*\.md)(?:\s|$)/.exec(entry.note)?.[1];
+    if (!artifact) continue;
+    selected.add(index);
+    const step = baseStep(entry.step);
+    let startedAt = index;
+    for (let prior = index - 1; prior >= 0; prior -= 1) {
+      const candidate = entries[prior]!;
+      if (baseStep(candidate.step) !== step) continue;
+      if (/\[started\]\s*$/.test(candidate.step)) {
+        selected.add(prior);
+        startedAt = prior;
+      }
+      break;
+    }
+    if (/^code(?:-r\d+)?\.md$/.test(artifact)) {
+      for (let between = startedAt + 1; between < index; between += 1) {
+        if (baseStep(entries[between]!.step) === 'Commit') selected.add(between);
+      }
+    }
+  }
+  return [...selected];
+}
+
+function renderActivityRecoveryMetadata(record: ActivityRecoveryRecord | null): string {
+  if (!record) return '';
+  const encoded = Buffer.from(canonicalJson(record), 'utf8').toString('base64url');
+  const first = record.entries[0]!;
+  const last = record.entries.at(-1)!;
+  return [
+    '<details><summary>恢复元数据</summary>',
+    '',
+    `- 动作：${baseStep(last.step)}`,
+    `- 记录：${record.entries.length} 条（${first.time} 至 ${last.time}）`,
+    ...(record.artifact ? [`- 产物：${record.artifact}`] : []),
+    `- 校验：\`${record.sha256}\``,
+    '',
+    `${METADATA_PREFIX}${encoded}${METADATA_SUFFIX}`,
+    '</details>',
+    ''
+  ].join('\n');
+}
+
+function parseActivityRecoveryMetadata(body: string): ActivityRecoveryRecord | null {
+  const match = body.match(/<!-- activity-recovery:v1:([A-Za-z0-9_-]+) -->/);
+  if (!match) return null;
+  let value: unknown;
+  try { value = JSON.parse(Buffer.from(match[1]!, 'base64url').toString('utf8')); }
+  catch { throw new Error('RECOVERY_EVIDENCE_MISSING: activity metadata is not valid'); }
+  if (!value || typeof value !== 'object') throw new Error('RECOVERY_EVIDENCE_MISSING: activity metadata is invalid');
+  const record = value as Partial<ActivityRecoveryRecord>;
+  if (record.version !== 1 || typeof record.taskId !== 'string' || (record.artifact !== undefined && typeof record.artifact !== 'string')
+    || !Array.isArray(record.entries) || typeof record.sha256 !== 'string') {
+    throw new Error('RECOVERY_EVIDENCE_MISSING: activity metadata shape is invalid');
+  }
+  if (record.entries.some((entry) => !entry || typeof entry.time !== 'string' || typeof entry.step !== 'string' || typeof entry.agent !== 'string' || typeof entry.note !== 'string')) {
+    throw new Error('RECOVERY_EVIDENCE_MISSING: activity metadata entries are invalid');
+  }
+  const base = { version: 1 as const, taskId: record.taskId, ...(record.artifact ? { artifact: record.artifact } : {}), entries: record.entries as LogEntry[] };
+  if (sha256(base) !== record.sha256) throw new Error('RECOVERY_EVIDENCE_MISSING: activity metadata checksum does not match');
+  return { ...base, sha256: record.sha256 };
+}
+
+export {
+  entriesForArtifact,
+  entriesForCancel,
+  entriesForSummary,
+  entriesForTask,
+  parseActivityRecoveryMetadata,
+  recordForArtifact,
+  recordForCancel,
+  recordForEntries,
+  recordForSummary,
+  recordForTask,
+  renderActivityRecoveryMetadata
+};
+export type { ActivityRecoveryRecord };