@tpsdev-ai/flair 0.46.0 → 0.47.1

package/dist/cli.js

@@ -6,10 +6,11 @@ import * as render from "./render.js";
 import { existsSync, mkdirSync, writeFileSync, readFileSync, chmodSync, renameSync, cpSync, rmSync, mkdtempSync, readdirSync, statSync, lstatSync, realpathSync, unlinkSync, chownSync, } from "node:fs";
 import { homedir, tmpdir } from "node:os";
 import { join, resolve, sep, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
 import { spawn, execFileSync, spawnSync, execSync } from "node:child_process";
 import { createHash, randomUUID, randomBytes } from "node:crypto";
 import { create as tarCreate, extract as tarExtract, list as tarList } from "tar";
-import { keystore } from "./keystore.js";
+import { keystore, keyPath as keystoreKeyPath } from "./keystore.js";
 import { deploy as deployToFabric, validateOptions as validateDeployOptions, buildTargetUrl as buildDeployUrl, resolveDeployPublicUrl } from "./deploy.js";
 import { COMPONENT_ENV_FILENAME, PUBLIC_URL_KEY, assertNoSecretKeysAdded, describePublicUrlFinding, planComponentEnv, readEnvValue, } from "./component-env.js";
 import { fabricUpgrade } from "./fabric-upgrade.js";
@@ -23,11 +24,13 @@ import { detectClients, renderWiringSummary, wireClaudeCode, wireCodex, wireGemi
 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, 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, 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, installContinuityHooks, uninstallContinuityHooks, continuityHookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.js";
 import { readSecretFileSecure, readAdminPassFileSecure, defaultAdminPassPath, defaultKeysDir, resolveLocalAdminPass, resolveKeyPath, buildEd25519Auth, authFetch, KeyLoadError, isLocalBase, authedRequest, } from "./lib/auth-resolve.js";
 import { resolveSigningIdentity, emitSigningIdentityDebug, } from "./lib/signing-identity.js";
 import { validateSnapshotArchive, extractSnapshotSafely } from "./lib/safe-snapshot-extract.js";
+import { entityFormatHint, parseEntitiesCsv } from "./lib/entity-vocab-cli.js";
 import { escapeXml, unescapeXml } from "./lib/xml-escape.js";
 import { assessLaunchdManagement, diagnoseLaunchdPlistPaths, isDetached, pickInstancePid, renderDetachedWarning, renderVerifiedSummary, LAUNCHCTL_QUERY_TIMEOUT_MS, } from "./lib/launchd-management.js";
 // Value-only static import so `--interval`'s advertised default cannot drift
@@ -2558,11 +2561,13 @@ export function upgradeStatusSuffix(name, status) {
     }
     if (status === "optional")
         return " (install via: openclaw plugins install @tpsdev-ai/openclaw-flair)";
-    // flair-mcp is refreshed by re-pinning its wiring (`flair doctor --fix` /
-    // the post-upgrade pin refresh), never `npm install -g` — a global bin does
-    // nothing for an `npx -y -p @tpsdev-ai/flair-mcp` invocation (flair#1208).
+    // flair-mcp is refreshed by re-pinning its wiring, never `npm install -g` —
+    // a global bin does nothing for an `npx -y -p @tpsdev-ai/flair-mcp`
+    // invocation (flair#1208). The re-pin is `flair upgrade`'s own job (the
+    // #1135/#1167 pin refresh) — never advise `doctor --fix` for it
+    // (flair#1324).
     if (status === "outdated" && name === FLAIR_MCP_PACKAGE) {
-        return " (npx-wired — run: flair doctor --fix to re-pin)";
+        return " (npx-wired — flair upgrade refreshes the pin)";
     }
     return "";
 }
@@ -4009,6 +4014,13 @@ agent
         : `✅ Agent '${id}' (${name}) registered`);
     console.log(`   Private key: ${privPath}`);
     console.log(`   Public key:  ${pubKeyB64url}`);
+    // flair#1280 — connector legibility at provisioning time: an OAuth /mcp
+    // connector resolves its own token subject to an Agent via
+    // Credential(kind:idp), NOT via this key, and the two identities are
+    // DISTINCT unless linked. One line here saves the "my connector memory is
+    // empty" discovery later.
+    console.log(`   Note: an OAuth /mcp connector maps its own IdP subject to an Agent (distinct from '${id}' by default).\n` +
+        `   To point a connector at '${id}': flair mcp enable --principal ${id} --idp-subject <your-idp-login>`);
 });
 agent
     .command("list")
@@ -5965,7 +5977,14 @@ async function loadInstanceSecretKey(instanceId, opts) {
             return nacl.sign.keyPair.fromSeed(new Uint8Array(seedFromDb)).secretKey;
         }
     }
-    throw new Error(`No private key found for instance ${instanceId}. Re-run 'flair federation status' to regenerate.`);
+    // flair#1233: the old advice here — "Re-run 'flair federation status' to
+    // regenerate" — was impossible: the server's create branch only fires when
+    // NO Instance row exists, so a re-run can never regenerate a key for an
+    // existing identity. Name the real remedy instead.
+    throw new Error(`No usable private key for instance ${instanceId}. Expected keystore file: ${keystoreKeyPath(instanceId)} ` +
+        `(no legacy _keySeed in the Instance table either). Restore that key file from a backup of ~/.flair/keys ` +
+        `(and FLAIR_KEY_PASSPHRASE, if one was set when it was written), or re-key this instance: delete its ` +
+        `Instance row and re-pair to mint a fresh identity.`);
 }
 /**
  * Sign a request body and return a new body with the signature field added.
@@ -6040,165 +6059,48 @@ federation
     const target = resolveTarget(opts);
     const baseUrl = target ? target.replace(/\/$/, "") : undefined;
     const mode = render.resolveOutputMode(opts);
+    // flair#1233: fetch instance and peers INDEPENDENTLY. One read failing
+    // must never take down the whole render — the principle latestPeerContact
+    // already documents for the driver verdict ("must never be the reason
+    // `federation status` fails"), extended to the two primary reads. Print
+    // what's available; mark the rest unverifiable.
+    let instance = null;
+    let instanceErr = null;
     try {
-        const instance = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
-        const { peers } = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
-        // Driver state (flair#922). Computed from the LOCAL service manager, so
-        // it is only meaningful when the CLI is pointed at the local instance.
-        let driver = null;
-        let assessment = null;
-        if (driverCheckAppliesTo(opts)) {
-            try {
-                const { schedulerStatus, assessDriver } = await import("./federation/scheduler.js");
-                driver = schedulerStatus();
-                let lastSyncAt = null;
-                for (const p of peers ?? []) {
-                    if (!p?.lastSyncAt)
-                        continue;
-                    const t = Date.parse(p.lastSyncAt);
-                    if (Number.isFinite(t) && (lastSyncAt === null || t > Date.parse(lastSyncAt))) {
-                        lastSyncAt = new Date(t).toISOString();
-                    }
-                }
-                assessment = assessDriver({
-                    installed: driver.installed,
-                    active: driver.active,
-                    intervalSeconds: driver.intervalSeconds,
-                    lastSyncAt,
-                    now: Date.now(),
-                });
-            }
-            catch {
-                // An unsupported platform (neither darwin nor linux) or an
-                // unreadable unit must not take down `federation status` — the peer
-                // table is still the primary output.
-                driver = null;
-                assessment = null;
-            }
-        }
-        if (mode === "json") {
-            console.log(render.asJSON({ instance, peers, driver, driverAssessment: assessment }));
-            return;
-        }
-        const statusColor = instance.status === "active" ? render.c.green : render.c.yellow;
-        console.log(render.wrap(render.c.bold, "Federation"));
-        console.log(render.kv("Instance", `${instance.id}  ${render.wrap(render.c.dim, `(${instance.role})`)}`));
-        console.log(render.kv("Public key", render.wrap(render.c.dim, instance.publicKey)));
-        console.log(render.kv("Status", render.wrap(statusColor, instance.status)));
-        if (peers.length === 0) {
-            console.log(`\n${render.icons.info} ${render.wrap(render.c.dim, "No peers configured. Use 'flair federation pair' to connect to a hub.")}`);
-            return;
-        }
-        // Print the driver line BEFORE the per-peer table: "is anything running
-        // sync at all" is the question that decides how to read everything
-        // below it.
-        if (assessment) {
-            const icon = assessment.verdict === "driving" || assessment.verdict === "external-driver"
-                ? render.icons.ok
-                : assessment.verdict === "unknown"
-                    ? render.icons.info
-                    : render.icons.warn;
-            const color = assessment.verdict === "driving" || assessment.verdict === "external-driver"
-                ? render.c.green
-                : assessment.verdict === "unknown"
-                    ? render.c.dim
-                    : render.c.yellow;
-            console.log();
-            console.log(`${icon} ${render.wrap(color, assessment.headline)}`);
-            console.log(`  ${render.wrap(render.c.dim, assessment.detail)}`);
-            if (assessment.remedy)
-                console.log(`  ${render.wrap(render.c.cyan, assessment.remedy)}`);
-        }
-        const now = Date.now();
-        const formatPeerAge = (iso, refNow, staleAfterMs) => {
-            if (!iso)
-                return render.wrap(render.c.red, "never");
-            const t = Date.parse(iso);
-            if (!Number.isFinite(t))
-                return render.wrap(render.c.red, "never");
-            const ageMs = refNow - t;
-            const ageStr = ageMs < 60_000 ? "<1m ago"
-                : ageMs < 3_600_000 ? `${Math.floor(ageMs / 60_000)}m ago`
-                    : ageMs < 86_400_000 ? `${Math.floor(ageMs / 3_600_000)}h ago`
-                        : `${Math.floor(ageMs / 86_400_000)}d ago`;
-            const stale = ageMs > staleAfterMs;
-            return render.wrap(stale ? render.c.yellow : render.c.dim, ageStr);
-        };
-        console.log();
-        const cols = [
-            { label: "peer", key: "id" },
-            { label: "role", key: "role", format: (v) => String(v ?? "—") },
-            {
-                label: "status",
-                key: "status",
-                format: (v) => {
-                    const s = String(v ?? "—");
-                    const color = s === "paired" || s === "connected" || s === "active" ? render.c.green : s === "revoked" ? render.c.red : render.c.yellow;
-                    return render.wrap(color, s);
-                },
-            },
-            {
-                // Liveness: "did we hear from this peer recently?" Updates on every
-                // contact, even when 100% of records were skipped. See flair#444.
-                label: "last_sync",
-                key: "lastSyncAt",
-                format: (v) => formatPeerAge(v, now, 86_400_000),
-            },
-            {
-                // Progress: "did data actually flow in?" Updates only when merged>0.
-                // Diverging from last_sync means contact-yes but data-no — investigate.
-                label: "last_merge",
-                key: "lastMergeAt",
-                format: (v) => formatPeerAge(v, now, 86_400_000),
-            },
-            {
-                label: "relay",
-                key: "relayOnly",
-                format: (v) => (v ? render.wrap(render.c.cyan, "yes") : render.wrap(render.c.dim, "no")),
-            },
-        ];
-        console.log(render.table(cols, peers));
-        // Stale warning is gated on lastMergeAt (real progress), not lastSyncAt.
-        // A peer that "syncs" every 5min but hasn't merged a record in 24h is
-        // exactly the failure mode we want surfaced.
-        const haveStale = peers.some((p) => {
-            const cursor = p.lastMergeAt ?? p.lastSyncAt;
-            if (!cursor)
-                return true;
-            const t = Date.parse(cursor);
-            return !Number.isFinite(t) || (now - t) > 86_400_000;
-        });
-        if (haveStale) {
-            console.log();
-            // The staleness warning used to fire identically whether sync was
-            // running and the peer was unreachable, or nothing had run sync since
-            // the day the spoke was paired (flair#922). Those need opposite
-            // actions, so the remedy is now chosen by the driver verdict instead
-            // of always pointing at SyncLog.
-            const noDriver = assessment?.verdict === "no-driver" || assessment?.verdict === "driver-inactive";
-            const remedy = noDriver
-                ? "Nothing is driving sync — see the driver line above. Run 'flair federation sync enable'."
-                : "Check skippedReasons in SyncLog or run 'flair federation sync'.";
-            console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, "One or more peers haven't merged a record in >24h.")} ${render.wrap(render.c.dim, remedy)}`);
-        }
-        const haveContactButNoMerge = peers.some((p) => {
-            if (!p.lastSyncAt || !Number.isFinite(Date.parse(p.lastSyncAt)))
-                return false;
-            if ((now - Date.parse(p.lastSyncAt)) > 3_600_000)
-                return false; // only recent contact
-            // Contact within the last hour, but no merge ever (or stale by >1h)
-            if (!p.lastMergeAt)
-                return true;
-            const tm = Date.parse(p.lastMergeAt);
-            return !Number.isFinite(tm) || (now - tm) > 3_600_000;
-        });
-        if (haveContactButNoMerge && !haveStale) {
-            console.log();
-            console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, "Peer contact is fresh but no records merged in the last hour.")} ${render.wrap(render.c.dim, "Possible silent-skip scenario — check SyncLog.skippedReasons.")}`);
-        }
+        instance = await api("GET", "/FederationInstance", undefined, baseUrl ? { baseUrl } : undefined);
+    }
+    catch (err) {
+        instanceErr = err;
+    }
+    // peers: null = unverifiable (the read failed), [] = verified empty.
+    let peers = null;
+    let peersErr = null;
+    try {
+        const r = await api("GET", "/FederationPeers", undefined, baseUrl ? { baseUrl } : undefined);
+        peers = r.peers ?? [];
     }
     catch (err) {
-        const msg = String(err.message ?? err);
+        peersErr = err;
+    }
+    // Auth-shaped failures stay FATAL even when the other read succeeded:
+    // both endpoints sit behind the same allowAdmin gate, so a 401/403 is a
+    // property of the session's credentials, not of one endpoint — and
+    // degrading it to "unverifiable" would swallow the actionable remedy
+    // (flair#634's UX, kept). Only non-auth failures degrade independently.
+    const authShaped = (err) => {
+        if (!err)
+            return false;
+        if (err.status === 401 || err.status === 403)
+            return true;
+        const m = String(err.message ?? err);
+        return m.includes("missing_or_invalid_authorization") || m.includes("401");
+    };
+    // Both reads failed → nothing to render at all. Either way keep the
+    // classic failure UX (auth remedy when it's an auth problem), exit
+    // non-zero.
+    if ((instanceErr && peersErr) || authShaped(instanceErr) || authShaped(peersErr)) {
+        const primaryErr = instanceErr ?? peersErr;
+        const msg = String(primaryErr.message ?? primaryErr);
         if (msg.includes("missing_or_invalid_authorization") || msg.includes("401")) {
             console.error(`${render.icons.error} federation status requires auth.`);
             console.error(`  ${render.wrap(render.c.dim, "Set one of:")}`);
@@ -6210,6 +6112,203 @@ federation
         console.error(`${render.icons.error} ${msg}`);
         process.exit(1);
     }
+    // Driver state (flair#922). Computed from the LOCAL service manager, so
+    // it is only meaningful when the CLI is pointed at the local instance —
+    // and only when the peer read succeeded: the verdict is derived from
+    // peer contact, so with peers unverifiable it would be a confident claim
+    // built on no data.
+    let driver = null;
+    let assessment = null;
+    if (peers !== null && driverCheckAppliesTo(opts)) {
+        try {
+            const { schedulerStatus, assessDriver } = await import("./federation/scheduler.js");
+            driver = schedulerStatus();
+            let lastSyncAt = null;
+            for (const p of peers) {
+                if (!p?.lastSyncAt)
+                    continue;
+                const t = Date.parse(p.lastSyncAt);
+                if (Number.isFinite(t) && (lastSyncAt === null || t > Date.parse(lastSyncAt))) {
+                    lastSyncAt = new Date(t).toISOString();
+                }
+            }
+            assessment = assessDriver({
+                installed: driver.installed,
+                active: driver.active,
+                intervalSeconds: driver.intervalSeconds,
+                lastSyncAt,
+                now: Date.now(),
+            });
+        }
+        catch {
+            // An unsupported platform (neither darwin nor linux) or an
+            // unreadable unit must not take down `federation status` — the peer
+            // table is still the primary output.
+            driver = null;
+            assessment = null;
+        }
+    }
+    if (mode === "json") {
+        console.log(render.asJSON({
+            instance,
+            peers,
+            driver,
+            driverAssessment: assessment,
+            // flair#1233: name what could not be read, so a partial result is
+            // distinguishable from "verified absent" (instance/peers stay null
+            // when their read failed).
+            ...(instanceErr || peersErr
+                ? {
+                    unverifiable: {
+                        ...(instanceErr ? { instance: String(instanceErr.message ?? instanceErr) } : {}),
+                        ...(peersErr ? { peers: String(peersErr.message ?? peersErr) } : {}),
+                    },
+                }
+                : {}),
+        }));
+        return;
+    }
+    console.log(render.wrap(render.c.bold, "Federation"));
+    if (instance) {
+        const statusColor = instance.status === "active" ? render.c.green : render.c.yellow;
+        console.log(render.kv("Instance", `${instance.id}  ${render.wrap(render.c.dim, `(${instance.role})`)}`));
+        console.log(render.kv("Public key", render.wrap(render.c.dim, instance.publicKey)));
+        console.log(render.kv("Status", render.wrap(statusColor, instance.status)));
+        // flair#1233 degraded marker — actor + state + remedy. The server sets
+        // signingKeyAvailable (runtime-only) on GET /FederationInstance; only
+        // an explicit false fires this. Older servers omit the field, which
+        // proves nothing either way, so no marker.
+        if (instance.signingKeyAvailable === false) {
+            console.log();
+            console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, "Signing key unavailable — the server could not store or read this instance's private key.")}`);
+            console.log(`  ${render.wrap(render.c.dim, "Reads (this status) still work; pair/sync signing on that instance will fail until the keystore is fixed.")}`);
+            console.log(`  ${render.wrap(render.c.cyan, "Fix on the server: make $HOME/.flair/keys (under the Harper process's HOME) a directory writable by the Harper process, mode 0700. If the key was never stored, re-key: delete the Instance row and re-pair.")}`);
+        }
+    }
+    else {
+        // Instance read failed but peers succeeded — render what we have.
+        console.log(render.kv("Instance", `${render.icons.warn} unverifiable — ${render.wrap(render.c.dim, String(instanceErr?.message ?? instanceErr))}`));
+    }
+    if (peers === null) {
+        // Peer read failed but the instance rendered — say so explicitly
+        // instead of aborting: "unverifiable" is a different claim from "no
+        // peers", and conflating them is how hub state became unobservable.
+        console.log();
+        console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, "Peers unverifiable — the peer read failed. This says nothing about whether peers exist or sync runs.")}`);
+        console.log(`  ${render.wrap(render.c.dim, String(peersErr?.message ?? peersErr))}`);
+        return;
+    }
+    if (peers.length === 0) {
+        console.log(`\n${render.icons.info} ${render.wrap(render.c.dim, "No peers configured. Use 'flair federation pair' to connect to a hub.")}`);
+        return;
+    }
+    // Print the driver line BEFORE the per-peer table: "is anything running
+    // sync at all" is the question that decides how to read everything
+    // below it.
+    if (assessment) {
+        const icon = assessment.verdict === "driving" || assessment.verdict === "external-driver"
+            ? render.icons.ok
+            : assessment.verdict === "unknown"
+                ? render.icons.info
+                : render.icons.warn;
+        const color = assessment.verdict === "driving" || assessment.verdict === "external-driver"
+            ? render.c.green
+            : assessment.verdict === "unknown"
+                ? render.c.dim
+                : render.c.yellow;
+        console.log();
+        console.log(`${icon} ${render.wrap(color, assessment.headline)}`);
+        console.log(`  ${render.wrap(render.c.dim, assessment.detail)}`);
+        if (assessment.remedy)
+            console.log(`  ${render.wrap(render.c.cyan, assessment.remedy)}`);
+    }
+    const now = Date.now();
+    const formatPeerAge = (iso, refNow, staleAfterMs) => {
+        if (!iso)
+            return render.wrap(render.c.red, "never");
+        const t = Date.parse(iso);
+        if (!Number.isFinite(t))
+            return render.wrap(render.c.red, "never");
+        const ageMs = refNow - t;
+        const ageStr = ageMs < 60_000 ? "<1m ago"
+            : ageMs < 3_600_000 ? `${Math.floor(ageMs / 60_000)}m ago`
+                : ageMs < 86_400_000 ? `${Math.floor(ageMs / 3_600_000)}h ago`
+                    : `${Math.floor(ageMs / 86_400_000)}d ago`;
+        const stale = ageMs > staleAfterMs;
+        return render.wrap(stale ? render.c.yellow : render.c.dim, ageStr);
+    };
+    console.log();
+    const cols = [
+        { label: "peer", key: "id" },
+        { label: "role", key: "role", format: (v) => String(v ?? "—") },
+        {
+            label: "status",
+            key: "status",
+            format: (v) => {
+                const s = String(v ?? "—");
+                const color = s === "paired" || s === "connected" || s === "active" ? render.c.green : s === "revoked" ? render.c.red : render.c.yellow;
+                return render.wrap(color, s);
+            },
+        },
+        {
+            // Liveness: "did we hear from this peer recently?" Updates on every
+            // contact, even when 100% of records were skipped. See flair#444.
+            label: "last_sync",
+            key: "lastSyncAt",
+            format: (v) => formatPeerAge(v, now, 86_400_000),
+        },
+        {
+            // Progress: "did data actually flow in?" Updates only when merged>0.
+            // Diverging from last_sync means contact-yes but data-no — investigate.
+            label: "last_merge",
+            key: "lastMergeAt",
+            format: (v) => formatPeerAge(v, now, 86_400_000),
+        },
+        {
+            label: "relay",
+            key: "relayOnly",
+            format: (v) => (v ? render.wrap(render.c.cyan, "yes") : render.wrap(render.c.dim, "no")),
+        },
+    ];
+    console.log(render.table(cols, peers));
+    // Stale warning is gated on lastMergeAt (real progress), not lastSyncAt.
+    // A peer that "syncs" every 5min but hasn't merged a record in 24h is
+    // exactly the failure mode we want surfaced.
+    const haveStale = peers.some((p) => {
+        const cursor = p.lastMergeAt ?? p.lastSyncAt;
+        if (!cursor)
+            return true;
+        const t = Date.parse(cursor);
+        return !Number.isFinite(t) || (now - t) > 86_400_000;
+    });
+    if (haveStale) {
+        console.log();
+        // The staleness warning used to fire identically whether sync was
+        // running and the peer was unreachable, or nothing had run sync since
+        // the day the spoke was paired (flair#922). Those need opposite
+        // actions, so the remedy is now chosen by the driver verdict instead
+        // of always pointing at SyncLog.
+        const noDriver = assessment?.verdict === "no-driver" || assessment?.verdict === "driver-inactive";
+        const remedy = noDriver
+            ? "Nothing is driving sync — see the driver line above. Run 'flair federation sync enable'."
+            : "Check skippedReasons in SyncLog or run 'flair federation sync'.";
+        console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, "One or more peers haven't merged a record in >24h.")} ${render.wrap(render.c.dim, remedy)}`);
+    }
+    const haveContactButNoMerge = peers.some((p) => {
+        if (!p.lastSyncAt || !Number.isFinite(Date.parse(p.lastSyncAt)))
+            return false;
+        if ((now - Date.parse(p.lastSyncAt)) > 3_600_000)
+            return false; // only recent contact
+        // Contact within the last hour, but no merge ever (or stale by >1h)
+        if (!p.lastMergeAt)
+            return true;
+        const tm = Date.parse(p.lastMergeAt);
+        return !Number.isFinite(tm) || (now - tm) > 3_600_000;
+    });
+    if (haveContactButNoMerge && !haveStale) {
+        console.log();
+        console.log(`${render.icons.warn} ${render.wrap(render.c.yellow, "Peer contact is fresh but no records merged in the last hour.")} ${render.wrap(render.c.dim, "Possible silent-skip scenario — check SyncLog.skippedReasons.")}`);
+    }
 });
 // `flair federation reachability` — probe local instance + all paired peers.
 // Productizes flair#695: a single command that tells
@@ -7819,6 +7918,43 @@ export function derivePromotedTags(candidateId, sources, stampedScopeTag) {
     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
@@ -7935,11 +8071,19 @@ rem
         // 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",
@@ -10078,11 +10222,69 @@ program
         console.log("\n✅ Everything is up to date.");
         return;
     }
-    // Nothing to install via npm/openclaw. What is left is advisory: packages
-    // not detected (missing) and/or a flair-mcp whose wired pin is behind latest
-    // — both fixed by re-wiring (`flair doctor --fix`), never by the
-    // npm-install + restart transaction below (#1168/#1208). Print the remedies
-    // and stop.
+    // ONE pin-refresh implementation, two callers (flair#1324): the post-
+    // install refresh below (#1135/#1167), and the stale-pin-only path — when
+    // flair-mcp's wired pin is behind latest but no package needs installing,
+    // `flair upgrade` refreshes the pin itself instead of advising a
+    // `doctor --fix` round-trip. Only refreshes clients that are ALREADY
+    // wired — never wires new ones. Best-effort: failures warn but never fail
+    // the upgrade.
+    async function refreshWiredMcpClientPins(targetPort) {
+        const agentId = resolveAgentIdOrEnv({}) ?? (() => {
+            try {
+                const kd = defaultKeysDir();
+                const keyFiles = readdirSync(kd).filter((f) => f.endsWith(".key"));
+                // Node-scoped federation keys aren't agents (flair#1193) — never
+                // pin-refresh a connector as one.
+                const agentKeyFile = keyFiles.find((f) => !isNodeKeyId(f.replace(/\.key$/, ""), kd));
+                return agentKeyFile ? agentKeyFile.replace(/\.key$/, "") : null;
+            }
+            catch {
+                return null;
+            }
+        })();
+        if (!agentId) {
+            console.log("\n   (no agent id known — skip MCP client pin refresh; run `flair init` to refresh manually)");
+            return;
+        }
+        const httpUrl = `http://127.0.0.1:${targetPort}`;
+        const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
+        const detected = detectClients().filter(c => c.detected);
+        if (detected.length === 0)
+            return;
+        console.log("\n   Refreshing MCP client pins...");
+        for (const client of detected) {
+            const configPath = clientConfigPath(client.id);
+            if (!existsSync(configPath))
+                continue;
+            // Only refresh clients that are already wired — don't wire new ones.
+            let hasFlair = false;
+            try {
+                const raw = readFileSync(configPath, "utf-8");
+                if (client.id === "codex") {
+                    hasFlair = codexConfigHasFlairSection(raw);
+                }
+                else {
+                    const cfg = JSON.parse(raw);
+                    hasFlair = !!cfg.mcpServers?.flair;
+                }
+            }
+            catch { /* unreadable/malformed — skip */ }
+            if (!hasFlair)
+                continue;
+            const env = { ...mcpEnv, FLAIR_CLIENT: client.id };
+            const result = client.wire(env);
+            console.log(`   ${result.ok ? "✓" : "•"} ${result.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
+    // stale pin is `flair upgrade`'s OWN job (flair#1324): refresh it right
+    // here rather than bouncing the user to `flair doctor --fix` — advice
+    // that was both roundabout and, until #1324, routed every upgrading user
+    // through doctor's consent hazard. Under --check, only say what a real
+    // run will do. `npm install -g` remains wrong for flair-mcp either way
+    // (#1168/#1208).
     if (totalUpgrades === 0) {
         if (missing.length > 0) {
             const npmMissing = missing.filter((f) => f.name !== FLAIR_MCP_PACKAGE);
@@ -10097,7 +10299,12 @@ program
         }
         if (flairMcpOutdated) {
             console.log(`\n⬆️  flair-mcp is wired via npx (pinned ${flairMcpOutdated.installed} → latest ${flairMcpOutdated.latest}).`);
-            console.log(`   Re-pin it: flair doctor --fix`);
+            if (checkOnly) {
+                console.log("   Run: flair upgrade (refreshes the pin)");
+            }
+            else {
+                await refreshWiredMcpClientPins(resolveHttpPort({}));
+            }
         }
         return;
     }
@@ -10318,54 +10525,7 @@ program
     // version. Runs BEFORE the restart so --no-restart and --no-verify paths
     // also get the refresh (flair#1167). Best-effort: failures warn but never
     // fail the upgrade.
-    await (async () => {
-        const agentId = resolveAgentIdOrEnv({}) ?? (() => {
-            try {
-                const kd = defaultKeysDir();
-                const keyFiles = readdirSync(kd).filter((f) => f.endsWith(".key"));
-                // Node-scoped federation keys aren't agents (flair#1193) — never
-                // pin-refresh a connector as one.
-                const agentKeyFile = keyFiles.find((f) => !isNodeKeyId(f.replace(/\.key$/, ""), kd));
-                return agentKeyFile ? agentKeyFile.replace(/\.key$/, "") : null;
-            }
-            catch {
-                return null;
-            }
-        })();
-        if (!agentId) {
-            console.log("\n   (no agent id known — skip MCP client pin refresh; run `flair init` to refresh manually)");
-            return;
-        }
-        const httpUrl = `http://127.0.0.1:${upgradePort}`;
-        const mcpEnv = { FLAIR_AGENT_ID: agentId, FLAIR_URL: httpUrl };
-        const detected = detectClients().filter(c => c.detected);
-        if (detected.length === 0)
-            return;
-        console.log("\n   Refreshing MCP client pins...");
-        for (const client of detected) {
-            const configPath = clientConfigPath(client.id);
-            if (!existsSync(configPath))
-                continue;
-            // Only refresh clients that are already wired — don't wire new ones.
-            let hasFlair = false;
-            try {
-                const raw = readFileSync(configPath, "utf-8");
-                if (client.id === "codex") {
-                    hasFlair = codexConfigHasFlairSection(raw);
-                }
-                else {
-                    const cfg = JSON.parse(raw);
-                    hasFlair = !!cfg.mcpServers?.flair;
-                }
-            }
-            catch { /* unreadable/malformed — skip */ }
-            if (!hasFlair)
-                continue;
-            const env = { ...mcpEnv, FLAIR_CLIENT: client.id };
-            const result = client.wire(env);
-            console.log(`   ${result.ok ? "✓" : "•"} ${result.message}`);
-        }
-    })();
+    await refreshWiredMcpClientPins(upgradePort);
     // ── Restart + verify + rollback (flair#635) ─────────────────────────────
     // Decision (2026-07-08): restart is now the default post-upgrade step —
     // installing new code without restarting leaves the OLD process serving
@@ -12175,6 +12335,33 @@ program
                 `Commands run through the CLI; the instance serves the data.`)}`);
         }
     }
+    // 0.5 npm global bin dir on PATH (flair#1134) — a user-prefix
+    // `npm i -g` succeeds and then `flair` is command-not-found because
+    // <prefix>/bin never made it into PATH. postinstall warns at install
+    // time, but lifecycle scripts are suppressed on several real paths
+    // (--ignore-scripts, bun without trustedDependencies, tar-swap
+    // deploys), so doctor re-runs the same check — cheap, local, and
+    // independent of Harper being up. When npm itself is absent or slow
+    // the check SKIPS silently: flair may be installed by other means,
+    // and "npm missing" has no actionable fix this check could print.
+    const npmGlobalPrefix = await resolveNpmGlobalPrefix();
+    if (npmGlobalPrefix) {
+        const binCheck = checkGlobalBinOnPath({
+            prefix: npmGlobalPrefix,
+            pathEnv: process.env.PATH,
+            shell: process.env.SHELL,
+        });
+        if ("message" in binCheck) {
+            console.log(`  ${render.icons.warn} ${render.wrap(render.c.yellow, `npm global bin dir ${binCheck.binDir} is NOT on PATH — global npm installs (flair included) won't be found by name`)}`);
+            for (const line of binCheck.message.split("\n")) {
+                console.log(`     ${render.wrap(render.c.dim, line)}`);
+            }
+            issues++;
+        }
+        else {
+            console.log(`  ${render.icons.ok} npm global bin dir ${render.wrap(render.c.dim, binCheck.binDir)} is on PATH`);
+        }
+    }
     // Helper: try to reach Harper on a given port.
     // Must return true ONLY when Harper's /Health endpoint returns 200 OK.
     // A generic HTTP status > 0 (flair#862) would accept 404 from a Node
@@ -12751,13 +12938,22 @@ program
                 continue;
             }
             console.log(`  ${render.icons.ok} ${client.label}: MCP server configured (${render.wrap(render.c.dim, block.configPath)})`);
-            const reachable = await probeFlairReachable(block.flairUrl);
+            // flair#1287: a block with FLAIR_AGENT_ID but no FLAIR_URL is a
+            // WORKING setup — flair-client falls back to its built-in default —
+            // and must never be reported as unconfigured. Say which URL applies
+            // and keep verifying against it, exactly as for an explicit one.
+            const eff = effectiveFlairUrl(block);
+            const urlLabel = eff.defaulted ? `${eff.url} (client default)` : eff.url;
+            if (eff.defaulted) {
+                console.log(`     ${render.icons.info} FLAIR_URL not set — flair-mcp defaults to ${render.wrap(render.c.dim, eff.url)}`);
+            }
+            const reachable = await probeFlairReachable(eff.url);
             if (!reachable) {
-                console.log(`     ${render.icons.warn} FLAIR_URL ${render.wrap(render.c.dim, block.flairUrl)} not reachable — cannot verify agent registration`);
+                console.log(`     ${render.icons.warn} FLAIR_URL ${render.wrap(render.c.dim, urlLabel)} not reachable — cannot verify agent registration`);
                 continue;
             }
-            console.log(`     ${render.icons.ok} FLAIR_URL ${render.wrap(render.c.dim, block.flairUrl)} reachable`);
-            const reg = await checkAgentRegistered(block.flairUrl, block.agentId, defaultKeysDir());
+            console.log(`     ${render.icons.ok} FLAIR_URL ${render.wrap(render.c.dim, urlLabel)} reachable`);
+            const reg = await checkAgentRegistered(eff.url, block.agentId, defaultKeysDir());
             if (reg.state === "registered") {
                 console.log(`     ${render.icons.ok} agent '${block.agentId}' registered`);
             }
@@ -12916,35 +13112,20 @@ program
             // the SessionStart check above: installed / absent / stale-form).
             // Continuity is OPT-IN — installing the PostToolUse+Stop pair IS the
             // opt-in — so "absent" renders as informational "not enabled": NEVER
-            // a pass (an unrun check must not look green) and never counted as an
-            // issue. A partial/stale install IS an issue and is --fix-able;
-            // --fix also offers first-time enablement (the y/N prompt is the
-            // consent; non-TTY --fix is itself the consent signal, matching every
-            // other doctor fix).
+            // a pass (an unrun check must not look green), never counted as an
+            // issue, and NEVER wired by --fix (flair#1324: doctor's fixable set
+            // is broken state; initiating an opt-in the user hasn't made is not a
+            // fix — a y/N prompt auto-answers yes in every non-TTY run, so it was
+            // no consent gate at all; enablement is `flair hook install
+            // --continuity` only). A partial or stale pair IS evidence of a prior
+            // opt-in, so repairing it to the complete current form remains a
+            // legitimate --fix.
             const continuity = checkContinuityCaptureHooks(homedir());
             if (continuity.state === "installed") {
                 console.log(`  ${render.icons.ok} Continuity capture hooks: PostToolUse + Stop wired in ${render.wrap(render.c.dim, continuity.path)}`);
             }
             else if (continuity.state === "absent") {
                 console.log(`  ${render.icons.info} Continuity capture hooks: not enabled ${render.wrap(render.c.dim, "(opt-in — auto-journal working state into the ephemeral memory tier; enable: flair hook install --continuity)")}`);
-                if (autoFix) {
-                    if (dryRun) {
-                        console.log(`     ${render.wrap(render.c.dim, "Would wire the continuity capture hooks (PostToolUse + Stop) in")} ${continuity.path}`);
-                    }
-                    else {
-                        const proceed = await confirmFix(`  Enable continuity capture (PostToolUse + Stop hooks in ${continuity.path})? [y/N] `);
-                        if (!proceed) {
-                            console.log(`     Skipped.`);
-                        }
-                        else {
-                            const fixAgentId = claudeCodeAgentId || opts.agent || process.env.FLAIR_AGENT_ID;
-                            const fixRes = fixContinuityCaptureHooks(homedir(), fixAgentId);
-                            console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
-                            if (fixRes.ok && fixRes.changed)
-                                fixed++;
-                        }
-                    }
-                }
             }
             else {
                 const continuityDetail = continuity.state === "partial"
@@ -13224,6 +13405,80 @@ program
             }
         }
     }
+    // 10. Scheduled drivers (flair#1278) — launchd/systemd liveness for the
+    // background schedulers (federation sync, REM nightly), read from the
+    // LOCAL service manager (no Harper dependency, so no harperResponding
+    // gate). Neither #1231 fleet incident (launchd spawn error 209 from a
+    // missing log dir, exit 126 from a stripped exec bit) was visible in
+    // doctor: driver health only surfaced in `flair federation sync status`
+    // / `flair rem nightly status` — commands an operator has to think to
+    // run, while doctor is the tool they actually run when something feels
+    // off. Reuses each scheduler's own status read (installed + genuinely
+    // loaded, flair#850) plus the #1282 last-exit plumbing
+    // (queryLastExitStatus); the verdict is describeScheduledDriverFinding
+    // (src/lib/scheduler-platform.ts) — pure decision logic, unit-tested
+    // without spawning launchctl/systemctl. Not-enabled renders as
+    // informational: an unenabled scheduler is a choice — never the pass
+    // marker, never the fail marker, never an issue.
+    console.log(`\n  ${render.wrap(render.c.bold, "Scheduled drivers")}`);
+    try {
+        const { queryLastExitStatus, describeScheduledDriverFinding } = await import("./lib/scheduler-platform.js");
+        const fedSched = await import("./federation/scheduler.js");
+        const remSched = await import("./rem/scheduler.js");
+        const guiDomain = `gui/${process.getuid?.() ?? ""}`;
+        const drivers = [
+            {
+                status: fedSched.schedulerStatus(),
+                label: "Federation sync driver",
+                enableCommand: "flair federation sync enable",
+                statusCommand: "flair federation sync status",
+                darwinTarget: `${guiDomain}/${fedSched.LAUNCHD_LABEL}`,
+                linuxServiceUnit: fedSched.SYSTEMD_SERVICE_UNIT,
+                stderrLogPath: join(homedir(), ".flair", "logs", "federation-sync.stderr.log"),
+            },
+            {
+                status: remSched.schedulerStatus(),
+                label: "REM nightly driver",
+                enableCommand: "flair rem nightly enable",
+                statusCommand: "flair rem nightly status",
+                darwinTarget: `${guiDomain}/${remSched.LAUNCHD_LABEL}`,
+                linuxServiceUnit: remSched.SYSTEMD_SERVICE_UNIT,
+                stderrLogPath: join(homedir(), ".flair", "logs", "rem-nightly.stderr.log"),
+            },
+        ];
+        for (const d of drivers) {
+            // Read the last run only when the service manager actually has the
+            // job — "not installed" and "not loaded" carry their own findings,
+            // and layering a last-exit read on top would blur which actor failed.
+            const lastExit = d.status.installed && d.status.active === true
+                ? queryLastExitStatus({ plat: d.status.platform, darwinTarget: d.darwinTarget, linuxServiceUnit: d.linuxServiceUnit })
+                : null;
+            const finding = describeScheduledDriverFinding({
+                label: d.label,
+                enableCommand: d.enableCommand,
+                statusCommand: d.statusCommand,
+                installed: d.status.installed,
+                active: d.status.active,
+                lastExit,
+                stderrLogPath: d.stderrLogPath,
+            });
+            console.log(`  ${render.icons[finding.icon]} ${finding.message}`);
+            finding.detail.forEach((line, i) => {
+                // Embed-verify degraded style: the actor+state line loud (red),
+                // the remedy dim.
+                const color = finding.state === "degraded" && i === 0 ? render.c.red : render.c.dim;
+                console.log(`     ${render.wrap(color, line)}`);
+            });
+            if (finding.isIssue)
+                issues++;
+        }
+    }
+    catch (err) {
+        // An unsupported platform (neither darwin nor linux) or a broken unit
+        // read must not take down doctor — report the section as unchecked
+        // (UNVERIFIED, not a pass), same as the other probes' skip discipline.
+        console.log(`  ${render.icons.warn} Scheduled drivers: could not check ${render.wrap(render.c.dim, `(${err?.message ?? err})`)}`);
+    }
     // Summary — see summarizeDoctorRun above (flair#721): distinguishes
     // issues --fix actually resolved this run from ones still outstanding.
     console.log("");
@@ -14297,6 +14552,29 @@ sessionSnapshot
     console.error(`  extracted to: ${targetDir}`);
 });
 // ─── Memory and Soul commands ────────────────────────────────────────────────
+// ─── --entities <csv> (flair#1288) ──────────────────────────────────────────
+//
+// Shared parse+validate for the `--entities <csv>` option on `memory add`,
+// `workspace set`, and `orgevent`. Comma-delimited to match the existing CLI
+// list-option convention (`--tags <csv>`, `--derived-from <csv>`); safe
+// because no entity grammar admits a comma. Invalid input exits 1 with the
+// canonical message — it names the offending values, the `type:value`
+// format, and the closed type set (errors must enable a response; same hint
+// the attention path's server-side invalid_entity 400 carries). The server
+// still re-validates on every write path (resources/entity-vocab.ts via
+// Memory/WorkspaceState/OrgEvent) — this client-side gate exists so a typo
+// is caught before any signing/network work, with a message a raw 400 body
+// never matched.
+function parseEntitiesOptionOrExit(csv) {
+    const { entities, invalid } = parseEntitiesCsv(csv);
+    if (invalid.length > 0) {
+        console.error(`error: invalid --entities value${invalid.length === 1 ? "" : "s"}: ${invalid.join(", ")}`);
+        console.error(`  ${entityFormatHint()}`);
+        process.exit(1);
+    }
+    return entities;
+}
+const ENTITIES_OPTION_DESCRIPTION = "Comma-separated entity vocabulary strings this record touches (type:value from the closed type set, e.g. repo:tpsdev-ai/flair — see docs/entity-vocabulary.md; feeds `flair attention`)";
 const memory = program.command("memory").description("Manage agent memories");
 memory.command("add [content]")
     .description("Write a new memory row for an agent (content via positional arg or --content)")
@@ -14307,6 +14585,7 @@ memory.command("add [content]")
     .option("--subject <text>", "one-line title / entity this memory is about")
     .option("--derived-from <csv>", "Comma-separated source Memory IDs this memory was distilled/reflected from (sets Memory.derivedFrom; used by the `rem rapid` reflection loop)")
     .option("--visibility <value>", "Writer-controlled sharing intent (sets Memory.visibility): 'private' (owner-only, never visible to any other agent) or 'shared' (visible to owner + every other agent on this instance — open within the org, not gated by a MemoryGrant). Omit to use the server's durability-keyed default: permanent/persistent -> shared, standard/ephemeral -> private (flair#509)")
+    .option("--entities <csv>", ENTITIES_OPTION_DESCRIPTION)
     .action(async (contentArg, opts) => {
     const content = contentArg ?? opts.content;
     if (!content) {
@@ -14342,6 +14621,13 @@ memory.command("add [content]")
     if (opts.derivedFrom) {
         body.derivedFrom = String(opts.derivedFrom).split(",").map((x) => x.trim()).filter(Boolean);
     }
+    // flair#1288: validated client-side; exits 1 with the canonical
+    // format-and-type-set message on any malformed value.
+    if (opts.entities) {
+        const entities = parseEntitiesOptionOrExit(String(opts.entities));
+        if (entities.length > 0)
+            body.entities = entities;
+    }
     const out = await api("PUT", `/Memory/${memId}`, body, { agentId });
     console.log(JSON.stringify(out, null, 2));
 });
@@ -16601,6 +16887,7 @@ workspace
     .option("--task <id>", "Task/issue id this workspace is attached to")
     .option("--phase <phase>", "Current phase (e.g. design, implement, review)")
     .option("--summary <text>", "Short summary of current workspace state")
+    .option("--entities <csv>", ENTITIES_OPTION_DESCRIPTION)
     .option("--agent <id>", "Agent ID (env: FLAIR_AGENT_ID)")
     .option("--port <port>", "Harper HTTP port")
     .option("--target <url>", "Remote Flair URL (env: FLAIR_TARGET)")
@@ -16617,6 +16904,9 @@ workspace
             process.exit(1);
         }
     }
+    // flair#1288: validate --entities before any key/network work; exits 1
+    // with the canonical format-and-type-set message on any malformed value.
+    const entities = opts.entities ? parseEntitiesOptionOrExit(String(opts.entities)) : undefined;
     const keyPath = resolveKeyPath(agentId);
     if (!keyPath) {
         console.error(`Error: private key not found for agent '${agentId}'. Check ~/.flair/keys/ or set FLAIR_KEY_DIR.`);
@@ -16649,6 +16939,8 @@ workspace
         body.phase = opts.phase;
     if (opts.summary)
         body.summary = opts.summary;
+    if (entities && entities.length > 0)
+        body.entities = entities;
     const res = await fetch(`${baseUrl}/WorkspaceState/${id}`, {
         method: "PUT",
         headers: { "Content-Type": "application/json", Authorization: auth },
@@ -16723,6 +17015,8 @@ async function publishOrgEvent(params) {
         body.scope = params.scope;
     if (params.targetIds && params.targetIds.length > 0)
         body.targetIds = params.targetIds;
+    if (params.entities && params.entities.length > 0)
+        body.entities = params.entities;
     const res = await fetch(`${params.baseUrl}/OrgEvent/${id}`, {
         method: "PUT",
         headers: { "Content-Type": "application/json", Authorization: auth },
@@ -16743,6 +17037,7 @@ program
     .option("--detail <text>", "Longer detail payload")
     .option("--scope <scope>", "Scope of the event (e.g. an agent id, repo, or 'org')")
     .option("--target <agentId>", "Recipient agent id (repeatable)", (val, acc) => { acc.push(val); return acc; }, [])
+    .option("--entities <csv>", ENTITIES_OPTION_DESCRIPTION)
     .option("--agent <id>", "Agent ID (env: FLAIR_AGENT_ID)")
     .option("--port <port>", "Harper HTTP port")
     .option("--target-url <url>", "Remote Flair URL (env: FLAIR_TARGET)")
@@ -16756,6 +17051,9 @@ program
     // --target-url here (env FLAIR_TARGET still honored via resolveBaseUrl).
     const baseUrl = resolveBaseUrl({ target: opts.targetUrl, port: opts.port }).replace(/\/$/, "");
     const targetIds = Array.isArray(opts.target) && opts.target.length > 0 ? opts.target : undefined;
+    // flair#1288: validate --entities before any key/network work; exits 1
+    // with the canonical format-and-type-set message on any malformed value.
+    const entities = opts.entities ? parseEntitiesOptionOrExit(String(opts.entities)) : undefined;
     const result = await publishOrgEvent({
         agentId,
         baseUrl,
@@ -16764,6 +17062,7 @@ program
         detail: opts.detail,
         scope: opts.scope,
         targetIds,
+        entities,
     });
     if (!result.ok) {
         console.error(`Error: ${result.error}`);
@@ -16884,6 +17183,26 @@ program
 // its Node-version check passes. The shim imports this module, so import.meta.main
 // is false there — without this explicit entry point the CLI would load but never run.
 async function runCli() {
+    // flair#1134 — npm ≥12 blocks install scripts by default, so the
+    // postinstall PATH warning cannot fire there; the first thing of ours
+    // that executes is this CLI, reached via npx / absolute path / a PATH
+    // fixed-for-one-shell. Spawn-free (prefix derived from this file's own
+    // location), validated (the derived bin dir must really hold flair),
+    // TTY-gated (no per-run noise for automation), and skipped for `doctor`,
+    // which prints the full finding itself. Must never break the CLI.
+    if (process.argv[2] !== "doctor") {
+        try {
+            const banner = cliBootPathWarning({
+                packageDir: resolve(dirname(fileURLToPath(import.meta.url)), ".."),
+                pathEnv: process.env.PATH,
+                shell: process.env.SHELL,
+                stderrIsTTY: process.stderr.isTTY === true,
+            });
+            if (banner)
+                console.error(banner);
+        }
+        catch { /* a diagnostic must never take down the CLI */ }
+    }
     // A bare `flair` (no command) is a help request, not a usage error — show
     // help and exit 0, rather than commander's default (help + exit 1). Flags
     // like -h/--help/-v have argv beyond the binary and fall through to