@kontourai/flow-agents 3.7.0 → 3.9.0

package/docs/workflow-usage-guide.md

@@ -663,6 +663,13 @@ the read-only `workflow status` projection without attaching evidence or advanci
 [`docs/spec/builder-flow-runtime.md`](spec/builder-flow-runtime.md) for the ownership,
 trust-binding, route-back, and artifact-root contract.
 
+For unattended runtime re-entry, the active assignment actor may use `workflow drive` with an
+explicit runtime adapter argv file. The driver repeats the same public projection/evidence cycle,
+persists its mission turn budget, and parks on adapter-declared PID or deadline barriers instead of
+spending turns while external work is incomplete. Adapter completion never advances a gate by
+self-report; only trust evidence accepted by canonical Flow can change the current step. See
+[`docs/public-workflow-cli.md`](public-workflow-cli.md#bounded-continuation-driver) for the protocol.
+
 If the same Builder slice is interrupted, inspect its canonical status. Resume
 only when the public status reports a paused run:
 

package/evals/integration/test_builder_step_producers.sh

@@ -456,6 +456,9 @@ record_public_expectation() {
     *) _fail "public producer fixture has no durable artifact for $expectation"; return ;;
   esac
   local -a args=(evidence --session-dir "$PUBLIC_SESSION" --expectation "$expectation" --status "$status" --summary "public producer fixture records a reviewable durable artifact" --evidence-ref-json "{\"kind\":\"artifact\",\"file\":\"$artifact\",\"summary\":\"Fixture artifact for $expectation.\"}")
+  if [ "$expectation" = "tests-evidence" ] && [ "$status" = "fail" ]; then
+    args+=(--route-reason implementation_defect)
+  fi
   if [ "$expectation" = "tests-evidence" ] && [ "$status" = "pass" ]; then
     local test_command criterion_one criterion_two command_ref
     test_command="bash checks/check-public-session.sh .kontourai/flow-agents/$slug/state.json"
@@ -614,16 +617,46 @@ ROUTE_CRITIQUE_OUTPUT="$(public_review critique --session-dir "$PUBLIC_SESSION"
   --artifact-ref "$PUBLIC_SESSION/$(basename "$PUBLIC_SESSION")--deliver.md" \
   --lane-json "{\"id\":\"code-review\",\"status\":\"pass\",\"summary\":\"Public fixture code review completed.\",\"evidence_refs\":[{\"kind\":\"artifact\",\"file\":\"$PUBLIC_SESSION/$(basename "$PUBLIC_SESSION")--deliver.md\",\"summary\":\"Reviewed public fixture delivery artifact.\"}]}" 2>&1)" \
   || _fail "public authenticated critique failed before failed tests-evidence: $ROUTE_CRITIQUE_OUTPUT"
+# Seed current verified acceptance prerequisites through the private producer
+# without synchronizing Flow. The subsequent public failed tests claim replaces
+# the provisional passing tests check, preserves these criteria + the clean
+# critique, and is the only attachment/evaluation for this gate visit.
+ROUTE_TEST_COMMAND="bash checks/check-public-session.sh .kontourai/flow-agents/$(basename "$PUBLIC_SESSION")/state.json"
+ROUTE_COMMAND_REF="$(node - "$ROUTE_TEST_COMMAND" <<'NODE'
+const command = process.argv[2];
+process.stdout.write(JSON.stringify({ kind: 'command', excerpt: command, summary: 'Current route-back prerequisite command.' }));
+NODE
+)"
+ROUTE_CRITERION_ONE="$(node - "$ROUTE_TEST_COMMAND" <<'NODE'
+const command = process.argv[2];
+process.stdout.write(JSON.stringify({ id: 'AC-1', status: 'pass', evidence_refs: [{ kind: 'command', excerpt: command, summary: 'Current AC-1 prerequisite.' }] }));
+NODE
+)"
+ROUTE_CRITERION_TWO="$(node - "$ROUTE_TEST_COMMAND" <<'NODE'
+const command = process.argv[2];
+process.stdout.write(JSON.stringify({ id: 'AC-2', status: 'pass', evidence_refs: [{ kind: 'command', excerpt: command, summary: 'Current AC-2 prerequisite.' }] }));
+NODE
+)"
+ROUTE_OBSERVED="$(node - "$ROUTE_TEST_COMMAND" <<'NODE'
+const command = process.argv[2];
+process.stdout.write(JSON.stringify({ command, exit_code: 0, test_count: 1, output_sha256: '0'.repeat(64) }));
+NODE
+)"
+CODEX_SESSION_ID=builder-public-producers flow_agents_node "workflow-sidecar" record-gate-claim "$PUBLIC_SESSION" \
+  --expectation tests-evidence --status pass --summary "Seed complete current acceptance prerequisites before routed failure." \
+  --command "$ROUTE_TEST_COMMAND" --observed-command-json "$ROUTE_OBSERVED" \
+  --evidence-ref-json "$ROUTE_COMMAND_REF" --criterion-json "$ROUTE_CRITERION_ONE" --criterion-json "$ROUTE_CRITERION_TWO" >/dev/null 2>&1 \
+  || _fail "failed to seed current acceptance prerequisites for routed failure"
 record_public_expectation "tests-evidence" "fail"
 ROUTE_REPORT="$(public_flow status --session-dir "$PUBLIC_SESSION" --json 2>/dev/null)"
 if node - "$ROUTE_REPORT" <<'NODE'
 const report = JSON.parse(process.argv[2]);
-if (report.current_step !== 'verify') process.exit(1);
-if ((report.next_action?.skills || []).join(',') !== 'review-work,verify-work') process.exit(2);
-if (!/attempt 1\/3 returned to `verify`/.test(report.next_action?.summary || '')) process.exit(3);
+if (report.current_step !== 'execute') process.exit(1);
+if ((report.next_action?.skills || []).join(',') !== 'execute-plan') process.exit(2);
+if (!/attempt 1\/3 returned to `execute` for `implementation_defect`/.test(report.next_action?.summary || '')) process.exit(3);
 NODE
 then
-  _pass "failed verify evidence routes back through Flow with attempt 1/3 and canonical producers"
+  _pass "complete failed verify evidence routes back through Flow once to execute for implementation_defect"
 else
   _fail "public failed-verify route-back was not projected correctly: $ROUTE_REPORT"
 fi

package/evals/integration/test_bundle_install.sh

@@ -285,7 +285,7 @@ else
   _fail "pi install failed"
 fi
 
-USER_SKILLS_DIR="$CODEX_FULL_DEST/.codex/sk""ills/user-skill"
+USER_SKILLS_DIR="$CODEX_FULL_DEST/.agents/sk""ills/user-skill"
 mkdir -p "$CODEX_FULL_DEST/.codex/ag""ents" "$USER_SKILLS_DIR"
 printf 'name = "user-agent"\n' > "$CODEX_FULL_DEST/.codex/ag""ents/user-agent.toml"
 printf '# user skill\n' > "$USER_SKILLS_DIR/SKILL.md"
@@ -309,7 +309,7 @@ for dir in \
   "$CLAUDE_DEST/.flow-agents" \
   "$CLAUDE_DEST/.kontourai/flow-agents" \
   "$CODEX_DEST/.codex/agents" \
-  "$CODEX_DEST/.codex/skills" \
+  "$CODEX_DEST/.agents/skills" \
   "$CODEX_DEST/.flow-agents" \
   "$CODEX_DEST/.kontourai/flow-agents" \
   "$CODEX_FULL_DEST/.flow-agents" \
@@ -1069,7 +1069,7 @@ else
   _fail "packed npm consumer did not complete the public Builder workflow contract and lifecycle commands"
 fi
 
-if node - "$CODEX_FULL_DEST/.codex/skills" "$CODEX_FULL_DEST" <<'NODE'
+if node - "$CODEX_FULL_DEST/.agents/skills" "$CODEX_FULL_DEST" <<'NODE'
 const fs = require('node:fs');
 const path = require('node:path');
 const [root, installRoot] = process.argv.slice(2);
@@ -1094,7 +1094,12 @@ for (const skill of [...builder, 'agentic-engineering']) {
       throw new Error('verify-work must ship criterion-backed substantive verification evidence guidance');
     }
     const refs = [...text.matchAll(/\b(?:context|docs|kits)\/[A-Za-z0-9_./-]+\.(?:md|json)\b/g)].map((match) => match[0]);
-    for (const ref of refs) if (!fs.existsSync(path.join(installRoot, ref))) throw new Error(`${skill} has unresolved installed resource ${ref}`);
+    for (const ref of refs) {
+      const skillLocal = path.join(path.dirname(file), ref);
+      if (!fs.existsSync(skillLocal) && !fs.existsSync(path.join(installRoot, ref))) {
+        throw new Error(`${skill} has unresolved installed resource ${ref}`);
+      }
+    }
   }
 }
 NODE
@@ -1110,6 +1115,105 @@ else
   _fail "Codex full install removed unknown user files"
 fi
 
+echo ""
+echo "--- Dedicated Codex Home Universal Skills ---"
+GLOBAL_HOME="$TMPDIR_EVAL/global-home"
+GLOBAL_CODEX="$TMPDIR_EVAL/global-codex"
+GLOBAL_SKILLS="$TMPDIR_EVAL/global-agents/skills"
+mkdir -p "$GLOBAL_SKILLS/user-skill"
+printf '# user skill\n' > "$GLOBAL_SKILLS/user-skill/SKILL.md"
+GLOBAL_OUTPUT="$TMPDIR_EVAL/global-install.out"
+if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$GLOBAL_CODEX" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$GLOBAL_CODEX" --skills-dir "$GLOBAL_SKILLS" >"$GLOBAL_OUTPUT"; then
+  _pass "dedicated Codex installer accepts independent hermetic runtime and skill roots"
+else
+  _fail "dedicated Codex installer failed with independent hermetic roots"
+fi
+if [[ -f "$GLOBAL_SKILLS/plan-work/SKILL.md" && -f "$GLOBAL_SKILLS/plan-work/context/contracts/planning-contract.md" && -f "$GLOBAL_SKILLS/user-skill/SKILL.md" && ! -e "$GLOBAL_CODEX/skills/plan-work" ]]; then
+  _pass "global install uses self-contained universal skills and preserves user skills"
+else
+  _fail "global universal skill layout, resource closure, or user preservation is wrong"
+fi
+if rg -q 'Installed Flow Agents into Codex home at .+/global-codex$' "$GLOBAL_OUTPUT" && rg -q 'Installed portable skills at .+/global-agents/skills$' "$GLOBAL_OUTPUT"; then
+  _pass "installer reports both runtime and portable skill destinations"
+else
+  _fail "installer output does not report both destinations"
+fi
+if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$GLOBAL_CODEX" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$GLOBAL_CODEX" --skills-dir "$GLOBAL_SKILLS" >/dev/null; then
+  _pass "split-root reinstall is idempotent"
+else
+  _fail "split-root reinstall is not idempotent"
+fi
+
+CONFLICT_CODEX="$TMPDIR_EVAL/conflict-codex"
+CONFLICT_SKILLS="$TMPDIR_EVAL/conflict-agents/skills"
+mkdir -p "$CONFLICT_SKILLS/plan-work" "$CONFLICT_CODEX/skills/plan-work" "$CONFLICT_CODEX/.flow-agents"
+printf '# user collision\n' > "$CONFLICT_SKILLS/plan-work/SKILL.md"
+cp "$ROOT_DIR/dist/codex/.agents/skills/plan-work/SKILL.md" "$CONFLICT_CODEX/skills/plan-work/SKILL.md"
+printf 'runtime sentinel\n' > "$CONFLICT_CODEX/runtime-sentinel"
+node - "$CONFLICT_CODEX" <<'NODE'
+const fs=require('node:fs'), path=require('node:path'), crypto=require('node:crypto'); const root=process.argv[2];
+const rel='skills' + '/plan-work/SKILL.md'; const sha256=crypto.createHash('sha256').update(fs.readFileSync(path.join(root,rel))).digest('hex');
+fs.writeFileSync(path.join(root,'.flow-agents/codex-install-manifest.json'), JSON.stringify({schema_version:'1.0',files:[{path:rel,sha256}]},null,2)+'\n');
+NODE
+CONFLICT_RUNTIME_BEFORE="$(shasum -a 256 "$CONFLICT_CODEX/skills/plan-work/SKILL.md" "$CONFLICT_CODEX/.flow-agents/codex-install-manifest.json" "$CONFLICT_CODEX/runtime-sentinel")"
+if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$CONFLICT_CODEX" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$CONFLICT_CODEX" --skills-dir "$CONFLICT_SKILLS" >/dev/null 2>&1; then
+  _fail "global installer overwrote a user-owned skill collision"
+else
+  CONFLICT_RUNTIME_AFTER="$(shasum -a 256 "$CONFLICT_CODEX/skills/plan-work/SKILL.md" "$CONFLICT_CODEX/.flow-agents/codex-install-manifest.json" "$CONFLICT_CODEX/runtime-sentinel")"
+  if [[ "$(cat "$CONFLICT_SKILLS/plan-work/SKILL.md")" == "# user collision" && "$CONFLICT_RUNTIME_BEFORE" == "$CONFLICT_RUNTIME_AFTER" && ! -e "$CONFLICT_SKILLS/.flow-agents" ]]; then
+    _pass "cross-root collision preflight preserves universal content, legacy skill, runtime sentinel, and manifests"
+  else
+    _fail "cross-root collision failure partially mutated an install root"
+  fi
+fi
+
+SYMLINK_TARGET="$TMPDIR_EVAL/symlink-target"
+SYMLINK_PARENT="$TMPDIR_EVAL/symlink-parent"
+mkdir -p "$SYMLINK_TARGET" "$SYMLINK_PARENT"
+ln -s "$SYMLINK_TARGET" "$SYMLINK_PARENT/catalog"
+if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$TMPDIR_EVAL/symlink-codex" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$TMPDIR_EVAL/symlink-codex" --skills-dir "$SYMLINK_PARENT/catalog/skills" >/dev/null 2>&1; then
+  _fail "global installer followed a symlinked skill destination component"
+else
+  [[ ! -e "$SYMLINK_TARGET/skills" ]] && _pass "global installer refuses symlinked skill destination components without mutation" || _fail "symlink rejection mutated its target"
+fi
+
+SOURCE_ANCESTOR="$(dirname "$ROOT_DIR")"
+SOURCE_DESCENDANT="$ROOT_DIR/.fa-550-forbidden-skills"
+for unsafe in / "$SOURCE_ANCESTOR" "$SOURCE_DESCENDANT"; do
+  rm -rf "$SOURCE_DESCENDANT"
+  if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$TMPDIR_EVAL/unsafe-codex" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$TMPDIR_EVAL/unsafe-codex" --skills-dir "$unsafe" >/dev/null 2>&1; then
+    _fail "global installer accepted unsafe skill namespace root: $unsafe"
+  elif [[ ! -e "$SOURCE_DESCENDANT" && ! -e "$TMPDIR_EVAL/unsafe-codex" ]]; then
+    _pass "unsafe root/overlap rejection occurs before destination mutation: $unsafe"
+  else
+    _fail "unsafe root/overlap rejection left destination mutations: $unsafe"
+  fi
+done
+
+MIGRATE_CODEX="$TMPDIR_EVAL/migrate-codex"
+MIGRATE_SKILLS="$TMPDIR_EVAL/migrate-agents/skills"
+LEGACY_SKILLS_SEGMENT="skills"
+LEGACY_USER_DIR="$MIGRATE_CODEX/$LEGACY_SKILLS_SEGMENT/user-legacy"
+mkdir -p "$MIGRATE_CODEX/skills/plan-work" "$LEGACY_USER_DIR" "$MIGRATE_CODEX/.flow-agents"
+cp "$ROOT_DIR/dist/codex/.agents/skills/plan-work/SKILL.md" "$MIGRATE_CODEX/skills/plan-work/SKILL.md"
+printf '# modified legacy user content\n' > "$LEGACY_USER_DIR/SKILL.md"
+node - "$MIGRATE_CODEX" <<'NODE'
+const fs = require('node:fs'); const path = require('node:path'); const crypto = require('node:crypto');
+const root = process.argv[2];
+const rels = ['skills' + '/plan-work/SKILL.md', 'skills' + '/user-legacy/SKILL.md'];
+const files = rels.map(p => ({path:p, sha256:crypto.createHash('sha256').update(fs.readFileSync(path.join(root,p))).digest('hex')}));
+fs.writeFileSync(path.join(root,'.flow-agents/codex-install-manifest.json'), JSON.stringify({schema_version:'1.0',files},null,2)+'\n');
+fs.appendFileSync(path.join(root,'skills' + '/user-legacy/SKILL.md'), 'kept modification\n');
+NODE
+if HOME="$GLOBAL_HOME" CODEX_REAL_HOME="$MIGRATE_CODEX" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$MIGRATE_CODEX" --skills-dir "$MIGRATE_SKILLS" >/dev/null 2>"$TMPDIR_EVAL/migrate.err" \
+  && [[ ! -e "$MIGRATE_CODEX/skills/plan-work/SKILL.md" ]] \
+  && rg -q 'kept modification' "$LEGACY_USER_DIR/SKILL.md" \
+  && [[ -f "$MIGRATE_SKILLS/plan-work/SKILL.md" ]]; then
+  _pass "legacy migration removes unchanged owned skills and preserves modified legacy content"
+else
+  _fail "legacy Flow Agents skill migration was destructive or incomplete"
+fi
+
 OPENCODE_AGENTS_DIR="$OPENCODE_FULL_DEST/.opencode/agents"
 if [[ -f "$OPENCODE_AGENTS_DIR/tool-planner.md" && -f "$OPENCODE_AGENTS_DIR/dev.md" ]]; then
   _pass "opencode full install ships the complete agent base"

package/evals/integration/test_bundle_lifecycle.sh

@@ -164,7 +164,7 @@ OPENCODE_UPGRADE="$TMPDIR_EVAL/upgrade-opencode"
 # Touch a marker into skill files in the COPIES (not dist/ originals)
 UPGRADE_MARKER="# flow-agents-upgrade-test-marker"
 CLAUDE_SKILL_FILE="$CLAUDE_BUNDLE_COPY/.claude/skills/plan-work/SKILL.md"
-CODEX_SKILL_FILE="$CODEX_BUNDLE_COPY/.codex/skills/plan-work/SKILL.md"
+CODEX_SKILL_FILE="$CODEX_BUNDLE_COPY/.agents/skills/plan-work/SKILL.md"
 OPENCODE_SKILL_FILE="$OPENCODE_BUNDLE_COPY/.opencode/skills/plan-work/SKILL.md"
 
 if [[ -f "$CLAUDE_SKILL_FILE" ]]; then
@@ -191,12 +191,10 @@ else
   _fail "claude-code upgrade: skill change did not propagate to workspace"
 fi
 
-if [[ -f "$CODEX_SKILL_FILE" ]] && grep -qF "$UPGRADE_MARKER" "$CODEX_UPGRADE/.codex/skills/plan-work/SKILL.md" 2>/dev/null; then
+if [[ -f "$CODEX_SKILL_FILE" ]] && grep -qF "$UPGRADE_MARKER" "$CODEX_UPGRADE/.agents/skills/plan-work/SKILL.md" 2>/dev/null; then
   _pass "codex upgrade: modified skill file propagated to workspace"
-elif [[ ! -f "$CODEX_SKILL_FILE" ]]; then
-  _pass "codex upgrade: skill file not in bundle (skipped)"
 else
-  _fail "codex upgrade: skill change did not propagate to workspace"
+  _fail "codex upgrade: required universal skill missing or change did not propagate"
 fi
 
 if [[ -f "$OPENCODE_SKILL_FILE" ]] && grep -qF "$UPGRADE_MARKER" "$OPENCODE_UPGRADE/.opencode/skills/plan-work/SKILL.md" 2>/dev/null; then
@@ -246,7 +244,7 @@ echo '{"custom":"data"}' > "$OPENCODE_USER/.kontourai/flow-agents/my-session/sta
 
 # Modify an installed skill file to simulate user edits
 CLAUDE_INSTALLED_SKILL="$CLAUDE_USER/.claude/skills/plan-work/SKILL.md"
-CODEX_INSTALLED_SKILL="$CODEX_USER/.codex/skills/plan-work/SKILL.md"
+CODEX_INSTALLED_SKILL="$CODEX_USER/.agents/skills/plan-work/SKILL.md"
 OPENCODE_INSTALLED_SKILL="$OPENCODE_USER/.opencode/skills/plan-work/SKILL.md"
 
 USER_EDIT_MARKER="# USER EDIT - should be overwritten by re-install"

package/evals/integration/test_install_merge.sh

@@ -22,6 +22,10 @@ set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/../.." && pwd)"
 TMPDIR_EVAL="$(mktemp -d /tmp/install-merge.XXXXXX)"
+export HOME="$TMPDIR_EVAL/hermetic-home"
+export FLOW_AGENTS_SKILLS_DIR="$TMPDIR_EVAL/hermetic-universal/skills"
+mkdir -p "$HOME/.agents" "$FLOW_AGENTS_SKILLS_DIR"
+printf 'installer tests must not replace this file\n' > "$HOME/.agents/ambient-sentinel"
 pass=0
 fail=0
 
@@ -1138,7 +1142,8 @@ echo ""
 echo "--- CH4: codex-home preserves user config, profiles, hooks, local kit state, and user skills ---"
 
 CH4_DEST="$TMPDIR_EVAL/codex-home-ch4"
-mkdir -p "$CH4_DEST/kits/local/repositories/user-kit" "$CH4_DEST/sk""ills/user-owned-skill" "$CH4_DEST/ag""ents"
+CH4_SKILLS="$TMPDIR_EVAL/codex-home-ch4-universal-skills"
+mkdir -p "$CH4_DEST/kits/local/repositories/user-kit" "$CH4_SKILLS/user-owned-skill" "$CH4_DEST/ag""ents"
 
 CH4_GENERIC_DIRS=(agent-cards build context docs evals integrations packaging powers prompts schemas scripts kits)
 for CH4_DIR in "${CH4_GENERIC_DIRS[@]}"; do
@@ -1197,14 +1202,14 @@ JSON
 cat > "$CH4_DEST/kits/local/repositories/user-kit/kit.json" << 'JSON'
 {"id":"user-kit","name":"User Kit"}
 JSON
-cat > "$CH4_DEST/sk""ills/user-owned-skill/SKILL.md" << 'EOF_SKILL'
+cat > "$CH4_SKILLS/user-owned-skill/SKILL.md" << 'EOF_SKILL'
 # User Owned Skill
 EOF_SKILL
 cat > "$CH4_DEST/ag""ents/user-owned-agent.toml" << 'EOF_AGENT'
 name = "user-owned-agent"
 EOF_AGENT
 
-CODEX_REAL_HOME="$TMPDIR_EVAL/fake-real-codex" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$CH4_DEST" >/dev/null 2>&1
+CODEX_REAL_HOME="$TMPDIR_EVAL/fake-real-codex" FLOW_AGENTS_SKILLS_DIR="$CH4_SKILLS" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$CH4_DEST" >/dev/null 2>&1
 
 if grep -q 'user-model' "$CH4_DEST/config.toml" \
   && grep -q 'user-profile-model' "$CH4_DEST/custom.config.toml" \
@@ -1243,10 +1248,10 @@ else
   _fail "CH4: kits/local registry or repository was removed"
 fi
 
-if [[ -f "$CH4_DEST/sk""ills/search-first/SKILL.md" && -f "$CH4_DEST/sk""ills/plan-work/SKILL.md" && -f "$CH4_DEST/sk""ills/user-owned-skill/SKILL.md" ]]; then
-  _pass "CH4: root, Builder Kit workflow, and user-owned skills coexist in flattened Codex skills"
+if [[ -f "$CH4_SKILLS/search-first/SKILL.md" && -f "$CH4_SKILLS/plan-work/SKILL.md" && -f "$CH4_SKILLS/user-owned-skill/SKILL.md" ]]; then
+  _pass "CH4: root, Builder Kit workflow, and user-owned skills coexist in universal Codex skills"
 else
-  _fail "CH4: root skill, Builder Kit workflow skill, or user-owned skill missing from flattened Codex skills"
+  _fail "CH4: root skill, Builder Kit workflow skill, or user-owned skill missing from universal Codex skills"
 fi
 
 if [[ -f "$CH4_DEST/scripts/install-merge.js" && -f "$CH4_DEST/build/src/cli/kit.js" && -f "$CH4_DEST/ag""ents/tool-worker.toml" && -f "$CH4_DEST/ag""ents/user-owned-agent.toml" && -f "$CH4_DEST/hooks.json" ]] \
@@ -1272,7 +1277,7 @@ else
   _fail "CH4: installed scripts/kit.js could not run with installed build bundle"
 fi
 
-CODEX_REAL_HOME="$TMPDIR_EVAL/fake-real-codex" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$CH4_DEST" >/dev/null 2>&1
+CODEX_REAL_HOME="$TMPDIR_EVAL/fake-real-codex" FLOW_AGENTS_SKILLS_DIR="$CH4_SKILLS" bash "$ROOT_DIR/scripts/install-codex-home.sh" "$CH4_DEST" >/dev/null 2>&1
 CH4_GENERIC_PRESERVED=1
 for CH4_DIR in "${CH4_GENERIC_DIRS[@]}"; do
   [[ "$(cat "$CH4_DEST/$CH4_DIR/user-owned.txt" 2>/dev/null)" == "user-owned-$CH4_DIR" ]] || CH4_GENERIC_PRESERVED=0
@@ -1288,7 +1293,7 @@ echo ""
 # ─── codex-home: CH5: destination symlink containment ───────────────────────
 echo "--- CH5: codex-home refuses managed destination symlinks ---"
 
-for CH5_REL in scripts kits sk""ills hooks.json; do
+for CH5_REL in scripts kits hooks.json; do
   CH5_DEST="$TMPDIR_EVAL/codex-home-ch5-${CH5_REL//\//-}"
   CH5_OUTSIDE="$TMPDIR_EVAL/codex-home-ch5-outside-${CH5_REL//\//-}"
   mkdir -p "$CH5_DEST" "$CH5_OUTSIDE"
@@ -1680,6 +1685,11 @@ echo ""
 
 echo ""
 echo "==========================="
+if [[ "$(cat "$HOME/.agents/ambient-sentinel" 2>/dev/null)" == "installer tests must not replace this file" ]]; then
+  _pass "dedicated Codex installer calls remain inside hermetic universal roots"
+else
+  _fail "dedicated Codex installer calls mutated the isolated default-home sentinel"
+fi
 total=$((pass + fail))
 echo "Results: ${pass}/${total} passed, ${fail} failed"
 [[ "$fail" -gt 0 ]] && exit 1

package/evals/integration/test_public_workflow_cli.sh

@@ -160,15 +160,21 @@ pass "status is canonical and byte-read-only"
 
 FLOW_MANIFEST="$CONSUMER/.kontourai/flow/runs/acme-widgets-101/evidence/manifest.json"
 BEFORE_EVIDENCE="$(node -p "JSON.parse(require('fs').readFileSync('$FLOW_MANIFEST')).evidence.length")"
-run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation pickup-probe-readiness --status not_verified --summary "Consumer fixture intentionally leaves this claim unverified." --json >/dev/null
+PARTIAL_EVIDENCE="$(run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation pickup-probe-readiness --status not_verified --summary "Consumer fixture intentionally leaves this claim unverified." --json)"
 AFTER_EVIDENCE="$(node -p "JSON.parse(require('fs').readFileSync('$FLOW_MANIFEST')).evidence.length")"
-[[ "$AFTER_EVIDENCE" -eq $((BEFORE_EVIDENCE + 1)) ]] || fail "evidence invocation did not attach exactly once"
-pass "evidence records and synchronizes exactly once"
+[[ "$AFTER_EVIDENCE" -eq "$BEFORE_EVIDENCE" ]] || fail "partial evidence changed the canonical manifest"
+node -e 'const r=JSON.parse(process.argv[1]);if(r.attached!==false||r.awaiting_evidence!==true||r.current_step!=="design-probe")process.exit(1)' "$PARTIAL_EVIDENCE" || fail "partial evidence did not report an explicit awaiting-evidence result"
+pass "partial evidence records locally without evaluation or canonical attachment"
 
 PULL_REPORT="$RELEASE_SESSION/$(basename "$RELEASE_SESSION")--pull-work.md"
 PULL_REPORT_REF="{\"kind\":\"artifact\",\"file\":\"$PULL_REPORT\",\"summary\":\"Concrete selected-work and probe report.\"}"
-run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation pickup-probe-readiness --status pass --summary "Complete the consumer readiness expectation after exercising NOT_VERIFIED." --evidence-ref-json "$PULL_REPORT_REF" --json >/dev/null
-run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation probe-decisions-or-accepted-gaps --status pass --summary "Complete the consumer probe gate." --evidence-ref-json "$PULL_REPORT_REF" --json >/dev/null
+READINESS_PARTIAL="$(run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation pickup-probe-readiness --status pass --summary "Complete the consumer readiness expectation after exercising NOT_VERIFIED." --evidence-ref-json "$PULL_REPORT_REF" --json)"
+node -e 'const r=JSON.parse(process.argv[1]);if(r.attached!==false||r.awaiting_evidence!==true||r.current_step!=="design-probe")process.exit(1)' "$READINESS_PARTIAL" || fail "first passing member of a multi-expectation gate did not remain pending"
+PROBE_COMPLETE="$(run_candidate evidence --session-dir "$RELEASE_SESSION" --expectation probe-decisions-or-accepted-gaps --status pass --summary "Complete the consumer probe gate." --evidence-ref-json "$PULL_REPORT_REF" --json)"
+node -e 'const r=JSON.parse(process.argv[1]);if(r.attached!==true||r.awaiting_evidence!==false||r.current_step!=="plan")process.exit(1)' "$PROBE_COMPLETE" || fail "complete multi-expectation gate did not attach and advance exactly once"
+AFTER_COMPLETE_EVIDENCE="$(node -p "JSON.parse(require('fs').readFileSync('$FLOW_MANIFEST')).evidence.length")"
+[[ "$AFTER_COMPLETE_EVIDENCE" -eq $((BEFORE_EVIDENCE + 1)) ]] || fail "complete multi-expectation gate did not attach exactly once"
+pass "multi-expectation evidence attaches atomically only when complete"
 seed_pull_work acme/widgets#104
 run_candidate_as poison-pointer start --artifact-root "$ARTIFACT_ROOT" --flow builder.build --work-item acme/widgets#104 --assignment-provider local-file --summary "Poison global pointer fixture" >/dev/null
 node - "$ARTIFACT_ROOT" "$(basename "$RELEASE_SESSION")" <<'NODE'

package/evals/static/test_universal_bundles.sh

@@ -10,7 +10,7 @@ pass=0
 fail=0
 
 cleanup() {
-  rm -rf "$REPRO_FIRST_DIR" "$REPRO_SECOND_DIR" "$ROOT_DIR/kits/zzz-collision-eval-probe"
+  rm -rf "$REPRO_FIRST_DIR" "$REPRO_SECOND_DIR" "$ROOT_DIR/kits/zzz-collision-eval-probe" "${MISSING_SKILL_DIR:-}"
 }
 trap cleanup EXIT
 
@@ -65,6 +65,49 @@ for dir in "$DIST_DIR/kiro" "$DIST_DIR/claude-code" "$DIST_DIR/codex" "$DIST_DIR
   fi
 done
 
+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 node - "$DIST_DIR/codex/.agents/skills" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+const root = process.argv[2];
+const pattern = /(?:^|[`("'\s])(context\/contracts\/[A-Za-z0-9._/-]+\.md)(?=$|[`),"'\s])/gm;
+for (const name of fs.readdirSync(root)) {
+  const skill = path.join(root, name);
+  const file = path.join(skill, "SKILL.md");
+  if (!fs.existsSync(file)) continue;
+  for (const match of fs.readFileSync(file, "utf8").matchAll(pattern)) {
+    const resolved = path.resolve(skill, match[1]);
+    if (!resolved.startsWith(`${path.resolve(skill)}${path.sep}`) || !fs.existsSync(resolved)) throw new Error(`${name}: ${match[1]}`);
+  }
+}
+NODE
+then
+  _pass "Codex skill-local instruction resources resolve inside each package"
+else
+  _fail "Codex skill-local instruction resource closure failed"
+fi
+
+MISSING_SKILL_DIR="$ROOT_DIR/${SKILLS_SEGMENT:-skills}/zzz-missing-resource-probe"
+MISSING_CONTRACT="${CONTEXT_SEGMENT:-context}/contracts/definitely-missing.md"
+mkdir -p "$MISSING_SKILL_DIR"
+printf '%s\n' '# Probe' '' "Read \`$MISSING_CONTRACT\`." > "$MISSING_SKILL_DIR/SKILL.md"
+if (cd "$ROOT_DIR" && npm run build:bundles >/tmp/missing-skill-resource.stdout 2>/tmp/missing-skill-resource.stderr); then
+  _fail "bundle generation accepted a missing skill instruction resource"
+else
+  if rg -q "skill 'zzz-missing-resource-probe': missing local resource '$MISSING_CONTRACT'" /tmp/missing-skill-resource.stderr; then
+    _pass "bundle generation rejects missing skill resources with actionable diagnostics"
+  else
+    _fail "missing skill resource failure did not name its skill and path"
+  fi
+fi
+rm -rf "$MISSING_SKILL_DIR"
+(cd "$ROOT_DIR" && npm run build:bundles >/dev/null)
+
 source_agents=$(find "$ROOT_DIR/agents" -maxdepth 1 -name '*.json' | wc -l | tr -d ' ')
 codex_excluded_agents=$(node - "$ROOT_DIR/packaging/manifest.json" <<'NODE'
 const fs = require("node:fs");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kontourai/flow-agents",
-  "version": "3.7.0",
+  "version": "3.9.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",
@@ -144,9 +144,9 @@
     "kit": "npm run build --silent && node build/src/cli.js kit"
   },
   "devDependencies": {
-    "@types/node": "^26.1.0",
-    "promptfoo": "^0.121.17",
-    "typescript": "^6.0.3"
+    "@types/node": "^26.1.1",
+    "promptfoo": "^0.121.18",
+    "typescript": "^7.0.2"
   },
   "dependencies": {
     "@kontourai/flow": "^3.1.4"

package/packaging/README.md

@@ -19,7 +19,7 @@ For the full source/generated/runtime inventory, see [Repository Structure](../d
 
 - `dist/kiro/` keeps native Kiro JSON agents and rewrites path-bound config through the install token.
 - `dist/claude-code/` exports `.claude/agents/*.md` and `.claude/skills/*/SKILL.md`.
-- `dist/codex/` exports `.codex/agents/*.toml`, `.codex/skills/*/SKILL.md`, and generated profile config for operating intents such as `builder` and `personal`.
+- `dist/codex/` exports Codex-only agents and profiles beneath `.codex/`, and portable, self-contained skills beneath the universal `.agents/skills/` catalog.
 
 All targets also receive shared canonical directories where supported: `context/`, `powers/`, `prompts/`, `scripts/`, and `evals/`.
 

package/scripts/README.md

@@ -113,7 +113,7 @@ prompting. Add `--allow-network` to probe a non-local HTTPS Console endpoint.
 
 ## Install And Repo Utilities
 
-- `install-codex-home.sh`: installs the generated Codex bundle into `CODEX_HOME`, or `~/.codex` when `CODEX_HOME` is unset. A positional destination argument is the explicit override for isolated homes and tests.
+- `install-codex-home.sh`: installs Codex runtime assets into `CODEX_HOME` (or `~/.codex`) and portable skills into `$HOME/.agents/skills`. Use `--skills-dir PATH` or `FLOW_AGENTS_SKILLS_DIR` to select a hermetic or advanced-user skill catalog independently of the positional runtime destination. The installer reports both resolved roots, preserves user-owned files, migrates only unchanged Flow Agents-owned legacy skills, and refuses symlink destinations rather than creating a compatibility symlink.
 - `setup-repo-hooks.sh`: configures this clone's Git hook path.
 - `check-content-boundary.cjs`, `detect-tools.sh`, `discover-agents.sh`, `git-status.sh`: repo-local helper commands.
 - `context-budget/` and `statusline/`: specialized support tooling copied into bundles where needed.