@kontourai/flow-agents 3.4.2 → 3.4.3

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## [3.4.3](https://github.com/kontourai/flow-agents/compare/v3.4.2...v3.4.3) (2026-07-10)
+
+
+### Fixes
+
+* start Builder Flow during session creation ([#539](https://github.com/kontourai/flow-agents/issues/539)) ([10214b4](https://github.com/kontourai/flow-agents/commit/10214b478530e522f0dc50c24175d1516c113431))
+
 ## [3.4.2](https://github.com/kontourai/flow-agents/compare/v3.4.1...v3.4.2) (2026-07-10)
 
 

package/agents/dev.json

@@ -53,11 +53,6 @@
         "matcher": "*",
         "timeout_ms": 3000
       },
-      {
-        "command": "node ~/.flow-agents/scripts/hooks/run-hook.js pre:workflow-entry workflow-steering.js standard,strict",
-        "matcher": "*",
-        "timeout_ms": 5000
-      },
       {
         "command": "node ~/.flow-agents/scripts/hooks/run-hook.js pre:config-protection config-protection.js standard,strict",
         "matcher": "fs_write",

package/build/src/builder-flow-runtime.js

@@ -26,15 +26,19 @@ export async function startBuilderFlowSession(input) {
             },
         });
     }
-    return syncAndProject(context, run);
+    assertRunSubjectBinding(run, subject);
+    return syncAndProject(context, run, sidecarSnapshot);
 }
 export async function syncBuilderFlowSession(input) {
     const context = resolveSessionContext(input.sessionDir);
+    const sidecarSnapshot = readSidecarSnapshot(context);
+    const subject = workflowSubject(sidecarSnapshot.state);
     const run = await loadBuilderBuildRun({
         cwd: context.projectRoot,
         runId: context.slug,
     });
-    return syncAndProject(context, run);
+    assertRunSubjectBinding(run, subject);
+    return syncAndProject(context, run, sidecarSnapshot);
 }
 export async function recoverBuilderFlowSession(input) {
     const context = resolveSessionContext(input.sessionDir);
@@ -44,14 +48,7 @@ export async function recoverBuilderFlowSession(input) {
         cwd: context.projectRoot,
         runId: context.slug,
     });
-    if (run.state.subject !== subject) {
-        throw new BuilderBuildRunInputError("flow_run.state.subject", "must match the selected Work Item");
-    }
-    if (isRecord(run.state.params)
-        && Object.prototype.hasOwnProperty.call(run.state.params, "subject")
-        && run.state.params.subject !== subject) {
-        throw new BuilderBuildRunInputError("flow_run.state.params.subject", "must match the selected Work Item");
-    }
+    assertRunSubjectBinding(run, subject);
     const projection = projectFlowRun(context, run, sidecarSnapshot.state);
     writeProjection(context, projection, sidecarSnapshot.raw, "recovery");
     return {
@@ -76,7 +73,7 @@ export async function syncBuilderFlowSessionIfPresent(sessionDir) {
         return null;
     return syncBuilderFlowSession({ sessionDir });
 }
-async function syncAndProject(context, initial) {
+async function syncAndProject(context, initial, sidecarSnapshot) {
     let run = initial;
     let attached = false;
     const gates = openGatesForResult(run);
@@ -104,7 +101,6 @@ async function syncAndProject(context, initial) {
             }
         }
     }
-    const sidecarSnapshot = readSidecarSnapshot(context);
     const projection = projectFlowRun(context, run, sidecarSnapshot.state);
     writeProjection(context, projection, sidecarSnapshot.raw, "projection");
     return {
@@ -115,6 +111,16 @@ async function syncAndProject(context, initial) {
         attached,
     };
 }
+function assertRunSubjectBinding(run, subject) {
+    if (run.state.subject !== subject) {
+        throw new BuilderBuildRunInputError("flow_run.state.subject", "must match the selected Work Item");
+    }
+    if (isRecord(run.state.params)
+        && Object.prototype.hasOwnProperty.call(run.state.params, "subject")
+        && run.state.params.subject !== subject) {
+        throw new BuilderBuildRunInputError("flow_run.state.params.subject", "must match the selected Work Item");
+    }
+}
 function resolveSessionContext(sessionDirInput) {
     const sessionDir = path.resolve(sessionDirInput);
     const artifactRoot = path.dirname(sessionDir);

package/build/src/cli/workflow-sidecar.js

@@ -9,7 +9,7 @@ import { fileURLToPath } from "node:url";
 // ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
 import { resolveActiveFlowStep, resolveAllFlowGateExpects, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy } 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
@@ -1292,9 +1292,13 @@ async function withLock(dir, create, command, 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 = null;
+    let acquiredLock = null;
     while (true) {
         try {
             fs.mkdirSync(lockDir);
+            acquiredRoot = fs.lstatSync(dir);
+            acquiredLock = fs.lstatSync(lockDir);
             break;
         }
         catch (error) {
@@ -1326,7 +1330,29 @@ async function withLock(dir, create, command, body) {
         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, right) => 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.code !== "ENOENT") {
+                process.stderr.write(`[workflow-sidecar] lock cleanup skipped: ${error instanceof Error ? error.message : String(error)}\n`);
+            }
+        }
     }
 }
 function section(text, heading) {
@@ -1930,18 +1956,55 @@ function resolveEnsureSessionEntry(p, dir) {
     }
     return { flowId, stepId: explicitStep || firstStep, firstStep };
 }
+function assertCanonicalBuilderArtifactRoot(root) {
+    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) => {
+        try {
+            return fs.lstatSync(candidate);
+        }
+        catch (error) {
+            if (error.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"],
+    ]) {
+        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) {
     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) {
+async function ensureSession(p) {
     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
@@ -1976,7 +2039,6 @@ function ensureSession(p) {
                     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.");
@@ -1997,6 +2059,16 @@ function ensureSession(p) {
         ? 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;
 }

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

@@ -363,7 +363,6 @@ function exportClaudeSettings() {
     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"\'' },
@@ -381,7 +380,6 @@ function exportCodexHooks() {
     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`;
 }
 function copySharedContent(targetRoot, targetName, token) {

package/context/scripts/hooks/workflow-steering.js

@@ -9,8 +9,7 @@
  * survive context loss instead of relying on the model voluntarily re-reading
  * the sidecar.
  *
- * Advisory by default. A structured next action may explicitly require its
- * projected command before unrelated tool use; only that PreToolUse case blocks.
+ * Non-blocking — always exits 0.
  */
 
 'use strict';
@@ -283,32 +282,6 @@ function stateSteering(root) {
   return parts.join(' ');
 }
 
-function normalizedCommand(value) {
-  return typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '';
-}
-
-function toolCommands(input) {
-  const toolInput = input && input.tool_input && typeof input.tool_input === 'object' ? input.tool_input : {};
-  return [
-    toolInput.command,
-    toolInput.content && toolInput.content.command,
-    toolInput.args && toolInput.args.command,
-  ].map(normalizedCommand).filter(Boolean);
-}
-
-function beforeToolUseEnforcement(input, current) {
-  if (!input || input.hook_event_name !== 'PreToolUse' || !current) return null;
-  const next = current.payload && current.payload.next_action;
-  if (!next || next.status !== 'continue' || next.enforcement !== 'before_tool_use') return null;
-  const expected = normalizedCommand(next.command);
-  if (!expected) return null;
-  if (toolCommands(input).some(command => command === expected)) return null;
-  return {
-    exitCode: 2,
-    stderr: `[workflow-entry] Run the required projected action before using other tools. Run exactly: ${safeStateText(expected, 500)}`,
-  };
-}
-
 function contextMapSteering(root) {
   const mapPath = path.join(root, 'docs', 'context-map.md');
   if (!fs.existsSync(mapPath)) return '';
@@ -599,8 +572,6 @@ function run(rawInput) {
     const toolInput = input.tool_input || {};
     const root = findRepoRoot(input.cwd || process.cwd());
     const current = latestWorkflowState(root);
-    const enforcement = beforeToolUseEnforcement(input, current);
-    if (enforcement) return enforcement;
     const hints = [];
     let shouldAppendWorkflowContext = false;
 
@@ -677,14 +648,7 @@ if (require.main === module) {
     data += chunk;
   });
   process.stdin.on('end', () => {
-    const result = run(data);
-    if (result && typeof result === 'object') {
-      if (result.stderr) process.stderr.write(String(result.stderr) + (String(result.stderr).endsWith('\n') ? '' : '\n'));
-      if (Object.prototype.hasOwnProperty.call(result, 'stdout')) process.stdout.write(String(result.stdout || ''));
-      process.exitCode = Number.isInteger(result.exitCode) ? result.exitCode : 0;
-    } else {
-      process.stdout.write(String(result));
-    }
+    process.stdout.write(String(run(data)));
   });
 }
 
@@ -703,6 +667,4 @@ module.exports = {
   promptText,
   looksLikeImplementationWork,
   kitWorkflowSteering,
-  beforeToolUseEnforcement,
-  toolCommands,
 };

package/docs/spec/builder-flow-runtime.md

@@ -28,18 +28,23 @@ expectations, and Builder Kit's structured action map.
 
 ## Entry And Synchronization
 
-A Builder session must first be created at the Flow Definition's entry step by the
-workflow sidecar. Start the canonical run with:
+A Builder session is created at the Flow Definition's entry step by the workflow
+sidecar. If automatic startup reports a failure, retry the canonical operation with:
 
 ```bash
 flow-agents builder-run start --session-dir .kontourai/flow-agents/<slug>
 ```
 
-The initial sidecar projects this as `next_action.command` with
-`enforcement: "before_tool_use"`. Runtime adapters deny unrelated tool calls until
-the projected command runs. Starting the canonical run replaces that bootstrap
-action with the ordinary Flow-step projection; later actions remain advisory while
-the agent performs their declared skills and operations.
+`ensure-session --flow-id builder.build` starts or loads this canonical run before
+returning, then projects the first Flow step into the sidecar. The command remains
+the explicit recovery path if Flow startup fails after sidecar creation; the
+failure is returned to the caller and no substitute run state is invented. Runtime
+hooks keep projected actions advisory while the agent performs their declared
+skills and operations.
+
+Sidecars written by 3.4.2 may still contain `next_action.enforcement`. The 1.0
+schema accepts that deprecated field for artifact compatibility, but current
+runtime steering ignores it and does not install a PreToolUse bootstrap hook.
 
 `start` requires exactly one `state.work_item_refs` entry and uses that stable Work
 Item reference as the Flow run subject. It is idempotent for an existing canonical

package/docs/spec/runtime-hook-surface.md

@@ -123,16 +123,16 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 
 **Canonical script**: `scripts/hooks/workflow-steering.js`
 
-**Canonical trigger event**: `userPromptSubmit` and `agentSpawn`/`SessionStart` (active-goal re-grounding), `postToolUse` (after `InvokeSubagents` tool calls), and `preToolUse` when the projected `next_action` explicitly declares `enforcement: "before_tool_use"`
+**Canonical trigger event**: `userPromptSubmit` and `agentSpawn`/`SessionStart` (active-goal re-grounding), `postToolUse` (after `InvokeSubagents` tool calls)
 
 **Inputs consumed**:
 - `.kontourai/flow-agents/<slug>/state.json` — current workflow phase and status
 - `.kontourai/flow-agents/<slug>/critique.json` — open critique findings
 - `docs/context-map.md` — structure hint for repo navigation
 
-**Decision contract**: Advisory by default. It appends steering text to the agent's context via `additionalContext` and re-grounds the active workflow goal (status, phase, recorded next step) at the start of every user turn — not only for flagged/blocked states — and on `SessionStart`, which fires after context compaction and on resume. A structured `next_action` may explicitly declare a non-empty `command` with `enforcement: "before_tool_use"`; at `PreToolUse`, the canonical script then exits 2 for every unrelated call and includes the exact projected command in the denial reason. The exact projected command is allowed. This narrow bootstrap policy keeps workflow authority in the projected state instead of relying on the model voluntarily following prompt text; ordinary Flow-step projections remain advisory.
+**Decision contract**: Non-blocking. Always exits 0. Appends steering text to the agent's context via `additionalContext`. It re-grounds the active workflow goal (status, phase, recorded next step) at the start of every user turn — not only for flagged/blocked states — and on `SessionStart`, which fires after context compaction and on resume. Canonical Builder run creation is part of session orchestration rather than a model-mediated hook action.
 
-**Degradation when host lacks trigger**: If the host has no `userPromptSubmit`-equivalent hook, workflow steering is silent and the agent receives no ambient phase reminders at turn start. If the host has no block-capable `preToolUse` equivalent, explicit projected-action enforcement degrades to the same advisory command guidance. These are capability losses, not reasons to invent a second lifecycle authority. Record each missing capability in the adapter's conformance declaration.
+**Degradation when host lacks trigger**: If the host has no `userPromptSubmit`-equivalent hook, workflow steering is silent. The agent receives no ambient phase reminders at turn start. This is a capability loss, not a blocking failure. Log the gap in the adapter's conformance declaration.
 
 **Codex live hook influence caveat**: Codex hook influence on live sessions is limited — the agent may not honor all injected context. The hook influence behavioral cases in `evals/fixtures/hook-influence/cases.json` document which behaviors are expected (`agent_must_do`) versus which may only be soft guidance. Adapters on similar runtimes should apply the same classification.
 
@@ -550,7 +550,7 @@ For structured `run()` responses (native import form), the return value is:
 | config-protection | Fail-closed (exit 2 on protected file) | Yes — hook runtime errors exit 0 | Yes (preToolUse) |
 | quality-gate | Fail-open (exit 0 always) | Yes | No |
 | stop-goal-fit | Engine default warn (fail-open); blocks in `FLOW_AGENTS_GOAL_FIT_MODE=block` (shipped L2 default) | Yes — hook runtime errors exit 0 | Yes (stop, block mode) |
-| workflow-steering | Advisory; exit 2 only for an explicit `before_tool_use` projected command | Yes — hook runtime and malformed-state errors exit 0 | Yes (preToolUse, explicit projection only) |
+| workflow-steering | Fail-open (exit 0 always) | Yes | No |
 | evidence-capture | Fail-open (exit 0 always) | Yes — capture errors never block or corrupt the log | No |
 
 **Telemetry**: Always fail-open. Hook runtime errors in telemetry scripts must never block agent work.

package/evals/integration/test_builder_entry_enforcement.sh

@@ -17,6 +17,100 @@ WRITER="workflow-sidecar"
 
 echo "=== Builder workflow entry enforcement ==="
 
+NONCANONICAL_ROOT="$TMP/noncanonical-root"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$NONCANONICAL_ROOT" \
+  --task-slug noncanonical \
+  --title "Noncanonical root" \
+  --summary "Builder state must use the product artifact root." \
+  --flow-id builder.build >"$TMP/noncanonical.out" 2>&1; then
+  fail "noncanonical Builder artifact root should be rejected"
+elif [[ ! -e "$NONCANONICAL_ROOT" ]] \
+  && grep -q 'requires --artifact-root <project>/.kontourai/flow-agents' "$TMP/noncanonical.out"; then
+  pass "noncanonical Builder artifact root is rejected before any sidecar write"
+else
+  fail "noncanonical Builder root left partial state or the wrong diagnostic: $(cat "$TMP/noncanonical.out")"
+fi
+
+SYMLINK_PROJECT="$TMP/symlink-project"
+SYMLINK_EXTERNAL="$TMP/symlink-external"
+mkdir -p "$SYMLINK_PROJECT/.kontourai" "$SYMLINK_EXTERNAL"
+ln -s "$SYMLINK_EXTERNAL" "$SYMLINK_PROJECT/.kontourai/flow-agents"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$SYMLINK_PROJECT/.kontourai/flow-agents" \
+  --task-slug symlink-root \
+  --title "Symlink root" \
+  --summary "Builder state must not escape the project." \
+  --flow-id builder.build >"$TMP/symlink-root.out" 2>&1; then
+  fail "symlinked Builder artifact root should be rejected"
+elif [[ -z "$(find "$SYMLINK_EXTERNAL" -mindepth 1 -print -quit)" ]] \
+  && grep -q 'requires a non-symlink Flow Agents artifact root' "$TMP/symlink-root.out"; then
+  pass "symlinked Builder artifact root is rejected before any external write"
+else
+  fail "symlinked Builder root wrote externally or returned the wrong diagnostic: $(cat "$TMP/symlink-root.out")"
+fi
+
+RACE_PROJECT="$TMP/race-project"
+RACE_ROOT="$RACE_PROJECT/.kontourai/flow-agents"
+RACE_MOVED="$RACE_PROJECT/.kontourai/flow-agents-acquired"
+RACE_EXTERNAL="$TMP/race-external"
+mkdir -p "$RACE_ROOT" "$RACE_EXTERNAL"
+FLOW_AGENTS_WORKFLOW_SIDECAR_LOCK_DELAY=1 flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$RACE_ROOT" \
+  --task-slug lock-swap \
+  --title "Lock swap" \
+  --summary "Lock cleanup must remain on the acquired root." \
+  --flow-id builder.build >"$TMP/lock-swap.out" 2>&1 &
+RACE_PID=$!
+node - "$RACE_ROOT/.workflow-sidecar.lockdir" <<'NODE'
+const fs = require('node:fs');
+const lock = process.argv[2];
+const deadline = Date.now() + 5000;
+(function wait() {
+  if (fs.existsSync(lock)) process.exit(0);
+  if (Date.now() > deadline) process.exit(1);
+  setTimeout(wait, 10);
+})();
+NODE
+mv "$RACE_ROOT" "$RACE_MOVED"
+mkdir -p "$RACE_EXTERNAL/.workflow-sidecar.lockdir"
+printf 'outside must survive\n' >"$RACE_EXTERNAL/.workflow-sidecar.lockdir/sentinel"
+ln -s "$RACE_EXTERNAL" "$RACE_ROOT"
+set +e
+wait "$RACE_PID"
+RACE_STATUS=$?
+set -e
+if [[ "$RACE_STATUS" -ne 0 ]] \
+  && [[ -f "$RACE_EXTERNAL/.workflow-sidecar.lockdir/sentinel" ]] \
+  && [[ -d "$RACE_MOVED/.workflow-sidecar.lockdir" ]] \
+  && grep -q 'lock cleanup skipped because root or lock identity changed' "$TMP/lock-swap.out"; then
+  pass "lock cleanup refuses a swapped root and preserves external content"
+else
+  fail "lock cleanup followed a swapped root or lost its identity diagnostic: $(cat "$TMP/lock-swap.out")"
+fi
+
+RELEASE_STATE="$TMP/release-3.4.2-state.json"
+cat >"$RELEASE_STATE" <<'JSON'
+{
+  "schema_version": "1.0",
+  "task_slug": "release-3-4-2",
+  "status": "new",
+  "phase": "pickup",
+  "updated_at": "2026-07-10T00:00:00Z",
+  "next_action": {
+    "status": "continue",
+    "summary": "Start the canonical Flow run.",
+    "command": "flow-agents builder-run start --session-dir .kontourai/flow-agents/release-3-4-2",
+    "enforcement": "before_tool_use"
+  }
+}
+JSON
+if flow_agents_node "validate-workflow-artifacts" --skip-markdown-validation "$RELEASE_STATE" >/dev/null 2>&1; then
+  pass "3.4.2 sidecars remain schema-valid while deprecated enforcement is ignored"
+else
+  fail "3.4.2 sidecar compatibility regressed"
+fi
+
 REFUSED_ROOT="$TMP/refused/.kontourai/flow-agents"
 if flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$REFUSED_ROOT" \
@@ -63,18 +157,20 @@ const root = process.argv[2];
 const current = JSON.parse(fs.readFileSync(path.join(root, 'current.json'), 'utf8'));
 const state = JSON.parse(fs.readFileSync(path.join(root, 'local-request', 'state.json'), 'utf8'));
 const workItem = JSON.parse(fs.readFileSync(path.join(root, 'local-request', 'work-item.json'), 'utf8'));
+const flowState = JSON.parse(fs.readFileSync(path.join(path.dirname(root), 'flow', 'runs', 'local-request', 'state.json'), 'utf8'));
 if (current.active_flow_id !== 'builder.build' || current.active_step_id !== 'pull-work') process.exit(1);
 if (state.status !== 'new' || state.phase !== 'pickup') process.exit(1);
 if (JSON.stringify(state.work_item_refs) !== JSON.stringify(['local:local-request'])) process.exit(1);
 if (workItem.id !== 'local-request' || workItem.title !== 'Local request') process.exit(1);
 if (workItem.source_provider?.kind !== 'local' || workItem.source_provider?.path !== 'work-item.json') process.exit(1);
-if (state.next_action?.command !== 'flow-agents builder-run start --session-dir .kontourai/flow-agents/local-request') process.exit(1);
-if (state.next_action?.enforcement !== 'before_tool_use') process.exit(1);
+if (flowState.current_step !== 'pull-work' || flowState.subject !== 'local:local-request') process.exit(1);
+if (state.flow_run?.current_step !== 'pull-work') process.exit(1);
 if (JSON.stringify(state.next_action?.skills) !== JSON.stringify(['pull-work'])) process.exit(1);
-if (!state.next_action?.summary?.includes('`pull-work`')) process.exit(1);
+if (!state.next_action?.command?.includes('builder-run sync')) process.exit(1);
+if ('enforcement' in state.next_action) process.exit(1);
 NODE
   then
-    pass "providerless request creates a local Work Item and starts at pull-work"
+    pass "providerless request creates a local Work Item and canonical Flow run at pull-work"
   else
     fail "local Work Item or first-step state is invalid"
   fi
@@ -83,7 +179,15 @@ else
 fi
 
 LOCAL_SESSION="$LOCAL_ROOT/local-request"
-if flow_agents_node builder-run start --session-dir "$LOCAL_SESSION" >"$TMP/builder-start.out" 2>&1 \
+FLOW_DIGEST_BEFORE="$(find "$TMP/local/.kontourai/flow/runs/local-request" -type f -print0 | sort -z | xargs -0 shasum -a 256)"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$LOCAL_ROOT" \
+  --task-slug local-request \
+  --title "Local request" \
+  --summary "Providerless work still needs an anchor." \
+  --flow-id builder.build \
+  --timestamp "2026-07-10T00:00:00Z" >"$TMP/builder-ensure-again.out" 2>&1 \
+  && [[ "$FLOW_DIGEST_BEFORE" == "$(find "$TMP/local/.kontourai/flow/runs/local-request" -type f -print0 | sort -z | xargs -0 shasum -a 256)" ]] \
   && node - "$TMP/local" "$LOCAL_SESSION" <<'NODE'
 const fs = require('node:fs');
 const path = require('node:path');
@@ -97,9 +201,36 @@ if (JSON.stringify(sidecar.next_action?.skills) !== JSON.stringify(['pull-work']
 if (!sidecar.next_action?.command?.includes('builder-run sync')) process.exit(1);
 NODE
 then
-  pass "small-model entry command creates canonical Flow run and projects pull-work action"
+  pass "repeated ensure-session loads the canonical Flow run without resetting its history"
+else
+  fail "canonical Builder ensure was not idempotent: $(cat "$TMP/builder-ensure-again.out")"
+fi
+
+BROKEN_PROJECT="$TMP/broken-start"
+BROKEN_ROOT="$BROKEN_PROJECT/.kontourai/flow-agents"
+mkdir -p "$BROKEN_PROJECT/.kontourai"
+printf 'not a run-store directory\n' > "$BROKEN_PROJECT/.kontourai/flow"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$BROKEN_ROOT" \
+  --task-slug broken-start \
+  --title "Broken start" \
+  --summary "Flow startup must fail visibly." \
+  --flow-id builder.build >"$TMP/broken-start.out" 2>&1; then
+  fail "invalid canonical Flow startup should fail ensure-session"
+elif [[ -f "$BROKEN_ROOT/broken-start/state.json" ]] \
+  && [[ ! -e "$BROKEN_PROJECT/.kontourai/flow/runs/broken-start" ]] \
+  && grep -q 'canonical Builder Flow run did not start' "$TMP/broken-start.out" \
+  && grep -q 'flow-agents builder-run start --session-dir .kontourai/flow-agents/broken-start' "$TMP/broken-start.out" \
+  && node - "$BROKEN_ROOT/broken-start/state.json" <<'NODE'
+const fs = require('node:fs');
+const state = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+if (state.flow_run) process.exit(1);
+if (!state.next_action?.command?.includes('builder-run start')) process.exit(1);
+NODE
+then
+  pass "failed canonical startup is visible and leaves only retryable sidecar guidance"
 else
-  fail "canonical Builder run did not start or project correctly: $(cat "$TMP/builder-start.out")"
+  fail "failed canonical startup forged state or lost recovery guidance: $(cat "$TMP/broken-start.out")"
 fi
 
 if flow_agents_node "$WRITER" record-gate-claim "$LOCAL_SESSION" \

package/evals/integration/test_builder_step_producers.sh

@@ -139,7 +139,7 @@ test_produce_claim() {
 
   local slug
   slug="$(echo "prod-$step-$expectation" | tr '/' '-' | tr '.' '-')"
-  local aroot="$TMP/$slug"
+  local aroot="$TMP/$slug/.kontourai/flow-agents"
   setup_session_for_produce "$aroot" "$slug" "$step"
 
   if flow_agents_node "workflow-sidecar" record-gate-claim "$aroot/$slug" \

package/evals/integration/test_bundle_install.sh

@@ -592,14 +592,14 @@ function hasWorkflowSteering(file, ...eventNames) {
 }
 for (const file of process.argv.slice(2)) {
   if (!hasWorkflowSteering(file, "UserPromptSubmit", "userPromptSubmit")) throw new Error(`missing prompt-submit workflow steering: ${file}`);
-  if (!hasWorkflowSteering(file, "PreToolUse", "preToolUse")) throw new Error(`missing pre-tool workflow entry enforcement: ${file}`);
+  if (hasWorkflowSteering(file, "PreToolUse", "preToolUse")) throw new Error(`workflow bootstrap must not be model-mediated at pre-tool time: ${file}`);
 }
 console.log("ok");
 NODE
 then
-  _pass "installed bundles wire prompt-submit steering and pre-tool entry enforcement across Claude Code, Codex, and Kiro"
+  _pass "installed bundles keep workflow steering advisory and session bootstrap product-owned"
 else
-  _fail "installed bundles do not wire workflow steering consistently"
+  _fail "installed bundles do not wire prompt-submit workflow steering consistently"
 fi
 
 if [[ -f "$OPENCODE_DEST/.opencode/plugins/flow-agents.js" ]]   && node - "$OPENCODE_DEST/.opencode/plugins/flow-agents.js" <<'NODE'

package/evals/integration/test_current_json_per_actor.sh

@@ -117,7 +117,7 @@ fi
 # --- 2. actor A's own current resolution is unaffected by actor B's later call (AC7) ----------
 echo "--- 2. actor A's current resolution survives actor B's later, unrelated ensure-session (AC7) ---"
 
-AC7_ROOT="$TMPDIR_EVAL/ac7-artifact-root"
+AC7_ROOT="$TMPDIR_EVAL/ac7-project/.kontourai/flow-agents"
 
 flow_agents_node "workflow-sidecar" ensure-session \
   --artifact-root "$AC7_ROOT" \
@@ -370,7 +370,7 @@ set -e
 # --- 5. record-gate-claim resolves A's own per-actor flow/step, not B's legacy pointer (AC11) --
 echo "--- 5. record-gate-claim resolves A's own per-actor flow/step, not B's legacy pointer (AC11) ---"
 
-AC11_ROOT="$TMPDIR_EVAL/ac11-artifact-root"
+AC11_ROOT="$TMPDIR_EVAL/ac11-project/.kontourai/flow-agents"
 
 flow_agents_node "workflow-sidecar" ensure-session \
   --artifact-root "$AC11_ROOT" \