@tpsdev-ai/flair 0.51.1 → 0.52.0

package/dist/cli.js

@@ -20,13 +20,13 @@ import { checkServerHandshake, formatHandshakeNudge, invalidateHandshakeCache }
 import { probeInstance } from "./probe.js";
 import { sweepFleet, renderFleetSweepTable, FLEET_EXIT_OK, } from "./fleet-verify.js";
 import { markStale, sortOldestVersionFirst } from "./fleet-presence.js";
-import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemini, wireCursor, wireAntigravity, wirePi, piFlairSpec, PI_FLAIR_PACKAGE, PI_FLAIR_DEFAULT_URL, clientConfigPath, codexConfigHasFlairSection } from "./install/clients.js";
+import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemini, wireCursor, wireAntigravity, wirePi, clientConfigPath, codexConfigHasFlairSection } from "./install/clients.js";
 import { flairCliVersion, clearFlairCliVersionCache, mcpServerSpec, unpinnedSpecWarning, FLAIR_MCP_PACKAGE } from "./lib/mcp-spec.js";
 import { resolveAgentKeyPath, loadEd25519PrivateKeyFromFile, signClientAssertion, buildTokenRequestForm, getMcpAccessToken, McpTokenRequestError, defaultMcpClientId, defaultMcpTokenEndpoint, defaultMcpResource, defaultMcpIssuer, MAX_ASSERTION_LIFETIME_SECONDS, } from "./mcp-client-assertion.js";
 import { enableMcp, disableMcp, mcpStatus, checkLocalOriginRefusal, selfVerifyMcpMetadata, } from "./lib/mcp-enable.js";
-import { readClientMcpBlock, effectiveFlairUrl, checkPiFlairWiring, checkClaudeMdBootstrap, detectWiredFlairMcp, inspectSessionStartHook, upgradeSessionStartHookCommand, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, fixCommandAgentHint, isNodeKeyId, partitionKeyIds, resolveFixAgentId, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, checkContinuityCaptureHooks, fixContinuityCaptureHooks, } from "./doctor-client.js";
+import { readClientMcpBlock, effectiveFlairUrl, checkClaudeMdBootstrap, detectWiredFlairMcp, inspectSessionStartHook, upgradeSessionStartHookCommand, checkSessionStartHookPinSkew, fixClaudeMdBootstrap, fixSessionStartHook, applyOrReportClaudeMdBootstrap, applyOrReportSessionStartHook, resolveWireFlairUrl, planAgentIterations, fixCommandAgentHint, isNodeKeyId, partitionKeyIds, resolveFixAgentId, describeAgentGateFinding, embeddingsSkipRemedy, classifyKeyFile, resolveCollisionSafeName, pruneDateStamp, PRUNED_DIR_NAME, checkContinuityCaptureHooks, fixContinuityCaptureHooks, } from "./doctor-client.js";
 import { checkGlobalBinOnPath, cliBootPathWarning, resolveNpmGlobalPrefix, } from "./install/global-bin-path.js";
-import { installHook, uninstallHook, hookStatus, hookStatusIdentityLines, HOOK_STATUS_UNPARSED, installContinuityHooks, uninstallContinuityHooks, continuityHookStatus, isSupportedHarness, SUPPORTED_HARNESSES, hookSettingsPath, hookInstallHint, harnessSupportsContinuity, resolveHookAgentId, } from "./hook-install.js";
+import { installHook, uninstallHook, repinSessionStartHook, hookStatus, hookStatusIdentityLines, HOOK_STATUS_UNPARSED, installContinuityHooks, uninstallContinuityHooks, continuityHookStatus, isSupportedHarness, SUPPORTED_HARNESSES, hookSettingsPath, hookInstallHint, harnessSupportsContinuity, resolveHookAgentId, } from "./hook-install.js";
 import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, DEFAULT_ADMIN_USER, resolveAdminUser, 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";
@@ -41,6 +41,8 @@ import { classifyDaemonState, verifyIdentity, parseProcStatStartTime, procStartT
 // functions — this pulls in nothing but node builtins.
 import { DEFAULT_INTERVAL_SECONDS as FEDERATION_SYNC_DEFAULT_INTERVAL } from "./federation/scheduler.js";
 import { applyUpgradeMigrations } from "./lib/upgrade-migrations.js";
+import { collectUpgradeExecPathWarning, findFlairPackageDir, resolveNpmGlobalFlairPackage, resolveServingFlairPackage, } from "./lib/upgrade-exec-path.js";
+import { applyPlainTreeUpgrade, decidePlainTreeRollback, discardPlainTreePrevious, findSystemdUnitsForTree, formatPlainTreeBanner, formatPlainTreePlan, formatPlainTreeScopeFooter, planPlainTreeUpgrade, resolvePlainTreeListingTarget, resolvePlainTreeTarget, restartSystemdUnits, restorePlainTreePrevious, } from "./lib/upgrade-plain-tree.js";
 // Federation crypto helpers — inlined to avoid cross-boundary imports from
 // src/ into resources/, which don't survive npm packaging (see also
 // resources/federation-crypto.ts; the two must stay in sync).
@@ -75,6 +77,16 @@ function signBody(body, secretKey) {
 // it against data.agentId for Memory (PRINCIPAL_OWNING_TABLES); it is
 // no longer informational-only. Credential.principalId is an unrelated
 // owner field — do not grep that path when changing this one.
+//
+// S2 COMMENT-PIN (Kern P2-5, flair#1521): Message is principal-owning by `from`
+// (PRINCIPAL_OWNER_FIELD in federation-classify.ts) but its rows carry NO
+// `provenance` stamp, so principalIdFromRow returns undefined for them → a v:2
+// Message push would omit `principalId` → the receiver's v≥2
+// checkPrincipalEntitlement skips EVERY Message as `principal_mismatch` (a
+// 100%-skip sync, not a migration). S1 does not push Message (receive-only —
+// the spoke push list below is a separate hardcoded set), so this is inert
+// today; the S2 pusher MUST stamp `principalId = row.from` for Message here
+// (a per-table owner-aware derivation, not `provenance.verified.agentId`).
 function principalIdFromRow(row) {
     if (typeof row?.provenance !== "string" || row.provenance.length === 0)
         return undefined;
@@ -687,10 +699,14 @@ function resolveSigningIdentityFor(opts, command) {
     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.
+// Same seam, returning the full ResolvedSigningIdentity (agentId + source) so
+// callers can thread the source down to api()/authedRequest. The source is what
+// lets authedRequest distinguish a flag-pinned agent (--agent X, flair#1500)
+// from an env-pinned one (FLAIR_AGENT_ID) — the flag must sign as itself BEFORE
+// env admin, while the env keeps its legacy Basic behavior. Still emits the
+// debug line via resolveSigningIdentityFor.
 function resolveSigningAgentId(opts, command) {
-    return resolveSigningIdentityFor(opts, command).agentId;
+    return resolveSigningIdentityFor(opts, command);
 }
 // ── Shared credential/identity flag surface (flair#1106) ─────────────────────
 // Sibling commands (memory add, backup, federation sync) used to drift on
@@ -1484,6 +1500,7 @@ async function api(method, path, body, options) {
         keysDir: options?.keysDir,
         explicitAdminPass: options?.explicitAdminPass,
         adminUser: options?.adminUser,
+        agentIdSource: options?.agentIdSource,
     });
 }
 /**
@@ -2413,10 +2430,30 @@ const FLAIR_AGENT_PERMISSION = {
             Memory: grant(true, true, true, true),
             MemoryCandidate: grant(true, true, true, true),
             MemoryGrant: grant(true, true, true, true),
+            // Asset (images-in-Flair slice 1). Harper authorizes BEFORE Asset.post
+            // runs, so a de-elevated flair_agent needs the table grant or signed
+            // POST /Asset 403s as AccessViolation (Kern P0). CRUD envelope;
+            // owner-only + write-time size/MIME gates live in resources/Asset.ts.
+            Asset: grant(true, true, true, true),
             Soul: grant(true, true, true, false),
             OrgEvent: grant(true, true, true, true),
             WorkspaceState: grant(true, true, true, true),
             Relationship: grant(true, true, true, true),
+            // Flair Relay S1 (flair#1521). Harper authorizes BEFORE the resource
+            // methods run, so a de-elevated flair_agent needs the table grant OR it
+            // 403s on POST /Message before relaySend is reached (Kern P0-2). read =
+            // the party-scoped collection (Message.search); insert = send via post().
+            // update = FALSE (least privilege, Kern P0 blocker): the ack's write goes
+            // through the IN-PROCESS static accessor (relayConsume → deps.messages.put),
+            // which bypasses role gates entirely — the same raw-put seam Federation.ts
+            // relies on — so update:true is NOT needed for any legitimate path. Leaving
+            // it granted let PATCH /Message/<id> reach Table's update verb, whose
+            // authorize step consults update:true and PASSES for any de-elevated agent,
+            // bypassing Message.put()'s FORBIDDEN guard AND relayConsume's recipient-only
+            // check (Message has no patch() at the platform level → TableResource.patch
+            // runs update()+save() directly). delete = false: direct deletes are
+            // admin/internal only. Message.patch() also guards the verb in-resource.
+            Message: grant(true, true, false, false),
             Integration: grant(true, true, true, true),
             Credential: grant(true, true, true, true),
             Presence: grant(true, true, true, false),
@@ -2430,6 +2467,9 @@ const FLAIR_AGENT_PERMISSION = {
             // (create → count → delete → count again → repeat), defeating the cap
             // entirely. See resources/MemoryUsage.ts's module doc.
             MemoryUsage: grant(true, true, false, false),
+            // MemoryHitStat (flair#1528): internal search-hit ledger. No agent REST
+            // surface (@table without @export). Counts overlay onto Memory reads.
+            MemoryHitStat: grant(false, false, false, false),
             // Agent: read for discovery, update own card; creation/removal is admin.
             Agent: grant(true, false, true, false),
             // Read-only reference data.
@@ -3672,7 +3712,7 @@ program
                 console.log("");
                 for (const [key, value] of soulEntries) {
                     try {
-                        await authFetch(httpUrl, agentId, privPath, "PUT", `/Soul/${agentId}:${key}`, { id: `${agentId}:${key}`, agentId, key, value, createdAt: new Date().toISOString() });
+                        await api("PUT", `/Soul/${agentId}:${key}`, { id: `${agentId}:${key}`, agentId, key, value, createdAt: new Date().toISOString() }, { baseUrl: httpUrl, explicitAdminPass: adminPass, adminUser });
                         console.log(`   ✓ soul:${key} set`);
                     }
                     catch (err) {
@@ -4474,8 +4514,9 @@ agent
 /** Best-effort seed-validity check for a `.key` file: does it parse via any
  *  of the formats loadEd25519PrivateKeyFromFile (src/mcp-client-assertion.ts
  *  — the same loader `flair mcp token` uses) accepts? Never throws — used
- *  only to decide "invalid" vs. "worth a registration check", not to
- *  actually sign anything. */
+ *  only to decide "unidentified" vs. "worth a registration check", not to
+ *  actually sign anything. An unparseable file is not junk: the keys dir is
+ *  also where FileKeyStore writes AES-256-GCM blobs (flair#1026). */
 function isValidPrivateKeySeedFile(keyPath) {
     try {
         loadEd25519PrivateKeyFromFile(keyPath);
@@ -4490,10 +4531,11 @@ function isValidPrivateKeySeedFile(keyPath) {
  * never writes or moves anything; see applyKeyPrune below for the actual
  * move. Directories (including keysDir's own `.pruned` archive, PRUNED_DIR_NAME)
  * and files not ending in `.key` are "ignored" without any network call.
- * `.key` files with an unparseable seed are "invalid" without a network call
- * either — only a `.key` file that DOES parse triggers a signed
- * `GET /Agent/:id` against `baseUrl` (checkAgentRegistered above, the exact
- * same check doctor's registration gate uses).
+ * `.key` files with an unparseable seed are "unidentified" without a network
+ * call either — reported, never pruned (flair#1026). Only a `.key` file that
+ * DOES parse triggers a signed `GET /Agent/:id` against `baseUrl`
+ * (checkAgentRegistered above, the exact same check doctor's registration
+ * gate uses).
  *
  * If that check EVER reports "unreachable" — the instance couldn't be
  * confirmed up for that key — the WHOLE run aborts immediately
@@ -4544,7 +4586,7 @@ export async function classifyKeysDir(keysDir, baseUrl) {
         // flair#1023 added "key-unreadable". It cannot occur here — this key's
         // seed already parsed via isValidPrivateKeySeedFile above — but is
         // handled explicitly rather than folded into the else: a key that will
-        // not load means exactly what prune already calls "invalid".
+        // not load is "unidentified", not prunable "invalid" (flair#1026).
         const decision = reg.state === "key-unreadable"
             ? classifyKeyFile(c.agentId, false, null, baseUrl)
             : classifyKeyFile(c.agentId, true, { state: reg.state, detail: reg.detail }, baseUrl);
@@ -4604,10 +4646,11 @@ keys
     }
     const stale = result.entries.filter((e) => e.class === "stale");
     const invalid = result.entries.filter((e) => e.class === "invalid");
+    const unidentified = result.entries.filter((e) => e.class === "unidentified");
     const kept = result.entries.filter((e) => e.class === "keep");
     const ignored = result.entries.filter((e) => e.class === "ignored");
     const prunable = [...stale, ...invalid];
-    if (stale.length + invalid.length + kept.length === 0) {
+    if (stale.length + invalid.length + unidentified.length + kept.length === 0) {
         console.log(`  ${render.icons.ok} No key files found in ${render.wrap(render.c.dim, keysDir)} — nothing to prune.`);
         console.log("");
         return;
@@ -4616,12 +4659,15 @@ keys
         const icon = e.class === "invalid" ? render.icons.error : render.icons.warn;
         console.log(`  ${icon} ${render.wrap(render.c.bold, e.name)} — ${e.class}: ${e.reason}`);
     }
+    for (const e of unidentified) {
+        console.log(`  ${render.icons.warn} ${render.wrap(render.c.bold, e.name)} — unidentified: ${e.reason}`);
+    }
     for (const e of kept) {
         console.log(`  ${render.icons.ok} ${e.name} — registered, keeping`);
     }
     if (!apply) {
         console.log("");
-        console.log(`  ${render.wrap(render.c.dim, `${prunable.length} prunable (${stale.length} stale, ${invalid.length} invalid), ${kept.length} kept, ${ignored.length} ignored`)}`);
+        console.log(`  ${render.wrap(render.c.dim, `${prunable.length} prunable (${stale.length} stale, ${invalid.length} invalid), ${kept.length} kept, ${unidentified.length} unidentified (left in place), ${ignored.length} ignored`)}`);
         if (prunable.length > 0) {
             console.log(`  ${render.wrap(render.c.dim, "Run with --apply to move prunable keys to")} ${join(keysDir, PRUNED_DIR_NAME, pruneDateStamp())}`);
         }
@@ -4633,7 +4679,7 @@ keys
     for (const m of moved) {
         console.log(`  ${render.icons.ok} moved ${m.name} -> ${m.movedTo}`);
     }
-    console.log(`\n  ${render.wrap(render.c.bold, String(moved.length))} moved, ${kept.length} kept, ${ignored.length} ignored\n`);
+    console.log(`\n  ${render.wrap(render.c.bold, String(moved.length))} moved, ${kept.length} kept, ${unidentified.length} unidentified (left in place), ${ignored.length} ignored\n`);
 });
 // ─── flair hook ──────────────────────────────────────────────────────────────
 // Ambient memory via harness SessionStart hooks (flair#745, design record
@@ -7937,6 +7983,9 @@ rem
     .command("candidates")
     .description("List staged memory candidates from the FLAIR-NIGHTLY-REM cycle (pending review)")
     .option("--port <port>", "Harper HTTP port")
+    .option("--ops-port <port>", "Harper operations API port")
+    .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--agent <id>", "Agent ID (or FLAIR_AGENT_ID env)")
     .option("--status <s>", "Filter by status: pending | promoted | rejected (default: pending)")
     .option("--json", "Output as JSON for scripting")
@@ -7952,16 +8001,35 @@ rem
         console.error(`${render.icons.error} --agent is required (or set FLAIR_AGENT_ID)`);
         process.exit(1);
     }
+    const opsPort = resolveOpsPort(opts);
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    if (!adminPass) {
+        console.error(`${render.icons.error} --admin-pass or FLAIR_ADMIN_PASS required`);
+        process.exit(1);
+    }
+    const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
     try {
-        const result = await api("POST", "/MemoryCandidate/search_by_conditions", {
-            operator: "and",
-            conditions: [
-                { search_attribute: "agentId", search_type: "equals", search_value: agentId },
-                { search_attribute: "status", search_type: "equals", search_value: status },
-            ],
-            get_attributes: ["id", "claim", "generatedBy", "generatedAt", "status", "target", "reviewerId", "decidedAt", "supersedes"],
+        const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json", Authorization: auth },
+            body: JSON.stringify({
+                operation: "search_by_conditions",
+                schema: "flair",
+                table: "MemoryCandidate",
+                operator: "and",
+                conditions: [
+                    { search_attribute: "agentId", search_type: "equals", search_value: agentId },
+                    { search_attribute: "status", search_type: "equals", search_value: status },
+                ],
+                get_attributes: ["id", "claim", "generatedBy", "generatedAt", "status", "target", "reviewerId", "decidedAt", "supersedes"],
+            }),
         });
-        const candidates = Array.isArray(result) ? result : (result?.results ?? []);
+        if (!res.ok) {
+            const text = await res.text().catch(() => "");
+            console.error(`${render.icons.error} ${res.status} ${text}`);
+            process.exit(1);
+        }
+        const candidates = await res.json();
         const mode = render.resolveOutputMode(opts);
         if (mode === "json") {
             console.log(render.asJSON({ agentId, status, count: candidates.length, candidates }));
@@ -8011,209 +8079,8 @@ rem
 // Pure validators extracted for testability. The action callbacks below thread
 // these through process.exit on failure; the helpers themselves are
 // side-effect-free.
-export function validatePromoteOpts(opts) {
-    if (!opts.rationale || !opts.rationale.trim()) {
-        return "--rationale is required (per spec § 5: no rubber-stamp)";
-    }
-    if (!opts.to || (opts.to !== "soul" && opts.to !== "memory")) {
-        return "--to must be 'soul' or 'memory'";
-    }
-    if (opts.to === "soul" && (!opts.key || !opts.key.trim())) {
-        return "--key is required when --to=soul (gives the Soul entry a meaningful identifier)";
-    }
-    return null;
-}
-export function validateRejectOpts(opts) {
-    if (!opts.reason || !opts.reason.trim()) {
-        return "--reason is required";
-    }
-    return null;
-}
-/**
- * Decide whether a promote/reject action can proceed against a candidate's
- * current state, and what message to surface to the operator. Pure function;
- * action side effects happen in the CLI body after this returns ok.
- */
-export function decideCandidateAction(candidate, action) {
-    if (!candidate)
-        return { ok: false, severity: "error", message: "candidate not found" };
-    const status = candidate.status;
-    if (status === "promoted") {
-        return action === "promote"
-            ? { ok: false, severity: "error", message: `already promoted (target=${candidate.target}, reviewer=${candidate.reviewerId})` }
-            : { ok: false, severity: "error", message: `already promoted; cannot reject after promotion` };
-    }
-    if (status === "rejected") {
-        return action === "reject"
-            ? { ok: false, severity: "info", message: `already rejected on ${candidate.decidedAt} by ${candidate.reviewerId}` }
-            : { ok: false, severity: "error", message: `already rejected; use a fresh candidate or reset status manually` };
-    }
-    return { ok: true };
-}
-// ─── ADK tag-lineage on promote (#1205 slice 1205a — Sherlock security req) ───
-// ADK session records are written by adk-flair (memory_service.py) under a
-// SHARED-namespace agentId, with per-user separation carried ENTIRELY by a
-// compound scope tag `adk:<app>:<user>`. That tag is the access-control
-// boundary. A candidate distilled from those records therefore MUST carry the
-// scope tag when promoted, or the promoted claim lands in the shared agentId
-// memory retrievable by every other user of the app — a cross-user leak.
-//
-// `rem promote` historically hard-coded `["nightly-rem-promoted", from:<id>]`
-// and DROPPED the source tag. We now propagate the source scope tag for
-// ADK-sourced candidates, and FAIL CLOSED (refuse) when a candidate is
-// ADK-sourced but its scope tag can't be uniquely+completely determined.
-//
-// SCOPING (deliberate, per spec): fail-closed applies ONLY to ADK-sourced
-// candidates. Non-ADK candidates carry no `adk:` tag and promote byte-for-byte
-// as before — a transient/deleted source on a non-ADK candidate must NOT block
-// its promotion.
-//
-// SEAM (foundation only; the distillation engine is slice #1205b): ADK-sourcing
-// is detected here by re-reading the candidate's source memories and inspecting
-// their tags. That leaves ONE residual fail-open: an ADK-sourced candidate all
-// of whose source memories are unreadable (deleted/transient) yields no `adk:`
-// evidence and is treated as non-ADK. Closing that corner without regressing
-// non-ADK promotion requires the ENGINE to stamp the authoritative scope tag
-// onto the MemoryCandidate row at distillation time (it distills per single
-// scope:tagged tag, so it knows it authoritatively). `derivePromotedTags` is
-// written so that override can be threaded in later without touching callers.
-export const ADK_SCOPE_TAG_PREFIX = "adk:";
-/**
- * Decide the tag set for a promoted Memory given the candidate id and the
- * result of fetching each of its source memories. Pure — no I/O; the action
- * callback does the fetching and threads the results here so this is unit-
- * testable and the fail-closed logic is exercised directly.
- *
- * `stampedScopeTag` (#1205b-1 — the engine slice the #1205a SEAM note below
- * anticipated): the authoritative scope:"tagged" tag the distillation engine
- * stamped onto the MemoryCandidate row (resources/MemoryReflect.ts →
- * buildStagedCandidateRow). When present it is AUTHORITATIVE and short-circuits
- * the source re-read entirely — the engine distilled under exactly this one
- * tag, so it knows the per-user scope tag independent of whether the source
- * memories are still readable. This closes the residual fail-open the SEAM
- * note describes: a candidate all of whose sources are unreadable yields no
- * `adk:` evidence and would otherwise be mis-classified NON-ADK and promoted
- * tagless into the shared agentId namespace (a cross-user leak). Threading it
- * in as an optional trailing arg keeps every pre-#1205b caller (and every
- * candidate that never carried a stamp) on the unchanged source-re-read path.
- *
- * With NO stamp (undefined/empty) the source-re-read classification runs
- * exactly as in #1205a:
- *  - No `adk:` scope tag across readable sources → NON-ADK candidate; return
- *    the provenance tags only (unchanged behavior).
- *  - Exactly one `adk:` scope tag AND every source readable → ADK-sourced;
- *    return [scopeTag, ...provenance].
- *  - `adk:` evidence present but the scope tag is ambiguous (>1 distinct tag)
- *    OR incomplete (some source unreadable) → REFUSE (fail-closed): a
- *    tagless/mis-tagged claim in a shared ADK namespace is a cross-user leak,
- *    not a benign miss.
- */
-export function derivePromotedTags(candidateId, sources, stampedScopeTag) {
-    const provenance = ["nightly-rem-promoted", `from:${candidateId}`];
-    // #1205b-1: a stamped scope tag is AUTHORITATIVE — consume it directly, never
-    // re-read sources. This is the seam closure: correctness no longer depends on
-    // source readability. `adkSourced` (which gates the Soul-promotion refusal in
-    // the promote action) tracks whether the stamped tag is an ADK scope tag.
-    if (typeof stampedScopeTag === "string" && stampedScopeTag.length > 0) {
-        return {
-            ok: true,
-            tags: [stampedScopeTag, ...provenance],
-            adkSourced: stampedScopeTag.startsWith(ADK_SCOPE_TAG_PREFIX),
-        };
-    }
-    const adkTags = new Set();
-    let anySourceUnreadable = false;
-    for (const s of sources) {
-        if (!s.ok) {
-            anySourceUnreadable = true;
-            continue;
-        }
-        for (const t of s.tags) {
-            if (typeof t === "string" && t.startsWith(ADK_SCOPE_TAG_PREFIX))
-                adkTags.add(t);
-        }
-    }
-    // No positive ADK evidence → non-ADK. An unreadable source with zero ADK
-    // evidence does NOT fail closed here (that would regress non-ADK promotion);
-    // see the SEAM note above.
-    if (adkTags.size === 0) {
-        return { ok: true, tags: provenance, adkSourced: false };
-    }
-    if (adkTags.size > 1) {
-        return {
-            ok: false,
-            reason: `ADK-sourced candidate spans multiple scope tags (${[...adkTags].sort().join(", ")}); refusing to promote — a merged cross-user claim would leak across users`,
-        };
-    }
-    if (anySourceUnreadable) {
-        return {
-            ok: false,
-            reason: `ADK-sourced candidate has unreadable source memories; the per-user scope tag cannot be confirmed — refusing to promote (fail-closed)`,
-        };
-    }
-    const scopeTag = [...adkTags][0];
-    return { ok: true, tags: [scopeTag, ...provenance], adkSourced: true };
-}
-// ─── Promoted-row visibility (flair#1257 slice 3 — default-private-unless) ────
-// Continuity-journal scope tag prefix. Canonical string duplicated in
-// resources/memory-reflect-lib.ts / resources/auto-promote-lib.ts and
-// packages/flair-mcp/src/continuity.ts — this file sits on the CLI side of the
-// npm-packaging boundary (see this file's header) and cannot import them; kept
-// in sync by the shared canonical string, same discipline as
-// MACHINE_REVIEWER_* below.
-export const CONTINUITY_SCOPE_TAG_PREFIX = "adk:continuity:";
-/**
- * Decide a promoted Memory row's visibility for the HUMAN `rem promote` path
- * (flair#1257 slice 3). Mirror of resources/auto-promote-lib.ts
- * decidePromotedVisibility (the server-side auto-promote half) — Sherlock's
- * default-private-unless ruling covers BOTH promotion paths: the sources of a
- * continuity candidate are the most sensitive tier (ephemeral+private journal
- * rows), so leaving visibility unset here would let Memory's durability-keyed
- * default widen it to shared ("persistent" defaults shared) — a silent
- * visibility escalation. "shared" only when the candidate is continuity-scoped
- * AND carries the distiller's affirmative ruling WITH its recorded
- * team-relevance justification; every other case — including every
- * uncertainty — is "private".
- *
- * Returns undefined for NON-continuity candidates: their visibility behavior
- * (durability-keyed default) is byte-for-byte the pre-slice-3 contract and is
- * deliberately not changed here.
- */
-export function derivePromotedVisibility(candidate) {
-    const scopeTag = candidate.scopeTag;
-    const isContinuity = typeof scopeTag === "string" &&
-        scopeTag.length > CONTINUITY_SCOPE_TAG_PREFIX.length &&
-        scopeTag.startsWith(CONTINUITY_SCOPE_TAG_PREFIX);
-    if (!isContinuity)
-        return undefined;
-    if (candidate.visibilityRuling !== "shared")
-        return "private";
-    const rationale = typeof candidate.visibilityRationale === "string" ? candidate.visibilityRationale.trim() : "";
-    return rationale.length > 0 ? "shared" : "private";
-}
-// ─── Machine reviewer namespace (#1205 slice 1205a — Sherlock security req 4) ─
-// A promotion records a reviewerId that feeds audit/attribution
-// (schemas/memory.graphql:209). An automated (machine-driven) promotion path
-// must record a reviewerId that can NEVER be mistaken for a human/agent
-// reviewer, so attribution isn't laundered. Reserve the `machine:` namespace
-// for that, and forbid the human `--reviewer` path from claiming it.
-export const MACHINE_REVIEWER_PREFIX = "machine:";
-/** Canonical machine reviewerId for the ADK auto-promote consumer (#1205b). */
-export const MACHINE_REVIEWER_ADK_AUTO_PROMOTE = "machine:adk-auto-promote";
-/** True iff `id` is in the reserved machine-reviewer namespace — i.e. it
- *  denotes an automated path, not a human or agent reviewer. */
-export function isMachineReviewerId(id) {
-    return typeof id === "string" && id.startsWith(MACHINE_REVIEWER_PREFIX);
-}
-/** The human `flair rem promote` path must not record a reviewerId in the
- *  reserved machine namespace — that would launder automated attribution onto
- *  a human-operated promotion. Returns an error string, or null if allowed. */
-export function validateHumanReviewerId(reviewerId) {
-    if (isMachineReviewerId(reviewerId)) {
-        return `--reviewer '${reviewerId}' uses the reserved '${MACHINE_REVIEWER_PREFIX}' namespace (reserved for automated promotion); use a human/agent reviewer id`;
-    }
-    return null;
-}
+import { validatePromoteOpts, validateRejectOpts, decideCandidateAction, derivePromotedTags, validateHumanReviewerId } from "./rem/promote-policy.js";
+export { validatePromoteOpts, validateRejectOpts, decideCandidateAction, derivePromotedTags, derivePromotedVisibility, validateHumanReviewerId, isMachineReviewerId, ADK_SCOPE_TAG_PREFIX, CONTINUITY_SCOPE_TAG_PREFIX, MACHINE_REVIEWER_PREFIX, MACHINE_REVIEWER_ADK_AUTO_PROMOTE } from "./rem/promote-policy.js";
 // ─── flair rem promote ───────────────────────────────────────────────────────
 // Slice 2 of FLAIR-NIGHTLY-REM (ops-2qq). Promote a candidate to either Soul
 // or persistent Memory. Both --rationale and --to are required (spec § 5: no
@@ -8249,6 +8116,17 @@ rem
         process.exit(1);
     }
     try {
+        if (opts.to === "memory") {
+            const promoted = await api("POST", "/PromoteMemoryCandidate", {
+                candidateId, rationale: opts.rationale,
+                ...(opts.reviewer ? { reviewerId: opts.reviewer } : {}),
+            });
+            if (promoted?.error)
+                throw new Error(promoted.error);
+            console.log(`✅ Wrote Memory ${promoted.memoryId} (durability=persistent)`);
+            console.log(`✅ Candidate ${candidateId} marked promoted → memory, reviewer=${promoted.reviewerId}`);
+            return;
+        }
         // Fetch the candidate
         const candidate = await api("GET", `/MemoryCandidate/${encodeURIComponent(candidateId)}`);
         const candidateData = (candidate && !candidate.error) ? candidate : null;
@@ -8295,63 +8173,31 @@ rem
         }
         // Soul entries are agentId-scoped and cannot carry a per-user scope tag,
         // so an ADK-sourced candidate promoted to Soul is a cross-user leak by
-        // construction — fail closed. (Server-side trust-tier enforcement that
-        // hard-locks the target is the engine slice #1205b; this is the CLI-side
-        // foundation.)
+        // construction — fail closed here and again on Soul.post/put so a
+        // scripted PUT /Soul cannot bypass the CLI.
         if (opts.to === "soul" && tagDecision.adkSourced) {
             console.error(`Error: candidate ${candidateId} is ADK-sourced (scope tag ${tagDecision.tags[0]}); Soul is agentId-scoped and cannot carry a per-user scope tag — refusing to promote to Soul (would leak across users). Promote ADK-sourced candidates to memory.`);
             process.exit(1);
         }
         const promotedTags = tagDecision.tags;
         const decidedAt = new Date().toISOString();
-        // Write the resulting Soul or Memory entry
-        if (opts.to === "memory") {
-            const memId = `${candidate.agentId}-promoted-${Date.now()}`;
-            // flair#1257 slice 3: for a CONTINUITY-scoped candidate, visibility is
-            // decided default-private-unless (derivePromotedVisibility) — the
-            // sources are ephemeral+private journal rows, and an unset visibility
-            // would silently widen to shared via the persistent durability
-            // default. Non-continuity candidates return undefined here and keep
-            // the pre-slice-3 durability-keyed default, unchanged.
-            const promotedVisibility = derivePromotedVisibility(candidate);
-            const memWrite = await api("PUT", `/Memory/${encodeURIComponent(memId)}`, {
-                id: memId,
-                agentId: candidate.agentId,
-                content: candidate.claim,
-                durability: "persistent",
-                ...(promotedVisibility ? { visibility: promotedVisibility } : {}),
-                tags: promotedTags,
-                derivedFrom: candidate.sourceMemoryIds ?? [],
-                promotionStatus: "approved",
-                promotedAt: decidedAt,
-                promotedBy: reviewerId,
-                createdAt: decidedAt,
-            });
-            if (memWrite?.error) {
-                console.error(`Error writing Memory: ${memWrite.error}`);
-                process.exit(1);
-            }
-            console.log(`✅ Wrote Memory ${memId} (durability=persistent)`);
-        }
-        else {
-            // soul
-            const soulId = `${candidate.agentId}-${opts.key}`;
-            const soulWrite = await api("PUT", `/Soul/${encodeURIComponent(soulId)}`, {
-                id: soulId,
-                agentId: candidate.agentId,
-                key: opts.key,
-                value: candidate.claim,
-                priority: "standard",
-                durability: "persistent",
-                createdAt: decidedAt,
-                updatedAt: decidedAt,
-            });
-            if (soulWrite?.error) {
-                console.error(`Error writing Soul: ${soulWrite.error}`);
-                process.exit(1);
-            }
-            console.log(`✅ Wrote Soul ${soulId} (key=${opts.key})`);
+        // Memory promotion is handled by the server workflow above.
+        const soulId = `${candidate.agentId}-${opts.key}`;
+        const soulWrite = await api("PUT", `/Soul/${encodeURIComponent(soulId)}`, {
+            id: soulId,
+            agentId: candidate.agentId,
+            key: opts.key,
+            value: candidate.claim,
+            priority: "standard",
+            durability: "persistent",
+            createdAt: decidedAt,
+            updatedAt: decidedAt,
+        });
+        if (soulWrite?.error) {
+            console.error(`Error writing Soul: ${soulWrite.error}`);
+            process.exit(1);
         }
+        console.log(`✅ Wrote Soul ${soulId} (key=${opts.key})`);
         // Update the candidate row
         const upd = await api("PUT", `/MemoryCandidate/${encodeURIComponent(candidateId)}`, {
             ...candidate,
@@ -8524,6 +8370,9 @@ remNightly
     .command("run-once")
     .description("Run one nightly cycle now (snapshot + log). Same code path the scheduler will use.")
     .option("--agent <id>", "Agent id (or FLAIR_AGENT_ID env)")
+    .option("--ops-port <port>", "Harper operations API port")
+    .option("--admin-pass <pass>", "Admin password (or set FLAIR_ADMIN_PASS)")
+    .option("--admin-user <name>", "Admin username for Basic auth (env: FLAIR_ADMIN_USER; default: admin)")
     .option("--dry-run", "Log the row but skip the snapshot write")
     .action(async (opts) => {
     const agentId = opts.agent || process.env.FLAIR_AGENT_ID;
@@ -8532,12 +8381,47 @@ remNightly
         process.exit(1);
     }
     const { runNightlyCycle } = await import("./rem/runner.js");
+    // The runner is agent-authed and cannot reach the ops port itself. When
+    // admin credentials are available, inject an ops-API `search_by_conditions`
+    // helper so the pending-candidate count can be sampled; otherwise the count
+    // is best-effort 0 (the cycle still runs).
+    const adminPass = opts.adminPass ?? process.env.FLAIR_ADMIN_PASS ?? "";
+    const opsSearch = adminPass
+        ? async (table, conditions, getAttributes) => {
+            const opsPort = resolveOpsPort(opts);
+            const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
+            const res = await fetch(`http://127.0.0.1:${opsPort}/`, {
+                method: "POST",
+                headers: { "Content-Type": "application/json", Authorization: auth },
+                body: JSON.stringify({ operation: "search_by_conditions", schema: "flair", table, operator: "and", conditions, get_attributes: getAttributes }),
+            });
+            if (!res.ok)
+                throw new Error(`ops API failed (${res.status})`);
+            const raw = await res.json();
+            return Array.isArray(raw) ? raw : (raw?.results ?? []);
+        }
+        : undefined;
     try {
+        const healthBase = (process.env.FLAIR_URL || `http://127.0.0.1:${resolveHttpPort({})}`).replace(/\/+$/, "");
         const result = await runNightlyCycle({
             agentId,
             flairVersion: __pkgVersion,
             apiCall: api,
+            opsSearch,
             dryRun: !!opts.dryRun,
+            healthProbe: async (timeoutMs) => {
+                const t = Date.now();
+                try {
+                    const res = await fetch(`${healthBase}/Health`, { signal: AbortSignal.timeout(timeoutMs) });
+                    if (!res.ok) {
+                        return { ok: false, elapsedMs: Date.now() - t, error: `GET /Health returned HTTP ${res.status}` };
+                    }
+                    return { ok: true, elapsedMs: Date.now() - t };
+                }
+                catch (err) {
+                    return { ok: false, elapsedMs: Date.now() - t, error: err?.message ?? String(err) };
+                }
+            },
         });
         const row = result.logRow;
         console.log(`-- rem nightly run-once${opts.dryRun ? " (dry-run)" : ""} --`);
@@ -8558,6 +8442,12 @@ remNightly
         if (row.candidates) {
             console.log(`Staged:     ${row.candidates.length} candidate${row.candidates.length === 1 ? "" : "s"}`);
         }
+        if (row.distill) {
+            const remaining = Math.max(0, row.distill.unreflected - row.distill.gathered);
+            console.log(`Distilled:  ${row.distill.gathered} memor${row.distill.gathered === 1 ? "y" : "ies"} (cap ${row.distill.maxMemories}; ${remaining} unreflected remaining)`);
+            if (row.distill.aborted)
+                console.log(`Aborted:    yes — in-flight distillation stopped (flair rem pause)`);
+        }
         // row.autoPromoted populates when step 5b (#1205b-2 ADK auto-promote) ran
         // this cycle — i.e. a non-dry-run cycle for an ADK agentId.
         if (row.autoPromoted) {
@@ -8570,6 +8460,10 @@ remNightly
             console.log(`Dedup:      ${row.dedup.clusterCount} cluster${row.dedup.clusterCount === 1 ? "" : "s"} (${row.dedup.totalMemoriesInClusters} memories, largest ${row.dedup.largestClusterSize})`);
         }
         console.log(`Duration:   ${row.durationMs}ms`);
+        if (result.status === "refused") {
+            console.log(`\nNote: REM refused to start because /Health could not be served.`);
+            console.log(`Restore /Health before retrying, or \`flair rem pause\` to stop the scheduler.`);
+        }
         if (row.errors.length > 0) {
             console.log(`Errors:`);
             for (const e of row.errors)
@@ -8635,8 +8529,7 @@ remSnapshot
 //
 // The <date> argument is an ISO-timestamp prefix or date-only prefix; the
 // command picks the latest snapshot matching that prefix.
-rem
-    .command("restore <date>")
+addSharedCredentialOptions(rem.command("restore <date>"))
     .description("Restore from a REM snapshot (inspect by default; --apply rewinds Harper state)")
     .option("--agent <id>", "Agent id (or FLAIR_AGENT_ID env)")
     .option("--target <dir>", "Directory to extract into (default: <snapshot>.restored, only used without --apply)")
@@ -8674,12 +8567,24 @@ rem
     // --apply path: live replay via src/rem/restore.ts
     if (opts.apply) {
         const { applySnapshot } = await import("./rem/restore.js");
+        applyAdminPassFile(opts);
+        const restoreBase = process.env.FLAIR_URL || `http://127.0.0.1:${resolveHttpPort({})}`;
+        const adminPass = opts.dryRun ? undefined : resolveLocalAdminPass(opts.adminPass, !isLocalBase(restoreBase));
+        if (!opts.dryRun && !adminPass) {
+            console.error("Error: --admin-pass, --admin-pass-file, or FLAIR_ADMIN_PASS required for rem restore --apply " +
+                "(Soul rewrite is operator-only; an agent key is refused).");
+            process.exit(1);
+        }
+        const soulApiCall = adminPass
+            ? (method, path, body) => api(method, path, body, { explicitAdminPass: adminPass, adminUser: opts.adminUser, agentId: null })
+            : undefined;
         try {
             const result = await applySnapshot({
                 agentId,
                 snapshotPath: match.path,
                 flairVersion: __pkgVersion,
                 apiCall: api,
+                soulApiCall,
                 dryRun: !!opts.dryRun,
             });
             const verb = opts.dryRun ? "(dry-run) would" : "";
@@ -8690,7 +8595,7 @@ rem
                 console.log(`  Pre-restore:  ${result.preRestoreSnapshotPath}`);
                 console.log(`                (rollback: flair rem restore <pre-restore-date> --agent ${agentId} --apply)`);
             }
-            console.log(`  Deleted:      ${result.deleted.memories} memories, ${result.deleted.souls} souls`);
+            console.log(`  Deleted:      ${result.deleted.memories} memories, ${result.deleted.souls} souls, ${result.deleted.candidates} candidates`);
             console.log(`  Restored:     ${result.restored.memories} memories, ${result.restored.souls} souls`);
             if (result.errors.length > 0) {
                 console.log(`  Errors:`);
@@ -8737,16 +8642,32 @@ rem
 // Slice 1 of FLAIR-NIGHTLY-REM § 9. The pause sentinel is checked by the
 // nightly runner before any side effects. Env-var FLAIR_REM_PAUSE=1 is also
 // honored — lets ops pause fleet-wide without writing a file.
+// #1515: the same sentinel aborts an in-flight /ReflectMemories gather on
+// the Harper host (checked between yield points) so an operator can stop a
+// runaway run without restarting Harper.
 const REM_PAUSE_FLAG = resolve(homedir(), ".flair", "rem.paused");
-rem
-    .command("pause")
-    .description("Pause nightly REM runs — writes ~/.flair/rem.paused sentinel")
-    .action(() => {
+function writeRemPauseSentinel() {
     const dir = dirname(REM_PAUSE_FLAG);
     if (!existsSync(dir))
         mkdirSync(dir, { recursive: true, mode: 0o700 });
     writeFileSync(REM_PAUSE_FLAG, new Date().toISOString() + "\n", { mode: 0o600 });
+}
+rem
+    .command("pause")
+    .description("Pause nightly REM runs and abort an in-flight distillation gather")
+    .action(() => {
+    writeRemPauseSentinel();
     console.log(`✅ REM nightly runs paused (sentinel: ${REM_PAUSE_FLAG})`);
+    console.log(`   In-flight distillation will abort at the next yield.`);
+    console.log(`   Resume with: flair rem resume`);
+});
+rem
+    .command("abort")
+    .description("Abort an in-flight REM distillation (same sentinel as pause)")
+    .action(() => {
+    writeRemPauseSentinel();
+    console.log(`✅ REM abort requested (sentinel: ${REM_PAUSE_FLAG})`);
+    console.log(`   In-flight distillation will stop at the next yield; the scheduler stays paused.`);
     console.log(`   Resume with: flair rem resume`);
 });
 rem
@@ -8890,7 +8811,7 @@ export async function discoverLocalFlairPort(originalUrl) {
 // 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) {
+async function fetchHealthDetail(opts, signingAgentIdOverride, signingAgentSource) {
     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}`);
@@ -8926,6 +8847,7 @@ async function fetchHealthDetail(opts, signingAgentIdOverride) {
                 agentId: signingAgentIdOverride !== undefined
                     ? (signingAgentIdOverride ?? undefined)
                     : (opts.agent || process.env.FLAIR_AGENT_ID),
+                agentIdSource: signingAgentSource,
             });
         }
         catch {
@@ -8944,8 +8866,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 statusAgentId = resolveSigningAgentId(opts, "status");
-    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts, statusAgentId);
+    const { agentId: statusAgentId, source: statusSource } = resolveSigningAgentId(opts, "status");
+    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts, statusAgentId, statusSource);
     // 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."
@@ -10292,6 +10214,7 @@ program
     .command("upgrade")
     .description("Upgrade Flair — local packages by default, or a deployed Fabric with --target")
     .option("--check", "Only check for updates / show the plan, don't install or deploy")
+    .option("--tree <dir>", "Upgrade this extracted package tree in place (npm pack / plain-tree lane). Default: the serving instance's packed tree when that is not the npm-global install")
     .option("--restart", "[deprecated] no-op — restart now happens automatically after upgrade; use --no-restart to opt out")
     .option("--no-restart", "Skip the restart after upgrade (stage new packages now, restart later)")
     .option("--no-verify", "Skip post-restart health/version/auth verification (default: verify — so a broken upgrade can't report success; see flair#635)")
@@ -10313,7 +10236,7 @@ program
     // 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("--flair-version <semver>", "Flair version to deploy with --target, or to pin the plain-tree tarball swap (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)")
@@ -10338,6 +10261,48 @@ program
     const checkOnly = opts.check ?? false;
     const showAll = opts.all ?? false;
     console.log("Checking for updates...\n");
+    // flair#1109 (a): if the serving tree (or --tree) is a packed extract,
+    // take the in-place tarball lane instead of upgrading a leftover
+    // npm-global relic. (b) still probes — and still prints — when we are
+    // not taking that lane (git checkout, unknown path). Detection is
+    // best-effort and never fails the command except an explicit --tree
+    // that does not name a packed install (refuse, don't silently fall through).
+    const upgradeServingPid = resolveInstanceServingPid(defaultDataDir(), resolveHttpPort({}));
+    const upgradeNpmPrefix = await resolveNpmGlobalPrefix();
+    let treeDecision = { kind: "skip" };
+    try {
+        treeDecision = resolvePlainTreeTarget({
+            treeFlag: typeof opts.tree === "string" && opts.tree.trim() !== "" ? opts.tree.trim() : null,
+            serving: upgradeServingPid != null ? resolveServingFlairPackage(upgradeServingPid) : null,
+            cli: findFlairPackageDir(flairPackageDir()),
+            global: resolveNpmGlobalFlairPackage(upgradeNpmPrefix, process.platform),
+        });
+    }
+    catch { /* treat as skip — never fail the probe */ }
+    if (treeDecision.kind === "refuse") {
+        console.error(`❌ ${treeDecision.message}`);
+        process.exit(1);
+    }
+    const treeLane = treeDecision.kind === "use" ? treeDecision.inspection : null;
+    // flair#1109 (b): print the mismatch warning only when this run will
+    // still treat npm-global as the install. Collect always, so the (b)
+    // wiring test keeps seeing the call.
+    try {
+        const execPathWarning = collectUpgradeExecPathWarning({
+            servingPid: upgradeServingPid,
+            cliPackageDir: flairPackageDir(),
+            npmGlobalPrefix: upgradeNpmPrefix,
+        });
+        if (execPathWarning && !treeLane) {
+            console.log(execPathWarning);
+            console.log("");
+        }
+    }
+    catch { /* never fail upgrade over a path probe */ }
+    if (treeLane) {
+        console.log(formatPlainTreeBanner(treeLane));
+        console.log("");
+    }
     const packages = [
         {
             name: "@tpsdev-ai/flair",
@@ -10380,11 +10345,33 @@ program
         if (transitive && !showAll)
             continue;
         try {
-            const res = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(5000) });
-            if (!res.ok)
-                continue;
-            const data = await res.json();
-            const latest = data.version ?? "unknown";
+            let registryLatest = null;
+            try {
+                const res = await fetch(`https://registry.npmjs.org/${name}/latest`, { signal: AbortSignal.timeout(5000) });
+                if (res.ok) {
+                    const data = await res.json();
+                    registryLatest = typeof data.version === "string" && data.version ? data.version : null;
+                }
+            }
+            catch { /* /latest timed out or failed — pin path must still work */ }
+            let latest;
+            if (treeLane && name === FLAIR_PKG_NAME) {
+                // Consult registry latest, then apply --flair-version as the swap
+                // target. A pin still applies when /latest is unavailable; without
+                // that, a requested tarball swap reports up to date and does nothing.
+                const listing = resolvePlainTreeListingTarget({
+                    registryLatest,
+                    pin: typeof opts.flairVersion === "string" ? opts.flairVersion : null,
+                });
+                if (!listing)
+                    continue;
+                latest = listing.version;
+            }
+            else {
+                if (!registryLatest)
+                    continue;
+                latest = registryLatest;
+            }
             if (name === FLAIR_PKG_NAME && latest !== "unknown") {
                 try {
                     primeVersionCheckCache(latest);
@@ -10394,7 +10381,18 @@ program
             const globalProbe = probe();
             let installed;
             let status;
-            if (name === FLAIR_MCP_PACKAGE) {
+            if (treeLane && name === FLAIR_PKG_NAME) {
+                // The serving/CLI packed tree is the install. A PATH or
+                // require.resolve probe would report the npm-global relic.
+                installed = treeLane.version;
+                if (installed === null)
+                    status = "missing";
+                else if (installed === latest)
+                    status = "current";
+                else
+                    status = "outdated";
+            }
+            else if (name === FLAIR_MCP_PACKAGE) {
                 // flair-mcp is zero-install via npx (#1168) — a null global probe is
                 // the NORMAL state, not "missing". Resolve it from its actual wiring
                 // (the pin in a client MCP config / the SessionStart hook) so the
@@ -10436,7 +10434,12 @@ program
     }
     // Scope footer: make explicit what `flair upgrade` does and
     // doesn't cover, so "were the others checked?" has a one-line answer.
-    console.log("\nScope: npm-global packages (flair, flair-mcp) + openclaw plugins. Other integrations (pi-flair, langgraph-flair, n8n-nodes-flair, hermes-flair) upgrade in their own ecosystems (pi / pip / n8n).");
+    if (treeLane) {
+        console.log(`\n${formatPlainTreeScopeFooter(treeLane)}`);
+    }
+    else {
+        console.log("\nScope: npm-global packages (flair, flair-mcp) + openclaw plugins. Other integrations (pi-flair, langgraph-flair, n8n-nodes-flair, hermes-flair) upgrade in their own ecosystems (pi / pip / n8n).");
+    }
     const outdated = findings.filter((f) => f.status === "outdated");
     const missing = findings.filter((f) => f.status === "missing");
     // flair-mcp is refreshed by re-pinning its wiring (`flair doctor --fix` /
@@ -10457,6 +10460,20 @@ program
         .filter((f) => f.kind === "openclaw-plugin")
         .map(({ name, installed, latest }) => ({ pkg: name, installed: installed ?? "unknown", latest }));
     const totalUpgrades = npmUpgrades.length + openclawUpgrades.length;
+    let treePlan = null;
+    if (treeLane) {
+        const flairFindingForPlan = findings.find((f) => f.name === FLAIR_PKG_NAME);
+        treePlan = planPlainTreeUpgrade({
+            treeDir: treeLane.dir,
+            fromVersion: treeLane.version,
+            toVersion: flairFindingForPlan?.latest ?? treeLane.version ?? "unknown",
+            systemdUnits: findSystemdUnitsForTree(treeLane.dir),
+        });
+        if (flairFindingForPlan?.status === "outdated") {
+            console.log("");
+            console.log(formatPlainTreePlan(treePlan));
+        }
+    }
     if (outdated.length === 0 && missing.length === 0) {
         console.log("\n✅ Everything is up to date.");
         return;
@@ -10515,6 +10532,19 @@ program
             const result = client.wire(env);
             console.log(`   ${result.ok ? "✓" : "•"} ${result.message}`);
         }
+        // flair#1516: the SessionStart hook command carries the SAME
+        // @tpsdev-ai/flair-mcp@<version> pin as the client MCP block, but only
+        // the client block was refreshed above — so an upgraded user kept
+        // launching the PREVIOUS adapter on every session, silently, while
+        // `flair doctor` reported the hook "still runs". Re-pin every ALREADY-
+        // wired hook to the current spec too (never adds one — that stays an
+        // opt-in). Best-effort, same as the client refresh.
+        for (const harness of SUPPORTED_HARNESSES) {
+            const repin = repinSessionStartHook(homedir(), harness);
+            if (repin.action === "update") {
+                console.log(`   ${repin.ok ? "✓" : "•"} ${repin.message}`);
+            }
+        }
     }
     // Nothing to install via npm/openclaw. What is left is advisory (packages
     // not detected) and/or a flair-mcp whose wired pin is behind latest. The
@@ -10548,7 +10578,10 @@ program
         return;
     }
     if (checkOnly) {
-        console.log(`\n${outdated.length} update${outdated.length > 1 ? "s" : ""} available. Run: flair upgrade`);
+        const treeHint = typeof opts.tree === "string" && opts.tree.trim() !== ""
+            ? ` --tree ${opts.tree.trim()}`
+            : treeLane ? ` --tree ${treeLane.dir}` : "";
+        console.log(`\n${outdated.length} update${outdated.length > 1 ? "s" : ""} available. Run: flair upgrade${treeHint}`);
         if (missing.length > 0) {
             console.log(`${missing.length} package${missing.length > 1 ? "s" : ""} not detected${missing.length > 0 ? ": " + missing.map((f) => f.name).join(", ") : ""}.`);
         }
@@ -10662,7 +10695,7 @@ program
     let currentEngineVersion = null;
     let targetEngineVersion = null;
     if (flairIsUpgrading && hasDataDir) {
-        currentEngineVersion = readInstalledHarperVersion(flairPackageDir());
+        currentEngineVersion = readInstalledHarperVersion(treeLane?.dir ?? flairPackageDir());
         const targetFlairVersion = flairFinding?.latest;
         if (targetFlairVersion && currentEngineVersion) {
             targetEngineVersion = await fetchDeclaredHarperVersion(targetFlairVersion);
@@ -10723,6 +10756,12 @@ program
     let flairInstallFailed = false;
     for (const { pkg, latest } of npmUpgrades) {
         try {
+            if (treePlan && pkg === FLAIR_PKG_NAME) {
+                console.log(`  Fetching ${pkg}@${latest} (npm pack) and swapping ${treePlan.treeDir}...`);
+                await applyPlainTreeUpgrade(treePlan);
+                console.log(`  ✅ ${pkg}@${latest} installed (plain-tree swap; previous tree at ${treePlan.previousDir})`);
+                continue;
+            }
             console.log(`  Installing ${pkg}@${latest}...`);
             execFileSync("npm", ["install", "-g", `${pkg}@${latest}`], { stdio: "pipe" });
             console.log(`  ✅ ${pkg}@${latest} installed`);
@@ -10785,6 +10824,9 @@ program
     }
     if (!shouldRestart) {
         console.log("\nRun: flair restart to use the new version");
+        if (treePlan) {
+            console.log(`Previous tree kept at ${treePlan.previousDir} until you restart and verify.`);
+        }
         return;
     }
     console.log("\nRestarting Flair...");
@@ -10805,12 +10847,31 @@ program
     const rollbackTo = async (toVersion, reason) => {
         console.log(`\nRolling back @tpsdev-ai/flair to ${toVersion}...`);
         try {
-            execFileSync("npm", ["install", "-g", `@tpsdev-ai/flair@${toVersion}`], { stdio: "pipe" });
+            if (treePlan) {
+                const rollbackDecision = decidePlainTreeRollback(existsSync(treePlan.previousDir));
+                if (rollbackDecision.kind === "restore") {
+                    if (!restorePlainTreePrevious(treePlan)) {
+                        throw new Error(`no previous tree at ${treePlan.previousDir} to restore`);
+                    }
+                    console.log(`  ✅ restored previous tree from ${treePlan.previousDir}`);
+                }
+                else {
+                    console.log(`   (${rollbackDecision.reason})`);
+                }
+            }
+            else {
+                execFileSync("npm", ["install", "-g", `@tpsdev-ai/flair@${toVersion}`], { stdio: "pipe" });
+            }
         }
         catch (err) {
             console.error(`❌ rollback install failed: ${err.message}`);
             console.error(`   Flair is currently on the FAILED version (${expectedFlairVersion ?? "unknown"}) and is NOT running.`);
-            console.error(`   Recover by hand: npm install -g @tpsdev-ai/flair@${toVersion} && flair start`);
+            const prevExists = !!(treePlan && existsSync(treePlan.previousDir));
+            console.error(treePlan
+                ? (prevExists
+                    ? `   Recover by hand: restore ${treePlan.previousDir} to ${treePlan.treeDir} && flair start`
+                    : `   The live tree at ${treePlan.treeDir} was not swapped; there is no .upgrade-prev to restore. Start it with: flair start`)
+                : `   Recover by hand: npm install -g @tpsdev-ai/flair@${toVersion} && flair start`);
             process.exit(1);
         }
         // flair#1053: when the engine (Harper) version changed, the pre-upgrade
@@ -10859,9 +10920,16 @@ program
         }
         // Same post-swap rule as the upgrade restart above: the rolled-back
         // version's own CLI is the thing that knows how to start it.
-        const rolledBackCli = resolveInstalledFlairCli(flairPackageDir(), toVersion);
+        const rolledBackRoot = treePlan?.treeDir ?? flairPackageDir();
+        const rolledBackCli = resolveInstalledFlairCli(rolledBackRoot, toVersion);
         try {
-            await restartAfterUpgrade(port, upgradeDataDir, rolledBackCli.ok ? rolledBackCli : null);
+            if (treePlan && treePlan.systemdUnits.length > 0) {
+                console.log(`  (restarting systemd unit: ${treePlan.systemdUnits.map((u) => u.name).join(", ")})`);
+                restartSystemdUnits(treePlan.systemdUnits);
+            }
+            else {
+                await restartAfterUpgrade(port, upgradeDataDir, rolledBackCli.ok ? rolledBackCli : null);
+            }
         }
         catch (err) {
             console.error(`❌ rollback restart failed: ${err.message}`);
@@ -10914,9 +10982,10 @@ program
     // from disk AFTER the swap. `null` (flair itself wasn't swapped, or the new
     // tree can't be verified) falls back to an in-process restart, announced.
     const flairWasSwapped = flairIsUpgrading && !flairInstallFailed;
+    const swappedPackageRoot = treePlan?.treeDir ?? flairPackageDir();
     let newCli = null;
     if (flairWasSwapped) {
-        const resolved = resolveInstalledFlairCli(flairPackageDir(), expectedFlairVersion);
+        const resolved = resolveInstalledFlairCli(swappedPackageRoot, expectedFlairVersion);
         if (resolved.ok === false) {
             console.error(`warning: could not verify the newly installed CLI (${resolved.reason}) — restarting with this process's own code instead.`);
         }
@@ -10926,7 +10995,15 @@ program
     }
     let restartWasDelegated = false;
     try {
-        restartWasDelegated = await restartAfterUpgrade(port, upgradeDataDir, newCli);
+        if (treePlan && treePlan.systemdUnits.length > 0) {
+            console.log(`  (restarting systemd unit: ${treePlan.systemdUnits.map((u) => u.name).join(", ")})`);
+            restartSystemdUnits(treePlan.systemdUnits);
+            restartWasDelegated = true;
+            console.log("✅ Flair restarted (systemd unit)");
+        }
+        else {
+            restartWasDelegated = await restartAfterUpgrade(port, upgradeDataDir, newCli);
+        }
     }
     catch (err) {
         console.error(`❌ restart failed: ${err.message}`);
@@ -10963,6 +11040,9 @@ program
     const detached = isDetached(management);
     if (!shouldVerify) {
         console.log("  (--no-verify: skipping post-restart verification)");
+        if (treePlan) {
+            console.log(`  Previous tree kept at ${treePlan.previousDir} (rollback source; not discarded without verify).`);
+        }
         if (detached) {
             for (const line of renderDetachedWarning(management, "Flair is running, but NOT under launchd.")) {
                 console.error(line);
@@ -10996,6 +11076,8 @@ program
             toVersion: expectedFlairVersion,
         });
         printVerifiedSummary(renderVerifiedSummary(verify.version, run));
+        if (treePlan)
+            discardPlainTreePrevious(treePlan.previousDir);
         return;
     }
     // flair#741 follow-through: a healthy instance the verifier just couldn't
@@ -11026,6 +11108,8 @@ program
         console.log(`   The version could not be verified — the checker couldn't authenticate to /HealthDetail (${verdict.reason}).`);
         console.log("   The server is confirmed running (public /Health passed); this is a verification gap, not an upgrade failure — nothing was rolled back.");
         console.log("   To enable full post-upgrade verification: set FLAIR_ADMIN_PASS, or run `flair init` to provision ~/.flair/admin-pass or an agent key.");
+        if (treePlan)
+            discardPlainTreePrevious(treePlan.previousDir);
         return;
     }
     console.error(`❌ post-restart verification failed: ${verdict.reason}`);
@@ -12298,8 +12382,21 @@ program
     // is actually stamping new writes with.
     const EMBEDDING_PREFIXES_ENABLED = true; // MUST mirror resources/embeddings-provider.ts's gate
     const EMBEDDING_VARIANT = "searchprefix";
+    // embedding-space-guard slice 1: getModelId() now stamps the ENGINE-QUALIFIED
+    // id `<engine>:<base>[+searchprefix]`. Duplicated as a literal here (separate
+    // build target — see above). A row is CURRENT-SPACE iff its stamp is the
+    // qualified id OR its one-time bare-name equivalent (today's corpus, stamped
+    // before the qualifier). Treat BOTH as current so `--stale-only` never
+    // re-embeds an already-correct bare-stamped row — that would loop forever
+    // (Memory.put re-stamps it QUALIFIED, still "!= bare" under a single-value
+    // check). Keep in lockstep with resources/embeddings-provider.ts's
+    // getModelId()/EMBEDDING_ENGINE and resources/embedding-space-guard.ts's
+    // normalizeStamp().
+    const EMBEDDING_ENGINE = "gguf";
     const baseModel = process.env.FLAIR_EMBEDDING_MODEL ?? "nomic-embed-text-v1.5-Q4_K_M";
-    const currentModel = EMBEDDING_PREFIXES_ENABLED ? `${baseModel}+${EMBEDDING_VARIANT}` : baseModel;
+    const bareCurrentModel = EMBEDDING_PREFIXES_ENABLED ? `${baseModel}+${EMBEDDING_VARIANT}` : baseModel;
+    const currentModel = `${EMBEDDING_ENGINE}:${bareCurrentModel}`;
+    const isCurrentSpace = (stamp) => stamp === currentModel || stamp === bareCurrentModel;
     if (agentId) {
         console.log(`Re-embedding memories for agent: ${agentId}`);
     }
@@ -12358,7 +12455,7 @@ program
         for (const m of allMemories) {
             if (!m.content)
                 continue;
-            if (staleOnly && m.embeddingModel === currentModel)
+            if (staleOnly && isCurrentSpace(m.embeddingModel))
                 continue;
             const agent = m.agentId || "unknown";
             if (!byAgent.has(agent))
@@ -12463,7 +12560,7 @@ program
         if (!m.content)
             return false;
         if (staleOnly)
-            return !m.embeddingModel || m.embeddingModel !== currentModel;
+            return !m.embeddingModel || !isCurrentSpace(m.embeddingModel);
         return true;
     });
     const total = candidates.length;
@@ -13469,170 +13566,13 @@ program
             }
         }
         for (const client of detectedClients) {
-            // ── pi (flair#1342): NATIVE EXTENSION, not an MCP client ───────────
-            // There is no mcpServers block to read — pi loads @tpsdev-ai/pi-flair
-            // through its own settings.json (`packages`). Every check below is a
-            // filesystem fact except agent registration, which is only checkable
-            // when this shell exposes the env pi would launch with — and the
-            // output says which of the two it verified.
-            if (client.kind === "native-extension") {
-                let pi = checkPiFlairWiring(homedir(), process.cwd());
-                // --fix for pi needs no agent id (pi settings carry no env block);
-                // a resolvable id only improves the export hint in the message.
-                const wirePiFix = async (prompt) => {
-                    if (dryRun) {
-                        console.log(`     ${render.wrap(render.c.dim, "Would update")} ${pi.settingsPath}`);
-                        return;
-                    }
-                    const proceed = await confirmFix(prompt);
-                    if (!proceed) {
-                        console.log(`     Skipped.`);
-                        return;
-                    }
-                    const hintAgentId = resolveFixAgentId({
-                        optsAgent: opts.agent,
-                        envAgentId: process.env.FLAIR_AGENT_ID,
-                        anyKnownAgentId,
-                        keyAgentIds,
-                        keysDir: defaultKeysDir(),
-                    }) ?? "<your-agent-id>";
-                    const wireResult = wirePi({ FLAIR_AGENT_ID: hintAgentId, FLAIR_URL: baseUrl });
-                    console.log(`     ${wireResult.ok ? render.icons.ok : render.icons.warn} ${wireResult.message}`);
-                    if (wireResult.ok)
-                        fixed++;
-                };
-                // (a) The flair#1346 trap FIRST, and by NAME: an npm: spec under
-                // "extensions" is silently ignored by pi — the user believes they
-                // are wired while pi registers zero tools. This is the documented
-                // field failure mode and must never fold into a generic "not
-                // wired": the fix is a MOVE to "packages", not an add.
-                const userTraps = pi.misconfigured.filter((m) => m.path === pi.settingsPath);
-                const projectTraps = pi.misconfigured.filter((m) => m.path !== pi.settingsPath);
-                for (const bad of pi.misconfigured) {
-                    console.log(`  ${render.icons.error} pi: ${PI_FLAIR_PACKAGE} is listed under "extensions" as an npm: spec (${bad.entry}) in ${render.wrap(render.c.dim, bad.path)}`);
-                    console.log(`     pi silently ignores npm: specs under "extensions", so the Flair tools never register (flair#1346). Package sources belong under "packages".`);
-                    issues++;
-                }
-                if (userTraps.length > 0) {
-                    if (autoFix) {
-                        await wirePiFix(`  Move the npm: spec to "packages" in ${pi.settingsPath} now? [y/N] `);
-                        // Re-derive the wiring from disk so the sections below reason
-                        // about the POST-fix state — otherwise a move that just
-                        // succeeded would still read as "not wired" and prompt again.
-                        pi = checkPiFlairWiring(homedir(), process.cwd());
-                    }
-                    else {
-                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, `(moves it to "packages")`)}`);
-                    }
-                }
-                if (projectTraps.length > 0) {
-                    // wirePi edits the USER-scope settings only — a project-scope
-                    // trap gets the exact manual fix, never a --fix that claims a
-                    // file it does not touch.
-                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} move the entry from "extensions" to "packages" in ${projectTraps[0].path}`);
-                }
-                if (!pi.wired) {
-                    console.log(`  ${render.icons.error} pi: ${PI_FLAIR_PACKAGE} not wired in ${render.wrap(render.c.dim, pi.settingsPath)}`);
-                    if (autoFix) {
-                        await wirePiFix(`  Wire pi now (adds ${piFlairSpec()} to "packages" in ${pi.settingsPath})? [y/N] `);
-                    }
-                    else {
-                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, `(adds ${piFlairSpec()} to "packages")`)} — or: pi install npm:${PI_FLAIR_PACKAGE}`);
-                    }
-                    issues++;
-                    continue;
-                }
-                if (pi.wiredVia === "packages") {
-                    console.log(`  ${render.icons.ok} pi: ${PI_FLAIR_PACKAGE} wired via "packages" (${pi.spec}) in ${render.wrap(render.c.dim, pi.wiredIn)}`);
-                    if (!pi.pinnedVersion) {
-                        console.log(`     ${render.icons.info} unpinned — pi re-resolves latest on (re)install; pin with ${piFlairSpec()}`);
-                    }
-                }
-                else {
-                    // extension-path: the documented pre-0.49 workaround (a local
-                    // path to the installed dist/index.js). Works, but the canonical
-                    // form is a "packages" entry — and a DANGLING path is a broken
-                    // wiring pi skips silently, so check the one thing checkable.
-                    if (pi.extensionPathExists) {
-                        console.log(`  ${render.icons.ok} pi: ${PI_FLAIR_PACKAGE} wired via a file-path "extensions" entry (${pi.spec}) in ${render.wrap(render.c.dim, pi.wiredIn)}`);
-                        console.log(`     ${render.wrap(render.c.dim, `pre-0.49 workaround — the canonical form is a "packages" entry: ${piFlairSpec()}`)}`);
-                    }
-                    else {
-                        console.log(`  ${render.icons.error} pi: the "extensions" entry ${pi.spec} in ${render.wrap(render.c.dim, pi.wiredIn)} points at a file that does not exist — pi silently skips missing extension paths`);
-                        if (autoFix) {
-                            await wirePiFix(`  Wire pi via "packages" instead (adds ${piFlairSpec()})? [y/N] `);
-                        }
-                        else {
-                            console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, `(adds ${piFlairSpec()} to "packages"; remove the dangling entry yourself)`)}`);
-                        }
-                        issues++;
-                        continue;
-                    }
-                }
-                // Env sanity (flair#1342 scope 3). pi settings carry no env block:
-                // pi-flair reads FLAIR_* from the environment of whatever shell/IDE
-                // launches pi. Doctor can only see ITS OWN environment — these
-                // lines verify this shell, and say so, rather than pretending to
-                // verify every pi launch. None of them counts as an issue: a clean
-                // pi launched elsewhere can be fine while this shell is bare, and
-                // vice versa.
-                console.log(`     ${render.wrap(render.c.dim, "pi-flair reads FLAIR_AGENT_ID / FLAIR_URL / FLAIR_KEY_PATH from the shell that launches pi — doctor sees only its own environment (this shell):")}`);
-                const piEnvAgent = process.env.FLAIR_AGENT_ID;
-                const piEnvUrl = process.env.FLAIR_URL;
-                const piEnvKey = process.env.FLAIR_KEY_PATH;
-                if (piEnvAgent) {
-                    console.log(`     ${render.icons.ok} FLAIR_AGENT_ID set ('${piEnvAgent}')`);
-                }
-                else {
-                    console.log(`     ${render.icons.warn} FLAIR_AGENT_ID not set in this shell — pi-flair falls back to the cwd directory name as its agent id (identity varies by project); export FLAIR_AGENT_ID=<id> where pi is launched`);
-                }
-                if (piEnvUrl) {
-                    console.log(`     ${render.icons.ok} FLAIR_URL set (${piEnvUrl})`);
-                }
-                else {
-                    console.log(`     ${render.icons.info} FLAIR_URL not set — pi-flair defaults to ${render.wrap(render.c.dim, PI_FLAIR_DEFAULT_URL)}`);
-                }
-                if (piEnvKey) {
-                    if (existsSync(piEnvKey)) {
-                        console.log(`     ${render.icons.ok} FLAIR_KEY_PATH set (${piEnvKey})`);
-                    }
-                    else {
-                        console.log(`     ${render.icons.warn} FLAIR_KEY_PATH points at a missing file (${piEnvKey})`);
-                    }
-                }
-                else {
-                    console.log(`     ${render.icons.info} FLAIR_KEY_PATH not set — auto-resolved from ~/.flair/keys`);
-                }
-                // Agent registration — checkable only when this shell exposes an
-                // agent id at all; otherwise say what was NOT verified instead of
-                // skipping silently.
-                if (piEnvAgent) {
-                    const piUrl = piEnvUrl || PI_FLAIR_DEFAULT_URL;
-                    const piReachable = await probeFlairReachable(piUrl);
-                    if (!piReachable) {
-                        console.log(`     ${render.icons.warn} FLAIR_URL ${render.wrap(render.c.dim, piUrl)} not reachable — cannot verify agent registration`);
-                    }
-                    else {
-                        const piReg = await checkAgentRegistered(piUrl, piEnvAgent, defaultKeysDir());
-                        if (piReg.state === "registered") {
-                            console.log(`     ${render.icons.ok} agent '${piEnvAgent}' registered`);
-                        }
-                        else if (piReg.state === "not-registered") {
-                            console.log(`     ${render.icons.error} agent '${piEnvAgent}' is NOT registered on this Flair instance`);
-                            console.log(`        ${render.wrap(render.c.dim, "Fix:")} flair agent add ${piEnvAgent}`);
-                            issues++;
-                        }
-                        else {
-                            const piFinding = describeAgentGateFinding(piEnvAgent, piReg.state, piReg.detail, { instanceReachable: piReachable });
-                            console.log(`     ${render.icons.warn} ${piFinding?.message ?? `could not verify agent registration (${piReg.detail})`}`);
-                        }
-                    }
-                }
-                else {
-                    console.log(`     ${render.wrap(render.c.dim, "agent registration not verified — no FLAIR_AGENT_ID visible to doctor")}`);
-                }
+            // flair#989 — pi is a dead namespace: the pi (kind:
+            // "native-extension") check is removed from doctor entirely. pi was
+            // the last non-MCP client here, and a detected-but-unwired pi was
+            // counted as an install failure for a namespace nobody opts into any
+            // more. Doctor now diagnoses only MCP clients the user wired (below).
+            if (client.kind !== "mcp")
                 continue;
-            }
             const block = readClientMcpBlock(client.id, homedir());
             if (client.id === "claude-code" && block.agentId)
                 claudeCodeAgentId = block.agentId;
@@ -13641,7 +13581,12 @@ program
             if (block.agentId)
                 anyKnownAgentId = anyKnownAgentId ?? block.agentId;
             if (!block.present) {
-                console.log(`  ${render.icons.error} ${client.label}: no Flair MCP server configured in ${render.wrap(render.c.dim, block.configPath)}`);
+                // flair#989: this client is DETECTED (binary/config on the box) but
+                // was never wired to Flair — the user did not opt into it. That is
+                // not an install FAILURE, so it renders as info, never a ✗, and is
+                // not counted (the catalog's opt-in mcp-block check owns the count).
+                // `--fix` still offers to wire it, on the user's y/N consent.
+                console.log(`  ${render.icons.info} ${client.label}: detected but not wired to Flair — optional (no Flair MCP server in ${render.wrap(render.c.dim, block.configPath)})`);
                 if (autoFix) {
                     if (dryRun) {
                         console.log(`     ${render.wrap(render.c.dim, "Would wire")} ${client.label} (writes ${block.configPath})`);
@@ -13702,7 +13647,7 @@ program
                     // `--fix` already works, so don't clutter the suggestion.
                     const knownAgentId = opts.agent || process.env.FLAIR_AGENT_ID || anyKnownAgentId;
                     const agentHint = knownAgentId ? "" : fixCommandAgentHint(keyAgentIds);
-                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix${agentHint} ${render.wrap(render.c.dim, `(wires ${client.label} automatically)`)}`);
+                    console.log(`     ${render.wrap(render.c.dim, "To wire it (optional):")} flair doctor --fix${agentHint} ${render.wrap(render.c.dim, `(wires ${client.label})`)}`);
                 }
                 continue;
             }
@@ -13739,10 +13684,25 @@ program
                 console.log(`     ${render.icons.warn} ${finding?.message ?? `could not verify agent registration (${reg.detail})`}`);
             }
         }
+        // flair#989: the harness-specific checks below (CLAUDE.md, SessionStart
+        // hook, continuity, Codex hook) run only for a harness the user actually
+        // WIRED — its MCP block is present. A harness merely DETECTED on the box
+        // but never opted into owes none of these; flagging them was the false-
+        // positive this fix removes. Read the block fresh so a `--fix` that just
+        // wired the client during the loop above is reflected here.
+        const claudeCodeDetected = detectedClients.some((c) => c.id === "claude-code");
+        const claudeCodeConfigured = claudeCodeDetected && readClientMcpBlock("claude-code", homedir()).present;
+        const codexConfigured = detectedClients.some((c) => c.id === "codex") && readClientMcpBlock("codex", homedir()).present;
         // Claude-Code-specific: CLAUDE.md + SessionStart hook + continuity.
         // Codex has a SessionStart hook too (checked below); CLAUDE.md and
         // continuity stay Claude Code only.
-        if (detectedClients.some((c) => c.id === "claude-code")) {
+        //
+        // flair#989: CLAUDE.md and the SessionStart hook are wiring-dependent —
+        // they apply, and can only fail, once Claude Code is WIRED — so they are
+        // gated on `claudeCodeConfigured`. Continuity (below) is a separate
+        // opt-in that renders "not enabled" as info and never a failure, so it
+        // stays gated on mere detection (flair#1324/#1257).
+        if (claudeCodeConfigured) {
             const claudeMd = checkClaudeMdBootstrap(process.cwd(), homedir());
             if (claudeMd.present) {
                 console.log(`  ${render.icons.ok} CLAUDE.md: bootstrap instruction present (${render.wrap(render.c.dim, claudeMd.path)})`);
@@ -13816,6 +13776,30 @@ program
                 else {
                     console.log(`  ${render.icons.ok} SessionStart hook: flair-session-start wired in ${render.wrap(render.c.dim, hook.path)} ${render.wrap(render.c.dim, "and still runs")}`);
                 }
+                // flair#1516: a hook can be wired AND still run yet be pinned to a
+                // DIFFERENT @tpsdev-ai/flair-mcp version than the Claude Code MCP
+                // client — an upgrade refreshed the client block but (pre-#1516)
+                // left the hook behind, so every session silently launched the OLD
+                // adapter. "and still runs" never caught this; compare the two pins.
+                const claudeHookSkew = checkSessionStartHookPinSkew(homedir(), "claude-code");
+                if (claudeHookSkew.skewed) {
+                    console.log(`  ${render.icons.warn} SessionStart hook: pinned to flair-mcp@${claudeHookSkew.hookPin} but the Claude Code MCP client is pinned to @${claudeHookSkew.clientPin} — the hook still launches the OLD adapter on every session`);
+                    if (autoFix) {
+                        if (dryRun) {
+                            console.log(`     ${render.wrap(render.c.dim, "Would re-pin the SessionStart hook in")} ${hook.path}`);
+                        }
+                        else {
+                            const repin = repinSessionStartHook(homedir(), "claude-code");
+                            console.log(`     ${repin.ok ? render.icons.ok : render.icons.warn} ${repin.message}`);
+                            if (repin.ok && repin.action === "update")
+                                fixed++;
+                        }
+                    }
+                    else {
+                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install ${render.wrap(render.c.dim, "(re-pins the hook to the current version)")}`);
+                    }
+                    issues++;
+                }
                 // Independent of whether it runs today: would it stay quiet if it
                 // stopped? Only offered as a repair when the command is the exact
                 // string Flair itself wrote — a hand-edited or pinned hook is the
@@ -13869,6 +13853,10 @@ program
                     console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(adds the flair-session-start SessionStart hook)")}`);
                 }
             }
+        } // end CLAUDE.md + SessionStart hook (claudeCodeConfigured)
+        // Continuity capture is a standalone Claude Code opt-in — shown whenever
+        // Claude Code is DETECTED, independent of MCP wiring (flair#1324/#1257).
+        if (claudeCodeDetected) {
             // flair#1257 slice 2 — continuity capture pair (the check-5 twin of
             // the SessionStart check above: installed / absent / stale-form).
             // Continuity is OPT-IN — installing the PostToolUse+Stop pair IS the
@@ -13926,7 +13914,7 @@ program
         // command Claude Code uses, written to ~/.codex/hooks.json. Continuity
         // and CLAUDE.md stay Claude-Code-only; Codex's session-start mechanism
         // is the hook file.
-        if (detectedClients.some((c) => c.id === "codex")) {
+        if (codexConfigured) {
             const hook = inspectSessionStartHook(homedir(), { settingsPath: hookSettingsPath(homedir(), "codex") });
             if (hook.present) {
                 if (hook.execution === "broken") {
@@ -13952,6 +13940,28 @@ program
                 else {
                     console.log(`  ${render.icons.ok} SessionStart hook (codex): flair-session-start wired in ${render.wrap(render.c.dim, hook.path)} ${render.wrap(render.c.dim, "and still runs")}`);
                 }
+                // flair#1516: same version-skew check as Claude Code — a Codex hook
+                // left behind by an upgrade keeps launching the OLD adapter while
+                // the Codex MCP block advertises the new pin.
+                const codexHookSkew = checkSessionStartHookPinSkew(homedir(), "codex");
+                if (codexHookSkew.skewed) {
+                    console.log(`  ${render.icons.warn} SessionStart hook (codex): pinned to flair-mcp@${codexHookSkew.hookPin} but the Codex MCP client is pinned to @${codexHookSkew.clientPin} — the hook still launches the OLD adapter on every session`);
+                    if (autoFix) {
+                        if (dryRun) {
+                            console.log(`     ${render.wrap(render.c.dim, "Would re-pin the SessionStart hook in")} ${hook.path}`);
+                        }
+                        else {
+                            const repin = repinSessionStartHook(homedir(), "codex");
+                            console.log(`     ${repin.ok ? render.icons.ok : render.icons.warn} ${repin.message}`);
+                            if (repin.ok && repin.action === "update")
+                                fixed++;
+                        }
+                    }
+                    else {
+                        console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install --harness codex ${render.wrap(render.c.dim, "(re-pins the hook to the current version)")}`);
+                    }
+                    issues++;
+                }
                 if (!hook.silenced && hook.ours) {
                     console.log(`  ${render.icons.warn} SessionStart hook (codex): a failure would print an error on every session (this command predates the silent-failure fix)`);
                     if (hook.upgradable) {
@@ -14484,11 +14494,13 @@ export const QUALITY_RECALL_K = 5;
  * pulls embedding vectors inline — the defect in flair#1360 was an
  * unfiltered `GET /Memory?agentId=…` that returned every row's 768-d
  * vector (~66 MB × 2 per `--emit` run on a 3k-row store) just to sample
- * 10 memories. `type` is intentionally omitted: it is not a declared
- * Memory column (see schemas/memory.graphql); snapshot exclusion keys
- * off `subject` (`quality-snapshot/…`).
+ * 10 memories. `archived` is projected so the planner can drop basemented
+ * rows before sampling (flair#857 — SemanticSearch excludes them, so an
+ * archived row in the sample is a guaranteed miss). `type` is intentionally
+ * omitted: it is not a declared Memory column (see schemas/memory.graphql);
+ * snapshot exclusion keys off `subject` (`quality-snapshot/…`).
  */
-export const QUALITY_MEMORY_LIST_SELECT = ["id", "subject", "content", "createdAt"];
+export const QUALITY_MEMORY_LIST_SELECT = ["id", "subject", "content", "createdAt", "archived"];
 /**
  * Extra most-recent rows fetched beyond `sampleSize` so
  * `planRecallSpotCheck` can drop the sweep's own quality-snapshot
@@ -14635,20 +14647,26 @@ function isQualitySnapshotRow(m) {
  * fail-closed health rules are testable without any I/O (flair#967).
  *
  * Order of operations, and why:
- *  1. drop the tool's own quality-snapshot rows (never grade your own
+ *  1. drop archived rows (SemanticSearch excludes them — flair#857 — so a
+ *     basemented row in the sample is a guaranteed miss, not a recall signal);
+ *  2. drop the tool's own quality-snapshot rows (never grade your own
  *     bookkeeping);
- *  2. take the `sampleSize` most-recently-written remaining rows (unchanged —
+ *  3. take the `sampleSize` most-recently-written remaining rows (unchanged —
  *     recency is still the sampling frame; see the issue's direction 3 for the
  *     stratified-sampling follow-up this deliberately does NOT take on);
- *  3. derive each cue via deriveRecallCue;
- *  4. judge the window: any duplicate cue, or any empty cue, makes it
+ *  4. derive each cue via deriveRecallCue;
+ *  5. judge the window: any duplicate cue, or any empty cue, makes it
  *     UNSCORABLE — reported as unhealthy, never silently scored.
  */
 export function planRecallSpotCheck(memories, opts = {}) {
     const sampleSize = opts.sampleSize ?? QUALITY_RECALL_SAMPLE_SIZE;
     const rows = Array.isArray(memories) ? memories : [];
-    const scorable = rows.filter((m) => !isQualitySnapshotRow(m ?? {}));
-    const excludedSnapshotRows = rows.length - scorable.length;
+    // `archived !== true` matches SemanticSearch / AdminMemory: unset and
+    // false stay in the live pool; only an explicit basement is dropped.
+    const live = rows.filter((m) => m?.archived !== true);
+    const scorable = live.filter((m) => !isQualitySnapshotRow(m ?? {}));
+    const excludedArchivedRows = rows.length - live.length;
+    const excludedSnapshotRows = live.length - scorable.length;
     const sorted = scorable.slice().sort((a, b) => {
         const ta = a?.createdAt ? new Date(a.createdAt).getTime() : 0;
         const tb = b?.createdAt ? new Date(b.createdAt).getTime() : 0;
@@ -14666,7 +14684,7 @@ export function planRecallSpotCheck(memories, opts = {}) {
     }
     const duplicateCues = [...counts.entries()].filter(([, n]) => n > 1).map(([cue]) => cue);
     if (duplicateCues.length === 0 && emptyCueCount === 0) {
-        return { sampled, health: { healthy: true }, excludedSnapshotRows };
+        return { sampled, health: { healthy: true }, excludedSnapshotRows, excludedArchivedRows };
     }
     const parts = [];
     if (duplicateCues.length > 0) {
@@ -14686,6 +14704,7 @@ export function planRecallSpotCheck(memories, opts = {}) {
             emptyCueCount,
         },
         excludedSnapshotRows,
+        excludedArchivedRows,
     };
 }
 /**
@@ -14910,13 +14929,21 @@ export async function fetchRecallSpotCheckData(agentId, baseUrl, opts = {}) {
         return { ok: false, agentId, skipReason: `could not fetch memories to sample: ${err?.message ?? String(err)}` };
     }
     // Deterministic sample + cue derivation + fail-closed health judgment, all
-    // pure (planRecallSpotCheck above). Snapshot rows are excluded there, so the
-    // "enough memories" check has to run on the PLANNED window, not on the raw
-    // row count — an instance whose recent writes are mostly the sweep's own
-    // bookkeeping should skip with a reason, not score a short window.
+    // pure (planRecallSpotCheck above). Archived rows (flair#857) and snapshot
+    // rows are excluded there, so the "enough memories" check has to run on the
+    // PLANNED window, not on the raw row count — an instance whose recent writes
+    // are mostly basemented or the sweep's own bookkeeping should skip with a
+    // reason, not score a short window.
     const plan = planRecallSpotCheck(all, { sampleSize });
     if (plan.sampled.length < sampleSize) {
-        const excluded = plan.excludedSnapshotRows > 0 ? ` (${plan.excludedSnapshotRows} quality-snapshot row(s) excluded — the spot-check never grades its own bookkeeping)` : "";
+        const exclusionParts = [];
+        if (plan.excludedArchivedRows > 0) {
+            exclusionParts.push(`${plan.excludedArchivedRows} archived row(s) excluded — SemanticSearch cannot return basemented memories; restore with \`flair memory restore <id>\` if they should be live`);
+        }
+        if (plan.excludedSnapshotRows > 0) {
+            exclusionParts.push(`${plan.excludedSnapshotRows} quality-snapshot row(s) excluded — the spot-check never grades its own bookkeeping`);
+        }
+        const excluded = exclusionParts.length > 0 ? ` (${exclusionParts.join("; ")})` : "";
         return {
             ok: false,
             agentId,
@@ -15198,7 +15225,7 @@ export async function fetchPreviousQualitySnapshot(agentId, baseUrl, subject, op
  *  `PUT /Memory/{id}` write shape `memory write-task-summary` already uses.
  *  Throws on a write failure — the CLI action below is responsible for
  *  surfacing that as a clear error, same as every other write path here. */
-async function storeQualitySnapshot(agentId, baseUrl, subject, snapshot) {
+async function storeQualitySnapshot(agentId, agentIdSource, baseUrl, subject, snapshot) {
     const memId = `${agentId}-quality-snapshot-${Date.now()}`;
     const body = {
         id: memId,
@@ -15210,7 +15237,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, agentId });
+    const out = await api("PUT", `/Memory/${encodeURIComponent(memId)}`, body, { baseUrl, agentId, agentIdSource });
     if (out?.error)
         throw new Error(String(out.error));
     return memId;
@@ -15226,8 +15253,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 agentId = resolveSigningAgentId(opts, "quality");
-    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts, agentId);
+    const { agentId, source } = resolveSigningAgentId(opts, "quality");
+    const { healthy, baseUrl, healthData } = await fetchHealthDetail(opts, agentId, source);
     if (opts.emit && !agentId) {
         console.error("Error: --emit requires an agent identity. Pass --agent <id> or set FLAIR_AGENT_ID.");
         process.exit(1);
@@ -15270,7 +15297,7 @@ program
             }
         }
         try {
-            emitResult.snapshotId = await storeQualitySnapshot(agentId, baseUrl, subject, current);
+            emitResult.snapshotId = await storeQualitySnapshot(agentId, source, baseUrl, subject, current);
         }
         catch (err) {
             emitResult.errors.push(`snapshot store failed: ${err?.message ?? String(err)}`);
@@ -15651,7 +15678,7 @@ addSharedCredentialOptions(addSharedIdentityOption(memory.command("add [content]
         process.exit(1);
     }
     applyAdminPassFile(opts);
-    const agentId = resolveSigningAgentId(opts, "memory add");
+    const { agentId, source } = resolveSigningAgentId(opts, "memory add");
     if (!agentId) {
         console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
         process.exit(2);
@@ -15693,6 +15720,7 @@ addSharedCredentialOptions(addSharedIdentityOption(memory.command("add [content]
     }
     const out = await api("PUT", `/Memory/${memId}`, body, {
         agentId,
+        agentIdSource: source,
         explicitAdminPass: opts.adminPass,
         adminUser: opts.adminUser,
     });
@@ -15750,7 +15778,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 { agentId, source } = resolveSigningAgentId(opts, "memory write-task-summary");
     const memId = `${opts.agent}-task-${opts.beads}-${Date.now()}`;
     const body = {
         id: memId,
@@ -15767,7 +15795,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, { agentId });
+    const out = await api("PUT", `/Memory/${encodeURIComponent(memId)}`, body, { agentId, agentIdSource: source });
     if (out?.error) {
         console.error(`Error writing task summary: ${out.error}`);
         process.exit(1);
@@ -15779,6 +15807,7 @@ memory.command("write-task-summary")
 memory.command("search [query]")
     .description("Semantic search over an agent's memories (query via positional arg or --q)")
     .option("--agent <id>", "Agent ID (or set FLAIR_AGENT_ID env)")
+    .option("--admin-pass <pass>", "Admin password — sign as admin while --agent names whose memories to search (flair#1500: a flag-pinned agent with no key no longer falls back to FLAIR_ADMIN_PASS)")
     .option("--q <query>", "search query (alias for positional arg)")
     .option("--limit <n>", "Max results", "5")
     .option("--tag <tag>")
@@ -15787,7 +15816,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 = resolveSigningAgentId(opts, "memory search");
+    const { agentId, source } = resolveSigningAgentId(opts, "memory search");
     if (!agentId) {
         console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
         process.exit(2);
@@ -15803,7 +15832,7 @@ memory.command("search [query]")
     if (opts.includeArchived)
         body.includeArchived = true;
     const baseUrl = resolveBaseUrl(opts);
-    const res = await api("POST", "/SemanticSearch", body, { baseUrl, agentId });
+    const res = await api("POST", "/SemanticSearch", body, { baseUrl, agentId, agentIdSource: source, explicitAdminPass: opts.adminPass });
     console.log(JSON.stringify(res, null, 2));
 });
 // ─── flair memory basement / restore ────────────────────────────────────────
@@ -15820,13 +15849,13 @@ memory.command("basement <id>")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--port <port>", "Harper HTTP port")
     .action(async (id, opts) => {
-    const agentId = resolveSigningAgentId(opts, "memory basement");
+    const { agentId, source } = resolveSigningAgentId(opts, "memory basement");
     if (!agentId) {
         console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
         process.exit(2);
     }
     const baseUrl = resolveBaseUrl(opts);
-    const res = await api("POST", "/MemoryArchive", { id, action: "basement" }, { baseUrl, agentId });
+    const res = await api("POST", "/MemoryArchive", { id, action: "basement" }, { baseUrl, agentId, agentIdSource: source });
     console.log(JSON.stringify(res, null, 2));
 });
 memory.command("restore <id>")
@@ -15836,13 +15865,13 @@ memory.command("restore <id>")
     .option("--url <url>", "Flair base URL (overrides --port)")
     .option("--port <port>", "Harper HTTP port")
     .action(async (id, opts) => {
-    const agentId = resolveSigningAgentId(opts, "memory restore");
+    const { agentId, source } = resolveSigningAgentId(opts, "memory restore");
     if (!agentId) {
         console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
         process.exit(2);
     }
     const baseUrl = resolveBaseUrl(opts);
-    const res = await api("POST", "/MemoryArchive", { id, action: "restore" }, { baseUrl, agentId });
+    const res = await api("POST", "/MemoryArchive", { id, action: "restore" }, { baseUrl, agentId, agentIdSource: source });
     console.log(JSON.stringify(res, null, 2));
 });
 memory.command("list")
@@ -15853,13 +15882,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 = resolveSigningAgentId(opts, "memory list");
+    const { agentId, source } = 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}`, undefined, { agentId });
+    const raw = await api("GET", `/Memory?${q}`, undefined, { agentId, agentIdSource: source });
     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.
@@ -16191,7 +16220,7 @@ program
     .option("--json", "Output raw JSON array")
     .action(async (query, opts) => {
     try {
-        const agentId = resolveSigningAgentId(opts, "search");
+        const { agentId } = resolveSigningAgentId(opts, "search");
         if (!agentId) {
             console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
             process.exit(2);
@@ -16351,7 +16380,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 = resolveSigningAgentId(opts, "bootstrap");
+    const { agentId, source } = resolveSigningAgentId(opts, "bootstrap");
     if (!agentId) {
         console.error(`${render.icons.error} --agent <id> required (or set FLAIR_AGENT_ID)`);
         process.exit(2);
@@ -16366,7 +16395,7 @@ program
         // finds a usable key. Previously this only ever tried Ed25519 (no
         // admin fallback at all) and sent NO Authorization header when no key
         // was found, relying on Harper's local passthrough.
-        const result = (await authedRequest("POST", "/BootstrapMemories", { agentId, maxTokens: parseInt(opts.maxTokens, 10) }, { baseUrl, agentId, explicitKeyPath: opts.key }));
+        const result = (await authedRequest("POST", "/BootstrapMemories", { agentId, maxTokens: parseInt(opts.maxTokens, 10) }, { baseUrl, agentId, agentIdSource: source, explicitKeyPath: opts.key }));
         if (mode === "json") {
             // Agent-first: emit the full server response, augmented with the cap
             // that was requested. Includes context, sections, tokenEstimate, etc.
@@ -16446,7 +16475,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 { agentId, source } = resolveSigningAgentId(opts, "relationship add");
     const id = canonicalRelationshipId(opts.agent, opts.subject, opts.predicate, opts.object);
     const body = {
         id,
@@ -16463,11 +16492,11 @@ relationship.command("add")
         body.validTo = opts.validTo;
     if (opts.source)
         body.source = opts.source;
-    const out = await api("PUT", `/Relationship/${id}`, body, { agentId });
+    const out = await api("PUT", `/Relationship/${id}`, body, { agentId, agentIdSource: source });
     console.log(JSON.stringify(out, null, 2));
 });
 const soul = program.command("soul").description("Manage agent soul entries");
-soul.command("set")
+addSharedCredentialOptions(soul.command("set"))
     .description("Set (upsert) a soul entry for an agent by key")
     .requiredOption("--agent <id>")
     .requiredOption("--key <key>")
@@ -16475,6 +16504,7 @@ soul.command("set")
     .option("--durability <d>", "permanent|persistent|standard|ephemeral (default permanent — soul entries are identity, not working memory)")
     .option("--json", "Emit raw JSON response (also: pipe + FLAIR_OUTPUT=json)")
     .action(async (opts) => {
+    applyAdminPassFile(opts);
     // 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)
@@ -16484,7 +16514,7 @@ soul.command("set")
     // 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 { agentId, source } = resolveSigningAgentId(opts, "soul set");
     const id = `${opts.agent}:${opts.key}`;
     const out = await api("PUT", `/Soul/${encodeURIComponent(id)}`, {
         id,
@@ -16493,7 +16523,7 @@ soul.command("set")
         value: opts.value,
         durability: opts.durability,
         createdAt: new Date().toISOString(),
-    }, { agentId });
+    }, { agentId, agentIdSource: source, explicitAdminPass: opts.adminPass, adminUser: opts.adminUser });
     const mode = render.resolveOutputMode(opts);
     if (mode === "json") {
         console.log(render.asJSON(out));
@@ -16515,8 +16545,8 @@ soul.command("get")
     // 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 { agentId, source } = resolveSigningAgentId(opts, "soul get");
+    const out = await api("GET", `/Soul/${id}`, undefined, { agentId, agentIdSource: source });
     const mode = render.resolveOutputMode(opts);
     if (mode === "json") {
         console.log(render.asJSON(out));
@@ -16548,12 +16578,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 = resolveSigningAgentId(opts, "soul list");
+    const { agentId, source } = 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)}`, undefined, { agentId });
+    const out = await api("GET", `/Soul?agentId=${encodeURIComponent(agentId)}`, undefined, { agentId, agentIdSource: source });
     const mode = render.resolveOutputMode(opts);
     if (mode === "json") {
         console.log(render.asJSON(out));
@@ -17379,19 +17409,7 @@ program
             console.warn(`  warn: agent ${agent.id}: ${err.message}`);
         }
     }
-    // Restore memories
-    console.log("Restoring memories...");
-    let memoryCount = 0;
-    for (const memory of memories) {
-        try {
-            await adminPut(`/Memory/${memory.id}`, memory);
-            memoryCount++;
-        }
-        catch (err) {
-            console.warn(`  warn: memory ${memory.id}: ${err.message}`);
-        }
-    }
-    // Restore souls
+    // Restore souls before memories: refuseLearnedSoulWrite matches Memory text.
     console.log("Restoring souls...");
     let soulCount = 0;
     for (const soul of souls) {
@@ -17403,6 +17421,17 @@ program
             console.warn(`  warn: soul ${soul.id}: ${err.message}`);
         }
     }
+    console.log("Restoring memories...");
+    let memoryCount = 0;
+    for (const memory of memories) {
+        try {
+            await adminPut(`/Memory/${memory.id}`, memory);
+            memoryCount++;
+        }
+        catch (err) {
+            console.warn(`  warn: memory ${memory.id}: ${err.message}`);
+        }
+    }
     console.log(`\n${render.icons.ok} ${render.wrap(render.c.green, "Restore complete")}`);
     console.log(render.kv("Agents restored", `${render.wrap(render.c.bold, String(agentCount))}${render.wrap(render.c.dim, `/${agents.length}`)}`));
     console.log(render.kv("Memories restored", `${render.wrap(render.c.bold, String(memoryCount))}${render.wrap(render.c.dim, `/${memories.length}`)}`));
@@ -17574,30 +17603,29 @@ program
     console.log(typeof seedOpsTarget === "string"
         ? `  Agent registered (ops: ${seedOpsTarget})`
         : `  Agent registered`);
-    // Restore memories
+    // Restore souls before memories: refuseLearnedSoulWrite matches Memory text.
     const auth = `Basic ${Buffer.from(`${resolveAdminUser(opts.adminUser)}:${adminPass}`).toString("base64")}`;
-    let memCount = 0;
-    for (const mem of data.memories ?? []) {
+    let soulCount = 0;
+    for (const soul of data.souls ?? []) {
         try {
-            await fetch(`${baseUrl}/Memory/${mem.id}`, {
+            await fetch(`${baseUrl}/Soul/${encodeURIComponent(soul.id)}`, {
                 method: "PUT",
                 headers: { "Content-Type": "application/json", Authorization: auth },
-                body: JSON.stringify(mem),
+                body: JSON.stringify(soul),
             });
-            memCount++;
+            soulCount++;
         }
         catch { /* skip failures */ }
     }
-    // Restore souls
-    let soulCount = 0;
-    for (const soul of data.souls ?? []) {
+    let memCount = 0;
+    for (const mem of data.memories ?? []) {
         try {
-            await fetch(`${baseUrl}/Soul/${encodeURIComponent(soul.id)}`, {
+            await fetch(`${baseUrl}/Memory/${mem.id}`, {
                 method: "PUT",
                 headers: { "Content-Type": "application/json", Authorization: auth },
-                body: JSON.stringify(soul),
+                body: JSON.stringify(mem),
             });
-            soulCount++;
+            memCount++;
         }
         catch { /* skip failures */ }
     }
@@ -17914,7 +17942,7 @@ presence
     .option("--port <port>", "Harper HTTP port")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .action(async (opts) => {
-    const agentId = resolveSigningAgentId(opts, "presence set");
+    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);
@@ -18000,7 +18028,7 @@ workspace
     .option("--port <port>", "Harper HTTP port")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .action(async (opts) => {
-    const agentId = resolveSigningAgentId(opts, "workspace set");
+    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);
@@ -18150,7 +18178,7 @@ program
     .option("--port <port>", "Harper HTTP port")
     .option("--target-url <url>", "Remote Flair URL (env: FLAIR_TARGET)")
     .action(async (opts) => {
-    const agentId = resolveSigningAgentId(opts, "orgevent");
+    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);
@@ -18220,7 +18248,7 @@ program
     .option("--json", "Output raw JSON")
     .action(async (entity, opts) => {
     try {
-        const agentId = resolveSigningAgentId(opts, "attention");
+        const { agentId } = resolveSigningAgentId(opts, "attention");
         if (!agentId) {
             console.error("error: --agent <id> required (or set FLAIR_AGENT_ID)");
             process.exit(2);