@fitlab-ai/agent-infra 0.11.6 → 0.11.8

package/lib/agent-clients/config.ts

@@ -167,10 +167,16 @@ function normalizeAgentClients(
   }
   if (hasOwn(input, 'tuis')) fail('INVALID_AGENT_CLIENTS', 'tuis');
   const sandbox = isRecord(input.sandbox) ? input.sandbox : undefined;
-  if (Array.isArray(sandbox?.tools)) {
-    for (const [index, tool] of sandbox.tools.entries()) {
+  if (sandbox && hasOwn(sandbox, 'customTools')) {
+    fail('INVALID_AGENT_CLIENTS', 'sandbox.customTools');
+  }
+  if (sandbox && hasOwn(sandbox, 'tools')) {
+    if (!isRecord(sandbox.tools)) fail('INVALID_AGENT_CLIENTS', 'sandbox.tools');
+    const tools = sandbox.tools;
+    if (!Array.isArray(tools.ids)) fail('INVALID_AGENT_CLIENTS', 'sandbox.tools.ids');
+    for (const [index, tool] of tools.ids.entries()) {
       if (isAgentClientId(tool)) {
-        fail('INVALID_AGENT_CLIENTS', `sandbox.tools[${index}]`);
+        fail('INVALID_AGENT_CLIENTS', `sandbox.tools.ids[${index}]`);
       }
     }
   }

package/lib/defaults.json

@@ -34,9 +34,12 @@
     "runtimes": [
       "node22"
     ],
-    "tools": [
-      "agent-infra"
-    ],
+    "tools": {
+      "ids": [
+        "agent-infra"
+      ],
+      "definitions": {}
+    },
     "refreshIntervalDays": 7,
     "dockerfile": null,
     "vm": {

package/lib/git/primary-worktree.ts

@@ -0,0 +1,62 @@
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+
+import { sameFilesystemEntry } from './worktree-identity.ts';
+
+function gitText(repositoryRoot: string, args: string[]): string {
+  return execFileSync('git', ['-C', repositoryRoot, ...args], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  }).replace(/\r?\n$/, '');
+}
+
+function isPrimaryWorktree(candidate: string, expectedCommonDirectory: string): boolean {
+  try {
+    const root = fs.realpathSync.native(candidate);
+    if (!fs.statSync(root).isDirectory()) return false;
+    if (gitText(root, ['rev-parse', '--show-prefix']) !== '') return false;
+
+    const commonDirectory = gitText(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    const gitDirectory = gitText(root, ['rev-parse', '--absolute-git-dir']);
+    return sameFilesystemEntry(commonDirectory, expectedCommonDirectory) &&
+      sameFilesystemEntry(gitDirectory, expectedCommonDirectory);
+  } catch {
+    return false;
+  }
+}
+
+function worktreePaths(repositoryRoot: string): string[] {
+  const output = execFileSync('git', ['-C', repositoryRoot, 'worktree', 'list', '--porcelain', '-z'], {
+    encoding: 'utf8',
+    stdio: ['ignore', 'pipe', 'pipe']
+  });
+
+  return output
+    .split('\0\0')
+    .flatMap((record) => record.split('\0'))
+    .filter((field) => field.startsWith('worktree '))
+    .map((field) => field.slice('worktree '.length));
+}
+
+export function resolvePrimaryWorktreeRoot(repositoryRoot: string): string {
+  try {
+    const root = fs.realpathSync.native(repositoryRoot);
+    if (!fs.statSync(root).isDirectory() || gitText(root, ['rev-parse', '--show-prefix']) !== '') {
+      throw new Error('repository root is not a worktree root');
+    }
+
+    const commonDirectory = gitText(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    const gitDirectory = gitText(root, ['rev-parse', '--absolute-git-dir']);
+    if (sameFilesystemEntry(gitDirectory, commonDirectory)) return root;
+
+    const matches = worktreePaths(root).filter((candidate) => isPrimaryWorktree(candidate, commonDirectory));
+    if (matches.length !== 1) {
+      throw new Error(matches.length === 0 ? 'primary worktree metadata was not found' : 'primary worktree metadata is ambiguous');
+    }
+
+    return fs.realpathSync.native(matches[0]!);
+  } catch (error) {
+    const detail = error instanceof Error ? error.message : String(error);
+    throw new Error(`server: unable to locate primary worktree: ${detail}`);
+  }
+}

package/lib/internal/cli-route-inventory.ts

@@ -63,6 +63,7 @@ export const INTERNAL_HANDLER_ROUTE_SELECTORS = Object.freeze({
   'task-invalidation': ['reconcile'],
   'task-lifecycle': ['intent'],
   'task-finalization': ['complete'],
+  'task-platform-recovery': ['inspect', 'recover'],
   'task-short-id': ['list', 'list-verify', 'alloc', 'release', 'resolve'],
   'task-snapshot': ['snapshot'],
   'task-verify': ['event'],
@@ -89,6 +90,7 @@ export function internalRouteSelector(command: string, args: readonly string[]):
   if (command === 'task-qualification') return args[1] ?? '';
   if (command === 'task-lifecycle') return args[1] ? 'intent' : '';
   if (command === 'task-finalization') return args[1] === 'complete' ? 'complete' : '';
+  if (command === 'task-platform-recovery') return args[1] ?? '';
   if (command === 'task-event') return args[1] ? 'event' : '';
   if (command === 'task-verify') return args[0] && args[1] ? 'event' : '';
   if (command === 'task-snapshot') return 'snapshot';

package/lib/internal/platform-pr-review.ts

@@ -6,14 +6,15 @@ import { listPrReviews, publishPrReview } from '../platform/pr-review.ts';
 import type { PrReviewEvent } from '../platform/pr-review.ts';
 import type { PlatformResult } from '../platform/types.ts';
 import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+import { normalizeAgentToken, AGENT_USAGE_HINT } from '../agent-clients/tokens.ts';
 
 const USAGE = `Usage: agent-infra-internal platform-pr-review inspect --pr <token> [--cwd <path>]
        agent-infra-internal platform-pr-review list --pr <token> [--cwd <path>]
-       agent-infra-internal platform-pr-review publish --pr <token> --scope <taskId|pr{N}> --round <N> --commit <sha> --event <COMMENT|APPROVE|REQUEST_CHANGES> --body-file <path|-> [--dry-run] [--cwd <path>]
+       agent-infra-internal platform-pr-review publish --pr <token> --scope <taskId|pr{N}> --round <N> --commit <sha> --event <COMMENT|APPROVE|REQUEST_CHANGES> --body-file <path|-> [--artifact <pr-review-artifact>] [--agent <agent>] [--dry-run] [--cwd <path>]
 `;
 
 const BOOLEAN_FLAGS = new Set(['--dry-run']);
-const VALUE_FLAGS = new Set(['--cwd', '--pr', '--scope', '--round', '--commit', '--event', '--body-file']);
+const VALUE_FLAGS = new Set(['--cwd', '--pr', '--scope', '--round', '--commit', '--event', '--body-file', '--artifact', '--agent']);
 
 function key(flag: string): string {
   return flag.slice(2).replace(/-([a-z])/g, (_, letter: string) => letter.toUpperCase());
@@ -67,7 +68,7 @@ async function platformPrReview(args: string[] = []): Promise<void> {
   const allowed: Record<string, string[]> = {
     inspect: ['cwd', 'pr'],
     list: ['cwd', 'pr'],
-    publish: ['cwd', 'pr', 'scope', 'round', 'commit', 'event', 'bodyFile', 'dryRun']
+    publish: ['cwd', 'pr', 'scope', 'round', 'commit', 'event', 'bodyFile', 'artifact', 'agent', 'dryRun']
   };
   const unexpected = Object.keys(values).find((name) => !allowed[operation]!.includes(name));
   if (unexpected) { fail(`${operation} does not accept --${unexpected}`); return; }
@@ -86,6 +87,8 @@ async function platformPrReview(args: string[] = []): Promise<void> {
   const round = Number(values.round);
   const commit = typeof values.commit === 'string' ? values.commit : '';
   const event = values.event as string;
+  const rawAgent = typeof values.agent === 'string' ? values.agent : '';
+  const agent = rawAgent ? normalizeAgentToken(rawAgent) : null;
   if (!scope || !/^(?:pr\d+|TASK-\d{8}-\d{6})$/.test(scope)) { fail('publish requires --scope <taskId|pr{N}>'); return; }
   if (!internalHandlerRoute('platform-pr-review', 'publish-task', publishSelector)
     && !internalHandlerRoute('platform-pr-review', 'publish-pr', publishSelector)) {
@@ -95,6 +98,12 @@ async function platformPrReview(args: string[] = []): Promise<void> {
   if (!/^[0-9a-f]{7,40}$/i.test(commit)) { fail('publish requires --commit <sha>'); return; }
   if (!['COMMENT', 'APPROVE', 'REQUEST_CHANGES'].includes(event)) { fail('publish requires --event <COMMENT|APPROVE|REQUEST_CHANGES>'); return; }
   if (typeof values.bodyFile !== 'string') { fail('publish requires --body-file'); return; }
+  if (/^TASK-\d{8}-\d{6}$/u.test(scope) && typeof values.artifact !== 'string') { fail('task-scoped publish requires --artifact <pr-review-artifact>'); return; }
+  if (/^TASK-\d{8}-\d{6}$/u.test(scope) && !agent) {
+    fail(`task-scoped publish requires --agent <agent>${rawAgent ? `: invalid '${rawAgent}'` : ''}: ${AGENT_USAGE_HINT}`);
+    return;
+  }
+  if (rawAgent && !agent) { fail(`invalid --agent '${rawAgent}': ${AGENT_USAGE_HINT}`); return; }
   let body: string;
   try {
     body = readBodyFile(values.bodyFile, cwd);
@@ -108,6 +117,8 @@ async function platformPrReview(args: string[] = []): Promise<void> {
     identity: { scope, round, commitSha: commit },
     event: event as PrReviewEvent,
     body,
+    ...(typeof values.artifact === 'string' ? { recoveryArtifact: values.artifact } : {}),
+    ...(agent ? { agent } : {}),
     dryRun: values.dryRun === true
   }));
 }

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

@@ -145,6 +145,8 @@ function internalTaskRoutes(): TaskOperationDescriptor[] {
     descriptor('internal', 'task-invalidation', 'reconcile', 'task-bound', 'progress'),
     descriptor('internal', 'task-lifecycle', 'intent', 'task-bound', 'progress'),
     descriptor('internal', 'task-finalization', 'complete', 'task-bound', 'progress'),
+    descriptor('internal', 'task-platform-recovery', 'inspect', 'task-bound', 'diagnostic'),
+    descriptor('internal', 'task-platform-recovery', 'recover', 'task-bound', 'recovery'),
     descriptor('internal', 'task-short-id', 'list', 'conditional', 'diagnostic'),
     descriptor('internal', 'task-short-id', 'list-verify', 'conditional', 'diagnostic'),
     descriptor('internal', 'task-short-id', 'alloc', 'task-bound', 'progress'),
@@ -221,7 +223,7 @@ export const INTERNAL_DISPATCHER_ROUTES = Object.freeze([
   'platform-comment', 'platform-issue', 'platform-pr', 'platform-pr-review', 'pr-review-grade',
   'platform-checks', 'task-context', 'task-ledger', 'task-warning', 'task-activity', 'task-artifact',
   'task-orchestration', 'task-review', 'task-event', 'task-invalidation', 'task-lifecycle',
-  'task-finalization', 'task-short-id', 'task-snapshot', 'task-verify', 'task-validate', 'manual-validation'
+  'task-finalization', 'task-platform-recovery', 'task-short-id', 'task-snapshot', 'task-verify', 'task-validate', 'manual-validation'
 ]);
 export const PUBLIC_DISPATCHER_ROUTES = Object.freeze([
   'agent-client', 'cp', 'data', 'decide', 'help', 'init', 'merge', 'run', 'sandbox', 'server', 'task', 'sync', 'update', 'version'

package/lib/internal/task-platform-recovery.ts

@@ -0,0 +1,53 @@
+import { detectRepoRoot, resolveTaskRef } from '../task/resolve-ref.ts';
+import { readPlatformOperationJournal } from '../task/platform-operation-journal.ts';
+import { recoverPlatformOperations } from '../task/platform-operation-recovery.ts';
+import { ensureInternalHandlerRoute, internalHandlerRoute } from './cli-route-inventory.ts';
+
+const USAGE = 'Usage: agent-infra-internal task-platform-recovery <N | TASK-id> <inspect | recover> [--agent <agent>] [--selection required|deferred|all]\n';
+
+function option(args: readonly string[], name: string): string | undefined {
+  const index = args.indexOf(name);
+  return index >= 0 ? args[index + 1] : undefined;
+}
+
+async function taskPlatformRecovery(args: string[] = []): Promise<void> {
+  if (args[0] === '--help' || args[0] === '-h') { process.stdout.write(USAGE); return; }
+  if (!ensureInternalHandlerRoute('task-platform-recovery', args)) return;
+  const action = args[1];
+  const registered = action === 'inspect'
+    ? internalHandlerRoute('task-platform-recovery', 'inspect', action)
+    : action === 'recover' && internalHandlerRoute('task-platform-recovery', 'recover', action);
+  if (!registered) return;
+  const repoRoot = detectRepoRoot();
+  const task = resolveTaskRef(args[0] ?? '', { repoRoot });
+  if (!task.ok) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: task.code, message: task.message } })}\n`);
+    process.exitCode = 1;
+    return;
+  }
+  if (action === 'inspect') {
+    try {
+      const journal = readPlatformOperationJournal(task.taskId, repoRoot);
+      process.stdout.write(`${JSON.stringify({ status: 'ready', changed: false, taskId: task.taskId, journal })}\n`);
+    } catch (error) {
+      const value = error as { code?: string; message?: string };
+      process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: value.code || 'PLATFORM_OPERATION_JOURNAL_INVALID', message: value.message || String(error) } })}\n`);
+      process.exitCode = 1;
+    }
+    return;
+  }
+  const agent = option(args, '--agent');
+  const selection = option(args, '--selection') ?? 'all';
+  if (!agent || !/^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/u.test(agent)
+    || !['required', 'deferred', 'all'].includes(selection)) {
+    process.stdout.write(`${JSON.stringify({ status: 'failed', changed: false, error: { code: 'PLATFORM_OPERATION_RECOVERY_PAYLOAD_INVALID', message: 'recover requires a valid --agent and --selection' } })}\n`);
+    process.stderr.write(USAGE);
+    process.exitCode = 1;
+    return;
+  }
+  const result = await recoverPlatformOperations(task.taskId, selection as 'required' | 'deferred' | 'all', { agent, cwd: repoRoot });
+  process.stdout.write(`${JSON.stringify(result)}\n`);
+  process.exitCode = result.status === 'applied' || result.status === 'no-op' ? 0 : result.status === 'blocked' ? 2 : 1;
+}
+
+export { taskPlatformRecovery };

package/lib/merge.ts

@@ -1,4 +1,5 @@
 import fs from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import crypto from 'node:crypto';
 import { removeDirRecursive } from './remove-dir.ts';
@@ -424,6 +425,24 @@ function formatBackupTimestamp(date: Date): string {
   ].join('') + `-${String(date.getHours()).padStart(2, '0')}${String(date.getMinutes()).padStart(2, '0')}${String(date.getSeconds()).padStart(2, '0')}`;
 }
 
+function resolveRecoveryProjectKey(repoRoot: string): string {
+  let projectKey: string | undefined;
+  try {
+    const config = JSON.parse(fs.readFileSync(path.join(repoRoot, '.agents', '.airc.json'), 'utf8')) as { project?: unknown };
+    if (typeof config.project === 'string' && config.project.trim() !== '') {
+      projectKey = config.project.trim();
+    }
+  } catch {
+    // Fall back to the repository directory when project config is unavailable.
+  }
+
+  projectKey ??= path.basename(repoRoot);
+  if (!/^[A-Za-z0-9_.@-]+$/.test(projectKey) || projectKey === '.' || projectKey === '..') {
+    throw new Error(`Invalid project name for recovery backups: ${projectKey}`);
+  }
+  return projectKey;
+}
+
 function toPosixPath(relativePath: string): string {
   return relativePath.split(path.sep).join('/');
 }
@@ -541,7 +560,7 @@ function buildWorkspaceIndex(workspaceDir: string): Map<string, WorkspaceRecord>
 function backupTaskDir(backupRoot: string, section: MutableSection, taskDir: string, taskId: string): string {
   const backupDir = path.join(backupRoot, section, taskId);
   fs.mkdirSync(path.dirname(backupDir), { recursive: true });
-  fs.cpSync(taskDir, backupDir, { recursive: true });
+  fs.cpSync(taskDir, backupDir, { recursive: true, verbatimSymlinks: true });
   return backupDir;
 }
 
@@ -1085,16 +1104,17 @@ async function cmdMerge(args: string[]): Promise<void> {
     throw new Error(`Source path is not a directory: ${sourcePath}`);
   }
 
-  const workspaceDir = path.join(process.cwd(), '.agents', 'workspace');
+  const repoRoot = process.cwd();
+  const workspaceDir = path.join(repoRoot, '.agents', 'workspace');
   const archiveDir = path.join(workspaceDir, 'archive');
   const backupStamp = formatBackupTimestamp(new Date());
-  const backupRootRelative = `.agents/workspace/.merge-backup/${backupStamp}/`;
-  const backupRoot = path.join(workspaceDir, '.merge-backup', backupStamp);
-  const report = createReport(resolvedSource, backupRootRelative);
+  const projectKey = resolveRecoveryProjectKey(repoRoot);
+  const recoveryRoot = path.join(os.homedir(), '.agent-infra', 'recovery-backups', projectKey, 'workspace-merge');
+  const backupRoot = path.join(recoveryRoot, backupStamp);
+  const report = createReport(resolvedSource, backupRoot);
   detectSourceMode(resolvedSource);
   validateSourceWorkspace(resolvedSource);
   validateArchiveSection(workspaceDir, new Map());
-
   for (const section of ALL_SECTIONS) {
     fs.mkdirSync(path.join(workspaceDir, section), { recursive: true });
   }

package/lib/platform/completion-backfill.ts

@@ -51,7 +51,7 @@ function referencedBackfillArtifact(taskDir: string, message: string): BackfillA
     .map((match) => match[1]!);
   if (names.length !== 1) return { status: 'ignored', artifact: null, error: null };
   const parsed = parseArtifactName(names[0]!);
-  if (!parsed || (parsed.family !== 'pr-review' && !COMPLETION_BACKFILL_FAMILIES.includes(parsed.family as typeof COMPLETION_BACKFILL_FAMILIES[number]))) {
+  if (!parsed || !COMPLETION_BACKFILL_FAMILIES.includes(parsed.family as typeof COMPLETION_BACKFILL_FAMILIES[number])) {
     return { status: 'ignored', artifact: null, error: null };
   }
   const artifactPath = path.join(taskDir, parsed.name);
@@ -141,6 +141,7 @@ async function backfillCompletionComments(
       artifact: artifact.name,
       agent: options.agent,
       backfill: true,
+      dependency: 'required',
       cwd: resolved.repoRoot,
       client: options.client
     });

package/lib/platform/in-label-sync.ts

@@ -1,4 +1,5 @@
 import { computeInLabels } from './metadata-labels.ts';
+import { createHash } from 'node:crypto';
 import type { PlatformError } from './types.ts';
 
 type InLabelPlan = {
@@ -68,6 +69,16 @@ function validateInLabelMapping(value: unknown): { ok: true; value: Record<strin
   return { ok: true, value: normalized };
 }
 
+function inLabelMappingDigest(value: unknown): { ok: true; digest: string } | { ok: false; error: InLabelValidationError } {
+  const mapping = validateInLabelMapping(value);
+  if (!mapping.ok) return mapping;
+  const canonical = Object.fromEntries(Object.keys(mapping.value).sort().map((name) => [
+    name,
+    [...new Set(mapping.value[name]!)].sort()
+  ]));
+  return { ok: true, digest: createHash('sha256').update(JSON.stringify(canonical)).digest('hex') };
+}
+
 function repositoryLabelPages(value: unknown): unknown[][] | null {
   if (!Array.isArray(value)) return null;
   if (value.length === 0) return [];
@@ -197,6 +208,7 @@ export {
   extractRepositoryLabelNames,
   flattenPages,
   inLabels,
+  inLabelMappingDigest,
   labelDelta,
   mergeInLabels,
   planInLabelUpdate,

package/lib/platform/issue-comments.ts

@@ -4,6 +4,7 @@ import { createHash } from 'node:crypto';
 
 import { parseTaskFrontmatter } from '../task/frontmatter.ts';
 import { resolveTaskRef } from '../task/resolve-ref.ts';
+import { coordinatePlatformWrite } from './operation-coordinator.ts';
 import { resolvePlatformProviderContext } from './context.ts';
 import type { PlatformClient } from './context.ts';
 import { platformResult } from './types.ts';
@@ -51,6 +52,9 @@ type SyncOptions = {
   client?: PlatformClient;
   runtimeVersion?: string;
   summaryAuthorization?: { sha256: string };
+  dependency?: 'deferred' | 'required';
+  skipQueue?: boolean;
+  taskProjection?: { content: string; sha256: string };
 };
 
 function providerCommentId(id: string, provider: { identity?: { comment?: string } }): number | string {
@@ -74,6 +78,8 @@ const ARTIFACT_TITLES: Record<string, string> = {
   'review-plan': '技术方案审查',
   code: '实现报告',
   'review-code': '代码审查',
+  'manual-validation': '人工验证',
+  'validation-run': '验证运行证据',
   'pr-review': 'PR 审查报告'
 };
 
@@ -150,7 +156,7 @@ function taskCommentLanguage(repoRoot: string): string {
 
 function artifactIdentity(artifact: string): { stem: string; title: string } {
   const stem = path.basename(artifact, '.md');
-  const match = stem.match(/^(analysis|review-analysis|plan|review-plan|code|review-code|pr-review)(?:-r(\d+))?$/);
+  const match = stem.match(/^(analysis|review-analysis|plan|review-plan|code|review-code|manual-validation|validation-run|pr-review)(?:-r(\d+))?$/);
   if (!match) throw new Error(`unsupported artifact '${artifact}'`);
   const base = ARTIFACT_TITLES[match[1]!]!;
   const round = match[2] ? Number(match[2]) : 1;
@@ -529,7 +535,7 @@ function writeComment(
   );
 }
 
-async function syncPlatformComment(taskRef: string, options: SyncOptions): Promise<PlatformResult> {
+async function syncPlatformCommentImpl(taskRef: string, options: SyncOptions): Promise<PlatformResult> {
   const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
   if (!resolved.ok) {
     return platformResult('failed', {
@@ -547,7 +553,12 @@ async function syncPlatformComment(taskRef: string, options: SyncOptions): Promi
   }
   let desired: RenderedChunk[];
   try {
-    desired = expectedComments(resolved.taskId, taskContent, resolved.taskDir, resolved.repoRoot, options);
+    const projectedContent = options.kind === 'task' && options.taskProjection ? options.taskProjection.content : taskContent;
+    if (options.kind === 'task' && options.taskProjection
+      && createHash('sha256').update(projectedContent).digest('hex') !== options.taskProjection.sha256) {
+      throw Object.assign(new Error('finalization task projection digest does not match content'), { code: 'FINALIZATION_PROJECTION_INVALID' });
+    }
+    desired = expectedComments(resolved.taskId, projectedContent, resolved.taskDir, resolved.repoRoot, options);
   } catch (error) {
     return platformResult('failed', {
       resource: { kind: 'issue', number: resourceIdentityNumber(issueIdentityFromTask) },
@@ -743,6 +754,50 @@ async function syncPlatformComment(taskRef: string, options: SyncOptions): Promi
   return result;
 }
 
+async function syncPlatformComment(taskRef: string, options: SyncOptions): Promise<PlatformResult> {
+  const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+  if (!resolved.ok) return syncPlatformCommentImpl(taskRef, options);
+  const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  if (!taskIssueIdentity(parseTaskFrontmatter(taskContent))) return syncPlatformCommentImpl(taskRef, options);
+
+  let operation: { kind: 'task-comment' | 'artifact-comment' | 'summary-comment' | 'cancel-comment'; target: string; expectedDigest: string };
+  try {
+    const sourceContent = options.kind === 'task' && options.taskProjection ? options.taskProjection.content : taskContent;
+    const desired = expectedComments(resolved.taskId, sourceContent, resolved.taskDir, resolved.repoRoot, options);
+    const content = desired.map((chunk) => chunk.content).join('\0');
+    const kind = options.kind === 'task' ? 'task-comment' : options.kind === 'summary' ? 'summary-comment'
+      : options.kind === 'cancel' ? 'cancel-comment' : 'artifact-comment';
+    const target = options.kind === 'artifact' ? options.artifact! : options.kind;
+    operation = { kind, target, expectedDigest: createHash('sha256').update(content).digest('hex') };
+  } catch {
+    return syncPlatformCommentImpl(taskRef, options);
+  }
+
+  const execute = () => syncPlatformCommentImpl(taskRef, options);
+  if (options.skipQueue) return execute();
+  return coordinatePlatformWrite({
+    operation: { taskRef: resolved.taskId, cwd: resolved.repoRoot, ...operation, dependency: options.dependency ?? 'deferred' },
+    agent: options.agent,
+    execute,
+    block: (error) => platformResult('blocked', { error }),
+    persistenceFailure: (error) => platformResult('failed', { error })
+  });
+}
+
+function inspectPlatformCommentOperation(taskRef: string, options: SyncOptions): { kind: 'task-comment' | 'artifact-comment' | 'summary-comment' | 'cancel-comment'; target: string; expectedDigest: string; id: string } | null {
+  const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+  if (!resolved.ok) return null;
+  const taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+  if (!taskIssueIdentity(parseTaskFrontmatter(taskContent))) return null;
+  const sourceContent = options.kind === 'task' && options.taskProjection ? options.taskProjection.content : taskContent;
+  const desired = expectedComments(resolved.taskId, sourceContent, resolved.taskDir, resolved.repoRoot, options);
+  const kind = options.kind === 'task' ? 'task-comment' : options.kind === 'summary' ? 'summary-comment'
+    : options.kind === 'cancel' ? 'cancel-comment' : 'artifact-comment';
+  const target = options.kind === 'artifact' ? options.artifact! : options.kind;
+  const expectedDigest = createHash('sha256').update(desired.map((chunk) => chunk.content).join('\0')).digest('hex');
+  return { kind, target, expectedDigest, id: createHash('sha256').update(`${kind}\0${target}\0${expectedDigest}`).digest('hex') };
+}
+
 async function listPlatformComments(issue: string | number, cwd = process.cwd(), client?: PlatformClient): Promise<PlatformResult & { comments?: RemoteComment[] }> {
   const loaded = await resolvePlatformProviderContext({ cwd, client });
   const context = loaded.ok ? loaded.value.context : loaded.context;
@@ -800,6 +855,7 @@ export {
   COMMENT_BYTE_LIMIT,
   MARKERS,
   chunkArtifactComment,
+  inspectPlatformCommentOperation,
   findMarkerComments,
   listRemoteComments,
   checkPlatformCommentOwner,

package/lib/platform/issues.ts

@@ -2,6 +2,7 @@ import type { PlatformIssueSnapshot as IssueSnapshot } from './snapshots.ts';
 import type { IssueFieldSchema } from './github-data.ts';
 import fs from 'node:fs';
 import path from 'node:path';
+import { createHash } from 'node:crypto';
 import { execFileSync } from 'node:child_process';
 
 import { buildDefaultBody } from '../task/commands/issue-body.ts';
@@ -24,6 +25,7 @@ import { platformResult } from './types.ts';
 import type { PlatformResult } from './types.ts';
 import {
   labelDelta,
+  inLabelMappingDigest,
   planInLabelUpdate,
   syncLabelDelta,
   validateInLabelMapping,
@@ -39,9 +41,11 @@ import {
 } from './provider-bridge.ts';
 import { resourceIdentityEquals, resourceIdentityNumber, resourceIdentityString, serializeResourceIdentity } from './resource-identity.ts';
 import { taskIssueIdentity, taskIssueIdentityError } from './task-identities.ts';
+import { coordinatePlatformWrite } from './operation-coordinator.ts';
 import type { ResourceIdentity } from './resource-identity.ts';
 import type { IssueSnapshot as ProviderIssueSnapshot, RepositoryMetadataSnapshot } from './provider-contract.ts';
-type IssueResult = PlatformResult & {
+type IssueResult = Omit<PlatformResult, 'operations'> & {
+  operations: PlannedOperation[];
   task: { id: string | null; issueNumber: number | null };
   issue: IssueSnapshot | null;
 };
@@ -61,6 +65,8 @@ type SyncOptions = SharedOptions & {
   state?: 'open' | 'closed';
   closeReason?: 'completed' | 'not_planned';
   dryRun?: boolean;
+  dependency?: 'deferred' | 'required';
+  skipQueue?: boolean;
 };
 
 function result(
@@ -305,7 +311,7 @@ async function createPlatformIssue(taskRef: string, options: CreateOptions): Pro
     platform: base.context.platform, capabilities: base.context.capabilities,
     operations: [{ name: 'issue:create', status: 'planned', reasonCode: null }], error: null
   });
-  {
+  const execute = async (): Promise<IssueResult> => {
     const created = base.provider.issues?.create
       ? await base.provider.issues.create({
         context: providerOperationContext(base.loadedContext),
@@ -344,7 +350,7 @@ async function createPlatformIssue(taskRef: string, options: CreateOptions): Pro
     if (written.status === 'failed') return result('failed', base.resolved.taskId, null, {
       platform: base.context.platform, capabilities: base.context.capabilities,
       resource: { kind: 'issue', number: issueNumber, identity: inspected.value.identity || createdIdentity },
-      error: { code: 'ISSUE_CREATED_BIND_FAILED', message: written.error.message, retryable: false }
+      error: { code: 'ISSUE_CREATED_BIND_FAILED', message: written.error.message, retryable: true }
     });
     return result('applied', base.resolved.taskId, issueNumber, {
       changed: true,
@@ -355,7 +361,26 @@ async function createPlatformIssue(taskRef: string, options: CreateOptions): Pro
       issue: normalizeProviderIssue(inspected.value, repository, issueNumber),
       error: null
     });
-  }
+  };
+  const issueCreate = { title: payload.title, bodyDigest: createHash('sha256').update(payload.body).digest('hex') };
+  const operation = {
+    kind: 'issue-create' as const,
+    target: `task:${base.resolved.taskId}`,
+    expectedDigest: createHash('sha256').update(JSON.stringify({
+      taskId: base.resolved.taskId,
+      title: payload.title,
+      body: createHash('sha256').update(payload.body).digest('hex'),
+      labels: payload.labels || [], assignees: payload.assignees,
+      milestone: typeof payload.milestone === 'string' ? payload.milestone : null
+    })).digest('hex')
+  };
+  return coordinatePlatformWrite({
+    operation: { taskRef: base.resolved.taskId, cwd: base.resolved.repoRoot, ...operation, issueCreate, dependency: 'required' },
+    agent: options.agent,
+    execute,
+    block: (error) => result('blocked', base.resolved.taskId, null, { platform: base.context.platform, capabilities: base.context.capabilities, error }),
+    persistenceFailure: (error) => result('failed', base.resolved.taskId, null, { error })
+  });
 }
 
 async function bindPlatformIssue(taskRef: string, options: BindOptions): Promise<IssueResult> {
@@ -478,7 +503,7 @@ function desiredFieldValues(frontmatter: Record<string, string>, fields: IssueFi
   return desired;
 }
 
-async function syncPlatformIssue(taskRef: string, options: SyncOptions): Promise<IssueResult> {
+async function syncPlatformIssueImpl(taskRef: string, options: SyncOptions): Promise<IssueResult> {
   const base = await resolvedContext(taskRef, options);
   if (!base.ok) return base.output;
   if (!base.issueIdentity) return result('failed', base.resolved.taskId, null, { error: { code: 'ISSUE_NOT_LINKED', message: 'Task has no valid platform issue identity', retryable: false } });
@@ -617,5 +642,78 @@ async function syncPlatformIssue(taskRef: string, options: SyncOptions): Promise
   });
 }
 
+async function syncPlatformIssue(taskRef: string, options: SyncOptions): Promise<IssueResult> {
+  const resolved = resolveTaskRef(taskRef, options.cwd ? { repoRoot: options.cwd } : {});
+  if (!resolved.ok || options.dryRun) return syncPlatformIssueImpl(taskRef, options);
+  let frontmatter: Record<string, string>;
+  let taskContent: string;
+  try {
+    taskContent = fs.readFileSync(resolved.taskMdPath, 'utf8');
+    frontmatter = parseTaskFrontmatter(taskContent);
+  }
+  catch { return syncPlatformIssueImpl(taskRef, options); }
+  const identity = taskIssueIdentity(frontmatter);
+  if (!identity || ![
+    options.requirements, options.issueType, options.fields, options.status !== undefined,
+    options.assignees !== undefined, options.milestone !== undefined,
+    options.inLabels !== undefined, options.state !== undefined
+  ].some(Boolean)) return syncPlatformIssueImpl(taskRef, options);
+  let fromDiffFiles: string[] | undefined;
+  let mappingDigest: string | undefined;
+  if (options.inLabels === 'from-diff') {
+    const taskBase = typeof frontmatter.delivery_base_ref === 'string' ? frontmatter.delivery_base_ref.trim() : '';
+    if (taskBase && (!options.base || options.base === taskBase)) {
+      try {
+        fromDiffFiles = execFileSync('git', ['diff', `${taskBase}...HEAD`, '--name-only'], {
+          cwd: resolved.repoRoot, encoding: 'utf8'
+        }).trim().split(/\r?\n/).filter(Boolean).sort();
+        const config = JSON.parse(fs.readFileSync(path.join(resolved.repoRoot, '.agents', '.airc.json'), 'utf8')) as { labels?: { in?: unknown } };
+        const mapping = inLabelMappingDigest(config.labels?.in);
+        if (!mapping.ok) return result('failed', resolved.taskId, resourceIdentityNumber(identity), {
+          error: { code: mapping.error.code, message: mapping.error.message, retryable: false }
+        });
+        mappingDigest = mapping.digest;
+      } catch {
+        return result('failed', resolved.taskId, resourceIdentityNumber(identity), {
+          error: { code: 'IN_LABEL_SYNC_EVIDENCE_UNAVAILABLE', message: 'Unable to derive the current changed-file set for Issue metadata recovery', retryable: false }
+        });
+      }
+    }
+  }
+  const issueMetadata = {
+    requirements: options.requirements === true,
+    issueType: options.issueType === true,
+    fields: options.fields === true,
+    ...(options.status !== undefined ? { status: options.status } : {}),
+    ...(options.assignees !== undefined ? { assignees: options.assignees } : {}),
+    ...(options.milestone !== undefined ? { milestone: options.milestone } : {}),
+    ...(options.inLabels ? { inLabels: options.inLabels } : {}),
+    ...(options.base ? { base: options.base } : {}),
+    ...(fromDiffFiles ? { fromDiffFiles } : {}),
+    ...(mappingDigest ? { inLabelMappingDigest: mappingDigest } : {}),
+    ...(options.state ? { state: options.state } : {}),
+    ...(options.closeReason ? { closeReason: options.closeReason } : {})
+  };
+  const operation = {
+    kind: 'issue-metadata' as const,
+    target: JSON.stringify(identity),
+    expectedDigest: createHash('sha256').update(JSON.stringify({
+      ...issueMetadata,
+      task: resolved.taskId,
+      taskContent: createHash('sha256').update(taskContent).digest('hex')
+    })).digest('hex')
+  };
+  const dependency = options.dependency ?? (options.state === 'closed' && options.closeReason === 'not_planned' ? 'required' : 'deferred');
+  const execute = () => syncPlatformIssueImpl(taskRef, options);
+  if (options.skipQueue) return execute();
+  return coordinatePlatformWrite({
+    operation: { taskRef: resolved.taskId, cwd: resolved.repoRoot, ...operation, issueMetadata, dependency },
+    agent: options.agent,
+    execute,
+    block: (error) => result('blocked', resolved.taskId, resourceIdentityNumber(identity), { error }),
+    persistenceFailure: (error) => result('failed', resolved.taskId, resourceIdentityNumber(identity), { error })
+  });
+}
+
 export { bindPlatformIssue, createPlatformIssue, inspectPlatformIssue, requirementSectionAnchors, syncPlatformIssue };
 export type { BindOptions, CreateOptions, IssueResult, SyncOptions };