@kontourai/flow-agents 3.4.0 → 3.4.2

package/src/cli/builder-flow-runtime.test.mjs

@@ -6,9 +6,11 @@ import path from "node:path";
 
 import { FLOW_RUN_EVIDENCE_MANIFEST_PATH, runDir } from "@kontourai/flow";
 import {
+  recoverBuilderFlowSession,
   startBuilderFlowSession,
   syncBuilderFlowSession,
 } from "../../build/src/builder-flow-runtime.js";
+import { main as builderRunMain } from "../../build/src/cli/builder-run.js";
 
 const SUBJECT = "local:work-item/runtime-projection";
 const NOW = "2026-07-09T20:00:00.000Z";
@@ -43,6 +45,45 @@ function readJson(file) {
   return JSON.parse(fs.readFileSync(file, "utf8"));
 }
 
+function snapshotFile(file) {
+  return fs.existsSync(file) ? fs.readFileSync(file).toString("base64") : null;
+}
+
+function snapshotTree(directory) {
+  if (!fs.existsSync(directory)) return null;
+  const files = [];
+  function visit(current) {
+    for (const entry of fs.readdirSync(current, { withFileTypes: true }).sort((a, b) => a.name.localeCompare(b.name))) {
+      const absolute = path.join(current, entry.name);
+      if (entry.isDirectory()) visit(absolute);
+      else files.push([path.relative(directory, absolute), fs.readFileSync(absolute).toString("base64")]);
+    }
+  }
+  visit(directory);
+  return files;
+}
+
+function snapshotProjectionTargets(session) {
+  const actorRoot = path.join(session.artifactRoot, "current");
+  const actors = fs.existsSync(actorRoot)
+    ? fs.readdirSync(actorRoot).filter((name) => name.endsWith(".json")).sort()
+    : [];
+  return {
+    state: snapshotFile(path.join(session.sessionDir, "state.json")),
+    current: snapshotFile(path.join(session.artifactRoot, "current.json")),
+    actors: actors.map((name) => [name, snapshotFile(path.join(actorRoot, name))]),
+  };
+}
+
+async function assertRecoveryRejectsWithoutWrites(session, pattern) {
+  const flowDirectory = runDir(session.slug, session.projectRoot);
+  const beforeFlow = snapshotTree(flowDirectory);
+  const beforeProjection = snapshotProjectionTargets(session);
+  await assert.rejects(() => recoverBuilderFlowSession({ sessionDir: session.sessionDir }), pattern);
+  assert.deepEqual(snapshotTree(flowDirectory), beforeFlow);
+  assert.deepEqual(snapshotProjectionTargets(session), beforeProjection);
+}
+
 function bundleClaim({ expectation, claimType, subjectType, status = "pass", routeReason, subject = SUBJECT }) {
   const claimId = `claim.${expectation}`;
   return {
@@ -210,4 +251,305 @@ test("verified sidecar claims drive the composed publish and learning prefix to
   assert.equal(completed.run.state.status, "completed");
   assert.equal(completed.projection.status, "delivered");
   assert.deepEqual(completed.projection.next_action, { status: "done", summary: "Canonical Flow run is complete." });
+
+  const flowDirectory = runDir(session.slug, session.projectRoot);
+  const beforeFlow = snapshotTree(flowDirectory);
+  const staleState = readJson(path.join(session.sessionDir, "state.json"));
+  staleState.status = "in_progress";
+  staleState.phase = "verification";
+  staleState.next_action = { status: "continue", summary: "stale" };
+  writeJson(path.join(session.sessionDir, "state.json"), staleState);
+  const recovered = await recoverBuilderFlowSession({ sessionDir: session.sessionDir });
+  assert.equal(recovered.attached, false);
+  assert.equal(recovered.projection.status, "delivered");
+  assert.equal(recovered.projection.phase, "done");
+  assert.deepEqual(recovered.projection.next_action, { status: "done", summary: "Canonical Flow run is complete." });
+  assert.deepEqual(snapshotTree(flowDirectory), beforeFlow);
+});
+
+test("recovery loads the slug-bound run, restores every matching projection, and preserves every Flow byte", async () => {
+  const session = makeSession("recover-active");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const advanced = await writeAndSync(session, [bundleClaim({
+    expectation: "selected-work",
+    claimType: "builder.pull-work.selected",
+    subjectType: "work-item",
+  })]);
+  assert.equal(advanced.run.state.current_step, "design-probe");
+
+  writeJson(path.join(session.artifactRoot, "current", "codex.json"), {
+    active_slug: session.slug,
+    active_step_id: "stale-step",
+    updated_at: NOW,
+  });
+  writeJson(path.join(session.artifactRoot, "current", "other.json"), {
+    active_slug: "another-session",
+    active_step_id: "untouched-step",
+    updated_at: NOW,
+  });
+  const staleState = readJson(path.join(session.sessionDir, "state.json"));
+  staleState.status = "planned";
+  staleState.phase = "planning";
+  staleState.flow_run.current_step = "pull-work";
+  staleState.next_action = { status: "continue", summary: "stale" };
+  writeJson(path.join(session.sessionDir, "state.json"), staleState);
+  const flowDirectory = runDir(session.slug, session.projectRoot);
+  const beforeFlow = snapshotTree(flowDirectory);
+  const beforeOther = snapshotFile(path.join(session.artifactRoot, "current", "other.json"));
+  const bundleBefore = snapshotFile(path.join(session.sessionDir, "trust.bundle"));
+
+  const recovered = await recoverBuilderFlowSession({ sessionDir: session.sessionDir });
+
+  assert.equal(recovered.attached, false);
+  assert.equal(recovered.run.runId, session.slug);
+  assert.equal(recovered.projection.flow_run.current_step, "design-probe");
+  assert.equal(recovered.projection.phase, advanced.projection.phase);
+  assert.deepEqual(recovered.projection.flow_run.open_gate_ids, advanced.projection.flow_run.open_gate_ids);
+  assert.deepEqual(recovered.projection.next_action.skills, ["pickup-probe"]);
+  assert.equal(readJson(path.join(session.artifactRoot, "current.json")).active_step_id, "design-probe");
+  assert.equal(readJson(path.join(session.artifactRoot, "current", "codex.json")).active_step_id, "design-probe");
+  assert.equal(snapshotFile(path.join(session.artifactRoot, "current", "other.json")), beforeOther);
+  assert.equal(snapshotFile(path.join(session.sessionDir, "trust.bundle")), bundleBefore);
+  assert.deepEqual(snapshotTree(flowDirectory), beforeFlow);
+});
+
+test("recovery fails before any write for invalid Work Item cardinality and Flow subject bindings", async (t) => {
+  const cases = [
+    ["zero refs", [], /state\.work_item_refs.*exactly one/],
+    ["empty ref", [""], /state\.work_item_refs.*exactly one/],
+    ["blank ref", ["   "], /state\.work_item_refs.*exactly one/],
+    ["two refs", [SUBJECT, "local:work-item/other"], /state\.work_item_refs.*exactly one/],
+  ];
+  for (const [name, refs, pattern] of cases) {
+    await t.test(name, async () => {
+      const session = makeSession(`recover-${name.replaceAll(" ", "-")}`);
+      await startBuilderFlowSession({ sessionDir: session.sessionDir });
+      const state = readJson(path.join(session.sessionDir, "state.json"));
+      state.work_item_refs = refs;
+      writeJson(path.join(session.sessionDir, "state.json"), state);
+      await assertRecoveryRejectsWithoutWrites(session, pattern);
+    });
+  }
+
+  await t.test("persisted state subject mismatch", async () => {
+    const session = makeSession("recover-state-subject-mismatch");
+    await startBuilderFlowSession({ sessionDir: session.sessionDir });
+    const file = path.join(runDir(session.slug, session.projectRoot), "state.json");
+    const state = readJson(file);
+    state.subject = "local:work-item/other";
+    writeJson(file, state);
+    await assertRecoveryRejectsWithoutWrites(session, /flow_run\.state\.subject.*selected Work Item/);
+  });
+
+  await t.test("persisted params subject mismatch", async () => {
+    const session = makeSession("recover-params-subject-mismatch");
+    await startBuilderFlowSession({ sessionDir: session.sessionDir });
+    const file = path.join(runDir(session.slug, session.projectRoot), "state.json");
+    const state = readJson(file);
+    state.params.subject = "local:work-item/other";
+    writeJson(file, state);
+    await assertRecoveryRejectsWithoutWrites(session, /flow_run\.state\.params\.subject.*selected Work Item/);
+  });
+
+  await t.test("absent persisted params subject is allowed", async () => {
+    const session = makeSession("recover-params-subject-absent");
+    await startBuilderFlowSession({ sessionDir: session.sessionDir });
+    const flowDirectory = runDir(session.slug, session.projectRoot);
+    const file = path.join(flowDirectory, "state.json");
+    const state = readJson(file);
+    delete state.params.subject;
+    writeJson(file, state);
+    const beforeFlow = snapshotTree(flowDirectory);
+    const recovered = await recoverBuilderFlowSession({ sessionDir: session.sessionDir });
+    assert.equal(recovered.attached, false);
+    assert.deepEqual(snapshotTree(flowDirectory), beforeFlow);
+  });
+});
+
+test("recovery fails closed for invalid sidecars and missing or corrupt canonical runs", async (t) => {
+  await t.test("invalid session path", async () => {
+    const projectRoot = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-builder-invalid-session-"));
+    await assert.rejects(
+      () => recoverBuilderFlowSession({ sessionDir: path.join(projectRoot, "not-a-session") }),
+      /sessionDir.*must be \.kontourai\/flow-agents/,
+    );
+    assert.equal(fs.existsSync(path.join(projectRoot, ".kontourai")), false);
+  });
+
+  await t.test("missing run remains missing", async () => {
+    const session = makeSession("recover-missing-run");
+    await assertRecoveryRejectsWithoutWrites(session, /not_found|not found/i);
+    assert.equal(fs.existsSync(runDir(session.slug, session.projectRoot)), false);
+  });
+
+  await t.test("task slug mismatch", async () => {
+    const session = makeSession("recover-task-slug-mismatch");
+    await startBuilderFlowSession({ sessionDir: session.sessionDir });
+    const state = readJson(path.join(session.sessionDir, "state.json"));
+    state.task_slug = "other";
+    writeJson(path.join(session.sessionDir, "state.json"), state);
+    await assertRecoveryRejectsWithoutWrites(session, /task_slug.*match/);
+  });
+
+  await t.test("missing sidecar state", async () => {
+    const session = makeSession("recover-missing-sidecar-state");
+    await startBuilderFlowSession({ sessionDir: session.sessionDir });
+    fs.rmSync(path.join(session.sessionDir, "state.json"));
+    await assertRecoveryRejectsWithoutWrites(session, /sessionDir.*state\.json/);
+  });
+
+  await t.test("corrupt sidecar state", async () => {
+    const session = makeSession("recover-corrupt-sidecar-state");
+    await startBuilderFlowSession({ sessionDir: session.sessionDir });
+    fs.writeFileSync(path.join(session.sessionDir, "state.json"), "not-json\n");
+    await assertRecoveryRejectsWithoutWrites(session, /JSON|parse|Unexpected/i);
+  });
+
+  for (const [name, relativeFile] of [
+    ["corrupt Flow state", "state.json"],
+    ["corrupt Flow manifest", FLOW_RUN_EVIDENCE_MANIFEST_PATH],
+  ]) {
+    await t.test(name, async () => {
+      const session = makeSession(`recover-${name.replaceAll(" ", "-").toLowerCase()}`);
+      await startBuilderFlowSession({ sessionDir: session.sessionDir });
+      fs.writeFileSync(path.join(runDir(session.slug, session.projectRoot), relativeFile), "not-json\n");
+      await assertRecoveryRejectsWithoutWrites(session, /JSON|parse|invalid|Unexpected/i);
+    });
+  }
+
+  for (const [name, mutate] of [
+    ["foreign definition identity", (definition) => { definition.id = "foreign.build"; }],
+    ["foreign definition content", (definition) => { definition.steps[0].description = "foreign content"; }],
+  ]) {
+    await t.test(name, async () => {
+      const session = makeSession(`recover-${name.replaceAll(" ", "-")}`);
+      await startBuilderFlowSession({ sessionDir: session.sessionDir });
+      const file = path.join(runDir(session.slug, session.projectRoot), "definition.json");
+      const definition = readJson(file);
+      mutate(definition);
+      writeJson(file, definition);
+      await assertRecoveryRejectsWithoutWrites(session, /definition|foreign|canonical|identity|content|invalid/i);
+    });
+  }
+});
+
+test("recover and sync remain separate: recovery leaves bundle unattached and sync evaluates it", async () => {
+  const session = makeSession("recover-then-sync");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  writeBundle(session.sessionDir, [bundleClaim({
+    expectation: "selected-work",
+    claimType: "builder.pull-work.selected",
+    subjectType: "work-item",
+  })]);
+  const manifestFile = path.join(runDir(session.slug, session.projectRoot), FLOW_RUN_EVIDENCE_MANIFEST_PATH);
+  const manifestBefore = snapshotFile(manifestFile);
+
+  const recovered = await recoverBuilderFlowSession({ sessionDir: session.sessionDir });
+  assert.equal(recovered.attached, false);
+  assert.equal(snapshotFile(manifestFile), manifestBefore);
+  assert.equal(recovered.run.state.current_step, "pull-work");
+
+  const synced = await syncBuilderFlowSession({ sessionDir: session.sessionDir });
+  assert.equal(synced.attached, true);
+  assert.equal(synced.run.state.current_step, "design-probe");
+  assert.notEqual(snapshotFile(manifestFile), manifestBefore);
+});
+
+test("builder-run recover accepts only a session directory and rejects caller-selected identity", async () => {
+  const session = makeSession("recover-cli");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  assert.equal(await builderRunMain(["recover", "--session-dir", session.sessionDir]), 0);
+  assert.equal(await builderRunMain(["recover", "--session-dir", session.sessionDir, "--run-id", "other"]), 64);
+  assert.equal(await builderRunMain(["recover", "--session-dir", session.sessionDir, "--step-id", "verify"]), 64);
+  assert.equal(await builderRunMain(["recover", "extra", "--session-dir", session.sessionDir]), 64);
+});
+
+test("recovery refuses a sidecar changed after its immutable subject snapshot", async () => {
+  const session = makeSession("recover-sidecar-race");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const flowDirectory = runDir(session.slug, session.projectRoot);
+  const beforeFlow = snapshotTree(flowDirectory);
+  const recovery = recoverBuilderFlowSession({ sessionDir: session.sessionDir });
+  const changed = readJson(path.join(session.sessionDir, "state.json"));
+  changed.work_item_refs = ["local:work-item/raced"];
+  writeJson(path.join(session.sessionDir, "state.json"), changed);
+  const beforeProjection = snapshotProjectionTargets(session);
+
+  await assert.rejects(() => recovery, /state\.json.*changed during recovery/);
+  assert.deepEqual(snapshotTree(flowDirectory), beforeFlow);
+  assert.deepEqual(snapshotProjectionTargets(session), beforeProjection);
+});
+
+test("recovery parses every projection target before writing any target", async (t) => {
+  for (const target of ["global", "actor"]) {
+    await t.test(`malformed ${target} pointer`, async () => {
+      const session = makeSession(`recover-malformed-${target}-pointer`);
+      await startBuilderFlowSession({ sessionDir: session.sessionDir });
+      const state = readJson(path.join(session.sessionDir, "state.json"));
+      state.next_action = { status: "continue", summary: "stale projection" };
+      writeJson(path.join(session.sessionDir, "state.json"), state);
+      const pointer = target === "global"
+        ? path.join(session.artifactRoot, "current.json")
+        : path.join(session.artifactRoot, "current", "codex.json");
+      fs.mkdirSync(path.dirname(pointer), { recursive: true });
+      fs.writeFileSync(pointer, "not-json\n");
+      await assertRecoveryRejectsWithoutWrites(session, /projection target.*JSON|JSON|parse|Unexpected/i);
+    });
+  }
+});
+
+test("recovery rejects symlinked session and projection targets before writes", async (t) => {
+  await t.test("session directory symlink", async () => {
+    const session = makeSession("recover-session-symlink");
+    await startBuilderFlowSession({ sessionDir: session.sessionDir });
+    const target = path.join(session.artifactRoot, "recover-session-symlink-target");
+    fs.renameSync(session.sessionDir, target);
+    fs.symlinkSync(target, session.sessionDir, "dir");
+    const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+    const beforeState = snapshotFile(path.join(target, "state.json"));
+    await assert.rejects(() => recoverBuilderFlowSession({ sessionDir: session.sessionDir }), /sessionDir.*symbolic link/);
+    assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+    assert.equal(snapshotFile(path.join(target, "state.json")), beforeState);
+  });
+
+  await t.test("state.json symlink", async () => {
+    const session = makeSession("recover-state-symlink");
+    await startBuilderFlowSession({ sessionDir: session.sessionDir });
+    const stateFile = path.join(session.sessionDir, "state.json");
+    const target = path.join(session.sessionDir, "state-target.json");
+    fs.renameSync(stateFile, target);
+    fs.symlinkSync(target, stateFile);
+    const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+    const beforeTarget = snapshotFile(target);
+    await assert.rejects(() => recoverBuilderFlowSession({ sessionDir: session.sessionDir }), /state\.json.*symbolic link/);
+    assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+    assert.equal(snapshotFile(target), beforeTarget);
+  });
+
+  for (const targetKind of ["global pointer", "actor pointer", "dangling actor pointer", "actor directory"]) {
+    await t.test(targetKind, async () => {
+      const session = makeSession(`recover-${targetKind.replaceAll(" ", "-")}-symlink`);
+      await startBuilderFlowSession({ sessionDir: session.sessionDir });
+      const externalRoot = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-builder-pointer-symlink-"));
+      const externalPointer = path.join(externalRoot, "current.json");
+      writeJson(externalPointer, { active_slug: session.slug, active_step_id: "stale", updated_at: NOW });
+      if (targetKind === "global pointer") {
+        fs.rmSync(path.join(session.artifactRoot, "current.json"));
+        fs.symlinkSync(externalPointer, path.join(session.artifactRoot, "current.json"));
+      } else if (targetKind === "actor pointer" || targetKind === "dangling actor pointer") {
+        const actorRoot = path.join(session.artifactRoot, "current");
+        fs.mkdirSync(actorRoot, { recursive: true });
+        fs.symlinkSync(targetKind === "dangling actor pointer" ? path.join(externalRoot, "missing.json") : externalPointer, path.join(actorRoot, "codex.json"));
+      } else {
+        fs.symlinkSync(externalRoot, path.join(session.artifactRoot, "current"), "dir");
+      }
+      const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+      const beforeState = snapshotFile(path.join(session.sessionDir, "state.json"));
+      const beforeExternal = snapshotFile(externalPointer);
+      await assert.rejects(() => recoverBuilderFlowSession({ sessionDir: session.sessionDir }), /current.*symbolic link|projection target.*symbolic link/);
+      assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+      assert.equal(snapshotFile(path.join(session.sessionDir, "state.json")), beforeState);
+      assert.equal(snapshotFile(externalPointer), beforeExternal);
+    });
+  }
 });

package/src/cli/builder-run.ts

@@ -1,21 +1,30 @@
 import { flagString, parseArgs } from "../lib/args.js";
-import { startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
+import { recoverBuilderFlowSession, startBuilderFlowSession, syncBuilderFlowSession } from "../builder-flow-runtime.js";
 
 export async function main(argv: string[]): Promise<number> {
   const parsed = parseArgs(argv);
   const action = parsed.positionals[0];
   const sessionDir = flagString(parsed.flags, "session-dir");
+  const validRecoveryArguments = parsed.positionals.length === 1
+    && Object.keys(parsed.flags).length === 1
+    && typeof parsed.flags["session-dir"] === "string";
+  if (action === "recover" && !validRecoveryArguments) {
+    console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
+    return 64;
+  }
   if (!sessionDir) {
     console.error("builder-run requires --session-dir .kontourai/flow-agents/<slug>");
     return 64;
   }
-  if (action !== "start" && action !== "sync") {
-    console.error("Usage: flow-agents builder-run <start|sync> --session-dir <path>");
+  if (action !== "start" && action !== "sync" && action !== "recover") {
+    console.error("Usage: flow-agents builder-run <start|sync|recover> --session-dir <path>");
     return 64;
   }
   const result = action === "start"
     ? await startBuilderFlowSession({ sessionDir })
-    : await syncBuilderFlowSession({ sessionDir });
+    : action === "sync"
+      ? await syncBuilderFlowSession({ sessionDir })
+      : await recoverBuilderFlowSession({ sessionDir });
   console.log(JSON.stringify({
     run_id: result.run.runId,
     definition_id: result.run.definitionId,

package/src/cli/flow-resolver-composition.test.mjs

@@ -4,7 +4,7 @@ import fs from "node:fs";
 import os from "node:os";
 import path from "node:path";
 
-import { resolveEffectiveFlowDefinition } from "../../build/src/lib/flow-resolver.js";
+import { resolveEffectiveFlowDefinition, resolveFlowFilePath } from "../../build/src/lib/flow-resolver.js";
 
 const REPO_ROOT = path.resolve(import.meta.dirname, "../..");
 
@@ -26,6 +26,35 @@ test("effective Builder definition materializes uses_flow and Flow-native comple
   );
 });
 
+test("installed package definitions resolve when a consumer repo has no kits directory", () => {
+  const consumer = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-consumer-"));
+  const resolved = resolveFlowFilePath("builder", "build", "builder.build", consumer, false);
+  assert.ok(resolved);
+  assert.equal(fs.realpathSync(resolved), fs.realpathSync(path.join(REPO_ROOT, "kits", "builder", "flows", "build.flow.json")));
+  assert.equal(resolveEffectiveFlowDefinition("builder.build", consumer, { allowOverride: false })?.version, "1.1");
+});
+
+test("consumer-vendored definitions remain authoritative over package fallback", () => {
+  const consumer = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-consumer-vendored-"));
+  const vendored = path.join(consumer, "kits", "builder", "flows", "build.flow.json");
+  writeJson(vendored, { id: "builder.build", version: "consumer", steps: [{ id: "local", next: null }], gates: {} });
+  assert.equal(resolveFlowFilePath("builder", "build", "builder.build", consumer, false), fs.realpathSync(vendored));
+});
+
+test("unsafe explicit overrides fail closed instead of using package fallback", () => {
+  const consumer = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-consumer-unsafe-"));
+  const unsafeDefinitions = path.join(consumer, ".kontourai", "flow-agents", "definitions");
+  fs.mkdirSync(unsafeDefinitions, { recursive: true });
+  const prior = process.env.FLOW_AGENTS_FLOW_DEFS_DIR;
+  process.env.FLOW_AGENTS_FLOW_DEFS_DIR = unsafeDefinitions;
+  try {
+    assert.equal(resolveFlowFilePath("builder", "build", "builder.build", consumer), null);
+  } finally {
+    if (prior === undefined) delete process.env.FLOW_AGENTS_FLOW_DEFS_DIR;
+    else process.env.FLOW_AGENTS_FLOW_DEFS_DIR = prior;
+  }
+});
+
 test("effective definition compilation rejects uses_flow cycles", () => {
   const definitions = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-composition-cycle-"));
   writeJson(path.join(definitions, "loop.one.flow.json"), {

package/src/cli/workflow-sidecar.ts

@@ -1661,7 +1661,7 @@ function initSidecars(
   slug: string,
   sourceRequest: string,
   summary: string,
-  nextAction: string,
+  nextAction: string | AnyObj,
   timestamp: string,
   markdown?: string,
   workItemRefs: string[] = [],
@@ -1698,12 +1698,16 @@ function initSidecars(
   // existing state.json's created_at when present; stamp only on true first-creation.
   // updated_at still reflects "now" on every call — that field is intentionally mutable.
   const retainedWorkItemRefs = workItemRefs.length > 0 ? workItemRefs : (Array.isArray(existingState.work_item_refs) ? existingState.work_item_refs : []);
+  const nextActionSummary = typeof nextAction === "string" ? nextAction : String(nextAction.summary ?? summary);
+  const nextActionPayload = typeof nextAction === "string"
+    ? { status: "continue", summary: nextAction || summary }
+    : { status: "continue", ...nextAction, summary: nextActionSummary };
   writeJson(path.join(dir, "state.json"), {
     ...sidecarBase(slug), status: initialLifecycle?.status ?? "planned", phase: initialLifecycle?.phase ?? "planning", created_at: existingState.created_at || timestamp, updated_at: timestamp,
     ...(branch ? { branch } : {}),
     ...(retainedWorkItemRefs.length > 0 ? { work_item_refs: retainedWorkItemRefs } : {}),
     artifact_paths: relArtifacts(dir),
-    next_action: { status: "continue", summary: nextAction || summary },
+    next_action: nextActionPayload,
   });
   writeJson(path.join(dir, "acceptance.json"), {
     ...sidecarBase(slug), source_request: sourceRequest,
@@ -1711,7 +1715,7 @@ function initSidecars(
     goal_fit: { status: "pending", summary: "Goal fit has not been verified yet." },
   });
   writeJson(path.join(dir, "handoff.json"), {
-    ...sidecarBase(slug), summary, current_state_ref: "state.json", next_steps: nextAction ? [nextAction] : [], blockers: [], warnings: [],
+    ...sidecarBase(slug), summary, current_state_ref: "state.json", next_steps: nextActionSummary ? [nextActionSummary] : [], blockers: [], warnings: [],
   });
 }
 
@@ -1982,9 +1986,16 @@ function ensureSession(p: ReturnType<typeof parseArgs>): number {
   if (!fs.existsSync(path.join(dir, "state.json")) || !fs.existsSync(path.join(dir, "acceptance.json")) || !fs.existsSync(path.join(dir, "handoff.json"))) {
     const phaseMap = entry.flowId ? resolvePhaseMap(entry.flowId, findRepoRootFromDir(dir)) : null;
     const initialPhase = Object.entries(phaseMap ?? {}).find(([, step]) => step === entry.firstStep)?.[0];
-    const nextAction = entry.flowId
+    const startCommand = `flow-agents builder-run start --session-dir .kontourai/flow-agents/${slug}`;
+    const nextAction: string | AnyObj = entry.flowId
       ? entry.flowId === "builder.build"
-        ? `Start the canonical Flow run with \`flow-agents builder-run start --session-dir .kontourai/flow-agents/${slug}\`; activate \`pull-work\` for work item ${JSON.stringify(workItem.ref)}, and satisfy the declared gate before advancing.`
+        ? {
+            status: "continue",
+            summary: `Start the canonical Flow run; activate \`pull-work\` for work item ${JSON.stringify(workItem.ref)}, and satisfy the declared gate before advancing.`,
+            skills: ["pull-work"],
+            command: startCommand,
+            enforcement: "before_tool_use",
+          }
         : `Continue at Flow step ${JSON.stringify(entry.stepId)} for work item ${JSON.stringify(workItem.ref)}; satisfy its declared gate before advancing.`
       : opt(p, "next-action", "Continue.");
     initSidecars(

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,8 +92,8 @@ 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,
@@ -82,14 +109,12 @@ export function resolveFlowFilePath(
 
   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
@@ -99,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.
@@ -120,6 +146,10 @@ export function resolveFlowFilePath(
     }
     return realPath;
   } catch {
+    if (canonicalLookup) {
+      const packaged = packagedFlowFile(kitId, flowName, repoRoot);
+      if (packaged) return packaged;
+    }
     return resolvedPath;
   }
 }

package/src/tools/build-universal-bundles.ts

@@ -337,6 +337,7 @@ function exportClaudeSettings(): string {
   hooks.UserPromptSubmit.push({ hooks: [shellHook(claudePolicy("UserPromptSubmit", "workflow-steering.js"), 30, "Running Flow Agents hook policy")] });
   hooks.PostToolUse.push({ hooks: [shellHook(claudePolicy("PostToolUse", "quality-gate.js"), 30, "Running Flow Agents hook policy")] });
   hooks.PostToolUse.push({ hooks: [shellHook(claudePolicy("PostToolUse", "evidence-capture.js"), 30, "Capturing Flow Agents command evidence")] });
+  hooks.PreToolUse.push({ hooks: [shellHook(claudePolicy("PreToolUse", "workflow-steering.js"), 30, "Enforcing Flow Agents projected action")] });
   hooks.PreToolUse.push({ hooks: [shellHook(claudePolicy("PreToolUse", "config-protection.js"), 30, "Running Flow Agents hook policy")] });
   return `${JSON.stringify({
     statusLine: { type: "command", command: 'bash -lc \'root="${CLAUDE_PROJECT_DIR:-$(pwd)}"; node "$root/scripts/statusline/flow-agents-statusline.js"\'' },
@@ -354,6 +355,7 @@ function exportCodexHooks(): string {
   hooks.SessionStart.push({ hooks: [shellHook(codexPolicy("workflow-steering.js"), 30, "Running Flow Agents hook policy")] });
   hooks.UserPromptSubmit.push({ hooks: [shellHook(codexPolicy("workflow-steering.js"), 30, "Running Flow Agents hook policy")] });
   hooks.PostToolUse.push({ hooks: [shellHook(codexPolicy("evidence-capture.js"), 30, "Capturing Flow Agents command evidence")] });
+  hooks.PreToolUse.push({ hooks: [shellHook(codexPolicy("workflow-steering.js"), 30, "Enforcing Flow Agents projected action")] });
   return `${JSON.stringify({ hooks }, null, 2)}\n`;
 }