@tpsdev-ai/flair 0.49.0 → 0.51.0

package/dist/cli.js

@@ -26,13 +26,14 @@ 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";
 import { entityFormatHint, parseEntitiesCsv } from "./lib/entity-vocab-cli.js";
 import { escapeXml, unescapeXml } from "./lib/xml-escape.js";
-import { assessLaunchdManagement, diagnoseLaunchdPlistPaths, isDetached, pickInstancePid, renderDetachedWarning, renderVerifiedSummary, LAUNCHCTL_QUERY_TIMEOUT_MS, } from "./lib/launchd-management.js";
+import { assessLaunchdManagement, diagnoseLaunchdPlistPaths, isDetached, pickInstancePid, renderDetachedWarning, LAUNCHCTL_QUERY_TIMEOUT_MS, } from "./lib/launchd-management.js";
+import { applyUpgradeHookConsent, catalogIssueDelta, renderCatalogDoctorLines, renderVerifiedSummary, runDoctorChecks, } from "./lib/doctor-run.js";
 // Value-only static import so `--interval`'s advertised default cannot drift
 // from the one the scheduler actually validates against. The module itself is
 // still loaded lazily at call time (the `await import()`s below) for the
@@ -60,14 +61,18 @@ function signBody(body, secretKey) {
     const sig = nacl.sign.detached(message, secretKey);
     return Buffer.from(sig).toString("base64url");
 }
-// Per-record principalId (federation-edge-hardening slice 3a) — INFORMATIONAL
-// only; the receiver (resources/Federation.ts) never treats it as verified
-// identity or uses it in any auth decision. Sourced from the write-time
-// provenance stamp (memory-provenance slice 1, Memory.ts's buildProvenance)
-// when present. `provenance` is persisted as a JSON STRING (not an object),
-// so it must be parsed — a raw `row.provenance?.verified?.agentId` would
-// silently always be undefined. Soul/Agent/Relationship rows never carry a
-// provenance stamp today, so this is a no-op for them.
+// Per-record principalId (federation-edge-hardening slice 3a / flair#1416).
+// Sourced from the write-time provenance stamp (memory-provenance slice 1,
+// Memory.ts's buildProvenance) when present. `provenance` is persisted as
+// a JSON STRING (not an object), so it must be parsed — a raw
+// `row.provenance?.verified?.agentId` would silently always be undefined.
+// Soul/Agent/Relationship rows never carry a provenance stamp today, so
+// this is a no-op for them (those tables are not principal-owning).
+//
+// As of v:2 this value is IN the signed payload. The receiver validates
+// it against data.agentId for Memory (PRINCIPAL_OWNING_TABLES); it is
+// no longer informational-only. Credential.principalId is an unrelated
+// owner field — do not grep that path when changing this one.
 function principalIdFromRow(row) {
     if (typeof row?.provenance !== "string" || row.provenance.length === 0)
         return undefined;
@@ -685,6 +690,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 +1476,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 +2667,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.
@@ -2954,7 +3007,7 @@ program
     .option("--no-mcp", "Skip MCP client wiring (instance + agent only)")
     .option("--skip-smoke", "Skip the MCP smoke test")
     .option("--skip-claude-md", "Skip appending the Flair bootstrap line to CLAUDE.md (claude-code only)")
-    .option("--skip-hook", "Skip installing the flair-session-start SessionStart hook (claude-code only)")
+    .option("--skip-hook", "Skip installing the flair-session-start SessionStart hook (claude-code and Codex)")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .option("--remote", "When used with --target, init as hub for remote federation")
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
@@ -3816,6 +3869,18 @@ program
                     }
                     wiringResults.push({ client: clientId, message: result.message, wired: result.ok });
                     console.log(`   ${result.ok ? "✓" : "•"} ${result.message}`);
+                    // Codex SessionStart hook (flair#1148 / #1439) — the hook is not
+                    // optional on Codex (no CLAUDE.md alternative). Init is the
+                    // consent to set up the client, same as the Claude Code hook
+                    // applied above. --skip-hook opts out and prints the JSON.
+                    if (clientId === "codex" && result.ok) {
+                        const hookResult = applyOrReportSessionStartHook(homedir(), agentId, !!opts.skipHook, hookSettingsPath(homedir(), "codex"));
+                        console.log(`   ${hookResult.ok ? "✓" : "•"} ${hookResult.message}`);
+                        if (hookResult.hint) {
+                            for (const line of hookResult.hint.split("\n"))
+                                console.log(`   ${line}`);
+                        }
+                    }
                 }
             }
         }
@@ -4573,18 +4638,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 +4660,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 +4689,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 +4753,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 +4779,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 +4800,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 +6184,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 +6281,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 +6295,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)")}`);
@@ -6895,22 +7047,40 @@ export async function runFederationSyncOnce(opts) {
                 // batch. Closes the hub-relay forgery hole — see
                 // resources/Federation.ts FederationSync.post's verification gate.
                 //
-                // CONTRACT — must match Federation.ts's verification payload
-                // byte-for-byte: keys { v, table, id, data, updatedAt,
-                // originatorInstanceId }. canonicalize() sorts keys, so field ORDER
-                // doesn't matter, but the field SET and values do. `v: 1` versions the
-                // canonical form itself: bump it on BOTH sides together if the signed
-                // field set ever changes, so an old signature fails closed instead of
-                // silently mis-verifying under a new form.
+                // CONTRACT — must match reconstructRecordVerifyBody
+                // (resources/federation-classify.ts) byte-for-byte. canonicalize()
+                // sorts keys, so field ORDER doesn't matter, but the field SET and
+                // values do. `v` versions the canonical form itself: a v:1
+                // signature cannot verify as v:2 (principalId in the field set).
                 //
-                // Additive/backward-compatible: pre-3a receivers don't read
-                // `signature`/`principalId` at all and merge exactly as before.
-                const signature = signBody({ v: 1, table, id: row.id, data: row, updatedAt, originatorInstanceId }, secretKey);
-                const sr = { table, id: row.id, data: row, updatedAt, originatorInstanceId, signature };
-                // Informational only (see principalIdFromRow) — never verified by the
-                // receiver as proof of authorship. Omitted entirely when the row
-                // carries no write-time provenance stamp.
+                // v: 2 puts principalId in the signed payload when the row carries
+                // a provenance stamp, and puts `v` on the wire so Phase 1
+                // receivers (`const v = record.v ?? 1`) don't default these
+                // records back to 1. Soul/Agent/Relationship have no stamp and
+                // omit principalId; Memory without a stamp also omits it (the
+                // receiver then skips Memory as principal_mismatch — absent is
+                // not an accept).
                 const principalId = principalIdFromRow(row);
+                const signedPayload = {
+                    v: 2,
+                    table,
+                    id: row.id,
+                    data: row,
+                    updatedAt,
+                    originatorInstanceId,
+                };
+                if (principalId)
+                    signedPayload.principalId = principalId;
+                const signature = signBody(signedPayload, secretKey);
+                const sr = {
+                    v: 2,
+                    table,
+                    id: row.id,
+                    data: row,
+                    updatedAt,
+                    originatorInstanceId,
+                    signature,
+                };
                 if (principalId)
                     sr.principalId = principalId;
                 const srBytes = JSON.stringify(sr).length;
@@ -7004,29 +7174,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}`);
@@ -10154,6 +10311,7 @@ program
     .option("--project <name>", "Fabric component name for --target", "flair")
     .option("--no-replicated", "Disable cluster-wide replication for --target (default: replicated=true)")
     .option("--yes", "Skip the confirmation prompt for --target")
+    .option("--install-hooks", "Consent to installing missing SessionStart hooks (claude-code / Codex) during upgrade. The hook executes at every session start — upgrade will not write it unprompted. Interactive runs prompt; non-interactive runs state the gap and withhold ✅ unless this flag is passed.")
     .option("--no-fleet-verify", "Skip the automatic post-upgrade fleet convergence sweep for --target (default: sweep runs — see flair#636)")
     // ── flair#878 ─────────────────────────────────────────────────────────────
     // These existed on `flair deploy` but stopped at the upgrade boundary, so
@@ -10819,20 +10977,16 @@ program
     });
     const verdict = decideAfterVerify(verify, previousFlairVersion);
     if (verdict.kind === "ok") {
-        // flair#1022: the verified facts are unchanged and still stated — the
-        // upgrade did land. What changes is the MARKER and the claim around it.
-        // A run that ended up outside its process manager has not fully
-        // succeeded, so it does not get a ✅, and the line names the property
-        // that is wrong rather than only the ones that are right. The choice
-        // lives in renderVerifiedSummary so it is testable without performing an
-        // upgrade — no CI lane runs this darwin path.
-        const summary = renderVerifiedSummary(verify.version, management);
-        for (const line of summary.lines) {
-            if (summary.degraded)
-                console.error(line);
-            else
-                console.log(line);
-        }
+        // flair#1439: the success marker is the doctor runner's verdict, not
+        // a second, narrower notion of "verified". Launchd detach is one
+        // catalog member; the Codex SessionStart hook is another. Adding a
+        // doctor check widens this claim automatically.
+        const run = await doctorRunAfterUpgrade({
+            management,
+            port,
+            installHooksFlag: !!opts.installHooks,
+        });
+        printVerifiedSummary(renderVerifiedSummary(verify.version, run));
         return;
     }
     // flair#741 follow-through: a healthy instance the verifier just couldn't
@@ -10844,21 +10998,23 @@ program
     // "print an honest note but roll back anyway" branch that used to sit below
     // is gone — that credentials case can no longer reach the rollback path.)
     if (verdict.kind === "healthy-unverified") {
-        // flair#1022: same rule as the "ok" branch above — the ✅ is withheld
-        // when the run left the instance outside launchd, and the reason is
-        // named. This branch already qualifies the version claim; the process
-        // manager is a second, independent qualification.
-        console.log(detached
-            ? `⚠️  upgrade complete: the instance is up and healthy${expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : ""}, but NOT under launchd.`
-            : `✅ upgrade complete: the instance is up and healthy${expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : ""}.`);
+        // Same doctor runner as the "ok" branch — an unverified version must
+        // not restore the unqualified ✅ while a catalog member is failing.
+        const run = await doctorRunAfterUpgrade({
+            management,
+            port,
+            installHooksFlag: !!opts.installHooks,
+        });
+        const versionNote = expectedFlairVersion ? ` on @tpsdev-ai/flair@${expectedFlairVersion}` : "";
+        if (run.healthy) {
+            console.log(`✅ upgrade complete: the instance is up and healthy${versionNote}.`);
+        }
+        else {
+            printVerifiedSummary(renderVerifiedSummary(verify.version, run, { authenticated: false }));
+        }
         console.log(`   The version could not be verified — the checker couldn't authenticate to /HealthDetail (${verdict.reason}).`);
         console.log("   The server is confirmed running (public /Health passed); this is a verification gap, not an upgrade failure — nothing was rolled back.");
         console.log("   To enable full post-upgrade verification: set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key.");
-        if (detached) {
-            for (const line of renderDetachedWarning(management, "The instance is NOT running under launchd.")) {
-                console.error(line);
-            }
-        }
         return;
     }
     console.error(`❌ post-restart verification failed: ${verdict.reason}`);
@@ -11177,6 +11333,83 @@ function resolveInstanceServingPid(dataDir, port) {
         listeningPids,
     });
 }
+/** Agent signing-key ids under `keysDir` — node-scoped federation keys excluded. */
+function collectKeyAgentIds(keysDir) {
+    if (!existsSync(keysDir))
+        return [];
+    try {
+        const keyFiles = readdirSync(keysDir).filter((f) => f.endsWith(".key"));
+        const { agentKeyIds } = partitionKeyIds(keyFiles.map((f) => f.replace(/\.key$/, "")), keysDir);
+        return agentKeyIds;
+    }
+    catch {
+        return [];
+    }
+}
+async function confirmYes(question) {
+    if (!process.stdin.isTTY)
+        return false;
+    const { createInterface } = await import("node:readline");
+    const rl = createInterface({ input: process.stdin, output: process.stdout });
+    const answer = await new Promise((res) => rl.question(question, (a) => { rl.close(); res(a); }));
+    return /^y(es)?$/i.test(answer.trim());
+}
+/**
+ * flair#1439 — run the enumerable doctor catalog after upgrade's instance
+ * probe, and offer a consented SessionStart-hook install when that check
+ * fails. Silent writes are refused: `--install-hooks` or an interactive
+ * yes is the only consent. The consent→write composition lives in
+ * applyUpgradeHookConsent so tests can drive the path that actually
+ * writes (or does not write) the hook file.
+ */
+async function doctorRunAfterUpgrade(args) {
+    const homeDir = homedir();
+    const keysDir = defaultKeysDir();
+    const ctx = {
+        homeDir,
+        cwd: process.cwd(),
+        detectedClientIds: detectClients().filter((c) => c.detected).map((c) => c.id),
+        launchd: args.management,
+        keysDir,
+        keyAgentIds: collectKeyAgentIds(keysDir),
+    };
+    const run = runDoctorChecks(ctx);
+    const apply = (promptAccepted) => applyUpgradeHookConsent({
+        homeDir,
+        ctx,
+        run,
+        installHooksFlag: args.installHooksFlag,
+        interactive: !!process.stdin.isTTY,
+        promptAccepted,
+        port: args.port,
+    });
+    let outcome = apply();
+    if (outcome.consent === "prompt" && outcome.prompt) {
+        console.log("");
+        for (const line of outcome.prompt.preamble)
+            console.log(`  ${line}`);
+        outcome = apply(await confirmYes(outcome.prompt.question));
+    }
+    if (outcome.consent === "install") {
+        for (const w of outcome.writes) {
+            console.log(`   ${w.ok ? "✓" : "•"} ${w.message}`);
+        }
+    }
+    if (outcome.consent === "skip-noninteractive") {
+        for (const line of outcome.messages) {
+            console.error(`   ${line}`);
+        }
+    }
+    return outcome.run;
+}
+function printVerifiedSummary(summary) {
+    for (const line of summary.lines) {
+        if (summary.degraded)
+            console.error(line);
+        else
+            console.log(line);
+    }
+}
 /**
  * Observe whether `dataDir`'s instance is running under launchd right now.
  *
@@ -12918,8 +13151,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 —
@@ -12935,11 +13168,27 @@ program
         return /^y(es)?$/i.test(answer.trim());
     }
     const detectedClients = detectClients().filter((c) => c.detected);
+    // flair#1439 — install-health (MCP, FLAIR_URL, CLAUDE.md, SessionStart
+    // hook, verified-read plan, keys classification, launchd) is the same
+    // catalog upgrade asserts. Adding a check to DOCTOR_CHECK_IDS widens
+    // both. Extra doctor UX (pi, --fix, execution probe, continuity,
+    // agent registration) stays below and does not redefine those checks.
+    const doctorCtx = {
+        homeDir: homedir(),
+        cwd: process.cwd(),
+        detectedClientIds: detectedClients.map((c) => c.id),
+        launchd: observeLaunchdManagement(defaultDataDir(), effectivePort),
+        keysDir,
+        keyAgentIds,
+        agentFlag: typeof opts.agent === "string" ? opts.agent : undefined,
+    };
+    const catalogBefore = runDoctorChecks(doctorCtx);
     if (detectedClients.length === 0) {
         console.log(`  ${render.icons.info} No MCP client detected — skipping client-integration checks`);
     }
     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 +13368,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 +13416,13 @@ program
                                             client.id === "antigravity" ? wireAntigravity(wireEnv) :
                                                 wireCursor(wireEnv);
                                 console.log(`     ${wireResult.ok ? render.icons.ok : render.icons.warn} ${wireResult.message}`);
-                                if (wireResult.ok)
-                                    fixed++;
+                                if (wireResult.ok) {
+                                    if (client.id === "claude-code")
+                                        claudeCodeAgentId = fixAgentId;
+                                    if (client.id === "codex")
+                                        codexAgentId = fixAgentId;
+                                    anyKnownAgentId = anyKnownAgentId ?? fixAgentId;
+                                }
                             }
                         }
                     }
@@ -13180,7 +13436,6 @@ program
                     const agentHint = knownAgentId ? "" : fixCommandAgentHint(keyAgentIds);
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix${agentHint} ${render.wrap(render.c.dim, `(wires ${client.label} automatically)`)}`);
                 }
-                issues++;
                 continue;
             }
             console.log(`  ${render.icons.ok} ${client.label}: MCP server configured (${render.wrap(render.c.dim, block.configPath)})`);
@@ -13216,8 +13471,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) {
@@ -13237,15 +13493,12 @@ program
                         else {
                             const fixRes = fixClaudeMdBootstrap(process.cwd());
                             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 doctor --fix ${render.wrap(render.c.dim, "(adds the mcp__flair__bootstrap line to ./CLAUDE.md)")}`);
                 }
-                issues++;
             }
             // flair#1007: presence was never the problem — the failing entry was
             // perfectly well-formed. inspectSessionStartHook() additionally RUNS
@@ -13314,8 +13567,6 @@ program
                                 else {
                                     const upgrade = upgradeSessionStartHookCommand(homedir());
                                     console.log(`     ${upgrade.ok ? render.icons.ok : render.icons.warn} ${upgrade.message}`);
-                                    if (upgrade.ok && upgrade.changed)
-                                        fixed++;
                                 }
                             }
                         }
@@ -13326,7 +13577,6 @@ program
                     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`);
                     }
-                    issues++;
                 }
             }
             else {
@@ -13344,15 +13594,12 @@ program
                             const fixAgentId = claudeCodeAgentId || opts.agent || process.env.FLAIR_AGENT_ID;
                             const fixRes = fixSessionStartHook(homedir(), fixAgentId);
                             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 doctor --fix ${render.wrap(render.c.dim, "(adds the flair-session-start SessionStart hook)")}`);
                 }
-                issues++;
             }
             // flair#1257 slice 2 — continuity capture pair (the check-5 twin of
             // the SessionStart check above: installed / absent / stale-form).
@@ -13407,6 +13654,98 @@ 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}`);
+                                }
+                            }
+                        }
+                        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`);
+                    }
+                }
+            }
+            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}`);
+                        }
+                    }
+                }
+                else {
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install --harness codex`);
+                }
+            }
+        }
+    }
+    // Catalog is the install-health verdict — count fail/unrun here, not
+    // via a second issues++ on MCP / CLAUDE.md / SessionStart hook above.
+    // --fix that cleared a catalog member shows up in the found→fixed delta.
+    const catalogAfter = autoFix ? runDoctorChecks(doctorCtx) : catalogBefore;
+    const catalogDelta = catalogIssueDelta(catalogBefore, catalogAfter);
+    issues += catalogDelta.found;
+    if (autoFix)
+        fixed += catalogDelta.fixed;
+    console.log(`\n  ${render.wrap(render.c.bold, "Install health")}`);
+    for (const row of renderCatalogDoctorLines(catalogAfter)) {
+        console.log(`  ${render.icons[row.icon]} ${row.line}`);
     }
     // 7a. Resolve which agent identities the two verified-read sections below
     // (Fleet presence, Migrations) iterate (flair#722). Previously both
@@ -13806,7 +14145,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 +14209,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 +14617,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 +14665,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 +14883,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 +15367,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 +15382,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 +15423,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 +16673,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 +16887,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");