@tpsdev-ai/flair 0.49.0 → 0.50.0

package/dist/cli.js

@@ -26,7 +26,7 @@ import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion
 import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMcpMetadata, } from "./lib/mcp-enable.js";
 import { readClientMcpBlock, effectiveFlairUrl, checkPiFlairWiring, checkClaudeMdBootstrap, detectWiredFlairMcp, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, fixCommandAgentHint, isNodeKeyId, partitionKeyIds, resolveFixAgentId, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, checkContinuityCaptureHooks, fixContinuityCaptureHooks, } from "./doctor-client.js";
 import { checkGlobalBinOnPath, cliBootPathWarning, resolveNpmGlobalPrefix, } from "./install/global-bin-path.js";
-import { installHook, uninstallHook, hookStatus, hookStatusIdentityLines, HOOK_STATUS_UNPARSED, installContinuityHooks, uninstallContinuityHooks, continuityHookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
+import { installHook, uninstallHook, hookStatus, hookStatusIdentityLines, HOOK_STATUS_UNPARSED, installContinuityHooks, uninstallContinuityHooks, continuityHookStatus, isSupportedHarness, SUPPORTED_HARNESSES, hookSettingsPath, hookInstallHint, harnessSupportsContinuity, resolveHookAgentId, } from "./hook-install.js";
 import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, DEFAULT_ADMIN_USER, resolveAdminUser, resolveKeyPath, buildEd25519Auth, authFetch, KeyLoadError, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
 import { resolveSigningIdentity, emitSigningIdentityDebug, } from "./lib/signing-identity.js";
 import { validateSnapshotArchive, extractSnapshotSafely } from "./lib/safe-snapshot-extract.js";
@@ -685,6 +685,48 @@ function resolveSigningIdentityFor(opts, command) {
 function resolveSigningAgentId(opts, command) {
     return resolveSigningIdentityFor(opts, command).agentId;
 }
+// ── Shared credential/identity flag surface (flair#1106) ─────────────────────
+// Sibling commands (memory add, backup, federation sync) used to drift on
+// the same concepts: `--admin-pass-file` existed on backup/sync but was an
+// unknown option on `memory add`, and `memory add --agent` was a commander
+// requiredOption so FLAIR_AGENT_ID could never satisfy it. One helper owns
+// the credential flag names/shapes; identity (`--agent`) stays optional so
+// the env fallback can actually apply. This does not invent a new auth
+// model — it only declares the flags authedRequest already resolves.
+/** Flag strings the sibling commands must share (name + argument shape). */
+export const SHARED_CREDENTIAL_FLAGS = {
+    adminPass: "--admin-pass <pass>",
+    adminPassFile: "--admin-pass-file <path>",
+    adminUser: "--admin-user <name>",
+};
+export const SHARED_IDENTITY_FLAGS = {
+    agent: "--agent <id>",
+};
+function addSharedCredentialOptions(cmd) {
+    return cmd
+        .option(SHARED_CREDENTIAL_FLAGS.adminPass, "Admin password (or set FLAIR_ADMIN_PASS env, or use --admin-pass-file)")
+        .option(SHARED_CREDENTIAL_FLAGS.adminPassFile, "Read admin password from a file (e.g., ~/.flair/admin-pass). Preferred over --admin-pass for launchd/cron — keeps the secret out of ps and shell history.")
+        .option(SHARED_CREDENTIAL_FLAGS.adminUser, "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)");
+}
+function addSharedIdentityOption(cmd) {
+    return cmd.option(SHARED_IDENTITY_FLAGS.agent, "Agent ID (or set FLAIR_AGENT_ID env)");
+}
+/**
+ * Resolve `--admin-pass-file` into the same `adminPass` slot the inline flag
+ * uses. Shared so sibling commands cannot drift on how the file is read
+ * (mode 0600 via readAdminPassFileSecure).
+ */
+function applyAdminPassFile(opts) {
+    if (!opts.adminPass && opts.adminPassFile) {
+        try {
+            opts.adminPass = readAdminPassFileSecure(opts.adminPassFile);
+        }
+        catch (err) {
+            console.error(`Error reading --admin-pass-file ${opts.adminPassFile}: ${err.message}`);
+            process.exit(1);
+        }
+    }
+}
 // Ops port resolution: --ops-port flag > FLAIR_OPS_PORT env > config opsPort > httpPort - 1
 //
 // Deliberately NOT routed through Harper's per-instance config the way
@@ -1429,7 +1471,13 @@ async function api(method, path, body, options) {
                 agentId = decodeURIComponent(match[1]);
         }
     }
-    return authedRequest(method, path, body, { baseUrl: base, agentId, keysDir: options?.keysDir });
+    return authedRequest(method, path, body, {
+        baseUrl: base,
+        agentId,
+        keysDir: options?.keysDir,
+        explicitAdminPass: options?.explicitAdminPass,
+        adminUser: options?.adminUser,
+    });
 }
 /**
  * The authedGet `flair upgrade` verification (flair#635/#741) hands to
@@ -2614,9 +2662,9 @@ export function upgradeStatusSuffix(name, status) {
  *      is `flair doctor --fix`, never `npm install -g`.
  *   3. Wired with a concrete pin — that pin IS the installed version
  *      (current when it equals latest, else outdated → re-pin via doctor).
- *   4. Wired but unpinned (a bare npx spec / the SessionStart hook) — `npx -y`
- *      re-resolves latest every session, so the effective version IS latest →
- *      current.
+ *   4. Wired but unpinned (a bare npx spec / a pre-#1143 SessionStart hook) —
+ *      `npx -y` re-resolves latest every session, so the effective version IS
+ *      latest → current.
  */
 export function resolveFlairMcpFinding(globalProbe, latest, wiring) {
     // 1. Legacy global install.
@@ -4573,18 +4621,12 @@ keys
 // dry-run delta, symmetric removal) lives in src/hook-install.ts — this
 // section is pure CLI plumbing: option parsing, default resolution, and
 // rendering the pure functions' results.
-function resolveHookAgentId(opts, homeDir) {
-    return (opts.agent ||
-        opts.agentId ||
-        process.env.FLAIR_AGENT_ID ||
-        readClientMcpBlock("claude-code", homeDir).agentId ||
-        undefined);
-}
-function resolveHookFlairUrl(opts, homeDir) {
+function resolveHookFlairUrl(opts, homeDir, harness) {
     return (opts.url ||
         process.env.FLAIR_TARGET ||
         process.env.FLAIR_URL ||
-        readClientMcpBlock("claude-code", homeDir).flairUrl ||
+        readClientMcpBlock(harness, homeDir).flairUrl ||
+        (harness !== "claude-code" ? readClientMcpBlock("claude-code", homeDir).flairUrl : undefined) ||
         resolveBaseUrl({}));
 }
 function requireSupportedHarness(raw) {
@@ -4601,19 +4643,19 @@ hook
     .description("Wire the Flair SessionStart hook into the harness config so memory loads automatically at session start")
     .option("--harness <name>", `Target harness (${SUPPORTED_HARNESSES.join(", ")})`, "claude-code")
     .option("--dry-run", "Print the exact JSON delta without writing")
-    .option("--agent <id>", "Agent ID to wire (else FLAIR_AGENT_ID, else the agent already wired for the claude-code MCP client)")
+    .option("--agent <id>", "Agent ID to wire (else FLAIR_AGENT_ID, else the agent already wired for this harness's MCP client)")
     .option("--agent-id <id>", "Alias for --agent")
-    .option("--url <url>", "Flair URL to wire (else FLAIR_TARGET/FLAIR_URL, else the existing claude-code MCP wiring, else the local default)")
+    .option("--url <url>", "Flair URL to wire (else FLAIR_TARGET/FLAIR_URL, else this harness's MCP wiring, else the local default)")
     .option("--continuity", "Wire the continuity capture hooks instead (PostToolUse + Stop — flair#1257; installing them IS the opt-in)")
     .action((opts) => {
     const harness = requireSupportedHarness(opts.harness);
     const home = homedir();
-    const agentId = resolveHookAgentId(opts, home);
+    const agentId = resolveHookAgentId(opts, home, harness);
     if (!agentId) {
         console.error("No agent id known — pass --agent <id>, set FLAIR_AGENT_ID, or run `flair init` / `flair agent add` first.");
         process.exit(1);
     }
-    const flairUrl = resolveHookFlairUrl(opts, home);
+    const flairUrl = resolveHookFlairUrl(opts, home, harness);
     const dryRun = !!opts.dryRun;
     if (opts.continuity) {
         const result = installContinuityHooks({ homeDir: home, harness, agentId, flairUrl, dryRun });
@@ -4630,6 +4672,11 @@ hook
     const result = installHook({ homeDir: home, harness, agentId, flairUrl, dryRun });
     console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook install")}${dryRun ? render.wrap(render.c.dim, " (dry run)") : ""}\n`);
     console.log(`  ${result.ok ? render.icons.ok : render.icons.error} ${result.message}`);
+    const pinWarning = unpinnedSpecWarning();
+    if (pinWarning && result.ok) {
+        for (const line of pinWarning.split("\n"))
+            console.error(`   ⚠ ${line}`);
+    }
     if (result.backupPath) {
         console.log(`     ${render.wrap(render.c.dim, `backup: ${result.backupPath}`)}`);
     }
@@ -4689,16 +4736,20 @@ hook
     // status in every branch below. "absent" is NOT a failure: installing the
     // pair is the opt-in, so absence renders as "not enabled".
     const renderContinuity = () => {
+        // Continuity is Claude Code only. Do not tip `--continuity --harness
+        // <other>` — that writes Claude tool matchers into the wrong file.
+        if (!harnessSupportsContinuity(harness))
+            return;
         const cont = continuityHookStatus(home, harness);
         if (cont.state === "installed") {
             console.log(`  ${render.icons.ok} continuity capture: PostToolUse + Stop wired`);
         }
         else if (cont.state === "absent") {
-            console.log(`  ${render.icons.info} continuity capture: not enabled ${render.wrap(render.c.dim, "(opt-in: flair hook install --continuity)")}`);
+            console.log(`  ${render.icons.info} continuity capture: not enabled ${render.wrap(render.c.dim, `(opt-in: ${hookInstallHint(harness, "--continuity")})`)}`);
         }
         else {
             const missing = !cont.postToolUse.present ? "PostToolUse missing" : !cont.stop.present ? "Stop missing" : "stale form";
-            console.log(`  ${render.icons.warn} continuity capture: ${cont.state} (${missing}) ${render.wrap(render.c.dim, "— re-run: flair hook install --continuity")}`);
+            console.log(`  ${render.icons.warn} continuity capture: ${cont.state} (${missing}) ${render.wrap(render.c.dim, `— re-run: ${hookInstallHint(harness, "--continuity")}`)}`);
         }
     };
     console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook status")}\n`);
@@ -4711,7 +4762,7 @@ hook
     }
     if (!status.wired) {
         console.log(`  ${render.icons.error} not wired`);
-        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install`);
+        console.log(`     ${render.wrap(render.c.dim, "Fix:")} ${hookInstallHint(status.harness)}`);
         renderContinuity();
         console.log("");
         process.exit(1);
@@ -4732,7 +4783,7 @@ hook
         console.log(`     ${render.wrap(render.c.dim, "On failure:")} silent (exit 0, no output)`);
     }
     else {
-        console.log(`     ${render.icons.warn} ${render.wrap(render.c.dim, "On failure:")} prints an error on every session — run \`flair hook install\` to adopt the silent form`);
+        console.log(`     ${render.icons.warn} ${render.wrap(render.c.dim, "On failure:")} prints an error on every session — run \`${hookInstallHint(status.harness)}\` to adopt the silent form`);
     }
     renderContinuity();
     console.log("");
@@ -6116,6 +6167,95 @@ function driverCheckAppliesTo(opts) {
     const target = resolveTarget(opts);
     return !target || isLocalBase(target.replace(/\/$/, ""));
 }
+/**
+ * flair#1108: a bare undici/Node "fetch failed" names neither the URL
+ * that was probed nor the knob that would change it. These helpers are
+ * the operator-facing sentence and the setting that produced (or would
+ * change) that URL. Pure so the contract can be unit-tested without
+ * driving process.exit.
+ */
+export function federationStatusUrlSetting(opts) {
+    if (opts.target)
+        return "--target";
+    if (process.env.FLAIR_TARGET)
+        return "FLAIR_TARGET";
+    if (process.env.FLAIR_URL)
+        return "FLAIR_URL";
+    if (opts.port !== undefined && opts.port !== null && String(opts.port) !== "")
+        return "--port";
+    return "FLAIR_URL or --port";
+}
+export function describeFederationStatusFetchFailed(url, setting) {
+    return `fetch failed against ${url} (set ${setting})`;
+}
+/** True for a connect-level failure (no HTTP status): Node's undici
+ *  `TypeError: fetch failed`, Bun's `Unable to connect…`, or a cause
+ *  carrying a connect/DNS errno. Auth and HTTP errors stay out. */
+export function isFederationStatusConnectFailure(err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/\bfetch failed\b/i.test(msg))
+        return true;
+    if (/unable to connect/i.test(msg))
+        return true;
+    const cause = err instanceof Error ? err.cause : undefined;
+    const code = cause && typeof cause === "object" && cause && "code" in cause
+        ? String(cause.code)
+        : "";
+    return /^(ECONNREFUSED|ENOTFOUND|ECONNRESET|ETIMEDOUT|EAI_AGAIN|EHOSTUNREACH)$/.test(code);
+}
+export function rewriteFederationStatusFetchFailed(err, url, setting) {
+    if (!isFederationStatusConnectFailure(err))
+        return err;
+    const next = new Error(describeFederationStatusFetchFailed(url, setting));
+    if (err && typeof err === "object" && "status" in err) {
+        next.status = err.status;
+    }
+    return next;
+}
+/**
+ * Auth-shaped vs connect-level for `federation status`. A rewritten
+ * fetch-failed sentence embeds the probed URL; that URL can contain a
+ * whole-token `401` (e.g. `--port 401`). The old `message.includes("401")`
+ * check then printed the credential remedy and hid the URL+setting this
+ * change exists to surface (Bugbot on flair#1108).
+ */
+export function isFederationStatusAuthFailure(err) {
+    if (!err)
+        return false;
+    if (isFederationStatusConnectFailure(err))
+        return false;
+    if (typeof err === "object" && "status" in err) {
+        const status = err.status;
+        if (status === 401 || status === 403)
+            return true;
+    }
+    const m = err instanceof Error
+        ? err.message
+        : String(typeof err === "object" && err && "message" in err
+            ? err.message ?? err
+            : err);
+    return m.includes("missing_or_invalid_authorization") || /(?:^|\D)401(?:\D|$)/.test(m);
+}
+/**
+ * Whether to print the "set one of: FLAIR_AGENT_ID / FLAIR_ADMIN_PASS /
+ * FLAIR_TOKEN" block. Narrower than `isFederationStatusAuthFailure`: a
+ * 403 with credentials already sent (wrong password) is fatal, but the
+ * server's own body is the honest message — the credential-list remedy
+ * is for missing/invalid auth (401), not a rejected password (flair#634).
+ */
+export function isFederationStatusAuthRemedy(err) {
+    if (!err || isFederationStatusConnectFailure(err))
+        return false;
+    if (typeof err === "object" && "status" in err && err.status === 401) {
+        return true;
+    }
+    const m = err instanceof Error
+        ? err.message
+        : String(typeof err === "object" && err && "message" in err
+            ? err.message ?? err
+            : err);
+    return m.includes("missing_or_invalid_authorization") || /(?:^|\D)401(?:\D|$)/.test(m);
+}
 federation
     .command("status")
     .description("Show federation status and peer connections")
@@ -6124,8 +6264,11 @@ federation
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
     .option("--json", "Emit JSON {instance, peers, driver} (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
-    const target = resolveTarget(opts);
-    const baseUrl = target ? target.replace(/\/$/, "") : undefined;
+    // Same URL api() would have derived, including --port (the command
+    // advertised --port but previously dropped it on the floor). Naming
+    // that URL on fetch failure is only honest if it is the URL we probe.
+    const baseUrl = resolveBaseUrl(opts).replace(/\/$/, "");
+    const urlSetting = federationStatusUrlSetting(opts);
     const mode = render.resolveOutputMode(opts);
     // flair#1233: fetch instance and peers INDEPENDENTLY. One read failing
     // must never take down the whole render — the principle latestPeerContact
@@ -6135,41 +6278,33 @@ federation
     let instance = null;
     let instanceErr = null;
     try {
-        instance = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
+        instance = await api("GET", "/FederationInstance", undefined, { baseUrl });
     }
     catch (err) {
-        instanceErr = err;
+        instanceErr = rewriteFederationStatusFetchFailed(err, baseUrl, urlSetting);
     }
     // peers: null = unverifiable (the read failed), [] = verified empty.
     let peers = null;
     let peersErr = null;
     try {
-        const r = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
+        const r = await api("GET", "/FederationPeers", undefined, { baseUrl });
         peers = r.peers ?? [];
     }
     catch (err) {
-        peersErr = err;
+        peersErr = rewriteFederationStatusFetchFailed(err, baseUrl, urlSetting);
     }
     // Auth-shaped failures stay FATAL even when the other read succeeded:
     // both endpoints sit behind the same allowAdmin gate, so a 401/403 is a
     // property of the session's credentials, not of one endpoint — and
     // degrading it to "unverifiable" would swallow the actionable remedy
     // (flair#634's UX, kept). Only non-auth failures degrade independently.
-    const authShaped = (err) => {
-        if (!err)
-            return false;
-        if (err.status === 401 || err.status === 403)
-            return true;
-        const m = String(err.message ?? err);
-        return m.includes("missing_or_invalid_authorization") || m.includes("401");
-    };
     // Both reads failed → nothing to render at all. Either way keep the
     // classic failure UX (auth remedy when it's an auth problem), exit
     // non-zero.
-    if ((instanceErr && peersErr) || authShaped(instanceErr) || authShaped(peersErr)) {
+    if ((instanceErr && peersErr) || isFederationStatusAuthFailure(instanceErr) || isFederationStatusAuthFailure(peersErr)) {
         const primaryErr = instanceErr ?? peersErr;
         const msg = String(primaryErr.message ?? primaryErr);
-        if (msg.includes("missing_or_invalid_authorization") || msg.includes("401")) {
+        if (isFederationStatusAuthRemedy(primaryErr)) {
             console.error(`${render.icons.error} federation status requires auth.`);
             console.error(`  ${render.wrap(render.c.dim, "Set one of:")}`);
             console.error(`    ${render.wrap(render.c.cyan, "FLAIR_AGENT_ID=<your-agent-id>")}     ${render.wrap(render.c.dim, "(Ed25519 — uses ~/.flair/keys/<id>.key)")}`);
@@ -7004,29 +7139,16 @@ export async function runFederationSyncOnce(opts) {
         return { pushed: totalMerged, skipped: totalSkipped, error: err instanceof Error ? err : new Error(String(err)) };
     }
 }
-const federationSync = federation
+const federationSync = addSharedCredentialOptions(federation
     .command("sync")
     .description("Push local changes to the hub (one-shot). Subcommands manage the scheduled driver.")
     .option("--port <port>", "Harper HTTP port")
-    .option("--admin-pass <pass>", "Admin password")
-    .option("--admin-pass-file <path>", "Read the admin password from a file (e.g. ~/.flair/admin-pass). Preferred for launchd/cron — keeps the secret out of ps and shell history.")
-    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
-    .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
-    .action(async (opts) => {
+    .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")).action(async (opts) => {
     // --admin-pass-file resolves into the same `adminPass` slot the inline
     // flag uses, so the scheduler never has to embed a secret in a unit file.
-    // readAdminPassFileSecure() refuses a file that is not owner-only.
-    if (!opts.adminPass && opts.adminPassFile) {
-        try {
-            opts.adminPass = readAdminPassFileSecure(opts.adminPassFile);
-        }
-        catch (err) {
-            console.error(`Error reading --admin-pass-file ${opts.adminPassFile}: ${err.message}`);
-            process.exit(1);
-        }
-    }
+    applyAdminPassFile(opts);
     const r = await runFederationSyncOnce(opts);
     if (r.error) {
         console.error(`Error: ${r.error.message}`);
@@ -12918,8 +13040,8 @@ program
     // Antigravity) the MCP block present + reachable + the configured agent
     // genuinely registered; for pi (a NATIVE EXTENSION host — flair#1342) the
     // pi-flair reference in pi's own settings, including the flair#1346
-    // npm:-under-"extensions" trap; plus CLAUDE.md + the SessionStart hook
-    // (Claude Code only, since only Claude Code has those mechanisms). Reuses
+    // npm:-under-"extensions" trap; plus CLAUDE.md (Claude Code) and the
+    // SessionStart hook (Claude Code + Codex — flair#1148). Reuses
     // detectClients() rather than reimplementing client detection.
     console.log(`\n  ${render.wrap(render.c.bold, "Client integration")}`);
     // Prompt y/N before a content-editing fix, but only when interactive —
@@ -12940,6 +13062,7 @@ program
     }
     else {
         let claudeCodeAgentId;
+        let codexAgentId;
         let anyKnownAgentId;
         // `doctor --fix` writes client configs through the same wire functions
         // init does, so it owes the user the same warning when the spec it would
@@ -13119,6 +13242,8 @@ program
             const block = readClientMcpBlock(client.id, homedir());
             if (client.id === "claude-code" && block.agentId)
                 claudeCodeAgentId = block.agentId;
+            if (client.id === "codex" && block.agentId)
+                codexAgentId = block.agentId;
             if (block.agentId)
                 anyKnownAgentId = anyKnownAgentId ?? block.agentId;
             if (!block.present) {
@@ -13165,8 +13290,14 @@ program
                                             client.id === "antigravity" ? wireAntigravity(wireEnv) :
                                                 wireCursor(wireEnv);
                                 console.log(`     ${wireResult.ok ? render.icons.ok : render.icons.warn} ${wireResult.message}`);
-                                if (wireResult.ok)
+                                if (wireResult.ok) {
                                     fixed++;
+                                    if (client.id === "claude-code")
+                                        claudeCodeAgentId = fixAgentId;
+                                    if (client.id === "codex")
+                                        codexAgentId = fixAgentId;
+                                    anyKnownAgentId = anyKnownAgentId ?? fixAgentId;
+                                }
                             }
                         }
                     }
@@ -13216,8 +13347,9 @@ program
                 console.log(`     ${render.icons.warn} ${finding?.message ?? `could not verify agent registration (${reg.detail})`}`);
             }
         }
-        // Claude-Code-specific: CLAUDE.md + SessionStart hook. Only Claude Code
-        // has these mechanisms, so only run them when claude-code was detected.
+        // Claude-Code-specific: CLAUDE.md + SessionStart hook + continuity.
+        // Codex has a SessionStart hook too (checked below); CLAUDE.md and
+        // continuity stay Claude Code only.
         if (detectedClients.some((c) => c.id === "claude-code")) {
             const claudeMd = checkClaudeMdBootstrap(process.cwd(), homedir());
             if (claudeMd.present) {
@@ -13407,6 +13539,92 @@ program
                 issues++;
             }
         }
+        // Codex SessionStart hook (flair#1148) — same flair-session-start
+        // command Claude Code uses, written to ~/.codex/hooks.json. Continuity
+        // and CLAUDE.md stay Claude-Code-only; Codex's session-start mechanism
+        // is the hook file.
+        if (detectedClients.some((c) => c.id === "codex")) {
+            const hook = inspectSessionStartHook(homedir(), { settingsPath: hookSettingsPath(homedir(), "codex") });
+            if (hook.present) {
+                if (hook.execution === "broken") {
+                    if (hook.silenced) {
+                        console.log(`  ${render.icons.ok} SessionStart hook (codex): wired in ${render.wrap(render.c.dim, hook.path)} — not yet exercised`);
+                        console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "The hook is correctly wired but the adapter has not been fetched yet.")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "This is normal on a fresh install — the first Codex session will warm the npx cache.")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "Codex requires /hooks to trust a newly written command before it runs.")}`);
+                    }
+                    else {
+                        console.log(`  ${render.icons.warn} SessionStart hook (codex): wired in ${render.wrap(render.c.dim, hook.path)}, but its command did not run just now`);
+                        console.log(`     ${render.wrap(render.c.dim, hook.detail ?? "")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install --harness codex ${render.wrap(render.c.dim, "(rewrites the hook to the current silent-failure form)")}`);
+                    }
+                }
+                else if (hook.execution === "unknown") {
+                    console.log(`  ${render.icons.warn} SessionStart hook (codex): wired in ${render.wrap(render.c.dim, hook.path)}, but could not be verified ${render.wrap(render.c.dim, `(${hook.detail ?? "no detail"})`)}`);
+                }
+                else if (!hook.ours) {
+                    console.log(`  ${render.icons.ok} SessionStart hook (codex): wired in ${render.wrap(render.c.dim, hook.path)} ${render.wrap(render.c.dim, "(custom command — not verified, not modified)")}`);
+                }
+                else {
+                    console.log(`  ${render.icons.ok} SessionStart hook (codex): flair-session-start wired in ${render.wrap(render.c.dim, hook.path)} ${render.wrap(render.c.dim, "and still runs")}`);
+                }
+                if (!hook.silenced && hook.ours) {
+                    console.log(`  ${render.icons.warn} SessionStart hook (codex): a failure would print an error on every session (this command predates the silent-failure fix)`);
+                    if (hook.upgradable) {
+                        if (autoFix) {
+                            if (dryRun) {
+                                console.log(`     ${render.wrap(render.c.dim, "Would rewrite the hook command in")} ${hook.path}`);
+                            }
+                            else {
+                                const proceed = await confirmFix(`  Rewrite the Flair SessionStart hook in ${hook.path} so failures stay silent? [y/N] `);
+                                if (!proceed) {
+                                    console.log(`     Skipped.`);
+                                }
+                                else {
+                                    const upgrade = upgradeSessionStartHookCommand(homedir(), hook.path);
+                                    console.log(`     ${upgrade.ok ? render.icons.ok : render.icons.warn} ${upgrade.message}`);
+                                    if (upgrade.ok && upgrade.changed)
+                                        fixed++;
+                                }
+                            }
+                        }
+                        else {
+                            console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install --harness codex ${render.wrap(render.c.dim, "(rewrites the hook command in place — same agent, same instance)")}`);
+                        }
+                    }
+                    else {
+                        console.log(`     ${render.wrap(render.c.dim, "This hook was hand-edited, so Flair will not rewrite it. To adopt the current form:")} flair hook install --harness codex`);
+                    }
+                    issues++;
+                }
+            }
+            else {
+                console.log(`  ${render.icons.error} SessionStart hook (codex): not found in ${render.wrap(render.c.dim, hook.path)}`);
+                if (autoFix) {
+                    if (dryRun) {
+                        console.log(`     ${render.wrap(render.c.dim, "Would add SessionStart hook to")} ${hook.path}`);
+                    }
+                    else {
+                        const proceed = await confirmFix(`  Add the flair-session-start SessionStart hook to ${hook.path}? [y/N] `);
+                        if (!proceed) {
+                            console.log(`     Skipped.`);
+                        }
+                        else {
+                            const fixAgentId = resolveHookAgentId({ agent: opts.agent }, homedir(), "codex");
+                            const fixRes = fixSessionStartHook(homedir(), fixAgentId, hook.path);
+                            console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
+                            if (fixRes.ok)
+                                fixed++;
+                        }
+                    }
+                }
+                else {
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install --harness codex`);
+                }
+                issues++;
+            }
+        }
     }
     // 7a. Resolve which agent identities the two verified-read sections below
     // (Fleet presence, Migrations) iterate (flair#722). Previously both
@@ -13806,7 +14024,8 @@ program
 // from /HealthDetail at all — it's the one metric in this file that requires
 // live QUERIES, because it's checking whether querying itself still works.
 // For a sample of the querying agent's OWN memories (fetchRecallSpotCheckData
-// below, GET /Memory?agentId=<self>), a CUE is derived from each memory
+// below, a projected+bounded GET /Memory — flair#1360: never the unfiltered
+// collection with embeddings inline), a CUE is derived from each memory
 // (deriveRecallCue — its `subject` if present, else the leading ~8 words /
 // first sentence of `content`; a PARTIAL cue, never the full content) and
 // searched for through the EXACT SAME authenticated read path `flair memory
@@ -13869,6 +14088,53 @@ export const QUALITY_HASH_FALLBACK_DEGRADED_PCT = 10;
  *  "first-pass default, tunable later" spirit as the thresholds above. */
 export const QUALITY_RECALL_SAMPLE_SIZE = 10;
 export const QUALITY_RECALL_K = 5;
+/**
+ * Fields the recall spot-check and the quality-snapshot lookup actually
+ * read. Harper REST `select(...)` (same syntax adk-flair-js's listMemories
+ * already uses) projects these server-side so the nightly sweep never
+ * pulls embedding vectors inline — the defect in flair#1360 was an
+ * unfiltered `GET /Memory?agentId=…` that returned every row's 768-d
+ * vector (~66 MB × 2 per `--emit` run on a 3k-row store) just to sample
+ * 10 memories. `type` is intentionally omitted: it is not a declared
+ * Memory column (see schemas/memory.graphql); snapshot exclusion keys
+ * off `subject` (`quality-snapshot/…`).
+ */
+export const QUALITY_MEMORY_LIST_SELECT = ["id", "subject", "content", "createdAt"];
+/**
+ * Extra most-recent rows fetched beyond `sampleSize` so
+ * `planRecallSpotCheck` can drop the sweep's own quality-snapshot
+ * bookkeeping and still fill a 10-row window — without scanning the
+ * table. Nightly `--emit` writes one snapshot per run; 16 is a buffer
+ * for a few extra `--emit`s in the same recency window, not a second
+ * full-table read.
+ */
+export const QUALITY_RECALL_SNAPSHOT_OVERFETCH = 16;
+/**
+ * Harper REST collection path for the recall spot-check's sample fetch:
+ * agent-scoped, projected (never `embedding`), recency-sorted, bounded.
+ * `limit(start,end)` is Harper's offset window — same as
+ * packages/adk-flair-js/src/memory_service.ts.
+ */
+export function qualityRecallSamplePath(agentId, sampleSize = QUALITY_RECALL_SAMPLE_SIZE) {
+    const select = QUALITY_MEMORY_LIST_SELECT.join(",");
+    const end = sampleSize + QUALITY_RECALL_SNAPSHOT_OVERFETCH;
+    return `/Memory?agentId=${encodeURIComponent(agentId)}&select(${select})&sort(-createdAt)&limit(0,${end})`;
+}
+/**
+ * Harper REST collection path for the previous quality-snapshot lookup:
+ * same projection as the sample fetch (never `embedding`). Subject is
+ * passed as a query equals (indexed) plus a client-side re-filter —
+ * Memory.search() historically did not turn bare query params into
+ * conditions beyond the signed agent scope, so the client-side filter
+ * in fetchPreviousQualitySnapshot stays as defense in depth. No `limit`:
+ * a bounded window could miss yesterday's snapshot after a busy day of
+ * writes, and without a reliable server-side subject pushdown that
+ * would silently look like a first run.
+ */
+export function qualitySnapshotLookupPath(agentId, subject) {
+    const select = QUALITY_MEMORY_LIST_SELECT.join(",");
+    return `/Memory?agentId=${encodeURIComponent(agentId)}&subject=${encodeURIComponent(subject)}&select(${select})&sort(-createdAt)`;
+}
 /** Leading-word cap on the content-derived cue. 25, matching the arm of the
  *  flair#967 A/B that was actually measured (same 10 memories, same instance,
  *  same minute: subject cue → recall@5 0.60 / MRR 0.16; first-25-words-of-
@@ -14230,23 +14496,25 @@ export function computeQualityReport(healthy, healthData, opts = {}) {
  * `agentId`'s own memories and, for each, search for a cue derived from it.
  * Reuses the EXACT read path `flair memory search` / `flair memory list`
  * use — `api()` (→ authedRequest's 5-tier resolver) for both the
- * `GET /Memory?agentId=...` sample fetch and the `POST /SemanticSearch`
- * queries — so this has zero new endpoint and zero new auth mechanism; it
- * is scoped to `agentId`'s own memories exactly as those commands already
- * are. Never throws: every failure mode (no agentId, fewer than
- * `sampleSize` memories, a fetch/search error) returns `{ ok: false,
- * skipReason }` for computeQualityReport to turn into a `gaps` entry.
+ * projected, bounded `GET /Memory?…&select(…)&limit(…)` sample fetch
+ * (flair#1360 — never the unfiltered collection with embeddings inline)
+ * and the `POST /SemanticSearch` queries — so this has zero new endpoint
+ * and zero new auth mechanism; it is scoped to `agentId`'s own memories
+ * exactly as those commands already are. Never throws: every failure mode
+ * (no agentId, fewer than `sampleSize` memories, a fetch/search error)
+ * returns `{ ok: false, skipReason }` for computeQualityReport to turn
+ * into a `gaps` entry.
  */
-async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
+export async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
     const sampleSize = opts.sampleSize ?? QUALITY_RECALL_SAMPLE_SIZE;
     const k = opts.k ?? QUALITY_RECALL_K;
+    const request = opts.request ?? api;
     if (!agentId) {
         return { ok: false, skipReason: "no agent identity to query as — pass --agent or set FLAIR_AGENT_ID" };
     }
     let all;
     try {
-        const q = new URLSearchParams({ agentId }).toString();
-        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl, agentId });
+        const raw = await request("GET", qualityRecallSamplePath(agentId, sampleSize), undefined, { baseUrl, agentId });
         all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
     }
     catch (err) {
@@ -14276,7 +14544,7 @@ async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
     try {
         for (const { id, cue } of plan.sampled) {
             const body = { agentId, q: cue, limit: k };
-            const res = await api("POST", "/SemanticSearch", body, { baseUrl, agentId });
+            const res = await request("POST", "/SemanticSearch", body, { baseUrl, agentId });
             const results = Array.isArray(res) ? res : (res?.results ?? []);
             sampledIds.push(id);
             perQueryResultIds.push(results.map((r) => String(r.id)));
@@ -14494,21 +14762,23 @@ export function qualitySnapshotSubject(baseUrl) {
     return `quality-snapshot/${host}`;
 }
 /** Fetch the most recent prior quality snapshot for `agentId` at `baseUrl`,
- *  via the exact same read path fetchRecallSpotCheckData uses (`api("GET",
- *  "/Memory?agentId=...")`, self-scoped by the signed request's own agent
- *  identity — no new endpoint). Filters client-side by subject (the server's
- *  `GET /Memory?...` doesn't translate query params into search conditions
- *  beyond the signed agentId scope — see resources/Memory.ts's search()),
- *  same client-side-filter pattern `memory list --hash-fallback` already
- *  uses. Returns null on: no prior snapshot, a fetch error, or a snapshot row
- *  whose content isn't parseable/versioned JSON (never throws — a corrupt or
- *  foreign row degrades to "no snapshot", same as a genuine first run, rather
- *  than crashing `--emit`). */
-async function fetchPreviousQualitySnapshot(agentId, baseUrl, subject) {
+ *  via the same signed `GET /Memory` read path fetchRecallSpotCheckData
+ *  uses (self-scoped by the signed request's own agent identity — no new
+ *  endpoint). Projects the same fields (never embeddings — flair#1360) and
+ *  asks for `subject` as a query equals; still filters client-side by
+ *  subject because Memory.search() historically did not turn bare query
+ *  params into search conditions beyond the signed agentId scope (see
+ *  resources/Memory.ts's search()), same client-side-filter pattern
+ *  `memory list --hash-fallback` already uses. Returns null on: no prior
+ *  snapshot, a fetch error, or a snapshot row whose content isn't
+ *  parseable/versioned JSON (never throws — a corrupt or foreign row
+ *  degrades to "no snapshot", same as a genuine first run, rather than
+ *  crashing `--emit`). */
+export async function fetchPreviousQualitySnapshot(agentId, baseUrl, subject, opts = {}) {
+    const request = opts.request ?? api;
     let all;
     try {
-        const q = new URLSearchParams({ agentId }).toString();
-        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl, agentId });
+        const raw = await request("GET", qualitySnapshotLookupPath(agentId, subject), undefined, { baseUrl, agentId });
         all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
     }
     catch {
@@ -14976,9 +15246,8 @@ function parseEntitiesOptionOrExit(csv) {
 }
 const ENTITIES_OPTION_DESCRIPTION = "Comma-separated entity vocabulary strings this record touches (type:value from the closed type set, e.g. repo:tpsdev-ai/flair — see docs/entity-vocabulary.md; feeds `flair attention`)";
 const memory = program.command("memory").description("Manage agent memories");
-memory.command("add [content]")
-    .description("Write a new memory row for an agent (content via positional arg or --content)")
-    .requiredOption("--agent <id>")
+addSharedCredentialOptions(addSharedIdentityOption(memory.command("add [content]")
+    .description("Write a new memory row for an agent (content via positional arg or --content)")))
     .option("--content <text>", "memory content (alias for positional arg)")
     .option("--durability <d>", "permanent|persistent|standard|ephemeral (default standard). Also decides the default visibility when --visibility is omitted: permanent/persistent -> shared, standard/ephemeral -> private").option("--tags <csv>")
     .option("--summary <text>", "agent-set multi-sentence dense compression (3-tier chain: subject → summary → content)")
@@ -14992,10 +15261,15 @@ memory.command("add [content]")
         console.error("error: content required (positional arg or --content)");
         process.exit(1);
     }
-    const agentId = resolveSigningAgentId(opts, "memory add") ?? opts.agent;
-    const memId = `${opts.agent}-${Date.now()}`;
+    applyAdminPassFile(opts);
+    const agentId = resolveSigningAgentId(opts, "memory add");
+    if (!agentId) {
+        console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
+        process.exit(2);
+    }
+    const memId = `${agentId}-${Date.now()}`;
     const body = {
-        id: memId, agentId: opts.agent, content, durability: opts.durability || "standard",
+        id: memId, agentId, content, durability: opts.durability || "standard",
         tags: opts.tags ? String(opts.tags).split(",").map((x) => x.trim()).filter(Boolean) : undefined,
         type: "memory", createdAt: new Date().toISOString(),
     };
@@ -15028,7 +15302,11 @@ memory.command("add [content]")
         if (entities.length > 0)
             body.entities = entities;
     }
-    const out = await api("PUT", `/Memory/${memId}`, body, { agentId });
+    const out = await api("PUT", `/Memory/${memId}`, body, {
+        agentId,
+        explicitAdminPass: opts.adminPass,
+        adminUser: opts.adminUser,
+    });
     console.log(JSON.stringify(out, null, 2));
 });
 // ─── flair memory write-task-summary ────────────────────────────────────────
@@ -16274,7 +16552,14 @@ bridge
         process.exit(2);
     }
     try {
-        const result = await runRoundTrip({ descriptor: loaded.descriptor, cwd, fixturePath: opts.fixture });
+        const result = await runRoundTrip({
+            descriptor: loaded.descriptor,
+            cwd,
+            fixturePath: opts.fixture,
+            // Keep the intermediate export so a failure can print a live path.
+            // The next harness start sweeps leftovers older than a minute (flair#1032).
+            retainTmpDir: true,
+        });
         if (opts.json) {
             console.log(JSON.stringify(result, null, 2));
             process.exit(result.passed ? 0 : 1);
@@ -16481,31 +16766,19 @@ function printTrustError(detail) {
     }
 }
 // ─── flair backup ────────────────────────────────────────────────────────────
-program
+addSharedCredentialOptions(program
     .command("backup")
     .description("Export agents, memories, and souls to a JSON archive")
     .option("--output <path>", "Output file path (default: ~/.flair/backups/flair-backup-<timestamp>.json)")
     .option("--agents <ids>", "Comma-separated agent IDs to include (default: all)")
     .option("--port <port>", "Harper HTTP port")
-    .option("--url <url>", "Flair base URL (overrides --port)")
-    .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS env, or use --admin-pass-file)")
-    .option("--admin-pass-file <path>", "Read admin password from a file (e.g., ~/.flair/admin-pass). Preferred over --admin-pass for launchd/cron — keeps the secret out of ps and shell history.")
-    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
-    .action(async (opts) => {
+    .option("--url <url>", "Flair base URL (overrides --port)")).action(async (opts) => {
     const baseUrl = opts.url ?? `http://127.0.0.1:${resolveHttpPort(opts)}`;
-    let adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
-    if (!adminPass && opts.adminPassFile) {
-        // readAdminPassFileSecure refuses world/group readable files (mode 0600
-        // recommended). Common gotcha: files generated via
-        // `openssl rand -base64 24 > admin-pass` end in a newline; helper trims it.
-        try {
-            adminPass = readAdminPassFileSecure(opts.adminPassFile);
-        }
-        catch (err) {
-            console.error(`Error reading --admin-pass-file ${opts.adminPassFile}: ${err.message}`);
-            process.exit(1);
-        }
-    }
+    applyAdminPassFile(opts);
+    // Env is a second-class fallback after the explicit flags (same order
+    // backup used before the shared helper). FLAIR_ADMIN_PASS is still
+    // accepted so existing scripts keep working.
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
     const adminUser = resolveAdminUser(opts.adminUser);
     if (!adminPass) {
         console.error("Error: --admin-pass, --admin-pass-file, or FLAIR_ADMIN_PASS required for backup");