@kontourai/flow-agents 2.3.0 → 2.4.0

package/scripts/install-codex-home.sh

@@ -1,5 +1,5 @@
 #!/usr/bin/env bash
-# install-codex-home.sh - Install Flow Agents as an isolated Codex home.
+# install-codex-home.sh - Install Flow Agents into a Codex home.
 set -euo pipefail
 
 ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
@@ -19,7 +19,7 @@ Options:
 EOF
 }
 
-DEST="$HOME/.flow-agents/codex"
+DEST="${CODEX_HOME:-$HOME/.codex}"
 DEST_SET=0
 CONSOLE_CONFIG_ARGS=()
 while [[ $# -gt 0 ]]; do
@@ -59,47 +59,144 @@ else
 fi
 
 mkdir -p "$DEST"
+DEST_REAL="$(cd "$DEST" && pwd -P)"
 
-# Stash the user's existing hooks.json (if any) BEFORE cleaning, so the merge
-# step below can preserve user hooks across re-installs.
+assert_safe_dest_path() {
+  local rel="$1"
+  local current="$DEST"
+  local part
+  IFS='/' read -r -a parts <<< "$rel"
+  for part in "${parts[@]}"; do
+    [[ -n "$part" && "$part" != "." ]] || continue
+    [[ "$part" != ".." ]] || { echo "install-codex-home.sh: unsafe destination path: $rel" >&2; exit 1; }
+    current="$current/$part"
+    if [[ -L "$current" ]]; then
+      echo "install-codex-home.sh: refusing to write through symlink: $current" >&2
+      exit 1
+    fi
+  done
+  local parent
+  parent="$(dirname "$current")"
+  mkdir -p "$parent"
+  local parent_real
+  parent_real="$(cd "$parent" && pwd -P)"
+  case "$parent_real/" in
+    "$DEST_REAL"/*) ;;
+    *) echo "install-codex-home.sh: destination escapes Codex home: $current" >&2; exit 1 ;;
+  esac
+}
+
+# Stash the user's existing hooks.json (if any), so the merge step below can
+# preserve user hooks across installs while replacing Flow Agents-managed groups.
 FA_USER_HOOKS_STASH=""
+assert_safe_dest_path "hooks.json"
 if [[ -f "$DEST/hooks.json" ]]; then
   FA_USER_HOOKS_STASH="$(mktemp /tmp/fa-user-hooks.XXXXXX.json)"
   cp "$DEST/hooks.json" "$FA_USER_HOOKS_STASH"
 fi
 
-# This is an isolated generated Codex home. Clean generated bundle content before
-# overlaying so renamed/deleted source files do not survive across installs.
-rm -rf \
-  "$DEST/.flow-agents" \
-  "$DEST/.codex" \
-  "$DEST/AGENTS.md" \
-  "$DEST/README.md" \
-  "$DEST/console.telemetry.json" \
-  "$DEST/install.sh" \
-  "$DEST/config.toml" \
-  "$DEST/hooks.json" \
-  "$DEST/agent-cards" \
-  "$DEST/agents" \
-  "$DEST/context" \
-  "$DEST/docs" \
-  "$DEST/evals" \
-  "$DEST/integrations" \
-  "$DEST/kits" \
-  "$DEST/packaging" \
-  "$DEST/powers" \
-  "$DEST/prompts" \
-  "$DEST/schemas" \
-  "$DEST/scripts" \
-  "$DEST/skills"
-find "$DEST" -maxdepth 1 -type f -name 'k*.config.toml' -delete
-
-rsync -a "$ROOT_DIR/dist/codex/." "$DEST/"
-rsync -a "$ROOT_DIR/dist/codex/.codex/." "$DEST/"
-rm -rf "$DEST/.codex" 2>/dev/null || true
+# 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.
+for managed_dir in \
+  .flow-agents \
+  agent-cards \
+  build \
+  context \
+  docs \
+  evals \
+  integrations \
+  packaging \
+  powers \
+  prompts \
+  schemas \
+  scripts
+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/"
+  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/"
+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/"
+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/"
+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/"
+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"
+  fi
+done
+
+# 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"
+  fi
+done
+generated_profile_files=()
+profile_names=()
+for seed_source in "$ROOT_DIR/dist/codex/.codex/config.toml" "$ROOT_DIR"/dist/codex/.codex/*.config.toml; do
+  [[ -f "$seed_source" ]] || continue
+  seed_file="$(basename "$seed_source")"
+  if [[ "$seed_file" == *.config.toml ]]; then
+    generated_profile_files+=("$seed_file")
+    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"
+  fi
+done
+for profile_path in "$DEST"/*.config.toml; do
+  [[ -f "$profile_path" ]] || continue
+  profile_file="$(basename "$profile_path")"
+  keep_generated=0
+  for generated_file in "${generated_profile_files[@]}"; do
+    if [[ "$profile_file" == "$generated_file" ]]; then
+      keep_generated=1
+      break
+    fi
+  done
+  if [[ "$keep_generated" -eq 0 ]] && grep -q 'Generated from packaging/manifest.json' "$profile_path"; then
+    assert_safe_dest_path "$profile_file"
+    rm -f "$profile_path"
+  fi
+done
+rmdir "$DEST/.codex" 2>/dev/null || true
 
 for auth_file in auth.json version.json installation_id models_cache.json; do
-  if [[ -f "$REAL_CODEX_HOME/$auth_file" ]]; then
+  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"
   fi
 done
@@ -122,7 +219,7 @@ if command -v node >/dev/null 2>&1 && [[ -f "$FA_MANAGED_HOOKS" ]]; then
       --managed-hooks "$FA_MANAGED_HOOKS" \
       --version "$FA_VERSION" \
       --install-record "$DEST/.flow-agents/install.json" \
-      --runtime "codex" || true
+      --runtime "codex"
     # Move the merged result into the destination.
     cp "$FA_USER_HOOKS_STASH" "$DEST/hooks.json"
     rm -f "$FA_USER_HOOKS_STASH"
@@ -133,7 +230,7 @@ if command -v node >/dev/null 2>&1 && [[ -f "$FA_MANAGED_HOOKS" ]]; then
       --managed-hooks "$FA_MANAGED_HOOKS" \
       --version "$FA_VERSION" \
       --install-record "$DEST/.flow-agents/install.json" \
-      --runtime "codex" || true
+      --runtime "codex"
   fi
 fi
 
@@ -141,5 +238,8 @@ if [[ ${#CONSOLE_CONFIG_ARGS[@]} -gt 0 || -n "${FLOW_AGENTS_TELEMETRY_SINK:-}" |
   bash "$DEST/scripts/telemetry/install-console-config.sh" "$DEST/scripts/telemetry/telemetry.conf" "${CONSOLE_CONFIG_ARGS[@]}"
 fi
 
-echo "Installed isolated Flow Agents Codex home at $DEST"
-echo "Use: CODEX_HOME=$DEST codex --profile kdev"
+echo "Installed Flow Agents into Codex home at $DEST"
+if [[ "${#profile_names[@]}" -gt 0 ]]; then
+  echo "Profiles: ${profile_names[*]}"
+fi
+echo "Use: codex --profile builder"

package/scripts/statusline/flow-agents-statusline.js

@@ -2,7 +2,7 @@
 /**
  * Compact Flow Agents workflow status for runtimes with status bar support.
  *
- * Reads optional runtime JSON from stdin, discovers `.flow-agents`, and
+ * Reads optional runtime JSON from stdin, discovers `.kontourai/flow-agents`, and
  * prints one ASCII line suitable for Claude Code statusLine or Pi setStatus.
  */
 
@@ -56,7 +56,7 @@ function runtimeCwd(input) {
 function findWorkflowRoot(startDir) {
   let current = path.resolve(startDir || process.cwd());
   for (;;) {
-    const candidate = path.join(current, '.flow-agents');
+    const candidate = path.join(current, '.kontourai', 'flow-agents');
     if (fs.existsSync(candidate)) return candidate;
     const parent = path.dirname(current);
     if (parent === current) return null;

package/src/cli/console-learning-projection.ts

@@ -2,6 +2,7 @@ import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import * as path from "node:path";
 import { flagBool, flagString, parseArgs } from "../lib/args.js";
+import { defaultArtifactRootForRead } from "../lib/local-artifact-root.js";
 import { buildWorkflowLearningProjection, readWorkflowLearningSources } from "../lib/workflow-learning-projection.js";
 
 type Summary = {
@@ -24,7 +25,7 @@ function printHelp(): void {
   console.log("Build an inert Console learning projection from local workflow learning sidecars.");
   console.log("");
   console.log("Options:");
-  console.log("  --artifact-root <path>  Workflow artifact root to scan (default: .flow-agents)");
+  console.log("  --artifact-root <path>  Workflow artifact root to scan (default: .kontourai/flow-agents)");
   console.log("  --kontour-root <path>   Local Kontour root to write under (default: .kontour)");
   console.log("  --scope <id>            Projection scope id (default: current directory name)");
   console.log("  --scope-kind <kind>     Projection scope kind (default: repo)");
@@ -105,7 +106,7 @@ export function main(argv = process.argv.slice(2)): number {
   }
 
   try {
-    const artifactRoot = path.resolve(flagString(flags, "artifact-root", ".flow-agents") ?? ".flow-agents");
+    const artifactRoot = path.resolve(flagString(flags, "artifact-root") ?? defaultArtifactRootForRead());
     const kontourRoot = path.resolve(flagString(flags, "kontour-root", ".kontour") ?? ".kontour");
     const producer = requireSafeSegment(flagString(flags, "producer", "flow-agents-learning") ?? "flow-agents-learning", "--producer");
     const scope = {

package/src/cli/init.ts

@@ -10,6 +10,7 @@ import { parseArgs, flagBool, flagList, flagString } from "../lib/args.js";
 import { activateCodexLocal } from "../runtime-adapters.js";
 import { main as buildBundles } from "../tools/build-universal-bundles.js";
 import { root } from "../tools/common.js";
+import { defaultCodexHome, durableInstallRecordPath } from "../lib/local-artifact-root.js";
 
 type Runtime = "base" | "codex" | "claude-code" | "kiro" | "opencode" | "pi";
 type TelemetrySink = "local-files" | "local-kontour-console" | "kontour-hosted-console" | "user-hosted-console" | "kontour-cloud" | "hosted-kontour-console";
@@ -101,8 +102,8 @@ Options:
                           Honors FLOW_AGENTS_USER_CLAUDE_SETTINGS for test isolation.
                         opencode: merges opencode.json into ~/.config/opencode/opencode.json
                           (honors XDG_CONFIG_HOME; test isolation via FLOW_AGENTS_USER_OPENCODE_CONFIG).
-                        codex: runs install-codex-home.sh into ~/.flow-agents/codex
-                          (the isolated Codex HOME; hooks merged, not overwritten).
+                        codex: runs install-codex-home.sh into CODEX_HOME or ~/.codex
+                          (hooks merged, not overwritten).
                         pi: NOT_VERIFIED (no documented global dir); warns and falls back to workspace default.
   --telemetry-sink local-files|local-kontour-console|kontour-hosted-console|user-hosted-console
   --console-url URL
@@ -193,9 +194,8 @@ function globalDest(runtime: Runtime): string {
     return path.join(process.env["XDG_CONFIG_HOME"] ?? path.join(os.homedir(), ".config"), "opencode");
   }
   if (runtime === "codex") {
-    // codex --global routes to the isolated Codex HOME at ~/.flow-agents/codex.
-    // This is the same path used by install-codex-home.sh; --dest overrides it for sandbox testing.
-    return path.join(os.homedir(), ".flow-agents", "codex");
+    // codex --global routes to the standard Codex home. --dest remains an explicit override.
+    return defaultCodexHome();
   }
   if (runtime === "pi") {
     // pi has no documented global config dir.
@@ -286,6 +286,73 @@ function ensureBundle(runtime: Runtime): string {
   return bundle;
 }
 
+// The bundle's hook commands resolve the flow-agents scripts directory via
+// ${CLAUDE_PROJECT_DIR:-$(pwd)}. That is correct for a project-scoped install
+// (installBundle rsyncs scripts/ alongside .claude/, so CLAUDE_PROJECT_DIR ==
+// the install destination). It is NOT correct for a --global install: there
+// is no per-destination copy of scripts/, and CLAUDE_PROJECT_DIR varies with
+// whichever project happens to be open, so the hook resolves to a path that
+// exists in at most one project (and never for most sessions). Global
+// installs need an absolute, session-independent path instead.
+const GLOBAL_INSTALL_PROJECT_DIR_PREFIX = /root="\$\{CLAUDE_PROJECT_DIR:-\$\(pwd\)\}";\s*/g;
+const GLOBAL_INSTALL_PROJECT_DIR_VAR = /"\$root\//g;
+
+function rewriteCommandForGlobalInstall(command: string, sourceRoot: string): string {
+  return command
+    .replace(GLOBAL_INSTALL_PROJECT_DIR_PREFIX, "")
+    .replace(GLOBAL_INSTALL_PROJECT_DIR_VAR, `"${sourceRoot}/`);
+}
+
+/** Recursively rewrite every `command` string found under `value` in place. */
+function rewriteCommandsForGlobalInstall(value: unknown, sourceRoot: string): void {
+  if (Array.isArray(value)) {
+    for (const item of value) rewriteCommandsForGlobalInstall(item, sourceRoot);
+    return;
+  }
+  if (!value || typeof value !== "object") return;
+  const obj = value as Record<string, unknown>;
+  for (const key of Object.keys(obj)) {
+    if (key === "command" && typeof obj[key] === "string") {
+      obj[key] = rewriteCommandForGlobalInstall(obj[key] as string, sourceRoot);
+      continue;
+    }
+    rewriteCommandsForGlobalInstall(obj[key], sourceRoot);
+  }
+}
+
+/**
+ * Additively copy every file under srcDir into destDir, creating directories
+ * as needed and overwriting files whose content changed. Never deletes files
+ * in destDir that srcDir does not own — destDir may contain unrelated content
+ * (other kits, other tools) that this sync must not touch.
+ */
+function copyDirMerge(srcDir: string, destDir: string): { added: number; updated: number } {
+  let added = 0;
+  let updated = 0;
+  if (!fs.existsSync(srcDir)) return { added, updated };
+  for (const entry of fs.readdirSync(srcDir, { withFileTypes: true })) {
+    const srcPath = path.join(srcDir, entry.name);
+    const destPath = path.join(destDir, entry.name);
+    if (entry.isDirectory()) {
+      const nested = copyDirMerge(srcPath, destPath);
+      added += nested.added;
+      updated += nested.updated;
+      continue;
+    }
+    if (!entry.isFile()) continue;
+    const content = fs.readFileSync(srcPath);
+    if (fs.existsSync(destPath)) {
+      if (Buffer.compare(fs.readFileSync(destPath), content) === 0) continue;
+      updated += 1;
+    } else {
+      fs.mkdirSync(path.dirname(destPath), { recursive: true });
+      added += 1;
+    }
+    fs.writeFileSync(destPath, content);
+  }
+  return { added, updated };
+}
+
 function installBundle(bundle: string, options: InitOptions): number {
   const args = ["install.sh", options.dest];
   for (const sink of options.telemetrySinks) args.push("--telemetry-sink", sink);
@@ -345,10 +412,13 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       // targeting the global settings, so the collision they'd create is expected.
       if (!options.global) checkScopeCollision();
     }
-    // --global for claude-code: merge only into the global/user-level settings dir.
-    // This writes only the hook-wiring config (merge into ~/.claude/settings.json),
-    // not the full workspace bundle. The global settings dir is the claude config root,
-    // so the settings.json lives directly in dest (not dest/.claude/).
+    // --global for claude-code: merge hook-wiring into the global/user-level
+    // settings dir, plus additively sync skills/agents so a global install
+    // does not silently go stale as new Builder Kit skills ship. This does
+    // NOT rsync the full workspace bundle (no context/, powers/, prompts/,
+    // etc.) — only the parts a global Claude Code user-config needs. The
+    // global settings dir is the claude config root, so the settings.json
+    // lives directly in dest (not dest/.claude/).
     if (options.global && options.runtime === "claude-code") {
       const bundle = ensureBundle(options.runtime);
       // For --global, dest is ~/.claude/ (the global settings dir).
@@ -364,6 +434,10 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       // Remove permissive defaults (not appropriate for global user settings).
       delete managed["permissions"];
       delete managed["skipDangerousModePermissionPrompt"];
+      // See rewriteCommandsForGlobalInstall: bundle hook commands assume
+      // CLAUDE_PROJECT_DIR points at this package; a global install must not
+      // depend on which project is currently open, so pin to an absolute path.
+      rewriteCommandsForGlobalInstall(managed, root);
       fs.mkdirSync(options.dest, { recursive: true });
       const destSettingsPath = path.join(options.dest, "settings.json");
       const installMergePath = path.join(root, "scripts", "install-merge.js");
@@ -377,16 +451,21 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       const tmp = `${destSettingsPath}.tmp.${process.pid}`;
       fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
       fs.renameSync(tmp, destSettingsPath);
+      // Additive skills/agents sync: adds new files and updates changed ones,
+      // never deletes — dest may hold unrelated content from other kits/tools.
+      const skillsSync = copyDirMerge(path.join(bundle, ".claude", "skills"), path.join(options.dest, "skills"));
+      const agentsSync = copyDirMerge(path.join(bundle, ".claude", "agents"), path.join(options.dest, "agents"));
       // Write version stamp.
-      const installRecordDir = path.join(options.dest, ".flow-agents");
+      const recordPath = durableInstallRecordPath(options.dest);
+      const installRecordDir = path.dirname(recordPath);
       fs.mkdirSync(installRecordDir, { recursive: true });
       const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")) as Record<string, string>;
       const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "claude-code", global: true };
-      const recordPath = path.join(installRecordDir, "install.json");
       const recordTmp = `${recordPath}.tmp.${process.pid}`;
       fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
       fs.renameSync(recordTmp, recordPath);
       console.log(`Flow Agents global hooks merged for claude-code in ${options.dest}`);
+      console.log(`Synced skills (+${skillsSync.added} new, ~${skillsSync.updated} updated) and agents (+${agentsSync.added} new, ~${agentsSync.updated} updated) in ${options.dest}`);
       return 0;
     }
     // --global for opencode: merge FA opencode.json into the global opencode config dir.
@@ -416,11 +495,11 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
 `, "utf8");
       fs.renameSync(tmp, destConfigPath);
       // Write version stamp.
-      const installRecordDir = path.join(options.dest, ".flow-agents");
+      const recordPath = durableInstallRecordPath(options.dest);
+      const installRecordDir = path.dirname(recordPath);
       fs.mkdirSync(installRecordDir, { recursive: true });
       const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")) as Record<string, string>;
       const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "opencode", global: true };
-      const recordPath = path.join(installRecordDir, "install.json");
       const recordTmp = `${recordPath}.tmp.${process.pid}`;
       fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}
 `, "utf8");
@@ -428,9 +507,8 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       console.log(`Flow Agents global config merged for opencode in ${options.dest}`);
       return 0;
     }
-    // --global for codex: run install-codex-home.sh to install into the isolated Codex HOME.
-    // The codex --global path is ~/.flow-agents/codex (the isolated home IS codex's global).
-    // Pass through telemetry/console args and honor --dest override for sandbox testing.
+    // --global for codex: run install-codex-home.sh to install into the Codex home.
+    // Defaults to CODEX_HOME or ~/.codex. --dest remains an explicit override.
     if (options.global && options.runtime === "codex") {
       const codexHomeScript = path.join(root, "scripts", "install-codex-home.sh");
       if (!fs.existsSync(codexHomeScript)) {
@@ -448,7 +526,9 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
         console.error(`flow-agents init: unable to run install-codex-home.sh: ${result.error.message}`);
         return 1;
       }
-      return result.status ?? 1;
+      const installed = result.status ?? 1;
+      if (installed !== 0) return installed;
+      return activateKits(options);
     }
     // --global for pi: NOT_VERIFIED (no documented global dir). Warn and fall through to workspace install.
     if (options.global && options.runtime === "pi") {
@@ -534,11 +614,11 @@ function dogfoodClaudeCode(bundleRoot: string, dest: string): void {
   fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
   fs.renameSync(tmp, destSettingsPath);
   // Write version stamp.
-  const installRecordDir = path.join(dest, ".flow-agents");
+  const recordPath = durableInstallRecordPath(dest);
+  const installRecordDir = path.dirname(recordPath);
   fs.mkdirSync(installRecordDir, { recursive: true });
   const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")) as Record<string, string>;
   const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "claude-code" };
-  const recordPath = path.join(installRecordDir, "install.json");
   const recordTmp = `${recordPath}.tmp.${process.pid}`;
   fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
   fs.renameSync(recordTmp, recordPath);
@@ -572,11 +652,11 @@ function dogfoodCodex(bundleRoot: string, dest: string): void {
   fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
   fs.renameSync(tmp, destHooksPath);
   // Write version stamp.
-  const installRecordDir = path.join(dest, ".flow-agents");
+  const recordPath = durableInstallRecordPath(dest);
+  const installRecordDir = path.dirname(recordPath);
   fs.mkdirSync(installRecordDir, { recursive: true });
   const pkgJson = JSON.parse(fs.readFileSync(path.join(root, "package.json"), "utf8")) as Record<string, string>;
   const record = { version: pkgJson["version"] ?? "0.0.0", installedAt: new Date().toISOString(), runtime: "codex" };
-  const recordPath = path.join(installRecordDir, "install.json");
   const recordTmp = `${recordPath}.tmp.${process.pid}`;
   fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
   fs.renameSync(recordTmp, recordPath);

package/src/cli/kit.ts

@@ -6,14 +6,19 @@ import * as path from "node:path";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagBool, flagString } from "../lib/args.js";
 import { assertPathContained, copyDir, isoNow, readJson, walkFiles, writeJson } from "../lib/fs.js";
-import { assertKitRepository, deriveKitTargets } from "../flow-kit/validate.js";
+import { assertKitRepository, deriveKitTargets, parseKitDependencies } from "../flow-kit/validate.js";
 import { activateCodexLocal, activateStrandsLocal } from "../runtime-adapters.js";
+import { defaultCodexHome } from "../lib/local-artifact-root.js";
 
 const REGISTRY_REL = path.join("kits", "local", "installed-kits.json");
 const REPOSITORIES_REL = path.join("kits", "local", "repositories");
 
 function registryPath(dest: string): string { return path.join(dest, REGISTRY_REL); }
 function installedPath(dest: string, kitId: string): string { return path.join(dest, REPOSITORIES_REL, kitId); }
+function resolveDest(flags: ReturnType<typeof parseArgs>["flags"]): string {
+  const explicit = flagString(flags, "dest");
+  return path.resolve(explicit ?? defaultCodexHome());
+}
 
 function loadRegistry(dest: string): { schema_version: string; kits: Record<string, unknown>[] } {
   const file = registryPath(dest);
@@ -22,6 +27,28 @@ function loadRegistry(dest: string): { schema_version: string; kits: Record<stri
   return { schema_version: data.schema_version ?? "1.0", kits: Array.isArray(data.kits) ? data.kits.filter((item): item is Record<string, unknown> => typeof item === "object" && item !== null) : [] };
 }
 
+/**
+ * Emit a non-blocking warning for each declared kit dependency that is not present
+ * in the destination's LOCAL registry.
+ *
+ * Scope limitation (v1, accepted): this check only sees the local installed-kits
+ * registry at `dest`, NOT the built-in Kit Catalog. A dependency satisfied solely by
+ * a built-in catalog kit will still warn here. Presence is enforced authoritatively
+ * (hard error) at activation time against the full discovered inventory
+ * (built-in catalog + local registry) — see src/runtime-adapters.ts.
+ */
+function warnUninstalledDependencies(manifest: Record<string, unknown>, manifestPath: string, dest: string): void {
+  const { entries } = parseKitDependencies(manifest, manifestPath);
+  if (!entries.length) return;
+  const installed = new Set(loadRegistry(dest).kits.map((entry) => String(entry.id ?? "")));
+  const kitId = String(manifest.id);
+  for (const dep of entries) {
+    if (!installed.has(dep.kit_id)) {
+      console.log(`warning: kit '${kitId}' declares a dependency on '${dep.kit_id}'${dep.reason ? ` (${dep.reason})` : ""} which is not installed at ${dest}; install it first with 'flow-agents kit install <source>' or activation will fail`);
+    }
+  }
+}
+
 function contentHash(root: string): string {
   const hash = crypto.createHash("sha256");
   for (const file of walkFiles(root)) {
@@ -80,7 +107,7 @@ async function install(argv: string[]): Promise<number> {
 
 async function installLocalSource(source: string, argv: string[]): Promise<number> {
   const args = parseArgs(argv);
-  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  const dest = resolveDest(args.flags);
   let manifest: Record<string, unknown>;
   try {
     manifest = await assertKitRepository(source);
@@ -90,10 +117,12 @@ async function installLocalSource(source: string, argv: string[]): Promise<numbe
     return 1;
   }
   const kitId = String(manifest.id);
+  warnUninstalledDependencies(manifest, path.join(source, "kit.json"), dest);
   const hash = contentHash(source);
   const registry = loadRegistry(dest);
   const existing = registry.kits.find((entry) => entry.id === kitId);
   const target = installedPath(dest, kitId);
+  fs.mkdirSync(dest, { recursive: true });
   assertPathContained(dest, target);
   const sourceText = source;
   if (existing && existing.source !== sourceText && !flagBool(args.flags, "update")) {
@@ -133,7 +162,7 @@ async function installGitSource(rawUrl: string, argv: string[]): Promise<number>
   }
   if (!ref) ref = flagString(args.flags, "ref") ?? null;
 
-  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  const dest = resolveDest(args.flags);
   const force = flagBool(args.flags, "force") ?? false;
   const update = flagBool(args.flags, "update") ?? false;
 
@@ -167,10 +196,12 @@ async function installGitSource(rawUrl: string, argv: string[]): Promise<number>
 
     // Delegate to the shared install logic (copy + registry update).
     const kitId = String(manifest.id);
+    warnUninstalledDependencies(manifest, path.join(tmpBase, "kit.json"), dest);
     const hash = kitContentHash(tmpBase);
     const registry = loadRegistry(dest);
     const existing = registry.kits.find((entry) => entry.id === kitId);
     const target = installedPath(dest, kitId);
+    fs.mkdirSync(dest, { recursive: true });
     assertPathContained(dest, target);
     const sourceText = repoUrl + (ref ? `#${ref}` : "");
     if (existing && existing.source !== sourceText && !update) {
@@ -202,7 +233,7 @@ async function installGitSource(rawUrl: string, argv: string[]): Promise<number>
 
 function list(argv: string[]): number {
   const args = parseArgs(argv);
-  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  const dest = resolveDest(args.flags);
   const entries = loadRegistry(dest).kits;
   if (!entries.length) {
     console.log("No local Flow Kits installed.");
@@ -216,7 +247,7 @@ function list(argv: string[]): number {
 
 function status(argv: string[]): number {
   const args = parseArgs(argv);
-  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  const dest = resolveDest(args.flags);
   let entries = loadRegistry(dest).kits;
   const kitId = args.positionals[0];
   if (kitId) {
@@ -241,7 +272,7 @@ const AVAILABLE_ADAPTERS = ["codex-local", "strands-local"];
 
 function activate(argv: string[]): number {
   const args = parseArgs(argv);
-  const dest = path.resolve(flagString(args.flags, "dest", ".") ?? ".");
+  const dest = resolveDest(args.flags);
   const sourceRoot = path.resolve(flagString(args.flags, "source-root", path.resolve(path.dirname(process.argv[1]), "..")) ?? ".");
   const adapter = flagString(args.flags, "adapter");
   if (adapter && !AVAILABLE_ADAPTERS.includes(adapter)) {