@tpsdev-ai/flair 0.31.0 → 0.32.0

package/README.md

@@ -40,7 +40,19 @@ Self-hosted on [Harper](https://harper.fast) as a single process. No sidecars, n
 
 ## Quick start
 
-Needs **Node.js 22+** and a **user-writable npm global prefix**.
+Two front doors. Pick by where your code already runs.
+
+### Already on Harper? Load Flair as a component
+
+Flair *is* a Harper component. Deploy it into the instance your application already runs in and call its resources directly — `await h.post({ agentId, content })` is a **method call**, not a network call. No second service to operate, no HTTP round trip, and no key to distribute: a caller in the same process is already inside the trust boundary and names the agent it is acting as, per call.
+
+Adding it takes nothing away. The HTTP surface keeps serving MCP clients and remote agents exactly as before.
+
+**→ [Embedding Flair in a Harper app](docs/embedding-in-a-harper-app.md)** — the whole in-process contract, measured against a real instance: resolving the resource, the table-vs-resource distinction that decides whether your memories are scoped at all, N agents in one process, and registering agents with no shell on the node.
+
+### Everywhere else — install the CLI
+
+A laptop, a VPS, an MCP client, or any language over HTTP. Needs **Node.js 22+** and a **user-writable npm global prefix**.
 
 > ⚠️ **Never `sudo npm install -g @tpsdev-ai/flair`.** A root-owned install can't write the embedding model into its own package directory, so semantic search silently degrades to keyword-only. `flair init` and `flair doctor` will warn you loudly. Use `nvm`, or point npm at your home directory: `npm config set prefix ~/.npm-global` and add `~/.npm-global/bin` to `PATH`.
 
@@ -73,6 +85,14 @@ That trailing figure is a rank score, normalized so the top hit is always near 1
 
 Full walkthrough with expected output at every step: **[docs/quickstart.md](docs/quickstart.md)**.
 
+### Where the agent's key lives
+
+`flair init --agent mybot` writes the private key to `~/.flair/keys/mybot.key` (mode `0600`) and the public half beside it as `mybot.pub`. Only the **public** key is registered on the instance; the private key never leaves the machine. `--keys-dir` writes both somewhere else.
+
+**Back that file up — it is the agent's identity, and there is one copy.** Memories are not encrypted with it, so losing it costs the identity, not the data: the agent can no longer sign, and every HTTP call it makes fails. Recovery is `flair agent rotate-key mybot`, which mints a new pair and re-registers the public half — it needs the admin password `flair init` wrote to `~/.flair/admin-pass`, so back that up too. Otherwise treat the key like an SSH key: one per agent per host, never copied between machines ([docs/secrets-and-keys.md](docs/secrets-and-keys.md)).
+
+**The in-process path needs no key at all.** Keys are how an agent *outside* the process proves who it is. Code running inside the same Harper instance asserts identity through the call context instead — `agentContext("mybot")` — which Flair reads and acts on with no signature, no `Agent`-table lookup and no registration. That is deliberate: same-process code could write the storage tables directly, so demanding a signature from it would be theatre. It is also why that id must come from your own server-side state and never from request data.
+
 ### Useful flags
 
 ```bash
@@ -278,24 +298,30 @@ Sign `agentId:timestamp:nonce:METHOD:/path` with the agent's private key. Protoc
 
 ### Embedded in a Harper app (in-process)
 
-Flair *is* a Harper component. If your application already runs on Harper, load Flair into the same instance and call its resources directly — a method call instead of an HTTP round trip.
+Flair *is* a Harper component. If your application already runs on Harper, load Flair into the same instance and call its resources directly — a method call instead of an HTTP round trip, and no key anywhere.
 
 ```javascript
 import { server } from "harper";
+import { agentContext, collectionResource } from "@tpsdev-ai/flair/dist/resources/in-process.js";
+
+// The RESOURCE — auth, read-scoping, visibility, embedding.
+// Registry keys carry no leading slash: get("Memory"), never get("/Memory").
+const Memory = server.resources.get("Memory").Resource;
 
-const Memory = server.resources.get("Memory").Resource;   // the resource, not the table
-const h = new Memory(undefined, { request: { tpsAgent: "mybot" } });
+const h = await collectionResource(Memory, agentContext("mybot"));
 await h.post({ agentId: "mybot", content: "...", durability: "standard" });
 ```
 
-`databases.flair.Memory` is the **table** (raw storage); the exported `Memory` class is the **resource**, where auth, read-scoping, visibility and embedding live. A context-less call runs unfiltered. Full guide: **[docs/embedding-in-a-harper-app.md](docs/embedding-in-a-harper-app.md)**.
+`databases.flair.Memory` is the **table** (raw storage); the exported `Memory` class is the **resource**, where auth, read-scoping, visibility and embedding live. `new Memory(...)` is not a substitute for `collectionResource` — a create needs a collection-bound instance only Harper can produce. Both helpers refuse a missing agent id rather than defaulting it, because a resource invoked with no context resolves to Flair's trusted `internal` verdict and runs unfiltered across every agent. Full guide: **[docs/embedding-in-a-harper-app.md](docs/embedding-in-a-harper-app.md)**.
 
 ### Auth across surfaces
 
-The default everywhere is **Ed25519 per-agent**: each agent holds its own key at `~/.flair/keys/<agent>.key` and signs every request. That gives write isolation — no agent can write as another — and identity-verified reads. It does *not* refuse cross-agent reads: within one instance, any verified agent can read any other agent's non-private memory by design. The hard boundary is the federation edge, not intra-instance reads. See [SECURITY.md](SECURITY.md).
+For every caller that reaches Flair over the network the default is **Ed25519 per-agent**: each agent holds its own key at `~/.flair/keys/<agent>.key` and signs every request. That gives write isolation — no agent can write as another — and identity-verified reads. It does *not* refuse cross-agent reads: within one instance, any verified agent can read any other agent's non-private memory by design. The hard boundary is the federation edge, not intra-instance reads. See [SECURITY.md](SECURITY.md).
 
 One exception: the **`n8n-nodes-flair`** node authenticates with the Harper **admin password** (Basic auth), which bypasses agent scoping entirely — it can read other agents' `visibility: private` memories and write as anyone. That is acceptable only on a single-tenant, operator-controlled n8n with trusted workflow inputs. Otherwise prefer the Ed25519 path. Full breakdown in **[docs/auth.md](docs/auth.md#auth-across-surfaces-read-this-first)**.
 
+In-process callers are a different model, not an exception to this one: they never sign, because identity is asserted through the call context rather than proven. Co-location *is* the grant — which is why Flair beside untrusted co-tenants on a shared instance is a different proposition to Flair inside your own app.
+
 ## Deployment
 
 ### Local (default)

package/dist/cli.js

@@ -269,7 +269,19 @@ function migrateLegacyLaunchdLabel(dataDir, runLaunchctl, launchAgentsDir = defa
     }
     catch { /* best effort */ }
     const legacyContent = readFileSync(resolved.plistPath, "utf-8");
-    const newContent = legacyContent.replace(`<key>Label</key><string>${LEGACY_LAUNCHD_LABEL}</string>`, `<key>Label</key><string>${newLabel}</string>`);
+    // Use a function replacer to avoid $-sensitivity in the replacement
+    // string (flair#919). String.prototype.replace interprets $&, $', $`
+    // etc. in the replacement even when the search value is a plain string.
+    const labelSearch = `<key>Label</key><string>${LEGACY_LAUNCHD_LABEL}</string>`;
+    const labelReplacement = `<key>Label</key><string>${newLabel}</string>`;
+    const newContent = legacyContent.replace(labelSearch, () => labelReplacement);
+    // Refuse to propagate a malformed plist: if the Label wasn't found,
+    // the plist is not what we expect and migration must not write it.
+    if (newContent === legacyContent) {
+        throw new Error(`Legacy plist at ${resolved.plistPath} does not contain the expected ` +
+            `Label key — it may be malformed or from an unknown Flair version. ` +
+            `Remove it manually and re-run 'flair init'.`);
+    }
     writeFileSync(newPlistPath, newContent);
     try {
         unlinkSync(resolved.plistPath);
@@ -277,6 +289,58 @@ function migrateLegacyLaunchdLabel(dataDir, runLaunchctl, launchAgentsDir = defa
     catch { /* best effort */ }
     return { migrated: true, label: newLabel, plistPath: newPlistPath };
 }
+/**
+ * Clean up a pre-flair#693 legacy launchd plist (ai.tpsdev.flair) during
+ * init, but ONLY when it belongs to the data dir being initialised.
+ *
+ * flair#966: the legacy plist is a single global label — init must not
+ * unload/delete it unless ROOTPATH proves it serves this data dir.
+ *
+ * `runLaunchctl` is injected so tests can record/mock without touching
+ * real launchd. The caller (init) passes a real execSync wrapper; tests
+ * pass a recording stub.
+ */
+function cleanupLegacyLaunchdPlist(dataDir, plistDir, runLaunchctl) {
+    const legacyPlistPath = launchdPlistPath(LEGACY_LAUNCHD_LABEL, plistDir);
+    if (!existsSync(legacyPlistPath))
+        return { action: "none" };
+    const legacyRootPath = readPlistRootPath(legacyPlistPath);
+    const legacyOwnedByUs = legacyRootPath !== null && resolve(legacyRootPath) === resolve(dataDir);
+    if (legacyOwnedByUs) {
+        let unloadFailed;
+        let deleteFailed;
+        try {
+            runLaunchctl(`launchctl unload "${legacyPlistPath}"`);
+        }
+        catch (err) {
+            unloadFailed = err?.message ?? String(err);
+            console.error(`Failed to unload legacy launchd service (${LEGACY_LAUNCHD_LABEL}): ` +
+                `${unloadFailed}. ` +
+                `The plist at ${legacyPlistPath} may still be loaded — ` +
+                `unload it manually with: launchctl unload "${legacyPlistPath}"`);
+        }
+        try {
+            unlinkSync(legacyPlistPath);
+            console.log(`Migrated off legacy launchd label (${LEGACY_LAUNCHD_LABEL}) ✓`);
+        }
+        catch (err) {
+            deleteFailed = err?.message ?? String(err);
+            console.error(`Failed to remove legacy launchd plist at ${legacyPlistPath}: ` +
+                `${deleteFailed}. Remove it manually.`);
+        }
+        return { action: "unloaded", unloadFailed, deleteFailed };
+    }
+    if (legacyRootPath !== null) {
+        console.log(`Skipped legacy launchd cleanup: the plist at ${legacyPlistPath} ` +
+            `belongs to data dir ${resolve(legacyRootPath)}, not ${resolve(dataDir)} — ` +
+            `that is a different Flair instance.`);
+        return { action: "skipped-foreign", foreignDataDir: resolve(legacyRootPath) };
+    }
+    console.log(`Skipped legacy launchd cleanup: could not determine which data dir ` +
+        `the plist at ${legacyPlistPath} serves. ` +
+        `If it is yours, remove it manually with: rm "${legacyPlistPath}"`);
+    return { action: "skipped-unknown" };
+}
 /**
  * Load + start `dataDir`'s launchd service, migrating off a pre-flair#693
  * legacy registration FIRST if one is found (migrateLegacyLaunchdLabel
@@ -290,6 +354,13 @@ function migrateLegacyLaunchdLabel(dataDir, runLaunchctl, launchAgentsDir = defa
  */
 function ensureLaunchdServiceLoaded(dataDir, runLaunchctl, launchAgentsDir = defaultLaunchAgentsDir()) {
     const migration = migrateLegacyLaunchdLabel(dataDir, runLaunchctl, launchAgentsDir);
+    // Unload first so a rewritten plist is re-read (flair#872).
+    // launchd caches the environment of an already-loaded job; load
+    // alone does not pick up changes to the plist on disk.
+    try {
+        runLaunchctl(`launchctl unload "${migration.plistPath}"`);
+    }
+    catch { /* not loaded, etc. — best effort */ }
     try {
         runLaunchctl(`launchctl load "${migration.plistPath}"`);
     }
@@ -500,15 +571,14 @@ function readOpsPortFromConfig(path = configPath()) {
  *     a clean install has always done, instead of the refusal that would make
  *     `flair init --data-dir <new>` impossible.
  *
- * Note that `init`'s own `--port` option carries a commander default of
- * DEFAULT_PORT, so in practice `opts.port` is always set there and this
- * function returns on the first rung — including when re-initialising an
- * instance that already serves a different port, which is silently renumbered
- * to DEFAULT_PORT. That is pre-existing (it is equally true of the default
- * install on a custom port, where re-running init is `flair doctor`'s standing
- * remedy) and is tracked separately; the "create" rung is what this function
- * would answer if that default were removed, and is what keeps the mode
- * distinction honest rather than hypothetical.
+ * 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
@@ -2386,6 +2456,14 @@ const __pkgVersion = flairCliVersion();
 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
@@ -2434,7 +2512,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)")
@@ -2640,9 +2723,14 @@ program
     // 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. (`--port` carries a
-    // commander default, so this usually returns on the flag rung; see
-    // resolveHttpPort's doc comment.)
+    // 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`,
@@ -2916,25 +3004,20 @@ program
                 const plistDir = defaultLaunchAgentsDir();
                 mkdirSync(plistDir, { recursive: true });
                 const plistPath = launchdPlistPath(label, plistDir);
-                // flair#693 migration: a pre-flair#693 install registered under
+                // flair#693 + flair#966: a pre-flair#693 install registered under
                 // the bare LEGACY_LAUNCHD_LABEL. init always writes fresh plist
                 // content below (it has the current ports/creds in hand), so
                 // migration here is just "clean up the old registration" —
                 // unload + remove it BEFORE writing the new one, so re-running
                 // init never leaves two services behind for this data dir.
-                const legacyPlistPath = launchdPlistPath(LEGACY_LAUNCHD_LABEL, plistDir);
-                if (existsSync(legacyPlistPath)) {
-                    try {
-                        const { execSync } = await import("node:child_process");
-                        execSync(`launchctl unload "${legacyPlistPath}"`, { stdio: "pipe" });
-                    }
-                    catch { /* best effort */ }
-                    try {
-                        unlinkSync(legacyPlistPath);
-                    }
-                    catch { /* best effort */ }
-                    console.log(`Migrated off legacy launchd label (${LEGACY_LAUNCHD_LABEL}) ✓`);
-                }
+                //
+                // flair#966: the legacy plist is NOT scoped to this data dir —
+                // it is a single global label. cleanupLegacyLaunchdPlist reads
+                // ROOTPATH to establish ownership before touching it.
+                cleanupLegacyLaunchdPlist(dataDir, plistDir, (cmd) => {
+                    const { execSync } = require("node:child_process");
+                    execSync(cmd, { stdio: "pipe" });
+                });
                 const opsSocket = join(dataDir, "operations-server");
                 // authorizeLocal: false (flair#654) — same posture as the initial spawn
                 // above; the launchd-managed process must not diverge from it.
@@ -3601,7 +3684,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)));
@@ -4753,6 +4837,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>")
@@ -4822,6 +4923,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(),
@@ -4874,7 +4980,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) {
@@ -4908,7 +5017,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",
@@ -4950,8 +5066,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)
@@ -6222,23 +6343,29 @@ 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))
-    .option("--admin-pass-file <path>", "Path to a 0600 file holding the admin password (default ~/.flair/admin-pass when it exists). The PATH is stored in the unit — never the password.")
     // 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")
-    .option("--target <url>", "Remote Flair URL to sync (default: the local instance)")
+    // `--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 BOTH this subcommand and its parent
-    // (`flair federation sync`), and when a parent declares the same option
-    // name commander binds the value to the PARENT — the subcommand's own
-    // opts come back undefined. Reading only the local opts silently dropped
-    // `--admin-pass-file <path>` here, which would have installed a driver
+    // 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.
+    // 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)) {
@@ -6306,12 +6433,14 @@ federationSync
 federationSync
     .command("status")
     .description("Show whether a sync driver is installed and genuinely active")
-    .option("--port <port>", "Harper HTTP port")
-    .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
+    // `--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` are declared on
-    // the parent too, so commander binds them there.
+    // 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 {
@@ -8482,7 +8611,9 @@ 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,
@@ -8992,7 +9123,14 @@ 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)")
@@ -9669,20 +9807,28 @@ program
  * 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;
+/**
+ * Read the ROOTPATH declared in a launchd plist, or null if it cannot be
+ * determined (file missing, unreadable, or no ROOTPATH key).
+ *
+ * The plist stores this XML-escaped (buildLaunchdPlist), so the returned
+ * value is decoded through unescapeXml before being returned — a data dir
+ * containing `&` is on disk as `&amp;` and this returns the literal `&`.
+ *
+ * Never logs plist contents — the plist embeds HDB_ADMIN_PASSWORD.
+ */
+export function readPlistRootPath(plistPath) {
     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;
+        return m ? unescapeXml(m[1]) : null;
     }
     catch {
-        return; // unreadable — no evidence, don't block
+        return null;
     }
+}
+export function assertLaunchdServiceOwnedBy(dataDir, label, plistPath, action) {
+    const declared = readPlistRootPath(plistPath);
     if (declared === null)
         return;
     if (resolve(declared) === resolve(dataDir))
@@ -9763,18 +9909,15 @@ async function stopFlairProcess(port, dataDir) {
             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)
-                try {
-                    execSync(`launchctl load "${plistPath}"`, { stdio: "pipe" });
-                }
-                catch { }
-                // Capture the current PID *before* stopping so callers that
+                // Capture the current PID *before* unloading so callers that
                 // immediately restart can verify exit. Without this, waitForHealth
                 // can race against the still-shutting-down old process and return
-                // success before KeepAlive brings the new one up.
+                // success before the new one comes up.
                 const oldPid = readHarperPid(dataDir);
+                // unload stops the job AND prevents KeepAlive from respawning it.
+                // launchctl stop alone is insufficient for a KeepAlive job (flair#874).
                 try {
-                    execSync(`launchctl stop ${label}`, { stdio: "pipe" });
+                    execSync(`launchctl unload "${plistPath}"`, { stdio: "pipe" });
                 }
                 catch { }
                 if (oldPid)
@@ -13996,6 +14139,19 @@ program
         console.error("Error: --admin-pass, --admin-pass-file, or FLAIR_ADMIN_PASS required for backup");
         process.exit(1);
     }
+    // flair#968: `flair backup > file.json` captures the progress report, not
+    // the archive (which goes to --output, defaulting to ~/.flair/backups/...).
+    // The result was exit 0 and a plausible-looking file of a few hundred bytes —
+    // a false success immediately before a destructive upgrade.
+    //
+    // When stdout is not a TTY, route progress output to stderr. The archive
+    // still goes to --output / the default path. This makes `flair backup >
+    // file.json` produce an EMPTY file — unmistakably not a valid archive —
+    // while leaving default-path callers (schedulers, cron) completely
+    // unaffected.
+    const log = process.stdout.isTTY
+        ? console.log.bind(console)
+        : console.error.bind(console);
     const auth = `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`;
     async function adminGet(path) {
         const res = await fetch(`${baseUrl}${path}`, {
@@ -14008,11 +14164,11 @@ program
         }
         return res.json();
     }
-    console.log("Fetching agents...");
+    log("Fetching agents...");
     const allAgents = await adminGet("/Agent/");
     const filterIds = opts.agents ? opts.agents.split(",").map((s) => s.trim()) : null;
     const agents = filterIds ? allAgents.filter((a) => filterIds.includes(a.id)) : allAgents;
-    console.log(`Fetching memories for ${agents.length} agent(s)...`);
+    log(`Fetching memories for ${agents.length} agent(s)...`);
     const memories = [];
     for (const agent of agents) {
         try {
@@ -14024,7 +14180,7 @@ program
             console.warn(`  Warning: could not fetch memories for ${agent.id}: ${err.message}`);
         }
     }
-    console.log("Fetching souls...");
+    log("Fetching souls...");
     const souls = [];
     for (const agent of agents) {
         try {
@@ -14052,11 +14208,11 @@ program
     const tmp = outputPath + ".tmp";
     writeFileSync(tmp, JSON.stringify(backup, null, 2) + "\n", "utf-8");
     renameSync(tmp, outputPath);
-    console.log(`\n${render.icons.ok} ${render.wrap(render.c.green, "Backup complete")}`);
-    console.log(render.kv("Agents", render.wrap(render.c.bold, String(agents.length))));
-    console.log(render.kv("Memories", render.wrap(render.c.bold, String(memories.length))));
-    console.log(render.kv("Souls", render.wrap(render.c.bold, String(souls.length))));
-    console.log(render.kv("Output", render.wrap(render.c.dim, outputPath)));
+    log(`\n${render.icons.ok} ${render.wrap(render.c.green, "Backup complete")}`);
+    log(render.kv("Agents", render.wrap(render.c.bold, String(agents.length))));
+    log(render.kv("Memories", render.wrap(render.c.bold, String(memories.length))));
+    log(render.kv("Souls", render.wrap(render.c.bold, String(souls.length))));
+    log(render.kv("Output", render.wrap(render.c.dim, outputPath)));
 });
 // ─── flair restore ────────────────────────────────────────────────────────────
 program
@@ -15065,4 +15221,4 @@ export { runCli, resolveKeyPath, buildEd25519Auth, readPortFromConfig, readOpsBi
 // 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, };
+LEGACY_LAUNCHD_LABEL, launchdLabel, launchdPlistPath, cleanupLegacyLaunchdPlist, resolveLaunchdLabel, migrateLegacyLaunchdLabel, ensureLaunchdServiceLoaded, };

package/dist/resources/AdminPrincipals.js

@@ -1,6 +1,7 @@
 import { Resource, databases } from "harper";
 import { layout, htmlResponse, esc } from "./admin-layout.js";
 import { allowAdmin } from "./agent-auth.js";
+import { adminFieldsDisagree, agentRecordIsAdmin } from "./agent-admin.js";
 /**
  * GET /AdminPrincipals — list all principals with kind, trust, status.
  *
@@ -39,7 +40,15 @@ export class AdminPrincipals extends Resource {
                 const statusBadge = status === "active"
                     ? `<span class="badge badge-green">${status}</span>`
                     : `<span class="badge badge-gray">${status}</span>`;
-                const admin = p.admin ? "yes" : "";
+                // flair#941 — report the status the GATE will actually apply, not the
+                // `admin` mirror. This column used to read the mirror alone, so a
+                // principal created by `flair principal add --admin` showed "yes" while
+                // allowAdmin() rejected it. A record whose two fields disagree (only
+                // reachable by a raw table write) is flagged rather than silently
+                // resolved, so an operator can see that it needs repairing.
+                const admin = agentRecordIsAdmin(p)
+                    ? (adminFieldsDisagree(p) ? "yes <small>(inconsistent record)</small>" : "yes")
+                    : (adminFieldsDisagree(p) ? "no <small>(inconsistent record)</small>" : "");
                 const created = p.createdAt?.slice(0, 10) ?? "—";
                 tableRows += `
           <tr>