@tpsdev-ai/flair 0.31.0 → 0.31.1

package/dist/cli.js

@@ -500,15 +500,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 +2385,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 +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)")
@@ -2640,9 +2652,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`,
@@ -3601,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)));
@@ -4753,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>")
@@ -4822,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(),
@@ -4874,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) {
@@ -4908,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",
@@ -4950,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)
@@ -6222,23 +6277,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 +6367,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 +8545,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 +9057,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)")

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>

package/dist/resources/Agent.js

@@ -1,5 +1,6 @@
 import { databases } from "harper";
-import { resolveAgentAuth, allowVerified, allowAdmin } from "./agent-auth.js";
+import { resolveAgentAuth, allowVerified, allowAdmin, invalidateAdminCache } from "./agent-auth.js";
+import { agentRecordIsAdmin, reconcileAdminFields } from "./agent-admin.js";
 import { localInstanceId } from "./instance-identity.js";
 /**
  * Agent resource — serves as the Principal table in 1.0.
@@ -34,10 +35,18 @@ export class Agent extends databases.flair.Agent {
         content.kind ||= "agent";
         content.status ||= "active";
         content.displayName ||= content.name;
-        content.admin ??= false;
-        // Trust tier defaults per kind
+        // flair#941 — the two admin fields are reconciled BEFORE anything derives
+        // from them, so `role` and `admin` agree on disk whichever one the caller
+        // used. Replaces `content.admin ??= false`, which defaulted the mirror
+        // without ever consulting the authority: a caller who passed role:"admin"
+        // got a record that was an admin at the gate and a non-admin to every
+        // reporter. allowCreate() is allowAdmin(), so this path is admin-only.
+        reconcileAdminFields(content);
+        // Trust tier defaults per kind — derived from the SAME predicate the gate
+        // uses, so an admin principal cannot land on the non-admin default just
+        // because the caller spelled admin the other way.
         if (!content.defaultTrustTier) {
-            content.defaultTrustTier = content.admin ? "endorsed" : "unverified";
+            content.defaultTrustTier = agentRecordIsAdmin(content) ? "endorsed" : "unverified";
         }
         content.createdAt = now;
         content.updatedAt = now;
@@ -51,7 +60,25 @@ export class Agent extends databases.flair.Agent {
         }
         return super.post(content, context);
     }
-    async put(content) {
+    /**
+     * Authorization shared by BOTH mutation paths (PUT → put, PATCH → patch).
+     *
+     * It lives in one place because it previously lived only in put(), and PATCH
+     * does not route through put() — so every rule written here was enforced on
+     * one verb and not the other. Returns a Response to send, or null to proceed.
+     *
+     * Two rules:
+     *   1. Only an admin principal may modify a principal OTHER than itself.
+     *   2. Only an admin principal may change a principal's ADMIN STATUS — on any
+     *      record, including the caller's own. Rule 1 alone never covered this:
+     *      an agent editing its own record is inside its rights for ordinary
+     *      fields (runtime, displayName, subjects) and must not be for the fields
+     *      that decide whether it is an administrator.
+     *
+     * `internal` (in-process maintenance, federation merge) and admin agents pass
+     * through unchanged.
+     */
+    async authorizePrincipalWrite(content) {
         const auth = await resolveAgentAuth(this.getContext?.());
         // Anonymous denied (defense-in-depth alongside allowUpdate; the old check read
         // tpsAgent and treated a missing agent as trusted, so anonymous slipped through).
@@ -60,24 +87,91 @@ export class Agent extends databases.flair.Agent {
                 status: 401, headers: { "content-type": "application/json" },
             });
         }
-        // Only admin principals can modify OTHER principals; an agent updates its own.
-        if (auth.kind === "agent" && !auth.isAdmin) {
-            const existing = await super.get();
-            if (existing && existing.id !== auth.agentId) {
-                return new Response(JSON.stringify({ error: "only admin principals can modify other principals" }), {
+        if (auth.kind !== "agent" || auth.isAdmin)
+            return null;
+        const existing = await Promise.resolve(super.get()).catch(() => null);
+        // 1. Only admin principals can modify OTHER principals.
+        if (existing && existing.id !== auth.agentId) {
+            return new Response(JSON.stringify({ error: "only admin principals can modify other principals" }), {
+                status: 403, headers: { "content-type": "application/json" },
+            });
+        }
+        // 2. Only admin principals can change admin status. Compare the RESULTING
+        // status against the stored one so an ordinary self-update that simply
+        // doesn't mention either field is unaffected, and a no-op restatement of
+        // the caller's existing status is not a spurious denial.
+        const touchesPrivilegeFields = content != null && typeof content === "object" && ("role" in content || "admin" in content);
+        if (touchesPrivilegeFields) {
+            const merged = { ...(existing ?? {}), ...content };
+            const wouldBeAdmin = agentRecordIsAdmin(merged) || merged.admin === true;
+            const isAdminNow = agentRecordIsAdmin(existing) || (existing?.admin === true);
+            if (wouldBeAdmin !== isAdminNow) {
+                return new Response(JSON.stringify({ error: "only admin principals can change a principal's admin status" }), {
                     status: 403, headers: { "content-type": "application/json" },
                 });
             }
         }
+        return null;
+    }
+    async put(content) {
+        const denial = await this.authorizePrincipalWrite(content);
+        if (denial)
+            return denial;
         content.updatedAt = new Date().toISOString();
         // Protect immutable fields
         delete content.createdAt;
         delete content.publicKey; // key rotation goes through dedicated endpoint
+        // Keep the two admin fields agreeing on disk — see resources/agent-admin.ts.
+        // Only an admin can have reached here with a privilege change (see
+        // authorizePrincipalWrite), so this normalises an authorized intent; it
+        // never manufactures one.
+        reconcileAdminFields(content);
         // Write-time originatorInstanceId stamp — see post() above / Memory.ts's
         // stampOriginatorInstanceId doc. No-op if already set.
         if (content.originatorInstanceId == null) {
             content.originatorInstanceId = await localInstanceId();
         }
-        return super.put(content);
+        const result = await super.put(content);
+        invalidateAdminCache();
+        return result;
+    }
+    /**
+     * PATCH → Harper's partial update (`Resource.patch(data, query)`; see
+     * harper/dist/server/REST.js's method switch and Resource.js's static patch).
+     *
+     * This override exists because there was none. Every per-record authorization
+     * rule this resource enforces was written in put(), and PATCH does not route
+     * through put() — so none of those rules ran on a PATCH. allowUpdate() is
+     * allowVerified(), which means the only check a PATCH ever met was "are you
+     * some verified agent"; the rules that make the principal table safe (you may
+     * only edit yourself; you may not change your own admin status) were not
+     * among them.
+     *
+     * That is the shape flair#941 keeps running into: a check that reads as
+     * complete because it exists, and simply is not on the path the caller took.
+     * Both verbs now share authorizePrincipalWrite().
+     */
+    async patch(content, query) {
+        const denial = await this.authorizePrincipalWrite(content);
+        if (denial)
+            return denial;
+        if (content != null && typeof content === "object") {
+            // A partial update must not be able to leave the record's two admin
+            // fields disagreeing, so reconcile against the MERGED result rather than
+            // the patch alone — patching only `role` has to carry the mirror with it.
+            if ("role" in content || "admin" in content) {
+                const existing = await Promise.resolve(super.get()).catch(() => null);
+                const merged = reconcileAdminFields({ ...(existing ?? {}), ...content });
+                content.role = merged.role;
+                content.admin = merged.admin;
+            }
+            // Immutable fields, matching put().
+            delete content.createdAt;
+            delete content.publicKey;
+            content.updatedAt = new Date().toISOString();
+        }
+        const result = await super.patch(content, query);
+        invalidateAdminCache();
+        return result;
     }
 }

package/dist/resources/AgentSeed.js

@@ -17,7 +17,8 @@
  * Auth: admin only.
  */
 import { Resource, databases } from "harper";
-import { isAdmin, allowAdmin } from "./agent-auth.js";
+import { isAdmin, allowAdmin, invalidateAdminCache } from "./agent-auth.js";
+import { reconcileAdminFields } from "./agent-admin.js";
 const DEFAULT_SOUL_KEYS = (agentId, displayName, role, now) => ({
     name: displayName,
     role,
@@ -62,8 +63,15 @@ export class AgentSeed extends Resource {
         const existingAgent = await databases.flair.Agent.get(agentId).catch(() => null);
         let agent = existingAgent;
         if (!existingAgent) {
-            agent = { id: agentId, name, role, publicKey: "pending", createdAt: now, updatedAt: now };
+            // flair#941 — this writes the RAW table, so resources/Agent.ts's post()
+            // never runs and its field reconciliation does not apply here. Seeding
+            // role:"admin" without the mirror was the one path in the product that
+            // produced a genuine administrator every reporter displayed as an
+            // ordinary agent. Admin-only path (allowCreate + the isAdmin re-check
+            // above), so this normalises an authorized intent.
+            agent = reconcileAdminFields({ id: agentId, name, role, publicKey: "pending", createdAt: now, updatedAt: now });
             await databases.flair.Agent.put(agent);
+            invalidateAdminCache();
         }
         // ── Soul entries ──────────────────────────────────────────────────────────
         const defaults = DEFAULT_SOUL_KEYS(agentId, name, role, now);

package/dist/resources/MemoryUsage.js

@@ -95,6 +95,24 @@ export class MemoryUsage extends databases.flair.MemoryUsage {
             return super.put(content);
         return FORBIDDEN("forbidden: MemoryUsage rows are immutable once written");
     }
+    /**
+     * PATCH — same rule as put(), because this ledger's invariant is IMMUTABILITY,
+     * not ownership.
+     *
+     * The shared record-ownership guard (resources/record-owner-guard.ts) covers
+     * this table for cross-agent writes, but it cannot express this rule: it
+     * permits an agent to modify a row it owns, and here even the OWNER must not.
+     * Measured before this override existed: the owning agent rewrote its own
+     * row's attribution with a PATCH and got 204, because Harper routes PATCH to
+     * patch() and put()'s check never ran. A resource whose rule is stricter than
+     * "you own it" still has to say so on every verb.
+     */
+    async patch(content, query) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))
+            return super.patch(content, query);
+        return FORBIDDEN("forbidden: MemoryUsage rows are immutable once written");
+    }
     async delete(id) {
         const auth = await resolveAgentAuth(this.getContext?.());
         if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin))

package/dist/resources/Presence.js

@@ -32,6 +32,7 @@ import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { createRequire } from "node:module";
 import { resolveAgentAuth, verifyAgentRequest } from "./agent-auth.js";
+import { agentRecordIsAdmin } from "./agent-admin.js";
 import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 // ─── Constants ────────────────────────────────────────────────────────────────
 const CURRENT_TASK_MAX_LENGTH = 200;
@@ -348,7 +349,13 @@ export class Presence extends databases.flair.Presence {
                 const entry = {
                     id: agentId,
                     displayName: agent?.displayName ?? agent?.name ?? agentId,
-                    role: agent?.role ?? "agent",
+                    // `role` is a human label on a PUBLIC roster (allowRead() is `true`),
+                    // and it is also the field that decides administrator status
+                    // (resources/agent-admin.ts). Publishing the admin sentinel would
+                    // hand an unauthenticated reader the list of privileged principals —
+                    // so the roster reports admins as ordinary agents. It is a display
+                    // label here and nothing authorizes on it (flair#941).
+                    role: agentRecordIsAdmin(agent) ? "agent" : (agent?.role ?? "agent"),
                     runtime: agent?.runtime ?? null,
                     // Current activity — only truthful while fresh; "idle" once decayed.
                     activity: activityFresh ? rawActivity : "idle",

package/dist/resources/agent-admin.js

@@ -0,0 +1,149 @@
+/**
+ * agent-admin.ts — the ONE answer to "is this principal an administrator?".
+ *
+ * The Agent (Principal) record carries two fields that both read as if they
+ * answered that question:
+ *
+ *   role: String       — administrator when the value is exactly "admin"
+ *   admin: Boolean     — "admin principals can manage other principals"
+ *
+ * They used to be consulted by DIFFERENT consumers, which is the whole defect
+ * (flair#941):
+ *
+ *   - resources/agent-auth.ts's isAdmin() — the single gate behind allowAdmin(),
+ *     and therefore behind every admin-only resource — searched `role` and
+ *     ignored `admin` completely.
+ *   - resources/mcp-handler.ts OR-ed the two together.
+ *   - Every reporter (flair principal show/list, the admin dashboard) displayed
+ *     `admin`, and every writer except AgentSeed wrote `admin`.
+ *
+ * So the field the product wrote and displayed was not the field the gate read.
+ * `flair principal add --admin` stored `admin: true` and granted nothing, while
+ * the dashboard confidently printed "admin: yes" for a principal that
+ * allowAdmin() rejects. Both directions are silent, and one of them is silent in
+ * the direction that flatters the operator.
+ *
+ * ─── The rule ────────────────────────────────────────────────────────────────
+ *
+ * `role === ADMIN_ROLE` is the AUTHORITY. `admin` is a SERVER-MAINTAINED MIRROR
+ * of it and is never read to reach an authorization decision again.
+ *
+ * Every decider and every reporter calls {@link agentRecordIsAdmin}, so no two
+ * surfaces can answer this question differently. Every write through a flair
+ * write path calls {@link reconcileAdminFields}, so a record that says one thing
+ * in one field and the opposite in the other cannot be STORED by any path flair
+ * offers.
+ *
+ * ─── Why `role` is the authority and not `admin` ─────────────────────────────
+ *
+ * `admin: Boolean` is honestly the better-shaped field: typed, indexed,
+ * unambiguous, and already the one every creation path and every UI uses.
+ * Making it the authority would nonetheless GRANT admin, on the primary HTTP
+ * gate, to every record that currently carries `admin: true` with a non-admin
+ * `role` — the records `flair principal add --admin` has been producing all
+ * along, which have never been admins. That is a widening of live access as a
+ * side effect of a consistency fix, decided by data nobody has audited. Keeping
+ * `role` as the authority changes no existing principal's rights on the gate:
+ * every principal that is an admin today is an admin after this change, and
+ * every principal that is not, is not.
+ *
+ * Switching the authority to `admin` is a reasonable follow-up, but it is a
+ * deliberate privilege migration with an audit of existing records — not
+ * something to slip in underneath a naming fix.
+ *
+ * ─── Records that already carry a mismatch ───────────────────────────────────
+ *
+ * Nothing is rewritten in bulk; no migration runs. What happens to each shape:
+ *
+ *   role:"admin" + admin:false|absent  — an admin today, an admin after. The
+ *     mirror is stale, so the CLI and dashboard used to report "not an admin"
+ *     for a principal holding admin rights; they now report the truth. The
+ *     stored mirror is repaired the next time the record is written through the
+ *     Agent resource.
+ *
+ *   admin:true + role not "admin"  — NOT an admin today on the gate, and not
+ *     after. This is what `flair principal add --admin` produced. The CLI and
+ *     dashboard used to report "admin: yes"; they now report the truth, which is
+ *     how an operator finds out the grant never took. The remedy is to re-issue
+ *     the grant (which now writes both fields). The one behaviour that does
+ *     change is the native MCP surface, which used to honour this field on its
+ *     own — see resources/mcp-handler.ts. That surface is gated behind
+ *     FLAIR_MCP_OAUTH and is default-OFF, so no instance running the shipped
+ *     defaults is affected.
+ *
+ * Deliberately dependency-free — pure predicates over a plain record, importing
+ * neither `harper` nor any resource, so the auth gate, the resources, the
+ * reporters and the tests can all share it without an import cycle.
+ */
+/** The exact `role` value that denotes a flair administrator. */
+export const ADMIN_ROLE = "admin";
+/**
+ * THE admin predicate. Every authorization decision and every report of a
+ * principal's admin status resolves through this one function.
+ *
+ * Total over every field combination: a record with a contradictory `admin`
+ * mirror gets the SAME answer here as it does at the gate, so a contradiction
+ * can never produce two different answers on two different surfaces. It is
+ * deliberately NOT an OR over the two fields — see the module header.
+ *
+ * Note this covers Agent RECORDS only. `FLAIR_ADMIN_AGENTS` is a separate,
+ * env-configured admin source union-ed in by resources/agent-auth.ts's
+ * getAdminAgents(); it names agent ids and never touches a record.
+ */
+export function agentRecordIsAdmin(record) {
+    return record?.role === ADMIN_ROLE;
+}
+/**
+ * Make a record about to be written self-consistent, so the two fields can
+ * never be STORED disagreeing.
+ *
+ * Admin is requested by EITHER spelling — `role: "admin"` or `admin: true` —
+ * because both have been documented and both are what an operator reaches for.
+ * Whichever they used, both fields come out of here agreeing. That is what
+ * makes `flair principal add --admin` finally do what it says: it writes the
+ * Boolean, and the Boolean now carries the record into the authority field.
+ *
+ * **Honouring `admin: true` here is not a privilege widening.** Every call site
+ * is already admin-gated — Agent.post() is allowCreate()=allowAdmin, Agent's
+ * update path refuses a privilege change from a non-admin, and AgentSeed is
+ * admin-only and re-checks. A caller that can reach this could have written
+ * `role: "admin"` directly; this only means they no longer have to know which
+ * of the two fields is the real one.
+ *
+ * A non-admin `role` is free text (a human label — "researcher", "COO") and is
+ * left exactly as supplied; only the admin sentinel is normalised.
+ *
+ * Mutates `content` in place and returns it, matching the surrounding
+ * defaults-stamping style in resources/Agent.ts's post().
+ */
+export function reconcileAdminFields(content) {
+    if (!content || typeof content !== "object")
+        return content;
+    // Widened locally: `content` is generic so TypeScript will not accept writes
+    // to named properties on it, but the whole point here is to normalise those
+    // two properties in place and hand the caller back its own object.
+    const record = content;
+    if (record.role === ADMIN_ROLE || record.admin === true) {
+        record.role = ADMIN_ROLE;
+        record.admin = true;
+    }
+    else {
+        record.admin = false;
+    }
+    return content;
+}
+/**
+ * True when a stored record's two fields disagree — i.e. it was written by
+ * something other than a flair write path (a raw table write, an ops-API
+ * insert, a federation merge) and now claims one thing to a reader of `admin`
+ * and the opposite to the gate.
+ *
+ * Reporting-only. Nothing authorizes on this; it exists so a surface can SAY
+ * that a record is inconsistent instead of silently picking a side.
+ */
+export function adminFieldsDisagree(record) {
+    const r = record;
+    if (!r || typeof r !== "object")
+        return false;
+    return agentRecordIsAdmin(r) !== (r.admin === true);
+}

package/dist/resources/agent-auth.js

@@ -17,6 +17,7 @@
  */
 import { databases } from "harper";
 import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
+import { ADMIN_ROLE, agentRecordIsAdmin } from "./agent-admin.js";
 /**
  * Shared Harper user that verified Ed25519 agents resolve to (least-privilege
  * `flair_agent` role), replacing the old admin super_user elevation. Single
@@ -32,8 +33,14 @@ export const FLAIR_AGENT_USERNAME = "flair-agent";
 // visible to the other two, and the crypto/decoder logic can't drift.
 // ─── Admin resolution ─────────────────────────────────────────────────────────
 // Admin agents come from FLAIR_ADMIN_AGENTS (comma-separated) OR Agent records
-// with role === "admin". OR-combined, cached 60s. Distinct from Harper's
-// super_user — admin here gates flair-policy decisions (promotions, raw ops).
+// whose `role` is the admin sentinel. OR-combined, cached 60s. Distinct from
+// Harper's super_user — admin here gates flair-policy decisions (promotions,
+// raw ops).
+//
+// The record half of that union is the ONE place the Agent table is consulted
+// for an authorization decision, and it resolves through
+// resources/agent-admin.ts's shared predicate so it cannot drift from the
+// reporters or from the MCP surface (flair#941 — they had drifted).
 let adminCacheExpiry = 0;
 let adminCache = new Set();
 async function getAdminAgents() {
@@ -43,9 +50,9 @@ async function getAdminAgents() {
     const fromEnv = (process.env.FLAIR_ADMIN_AGENTS ?? "").split(",").map((s) => s.trim()).filter(Boolean);
     const fromDb = [];
     try {
-        const results = await databases.flair.Agent.search([{ attribute: "role", value: "admin", condition: "equals" }]);
+        const results = await databases.flair.Agent.search([{ attribute: "role", value: ADMIN_ROLE, condition: "equals" }]);
         for await (const row of results)
-            if (row?.id)
+            if (row?.id && agentRecordIsAdmin(row))
                 fromDb.push(row.id);
     }
     catch { /* Agent table may be empty */ }
@@ -53,6 +60,28 @@ async function getAdminAgents() {
     adminCacheExpiry = now + 60_000;
     return adminCache;
 }
+/**
+ * Drop the memoised admin set so the NEXT isAdmin() re-reads the Agent table.
+ *
+ * The 60s TTL is a load optimisation, but on its own it makes a privilege
+ * change take up to a minute to appear — which reads as "the change didn't
+ * work", and is exactly the confusion flair#941 is about: an operator grants
+ * admin, tests it, sees a denial, and starts changing other things. The write
+ * path knows precisely when a principal's admin status changed, so it says so
+ * and the grant is effective on the caller's very next request.
+ *
+ * Deliberately NOT a distributed invalidation: Harper runs N worker threads,
+ * each with its own module instance and its own cache, so a promotion applied
+ * on thread A still takes up to the TTL to be seen by thread B. Making that
+ * exact would mean a shared invalidation channel, which is a much larger change
+ * than the confusion warrants — the bound stays 60s, unchanged, and the common
+ * single-threaded/dev case becomes immediate. Called by resources/Agent.ts's
+ * write paths.
+ */
+export function invalidateAdminCache() {
+    adminCacheExpiry = 0;
+    adminCache = new Set();
+}
 export async function isAdmin(agentId) {
     return (await getAdminAgents()).has(agentId);
 }
@@ -195,10 +224,73 @@ export async function allowAdmin(context) {
     const a = await resolveAgentAuth(context);
     return a.kind === "internal" || (a.kind === "agent" && a.isAdmin);
 }
+/**
+ * flair#936 — the `internal` verdict is TRUSTED and UNFILTERED, and it is also
+ * what a caller gets for supplying no context at all. Nothing distinguishes
+ * "I am flair's own maintenance code" from "I am an application developer who
+ * did not know a context was required": both spell it `new Memory()`, both
+ * succeed, and both return plausible data. It surfaces months later as memories
+ * that were never scoped.
+ *
+ * This does not change the verdict — every authorization outcome is byte-
+ * identical — it ends the SILENCE. A deliberate elevated call says so with
+ * `internalContext()` (resources/in-process.ts), whose `__flairInternal` marker
+ * is read here and nowhere else; anything else that lands on `internal` gets one
+ * warning per process, with the stack, so the condition is observable where it
+ * was previously invisible.
+ *
+ * MEASURED, and the reason this is worth having: flair itself has NO in-process
+ * caller that relies on the omission — every maintenance, migration, federation
+ * and boot path goes through the raw `databases.flair.*` table accessor, which
+ * bypasses this resolver entirely rather than defaulting through it. So a
+ * warning from this line is, in practice, always either an embedding
+ * application that forgot a context or a flair call site that should be naming
+ * its intent. Neither is noise.
+ *
+ * The marker is read off `context`, NOT off `c`: `c` is rebound to
+ * `context.request` on the line below, and internalContext() carries the marker
+ * on the outer object.
+ */
+let warnedInternalByOmission = false;
+/**
+ * Was this elevated call DELIBERATE — i.e. did the caller name the authority
+ * with `internalContext()` rather than land on it by leaving a context off?
+ *
+ * Exported because it is the whole decision, and a decision worth testing is
+ * worth testing directly: the warning itself is latched once per process, which
+ * makes any test of the side effect order-dependent (bun shares one module
+ * registry across the whole run, so whichever file resolves a context-less call
+ * first consumes the latch and every later assertion silently passes). Pinning
+ * the predicate instead is deterministic.
+ *
+ * Grants nothing and is never consulted for an authorization decision — the
+ * verdict is identical either way.
+ */
+export function isDeliberateInternalCall(context) {
+    return context?.__flairInternal === true;
+}
+/** The advisory text, exported so its content is pinned without tripping the latch. */
+export const INTERNAL_BY_OMISSION_WARNING = "[flair-auth] a resource was invoked with NO caller context and resolved to the trusted " +
+    "`internal` verdict: reads are UNFILTERED across every agent, writes are unattributed, and " +
+    "the admin-only gate passes. If this is your application's code, pass agentContext(<id>) from " +
+    "@tpsdev-ai/flair's in-process seam so the call is scoped and attributed. If the elevated " +
+    "authority is genuinely intended, say so with internalContext() and this warning will stop. " +
+    "Fires once per process.";
+function noteInternalVerdict(context) {
+    if (warnedInternalByOmission)
+        return;
+    if (isDeliberateInternalCall(context))
+        return; // deliberate, and said so
+    warnedInternalByOmission = true;
+    const stack = (new Error().stack ?? "").split("\n").slice(2, 7).join("\n");
+    console.error(INTERNAL_BY_OMISSION_WARNING + "\n" + stack);
+}
 export async function resolveAgentAuth(context) {
     const c = context?.request ?? context;
-    if (!c)
+    if (!c) {
+        noteInternalVerdict(context);
         return { kind: "internal" };
+    }
     if (c.tpsAnonymous === true)
         return { kind: "anonymous" };
     if (c.tpsAgent) {
@@ -231,5 +323,6 @@ export async function resolveAgentAuth(context) {
             return { kind: "agent", agentId: auth.agentId, isAdmin: auth.isAdmin };
         return { kind: "anonymous" };
     }
+    noteInternalVerdict(context);
     return { kind: "internal" };
 }

package/dist/resources/auth-middleware.js

@@ -4,6 +4,7 @@ import { getEmbedding } from "./embeddings-provider.js";
 import { isAdmin, FLAIR_AGENT_USERNAME } from "./agent-auth.js";
 import { WINDOW_MS, isNonceReplay, recordNonce, importEd25519Key, b64ToArrayBuffer, parseTpsEd25519Header } from "./ed25519-auth.js";
 import { resolveReadScope } from "./memory-read-scope.js";
+import { isForbiddenOwnerMutation, resolveGuardedRecord } from "./record-owner-guard.js";
 // --- Admin credentials ---
 // Admin auth is sourced exclusively from Harper's own environment variables
 // (HDB_ADMIN_PASSWORD / FLAIR_ADMIN_PASSWORD). No filesystem token file.
@@ -350,6 +351,37 @@ server.http(async (request, nextLayer) => {
     // ── Server-side permission guards ──────────────────────────────────────────
     const method = request.method.toUpperCase();
     const isMutation = method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE";
+    // ── THE record-ownership rule, for every table, on every mutating verb ─────
+    //
+    // One enforcement point rather than one per resource. See
+    // resources/record-owner-guard.ts for why this is not written into each
+    // resource's put(): Harper maps verbs to methods one-to-one, so a rule living
+    // in put() is enforced on PUT alone, and nearly every resource wrote its rules
+    // there. Doing this per-resource would be N chances to get one wrong and would
+    // still leave the next resource broken by default.
+    //
+    // Ownership is read from the STORED record named by the path — never from the
+    // request body, which is the caller's claim about who owns the row and was how
+    // a body that simply omitted the field passed unchecked.
+    //
+    // Deliberately scoped to records that ALREADY EXIST: creation is left to each
+    // resource's own no-forge attribution. That keeps this incapable of breaking a
+    // create, a self-write, or a legitimate cross-agent field like MemoryGrant's
+    // granteeId — it can only narrow mutation of another agent's stored row.
+    if (isMutation && !request.tpsAgentIsAdmin) {
+        const guarded = resolveGuardedRecord(url.pathname);
+        if (guarded) {
+            try {
+                const record = await databases.flair[guarded.table]?.get(guarded.id);
+                if (isForbiddenOwnerMutation(record, guarded.ownerField, agentId)) {
+                    return new Response(JSON.stringify({
+                        error: `forbidden: cannot modify ${guarded.table} owned by another principal`,
+                    }), { status: 403, headers: { "Content-Type": "application/json" } });
+                }
+            }
+            catch { /* unreadable row → fall through to the resource's own rules */ }
+        }
+    }
     if (isMutation) {
         // OrgEvent: authorId must match authenticated agent
         if ((url.pathname === "/OrgEvent" || url.pathname.startsWith("/OrgEvent/")) &&
@@ -419,19 +451,59 @@ server.http(async (request, nextLayer) => {
                 catch { }
             }
         }
-        // Soul PUT: only owner or admin
-        if (url.pathname.startsWith("/Soul") && (method === "PUT" || method === "POST")) {
+        // Soul mutations: only the owner or an admin may write a soul entry.
+        //
+        // This guard had two independent holes, either of which alone let one agent
+        // rewrite another's identity data:
+        //
+        //   1. THE VERB LIST enumerated PUT and POST only. Its three siblings above
+        //      (OrgEvent, WorkspaceState, Memory) all include PATCH, and Memory
+        //      includes DELETE; this one did neither. Harper routes PATCH to a
+        //      resource method that carries no ownership check of its own
+        //      (Soul.ts's enforceWriteAuth covers post()/put()), and DELETE reached
+        //      the table with no per-record check at all. Both were live.
+        //
+        //   2. IT COMPARED THE BODY, not the target. `body.agentId` is the owner
+        //      the CALLER claims, and the check only fired when that field was
+        //      present and mismatched — so a body omitting it, which a partial
+        //      write naturally does, was compared against nothing and passed
+        //      whatever record the URL pointed at. The resource-level check behind
+        //      it is "validate-truthy" attribution, which by design also passes an
+        //      ABSENT owner field, so nothing downstream caught it either. (A PUT
+        //      happened to fail anyway, but on `agentId: String!` schema
+        //      validation — a 400 for the wrong reason, not an authorization
+        //      decision, and not a defence to rely on.)
+        //
+        // Closing one hole leaves the other reachable through the remaining verbs,
+        // so both are closed here: every mutating verb is covered, and ownership is
+        // resolved from the STORED RECORD named by the path. That is the same shape
+        // as the Memory ownership guard below, which is the resource in this file
+        // that already had it right — worth copying rather than reinventing.
+        //
+        // The path test stays `startsWith("/Soul")` so sibling routes keep the
+        // body check they already had; the record lookup is scoped to the real
+        // `/Soul/<id>` collection so it never resolves an unrelated id.
+        if (url.pathname.startsWith("/Soul") &&
+            (method === "POST" || method === "PUT" || method === "PATCH" || method === "DELETE")) {
             if (!request.tpsAgentIsAdmin) {
-                let bodyAgentId = null;
-                try {
-                    const clone = request.clone();
-                    const body = await clone.json();
-                    bodyAgentId = body?.agentId ?? null;
-                }
-                catch { }
-                if (bodyAgentId && bodyAgentId !== agentId) {
-                    return new Response(JSON.stringify({ error: "forbidden: non-admin cannot modify another agent's soul" }), { status: 403 });
+                // (a) A PRESENT, mismatched body agentId is a forged attribution.
+                if (method !== "DELETE") {
+                    let bodyAgentId = null;
+                    try {
+                        const clone = request.clone();
+                        const body = await clone.json();
+                        bodyAgentId = body?.agentId ?? null;
+                    }
+                    catch { }
+                    if (bodyAgentId && bodyAgentId !== agentId) {
+                        return new Response(JSON.stringify({ error: "forbidden: non-admin cannot modify another agent's soul" }), { status: 403 });
+                    }
                 }
+                // (b) The owner of the record actually being written — the half that
+                // catches a body simply leaving agentId out — is now the shared
+                // record-ownership rule at the top of this block, which applies it to
+                // every table on every mutating verb. Deliberately NOT repeated here:
+                // one condition enforced in two places is how the two drift apart.
             }
         }
         // Memory promotion guard: only admin can approve or set durability=permanent
@@ -453,21 +525,22 @@ server.http(async (request, nextLayer) => {
                 catch { }
             }
         }
-        // Memory PUT/DELETE: ownership check (non-admin can only modify their own memories)
+        // Memory DELETE: permanent memories are admin-only to purge.
+        //
+        // The OWNERSHIP half of this guard — which was the model the shared
+        // record-ownership rule above was built from, and the only one in this file
+        // that already covered PATCH — now lives there and covers every table. What
+        // remains here is the part that is NOT about ownership: durability. An agent
+        // owning a permanent memory still may not purge it.
         if (((url.pathname === "/Memory" || url.pathname.startsWith("/Memory/") || url.pathname === "/memory" || url.pathname.startsWith("/memory/"))) &&
-            (method === "PUT" || method === "DELETE" || method === "PATCH")) {
+            method === "DELETE") {
             if (!request.tpsAgentIsAdmin) {
                 try {
                     const pathParts = url.pathname.split("/").filter(Boolean);
                     const memId = pathParts[1] ? decodeURIComponent(pathParts[1]) : null;
                     if (memId) {
                         const record = await databases.flair.Memory.get(memId);
-                        if (record && record.agentId && record.agentId !== agentId) {
-                            return new Response(JSON.stringify({
-                                error: `forbidden: cannot modify memory owned by ${record.agentId}`
-                            }), { status: 403 });
-                        }
-                        if (method === "DELETE" && record?.durability === "permanent") {
+                        if (record?.durability === "permanent") {
                             return new Response(JSON.stringify({
                                 error: "forbidden: only admins can purge permanent memories"
                             }), { status: 403 });

package/dist/resources/in-process.js

@@ -208,6 +208,15 @@ export function internalContext() {
  * Reads do not need this — `Cls.get(id, context)` and `Cls.search(query,
  * context)` (Harper's static resource methods) already thread the context and
  * start their own transaction.
+ *
+ * **They do still need the CONTEXT.** Only the collection binding is
+ * unnecessary for a read, not the identity. `Cls.search(query)` with the second
+ * argument left off does not read "as nobody" — outside a Harper request scope
+ * (a boot hook, a timer, a queue worker, a detached promise) it resolves to the
+ * same trusted `internal` verdict this module exists to keep out of reach, and
+ * returns every agent's private records unfiltered. On that path the resource's
+ * own `allow*` gate is not consulted at all, so nothing else stands in the way.
+ * Pass the context to every call, read or write (flair#936).
  */
 export async function collectionResource(Cls, context) {
     if (context == null || typeof context !== "object") {

package/dist/resources/mcp-handler.js

@@ -26,6 +26,7 @@
 import { databases } from "harper";
 import { randomBytes } from "node:crypto";
 import { TOOLS, listToolDefs } from "./mcp-tools.js";
+import { agentRecordIsAdmin } from "./agent-admin.js";
 // The MCP protocol revision we implement (initialize handshake).
 const PROTOCOL_VERSION = "2025-06-18";
 const JSON_HEADERS = { "content-type": "application/json" };
@@ -157,14 +158,23 @@ async function jitProvisionPrincipal(sub) {
     return principalId;
 }
 /**
- * Is this Principal a flair admin? Reads the Agent record's `admin`/`role`
- * fields. A MCP-OAuth agent is NON-admin unless an operator has explicitly
- * marked its Agent record admin — the MCP surface never elevates on its own.
+ * Is this Principal a flair admin? A MCP-OAuth agent is NON-admin unless an
+ * operator has explicitly marked its Agent record admin — the MCP surface never
+ * elevates on its own.
+ *
+ * flair#941: this used to OR the two admin fields together while the primary
+ * HTTP gate (resources/agent-auth.ts's isAdmin) read only `role`, so the same
+ * record could be an administrator here and an ordinary agent there. It now
+ * resolves through the one shared predicate, so both surfaces answer
+ * identically. A record carrying `admin: true` alone — which no flair write
+ * path produces, and which was never an admin on the HTTP gate — is no longer
+ * an admin here either; see resources/agent-admin.ts for the remedy. This
+ * surface is gated behind FLAIR_MCP_OAUTH and is default-OFF.
  */
 async function isAgentAdmin(principalId) {
     try {
         const agent = await databases.flair.Agent.get(principalId);
-        return agent?.admin === true || agent?.role === "admin";
+        return agentRecordIsAdmin(agent);
     }
     catch {
         return false;

package/dist/resources/presence-internal.js

@@ -2,7 +2,12 @@ function presenceDelegationContext(auth) {
     const agentAuth = auth.kind === "agent"
         ? { agentId: auth.agentId, isAdmin: auth.isAdmin }
         : { agentId: "internal", isAdmin: true };
-    return { request: { _flairAgentAuth: agentAuth } };
+    // `__flairInternal` marks the `internal` branch as DELIBERATE (flair#936) —
+    // an "internal" verdict relayed here is a trusted in-process call this file
+    // has already established, not a caller who forgot to pass a context. It is
+    // read only by resources/agent-auth.ts's accidental-omission warning; it
+    // grants nothing and is never consulted for an authorization decision.
+    return { request: { _flairAgentAuth: agentAuth }, __flairInternal: true };
 }
 /**
  * The full presence roster (one row per agent — bounded, per the K&S

package/dist/resources/record-owner-guard.js

@@ -0,0 +1,149 @@
+/**
+ * record-owner-guard.ts — ONE enforcement point for "you may not modify a
+ * record you do not own".
+ *
+ * ─── The defect this deletes ─────────────────────────────────────────────────
+ *
+ * Harper's REST layer maps verbs to resource methods ONE-TO-ONE (see
+ * harper/dist/server/REST.js's method switch): GET→get, POST→post, PUT→put,
+ * PATCH→patch, DELETE→delete. There is no fallback — `patch()` does NOT route
+ * through `put()`. So an ownership rule written inside a resource's `put()` is
+ * enforced on PUT and on nothing else, and a resource with no `patch()` override
+ * reaches the table with only its `allow*` gate, which is typically
+ * `allowVerified()` — "any verified agent".
+ *
+ * Almost every flair resource wrote its per-record rules in `put()`. That is not
+ * a mistake anyone made once; it is what the resource model invites, because
+ * `put()` is where the write logic naturally goes and nothing anywhere says the
+ * other verbs exist. Fixing it resource-by-resource would mean N hand-written
+ * guards — N chances to get one subtly wrong — and would still leave the NEXT
+ * resource broken by default, because its author would have to know this file
+ * exists to be safe. So the rule lives here instead, once, on the path every
+ * HTTP request already takes.
+ *
+ * ─── The rule, and why it is this narrow ─────────────────────────────────────
+ *
+ *   On a record that ALREADY EXISTS, a non-admin caller whose agent id does not
+ *   match the record's stored owner is refused — on every mutating verb.
+ *
+ * It deliberately says nothing about creation. Over-blocking is the failure mode
+ * a security fix reaches for, and a blunter rule ("the caller must own whatever
+ * it names") would break real flows: Presence heartbeats arrive at the
+ * collection with no record yet, credential provisioning creates rows for other
+ * principals, and a MemoryGrant's `granteeId` is SUPPOSED to be someone else.
+ * Restricting this to records that exist means the guard can only ever narrow
+ * mutation of another agent's data. It cannot break a create, and it cannot
+ * break an agent writing its own record.
+ *
+ * ─── Owner is read from STORED STATE, never from the request body ────────────
+ *
+ * The guards this replaces compared the owner field in the request BODY — the
+ * owner the CALLER CLAIMS — and denied only when that field was present and
+ * mismatched. A body that simply omitted it was compared against nothing and
+ * passed, whatever record the URL named. Harper binds the write to the URL's id,
+ * not to the body, so body-derived authorization was answering a question nobody
+ * asked. That is the same defect as the verb gap wearing different clothes: an
+ * authorization decision made against attacker-supplied data instead of stored
+ * state. Both are closed here, together, because closing one leaves the other
+ * reachable.
+ *
+ * Per-resource body checks (no-forge attribution on CREATE) still belong in the
+ * resources — they answer a different question, "may you attribute a NEW record
+ * to someone else", which this guard does not address.
+ *
+ * ─── Keeping this honest as the codebase grows ───────────────────────────────
+ *
+ * OWNER_FIELDS below is static and PR-reviewed, matching the posture of
+ * resources/record-types.ts. A static map alone would rot, so
+ * test/unit/record-owner-guard-coverage.test.ts parses `schemas/*.graphql` and
+ * FAILS when a table declares an owner-shaped column and is neither listed here
+ * nor exempted with a stated reason. A table added later enters that test's
+ * scope the moment it declares the column — nobody has to know this file exists.
+ */
+/**
+ * Table → the attribute naming the principal that owns a row.
+ *
+ * Derived from the columns actually declared in `schemas/*.graphql`, and pinned
+ * against them by the coverage test. Tables with no resource class are listed
+ * anyway: costing nothing when the route does not exist is much better than
+ * being absent on the day someone adds one.
+ */
+export const OWNER_FIELDS = Object.freeze({
+    Credential: "principalId",
+    Integration: "agentId",
+    Memory: "agentId",
+    MemoryCandidate: "agentId",
+    MemoryGrant: "ownerId",
+    MemoryUsage: "agentId",
+    OAuthAuthCode: "principalId",
+    OAuthToken: "principalId",
+    OrgEvent: "authorId",
+    Presence: "agentId",
+    Relationship: "agentId",
+    Soul: "agentId",
+    WorkspaceState: "agentId",
+});
+/**
+ * Tables that declare an owner-shaped column but are deliberately NOT guarded
+ * here, each with the reason. The coverage test accepts these and rejects
+ * anything else, so an omission has to be argued rather than merely happen.
+ */
+export const OWNER_GUARD_EXEMPT = Object.freeze({
+    // The principal table's own rule is "the record IS the caller", not "the
+    // record has an owner column" — a principal may edit itself, and only an
+    // admin may change anyone's admin status. That is enforced in
+    // resources/Agent.ts's shared write-authorization helper, which both its
+    // put() and its patch() route through.
+    Agent: "self-ownership by primary key; enforced in resources/Agent.ts for every verb",
+});
+/** The verbs that can mutate a record, and therefore need the rule applied. */
+export const MUTATING_METHODS = Object.freeze(["POST", "PUT", "PATCH", "DELETE"]);
+export function isMutatingMethod(method) {
+    return MUTATING_METHODS.includes(method.toUpperCase());
+}
+/**
+ * Resolve a request path to the guarded table and record id it addresses, or
+ * null when the path is not a guarded single-record route.
+ *
+ * Matches `/<Table>/<id>` ONLY. A collection path (`/<Table>`) addresses no
+ * existing record, so there is nothing to own and nothing to check — that is the
+ * "creation is untouched" property, expressed as a parse rather than a special
+ * case. The table segment is matched EXACTLY so `/SoulFeed/x` can never be read
+ * as a `Soul` route.
+ */
+export function resolveGuardedRecord(pathname) {
+    const parts = pathname.split("/").filter(Boolean);
+    if (parts.length < 2)
+        return null;
+    const table = parts[0];
+    const ownerField = OWNER_FIELDS[table];
+    if (!ownerField)
+        return null;
+    let id;
+    try {
+        id = decodeURIComponent(parts[1]);
+    }
+    catch {
+        return null; // malformed percent-encoding addresses no record we can resolve
+    }
+    if (!id)
+        return null;
+    return { table, ownerField, id };
+}
+/**
+ * Decide whether a caller may mutate an already-stored record.
+ *
+ * Pure, so the decision is testable without a Harper instance — the middleware
+ * supplies the record it loaded. A record that does not exist, or that carries
+ * no owner value, is NOT refused here: the first is a create (or a 404 the
+ * resource will produce), and the second is a row with nothing to own, neither
+ * of which this rule is about.
+ */
+export function isForbiddenOwnerMutation(record, ownerField, callerAgentId) {
+    if (!record)
+        return false;
+    const owner = record[ownerField];
+    if (owner == null || owner === "")
+        return false;
+    return owner !== callerAgentId;
+}

package/docs/embedding-in-a-harper-app.md

@@ -54,6 +54,8 @@ export async function remember(agentId, content, opts = {}) {
 > ```
 >
 > `collectionResource(Cls, context)` is a two-line wrapper over the supported call — `Cls.getResource({}, context, { isCollection: true })` — and exists so this is written once. **Reads do not need it:** `Cls.get(id, context)` and `Cls.search(query, context)` thread the context themselves.
+>
+> They do still need the **context**. Only the collection binding is unnecessary for a read, never the identity — `Cls.search(query)` with the second argument left off resolves to the trusted `internal` verdict when it runs outside a request scope (a boot hook, a timer, a queue worker, a detached promise) and returns every agent's private records. On that path the resource's `allow*` gate is not consulted at all. Pass the context to every call, read and write.
 
 > ### ⚠️ A resource with no context is an administrator
 >
@@ -124,7 +126,7 @@ export async function registerAgent(id, { publicKey = "pending", admin = false }
     id, name: id, displayName: id,
     publicKey,                            // a placeholder is fine — see below
     runtime: "headless",
-    ...(admin ? { role: "admin", admin: true } : {}),   // role is what actually grants admin
+    ...(admin ? { admin: true } : {}),    // sets role:"admin" too — see below
   });
 }
 ```
@@ -133,7 +135,9 @@ Verified against a real instance: that lands `kind: "agent"`, `status: "active"`
 
 > **Prefer this to `databases.flair.Agent.put()`.** The raw table applies **no** defaults, so a hand-written literal has to reproduce every field above and then stay in step with Flair as the Principal model grows. Records written that way are missing `kind`/`status`/`defaultTrustTier` and read as under-specified Principals in the admin surfaces.
 
-> **`isAdmin()` reads `role === "admin"`, not the `admin` boolean.** They are separate fields and only `role` grants admin rights; set both to keep the record self-consistent. Admin lookups are cached for 60 seconds, so a newly-created admin is not effective immediately.
+> **Admin is one meaning with one answer.** `role === "admin"` is the authority; the `admin` boolean is a mirror of it that the server maintains. Write **either** through the `Agent` resource and both are set — you no longer have to know which one is real, and a record cannot be stored saying one thing in one field and the opposite in the other. Nothing reads the mirror to make an authorization decision, and a promotion applied through the resource takes effect on the next request rather than after the 60-second admin-lookup cache expires.
+>
+> A record written straight to the table (`databases.flair.Agent.put()`, an ops-API insert, a federation merge) skips that reconciliation and can still carry a mismatch. `flair principal show` and the admin dashboard flag such a record rather than silently picking a side; re-issuing the grant repairs it.
 
 `publicKey` is non-nullable in the schema, but it does not have to be a real key. An agent that only ever acts in-process never authenticates, and Flair's own paths write placeholders — `"pending"` when seeding, `mcp-oauth:<sub>` for token-authenticated agents. Give an agent a real key only if it must also authenticate **over HTTP**, which your app can do without any CLI:
 

package/docs/upgrade.md

@@ -188,7 +188,7 @@ FABRIC_USER=<admin> FABRIC_PASSWORD=<pass> \
 
 (or `--fabric-password-file <path>` instead of the `FABRIC_PASSWORD` env var — reads the
 password from a file, chmod 600). This resolves the target version (latest published
-`@tpsdev-ai/flair`, or pin one with `--version`), stages a clean deployable with the
+`@tpsdev-ai/flair`, or pin one with `--flair-version`), stages a clean deployable with the
 required `harper` version pin applied (`--harper-version` to override),
 confirms the staged Harper build before deploying, then reuses `flair deploy` to push it
 and verifies the result. `--check` shows the version diff and plan without deploying

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.31.0",
+  "version": "0.31.1",
   "packageManager": "bun@1.3.10",
   "description": "Identity, memory, and soul for AI agents. Cryptographic identity (Ed25519), semantic memory with local embeddings, and persistent personality — all in a single process.",
   "type": "module",