@eleboucher/opencode-memini 0.6.8 → 0.6.10

package/README.md

@@ -53,12 +53,23 @@ Pass options inline via the `[name, options]` form:
 | `recall_limit`      | `MEMINI_RECALL_LIMIT`            | `3`                     | max memories injected per turn                                                                                                         |
 | `recall_max_tokens` | `MEMINI_INJECT_RECALL_MAX_TOK`   | `0`                     | hard ceiling on the recall-block tokens (`0` = unbounded); the tail is dropped with a `[… N item(s) truncated by token budget]` footer |
 | `recall_min_score`  | `MEMINI_INJECT_RECALL_MIN_SCORE` | `0`                     | fused-score floor (>=) sent as `min_score` to `/v1/search`                                                                             |
-| `timeout_ms`        | `MEMINI_TIMEOUT_MS`              | `30000`                 | per-request timeout                                                                                                                    |
+| `recall_budget_ms`  | `MEMINI_RECALL_BUDGET_MS`        | `2000`                  | how long a turn waits for recall before proceeding without it (`0` = wait for the full `timeout_ms`)                                   |
+| `timeout_ms`        | `MEMINI_TIMEOUT_MS`              | `30000`                 | per-request timeout (recall past its budget keeps running in the background under this bound)                                          |
 | `fallback_on_error` | `MEMINI_FALLBACK`                | on                      | `false` surfaces errors instead of degrading silently                                                                                  |
-| —                   | `MEMINI_INJECT_LABELS`           | —                       | comma-separated label toggles for each bullet: `tier`, `confidence`, `age`                                                             |
+| —                   | `MEMINI_INJECT_LABELS`           | —                       | comma-separated label toggles for each bullet: `tier`, `confidence`, `age`, `reason`                                                   |
 | —                   | `MEMINI_API_KEY`                 | —                       | bearer token, if memini needs auth (env only — secret; alias: `MEMINI_TOKEN`)                                                          |
 | —                   | `MEMINI_REQUIRE_HTTPS`           | —                       | `1` refuses to send the token over plaintext HTTP                                                                                      |
 
+opencode awaits `chat.message` before the model sees the message, so a slow or
+unreachable memini would otherwise freeze the turn for the full `timeout_ms`.
+Instead, recall races `recall_budget_ms`: if the search hasn't answered in time,
+the turn proceeds without memories and the search keeps running in the
+background — results that arrive late are injected on the session's next
+message instead of being dropped. The plugin also pings `/healthz` once at
+startup to warm the connection, so the first recall doesn't pay the
+DNS/TLS cold-start. Set `recall_budget_ms: 0` to restore fully blocking
+same-turn injection.
+
 Inline options win over the env vars. Secrets stay in the environment: set
 `MEMINI_API_KEY` (sent as `Authorization: Bearer …`), and optionally
 `MEMINI_REQUIRE_HTTPS=1` to refuse plaintext HTTP, in the shell that launches
@@ -71,6 +82,44 @@ stays correct even against a remote memini (the HTTP MCP wire below can't — a
 remote server has no access to your cwd). Set it to share one memory pool with
 your other agents.
 
+If `$XDG_CONFIG_HOME/memini/config.json` (default `~/.config/memini/config.json`)
+exists, the unset namespace is instead rendered from its `template` (default
+`{tenant}/{project}/{agent}`): `{tenant}` from the `tenantRoots` entry whose
+`path` contains the cwd, `{project}` from the git repo, `{agent}` from
+`MEMINI_AGENT`; unresolved segments are dropped. The Hermes and Pi integrations
+share this resolver, so one config file scopes them all identically.
+
+### Namespace resolution
+
+In full, in order: a **per-project override** in
+`$XDG_CONFIG_HOME/memini/overrides.json` > the `namespace` option /
+`MEMINI_NAMESPACE` > the config template above > the git worktree basename.
+
+The override wins over both deliberately. A globally exported `MEMINI_NAMESPACE`
+— a shell rc, or a fish universal variable — pins every repo on the machine to
+one namespace (as does a `namespace` option in a global
+`~/.config/opencode/opencode.json`), and if either won, setting an override would
+silently do nothing on exactly the machines that need one. The file is keyed by
+git toplevel, so an override set at the top of a repo applies from any
+subdirectory; it is the same file the Claude Code plugin writes and `memini
+doctor` reads; and a malformed one degrades to automatic resolution rather than
+breaking a turn.
+
+### The `memini_status` tool
+
+The plugin registers one tool, `memini_status`: read-only, no arguments. It
+reports the namespace in force and where it came from, what it would be _without_
+the override and without the env pin, the connection settings (the API key
+fingerprinted, never printed), and warnings — a global `MEMINI_NAMESPACE` pin, a
+bearer token crossing plaintext HTTP, an override you forgot you set.
+
+There is no `/memini:status` slash command: opencode's plugin contract registers
+tools, not commands, and this plugin does not invent an API it does not have.
+Setting or clearing an override is likewise not exposed here — declaring a tool
+argument requires a zod schema, and this plugin ships dependency-free — so use
+`/memini:namespace` from the Claude Code plugin, or edit `overrides.json`
+directly; all harnesses read the same file.
+
 ### Tests
 
 ```bash

package/memini.js

@@ -17,15 +17,19 @@
  */
 
 import { execSync } from "node:child_process";
-import { readFileSync } from "node:fs";
+import { existsSync, readFileSync } from "node:fs";
 import { join, resolve, sep } from "node:path";
 import { homedir } from "node:os";
 
 const DEFAULT_BASE_URL = "http://localhost:8080";
 const DEFAULT_TIMEOUT_MS = 30000;
+const DEFAULT_RECALL_BUDGET_MS = 2000;
 const DEFAULT_RECALL_LIMIT = 3;
 const DEFAULT_NAMESPACE = "opencode";
 const LOOPBACK_HOSTS = new Set(["localhost", "127.0.0.1", "::1"]);
+// Race sentinel: distinguishes "the recall budget expired" from any value the
+// search itself could resolve to (including null on a degraded failure).
+const BUDGET_EXPIRED = Symbol("memini-recall-budget-expired");
 
 function envBool(value, fallback) {
   if (value === undefined || value === null || value === "") return fallback;
@@ -136,25 +140,112 @@ function resolveConfigNamespace(cwd) {
   return ns || null;
 }
 
+// --- Namespace override ---------------------------------------------------
+//
+// $XDG_CONFIG_HOME/memini/overrides.json (else ~/.config/memini/overrides.json)
+// holds the per-project namespace a user set deliberately. It is a shared
+// contract: the Claude Code plugin writes it, `memini doctor` reads it, and
+// every harness must agree about which namespace is in force — an override that
+// only some of them honor is worse than none at all.
+//
+// This plugin ships standalone and dependency-free from npm, so it cannot
+// import @memini/client; the reader below is the whole contract (a JSON file
+// plus a `git rev-parse`) and stays a copy, the same trade already made for
+// createPlaintextBearerAuthGuard and the injection-budget helpers. Keep the
+// contract identical when both sides change.
+
+// overridesPath resolves the overrides file. Exported for testing / status.
+export function overridesPath(env = process.env) {
+  const xdg = env.XDG_CONFIG_HOME;
+  const base = xdg && String(xdg).trim() ? String(xdg) : join(homedir(), ".config");
+  return join(base, "memini", "overrides.json");
+}
+
+// overrideKey is the key an override is stored under: the git toplevel when
+// there is one, else the resolved directory. Keying on the repo root rather
+// than the raw cwd means an override set at the top of a repo still applies
+// when the agent is working three directories down.
+export function overrideKey(cwd) {
+  const dir = cwd && String(cwd).trim() ? String(cwd) : process.cwd();
+  try {
+    const top = execSync("git rev-parse --show-toplevel", {
+      cwd: dir,
+      stdio: ["ignore", "pipe", "ignore"],
+      timeout: 500,
+    })
+      .toString()
+      .trim();
+    if (top) return resolve(top);
+  } catch {
+    // not a repo, or no git — fall through to the plain path
+  }
+  return resolve(dir);
+}
+
+// readOverride returns the override in effect for `cwd`, or null.
+//
+// The file is read BEFORE the key is computed, because the key costs a `git
+// rev-parse` and this runs on every chat.message: nobody should pay for a git
+// call to discover they have no overrides at all, which is the common case.
+// Any error — missing file, hand-edited JSON, wrong shape — degrades to "no
+// override" rather than throwing into opencode. Exported for testing.
+export function readOverride(cwd, path) {
+  let file;
+  try {
+    file = JSON.parse(readFileSync(path || overridesPath(), "utf8"));
+  } catch {
+    return null;
+  }
+  const overrides = file && typeof file === "object" ? file.overrides : null;
+  if (!overrides || typeof overrides !== "object" || Object.keys(overrides).length === 0) return null;
+  const entry = overrides[overrideKey(cwd)];
+  if (!entry || typeof entry !== "object") return null;
+  const ns = typeof entry.namespace === "string" ? entry.namespace.trim() : "";
+  if (!ns) return null;
+  return { namespace: ns, setAt: typeof entry.setAt === "string" ? entry.setAt : "" };
+}
+
 // resolveConfig merges env vars with the options object (options win), filling
 // in defaults. Exported for testing.
-export function resolveConfig(env, options, worktree) {
+//
+// Namespace precedence: project override > namespace option / MEMINI_NAMESPACE >
+// config template > git worktree > default. The override sits ABOVE the env var
+// (and above the inline option) on purpose: a globally exported MEMINI_NAMESPACE
+// — a shell rc, or a fish universal variable — pins every repo on the machine to
+// one namespace, and if the env won, setting an override would silently do
+// nothing on exactly the machines that need one. The same argument applies to a
+// `namespace` option in ~/.config/opencode/opencode.json, which pins every
+// project the same way; and `memini doctor` reports the override as in force
+// regardless, so anything else would make the two disagree.
+//
+// opts.ignoreOverride skips the override so the status tool can ask what the
+// namespace would be without it — it lives in a file, so no amount of doctoring
+// `env` would strip it. opts.overridesPath is for tests.
+export function resolveConfig(env, options, worktree, opts = {}) {
   const e = env || {};
   const o = options || {};
-  // An explicit namespace (option or MEMINI_NAMESPACE env) wins and is used
-  // raw-trimmed: the server validates the header, and flattening "/" here would
-  // split a tenant path like work/memini from the other integrations.
+  const dir = worktree || process.cwd();
+  const override = opts.ignoreOverride ? null : readOverride(dir, opts.overridesPath);
+  // An explicit namespace (option or MEMINI_NAMESPACE env) is used raw-trimmed:
+  // the server validates the header, and flattening "/" here would split a
+  // tenant path like work/memini from the other integrations. The override is
+  // written through @memini/client, which validates it, so it is used as-is too.
   const explicit = o.namespace || e.MEMINI_NAMESPACE;
   let namespace;
-  if (explicit && String(explicit).trim()) {
+  let namespace_source;
+  if (override) {
+    namespace = override.namespace;
+    namespace_source = "override";
+  } else if (explicit && String(explicit).trim()) {
     namespace = String(explicit).trim();
+    namespace_source = o.namespace ? "option" : "env";
   } else {
     // Config present -> render the config template (tenant segments already
     // sanitized, "/" preserved); otherwise fall back to the legacy cwd chain.
-    namespace =
-      resolveConfigNamespace(worktree || process.cwd()) ||
-      deriveNamespace(worktree) ||
-      DEFAULT_NAMESPACE;
+    const fromConfig = resolveConfigNamespace(dir);
+    const fromWorktree = deriveNamespace(worktree);
+    namespace = fromConfig || fromWorktree || DEFAULT_NAMESPACE;
+    namespace_source = fromConfig ? "config" : fromWorktree ? "worktree" : "default";
   }
   // Number.isFinite guard: malformed env / option falls through to the next
   // source instead of NaN flowing into the request body.
@@ -165,6 +256,17 @@ export function resolveConfig(env, options, worktree) {
     }
     return DEFAULT_RECALL_LIMIT;
   })();
+  // How long chat.message waits for recall before letting the turn proceed
+  // without it; 0 disables the race (fully blocking recall). The ""-skip
+  // matters: Number("") === 0, so an empty env var would silently go blocking.
+  const recall_budget_ms = (() => {
+    for (const v of [o.recall_budget_ms, e.MEMINI_RECALL_BUDGET_MS, DEFAULT_RECALL_BUDGET_MS]) {
+      if (v === undefined || v === null || v === "") continue;
+      const n = Number(v);
+      if (Number.isFinite(n) && n >= 0) return n;
+    }
+    return DEFAULT_RECALL_BUDGET_MS;
+  })();
   // home: the caller's personal namespace, sent as X-Memini-Home. Same
   // env-only resolution style as namespace's MEMINI_NAMESPACE (option wins
   // over env), but no config-file/derivation fallback — unset means "no home
@@ -177,6 +279,11 @@ export function resolveConfig(env, options, worktree) {
     // per-segment-sanitized config/derived value); re-sanitizing here would
     // flatten tenant "/" separators.
     namespace: namespace || DEFAULT_NAMESPACE,
+    // Where the namespace came from, and the override itself when one is in
+    // force. Carried on the config so the status tool reports what the plugin
+    // actually does rather than a second, idealized resolution of its own.
+    namespace_source,
+    override,
     home,
     recall: o.recall !== undefined ? o.recall !== false : envBool(e.MEMINI_RECALL, true),
     capture: o.capture !== undefined ? o.capture !== false : envBool(e.MEMINI_CAPTURE, true),
@@ -189,6 +296,7 @@ export function resolveConfig(env, options, worktree) {
       o.recall_min_score !== undefined
         ? Number(o.recall_min_score) || 0
         : floatEnv("MEMINI_INJECT_RECALL_MIN_SCORE", 0),
+    recall_budget_ms,
     timeout_ms: Number(o.timeout_ms || e.MEMINI_TIMEOUT_MS || DEFAULT_TIMEOUT_MS),
     fallback_on_error:
       o.fallback_on_error !== undefined
@@ -384,6 +492,190 @@ export function truncate(value, max) {
   return value;
 }
 
+// --- Status --------------------------------------------------------------
+//
+// "What is this plugin actually doing right now?" A list of values would not
+// answer that. The case worth catching is MEMINI_NAMESPACE exported globally (a
+// shell rc, or a fish universal variable), set once and forgotten, quietly
+// collapsing every repo on the machine into one namespace: the value looks
+// fine, only its provenance gives it away. So the namespace is resolved three
+// times against progressively stripped inputs — as-is, without the override,
+// and without the override AND the env/option pin — and all three are reported.
+
+/**
+ * Render a secret as a recognizable-but-useless fingerprint: enough to tell two
+ * tokens apart, not enough to use. Short values are elided entirely rather than
+ * half-revealed. Mirrors packages/memini-client's redactValue. Exported for
+ * testing.
+ */
+export function redactSecret(value) {
+  if (!value) return "";
+  return value.length <= 12 ? "***" : `${value.slice(0, 3)}…${value.slice(-4)}`;
+}
+
+/**
+ * Build the effective-settings report: the three namespace resolutions, the
+ * knobs with their provenance (secrets redacted), the paths, and the warnings.
+ * Exported for testing.
+ */
+export function describeSettings(env, options, worktree) {
+  const e = env || {};
+  const o = options || {};
+  const dir = worktree || process.cwd();
+
+  const cfg = resolveConfig(e, o, worktree);
+  // Both counterfactuals must ignore the override explicitly: it lives in a
+  // file, so a resolution handed a stripped env would hand it straight back —
+  // and these are the two lines that exist to see past it.
+  const withoutOverride = resolveConfig(e, o, worktree, { ignoreOverride: true });
+  const envSansPin = { ...e };
+  delete envSansPin.MEMINI_NAMESPACE;
+  const derived = resolveConfig(
+    envSansPin,
+    { ...o, namespace: undefined },
+    worktree,
+    { ignoreOverride: true },
+  );
+
+  const secret = e.MEMINI_API_KEY || e.MEMINI_TOKEN || "";
+  const warnings = [];
+
+  if (cfg.override) {
+    warnings.push({
+      level: "note",
+      code: "override-active",
+      message:
+        `namespace is overridden to "${cfg.override.namespace}" for this project` +
+        (cfg.override.setAt ? ` (set ${cfg.override.setAt})` : "") +
+        `; without it this project would use "${withoutOverride.namespace}".`,
+      fix: `Remove the entry for ${overrideKey(dir)} from ${overridesPath(e)} to return to automatic resolution.`,
+    });
+  }
+
+  // The finding this whole report exists for.
+  const pin = String(e.MEMINI_NAMESPACE || "").trim();
+  if (pin && !cfg.override && derived.namespace && derived.namespace !== pin) {
+    warnings.push({
+      level: "warn",
+      code: "global-namespace-pin",
+      message:
+        `MEMINI_NAMESPACE is set to "${pin}", which pins EVERY project on this machine to one ` +
+        `namespace. This project would otherwise resolve to "${derived.namespace}". If it is ` +
+        `exported from a shell rc (or a fish universal variable), every repo you work in is ` +
+        `sharing one memory pool.`,
+      fix: "Unset MEMINI_NAMESPACE and let each repo resolve on its own, or set a per-project override instead.",
+    });
+  }
+
+  if (usesPlaintextBearerAuth(cfg.base_url, secret)) {
+    warnings.push({
+      level: "warn",
+      code: "plaintext-bearer",
+      message: plaintextBearerAuthMessage(cfg.base_url),
+      fix: "Use HTTPS, or tunnel over SSH. Set MEMINI_REQUIRE_HTTPS=1 to make this an error.",
+    });
+  }
+
+  if (!cfg.home) {
+    warnings.push({
+      level: "note",
+      code: "home-unset",
+      message: "MEMINI_HOME is unset: no personal leg merges into recall.",
+      fix: "Export MEMINI_HOME=personal/<you>.",
+    });
+  }
+
+  return {
+    project: overrideKey(dir),
+    worktree: dir,
+    namespace: {
+      effective: cfg.namespace,
+      source: cfg.namespace_source,
+      override: cfg.override,
+      withoutOverride,
+      derived,
+      home: cfg.home,
+    },
+    connection: {
+      base_url: cfg.base_url,
+      api_key: secret ? redactSecret(secret) : "",
+      require_https: e.MEMINI_REQUIRE_HTTPS === "1",
+      timeout_ms: cfg.timeout_ms,
+    },
+    memory: {
+      recall: cfg.recall,
+      capture: cfg.capture,
+      recall_limit: cfg.recall_limit,
+      recall_max_tokens: cfg.recall_max_tokens,
+      recall_min_score: cfg.recall_min_score,
+      recall_budget_ms: cfg.recall_budget_ms,
+      labels: [...labelsEnv()],
+    },
+    paths: { overrides: overridesPath(e) },
+    warnings,
+  };
+}
+
+const padTo = (s, n) => String(s).padEnd(n);
+
+/** Render describeSettings() as the text block the tool hands back. */
+export function renderStatus(report) {
+  const { namespace: ns, connection, memory, paths } = report;
+  const L = [];
+
+  L.push("memini — effective settings (opencode)");
+  L.push(`project: ${report.project}`);
+  L.push("");
+
+  L.push("NAMESPACE");
+  L.push(`  ${padTo("effective", 26)} ${padTo(ns.effective, 30)} <- ${ns.source}`);
+  if (ns.override) {
+    L.push(
+      `  ${padTo("without the override", 26)} ${padTo(ns.withoutOverride.namespace, 30)} <- ${ns.withoutOverride.source}`,
+    );
+  }
+  if (ns.derived.namespace !== ns.effective) {
+    L.push(
+      `  ${padTo("git/cwd would give", 26)} ${padTo(ns.derived.namespace, 30)} <- ${ns.derived.source}`,
+    );
+  }
+  L.push(`  ${padTo("home (personal)", 26)} ${ns.home || "(unset)"}`);
+  L.push("");
+
+  L.push("CONNECTION");
+  L.push(`  ${padTo("base_url", 26)} ${connection.base_url}`);
+  L.push(`  ${padTo("api_key", 26)} ${connection.api_key || "(unset)"}`);
+  L.push(`  ${padTo("require_https", 26)} ${connection.require_https ? "1" : "0"}`);
+  L.push(`  ${padTo("timeout_ms", 26)} ${connection.timeout_ms}`);
+  L.push("");
+
+  L.push("MEMORY");
+  L.push(`  ${padTo("recall", 26)} ${memory.recall ? "on" : "off"}`);
+  L.push(`  ${padTo("capture", 26)} ${memory.capture ? "on" : "off"}`);
+  L.push(`  ${padTo("recall_limit", 26)} ${memory.recall_limit}`);
+  L.push(`  ${padTo("recall_max_tokens", 26)} ${memory.recall_max_tokens || "uncapped"}`);
+  L.push(`  ${padTo("recall_min_score", 26)} ${memory.recall_min_score}`);
+  L.push(`  ${padTo("recall_budget_ms", 26)} ${memory.recall_budget_ms === 0 ? "0 (blocking)" : memory.recall_budget_ms}`);
+  L.push(`  ${padTo("labels", 26)} ${memory.labels.length ? memory.labels.join(",") : "(none)"}`);
+  L.push("");
+
+  L.push("PATHS");
+  L.push(`  ${padTo("overrides", 26)} ${paths.overrides}${existsSync(paths.overrides) ? "" : " (absent)"}`);
+  L.push("");
+
+  if (report.warnings.length) {
+    L.push("WARNINGS");
+    for (const w of report.warnings) {
+      L.push(`  [${w.level === "warn" ? "!" : "i"}] ${w.code}: ${w.message}`);
+      if (w.fix) L.push(`      fix: ${w.fix}`);
+    }
+  } else {
+    L.push("No problems detected.");
+  }
+
+  return L.join("\n");
+}
+
 function createClient(cfg, log) {
   const baseUrl = String(cfg.base_url).replace(/\/+$/, "");
   const secret = process.env.MEMINI_API_KEY || process.env.MEMINI_TOKEN;
@@ -476,28 +768,46 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
 
   const cfg = resolveConfig(process.env, options, worktree || directory);
   const rest = createClient(cfg, log);
+  // Warm the connection (DNS/TCP/TLS) in opencode's embedded bun so a cold
+  // start doesn't eat the first recall budget. Silent: even a 404 warms the
+  // path, and an ingress that only routes /v1 legitimately has no /healthz.
+  if (cfg.recall || cfg.capture) {
+    try {
+      fetch(`${rest.baseUrl}/healthz`, { signal: AbortSignal.timeout(3000) }).catch(() => {});
+    } catch {
+      /* ignore */
+    }
+  }
   // Assistant message ids already captured, so repeated session.idle events for
   // the same turn don't write duplicates.
   const captured = new Set();
+  // boundedPut inserts key -> value and evicts the oldest entries, so a
+  // long-lived host can't grow a per-session map without limit.
+  const MAX_TRACKED_SESSIONS = 200;
+  const boundedPut = (map, key, value) => {
+    map.set(key, value);
+    while (map.size > MAX_TRACKED_SESSIONS) {
+      const oldest = map.keys().next().value;
+      if (oldest === undefined) break;
+      map.delete(oldest);
+    }
+  };
   // Memory ids each session has already been shown (mirrors the pi plugin):
   // the injected synthetic part is persisted into the session, so re-injecting
   // an unchanged match every turn stacks identical blocks in the context.
-  // Bounded so long-lived hosts can't grow the map without limit.
   const injectedBySession = new Map();
-  const MAX_TRACKED_SESSIONS = 200;
   const rememberInjected = (session, ids) => {
     let seen = injectedBySession.get(session);
     if (!seen) {
       seen = new Set();
-      injectedBySession.set(session, seen);
-      while (injectedBySession.size > MAX_TRACKED_SESSIONS) {
-        const oldest = injectedBySession.keys().next().value;
-        if (oldest === undefined) break;
-        injectedBySession.delete(oldest);
-      }
+      boundedPut(injectedBySession, session, seen);
     }
     for (const id of ids) if (id) seen.add(id);
   };
+  // Recall results that arrived after the injection budget expired, keyed by
+  // session and injected on that session's next chat.message. Latest-replace:
+  // a second late recall for the same session supersedes the first.
+  const pendingBySession = new Map();
 
   // opencode runs chat.message via an unguarded Effect.promise (a throw aborts the
   // turn) and dispatches event hooks fire-and-forget, so a hook must never reject:
@@ -511,6 +821,46 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
   };
 
   return {
+    // A tool, not a slash command, and deliberately so. opencode's plugin
+    // contract (Hooks in @opencode-ai/plugin) registers tools — `tool: { [id]:
+    // { description, args, execute } }` — but exposes no hook for registering a
+    // user-invocable command, so there is no `/memini:status` this plugin could
+    // offer without inventing one. `args` is empty: declaring a parameter means
+    // handing opencode a zod schema, and this plugin has no dependencies (a
+    // raw-JSON-Schema arg rides a compatibility path that older hosts feed
+    // straight to z.object() and throw on). A zero-arg tool is the shape every
+    // version accepts, and a read-only report needs no arguments anyway.
+    //
+    // Settings are recomputed per call rather than read off `cfg`, so an
+    // override set mid-session is visible here without restarting opencode —
+    // even though the hooks below still use the namespace they resolved at load.
+    tool: {
+      memini_status: {
+        description:
+          "Show the memini memory settings in force for this project: which namespace memories " +
+          "are written to and recalled from, where that namespace came from (a per-project " +
+          "override, MEMINI_NAMESPACE, the config file, or the git worktree), what it would be " +
+          "without each of those, and any misconfiguration worth flagging. Read-only; secrets " +
+          "are redacted. Call it when the user asks what memini is doing, why a memory cannot " +
+          "be recalled, or which namespace is in use.",
+        args: {},
+        execute: async () => {
+          try {
+            const report = describeSettings(process.env, options, worktree || directory);
+            return {
+              title: `memini: ${report.namespace.effective}`,
+              output: renderStatus(report),
+              metadata: { namespace: report.namespace.effective, source: report.namespace.source },
+            };
+          } catch (error) {
+            // A diagnostic that crashes the turn it was meant to diagnose is
+            // worse than no diagnostic.
+            return `memini status failed: ${String(error)}`;
+          }
+        },
+      },
+    },
+
     "chat.message": guard("chat.message", async (input, output) => {
       if (!cfg.recall) return;
       const query = extractPartsText(output && output.parts);
@@ -530,13 +880,58 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
       // the Claude Code plugin's pre-tool-use hook uses; client-side re-filter
       // is a belt-and-braces guard against score-normalization edge cases.
       if (cfg.recall_min_score > 0) body.min_score = cfg.recall_min_score;
-      const result = await rest.postJson("/v1/search", body);
+      // opencode awaits this hook before the model sees the message, so the
+      // turn only waits recall_budget_ms for the search; the fetch itself keeps
+      // cfg.timeout_ms as its bound and runs on in the background. A slow or
+      // unreachable memini degrades to "no memories this turn" instead of a
+      // frozen turn, and late results carry over to the session's next message.
+      const fetchPromise = rest.postJson("/v1/search", body);
+      // Once the budget expires nothing awaits this promise, and with
+      // fallback_on_error off postJson rethrows — catch here or a late
+      // rejection surfaces as an unhandled rejection in the host.
+      const settled = fetchPromise.catch((error) => {
+        log.warn(`memini: ${String(error)}`);
+        return null;
+      });
+      let result;
+      if (cfg.recall_budget_ms > 0) {
+        let timer;
+        const budget = new Promise((resolve) => {
+          timer = setTimeout(() => resolve(BUDGET_EXPIRED), cfg.recall_budget_ms);
+        });
+        result = await Promise.race([settled, budget]);
+        clearTimeout(timer);
+        if (result === BUDGET_EXPIRED) {
+          log.warn(
+            `recall exceeded its ${cfg.recall_budget_ms}ms budget; late results will inject next turn`,
+          );
+          if (sessionID) {
+            settled.then((late) => {
+              const hits = Array.isArray(late && late.results) ? late.results : [];
+              if (hits.length) boundedPut(pendingBySession, sessionID, hits);
+            });
+          }
+          result = null;
+        }
+      } else {
+        result = await settled;
+      }
       // Client-side score floor: filter the raw hit list before formatting so
       // the bullet array only contains hits the operator asked for. Without
       // this, the server's default floor could leak low-quality hits in
       // regardless of cfg.recall_min_score.
       const floor = cfg.recall_min_score > 0 ? cfg.recall_min_score : 0;
       let rawHits = Array.isArray(result && result.results) ? result.results : [];
+      // Merge in results that arrived late on a previous turn: fresh hits
+      // first (they answer the current query), deduped by memory id.
+      if (sessionID) {
+        const pending = pendingBySession.get(sessionID);
+        if (pending && pending.length) {
+          pendingBySession.delete(sessionID);
+          const fresh = new Set(rawHits.map((r) => r?.memory?.id).filter(Boolean));
+          rawHits = rawHits.concat(pending.filter((r) => !fresh.has(r?.memory?.id)));
+        }
+      }
       // Suppress memories this session has already been shown — the injected
       // part persists in the session, so a repeat adds nothing but noise.
       if (sessionID) {
@@ -555,7 +950,16 @@ export const MeminiPlugin = async ({ client, worktree, directory }, options) =>
       const fit = fitByTokens(hits, cfg.recall_max_tokens);
       if (fit.items.length === 0) return;
       if (sessionID) {
-        rememberInjected(sessionID, filtered.map((r) => r?.memory?.id).filter(Boolean));
+        // Mark only the slice formatResults actually renders: with carryover
+        // merged in, `filtered` can exceed recall_limit, and marking unshown
+        // hits as seen would suppress them forever.
+        rememberInjected(
+          sessionID,
+          filtered
+            .slice(0, cfg.recall_limit || DEFAULT_RECALL_LIMIT)
+            .map((r) => r?.memory?.id)
+            .filter(Boolean),
+        );
       }
       const lines = [
         `Relevant long-term memory from memini (background context — prefer ` +

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@eleboucher/opencode-memini",
-  "version": "0.6.8",
+  "version": "0.6.10",
   "description": "Automatic cross-session memory for opencode via memini — recall before each turn, capture after.",
   "keywords": [
     "memini",