@tpsdev-ai/flair 0.46.0 → 0.47.0

package/dist/postinstall.cjs

@@ -0,0 +1,88 @@
+"use strict";
+/**
+ * postinstall.cts — `npm install -g` PATH check (flair#1134).
+ *
+ * THIS IS THE POSTINSTALL ENTRY (`package.json` "postinstall" requires
+ * dist/postinstall.cjs). It exists for exactly one case: a user-prefix
+ * global install (prefix = ~/.npm-global or similar) where npm links the
+ * `flair` bin into a directory that is not on PATH. The install "succeeds",
+ * then `flair` is command-not-found, and the docs' one-command install claim
+ * is a lie. This is the only surface that can reach the user at the moment
+ * that happens — a first-run banner can never run, because the bin the user
+ * would run is precisely what's unreachable.
+ *
+ * History note (#1078/#1008): the previous postinstall was removed because it
+ * was a NO-OP (chmod +x on bins npm already marks executable) that cost an
+ * install-script approval line. This one is not that: it does work no other
+ * surface can, it is read-only (env + one existsSync — no network, no
+ * writes), and it NEVER fails the install (every path swallows errors and
+ * exits 0). Where lifecycle scripts are suppressed — `--ignore-scripts`,
+ * bun without trustedDependencies, the fleet's tar-swap deploys (the #1078
+ * path, which manages PATH itself) — `flair doctor` runs the same check.
+ *
+ * Delivery: npm ≥8 hides lifecycle-script output on success (it only shows
+ * with --foreground-scripts or on failure), so printing to stderr alone
+ * would be invisible exactly where it matters. We write to /dev/tty first —
+ * that bypasses npm's captured pipes and lands on the interactive terminal —
+ * and fall back to stderr (visible under --foreground-scripts, bun, older
+ * npm; harmlessly buffered otherwise). No TTY (CI) ⇒ the fallback is the
+ * only path, which is the right amount of noise for CI: none visible.
+ *
+ * Like cli-shim.cts this is CommonJS on purpose: it parses and runs on any
+ * Node a user could have, and the ESM helper is loaded via dynamic import()
+ * with every failure swallowed — a postinstall must never be the thing that
+ * breaks an install.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+function writeToTty(text) {
+    // npm captures the script's stdout/stderr pipes; the controlling terminal
+    // does not go through them. Best-effort, sync, closed either way.
+    //
+    // FLAIR_POSTINSTALL_NO_TTY: unit tests spawn this entry and assert on the
+    // stderr fallback; without the knob, a dev running the suite from a real
+    // terminal would have /dev/tty succeed — scribbling the banner over their
+    // screen and blanking the stderr the test asserts on (flaky by
+    // environment). The tty path's own coverage is the manual pty
+    // verification recorded in the flair#1134 PR (`script`-wrapped npm i -g).
+    if (process.env.FLAIR_POSTINSTALL_NO_TTY)
+        return false;
+    try {
+        var fs = require("node:fs");
+        var fd = fs.openSync("/dev/tty", "w");
+        try {
+            fs.writeSync(fd, text);
+        }
+        finally {
+            fs.closeSync(fd);
+        }
+        return true;
+    }
+    catch (e) {
+        return false;
+    }
+}
+import("./install/global-bin-path.js")
+    .then(function (mod) {
+    try {
+        var path = require("node:path");
+        var message = mod.postinstallWarning({
+            npmConfigGlobal: process.env.npm_config_global,
+            npmConfigPrefix: process.env.npm_config_prefix,
+            pathEnv: process.env.PATH,
+            shell: process.env.SHELL,
+            // __dirname is <pkg>/dist — the package root is one up.
+            packageDir: path.resolve(__dirname, ".."),
+        });
+        if (message) {
+            var banner = "\n@tpsdev-ai/flair postinstall:\n\n" + message + "\n";
+            if (!writeToTty(banner))
+                console.error(banner);
+        }
+    }
+    catch (e) {
+        // Never fail the install over a diagnostic.
+    }
+})
+    .catch(function () {
+    // Helper unloadable (ancient Node, partial install) — never fail the install.
+});

package/dist/rem/runner.js

@@ -67,6 +67,43 @@ export const REM_NIGHTLY_LOG = resolve(homedir(), ".flair", "logs", "rem-nightly
 // adk: tag under scope:"tagged", so each user's claims come only from that
 // user's sessions.
 export const ADK_TAG_PREFIX = "adk:";
+// ─── Continuity-journal distillation (flair#1257 slice 3) ────────────────────
+// The session-continuity journal (slice 2, #1283) writes ephemeral+private
+// rows tagged `adk:continuity:<sessionId>`. Those tags share the `adk:` prefix
+// but are NOT per-user ADK tags — they are per-SESSION journals with their own
+// selection rule: a session is distilled only once it has SETTLED (its newest
+// entry older than the settle window — never distill a live session) and only
+// while it still has un-expired entries (the journal rows carry the ephemeral
+// TTL; a fully-expired session has nothing left to distill). deriveActiveAdkTags
+// EXCLUDES continuity tags for the same reason: the recency-based "active"
+// rule would distill a session that is still live.
+//
+// Canonical prefix string duplicated in packages/flair-mcp/src/continuity.ts
+// (CONTINUITY_TAG_PREFIX — the writer) and resources/memory-reflect-lib.ts /
+// resources/auto-promote-lib.ts (CONTINUITY_SCOPE_TAG_PREFIX) — src/,
+// packages/ and resources/ sit on opposite sides of npm-packaging boundaries
+// (imports across them don't survive packaging; see src/cli.ts's header), so
+// they are kept in sync by the shared canonical string.
+export const CONTINUITY_TAG_PREFIX = "adk:continuity:";
+/**
+ * Settle window (ms) for continuity-session selection — a session is
+ * distillable only when its NEWEST entry is older than this (Kern's ruling:
+ * the window is measured on the newest entry's createdAt, which is
+ * load-bearing — a 6h-long session whose last entry is 30min old is still
+ * LIVE and must not be distilled; measuring on the oldest entry would
+ * distill it). Default 2h, configurable via FLAIR_REM_SETTLE_HOURS.
+ */
+export const DEFAULT_REM_SETTLE_MS = 2 * 3600_000;
+/** Resolve the settle window: explicit override > FLAIR_REM_SETTLE_HOURS env
+ *  (positive, finite) > DEFAULT_REM_SETTLE_MS. Exported for tests. */
+export function resolveSettleMs(override, env = process.env) {
+    if (typeof override === "number" && Number.isFinite(override) && override >= 0)
+        return override;
+    const hours = Number(env.FLAIR_REM_SETTLE_HOURS);
+    if (Number.isFinite(hours) && hours > 0)
+        return hours * 3600_000;
+    return DEFAULT_REM_SETTLE_MS;
+}
 /**
  * Recency window (ms) used to decide which adk: tags are ACTIVE — a tag is
  * enumerated (and distilled) only if it has memory records created within this
@@ -224,12 +261,79 @@ export function deriveActiveAdkTags(memories, sinceDate, agentId) {
         if (!Array.isArray(mt))
             continue;
         for (const t of mt) {
+            // flair#1257 slice 3: continuity tags share the adk: prefix but are
+            // per-SESSION journals, not per-user ADK tags — they get their own
+            // settle-window selection (deriveSettledContinuityTags). Admitting
+            // them here would distill a session that is still LIVE (the recency
+            // rule treats "written recently" as a reason TO distill; for a
+            // journal it is the reason NOT to).
+            if (typeof t === "string" && t.startsWith(CONTINUITY_TAG_PREFIX))
+                continue;
             if (typeof t === "string" && t.startsWith(ADK_TAG_PREFIX))
                 tags.add(t);
         }
     }
     return [...tags].sort();
 }
+/**
+ * Derive the DISTINCT continuity-session tags that are SETTLED and still
+ * distillable (flair#1257 slice 3 — the session-selection step). A tag is
+ * returned iff, over this agent's OWN un-expired journal rows carrying it:
+ *
+ *   - the NEWEST entry's createdAt is at least `settleMs` old (the settle
+ *     window, Kern's ruling — measured on the newest entry so a long-running
+ *     session that wrote 30min ago is still live and excluded), and
+ *   - at least one entry is un-expired (`expiresAt` absent or in the future)
+ *     — "younger than TTL expiry": a fully-expired session has nothing left
+ *     to distill (its rows are reaped, or excluded from the gather either
+ *     way; see resources/MemoryReflect.ts's expired-row skip).
+ *
+ * Same owner-scoping discipline as deriveActiveAdkTags above (the snapshot
+ * fetch is org-wide; the per-record agentId check is load-bearing — no
+ * cross-agent session enumeration), and the same no-extra-query property:
+ * this reduces over the memories the cycle already fetched.
+ */
+export function deriveSettledContinuityTags(memories, params) {
+    const { agentId, now, settleMs } = params;
+    const newestByTag = new Map();
+    for (const m of memories) {
+        if (!m || typeof m !== "object")
+            continue;
+        if (m.agentId !== agentId)
+            continue; // owner scope (fetch is org-wide)
+        // The JOURNAL is the ephemeral tier. Promoted rows PRESERVE the session
+        // scopeTag but are persistent — counting them would keep a session
+        // selectable (and re-distilled) forever after its journal expired.
+        if (m.durability !== "ephemeral")
+            continue;
+        // TTL: only un-expired rows count — an expired row neither keeps a
+        // session selectable nor (below) marks it live.
+        if (typeof m.expiresAt === "string" && m.expiresAt !== "" && new Date(m.expiresAt) <= now)
+            continue;
+        const createdAt = m.createdAt ? new Date(m.createdAt).getTime() : NaN;
+        if (!Number.isFinite(createdAt))
+            continue;
+        const mt = m.tags;
+        if (!Array.isArray(mt))
+            continue;
+        for (const t of mt) {
+            if (typeof t !== "string" || !t.startsWith(CONTINUITY_TAG_PREFIX))
+                continue;
+            if (t.length <= CONTINUITY_TAG_PREFIX.length)
+                continue; // bare prefix is not a session
+            const prev = newestByTag.get(t);
+            if (prev === undefined || createdAt > prev)
+                newestByTag.set(t, createdAt);
+        }
+    }
+    const settled = [];
+    const cutoff = now.getTime() - settleMs;
+    for (const [tag, newest] of newestByTag) {
+        if (newest <= cutoff)
+            settled.push(tag);
+    }
+    return settled.sort();
+}
 /**
  * Runs one nightly cycle for the given agent. See module header for steps.
  * Pure orchestration; all I/O goes through injected dependencies.
@@ -363,8 +467,11 @@ export async function runNightlyCycle(opts) {
     // this all runs inside the one cycle on the one node.
     let candidates;
     // #1205b-2: outcome of the post-distillation auto-promote step, assigned
-    // inside the !dryRun block below (only when this is an ADK agentId).
+    // inside the !dryRun block below (only when this is an ADK agentId or a
+    // cycle that distilled settled continuity sessions — flair#1257 slice 3).
     let autoPromoted;
+    // flair#1257 slice 3: settled continuity sessions distilled this cycle.
+    let continuitySessions;
     const collectStagedIds = (obj) => asArray(obj.candidates)
         .map((c) => (c && typeof c === "object" ? c.id : c))
         .filter((id) => typeof id === "string");
@@ -438,16 +545,75 @@ export async function runNightlyCycle(opts) {
                 errors.push(`distillation: ${describeApiError(err?.message ?? err)}`);
             }
         }
+        // ── Step 5a (flair#1257 slice 3): continuity-session distillation ─────────
+        // Runs IN ADDITION to whichever path above ran — continuity journals are
+        // per-session, not per-user, and a non-ADK agent (the primary continuity
+        // consumer) still gets its regular agentId-only distill above. Selection:
+        // deriveSettledContinuityTags — only SETTLED (newest entry older than the
+        // settle window; never a live session) and un-expired sessions. Each runs
+        // scope:"tagged" with focus:"continuity" (the server enforces the
+        // continuity guard set for continuity tags regardless — the focus here is
+        // explicitness, not the enforcement point). Shares the per-cycle tag cap
+        // with the ADK path (Kern 1b); a deferred SETTLED session stays settled
+        // and is re-selected next cycle while its rows are un-expired (with the
+        // default 24h TTL and a nightly cadence a deferral can age a session out
+        // — acceptable at the 200-tag cap, recorded in `errors` when it happens).
+        // Same non-fatal per-tag failure discipline as the ADK path.
+        const settleMs = resolveSettleMs(opts.settleMs);
+        const settledContinuityTags = deriveSettledContinuityTags(fetchedMemories, {
+            agentId: opts.agentId,
+            now: startedAt,
+            settleMs,
+        });
+        const continuityBudget = Math.max(0, maxTags - Math.min(activeAdkTags.length, maxTags));
+        const continuityToRun = settledContinuityTags.slice(0, continuityBudget);
+        if (settledContinuityTags.length > continuityToRun.length) {
+            errors.push(`distillation: ${settledContinuityTags.length - continuityToRun.length} settled continuity session(s) deferred by the per-cycle tag cap (${maxTags}); re-selected next cycle while un-expired`);
+        }
+        if (continuityToRun.length > 0) {
+            // `candidates` is defined whenever distillation was ATTEMPTED (same
+            // contract as both paths above).
+            candidates = candidates ?? [];
+            let distilled = 0;
+            for (const tag of continuityToRun) {
+                try {
+                    const reflectRaw = await opts.apiCall("POST", "/ReflectMemories", {
+                        agentId: opts.agentId,
+                        execute: true,
+                        scope: "tagged",
+                        tag,
+                        focus: "continuity",
+                    });
+                    const obj = (reflectRaw && typeof reflectRaw === "object") ? reflectRaw : {};
+                    if (obj.error) {
+                        errors.push(`distillation[${tag}]: ${describeApiError(obj.error)}`);
+                    }
+                    else {
+                        candidates.push(...collectStagedIds(obj));
+                        distilled++;
+                    }
+                }
+                catch (err) {
+                    errors.push(`distillation[${tag}]: ${describeApiError(err?.message ?? err)}`);
+                }
+            }
+            continuitySessions = distilled;
+        }
         // ── Step 5b (#1205b-2): server-side ADK auto-promote ───────────────────────
-        // Only for an ADK agentId (active adk: tags this cycle) — a non-ADK agent
-        // has no scopeTag-bearing candidates, so there is nothing to auto-promote
-        // and no call is made. The SERVER enforces every security invariant
-        // (memory-only target, fail-closed tag lineage, content-safety, machine
-        // reviewerId) — the runner only TRIGGERS the sweep; it never itself decides
-        // where a claim lands. Non-fatal like distillation: a failure is recorded
-        // and the candidates stay pending (re-swept next cycle, or promotable by the
-        // human `rem promote` path). Bounded by the per-cycle cap.
-        if (activeAdkTags.length > 0) {
+        // For an ADK agentId (active adk: tags this cycle) OR a cycle that
+        // distilled settled continuity sessions (flair#1257 slice 3 — continuity
+        // candidates carry the session's adk:continuity: scopeTag and ride the
+        // same server-side sweep, promoted default-private-unless per Sherlock's
+        // ruling). An agent with neither has no scopeTag-bearing candidates, so
+        // there is nothing to auto-promote and no call is made. The SERVER
+        // enforces every security invariant (memory-only target, fail-closed tag
+        // lineage, content-safety, machine reviewerId, default-private
+        // visibility) — the runner only TRIGGERS the sweep; it never itself
+        // decides where a claim lands or who can read it. Non-fatal like
+        // distillation: a failure is recorded and the candidates stay pending
+        // (re-swept next cycle, or promotable by the human `rem promote` path).
+        // Bounded by the per-cycle cap.
+        if (activeAdkTags.length > 0 || continuityToRun.length > 0) {
             try {
                 const apRaw = await opts.apiCall("POST", "/AutoPromoteCandidates", {
                     agentId: opts.agentId,
@@ -525,6 +691,7 @@ export async function runNightlyCycle(opts) {
         expired,
         candidates,
         autoPromoted,
+        continuitySessions,
         dedup,
         durationMs: Date.now() - startedMs,
         errors,

package/dist/rem/scheduler.js

@@ -26,10 +26,16 @@ import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readT
 // flair#850's lesson must have exactly one implementation).
 export { interpretActiveResult };
 export const SHIM_PATH_DEFAULT = resolve(homedir(), ".flair", "bin", "flair-rem-nightly");
-export const LAUNCHD_PLIST_PATH = resolve(homedir(), "Library", "LaunchAgents", "dev.flair.rem.nightly.plist");
+// Unit names, exported (flair#1278) so `flair doctor`'s scheduled-drivers
+// section addresses the same job this module installs — same single-source
+// rule as the federation scheduler's LAUNCHD_LABEL/SYSTEMD_*_UNIT constants.
+export const LAUNCHD_LABEL = "dev.flair.rem.nightly";
+export const SYSTEMD_TIMER_UNIT = "flair-rem-nightly.timer";
+export const SYSTEMD_SERVICE_UNIT = "flair-rem-nightly.service";
+export const LAUNCHD_PLIST_PATH = resolve(homedir(), "Library", "LaunchAgents", `${LAUNCHD_LABEL}.plist`);
 export const SYSTEMD_USER_DIR = resolve(homedir(), ".config", "systemd", "user");
-export const SYSTEMD_TIMER_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.timer");
-export const SYSTEMD_SERVICE_PATH = resolve(SYSTEMD_USER_DIR, "flair-rem-nightly.service");
+export const SYSTEMD_TIMER_PATH = resolve(SYSTEMD_USER_DIR, SYSTEMD_TIMER_UNIT);
+export const SYSTEMD_SERVICE_PATH = resolve(SYSTEMD_USER_DIR, SYSTEMD_SERVICE_UNIT);
 function detectPlatform(override) {
     return detectPlatformFor("REM nightly scheduler", override);
 }
@@ -113,9 +119,9 @@ function buildSubstitutions(opts, shimPath, flairBin, nodeBin) {
  */
 function activeCheckCommand(plat) {
     if (plat === "darwin") {
-        return ["launchctl", "print", `gui/${process.getuid?.() ?? ""}/dev.flair.rem.nightly`];
+        return ["launchctl", "print", `gui/${process.getuid?.() ?? ""}/${LAUNCHD_LABEL}`];
     }
-    return ["systemctl", "--user", "is-active", "flair-rem-nightly.timer"];
+    return ["systemctl", "--user", "is-active", SYSTEMD_TIMER_UNIT];
 }
 /**
  * Synchronous active-state check for CLI use (`flair rem nightly status`).
@@ -369,7 +375,7 @@ export function enableScheduler(opts) {
                 // remedy — kickstarting on top of it would blur which actor failed.
                 firstRun = verifyFirstRun({
                     plat,
-                    darwinTarget: `gui/${process.getuid?.() ?? ""}/dev.flair.rem.nightly`,
+                    darwinTarget: `gui/${process.getuid?.() ?? ""}/${LAUNCHD_LABEL}`,
                     stderrLogPath,
                 });
             }
@@ -386,7 +392,7 @@ export function enableScheduler(opts) {
     const timerContents = renderTemplate(readTemplate(templateRoot, "systemd/flair-rem-nightly.timer.tmpl"), subs);
     writeFileWithDir(servicePath, serviceContents, 0o600);
     writeFileWithDir(timerPath, timerContents, 0o600);
-    const loadCommand = ["systemctl", "--user", "enable", "--now", "flair-rem-nightly.timer"];
+    const loadCommand = ["systemctl", "--user", "enable", "--now", SYSTEMD_TIMER_UNIT];
     let loadResult;
     let firstRun;
     if (!opts.skipLoad) {
@@ -396,7 +402,7 @@ export function enableScheduler(opts) {
             // Ordering gate (#1231): only after the load exited 0. Starts the
             // SERVICE unit directly (oneshot ⇒ blocks until the run exits) rather
             // than waiting for the nightly timer to fire.
-            firstRun = verifyFirstRun({ plat, linuxServiceUnit: "flair-rem-nightly.service", stderrLogPath });
+            firstRun = verifyFirstRun({ plat, linuxServiceUnit: SYSTEMD_SERVICE_UNIT, stderrLogPath });
         }
     }
     return {
@@ -432,7 +438,7 @@ export function disableScheduler(opts = {}) {
     }
     const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
     const servicePath = opts.systemdServiceOverride ?? SYSTEMD_SERVICE_PATH;
-    const unloadCommand = ["systemctl", "--user", "disable", "--now", "flair-rem-nightly.timer"];
+    const unloadCommand = ["systemctl", "--user", "disable", "--now", SYSTEMD_TIMER_UNIT];
     let unloadResult;
     if (existsSync(timerPath) || existsSync(servicePath)) {
         if (!opts.skipUnload) {

package/dist/resources/AttentionQuery.js

@@ -77,7 +77,7 @@
  */
 import { Resource, databases } from "harper";
 import { resolveAgentAuth, allowVerified } from "./agent-auth.js";
-import { isValidEntity } from "./entity-vocab.js";
+import { entityFormatHint, isValidEntity } from "./entity-vocab.js";
 import { resolveReadScope } from "./memory-read-scope.js";
 import { withDetachedTxn } from "./table-helpers.js";
 import { checkRateLimit, rateLimitResponse } from "./rate-limiter.js";
@@ -102,7 +102,7 @@ const UNAUTH = () => new Response(JSON.stringify({ error: "authentication requir
 function parseQueryInput(data) {
     const entity = data?.entity;
     if (typeof entity !== "string" || entity.length === 0) {
-        return badRequest("invalid_entity", "entity is required (a vocabulary string, e.g. 'repo:owner/name')");
+        return badRequest("invalid_entity", `entity is required — ${entityFormatHint()}`);
     }
     // Exact match on the full type:value string — the SAME validator every
     // write path (Memory/WorkspaceState/OrgEvent) gates `entities` writes
@@ -110,7 +110,9 @@ function parseQueryInput(data) {
     // closed, documented type set / grammar — never a prefix/regex match, so
     // this stays a plain indexed equality lookup, never a scan.
     if (!isValidEntity(entity)) {
-        return badRequest("invalid_entity", `'${entity}' is not a well-formed vocabulary string (type:value, closed type set)`);
+        // flair#1288 (canary finding 5): the rejection must say what well-formed
+        // looks like — name the type:value format and enumerate the valid types.
+        return badRequest("invalid_entity", `'${entity}' is not a well-formed vocabulary string — ${entityFormatHint()}`);
     }
     let days = DEFAULT_WINDOW_DAYS;
     if (data?.days !== undefined && data?.days !== null) {

package/dist/resources/AutoPromoteCandidates.js

@@ -42,7 +42,7 @@ import { Resource, databases, logger } from "harper";
 import { isAdmin, allowVerified } from "./agent-auth.js";
 import { resolveReflectActor } from "./memory-reflect-lib.js";
 import { agentContext } from "./in-process.js";
-import { decideAutoPromote, buildAutoPromotedTags, DEFAULT_MAX_AUTO_PROMOTE_PER_CYCLE, } from "./auto-promote-lib.js";
+import { decideAutoPromote, buildAutoPromotedTags, decidePromotedVisibility, DEFAULT_MAX_AUTO_PROMOTE_PER_CYCLE, } from "./auto-promote-lib.js";
 export class AutoPromoteCandidates extends Resource {
     // Any verified agent may trigger a sweep of ITS OWN candidates; the actor
     // resolution in post() enforces the own-only scope. Same gate ReflectMemories
@@ -124,20 +124,26 @@ export class AutoPromoteCandidates extends Resource {
                 agentId,
                 content: c.claim,
                 durability: "persistent",
-                // ── visibility: PRIVATE, explicit (Sherlock cross-agent leak fix) ──────
+                // ── visibility: DEFAULT-PRIVATE-UNLESS, explicit (Sherlock) ───────────
                 // MUST be set. Memory.put() defaults an unset visibility from durability
                 // (Memory.ts) and "persistent" defaults to "shared" — and "shared" is
                 // ORG-OPEN (memory-read-scope.ts): readable by EVERY verified agent on
-                // the instance. The source episodes are the user's PRIVATE session data
-                // (durability:"standard" → default private), and the per-user boundary
-                // is adk-flair's CLIENT-SIDE tag re-verification, which OTHER agents do
-                // NOT run. So a shared auto-promoted claim would leak a user's distilled
-                // private data to every agent on the box — unattended. "private" is
-                // owner-only, so the claim is reachable ONLY through the app agent's own
-                // tag-filtered search (which re-verifies the tag) and is invisible to
-                // every other agent. This keeps the blast radius inside the one agentId,
-                // which is the entire #1205 safety argument.
-                visibility: "private",
+                // the instance. The sources are the most sensitive tiers (a user's
+                // PRIVATE session episodes, or an agent's ephemeral+private continuity
+                // journal), so promotion is a visibility ESCALATION and the default —
+                // including every uncertainty fallback — is "private".
+                //
+                // decidePromotedVisibility (auto-promote-lib.ts) returns "shared" ONLY
+                // for a CONTINUITY-scoped candidate carrying an AFFIRMATIVE distiller
+                // ruling with a recorded team-relevance justification (flair#1257
+                // slice 3 — a shared row always traces to a justification on its
+                // candidate, never to a default). ADK per-user candidates remain
+                // ALWAYS private regardless of any ruling: their per-user boundary is
+                // adk-flair's CLIENT-SIDE tag re-verification, which OTHER agents do
+                // NOT run — a shared ADK promotion would leak a user's distilled
+                // private data to every agent on the box, unattended. That is the
+                // entire #1205 safety argument, unchanged.
+                visibility: decidePromotedVisibility(c),
                 // scopeTag FIRST — the per-user access-control boundary (Req 2).
                 tags: buildAutoPromotedTags(c.id, decision.scopeTag),
                 derivedFrom: Array.isArray(c.sourceMemoryIds) ? c.sourceMemoryIds : [],

package/dist/resources/Federation.js

@@ -86,7 +86,23 @@ export class FederationInstance extends Resource {
                 break;
             }
         }
-        catch { /* table may not exist */ }
+        catch (err) {
+            // Expected on genuine first boot: the Instance table doesn't exist yet,
+            // and the create branch below handles that. But a bare swallow here also
+            // hid every OTHER read failure (storage, permissions), making a
+            // persistently failing read indistinguishable from first boot
+            // (flair#1233). Log the error class so the two are tellable apart in
+            // server logs; behavior is unchanged — fall through to create.
+            console.warn("[federation] Instance read failed — proceeding as first boot (create branch will run). " +
+                "If this instance already has an identity, this is a real read error, not an absent table. " +
+                `${err?.constructor?.name ?? "Error"}: ${err?.message ?? err}`);
+        }
+        // Runtime-only signal (flair#1233): whether this instance's private key
+        // seed is present in the keystore, i.e. whether it can SIGN (pair/sync).
+        // Deliberately NOT persisted — the Instance.status enum is
+        // schema-constrained and this is transient machine state; recomputed on
+        // every GET.
+        let signingKeyAvailable = false;
         if (!instance) {
             // First boot — generate instance identity
             const kp = nacl.sign.keyPair();
@@ -101,16 +117,42 @@ export class FederationInstance extends Resource {
                 updatedAt: new Date().toISOString(),
             };
             await databases.flair.Instance.put(instance);
-            // Store private key seed in encrypted keystore (not in DB)
+            // Store private key seed in encrypted keystore (not in DB).
+            //
+            // flair#1233: a keystore failure no longer aborts the GET. This is a
+            // READ path — the response never uses the private key, and the old
+            // throw here left federation state entirely unobservable on hosts
+            // whose HOME isn't writable (the #812 ENOTDIR class; keysDir() is
+            // homedir()-relative). Fail-closed stays where the key is USED:
+            // signing, in pair/sync, still throws when the key is absent. Here the
+            // failure is logged server-side and surfaced to the caller as
+            // signingKeyAvailable:false. Plaintext keys still never touch the DB.
             try {
                 const { keystore } = await import("../src/keystore.js");
                 const seed = kp.secretKey.slice(0, 32);
                 keystore.setPrivateKeySeed(id, seed);
+                signingKeyAvailable = true;
             }
             catch (err) {
-                // Fail closed — never store plaintext keys in the database
-                console.error("[federation] FATAL: Could not store key seed in keystore. Federation identity not created.", err);
-                throw new Error("Keystore unavailable — cannot create federation identity without secure key storage");
+                console.error("[federation] Could not store the federation signing key seed in the keystore " +
+                    "($HOME/.flair/keys, relative to the Harper process's HOME). The identity row was created and " +
+                    "reads work, but this instance cannot sign — pair/sync will fail until the keystore is fixed. " +
+                    "Remedy: make $HOME/.flair/keys a directory writable by the Harper process (mode 0700). " +
+                    "The seed for THIS identity was never stored, so after fixing the keystore, re-key: delete the " +
+                    "Instance row and re-pair to mint a fresh identity. " +
+                    `${err?.constructor?.name ?? "Error"}: ${err?.message ?? err}`);
+            }
+        }
+        else {
+            // Existing identity: report whether its signing key is present and
+            // decryptable. getPrivateKeySeed is a read-only probe that returns null
+            // (never throws) when the key file is missing or unreadable.
+            try {
+                const { keystore } = await import("../src/keystore.js");
+                signingKeyAvailable = keystore.getPrivateKeySeed(instance.id) !== null;
+            }
+            catch {
+                signingKeyAvailable = false;
             }
         }
         return {
@@ -118,6 +160,8 @@ export class FederationInstance extends Resource {
             publicKey: instance.publicKey,
             role: instance.role,
             status: instance.status,
+            // Runtime-only — see above; never persisted.
+            signingKeyAvailable,
         };
     }
 }

package/dist/resources/Memory.js

@@ -887,6 +887,30 @@ export class Memory extends databases.flair.Memory {
         if (!preExisting && (content.visibility === undefined || content.visibility === null)) {
             content.visibility = defaultVisibilityForDurability(content.durability);
         }
+        // ── flair#1257 slice 3: stamp the ephemeral TTL on the PUT path too ──────
+        // post() has stamped expiresAt for ephemeral rows since the tier shipped,
+        // but put() — the verb the continuity capture hook actually writes with
+        // (`PUT /Memory/<id>`, packages/flair-mcp/src/continuity-capture-hook.ts)
+        // — never did. MemoryMaintenance's reap keys on expiresAt (expired =
+        // expiresAt < now), so hook-written journal rows carried NO expiry and
+        // the tier's load-bearing 24h containment bound (the exposure window the
+        // #1257 rulings cite) silently never engaged on the real write path.
+        // Effective durability = the write's, else the pre-existing row's (same
+        // resolution the visibility guard above uses). A pre-existing expiry is
+        // carried forward, never re-stamped — an update must not extend the
+        // exposure window; an explicit caller-provided expiresAt always wins.
+        {
+            const effectiveDurability = content.durability ?? preExisting?.durability;
+            if (effectiveDurability === "ephemeral" && !content.expiresAt) {
+                if (preExisting?.expiresAt) {
+                    content.expiresAt = preExisting.expiresAt;
+                }
+                else {
+                    const ttlHours = Number(process.env.FLAIR_EPHEMERAL_TTL_HOURS || 24);
+                    content.expiresAt = new Date(Date.now() + ttlHours * 3600_000).toISOString();
+                }
+            }
+        }
         // supersedes: optional reference to the ID of the memory this one
         // replaces. Validates shape + cross-agent-write authorization (shared
         // with post() — see validateAndAuthorizeSupersedes doc for why PUT needs
@@ -967,8 +991,18 @@ export class Memory extends databases.flair.Memory {
         if (content.promotionStatus === "approved" && !content.promotedAt) {
             content.promotedAt = now;
         }
-        // Upgrade to permanent when approved
-        if (content.promotionStatus === "approved") {
+        // Upgrade to permanent when approved — the LEGACY in-place approval flow
+        // (an admin marks an EXISTING row approved without naming a tier; the
+        // auth-middleware admin-gates setting promotionStatus over HTTP). An
+        // explicit durability on the SAME write now wins (flair#1257 slice 3):
+        // the candidate-promotion paths (#1205b-2 /AutoPromoteCandidates and the
+        // human `flair rem promote`) write NEW rows carrying promotionStatus:
+        // "approved" purely as an audit stamp ALONGSIDE an explicit durability:
+        // "persistent" — the unconditional coercion here silently lifted every
+        // promoted claim into the never-reaped permanent tier while every audit
+        // surface (CLI output, specs, review rulings) said persistent. A write
+        // that names its tier keeps it; only a tier-less approval still upgrades.
+        if (content.promotionStatus === "approved" && (content.durability === undefined || content.durability === null)) {
             content.durability = "permanent";
         }
         // Write-time provenance stamp (memory-provenance slice 1) — see