@tpsdev-ai/flair 0.32.0 → 0.34.0

package/dist/doctor-client.js

@@ -7,15 +7,19 @@
 // but no CLAUDE.md line; or no SessionStart hook) that silently no-op, with
 // no way to tell "is Flair working for my agent?" short of an incident.
 //
-// This module is pure filesystem logic (no network, no crypto) so it's fast
-// and fully unit-testable in isolation — mirrors test/unit/client-wiring.test.ts's
+// This module is filesystem logic (no network, no crypto) so it's fast and
+// fully unit-testable in isolation — mirrors test/unit/client-wiring.test.ts's
 // technique of overriding process.env.HOME to a temp dir. The two
 // network-dependent checks (reachability + agent registration) live in
-// src/cli.ts alongside authFetch/resolveKeyPath, which they reuse.
+// src/cli.ts alongside authFetch/resolveKeyPath, which they reuse. The one
+// exception to "filesystem only" is probeSessionStartHookCommand (flair#1007),
+// which spawns a bounded subprocess — it takes an injectable runner so every
+// caller in the test suite stays hermetic.
 //
 // Every read here is try/catch-wrapped: a missing or malformed config file is
 // "not present", never a thrown error — doctor must never crash or hang on a
 // broken client config.
+import { spawnSync } from "node:child_process";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { dirname, join } from "node:path";
 import { clientConfigPath } from "./install/clients.js";
@@ -26,6 +30,129 @@ const CLAUDE_MD_BOOTSTRAP_LINE = "At the start of every session, run mcp__flair_
 // The exact substring identifying a Flair SessionStart hook command (see
 // docs/mcp-clients.md "Auto-recall on session start").
 export const SESSION_START_HOOK_MARKER = "flair-session-start";
+// ── the canonical SessionStart hook command (flair#1007) ───────────────────
+//
+// ONE builder, three call sites: `flair doctor --fix` (fixSessionStartHook),
+// `flair init`'s copy-paste hint (sessionStartHookHint), and `flair hook
+// install` (src/hook-install.ts's buildHookCommand, which delegates here).
+// Before #1007 each of those carried its own literal copy of the string, so a
+// change to the invocation's failure behaviour had to be made in three places
+// and could be tested in none of them.
+//
+// WHY THE INVOCATION IS WRAPPED
+// -----------------------------
+// The hook runs `npx -y @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
+// 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
+// neither Flair nor a remedy. It also outlives Flair itself: uninstalling the
+// CLI does not remove the hook, so the error survives the tool it exists to
+// serve (flair#1007).
+//
+// packages/flair-mcp/src/session-start-hook.ts already guarantees
+// no-op-on-any-failure — but that guarantee lives INSIDE the binary which, in
+// this failure, never runs. The guard is behind the door it is meant to guard.
+// The only layer that still exists when the binary does not is the command
+// string itself, so that is where the silence has to be enforced.
+//
+// WHY `sh -c '...'` RATHER THAN A BARE FRAGMENT
+// ---------------------------------------------
+// Claude Code runs a `type: "command"` hook as `/bin/sh -c "<command>"` — it
+// 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.
+//
+// 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
+// docs/mcp-clients.md publishes this exact command for hand-wiring. Measured
+// across sh, bash, zsh, dash, ksh, fish and tcsh:
+//   - the wrapped form is uniform — stdout passed through byte-for-byte on
+//     success; empty stdout, empty stderr and exit 0 on every failure;
+//   - a bare `out=$(...) && ... || true` fragment is a SYNTAX ERROR in fish and
+//     csh/tcsh — silent on some shells, LOUDER than before on others, which is
+//     not a fix;
+//   - the unwrapped pre-#1007 command is already broken outright in csh/tcsh
+//     ("FLAIR_AGENT_ID=me: Command not found."), which the wrapper fixes.
+// The cost is one extra process at session start; the benefit is that the
+// silence is a property of the string rather than of who runs it.
+//
+// WHY STDOUT IS CAPTURED, NOT JUST STDERR DISCARDED
+// -------------------------------------------------
+// Exit code alone is not the whole surface. In the same bundle, a SessionStart
+// hook's stdout is consumed two ways EVEN AT EXIT 0:
+//   - stdout that does not start with `{` is injected into the model's context
+//     verbatim, as a `<hook> hook success: <stdout>` meta message;
+//   - stdout that starts with `{` but fails to parse/validate is reported as a
+//     hook error — at exit 0, presented as exit 1.
+// So a failing resolver that happens to print on stdout would either become
+// silently injected context or produce the exact error class this issue is
+// about, no matter what the exit code says. Capturing stdout and emitting it
+// only on success closes both; discarding stderr alone would close neither.
+/**
+ * Values interpolated into the hook command are constrained by a strict
+ * allow-list rather than escaped. The command is a single-quoted `sh -c`
+ * argument and correct single-quote escaping is NOT uniform across the shells
+ * above (fish and csh disagree with POSIX), so "cannot contain a quote" is
+ * enforced by shape instead of handled by quoting. This is also strictly
+ * safer than the pre-#1007 command, where an agent id containing a space or a
+ * `;` was a command injection into the user's settings file.
+ */
+const HOOK_VALUE_SAFE_RE = /^[A-Za-z0-9._:/-]+$/;
+export function isHookCommandValueSafe(value) {
+    return typeof value === "string" && HOOK_VALUE_SAFE_RE.test(value);
+}
+/**
+ * Build the exact `command` string to register as a SessionStart hook.
+ * Throws (rather than emitting a quoted approximation) when a value cannot be
+ * represented safely — see HOOK_VALUE_SAFE_RE.
+ */
+export function buildSessionStartHookCommand(agentId, flairUrl) {
+    if (!isHookCommandValueSafe(agentId)) {
+        throw new Error(`agent id '${agentId}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`);
+    }
+    if (flairUrl != null && flairUrl !== "" && !isHookCommandValueSafe(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 @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
+    return `sh -c 'out=$(${invocation} 2>/dev/null) && printf %s "$out" || true'`;
+}
+/**
+ * Does this command absorb a failure instead of surfacing it? Checked as two
+ * independent PROPERTIES (stderr discarded, non-zero exit absorbed) rather
+ * than by string equality with what we currently emit, so a hand-rolled
+ * command that genuinely achieves both is not nagged about.
+ */
+export function hookCommandIsSilenced(command) {
+    if (typeof command !== "string")
+        return false;
+    const discardsStderr = command.includes("2>/dev/null") || command.includes("2>&-");
+    const absorbsFailure = /\|\|\s*(?:true|:)(?:\s|'|$)/.test(command) || /;\s*(?:true|:)\s*'?\s*$/.test(command);
+    return discardsStderr && absorbsFailure;
+}
+/**
+ * The EXACT unwrapped shape Flair wrote before #1007. Recognising it precisely
+ * (not "anything containing the marker") is what lets `flair doctor --fix`
+ * upgrade a hook we know we authored while never rewriting one a user placed
+ * or edited themselves.
+ */
+const LEGACY_SESSION_START_HOOK_RE = /^FLAIR_AGENT_ID=([^\s'"]+)(?: FLAIR_URL=([^\s'"]+))? npx -y @tpsdev-ai\/flair-mcp flair-session-start$/;
+export function parseLegacySessionStartHookCommand(command) {
+    if (typeof command !== "string")
+        return null;
+    const m = command.trim().match(LEGACY_SESSION_START_HOOK_RE);
+    if (!m)
+        return null;
+    return { agentId: m[1], flairUrl: m[2] };
+}
+/** Does this command invoke the Flair adapter at all (pinned or not)? Only
+ *  such a command is ever probed or rewritten. */
+export function isFlairHookCommand(command) {
+    return typeof command === "string" && command.includes("@tpsdev-ai/flair-mcp") && command.includes(SESSION_START_HOOK_MARKER);
+}
 // ── shared helpers ──────────────────────────────────────────────────────────
 /**
  * Run `fn` with process.env.HOME temporarily pointed at `homeDir`, then
@@ -228,7 +355,7 @@ export function checkSessionStartHook(homeDir) {
                 continue;
             for (const hook of hooks) {
                 if (typeof hook?.command === "string" && hook.command.includes(SESSION_START_HOOK_MARKER)) {
-                    return { present: true, path };
+                    return { present: true, path, command: hook.command };
                 }
             }
         }
@@ -255,6 +382,13 @@ export function fixSessionStartHook(homeDir, agentId) {
             message: "no agent id known — pass --agent <id> (or set FLAIR_AGENT_ID) so doctor knows which agent to wire the hook to",
         };
     }
+    if (!isHookCommandValueSafe(agentId)) {
+        return {
+            ok: false,
+            path,
+            message: `agent id '${agentId}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`,
+        };
+    }
     try {
         let config = {};
         const raw = readTextFile(path);
@@ -271,7 +405,7 @@ export function fixSessionStartHook(homeDir, agentId) {
             hooks: [
                 {
                     type: "command",
-                    command: `FLAIR_AGENT_ID=${agentId} npx -y @tpsdev-ai/flair-mcp flair-session-start`,
+                    command: buildSessionStartHookCommand(agentId),
                 },
             ],
         });
@@ -284,6 +418,172 @@ export function fixSessionStartHook(homeDir, agentId) {
         return { ok: false, path, message: `could not write ${path}: ${reason}` };
     }
 }
+/** Default probe budget. Generous: a cold `npx` may have to reach the registry
+ *  before it can answer, and a slow answer must never be reported as a broken
+ *  hook — that is what the "unknown" verdict is for. */
+export const HOOK_PROBE_TIMEOUT_MS = 20_000;
+/** Package-manager chatter that is never the reason a hook failed. The harness
+ *  itself reports the FIRST stderr line, which on a modern npm is one of these
+ *  — so doctor deliberately does better than repeating the symptom back. */
+const NOISE_LINE_RE = /^(?:npm|yarn|pnpm|bun)\s+(?:notice|warn|info|http|verb)\b/i;
+/** The most informative single line of a failed probe's output. */
+export function evidenceLine(s, max = 200) {
+    const lines = (s || "").split("\n").map((l) => l.trim()).filter((l) => l.length > 0);
+    const line = lines.find((l) => !NOISE_LINE_RE.test(l)) ?? lines[0] ?? "";
+    return line.length > max ? `${line.slice(0, max - 1)}…` : line;
+}
+const defaultProbeRunner = (command, timeoutMs) => {
+    // `/bin/sh -c` is not a guess: it is exactly how Claude Code runs a
+    // `type: "command"` hook (spawn with `shell: true`, $SHELL never consulted).
+    // Probing through any other shell would answer a question the user never
+    // asked.
+    const res = spawnSync("/bin/sh", ["-c", command], {
+        input: "",
+        encoding: "utf-8",
+        timeout: timeoutMs,
+        env: {
+            ...process.env,
+            // Tell a #1007-or-later adapter to answer without side effects.
+            FLAIR_HOOK_PROBE: "1",
+            // Bound an OLDER adapter, which will do a real bootstrap + presence
+            // heartbeat because it has never heard of FLAIR_HOOK_PROBE.
+            FLAIR_HOOK_TIMEOUT_MS: "1500",
+            FLAIR_PRESENCE_TIMEOUT_MS: "500",
+        },
+    });
+    const timedOut = res.signal === "SIGTERM" && res.status === null;
+    return {
+        exitCode: res.status,
+        stdout: res.stdout ?? "",
+        stderr: res.stderr ?? "",
+        timedOut,
+        spawnError: res.error && !timedOut ? res.error.message : null,
+    };
+};
+/**
+ * Run a registered hook command once, bounded, with probe-mode env set.
+ * Only ever called for commands isFlairHookCommand() recognises — doctor does
+ * not execute a stranger's hook to find out what it does.
+ */
+export function probeSessionStartHookCommand(command, opts = {}) {
+    const timeoutMs = opts.timeoutMs ?? HOOK_PROBE_TIMEOUT_MS;
+    const runner = opts.runner ?? defaultProbeRunner;
+    try {
+        return runner(command, timeoutMs);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { exitCode: null, stdout: "", stderr: "", timedOut: false, spawnError: reason };
+    }
+}
+/** Pure: probe outcome -> verdict. See the section doc for why "exit 0, no
+ *  output" is a definite failure rather than an ambiguous one. */
+export function classifyHookProbe(outcome) {
+    if (outcome.timedOut) {
+        return { execution: "unknown", detail: "the command did not answer in time" };
+    }
+    if (outcome.spawnError) {
+        return { execution: "unknown", detail: `could not run the command (${outcome.spawnError})` };
+    }
+    if (outcome.exitCode !== 0) {
+        const evidence = evidenceLine(outcome.stderr) || evidenceLine(outcome.stdout);
+        return {
+            execution: "broken",
+            detail: evidence ? `exited ${outcome.exitCode}: ${evidence}` : `exited ${outcome.exitCode}`,
+        };
+    }
+    if (!outcome.stdout.trim()) {
+        return {
+            execution: "broken",
+            detail: "the command produced no output — the flair-session-start binary never ran",
+        };
+    }
+    return { execution: "runs" };
+}
+/**
+ * Full report for the registered hook: presence (as before), plus whether its
+ * command still executes and whether it would fail quietly if it stopped.
+ * `probe` is injectable and defaults to the real bounded spawn; pass a stub
+ * (or null via `{ probe: false }`) to keep a caller hermetic.
+ */
+export function inspectSessionStartHook(homeDir, opts = {}) {
+    const found = checkSessionStartHook(homeDir);
+    if (!found.present || !found.command) {
+        return { path: found.path, present: false, ours: false, silenced: false, upgradable: false, execution: null };
+    }
+    const command = found.command;
+    const ours = isFlairHookCommand(command);
+    const silenced = hookCommandIsSilenced(command);
+    const upgradable = parseLegacySessionStartHookCommand(command) !== null;
+    if (!ours || opts.probe === false) {
+        return { path: found.path, present: true, command, ours, silenced, upgradable, execution: null };
+    }
+    const outcome = probeSessionStartHookCommand(command, {
+        timeoutMs: opts.timeoutMs,
+        runner: opts.probe || undefined,
+    });
+    const verdict = classifyHookProbe(outcome);
+    return { path: found.path, present: true, command, ours, silenced, upgradable, execution: verdict.execution, detail: verdict.detail };
+}
+/**
+ * Rewrite an existing Flair-authored hook command to the current canonical
+ * form, in place, preserving the agent id and URL the entry already carries —
+ * so this never needs --agent and never re-points a hook at a different agent.
+ *
+ * Deliberately narrow: it refuses unless the registered command is the EXACT
+ * unwrapped string Flair used to write. A hook the user hand-wrote or pinned
+ * is theirs; doctor reports on it and leaves it alone. And it never REMOVES a
+ * hook — an unresolvable command is an environment that changed, not a
+ * 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");
+    try {
+        const raw = readTextFile(path);
+        if (!raw || !raw.trim())
+            return { ok: false, path, changed: false, message: `no ${path} to update` };
+        const config = JSON.parse(raw);
+        const groups = config?.hooks?.SessionStart;
+        if (!Array.isArray(groups))
+            return { ok: false, path, changed: false, message: `no SessionStart hooks in ${path}` };
+        for (const group of groups) {
+            const hooks = group?.hooks;
+            if (!Array.isArray(hooks))
+                continue;
+            for (const hook of hooks) {
+                if (typeof hook?.command !== "string" || !hook.command.includes(SESSION_START_HOOK_MARKER))
+                    continue;
+                // Already absorbing its own failures — nothing to repair, whether we
+                // wrote it or the user did. Checked BEFORE the legacy match so a second
+                // run is a clean no-op rather than "that isn't the command we wrote".
+                if (hookCommandIsSilenced(hook.command)) {
+                    return { ok: true, path, changed: false, message: `SessionStart hook in ${path} is already current` };
+                }
+                const legacy = parseLegacySessionStartHookCommand(hook.command);
+                if (!legacy) {
+                    return {
+                        ok: false,
+                        path,
+                        changed: false,
+                        message: `the SessionStart hook in ${path} is not the command Flair wrote — leaving it untouched`,
+                    };
+                }
+                const next = buildSessionStartHookCommand(legacy.agentId, legacy.flairUrl);
+                if (next === hook.command)
+                    return { ok: true, path, changed: false, message: `SessionStart hook in ${path} is already current` };
+                hook.command = next;
+                writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+                return { ok: true, path, changed: true, message: `rewrote the SessionStart hook in ${path} so a failure to resolve stays silent` };
+            }
+        }
+        return { ok: false, path, changed: false, message: `no Flair SessionStart hook found in ${path}` };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { ok: false, path, changed: false, message: `could not update ${path}: ${reason}` };
+    }
+}
 function indentLines(s) {
     return s
         .split("\n")
@@ -315,7 +615,9 @@ function sessionStartHookHint(agentId, path) {
                     hooks: [
                         {
                             type: "command",
-                            command: `FLAIR_AGENT_ID=${agentId} npx -y @tpsdev-ai/flair-mcp flair-session-start`,
+                            command: isHookCommandValueSafe(agentId)
+                                ? buildSessionStartHookCommand(agentId)
+                                : buildSessionStartHookCommand("me"),
                         },
                     ],
                 },
@@ -420,6 +722,27 @@ export function fixCommandAgentHint(keyAgentIds) {
         return "";
     return ` --agent ${[...keyAgentIds].sort()[0]}`;
 }
+/**
+ * The remedy line to print under doctor's "Embeddings: not verified" warning,
+ * or null when no remedy applies (flair#1023 requirement 4).
+ *
+ * doctor used to print "Pass --agent <id> ..." for EVERY skip reason. That
+ * sentence only fixes the two cases where no agent identity was resolved. It
+ * cannot fix a key that will not decode — following it produces the identical
+ * error — and it cannot fix an HTTP failure from the probe itself. Printing a
+ * remedy that provably will not change the outcome spends the operator's time
+ * and is worse than printing nothing, so those cases now print nothing.
+ */
+export function embeddingsSkipRemedy(reason) {
+    switch (reason) {
+        case "no-agent":
+        case "no-key":
+            return "Pass --agent <id> (or set FLAIR_AGENT_ID) so doctor can run a real semantic round-trip.";
+        case "key-load":
+        case "probe-failed":
+            return null;
+    }
+}
 /**
  * Render decision for one agent's registration-gate outcome, ahead of a
  * verified-read section (Fleet presence / Migrations). Returns null when the
@@ -428,10 +751,37 @@ export function fixCommandAgentHint(keyAgentIds) {
  * agent's subsection; the caller must still move on to the next agent
  * (failure isolation, flair#722) rather than aborting the whole section.
  */
-export function describeAgentGateFinding(agentId, state, detail) {
+export function describeAgentGateFinding(agentId, state, detail, reachability) {
+    // Self-inconsistency guard. "unreachable" is a legitimate state — a bare
+    // 500, a timeout — but it must never be ASSERTED after this run has already
+    // watched the instance answer. When it is, report the honest thing: the
+    // check failed, and we know it was not connectivity.
+    if (state === "unreachable" && reachability?.instanceReachable === true) {
+        // Strip the caller's own "instance unreachable:" prefix before quoting the
+        // detail — that prefix IS the claim being disclaimed, and leaving it in
+        // would reassert it in the same sentence that denies it.
+        const raw = detail?.replace(/^instance unreachable:\s*/i, "").trim();
+        return {
+            icon: "warn",
+            message: `could not verify agent '${agentId}' registration — the instance responded to this run, ` +
+                `so this is not a connectivity problem${raw ? ` (${raw})` : ""}`,
+            isIssue: false,
+        };
+    }
     switch (state) {
         case "registered":
             return null;
+        case "key-unreadable":
+            return {
+                icon: "warn",
+                // Names the file and the operation. No cause is invented and no fix
+                // hint is offered: the failure classes that land here (a corrupt key,
+                // a file that is not an agent key at all) have different remedies and
+                // we cannot tell them apart from the bytes. A remedy we cannot stand
+                // behind is the flair#1023 defect, not a fix for it.
+                message: `could not verify agent '${agentId}' registration — ${detail ?? "its signing key could not be loaded"}`,
+                isIssue: false,
+            };
         case "no-key":
             return {
                 icon: "warn",

package/dist/hook-install.js

@@ -41,14 +41,20 @@
 //      FlairClient's plain global `fetch`, no rejectUnauthorized/NODE_TLS_*
 //      bypass anywhere — test/unit/hook-install.test.ts asserts that
 //      statically).
-//   5. Silent-fast degradation — also owned by session-start-hook.ts (hard
-//      timeout, no-op-on-any-failure); this module only writes the pointer
-//      to it.
+//   5. Silent-fast degradation — SPLIT, deliberately, since flair#1007.
+//      session-start-hook.ts owns it once the binary is running (hard
+//      timeout, no-op-on-any-failure). It cannot own the case where the
+//      binary never runs at all — an orphaned global install after a Node
+//      runtime change — because in that case its guard is behind the door it
+//      is meant to guard. That half is owned by the command string this
+//      module writes, which is built by doctor-client.ts's
+//      buildSessionStartHookCommand (see its section doc for the shell
+//      analysis and why the wrapper is `sh -c`, not a bare fragment).
 //   6. Size-budgeted payload — also owned by session-start-hook.ts, which
 //      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 } from "./doctor-client.js";
+import { SESSION_START_HOOK_MARKER, buildSessionStartHookCommand, hookCommandIsSilenced, isHookCommandValueSafe, } 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
@@ -77,9 +83,16 @@ export function hookBackupPath(settingsPath) {
 /** The exact `command` string written into the SessionStart hook entry.
  *  Always carries both FLAIR_AGENT_ID and FLAIR_URL (see module doc above)
  *  and always contains SESSION_START_HOOK_MARKER verbatim, so doctor's
- *  existing checkSessionStartHook recognizes it unchanged. */
+ *  existing checkSessionStartHook recognizes it unchanged.
+ *
+ *  Since flair#1007 this is a thin wrapper over doctor-client.ts's
+ *  buildSessionStartHookCommand — ONE builder for every path that writes this
+ *  string (`flair hook install`, `flair doctor --fix`, `flair init`'s hint),
+ *  so the invocation's failure behaviour is defined and tested in one place
+ *  instead of drifting across three literals. Throws when agentId/flairUrl
+ *  cannot be represented safely; installHook() checks first and reports. */
 export function buildHookCommand(agentId, flairUrl) {
-    return `FLAIR_AGENT_ID=${agentId} FLAIR_URL=${flairUrl} npx -y @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
+    return buildSessionStartHookCommand(agentId, flairUrl);
 }
 /** Best-effort recovery of the agentId/flairUrl a previously-wired hook
  *  command carries — used by `flair hook status`. Pure string scan, never
@@ -194,6 +207,19 @@ export function installHook(opts) {
     const { homeDir, harness, agentId, flairUrl } = opts;
     const dryRun = !!opts.dryRun;
     const path = hookSettingsPath(homeDir, harness);
+    // The command is a single-quoted shell argument (flair#1007) and quoting
+    // rules are not uniform across the shells a harness might use, so unsafe
+    // values are REFUSED rather than escaped — checked before anything is
+    // backed up or written, so a bad input never half-mutates the file.
+    for (const [label, value] of [["agent id", agentId], ["Flair URL", flairUrl]]) {
+        if (!isHookCommandValueSafe(value)) {
+            return {
+                ok: false, path, harness, dryRun,
+                message: `${label} '${value}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -) — refusing to write it`,
+                backupPath: null, delta: null,
+            };
+        }
+    }
     if (dryRun) {
         const read = readSettingsFile(path);
         if (read.parseError) {
@@ -309,16 +335,20 @@ export function hookStatus(homeDir, harness) {
     const path = hookSettingsPath(homeDir, harness);
     const read = readSettingsFile(path);
     if (read.parseError) {
-        return { harness, path, wired: false, correctShape: false, parseError: read.parseError };
+        return { harness, path, wired: false, correctShape: false, silenced: false, parseError: read.parseError };
     }
     const config = read.parsed ?? {};
     const existing = findHookEntry(config);
     if (!existing) {
-        return { harness, path, wired: false, correctShape: false, parseError: null };
+        return { harness, path, wired: false, correctShape: false, silenced: false, parseError: null };
     }
     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 @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
     const env = parseHookCommandEnv(command);
-    return { harness, path, wired: true, correctShape, agentId: env.agentId, flairUrl: env.flairUrl, command, parseError: null };
+    return {
+        harness, path, wired: true, correctShape,
+        silenced: hookCommandIsSilenced(command),
+        agentId: env.agentId, flairUrl: env.flairUrl, command, parseError: null,
+    };
 }

package/dist/lib/auth-resolve.js

@@ -197,9 +197,92 @@ export function buildEd25519Auth(agentId, method, path, keyPath) {
     const sig = nodeCryptoSign(null, Buffer.from(payload), privKey).toString("base64");
     return `TPS-Ed25519 ${agentId}:${ts}:${nonce}:${sig}`;
 }
-/** Authenticated fetch against Flair using Ed25519. */
+/**
+ * Classify a throw from `buildEd25519Auth`.
+ *
+ * Keyed on the STRUCTURED `code` property rather than on message text,
+ * because the message is not stable across crypto backends. Probed directly
+ * on the same 60-byte malformed input:
+ *
+ *   Node (OpenSSL)   ERR_OSSL_UNSUPPORTED       error:1E08010C:DECODER routines::unsupported
+ *                    ERR_OSSL_ASN1_WRONG_TAG    error:068000A8:asn1 encoding routines::wrong tag
+ *   Bun (BoringSSL)  ERR_OSSL_NO_START_LINE     error:0900006e:PEM routines:...:NO_START_LINE
+ *                    ERR_OSSL_WRONG_TAG         error:0c0000be:ASN.1 encoding routines:...:WRONG_TAG
+ *
+ * The first line is the error in flair#1023, and matching it alone would have
+ * left the tests (bun) and the shipped CLI (node) classifying differently.
+ * So the rule is the `ERR_OSSL_` family as a whole — sound here because
+ * buildEd25519Auth does no I/O beyond reading the file: any crypto-backend
+ * error it raises is about the key, never about the instance. Message text is
+ * a secondary signal only, for a backend that reports no code we recognise.
+ */
+export function classifyKeyLoadFailure(err) {
+    const code = typeof err?.code === "string" ? err.code : "";
+    if (code === "ENOENT")
+        return "not-found";
+    if (code === "EACCES" || code === "EPERM" || code === "EISDIR")
+        return "unreadable";
+    if (code.startsWith("ERR_OSSL"))
+        return "decode";
+    const message = err instanceof Error ? err.message : String(err ?? "");
+    // `asn\.?1` because the two backends punctuate it differently:
+    // "asn1 encoding routines" (OpenSSL) vs "ASN.1 encoding routines" (BoringSSL).
+    if (/DECODER routines|asn\.?1 encoding routines|PEM routines/i.test(message))
+        return "decode";
+    return "unknown";
+}
+/** A signing key could not be loaded — distinct from the instance being down. */
+export class KeyLoadError extends Error {
+    /** The file we tried to read. Known at the point of failure; used to be discarded. */
+    keyPath;
+    kind;
+    /** The underlying error's message, preserved verbatim for the operator. */
+    underlying;
+    constructor(keyPath, kind, underlying) {
+        super(describeKeyLoadFailure(keyPath, kind, underlying));
+        this.name = "KeyLoadError";
+        this.keyPath = keyPath;
+        this.kind = kind;
+        this.underlying = underlying;
+    }
+    static from(keyPath, err) {
+        const underlying = err instanceof Error ? err.message : String(err ?? "");
+        return new KeyLoadError(keyPath, classifyKeyLoadFailure(err), underlying);
+    }
+}
+/**
+ * One line an operator can act on: what we were doing, which file, and — only
+ * when it has actually been established — why. The "unknown" arm deliberately
+ * states no cause and shows the raw error instead (flair#1023 requirement 1).
+ */
+export function describeKeyLoadFailure(keyPath, kind, underlying) {
+    switch (kind) {
+        case "not-found":
+            return `signing key ${keyPath} does not exist`;
+        case "unreadable":
+            return `signing key ${keyPath} could not be read (${underlying})`;
+        case "decode":
+            return `signing key ${keyPath} could not be parsed as an Ed25519 private key (${underlying})`;
+        case "unknown":
+            // No cause is asserted — we genuinely do not know one.
+            return `signing key ${keyPath} could not be loaded: ${underlying}`;
+    }
+}
+/**
+ * Authenticated fetch against Flair using Ed25519.
+ *
+ * Throws {@link KeyLoadError} if the key could not be loaded — a failure that
+ * provably happened BEFORE any byte hit the network, so no caller need guess
+ * whether the instance is reachable. Anything else thrown here is transport.
+ */
 export async function authFetch(baseUrl, agentId, keyPath, method, path, body) {
-    const auth = buildEd25519Auth(agentId, method, path, keyPath);
+    let auth;
+    try {
+        auth = buildEd25519Auth(agentId, method, path, keyPath);
+    }
+    catch (err) {
+        throw KeyLoadError.from(keyPath, err);
+    }
     const headers = { Authorization: auth };
     if (body !== undefined)
         headers["Content-Type"] = "application/json";