@tpsdev-ai/flair 0.53.0 → 0.54.2

package/dist/lib/ops-api-bind.js

@@ -0,0 +1,115 @@
+/**
+ * ops-api-bind.ts — one decision for "is the Harper ops API bound to all
+ * interfaces?", shared by `flair doctor` and `flair status` (flair#670,
+ * unified in flair#852).
+ *
+ * The Harper ops API used to bind all interfaces unconditionally. `flair init`
+ * now defaults it to loopback + the domain socket, with an escape hatch
+ * (`--ops-bind` / `FLAIR_OPS_BIND`) for deployments that genuinely need remote
+ * ops access (flair#670). That narrowing is only useful if every health surface
+ * agrees on what the running install actually bound, and it is what doctor
+ * reads out of Harper's own config. The predicate is an allow-list: ONLY a
+ * loopback host narrows the bind. A bare numeric port, a wildcard host
+ * (`0.0.0.0:19925`, `[::]:19925`, …), an empty/unspecified host and an
+ * unparseable value are all reported as exposed — a `host:port` string is not
+ * evidence of narrowing unless the host is actually loopback.
+ *
+ * That allow-list is the flair#852 wildcard blind spot. The detector originally
+ * treated ANY `host:port` as narrowed, so `flair init --ops-bind 0.0.0.0`
+ * persisted `0.0.0.0:19925` and both `flair status` and `flair doctor` printed
+ * green while the ops API was reachable off-box.
+ *
+ * flair#852 was the two surfaces disagreeing. `flair doctor` flagged the bare
+ * port while `flair status` printed "✓ all checks passing" — a security-relevant
+ * exposure visible to one command and invisible to the other, so users shipped
+ * with the ops API reachable off-box. The fix is structural: the decision lives
+ * HERE, both commands call it, and status folds the finding into the same
+ * warning verdict that drives its green line.
+ *
+ * Pure: parsing Harper's config is the caller's job (doctor/status both read it
+ * with `readHarperConfig`); this module only decides.
+ */
+/**
+ * Hosts that genuinely narrow the ops-API bind to loopback. This is an
+ * allow-list on purpose: ANYTHING not in it — a wildcard (`0.0.0.0`, `::`,
+ * `[::]`, `0:0:0:0:0:0:0:0`), an explicit routable host, an empty/unspecified
+ * host, or a value we cannot parse — is reported as exposed. The cost of a
+ * missed exposure (a user ships an ops API reachable off-box) is worse than the
+ * cost of warning about a bind we did not recognise.
+ */
+const LOOPBACK_HOSTS = new Set(["127.0.0.1", "localhost", "::1"]);
+/**
+ * Best-effort host half of a persisted `operationsApi.network.port` value.
+ * Returns null when the value declares no host (a bare port) or the host is
+ * unparseable; the caller reports both as exposed.
+ *
+ * Handles the forms flair and Harper write:
+ *   - `127.0.0.1:19925`  → `127.0.0.1`
+ *   - `[::1]:19925`      → `::1`   (bracketed IPv6, port stripped)
+ *   - `[::]:19925`       → `::`
+ *   - `::1:19925`        → `::1`   (bare IPv6 with a trailing numeric port)
+ *   - `::`               → `::`    (bare wildcard, nothing to strip)
+ *   - `0:0:0:0:0:0:0:0`  → `0:0:0:0:0:0:0` (still not loopback — flagged)
+ *
+ * Splits on the LAST colon so an IPv6 literal keeps its port, matching
+ * `harperPortValue`. A trailing all-digit segment is treated as the port; a
+ * bare IPv6 like `::` has no trailing port, so the whole value is the host.
+ */
+function parseBindHost(str) {
+    if (str.startsWith("[")) {
+        const close = str.indexOf("]");
+        if (close === -1)
+            return null; // malformed bracket form — unparseable
+        return str.slice(1, close);
+    }
+    const lastColon = str.lastIndexOf(":");
+    if (lastColon === -1)
+        return null; // bare port — no host to narrow on
+    const tail = str.slice(lastColon + 1);
+    return /^\d+$/.test(tail) ? str.slice(0, lastColon) : str;
+}
+/**
+ * Decide whether a persisted `operationsApi.network.port` value (read back from
+ * harper-config.yaml) indicates an ops-API bind reachable off-box.
+ *
+ * A bare port number/numeric string is Harper's all-interfaces default (the
+ * pre-flair#670 behavior, or an install that predates the fix and has not been
+ * re-`init`ed). A `host:port` string narrows the bind ONLY when the host is
+ * loopback — a wildcard (`0.0.0.0:19925`, `[::]:19925`, `::19925`) is still
+ * all-interfaces, and is flagged (flair#852). Empty/unspecified and unparseable
+ * values are flagged too.
+ */
+export function detectOpsApiAllInterfacesBind(portValue) {
+    if (portValue === undefined || portValue === null)
+        return { allInterfaces: false, boundHost: null };
+    const str = String(portValue).trim();
+    if (str === "")
+        return { allInterfaces: false, boundHost: null };
+    const host = parseBindHost(str);
+    if (host !== null && LOOPBACK_HOSTS.has(host.toLowerCase())) {
+        return { allInterfaces: false, boundHost: host };
+    }
+    return { allInterfaces: true, boundHost: null };
+}
+const OPS_API_BIND_REMEDY = "Single-host installs don't need this reachable off-box. Fix: flair init && flair restart " +
+    "(rebinds to loopback + domain socket; re-init reuses your existing admin password, so this is " +
+    "safe on a running install — pass --ops-bind for deliberate remote admin)";
+/**
+ * The ops-API bind finding for a parsed harper-config, or null when the config
+ * declares no ops port (nothing to report). This is the single source of truth
+ * `flair doctor` and `flair status` both call, so they cannot disagree about
+ * the same instance.
+ */
+export function opsApiBindFinding(harperConfig) {
+    const portValue = harperConfig?.operationsApi?.network?.port;
+    if (portValue === undefined || portValue === null || String(portValue).trim() === "")
+        return null;
+    const { allInterfaces, boundHost } = detectOpsApiAllInterfacesBind(portValue);
+    return {
+        allInterfaces,
+        portValue,
+        boundHost,
+        message: `Ops API bound to all interfaces (${String(portValue)})`,
+        remedy: OPS_API_BIND_REMEDY,
+    };
+}

package/dist/lib/owned-pins.js

@@ -0,0 +1,219 @@
+/**
+ * owned-pins.ts — flair#1485
+ *
+ * The single catalogue of files `flair init` / `flair hook install` write a
+ * pinned `@tpsdev-ai/flair-mcp@<version>` into. `flair upgrade` refreshes
+ * every entry that is already wired; `flair doctor` reads the same list to
+ * decide whether a pin is current.
+ *
+ * Two kinds:
+ *   mcp-client         — ALL_CLIENTS kind:"mcp" config paths
+ *   session-start-hook — SUPPORTED_HARNESSES hook settings paths
+ *
+ * Adding a client to ALL_CLIENTS or a harness to SUPPORTED_HARNESSES adds
+ * it here automatically — no second list to forget on the next upgrade.
+ */
+import { existsSync, readFileSync } from "node:fs";
+import { ALL_CLIENTS, clientConfigPath, } from "../install/clients.js";
+import { checkSessionStartHook, extractFlairMcpPin, isFlairHookCommand, readClientMcpBlock, } from "../doctor-client.js";
+import { hookInstallHint, hookSettingsPath, repinSessionStartHook, SUPPORTED_HARNESSES, } from "../hook-install.js";
+import { flairCliVersion, isResolvedVersion } from "./mcp-spec.js";
+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 displayHomePath(homeDir, path) {
+    if (path.startsWith(homeDir))
+        return "~" + path.slice(homeDir.length);
+    return path;
+}
+/**
+ * Every file Flair pins. Order: MCP clients (registry order), then hooks
+ * (harness registry order). Upgrade and doctor both iterate this.
+ */
+export function listOwnedPinTargets(homeDir) {
+    return withHome(homeDir, () => {
+        const targets = [];
+        for (const client of ALL_CLIENTS) {
+            if (client.kind !== "mcp")
+                continue;
+            const path = clientConfigPath(client.id);
+            targets.push({
+                kind: "mcp-client",
+                id: client.id,
+                path,
+                displayPath: displayHomePath(homeDir, path),
+            });
+        }
+        for (const harness of SUPPORTED_HARNESSES) {
+            const path = hookSettingsPath(homeDir, harness);
+            targets.push({
+                kind: "session-start-hook",
+                id: harness,
+                path,
+                displayPath: displayHomePath(homeDir, path),
+            });
+        }
+        return targets;
+    });
+}
+function readFileText(path) {
+    try {
+        if (!existsSync(path))
+            return null;
+        return readFileSync(path, "utf-8");
+    }
+    catch {
+        return null;
+    }
+}
+export function readOwnedPin(target, homeDir) {
+    if (target.kind === "session-start-hook") {
+        const hook = checkSessionStartHook(homeDir, target.path);
+        const present = !!(hook.present && hook.command && isFlairHookCommand(hook.command));
+        return {
+            target,
+            present,
+            pin: present ? extractFlairMcpPin(hook.command ?? "") : null,
+        };
+    }
+    const block = readClientMcpBlock(target.id, homeDir);
+    const text = readFileText(target.path) ?? "";
+    return {
+        target,
+        present: block.present,
+        pin: block.present ? extractFlairMcpPin(text) : null,
+    };
+}
+export function readOwnedPins(homeDir) {
+    return listOwnedPinTargets(homeDir).map((t) => readOwnedPin(t, homeDir));
+}
+/**
+ * Wired pins whose concrete version is not the installed CLI version.
+ * Unpinned / absent entries are not stale — they are a different check.
+ */
+export function staleOwnedPins(homeDir, expectedVersion = flairCliVersion()) {
+    if (!isResolvedVersion(expectedVersion))
+        return [];
+    return readOwnedPins(homeDir).filter((r) => r.present && r.pin !== null && r.pin !== expectedVersion);
+}
+export function staleSessionStartHookPins(homeDir, expectedVersion = flairCliVersion()) {
+    return staleOwnedPins(homeDir, expectedVersion).filter((r) => r.target.kind === "session-start-hook");
+}
+export function staleMcpClientPins(homeDir, expectedVersion = flairCliVersion()) {
+    return staleOwnedPins(homeDir, expectedVersion).filter((r) => r.target.kind === "mcp-client");
+}
+/**
+ * What `flair upgrade` prints from a refresh result.
+ *
+ * A failed `client.wire` is `action: "skip"` + `ok: false` (same shape as a
+ * fail-closed hook re-pin). Filtering on `action !== "skip"` alone dropped
+ * that failure, left the pin stale, and printed nothing (Bugbot on #1485).
+ * Failures always surface. MCP no-ops/updates still print; hook no-ops stay quiet.
+ */
+export function ownedPinRefreshShouldReport(r) {
+    if (!r.ok)
+        return true;
+    if (r.target.kind === "mcp-client")
+        return r.action !== "skip";
+    return r.action === "update";
+}
+export function staleHookRemedy(readings) {
+    const harnesses = readings
+        .filter((r) => r.target.kind === "session-start-hook")
+        .map((r) => r.target.id);
+    if (harnesses.length === 0)
+        return "flair hook install";
+    return [...new Set(harnesses)].map((h) => hookInstallHint(h)).join(" ; ");
+}
+/**
+ * Refresh every already-wired owned pin to the running CLI's spec.
+ *
+ * MCP client pins need `agentId` (the wire functions rewrite the env block).
+ * SessionStart hooks do not — `repinSessionStartHook` reads the agent from
+ * the existing command. A missing agentId therefore skips MCP only; it must
+ * not skip hooks (that was the early-return hole in the inline upgrade path).
+ *
+ * NEVER adds a hook or wires a new client.
+ */
+export function refreshOwnedPins(opts) {
+    const { homeDir } = opts;
+    const flairUrl = opts.flairUrl ?? "http://127.0.0.1:9926";
+    const agentId = opts.agentId ?? null;
+    const targets = listOwnedPinTargets(homeDir);
+    const results = [];
+    return withHome(homeDir, () => {
+        for (const target of targets) {
+            if (target.kind === "session-start-hook") {
+                const harness = target.id;
+                const repin = repinSessionStartHook(homeDir, harness);
+                results.push({
+                    target,
+                    action: repin.action,
+                    ok: repin.ok,
+                    message: repin.message,
+                });
+                continue;
+            }
+            const block = readClientMcpBlock(target.id, homeDir);
+            if (!block.present) {
+                results.push({
+                    target,
+                    action: "skip",
+                    ok: true,
+                    message: `${target.id}: not wired — skip`,
+                });
+                continue;
+            }
+            if (!agentId) {
+                results.push({
+                    target,
+                    action: "skip",
+                    ok: true,
+                    message: `${target.id}: no agent id — skip MCP pin refresh`,
+                });
+                continue;
+            }
+            const client = ALL_CLIENTS.find((c) => c.id === target.id);
+            if (!client) {
+                results.push({
+                    target,
+                    action: "skip",
+                    ok: true,
+                    message: `${target.id}: not in client registry — skip`,
+                });
+                continue;
+            }
+            const env = {
+                FLAIR_AGENT_ID: agentId,
+                FLAIR_URL: flairUrl,
+                FLAIR_CLIENT: target.id,
+            };
+            const before = extractFlairMcpPin(readFileText(target.path) ?? "");
+            const wired = client.wire(env);
+            const after = extractFlairMcpPin(readFileText(target.path) ?? "");
+            // Failed write stays skip+ok:false (fail-closed, like hook re-pin).
+            // ownedPinRefreshShouldReport treats !ok as printable — do not recode
+            // this as a quiet skip.
+            const action = !wired.ok ? "skip"
+                : before !== after ? "update"
+                    : "noop";
+            results.push({
+                target,
+                action,
+                ok: wired.ok,
+                message: wired.message,
+            });
+        }
+        return results;
+    });
+}

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 };
+    }
+}