@tpsdev-ai/flair 0.22.1 → 0.24.0

package/dist/deploy.js

@@ -225,6 +225,21 @@ export const REPLICATION_FAILURE_RE = /failed to replicate to \d+ (of \d+ )?peer
 // the previous stdio:"inherit" passthrough, which gave no way to inspect
 // harper's output. stdin stays "inherit" — harper's deploy never reads
 // from it, so there's nothing to tee there.
+//
+// Resolves on "close", NOT "exit" (flair#699). Node's child_process fires
+// "exit" as soon as the process terminates, but the piped stdout/stderr
+// streams can still have buffered `data` events in flight at that instant —
+// "exit" makes no promise that every chunk already written by the child has
+// been delivered to our listeners yet. "close" is the event Node guarantees
+// fires only after all stdio streams have ended, i.e. every `data` chunk has
+// already been pushed into `chunks`. Resolving on "exit" was a real
+// output-capture race, not just a test artifact: under scheduler pressure
+// (e.g. loaded CI runners) the process could exit and this promise could
+// resolve before the final stderr chunk — often exactly the line carrying
+// the replication-failure signature, since callers naturally console.error
+// their last message immediately before process.exit() — had been received,
+// so REPLICATION_FAILURE_RE silently missed a match it should have made and
+// runHarperDeploy fell through to the generic "exited with code N" error.
 function spawnHarperCaptured(bin, args, cwd, env) {
     return new Promise((resolveP, rejectP) => {
         const p = spawn(process.execPath, [bin, ...args], {
@@ -242,7 +257,7 @@ function spawnHarperCaptured(bin, args, cwd, env) {
             chunks.push(d.toString("utf8"));
         });
         p.on("error", rejectP);
-        p.on("exit", (code) => resolveP({ code, output: chunks.join("") }));
+        p.on("close", (code) => resolveP({ code, output: chunks.join("") }));
     });
 }
 function sleep(ms) {

package/dist/doctor-client.js

@@ -135,6 +135,37 @@ function scanCodexFlairBlock(raw) {
     const flairUrl = urlMatch?.[1] || undefined;
     return { present: !!agentId && !!flairUrl, agentId, flairUrl };
 }
+// ── 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
+ * client whose block was judged "not present" (readClientMcpBlock — missing
+ * FLAIR_AGENT_ID and/or FLAIR_URL). A pre-existing config can still carry a
+ * `flairUrl` fragment (e.g. `present:false` because FLAIR_AGENT_ID is empty,
+ * but FLAIR_URL scanned fine) — and that fragment can itself be malformed: a
+ * bare host with no scheme/port (`"127.0.0.1"`), left over from an older
+ * Flair version or a hand-edited config. Blindly reusing it perpetuates the
+ * corruption into the freshly suggested block (flair#727 — a real dogfood
+ * run printed exactly `FLAIR_URL = "127.0.0.1"`, unusable if pasted).
+ *
+ * Only trust `existingFlairUrl` when it parses as an absolute http(s) URL;
+ * otherwise fall back to `baseUrl` — the live, authoritative URL `doctor`
+ * already computed from the same port source as its "Config: ... (port:
+ * NNNNN)" line (resolveHttpPort / readPortFromConfig, with live-port
+ * discovery layered on top).
+ */
+export function resolveWireFlairUrl(existingFlairUrl, baseUrl) {
+    if (existingFlairUrl) {
+        try {
+            const parsed = new URL(existingFlairUrl);
+            if (parsed.protocol === "http:" || parsed.protocol === "https:")
+                return existingFlairUrl;
+        }
+        catch {
+            // Not an absolute URL (e.g. a bare host like "127.0.0.1") — fall through.
+        }
+    }
+    return baseUrl;
+}
 /**
  * Pass when EITHER the project-scoped `${cwd}/CLAUDE.md` or the user-level
  * `~/.claude/CLAUDE.md` contains the bootstrap marker — Claude Code loads
@@ -310,3 +341,148 @@ export function applyOrReportSessionStartHook(homeDir, agentId, skip) {
     const fix = fixSessionStartHook(homeDir, agentId);
     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) ────
+//
+// `doctor`'s Fleet presence and Migrations sections need a signed (Ed25519)
+// request to reveal server-verified fields (flairVersion/harperVersion,
+// migration state) — previously that meant passing --agent explicitly, even
+// though doctor already enumerates every key in ~/.flair/keys (the "Keys
+// found: N agent(s)" line above). A real dogfood run found the #720
+// halted-migration warning visible via `flair status --agent local` but
+// invisible in the default `doctor` run the same user ran minutes later.
+//
+// These two functions are the pure decision logic for iterating and
+// rendering per agent — no fs, no network, no crypto — so they're
+// unit-testable the same way as the rest of this module. The actual signed
+// fetches (which reuse authFetch/checkAgentRegistered, private to cli.ts)
+// stay in src/cli.ts and call these to decide who to iterate and how a given
+// agent's registration-gate outcome should render.
+/**
+ * Decide which agent ids the verified-read sections should iterate over.
+ *   - `agentFlag` given -> exactly that one id (a plain filter — unchanged
+ *     pre-#722 semantics: doctor still tries a single signed identity, it
+ *     just doesn't widen to "every key"). Doesn't require the id to already
+ *     have a key on disk; the registration gate reports "no local key" for
+ *     that case rather than silently expanding the search.
+ *   - no `agentFlag` -> every id in `keyAgentIds` (the ~/.flair/keys
+ *     enumeration doctor's own "Keys found" check already did), sorted for
+ *     deterministic, reproducible output across runs.
+ */
+export function planAgentIterations(keyAgentIds, agentFlag) {
+    if (agentFlag)
+        return [agentFlag];
+    return [...keyAgentIds].sort();
+}
+/**
+ * Render decision for one agent's registration-gate outcome, ahead of a
+ * verified-read section (Fleet presence / Migrations). Returns null when the
+ * agent is registered — the caller should proceed with its actual signed
+ * read for that agent. Otherwise returns the finding to print for THAT
+ * 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) {
+    switch (state) {
+        case "registered":
+            return null;
+        case "no-key":
+            return {
+                icon: "warn",
+                message: `no local key for '${agentId}' — skipping${detail ? ` (${detail})` : ""}`,
+                isIssue: false,
+            };
+        case "not-registered":
+            return {
+                icon: "error",
+                message: `agent '${agentId}' has a local key but is NOT registered on this Flair instance`,
+                // Two ways out, both actionable — register it if it should exist, or
+                // (flair#734) clean it up if it's a stale/leftover key. `flair keys
+                // prune` never touches a key that IS registered, so it's always a
+                // safe suggestion here even when the right fix is actually `agent add`.
+                fixHint: `flair agent add ${agentId} (if it should be registered) — or flair keys prune (if it's a stale/leftover key)`,
+                isIssue: true,
+            };
+        case "unreachable":
+            return {
+                icon: "warn",
+                message: `could not verify agent '${agentId}' registration${detail ? ` (${detail})` : ""}`,
+                isIssue: false,
+            };
+    }
+}
+// ── check 6: `flair keys prune` classification (flair#734) ─────────────────
+//
+// Follow-up to #731's doctor agent-iteration, which made previously-invisible
+// stale keys visible (each renders as a "not registered" gate finding, check
+// 5 above) but shipped no command to act on it — every doctor run just
+// re-reported the same noise. `flair keys prune` (src/cli.ts) walks the key
+// dir and moves anything it can positively classify as prunable into
+// `<keysDir>/.pruned/<date>/` — never deletes. The network-dependent half
+// (is this agentId actually registered?) reuses checkAgentRegistered
+// (src/cli.ts), the exact same signed GET /Agent/:id check 5's gate uses.
+// This module only owns the PURE decision — given a file's seed-validity and
+// (if checked) registration state, what class is it and why — plus two
+// path/naming helpers pure enough to live here (no crypto, no network).
+/** Name of the archive subdirectory prune moves prunable files into —
+ *  `<keysDir>/.pruned/<date>/`. Also the one directory name the scanner
+ *  itself must skip when walking the key dir (never re-classify prune's own
+ *  archive as a candidate). */
+export const PRUNED_DIR_NAME = ".pruned";
+/** `YYYY-MM-DD`, UTC — the `<date>` component of the archive path. UTC (not
+ *  local time) so a single prune run always lands in exactly one date
+ *  bucket regardless of the host's timezone. */
+export function pruneDateStamp(now = new Date()) {
+    return now.toISOString().slice(0, 10);
+}
+/**
+ * Pick a collision-free destination filename for a move into an archive
+ * directory that may already hold a file of the same name (e.g. two prune
+ * runs on the same UTC day). Preserves the original name whenever possible;
+ * on collision appends `.2`, `.3`, ... until free. Pure — the caller supplies
+ * the set of names already present (or about to be present, within the same
+ * run) at the destination; no fs access happens here.
+ */
+export function resolveCollisionSafeName(existingNames, filename) {
+    const existing = existingNames instanceof Set ? existingNames : new Set(existingNames);
+    if (!existing.has(filename))
+        return filename;
+    let n = 2;
+    while (existing.has(`${filename}.${n}`))
+        n++;
+    return `${filename}.${n}`;
+}
+/**
+ * Classify one `.key` file given whether its seed parsed (`seedValid`) and,
+ * if it did, the registration-gate result checkAgentRegistered (src/cli.ts)
+ * returned for it — the SAME check doctor's "not registered" finding above
+ * is built from. Pure — no fs/crypto/network; the caller (classifyKeysDir,
+ * src/cli.ts) does the actual file read, seed parse, and signed registration
+ * check, and only calls this to decide what the result means.
+ *
+ * `registration` is ignored (pass null) when `seedValid` is false — an
+ * unparseable seed can't be signed with, so it was never checked against the
+ * instance, regardless of what agentId its filename implies.
+ *
+ * Deliberately has no case for "unreachable": classifyKeysDir aborts the
+ * WHOLE run before classifying anything once the instance is confirmed
+ * unreachable (never classify offline) — this function is only ever called
+ * once that's already been ruled out.
+ */
+export function classifyKeyFile(agentId, seedValid, registration, baseUrl) {
+    if (!seedValid) {
+        return { class: "invalid", reason: "not a parseable Ed25519 private key seed" };
+    }
+    if (registration?.state === "registered") {
+        return { class: "keep", reason: `agent '${agentId}' is registered on ${baseUrl} — never pruned` };
+    }
+    // "not-registered", "no-key", or (defensively) no registration result at
+    // all — every one of those means we could not confirm this agent is
+    // registered, so it's prunable. "no-key" is not expected in practice here
+    // (the file we just parsed a valid seed FROM is itself the key
+    // checkAgentRegistered would sign with), but is handled the same way
+    // rather than left as an unclassified gap.
+    return {
+        class: "stale",
+        reason: `agent '${agentId}' is not registered on ${baseUrl}${registration?.detail ? ` (${registration.detail})` : ""}`,
+    };
+}

package/dist/hook-install.js

@@ -0,0 +1,324 @@
+// ─── `flair hook install` — ambient memory via harness SessionStart hooks (flair#745) ──
+//
+// Design record: https://github.com/tpsdev-ai/flair/issues/719 ("Paved-paths
+// design round" — the `flair hook install` section) + Kern's and Sherlock's
+// verdicts on that thread. Issue: https://github.com/tpsdev-ai/flair/issues/745
+//
+// `flair doctor --fix` and `flair init` already wire a SessionStart hook into
+// ~/.claude/settings.json (src/doctor-client.ts's checkSessionStartHook /
+// fixSessionStartHook, driven by `applyOrReportSessionStartHook`) — but that
+// wiring is a side effect of a broader diagnostic/setup flow, not a
+// standalone, symmetric, testable command a user or an automation can run on
+// its own. This module is the pure (no network, no process spawn) decision
+// logic behind the new top-level `flair hook install|uninstall|status`
+// command family (wired into src/cli.ts). It intentionally reuses
+// doctor-client.ts's SESSION_START_HOOK_MARKER as the single source of truth
+// for "is this our hook" — so `flair doctor`'s existing check keeps
+// recognizing anything this module writes with ZERO changes to that check.
+// The one deliberate shape difference: this module's command always sets
+// BOTH FLAIR_AGENT_ID and FLAIR_URL (mirroring src/install/clients.ts's
+// WireEnv/flairMcpEntry, which does the same for the MCP server block),
+// where doctor/init's minimal shape sets only FLAIR_AGENT_ID. That addition
+// never breaks doctor's marker-substring check (the marker is still present
+// verbatim), and is what makes a remote-instance install actually target the
+// remote instance instead of silently falling back to flair-mcp's localhost
+// default.
+//
+// Binding review conditions (Sherlock, #719 thread) this module implements:
+//   1. Malformed settings.json fails CLOSED — a backup is taken BEFORE the
+//      parse attempt (whenever the file exists and we're not in --dry-run),
+//      and on a parse error we report and refuse to touch the real file:
+//      never truncate, never write a partial replacement.
+//   2. Idempotent merge — parse, add/update ONLY our hook entry (found via
+//      the SESSION_START_HOOK_MARKER substring, exactly like doctor's own
+//      check), never touch unrelated hooks/keys. Re-running with unchanged
+//      inputs is a byte-identical no-op; re-running with a changed
+//      agent/URL updates just that one hook's `command` field in place.
+//   3. --dry-run computes the exact delta (before/after hook group) without
+//      writing anything — no backup either, since a backup is itself a write.
+//   4. Remote-instance transport — this module never touches HTTP/TLS at
+//      all (see packages/flair-mcp/src/session-start-hook.ts, which uses
+//      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.
+//   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";
+// ── 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"];
+export function isSupportedHarness(value) {
+    return SUPPORTED_HARNESSES.includes(value);
+}
+/** Where this harness's hook config lives, given a home directory (never
+ *  reads process.env.HOME itself — callers pass homedir() in production and
+ *  a temp dir in tests, mirroring doctor-client.ts's withHome technique). */
+export function hookSettingsPath(homeDir, harness) {
+    switch (harness) {
+        case "claude-code":
+            return join(homeDir, ".claude", "settings.json");
+    }
+}
+/** 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
+ *  constant this module uses internally. */
+export function hookBackupPath(settingsPath) {
+    return `${settingsPath}.bak`;
+}
+// ── the hook command itself ─────────────────────────────────────────────────
+/** 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. */
+export function buildHookCommand(agentId, flairUrl) {
+    return `FLAIR_AGENT_ID=${agentId} FLAIR_URL=${flairUrl} npx -y @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
+}
+/** 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. */
+export function parseHookCommandEnv(command) {
+    const agentMatch = command.match(/FLAIR_AGENT_ID=(\S+)/);
+    const urlMatch = command.match(/FLAIR_URL=(\S+)/);
+    return { agentId: agentMatch?.[1], flairUrl: urlMatch?.[1] };
+}
+function makeHookGroup(command) {
+    return { hooks: [{ type: "command", command }] };
+}
+function deepClone(value) {
+    return JSON.parse(JSON.stringify(value));
+}
+/** Locate our hook (by marker substring, exactly like doctor's
+ *  checkSessionStartHook) inside a parsed settings object, if present.
+ *  Returns array indices (not the doctor-client boolean) since install/
+ *  uninstall need to mutate/splice in place without disturbing siblings. */
+function findHookEntry(config) {
+    const groups = config?.hooks?.SessionStart;
+    if (!Array.isArray(groups))
+        return null;
+    for (let gi = 0; gi < groups.length; gi++) {
+        const hooks = groups[gi]?.hooks;
+        if (!Array.isArray(hooks))
+            continue;
+        for (let hi = 0; hi < hooks.length; hi++) {
+            if (typeof hooks[hi]?.command === "string" && hooks[hi].command.includes(SESSION_START_HOOK_MARKER)) {
+                return { groupIndex: gi, hookIndex: hi };
+            }
+        }
+    }
+    return null;
+}
+function readSettingsFile(path) {
+    if (!existsSync(path))
+        return { exists: false, parsed: {}, parseError: null };
+    let raw;
+    try {
+        raw = readFileSync(path, "utf-8");
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { exists: true, parsed: null, parseError: `could not read ${path}: ${reason}` };
+    }
+    if (!raw.trim())
+        return { exists: true, parsed: {}, parseError: null };
+    try {
+        return { exists: true, parsed: JSON.parse(raw), parseError: null };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return { exists: true, parsed: null, parseError: `malformed JSON in ${path} (${reason})` };
+    }
+}
+/** Copy the existing file to its backup path. Caller must only call this
+ *  when the file exists AND we're about to mutate for real (never during
+ *  --dry-run — a backup is itself a write). Throws on failure so the caller
+ *  can fail closed rather than silently proceeding without a safety copy. */
+function takeBackup(path) {
+    const dest = hookBackupPath(path);
+    copyFileSync(path, dest);
+    return dest;
+}
+function computeInstallDelta(config, agentId, flairUrl) {
+    const command = buildHookCommand(agentId, flairUrl);
+    const after = makeHookGroup(command);
+    const existing = findHookEntry(config);
+    if (existing) {
+        const beforeGroup = config.hooks.SessionStart[existing.groupIndex];
+        const beforeSnapshot = deepClone(beforeGroup);
+        const beforeCommand = beforeGroup.hooks[existing.hookIndex]?.command;
+        if (beforeCommand === command && beforeGroup.hooks.length === 1) {
+            return { action: "noop", before: beforeSnapshot, after, newConfig: config };
+        }
+        const newConfig = deepClone(config);
+        // Update ONLY the one matching hook entry — any sibling hooks in the
+        // same group (or other groups/keys) are left byte-identical.
+        newConfig.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex] = { type: "command", command };
+        return { action: "update", before: beforeSnapshot, after, newConfig };
+    }
+    const newConfig = deepClone(config);
+    newConfig.hooks = newConfig.hooks && typeof newConfig.hooks === "object" && !Array.isArray(newConfig.hooks) ? newConfig.hooks : {};
+    newConfig.hooks.SessionStart = Array.isArray(newConfig.hooks.SessionStart) ? newConfig.hooks.SessionStart : [];
+    newConfig.hooks.SessionStart.push(after);
+    return { action: "add", before: null, after, newConfig };
+}
+function computeRemovalDelta(config) {
+    const existing = findHookEntry(config);
+    if (!existing)
+        return { action: "noop", before: null, newConfig: config };
+    const beforeSnapshot = deepClone(config.hooks.SessionStart[existing.groupIndex]);
+    const newConfig = deepClone(config);
+    const group = newConfig.hooks.SessionStart[existing.groupIndex];
+    group.hooks.splice(existing.hookIndex, 1);
+    if (group.hooks.length === 0) {
+        newConfig.hooks.SessionStart.splice(existing.groupIndex, 1);
+    }
+    if (newConfig.hooks.SessionStart.length === 0) {
+        delete newConfig.hooks.SessionStart;
+    }
+    if (newConfig.hooks && Object.keys(newConfig.hooks).length === 0) {
+        delete newConfig.hooks;
+    }
+    return { action: "remove", before: beforeSnapshot, newConfig };
+}
+/** Idempotent, fail-closed, dry-run-able install of the Flair SessionStart
+ *  hook into `harness`'s settings file. See module doc for the Sherlock
+ *  conditions this implements. */
+export function installHook(opts) {
+    const { homeDir, harness, agentId, flairUrl } = opts;
+    const dryRun = !!opts.dryRun;
+    const path = hookSettingsPath(homeDir, harness);
+    if (dryRun) {
+        const read = readSettingsFile(path);
+        if (read.parseError) {
+            return {
+                ok: false, path, harness, dryRun,
+                message: `${read.parseError} — dry run: nothing would be written until this is fixed`,
+                backupPath: null, delta: null,
+            };
+        }
+        const { action, before, after } = computeInstallDelta(read.parsed ?? {}, agentId, flairUrl);
+        const delta = { action, path, harness, before, after };
+        const message = action === "noop"
+            ? `already correct in ${path} — no changes`
+            : `would ${action} the SessionStart hook in ${path} (dry run — nothing written)`;
+        return { ok: true, path, harness, dryRun, message, backupPath: null, delta };
+    }
+    // Backup BEFORE the parse attempt (Sherlock condition 1) — only meaningful
+    // when a file already exists; a fresh install has nothing to protect.
+    let backupPath = null;
+    if (existsSync(path)) {
+        try {
+            backupPath = takeBackup(path);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false, path, harness, dryRun,
+                message: `could not back up ${path} before mutating it: ${reason} — refusing to touch it`,
+                backupPath: null, delta: null,
+            };
+        }
+    }
+    const read = readSettingsFile(path);
+    if (read.parseError) {
+        return {
+            ok: false, path, harness, dryRun,
+            message: `${read.parseError} — refusing to modify a file we can't safely parse. Original left untouched at ${path}` +
+                (backupPath ? `; backup copy at ${backupPath}.` : "."),
+            backupPath, delta: null,
+        };
+    }
+    const { action, before, after, newConfig } = computeInstallDelta(read.parsed ?? {}, agentId, flairUrl);
+    const delta = { action, path, harness, before, after };
+    if (action === "noop") {
+        return { ok: true, path, harness, dryRun, message: `SessionStart hook already correct in ${path}`, backupPath, delta };
+    }
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+    return {
+        ok: true, path, harness, dryRun,
+        message: `${action === "add" ? "added" : "updated"} the SessionStart hook in ${path}`,
+        backupPath, delta,
+    };
+}
+/** Symmetric removal — deletes ONLY our hook entry (found the same way
+ *  install finds it: SESSION_START_HOOK_MARKER substring match), never
+ *  touches unrelated hooks/keys. A no-op (ok:true, action "noop") when
+ *  nothing is installed — never creates a file that didn't already exist. */
+export function uninstallHook(opts) {
+    const { homeDir, harness } = opts;
+    const dryRun = !!opts.dryRun;
+    const path = hookSettingsPath(homeDir, harness);
+    if (dryRun) {
+        const read = readSettingsFile(path);
+        if (read.parseError) {
+            return {
+                ok: false, path, harness, dryRun,
+                message: `${read.parseError} — dry run: nothing would be removed until this is fixed`,
+                backupPath: null, delta: null,
+            };
+        }
+        const { action, before } = computeRemovalDelta(read.parsed ?? {});
+        const delta = { action, path, harness, before, after: null };
+        const message = action === "noop"
+            ? `no Flair SessionStart hook found in ${path} — nothing to remove`
+            : `would remove the Flair SessionStart hook from ${path} (dry run — nothing written)`;
+        return { ok: true, path, harness, dryRun, message, backupPath: null, delta };
+    }
+    let backupPath = null;
+    if (existsSync(path)) {
+        try {
+            backupPath = takeBackup(path);
+        }
+        catch (err) {
+            const reason = err instanceof Error ? err.message : String(err);
+            return {
+                ok: false, path, harness, dryRun,
+                message: `could not back up ${path} before mutating it: ${reason} — refusing to touch it`,
+                backupPath: null, delta: null,
+            };
+        }
+    }
+    const read = readSettingsFile(path);
+    if (read.parseError) {
+        return {
+            ok: false, path, harness, dryRun,
+            message: `${read.parseError} — refusing to modify a file we can't safely parse. Original left untouched at ${path}` +
+                (backupPath ? `; backup copy at ${backupPath}.` : "."),
+            backupPath, delta: null,
+        };
+    }
+    const { action, before, newConfig } = computeRemovalDelta(read.parsed ?? {});
+    const delta = { action, path, harness, before, after: null };
+    if (action === "noop") {
+        return { ok: true, path, harness, dryRun, message: `no Flair SessionStart hook found in ${path} — nothing to remove`, backupPath, delta };
+    }
+    writeFileSync(path, JSON.stringify(newConfig, null, 2) + "\n");
+    return { ok: true, path, harness, dryRun, message: `removed the Flair SessionStart hook from ${path}`, backupPath, delta };
+}
+/** Read-only report: is the hook wired, does it look right, and which agent
+ *  / Flair instance does it point at (recovered from the wired command). */
+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 };
+    }
+    const config = read.parsed ?? {};
+    const existing = findHookEntry(config);
+    if (!existing) {
+        return { harness, path, wired: false, correctShape: 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 };
+}

package/dist/install/clients.js

@@ -110,15 +110,22 @@ function flairMcpEntry(env) {
     return {
         command: "npx",
         args: ["-y", "@tpsdev-ai/flair-mcp"],
-        env: { FLAIR_AGENT_ID: env.FLAIR_AGENT_ID, FLAIR_URL: env.FLAIR_URL },
+        env: {
+            FLAIR_AGENT_ID: env.FLAIR_AGENT_ID,
+            FLAIR_URL: env.FLAIR_URL,
+            // flair#718 — only present when the caller set it; absent = omitted,
+            // not written as FLAIR_CLIENT: undefined.
+            ...(env.FLAIR_CLIENT ? { FLAIR_CLIENT: env.FLAIR_CLIENT } : {}),
+        },
     };
 }
 /** Pretty-printed JSON `mcpServers.flair` snippet for copy-paste fallbacks. */
 function jsonSnippet(env) {
     return JSON.stringify({ mcpServers: { flair: flairMcpEntry(env) } }, null, 2);
 }
-/** TOML `[mcp_servers.flair]` snippet (Codex format). */
-function tomlSnippet(env) {
+/** TOML `[mcp_servers.flair]` snippet (Codex format). Exported for tests
+ * (flair#727 — asserts the rendered template carries a full scheme+port URL). */
+export function tomlSnippet(env) {
     return [
         `[mcp_servers.flair]`,
         `command = "npx"`,
@@ -127,8 +134,32 @@ function tomlSnippet(env) {
         `[mcp_servers.flair.env]`,
         `FLAIR_AGENT_ID = "${env.FLAIR_AGENT_ID}"`,
         `FLAIR_URL = "${env.FLAIR_URL}"`,
+        // flair#718 — only present when the caller set it (same rule as flairMcpEntry above).
+        ...(env.FLAIR_CLIENT ? [`FLAIR_CLIENT = "${env.FLAIR_CLIENT}"`] : []),
     ].join("\n");
 }
+/**
+ * True when `raw` TOML content already has a `[mcp_servers.flair]` header —
+ * the same detection scanCodexFlairBlock (src/doctor-client.ts) uses to
+ * decide whether the block is present. Pure string scan; no TOML parser
+ * (see the comment on _wireCodex below for why).
+ */
+export function codexConfigHasFlairSection(raw) {
+    return /^\[mcp_servers\.flair\]\s*$/m.test(raw);
+}
+/**
+ * Pure merge: append the Flair TOML snippet to existing raw config.toml
+ * content. Callers MUST first confirm codexConfigHasFlairSection(raw) is
+ * false — appending a second `[mcp_servers.flair]` table would shadow/
+ * duplicate the first (TOML doesn't merge repeated table headers), so this
+ * function does not re-check; it just appends safely with a newline
+ * separator (mirrors fixClaudeMdBootstrap's separator logic in
+ * src/doctor-client.ts — never runs the new block into the prior line).
+ */
+export function appendCodexFlairBlock(raw, env) {
+    const separator = raw.length === 0 ? "" : raw.endsWith("\n\n") ? "" : raw.endsWith("\n") ? "\n" : "\n\n";
+    return raw + separator + tomlSnippet(env) + "\n";
+}
 /**
  * Merge the Flair MCP server into a JSON config file with an `mcpServers` map.
  * Creates the file (and parent dir) if absent; preserves existing servers and
@@ -211,18 +242,22 @@ function _wireClaudeCode(env) {
 }
 function _wireCodex(env) {
     // Codex uses TOML with a [mcp_servers.flair] table. We don't carry a TOML
-    // parser, and blind text-appending risks corrupting/duplicating an existing
-    // table — so we only auto-write when the file does NOT yet exist (clean
-    // create), otherwise emit the exact TOML block to paste.
+    // parser, but appending a new top-level table at EOF is safe TOML when the
+    // exact header isn't already present (flair#727) — so an existing file only
+    // forces the manual-print fallback when it's genuinely unreadable/
+    // unwritable (permissions, I/O error), never merely "exists". A file that
+    // already has the section is reported already-wired, matching the JSON
+    // clients' idempotency (wireJsonMcp above).
     const path = codexConfigPath();
     const display = "~/.codex/config.toml";
     try {
         if (existsSync(path)) {
-            return {
-                ok: false,
-                message: `Codex: manual wiring needed — ${display} already exists.\n` +
-                    `   Add this block to ${display}:\n${indent(tomlSnippet(env))}`,
-            };
+            const raw = readFileSync(path, "utf-8");
+            if (codexConfigHasFlairSection(raw)) {
+                return { ok: true, message: `Codex: already wired in ${display}` };
+            }
+            writeFileSync(path, appendCodexFlairBlock(raw, env));
+            return { ok: true, message: `Codex: wired ${display} (restart Codex to pick it up)` };
         }
         mkdirSync(dirname(path), { recursive: true });
         writeFileSync(path, tomlSnippet(env) + "\n");