@kontourai/flow-agents 3.4.3 → 3.5.0

package/evals/integration/test_builder_entry_enforcement.sh

@@ -50,6 +50,48 @@ else
   fail "symlinked Builder root wrote externally or returned the wrong diagnostic: $(cat "$TMP/symlink-root.out")"
 fi
 
+SESSION_SYMLINK_PROJECT="$TMP/session-symlink-project"
+SESSION_SYMLINK_ROOT="$SESSION_SYMLINK_PROJECT/.kontourai/flow-agents"
+SESSION_SYMLINK_EXTERNAL="$TMP/session-symlink-external"
+mkdir -p "$SESSION_SYMLINK_ROOT" "$SESSION_SYMLINK_EXTERNAL"
+ln -s "$SESSION_SYMLINK_EXTERNAL" "$SESSION_SYMLINK_ROOT/session-symlink"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$SESSION_SYMLINK_ROOT" \
+  --task-slug session-symlink \
+  --actor builder-entry-session-symlink \
+  --title "Session symlink" \
+  --summary "Session state must not escape the artifact root." \
+  --flow-id builder.build >"$TMP/session-symlink.out" 2>&1; then
+  fail "symlinked session directory should be rejected"
+elif [[ -z "$(find "$SESSION_SYMLINK_EXTERNAL" -mindepth 1 -print -quit)" ]] \
+  && grep -q 'session directory must be a real directory under the artifact root' "$TMP/session-symlink.out"; then
+  pass "symlinked session directory is rejected before external reads or writes"
+else
+  fail "symlinked session directory escaped or returned the wrong diagnostic: $(cat "$TMP/session-symlink.out")"
+fi
+
+NESTED_PROJECT="$TMP/nested-symlink-project"
+NESTED_ROOT="$NESTED_PROJECT/.kontourai/flow-agents"
+NESTED_EXTERNAL="$TMP/nested-symlink-external.json"
+mkdir -p "$NESTED_ROOT/assignment"
+printf 'external must survive\n' >"$NESTED_EXTERNAL"
+ln -s "$NESTED_EXTERNAL" "$NESTED_ROOT/assignment/nested-symlink.json"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$NESTED_ROOT" \
+  --task-slug nested-symlink \
+  --actor builder-entry-nested-symlink \
+  --title "Nested assignment symlink" \
+  --summary "Assignment evidence must stay inside the product root." \
+  --flow-id builder.build >"$TMP/nested-symlink.out" 2>&1; then
+  fail "symlinked assignment record should be rejected"
+elif [[ "$(cat "$NESTED_EXTERNAL")" == "external must survive" ]] \
+  && [[ ! -e "$NESTED_ROOT/nested-symlink" ]] \
+  && grep -q 'assignment record must be a regular file, not a symlink' "$TMP/nested-symlink.out"; then
+  pass "nested assignment symlink is rejected before external write or trust evidence"
+else
+  fail "nested assignment symlink escaped or returned the wrong diagnostic: $(cat "$TMP/nested-symlink.out")"
+fi
+
 RACE_PROJECT="$TMP/race-project"
 RACE_ROOT="$RACE_PROJECT/.kontourai/flow-agents"
 RACE_MOVED="$RACE_PROJECT/.kontourai/flow-agents-acquired"
@@ -146,6 +188,7 @@ LOCAL_ROOT="$TMP/local/.kontourai/flow-agents"
 if flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$LOCAL_ROOT" \
   --task-slug local-request \
+  --actor builder-entry-local \
   --title "Local request" \
   --summary "Providerless work still needs an anchor." \
   --flow-id builder.build \
@@ -158,19 +201,24 @@ const current = JSON.parse(fs.readFileSync(path.join(root, 'current.json'), 'utf
 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 (current.active_flow_id !== 'builder.build' || current.active_step_id !== 'design-probe') process.exit(1);
+if (state.status !== 'in_progress' || 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 (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 (flowState.current_step !== 'design-probe' || flowState.subject !== 'local:local-request') process.exit(1);
+if (state.flow_run?.current_step !== 'design-probe') process.exit(1);
+if (JSON.stringify(state.next_action?.skills) !== JSON.stringify(['pickup-probe'])) process.exit(1);
 if (!state.next_action?.command?.includes('builder-run sync')) process.exit(1);
 if ('enforcement' in state.next_action) process.exit(1);
+const bundle = JSON.parse(fs.readFileSync(path.join(root, 'local-request', 'trust.bundle'), 'utf8'));
+const selected = (bundle.claims || []).find((claim) => claim.claimType === 'builder.pull-work.selected');
+if (selected?.status !== 'verified') process.exit(1);
+if (selected?.metadata?.workflow_subject_ref !== 'local:local-request') process.exit(1);
+if (!(selected?.metadata?.artifact_refs || []).some((ref) => ref.file === '.kontourai/flow-agents/assignment/local-request.json')) process.exit(1);
 NODE
   then
-    pass "providerless request creates a local Work Item and canonical Flow run at pull-work"
+    pass "durably acquired local Work Item satisfies pull-work through the trust bundle and Flow advances"
   else
     fail "local Work Item or first-step state is invalid"
   fi
@@ -183,6 +231,7 @@ FLOW_DIGEST_BEFORE="$(find "$TMP/local/.kontourai/flow/runs/local-request" -type
 if flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$LOCAL_ROOT" \
   --task-slug local-request \
+  --actor builder-entry-local \
   --title "Local request" \
   --summary "Providerless work still needs an anchor." \
   --flow-id builder.build \
@@ -195,9 +244,9 @@ const project = process.argv[2];
 const session = process.argv[3];
 const flowState = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow', 'runs', 'local-request', 'state.json'), 'utf8'));
 const sidecar = JSON.parse(fs.readFileSync(path.join(session, 'state.json'), 'utf8'));
-if (flowState.current_step !== 'pull-work' || flowState.subject !== 'local:local-request') process.exit(1);
-if (sidecar.flow_run?.current_step !== 'pull-work') process.exit(1);
-if (JSON.stringify(sidecar.next_action?.skills) !== JSON.stringify(['pull-work'])) process.exit(1);
+if (flowState.current_step !== 'design-probe' || flowState.subject !== 'local:local-request') process.exit(1);
+if (sidecar.flow_run?.current_step !== 'design-probe') process.exit(1);
+if (JSON.stringify(sidecar.next_action?.skills) !== JSON.stringify(['pickup-probe'])) process.exit(1);
 if (!sidecar.next_action?.command?.includes('builder-run sync')) process.exit(1);
 NODE
 then
@@ -213,14 +262,15 @@ 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 \
+  --actor builder-entry-broken \
   --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" \
+  && grep -q 'canonical Builder Flow entry failed' "$TMP/broken-start.out" \
+  && grep -q 'Re-run the same ensure-session command' "$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'));
@@ -233,13 +283,30 @@ else
   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" \
-  --expectation selected-work \
-  --status pass \
-  --summary "Selected local:local-request with scope and acceptance context." \
-  --evidence-ref-json '{"kind":"artifact","file":".kontourai/flow-agents/local-request/work-item.json","summary":"Provider-neutral local Work Item."}' \
-  >"$TMP/selected-work.out" 2>&1 \
-  && node - "$TMP/local" "$LOCAL_SESSION" <<'NODE'
+rm -f "$BROKEN_PROJECT/.kontourai/flow"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$BROKEN_ROOT" \
+  --task-slug broken-start \
+  --actor builder-entry-broken \
+  --title "Broken start" \
+  --summary "Flow startup must recover from persisted acquisition provenance." \
+  --flow-id builder.build >"$TMP/broken-start-retry.out" 2>&1 \
+  && node - "$BROKEN_PROJECT" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const project = process.argv[2];
+const flowState = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow', 'runs', 'broken-start', 'state.json'), 'utf8'));
+const bundle = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow-agents', 'broken-start', 'trust.bundle'), 'utf8'));
+if (flowState.current_step !== 'design-probe') process.exit(1);
+if (!(bundle.claims || []).some((claim) => claim.claimType === 'builder.pull-work.selected' && claim.status === 'verified')) process.exit(1);
+NODE
+then
+  pass "interrupted Flow startup retries from exact persisted acquisition provenance"
+else
+  fail "interrupted acquisition could not recover: $(cat "$TMP/broken-start-retry.out")"
+fi
+
+if node - "$TMP/local" "$LOCAL_SESSION" <<'NODE'
 const fs = require('node:fs');
 const path = require('node:path');
 const project = process.argv[2];
@@ -251,9 +318,158 @@ if (sidecar.flow_run?.current_step !== 'design-probe') process.exit(1);
 if (JSON.stringify(sidecar.next_action?.skills) !== JSON.stringify(['pickup-probe'])) process.exit(1);
 NODE
 then
-  pass "gate-claim write synchronizes Flow and projects the next skill"
+  pass "automatic selected-work claim synchronizes Flow and projects the next skill"
+else
+  fail "automatic selected-work claim did not advance the canonical run"
+fi
+
+SKIPPED_ROOT="$TMP/skipped/.kontourai/flow-agents"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$SKIPPED_ROOT" \
+  --task-slug skipped-ownership \
+  --actor builder-entry-skipped \
+  --skip-ownership-guard \
+  --title "Skipped ownership" \
+  --summary "Unproven ownership must remain at pull-work." \
+  --flow-id builder.build >"$TMP/skipped.out" 2>&1 \
+  && node - "$TMP/skipped" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const project = process.argv[2];
+const session = path.join(project, '.kontourai', 'flow-agents', 'skipped-ownership');
+const flowState = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow', 'runs', 'skipped-ownership', 'state.json'), 'utf8'));
+const sidecar = JSON.parse(fs.readFileSync(path.join(session, 'state.json'), 'utf8'));
+if (flowState.current_step !== 'pull-work' || sidecar.flow_run?.current_step !== 'pull-work') process.exit(1);
+if (JSON.stringify(sidecar.next_action?.skills) !== JSON.stringify(['pull-work'])) process.exit(1);
+if (fs.existsSync(path.join(session, 'trust.bundle'))) process.exit(1);
+if (fs.existsSync(path.join(project, '.kontourai', 'flow-agents', 'assignment', 'skipped-ownership.json'))) process.exit(1);
+NODE
+then
+  pass "skipped ownership remains at pull-work without selected-work evidence"
+else
+  fail "unproven ownership advanced the canonical run: $(cat "$TMP/skipped.out")"
+fi
+
+MISMATCH_ROOT="$TMP/mismatched-subject/.kontourai/flow-agents"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$MISMATCH_ROOT" \
+  --task-slug arbitrary-session-name \
+  --work-item "kontourai/flow-agents#541" \
+  --actor builder-entry-mismatch \
+  --title "Mismatched assignment subject" \
+  --summary "An arbitrary slug is not exact Work Item evidence." \
+  --flow-id builder.build >"$TMP/mismatched-subject.out" 2>&1 \
+  && node - "$TMP/mismatched-subject" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const project = process.argv[2];
+const session = path.join(project, '.kontourai', 'flow-agents', 'arbitrary-session-name');
+const flowState = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow', 'runs', 'arbitrary-session-name', 'state.json'), 'utf8'));
+const sidecar = JSON.parse(fs.readFileSync(path.join(session, 'state.json'), 'utf8'));
+if (flowState.subject !== 'kontourai/flow-agents#541' || flowState.current_step !== 'pull-work') process.exit(1);
+if (sidecar.flow_run?.current_step !== 'pull-work') process.exit(1);
+if (fs.existsSync(path.join(session, 'trust.bundle'))) process.exit(1);
+if (!fs.existsSync(path.join(project, '.kontourai', 'flow-agents', 'assignment', 'arbitrary-session-name.json'))) process.exit(1);
+NODE
+then
+  pass "assignment subject must canonically match the exact Work Item before pull-work can pass"
+else
+  fail "mismatched assignment subject was treated as exact Work Item evidence: $(cat "$TMP/mismatched-subject.out")"
+fi
+
+COLLISION_ROOT="$TMP/collision/.kontourai/flow-agents"
+if ! flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$COLLISION_ROOT" \
+  --work-item "owner/a.b#541" \
+  --actor builder-entry-collision \
+  --title "Collision seed" \
+  --summary "Bind the first exact Work Item." >/dev/null 2>&1; then
+  fail "collision fixture could not seed the first exact Work Item"
+else
+  COLLISION_ASSIGNMENT="$COLLISION_ROOT/assignment/owner-a-b-541.json"
+  COLLISION_DIGEST="$(shasum -a 256 "$COLLISION_ASSIGNMENT")"
+  if flow_agents_node "$WRITER" ensure-session \
+    --artifact-root "$COLLISION_ROOT" \
+    --work-item "owner/a-b#541" \
+    --actor builder-entry-collision \
+    --title "Collision attempt" \
+    --summary "A colliding slug must not change the exact Work Item." \
+    --flow-id builder.build >"$TMP/collision.out" 2>&1; then
+    fail "colliding exact Work Item refs should be rejected"
+  elif grep -q 'already bound to Work Item "owner/a.b#541", not "owner/a-b#541"' "$TMP/collision.out" \
+    && [[ "$COLLISION_DIGEST" == "$(shasum -a 256 "$COLLISION_ASSIGNMENT")" ]] \
+    && [[ ! -e "$TMP/collision/.kontourai/flow/runs/owner-a-b-541" ]]; then
+    pass "colliding slugs cannot change an existing session's exact Work Item binding"
+  else
+    fail "slug collision mutated ownership or returned the wrong diagnostic: $(cat "$TMP/collision.out")"
+  fi
+fi
+
+ASSIGNMENT_ONLY_ROOT="$TMP/assignment-only-collision/.kontourai/flow-agents"
+mkdir -p "$ASSIGNMENT_ONLY_ROOT/assignment"
+cat >"$ASSIGNMENT_ONLY_ROOT/assignment/owner-a-b-542.json" <<'JSON'
+{
+  "schema_version": "1.0",
+  "role": "AssignmentClaimRecord",
+  "subject_id": "owner-a-b-542",
+  "actor": { "runtime": "codex", "session_id": "interrupted", "host": "eval-host", "human": null },
+  "actor_key": "interrupted",
+  "work_item_ref": "owner/a.b#542",
+  "claimed_at": "2020-01-01T00:00:00Z",
+  "ttl_seconds": 1,
+  "branch": "agent/interrupted/owner-a-b-542",
+  "artifact_dir": "owner-a-b-542",
+  "status": "claimed",
+  "audit_trail": []
+}
+JSON
+ASSIGNMENT_ONLY_FILE="$ASSIGNMENT_ONLY_ROOT/assignment/owner-a-b-542.json"
+ASSIGNMENT_ONLY_DIGEST="$(shasum -a 256 "$ASSIGNMENT_ONLY_FILE")"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$ASSIGNMENT_ONLY_ROOT" \
+  --work-item "owner/a-b#542" \
+  --actor builder-entry-assignment-only-collision \
+  --supersede-stale \
+  --now "2026-07-10T00:00:00Z" \
+  --title "Assignment-only collision" \
+  --summary "A crash before state creation must preserve exact assignment identity." \
+  --flow-id builder.build >"$TMP/assignment-only-collision.out" 2>&1; then
+  fail "assignment-only colliding Work Item should be rejected"
+elif grep -q 'already bound to Work Item "owner/a.b#542", not "owner/a-b#542"' "$TMP/assignment-only-collision.out" \
+  && [[ "$ASSIGNMENT_ONLY_DIGEST" == "$(shasum -a 256 "$ASSIGNMENT_ONLY_FILE")" ]] \
+  && [[ ! -e "$ASSIGNMENT_ONLY_ROOT/owner-a-b-542" ]]; then
+  pass "assignment provenance blocks slug collisions before session state exists"
+else
+  fail "assignment-only collision mutated provenance or returned the wrong diagnostic: $(cat "$TMP/assignment-only-collision.out")"
+fi
+
+PREEXISTING_ROOT="$TMP/preexisting/.kontourai/flow-agents"
+if flow_agents_node "$WRITER" ensure-session \
+  --artifact-root "$PREEXISTING_ROOT" \
+  --task-slug preexisting-selection \
+  --actor builder-entry-preexisting \
+  --title "Preexisting selection" \
+  --summary "Seed an assignment before the canonical Builder run." >/dev/null 2>&1 \
+  && flow_agents_node "$WRITER" ensure-session \
+    --artifact-root "$PREEXISTING_ROOT" \
+    --task-slug preexisting-selection \
+    --actor builder-entry-preexisting \
+    --title "Preexisting selection" \
+    --summary "An older self-held assignment is not new selection evidence." \
+    --flow-id builder.build >"$TMP/preexisting.out" 2>&1 \
+  && node - "$TMP/preexisting" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const project = process.argv[2];
+const session = path.join(project, '.kontourai', 'flow-agents', 'preexisting-selection');
+const flowState = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow', 'runs', 'preexisting-selection', 'state.json'), 'utf8'));
+if (flowState.current_step !== 'pull-work') process.exit(1);
+if (fs.existsSync(path.join(session, 'trust.bundle'))) process.exit(1);
+NODE
+then
+  pass "preexisting self-held assignments do not retroactively satisfy pull-work"
 else
-  fail "selected-work claim did not advance the canonical run: $(cat "$TMP/selected-work.out")"
+  fail "preexisting assignment was treated as current selection evidence: $(cat "$TMP/preexisting.out")"
 fi
 
 if FLOW_AGENTS_GOAL_FIT_MODE=block FLOW_AGENTS_GOAL_FIT_MAX_BLOCKS=100000 \

package/evals/integration/test_bundle_install.sh

@@ -881,6 +881,49 @@ else
   _fail "Codex full install lost Builder specialist role routing"
 fi
 
+echo ""
+echo "--- Packed Package Builder Entry ---"
+PACKAGE_CONSUMER="$TMPDIR_EVAL/package-consumer"
+PACKAGE_PROJECT="$TMPDIR_EVAL/package-project"
+PACKAGE_AMBIENT="$TMPDIR_EVAL/package-ambient"
+mkdir -p "$PACKAGE_CONSUMER" "$PACKAGE_PROJECT/.kontourai/flow-agents" "$PACKAGE_AMBIENT/kits/builder/flows"
+cat >"$PACKAGE_AMBIENT/kits/builder/flows/build.flow.json" <<'JSON'
+{
+  "id": "builder.build",
+  "version": "poison-ambient-cwd",
+  "steps": [{ "id": "ambient-poison", "next": null }],
+  "gates": {}
+}
+JSON
+PACKAGE_PACK_LOG="$TMPDIR_EVAL/package-pack.log"
+if (cd "$ROOT_DIR" && npm pack --silent --pack-destination "$TMPDIR_EVAL" >"$PACKAGE_PACK_LOG") \
+  && PACKAGE_TARBALL="$(find "$TMPDIR_EVAL" -maxdepth 1 -type f -name 'kontourai-flow-agents-*.tgz' -print -quit)" \
+  && [[ -n "$PACKAGE_TARBALL" ]] \
+  && npm install --silent --no-audit --no-fund --ignore-scripts --prefix "$PACKAGE_CONSUMER" "$PACKAGE_TARBALL" \
+  && (cd "$PACKAGE_AMBIENT" && node "$PACKAGE_CONSUMER/node_modules/@kontourai/flow-agents/build/src/cli/workflow-sidecar.js" ensure-session \
+    --artifact-root "$PACKAGE_PROJECT/.kontourai/flow-agents" \
+    --task-slug packed-builder-entry \
+    --actor packed-package-consumer \
+    --title "Packed Builder entry" \
+    --summary "Installed package should project pickup-probe." \
+    --flow-id builder.build >/dev/null 2>&1) \
+  && node - "$PACKAGE_PROJECT" <<'NODE'
+const fs = require('node:fs');
+const path = require('node:path');
+const project = process.argv[2];
+const state = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow-agents', 'packed-builder-entry', 'state.json'), 'utf8'));
+const flow = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow', 'runs', 'packed-builder-entry', 'state.json'), 'utf8'));
+const bundle = JSON.parse(fs.readFileSync(path.join(project, '.kontourai', 'flow-agents', 'packed-builder-entry', 'trust.bundle'), 'utf8'));
+if (flow.current_step !== 'design-probe' || state.flow_run?.current_step !== 'design-probe') process.exit(1);
+if (JSON.stringify(state.next_action?.skills) !== JSON.stringify(['pickup-probe'])) process.exit(1);
+if (!(bundle.claims || []).some((claim) => claim.claimType === 'builder.pull-work.selected' && claim.status === 'verified')) process.exit(1);
+NODE
+then
+  _pass "packed npm consumer ignores unrelated ambient Flow definitions and projects pickup-probe"
+else
+  _fail "packed npm consumer did not execute canonical Builder entry"
+fi
+
 if [[ -d "$CODEX_FULL_DEST/.codex/skills/plan-work" && -d "$CODEX_FULL_DEST/.codex/skills/deliver" && -d "$CODEX_FULL_DEST/.codex/skills/agentic-engineering" ]]; then
   _pass "Codex full install ships kit-skills and standalone skills together"
 else

package/evals/integration/test_current_json_per_actor.sh

@@ -377,6 +377,7 @@ flow_agents_node "workflow-sidecar" ensure-session \
   --task-slug gate-actor-a \
   --actor eval-actor-a-session \
   --flow-id builder.build \
+  --skip-ownership-guard \
   --source-request "Actor A is active on a FlowDefinition-driven session." \
   --summary "Actor A, builder.build, pull-work step." \
   --timestamp "2026-07-01T00:00:00Z" \

package/evals/integration/test_dual_emit_flow_step.sh

@@ -258,6 +258,7 @@ if flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$SESSION_ROOT" \
   --task-slug dual-emit-test \
   --flow-id builder.build \
+  --skip-ownership-guard \
   --title "Declared-Only Test" \
   --summary "Test declared-only emit for ADR 0016 P-d." \
   --criterion "Tests pass" \
@@ -348,6 +349,7 @@ if flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$SESSION_ROOT" \
   --task-slug dual-emit-policy \
   --flow-id builder.build \
+  --skip-ownership-guard \
   --title "Declared Policy Test" \
   --summary "Test declared-only policy emit for ADR 0016 P-d." \
   --criterion "Policy passes" \

package/evals/integration/test_flowdef_session_activation.sh

@@ -51,6 +51,7 @@ mkdir -p "$MAIN_AROOT"
 if flow_agents_node "$WRITER" ensure-session \
   --artifact-root "$MAIN_AROOT" \
   --task-slug "$SLUG" \
+  --actor activation-test-actor \
   --title "Step 1 activation test" \
   --summary "Test that --flow-id builder.build activates the FlowDefinition-driven path." \
   --criterion "All gates produce declared claims" \
@@ -65,12 +66,14 @@ 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'));
+const bundle = JSON.parse(fs.readFileSync('$SESSION_DIR/trust.bundle', '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));
+if (c.active_step_id !== 'design-probe') throw new Error('expected active_step_id=design-probe, got ' + c.active_step_id);
+if (flow.status !== 'active' || flow.current_step !== 'design-probe') throw new Error('canonical Flow did not advance through trusted selection: ' + JSON.stringify(flow));
+if (!(bundle.claims || []).some((claim) => claim.claimType === 'builder.pull-work.selected' && claim.status === 'verified')) throw new Error('missing verified selected-work claim');
 console.log('current.json: active_flow_id=' + c.active_flow_id + ' active_step_id=' + c.active_step_id);
 " 2>&1 \
-  && _pass "ensure-session writes current projection and a canonical Flow run at pull-work" \
+  && _pass "ensure-session records trusted selection and projects the canonical Flow run at design-probe" \
   || _fail "ensure-session did not create and project the canonical Flow run"
 
 # ─── TEST 2: advance-state sets active_step_id via phase_map ─────────────────

package/evals/integration/test_goal_fit_escape_hatch.sh

@@ -15,10 +15,10 @@ _pass() { echo "  ✓ $1"; }
 _fail() { echo "  ✗ $1"; errors=$((errors + 1)); }
 
 REPO="$TMPDIR_EVAL/repo"
-mkdir -p "$REPO/.flow-agents/stuck"
+mkdir -p "$REPO/.kontourai/flow-agents/stuck"
 printf '# Test Repo\n' > "$REPO/AGENTS.md"
 printf '# Stuck\n\nbranch: main\nstatus: executing\ntype: deliver\n\n## Plan\n\nTBD.\n' \
-  > "$REPO/.flow-agents/stuck/stuck--deliver.md"
+  > "$REPO/.kontourai/flow-agents/stuck/stuck--deliver.md"
 
 PAYLOAD="{\"hook_event_name\":\"Stop\",\"cwd\":\"$REPO\"}"
 
@@ -54,7 +54,7 @@ c4=$(run_block "$TMPDIR_EVAL/b4.err")
 printf '%s' "$PAYLOAD" | FLOW_AGENTS_GOAL_FIT_MODE=block FLOW_AGENTS_GOAL_FIT_MAX_BLOCKS=3 node "$ROOT/scripts/hooks/stop-goal-fit.js" >/dev/null 2>/dev/null
 # mutate the artifact so the warning set differs
 printf '# Stuck\n\nbranch: main\nstatus: verifying\ntype: deliver\n\n## Plan\n\nDifferent.\n' \
-  > "$REPO/.flow-agents/stuck/stuck--deliver.md"
+  > "$REPO/.kontourai/flow-agents/stuck/stuck--deliver.md"
 cd=$(run_block "$TMPDIR_EVAL/bd.err")
 [[ "$cd" -eq 2 ]] && rg -q 'Stop blocked .* \(block 1; after 3 identical blocks' "$TMPDIR_EVAL/bd.err" \
   && _pass "changed goal-fit gap resets the streak to 1/3" \

package/evals/integration/test_phase_map_and_gate_claim.sh

@@ -129,6 +129,7 @@ flow_agents_node "workflow-sidecar" ensure-session \
   --title "Ensure Default Step" \
   --summary "Test ensure-session default step." \
   --flow-id builder.build \
+  --skip-ownership-guard \
   --timestamp "2026-06-26T00:00:00Z" >/dev/null 2>&1
 
 node -e "
@@ -154,6 +155,7 @@ flow_agents_node "workflow-sidecar" ensure-session \
   --title "Gate Claim Test" \
   --summary "Test gate claim producer." \
   --flow-id builder.build \
+  --skip-ownership-guard \
   --timestamp "2026-06-26T00:00:00Z" >/dev/null 2>&1
 
 flow_agents_node "workflow-sidecar" init-plan "$CLAIM_ROOT/gate-claim/gate-claim--deliver.md" \
@@ -261,6 +263,7 @@ flow_agents_node "workflow-sidecar" ensure-session \
   --title "Tamper Test" \
   --summary "Testing tamper detection." \
   --flow-id builder.build \
+  --skip-ownership-guard \
   --timestamp "2026-06-26T00:00:00Z" >/dev/null 2>&1
 
 flow_agents_node "workflow-sidecar" init-plan "$T_DIR/.kontourai/flow-agents/tamper/tamper--deliver.md" \
@@ -364,6 +367,7 @@ flow_agents_node "workflow-sidecar" ensure-session \
   --title "Clean Test" \
   --summary "Testing clean gate claim." \
   --flow-id builder.build \
+  --skip-ownership-guard \
   --timestamp "2026-06-26T00:00:00Z" >/dev/null 2>&1
 
 flow_agents_node "workflow-sidecar" init-plan "$C_DIR/.kontourai/flow-agents/clean/clean--deliver.md" \

package/evals/integration/test_workflow_sidecar_writer.sh

@@ -4228,6 +4228,7 @@ flow_agents_node "$WRITER" ensure-session \
   --task-slug "$UNRESOLVABLE_SLUG" \
   --actor unresolvable-actor \
   --flow-id builder.build \
+  --skip-ownership-guard \
   --title "Unresolvable FlowDefinition regression" \
   --source-request "Regression: an unresolvable FlowDefinition must die with the dedicated cannot-be-loaded message." \
   --summary "Seed session with a REAL flow so a real stamped gate claim can be recorded." \

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.4.3",
+  "version": "3.5.0",
   "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/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,