@kontourai/flow-agents 3.2.0 → 3.4.0

package/scripts/hooks/workflow-steering.js

@@ -18,8 +18,9 @@ const fs = require('fs');
 const path = require('path');
 const { readLivenessEvents, freshHolders } = require('./lib/liveness-read');
 const { resolveActor } = require('./lib/actor-identity');
-const { flowAgentsArtifactRootsForRead } = require('./lib/local-artifact-paths');
+const { flowAgentsArtifactRootsForRead, resolveSharedRepoRoot, warnIfFailingOpenInsideGitTree } = require('./lib/local-artifact-paths');
 const { readCurrentPointer } = require('./lib/current-pointer');
+const { workflowTriggersFor } = require('./lib/kit-catalog');
 
 const STEERING = {
   'tool-planner': [
@@ -71,14 +72,36 @@ const ACTIVE_STATE_STATUSES = new Set([
 ]);
 
 function findRepoRoot(startDir) {
-  let dir = path.resolve(startDir || process.cwd());
+  const resolvedStartDir = path.resolve(startDir || process.cwd());
+  // #357: prefer git's SHARED common-dir root (the primary checkout's repo root, resolved
+  // identically from any linked worktree) before falling back to the plain `.git`/AGENTS.md
+  // ancestor walk below. Without this, a worktree's OWN `.git` FILE (not the shared `.git`
+  // DIRECTORY) satisfies `fs.existsSync(path.join(dir, '.git'))` at the very first directory
+  // checked, so the walk always stopped at the worktree root instead of resolving to the
+  // shared primary checkout — see src/lib/local-artifact-root.ts's resolveSharedRepoRoot doc
+  // comment for the full rationale. Fails open to the walk below (unchanged) when git is
+  // unavailable, `resolvedStartDir` is not inside a git working tree, or the command fails —
+  // this is also exactly today's behavior in the single-checkout case, where
+  // `--git-common-dir` resolves to `.git` under `resolvedStartDir` itself.
+  const sharedRoot = resolveSharedRepoRoot(resolvedStartDir);
+  if (sharedRoot) return sharedRoot;
+  let dir = resolvedStartDir;
   const root = path.parse(dir).root;
   for (let depth = 0; dir && depth < 40; depth++) {
-    if (fs.existsSync(path.join(dir, '.git')) || fs.existsSync(path.join(dir, 'AGENTS.md'))) return dir;
+    if (fs.existsSync(path.join(dir, '.git'))) {
+      // #413 iteration-2 Fix 1: resolveSharedRepoRoot failed above even though a `.git` entry
+      // exists right here — git resolution was ATTEMPTED and FAILED (corrupted gitlink, bad
+      // GIT_DIR, git unavailable, etc.), not merely "no git repo at all". Loud, not silent —
+      // see warnIfFailingOpenInsideGitTree's own doc comment for the full rationale. This walk
+      // still returns `dir` (the ancestor-walk fallback is preserved unchanged) after warning.
+      warnIfFailingOpenInsideGitTree(resolvedStartDir, dir);
+      return dir;
+    }
+    if (fs.existsSync(path.join(dir, 'AGENTS.md'))) return dir;
     if (dir === root) break;
     dir = path.dirname(dir);
   }
-  return path.resolve(startDir || process.cwd());
+  return resolvedStartDir;
 }
 
 function walkStateFiles(dir, out = []) {
@@ -159,8 +182,25 @@ function latestWorkflowState(root) {
   return states[0] || null;
 }
 
+// #293 AC7 (injection discipline): strips C0 (0x00-0x1F), DEL (0x7F), and C1 (0x80-0x9F,
+// which includes ANSI-CSI-adjacent bytes) BEFORE whitespace-collapse/truncation — mirroring
+// src/cli/workflow-sidecar.ts's stripControlCharsForDisplay / assignment-provider.ts's
+// sanitizeDisplayField exactly (same charset, same rationale: holder/actor/assignee strings
+// sourced from the shared multi-writer liveness stream or an attacker-postable GitHub comment
+// are untrusted display input). Previously this function only collapsed whitespace, so a raw
+// ESC/BEL byte embedded in a hostile actor string passed through unstripped into every steering
+// notice that calls safeStateText (resumeSteering's LIVENESS WARNING block, supersessionSteering's
+// SUPERSEDED notice) — fixed here, in the one shared helper, rather than in each call site.
 function safeStateText(value, maxLength = 240) {
-  const text = String(value || '').replace(/\s+/g, ' ').trim();
+  // Whitespace-collapse FIRST (so an embedded newline/tab becomes a joining space, preserving
+  // the existing multiline-summary neutralization behavior), THEN strip control/ANSI bytes
+  // (#293 AC7) — reversing this order would strip \n before the collapse ever sees it, losing
+  // the join-space between sentences. Only C0/DEL/C1 bytes THAT SURVIVE the collapse (ESC, BEL,
+  // and other non-whitespace control bytes — real \s already became a plain space above) are
+  // stripped, mirroring src/cli/workflow-sidecar.ts's stripControlCharsForDisplay /
+  // assignment-provider.ts's sanitizeDisplayField charset exactly.
+  const collapsed = String(value || '').replace(/\s+/g, ' ').trim();
+  const text = collapsed.replace(/[\u0000-\u001F\u007F-\u009F]/g, '');
   if (text.length <= maxLength) return text;
   return `${text.slice(0, maxLength - 3)}...`;
 }
@@ -227,6 +267,9 @@ function stateSteering(root) {
     `STATE: ${state.task_slug || path.basename(path.dirname(current.file))} is status:${state.status} phase:${state.phase}.`,
   ];
   if (next.summary) parts.push(`Recorded next_action.summary: "${safeStateText(next.summary)}"`);
+  if (Array.isArray(next.skills) && next.skills.length) parts.push(`Required skills: ${next.skills.map(skill => safeStateText(skill, 80)).join(' -> ')}.`);
+  if (Array.isArray(next.operations) && next.operations.length) parts.push(`Required operations: ${next.operations.map(operation => safeStateText(operation, 80)).join(' -> ')}.`);
+  if (next.command) parts.push(`Run: ${safeStateText(next.command, 240)}`);
   if (next.target_phase) parts.push(`Target phase: ${safeStateText(next.target_phase, 80)}.`);
   if (next.status === 'needs_user' || state.status === 'needs_decision' || state.status === 'not_verified') {
     parts.push('Do not deliver as complete until the user decision or accepted gap is recorded.');
@@ -248,6 +291,52 @@ function contextMapSteering(root) {
   ].join(' ');
 }
 
+/**
+ * Compose the SessionStart advisory line for installed-skill drift (#439). Fires only inside a
+ * kit-bearing checkout (repo has `kits/` AND a built `dist/claude-code/.claude/skills` bundle) —
+ * never triggers a build itself, staying read-only and cheap on every SessionStart. Returns ''
+ * (never throws past this function) in every other case: not kit-bearing, no manifest yet, no
+ * drift found, or any internal error.
+ *
+ * Reuses the SINGLE shared classification choke point, `scripts/hooks/lib/skill-drift.js`'s
+ * `compareSkillDrift()` — this function must never hand-roll its own drift comparison (same
+ * convention the CLI check and the manifest writer follow, see #439 plan).
+ *
+ * @param {string} root  Repository root
+ * @returns {string}
+ */
+function skillDriftSteering(root) {
+  try {
+    if (!fs.existsSync(path.join(root, 'kits'))) return '';
+    if (!fs.existsSync(path.join(root, 'dist', 'claude-code', '.claude', 'skills'))) return '';
+
+    const { loadManifest, compareSkillDrift, resolveClaudeGlobalSkillsDir } = require('./lib/skill-drift');
+
+    const destDir = resolveClaudeGlobalSkillsDir(process.env);
+    // Sibling layout: <destDir>/.flow-agents/skills-manifest.json — mirrors
+    // src/lib/local-artifact-root.ts's durableFlowAgentsRoot(destDir)/skillsManifestPath exactly
+    // (durableFlowAgentsRoot(cwd) resolves to `${cwd}/.flow-agents`, no parent traversal).
+    const manifestPath = path.join(destDir, '.flow-agents', 'skills-manifest.json');
+    const manifest = loadManifest(manifestPath);
+
+    const installedDir = path.join(destDir, 'skills');
+    const kitSourceDir = path.join(root, 'dist', 'claude-code', '.claude', 'skills');
+    const report = compareSkillDrift({ installedDir, kitSourceDir, manifest });
+    if (!report.hasDrift) return '';
+
+    const { kitUpdated, userModified, unbaselined, missingInstall, kitRemoved } = report.summary;
+    // kit_removed (#439 review fix) folds into staleCount alongside the other non-in_sync
+    // states — this advisory line only ever surfaces kit-updated/user-modified counts by name
+    // (see the template string below), so kit_removed does not get its own named count here; it
+    // is still reflected in the total. Full per-state detail is always available via
+    // `flow-agents skill-drift-check`.
+    const staleCount = kitUpdated + userModified + unbaselined + missingInstall + kitRemoved;
+    return `[SKILL DRIFT] ${staleCount} installed Claude Code skill file(s) are stale vs this kit (${kitUpdated} kit-updated, ${userModified} user-modified). Run \`flow-agents init --runtime claude-code --global\` to refresh (user-modified files are reported, not overwritten). See \`flow-agents skill-drift-check\` for details.`;
+  } catch {
+    return '';
+  }
+}
+
 function promptText(input) {
   const candidates = [
     input && input.prompt,
@@ -262,7 +351,7 @@ function promptText(input) {
   return '';
 }
 
-function looksLikeBuilderWork(text) {
+function looksLikeImplementationWork(text) {
   const normalized = safeStateText(text, 2000).toLowerCase();
   if (!normalized) return false;
   const readOnlyIntent = /\b(read[- ]only|review[- ]only|no (source |code |file )?(changes?|edits?|modifications?)|do not (modify|edit|change|write|fix|implement|touch)|don't (modify|edit|change|write|fix|implement|touch)|dont (modify|edit|change|write|fix|implement|touch))\b/.test(normalized);
@@ -281,17 +370,29 @@ function looksLikeBuilderWork(text) {
   return hasWorkVerb || (hasWorkObject && hasRequestLanguage);
 }
 
-function builderWorkflowSteering(input) {
-  if (!looksLikeBuilderWork(promptText(input))) return '';
-  return [
-    'BUILDER WORKFLOW ROUTE: this user prompt looks like coding/build work.',
-    'Builder lifecycle: shape raw ideas -> build selected work -> publish verified branch/PR -> learn correction feedback.',
-    'Before source edits or implementation commands, activate Builder Kit delivery workflow.',
-    'If the user explicitly requested TDD, activate `tdd-workflow`; otherwise activate `deliver` and keep the session on `builder.build`.',
-    'Use `npm run workflow:sidecar -- ensure-session --flow-id builder.build ...` when the repo provides the sidecar writer.',
-    'After local verification, continue to publish/release-readiness and learning-review; do not treat local verification as terminal delivery.',
-    'Do not bypass plan-work -> execute-plan -> review-work -> verify-work for coding tasks; direct implementation is only acceptable when the user explicitly asks for no workflow or explanation-only help.',
-  ].join(' ');
+function looksLikeKnowledgeWork(text) {
+  const normalized = safeStateText(text, 2000).toLowerCase();
+  if (!normalized) return false;
+  return /\b(remember|capture|save|file|bookmark)\s+(this|that|the|my|our)\b/.test(normalized) ||
+    /\bcapture\s+(this\s+)?(decision|learning|lesson|note|context)\b/.test(normalized) ||
+    /\bwhat did we learn about\b/.test(normalized);
+}
+
+function kitWorkflowSteering(input, root) {
+  const prompt = promptText(input);
+  const categories = [];
+  if (looksLikeImplementationWork(prompt)) categories.push('implementation-work-detected');
+  if (looksLikeKnowledgeWork(prompt)) categories.push('knowledge-capture-detected');
+  if (!categories.length) return '';
+  try {
+    return categories
+      .flatMap(category => workflowTriggersFor(root, category))
+      .map(trigger => trigger.steering)
+      .filter(Boolean)
+      .join('\n');
+  } catch {
+    return '';
+  }
 }
 
 /**
@@ -324,6 +425,13 @@ function resumeSteering(root, current) {
     // Full next action (240-char display path, not the 80-char normalization)
     const nextSummary = next.summary ? safeStateText(next.summary, 240) : 'none';
     lines.push(`Next action: ${nextSummary}`);
+    if (Array.isArray(next.skills) && next.skills.length) {
+      lines.push(`Required skills: ${next.skills.map(skill => safeStateText(skill, 80)).join(' -> ')}`);
+    }
+    if (Array.isArray(next.operations) && next.operations.length) {
+      lines.push(`Required operations: ${next.operations.map(operation => safeStateText(operation, 80)).join(' -> ')}`);
+    }
+    if (next.command) lines.push(`Run: ${safeStateText(next.command, 240)}`);
 
     // Plan artifact path
     let planPath = 'not found';
@@ -411,6 +519,51 @@ function resumeSteering(root, current) {
   }
 }
 
+/**
+ * Compose the every-turn SUPERSEDED steering notice (issue #293).
+ *
+ * Unlike resumeSteering()'s RESUME block (SessionStart only), this notice must
+ * surface on EVERY turn (UserPromptSubmit as well as SessionStart) once another
+ * actor holds a fresh liveness claim on the caller's own subject — the
+ * "don't publish, you may be stale" signal the verify-hold gate backstops at
+ * publish time. Reuses the SAME liveness-only join resumeSteering()'s liveness
+ * advisory block already performs (freshHolders(events, slug, selfActor, now)),
+ * not a second computation.
+ *
+ * freshHolders() already excludes selfActor internally (see
+ * scripts/hooks/lib/liveness-read.js), so any holder returned here is by
+ * definition another actor — no additional self-filter is required.
+ *
+ * Fully fail-open: any error anywhere in this function returns '' rather than
+ * throwing, matching every other steering helper in this file.
+ *
+ * @param {string} root     Repository root
+ * @param {{ file: string, payload: object }} current  Latest active state entry (this actor's own)
+ * @returns {string}
+ */
+function supersessionSteering(root, current) {
+  try {
+    const state = current.payload;
+    const workflowDir = path.dirname(current.file);
+    const slug = state.task_slug || path.basename(workflowDir);
+
+    const resolved = resolveActor(process.env);
+    const selfActor = resolved.actor || 'local';
+
+    const events = flowAgentsArtifactRootsForRead(root)
+      .flatMap(artifactRoot => readLivenessEvents(path.join(artifactRoot, 'liveness', 'events.jsonl')));
+    if (events.length === 0) return '';
+
+    const holders = freshHolders(events, slug, selfActor, Date.now());
+    if (holders.length === 0) return '';
+
+    const holder = holders[0];
+    return `[SUPERSEDED: another agent appears live on this work: actor ${safeStateText(holder.actor)}, last seen ${holder.lastAt}. Your claim on this subject may be stale — do not publish until you re-verify hold (see verify-hold gate) or hand off.]`;
+  } catch {
+    return '';
+  }
+}
+
 function run(rawInput) {
   try {
     const input = JSON.parse(rawInput);
@@ -443,18 +596,35 @@ function run(rawInput) {
     }
 
     if (event === 'UserPromptSubmit') {
-      const builderHint = builderWorkflowSteering(input);
-      if (builderHint) {
-        hints.push(builderHint);
+      const kitHint = kitWorkflowSteering(input, root);
+      if (kitHint) {
+        hints.push(kitHint);
         const contextHint = contextMapSteering(root);
         if (contextHint) hints.push(contextHint);
       }
     }
 
+    // Every-turn supersession notice (#293): fires on UserPromptSubmit (every turn),
+    // not just SessionStart, so a takeover mid-session keeps surfacing the warning.
+    if (event === 'UserPromptSubmit' && current) {
+      const supersessionHint = supersessionSteering(root, current);
+      if (supersessionHint) hints.push(supersessionHint);
+    }
+
     // SessionStart only: append the RESUME block for richer situational awareness
     if (event === 'SessionStart' && current) {
       const resumeBlock = resumeSteering(root, current);
       if (resumeBlock) hints.push(resumeBlock);
+      const supersessionHint = supersessionSteering(root, current);
+      if (supersessionHint) hints.push(supersessionHint);
+    }
+
+    // SessionStart only, unconditional of `current` (#439): the installed-skill drift advisory
+    // fires on every SessionStart inside a kit-bearing checkout, independent of whether an active
+    // workflow session exists — do NOT fold this into the `current`-gated block above.
+    if (event === 'SessionStart') {
+      const driftHint = skillDriftSteering(root);
+      if (driftHint) hints.push(driftHint);
     }
 
     if (shouldAppendWorkflowContext) {
@@ -487,12 +657,14 @@ module.exports = {
   stateSteering,
   critiqueSteering,
   contextMapSteering,
+  skillDriftSteering,
   latestWorkflowState,
   findRepoRoot,
   safeStateText,
   stateNeedsAmbientSteering,
   resumeSteering,
+  supersessionSteering,
   promptText,
-  looksLikeBuilderWork,
-  builderWorkflowSteering,
+  looksLikeImplementationWork,
+  kitWorkflowSteering,
 };

package/scripts/install-codex-home.sh

@@ -51,6 +51,41 @@ while [[ $# -gt 0 ]]; do
   esac
 done
 REAL_CODEX_HOME="${CODEX_REAL_HOME:-$HOME/.codex}"
+
+canonicalize_path() {
+  node - "$1" <<'NODE'
+const fs = require("node:fs");
+const path = require("node:path");
+let current = path.resolve(process.argv[2]);
+const missing = [];
+while (!fs.existsSync(current)) {
+  missing.unshift(path.basename(current));
+  const parent = path.dirname(current);
+  if (parent === current) break;
+  current = parent;
+}
+process.stdout.write(path.resolve(fs.realpathSync(current), ...missing));
+NODE
+}
+
+[[ ! -L "$DEST" ]] || { echo "install-codex-home.sh: refusing symlink destination root: $DEST" >&2; exit 1; }
+ROOT_REAL="$(canonicalize_path "$ROOT_DIR")"
+BUNDLE_SOURCE_REAL="$(canonicalize_path "$ROOT_DIR/dist/codex")"
+DEST_REAL="$(canonicalize_path "$DEST")"
+REAL_CODEX_HOME_REAL="$(canonicalize_path "$REAL_CODEX_HOME")"
+case "$DEST_REAL/" in
+  "$ROOT_REAL/"*|"$BUNDLE_SOURCE_REAL/"*)
+    echo "install-codex-home.sh: destination overlaps Flow Agents source: $DEST_REAL" >&2
+    exit 1
+    ;;
+esac
+case "$ROOT_REAL/" in
+  "$DEST_REAL/"*)
+    echo "install-codex-home.sh: Flow Agents source overlaps destination: $DEST_REAL" >&2
+    exit 1
+    ;;
+esac
+
 if command -v npm >/dev/null 2>&1; then
   (cd "$ROOT_DIR" && FLOW_AGENTS_EXPORT_DIAGNOSTICS=0 npm run build:bundles --silent >/dev/null)
 else
@@ -59,7 +94,8 @@ else
 fi
 
 mkdir -p "$DEST"
-DEST_REAL="$(cd "$DEST" && pwd -P)"
+DEST="$(cd "$DEST" && pwd -P)"
+DEST_REAL="$DEST"
 
 assert_safe_dest_path() {
   local rel="$1"
@@ -95,10 +131,17 @@ if [[ -f "$DEST/hooks.json" ]]; then
   cp "$DEST/hooks.json" "$FA_USER_HOOKS_STASH"
 fi
 
-# A real Codex home can contain user-owned config, profiles, auth, hooks, and
-# locally installed kits. Update Flow Agents-owned bundle trees in place without
-# deleting that state. `kits/local` is user/runtime state; everything else under
-# the generated bundle paths is managed by this installer.
+# A real Codex home can contain user-owned files in every shared directory.
+# Prepare an exact Flow Agents overlay, then synchronize only files recorded in
+# the ownership manifest. The synchronizer never uses directory-wide --delete:
+# it removes only unchanged files from its prior manifest and refuses collisions.
+FA_OWNED_OVERLAY="$(mktemp -d /tmp/fa-codex-overlay.XXXXXX)"
+cleanup_install_temps() {
+  rm -rf "$FA_OWNED_OVERLAY"
+  [[ -z "${FA_USER_HOOKS_STASH:-}" ]] || rm -f "$FA_USER_HOOKS_STASH"
+}
+trap cleanup_install_temps EXIT
+
 for managed_dir in \
   .flow-agents \
   agent-cards \
@@ -115,52 +158,65 @@ for managed_dir in \
 do
   if [[ -d "$ROOT_DIR/dist/codex/$managed_dir" ]]; then
     assert_safe_dest_path "$managed_dir"
-    mkdir -p "$DEST/$managed_dir"
-    rsync -a --delete "$ROOT_DIR/dist/codex/$managed_dir/" "$DEST/$managed_dir/"
+    mkdir -p "$FA_OWNED_OVERLAY/$managed_dir"
+    rsync -a "$ROOT_DIR/dist/codex/$managed_dir/" "$FA_OWNED_OVERLAY/$managed_dir/"
   fi
 done
 
 # Skills are user-extensible in a real Codex home. Merge both bundle skill
 # layers into the flattened destination without deleting user-owned skills.
 if [[ -d "$ROOT_DIR/dist/codex/skills" ]]; then
-  assert_safe_dest_path "skills"
-  mkdir -p "$DEST/skills"
-  rsync -a "$ROOT_DIR/dist/codex/skills/" "$DEST/skills/"
+  mkdir -p "$FA_OWNED_OVERLAY/skills"
+  rsync -a "$ROOT_DIR/dist/codex/skills/" "$FA_OWNED_OVERLAY/skills/"
 fi
 
 if [[ -d "$ROOT_DIR/dist/codex/.codex/skills" ]]; then
-  assert_safe_dest_path "skills"
-  mkdir -p "$DEST/skills"
-  rsync -a "$ROOT_DIR/dist/codex/.codex/skills/" "$DEST/skills/"
+  mkdir -p "$FA_OWNED_OVERLAY/skills"
+  rsync -a "$ROOT_DIR/dist/codex/.codex/skills/" "$FA_OWNED_OVERLAY/skills/"
 fi
 
 if [[ -d "$ROOT_DIR/dist/codex/kits" ]]; then
-  assert_safe_dest_path "kits"
-  mkdir -p "$DEST/kits"
-  rsync -a --delete --exclude 'local/' "$ROOT_DIR/dist/codex/kits/" "$DEST/kits/"
+  mkdir -p "$FA_OWNED_OVERLAY/kits"
+  rsync -a --exclude 'local/' "$ROOT_DIR/dist/codex/kits/" "$FA_OWNED_OVERLAY/kits/"
 fi
 
 # Agents are user-extensible in a real Codex home. Merge generated agents
 # without deleting user-owned agents.
 if [[ -d "$ROOT_DIR/dist/codex/.codex/agents" ]]; then
-  assert_safe_dest_path "agents"
-  mkdir -p "$DEST/agents"
-  rsync -a "$ROOT_DIR/dist/codex/.codex/agents/" "$DEST/agents/"
+  mkdir -p "$FA_OWNED_OVERLAY/agents"
+  rsync -a "$ROOT_DIR/dist/codex/.codex/agents/" "$FA_OWNED_OVERLAY/agents/"
 fi
 
 for bundle_file in README.md console.telemetry.json install.sh; do
   if [[ -f "$ROOT_DIR/dist/codex/$bundle_file" ]]; then
-    assert_safe_dest_path "$bundle_file"
-    cp "$ROOT_DIR/dist/codex/$bundle_file" "$DEST/$bundle_file"
+    cp "$ROOT_DIR/dist/codex/$bundle_file" "$FA_OWNED_OVERLAY/$bundle_file"
   fi
 done
 
+assert_safe_dest_path ".flow-agents/codex-install-manifest.json"
+node "$ROOT_DIR/scripts/install-owned-files.js" \
+  "$FA_OWNED_OVERLAY" "$DEST" ".flow-agents/codex-install-manifest.json"
+
+atomic_copy() {
+  local source="$1"
+  local rel="$2"
+  assert_safe_dest_path "$rel"
+  local target="$DEST/$rel"
+  if [[ -e "$target" && ! -f "$target" ]]; then
+    echo "install-codex-home.sh: refusing to replace non-file: $target" >&2
+    exit 1
+  fi
+  local temp
+  temp="$(mktemp "$(dirname "$target")/.flow-agents-install.XXXXXX")"
+  cp "$source" "$temp"
+  mv -f "$temp" "$target"
+}
+
 # Root Codex config/profiles and AGENTS.md may be user-owned in ~/.codex.
 # Seed Flow Agents defaults only when absent.
 for seed_file in AGENTS.md; do
   if [[ -f "$ROOT_DIR/dist/codex/$seed_file" && ! -e "$DEST/$seed_file" ]]; then
-    assert_safe_dest_path "$seed_file"
-    cp "$ROOT_DIR/dist/codex/$seed_file" "$DEST/$seed_file"
+    atomic_copy "$ROOT_DIR/dist/codex/$seed_file" "$seed_file"
   fi
 done
 generated_profile_files=()
@@ -173,8 +229,7 @@ for seed_source in "$ROOT_DIR/dist/codex/.codex/config.toml" "$ROOT_DIR"/dist/co
     profile_names+=("${seed_file%.config.toml}")
   fi
   if [[ ! -e "$DEST/$seed_file" ]] || grep -q 'Generated from packaging/manifest.json' "$DEST/$seed_file"; then
-    assert_safe_dest_path "$seed_file"
-    cp "$seed_source" "$DEST/$seed_file"
+    atomic_copy "$seed_source" "$seed_file"
   fi
 done
 for profile_path in "$DEST"/*.config.toml; do
@@ -195,9 +250,8 @@ done
 rmdir "$DEST/.codex" 2>/dev/null || true
 
 for auth_file in auth.json version.json installation_id models_cache.json; do
-  if [[ "$REAL_CODEX_HOME" != "$DEST" && -f "$REAL_CODEX_HOME/$auth_file" ]]; then
-    assert_safe_dest_path "$auth_file"
-    cp "$REAL_CODEX_HOME/$auth_file" "$DEST/$auth_file"
+  if [[ "$REAL_CODEX_HOME_REAL" != "$DEST_REAL" && -f "$REAL_CODEX_HOME_REAL/$auth_file" ]]; then
+    atomic_copy "$REAL_CODEX_HOME_REAL/$auth_file" "$auth_file"
   fi
 done
 
@@ -212,26 +266,22 @@ chmod 700 "$DEST" 2>/dev/null || true
 FA_VERSION="$(node -p "require('$ROOT_DIR/package.json').version" 2>/dev/null || echo unknown)"
 FA_MANAGED_HOOKS="$ROOT_DIR/dist/codex/.codex/hooks.json"
 if command -v node >/dev/null 2>&1 && [[ -f "$FA_MANAGED_HOOKS" ]]; then
-  if [[ -n "$FA_USER_HOOKS_STASH" && -f "$FA_USER_HOOKS_STASH" ]]; then
-    # Merge user's prior hooks (stash) with the current FA managed hooks.
-    node "$ROOT_DIR/scripts/install-merge.js" \
-      --config "$FA_USER_HOOKS_STASH" \
-      --managed-hooks "$FA_MANAGED_HOOKS" \
-      --version "$FA_VERSION" \
-      --install-record "$DEST/.flow-agents/install.json" \
-      --runtime "codex"
-    # Move the merged result into the destination.
-    cp "$FA_USER_HOOKS_STASH" "$DEST/hooks.json"
-    rm -f "$FA_USER_HOOKS_STASH"
-  else
-    # No prior user hooks: just write the version stamp (FA hooks are already correct from rsync).
-    node "$ROOT_DIR/scripts/install-merge.js" \
-      --config "$DEST/hooks.json" \
-      --managed-hooks "$FA_MANAGED_HOOKS" \
-      --version "$FA_VERSION" \
-      --install-record "$DEST/.flow-agents/install.json" \
-      --runtime "codex"
+  FA_HOOKS_WORK="${FA_USER_HOOKS_STASH:-}"
+  if [[ -z "$FA_HOOKS_WORK" ]]; then
+    FA_HOOKS_WORK="$(mktemp /tmp/fa-hooks-work.XXXXXX.json)"
+    printf '{"hooks":{}}\n' > "$FA_HOOKS_WORK"
   fi
+  FA_INSTALL_RECORD_WORK="$(mktemp /tmp/fa-install-record.XXXXXX.json)"
+  node "$ROOT_DIR/scripts/install-merge.js" \
+    --config "$FA_HOOKS_WORK" \
+    --managed-hooks "$FA_MANAGED_HOOKS" \
+    --version "$FA_VERSION" \
+    --install-record "$FA_INSTALL_RECORD_WORK" \
+    --runtime "codex"
+  atomic_copy "$FA_HOOKS_WORK" "hooks.json"
+  atomic_copy "$FA_INSTALL_RECORD_WORK" ".flow-agents/install.json"
+  rm -f "$FA_HOOKS_WORK" "$FA_INSTALL_RECORD_WORK"
+  FA_USER_HOOKS_STASH=""
 fi
 
 if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" || -n "${FLOW_AGENTS_TELEMETRY_SINKS:-}" || -n "${FLOW_AGENTS_CONSOLE_URL:-}" || -n "${CONSOLE_TELEMETRY_URL:-}" || -n "${CONSOLE_URL:-}" || -n "${FLOW_AGENTS_CONSOLE_TOKEN_FILE:-}" || -n "${CONSOLE_TELEMETRY_TOKEN_FILE:-}" ]]; then