@fitlab-ai/agent-infra 0.9.13 → 0.9.15

package/lib/sandbox/task-cleanup.ts

@@ -0,0 +1,209 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { inspectOwnedPath } from '../owned-path.ts';
+import { parseTaskFrontmatter } from '../task/frontmatter.ts';
+import { readTaskFinalizationReceipt, type TaskFinalizationReceipt } from '../task/finalization.ts';
+import { taskFinalizationReceiptState, type TaskControlBindingEvidence, type TaskControlBinding as SandboxControlBinding } from '../task/finalization-state.ts';
+import { enumerateAllTaskDirs } from '../task/resolve-ref.ts';
+import { resolveSandboxCleanupTarget } from './workspace-identity.ts';
+import { readSandboxControlManifest } from './control/lifecycle.ts';
+import { readJsonFile, readSandboxControlStatus } from './control/state.ts';
+import { finalizationTerminalResponse } from './control/finalization-response.ts';
+
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+
+function matchingControlManifest(repoRoot: string, controlRoot: string, taskId: string, binding: SandboxControlBinding) {
+  if (!controlRootIdentity(controlRoot)) return null;
+  const manifestPath = path.join(controlRoot, 'manifest.json');
+  let manifest;
+  try { manifest = readSandboxControlManifest(manifestPath); }
+  catch { return null; }
+  if (manifest.mode !== 'task-bound' || manifest.taskId !== taskId
+    || canonicalPath(manifest.repoRoot) !== repoRoot || manifest.generation !== binding.generation
+    || path.resolve(manifest.channelDir) !== path.join(controlRoot, 'channel')
+    || path.resolve(manifest.publicStatusDir) !== path.join(controlRoot, 'public')
+    || path.resolve(manifest.processingDir) !== path.join(controlRoot, 'processing')
+    || path.resolve(manifest.runtimeDir) !== path.join(controlRoot, 'runtime')) return null;
+  return manifest;
+}
+
+type DirectoryIdentity = Readonly<{ dev: string; ino: string }>;
+type SandboxRemovalJournalEvidence = Readonly<{
+  phase: string;
+  generation: string;
+  target: Readonly<{
+    branch: string;
+    controlRoot: string;
+  }>;
+}>;
+
+function errorCode(error: unknown): string | null {
+  const code = (error as NodeJS.ErrnoException | null)?.code;
+  return typeof code === 'string' ? code : null;
+}
+
+function controlBindingKey(taskId: string, binding: SandboxControlBinding): string {
+  return `${taskId}\0${binding.generation}\0${binding.requestId}`;
+}
+
+function controlRootIdentity(root: string): DirectoryIdentity | null {
+  try {
+    const stat = fs.lstatSync(root);
+    if (!stat.isDirectory() || stat.isSymbolicLink()) return null;
+    return { dev: String(stat.dev), ino: String(stat.ino) };
+  } catch {
+    return null;
+  }
+}
+
+function controlRootState(
+  root: string,
+  expected: DirectoryIdentity
+): 'missing' | 'same' | 'replaced' {
+  let stat: fs.Stats;
+  try { stat = fs.lstatSync(root); }
+  catch (error) { return errorCode(error) === 'ENOENT' ? 'missing' : 'replaced'; }
+  if (stat.isSymbolicLink() || !stat.isDirectory()) return 'replaced';
+  return String(stat.dev) === expected.dev && String(stat.ino) === expected.ino ? 'same' : 'replaced';
+}
+
+function controlRootIsAbsent(root: string): boolean {
+  try {
+    fs.lstatSync(root);
+    return false;
+  } catch (error) {
+    return errorCode(error) === 'ENOENT';
+  }
+}
+
+function canonicalPath(input: string): string {
+  try { return fs.realpathSync.native(input); }
+  catch { return path.resolve(input); }
+}
+
+function taskFinalizationReceiptComplete(
+  receipt: TaskFinalizationReceipt,
+  taskId: string,
+  binding: SandboxControlBinding
+): boolean {
+  return receipt.taskId === taskId
+    && taskFinalizationReceiptState(receipt) === 'complete'
+    && receipt.controlBinding?.generation === binding.generation
+    && receipt.controlBinding.requestId === binding.requestId;
+}
+
+function terminalControlBindingEvidence(
+  repoRootInput: string,
+  controlRootInput: string,
+  taskId: string,
+  binding: SandboxControlBinding
+): boolean {
+  const repoRoot = canonicalPath(repoRootInput);
+  const controlRoot = path.resolve(controlRootInput);
+  if (!TASK_ID_RE.test(taskId) || !controlRootIdentity(controlRoot)) return false;
+  const manifestPath = path.join(controlRoot, 'manifest.json');
+  if (!inspectOwnedPath(controlRoot, manifestPath, 'file')) return false;
+  const manifest = matchingControlManifest(repoRoot, controlRoot, taskId, binding);
+  if (!manifest) return false;
+  try {
+    const leasePath = path.join(controlRoot, 'lease.json');
+    try {
+      fs.lstatSync(leasePath);
+      return false;
+    } catch (error) {
+      if (errorCode(error) !== 'ENOENT') return false;
+    }
+    const receipt = readTaskFinalizationReceipt(repoRoot, taskId);
+    if (!receipt || !taskFinalizationReceiptComplete(receipt, taskId, binding)) {
+      return false;
+    }
+    const status = readSandboxControlStatus(manifest.publicStatusDir);
+    const viewReceipt = status.taskView.receipt;
+    const terminalTaskView = (status.taskView.state === 'current' && status.taskView.observedSource === 'completed')
+      || (status.taskView.state === 'finalized-stale' && status.taskView.observedSource === 'active');
+    if (status.generation !== binding.generation || status.state !== 'healthy'
+      || status.activeRequestId !== null || !terminalTaskView || status.taskView.taskId !== taskId
+      || !viewReceipt || viewReceipt.generation !== binding.generation
+      || viewReceipt.requestId !== binding.requestId
+      || viewReceipt.receiptId !== receipt.receiptId
+      || viewReceipt.revision !== receipt.revision) return false;
+    const responsePath = path.join(manifest.channelDir, 'responses', `${binding.requestId}.json`);
+    if (!inspectOwnedPath(path.join(controlRoot, 'channel'), responsePath, 'file')) return false;
+    const actual = readJsonFile(responsePath);
+    const expected = finalizationTerminalResponse(taskId, binding.requestId, receipt);
+    return JSON.stringify(actual) === JSON.stringify(expected);
+  } catch {
+    return false;
+  }
+}
+
+function removedControlBindingEvidence(
+  repoRootInput: string,
+  journal: SandboxRemovalJournalEvidence,
+  taskId: string,
+  binding: SandboxControlBinding
+): boolean {
+  const repoRoot = canonicalPath(repoRootInput);
+  if (journal.phase !== 'completed'
+    || journal.generation !== binding.generation
+    || !path.isAbsolute(journal.target.controlRoot)) return false;
+  const controlRoot = path.resolve(journal.target.controlRoot);
+  if (!controlRootIsAbsent(controlRoot)) return false;
+  const task = enumerateAllTaskDirs(repoRoot).find((entry) => entry.taskId === taskId);
+  if (!task || (task.state !== 'completed' && task.state !== 'archive')) return false;
+  let frontmatter: Record<string, string>;
+  try { frontmatter = parseTaskFrontmatter(fs.readFileSync(path.join(task.taskDir, 'task.md'), 'utf8')); }
+  catch { return false; }
+  if (frontmatter.id !== taskId || frontmatter.branch !== journal.target.branch) return false;
+  try {
+    const receipt = readTaskFinalizationReceipt(repoRoot, taskId);
+    return receipt !== null && taskFinalizationReceiptComplete(receipt, taskId, binding);
+  } catch {
+    return false;
+  }
+}
+
+export function createSandboxControlBindingEvidence(
+  repoRoot: string,
+  controlRoots: readonly string[],
+  removalJournals: readonly SandboxRemovalJournalEvidence[] = []
+): TaskControlBindingEvidence {
+  const canonicalRepoRoot = canonicalPath(repoRoot);
+  const roots = [...new Set(controlRoots.map((candidate) => path.resolve(candidate)))];
+  const captured = roots.flatMap((controlRoot) => {
+    let manifest;
+    try { manifest = readSandboxControlManifest(path.join(controlRoot, 'manifest.json')); }
+    catch { return []; }
+    const rootIdentity = controlRootIdentity(controlRoot);
+    if (!rootIdentity) return [];
+    const receipt = (() => {
+      try { return readSandboxControlStatus(manifest.publicStatusDir).taskView.receipt; }
+      catch { return null; }
+    })();
+    if (!receipt || !terminalControlBindingEvidence(canonicalRepoRoot, controlRoot, manifest.taskId ?? '', receipt)) return [];
+    return [{
+      controlRoot,
+      taskId: manifest.taskId!,
+      key: controlBindingKey(manifest.taskId!, receipt),
+      rootIdentity
+    }];
+  });
+  return (taskId, binding) => {
+    const terminal = captured.some((candidate) => {
+      if (candidate.taskId !== taskId || candidate.key !== controlBindingKey(taskId, binding)) return false;
+      const state = controlRootState(candidate.controlRoot, candidate.rootIdentity);
+      return state === 'missing'
+        || state === 'same' && terminalControlBindingEvidence(canonicalRepoRoot, candidate.controlRoot, taskId, binding);
+    }) || removalJournals.some((journal) => removedControlBindingEvidence(canonicalRepoRoot, journal, taskId, binding));
+    if (terminal) return 'terminal';
+    if (roots.some((root) => matchingControlManifest(canonicalRepoRoot, root, taskId, binding))) return 'pending';
+    try {
+      const branch = resolveSandboxCleanupTarget(taskId, canonicalRepoRoot, { allowProtected: true }).branch;
+      if (removalJournals.some((journal) => journal.phase !== 'completed'
+        && journal.generation === binding.generation && journal.target.branch === branch)) return 'pending';
+    } catch {
+      // Missing or conflicting task identity cannot authorize removal.
+    }
+    return 'mismatch';
+  };
+}

package/lib/sandbox/workspace-view.ts

@@ -3,10 +3,13 @@ import fs from 'node:fs';
 import path from 'node:path';
 import type { SandboxWorkspaceIdentity, SandboxWorkspaceKey } from './workspace-identity.ts';
 import type { SandboxControlManifest } from './control/protocol.ts';
+import {
+  createSandboxControlIdentitySentinel,
+  writeSandboxControlIdentitySentinel
+} from './control/identity-sentinel.ts';
 
 export type SandboxWorkspaceView = Readonly<{
   root: string;
-  taskMountPath: string | null;
 }>;
 
 export const SANDBOX_WORKSPACE_VIEW_STATES = Object.freeze([
@@ -38,12 +41,7 @@ export function sandboxWorkspaceViewPaths(params: Readonly<{
   const digest = createHash('sha256').update(identityKey).digest('hex').slice(0, 16);
   const projectRoot = path.resolve(params.base, params.project);
   const root = path.resolve(projectRoot, params.container, digest);
-  return {
-    root,
-    taskMountPath: params.identity.mode === 'task-bound'
-      ? path.join(root, 'active', params.identity.taskId)
-      : null
-  };
+  return { root };
 }
 
 export type SandboxControlSetup = Readonly<{
@@ -55,9 +53,10 @@ export type SandboxControlSetup = Readonly<{
   manifestDraft: SandboxControlManifestDraft;
   token: string;
   generation: string;
+  controlRootId: string;
 }>;
 
-export type SandboxControlManifestDraft = Readonly<Omit<SandboxControlManifest, 'containerIdentity' | 'engine'> & {
+export type SandboxControlManifestDraft = Readonly<Omit<SandboxControlManifest, 'containerIdentity' | 'engine' | 'authorityEvidence'> & {
   engine: string;
 }>;
 
@@ -158,7 +157,7 @@ export function materializeSandboxWorkspaceView(params: Readonly<{
   identity: SandboxWorkspaceIdentity;
 }>): SandboxWorkspaceView {
   const projectRoot = path.resolve(params.base, params.project);
-  const { root, taskMountPath } = sandboxWorkspaceViewPaths(params);
+  const { root } = sandboxWorkspaceViewPaths(params);
   assertSafeDirectory(projectRoot, path.resolve(params.base));
   assertSafeDirectory(root, projectRoot);
   fs.mkdirSync(root, { recursive: true, mode: 0o700 });
@@ -179,11 +178,7 @@ export function materializeSandboxWorkspaceView(params: Readonly<{
     encoding: 'utf8',
     mode: 0o600
   });
-  if (taskMountPath) {
-    assertSafeDirectory(taskMountPath, active);
-    fs.mkdirSync(taskMountPath, { recursive: true, mode: 0o700 });
-  }
-  return { root, taskMountPath };
+  return { root };
 }
 
 export function materializeSandboxControl(params: Readonly<{
@@ -234,6 +229,12 @@ export function materializeSandboxControl(params: Readonly<{
   }
   const token = randomBytes(32).toString('hex');
   const generation = randomBytes(16).toString('hex');
+  const identitySentinel = createSandboxControlIdentitySentinel({
+    mode: params.identity.mode,
+    taskId: params.identity.mode === 'task-bound' ? params.identity.taskId : null,
+    generation
+  });
+  writeSandboxControlIdentitySentinel(statusDir, identitySentinel);
   const repoRoot = fs.realpathSync.native(params.repoRoot);
   const manifestDraft: SandboxControlManifestDraft = {
     engine: params.engine ?? 'docker',
@@ -246,23 +247,30 @@ export function materializeSandboxControl(params: Readonly<{
     taskId: params.identity.mode === 'task-bound' ? params.identity.taskId : null,
     token,
     generation,
+    controlRootId: identitySentinel.controlRootId,
     channelDir,
     publicStatusDir: statusDir,
     processingDir,
-    runtimeDir
+    runtimeDir,
   };
-  return { root, channelDir, statusDir, runtimeDir, manifestPath, manifestDraft, token, generation };
+  return { root, channelDir, statusDir, runtimeDir, manifestPath, manifestDraft, token, generation, controlRootId: identitySentinel.controlRootId };
 }
 
 export function finalizeSandboxControlManifest(
   setup: SandboxControlSetup,
-  identity: Readonly<{ engine: string; id: string; labels: Readonly<Record<string, string>> }>
+  identity: Readonly<{
+    engine: string;
+    id: string;
+    labels: Readonly<Record<string, string>>;
+    authorityEvidence: SandboxControlManifest['authorityEvidence'];
+  }>
 ): SandboxControlManifest {
   if (!identity.engine || !identity.id) throw new Error('SANDBOX_CONTROL_CONTAINER_ID_INVALID');
   const manifest: SandboxControlManifest = {
     ...setup.manifestDraft,
     engine: identity.engine,
-    containerIdentity: { id: identity.id, labels: { ...identity.labels } }
+    containerIdentity: { id: identity.id, labels: { ...identity.labels } },
+    authorityEvidence: identity.authorityEvidence
   };
   const temporary = `${setup.manifestPath}.${process.pid}.${randomBytes(8).toString('hex')}.tmp`;
   try {

package/lib/sandbox/worktree-safety.ts

@@ -436,7 +436,10 @@ function verifyWorktreePermit(
     ? inspectRecoveredWorktree(permit.snapshot.worktree, permit.snapshot.recovery, options)
     : inspectWorktree(permit.snapshot.worktree, options);
   if (current.status === 'failed') throw new Error(`Unable to verify worktree permit: ${current.message}`);
-  if (current.snapshot.identity !== permit.snapshot.identity || (permit.mode === 'clean' && current.status !== 'clean')) {
+  const sameTarget = current.snapshot.worktree === permit.snapshot.worktree
+    && current.snapshot.branch === permit.snapshot.branch;
+  if (!sameTarget || (permit.mode === 'clean'
+    && (current.snapshot.identity !== permit.snapshot.identity || current.status !== 'clean'))) {
     throw new Error(`Worktree changed after authorization: ${permit.snapshot.worktree}`);
   }
   return current.snapshot;

package/lib/server/index.ts

@@ -1,5 +1,8 @@
 import { runDaemon } from './daemon.ts';
 import { start, stop, status, logs } from './process-control.ts';
+import { PUBLIC_CLI_ROUTE_SELECTORS } from '../internal/cli-route-inventory.ts';
+
+const SERVER_OPERATIONS = PUBLIC_CLI_ROUTE_SELECTORS.server;
 
 const USAGE = `Usage: ai server <command> [options]
 
@@ -25,6 +28,13 @@ export async function runServer(args: string[]): Promise<void> {
     return;
   }
 
+  if (!SERVER_OPERATIONS.includes(subcommand as typeof SERVER_OPERATIONS[number])) {
+    process.stderr.write(`Unknown server command: ${subcommand}\n`);
+    process.stdout.write(`${USAGE}\n`);
+    process.exitCode = 1;
+    return;
+  }
+
   switch (subcommand) {
     case 'start':
       await start({ foreground: rest.includes('--foreground') });

package/lib/task/activity-intent.ts

@@ -6,9 +6,9 @@ import { locateActivityLog, appendActivityEntry } from './activity-log.ts';
 import {
   assertWritableInventory,
   buildArtifactLinkSection,
-  inspectTaskArtifacts,
-  parseArtifactName
+  inspectTaskArtifacts
 } from './artifact-lifecycle.ts';
+import { parseArtifactName } from './artifact-name.ts';
 import type { ArtifactIdentity } from './artifact-lifecycle.ts';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.ts';
 import type { TaskExecutionLockOptions } from './task-execution-lock.ts';

package/lib/task/activity-log.ts

@@ -1,5 +1,4 @@
-const HEADING_RE = /^##\s+(活动日志|Activity Log)\s*$/;
-const NEXT_H2_RE = /^##\s/;
+import { scanVisibleMarkdown } from './markdown.ts';
 const ENTRY_RE = /^- (\d{4}-\d{2}-\d{2} \d{2}:\d{2}:\d{2}[+-]\d{2}:\d{2}) — \*\*(.+?)\*\* by (.+?) — (.*)$/;
 const STARTED_SUFFIX_RE = /\s*\[started\]\s*$/;
 const ABORTED_SUFFIX_RE = /\s*\[aborted\]\s*$/;
@@ -17,24 +16,32 @@ function parseActivityLog(content: string): { sectionFound: boolean; entries: Lo
   return section ? { sectionFound: true, entries: section.entries } : { sectionFound: false, entries: [] };
 }
 
-function locateActivityLog(content: string): ActivityLogSection | null {
-  const lines = content.split('\n');
-  const headings = lines.map((line, index) => HEADING_RE.test(line) ? index : -1).filter((index) => index >= 0);
-  if (headings.length !== 1) return null;
-  const i = headings[0]!;
-  let end = lines.length;
-  for (let j = i + 1; j < lines.length; j += 1) {
-    if (NEXT_H2_RE.test(lines[j]!)) { end = j; break; }
-  }
-  const bodyLines = lines.slice(i + 1, end);
-  const parsed: { entry: LogEntry; epoch: number; order: number }[] = [];
-  for (const line of bodyLines) {
-    const m = ENTRY_RE.exec(line);
-    if (!m) continue;
-    parsed.push({ entry: { time: m[1]!, step: m[2]!, agent: m[3]!, note: m[4]! }, epoch: Date.parse(m[1]!.replace(' ', 'T')), order: parsed.length });
+/** Returns source-order entries and malformed bullets without applying display or gate policy. */
+function inspectActivityLog(content: string): { section: ActivityLogSection | null; invalidEntries: string[] } {
+  const scanned = scanVisibleMarkdown(content);
+  const headings = scanned.headings.filter((heading) => heading.level === 2);
+  const matches = headings.filter((heading) => heading.text === '活动日志' || heading.text === 'Activity Log');
+  if (matches.length !== 1) return { section: null, invalidEntries: [] };
+  const heading = matches[0]!;
+  const end = headings.find((candidate) => candidate.start > heading.start)?.start ?? content.length;
+  const entries: LogEntry[] = [];
+  const invalidEntries: string[] = [];
+  for (const line of scanned.lines) {
+    if (line.start <= heading.end || line.start >= end) continue;
+    const text = line.text.trimStart();
+    const match = ENTRY_RE.exec(text);
+    if (match) entries.push({ time: match[1]!, step: match[2]!, agent: match[3]!, note: match[4]! });
+    else if (text.startsWith('- ')) invalidEntries.push(text);
   }
-  parsed.sort((a, b) => a.epoch - b.epoch || a.order - b.order);
-  return { heading: HEADING_RE.exec(lines[i]!)![1]!, body: bodyLines.join('\n').replace(/^\n+|\n+$/g, ''), entries: parsed.map((item) => item.entry) };
+  const body = content.slice(heading.end + 1, end).replace(/\r\n/g, '\n').replace(/^\n+|\n+$/g, '');
+  return { section: { heading: heading.text, body, entries }, invalidEntries };
+}
+
+function locateActivityLog(content: string): ActivityLogSection | null {
+  const { section } = inspectActivityLog(content);
+  if (!section) return null;
+  section.entries.sort((left, right) => Date.parse(left.time.replace(' ', 'T')) - Date.parse(right.time.replace(' ', 'T')));
+  return section;
 }
 
 function appendActivityEntry(section: ActivityLogSection, entry: LogEntry): string {
@@ -105,6 +112,7 @@ export {
   appendActivityEntry,
   hasOpenLifecycleExecution,
   commitAttemptStartedNote,
+  inspectActivityLog,
   locateActivityLog,
   pairEntries,
   parseActivityLog,

package/lib/task/artifact-command.ts

@@ -0,0 +1,104 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { readStableFileSync } from '../host-control/secure-fs.ts';
+
+import { resolveArtifactContext, hasOpenArtifactRound } from './artifact-lifecycle.ts';
+import { parseArtifactName } from './artifact-name.ts';
+import { resolveTaskRef } from './resolve-ref.ts';
+import { getArtifactSchema } from './artifact-schema.ts';
+import { finalizeLocalArtifact } from './local-artifact-finalization.ts';
+import { applyArtifactRepair, initializeArtifactSkeleton, inspectArtifactStructure } from './artifact-operations.ts';
+
+export type ArtifactCommand = Readonly<{
+  taskRef: string;
+  operation: 'inspect' | 'init' | 'repair' | 'finalize-local';
+  family: string;
+  artifact: string;
+  locale?: 'zh-CN' | 'en';
+  expectedSha256: string;
+  expectedSemanticDigest: string;
+}>;
+
+/** One option contract for the CLI and trusted projection executor. */
+export function parseArtifactCommand(args: readonly string[]): ArtifactCommand {
+  const [taskRef, operation] = args;
+  if (!taskRef || !['inspect', 'init', 'repair', 'finalize-local'].includes(operation ?? '')) {
+    throw new Error('task ref and a supported artifact operation are required');
+  }
+  const fields: Record<string, string> = {};
+  const allowed = {
+    inspect: ['--family'],
+    init: ['--family', '--artifact', '--locale'],
+    repair: ['--family', '--artifact', '--expected-sha256', '--expected-semantic-digest'],
+    'finalize-local': ['--family', '--artifact']
+  }[operation as ArtifactCommand['operation']];
+  for (let index = 2; index < args.length; index += 1) {
+    const flag = args[index]!;
+    if (!allowed.includes(flag)) throw new Error(`unknown option '${flag}'`);
+    if (Object.hasOwn(fields, flag)) throw new Error(`duplicate option '${flag}'`);
+    const value = args[++index];
+    if (!value || value.startsWith('--')) throw new Error(`option '${flag}' requires a value`);
+    fields[flag] = value;
+  }
+  if (!fields['--family']) throw new Error("option '--family' is required");
+  if (operation !== 'inspect' && !fields['--artifact']) throw new Error("option '--artifact' is required");
+  const locale = fields['--locale'];
+  if (locale !== undefined && locale !== 'zh-CN' && locale !== 'en') throw new Error("option '--locale' must be 'zh-CN' or 'en'");
+  if (operation === 'repair' && !['--expected-sha256', '--expected-semantic-digest'].every((flag) => /^[a-f0-9]{64}$/u.test(fields[flag] ?? ''))) {
+    throw new Error('repair requires lowercase 64-character digests');
+  }
+  return {
+    taskRef, operation: operation as ArtifactCommand['operation'], family: fields['--family'],
+    artifact: fields['--artifact'] ?? '', locale,
+    expectedSha256: fields['--expected-sha256'] ?? '', expectedSemanticDigest: fields['--expected-semantic-digest'] ?? ''
+  };
+}
+/** Resolve authoritative task metadata separately from a trusted candidate directory. */
+export function executeArtifactCommand(
+  command: ArtifactCommand,
+  options: Readonly<{ repoRoot?: string; artifactDir?: string }> = {}
+): Record<string, unknown> {
+  const { taskRef, operation, family, artifact, locale, expectedSha256, expectedSemanticDigest } = command;
+  const fail = (code: string, message: string) => ({ status: 'failed', changed: false, error: { code, message } });
+  if (operation === 'inspect') {
+    const result = resolveArtifactContext(taskRef, family, { repoRoot: options.repoRoot });
+    return family === 'code' && result.codeMode ? {
+      ...result, mode: result.codeMode.mode, code_max: result.codeMode.codeMax, rev_max: result.codeMode.reviewMax,
+      verdict: result.codeMode.verdict, next_round: result.next?.round ?? null, next_artifact: result.next?.name ?? null,
+      review_artifact: result.codeMode.reviewArtifact, implementation_input: result.codeMode.implementationInput,
+      decision_id: result.codeMode.decisionId, decision_evidence: result.codeMode.decisionEvidence, message: result.codeMode.message
+    } : { ...result };
+  }
+  const resolved = resolveTaskRef(taskRef, { repoRoot: options.repoRoot });
+  if (!resolved.ok) return fail(resolved.code, resolved.message);
+  const schema = getArtifactSchema(family);
+  const parsed = parseArtifactName(artifact);
+  if (!schema || !parsed || parsed.family !== family) {
+    return fail('ARTIFACT_IDENTITY_INVALID', `artifact '${artifact}' does not match ${family}`);
+  }
+  const taskDir = options.artifactDir ?? resolved.taskDir;
+  const identity = { taskId: resolved.taskId, taskDir, family, artifact };
+  const input = { repoRoot: resolved.repoRoot, taskId: resolved.taskId, taskDir, family: schema.family, artifact };
+  if (operation === 'init') {
+    const context = resolveArtifactContext(taskRef, family, { repoRoot: resolved.repoRoot });
+    if (context.status !== 'ready' || (context.next?.name !== artifact && !hasOpenArtifactRound(fs.readFileSync(resolved.taskMdPath, 'utf8'), family, parsed.round))) {
+      return fail('ARTIFACT_INIT_CONTEXT_INVALID', context.error?.message ?? `artifact '${artifact}' is not the next ${family} artifact`);
+    }
+    return { ...initializeArtifactSkeleton({ ...input, ...(locale ? { locale } : {}) }), ...identity };
+  }
+  if (operation === 'repair') {
+    let content: string;
+    try { content = readStableFileSync(path.join(taskDir, artifact), { maxBytes: 1024 * 1024 }).bytes.toString('utf8'); }
+    catch (error) { return fail('ARTIFACT_REPAIR_TARGET_INVALID', String(error)); }
+    const inspection = inspectArtifactStructure(content, schema);
+    if (!inspection.repair) {
+      return { ...fail('ARTIFACT_REPAIR_UNSAFE', inspection.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ') || 'no deterministic structural repair is available'),
+        artifact, family, diagnostics: inspection.diagnostics };
+    }
+    return { ...applyArtifactRepair({ ...input, expectedSha256, expectedSemanticDigest, operation: inspection.repair }), ...identity };
+  }
+  if (family !== 'analysis' && family !== 'plan' && family !== 'code') {
+    return fail('ARTIFACT_PAYLOAD_INVALID', "finalize-local only supports 'analysis', 'plan', and 'code'");
+  }
+  return { ...finalizeLocalArtifact({ taskRef, family, artifact, repoRoot: resolved.repoRoot }) };
+}