#1 Persistent memory for AI coding agents based on real-world benchmarks
TypeScript agentmemoryagentsaiclaudeclaudecodecodexcopilotcursorgenaiharnesshermesmemoryompopenclawopencodepi
fix: release blockers for export, forget accounting and shutdown flush (#1449)
Rohit Ghumare63c54d9d4973
diff --git a/src/cli.ts b/src/cli.tsindex 2b9fbad6..7d4b72e9 100644--- a/src/cli.ts+++ b/src/cli.ts@@ -55,6 +55,8 @@ import {type ConnectManifest,type RemoveOptions,} from "./cli/remove-plan.js";+import { portFlagSuffix } from "./cli/ready-hint.js";+import { describeInstallFailure, iiiInstallShellCommand, iiiManualInstallCommand, III_INSTALL_SPAWN_TIMEOUT_MS } from "./cli/engine-install.js";import {dockerComposeArgs,dockerProjectName,@@ -71,6 +73,8 @@ import { runtimeMetadataPath } from "./runtime-paths.js";import { createStartupStderrCapture } from "./cli/startup-stderr.js";import {clearPersistedBuiltinConfig,+ engineFlushWaitMs,+ persistedBuiltinConfigDirs,renderEngineConfig,} from "./cli/engine-config.js";import { SHUTDOWN_HARD_EXIT_MS } from "./shutdown.js";@@ -1326,21 +1330,25 @@ async function runIiiInstaller(): Promise<{ ok: boolean; binPath: string | nullconst binDir = agentmemoryBinDir();const binPath = privateIiiPath();- const installCmd = [- `mkdir -p "${binDir}"`,- `curl -fsSL "${releaseUrl}" | tar -xz -C "${binDir}"`,- `chmod +x "${binPath}"`,- ].join(" && ");- const installerOk = runCommand(shBin, ["-c", installCmd], {- label: `Installing iii-engine v${IIPINNED_VERSION} (pinned)`,- optional: true,- });- if (!installerOk) {+ const label = `Installing iii-engine v${IIPINNED_VERSION} (pinned)`;+ const spinner = p.spinner();+ spinner.start(label);+ const result = spawnSync(+ shBin,+ ["-c", iiiInstallShellCommand(releaseUrl, binDir, binPath)],+ { stdio: "pipe", encoding: "utf-8", timeout: III_INSTALL_SPAWN_TIMEOUT_MS },+ );+ if (result.status !== 0) {+ spinner.stop(`${label} ${pc.red("✗")}`);p.log.warn(- `iii-engine installer failed. Fallbacks: Docker (\`docker pull iiidev/iii:${IIPINNED_VERSION}\`) or download manually from https://github.com/iii-hq/iii/releases/tag/iii%2Fv${IIPINNED_VERSION}.`,+ `iii-engine download failed: ${describeInstallFailure(result).slice(0, 300)}\n` ++ `Install it manually, then re-run agentmemory:\n` ++ ` ${iiiManualInstallCommand(releaseUrl, binDir, binPath)}\n` ++ `Or use Docker: docker pull iiidev/iii:${IIPINNED_VERSION}`,);return { ok: false, binPath: null };}+ spinner.stop(`${label} ${pc.green("✓")}`);return { ok: true, binPath };}@@ -1906,8 +1914,9 @@ function printReadyHint(): void {const engineUrl = `ws://${engineHost}:${getEnginePort()}`;const invocation = isInvokedViaNpx() ? "npx @agentmemory/agentmemory" : "agentmemory";const consolePort = defaultConsolePort(getConfiguredViewerPort());+ const portFlags = portFlagSuffix(getRestPort(), selectedInstance);- const consoleLine = `${c.label("iii console")} ${c.cmd(`${invocation} console`)} ${c.dim(`(serves on :${consolePort}; first run downloads the console next to the pinned iii)`)}`;+ const consoleLine = `${c.label("iii console")} ${c.cmd(`${invocation} console${portFlags}`)} ${c.dim(`(serves on :${consolePort}; first run downloads the console next to the pinned iii)`)}`;const lines = [`${c.label("REST API")} ${c.url(restUrl)}`,@@ -1926,7 +1935,7 @@ function printReadyHint(): void {// (unless they accepted the global-install prompt and the npm bin// dir was already on PATH in this shell), so we suggest the npx// form for them; everyone else gets the global form.- const demoCommand = `${invocation} demo`;+ const demoCommand = `${invocation} demo${portFlags}`;process.stdout.write(`\n${c.dim("Try:")} ${c.cmd(demoCommand)}\n`);}@@ -3269,6 +3278,29 @@ async function signalAndWait(// Shared worker-reap: SIGTERM with a grace window sized for the worker's// shutdown flush (index snapshots land via the engine, so the worker must// die before the engine does, with time to commit).+async function waitForEngineFlush(): Promise<void> {+ let stateBackend: "file" | "redis" = "file";+ try {+ stateBackend = getStateBackend();+ } catch {}+ const runtimePath = runtimeConfigPath(dataDirResolution.dataDir);+ const configTexts: string[] = [];+ for (const path of [+ ...persistedBuiltinConfigDirs(join(homedir(), ".agentmemory"), runtimePath).map((dir) => join(dir, "iii-state.yaml")),+ runtimePath,+ ]) {+ try {+ configTexts.push(readFileSync(path, "utf-8"));+ } catch {}+ }+ const waitMs = engineFlushWaitMs(stateBackend, configTexts);+ if (waitMs <= 0) return;+ const s = p.spinner();+ s.start(`Waiting ${(waitMs / 1000).toFixed(1)}s for iii-engine to write state to disk...`);+ await new Promise((r) => setTimeout(r, waitMs));+ s.stop("iii-engine state flush window passed");+}+async function stopWorkerPid(pid: number, graceMs: number): Promise<boolean> {const s = p.spinner();s.start(`Stopping agentmemory worker (pid ${pid})... [flushing state]`);@@ -3585,7 +3617,10 @@ async function runStop(): Promise<void> {// persists. Worker SIGTERM grace bumped 3s -> 5s to give a large// index a real chance to commit before the engine goes away.for (const pid of workerCandidates) {- if (!(await stopWorkerPid(pid, 5000))) allStopped = false;+ if (!(await stopWorkerPid(pid, SHUTDOWN_HARD_EXIT_MS + 1000))) allStopped = false;+ }+ if (workerCandidates.size > 0 && [...candidates].some((pid) => !workerCandidates.has(pid))) {+ await waitForEngineFlush();}const skippedForeign: Array<{ pid: number; comm: string }> = [];for (const pid of candidates) {diff --git a/src/cli/engine-config.ts b/src/cli/engine-config.tsindex 4982b4ef..e873494c 100644--- a/src/cli/engine-config.ts+++ b/src/cli/engine-config.ts@@ -33,6 +33,21 @@ export function configuredSaveIntervalMs(renderedConfig: string): number | nullreturn match ? parseInt(match[1]!, 10) : null;}+export const ENGINE_DEFAULT_SAVE_INTERVAL_MS = 5000;+export const ENGINE_FLUSH_MARGIN_MS = 1500;+export const ENGINE_FLUSH_WAIT_CAP_MS = 15_000;++export function engineFlushWaitMs(+ stateBackend: "file" | "redis",+ configTexts: readonly string[],+): number {+ if (stateBackend === "redis") return 0;+ const interval =+ configTexts.map(configuredSaveIntervalMs).find((ms) => ms !== null) ??+ ENGINE_DEFAULT_SAVE_INTERVAL_MS;+ return Math.min(interval + ENGINE_FLUSH_MARGIN_MS, ENGINE_FLUSH_WAIT_CAP_MS);+}+export function persistedBuiltinConfigDirs(engineCwd: string,configPath: string,diff --git a/src/cli/engine-install.ts b/src/cli/engine-install.tsnew file mode 100644index 00000000..db1b38b4--- /dev/null+++ b/src/cli/engine-install.ts@@ -0,0 +1,50 @@+export const III_INSTALL_CONNECT_TIMEOUT_S = 15;+export const III_INSTALL_MAX_TIME_S = 300;+export const III_INSTALL_SPAWN_TIMEOUT_MS =+ (III_INSTALL_CONNECT_TIMEOUT_S + III_INSTALL_MAX_TIME_S + 30) * 1000;++function curlTimeoutFlags(): string {+ return `--connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S} --max-time ${III_INSTALL_MAX_TIME_S}`;+}++export function iiiInstallShellCommand(+ releaseUrl: string,+ binDir: string,+ binPath: string,+): string {+ const archive = `${binDir}/.iii-download.tar.gz`;+ return [+ `mkdir -p "${binDir}"`,+ `rm -f "${archive}"`,+ `if curl -fsSL ${curlTimeoutFlags()} -o "${archive}" "${releaseUrl}" && tar -xzf "${archive}" -C "${binDir}"; then rm -f "${archive}"; else code=$?; rm -f "${archive}"; exit $code; fi`,+ `chmod +x "${binPath}"`,+ ].join(" && ");+}++export function iiiManualInstallCommand(+ releaseUrl: string,+ binDir: string,+ binPath: string,+): string {+ return `mkdir -p "${binDir}" && archive="$(mktemp "${binDir}/.iii-download.XXXXXX")" && { curl -fL --connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S} -o "$archive" "${releaseUrl}" && tar -xzf "$archive" -C "${binDir}"; code=$?; rm -f "$archive"; (exit $code); } && chmod +x "${binPath}"`;+}++export function describeInstallFailure(result: {+ error?: Error & { code?: string };+ signal?: NodeJS.Signals | null;+ status?: number | null;+ stderr?: string | null;+ stdout?: string | null;+}): string {+ if (result.error?.code === "ETIMEDOUT") {+ return `timed out after ${Math.round(III_INSTALL_SPAWN_TIMEOUT_MS / 1000)} s`;+ }+ const output = (result.stderr || result.stdout || "").toString().trim();+ if (output) return output;+ if (result.status === 28) {+ return `download timed out (no connection within ${III_INSTALL_CONNECT_TIMEOUT_S} s or not finished within ${III_INSTALL_MAX_TIME_S} s)`;+ }+ if (result.signal) return `installer stopped by ${result.signal}`;+ if (result.error) return result.error.message;+ return `installer exited with status ${result.status ?? "unknown"}`;+}diff --git a/src/cli/ready-hint.ts b/src/cli/ready-hint.tsnew file mode 100644index 00000000..12bb0be6--- /dev/null+++ b/src/cli/ready-hint.ts@@ -0,0 +1,8 @@+const DEFAULT_REST_PORT = 3111;++export function portFlagSuffix(restPort: number, instance: number): string {+ if (instance > 0 && restPort === DEFAULT_REST_PORT + instance * 100) {+ return ` --instance ${instance}`;+ }+ return restPort === DEFAULT_REST_PORT ? "" : ` --port ${restPort}`;+}diff --git a/src/config.ts b/src/config.tsindex 7601a3a1..7fc5a655 100644--- a/src/config.ts+++ b/src/config.ts@@ -21,6 +21,13 @@ const DATA_DIR = join(homedir(), ".agentmemory");const ENV_FILE = join(DATA_DIR, ".env");let warnPremiumModelShown = false;+let providerNoticeShown = false;++function writeProviderNoticeOnce(text: string): void {+ if (providerNoticeShown) return;+ providerNoticeShown = true;+ process.stderr.write(text);+}// Parsed ~/.agentmemory/.env, memoized for the process lifetime. getMergedEnv()// runs on every config getter (~20 of them), so without this cache a single@@ -158,10 +165,10 @@ function detectProvider(env: Record<string, string>): ProviderConfig {const allowAgentSdk = env["AGENTMEMORY_ALLOW_AGENT_SDK"] === "true";if (!allowAgentSdk) {- process.stderr.write(+ writeProviderNoticeOnce(pc.dim(- "[agentmemory] No LLM provider key set — running zero-LLM with BM25 search. " +- "Set EMBEDDING_PROVIDER=local for on-device semantic embeddings. " ++ "[agentmemory] No LLM provider key set — running zero-LLM: no LLM compression or summaries; search uses BM25 plus any configured embedding provider. " ++ "Set EMBEDDING_PROVIDER=local for on-device semantic embeddings if none is configured. " +"Set ANTHROPIC_API_KEY (or GEMINI/OPENAI/OPENROUTER/MINIMAX) in ~/.agentmemory/.env for LLM compression and summaries. " +"Agent-SDK fallback stays off by default to avoid a Stop-hook recursion loop; opt in with AGENTMEMORY_AUTO_COMPRESS=true + AGENTMEMORY_ALLOW_AGENT_SDK=true.\n",),@@ -173,7 +180,7 @@ function detectProvider(env: Record<string, string>): ProviderConfig {};}- process.stderr.write(+ writeProviderNoticeOnce("[agentmemory] WARNING: agent-sdk fallback enabled via AGENTMEMORY_ALLOW_AGENT_SDK=true. " +"This spawns @anthropic-ai/claude-agent-sdk child sessions that can trigger the Stop-hook " +"recursion loop. A SDK-child env marker is set to block re-entry, " +diff --git a/src/functions/export-import.ts b/src/functions/export-import.tsindex 1cdd977c..1758a94c 100644--- a/src/functions/export-import.ts+++ b/src/functions/export-import.ts@@ -6,10 +6,6 @@ import type {SessionSummary,ProjectProfile,ExportData,- GraphNode,- GraphEdge,- SemanticMemory,- ProceduralMemory,Action,ActionEdge,Routine,@@ -27,7 +23,7 @@ import type {import { importOrigin } from "../types.js";import { normalizeAccessLog } from "./access-tracker.js";import { KV } from "../state/schema.js";-import { checkPayloadFrameSize } from "../state/frame-guard.js";+import { checkPayloadFrameSize, oversizedPayloadError, payloadByteLength, SAFE_PAYLOAD_BYTES } from "../state/frame-guard.js";import { StateKV } from "../state/kv.js";import {addSessionToProjectIndex,@@ -68,34 +64,85 @@ async function runChunked<T>(}}+const EXPORT_OVERSIZE_HINT =+ "narrow the range with ?maxSessions / ?offset, or export fewer collections; the non-session collections (memories, graph, semantic, actions, lessons, ...) are not yet paginated";++const EXPORT_COLLECTIONS: ReadonlyArray<readonly [keyof ExportData, string]> = [+ ["graphNodes", KV.graphNodes],+ ["graphEdges", KV.graphEdges],+ ["semanticMemories", KV.semantic],+ ["proceduralMemories", KV.procedural],+ ["actions", KV.actions],+ ["actionEdges", KV.actionEdges],+ ["sentinels", KV.sentinels],+ ["sketches", KV.sketches],+ ["crystals", KV.crystals],+ ["facets", KV.facets],+ ["lessons", KV.lessons],+ ["insights", KV.insights],+ ["routines", KV.routines],+ ["signals", KV.signals],+ ["checkpoints", KV.checkpoints],+ ["accessLogs", KV.accessLog],+];++export class ExportBudget {+ bytes = 0;++ constructor(private readonly limit = SAFE_PAYLOAD_BYTES) {}++ fits(items: readonly unknown[], key = ""): boolean {+ this.bytes += key.length + 6;+ for (const item of items) {+ this.bytes += payloadByteLength(item) + 1;+ if (this.bytes > this.limit) return false;+ }+ return this.bytes <= this.limit;+ }+}+export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void {- sdk.registerFunction("mem::export",+ sdk.registerFunction("mem::export",async (data?: { maxSessions?: number; offset?: number }) => {const rawMax = Number(data?.maxSessions);const maxSessions = Number.isFinite(rawMax) && rawMax > 0 ? Math.min(Math.floor(rawMax), 1000) : undefined;const rawOffset = Number(data?.offset);const offset = Number.isFinite(rawOffset) && rawOffset >= 0 ? Math.floor(rawOffset) : 0;+ const budget = new ExportBudget();+ const refuse = (collection: string) => {+ logger.warn("Export exceeds transport frame limit", {+ bytesSoFar: budget.bytes,+ collection,+ });+ return {+ ...oversizedPayloadError(budget.bytes, EXPORT_OVERSIZE_HINT),+ stoppedAt: collection,+ };+ };+ const optional = async <T>(scope: string): Promise<T[]> =>+ kv.list<T>(scope).catch(() => [] as T[]);+const allSessions = await kv.list<Session>(KV.sessions);const paginatedSessions = maxSessions !== undefined? allSessions.slice(offset, offset + maxSessions): allSessions;+ if (!budget.fits(paginatedSessions)) return refuse("sessions");+const memories = await kv.list<Memory>(KV.memories);+ if (!budget.fits(memories)) return refuse("memories");+const summaries = await kv.list<SessionSummary>(KV.summaries);+ if (!budget.fits(summaries)) return refuse("summaries");const observations: Record<string, CompressedObservation[]> = {};- const obsResults = await Promise.all(- paginatedSessions.map((session) =>- kv- .list<CompressedObservation>(KV.observations(session.id))- .catch(() => [] as CompressedObservation[])- .then((obs) => ({ sessionId: session.id, obs })),- ),- );- for (const { sessionId, obs } of obsResults) {- if (obs.length > 0) {- observations[sessionId] = obs;- }+ for (const session of paginatedSessions) {+ const obs = await optional<CompressedObservation>(+ KV.observations(session.id),+ );+ if (obs.length === 0) continue;+ if (!budget.fits(obs, session.id)) return refuse("observations");+ observations[session.id] = obs;}const profiles: ProjectProfile[] = [];@@ -108,42 +155,15 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): voidfor (const profile of profileResults) {if (profile) profiles.push(profile);}+ if (!budget.fits(profiles)) return refuse("profiles");- const [- graphNodes,- graphEdges,- semanticMemories,- proceduralMemories,- actions,- actionEdges,- sentinels,- sketches,- crystals,- facets,- lessons,- insights,- routines,- signals,- checkpoints,- accessLogs,- ] = await Promise.all([- kv.list<GraphNode>(KV.graphNodes).catch(() => []),- kv.list<GraphEdge>(KV.graphEdges).catch(() => []),- kv.list<SemanticMemory>(KV.semantic).catch(() => []),- kv.list<ProceduralMemory>(KV.procedural).catch(() => []),- kv.list<Action>(KV.actions).catch(() => []),- kv.list<ActionEdge>(KV.actionEdges).catch(() => []),- kv.list<Sentinel>(KV.sentinels).catch(() => []),- kv.list<Sketch>(KV.sketches).catch(() => []),- kv.list<Crystal>(KV.crystals).catch(() => []),- kv.list<Facet>(KV.facets).catch(() => []),- kv.list<Lesson>(KV.lessons).catch(() => []),- kv.list<Insight>(KV.insights).catch(() => []),- kv.list<Routine>(KV.routines).catch(() => []),- kv.list<Signal>(KV.signals).catch(() => []),- kv.list<Checkpoint>(KV.checkpoints).catch(() => []),- kv.list<AccessLogExport>(KV.accessLog).catch(() => []),- ]);+ const collections: Partial<ExportData> = {};+ for (const [field, scope] of EXPORT_COLLECTIONS) {+ const items = await optional<unknown>(scope);+ if (items.length === 0) continue;+ if (!budget.fits(items, field)) return refuse(field);+ (collections as Record<string, unknown>)[field] = items;+ }const exportData: ExportData = {version: VERSION,@@ -153,24 +173,7 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): voidmemories,summaries,profiles: profiles.length > 0 ? profiles : undefined,- graphNodes: graphNodes.length > 0 ? graphNodes : undefined,- graphEdges: graphEdges.length > 0 ? graphEdges : undefined,- semanticMemories:- semanticMemories.length > 0 ? semanticMemories : undefined,- proceduralMemories:- proceduralMemories.length > 0 ? proceduralMemories : undefined,- actions: actions.length > 0 ? actions : undefined,- actionEdges: actionEdges.length > 0 ? actionEdges : undefined,- sentinels: sentinels.length > 0 ? sentinels : undefined,- sketches: sketches.length > 0 ? sketches : undefined,- crystals: crystals.length > 0 ? crystals : undefined,- facets: facets.length > 0 ? facets : undefined,- lessons: lessons.length > 0 ? lessons : undefined,- insights: insights.length > 0 ? insights : undefined,- routines: routines.length > 0 ? routines : undefined,- signals: signals.length > 0 ? signals : undefined,- checkpoints: checkpoints.length > 0 ? checkpoints : undefined,- accessLogs: accessLogs.length > 0 ? accessLogs : undefined,+ ...collections,};if (maxSessions !== undefined) {@@ -182,6 +185,14 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): void};}+ const oversized = checkPayloadFrameSize(exportData, EXPORT_OVERSIZE_HINT);+ if (oversized) {+ logger.warn("Export exceeds transport frame limit", {+ bytes: oversized.bytes,+ });+ return oversized;+ }+const totalObs = Object.values(observations).reduce((sum, arr) => sum + arr.length,0,@@ -194,19 +205,6 @@ export function registerExportImportFunction(sdk: IIIClient, kv: StateKV): voidsummaries: summaries.length,});- // Only session collections page on ?maxSessions/?offset, so a large- // store can exceed the transport cap even at ?maxSessions=1.- const oversized = checkPayloadFrameSize(- exportData,- "narrow the range with ?maxSessions / ?offset, or export fewer collections; the non-session collections (memories, graph, semantic, actions, lessons, ...) are not yet paginated",- );- if (oversized) {- logger.warn("Export exceeds transport frame limit", {- bytes: oversized.bytes,- });- return oversized;- }-return exportData;},);diff --git a/src/functions/governance.ts b/src/functions/governance.tsindex 2b225a86..cde04314 100644--- a/src/functions/governance.ts+++ b/src/functions/governance.ts@@ -7,8 +7,30 @@ import { deleteAccessLog } from "./access-tracker.js";import { getSearchIndex, vectorIndexRemove, flushIndexSave } from "./search.js";import { logger } from "../logger.js";+const BULK_FILTER_KEYS = ["type", "dateFrom", "dateTo", "project", "qualityBelow"];+const BULK_CONTROL_KEYS = ["dryRun", "reason"];++type DeleteFailure = { id: string; error: string };++function errorMessage(err: unknown): string {+ return err instanceof Error ? err.message : String(err);+}++async function deleteMemoryRecord(+ kv: StateKV,+ id: string,+): Promise<"deleted" | "missing"> {+ const mem = await kv.get<Memory>(KV.memories, id);+ if (!mem) return "missing";+ await kv.delete(KV.memories, id);+ await deleteAccessLog(kv, id);+ getSearchIndex().remove(id);+ vectorIndexRemove(id);+ return "deleted";+}+export function registerGovernanceFunction(sdk: IIIClient, kv: StateKV): void {- sdk.registerFunction("mem::governance-delete",+ sdk.registerFunction("mem::governance-delete",async (data: { memoryIds: string[]; reason?: string }) => {if (!data.memoryIds ||@@ -18,51 +40,91 @@ export function registerGovernanceFunction(sdk: IIIClient, kv: StateKV): void {return { success: false, error: "memoryIds array is required" };}- let deleted = 0;+ const deletedIds: string[] = [];+ const notFound: string[] = [];+ const failures: DeleteFailure[] = [];for (const id of data.memoryIds) {- const mem = await kv.get<Memory>(KV.memories, id);- if (mem) {- await kv.delete(KV.memories, id);- await deleteAccessLog(kv, id);- getSearchIndex().remove(id);- vectorIndexRemove(id);- deleted++;+ try {+ if ((await deleteMemoryRecord(kv, id)) === "deleted") {+ deletedIds.push(id);+ } else {+ notFound.push(id);+ }+ } catch (err) {+ logger.warn("Governance delete failed", {+ memoryId: id,+ error: errorMessage(err),+ });+ failures.push({ id, error: "delete_failed" });}}+ const deleted = deletedIds.length;if (deleted > 0) await flushIndexSave();- await recordAudit(- kv,- "delete",- "mem::governance-delete",- data.memoryIds,- {- reason: data.reason || "manual deletion",- deleted,- },- );+ if (deleted > 0 || failures.length > 0) {+ await recordAudit(+ kv,+ "delete",+ "mem::governance-delete",+ deletedIds,+ {+ reason: data.reason || "manual deletion",+ deleted,+ requested: data.memoryIds.length,+ notFound: notFound.length,+ failed: failures.length,+ failures: failures.length > 0 ? failures : undefined,+ },+ );+ }logger.info("Governance delete", {requested: data.memoryIds.length,deleted,+ notFound: notFound.length,+ failed: failures.length,});- return { success: true, deleted, total: data.memoryIds.length };+ return {+ success: failures.length === 0,+ deleted,+ total: data.memoryIds.length,+ notFound,+ failed: failures.length,+ failures: failures.length > 0 ? failures : undefined,+ };},);- sdk.registerFunction("mem::governance-bulk",- async (data: GovernanceFilter & { dryRun?: boolean }) => {+ sdk.registerFunction("mem::governance-bulk",+ async (input: GovernanceFilter & { dryRun?: boolean; reason?: string }) => {+ const data = input ?? {};+ const unsupported = Object.keys(data).filter(+ (key) => !BULK_FILTER_KEYS.includes(key) && !BULK_CONTROL_KEYS.includes(key),+ );+ if (unsupported.length > 0) {+ return {+ success: false,+ error: `Unsupported bulk delete filter: ${unsupported.join(", ")}. Supported filters: ${BULK_FILTER_KEYS.join(", ")}`,+ };+ }+ if (+ data.project !== undefined &&+ (typeof data.project !== "string" || data.project.trim().length === 0)+ ) {+ return { success: false, error: "project must be a non-empty string" };+ }const hasFilter =(data.type && data.type.length > 0) ||data.dateFrom ||data.dateTo ||+ (typeof data.project === "string" && data.project.length > 0) ||data.qualityBelow !== undefined;- if (!hasFilter && !data.dryRun) {+ if (!hasFilter) {return {success: false,- error: "At least one filter is required for non-dryRun bulk delete",+ error: `At least one filter is required for bulk delete (${BULK_FILTER_KEYS.join(", ")})`,};}@@ -90,6 +152,9 @@ export function registerGovernanceFunction(sdk: IIIClient, kv: StateKV): void {(m) => new Date(m.createdAt).getTime() <= to,);}+ if (typeof data.project === "string" && data.project.length > 0) {+ candidates = candidates.filter((m) => m.project === data.project);+ }if (data.qualityBelow !== undefined) {candidates = candidates.filter((m) => m.strength < data.qualityBelow!);}@@ -105,66 +170,63 @@ export function registerGovernanceFunction(sdk: IIIClient, kv: StateKV): void {const BATCH_SIZE = 50;const successfulIds: string[] = [];- const failures: Array<{ id: string; error: string }> = [];+ const notFound: string[] = [];+ const failures: DeleteFailure[] = [];for (let i = 0; i < candidates.length; i += BATCH_SIZE) {const batch = candidates.slice(i, i + BATCH_SIZE);const results = await Promise.allSettled(- batch.map(async (mem) => {- await kv.delete(KV.memories, mem.id);- await deleteAccessLog(kv, mem.id);- getSearchIndex().remove(mem.id);- vectorIndexRemove(mem.id);- }),+ batch.map((mem) => deleteMemoryRecord(kv, mem.id)),);results.forEach((result, j) => {const mem = batch[j];- if (result.status === "fulfilled") {- successfulIds.push(mem.id);- } else {+ if (result.status === "rejected") {logger.warn("Governance bulk delete failed", {memoryId: mem.id,- error:- result.reason instanceof Error- ? result.reason.message- : String(result.reason),- });- failures.push({- id: mem.id,- error: "delete_failed",+ error: errorMessage(result.reason),});+ failures.push({ id: mem.id, error: "delete_failed" });+ } else if (result.value === "deleted") {+ successfulIds.push(mem.id);+ } else {+ notFound.push(mem.id);}});}if (successfulIds.length > 0) await flushIndexSave();- await safeAudit(- kv,- "delete",- "mem::governance-bulk",- successfulIds,- {- filter: data,- deleted: successfulIds.length,- failed: failures.length,- failures: failures.length > 0 ? failures : undefined,- },- );+ if (successfulIds.length > 0 || failures.length > 0) {+ await safeAudit(+ kv,+ "delete",+ "mem::governance-bulk",+ successfulIds,+ {+ filter: data,+ deleted: successfulIds.length,+ notFound: notFound.length,+ failed: failures.length,+ failures: failures.length > 0 ? failures : undefined,+ },+ );+ }logger.info("Governance bulk delete", {deleted: successfulIds.length,+ notFound: notFound.length,failed: failures.length,});return {success: failures.length === 0,deleted: successfulIds.length,+ notFound,failed: failures.length,failures: failures.length > 0 ? failures : undefined,};},);- sdk.registerFunction("mem::audit-query",+ sdk.registerFunction("mem::audit-query",async (data?: {operation?: AuditEntry["operation"];dateFrom?: string;diff --git a/src/functions/remember.ts b/src/functions/remember.tsindex 7acb7e59..89c47f4e 100644--- a/src/functions/remember.ts+++ b/src/functions/remember.ts@@ -270,25 +270,78 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {observationIds?: string[];memoryId?: string;}) => {+ type ObservationRef = { id?: string; imageData?: string; imageRef?: string };let deleted = 0;const deletedMemoryIds: string[] = [];const deletedObservationIds: string[] = [];+ const notFound: string[] = [];+ const failures: Array<{ id: string; error: string }> = [];let deletedSession = false;+ let deletedSummary = false;+ let indexCleaned = false;const { decrementImageRef } = await import("./image-refs.js");- if (data.memoryId) {- const mem = await kv.get<Memory>(KV.memories, data.memoryId);- if (mem) {- await kv.delete(KV.memories, data.memoryId);- if (mem.imageRef) {- await decrementImageRef(kv, sdk, mem.imageRef);+ const recordFailure = (id: string, err: unknown) => {+ logger.warn("Forget failed", {+ id,+ error: err instanceof Error ? err.message : String(err),+ });+ failures.push({ id, error: "delete_failed" });+ };++ const attempt = async (id: string, remove: () => Promise<boolean>) => {+ try {+ if (await remove()) deleted++;+ else notFound.push(id);+ } catch (err) {+ recordFailure(id, err);+ }+ };++ const forgetObservation = async (+ sessionId: string,+ obsId: string,+ known?: ObservationRef,+ ): Promise<boolean> => {+ const obs =+ known ??+ (await kv.get<ObservationRef>(KV.observations(sessionId), obsId));+ if (!obs) return false;+ await kv.delete(KV.observations(sessionId), obsId);+ await unindexObservationSession(kv, obsId).catch(() => {});+ try {+ if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData);+ if (obs.imageRef && obs.imageRef !== obs.imageData) {+ await decrementImageRef(kv, sdk, obs.imageRef);}- await deleteAccessLog(kv, data.memoryId);- getSearchIndex().remove(data.memoryId);- vectorIndexRemove(data.memoryId);- deletedMemoryIds.push(data.memoryId);- deleted++;+ } finally {+ getSearchIndex().remove(obsId);+ vectorIndexRemove(obsId);+ indexCleaned = true;}+ deletedObservationIds.push(obsId);+ return true;+ };++ if (data.memoryId) {+ const memoryId = data.memoryId;+ await attempt(memoryId, async () => {+ const mem = await kv.get<Memory>(KV.memories, memoryId);+ if (!mem) return false;+ await kv.delete(KV.memories, memoryId);+ try {+ if (mem.imageRef) {+ await decrementImageRef(kv, sdk, mem.imageRef);+ }+ } finally {+ getSearchIndex().remove(memoryId);+ vectorIndexRemove(memoryId);+ indexCleaned = true;+ }+ await deleteAccessLog(kv, memoryId);+ deletedMemoryIds.push(memoryId);+ return true;+ });}if (@@ -296,21 +349,9 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {data.observationIds &&data.observationIds.length > 0) {+ const sessionId = data.sessionId;for (const obsId of data.observationIds) {- const obs = await kv.get<{ imageData?: string; imageRef?: string }>(- KV.observations(data.sessionId),- obsId,- );- await kv.delete(KV.observations(data.sessionId), obsId);- await unindexObservationSession(kv, obsId).catch(() => {});- if (obs?.imageData) await decrementImageRef(kv, sdk, obs.imageData);- if (obs?.imageRef && obs.imageRef !== obs.imageData) {- await decrementImageRef(kv, sdk, obs.imageRef);- }- getSearchIndex().remove(obsId);- vectorIndexRemove(obsId);- deletedObservationIds.push(obsId);- deleted++;+ await attempt(obsId, () => forgetObservation(sessionId, obsId));}}@@ -319,39 +360,40 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {(!data.observationIds || data.observationIds.length === 0) &&!data.memoryId) {- const observations = await kv.list<{ id: string; imageData?: string; imageRef?: string }>(- KV.observations(data.sessionId),+ const sessionId = data.sessionId;+ const observations = await kv.list<ObservationRef & { id: string }>(+ KV.observations(sessionId),);for (const obs of observations) {- await kv.delete(KV.observations(data.sessionId), obs.id);- await unindexObservationSession(kv, obs.id).catch(() => {});- if (obs.imageData) await decrementImageRef(kv, sdk, obs.imageData);- if (obs.imageRef && obs.imageRef !== obs.imageData) {- await decrementImageRef(kv, sdk, obs.imageRef);- }- getSearchIndex().remove(obs.id);- vectorIndexRemove(obs.id);- deletedObservationIds.push(obs.id);- deleted++;+ await attempt(obs.id, () => forgetObservation(sessionId, obs.id, obs));}- const sessionToDelete = await kv- .get<Session>(KV.sessions, data.sessionId)- .catch(() => null);- await kv.delete(KV.sessions, data.sessionId);- await kv.delete(KV.summaries, data.sessionId);- if (sessionToDelete) {+ await attempt(sessionId, async () => {+ const session = await kv.get<Session>(KV.sessions, sessionId);+ if (!session) return false;+ await kv.delete(KV.sessions, sessionId);await removeSessionFromProjectIndex(kv,- sessionToDelete.project,- data.sessionId,+ session.project,+ sessionId,).catch(() => {});+ deletedSession = true;+ return true;+ });+ try {+ const summary = await kv.get(KV.summaries, sessionId);+ if (summary) {+ await kv.delete(KV.summaries, sessionId);+ deletedSummary = true;+ deleted++;+ }+ } catch (err) {+ recordFailure(`summary:${sessionId}`, err);}- deletedSession = true;- deleted += 2;}- if (deleted > 0) {- await flushIndexSave();+ if (deleted > 0 || indexCleaned) await flushIndexSave();++ if (deleted > 0 || failures.length > 0) {await recordAudit(kv,"forget",@@ -363,13 +405,27 @@ export function registerRememberFunction(sdk: IIIClient, kv: StateKV): void {memoriesDeleted: deletedMemoryIds.length,observationsDeleted: deletedObservationIds.length,sessionDeleted: deletedSession,+ summaryDeleted: deletedSummary,+ notFound: notFound.length,+ failed: failures.length,+ failures: failures.length > 0 ? failures : undefined,reason: "user-initiated forget",},);}- logger.info("Memory forgotten", { deleted });- return { success: true, deleted };+ logger.info("Memory forgotten", {+ deleted,+ notFound: notFound.length,+ failed: failures.length,+ });+ return {+ success: failures.length === 0,+ deleted,+ notFound,+ failed: failures.length,+ failures: failures.length > 0 ? failures : undefined,+ };},);}diff --git a/src/functions/search.ts b/src/functions/search.tsindex 0493e23a..0130d0d7 100644--- a/src/functions/search.ts+++ b/src/functions/search.ts@@ -56,6 +56,19 @@ export function isBm25RebuildIncomplete(): boolean {return bm25RebuildIncomplete}+let keywordRebuildPending = false+let keywordRebuildsRunning = 0+let keywordRebuildEpoch = 0+export function getKeywordRebuildEpoch(): number {+ return keywordRebuildEpoch+}+export function markKeywordRebuildPending(): void {+ keywordRebuildPending = true+}+export function isKeywordRebuildInProgress(): boolean {+ return keywordRebuildPending || keywordRebuildsRunning > 0+}+let pendingVectorBackfill = 0export type VectorBackfillState = "idle" | "running" | "waiting-for-opt-in"let vectorBackfillState: VectorBackfillState = "idle"@@ -516,10 +529,26 @@ async function listSessionsWithRetry(kv: StateKV): Promise<Session[] | null> {return null}+type KeywordRebuildResult = { documents: number; vectorJobs: VectorBackfillJob[]; fullBackfillPending: number }+export async function rebuildKeywordIndex(kv: StateKV,vectorBackfillSince?: string | null,-): Promise<{ documents: number; vectorJobs: VectorBackfillJob[]; fullBackfillPending: number }> {+): Promise<KeywordRebuildResult> {+ keywordRebuildsRunning+++ try {+ return await runKeywordRebuild(kv, vectorBackfillSince)+ } finally {+ keywordRebuildsRunning--+ keywordRebuildPending = false+ keywordRebuildEpoch+++ }+}++async function runKeywordRebuild(+ kv: StateKV,+ vectorBackfillSince?: string | null,+): Promise<KeywordRebuildResult> {const idx = getSearchIndex()idx.clear()memoryIndexReady = falsediff --git a/src/functions/status.ts b/src/functions/status.tsindex 19fb07d7..3e4d8af6 100644--- a/src/functions/status.ts+++ b/src/functions/status.ts@@ -65,6 +65,7 @@ export interface StatusInputs {missingObservations: number | null;sessions: number | null;bm25Incomplete: boolean;+ keywordRebuildRunning?: boolean;pendingVectorBackfill: number;vectorBackfillState?: VectorBackfillState;};@@ -281,7 +282,7 @@ export function evaluateStatus(input: StatusInputs): StatusReport {}const missingObservations = input.index.missingObservations;- if (missingObservations !== null && missingObservations > 0) {+ if (!input.index.keywordRebuildRunning && missingObservations !== null && missingObservations > 0) {problems.push({level: "warn",code: "index-missing-observations",@@ -289,7 +290,14 @@ export function evaluateStatus(input: StatusInputs): StatusReport {fix: "Restart agentmemory: the boot reconcile re-indexes observations missing from the snapshot.",});}- if (missingObservations === null) {+ if (input.index.keywordRebuildRunning) {+ problems.push({+ level: "info",+ code: "keyword-index-rebuilding",+ message: "The keyword index is still rebuilding from stored data, so the check for observations missing from search waits until it finishes.",+ fix: "No action needed. The check runs on the next health update after the rebuild.",+ });+ } else if (missingObservations === null) {problems.push({level: "info",code: "index-check-unavailable",diff --git a/src/index.ts b/src/index.tsindex 16dfd396..1025bf9d 100644--- a/src/index.ts+++ b/src/index.ts@@ -40,6 +40,7 @@ import {registerSearchFunction,backfillVectors,rebuildKeywordIndex,+ markKeywordRebuildPending,getSearchIndex,setVectorIndex,setEmbeddingProvider,@@ -415,6 +416,7 @@ async function main() {setHybridRanker(hybridRanker);registerRecentSearchesSweepFunction(sdk, kv);+ markKeywordRebuildPending();registerApiTriggers(sdk, kv, secret, metricsStore, provider);registerEventTriggers(sdk, kv);registerViewerStreamTriggers(sdk, kv, { secret, metricsStore, provider });diff --git a/src/triggers/api.ts b/src/triggers/api.tsindex 55f2c599..f60e61fa 100644--- a/src/triggers/api.ts+++ b/src/triggers/api.ts@@ -16,6 +16,8 @@ import { CONSOLIDATION_COUNTS_REUSE_MS, CONSOLIDATION_LAST_RUN_KEY, PROCEDURAL_Mimport { UNINDEXED_SCAN_REUSE_MS, evaluateStatus, prefersHtml, renderStatusHtml, singleFlight, type GraphStatsInput, type StatusReport } from "../functions/status.js";import {findUnindexedObservations,+ getKeywordRebuildEpoch,+ isKeywordRebuildInProgress,getIndexPersistenceStatus,getEmbeddingProvider,getPendingVectorBackfillCount,@@ -304,12 +306,14 @@ async function probeStateStore(kv: StateKV): Promise<{ ok: boolean; latencyMs?:}type UnindexedScan = Awaited<ReturnType<typeof findUnindexedObservations>>;-const unindexedScans = new WeakMap<StateKV, { run: () => Promise<UnindexedScan>; last: { at: number; value: UnindexedScan } | null }>();+type UnindexedScanEntry = { epoch: number; run: () => Promise<UnindexedScan>; last: { at: number; value: UnindexedScan } | null };+const unindexedScans = new WeakMap<StateKV, UnindexedScanEntry>();function unindexedScanFor(kv: StateKV) {let entry = unindexedScans.get(kv);- if (!entry) {- const created: { run: () => Promise<UnindexedScan>; last: { at: number; value: UnindexedScan } | null } = {+ if (!entry || entry.epoch !== getKeywordRebuildEpoch()) {+ const created: UnindexedScanEntry = {+ epoch: getKeywordRebuildEpoch(),run: singleFlight(async () => {const value = await findUnindexedObservations(kv);created.last = { at: Date.now(), value };@@ -329,9 +333,10 @@ export interface StatusReporterDeps {}export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusReporterDeps) {- const scan = unindexedScanFor(kv);return async function statusReport(options: { health?: HealthSnapshot | null; scanMaxAgeMs?: number } = {}): Promise<StatusReport> {const idx = getSearchIndex();+ const keywordRebuildRunning = isKeywordRebuildInProgress();+ const scan = unindexedScanFor(kv);const cached = scan.last && options.scanMaxAgeMs !== undefined && Date.now() - scan.last.at < options.scanMaxAgeMs? scan.last.value: null;@@ -342,7 +347,7 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusResdk.trigger({ function_id: "mem::graph-stats", payload: {} }) as Promise<GraphStatsInput>,STATUS_CHECK_TIMEOUT_MS,),- cached ? Promise.resolve(cached) : valueWithin(scan.run(), STATUS_CHECK_TIMEOUT_MS),+ keywordRebuildRunning ? Promise.resolve(null) : cached ? Promise.resolve(cached) : valueWithin(scan.run(), STATUS_CHECK_TIMEOUT_MS),valueWithin(kv.get<AuditMigrationState>(KV.auditMonths, AUDIT_MIGRATION_STATE_KEY),STATUS_CHECK_TIMEOUT_MS,@@ -355,6 +360,7 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusRedeps.provider && "circuitState" in deps.provider? (deps.provider.circuitState as { state?: string; failures?: number } | null): null;+ const config = loadConfig();return evaluateStatus({now: new Date(),version: VERSION,@@ -362,8 +368,8 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusReuptimeSeconds: Math.round(process.uptime()),stateBackend: kv.backend === "redis" ? "redis" : "file",ports: {- rest: loadConfig().restPort ?? null,- streams: loadConfig().streamsPort ?? null,+ rest: config.restPort ?? null,+ streams: config.streamsPort ?? null,viewer: getViewerSkipped() ? null : (getBoundViewerPort() ?? null),},health: health@@ -391,6 +397,7 @@ export function createStatusReporter(sdk: IIIClient, kv: StateKV, deps: StatusRemissingObservations: unindexed ? unindexed.missing.length : null,sessions: unindexed ? unindexed.sessions : null,bm25Incomplete: isBm25RebuildIncomplete(),+ keywordRebuildRunning,pendingVectorBackfill: getPendingVectorBackfillCount(),vectorBackfillState: getVectorBackfillState(),},@@ -2303,6 +2310,7 @@ export function registerApiTriggers(type?: string[];dateFrom?: string;dateTo?: string;+ project?: string;qualityBelow?: number;dryRun?: boolean;}>,diff --git a/test/cli-ready-hint.test.ts b/test/cli-ready-hint.test.tsnew file mode 100644index 00000000..cbb4d351--- /dev/null+++ b/test/cli-ready-hint.test.ts@@ -0,0 +1,20 @@+import { describe, expect, it } from "vitest";+import { portFlagSuffix } from "../src/cli/ready-hint.js";++describe("ready hint port flags", () => {+ it("adds nothing on the default port", () => {+ expect(portFlagSuffix(3111, 0)).toBe("");+ });++ it("carries a custom --port into the suggested commands", () => {+ expect(portFlagSuffix(4321, 0)).toBe(" --port 4321");+ });++ it("uses --instance when the port comes from an instance block", () => {+ expect(portFlagSuffix(3211, 1)).toBe(" --instance 1");+ });++ it("prefers the live port when --port overrides an instance block", () => {+ expect(portFlagSuffix(4321, 1)).toBe(" --port 4321");+ });+});diff --git a/test/engine-flush-wait.test.ts b/test/engine-flush-wait.test.tsnew file mode 100644index 00000000..c5b3cb75--- /dev/null+++ b/test/engine-flush-wait.test.ts@@ -0,0 +1,35 @@+import { describe, expect, it } from "vitest";+import { ENGINE_FLUSH_WAIT_CAP_MS, engineFlushWaitMs } from "../src/cli/engine-config.js";++const persistedState = [+ "id: iii-state",+ "value:",+ " adapter:",+ " config:",+ " file_path: /data/state_store.db",+ " store_method: file_based",+ " name: kv",+].join("\n");++describe("engine flush wait on stop", () => {+ it("waits one default save interval plus margin for the file store", () => {+ expect(engineFlushWaitMs("file", [persistedState])).toBe(6500);+ });++ it("falls back to the default window when no config can be read", () => {+ expect(engineFlushWaitMs("file", [])).toBe(6500);+ });++ it("follows a configured save interval", () => {+ const custom = `${persistedState}\n save_interval_ms: 2000`;+ expect(engineFlushWaitMs("file", [custom, "save_interval_ms: 9000"])).toBe(3500);+ });++ it("caps a very long save interval", () => {+ expect(engineFlushWaitMs("file", ["save_interval_ms: 600000"])).toBe(ENGINE_FLUSH_WAIT_CAP_MS);+ });++ it("does not wait for the redis state backend", () => {+ expect(engineFlushWaitMs("redis", [persistedState])).toBe(0);+ });+});diff --git a/test/engine-install.test.ts b/test/engine-install.test.tsnew file mode 100644index 00000000..04fb4605--- /dev/null+++ b/test/engine-install.test.ts@@ -0,0 +1,97 @@+import { spawnSync } from "node:child_process";+import { chmodSync, existsSync, mkdirSync, mkdtempSync, readdirSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";+import { afterEach, describe, expect, it } from "vitest";+import {+ III_INSTALL_CONNECT_TIMEOUT_S,+ III_INSTALL_MAX_TIME_S,+ describeInstallFailure,+ iiiInstallShellCommand,+ iiiManualInstallCommand,+} from "../src/cli/engine-install.js";++const sandboxes: string[] = [];++function sandbox(): string {+ const dir = mkdtempSync(join(tmpdir(), "agentmemory-install-"));+ sandboxes.push(dir);+ return dir;+}++afterEach(() => {+ for (const dir of sandboxes.splice(0)) rmSync(dir, { recursive: true, force: true });+});++function fakeCurl(dir: string, script: string): string {+ const bin = join(dir, "fakebin");+ mkdirSync(bin, { recursive: true });+ const path = join(bin, "curl");+ writeFileSync(path, `#!/bin/sh\n${script}\n`);+ chmodSync(path, 0o755);+ return bin;+}++function runInstall(dir: string, bin: string) {+ const binDir = join(dir, "bin");+ const binPath = join(binDir, "iii");+ const result = spawnSync(+ "sh",+ ["-c", iiiInstallShellCommand("https://example.invalid/iii.tar.gz", binDir, binPath)],+ { encoding: "utf-8", env: { ...process.env, PATH: `${bin}:${process.env.PATH}` } },+ );+ return { result, binDir, binPath };+}++describe("iii engine auto-installer", () => {+ it("passes connect and overall timeouts to curl", () => {+ const cmd = iiiInstallShellCommand("https://x/iii.tar.gz", "/b", "/b/iii");+ expect(cmd).toContain(`--connect-timeout ${III_INSTALL_CONNECT_TIMEOUT_S}`);+ expect(cmd).toContain(`--max-time ${III_INSTALL_MAX_TIME_S}`);+ });++ it("leaves no partial binary or archive behind when the download times out", () => {+ const dir = sandbox();+ const bin = fakeCurl(+ dir,+ 'out=""; while [ $# -gt 0 ]; do if [ "$1" = "-o" ]; then out="$2"; fi; shift; done; printf partial > "$out"; echo "curl: (28) Operation timed out" >&2; exit 28',+ );+ const { result, binDir, binPath } = runInstall(dir, bin);++ expect(result.status).toBe(28);+ expect(existsSync(binPath)).toBe(false);+ expect(readdirSync(binDir)).toEqual([]);+ expect(describeInstallFailure(result)).toContain("timed out");+ });++ it("installs the binary when the download completes", () => {+ const dir = sandbox();+ const staging = join(dir, "staging");+ mkdirSync(staging);+ writeFileSync(join(staging, "iii"), "#!/bin/sh\necho iii\n");+ const tarball = join(dir, "iii.tar.gz");+ spawnSync("tar", ["-czf", tarball, "-C", staging, "iii"]);+ const bin = fakeCurl(+ dir,+ `out=""; while [ $# -gt 0 ]; do if [ "$1" = "-o" ]; then out="$2"; fi; shift; done; cp "${tarball}" "$out"`,+ );+ const { result, binDir, binPath } = runInstall(dir, bin);++ expect(result.status).toBe(0);+ expect(existsSync(binPath)).toBe(true);+ expect(readdirSync(binDir)).toEqual(["iii"]);+ });++ it("explains a timeout without stderr and prints a copyable manual command", () => {+ expect(describeInstallFailure({ status: 28, stderr: "" })).toContain("download timed out");+ expect(+ describeInstallFailure({ status: null, error: Object.assign(new Error("x"), { code: "ETIMEDOUT" }) }),+ ).toContain("timed out after");+ const manual = iiiManualInstallCommand("https://x/iii.tar.gz", "/b", "/b/iii");+ expect(manual).toContain('curl -fL --connect-timeout');+ expect(manual).toContain('chmod +x "/b/iii"');+ expect(manual).toContain('mktemp "/b/.iii-download.XXXXXX"');+ expect(manual).not.toContain("/tmp/");+ expect(manual).toContain('rm -f "$archive"; (exit $code)');+ });+});diff --git a/test/export-incremental-budget.test.ts b/test/export-incremental-budget.test.tsnew file mode 100644index 00000000..4b47e09a--- /dev/null+++ b/test/export-incremental-budget.test.ts@@ -0,0 +1,177 @@+import { describe, it, expect, vi } from "vitest";++vi.mock("../src/logger.js", () => ({+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },+}));++import {+ registerExportImportFunction,+ ExportBudget,+} from "../src/functions/export-import.js";+import { registerApiTriggers } from "../src/triggers/api.js";+import { KV } from "../src/state/schema.js";+import { SAFE_PAYLOAD_BYTES, payloadByteLength } from "../src/state/frame-guard.js";++const BEARER = "export-budget-bearer";+const MIB = 1024 * 1024;++function countingKV() {+ const store = new Map<string, Map<string, unknown>>();+ const listCalls: string[] = [];+ return {+ listCalls,+ seed(scope: string, key: string, value: unknown) {+ if (!store.has(scope)) store.set(scope, new Map());+ store.get(scope)!.set(key, value);+ },+ get: async <T>(scope: string, key: string): Promise<T | null> =>+ (store.get(scope)?.get(key) as T) ?? null,+ set: async <T>(scope: string, key: string, data: T): Promise<T> => data,+ delete: async (): Promise<void> => {},+ update: async () => {},+ list: async <T>(scope: string): Promise<T[]> => {+ listCalls.push(scope);+ return Array.from(store.get(scope)?.values() ?? []) as T[];+ },+ };+}++function mockSdk() {+ const fns = new Map<string, Function>();+ return {+ registerFunction: (idOrOpts: string | { id: string }, handler: Function) => {+ const id = typeof idOrOpts === "string" ? idOrOpts : idOrOpts.id;+ fns.set(id, handler);+ },+ registerTrigger: () => {},+ trigger: async (input: { function_id: string; payload?: unknown }) =>+ fns.get(input.function_id)?.(input.payload),+ fns,+ };+}++function seedSessions(kv: ReturnType<typeof countingKV>, count: number, obsBytes: number) {+ for (let i = 0; i < count; i++) {+ const id = `ses_${i}`;+ kv.seed(KV.sessions, id, { id, project: "p", startedAt: "2026-09-01T00:00:00Z" });+ kv.seed(KV.observations(id), `obs_${i}`, {+ id: `obs_${i}`,+ sessionId: id,+ narrative: "n".repeat(obsBytes),+ });+ }+}++describe("mem::export stops assembling once the frame budget is exceeded (#1334)", () => {+ it("never lists observations or the graph when memories alone exceed the limit", async () => {+ const kv = countingKV();+ const sdk = mockSdk();+ registerExportImportFunction(sdk as never, kv as never);+ seedSessions(kv, 3, 10);+ kv.seed(KV.memories, "m_big", { id: "m_big", content: "z".repeat(SAFE_PAYLOAD_BYTES + 1024) });+ kv.seed(KV.graphNodes, "n_1", { id: "n_1" });++ const result = (await sdk.trigger({ function_id: "mem::export", payload: {} })) as {+ success: boolean;+ oversized: boolean;+ stoppedAt: string;+ };++ expect(result.success).toBe(false);+ expect(result.oversized).toBe(true);+ expect(result.stoppedAt).toBe("memories");+ expect(kv.listCalls).toEqual([KV.sessions, KV.memories]);+ });++ it("stops listing session observations at the session that crosses the limit", async () => {+ const kv = countingKV();+ const sdk = mockSdk();+ registerExportImportFunction(sdk as never, kv as never);+ seedSessions(kv, 10, 6 * MIB);+ kv.seed(KV.graphNodes, "n_1", { id: "n_1" });++ const result = (await sdk.trigger({ function_id: "mem::export", payload: {} })) as {+ oversized: boolean;+ stoppedAt: string;+ bytes: number;+ };++ expect(result.oversized).toBe(true);+ expect(result.stoppedAt).toBe("observations");+ const obsLists = kv.listCalls.filter((s) => s.startsWith("mem:obs:"));+ expect(obsLists).toHaveLength(3);+ expect(kv.listCalls).not.toContain(KV.graphNodes);+ expect(result.bytes).toBeGreaterThan(SAFE_PAYLOAD_BYTES);+ expect(result.bytes).toBeLessThan(19 * MIB);+ });++ it("never lists later collections once the graph exceeds the limit", async () => {+ const kv = countingKV();+ const sdk = mockSdk();+ registerExportImportFunction(sdk as never, kv as never);+ for (let i = 0; i < 20; i++) {+ kv.seed(KV.graphNodes, `n_${i}`, { id: `n_${i}`, name: "g".repeat(MIB) });+ }++ const result = (await sdk.trigger({ function_id: "mem::export", payload: {} })) as {+ stoppedAt: string;+ };++ expect(result.stoppedAt).toBe("graphNodes");+ expect(kv.listCalls).not.toContain(KV.graphEdges);+ expect(kv.listCalls).not.toContain(KV.lessons);+ });++ it("still pages sessions with maxSessions so a narrowed export fits", async () => {+ const kv = countingKV();+ const sdk = mockSdk();+ registerExportImportFunction(sdk as never, kv as never);+ seedSessions(kv, 10, 6 * MIB);++ const result = (await sdk.trigger({+ function_id: "mem::export",+ payload: { maxSessions: 2, offset: 4 },+ })) as {+ sessions: Array<{ id: string }>;+ observations: Record<string, unknown[]>;+ pagination: { offset: number; limit: number; total: number; hasMore: boolean };+ };++ expect(result.sessions.map((s) => s.id)).toEqual(["ses_4", "ses_5"]);+ expect(Object.keys(result.observations)).toEqual(["ses_4", "ses_5"]);+ expect(result.pagination).toEqual({ offset: 4, limit: 2, total: 10, hasMore: true });+ });++ it("returns 413 through the REST endpoint without assembling the rest", async () => {+ const kv = countingKV();+ const sdk = mockSdk();+ registerExportImportFunction(sdk as never, kv as never);+ registerApiTriggers(sdk as never, kv as never, BEARER);+ seedSessions(kv, 10, 6 * MIB);++ const resp = (await sdk.fns.get("api::export")!({+ headers: { authorization: `Bearer ${BEARER}` },+ query_params: {},+ })) as { status_code: number; body: { oversized?: boolean } };++ expect(resp.status_code).toBe(413);+ expect(resp.body.oversized).toBe(true);+ expect(kv.listCalls.filter((s) => s.startsWith("mem:obs:"))).toHaveLength(3);+ });+});++describe("ExportBudget", () => {+ it("tracks a collection's serialized size to within its framing", () => {+ const items = [{ a: 1 }, { b: "two" }, { c: [3, 4] }];+ const budget = new ExportBudget();+ expect(budget.fits(items, "things")).toBe(true);+ const exact = payloadByteLength({ things: items });+ expect(budget.bytes).toBeGreaterThanOrEqual(exact - 2);+ });++ it("reports false as soon as the limit is crossed", () => {+ const budget = new ExportBudget(100);+ expect(budget.fits(["x".repeat(40)])).toBe(true);+ expect(budget.fits(["x".repeat(80)])).toBe(false);+ });+});diff --git a/test/governance.test.ts b/test/governance.test.tsindex 76334ee3..43c622aa 100644--- a/test/governance.test.ts+++ b/test/governance.test.ts@@ -256,3 +256,142 @@ describe("Governance Functions", () => {expect(entries[0].functionId).toBe("mem::governance-delete");});});++describe("governance deletes count only what was really deleted (#1427, #1428)", () => {+ let sdk: ReturnType<typeof mockSdk>;+ let kv: ReturnType<typeof mockKV>;++ beforeEach(async () => {+ sdk = mockSdk();+ kv = mockKV();+ registerGovernanceFunction(sdk as never, kv as never);+ await kv.set("mem:memories", "mem_1", { ...makeMemory("mem_1", "pattern"), project: "alpha" });+ await kv.set("mem:memories", "mem_2", { ...makeMemory("mem_2", "pattern"), project: "beta" });+ });++ async function auditRows() {+ const { entries } = (await sdk.trigger("mem::audit-query", {})) as {+ entries: AuditEntry[];+ };+ return entries;+ }++ it("governance-delete writes no audit row when no id existed", async () => {+ const result = (await sdk.trigger("mem::governance-delete", {+ memoryIds: ["missing_1"],+ })) as { deleted: number; notFound: string[] };++ expect(result.deleted).toBe(0);+ expect(result.notFound).toEqual(["missing_1"]);+ expect(await auditRows()).toHaveLength(0);+ });++ it("governance-delete audits only the ids it deleted", async () => {+ const result = (await sdk.trigger("mem::governance-delete", {+ memoryIds: ["mem_1", "missing_1"],+ })) as { deleted: number; notFound: string[]; failed: number };++ expect(result.deleted).toBe(1);+ expect(result.notFound).toEqual(["missing_1"]);+ expect(result.failed).toBe(0);+ const rows = await auditRows();+ expect(rows).toHaveLength(1);+ expect(rows[0].targetIds).toEqual(["mem_1"]);+ });++ it("governance-delete reports a failed delete separately", async () => {+ const realDelete = kv.delete;+ kv.delete = async (scope: string, key: string) => {+ if (key === "mem_2") throw new Error("disk full");+ return realDelete(scope, key);+ };++ const result = (await sdk.trigger("mem::governance-delete", {+ memoryIds: ["mem_1", "mem_2"],+ })) as { success: boolean; deleted: number; failed: number };++ expect(result.success).toBe(false);+ expect(result.deleted).toBe(1);+ expect(result.failed).toBe(1);+ expect((await auditRows())[0].targetIds).toEqual(["mem_1"]);+ });++ it("governance-bulk dry run applies the same project filter as the live call", async () => {+ const dry = (await sdk.trigger("mem::governance-bulk", {+ project: "alpha",+ dryRun: true,+ })) as { wouldDelete: number; ids: string[] };+ expect(dry.wouldDelete).toBe(1);+ expect(dry.ids).toEqual(["mem_1"]);++ const live = (await sdk.trigger("mem::governance-bulk", {+ project: "alpha",+ })) as { success: boolean; deleted: number };+ expect(live.success).toBe(true);+ expect(live.deleted).toBe(1);+ const remaining = await kv.list<Memory>("mem:memories");+ expect(remaining.map((m) => m.id)).toEqual(["mem_2"]);+ });++ it("governance-bulk rejects an empty filter in dry run and live alike", async () => {+ for (const body of [{ dryRun: true }, {}]) {+ const result = (await sdk.trigger("mem::governance-bulk", body)) as {+ success: boolean;+ error: string;+ };+ expect(result.success).toBe(false);+ expect(result.error).toContain("At least one filter");+ }+ expect(await kv.list("mem:memories")).toHaveLength(2);+ });++ it("governance-bulk rejects an empty or non-string project in dry run and live alike", async () => {+ for (const body of [+ { project: "", type: ["pattern"], dryRun: true },+ { project: " ", type: ["pattern"] },+ { project: 42, type: ["pattern"] },+ ]) {+ const result = (await sdk.trigger("mem::governance-bulk", body)) as {+ success: boolean;+ error: string;+ };+ expect(result.success).toBe(false);+ expect(result.error).toContain("project must be a non-empty string");+ }+ expect(await kv.list("mem:memories")).toHaveLength(2);+ });++ it("governance-bulk rejects unsupported filter keys in dry run and live alike", async () => {+ for (const body of [+ { ids: ["mem_1"], dryRun: true },+ { ids: ["mem_1"] },+ { concepts: ["test"], type: ["pattern"], dryRun: true },+ ]) {+ const result = (await sdk.trigger("mem::governance-bulk", body)) as {+ success: boolean;+ error: string;+ };+ expect(result.success).toBe(false);+ expect(result.error).toContain("Unsupported bulk delete filter");+ }+ expect(await kv.list("mem:memories")).toHaveLength(2);+ });++ it("governance-bulk does not count or audit a candidate that vanished before delete", async () => {+ const realGet = kv.get;+ kv.get = async <T>(scope: string, key: string): Promise<T | null> => {+ if (key === "mem_2") return null;+ return realGet<T>(scope, key);+ };++ const result = (await sdk.trigger("mem::governance-bulk", {+ type: ["pattern"],+ })) as { deleted: number; notFound: string[] };++ expect(result.deleted).toBe(1);+ expect(result.notFound).toEqual(["mem_2"]);+ const rows = await auditRows();+ expect(rows).toHaveLength(1);+ expect(rows[0].targetIds).toEqual(["mem_1"]);+ });+});diff --git a/test/provider-notice-once.test.ts b/test/provider-notice-once.test.tsnew file mode 100644index 00000000..68851b55--- /dev/null+++ b/test/provider-notice-once.test.ts@@ -0,0 +1,48 @@+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";+import { mkdtempSync } from "node:fs";+import { tmpdir } from "node:os";+import { join } from "node:path";++const fakeHome = mkdtempSync(join(tmpdir(), "agentmemory-notice-"));++vi.mock("node:os", async (importOriginal) => {+ const actual = await importOriginal<typeof import("node:os")>();+ return { ...actual, homedir: () => fakeHome };+});++const PROVIDER_ENV = /(API_KEY|_KEY$|_TOKEN$|PROVIDER|_BASE_URL$|^AGENTMEMORY_ALLOW_AGENT_SDK$|^OLLAMA)/;++describe("zero-LLM provider notice", () => {+ const saved: Record<string, string | undefined> = {};++ beforeEach(() => {+ vi.resetModules();+ for (const key of Object.keys(process.env)) {+ if (PROVIDER_ENV.test(key)) {+ saved[key] = process.env[key];+ delete process.env[key];+ }+ }+ });++ afterEach(() => {+ for (const [key, value] of Object.entries(saved)) {+ if (value !== undefined) process.env[key] = value;+ }+ vi.restoreAllMocks();+ });++ it("is printed once per process however often the config is loaded", async () => {+ const write = vi.spyOn(process.stderr, "write").mockImplementation(() => true);+ const { loadConfig } = await import("../src/config.js");++ for (let i = 0; i < 4; i++) {+ expect(loadConfig().provider.provider).toBe("noop");+ }++ const notices = write.mock.calls.filter((call) =>+ String(call[0]).includes("No LLM provider key set"),+ );+ expect(notices).toHaveLength(1);+ });+});diff --git a/test/remember-forget-audit.test.ts b/test/remember-forget-audit.test.tsindex f87ae474..e8fc5a4c 100644--- a/test/remember-forget-audit.test.ts+++ b/test/remember-forget-audit.test.ts@@ -8,6 +8,9 @@ vi.mock("../src/state/keyed-mutex.js", () => ({withKeyedLock: <T>(_key: string, fn: () => Promise<T>) => fn(),}));+const decrementImageRef = vi.fn(async () => {});+vi.mock("../src/functions/image-refs.js", () => ({ decrementImageRef }));+import { registerRememberFunction } from "../src/functions/remember.js";import {getSearchIndex,@@ -138,7 +141,12 @@ describe("mem::forget audit coverage (issue #125)", () => {payload: { memoryId: "lsn_4f9cb07017a7c8ac" },});- expect(result).toEqual({ success: true, deleted: 0 });+ expect(result).toMatchObject({+ success: true,+ deleted: 0,+ notFound: ["lsn_4f9cb07017a7c8ac"],+ failed: 0,+ });// No-op path must not touch the memories keyspace or search index.expect(deleteSpy).not.toHaveBeenCalled();expect(getSearchIndex().has("lsn_4f9cb07017a7c8ac")).toBe(false);@@ -227,6 +235,27 @@ describe("mem::forget search-index cleanup", () => {expect(getSearchIndex().has("obs_b")).toBe(true);});+ it("still unindexes and flushes an observation whose image cleanup fails", async () => {+ const sdk = mockSdk();+ const kv = mockKV();+ registerRememberFunction(sdk as never, kv as never);+ const persistence = { scheduleSave: vi.fn(), save: vi.fn(async () => {}) };+ setIndexPersistence(persistence);+ decrementImageRef.mockRejectedValueOnce(new Error("image store down"));++ await kv.set("mem:obs:ses_1", "obs_img", { id: "obs_img", imageRef: "img_1" });+ getSearchIndex().add(memoryToObservation(makeMemory("obs_img")));++ await sdk.trigger({+ function_id: "mem::forget",+ payload: { sessionId: "ses_1", observationIds: ["obs_img"] },+ });++ expect(await kv.get("mem:obs:ses_1", "obs_img")).toBeNull();+ expect(getSearchIndex().has("obs_img")).toBe(false);+ expect(persistence.save).toHaveBeenCalled();+ });+it("flushes persistence immediately when a memory is forgotten", async () => {const sdk = mockSdk();const kv = mockKV();@@ -244,3 +273,117 @@ describe("mem::forget search-index cleanup", () => {expect(persistence.save).toHaveBeenCalled();});});++describe("mem::forget counts only records that were really deleted (#1428)", () => {+ type ForgetResult = {+ success: boolean;+ deleted: number;+ notFound: string[];+ failed: number;+ failures?: Array<{ id: string; error: string }>;+ };++ it("reports nothing and writes no audit row for an absent session", async () => {+ const sdk = mockSdk();+ const kv = mockKV();+ registerRememberFunction(sdk as never, kv as never);++ const result = (await sdk.trigger({+ function_id: "mem::forget",+ payload: { sessionId: "sess_ABSENT" },+ })) as ForgetResult;++ expect(result.success).toBe(true);+ expect(result.deleted).toBe(0);+ expect(result.notFound).toEqual(["sess_ABSENT"]);+ expect(result.failed).toBe(0);+ expect(await kv.list(currentAuditScope())).toHaveLength(0);+ });++ it("reports nothing and writes no audit row for absent observation ids", async () => {+ const sdk = mockSdk();+ const kv = mockKV();+ registerRememberFunction(sdk as never, kv as never);++ const result = (await sdk.trigger({+ function_id: "mem::forget",+ payload: { sessionId: "sess_ABSENT", observationIds: ["obs_ABSENT"] },+ })) as ForgetResult;++ expect(result.deleted).toBe(0);+ expect(result.notFound).toEqual(["obs_ABSENT"]);+ expect(await kv.list(currentAuditScope())).toHaveLength(0);+ });++ it("audits only the observation ids that existed", async () => {+ const sdk = mockSdk();+ const kv = mockKV();+ registerRememberFunction(sdk as never, kv as never);+ await kv.set("mem:obs:sess_1", "obs_a", { id: "obs_a" });++ const result = (await sdk.trigger({+ function_id: "mem::forget",+ payload: { sessionId: "sess_1", observationIds: ["obs_a", "obs_missing"] },+ })) as ForgetResult;++ expect(result.deleted).toBe(1);+ expect(result.notFound).toEqual(["obs_missing"]);+ const rows = await kv.list<{+ targetIds: string[];+ details: Record<string, unknown>;+ }>(currentAuditScope());+ expect(rows).toHaveLength(1);+ expect(rows[0].targetIds).toEqual(["obs_a"]);+ expect(rows[0].details.observationsDeleted).toBe(1);+ expect(rows[0].details.notFound).toBe(1);+ });++ it("does not count a missing summary for an existing session", async () => {+ const sdk = mockSdk();+ const kv = mockKV();+ registerRememberFunction(sdk as never, kv as never);+ await kv.set("mem:sessions", "sess_1", { id: "sess_1", project: "p" });++ const result = (await sdk.trigger({+ function_id: "mem::forget",+ payload: { sessionId: "sess_1" },+ })) as ForgetResult;++ expect(result.deleted).toBe(1);+ const rows = await kv.list<{ details: Record<string, unknown> }>(+ currentAuditScope(),+ );+ expect(rows[0].details.sessionDeleted).toBe(true);+ expect(rows[0].details.summaryDeleted).toBe(false);+ });++ it("reports a failed delete separately and keeps it out of the deleted count", async () => {+ const sdk = mockSdk();+ const kv = mockKV();+ registerRememberFunction(sdk as never, kv as never);+ await kv.set("mem:obs:sess_1", "obs_a", { id: "obs_a" });+ await kv.set("mem:obs:sess_1", "obs_b", { id: "obs_b" });+ const realDelete = kv.delete;+ kv.delete = async (scope: string, key: string) => {+ if (key === "obs_b") throw new Error("disk full");+ return realDelete(scope, key);+ };++ const result = (await sdk.trigger({+ function_id: "mem::forget",+ payload: { sessionId: "sess_1", observationIds: ["obs_a", "obs_b"] },+ })) as ForgetResult;++ expect(result.success).toBe(false);+ expect(result.deleted).toBe(1);+ expect(result.failed).toBe(1);+ expect(result.failures).toEqual([{ id: "obs_b", error: "delete_failed" }]);+ const rows = await kv.list<{+ targetIds: string[];+ details: Record<string, unknown>;+ }>(currentAuditScope());+ expect(rows).toHaveLength(1);+ expect(rows[0].targetIds).toEqual(["obs_a"]);+ expect(rows[0].details.failed).toBe(1);+ });+});diff --git a/test/status-rebuild-overlap.test.ts b/test/status-rebuild-overlap.test.tsnew file mode 100644index 00000000..4f332b3f--- /dev/null+++ b/test/status-rebuild-overlap.test.ts@@ -0,0 +1,102 @@+import { describe, it, expect, vi } from "vitest";++vi.mock("../src/logger.js", () => ({+ logger: { info: vi.fn(), warn: vi.fn(), error: vi.fn() },+}));++import { createStatusReporter } from "../src/triggers/api.js";+import {+ getSearchIndex,+ markKeywordRebuildPending,+ rebuildKeywordIndex,+} from "../src/functions/search.js";+import { KV } from "../src/state/schema.js";++function storeKV() {+ const store = new Map<string, Map<string, unknown>>();+ const listCalls: string[] = [];+ return {+ backend: "file" as const,+ listCalls,+ seed(scope: string, key: string, value: unknown) {+ if (!store.has(scope)) store.set(scope, new Map());+ store.get(scope)!.set(key, value);+ },+ get: async <T>(scope: string, key: string): Promise<T | null> =>+ (store.get(scope)?.get(key) as T) ?? null,+ set: async <T>(_scope: string, _key: string, data: T): Promise<T> => data,+ delete: async (): Promise<void> => {},+ list: async <T>(scope: string): Promise<T[]> => {+ listCalls.push(scope);+ return Array.from(store.get(scope)?.values() ?? []) as T[];+ },+ };+}++const sdk = { trigger: async () => null };++function seedStore() {+ const kv = storeKV();+ kv.seed(KV.sessions, "ses_1", {+ id: "ses_1",+ project: "p",+ startedAt: "2026-09-30T00:00:00Z",+ observationCount: 3,+ });+ for (let i = 0; i < 3; i++) {+ kv.seed(KV.observations("ses_1"), `obs_${i}`, {+ id: `obs_${i}`,+ sessionId: "ses_1",+ title: `title ${i}`,+ narrative: `narrative ${i}`,+ type: "decision",+ facts: [],+ concepts: [],+ files: [],+ importance: 5,+ timestamp: "2026-09-30T00:00:00Z",+ });+ }+ return kv;+}++function codes(report: { problems: Array<{ code: string }> }): string[] {+ return report.problems.map((p) => p.code);+}++describe("status while the boot keyword rebuild runs", () => {+ it("does not report missing observations before the rebuild finishes", async () => {+ getSearchIndex().clear();+ const kv = seedStore();+ markKeywordRebuildPending();+ const statusReport = createStatusReporter(sdk as never, kv as never, {});++ const during = await statusReport({ health: null, scanMaxAgeMs: 30_000 });+ expect(during.index.missingObservations).toBeNull();+ expect(codes(during)).toContain("keyword-index-rebuilding");+ expect(codes(during)).not.toContain("index-missing-observations");+ expect(codes(during)).not.toContain("index-check-unavailable");+ expect(kv.listCalls).not.toContain(KV.sessions);++ await rebuildKeywordIndex(kv as never);++ const after = await statusReport({ health: null, scanMaxAgeMs: 30_000 });+ expect(after.index.missingObservations).toBe(0);+ expect(codes(after)).not.toContain("keyword-index-rebuilding");+ expect(codes(after)).not.toContain("index-missing-observations");+ });++ it("drops a cached scan taken before a rebuild completed", async () => {+ getSearchIndex().clear();+ const kv = seedStore();+ const statusReport = createStatusReporter(sdk as never, kv as never, {});++ const before = await statusReport({ health: null, scanMaxAgeMs: 30_000 });+ expect(before.index.missingObservations).toBe(3);++ await rebuildKeywordIndex(kv as never);++ const after = await statusReport({ health: null, scanMaxAgeMs: 30_000 });+ expect(after.index.missingObservations).toBe(0);+ });+});diff --git a/test/status.test.ts b/test/status.test.tsindex 7e621de5..c3ed308e 100644--- a/test/status.test.ts+++ b/test/status.test.ts@@ -50,6 +50,14 @@ function codes(report: ReturnType<typeof evaluateStatus>): string[] {}describe("evaluateStatus", () => {+ it("holds the missing-observations warning while the keyword index rebuilds", () => {+ const report = evaluateStatus(+ inputs({ index: { ...inputs().index, missingObservations: 7, keywordRebuildRunning: true } }),+ );+ expect(codes(report)).not.toContain("index-missing-observations");+ expect(codes(report)).toContain("keyword-index-rebuilding");+ });+it("reports ok with no problems on a healthy install", () => {const report = evaluateStatus(inputs());expect(report.status).toBe("ok");