swallowkit 1.0.1 → 1.0.2

package/src/core/operations/file-session.ts

@@ -43,6 +43,13 @@ export interface RecordedFileOperation {
   newHash: string | null;
 }
 
+export interface SchemaAnalysisSnapshot {
+  parserMode: string;
+  semanticFingerprint: string;
+  canonicalModel: unknown;
+  warnings: string[];
+}
+
 export function normalizeContentForHash(content: string): string {
   return content.replace(/\r\n/g, "\n");
 }
@@ -78,6 +85,7 @@ export class FileOperationSession {
   private readonly inputFingerprintsByPath = new Map<string, string | null>();
   /** overlay: absolute normalized path -> content (null = deleted in session) */
   private readonly overlay = new Map<string, string | null>();
+  private schemaAnalysisValue: SchemaAnalysisSnapshot | null = null;
 
   constructor(mode: FileSessionMode, rootDirectory: string = process.cwd()) {
     this.mode = mode;
@@ -94,6 +102,14 @@ export class FileOperationSession {
     );
   }
 
+  get schemaAnalysis(): SchemaAnalysisSnapshot | null {
+    return this.schemaAnalysisValue;
+  }
+
+  setSchemaAnalysis(analysis: SchemaAnalysisSnapshot): void {
+    this.schemaAnalysisValue = analysis;
+  }
+
   addWarning(message: string): void {
     if (!this.warnings.includes(message)) {
       this.warnings.push(message);

package/src/core/operations/scaffold-apply.ts

@@ -75,6 +75,23 @@ export async function applyScaffoldOperation(options: ApplyScaffoldOptions): Pro
   // 常に最新状態で collect し、競合を検出する(plan 指定時も現況を再確認)
   const currentPlan = await planScaffoldOperation(effectiveOptions);
 
+  if (basePlan &&
+      (!basePlan.schemaAnalysis ||
+       basePlan.schemaAnalysis.parserMode !== currentPlan.schemaAnalysis.parserMode ||
+       basePlan.schemaAnalysis.semanticFingerprint !== currentPlan.schemaAnalysis.semanticFingerprint)) {
+    throw new MachineCommandError(
+      "schema-analysis-mismatch",
+      `Plan "${basePlan.planId}" used different schema analysis metadata; no artifacts were written.`,
+      {
+        planId: basePlan.planId,
+        expected: basePlan.schemaAnalysis,
+        actual: currentPlan.schemaAnalysis,
+        nextAction: "Re-run plan scaffold in the same environment, then apply the new plan.",
+      },
+      "blocked"
+    );
+  }
+
   if (currentPlan.requiresApproval && !options.approve) {
     // 承認待ちの plan は残し、参照できるようにする
     throw new MachineCommandError(
@@ -88,7 +105,10 @@ export async function applyScaffoldOperation(options: ApplyScaffoldOptions): Pro
     );
   }
 
-  const result = await runMachineScaffoldOperation(effectiveOptions);
+  const result = await runMachineScaffoldOperation({
+    ...effectiveOptions,
+    expectedSchemaAnalysis: currentPlan.schemaAnalysis,
+  });
 
   // 適用済み plan の状態を破棄
   deletePlanState(currentPlan.planId, projectRoot);

package/src/core/operations/scaffold-machine.ts

@@ -1,4 +1,5 @@
 import { scaffoldCommand } from "../../cli/commands/scaffold";
+import { SchemaAnalysisSnapshot } from "./file-session";
 import {
   captureConsoleMessagesWithError,
   deriveCapturedErrorMessage,
@@ -12,6 +13,7 @@ export interface MachineScaffoldOperationOptions {
   functionsDir?: string;
   apiDir?: string;
   apiOnly?: boolean;
+  expectedSchemaAnalysis?: SchemaAnalysisSnapshot;
 }
 
 export interface MachineScaffoldOperationResult {

package/src/core/operations/scaffold-plan.ts

@@ -12,6 +12,7 @@ import { savePlanState } from "../project/state";
 import {
   ArtifactOwnership,
   FileOperationSession,
+  SchemaAnalysisSnapshot,
   hashFileIfExists,
   runWithFileSession,
 } from "./file-session";
@@ -52,6 +53,8 @@ export interface ScaffoldPlanData {
   swallowkitVersion: string;
   operations: ScaffoldPlanOperation[];
   warnings: string[];
+  diagnostics: string[];
+  schemaAnalysis: SchemaAnalysisSnapshot;
   conflicts: ScaffoldPlanOperation[];
   requiresApproval: boolean;
   /** project-relative path -> pre-plan content hash (null = did not exist). Used for stale-plan detection. */
@@ -112,6 +115,10 @@ export async function planScaffoldOperation(options: PlanScaffoldOptions): Promi
   const operations: ScaffoldPlanOperation[] = [];
   const fingerprints: Record<string, string | null> = { ...session.inputFingerprints };
   const warnings = [...session.warnings];
+  const schemaAnalysis = session.schemaAnalysis;
+  if (!schemaAnalysis) {
+    throw new Error("Scaffold completed without recording schema analysis metadata.");
+  }
 
   for (const op of session.operations) {
     fingerprints[op.path] = op.previousHash;
@@ -173,6 +180,7 @@ export async function planScaffoldOperation(options: PlanScaffoldOptions): Promi
         options: { functionsDir: options.functionsDir, apiDir: options.apiDir, apiOnly: options.apiOnly },
         operations: operations.map((op) => ({ path: op.path, action: op.action })),
         fingerprints,
+        schemaAnalysis,
       })
     )
     .digest("hex")
@@ -191,6 +199,8 @@ export async function planScaffoldOperation(options: PlanScaffoldOptions): Promi
     swallowkitVersion: getSwallowKitVersion(),
     operations,
     warnings,
+    diagnostics: schemaAnalysis.warnings.map((warning) => `warning:${warning}`),
+    schemaAnalysis,
     conflicts,
     requiresApproval: conflicts.length > 0,
     fingerprints,

package/src/core/project/drift.ts

@@ -12,6 +12,7 @@
 import * as path from "path";
 import { getSwallowKitVersion } from "../../version";
 import { hashFileIfExists } from "../operations/file-session";
+import { parseModelFile } from "../scaffold/model-parser";
 import { ArtifactRecord, loadArtifactLedger } from "./artifacts";
 import { buildProjectManifest, readProjectManifest, SWALLOWKIT_MANIFEST_PATH } from "./manifest";
 
@@ -84,11 +85,11 @@ function detectArtifactDrift(
   }
 }
 
-function detectSchemaDrift(
+async function detectSchemaDrift(
   records: ArtifactRecord[],
   projectRoot: string,
   findings: DriftFinding[]
-): void {
+): Promise<void> {
   const byModel = new Map<string, ArtifactRecord[]>();
 
   for (const record of records) {
@@ -110,7 +111,10 @@ function detectSchemaDrift(
     if (currentSchemaHash === null) {
       continue; // モデルファイルが見つからない場合は manifest-drift 側で検出される
     }
-    const staleRecords = modelRecords.filter((record) => record.schemaHash !== currentSchemaHash);
+    const semanticSchemaHash = (await parseModelFile(modelPath)).semanticFingerprint;
+    const staleRecords = modelRecords.filter(
+      (record) => record.schemaHash !== semanticSchemaHash && record.schemaHash !== currentSchemaHash
+    );
     if (staleRecords.length > 0) {
       const staleSchemaHashes = [...new Set(staleRecords.map((record) => record.schemaHash!))].sort();
       findings.push({
@@ -120,7 +124,7 @@ function detectSchemaDrift(
         path: `shared/models/${kebab}.ts`,
         entity: modelName,
         expected: staleSchemaHashes.join(", "),
-        actual: currentSchemaHash,
+        actual: semanticSchemaHash,
         repairAction: `Run "swallowkit machine plan scaffold ${kebab}" then apply to regenerate artifacts for ${modelName}.`,
       });
     }
@@ -182,7 +186,7 @@ export async function detectDrift(projectRoot: string = process.cwd()): Promise<
     for (const record of ledger.artifacts) {
       detectArtifactDrift(record, projectRoot, findings);
     }
-    detectSchemaDrift(ledger.artifacts, projectRoot, findings);
+    await detectSchemaDrift(ledger.artifacts, projectRoot, findings);
     detectGeneratorDrift(ledger.artifacts, findings);
   } else {
     findings.push({

package/src/core/scaffold/model-parser.ts

@@ -8,6 +8,14 @@ import * as path from "path";
 import * as ts from "typescript";
 
 import { ModelConnectorConfig, ModelAuthPolicy } from "../../types";
+import { MachineCommandError } from "../../machine/errors";
+import { hashContent } from "../operations/file-session";
+
+export type SchemaParserMode = "static-ast" | "dynamic";
+
+export interface ModelParserOptions {
+  executeNode?: typeof execFileSync;
+}
 
 export interface ModelInfo {
   name: string; // モデル名（例: "Todo"）
@@ -22,6 +30,9 @@ export interface ModelInfo {
   connectorConfig?: ModelConnectorConfig; // コネクタメタデータ（外部データソース用）
   authPolicy?: ModelAuthPolicy; // 認可ポリシー（ロールベースアクセス制御用）
   partitionKey: string; // Cosmos DB パーティションキーパス（デフォルト: "/id"）
+  parserMode: SchemaParserMode;
+  parserWarnings: string[];
+  semanticFingerprint: string;
 }
 
 export interface FieldInfo {
@@ -55,7 +66,7 @@ export interface NestedSchemaRef {
 /**
  * モデルファイルを解析して ModelInfo を返す
  */
-export async function parseModelFile(modelPath: string): Promise<ModelInfo> {
+export async function parseModelFile(modelPath: string, options: ModelParserOptions = {}): Promise<ModelInfo> {
   if (!fs.existsSync(modelPath)) {
     throw new Error(`Model file not found: ${modelPath}`);
   }
@@ -100,7 +111,8 @@ export async function parseModelFile(modelPath: string): Promise<ModelInfo> {
   const nestedSchemaRefs = detectNestedSchemaRefs(modelPath, content, schemaName);
   
   // フィールド情報を抽出（動的インポートを使用）
-  const fields = await extractFieldsFromSchema(modelPath, schemaName);
+  const parsedSchema = await extractFieldsFromSchema(modelPath, schemaName, options.executeNode ?? execFileSync);
+  const fields = parsedSchema.fields;
   
   // ネストスキーマ情報をフィールドにマージ
   mergeNestedSchemaInfo(fields, nestedSchemaRefs);
@@ -121,7 +133,7 @@ export async function parseModelFile(modelPath: string): Promise<ModelInfo> {
     }
   }
   
-  return {
+  const modelInfo: ModelInfo = {
     name: modelName,
     displayName,
     schemaName,
@@ -134,7 +146,25 @@ export async function parseModelFile(modelPath: string): Promise<ModelInfo> {
     partitionKey,
     ...(connectorConfig ? { connectorConfig } : {}),
     ...(authPolicy ? { authPolicy } : {}),
+    parserMode: parsedSchema.mode,
+    parserWarnings: parsedSchema.warnings,
+    semanticFingerprint: "",
   };
+  modelInfo.semanticFingerprint = createModelSemanticFingerprint(modelInfo);
+  return modelInfo;
+}
+
+export function createModelSemanticFingerprint(model: Omit<ModelInfo, "semanticFingerprint" | "filePath">): string {
+  return hashContent(JSON.stringify({
+    name: model.name,
+    displayName: model.displayName,
+    schemaName: model.schemaName,
+    fields: model.fields,
+    nestedSchemaRefs: model.nestedSchemaRefs,
+    partitionKey: model.partitionKey,
+    connectorConfig: model.connectorConfig,
+    authPolicy: model.authPolicy,
+  }));
 }
 
 /**
@@ -360,7 +390,128 @@ function compileModelModule(modelPath: string, directory: string, modules = new
 /**
  * Zodスキーマから動的にフィールド情報を抽出
  */
-async function extractFieldsFromSchema(modelPath: string, schemaName: string): Promise<FieldInfo[]> {
+interface ParsedSchemaFields {
+  fields: FieldInfo[];
+  mode: SchemaParserMode;
+  warnings: string[];
+}
+
+function staticParseFields(modelPath: string, schemaName: string): FieldInfo[] | null {
+  const source = ts.createSourceFile(modelPath, fs.readFileSync(modelPath, "utf-8"), ts.ScriptTarget.Latest, true);
+  const constants = new Map<string, ts.Expression>();
+  const importedObjectSchemas = new Set<string>();
+  for (const statement of source.statements) {
+    if (ts.isImportDeclaration(statement) && ts.isStringLiteral(statement.moduleSpecifier) &&
+        statement.moduleSpecifier.text.startsWith(".") && statement.importClause?.namedBindings &&
+        ts.isNamedImports(statement.importClause.namedBindings)) {
+      const base = path.resolve(path.dirname(modelPath), statement.moduleSpecifier.text);
+      const targetPath = [base, `${base}.ts`, path.join(base, "index.ts")].find(candidate => fs.existsSync(candidate));
+      if (targetPath) {
+        const targetContent = fs.readFileSync(targetPath, "utf-8");
+        for (const element of statement.importClause.namedBindings.elements) {
+          const importedName = element.propertyName?.text ?? element.name.text;
+          if (new RegExp(`(?:export\\s+)?const\\s+${importedName}\\s*=\\s*z\\.object\\s*\\(`).test(targetContent)) {
+            importedObjectSchemas.add(element.name.text);
+          }
+        }
+      }
+    }
+    if (!ts.isVariableStatement(statement)) continue;
+    for (const declaration of statement.declarationList.declarations) {
+      if (ts.isIdentifier(declaration.name) && declaration.initializer) constants.set(declaration.name.text, declaration.initializer);
+    }
+  }
+
+  const schema = constants.get(schemaName);
+  if (!schema || !ts.isCallExpression(schema) || !ts.isPropertyAccessExpression(schema.expression) ||
+      schema.expression.name.text !== "object" || schema.arguments.length === 0 || !ts.isObjectLiteralExpression(schema.arguments[0])) {
+    return null;
+  }
+
+  const literalValues = (expression: ts.Expression): string[] | null => {
+    let value = expression;
+    if (ts.isAsExpression(value)) value = value.expression;
+    if (ts.isIdentifier(value)) {
+      const resolved = constants.get(value.text);
+      return resolved ? literalValues(resolved) : null;
+    }
+    if (!ts.isArrayLiteralExpression(value)) return null;
+    const values: string[] = [];
+    for (const element of value.elements) {
+      if (ts.isStringLiteral(element) || ts.isNumericLiteral(element)) values.push(element.text);
+      else return null;
+    }
+    return values;
+  };
+
+  const parseExpression = (expression: ts.Expression): Omit<FieldInfo, "name"> | null => {
+    if (ts.isIdentifier(expression)) {
+      const resolved = constants.get(expression.text);
+      if (resolved) return parseExpression(resolved);
+      return importedObjectSchemas.has(expression.text)
+        ? { type: "object", isOptional: false, isNullable: false, isArray: false }
+        : null;
+    }
+    if (!ts.isCallExpression(expression) || !ts.isPropertyAccessExpression(expression.expression)) return null;
+    const method = expression.expression.name.text;
+    const receiver = expression.expression.expression;
+    const wrappers = new Set(["optional", "nullable", "default", "min", "max", "int", "positive", "negative", "nonnegative", "nonpositive", "regex", "email", "url", "uuid", "trim"]);
+    if (wrappers.has(method)) {
+      const inner = parseExpression(receiver);
+      if (!inner) return null;
+      if (method === "optional" || method === "default") inner.isOptional = true;
+      if (method === "nullable") inner.isNullable = true;
+      return inner;
+    }
+    if (!ts.isIdentifier(receiver) || receiver.text !== "z") return null;
+    if (["string", "number", "boolean", "date"].includes(method)) {
+      return { type: method, isOptional: false, isNullable: false, isArray: false };
+    }
+    if (method === "object") return { type: "object", isOptional: false, isNullable: false, isArray: false };
+    if (method === "array" && expression.arguments[0]) {
+      const element = parseExpression(expression.arguments[0]);
+      return element ? { ...element, isArray: true } : null;
+    }
+    if (method === "enum" && expression.arguments[0]) {
+      const enumValues = literalValues(expression.arguments[0]);
+      return enumValues ? { type: "string", isOptional: false, isNullable: false, isArray: false, enumValues } : null;
+    }
+    if (method === "literal" && expression.arguments[0]) {
+      const value = expression.arguments[0];
+      if (ts.isStringLiteral(value) || ts.isNumericLiteral(value)) {
+        return { type: ts.isNumericLiteral(value) ? "number" : "string", isOptional: false, isNullable: false, isArray: false, enumValues: [value.text] };
+      }
+      if (value.kind === ts.SyntaxKind.TrueKeyword || value.kind === ts.SyntaxKind.FalseKeyword) {
+        return { type: "boolean", isOptional: false, isNullable: false, isArray: false, enumValues: [value.kind === ts.SyntaxKind.TrueKeyword ? "true" : "false"] };
+      }
+    }
+    return null;
+  };
+
+  const fields: FieldInfo[] = [];
+  for (const property of schema.arguments[0].properties) {
+    if (!ts.isPropertyAssignment(property)) return null;
+    const name = ts.isIdentifier(property.name) || ts.isStringLiteral(property.name) ? property.name.text : null;
+    if (!name) return null;
+    const parsed = parseExpression(property.initializer);
+    if (!parsed) return null;
+    const isForeignKey = name.endsWith("Id") && name.length > 2 && parsed.type === "string";
+    fields.push({
+      name,
+      ...parsed,
+      ...(isForeignKey ? { isForeignKey: true, referencedModel: name.slice(0, -2).replace(/^./, char => char.toUpperCase()) } : {}),
+    });
+  }
+  return fields;
+}
+
+async function extractFieldsFromSchema(
+  modelPath: string,
+  schemaName: string,
+  executeNode: typeof execFileSync
+): Promise<ParsedSchemaFields> {
+  const staticFields = staticParseFields(modelPath, schemaName);
+  if (staticFields) return { fields: staticFields, mode: "static-ast", warnings: [] };
   const fields: FieldInfo[] = [];
   let tempDirectory: string | undefined;
   
@@ -389,7 +540,7 @@ if (isObject) {
   const shape = typeof schema._def.shape === 'function' ? schema._def.shape() : schema._def.shape;
   const fields = Object.keys(shape).map(key => {
     const field = shape[key];
-    let type = 'string';
+    let type = undefined;
     let isOptional = false;
     let isNullable = false;
     let isArray = false;
@@ -457,6 +608,19 @@ if (isObject) {
           ? fieldDef._def.entries
           : Object.values(fieldDef._def.entries);
       }
+    } else if (typeName === 'ZodLiteral') {
+      const rawLiteralValues = fieldDef.values || fieldDef._def.values ||
+        (fieldDef._def.value !== undefined ? [fieldDef._def.value] : undefined);
+      const literalValues = rawLiteralValues instanceof Set ? Array.from(rawLiteralValues) : rawLiteralValues;
+      if (Array.isArray(literalValues) && literalValues.length > 0) {
+        const literalValue = literalValues[0];
+        type = typeof literalValue === 'number' ? 'number' : typeof literalValue === 'boolean' ? 'boolean' : 'string';
+        enumValues = literalValues.map(value => String(value));
+      }
+    }
+
+    if (!type || ((typeName === 'ZodEnum' || typeName === 'ZodNativeEnum') && (!enumValues || enumValues.length === 0))) {
+      throw new Error('Unsupported or ambiguous Zod field "' + key + '" (' + (typeName || 'unknown') + ')');
     }
     
     // 外部キー検出: フィールド名が <ModelName>Id のパターンの場合
@@ -473,13 +637,15 @@ if (isObject) {
   });
   
   console.log(JSON.stringify(fields));
+} else {
+  throw new Error('Exported schema is not a Zod object');
 }
 `;
     
     fs.writeFileSync(tempScript, scriptCode, 'utf8');
     
     try {
-      const result = execFileSync(process.execPath, [tempScript], {
+      const result = executeNode(process.execPath, [tempScript], {
         encoding: 'utf8',
         cwd: projectRoot,
       });
@@ -499,71 +665,37 @@ if (isObject) {
       }
     }
   } catch (error) {
-    console.warn('Failed to use dynamic import, falling back to regex parsing');
-    console.warn('Error:', error);
-    return extractFieldsWithRegex(modelPath, schemaName);
+    const nodeError = error as NodeJS.ErrnoException;
+    if (nodeError.code === "EPERM" || nodeError.code === "EACCES" || nodeError.code === "ENOENT") {
+      throw new MachineCommandError(
+        "schema-evaluation-unavailable",
+        `Schema evaluation could not start: ${nodeError.message}`,
+        {
+          command: process.execPath,
+          reason: nodeError.code,
+          modelPath,
+          diagnostics: ["Dynamic schema evaluation requires permission to start a Node.js child process."],
+          nextAction: "Re-run in an environment that permits normal Node.js child process execution.",
+        },
+        "blocked"
+      );
+    }
+    throw new MachineCommandError(
+      "schema-analysis-unsupported",
+      `The model could not be analyzed safely without losing schema semantics: ${error instanceof Error ? error.message : String(error)}`,
+      {
+        command: process.execPath,
+        modelPath,
+        diagnostics: ["Lossy regex parsing was not used."],
+        nextAction: "Use supported static Zod expressions or re-run where dynamic schema evaluation succeeds.",
+      },
+      "blocked"
+    );
   } finally {
     if (tempDirectory) fs.rmSync(tempDirectory, { recursive: true, force: true });
   }
   
-  return fields;
-}
-
-/**
- * 正規表現でフィールド情報を抽出（フォールバック用）
- */
-function extractFieldsWithRegex(modelPath: string, schemaName: string): FieldInfo[] {
-  const fields: FieldInfo[] = [];
-  const content = fs.readFileSync(modelPath, "utf-8");
-  
-  // z.object({ ... }) の内容を抽出（ネストした括弧に対応）
-  const objectContent = extractObjectContent(content, schemaName);
-  
-  if (!objectContent) {
-    return fields;
-  }
-  
-  // 各フィールドを解析
-  const fieldRegex = /(\w+)\s*:\s*(z\.\w+)/g;
-  let match;
-  
-  while ((match = fieldRegex.exec(objectContent)) !== null) {
-    const fieldName = match[1];
-    const zodDef = match[2];
-    const zodType = zodDef.split('.')[1];
-    
-    const fieldStart = match.index;
-    const fieldEnd = objectContent.indexOf(',', fieldStart);
-    const fieldDef = fieldEnd > -1 
-      ? objectContent.substring(fieldStart, fieldEnd) 
-      : objectContent.substring(fieldStart);
-    
-    fields.push({
-      name: fieldName,
-      type: mapZodTypeToTs(zodType),
-      isOptional: fieldDef.includes(".optional()"),
-      isNullable: fieldDef.includes(".nullable()"),
-      isArray: fieldDef.includes(".array()"),
-    });
-  }
-  
-  return fields;
-}
-
-/**
- * Zod 型を TypeScript 型にマッピング
- */
-function mapZodTypeToTs(zodType: string): string {
-  const typeMap: Record<string, string> = {
-    string: "string",
-    number: "number",
-    boolean: "boolean",
-    date: "Date",
-    object: "object",
-    array: "array",
-  };
-  
-  return typeMap[zodType] || "any";
+  return { fields, mode: "dynamic", warnings: [] };
 }
 
 /**

package/src/core/verify/index.ts

@@ -31,6 +31,8 @@ export interface VerifyCheckEvidence {
   logTail?: string[];
   /** --compact で抑制された info-severity findings の件数。 */
   suppressedInfoFindings?: number;
+  errorCode?: "verification-command-unavailable";
+  diagnostics?: string[];
 }
 
 export interface VerifyCheckResult {
@@ -158,8 +160,13 @@ function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyChe
         status: "error",
         durationMs: Date.now() - startedAt,
         fixable: false,
-        evidence: { command: commandLabel, logTail: [result.error.message] },
-        suggestedActions: [`Ensure "${commandLabel}" can run in this project.`],
+        evidence: {
+          command: commandLabel,
+          logTail: [result.error.message],
+          errorCode: "verification-command-unavailable",
+          diagnostics: [`Unable to start the verification command: ${result.error.message}`],
+        },
+        suggestedActions: [`Re-run "${commandLabel}" in an environment that permits child process execution.`],
       };
     }
 
@@ -183,8 +190,13 @@ function runCommandCheck(projectRoot: string, spec: CommandCheckSpec): VerifyChe
       status: "error",
       durationMs: Date.now() - startedAt,
       fixable: false,
-      evidence: { command: commandLabel, logTail: [error instanceof Error ? error.message : String(error)] },
-      suggestedActions: [],
+      evidence: {
+        command: commandLabel,
+        logTail: [error instanceof Error ? error.message : String(error)],
+        errorCode: "verification-command-unavailable",
+        diagnostics: ["The verification command could not be started in this environment."],
+      },
+      suggestedActions: [`Re-run "${commandLabel}" in an environment that permits child process execution.`],
     };
   }
 }
@@ -225,10 +237,17 @@ function runTypecheckCheck(projectRoot: string): VerifyCheckResult {
       status: "fail",
       durationMs: Date.now() - startedAt,
       fixable: true,
-      evidence: { command: sharedBuild.command, logTail: sharedBuild.logTail },
-      suggestedActions: [
-        "Fix the shared package build errors first; typecheck resolves the shared package from its built dist/.",
-      ],
+      evidence: {
+        command: sharedBuild.command,
+        logTail: sharedBuild.logTail,
+        ...(sharedBuild.unavailable ? {
+          errorCode: "verification-command-unavailable" as const,
+          diagnostics: ["The shared package build command could not be started in this environment."],
+        } : {}),
+      },
+      suggestedActions: sharedBuild.unavailable
+        ? ["Re-run verification in an environment that permits child process execution."]
+        : ["Fix the shared package build errors first; typecheck resolves the shared package from its built dist/."],
     };
   }
 
@@ -264,6 +283,7 @@ interface SharedBuildOutcome {
   ok: boolean;
   command?: string;
   logTail?: string[];
+  unavailable?: boolean;
 }
 
 /** shared/package.json に build script があれば実行する (なければ no-op)。 */
@@ -292,6 +312,7 @@ function runSharedBuildIfPresent(projectRoot: string): SharedBuildOutcome {
     ok,
     command: `${command} run build (in shared/)`,
     logTail: ok ? undefined : tailLines(result.error ? `${output}\n${result.error.message}` : output, 50),
+    unavailable: Boolean(result.error),
   };
 }
 

package/src/machine/index.ts

@@ -548,13 +548,27 @@ function createMachineProgram(): Command {
         "verify-project",
         async () => {
           const result = await runVerify(options.checks ? options.checks.split(",") : undefined);
+          const unavailable = result.checks.find(
+            (check) => check.evidence.errorCode === "verification-command-unavailable"
+          );
+          if (unavailable) {
+            throw new MachineCommandError(
+              "verification-command-unavailable",
+              `Verification could not start "${unavailable.evidence.command ?? unavailable.id}" in this environment.`,
+              {
+                check: unavailable.id,
+                command: unavailable.evidence.command,
+                diagnostics: unavailable.evidence.diagnostics ?? unavailable.evidence.logTail,
+                nextAction: "Re-run verification in an environment that permits normal child process execution.",
+              },
+              "blocked"
+            );
+          }
           return options.compact ? compactVerifyResult(result) : result;
         },
         (result) => ({
-          status: result.summary.done ? "complete" : "in-progress",
-          nextActions: result.summary.done
-            ? []
-            : [
+          status: result.summary.done ? "complete" : "failed",
+          nextActions: result.summary.done ? [] : [
                 {
                   command: "swallowkit machine explain failure",
                   description: "Get evidence and suggested actions for the failed checks.",