@kontourai/flow-agents 3.4.0 → 3.4.2

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

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

package/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.

package/evals/integration/test_builder_entry_enforcement.sh

@@ -68,7 +68,10 @@ if (state.status !== 'new' || state.phase !== 'pickup') process.exit(1);
 if (JSON.stringify(state.work_item_refs) !== JSON.stringify(['local:local-request'])) process.exit(1);
 if (workItem.id !== 'local-request' || workItem.title !== 'Local request') process.exit(1);
 if (workItem.source_provider?.kind !== 'local' || workItem.source_provider?.path !== 'work-item.json') process.exit(1);
-if (!state.next_action?.summary?.includes('builder-run start') || !state.next_action?.summary?.includes('`pull-work`')) process.exit(1);
+if (state.next_action?.command !== 'flow-agents builder-run start --session-dir .kontourai/flow-agents/local-request') process.exit(1);
+if (state.next_action?.enforcement !== 'before_tool_use') process.exit(1);
+if (JSON.stringify(state.next_action?.skills) !== JSON.stringify(['pull-work'])) process.exit(1);
+if (!state.next_action?.summary?.includes('`pull-work`')) process.exit(1);
 NODE
   then
     pass "providerless request creates a local Work Item and starts at pull-work"

package/evals/integration/test_bundle_install.sh

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

package/evals/integration/test_workflow_steering_hook.sh

@@ -21,6 +21,78 @@ mkdir -p "$REPO/docs"
 printf '# Test Repo\n' > "$REPO/AGENTS.md"
 printf '# Context Map\n' > "$REPO/docs/context-map.md"
 
+ENTRY_REPO="$TMPDIR_EVAL/entry-repo"
+ENTRY_COMMAND='flow-agents builder-run start --session-dir .kontourai/flow-agents/entry-demo'
+mkdir -p "$ENTRY_REPO/.kontourai/flow-agents/entry-demo"
+printf '# Entry Repo\n' > "$ENTRY_REPO/AGENTS.md"
+cat > "$ENTRY_REPO/.kontourai/flow-agents/entry-demo/state.json" <<JSON
+{
+  "schema_version": "1.0",
+  "task_slug": "entry-demo",
+  "status": "new",
+  "phase": "pickup",
+  "updated_at": "2026-07-10T00:00:00Z",
+  "next_action": {
+    "status": "continue",
+    "summary": "Start the canonical Flow run.",
+    "skills": ["pull-work"],
+    "command": "$ENTRY_COMMAND",
+    "enforcement": "before_tool_use"
+  }
+}
+JSON
+
+if node "$ROOT/scripts/hooks/workflow-steering.js" >"$TMPDIR_EVAL/entry-direct.out" 2>"$TMPDIR_EVAL/entry-direct.err" <<JSON
+{"hook_event_name":"PreToolUse","cwd":"$ENTRY_REPO","tool_name":"Bash","tool_input":{"command":"git status --short"}}
+JSON
+then
+  _fail "workflow entry enforcement should block unrelated tools"
+else
+  status=$?
+  if [[ "$status" -eq 2 ]] && rg -F -q "Run exactly: $ENTRY_COMMAND" "$TMPDIR_EVAL/entry-direct.err"; then
+    _pass "workflow entry enforcement blocks unrelated tools with the projected action"
+  else
+    _fail "workflow entry enforcement returned the wrong direct-hook decision: rc=$status $(cat "$TMPDIR_EVAL/entry-direct.err")"
+  fi
+fi
+
+if node "$ROOT/scripts/hooks/workflow-steering.js" >"$TMPDIR_EVAL/entry-allow.out" 2>"$TMPDIR_EVAL/entry-allow.err" <<JSON
+{"hook_event_name":"PreToolUse","cwd":"$ENTRY_REPO","tool_name":"Bash","tool_input":{"command":"$ENTRY_COMMAND"}}
+JSON
+then
+  _pass "workflow entry enforcement allows the exact projected action"
+else
+  _fail "workflow entry enforcement blocked the projected action: $(cat "$TMPDIR_EVAL/entry-allow.err")"
+fi
+
+for adapter in codex claude; do
+  if [[ "$adapter" == "codex" ]]; then
+    adapter_command=(node "$ROOT/scripts/hooks/codex-hook-adapter.js" pre:workflow-entry workflow-steering.js standard,strict)
+  else
+    adapter_command=(node "$ROOT/scripts/hooks/claude-hook-adapter.js" PreToolUse pre:workflow-entry workflow-steering.js standard,strict)
+  fi
+  if "${adapter_command[@]}" >"$TMPDIR_EVAL/entry-$adapter.out" 2>"$TMPDIR_EVAL/entry-$adapter.err" <<JSON
+{"hook_event_name":"PreToolUse","cwd":"$ENTRY_REPO","tool_name":"Bash","tool_input":{"command":"git status --short"}}
+JSON
+  then
+    if node - "$TMPDIR_EVAL/entry-$adapter.out" "$ENTRY_COMMAND" <<'NODE'
+const fs = require('node:fs');
+const payload = JSON.parse(fs.readFileSync(process.argv[2], 'utf8'));
+const expected = process.argv[3];
+if (payload.hookSpecificOutput?.hookEventName !== 'PreToolUse') process.exit(1);
+if (payload.hookSpecificOutput?.permissionDecision !== 'deny') process.exit(1);
+if (!String(payload.hookSpecificOutput?.permissionDecisionReason || '').includes(expected)) process.exit(1);
+NODE
+    then
+      _pass "$adapter adapter translates projected-action enforcement into a PreToolUse denial"
+    else
+      _fail "$adapter adapter returned the wrong projected-action denial: $(cat "$TMPDIR_EVAL/entry-$adapter.out")"
+    fi
+  else
+    _fail "$adapter adapter should translate a policy block without failing: $(cat "$TMPDIR_EVAL/entry-$adapter.err")"
+  fi
+done
+
 cat > "$REPO/.kontourai/flow-agents/steering-demo/state.json" <<'JSON'
 {
   "schema_version": "1.0",

package/kits/builder/skills/continue-work/SKILL.md

@@ -27,6 +27,13 @@ continue-work ties these together for **one job**: take a multi-slice work item
 - The request is **brand-new work** with nothing landed yet — that is selection from the backlog. Route to `pull-work`.
 - The request is to **resume the *same* interrupted slice** after a restart (same in-flight slice, mid-execution, picking up new hooks/logic) — that is the resume surface (#153), which reconstructs `state.json` + `handoff.json` + plan + `trust.bundle` for the *same* increment. continue-work advances to the *next* increment; it does not re-enter an unfinished one.
 
+For that same-slice case, when a canonical Builder Flow run already exists, restore
+its sidecar/current projection with `flow-agents builder-run recover --session-dir
+.kontourai/flow-agents/<slug>` before following the resume surface. The command
+derives run identity from the session slug and only loads, validates, and projects;
+never invent or supply a run id or step, and use `builder-run sync` separately only
+when recorded evidence should be attached and evaluated.
+
 If the boundary is ambiguous (is this the next slice or the same one?), stop and ask one question before routing. Do not silently assume.
 
 ## Boundary (ADR 0014)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.4.0",
+  "version": "3.4.2",
   "description": "Flow Agents — a Kontour product that applies Flow and Veritas discipline as a portable process layer inside the agent tools you already use: Claude Code, Codex, Kiro, opencode, pi, and GitHub Actions — with framework adapters (AWS Strands preview) on the same policy-engine contract.",
   "keywords": [
     "agents",

package/schemas/workflow-state.schema.json

@@ -122,6 +122,13 @@
         "command": {
           "type": "string",
           "minLength": 1
+        },
+        "enforcement": {
+          "type": "string",
+          "enum": [
+            "advisory",
+            "before_tool_use"
+          ]
         }
       }
     }

package/scripts/hooks/workflow-steering.js

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

package/scripts/install-merge.js

@@ -41,13 +41,14 @@ const path = require("node:path");
 const os = require("node:os");
 
 // ─── Marker strings ───────────────────────────────────────────────────────────
-// These three statusMessage strings identify every flow-agents managed hook.
+// These statusMessage strings identify every flow-agents managed hook.
 // They are the same strings used by COLLISION_MARKER in src/cli/init.ts and
 // by exportClaudeSettings() / exportCodexHooks() in build-universal-bundles.ts.
 const FA_MARKERS = [
   "Recording Flow Agents telemetry",
   "Running Flow Agents hook policy",
   "Capturing Flow Agents command evidence",
+  "Enforcing Flow Agents projected action",
 ];
 
 const FA_OWNERSHIP_MARKERS = [

package/src/builder-flow-runtime.ts

@@ -44,10 +44,28 @@ type SessionContext = {
   bundleFile: string;
 };
 
+type SidecarSnapshot = {
+  state: AnyRecord;
+  raw: string;
+};
+
+type ProjectionTargetSnapshot = {
+  file: string;
+  raw: string | null;
+  root: string;
+  field: string;
+};
+
+type PreparedProjectionWrites = {
+  targets: ProjectionTargetSnapshot[];
+  actorEntries: string[] | null;
+  writes: Array<{ file: string; content: string }>;
+};
+
 export async function startBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult> {
   const context = resolveSessionContext(input.sessionDir);
-  const sidecarState = readSidecarState(context);
-  const subject = workflowSubject(sidecarState);
+  const sidecarSnapshot = readSidecarSnapshot(context);
+  const subject = workflowSubject(sidecarSnapshot.state);
   let run: BuilderBuildRunResult;
   try {
     run = await loadBuilderBuildRun({
@@ -77,6 +95,33 @@ export async function syncBuilderFlowSession(input: BuilderFlowSessionInput): Pr
   return syncAndProject(context, run);
 }
 
+export async function recoverBuilderFlowSession(input: BuilderFlowSessionInput): Promise<BuilderFlowSessionResult> {
+  const context = resolveSessionContext(input.sessionDir);
+  const sidecarSnapshot = readSidecarSnapshot(context);
+  const subject = workflowSubject(sidecarSnapshot.state);
+  const run = await loadBuilderBuildRun({
+    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");
+  }
+  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: string): Promise<BuilderFlowSessionResult | null> {
   let context: SessionContext;
   try {
@@ -119,8 +164,9 @@ async function syncAndProject(context: SessionContext, initial: BuilderBuildRunR
       }
     }
   }
-  const projection = projectFlowRun(context, run);
-  writeProjection(context, projection);
+  const sidecarSnapshot = readSidecarSnapshot(context);
+  const projection = projectFlowRun(context, run, sidecarSnapshot.state);
+  writeProjection(context, projection, sidecarSnapshot.raw, "projection");
   return {
     sessionDir: context.sessionDir,
     projectRoot: context.projectRoot,
@@ -137,6 +183,7 @@ function resolveSessionContext(sessionDirInput: string): SessionContext {
   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");
@@ -145,6 +192,7 @@ function resolveSessionContext(sessionDirInput: string): SessionContext {
   if (!fs.existsSync(stateFile)) {
     throw new BuilderBuildRunInputError("sessionDir", "must contain state.json");
   }
+  assertSafeFile(stateFile, sessionDir, "state.json");
   return {
     sessionDir,
     artifactRoot,
@@ -155,19 +203,22 @@ function resolveSessionContext(sessionDirInput: string): SessionContext {
   };
 }
 
-function readSidecarState(context: SessionContext): AnyRecord {
-  const value = JSON.parse(fs.readFileSync(context.stateFile, "utf8"));
+function readSidecarSnapshot(context: SessionContext): SidecarSnapshot {
+  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: AnyRecord): string {
-  const refs = Array.isArray(state.work_item_refs)
-    ? state.work_item_refs.filter((value: unknown): value is string => 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]!;
@@ -225,8 +276,7 @@ function manifestEvidence(manifest: JsonObject): AnyRecord[] {
   return Array.isArray(manifest.evidence) ? manifest.evidence.filter(isRecord) : [];
 }
 
-function projectFlowRun(context: SessionContext, run: BuilderBuildRunResult): AnyRecord {
-  const sidecar = readSidecarState(context);
+function projectFlowRun(context: SessionContext, run: BuilderBuildRunResult, sidecar: AnyRecord): AnyRecord {
   const definition = JSON.parse(fs.readFileSync(path.join(run.dir, "definition.json"), "utf8"));
   const gates = openGates(definition, run.state) as Array<FlowGate & { id: string }>;
   const complete = run.state.status === "completed";
@@ -279,23 +329,164 @@ function projectFlowRun(context: SessionContext, run: BuilderBuildRunResult): An
   };
 }
 
-function writeProjection(context: SessionContext, projection: AnyRecord): void {
-  fs.writeFileSync(context.stateFile, `${JSON.stringify(projection, null, 2)}\n`);
-  const pointerFiles = [path.join(context.artifactRoot, "current.json")];
+function writeProjection(context: SessionContext, projection: AnyRecord, expectedStateRaw: string, operation: string): void {
+  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: SessionContext,
+  projection: AnyRecord,
+  expectedStateRaw: string,
+  operation: string,
+): PreparedProjectionWrites {
+  const targets: ProjectionTargetSnapshot[] = [];
+  const writes: Array<{ file: string; content: string }> = [];
+  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: string[] = [];
+  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: string[] | null = 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: SessionContext,
+  prepared: PreparedProjectionWrites,
+  operation: string,
+): void {
+  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: string, root: string, field: string): ProjectionTargetSnapshot {
+  if (!pathExistsNoFollow(file)) return { file, raw: null, root, field };
+  return readProjectionTarget(file, root, field);
+}
+
+function readProjectionTarget(file: string, root: string, field: string): ProjectionTargetSnapshot {
+  assertSafeFile(file, root, field);
+  return { file, raw: fs.readFileSync(file, "utf8"), root, field };
+}
+
+function parseProjectionTarget(target: ProjectionTargetSnapshot): unknown {
+  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: string, root: string, field: string): void {
+  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: string): boolean {
+  try {
+    fs.lstatSync(candidate);
+    return true;
+  } catch (error) {
+    if (isRecord(error) && error.code === "ENOENT") return false;
+    throw error;
+  }
+}
+
+function assertSafeFile(file: string, root: string, field: string): void {
+  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: string, root: string, field: string): void {
+  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: string, root: string): boolean {
+  const relative = path.relative(root, candidate);
+  return relative === "" || (!relative.startsWith(`..${path.sep}`) && relative !== ".." && !path.isAbsolute(relative));
+}
+
+function writeExistingFileNoFollow(file: string, content: string): void {
+  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);
   }
 }