@tpsdev-ai/flair 0.48.0 → 0.50.0

package/dist/component-env.js

@@ -214,16 +214,51 @@ export function planComponentEnv(existing, publicUrl) {
     assertNoSecretKeysAdded(existing, text);
     return { action: "added", text, effectiveValue: publicUrl, notices };
 }
+/**
+ * True when `envPath` is inside a `node_modules` tree (any platform separator).
+ *
+ * A `.env` there is not a durable location: it does not exist on a stock npm
+ * install and `npm upgrade` / `flair upgrade` wipes the package directory
+ * (flair#1313). Doctor and deploy must never name that path as the fix.
+ *
+ * Heuristic, not a guarantee: a path segment equal to `node_modules` is treated
+ * as the npm tree. A durable deploy root that happened to use that as a
+ * directory name (e.g. `/opt/my-node_modules-app/flair/.env`) would be
+ * misclassified. That is not a real deployment shape.
+ */
+export function isNodeModulesEnvPath(envPath) {
+    // Path-segment match, not a substring of a filename — still a heuristic.
+    return envPath.split(/[\\/]/).includes("node_modules");
+}
+/**
+ * The location `publicUrlRemedy` names when the component path is inside
+ * `node_modules`. Three durable channels, matching what the deploy actually
+ * reads: the process environment that starts Harper (CLI / launchd / systemd),
+ * or the component `.env` on a Fabric/server deploy (`loadEnv` in config.yaml).
+ */
+export const DURABLE_PUBLIC_URL_LOCATION = "the Flair process environment (launchd EnvironmentVariables, systemd Environment=, " +
+    "or export before flair start/restart) or, on a Fabric/server deploy, the component " +
+    `${COMPONENT_ENV_FILENAME} that Harper's loadEnv plugin reads — never a ${COMPONENT_ENV_FILENAME} ` +
+    "inside node_modules (that path does not exist by default and is wiped on every upgrade)";
 /**
  * The remedy string for a missing/loopback `FLAIR_PUBLIC_URL`. One definition so
  * `flair deploy` and `flair doctor` cannot drift into naming different files.
  *
- * It names all three things an operator needs: the FILE, the KEY, and the fact that
- * the file is only read because config.yaml declares Harper's `loadEnv` plugin —
- * without which the file is present and inert, which is what made flair#1000 hard
- * to see.
+ * When `envPath` is a durable component location (the deploy root, a server
+ * component dir), it names the FILE, the KEY, and the fact that the file is
+ * only read because config.yaml declares Harper's `loadEnv` plugin — without
+ * which the file is present and inert, which is what made flair#1000 hard to
+ * see.
+ *
+ * When `envPath` is inside `node_modules` (a global `npm install -g` package
+ * dir), naming that file would send the operator to a path that does not exist
+ * by default and is destroyed on every upgrade (flair#1313). The remedy then
+ * names the durable process-environment / server-component channels instead.
  */
 export function publicUrlRemedy(envPath, exampleUrl = "https://flair.example.com") {
+    if (isNodeModulesEnvPath(envPath)) {
+        return `set ${PUBLIC_URL_KEY}=${exampleUrl} in ${DURABLE_PUBLIC_URL_LOCATION}, then restart the instance`;
+    }
     return (`set ${PUBLIC_URL_KEY}=${exampleUrl} in ${envPath} (Harper reads a component's ` +
         `${COMPONENT_ENV_FILENAME} only because flair's config.yaml declares the loadEnv plugin, ` +
         `above jsResource), then restart the instance`);
@@ -257,6 +292,19 @@ export function describePublicUrlFinding(input) {
         };
     }
     if (componentEnvValue !== null && !isLoopbackUrl(componentEnvValue)) {
+        if (isNodeModulesEnvPath(componentEnvPath)) {
+            // The value is in an upgrade-wiped location. Naming that path — even to
+            // say "confirm loadEnv" — would send the operator back into node_modules
+            // (flair#1313). Move the value to a durable channel.
+            return {
+                isIssue: true,
+                icon: "error",
+                message: `${PUBLIC_URL_KEY} is set in a ${COMPONENT_ENV_FILENAME} inside the npm package ` +
+                    `directory but discovery still advertises ${advertisedIssuer} — that file is ` +
+                    `wiped on every upgrade and is not a durable location`,
+                fixHint: publicUrlRemedy(componentEnvPath, componentEnvValue),
+            };
+        }
         return {
             isIssue: true,
             icon: "error",

package/dist/deploy.js

@@ -631,9 +631,26 @@ export function publishedEntryNames(packageRoot) {
     }
     // `files` entries are npm patterns; the ones flair uses are plain top-level
     // names, optionally trailing-slashed ("dist/"). Normalise to the entry name.
-    const names = declared
-        .map((f) => String(f).replace(/^\.\//, "").replace(/\/+$/, ""))
-        .filter((f) => f !== "" && !f.includes("*") && !f.startsWith("!"));
+    //
+    // Honourable iff the entry is a plain top-level name. A blacklist of `*` and
+    // `!` lets `?`, `[]`, `{}` (and anything else minimatch understands) through
+    // as a literal that matches no real file — the same silent drop this fix
+    // exists to prevent (Sherlock on #1398). Whitelist: there is no
+    // differently-malformed form that slips through.
+    const names = [];
+    for (const raw of declared) {
+        const f = String(raw).replace(/^\.\//, "").replace(/\/+$/, "");
+        // Empty after normalize (`""`, `./`, `/`) is a listed entry we cannot
+        // honour as a plain top-level name. Skipping it left hasDeclaredFiles
+        // true and shipped only the always-includes — the same silent omit
+        // (Bugbot on #1398).
+        if (f === "." || f === ".." || !/^[a-zA-Z0-9._-]+$/.test(f)) {
+            throw new Error(`Cannot honour files entry ${JSON.stringify(String(raw))}: the deploy payload filter supports plain ` +
+                `top-level entries only. Either simplify the entry, or extend publishedEntryNames() ` +
+                `to match npm pack semantics.`);
+        }
+        names.push(f);
+    }
     return new Set([...names, ...always]);
 }
 /**

package/dist/doctor-client.js

@@ -22,8 +22,8 @@
 import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { ALL_CLIENTS, clientConfigPath } from "./install/clients.js";
-import { FLAIR_MCP_PACKAGE } from "./lib/mcp-spec.js";
+import { ALL_CLIENTS, clientConfigPath, piSettingsPath, resolvePiExtensionPath, scanPiSettings, } from "./install/clients.js";
+import { FLAIR_MCP_PACKAGE, mcpServerSpec } from "./lib/mcp-spec.js";
 // The exact substring `flair init` writes into CLAUDE.md (src/cli.ts, the
 // `init` action) and that the doctor check + fix both key off of.
 export const CLAUDE_MD_BOOTSTRAP_MARKER = "mcp__flair__bootstrap";
@@ -42,9 +42,10 @@ export const SESSION_START_HOOK_MARKER = "flair-session-start";
 //
 // WHY THE INVOCATION IS WRAPPED
 // -----------------------------
-// The hook runs `npx -y -p @tpsdev-ai/flair-mcp flair-session-start`: it resolves
-// a package binary through whatever Node runtime the user's shell happens to
-// expose. Under a Node version manager, globally installed packages are
+// The hook runs `npx -y -p @tpsdev-ai/flair-mcp@<version> flair-session-start`
+// (same mcpServerSpec() pin as `flair init`'s user-local MCP client configs —
+// flair#1143). It resolves a package binary through whatever Node runtime the
+// user's shell happens to expose. Under a Node version manager, globally installed packages are
 // per-runtime-version, so a routine and entirely unrelated runtime upgrade
 // orphans that binary. The command then stops resolving and the harness
 // reports a hook error on EVERY session, indefinitely, in wording that names
@@ -64,7 +65,7 @@ export const SESSION_START_HOOK_MARKER = "flair-session-start";
 // spawns with `shell: true` and never consults $SHELL (verified against the
 // 2.1.220 bundle; the settings schema's claim that `"shell": "bash"` uses your
 // $SHELL is not what the code does on POSIX). So a bare POSIX fragment would
-// in fact be enough for the one harness we support today.
+// in fact be enough for the JSON-command harnesses we support today.
 //
 // It is still wrapped, because this string is not private to that harness:
 // SUPPORTED_HARNESSES (src/hook-install.ts) is a registry meant to grow, and
@@ -118,9 +119,23 @@ export function buildSessionStartHookCommand(agentId, flairUrl) {
         throw new Error(`Flair URL '${flairUrl}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`);
     }
     const env = flairUrl ? `FLAIR_AGENT_ID=${agentId} FLAIR_URL=${flairUrl}` : `FLAIR_AGENT_ID=${agentId}`;
-    const invocation = `${env} npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
+    // Same pin as user-local MCP client configs (mcpServerSpec / flair#907).
+    // Public plugin mcp.json stays unpinned (flair#1308) — that is a scraped
+    // listing, not a machine we just wired.
+    const invocation = `${env} npx -y -p ${mcpServerSpec()} ${SESSION_START_HOOK_MARKER}`;
     return `sh -c 'out=$(${invocation} 2>/dev/null) && printf %s "$out" || true'`;
 }
+/**
+ * The `npx -y -p` invocation that runs `flair-session-start` — pinned
+ * (`@tpsdev-ai/flair-mcp@<ver>`) or the pre-#1143 unpinned form. Used by
+ * `flair hook status` so a freshly-pinned hook is not reported as
+ * hand-edited, and an older unpinned hook is not reported as broken.
+ * Rejects the pre-#1166 form (no `-p`), which runs the MCP shim.
+ */
+export const SESSION_START_HOOK_INVOCATION_RE = /npx -y -p @tpsdev-ai\/flair-mcp(?:@[^\s"']+)? flair-session-start/;
+export function isSessionStartHookInvocation(command) {
+    return typeof command === "string" && SESSION_START_HOOK_INVOCATION_RE.test(command);
+}
 /**
  * Does this command absorb a failure instead of surfacing it? Checked as two
  * independent PROPERTIES (stderr discarded, non-zero exit absorbed) rather
@@ -249,8 +264,8 @@ function continuityEventReport(config, event) {
  * pure fs read, no probe. A missing or unparseable settings.json reads as
  * "absent" (not enabled), matching checkSessionStartHook's tolerance.
  */
-export function checkContinuityCaptureHooks(homeDir) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function checkContinuityCaptureHooks(homeDir, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     let config = {};
     const raw = readTextFile(path);
     if (raw && raw.trim()) {
@@ -610,6 +625,51 @@ function scanCodexFlairBlock(raw) {
     const present = !!agentId;
     return { present, agentId, flairUrl, urlDefaulted: present && !flairUrl };
 }
+export function checkPiFlairWiring(homeDir, cwd) {
+    const userPath = withHome(homeDir, () => piSettingsPath());
+    const files = [
+        // pi resolves user-scope relative paths against the agent dir (the
+        // settings file's own directory), project-scope against the project dir.
+        { path: userPath, baseDir: dirname(userPath) },
+    ];
+    if (cwd)
+        files.push({ path: join(cwd, ".pi", "settings.json"), baseDir: cwd });
+    const report = {
+        settingsPath: userPath,
+        checked: [],
+        wired: false,
+        wiredVia: null,
+        pinnedVersion: null,
+        misconfigured: [],
+    };
+    for (const file of files) {
+        const raw = readTextFile(file.path);
+        report.checked.push({ path: file.path, exists: raw !== null });
+        const scan = scanPiSettings(raw);
+        for (const entry of scan.misconfiguredNpmUnderExtensions) {
+            report.misconfigured.push({ path: file.path, entry });
+        }
+        if (report.wired)
+            continue; // first wiring found wins; keep collecting traps
+        if (scan.packagesSpec) {
+            report.wired = true;
+            report.wiredVia = "packages";
+            report.wiredIn = file.path;
+            report.spec = scan.packagesSpec;
+            report.pinnedVersion = scan.pinnedVersion;
+            continue;
+        }
+        if (scan.extensionFilePaths.length > 0) {
+            const entry = scan.extensionFilePaths[0];
+            report.wired = true;
+            report.wiredVia = "extension-path";
+            report.wiredIn = file.path;
+            report.spec = entry;
+            report.extensionPathExists = existsSync(resolvePiExtensionPath(entry, homeDir, file.baseDir));
+        }
+    }
+    return report;
+}
 // ── check 2: FLAIR_URL to use when (re-)wiring a client (flair#727) ────────
 /**
  * Pick the FLAIR_URL to feed a wire() call when `doctor --fix` re-wires a
@@ -683,12 +743,14 @@ export function fixClaudeMdBootstrap(cwd) {
     }
 }
 /**
- * Pass when ~/.claude/settings.json exists, parses as JSON, and ANY hook
+ * Pass when the harness settings file exists, parses as JSON, and ANY hook
  * command anywhere under hooks.SessionStart[*].hooks[*].command contains the
  * flair-session-start marker (see docs/mcp-clients.md for the exact shape).
+ * `settingsPath` defaults to ~/.claude/settings.json; pass the Codex
+ * `~/.codex/hooks.json` path (or any other hookSettingsPath) for that harness.
  */
-export function checkSessionStartHook(homeDir) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function checkSessionStartHook(homeDir, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     const raw = readTextFile(path);
     if (!raw || !raw.trim())
         return { present: false, path };
@@ -727,10 +789,9 @@ export function checkSessionStartHook(homeDir) {
  * command. Returns the version when the spec is written
  * `@tpsdev-ai/flair-mcp@<ver>`; null for a bare/unpinned spec.
  *
- * The SessionStart hook is deliberately unpinned (`npx -y -p
- * @tpsdev-ai/flair-mcp`, buildSessionStartHookCommand above), so a hook
- * establishes that flair-mcp is wired but never carries a version — the pin
- * comes from the client MCP config.
+ * SessionStart hooks written since flair#1143 carry the same pin as a
+ * client MCP config (`mcpServerSpec()`). A pre-#1143 unpinned hook still
+ * establishes that flair-mcp is wired but contributes no version.
  */
 export function extractFlairMcpPin(text) {
     if (typeof text !== "string")
@@ -755,27 +816,39 @@ export function detectWiredFlairMcp(homeDir) {
                 pinnedVersion = pin;
         }
     };
-    // 1. The SessionStart hook (claude-code). Establishes wiring; unpinned by design.
-    const hook = checkSessionStartHook(homeDir);
-    if (hook.present && isFlairHookCommand(hook.command ?? ""))
-        note(hook.command);
-    // 2. Every known client's MCP config — a wired flair block carries the spec.
+    // 1. Every known client's MCP config — a wired flair block carries the spec.
+    //    Scanned first so a client pin wins (see module note above).
     for (const client of ALL_CLIENTS) {
         const configPath = withHome(homeDir, () => clientConfigPath(client.id));
         note(readTextFile(configPath));
     }
+    // 2. SessionStart hooks (claude-code settings.json + Codex hooks.json).
+    //    Establish wiring; may carry a pin, but NEVER override a client pin
+    //    already taken above — `note()` only sets pinnedVersion when it is still
+    //    unset, so THIS ORDERING IS THE PRECEDENCE RULE, not decoration. The
+    //    Codex path is additive (flair#1148); it must not reorder these two steps.
+    //    Paths match hookSettingsPath in src/hook-install.ts — listed here to
+    //    avoid a cycle (hook-install already imports this module).
+    for (const hookPath of [
+        join(homeDir, ".claude", "settings.json"),
+        join(homeDir, ".codex", "hooks.json"),
+    ]) {
+        const hook = checkSessionStartHook(homeDir, hookPath);
+        if (hook.present && isFlairHookCommand(hook.command ?? ""))
+            note(hook.command);
+    }
     return { wired, pinnedVersion };
 }
 /**
- * Merge-safe insert of a Flair SessionStart hook group into
- * ~/.claude/settings.json — creates the file/array if absent, preserves any
- * other existing hooks/keys (read-parse-merge-write, mirroring wireJsonMcp's
- * merge safety in src/install/clients.ts; never a blind overwrite). Dedupes:
- * a no-op (ok:true) if a matching hook is already present, so it's safe to
- * call twice.
+ * Merge-safe insert of a Flair SessionStart hook group into the harness
+ * settings file (default ~/.claude/settings.json) — creates the file/array
+ * if absent, preserves any other existing hooks/keys (read-parse-merge-write,
+ * mirroring wireJsonMcp's merge safety in src/install/clients.ts; never a
+ * blind overwrite). Dedupes: a no-op (ok:true) if a matching hook is already
+ * present, so it's safe to call twice.
  */
-export function fixSessionStartHook(homeDir, agentId) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function fixSessionStartHook(homeDir, agentId, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     if (!agentId) {
         return {
             ok: false,
@@ -908,7 +981,7 @@ export function classifyHookProbe(outcome) {
  * (or null via `{ probe: false }`) to keep a caller hermetic.
  */
 export function inspectSessionStartHook(homeDir, opts = {}) {
-    const found = checkSessionStartHook(homeDir);
+    const found = checkSessionStartHook(homeDir, opts.settingsPath);
     if (!found.present || !found.command) {
         return { path: found.path, present: false, ours: false, silenced: false, upgradable: false, execution: null };
     }
@@ -950,8 +1023,8 @@ export function classifyHookReadiness(report) {
  * decision to un-wire ambient memory, and `flair hook uninstall` is the
  * command for that when the user does decide.
  */
-export function upgradeSessionStartHookCommand(homeDir) {
-    const path = join(homeDir, ".claude", "settings.json");
+export function upgradeSessionStartHookCommand(homeDir, settingsPath) {
+    const path = settingsPath ?? join(homeDir, ".claude", "settings.json");
     try {
         const raw = readTextFile(path);
         if (!raw || !raw.trim())

package/dist/federation/scheduler.js

@@ -62,7 +62,7 @@ import { resolve, dirname } from "node:path";
 import { homedir } from "node:os";
 import { fileURLToPath } from "node:url";
 import { escapeXml } from "../lib/xml-escape.js";
-import { detectPlatform as detectPlatformFor, spawnReport, readTemplate, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, verifyFirstRun, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, resolveFlairBin, formatFlairBinWarning, verifyFirstRun, probeUserLingerEnabled, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
 export const LAUNCHD_LABEL = "dev.flair.federation.sync";
 export const SYSTEMD_TIMER_UNIT = "flair-federation-sync.timer";
 export const SYSTEMD_SERVICE_UNIT = "flair-federation-sync.service";
@@ -165,7 +165,8 @@ function launchdDomain() {
  */
 export function enableScheduler(opts) {
     const plat = detectPlatform(opts.platformOverride);
-    const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const resolvedFlair = resolveFlairBin(opts.flairBin);
+    const flairBin = resolvedFlair.path;
     const nodeBin = resolveNodeBin(opts.nodeBin);
     const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
     const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
@@ -221,6 +222,7 @@ export function enableScheduler(opts) {
         return {
             platform: plat, shimPath, schedulerPath: plistPath, intervalSeconds: opts.intervalSeconds,
             loadCommand, loadResult, firstRunVerified: firstRun?.verified === true, firstRun,
+            flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
         };
     }
     // Linux: systemd user units.
@@ -249,6 +251,7 @@ export function enableScheduler(opts) {
     return {
         platform: plat, shimPath, schedulerPath: timerPath, intervalSeconds: opts.intervalSeconds,
         loadCommand, loadResult, firstRunVerified: firstRun?.verified === true, firstRun,
+        flairBin, flairBinCanonical: resolvedFlair.canonical, flairBinPublic: resolvedFlair.publicBin,
     };
 }
 /** Removes the scheduler entry. Peer records and sync history are untouched. */
@@ -485,6 +488,15 @@ export function assessDriver(input) {
  * asked for — a sync run through the service manager — has been observed to
  * happen once.
  */
+function appendFlairBinWarning(lines, r) {
+    if (r.flairBinCanonical !== false || !r.flairBin)
+        return;
+    const warning = formatFlairBinWarning(r.flairBin, r.flairBinPublic ?? null, "flair federation sync enable");
+    if (warning.length === 0)
+        return;
+    lines.push("");
+    lines.push(...warning);
+}
 export function formatEnableReport(r, input) {
     const activationFailed = !!r.loadResult && r.loadResult.code !== 0;
     const credLine = input.adminPassFile
@@ -504,11 +516,18 @@ export function formatEnableReport(r, input) {
         lines.push(`   Activation:  ${r.loadCommand.join(" ")} → code ${lr.code}`);
         if (lr.stderr)
             lines.push(`     stderr: ${lr.stderr.trim()}`);
-        const remedy = describeLoadFailureFor(r.platform, lr, "flair federation sync enable");
+        const lingerEnabled = input.lingerEnabled !== undefined
+            ? input.lingerEnabled
+            : (r.platform === "linux" ? (input.probeLinger ?? probeUserLingerEnabled)() : undefined);
+        const remedy = describeLoadFailureFor(r.platform, lr, "flair federation sync enable", {
+            lingerEnabled,
+            env: input.env,
+        });
         lines.push("");
         lines.push(remedy ? `   ${remedy}` : `   Re-run the activation command above manually to see the full diagnostic.`);
         lines.push("");
         lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair federation sync status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     if (!r.firstRunVerified) {
@@ -561,6 +580,7 @@ export function formatEnableReport(r, input) {
         }
         lines.push("");
         lines.push(`   Check anytime with: flair federation sync status`);
+        appendFlairBinWarning(lines, r);
         return { lines, ok: false };
     }
     const lines = [
@@ -579,6 +599,7 @@ export function formatEnableReport(r, input) {
     lines.push(`Confirm anytime with \`flair federation status\`,`);
     lines.push(`which reports whether anything is actually driving sync.`);
     lines.push(`Disable with \`flair federation sync disable\`.`);
+    appendFlairBinWarning(lines, r);
     return { lines, ok: true };
 }
 /** Formats the `flair federation sync status` report. */

package/dist/hook-install.js

@@ -54,12 +54,13 @@
 //      reuses bootstrap's own maxTokens machinery.
 import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
-import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, buildContinuityCaptureHookCommand, checkContinuityCaptureHooks, computeContinuityHookInstall, computeContinuityHookRemoval, hookCommandIsSilenced, isHookCommandValueSafe, } from "./doctor-client.js";
+import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, buildContinuityCaptureHookCommand, checkContinuityCaptureHooks, computeContinuityHookInstall, computeContinuityHookRemoval, hookCommandIsSilenced, isHookCommandValueSafe, isSessionStartHookInvocation, readClientMcpBlock, } from "./doctor-client.js";
 // ── harness registry ────────────────────────────────────────────────────────
-/** v1 supports exactly one harness. The flag/type exist so a second harness
- *  is an additive registry entry, not a rewrite (Kern's #719 verdict: "a
- *  switch statement... is fine until we have 3+ harnesses"). */
-export const SUPPORTED_HARNESSES = ["claude-code"];
+/** SessionStart hook harnesses. A second harness is an additive registry
+ *  entry, not a rewrite (Kern's #719 verdict: "a switch statement... is
+ *  fine until we have 3+ harnesses"). Codex writes the same JSON hook
+ *  schema Claude Code uses, into `~/.codex/hooks.json` (flair#1148). */
+export const SUPPORTED_HARNESSES = ["claude-code", "codex"];
 export function isSupportedHarness(value) {
     return SUPPORTED_HARNESSES.includes(value);
 }
@@ -70,8 +71,37 @@ export function hookSettingsPath(homeDir, harness) {
     switch (harness) {
         case "claude-code":
             return join(homeDir, ".claude", "settings.json");
+        case "codex":
+            return join(homeDir, ".codex", "hooks.json");
     }
 }
+/** Continuity capture (PostToolUse + Stop) is Claude Code only. The matcher
+ *  is Claude tool names; writing it into another harness looks enabled and
+ *  never journals (flair#1148 Bugbot). SessionStart stays per-harness. */
+export function harnessSupportsContinuity(harness) {
+    return harness === "claude-code";
+}
+/** Status/doctor hint for `flair hook install`. Claude Code stays the bare
+ *  default; every other harness is named so the hint cannot silently write
+ *  the wrong file (flair#1148 Bugbot). */
+export function hookInstallHint(harness, extraFlags = "") {
+    const parts = ["flair hook install"];
+    if (extraFlags)
+        parts.push(extraFlags);
+    if (harness !== "claude-code")
+        parts.push(`--harness ${harness}`);
+    return parts.join(" ");
+}
+/** Agent id for a hook install: flag, env, this harness's MCP block, then
+ *  Claude Code's block as a last resort (same agent is often shared). */
+export function resolveHookAgentId(opts, homeDir, harness) {
+    return (opts.agent ||
+        opts.agentId ||
+        process.env.FLAIR_AGENT_ID ||
+        readClientMcpBlock(harness, homeDir).agentId ||
+        (harness !== "claude-code" ? readClientMcpBlock("claude-code", homeDir).agentId : undefined) ||
+        undefined);
+}
 /** Backup path convention: a single sibling `<path>.bak`, overwritten on
  *  every mutating run — recovery insurance for the mutation that's about to
  *  happen, not a version history. Exported so tests assert against the same
@@ -94,14 +124,62 @@ export function hookBackupPath(settingsPath) {
 export function buildHookCommand(agentId, flairUrl) {
     return buildSessionStartHookCommand(agentId, flairUrl);
 }
+/**
+ * Peel the installer `sh -c '...'` wrapper (and its `out=$(...)` capture)
+ * so env assignments can be read from the inner invocation. Leaves a bare
+ * command (legacy pre-#1007, hand-rolled) unchanged. Never throws.
+ */
+function unwrapInstallerHookCommand(command) {
+    const shc = command.match(/^sh\s+-c\s+(['"])([\s\S]*)\1\s*$/);
+    const body = shc ? shc[2] : command;
+    // SessionStart installer: `out=$(<invocation> 2>/dev/null) && printf ...`
+    const captured = body.match(/^out=\$\((.*)\)\s*&&/);
+    return captured ? captured[1] : body;
+}
+/** Env values the installer interpolates are allow-listed (see
+ *  isHookCommandValueSafe). Stop before whitespace or the shell
+ *  metacharacters the `$(...)` wrapper can leave adjacent to a value. */
+const HOOK_ENV_VALUE_RE = /[^\s'"$();|&<>]+/;
 /** Best-effort recovery of the agentId/flairUrl a previously-wired hook
- *  command carries — used by `flair hook status`. Pure string scan, never
- *  throws on an unexpected shape. */
+ *  command carries — used by `flair hook status`. Understands the
+ *  installer-written `sh -c` wrapper (`flair init`, `flair hook install`,
+ *  docs/mcp-clients.md) as well as a bare invocation. Pure string scan,
+ *  never throws on an unexpected shape. A missing FLAIR_URL is not a
+ *  parse failure: `flair init` / doctor's minimal shape omit it on
+ *  purpose (the hook then uses flair-client's localhost default). */
 export function parseHookCommandEnv(command) {
-    const agentMatch = command.match(/FLAIR_AGENT_ID=(\S+)/);
-    const urlMatch = command.match(/FLAIR_URL=(\S+)/);
+    const source = unwrapInstallerHookCommand(command);
+    const agentMatch = source.match(new RegExp(`FLAIR_AGENT_ID=(${HOOK_ENV_VALUE_RE.source})`));
+    const urlMatch = source.match(new RegExp(`FLAIR_URL=(${HOOK_ENV_VALUE_RE.source})`));
     return { agentId: agentMatch?.[1], flairUrl: urlMatch?.[1] };
 }
+/** Printed by `flair hook status` only when the command is wired but its
+ *  agent/URL really could not be recovered — never for the installer
+ *  `sh -c` form that simply omits FLAIR_URL (flair#1325). */
+export const HOOK_STATUS_UNPARSED = "(unknown — could not parse command)";
+/** Agent / Flair URL lines `flair hook status` prints under a wired hook.
+ *  Recovered values are shown. The installer-no-URL omit (flair#1325) is
+ *  allowed ONLY when agentId was parsed — that is the real `flair init`
+ *  shape (`FLAIR_AGENT_ID` set, `FLAIR_URL` omitted). correctShape alone
+ *  is not enough: it is an npx-invocation check and a wired correct-shape
+ *  command with no env assignments must still show the unknown lines,
+ *  not a silent all-clear. */
+export function hookStatusIdentityLines(status) {
+    const lines = [];
+    if (status.agentId) {
+        lines.push({ label: "Agent", value: status.agentId });
+    }
+    else {
+        lines.push({ label: "Agent", value: HOOK_STATUS_UNPARSED });
+    }
+    if (status.flairUrl) {
+        lines.push({ label: "Flair URL", value: status.flairUrl });
+    }
+    else if (!status.agentId) {
+        lines.push({ label: "Flair URL", value: HOOK_STATUS_UNPARSED });
+    }
+    return lines;
+}
 function makeHookGroup(command) {
     return { hooks: [{ type: "command", command }] };
 }
@@ -344,7 +422,7 @@ export function hookStatus(homeDir, harness) {
     }
     const hookEntry = config.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex];
     const command = typeof hookEntry?.command === "string" ? hookEntry.command : "";
-    const correctShape = hookEntry?.type === "command" && command.includes(`npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
+    const correctShape = hookEntry?.type === "command" && isSessionStartHookInvocation(command);
     const env = parseHookCommandEnv(command);
     return {
         harness, path, wired: true, correctShape,
@@ -377,6 +455,13 @@ export function installContinuityHooks(opts) {
     const { homeDir, harness, agentId, flairUrl } = opts;
     const dryRun = !!opts.dryRun;
     const path = hookSettingsPath(homeDir, harness);
+    if (!harnessSupportsContinuity(harness)) {
+        return {
+            ok: false, path, harness, dryRun,
+            message: `continuity capture is Claude Code only — ${harness} has no PostToolUse/Stop matcher Flair can journal (SessionStart is still ${hookInstallHint(harness)})`,
+            backupPath: null, actions: null,
+        };
+    }
     for (const [label, value] of [["agent id", agentId], ["Flair URL", flairUrl]]) {
         if (!isHookCommandValueSafe(value)) {
             return {
@@ -494,10 +579,5 @@ export function uninstallContinuityHooks(opts) {
 /** Read-only continuity status for `flair hook status` — the same report
  *  doctor's check consumes, resolved through the harness's settings path. */
 export function continuityHookStatus(homeDir, harness) {
-    // hookSettingsPath and checkContinuityCaptureHooks both resolve
-    // ~/.claude/settings.json from homeDir; asserting through the harness
-    // registry keeps a future second harness from silently reading the wrong
-    // file.
-    void hookSettingsPath(homeDir, harness);
-    return checkContinuityCaptureHooks(homeDir);
+    return checkContinuityCaptureHooks(homeDir, hookSettingsPath(homeDir, harness));
 }