@tpsdev-ai/flair 0.30.0 → 0.31.1

package/dist/cli.js

@@ -17,12 +17,20 @@ import { checkServerHandshake, formatHandshakeNudge, invalidateHandshakeCache }
 import { probeInstance } from "./probe.js";
 import { sweepFleet, renderFleetSweepTable, FLEET_EXIT_OK, } from "./fleet-verify.js";
 import { markStale, sortOldestVersionFirst } from "./fleet-presence.js";
-import { detectClients, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
+import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemini, wireCursor } from "./install/clients.js";
+import { flairCliVersion, mcpServerSpec, unpinnedSpecWarning } from "./lib/mcp-spec.js";
 import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, defaultMcpIssuer, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
 import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMcpMetadata, } from "./lib/mcp-enable.js";
 import { readClientMcpBlock, checkClaudeMdBootstrap, checkSessionStartHook, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, inferSoleAgentId, fixCommandAgentHint, describeAgentGateFinding, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
 import { installHook, uninstallHook, hookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
-import { readSecretFileSecure, readAdminPassFileSecure, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
+import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
+import { validateSnapshotArchive, extractSnapshotSafely } from "./lib/safe-snapshot-extract.js";
+import { escapeXml, unescapeXml } from "./lib/xml-escape.js";
+// Value-only static import so `--interval`'s advertised default cannot drift
+// from the one the scheduler actually validates against. The module itself is
+// still loaded lazily at call time (the `await import()`s below) for the
+// functions — this pulls in nothing but node builtins.
+import { DEFAULT_INTERVAL_SECONDS as FEDERATION_SYNC_DEFAULT_INTERVAL } from "./federation/scheduler.js";
 // Federation crypto helpers — inlined to avoid cross-boundary imports from
 // src/ into resources/, which don't survive npm packaging (see also
 // resources/federation-crypto.ts; the two must stay in sync).
@@ -170,6 +178,55 @@ function launchdLabel(dataDir) {
 function launchdPlistPath(label, launchAgentsDir = defaultLaunchAgentsDir()) {
     return join(launchAgentsDir, `${label}.plist`);
 }
+/**
+ * Build the launchd plist for a Flair instance.
+ *
+ * Extracted from the `init` command so the XML escaping is unit-testable
+ * without touching real launchd or ~/Library/LaunchAgents. EVERY interpolated
+ * value goes through escapeXml() — including ones that look safe today (the
+ * label is a hash, the ports are numbers), because "this field can't contain
+ * a special character" is exactly the assumption that rots when a field's
+ * source changes. A future key added to this template that skips escapeXml()
+ * is the bug reappearing.
+ *
+ * Never log the return value: it embeds HDB_ADMIN_PASSWORD.
+ */
+export function buildLaunchdPlist(opts) {
+    const e = escapeXml;
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key><string>${e(opts.label)}</string>
+  <key>ProgramArguments</key>
+  <array>
+    <string>${e(opts.execPath)}</string>
+    <string>${e(opts.harperBinPath)}</string>
+    <string>run</string>
+    <string>.</string>
+  </array>
+  <key>WorkingDirectory</key><string>${e(opts.workingDirectory)}</string>
+  <key>EnvironmentVariables</key>
+  <dict>
+    <key>ROOTPATH</key><string>${e(opts.dataDir)}</string>
+    <key>FLAIR_MODELS_DIR</key><string>${e(opts.modelsDir)}</string>
+    <key>HARPER_SET_CONFIG</key><string>${e(opts.setConfig)}</string>
+    <key>DEFAULTS_MODE</key><string>dev</string>
+    <key>HDB_ADMIN_USERNAME</key><string>${e(opts.adminUser)}</string>
+    <key>HDB_ADMIN_PASSWORD</key><string>${e(opts.adminPass)}</string>
+    <key>THREADS_COUNT</key><string>1</string>
+    <key>NODE_HOSTNAME</key><string>localhost</string>
+    <key>HTTP_PORT</key><string>${e(String(opts.httpPort))}</string>
+    <key>OPERATIONSAPI_NETWORK_PORT</key><string>${e(opts.opsNetworkPort)}</string>
+    <key>LOCAL_STUDIO</key><string>false</string>
+  </dict>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>StandardOutPath</key><string>${e(join(opts.dataDir, "log", "launchd-stdout.log"))}</string>
+  <key>StandardErrorPath</key><string>${e(join(opts.dataDir, "log", "launchd-stderr.log"))}</string>
+</dict>
+</plist>`;
+}
 /**
  * Which launchd label an existing installation for `dataDir` is actually
  * registered under right now. Prefers the new instance-scoped label if its
@@ -248,6 +305,15 @@ function configPath() {
         return ymlPath;
     return yamlPath;
 }
+/**
+ * `~/.flair/config.yaml`'s `port:` — the PER-USER file, which describes the
+ * default install and only the default install (flair#914).
+ *
+ * Kept for the commands that have no `--data-dir` of their own and therefore
+ * genuinely mean the default instance, and as the source the instance-local
+ * migration reads from. Anything that resolves a port for a NAMED instance
+ * must go through `resolveHttpPort`, not this.
+ */
 function readPortFromConfig() {
     try {
         const p = configPath();
@@ -261,6 +327,121 @@ function readPortFromConfig() {
     catch { /* ignore */ }
     return null;
 }
+// ─── Harper's own config: where an instance's port actually lives (flair#914) ─
+//
+// `~/.flair/config.yaml` records ONE port for the whole user. `flair init
+// --data-dir X --port P` wrote it unconditionally, so a second instance
+// overwrote the first's recorded port and `resolveHttpPort()` then answered a
+// per-instance question from a file that cannot tell instances apart — with no
+// data dir as input at all.
+//
+// This is the dual of flair#902 (fixed in flair#910): that one resolved the
+// INSTANCE from the wrong directory; this one resolved the PORT from a file
+// that has no notion of instances. The fix is the same shape flair#910
+// established — the data directory IS the instance identity, and everything
+// else derives from it.
+//
+// The port is read from HARPER'S config, not a Flair-owned file beside it.
+// Harper writes `<dataDir>/harper-config.yaml` at install (configUtils'
+// `createConfigFile`) and rewrites it from its environment on EVERY boot, so it
+// records `rootPath`, `http.port` and `operationsApi.network.port` for the
+// instance served from this directory — written by the process that actually
+// binds the sockets. That is what makes it authoritative.
+//
+// A Flair-owned file recording the same three facts (the `flair-instance.yaml`
+// this replaces) was a fourth artefact duplicating the first, with nothing to
+// reconcile the two. It does not stay true: boot an existing data directory on
+// a different port and Harper updates its own config while the Flair copy keeps
+// the old number — a silent wrong answer that looks authoritative. Measured, not
+// theorised.
+//
+// The layering this restores: Harper core owns the data root and the ports, the
+// Flair component owns memory semantics, local wrappers own convenience.
+//
+// Everything here is a PLAIN FILE READ. Resolution must work while the instance
+// is DOWN — locating a stopped instance is most of what `flair start`, `stop`
+// and `doctor` are for — so it must never require the process it is trying to
+// find.
+//
+// Enumeration (`flair instances`) is deliberately NOT accommodated here. If it
+// ever lands it is a DERIVED registry written by a scan, never by `init`, so
+// that it can be stale without being wrong.
+/**
+ * Harper's config filenames, in Harper's own resolution order — current name
+ * first, pre-rename legacy name second (harper `bin/run.js` and
+ * `config/configUtils.js` both fall back this way, and `docs/rem.md` documents
+ * the pair). An install predating the rename still serves from the legacy name,
+ * so reading only the current one would make a working instance unaddressable.
+ */
+const HARPER_CONFIG_FILENAMES = ["harper-config.yaml", "harperdb-config.yaml"];
+/** Harper's config file for `dataDir`, or null when Harper has written none there yet. */
+function harperConfigPath(dataDir) {
+    const dir = resolve(dataDir);
+    for (const name of HARPER_CONFIG_FILENAMES) {
+        const p = join(dir, name);
+        if (existsSync(p))
+            return p;
+    }
+    return null;
+}
+/**
+ * Parse Harper's config for `dataDir`. Returns null when absent or unreadable —
+ * a malformed config is Harper's problem to report, and resolution falling back
+ * to its next rung beats a crash in an unrelated command.
+ *
+ * Parsed as YAML, never regex-matched. The values wanted here are NESTED
+ * (`http.port`, `operationsApi.network.port`), so line-anchored matching on a
+ * bare key name would find `port:` under whichever block came first — wrong
+ * answer, not just an ugly one. It is also how the predecessor earned a
+ * blocking `detect-non-literal-regexp` SAST finding for building a RegExp from
+ * a key name.
+ */
+function readHarperConfig(dataDir) {
+    try {
+        const p = harperConfigPath(dataDir);
+        if (!p)
+            return null;
+        const parsed = parseYaml(readFileSync(p, "utf-8"));
+        return parsed && typeof parsed === "object" ? parsed : null;
+    }
+    catch { /* ignore — see doc comment */ }
+    return null;
+}
+/**
+ * A Harper port config value as a number.
+ *
+ * Harper accepts both a bare port (`9926`, all interfaces) and the
+ * host-qualified `host:port` form flair writes for the ops API (`127.0.0.1:9925`
+ * — see `opsNetworkPortValue`). Both name the same port; only the bind differs,
+ * and `detectOpsApiAllInterfacesBind` is what reads the host half. Splits on the
+ * LAST colon so an IPv6 literal (`[::1]:9925`) keeps its port.
+ */
+export function harperPortValue(value) {
+    if (value === undefined || value === null)
+        return null;
+    if (typeof value === "number")
+        return Number.isInteger(value) && value > 0 ? value : null;
+    const str = String(value).trim();
+    if (str === "")
+        return null;
+    const lastColon = str.lastIndexOf(":");
+    const portPart = lastColon > 0 ? str.slice(lastColon + 1) : str;
+    if (!/^\d+$/.test(portPart))
+        return null;
+    const n = Number(portPart);
+    return n > 0 ? n : null;
+}
+/** This instance's HTTP port, from Harper's own config in its data directory. */
+function readPortFromHarperConfig(dataDir) {
+    return harperPortValue(readHarperConfig(dataDir)?.http?.port);
+}
+/** Which instance a command is addressing: `--data-dir` if given, else the default install. */
+function instanceDataDir(opts) {
+    return opts.dataDir ? resolve(opts.dataDir) : defaultDataDir();
+}
+function isDefaultDataDir(dataDir) {
+    return resolve(dataDir) === resolve(defaultDataDir());
+}
 /**
  * Read the persisted ops-API bind host from ~/.flair/config.yaml (flair#863).
  * Line-anchored so it can't be satisfied by some other key that merely ends
@@ -295,9 +476,45 @@ function readOpsPortFromConfig(path = configPath()) {
     catch { /* ignore */ }
     return null;
 }
-// Unified port resolution: --port flag > FLAIR_URL env > config file > default
-// Every command that talks to Harper MUST use these helpers.
-function resolveHttpPort(opts) {
+/**
+ * Unified port resolution: `--port` flag > `FLAIR_URL` env > Harper's own config
+ * in the instance's data directory > (default install only) the per-user config
+ * > default.
+ *
+ * Every command that talks to Harper MUST use this helper.
+ *
+ * `opts.dataDir` names the instance (flair#914). Commands without a
+ * `--data-dir` flag do not carry one and therefore mean the default install,
+ * which is what they have always meant.
+ *
+ * `mode` distinguishes ADDRESSING an instance that is expected to exist from
+ * CREATING one:
+ *
+ *   - `"address"` (default) — a non-default data directory Harper has never
+ *     written a config into is a hard error. That case is precisely the bug
+ *     this fixes: falling back to the per-user file would answer with some
+ *     OTHER instance's port, which is a silent wrong answer wearing a
+ *     migration. The default install keeps today's behaviour exactly.
+ *   - `"create"` — `flair init`, which is establishing the instance rather
+ *     than looking one up. An unknown instance takes DEFAULT_PORT, the same as
+ *     a clean install has always done, instead of the refusal that would make
+ *     `flair init --data-dir <new>` impossible.
+ *
+ * The "create" rung is load-bearing rather than hypothetical (flair#928).
+ * `init`'s `--port` used to carry a commander default of DEFAULT_PORT, so
+ * `opts.port` was ALWAYS set there and this function returned on the first rung
+ * — including when re-initialising an instance already serving a different
+ * port, which was silently renumbered to DEFAULT_PORT. Commander cannot tell
+ * "the user passed the default" from "the user passed nothing", so the default
+ * was the bug. It is gone; a bare `init` now falls through to the ladder, and
+ * only a directory no instance has ever been served from reaches DEFAULT_PORT.
+ *
+ * Nothing is copied, migrated or written here. Harper's config already IS the
+ * per-instance record, so there is no second file to keep in step — which is
+ * the whole reason the port is read from it. The per-user file stays exactly as
+ * it is for the default install that has always relied on it.
+ */
+function resolveHttpPort(opts, mode = "address") {
     if (opts.port !== undefined && opts.port !== null) {
         const n = Number(opts.port);
         if (!isNaN(n) && n > 0)
@@ -309,7 +526,28 @@ function resolveHttpPort(opts) {
         if (m)
             return Number(m[1]);
     }
-    return readPortFromConfig() ?? DEFAULT_PORT;
+    const dataDir = instanceDataDir(opts);
+    // 1. Harper's own config for this instance. Once Harper has written one it is
+    //    the only answer — it is maintained by the process that binds the socket.
+    const harperPort = readPortFromHarperConfig(dataDir);
+    if (harperPort !== null)
+        return harperPort;
+    // 2. Harper has written nothing here. For the DEFAULT install the per-user
+    //    file is about this instance by definition — a single-instance install is
+    //    the overwhelmingly common case and its recorded port is correct — so it
+    //    stays the answer for existing installs. Read, never rewritten.
+    if (isDefaultDataDir(dataDir)) {
+        return readPortFromConfig() ?? DEFAULT_PORT;
+    }
+    // 3. A non-default directory Harper has never written to. `init` may go on to
+    //    create the instance; nothing else may guess.
+    if (mode === "create")
+        return DEFAULT_PORT;
+    throw new Error(`cannot determine which port ${dataDir} serves: Harper has written no config there `
+        + `(no ${HARPER_CONFIG_FILENAMES.join(" or ")}), so that directory does not hold an instance yet. `
+        + `Falling back to ~/.flair/config.yaml would answer with the port of a DIFFERENT instance — that file records one port `
+        + `for the whole user, not one per data directory. `
+        + `Pass --port <port> to say which port that instance serves, or run 'flair init --data-dir ${dataDir} --port <port>' to create it.`);
 }
 // Unified base URL resolution. Precedence:
 //   --target > --url > FLAIR_TARGET env > FLAIR_URL env > http://127.0.0.1:<resolveHttpPort>
@@ -331,6 +569,15 @@ function resolveAgentIdOrEnv(opts) {
     return opts.agent || process.env.FLAIR_AGENT_ID || null;
 }
 // Ops port resolution: --ops-port flag > FLAIR_OPS_PORT env > config opsPort > httpPort - 1
+//
+// Deliberately NOT routed through Harper's per-instance config the way
+// resolveHttpPort is (flair#914). The last rung couples the ops port to the HTTP
+// port the CALLER named, and that coupling is what makes `flair init --port N`
+// land its ops API at N-1 on a host that already runs an instance. A Harper rung
+// above it would answer that call with the EXISTING instance's ops port instead,
+// which is the bug flair#914 fixed pointing the other way. The ops port becomes
+// per-instance when the lifecycle commands grow `--data-dir` and there is a
+// named instance to attribute it to.
 function resolveOpsPort(opts) {
     if (opts.opsPort !== undefined && opts.opsPort !== null) {
         const n = Number(opts.opsPort);
@@ -812,6 +1059,36 @@ function writeConfig(port, opsPort, opsBind, path = configPath()) {
         body += `opsBind: ${resolvedOpsBind}\n`;
     writeFileSync(path, body);
 }
+/**
+ * Persist the coordinates of the instance served from `dataDir` (flair#914).
+ *
+ * Harper records its OWN coordinates — `rootPath`, `http.port`,
+ * `operationsApi.network.port` — into `<dataDir>/harper-config.yaml` on every
+ * boot, and that is what `resolveHttpPort` reads. So there is nothing
+ * instance-local for flair to write: the instance already describes itself, and
+ * a second copy is a drift source, not a record (flair#937).
+ *
+ * What remains is the per-user file, and the GUARD on it is the whole of the
+ * flair#914 fix. `init` used to write `~/.flair/config.yaml` unconditionally, so
+ * `flair init --data-dir X --port P` overwrote whatever port the DEFAULT install
+ * had recorded, and every later lookup answered with P. Writing it only for the
+ * default install is what makes one instance's `init` unable to renumber
+ * another's.
+ *
+ * The guard lives HERE rather than at the call sites: a caller that forgets it
+ * reintroduces flair#914 silently, and there is no test that would notice at the
+ * call site it was forgotten in.
+ *
+ * It keeps the readers that have no `--data-dir` of their own
+ * (`readPortFromConfig` — `flair uninstall`, the `rem` scheduler, `api()`,
+ * doctor's config line) correct for the one instance they are able to address.
+ * Those read Harper's config directly when the lifecycle commands grow the flag,
+ * and this file goes with them.
+ */
+function persistDefaultInstallCoordinates(dataDir, port, opsPort, opsBind) {
+    if (isDefaultDataDir(dataDir))
+        writeConfig(port, opsPort, opsBind);
+}
 function privKeyPath(agentId, keysDir) {
     return join(keysDir, `${agentId}.key`);
 }
@@ -822,30 +1099,135 @@ function flairPackageDir() {
     // dist/cli.js → package root (one level up from dist/)
     return join(import.meta.dirname ?? __dirname, "..");
 }
-function harperBin() {
-    // Resolve relative to this file's location (dist/cli.js → ../node_modules/...).
-    //
-    // flair#870: flair depends on the BARE `harper` package name. The scoped
-    // `@harperfast/harper` segments are kept as a fallback so an in-place upgrade
-    // over a pre-#870 install (whose node_modules still holds the scoped copy,
-    // and whose Harper is the one currently serving the data dir) keeps booting
-    // until the next clean install. Bare name is tried first so a tree that has
-    // BOTH resolves to the one flair actually declares.
-    const roots = [
-        join(import.meta.dirname ?? __dirname, ".."),
-        process.cwd(),
-    ];
-    const pkgSegments = [["harper"], ["@harperfast", "harper"]];
-    const candidates = [];
+/**
+ * Harper npm package names this build knows about, newest-convention first.
+ *
+ * flair#870: flair depends on the BARE `harper` package name. The scoped
+ * `@harperfast/harper` name is kept as a fallback so an in-place upgrade over
+ * a pre-#870 install (whose node_modules still holds the scoped copy, and
+ * whose Harper is the one currently serving the data dir) keeps booting until
+ * the next clean install. Bare name is tried first so a tree that has BOTH
+ * resolves to the one flair actually declares.
+ *
+ * This list is a FALLBACK, not the authority — see declaredHarperPackageNames.
+ */
+const KNOWN_HARPER_PACKAGE_NAMES = ["harper", "@harperfast/harper"];
+/**
+ * The Harper package name(s) the install at `packageRoot` actually declares,
+ * read fresh off disk on every call.
+ *
+ * flair#905: `flair upgrade` replaces this package tree while the CLI is
+ * executing out of it, so anything the running code "knows" about the tree
+ * describes the tree that WAS there, not the one that is. That is exactly how
+ * the 0.29.0 → 0.30.0 upgrade broke: 0.30.0 renamed its Harper dependency
+ * `@harperfast/harper` → `harper` (flair#870), 0.29.0's resolver only ever
+ * probed the scoped name, and the post-swap tree no longer had it — so the
+ * restart reported "Harper binary not found" against an install that was
+ * perfectly intact. Deriving the name from the package.json sitting at
+ * `packageRoot` reads the POST-swap truth instead of a compiled-in guess, so a
+ * future rename cannot break the same way.
+ *
+ * Matches `harper` and `@scope/harper` only — never `harper-fabric-embeddings`
+ * or any other `harper`-prefixed dependency.
+ */
+export function declaredHarperPackageNames(packageRoot) {
+    try {
+        const pkg = JSON.parse(readFileSync(join(packageRoot, "package.json"), "utf-8"));
+        return Object.keys(pkg.dependencies ?? {}).filter((n) => /^(@[^/]+\/)?harper$/.test(n));
+    }
+    catch {
+        return [];
+    }
+}
+/**
+ * Locate a Harper binary under `roots`, and report every path that was tried.
+ *
+ * The `searched` list is not decoration: "Harper binary not found" with no
+ * paths is unactionable, and the message it replaced named the wrong remedy
+ * (flair#905). Callers surface these paths verbatim.
+ */
+export function resolveHarperBin(roots) {
+    const searched = [];
     for (const root of roots) {
-        for (const segs of pkgSegments) {
-            candidates.push(join(root, "node_modules", ...segs, "dist", "bin", "harper.js"));
+        const names = [...declaredHarperPackageNames(root), ...KNOWN_HARPER_PACKAGE_NAMES];
+        for (const name of names) {
+            const candidate = join(root, "node_modules", ...name.split("/"), "dist", "bin", "harper.js");
+            if (searched.includes(candidate))
+                continue;
+            searched.push(candidate);
+            if (existsSync(candidate))
+                return { path: candidate, searched };
         }
     }
-    for (const c of candidates)
-        if (existsSync(c))
-            return c;
-    return null;
+    return { path: null, searched };
+}
+/**
+ * Roots under which a Harper install is looked for: this package's own
+ * directory (dist/cli.js → ../node_modules/...) then the caller's cwd.
+ *
+ * Recomputed per call rather than captured at module load — see
+ * declaredHarperPackageNames for why anything cached across a package swap is
+ * a bug waiting to happen.
+ */
+function harperSearchRoots() {
+    return [flairPackageDir(), process.cwd()];
+}
+/**
+ * The operator-facing message for "we looked for Harper and it isn't there".
+ *
+ * flair#905: the text this replaces was `Harper binary not found. Run 'flair
+ * init' first.` — which is wrong twice over on an initialised instance. It
+ * names no path, so there is nothing to check; and `flair init` cannot fix a
+ * missing Harper (init resolves the same binary the same way) while it CAN be
+ * mistaken for "re-provision my instance" by someone reading it at 3am. A
+ * missing binary is an incomplete package tree, so the remedy is a reinstall.
+ */
+export function harperBinNotFoundMessage(searched) {
+    return [
+        "Harper binary not found — this Flair package tree looks incomplete.",
+        "   Searched:",
+        ...searched.map((p) => `     ${p}`),
+        "   Reinstall the package: npm install -g @tpsdev-ai/flair@latest",
+        "   Your data in ~/.flair is untouched — `flair init` will NOT fix this (it resolves the same binary).",
+    ].join("\n");
+}
+function harperBin() {
+    return resolveHarperBin(harperSearchRoots()).path;
+}
+/**
+ * Parse `lsof -ti` output into PIDs safe to signal as "the thing on this port".
+ *
+ * Two filters, both load-bearing (flair#800, extended by flair#905):
+ *
+ * A bare `lsof -ti :<port>` matches CLIENT sockets as well as the listening
+ * server — including the calling process's OWN keep-alive connections, left by
+ * anything that has spoken HTTP to that port in this run (the version-handshake
+ * nudge on every command, a health probe, a caller's `fetch`). `-sTCP:LISTEN`
+ * on the command narrows it to the server; this function is the second half:
+ * never return our own PID, whatever lsof said. flair#800 was that exact
+ * self-SIGTERM in `flair upgrade`'s stop step; the same unfiltered pattern
+ * survived in `flair stop`, `flair uninstall` and `flair doctor`, where it can
+ * kill the caller, kill an unrelated client, or tell an operator to `kill` the
+ * PID of the shell they are typing into.
+ */
+export function parseListeningPids(lsofOutput, selfPid) {
+    return (lsofOutput ?? "")
+        .trim()
+        .split("\n")
+        .map((s) => Number(s.trim()))
+        .filter((pid) => Number.isFinite(pid) && pid > 0 && pid !== selfPid);
+}
+/**
+ * PIDs LISTENING on `port`, never this process. Empty when nothing is there or
+ * lsof is unavailable — callers treat that as "not running".
+ */
+function listeningPidsOnPort(port, exec) {
+    try {
+        return parseListeningPids(exec(`lsof -ti :${port} -sTCP:LISTEN`), process.pid);
+    }
+    catch {
+        return [];
+    }
 }
 // ─── Helpers ─────────────────────────────────────────────────────────────────
 function b64(bytes) {
@@ -1991,51 +2373,26 @@ async function runSoulWizard(agentId) {
     return entries.filter(([, v]) => v.trim().length > 0);
 }
 // ─── Program ─────────────────────────────────────────────────────────────────
-// Read version from package.json at the package root
-const __pkgDir = join(import.meta.dirname ?? __dirname, "..");
-const __pkgVersion = (() => {
-    try {
-        return JSON.parse(readFileSync(join(__pkgDir, "package.json"), "utf-8")).version;
-    }
-    catch {
-        return "unknown";
-    }
-})();
-/**
- * The `@tpsdev-ai/flair-mcp` spec written into a client's MCP config.
- *
- * PINNED, deliberately. A bare `npx -y @tpsdev-ai/flair-mcp` re-resolves to
- * whatever is currently published on EVERY agent session — so a single bad
- * publish (stolen credentials, a malicious commit that clears review, or a
- * compromised dependency of the MCP package) reaches every wired user
- * silently, with no lockfile and no review step in the path. The postmark-mcp
- * incident was exactly this shape: a legitimate publish by the legitimate
- * owner, propagating for 16 days before anyone noticed. Worse, a yank does
- * not help — unpinned clients keep resolving latest.
- *
- * Our publish side is already hardened (OIDC staged publish, human 2FA at the
- * release gate), but that defends against credential theft, not against a bad
- * version being published legitimately. The consumer side is where that gap
- * closes, and pinning is what closes it: a wired client keeps running the
- * exact version that was current when it was wired, and moving forward
- * becomes a deliberate act.
- *
- * flair and flair-mcp ship in version lockstep from this monorepo, so the
- * running CLI's own version is the correct pin. `flair init` re-run rewires
- * to the then-current version; see the upgrade-rewire follow-up issue for
- * making `flair upgrade` do the same.
- *
- * Falls back to the unpinned spec only when the version can't be read, which
- * is the same condition under which `--version` reports "unknown" — a broken
- * install, where a working MCP wiring matters more than a precise pin.
- */
-export function mcpServerSpec(version = __pkgVersion) {
-    return version && version !== "unknown"
-        ? `@tpsdev-ai/flair-mcp@${version}`
-        : "@tpsdev-ai/flair-mcp";
-}
+// This CLI's own version. Resolution lives in src/lib/mcp-spec.ts so that the
+// client-wiring code (src/install/clients.ts) shares ONE definition of both
+// the version and the MCP spec derived from it — see flair#907 for what
+// happened when the pin lived next to a single call site.
+const __pkgVersion = flairCliVersion();
+// mcpServerSpec now lives in src/lib/mcp-spec.ts alongside the version
+// resolution it depends on, so every writer shares it. Re-exported here
+// because it is part of this module's public surface (tests and callers
+// import it from src/cli.ts).
+export { mcpServerSpec };
 const program = new Command();
 program.name("flair").version(__pkgVersion, "-v, --version");
+// flair#926: an option declared on a parent is consumed by the PARENT even when
+// it appears after a subcommand name, so a subcommand must NOT redeclare one —
+// the duplicate never receives a value, it only makes the flag look local.
+// Removing those duplicates would have hidden working flags from the
+// subcommand's help, so the help is taught to show inherited options instead.
+// This is commander's own answer to the problem, and it applies to every
+// subcommand at once rather than one hand-maintained list of exceptions.
+program.configureHelp({ showGlobalOptions: true });
 // ─── CLI↔server version handshake (flair#695 §B) ────────────────────────────
 // Every command invocation gets a cheap, cached (~60s), short-timeout check
 // of the running server's version against this CLI's own — catches the
@@ -2084,7 +2441,12 @@ program
     .description("One-command Flair setup — bootstrap the instance, register an agent, and wire MCP clients")
     .option("--agent-id <id>", "Agent ID to register (omit to bootstrap instance without agent)")
     .option("--agent <id>", "Alias for --agent-id")
-    .option("--port <port>", "Harper HTTP port", String(DEFAULT_PORT))
+    // No commander default (flair#928). A default here is indistinguishable from
+    // the user typing it, so a BARE `flair init` used to state DEFAULT_PORT and
+    // renumber an instance already serving a custom one. Absent means absent, and
+    // resolveHttpPort's "create" ladder supplies DEFAULT_PORT for a genuinely new
+    // instance — which is the only case that ever wanted one.
+    .option("--port <port>", "Harper HTTP port (default: this instance's current port, or 19926 for a new one)")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--ops-bind <addr>", "Harper ops API bind address (env: FLAIR_OPS_BIND; default: 127.0.0.1 loopback-only for single-host — pass e.g. 0.0.0.0 for multi-host/Fabric remote admin)")
     .option("--admin-pass <pass>", "Admin password (generated if omitted)")
@@ -2284,11 +2646,26 @@ program
         return;
     }
     // ── Local init (full one-command setup) ──
-    const httpPort = resolveHttpPort(opts);
-    const opsPort = resolveOpsPort(opts);
-    const opsBindHost = resolveOpsBindHost(opts);
     const keysDir = opts.keysDir ?? defaultKeysDir();
     const dataDir = opts.dataDir ?? defaultDataDir();
+    // "create" mode (flair#914): init ESTABLISHES an instance, so a data
+    // directory with no recorded port is a new instance taking the default,
+    // not the hard error every other caller gets — otherwise `flair init
+    // --data-dir <new>` could never succeed. `dataDir` is resolved first so
+    // this is never asked before the instance is known.
+    //
+    // flair#928: `--port` deliberately carries NO commander default, so a bare
+    // `init` reaches the ladder below instead of restating DEFAULT_PORT and
+    // renumbering an instance that already serves a custom port. `init` is
+    // `flair doctor`'s standing remedy and is recommended in ten places, so the
+    // command handed to an operator whose install is already wrong must not be
+    // the one that moves their port.
+    const httpPort = resolveHttpPort(opts, "create");
+    // The already-resolved port is handed to the ops resolver rather than
+    // letting it re-resolve — its last rung is `resolveHttpPort(opts) - 1`,
+    // which would ask the same question again in "address" mode.
+    const opsPort = resolveOpsPort({ ...opts, port: httpPort });
+    const opsBindHost = resolveOpsBindHost(opts);
     // Resolve MCP client selection (union of init's auto-wire + the multi-client
     // detection/wiring that the front-door command provides). `--no-mcp` sets
     // opts.mcp === false (commander negates the flag). Validate an explicit
@@ -2439,11 +2816,14 @@ program
             }
             mkdirSync(dataDir, { recursive: true });
             // Detect whether Harper has already been installed in this data dir.
-            // harper-config.yaml is created during install — its presence means
+            // Harper's config is created during install — its presence means
             // install already ran. Re-running install against an existing data dir
             // crashes in Harper v5 beta.6+ (checkForExistingInstall queries the
-            // database before the env is initialized).
-            const alreadyInstalled = existsSync(join(dataDir, "harper-config.yaml"));
+            // database before the env is initialized). Goes through
+            // harperConfigPath so an install predating Harper's config-file rename
+            // (harperdb-config.yaml) is still recognised as installed rather than
+            // re-installed over.
+            const alreadyInstalled = harperConfigPath(dataDir) !== null;
             const opsSocket = join(dataDir, "operations-server");
             // authorizeLocal: false (flair#654) — a credential-less loopback ops-API
             // request is no longer auto-authorized as super_user. Every ops-API
@@ -2591,40 +2971,19 @@ program
                 // backend on every KeepAlive restart in-process. See that file's
                 // header (flair#694) for why this replaced the old HARPER_CONFIG
                 // plist line.
-                const escapeXml = (s) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/"/g, "&quot;");
-                const plist = `<?xml version="1.0" encoding="UTF-8"?>
-<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
-<plist version="1.0">
-<dict>
-  <key>Label</key><string>${label}</string>
-  <key>ProgramArguments</key>
-  <array>
-    <string>${process.execPath}</string>
-    <string>${harperBinPath}</string>
-    <string>run</string>
-    <string>.</string>
-  </array>
-  <key>WorkingDirectory</key><string>${flairPackageDir()}</string>
-  <key>EnvironmentVariables</key>
-  <dict>
-    <key>ROOTPATH</key><string>${dataDir}</string>
-    <key>FLAIR_MODELS_DIR</key><string>${modelsDir}</string>
-    <key>HARPER_SET_CONFIG</key><string>${escapeXml(setConfig)}</string>
-    <key>DEFAULTS_MODE</key><string>dev</string>
-    <key>HDB_ADMIN_USERNAME</key><string>${adminUser}</string>
-    <key>HDB_ADMIN_PASSWORD</key><string>${adminPass}</string>
-    <key>THREADS_COUNT</key><string>1</string>
-    <key>NODE_HOSTNAME</key><string>localhost</string>
-    <key>HTTP_PORT</key><string>${httpPort}</string>
-    <key>OPERATIONSAPI_NETWORK_PORT</key><string>${escapeXml(opsNetworkPortValue(opsBindHost, opsPort))}</string>
-    <key>LOCAL_STUDIO</key><string>false</string>
-  </dict>
-  <key>RunAtLoad</key><true/>
-  <key>KeepAlive</key><true/>
-  <key>StandardOutPath</key><string>${join(dataDir, "log", "launchd-stdout.log")}</string>
-  <key>StandardErrorPath</key><string>${join(dataDir, "log", "launchd-stderr.log")}</string>
-</dict>
-</plist>`;
+                const plist = buildLaunchdPlist({
+                    label,
+                    execPath: process.execPath,
+                    harperBinPath,
+                    workingDirectory: flairPackageDir(),
+                    dataDir,
+                    modelsDir,
+                    setConfig,
+                    adminUser,
+                    adminPass,
+                    httpPort,
+                    opsNetworkPort: opsNetworkPortValue(opsBindHost, opsPort),
+                });
                 writeFileSync(plistPath, plist);
                 console.log("Launchd service registered ✓");
             }
@@ -2638,7 +2997,12 @@ program
     // survives an `--ops-bind` choice past the next restart. It also runs on
     // the already-running path (where init skips the spawn entirely), which is
     // what makes doctor's `flair init && flair restart` remedy actually apply.
-    writeConfig(httpPort, opsPort, opsBindHost);
+    // flair#914: written ONLY when this init is about the default install, so a
+    // second instance can no longer overwrite the first's recorded port. This
+    // instance's own port needs no write here — Harper has just recorded it in
+    // <dataDir>/harper-config.yaml, which is what resolveHttpPort reads (see
+    // persistDefaultInstallCoordinates).
+    persistDefaultInstallCoordinates(dataDir, httpPort, opsPort, opsBindHost);
     if (agentId) {
         // Generate or reuse keypair
         mkdirSync(keysDir, { recursive: true });
@@ -2759,13 +3123,35 @@ program
         // skips wiring entirely; `--client <name>` targets one client; the
         // default (no flag) wires every detected client.
         const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
+        // `wired` is the load-bearing field (flair#906): it separates "a config
+        // file was actually written" from "we printed something and moved on".
+        // Both outcomes used to be pushed here indistinguishably as far as the
+        // user was concerned, so `--client all` reported success for a client it
+        // had not wired.
         const wiringResults = [];
+        // Human-readable labels + the clients `--client all` passed over because
+        // they aren't installed, so the closing summary can account for every
+        // client the user asked for rather than only the ones we tried.
+        const clientLabels = new Map();
+        const skippedUndetected = [];
         if (!noMcp && clientOpt !== "none") {
+            // A spec we cannot pin is a security property quietly downgraded, so
+            // say so BEFORE writing it and again in the summary below (flair#907).
+            // stderr: this must survive `flair init | tee`, and it is a warning,
+            // not part of the command's normal output.
+            const pinWarning = unpinnedSpecWarning();
+            if (pinWarning) {
+                console.error("");
+                for (const line of pinWarning.split("\n"))
+                    console.error(`   ⚠ ${line}`);
+            }
             // Determine which clients to wire.
             let clients = detectClients();
             if (selectedClients.length > 0) {
                 clients = clients.filter(c => selectedClients.includes(c.id));
             }
+            for (const c of clients)
+                clientLabels.set(c.id, c.label);
             const detected = clients.filter(c => c.detected);
             if (!clientOpt) {
                 if (detected.length === 0) {
@@ -2780,6 +3166,15 @@ program
                 : selectedClients.length > 0
                     ? selectedClients
                     : clients.filter(c => c.detected).map(c => c.id);
+            // `--client all` is a promise about every client, so the ones it
+            // passed over have to be accounted for too — silently omitting them
+            // is how "all" reports success for work it never did (flair#906).
+            if (clientOpt === "all") {
+                for (const c of clients) {
+                    if (!c.detected)
+                        skippedUndetected.push(c.label);
+                }
+            }
             for (const clientId of toWire) {
                 if (clientId === "claude-code") {
                     // Claude Code gets real auto-wiring into ~/.claude.json (zero-install
@@ -2797,32 +3192,45 @@ program
                         // provenance.claimed.client = "claude-code".
                         env: { ...mcpEnv, FLAIR_CLIENT: "claude-code" },
                     };
+                    // ~/.claude.json exists once Claude Code has been RUN, not once it
+                    // is installed — so gating the write on it skipped every user who
+                    // installed Claude Code and Flair in the same sitting (flair#906).
+                    // The file is Claude Code's own and creating it with a single
+                    // `mcpServers` key is exactly what `claude mcp add` does, so an
+                    // absent file is created rather than turned into a printed snippet
+                    // the user has to notice and act on.
                     try {
-                        if (existsSync(claudeJsonPath)) {
-                            const claudeJson = JSON.parse(readFileSync(claudeJsonPath, "utf-8"));
-                            const existing = claudeJson.mcpServers?.flair;
-                            if (existing && existing.env?.FLAIR_URL === httpUrl && existing.env?.FLAIR_AGENT_ID === agentId) {
-                                console.log(`   ✓ Claude Code already wired in ~/.claude.json`);
-                                wiringResults.push({ client: "claude-code", message: "already wired" });
-                            }
-                            else {
-                                claudeJson.mcpServers = claudeJson.mcpServers || {};
-                                claudeJson.mcpServers.flair = flairMcpConfig;
-                                writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
-                                console.log(`   ✓ Claude Code wired in ~/.claude.json (restart Claude Code to pick it up)`);
-                                wiringResults.push({ client: "claude-code", message: "wired ~/.claude.json" });
-                            }
+                        const claudeJsonExisted = existsSync(claudeJsonPath);
+                        const claudeJson = claudeJsonExisted
+                            ? JSON.parse(readFileSync(claudeJsonPath, "utf-8"))
+                            : {};
+                        const existing = claudeJson.mcpServers?.flair;
+                        if (existing && existing.env?.FLAIR_URL === httpUrl && existing.env?.FLAIR_AGENT_ID === agentId) {
+                            console.log(`   ✓ Claude Code already wired in ~/.claude.json`);
+                            wiringResults.push({ client: "claude-code", message: "already wired", wired: true });
                         }
                         else {
-                            console.log(`   MCP config (add to ~/.claude.json):`);
-                            console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
-                            wiringResults.push({ client: "claude-code", message: "snippet printed (no ~/.claude.json)" });
+                            claudeJson.mcpServers = claudeJson.mcpServers || {};
+                            claudeJson.mcpServers.flair = flairMcpConfig;
+                            writeFileSync(claudeJsonPath, JSON.stringify(claudeJson, null, 2));
+                            const how = claudeJsonExisted ? "wired in ~/.claude.json" : "wired in ~/.claude.json (created)";
+                            console.log(`   ✓ Claude Code ${how} (restart Claude Code to pick it up)`);
+                            wiringResults.push({
+                                client: "claude-code",
+                                message: claudeJsonExisted ? "wired ~/.claude.json" : "created and wired ~/.claude.json",
+                                wired: true,
+                            });
                         }
                     }
-                    catch {
+                    catch (err) {
+                        // Only a genuine read/parse/write failure lands here now (bad
+                        // permissions, malformed existing JSON) — never merely "the file
+                        // does not exist yet".
+                        const reason = err instanceof Error ? err.message : String(err);
+                        console.log(`   ${render.icons.warn} Claude Code: could not write ~/.claude.json (${reason})`);
                         console.log(`   MCP config (add manually to ~/.claude.json):`);
                         console.log(`     { "mcpServers": { "flair": ${JSON.stringify(flairMcpConfig)} } }`);
-                        wiringResults.push({ client: "claude-code", message: "snippet printed" });
+                        wiringResults.push({ client: "claude-code", message: `snippet printed (${reason})`, wired: false });
                     }
                     // ── CLAUDE.md bootstrap line (flair#597) ──────────────────────────
                     // The MCP block alone isn't a working setup — Claude Code also needs
@@ -2866,7 +3274,7 @@ program
                             break;
                         default: result = { ok: false, message: `Unknown client: ${clientId}` };
                     }
-                    wiringResults.push({ client: clientId, message: result.message });
+                    wiringResults.push({ client: clientId, message: result.message, wired: result.ok });
                     console.log(`   ${result.ok ? "✓" : "•"} ${result.message}`);
                 }
             }
@@ -2944,6 +3352,34 @@ program
                 console.log("   Use --skip-smoke to bypass.");
             }
         }
+        // ── MCP wiring summary (flair#906) ───────────────────────────────────
+        // LAST thing init prints, deliberately. Every fact below was already
+        // available mid-run, but a client that was not wired appeared only as a
+        // snippet in the middle of a wall of output, after a success line — so
+        // the user's next action was to open their client and find nothing
+        // there, with no reason to suspect init. A client the user asked for and
+        // did NOT get must still be on screen when the command finishes.
+        if (!noMcp && clientOpt !== "none") {
+            // The pin warning repeats here for the same reason the summary exists:
+            // a warning only in scrollback is a warning the user acts on never.
+            const summaryLines = renderWiringSummary(wiringResults, {
+                labels: clientLabels,
+                skippedUndetected,
+                rewireHint: `flair init --agent ${agentId} --client all`,
+                unpinned: unpinnedSpecWarning() !== null,
+            });
+            for (const line of summaryLines) {
+                const icon = line.level === "ok" ? render.icons.ok :
+                    line.level === "error" ? render.icons.error :
+                        line.level === "warn" ? render.icons.warn :
+                            line.level === "muted" ? render.icons.bullet :
+                                null;
+                if (line.level === "heading")
+                    console.log(`\n   ${line.text}`);
+                else
+                    console.log(`   ${icon} ${line.text}`);
+            }
+        }
     }
     else {
         const httpUrl = `http://127.0.0.1:${httpPort}`;
@@ -3182,7 +3618,8 @@ agent
     }
     if (out.defaultTrustTier)
         console.log(render.kv("trust tier", String(out.defaultTrustTier)));
-    if (out.admin)
+    // flair#941 — read the authority, not the mirror. See `principal show`.
+    if (agentRecordIsAdmin(out))
         console.log(render.kv("admin", render.wrap(render.c.magenta, "yes")));
     if (out.runtime)
         console.log(render.kv("runtime", String(out.runtime)));
@@ -4334,6 +4771,23 @@ mcp
 // ─── flair principal ─────────────────────────────────────────────────────────
 // 1.0 identity management. The Principal model extends Agent — this is the
 // preferred CLI surface for managing identities going forward.
+/**
+ * The exact `role` value that denotes a flair administrator, and the predicate
+ * that reads it.
+ *
+ * DUPLICATED FROM resources/agent-admin.ts on purpose — the same deliberate
+ * copy as the federation crypto helpers above: src/cli.ts must not import from
+ * resources/, because those imports don't survive npm packaging. The two must
+ * stay in sync.
+ *
+ * flair#941: `role` is the authority and `admin` is its mirror. The CLI used to
+ * both write and display ONLY the mirror, so `principal add --admin` created a
+ * principal the gate refuses and `principal show` printed "admin: yes" for it.
+ */
+const ADMIN_ROLE = "admin";
+function agentRecordIsAdmin(record) {
+    return record?.role === ADMIN_ROLE;
+}
 const principal = program.command("principal").description("Manage principals (humans and agents)");
 principal
     .command("add <id>")
@@ -4403,6 +4857,11 @@ principal
         status: "active",
         publicKey: pubKeyB64url,
         defaultTrustTier: trustTier,
+        // flair#941 — write BOTH. This is an ops-API upsert, so the Agent
+        // resource's reconciliation never runs; writing only the `admin` mirror
+        // is what made `--admin` a no-op at the gate for every principal this
+        // command has ever created.
+        role: isAdmin ? ADMIN_ROLE : "agent",
         admin: isAdmin,
         runtime: runtime ?? null,
         createdAt: new Date().toISOString(),
@@ -4455,7 +4914,10 @@ principal
             table: "Agent",
             operator: "and",
             conditions,
-            get_attributes: ["id", "name", "kind", "status", "defaultTrustTier", "admin", "runtime", "createdAt"],
+            // `role` is the authority behind admin status (flair#941); the
+            // projection used to omit it, so this listing could only ever report
+            // the mirror.
+            get_attributes: ["id", "name", "kind", "status", "defaultTrustTier", "role", "admin", "runtime", "createdAt"],
         }),
     });
     if (!res.ok) {
@@ -4489,7 +4951,14 @@ principal
         {
             label: "admin",
             key: "admin",
-            format: (v) => (v ? render.wrap(render.c.red, "yes") : render.wrap(render.c.dim, "no")),
+            // Report the status the gate will apply, and flag a record whose two
+            // fields disagree rather than picking a side silently (flair#941).
+            format: (_v, row) => {
+                const isAdmin = agentRecordIsAdmin(row);
+                const mismatch = isAdmin !== (row.admin === true);
+                const base = isAdmin ? render.wrap(render.c.red, "yes") : render.wrap(render.c.dim, "no");
+                return mismatch ? `${base} ${render.wrap(render.c.yellow, "(!)")}` : base;
+            },
         },
         {
             label: "status",
@@ -4531,8 +5000,13 @@ principal
     }
     if (result.defaultTrustTier)
         console.log(render.kv("trust tier", String(result.defaultTrustTier)));
-    if (result.admin)
+    // flair#941 — read the authority, not the mirror, and say so when the two
+    // disagree (only reachable via a raw table write).
+    if (agentRecordIsAdmin(result))
         console.log(render.kv("admin", render.wrap(render.c.red, "yes")));
+    if (agentRecordIsAdmin(result) !== (result.admin === true)) {
+        console.log(render.kv("admin", render.wrap(render.c.yellow, `record is inconsistent (role=${result.role ?? "unset"}, admin=${result.admin ?? "unset"}) — re-issue the grant to repair`)));
+    }
     if (result.runtime)
         console.log(render.kv("runtime", String(result.runtime)));
     if (result.email)
@@ -4924,13 +5398,56 @@ function signRequestBody(body, secretKey) {
 const signBodyFresh = signRequestBody;
 // ─── flair federation ────────────────────────────────────────────────────────
 const federation = program.command("federation").description("Manage federation (hub-and-spoke sync)");
+/**
+ * The most recent CONTACT with any peer (max of peer.lastSyncAt), or null.
+ *
+ * Contact, not merge: a sync that reaches the peer and legitimately has
+ * nothing to send still proves the driver ran. This is half of what lets
+ * `federation status` tell "nothing is driving sync" apart from "sync is
+ * running, the peer is unreachable" (flair#922) — the other half is whether
+ * the service manager has a driver loaded.
+ *
+ * Returns null on ANY failure. A driver verdict is a diagnostic aid; it must
+ * never be the reason `federation status` fails.
+ */
+async function latestPeerContact(opts) {
+    try {
+        const target = resolveTarget(opts);
+        const baseUrl = target ? target.replace(/\/$/, "") : undefined;
+        const { peers } = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
+        let best = null;
+        for (const p of peers ?? []) {
+            if (!p?.lastSyncAt)
+                continue;
+            const t = Date.parse(p.lastSyncAt);
+            if (Number.isFinite(t) && (best === null || t > best))
+                best = t;
+        }
+        return best === null ? null : new Date(best).toISOString();
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * True when the CLI is pointed at the instance running on THIS machine.
+ *
+ * The scheduler check is inherently local — launchctl/systemctl only know
+ * about jobs on the host the CLI is running on. Reporting "no driver" while
+ * `--target` points at someone else's hub would be a confident claim about a
+ * machine we cannot see, so the driver block is suppressed for remote targets.
+ */
+function driverCheckAppliesTo(opts) {
+    const target = resolveTarget(opts);
+    return !target || isLocalBase(target.replace(/\/$/, ""));
+}
 federation
     .command("status")
     .description("Show federation status and peer connections")
     .option("--port <port>", "Harper HTTP port")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
-    .option("--json", "Emit JSON {instance, peers} (also: pipe + FLAIR_OUTPUT=json)")
+    .option("--json", "Emit JSON {instance, peers, driver} (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
     const target = resolveTarget(opts);
     const baseUrl = target ? target.replace(/\/$/, "") : undefined;
@@ -4938,8 +5455,41 @@ federation
     try {
         const instance = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
         const { peers } = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
+        // Driver state (flair#922). Computed from the LOCAL service manager, so
+        // it is only meaningful when the CLI is pointed at the local instance.
+        let driver = null;
+        let assessment = null;
+        if (driverCheckAppliesTo(opts)) {
+            try {
+                const { schedulerStatus, assessDriver } = await import("./federation/scheduler.js");
+                driver = schedulerStatus();
+                let lastSyncAt = null;
+                for (const p of peers ?? []) {
+                    if (!p?.lastSyncAt)
+                        continue;
+                    const t = Date.parse(p.lastSyncAt);
+                    if (Number.isFinite(t) && (lastSyncAt === null || t > Date.parse(lastSyncAt))) {
+                        lastSyncAt = new Date(t).toISOString();
+                    }
+                }
+                assessment = assessDriver({
+                    installed: driver.installed,
+                    active: driver.active,
+                    intervalSeconds: driver.intervalSeconds,
+                    lastSyncAt,
+                    now: Date.now(),
+                });
+            }
+            catch {
+                // An unsupported platform (neither darwin nor linux) or an
+                // unreadable unit must not take down `federation status` — the peer
+                // table is still the primary output.
+                driver = null;
+                assessment = null;
+            }
+        }
         if (mode === "json") {
-            console.log(render.asJSON({ instance, peers }));
+            console.log(render.asJSON({ instance, peers, driver, driverAssessment: assessment }));
             return;
         }
         const statusColor = instance.status === "active" ? render.c.green : render.c.yellow;
@@ -4951,6 +5501,26 @@ federation
             console.log(`\n${render.icons.info} ${render.wrap(render.c.dim, "No peers configured. Use 'flair federation pair' to connect to a hub.")}`);
             return;
         }
+        // Print the driver line BEFORE the per-peer table: "is anything running
+        // sync at all" is the question that decides how to read everything
+        // below it.
+        if (assessment) {
+            const icon = assessment.verdict === "driving" || assessment.verdict === "external-driver"
+                ? render.icons.ok
+                : assessment.verdict === "unknown"
+                    ? render.icons.info
+                    : render.icons.warn;
+            const color = assessment.verdict === "driving" || assessment.verdict === "external-driver"
+                ? render.c.green
+                : assessment.verdict === "unknown"
+                    ? render.c.dim
+                    : render.c.yellow;
+            console.log();
+            console.log(`${icon} ${render.wrap(color, assessment.headline)}`);
+            console.log(`  ${render.wrap(render.c.dim, assessment.detail)}`);
+            if (assessment.remedy)
+                console.log(`  ${render.wrap(render.c.cyan, assessment.remedy)}`);
+        }
         const now = Date.now();
         const formatPeerAge = (iso, refNow, staleAfterMs) => {
             if (!iso)
@@ -5012,7 +5582,16 @@ federation
         });
         if (haveStale) {
             console.log();
-            console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, "One or more peers haven't merged a record in >24h.")} ${render.wrap(render.c.dim, "Check skippedReasons in SyncLog or run 'flair federation sync'.")}`);
+            // The staleness warning used to fire identically whether sync was
+            // running and the peer was unreachable, or nothing had run sync since
+            // the day the spoke was paired (flair#922). Those need opposite
+            // actions, so the remedy is now chosen by the driver verdict instead
+            // of always pointing at SyncLog.
+            const noDriver = assessment?.verdict === "no-driver" || assessment?.verdict === "driver-inactive";
+            const remedy = noDriver
+                ? "Nothing is driving sync — see the driver line above. Run 'flair federation sync enable'."
+                : "Check skippedReasons in SyncLog or run 'flair federation sync'.";
+            console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, "One or more peers haven't merged a record in >24h.")} ${render.wrap(render.c.dim, remedy)}`);
         }
         const haveContactButNoMerge = peers.some((p) => {
             if (!p.lastSyncAt || !Number.isFinite(Date.parse(p.lastSyncAt)))
@@ -5655,21 +6234,172 @@ export async function runFederationSyncOnce(opts) {
         return { pushed: totalMerged, skipped: totalSkipped, error: err instanceof Error ? err : new Error(String(err)) };
     }
 }
-federation
+const federationSync = federation
     .command("sync")
-    .description("Push local changes to the hub")
+    .description("Push local changes to the hub (one-shot). Subcommands manage the scheduled driver.")
     .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password")
+    .option("--admin-pass-file <path>", "Read the admin password from a file (e.g. ~/.flair/admin-pass). Preferred for launchd/cron — keeps the secret out of ps and shell history.")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .option("--ops-target <url>", "Explicit ops API URL (env: FLAIR_OPS_TARGET; bypasses port derivation)")
     .action(async (opts) => {
+    // --admin-pass-file resolves into the same `adminPass` slot the inline
+    // flag uses, so the scheduler never has to embed a secret in a unit file.
+    // readAdminPassFileSecure() refuses a file that is not owner-only.
+    if (!opts.adminPass && opts.adminPassFile) {
+        try {
+            opts.adminPass = readAdminPassFileSecure(opts.adminPassFile);
+        }
+        catch (err) {
+            console.error(`Error reading --admin-pass-file ${opts.adminPassFile}: ${err.message}`);
+            process.exit(1);
+        }
+    }
     const r = await runFederationSyncOnce(opts);
     if (r.error) {
         console.error(`Error: ${r.error.message}`);
         process.exit(1);
     }
 });
+// ─── flair federation sync enable | disable | status ────────────────────────
+// The supervised driver (flair#922). Federation had no automatic driver at
+// all: `sync` is one-shot and `watch` is a foreground loop that dies with its
+// terminal, so every operator paired a spoke, saw one successful sync, and
+// then silently stopped syncing.
+//
+// Shape deliberately mirrors `flair rem nightly enable|disable|status` —
+// same verbs, same platform coverage (launchd on macOS, systemd --user timer
+// on Linux), same "never claim success before activation succeeded" rule.
+// Strategy is a PERIODIC ONE-SHOT rather than a supervised long-lived
+// watcher; the reasoning is in src/federation/scheduler.ts's header.
+federationSync
+    .command("enable")
+    .description("Install the sync driver (launchd on macOS, systemd timer on Linux)")
+    .option("--interval <seconds>", `Seconds between syncs (default ${FEDERATION_SYNC_DEFAULT_INTERVAL})`, String(FEDERATION_SYNC_DEFAULT_INTERVAL))
+    // Deliberately NOT `--no-admin-pass-file`: commander treats a `--no-x` flag
+    // as the negation of `--x`, and declaring both on one command makes the
+    // POSITIVE option silently parse to undefined — `--admin-pass-file /path`
+    // would be accepted and dropped, producing a driver that fails auth every
+    // cycle with no error anywhere. Verified against commander 14.
+    .option("--no-credentials", "Do not wire any credential file into the unit")
+    // `--admin-pass-file` and `--target` are NOT redeclared here (flair#926).
+    // The parent `flair federation sync` owns both, and commander matches an
+    // option against the parent's list before dispatching — so a duplicate
+    // declaration here never receives a value, it only makes the option LOOK
+    // local. Both flags still work on this command; they arrive via
+    // optsWithGlobals() below and are listed under "Global Options" in --help.
+    .addHelpText("after", "\nCredentials:\n"
+    + "  --admin-pass-file defaults to ~/.flair/admin-pass when that file exists.\n"
+    + "  The PATH is stored in the unit — never the password.\n")
+    .action(async (_opts, cmd) => {
+    // optsWithGlobals(), NOT the action's first argument: `--admin-pass-file`
+    // and `--target` are declared on the PARENT (`flair federation sync`), and
+    // commander binds their values there. The subcommand's own opts() has no
+    // entry for them at all. Reading only the local opts silently dropped
+    // `--admin-pass-file <path>` here (flair#923), which installed a driver
+    // that failed auth every cycle with no error anywhere. Verified against
+    // commander 14; test/unit/cli-option-collisions.test.ts pins the rule.
+    const opts = cmd.optsWithGlobals();
+    const intervalSeconds = Number(opts.interval);
+    if (!Number.isFinite(intervalSeconds)) {
+        console.error(`Error: --interval must be a number of seconds (got: ${opts.interval})`);
+        process.exit(1);
+    }
+    // Default to the canonical admin-pass file when it is actually there.
+    // Silently wiring a path that does not exist would produce a driver that
+    // runs and fails auth every interval — the failure mode this whole issue
+    // is about, in a new costume.
+    let adminPassFile;
+    if (opts.credentials === false) {
+        adminPassFile = undefined;
+    }
+    else if (typeof opts.adminPassFile === "string" && opts.adminPassFile) {
+        adminPassFile = opts.adminPassFile;
+    }
+    else {
+        const fallback = defaultAdminPassPath();
+        adminPassFile = existsSync(fallback) ? fallback : undefined;
+    }
+    const { enableScheduler, formatEnableReport } = await import("./federation/scheduler.js");
+    try {
+        const r = enableScheduler({ intervalSeconds, adminPassFile, target: opts.target });
+        const { lines, ok } = formatEnableReport(r, { adminPassFile, target: opts.target });
+        for (const line of lines)
+            console.log(line);
+        if (!ok)
+            process.exit(1);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+federationSync
+    .command("disable")
+    .description("Remove the sync driver (peers and sync history are preserved)")
+    .option("--remove-shim", "Also delete the ~/.flair/bin/flair-federation-sync shim")
+    .action(async (opts) => {
+    const { disableScheduler } = await import("./federation/scheduler.js");
+    try {
+        const r = disableScheduler({ removeShim: !!opts.removeShim });
+        if (r.removed.length === 0) {
+            console.log(`(Federation sync driver was not installed on ${r.platform})`);
+            return;
+        }
+        console.log(`✅ Federation sync driver disabled (${r.platform})`);
+        console.log(`   Removed:`);
+        for (const p of r.removed)
+            console.log(`     ${p}`);
+        if (r.unloadResult && r.unloadResult.code !== 0) {
+            console.log(`   Unload:      ${r.unloadCommand.join(" ")} → code ${r.unloadResult.code}`);
+            if (r.unloadResult.stderr)
+                console.log(`     stderr: ${r.unloadResult.stderr.trim()}`);
+        }
+        console.log(`\nPeers, keys and sync history are untouched. Nothing will sync until you`);
+        console.log(`re-enable the driver or run \`flair federation sync\` by hand.`);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
+federationSync
+    .command("status")
+    .description("Show whether a sync driver is installed and genuinely active")
+    // `--port` and `--target` are NOT redeclared here (flair#926) — the parent
+    // `flair federation sync` owns them and commander binds them there. They
+    // still work on this command, via optsWithGlobals() below.
+    .option("--json", "Emit JSON")
+    .action(async (_opts, cmd) => {
+    // See the comment on `enable` above: `--target`/`--port` live on the
+    // parent, so commander binds them there and only optsWithGlobals() sees
+    // them.
+    const opts = cmd.optsWithGlobals();
+    const { schedulerStatus, formatStatusReport, assessDriver } = await import("./federation/scheduler.js");
+    try {
+        const s = schedulerStatus();
+        const lastSyncAt = await latestPeerContact(opts);
+        const a = assessDriver({
+            installed: s.installed,
+            active: s.active,
+            intervalSeconds: s.intervalSeconds,
+            lastSyncAt,
+            now: Date.now(),
+        });
+        if (render.resolveOutputMode(opts) === "json") {
+            console.log(render.asJSON({ driver: s, assessment: a, lastSyncAt }));
+            return;
+        }
+        const { lines } = formatStatusReport(s, a);
+        for (const line of lines)
+            console.log(line);
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
+});
 export async function runFederationWatch(opts) {
     const intervalMs = Math.max(5, parseFloat(opts.interval) || 30) * 1000;
     let stopped = false;
@@ -7786,6 +8516,7 @@ export function resolveFabricCredentials(opts) {
 async function runFabricUpgrade(opts) {
     const green = (s) => `\x1b[32m${s}\x1b[0m`;
     const red = (s) => `\x1b[31m${s}\x1b[0m`;
+    const yellow = (s) => `\x1b[33m${s}\x1b[0m`;
     const dim = (s) => `\x1b[2m${s}\x1b[0m`;
     let fabricUser;
     let fabricPassword;
@@ -7814,13 +8545,21 @@ async function runFabricUpgrade(opts) {
     const upgradeOpts = {
         target: opts.target,
         project: opts.project,
-        version: opts.version,
+        // flair#926: `--flair-version`, never `opts.version` — that attribute name
+        // belongs to the program's `-v, --version` and never reaches this action.
+        version: opts.flairVersion,
         harperVersion: opts.harperVersion,
         fabricUser,
         fabricPassword,
         check,
         restart: opts.restart !== false,
         replicated: opts.replicated !== false,
+        // flair#878 — previously unreachable from this command; see
+        // FabricUpgradeOptions.
+        deployRetries: Number(opts.deployRetries ?? 0),
+        ignoreReplicationErrors: opts.ignoreReplicationErrors ?? false,
+        convergenceCheck: opts.convergenceCheck !== false,
+        convergenceTimeoutMs: opts.convergenceTimeout != null ? Number(opts.convergenceTimeout) : undefined,
     };
     console.log(`${green("→")} Upgrading Fabric Flair at ${upgradeOpts.target}`);
     if (check)
@@ -7847,6 +8586,20 @@ async function runFabricUpgrade(opts) {
             console.log(`\n${green("✓")} already up to date.`);
             return;
         }
+        if (result.convergedAfterReplicationError) {
+            // flair#878: this deploy is a SUCCESS that harper's own exit code called
+            // a failure. Say both halves out loud — an operator who saw the
+            // replication error scroll past needs to know it resolved, and an
+            // operator reading only this line needs to know it happened at all.
+            console.log(`\n${yellow("⚠")} harper reported a peer-replication failure during this upgrade, but the component ` +
+                `tree on every named peer node matched the origin when checked afterwards — replication converged ` +
+                `on its own. Harper replicates components asynchronously, so a replication error at deploy time is ` +
+                `a snapshot, not a verdict.`);
+        }
+        if (result.replicationWarning) {
+            console.log(`\n${yellow("⚠")} Deployed to the ORIGIN NODE ONLY — peer replication did not converge and ` +
+                `--ignore-replication-errors was set. The peer will need to catch up via federation sync or a later deploy.`);
+        }
         console.log(`\n${green("✓")} Fabric upgrade complete.`);
         // ── Post-upgrade fleet sweep (flair#636) ────────────────────────────────
         // "deploy complete" from harper's own CLI means "origin took it" — this
@@ -7878,6 +8631,15 @@ async function runFabricUpgrade(opts) {
         if (hint.includes("401") || hint.includes("unauthoriz")) {
             console.error(dim("  hint: check Fabric Studio → Cluster Settings → Admin for the admin password"));
         }
+        // flair#878: harper's own replication error tells the operator to "pass
+        // ignore_replication_errors: true" — until now there was no way to do that
+        // through `flair upgrade`. Name the flag that actually does it, and the
+        // one that turns off the retry that can make things worse.
+        if (hint.includes("peer replication") || hint.includes("ignore_replication_errors")) {
+            console.error(dim("  hint: --ignore-replication-errors accepts an origin-only upgrade (the peer catches up via federation sync or a later deploy)"));
+            console.error(dim("  hint: --convergence-timeout <ms> waits longer for asynchronous replication before giving up (default 180000)"));
+            console.error(dim("  hint: --deploy-retries defaults to 0 — a retry can turn a transient replication warning into a hard install failure (flair#878)"));
+        }
         process.exit(1);
     }
 }
@@ -8069,6 +8831,22 @@ export const UPGRADE_SNAPSHOT_NUDGE_LINES = [
 const snapshotCmd = program
     .command("snapshot")
     .description("Physical ~/.flair/data snapshots (byte-exact tar.gz, local-only — see `flair backup`/`flair restore` for the logical JSON export/import)");
+/**
+ * `resolveHttpPort` for a command that takes `--data-dir`, reported as a
+ * message rather than a stack trace (flair#914).
+ *
+ * The throw is a refusal to guess which instance a directory is, and a refusal
+ * has to tell the operator what to pass instead — a stack trace does not.
+ */
+function resolveHttpPortForDataDir(opts) {
+    try {
+        return resolveHttpPort(opts);
+    }
+    catch (err) {
+        console.error(`❌ ${err?.message ?? err}`);
+        process.exit(1);
+    }
+}
 snapshotCmd
     .command("create")
     .description("Take a physical snapshot of the Flair data directory now (briefly stops Flair for a consistent copy — use `flair backup` for a no-downtime logical export)")
@@ -8076,11 +8854,16 @@ snapshotCmd
     .option("--port <port>", "Harper HTTP port (used to quiesce Flair around the snapshot)")
     .action(async (opts) => {
     const dataDir = opts.dataDir ? resolve(opts.dataDir) : defaultDataDir();
-    const port = resolveHttpPort(opts);
+    // Existence first, THEN the port. A directory that isn't there has a more
+    // specific diagnosis than "it doesn't say which port it serves", and the
+    // caller should get the one that names the actual problem (flair#914).
     if (!existsSync(dataDir)) {
         console.error(`Error: data directory does not exist: ${dataDir}`);
         process.exit(1);
     }
+    // flair#914: the port of the instance NAMED here, never the per-user
+    // file's — refuses rather than guessing when that directory has no record.
+    const port = resolveHttpPortForDataDir(opts);
     console.log(`Snapshotting ${dataDir}...`);
     console.log("(Flair will be briefly stopped for a point-in-time-consistent copy, then restarted.)");
     // Same consistency requirement as the upgrade path's snapshot step: a
@@ -8091,7 +8874,9 @@ snapshotCmd
     // point-in-time-consistent guarantee, not a weaker one.
     let stoppedForSnapshot = false;
     try {
-        await stopFlairProcess(port);
+        // `dataDir`, not the default (flair#902) — quiesce the instance this
+        // command was pointed at, never whichever one owns ~/.flair/data.
+        await stopFlairProcess(port, dataDir);
         stoppedForSnapshot = true;
         const snapshot = await createDataSnapshot(dataDir);
         const removed = pruneOldSnapshots();
@@ -8104,14 +8889,14 @@ snapshotCmd
         console.error(`❌ snapshot failed: ${err.message}`);
         if (stoppedForSnapshot) {
             try {
-                await startFlairProcess(port);
+                await startFlairProcess(port, dataDir);
             }
             catch { /* best effort — surface the original snapshot error, not this */ }
         }
         process.exit(1);
     }
     try {
-        await startFlairProcess(port);
+        await startFlairProcess(port, dataDir);
     }
     catch (err) {
         console.error(`❌ the snapshot succeeded but Flair failed to restart: ${err.message}`);
@@ -8169,7 +8954,9 @@ snapshotCmd
         process.exit(1);
     }
     const dataDir = opts.dataDir ? resolve(opts.dataDir) : defaultDataDir();
-    const port = resolveHttpPort(opts);
+    // flair#914: the port of the instance NAMED here, never the per-user
+    // file's — refuses rather than guessing when that directory has no record.
+    const port = resolveHttpPortForDataDir(opts);
     console.log("This will STOP Flair, DELETE the current data directory, and replace it with:");
     console.log(`  snapshot: ${snapshotPath}`);
     console.log(`  target:   ${dataDir}`);
@@ -8187,32 +8974,62 @@ snapshotCmd
         }
     }
     try {
-        await stopFlairProcess(port);
+        // `dataDir`, not the default (flair#902) — the whole point of this
+        // command's --data-dir is that it may name a scratch directory, and
+        // stopping the default instance instead is how a cautious inspect-a-
+        // snapshot-somewhere-else took production down.
+        await stopFlairProcess(port, dataDir);
     }
     catch (err) {
         console.error(`❌ failed to stop Flair: ${err.message}`);
         process.exit(1);
     }
+    // Validate the archive BEFORE the destructive rmSync below. Restore
+    // accepts snapshots this CLI did not create — copied off another machine,
+    // downloaded, handed over during a migration — so the archive is untrusted
+    // input, and a hostile one must not cost the operator their data directory
+    // on its way to being refused.
+    try {
+        await validateSnapshotArchive({ file: snapshotPath, targetDir: dataDir });
+    }
+    catch (err) {
+        console.error(`❌ ${err.message}`);
+        console.error(`   ${dataDir} was NOT modified.`);
+        process.exit(1);
+    }
     try {
         rmSync(dataDir, { recursive: true, force: true });
         mkdirSync(dataDir, { recursive: true, mode: 0o700 });
-        // preservePaths mirrors createDataSnapshot's own preservePaths: true —
-        // restores absolute symlink targets verbatim instead of node-tar's
-        // default of stripping the leading "/" on extraction. No `follow`
-        // option, so symlinks extract as symlinks (never their targets'
-        // contents), and file modes extract exactly as stored — the archive
-        // itself already only contains what createDataSnapshot's filter chose
-        // to include (in-bounds symlinks, regular files/dirs only), so restore
-        // needs no re-filtering of its own.
-        await tarExtract({ file: snapshotPath, cwd: dataDir, preservePaths: true });
+        // extractSnapshotSafely keeps preservePaths: true — load-bearing for
+        // symlink TARGET fidelity, mirroring createDataSnapshot — while doing
+        // the entry-path containment that flag disables. See
+        // src/lib/safe-snapshot-extract.ts for why the flag cannot simply be
+        // dropped. No `follow` option, so symlinks extract as symlinks (never
+        // their targets' contents), and file modes extract exactly as stored.
+        await extractSnapshotSafely({ file: snapshotPath, targetDir: dataDir });
     }
     catch (err) {
         console.error(`❌ restore failed: ${err.message}`);
         console.error(`   ${dataDir} may be partially restored or empty — do not start Flair until this is resolved.`);
         process.exit(1);
     }
+    // flair#914: a snapshot is a byte-exact copy of a data directory, so it
+    // carries the SOURCE instance's harper-config.yaml, and the extract just
+    // wrote it over this instance's. Between here and the boot below, that file
+    // names the SOURCE's port — but nothing re-resolves in that window: `port`
+    // was resolved before the extract and is handed to startFlairProcess
+    // explicitly, and Harper rewrites http.port / operationsApi.network.port
+    // from that spawn's environment as it boots. So the directory is
+    // self-describing again the moment it is serving, without flair writing into
+    // Harper's config to make it so.
+    //
+    // The port is a property of the instance, not of the data it serves. That
+    // is also what keeps a snapshot from somewhere else out of the business of
+    // naming ports on this host: restoring one to look at it cannot hand the
+    // restored directory a port it did not have — the boot immediately below is
+    // what settles the question, on this host's terms.
     try {
-        await startFlairProcess(port);
+        await startFlairProcess(port, dataDir);
     }
     catch (err) {
         console.error(`❌ restore succeeded but Flair failed to restart: ${err.message}`);
@@ -8240,12 +9057,27 @@ program
     .option("--fabric-user <user>", "Fabric admin username — for --target (env: FABRIC_USER preferred; inline leaks to shell history)")
     .option("--fabric-password <pass>", "Fabric admin password — for --target (prefer FABRIC_PASSWORD env or --fabric-password-file; inline leaks to shell history)")
     .option("--fabric-password-file <path>", "Read the Fabric admin password from a file (chmod 600) — for --target")
-    .option("--version <semver>", "Flair version to deploy with --target (default: latest published @tpsdev-ai/flair)")
+    // NOT `--version` (flair#926). The program declares `-v, --version`, and
+    // commander matches an option against the PARENT's list before dispatching to
+    // the subcommand — so `flair upgrade --target X --version 1.2.3` printed the
+    // CLI's own version and exited 0, never running the Fabric upgrade at all.
+    // A colliding name is normally recoverable via optsWithGlobals(); this one is
+    // not, because commander's version listener exits the process. The name had
+    // to change. `--harper-version` below is the symmetry this follows.
+    .option("--flair-version <semver>", "Flair version to deploy with --target (default: latest published @tpsdev-ai/flair)")
     .option("--harper-version <semver>", "Pin harper to this version for --target (default: registry latest, floored at the flair#513 fix)")
     .option("--project <name>", "Fabric component name for --target", "flair")
     .option("--no-replicated", "Disable cluster-wide replication for --target (default: replicated=true)")
     .option("--yes", "Skip the confirmation prompt for --target")
     .option("--no-fleet-verify", "Skip the automatic post-upgrade fleet convergence sweep for --target (default: sweep runs — see flair#636)")
+    // ── flair#878 ─────────────────────────────────────────────────────────────
+    // These existed on `flair deploy` but stopped at the upgrade boundary, so
+    // harper's own remedy ("pass ignore_replication_errors: true") was not
+    // actually reachable through `flair upgrade --target`.
+    .option("--deploy-retries <n>", "Retry the full harper deploy this many times for --target, ONLY when peer replication is positively observed not to converge (default: 0 — a retry can escalate a transient replication warning into a hard install failure; see flair#878)", "0")
+    .option("--ignore-replication-errors", "For --target: if peer replication still hasn't converged, accept an origin-only deploy instead of failing (the peer catches up via federation sync or a later deploy)")
+    .option("--no-convergence-check", "For --target: skip the post-replication-error convergence poll and fail on harper's error verbatim (default: poll — Harper replicates asynchronously, so its error is a snapshot, not a verdict; flair#878)")
+    .option("--convergence-timeout <ms>", "For --target: how long to wait for peer replication to converge before reporting a replication failure (default: 180000)")
     .action(async (opts) => {
     // ── Fabric-upgrade branch ───────────────────────────────────────────────
     if (opts.target) {
@@ -8381,6 +9213,13 @@ program
     // `opts` — safe to call this early.
     const { restart: shouldRestart, verify: shouldVerify, deprecatedRestartFlagUsed } = resolveUpgradeRestartVerify(opts);
     const upgradePort = resolveHttpPort({});
+    // The instance this upgrade is about, named once next to its port
+    // (flair#902). `flair upgrade` has no --data-dir, so this IS the default
+    // install — but stop/start/restart now take the directory explicitly, so
+    // the choice is made here in the open rather than assumed inside them.
+    // A default that happens to be right is the same defect waiting for the
+    // next caller.
+    const upgradeDataDir = defaultDataDir();
     // Hoisted so the pre-flight check (below) and the post-restart/rollback
     // verification steps (further down) all target the same URL — upgrade
     // never restarts Flair onto a different port.
@@ -8463,8 +9302,7 @@ program
     // the exact same mechanism as a standalone command for anyone who wants
     // one without wrapping it around an upgrade.
     const flairIsUpgrading = npmUpgrades.some((u) => u.pkg === "@tpsdev-ai/flair");
-    const snapshotDataDir = defaultDataDir();
-    const snapshotDecision = decideUpgradeSnapshotAction(flairIsUpgrading, !!opts.snapshot, existsSync(snapshotDataDir));
+    const snapshotDecision = decideUpgradeSnapshotAction(flairIsUpgrading, !!opts.snapshot, existsSync(upgradeDataDir));
     let snapshotPath = null;
     if (snapshotDecision === "nudge") {
         // Non-blocking nudge only — never prompt/block here, this must stay
@@ -8477,7 +9315,7 @@ program
             console.log(render.wrap(render.c.dim, line));
     }
     else if (snapshotDecision === "no-data") {
-        console.log(`\n(no data directory at ${snapshotDataDir} yet — nothing to snapshot)`);
+        console.log(`\n(no data directory at ${upgradeDataDir} yet — nothing to snapshot)`);
     }
     else if (snapshotDecision === "snapshot") {
         console.log("\nSnapshotting data before upgrade...");
@@ -8496,9 +9334,9 @@ program
         // the server being up).
         let stoppedForSnapshot = false;
         try {
-            await stopFlairProcess(upgradePort);
+            await stopFlairProcess(upgradePort, upgradeDataDir);
             stoppedForSnapshot = true;
-            const snapshot = await createDataSnapshot(snapshotDataDir);
+            const snapshot = await createDataSnapshot(upgradeDataDir);
             snapshotPath = snapshot.path;
             const removed = pruneOldSnapshots();
             console.log(`✅ Snapshot: ${snapshotPath} (${humanBytes(snapshot.bytes)})`);
@@ -8512,14 +9350,14 @@ program
             console.error("   Aborting upgrade — no packages were changed. Omit --snapshot to proceed without one (not recommended).");
             if (stoppedForSnapshot) {
                 try {
-                    await startFlairProcess(upgradePort);
+                    await startFlairProcess(upgradePort, upgradeDataDir);
                 }
                 catch { /* best effort — surface the original snapshot error, not this */ }
             }
             process.exit(1);
         }
         try {
-            await startFlairProcess(upgradePort);
+            await startFlairProcess(upgradePort, upgradeDataDir);
         }
         catch (err) {
             console.error(`❌ failed to restart Flair after the pre-upgrade snapshot: ${err.message}`);
@@ -8595,15 +9433,118 @@ program
     console.log("\nRestarting Flair...");
     const port = upgradePort;
     // baseUrl was hoisted above (pre-flight, fix #1) — same URL, no redeclaration.
+    /**
+     * Roll @tpsdev-ai/flair back to `toVersion`, restart on it, re-verify, and
+     * exit. Shared by the two ways an upgrade can fail after the package swap:
+     * the restart itself (flair#905) and post-restart verification (flair#635).
+     *
+     * flair#905 found the restart leg wired straight to `process.exit(1)` — so
+     * `docs/upgrade.md`'s "install → restart → verify → rollback-on-failure, in
+     * one step" was only ever true for the verify leg. An upgrade that installed
+     * new packages and then failed to start them left the operator on the new
+     * version with nothing running and no rollback, which is the one outcome the
+     * whole transaction exists to prevent.
+     */
+    const rollbackTo = async (toVersion, reason) => {
+        console.log(`\nRolling back @tpsdev-ai/flair to ${toVersion}...`);
+        try {
+            execFileSync("npm", ["install", "-g", `@tpsdev-ai/flair@${toVersion}`], { stdio: "pipe" });
+        }
+        catch (err) {
+            console.error(`❌ rollback install failed: ${err.message}`);
+            console.error(`   Flair is currently on the FAILED version (${expectedFlairVersion ?? "unknown"}) and is NOT running.`);
+            console.error(`   Recover by hand: npm install -g @tpsdev-ai/flair@${toVersion} && flair start`);
+            process.exit(1);
+        }
+        // Same post-swap rule as the upgrade restart above: the rolled-back
+        // version's own CLI is the thing that knows how to start it.
+        const rolledBackCli = resolveInstalledFlairCli(flairPackageDir(), toVersion);
+        try {
+            await restartAfterUpgrade(port, upgradeDataDir, rolledBackCli.ok ? rolledBackCli : null);
+        }
+        catch (err) {
+            console.error(`❌ rollback restart failed: ${err.message}`);
+            console.error(`   @tpsdev-ai/flair@${toVersion} is installed but NOT running. Start it with: flair start`);
+            console.error("   Then check: flair status");
+            process.exit(1);
+        }
+        const rollbackVerify = await probeInstance(baseUrl, {
+            expectVersion: toVersion,
+            timeoutMs: STARTUP_TIMEOUT_MS,
+            authedGet: (path) => verifyAuthedGet(baseUrl, path, defaultKeysDir()),
+        });
+        const rollbackVerdict = decideAfterRollbackVerify(rollbackVerify);
+        if (rollbackVerdict.kind === "rolled-back") {
+            console.error(`❌ upgrade failed and was rolled back to @tpsdev-ai/flair@${toVersion} (running, verified).`);
+            console.error(`   Original failure: ${reason}`);
+            process.exit(1);
+        }
+        console.error(`❌❌ ROLLBACK ALSO FAILED VERIFICATION: ${rollbackVerdict.reason}`);
+        // flair#741 fix #3: this is the exact incident report — a 403 from a
+        // responding, healthy server (credentials-only failure) was printed as
+        // "state UNKNOWN — do not assume data integrity" for BOTH the upgrade
+        // verify AND the rollback re-verify, because the same missing-auth-
+        // material condition rejects both. Reserve the UNKNOWN/do-not-assume
+        // text for failures where the instance's real state genuinely can't be
+        // determined (connection refused, timeout, 5xx) — a credential-only
+        // failure here means the rollback likely landed fine and the checker
+        // simply can't prove it.
+        if (isCredentialOnlyFailure(rollbackVerify)) {
+            console.error("   The instance is up and responding — the verifier could not authenticate (credentials, not the rollback, are the problem).");
+            console.error("   Set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key, then check: flair doctor");
+        }
+        else {
+            console.error("   Instance state is UNKNOWN — do not assume data integrity.");
+        }
+        // This double-failure isn't auto-recoverable yet (flair#637) — but if a
+        // pre-upgrade snapshot landed, point at the CONCRETE path instead of
+        // just the issue number, so recovery doesn't start with a GitHub search.
+        if (snapshotPath) {
+            console.error(`   A pre-upgrade snapshot is available: ${snapshotPath}`);
+            console.error(`   Restore: flair snapshot restore "${snapshotPath}" (or see docs/upgrade.md#downgrade).`);
+        }
+        else {
+            console.error("   No pre-upgrade snapshot was taken for this run (snapshot is opt-in — pass --snapshot next time, or ~/.flair/data didn't exist yet).");
+            console.error("   Check `flair snapshot list` for a manual one, or restore from a `flair backup` JSON export. See docs/upgrade.md#downgrade.");
+        }
+        process.exit(1);
+    };
+    // flair#905: hand the restart to the CLI that was just installed, resolved
+    // from disk AFTER the swap. `null` (flair itself wasn't swapped, or the new
+    // tree can't be verified) falls back to an in-process restart, announced.
+    const flairWasSwapped = flairIsUpgrading && !flairInstallFailed;
+    let newCli = null;
+    if (flairWasSwapped) {
+        const resolved = resolveInstalledFlairCli(flairPackageDir(), expectedFlairVersion);
+        if (resolved.ok === false) {
+            console.error(`warning: could not verify the newly installed CLI (${resolved.reason}) — restarting with this process's own code instead.`);
+        }
+        else {
+            newCli = { cliPath: resolved.cliPath, version: resolved.version };
+        }
+    }
+    let restartWasDelegated = false;
     try {
-        await restartFlair(port);
+        restartWasDelegated = await restartAfterUpgrade(port, upgradeDataDir, newCli);
     }
     catch (err) {
         console.error(`❌ restart failed: ${err.message}`);
-        console.error("   Flair may be partially down. Check: flair doctor");
+        console.error("   Flair is NOT running. Your data in ~/.flair was not touched by this upgrade.");
+        if (flairWasSwapped && previousFlairVersion) {
+            await rollbackTo(previousFlairVersion, `restart failed: ${err.message}`);
+        }
+        // Not reached when a rollback ran — rollbackTo always exits. Say WHICH of
+        // the two "no rollback" cases this is; "nothing to roll back" is not the
+        // same statement as "we don't know what to roll back to".
+        console.error(flairWasSwapped
+            ? "   Cannot roll back automatically: the previously-installed @tpsdev-ai/flair version is unknown."
+            : "   Nothing to roll back: @tpsdev-ai/flair itself was not changed by this upgrade.");
+        console.error("   Start it with: flair start   — then check: flair status");
         process.exit(1);
     }
-    console.log("✅ Flair restarted");
+    // The delegated `flair restart` printed its own success line; don't say it twice.
+    if (!restartWasDelegated)
+        console.log("✅ Flair restarted");
     if (!shouldVerify) {
         console.log("  (--no-verify: skipping post-restart verification)");
         return;
@@ -8646,63 +9587,7 @@ program
         console.error("   Check the instance now: flair doctor");
         process.exit(1);
     }
-    console.log(`\nRolling back @tpsdev-ai/flair to ${verdict.toVersion}...`);
-    try {
-        execFileSync("npm", ["install", "-g", `@tpsdev-ai/flair@${verdict.toVersion}`], { stdio: "pipe" });
-    }
-    catch (err) {
-        console.error(`❌ rollback install failed: ${err.message}`);
-        console.error(`   Flair is currently running the FAILED version (${expectedFlairVersion ?? "unknown"}). Manual intervention required.`);
-        process.exit(1);
-    }
-    try {
-        await restartFlair(port);
-    }
-    catch (err) {
-        console.error(`❌ rollback restart failed: ${err.message}`);
-        console.error("   Instance state is UNKNOWN — it may be down entirely. Check: flair doctor");
-        process.exit(1);
-    }
-    const rollbackVerify = await probeInstance(baseUrl, {
-        expectVersion: verdict.toVersion,
-        timeoutMs: STARTUP_TIMEOUT_MS,
-        authedGet: (path) => verifyAuthedGet(baseUrl, path, defaultKeysDir()),
-    });
-    const rollbackVerdict = decideAfterRollbackVerify(rollbackVerify);
-    if (rollbackVerdict.kind === "rolled-back") {
-        console.error(`❌ upgrade failed verification and was rolled back to @tpsdev-ai/flair@${verdict.toVersion}.`);
-        console.error(`   Original failure: ${verdict.reason}`);
-        process.exit(1);
-    }
-    console.error(`❌❌ ROLLBACK ALSO FAILED VERIFICATION: ${rollbackVerdict.reason}`);
-    // flair#741 fix #3: this is the exact incident report — a 403 from a
-    // responding, healthy server (credentials-only failure) was printed as
-    // "state UNKNOWN — do not assume data integrity" for BOTH the upgrade
-    // verify AND the rollback re-verify, because the same missing-auth-
-    // material condition rejects both. Reserve the UNKNOWN/do-not-assume
-    // text for failures where the instance's real state genuinely can't be
-    // determined (connection refused, timeout, 5xx) — a credential-only
-    // failure here means the rollback likely landed fine and the checker
-    // simply can't prove it.
-    if (isCredentialOnlyFailure(rollbackVerify)) {
-        console.error("   The instance is up and responding — the verifier could not authenticate (credentials, not the rollback, are the problem).");
-        console.error("   Set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key, then check: flair doctor");
-    }
-    else {
-        console.error("   Instance state is UNKNOWN — do not assume data integrity.");
-    }
-    // This double-failure isn't auto-recoverable yet (flair#637) — but if a
-    // pre-upgrade snapshot landed, point at the CONCRETE path instead of
-    // just the issue number, so recovery doesn't start with a GitHub search.
-    if (snapshotPath) {
-        console.error(`   A pre-upgrade snapshot is available: ${snapshotPath}`);
-        console.error(`   Restore: flair snapshot restore "${snapshotPath}" (or see docs/upgrade.md#downgrade).`);
-    }
-    else {
-        console.error("   No pre-upgrade snapshot was taken for this run (snapshot is opt-in — pass --snapshot next time, or ~/.flair/data didn't exist yet).");
-        console.error("   Check `flair snapshot list` for a manual one, or restore from a `flair backup` JSON export. See docs/upgrade.md#downgrade.");
-    }
-    process.exit(1);
+    await rollbackTo(verdict.toVersion, verdict.reason);
 });
 // ─── flair stop ───────────────────────────────────────────────────────────────
 program
@@ -8729,14 +9614,19 @@ program
             }
         }
     }
-    // Fallback: find process by port
+    // Fallback: find process by port. Listening sockets only, never our own
+    // PID — see parseListeningPids (flair#800/flair#905): this used to SIGTERM
+    // every process holding ANY socket on the port, so `flair stop` could kill
+    // itself (leaving Flair running) or kill an unrelated client of it.
     try {
         const { execSync } = await import("node:child_process");
-        const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
-        if (lsof) {
-            const pids = lsof.split("\n").map(p => p.trim()).filter(Boolean);
+        const pids = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
+        if (pids.length > 0) {
             for (const pid of pids) {
-                process.kill(Number(pid), "SIGTERM");
+                try {
+                    process.kill(pid, "SIGTERM");
+                }
+                catch { /* already gone */ }
             }
             console.log(`✅ Flair stopped (killed PID${pids.length > 1 ? "s" : ""}: ${pids.join(", ")})`);
         }
@@ -8793,11 +9683,12 @@ program
         }
     }
     // Direct start (Linux, or macOS fallback when no launchd plist)
-    const bin = harperBin();
-    if (!bin) {
-        console.error("❌ Harper binary not found. Run 'flair init' first.");
+    const harper = resolveHarperBin(harperSearchRoots());
+    if (!harper.path) {
+        console.error(`❌ ${harperBinNotFoundMessage(harper.searched)}`);
         process.exit(1);
     }
+    const bin = harper.path;
     const adminPass = process.env.HDB_ADMIN_PASSWORD || process.env.FLAIR_ADMIN_PASS || "";
     // flair#670/#863: this fallback path (no launchd plist) sets no
     // HARPER_SET_CONFIG, so the ops bind has to be re-asserted explicitly on
@@ -8831,6 +9722,81 @@ program
     }
 });
 // ─── flair restart ────────────────────────────────────────────────────────────
+/**
+ * Refuse to act on a launchd service that belongs to a DIFFERENT data
+ * directory than the one the command is operating on (flair#902).
+ *
+ * `resolveLaunchdLabel`'s instance-scoped label is a hash of the data dir,
+ * so it can never address another instance — but its pre-flair#693 legacy
+ * fallback CAN: `ai.tpsdev.flair` is a single global label, returned for
+ * ANY data dir whenever that plist exists. On a host that still has one,
+ * `flair snapshot restore --data-dir <scratch>` would resolve the legacy
+ * service and stop whatever install it actually belongs to.
+ *
+ * The plist records the instance it was written for (`ROOTPATH`), so the
+ * check is exact. Refuses ONLY on positive contradiction: a plist with no
+ * ROOTPATH (hand-written, or some other writer's) is no evidence and is
+ * left alone rather than blocking a legitimate stop.
+ *
+ * Never logs plist contents — the plist embeds HDB_ADMIN_PASSWORD. Only the
+ * extracted ROOTPATH path ever reaches a message.
+ */
+export function assertLaunchdServiceOwnedBy(dataDir, label, plistPath, action) {
+    let declared = null;
+    try {
+        const raw = readFileSync(plistPath, "utf-8");
+        const m = raw.match(/<key>ROOTPATH<\/key>\s*<string>([^<]*)<\/string>/);
+        // The plist stores this XML-escaped (buildLaunchdPlist), so a data dir
+        // containing `&` is on disk as `&amp;`. Decode before comparing, or the
+        // path would never equal itself and this guard would refuse a legitimate
+        // stop/start on any instance whose path contains an escaped character.
+        declared = m ? unescapeXml(m[1]) : null;
+    }
+    catch {
+        return; // unreadable — no evidence, don't block
+    }
+    if (declared === null)
+        return;
+    if (resolve(declared) === resolve(dataDir))
+        return;
+    throw new Error(`refusing to ${action} launchd service ${label}: its plist (${plistPath}) is registered to data directory ` +
+        `${resolve(declared)}, not ${resolve(dataDir)} — that is a different Flair instance. ` +
+        `Re-run with --data-dir ${resolve(declared)} to act on that one, or run ` +
+        `'flair init --data-dir ${resolve(dataDir)}' to register a service for this one.`);
+}
+/**
+ * Refuse a port-based SIGTERM that cannot be attributed to `dataDir`
+ * (flair#902).
+ *
+ * The port fallback below identifies its target by port number and nothing
+ * else, so `--data-dir <scratch>` with a port that scratch instance does not
+ * serve signals whichever instance DOES serve it. That is the whole of this
+ * bug on Linux, where there is no launchd path at all.
+ *
+ * Scoped deliberately to a non-default data dir. For the default install the
+ * port genuinely is that instance's port by every convention in this CLI
+ * (`writeConfig`/`readPortFromConfig`), and the only evidence available here
+ * — `<dataDir>/hdb.pid` vs the listening PIDs — is not something we can
+ * require without risking a false refusal on a working install whose PID file
+ * is missing or whose listener is a worker. So the default path keeps today's
+ * behavior exactly, and the residual gap is stated rather than papered over:
+ * a default-dir port stop is still unattributed. The new refusal can only
+ * fire for a caller that explicitly named another data dir — the case that is
+ * wrong today whenever the port does not match.
+ */
+function assertPortInstanceOwnedBy(port, dataDir, listeningPids) {
+    if (resolve(dataDir) === defaultDataDir())
+        return;
+    const expected = readHarperPid(dataDir);
+    if (expected !== null && listeningPids.includes(expected))
+        return;
+    const why = expected === null
+        ? `no hdb.pid under that directory, so it does not look like a running instance`
+        : `its recorded PID ${expected} is not the process listening on ${port}`;
+    throw new Error(`refusing to stop the process listening on port ${port}: it cannot be attributed to ${resolve(dataDir)} (${why}). ` +
+        `Stopping by port alone would signal a different Flair instance. ` +
+        `Pass --port with the port ${resolve(dataDir)} actually serves, or omit --data-dir to operate on the default install.`);
+}
 /**
  * Stop the local Flair (Harper) process — launchd `stop` on darwin when a
  * plist is present (falling back on failure), otherwise a manual SIGTERM by
@@ -8839,19 +9805,34 @@ program
  * start without duplicating this logic — `restartFlair` is now just
  * `stopFlairProcess` followed by `startFlairProcess`.
  *
+ * `dataDir` is REQUIRED and names the instance to stop — it is not a
+ * convenience parameter. It used to be resolved internally from
+ * `defaultDataDir()`, which meant `flair snapshot create|restore --data-dir
+ * <elsewhere>` stopped the DEFAULT instance and reported success
+ * (flair#902). A port alone does not identify an instance to launchd; the
+ * data dir does, via `resolveLaunchdLabel`.
+ *
  * Idempotent-ish: stopping an already-stopped instance is a harmless no-op
  * on both paths (launchctl stop on an unloaded/idle service, or an empty
  * `lsof` match).
+ *
+ * Throws when the resolved target provably belongs to a different instance
+ * — see assertLaunchdServiceOwnedBy / assertPortInstanceOwnedBy. Callers
+ * already treat a failed stop as fatal, which is the point: refusing beats
+ * quiescing the wrong install.
  */
-async function stopFlairProcess(port) {
+async function stopFlairProcess(port, dataDir) {
     if (process.platform === "darwin") {
-        const dataDir = defaultDataDir();
         // resolveLaunchdLabel (flair#693) finds whichever label this data dir
         // is currently registered under (new instance-scoped, or a
         // pre-flair#693 legacy install) — stop only needs to operate on
         // whichever exists, no migration.
         const { label, plistPath } = resolveLaunchdLabel(dataDir);
         if (existsSync(plistPath)) {
+            // Outside the try below: an ownership refusal must NOT degrade into
+            // the port-based fallback, which would go on to signal by port the
+            // very instance we just refused to touch.
+            assertLaunchdServiceOwnedBy(dataDir, label, plistPath, "stop");
             try {
                 const { execSync } = await import("node:child_process");
                 // Ensure the service is loaded (init writes the plist but doesn't load it)
@@ -8879,45 +9860,55 @@ async function stopFlairProcess(port) {
     }
     // Port-based stop (Linux, or macOS fallback when no launchd plist)
     console.log("Stopping...");
-    try {
-        const { execSync } = await import("node:child_process");
-        // -sTCP:LISTEN: match the LISTENING server only — a bare `lsof -ti :port`
-        // also matches CLIENT sockets referencing the port, including THIS CLI's
-        // own keep-alive connections left by the credential pre-flight's
-        // probeInstance() HTTP calls (flair#741). Without the filter, the upgrade
-        // path SIGTERM'd its own process mid-restart — "Stopping..." then death
-        // (exit 143) before "Starting..." ever ran, leaving the server down
-        // (flair#800, deterministic on the Linux/non-launchd default path).
-        const lsof = execSync(`lsof -ti :${port} -sTCP:LISTEN`, { encoding: "utf-8" }).trim();
-        if (lsof) {
-            for (const pid of lsof.split("\n")) {
-                const target = Number(pid.trim());
-                // Belt-and-suspenders: never SIGTERM ourselves, whatever lsof says.
-                if (!Number.isFinite(target) || target === process.pid)
-                    continue;
-                try {
-                    process.kill(target, "SIGTERM");
-                }
-                catch { }
-            }
-            // Wait briefly for shutdown
-            await new Promise(r => setTimeout(r, 2000));
+    const { execSync } = await import("node:child_process");
+    // -sTCP:LISTEN plus a self-PID guard, both inside listeningPidsOnPort: a bare
+    // `lsof -ti :port` also matches CLIENT sockets referencing the port, including
+    // THIS CLI's own keep-alive connections left by the credential pre-flight's
+    // probeInstance() HTTP calls (flair#741). Without the filter, the upgrade
+    // path SIGTERM'd its own process mid-restart — "Stopping..." then death
+    // (exit 143) before "Starting..." ever ran, leaving the server down
+    // (flair#800, deterministic on the Linux/non-launchd default path).
+    // flair#905 moved both halves into that one helper because the same
+    // unfiltered pattern had survived in `flair stop`, `flair uninstall` and
+    // `flair doctor` — one guarded resolver is what keeps the next site honest.
+    // It returns [] when lsof matches nothing, which is this path's "not running".
+    const targets = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
+    if (targets.length === 0)
+        return;
+    // Deliberately outside any catch: a refusal must reach the caller, not be
+    // swallowed as "not running" and reported as a successful stop.
+    assertPortInstanceOwnedBy(port, dataDir, targets);
+    for (const target of targets) {
+        try {
+            process.kill(target, "SIGTERM");
         }
+        catch { }
     }
-    catch { /* not running */ }
+    // Wait briefly for shutdown
+    await new Promise((r) => setTimeout(r, 2000));
 }
 /**
  * Start the local Flair (Harper) process — launchd `start` on darwin when a
  * plist is present (falling back on failure), otherwise a direct spawn.
  * Counterpart to `stopFlairProcess`; see that function's doc comment.
+ *
+ * `dataDir` is REQUIRED for the same reason it is on `stopFlairProcess`
+ * (flair#902): it, not the port, is what identifies the instance. This
+ * function resolved it internally from `defaultDataDir()` too, so the
+ * snapshot commands' restart leg brought the DEFAULT instance back up after
+ * operating on a `--data-dir` elsewhere.
  */
-async function startFlairProcess(port) {
-    const dataDir = defaultDataDir();
+async function startFlairProcess(port, dataDir) {
     if (process.platform === "darwin") {
         // resolveLaunchdLabel (flair#693) finds whichever label this data dir
         // is currently registered under before we attempt anything.
-        const { plistPath } = resolveLaunchdLabel(dataDir);
+        const { label, plistPath } = resolveLaunchdLabel(dataDir);
         if (existsSync(plistPath)) {
+            // Same ownership gate as the stop path (flair#902), and outside the
+            // try for the same reason: starting the wrong service would then wait
+            // for health on `port`, see the OTHER instance answer, and report
+            // success.
+            assertLaunchdServiceOwnedBy(dataDir, label, plistPath, "start");
             try {
                 const { execSync } = await import("node:child_process");
                 ensureLaunchdServiceLoaded(dataDir, (cmd) => execSync(cmd, { stdio: "pipe" }));
@@ -8931,10 +9922,11 @@ async function startFlairProcess(port) {
         }
     }
     console.log("Starting...");
-    const bin = harperBin();
-    if (!bin) {
-        throw new Error("Harper binary not found. Run 'flair init' first.");
+    const harper = resolveHarperBin(harperSearchRoots());
+    if (!harper.path) {
+        throw new Error(harperBinNotFoundMessage(harper.searched));
     }
+    const bin = harper.path;
     // Match `flair start`: accept either HDB_ADMIN_PASSWORD or FLAIR_ADMIN_PASS.
     // Without this, `flair init --admin-pass X` (which only exports HDB_*
     // to the initial Harper spawn) followed by `flair restart` would silently
@@ -8981,28 +9973,119 @@ async function startFlairProcess(port) {
  * Throws on failure instead of calling process.exit — callers decide how to
  * react (`flair restart` exits 1; `flair upgrade` treats a failed restart as
  * an upgrade failure and may attempt a rollback).
+ *
+ * Takes `dataDir` explicitly (flair#902) so the instance being bounced is
+ * named at the call site rather than assumed from `defaultDataDir()` two
+ * frames down.
  */
-async function restartFlair(port) {
-    await stopFlairProcess(port);
-    await startFlairProcess(port);
+async function restartFlair(port, dataDir) {
+    await stopFlairProcess(port, dataDir);
+    await startFlairProcess(port, dataDir);
     // Bust the version-handshake cache so the next preAction nudge re-fetches
     // the LIVE version instead of the pre-restart cached one (the false
     // "server is running <old>" users hit for up to 60s post-upgrade+restart).
     // Same (rootPath, serverUrl) key the preAction hook computes (~line 2189)
-    // — must match exactly, or this busts the wrong cache file.
+    // — must match exactly, or this busts the wrong cache file. Deliberately
+    // NOT `dataDir`: the key is whatever the preAction hook computed for THIS
+    // process, and using the restarted instance's dir instead would bust a
+    // different cache file (or none) and leave the stale entry in place.
     try {
         invalidateHandshakeCache(process.env.ROOTPATH ?? defaultDataDir(), `http://127.0.0.1:${port}`);
     }
     catch { /* best-effort — never fail a restart over cache cleanup */ }
 }
+export function resolveInstalledFlairCli(packageRoot, expectVersion, deps = {}) {
+    const exists = deps.exists ?? existsSync;
+    const read = deps.read ?? ((p) => readFileSync(p, "utf-8"));
+    const cliPath = join(packageRoot, "dist", "cli.js");
+    if (!exists(cliPath))
+        return { ok: false, reason: `no dist/cli.js at ${cliPath}` };
+    let version;
+    try {
+        version = JSON.parse(read(join(packageRoot, "package.json"))).version ?? "";
+    }
+    catch (err) {
+        return { ok: false, reason: `could not read ${join(packageRoot, "package.json")}: ${err?.message ?? err}` };
+    }
+    if (!version)
+        return { ok: false, reason: `${join(packageRoot, "package.json")} declares no version` };
+    if (expectVersion && version !== expectVersion) {
+        return { ok: false, reason: `${packageRoot} holds ${version}, expected ${expectVersion}` };
+    }
+    return { ok: true, cliPath, version };
+}
+/**
+ * Restart Flair after a package swap, through the newly installed CLI when one
+ * could be located and in-process otherwise.
+ *
+ * The in-process fallback is deliberate and is NOT a silent one: it announces
+ * which path it took and why. A missing/unverifiable new CLI means the swap
+ * itself is suspect, and refusing to restart at all would turn a recoverable
+ * upgrade into a guaranteed outage — but a fallback nobody can see in the
+ * output is how "it restarted fine" and "it restarted with the wrong code"
+ * become indistinguishable after the fact.
+ *
+ * Delegation is limited to the DEFAULT data directory, and that limit is not
+ * incidental. The child is `flair restart`, which has no `--data-dir` and
+ * therefore restarts `defaultDataDir()` — handing it a `dataDir` that is not
+ * the default would restart a different instance and then wait for health on
+ * `port` and watch the wrong one answer. That is flair#902 exactly, and the
+ * required `dataDir` parameter here exists so the condition is checkable rather
+ * than assumed. Today the upgrade path only ever operates on the default
+ * install, so this never triggers; if that changes, `flair restart` needs a
+ * `--data-dir` before this may delegate.
+ *
+ * Throws on failure; the caller owns the rollback decision. Returns whether the
+ * restart was delegated, so the caller can leave the success line to whichever
+ * process actually printed one.
+ */
+async function restartAfterUpgrade(port, dataDir, newCliArg) {
+    let newCli = newCliArg;
+    if (newCli && resolve(dataDir) !== defaultDataDir()) {
+        console.error(`warning: not delegating the restart to ${newCli.cliPath} — it would restart ${defaultDataDir()}, ` +
+            `not ${resolve(dataDir)}. Restarting with this process's own code instead.`);
+        newCli = null;
+    }
+    if (!newCli) {
+        await restartFlair(port, dataDir);
+        return false;
+    }
+    console.log(`  (restarting via the newly installed CLI: ${newCli.cliPath} @ ${newCli.version})`);
+    const { spawnSync } = await import("node:child_process");
+    const res = spawnSync(process.execPath, [newCli.cliPath, "restart", "--port", String(port)], {
+        encoding: "utf-8",
+        // The child runs the same stop→start→waitForHealth sequence this process
+        // would have; give it the full startup budget plus slack for the stop leg
+        // rather than killing a restart that is merely slow.
+        timeout: STARTUP_TIMEOUT_MS * 3,
+        env: process.env,
+    });
+    if (res.stdout)
+        process.stdout.write(res.stdout);
+    if (res.stderr)
+        process.stderr.write(res.stderr);
+    if (res.error) {
+        throw new Error(`could not run the newly installed CLI (${newCli.cliPath}): ${res.error.message}`);
+    }
+    if (res.status !== 0) {
+        const detail = (res.stderr ?? "").trim().split("\n").filter(Boolean).pop();
+        throw new Error(`the newly installed CLI (@tpsdev-ai/flair@${newCli.version}) failed to restart Flair` +
+            `${res.signal ? ` (killed by ${res.signal})` : ` (exit ${res.status})`}` +
+            `${detail ? `: ${detail}` : ""}`);
+    }
+    return true;
+}
 program
     .command("restart")
     .description("Restart the Flair (Harper) instance")
     .option("--port <port>", "Harper HTTP port")
     .action(async (opts) => {
     const port = resolveHttpPort(opts);
+    // Explicit, not defaulted inside restartFlair (flair#902): `flair
+    // restart` has no --data-dir, so the default install IS what it means —
+    // and saying so here is what keeps that true when someone adds one.
     try {
-        await restartFlair(port);
+        await restartFlair(port, defaultDataDir());
         console.log("✅ Flair restarted");
     }
     catch (err) {
@@ -9041,14 +10124,16 @@ program
         if (removedAny)
             console.log("✅ Launchd service removed");
     }
-    // Kill any process still on the port (covers direct-start, no-service, or failed unload)
+    // Kill any process still on the port (covers direct-start, no-service, or
+    // failed unload). Listening sockets only, never our own PID — see
+    // parseListeningPids (flair#800/flair#905).
     try {
         const { execSync } = await import("node:child_process");
-        const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
-        if (lsof) {
-            for (const pid of lsof.split("\n")) {
+        const pids = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
+        if (pids.length > 0) {
+            for (const pid of pids) {
                 try {
-                    process.kill(Number(pid.trim()), "SIGTERM");
+                    process.kill(pid, "SIGTERM");
                 }
                 catch { }
             }
@@ -9463,8 +10548,10 @@ program
     .option("--no-verify", "Skip post-deploy served-API verification (default: verify — on by design, so the CLI can't report success on an empty/broken deploy)")
     .option("--verify-timeout <ms>", "Milliseconds to wait for the served API to settle after harper's post-deploy restart before verifying (default: 300000)")
     .option("--verify-resource <name>", "Resource to verify is serving after deploy (repeatable; default: derived from the deployed package's dist/resources)", (val, prev) => [...prev, val], [])
-    .option("--deploy-retries <n>", "Retry the full harper deploy this many times on a detected flaky peer-replication failure ONLY — a normal deploy failure (auth, bad package, ...) never retries (default: 2; 0 disables)", "2")
-    .option("--ignore-replication-errors", "If peer replication is still failing once retries are exhausted, treat it as a non-fatal warning and succeed with an origin-only deploy (the peer catches up via federation sync or a later deploy)")
+    .option("--deploy-retries <n>", "Retry the full harper deploy this many times, ONLY when peer replication is positively observed not to converge (default: 0 — retrying re-runs harper's component install and can escalate a transient replication warning into a hard ENOTEMPTY install failure; see flair#878)", "0")
+    .option("--ignore-replication-errors", "If peer replication still hasn't converged, treat it as a non-fatal warning and succeed with an origin-only deploy (the peer catches up via federation sync or a later deploy)")
+    .option("--no-convergence-check", "Skip the post-replication-error convergence poll and fail on harper's error verbatim (default: poll — Harper replicates asynchronously, so its error is a snapshot, not a verdict; flair#878)")
+    .option("--convergence-timeout <ms>", "How long to wait for peer replication to converge before reporting a replication failure (default: 180000)")
     .option("--no-fleet-verify", "Skip the automatic post-deploy fleet convergence sweep (default: sweep runs — see flair#636)")
     .action(async (opts) => {
     const green = (s) => `\x1b[32m${s}\x1b[0m`;
@@ -9499,8 +10586,10 @@ program
         verify: opts.verify !== false,
         verifyResources: opts.verifyResource?.length ? opts.verifyResource : undefined,
         verifyTimeoutMs: Number(opts.verifyTimeout ?? 300_000),
-        deployRetries: Number(opts.deployRetries ?? 2),
+        deployRetries: Number(opts.deployRetries ?? 0),
         ignoreReplicationErrors: opts.ignoreReplicationErrors ?? false,
+        convergenceCheck: opts.convergenceCheck !== false,
+        convergenceTimeoutMs: opts.convergenceTimeout != null ? Number(opts.convergenceTimeout) : undefined,
         onProgress: (msg) => console.log(dim(`  ${msg}`)),
     };
     const errors = validateDeployOptions(deployOpts);
@@ -9525,6 +10614,11 @@ program
             console.log(dim(`  package root: ${result.packageRoot}`));
             return;
         }
+        if (result.convergedAfterReplicationError) {
+            // flair#878: harper's exit code said failure; the per-node component
+            // comparison said otherwise. Both halves get said out loud.
+            console.log(`\n${yellow("⚠")} harper reported a peer-replication failure, but every named peer node's component tree matched the origin when checked afterwards — replication converged on its own.`);
+        }
         if (result.replicationWarning) {
             console.log(`\n${yellow("⚠")} Flair ${result.version} deployed to the ORIGIN NODE ONLY — peer replication did not complete (see warning above). The peer will catch up via federation sync or a later deploy.`);
         }
@@ -9579,8 +10673,9 @@ program
         if (hint?.includes("did not settle")) {
             console.error(dim("  hint: Harper may still be restarting — check Fabric Studio, or retry with a longer --verify-timeout"));
         }
-        if (hint?.includes("peer replication failed after")) {
+        if (hint?.includes("peer replication")) {
             console.error(dim("  hint: pass --ignore-replication-errors to accept an origin-only deploy, or re-run once the peer link recovers"));
+            console.error(dim("  hint: --convergence-timeout <ms> waits longer for asynchronous replication before giving up (default 180000)"));
         }
         process.exit(1);
     }
@@ -9789,7 +10884,10 @@ program
                         console.log(`     ${render.wrap(render.c.dim, "Would update config to port")} ${discoveredPort}`);
                     }
                     else {
-                        writeConfig(discoveredPort);
+                        // dataDir0 is defaultDataDir() — `flair doctor` has no
+                        // --data-dir, so the default install is what it means, and
+                        // saying so keeps that true when it grows one (flair#914).
+                        persistDefaultInstallCoordinates(dataDir0, discoveredPort);
                         console.log(`     ${render.icons.ok} Updated config to port ${discoveredPort}`);
                         fixed++;
                     }
@@ -9813,8 +10911,13 @@ program
             // Check if something else grabbed the port
             try {
                 const { execSync } = await import("node:child_process");
-                const lsof = execSync(`lsof -ti :${port}`, { encoding: "utf-8" }).trim();
-                if (lsof) {
+                // Listening sockets only, never our own PID — doctor has already
+                // probed this port over HTTP, so a bare lsof reports doctor's own
+                // process as the squatter and tells the operator to kill it
+                // (flair#905; see parseListeningPids).
+                const pids = listeningPidsOnPort(port, (cmd) => execSync(cmd, { encoding: "utf-8" }));
+                if (pids.length > 0) {
+                    const lsof = pids.join(" ");
                     console.log(`  ${render.icons.error} Nothing responding on port ${port} ${render.wrap(render.c.dim, `(port occupied by PID ${lsof})`)}`);
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} kill ${lsof} && flair restart`);
                 }
@@ -9936,9 +11039,8 @@ program
     // (see its doc comment) now reuses the existing password instead, so this
     // remedy is safe to follow on a working install.
     try {
-        const harperConfigPath = join(defaultDataDir(), "harper-config.yaml");
-        if (existsSync(harperConfigPath)) {
-            const harperConfig = parseYaml(readFileSync(harperConfigPath, "utf-8")) || {};
+        const harperConfig = readHarperConfig(defaultDataDir());
+        if (harperConfig) {
             const opsPortValue = harperConfig?.operationsApi?.network?.port;
             const bind = detectOpsApiAllInterfacesBind(opsPortValue);
             if (bind.allInterfaces) {
@@ -10074,6 +11176,16 @@ program
     else {
         let claudeCodeAgentId;
         let anyKnownAgentId;
+        // `doctor --fix` writes client configs through the same wire functions
+        // init does, so it owes the user the same warning when the spec it would
+        // write cannot be pinned (flair#907).
+        if (autoFix) {
+            const pinWarning = unpinnedSpecWarning();
+            if (pinWarning) {
+                for (const line of pinWarning.split("\n"))
+                    console.log(`  ${render.icons.warn} ${line}`);
+            }
+        }
         for (const client of detectedClients) {
             const block = readClientMcpBlock(client.id, homedir());
             if (client.id === "claude-code" && block.agentId)
@@ -10392,9 +11504,30 @@ program
             if (migBlock.cyclePhase === "pre-hash") {
                 console.log(`${indent}${render.icons.info} Pre-flight integrity check in progress — migrations deferred until it completes`);
             }
+            // flair#812: the boot trigger sets `scheduled` synchronously at
+            // module load, so `idle` means resources/migration-boot.js never
+            // loaded in the serving process — NO migration will ever run on
+            // this instance, which is precisely the failure that went unnoticed
+            // because a skipped cycle looked identical to a clean one.
+            if (migBlock.cyclePhase === "idle") {
+                console.log(`${indent}${render.icons.error} Migration boot cycle never fired on this instance — no migration will run until this is resolved. Check the instance log for [flair-migrations] and confirm the running build ships dist/resources/migration-boot.js.`);
+                issues++;
+            }
+            // A cycle that reached a terminal phase carrying an error explains
+            // itself here rather than only in the process log — the reason
+            // string names the paths tried and the remedy.
+            if (migBlock.lastCycleError) {
+                console.log(`${indent}${render.icons.error} Last migration cycle did not complete: ${migBlock.lastCycleError}`);
+                issues++;
+            }
             for (const m of migBlock.migrations) {
                 if (m.state === "completed") {
-                    console.log(`${indent}${render.icons.ok} ${m.id}: completed`);
+                    // flair#812: a `reason` on a COMPLETED migration means the
+                    // runner short-circuited it from the (hand-editable) state file
+                    // rather than verifying the corpus this boot. Print it, so an
+                    // unverified claim is never rendered as a verified one.
+                    const note = m.reason ? ` ${render.wrap(render.c.dim, `(${m.reason})`)}` : "";
+                    console.log(`${indent}${render.icons.ok} ${m.id}: completed${note}`);
                 }
                 else if (m.state === "halted" || m.state === "failed") {
                     console.log(`${indent}${render.icons.error} ${m.id}: ${m.state}${m.reason ? ` — ${m.reason}` : ""}`);
@@ -11473,6 +12606,17 @@ sessionSnapshot
         process.exit(1);
     }
     mkdirSync(targetDir, { recursive: true, mode: 0o700 });
+    // Deliberately NOT preservePaths, and deliberately NOT routed through
+    // extractSnapshotSafely. --snapshot is an operator-supplied path, so
+    // provenance here is no more controlled than the data-dir restore's — the
+    // difference is the flag, not the trust. node-tar's defaults keep their
+    // own containment: leading "/" stripped from entry paths, ".." entries
+    // dropped, and no writing through a symlink (including one created
+    // earlier in the same archive). Verified against the pinned tar (7.5.20)
+    // on all four cases, each contained, with a benign control entry landing
+    // to prove the archives parsed. Add `preservePaths` here and that
+    // containment disappears — this call would then need extractSnapshotSafely,
+    // exactly as the data-dir restore does. See src/lib/safe-snapshot-extract.ts.
     await tarExtract({ file: snapshotPath, cwd: targetDir });
     console.log(targetDir);
     console.error(`  extracted to: ${targetDir}`);
@@ -13989,6 +15133,8 @@ if (import.meta.main) {
     await runCli();
 }
 // ─── Exported for testing ─────────────────────────────────────────────────────
-export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, readOpsBindFromConfig, readOpsPortFromConfig, writeConfig, resolveHttpPort, resolveOpsPort, resolveOpsBindHost, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
+export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, readOpsBindFromConfig, readOpsPortFromConfig, writeConfig, resolveHttpPort, resolveOpsPort, resolveOpsBindHost, 
+// Harper's own config — the per-instance port record (flair#914)
+harperConfigPath, readHarperConfig, readPortFromHarperConfig, persistDefaultInstallCoordinates, resolveTarget, resolveOpsTarget, resolveEffectiveOpsUrl, resolveOpsUrlFromTarget, signRequestBody, b64, b64url, program, api, VALID_PRESENCE_ACTIVITIES, MAX_TASK_LENGTH, MAX_WORKSPACE_FIELD_LENGTH, MAX_ORGEVENT_SUMMARY_LENGTH, MAX_ORGEVENT_DETAIL_LENGTH, isLocalBase, isLikelyRealSecret, shouldShowInlineSecretWarning, parseTokenFromFile, resolveLocalAdminPass, readAdminPassFileSecure, 
 // launchd label (flair#693)
 LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, };