@kontourai/flow-agents 3.4.1 → 3.4.3

package/evals/integration/test_builder_entry_enforcement.sh

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

package/evals/integration/test_builder_step_producers.sh

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

package/evals/integration/test_bundle_install.sh

@@ -592,11 +592,12 @@ 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(`workflow bootstrap must not be model-mediated at pre-tool time: ${file}`);
 }
 console.log("ok");
 NODE
 then
-  _pass "installed bundles wire prompt-submit workflow steering across Claude Code, Codex, and Kiro"
+  _pass "installed bundles keep workflow steering advisory and session bootstrap product-owned"
 else
   _fail "installed bundles do not wire prompt-submit workflow steering consistently"
 fi

package/evals/integration/test_current_json_per_actor.sh

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

package/evals/integration/test_dual_emit_flow_step.sh

@@ -34,7 +34,7 @@ cleanup() { rm -rf "$TMP"; }
 trap cleanup EXIT
 
 WRITER="workflow-sidecar"
-SESSION_ROOT="$TMP/.flow-agents"
+SESSION_ROOT="$TMP/.kontourai/flow-agents"
 
 echo "── P-a resolver unit checks ──"
 
@@ -269,11 +269,25 @@ fi
 
 DUAL_DIR="$SESSION_ROOT/dual-emit-test"
 
-flow_agents_node "$WRITER" advance-state "$DUAL_DIR" \
-  --status in_progress --phase verification \
-  --summary "Testing declared-only verify claims." --next-action "Record evidence." \
-  --flow-definition builder.build \
-  --timestamp "2026-06-26T00:00:30Z" >/dev/null 2>&1
+advance_builder_to_verify() {
+  local session_dir="$1"
+  flow_agents_node "$WRITER" record-gate-claim "$session_dir" --status pass --expectation selected-work \
+    --summary "Selected the fixture Work Item." --timestamp "2026-06-26T00:00:10Z" >/dev/null 2>&1 \
+    && flow_agents_node "$WRITER" record-gate-claim "$session_dir" --status pass --expectation pickup-probe-readiness \
+      --summary "Pickup readiness is established." --timestamp "2026-06-26T00:00:20Z" >/dev/null 2>&1 \
+    && flow_agents_node "$WRITER" record-gate-claim "$session_dir" --status pass --expectation probe-decisions-or-accepted-gaps \
+      --summary "Probe decisions are recorded." --timestamp "2026-06-26T00:00:30Z" >/dev/null 2>&1 \
+    && flow_agents_node "$WRITER" record-gate-claim "$session_dir" --status pass --expectation implementation-plan \
+      --summary "Implementation plan is recorded." --timestamp "2026-06-26T00:00:40Z" >/dev/null 2>&1 \
+    && flow_agents_node "$WRITER" record-gate-claim "$session_dir" --status pass --expectation implementation-scope \
+      --summary "Implementation scope is recorded." --timestamp "2026-06-26T00:00:50Z" >/dev/null 2>&1
+}
+
+if advance_builder_to_verify "$DUAL_DIR"; then
+  _pass "canonical Builder Flow advances through required gates to verify"
+else
+  _fail "canonical Builder Flow did not reach verify"
+fi
 
 # Verify current.json carries the flow keys
 if node -e "
@@ -328,8 +342,26 @@ fi
 echo ""
 echo "── P-d declared-only: policy-kind check maps to builder.verify.policy-compliance ──"
 
-# Record a policy check with the same flow context
-if flow_agents_node "$WRITER" record-evidence "$DUAL_DIR" \
+# Use a separate canonical run because the failing tests evidence above legitimately
+# routes its run back to execute before this independent producer assertion.
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$SESSION_ROOT" \
+  --task-slug dual-emit-policy \
+  --flow-id builder.build \
+  --title "Declared Policy Test" \
+  --summary "Test declared-only policy emit for ADR 0016 P-d." \
+  --criterion "Policy passes" \
+  --timestamp "2026-06-26T00:01:30Z" >/dev/null 2>&1 \
+  && advance_builder_to_verify "$SESSION_ROOT/dual-emit-policy"; then
+  _pass "policy fixture canonical Builder Flow reaches verify"
+else
+  _fail "policy fixture canonical Builder Flow did not reach verify"
+fi
+
+POLICY_DIR="$SESSION_ROOT/dual-emit-policy"
+POLICY_BUNDLE="$POLICY_DIR/trust.bundle"
+
+if flow_agents_node "$WRITER" record-evidence "$POLICY_DIR" \
   --verdict pass \
   --check-json '{"id":"policy-check","kind":"policy","status":"pass","summary":"Policy compliance passed"}' \
   --timestamp "2026-06-26T00:02:00Z" >"$TMP/policy-evidence.out" 2>"$TMP/policy-evidence.err"; then
@@ -340,7 +372,7 @@ fi
 
 if node -e "
 const fs = require('fs');
-const bundle = JSON.parse(fs.readFileSync('${BUNDLE}', 'utf8'));
+const bundle = JSON.parse(fs.readFileSync('${POLICY_BUNDLE}', 'utf8'));
 const claims = bundle.claims;
 // Declared claim for policy kind should be builder.verify.policy-compliance
 const policyDeclared = claims.find(c => c.claimType === 'builder.verify.policy-compliance');

package/evals/integration/test_flowdef_session_activation.sh

@@ -43,29 +43,35 @@ WRITER="workflow-sidecar"
 echo ""
 echo "=== 1. ensure-session --flow-id builder.build activates FlowDefinition-driven path ==="
 
-MAIN_AROOT="$TMP/main-aroot"
+MAIN_AROOT="$TMP/main-project/.kontourai/flow-agents"
 SLUG="activation-test"
 SESSION_DIR="$MAIN_AROOT/$SLUG"
 mkdir -p "$MAIN_AROOT"
 
-flow_agents_node "$WRITER" ensure-session \
+if flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$MAIN_AROOT" \
   --task-slug "$SLUG" \
   --title "Step 1 activation test" \
   --summary "Test that --flow-id builder.build activates the FlowDefinition-driven path." \
   --criterion "All gates produce declared claims" \
   --flow-id builder.build \
-  --timestamp "2026-06-01T00:00:00Z" >/dev/null 2>&1
+  --timestamp "2026-06-01T00:00:00Z" >/dev/null 2>&1; then
+  _pass "ensure-session starts the canonical Builder Flow from a canonical artifact root"
+else
+  _fail "ensure-session failed to start the canonical Builder Flow"
+fi
 
 node -e "
 const fs = require('fs');
 const c = JSON.parse(fs.readFileSync('$MAIN_AROOT/current.json', 'utf8'));
+const flow = JSON.parse(fs.readFileSync('$TMP/main-project/.kontourai/flow/runs/$SLUG/state.json', 'utf8'));
 if (c.active_flow_id !== 'builder.build') throw new Error('expected active_flow_id=builder.build, got ' + c.active_flow_id);
 if (!c.active_step_id) throw new Error('expected active_step_id to be set (first step default), got ' + c.active_step_id);
+if (flow.status !== 'active' || flow.current_step !== 'pull-work') throw new Error('canonical Flow did not start at pull-work: ' + JSON.stringify(flow));
 console.log('current.json: active_flow_id=' + c.active_flow_id + ' active_step_id=' + c.active_step_id);
 " 2>&1 \
-  && _pass "ensure-session --flow-id builder.build writes active_flow_id + default active_step_id to current.json" \
-  || _fail "ensure-session --flow-id builder.build did NOT write active_flow_id to current.json"
+  && _pass "ensure-session writes current projection and a canonical Flow run at pull-work" \
+  || _fail "ensure-session did not create and project the canonical Flow run"
 
 # ─── TEST 2: advance-state sets active_step_id via phase_map ─────────────────
 echo ""

package/evals/integration/test_install_merge.sh

@@ -47,6 +47,30 @@ else
 fi
 echo ""
 
+# The 3.4.2 bootstrap hook is intentionally absent from new bundles, but its
+# marker remains an ownership tombstone so upgrades remove the retired denial.
+if node - "$ROOT_DIR/scripts/install-merge.js" <<'NODE'
+const { mergeSettings, isManagedHookGroup } = require(process.argv[2]);
+const retired = { hooks: [{ type: "command", command: "old-flow-agents-entry", statusMessage: "Enforcing Flow Agents projected action" }] };
+const user = { hooks: [{ type: "command", command: "user-pretool" }] };
+const current = { hooks: [{ type: "command", command: "new-flow-agents", statusMessage: "Running Flow Agents hook policy" }] };
+if (!isManagedHookGroup(retired)) throw new Error("retired hook marker is no longer recognized as managed");
+const merged = mergeSettings(
+  { hooks: { PreToolUse: [retired, user] } },
+  { hooks: { UserPromptSubmit: [current] } },
+);
+const text = JSON.stringify(merged);
+if (text.includes("old-flow-agents-entry")) throw new Error("retired bootstrap hook survived upgrade");
+if (!text.includes("user-pretool")) throw new Error("user-owned PreToolUse hook was removed");
+if (!text.includes("new-flow-agents")) throw new Error("current managed hook was not installed");
+NODE
+then
+  _pass "upgrade removes the retired 3.4.2 bootstrap hook while preserving user hooks"
+else
+  _fail "upgrade did not cleanly replace the retired 3.4.2 bootstrap hook"
+fi
+echo ""
+
 # ─── Scenario 1: Seeded user config ──────────────────────────────────────────
 echo "--- Scenario 1: Seeded user config (user keys + non-FA hook survive) ---"
 

package/evals/integration/test_phase_map_and_gate_claim.sh

@@ -8,7 +8,8 @@
 #   4. record-gate-claim at pull-work step produces builder.pull-work.selected claim (status=verified).
 #   5. A TAMPERED bundle (stored verified, evidence fail) at pull-work step BLOCKS (exit 2)
 #      with the tamper warning naming the declared claimType.
-#   6. A CLEAN record-gate-claim bundle (passing evidence → verified) is NOT blocked.
+#   6. A CLEAN record-gate-claim bundle is not reported as false completion;
+#      its still-active canonical Flow run remains blocked from stopping.
 #
 # Deterministic, no model spend, self-cleaning.
 # Usage: bash evals/integration/test_phase_map_and_gate_claim.sh
@@ -119,7 +120,7 @@ test_advance_state "learning"     "learn"
 echo ""
 echo "=== 3. ensure-session --flow-id builder.build defaults to pull-work ==="
 
-ENSURE_ROOT="$TMP/ensure-test"
+ENSURE_ROOT="$TMP/ensure-project/.kontourai/flow-agents"
 mkdir -p "$ENSURE_ROOT"
 
 flow_agents_node "workflow-sidecar" ensure-session \
@@ -144,7 +145,7 @@ node -e "
 echo ""
 echo "=== 4. record-gate-claim produces builder.pull-work.selected claim ==="
 
-CLAIM_ROOT="$TMP/gate-claim-test"
+CLAIM_ROOT="$TMP/gate-claim-project/.kontourai/flow-agents"
 mkdir -p "$CLAIM_ROOT"
 
 flow_agents_node "workflow-sidecar" ensure-session \
@@ -192,7 +193,7 @@ node -e "
 echo ""
 echo "=== 4b. composed publish-learn gate claim emits builder.pr-open.pull-request ==="
 
-COMPOSED_ROOT="$TMP/composed-gate-claim-test"
+COMPOSED_ROOT="$TMP/composed-gate-claim-project/.kontourai/flow-agents"
 mkdir -p "$COMPOSED_ROOT"
 
 flow_agents_node "workflow-sidecar" ensure-session \
@@ -200,7 +201,6 @@ flow_agents_node "workflow-sidecar" ensure-session \
   --task-slug composed-gate-claim \
   --title "Composed Gate Claim Test" \
   --summary "Test composed Builder publish/learn flow producer." \
-  --flow-id builder.build \
   --timestamp "2026-06-26T00:00:00Z" >/dev/null 2>&1
 
 flow_agents_node "workflow-sidecar" init-plan "$COMPOSED_ROOT/composed-gate-claim/composed-gate-claim--deliver.md" \
@@ -350,9 +350,9 @@ else
   _fail "tamper warning does not name claimType: $tamper_out"
 fi
 
-# ─── Clean gate-claim: passing evidence → NOT blocked ────────────────────────
+# ─── Clean gate-claim: no false completion, active Flow still blocks ─────────
 echo ""
-echo "=== 6. CLEAN record-gate-claim (passing evidence → verified) → NOT BLOCKED ==="
+echo "=== 6. CLEAN record-gate-claim remains governed by active canonical Flow ==="
 
 C_DIR="$TMP/clean-test"
 mkdir -p "$C_DIR"
@@ -400,10 +400,10 @@ clean_out="$(FLOW_AGENTS_GOAL_FIT_MODE=block FLOW_AGENTS_GOAL_FIT_BACKSTOP=skip
 clean_exit="$?"
 set -e
 
-if [ "$clean_exit" -ne 2 ]; then
-  _pass "clean builder.pull-work.selected bundle not blocked (exit $clean_exit)"
+if [ "$clean_exit" -eq 2 ] && echo "$clean_out" | grep -q 'release skipped for active Flow run "clean"'; then
+  _pass "clean claim advances to the next Flow step and active run blocks premature Stop"
 else
-  _fail "clean builder.pull-work.selected bundle false-blocked (exit 2): $clean_out"
+  _fail "clean active Flow run returned the wrong Stop decision (exit $clean_exit): $clean_out"
 fi
 
 if echo "$clean_out" | grep -q "caught false-completion"; then

package/evals/integration/test_resolvefirststep_security.sh

@@ -185,7 +185,7 @@ fi
 echo ""
 echo "=== 4. Legit --flow-id builder.build → active_step_id set (first step resolved) ==="
 
-LEGIT_AROOT="$TMP/legit-aroot"
+LEGIT_AROOT="$TMP/legit-project/.kontourai/flow-agents"
 mkdir -p "$LEGIT_AROOT"
 
 set +e

package/evals/integration/test_sidecar_field_preservation.sh

@@ -85,13 +85,15 @@ _assert_preserved() {
   [[ "$ok" -eq 1 ]] && _pass "persistent identity fields (${FIELDS[*]}) survive $label"
 }
 
-# ─── Seed: ensure-session with an injected actor (derived branch) and a KNOWN timestamp ──────
+# ─── Seed: standalone sidecar session with an injected actor and a KNOWN timestamp ──────────
+# This sweep tests sidecar writer preservation. Canonical Flow startup and transitions are
+# covered separately; advance-state below activates Builder FlowDefinition claim typing without
+# creating a run that would legitimately project over this fixture's synthetic phase sequence.
 SEED_TS="2026-06-20T08:00:00Z"
 if ! flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$SESSION_ROOT" \
   --task-slug "$SLUG" \
   --actor sweep-actor \
-  --flow-id builder.build \
   --title "Sidecar Field Preservation Sweep" \
   --source-request "Seed a fully-populated session for the field-preservation invariant sweep." \
   --summary "Seed session for the class-level field-preservation sweep." \

package/evals/integration/test_takeover_protocol.sh

@@ -40,7 +40,7 @@ WRITER="workflow-sidecar"
 
 TMPDIR_EVAL="$(mktemp -d)"
 trap 'rm -rf "$TMPDIR_EVAL"' EXIT
-ARTIFACT_ROOT="$TMPDIR_EVAL/artifact-root"
+ARTIFACT_ROOT="$TMPDIR_EVAL/project/.kontourai/flow-agents"
 
 errors=0
 pass() { echo "  [PASS] $1"; }

package/evals/integration/test_workflow_sidecar_writer.sh

@@ -3437,7 +3437,7 @@ fi
 # ─── #270/#298 compose layer: gate-claim accumulation, gate-claim typing survives rebuild, ──
 # compose-two/three/four-writer round-trip, waiver + artifact_refs/standard_refs round-trip,
 # runnability rejection at record time (AC1-AC6, AC8, AC10) ──────────────────────────────────
-COMPOSE_ROOT="$TMPDIR_EVAL/compose-root"
+COMPOSE_ROOT="$TMPDIR_EVAL/compose-project/.kontourai/flow-agents"
 COMPOSE_SLUG="compose-270"
 COMPOSE_DIR="$COMPOSE_ROOT/$COMPOSE_SLUG"
 mkdir -p "$COMPOSE_ROOT"
@@ -3446,13 +3446,24 @@ flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$COMPOSE_ROOT" \
   --task-slug "$COMPOSE_SLUG" \
   --actor compose-actor \
-  --flow-id builder.build \
   --title "Compose layer session" \
   --source-request "Compose-safe writer layer smoke session." \
   --summary "Seed session for compose-layer round-trip assertions." \
   --criterion "Compose layer round-trips losslessly" \
   --timestamp "2026-07-05T09:00:00Z" >"$TMPDIR_EVAL/compose-seed.out" 2>"$TMPDIR_EVAL/compose-seed.err"
 
+# This fixture exercises sidecar writer composition, not canonical run
+# transitions. Activate FlowDefinition claim typing through the standalone
+# transition primitive so preliminary generic evidence cannot advance Flow.
+flow_agents_node "$WRITER" advance-state "$COMPOSE_DIR" \
+  --actor compose-actor \
+  --status in_progress \
+  --phase pickup \
+  --summary "Compose writer fixture at pull-work." \
+  --next-action "Record composed claims." \
+  --flow-definition builder.build \
+  --timestamp "2026-07-05T09:00:30Z" >"$TMPDIR_EVAL/compose-activate.out" 2>"$TMPDIR_EVAL/compose-activate.err"
+
 _compose_claims_json() {
   cat "$COMPOSE_DIR/trust.bundle"
 }
@@ -4157,7 +4168,7 @@ fi
 # misclassified as an unstamped pre-cluster-270 gate claim on the NEXT rebuild — is now rejected
 # AT RECORD TIME instead, in a FRESH session (isolated from COMPOSE_DIR) so no rebuild landmine
 # is ever created.
-COLLISION_ROOT="$TMPDIR_EVAL/collision-root"
+COLLISION_ROOT="$TMPDIR_EVAL/collision-project/.kontourai/flow-agents"
 COLLISION_SLUG="collision-270"
 COLLISION_DIR="$COLLISION_ROOT/$COLLISION_SLUG"
 mkdir -p "$COLLISION_ROOT"
@@ -4207,7 +4218,7 @@ fi
 # (real flow, real record-gate-claim), then break resolution by pointing active_flow_id at a
 # bogus flow id that cannot resolve under kits/ (mirrors the re-reviewer's approach of pointing
 # at an unresolvable kits/ path), in an ISOLATED fixture copied from a fresh session.
-UNRESOLVABLE_ROOT="$TMPDIR_EVAL/unresolvable-root"
+UNRESOLVABLE_ROOT="$TMPDIR_EVAL/unresolvable-project/.kontourai/flow-agents"
 UNRESOLVABLE_SLUG="unresolvable-270"
 UNRESOLVABLE_DIR="$UNRESOLVABLE_ROOT/$UNRESOLVABLE_SLUG"
 mkdir -p "$UNRESOLVABLE_ROOT"
@@ -4327,7 +4338,7 @@ fi
 # label, exactly the real kontourai-flow-agents-270 wedge this closes) can NEVER be corrected:
 # every attempt to re-record that exact id — the only way to supersede/fix it — is itself
 # rejected by the guard, permanently wedging that id and blocking publish-preflight forever.
-CORRECTION_ROOT="$TMPDIR_EVAL/correction-root"
+CORRECTION_ROOT="$TMPDIR_EVAL/correction-project/.kontourai/flow-agents"
 CORRECTION_SLUG="correction-270"
 CORRECTION_DIR="$CORRECTION_ROOT/$CORRECTION_SLUG"
 mkdir -p "$CORRECTION_ROOT"
@@ -4479,7 +4490,7 @@ fi
 # check_kind so the replacement claim can be shaped to evade gateClaimShapeUnstampedId's detector
 # (which requires check_kind==="external"). This eval reproduces that exact attack end-to-end
 # against the CURRENT (narrowed) binary and asserts it now dies, with the stamp intact afterward.
-STAMPED_ROOT="$TMPDIR_EVAL/stamped-claim-root"
+STAMPED_ROOT="$TMPDIR_EVAL/stamped-claim-project/.kontourai/flow-agents"
 STAMPED_SLUG="stamped-claim-270"
 STAMPED_DIR="$STAMPED_ROOT/$STAMPED_SLUG"
 mkdir -p "$STAMPED_ROOT"

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.1",
+  "version": "3.4.3",
   "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,14 @@
         "command": {
           "type": "string",
           "minLength": 1
+        },
+        "enforcement": {
+          "description": "Deprecated compatibility field. Runtime steering ignores this value; session orchestration owns Builder Flow startup.",
+          "type": "string",
+          "enum": [
+            "advisory",
+            "before_tool_use"
+          ]
         }
       }
     }

package/scripts/install-merge.js

@@ -41,13 +41,16 @@ 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",
+  // Cleanup tombstone: 3.4.2 installed this retired PreToolUse hook. Keep the
+  // marker recognizable so upgrades remove it even though new bundles do not.
+  "Enforcing Flow Agents projected action",
 ];
 
 const FA_OWNERSHIP_MARKERS = [