@tpsdev-ai/flair 0.44.13 → 0.46.0

package/config.yaml

@@ -16,9 +16,42 @@ authentication:
       clientId: ${OAUTH_GITHUB_CLIENT_ID}
       clientSecret: ${OAUTH_GITHUB_CLIENT_SECRET}
   mcp:
-    enabled: false
+    # WHOLE-TOKEN env reference — the same FLAIR_MCP_OAUTH flag flair's
+    # in-process /mcp route gates on (resources/mcp-oauth-flag.ts). The on/off
+    # choice lives in the instance ENVIRONMENT, not in this packed file, so a
+    # re-packed deploy can no longer revert an operator's enablement
+    # (flair#1152). Requires @harperfast/oauth >= 2.5.0 (resolved-version
+    # assertion + behavioral gate: test/integration/mcp-oauth-boot-safety.test.ts).
+    #
+    # ASYMMETRY (load-bearing, measured on oauth 2.5.0): the two readers of
+    # this flag accept DIFFERENT vocabularies. The component's
+    # coerceConfigBoolean accepts ONLY "true"/"false" and DELETES any other
+    # string (unresolved placeholder, "1", "yes", garbage) so its disabled
+    # default applies. flair's mcpOAuthEnabled() accepts 1/true/yes/on.
+    #
+    # Failure modes (oauth 2.5.0):
+    #   unset             -> placeholder deleted -> both sides OFF, clean boot
+    #   true              -> BOTH sides ON — the one working enable value
+    #                        (`flair mcp enable` stages exactly this)
+    #   false             -> both sides OFF
+    #   1 / yes / on      -> flair /mcp handler ON, component AS OFF ->
+    #                        fail-closed broken-on: every /mcp request 401s,
+    #                        no AS is advertised. Use "true" instead.
+    #   garbage (maybe)   -> deleted -> component OFF; flair strict -> OFF.
+    #                        Inert: no /mcp handler, no data path (flair's own
+    #                        discovery documents still serve, by design).
+    # On oauth <2.5.0 there is NO normalization: an unresolved placeholder is
+    # a truthy string (fail-open) — the version assertion exists for that.
+    # If the component's `enabled` vocabulary changes, or it ever drives
+    # flair's handler registration directly, re-derive this table first.
+    enabled: ${FLAIR_MCP_OAUTH}
     issuer: ${FLAIR_MCP_ISSUER}
-    resource: ${FLAIR_MCP_ISSUER}/mcp
+    # No `resource:` key ON PURPOSE (flair#1180): when absent, the component
+    # derives `<issuer>/mcp` at request time (resolveResource) — identical to
+    # flair's in-process derivation. A composite like ${FLAIR_MCP_ISSUER}/mcp
+    # NEVER interpolates (env expansion is whole-token-only) and fails every
+    # connect with invalid_target. Escape hatch: an operator needing a
+    # non-standard resource sets an explicit LITERAL absolute URL here.
     accessTokenTtl: 900
     dynamicClientRegistration:
       enabled: false

package/dist/cli.js

@@ -23,8 +23,8 @@ 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, 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 { 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";
@@ -1604,6 +1604,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 +3513,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}`);
@@ -3743,6 +3928,7 @@ agent
     .option("--name <name>", "Display name (defaults to id)")
     .option("--port <port>", "Harper HTTP port")
     .option("--admin-pass <pass>", "Admin password for registration")
+    .option("--admin-pass-file <path>", "Read the admin password from a file (chmod 600 enforced). Preferred over inline --admin-pass — keeps the secret out of ps and shell history; works for remote targets too (an explicit flag is operator intent).")
     .option("--keys-dir <dir>", "Directory for Ed25519 keys")
     .option("--ops-port <port>", "Harper operations API port")
     .option("--target <url>", "Remote Flair REST URL; derives the ops API URL (port-1) to seed the Agent there (env: FLAIR_TARGET)")
@@ -3759,6 +3945,22 @@ agent
     // `flair import`: explicit --ops-target > derive from --target > localhost.
     const seedOpsTarget = resolveEffectiveOpsUrl({ target: opts.target, opsTarget: opts.opsTarget }) ?? opsPort;
     const isRemoteTarget = typeof seedOpsTarget === "string";
+    // flair#1259 — --admin-pass-file resolves into the same explicit slot the
+    // inline flag uses (same shape as `flair federation sync`), read in-process
+    // via readAdminPassFileSecure so the secret never appears in ps or shell
+    // history. This does NOT weaken the #1085 remote guard below: an explicit
+    // flag naming a file IS operator intent toward this target, exactly like an
+    // explicit inline --admin-pass — what the guard blocks is the AMBIENT
+    // env/local-file fallbacks silently traveling to a third-party host.
+    if (!opts.adminPass && opts.adminPassFile) {
+        try {
+            opts.adminPass = readAdminPassFileSecure(opts.adminPassFile);
+        }
+        catch (err) {
+            console.error(`Error reading --admin-pass-file ${opts.adminPassFile}: ${err.message}`);
+            process.exit(1);
+        }
+    }
     // #590 — local convenience fallback: FLAIR_ADMIN_PASS env, then the secure
     // ~/.flair/admin-pass file `flair init` already writes (mode 0600). Never
     // applied for a remote target — see resolveLocalAdminPass.
@@ -3772,12 +3974,13 @@ agent
     }
     if (!adminPass) {
         if (isRemoteTarget) {
-            console.error("Error: --admin-pass is required for agent add when targeting a remote instance " +
-                "(--target/--ops-target) — the local ~/.flair/admin-pass fallback is not used for remote targets.");
+            console.error("Error: --admin-pass <pass> or --admin-pass-file <path> is required for agent add when targeting " +
+                "a remote instance (--target/--ops-target) — the local ~/.flair/admin-pass and FLAIR_ADMIN_PASS " +
+                "fallbacks are never used for remote targets. Prefer --admin-pass-file: it keeps the secret out of ps.");
         }
         else {
-            console.error("Error: --admin-pass is required for agent add (needed to insert into Agent table). " +
-                "Set FLAIR_ADMIN_PASS, or make sure ~/.flair/admin-pass exists (created by `flair init`).");
+            console.error("Error: --admin-pass <pass> or --admin-pass-file <path> is required for agent add (needed to insert " +
+                "into Agent table). Set FLAIR_ADMIN_PASS, or make sure ~/.flair/admin-pass exists (created by `flair init`).");
         }
         process.exit(1);
     }
@@ -4341,6 +4544,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();
@@ -4351,6 +4555,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}`);
@@ -4370,10 +4586,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}`);
@@ -4396,6 +4625,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}`);
@@ -4407,6 +4652,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);
     }
@@ -4421,6 +4667,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 ───────────────────────────────────────────────────────────────
@@ -6415,6 +6662,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 [
@@ -6448,9 +6700,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;
@@ -6565,7 +6819,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`);
@@ -12285,6 +12545,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");
@@ -12598,6 +12912,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
@@ -13891,18 +14272,26 @@ sessionSnapshot
         console.error(`  Pass --target <new-path> or remove the existing dir.`);
         process.exit(1);
     }
+    // flair#903 — fail CLOSED on a tampered archive. node-tar's defaults below
+    // do contain malicious entries (leading "/" stripped, ".." entries
+    // dropped, no writing through a symlink — verified on the pinned tar
+    // against all four vectors), but they discard those entries SILENTLY: the
+    // restore printed the target dir as a plain success minus the parts it
+    // never mentioned. Validation runs BEFORE the target directory is even
+    // created — a tampered snapshot aborts the whole restore, names the
+    // offending entry, and writes nothing (same posture as the data-dir
+    // restore's extractSnapshotSafely). The default extract flags stay as
+    // containment defense-in-depth — deliberately NOT preservePaths; if that
+    // flag is ever added here, this call MUST move to extractSnapshotSafely.
+    // See src/lib/safe-snapshot-extract.ts.
+    try {
+        await validateSnapshotArchive({ file: snapshotPath, targetDir });
+    }
+    catch (err) {
+        console.error(`Error: ${err.message}`);
+        process.exit(1);
+    }
     mkdirSync(targetDir, { recursive: true, mode: 0o700 });
-    // Deliberately NOT preservePaths, and deliberately NOT routed through
-    // extractSnapshotSafely. --snapshot is an operator-supplied path, so
-    // provenance here is no more controlled than the data-dir restore's — the
-    // difference is the flag, not the trust. node-tar's defaults keep their
-    // own containment: leading "/" stripped from entry paths, ".." entries
-    // dropped, and no writing through a symlink (including one created
-    // earlier in the same archive). Verified against the pinned tar (7.5.20)
-    // on all four cases, each contained, with a benign control entry landing
-    // to prove the archives parsed. Add `preservePaths` here and that
-    // containment disappears — this call would then need extractSnapshotSafely,
-    // exactly as the data-dir restore does. See src/lib/safe-snapshot-extract.ts.
     await tarExtract({ file: snapshotPath, cwd: targetDir });
     console.log(targetDir);
     console.error(`  extracted to: ${targetDir}`);