@tpsdev-ai/flair 0.50.0 → 0.51.1

package/dist/doctor-client.js

@@ -1117,8 +1117,8 @@ function sessionStartHookHint(agentId, path) {
  * after the hook is present (whether from a prior call or already there)
  * reports ok:true, applied:false — safe to call on every `flair init`.
  */
-export function applyOrReportSessionStartHook(homeDir, agentId, skip) {
-    const existing = checkSessionStartHook(homeDir);
+export function applyOrReportSessionStartHook(homeDir, agentId, skip, settingsPath) {
+    const existing = checkSessionStartHook(homeDir, settingsPath);
     if (existing.present) {
         return { applied: false, ok: true, message: `SessionStart hook already wired in ${existing.path}` };
     }
@@ -1126,7 +1126,7 @@ export function applyOrReportSessionStartHook(homeDir, agentId, skip) {
     if (skip) {
         return { applied: false, ok: false, message: "SessionStart hook skipped (--skip-hook)", hint };
     }
-    const fix = fixSessionStartHook(homeDir, agentId);
+    const fix = fixSessionStartHook(homeDir, agentId, settingsPath ?? existing.path);
     return { applied: fix.ok, ok: fix.ok, message: fix.message, hint: fix.ok ? undefined : hint };
 }
 // ── check 5: per-agent iteration for verified-read sections (flair#722) ────

package/dist/install/clients.js

@@ -5,7 +5,9 @@
 // @tpsdev-ai/flair-mcp); pi is a native-extension host (kind:
 // "native-extension" — wired via pi's own settings.json `packages` key,
 // flair#1342). Each client has:
-//   - detection: `bin` on PATH, optionally widened by a declared detect() override
+//   - detection: `bin` on PATH OR the client's known config path exists
+//     (flair#1417 — GUI-only Cursor, PATH-quirky installs). A declared
+//     detect() override remains the exception (pi).
 //   - wire(env): { ok: boolean; message: string }
 //
 // Wiring contract (FIX 4 — onboarding dogfood round 1):
@@ -89,12 +91,13 @@ function binInPath(name) {
  *      elsewhere — the same defect already fixed for `flair upgrade`'s presence
  *      probes (see "Upgrade presence probes" in src/cli.ts).
  *
- * Nothing is lost by dropping it: an `npm install -g` links the package's bin
- * into the prefix's bin directory, which is on PATH by construction (it is where
- * `npm` itself is found from). A client whose binary is NOT on PATH is a client
- * the user cannot launch, and wiring an MCP config for it is at best a no-op.
- * `flair init --client <name>` still wires a client explicitly, bypassing
- * detection entirely, so an exotic install is never locked out.
+ * Nothing is lost by dropping the npm-list fallback: an `npm install -g` links
+ * the package's bin into the prefix's bin directory, which is on PATH by
+ * construction. Detection still asks PATH first. A second signal is the
+ * client's known config path (detectClients, flair#1417): a GUI install whose
+ * shell command is opt-in (Cursor) is still present when its config file
+ * exists. `flair init --client <name>` still wires a client explicitly,
+ * bypassing detection entirely, so an exotic install is never locked out.
  */
 function detectBin(bin) {
     try {
@@ -560,10 +563,12 @@ function antigravityConfigPath() {
     return join(resolveHome(), ".gemini", "config", "mcp_config.json");
 }
 /**
- * Single dispatcher for "where does this client's MCP config live" — used by
+ * Single dispatcher for "where does this client's config live" — used by
  * `flair doctor`'s client-integration checks (flair#588) to read the config
- * without duplicating the per-client path logic that already lives here.
- * Additive only: does not change existing wire/detect behavior.
+ * without duplicating the per-client path logic that already lives here,
+ * and by detectClients() as the config-path presence signal (flair#1417).
+ * Every current ClientId has a path; a future id must extend this switch
+ * or stay binary-only via a `detect` override — do not invent a path.
  */
 export function clientConfigPath(id) {
     switch (id) {
@@ -758,17 +763,23 @@ export function renderWiringSummary(results, opts = {}) {
     return lines;
 }
 /**
- * Detect every known client. One rule (`bin` on PATH) applied uniformly — a
- * client added to ALL_CLIENTS is detected by declaring its executable, with no
- * per-client branch here to forget to extend. A client may widen that with a
- * declared `detect` override (still a pure fs check — pi adds its settings
- * file as a second signal, flair#1342); the override lives on the registry
- * entry, so this function stays branch-free.
+ * Detect every known client. One rule applied uniformly: `bin` on PATH OR
+ * the client's known config path exists (flair#1417). A client added to
+ * ALL_CLIENTS is detected by declaring its executable; clientConfigPath()
+ * already names every current id, so the config-path fallback is not a
+ * per-client branch to forget. A declared `detect` override remains the
+ * exception (still a pure fs check — pi, flair#1342). Detection never
+ * spawns a subprocess (flair#946).
+ *
+ * A future client with no config path helper stays binary-only until it
+ * grows one here or a `detect` override — do not invent a path.
  */
 export function detectClients() {
     return ALL_CLIENTS.map((client) => ({
         ...client,
-        detected: client.detect ? client.detect() : detectBin(client.bin),
+        detected: client.detect
+            ? client.detect()
+            : detectBin(client.bin) || existsSync(clientConfigPath(client.id)),
     }));
 }
 export function wireClaudeCode(env) {

package/dist/lib/daemon-liveness.js

@@ -0,0 +1,207 @@
+/**
+ * daemon-liveness.ts — the five-state liveness machine for a local Flair
+ * (Harper) daemon (flair#1454).
+ *
+ * The defect this replaces: `flair stop` decided "not running" from a single
+ * `lsof -ti :<port>` whose `catch` converted "lsof unavailable" into "nothing
+ * is listening" — absence rendered as a definite negative. `flair start` then
+ * "succeeded" over the live daemon it had just failed to see, and a
+ * `stop; start` wrapper (a systemd `Type=forking` unit's `ExecStop`, say)
+ * produced a second daemon while the first kept running.
+ *
+ * The fix is a classifier with FIVE states, not a boolean:
+ *
+ *   RUNNING       identity-verified pid alive  +  health 200
+ *   NOT_RUNNING   no pidfile, or verified dead  +  port refused
+ *   WEDGED        identity-VERIFIED pid alive   +  not serving   -> stop ACTS
+ *   DISAGREEMENT  evidence conflicts, identity NOT verified       -> stop REFUSES
+ *   UNKNOWN       insufficient evidence to classify               -> stop REFUSES
+ *
+ * THE INVARIANT (the whole design): WEDGED is reachable ONLY when the pidfile
+ * identity has been VERIFIED. The same physical evidence with an unverified
+ * identity lands in DISAGREEMENT. This is encoded structurally — the classifier
+ * takes the identity-check RESULT as an input, and there is no code path to
+ * WEDGED that bypasses it. Killing a wedged daemon is recovery only when we
+ * have proven the pid is ours; without that proof it is a recycled-PID gamble
+ * and the machine refuses.
+ *
+ * Identity is carried by a sidecar (`<dataDir>/flair-daemon.json`) that flair
+ * writes at spawn — `{ pid, startTimeMs, port, flairVersion }` — because
+ * `hdb.pid` is written by the Harper process itself and flair does not own its
+ * format. Verification = hdb.pid's pid matches the sidecar pid AND the live
+ * process's start time matches the sidecar's startTimeMs (±2s).
+ *
+ * This module is PURE: it classifies and parses, and never touches the
+ * filesystem, the network, or a process. The adapters that do (O_NOFOLLOW
+ * reads, `kill(pid, 0)`, the health probe, the start-time readers) live in
+ * `src/cli.ts`, so every branch here is unit-testable without a daemon.
+ */
+/**
+ * Classify the gathered evidence into one of the five states.
+ *
+ * The WEDGED gate is the first branch and the only one that can return WEDGED:
+ * it requires `identity.kind === "verified"` AND `pidLiveness.kind === "alive"`.
+ * Every other "alive" pid — unverified identity, or EPERM — is DISAGREEMENT.
+ */
+export function classifyDaemonState(ev, ctx) {
+    if (ev.dataDirUnsafe !== null) {
+        return { state: "UNKNOWN", detail: ev.dataDirUnsafe };
+    }
+    if (ev.pidfile.kind === "unreadable") {
+        return { state: "UNKNOWN", detail: ev.pidfile.reason };
+    }
+    const pid = ev.pidfile.kind === "present" ? ev.pidfile.pid : null;
+    const liveness = ev.pidLiveness;
+    // THE INVARIANT: WEDGED is reachable only through a VERIFIED identity.
+    if (ev.identity.kind === "verified" && liveness?.kind === "alive") {
+        if (ev.health.kind === "ok") {
+            return { state: "RUNNING", pid: ev.identity.pid };
+        }
+        return { state: "WEDGED", pid: ev.identity.pid };
+    }
+    // No live pid recorded (absent, or the recorded pid is gone).
+    if (pid === null || liveness?.kind === "gone") {
+        if (ev.health.kind === "refused") {
+            return { state: "NOT_RUNNING" };
+        }
+        if (ev.health.kind === "ok") {
+            return {
+                state: "DISAGREEMENT",
+                detail: pid === null
+                    ? `a process is serving port ${ctx.port}, but no pid is recorded under ${ctx.dataDir}`
+                    : `a process is serving port ${ctx.port}, but the recorded pid ${pid} is not alive`,
+            };
+        }
+        return {
+            state: "UNKNOWN",
+            detail: `could not determine whether Flair is running: ` +
+                `${pid === null ? "no pid is recorded" : `recorded pid ${pid} is not alive`} ` +
+                `and the health check on port ${ctx.port} did not respond`,
+        };
+    }
+    // EPERM — the recorded pid exists but belongs to another user.
+    if (liveness?.kind === "eperm") {
+        return {
+            state: "DISAGREEMENT",
+            detail: `the recorded pid ${pid} exists but belongs to another user — refusing to act on it`,
+        };
+    }
+    // Alive, but identity NOT verified — the WEDGED shape without the proof.
+    if (liveness?.kind === "alive") {
+        const reason = ev.identity.kind === "unverified" ? ev.identity.reason : "no identity sidecar";
+        return {
+            state: "DISAGREEMENT",
+            detail: `the recorded pid ${pid} is alive, but its identity could not be verified (${reason}) — refusing to act on it`,
+        };
+    }
+    return { state: "UNKNOWN", detail: "could not determine whether Flair is running" };
+}
+/**
+ * Verify the pidfile identity against the sidecar. Pure — `readStartTime` is
+ * injected so the live-process read (the only non-deterministic part) stays in
+ * the adapter layer.
+ *
+ * Verified requires ALL of: a pidfile pid, a readable sidecar, matching pids,
+ * a readable live start time, and a start time within `toleranceMs` (±2s).
+ * Any shortfall is `unverified` (or `none` when there is nothing to check).
+ */
+export function verifyIdentity(input) {
+    const tolerance = input.toleranceMs ?? 2000;
+    if (input.pidfilePid === null) {
+        return { kind: "none" };
+    }
+    if (input.sidecar.kind === "absent") {
+        return { kind: "none" };
+    }
+    if (input.sidecar.kind === "unreadable") {
+        return { kind: "unverified", reason: input.sidecar.reason };
+    }
+    if (input.pidfilePid !== input.sidecar.pid) {
+        return {
+            kind: "unverified",
+            reason: `hdb.pid names pid ${input.pidfilePid} but the sidecar records pid ${input.sidecar.pid}`,
+        };
+    }
+    const actual = input.readStartTime(input.pidfilePid);
+    if (actual === null) {
+        return { kind: "unverified", reason: `could not read the start time of pid ${input.pidfilePid}` };
+    }
+    if (!isStartTimeMatch(actual, input.sidecar.startTimeMs, tolerance)) {
+        return {
+            kind: "unverified",
+            reason: `pid ${input.pidfilePid} started at ${actual}ms but the sidecar records ${input.sidecar.startTimeMs}ms`,
+        };
+    }
+    return { kind: "verified", pid: input.pidfilePid };
+}
+/** `|actual - recorded| <= tolerance`. */
+export function isStartTimeMatch(actualMs, recordedMs, toleranceMs = 2000) {
+    return Math.abs(actualMs - recordedMs) <= toleranceMs;
+}
+/**
+ * Parse `/proc/<pid>/stat` field 22 (starttime, in clock ticks).
+ *
+ * Field 2 (comm) is parenthesised and may itself contain spaces and `)`
+ * characters, so the split is on the LAST `)` — not the first space, which is
+ * the classic bug that mangles any process whose comm has a space in it.
+ * Returns the raw tick count; the ticks→epoch conversion (which needs boot
+ * time and CLK_TCK) lives in the adapter.
+ */
+export function parseProcStatStartTime(stat) {
+    const closeParen = stat.lastIndexOf(")");
+    if (closeParen < 0)
+        return null;
+    const rest = stat.slice(closeParen + 1).trim().split(/\s+/);
+    // rest[0] is field 3 (state); field 22 (starttime) is therefore rest[19].
+    const starttime = Number(rest[19]);
+    return Number.isFinite(starttime) ? starttime : null;
+}
+/**
+ * Convert a `/proc/<pid>/stat` starttime (clock ticks since boot) to epoch ms,
+ * given the system uptime in seconds and the current wall clock. Pure so the
+ * arithmetic is testable without a live process.
+ */
+export function procStartTimeToEpochMs(starttimeTicks, uptimeSeconds, nowMs, clkTck = 100) {
+    const bootTimeMs = nowMs - uptimeSeconds * 1000;
+    return bootTimeMs + (starttimeTicks / clkTck) * 1000;
+}
+/**
+ * Parse `ps -o lstart= -p <pid>` output ("Sat Aug 29 15:03:22 2026") to epoch
+ * ms. Returns null when the output is empty or unparseable — the caller treats
+ * that as "identity unverified", never as a verdict toward the destructive
+ * branch.
+ */
+export function parsePsLstart(output) {
+    const trimmed = output.trim();
+    if (!trimmed)
+        return null;
+    const ms = Date.parse(trimmed);
+    return Number.isFinite(ms) ? ms : null;
+}
+/**
+ * Parse the sidecar JSON. Returns null on malformed content or a missing /
+ * non-positive pid/startTimeMs/port — the caller reports that as "unreadable".
+ */
+export function parseSidecarJson(content) {
+    let obj;
+    try {
+        obj = JSON.parse(content);
+    }
+    catch {
+        return null;
+    }
+    if (typeof obj !== "object" || obj === null)
+        return null;
+    const rec = obj;
+    const pid = Number(rec.pid);
+    const startTimeMs = Number(rec.startTimeMs);
+    const port = Number(rec.port);
+    const flairVersion = typeof rec.flairVersion === "string" ? rec.flairVersion : "";
+    if (!Number.isInteger(pid) || pid <= 0)
+        return null;
+    if (!Number.isFinite(startTimeMs))
+        return null;
+    if (!Number.isInteger(port) || port <= 0)
+        return null;
+    return { pid, startTimeMs, port, flairVersion };
+}