@tpsdev-ai/flair 0.40.0 → 0.42.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";
@@ -774,6 +774,14 @@ export function buildDirectSpawnEnv(opts) {
         HTTP_PORT: String(opts.httpPort),
         OPERATIONSAPI_NETWORK_PORT: opsNetworkPortValue(opts.opsBindHost, opts.opsPort),
         LOCAL_STUDIO: "false",
+        // flair#905 / lrf5: Harper's forceDowngradePrompt reads CONFIRM_DOWNGRADE
+        // from the environment (via the `prompt` npm package's assignCmdEnvVariables
+        // override). Under launchd/systemd stdin is not a TTY, so the prompt gets
+        // EOF and Harper exits 0 without starting — leaving the instance DOWN with
+        // no error. Setting this to "yes" makes the prompt non-interactive: Harper
+        // proceeds without blocking, which is the correct default for a managed
+        // restart where the operator already chose to proceed.
+        CONFIRM_DOWNGRADE: "yes",
     };
     if (opts.adminPass)
         env.HDB_ADMIN_PASSWORD = opts.adminPass;
@@ -1332,11 +1340,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.
@@ -3348,7 +3354,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 });
                         }
@@ -3356,11 +3368,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,
                             });
                         }
@@ -4803,7 +4819,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.");
@@ -4857,7 +4873,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) {
@@ -9688,6 +9717,50 @@ program
             console.error(`   Recover by hand: npm install -g @tpsdev-ai/flair@${toVersion} && flair start`);
             process.exit(1);
         }
+        // flair#1053: when the engine (Harper) version changed, the pre-upgrade
+        // snapshot is the ONLY way back — the old Harper cannot read data written
+        // by the new one (e.g. 5.2 LZ4-compressed storage is unreadable by 5.1).
+        // Restore it before restarting, or refuse loudly when none exists.
+        if (engineVersionChanging) {
+            if (snapshotPath) {
+                console.log(`\nEngine version changed — restoring pre-upgrade snapshot before rollback...`);
+                console.log(`  snapshot: ${snapshotPath}`);
+                console.log(`  target:   ${upgradeDataDir}`);
+                try {
+                    await validateSnapshotArchive({ file: snapshotPath, targetDir: upgradeDataDir });
+                    rmSync(upgradeDataDir, { recursive: true, force: true });
+                    mkdirSync(upgradeDataDir, { recursive: true, mode: 0o700 });
+                    await extractSnapshotSafely({ file: snapshotPath, targetDir: upgradeDataDir });
+                    console.log(`  ✅ snapshot restored`);
+                }
+                catch (err) {
+                    console.error(`❌ snapshot restore failed: ${err.message}`);
+                    console.error(`   @tpsdev-ai/flair@${toVersion} is installed but the data directory could not be restored.`);
+                    console.error(`   The snapshot itself is intact at ${snapshotPath} — restore it by hand:`);
+                    console.error(`   flair snapshot restore "${snapshotPath}"`);
+                    console.error(`   Then: flair start`);
+                    process.exit(1);
+                }
+            }
+            else {
+                // No snapshot exists — the old Harper WILL NOT BOOT against the new
+                // data. Refuse loudly rather than attempting a guaranteed failure.
+                console.error(`\n❌ Cannot roll back: the Harper engine version changed (${currentEngineVersion ?? "?"} → ${targetEngineVersion ?? "?"}) and no pre-upgrade snapshot exists.`);
+                console.error(`   The old Harper cannot read data written by the new engine — restarting without a snapshot restore would fail.`);
+                console.error(`   @tpsdev-ai/flair@${toVersion} is installed but NOT running.`);
+                if (snapshotDecision === "nudge") {
+                    console.error(`   A snapshot was skipped because --no-engine-snapshot was passed.`);
+                    console.error(`   Recovery options:`);
+                    console.error(`   1. Re-upgrade to the version that wrote this data: npm install -g @tpsdev-ai/flair@${expectedFlairVersion ?? "latest"} && flair start`);
+                    console.error(`   2. Restore from a ` + "`flair backup`" + ` JSON export on a fresh data directory.`);
+                }
+                else {
+                    console.error(`   No snapshot was taken (data directory may not have existed, or the snapshot step was skipped).`);
+                    console.error(`   Recovery: re-upgrade to the version that wrote this data, or restore from a ` + "`flair backup`" + ` JSON export.`);
+                }
+                process.exit(1);
+            }
+        }
         // Same post-swap rule as the upgrade restart above: the rolled-back
         // version's own CLI is the thing that knows how to start it.
         const rolledBackCli = resolveInstalledFlairCli(flairPackageDir(), toVersion);
@@ -9814,6 +9887,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.
@@ -9829,6 +9951,7 @@ program
             else
                 console.log(line);
         }
+        await refreshWiredClients();
         return;
     }
     // flair#741 follow-through: a healthy instance the verifier just couldn't
@@ -9855,6 +9978,7 @@ program
                 console.error(line);
             }
         }
+        await refreshWiredClients();
         return;
     }
     console.error(`❌ post-restart verification failed: ${verdict.reason}`);
@@ -10321,8 +10445,18 @@ async function stopFlairProcess(port, dataDir) {
         }
         catch { }
     }
-    // Wait briefly for shutdown
-    await new Promise((r) => setTimeout(r, 2000));
+    // flair#905 / lrf5: wait for every signalled process to actually exit.
+    // A blind 2-second sleep is not a guarantee — Harper may be flushing
+    // RocksDB WAL/MANIFEST, and the next start will fail with a locked data
+    // directory if the old process hasn't released it yet. The launchd path
+    // above already does this via waitForProcessExit; the port-based path
+    // must match that guarantee.
+    for (const target of targets) {
+        try {
+            await waitForProcessExit(target, STARTUP_TIMEOUT_MS);
+        }
+        catch { /* best-effort — the next start will surface the real problem */ }
+    }
 }
 /**
  * Start the local Flair (Harper) process — launchd `start` on darwin when a
@@ -15446,8 +15580,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);

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
@@ -303,6 +304,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 +315,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 +333,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) {
@@ -871,11 +952,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 +1056,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 };
+        }
+        // ── 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,
+            };
         }
-        currentStep = "apply-config-and-restart";
-        // ── Capture boot discriminator BEFORE restart (flair#1120) ─────────────
+        // ── 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 +1115,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/upgrade.md

@@ -357,7 +357,7 @@ if you want to see it scripted end-to-end.
   upgraded via `flair upgrade`. Real snapshots for production datasets run hundreds of
   megabytes — plan disk capacity accordingly. Cleanup of old engine snapshots is manual;
   `flair snapshot list` shows available snapshots, and you can delete entries you no longer
-  need.
+  need (e.g. `rm ~/.flair/upgrade-snapshots/flair-data-<old>.tar.gz`).
 
 ## Rollback
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.40.0",
+  "version": "0.42.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",
@@ -64,7 +64,7 @@
     "@harperfast/oauth": "2.4.0",
     "@types/js-yaml": "4.0.9",
     "commander": "14.0.3",
-    "harper": "5.1.22",
+    "harper": "5.2.0",
     "harper-fabric-embeddings": "^0.5.0",
     "jose": "6.2.2",
     "js-yaml": "^4.3.1",