@kontourai/flow-agents 3.4.2 → 3.5.0

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## [3.5.0](https://github.com/kontourai/flow-agents/compare/v3.4.3...v3.5.0) (2026-07-10)
+
+
+### Features
+
+* **builder:** derive selected-work evidence from acquisition ([#543](https://github.com/kontourai/flow-agents/issues/543)) ([bfe1681](https://github.com/kontourai/flow-agents/commit/bfe1681211174cb6219b0dd94d765aa9c99734bd))
+
+## [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/assignment-provider.d.ts

@@ -31,6 +31,7 @@ export type AssignmentClaimRecord = {
     subject_id: string;
     actor: ActorStruct;
     actor_key?: string;
+    work_item_ref?: string;
     claimed_at: string;
     ttl_seconds: number;
     branch: string;
@@ -116,6 +117,7 @@ export declare function performLocalClaim(artifactRoot: string, subjectId: strin
     artifactDir: string;
     reason?: string;
     actorKey?: string;
+    workItemRef?: string;
 }): AssignmentClaimRecord;
 /**
  * Wave 1 (#292) extraction: the durable-write body previously inlined inside releaseLocalFile's
@@ -177,6 +179,7 @@ export declare function performLocalSupersede(artifactRoot: string, subjectId: s
     artifactDir?: string;
     reason?: string;
     actorKey?: string;
+    workItemRef?: string;
 }): AssignmentClaimRecord;
 /**
  * Wave 1 (#291) extraction: the local-file branch of statusCommand's assignment-layer read,

package/build/src/cli/assignment-provider.js

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagString } from "../lib/args.js";
-import { readJson, writeJson, isoNow } from "../lib/fs.js";
+import { atomicWriteJson, readJson, isoNow } from "../lib/fs.js";
 const DEFAULT_LABEL_NAME = "agent:claimed";
 const CLAIM_COMMENT_MARKER_DEFAULT = "<!-- flow-agents:assignment-claim -->";
 /**
@@ -95,19 +95,59 @@ export function assignmentFilePath(artifactRoot, subjectId) {
     const sanitized = loadActorIdentityHelper().sanitizeSegment(subjectId);
     return path.join(artifactRoot, "assignment", `${sanitized}.json`);
 }
+function localAssignmentDir(artifactRoot, create) {
+    const dir = path.join(artifactRoot, "assignment");
+    if (create)
+        fs.mkdirSync(dir, { recursive: true });
+    let stat;
+    try {
+        stat = fs.lstatSync(dir);
+    }
+    catch (error) {
+        if (!create && error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (stat.isSymbolicLink() || !stat.isDirectory()) {
+        throw new Error(`assignment directory must be a real directory, not a symlink: ${dir}`);
+    }
+    const realRoot = fs.realpathSync(artifactRoot);
+    if (fs.realpathSync(dir) !== path.join(realRoot, "assignment")) {
+        throw new Error(`assignment directory escapes the artifact root: ${dir}`);
+    }
+    return dir;
+}
 export function readLocalRecord(artifactRoot, subjectId) {
-    const file = assignmentFilePath(artifactRoot, subjectId);
-    if (!fs.existsSync(file))
+    if (!localAssignmentDir(artifactRoot, false))
         return null;
+    const file = assignmentFilePath(artifactRoot, subjectId);
+    let stat;
+    try {
+        stat = fs.lstatSync(file);
+    }
+    catch (error) {
+        if (error.code === "ENOENT")
+            return null;
+        throw error;
+    }
+    if (stat.isSymbolicLink() || !stat.isFile()) {
+        throw new Error(`assignment record must be a regular file, not a symlink: ${file}`);
+    }
     let data;
+    let descriptor = null;
     try {
-        data = readJson(file);
+        descriptor = fs.openSync(file, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+        data = JSON.parse(fs.readFileSync(descriptor, "utf8"));
     }
     catch (error) {
         // Fail loud: a corrupt claim record must never be silently treated as "no claim" — that
         // would be a fail-open path that could let a second claim silently overwrite a real one.
         throw new Error(`assignment record is corrupt, refusing to proceed: ${file}: ${error.message}`);
     }
+    finally {
+        if (descriptor !== null)
+            fs.closeSync(descriptor);
+    }
     if (typeof data !== "object" || data === null)
         throw new Error(`assignment record is not an object: ${file}`);
     const record = data;
@@ -119,7 +159,7 @@ export function writeLocalRecord(artifactRoot, subjectId, record) {
     // writeJson throws on any mkdir/writeFileSync failure; that error is intentionally allowed to
     // propagate to main()'s top-level try/catch and exit non-zero. Durable writes must fail loud,
     // never fail open (artifact-contract.md).
-    writeJson(assignmentFilePath(artifactRoot, subjectId), record);
+    atomicWriteJson(artifactRoot, assignmentFilePath(artifactRoot, subjectId), record);
 }
 /**
  * Synchronous busy-sleep via Atomics.wait on a throwaway SharedArrayBuffer — Node.js (unlike
@@ -133,8 +173,7 @@ function sleepSync(ms) {
     Atomics.wait(ia, 0, 0, ms);
 }
 function subjectLockDir(artifactRoot, subjectId) {
-    const assignmentDir = path.join(artifactRoot, "assignment");
-    fs.mkdirSync(assignmentDir, { recursive: true });
+    const assignmentDir = localAssignmentDir(artifactRoot, true);
     const sanitized = loadActorIdentityHelper().sanitizeSegment(subjectId);
     return path.join(assignmentDir, `.${sanitized}.lockdir`);
 }
@@ -190,12 +229,20 @@ export function withSubjectLock(artifactRoot, subjectId, body) {
             sleepSync(20);
         }
     }
+    const release = () => fs.rmSync(lockDir, { recursive: true, force: true });
+    let result;
     try {
-        return body();
+        result = body();
     }
-    finally {
-        fs.rmSync(lockDir, { recursive: true, force: true });
+    catch (error) {
+        release();
+        throw error;
+    }
+    if (result && typeof result.then === "function") {
+        return Promise.resolve(result).finally(release);
     }
+    release();
+    return result;
 }
 /**
  * The assignment ⋈ liveness join (contract doc's "assignment ⋈ liveness join" section, ADR 0021
@@ -403,6 +450,7 @@ export function performLocalClaim(artifactRoot, subjectId, actor, opts) {
             subject_id: subjectId,
             actor,
             ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
+            ...((opts.workItemRef ?? existing?.work_item_ref) ? { work_item_ref: opts.workItemRef ?? existing?.work_item_ref } : {}),
             claimed_at: isoNow(),
             ttl_seconds: opts.ttlSeconds,
             branch: opts.branch,
@@ -574,6 +622,7 @@ export function performLocalSupersede(artifactRoot, subjectId, fromActor, toActo
             subject_id: subjectId,
             actor: toActor,
             ...(opts.actorKey ? { actor_key: opts.actorKey } : {}),
+            ...((opts.workItemRef ?? existing.work_item_ref) ? { work_item_ref: opts.workItemRef ?? existing.work_item_ref } : {}),
             claimed_at: isoNow(),
             ttl_seconds: ttlSeconds,
             branch: opts.branch ?? existing.branch,

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

@@ -9,12 +9,13 @@ 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 { ensureSafeDirectory } from "../lib/fs.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
 // import — same idiom already used above for ../lib/flow-resolver.js).
-import { computeEffectiveState, performLocalClaim, performLocalSupersede, readLocalAssignmentStatus } from "./assignment-provider.js";
+import { assignmentFilePath, computeEffectiveState, performLocalClaim, performLocalSupersede, readLocalAssignmentStatus, withSubjectLock } from "./assignment-provider.js";
 export const statuses = new Set(["new", "planning", "planned", "in_progress", "blocked", "verifying", "verified", "needs_decision", "not_verified", "failed", "delivered", "accepted", "archived"]);
 export const phases = ["idea", "backlog", "pickup", "planning", "execution", "verification", "goal_fit", "evidence", "release", "learning", "done"];
 export const checkKinds = new Set(["build", "types", "lint", "test", "command", "security", "diff", "browser", "runtime", "policy", "external"]);
@@ -55,14 +56,27 @@ function workItemSlug(ref) {
     const [owner, repo] = parts;
     return slugify(`${owner}-${repo}-${id}`, "work-item");
 }
+function assignmentSubjectMatchesWorkItem(slug, ref) {
+    if (ref === `local:${slug}`)
+        return true;
+    if (!/^[^/#]+\/[^/#]+#\d+$/.test(ref))
+        return false;
+    return workItemSlug(ref) === slug;
+}
 function sessionWorkItem(p, slug, dir) {
     const providerRef = opt(p, "work-item");
+    const existingState = loadJson(path.join(dir, "state.json"));
+    const existingRef = Array.isArray(existingState.work_item_refs) && typeof existingState.work_item_refs[0] === "string"
+        ? existingState.work_item_refs[0]
+        : "";
     if (providerRef) {
+        if (existingRef && existingRef !== providerRef) {
+            die(`ensure-session refused: session ${JSON.stringify(slug)} is already bound to Work Item ${JSON.stringify(existingRef)}, not ${JSON.stringify(providerRef)}`);
+        }
         return { ref: providerRef };
     }
-    const existingState = loadJson(path.join(dir, "state.json"));
-    if (Array.isArray(existingState.work_item_refs) && typeof existingState.work_item_refs[0] === "string") {
-        return { ref: existingState.work_item_refs[0] };
+    if (existingRef) {
+        return { ref: existingRef };
     }
     const title = opt(p, "title", slug).trim() || slug;
     const body = opt(p, "summary").trim();
@@ -1292,9 +1306,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 +1344,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) {
@@ -1411,6 +1451,15 @@ function sessionDirFor(root, slug) {
         die("session directory must stay under artifact root");
     return dir;
 }
+function assertSafeSessionDirectory(root, dir) {
+    if (!fs.existsSync(dir))
+        return;
+    const stat = fs.lstatSync(dir);
+    const expected = path.join(fs.realpathSync(root), path.basename(dir));
+    if (stat.isSymbolicLink() || !stat.isDirectory() || fs.realpathSync(dir) !== expected) {
+        die(`session directory must be a real directory under the artifact root: ${dir}`);
+    }
+}
 function validateAgentId(agent) {
     if (!agent)
         die("--agent-id is required");
@@ -1455,17 +1504,22 @@ function findRepoRootFromDirStrict(startDir) {
  * Find the repository root by walking upward from a starting directory to locate
  * the nearest ancestor containing a kits/ subdirectory. Mirrors flow-resolver.ts
  * findRepoRoot, but callable from workflow-sidecar.ts without re-importing the
- * internal helper. Falls back to process.cwd() when no kits/ ancestor is found —
- * appropriate for phase-map/first-step resolution (ADR 0016 Abstraction A, P-d),
- * where the caller is always invoked from within a real repo checkout.
+ * internal helper. A canonical `.kontourai` path falls back to its owning project,
+ * allowing installed package assets to resolve independently of ambient cwd. Other
+ * layouts retain the cwd fallback used by standalone primitive sessions.
  *
- * Do NOT use this cwd-falling-back variant for publishDelivery's repo-root
- * resolution — use findRepoRootFromDirStrict there instead, so a scratch/test
+ * Do NOT use this permissive variant for publishDelivery's repo-root resolution —
+ * use findRepoRootFromDirStrict there instead, so a scratch/test
  * session dir with no repo ancestor fails closed (skips publish) rather than
  * silently trusting process.cwd(), which could be an unrelated real repo.
  */
 function findRepoRootFromDir(startDir) {
-    return findRepoRootFromDirStrict(startDir) ?? process.cwd();
+    const discovered = findRepoRootFromDirStrict(startDir);
+    if (discovered)
+        return discovered;
+    if (path.basename(startDir) === ".kontourai")
+        return path.dirname(startDir);
+    return process.cwd();
 }
 /**
  * Resolve the first step id from a FlowDefinition's steps[] list.
@@ -1744,10 +1798,10 @@ function loadJsonInputFile(file) {
  * mitigation class: a hostile liveness event or a hand-crafted --effective-state-json fixture must
  * never be able to smuggle raw control/ANSI bytes into this process's stderr/thrown message).
  */
-function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
+function enforceEnsureSessionOwnership(p, root, slug, dir, resolution, workItemRef) {
     if (p.flags.has("skip-ownership-guard")) {
         process.stderr.write("[ensure-session] ownership guard skipped via --skip-ownership-guard\n");
-        return;
+        return null;
     }
     // Design Decision 4 (unchanged from resolveSessionBranch): actor-resolution ambiguity never
     // hard-fails session creation. Without a resolvable actor there is no safe identity to claim
@@ -1755,7 +1809,7 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
     // than claiming under a synthetic/unstable identity.
     if (resolution.unresolved) {
         process.stderr.write("[ensure-session] ownership guard not evaluated: actor is unresolved (set --actor or FLOW_AGENTS_ACTOR, or run inside a supported runtime) — proceeding without a durable claim, exactly as ensure-session behaved before #291\n");
-        return;
+        return null;
     }
     // F5 fix (fix-plan iteration 1, LOW): match assignment-provider.ts's sanitizeDisplayField
     // two-tier convention (64 for id-like fields, 240 for free text) rather than asserting one
@@ -1804,6 +1858,9 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
         // `assignment-provider status --self-actor <branchActorKey>` run by a DIFFERENT tool
         // afterward would never recognize this guard's own claim as self.
         const assignment = readLocalAssignmentStatus(root, slug);
+        if (workItemRef && assignment.record?.work_item_ref && assignment.record.work_item_ref !== workItemRef) {
+            die(`ensure-session refused: assignment ${JSON.stringify(slug)} is already bound to Work Item ${JSON.stringify(assignment.record.work_item_ref)}, not ${JSON.stringify(workItemRef)}`);
+        }
         const events = readLivenessEvents(root);
         const freshList = loadLivenessReadHelper().freshHolders(events, slug, resolution.branchActorKey, nowMs);
         effective = computeEffectiveState(assignment, freshList, resolution.branchActorKey, nowMs);
@@ -1815,8 +1872,27 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
         // neither applies, this is a documented scope boundary (today's pre-#291 baseline behavior),
         // never a silent hole.
         process.stderr.write(`[ensure-session] ownership guard not evaluated: provider "${sanitize(assignmentProviderKind)}" requires --effective-state-json\n`);
-        return;
+        return null;
     }
+    const selectedWorkEvidence = () => {
+        // Only a claim read from the local provider is durable evidence. Precomputed provider state
+        // can authorize entry, but it cannot prove that this process acquired the Work Item.
+        if (!workItemRef || effectiveStateJsonFlag || assignmentProviderKind !== "local-file")
+            return null;
+        const assignment = readLocalAssignmentStatus(root, slug);
+        const record = assignment.record;
+        if (!record
+            || record.status !== "claimed"
+            || record.subject_id !== slug
+            || record.actor_key !== resolution.branchActorKey
+            || record.work_item_ref !== workItemRef) {
+            return null;
+        }
+        return {
+            assignmentFile: assignmentFilePath(root, slug),
+            actorKey: resolution.branchActorKey,
+        };
+    };
     const resolveBranchForClaim = () => {
         const existingBranch = fs.existsSync(path.join(dir, "state.json")) ? loadJson(path.join(dir, "state.json")).branch : undefined;
         return existingBranch || resolveSessionBranch(p, slug);
@@ -1829,17 +1905,17 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
             // effective_state computation instead of silently using a different identity.
             const isSelf = effective.reason === "self_is_holder" || (!!effective.holder?.actor && effective.holder.actor === resolution.branchActorKey);
             if (isSelf)
-                return; // resume own session — no refusal
+                return selectedWorkEvidence();
             const holderActor = sanitize(effective.holder?.actor ?? "unknown");
             const lastAtSuffix = effective.holder?.last_at ? ` (last_at ${sanitize(effective.holder.last_at)})` : "";
             die(`ensure-session refused: subject ${sanitize(slug)} is currently held by a different, still-live actor (${holderActor}${lastAtSuffix}). Pick a different work item, or confirm the holder session is truly gone before considering a takeover.`);
-            return;
+            return null;
         }
         case "human-held": {
             const assignee = effective.holder?.assignee ? sanitize(effective.holder.assignee) : "an assigned human";
             const idleSuffix = effective.holder?.idle_days != null ? ` (idle ${Number(effective.holder.idle_days)} day(s))` : "";
             die(`ensure-session refused: subject ${sanitize(slug)} is assigned to ${assignee}${idleSuffix}. This guard never auto-reclaims a human assignment — confirm with the user before proceeding.`);
-            return;
+            return null;
         }
         case "reclaimable": {
             const holderActor = sanitize(effective.holder?.actor ?? "unknown");
@@ -1873,11 +1949,12 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
                 // computeEffectiveState's holderActorKey (assignment-provider.ts) matches this same
                 // branchActorKey string on the next status/guard check, cross-tool.
                 actorKey: resolution.branchActorKey,
+                ...(workItemRef ? { workItemRef } : {}),
             });
             // Render-don't-execute: emit the incumbent's branch so the skill continues it (never a new
             // branch). The successor re-enters the SAME artifact dir (deterministic slug) by construction.
             printJson({ role: "SupersedeTakeover", subject: sanitize(slug), superseded_actor: holderActor, ...(incumbentBranch ? { resumed_branch: sanitizeWide(incumbentBranch) } : {}), reason: sanitizeWide(takeoverReason) });
-            return;
+            return selectedWorkEvidence();
         }
         case "free": {
             performLocalClaim(root, slug, resolution.actorStruct, {
@@ -1887,8 +1964,9 @@ function enforceEnsureSessionOwnership(p, root, slug, dir, resolution) {
                 reason: opt(p, "reason", "ensure-session entry"),
                 // F1 fix (fix-plan iteration 1, HIGH): see the performLocalSupersede call above.
                 actorKey: resolution.branchActorKey,
+                ...(workItemRef ? { workItemRef } : {}),
             });
-            return;
+            return selectedWorkEvidence();
         }
         default:
             die(`ensure-session ownership guard: unrecognized effective_state ${JSON.stringify(effective.effective_state)}`);
@@ -1930,26 +2008,68 @@ 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);
+    assertSafeSessionDirectory(root, 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);
+    assertSafeSessionDirectory(root, dir);
     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
     // below (writeCurrent's per-actor dual-write) so the branch-naming actor and the
     // assignment-claim actor are always the same identity.
     const actorResolution = resolveEnsureSessionActor(p);
-    enforceEnsureSessionOwnership(p, root, slug, dir, actorResolution);
-    fs.mkdirSync(dir, { recursive: true });
+    const selectionWorkItemRef = entry.flowId === "builder.build" && assignmentSubjectMatchesWorkItem(slug, workItem.ref)
+        ? workItem.ref
+        : undefined;
+    const selectedWorkEvidence = enforceEnsureSessionOwnership(p, root, slug, dir, actorResolution, selectionWorkItemRef);
+    ensureSafeDirectory(root, dir);
     const timestamp = opt(p, "timestamp", now());
     if (workItem.localRecord && !fs.existsSync(path.join(dir, "work-item.json"))) {
         writeJson(path.join(dir, "work-item.json"), workItem.localRecord);
@@ -1976,7 +2096,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 +2116,47 @@ 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 {
+            const started = await startBuilderFlowSession({ sessionDir: dir });
+            if (started.run.state.current_step === "pull-work"
+                && selectedWorkEvidence
+                && assignmentSubjectMatchesWorkItem(slug, workItem.ref)) {
+                await withSubjectLock(root, slug, async () => {
+                    const assignment = readLocalAssignmentStatus(root, slug).record;
+                    if (!assignment
+                        || assignment.status !== "claimed"
+                        || assignment.subject_id !== slug
+                        || assignment.actor_key !== selectedWorkEvidence.actorKey
+                        || assignment.work_item_ref !== workItem.ref) {
+                        die(`ensure-session refused to emit selected-work evidence: assignment provenance changed before gate evaluation for ${JSON.stringify(workItem.ref)}`);
+                    }
+                    const assignmentContent = fs.readFileSync(selectedWorkEvidence.assignmentFile);
+                    const assignmentDigest = createHash("sha256").update(assignmentContent).digest("hex");
+                    const projectRoot = path.dirname(path.dirname(root));
+                    const evidenceFile = path.relative(projectRoot, selectedWorkEvidence.assignmentFile);
+                    await recordGateClaim(parseArgs([
+                        "record-gate-claim",
+                        dir,
+                        "--actor", selectedWorkEvidence.actorKey,
+                        "--expectation", "selected-work",
+                        "--status", "pass",
+                        "--summary", `Work Item ${workItem.ref} is durably assigned to the active workflow actor (assignment sha256:${assignmentDigest}).`,
+                        "--evidence-ref-json", JSON.stringify({
+                            kind: "artifact",
+                            file: evidenceFile,
+                            summary: `Durable local assignment record for the selected Work Item and active actor; sha256:${assignmentDigest}.`,
+                        }),
+                        "--timestamp", timestamp,
+                    ]));
+                });
+            }
+        }
+        catch (error) {
+            process.stderr.write("[ensure-session] canonical Builder Flow entry failed; the acquired Work Item provenance remains retryable. Re-run the same ensure-session command.\n");
+            throw error;
+        }
+    }
     console.log(dir);
     return 0;
 }

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

@@ -392,8 +392,8 @@ export function resolvePhaseMap(flowId, repoRoot) {
 }
 /**
  * Find the repository root from a starting directory by walking upward to locate
- * the nearest ancestor that contains a `kits/` subdirectory. If none is found,
- * falls back to `process.cwd()` so the default "run from repo root" case still works.
+ * the nearest ancestor that contains a `kits/` subdirectory. A canonical `.kontourai`
+ * artifact path falls back to its owning project; other layouts fall back to cwd.
  *
  * This is required because the runtime artifact directory can live anywhere (temp dirs,
  * subprojects, CI workspaces) while the kits/ directory is always at the repo root.
@@ -409,6 +409,11 @@ function findRepoRoot(startDir) {
             break; // reached filesystem root
         dir = parent;
     }
+    // A canonical product artifact root identifies its owning project even when that
+    // consumer has no source-tree kits/. resolveFlowFilePath can then use the installed
+    // package fallback without consulting an unrelated ambient cwd.
+    if (path.basename(startDir) === ".kontourai")
+        return path.dirname(startDir);
     // Fallback: process.cwd() covers the common "run from repo root" case
     return process.cwd();
 }