@kontourai/flow-agents 3.3.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 = []) {
@@ -244,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.');
@@ -265,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,
@@ -279,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);
@@ -298,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 '';
+  }
 }
 
 /**
@@ -341,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';
@@ -505,9 +596,9 @@ 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);
       }
@@ -528,6 +619,14 @@ function run(rawInput) {
       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) {
       const stateHint = stateSteering(root);
       if (stateHint) hints.push(stateHint);
@@ -558,6 +657,7 @@ module.exports = {
   stateSteering,
   critiqueSteering,
   contextMapSteering,
+  skillDriftSteering,
   latestWorkflowState,
   findRepoRoot,
   safeStateText,
@@ -565,6 +665,6 @@ module.exports = {
   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

package/scripts/install-merge.js

@@ -23,10 +23,13 @@
  *       flow-agents marker (the COLLISION_MARKER strings from init.ts).
  *   (c) APPEND the current managed hook groups from the bundle.
  *   (d) Preserve ALL other keys (permissions, statusLine, user hooks, auth).
+ *       Managed non-hook values are added only when absent or when replacing
+ *       an existing Flow Agents-owned value. Conflicting user-owned values win
+ *       and are reported to stderr.
  *   (e) Atomic write (write tmp + rename).
  *   (f) Write/update .flow-agents/install.json version stamp.
  *
- * Export: mergeSettings(existing, managed) — pure, testable.
+ * Export: mergeSettings(existing, managed, options) — pure, testable.
  * The managed ownership region is identified purely by statusMessage markers
  * (cross-runtime, no top-level key needed in settings.json).
  */
@@ -47,6 +50,33 @@ const FA_MARKERS = [
   "Capturing Flow Agents command evidence",
 ];
 
+const FA_OWNERSHIP_MARKERS = [
+  ...FA_MARKERS,
+  "flow-agents",
+  "Flow Agents",
+];
+
+function stableJson(value) {
+  if (value === undefined) return "undefined";
+  return JSON.stringify(value);
+}
+
+function valuesEqual(a, b) {
+  return stableJson(a) === stableJson(b);
+}
+
+function valueContainsManagedMarker(value) {
+  return FA_OWNERSHIP_MARKERS.some((marker) => stableJson(value).includes(marker));
+}
+
+function conflict(path, existingValue, managedValue) {
+  return { path, existingValue, managedValue };
+}
+
+function emitConflict(onConflict, item) {
+  if (typeof onConflict === "function") onConflict(item);
+}
+
 /**
  * Returns true if a hook-group entry is owned by flow-agents.
  * A hook-group in Claude Code settings looks like:
@@ -95,16 +125,28 @@ function mergeArrayUnion(a, b) {
  * @param {unknown} existingPerms @param {unknown} managedPerms
  * @returns {Record<string, unknown>}
  */
-function mergePermissions(existingPerms, managedPerms) {
+function mergePermissions(existingPerms, managedPerms, options = {}) {
   const e = existingPerms && typeof existingPerms === "object" ? existingPerms : {};
   const m = managedPerms && typeof managedPerms === "object" ? managedPerms : {};
-  const out = Object.assign({}, e, m);
+  const out = Object.assign({}, e);
   for (const listKey of ["allow", "deny", "ask"]) {
     if (Array.isArray(e[listKey]) || Array.isArray(m[listKey])) {
       out[listKey] = mergeArrayUnion(e[listKey], m[listKey]);
     }
   }
-  if (e.defaultMode !== undefined) out.defaultMode = e.defaultMode;
+  for (const [key, value] of Object.entries(m)) {
+    if (["allow", "deny", "ask"].includes(key)) continue;
+    if (!(key in e)) {
+      out[key] = value;
+      continue;
+    }
+    if (valuesEqual(e[key], value) || valueContainsManagedMarker(e[key])) {
+      out[key] = value;
+      continue;
+    }
+    out[key] = e[key];
+    emitConflict(options.onConflict, conflict(`permissions.${key}`, e[key], value));
+  }
   return out;
 }
 
@@ -117,14 +159,17 @@ function mergePermissions(existingPerms, managedPerms) {
  *
  * Returns a new object with:
  *   - All keys from `existing` preserved (permissions, statusLine, auth, etc.)
- *   - All keys from `managed` merged in (flow-agents owned keys like statusLine, hooks)
+ *   - Managed keys added when absent, or updated only when the existing value
+ *     is already Flow Agents-owned.
+ *   - User-owned managed-key conflicts preserved from `existing` and surfaced
+ *     through `options.onConflict`.
  *   - For the `hooks` key: user-owned hook groups (non-FA) survive; FA groups are
  *     replaced with the current managed set from `managed`.
  *
  * Strategy:
  *   1. Start with a shallow copy of `existing` (preserves all user keys).
- *   2. Overlay all scalar/non-hooks keys from `managed` (statusLine, permissions
- *      from the bundle, skipDangerousModePermissionPrompt, etc.).
+ *   2. Add or update Flow Agents-owned non-hooks keys from `managed`; preserve
+ *      user-owned conflicting values and report conflicts.
  *   3. For `hooks`: iterate each event key from both existing and managed;
  *      keep user (non-FA) groups from existing, append the current FA groups
  *      from managed.
@@ -133,19 +178,26 @@ function mergePermissions(existingPerms, managedPerms) {
  * @param {Record<string, unknown>} managed
  * @returns {Record<string, unknown>}
  */
-function mergeSettings(existing, managed) {
+function mergeSettings(existing, managed, options = {}) {
   // 1. Start with all existing keys (preserves user-owned data).
   const result = Object.assign({}, existing);
 
-  // 2. Overlay non-hooks keys from managed. `permissions` is DEEP-merged so the
-  //    user's allow/deny/ask lists + defaultMode survive — flow-agents only adds
-  //    its required entries (#117: never clobber user customizations).
+  // 2. Add non-hooks keys from managed without overwriting user-owned values.
+  //    If a key is absent, add the managed default. If the existing value is
+  //    already Flow Agents-owned (for example the generated statusLine command),
+  //    replace it with the current managed value. Otherwise preserve the user's
+  //    value and surface a conflict so the user can decide.
   for (const [key, value] of Object.entries(managed)) {
     if (key === "hooks") continue;
     if (key === "permissions") {
-      result.permissions = mergePermissions(existing.permissions, value);
-    } else {
+      result.permissions = mergePermissions(existing.permissions, value, options);
+    } else if (!(key in existing)) {
       result[key] = value;
+    } else if (valuesEqual(existing[key], value) || valueContainsManagedMarker(existing[key])) {
+      result[key] = value;
+    } else {
+      result[key] = existing[key];
+      emitConflict(options.onConflict, conflict(key, existing[key], value));
     }
   }
 
@@ -267,7 +319,13 @@ function runMerge({ configPath, managedHooksPath, version, installRecordPath, ru
   }
 
   // (b) + (c) + (d) Merge.
-  const merged = mergeSettings(existing, managed);
+  const conflicts = [];
+  const merged = mergeSettings(existing, managed, { onConflict: (item) => conflicts.push(item) });
+  for (const item of conflicts) {
+    process.stderr.write(
+      `install-merge: conflict: preserving existing setting '${item.path}' and not applying Flow Agents managed value\n`
+    );
+  }
 
   // (e) Atomic write.
   atomicWriteJson(configPath, merged);