@kontourai/flow-agents 3.5.0 → 3.7.0

package/scripts/hooks/stop-goal-fit.js

@@ -77,7 +77,7 @@ const PRE_EXECUTION_PHASES = new Set(['idea', 'backlog', 'pickup', 'planning']);
 // Terminal tasks are complete — they must never gate a stop or count as "active".
 // A stale current.json pointing at one, or a graveyard of finished states, must
 // not block an unrelated session.
-const TERMINAL_STATUSES = new Set(['done', 'delivered', 'accepted', 'archived', 'complete', 'completed']);
+const TERMINAL_STATUSES = new Set(['done', 'delivered', 'canceled', 'accepted', 'archived', 'complete', 'completed']);
 
 function isTerminalDeliveredState(state) {
   if (!state || typeof state !== 'object') return false;
@@ -1759,6 +1759,37 @@ function hasSidecarPresence(artifactDir) {
   return fs.existsSync(path.join(artifactDir, 'state.json')) || fs.existsSync(path.join(artifactDir, 'trust.bundle'));
 }
 
+function canonicalFlowState(root, artifactDir) {
+  if (!artifactDir) return { state: null, error: null };
+  const slug = path.basename(artifactDir);
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(slug)) return { state: null, error: 'canonical Flow run slug is malformed' };
+  const runDir = path.join(root, '.kontourai', 'flow', 'runs', slug);
+  const components = [
+    path.join(root, '.kontourai'),
+    path.join(root, '.kontourai', 'flow'),
+    path.join(root, '.kontourai', 'flow', 'runs'),
+    runDir,
+  ];
+  try {
+    for (const component of components) {
+      const stat = fs.lstatSync(component);
+      if (stat.isSymbolicLink() || !stat.isDirectory()) return { state: null, error: `canonical Flow run has an unsafe parent component: ${component}` };
+    }
+    const file = path.join(runDir, 'state.json');
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink() || !stat.isFile()) return { state: null, error: 'canonical Flow state must be a non-symlink regular file' };
+    const state = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (!state || typeof state !== 'object' || Array.isArray(state)
+      || typeof state.status !== 'string' || !state.status.trim()
+      || typeof state.current_step !== 'string' || !state.current_step.trim()) {
+      return { state: null, error: 'canonical Flow state is malformed' };
+    }
+    return { state, error: null };
+  } catch (error) {
+    return { state: null, error: `canonical Flow state is unavailable or malformed: ${safeOneLine(error && error.message || error, 120)}` };
+  }
+}
+
 // WS8 (AC10a): when current.json names a slug whose session directory does NOT exist,
 // return that slug so analyze() can log the staleness rather than silently falling back to
 // a global mtime scan that could resurface an abandoned/never-real session as active.
@@ -1871,7 +1902,7 @@ function missingBundleOrStateSignal(artifactDir, activeFlowStep) {
 //
 // Both are used in analyze() for blocking decisions AND in run() for the AC2
 // MAX_BLOCKS hard-block guard (preventing auto-release of hard blocks).
-const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence verdict:|evidence check .+ status:|critique status|critique open|required sidecar is missing|command-log integrity check FAILED|gate misconfiguration:|exit-code-laundered|NOT_VERIFIED \(ambiguous\)/;
+const HARD_BLOCK = /contradicts evidence\.json|caught false-completion|evidence verdict:|evidence check .+ status:|critique status|critique open|required sidecar is missing|command-log integrity check FAILED|gate misconfiguration:|exit-code-laundered|NOT_VERIFIED \(ambiguous\)|canonical Flow (?:run remains active|state is unsafe or malformed)/;
 // FULL_BLOCK adds: workflow-state hygiene, surface-unavailable fail-closed, missing log.
 const FULL_BLOCK = /status:|Definition Of Done|Goal Fit|sidecar validation:|contradicts evidence\.json|workflow state|evidence verdict|evidence check|NOT_VERIFIED gap|critique status|critique open|next action|caught false-completion|NOT_VERIFIED —|command-log integrity check FAILED|gate misconfiguration:|surface unavailable —|expected capture log is missing|exit-code-laundered|malformed-evidence|NOT_VERIFIED \(ambiguous\)/;
 
@@ -1897,7 +1928,31 @@ async function analyze(root, now = Date.now()) {
     artifacts = artifacts.filter(a => a && hasSidecarPresence(path.dirname(a.file)));
   }
 
-  if (artifacts.length === 0) return { warnings: [], blocking: false, latestArtifactDir: null };
+  const scopedCanonicalFlow = canonicalFlowState(root, scoped);
+  const scopedState = scoped ? readJsonFile(path.join(scoped, 'state.json')) : null;
+  const scopedProjectedActive = Boolean(scopedState && scopedState.flow_run && normalizedStatus(scopedState.flow_run.status) === 'active');
+  if (scopedProjectedActive && scopedCanonicalFlow.error) {
+    return {
+      warnings: [`workflow state: canonical Flow state is unsafe or malformed for the active scoped session: ${scopedCanonicalFlow.error}. Resolve the canonical run before stopping.`],
+      blocking: true,
+      activeFlowRun: true,
+      latestArtifactDir: scoped,
+      gatePrefix: '[stop-gate]',
+    };
+  }
+  if (artifacts.length === 0) {
+    if (normalizedStatus(scopedCanonicalFlow.state?.status) === 'active') {
+      const activeStep = safeOneLine(scopedCanonicalFlow.state.current_step || 'unknown', 80);
+      return {
+        warnings: [`workflow state: canonical Flow run remains active at step ${activeStep}; complete or explicitly cancel the run before stopping.`],
+        blocking: true,
+        activeFlowRun: true,
+        latestArtifactDir: scoped,
+        gatePrefix: '[stop-gate]',
+      };
+    }
+    return { warnings: [], blocking: false, activeFlowRun: false, latestArtifactDir: null };
+  }
 
   const latest = artifacts[0];
   const latestArtifactDir = path.dirname(latest.file);
@@ -1965,14 +2020,25 @@ async function analyze(root, now = Date.now()) {
   // Use module-scope HARD_BLOCK / FULL_BLOCK (defined above analyze()).
   // pre-execution/terminal tasks: only HARD_BLOCK signals cause a block.
   // execution-onward tasks: FULL_BLOCK signals cause a block.
-  const activeFlowRun = gateState && gateState.flow_run && normalizedStatus(gateState.flow_run.status) === 'active';
+  const canonicalFlow = canonicalFlowState(root, latestArtifactDir);
+  const activeProjectedFlow = gateState && gateState.flow_run && normalizedStatus(gateState.flow_run.status) === 'active';
+  const unsafeActiveCanonical = Boolean(activeProjectedFlow && canonicalFlow.error);
+  if (unsafeActiveCanonical) {
+    warnings.push(`workflow state: canonical Flow state is unsafe or malformed for the active scoped session: ${canonicalFlow.error}. Resolve the canonical run before stopping.`);
+  }
+  const activeFlowRun = normalizedStatus(canonicalFlow.state?.status) === 'active'
+    || (gateState && gateState.flow_run && normalizedStatus(gateState.flow_run.status) === 'active');
+  if (activeFlowRun && !warnings.some(w => /canonical Flow run remains active/.test(w))) {
+    const activeStep = safeOneLine(canonicalFlow.state?.current_step || gateState?.flow_run?.current_step || 'unknown', 80);
+    warnings.push(`workflow state: canonical Flow run remains active at step ${activeStep}; complete or explicitly cancel the run before stopping.`);
+  }
   const blockRe = ((preExecution && !activeFlowRun) || terminal) ? HARD_BLOCK : FULL_BLOCK;
-  const blocking = warnings.some(w => {
+  const blocking = activeFlowRun || warnings.some(w => {
     // Capture cross-reference warn-mode notes never block (operator opted out).
     if (/\[backstop in warn mode — not blocking\]/.test(w)) return false;
     return blockRe.test(w);
   });
-  return { warnings, blocking, preExecution, gatePrefix: gateLabel(activeFlowStep), latestArtifactDir };
+  return { warnings, blocking, activeFlowRun, preExecution, gatePrefix: gateLabel(activeFlowStep), latestArtifactDir };
 }
 
 /**
@@ -2220,8 +2286,9 @@ function releaseOnNonTerminalStop(root, artifactDir) {
 
     const state = readJsonFile(path.join(artifactDir, 'state.json'));
     if (!state) return; // AC5: no state.json — nothing to gate a release decision on.
-    if (state.flow_run && normalizedStatus(state.flow_run.status) === 'active') {
-      process.stderr.write(`[Hook] Goal Fit: stop-hook release skipped for active Flow run "${safeOneLine(state.flow_run.run_id || state.task_slug || 'unknown', 80)}"; continuation remains governed by Flow state.\n`);
+    const canonicalFlow = canonicalFlowState(root, artifactDir);
+    if (normalizedStatus(canonicalFlow.state?.status) === 'active' || (state.flow_run && normalizedStatus(state.flow_run.status) === 'active')) {
+      process.stderr.write(`[Hook] Goal Fit: stop-hook release skipped for active Flow run "${safeOneLine(state.flow_run?.run_id || state.task_slug || path.basename(artifactDir), 80)}"; continuation remains governed by Flow state.\n`);
       return;
     }
 
@@ -2367,7 +2434,7 @@ async function run(rawInput) {
     // with runtime-constructed paths or by modifying the warning
     // text so the hash changes. The real anchor is external (signed checkpoints + human
     // review). This raises the cost of the burn-through-the-counter escape vector.
-    const isHardBlock = result.warnings.some(w => {
+    const isHardBlock = result.activeFlowRun || result.warnings.some(w => {
       if (/\[backstop in warn mode — not blocking\]/.test(w)) return false;
       return HARD_BLOCK.test(w);
     });
@@ -2375,7 +2442,9 @@ async function run(rawInput) {
       // Do NOT clear the streak — keep accumulating so the same hard block stays visible.
       return {
         stdout: rawInput,
-        stderr: `${message}\n${gatePrefix} max-blocks reached but the block is a caught false-completion / integrity failure — not auto-releasing; requires a real fix or operator override.`,
+        stderr: result.activeFlowRun
+          ? `${message}\n${gatePrefix} max-blocks reached but canonical Flow remains active — not auto-releasing; complete or explicitly cancel the run.`
+          : `${message}\n${gatePrefix} max-blocks reached but the block is a caught false-completion / integrity failure — not auto-releasing; requires a real fix or operator override.`,
         exitCode: 2,
       };
     }

package/src/builder-flow-run-adapter.ts

@@ -1,19 +1,22 @@
 import { createHash } from "node:crypto";
-import { existsSync, mkdirSync, writeFileSync } from "node:fs";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
 import { isDeepStrictEqual } from "node:util";
 import {
   attachEvidence,
+  cancelRun,
   evaluateRun,
   expectationsForGate,
   loadRun,
   normalizeTrustBundle,
   openGates,
-  readJson,
+  pauseRun,
+  resumeRun,
   startRun,
   validateDefinition,
   type FlowEvidenceEntry,
+  type FlowLifecycleRequest,
   type FlowRunState,
   type GateOutcome,
   type JsonObject,
@@ -22,6 +25,9 @@ import { resolveEffectiveFlowDefinition } from "./lib/flow-resolver.js";
 
 export const BUILDER_BUILD_FLOW_ID = "builder.build";
 export const BUILDER_BUILD_FLOW_RELATIVE_PATH = "kits/builder/flows/build.flow.json";
+export const BUILDER_SHAPE_FLOW_ID = "builder.shape";
+export const BUILDER_SHAPE_FLOW_RELATIVE_PATH = "kits/builder/flows/shape.flow.json";
+export type BuilderFlowId = typeof BUILDER_BUILD_FLOW_ID | typeof BUILDER_SHAPE_FLOW_ID;
 
 export interface BuilderBuildTrustBundleEvidenceInput {
   gate: string;
@@ -30,6 +36,8 @@ export interface BuilderBuildTrustBundleEvidenceInput {
    * Callers must not pass raw user-controlled paths to this local runtime API.
    */
   file: string;
+  /** SHA-256 of the immutable snapshot validated by Flow Agents before Flow attaches it. */
+  expectedSha256?: string;
   status?: "passed" | "failed";
   producer?: string;
   authorityTrace?: string;
@@ -52,6 +60,10 @@ export interface StartBuilderBuildRunInput {
   runId?: string;
 }
 
+export interface StartBuilderFlowRunInput extends StartBuilderBuildRunInput {
+  flowId: BuilderFlowId;
+}
+
 export interface EvaluateBuilderBuildRunInput {
   runId: string;
   /**
@@ -67,8 +79,13 @@ export interface LoadBuilderBuildRunInput {
   cwd?: string;
 }
 
-export interface BuilderBuildRunResult {
-  definitionId: typeof BUILDER_BUILD_FLOW_ID;
+export interface ChangeBuilderBuildRunLifecycleInput extends LoadBuilderBuildRunInput {
+  request: FlowLifecycleRequest;
+  at?: string;
+}
+
+export interface BuilderFlowRunResult {
+  definitionId: BuilderFlowId;
   definitionVersion: string;
   runId: string;
   dir: string;
@@ -79,6 +96,10 @@ export interface BuilderBuildRunResult {
   freshnessTransitions: JsonObject[];
 }
 
+export interface BuilderBuildRunResult extends Omit<BuilderFlowRunResult, "definitionId"> {
+  definitionId: typeof BUILDER_BUILD_FLOW_ID;
+}
+
 export type BuilderBuildRunIdentityMismatch = "definition-id" | "definition-version" | "definition-content";
 
 export class BuilderBuildRunInputError extends Error {
@@ -119,20 +140,29 @@ export class BuilderBuildRunIdentityError extends Error {
 }
 
 export function resolveBuilderBuildFlowDefinitionPath(startDir = moduleDirectory()): string {
-  const root = findPackageRoot(startDir);
-  return path.join(root, BUILDER_BUILD_FLOW_RELATIVE_PATH);
+  return resolveBuilderFlowDefinitionPath(BUILDER_BUILD_FLOW_ID, startDir);
 }
 
 export async function startBuilderBuildRun(input: StartBuilderBuildRunInput): Promise<BuilderBuildRunResult> {
+  const result = await startBuilderFlowRun({ ...input, flowId: BUILDER_BUILD_FLOW_ID });
+  return asBuilderBuildResult(result, input.runId ?? result.runId);
+}
+
+export function resolveBuilderFlowDefinitionPath(flowId: BuilderFlowId, startDir = moduleDirectory()): string {
+  const root = findPackageRoot(startDir);
+  return path.join(root, flowRelativePath(flowId));
+}
+
+export async function startBuilderFlowRun(input: StartBuilderFlowRunInput): Promise<BuilderFlowRunResult> {
   assertRuntimeInput(input, ["evidence", "now", "gate"]);
   if (!isNonEmptyString(input.subject)) {
     throw new BuilderBuildRunInputError("subject", "must be a non-empty string");
   }
 
   const cwd = input.cwd ?? process.cwd();
-  const definitionPath = resolveBuilderBuildFlowDefinitionPath();
-  const definition = await loadShippedBuilderBuildDefinition(definitionPath);
-  const runtimeDefinitionPath = materializeRuntimeDefinition(cwd, definition);
+  const definitionPath = resolveBuilderFlowDefinitionPath(input.flowId);
+  const definition = await loadShippedBuilderFlowDefinition(input.flowId, definitionPath);
+  const runtimeDefinitionPath = materializeRuntimeDefinition(cwd, input.flowId, definition);
   const started = await startRun(runtimeDefinitionPath, {
     cwd,
     runId: input.runId,
@@ -141,12 +171,17 @@ export async function startBuilderBuildRun(input: StartBuilderBuildRunInput): Pr
       subject: input.subject,
     },
   });
-  const run = await loadCanonicalBuilderBuildRun(started.runId, cwd, definition);
+  const run = await loadCanonicalBuilderFlowRun(started.runId, cwd, definition);
 
   return resultFromRun(run, started.runId);
 }
 
 export async function evaluateBuilderBuildRun(input: EvaluateBuilderBuildRunInput): Promise<BuilderBuildRunResult> {
+  const result = await evaluateBuilderFlowRun(input);
+  return asBuilderBuildResult(result, input.runId);
+}
+
+export async function evaluateBuilderFlowRun(input: EvaluateBuilderBuildRunInput): Promise<BuilderFlowRunResult> {
   assertRuntimeInput(input, ["now", "gate"]);
   if (Array.isArray(input.evidence)) {
     throw new BuilderBuildRunInputError("evidence", "must be zero or one evidence object, not an array");
@@ -154,16 +189,26 @@ export async function evaluateBuilderBuildRun(input: EvaluateBuilderBuildRunInpu
 
   const cwd = input.cwd ?? process.cwd();
   const run = await loadRun(input.runId, cwd);
-  const definition = await loadShippedBuilderBuildDefinition(resolveBuilderBuildFlowDefinitionPath());
+  const definition = await loadShippedBuilderFlowDefinitionForRun(input.runId, run.definition);
   assertCanonicalDefinition(input.runId, definition, run.definition);
 
   let attachedEvidence: FlowEvidenceEntry[] = [];
   if (input.evidence !== undefined) {
     const evidence = validateEvidenceInput(input.evidence);
     assertCurrentOpenGate(run.definition, run.state, evidence.gate);
-    const normalized = normalizeTrustBundle(await readJson(path.resolve(cwd, evidence.file)));
+    const source = path.resolve(cwd, evidence.file);
+    const bytes = readFileSync(source);
+    const validatedSha256 = createHash("sha256").update(bytes).digest("hex");
+    if (evidence.expectedSha256 && evidence.expectedSha256 !== validatedSha256) {
+      throw new BuilderBuildRunInputError("evidence.expectedSha256", "does not match the bytes presented for validation");
+    }
+    const normalized = normalizeTrustBundle(JSON.parse(bytes.toString("utf8")));
     assertBundleSubjects(normalized.bundle, run.state.subject, openGates(run.definition, run.state)[0]);
-    attachedEvidence = [await attachEvidence(input.runId, trustBundleAttachOptions(cwd, evidence))];
+    const attached = await attachEvidence(input.runId, trustBundleAttachOptions(cwd, evidence, validatedSha256));
+    if (attached.sha256 !== validatedSha256) {
+      throw new BuilderBuildRunInputError("evidence.file", "changed after validation before Flow attachment");
+    }
+    attachedEvidence = [attached];
   }
 
   const evaluated = await evaluateRun(input.runId, { cwd });
@@ -181,15 +226,73 @@ export async function evaluateBuilderBuildRun(input: EvaluateBuilderBuildRunInpu
 }
 
 export async function loadBuilderBuildRun(input: LoadBuilderBuildRunInput): Promise<BuilderBuildRunResult> {
+  const result = await loadBuilderFlowRun(input);
+  return asBuilderBuildResult(result, input.runId);
+}
+
+export async function loadBuilderFlowRun(input: LoadBuilderBuildRunInput): Promise<BuilderFlowRunResult> {
   assertRuntimeInput(input, ["evidence", "now", "gate"]);
   const cwd = input.cwd ?? process.cwd();
   const run = await loadRun(input.runId, cwd);
-  const definition = await loadShippedBuilderBuildDefinition(resolveBuilderBuildFlowDefinitionPath());
+  const definition = await loadShippedBuilderFlowDefinitionForRun(input.runId, run.definition);
   assertCanonicalDefinition(input.runId, definition, run.definition);
   return resultFromRun(run, input.runId);
 }
 
-function resultFromRun(run: Awaited<ReturnType<typeof loadRun>>, runId: string): BuilderBuildRunResult {
+export async function pauseBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult> {
+  const result = await pauseBuilderFlowRun(input);
+  return asBuilderBuildResult(result, input.runId);
+}
+
+export async function resumeBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult> {
+  const result = await resumeBuilderFlowRun(input);
+  return asBuilderBuildResult(result, input.runId);
+}
+
+export async function cancelBuilderBuildRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderBuildRunResult & { idempotent: boolean }> {
+  const changed = await changeBuilderFlowRunLifecycleResult(input, cancelRun);
+  return { ...asBuilderBuildResult(resultFromRun(changed, input.runId), input.runId), idempotent: changed.idempotent };
+}
+
+export async function pauseBuilderFlowRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderFlowRunResult> {
+  return changeBuilderFlowRunLifecycle(input, pauseRun);
+}
+
+export async function resumeBuilderFlowRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderFlowRunResult> {
+  return changeBuilderFlowRunLifecycle(input, resumeRun);
+}
+
+export async function cancelBuilderFlowRun(input: ChangeBuilderBuildRunLifecycleInput): Promise<BuilderFlowRunResult & { idempotent: boolean }> {
+  const changed = await changeBuilderFlowRunLifecycleResult(input, cancelRun);
+  return { ...resultFromRun(changed, input.runId), idempotent: changed.idempotent };
+}
+
+async function changeBuilderFlowRunLifecycle(
+  input: ChangeBuilderBuildRunLifecycleInput,
+  operation: typeof pauseRun | typeof resumeRun,
+): Promise<BuilderFlowRunResult> {
+  const changed = await changeBuilderFlowRunLifecycleResult(input, operation);
+  return resultFromRun(changed, input.runId);
+}
+
+async function changeBuilderFlowRunLifecycleResult(
+  input: ChangeBuilderBuildRunLifecycleInput,
+  operation: typeof pauseRun | typeof resumeRun | typeof cancelRun,
+) {
+  assertRuntimeInput(input, []);
+  if (!isRecord(input.request)) throw new BuilderBuildRunInputError("request", "must be a lifecycle request object");
+  const cwd = input.cwd ?? process.cwd();
+  const before = await loadBuilderFlowRun({ runId: input.runId, cwd });
+  const changed = await operation(input.runId, { cwd, ...input.request, ...(input.at ? { at: input.at } : {}) });
+  const definition = await loadShippedBuilderFlowDefinitionForRun(input.runId, changed.definition);
+  assertCanonicalDefinition(input.runId, definition, changed.definition);
+  if (changed.state.subject !== before.state.subject) {
+    throw new BuilderBuildRunInputError("flow_run.state.subject", "changed during lifecycle transition");
+  }
+  return changed;
+}
+
+function resultFromRun(run: Awaited<ReturnType<typeof loadRun>>, runId: string): BuilderFlowRunResult {
   return {
     definitionId: run.definition.id,
     definitionVersion: run.definition.version,
@@ -203,7 +306,7 @@ function resultFromRun(run: Awaited<ReturnType<typeof loadRun>>, runId: string):
   };
 }
 
-async function loadCanonicalBuilderBuildRun(
+async function loadCanonicalBuilderFlowRun(
   runId: string,
   cwd: string,
   definition: { id: string; version: string },
@@ -213,29 +316,55 @@ async function loadCanonicalBuilderBuildRun(
   return run;
 }
 
-async function loadShippedBuilderBuildDefinition(definitionPath: string): Promise<{ id: string; version: string }> {
+async function loadShippedBuilderFlowDefinition(flowId: BuilderFlowId, definitionPath: string): Promise<{ id: string; version: string }> {
   const packageRoot = findPackageRoot(path.dirname(definitionPath));
-  const effective = resolveEffectiveFlowDefinition(BUILDER_BUILD_FLOW_ID, packageRoot, { allowOverride: false });
+  const effective = resolveEffectiveFlowDefinition(flowId, packageRoot, { allowOverride: false });
   if (!effective) {
     throw new BuilderBuildRunInputError("definition", "could not compile the shipped uses_flow composition");
   }
   const definition = validateDefinition(effective);
-  if (definition.id !== BUILDER_BUILD_FLOW_ID) {
-    throw new BuilderBuildRunInputError("definition", `expected shipped definition id ${BUILDER_BUILD_FLOW_ID}`);
+  if (definition.id !== flowId) {
+    throw new BuilderBuildRunInputError("definition", `expected shipped definition id ${flowId}`);
   }
   return definition;
 }
 
-function materializeRuntimeDefinition(cwd: string, definition: unknown): string {
+async function loadShippedBuilderFlowDefinitionForRun(runId: string, actualDefinition: { id: string; version: string }): Promise<{ id: string; version: string }> {
+  const flowId = actualDefinition.id;
+  if (!isBuilderFlowId(flowId)) {
+    throw new BuilderBuildRunIdentityError(runId, { id: BUILDER_BUILD_FLOW_ID, version: "unknown" }, actualDefinition, "definition-id");
+  }
+  return loadShippedBuilderFlowDefinition(flowId, resolveBuilderFlowDefinitionPath(flowId));
+}
+
+function materializeRuntimeDefinition(cwd: string, flowId: BuilderFlowId, definition: unknown): string {
   const content = `${JSON.stringify(definition, null, 2)}\n`;
   const digest = createHash("sha256").update(content).digest("hex").slice(0, 16);
   const directory = path.join(cwd, ".kontourai", "flow-agents", "runtime-definitions");
   mkdirSync(directory, { recursive: true });
-  const file = path.join(directory, `builder-build-${digest}.flow.json`);
+  const file = path.join(directory, `${flowId.replace(".", "-")}-${digest}.flow.json`);
   if (!existsSync(file)) writeFileSync(file, content);
   return file;
 }
 
+function flowRelativePath(flowId: BuilderFlowId): string {
+  return flowId === BUILDER_BUILD_FLOW_ID ? BUILDER_BUILD_FLOW_RELATIVE_PATH : BUILDER_SHAPE_FLOW_RELATIVE_PATH;
+}
+
+function isBuilderFlowId(value: string): value is BuilderFlowId {
+  return value === BUILDER_BUILD_FLOW_ID || value === BUILDER_SHAPE_FLOW_ID;
+}
+
+function assertExpectedFlow(runId: string, actual: BuilderFlowId, expected: BuilderFlowId): void {
+  if (actual === expected) return;
+  throw new BuilderBuildRunIdentityError(runId, { id: expected, version: "unknown" }, { id: actual, version: "unknown" }, "definition-id");
+}
+
+function asBuilderBuildResult(result: BuilderFlowRunResult, runId: string): BuilderBuildRunResult {
+  assertExpectedFlow(runId, result.definitionId, BUILDER_BUILD_FLOW_ID);
+  return result as BuilderBuildRunResult;
+}
+
 function assertCanonicalDefinition(
   runId: string,
   expectedDefinition: { id: string; version: string },
@@ -272,6 +401,9 @@ function validateEvidenceInput(evidence: unknown): BuilderBuildTrustBundleEviden
   if (!isNonEmptyString(evidence.file)) {
     throw new BuilderBuildRunInputError("evidence.file", "must be a non-empty string");
   }
+  if (evidence.expectedSha256 !== undefined && (!isNonEmptyString(evidence.expectedSha256) || !/^[a-f0-9]{64}$/i.test(evidence.expectedSha256))) {
+    throw new BuilderBuildRunInputError("evidence.expectedSha256", "must be a SHA-256 hex digest");
+  }
   if (evidence.status !== undefined && evidence.status !== "passed" && evidence.status !== "failed") {
     throw new BuilderBuildRunInputError("evidence.status", "must be passed or failed");
   }
@@ -311,11 +443,12 @@ function assertBundleSubjects(bundle: unknown, subject: string, gate: unknown):
   }
 }
 
-function trustBundleAttachOptions(cwd: string, evidence: BuilderBuildTrustBundleEvidenceInput): JsonObject {
+function trustBundleAttachOptions(cwd: string, evidence: BuilderBuildTrustBundleEvidenceInput, expectedSha256: string): JsonObject {
   return {
     cwd,
     gate: evidence.gate,
     file: evidence.file,
+    expectedSha256,
     kind: "trust.bundle",
     bundle: true,
     ...(evidence.status ? { status: evidence.status } : {}),