@tpsdev-ai/flair 0.44.3 → 0.44.4

package/dist/cli.js

@@ -26,6 +26,7 @@ import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMc
 import { readClientMcpBlock, checkClaudeMdBootstrap, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, inferSoleAgentId, fixCommandAgentHint, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, } from "./doctor-client.js";
 import { installHook, uninstallHook, hookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
 import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, KeyLoadError, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
+import { resolveSigningIdentity, emitSigningIdentityDebug, } from "./lib/signing-identity.js";
 import { validateSnapshotArchive, extractSnapshotSafely } from "./lib/safe-snapshot-extract.js";
 import { escapeXml, unescapeXml } from "./lib/xml-escape.js";
 import { assessLaunchdManagement, diagnoseLaunchdPlistPaths, isDetached, pickInstancePid, renderDetachedWarning, renderVerifiedSummary, LAUNCHCTL_QUERY_TIMEOUT_MS, } from "./lib/launchd-management.js";
@@ -638,10 +639,47 @@ function resolveBaseUrl(opts) {
         || process.env.FLAIR_URL
         || `http://127.0.0.1:${resolveHttpPort(opts)}`);
 }
-// Resolve agent id from --agent flag or FLAIR_AGENT_ID env.
-// Returns null if neither is set; caller decides whether that's fatal.
+// Resolve agent id from --agent flag or FLAIR_AGENT_ID env (flag > env).
+// The low-level helper with no debug line — used where only the flag/env pair
+// is wanted (e.g. the upgrade path that then applies its own key-dir floor).
+// Delegates to the canonical core so the flag>env precedence lives in exactly
+// one place (flair#1183). Returns null if neither is set; caller decides
+// whether that's fatal.
 function resolveAgentIdOrEnv(opts) {
-    return opts.agent || process.env.FLAIR_AGENT_ID || null;
+    return resolveSigningIdentity(opts).agentId;
+}
+// ── The ONE signing-identity seam every user-facing command family calls ──────
+//
+// Precedence (flair#1183): --agent flag > FLAIR_AGENT_ID env > config profile.
+//
+// This seam pins the top two tiers — the flag and the env — and resolves the
+// signer ONCE, at the command boundary, threading the result down to
+// api()/authedRequest as an AUTHORITATIVE value. That is the whole fix: a lower
+// layer must never re-derive the signer from the environment behind the
+// command's back (api() used to, signing as FLAIR_AGENT_ID even when --agent
+// named someone else).
+//
+// The third tier — the "config profile" — is the machine's ambient credential
+// (the ~/.flair/admin-pass file and the Ed25519 agent-key FLOOR), applied BELOW
+// this by authedRequest (src/lib/auth-resolve.ts tiers 4-5) when this seam
+// resolves nothing. It is deliberately NOT a name lookup here: making a
+// forgotten --agent silently resolve to some configured identity is the exact
+// silent-substitution this issue is about, and it would also turn every
+// "identity required" command into one that guesses. So when neither flag nor
+// env is set this returns null, and the caller either demands an explicit
+// identity (agent-scoped commands) or lets authedRequest apply the ambient
+// config-profile credential. Emits the FLAIR_DEBUG line naming the resolved
+// agentId + which source won, so operator, CLI, and server cannot silently
+// disagree about who's calling.
+function resolveSigningIdentityFor(opts, command) {
+    const resolved = resolveSigningIdentity(opts);
+    emitSigningIdentityDebug(resolved, command);
+    return resolved;
+}
+// Same seam, returning just the agentId (or null) for the common call site that
+// only needs the id. Still emits the debug line via resolveSigningIdentityFor.
+function resolveSigningAgentId(opts, command) {
+    return resolveSigningIdentityFor(opts, command).agentId;
 }
 // Ops port resolution: --ops-port flag > FLAIR_OPS_PORT env > config opsPort > httpPort - 1
 //
@@ -1336,10 +1374,23 @@ function b64url(bytes) {
  * api() resolves the request's Harper HTTP/REST auth via the shared
  * `authedRequest` (src/lib/auth-resolve.ts — see that module's header for
  * the full 5-tier resolution order, including tier 5, the Ed25519 agent-key
- * FLOOR this used to lack entirely). The only thing api() itself still owns
- * is Harper-CLI-convention agentId extraction (FLAIR_AGENT_ID env, or an
- * agentId embedded in the request body/query string) — request-shape
- * knowledge that belongs here, not in the generic resolver.
+ * FLOOR this used to lack entirely).
+ *
+ * SIGNING IDENTITY (flair#1183): a caller that has already resolved the signer
+ * — every user-facing command does, via `resolveSigningAgentId` (flag > env >
+ * config profile) — passes it as `options.agentId`, and that value is
+ * AUTHORITATIVE. api() does NOT re-derive it from the environment in that case.
+ * That re-derivation was the bug: api() used to compute the signer as
+ * `FLAIR_AGENT_ID env > body.agentId`, so a command run with `--agent X` while
+ * `FLAIR_AGENT_ID=Y` was exported signed as Y — inverting the documented
+ * precedence and silently disagreeing with the record/query, which both named X.
+ *
+ * Only when the caller passes NO agentId (the `"agentId" in options` check
+ * distinguishes an omitted key from an explicit `null`) does api() fall back to
+ * the legacy request-shape extraction — FLAIR_AGENT_ID env, then an agentId
+ * embedded in the body/query string. That path serves the admin/federation
+ * callers that resolve no identity of their own and lean on admin-pass / the
+ * floor, so their behavior is unchanged.
  *
  * NOTE: this function is for the Harper HTTP/REST API only. The Harper
  * operations API (used by seedAgentViaOpsApi / seedFederationInstanceViaOpsApi)
@@ -1355,14 +1406,24 @@ async function api(method, path, body, options) {
     // Resolve port via the canonical path (flair#1129): options.baseUrl > FLAIR_URL > resolveHttpPort.
     // api() callers mean the default install, so resolveHttpPort({}) with no --data-dir is correct.
     const base = options?.baseUrl ?? (process.env.FLAIR_URL || `http://127.0.0.1:${resolveHttpPort({})}`);
-    // Extract agentId from FLAIR_AGENT_ID env, or the body (POST/PUT) / URL
-    // query params (GET) — Harper-CLI-request-shape knowledge, not a generic
-    // auth concern, so it stays here rather than in authedRequest.
-    let agentId = process.env.FLAIR_AGENT_ID || (body && typeof body === "object" ? body.agentId : undefined);
-    if (!agentId && path.includes("agentId=")) {
-        const match = path.match(/agentId=([^&]+)/);
-        if (match)
-            agentId = decodeURIComponent(match[1]);
+    let agentId;
+    if (options && "agentId" in options) {
+        // The caller resolved the signing identity (flag > env > config profile)
+        // and it is AUTHORITATIVE — never override it with FLAIR_AGENT_ID here
+        // (that inversion is flair#1183). An explicit null means "no identity
+        // resolved"; honor it and let authedRequest fall to admin-pass / the floor.
+        agentId = options.agentId ?? undefined;
+    }
+    else {
+        // Legacy request-shape extraction for callers that resolve no identity of
+        // their own (admin/federation ops): FLAIR_AGENT_ID env, then the body
+        // (POST/PUT) / URL query params (GET).
+        agentId = process.env.FLAIR_AGENT_ID || (body && typeof body === "object" ? body.agentId : undefined);
+        if (!agentId && path.includes("agentId=")) {
+            const match = path.match(/agentId=([^&]+)/);
+            if (match)
+                agentId = decodeURIComponent(match[1]);
+        }
     }
     return authedRequest(method, path, body, { baseUrl: base, agentId, keysDir: options?.keysDir });
 }
@@ -7949,7 +8010,12 @@ export async function discoverLocalFlairPort(originalUrl) {
     }
     return null;
 }
-async function fetchHealthDetail(opts) {
+// flair#1183: `signingAgentIdOverride` lets a calling command that already
+// resolved a signing identity via the canonical seam (resolveSigningAgentId)
+// pass it in, so this verified read signs as the SAME agent the rest of the
+// command does. Undefined = resolve locally via the legacy flag>env pair (all
+// other callers, unchanged).
+async function fetchHealthDetail(opts, signingAgentIdOverride) {
     const port = resolveHttpPort(opts);
     // --target takes precedence, then --url, then FLAIR_TARGET, then FLAIR_URL, then localhost
     const baseUrl = opts.target || opts.url || process.env.FLAIR_TARGET || (process.env.FLAIR_URL ?? `http://127.0.0.1:${port}`);
@@ -7982,7 +8048,9 @@ async function fetchHealthDetail(opts) {
         try {
             healthData = await authedRequest("GET", "/HealthDetail", undefined, {
                 baseUrl,
-                agentId: opts.agent || process.env.FLAIR_AGENT_ID,
+                agentId: signingAgentIdOverride !== undefined
+                    ? (signingAgentIdOverride ?? undefined)
+                    : (opts.agent || process.env.FLAIR_AGENT_ID),
             });
         }
         catch {
@@ -8001,7 +8069,8 @@ const statusCmd = program
     .option("--json", "Output as JSON")
     .option("--agent <id>", "Agent ID for authenticated detail (or set FLAIR_AGENT_ID)")
     .action(async (opts) => {
-    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts);
+    const statusAgentId = resolveSigningAgentId(opts, "status");
+    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts, statusAgentId);
     // When unreachable on a localhost URL, probe candidate ports to detect
     // config-vs-daemon port drift. Surface the actually-listening
     // port with a fix recipe — better UX than just "unreachable."
@@ -12861,7 +12930,7 @@ async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
     let all;
     try {
         const q = new URLSearchParams({ agentId }).toString();
-        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl });
+        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl, agentId });
         all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
     }
     catch (err) {
@@ -12888,7 +12957,7 @@ async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
             const id = String(m.id);
             const cue = deriveRecallCue(m);
             const body = { agentId, q: cue, limit: k };
-            const res = await api("POST", "/SemanticSearch", body, { baseUrl });
+            const res = await api("POST", "/SemanticSearch", body, { baseUrl, agentId });
             const results = Array.isArray(res) ? res : (res?.results ?? []);
             sampledIds.push(id);
             perQueryResultIds.push(results.map((r) => String(r.id)));
@@ -13103,7 +13172,7 @@ async function fetchPreviousQualitySnapshot(agentId, baseUrl, subject) {
     let all;
     try {
         const q = new URLSearchParams({ agentId }).toString();
-        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl });
+        const raw = await api("GET", `/Memory?${q}`, undefined, { baseUrl, agentId });
         all = Array.isArray(raw) ? raw : (raw?.results ?? raw?.items ?? []);
     }
     catch {
@@ -13146,7 +13215,7 @@ async function storeQualitySnapshot(agentId, baseUrl, subject, snapshot) {
         type: "quality-snapshot",
         createdAt: new Date().toISOString(),
     };
-    const out = await api("PUT", `/Memory/${encodeURIComponent(memId)}`, body, { baseUrl });
+    const out = await api("PUT", `/Memory/${encodeURIComponent(memId)}`, body, { baseUrl, agentId });
     if (out?.error)
         throw new Error(String(out.error));
     return memId;
@@ -13162,8 +13231,8 @@ program
     .option("--agent <id>", "Scope per-agent metrics to one agent id (or set FLAIR_AGENT_ID); default = all agents")
     .option("--emit", "Slice 2: snapshot this report, diff it against the previous quality-snapshot memory, and emit OrgEvents (quality.threshold_crossed / quality.regression) for any crossings/regressions found. Requires an agent identity (--agent or FLAIR_AGENT_ID) — the opt-in write boundary; without this flag `flair quality` remains fully read-only")
     .action(async (opts) => {
-    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts);
-    const agentId = opts.agent || process.env.FLAIR_AGENT_ID || null;
+    const agentId = resolveSigningAgentId(opts, "quality");
+    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts, agentId);
     if (opts.emit && !agentId) {
         console.error("Error: --emit requires an agent identity. Pass --agent <id> or set FLAIR_AGENT_ID.");
         process.exit(1);
@@ -13549,6 +13618,7 @@ memory.command("add [content]")
         console.error("error: content required (positional arg or --content)");
         process.exit(1);
     }
+    const agentId = resolveSigningAgentId(opts, "memory add") ?? opts.agent;
     const memId = `${opts.agent}-${Date.now()}`;
     const body = {
         id: memId, agentId: opts.agent, content, durability: opts.durability || "standard",
@@ -13577,7 +13647,7 @@ memory.command("add [content]")
     if (opts.derivedFrom) {
         body.derivedFrom = String(opts.derivedFrom).split(",").map((x) => x.trim()).filter(Boolean);
     }
-    const out = await api("PUT", `/Memory/${memId}`, body);
+    const out = await api("PUT", `/Memory/${memId}`, body, { agentId });
     console.log(JSON.stringify(out, null, 2));
 });
 // ─── flair memory write-task-summary ────────────────────────────────────────
@@ -13632,6 +13702,7 @@ memory.command("write-task-summary")
         lines.push(opts.summary);
     }
     const content = lines.join("\n");
+    const agentId = resolveSigningAgentId(opts, "memory write-task-summary") ?? opts.agent;
     const memId = `${opts.agent}-task-${opts.beads}-${Date.now()}`;
     const body = {
         id: memId,
@@ -13648,7 +13719,7 @@ memory.command("write-task-summary")
     if (opts.derivedFrom) {
         body.derivedFrom = String(opts.derivedFrom).split(",").map((x) => x.trim()).filter(Boolean);
     }
-    const out = await api("PUT", `/Memory/${encodeURIComponent(memId)}`, body);
+    const out = await api("PUT", `/Memory/${encodeURIComponent(memId)}`, body, { agentId });
     if (out?.error) {
         console.error(`Error writing task summary: ${out.error}`);
         process.exit(1);
@@ -13667,7 +13738,7 @@ memory.command("search [query]")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--port <port>", "Harper HTTP port")
     .action(async (queryArg, opts) => {
-    const agentId = resolveAgentIdOrEnv(opts);
+    const agentId = resolveSigningAgentId(opts, "memory search");
     if (!agentId) {
         console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
         process.exit(2);
@@ -13681,7 +13752,7 @@ memory.command("search [query]")
     if (opts.tag)
         body.tag = opts.tag;
     const baseUrl = resolveBaseUrl(opts);
-    const res = await api("POST", "/SemanticSearch", body, { baseUrl });
+    const res = await api("POST", "/SemanticSearch", body, { baseUrl, agentId });
     console.log(JSON.stringify(res, null, 2));
 });
 memory.command("list")
@@ -13692,13 +13763,13 @@ memory.command("list")
     .option("--limit <n>", "Max rows when using --hash-fallback", "50")
     .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
-    const agentId = resolveAgentIdOrEnv(opts);
+    const agentId = resolveSigningAgentId(opts, "memory list");
     if (!agentId) {
         console.error(`${render.icons.error} --agent <id> required (or set FLAIR_AGENT_ID)`);
         process.exit(2);
     }
     const q = new URLSearchParams({ agentId, ...(opts.tag ? { tag: opts.tag } : {}) }).toString();
-    const raw = await api("GET", `/Memory?${q}`);
+    const raw = await api("GET", `/Memory?${q}`, undefined, { agentId });
     const mode = render.resolveOutputMode(opts);
     // hashFallback flag changes the lens: instead of all memories, show
     // only those that need re-embedding. Keep that surface separate.
@@ -14030,7 +14101,7 @@ program
     .option("--json", "Output raw JSON array")
     .action(async (query, opts) => {
     try {
-        const agentId = resolveAgentIdOrEnv(opts);
+        const agentId = resolveSigningAgentId(opts, "search");
         if (!agentId) {
             console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
             process.exit(2);
@@ -14190,7 +14261,7 @@ program
     .option("--key <path>", "Ed25519 private key path")
     .option("--json", "Emit JSON {context, tokenEstimate, memoriesIncluded, ...} (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
-    const agentId = resolveAgentIdOrEnv(opts);
+    const agentId = resolveSigningAgentId(opts, "bootstrap");
     if (!agentId) {
         console.error(`${render.icons.error} --agent <id> required (or set FLAIR_AGENT_ID)`);
         process.exit(2);
@@ -14279,6 +14350,7 @@ relationship.command("add")
     .option("--valid-to <iso>", "ISO timestamp this relationship ended (leave unset for an active relationship)")
     .option("--source <text>", "Where this was learned from (a memory ID, conversation, etc.)")
     .action(async (opts) => {
+    const agentId = resolveSigningAgentId(opts, "relationship add") ?? opts.agent;
     const id = canonicalRelationshipId(opts.agent, opts.subject, opts.predicate, opts.object);
     const body = {
         id,
@@ -14295,7 +14367,7 @@ relationship.command("add")
         body.validTo = opts.validTo;
     if (opts.source)
         body.source = opts.source;
-    const out = await api("PUT", `/Relationship/${id}`, body);
+    const out = await api("PUT", `/Relationship/${id}`, body, { agentId });
     console.log(JSON.stringify(out, null, 2));
 });
 const soul = program.command("soul").description("Manage agent soul entries");
@@ -14310,6 +14382,13 @@ soul.command("set")
     // PUT /Soul/{agentId:key} (upsert by id), matching flair-client's soul.set().
     // The Soul table resource has no POST handler, so a collection POST /Soul
     // 405s; the record must be written by its primary key. (#498)
+    //
+    // flair#1183: resolve the SIGNING identity through the canonical seam and
+    // thread it to api(). --agent is required, so the flag always wins the
+    // precedence — but before this, api() re-derived the signer as
+    // FLAIR_AGENT_ID-first, so `soul set --agent X` with FLAIR_AGENT_ID=Y set
+    // wrote a record owned by X while signing as Y (the soul family's stale rung).
+    const agentId = resolveSigningAgentId(opts, "soul set") ?? opts.agent;
     const id = `${opts.agent}:${opts.key}`;
     const out = await api("PUT", `/Soul/${encodeURIComponent(id)}`, {
         id,
@@ -14318,7 +14397,7 @@ soul.command("set")
         value: opts.value,
         durability: opts.durability,
         createdAt: new Date().toISOString(),
-    });
+    }, { agentId });
     const mode = render.resolveOutputMode(opts);
     if (mode === "json") {
         console.log(render.asJSON(out));
@@ -14334,9 +14413,14 @@ soul.command("set")
 soul.command("get")
     .description("Fetch a single soul entry by id (agent:key)")
     .argument("<id>")
+    .option("--agent <id>", "Agent ID to sign the read as (or set FLAIR_AGENT_ID); falls back to the config-profile agent")
     .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (id, opts) => {
-    const out = await api("GET", `/Soul/${id}`);
+    // flair#1183: /Soul reads are verified (any registered agent). Resolve the
+    // signer through the canonical seam so soul get honors the SAME precedence
+    // as every other family; a null result lets api() fall to admin-pass/floor.
+    const agentId = resolveSigningAgentId(opts, "soul get");
+    const out = await api("GET", `/Soul/${id}`, undefined, { agentId });
     const mode = render.resolveOutputMode(opts);
     if (mode === "json") {
         console.log(render.asJSON(out));
@@ -14368,12 +14452,12 @@ soul.command("list")
     .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
     .option("--json", "Emit raw JSON array (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
-    const agentId = resolveAgentIdOrEnv(opts);
+    const agentId = resolveSigningAgentId(opts, "soul list");
     if (!agentId) {
         console.error(`${render.icons.error} --agent <id> required (or set FLAIR_AGENT_ID)`);
         process.exit(2);
     }
-    const out = await api("GET", `/Soul?agentId=${encodeURIComponent(agentId)}`);
+    const out = await api("GET", `/Soul?agentId=${encodeURIComponent(agentId)}`, undefined, { agentId });
     const mode = render.resolveOutputMode(opts);
     if (mode === "json") {
         console.log(render.asJSON(out));
@@ -15735,7 +15819,7 @@ presence
     .option("--port <port>", "Harper HTTP port")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .action(async (opts) => {
-    const agentId = resolveAgentIdOrEnv(opts);
+    const agentId = resolveSigningAgentId(opts, "presence set");
     if (!agentId) {
         console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
         process.exit(1);
@@ -15820,7 +15904,7 @@ workspace
     .option("--port <port>", "Harper HTTP port")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .action(async (opts) => {
-    const agentId = resolveAgentIdOrEnv(opts);
+    const agentId = resolveSigningAgentId(opts, "workspace set");
     if (!agentId) {
         console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
         process.exit(1);
@@ -15962,7 +16046,7 @@ program
     .option("--port <port>", "Harper HTTP port")
     .option("--target-url <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .action(async (opts) => {
-    const agentId = resolveAgentIdOrEnv(opts);
+    const agentId = resolveSigningAgentId(opts, "orgevent");
     if (!agentId) {
         console.error("Error: agent ID required. Pass --agent <id> or set FLAIR_AGENT_ID environment variable.");
         process.exit(1);
@@ -16028,7 +16112,7 @@ program
     .option("--json", "Output raw JSON")
     .action(async (entity, opts) => {
     try {
-        const agentId = resolveAgentIdOrEnv(opts);
+        const agentId = resolveSigningAgentId(opts, "attention");
         if (!agentId) {
             console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
             process.exit(2);

package/dist/lib/signing-identity.js

@@ -0,0 +1,97 @@
+/**
+ * signing-identity.ts — the ONE canonical signing-identity resolver (flair#1183).
+ *
+ * Before this file existed, every CLI command family answered "which agent am
+ * I signing this request AS?" with its own chain, and they disagreed:
+ *
+ *   - `search`/`bootstrap`/`status`/`presence`/`workspace` resolved
+ *     `--agent flag > FLAIR_AGENT_ID env` (via `resolveAgentIdOrEnv`), then
+ *     hand-signed with that id.
+ *   - Everything routed through `api()` (memory search/list, soul list, and
+ *     the writes) RE-derived the signer inside `api()` as
+ *     `FLAIR_AGENT_ID env > body.agentId`. That inverts the precedence: a
+ *     command the operator ran with `--agent X` while `FLAIR_AGENT_ID=Y` was
+ *     exported in the shell SIGNED as Y, even though the record it wrote and
+ *     the query it filtered both named X. Against a remote target where Y is
+ *     not registered, the server answered `unknown_agent` — three parties
+ *     (operator, CLI, server) silently disagreeing about who was calling.
+ *   - The `soul` family had NO env/flag resolution of its own at all: it put
+ *     `--agent` into the request body and leaned entirely on `api()`'s
+ *     env-first extraction, so even the `FLAIR_KEY_DIR` workaround that forced
+ *     the identity on the other commands could not steer it. That was the
+ *     worst rung — the "stale rung" the issue calls out.
+ *
+ * This module makes the precedence ONE thing, documented and testable:
+ *
+ *   ── Resolution order ──────────────────────────────────────────────────────
+ *   1. FLAG   — an explicit `--agent <id>`. The operator naming an identity on
+ *               THIS invocation always wins.
+ *   2. ENV    — `FLAIR_AGENT_ID`. Ambient but still a deliberate operator/CI
+ *               choice for the session.
+ *   3. CONFIG — the "config profile": the machine's ambient signing credential
+ *               (the `~/.flair/admin-pass` file and the Ed25519 agent-key floor
+ *               under `~/.flair/keys`). This tier is applied DOWNSTREAM by
+ *               `authedRequest` (src/lib/auth-resolve.ts, tiers 4-5), not by a
+ *               name lookup here — a forgotten `--agent` must never silently
+ *               resolve to some other configured identity. `resolveSigningIdentity`
+ *               models this tier via its `configProfileAgentId` parameter so the
+ *               full documented precedence is expressible and unit-testable; the
+ *               CLI leaves it unset and delegates the tier to `authedRequest`.
+ *   4. NONE   — nothing resolved by flag/env; the caller decides whether that is
+ *               fatal (agent-scoped commands demand an explicit identity) or
+ *               whether to let `authedRequest` apply the tier-3 ambient credential.
+ *
+ * The signer is resolved ONCE, at the command boundary, and threaded down to
+ * `api()`/`authedRequest` as an authoritative value — `api()` no longer
+ * re-derives it from the environment behind the caller's back.
+ */
+/**
+ * The canonical resolver. Pure: every input is a parameter, so precedence is
+ * testable in isolation with no filesystem or process state.
+ *
+ * `configProfileAgentId` is the tier-3 value (the machine's wired agent id);
+ * pass `undefined`/`null` when there is no config profile, or when the caller
+ * deliberately does not consult one. `env` is injectable for tests; it
+ * defaults to `process.env`.
+ */
+export function resolveSigningIdentity(opts, configProfileAgentId, env = process.env) {
+    if (opts.agent)
+        return { agentId: opts.agent, source: "flag" };
+    const envId = env.FLAIR_AGENT_ID;
+    if (envId)
+        return { agentId: envId, source: "env" };
+    if (configProfileAgentId)
+        return { agentId: configProfileAgentId, source: "config" };
+    return { agentId: null, source: "none" };
+}
+/** Human label for a source, used in the debug line and error text. */
+export function describeSigningIdentitySource(source) {
+    switch (source) {
+        case "flag": return "--agent flag";
+        case "env": return "FLAIR_AGENT_ID env";
+        case "config": return "config profile";
+        case "none": return "no --agent flag, FLAIR_AGENT_ID env, or config-profile agent";
+    }
+}
+/**
+ * The one-line diagnostic. Names the resolved agentId AND which tier won, so
+ * an operator can see — without guessing — who the CLI is about to sign as.
+ * Pure string builder; the gate + write live in `emitSigningIdentityDebug`.
+ */
+export function formatSigningIdentityDebug(resolved, command) {
+    const where = command ? ` for '${command}'` : "";
+    if (resolved.agentId === null) {
+        return `[flair] signing identity${where}: <none> — ${describeSigningIdentitySource("none")} resolved`;
+    }
+    return `[flair] signing identity${where}: ${resolved.agentId} (source: ${describeSigningIdentitySource(resolved.source)})`;
+}
+/**
+ * Emit the debug line to stderr, gated behind `FLAIR_DEBUG` (any non-empty
+ * value). stderr, never stdout, so `--json` output stays clean and pipeable.
+ * `env` and `write` are injectable for tests.
+ */
+export function emitSigningIdentityDebug(resolved, command, env = process.env, write = (s) => { process.stderr.write(s); }) {
+    if (!env.FLAIR_DEBUG)
+        return;
+    write(formatSigningIdentityDebug(resolved, command) + "\n");
+}

package/dist/resources/Memory.js

@@ -23,6 +23,15 @@ import { recordCitations } from "./usage-recording.js";
 function wantsTrust(target, opts) {
     if (opts?.includeTrust === true)
         return true;
+    // flair#1181 — the in-process STATIC by-id read (resources/mcp-tools.ts
+    // memory_get) folds includeTrust into the RequestTarget as a plain property,
+    // because Harper's static `Cls.get(target, context)` has no opts slot (arg 2
+    // is the context, not opts). This is the in-process analog of the two shapes
+    // below; a real RequestTarget from the HTTP path never carries a plain
+    // `includeTrust` property (it lives in the query string, read via `.get`),
+    // so this is purely additive and does not affect the HTTP path.
+    if (target?.includeTrust === true)
+        return true;
     const raw = target?.get?.("includeTrust") ??
         target?.searchParams?.get?.("includeTrust") ??
         undefined;

package/dist/resources/MemoryBootstrap.js

@@ -68,7 +68,13 @@ import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
  *   row's `entities`.
  *
  * Response:
- *   { context, sections, tokenEstimate, memoriesIncluded, memoriesAvailable }
+ *   { context, sections, tokenEstimate, memoriesIncluded, memoriesAvailable,
+ *     agentId, scope, soul, memories, predicted[, currentTaskHint] }
+ *   The self-describing keys (flair#1182 part 1) — `agentId` (resolved caller),
+ *   `scope` (read model applied to the caller), `soul`/`memories`/`predicted`
+ *   (the caller's OWN records as structured containers), and `currentTaskHint`
+ *   (present only when currentTask is absent/blank) — are ALWAYS emitted so a
+ *   client can tell an empty instance from one that doesn't support them.
  */
 // Collision surfacing (flair#681) tunables.
 const COLLISION_WINDOW_DAYS = 7;
@@ -187,6 +193,27 @@ export class BootstrapMemories extends Resource {
         let memoriesIncluded = 0;
         let memoriesAvailable = 0;
         let memoriesTruncated = 0;
+        // flair#1182 (part 1) — self-describing bootstrap. These structured
+        // container keys are ALWAYS emitted on the response (empty `{}`/`[]` when
+        // the caller has nothing), so a client can tell an *empty* instance from
+        // one that doesn't support these keys at all — and can read the caller's
+        // own soul/memories as structured data instead of parsing the `context`
+        // markdown string. Scoped to the CALLER'S OWN records only
+        // (permanent/recent/relevant/predicted are all agentId==self reads);
+        // teammate findings stay in `context`/`sections.teammate` and are never
+        // duplicated here, so these containers carry no other agent's data.
+        const soulMap = {};
+        const includedOwnMemories = [];
+        const includedPredicted = [];
+        const leanMemory = (m, section) => ({
+            id: m.id,
+            content: m.content,
+            durability: m.durability ?? null,
+            createdAt: m.createdAt ?? null,
+            agentId: m.agentId ?? agentId,
+            subject: m.subject ?? null,
+            section,
+        });
         // --- 1. Soul records (budgeted — prioritized by key importance) ---
         // Soul is who you are, but we still need to respect token budgets.
         // Workspace files (SOUL.md, AGENTS.md) can be massive — they're already
@@ -210,6 +237,9 @@ export class BootstrapMemories extends Resource {
                     skillAssignments.push(record);
                     continue;
                 }
+                // flair#1182 — the raw soul container (key→value), independent of the
+                // token-budgeted/priority-truncated `sections.soul` lines built below.
+                soulMap[record.key] = record.value;
                 const line = `**${record.key}:** ${record.value}`;
                 const tokens = estimateTokens(line);
                 const priority = SOUL_KEY_PRIORITY[record.key] ?? 50;
@@ -424,6 +454,7 @@ export class BootstrapMemories extends Resource {
             const cost = estimateTokens(line);
             if (cost <= tokenBudget) {
                 sections.permanent.push(line);
+                includedOwnMemories.push(leanMemory(m, "permanent"));
                 if (includeTrust)
                     includedTrustMemories.push(m);
                 tokenBudget -= cost;
@@ -498,6 +529,7 @@ export class BootstrapMemories extends Resource {
                 continue;
             }
             sections.recent.push(line);
+            includedOwnMemories.push(leanMemory(m, "recent"));
             if (includeTrust)
                 includedTrustMemories.push(m);
             recentSpent += cost;
@@ -540,6 +572,7 @@ export class BootstrapMemories extends Resource {
                     continue;
                 }
                 sections.predicted.push(line);
+                includedPredicted.push(leanMemory(m, "predicted"));
                 if (includeTrust)
                     includedTrustMemories.push(m);
                 predictedSpent += cost;
@@ -716,6 +749,9 @@ export class BootstrapMemories extends Resource {
                     }
                     else {
                         sections.relevant.push(line);
+                        // flair#1182 — own task-relevant records join the `memories`
+                        // container; teammate (`_source`) records stay in `context` only.
+                        includedOwnMemories.push(leanMemory(m, "relevant"));
                     }
                     if (includeTrust)
                         includedTrustMemories.push(m);
@@ -944,8 +980,38 @@ export class BootstrapMemories extends Resource {
         // decision reads only the confidence number — never a principal — against
         // the single GLOBAL threshold.
         const abstention = abstain ? evaluateAbstention(taskBestSimilarity) : undefined;
+        // flair#1182 (part 1) — resolved identity + read-scope descriptor. Reveals
+        // ONLY the caller's own resolved identity/scope (who the server decided the
+        // caller is, and the read model applied to them) — never another agent's
+        // data. Would have made the #1181 read-gate bug a one-call diagnosis.
+        const scopeInfo = {
+            agentId,
+            isAdmin: callerIsAdmin,
+            // The read model resolveReadScope(agentId) enforces for this caller: the
+            // caller's own records (any visibility) plus every other in-org agent's
+            // non-private record. Keep in sync with resources/memory-read-scope.ts.
+            reads: "own-and-org-non-private",
+        };
+        // flair#1182 (part 1) — currentTask is what turns on task-relevant
+        // retrieval, teammate findings and collision surfacing. When it's absent or
+        // blank, say so in the response so a caller learns the knob exists (present
+        // ONLY when absent/blank — a provided task needs no hint).
+        const taskProvided = typeof currentTask === "string" && currentTask.trim().length > 0;
+        const currentTaskHint = taskProvided
+            ? undefined
+            : "No currentTask was provided. Pass currentTask (a short description of what you're working on) to enable task-relevant memory retrieval, teammate findings, and collision surfacing.";
         return {
             context,
+            // flair#1182 (part 1) — always-present self-describing keys: who the
+            // server resolved the caller as, the read model applied, and the caller's
+            // own soul/memories/predicted as structured containers (empty `{}`/`[]`,
+            // never absent, so "empty" is distinguishable from "unsupported").
+            agentId,
+            scope: scopeInfo,
+            soul: soulMap,
+            memories: includedOwnMemories,
+            predicted: includedPredicted,
+            ...(currentTaskHint ? { currentTaskHint } : {}),
             ...(trust ? { trust } : {}),
             ...(abstention ? { abstention } : {}),
             sections: {

package/dist/resources/mcp-tools.js

@@ -213,11 +213,15 @@ async function memoryStore(agent, args) {
  */
 async function memoryUpdate(agent, args) {
     const Cls = await handler("Memory");
-    const h = new Cls(undefined, delegationContext(agent));
     const id = args?.id;
     const content = args?.content;
     const preserveHistory = args?.preserveHistory === true;
-    const existing = await h.get(id);
+    // flair#1181 — the existing-record fetch is a by-id READ and must use the
+    // STATIC `Cls.get(id, context)` form (see memoryGet). The instance
+    // `new Cls(undefined, ctx).get(id)` returned `undefined` for the caller's own
+    // record (getProperty on an unloaded instance), so memory_update 404'd
+    // ("memory not found") on the connector path before it ever reached a write.
+    const existing = await Cls.get(id, delegationContext(agent));
     if (!existing) {
         return { error: "memory not found", status: 404 };
     }
@@ -241,8 +245,7 @@ async function memoryUpdate(agent, args) {
         // version's provenance records which client authored this update.
         if (agent.clientId)
             record.claimedClient = agent.clientId;
-        // A create needs a COLLECTION-bound instance (see resources/in-process.ts);
-        // `h` above is the by-id handle the get()/put() branches use.
+        // A create needs a COLLECTION-bound instance (see resources/in-process.ts).
         const coll = await collectionResource(Cls, delegationContext(agent));
         return unwrap(await coll.post(record));
     }
@@ -252,21 +255,51 @@ async function memoryUpdate(agent, args) {
     // flair#718 authorship-provenance — see memoryStore's comment above.
     if (agent.clientId)
         merged.claimedClient = agent.clientId;
-    return unwrap(await h.put(merged));
+    // flair#1181 — the default merge write must ALSO use the STATIC transactional
+    // path, `Cls.put(merged, context)`, NOT an instance `new Cls(undefined, ctx).put(merged)`.
+    // An unloaded instance has no primary key, so its put()/save() throws
+    // "Invalid primary key type: undefined" (proven by the memory_update
+    // round-trip integration test). The pre-#1181 code never hit this because the
+    // broken by-id read above 404'd first — migrating the read to static exposed
+    // the same unloaded-instance defect on the write. The static form loads the
+    // row by `merged.id` and threads the context, then dispatches through
+    // Memory.put()'s own ownership gate — no scope change, same as the read.
+    return unwrap(await Cls.put(merged, delegationContext(agent)));
 }
 async function memoryGet(agent, args) {
     const Cls = await handler("Memory");
-    const h = new Cls(undefined, delegationContext(agent));
-    // flair#744 slice 1 — opt-in inline trust block on the returned record.
-    // Pass the opts arg ONLY when requested so a plain get() call is unchanged.
-    return unwrap(args?.includeTrust === true
-        ? await h.get(args?.id, { includeTrust: true })
-        : await h.get(args?.id));
+    // flair#1181 — by-id reads MUST use the STATIC `Cls.get(id, context)` form,
+    // never an instance `new Cls(undefined, ctx).get(id)`. Harper routes an
+    // instance `.get(<string>)` on an UNLOADED record (tables leave
+    // `loadAsInstance` at its `undefined` default) to `getProperty()` — a field
+    // accessor that returns `undefined` — so the read never loads the row and
+    // `makeByIdReadGate`'s `!record` branch 404s the caller's OWN record (one
+    // call after a successful store). The static form is the same transactional
+    // path the Ed25519 REST route takes: it loads the row, hands the override a
+    // `RequestTarget` (never a bare string), and still dispatches through
+    // Memory.get() → makeByIdReadGate → resolveReadScope, so the scope model is
+    // unchanged (own + org-non-private only). See resources/in-process.ts:223.
+    //
+    // flair#744 slice 1 — opt-in inline trust block. The instance call passed
+    // `includeTrust` as a 2nd positional opts arg to get(); the static form has
+    // no opts slot (arg 2 is the context), so fold it into the RequestTarget as
+    // a plain `{ id, includeTrust }` property — Memory.get()'s wantsTrust() reads
+    // it there (the in-process shape alongside the HTTP query-param shape).
+    const target = args?.includeTrust === true ? { id: args?.id, includeTrust: true } : args?.id;
+    return unwrap(await Cls.get(target, delegationContext(agent)));
 }
 async function memoryDelete(agent, args) {
     const Cls = await handler("Memory");
-    const h = new Cls(undefined, delegationContext(agent));
-    return unwrap(await h.delete(args?.id));
+    // flair#1181 — STATIC `Cls.delete(id, context)`, not an instance
+    // `new Cls(undefined, ctx).delete(id)`. Memory.delete()'s override loads the
+    // row via `super.get(id)` to enforce the permanent-memory admin guard; on an
+    // unloaded instance that `super.get(<string>)` hit the same `getProperty()`
+    // dead end (`undefined`), so the guard's `record.durability === "permanent"`
+    // check was SILENTLY SKIPPED and the delete fell through to an unguarded
+    // `super.delete(id)`. The static form loads the row first (RequestTarget,
+    // not a bare string), so the override sees the real record and the
+    // ownership/durability guard runs as intended.
+    return unwrap(await Cls.delete(args?.id, delegationContext(agent)));
 }
 async function bootstrap(agent, args) {
     const Cls = await handler("BootstrapMemories");
@@ -315,8 +348,14 @@ async function soulSet(agent, args) {
 }
 async function soulGet(agent, args) {
     const Cls = await handler("Soul");
-    const h = new Cls(undefined, delegationContext(agent));
-    return unwrap(await h.get(`${agent.agentId}:${args?.key}`));
+    // flair#1181 — STATIC by-id read (see memoryGet). Soul has no get() override
+    // and no read-scope gate; its ids are `${agentId}:${key}`, built here from
+    // the RESOLVED agent, so a caller can only ever address its OWN soul — the
+    // static migration does not change that. The instance `h.get(<string>)`
+    // returned `undefined` (getProperty on an unloaded record), which is why
+    // soul_get came back empty on the connector path even though the entries
+    // exist and load fine via the Ed25519 static route.
+    return unwrap(await Cls.get(`${agent.agentId}:${args?.key}`, delegationContext(agent)));
 }
 async function workspaceSet(agent, args) {
     const Cls = await handler("WorkspaceState");

package/dist/resources/record-type-kit.js

@@ -184,6 +184,10 @@ export function makeReadScope(mode, ownerField = "agentId") {
  * where it was.
  */
 export function makeByIdReadGate(readScope) {
+    // flair#1181 — the owner field this gate's read-scope keys on, used ONLY to
+    // annotate the diagnostic logs below. Tagged onto the resolver by
+    // makeReadScope(); "agentId" for every table wired through this kit today.
+    const ownerField = readScope?.ownerField ?? "agentId";
     return async function byIdReadGate(target, superGet) {
         // Collection / query reads arrive as a RequestTarget with
         // `isCollection === true`, and are governed by search() (same owner
@@ -191,23 +195,48 @@ export function makeByIdReadGate(readScope) {
         if (!target || (typeof target === "object" && target.isCollection)) {
             return this.search(target);
         }
+        // flair#1181 — a single debug breadcrumb per DENY/ABSENT outcome so the
+        // next 404-on-your-own-record is a one-log diagnosis instead of a re-derive
+        // from Anthropic request ids. The three outcomes below are otherwise
+        // indistinguishable to the caller BY DESIGN — the client ALWAYS receives
+        // NOT_FOUND (404-never-403, so a denied caller can't enumerate other
+        // agents' ids). This logging is server-side only and changes no response.
+        const table = this?.constructor?.name;
+        const targetId = typeof target === "string" ? target : target?.id;
         const ctx = this.getContext?.();
         const auth = await resolveAgentAuth(ctx);
         // Anonymous by-id read is already blocked at the allowRead() gate (403);
         // this is defense-in-depth if get() is ever reached directly.
-        if (auth.kind === "anonymous")
+        if (auth.kind === "anonymous") {
+            console.debug("makeByIdReadGate by-id read → NOT_FOUND", {
+                table, targetId, resolvedAgentId: undefined, recordLoaded: false, recordOwner: undefined, branch: "anonymous",
+            });
             return NOT_FOUND();
+        }
         // Trusted internal call or admin agent — unfiltered, unchanged behavior.
         if (auth.kind === "internal" || (auth.kind === "agent" && auth.isAdmin)) {
             return superGet(target);
         }
         // Non-admin agent: scoped per the table's own read-scope model.
         const record = await superGet(target);
-        if (!record)
+        if (!record) {
+            // Row did not load: either it genuinely does not exist, OR — the #1181
+            // failure — a by-id read reached here on an unloaded instance and
+            // getProperty()'d to undefined. `recordLoaded: false` is the tell.
+            console.debug("makeByIdReadGate by-id read → NOT_FOUND", {
+                table, targetId, resolvedAgentId: auth.agentId, recordLoaded: false, recordOwner: undefined, branch: "absent-or-failed-load",
+            });
             return NOT_FOUND();
+        }
         const scope = await readScope(auth.agentId);
-        if (!scope.isAllowed(record))
+        if (!scope.isAllowed(record)) {
+            // Row loaded and is owned by someone this caller may not read — a genuine
+            // ownership denial, distinct from the absent/failed-load branch above.
+            console.debug("makeByIdReadGate by-id read → NOT_FOUND", {
+                table, targetId, resolvedAgentId: auth.agentId, recordLoaded: true, recordOwner: record?.[ownerField], branch: "denied",
+            });
             return NOT_FOUND();
+        }
         return record;
     };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tpsdev-ai/flair",
-  "version": "0.44.3",
+  "version": "0.44.4",
   "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",