@tpsdev-ai/flair 0.35.0 → 0.37.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

@@ -355,8 +355,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 +430,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;
@@ -630,29 +684,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 +731,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 +758,14 @@ export async function enableMcp(params, deps = {}) {
             idpClientId: params.idpClientId,
             idpClientSecret: params.idpClientSecret,
         });
+        currentStep = "secrets-provisioning";
         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}`);
+        push(true, `mechanism: ${secretsResult.mechanism}; ${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 +775,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 +783,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 +804,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 +820,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 };
     }
 }
 /**