@tpsdev-ai/flair 0.48.0 → 0.49.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/doctor-client.js

@@ -22,7 +22,7 @@
 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 { ALL_CLIENTS, clientConfigPath, piSettingsPath, resolvePiExtensionPath, scanPiSettings, } from "./install/clients.js";
 import { FLAIR_MCP_PACKAGE } 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.
@@ -610,6 +610,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

package/dist/hook-install.js

@@ -94,14 +94,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-substring 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 }] };
 }

package/dist/install/clients.js

@@ -1,9 +1,12 @@
 // ─── Client Detection & Wiring ──────────────────────────────────────────────────────
 //
-// Detects locally installed MCP clients and wires them to Flair.
-// Each client has:
-//   - detect(): boolean - returns true if client is installed
-//   - wire(options: { agentId: string; flairUrl: string }): { ok: boolean; message: string }
+// Detects locally installed clients and wires them to Flair. Most are MCP
+// clients (kind: "mcp" — wired via an mcpServers block/TOML table running
+// @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
+//   - wire(env): { ok: boolean; message: string }
 //
 // Wiring contract (FIX 4 — onboarding dogfood round 1):
 //   "wired" MUST mean a config file was actually written. A wire function returns
@@ -17,7 +20,7 @@
 import { accessSync, constants, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { dirname, join } from "node:path";
-import { mcpServerSpec } from "../lib/mcp-spec.js";
+import { flairCliVersion, isResolvedVersion, mcpServerSpec } from "../lib/mcp-spec.js";
 /**
  * Resolve the user's home dir. Prefer the live HOME/USERPROFILE env over
  * os.homedir(), which caches the value at process start and so ignores a
@@ -263,6 +266,282 @@ function geminiConfigPath() {
 function codexConfigPath() {
     return join(resolveHome(), ".codex", "config.toml");
 }
+// ---- pi (native extension — NOT an MCP client) ------------------------------------
+//
+// pi has no MCP client support (packages/pi-flair/README "Design Decision"), so
+// Flair ships @tpsdev-ai/pi-flair as a NATIVE pi extension. Wiring pi therefore
+// means editing pi's OWN settings, not writing an mcpServers block (flair#1342):
+//
+//   ~/.pi/agent/settings.json          (user scope; pi's getSettingsPath() —
+//                                       agent dir overridable via the
+//                                       PI_CODING_AGENT_DIR env var, honored here)
+//   <project>/.pi/settings.json        (project scope)
+//
+// Two settings keys matter, and confusing them is the flair#1346 field failure:
+//
+//   "packages"    — package SOURCES (`npm:`, `git:`, local paths, or
+//                   { source, ...filters } objects). pi parses these through
+//                   parseSource() and AUTO-INSTALLS a missing/mismatched npm
+//                   package at resource collection (package-manager.js
+//                   resolvePackageSources), honoring an exact `@<version>` pin.
+//                   This is where npm:@tpsdev-ai/pi-flair belongs.
+//   "extensions"  — local FILE PATHS only. An `npm:` spec here is treated as a
+//                   path, fails existsSync, and is dropped WITHOUT ERROR — the
+//                   user believes they are wired and pi registers zero tools.
+//                   (Verified against pi 0.84.2's package-manager.js: the
+//                   extensions override list feeds resolvePathFromBase/
+//                   collectFilesFromPaths, never parseSource.)
+//
+// pi-flair reads FLAIR_AGENT_ID / FLAIR_URL / FLAIR_KEY_PATH from the process
+// environment of the pi that loads it — pi settings carry NO per-package env
+// block, so wiring here cannot pin an agent identity the way the MCP clients'
+// env blocks do. Wire messages say so instead of pretending.
+/** The npm package pi loads as its Flair extension. */
+export const PI_FLAIR_PACKAGE = "@tpsdev-ai/pi-flair";
+/**
+ * pi-flair's own DEFAULT_FLAIR_URL (packages/pi-flair/src/index.ts). Duplicated
+ * as a value rather than imported — the CLI does not depend on the pi-flair
+ * workspace package — by the same convention as doctor-client's
+ * FLAIR_CLIENT_DEFAULT_URL; a unit test (pi-client.test.ts) asserts this
+ * literal matches pi-flair's source so the two cannot drift silently.
+ */
+export const PI_FLAIR_DEFAULT_URL = "http://127.0.0.1:19926";
+/**
+ * The `packages` entry a wired pi gets. PINNED for the same reason as
+ * mcpServerSpec (flair#907): pi re-resolves an unpinned npm source to latest
+ * when (re)installing, and pi-flair ships in version lockstep with the CLI.
+ * Falls back to the bare spec when the CLI cannot read its own version — the
+ * same condition and caller-owed warning as mcpServerSpec.
+ */
+export function piFlairSpec(version = flairCliVersion()) {
+    return isResolvedVersion(version)
+        ? `npm:${PI_FLAIR_PACKAGE}@${version}`
+        : `npm:${PI_FLAIR_PACKAGE}`;
+}
+/** pi's agent config dir: $PI_CODING_AGENT_DIR, else ~/.pi/agent (pi config.js). */
+function piAgentDir() {
+    const envDir = process.env.PI_CODING_AGENT_DIR;
+    if (envDir)
+        return envDir;
+    return join(resolveHome(), ".pi", "agent");
+}
+/** pi user-scope settings: <agent dir>/settings.json. */
+export function piSettingsPath() {
+    return join(piAgentDir(), "settings.json");
+}
+/** A pi `packages` array entry is a source string or `{ source, ...filters }`. */
+export function piPackageEntrySource(entry) {
+    if (typeof entry === "string")
+        return entry;
+    if (entry && typeof entry === "object" && typeof entry.source === "string") {
+        return entry.source;
+    }
+    return null;
+}
+/** Does this source string name the pi-flair package as an npm source
+ *  (bare `npm:@tpsdev-ai/pi-flair` or any `npm:@tpsdev-ai/pi-flair@<spec>`)? */
+export function isPiFlairNpmSource(source) {
+    if (typeof source !== "string" || !source.startsWith("npm:"))
+        return false;
+    const spec = source.slice("npm:".length).trim();
+    return spec === PI_FLAIR_PACKAGE || spec.startsWith(`${PI_FLAIR_PACKAGE}@`);
+}
+/** The version text of a pinned pi-flair npm source, or null when bare. */
+export function extractPiFlairPin(source) {
+    if (!isPiFlairNpmSource(source))
+        return null;
+    const spec = source.slice("npm:".length).trim();
+    const version = spec.slice(`${PI_FLAIR_PACKAGE}@`.length);
+    return spec.startsWith(`${PI_FLAIR_PACKAGE}@`) && version ? version : null;
+}
+/**
+ * Does this `extensions` entry point at pi-flair BY PATH (the documented
+ * pre-0.49 workaround: a local path to the installed dist/index.js)? A
+ * substring heuristic on the package/directory name — the entry is user-
+ * written free text, so this is deliberately loose in the direction of
+ * REPORTING (doctor names the entry it matched); it never gates anything
+ * destructive.
+ */
+export function isPiFlairExtensionPath(entry) {
+    if (typeof entry !== "string" || entry.startsWith("npm:") || entry.startsWith("git:"))
+        return false;
+    return entry.includes("pi-flair");
+}
+export function scanPiSettings(raw) {
+    const empty = { parsed: false, pinnedVersion: null, extensionFilePaths: [], misconfiguredNpmUnderExtensions: [] };
+    if (!raw || !raw.trim())
+        return empty;
+    let config;
+    try {
+        config = JSON.parse(raw);
+    }
+    catch {
+        return empty;
+    }
+    if (!config || typeof config !== "object" || Array.isArray(config))
+        return empty;
+    const cfg = config;
+    let packagesSpec;
+    let pinnedVersion = null;
+    if (Array.isArray(cfg.packages)) {
+        for (const entry of cfg.packages) {
+            const source = piPackageEntrySource(entry);
+            if (source && isPiFlairNpmSource(source)) {
+                packagesSpec = source;
+                pinnedVersion = extractPiFlairPin(source);
+                break;
+            }
+        }
+    }
+    const extensionFilePaths = [];
+    const misconfiguredNpmUnderExtensions = [];
+    if (Array.isArray(cfg.extensions)) {
+        for (const entry of cfg.extensions) {
+            if (typeof entry !== "string")
+                continue;
+            if (isPiFlairNpmSource(entry))
+                misconfiguredNpmUnderExtensions.push(entry);
+            else if (isPiFlairExtensionPath(entry))
+                extensionFilePaths.push(entry);
+        }
+    }
+    return { parsed: true, packagesSpec, pinnedVersion, extensionFilePaths, misconfiguredNpmUnderExtensions };
+}
+/**
+ * Resolve a pi `extensions` path entry the way pi's loader will: `~/` against
+ * the home dir, a relative path against the settings file's own base dir, an
+ * absolute path as-is. `baseDir` is the directory pi treats as the scope's
+ * base (user scope: the agent dir).
+ */
+export function resolvePiExtensionPath(entry, homeDir, baseDir) {
+    if (entry.startsWith("~/") || entry === "~")
+        return join(homeDir, entry.slice(1));
+    if (entry.startsWith("/"))
+        return entry;
+    return join(baseDir, entry);
+}
+/** Pretty-printed minimal settings snippet for copy-paste fallbacks. */
+function piJsonSnippet() {
+    return JSON.stringify({ packages: [piFlairSpec()] }, null, 2);
+}
+/**
+ * Wire pi by editing ~/.pi/agent/settings.json `packages` (flair#1342) — the
+ * same merge/idempotence/preservation contract as wireJsonMcp: sibling keys
+ * and entries survive byte-identical, a current entry is a no-op, a stale pin
+ * is refreshed, and ok:true means the file was actually written (or already
+ * correct). Two pi-specific rules on top:
+ *
+ *   • an `npm:` pi-flair spec under `extensions` is MOVED to `packages` — that
+ *     misplacement is silently ignored by pi (flair#1346), so leaving it while
+ *     adding a packages entry would preserve a decoy;
+ *   • an existing FILE-PATH `extensions` entry that resolves to a real file is
+ *     honored as already-wired (the documented pre-0.49 workaround) — the user
+ *     may deliberately be running a local build, so it is reported, not
+ *     rewritten.
+ *
+ * `env` is used for the launch-environment hint only: pi settings have no
+ * per-package env block, so FLAIR_AGENT_ID/FLAIR_URL must be exported by
+ * whatever shell launches pi — the message says so rather than implying the
+ * wiring carried them.
+ */
+function _wirePi(env) {
+    const path = piSettingsPath();
+    const home = resolveHome();
+    const display = path.startsWith(home) ? "~" + path.slice(home.length) : path;
+    const spec = piFlairSpec();
+    const envHint = `pi settings carry no env — export FLAIR_AGENT_ID=${env.FLAIR_AGENT_ID} in the shell that launches pi`;
+    try {
+        let config = {};
+        if (existsSync(path)) {
+            const raw = readFileSync(path, "utf-8").trim();
+            if (raw)
+                config = JSON.parse(raw);
+        }
+        if (!config || typeof config !== "object" || Array.isArray(config)) {
+            throw new Error("settings.json is not a JSON object");
+        }
+        if (config.packages !== undefined && !Array.isArray(config.packages)) {
+            throw new Error(`"packages" exists but is not an array — not rewriting it`);
+        }
+        if (config.extensions !== undefined && !Array.isArray(config.extensions)) {
+            throw new Error(`"extensions" exists but is not an array — not rewriting it`);
+        }
+        // The #1346 trap: npm: pi-flair specs under `extensions`. Collect + drop.
+        let movedFromExtensions = false;
+        if (Array.isArray(config.extensions)) {
+            const kept = config.extensions.filter((e) => !(typeof e === "string" && isPiFlairNpmSource(e)));
+            movedFromExtensions = kept.length !== config.extensions.length;
+            if (movedFromExtensions)
+                config.extensions = kept;
+        }
+        // Existing packages entry?
+        let entryIndex = -1;
+        let entrySource = null;
+        if (Array.isArray(config.packages)) {
+            for (let i = 0; i < config.packages.length; i++) {
+                const source = piPackageEntrySource(config.packages[i]);
+                if (source && isPiFlairNpmSource(source)) {
+                    entryIndex = i;
+                    entrySource = source;
+                    break;
+                }
+            }
+        }
+        if (!movedFromExtensions && entrySource === spec) {
+            return { ok: true, message: `pi: already wired in ${display} (${spec})` };
+        }
+        if (!movedFromExtensions && entryIndex === -1) {
+            // No packages entry and nothing misplaced — honor a working file-path
+            // extensions entry (pre-0.49 workaround) instead of double-wiring.
+            const scan = scanPiSettings(JSON.stringify(config));
+            const workingPath = scan.extensionFilePaths.find((p) => existsSync(resolvePiExtensionPath(p, home, piAgentDir())));
+            if (workingPath) {
+                return {
+                    ok: true,
+                    message: `pi: already wired via a file-path extension in ${display} (${workingPath}) — ` +
+                        `the pre-0.49 workaround; the canonical form is a "packages" entry: ${spec}`,
+                };
+            }
+        }
+        config.packages = Array.isArray(config.packages) ? config.packages : [];
+        let action;
+        if (entryIndex >= 0) {
+            const entry = config.packages[entryIndex];
+            if (typeof entry === "string")
+                config.packages[entryIndex] = spec;
+            else
+                entry.source = spec; // object entry: refresh source, keep filters
+            action = movedFromExtensions
+                ? `moved ${PI_FLAIR_PACKAGE} out of "extensions" and refreshed the "packages" pin in`
+                : "refreshed pin in";
+        }
+        else if (movedFromExtensions) {
+            config.packages.push(spec);
+            action = `moved ${PI_FLAIR_PACKAGE} from "extensions" to "packages" in`;
+        }
+        else {
+            config.packages.push(spec);
+            action = "wired";
+        }
+        mkdirSync(dirname(path), { recursive: true });
+        writeFileSync(path, JSON.stringify(config, null, 2) + "\n");
+        const trapNote = movedFromExtensions
+            ? ` — pi silently ignores npm: specs under "extensions" (flair#1346)`
+            : "";
+        return {
+            ok: true,
+            message: `pi: ${action} ${display} (${spec} — pi installs the package on next launch; ${envHint})${trapNote}`,
+        };
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        return {
+            ok: false,
+            message: `pi: manual wiring needed (could not update ${display}: ${reason}).\n` +
+                `   Add this to ${display} (${envHint}):\n${indent(piJsonSnippet())}`,
+        };
+    }
+}
 /**
  * Antigravity CLI (`agy`) + Antigravity 2.0 IDE + SDK: they share ONE central
  * MCP config at ~/.gemini/config/mcp_config.json on every OS (flair#1209).
@@ -298,6 +577,11 @@ export function clientConfigPath(id) {
             return cursorConfigPath();
         case "antigravity":
             return antigravityConfigPath();
+        case "pi":
+            // NOT an MCP config: pi's own settings.json, where the pi-flair
+            // native-extension wiring lives (flair#1342). readClientMcpBlock over
+            // this file correctly reports "no MCP block" — pi never has one.
+            return piSettingsPath();
     }
 }
 // ---- Internal wiring functions --------------------------------------------------
@@ -374,24 +658,28 @@ export const ALL_CLIENTS = [
         id: "claude-code",
         label: "Claude Code",
         bin: "claude",
+        kind: "mcp",
         wire: _wireClaudeCode,
     },
     {
         id: "codex",
         label: "Codex",
         bin: "codex",
+        kind: "mcp",
         wire: _wireCodex,
     },
     {
         id: "gemini",
         label: "Gemini",
         bin: "gemini",
+        kind: "mcp",
         wire: _wireGemini,
     },
     {
         id: "cursor",
         label: "Cursor",
         bin: "cursor",
+        kind: "mcp",
         wire: _wireCursor,
     },
     {
@@ -399,8 +687,23 @@ export const ALL_CLIENTS = [
         label: "Antigravity",
         // Google's Antigravity CLI — the executable is `agy` (flair#1209).
         bin: "agy",
+        kind: "mcp",
         wire: _wireAntigravity,
     },
+    {
+        id: "pi",
+        label: "pi",
+        bin: "pi",
+        // NOT an MCP client — pi loads @tpsdev-ai/pi-flair as a native extension
+        // via its settings.json `packages` key (flair#1342). Consumers doing
+        // MCP-shaped work must filter on `kind`.
+        kind: "native-extension",
+        // pi is also detected by its settings file: a configured pi whose binary
+        // isn't on THIS shell's PATH (version manager, launchd context) is still
+        // a pi whose wiring is worth checking/fixing. Pure fs check, both legs.
+        detect: () => detectBin("pi") || existsSync(piSettingsPath()),
+        wire: _wirePi,
+    },
 ];
 /**
  * The summary `flair init` prints LAST.
@@ -455,14 +758,17 @@ export function renderWiringSummary(results, opts = {}) {
     return lines;
 }
 /**
- * Detect every known client. One rule (`bin` on PATH) applied uniformly, so a
- * client added to ALL_CLIENTS is detected by declaring its executable — there is
- * no per-client branch here to forget to extend.
+ * 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.
  */
 export function detectClients() {
     return ALL_CLIENTS.map((client) => ({
         ...client,
-        detected: detectBin(client.bin),
+        detected: client.detect ? client.detect() : detectBin(client.bin),
     }));
 }
 export function wireClaudeCode(env) {
@@ -480,3 +786,6 @@ export function wireCursor(env) {
 export function wireAntigravity(env) {
     return _wireAntigravity(env);
 }
+export function wirePi(env) {
+    return _wirePi(env);
+}

package/dist/lib/auth-resolve.js

@@ -119,6 +119,34 @@ export function readAdminPassFileSecure(path) {
 export function defaultAdminPassPath() {
     return join(homedir(), ".flair", "admin-pass");
 }
+/** The admin username Harper's bootstrap creates and every Basic-auth path
+ * historically hardcoded. Kept as the default; overridable per call via
+ * `resolveAdminUser` (flair#1345). */
+export const DEFAULT_ADMIN_USER = "admin";
+/**
+ * Resolve the admin USERNAME for Basic auth against a Flair/Harper instance
+ * (flair#1345).
+ *
+ * Precedence: explicit value (an `--admin-user` flag) → `FLAIR_ADMIN_USER`
+ * env → `"admin"`. Always returns a usable name — unlike the password there
+ * is no "missing" state, because `admin` is the correct answer for every
+ * instance `flair init` ever bootstrapped.
+ *
+ * Why it exists: with `authorizeLocal: false` (the #604/#610 hardening) the
+ * CLI must send real Basic admin auth, and on an instance whose superuser is
+ * not named `admin` there was no way to say so — `--admin-pass` existed,
+ * the username didn't. A wrong username and a wrong password produce the
+ * SAME 401 "Login failed" from Harper, so this also feeds the 401 hint text
+ * (see opsAuth401Hint in src/cli.ts).
+ *
+ * Unlike the admin PASSWORD (see resolveLocalAdminPass's remote-target
+ * guard), the env leg is honored for remote targets too: a username is not a
+ * secret — sending the wrong one to a third-party host leaks nothing and
+ * fails closed with a 401.
+ */
+export function resolveAdminUser(explicit) {
+    return explicit || process.env.FLAIR_ADMIN_USER || DEFAULT_ADMIN_USER;
+}
 export function defaultKeysDir() {
     return join(homedir(), ".flair", "keys");
 }
@@ -400,10 +428,13 @@ export async function tryAgentKeyFloor(baseUrl, method, path, body, keysDir) {
 export async function authedRequest(method, path, body, opts) {
     const isLocal = opts.isLocal ?? isLocalBase(opts.baseUrl);
     const keysDir = opts.keysDir ?? defaultKeysDir();
+    // One username for every Basic tier: flag > FLAIR_ADMIN_USER env > "admin"
+    // (flair#1345 — these three sites used to hardcode the literal `admin`).
+    const adminUser = resolveAdminUser(opts.adminUser);
     let authHeader;
     // Tier 1: explicit — caller-resolved flag material always wins.
     if (opts.explicitAdminPass) {
-        authHeader = `Basic ${Buffer.from(`admin:${opts.explicitAdminPass}`).toString("base64")}`;
+        authHeader = `Basic ${Buffer.from(`${adminUser}:${opts.explicitAdminPass}`).toString("base64")}`;
     }
     else if (opts.explicitKeyPath && opts.agentId) {
         try {
@@ -421,7 +452,7 @@ export async function authedRequest(method, path, body, opts) {
         }
         else if (process.env.FLAIR_ADMIN_PASS || process.env.HDB_ADMIN_PASSWORD) {
             const adminPass = process.env.FLAIR_ADMIN_PASS ?? process.env.HDB_ADMIN_PASSWORD;
-            authHeader = `Basic ${Buffer.from(`admin:${adminPass}`).toString("base64")}`;
+            authHeader = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
         }
     }
     // Tier 3: a PINNED agent identity — sign specifically as this agent via
@@ -444,7 +475,7 @@ export async function authedRequest(method, path, body, opts) {
         try {
             const filePass = resolveLocalAdminPass(undefined, !isLocal);
             if (filePass) {
-                authHeader = `Basic ${Buffer.from(`admin:${filePass}`).toString("base64")}`;
+                authHeader = `Basic ${Buffer.from(`${adminUser}:${filePass}`).toString("base64")}`;
             }
         }
         catch (err) {