@tpsdev-ai/flair 0.45.0 → 0.47.0

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

@@ -13,23 +13,29 @@
  * No daemon code lives here — the scheduler invokes the shim, the shim
  * invokes `flair rem nightly run-once`, the runner module does the work.
  */
-import { existsSync, chmodSync, rmSync } from "node:fs";
+import { existsSync, mkdirSync, chmodSync, rmSync } from "node:fs";
 import { resolve, dirname } from "node:path";
 import { homedir } from "node:os";
 import { spawn } from "node:child_process";
 import { fileURLToPath } from "node:url";
 import { escapeXml } from "../lib/xml-escape.js";
-import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
+import { detectPlatform as detectPlatformFor, spawnReport, readTemplate as readTemplateFrom, renderTemplateWith, writeFileWithDir, interpretActiveResult, describeLoadFailure as describeLoadFailureFor, describeExitCode, resolveNodeBin, verifyFirstRun, STATUS_CHECK_TIMEOUT_MS, } from "../lib/scheduler-platform.js";
 // Re-exported so this module's public surface is unchanged by the extraction
 // into src/lib/scheduler-platform.ts (a second scheduler — `flair federation
 // sync enable` — needs the identical launchctl/systemctl interpretation, and
 // 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);
 }
@@ -87,15 +93,16 @@ function validateSchedule(hour, minute) {
         throw new Error(`minute must be an integer 0-59, got ${minute}`);
     }
 }
-function buildSubstitutions(opts, shimPath, flairBin) {
+function buildSubstitutions(opts, shimPath, flairBin, nodeBin) {
     validateSchedule(opts.hour, opts.minute);
     if (!/^[a-zA-Z0-9_-]+$/.test(opts.agentId)) {
         throw new Error(`invalid agent id: ${opts.agentId}`);
     }
     return {
         FLAIR_BIN: flairBin,
+        NODE_BIN: nodeBin,
         SHIM_PATH: shimPath,
-        HOME: homedir(),
+        HOME: opts.homeOverride ?? homedir(),
         AGENT_ID: opts.agentId,
         FLAIR_URL: opts.flairUrl,
         HOUR: String(opts.hour),
@@ -112,9 +119,9 @@ function buildSubstitutions(opts, shimPath, flairBin) {
  */
 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`).
@@ -183,10 +190,14 @@ export function describeLoadFailure(plat, loadResult) {
  * succeeded) is unit-testable without spawning a real launchctl/systemctl or
  * parsing CLI argv.
  *
- * `r.loadResult` is only set when the load command actually ran (the CLI
- * never sets `skipLoad`). A missing `loadResult` (test-only path) is treated
- * as success — matches the CLI's real-world behavior, which always runs the
- * load command and therefore always gets a `loadResult`.
+ * flair#1231 deepened the #850 rule by one layer: activation exiting 0 proves
+ * the service manager ACCEPTED the job, not that the job can run — a stripped
+ * exec bit and a missing log directory both passed activation and killed the
+ * first real run invisibly. So the ✅ headline is now additionally gated on
+ * `firstRunVerified`: success may not be claimed until the thing the operator
+ * asked for — a REM run through the service manager — has been observed to
+ * happen once. A missing `loadResult`/`firstRun` (test-only skipLoad shape)
+ * therefore withholds the headline too, instead of being treated as success.
  */
 export function formatEnableReport(r, input) {
     const { hour, minute, agentId, flairUrl } = input;
@@ -212,6 +223,57 @@ export function formatEnableReport(r, input) {
         lines.push(`   Nothing is scheduled until activation succeeds. Check anytime with: flair rem nightly status`);
         return { lines, ok: false };
     }
+    if (!r.firstRunVerified) {
+        const fr = r.firstRun;
+        const headline = fr?.outcome === "run-failed"
+            ? `⚠️  REM nightly scheduler installed but the first run FAILED (${describeExitCode(fr.exitCode)})`
+            : fr?.outcome === "timeout"
+                ? `⚠️  REM nightly scheduler installed but the first run did not complete within ${Math.round(fr.budgetMs / 1000)}s — cannot confirm it works`
+                : fr?.outcome === "manager-unavailable"
+                    ? `⚠️  REM nightly scheduler installed but the service manager is unreachable — cannot verify the first run`
+                    : fr?.outcome === "start-failed"
+                        ? `⚠️  REM nightly scheduler installed but the first run could not be started`
+                        : `⚠️  REM nightly scheduler installed but the first run was never verified`;
+        const lines = [
+            headline,
+            `   Schedule:    ${scheduleTime} local time`,
+            `   Scheduler:   ${r.schedulerPath}`,
+            `   Shim:        ${r.shimPath}`,
+            `   Agent:       ${agentId}`,
+            `   Flair URL:   ${flairUrl}`,
+        ];
+        if (r.loadResult)
+            lines.push(`   Load:        ${r.loadCommand.join(" ")} → ok`);
+        if (fr) {
+            lines.push(`   First run:   ${fr.detail}`);
+            if (fr.stderrTail) {
+                lines.push(`   Log tail (${fr.logPath}):`);
+                for (const l of fr.stderrTail.split("\n"))
+                    lines.push(`     ${l}`);
+            }
+            else if (fr.logEmpty) {
+                lines.push(`   Log file ${fr.logPath} exists but is EMPTY — the run died before writing anything.`);
+            }
+            else {
+                lines.push(`   No log file at ${fr.logPath}.`);
+            }
+        }
+        lines.push("");
+        if (fr?.outcome === "timeout") {
+            lines.push(`   The run may legitimately still be going (a REM cycle can be slow). Check the log above and`);
+            lines.push(`   \`flair rem nightly status\`; no cycle has been CONFIRMED to work yet.`);
+        }
+        else if (fr?.outcome === "manager-unavailable") {
+            lines.push(`   The scheduler files are installed, but launchctl/systemctl could not be consulted, so whether`);
+            lines.push(`   the nightly cycle runs is UNKNOWN. Fix the service manager for this session, then re-run \`flair rem nightly enable\`.`);
+        }
+        else {
+            lines.push(`   No REM cycle has run. Fix the cause above, then re-run \`flair rem nightly enable\`.`);
+        }
+        lines.push("");
+        lines.push(`   Check anytime with: flair rem nightly status`);
+        return { lines, ok: false };
+    }
     const lines = [
         `✅ REM nightly scheduler enabled (${r.platform})`,
         `   Schedule:    ${scheduleTime} local time`,
@@ -223,9 +285,9 @@ export function formatEnableReport(r, input) {
     if (r.loadResult) {
         lines.push(`   Load:        ${r.loadCommand.join(" ")} → ok`);
     }
+    lines.push(`   First run:   completed through the service manager, exit 0`);
     lines.push("");
-    lines.push(`Tip: run \`flair rem nightly run-once --dry-run\` to verify the cycle works`);
-    lines.push(`     before the first scheduled fire. Disable with \`flair rem nightly disable\`.`);
+    lines.push(`Disable with \`flair rem nightly disable\`.`);
     return { lines, ok: true };
 }
 /**
@@ -268,9 +330,29 @@ export function formatStatusReport(s) {
 export function enableScheduler(opts) {
     const plat = detectPlatform(opts.platformOverride);
     const flairBin = opts.flairBin ?? process.argv[1] ?? "flair";
+    const nodeBin = resolveNodeBin(opts.nodeBin);
     const shimPath = opts.shimPathOverride ?? SHIM_PATH_DEFAULT;
     const templateRoot = opts.templateRootOverride ?? defaultTemplateRoot();
-    const subs = buildSubstitutions(opts, shimPath, flairBin);
+    const subs = buildSubstitutions(opts, shimPath, flairBin, nodeBin);
+    // 0. Create the log directory the unit files point stdout/stderr at.
+    // Nothing else ever creates it — launchd kills a job whose StandardOutPath
+    // directory is missing (spawn error 209) and systemd fails the unit (#1231).
+    //
+    // Mode 0700 is load-bearing, NOT cosmetic: REM's nightly log carries
+    // distillation CANDIDATE CONTENT — actual memory text, not just counts.
+    // Relaxing it to 0755 (e.g. "for shared debugging") would expose memory
+    // content to every local user.
+    const logsDir = resolve(subs.HOME, ".flair", "logs");
+    try {
+        mkdirSync(logsDir, { recursive: true, mode: 0o700 });
+    }
+    catch (err) {
+        throw new Error(`could not create the scheduler log directory ${logsDir}: ${err?.message ?? err}. ` +
+            `The service manager writes the job's stdout/stderr there; without it the first run dies ` +
+            `before producing any output. Fix whatever blocks creating that directory, then re-run ` +
+            `\`flair rem nightly enable\`.`);
+    }
+    const stderrLogPath = resolve(logsDir, "rem-nightly.stderr.log");
     // 1. Deploy the shim (always — both platforms invoke it).
     const shimContents = renderTemplate(readTemplate(templateRoot, "bin/flair-rem-nightly.sh.tmpl"), subs);
     writeFileWithDir(shimPath, shimContents, 0o700);
@@ -282,12 +364,26 @@ export function enableScheduler(opts) {
         writeFileWithDir(plistPath, plistContents, 0o600);
         const loadCommand = ["launchctl", "bootstrap", `gui/${process.getuid?.() ?? ""}`, plistPath];
         let loadResult;
+        let firstRun;
         if (!opts.skipLoad) {
             // Bootout first in case a prior install left the job loaded.
             spawnReport(["launchctl", "bootout", `gui/${process.getuid?.() ?? ""}`, plistPath]);
             loadResult = spawnReport(loadCommand);
+            if (loadResult.code === 0) {
+                // Ordering gate (#1231): verify the first run ONLY after the load
+                // exited 0. A load failure is its own failure mode with its own
+                // remedy — kickstarting on top of it would blur which actor failed.
+                firstRun = verifyFirstRun({
+                    plat,
+                    darwinTarget: `gui/${process.getuid?.() ?? ""}/${LAUNCHD_LABEL}`,
+                    stderrLogPath,
+                });
+            }
         }
-        return { platform: plat, shimPath, schedulerPath: plistPath, loadCommand, loadResult };
+        return {
+            platform: plat, shimPath, schedulerPath: plistPath, loadCommand, loadResult,
+            firstRunVerified: firstRun?.verified === true, firstRun,
+        };
     }
     // Linux: systemd user units.
     const timerPath = opts.systemdTimerOverride ?? SYSTEMD_TIMER_PATH;
@@ -296,13 +392,23 @@ 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) {
         spawnReport(["systemctl", "--user", "daemon-reload"]);
         loadResult = spawnReport(loadCommand);
+        if (loadResult.code === 0) {
+            // 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: SYSTEMD_SERVICE_UNIT, stderrLogPath });
+        }
     }
-    return { platform: plat, shimPath, schedulerPath: timerPath, loadCommand, loadResult };
+    return {
+        platform: plat, shimPath, schedulerPath: timerPath, loadCommand, loadResult,
+        firstRunVerified: firstRun?.verified === true, firstRun,
+    };
 }
 /**
  * Removes the scheduler entry. Audit log + snapshots are preserved.
@@ -332,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,
         };
     }
 }