@kontourai/flow-agents 3.4.2 → 3.5.0

package/src/cli/assignment-provider.ts

@@ -4,7 +4,7 @@ import * as path from "node:path";
 import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagString, type ParsedArgs } from "../lib/args.js";
-import { readJson, writeJson, isoNow } from "../lib/fs.js";
+import { atomicWriteJson, readJson, isoNow } from "../lib/fs.js";
 
 // ─── AssignmentProvider CLI (#290) ──────────────────────────────────────────
 // context/contracts/assignment-provider-contract.md is the governing vocabulary doc for this
@@ -60,6 +60,7 @@ export type AssignmentClaimRecord = {
   subject_id: string;
   actor: ActorStruct;
   actor_key?: string;
+  work_item_ref?: string;
   claimed_at: string;
   ttl_seconds: number;
   branch: string;
@@ -218,16 +219,50 @@ export function assignmentFilePath(artifactRoot: string, subjectId: string): str
   return path.join(artifactRoot, "assignment", `${sanitized}.json`);
 }
 
+function localAssignmentDir(artifactRoot: string, create: boolean): string | null {
+  const dir = path.join(artifactRoot, "assignment");
+  if (create) fs.mkdirSync(dir, { recursive: true });
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(dir);
+  } catch (error) {
+    if (!create && (error as NodeJS.ErrnoException).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: string, subjectId: string): AssignmentClaimRecord | null {
+  if (!localAssignmentDir(artifactRoot, false)) return null;
   const file = assignmentFilePath(artifactRoot, subjectId);
-  if (!fs.existsSync(file)) return null;
+  let stat: fs.Stats;
+  try {
+    stat = fs.lstatSync(file);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException).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: unknown;
+  let descriptor: number | null = 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 as 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 as AssignmentClaimRecord;
@@ -239,7 +274,7 @@ export function writeLocalRecord(artifactRoot: string, subjectId: string, 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);
 }
 
 /**
@@ -255,8 +290,7 @@ function sleepSync(ms: number): void {
 }
 
 function subjectLockDir(artifactRoot: string, subjectId: string): string {
-  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`);
 }
@@ -310,11 +344,19 @@ export function withSubjectLock<T>(artifactRoot: string, subjectId: string, body
       sleepSync(20);
     }
   }
+  const release = (): void => fs.rmSync(lockDir, { recursive: true, force: true });
+  let result: T;
   try {
-    return body();
-  } finally {
-    fs.rmSync(lockDir, { recursive: true, force: true });
+    result = body();
+  } catch (error) {
+    release();
+    throw error;
+  }
+  if (result && typeof (result as { then?: unknown }).then === "function") {
+    return Promise.resolve(result).finally(release) as T;
   }
+  release();
+  return result;
 }
 
 /**
@@ -512,7 +554,7 @@ export function performLocalClaim(
   artifactRoot: string,
   subjectId: string,
   actor: ActorStruct,
-  opts: { ttlSeconds: number; branch: string; artifactDir: string; reason?: string; actorKey?: string },
+  opts: { ttlSeconds: number; branch: string; artifactDir: string; reason?: string; actorKey?: string; workItemRef?: string },
 ): AssignmentClaimRecord {
   const helper = loadActorIdentityHelper();
   const reason = opts.reason ?? "claim";
@@ -538,6 +580,7 @@ export function performLocalClaim(
       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,
@@ -707,7 +750,7 @@ export function performLocalSupersede(
   subjectId: string,
   fromActor: ActorStruct,
   toActor: ActorStruct,
-  opts: { ttlSeconds?: number; branch?: string; artifactDir?: string; reason?: string; actorKey?: string } = {},
+  opts: { ttlSeconds?: number; branch?: string; artifactDir?: string; reason?: string; actorKey?: string; workItemRef?: string } = {},
 ): AssignmentClaimRecord {
   const helper = loadActorIdentityHelper();
   const reason = opts.reason ?? "supersede";
@@ -732,6 +775,7 @@ export function performLocalSupersede(
       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/src/cli/builder-flow-runtime.test.mjs

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

package/src/cli/workflow-sidecar.ts

@@ -9,12 +9,13 @@ import { fileURLToPath } from "node:url";
 // ADR 0016 Abstraction A: shared FlowDefinition resolver (P-a)
 import { resolveActiveFlowStep, resolveAllFlowGateExpects, resolveFlowFilePath, resolvePhaseMap, resolveRouteBackPolicy, type ActiveFlowStep } from "../lib/flow-resolver.js";
 import { defaultArtifactRootForRead, flowAgentsArtifactRoot } from "../lib/local-artifact-root.js";
-import { syncBuilderFlowSessionIfPresent } from "../builder-flow-runtime.js";
+import { 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, type ActorStruct, type EffectiveState, type FreshHolder } from "./assignment-provider.js";
+import { assignmentFilePath, computeEffectiveState, performLocalClaim, performLocalSupersede, readLocalAssignmentStatus, withSubjectLock, type ActorStruct, type EffectiveState, type FreshHolder } from "./assignment-provider.js";
 
 type AnyObj = Record<string, any>;
 
@@ -57,6 +58,12 @@ function workItemSlug(ref: string): string {
   return slugify(`${owner}-${repo}-${id}`, "work-item");
 }
 
+function assignmentSubjectMatchesWorkItem(slug: string, ref: string): boolean {
+  if (ref === `local:${slug}`) return true;
+  if (!/^[^/#]+\/[^/#]+#\d+$/.test(ref)) return false;
+  return workItemSlug(ref) === slug;
+}
+
 type SessionWorkItem = {
   ref: string;
   localRecord?: AnyObj;
@@ -64,13 +71,18 @@ type SessionWorkItem = {
 
 function sessionWorkItem(p: ReturnType<typeof parseArgs>, slug: string, dir: string): SessionWorkItem {
   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;
@@ -1312,8 +1324,15 @@ async function withLock<T>(dir: string, create: boolean, command: string, body:
   const lockDir = path.join(dir, ".workflow-sidecar.lockdir");
   const staleMs = Number(process.env.FLOW_AGENTS_WORKFLOW_SIDECAR_STALE_LOCK_MS ?? 5 * 60 * 1000);
   const deadline = Date.now() + 30000;
+  let acquiredRoot: fs.Stats | null = null;
+  let acquiredLock: fs.Stats | null = null;
   while (true) {
-    try { fs.mkdirSync(lockDir); break; }
+    try {
+      fs.mkdirSync(lockDir);
+      acquiredRoot = fs.lstatSync(dir);
+      acquiredLock = fs.lstatSync(lockDir);
+      break;
+    }
     catch (error) {
       const lockError = error as NodeJS.ErrnoException;
       if (lockError.code !== "EEXIST") {
@@ -1338,7 +1357,28 @@ async function withLock<T>(dir: string, create: boolean, command: string, body:
     if (delay) await new Promise((resolve) => setTimeout(resolve, Number(delay) * 1000));
     return await body();
   } finally {
-    fs.rmSync(lockDir, { recursive: true, force: true });
+    try {
+      const currentRoot = fs.lstatSync(dir);
+      const currentLock = fs.lstatSync(lockDir);
+      const sameIdentity = (left: fs.Stats, right: fs.Stats): boolean =>
+        left.dev === right.dev && left.ino === right.ino;
+      if (acquiredRoot
+        && acquiredLock
+        && !currentRoot.isSymbolicLink()
+        && currentRoot.isDirectory()
+        && !currentLock.isSymbolicLink()
+        && currentLock.isDirectory()
+        && sameIdentity(currentRoot, acquiredRoot)
+        && sameIdentity(currentLock, acquiredLock)) {
+        fs.rmdirSync(lockDir);
+      } else {
+        process.stderr.write(`[workflow-sidecar] lock cleanup skipped because root or lock identity changed: ${lockDir}\n`);
+      }
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "ENOENT") {
+        process.stderr.write(`[workflow-sidecar] lock cleanup skipped: ${error instanceof Error ? error.message : String(error)}\n`);
+      }
+    }
   }
 }
 
@@ -1414,6 +1454,15 @@ function sessionDirFor(root: string, slug: string): string {
   return dir;
 }
 
+function assertSafeSessionDirectory(root: string, dir: string): void {
+  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: string): string {
   if (!agent) die("--agent-id is required");
   if (path.isAbsolute(agent)) die("--agent-id must be a relative slug");
@@ -1453,17 +1502,20 @@ function findRepoRootFromDirStrict(startDir: string): string | null {
  * 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: string): string {
-  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();
 }
 
 /**
@@ -1758,10 +1810,11 @@ function enforceEnsureSessionOwnership(
   slug: string,
   dir: string,
   resolution: { actorStruct: ActorStruct; actorKey: string; branchActorKey: string; unresolved: boolean },
-): void {
+  workItemRef?: string,
+): { assignmentFile: string; actorKey: string } | null {
   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
@@ -1769,7 +1822,7 @@ function enforceEnsureSessionOwnership(
   // 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
@@ -1821,6 +1874,9 @@ function enforceEnsureSessionOwnership(
     // `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);
@@ -1831,9 +1887,28 @@ function enforceEnsureSessionOwnership(
     // 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 = (): { assignmentFile: string; actorKey: string } | null => {
+    // 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 = (): string => {
     const existingBranch = fs.existsSync(path.join(dir, "state.json")) ? (loadJson(path.join(dir, "state.json")).branch as string | undefined) : undefined;
     return existingBranch || resolveSessionBranch(p, slug);
@@ -1846,17 +1921,17 @@ function enforceEnsureSessionOwnership(
       // ActorStruct triple), so this redundant belt-and-suspenders check agrees with the
       // 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
+      if (isSelf) 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");
@@ -1889,11 +1964,12 @@ function enforceEnsureSessionOwnership(
         // 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, {
@@ -1903,8 +1979,9 @@ function enforceEnsureSessionOwnership(
         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)}`);
@@ -1947,27 +2024,66 @@ function resolveEnsureSessionEntry(p: ReturnType<typeof parseArgs>, dir: string)
   return { flowId, stepId: explicitStep || firstStep, firstStep };
 }
 
+function assertCanonicalBuilderArtifactRoot(root: string): void {
+  const kontouraiRoot = path.dirname(root);
+  const projectRoot = path.dirname(kontouraiRoot);
+  if (path.basename(root) !== "flow-agents" || path.basename(kontouraiRoot) !== ".kontourai") {
+    die("ensure-session --flow-id builder.build requires --artifact-root <project>/.kontourai/flow-agents");
+  }
+
+  const statIfPresent = (candidate: string): fs.Stats | null => {
+    try {
+      return fs.lstatSync(candidate);
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code === "ENOENT") return null;
+      throw error;
+    }
+  };
+  const projectStat = statIfPresent(projectRoot);
+  if (projectStat && (projectStat.isSymbolicLink() || !projectStat.isDirectory())) {
+    die(`ensure-session --flow-id builder.build requires a non-symlink project root: ${projectRoot}`);
+  }
+  const realProjectRoot = projectStat ? fs.realpathSync(projectRoot) : projectRoot;
+  for (const [candidate, expected, label] of [
+    [kontouraiRoot, path.join(realProjectRoot, ".kontourai"), ".kontourai root"],
+    [root, path.join(realProjectRoot, ".kontourai", "flow-agents"), "Flow Agents artifact root"],
+  ] as const) {
+    const stat = statIfPresent(candidate);
+    if (!stat) continue;
+    if (stat.isSymbolicLink() || !stat.isDirectory() || fs.realpathSync(candidate) !== expected) {
+      die(`ensure-session --flow-id builder.build requires a non-symlink ${label}: ${candidate}`);
+    }
+  }
+}
+
 function preflightEnsureSession(p: ReturnType<typeof parseArgs>): void {
   const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
   const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
   const dir = sessionDirFor(root, slug);
-  resolveEnsureSessionEntry(p, dir);
+  assertSafeSessionDirectory(root, dir);
+  const entry = resolveEnsureSessionEntry(p, dir);
+  if (entry.flowId === "builder.build") assertCanonicalBuilderArtifactRoot(root);
   sessionWorkItem(p, slug, dir);
 }
 
-function ensureSession(p: ReturnType<typeof parseArgs>): number {
+async function ensureSession(p: ReturnType<typeof parseArgs>): Promise<number> {
   const root = opt(p, "artifact-root") ? path.resolve(opt(p, "artifact-root")) : flowAgentsArtifactRoot();
   const slug = opt(p, "task-slug") || (opt(p, "work-item") ? workItemSlug(opt(p, "work-item")) : die("--task-slug is required (or pass --work-item to derive it)"));
   const dir = sessionDirFor(root, slug);
+  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);
@@ -1994,7 +2110,6 @@ function ensureSession(p: ReturnType<typeof parseArgs>): number {
             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.");
@@ -2025,6 +2140,46 @@ function ensureSession(p: ReturnType<typeof parseArgs>): number {
     ? persistedCurrent.active_step_id
     : entry.stepId;
   writeCurrent(root, dir, timestamp, "workflow-sidecar", "ensure-session", entry.flowId || undefined, resumedStep || undefined, actorResolution.unresolved ? undefined : actorResolution.branchActorKey);
+  if (entry.flowId === "builder.build") {
+    try {
+      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/src/lib/flow-resolver.ts

@@ -449,8 +449,8 @@ export function resolvePhaseMap(flowId: string, repoRoot: string): Record<string
 
 /**
  * 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.
@@ -464,6 +464,10 @@ function findRepoRoot(startDir: string): string {
     if (parent === dir) 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();
 }

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

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