@fitlab-ai/agent-infra 0.9.14 → 0.10.0

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-identity.ts

@@ -23,7 +23,7 @@ export type SandboxCleanupTarget = Readonly<{
   requestedRef: string;
   branch: string;
   workspace: SandboxWorkspaceKey;
-  taskState: TaskWorkspaceState | 'branch-only';
+  taskState: TaskWorkspaceState | 'branch-only' | 'unknown';
 }>;
 
 export type SandboxContainerWorkspaceIdentity =
@@ -147,14 +147,30 @@ export function resolveSandboxReentryContext(params: Readonly<{
 export function resolveSandboxCleanupTarget(
   requestedRef: string,
   repoRoot: string,
-  options: Readonly<{ allowProtected?: boolean }> = {}
+  options: Readonly<{
+    allowProtected?: boolean;
+    resolveMissingTask?: (taskId: string) => string | null;
+  }> = {}
 ): SandboxCleanupTarget {
   if (isRemovedHashShortIdInput(requestedRef)) {
     throw new Error(`Invalid task short id '${requestedRef}': task short ids must use bare digits`);
   }
 
   if (TASK_ID_RE.test(requestedRef)) {
-    const task = resolveTaskWorkspace(requestedRef, repoRoot);
+    let task: ReturnType<typeof resolveTaskWorkspace>;
+    try {
+      task = resolveTaskWorkspace(requestedRef, repoRoot);
+    } catch (error) {
+      if (!(error instanceof Error && error.message === `Task not found: ${requestedRef}`)) throw error;
+      const branch = options.resolveMissingTask?.(requestedRef);
+      if (!branch) throw error;
+      return {
+        requestedRef,
+        branch,
+        workspace: { mode: 'task-bound', taskId: requestedRef },
+        taskState: 'unknown'
+      };
+    }
     if (!options.allowProtected && (task.state === 'blocked' || task.state === 'archive')) {
       throw new Error(`SANDBOX_CLEANUP_STATE_UNSUPPORTED: task ${requestedRef} is ${task.state}`);
     }

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,6 +53,7 @@ export type SandboxControlSetup = Readonly<{
   manifestDraft: SandboxControlManifestDraft;
   token: string;
   generation: string;
+  controlRootId: string;
 }>;
 
 export type SandboxControlManifestDraft = Readonly<Omit<SandboxControlManifest, 'containerIdentity' | 'engine' | 'authorityEvidence'> & {
@@ -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,12 +247,13 @@ 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(

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,85 @@
+import fs from 'node:fs';
+
+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 { initializeArtifactSkeleton } from './artifact-operations.ts';
+
+export type ArtifactCommand = Readonly<{
+  taskRef: string;
+  operation: 'inspect' | 'init' | 'finalize-local';
+  family: string;
+  artifact: string;
+  locale?: 'zh-CN' | 'en';
+  recoveryId?: 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', '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'],
+    'finalize-local': ['--family', '--artifact', '--recovery-id']
+  }[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'");
+  return {
+    taskRef, operation: operation as ArtifactCommand['operation'], family: fields['--family'],
+    artifact: fields['--artifact'] ?? '', locale, recoveryId: fields['--recovery-id']
+  };
+}
+/** 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, recoveryId } = 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 (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, recoveryId }) };
+}

package/lib/task/artifact-lifecycle.ts

@@ -1,9 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
 
+import { ARTIFACT_FAMILY_CATALOG, artifactName, parseArtifactName } from './artifact-name.ts';
 import { resolveTaskRef } from './resolve-ref.ts';
 import type { ResolveTaskRefErrorCode, TaskWorkspaceState } from './resolve-ref.ts';
-import { locateActivityLog } from './activity-log.ts';
+import { locateActivityLog, pairEntries, startedBackedRows } from './activity-log.ts';
 import { parseImplementationInputs, selectPendingImplementationInput } from './implementation-inputs.ts';
 import { parseVerdict } from './review-artifacts.ts';
 import { extractSection, findSectionHeading } from './sections.ts';
@@ -11,10 +12,27 @@ import { receiptForOutput, sha256File } from './artifact-receipts.ts';
 import { isArtifactInvalidated, parseInvalidationDocument } from './invalidation.ts';
 import type { InvalidationDocument } from './invalidation.ts';
 import { validateQualificationAudit } from './qualification-audit.ts';
-import { ARTIFACT_FAMILY_CATALOG } from './artifact-schema.ts';
-import type { ArtifactFamily, ArtifactFamilySpec } from './artifact-schema.ts';
+import type { ArtifactFamily, ArtifactFamilySpec } from './artifact-name.ts';
 
 const artifactFamilyCatalog = ARTIFACT_FAMILY_CATALOG;
+const ARTIFACT_STEPS: Readonly<Record<string, string>> = {
+  analysis: 'Analyze Task', 'review-analysis': 'Review Analysis',
+  plan: 'Plan Task', 'review-plan': 'Review Plan',
+  code: 'Code Task', 'review-code': 'Review Code'
+};
+
+/** Init, repair and finalization share the same authoritative round identity. */
+export function hasOpenArtifactRound(content: string, family: string, round: number): boolean {
+  const activity = locateActivityLog(content);
+  const step = ARTIFACT_STEPS[family];
+  if (!activity || !step) return false;
+  const qualifier = family === 'code'
+    ? '(?:, (?:fix for review-code(?:-r(?:[2-9]|[1-9]\\d+))?\\.md|decision II-[1-9]\\d*))?'
+    : '';
+  const expected = new RegExp(`^${step} \\(Round ${round}${qualifier}\\)$`);
+  return startedBackedRows(pairEntries(activity.entries)).filter((row) => expected.test(row.step) && !row.done).length === 1;
+}
+
 type ArtifactIdentity = {
   family: ArtifactFamily;
   round: number;
@@ -75,7 +93,6 @@ type ArtifactContextResult = Omit<ArtifactInventoryResult, 'status'> & {
 };
 type InspectOptions = { repoRoot?: string };
 
-const FAMILY_SET = new Set<string>(artifactFamilyCatalog.map((item) => item.family));
 const BLOCKING_DIAGNOSTICS = new Set<ArtifactDiagnosticCode>([
   'NONCANONICAL_NAME', 'ROUND_OUT_OF_RANGE', 'MISSING_BASE', 'ROUND_GAP',
   'DUPLICATE_LOGICAL_ROUND', 'NON_REGULAR_FILE', 'SYMBOLIC_LINK',
@@ -86,27 +103,6 @@ function familySpec(family: string): ArtifactFamilySpec | null {
   return artifactFamilyCatalog.find((item) => item.family === family) ?? null;
 }
 
-function artifactName(family: ArtifactFamily, round: number): string {
-  if (!FAMILY_SET.has(family)) throw new Error(`unknown artifact family '${family}'`);
-  if (!Number.isSafeInteger(round) || round < 1) throw new Error('artifact round must be a safe positive integer');
-  return round === 1 ? `${family}.md` : `${family}-r${round}.md`;
-}
-
-function parseArtifactName(name: string): { family: ArtifactFamily; round: number; name: string } | null {
-  if (path.basename(name) !== name) return null;
-  const matches: Array<{ family: ArtifactFamily; round: number; name: string }> = [];
-  for (const spec of artifactFamilyCatalog) {
-    if (name === `${spec.family}.md`) matches.push({ family: spec.family, round: 1, name });
-    const match = new RegExp(`^${escapeRegExp(spec.family)}-r([1-9]\\d*)\\.md$`).exec(name);
-    if (!match) continue;
-    const round = Number(match[1]);
-    if (Number.isSafeInteger(round) && round >= 2 && String(round) === match[1]) {
-      matches.push({ family: spec.family, round, name });
-    }
-  }
-  return matches.length === 1 ? matches[0]! : null;
-}
-
 function escapeRegExp(value: string): string {
   return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -518,6 +514,15 @@ function validateCompletedArtifact(taskDir: string, family: ArtifactFamily, name
   return artifact ? { ok: true, artifact } : { ok: false, error: { code: 'ARTIFACT_NOT_FOUND', message: `artifact '${name}' is not in inventory` } };
 }
 
+/** A candidate may replace its current slot or fill the next slot, never skip rounds. */
+export function validateArtifactPublication(taskDir: string, family: ArtifactFamily, name: string): ArtifactError | null {
+  const inventory = inspectArtifactDirectory(taskDir, family);
+  const error = assertWritableInventory(inventory);
+  if (error) return error;
+  if (inventory.next?.name === name || inventory.artifacts.some((artifact) => artifact.name === name)) return null;
+  return { code: 'ARTIFACT_IDENTITY_INVALID', message: `artifact '${name}' is not a current or next ${family} slot` };
+}
+
 function buildArtifactLinkSection(content: string, artifact: ArtifactIdentity): {
   aliases: readonly string[];
   heading: string;
@@ -550,7 +555,7 @@ function buildArtifactLinkSection(content: string, artifact: ArtifactIdentity):
 }
 
 export {
-  artifactFamilyCatalog, artifactName, parseArtifactName, familySpec,
+  artifactFamilyCatalog, familySpec,
   inspectTaskArtifacts, inspectArtifactDirectory, resolveArtifactContext,
   parseReviewedInputReference, parseCodePlanInputReference, resolveCodePlanInput, reviewEventName,
   assertWritableInventory, validateCompletedArtifact, buildArtifactLinkSection

package/lib/task/artifact-name.ts

@@ -0,0 +1,55 @@
+type ArtifactFamily =
+  | 'analysis'
+  | 'review-analysis'
+  | 'plan'
+  | 'review-plan'
+  | 'code'
+  | 'review-code'
+  | 'manual-validation'
+  | 'validation-run'
+  | 'pr-review';
+
+type ArtifactFamilySpec = Readonly<{
+  family: ArtifactFamily;
+  sectionAliases: readonly [string, string];
+  heading: string;
+  labels: readonly [string, string];
+}>;
+
+const ARTIFACT_FAMILY_CATALOG = [
+  { family: 'analysis', sectionAliases: ['分析', 'Analysis'], heading: '分析', labels: ['需求分析报告', 'Requirements Analysis'] },
+  { family: 'review-analysis', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['需求分析审查', 'Analysis Review'] },
+  { family: 'plan', sectionAliases: ['设计', 'Design'], heading: '设计', labels: ['技术方案', 'Technical Plan'] },
+  { family: 'review-plan', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['技术方案审查', 'Plan Review'] },
+  { family: 'code', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['实现报告', 'Implementation Report'] },
+  { family: 'review-code', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['代码审查', 'Code Review'] },
+  { family: 'manual-validation', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['人工验证', 'Manual Validation'] },
+  { family: 'validation-run', sectionAliases: ['实现备注', 'Implementation Notes'], heading: '实现备注', labels: ['验证运行证据', 'Validation Run Evidence'] },
+  { family: 'pr-review', sectionAliases: ['审查反馈', 'Review Feedback'], heading: '审查反馈', labels: ['PR 审查报告', 'PR Review Report'] }
+] as const satisfies readonly ArtifactFamilySpec[];
+
+const FAMILIES = new Set<string>(ARTIFACT_FAMILY_CATALOG.map(({ family }) => family));
+
+export function artifactName(family: ArtifactFamily, round: number): string {
+  if (!FAMILIES.has(family)) throw new Error(`unknown artifact family '${family}'`);
+  if (!Number.isSafeInteger(round) || round < 1) throw new Error('artifact round must be a safe positive integer');
+  return round === 1 ? `${family}.md` : `${family}-r${round}.md`;
+}
+
+export function parseArtifactName(name: string): { family: ArtifactFamily; round: number; name: string } | null {
+  const match = /^(.+?)(?:-r([1-9]\d*))?\.md$/.exec(name);
+  if (!match || match[0] !== name || !FAMILIES.has(match[1]!)) return null;
+  const round = match[2] ? Number(match[2]) : 1;
+  if (!Number.isSafeInteger(round) || (match[2] && round < 2)) return null;
+  return { family: match[1] as ArtifactFamily, round, name };
+}
+
+export function maxArtifactRound(names: readonly string[], family: string): number {
+  return names.reduce((max, name) => {
+    const identity = parseArtifactName(name);
+    return identity?.family === family ? Math.max(max, identity.round) : max;
+  }, 0);
+}
+
+export { ARTIFACT_FAMILY_CATALOG };
+export type { ArtifactFamily, ArtifactFamilySpec };