@kontourai/flow-agents 3.3.0 → 3.4.1

package/build/src/lib/console-connect-options.js

@@ -0,0 +1,199 @@
+/**
+ * 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";
+/**
+ * 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, fallback) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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 };
+}
+// 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, defaults) {
+    const warnings = [];
+    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;
+    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;
+    let consoleTenant;
+    // 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 };
+}
+/**
+ * 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) {
+    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 };
+}
+function consoleStatusLine(consoleStatus) {
+    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) {
+    const lines = [];
+    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/build/src/lib/console-telemetry-validate.d.ts

@@ -0,0 +1,49 @@
+/**
+ * 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 declare function hasControlChars(value: string): boolean;
+/**
+ * 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 declare function isValidConsoleUrl(value: string): boolean;
+/**
+ * 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 declare function isValidConsoleEndpointStrict(value: string): boolean;
+/**
+ * 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 declare function isValidConsoleToken(value: string): boolean;
+/**
+ * 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 declare function isValidConsoleTenant(value: string): boolean;
+/**
+ * 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 declare function isSafeConsoleTenantForRuntime(value: string): boolean;

package/build/src/lib/console-telemetry-validate.js

@@ -0,0 +1,91 @@
+/**
+ * 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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    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) {
+    if (value.length < 1 || value.length > 128)
+        return false;
+    return CONSOLE_TENANT_CHARSET.test(value);
+}

package/build/src/lib/flow-resolver.d.ts

@@ -20,10 +20,10 @@
  *  - 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 declare function resolveFlowFilePath(kitId: string, flowName: string, flowId: string, repoRoot: string): string | null;
+export declare function resolveFlowFilePath(kitId: string, flowName: string, flowId: string, repoRoot: string, allowOverride?: boolean): string | null;
 /** A single gate expectation from a FlowDefinition expects[] entry. */
 export type GateExpectation = {
     id: string;
@@ -41,6 +41,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;
 };
@@ -54,6 +55,58 @@ export type ActiveFlowStep = {
  * @returns ActiveFlowStep with the matched gate's expects[], or null on any error.
  */
 export declare function resolveFlowStep(flowId: string, stepId: string, repoRoot: string): ActiveFlowStep | null;
+/**
+ * Compile Flow Agents' `uses_flow` kit extension into one effective definition
+ * that the Flow runtime can evaluate without understanding agent-layer composition.
+ */
+export declare function resolveEffectiveFlowDefinition(flowId: string, repoRoot: string, options?: {
+    allowOverride?: boolean;
+}): Record<string, unknown> | null;
+/**
+ * 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 declare function resolveAllFlowGateExpects(flowId: string, repoRoot: string): FlowGateExpectsEntry[] | null;
 /**
  * Resolve the phase→step mapping from a FlowDefinition's phase_map field.
  *

package/build/src/lib/flow-resolver.js

@@ -54,6 +54,35 @@ function isAgentWritableDir(resolvedDir) {
         return false;
     }
 }
+function installedPackageRoot() {
+    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, flowName, consumerRoot) {
+    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.
  *
@@ -62,23 +91,21 @@ function isAgentWritableDir(resolvedDir) {
  *  - 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, flowName, flowId, repoRoot) {
+export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot, allowOverride = true) {
     // 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;
     let flowFilePath;
+    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;
@@ -90,6 +117,7 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot) {
     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.
     // After slug validation this is theoretically unreachable, but defense-in-depth
@@ -110,6 +138,11 @@ export function resolveFlowFilePath(kitId, flowName, flowId, repoRoot) {
         return realPath;
     }
     catch {
+        if (canonicalLookup) {
+            const packaged = packagedFlowFile(kitId, flowName, repoRoot);
+            if (packaged)
+                return packaged;
+        }
         return resolvedPath;
     }
 }
@@ -125,11 +158,11 @@ function flowIdParts(flowId) {
         return null;
     return { kitId, flowName };
 }
-function readFlowDefinition(flowId, repoRoot) {
+function readFlowDefinition(flowId, repoRoot, allowOverride = true) {
     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 {
@@ -156,6 +189,112 @@ export function resolveFlowStep(flowId, stepId, repoRoot) {
     const { flowExports: _flowExports, ...publicStep } = resolved;
     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, repoRoot, options = {}) {
+    return resolveEffectiveFlowDefinitionInternal(flowId, repoRoot, new Set(), options.allowOverride !== false);
+}
+function resolveEffectiveFlowDefinitionInternal(flowId, repoRoot, seen, allowOverride) {
+    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));
+    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);
+        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;
+}
+/**
+ * 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, repoRoot) {
+    const flowDef = readFlowDefinition(flowId, repoRoot);
+    if (!flowDef || typeof flowDef !== "object" || !Array.isArray(flowDef.steps))
+        return null;
+    const out = [];
+    const seenGateIds = new Set();
+    for (const step of flowDef.steps) {
+        if (!step || typeof step.id !== "string" || !step.id)
+            continue;
+        const resolved = resolveFlowStepInternal(flowId, step.id, repoRoot, new Set());
+        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) {
     const keys = [];
     if (typeof expectation.id === "string" && expectation.id)
@@ -196,7 +335,7 @@ function resolveFlowStepInternal(flowId, stepId, repoRoot, seen) {
             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 };
         }
     }
     const composedStep = Array.isArray(flowDef.steps)
@@ -213,6 +352,7 @@ function resolveFlowStepInternal(flowId, stepId, repoRoot, seen) {
                 stepId,
                 gateId: `${child.flowId}:${child.gateId}`,
                 gateExpects: childGateExpects,
+                routeBackReasons: child.routeBackReasons,
                 sourceFlowId: child.flowId,
                 flowExports: flowDef.exports,
             };