@fitlab-ai/agent-infra 0.9.14 → 0.10.0

package/dist/lib/sandbox/task-cleanup.js

@@ -0,0 +1,217 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { inspectOwnedPath } from '../owned-path.js';
+import { parseTaskFrontmatter } from '../task/frontmatter.js';
+import { readTaskFinalizationReceipt } from '../task/finalization.js';
+import { taskFinalizationReceiptState } from '../task/finalization-state.js';
+import { enumerateAllTaskDirs } from '../task/resolve-ref.js';
+import { resolveSandboxCleanupTarget } from './workspace-identity.js';
+import { readSandboxControlManifest } from './control/lifecycle.js';
+import { readJsonFile, readSandboxControlStatus } from './control/state.js';
+import { finalizationTerminalResponse } from './control/finalization-response.js';
+const TASK_ID_RE = /^TASK-\d{8}-\d{6}$/;
+function matchingControlManifest(repoRoot, controlRoot, taskId, binding) {
+    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;
+}
+function errorCode(error) {
+    const code = error?.code;
+    return typeof code === 'string' ? code : null;
+}
+function controlBindingKey(taskId, binding) {
+    return `${taskId}\0${binding.generation}\0${binding.requestId}`;
+}
+function controlRootIdentity(root) {
+    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, expected) {
+    let stat;
+    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) {
+    try {
+        fs.lstatSync(root);
+        return false;
+    }
+    catch (error) {
+        return errorCode(error) === 'ENOENT';
+    }
+}
+function canonicalPath(input) {
+    try {
+        return fs.realpathSync.native(input);
+    }
+    catch {
+        return path.resolve(input);
+    }
+}
+function taskFinalizationReceiptComplete(receipt, taskId, binding) {
+    return receipt.taskId === taskId
+        && taskFinalizationReceiptState(receipt) === 'complete'
+        && receipt.controlBinding?.generation === binding.generation
+        && receipt.controlBinding.requestId === binding.requestId;
+}
+function terminalControlBindingEvidence(repoRootInput, controlRootInput, taskId, binding) {
+    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, journal, taskId, binding) {
+    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;
+    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, controlRoots, removalJournals = []) {
+    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';
+    };
+}
+//# sourceMappingURL=task-cleanup.js.map

package/dist/lib/sandbox/workspace-identity.js

@@ -98,7 +98,23 @@ export function resolveSandboxCleanupTarget(requestedRef, repoRoot, options = {}
         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;
+        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/dist/lib/sandbox/workspace-view.js

@@ -1,6 +1,7 @@
 import { createHash, randomBytes } from 'node:crypto';
 import fs from 'node:fs';
 import path from 'node:path';
+import { createSandboxControlIdentitySentinel, writeSandboxControlIdentitySentinel } from './control/identity-sentinel.js';
 export const SANDBOX_WORKSPACE_VIEW_STATES = Object.freeze([
     'active',
     'completed',
@@ -20,12 +21,7 @@ export function sandboxWorkspaceViewPaths(params) {
     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 function sandboxControlPaths(params) {
     const identityKey = params.identity.mode === 'task-bound'
@@ -108,7 +104,7 @@ export function prepareSandboxWorkspaceMountTargets(worktreeRoot) {
 }
 export function materializeSandboxWorkspaceView(params) {
     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 });
@@ -128,11 +124,7 @@ export function materializeSandboxWorkspaceView(params) {
         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) {
     const { root, channelDir, statusDir, processingDir, runtimeDir, manifestPath } = sandboxControlPaths(params);
@@ -170,6 +162,12 @@ export function materializeSandboxControl(params) {
     }
     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 = {
         engine: params.engine ?? 'docker',
@@ -182,12 +180,13 @@ export function materializeSandboxControl(params) {
         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, identity) {
     if (!identity.engine || !identity.id)

package/dist/lib/task/activity-intent.js

@@ -2,7 +2,8 @@ import fs from 'node:fs';
 import { normalizeAgentToken } from '../agent-clients/tokens.js';
 import { resolveTaskRef } from './resolve-ref.js';
 import { locateActivityLog, appendActivityEntry } from './activity-log.js';
-import { assertWritableInventory, buildArtifactLinkSection, inspectTaskArtifacts, parseArtifactName } from './artifact-lifecycle.js';
+import { assertWritableInventory, buildArtifactLinkSection, inspectTaskArtifacts } from './artifact-lifecycle.js';
+import { parseArtifactName } from './artifact-name.js';
 import { TaskExecutionLockError, withTaskExecutionLock } from './task-execution-lock.js';
 import { captureTaskWriteMetadata, writeTask } from './write.js';
 import { allowsManualOverride } from './guard-override.js';

package/dist/lib/task/activity-log.js

@@ -1,5 +1,4 @@
-const HEADING_RE = /^##\s+(活动日志|Activity Log)\s*$/;
-const NEXT_H2_RE = /^##\s/;
+import { scanVisibleMarkdown } from './markdown.js';
 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*$/;
@@ -10,29 +9,36 @@ function parseActivityLog(content) {
     const section = locateActivityLog(content);
     return section ? { sectionFound: true, entries: section.entries } : { sectionFound: false, entries: [] };
 }
-function locateActivityLog(content) {
-    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 = [];
-    for (const line of bodyLines) {
-        const m = ENTRY_RE.exec(line);
-        if (!m)
+/** Returns source-order entries and malformed bullets without applying display or gate policy. */
+function inspectActivityLog(content) {
+    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 = [];
+    const invalidEntries = [];
+    for (const line of scanned.lines) {
+        if (line.start <= heading.end || line.start >= end)
             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 });
+        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) {
+    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, entry) {
     const line = `- ${entry.time} — **${entry.step}** by ${entry.agent} — ${entry.note}`;
@@ -94,5 +100,5 @@ function hasOpenLifecycleExecution(content) {
         return false;
     return pairEntries(section.entries).some((row) => row.done === '' && LIFECYCLE_STEP_RE.test(row.step));
 }
-export { activityAttempt, appendActivityEntry, hasOpenLifecycleExecution, commitAttemptStartedNote, locateActivityLog, pairEntries, parseActivityLog, parseCommitAttemptStarted, startedBackedRows };
+export { activityAttempt, appendActivityEntry, hasOpenLifecycleExecution, commitAttemptStartedNote, inspectActivityLog, locateActivityLog, pairEntries, parseActivityLog, parseCommitAttemptStarted, startedBackedRows };
 //# sourceMappingURL=activity-log.js.map

package/dist/lib/task/artifact-command.js

@@ -0,0 +1,79 @@
+import fs from 'node:fs';
+import { resolveArtifactContext, hasOpenArtifactRound } from './artifact-lifecycle.js';
+import { parseArtifactName } from './artifact-name.js';
+import { resolveTaskRef } from './resolve-ref.js';
+import { getArtifactSchema } from './artifact-schema.js';
+import { finalizeLocalArtifact } from './local-artifact-finalization.js';
+import { initializeArtifactSkeleton } from './artifact-operations.js';
+/** One option contract for the CLI and trusted projection executor. */
+export function parseArtifactCommand(args) {
+    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 = {};
+    const allowed = {
+        inspect: ['--family'],
+        init: ['--family', '--artifact', '--locale'],
+        'finalize-local': ['--family', '--artifact', '--recovery-id']
+    }[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, 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, options = {}) {
+    const { taskRef, operation, family, artifact, locale, recoveryId } = command;
+    const fail = (code, message) => ({ 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 }) };
+}
+//# sourceMappingURL=artifact-command.js.map

package/dist/lib/task/artifact-lifecycle.js

@@ -1,16 +1,32 @@
 import fs from 'node:fs';
 import path from 'node:path';
+import { ARTIFACT_FAMILY_CATALOG, artifactName, parseArtifactName } from './artifact-name.js';
 import { resolveTaskRef } from './resolve-ref.js';
-import { locateActivityLog } from './activity-log.js';
+import { locateActivityLog, pairEntries, startedBackedRows } from './activity-log.js';
 import { parseImplementationInputs, selectPendingImplementationInput } from './implementation-inputs.js';
 import { parseVerdict } from './review-artifacts.js';
 import { extractSection, findSectionHeading } from './sections.js';
 import { receiptForOutput, sha256File } from './artifact-receipts.js';
 import { isArtifactInvalidated, parseInvalidationDocument } from './invalidation.js';
 import { validateQualificationAudit } from './qualification-audit.js';
-import { ARTIFACT_FAMILY_CATALOG } from './artifact-schema.js';
 const artifactFamilyCatalog = ARTIFACT_FAMILY_CATALOG;
-const FAMILY_SET = new Set(artifactFamilyCatalog.map((item) => item.family));
+const ARTIFACT_STEPS = {
+    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, family, round) {
+    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;
+}
 const BLOCKING_DIAGNOSTICS = new Set([
     'NONCANONICAL_NAME', 'ROUND_OUT_OF_RANGE', 'MISSING_BASE', 'ROUND_GAP',
     'DUPLICATE_LOGICAL_ROUND', 'NON_REGULAR_FILE', 'SYMBOLIC_LINK',
@@ -19,30 +35,6 @@ const BLOCKING_DIAGNOSTICS = new Set([
 function familySpec(family) {
     return artifactFamilyCatalog.find((item) => item.family === family) ?? null;
 }
-function artifactName(family, round) {
-    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) {
-    if (path.basename(name) !== name)
-        return null;
-    const matches = [];
-    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) {
     return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
 }
@@ -478,6 +470,16 @@ function validateCompletedArtifact(taskDir, family, name, round) {
     const artifact = inventory.artifacts.find((item) => item.name === 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, family, name) {
+    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, artifact) {
     const spec = familySpec(artifact.family);
     const aliases = [...spec.sectionAliases];
@@ -507,5 +509,5 @@ function buildArtifactLinkSection(content, artifact) {
     body = lines.join('\n').replace(/^\n+|\n+$/g, '');
     return { aliases, heading, body };
 }
-export { artifactFamilyCatalog, artifactName, parseArtifactName, familySpec, inspectTaskArtifacts, inspectArtifactDirectory, resolveArtifactContext, parseReviewedInputReference, parseCodePlanInputReference, resolveCodePlanInput, reviewEventName, assertWritableInventory, validateCompletedArtifact, buildArtifactLinkSection };
+export { artifactFamilyCatalog, familySpec, inspectTaskArtifacts, inspectArtifactDirectory, resolveArtifactContext, parseReviewedInputReference, parseCodePlanInputReference, resolveCodePlanInput, reviewEventName, assertWritableInventory, validateCompletedArtifact, buildArtifactLinkSection };
 //# sourceMappingURL=artifact-lifecycle.js.map

package/dist/lib/task/artifact-name.js

@@ -0,0 +1,36 @@
+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'] }
+];
+const FAMILIES = new Set(ARTIFACT_FAMILY_CATALOG.map(({ family }) => family));
+export function artifactName(family, round) {
+    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) {
+    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], round, name };
+}
+export function maxArtifactRound(names, family) {
+    return names.reduce((max, name) => {
+        const identity = parseArtifactName(name);
+        return identity?.family === family ? Math.max(max, identity.round) : max;
+    }, 0);
+}
+export { ARTIFACT_FAMILY_CATALOG };
+//# sourceMappingURL=artifact-name.js.map