@kontourai/flow-agents 3.4.1 → 3.4.3

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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)
+
+
+### Fixes
+
+* enforce canonical Builder entry action ([#536](https://github.com/kontourai/flow-agents/issues/536)) ([bab5dfe](https://github.com/kontourai/flow-agents/commit/bab5dfe419a42b137dcb79bd276edf3268c5fb23))
+
 ## [3.4.1](https://github.com/kontourai/flow-agents/compare/v3.4.0...v3.4.1) (2026-07-10)
 
 

package/build/src/builder-flow-runtime.d.ts

@@ -12,5 +12,6 @@ export interface BuilderFlowSessionResult {
 }
 export declare function startBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
 export declare function syncBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
+export declare function recoverBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult>;
 export declare function syncBuilderFlowSessionIfPresent(sessionDir: string): Promise<BuilderFlowSessionResult | null>;
 export {};

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

@@ -5,8 +5,8 @@ import { expectationsForGate, openGates, readJson, runDir, sha256File, } from "@
 import { BUILDER_BUILD_FLOW_ID, BuilderBuildRunInputError, evaluateBuilderBuildRun, loadBuilderBuildRun, startBuilderBuildRun, } from "./builder-flow-run-adapter.js";
 export async function startBuilderFlowSession(input) {
     const context = resolveSessionContext(input.sessionDir);
-    const sidecarState = readSidecarState(context);
-    const subject = workflowSubject(sidecarState);
+    const sidecarSnapshot = readSidecarSnapshot(context);
+    const subject = workflowSubject(sidecarSnapshot.state);
     let run;
     try {
         run = await loadBuilderBuildRun({
@@ -26,15 +26,38 @@ 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);
+    const sidecarSnapshot = readSidecarSnapshot(context);
+    const subject = workflowSubject(sidecarSnapshot.state);
+    const run = await loadBuilderBuildRun({
+        cwd: context.projectRoot,
+        runId: context.slug,
+    });
+    assertRunSubjectBinding(run, subject);
+    const projection = projectFlowRun(context, run, sidecarSnapshot.state);
+    writeProjection(context, projection, sidecarSnapshot.raw, "recovery");
+    return {
+        sessionDir: context.sessionDir,
+        projectRoot: context.projectRoot,
+        run,
+        projection,
+        attached: false,
+    };
 }
 export async function syncBuilderFlowSessionIfPresent(sessionDir) {
     let context;
@@ -50,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);
@@ -78,8 +101,8 @@ async function syncAndProject(context, initial) {
             }
         }
     }
-    const projection = projectFlowRun(context, run);
-    writeProjection(context, projection);
+    const projection = projectFlowRun(context, run, sidecarSnapshot.state);
+    writeProjection(context, projection, sidecarSnapshot.raw, "projection");
     return {
         sessionDir: context.sessionDir,
         projectRoot: context.projectRoot,
@@ -88,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);
@@ -95,6 +128,7 @@ function resolveSessionContext(sessionDirInput) {
     if (path.basename(artifactRoot) !== "flow-agents" || path.basename(kontouraiRoot) !== ".kontourai") {
         throw new BuilderBuildRunInputError("sessionDir", "must be .kontourai/flow-agents/<slug>");
     }
+    assertSafeDirectory(sessionDir, artifactRoot, "sessionDir");
     const slug = path.basename(sessionDir);
     if (!slug || slug === "." || slug === "..") {
         throw new BuilderBuildRunInputError("sessionDir", "must name a session");
@@ -103,6 +137,7 @@ function resolveSessionContext(sessionDirInput) {
     if (!fs.existsSync(stateFile)) {
         throw new BuilderBuildRunInputError("sessionDir", "must contain state.json");
     }
+    assertSafeFile(stateFile, sessionDir, "state.json");
     return {
         sessionDir,
         artifactRoot,
@@ -112,18 +147,21 @@ function resolveSessionContext(sessionDirInput) {
         bundleFile: path.join(sessionDir, "trust.bundle"),
     };
 }
-function readSidecarState(context) {
-    const value = JSON.parse(fs.readFileSync(context.stateFile, "utf8"));
+function readSidecarSnapshot(context) {
+    assertSafeFile(context.stateFile, context.sessionDir, "state.json");
+    const raw = fs.readFileSync(context.stateFile, "utf8");
+    const value = JSON.parse(raw);
     if (!isRecord(value) || value.task_slug !== context.slug) {
         throw new BuilderBuildRunInputError("sessionDir", "state.json task_slug must match the session directory");
     }
-    return value;
+    return { state: value, raw };
 }
 function workflowSubject(state) {
-    const refs = Array.isArray(state.work_item_refs)
-        ? state.work_item_refs.filter((value) => typeof value === "string" && value.length > 0)
-        : [];
-    if (refs.length !== 1) {
+    const refs = state.work_item_refs;
+    if (!Array.isArray(refs)
+        || refs.length !== 1
+        || typeof refs[0] !== "string"
+        || refs[0].trim().length === 0) {
         throw new BuilderBuildRunInputError("state.work_item_refs", "must contain exactly one selected Work Item for builder.build");
     }
     return refs[0];
@@ -174,8 +212,7 @@ function workflowSubjectRef(claim) {
 function manifestEvidence(manifest) {
     return Array.isArray(manifest.evidence) ? manifest.evidence.filter(isRecord) : [];
 }
-function projectFlowRun(context, run) {
-    const sidecar = readSidecarState(context);
+function projectFlowRun(context, run, sidecar) {
     const definition = JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8"));
     const gates = openGates(definition, run.state);
     const complete = run.state.status === "completed";
@@ -227,25 +264,150 @@ function projectFlowRun(context, run) {
         next_action: nextAction,
     };
 }
-function writeProjection(context, projection) {
-    fs.writeFileSync(context.stateFile, `${JSON.stringify(projection, null, 2)}\n`);
-    const pointerFiles = [path.join(context.artifactRoot, "current.json")];
+function writeProjection(context, projection, expectedStateRaw, operation) {
+    const prepared = prepareProjectionWrites(context, projection, expectedStateRaw, operation);
+    assertProjectionTargetsUnchanged(context, prepared, operation);
+    for (const write of prepared.writes)
+        writeExistingFileNoFollow(write.file, write.content);
+}
+function prepareProjectionWrites(context, projection, expectedStateRaw, operation) {
+    const targets = [];
+    const writes = [];
+    const stateTarget = readProjectionTarget(context.stateFile, context.sessionDir, "state.json");
+    targets.push(stateTarget);
+    if (stateTarget.raw !== expectedStateRaw) {
+        throw new BuilderBuildRunInputError("state.json", `changed during ${operation}`);
+    }
+    writes.push({ file: context.stateFile, content: `${JSON.stringify(projection, null, 2)}\n` });
+    const pointerFiles = [];
+    const globalPointer = path.join(context.artifactRoot, "current.json");
+    const globalTarget = readOptionalProjectionTarget(globalPointer, context.artifactRoot, "current.json");
+    targets.push(globalTarget);
+    if (globalTarget.raw !== null)
+        pointerFiles.push(globalPointer);
     const actorRoot = path.join(context.artifactRoot, "current");
-    if (fs.existsSync(actorRoot)) {
-        pointerFiles.push(...fs.readdirSync(actorRoot)
-            .filter((name) => name.endsWith(".json"))
-            .map((name) => path.join(actorRoot, name)));
+    let actorEntries = null;
+    if (pathExistsNoFollow(actorRoot)) {
+        assertSafeDirectory(actorRoot, context.artifactRoot, "current directory");
+        actorEntries = fs.readdirSync(actorRoot).sort();
+        for (const name of actorEntries) {
+            const file = path.join(actorRoot, name);
+            const stat = fs.lstatSync(file);
+            if (stat.isSymbolicLink()) {
+                throw new BuilderBuildRunInputError("projection target", `current/${name} must not be a symbolic link`);
+            }
+            if (!name.endsWith(".json"))
+                continue;
+            if (!stat.isFile()) {
+                throw new BuilderBuildRunInputError("projection target", `current/${name} must be a regular file`);
+            }
+            const target = readProjectionTarget(file, actorRoot, `current/${name}`);
+            targets.push(target);
+            pointerFiles.push(file);
+        }
     }
     for (const file of pointerFiles) {
-        if (!fs.existsSync(file))
-            continue;
-        const pointer = JSON.parse(fs.readFileSync(file, "utf8"));
+        const target = targets.find((candidate) => candidate.file === file);
+        const pointer = parseProjectionTarget(target);
         if (!isRecord(pointer) || pointer.active_slug !== context.slug)
             continue;
-        pointer.active_flow_id = BUILDER_BUILD_FLOW_ID;
-        pointer.active_step_id = projection.flow_run.current_step;
-        pointer.updated_at = projection.updated_at;
-        fs.writeFileSync(file, `${JSON.stringify(pointer, null, 2)}\n`);
+        const output = {
+            ...pointer,
+            active_flow_id: BUILDER_BUILD_FLOW_ID,
+            active_step_id: projection.flow_run.current_step,
+            updated_at: projection.updated_at,
+        };
+        writes.push({ file, content: `${JSON.stringify(output, null, 2)}\n` });
+    }
+    return { targets, actorEntries, writes };
+}
+function assertProjectionTargetsUnchanged(context, prepared, operation) {
+    const actorRoot = path.join(context.artifactRoot, "current");
+    const currentActorEntries = pathExistsNoFollow(actorRoot)
+        ? (assertSafeDirectory(actorRoot, context.artifactRoot, "current directory"), fs.readdirSync(actorRoot).sort())
+        : null;
+    if (JSON.stringify(currentActorEntries) !== JSON.stringify(prepared.actorEntries)) {
+        throw new BuilderBuildRunInputError("current", `directory changed during ${operation}`);
+    }
+    for (const target of prepared.targets) {
+        const current = readOptionalProjectionTarget(target.file, target.root, target.field);
+        if (current.raw !== target.raw) {
+            throw new BuilderBuildRunInputError(target.field, `changed during ${operation}`);
+        }
+    }
+}
+function readOptionalProjectionTarget(file, root, field) {
+    if (!pathExistsNoFollow(file))
+        return { file, raw: null, root, field };
+    return readProjectionTarget(file, root, field);
+}
+function readProjectionTarget(file, root, field) {
+    assertSafeFile(file, root, field);
+    return { file, raw: fs.readFileSync(file, "utf8"), root, field };
+}
+function parseProjectionTarget(target) {
+    try {
+        return JSON.parse(target.raw);
+    }
+    catch (error) {
+        throw new BuilderBuildRunInputError("projection target", `${target.field} must contain valid JSON: ${error instanceof Error ? error.message : String(error)}`);
+    }
+}
+function assertSafeDirectory(directory, root, field) {
+    if (!pathExistsNoFollow(directory)) {
+        throw new BuilderBuildRunInputError(field, "must exist");
+    }
+    const stat = fs.lstatSync(directory);
+    if (stat.isSymbolicLink()) {
+        throw new BuilderBuildRunInputError(field, "must not be a symbolic link");
+    }
+    if (!stat.isDirectory()) {
+        throw new BuilderBuildRunInputError(field, "must be a directory");
+    }
+    assertContainedPath(directory, root, field);
+}
+function pathExistsNoFollow(candidate) {
+    try {
+        fs.lstatSync(candidate);
+        return true;
+    }
+    catch (error) {
+        if (isRecord(error) && error.code === "ENOENT")
+            return false;
+        throw error;
+    }
+}
+function assertSafeFile(file, root, field) {
+    const stat = fs.lstatSync(file);
+    if (stat.isSymbolicLink()) {
+        throw new BuilderBuildRunInputError(field, "must not be a symbolic link");
+    }
+    if (!stat.isFile()) {
+        throw new BuilderBuildRunInputError(field, "must be a regular file");
+    }
+    assertContainedPath(file, root, field);
+}
+function assertContainedPath(candidate, root, field) {
+    if (!pathIsWithin(candidate, root)) {
+        throw new BuilderBuildRunInputError(field, "must remain within its expected artifact root");
+    }
+    const realCandidate = fs.realpathSync(candidate);
+    const realRoot = fs.realpathSync(root);
+    if (!pathIsWithin(realCandidate, realRoot)) {
+        throw new BuilderBuildRunInputError(field, "must not escape its expected artifact root");
+    }
+}
+function pathIsWithin(candidate, root) {
+    const relative = path.relative(root, candidate);
+    return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+function writeExistingFileNoFollow(file, content) {
+    const descriptor = fs.openSync(file, fs.constants.O_WRONLY | fs.constants.O_TRUNC | fs.constants.O_NOFOLLOW);
+    try {
+        fs.writeFileSync(descriptor, content);
+    }
+    finally {
+        fs.closeSync(descriptor);
     }
 }
 function stepAction(stepId) {

package/build/src/cli/builder-run.js

@@ -1,20 +1,29 @@
 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) {
     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/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) {
@@ -1692,12 +1718,16 @@ function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp,
     // 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,
@@ -1705,7 +1735,7 @@ function initSidecars(dir, slug, sourceRequest, summary, nextAction, timestamp,
         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: [],
     });
 }
 /** Read a `--*-json` flag's value as a file path (or `-` for stdin), mirroring
@@ -1926,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
@@ -1964,9 +2031,15 @@ function ensureSession(p) {
     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 startCommand = `flow-agents builder-run start --session-dir .kontourai/flow-agents/${slug}`;
         const nextAction = 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(dir, slug, opt(p, "source-request"), opt(p, "summary"), nextAction, timestamp, md, [workItem.ref], initialPhase ? { status: "new", phase: initialPhase } : undefined);
@@ -1986,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/docs/spec/builder-flow-runtime.md

@@ -28,13 +28,24 @@ 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>
 ```
 
+`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
 run. A direct primitive session without a Builder Flow stamp remains independent and
@@ -51,6 +62,28 @@ Synchronization is digest-idempotent. The same trust bundle is not attached twic
 Inspection loads the run without evaluating it, so invalid evidence is rejected
 before Flow mutation.
 
+## Recovery
+
+Recover an interrupted canonical Builder session with:
+
+```bash
+flow-agents builder-run recover --session-dir .kontourai/flow-agents/<slug>
+```
+
+`recover` derives the Flow run id from the session directory slug; callers cannot
+select a run id or step. It requires exactly one non-empty
+`state.work_item_refs` entry, loads the existing run through Flow's canonical load
+API, and verifies that the ref matches persisted `state.subject` and, when present,
+`state.params.subject`. A missing, foreign, or corrupt run fails closed and is not
+created or repaired.
+
+Recovery is load/validate/project only. It computes the complete projection before
+updating `state.json`, the matching global `current.json`, and matching per-actor
+current pointers. It does not inspect or attach `trust.bundle`, evaluate gates, or
+write any file in `.kontourai/flow/runs/<slug>/`; the complete Flow run tree remains
+byte-identical. Use `sync`, not `recover`, to attach recorded evidence and evaluate
+the current gate.
+
 ## Trust Binding
 
 Claims relevant to the current gate must carry

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

@@ -130,9 +130,9 @@ Flow Agents currently ships five canonical policy classes. Each policy class has
 - `.kontourai/flow-agents/<slug>/critique.json` — open critique findings
 - `docs/context-map.md` — structure hint for repo navigation
 
-**Decision contract**: Non-blocking. Always exits 0. Appends steering text to the agent's context via `additionalContext` in the hook response. Does not block any action. 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. This is the mechanism that keeps an in-flight goal alive across context loss instead of relying on the model voluntarily re-reading the sidecar.
+**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. 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 as `userPromptSubmit: no native equivalent — steering context injection unavailable`.
+**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.
 

package/docs/workflow-usage-guide.md

@@ -591,6 +591,18 @@ Start a newly selected session with `flow-agents builder-run start --session-dir
 [`docs/spec/builder-flow-runtime.md`](spec/builder-flow-runtime.md) for the ownership,
 trust-binding, route-back, and artifact-root contract.
 
+If the same Builder slice is interrupted and its sidecar/current pointers may be
+stale, restore the projection from the existing canonical Flow run with:
+
+```bash
+flow-agents builder-run recover --session-dir .kontourai/flow-agents/<slug>
+```
+
+The session slug is the run identity; recovery accepts no caller-selected run or
+step. It validates the sole Work Item binding and updates only the sidecar/current
+projection, leaving the entire Flow run byte-identical. Recovery never attaches or
+evaluates `trust.bundle`; use `builder-run sync` for that separate operation.
+
 When a session resumes (after context compaction, an agent restart, or a cross-session
 handoff), the workflow-steering hook emits a `RESUME:` block on `SessionStart` that
 gives the resuming agent immediate situational awareness without blocking or auto-deciding.