@kontourai/flow-agents 3.9.0 → 3.10.0

package/evals/integration/test_verify_hold.sh

@@ -46,6 +46,7 @@
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CURRENT_POINTER_HELPER="$ROOT/scripts/hooks/lib/current-pointer.js"
 source "$ROOT/evals/lib/node.sh"
 
 CLI="$ROOT/build/src/cli.js"
@@ -196,6 +197,31 @@ write_steering_fixture_repo() {
   mv "$repoRoot/.kontourai/flow-agents/$slug/state.dot.json.tmp" "$repoRoot/.kontourai/flow-agents/$slug/state.json"
 }
 
+# seed_current_pointer <repo_root> <slug> <actor> — #440 FIXTURE-GAP: this suite's
+# write_steering_fixture_repo fixtures were written before #440's per-actor ownership scoping and
+# never establish a per-actor current pointer for the invoking actor -- under a RESOLVED
+# FLOW_AGENTS_ACTOR override, workflow-steering.js's actorScopedWorkflowState now scopes to that
+# actor's own (nonexistent) pointer and never reaches the fixture-under-test. Seeds BOTH the
+# legacy current.json AND the per-actor current/<actor>.json pointer with the SAME payload,
+# mirroring workflow-sidecar.ts's real writeCurrent() dual-write via current-pointer.js's own
+# writePerActorCurrent.
+seed_current_pointer() {
+  local repoRoot="$1" slug="$2" actor="$3"
+  local flowAgentsDir="$repoRoot/.kontourai/flow-agents"
+  CP_HELPER_ARG="$CURRENT_POINTER_HELPER" DIR_ARG="$flowAgentsDir" SLUG_ARG="$slug" ACTOR_ARG="$actor" node - <<'NODE'
+const fs = require('fs');
+const path = require('path');
+const { writePerActorCurrent } = require(process.env.CP_HELPER_ARG);
+const dir = process.env.DIR_ARG;
+const slug = process.env.SLUG_ARG;
+const actor = process.env.ACTOR_ARG;
+const payload = { schema_version: '1.0', active_slug: slug, artifact_dir: slug };
+fs.mkdirSync(dir, { recursive: true });
+fs.writeFileSync(path.join(dir, 'current.json'), JSON.stringify(payload, null, 2) + '\n');
+writePerActorCurrent(dir, actor, payload);
+NODE
+}
+
 ROOT_SCRATCH_STATE_WRITER="$TMPDIR_EVAL/write-state-json.js"
 cat > "$ROOT_SCRATCH_STATE_WRITER" << 'JSEOF'
 const fs = require("fs");
@@ -388,7 +414,7 @@ mkdir -p "$UNSTABLE_DIR"
 # (a) Unstable current actor: unset the explicit override, the native runtime session id, AND every
 # CI-provider marker (#398) so resolveActor() genuinely falls through to process-ancestry/unresolved
 # regardless of whether this suite is running inside a CI job.
-if (unset FLOW_AGENTS_ACTOR CLAUDE_CODE_SESSION_ID CODEX_SESSION_ID OPENCODE_SESSION_ID PI_SESSION_ID CLAUDECODE \
+if (unset FLOW_AGENTS_ACTOR CLAUDE_CODE_SESSION_ID CODEX_THREAD_ID CODEX_SESSION_ID OPENCODE_SESSION_ID PI_SESSION_ID CLAUDECODE \
       GITHUB_ACTIONS GITLAB_CI CIRCLECI JENKINS_URL TF_BUILD BUILDKITE; \
     flow_agents_node "$WRITER" verify-hold "$UNSTABLE_DIR") >"$TMPDIR_EVAL/vh-unstable.out" 2>"$TMPDIR_EVAL/vh-unstable.err"; then
   pass "verify-hold with an unstable (ancestry/unresolved) current actor does NOT hard-block a subject held by a different actor (advisory-only, AC1 SECOND fix)"
@@ -713,6 +739,12 @@ grep -qF "hostile-holder-actor" "$TMPDIR_EVAL/vh-hostile.out" && pass "the sanit
 STEERING_REPO="$TMPDIR_EVAL/steering-hostile-repo"
 STEERING_HOSTILE_NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 write_steering_fixture_repo "$STEERING_REPO" "$HOSTILE_SLUG" "$STEERING_HOSTILE_NOW"
+# #440 FIX 2 (de-vacuate, delta review): the invoking actor (eval-actor-hostile-reader) owns
+# HOSTILE_SLUG -- seed its own per-actor pointer (real dual-write helper) so
+# actorScopedWorkflowState finds it and supersessionSteering is REACHED at all; without this the
+# absence assertion below passed only because no steering output existed in the first place, not
+# because the sanitization itself was exercised.
+seed_current_pointer "$STEERING_REPO" "$HOSTILE_SLUG" "eval-actor-hostile-reader"
 append_liveness_event "$STEERING_REPO/.kontourai/flow-agents" "$HOSTILE_SLUG" "$HOSTILE_HOLDER_ACTOR" "$STEERING_HOSTILE_NOW" 1800
 
 if FLOW_AGENTS_ACTOR="eval-actor-hostile-reader" node "$ROOT/scripts/hooks/workflow-steering.js" \
@@ -724,6 +756,14 @@ then
 else
   fail "steering hook should not fail for the hostile-holder fixture"
 fi
+# #440 FIX 2 reachability control (delta review): prove the supersession notice is ACTUALLY
+# present and names the sanitized holder -- the ANSI/control-byte absence checks below would
+# otherwise pass vacuously if no notice were emitted at all (exactly the pre-fix defect).
+if grep -qF "[SUPERSEDED:" "$TMPDIR_EVAL/steering-hostile.out" && grep -qF "hostile-holder-actor" "$TMPDIR_EVAL/steering-hostile.out"; then
+  pass "#440 reachability control: the steering supersession notice is present and names the sanitized (non-control-byte) hostile holder actor (AC7)"
+else
+  fail "#440 reachability control: no supersession notice was emitted, or it did not name the sanitized hostile holder actor: $(cat "$TMPDIR_EVAL/steering-hostile.out")"
+fi
 if grep -qF $'\x1b[31;1m' "$TMPDIR_EVAL/steering-hostile.out" || grep -qF $'\x07' "$TMPDIR_EVAL/steering-hostile.out"; then
   fail "hostile holder actor's raw ANSI/control bytes leaked into the steering supersession notice (AC7)"
 else
@@ -835,6 +875,7 @@ STEERING_SUP_REPO="$TMPDIR_EVAL/steering-supersede-repo"
 SUP_SLUG="steering-superseded-demo"
 SUP_NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 write_steering_fixture_repo "$STEERING_SUP_REPO" "$SUP_SLUG" "$SUP_NOW"
+seed_current_pointer "$STEERING_SUP_REPO" "$SUP_SLUG" "eval-actor-steering-self-a"
 append_liveness_event "$STEERING_SUP_REPO/.kontourai/flow-agents" "$SUP_SLUG" "eval-actor-steering-holder-b" "$SUP_NOW" 1800
 
 # 7a. UserPromptSubmit on a SECOND, unrelated turn (not the takeover turn itself) — the
@@ -869,6 +910,13 @@ NO_SUP_REPO="$TMPDIR_EVAL/steering-no-supersede-repo"
 NO_SUP_SLUG="steering-not-superseded-demo"
 NO_SUP_NOW="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
 write_steering_fixture_repo "$NO_SUP_REPO" "$NO_SUP_SLUG" "$NO_SUP_NOW"
+# #440 FIX 2 (de-vacuate, delta review): the invoking actor (eval-actor-steering-self-a) owns
+# NO_SUP_SLUG -- seed its own per-actor pointer (real dual-write helper) so
+# actorScopedWorkflowState finds it. Without this, the "no notice" assertions below would pass
+# only because NO scoped session existed at all (analyze()/actorScopedWorkflowState finds
+# nothing), not because a genuinely scoped session correctly found no other-actor holder -- the
+# exact "no scoped session" vs "scoped session, no other holder" distinction this case must prove.
+seed_current_pointer "$NO_SUP_REPO" "$NO_SUP_SLUG" "eval-actor-steering-self-a"
 # No liveness stream at all for this repo — no other-actor holder can exist.
 
 if FLOW_AGENTS_ACTOR="eval-actor-steering-self-a" node "$ROOT/scripts/hooks/workflow-steering.js" \
@@ -880,6 +928,14 @@ then
 else
   fail "steering hook should not fail for UserPromptSubmit on the non-superseded fixture"
 fi
+# #440 FIX 2 reachability control (delta review): prove the session WAS scoped/found (the STATE
+# banner is present) so the "no SUPERSEDED notice" checks below prove "scoped session, no other
+# holder" rather than vacuously "no scoped session at all".
+if grep -qF "STATE: $NO_SUP_SLUG is status:in_progress phase:execution" "$TMPDIR_EVAL/steering-no-sup-prompt.out"; then
+  pass "#440 reachability control: actor A's own scoped session is found at UserPromptSubmit (STATE banner present) (AC5)"
+else
+  fail "#440 reachability control: actor A's own scoped session was NOT found at UserPromptSubmit (no STATE banner): $(cat "$TMPDIR_EVAL/steering-no-sup-prompt.out")"
+fi
 if grep -qF "[SUPERSEDED:" "$TMPDIR_EVAL/steering-no-sup-prompt.out"; then
   fail "supersession notice incorrectly appeared at UserPromptSubmit with no other-actor fresh holder (false positive) (AC5)"
 else
@@ -895,6 +951,13 @@ then
 else
   fail "steering hook should not fail for SessionStart on the non-superseded fixture"
 fi
+# #440 FIX 2 reachability control (delta review): same rationale as the UserPromptSubmit check
+# above, for SessionStart's RESUME block.
+if grep -qF "RESUME: $NO_SUP_SLUG" "$TMPDIR_EVAL/steering-no-sup-start.out"; then
+  pass "#440 reachability control: actor A's own scoped session is found at SessionStart (RESUME banner present) (AC5)"
+else
+  fail "#440 reachability control: actor A's own scoped session was NOT found at SessionStart (no RESUME banner): $(cat "$TMPDIR_EVAL/steering-no-sup-start.out")"
+fi
 if grep -qF "[SUPERSEDED:" "$TMPDIR_EVAL/steering-no-sup-start.out"; then
   fail "supersession notice incorrectly appeared at SessionStart with no other-actor fresh holder (false positive) (AC5)"
 else

package/evals/integration/test_workflow_sidecar_writer.sh

@@ -3,6 +3,7 @@
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CURRENT_POINTER_HELPER="$ROOT/scripts/hooks/lib/current-pointer.js"
 source "$ROOT/evals/lib/node.sh"
 
 TMPDIR_EVAL="$(mktemp -d)"
@@ -4467,9 +4468,17 @@ fi
 
 # Poison BOTH navigation pointers. Exact-session writers must continue to use the persisted
 # canonical flow_run from the session instead of treating ambient pointers as authority.
+# #440 fix-wave 2: the per-actor filename is now collision-resistant (sanitized prefix + hash of
+# the FULL actor key, see current-pointer.js's perActorCurrentFile) -- resolve the real per-actor
+# path via the shared helper instead of hand-deriving the old (now-stale) "<actor>.json" name.
+UNRESOLVABLE_PER_ACTOR_FILE="$(CP_HELPER_ARG="$CURRENT_POINTER_HELPER" ROOT_ARG="$UNRESOLVABLE_ROOT" ACTOR_ARG="unresolvable-actor" node - <<'NODE'
+const { perActorCurrentFile } = require(process.env.CP_HELPER_ARG);
+process.stdout.write(perActorCurrentFile(process.env.ROOT_ARG, process.env.ACTOR_ARG));
+NODE
+)"
 node --input-type=module <<NODEOF 2>"$TMPDIR_EVAL/unresolvable-mutate.err"
 import { readFileSync, writeFileSync } from 'node:fs';
-for (const f of ['${UNRESOLVABLE_ROOT}/current.json', '${UNRESOLVABLE_ROOT}/current/unresolvable-actor.json']) {
+for (const f of ['${UNRESOLVABLE_ROOT}/current.json', '${UNRESOLVABLE_PER_ACTOR_FILE}']) {
   const d = JSON.parse(readFileSync(f, 'utf8'));
   d.active_flow_id = 'builder.bogus-nonexistent-flow-270';
   writeFileSync(f, JSON.stringify(d, null, 2) + '\n');

package/evals/integration/test_workflow_steering_hook.sh

@@ -3,6 +3,7 @@
 set -uo pipefail
 
 ROOT="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
+CURRENT_POINTER_HELPER="$ROOT/scripts/hooks/lib/current-pointer.js"
 
 TMPDIR_EVAL="$(mktemp -d)"
 errors=0
@@ -43,7 +44,22 @@ cat > "$REPO/.kontourai/flow-agents/steering-demo/trust.bundle" <<'JSON'
 {"schema_version":"1.0","claims":[]}
 JSON
 
-if node "$ROOT/scripts/hooks/workflow-steering.js" >"$TMPDIR_EVAL/steering.out" 2>"$TMPDIR_EVAL/steering.err" <<JSON
+# #440 FIXTURE-GAP: this file never set FLOW_AGENTS_ACTOR (every invocation ran under whichever
+# ambient/ancestry actor happened to resolve, never asserted on). The 4 assertions below that
+# expect steering-demo's STATE/RESUME banner need a RESOLVED actor that legitimately owns
+# steering-demo -- a stable, explicit override plus its own per-actor current pointer (mirroring
+# workflow-sidecar.ts's real writeCurrent() dual-write via current-pointer.js's own
+# writePerActorCurrent). Only the specific invocations that need this pass FLOW_AGENTS_ACTOR below
+# -- every other invocation in this file is untouched and keeps resolving via whatever ambient
+# actor it always has (harmless: none of the untouched assertions depend on `current`).
+STEERING_ACTOR="eval-workflow-steering-actor"
+CP_HELPER_ARG="$CURRENT_POINTER_HELPER" FLOW_AGENTS_DIR_ARG="$REPO/.kontourai/flow-agents" \
+  SLUG_ARG="steering-demo" ACTOR_ARG="$STEERING_ACTOR" node - <<'NODE'
+const { writePerActorCurrent } = require(process.env.CP_HELPER_ARG);
+writePerActorCurrent(process.env.FLOW_AGENTS_DIR_ARG, process.env.ACTOR_ARG, { active_slug: process.env.SLUG_ARG });
+NODE
+
+if FLOW_AGENTS_ACTOR="$STEERING_ACTOR" node "$ROOT/scripts/hooks/workflow-steering.js" >"$TMPDIR_EVAL/steering.out" 2>"$TMPDIR_EVAL/steering.err" <<JSON
 {"cwd":"$REPO","tool_input":{"command":"InvokeSubagents","content":{"subagents":[{"agent_name":"tool-verifier"}]}},"tool_response":"verification finished"}
 JSON
 then
@@ -137,7 +153,7 @@ else
   _fail "workflow steering hook should not fail for ordinary non-subagent tools"
 fi
 
-if node "$ROOT/scripts/hooks/workflow-steering.js" >"$TMPDIR_EVAL/prompt.out" 2>"$TMPDIR_EVAL/prompt.err" <<JSON
+if FLOW_AGENTS_ACTOR="$STEERING_ACTOR" node "$ROOT/scripts/hooks/workflow-steering.js" >"$TMPDIR_EVAL/prompt.out" 2>"$TMPDIR_EVAL/prompt.err" <<JSON
 {"hook_event_name":"UserPromptSubmit","cwd":"$REPO","prompt":"continue"}
 JSON
 then
@@ -174,7 +190,7 @@ else
   _fail "Claude hook adapter should not fail for workflow steering"
 fi
 
-if node "$ROOT/scripts/hooks/claude-hook-adapter.js" UserPromptSubmit prompt:workflow-steering workflow-steering.js standard,strict >"$TMPDIR_EVAL/claude-prompt-adapter.out" 2>"$TMPDIR_EVAL/claude-prompt-adapter.err" <<JSON
+if FLOW_AGENTS_ACTOR="$STEERING_ACTOR" node "$ROOT/scripts/hooks/claude-hook-adapter.js" UserPromptSubmit prompt:workflow-steering workflow-steering.js standard,strict >"$TMPDIR_EVAL/claude-prompt-adapter.out" 2>"$TMPDIR_EVAL/claude-prompt-adapter.err" <<JSON
 {"hook_event_name":"UserPromptSubmit","cwd":"$REPO","prompt":"continue"}
 JSON
 then
@@ -551,7 +567,7 @@ else
   _fail "Codex hook adapter should not fail after tool-worker execution"
 fi
 
-if node "$ROOT/scripts/hooks/codex-hook-adapter.js" prompt:workflow-steering workflow-steering.js standard,strict >"$TMPDIR_EVAL/codex-prompt-adapter.out" 2>"$TMPDIR_EVAL/codex-prompt-adapter.err" <<JSON
+if FLOW_AGENTS_ACTOR="$STEERING_ACTOR" node "$ROOT/scripts/hooks/codex-hook-adapter.js" prompt:workflow-steering workflow-steering.js standard,strict >"$TMPDIR_EVAL/codex-prompt-adapter.out" 2>"$TMPDIR_EVAL/codex-prompt-adapter.err" <<JSON
 {"hook_event_name":"UserPromptSubmit","cwd":"$REPO","prompt":"continue"}
 JSON
 then

package/evals/run.sh

@@ -175,6 +175,8 @@ run_integration() {
   echo ""
   bash "$EVAL_DIR/integration/test_telemetry_usage_pipeline.sh" || result=1
   echo ""
+  bash "$EVAL_DIR/integration/test_telemetry_tool_usage.sh" || result=1
+  echo ""
   bash "$EVAL_DIR/integration/test_telemetry_doctor.sh" || result=1
   echo ""
   bash "$EVAL_DIR/integration/test_usage_feedback_outcomes.sh" || result=1

package/evals/static/test_universal_bundles.sh

@@ -65,12 +65,135 @@ for dir in "$DIST_DIR/kiro" "$DIST_DIR/claude-code" "$DIST_DIR/codex" "$DIST_DIR
   fi
 done
 
+if node - "$ROOT_DIR/package.json" "$DIST_DIR" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+const [sourcePackageFile, dist] = process.argv.slice(2);
+const source = JSON.parse(fs.readFileSync(sourcePackageFile, "utf8"));
+for (const runtime of ["base", "kiro", "claude-code", "codex", "opencode", "pi"]) {
+  const manifest = JSON.parse(fs.readFileSync(path.join(dist, runtime, "build", "package.json"), "utf8"));
+  if (manifest.name !== "@kontourai/flow-agents" || manifest.version !== source.version || manifest.type !== "module") {
+    throw new Error(`${runtime} build package identity does not match Flow Agents ${source.version}`);
+  }
+}
+NODE
+then
+  _pass "all bundles stamp their compiled runtime with Flow Agents package identity"
+else
+  _fail "bundle compiled-runtime package identity is missing or stale"
+fi
+
 if [[ -d "$DIST_DIR/codex/.agents/skills/plan-work" && ! -e "$DIST_DIR/codex/.codex/skills" ]]; then
   _pass "Codex exports portable skills only in the universal .agents catalog"
 else
   _fail "Codex portable skills are not rooted exclusively at .agents/skills"
 fi
 
+if [[ ! -e "$DIST_DIR/codex/AGENTS.md" ]] \
+  && grep -q 'Generated from the canonical source' "$DIST_DIR/codex/README.md" \
+  && grep -q '## Exported agents' "$DIST_DIR/codex/README.md" \
+  && grep -q '`tool-worker`' "$DIST_DIR/codex/README.md" \
+  && ! grep -q 'Universal Agent Bundle (Codex)' "$DIST_DIR/codex/README.md"; then
+  _pass "Codex provenance and agent inventory are documentation, not global instructions"
+else
+  _fail "Codex bundle still exposes generated global instructions or lost README discovery metadata"
+fi
+
+echo ""
+echo "--- Documentation and Instruction Discovery Contract ---"
+# Keep this table aligned with the supported-runtime capability policy.  A dash
+# means the harness has no bundle-owned repository instruction file.
+while IFS='|' read -r runtime bundle_dir instruction_rel; do
+  readme="$DIST_DIR/$bundle_dir/README.md"
+  if [[ -f "$readme" ]] \
+    && grep -q 'Generated from the canonical source' "$readme" \
+    && grep -q '## Exported agents' "$readme" \
+    && grep -q '`tool-worker`' "$readme"; then
+    _pass "$runtime keeps provenance and the exported-agent inventory in README.md"
+  else
+    _fail "$runtime README.md is missing canonical provenance or exported-agent inventory"
+  fi
+
+  if [[ "$instruction_rel" == "-" ]]; then
+    if [[ ! -e "$DIST_DIR/$bundle_dir/AGENTS.md" && ! -e "$DIST_DIR/$bundle_dir/CLAUDE.md" ]]; then
+      _pass "$runtime does not publish a repository instruction surface"
+    else
+      _fail "$runtime publishes an instruction file despite declaring no discovery surface"
+    fi
+    continue
+  fi
+
+  instruction="$DIST_DIR/$bundle_dir/$instruction_rel"
+  if [[ -f "$instruction" ]]; then
+    _pass "$runtime publishes concise guidance on $instruction_rel"
+  else
+    _fail "$runtime is missing its $instruction_rel discovery surface"
+    continue
+  fi
+
+  if ! grep -Eq 'Treat the repo root as the source of truth|regenerate the bundle|were copied from the canonical source|Kiro-only hook wiring was stripped|## Exported Agents|## Exported agents' "$instruction" \
+    && [[ "$(grep -Ec '^- `tool-' "$instruction" || true)" -eq 0 ]]; then
+    _pass "$runtime instructions exclude maintainer prose and the exported-agent catalog"
+  else
+    _fail "$runtime instructions contain maintainer provenance, copied-directory notes, Kiro stripping notes, or a full agent catalog"
+  fi
+done <<'MATRIX'
+Base|base|AGENTS.md
+Kiro|kiro|AGENTS.md
+Claude Code|claude-code|CLAUDE.md
+Codex|codex|-
+OpenCode|opencode|AGENTS.md
+pi|pi|AGENTS.md
+MATRIX
+
+if node - "$ROOT_DIR/src/tools/build-universal-bundles.ts" <<'NODE'
+const fs = require("node:fs");
+const source = fs.readFileSync(process.argv[2], "utf8");
+for (const runtime of ["base", "kiro", "claude-code", "codex", "opencode", "pi"]) {
+  if (!source.includes(`\"${runtime}\"`)) throw new Error(`shared capability policy missing ${runtime}`);
+}
+for (const required of ["BUNDLE_CAPABILITIES", "renderBundleReadme", "renderOperationalInstructions", "installScript"]) {
+  if (!source.includes(required)) throw new Error(`shared bundle policy missing ${required}`);
+}
+if (source.includes("exportRootAgentsMd")) throw new Error("legacy combined provenance/instruction renderer remains");
+
+const builders = source.match(/function build(?:Base|Kiro|ClaudeCode|Codex|Opencode|Pi)\([^]*?(?=\nfunction |\nexport |\nmain\()/g) || [];
+if (builders.length !== 6) throw new Error(`expected six runtime builders, found ${builders.length}`);
+for (const builder of builders) {
+  if (!builder.includes("BUNDLE_CAPABILITIES")) throw new Error("runtime builder does not select shared capability data");
+  if (!builder.includes("installScript(")) throw new Error("runtime builder bypasses the shared installer generator");
+  if (/AGENTS\.md|CLAUDE\.md/.test(builder)) throw new Error("runtime builder contains a local instruction-file branch");
+}
+NODE
+then
+  _pass "all runtime builders select shared capabilities, renderers, and installer policy without local instruction branches"
+else
+  _fail "runtime bundle policy is duplicated or bypasses shared capabilities/renderers/installer preservation"
+fi
+
+if (cd "$ROOT_DIR" && node scripts/audit-codex-legacy-agents.js packaging/codex-legacy-agents-fingerprints.json >/tmp/codex-legacy-agents-audit.txt 2>&1) \
+  && grep -q 'Audited 14 seed-capable releases; 1 unique payload(s); gaps=0' /tmp/codex-legacy-agents-audit.txt; then
+  _pass "Codex legacy fingerprint catalog independently covers all seed-capable release tags"
+else
+  _fail "Codex legacy fingerprint catalog is incomplete, stale, or not byte-reproducible"
+fi
+
+if node - "$ROOT_DIR/scripts/classify-codex-legacy-agents.js" <<'NODE'
+const fs = require("node:fs");
+const source = fs.readFileSync(process.argv[2], "utf8");
+for (const forbidden of ["renameSync", "unlinkSync", "writeFileSync", "copyFileSync", "mkdirSync", "chmodSync", "MIGRATION_TEST", "--apply", "quarantine", "mv --", "rm --", "cp --"]) {
+  if (source.includes(forbidden)) throw new Error(`production classifier contains destructive/test path: ${forbidden}`);
+}
+for (const required of ["lstatSync", "openSync", "O_RDONLY", "O_NOFOLLOW", "fstatSync", "readFileSync(fd)", "createHash", "manual remediation checklist", "shellQuote"]) {
+  if (!source.includes(required)) throw new Error(`production classifier missing read-only behavior: ${required}`);
+}
+NODE
+then
+  _pass "Codex legacy classifier is read-only and exposes no production apply or test hooks"
+else
+  _fail "Codex legacy classifier contains mutation/apply/test-hook behavior"
+fi
+
 if node - "$DIST_DIR/codex/.agents/skills" <<'NODE'
 const fs = require("node:fs");
 const path = require("node:path");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.9.0",
+  "version": "3.10.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/packaging/README.md

@@ -25,6 +25,27 @@ All targets also receive shared canonical directories where supported: `context/
 
 `docs/` and `evals/` are intentionally included in generated bundles today. `docs/` gives installed agents durable local reference material, and `evals/` provides install-time and runtime smoke tests for the exported bundle. If bundle size becomes a product constraint, prune these through `packaging/manifest.json` and update install tests rather than deleting generated output by hand.
 
+## Documentation And Instruction Discovery
+
+Every runtime bundle puts generated-source provenance and the complete exported-agent inventory in `README.md`. That content is maintainer documentation, not agent instructions. A shared runtime capability policy separately decides whether a bundle publishes a concise repository instruction file:
+
+| Runtime | Bundle documentation | Repository instruction surface |
+| --- | --- | --- |
+| Base | `README.md` | `AGENTS.md` |
+| Kiro | `README.md` | `AGENTS.md` |
+| Claude Code | `README.md` | `CLAUDE.md` |
+| Codex | `README.md` | None |
+| OpenCode | `README.md` | `AGENTS.md` |
+| pi | `README.md` | `AGENTS.md` |
+
+Instruction files contain only concise operational guidance discoverable by the target harness. They do not contain regeneration advice, packaging provenance, or the exported-agent catalog.
+
+## Repository Instruction Preservation
+
+All generated installers use one preservation policy for repository instructions. An existing `AGENTS.md` or `CLAUDE.md` is repository-owned and is never overwritten or deleted. The installer excludes both paths from synchronization, including Kiro's `rsync --delete` path, and creates a runtime's declared instruction file only when that destination path is absent. This applies equally to direct bundle installation and `flow-agents init`.
+
+The CLI does not own a second instruction policy: `flow-agents init` selects a generated runtime bundle and invokes that bundle's `install.sh`. Changes to discovery or preservation therefore belong in the shared bundle capability and installer generation code, with direct and CLI-mediated fixtures covering the same behavior.
+
 ## Generated And Runtime Boundaries
 
 `dist/` is a generated export surface, not the source of truth. Installed runtime directories such as `.codex/` and `.claude/` are also not source. They are created from the generated target bundle and installer scripts. If generated or installed hook config is wrong, fix the canonical source, rebuild `dist/`, and reinstall the runtime config.

package/packaging/codex-legacy-agents-fingerprints.json

@@ -0,0 +1,33 @@
+{
+  "schema_version": 2,
+  "audit": {
+    "first_tag": "v2.4.0",
+    "last_tag": "v3.9.0",
+    "selection": "Every reachable release tag whose scripts/install-codex-home.sh contains the exact root seed loop 'for seed_file in AGENTS.md'.",
+    "reproduction_command": "node scripts/audit-codex-legacy-agents.js packaging/codex-legacy-agents-fingerprints.json",
+    "gaps": []
+  },
+  "files": [
+    {
+      "sha256": "5273878130bdafc8a024a650bb5b66c9b003f1f859b5dc6e5b588cbf4ab23228",
+      "bytes": 3315,
+      "fixture": "evals/fixtures/codex-legacy-agents/5273878130bdafc8a024a650bb5b66c9b003f1f859b5dc6e5b588cbf4ab23228.md",
+      "covered_releases": [
+        { "tag": "v2.4.0", "commit": "bee760272b8bb770df02400ccc5881bd3dbc8806" },
+        { "tag": "v3.0.0", "commit": "99abf1f6f44a333867b03702548927a12ad01275" },
+        { "tag": "v3.1.0", "commit": "7e6a9594212ef7813c428069b9f7fc6f39def8f1" },
+        { "tag": "v3.2.0", "commit": "15d5e9ae2bb9a80c3b3a89bf7887b5eff596f5d8" },
+        { "tag": "v3.3.0", "commit": "21c98807a259dfc4449bae2f359e975893dc4f4f" },
+        { "tag": "v3.4.0", "commit": "130a94696dac17cf1a65e6525e9168a835db79ff" },
+        { "tag": "v3.4.1", "commit": "0b41434f6422de62a8e06e48998a0699e3f623d2" },
+        { "tag": "v3.4.2", "commit": "c0d1724f0a5212942b0f457f4a7ae99c5f71da6b" },
+        { "tag": "v3.4.3", "commit": "07f98df4b7f737b543e3469ce3792fee2e5e6b81" },
+        { "tag": "v3.5.0", "commit": "4ffc9f9d7a5eeea006acddcdb259299fcc56354d" },
+        { "tag": "v3.6.0", "commit": "9f59f16143d7c6cc877778e4ad6620e2fc0cd829" },
+        { "tag": "v3.7.0", "commit": "4901adc14036c25d4ed98a7eac8c8e7b15b6a048" },
+        { "tag": "v3.8.0", "commit": "697795c87b0296d037ae76ee1984ce0eaa6684fb" },
+        { "tag": "v3.9.0", "commit": "a5c272bd19b563bd4e3da5db017e996eb0f854d0" }
+      ]
+    }
+  ]
+}

package/scripts/README.md

@@ -67,10 +67,11 @@ renamed, or changes category, update the table and the validator together.
 | `workflow-steering.js` | policy hook | `evals/integration/test_workflow_steering_hook.sh` | Provides workflow guidance from current artifact state. |
 | `pre-commit-quality.js` | repo guardrail hook | `evals/integration/test_hook_category_behaviors.sh` | Supports repository Git hook checks, not installed runtime hooks. |
 | `desktop-notify.sh` | local notification helper | `evals/integration/test_hook_category_behaviors.sh` | Optional local desktop notification helper. |
-| `lib/actor-identity.js` | shared hook library | `evals/integration/test_actor_identity.sh` | Shared runtime-agnostic actor identity resolver (`resolveActor`) consumed by `workflow-steering.js` and `workflow-sidecar.js` to retire the shared `"local"` liveness-actor default (issue #287). |
+| `lib/actor-identity.js` | shared hook library | `evals/integration/test_actor_identity.sh` | Canonical runtime-agnostic actor resolver (`resolveActor`), including privacy-safe Codex thread identity and explicitly unstable process-ancestry fallback. TypeScript consumers load this file directly; there is no maintained mirror. |
 | `lib/audit-transport.sh` | shared hook library | `evals/integration/test_hook_category_behaviors.sh`, `evals/integration/test_telemetry.sh` | Shared audit event transport functions. |
 | `lib/codex-exit-code.js` | shared hook library | `evals/acceptance/prove-capture-teeth.sh` | Shared codex-only host-banner exit-code extraction (`extractExitCodeFromBanner`, `readExitCodeFromRollout`) — parses the `Process exited with code N` prose the codex CLI writes into a `function_call_output` payload or session rollout so `codex-hook-adapter.js` can inject a structured exit code before `evidence-capture.js` observes (issue #470). |
 | `lib/config-protection-remedies.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Sanctioned-remedy table for `config-protection.js` (WS8/ADR 0020 extraction). |
+| `lib/continuation-turn-authority.js` | shared hook library | `src/cli/continuation-driver.test.mjs`, `evals/integration/test_goal_fit_hook.sh` | Signed transient authority for one public continuation adapter turn, independently anchored by the signer digest in driver mission state. Assignment-gated evidence mutation can fall back to its live signed assignment identity only after ordinary resolution mismatches; lifecycle controls never use it. Stop keeps a base-valid signed run selected across canonical dispositions, validates canonical state against its definition, and treats only ordinary active-gate warnings as advisory. Same-UID filesystem/process attacks remain outside the cooperative boundary. |
 | `lib/current-pointer.js` | shared hook library | `evals/integration/test_current_json_per_actor.sh` | Shared per-actor "current" pointer reader/writer (`readCurrentPointer`, `writePerActorCurrent`) — the compat-shim fallback (per-actor `current/<actor>.json` first, legacy global `current.json` fallback) every actor-aware consumer routes through (issue #291). |
 | `lib/hook-flags.js` | shared hook library | `evals/integration/test_hook_category_behaviors.sh` | Shared profile/disable flag parsing. |
 | `lib/kit-catalog.js` | shared hook library | `evals/integration/test_workflow_steering_hook.sh` | Build-free kit catalog reader used by `workflow-steering.js` to load kit-declared workflow triggers while hooks remain fail-open and independent of compiled TypeScript output. |

package/scripts/audit-codex-legacy-agents.js

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+"use strict";
+
+const cp = require("node:child_process");
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+
+function git(...args) { return cp.execFileSync("git", args, { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] }); }
+function show(tag, file) { return git("show", `${tag}:${file}`); }
+function payloadAt(tag) {
+  const manifest = JSON.parse(show(tag, "packaging/manifest.json"));
+  const excluded = new Set(manifest.codex?.excluded_agents ?? []);
+  const names = git("ls-tree", "--name-only", `${tag}:agents`).trim().split(/\n/).filter((name) => name.endsWith(".json"));
+  const agents = names.map((name) => JSON.parse(show(tag, `agents/${name}`)))
+    .filter((agent) => !excluded.has(agent.name)).sort((a, b) => a.name.localeCompare(b.name));
+  const summary = agents.map((agent) => `- \`${agent.name}\` — ${String(agent.description ?? "").trim()}`).join("\n");
+  return Buffer.from(`# Universal Agent Bundle (Codex)\n\nThis bundle was generated from the canonical source in this repo. Treat the repo root as the source of truth and regenerate the bundle instead of editing exported agent files by hand.\n\n## Shared Conventions\n\n- \`skills/\`, \`context/\`, \`powers/\`, \`prompts/\`, \`scripts/\`, and \`evals/\` were copied from the canonical source.\n- Cross-session task artifacts should live under \`${manifest.codex.task_dir}\`.\n- Kiro-only hook wiring was stripped from exported non-Kiro agents to keep the package portable.\n\n## Exported Agents\n\n${summary}\n`);
+}
+
+const catalogPath = process.argv[2];
+if (!catalogPath) throw new Error("usage: audit-codex-legacy-agents.js CATALOG");
+const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
+const tags = git("tag", "--sort=version:refname").trim().split(/\n/).filter(Boolean);
+const discovered = [];
+for (const tag of tags) {
+  let installer;
+  try { installer = show(tag, "scripts/install-codex-home.sh"); } catch { continue; }
+  if (!/for seed_file in AGENTS\.md/.test(installer)) continue;
+  const bytes = payloadAt(tag);
+  discovered.push({ tag, commit: git("rev-list", "-n1", tag).trim(), bytes: bytes.length, sha256: crypto.createHash("sha256").update(bytes).digest("hex"), payload: bytes });
+}
+const covered = new Map();
+for (const file of catalog.files ?? []) for (const release of file.covered_releases ?? []) covered.set(release.tag, { ...release, file });
+for (const release of discovered) {
+  const entry = covered.get(release.tag);
+  if (!entry) throw new Error(`catalog omits seed-capable release ${release.tag}`);
+  if (entry.commit !== release.commit || entry.file.sha256 !== release.sha256 || entry.file.bytes !== release.bytes) throw new Error(`catalog mismatch for ${release.tag}`);
+  if (!entry.file.fixture || !fs.existsSync(entry.file.fixture) || !release.payload.equals(fs.readFileSync(entry.file.fixture))) throw new Error(`fixture mismatch for ${release.tag}`);
+}
+for (const tag of covered.keys()) if (!discovered.some((release) => release.tag === tag)) throw new Error(`catalog includes non-seed-capable or unreachable release ${tag}`);
+if (catalog.audit?.first_tag !== discovered[0]?.tag || catalog.audit?.last_tag !== discovered.at(-1)?.tag) throw new Error("catalog audit interval does not match independently discovered releases");
+if (!Array.isArray(catalog.audit?.gaps)) throw new Error("catalog must explicitly record reproduction gaps");
+console.log(`Audited ${discovered.length} seed-capable releases; ${new Set(discovered.map((item) => item.sha256)).size} unique payload(s); gaps=${catalog.audit.gaps.length}`);

package/scripts/classify-codex-legacy-agents.js

@@ -0,0 +1,71 @@
+#!/usr/bin/env node
+"use strict";
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const path = require("node:path");
+
+function shellQuote(value) { return `'${String(value).replace(/'/g, `'"'"'`)}'`; }
+function advisory(message) { console.error(`classify-codex-legacy-agents: ${message}`); }
+
+const [destinationArg, catalogArg] = process.argv.slice(2);
+if (!destinationArg || !catalogArg) {
+  advisory("usage: classify-codex-legacy-agents.js DEST CATALOG");
+  process.exit(2);
+}
+const destination = path.resolve(destinationArg);
+const source = path.join(destination, "AGENTS.md");
+let stat;
+try { stat = fs.lstatSync(source); }
+catch (error) {
+  if (error?.code === "ENOENT") process.exit(0);
+  advisory(`cannot inspect ${source}; preserved without changes: ${error.message}`);
+  process.exit(2);
+}
+if (stat.isSymbolicLink() || !stat.isFile()) {
+  advisory(`preserved ambiguous non-regular or symlink object without changes: ${source}`);
+  process.exit(0);
+}
+if (fs.constants.O_NOFOLLOW === undefined) {
+  advisory(`platform lacks O_NOFOLLOW; preserved without classification: ${source}`);
+  process.exit(2);
+}
+let fd;
+let bytes;
+try {
+  fd = fs.openSync(source, fs.constants.O_RDONLY | fs.constants.O_NOFOLLOW);
+  const opened = fs.fstatSync(fd);
+  if (!opened.isFile()) {
+    advisory(`preserved non-regular descriptor without changes: ${source}`);
+    process.exit(0);
+  }
+  bytes = fs.readFileSync(fd);
+} catch (error) {
+  advisory(`cannot open/read ${source} without following links; preserved without changes: ${error.message}`);
+  process.exit(2);
+} finally {
+  if (fd !== undefined) fs.closeSync(fd);
+}
+const digest = crypto.createHash("sha256").update(bytes).digest("hex");
+const catalog = JSON.parse(fs.readFileSync(catalogArg, "utf8"));
+const match = (catalog.files ?? []).find((entry) => entry.sha256 === digest && entry.bytes === bytes.length);
+if (!match) {
+  advisory(`preserved unrecognized or user-owned ${source} (sha256=${digest}, bytes=${bytes.length})`);
+  process.exit(0);
+}
+const releases = (match.covered_releases ?? []).map((item) => `${item.tag}@${item.commit}`).join(", ");
+advisory(`REFUSING INSTALL: exact historical Flow Agents-generated global instructions remain active`);
+advisory(`path=${source}`);
+advisory(`sha256=${digest} bytes=${bytes.length}`);
+advisory(`matching_releases=${releases}`);
+advisory("automatic mutation is disabled because portable Node cannot condition pathname removal on the inode that was classified");
+advisory(`evidence command (hash): shasum -a 256 -- ${shellQuote(source)}`);
+advisory(`evidence command (bytes): wc -c < ${shellQuote(source)}`);
+advisory("manual remediation checklist:");
+advisory("1. Stop all agent and writer processes that can modify the Codex home.");
+advisory(`2. Revalidate the file is still exactly sha256=${digest} and bytes=${bytes.length} using the evidence commands above.`);
+advisory("3. Choose a new, unused recovery path outside every agent instruction-discovery location.");
+advisory("4. Move the file manually without overwrite using operator-trusted tooling; no mutation command is emitted here.");
+advisory("5. Inspect the preserved recovery file and confirm its exact hash and byte count.");
+advisory("6. Rerun the Flow Agents Codex installer.");
+process.exit(3);

package/scripts/hooks/evidence-capture.js

@@ -57,8 +57,8 @@
 const fs = require('fs');
 const path = require('path');
 const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
-const { resolveActor } = require('./lib/actor-identity.js');
-const { readCurrentPointer } = require('./lib/current-pointer.js');
+const { resolveActor, isUnresolvedActor } = require('./lib/actor-identity.js');
+const { readOwnCurrentPointer } = require('./lib/current-pointer.js');
 const { isAmbiguousAbsenceCommand } = require('./lib/runnable-command.js');
 const crypto = require('crypto');
 
@@ -204,14 +204,19 @@ function latestStateDir(flowAgentsDir) {
 }
 
 /**
- * Resolve the active artifact directory the same way the other hooks do:
- * prefer .kontourai/flow-agents/current.json (active_slug / artifact_dir), then fall back
- * to the newest-mtime state.json directory.
+ * Resolve the active artifact directory the same way the other #440-migrated hooks do: prefer
+ * the RESOLVED actor's own per-actor `current/<actor>.json` pointer (active_slug / artifact_dir)
+ * via `readOwnCurrentPointer` — never the shared legacy `current.json`, and never the repo-wide
+ * newest-mtime scan (D1: that would append this actor's OWN captured evidence into an unrelated
+ * actor's session directory). Only for an empty/unresolved actor does this fall back to the
+ * legacy global `current.json` and, failing that, the newest-mtime `state.json` directory scan —
+ * the pre-#440/#291 behavior, unchanged for that case (D3 compat). See the D1/D2/D3 comment
+ * inline below for the exact branching.
  */
 function resolveArtifactDir(root) {
   const actorKey = resolveActor(process.env).actor;
   for (const flowAgentsDir of flowAgentsArtifactRootsForRead(root)) {
-    const { payload: current } = readCurrentPointer(flowAgentsDir, actorKey);
+    const { payload: current } = readOwnCurrentPointer(flowAgentsDir, actorKey);
     if (current) {
       const slug = current.artifact_dir || current.active_slug;
       if (typeof slug === 'string' && slug.trim()) {
@@ -222,6 +227,13 @@ function resolveArtifactDir(root) {
       }
     }
   }
+  // #440 D1: a resolved actor with no own per-actor pointer never falls back to the repo-wide
+  // newest-mtime scan below — that would append this actor's OWN captured evidence into an
+  // unrelated actor's session directory (write-side ownership conflation). D2 accepted gap:
+  // captured evidence is simply dropped (existing `if (!artifactDir) return rawInput;` no-op in
+  // run()) until this actor's next sidecar command establishes its own per-actor pointer. D3: an
+  // unresolved actor keeps today's exact global-scan fallback, unchanged.
+  if (!isUnresolvedActor(actorKey)) return null;
   for (const flowAgentsDir of flowAgentsArtifactRootsForRead(root)) {
     const latest = latestStateDir(flowAgentsDir);
     if (latest) return latest;