@kontourai/flow-agents 3.3.0 → 3.4.1

package/src/lib/console-connect-options.ts

@@ -0,0 +1,261 @@
+/**
+ * Pure, side-effect-free decision logic for the guided "Connect to Kontour
+ * Console?" wizard (install-flow-console-connect PR2). Mirrors the doc-comment
+ * convention of `console-telemetry-validate.ts` (this literally is "the future
+ * guided console-connect wizard (PR2/PR3)" that file's own docstring names).
+ *
+ * No `fs`/`child_process`/network imports here — every export is a pure
+ * function or a thin orchestration over injected `ask`/`askHidden` callbacks,
+ * so `interactiveOptions()` in `src/cli/init.ts` stays a thin caller and this
+ * module is fully unit-testable without a TTY.
+ *
+ * `TelemetrySink` is re-declared as a local type alias (not imported from
+ * `init.ts`) to avoid a lib -> cli import direction. Keep this union in sync
+ * with `src/cli/init.ts`'s `TelemetrySink` by comment cross-reference:
+ *   "local-files" | "local-kontour-console" | "kontour-hosted-console" |
+ *   "user-hosted-console" | "kontour-cloud" | "hosted-kontour-console"
+ */
+import { isValidConsoleUrl, isValidConsoleToken, isValidConsoleTenant } from "./console-telemetry-validate.js";
+
+export type TelemetrySink =
+  | "local-files"
+  | "local-kontour-console"
+  | "kontour-hosted-console"
+  | "user-hosted-console"
+  | "kontour-cloud"
+  | "hosted-kontour-console";
+
+export type ConsoleConnectChoice = "hosted" | "local" | "self-hosted" | "skip";
+
+/**
+ * Case-insensitive match on the four accepted choice spellings. Blank or
+ * unrecognized input falls back to `fallback` (the caller decides the
+ * default, typically "hosted").
+ */
+export function normalizeConsoleConnectChoice(answer: string, fallback: ConsoleConnectChoice): ConsoleConnectChoice {
+  const normalized = answer.trim().toLowerCase();
+  if (!normalized) return fallback;
+  if (normalized === "hosted" || normalized === "h") return "hosted";
+  if (normalized === "local" || normalized === "l") return "local";
+  if (normalized === "self-hosted" || normalized === "selfhosted" || normalized === "self" || normalized === "s") return "self-hosted";
+  if (normalized === "skip" || normalized === "none" || normalized === "n") return "skip";
+  return fallback;
+}
+
+/** Pure lookup table: choice -> the exact `telemetrySinks` array to install with. */
+export function mapConsoleConnectChoiceToSinks(choice: ConsoleConnectChoice): TelemetrySink[] {
+  if (choice === "hosted") return ["kontour-hosted-console"];
+  if (choice === "local") return ["local-kontour-console"];
+  if (choice === "self-hosted") return ["user-hosted-console"];
+  return ["local-files"];
+}
+
+/** Only "self-hosted" requires an inline URL prompt. */
+export function needsConsoleUrlPrompt(choice: ConsoleConnectChoice): boolean {
+  return choice === "self-hosted";
+}
+
+/**
+ * Mirrors `needsConsoleCredentials`'s existing semantics one-for-one
+ * (choice-based instead of sinks-based): every choice except "skip" wants
+ * token/tenant prompts.
+ */
+export function needsConsoleCredentialPrompts(choice: ConsoleConnectChoice): boolean {
+  return choice !== "skip";
+}
+
+/**
+ * The one hard-fail guard this PR adds: self-hosted Console with a blank URL
+ * is a downstream `die` in `install-console-config.sh` (the `user-hosted-console`
+ * branch requires `--console-url`/`--console-endpoint`). Falls back to
+ * `local-files` with a one-line warning instead of letting that crash happen.
+ *
+ * Only handles the blank case — a non-blank-but-malformed URL (e.g. a typo)
+ * is NOT this guard's job; callers separately run `isValidConsoleUrl` for
+ * that format-only warn-and-continue case.
+ */
+export function resolveSelfHostedUrlOrFallback(url: string): { sinks: TelemetrySink[]; url: string; fallbackWarning?: string } {
+  if (url.trim() === "") {
+    return {
+      sinks: ["local-files"],
+      url: "",
+      fallbackWarning: "Self-hosted Console requires a URL; no URL was given, so telemetry stays local-only. Re-run init or telemetry-doctor to add a Console URL later.",
+    };
+  }
+  return { sinks: ["user-hosted-console"], url };
+}
+
+export type ConsoleConnectIo = {
+  ask: (prompt: string) => Promise<string>;
+  askHidden: (prompt: string) => Promise<string>;
+};
+
+export type ConsoleConnectDefaults = {
+  hostedUrl: string;
+  localUrl: string;
+};
+
+export type ConsoleConnectResult = {
+  telemetrySinks: TelemetrySink[];
+  consoleUrl?: string;
+  consoleTokenValue?: string;
+  consoleTenant?: string;
+  warnings: string[];
+};
+
+// Token provisioning is console-side (CONSOLE_AUTH_TOKENS_JSON), not
+// flow-agents-side. This hint is folded into the token prompt string itself
+// (rather than printed directly via console.log) so the whole orchestration
+// stays testable via the injected `askHidden` stub's captured prompt argument.
+const TOKEN_PROVISIONING_HINT =
+  "Tokens are provisioned by your Console admin via CONSOLE_AUTH_TOKENS_JSON -- see docs/integrations/flow-agents-console.md.";
+
+/**
+ * Full interactive orchestration used by `interactiveOptions()`: prompts the
+ * four-way "Connect to Kontour Console?" choice (default Hosted, showing the
+ * real `console-presets.sh`-resolved hosted URL), applies the self-hosted
+ * blank-URL guard, prompts hidden token + tenant when a console connection is
+ * wanted, runs PR1's pure validators (validate-and-warn, not
+ * validate-and-block), and returns any format warnings in `warnings` for the
+ * caller to print -- rather than printing directly, so this stays testable
+ * via return-value assertions, not console-spy assertions.
+ */
+export async function runConsoleConnectWizard(
+  io: ConsoleConnectIo,
+  defaults: ConsoleConnectDefaults,
+): Promise<ConsoleConnectResult> {
+  const warnings: string[] = [];
+
+  const choiceAnswer = await io.ask(
+    `Connect to Kontour Console? [Hosted (${defaults.hostedUrl})/Local (${defaults.localUrl})/Self-hosted/Skip] [Hosted]: `,
+  );
+  const choice = normalizeConsoleConnectChoice(choiceAnswer, "hosted");
+
+  let sinks = mapConsoleConnectChoiceToSinks(choice);
+  let consoleUrl: string | undefined;
+
+  if (needsConsoleUrlPrompt(choice)) {
+    const urlAnswer = await io.ask("Self-hosted Console URL: ");
+    const resolved = resolveSelfHostedUrlOrFallback(urlAnswer);
+    sinks = resolved.sinks;
+    consoleUrl = resolved.url ? resolved.url : undefined;
+    if (resolved.fallbackWarning) {
+      warnings.push(resolved.fallbackWarning);
+    } else if (consoleUrl && !isValidConsoleUrl(consoleUrl)) {
+      warnings.push(
+        `Console URL '${consoleUrl}' does not look valid (expected https://, or http:// to localhost/127.0.0.1); continuing anyway.`,
+      );
+    }
+  }
+
+  let consoleTokenValue: string | undefined;
+  let consoleTenant: string | undefined;
+  // Only prompt for credentials when a console sink actually survived (the
+  // self-hosted blank-URL fallback above may have already downgraded to
+  // local-files, in which case there is nothing to authenticate).
+  const wantsConsole = needsConsoleCredentialPrompts(choice) && sinks.some((sink) => sink !== "local-files");
+  if (wantsConsole) {
+    const tokenAnswer = await io.askHidden(`${TOKEN_PROVISIONING_HINT}\nConsole telemetry token (blank to skip): `);
+    consoleTokenValue = tokenAnswer.trim() || undefined;
+    if (consoleTokenValue && !isValidConsoleToken(consoleTokenValue)) {
+      warnings.push(
+        "Console token format looks unusual (expected <=4096 chars, charset [A-Za-z0-9._~+/=-]); continuing anyway.",
+      );
+    }
+    const tenantAnswer = await io.ask("Console tenant ID (blank to skip): ");
+    consoleTenant = tenantAnswer.trim() || undefined;
+    if (consoleTenant && !isValidConsoleTenant(consoleTenant)) {
+      warnings.push(
+        "Console tenant format looks unusual (expected charset [A-Za-z0-9._:-]); continuing anyway.",
+      );
+    }
+  }
+
+  return { telemetrySinks: sinks, consoleUrl, consoleTokenValue, consoleTenant, warnings };
+}
+
+export type ConsoleStatus = "connected-verified" | "connected-unverified" | "local-only";
+
+type DoctorConsoleShape = {
+  sink: "local-only" | "console";
+  reachability: { checked: boolean; ok: boolean | null; error?: string; statusCode?: number };
+};
+
+/**
+ * Pure classifier over the exact structural shape `telemetry-doctor.ts`'s
+ * `DoctorReport.console` already has. Deliberately accepts a narrow
+ * structural type rather than importing `DoctorReport` itself, keeping this
+ * module dependency-free (no lib -> cli import).
+ */
+// Actionable detail shown when a Console sink's reachability was never
+// attempted (checked:false). In practice this branch is reached ONLY via
+// telemetry-doctor.ts's pre-attempt guard clauses (endpointAllowed() said no,
+// or the endpoint URL was malformed) -- an actually-attempted check that
+// fails always sets checked:true (see checkConsoleReachability's HEAD
+// request path) and is handled by the branch above, which keeps surfacing
+// error/statusCode unchanged. The most common guard-clause reason by far is
+// a self-hosted/BYO HTTPS host that --allow-network was not passed for, so
+// the hint below points at the one flag that unblocks it.
+const NOT_CHECKED_DETAIL =
+  "not checked — self-hosted/BYO consoles need `flow-agents telemetry-doctor --allow-network` to verify reachability";
+
+export function describeConsoleStatus(doctor: { console: DoctorConsoleShape }): { status: ConsoleStatus; detail?: string } {
+  const { sink, reachability } = doctor.console;
+  if (sink === "local-only") return { status: "local-only" };
+  if (reachability.checked && reachability.ok === true) return { status: "connected-verified" };
+  if (reachability.checked && reachability.ok === false) {
+    const detail = reachability.error ?? (reachability.statusCode !== undefined ? `HTTP ${reachability.statusCode}` : "reachability check failed");
+    return { status: "connected-unverified", detail };
+  }
+  // reachability.checked === false: never attempted (see NOT_CHECKED_DETAIL's
+  // doc comment for why this is always the not-allowed/skipped reason here,
+  // never an attempted-and-failed check).
+  return { status: "connected-unverified", detail: NOT_CHECKED_DETAIL };
+}
+
+export type PostInstallSummaryInput = {
+  runtime: string;
+  runtimeAutoDetected: boolean;
+  dest: string;
+  telemetrySinks: string[];
+  consoleStatus: { status: ConsoleStatus; detail?: string };
+  tokenConfigured: boolean;
+  tenantConfigured: boolean;
+  nextSteps: string[];
+};
+
+function consoleStatusLine(consoleStatus: { status: ConsoleStatus; detail?: string }): string {
+  if (consoleStatus.status === "connected-verified") return "✓ Console: connected + verified";
+  if (consoleStatus.status === "connected-unverified") {
+    return `✗ Console: connected, unverified${consoleStatus.detail ? `: ${consoleStatus.detail}` : ""}`;
+  }
+  return "- Console: local-only";
+}
+
+/**
+ * Pure string[]-builder for the post-install summary block: one array entry
+ * per line, so callers `console.log` each entry and tests assert on array
+ * contents rather than scraping stdout. Never receives or emits the raw
+ * console token value -- only the `tokenConfigured`/`tenantConfigured`
+ * booleans are shown.
+ */
+export function buildPostInstallSummaryLines(input: PostInstallSummaryInput): string[] {
+  const lines: string[] = [];
+  lines.push("");
+  lines.push("Flow Agents install summary:");
+  const runtimeLine = input.runtimeAutoDetected ? `${input.runtime} (auto-detected)` : input.runtime;
+  lines.push(`  ✓ Runtime: ${runtimeLine}`);
+  lines.push(`  ✓ Destination: ${input.dest}`);
+  lines.push(`  ✓ Telemetry sink: ${input.telemetrySinks.length ? input.telemetrySinks.join(", ") : "local-files"}`);
+  lines.push(`  ${consoleStatusLine(input.consoleStatus)}`);
+  if (input.consoleStatus.status !== "local-only") {
+    lines.push(`    Console token: ${input.tokenConfigured ? "configured" : "not configured"}`);
+    lines.push(`    Console tenant: ${input.tenantConfigured ? "configured" : "not configured"}`);
+  }
+  if (input.nextSteps.length) {
+    lines.push("");
+    lines.push("Next steps:");
+    for (const step of input.nextSteps) lines.push(`  - ${step}`);
+  }
+  return lines;
+}

package/src/lib/console-telemetry-validate.ts

@@ -0,0 +1,88 @@
+/**
+ * Pure, side-effect-free validation predicates mirroring the bash Console
+ * telemetry validators exactly, for the future guided console-connect wizard
+ * (PR2/PR3) to reuse at prompt time. Deliberately NOT wired into `init.ts`'s
+ * interactive flow in this PR — see install-flow-foundations plan, Thread D.
+ *
+ * Every predicate returns a plain boolean (never throws), matching the
+ * "wizard re-prompts on false" use case, unlike the bash `die`-based
+ * validators these mirror (which exit non-zero on failure).
+ */
+
+/**
+ * Mirrors `has_control_chars` (scripts/telemetry/install-console-config.sh:43-45).
+ * Rejects values containing a newline, carriage return, or tab.
+ */
+export function hasControlChars(value: string): boolean {
+  return value.includes("\n") || value.includes("\r") || value.includes("\t");
+}
+
+/** Shared https/localhost/127.0.0.1 scheme rule used by both URL validators below. */
+function isHttpsOrLocalhostUrl(value: string): boolean {
+  if (value.startsWith("https://")) return true;
+  if (value === "http://127.0.0.1" || value.startsWith("http://127.0.0.1:") || value.startsWith("http://127.0.0.1/")) return true;
+  if (value === "http://localhost" || value.startsWith("http://localhost:") || value.startsWith("http://localhost/")) return true;
+  return false;
+}
+
+/**
+ * Mirrors `validate_url` (scripts/telemetry/install-console-config.sh:47-62).
+ * Blank is valid (the field is optional at install time). Otherwise: no
+ * control characters, and must be `https://*`, or `http://` to localhost/127.0.0.1.
+ */
+export function isValidConsoleUrl(value: string): boolean {
+  if (value === "") return true;
+  if (hasControlChars(value)) return false;
+  return isHttpsOrLocalhostUrl(value);
+}
+
+/**
+ * Mirrors `console_telemetry_endpoint_allowed` (scripts/telemetry/lib/transport.sh:20-28).
+ * Unlike `isValidConsoleUrl`, blank is INVALID (a non-empty endpoint is
+ * required at runtime-post time). This check is deliberately narrower than
+ * `hasControlChars`: the bash function only rejects `\n`, `\r`, and a
+ * literal `"` (the value is later embedded in a curl config file as a
+ * quoted string) — it does NOT reject tab, so this must not call
+ * `hasControlChars` (which also rejects tab).
+ */
+export function isValidConsoleEndpointStrict(value: string): boolean {
+  if (value === "") return false;
+  if (value.includes("\n") || value.includes("\r") || value.includes('"')) return false;
+  return isHttpsOrLocalhostUrl(value);
+}
+
+const CONSOLE_TOKEN_CHARSET = /^[A-Za-z0-9._~+/=-]+$/;
+
+/**
+ * Mirrors `validate_token` (scripts/telemetry/install-console-config.sh:64-69).
+ * Blank is valid (optional field). Otherwise: length <= 4096, no control
+ * characters, and charset restricted to `[A-Za-z0-9._~+/=-]`.
+ */
+export function isValidConsoleToken(value: string): boolean {
+  if (value === "") return true;
+  if (value.length > 4096) return false;
+  if (hasControlChars(value)) return false;
+  return CONSOLE_TOKEN_CHARSET.test(value);
+}
+
+const CONSOLE_TENANT_CHARSET = /^[A-Za-z0-9._:-]+$/;
+
+/**
+ * Mirrors `validate_tenant` (scripts/telemetry/install-console-config.sh:82-86).
+ * Blank is valid (optional field). Otherwise: charset restricted to
+ * `[A-Za-z0-9._:-]` (no length bound at install time).
+ */
+export function isValidConsoleTenant(value: string): boolean {
+  if (value === "") return true;
+  return CONSOLE_TENANT_CHARSET.test(value);
+}
+
+/**
+ * Mirrors `console_telemetry_safe_tenant` (scripts/telemetry/lib/transport.sh:35-38).
+ * Unlike `isValidConsoleTenant`, non-empty is required and length is bounded
+ * to 1..128 (the runtime-safety gate, stricter than the install-time validator).
+ */
+export function isSafeConsoleTenantForRuntime(value: string): boolean {
+  if (value.length < 1 || value.length > 128) return false;
+  return CONSOLE_TENANT_CHARSET.test(value);
+}

package/src/lib/flow-resolver.ts

@@ -57,6 +57,33 @@ function isAgentWritableDir(resolvedDir: string): boolean {
   }
 }
 
+function installedPackageRoot(): string | null {
+  let directory = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    if (fs.existsSync(path.join(directory, "package.json")) && fs.existsSync(path.join(directory, "kits"))) {
+      return directory;
+    }
+    const parent = path.dirname(directory);
+    if (parent === directory) return null;
+    directory = parent;
+  }
+}
+
+function packagedFlowFile(kitId: string, flowName: string, consumerRoot: string): string | null {
+  const packageRoot = installedPackageRoot();
+  if (!packageRoot || path.resolve(packageRoot) === path.resolve(consumerRoot)) return null;
+  const kitsRoot = path.resolve(packageRoot, "kits");
+  const candidate = path.resolve(kitsRoot, kitId, "flows", `${flowName}.flow.json`);
+  if (!candidate.startsWith(kitsRoot + path.sep)) return null;
+  try {
+    const realKitsRoot = fs.realpathSync.native(kitsRoot);
+    const realCandidate = fs.realpathSync.native(candidate);
+    return realCandidate.startsWith(realKitsRoot + path.sep) ? realCandidate : null;
+  } catch {
+    return null;
+  }
+}
+
 /**
  * Build and validate the FlowDefinition file path.
  *
@@ -65,30 +92,29 @@ function isAgentWritableDir(resolvedDir: string): boolean {
  *  - FLOW_AGENTS_FLOW_DEFS_DIR resolves into a runtime artifact directory
  *  - The resolved path escapes the expected root (belt-and-suspenders)
  *
- * When the override is unsafe, it is ignored and the resolver uses the
- * canonical repoRoot/kits/ source for legitimate flows.
+ * An unsafe explicit override fails closed. Package fallback applies only to
+ * canonical lookup when no override was supplied.
  */
 export function resolveFlowFilePath(
   kitId: string,
   flowName: string,
   flowId: string,
   repoRoot: string,
+  allowOverride = true,
 ): string | null {
   // Primary defense: reject any slug containing traversal chars or non-identifier chars.
   if (!SLUG_RE.test(kitId) || !SLUG_RE.test(flowName)) return null;
 
-  const override = process.env["FLOW_AGENTS_FLOW_DEFS_DIR"];
+  const override = allowOverride ? process.env["FLOW_AGENTS_FLOW_DEFS_DIR"] : undefined;
 
   let expectedRoot: string;
   let flowFilePath: string;
+  let canonicalLookup = false;
 
   if (override) {
     const resolvedOverride = path.resolve(override);
     if (isAgentWritableDir(resolvedOverride)) {
-      // Override targets an agent-writable runtime path; ignore it and use
-      // the canonical kit root. The session will resolve the real kit flow.
-      expectedRoot = path.resolve(repoRoot, "kits");
-      flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+      return null;
     } else {
       expectedRoot = resolvedOverride;
       // flowId = kitId + "." + flowName; after slug validation this contains only
@@ -98,6 +124,7 @@ export function resolveFlowFilePath(
   } else {
     expectedRoot = path.resolve(repoRoot, "kits");
     flowFilePath = path.join(repoRoot, "kits", kitId, "flows", `${flowName}.flow.json`);
+    canonicalLookup = true;
   }
 
   // Belt-and-suspenders: confirm the resolved path stays within the expected root.
@@ -119,6 +146,10 @@ export function resolveFlowFilePath(
     }
     return realPath;
   } catch {
+    if (canonicalLookup) {
+      const packaged = packagedFlowFile(kitId, flowName, repoRoot);
+      if (packaged) return packaged;
+    }
     return resolvedPath;
   }
 }
@@ -143,6 +174,7 @@ export type ActiveFlowStep = {
   stepId: string;
   gateId: string;
   gateExpects: GateExpectation[];
+  routeBackReasons: string[];
   /** When resolved through a parent step's uses_flow edge, names the child FlowDefinition that owns the gate. */
   sourceFlowId?: string;
 };
@@ -183,10 +215,10 @@ function flowIdParts(flowId: string): { kitId: string; flowName: string } | null
   return { kitId, flowName };
 }
 
-function readFlowDefinition(flowId: string, repoRoot: string): FlowDefinition | null {
+function readFlowDefinition(flowId: string, repoRoot: string, allowOverride = true): FlowDefinition | null {
   const parts = flowIdParts(flowId);
   if (!parts) return null;
-  const flowFilePath = resolveFlowFilePath(parts.kitId, parts.flowName, flowId, repoRoot);
+  const flowFilePath = resolveFlowFilePath(parts.kitId, parts.flowName, flowId, repoRoot, allowOverride);
   if (!flowFilePath) return null;
 
   try {
@@ -213,6 +245,116 @@ export function resolveFlowStep(flowId: string, stepId: string, repoRoot: string
   return publicStep;
 }
 
+/**
+ * Compile Flow Agents' `uses_flow` kit extension into one effective definition
+ * that the Flow runtime can evaluate without understanding agent-layer composition.
+ */
+export function resolveEffectiveFlowDefinition(flowId: string, repoRoot: string, options: { allowOverride?: boolean } = {}): Record<string, unknown> | null {
+  return resolveEffectiveFlowDefinitionInternal(flowId, repoRoot, new Set<string>(), options.allowOverride !== false);
+}
+
+function resolveEffectiveFlowDefinitionInternal(flowId: string, repoRoot: string, seen: Set<string>, allowOverride: boolean): Record<string, unknown> | null {
+  if (seen.has(flowId)) return null;
+  const nextSeen = new Set(seen);
+  nextSeen.add(flowId);
+  const source = readFlowDefinition(flowId, repoRoot, allowOverride);
+  if (!source || !Array.isArray(source.steps)) return null;
+  const effective = JSON.parse(JSON.stringify(source)) as FlowDefinition;
+  effective.gates = { ...(effective.gates ?? {}) };
+
+  for (let index = 0; index < source.steps.length; index += 1) {
+    const sourceStep = source.steps[index]!;
+    if (typeof sourceStep.uses_flow !== "string" || !sourceStep.uses_flow.trim()) continue;
+    const child = resolveEffectiveFlowDefinitionInternal(sourceStep.uses_flow, repoRoot, nextSeen, allowOverride) as FlowDefinition | null;
+    if (!child || !child.gates) return null;
+    const childGateEntry = Object.entries(child.gates).find(([, gate]) => gate?.step === sourceStep.id);
+    if (!childGateEntry) return null;
+    if (Object.values(effective.gates).some((gate) => gate?.step === sourceStep.id)) return null;
+    const [childGateId, childGate] = childGateEntry;
+    const childExpects = Array.isArray(childGate.expects) ? childGate.expects : [];
+    const exported = exportedExpectations(childExpects, child.exports);
+    if (!exported) return null;
+    effective.gates[`${sourceStep.uses_flow}:${childGateId}`] = {
+      ...childGate,
+      expects: exported,
+    };
+    const { uses_flow: _usesFlow, ...compiledStep } = effective.steps![index]!;
+    effective.steps![index] = compiledStep;
+  }
+  const effectiveSteps = effective.steps!;
+  const done = effectiveSteps.find((step) => step.id === "done" && step.next === null);
+  if (done && !Object.values(effective.gates).some((gate) => gate?.step === "done")) {
+    effective.steps = effectiveSteps
+      .filter((step) => step.id !== "done")
+      .map((step) => step.next === "done" ? { ...step, next: null } : step);
+  }
+  return effective as unknown as Record<string, unknown>;
+}
+
+/**
+ * A single (stepId, gateId) → expects[] tuple, as part of the FULL enumeration of every gate in
+ * a FlowDefinition (across every step — see resolveAllFlowGateExpects below), not just the
+ * currently-active one.
+ */
+export type FlowGateExpectsEntry = {
+  stepId: string;
+  gateId: string;
+  gateExpects: GateExpectation[];
+};
+
+/**
+ * Enumerate the gate expects[] for EVERY step in a FlowDefinition (#270 CRITICAL/HIGH fix) —
+ * not just the currently-active step. This is what lets a stamped gate-claim's
+ * (expectation_id, claim_type, subject_type, step_id) tuple be validated against the FULL,
+ * declared shape of the flow, instead of only against whatever step happens to be active at
+ * validation time (which is a DIFFERENT, and usually wrong, question: the stamp names the step
+ * it was ORIGINALLY recorded at, which by design may not be the currently-active one — see
+ * buildTrustBundle's #270(a)/(c) step_id-freezing comments in workflow-sidecar.ts).
+ *
+ * Walks flowDef.steps[] (in declaration order) and resolves each step's gate via the same
+ * resolveFlowStepInternal used by resolveFlowStep/resolveActiveFlowStep — including the
+ * uses_flow composed-step case, so a gate that lives in a child FlowDefinition (e.g.
+ * builder.publish-learn's pr-open-gate, composed into builder.build's "pr-open" step) is
+ * enumerated too, exports-filtered exactly as a live resolution would be.
+ *
+ * Pure and synchronous — no throws, fail-open (returns []) on any error, mirroring every other
+ * resolver in this module.
+ *
+ * Callers MUST distinguish the two null-ish outcomes (#270 MEDIUM fix, iteration 3):
+ *   - `null`  → the FlowDefinition could not be LOADED at all (missing file, unreadable, invalid
+ *     JSON, or no `steps[]` array) — the caller has no basis to validate anything against this
+ *     flow and must fail closed with a dedicated "cannot be loaded" message, never the "stamp
+ *     does not match any expects[]" (forged/corrupt) message; those are different failure
+ *     classes with different remedies (a load failure means "fix/restore the FlowDefinition
+ *     file or the flowId", not "this stamp was forged").
+ *   - `[]`    → the FlowDefinition LOADED successfully but genuinely declares no steps with
+ *     matching gates (or no gates at all) — a real, if unusual, flow shape, not an error.
+ *
+ * @param flowId   e.g. "builder.build" — kitId is extracted as the prefix before the first ".".
+ * @param repoRoot Absolute path to the repository root (kits/ lives here).
+ *                 Honored only when FLOW_AGENTS_FLOW_DEFS_DIR is not set.
+ * @returns Every (stepId, gateId, gateExpects) tuple in the flow; `[]` when the flow loads but
+ *   declares no matching gates; `null` when the FlowDefinition cannot be loaded/parsed at all.
+ */
+export function resolveAllFlowGateExpects(flowId: string, repoRoot: string): FlowGateExpectsEntry[] | null {
+  const flowDef = readFlowDefinition(flowId, repoRoot);
+  if (!flowDef || typeof flowDef !== "object" || !Array.isArray(flowDef.steps)) return null;
+  const out: FlowGateExpectsEntry[] = [];
+  const seenGateIds = new Set<string>();
+  for (const step of flowDef.steps) {
+    if (!step || typeof step.id !== "string" || !step.id) continue;
+    const resolved = resolveFlowStepInternal(flowId, step.id, repoRoot, new Set<string>());
+    if (!resolved) continue;
+    // A gate can be reached by more than one step declaration in degenerate/duplicate step
+    // lists; de-dupe by gateId so callers never see the same expects[] entries twice.
+    const dedupeKey = `${resolved.gateId}`;
+    if (seenGateIds.has(dedupeKey)) continue;
+    seenGateIds.add(dedupeKey);
+    out.push({ stepId: resolved.stepId, gateId: resolved.gateId, gateExpects: resolved.gateExpects });
+  }
+  return out;
+}
+
 function expectationExportKeys(expectation: GateExpectation): string[] {
   const keys: string[] = [];
   if (typeof expectation.id === "string" && expectation.id) keys.push(expectation.id);
@@ -249,7 +391,7 @@ function resolveFlowStepInternal(flowId: string, stepId: string, repoRoot: strin
     for (const [gateId, gate] of Object.entries(flowDef.gates)) {
       if (!gate || gate.step !== stepId) continue;
       const expects = Array.isArray(gate.expects) ? gate.expects : [];
-      return { flowId, stepId, gateId, gateExpects: expects, flowExports: flowDef.exports };
+      return { flowId, stepId, gateId, gateExpects: expects, routeBackReasons: Object.keys(gate.on_route_back ?? {}), flowExports: flowDef.exports };
     }
   }
 
@@ -266,6 +408,7 @@ function resolveFlowStepInternal(flowId: string, stepId: string, repoRoot: strin
         stepId,
         gateId: `${child.flowId}:${child.gateId}`,
         gateExpects: childGateExpects,
+        routeBackReasons: child.routeBackReasons,
         sourceFlowId: child.flowId,
         flowExports: flowDef.exports,
       };