@kontourai/flow-agents 2.3.0 → 3.0.0

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/effective-assignment-provider-settings.ts

@@ -0,0 +1,112 @@
+import * as child_process from "node:child_process";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs, flagString, flagBool } from "../lib/args.js";
+import { readJson } from "../lib/fs.js";
+
+// Mirrors src/cli/effective-backlog-settings.ts's loadSettings/currentRepo/merge/findProject/
+// effective structure and its ask_user/configured result envelope exactly, pointed at the
+// AssignmentProvider settings schema/example instead of the backlog equivalents (#290 Wave 2
+// Task B). Deliberately NOT extracted into a shared helper with effective-backlog-settings.ts —
+// see the #290 plan artifact's Unresolved Questions #3 for the recorded rationale (duplicating
+// this file's small merge/repo-detection logic is lower-risk than refactoring a file outside
+// this issue's declared scope).
+
+const PROJECT_SETTINGS_RELATIVE_PATH = path.join("context", "settings", "assignment-provider-settings.json");
+
+function loadSettings(file: string): Record<string, unknown> | null {
+  if (!fs.existsSync(file)) return null;
+  const data = readJson(file) as Record<string, unknown>;
+  if (data.schema_version !== "1.0") throw new Error(`${file}: unsupported schema_version ${String(data.schema_version)}`);
+  return data;
+}
+
+function repoFromText(text: string): { owner: string; name: string } | null {
+  const match = text.trim().match(/github\.com[:/]([^/]+)\/([^/.]+)(?:\.git)?$/);
+  return match ? { owner: match[1], name: match[2] } : null;
+}
+
+function currentRepo(repoPath: string): { owner: string; name: string } | null {
+  try {
+    const out = child_process.execFileSync("git", ["-C", repoPath, "remote", "get-url", "origin"], { encoding: "utf8", stdio: ["ignore", "pipe", "ignore"] });
+    const repo = repoFromText(out);
+    if (repo) return repo;
+  } catch {}
+  const packagePath = path.join(repoPath, "package.json");
+  if (fs.existsSync(packagePath)) {
+    const data = readJson(packagePath) as Record<string, unknown>;
+    const repository = data.repository;
+    const url = typeof repository === "object" && repository !== null ? (repository as Record<string, unknown>).url : repository;
+    if (typeof url === "string") return repoFromText(url);
+  }
+  return null;
+}
+
+function merge(base: unknown, override: unknown): Record<string, unknown> | null {
+  if (!base && !override) return null;
+  if (!base) return structuredClone(override) as Record<string, unknown>;
+  if (!override) return structuredClone(base) as Record<string, unknown>;
+  const out = structuredClone(base) as Record<string, unknown>;
+  for (const [key, value] of Object.entries(override as Record<string, unknown>)) {
+    out[key] = typeof value === "object" && value !== null && typeof out[key] === "object" && out[key] !== null && !Array.isArray(value)
+      ? merge(out[key], value)
+      : structuredClone(value);
+  }
+  return out;
+}
+
+function findProject(settings: Record<string, unknown> | null, repo: { owner: string; name: string }): Record<string, unknown> | null {
+  const projects = settings?.projects;
+  if (!Array.isArray(projects)) return null;
+  return (projects.find((project) => {
+    const projectRepo = (((project as Record<string, unknown>).project as Record<string, unknown> | undefined)?.repo ?? {}) as Record<string, unknown>;
+    return projectRepo.owner === repo.owner && projectRepo.name === repo.name;
+  }) as Record<string, unknown> | undefined) ?? null;
+}
+
+function defaultProjectSettingsPath(): string {
+  let cursor = path.dirname(fileURLToPath(import.meta.url));
+  while (true) {
+    const candidate = path.join(cursor, PROJECT_SETTINGS_RELATIVE_PATH);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(cursor);
+    if (parent === cursor) return path.resolve(PROJECT_SETTINGS_RELATIVE_PATH);
+    cursor = parent;
+  }
+}
+
+function effective(repoPath: string, projectSettings: string, globalSettings: string): [Record<string, unknown>, number] {
+  const repo = currentRepo(repoPath);
+  const projectDoc = loadSettings(projectSettings);
+  const globalDoc = loadSettings(globalSettings);
+  if (!repo) return [{ status: "ask_user", reason: "could_not_identify_current_repo", message: "Ask the user which assignment AssignmentProvider to use for this workspace.", resolution: { project_settings_path: projectSettings, global_settings_path: globalSettings } }, 2];
+  const effectiveSettings = merge(merge(merge(globalDoc?.defaults, findProject(globalDoc, repo)), projectDoc?.defaults), findProject(projectDoc, repo));
+  if (!effectiveSettings) return [{ status: "ask_user", reason: "no_assignment_provider_settings", message: "Ask the user which assignment AssignmentProvider to use before claiming work.", current_repo: repo, resolution: { project_settings_path: projectSettings, global_settings_path: globalSettings, checked: ["project", "global"] } }, 2];
+  return [{ status: "configured", current_repo: repo, source: findProject(projectDoc, repo) || projectDoc?.defaults ? "project" : "global", precedence: ["project.projects match", "project.defaults", "global.projects match", "global.defaults"], settings: effectiveSettings }, 0];
+}
+
+export function main(argv = process.argv.slice(2)): number {
+  const args = parseArgs(argv);
+  try {
+    const [result, code] = effective(
+      path.resolve(flagString(args.flags, "repo-path", ".") ?? "."),
+      path.resolve(flagString(args.flags, "project-settings", defaultProjectSettingsPath()) ?? ""),
+      path.resolve(flagString(args.flags, "global-settings", path.join(os.homedir(), ".config", "flow-agents", "assignment-provider-settings.json")) ?? ""),
+    );
+    if (flagBool(args.flags, "json")) console.log(JSON.stringify(result, null, 2));
+    else console.log(`status: ${String(result.status)}`);
+    return code;
+  } catch (error) {
+    console.error(`error: ${(error as Error).message}`);
+    return 1;
+  }
+}
+
+// Use process.exitCode (not process.exit) to allow stdout to be flushed before exit.
+// Resolve real paths to handle symlinks (e.g. /tmp -> /private/tmp on macOS) so the
+// entry-point guard fires correctly when the module is loaded directly as a script.
+const _selfRealPath = (() => { try { return fs.realpathSync(fileURLToPath(import.meta.url)); } catch { return fileURLToPath(import.meta.url); } })();
+const _argv1RealPath = (() => { try { return fs.realpathSync(process.argv[1]); } catch { return process.argv[1]; } })();
+if (_selfRealPath === _argv1RealPath) { process.exitCode = main(); }

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)) {

package/src/cli/public-api.test.mjs

@@ -1,21 +1,73 @@
 import test from "node:test";
 import assert from "node:assert/strict";
+import fs from "node:fs";
+import os from "node:os";
 import path from "node:path";
+import { createRequire } from "node:module";
 
 import {
   defaultArtifactRootForRead,
+  defaultCodexHome,
+  durableFlowAgentsRoot,
+  durableInstallRecordPath,
+  DURABLE_FLOW_AGENTS_DIR,
+  FLOW_AGENTS_RUNTIME_DIR,
+  FLOW_AGENTS_RUNTIME_SUBDIR,
   flowAgentsArtifactRoot,
   KONTOURAI_DIR,
-  legacyFlowAgentsArtifactRoot,
-  LEGACY_FLOW_AGENTS_DIR,
 } from "../../build/src/index.js";
 
 test("public API exports local artifact root helpers", () => {
   const cwd = path.resolve("/tmp/flow-agents-public-api");
 
   assert.equal(KONTOURAI_DIR, ".kontourai");
-  assert.equal(LEGACY_FLOW_AGENTS_DIR, ".flow-agents");
-  assert.equal(flowAgentsArtifactRoot(cwd), path.join(cwd, ".kontourai", "flow-agents"));
-  assert.equal(legacyFlowAgentsArtifactRoot(cwd), path.join(cwd, ".flow-agents"));
-  assert.equal(defaultArtifactRootForRead(cwd), path.join(cwd, ".kontourai", "flow-agents"));
+  assert.equal(FLOW_AGENTS_RUNTIME_SUBDIR, "flow-agents");
+  assert.equal(FLOW_AGENTS_RUNTIME_DIR, path.join(".kontourai", "flow-agents"));
+  assert.equal(DURABLE_FLOW_AGENTS_DIR, ".flow-agents");
+  assert.equal(flowAgentsArtifactRoot(cwd), path.join(cwd, FLOW_AGENTS_RUNTIME_DIR));
+  assert.equal(durableFlowAgentsRoot(cwd), path.join(cwd, ".flow-agents"));
+  assert.equal(durableInstallRecordPath(cwd), path.join(cwd, ".flow-agents", "install.json"));
+  assert.equal(defaultArtifactRootForRead(cwd), path.join(cwd, FLOW_AGENTS_RUNTIME_DIR));
+  assert.notEqual(defaultArtifactRootForRead(cwd), durableFlowAgentsRoot(cwd));
+});
+
+test("TS and CJS artifact helpers stay in parity without durable-root fallback", () => {
+  const require = createRequire(import.meta.url);
+  const cjs = require("../../scripts/hooks/lib/local-artifact-paths.js");
+  const cwd = fs.mkdtempSync(path.join(os.tmpdir(), "flow-agents-paths-"));
+
+  fs.mkdirSync(path.join(cwd, DURABLE_FLOW_AGENTS_DIR, "previous-session"), { recursive: true });
+  fs.writeFileSync(path.join(cwd, DURABLE_FLOW_AGENTS_DIR, "current.json"), "{}\n");
+
+  assert.equal(cjs.KONTOURAI_DIR, KONTOURAI_DIR);
+  assert.equal(cjs.FLOW_AGENTS_RUNTIME_SUBDIR, FLOW_AGENTS_RUNTIME_SUBDIR);
+  assert.equal(cjs.FLOW_AGENTS_RUNTIME_DIR, FLOW_AGENTS_RUNTIME_DIR);
+  assert.equal(cjs.DURABLE_FLOW_AGENTS_DIR, DURABLE_FLOW_AGENTS_DIR);
+
+  assert.equal(cjs.flowAgentsArtifactRoot(cwd), flowAgentsArtifactRoot(cwd));
+  assert.equal(cjs.defaultArtifactRootForRead(cwd), defaultArtifactRootForRead(cwd));
+  assert.equal(cjs.durableFlowAgentsRoot(cwd), durableFlowAgentsRoot(cwd));
+  assert.deepEqual(cjs.flowAgentsArtifactRootsForRead(cwd), []);
+});
+
+test("defaultCodexHome honors CODEX_HOME env override", () => {
+  const previous = process.env["CODEX_HOME"];
+  try {
+    process.env["CODEX_HOME"] = "/custom/codex-home";
+    assert.equal(defaultCodexHome(), "/custom/codex-home");
+  } finally {
+    if (previous === undefined) delete process.env["CODEX_HOME"];
+    else process.env["CODEX_HOME"] = previous;
+  }
+});
+
+test("defaultCodexHome falls back to ~/.codex when CODEX_HOME is unset", () => {
+  const previous = process.env["CODEX_HOME"];
+  try {
+    delete process.env["CODEX_HOME"];
+    assert.equal(defaultCodexHome(), path.join(os.homedir(), ".codex"));
+  } finally {
+    if (previous === undefined) delete process.env["CODEX_HOME"];
+    else process.env["CODEX_HOME"] = previous;
+  }
 });

package/src/cli/pull-work-provider.ts

@@ -2,7 +2,7 @@ import * as fs from "node:fs";
 import { fileURLToPath } from "node:url";
 import { parseArgs, flagList, flagString } from "../lib/args.js";
 
-const FLOW_ARTIFACT_PATTERN = /(?<path>\.flow-agents\/[^\s`'")]+)/g;
+const FLOW_ARTIFACT_PATTERN = /(?<path>\.kontourai\/flow-agents\/[^\s`'")]+)/g;
 const GITHUB_ISSUE_PATTERN = /(?:(?<owner>[A-Za-z0-9_.-]+)\/(?<repo>[A-Za-z0-9_.-]+))?#(?<number>\d+)/g;
 const GITHUB_URL_PATTERN = /https:\/\/github\.com\/(?<owner>[^/\s]+)\/(?<repo>[^/\s]+)\/(?:issues|pull)\/(?<number>\d+)/g;
 const BLOCKER_PATTERN = /\b(?:blocked by|depends on|waiting on|requires|should follow|coordinate with)\b[:\s-]*(?<refs>[^\n]+)/gi;