@tpsdev-ai/flair 0.52.0 → 0.54.1

package/dist/lib/uninstall-purge.js

@@ -0,0 +1,218 @@
+/**
+ * uninstall-purge.ts — flair#853
+ *
+ * `flair uninstall --purge` used to delete only `~/.flair/data` and
+ * `~/.flair/keys`, then print "Flair fully purged". That left the admin
+ * password, backups/logs/upgrade-snapshots, the REM nightly shim, client
+ * MCP/hook wiring, and the systemd/launchd scheduler units — a secret and
+ * a job that can resurrect on reinstall.
+ *
+ * This module is the purge body. The CLI stops the Harper service, then
+ * calls `purgeFlairInstall`. Docs say purge removes everything including
+ * data and keys; this does that, plus secrets, schedulers, and client
+ * wiring. The npm package is an intentional leftover: this CLI cannot
+ * uninstall itself. The report always names leftovers instead of claiming
+ * "fully purged" when anything remains.
+ */
+import { existsSync, rmSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { ALL_CLIENTS } from "../install/clients.js";
+import { uninstallContinuityHooks, uninstallHook, harnessSupportsContinuity, hookBackupPath, hookSettingsPath, SUPPORTED_HARNESSES, } from "../hook-install.js";
+import { disableScheduler as disableRemScheduler, LAUNCHD_LABEL as REM_LAUNCHD_LABEL, SYSTEMD_SERVICE_UNIT as REM_SYSTEMD_SERVICE, SYSTEMD_TIMER_UNIT as REM_SYSTEMD_TIMER, } from "../rem/scheduler.js";
+import { disableScheduler as disableFederationScheduler, LAUNCHD_LABEL as FED_LAUNCHD_LABEL, SYSTEMD_SERVICE_UNIT as FED_SYSTEMD_SERVICE, SYSTEMD_TIMER_UNIT as FED_SYSTEMD_TIMER, } from "../federation/scheduler.js";
+/** The published CLI package. Named here so the leftover line cannot drift
+ *  from the remedy command. */
+export const FLAIR_NPM_PACKAGE = "@tpsdev-ai/flair";
+function resolveHome(homeDir) {
+    return homeDir ?? process.env.HOME ?? process.env.USERPROFILE ?? homedir();
+}
+function withHome(homeDir, fn) {
+    const prev = process.env.HOME;
+    process.env.HOME = homeDir;
+    try {
+        return fn();
+    }
+    finally {
+        if (prev === undefined)
+            delete process.env.HOME;
+        else
+            process.env.HOME = prev;
+    }
+}
+function displayUnderHome(homeDir, absPath) {
+    if (absPath.startsWith(homeDir))
+        return "~" + absPath.slice(homeDir.length);
+    return absPath;
+}
+function rmPath(absPath, removed, leftovers, display) {
+    if (!existsSync(absPath))
+        return;
+    try {
+        rmSync(absPath, { recursive: true, force: true });
+        removed.push(display);
+    }
+    catch (err) {
+        const reason = err instanceof Error ? err.message : String(err);
+        leftovers.push({
+            path: display,
+            kind: "failed",
+            reason: `could not remove: ${reason}`,
+        });
+    }
+}
+function schedulerPaths(homeDir, spec) {
+    return [
+        join(homeDir, ".flair", "bin", spec.shimName),
+        join(homeDir, "Library", "LaunchAgents", `${spec.launchdLabel}.plist`),
+        join(homeDir, ".config", "systemd", "user", spec.systemdTimer),
+        join(homeDir, ".config", "systemd", "user", spec.systemdService),
+    ];
+}
+function disableAndSweepScheduler(homeDir, skipUnload, kind, removed, leftovers) {
+    const spec = kind === "rem"
+        ? {
+            shimName: "flair-rem-nightly",
+            launchdLabel: REM_LAUNCHD_LABEL,
+            systemdTimer: REM_SYSTEMD_TIMER,
+            systemdService: REM_SYSTEMD_SERVICE,
+            disable: disableRemScheduler,
+        }
+        : {
+            shimName: "flair-federation-sync",
+            launchdLabel: FED_LAUNCHD_LABEL,
+            systemdTimer: FED_SYSTEMD_TIMER,
+            systemdService: FED_SYSTEMD_SERVICE,
+            disable: disableFederationScheduler,
+        };
+    const paths = schedulerPaths(homeDir, spec);
+    try {
+        spec.disable({
+            skipUnload,
+            removeShim: true,
+            shimPathOverride: paths[0],
+            launchdPlistOverride: paths[1],
+            systemdTimerOverride: paths[2],
+            systemdServiceOverride: paths[3],
+        });
+    }
+    catch {
+        // File sweep below still runs — unload failure must not keep units on disk.
+    }
+    for (const abs of paths) {
+        rmPath(abs, removed, leftovers, displayUnderHome(homeDir, abs));
+    }
+}
+/**
+ * `uninstallHook` / `uninstallContinuityHooks` copy the settings file to a
+ * sibling `.bak` whenever it exists — including on a no-op. Purge must not
+ * leave that copy (or a pre-existing `.bak` it just overwrote). flair#853
+ * Bugbot: only deleting the bak after an actual remove left
+ * `~/.claude/settings.json.bak` / `~/.codex/hooks.json.bak` behind.
+ */
+function sweepHookBackup(settingsPath, reportedBackup, homeDir, removed, leftovers) {
+    const candidates = new Set();
+    if (reportedBackup)
+        candidates.add(reportedBackup);
+    candidates.add(hookBackupPath(settingsPath));
+    for (const bak of candidates) {
+        rmPath(bak, removed, leftovers, displayUnderHome(homeDir, bak));
+    }
+}
+/**
+ * Remove Flair-owned state under `homeDir`: the `~/.flair` tree (data, keys,
+ * admin-pass, backups, logs, snapshots, shims), REM + federation scheduler
+ * units on both platforms, SessionStart/continuity hooks, and MCP/native
+ * client wiring. The npm package is listed as an intentional leftover
+ * unless `omitNpmLeftover` is set.
+ */
+export function purgeFlairInstall(opts = {}) {
+    const homeDir = resolveHome(opts.homeDir);
+    const skipUnload = !!opts.skipSchedulerUnload;
+    const removed = [];
+    const leftovers = [];
+    disableAndSweepScheduler(homeDir, skipUnload, "rem", removed, leftovers);
+    disableAndSweepScheduler(homeDir, skipUnload, "federation", removed, leftovers);
+    for (const harness of SUPPORTED_HARNESSES) {
+        const hook = uninstallHook({ homeDir, harness });
+        if (!hook.ok) {
+            leftovers.push({ path: hook.path, kind: "failed", reason: hook.message });
+        }
+        else if (hook.delta && hook.delta.action !== "noop") {
+            removed.push(displayUnderHome(homeDir, hook.path) + " (SessionStart hook)");
+        }
+        sweepHookBackup(hook.path, hook.backupPath, homeDir, removed, leftovers);
+        if (!harnessSupportsContinuity(harness))
+            continue;
+        const continuity = uninstallContinuityHooks({ homeDir, harness });
+        if (!continuity.ok) {
+            leftovers.push({ path: continuity.path, kind: "failed", reason: continuity.message });
+        }
+        else if (continuity.actions && (continuity.actions.PostToolUse === "remove" || continuity.actions.Stop === "remove")) {
+            removed.push(displayUnderHome(homeDir, continuity.path) + " (continuity hooks)");
+        }
+        sweepHookBackup(continuity.path, continuity.backupPath, homeDir, removed, leftovers);
+    }
+    // Pre-existing sibling backups (or a harness we skipped) must not survive.
+    for (const harness of SUPPORTED_HARNESSES) {
+        sweepHookBackup(hookSettingsPath(homeDir, harness), null, homeDir, removed, leftovers);
+    }
+    const unwireResults = withHome(homeDir, () => ALL_CLIENTS.map((c) => c.unwire()));
+    for (const u of unwireResults) {
+        if (!u.ok) {
+            leftovers.push({ path: u.message, kind: "failed", reason: u.message });
+        }
+        else if (u.removed) {
+            removed.push(u.message);
+        }
+    }
+    const flairDir = join(homeDir, ".flair");
+    rmPath(flairDir, removed, leftovers, "~/.flair");
+    if (existsSync(flairDir)) {
+        leftovers.push({
+            path: "~/.flair",
+            kind: "failed",
+            reason: "directory still present after purge",
+        });
+    }
+    if (!opts.omitNpmLeftover) {
+        leftovers.push({
+            path: FLAIR_NPM_PACKAGE,
+            kind: "intentional",
+            reason: "this CLI cannot uninstall itself",
+            remedy: `npm uninstall -g ${FLAIR_NPM_PACKAGE}`,
+        });
+    }
+    return { removed, leftovers };
+}
+export function formatPurgeReport(result) {
+    const lines = [];
+    for (const item of result.removed) {
+        lines.push(`✅ Removed: ${item}`);
+    }
+    const failed = result.leftovers.filter((l) => l.kind === "failed");
+    const intentional = result.leftovers.filter((l) => l.kind === "intentional");
+    for (const item of failed) {
+        lines.push(`⚠️  Left (failed): ${item.path} — ${item.reason}`);
+    }
+    if (failed.length === 0 && intentional.length === 0) {
+        lines.push("");
+        lines.push("🗑️  Flair fully purged");
+        return { lines, claimedFullyPurged: true };
+    }
+    lines.push("");
+    lines.push("🗑️  Flair purged (data, keys, secrets, schedulers, and client wiring)");
+    if (intentional.length > 0) {
+        lines.push("");
+        lines.push("Intentionally left:");
+        for (const item of intentional) {
+            lines.push(`  • ${item.path} — ${item.reason}`);
+            if (item.remedy)
+                lines.push(`    Remove with: ${item.remedy}`);
+        }
+    }
+    return { lines, claimedFullyPurged: false };
+}
+export function purgeHadFailures(result) {
+    return result.leftovers.some((l) => l.kind === "failed");
+}

package/dist/rem/restore.js

@@ -41,14 +41,12 @@ function asArray(raw) {
 function soulWrite(opts) {
     return opts.soulApiCall ?? opts.apiCall;
 }
-async function listAgentCandidates(apiCall, agentId) {
-    return asArray(await apiCall("POST", "/MemoryCandidate/search_by_conditions", {
-        operator: "and",
-        conditions: [
-            { search_attribute: "agentId", search_type: "equals", search_value: agentId },
-        ],
-        get_attributes: ["id", "claim"],
-    }));
+async function listAgentCandidates(opsSearch, agentId) {
+    if (!opsSearch)
+        return [];
+    return asArray(await opsSearch("MemoryCandidate", [
+        { search_attribute: "agentId", search_type: "equals", search_value: agentId },
+    ], ["id", "claim"]));
 }
 function parseJsonlSafe(text) {
     if (!text.trim())
@@ -142,7 +140,7 @@ export async function applySnapshot(opts) {
         try {
             const currentMem = asArray(await opts.apiCall("GET", `/Memory?agentId=${encodeURIComponent(opts.agentId)}`));
             const currentSouls = asArray(await opts.apiCall("GET", `/Soul?agentId=${encodeURIComponent(opts.agentId)}`));
-            const currentCandidates = await listAgentCandidates(opts.apiCall, opts.agentId);
+            const currentCandidates = await listAgentCandidates(opts.opsSearch, opts.agentId);
             result.deleted.memories = currentMem.length;
             result.deleted.souls = currentSouls.length;
             result.deleted.candidates = currentCandidates.length;
@@ -186,7 +184,7 @@ export async function applySnapshot(opts) {
     // so a leftover row 403s Soul PUT after operator auth succeeds.
     let currentCandidates = [];
     try {
-        currentCandidates = await listAgentCandidates(opts.apiCall, opts.agentId);
+        currentCandidates = await listAgentCandidates(opts.opsSearch, opts.agentId);
     }
     catch (err) {
         errors.push(`fetch-candidates: ${err?.message ?? String(err)}`);

package/dist/resources/AgentReadPosition.js

@@ -0,0 +1,74 @@
+/**
+ * AgentReadPosition.ts — HTTP surface for the per-agent read-position primitive.
+ *
+ * GET  /AgentReadPosition/{agentId}?stream=org-event
+ * POST /AgentReadPosition/{agentId}  { stream, position }
+ *
+ * Owner-scoped: an agent reads/advances only its own watermark. Admins and
+ * internal calls may act on any agent. The table itself is not @export.
+ */
+import { Resource } from "harper";
+import { allowVerified, resolveAgentAuth } from "./agent-auth.js";
+import { ORG_EVENT_STREAM } from "./agent-read-position-lib.js";
+import { advanceReadPosition, defaultReadPositionTable, getReadPosition, } from "./agent-read-position.js";
+function pathAgentId(pathInfo, resource) {
+    return ((typeof pathInfo === "object" && pathInfo !== null ? pathInfo.id : null) ??
+        (typeof pathInfo === "string" ? pathInfo : null) ??
+        resource?.getId?.() ??
+        null);
+}
+function queryValue(pathInfo, name) {
+    if (typeof pathInfo !== "object" || pathInfo === null)
+        return null;
+    return pathInfo.conditions?.find((c) => c.attribute === name)?.value ?? null;
+}
+function denyOwner() {
+    return new Response(JSON.stringify({ error: "forbidden: can only read or advance your own watermark" }), { status: 403, headers: { "Content-Type": "application/json" } });
+}
+function ownerDenied(auth, agentId) {
+    if (auth.kind === "anonymous")
+        return true;
+    if (auth.kind === "agent" && !auth.isAdmin && auth.agentId !== agentId)
+        return true;
+    return false;
+}
+export class AgentReadPosition extends Resource {
+    async allowRead() {
+        return allowVerified(this.getContext?.());
+    }
+    async allowCreate() {
+        return allowVerified(this.getContext?.());
+    }
+    async get(pathInfo) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        const agentId = pathAgentId(pathInfo, this);
+        if (!agentId) {
+            return new Response(JSON.stringify({ error: "agentId required in path: GET /AgentReadPosition/{agentId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        if (ownerDenied(auth, agentId))
+            return denyOwner();
+        const stream = queryValue(pathInfo, "stream") || ORG_EVENT_STREAM;
+        const ctx = this.getContext?.();
+        const position = await getReadPosition(defaultReadPositionTable(), agentId, stream, ctx);
+        return { agentId, stream, position };
+    }
+    async post(content, pathInfo) {
+        const auth = await resolveAgentAuth(this.getContext?.());
+        const agentId = pathAgentId(pathInfo, this) ??
+            (content && typeof content === "object" ? content.agentId : null) ??
+            null;
+        if (!agentId) {
+            return new Response(JSON.stringify({ error: "agentId required in path: POST /AgentReadPosition/{agentId}" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        if (ownerDenied(auth, agentId))
+            return denyOwner();
+        const stream = (content && typeof content === "object" && content.stream) || ORG_EVENT_STREAM;
+        const position = content && typeof content === "object" ? String(content.position ?? "") : "";
+        if (!position) {
+            return new Response(JSON.stringify({ error: "position required to advance watermark" }), { status: 400, headers: { "Content-Type": "application/json" } });
+        }
+        const ctx = this.getContext?.();
+        const result = await advanceReadPosition(defaultReadPositionTable(), agentId, stream, position, ctx);
+        return { agentId, stream, ...result };
+    }
+}

package/dist/resources/Federation.js

@@ -109,7 +109,9 @@ export function noteFederationMergedMemory(recordTable, mergedData) {
  * AdminInstance.ts/AdminDashboard.ts: this is an admin-view endpoint (peers
  * never call it during pairing — FederationPair.post() reads the Instance
  * table directly server-side to hand a peer our identity; this HTTP GET is
- * CLI tooling only).
+ * CLI tooling only). The spoke pair CLI must not GET this path to fill a
+ * missing pair publicKey (flair#822): allowRead is allowAdmin, and get()
+ * find-or-creates an Instance (that would invent a hub row; #839).
  */
 export class FederationInstance extends Resource {
     async allowRead() {
@@ -325,7 +327,11 @@ export class FederationPair extends Resource {
                 console.warn(`[federation] drop_user failed: ${err?.message} — cleanup sweep will retry`);
             }
         }
-        // Return our own identity for the peer to record
+        // Return our own identity for the peer to record. Already
+        // `{ id, publicKey, role }` when an Instance row exists (flair#213).
+        // `instance: null` means the hub has no FederationInstance — that is
+        // #839, not a pair-response-shape bug. The spoke must ERROR, never
+        // store publicKey:"" (flair#822).
         let ourInstance = null;
         try {
             for await (const i of databases.flair.Instance.search()) {

package/dist/resources/Memory.js

@@ -269,9 +269,10 @@ async function runDedupGate(ctx, content) {
     // miss a near-duplicate during that window. Bounded (the re-embed pass is
     // batched and finishes in minutes), self-healing once the pass completes,
     // and a missed dedup is a duplicate row, not data loss — quality, not
-    // correctness. Stage 1 (this PR) doesn't trigger this at all: no re-embed
-    // runs, so there's no mixed-space window until stage 2's separate,
-    // deliberate ops step.
+    // correctness. flair#1073: if that window lasts days (boot cycle marked
+    // embedding-stamp complete without converging), /HealthDetail names the
+    // outstanding migration and that duplicate detection is inactive — do
+    // not treat a long-lived split as this documented transient.
     let embedding = Array.isArray(content.embedding) ? content.embedding : null;
     if (!embedding) {
         try {

package/dist/resources/MemoryBootstrap.js

@@ -19,6 +19,9 @@ import { hybridEnabled } from "./bm25.js";
 import { buildTrustBlock } from "./trust-block.js";
 import { bestSemanticSimilarity, evaluateAbstention } from "./abstention.js";
 import { estimateTokens } from "./token-estimate.js";
+import { initialPosition, ORG_EVENT_STREAM } from "./agent-read-position-lib.js";
+import { defaultReadPositionTable, ensureReadPosition } from "./agent-read-position.js";
+import { catchupSeekTimestamp, isCatchupEligible } from "./org-event-catchup-lib.js";
 /**
  * POST /MemoryBootstrap
  *
@@ -188,11 +191,11 @@ function buildTrustEntry(m, section) {
         : undefined;
     return { id: m.id, section, ...block, ...(matchQualityNote ? { matchQualityNote } : {}) };
 }
-// flair#1199/#1206 — the default cap on how many org events bootstrap ships.
-// Overridable per-request via `maxEvents`. Event slots are scarce AND (as of
-// #1199) token-charged, so this bounds both the count and the spend; the shared
-// tokenBudget is the harder ceiling (an event that doesn't fit is skipped even
-// under the cap).
+// flair#1199/#1206 — the default DISPLAY cap on how many org events bootstrap
+// ships. Overridable per-request via `maxEvents`. This is no longer a silent
+// drop (flair#931): leftover events set eventsHasMore / eventsRemaining so the
+// caller pages /OrgEventCatchup. Event slots are scarce AND (as of #1199)
+// token-charged; the shared tokenBudget is the harder ceiling.
 const MAX_ORG_EVENTS = 10;
 // ─── Bootstrap scale fix (flair-bootstrap-scale-fix) tunables ───────────────
 //
@@ -440,6 +443,12 @@ export class BootstrapMemories extends Resource {
         // skipped events — never a gap derived from some larger tally, which
         // could imply the existence of rows the caller was not allowed to see.
         let eventsBudgetTruncated = 0;
+        // flair#931 — watermark path. Always present on the response so a
+        // display cap (maxEvents / budget) is never a silent drop: the agent
+        // pages /OrgEventCatchup until drained, then acks.
+        let eventWatermark = null;
+        let eventsHasMore = false;
+        let eventsRemaining = 0;
         const leanMemory = (m, section) => ({
             id: m.id,
             content: m.content,
@@ -1293,28 +1302,27 @@ export class BootstrapMemories extends Resource {
             // dependency — WorkspaceState/OrgEvent/Presence being briefly
             // unavailable must not break bootstrap's core memory context.
         }
-        // --- 5. Recent OrgEvents for this agent ---
+        // --- 5. OrgEvents for this agent (per-agent watermark, flair#931) ---
         try {
-            const eventSince = data?.lastBootAt
-                ? new Date(data.lastBootAt)
-                : new Date(Date.now() - 24 * 3600_000);
-            const eventSinceStr = eventSince.toISOString();
+            // Optional lastBootAt remains a createdAt floor (legacy / probe), never
+            // the primary cursor. Default path is the durable watermark: "now" on
+            // first seen (or FLAIR_CATCHUP_BACKFILL_MS), then position > watermark.
+            // The old 24h window + silent slice(0, 10) is retired as the primary path.
+            const sinceFloor = data?.lastBootAt ? new Date(data.lastBootAt).toISOString() : null;
+            eventWatermark = await ensureReadPosition(defaultReadPositionTable(), agentId, ORG_EVENT_STREAM, initialPosition(), ctx);
+            const seekTs = catchupSeekTimestamp(eventWatermark, sinceFloor);
             const eventResults = [];
-            // Seek the indexed lookback window before materializing events. Keep detail
+            // Seek the indexed floor before materializing events. Keep detail
             // for no-op suppression/dedup even when the response omits it. No limit here:
-            // expiry, targeting, dedup and budget admission must run before the cap.
+            // expiry, targeting, dedup and budget admission must run before the display cap.
             const recentEvents = withDetachedTxn(ctx, () => databases.flair.OrgEvent.search({
-                conditions: [{ attribute: "createdAt", comparator: "greater_than_equal", value: eventSinceStr }],
+                ...(seekTs
+                    ? { conditions: [{ attribute: "createdAt", comparator: "greater_than_equal", value: seekTs }] }
+                    : {}),
                 select: ["id", "kind", "summary", "detail", "targetIds", "createdAt", "expiresAt", "scope"],
             }));
             for await (const event of recentEvents) {
-                if (!event.createdAt || event.createdAt < eventSinceStr)
-                    continue;
-                if (event.expiresAt && new Date(event.expiresAt) < new Date())
-                    continue;
-                const targets = event.targetIds;
-                const isRelevant = !targets || targets.length === 0 || targets.includes(agentId);
-                if (!isRelevant)
+                if (!isCatchupEligible(event, { participantId: agentId, after: eventWatermark, since: sinceFloor }))
                     continue;
                 // flair#1200 — suppress zero-row no-op auto-heal migration events at
                 // render. On a healthy store every boot emits a "migration graph-heal
@@ -1365,8 +1373,10 @@ export class BootstrapMemories extends Resource {
             const dedupedEvents = [...eventBySignature.values()]
                 .sort((a, b) => (b.createdAt || "").localeCompare(a.createdAt || ""));
             for (const evt of dedupedEvents) {
-                if (sections.events.length >= eventCap)
-                    break;
+                if (sections.events.length >= eventCap) {
+                    eventsRemaining++;
+                    continue;
+                }
                 // The structured object a connector actually reads (flair#1206). Lean by
                 // default; `detail` (the verbose migration-internals/summary-restating
                 // JSON) only when explicitly requested. Optional fields are omitted when
@@ -1389,6 +1399,7 @@ export class BootstrapMemories extends Resource {
                 // can say so instead of claiming "empty by design" (#1182 contract).
                 if (cost > tokenBudget) {
                     eventsBudgetTruncated++;
+                    eventsRemaining++;
                     continue;
                 }
                 const elapsed = Date.now() - new Date(evt.createdAt).getTime();
@@ -1400,9 +1411,10 @@ export class BootstrapMemories extends Resource {
                 includedEvents.push(structured);
                 tokenBudget -= cost;
             }
+            eventsHasMore = eventsRemaining > 0;
         }
         catch {
-            // non-fatal: OrgEvent table may not exist yet
+            // non-fatal: OrgEvent / AgentReadPosition table may not exist yet
         }
         // flair#1207 — derive the own-memory counters from the unique-id sets so the
         // invariant memoriesIncluded + memoriesTruncated <= memoriesAvailable holds.
@@ -1615,8 +1627,9 @@ export class BootstrapMemories extends Resource {
         const eventsHint = includedEvents.length === 0
             ? (eventsBudgetTruncated > 0
                 ? `No org events fit the token budget: ${eventsBudgetTruncated} relevant event(s) cleared the `
-                    + "lookback window but were budget-truncated. Raise maxTokens to include them."
-                : "No org events in the lookback window were relevant to you (org-wide, or targeted at you) "
+                    + "watermark (or optional lastBootAt floor) but were budget-truncated. Raise maxTokens "
+                    + "or GET /OrgEventCatchup to page the rest."
+                : "No org events after your watermark were relevant to you (org-wide, or targeted at you) "
                     + "after zero-row no-op auto-heal filtering. This container is present-but-empty by design, not dropped.")
             : undefined;
         // teammateFindings: [] — name WHICH legitimate empty this is (no task → no
@@ -1657,6 +1670,9 @@ export class BootstrapMemories extends Resource {
             // delivered. Deduped (#1200) and targetIds-scoped (same set as the prose
             // "## Recent Org Events" lines), so count/charge/delivery all agree.
             events: includedEvents,
+            eventWatermark,
+            eventsHasMore,
+            eventsRemaining,
             ...(currentTaskHint ? { currentTaskHint } : {}),
             ...(predictedHint ? { predictedHint } : {}),
             // flair#1182 (0.44.11) — empty-container hints, present only when the

package/dist/resources/MemoryCandidate.js

@@ -83,12 +83,11 @@ export class MemoryCandidate extends databases.flair.MemoryCandidate {
         return memoryCandidateByIdReadGate.call(this, target, (t) => super.get(t));
     }
     /**
-     * Scope collection reads to the caller's own candidates. This is the
-     * handler `flair rem candidates` reaches via `POST
-     * /MemoryCandidate/search_by_conditions` (src/cli.ts) — the agentId
-     * condition is wrapped as the OUTERMOST `and` block (Relationship.ts's
-     * same "Security Critical" discipline) so a caller-supplied `operator:
-     * "or"` in the request body cannot boolean-inject past the owner scope.
+     * Scope collection reads to the caller's own candidates. Agent-facing
+     * collection reads (`GET /MemoryCandidate`) reach this handler — the agentId
+     * condition is wrapped as the OUTERMOST `and` block (Relationship.ts's same
+     * "Security Critical" discipline) so a caller-supplied `operator: "or"` in
+     * the query cannot boolean-inject past the owner scope.
      */
     async search(query) {
         const ctx = this.getContext?.();