@kontourai/flow-agents 3.3.0 → 3.4.0

package/build/src/cli/init.js

@@ -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";
 const runtimeBundles = {
     base: "base",
     codex: "codex",
@@ -92,9 +94,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() {
+    const catalogPath = path.join(root, "kits", "catalog.json");
+    if (!fs.existsSync(catalogPath))
+        return [];
+    const catalog = JSON.parse(fs.readFileSync(catalogPath, "utf8"));
+    if (!Array.isArray(catalog.kits))
+        return [];
+    return catalog.kits
+        .map((entry) => typeof entry === "object" && entry !== null ? String(entry.id ?? "") : "")
+        .filter(Boolean);
+}
+function selectedKitIdsFromFlags(flags) {
+    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, runtime, global, activeKitIds = []) {
+    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"));
+    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) {
     if (!value)
         return undefined;
@@ -104,6 +136,91 @@ function normalizeRuntime(value) {
         return value;
     throw new Error(`unknown runtime '${value}'; expected base, codex, claude-code, kiro, opencode, or pi`);
 }
+/**
+ * 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, env) {
+    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 = process.env) {
+    const actorIdentityPath = path.join(root, "scripts", "hooks", "lib", "actor-identity.js");
+    const _require = createRequire(import.meta.url);
+    const { detectRuntime } = _require(actorIdentityPath);
+    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 = os.homedir(), env = process.env) {
+    const candidates = runtimeGlobalConfigCandidates(homedir, env);
+    const matches = Object.keys(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 = process.env, homedir = os.homedir()) {
+    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 = process.env, homedir = os.homedir()) {
+    const fromEnv = detectRuntimeFromProcessEnv(env);
+    if (fromEnv !== "unknown")
+        return fromEnv;
+    return detectRuntimeFromFilesystem(homedir, env);
+}
 function normalizeTelemetrySink(value) {
     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;
@@ -119,6 +236,24 @@ function telemetrySinksFromFlags(flags) {
 function needsConsoleCredentials(sinks) {
     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, fallback) {
+    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) {
     if (!process.stdin.isTTY)
         return "";
@@ -157,13 +292,16 @@ function defaultDest(runtime) {
         return path.join(os.homedir(), ".flow-agents");
     return process.cwd();
 }
-function globalDest(runtime) {
+export function globalDest(runtime) {
+    // 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,
@@ -172,11 +310,15 @@ function globalDest(runtime) {
         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.
@@ -185,46 +327,94 @@ function globalDest(runtime) {
     }
     return defaultDest(runtime);
 }
-function parseYesNo(value, fallback) {
-    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;
+/**
+ * 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, args, consoleTokenFile) {
+    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) => {
+        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) => {
+        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) {
     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,
@@ -233,7 +423,8 @@ async function interactiveOptions(argv) {
             consoleTokenValue: consoleTokenValue?.trim() || undefined,
             consoleTenant: consoleTenant?.trim() || undefined,
             telemetrySinks,
-            activateKits: runtime === "codex" && parseYesNo(activateAnswer, activateDefault),
+            activateKits: activeKitIds.length > 0,
+            activeKitIds,
         };
     }
     finally {
@@ -242,7 +433,7 @@ async function interactiveOptions(argv) {
 }
 function headlessOptions(argv) {
     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 {
@@ -254,10 +445,11 @@ function headlessOptions(argv) {
         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) {
+export function ensureBundle(runtime) {
     const bundle = path.join(root, "dist", runtimeBundles[runtime]);
     if (!fs.existsSync(path.join(bundle, "install.sh"))) {
         const rc = buildBundles();
@@ -278,6 +470,17 @@ function ensureBundle(runtime) {
 // 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 warnInstallMergeConflicts(conflicts) {
+    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, existing, managed) {
+    const conflicts = [];
+    const merged = mergeSettings(existing, managed, { onConflict: (conflict) => conflicts.push(conflict) });
+    warnInstallMergeConflicts(conflicts);
+    return merged;
+}
 function rewriteCommandForGlobalInstall(command, sourceRoot) {
     return command
         .replace(GLOBAL_INSTALL_PROJECT_DIR_PREFIX, "")
@@ -369,9 +572,10 @@ function installBundle(bundle, options) {
     return result.status ?? 1;
 }
 function activateKits(options) {
-    if (!options.activateKits)
+    const activeKitIds = options.activeKitIds ?? [];
+    if (!options.activateKits || activeKitIds.length === 0 || options.runtime !== "codex")
         return 0;
-    const result = activateCodexLocal(options.dest, options.dest);
+    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;
@@ -380,6 +584,70 @@ function activateKits(options) {
     console.log(`Activated ${generated.length} Codex local runtime asset(s)`);
     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) {
+    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) {
+    let doctorConsole = { 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.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)) {
     if (argv.includes("--help") || argv.includes("-h")) {
         usage();
@@ -387,7 +655,9 @@ export async function main(argv = process.argv.slice(2)) {
     }
     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
@@ -443,7 +713,7 @@ export async function main(argv = process.argv.slice(2)) {
                     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);
@@ -452,16 +722,27 @@ export async function main(argv = process.argv.slice(2)) {
             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"));
-            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);
+                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.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.
@@ -490,21 +771,13 @@ export async function main(argv = process.argv.slice(2)) {
                     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"));
-            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;
         }
@@ -535,6 +808,7 @@ export async function main(argv = process.argv.slice(2)) {
             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.
@@ -547,7 +821,13 @@ export async function main(argv = process.argv.slice(2)) {
         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.message}`);
@@ -619,7 +899,7 @@ function dogfoodClaudeCode(bundleRoot, dest) {
             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);
@@ -662,7 +942,7 @@ function dogfoodCodex(bundleRoot, dest) {
             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);