@tpsdev-ai/flair 0.45.0 → 0.47.0

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, } from "./doctor-client.js";
-import { installHook, uninstallHook, hookStatus, isSupportedHarness, SUPPORTED_HARNESSES, } from "./hook-install.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
@@ -1604,6 +1607,164 @@ export async function verifySemanticSearch(baseUrl, agentIdOpt, keysDir) {
         }
     }
 }
+/**
+ * Positive control for the Harper audit log (flair#970): verify that audit
+ * ACTUALLY records by writing and then reading the audit trail back — never by
+ * trusting the `audit: true` flag `describe_table` reports.
+ *
+ * Why a positive control: records applied via cluster base-copy/resync are
+ * committed with audit explicitly disabled (harper Table.ts isCopyApply, filed
+ * upstream as harper#2212), so a node can report audit enabled, answer
+ * read_audit_log with HTTP 200, and still hold zero entries. Before this
+ * check, nothing in flair declared, read, or verified audit — the canonical
+ * check that cannot fire.
+ *
+ * Probe (modeled on verifySemanticSearch above, same skipped/degraded/ok
+ * discipline):
+ *   1. PUT an ephemeral probe row (id `flair-doctor-audit-probe-<uuid>`,
+ *      short inert marker content — ephemeral durability so a failed cleanup
+ *      self-prunes; the DELETE in `finally` is best-effort).
+ *   2. PATCH it — verified live on harper@5.2.0: PATCH /Memory/<id> returns
+ *      204 and generates an audit entry with operation "patch" (PUT generates
+ *      "upsert", DELETE "delete").
+ *   3. `read_audit_log` (search_type hash_value, the probe id) over the ops
+ *      API with Basic admin auth — the operations API only exists on its own
+ *      port/socket, so the agent's Ed25519 header cannot authenticate it.
+ *   4. Assert BOTH write entries are present. The probe's own DELETE lands
+ *      AFTER the read, so it is never required (audit is append-only; the
+ *      probe's entries persisting after the row is gone is by design).
+ *
+ * All assertions are BOOLEAN (entry counts only). Audit entries carry full
+ * record images (`records: [value]`), so no entry content is ever copied into
+ * a result detail — the detail strings are fixed text plus counts/statuses.
+ */
+export async function verifyAuditLog(baseUrl, agentIdOpt, keysDir, opsUrl, adminUser, adminPass) {
+    // Resolve an agent + key to sign the probe writes with — identical
+    // resolution to verifySemanticSearch so the two probes agree on identity.
+    let agentId = agentIdOpt || process.env.FLAIR_AGENT_ID || undefined;
+    if (!agentId) {
+        try {
+            const keyFiles = readdirSync(keysDir).filter((f) => f.endsWith(".key"));
+            const agentKeyFile = keyFiles.find((f) => !isNodeKeyId(f.replace(/\.key$/, ""), keysDir));
+            if (agentKeyFile)
+                agentId = agentKeyFile.replace(/\.key$/, "");
+        }
+        catch { /* keysDir missing */ }
+    }
+    if (!agentId) {
+        return { state: "skipped", reason: "no-agent", detail: "no agent id or key found" };
+    }
+    let keyPath = resolveKeyPath(agentId);
+    if (!keyPath) {
+        const candidate = join(keysDir, `${agentId}.key`);
+        if (existsSync(candidate))
+            keyPath = candidate;
+    }
+    if (!keyPath) {
+        return { state: "skipped", reason: "no-key", detail: `no private key for agent '${agentId}'` };
+    }
+    if (!adminUser || !adminPass) {
+        return {
+            state: "skipped",
+            reason: "no-admin-credentials",
+            detail: "no admin credentials for the ops API (read_audit_log requires them)",
+        };
+    }
+    const id = `flair-doctor-audit-probe-${randomUUID()}`;
+    const path = `/Memory/${id}`;
+    let stored = false;
+    try {
+        // Write 1: PUT the probe row. Ephemeral durability — TTL is the cleanup
+        // backstop if the finally-DELETE fails.
+        const putRes = await authFetch(baseUrl, agentId, keyPath, "PUT", path, {
+            id,
+            agentId,
+            content: `flair doctor audit probe (inert marker, safe to ignore) [${id}]`,
+            durability: "ephemeral",
+            createdAt: new Date().toISOString(),
+        });
+        if (!putRes.ok && putRes.status !== 204) {
+            return { state: "skipped", reason: "probe-failed", detail: `could not write probe row: HTTP ${putRes.status}` };
+        }
+        stored = true;
+        // Write 2: PATCH — a second, distinct audit-visible write (live-verified
+        // to produce its own entry on harper@5.2.0; see doc comment).
+        const patchRes = await authFetch(baseUrl, agentId, keyPath, "PATCH", path, {
+            content: `flair doctor audit probe (inert marker, second write) [${id}]`,
+        });
+        if (!patchRes.ok && patchRes.status !== 204) {
+            return { state: "skipped", reason: "probe-failed", detail: `could not apply second probe write: HTTP ${patchRes.status}` };
+        }
+        // Read the audit trail back over the ops API.
+        let auditRes;
+        try {
+            auditRes = await fetch(`${opsUrl.replace(/\/+$/, "")}/`, {
+                method: "POST",
+                headers: {
+                    "Content-Type": "application/json",
+                    Authorization: `Basic ${Buffer.from(`${adminUser}:${adminPass}`).toString("base64")}`,
+                },
+                body: JSON.stringify({
+                    operation: "read_audit_log",
+                    database: "flair",
+                    table: "Memory",
+                    search_type: "hash_value",
+                    search_values: [id],
+                }),
+                signal: AbortSignal.timeout(10_000),
+            });
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return { state: "skipped", reason: "probe-failed", detail: `ops API unreachable at ${opsUrl} (${message.slice(0, 80)})` };
+        }
+        if (auditRes.status === 400) {
+            // harper rejects read_audit_log with HTTP 400 ("To use this operation
+            // audit log must be enabled in harperdb-config.yaml") when
+            // logging.auditLog is off — live-verified on harper@5.2.0.
+            return { state: "degraded", cause: "disabled", detail: "read_audit_log rejected the probe: audit logging is not enabled on this instance" };
+        }
+        if (!auditRes.ok) {
+            // 401/403/404/5xx tell us nothing about whether audit records — that is
+            // "could not verify", never "verified" and never "broken".
+            return { state: "skipped", reason: "probe-failed", detail: `read_audit_log failed: HTTP ${auditRes.status}` };
+        }
+        const body = (await auditRes.json().catch(() => null));
+        // BOOLEAN classification only: count the probe's write entries. Audit
+        // entries carry full record images — none of that content may reach the
+        // result (and via it, doctor/init output).
+        const entries = body && Array.isArray(body[id]) ? body[id] : [];
+        const writeEntries = entries.filter((e) => e && typeof e === "object" && e.operation !== "delete");
+        if (writeEntries.length >= 2) {
+            return { state: "ok" };
+        }
+        // Enabled-but-empty (or partial) is the critical row: we put data in and
+        // could not see it come back — the pipeline is broken, not "empty". The
+        // pre-fix world silently passed this as ok.
+        return {
+            state: "degraded",
+            cause: "not-recording",
+            detail: `probe made 2 writes; read_audit_log returned ${writeEntries.length} write ${writeEntries.length === 1 ? "entry" : "entries"}`,
+        };
+    }
+    catch (err) {
+        if (err instanceof KeyLoadError) {
+            return { state: "skipped", reason: "key-load", detail: err.message };
+        }
+        const message = err instanceof Error ? err.message : String(err);
+        return { state: "skipped", reason: "probe-failed", detail: `probe error: ${message.slice(0, 100)}` };
+    }
+    finally {
+        // Best-effort cleanup — ephemeral TTL is the backstop if this fails. The
+        // DELETE itself appends one more audit entry AFTER the read, by design.
+        if (stored) {
+            try {
+                await authFetch(baseUrl, agentId, keyPath, "DELETE", path);
+            }
+            catch { /* leave the ephemeral row; it'll age out */ }
+        }
+    }
+}
 // ─── Doctor: client-integration network checks (flair#588) ────────────────────
 //
 // The pure filesystem checks (MCP block parsing, CLAUDE.md, SessionStart hook)
@@ -3355,6 +3516,33 @@ program
         else {
             console.log(`${render.icons.warn} Semantic search not verified ${render.wrap(render.c.dim, `(${embedCheck.detail})`)}`);
         }
+        // Verify the audit log ACTUALLY records (flair#970) — a positive
+        // control, not a flag read: `describe_table` reports `audit: true` on
+        // nodes whose audit trail is empty (base-copy elision, harper#2212).
+        // Same surface as the semantic-search check above.
+        console.log("Verifying audit log...");
+        const auditCheck = await verifyAuditLog(httpUrl, agentId, keysDir, `http://127.0.0.1:${opsPort}`, adminUser, adminPass);
+        if (auditCheck.state === "ok") {
+            // Present tense ONLY: the probe proves current recording, never
+            // historical completeness — see AuditVerifyResult's doc comment.
+            console.log(`Audit log: recording (verified now) ✓ ${render.wrap(render.c.dim, "(verifies current recording, not history — a resynced node's audit has a hard start boundary at its copy time)")}`);
+        }
+        else if (auditCheck.state === "degraded") {
+            if (auditCheck.cause === "disabled") {
+                console.log(`\n${render.icons.error} ${render.wrap(render.c.red, "Audit log DISABLED")} — ${auditCheck.detail}.`);
+                console.log(`   ${render.wrap(render.c.dim, "Fix: enable logging.auditLog in the ROOT harperdb-config.yaml (the Harper instance config, NOT flair's component config.yaml), then restart Harper.")}`);
+            }
+            else {
+                console.log(`\n${render.icons.error} ${render.wrap(render.c.red, "Audit log NOT RECORDING")} — ${auditCheck.detail}.`);
+                console.log(`   ${render.wrap(render.c.red, "Audit reports as enabled, but fresh writes produced no audit entries — do not treat the audit log as a record of what happened.")}`);
+                console.log(`   ${render.wrap(render.c.dim, "On a node that joined or resynced via cluster base copy, audit history has a hard start boundary at copy time (harper#2212) — \"no history\" does not mean \"nothing happened\".")}`);
+                console.log(`   ${render.wrap(render.c.dim, "Check logging.auditLog in the ROOT harperdb-config.yaml (not flair's component config.yaml), then restart Harper.")}`);
+            }
+        }
+        else {
+            // An unrun check must not look like a pass.
+            console.log(`${render.icons.warn} Audit log: UNVERIFIED (could not probe — ${auditCheck.detail})`);
+        }
         // Output — admin password printed once, never written to disk
         console.log("\n✅ Flair initialized successfully");
         console.log(`   Agent ID:    ${agentId}`);
@@ -3824,6 +4012,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")
@@ -4359,6 +4554,7 @@ hook
     .option("--agent <id>", "Agent ID to wire (else FLAIR_AGENT_ID, else the agent already wired for the claude-code MCP client)")
     .option("--agent-id <id>", "Alias for --agent")
     .option("--url <url>", "Flair URL to wire (else FLAIR_TARGET/FLAIR_URL, else the existing claude-code MCP wiring, else the local default)")
+    .option("--continuity", "Wire the continuity capture hooks instead (PostToolUse + Stop — flair#1257; installing them IS the opt-in)")
     .action((opts) => {
     const harness = requireSupportedHarness(opts.harness);
     const home = homedir();
@@ -4369,6 +4565,18 @@ hook
     }
     const flairUrl = resolveHookFlairUrl(opts, home);
     const dryRun = !!opts.dryRun;
+    if (opts.continuity) {
+        const result = installContinuityHooks({ homeDir: home, harness, agentId, flairUrl, dryRun });
+        console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook install --continuity")}${dryRun ? render.wrap(render.c.dim, " (dry run)") : ""}\n`);
+        console.log(`  ${result.ok ? render.icons.ok : render.icons.error} ${result.message}`);
+        if (result.backupPath) {
+            console.log(`     ${render.wrap(render.c.dim, `backup: ${result.backupPath}`)}`);
+        }
+        console.log("");
+        if (!result.ok)
+            process.exit(1);
+        return;
+    }
     const result = installHook({ homeDir: home, harness, agentId, flairUrl, dryRun });
     console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook install")}${dryRun ? render.wrap(render.c.dim, " (dry run)") : ""}\n`);
     console.log(`  ${result.ok ? render.icons.ok : render.icons.error} ${result.message}`);
@@ -4388,10 +4596,23 @@ hook
     .description("Remove the Flair SessionStart hook entry — only ours, everything else in the file is left untouched")
     .option("--harness <name>", `Target harness (${SUPPORTED_HARNESSES.join(", ")})`, "claude-code")
     .option("--dry-run", "Print the exact JSON delta without writing")
+    .option("--continuity", "Remove the continuity capture hooks instead (PostToolUse + Stop — flair#1257)")
     .action((opts) => {
     const harness = requireSupportedHarness(opts.harness);
     const home = homedir();
     const dryRun = !!opts.dryRun;
+    if (opts.continuity) {
+        const result = uninstallContinuityHooks({ homeDir: home, harness, dryRun });
+        console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook uninstall --continuity")}${dryRun ? render.wrap(render.c.dim, " (dry run)") : ""}\n`);
+        console.log(`  ${result.ok ? render.icons.ok : render.icons.error} ${result.message}`);
+        if (result.backupPath) {
+            console.log(`     ${render.wrap(render.c.dim, `backup: ${result.backupPath}`)}`);
+        }
+        console.log("");
+        if (!result.ok)
+            process.exit(1);
+        return;
+    }
     const result = uninstallHook({ homeDir: home, harness, dryRun });
     console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook uninstall")}${dryRun ? render.wrap(render.c.dim, " (dry run)") : ""}\n`);
     console.log(`  ${result.ok ? render.icons.ok : render.icons.error} ${result.message}`);
@@ -4414,6 +4635,22 @@ hook
     const harness = requireSupportedHarness(opts.harness);
     const home = homedir();
     const status = hookStatus(home, harness);
+    // Continuity pair (flair#1257) — reported alongside the SessionStart
+    // status in every branch below. "absent" is NOT a failure: installing the
+    // pair is the opt-in, so absence renders as "not enabled".
+    const renderContinuity = () => {
+        const cont = continuityHookStatus(home, harness);
+        if (cont.state === "installed") {
+            console.log(`  ${render.icons.ok} continuity capture: PostToolUse + Stop wired`);
+        }
+        else if (cont.state === "absent") {
+            console.log(`  ${render.icons.info} continuity capture: not enabled ${render.wrap(render.c.dim, "(opt-in: flair hook install --continuity)")}`);
+        }
+        else {
+            const missing = !cont.postToolUse.present ? "PostToolUse missing" : !cont.stop.present ? "Stop missing" : "stale form";
+            console.log(`  ${render.icons.warn} continuity capture: ${cont.state} (${missing}) ${render.wrap(render.c.dim, "— re-run: flair hook install --continuity")}`);
+        }
+    };
     console.log(`\n${render.wrap(render.c.bold, "🪝 flair hook status")}\n`);
     console.log(`  ${render.wrap(render.c.dim, "Harness:")} ${status.harness}`);
     console.log(`  ${render.wrap(render.c.dim, "Config:")}  ${status.path}`);
@@ -4425,6 +4662,7 @@ hook
     if (!status.wired) {
         console.log(`  ${render.icons.error} not wired`);
         console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair hook install`);
+        renderContinuity();
         console.log("");
         process.exit(1);
     }
@@ -4439,6 +4677,7 @@ hook
     else {
         console.log(`     ${render.icons.warn} ${render.wrap(render.c.dim, "On failure:")} prints an error on every session — run \`flair hook install\` to adopt the silent form`);
     }
+    renderContinuity();
     console.log("");
 });
 // ─── flair mcp ───────────────────────────────────────────────────────────────
@@ -5736,7 +5975,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.
@@ -5811,165 +6057,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) {
-        const msg = String(err.message ?? 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) {
+        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:")}`);
@@ -5981,6 +6110,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
@@ -6433,6 +6759,11 @@ export async function runFederationSyncOnce(opts) {
             return await syncRes.json();
         }
         let totalBatches = 0;
+        // Memory rows that passed the since-cursor filter but were excluded as
+        // private. Used only so the quiet path can distinguish "nothing since
+        // the cursor" from "found rows, all withheld" (flair#1232). Does not
+        // change what gets pushed — private still never leaves the instance.
+        let privateHeldBack = 0;
         for (const table of tables) {
             let rows = [];
             for (const query of [
@@ -6466,9 +6797,11 @@ export async function runFederationSyncOnce(opts) {
                 // filter only applies there; on the other 3 tables `row.visibility`
                 // is always undefined, which isFederationPrivateVisibility() treats
                 // as non-private (included) — a no-op for them.
-                rows = rows.concat(batch
-                    .filter((r) => r.updatedAt !== null || r.createdAt > since)
-                    .filter((r) => table !== "Memory" || !isFederationPrivateVisibility(r.visibility)));
+                const sinceCursor = batch.filter((r) => r.updatedAt !== null || r.createdAt > since);
+                const federable = sinceCursor.filter((r) => table !== "Memory" || !isFederationPrivateVisibility(r.visibility));
+                if (table === "Memory")
+                    privateHeldBack += sinceCursor.length - federable.length;
+                rows = rows.concat(federable);
             }
             if (rows.length === 0)
                 continue;
@@ -6583,7 +6916,13 @@ export async function runFederationSyncOnce(opts) {
             catch (pingErr) {
                 console.warn(`⚠️  Liveness ping error: ${pingErr?.message ?? pingErr}. Hub won't update spoke liveness.`);
             }
-            console.log("No changes since last sync.");
+            // flair#1232: "No changes" is true only when nothing was found since
+            // the cursor. If rows were found and every one was withheld as private,
+            // say so — count and reason only, never content. A zero withheld count
+            // must not invent a private-withheld story.
+            console.log(privateHeldBack > 0
+                ? `No federable changes since last sync (${privateHeldBack} row${privateHeldBack === 1 ? "" : "s"} held back: private visibility).`
+                : "No changes since last sync.");
             return { pushed: 0, skipped: 0 };
         }
         console.log(`✅ Synced ${totalMerged} records (${totalSkipped} skipped) across ${totalBatches} batches`);
@@ -7577,6 +7916,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
@@ -7693,11 +8069,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",
@@ -11933,6 +12317,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
@@ -12303,6 +12714,60 @@ program
             }
         }
     }
+    // 4b. Audit-log positive control (flair#970) — REAL write→read_audit_log
+    // round-trip, only if Harper is responding. `describe_table` reporting
+    // `audit: true` proves nothing: a node that joined or resynced via
+    // cluster base copy holds zero audit history while reporting audit
+    // enabled and answering read_audit_log with clean empty (harper#2212).
+    // So doctor writes probe rows and asserts their audit entries come back —
+    // never trusts the flag. Same ok/degraded/skipped discipline as the
+    // embeddings check above: skipped is rendered UNVERIFIED, never as a pass.
+    if (harperResponding) {
+        // read_audit_log only exists on the ops API (its own port), which the
+        // agent's Ed25519 header cannot authenticate — resolve the local admin
+        // credential (env or ~/.flair/admin-pass; never prompts). A file with
+        // unsafe permissions throws — that is "could not probe", not "broken".
+        let auditAdminPass;
+        let auditCredIssue = null;
+        try {
+            auditAdminPass = resolveLocalAdminPass(undefined);
+        }
+        catch (err) {
+            auditCredIssue = err instanceof Error ? err.message : String(err);
+        }
+        const auditStatus = auditCredIssue
+            ? { state: "skipped", reason: "no-admin-credentials", detail: auditCredIssue }
+            : await verifyAuditLog(baseUrl, opts.agent, defaultKeysDir(), `http://127.0.0.1:${resolveOpsPort(opts)}`, DEFAULT_ADMIN_USER, auditAdminPass);
+        switch (auditStatus.state) {
+            case "ok":
+                // Present-tense claim ONLY (see AuditVerifyResult): the probe
+                // proves the log records writes NOW — never that history is
+                // complete. Overclaiming here would rebuild the false trust
+                // anchor this check exists to kill, one layer up.
+                console.log(`  ${render.icons.ok} Audit log: recording (verified now) ${render.wrap(render.c.dim, "(verifies current recording, not history — a resynced node's audit has a hard start boundary at its copy time)")}`);
+                break;
+            case "degraded":
+                if (auditStatus.cause === "disabled") {
+                    console.log(`  ${render.icons.error} Audit log DISABLED ${render.wrap(render.c.dim, `— ${auditStatus.detail}`)}`);
+                    console.log(`     ${render.wrap(render.c.dim, "Fix: enable logging.auditLog in the ROOT harperdb-config.yaml (the Harper instance config, NOT flair's component config.yaml), then restart Harper.")}`);
+                }
+                else {
+                    console.log(`  ${render.icons.error} Audit log NOT RECORDING ${render.wrap(render.c.dim, `— ${auditStatus.detail}`)}`);
+                    console.log(`     ${render.wrap(render.c.red, "Audit reports as enabled, but fresh writes produced no audit entries — do not treat the audit log as a record of what happened.")}`);
+                    console.log(`     ${render.wrap(render.c.dim, "On a node that joined or resynced via cluster base copy, audit history has a hard start boundary at copy time (harper#2212) — \"no history\" does not mean \"nothing happened\".")}`);
+                    console.log(`     ${render.wrap(render.c.dim, "Check logging.auditLog in the ROOT harperdb-config.yaml (not flair's component config.yaml), then restart Harper.")}`);
+                }
+                issues++;
+                break;
+            case "skipped":
+                // An unrun check must not look like a pass — UNVERIFIED, visually
+                // distinct from ok, but not a hard issue (mirrors the embeddings
+                // skip: the operator may simply have no agent or no local admin
+                // credential on this box).
+                console.log(`  ${render.icons.warn} Audit log: UNVERIFIED (could not probe — ${auditStatus.detail})`);
+                break;
+        }
+    }
     // 5. Stale PID file (skip if already reported in port check)
     const dataDir = defaultDataDir();
     const pidFile = join(dataDir, "hdb.pid");
@@ -12455,13 +12920,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`);
             }
@@ -12616,6 +13090,73 @@ program
                 }
                 issues++;
             }
+            // 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
+            // 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).
+            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"
+                    ? (!continuity.postToolUse.present ? "the PostToolUse entry is missing" : "the Stop entry is missing")
+                    : "an entry is not the current form (unsilenced, hand-altered, or a drifted PostToolUse matcher)";
+                console.log(`  ${render.icons.warn} Continuity capture hooks: ${continuity.state} — ${continuityDetail}`);
+                if (autoFix) {
+                    if (dryRun) {
+                        console.log(`     ${render.wrap(render.c.dim, "Would rewrite the continuity capture hooks in")} ${continuity.path}`);
+                    }
+                    else {
+                        const proceed = await confirmFix(`  Rewrite the continuity capture hooks in ${continuity.path} to the current form? [y/N] `);
+                        if (!proceed) {
+                            console.log(`     Skipped.`);
+                        }
+                        else {
+                            const fixAgentId = claudeCodeAgentId || opts.agent || process.env.FLAIR_AGENT_ID;
+                            // Preserve the FLAIR_URL an existing entry already carries —
+                            // a repair must never silently re-point the hooks at a
+                            // different instance.
+                            const existingCommand = continuity.postToolUse.command || continuity.stop.command || "";
+                            const existingUrl = existingCommand.match(/FLAIR_URL=(\S+)/)?.[1];
+                            const fixRes = fixContinuityCaptureHooks(homedir(), fixAgentId, existingUrl);
+                            console.log(`     ${fixRes.ok ? render.icons.ok : render.icons.warn} ${fixRes.message}`);
+                            if (fixRes.ok && fixRes.changed)
+                                fixed++;
+                        }
+                    }
+                }
+                else {
+                    console.log(`     ${render.wrap(render.c.dim, "Fix:")} flair doctor --fix ${render.wrap(render.c.dim, "(rewrites both entries to the current form — same agent, same instance)")}`);
+                }
+                issues++;
+            }
         }
     }
     // 7a. Resolve which agent identities the two verified-read sections below
@@ -12861,6 +13402,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("");
@@ -13934,6 +14549,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)")
@@ -13944,6 +14582,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) {
@@ -13979,6 +14618,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));
 });
@@ -16238,6 +16884,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)")
@@ -16254,6 +16901,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.`);
@@ -16286,6 +16936,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 },
@@ -16360,6 +17012,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 },
@@ -16380,6 +17034,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)")
@@ -16393,6 +17048,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,
@@ -16401,6 +17059,7 @@ program
         detail: opts.detail,
         scope: opts.scope,
         targetIds,
+        entities,
     });
     if (!result.ok) {
         console.error(`Error: ${result.error}`);
@@ -16521,6 +17180,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