@kontourai/flow-agents 3.4.1 → 3.4.3

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 {
@@ -131,6 +172,38 @@ test("small-model client can start and advance from projected actions without ch
   assert.equal(duplicate.run.manifest.evidence.length, advanced.run.manifest.evidence.length);
 });
 
+test("automatic start refuses a slug-bound run for another Work Item without mutation", async () => {
+  const session = makeSession("start-subject-mismatch");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const sidecar = readJson(path.join(session.sessionDir, "state.json"));
+  sidecar.work_item_refs = ["local:work-item/other"];
+  writeJson(path.join(session.sessionDir, "state.json"), sidecar);
+  const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+  const beforeProjection = snapshotProjectionTargets(session);
+
+  await assert.rejects(
+    () => startBuilderFlowSession({ sessionDir: session.sessionDir }),
+    /flow_run\.state\.subject.*selected Work Item/,
+  );
+  assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+  assert.deepEqual(snapshotProjectionTargets(session), beforeProjection);
+});
+
+test("automatic start refuses a sidecar changed after its immutable subject snapshot", async () => {
+  const session = makeSession("start-sidecar-race");
+  await startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const beforeFlow = snapshotTree(runDir(session.slug, session.projectRoot));
+  const startup = startBuilderFlowSession({ sessionDir: session.sessionDir });
+  const changed = readJson(path.join(session.sessionDir, "state.json"));
+  changed.next_action = { status: "continue", summary: "concurrent change" };
+  writeJson(path.join(session.sessionDir, "state.json"), changed);
+  const beforeProjection = snapshotProjectionTargets(session);
+
+  await assert.rejects(() => startup, /state\.json.*changed during projection/);
+  assert.deepEqual(snapshotTree(runDir(session.slug, session.projectRoot)), beforeFlow);
+  assert.deepEqual(snapshotProjectionTargets(session), beforeProjection);
+});
+
 test("wrong workflow subject is rejected before canonical Flow mutation", async () => {
   const session = makeSession("wrong-subject");
   await startBuilderFlowSession({ sessionDir: session.sessionDir });
@@ -210,4 +283,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/workflow-sidecar.ts

@@ -9,7 +9,7 @@ import { fileURLToPath } from "node:url";
 // ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
 import { resolveActiveFlowStep, resolveAllFlowGateExpects, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy, type ActiveFlowStep } from "../lib/flow-resolver.js";
 import { defaultArtifactRootForRead, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
-import { syncBuilderFlowSessionIfPresent } from "../builder-flow-runtime.js";
+import { startBuilderFlowSession, syncBuilderFlowSessionIfPresent } from "../builder-flow-runtime.js";
 // #291 Wave 1 Task 1.1 exports: ensure-session's ownership guard reuses the EXACT same
 // assignment ⋈ liveness join / claim / supersede logic #290 already ships for the
 // `assignment-provider` CLI, rather than reimplementing a second, parallel join (static ESM
@@ -1312,8 +1312,15 @@ async function withLock<T>(dir: string, create: boolean, command: string, body:
   const lockDir = path.join(dir, ".workflow-sidecar.lockdir");
   const staleMs = Number(process.env.FLOW_AGENTS_WORKFLOW_SIDECAR_STALE_LOCK_MS ?? 5 * 60 * 1000);
   const deadline = Date.now() + 30000;
+  let acquiredRoot: fs.Stats | null = null;
+  let acquiredLock: fs.Stats | null = null;
   while (true) {
-    try { fs.mkdirSync(lockDir); break; }
+    try {
+      fs.mkdirSync(lockDir);
+      acquiredRoot = fs.lstatSync(dir);
+      acquiredLock = fs.lstatSync(lockDir);
+      break;
+    }
     catch (error) {
       const lockError = error as NodeJS.ErrnoException;
       if (lockError.code !== "EEXIST") {
@@ -1338,7 +1345,28 @@ async function withLock<T>(dir: string, create: boolean, command: string, body:
     if (delay) await new Promise((resolve) => setTimeout(resolve, Number(delay) * 1000));
     return await body();
   } finally {
-    fs.rmSync(lockDir, { recursive: true, force: true });
+    try {
+      const currentRoot = fs.lstatSync(dir);
+      const currentLock = fs.lstatSync(lockDir);
+      const sameIdentity = (left: fs.Stats, right: fs.Stats): boolean =>
+        left.dev === right.dev && left.ino === right.ino;
+      if (acquiredRoot
+        && acquiredLock
+        && !currentRoot.isSymbolicLink()
+        && currentRoot.isDirectory()
+        && !currentLock.isSymbolicLink()
+        && currentLock.isDirectory()
+        && sameIdentity(currentRoot, acquiredRoot)
+        && sameIdentity(currentLock, acquiredLock)) {
+        fs.rmdirSync(lockDir);
+      } else {
+        process.stderr.write(`[workflow-sidecar] lock cleanup skipped because root or lock identity changed: ${lockDir}\n`);
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        process.stderr.write(`[workflow-sidecar] lock cleanup skipped: ${error instanceof Error ? error.message : String(error)}\n`);
+      }
+    }
   }
 }
 
@@ -1661,7 +1689,7 @@ function initSidecars(
   slug: string,
   sourceRequest: string,
   summary: string,
-  nextAction: string,
+  nextAction: string | AnyObj,
   timestamp: string,
   markdown?: string,
   workItemRefs: string[] = [],
@@ -1698,12 +1726,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 +1743,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: [],
   });
 }
 
@@ -1943,19 +1975,53 @@ function resolveEnsureSessionEntry(p: ReturnType<typeof parseArgs>, dir: string)
   return { flowId, stepId: explicitStep || firstStep, firstStep };
 }
 
+function assertCanonicalBuilderArtifactRoot(root: string): void {
+  const kontouraiRoot = path.dirname(root);
+  const projectRoot = path.dirname(kontouraiRoot);
+  if (path.basename(root) !== "flow-agents" || path.basename(kontouraiRoot) !== ".kontourai") {
+    die("ensure-session --flow-id builder.build requires --artifact-root <project>/.kontourai/flow-agents");
+  }
+
+  const statIfPresent = (candidate: string): fs.Stats | null => {
+    try {
+      return fs.lstatSync(candidate);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+  };
+  const projectStat = statIfPresent(projectRoot);
+  if (projectStat && (projectStat.isSymbolicLink() || !projectStat.isDirectory())) {
+    die(`ensure-session --flow-id builder.build requires a non-symlink project root: ${projectRoot}`);
+  }
+  const realProjectRoot = projectStat ? fs.realpathSync(projectRoot) : projectRoot;
+  for (const [candidate, expected, label] of [
+    [kontouraiRoot, path.join(realProjectRoot, ".kontourai"), ".kontourai root"],
+    [root, path.join(realProjectRoot, ".kontourai", "flow-agents"), "Flow Agents artifact root"],
+  ] as const) {
+    const stat = statIfPresent(candidate);
+    if (!stat) continue;
+    if (stat.isSymbolicLink() || !stat.isDirectory() || fs.realpathSync(candidate) !== expected) {
+      die(`ensure-session --flow-id builder.build requires a non-symlink ${label}: ${candidate}`);
+    }
+  }
+}
+
 function preflightEnsureSession(p: ReturnType<typeof parseArgs>): void {
   const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
   const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
   const dir = sessionDirFor(root, slug);
-  resolveEnsureSessionEntry(p, dir);
+  const entry = resolveEnsureSessionEntry(p, dir);
+  if (entry.flowId === "builder.build") assertCanonicalBuilderArtifactRoot(root);
   sessionWorkItem(p, slug, dir);
 }
 
-function ensureSession(p: ReturnType<typeof parseArgs>): number {
+async function ensureSession(p: ReturnType<typeof parseArgs>): Promise<number> {
   const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
   const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
   const dir = sessionDirFor(root, slug);
   const entry = resolveEnsureSessionEntry(p, dir);
+  if (entry.flowId === "builder.build") assertCanonicalBuilderArtifactRoot(root);
   const workItem = sessionWorkItem(p, slug, dir);
   // #291 Wave 2 Task 2.1 (§3, §4): resolve the actor ONCE, then run the ownership guard BEFORE
   // any directory/file is created — a refusal must never leave a stray empty session dir. Reused
@@ -1982,9 +2048,15 @@ 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,
+          }
         : `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(
@@ -2014,6 +2086,15 @@ function ensureSession(p: ReturnType<typeof parseArgs>): number {
     ? persistedCurrent.active_step_id
     : entry.stepId;
   writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", entry.flowId || undefined, resumedStep || undefined, actorResolution.unresolved ? undefined : actorResolution.branchActorKey);
+  if (entry.flowId === "builder.build") {
+    try {
+      await startBuilderFlowSession({ sessionDir: dir });
+    } catch (error) {
+      const retry = `flow-agents builder-run start --session-dir .kontourai/flow-agents/${slug}`;
+      process.stderr.write(`[ensure-session] canonical Builder Flow run did not start; the sidecar remains retryable. Run: ${retry}\n`);
+      throw error;
+    }
+  }
   console.log(dir);
   return 0;
 }