@tpsdev-ai/flair 0.41.0 → 0.44.0

package/config.yaml

@@ -1,100 +1,29 @@
 name: flair
 rest: true
-
-## Port is configured via CLI (flair init --port) or HTTP_PORT env var.
-## Omitted here to avoid conflicts with different deployment scenarios.
-# http:
-#   port: 19926
-
-# Harper does not read a component's `.env` implicitly — it only loads env
-# files a component ASKS for, via this plugin. Without this block a `.env`
-# sitting next to config.yaml is inert: the file is present and its values
-# never reach `process.env`. That is exactly what a deployed instance hit —
-# `FLAIR_PUBLIC_URL` was set in the deployed component's `.env` and OAuth
-# discovery kept advertising a loopback issuer (flair#1005, #1000).
-#
-# MUST STAY FIRST. Config keys are iterated in file order by Harper's
-# component loader, and each plugin's initial entry load is awaited before
-# the next key is processed — so declaring this above `jsResource` is what
-# guarantees `process.env` is populated before `dist/resources/*.js` are
-# imported. Most consumers read `process.env` per request and would not care
-# (resources/OAuth.ts, resources/AdminInstance.ts, resources/XAA.ts,
-# resources/a2a-url.ts), but `resources/mcp-oauth.ts` decides at MODULE LOAD
-# whether to mount `/mcp`; move this below `jsResource` and that decision is
-# made against an env that has not been loaded yet.
-#
-# No `.env` is required, which is the case for essentially every local
-# install: when the glob matches nothing the plugin never fires and emits
-# nothing. Measured — a boot log with this block and no `.env` differs from
-# one without the block only in the PID and in non-deterministic table-init
-# ordering. (A MALFORMED declaration is loud, not silent: a pattern
-# containing '..' produced both an `Ignoring invalid loadEnv files pattern`
-# warning and a `Could not load component 'loadEnv'` error, which is the
-# positive control for that silence.)
-#
-# Application variables only. Harper composes its OWN configuration before
-# component `.env` files load, so Harper-level settings cannot be set this
-# way; `HARPER_CONFIG` / `HARPER_DEFAULT_CONFIG` / `HARPER_SET_CONFIG` are
-# refused at the injection point and warned about (harper#1513). Those
-# belong in the process environment or harper-config.yaml.
 loadEnv:
-  files: '.env'
-
+  files: .env
 graphqlSchema:
   files: schemas/*.graphql
-
 jsResource:
   files: dist/resources/*.js
-
-# Phase 1 (flair#504): embeddings now run through Harper's native
-# models.embed() facade, backed by harper-fabric-embeddings registered as the
-# `embedding` backend. That registration is NOT configured here, and (as of
-# flair#694) is no longer config-driven anywhere: a `models:` block in THIS
-# file would silently never be read (this application always loads with
-# `isRoot: false` — components/componentLoader.ts gates `bootstrapModels()`
-# on `isRoot`), and the earlier fix for that — reasserting the block into the
-# Harper INSTANCE-ROOT config via the HARPER_CONFIG env var on every spawn —
-# turned out to PERSIST that block into harper-config.yaml, which an
-# older/downgraded build's boot (never having set the env var) would tear
-# down to an invalid empty shell and refuse to boot against (flair#694; see
-# flair#695 for the invariant this violated). The registration now happens
-# in-process instead: `dist/resources/embeddings-boot.js` (built from
-# resources/embeddings-boot.ts, loaded by the `jsResource` glob below like
-# every other file under resources/) calls harper-fabric-embeddings'
-# `register()` factory directly on every boot — nothing is ever written to
-# the config file, so there is nothing for a downgrade to trip over. This
-# also means a `package:`-style sub-component entry
-# (`'harper-fabric-embeddings': { package: ... }`, which used to sit here and
-# drove `handleApplication`) still must not be reintroduced alongside it —
-# that hook populates a SEPARATE raw-API engine, not `models.embed()`, and
-# running both would double-init (two separate EmbeddingEngine instances:
-# one unused, one backing models.embed).
-
 authentication:
-  # Default secure (flair#654): a credential-less loopback request to the
-  # Harper ops API (:9925) is no longer auto-authorized as super_user. Local
-  # admin operations now require a real credential — ~/.flair/admin-pass
-  # (written by `flair init`), --admin-pass, or FLAIR_ADMIN_PASS. flair's own
-  # application-layer resources were already immune to this forgery (#655's
-  # credential-evidence gate); this closes the remaining gap below it, in the
-  # raw Harper ops API itself. Set true only for local development, at your
-  # own risk.
   authorizeLocal: false
   enableSessions: true
-
-# @harperfast/oauth — authorization server component declaration.
-# Commented out by default: the plugin is only needed when FLAIR_MCP_OAUTH=on.
-# When you enable the flag without uncommenting this block, the boot guard
-# (resources/mcp-oauth.ts) logs an error with the exact YAML to add — uncomment
-# the block below and add mcp.* config. The issuer is derived at runtime from
-# FLAIR_MCP_ISSUER / FLAIR_PUBLIC_URL; do not hardcode one here.
-#
-# "@harperfast/oauth":
-#   providers:
-#     default:
-#       authorizationEndpoint: "/OAuthAuthorize"
-#       tokenEndpoint: "/OAuthToken"
-#       revocationEndpoint: "/OAuthRevoke"
-#       registrationEndpoint: "/OAuthRegister"
-#       jwksUri: "/.well-known/jwks.json"
-#       discoveryEndpoint: "/.well-known/oauth-authorization-server"
+'@harperfast/oauth':
+  package: '@harperfast/oauth'
+  providers:
+    github:
+      clientId: ${OAUTH_GITHUB_CLIENT_ID}
+      clientSecret: ${OAUTH_GITHUB_CLIENT_SECRET}
+  mcp:
+    enabled: false
+    issuer: ${FLAIR_MCP_ISSUER}
+    resource: ${FLAIR_MCP_ISSUER}/mcp
+    accessTokenTtl: 900
+    dynamicClientRegistration:
+      enabled: false
+    clientIdMetadataDocuments:
+      allowedHosts:
+        - claude.ai
+        - claude.com
+    signingKeyPem: ${FLAIR_MCP_SIGNING_KEY_PEM}

package/dist/cli.js

@@ -19,7 +19,7 @@ import { checkServerHandshake, formatHandshakeNudge, invalidateHandshakeCache }
 import { probeInstance } from "./probe.js";
 import { sweepFleet, renderFleetSweepTable, FLEET_EXIT_OK, } from "./fleet-verify.js";
 import { markStale, sortOldestVersionFirst } from "./fleet-presence.js";
-import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
+import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemini, wireCursor, clientConfigPath, codexConfigHasFlairSection } from "./install/clients.js";
 import { flairCliVersion, mcpServerSpec, unpinnedSpecWarning } from "./lib/mcp-spec.js";
 import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, defaultMcpIssuer, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
 import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMcpMetadata, } from "./lib/mcp-enable.js";
@@ -136,6 +136,7 @@ function shouldShowInlineSecretWarning(optValue, fromEnv, secretFlagNames, flagN
 // ─── Defaults ────────────────────────────────────────────────────────────────
 const DEFAULT_PORT = 19926;
 const DEFAULT_OPS_PORT = 19925;
+const FABRIC_OPS_PORT = 9925;
 const DEFAULT_ADMIN_USER = "admin";
 const STARTUP_TIMEOUT_MS = 60_000;
 const HEALTH_POLL_INTERVAL_MS = 500;
@@ -1076,10 +1077,15 @@ function resolveOpsTarget(opts) {
     return opts.opsTarget || process.env.FLAIR_OPS_TARGET || undefined;
 }
 /** Derive the ops API URL from a Flair base URL.
- *  Convention: ops port = HTTP port - 1.
- *  If target has an explicit port, use port-1 (validated: must be 1-65535).
- *  If no explicit port: https → 442 (443-1), http → 19925 (19926-1), bare host → https://<host>:19925.
- *  Throws on unparseable URLs.
+ *  https with effective port 443 (no explicit port, or explicit :443): returns
+ *    <host>:9925 (FABRIC_OPS_PORT) — the Fabric managed case where port-1/:442
+ *    is a dead-end.
+ *  All other cases unchanged:
+ *    https with non-443 explicit port → port-1 (self-hosted TLS: 19926→19925, 8443→8442)
+ *    http with explicit port → port-1 (19926→19925)
+ *    http with no port → DEFAULT_OPS_PORT (19925)
+ *  Bare hosts are normalised to https:// (effective-443 → Fabric path).
+ *  Throws on unparseable URLs or out-of-range ports.
  */
 /** Compute the effective ops API URL for remote commands.
  *  - If --ops-target is set, use it directly (no derivation).
@@ -1099,6 +1105,17 @@ function resolveOpsUrlFromTarget(targetUrl) {
     // Normalise bare hosts: add https:// prefix so URL parser can handle them.
     const normalised = targetUrl.includes("://") ? targetUrl : `https://${targetUrl}`;
     const url = new URL(normalised);
+    // https target with effective port 443 (no explicit port, or explicit :443):
+    // this is the Fabric managed case — the ops API is on the well-known Fabric
+    // ops port, never REST-adjacent. The port-1 / :442 logic is a dead-end here.
+    if (url.protocol === "https:" && (url.port === "" || url.port === "443")) {
+        url.port = String(FABRIC_OPS_PORT);
+        return url.toString().replace(/\/$/, "");
+    }
+    // All other cases: unchanged port-1 convention.
+    //   https with non-443 explicit port → port-1 (self-hosted TLS: 19926→19925, 8443→8442)
+    //   http with explicit port → port-1 (19926→19925)
+    //   http with no port → DEFAULT_OPS_PORT (19925)
     const port = parseInt(url.port, 10);
     if (!isNaN(port) && port > 0 && port <= 65535) {
         const opsPort = port - 1;
@@ -1111,13 +1128,8 @@ function resolveOpsUrlFromTarget(targetUrl) {
     if (url.port !== "" && url.port !== undefined) {
         throw new Error(`Invalid target port: ${url.port} (must be 1-65535)`);
     }
-    // No explicit port — infer from scheme
-    if (url.protocol === "https:") {
-        url.port = "442";
-    }
-    else {
-        url.port = String(DEFAULT_OPS_PORT);
-    }
+    // No explicit port on http — use the default ops port.
+    url.port = String(DEFAULT_OPS_PORT);
     return url.toString().replace(/\/$/, "");
 }
 /**
@@ -1340,11 +1352,9 @@ function b64url(bytes) {
  * out of scope for this HTTP/REST auth path.
  */
 async function api(method, path, body, options) {
-    // Resolve port: FLAIR_URL env > ~/.flair/config.yaml > default 9926
-    // When baseUrl is provided (--target), use it directly.
-    const savedPort = readPortFromConfig();
-    const defaultUrl = savedPort ? `http://127.0.0.1:${savedPort}` : `http://127.0.0.1:${DEFAULT_PORT}`;
-    const base = options?.baseUrl ?? (process.env.FLAIR_URL || defaultUrl);
+    // Resolve port via the canonical path (flair#1129): options.baseUrl > FLAIR_URL > resolveHttpPort.
+    // api() callers mean the default install, so resolveHttpPort({}) with no --data-dir is correct.
+    const base = options?.baseUrl ?? (process.env.FLAIR_URL || `http://127.0.0.1:${resolveHttpPort({})}`);
     // Extract agentId from FLAIR_AGENT_ID env, or the body (POST/PUT) / URL
     // query params (GET) — Harper-CLI-request-shape knowledge, not a generic
     // auth concern, so it stays here rather than in authedRequest.
@@ -1784,12 +1794,21 @@ export async function seedFederationInstanceViaOpsApi(opsPortOrUrl, instanceId,
 export async function callOpsApi(opsUrl, body, user, pass) {
     const url = `${opsUrl.replace(/\/$/, "")}/`;
     const auth = Buffer.from(`${user}:${pass}`).toString("base64");
-    const res = await fetch(url, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
-        body: JSON.stringify(body),
-        signal: AbortSignal.timeout(30_000),
-    });
+    let res;
+    try {
+        res = await fetch(url, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", ...(auth ? { Authorization: `Basic ${auth}` } : {}) },
+            body: JSON.stringify(body),
+            signal: AbortSignal.timeout(30_000),
+        });
+    }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        throw new Error(`ops API unreachable at ${opsUrl} (derived from --target). ` +
+            `Set --ops-target or FLAIR_OPS_TARGET to override. ` +
+            `(${message})`);
+    }
     if (!res.ok) {
         const text = await res.text().catch(() => "");
         throw new Error(`Ops API call failed (${res.status}): ${text}`);
@@ -3356,7 +3375,13 @@ program
                             ? JSON.parse(readFileSync(claudeJsonPath, "utf-8"))
                             : {};
                         const existing = claudeJson.mcpServers?.flair;
-                        if (existing && existing.env?.FLAIR_URL === httpUrl && existing.env?.FLAIR_AGENT_ID === agentId) {
+                        const currentSpec = mcpServerSpec();
+                        const existingArgs = existing?.args;
+                        const argsMatch = Array.isArray(existingArgs) && existingArgs.includes(currentSpec);
+                        const urlAgentMatch = existing && existing.env?.FLAIR_URL === httpUrl && existing.env?.FLAIR_AGENT_ID === agentId;
+                        // flair#1135: the pin in `args` must match the current mcpServerSpec().
+                        // A matching pin stays a no-op (idempotent); only a stale pin triggers a re-write.
+                        if (urlAgentMatch && argsMatch) {
                             console.log(`   ✓ Claude Code already wired in ~/.claude.json`);
                             wiringResults.push({ client: "claude-code", message: "already wired", wired: true });
                         }
@@ -3364,11 +3389,15 @@ program
                             claudeJson.mcpServers = claudeJson.mcpServers || {};
                             claudeJson.mcpServers.flair = flairMcpConfig;
                             writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
-                            const how = claudeJsonExisted ? "wired in ~/.claude.json" : "wired in ~/.claude.json (created)";
-                            console.log(`   ✓ Claude Code ${how} (restart Claude Code to pick it up)`);
+                            const action = urlAgentMatch ? "refreshed pin in ~/.claude.json"
+                                : claudeJsonExisted ? "wired in ~/.claude.json"
+                                    : "wired in ~/.claude.json (created)";
+                            console.log(`   ✓ Claude Code ${action} (restart Claude Code to pick it up)`);
                             wiringResults.push({
                                 client: "claude-code",
-                                message: claudeJsonExisted ? "wired ~/.claude.json" : "created and wired ~/.claude.json",
+                                message: urlAgentMatch ? "refreshed pin in ~/.claude.json"
+                                    : claudeJsonExisted ? "wired ~/.claude.json"
+                                        : "created and wired ~/.claude.json",
                                 wired: true,
                             });
                         }
@@ -4811,7 +4840,7 @@ mcp
     const adminPass = dryRun ? (opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "") : resolveLocalAdminPass(opts.adminPass, /* isRemoteTarget */ true);
     if (!dryRun && !adminPass) {
         console.error("Error: --admin-pass <pass> or --admin-pass-file <path> is required for a REMOTE target " +
-            "(the operations API on the target instance needs it for identity mapping + set_configuration + restart).\n" +
+            "(the operations API on the target instance needs it for identity mapping + restart).\n" +
             "  FLAIR_ADMIN_PASS and ~/.flair/admin-pass are deliberately NOT used here: they are THIS machine's " +
             "local admin credentials, and sending them to another instance is how a local secret ends up on someone " +
             "else's Harper. Pass the target's own admin password explicitly.");
@@ -4865,7 +4894,20 @@ mcp
         process.exit(1);
     }
     if (!result.ok) {
-        console.error(`${render.icons.error} enable failed at step "${result.failedStep}" — see detail above for the exact fix, then re-run \`flair mcp enable\` (earlier steps are idempotent and will be reused).`);
+        if (result.failedStep === "fabric-operator-deploy") {
+            // flair#1136: Fabric deployments require the operator to deploy the
+            // config change — we can't write to harperdb-config.yaml (Fabric
+            // regenerates it on every container restart).
+            console.error(`\n${render.icons.info} ${render.wrap(render.c.bold, "Fabric deployment detected.")}`);
+            console.error(`   The @harperfast/oauth block ships in your component config.yaml with mcp.enabled: false.`);
+            console.error(`   To activate: set mcp.enabled: true (literal boolean) in your deployed component`);
+            console.error(`   config.yaml, ensure the staged secrets are live in the instance's process`);
+            console.error(`   environment, and redeploy. Then re-run \`flair mcp enable\` — earlier steps`);
+            console.error(`   are idempotent and will be reused.\n`);
+        }
+        else {
+            console.error(`${render.icons.error} enable failed at step "${result.failedStep}" — see detail above for the exact fix, then re-run \`flair mcp enable\` (earlier steps are idempotent and will be reused).`);
+        }
         process.exit(1);
     }
     if (result.dryRun) {
@@ -9866,6 +9908,55 @@ program
         authedGet: (path) => verifyAuthedGet(baseUrl, path, defaultKeysDir()),
     });
     const verdict = decideAfterVerify(verify, previousFlairVersion);
+    // ── Refresh wired MCP client configs (flair#1135) ──────────────────────
+    // After a successful upgrade, the flair-mcp package on disk is newer than
+    // the pinned version in wired client configs. Re-run wiring for
+    // already-wired clients so the pin stays in lockstep with the installed
+    // version. Best-effort: failures warn but never fail the upgrade.
+    const refreshWiredClients = async () => {
+        const agentId = resolveAgentIdOrEnv({}) ?? (() => {
+            try {
+                const keyFiles = readdirSync(defaultKeysDir()).filter((f) => f.endsWith(".key"));
+                return keyFiles.length > 0 ? keyFiles[0].replace(/\.key$/, "") : null;
+            }
+            catch {
+                return null;
+            }
+        })();
+        if (!agentId) {
+            console.log("\n   (no agent id known — skip MCP client pin refresh; run `flair init` to refresh manually)");
+            return;
+        }
+        const httpUrl = `http://127.0.0.1:${upgradePort}`;
+        const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
+        const detected = detectClients().filter(c => c.detected);
+        if (detected.length === 0)
+            return;
+        console.log("\n   Refreshing MCP client pins...");
+        for (const client of detected) {
+            const configPath = clientConfigPath(client.id);
+            if (!existsSync(configPath))
+                continue;
+            // Only refresh clients that are already wired — don't wire new ones.
+            let hasFlair = false;
+            try {
+                const raw = readFileSync(configPath, "utf-8");
+                if (client.id === "codex") {
+                    hasFlair = codexConfigHasFlairSection(raw);
+                }
+                else {
+                    const cfg = JSON.parse(raw);
+                    hasFlair = !!cfg.mcpServers?.flair;
+                }
+            }
+            catch { /* unreadable/malformed — skip */ }
+            if (!hasFlair)
+                continue;
+            const env = { ...mcpEnv, FLAIR_CLIENT: client.id };
+            const result = client.wire(env);
+            console.log(`   ${result.ok ? "✓" : "•"} ${result.message}`);
+        }
+    };
     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.
@@ -9881,6 +9972,7 @@ program
             else
                 console.log(line);
         }
+        await refreshWiredClients();
         return;
     }
     // flair#741 follow-through: a healthy instance the verifier just couldn't
@@ -9907,6 +9999,7 @@ program
                 console.error(line);
             }
         }
+        await refreshWiredClients();
         return;
     }
     console.error(`❌ post-restart verification failed: ${verdict.reason}`);
@@ -12013,22 +12106,34 @@ program
             const hook = inspectSessionStartHook(homedir());
             if (hook.present) {
                 if (hook.execution === "broken") {
-                    // Reported in full, with the remedy — but NOT counted as an issue,
-                    // so it never flips doctor's exit code on its own. This is a
-                    // verification of the environment at the moment doctor runs (a
-                    // cold `npx` cache, an offline machine, a slow registry), exactly
-                    // like the FLAIR_URL reachability and agent-registration
-                    // verifications above, which are warnings for the same reason. A
-                    // fresh, correct install on a machine that simply has not fetched
-                    // the adapter yet must not be told it is broken in the exit code.
-                    // The unsilenced finding below IS counted: that one is a fact
-                    // about the file, true regardless of the environment.
-                    console.log(`  ${render.icons.warn} SessionStart hook: 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, "If this persists, the Node runtime probably changed and the globally")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "installed @tpsdev-ai/flair-mcp no longer resolves for it.")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} npm install -g @tpsdev-ai/flair-mcp ${render.wrap(render.c.dim, "(reinstall for the runtime you use now)")}`);
-                    console.log(`     ${render.wrap(render.c.dim, "Or, if you no longer want ambient memory:")} flair hook uninstall`);
+                    // Two very different states that share one probe outcome:
+                    //
+                    // 1. Silenced (current) command that didn't run — the npx cache
+                    //    is cold, the machine is offline, or the adapter hasn't been
+                    //    fetched yet.  On a fresh install this is NORMAL: the hook is
+                    //    wired but no Claude Code session has exercised it yet.
+                    //    Report as informational, not a warning, and never suggest
+                    //    reinstall — the setup is correct, the environment just
+                    //    hasn't warmed yet.
+                    //
+                    // 2. Unsilenced (legacy) command that didn't run — the hook has
+                    //    been in place long enough that a cold cache is not the
+                    //    explanation.  This IS a genuine failure: warn and name the
+                    //    actual state with a fitting remedy.
+                    if (hook.silenced) {
+                        console.log(`  ${render.icons.ok} SessionStart hook: 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 Claude Code session will warm the npx cache.")}`);
+                    }
+                    else {
+                        console.log(`  ${render.icons.warn} SessionStart hook: 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, "The hook command could not be executed. Check that npx can resolve")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "@tpsdev-ai/flair-mcp — a cold cache, missing global install, or network")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "issue can prevent the adapter from running on its first invocation.")}`);
+                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${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: wired in ${render.wrap(render.c.dim, hook.path)}, but could not be verified ${render.wrap(render.c.dim, `(${hook.detail ?? "no detail"})`)}`);
@@ -15508,8 +15613,7 @@ program
         if (!dryRun) {
             console.log(`    Writing to Flair...`);
             try {
-                const DEFAULT_PORT = 19926;
-                const httpUrl = `http://127.0.0.1:${DEFAULT_PORT}`;
+                const httpUrl = `http://127.0.0.1:${resolveHttpPort({})}`;
                 const agentKeyId = `${agentId}.key`;
                 const keysDir = join(homedir(), ".flair", "keys");
                 const keyPath = join(keysDir, agentKeyId);
@@ -15987,7 +16091,7 @@ if (import.meta.main) {
 // ─── Exported for testing ─────────────────────────────────────────────────────
 export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, readOpsBindFromConfig, readOpsPortFromConfig, writeConfig, resolveHttpPort, resolveOpsPort, resolveOpsBindHost, 
 // Harper's own config — the per-instance port record (flair#914)
-harperConfigPath, readHarperConfig, readPortFromHarperConfig, persistDefaultInstallCoordinates, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
+harperConfigPath, readHarperConfig, readPortFromHarperConfig, persistDefaultInstallCoordinates, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, FABRIC_OPS_PORT, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
 // launchd label (flair#693)
 LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, cleanupLegacyLaunchdPlist, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, 
 // launchd management observation (flair#1022)

package/dist/doctor-client.js

@@ -41,7 +41,7 @@ export const SESSION_START_HOOK_MARKER = "flair-session-start";
 //
 // WHY THE INVOCATION IS WRAPPED
 // -----------------------------
-// The hook runs `npx -y @tpsdev-ai/flair-mcp flair-session-start`: it resolves
+// The hook runs `npx -y -p @tpsdev-ai/flair-mcp flair-session-start`: it resolves
 // a package binary through whatever Node runtime the user's shell happens to
 // expose. Under a Node version manager, globally installed packages are
 // per-runtime-version, so a routine and entirely unrelated runtime upgrade
@@ -117,7 +117,7 @@ export function buildSessionStartHookCommand(agentId, flairUrl) {
         throw new Error(`Flair URL '${flairUrl}' contains characters that cannot be safely written into a shell hook command (allowed: letters, digits, . _ : / -)`);
     }
     const env = flairUrl ? `FLAIR_AGENT_ID=${agentId} FLAIR_URL=${flairUrl}` : `FLAIR_AGENT_ID=${agentId}`;
-    const invocation = `${env} npx -y @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
+    const invocation = `${env} npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`;
     return `sh -c 'out=$(${invocation} 2>/dev/null) && printf %s "$out" || true'`;
 }
 /**
@@ -525,6 +525,18 @@ export function inspectSessionStartHook(homeDir, opts = {}) {
     const verdict = classifyHookProbe(outcome);
     return { path: found.path, present: true, command, ours, silenced, upgradable, execution: verdict.execution, detail: verdict.detail };
 }
+export function classifyHookReadiness(report) {
+    if (!report.present)
+        return "absent";
+    if (!report.ours)
+        return "custom";
+    if (report.execution === "runs")
+        return "runs";
+    if (report.execution === "broken") {
+        return report.silenced ? "not-yet-exercised" : "genuinely-broken";
+    }
+    return "unverified";
+}
 /**
  * Rewrite an existing Flair-authored hook command to the current canonical
  * form, in place, preserving the agent id and URL the entry already carries —

package/dist/hook-install.js

@@ -344,7 +344,7 @@ export function hookStatus(homeDir, harness) {
     }
     const hookEntry = config.hooks.SessionStart[existing.groupIndex].hooks[existing.hookIndex];
     const command = typeof hookEntry?.command === "string" ? hookEntry.command : "";
-    const correctShape = hookEntry?.type === "command" && command.includes(`npx -y @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
+    const correctShape = hookEntry?.type === "command" && command.includes(`npx -y -p @tpsdev-ai/flair-mcp ${SESSION_START_HOOK_MARKER}`);
     const env = parseHookCommandEnv(command);
     return {
         harness, path, wired: true, correctShape,

package/dist/install/clients.js

@@ -165,6 +165,40 @@ export function appendCodexFlairBlock(raw, env) {
     const separator = raw.length === 0 ? "" : raw.endsWith("\n\n") ? "" : raw.endsWith("\n") ? "\n" : "\n\n";
     return raw + separator + tomlSnippet(env) + "\n";
 }
+/**
+ * flair#1135: does the existing `[mcp_servers.flair]` TOML section carry the
+ * CURRENT pinned mcpServerSpec()? Pure string scan — no TOML parser needed
+ * (same rationale as codexConfigHasFlairSection).
+ */
+function codexFlairSectionHasCurrentPin(raw) {
+    const idx = raw.indexOf("[mcp_servers.flair]");
+    if (idx === -1)
+        return false;
+    const after = raw.slice(idx);
+    // Find the end of the section: the next top-level [header] that is NOT a
+    // sub-table of mcp_servers.flair (e.g. [mcp_servers.flair.env] is part of
+    // the same logical section and must not terminate the scan).
+    const nextHeader = after.slice("[mcp_servers.flair]".length).search(/\n\[(?!mcp_servers\.flair\.)/);
+    const section = nextHeader === -1 ? after : after.slice(0, "[mcp_servers.flair]".length + nextHeader);
+    return section.includes(mcpServerSpec());
+}
+/**
+ * flair#1135: replace the existing `[mcp_servers.flair]` TOML section with a
+ * fresh one carrying the current pin. Preserves everything else in the file.
+ */
+function replaceCodexFlairBlock(raw, env) {
+    const idx = raw.indexOf("[mcp_servers.flair]");
+    if (idx === -1)
+        return appendCodexFlairBlock(raw, env);
+    const before = raw.slice(0, idx);
+    const after = raw.slice(idx);
+    const nextHeader = after.slice("[mcp_servers.flair]".length).search(/\n\[(?!mcp_servers\.flair\.)/);
+    const rest = nextHeader === -1 ? "" : after.slice("[mcp_servers.flair]".length + nextHeader);
+    const newBlock = tomlSnippet(env) + "\n";
+    // Preserve the separator between the new block and whatever follows.
+    const sep = rest.length === 0 ? "" : rest.startsWith("\n") ? "" : "\n";
+    return before + newBlock + sep + rest;
+}
 /**
  * Merge the Flair MCP server into a JSON config file with an `mcpServers` map.
  * Creates the file (and parent dir) if absent; preserves existing servers and
@@ -182,13 +216,20 @@ function wireJsonMcp(configPath, label, env) {
         }
         config.mcpServers = config.mcpServers || {};
         const existing = config.mcpServers.flair;
-        if (existing && existing.env?.FLAIR_URL === env.FLAIR_URL && existing.env?.FLAIR_AGENT_ID === env.FLAIR_AGENT_ID) {
+        const currentSpec = mcpServerSpec();
+        const existingArgs = existing?.args;
+        const argsMatch = Array.isArray(existingArgs) && existingArgs.includes(currentSpec);
+        const urlAgentMatch = existing && existing.env?.FLAIR_URL === env.FLAIR_URL && existing.env?.FLAIR_AGENT_ID === env.FLAIR_AGENT_ID;
+        // flair#1135: the pin in `args` must match the current mcpServerSpec().
+        // A matching pin stays a no-op (idempotent); only a stale pin triggers a re-write.
+        if (urlAgentMatch && argsMatch) {
             return { ok: true, message: `${label}: already wired in ${display}` };
         }
         config.mcpServers.flair = flairMcpEntry(env);
         mkdirSync(dirname(configPath), { recursive: true });
         writeFileSync(configPath, JSON.stringify(config, null, 2) + "\n");
-        return { ok: true, message: `${label}: wired ${display} (restart ${label} to pick it up)` };
+        const action = urlAgentMatch ? "refreshed pin in" : "wired";
+        return { ok: true, message: `${label}: ${action} ${display} (restart ${label} to pick it up)` };
     }
     catch (err) {
         const reason = err instanceof Error ? err.message : String(err);
@@ -250,17 +291,23 @@ function _wireCodex(env) {
     // parser, but appending a new top-level table at EOF is safe TOML when the
     // exact header isn't already present (flair#727) — so an existing file only
     // forces the manual-print fallback when it's genuinely unreadable/
-    // unwritable (permissions, I/O error), never merely "exists". A file that
-    // already has the section is reported already-wired, matching the JSON
-    // clients' idempotency (wireJsonMcp above).
+    // unwritable (permissions, I/O error), never merely "exists".
+    //
+    // flair#1135: the "already wired" check is now version-aware — a section
+    // with a stale pin triggers a re-write instead of a no-op.
     const path = codexConfigPath();
     const display = "~/.codex/config.toml";
     try {
         if (existsSync(path)) {
             const raw = readFileSync(path, "utf-8");
-            if (codexConfigHasFlairSection(raw)) {
+            if (codexFlairSectionHasCurrentPin(raw)) {
                 return { ok: true, message: `Codex: already wired in ${display}` };
             }
+            if (codexConfigHasFlairSection(raw)) {
+                // Section exists but pin is stale — replace it.
+                writeFileSync(path, replaceCodexFlairBlock(raw, env));
+                return { ok: true, message: `Codex: refreshed pin in ${display} (restart Codex to pick it up)` };
+            }
             writeFileSync(path, appendCodexFlairBlock(raw, env));
             return { ok: true, message: `Codex: wired ${display} (restart Codex to pick it up)` };
         }

package/dist/lib/mcp-enable.js

@@ -144,6 +144,7 @@ import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync } from "n
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
 import { generateKeyPairSync, randomBytes } from "node:crypto";
+import yaml from "js-yaml";
 // ─── CIMD constants ──────────────────────────────────────────────────────────
 /** Default `clientIdMetadataDocuments.allowedHosts` allowlist — see the
  *  module header's "claude.ai CIMD/redirect-URI allowlist hosts" note for
@@ -285,10 +286,12 @@ export function readSigningKeyFile(path) {
 /**
  * The `@harperfast/oauth` config block, matching the installed 2.2.0
  * package's field names (node_modules/@harperfast/oauth/dist/types.d.ts).
- * Secrets are `${ENV_VAR}` placeholders — never literal values — so this
- * block is safe to write to harperdb-config.yaml via `set_configuration`
- * (the config file itself carries no secret material; see the
- * secrets-provisioning step for how the referenced env vars land).
+ * Secrets are `${ENV_VAR}` placeholders — never literal values.
+ *
+ * flair#1136: set_configuration delivery was removed. Fabric regenerates
+ * the root harperdb-config.yaml; the component's own config.yaml is the
+ * source of truth for the oauth block. This function builds the block that
+ * ships in config.yaml — it is never written to harperdb-config.yaml.
  *
  * flair#756: `dynamicClientRegistration: { enabled: false }` is written
  * EXPLICITLY — never omitted. See the module header's "Leaving
@@ -303,6 +306,7 @@ export function buildMcpOAuthConfigBlock(params) {
     const provider = params.idpProvider;
     const envPrefix = `OAUTH_${provider.toUpperCase()}`;
     const cimdAllowedHosts = params.cimdAllowedHosts ?? DEFAULT_CIMD_ALLOWED_HOSTS;
+    const enabled = params.enabled ?? true;
     return {
         "@harperfast/oauth": {
             package: "@harperfast/oauth",
@@ -313,7 +317,7 @@ export function buildMcpOAuthConfigBlock(params) {
                 },
             },
             mcp: {
-                enabled: true,
+                enabled,
                 issuer: "${FLAIR_MCP_ISSUER}",
                 resource: "${FLAIR_MCP_ISSUER}/mcp",
                 accessTokenTtl: REQUIRED_ACCESS_TOKEN_TTL,
@@ -331,6 +335,85 @@ export function buildMcpOAuthConfigBlock(params) {
         },
     };
 }
+// ─── Local config.yaml update (flair#1136) ──────────────────────────────────
+/**
+ * Flip mcp.enabled in a local component config.yaml. Best-effort: returns
+ * `{ ok: false }` with a reason when the file can't be found or parsed.
+ *
+ * Looks for config.yaml at `explicitPath`, then `./config.yaml`, then
+ * `~/.flair/config.yaml`. When found, replaces `mcp:\n    enabled: false`
+ * with `mcp:\n    enabled: true` (exact string match — avoids a YAML parser
+ * dependency for a single boolean flip).
+ */
+export function updateLocalConfigMcpEnabled(enabled, explicitPath) {
+    const candidates = explicitPath
+        ? [explicitPath]
+        : ["config.yaml", join(homedir(), ".flair", "config.yaml")];
+    let configPath = null;
+    for (const p of candidates) {
+        if (existsSync(p)) {
+            configPath = p;
+            break;
+        }
+    }
+    if (!configPath) {
+        return {
+            ok: false,
+            detail: `local config.yaml not found (tried: ${candidates.join(", ")}). ` +
+                `Set mcp.enabled: ${enabled} in your component config.yaml manually, then restart.`,
+        };
+    }
+    let raw;
+    try {
+        raw = readFileSync(configPath, "utf-8");
+    }
+    catch (err) {
+        return { ok: false, detail: `cannot read ${configPath}: ${err.message}` };
+    }
+    // Parse the YAML to navigate to the exact key — avoids the ambiguity of
+    // string-matching `enabled:` when the block has multiple enabled keys
+    // (mcp.enabled vs dynamicClientRegistration.enabled).
+    let doc;
+    try {
+        doc = yaml.load(raw);
+    }
+    catch (err) {
+        return { ok: false, detail: `cannot parse ${configPath} as YAML: ${err.message}` };
+    }
+    if (!doc || typeof doc !== "object") {
+        return { ok: false, detail: `${configPath} is empty or not a YAML mapping` };
+    }
+    const oauth = doc["@harperfast/oauth"];
+    if (!oauth || typeof oauth !== "object") {
+        return {
+            ok: false,
+            detail: `@harperfast/oauth block not found in ${configPath}. ` +
+                `Ensure the component block is present with mcp.enabled: ${enabled}.`,
+        };
+    }
+    const mcp = oauth.mcp;
+    if (!mcp || typeof mcp !== "object") {
+        return {
+            ok: false,
+            detail: `mcp key not found under @harperfast/oauth in ${configPath}. ` +
+                `Ensure the mcp block is present with enabled: ${enabled}.`,
+        };
+    }
+    const current = mcp.enabled;
+    if (current === enabled) {
+        return { ok: true, detail: `mcp.enabled already ${enabled} in ${configPath}` };
+    }
+    // Mutate the parsed document and re-emit.
+    mcp.enabled = enabled;
+    const updated = yaml.dump(doc, { lineWidth: -1, noCompatMode: true });
+    try {
+        writeFileSync(configPath, updated, { encoding: "utf-8" });
+    }
+    catch (err) {
+        return { ok: false, detail: `cannot write ${configPath}: ${err.message}` };
+    }
+    return { ok: true, detail: `mcp.enabled set to ${enabled} in ${configPath}` };
+}
 /** The exact callback URL to hand the operator when they create the IdP
  *  OAuth app ("with the exact GitHub callback URL printed"). */
 export function idpCallbackUrl(issuer, idpProvider) {
@@ -553,32 +636,7 @@ export async function provisionIdpIdentityMapping(params, deps = {}) {
     }
     return { principalCreated, credentialId, credentialReused: Boolean(existing) };
 }
-/** `set_configuration` (writes harperdb-config.yaml) then `restart`
- *  (whole-process restart) — the genuine Harper Operations API operations
- *  this module's header documents. Throws on either non-2xx response. */
-export async function applyRemoteConfigAndRestart(params, deps = {}) {
-    const fetchImpl = deps.fetchImpl ?? fetch;
-    const opsUrl = opsBaseUrl(params.opsPortOrUrl);
-    const authHeader = basicAuthHeader(params.adminUser, params.adminPass);
-    const setRes = await fetchImpl(opsUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: authHeader },
-        body: JSON.stringify({ operation: "set_configuration", ...params.configBlock }),
-    });
-    if (!setRes.ok) {
-        const text = await setRes.text().catch(() => "");
-        throw new Error(`set_configuration failed (HTTP ${setRes.status}): ${text}`);
-    }
-    const restartRes = await fetchImpl(opsUrl, {
-        method: "POST",
-        headers: { "Content-Type": "application/json", Authorization: authHeader },
-        body: JSON.stringify({ operation: "restart" }),
-    });
-    if (!restartRes.ok) {
-        const text = await restartRes.text().catch(() => "");
-        throw new Error(`restart failed (HTTP ${restartRes.status}): ${text}`);
-    }
-}
+// ─── Restart only ────────────────────────────────────────────────────────────
 /** `restart` only — used by `disableMcp` (flag off + restart, no config
  *  rewrite: the `@harperfast/oauth` config block is left in place; it is
  *  inert whenever `FLAIR_MCP_OAUTH` is unset, per the byte-identical-boot
@@ -871,11 +929,13 @@ export async function enableMcp(params, deps = {}) {
         currentStep = "signing-key";
         const keyResult = ensureSigningKeyFile(params.signingKeyFilePath, { generate: deps.generateRsaKeyPair });
         push(true, `signing key ${keyResult.reused ? "reused" : "generated"} at ${keyResult.path} (0600)`);
-        // ── @harperfast/oauth config block (CIMD-only; DCR explicitly disabled) ──
+        // ── @harperfast/oauth config (flair#1136: shipped in config.yaml) ──────
+        // The block ships uncommented with mcp.enabled: false (inert default).
+        // set_configuration is removed — the block lives in the component's own
+        // config.yaml, not in harperdb-config.yaml where Fabric would wipe it.
         const cimdAllowedHosts = params.cimdAllowedHosts ?? DEFAULT_CIMD_ALLOWED_HOSTS;
         currentStep = "config-block";
-        const configBlock = buildMcpOAuthConfigBlock({ idpProvider, cimdAllowedHosts });
-        push(true, `built the @harperfast/oauth mcp config block (accessTokenTtl=${REQUIRED_ACCESS_TOKEN_TTL}, ` +
+        push(true, `@harperfast/oauth config ships in config.yaml (mcp.enabled=false, ` +
             `dynamicClientRegistration.enabled=false, clientIdMetadataDocuments.allowedHosts=${JSON.stringify(cimdAllowedHosts)})`);
         // ── IdP OAuth-app credential intake ───────────────────────────────────────
         currentStep = "idp-credentials";
@@ -973,18 +1033,54 @@ export async function enableMcp(params, deps = {}) {
         }
         if (!confirmed) {
             push(false, `not applied: pass --confirm-secrets-applied once the staged secrets are live on ${params.instance}, then re-run \`flair mcp enable\` (earlier steps are idempotent and will reuse what's already provisioned).`);
-            return { ok: false, dryRun, steps, failedStep: "apply-config-and-restart", secretsMechanism: secretsResult.mechanism, secretsPath: secretsResult.path };
+            return { ok: false, dryRun, steps, failedStep: "secrets-provisioning", secretsMechanism: secretsResult.mechanism, secretsPath: secretsResult.path };
         }
-        currentStep = "apply-config-and-restart";
-        // ── Capture boot discriminator BEFORE restart (flair#1120) ─────────────
+        // ── flair#1136: config delivery is now SHIPPED in config.yaml ────────────
+        // The @harperfast/oauth block ships uncommented with mcp.enabled: false
+        // (inert default). set_configuration is REMOVED — Fabric regenerates
+        // harperdb-config.yaml on every container restart, so writing the block
+        // there was always a race against the next deploy. Instead:
+        //
+        //   - Standalone-local: flip mcp.enabled to true in the local config.yaml,
+        //     restart, self-verify.
+        //   - Fabric: the operator must set mcp.enabled: true in their deployed
+        //     component config.yaml. Report the requirement LOUDLY — never report
+        //     success with /mcp still dark.
+        const isFabric = isFabricOrigin(params.instance);
+        if (isFabric) {
+            // ── Fabric: operator-deploy requirement ──────────────────────────────
+            currentStep = "fabric-operator-deploy";
+            const msg = [
+                `Fabric deployment detected (${new URL(params.instance).hostname}).`,
+                `The @harperfast/oauth block ships in config.yaml with mcp.enabled: false.`,
+                `To activate: set mcp.enabled: true (literal boolean) in your deployed component config.yaml,`,
+                `ensure the staged secrets are live in the instance's process environment, and redeploy.`,
+                `Then re-run \`flair mcp enable\` — earlier steps are idempotent and will be reused.`,
+            ].join(" ");
+            push(false, msg);
+            return {
+                ok: false,
+                dryRun,
+                steps,
+                failedStep: "fabric-operator-deploy",
+                issuer,
+                resource: `${issuer}/mcp`,
+                secretsMechanism: secretsResult.mechanism,
+                secretsPath: secretsResult.path,
+                signingKeyFilePath: keyResult.path,
+                callbackUrl,
+            };
+        }
+        // ── Standalone (non-Fabric): update local config + restart ────────────
+        currentStep = "local-config-update";
+        const localConfigResult = updateLocalConfigMcpEnabled(true, params.localConfigPath);
+        push(localConfigResult.ok, localConfigResult.detail);
+        // ── Restart ───────────────────────────────────────────────────────────
+        currentStep = "restart";
         const preDiscriminator = await captureBootDiscriminator(params.instance, params.adminUser, params.adminPass, { fetchImpl: deps.fetchImpl });
-        await applyRemoteConfigAndRestart({ opsPortOrUrl: params.instance, adminUser: params.adminUser, adminPass: params.adminPass, configBlock }, { fetchImpl: deps.fetchImpl });
-        push(true, `set_configuration + restart succeeded against ${params.instance}`);
+        await triggerRemoteRestart(params.instance, params.adminUser, params.adminPass, { fetchImpl: deps.fetchImpl });
+        push(true, `restart triggered against ${params.instance}`);
         // ── Verify the process actually restarted (flair#1120) ──────────────────
-        // Poll the ops API until the PID changes — the old process can briefly
-        // still answer after a real restart, so a single post-capture is unreliable.
-        // waitForOpsApi guarantees PID change (or throws on timeout), so the restart
-        // is confirmed when this call returns.
         currentStep = "verify-restart";
         const postDiscriminator = await waitForOpsApi(resolveOpsUrl(params.instance), basicAuthHeader(params.adminUser, params.adminPass), preDiscriminator.pid, {
             fetchImpl: deps.fetchImpl,
@@ -996,7 +1092,7 @@ export async function enableMcp(params, deps = {}) {
         currentStep = "self-verify";
         const verify = await selfVerifyMcpMetadata(issuer, { fetchImpl: deps.fetchImpl });
         if (!verify.ok) {
-            push(false, `${verify.detail} — re-run \`flair mcp status\` to check current state, or \`flair mcp enable\` to retry the apply-config-and-restart step.`);
+            push(false, `${verify.detail} — re-run \`flair mcp status\` to check current state, or \`flair mcp enable\` to retry.`);
             return {
                 ok: false,
                 dryRun,

package/docs/deploying-on-fabric.md

@@ -129,14 +129,17 @@ where nothing answers:
 # --target https://<fabric-node>:19926/<instance>     → ops derived as :19925 ✓
 ```
 
+**Fabric's ops API runs on the same hostname at port 9925** <!-- docs-freshness-allow: Fabric ops API port, not legacy data port --> (the deploy/upgrade path already targets this port). For a managed `*.harperfabric.com` instance:
+
+```bash
+# Same hostname, port 9925 — not port 442 <!-- docs-freshness-allow: Fabric ops API -->
+flair init --target https://<cluster>.<org>.harperfabric.com \
+    --ops-target https://<cluster>.<org>.harperfabric.com:9925 <!-- docs-freshness-allow: Fabric ops API -->
+```
+
 **Pass `--ops-target <url>` explicitly** (or set `FLAIR_OPS_TARGET`) on any command that
 touches the ops API: `init --target`, `agent add --target`, `federation token --target`.
 
-> **Gap — needs a Fabric account to verify.** This guide does not state the correct
-> ops-API URL for a managed `*.harperfabric.com` instance, or whether the ops API is
-> reachable remotely there at all. The derivation above is certain (read from source);
-> the right value to pass is not.
-
 Precedence: `--target` > `--url` > `FLAIR_TARGET` > `FLAIR_URL` > localhost. For ops:
 `--ops-target` > `FLAIR_OPS_TARGET` > derived > localhost.
 
@@ -250,8 +253,9 @@ and shells out to `lsof`. The command you'd reach for when something breaks is u
 here. Unavailable too: `start`, `stop`, `restart`, `snapshot`, `reembed`, `rem`, `bridge`.
 
 **Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation
-peer table, not Harper's cluster nodes — `cluster_status` is harper-pro-only and absent
-from the OSS `harper` build. **`0 peers known` means "0 on file", never "0 exist."**
+peer table, not Harper's cluster nodes. **`cluster_status` works on Fabric** — Fabric
+always runs harper-pro (not the OSS harper build), so cluster_status is available over
+the ops API. `0 peers known` means "0 on file", never "0 exist."
 
 **There is no disk or quota telemetry.** `flair status` reports usage for two directories:
 no free space, no total, no quota, no warning threshold, walk capped at six levels, no
@@ -263,6 +267,35 @@ with nothing saying so. The one indirect signal is a migration halting for space
 > wouldn't matter: Flair calls it only as a post-failure convergence oracle and discards
 > the `size` field. Component disk usage is invisible structurally.
 
+### The `mcp.enabled` operator step
+
+MCP is **off by default**. The shipped component `config.yaml` contains
+`@harperfast/oauth` → `mcp` → `enabled: false`. Until [flair#1152](https://github.com/tpsdev-ai/flair/issues/1152)
+lands (interpolate from env — *ON HOLD*), you must flip this manually:
+
+1. In your deployed component's `config.yaml`, change:
+    ```yaml
+    '@harperfast/oauth':
+     mcp:
+       enabled: true      # was: false
+    ```
+2. Re-deploy the component so Harper picks up the new value.
+3. **Verify the `/mcp` surface is actually serving** (the flag alone does not
+   guarantee it — a secret that is stored but never decrypted fails at self-verify):
+    ```bash
+    # Check /mcp is reachable and returning MCP protocol (not a loopback proxy or 404)
+    curl -sf https://\<cluster\>.\<org\>.harperfabric.com/mcp
+    # Should return MCP JSON-RPC content; if you get HTML redirect or 404 the flag
+    # is not effective
+    ```
+
+**⚠ SECURITY CAVEAT — the upgrade-reverts trap.** Any package update or fleet component
+update re-ships the literal `enabled: false` and silently darkens a live `/mcp` surface.
+You must **re-flip to `true` after every upgrade** and re-deploy. An updated component
+without this re-flip will appear healthy (`/Health` green) while its MCP tools are
+dark to every connected client. If you rely on MCP, add the re-flip to your upgrade
+runbook.
+
 ### Known hazard: unbounded npm cache
 
 **Open — [flair#886](https://github.com/tpsdev-ai/flair/issues/886).** Every deploy runs a

package/docs/hosted-on-fabric.md

@@ -79,6 +79,35 @@ The staging file is written in every case, so a fallback never strands you mid-r
 
 `--secrets-mechanism <fabric-env-secrets|env-file>` remains an explicit override and skips the probe entirely.
 
+### The `mcp.enabled` operator step (Fabric)
+
+MCP is **off by default**. The shipped component `config.yaml` contains
+`@harperfast/oauth` → `mcp` → `enabled: false`. Until [flair#1152](https://github.com/tpsdev-ai/flair/issues/1152)
+lands (interpolate from env — *ON HOLD*), you must flip this manually:
+
+1. In your deployed component's `config.yaml`, change:
+   ```yaml
+   '@harperfast/oauth':
+     mcp:
+       enabled: true     # was: false
+   ```
+2. Re-deploy the component so Harper picks up the new value.
+3. **Verify the `/mcp` surface is actually serving** (the flag alone does not
+   guarantee it — a secret that is stored but never decrypted fails at self-verify):
+   ```bash
+   # Check /mcp is reachable and returning MCP protocol (not a loopback proxy or 404)
+   curl -sf https://<cluster>.<org>.harperfabric.com/mcp
+   # Should return MCP JSON-RPC content; if you get HTML redirect or 404 the flag
+   # is not effective
+   ```
+
+**⚠ SECURITY CAVEAT — the upgrade-reverts trap.** Any package update or fleet component
+update re-ships the literal `enabled: false` and silently darkens a live `/mcp` surface.
+You must **re-flip to `true` after every upgrade** and re-deploy. An updated component
+without this re-flip will appear healthy (`/Health` green) while its MCP tools are
+dark to every connected client. If you rely on MCP, add the re-flip to your upgrade
+runbook.
+
 ---
 
 ## Agent authentication
@@ -140,7 +169,7 @@ flair fleet verify --target https://<cluster>.<org>.harperfabric.com
 
 **`flair doctor`** takes no `--target` — it hardcodes localhost, reads a local PID file, and shells out to `lsof`. Unavailable too: `start`, `stop`, `restart`, `snapshot`, `reembed`, `rem`, `bridge`.
 
-**Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation peer table, not Harper's cluster nodes. `cluster_status` is harper-pro-only. `0 peers known` means "0 on file", never "0 exist."
+**Fabric's own cluster topology is invisible.** `fleet verify` sweeps *Flair's* federation peer table, not Harper's cluster nodes. **`cluster_status` works on Fabric** — Fabric always runs harper-pro (not the OSS harper build), so cluster_status is available over the ops API. `0 peers known` means "0 on file", never "0 exist."
 
 ---
 

package/docs/mcp-clients.md

@@ -109,7 +109,7 @@ Or wire it by hand — add a `SessionStart` hook to `~/.claude/settings.json`:
         "hooks": [
           {
             "type": "command",
-            "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'"
+            "command": "sh -c 'out=$(FLAIR_AGENT_ID=me npx -y -p @tpsdev-ai/flair-mcp flair-session-start 2>/dev/null) && printf %s \"$out\" || true'"
           }
         ]
       }

package/docs/quickstart.md

@@ -154,6 +154,8 @@ flair search --agent local "native addon loading in sandboxed runtimes"
 
 You searched for a concept, not the keywords. The line under each hit is its creation date, durability tier, and rank score.
 
+> **When stdout is not a terminal** — piped to another command, captured in a script, or run in CI — the same `flair search` command emits a JSON array instead of the formatted prose above. Each hit is an object with `id`, `text`, `createdAt`, `durability`, and `_score` fields. Add `--explain` to include an `_explain` ranking breakdown on each hit. Use `flair search --json` to force JSON output even in a terminal, or `flair memory search` for the raw JSON form in all contexts.
+
 > The percentage is a **rank-fusion score, not a similarity**. It is normalized so the top result is always near 100%. Read it as ordering within these results, never as confidence that the match is good.
 
 Add `--explain` to see the ranking inputs per hit — the raw score, the composite score under `--scoring composite`, and the record's durability, age and usage count. When output is JSON (`--json`, or any time stdout is not a terminal) the same breakdown arrives as an `_explain` object on each hit, so scripts get it too. Use `--limit`, `--tag`, `--since 7d` to narrow the search. `flair memory search` runs the same query but always prints raw JSON — use it when piping to a script.

package/docs/troubleshooting.md

@@ -23,7 +23,8 @@ If it fails to start:
 lsof -i :19926
 
 # Check logs (macOS)
-cat ~/.flair/data/log/hdb.log | tail -50
+cat ~/.flair/data/log/hdb.log | tail -50     # Harper ≤ 5.1 only (see below)
+cat ~/.flair/data/log/system.log | tail -50   # Harper 5.2+ (live log)
 
 # Check logs (Linux)
 journalctl --user -u flair --since "10 minutes ago"
@@ -242,6 +243,14 @@ flair --help          # all commands
 flair <command> -h    # command-specific help
 ```
 
-Logs: `~/.flair/data/log/hdb.log`
+**Log paths depend on Harper version:**
+
+- **Harper ≤ 5.1:** `~/.flair/data/log/hdb.log`
+- **Harper 5.2+:** `~/.flair/data/log/system.log`
+
+> ⚠ **On Harper 5.2+, `hdb.log` freezes at the upgrade boundary.** The live log is
+> `system.log`. The Harper ops `read_log` endpoint keeps serving the frozen `hdb.log`,
+> so remote diagnosis reads days-stale entries that look current. Always check
+> `system.log` after upgrading to 5.2+.
 
 File issues: [github.com/tpsdev-ai/flair/issues](https://github.com/tpsdev-ai/flair/issues)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.41.0",
+  "version": "0.44.0",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",