@fitlab-ai/agent-infra 0.9.13 → 0.9.14

package/lib/sandbox/engines/docker-exact-discovery.ts

@@ -0,0 +1,132 @@
+import type { SpawnSyncReturns } from 'node:child_process';
+import { commandForEngine, runProbe } from '../shell.ts';
+import { commandForSandboxAuthority, type SandboxAuthorityEvidenceV1 } from './authority.ts';
+
+type ProbeResult = SpawnSyncReturns<string | Buffer>;
+type Probe = (cmd: string, args: string[], options?: { timeout?: number }) => ProbeResult;
+
+export type ExactContainerDiscovery =
+  | Readonly<{ state: 'absent'; id: string; evidence: 'exact-empty' }>
+  | Readonly<{
+    state: 'found';
+    id: string;
+    running: boolean;
+    labels: Readonly<Record<string, string>>;
+    evidence: 'exact-present';
+  }>
+  | Readonly<{ state: 'conflict'; reason: string }>
+  | Readonly<{ state: 'unknown'; reason: string }>;
+
+export type ExactContainerDiscoveryOptions = Readonly<{
+  probe?: Probe;
+  timeoutMs?: number;
+  authority?: SandboxAuthorityEvidenceV1;
+}>;
+
+const FULL_CONTAINER_ID = /^[a-f0-9]{64}$/u;
+
+function outputText(value: string | Buffer | null | undefined): string {
+  return typeof value === 'string' ? value : value?.toString('utf8') ?? '';
+}
+
+function unknown(reason: string): ExactContainerDiscovery {
+  return { state: 'unknown', reason };
+}
+
+export function buildExactContainerListArgs(id: string): string[] {
+  if (!FULL_CONTAINER_ID.test(id)) throw new Error('SANDBOX_CONTAINER_ID_NOT_FULL');
+  return ['container', 'ls', '--all', '--no-trunc', '--filter', `id=${id}`, '--format', '{{.ID}}'];
+}
+
+function buildExactContainerInspectArgs(id: string): string[] {
+  return ['container', 'inspect', '--format', '{{json .}}', id];
+}
+
+function runDockerProbe(
+  engine: string,
+  args: string[],
+  options: ExactContainerDiscoveryOptions
+): ProbeResult {
+  const command = options.authority
+    ? commandForSandboxAuthority(options.authority, 'docker', args)
+    : commandForEngine(engine, 'docker', args);
+  return (options.probe ?? runProbe)(
+    command.cmd,
+    command.args,
+    options.timeoutMs === undefined ? {} : { timeout: options.timeoutMs }
+  );
+}
+
+function parseExactList(stdout: string, expectedId: string): 'empty' | 'present' | 'conflict' | string {
+  const rows = stdout.split(/\r?\n/u).map((row) => row.trim()).filter(Boolean);
+  if (rows.length === 0) return 'empty';
+  if (rows.length !== 1) return 'exact container query returned multiple rows';
+  if (!FULL_CONTAINER_ID.test(rows[0]!)) return 'exact container query returned a malformed ID';
+  if (rows[0] !== expectedId) return 'conflict';
+  return 'present';
+}
+
+function parseExactInspect(stdout: string, expectedId: string): ExactContainerDiscovery {
+  let value: unknown;
+  try {
+    value = JSON.parse(stdout);
+  } catch {
+    return unknown('exact container inspection returned malformed JSON');
+  }
+  if (!value || typeof value !== 'object' || Array.isArray(value)) {
+    return unknown('exact container inspection returned an incomplete object');
+  }
+  const inspected = value as {
+    Id?: unknown;
+    State?: { Running?: unknown };
+    Config?: { Labels?: unknown };
+  };
+  if (inspected.Id !== expectedId || typeof inspected.State?.Running !== 'boolean'
+    || !inspected.Config?.Labels || typeof inspected.Config.Labels !== 'object'
+    || Array.isArray(inspected.Config.Labels)) {
+    return unknown('exact container inspection identity is incomplete');
+  }
+  const rawLabels = inspected.Config.Labels as Record<string, unknown>;
+  if (Object.values(rawLabels).some((value) => typeof value !== 'string')) {
+    return unknown('exact container inspection labels are malformed');
+  }
+  return {
+    state: 'found',
+    id: expectedId,
+    running: inspected.State.Running,
+    labels: { ...rawLabels as Record<string, string> },
+    evidence: 'exact-present'
+  };
+}
+
+export function discoverExactContainer(
+  engine: string,
+  id: string,
+  options: ExactContainerDiscoveryOptions = {}
+): ExactContainerDiscovery {
+  if (!FULL_CONTAINER_ID.test(id)) return unknown('container identity is not a full 64-character ID');
+  let listed: ProbeResult;
+  try {
+    listed = runDockerProbe(engine, buildExactContainerListArgs(id), options);
+  } catch {
+    return unknown('exact container query failed before producing a result');
+  }
+  if (listed.status !== 0) {
+    return unknown(`exact container query exited with ${listed.status ?? 'unknown status'}`);
+  }
+  const listState = parseExactList(outputText(listed.stdout), id);
+  if (listState === 'empty') return { state: 'absent', id, evidence: 'exact-empty' };
+  if (listState === 'conflict') return { state: 'conflict', reason: 'exact container query returned a different ID' };
+  if (listState !== 'present') return unknown(listState);
+
+  let inspected: ProbeResult;
+  try {
+    inspected = runDockerProbe(engine, buildExactContainerInspectArgs(id), options);
+  } catch {
+    return unknown('exact container inspection failed before producing a result');
+  }
+  if (inspected.status !== 0) {
+    return unknown(`exact container inspection exited with ${inspected.status ?? 'unknown status'}`);
+  }
+  return parseExactInspect(outputText(inspected.stdout).trim(), id);
+}

package/lib/sandbox/index.ts

@@ -1,3 +1,5 @@
+import { PUBLIC_CLI_ROUTE_SELECTORS } from '../internal/cli-route-inventory.ts';
+
 const USAGE = `Usage: ai sandbox <command> [options]
 
 Commands:
@@ -26,6 +28,7 @@ Commands:
   vm status|start|stop         Manage the sandbox VM (macOS) or check the backend (Windows)
 
 Run 'ai sandbox <command> --help' for details.`;
+const SANDBOX_OPERATIONS = PUBLIC_CLI_ROUTE_SELECTORS.sandbox;
 
 export async function runSandbox(args: string[]): Promise<void> {
   const [subcommand, ...rest] = args;
@@ -41,6 +44,10 @@ export async function runSandbox(args: string[]): Promise<void> {
     return;
   }
 
+  if (!SANDBOX_OPERATIONS.includes(subcommand as typeof SANDBOX_OPERATIONS[number])) {
+    throw new Error(`Unknown sandbox command: ${subcommand}`);
+  }
+
   switch (subcommand) {
     case 'create': {
       const { create } = await import('./commands/create.ts');

package/lib/sandbox/recovery.ts

@@ -1,3 +1,4 @@
+import { prepareCompletedReentry, publishCompletedReentry, waitForCompletedReentry } from './control/completed-reentry.ts';
 import fs from 'node:fs';
 import path from 'node:path';
 import { spawn } from 'node:child_process';
@@ -653,7 +654,7 @@ function recoveryTaskSources(repoRoot: string, taskId: string): {
   return { mountPaths, accessiblePaths: [completedSource] };
 }
 
-function startCompletedSandboxContainer(params: {
+export function startCompletedSandboxContainer(params: {
   config: SandboxConfig;
   engine: string;
   container: string;
@@ -1250,7 +1251,17 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
       throw new Error('Explicit container recreation requested.');
     }
     if (!params.row.running) {
+      let completedReentry: { manifest: SandboxControlManifest; evidence: Awaited<ReturnType<typeof prepareCompletedReentry>> } | null = null;
       if (params.reentry === 'completed' && params.workspace?.mode === 'task-bound') {
+        const control = sandboxControlPaths({
+          base: params.config.controlBase, project: params.config.project,
+          container: params.row.name, identity: params.workspace
+        });
+        const manifest = readSandboxControlManifest(control.manifestPath);
+        if (manifest.taskId !== params.workspace.taskId || manifest.branch !== params.branch) {
+          throw new Error('SANDBOX_COMPLETED_REENTRY_EVIDENCE_INVALID');
+        }
+        completedReentry = { manifest, evidence: await prepareCompletedReentry(manifest) };
         startCompletedSandboxContainer({
           config: params.config,
           engine: params.engine,
@@ -1315,6 +1326,15 @@ export async function ensureSandboxReady(params: EnsureSandboxReadyParams): Prom
       if (final.findings.length > 0) {
         throw new Error(describeFindings(final.findings));
       }
+      if (completedReentry) {
+        const { manifest, evidence } = completedReentry;
+        const current = await prepareCompletedReentry(manifest);
+        if (JSON.stringify(current) !== JSON.stringify(evidence)) {
+          throw new Error('SANDBOX_COMPLETED_REENTRY_EVIDENCE_INVALID');
+        }
+        publishCompletedReentry(manifest, evidence);
+        await waitForCompletedReentry(manifest, evidence);
+      }
       return { container: params.row.name, path: 'recovered', warnings };
     }
 

package/lib/sandbox/workspace-view.ts

@@ -57,7 +57,7 @@ export type SandboxControlSetup = Readonly<{
   generation: string;
 }>;
 
-export type SandboxControlManifestDraft = Readonly<Omit<SandboxControlManifest, 'containerIdentity' | 'engine'> & {
+export type SandboxControlManifestDraft = Readonly<Omit<SandboxControlManifest, 'containerIdentity' | 'engine' | 'authorityEvidence'> & {
   engine: string;
 }>;
 
@@ -256,13 +256,19 @@ export function materializeSandboxControl(params: Readonly<{
 
 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/artifact-lifecycle.ts

@@ -10,21 +10,11 @@ import { extractSection, findSectionHeading } from './sections.ts';
 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';
 
-const artifactFamilyCatalog = [
-  { 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;
-
-type ArtifactFamily = (typeof artifactFamilyCatalog)[number]['family'];
-type ArtifactFamilySpec = (typeof artifactFamilyCatalog)[number];
+const artifactFamilyCatalog = ARTIFACT_FAMILY_CATALOG;
 type ArtifactIdentity = {
   family: ArtifactFamily;
   round: number;
@@ -340,6 +330,7 @@ const OPTIONAL_CONTEXT: Partial<Record<ArtifactFamily, { family: ArtifactFamily;
   'manual-validation': { family: 'review-code' },
   'validation-run': { family: 'review-code' }
 };
+const QUALIFICATION_RECOVERY_OPTIONAL_CONTEXT_CONSUMERS = new Set<ArtifactFamily>(['analysis', 'plan']);
 
 function resolveArtifactContext(taskRef: string, family: string, options: InspectOptions = {}): ArtifactContextResult {
   const inventory = inspectTaskArtifacts(taskRef, family, options);
@@ -354,6 +345,8 @@ function resolveArtifactContext(taskRef: string, family: string, options: Inspec
     if (input.status === 'failed' || !input.latest) {
       return { ...inventory, status: 'failed', inputs, codeMode: null, error: { code: 'ARTIFACT_INPUT_MISSING', message: `latest ${required} artifact is required` } };
     }
+    const qualificationError = qualificationErrorForArtifact(input.latest);
+    if (qualificationError) return { ...inventory, status: 'failed', inputs, codeMode: null, error: { code: 'ARTIFACT_REFERENCE_INVALID', message: qualificationError } };
     inputs.push(input.latest);
   }
   const optional = OPTIONAL_CONTEXT[inventory.family as ArtifactFamily];
@@ -363,12 +356,27 @@ function resolveArtifactContext(taskRef: string, family: string, options: Inspec
       if (optional.requireReference && !context.reviewedInput) {
         return { ...inventory, status: 'failed', inputs, codeMode: null, error: { code: 'ARTIFACT_REFERENCE_INVALID', message: `${context.latest.name} has no valid reviewed input` } };
       }
+      const qualificationError = qualificationErrorForArtifact(context.latest);
+      if (qualificationError && !QUALIFICATION_RECOVERY_OPTIONAL_CONTEXT_CONSUMERS.has(inventory.family as ArtifactFamily)) {
+        return { ...inventory, status: 'failed', inputs, codeMode: null, error: { code: 'ARTIFACT_REFERENCE_INVALID', message: qualificationError } };
+      }
       inputs.push(context.latest);
     }
   }
   return { ...inventory, inputs, codeMode: null };
 }
 
+function qualificationErrorForArtifact(artifact: ArtifactIdentity): string | null {
+  try {
+    const taskContent = fs.readFileSync(path.join(path.dirname(artifact.path), 'task.md'), 'utf8');
+    const artifactContent = fs.readFileSync(artifact.path, 'utf8');
+    const result = validateQualificationAudit(taskContent, artifactContent);
+    return result.ok ? null : `${result.code}: ${result.message}`;
+  } catch (error) {
+    return error instanceof Error ? error.message : String(error);
+  }
+}
+
 function resolveCodeContext(inventory: ArtifactInventoryResult, options: InspectOptions): ArtifactContextResult {
   const taskRef = inventory.requestRef;
   const plan = inspectTaskArtifacts(taskRef, 'plan', options);
@@ -379,6 +387,16 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
   const codeMax = latestCode?.round ?? 0;
   const reviewMax = reviewCode.latest?.round ?? 0;
   const inputs = [plan.latest];
+  const planQualificationError = qualificationErrorForArtifact(plan.latest);
+  if (planQualificationError) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', planQualificationError);
+  if (latestCode) {
+    const qualificationError = qualificationErrorForArtifact(latestCode);
+    if (qualificationError) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', qualificationError, latestCode.name);
+  }
+  if (reviewCode.latest) {
+    const qualificationError = qualificationErrorForArtifact(reviewCode.latest);
+    if (qualificationError) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', qualificationError, reviewCode.latest.name);
+  }
   if (!latestCode) {
     if (!reviewPlan.latest || reviewPlan.reviewedInput?.name !== plan.latest.name) {
       return contextFailure(inventory, 'ARTIFACT_INPUT_MISSING', `latest plan '${plan.latest.name}' requires a matching approved review-plan`);
@@ -398,6 +416,10 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
   if (reviewPlan.latest && !reviewPlan.reviewedInput) {
     return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', `${reviewPlan.latest.name} has no valid reviewed input`, reviewPlan.latest.name);
   }
+  if (reviewPlan.latest) {
+    const qualificationError = qualificationErrorForArtifact(reviewPlan.latest);
+    if (qualificationError) return contextFailure(inventory, 'ARTIFACT_REFERENCE_INVALID', qualificationError, reviewPlan.latest.name);
+  }
   if (reviewPlan.latest && reviewPlan.reviewedInput?.name === plan.latest.name) {
     const verdict = parseVerdict(reviewPlan.latest.path);
     if (!verdict.ok) return contextFailure(inventory, 'ARTIFACT_VERDICT_INVALID', `${verdict.code}: ${verdict.message}`, reviewPlan.latest.name);
@@ -409,8 +431,8 @@ function resolveCodeContext(inventory: ArtifactInventoryResult, options: Inspect
         `Latest ${reviewPlan.latest.name} approves plan content not captured by the latest code input receipt. Entering replan-driven init.`);
     }
   }
-  if (reviewMax < codeMax) {
-    const expected = artifactName('review-code', codeMax);
+  if (!reviewCode.latest || reviewCode.reviewedInput?.name !== latestCode.name) {
+    const expected = reviewCode.next?.name ?? artifactName('review-code', reviewMax + 1);
     return contextFailure(inventory, 'ARTIFACT_INPUT_MISSING', `${expected} is required before another code round`, expected);
   }
   const review = reviewCode.latest;