@fitlab-ai/agent-infra 0.10.0 → 0.11.1

package/lib/sandbox/control/executor.ts

@@ -188,7 +188,9 @@ export async function prepareSandboxControlExecution(params: {
         owner: gateOwner,
         requestId: params.request.id,
         operationId: authority?.operationId ?? params.request.id,
-        phase: authority?.phase ?? (params.request.family === 'task-workflow' ? 'artifact.finalize-local' : 'orchestration.prepare'),
+        phase: authority?.phase ?? (params.request.family === 'task-workflow'
+          && params.request.workflow?.operation === 'artifact-preflight' ? 'artifact.preflight'
+          : params.request.family === 'task-workflow' ? 'artifact.finalize-local' : 'orchestration.prepare'),
         authority
       } satisfies SandboxControlExecutorGateV2);
     },
@@ -235,7 +237,7 @@ function waitForGate(nonce: string, timeoutMs = 2_000): Promise<Readonly<{ owner
         return;
       }
       if (typeof value.requestId !== 'string' || typeof value.operationId !== 'string'
-        || !['orchestration.prepare', 'artifact.finalize-local', 'task-event.completed'].includes(value.phase as string)
+        || !['orchestration.prepare', 'artifact.preflight', 'artifact.finalize-local', 'task-event.completed'].includes(value.phase as string)
         || (value.authority !== null && value.authority !== undefined && (() => {
           try { validateLifecycleRecoveryAttestation(value.authority); return false; } catch { return true; }
         })())) {

package/lib/sandbox/control/protocol.ts

@@ -62,7 +62,7 @@ export type SandboxControlExecutorGateV2 = Readonly<{
   owner: SandboxControlBrokerOwner;
   requestId: string;
   operationId: string;
-  phase: 'orchestration.prepare' | 'artifact.finalize-local' | 'task-event.completed';
+  phase: 'orchestration.prepare' | 'artifact.preflight' | 'artifact.finalize-local' | 'task-event.completed';
   authority: LifecycleRecoveryAttestationV1 | null;
 }>;
 type RequestBase = Readonly<{

package/lib/sandbox/control/task-workflow.ts

@@ -2,7 +2,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
-import { readStableFile, SecureFileError, writeAtomicFile } from '../../host-control/secure-fs.ts';
+import { readStableFile, SecureFileError, writeAtomicFile } from '../../task/secure-fs.ts';
 
 import { TASK_WORKFLOW_COMMANDS, TASK_WORKFLOW_OPERATIONS, type TaskWorkflowOperation, type WorkflowCommand } from '../../task/workflow-command.ts';
 

package/lib/sandbox/control/workflow-executor.ts

@@ -2,10 +2,15 @@ import { TASK_WORKFLOW_COMMANDS } from '../../task/workflow-command.ts';
 
 import { parseArtifactCommand, executeArtifactCommand } from '../../task/artifact-command.ts';
 import { parseReviewCommand } from '../../task/review-command.ts';
-import { prepareLocalArtifact, commitLocalArtifactProvenance } from '../../task/local-artifact-finalization.ts';
-import { prepareReviewSummaryCandidate, commitReviewSummaryProvenance } from '../../task/review-finalization.ts';
+import { prepareLocalArtifact, preflightLocalArtifact, commitLocalArtifactProvenance } from '../../task/local-artifact-finalization.ts';
+import {
+  prepareReviewSummaryCandidate,
+  commitReviewSummaryProvenance,
+  preflightReviewSummary
+} from '../../task/review-finalization.ts';
+import { readArtifactRecoveryIntent } from '../../task/artifact-repair-intent.ts';
 import { withTaskExecutionLock } from '../../task/task-execution-lock.ts';
-import { dispatchHostControlCommand } from '../../host-control/command.ts';
+import { dispatchWorkflowCommand } from '../../task/workflow-dispatch.ts';
 import { assertSandboxTaskSource } from '../workspace-view.ts';
 import { appendDiagnosticAudit } from './audit.ts';
 import {
@@ -17,6 +22,17 @@ import type { LifecycleRecoveryAttestationV1 } from '../../task/control-authorit
 import { applyTaskEvent } from '../../task/events.ts';
 import { parseTaskEventRequest } from '../../internal/task-event.ts';
 
+export type TaskWorkflowFaultWindow =
+  | 'before-call'
+  | 'before-domain-write'
+  | 'after-atomic-rename'
+  | 'before-result-return';
+
+export type TaskWorkflowExecutionOptions = Readonly<{
+  /** Deterministic test seam; production callers leave this unset. */
+  faultWindow?: TaskWorkflowFaultWindow;
+}>;
+
 function executionResult(result: Record<string, unknown>): SandboxControlExecutionResult {
   return { exitCode: result.status === 'failed' || result.status === 'refused' ? 1 : 0, stdout: `${JSON.stringify(result)}\n`, stderr: '' };
 }
@@ -25,10 +41,41 @@ function executionResult(result: Record<string, unknown>): SandboxControlExecuti
 export async function executeTaskWorkflow(
   manifest: SandboxControlManifest,
   request: TaskWorkflowRequest,
-  lifecycleRecoveryAttestation: LifecycleRecoveryAttestationV1 | null = null
+  lifecycleRecoveryAttestation: LifecycleRecoveryAttestationV1 | null = null,
+  options: TaskWorkflowExecutionOptions = {}
 ): Promise<SandboxControlExecutionResult> {
-  let publicationStarted = false;
+  let publicationCommitted = false;
+  let recoveryObservation: Readonly<{
+    family: 'analysis' | 'plan' | 'code' | 'review-analysis' | 'review-plan' | 'review-code';
+    artifact: string;
+    wasPassed: boolean;
+  }> | null = null;
+  const observeRecoveryPublication = (): void => {
+    if (!recoveryObservation || recoveryObservation.wasPassed) return;
+    const intent = readArtifactRecoveryIntent(
+      manifest.repoRoot,
+      request.taskId,
+      recoveryObservation.family,
+      recoveryObservation.artifact
+    );
+    publicationCommitted ||= intent?.state === 'preflight-ready'
+      || intent?.state === 'preflight-commit-started'
+      || intent?.state === 'preflight-passed'
+      || intent?.state === 'passed'
+      || intent?.state === 'commit-started';
+  };
+  let faultTriggered = false;
+  const fault = (window: TaskWorkflowFaultWindow): void => {
+    if (faultTriggered || options.faultWindow !== window) return;
+    faultTriggered = true;
+    throw new Error(`TASK_WORKFLOW_FAULT_INJECTED:${window}`);
+  };
+  const response = (result: Record<string, unknown>): SandboxControlExecutionResult => {
+    fault('before-result-return');
+    return executionResult(result);
+  };
   try {
+    fault('before-call');
     const taskDir = assertSandboxTaskSource(manifest.repoRoot, request.taskId);
     const [command] = TASK_WORKFLOW_COMMANDS[request.operation];
     if (request.operation === 'event') {
@@ -36,57 +83,101 @@ export async function executeTaskWorkflow(
       const boundEventRequest = lifecycleRecoveryAttestation && eventRequest.requestId === undefined
         ? { ...eventRequest, requestId: lifecycleRecoveryAttestation.lifecycleRequestId }
         : eventRequest;
+      fault('before-domain-write');
       const result = applyTaskEvent(boundEventRequest, {
         repoRoot: manifest.repoRoot,
         lifecycleRecoveryAttestation,
         deferLifecycleRecoveryConsumption: true
       });
-      return executionResult(result);
+      publicationCommitted = result.changed;
+      fault('after-atomic-rename');
+      return response(result);
     }
     if (command !== 'task-artifact' && command !== 'task-review') {
-      publicationStarted = true;
-      // Inherit this executor's process group so its existing recovery owns the worker too.
-      const result = await dispatchHostControlCommand({
-        operation: command, payload: { workingDirectory: manifest.repoRoot, args: request.args }
-      });
-      return result;
+      // The broker owns this short-lived executor; no global service or worker
+      // credential participates in the command's authority or recovery path.
+      fault('before-domain-write');
+      const result = dispatchWorkflowCommand(manifest.repoRoot, request.operation, request.args);
+      publicationCommitted = result.changed === true;
+      fault('after-atomic-rename');
+      return response(result);
     }
     const input = command === 'task-artifact' ? parseArtifactCommand(request.args) : parseReviewCommand(request.args);
     if (command === 'task-artifact' && 'operation' in input && input.operation === 'inspect') {
-      return executionResult(executeArtifactCommand(input, { repoRoot: manifest.repoRoot }));
+      fault('before-domain-write');
+      const result = executeArtifactCommand(input, { repoRoot: manifest.repoRoot });
+      publicationCommitted = result.changed === true;
+      fault('after-atomic-rename');
+      return response(result);
     }
     if ('operation' in input && input.operation === 'init') {
-      return executionResult(executeArtifactCommand(input, { repoRoot: manifest.repoRoot, artifactDir: taskDir }));
+      fault('before-domain-write');
+      const result = executeArtifactCommand(input, { repoRoot: manifest.repoRoot, artifactDir: taskDir });
+      publicationCommitted = result.changed === true;
+      fault('after-atomic-rename');
+      return response(result);
     }
     return await withTaskExecutionLock(manifest.repoRoot, request.taskId, `sandbox-control.${request.operation}`, async () => {
       const artifact = await readTaskArtifact(taskDir, { artifact: input.artifact });
       const content = artifact.bytes.toString('utf8');
+      fault('before-domain-write');
       let result: Record<string, unknown>;
       if ('operation' in input) {
         const { family } = input;
         if (family !== 'analysis' && family !== 'plan' && family !== 'code') throw new Error('ARTIFACT_IDENTITY_INVALID');
         const local = { taskRef: request.taskId, family, artifact: input.artifact, repoRoot: manifest.repoRoot, recoveryId: input.recoveryId, lockAlreadyHeld: true } as const;
+        if (input.operation === 'preflight') {
+          // Preflight only seals a verified generation. It must not publish the
+          // formal artifact, set publicationStarted, or append finalizer audit.
+          const result = preflightLocalArtifact(local);
+          recoveryObservation = { family, artifact: input.artifact, wasPassed: false };
+          observeRecoveryPublication();
+          return response(result);
+        }
+        recoveryObservation = {
+          family,
+          artifact: input.artifact,
+          wasPassed: readArtifactRecoveryIntent(manifest.repoRoot, request.taskId, family, input.artifact)?.state === 'passed'
+        };
         const prepared = prepareLocalArtifact(local, content, lifecycleRecoveryAttestation ?? undefined);
-        if (prepared.result.status === 'failed') return executionResult(commitLocalArtifactProvenance(prepared));
-        publicationStarted = true;
-        result = commitLocalArtifactProvenance(prepared);
+        observeRecoveryPublication();
+        const commitOptions = { afterPublish: () => fault('after-atomic-rename') };
+        if (prepared.result.status === 'failed') return executionResult(commitLocalArtifactProvenance(prepared, commitOptions));
+        result = commitLocalArtifactProvenance(prepared, commitOptions);
       } else {
         if (input.overrideTicket) throw new Error('TASK_WORKFLOW_OVERRIDE_UNSUPPORTED');
+        const family = `review-${input.stage}` as 'review-analysis' | 'review-plan' | 'review-code';
+        if (request.operation === 'review-preflight') {
+          const result = preflightReviewSummary(input, { repoRoot: manifest.repoRoot, lockAlreadyHeld: true });
+          recoveryObservation = { family, artifact: input.artifact, wasPassed: false };
+          observeRecoveryPublication();
+          return response(result);
+        }
+        recoveryObservation = {
+          family,
+          artifact: input.artifact,
+          wasPassed: readArtifactRecoveryIntent(manifest.repoRoot, request.taskId, family, input.artifact)?.state === 'passed'
+        };
         const prepared = prepareReviewSummaryCandidate(input, content, { repoRoot: manifest.repoRoot, lockAlreadyHeld: true, startRecovery: true });
+        observeRecoveryPublication();
         if (input.dryRun || prepared.result.status === 'planned') return executionResult(prepared.result);
-        if (prepared.result.status === 'failed') return executionResult(commitReviewSummaryProvenance(prepared, manifest.repoRoot));
-        publicationStarted = true;
-        result = commitReviewSummaryProvenance(prepared, manifest.repoRoot);
+        const commitOptions = { afterPublish: () => fault('after-atomic-rename') };
+        if (prepared.result.status === 'failed') return executionResult(commitReviewSummaryProvenance(prepared, manifest.repoRoot, commitOptions));
+        result = commitReviewSummaryProvenance(prepared, manifest.repoRoot, commitOptions);
       }
+      observeRecoveryPublication();
+      publicationCommitted ||= result.changed === true;
       if (result.status !== 'failed') appendDiagnosticAudit(manifest, 'task-workflow-artifact-finalized', {
         requestId: request.id, sandboxTaskId: request.taskId, workflowOperation: request.operation,
         artifact: input.artifact, sha256: result.artifactSha256 as string, semanticDigest: result.semanticDigest as string
       });
-      return executionResult({ ...result, changed: true });
+      fault('after-atomic-rename');
+      return response(result);
     });
   } catch (error) {
+    observeRecoveryPublication();
     const message = error instanceof Error ? error.message : String(error);
     const code = (error as { code?: string })?.code ?? /^([A-Z][A-Z0-9_]+)/u.exec(message)?.[1] ?? 'TASK_WORKFLOW_REQUEST_INVALID';
-    return executionResult({ status: 'failed', changed: publicationStarted ? null : false, error: { code, message } });
+    return executionResult({ status: 'failed', changed: publicationCommitted ? null : false, error: { code, message } });
   }
 }

package/lib/server/process-state.ts

@@ -12,6 +12,11 @@ export type ProcessIdentity = Readonly<{
 export type ProcessIdentityState = 'alive' | 'dead' | 'unknown';
 export type ProcessIdentityProbe = (identity: ProcessIdentity) => ProcessIdentityState;
 
+type ProcessIdentityRuntime = Readonly<{
+  probePid?: (pid: number) => void;
+  execFileSync?: typeof execFileSync;
+}>;
+
 export type PidRecord = ProcessIdentity & {
   version: 2;
 };
@@ -132,7 +137,8 @@ export function getProcessStartTime(
 
 export function getProcessIdentityState(
   identity: ProcessIdentity,
-  platform: NodeJS.Platform = process.platform
+  platform: NodeJS.Platform = process.platform,
+  runtime: ProcessIdentityRuntime = {}
 ): ProcessIdentityState {
   if (!Number.isInteger(identity.pid) || identity.pid <= 0 || !Number.isSafeInteger(identity.startTime)) {
     return 'dead';
@@ -147,8 +153,9 @@ export function getProcessIdentityState(
       return (error as NodeJS.ErrnoException).code === 'ENOENT' ? 'dead' : 'unknown';
     }
   }
+  const probePid = runtime.probePid ?? ((pid: number) => process.kill(pid, 0));
   try {
-    process.kill(identity.pid, 0);
+    probePid(identity.pid);
   } catch (error) {
     const code = (error as NodeJS.ErrnoException).code;
     if (code === 'ESRCH') return 'dead';
@@ -157,20 +164,34 @@ export function getProcessIdentityState(
   const query = buildProcessStartTimeQuery(identity.pid, platform);
   if (query === null) return 'unknown';
   try {
-    const output = execFileSync(query.command, query.args, {
+    const output = (runtime.execFileSync ?? execFileSync)(query.command, query.args, {
       encoding: 'utf8',
       env: platform === 'darwin' ? { ...process.env, LC_ALL: 'C', LANG: 'C', TZ: 'UTC' } : process.env
     }).trim();
-    if (output.length === 0) return 'unknown';
+    if (output.length === 0) return recheckDarwinProcessExit(identity.pid, platform, probePid);
     const startTime = platform === 'win32'
       ? new Date(output).getTime()
       : platform === 'darwin'
         ? parseDarwinStartTime(output)
         : null;
-    if (startTime === null || Number.isNaN(startTime)) return 'unknown';
+    if (startTime === null || Number.isNaN(startTime)) return recheckDarwinProcessExit(identity.pid, platform, probePid);
     return startTime === identity.startTime ? 'alive' : 'dead';
   } catch {
+    return recheckDarwinProcessExit(identity.pid, platform, probePid);
+  }
+}
+
+function recheckDarwinProcessExit(
+  pid: number,
+  platform: NodeJS.Platform,
+  probePid: (pid: number) => void
+): ProcessIdentityState {
+  if (platform !== 'darwin') return 'unknown';
+  try {
+    probePid(pid);
     return 'unknown';
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === 'ESRCH' ? 'dead' : 'unknown';
   }
 }
 

package/lib/task/artifact-command.ts

@@ -4,12 +4,12 @@ import { resolveArtifactContext, hasOpenArtifactRound } from './artifact-lifecyc
 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 { finalizeLocalArtifact, preflightLocalArtifact } from './local-artifact-finalization.ts';
 import { initializeArtifactSkeleton } from './artifact-operations.ts';
 
 export type ArtifactCommand = Readonly<{
   taskRef: string;
-  operation: 'inspect' | 'init' | 'finalize-local';
+  operation: 'inspect' | 'init' | 'preflight' | 'finalize-local';
   family: string;
   artifact: string;
   locale?: 'zh-CN' | 'en';
@@ -19,13 +19,14 @@ export type ArtifactCommand = Readonly<{
 /** 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 ?? '')) {
+  if (!taskRef || !['inspect', 'init', 'preflight', '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'],
+    'preflight': ['--family', '--artifact', '--recovery-id'],
     'finalize-local': ['--family', '--artifact', '--recovery-id']
   }[operation as ArtifactCommand['operation']];
   for (let index = 2; index < args.length; index += 1) {
@@ -79,7 +80,8 @@ export function executeArtifactCommand(
     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 fail('ARTIFACT_PAYLOAD_INVALID', "preflight and finalize-local only support 'analysis', 'plan', and 'code'");
   }
+  if (operation === 'preflight') return { ...preflightLocalArtifact({ taskRef, family, artifact, repoRoot: resolved.repoRoot, recoveryId }) };
   return { ...finalizeLocalArtifact({ taskRef, family, artifact, repoRoot: resolved.repoRoot, recoveryId }) };
 }

package/lib/task/artifact-lifecycle.ts

@@ -221,67 +221,30 @@ function resolveReviewedInput(
   expectedFamily: ArtifactFamily,
   diagnostics: ArtifactDiagnostic[]
 ): ArtifactIdentity | null {
-  let content: string;
-  try { content = fs.readFileSync(review.path, 'utf8'); }
-  catch (error) {
-    diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, String(error)));
-    return null;
-  }
-  const parsed = parseReviewedInputReference(content, expectedFamily);
-  if (!parsed) {
-    diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, `${review.name} does not reference a canonical ${expectedFamily} artifact`));
-    return null;
-  }
-  const abs = path.join(taskDir, parsed.name);
   try {
+    const taskContent = fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8');
+    const receipt = receiptForOutput(taskContent, review.name);
+    const expectedEvent = reviewEventName(review.family);
+    if (!receipt || receipt.event !== expectedEvent) throw new Error(`receipt for ${review.name} is missing or invalid`);
+    const input = parseArtifactName(receipt.input);
+    if (!input || input.family !== expectedFamily) throw new Error(`receipt input '${receipt.input}' is not a canonical ${expectedFamily} artifact`);
+    const abs = path.join(taskDir, input.name);
     const stat = fs.lstatSync(abs);
     if (!stat.isFile() || stat.isSymbolicLink()) throw new Error('referenced input is not a regular file');
-    const taskContent = fs.readFileSync(path.join(taskDir, 'task.md'), 'utf8');
     const invalidation = parseInvalidationDocument(taskContent);
     if (!invalidation.ok) throw new Error(invalidation.message);
-    if (isArtifactInvalidated(invalidation.document, expectedFamily, parsed.name)) {
-      throw new Error(`${parsed.name} is invalidated`);
-    }
-    const receipt = receiptForOutput(taskContent, review.name);
-    if (!receipt) throw new Error(`receipt for ${review.name} is missing`);
-    const expectedEvent = reviewEventName(review.family);
-    if (receipt.event !== expectedEvent || receipt.input !== parsed.name) {
-      throw new Error(`receipt for ${review.name} does not match ${parsed.name}`);
-    }
+    if (isArtifactInvalidated(invalidation.document, expectedFamily, input.name)) throw new Error(`${input.name} is invalidated`);
     const actualSha256 = sha256File(abs);
     if (actualSha256 !== receipt.inputSha256) {
-      throw new Error(`${parsed.name} content digest does not match receipt`);
+      throw new Error(`${input.name} content digest does not match receipt`);
     }
-    return { ...parsed, path: abs, size: stat.size, mtimeMs: stat.mtimeMs };
+    return { ...input, path: abs, size: stat.size, mtimeMs: stat.mtimeMs };
   } catch (error) {
-    diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, `${parsed.name}: ${String(error)}`));
+    diagnostics.push(diagnostic('BROKEN_REFERENCE', review.family, review.name, String(error)));
     return null;
   }
 }
 
-function parseReviewedInputReference(content: string, expectedFamily: ArtifactFamily): { family: ArtifactFamily; round: number; name: string } | null {
-  const lines = content.split(/\r?\n/);
-  const header = lines.findIndex((line) => /\*\*(?:审查输入|Review Input)\*\*[:：]/.test(line));
-  const referenceBlock = header >= 0 ? lines.slice(header, header + 12).join('\n') : '';
-  const candidates = [...referenceBlock.matchAll(/`([^`]+\.md)`/g)].map((match) => match[1]!);
-  return candidates
-    .map((name) => parseArtifactName(name))
-    .find((item) => item?.family === expectedFamily) ?? null;
-}
-
-function parseCodePlanInputReference(content: string): { family: 'plan'; round: number; name: string } | null {
-  const lines = content.split(/\r?\n/);
-  const sectionStart = lines.findIndex((line) => /^##\s+(?:实现输入|Implementation Input)\s*$/.test(line.trim()));
-  if (sectionStart < 0) return null;
-  const bodyLines = lines.slice(sectionStart + 1);
-  const nextSection = bodyLines.findIndex((line) => /^##\s+/.test(line.trim()));
-  const body = (nextSection < 0 ? bodyLines : bodyLines.slice(0, nextSection)).join('\n');
-  const match = body.match(/\*\*(?:方案输入|Plan Input)\*\*[:：]\s*`([^`]+\.md)`/);
-  if (!match) return null;
-  const parsed = parseArtifactName(match[1]!);
-  return parsed?.family === 'plan' ? { ...parsed, family: 'plan' } : null;
-}
-
 function reviewEventName(family: ArtifactFamily): 'review-analysis.completed' | 'review-plan.completed' | 'review-code.completed' {
   if (family === 'review-analysis') return 'review-analysis.completed';
   if (family === 'review-plan') return 'review-plan.completed';
@@ -557,7 +520,7 @@ function buildArtifactLinkSection(content: string, artifact: ArtifactIdentity):
 export {
   artifactFamilyCatalog, familySpec,
   inspectTaskArtifacts, inspectArtifactDirectory, resolveArtifactContext,
-  parseReviewedInputReference, parseCodePlanInputReference, resolveCodePlanInput, reviewEventName,
+  resolveCodePlanInput, reviewEventName,
   assertWritableInventory, validateCompletedArtifact, buildArtifactLinkSection
 };
 export type {

package/lib/task/artifact-operations.ts

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { createHash } from 'node:crypto';
-import { readStableFileSync } from '../host-control/secure-fs.ts';
+import { readStableFileSync } from './secure-fs.ts';
 import { parseArtifactName } from './artifact-name.ts';
 
 import { scanVisibleMarkdown, type VisibleMarkdown, type VisibleHeading } from './markdown.ts';
@@ -10,6 +10,12 @@ import {
   renderArtifactSkeleton
 } from './artifact-schema.ts';
 import { withTaskExecutionLock } from './task-execution-lock.ts';
+import {
+  buildQualificationAudit,
+  expectedQualificationRelations,
+  parseTaskQualification,
+  renderQualificationAudit
+} from './qualification-audit.ts';
 import type {
   ArtifactSchema,
   ArtifactSchemaFamily,
@@ -288,6 +294,23 @@ function artifactRound(family: ArtifactSchemaFamily, artifact: string): number |
   return identity?.family === family ? identity.round : null;
 }
 
+function qualificationAuditForInit(request: ArtifactInitRequest): { ok: true; content: string } | { ok: false; code: string; message: string } {
+  let taskContent: string;
+  try {
+    taskContent = readStableFileSync(path.join(request.taskDir, 'task.md'), { maxBytes: 1024 * 1024 }).bytes.toString('utf8');
+  } catch (error) {
+    return { ok: false, code: 'ARTIFACT_INIT_TASK_READ_FAILED', message: error instanceof Error ? error.message : String(error) };
+  }
+  const qualification = parseTaskQualification(taskContent);
+  if (!qualification.ok) return qualification;
+  if (!qualification.qualification.present) return { ok: true, content: '' };
+  const relations = expectedQualificationRelations(taskContent, request.family);
+  if (!relations.ok) return relations;
+  const audit = buildQualificationAudit(taskContent, { upstreamRelations: relations.relations ?? [] });
+  if (!audit.ok) return audit;
+  return { ok: true, content: `\n## 资格审计\n\n${renderQualificationAudit(audit.audit)}\n` };
+}
+
 function initializeArtifactSkeleton(request: ArtifactInitRequest): ArtifactFileResult {
   const schema = getArtifactSchema(request.family);
   if (!schema) return resultFailure('ARTIFACT_FAMILY_UNKNOWN', `unknown artifact family '${request.family}'`);
@@ -304,12 +327,15 @@ function initializeArtifactSkeleton(request: ArtifactInitRequest): ArtifactFileR
       } catch (error) {
         if ((error as NodeJS.ErrnoException).code !== 'ENOENT') return resultFailure('ARTIFACT_INIT_TARGET_INVALID', String(error));
       }
-      const content = renderArtifactSkeleton({
+      const skeleton = renderArtifactSkeleton({
         taskId: request.taskId,
         family: request.family,
         artifact: request.artifact,
         ...(request.locale ? { locale: request.locale } : {})
       });
+      const audit = qualificationAuditForInit(request);
+      if (!audit.ok) return resultFailure(audit.code, audit.message);
+      const content = `${skeleton.trimEnd()}${audit.content}`;
       const tempPath = path.join(request.taskDir, `.${request.artifact}.init-${process.pid}-${Date.now()}.tmp`);
       try {
         fs.writeFileSync(tempPath, content, { encoding: 'utf8', mode: 0o600, flag: 'wx' });