@kontourai/flow-agents 3.3.0 → 3.4.1

package/src/lib/fs.ts

@@ -1,5 +1,6 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
+import * as crypto from "node:crypto";
 
 export function readJson(file: string): unknown {
   return JSON.parse(fs.readFileSync(file, "utf8"));
@@ -10,6 +11,118 @@ export function writeJson(file: string, value: unknown): void {
   fs.writeFileSync(file, `${JSON.stringify(value, null, 2)}\n`, "utf8");
 }
 
+function existingAncestor(file: string): { ancestor: string; missing: string[] } {
+  let current = path.resolve(file);
+  const missing: string[] = [];
+  while (!fs.existsSync(current)) {
+    missing.unshift(path.basename(current));
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return { ancestor: current, missing };
+}
+
+/** Resolve a possibly-missing path through its nearest existing ancestor. */
+export function canonicalProspectivePath(file: string): string {
+  const { ancestor, missing } = existingAncestor(file);
+  return path.resolve(fs.realpathSync(ancestor), ...missing);
+}
+
+function isContained(root: string, target: string): boolean {
+  const relative = path.relative(root, target);
+  return relative === "" || (!relative.startsWith("..") && !path.isAbsolute(relative));
+}
+
+/** Reject equality and either-direction containment after canonical resolution. */
+export function assertPathsDisjoint(first: string, second: string): void {
+  const firstReal = canonicalProspectivePath(first);
+  const secondReal = canonicalProspectivePath(second);
+  if (isContained(firstReal, secondReal) || isContained(secondReal, firstReal)) {
+    throw new Error(`refusing overlapping paths: ${firstReal} and ${secondReal}`);
+  }
+}
+
+/**
+ * Create a directory below root without following any symlink that already
+ * exists at or below the root. Ambient aliases above root (for example macOS
+ * /tmp -> /private/tmp) are resolved once and are not treated as destination
+ * components.
+ */
+export function ensureSafeDirectory(root: string, directory: string): string {
+  const rootPath = path.resolve(root);
+  if (fs.existsSync(rootPath)) {
+    const rootStat = fs.lstatSync(rootPath);
+    if (rootStat.isSymbolicLink()) throw new Error(`refusing symlink destination root: ${rootPath}`);
+    if (!rootStat.isDirectory()) throw new Error(`destination root is not a directory: ${rootPath}`);
+  } else {
+    const { ancestor, missing } = existingAncestor(rootPath);
+    let current = fs.realpathSync(ancestor);
+    for (const part of missing) {
+      current = path.join(current, part);
+      if (fs.existsSync(current)) {
+        const stat = fs.lstatSync(current);
+        if (stat.isSymbolicLink()) throw new Error(`refusing to write through symlink: ${current}`);
+        if (!stat.isDirectory()) throw new Error(`destination component is not a directory: ${current}`);
+      } else {
+        fs.mkdirSync(current);
+      }
+    }
+  }
+
+  const rootReal = fs.realpathSync(rootPath);
+  const target = path.resolve(directory);
+  const prospective = canonicalProspectivePath(target);
+  if (!isContained(rootReal, prospective)) throw new Error(`path escapes root: ${target}`);
+  const relative = path.relative(rootReal, prospective);
+  let current = rootReal;
+  for (const part of relative.split(path.sep).filter(Boolean)) {
+    current = path.join(current, part);
+    if (fs.existsSync(current)) {
+      const stat = fs.lstatSync(current);
+      if (stat.isSymbolicLink()) throw new Error(`refusing to write through symlink: ${current}`);
+      if (!stat.isDirectory()) throw new Error(`destination component is not a directory: ${current}`);
+    } else {
+      fs.mkdirSync(current);
+    }
+  }
+  return prospective;
+}
+
+function assertSafeFileTarget(root: string, file: string): string {
+  const target = path.resolve(file);
+  ensureSafeDirectory(root, path.dirname(target));
+  const rootReal = fs.realpathSync(path.resolve(root));
+  const prospective = canonicalProspectivePath(target);
+  if (!isContained(rootReal, prospective) || prospective === rootReal) throw new Error(`path escapes root: ${target}`);
+  if (fs.existsSync(target)) {
+    const stat = fs.lstatSync(target);
+    if (stat.isSymbolicLink()) throw new Error(`refusing to replace symlink: ${target}`);
+    if (!stat.isFile()) throw new Error(`destination is not a regular file: ${target}`);
+  }
+  return target;
+}
+
+/** Atomically replace a regular file without following a final-component symlink. */
+export function atomicWriteFile(root: string, file: string, data: string | Buffer): void {
+  const target = assertSafeFileTarget(root, file);
+  const temp = path.join(path.dirname(target), `.${path.basename(target)}.flow-agents-${process.pid}-${crypto.randomBytes(6).toString("hex")}.tmp`);
+  try {
+    fs.writeFileSync(temp, data, { flag: "wx" });
+    fs.renameSync(temp, target);
+  } finally {
+    fs.rmSync(temp, { force: true });
+  }
+}
+
+export function atomicWriteJson(root: string, file: string, value: unknown): void {
+  atomicWriteFile(root, file, `${JSON.stringify(value, null, 2)}\n`);
+}
+
+export function atomicCopyFile(root: string, source: string, target: string): void {
+  atomicWriteFile(root, target, fs.readFileSync(source));
+}
+
 export function copyDir(src: string, dest: string): void {
   fs.mkdirSync(path.dirname(dest), { recursive: true });
   if (fs.existsSync(dest)) fs.rmSync(dest, { recursive: true, force: true });
@@ -19,6 +132,53 @@ export function copyDir(src: string, dest: string): void {
   });
 }
 
+function copiedTreeDigest(root: string): string {
+  const hash = crypto.createHash("sha256");
+  for (const file of walkFiles(root)) {
+    const rel = path.relative(root, file).split(path.sep).join("/");
+    if (rel.split("/").some((part) => [".git", "__pycache__", ".pytest_cache"].includes(part))) continue;
+    hash.update(rel);
+    hash.update("\0");
+    hash.update(fs.readFileSync(file));
+    hash.update("\0");
+  }
+  return hash.digest("hex");
+}
+
+/** Copy through a verified sibling directory, then swap with rollback. */
+export function copyDirAtomic(root: string, src: string, dest: string): void {
+  assertPathsDisjoint(src, dest);
+  const parent = ensureSafeDirectory(root, path.dirname(dest));
+  if (fs.existsSync(dest)) {
+    const stat = fs.lstatSync(dest);
+    if (stat.isSymbolicLink()) throw new Error(`refusing to replace symlink: ${dest}`);
+    if (!stat.isDirectory()) throw new Error(`destination is not a directory: ${dest}`);
+  }
+  const nonce = `${process.pid}-${crypto.randomBytes(6).toString("hex")}`;
+  const temp = path.join(parent, `.${path.basename(dest)}.flow-agents-${nonce}.tmp`);
+  const backup = path.join(parent, `.${path.basename(dest)}.flow-agents-${nonce}.old`);
+  try {
+    fs.cpSync(src, temp, {
+      recursive: true,
+      errorOnExist: true,
+      force: false,
+      filter: (source) => !source.split(path.sep).some((part) => [".git", "__pycache__", ".pytest_cache"].includes(part)),
+    });
+    if (copiedTreeDigest(src) !== copiedTreeDigest(temp)) throw new Error(`copied kit verification failed: ${src}`);
+    if (fs.existsSync(dest)) fs.renameSync(dest, backup);
+    try {
+      fs.renameSync(temp, dest);
+    } catch (error) {
+      if (fs.existsSync(backup)) fs.renameSync(backup, dest);
+      throw error;
+    }
+    fs.rmSync(backup, { recursive: true, force: true });
+  } finally {
+    fs.rmSync(temp, { recursive: true, force: true });
+    if (fs.existsSync(backup) && !fs.existsSync(dest)) fs.renameSync(backup, dest);
+  }
+}
+
 export function assertPathContained(root: string, target: string): void {
   const rootReal = fs.realpathSync(root);
   let existingParent = path.dirname(target);

package/src/lib/local-artifact-root.ts

@@ -1,6 +1,7 @@
 import * as fs from "node:fs";
 import * as os from "node:os";
 import * as path from "node:path";
+import { execFileSync } from "node:child_process";
 
 export const KONTOURAI_DIR = ".kontourai";
 export const FLOW_AGENTS_RUNTIME_SUBDIR = "flow-agents";
@@ -16,12 +17,132 @@ export const LEGACY_TELEMETRY_DIR = ".telemetry";
  * and the durable per-destination install record root
  * (`DURABLE_FLOW_AGENTS_DIR`, i.e. `.flow-agents`).
  */
-export function defaultCodexHome(): string {
-  return process.env["CODEX_HOME"] || path.join(os.homedir(), ".codex");
+export function defaultCodexHome(env: NodeJS.ProcessEnv = process.env, homedir: string = os.homedir()): string {
+  return env["CODEX_HOME"] || path.join(homedir, ".codex");
 }
 
+/**
+ * #357: resolve the SHARED, git-common-dir-anchored `.kontourai/flow-agents` root for `cwd`.
+ *
+ * `git rev-parse --git-common-dir` returns the ONE `.git` directory shared by every worktree
+ * of a repository (in the primary checkout this is simply `.git` relative to cwd; in a linked
+ * worktree it resolves to the primary checkout's real `.git` directory, e.g.
+ * `/path/to/primary/.git`, NOT the worktree's own `.git` file). Taking `path.dirname()` of that
+ * resolved, absolute path yields the primary checkout's repo root — the one location every
+ * worktree of the same repo should treat as the shared `.kontourai/flow-agents` store, so a
+ * `liveness claim` or `ensure-session` invoked from ANY worktree's cwd is visible to a reader
+ * in any other checkout of the same repo (including the primary one).
+ *
+ * Returns null (never throws) when git is unavailable, `cwd` is not inside a git working tree,
+ * or the command otherwise fails — callers MUST fail open to the existing cwd-based
+ * `path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR)` behavior in that case (see flowAgentsArtifactRoot
+ * below), which is also exactly what happens today in the single-checkout case: there,
+ * `--git-common-dir` resolves to `.git` under cwd itself, so `path.dirname()` of its absolute
+ * form is cwd — byte-identical to today's plain `path.resolve(cwd, ...)` result.
+ *
+ * #413 iteration-2 Fix 3: strips the ambient GIT_DIR/GIT_COMMON_DIR/GIT_WORK_TREE/
+ * GIT_CEILING_DIRECTORIES env vars before shelling out. Any of these, if set in the calling
+ * process's environment (e.g. leaked from an outer `git rebase`/hook invocation, or a stray
+ * export in a dev shell), can silently redirect `--git-common-dir` to resolve a DIFFERENT
+ * repository's `.git` than the one `cwd` is actually inside — which would silently redirect
+ * the shared `.kontourai/flow-agents` store to that other repo. Passing an explicit env with
+ * those keys deleted makes resolution depend only on `cwd`, never on ambient process state.
+ */
+export function resolveSharedRepoRoot(cwd: string): string | null {
+  try {
+    const env = { ...process.env };
+    delete env["GIT_DIR"];
+    delete env["GIT_COMMON_DIR"];
+    delete env["GIT_WORK_TREE"];
+    delete env["GIT_CEILING_DIRECTORIES"];
+    const out = execFileSync("git", ["rev-parse", "--git-common-dir"], {
+      cwd,
+      env,
+      encoding: "utf8",
+      stdio: ["ignore", "pipe", "ignore"],
+    }).trim();
+    if (!out) return null;
+    const absoluteCommonDir = path.resolve(cwd, out);
+    return path.dirname(absoluteCommonDir);
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * #413 iteration-2 Fix 1: cheap discriminator for the loud-vs-silent fail-open decision below.
+ * Walks up from `cwd` (bounded, same 40-level cap the hook-side ancestor walks use) looking for
+ * a `.git` entry — a FILE (linked worktree's gitdir pointer) or a DIRECTORY (primary checkout) —
+ * without shelling out to git at all, so it stays meaningful even when git itself is the thing
+ * that's broken/absent. Never throws; a filesystem error at any level is treated as "no .git
+ * found here", not as a crash.
+ */
+function isInsideGitWorkingTree(cwd: string): boolean {
+  try {
+    let dir = path.resolve(cwd);
+    const root = path.parse(dir).root;
+    for (let depth = 0; depth < 40; depth++) {
+      if (fs.existsSync(path.join(dir, ".git"))) return true;
+      if (dir === root) break;
+      const parent = path.dirname(dir);
+      if (parent === dir) break;
+      dir = parent;
+    }
+    return false;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * #413 iteration-2 Fix 1 (HIGH, security): emit a LOUD stderr warning before falling open, but
+ * ONLY when `cwd` is genuinely inside a git working tree (per isInsideGitWorkingTree above) AND
+ * resolveSharedRepoRoot still returned null — i.e. git resolution was ATTEMPTED and FAILED, not
+ * merely "there was no git repo to resolve in the first place". That second, benign case (a
+ * scratch dir, a non-git cwd) must stay perfectly silent — this is exactly what
+ * evals/integration/test_liveness_worktree_root.sh's AC6 companion case (no git at all) already
+ * asserts, and it must remain byte-identical to today.
+ *
+ * The loud case (corrupted gitlink, bad GIT_DIR-in-cwd's-own-config, git binary missing, a
+ * permissions error on .git, etc.) is #357's exact silent-fail-open bug: an actor's
+ * liveness/ownership claim lands in an ISOLATED cwd-local store invisible to every other
+ * worktree/checkout of the same repo, with no diagnostic at all. A warning (not a hard refuse —
+ * this helper sits on read paths too, and a degraded read must still return something usable)
+ * gives an operator the signal needed to pass `--artifact-root` explicitly instead of silently
+ * losing coordination visibility.
+ */
+function warnIfFailingOpenInsideGitTree(cwd: string, fallbackPath: string): void {
+  if (!isInsideGitWorkingTree(cwd)) return;
+  process.stderr.write(
+    `[artifact-root] WARNING: inside a git working tree but could not resolve the shared repo root ` +
+      `(git rev-parse --git-common-dir failed or returned nothing from ${cwd}); falling back to a ` +
+      `cwd-local store at ${fallbackPath} — coordination claims may be invisible to other ` +
+      `worktrees/actors. Pass --artifact-root explicitly to fix.\n`
+  );
+}
+
+/**
+ * #413 iteration-2 Fix 2 (documentation only, no behavior change): when `cwd` is a
+ * SUBDIRECTORY of a plain (non-worktree) checkout, `git rev-parse --git-common-dir` returns a
+ * RELATIVE path (e.g. `../.git` or deeper) that `resolveSharedRepoRoot` walks up to the repo
+ * root — so this intentionally resolves to `<repo-root>/.kontourai/flow-agents` regardless of
+ * which subdirectory `cwd` is, NOT `<subdir>/.kontourai/flow-agents` (the old plain
+ * `path.resolve(cwd, ...)` cwd-anchored behavior). This is the CORRECT shared-store semantics —
+ * one store per repo, matching every other cwd (primary checkout, linked worktree) this
+ * resolver already unifies — not a regression to guard against. See
+ * evals/integration/test_liveness_worktree_root.sh's AC6b for the explicit assertion, and its
+ * header docstring for why AC6's "byte-identical" guarantee is scoped to repo-root cwd and
+ * non-git cwd only, never to an arbitrary subdirectory cwd.
+ */
 export function flowAgentsArtifactRoot(cwd = process.cwd()): string {
-  return path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR);
+  const sharedRepoRoot = resolveSharedRepoRoot(cwd);
+  if (sharedRepoRoot) return path.resolve(sharedRepoRoot, FLOW_AGENTS_RUNTIME_DIR);
+  // Fail-open: not a git repo, git unavailable, or command failed — reproduce today's plain
+  // cwd-based behavior unchanged (AC6 backward-compat guarantee). #413 iteration-2 Fix 1: loud,
+  // not silent, when cwd IS inside a git working tree (see warnIfFailingOpenInsideGitTree).
+  const fallback = path.resolve(cwd, FLOW_AGENTS_RUNTIME_DIR);
+  warnIfFailingOpenInsideGitTree(cwd, fallback);
+  return fallback;
 }
 
 export function durableFlowAgentsRoot(cwd = process.cwd()): string {
@@ -32,6 +153,11 @@ export function durableInstallRecordPath(cwd = process.cwd()): string {
   return path.join(durableFlowAgentsRoot(cwd), "install.json");
 }
 
+/** Path to the per-skill-file content-hash drift manifest, a sibling of `install.json` under the same durable root. */
+export function skillsManifestPath(cwd = process.cwd()): string {
+  return path.join(durableFlowAgentsRoot(cwd), "skills-manifest.json");
+}
+
 export function telemetryDataDir(cwd = process.cwd()): string {
   return path.resolve(cwd, KONTOURAI_DIR, "telemetry");
 }

package/src/runtime-adapters.ts

@@ -1,8 +1,8 @@
 import * as fs from "node:fs";
 import * as path from "node:path";
-import { readJson, relPath, writeJson } from "./lib/fs.js";
+import { atomicCopyFile, atomicWriteJson, ensureSafeDirectory, readJson, relPath } from "./lib/fs.js";
 import { flowAgentsArtifactRoot } from "./lib/local-artifact-root.js";
-import { parseKitDependencies } from "./flow-kit/validate.js";
+import { parseKitDependencies, parseKitHookInfluenceExpectations, parseKitWorkflowTriggers } from "./flow-kit/validate.js";
 
 export type KitAsset = {
   kit_id: string;
@@ -15,15 +15,52 @@ export type KitAsset = {
   description?: string;
 };
 
-export type KitInventory = { assets: KitAsset[]; warnings: string[]; errors: string[] };
+export type KitWorkflowTriggerRef = {
+  kit_id: string;
+  source_kind: string;
+  id: string;
+  when: string;
+  target_flow_id?: string;
+  default_skill?: string;
+  conditional_skills?: { when: string; skill: string }[];
+  required_sequence?: string[];
+  post_verify_targets?: string[];
+};
+export type KitHookInfluenceExpectationRef = {
+  kit_id: string;
+  source_kind: string;
+  id: string;
+  description: string;
+  tier: string;
+  hook?: string;
+  event?: string;
+  must_include_guidance: string[];
+  must_include_actions: string[];
+};
+
+export type KitInventory = {
+  assets: KitAsset[];
+  dependencies: KitDependencyRef[];
+  workflow_triggers: KitWorkflowTriggerRef[];
+  hook_influence_expectations: KitHookInfluenceExpectationRef[];
+  warnings: string[];
+  errors: string[];
+};
 
 /** A cross-kit dependency edge discovered while loading a kit manifest. */
 export type KitDependencyRef = { from_kit_id: string; kit_id: string; reason?: string };
 
 /** The parsed result of a single kit manifest: its id, activatable assets, and declared dependencies. */
-export type LoadedKit = { kit_id: string; assets: KitAsset[]; dependencies: KitDependencyRef[] };
+export type LoadedKit = {
+  kit_id: string;
+  assets: KitAsset[];
+  dependencies: KitDependencyRef[];
+  workflow_triggers: KitWorkflowTriggerRef[];
+  hook_influence_expectations: KitHookInfluenceExpectationRef[];
+};
 
 const ASSET_CLASSES = ["flows", "skills", "docs", "adapters", "evals", "assets"];
+const KIT_ID_RE = /^[a-z][a-z0-9-]*$/;
 
 function assetPath(root: string, value: string): string | null {
   if (path.isAbsolute(value)) return null;
@@ -36,20 +73,20 @@ function loadKitAssets(kitRoot: string, sourceKind: string, warnings: string[],
   const manifestPath = path.join(kitRoot, "kit.json");
   if (!fs.existsSync(manifestPath)) {
     errors.push(`${kitRoot}: missing kit.json`);
-    return { kit_id: "", assets: [], dependencies: [] };
+    return { kit_id: "", assets: [], dependencies: [], workflow_triggers: [], hook_influence_expectations: [] };
   }
   let manifest: Record<string, unknown>;
   try {
     manifest = readJson(manifestPath) as Record<string, unknown>;
   } catch (error) {
     errors.push(`${manifestPath}: ${(error as Error).message}`);
-    return { kit_id: "", assets: [], dependencies: [] };
+    return { kit_id: "", assets: [], dependencies: [], workflow_triggers: [], hook_influence_expectations: [] };
   }
   const kitId = typeof manifest.id === "string" ? manifest.id : "";
   const kitName = typeof manifest.name === "string" ? manifest.name : kitId;
-  if (!kitId) {
-    errors.push(`${manifestPath}: missing kit id`);
-    return { kit_id: "", assets: [], dependencies: [] };
+  if (!KIT_ID_RE.test(kitId)) {
+    errors.push(`${manifestPath}: kit id must be a kebab-case id (^[a-z][a-z0-9-]*$)`);
+    return { kit_id: "", assets: [], dependencies: [], workflow_triggers: [], hook_influence_expectations: [] };
   }
   const assets: KitAsset[] = [];
   for (const assetClass of ASSET_CLASSES) {
@@ -90,17 +127,55 @@ function loadKitAssets(kitRoot: string, sourceKind: string, warnings: string[],
   // docs/adr/0019-kit-dependency-ownership.md). Shape errors surface at
   // install/inspect/validate time via validateKitRepository; here we only collect
   // the edges so activation can enforce presence against the full inventory.
-  const dependencies: KitDependencyRef[] = parseKitDependencies(manifest, manifestPath).entries
+  const dependencyResult = parseKitDependencies(manifest, manifestPath);
+  if (dependencyResult.errors.length) {
+    errors.push(...dependencyResult.errors);
+    warnings.push(`${kitId}: invalid dependencies metadata; skipping dependencies`);
+  }
+  const dependencies: KitDependencyRef[] = dependencyResult.errors.length ? [] : dependencyResult.entries
     .map((dep) => ({ from_kit_id: kitId, kit_id: dep.kit_id, ...(dep.reason ? { reason: dep.reason } : {}) }));
-  return { kit_id: kitId, assets, dependencies };
+  const workflowTriggerResult = parseKitWorkflowTriggers(manifest, manifestPath);
+  if (workflowTriggerResult.errors.length) {
+    errors.push(...workflowTriggerResult.errors);
+    warnings.push(`${kitId}: invalid workflow_triggers metadata; skipping workflow_triggers`);
+  }
+  const workflow_triggers: KitWorkflowTriggerRef[] = workflowTriggerResult.errors.length ? [] : workflowTriggerResult.entries
+    .map((trigger) => ({ kit_id: kitId, source_kind: sourceKind, ...trigger }));
+  const hookInfluenceResult = parseKitHookInfluenceExpectations(manifest, manifestPath);
+  if (hookInfluenceResult.errors.length) {
+    errors.push(...hookInfluenceResult.errors);
+    warnings.push(`${kitId}: invalid hook_influence_expectations metadata; skipping hook_influence_expectations`);
+  }
+  const hook_influence_expectations: KitHookInfluenceExpectationRef[] = hookInfluenceResult.errors.length ? [] : hookInfluenceResult.entries
+    .map((expectation) => ({ kit_id: kitId, source_kind: sourceKind, ...expectation }));
+  return { kit_id: kitId, assets, dependencies, workflow_triggers, hook_influence_expectations };
 }
 
-export function readKitInventory(sourceRoot: string, dest: string): KitInventory {
+function expandKitIdFilter(requested: Set<string> | undefined, dependencies: KitDependencyRef[], presentKitIds: Set<string>): Set<string> | undefined {
+  if (!requested) return undefined;
+  const selected = new Set(requested);
+  let changed = true;
+  while (changed) {
+    changed = false;
+    for (const dep of dependencies) {
+      if (!selected.has(dep.from_kit_id) || selected.has(dep.kit_id) || !presentKitIds.has(dep.kit_id)) continue;
+      selected.add(dep.kit_id);
+      changed = true;
+    }
+  }
+  return selected;
+}
+
+export function readKitInventory(sourceRoot: string, dest: string, options: { kitIdFilter?: string[] } = {}): KitInventory {
   const warnings: string[] = [];
   const errors: string[] = [];
   const assets: KitAsset[] = [];
   const dependencies: KitDependencyRef[] = [];
+  const workflow_triggers: KitWorkflowTriggerRef[] = [];
+  const hook_influence_expectations: KitHookInfluenceExpectationRef[] = [];
+  const loadedKits: LoadedKit[] = [];
   const presentKitIds = new Set<string>();
+  const kitIdFilter = options.kitIdFilter ? new Set(options.kitIdFilter) : undefined;
   const catalogPath = path.join(sourceRoot, "kits", "catalog.json");
   if (!fs.existsSync(catalogPath)) warnings.push(`${catalogPath}: built-in Kit Catalog not found; skipping built-in kits (this is normal when running outside a flow-agents checkout)`);
   else {
@@ -117,8 +192,7 @@ export function readKitInventory(sourceRoot: string, dest: string): KitInventory
         if (!kitRoot || !fs.existsSync(kitRoot)) warnings.push(`${catalogPath}: kits[${index}].path unavailable: ${rel}`);
         else {
           const loaded = loadKitAssets(kitRoot, "builtin", warnings, errors);
-          assets.push(...loaded.assets);
-          dependencies.push(...loaded.dependencies);
+          loadedKits.push(loaded);
           if (loaded.kit_id) presentKitIds.add(loaded.kit_id);
         }
       });
@@ -138,13 +212,21 @@ export function readKitInventory(sourceRoot: string, dest: string): KitInventory
         if (!fs.existsSync(kitRoot)) warnings.push(`${id}: installed kit copy missing at ${kitRoot}; skipping`);
         else {
           const loaded = loadKitAssets(kitRoot, "local", warnings, errors);
-          assets.push(...loaded.assets);
-          dependencies.push(...loaded.dependencies);
+          loadedKits.push(loaded);
           if (loaded.kit_id) presentKitIds.add(loaded.kit_id);
         }
       });
     }
   }
+  const allDependencies = loadedKits.flatMap((kit) => kit.dependencies);
+  const selectedKitIds = expandKitIdFilter(kitIdFilter, allDependencies, presentKitIds);
+  for (const loaded of loadedKits) {
+    if (selectedKitIds && !selectedKitIds.has(loaded.kit_id)) continue;
+    assets.push(...loaded.assets);
+    dependencies.push(...loaded.dependencies);
+    workflow_triggers.push(...loaded.workflow_triggers);
+    hook_influence_expectations.push(...loaded.hook_influence_expectations);
+  }
   // Activation-time cross-kit dependency enforcement: any declared dependency whose
   // kit_id is not present among the union of built-in catalog kits and locally-installed
   // kits is a hard error (feeds the errors[] -> activation-manifest -> non-zero exit path).
@@ -153,7 +235,7 @@ export function readKitInventory(sourceRoot: string, dest: string): KitInventory
       errors.push(`${dep.from_kit_id}: declares a dependency on kit '${dep.kit_id}'${dep.reason ? ` (${dep.reason})` : ""} which is not installed or activated. Install it with 'flow-agents kit install <source>' and re-activate, or remove the dependency declaration if it is no longer needed.`);
     }
   }
-  return { assets, warnings, errors };
+  return { assets, dependencies, workflow_triggers, hook_influence_expectations, warnings, errors };
 }
 
 function safeSegment(value: string): string {
@@ -166,9 +248,11 @@ function safeSegment(value: string): string {
 // docs: documentation markdown copied to docs/<kit-id>/ for agent reference.
 const ACTIVATED_ASSET_CLASSES = new Set(["flows", "skills", "docs"]);
 
-export function activateCodexLocal(sourceRoot: string, dest: string): Record<string, unknown> {
-  const inventory = readKitInventory(sourceRoot, dest);
+export function activateCodexLocal(sourceRoot: string, dest: string, options: { kitIdFilter?: string[] } = {}): Record<string, unknown> {
+  const inventory = readKitInventory(sourceRoot, dest, options);
   const runtimeDir = path.join(flowAgentsArtifactRoot(dest), "projections", "codex");
+  const writeRoot = path.resolve(runtimeDir, "../../..");
+  ensureSafeDirectory(writeRoot, runtimeDir);
   const generated: Record<string, string>[] = [];
   const skipped: Record<string, string | null>[] = [];
   for (const asset of inventory.assets) {
@@ -178,8 +262,7 @@ export function activateCodexLocal(sourceRoot: string, dest: string): Record<str
         continue;
       }
       const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
-      fs.mkdirSync(path.dirname(output), { recursive: true });
-      fs.copyFileSync(asset.source_path, output);
+      atomicCopyFile(writeRoot, asset.source_path, output);
       generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
     } else if (asset.asset_class === "skills" || asset.asset_class === "docs") {
       // Copy skills and docs to runtime/<adapter>/<class>/<kit-id>/<filename> so the
@@ -193,18 +276,16 @@ export function activateCodexLocal(sourceRoot: string, dest: string): Record<str
       const output = asset.asset_class === "skills"
         ? path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), safeSegment(path.basename(path.dirname(asset.source_path))), filename)
         : path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
-      fs.mkdirSync(path.dirname(output), { recursive: true });
-      fs.copyFileSync(asset.source_path, output);
+      atomicCopyFile(writeRoot, asset.source_path, output);
       generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id ?? "", source_path: asset.source_path.split(path.sep).join("/") });
     } else {
       skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is not activated by codex-local" });
     }
   }
-  fs.mkdirSync(runtimeDir, { recursive: true });
   const supportedClasses = Array.from(ACTIVATED_ASSET_CLASSES);
   const manifest = { schema_version: "1.0", adapter: "codex-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
   const manifestPath = path.join(runtimeDir, "activation.json");
-  writeJson(manifestPath, manifest);
+  atomicWriteJson(writeRoot, manifestPath, manifest);
   generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "codex-local.activation", source_path: manifestPath.split(path.sep).join("/") });
   return { selected_adapter: "codex-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }
@@ -215,13 +296,15 @@ export function activateCodexLocal(sourceRoot: string, dest: string): Record<str
 // Keeping it in the CLI adapter layer maximises reuse of readKitInventory and safeSegment,
 // mirrors the codex-local pattern exactly, and keeps framework adapters free of catalog-
 // layout knowledge. The Strands steering layer then reads the written runtime files.
-export function activateStrandsLocal(sourceRoot: string, dest: string): Record<string, unknown> {
-  const inventory = readKitInventory(sourceRoot, dest);
+export function activateStrandsLocal(sourceRoot: string, dest: string, options: { kitIdFilter?: string[] } = {}): Record<string, unknown> {
+  const inventory = readKitInventory(sourceRoot, dest, options);
   // Runtime flows land at .kontourai/flow-agents/projections/strands/flows/<kit-id>/<asset-id>.flow.json
   // so the Strands steering context can glob for *.flow.json under this path.
   // Runtime skills land at .kontourai/flow-agents/projections/strands/skills/<kit-id>/<filename> and
   // docs at .kontourai/flow-agents/projections/strands/docs/<kit-id>/<filename> for system-prompt injection.
   const runtimeDir = path.join(flowAgentsArtifactRoot(dest), "projections", "strands");
+  const writeRoot = path.resolve(runtimeDir, "../../..");
+  ensureSafeDirectory(writeRoot, runtimeDir);
   const generated: Record<string, string>[] = [];
   const skipped: Record<string, string | null>[] = [];
   for (const asset of inventory.assets) {
@@ -231,8 +314,7 @@ export function activateStrandsLocal(sourceRoot: string, dest: string): Record<s
         continue;
       }
       const output = path.join(runtimeDir, "flows", safeSegment(asset.kit_id), `${safeSegment(asset.asset_id)}.flow.json`);
-      fs.mkdirSync(path.dirname(output), { recursive: true });
-      fs.copyFileSync(asset.source_path, output);
+      atomicCopyFile(writeRoot, asset.source_path, output);
       generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id, source_path: asset.source_path.split(path.sep).join("/") });
     } else if (asset.asset_class === "skills" || asset.asset_class === "docs") {
       // Mirror the codex-local layout: strands/<class>/<kit-id>/<filename>.
@@ -246,18 +328,16 @@ export function activateStrandsLocal(sourceRoot: string, dest: string): Record<s
       const output = asset.asset_class === "skills"
         ? path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), safeSegment(path.basename(path.dirname(asset.source_path))), filename)
         : path.join(runtimeDir, asset.asset_class, safeSegment(asset.kit_id), filename);
-      fs.mkdirSync(path.dirname(output), { recursive: true });
-      fs.copyFileSync(asset.source_path, output);
+      atomicCopyFile(writeRoot, asset.source_path, output);
       generated.push({ asset_class: asset.asset_class, path: relPath(dest, output), kit_id: asset.kit_id, asset_id: asset.asset_id ?? "", source_path: asset.source_path.split(path.sep).join("/") });
     } else {
       skipped.push({ asset_class: asset.asset_class, path: asset.relative_path, kit_id: asset.kit_id, asset_id: asset.asset_id, reason: "asset class is not activated by strands-local" });
     }
   }
-  fs.mkdirSync(runtimeDir, { recursive: true });
   const supportedClasses = Array.from(ACTIVATED_ASSET_CLASSES);
   const manifest = { schema_version: "1.0", adapter: "strands-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
   const manifestPath = path.join(runtimeDir, "activation.json");
-  writeJson(manifestPath, manifest);
+  atomicWriteJson(writeRoot, manifestPath, manifest);
   generated.push({ asset_class: "activation-manifest", path: relPath(dest, manifestPath), kit_id: "runtime", asset_id: "strands-local.activation", source_path: manifestPath.split(path.sep).join("/") });
   return { selected_adapter: "strands-local", supported_asset_classes: supportedClasses, generated_runtime_files: generated, skipped_assets: skipped, warnings: inventory.warnings, errors: inventory.errors };
 }