@tpsdev-ai/flair-mcp 0.32.0 → 0.34.0

package/dist/session-start-hook.d.ts

@@ -26,6 +26,23 @@
  * A hard timeout (FLAIR_HOOK_TIMEOUT_MS, default 8s) wraps the bootstrap call
  * so a stalled Flair daemon can't hang session startup; on timeout we no-op.
  *
+ * That guarantee covers everything from the moment this binary starts running.
+ * It cannot cover the case where the binary never runs at all — an `npx`
+ * invocation that stops resolving after a Node runtime change (flair#1007) —
+ * because the guard would be behind the door it is meant to guard. That half
+ * is owned by the command string registered in settings.json; see
+ * buildSessionStartHookCommand in the CLI's src/doctor-client.ts.
+ *
+ * PROBE MODE (flair#1007)
+ * ----------------------
+ * `flair doctor` needs to answer "does the command registered in settings.json
+ * still resolve and execute?" — the check whose absence turned an orphaned
+ * shim into an opaque, unattributed error on every session. Setting
+ * FLAIR_HOOK_PROBE makes this binary answer that and nothing else: it prints
+ * its inert output and exits immediately, before reading stdin, constructing a
+ * client, touching the network or writing presence. Being reached at all IS
+ * the answer.
+ *
  * AUTO-PRESENCE (flair#598)
  * -------------------------
  * A session starting is the clearest "this agent is alive" signal flair-mcp
@@ -43,13 +60,15 @@
  *   FLAIR_KEY_PATH   (default ~/.flair/keys/<agent>.key via flair-client)
  *   FLAIR_HOOK_TIMEOUT_MS (default 8000; clamped 500..30000)
  *   FLAIR_PRESENCE_TIMEOUT_MS (default 3000; clamped 500..10000 — see ./presence.ts)
+ *   FLAIR_HOOK_PROBE (unset by default — see PROBE MODE above)
  *
- * USAGE — register in ~/.claude/settings.json:
+ * USAGE — register with `flair hook install`, or by hand in
+ * ~/.claude/settings.json:
  *   {
  *     "hooks": {
  *       "SessionStart": [
  *         { "hooks": [ { "type": "command",
- *           "command": "FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start" } ] }
+ *           "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'" } ] }
  *       ]
  *     }
  *   }
@@ -70,6 +89,12 @@ interface BootstrapClient extends Partial<PresencePoster> {
         context?: string;
     } | undefined>;
 }
+/**
+ * Probe mode (flair#1007) — see the module doc. Any non-empty value other
+ * than "0" enables it, so `FLAIR_HOOK_PROBE=1` and `FLAIR_HOOK_PROBE=true`
+ * both work and an accidentally-empty variable does not.
+ */
+export declare function isProbeMode(env?: Record<string, string | undefined>): boolean;
 /**
  * Core hook logic, with injectable dependencies so it can be unit-tested
  * without a live Flair daemon. Returns the exact string to print to stdout.

package/dist/session-start-hook.js

@@ -26,6 +26,23 @@
  * A hard timeout (FLAIR_HOOK_TIMEOUT_MS, default 8s) wraps the bootstrap call
  * so a stalled Flair daemon can't hang session startup; on timeout we no-op.
  *
+ * That guarantee covers everything from the moment this binary starts running.
+ * It cannot cover the case where the binary never runs at all — an `npx`
+ * invocation that stops resolving after a Node runtime change (flair#1007) —
+ * because the guard would be behind the door it is meant to guard. That half
+ * is owned by the command string registered in settings.json; see
+ * buildSessionStartHookCommand in the CLI's src/doctor-client.ts.
+ *
+ * PROBE MODE (flair#1007)
+ * ----------------------
+ * `flair doctor` needs to answer "does the command registered in settings.json
+ * still resolve and execute?" — the check whose absence turned an orphaned
+ * shim into an opaque, unattributed error on every session. Setting
+ * FLAIR_HOOK_PROBE makes this binary answer that and nothing else: it prints
+ * its inert output and exits immediately, before reading stdin, constructing a
+ * client, touching the network or writing presence. Being reached at all IS
+ * the answer.
+ *
  * AUTO-PRESENCE (flair#598)
  * -------------------------
  * A session starting is the clearest "this agent is alive" signal flair-mcp
@@ -43,13 +60,15 @@
  *   FLAIR_KEY_PATH   (default ~/.flair/keys/<agent>.key via flair-client)
  *   FLAIR_HOOK_TIMEOUT_MS (default 8000; clamped 500..30000)
  *   FLAIR_PRESENCE_TIMEOUT_MS (default 3000; clamped 500..10000 — see ./presence.ts)
+ *   FLAIR_HOOK_PROBE (unset by default — see PROBE MODE above)
  *
- * USAGE — register in ~/.claude/settings.json:
+ * USAGE — register with `flair hook install`, or by hand in
+ * ~/.claude/settings.json:
  *   {
  *     "hooks": {
  *       "SessionStart": [
  *         { "hooks": [ { "type": "command",
- *           "command": "FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start" } ] }
+ *           "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'" } ] }
  *       ]
  *     }
  *   }
@@ -67,6 +86,15 @@ const TIMEOUT_FLOOR_MS = 500;
 const TIMEOUT_CEILING_MS = 30_000;
 /** Empty, inert hook output. Printing this is always a safe no-op. */
 const NOOP_OUTPUT = "{}";
+/**
+ * Probe mode (flair#1007) — see the module doc. Any non-empty value other
+ * than "0" enables it, so `FLAIR_HOOK_PROBE=1` and `FLAIR_HOOK_PROBE=true`
+ * both work and an accidentally-empty variable does not.
+ */
+export function isProbeMode(env = process.env) {
+    const raw = env.FLAIR_HOOK_PROBE;
+    return typeof raw === "string" && raw !== "" && raw !== "0";
+}
 /** Resolve the bootstrap timeout from env, clamped to a sane range. */
 function resolveTimeoutMs() {
     const raw = process.env.FLAIR_HOOK_TIMEOUT_MS;
@@ -179,6 +207,13 @@ function defaultClientFactory(agentId) {
 /** Entry point. Reads stdin, runs the hook, prints the result, exits 0.
  *  Wrapped so that even an unexpected throw degrades to a no-op. */
 async function main() {
+    // Probe mode short-circuits BEFORE readStdin() — reaching this line is the
+    // entire answer doctor is looking for, and a probe must cost nothing and
+    // change nothing (no stdin wait, no client, no bootstrap, no presence).
+    if (isProbeMode()) {
+        process.stdout.write(NOOP_OUTPUT);
+        return;
+    }
     let output = NOOP_OUTPUT;
     try {
         output = await runHook(await readStdin());

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair-mcp",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "MCP server for Flair — persistent memory for Claude Code, Cursor, and any MCP client.",
   "type": "module",
   "main": "dist/index.js",
@@ -27,7 +27,7 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.27.1",
-    "@tpsdev-ai/flair-client": "0.32.0",
+    "@tpsdev-ai/flair-client": "0.34.0",
     "zod": "4.3.6"
   },
   "license": "Apache-2.0",