@fitlab-ai/agent-infra 0.11.7 → 0.11.9

package/dist/lib/update.js

@@ -132,8 +132,8 @@ async function cmdSync() {
     ok('Seed files synced successfully!');
     console.log('');
     if (workflowPlan.nextSteps.length === 0) {
-        console.log('  No Agent Client project integration enabled.');
-        console.log(`  Configure "customTUIs" in ${CONFIG_PATH} if needed.`);
+        console.log('  No Agent Client or sandbox custom tool integration enabled.');
+        console.log(`  Configure a custom tool in "sandbox.tools.definitions" and select it in "sandbox.tools.ids" in ${CONFIG_PATH}.`);
         console.log('');
     }
     else {

package/dist/lifecycle-build-manifest.json

@@ -1,6 +1,6 @@
 {
   "protocolVersion": 3,
-  "packageVersion": "0.11.7",
-  "sourceInputHash": "095f0cf30aa29fcd2dd45123dc755e5097d7a9f81de33420461fd943cff122b2",
-  "internalExecutableBuildHash": "a956f2ed366e025a111a87bc1f542b87d83d4025e068304f95b1aae704709d3f"
+  "packageVersion": "0.11.9",
+  "sourceInputHash": "17fe6c91408c93e3aa5185e816025d590ded7db7e6a305fdce00751e78723abc",
+  "internalExecutableBuildHash": "8de9870e4ece1050564d7a3e77ee211a789dd975e3f94593300b7362ed815a00"
 }

package/lib/agent-clients/adapters/codex.ts

@@ -54,7 +54,7 @@ const codexAdapter = defineAgentClientAdapter({
       containerMount: '/home/devuser/.codex',
       versionCmd: 'codex --version',
       setupHint: 'Run codex once inside the container and choose Device Code login if needed.',
-      tmpfs: { size: '512m', seed: ['config.toml', 'model-catalogs'] },
+      tmpfs: { size: '512m', seed: ['config.toml', 'model-catalogs'], exec: true },
       hostLiveMounts: [
         {
           hostPath: hostJoin(home, '.codex', 'auth.json'),

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/agent-clients/custom-tool-invocations.ts

@@ -0,0 +1,129 @@
+type CustomToolInvocation = Readonly<{
+  name: string;
+  invocation: string;
+}>;
+
+type CustomToolInvocationDiagnosticCode =
+  | 'INVALID_CUSTOM_TOOL_CONFIG'
+  | 'INVALID_CUSTOM_TOOL_INVOCATION'
+  | 'INVALID_CUSTOM_TOOL_INVOCATION_PLACEHOLDER';
+
+type CustomToolInvocationDiagnostic = Readonly<{
+  code: CustomToolInvocationDiagnosticCode;
+  path: string;
+}>;
+
+type NormalizeCustomToolInvocationsResult = Readonly<{
+  items: readonly CustomToolInvocation[];
+  diagnostics: readonly CustomToolInvocationDiagnostic[];
+}>;
+
+const ALLOWED_PLACEHOLDERS = Object.freeze(['skillName', 'projectName']);
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+
+function isNonEmptySingleLine(value: unknown): value is string {
+  return typeof value === 'string'
+    && value.trim() !== ''
+    && !/[\r\n]/.test(value);
+}
+
+function hasValidPlaceholders(invocation: string): boolean {
+  const placeholders = [
+    ...invocation.matchAll(/\$\{([^}]+)\}/g)
+  ].map((match) => match[1]!);
+  return placeholders.includes('skillName')
+    && placeholders.every((placeholder) =>
+      ALLOWED_PLACEHOLDERS.includes(placeholder)
+    )
+    && !invocation
+      .replaceAll('${skillName}', '')
+      .replaceAll('${projectName}', '')
+      .includes('${');
+}
+
+function normalizeCustomToolInvocations(config: unknown): NormalizeCustomToolInvocationsResult {
+  const items: CustomToolInvocation[] = [];
+  const diagnostics: CustomToolInvocationDiagnostic[] = [];
+
+  const root = isRecord(config) ? config : {};
+  const sandbox = isRecord(root.sandbox) ? root.sandbox : {};
+  const sandboxTools = isRecord(sandbox.tools) ? sandbox.tools : { ids: ['agent-infra'] };
+  const definitions = sandboxTools.definitions ?? {};
+  const selectedIds = sandboxTools.ids;
+
+  if (!Array.isArray(selectedIds)) {
+    return Object.freeze({
+      items: Object.freeze([]),
+      diagnostics: Object.freeze([
+        Object.freeze({
+          code: 'INVALID_CUSTOM_TOOL_CONFIG' as const,
+          path: 'sandbox.tools.ids'
+        })
+      ])
+    });
+  }
+
+  if (!isRecord(definitions)) {
+    return Object.freeze({
+      items: Object.freeze([]),
+      diagnostics: Object.freeze([
+        Object.freeze({
+          code: 'INVALID_CUSTOM_TOOL_CONFIG' as const,
+          path: 'sandbox.tools.definitions'
+        })
+      ])
+    });
+  }
+
+  for (const [index, id] of selectedIds.entries()) {
+    if (typeof id !== 'string') {
+      diagnostics.push({
+        code: 'INVALID_CUSTOM_TOOL_INVOCATION',
+        path: `sandbox.tools.ids[${index}]`
+      });
+      continue;
+    }
+    const candidate = definitions[id];
+    if (!isRecord(candidate)) continue;
+    if (candidate.invoke === undefined) continue;
+    const base = `sandbox.tools.definitions.${id}`;
+    const name = candidate.name === undefined ? id : candidate.name;
+    if (!isNonEmptySingleLine(name)) {
+      diagnostics.push({ code: 'INVALID_CUSTOM_TOOL_INVOCATION', path: `${base}.name` });
+      continue;
+    }
+    if (!isNonEmptySingleLine(candidate.invoke)) {
+      diagnostics.push({ code: 'INVALID_CUSTOM_TOOL_INVOCATION', path: `${base}.invoke` });
+      continue;
+    }
+    if (!hasValidPlaceholders(candidate.invoke)) {
+      diagnostics.push({
+        code: 'INVALID_CUSTOM_TOOL_INVOCATION_PLACEHOLDER',
+        path: `${base}.invoke`
+      });
+      continue;
+    }
+    items.push(Object.freeze({
+      name,
+      invocation: candidate.invoke
+    }));
+  }
+
+  return Object.freeze({
+    items: Object.freeze(items),
+    diagnostics: Object.freeze(
+      diagnostics.map((diagnostic) => Object.freeze(diagnostic))
+    )
+  });
+}
+
+export { normalizeCustomToolInvocations };
+export type {
+  CustomToolInvocation,
+  CustomToolInvocationDiagnostic,
+  CustomToolInvocationDiagnosticCode,
+  NormalizeCustomToolInvocationsResult
+};

package/lib/agent-clients/next-steps.ts

@@ -2,7 +2,7 @@ import { listEnabledAgentClientAdapters } from './registry.ts';
 import { renderAgentClientInvocation } from './invocation.ts';
 import semver from 'semver';
 import { isTaskScopeSkill } from '../task/skill-scope.ts';
-import type { CustomTUI } from './custom-tuis.ts';
+import type { CustomToolInvocation } from './custom-tool-invocations.ts';
 import type { AgentClientId, AgentClientState } from './types.ts';
 
 type NextStepCommand = Readonly<{
@@ -15,7 +15,7 @@ type NextStepCommand = Readonly<{
 type RenderNextStepsInput = Readonly<{
   projectName: string;
   state: AgentClientState;
-  customTUIs: readonly CustomTUI[];
+  customToolInvocations: readonly CustomToolInvocation[];
   skillName: string;
   taskRef?: string;
   version?: string;
@@ -69,7 +69,7 @@ function renderNextStepCommands(
       )
     })
   );
-  const custom = input.customTUIs.map(
+  const custom = input.customToolInvocations.map(
     (tool): NextStepCommand => Object.freeze({
       source: 'custom',
       displayName: tool.name,

package/lib/agent-clients/reconcile.ts

@@ -4,7 +4,7 @@ import path from 'node:path';
 
 import defaults from '../defaults.json' with { type: 'json' };
 import { normalizeAgentClients, serializeAgentClients } from './config.ts';
-import { normalizeCustomTUIs } from './custom-tuis.ts';
+import { normalizeCustomToolInvocations } from './custom-tool-invocations.ts';
 import { renderNextStepCommands } from './next-steps.ts';
 import { planAgentClientProjectAssets } from './project-assets.ts';
 import {
@@ -216,11 +216,11 @@ function planAgentClientReconciliation(input: Readonly<{
     delete (nextConfig.files as Record<string, unknown>).managedBaselines;
   }
 
-  const custom = normalizeCustomTUIs(input.projectRoot, input.config.customTUIs ?? []);
+  const custom = normalizeCustomToolInvocations(input.config);
   const nextSteps = renderNextStepCommands({
     projectName,
     state: desired,
-    customTUIs: custom.items,
+    customToolInvocations: custom.items,
     skillName: 'update-agent-infra'
   });
   const actionableSeed = seedOperations.some((operation) =>

package/lib/agent-clients/schema.ts

@@ -43,16 +43,24 @@ const AGENT_CLIENTS_SCHEMA = {
         }
       }))
     },
-    customTUIs: {
-      type: 'array',
-      items: {
-        type: 'object',
-        additionalProperties: true,
-        required: ['name', 'dir', 'invoke'],
-        properties: {
-          name: { type: 'string' },
-          dir: { type: 'string' },
-          invoke: { type: 'string' }
+    sandbox: {
+      type: 'object',
+      properties: {
+        tools: {
+          type: 'object',
+          properties: {
+            ids: { type: 'array', items: { type: 'string' } },
+            definitions: {
+              type: 'object',
+              additionalProperties: {
+                type: 'object',
+                properties: {
+                  name: { type: 'string' },
+                  invoke: { type: 'string' }
+                }
+              }
+            }
+          }
         }
       }
     }

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/init.ts

@@ -314,8 +314,8 @@ async function cmdInit(): Promise<void> {
   console.log('    npm install -g @fitlab-ai/agent-infra');
   console.log('');
   if (workflowPlan.nextSteps.length === 0) {
-    console.log('  No Agent Client project integration enabled.');
-    console.log(`  Configure "customTUIs" in ${configPath} before running update-agent-infra.`);
+    console.log('  No Agent Client or sandbox custom tool integration enabled.');
+    console.log(`  Configure a custom tool in "sandbox.tools.definitions" and select it in "sandbox.tools.ids" in ${configPath}.`);
     console.log('');
   } else {
     console.log('  Next step: open this project in any AI TUI and run:');

package/lib/internal/agent-client.ts

@@ -5,7 +5,7 @@ import {
   AgentClientConfigError,
   normalizeAgentClients
 } from '../agent-clients/config.ts';
-import { normalizeCustomTUIs } from '../agent-clients/custom-tuis.ts';
+import { normalizeCustomToolInvocations } from '../agent-clients/custom-tool-invocations.ts';
 import { renderNextStepCommands } from '../agent-clients/next-steps.ts';
 import { getAgentClientModelSelection } from '../agent-clients/registry.ts';
 import { isAgentClientId } from '../agent-clients/types.ts';
@@ -148,11 +148,11 @@ function agentClient(args: string[] = []): void {
 
   try {
     const clients = normalizeAgentClients(config);
-    const custom = normalizeCustomTUIs(process.cwd(), config.customTUIs ?? []);
+    const custom = normalizeCustomToolInvocations(config);
     const commands = renderNextStepCommands({
       projectName: String(config.project ?? ''),
       state: clients.state,
-      customTUIs: custom.items,
+      customToolInvocations: custom.items,
       skillName: parsed.skillName,
       ...(parsed.taskRef ? { taskRef: parsed.taskRef } : {}),
       ...(parsed.version ? { version: parsed.version } : {})

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,