@tpsdev-ai/flair 0.36.0 → 0.38.0

package/dist/cli.js

@@ -13,7 +13,7 @@ import { keystore } from "./keystore.js";
 import { deploy as deployToFabric, validateOptions as validateDeployOptions, buildTargetUrl as buildDeployUrl, resolveDeployPublicUrl } from "./deploy.js";
 import { COMPONENT_ENV_FILENAME, PUBLIC_URL_KEY, assertNoSecretKeysAdded, describePublicUrlFinding, planComponentEnv, readEnvValue, } from "./component-env.js";
 import { fabricUpgrade } from "./fabric-upgrade.js";
-import { checkVersion, formatVersionNudge, primeVersionCheckCache, FLAIR_PKG_NAME } from "./version-check.js";
+import { checkVersion, formatVersionNudge, primeVersionCheckCache, probeInstanceVersion, FLAIR_PKG_NAME } from "./version-check.js";
 import { readInstalledHarperVersion, fetchDeclaredHarperVersion, writeEngineVersionStamp, checkEngineVersionBackwards, UPGRADE_SNAPSHOT_ROOT, } from "./engine-version.js";
 import { checkServerHandshake, formatHandshakeNudge, invalidateHandshakeCache } from "./version-handshake.js";
 import { probeInstance } from "./probe.js";
@@ -4777,7 +4777,7 @@ mcp
     .option("--secrets-path <path>", "Override the secrets staging file path")
     .option("--cimd-allowed-hosts <hosts>", "Comma-separated clientIdMetadataDocuments.allowedHosts override (else claude.ai,claude.com)")
     .option("--signing-key-file <path>", "RS256 signing key PEM file (else ~/.flair/mcp-signing-key.pem)")
-    .option("--admin-pass <pass>", "Admin password for the target instance (or FLAIR_ADMIN_PASS)")
+    .option("--admin-pass <pass>", "Admin password for the TARGET instance. Required explicitly for a remote target — FLAIR_ADMIN_PASS and ~/.flair/admin-pass are this machine's local credentials and are never sent to a remote instance")
     .option("--confirm-secrets-applied", "Confirm the staged secrets are already live on the target instance's environment (skips the interactive confirm)")
     .option("--dry-run", "Generate keys/tokens/config and validate inputs; skip every remote call")
     .option("--json", "Print machine-readable JSON instead of a human summary")
@@ -4802,8 +4802,11 @@ mcp
     // against someone else's instance (see resolveLocalAdminPass's doc comment).
     const adminPass = dryRun ? (opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "") : resolveLocalAdminPass(opts.adminPass, /* isRemoteTarget */ true);
     if (!dryRun && !adminPass) {
-        console.error("Error: --admin-pass or FLAIR_ADMIN_PASS required (the operations API on the target instance needs it " +
-            "for identity mapping + set_configuration + restart).");
+        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" +
+            "  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.");
         process.exit(1);
     }
     let idpClientId = opts.idpClientId;
@@ -9954,14 +9957,17 @@ program
         process.exit(1);
     }
     // flair#1047: refuse to boot if the store was written by a newer engine.
-    const runningHarperVersion = readInstalledHarperVersion(flairPackageDir());
-    if (runningHarperVersion) {
-        const backwardsError = checkEngineVersionBackwards(dataDir, runningHarperVersion);
-        if (backwardsError) {
-            console.error(`❌ Cannot start Flair — the data directory was written by a newer Harper engine.\n`);
-            console.error(backwardsError);
-            process.exit(1);
-        }
+    // Same guard startFlairProcess runs, so restart/upgrade/snapshot cannot
+    // reach a boot this command would refuse (flair#1093).
+    try {
+        guardEngineNotBackwards(dataDir);
+    }
+    catch (err) {
+        if (!err?.engineBackwards)
+            throw err;
+        console.error(`❌ Cannot start Flair — the data directory was written by a newer Harper engine.\n`);
+        console.error(err.message);
+        process.exit(1);
     }
     const platform = process.platform;
     if (platform === "darwin") {
@@ -10329,7 +10335,45 @@ async function stopFlairProcess(port, dataDir) {
  * snapshot commands' restart leg brought the DEFAULT instance back up after
  * operating on a `--data-dir` elsewhere.
  */
+/**
+ * flair#1047's refusal, at the point every boot passes through (flair#1093).
+ *
+ * It used to live inline in the `start` command's action and nowhere else, so
+ * `flair restart`, `flair upgrade` (which restarts by spawning the new CLI with
+ * `restart`) and the snapshot paths all booted Harper without it. The guard
+ * covered one of the doors, and not the one an ENGINE SWAP comes through — so
+ * an upgrade across a storage-format boundary came back as a dead port and a
+ * bare exit 1 instead of a refusal naming actor, state and remedy.
+ *
+ * These same two functions had already drifted once, on the spawn environment:
+ * see the note above buildDirectSpawnEnv about `start` setting a host-qualified
+ * OPERATIONSAPI_NETWORK_PORT while startFlairProcess set none, silently
+ * re-widening the ops API on every restart. Same pair, same shape. This is why
+ * the check is a single function called from both rather than a second copy.
+ *
+ * Throws rather than exiting: `start` wants its own framing and an exit code,
+ * while restart/upgrade need the message to travel up as an error. Nothing here
+ * decides how it is presented.
+ */
+function guardEngineNotBackwards(dataDir) {
+    const runningHarperVersion = readInstalledHarperVersion(flairPackageDir());
+    // No readable engine version means nothing to compare — the pre-stamp case
+    // checkEngineVersionBackwards already treats as "not backwards". Refusing here
+    // would brick every install written before the stamp existed.
+    if (!runningHarperVersion)
+        return;
+    const backwardsError = checkEngineVersionBackwards(dataDir, runningHarperVersion);
+    if (!backwardsError)
+        return;
+    const err = new Error(backwardsError);
+    err.engineBackwards = true;
+    throw err;
+}
 async function startFlairProcess(port, dataDir) {
+    // Before anything is spawned or launchd is touched: an older engine opening a
+    // newer store fails at the storage layer with an error about compression
+    // internals, minutes later and nowhere near the cause.
+    guardEngineNotBackwards(dataDir);
     if (process.platform === "darwin") {
         // resolveLaunchdLabel (flair#693) finds whichever label this data dir
         // is currently registered under before we attempt anything.
@@ -11310,17 +11354,46 @@ program
     // since we don't have advisory data, only the version gap. A red gap
     // counts as an issue (exit 1); a quieter yellow gap (one minor, or
     // patch-only) is printed but doesn't fail doctor.
-    const versionCheckResult = await checkVersion(__pkgVersion);
-    const versionNudge = formatVersionNudge(versionCheckResult);
-    if (versionNudge) {
-        const color = versionNudge.severity === "red" ? render.c.red : render.c.yellow;
-        const icon = versionNudge.severity === "red" ? render.wrap(render.c.red, "✗") : render.icons.warn;
-        console.log(`  ${icon} ${render.wrap(color, versionNudge.message)}`);
-        if (versionNudge.severity === "red")
-            issues++;
+    // ── flair#1072: the currency claim must be about the INSTANCE ─────────────
+    //
+    // This check used to run `checkVersion(__pkgVersion)` — the version of the
+    // CLI you happen to have installed — and print "flair <x> is current". When
+    // FLAIR_URL or --url points at a deployed instance, every other line doctor
+    // prints is genuinely remote, so that sentence reads as a statement about
+    // the thing you are talking to. It was a statement about your laptop.
+    //
+    // Reported against an instance five minors behind, where doctor said
+    // "current". Telling you that is doctor's entire job.
+    //
+    // UNKNOWN MUST NOT FALL BACK TO THE LOCAL NUMBER. An older instance may not
+    // expose its version at all, and the tempting fix is to use the one already
+    // in hand — which is precisely how this bug reads today. If the instance
+    // version cannot be determined, say so and count it as an issue rather than
+    // answering from the wrong machine.
+    const instanceVersion = await probeInstanceVersion(baseUrl);
+    const versionSubject = instanceVersion ?? null;
+    if (versionSubject === null) {
+        console.log(`  ${render.icons.warn} ${render.wrap(render.c.yellow, `could not determine the version running at ${baseUrl} — not reporting currency. ` +
+            `(The local CLI is ${__pkgVersion}; that is NOT the instance.)`)}`);
+        issues++;
     }
-    else if (versionCheckResult.latest) {
-        console.log(`  ${render.icons.ok} flair ${__pkgVersion} is current`);
+    else {
+        const versionCheckResult = await checkVersion(versionSubject);
+        const versionNudge = formatVersionNudge(versionCheckResult);
+        if (versionNudge) {
+            const color = versionNudge.severity === "red" ? render.c.red : render.c.yellow;
+            const icon = versionNudge.severity === "red" ? render.wrap(render.c.red, "✗") : render.icons.warn;
+            console.log(`  ${icon} ${render.wrap(color, versionNudge.message)}`);
+            if (versionNudge.severity === "red")
+                issues++;
+        }
+        else if (versionCheckResult.latest) {
+            console.log(`  ${render.icons.ok} instance at ${baseUrl} runs flair ${versionSubject} — current`);
+        }
+        if (versionSubject !== __pkgVersion) {
+            console.log(`  ${render.icons.warn} ${render.wrap(render.c.yellow, `local CLI is ${__pkgVersion}, instance is ${versionSubject} — they differ. ` +
+                `Commands run through the CLI; the instance serves the data.`)}`);
+        }
     }
     // Helper: try to reach Harper on a given port.
     // Must return true ONLY when Harper's /Health endpoint returns 200 OK.

package/dist/deploy.js

@@ -6,8 +6,19 @@ import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { COMPONENT_ENV_FILENAME, PUBLIC_URL_KEY, isLoopbackUrl, planComponentEnv, publicUrlRemedy, } from "./component-env.js";
 import { awaitOriginQuiescent, awaitReplicationConvergence, defaultConvergenceDeps, parseReplicationFailure, } from "./replication-convergence.js";
-// Files that must be present in a Flair package for deployment.
-// Mirrors the `files` array in package.json — keep in sync.
+// Files that must be PRESENT for a deploy root to be usable at all — a
+// preflight sanity check, not the payload definition.
+//
+// This used to say "Mirrors the `files` array in package.json — keep in sync."
+// It did not, and nothing compared them. The payload was whatever sat in the
+// deploy root, which for a git checkout meant .git, models/, test/, packages/
+// and any stray file: 96 MB against a 1.3 MB published tarball, verified on a
+// production Fabric component. A rule asserted in a comment with no mechanism
+// behind it will drift, and this one drifted invisibly for as long as it existed.
+//
+// The payload is now derived from `files` directly, at pack time, by
+// publishedEntryNames() — so there is one source of truth and nothing left to
+// keep in sync by hand.
 export const REQUIRED_PACKAGE_FILES = [
     "dist",
     "schemas",
@@ -592,6 +603,73 @@ function isNodeModulesPath(root, path) {
     const rel = relative(root, path);
     return rel !== "" && rel.split(sep).includes("node_modules");
 }
+/**
+ * The top-level entries the payload may contain: whatever `files` declares, plus
+ * the three npm always-includes. Read from the deploy root's own package.json so
+ * there is ONE source of truth — a hardcoded copy here is how `files` and the
+ * payload drifted apart in the first place.
+ */
+export function publishedEntryNames(packageRoot) {
+    // `.env` is not in `files` and never ships to npm, but it MUST reach the
+    // component: config.yaml's `loadEnv` reads it, and shipping it is the whole
+    // point of flair#1005 and of stageDeployRoot itself. Filtering it out breaks
+    // FLAIR_PUBLIC_URL on every deploy — caught by the operator-value test rather
+    // than in production, which is the only reason this comment exists.
+    //
+    // What goes INSIDE that file is a separate concern with its own issue
+    // (flair#1011, HDB_ADMIN_PASSWORD must not be written into a deployed .env).
+    // This function decides what may ship, not what the file may contain.
+    const always = ["package.json", "README.md", "LICENSE", "LICENCE", COMPONENT_ENV_FILENAME];
+    let declared = [];
+    try {
+        const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        if (Array.isArray(pkg.files))
+            declared = pkg.files;
+    }
+    catch {
+        /* handled by the caller's emptiness check below */
+    }
+    // `files` entries are npm patterns; the ones flair uses are plain top-level
+    // names, optionally trailing-slashed ("dist/"). Normalise to the entry name.
+    const names = declared
+        .map((f) => String(f).replace(/^\.\//, "").replace(/\/+$/, ""))
+        .filter((f) => f !== "" && !f.includes("*") && !f.startsWith("!"));
+    return new Set([...names, ...always]);
+}
+/**
+ * Whether `packageRoot` declares a usable `files` array.
+ *
+ * Separate from `publishedEntryNames` deliberately. The refusal below used to
+ * ask whether the resulting set was larger than the always-includes, i.e. it
+ * compared against a hardcoded count — so adding one always-include silently
+ * stopped it firing. A check keyed to the length of a list that grows is a check
+ * that disables itself the next time someone edits that list.
+ */
+export function hasDeclaredFiles(packageRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf8"));
+        return Array.isArray(pkg.files) && pkg.files.length > 0;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * True when `src` is a top-level entry the published package would not contain.
+ *
+ * Only TOP-LEVEL entries are filtered. Once a directory is admitted its whole
+ * subtree ships, which is what npm does and what makes the staged copy equal the
+ * published tarball rather than merely similar.
+ */
+function isUnpublishedEntry(root, src, allowed) {
+    const rel = relative(root, src);
+    if (rel === "")
+        return false;
+    const parts = rel.split(sep);
+    if (parts.length > 1)
+        return false;
+    return !allowed.has(parts[0]);
+}
 /**
  * Resolve the value `FLAIR_PUBLIC_URL` should carry for this deploy, or null.
  *
@@ -629,8 +707,40 @@ export function stageDeployRoot(packageRoot, publicUrl) {
     const envPath = join(packageRoot, COMPONENT_ENV_FILENAME);
     const existing = existsSync(envPath) ? readFileSync(envPath, "utf8") : null;
     const plan = planComponentEnv(existing, publicUrl);
-    if (plan.text === null) {
-        return { dir: packageRoot, plan, cleanup: () => { } };
+    // ── Why this ALWAYS stages now ─────────────────────────────────────────────
+    //
+    // harper packs its CWD wholesale, so the payload is whatever sits in the
+    // deploy root. The comment above assumes that root is an npm-installed
+    // package, where the tree already IS the published file set. That assumption
+    // is true for the intended path and silently false for the one our own
+    // deploy procedure prescribes: a git checkout.
+    //
+    // Measured on the production Fabric origin 2026-08-03, deploying from a
+    // checkout at v0.36.0: the deployed component held 36 top-level entries —
+    // `.git`, `.env`, `models/`, `test/`, `packages/`, `src/`, and a scratch
+    // `pr-body.md` left in the clone that afternoon. Payload 96 MB against the
+    // published tarball's 1.3 MB, a factor of 74. `models/` alone was 80 MB.
+    //
+    // Two consequences, both bad. An operator deploying from a checkout ships
+    // `.git` (every secret ever committed and later removed) and any `.env`
+    // sitting in the tree, into a component that is then PERSISTED and REPLICATED
+    // across the cluster. And a 96 MB payload is what puts the deploy inside
+    // HarperFast/harper#2062's aborted-transaction window, where the pre-saved
+    // blob is destroyed at the source.
+    //
+    // So the filter is not an optimisation. Staging unconditionally, restricted to
+    // the entries `files` declares, makes the payload equal the published package
+    // BY CONSTRUCTION rather than by an operator happening to run from the right
+    // directory. For an npm-installed root the result is byte-identical to before,
+    // because such a tree contains nothing else.
+    const allowed = publishedEntryNames(packageRoot);
+    // An empty/unreadable `files` would filter the payload down to the
+    // always-includes and deploy a component with no dist/. Refuse instead: a
+    // deploy that silently ships almost nothing is worse than one that does not run.
+    if (!hasDeclaredFiles(packageRoot)) {
+        throw new Error(`Cannot determine the published file set for ${packageRoot}: package.json has no usable "files" array. ` +
+            `Refusing to deploy rather than shipping an unfiltered payload (which would include .git and any .env) ` +
+            `or an empty one. Deploy from an npm-installed @tpsdev-ai/flair, or pass --package-root at one.`);
     }
     const dir = mkdtempSync(join(tmpdir(), STAGING_PREFIX));
     try {
@@ -638,12 +748,19 @@ export function stageDeployRoot(packageRoot, publicUrl) {
             recursive: true,
             dereference: false,
             verbatimSymlinks: true,
-            filter: (src) => !isNodeModulesPath(packageRoot, src),
+            filter: (src) => !isNodeModulesPath(packageRoot, src) && !isUnpublishedEntry(packageRoot, src, allowed),
         });
         // 0600 even though the generated content is a public URL: an operator's own
         // keys may have been merged through, and the file's permissions should not
         // depend on what happens to be in it.
-        writeFileSync(join(dir, COMPONENT_ENV_FILENAME), plan.text, { mode: 0o600 });
+        //
+        // `plan.text === null` means there is nothing to add — a loopback target, or
+        // an operator who already set the key. Staging still happened (the filter is
+        // the point now, not the `.env`), so any `.env` the root carried has been
+        // copied through unchanged and must be left alone.
+        if (plan.text !== null) {
+            writeFileSync(join(dir, COMPONENT_ENV_FILENAME), plan.text, { mode: 0o600 });
+        }
     }
     catch (err) {
         rmSync(dir, { recursive: true, force: true });

package/dist/lib/auth-resolve.js

@@ -140,6 +140,25 @@ export function defaultKeysDir() {
  * local admin secret against someone else's Harper instance. Remote callers
  * keep requiring an explicit `--admin-pass`.
  *
+ * ── Both legs, not just the file (flair#1085) ────────────────────────────────
+ * An operator reported this as a bug: `--help` and the error both promised
+ * `FLAIR_ADMIN_PASS` would work, and for a remote target it silently did not.
+ * The promise was wrong, not the guard — but the codebase disagreed with itself,
+ * which is why it read as a defect. One call site's comment described the goal as
+ * blocking only the *file* fallback, this doc described blocking both, and the
+ * user-facing strings described neither.
+ *
+ * The env leg is skipped **deliberately**, and the reasoning is worth keeping:
+ * an exported `FLAIR_ADMIN_PASS` is not evidence of intent toward THIS target. It
+ * persists across a shell session, so an operator who set it for their local
+ * instance and later types `--instance https://someone-elses-host` would send a
+ * local admin credential to a third party — silently, and with no way to notice.
+ * "The operator exported it" and "the operator meant it for this host" are
+ * different claims, and only the explicit flag asserts the second.
+ *
+ * If that trade is ever revisited, revisit it here rather than at a call site:
+ * the guard is one line and the reasoning is not obvious from it.
+ *
  * Throws (via readAdminPassFileSecure) if the file exists but has unsafe
  * permissions, so a misconfigured file surfaces as an actionable chmod error
  * instead of a generic "admin pass required" message.

package/dist/lib/mcp-enable.js

@@ -101,10 +101,14 @@
  *     `dist/lib/mcp/wellKnown.js`'s `buildAuthorizationServerMetadata`
  *     (lines 129-166), which advertises `registration_endpoint`/
  *     `token_endpoint` unconditionally (NOTE: `registration_endpoint` is
- *     advertised even though DCR is disabled — the plugin doesn't condition
- *     that field on `dynamicClientRegistration.enabled`; a POST there still
- *     404s per dcr.js:165-167, this is just a metadata-completeness quirk of
- *     the installed package, not a gap in our config) and
+ *     advertised even though DCR is disabled — CORRECTED 2026-08-05: that was
+ *     true of the version this was written against and is FALSE of the
+ *     installed one. wellKnown.js:142 now reads
+ *     `...(dcrEnabled(mcpConfig) ? { registration_endpoint: … } : {})`, so the
+ *     field is OMITTED whenever DCR is off — which is every instance `enable`
+ *     configures. selfVerifyMcpMetadata required it and therefore failed on a
+ *     correctly enabled surface; see the note at that check. A verified fact
+ *     carries the date it was verified, and this one expired.) and
  *     `client_id_metadata_document_supported: true` whenever
  *     `clientIdMetadataDocuments.enabled !== false` (wellKnown.js:164 — true
  *     by default, which is what our config relies on), and
@@ -135,6 +139,7 @@
  *     in `cimd.js`, so listing an extra host is not a meaningful risk
  *     expansion.
  */
+import { probeSecretsCapability, pushSecrets, PROCESS_ENV_TIER } from "./secrets-push.js";
 import { existsSync, mkdirSync, writeFileSync, chmodSync, readFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, dirname } from "node:path";
@@ -216,6 +221,30 @@ export function isFabricOrigin(url) {
  * installed 5.1.17 SDK). Anything else defaults to `env-file` — the
  * documented, universally-supported fallback. Always overridable.
  */
+/**
+ * ── The hostname no longer selects the mechanism (flair#1094) ───────────────
+ *
+ * This used to be `isFabricOrigin(url) ? "fabric-env-secrets" : "env-file"`, and
+ * that was wrong in BOTH directions on the day it was replaced:
+ *
+ *   - `tps.dtrt.harperfabric.com` runs Harper 5.1.26 and has no secrets
+ *     operations at all — measured; `set_secret` answers "Operation 'set_secret'
+ *     not found", identical to an invented operation — and was selected for the
+ *     automated mechanism purely because of its name.
+ *   - a self-hosted Harper 5.2 with the Pro env-secrets component is fully
+ *     capable and was sent down the manual Studio path for not matching.
+ *
+ * A hostname is not a capability, and neither is a version — the write
+ * operations and the Pro decryptor that makes a `processEnv` secret reach the
+ * process ship separately. `probeSecretsCapability` asks the target instead, and
+ * the answer decides at provisioning time.
+ *
+ * What remains here is the STAGING FILE's flavour of instructions, which is
+ * genuinely about where the operator will paste if we end up falling back.
+ * Fabric operators paste into Studio; everyone else edits a unit file. That is a
+ * UI fact about a human, not a claim about the server, so a hostname is a
+ * reasonable signal for it and a wrong guess costs only slightly-off prose.
+ */
 export function selectSecretsMechanism(instanceUrl, override) {
     if (override)
         return override;
@@ -355,8 +384,50 @@ export function provisionSecrets(instanceUrl, bundle, opts = {}) {
     return { mechanism, path, varNames, instructions };
 }
 // ─── Identity mapping (Credential kind:idp) ─────────────────────────────────
+/**
+ * The ops API is NOT the served origin, and its port is NOT derivable.
+ *
+ * flair#1072-adjacent, found while enabling MCP against a hosted instance: this
+ * function used a string target verbatim, so `flair mcp enable --instance
+ * https://flair.example.harperfabric.com` posted its ops calls to **port 443**,
+ * where the flair REST component owns `/` and answers `404 Not found`. Measured
+ * against a live Fabric instance, same request both ways:
+ *
+ *     POST https://<host>/          -> HTTP 404  "Not found"
+ *     POST https://<host>:9925/     -> HTTP 200  []
+ *
+ * The codebase elsewhere documents "ops port = HTTP port - 1", which derives 442
+ * for a 443-served instance. Also measured: 442 and 19925 are both dead on
+ * Fabric. **That convention does not hold, and no arithmetic on the served port
+ * can be trusted — an operator can put the ops API anywhere.**
+ *
+ * So: never derive silently. An explicit target wins; otherwise the conventional
+ * hosted ops port is *tried*, and a caller that cannot reach it is told to pass
+ * one rather than being handed a 404 about something else.
+ */
+export const HOSTED_OPS_PORT = 9925;
+export function resolveOpsUrl(target, explicitOpsUrl) {
+    if (explicitOpsUrl)
+        return `${explicitOpsUrl.replace(/\/+$/, "")}/`;
+    if (typeof target === "number")
+        return `http://127.0.0.1:${target}/`;
+    // A string target is the SERVED origin. Its own port serves the REST surface,
+    // not the ops API, so reuse the host and apply the hosted ops port.
+    try {
+        const u = new URL(target.includes("://") ? target : `https://${target}`);
+        u.port = String(HOSTED_OPS_PORT);
+        u.pathname = "/";
+        u.search = "";
+        return u.toString();
+    }
+    catch {
+        // Unparseable — preserve the old behaviour rather than inventing a URL, and
+        // let the caller's error path name the remedy.
+        return `${target.replace(/\/+$/, "")}/`;
+    }
+}
 function opsBaseUrl(opsPortOrUrl) {
-    return typeof opsPortOrUrl === "number" ? `http://127.0.0.1:${opsPortOrUrl}/` : `${opsPortOrUrl.replace(/\/$/, "")}/`;
+    return resolveOpsUrl(opsPortOrUrl);
 }
 function basicAuthHeader(adminUser, adminPass) {
     return `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
@@ -388,7 +459,19 @@ export async function provisionIdpIdentityMapping(params, deps = {}) {
     });
     if (!findRes.ok) {
         const text = await findRes.text().catch(() => "");
-        throw new Error(`Identity mapping: failed to look up principal '${params.principal}' (HTTP ${findRes.status}): ${text}`);
+        // A MISSING principal is not this branch. The ops API answers an empty
+        // search with 200 and [], and the code below creates the principal when the
+        // list is empty. Reaching here means the ops CALL failed, not that the
+        // identity is absent — and saying "failed to look up principal 'x'" sends
+        // the reader to look at principals, which is where an evening goes.
+        //
+        // 404 in particular almost always means the request reached the SERVED
+        // origin instead of the ops API: the flair REST component owns `/` there and
+        // answers 404. Say that, and name the flag that fixes it.
+        const hint = findRes.status === 404
+            ? ` — a 404 here usually means ${opsUrl} is the served origin rather than the ops API (the REST component owns "/" and answers 404). The ops API is a DIFFERENT port (conventionally ${HOSTED_OPS_PORT} on hosted instances) and is not derivable from the served port. Pass --ops-url <url> to point at it explicitly.`
+            : "";
+        throw new Error(`Identity mapping: the ops API call to ${opsUrl} failed (HTTP ${findRes.status})${hint}${text ? `: ${text}` : ""}`);
     }
     const foundAgents = await findRes.json().catch(() => []);
     let principalCreated = false;
@@ -551,12 +634,61 @@ export async function selfVerifyMcpMetadata(issuer, deps = {}) {
     catch {
         return { ok: false, detail: `${url} did not return JSON` };
     }
+    // ── The flair's-own-server check runs BEFORE the shape check (flair#1094) ──
+    //
+    // It used to run after, and that made the DEFAULT flag-off case misreport.
+    // flair's own document omits `registration_endpoint` unless DCR is enabled,
+    // which it is not by default — so the shape check fired first and returned
+    // "the metadata shape is unexpected", which is true, useless, and points at
+    // shapes when the cause is an unset environment variable.
+    //
+    // `token_endpoint` is present in that document either way, so testing the
+    // discriminator first names the real cause in EVERY flag-off case rather than
+    // only when DCR happens to be on. Found by writing the test that pins this
+    // relationship, not by reading the code.
+    if (typeof body?.token_endpoint === "string" && body.token_endpoint === `${normalizedIssuer}/OAuthToken`) {
+        return {
+            ok: false,
+            issuer: body?.issuer,
+            registrationEndpoint: body?.registration_endpoint,
+            tokenEndpoint: body.token_endpoint,
+            detail: `${url} answered with flair's OWN OAuth 2.1 authorization server, not the MCP one ` +
+                `(token_endpoint=${body.token_endpoint}) — the /mcp surface is NOT enabled on that instance. ` +
+                `Is FLAIR_MCP_OAUTH actually set on the restarted instance, and is the '@harperfast/oauth' ` +
+                `component declared in its config.yaml?`,
+        };
+    }
+    // ── registration_endpoint is OPTIONAL and must not be required (Kern, #1101) ─
+    //
+    // Requiring it made self-verify fail on a CORRECTLY enabled instance — the
+    // exact configuration `enable` itself creates.
+    //
+    // RFC 8414 marks the field optional, and BOTH authorization servers in this
+    // system omit it when DCR is off:
+    //   - flair's own AS: resources/oauth-discovery.ts, conditional spread on
+    //     dcrEnabled(), default off.
+    //   - the MCP plugin: @harperfast/oauth/dist/lib/mcp/wellKnown.js:142,
+    //     `...(dcrEnabled(mcpConfig) ? { registration_endpoint: … } : {})`.
+    //
+    // And `enable` writes `dynamicClientRegistration: { enabled: false }` by
+    // design — DCR is unsupported on this surface (#756). So the plugin omits the
+    // field on every instance this command configures, and self-verify then
+    // reported "the metadata shape is unexpected" on a working MCP surface,
+    // sending the operator to debug metadata fields instead.
+    //
+    // The module header above still claims the plugin advertises it
+    // "unconditionally". That was true of the version it was written against and
+    // is false of the installed one — corrected there too. A verified fact carries
+    // the date it was verified, and this one expired.
+    //
+    // Required: issuer and token_endpoint, both always present in both servers.
+    // registration_endpoint is validated only when it appears.
     if (body?.issuer !== normalizedIssuer ||
-        typeof body?.registration_endpoint !== "string" ||
-        typeof body?.token_endpoint !== "string") {
+        typeof body?.token_endpoint !== "string" ||
+        (body?.registration_endpoint !== undefined && typeof body.registration_endpoint !== "string")) {
         return {
             ok: false,
-            detail: `${url} responded but the metadata shape is unexpected (issuer/registration_endpoint/token_endpoint) — got issuer=${JSON.stringify(body?.issuer)}`,
+            detail: `${url} responded but the metadata shape is unexpected (issuer/token_endpoint) — got issuer=${JSON.stringify(body?.issuer)}`,
         };
     }
     // flair#1000: this path is now served by flair ITSELF when FLAIR_MCP_OAUTH is
@@ -630,29 +762,46 @@ export function buildClaudePasteBlock(resource) {
  */
 export async function enableMcp(params, deps = {}) {
     const steps = [];
+    // The step currently executing, so a throw is attributed to IT rather than to
+    // the last step that succeeded (flair#1087).
+    //
+    // `push` deliberately takes NO step name: it reads this variable. A name passed
+    // per-call would be the same string typed twice (once here, once at the push),
+    // and the two drifting apart is precisely the misattribution #1087 is about —
+    // a rule that only a comment or a source scan could enforce. Deriving it makes
+    // a wrong name unrepresentable instead of merely discouraged, so there is
+    // nothing left for a reviewer to check.
+    //
+    // Initialised to the first step rather than left undefined so a throw before
+    // any assignment cannot be attributed to an arbitrary fallback name.
+    let currentStep = "local-origin-check";
     const dryRun = Boolean(params.dryRun);
-    const push = (step, ok, detail) => steps.push({ step, ok, detail });
+    const push = (ok, detail) => steps.push({ step: currentStep, ok, detail });
     // ── Local-origin refusal (scenario addendum, binding) ─────────────────────
+    currentStep = "local-origin-check";
     const localCheck = checkLocalOriginRefusal(params.instance);
     if (localCheck.refused) {
-        push("local-origin-check", false, localCheck.message);
+        push(false, localCheck.message);
         return { ok: false, dryRun, refused: { message: localCheck.message }, steps, failedStep: "local-origin-check" };
     }
-    push("local-origin-check", true, `${params.instance} is a public-shaped origin`);
+    push(true, `${params.instance} is a public-shaped origin`);
     const issuer = (params.issuer ?? params.instance).replace(/\/+$/, "");
     const idpProvider = params.idpProvider ?? "github";
     const principal = params.principal ?? "self";
     const principalKind = params.principalKind ?? "human";
     try {
         // ── RS256 signing keypair ─────────────────────────────────────────────────
+        currentStep = "signing-key";
         const keyResult = ensureSigningKeyFile(params.signingKeyFilePath, { generate: deps.generateRsaKeyPair });
-        push("signing-key", true, `signing key ${keyResult.reused ? "reused" : "generated"} at ${keyResult.path} (0600)`);
+        push(true, `signing key ${keyResult.reused ? "reused" : "generated"} at ${keyResult.path} (0600)`);
         // ── @harperfast/oauth config block (CIMD-only; DCR explicitly disabled) ──
         const cimdAllowedHosts = params.cimdAllowedHosts ?? DEFAULT_CIMD_ALLOWED_HOSTS;
+        currentStep = "config-block";
         const configBlock = buildMcpOAuthConfigBlock({ idpProvider, cimdAllowedHosts });
-        push("config-block", true, `built the @harperfast/oauth mcp config block (accessTokenTtl=${REQUIRED_ACCESS_TOKEN_TTL}, ` +
+        push(true, `built the @harperfast/oauth mcp config block (accessTokenTtl=${REQUIRED_ACCESS_TOKEN_TTL}, ` +
             `dynamicClientRegistration.enabled=false, clientIdMetadataDocuments.allowedHosts=${JSON.stringify(cimdAllowedHosts)})`);
         // ── IdP OAuth-app credential intake ───────────────────────────────────────
+        currentStep = "idp-credentials";
         const callbackUrl = idpCallbackUrl(issuer, idpProvider);
         if (!params.idpClientId || !params.idpClientSecret || !params.idpSubject) {
             const missing = [
@@ -660,10 +809,10 @@ export async function enableMcp(params, deps = {}) {
                 !params.idpClientSecret && "--idp-client-secret",
                 !params.idpSubject && "--idp-subject",
             ].filter(Boolean).join(", ");
-            push("idp-credentials", false, `missing ${missing}. Create a ${idpProvider} OAuth app with callback URL ${callbackUrl}, then re-run with the credentials.`);
+            push(false, `missing ${missing}. Create a ${idpProvider} OAuth app with callback URL ${callbackUrl}, then re-run with the credentials.`);
             return { ok: false, dryRun, steps, failedStep: "idp-credentials", callbackUrl };
         }
-        push("idp-credentials", true, `${idpProvider} OAuth app credentials present; callback URL: ${callbackUrl}`);
+        push(true, `${idpProvider} OAuth app credentials present; callback URL: ${callbackUrl}`);
         if (dryRun) {
             // Dry-run stops here — everything above is pure/local generation; no
             // remote mutation has happened, and nothing below this line would run
@@ -687,12 +836,48 @@ export async function enableMcp(params, deps = {}) {
             idpClientId: params.idpClientId,
             idpClientSecret: params.idpClientSecret,
         });
+        currentStep = "secrets-provisioning";
+        // Stage first, unconditionally. If the push works the file is a no-op the
+        // operator never opens; if anything about the push is uncertain they still
+        // have the thing that always works, without a re-run. Staging costs a 0600
+        // write; not staging costs an operator stranded mid-enable.
         const secretsResult = provisionSecrets(params.instance, bundle, {
             mechanism: params.secretsMechanism,
             stagingPath: params.secretsStagingPath,
         });
-        push("secrets-provisioning", true, `mechanism: ${secretsResult.mechanism}; ${secretsResult.varNames.length} vars staged at ${secretsResult.path} (0600). ${secretsResult.instructions}`);
+        // Ask the TARGET whether it can take these, rather than inferring from its
+        // hostname or its version (flair#1094 — see selectSecretsMechanism's note).
+        // An explicit --secrets-mechanism is an operator override and is honoured
+        // without a probe: they have said what they want.
+        let secretsPushed = false;
+        if (!params.secretsMechanism) {
+            const cap = await probeSecretsCapability(resolveOpsUrl(params.instance), basicAuthHeader(params.adminUser, params.adminPass), { fetchImpl: deps.fetchImpl });
+            if (cap.available && cap.publicKeyPem) {
+                const pushResult = await pushSecrets(resolveOpsUrl(params.instance), basicAuthHeader(params.adminUser, params.adminPass), bundle, cap.publicKeyPem, { fetchImpl: deps.fetchImpl });
+                secretsPushed = pushResult.allOk;
+                if (secretsPushed) {
+                    push(true, `${secretsResult.varNames.length} vars pushed to the target as enc:v1 env-secrets (tier ${PROCESS_ENV_TIER}); ` +
+                        `values were sealed locally and never sent in plaintext. Staged copy at ${secretsResult.path} (0600) is unused. ` +
+                        `Self-verify below is what proves they were DECRYPTED into the process — a target that stores them without an ` +
+                        `active env-secrets decryptor will fail there, not here.`);
+                }
+                else {
+                    const failed = pushResult.results.filter((r) => !r.ok).map((r) => `${r.name} (${r.detail})`).join("; ");
+                    push(true, `push attempted and did not complete for: ${failed}. Falling back to the staged file at ${secretsResult.path} (0600). ` +
+                        `${secretsResult.instructions}`);
+                }
+            }
+            else {
+                push(true, `mechanism: ${secretsResult.mechanism}; ${secretsResult.varNames.length} vars staged at ${secretsResult.path} (0600). ` +
+                    `${cap.reason}. ${secretsResult.instructions}`);
+            }
+        }
+        else {
+            push(true, `mechanism: ${secretsResult.mechanism} (explicit --secrets-mechanism, no capability probe); ` +
+                `${secretsResult.varNames.length} vars staged at ${secretsResult.path} (0600). ${secretsResult.instructions}`);
+        }
         // ── Identity mapping (Credential kind:idp) ────────────────────────────────
+        currentStep = "identity-mapping";
         const mapping = await provisionIdpIdentityMapping({
             opsPortOrUrl: params.instance,
             adminUser: params.adminUser,
@@ -702,7 +887,7 @@ export async function enableMcp(params, deps = {}) {
             idpProvider,
             idpSubject: params.idpSubject,
         }, { fetchImpl: deps.fetchImpl, now: deps.now });
-        push("identity-mapping", true, `principal '${principal}' ${mapping.principalCreated ? "created" : "already existed"}; ` +
+        push(true, `principal '${principal}' ${mapping.principalCreated ? "created" : "already existed"}; ` +
             `Credential(kind:idp) ${mapping.credentialReused ? "reused" : "created"} (${mapping.credentialId})`);
         // ── Gate: confirm the staged secrets are actually live before restarting ─
         let confirmed = Boolean(params.confirmSecretsApplied);
@@ -710,16 +895,18 @@ export async function enableMcp(params, deps = {}) {
             confirmed = await deps.confirmPrompt(`Have you applied the ${secretsResult.varNames.length} vars staged at ${secretsResult.path} to ${params.instance}'s environment?`);
         }
         if (!confirmed) {
-            push("apply-config-and-restart", 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).`);
+            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 };
         }
         // ── Apply config + restart ────────────────────────────────────────────────
+        currentStep = "apply-config-and-restart";
         await applyRemoteConfigAndRestart({ opsPortOrUrl: params.instance, adminUser: params.adminUser, adminPass: params.adminPass, configBlock }, { fetchImpl: deps.fetchImpl });
-        push("apply-config-and-restart", true, `set_configuration + restart succeeded against ${params.instance}`);
+        push(true, `set_configuration + restart succeeded against ${params.instance}`);
         // ── Self-verify from the operator's machine, public origin, CIMD-inclusive
+        currentStep = "self-verify";
         const verify = await selfVerifyMcpMetadata(issuer, { fetchImpl: deps.fetchImpl });
         if (!verify.ok) {
-            push("self-verify", 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 the apply-config-and-restart step.`);
             return {
                 ok: false,
                 dryRun,
@@ -729,7 +916,7 @@ export async function enableMcp(params, deps = {}) {
                 resource: `${issuer}/mcp`,
             };
         }
-        push("self-verify", true, verify.detail);
+        push(true, verify.detail);
         const resource = `${issuer}/mcp`;
         return {
             ok: true,
@@ -745,9 +932,23 @@ export async function enableMcp(params, deps = {}) {
         };
     }
     catch (err) {
-        const lastStep = steps.length > 0 ? steps[steps.length - 1].step : "signing-key";
-        push(lastStep, false, `unexpected error: ${err?.message ?? err}`);
-        return { ok: false, dryRun, steps, failedStep: lastStep };
+        // flair#1087: blame the step that was RUNNING, never the last one that
+        // succeeded. This read steps[steps.length - 1] — the last COMPLETED step —
+        // so a throw inside identity-mapping was reported against
+        // secrets-provisioning, which had just succeeded. An operator saw:
+        //
+        //     ✓ secrets-provisioning   ...apply these 5 vars in Fabric Studio, then re-run
+        //     ✗ secrets-provisioning   unexpected error: Identity mapping: ...
+        //
+        // Two results for one step, and the ✓ instructs several minutes of manual
+        // work in a web UI that the ✗ makes pointless. Read in order, you do the
+        // work first.
+        // No `?? "signing-key"` fallback: currentStep is initialised to the first
+        // step, so there is no undefined case to invent a name for. A fallback here
+        // would attribute a throw to a step chosen for being a plausible default —
+        // the same misattribution this handler exists to prevent, one layer down.
+        push(false, `unexpected error: ${err?.message ?? err}`);
+        return { ok: false, dryRun, steps, failedStep: currentStep };
     }
 }
 /**

package/dist/lib/secret-envelope.js

@@ -0,0 +1,76 @@
+/**
+ * Client-side `enc:v1:` secret envelopes — the wire format Harper's env-secrets
+ * feature reads (`hdb_secret` store and encrypted `.env` entries).
+ *
+ * ── Why this is reimplemented rather than imported ──────────────────────────
+ * `harper@5.2.0` ships this as `utility/secretEnvelope.ts`, deliberately free of
+ * Harper imports and described in its own header as "safe to publish". We could
+ * import it — except that `flair mcp enable` builds the envelope for a REMOTE
+ * target whose Harper version is discovered at runtime and is routinely NEWER
+ * than the one flair bundles. Importing would tie the format we can produce to
+ * the engine we happen to ship, which is exactly backwards: the local engine has
+ * nothing to do with what the remote instance can read.
+ *
+ * So it is reimplemented, and the compatibility claim is TESTED rather than
+ * asserted — test/unit/secret-envelope.test.ts runs Harper's own
+ * `decryptEnvelope` (vendored verbatim into the test as a reference oracle)
+ * against envelopes this module produces. A round-trip against ourselves would
+ * only prove self-consistency, which is worth nothing here: the reader is
+ * someone else's code.
+ *
+ * ── The format, from harper@5.2.0 utility/secretEnvelope.ts ─────────────────
+ * Hybrid: AES-256-GCM encrypts the value, RSA-OAEP(SHA-256) wraps the AES key.
+ *
+ *   envelope = base64url(JSON.stringify({ kid, k, iv, ct, tag }))
+ *   kid = sha256(DER SPKI of the public key), hex
+ *   k   = base64(RSA-OAEP(aesKey))     iv  = base64(12 random bytes)
+ *   ct  = base64(ciphertext)           tag = base64(GCM auth tag)
+ *
+ * The `enc:v1:` marker is NOT part of the body — it is added by callers, the
+ * same split Harper uses (the marker lives in `utility/envFile.ts`).
+ *
+ * Nothing here reads or writes a secret to disk, and no value is logged. The
+ * plaintext exists only as an argument.
+ */
+import { createCipheriv, createHash, createPublicKey, publicEncrypt, randomBytes, constants } from "node:crypto";
+/** Marker prefixed to an envelope body. Harper keys the encrypted-value path on this. */
+export const ENV_ENCRYPTED_PREFIX = "enc:v1:";
+/**
+ * SHA-256 (hex) of the DER SPKI public key — the stable key id used as `kid`.
+ *
+ * The server derives `kid` from the sealed body and trusts only that one, never
+ * a separate client-supplied field, so getting this wrong surfaces as a refusal
+ * to decrypt rather than as a silently-wrong secret.
+ */
+export function fingerprintOf(publicKeyPem) {
+    const der = createPublicKey(publicKeyPem).export({ type: "spki", format: "der" });
+    return createHash("sha256").update(der).digest("hex");
+}
+/**
+ * Seal `plaintext` for the holder of `publicKeyPem`. Returns the envelope BODY,
+ * without the `enc:v1:` marker.
+ *
+ * Randomised per call (fresh AES key and IV), so two calls on the same input
+ * differ — which is why the tests assert decryptability by the reference
+ * implementation rather than comparing against a fixed string.
+ */
+export function encryptEnvelope(plaintext, publicKeyPem, kid) {
+    const aesKey = randomBytes(32);
+    const iv = randomBytes(12);
+    const cipher = createCipheriv("aes-256-gcm", aesKey, iv);
+    const ct = Buffer.concat([cipher.update(plaintext, "utf8"), cipher.final()]);
+    const tag = cipher.getAuthTag();
+    const k = publicEncrypt({ key: publicKeyPem, padding: constants.RSA_PKCS1_OAEP_PADDING, oaepHash: "sha256" }, aesKey);
+    const envelope = {
+        kid: kid ?? fingerprintOf(publicKeyPem),
+        k: k.toString("base64"),
+        iv: iv.toString("base64"),
+        ct: ct.toString("base64"),
+        tag: tag.toString("base64"),
+    };
+    return Buffer.from(JSON.stringify(envelope)).toString("base64url");
+}
+/** Seal and prefix — what a caller sends as `set_secret`'s `envelope` field. */
+export function sealSecret(plaintext, publicKeyPem) {
+    return ENV_ENCRYPTED_PREFIX + encryptEnvelope(plaintext, publicKeyPem);
+}

package/dist/lib/secrets-push.js

@@ -0,0 +1,128 @@
+/**
+ * Pushing `mcp enable`'s staged secrets to the target over the ops API, when the
+ * target can actually take them (flair#1094).
+ *
+ * ── What replaced what ──────────────────────────────────────────────────────
+ * The mechanism used to be chosen by HOSTNAME: `selectSecretsMechanism` returned
+ * `fabric-env-secrets` for anything ending `.harperfabric.com` and `env-file`
+ * otherwise. That is wrong in both directions and was wrong in both directions
+ * on the day it was replaced:
+ *
+ *   - tps.dtrt.harperfabric.com runs Harper 5.1.26 and has NO secrets
+ *     operations — measured, `set_secret` answers "Operation 'set_secret' not
+ *     found", identical to an operation that does not exist at all — and was
+ *     selected for the automated mechanism because of its name.
+ *   - a self-hosted Harper 5.2 with the Pro env-secrets component is fully
+ *     capable and was sent down the manual Fabric Studio path because its
+ *     hostname did not match.
+ *
+ * A hostname is not a capability. Nor is a version: the write operations and the
+ * decryptor that makes a `processEnv` secret reach the process ship separately
+ * (core vs Pro). So this asks the target directly.
+ *
+ * ── What this probe does and does not establish ─────────────────────────────
+ * It establishes that the secrets OPERATIONS exist, by asking for the public key
+ * we would need anyway. It does NOT establish that the Pro decryptor is active,
+ * and no read-only call can — a secret only proves it was decrypted by being
+ * present in the process.
+ *
+ * That check already exists downstream, though NOT for the reason first claimed
+ * here. The well-known endpoint does not stop answering when the flag is off —
+ * flair serves its OWN OAuth 2.1 discovery document in that case
+ * (resources/oauth-discovery.ts). What distinguishes them is a DISCRIMINATOR:
+ * flair's document advertises `<issuer>/OAuthToken`, the plugin's advertises
+ * `<issuer>/oauth/mcp/token`, and self-verify tests for the former by name.
+ *
+ * So a push that lands in `hdb_secret` and is never decrypted shows up as a
+ * self-verify failure naming FLAIR_MCP_OAUTH — because of a comparison, not an
+ * absence. That relationship spans two files and is pinned by a test in
+ * test/unit/secrets-push.test.ts; without it, changing either side silently
+ * disables the only thing standing between "stored" and "working".
+ *
+ * ── Failure direction ───────────────────────────────────────────────────────
+ * Every uncertain outcome falls back to the staged-file flow. That path works
+ * today, on every target, and costs the operator a paste. Pushing a secret at an
+ * endpoint that may not exist costs a silent flag-OFF boot, which is the exact
+ * failure this automation is meant to remove.
+ */
+import { sealSecret } from "./secret-envelope.js";
+/** `set_secret`'s delivery tier. `processEnv` is global and cannot be scoped —
+ *  which is what `FLAIR_MCP_OAUTH` and the signing key PEM need, since both are
+ *  read from `process.env` and never from YAML. */
+export const PROCESS_ENV_TIER = "processEnv";
+async function opsCall(opsUrl, authHeader, body, fetchImpl) {
+    const res = await fetchImpl(opsUrl, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", Authorization: authHeader },
+        body: JSON.stringify(body),
+    });
+    const text = await res.text().catch(() => "");
+    let json = null;
+    try {
+        json = JSON.parse(text);
+    }
+    catch { /* non-JSON body — keep the text */ }
+    return { ok: res.ok, status: res.status, json, text };
+}
+/**
+ * Ask the target whether it can take pushed secrets, by requesting the key we
+ * would encrypt to. Never throws: an unreachable or unparseable target is a
+ * fall-back-and-say-why, not a crash mid-enable.
+ */
+export async function probeSecretsCapability(opsUrl, authHeader, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    let r;
+    try {
+        r = await opsCall(opsUrl, authHeader, { operation: "get_secrets_public_key" }, fetchImpl);
+    }
+    catch (err) {
+        return { available: false, reason: `could not reach the ops API to ask (${err?.message ?? err}) — using the staged-file flow` };
+    }
+    // "Operation '<name>' not found" is how Harper answers an operation it does
+    // not have, and it is byte-identical to the answer for an invented one. That
+    // is the signal for a target older than the env-secrets feature.
+    const errText = String(r.json?.error ?? r.text ?? "");
+    if (/not found/i.test(errText) && /get_secrets_public_key/.test(errText)) {
+        return { available: false, reason: "the target's Harper has no env-secrets operations (needs 5.2 or newer) — using the staged-file flow" };
+    }
+    if (!r.ok) {
+        return { available: false, reason: `the target refused the capability probe (HTTP ${r.status}${errText ? `: ${errText.slice(0, 120)}` : ""}) — using the staged-file flow` };
+    }
+    const pem = extractPublicKeyPem(r.json);
+    if (!pem) {
+        // Answered, but not with something we can encrypt to. Undeterminable is
+        // treated exactly like unavailable — see the failure-direction note above.
+        return { available: false, reason: "the target answered the probe without a usable public key — using the staged-file flow" };
+    }
+    return { available: true, reason: "target supports env-secrets; pushing over the ops API", publicKeyPem: pem };
+}
+/** Pull the PEM out of whatever shape the operation returns, without guessing
+ *  at a value that is not obviously a key. */
+function extractPublicKeyPem(json) {
+    const candidates = [json, json?.public_key, json?.publicKey, json?.key, json?.pem, json?.data?.public_key];
+    for (const c of candidates) {
+        if (typeof c === "string" && c.includes("BEGIN PUBLIC KEY"))
+            return c;
+    }
+    return undefined;
+}
+/**
+ * Seal and set each var. Values are encrypted client-side, so plaintext never
+ * appears in a request body — and never in this module's return value either:
+ * results carry NAMES and outcomes only.
+ */
+export async function pushSecrets(opsUrl, authHeader, vars, publicKeyPem, deps = {}) {
+    const fetchImpl = deps.fetchImpl ?? fetch;
+    const results = [];
+    for (const [name, value] of Object.entries(vars)) {
+        try {
+            const r = await opsCall(opsUrl, authHeader, { operation: "set_secret", name, envelope: sealSecret(value, publicKeyPem), tier: PROCESS_ENV_TIER }, fetchImpl);
+            const err = String(r.json?.error ?? "").slice(0, 140);
+            results.push({ name, ok: r.ok, detail: r.ok ? undefined : `HTTP ${r.status}${err ? `: ${err}` : ""}` });
+        }
+        catch (err) {
+            results.push({ name, ok: false, detail: String(err?.message ?? err).slice(0, 140) });
+        }
+    }
+    return { allOk: results.every((x) => x.ok), results };
+}

package/dist/resources/Memory.js

@@ -6,6 +6,7 @@ import { getEmbedding, getModelId } from "./embeddings-provider.js";
 import { scanFields, isStrictMode } from "./content-safety.js";
 import { invalidEntitiesResponse } from "./entity-vocab.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
+import { assertValidVisibility } from "./memory-visibility.js";
 import { DEDUP_COSINE_THRESHOLD_DEFAULT, DEDUP_LEXICAL_THRESHOLD_DEFAULT, DEDUP_MIN_CONTENT_LENGTH, computeMatchConfidence, cosineSimilarity, isConservativeMatch, } from "./dedup.js";
 import { buildProvenance, makeAuthGate, makeReadScope, makeByIdReadGate, makeScopedSearch, resolveAuthGate, stampAttribution, FORBIDDEN, UNAUTH, } from "./record-type-kit.js";
 import { RECORD_TYPES } from "./record-types.js";
@@ -600,6 +601,23 @@ export class Memory extends databases.flair.Memory {
         // existing record's visibility" concern here. Explicit visibility on the
         // write ALWAYS overrides; only stamp the default when the caller left it
         // unset. permanent|persistent → shared; standard|ephemeral|absent → private.
+        // ── flair#1009: refuse an unrecognised visibility BEFORE defaulting ──
+        // isPrivateVisibility() is an exact match on "private", so on the READ
+        // side every other value (a typo, a wrong case, a retired tier like
+        // "office") resolves to non-private and is readable by every agent on the
+        // instance. #1006 closed that at the CLI flag and the MCP tool argument;
+        // REST and the in-process API reach here without passing either.
+        //
+        // Refusing, rather than dropping the key: dropping it falls through to the
+        // durability-keyed default below, which for a permanent or persistent
+        // write is "shared" - the same widening, arrived at silently. A misspelled
+        // argument must not decide who can read a memory.
+        {
+            const visibilityError = assertValidVisibility(content.visibility);
+            if (visibilityError) {
+                return new Response(JSON.stringify({ error: "invalid_visibility", message: visibilityError }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
         if (content.visibility === undefined || content.visibility === null) {
             content.visibility = defaultVisibilityForDurability(content.durability);
         }
@@ -784,6 +802,23 @@ export class Memory extends databases.flair.Memory {
         // Explicit visibility on the write ALWAYS overrides; only stamp the
         // default when the caller left it unset AND this is a fresh record.
         // permanent|persistent → shared; standard|ephemeral|absent → private.
+        // ── flair#1009: refuse an unrecognised visibility BEFORE defaulting ──
+        // isPrivateVisibility() is an exact match on "private", so on the READ
+        // side every other value (a typo, a wrong case, a retired tier like
+        // "office") resolves to non-private and is readable by every agent on the
+        // instance. #1006 closed that at the CLI flag and the MCP tool argument;
+        // REST and the in-process API reach here without passing either.
+        //
+        // Refusing, rather than dropping the key: dropping it falls through to the
+        // durability-keyed default below, which for a permanent or persistent
+        // write is "shared" - the same widening, arrived at silently. A misspelled
+        // argument must not decide who can read a memory.
+        {
+            const visibilityError = assertValidVisibility(content.visibility);
+            if (visibilityError) {
+                return new Response(JSON.stringify({ error: "invalid_visibility", message: visibilityError }), { status: 400, headers: { "content-type": "application/json" } });
+            }
+        }
         if (!preExisting && (content.visibility === undefined || content.visibility === null)) {
             content.visibility = defaultVisibilityForDurability(content.durability);
         }

package/dist/resources/memory-visibility.js

@@ -29,9 +29,53 @@
  * missing/null/anything-other-than-'private' all count as non-private.
  */
 export const PRIVATE_VISIBILITY = "private";
+export const SHARED_VISIBILITY = "shared";
+/** The only values a WRITER may supply. Deliberately not derived from the read
+ *  predicate below — see the asymmetry note on assertValidVisibility. */
+export const WRITABLE_VISIBILITIES = [PRIVATE_VISIBILITY, SHARED_VISIBILITY];
 /** True only when visibility is the literal string "private". Null, undefined,
  *  "shared", or any other value are all non-private (see migration invariant
  *  above) — never invert this to an allowlist of "shared". */
 export function isPrivateVisibility(visibility) {
     return visibility === PRIVATE_VISIBILITY;
 }
+/**
+ * Reject a visibility a writer supplied that is not one of the two valid values.
+ * Returns an error message, or null when the value is acceptable.
+ *
+ * ── Why this is NOT the inverse of isPrivateVisibility (flair#1009) ──────────
+ *
+ * The read predicate above must stay "is this exactly 'private'", because a row
+ * written before the field existed has no visibility and must keep reading as it
+ * always did. That is a MIGRATION rule about stored data, and it is correct.
+ *
+ * The consequence is that on the read side every unrecognised value — a typo, a
+ * wrong case, a retired tier — resolves to non-private and is readable by every
+ * agent on the instance. #1006 closed that at the two writer-intent boundaries
+ * (the CLI flag, the MCP tool argument); REST and the in-process API still
+ * accepted anything, so `PUT /Memory/<id> {"visibility":"prvate"}` wrote a
+ * memory the caller believed was owner-only and everyone could read.
+ *
+ * So the two directions need different rules, and conflating them breaks one or
+ * the other:
+ *   - READING an unknown value must be permissive, or old rows break.
+ *   - WRITING an unknown value must be refused, or a typo silently widens who
+ *     can read a memory.
+ *
+ * Refusing is also the only safe option at write time. Silently dropping the key
+ * would fall back to the durability-keyed default, which for a permanent or
+ * persistent write is `shared` — the same wrong outcome, arrived at quietly.
+ *
+ * `undefined`/`null` are accepted: omitting the field is how a caller asks for
+ * the durability-keyed default, and that is a documented, intentional path.
+ */
+export function assertValidVisibility(visibility) {
+    if (visibility === undefined || visibility === null)
+        return null;
+    if (typeof visibility === "string" && WRITABLE_VISIBILITIES.includes(visibility)) {
+        return null;
+    }
+    return (`visibility must be ${WRITABLE_VISIBILITIES.map((v) => `"${v}"`).join(" or ")} ` +
+        `(got: ${JSON.stringify(visibility)}). Omit it to use the durability-keyed default: ` +
+        `permanent/persistent -> shared, standard/ephemeral -> private.`);
+}

package/dist/version-check.js

@@ -178,3 +178,48 @@ export function formatVersionNudge(result) {
         `Upgrade: npm i -g ${FLAIR_PKG_NAME}@latest`;
     return { severity: gap.severity, message };
 }
+/**
+ * The version an INSTANCE reports, or null when it cannot be determined.
+ *
+ * flair#1072. Every other line `doctor` prints about a remote target is
+ * genuinely remote; the currency claim was about the local CLI. This asks the
+ * instance instead.
+ *
+ * Returns null — never a fallback — when the instance is unreachable, answers
+ * without a version, or times out. The whole defect being fixed is a fallback
+ * to the number already in hand, and an older instance that does not expose its
+ * version is exactly the case where that fallback is most tempting and most
+ * wrong. A caller that gets null must say "unknown", not substitute its own
+ * version.
+ *
+ * Deliberately short-timeout and failure-swallowing: doctor runs against
+ * possibly-down instances by design, and "cannot determine" is a legitimate,
+ * reportable answer rather than an error to propagate.
+ */
+export async function probeInstanceVersion(baseUrl, timeoutMs = 5000, fetchImpl = fetch) {
+    const url = `${String(baseUrl).replace(/\/+$/, "")}/Health`;
+    const ctrl = new AbortController();
+    const timer = setTimeout(() => ctrl.abort(), timeoutMs);
+    try {
+        const res = await fetchImpl(url, { signal: ctrl.signal });
+        if (!res.ok)
+            return null;
+        const body = await res.json();
+        if (!body || typeof body !== "object")
+            return null;
+        const v = body.version;
+        // "dev" and other non-semver markers are real answers from a real server,
+        // but they cannot be compared against a published version. Treat them as
+        // undeterminable rather than feeding them to a semver comparison — a
+        // Fabric peer mid-failed-deploy reports exactly this (harper#2061).
+        if (typeof v !== "string" || !/^\d+\.\d+\.\d+/.test(v))
+            return null;
+        return v;
+    }
+    catch {
+        return null;
+    }
+    finally {
+        clearTimeout(timer);
+    }
+}

package/docs/hosted-on-fabric.md

@@ -59,6 +59,26 @@ On Fabric, configuration goes through the component's environment, not a local `
 
 On Fabric / managed deploys, environment variables are provisioned through Harper's Fabric secrets mechanism (encrypted at rest with `enc:v1:` storage format).
 
+### How `flair mcp enable` delivers its secrets
+
+`flair mcp enable` needs five variables live in the target's process before it restarts — including `FLAIR_MCP_OAUTH` and the RS256 signing key, both read from `process.env` only and therefore impossible to deliver via `set_configuration`.
+
+It asks the target what it can do, rather than assuming from the hostname or the version:
+
+| The target… | What happens |
+|-------------|--------------|
+| supports Harper's env-secrets operations | the five vars are **sealed locally** and pushed over the ops API. No manual step, no re-run. |
+| does not have them (Harper older than 5.2) | the vars are staged to a `0600` file and you apply them yourself, then re-run with `--confirm-secrets-applied` |
+| is unreachable, refuses the probe, or answers unusably | same staged-file fallback, and the output says **which** of those happened |
+
+Values are encrypted **before leaving your machine** — AES-256-GCM on the value, RSA-OAEP(SHA-256) wrapping the key, addressed to a public key fetched from the target. Plaintext never appears in a request body, and the command's output carries variable *names* only.
+
+The staging file is written in every case, so a fallback never strands you mid-run. When the push succeeds it simply goes unused.
+
+> **What the probe does not promise.** It establishes that the target accepts secrets, not that it will *decrypt* them — no read-only call can, since a secret only proves it was decrypted by being present in the process. The **self-verify** step at the end is what proves that. Note the endpoint does *not* go quiet when the flag is off — flair serves its own OAuth 2.1 discovery document instead, and self-verify tells them apart by the advertised `token_endpoint` (`/OAuthToken` is flair's own; the MCP one is `/oauth/mcp/token`). So a secret that is stored and never decrypted fails at self-verify with a message naming `FLAIR_MCP_OAUTH`, rather than reporting success.
+
+`--secrets-mechanism <fabric-env-secrets|env-file>` remains an explicit override and skips the probe entirely.
+
 ---
 
 ## Agent authentication

package/docs/upgrade.md

@@ -2,7 +2,7 @@
 
 This page covers the mechanics of upgrading Flair — the general path, valid across
 versions. For **what changed in a specific release** (behavior changes, new surfaces,
-breaking changes), see [`CHANGELOG.md`](../CHANGELOG.md) — each version has its own
+breaking changes), see [`CHANGELOG.md`](https://github.com/tpsdev-ai/flair/blob/main/CHANGELOG.md) — each version has its own
 `## [X.Y.Z]` section. Check the CHANGELOG entries between your current version and the
 target version before upgrading anything you depend on in production.
 
@@ -370,7 +370,7 @@ flair restore ~/flair-backup-<date>.json
 
 ### Known issue — upgrading *from* an older version can still report a false rollback
 
-The 0.25.1 fix (see [`CHANGELOG.md`](../CHANGELOG.md)) makes `flair upgrade` resolve a
+The 0.25.1 fix (see [`CHANGELOG.md`](https://github.com/tpsdev-ai/flair/blob/main/CHANGELOG.md)) makes `flair upgrade` resolve a
 credentials-only post-restart-verification failure to `healthy-unverified` instead of
 rolling back. That fix is **forward-only**: it lives in the *new* CLI code, but an
 upgrade's post-restart verification is run by the CLI that was already installed
@@ -526,7 +526,7 @@ you haven't personally tested.
 
 ## See also
 
-- [`CHANGELOG.md`](../CHANGELOG.md) — what actually changed, version by version.
+- [`CHANGELOG.md`](https://github.com/tpsdev-ai/flair/blob/main/CHANGELOG.md) — what actually changed, version by version.
 - [`docs/releasing.md`](releasing.md) — how a release gets published in the first
   place (staged npm publish with 2FA approval), if you're curious why a new version
   shows up when it does.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.36.0",
+  "version": "0.38.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",
@@ -52,8 +52,7 @@
     "prepublishOnly": "npm run build && npm run build:cli",
     "test": "bun test",
     "test:e2e": "playwright test",
-    "release": "./scripts/release.sh",
-    "postinstall": "node -e \"try{const{chmodSync,statSync}=require('fs');for(const p of ['dist/cli-shim.cjs','dist/cli.js']){try{if(statSync(p).isFile()){chmodSync(p,0o755);console.error('@tpsdev-ai/flair: chmod +x ' + p + ' OK')}}catch(e){if(e.code!=='ENOENT')console.error('postinstall warn:',e.message)}}}catch(e){console.error('postinstall warn:',e.message)}\""
+    "release": "./scripts/release.sh"
   },
   "publishConfig": {
     "access": "public"
@@ -73,7 +72,11 @@
     "tweetnacl": "1.0.3"
   },
   "overrides": {
-    "react-native-fs": "npm:empty-npm-package@1.0.0"
+    "react-native-fs": "npm:empty-npm-package@1.0.0",
+    "brace-expansion": "^5.0.9",
+    "undici": "^8.9.0",
+    "fast-uri": "^4.1.2",
+    "hono": "^4.12.34"
   },
   "devDependencies": {
     "@playwright/test": "1.59.1",