@kontourai/flow-agents 3.3.0 → 3.4.0

package/src/cli/init.ts

@@ -10,7 +10,9 @@ 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";
+import { defaultCodexHome, durableInstallRecordPath, skillsManifestPath } from "../lib/local-artifact-root.js";
+import { runConsoleConnectWizard, describeConsoleStatus, buildPostInstallSummaryLines } from "../lib/console-connect-options.js";
+import { buildReport } from "./telemetry-doctor.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";
@@ -26,6 +28,15 @@ type InitOptions = {
   consoleTenant?: string;
   telemetrySinks: TelemetrySink[];
   activateKits: boolean;
+  activeKitIds?: string[];
+  // Informational only -- never read by installBundle()/install-console-config.sh
+  // (not part of the install writer contract). Set when the runtime was not
+  // given via an explicit --runtime flag/typed answer and the layered
+  // detector (detectRuntimeFromProcessEnv/detectRuntimeFromFilesystem)
+  // actually matched a signal, for the post-install summary's
+  // "(auto-detected)" annotation. headlessOptions() itself never sets this
+  // (untouched) -- main() merges it onto the headless result separately.
+  runtimeAutoDetected?: boolean;
 };
 
 const runtimeBundles: Record<Runtime, string> = {
@@ -111,10 +122,39 @@ Options:
   --console-token-file PATH
   --console-tenant ID
   --activate-kits
+  --activate-kit KIT_ID   Activate one catalog kit by id. Repeat for multiple kits.
   --yes, --headless
 `);
 }
 
+function catalogKitIds(): string[] {
+  const catalogPath = path.join(root, "kits", "catalog.json");
+  if (!fs.existsSync(catalogPath)) return [];
+  const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8")) as { kits?: unknown[] };
+  if (!Array.isArray(catalog.kits)) return [];
+  return catalog.kits
+    .map((entry) => typeof entry === "object" && entry !== null ? String((entry as Record<string, unknown>).id ?? "") : "")
+    .filter(Boolean);
+}
+
+function selectedKitIdsFromFlags(flags: ReturnType<typeof parseArgs>["flags"]): string[] {
+  const explicit = flagList(flags, "activate-kit").map((id) => id.trim()).filter(Boolean);
+  if (explicit.length) return [...new Set(explicit)];
+  if (flagBool(flags, "activate-kits")) return catalogKitIds();
+  return [];
+}
+
+function writeInstallRecord(dest: string, runtime: Runtime, global: boolean | undefined, activeKitIds: string[] = []): void {
+  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, ...(global ? { global: true } : {}), active_kit_ids: activeKitIds };
+  const recordTmp = `${recordPath}.tmp.${process.pid}`;
+  fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
+  fs.renameSync(recordTmp, recordPath);
+}
+
 function normalizeRuntime(value: string | undefined): Runtime | undefined {
   if (!value) return undefined;
   if (value === "claude") return "claude-code";
@@ -122,6 +162,105 @@ function normalizeRuntime(value: string | undefined): Runtime | undefined {
   throw new Error(`unknown runtime '${value}'; expected base, codex, claude-code, kiro, opencode, or pi`);
 }
 
+type ActorIdentityModule = { detectRuntime: (env: NodeJS.ProcessEnv) => string };
+
+/**
+ * The three candidate global config directories a runtime's own tooling uses,
+ * shared between `globalDest` (the `--global` install target) and
+ * `detectRuntimeFromFilesystem` (auto-detection fallback) so "where does
+ * runtime X's global config live" is defined in exactly one place.
+ */
+function runtimeGlobalConfigCandidates(
+  homedir: string,
+  env: NodeJS.ProcessEnv,
+): { "claude-code": string; codex: string; opencode: string } {
+  return {
+    "claude-code": path.join(homedir, ".claude"),
+    codex: defaultCodexHome(env, homedir),
+    opencode: path.join(env["XDG_CONFIG_HOME"] ?? path.join(homedir, ".config"), "opencode"),
+  };
+}
+
+/**
+ * Detect the current runtime from environment-variable signals already
+ * ambient in the invoking process (Claude Code / Codex / opencode session
+ * markers). Reuses the single existing `detectRuntime` implementation from
+ * `scripts/hooks/lib/actor-identity.js` (via the same `createRequire` pattern
+ * used elsewhere in this file for `install-merge.js`/`skill-drift.js`)
+ * instead of forking a second copy of the env-var contract. `pi`'s env-var
+ * contract is unverified there (see actor-identity.js's own docstring) and is
+ * intentionally out of scope for auto-detection, so it maps down to
+ * `"unknown"` here (pi still falls back to `"base"` like today).
+ */
+export function detectRuntimeFromProcessEnv(env: NodeJS.ProcessEnv = process.env): Runtime | "unknown" {
+  const actorIdentityPath = path.join(root, "scripts", "hooks", "lib", "actor-identity.js");
+  const _require = createRequire(import.meta.url);
+  const { detectRuntime } = _require(actorIdentityPath) as ActorIdentityModule;
+  const detected = detectRuntime(env);
+  if (detected === "claude-code" || detected === "codex" || detected === "opencode") return detected;
+  return "unknown";
+}
+
+/**
+ * Detect the current runtime by probing for exactly one runtime's own global
+ * config directory on disk (the same paths `globalDest` computes for
+ * `--global` installs — see `runtimeGlobalConfigCandidates`). Zero matches or
+ * 2+ matches are both ambiguous and must never guess: only a single
+ * unambiguous hit returns a runtime; everything else is `"unknown"`.
+ */
+export function detectRuntimeFromFilesystem(
+  homedir: string = os.homedir(),
+  env: NodeJS.ProcessEnv = process.env,
+): Runtime | "unknown" {
+  const candidates = runtimeGlobalConfigCandidates(homedir, env);
+  const matches = (Object.keys(candidates) as Array<keyof typeof candidates>).filter((runtime) => {
+    try {
+      return fs.existsSync(candidates[runtime]);
+    } catch {
+      return false;
+    }
+  });
+  return matches.length === 1 ? matches[0] : "unknown";
+}
+
+/**
+ * Layered runtime auto-detection default used to pre-fill both the
+ * interactive prompt and the headless `--runtime` fallback: (1) env-var
+ * signals from the invoking process, (2) failing that, an unambiguous
+ * filesystem probe, (3) failing that, today's `"base"` default. An explicit
+ * `--runtime` flag or interactive answer always overrides this — this
+ * function only supplies the fallback default (see `interactiveOptions` /
+ * `headlessOptions`).
+ */
+export function detectDefaultRuntime(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: string = os.homedir(),
+): Runtime {
+  const fromEnv = detectRuntimeFromProcessEnv(env);
+  if (fromEnv !== "unknown") return fromEnv;
+  const fromFilesystem = detectRuntimeFromFilesystem(homedir, env);
+  if (fromFilesystem !== "unknown") return fromFilesystem;
+  return "base";
+}
+
+/**
+ * Returns the runtime the layered detector actually matched (env signal
+ * first, then an unambiguous filesystem probe), or "unknown" if neither
+ * fired. Distinct from `detectDefaultRuntime()`, which additionally falls
+ * back to `"base"` when detection is unknown -- the post-install summary's
+ * "(auto-detected)" annotation needs to distinguish "detection fired" from
+ * "detection defaulted to base," which `detectDefaultRuntime()`'s return
+ * value alone cannot express.
+ */
+function detectedRuntimeSignal(
+  env: NodeJS.ProcessEnv = process.env,
+  homedir: string = os.homedir(),
+): Runtime | "unknown" {
+  const fromEnv = detectRuntimeFromProcessEnv(env);
+  if (fromEnv !== "unknown") return fromEnv;
+  return detectRuntimeFromFilesystem(homedir, env);
+}
+
 function normalizeTelemetrySink(value: string): TelemetrySink {
   if (value === "local-files" || value === "local-kontour-console" || value === "kontour-hosted-console" || value === "user-hosted-console" || value === "kontour-cloud" || value === "hosted-kontour-console") return value;
   throw new Error(`unknown telemetry sink '${value}'`);
@@ -140,6 +279,26 @@ function needsConsoleCredentials(sinks: TelemetrySink[]): boolean {
   return sinks.some((sink) => sink !== "local-files");
 }
 
+const DEFAULT_HOSTED_CONSOLE_URL = "https://console.kontourai.io";
+const DEFAULT_LOCAL_CONSOLE_URL = "http://127.0.0.1:3737";
+
+/**
+ * Resolve one of `console-presets.sh`'s bash functions (by name) against the
+ * source root, so the interactive wizard's printed defaults are never a
+ * second hardcoded literal competing with the one bash source of truth
+ * (itself overridable via FLOW_AGENTS_KONTOUR_CLOUD_CONSOLE_URL /
+ * FLOW_AGENTS_LOCAL_KONTOUR_CONSOLE_URL, depending on which function is
+ * named). `fallback` is only a defensive floor for the rare case the
+ * subprocess produces no output (e.g. an unreadable source tree) -- it is not
+ * a second default.
+ */
+function presetConsoleUrl(bashFnName: string, fallback: string): string {
+  const scriptPath = path.join(root, "scripts", "telemetry", "console-presets.sh");
+  const result = spawnSync("bash", ["-c", `source "${scriptPath}" && ${bashFnName}`], { encoding: "utf8" });
+  const stdout = (result.stdout ?? "").trim();
+  return stdout || fallback;
+}
+
 async function questionHidden(prompt: string): Promise<string> {
   if (!process.stdin.isTTY) return "";
   return await new Promise((resolve) => {
@@ -178,12 +337,15 @@ function defaultDest(runtime: Runtime): string {
   return process.cwd();
 }
 
-function globalDest(runtime: Runtime): string {
+export function globalDest(runtime: Runtime): string {
+  // Shared with detectRuntimeFromFilesystem so the "where is runtime X's global
+  // config" path logic is defined exactly once.
+  const candidates = runtimeGlobalConfigCandidates(os.homedir(), process.env);
   if (runtime === "claude-code") {
     // Honor FLOW_AGENTS_USER_CLAUDE_SETTINGS for test isolation (same as checkScopeCollision).
     const override = process.env["FLOW_AGENTS_USER_CLAUDE_SETTINGS"];
     if (override) return path.dirname(override);
-    return path.join(os.homedir(), ".claude");
+    return candidates["claude-code"];
   }
   if (runtime === "opencode") {
     // Honor FLOW_AGENTS_USER_OPENCODE_CONFIG (points to the opencode.json FILE) for test isolation,
@@ -191,11 +353,15 @@ function globalDest(runtime: Runtime): string {
     const override = process.env["FLOW_AGENTS_USER_OPENCODE_CONFIG"];
     if (override) return path.dirname(override);
     // Global opencode config: ~/.config/opencode/ (honor XDG_CONFIG_HOME when set, else ~/.config).
-    return path.join(process.env["XDG_CONFIG_HOME"] ?? path.join(os.homedir(), ".config"), "opencode");
+    return candidates.opencode;
   }
   if (runtime === "codex") {
     // codex --global routes to the standard Codex home. --dest remains an explicit override.
-    return defaultCodexHome();
+    // `candidates.codex` is built from the same `CODEX_HOME || ~/.codex` resolution as
+    // `defaultCodexHome()` (see runtimeGlobalConfigCandidates above), so this is byte-identical
+    // to calling `defaultCodexHome()` directly while keeping the candidate map the single
+    // source of truth for "where does runtime X's global config live".
+    return candidates.codex;
   }
   if (runtime === "pi") {
     // pi has no documented global config dir.
@@ -205,44 +371,109 @@ function globalDest(runtime: Runtime): string {
   return defaultDest(runtime);
 }
 
-function parseYesNo(value: string, fallback: boolean): boolean {
-  const normalized = value.trim().toLowerCase();
-  if (!normalized) return fallback;
-  if (["y", "yes", "true", "1"].includes(normalized)) return true;
-  if (["n", "no", "false", "0"].includes(normalized)) return false;
-  return fallback;
+type ConsoleConnectGatherResult = {
+  telemetrySinks: TelemetrySink[];
+  consoleUrl: string | undefined;
+  consoleTokenValue: string | undefined;
+  consoleTenant: string | undefined;
+};
+
+/**
+ * Console-connect sink/credential gathering for interactiveOptions(),
+ * extracted as a pure refactor (identical behavior, identical returned
+ * shape) so interactiveOptions() itself stays a thin top-level orchestration.
+ * Covers both branches of "did the caller already give --telemetry-sink(s)
+ * on argv":
+ *  - sinkFlagsGiven: the guided wizard is bypassed entirely (same as the old
+ *    hidden sinkAnswer skip); only whichever of URL/token/tenant was not
+ *    already supplied via flag gets its own prompt.
+ *  - not given: the full guided wizard runs, with askWithFlagOverrides /
+ *    askHiddenWithFlagOverrides short-circuiting any individual sub-prompt
+ *    whose answer was already supplied via flag -- same flag-wins precedence
+ *    as the sinkFlagsGiven branch, just applied per-sub-prompt instead of
+ *    skipping the whole wizard.
+ * Flag-wins-over-prompt precedence is unchanged from before this wizard
+ * existed.
+ */
+async function gatherConsoleConnectOptions(
+  rl: ReturnType<typeof createInterface>,
+  args: ReturnType<typeof parseArgs>,
+  consoleTokenFile: string | undefined,
+): Promise<ConsoleConnectGatherResult> {
+  const sinkFlagsGiven = flagList(args.flags, "telemetry-sink").length > 0 || flagList(args.flags, "telemetry-sinks").length > 0;
+  const consoleUrlFlag = flagString(args.flags, "console-url");
+  const consoleTenantFlag = flagString(args.flags, "console-tenant") ?? flagString(args.flags, "console-tenant-id");
+
+  if (sinkFlagsGiven) {
+    const telemetrySinks = telemetrySinksFromFlags(args.flags);
+    const needsUserHostedUrl = telemetrySinks.includes("user-hosted-console") || telemetrySinks.includes("hosted-kontour-console");
+    const consoleUrl = consoleUrlFlag ?? (needsUserHostedUrl ? await rl.question("User-hosted Console URL: ") : undefined);
+    const consoleTokenValue = consoleTokenFile ? undefined : (needsConsoleCredentials(telemetrySinks) ? await questionHidden("Console telemetry token (blank to skip): ") : undefined);
+    const consoleTenant = consoleTenantFlag ?? (needsConsoleCredentials(telemetrySinks) ? await rl.question("Console tenant ID (blank to skip): ") : undefined);
+    return { telemetrySinks, consoleUrl, consoleTokenValue, consoleTenant };
+  }
+
+  const askWithFlagOverrides = async (prompt: string): Promise<string> => {
+    if (prompt.includes("Self-hosted Console URL") && consoleUrlFlag !== undefined) return consoleUrlFlag;
+    if (prompt.includes("Console tenant ID") && consoleTenantFlag !== undefined) return consoleTenantFlag;
+    return rl.question(prompt);
+  };
+  const askHiddenWithFlagOverrides = async (prompt: string): Promise<string> => {
+    if (consoleTokenFile) return "";
+    return questionHidden(prompt);
+  };
+  const wizardResult = await runConsoleConnectWizard(
+    { ask: askWithFlagOverrides, askHidden: askHiddenWithFlagOverrides },
+    {
+      hostedUrl: presetConsoleUrl("flow_agents_kontour_hosted_console_url", DEFAULT_HOSTED_CONSOLE_URL),
+      localUrl: presetConsoleUrl("flow_agents_local_kontour_console_url", DEFAULT_LOCAL_CONSOLE_URL),
+    },
+  );
+  for (const warning of wizardResult.warnings) console.warn(`flow-agents init: ${warning}`);
+  return {
+    telemetrySinks: wizardResult.telemetrySinks,
+    consoleUrl: consoleUrlFlag ?? wizardResult.consoleUrl,
+    consoleTokenValue: consoleTokenFile ? undefined : wizardResult.consoleTokenValue,
+    consoleTenant: consoleTenantFlag ?? wizardResult.consoleTenant,
+  };
 }
 
 async function interactiveOptions(argv: string[]): Promise<InitOptions> {
   const args = parseArgs(argv);
   const rl = createInterface({ input, output });
   try {
-    const runtimeDefault = normalizeRuntime(flagString(args.flags, "runtime")) ?? "base";
-    const runtimeAnswer = flagString(args.flags, "runtime") ?? await rl.question(`Runtime [${runtimeDefault}]: `);
-    const runtime = normalizeRuntime(runtimeAnswer.trim() || runtimeDefault) ?? runtimeDefault;
+    const explicitRuntimeFlag = flagString(args.flags, "runtime");
+    const runtimeDefault = normalizeRuntime(explicitRuntimeFlag) ?? detectDefaultRuntime();
+    const runtimeAnswer = explicitRuntimeFlag ?? await rl.question(`Runtime [${runtimeDefault}]: `);
+    const runtimeAnswerTrimmed = runtimeAnswer.trim();
+    const runtime = normalizeRuntime(runtimeAnswerTrimmed || runtimeDefault) ?? runtimeDefault;
+    // "(auto-detected)" is only accurate when the runtime was neither an
+    // explicit --runtime flag nor a typed interactive answer AND the layered
+    // detector actually matched a signal (not merely defaulted to "base").
+    const runtimeAutoDetected = !explicitRuntimeFlag && !runtimeAnswerTrimmed && detectedRuntimeSignal() === runtime;
     const isGlobal = flagBool(args.flags, "global");
     const destBase = isGlobal ? globalDest(runtime) : defaultDest(runtime);
     const destDefault = flagString(args.flags, "dest", destBase) ?? destBase;
     const destAnswer = flagString(args.flags, "dest") ?? await rl.question(`Install destination [${destDefault}]: `);
-    const sinkDefault = telemetrySinksFromFlags(args.flags);
-    const sinkAnswer = flagList(args.flags, "telemetry-sink").length || flagList(args.flags, "telemetry-sinks").length
-      ? sinkDefault.join(",")
-      : await rl.question(`Telemetry sinks [${sinkDefault.join(",")}]: `);
-    const telemetrySinks = telemetrySinksFromValues([sinkAnswer || sinkDefault.join(",")]);
-    const needsUserHostedUrl = telemetrySinks.includes("user-hosted-console") || telemetrySinks.includes("hosted-kontour-console");
-    const consoleUrl = flagString(args.flags, "console-url") ?? (needsUserHostedUrl ? await rl.question("User-hosted Console URL: ") : undefined);
+
+    // Guided "Connect to Kontour Console?" wizard (Hosted/Local/Self-hosted/Skip)
+    // replaces the old hidden sink-keyword prompt -- see gatherConsoleConnectOptions
+    // for the flag-override / sink-flags-given branching.
     const consoleEndpoint = flagString(args.flags, "console-endpoint") ?? flagString(args.flags, "console-endpoint-url");
     const consoleTokenFile = flagString(args.flags, "console-token-file");
-    const consoleTokenValue = consoleTokenFile ? undefined : (needsConsoleCredentials(telemetrySinks) ? await questionHidden("Console telemetry token (blank to skip): ") : undefined);
-    const consoleTenant = flagString(args.flags, "console-tenant") ?? flagString(args.flags, "console-tenant-id") ?? (needsConsoleCredentials(telemetrySinks) ? await rl.question("Console tenant ID (blank to skip): ") : undefined);
-    const activateDefault = false;
-    const activateAnswer = flagBool(args.flags, "activate-kits")
-      ? "yes"
-      : runtime === "codex"
-        ? await rl.question(`Activate local Builder Kit runtime assets [${activateDefault ? "Y/n" : "y/N"}]: `)
-        : "no";
+    const { telemetrySinks, consoleUrl, consoleTokenValue, consoleTenant } = await gatherConsoleConnectOptions(rl, args, consoleTokenFile);
+
+    const activeKitIds = selectedKitIdsFromFlags(args.flags);
+    if (!activeKitIds.length && !flagBool(args.flags, "activate-kits") && !flagList(args.flags, "activate-kit").length) {
+      const available = catalogKitIds();
+      if (available.length) {
+        const answer = await rl.question(`Activate kits by id (comma-separated, default none) [none]: `);
+        activeKitIds.push(...answer.split(",").map((id) => id.trim()).filter((id) => available.includes(id)));
+      }
+    }
     return {
       runtime,
+      runtimeAutoDetected,
       global: isGlobal,
       dest: path.resolve(destAnswer.trim() || destDefault),
       consoleUrl: consoleUrl?.trim() || undefined,
@@ -251,7 +482,8 @@ async function interactiveOptions(argv: string[]): Promise<InitOptions> {
       consoleTokenValue: consoleTokenValue?.trim() || undefined,
       consoleTenant: consoleTenant?.trim() || undefined,
       telemetrySinks,
-      activateKits: runtime === "codex" && parseYesNo(activateAnswer, activateDefault),
+      activateKits: activeKitIds.length > 0,
+      activeKitIds,
     };
   } finally {
     rl.close();
@@ -260,7 +492,7 @@ async function interactiveOptions(argv: string[]): Promise<InitOptions> {
 
 function headlessOptions(argv: string[]): InitOptions {
   const args = parseArgs(argv);
-  const runtime = normalizeRuntime(flagString(args.flags, "runtime")) ?? "base";
+  const runtime = normalizeRuntime(flagString(args.flags, "runtime")) ?? detectDefaultRuntime();
   const isGlobal = flagBool(args.flags, "global");
   const destBase = isGlobal ? globalDest(runtime) : defaultDest(runtime);
   return {
@@ -272,11 +504,12 @@ function headlessOptions(argv: string[]): InitOptions {
     consoleTokenFile: flagString(args.flags, "console-token-file"),
     consoleTenant: flagString(args.flags, "console-tenant") ?? flagString(args.flags, "console-tenant-id"),
     telemetrySinks: telemetrySinksFromFlags(args.flags),
-    activateKits: runtime === "codex" && flagBool(args.flags, "activate-kits"),
+    activateKits: selectedKitIdsFromFlags(args.flags).length > 0,
+    activeKitIds: selectedKitIdsFromFlags(args.flags),
   };
 }
 
-function ensureBundle(runtime: Runtime): string {
+export function ensureBundle(runtime: Runtime): string {
   const bundle = path.join(root, "dist", runtimeBundles[runtime]);
   if (!fs.existsSync(path.join(bundle, "install.sh"))) {
     const rc = buildBundles();
@@ -297,6 +530,35 @@ function ensureBundle(runtime: Runtime): string {
 const GLOBAL_INSTALL_PROJECT_DIR_PREFIX = /root="\$\{CLAUDE_PROJECT_DIR:-\$\(pwd\)\}";\s*/g;
 const GLOBAL_INSTALL_PROJECT_DIR_VAR = /"\$root\//g;
 
+type InstallMergeConflict = {
+  path: string;
+  existingValue: unknown;
+  managedValue: unknown;
+};
+
+type MergeSettingsFn = (
+  existing: Record<string, unknown>,
+  managed: Record<string, unknown>,
+  options?: { onConflict?: (conflict: InstallMergeConflict) => void },
+) => Record<string, unknown>;
+
+function warnInstallMergeConflicts(conflicts: InstallMergeConflict[]): void {
+  for (const conflict of conflicts) {
+    console.warn(`install-merge: conflict: preserving existing setting '${conflict.path}' and not applying Flow Agents managed value`);
+  }
+}
+
+function mergeInstallSettings(
+  mergeSettings: MergeSettingsFn,
+  existing: Record<string, unknown>,
+  managed: Record<string, unknown>,
+): Record<string, unknown> {
+  const conflicts: InstallMergeConflict[] = [];
+  const merged = mergeSettings(existing, managed, { onConflict: (conflict) => conflicts.push(conflict) });
+  warnInstallMergeConflicts(conflicts);
+  return merged;
+}
+
 function rewriteCommandForGlobalInstall(command: string, sourceRoot: string): string {
   return command
     .replace(GLOBAL_INSTALL_PROJECT_DIR_PREFIX, "")
@@ -379,8 +641,9 @@ function installBundle(bundle: string, options: InitOptions): number {
 }
 
 function activateKits(options: InitOptions): number {
-  if (!options.activateKits) return 0;
-  const result = activateCodexLocal(options.dest, options.dest);
+  const activeKitIds = options.activeKitIds ?? [];
+  if (!options.activateKits || activeKitIds.length === 0 || options.runtime !== "codex") return 0;
+  const result = activateCodexLocal(options.dest, options.dest, { kitIdFilter: activeKitIds });
   if (Array.isArray(result.errors) && result.errors.length > 0) {
     console.error(JSON.stringify(result, null, 2));
     return 1;
@@ -390,6 +653,72 @@ function activateKits(options: InitOptions): number {
   return 0;
 }
 
+/**
+ * Headless counterpart of interactiveOptions()'s inline `runtimeAutoDetected`
+ * computation. headlessOptions() itself is untouched (see its doc note) --
+ * this is computed separately in main() and merged onto its result, so the
+ * "(auto-detected)" annotation applies to both install paths without adding
+ * a new required prompt or changing headlessOptions()'s own behavior.
+ */
+function headlessRuntimeAutoDetected(argv: string[]): boolean {
+  const args = parseArgs(argv);
+  if (flagString(args.flags, "runtime")) return false;
+  return detectedRuntimeSignal() !== "unknown";
+}
+
+/**
+ * G2 auto-verify + G3 post-install summary, shared by both the headless and
+ * interactive install paths (applies identically regardless of which one
+ * reached main()'s successful non-global install tail). Calls
+ * telemetry-doctor.ts's buildReport() in-process against the endpoint
+ * install-console-config.sh just wrote. Never allowed to change the exit
+ * code or hang the install: buildReport already has its own bounded default
+ * reachability timeout (2000ms unless overridden), and any thrown/rejected
+ * error here is caught and downgraded to a warning line only.
+ */
+async function printPostInstallSummary(options: InitOptions): Promise<void> {
+  let doctorConsole: {
+    sink: "local-only" | "console";
+    reachability: { checked: boolean; ok: boolean | null; error?: string; statusCode?: number };
+  } = { sink: "local-only", reachability: { checked: false, ok: null } };
+  let tokenConfigured = false;
+  let tenantConfigured = false;
+  try {
+    const report = await buildReport(["--dest", options.dest]);
+    doctorConsole = report.console;
+    tokenConfigured = report.console.tokenConfigured;
+    tenantConfigured = report.console.tenantConfigured;
+  } catch (error) {
+    console.warn(`flow-agents init: WARNING: could not verify the Console connection: ${(error as Error).message} (telemetry still installed; run 'flow-agents telemetry-doctor' to re-check).`);
+  }
+  const consoleStatus = describeConsoleStatus({ console: doctorConsole });
+  const nextSteps = [`Run your agent inside ${options.dest} -- Flow Agents hooks are already wired.`];
+  if (consoleStatus.status !== "local-only") {
+    nextSteps.push("Telemetry now flows to Kontour Console; visit the Console for ROI/economics views.");
+  }
+  // Only for the "reachability was never attempted" case (self-hosted/BYO
+  // HTTPS hosts default to not-allowed without --allow-network) -- never for
+  // local-only (nothing to verify) or the already-verified case (nothing left
+  // to do). doctorConsole.reachability.checked is the same raw signal
+  // describeConsoleStatus used to pick its NOT_CHECKED_DETAIL branch, so this
+  // stays in sync with that classifier without re-parsing its detail string.
+  if (consoleStatus.status === "connected-unverified" && doctorConsole.reachability.checked === false) {
+    nextSteps.push("Self-hosted/BYO Console reachability was not checked; run `flow-agents telemetry-doctor --allow-network` to verify it.");
+  }
+  nextSteps.push("Re-run `flow-agents init` anytime to reconfigure runtime, destination, or Console connection.");
+  const summaryLines = buildPostInstallSummaryLines({
+    runtime: options.runtime,
+    runtimeAutoDetected: Boolean(options.runtimeAutoDetected),
+    dest: options.dest,
+    telemetrySinks: options.telemetrySinks,
+    consoleStatus,
+    tokenConfigured,
+    tenantConfigured,
+    nextSteps,
+  });
+  for (const line of summaryLines) console.log(line);
+}
+
 export async function main(argv = process.argv.slice(2)): Promise<number> {
   if (argv.includes("--help") || argv.includes("-h")) {
     usage();
@@ -397,7 +726,9 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
   }
   const headless = argv.includes("--yes") || argv.includes("--headless") || !process.stdin.isTTY;
   try {
-    const options = headless ? headlessOptions(argv) : await interactiveOptions(argv);
+    const options = headless
+      ? { ...headlessOptions(argv), runtimeAutoDetected: headlessRuntimeAutoDetected(argv) }
+      : await interactiveOptions(argv);
     // Scope-collision check for claude-code: Claude Code merges user-level
     // (~/.claude/settings.json) and project-level (.claude/settings.json) settings
     // and runs ALL matching hooks from both files. If a user-level settings file
@@ -442,12 +773,12 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       const destSettingsPath = path.join(options.dest, "settings.json");
       const installMergePath = path.join(root, "scripts", "install-merge.js");
       const _require = createRequire(import.meta.url);
-      const { mergeSettings } = _require(installMergePath) as { mergeSettings: (a: Record<string, unknown>, b: Record<string, unknown>) => Record<string, unknown> };
+      const { mergeSettings } = _require(installMergePath) as { mergeSettings: MergeSettingsFn };
       let existing: Record<string, unknown> = {};
       if (fs.existsSync(destSettingsPath)) {
         try { existing = JSON.parse(fs.readFileSync(destSettingsPath, "utf8")) as Record<string, unknown>; } catch { existing = {}; }
       }
-      const merged = mergeSettings(existing, managed);
+      const merged = mergeInstallSettings(mergeSettings, existing, managed);
       const tmp = `${destSettingsPath}.tmp.${process.pid}`;
       fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
       fs.renameSync(tmp, destSettingsPath);
@@ -456,16 +787,31 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       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 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 recordTmp = `${recordPath}.tmp.${process.pid}`;
-      fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}\n`, "utf8");
-      fs.renameSync(recordTmp, recordPath);
+      writeInstallRecord(options.dest, "claude-code", true, options.activeKitIds ?? []);
       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}`);
+      // Write a per-skill-file sha256 content-hash manifest, sibling of install.json, so
+      // `flow-agents skill-drift-check` and the SessionStart advisory can classify installed
+      // skill files as in_sync/kit_updated/user_modified/unbaselined/missing_install/kit_removed
+      // without re-deriving a second hashing convention (kontourai/flow-agents#439). This is an
+      // additive convenience feature layered on top of the install that already succeeded above
+      // (settings merge + skills/agents sync) — a failure writing this manifest must never fail
+      // the whole `init --global` run, so it is contained here: warn and continue.
+      try {
+        const skillDriftLibPath = path.join(root, "scripts", "hooks", "lib", "skill-drift.js");
+        const _requireSkillDrift = createRequire(import.meta.url);
+        const { buildManifest, writeManifestAtomic } = _requireSkillDrift(skillDriftLibPath) as {
+          buildManifest: (params: { skillsSourceDir: string; runtime: string }) => unknown;
+          writeManifestAtomic: (manifestPath: string, manifest: unknown) => void;
+        };
+        const skillsManifest = buildManifest({ skillsSourceDir: path.join(bundle, ".claude", "skills"), runtime: "claude-code" });
+        writeManifestAtomic(skillsManifestPath(options.dest), skillsManifest);
+      } catch (error) {
+        console.error(
+          `flow-agents init: WARNING: could not write skills drift-detection manifest: ${(error as Error).message} ` +
+            "(drift detection will report unbaselined until the next successful --global sync)."
+        );
+      }
       return 0;
     }
     // --global for opencode: merge FA opencode.json into the global opencode config dir.
@@ -484,26 +830,18 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       const destConfigPath = path.join(options.dest, "opencode.json");
       const installMergePath = path.join(root, "scripts", "install-merge.js");
       const _require = createRequire(import.meta.url);
-      const { mergeSettings } = _require(installMergePath) as { mergeSettings: (a: Record<string, unknown>, b: Record<string, unknown>) => Record<string, unknown> };
+      const { mergeSettings } = _require(installMergePath) as { mergeSettings: MergeSettingsFn };
       let existing: Record<string, unknown> = {};
       if (fs.existsSync(destConfigPath)) {
         try { existing = JSON.parse(fs.readFileSync(destConfigPath, "utf8")) as Record<string, unknown>; } catch { existing = {}; }
       }
-      const merged = mergeSettings(existing, managed);
+      const merged = mergeInstallSettings(mergeSettings, existing, managed);
       const tmp = `${destConfigPath}.tmp.${process.pid}`;
       fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}
 `, "utf8");
       fs.renameSync(tmp, destConfigPath);
       // Write version stamp.
-      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 recordTmp = `${recordPath}.tmp.${process.pid}`;
-      fs.writeFileSync(recordTmp, `${JSON.stringify(record, null, 2)}
-`, "utf8");
-      fs.renameSync(recordTmp, recordPath);
+      writeInstallRecord(options.dest, "opencode", true, options.activeKitIds ?? []);
       console.log(`Flow Agents global config merged for opencode in ${options.dest}`);
       return 0;
     }
@@ -528,6 +866,7 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
       }
       const installed = result.status ?? 1;
       if (installed !== 0) return installed;
+      writeInstallRecord(options.dest, "codex", true, options.activeKitIds ?? []);
       return activateKits(options);
     }
     // --global for pi: NOT_VERIFIED (no documented global dir). Warn and fall through to workspace install.
@@ -541,7 +880,13 @@ export async function main(argv = process.argv.slice(2)): Promise<number> {
     const bundle = ensureBundle(options.runtime);
     const installed = installBundle(bundle, options);
     if (installed !== 0) return installed;
-    return activateKits(options);
+    writeInstallRecord(options.dest, options.runtime, options.global, options.activeKitIds ?? []);
+    const activated = activateKits(options);
+    // G2/G3: shared post-install auto-verify + summary tail. Applies
+    // identically whether main() reached here via headlessOptions() or
+    // interactiveOptions() -- never changes `activated`'s exit code.
+    await printPostInstallSummary(options);
+    return activated;
   } catch (error) {
     console.error(`flow-agents init: ${(error as Error).message}`);
     return 2;
@@ -604,12 +949,12 @@ function dogfoodClaudeCode(bundleRoot: string, dest: string): void {
   // Merge: read existing, strip FA hooks, append new FA hooks, preserve all other keys.
   const installMergePath = path.join(root, "scripts", "install-merge.js");
   const _require = createRequire(import.meta.url);
-  const { mergeSettings } = _require(installMergePath) as { mergeSettings: (a: Record<string, unknown>, b: Record<string, unknown>) => Record<string, unknown> };
+  const { mergeSettings } = _require(installMergePath) as { mergeSettings: MergeSettingsFn };
   let existing: Record<string, unknown> = {};
   if (fs.existsSync(destSettingsPath)) {
     try { existing = JSON.parse(fs.readFileSync(destSettingsPath, "utf8")) as Record<string, unknown>; } catch { existing = {}; }
   }
-  const merged = mergeSettings(existing, managed);
+  const merged = mergeInstallSettings(mergeSettings, existing, managed);
   const tmp = `${destSettingsPath}.tmp.${process.pid}`;
   fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
   fs.renameSync(tmp, destSettingsPath);
@@ -642,12 +987,12 @@ function dogfoodCodex(bundleRoot: string, dest: string): void {
   // Merge: read existing, strip FA hook-groups, append new FA hook-groups, preserve user groups.
   const installMergePath = path.join(root, "scripts", "install-merge.js");
   const _require = createRequire(import.meta.url);
-  const { mergeSettings } = _require(installMergePath) as { mergeSettings: (a: Record<string, unknown>, b: Record<string, unknown>) => Record<string, unknown> };
+  const { mergeSettings } = _require(installMergePath) as { mergeSettings: MergeSettingsFn };
   let existing: Record<string, unknown> = {};
   if (fs.existsSync(destHooksPath)) {
     try { existing = JSON.parse(fs.readFileSync(destHooksPath, "utf8")) as Record<string, unknown>; } catch { existing = {}; }
   }
-  const merged = mergeSettings(existing, managed);
+  const merged = mergeInstallSettings(mergeSettings, existing, managed);
   const tmp = `${destHooksPath}.tmp.${process.pid}`;
   fs.writeFileSync(tmp, `${JSON.stringify(merged, null, 2)}\n`, "utf8");
   fs.renameSync(tmp, destHooksPath);