@joe-broadhead/opencode-history 0.0.0 → 0.0.1

package/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 All notable changes to this project are documented here. The format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.0.1] - 2026-11-04
+
+### Added
+
+- OpenCode 2.2.5 is a tested host, next to 2.2.3 and 2.2.4.
+- Status shows the index file's size, as `Index file: <path> (511 MB)` and `indexBytes`, and the README says how large the index grows and how to make it smaller.
+- A mask pattern you add now applies at once to everything the tools return, `history_sql` included, not only to text indexed after it. Status shows a `Masks:` row and asks for `/history-reindex rebuild` until the index file is rewritten with the new patterns.
+- README sections on updating the plugin, and on what to run after installing it.
+
+### Changed
+
+- The status RPC (`history.sessions` `status`) uses the field names every plugin's status RPC shares:
+  - `connection` is now `state`, in machine words: `ready` (was `connected`), `connecting` and `failed`. The old `host untested` is gone: an untested host no longer changes the state, and shows in `host.tested` instead. The `/history-status` rows keep their words.
+  - `next` is now `nextStep`, always present, and `Nothing to do.` when nothing is needed.
+  - `host` is now `{ version, range, tested }`; it was `{ required, found, availability, next }`. `tested` is true only for 2.2.3, 2.2.4 and 2.2.5.
+- An OpenCode release inside `>=2.2.3 <2.3.0` that is not tested, such as 2.2.6, works as before, but status now says it is untested: `host.tested` is `false` and its OpenCode row reads `2.2.6 (untested; supported range >=2.2.3 <2.3.0)`. Before, every release in the range was called tested.
+- The tools RPC words a bad envelope as every plugin's tools RPC does, such as `"extra" is not allowed`, `"sessionID" must be a non-empty string`, `"input" is missing` and `describe takes no input`, instead of zod's messages. A call without `input` is now refused; before, it ran with `{}`.
+- `SESSION_UNKNOWN` and `SESSION_AGENT_REQUIRED` have the next step every plugin uses: create a session that names an agent and pass its id.
+- The Uninstall steps run in the same order as every plugin's: pins first, while the plugin can still remove them, then the plugin, its index, and copied rules.
+- The scripting docs say that `opencode api` runs in the service's default location, your home directory, and how to target a project, and that it exits with status 1 on an RPC error.
+
+### Fixed
+
+- A `history_sql` statement no longer keeps running after OpenCode stops. Before, a statement that never ended went on using a CPU core after OpenCode crashed or was killed. Now its process stops by itself at the 10-second limit, and as soon as OpenCode exits, crashes or reloads the plugin.
+- `QUERY_INVALID` now gives a next step that fits its cause. A short substring, a bad date or an empty path no longer gets advice about regular expressions.
+- `/history-reindex` with an unknown argument answers in the usual error format: `INPUT_INVALID: /history-reindex takes no argument or rebuild. Next step: …`.
+- `/history-reindex rebuild` now overwrites the text it drops and empties the write-ahead log, so text that only a newer mask pattern covers no longer stays in the index file's free space.
+- `history_pin` keeps the whole pin within `maxChars`. Before, its header line came on top, so `maxChars: 500` pinned about 730 characters.
+
 ## [0.0.0] - 2026-11-03
 
 ### Added

package/README.md

@@ -6,7 +6,7 @@ Unofficial; not affiliated with OpenCode.
 
 ## Requirements
 
-- OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3 and 2.2.4. On any other version the plugin does not start, unless you set [`allowUntestedHost`](https://github.com/joe-broadhead/opencode-history/blob/HEAD/docs/configuration.md#options).
+- OpenCode `>=2.2.3 <2.3.0`, tested on 2.2.3, 2.2.4 and 2.2.5. Another release inside that range starts too, and status says it is untested. Outside `>=2.2.3 <2.3.0` the plugin does not start, unless you set [`allowUntestedHost`](https://github.com/joe-broadhead/opencode-history/blob/HEAD/docs/configuration.md#options).
 - macOS or Linux.
 - Nothing else: no native programs, downloads or accounts. The index is SQLite with full-text search, through the `node:sqlite` module of OpenCode's runtime.
 
@@ -16,7 +16,16 @@ Unofficial; not affiliated with OpenCode.
 opencode plugin add @joe-broadhead/opencode-history
 ```
 
-Restart OpenCode. On first start the plugin indexes every session in OpenCode's database in the background, newest first. The tools work while it runs, over the sessions indexed so far. `/history-status`, or `/history` in the terminal UI, shows the progress.
+Run `opencode reload`, or restart OpenCode. Then run `/history-status`. On first start the plugin indexes every session in OpenCode's database in the background, newest first. The tools work while it runs, over the sessions indexed so far. `/history-status`, or `/history` in the terminal UI, shows the progress.
+
+## Update
+
+```sh
+opencode plugin update @joe-broadhead/opencode-history
+opencode reload
+```
+
+An entry pinned to a version (`@joe-broadhead/opencode-history@0.0.1`) does not update: remove the `@version` from `plugins` first. The index is kept; when a new version changes its layout, the plugin rebuilds it in the background.
 
 ## Sign in
 
@@ -60,7 +69,7 @@ The index holds prompts, replies, tool calls and their output, compaction summar
 
 ### Commands
 
-- `/history-status` posts the status into the session: the connection, index progress and how far behind it is, the source, the database and index paths, the default scope, recall answers, the tools, agents without the default rules, the OpenCode version and one Next step.
+- `/history-status` posts the status into the session: the connection, index progress and how far behind it is, the source, the database and index paths with the index's size, the default scope, recall answers, the tools, agents without the default rules, the OpenCode version and one Next step.
 - `/history-reindex` catches the index up with OpenCode's sessions. `/history-reindex rebuild` drops the index and indexes everything again.
 
 ### Status dialog
@@ -152,7 +161,9 @@ Start with `/history-status` or `history_status`. They end with one next step. E
 | `Agents without default rules: …` | Those agents run every History tool, `history_pin` included, without asking. Put the block status shows first in each agent's own `permissions`. |
 | `Index: ..., 35 s behind` | Seconds since the index was last in step with OpenCode. The next search, sessions or recall call catches up, or run `/history-reindex`. |
 | A recent session is missing | Search, sessions and recall catch up for up to about 200 ms before they answer. A longer catch-up finishes in the background, so run `/history-reindex` to wait for it. |
-| `HOST_UNTESTED` | Use OpenCode 2.2.3 or a later 2.2.x, or set `allowUntestedHost: true` and accept the warning. |
+| `HOST_UNTESTED`, `OpenCode: … (untested; …)` | The OpenCode release is not one of the tested 2.2.3, 2.2.4 and 2.2.5. Inside `>=2.2.3 <2.3.0` the plugin runs normally; outside it, it starts only with `allowUntestedHost: true`. If something fails, use a tested release. |
+| `Masks: changed since text was indexed` | You changed `mask` or `maskDefaults` after text was indexed. Results already use the new patterns, but the index file holds the old text: run `/history-reindex rebuild`. |
+| A large index file | The index takes about 2.7 times the text it holds, about 500 MB for 200,000 indexed texts, and status shows its size in the `Index file` row. It grows with your history; a deleted session leaves it, but the file keeps its size and reuses the space. To make it smaller, set `index.toolResults: false`, which leaves out tool output, or a lower `index.maxDocChars`, then delete the index file (with its `-wal` and `-shm` files) and restart OpenCode: the plugin builds a new one. |
 | `OPTIONS_INVALID` | The message names the option. Fix it in the plugin entry and restart. |
 | `SOURCE_UNAVAILABLE` | OpenCode's database stopped answering. Check that `database` points at OpenCode's `opencode.db`, then restart OpenCode. |
 | `INDEX_UNAVAILABLE` | `indexPath` must be a file the plugin can create and write. Fix it and restart. |
@@ -161,7 +172,7 @@ Start with `/history-status` or `history_status`. They end with one next step. E
 | `INDEX_FAILED` | Run `/history-status`, and if it persists, delete the index file and restart OpenCode. |
 | `INDEX_MISMATCH`, `Index schema: ...` | Another OpenCode process running another version of the plugin rebuilt the index for its own version; status shows both versions. Restart every OpenCode process so they all run one version; the index is then rebuilt for it. |
 | `SESSION_NOT_FOUND` | Find the session ID with `history_search` or `history_sessions`. |
-| `QUERY_INVALID` | Fix the regular expression or the date, or search with `match: "words"`. |
+| `QUERY_INVALID` | Fix what the message names: a substring of at least 3 characters, the regular expression, the date, the path or another filter. The next step fits the mistake. |
 | `SQL_REJECTED`, `SQL_FAILED` | Write one read-only `SELECT` or `WITH` statement, best over the `v_*` views. The message says what was wrong. |
 | `SQL_TIMEOUT` | The statement ran longer than 10 seconds and was stopped. Filter by time or session, and bound a recursive `WITH`. |
 | `PERMISSION_DENIED`, `SESSION_UNKNOWN`, `SESSION_AGENT_REQUIRED` | Scripts only: the session's agent may not use the tool, the session does not exist, or it names no agent. See [Scripting](https://github.com/joe-broadhead/opencode-history/blob/HEAD/docs/scripting.md). |
@@ -174,11 +185,15 @@ The full list of codes is in [docs/configuration.md](https://github.com/joe-broa
 
 ## Uninstall
 
-```sh
-opencode plugin remove @joe-broadhead/opencode-history
-```
+1. History has no sign-in, so there is nothing to sign out of. Remove your pins while the plugin is still installed: they are instruction entries that OpenCode keeps on the sessions where you made them, and the plugin cannot remove them once it is gone. In each such session, call `history_pin` with `"action": "list"`, then `"action": "remove"` for each one.
+2. Remove the plugin, then run `opencode reload` or restart OpenCode:
+
+   ```sh
+   opencode plugin remove @joe-broadhead/opencode-history
+   ```
 
-Removing the plugin keeps the index. To delete it, remove `~/.local/share/opencode-history` (or your `indexPath`, with its `-wal` and `-shm` files). OpenCode's database is not touched either way. Pins are instruction entries that OpenCode keeps on the sessions where you made them; the plugin does not remove them when it is uninstalled, so remove them first with `history_pin` and `"action": "remove"`. Rules you added to `permissions` stay until you remove them.
+3. Delete the index, which removing the plugin keeps: `~/.local/share/opencode-history`, or your `indexPath` with its `-wal` and `-shm` files. OpenCode's database is not touched either way.
+4. Remove the `history_*` rules you copied into `permissions` or into an agent's own permissions.
 
 ## Links
 

package/dist/index.js

@@ -2243,14 +2243,14 @@ var $ZodNever = /* @__PURE__ */ $constructor("$ZodNever", (inst, def) => {
     return payload;
   };
 });
-function capSize(inst, size) {
+function capSize(inst, size2) {
   const caps = sizeCaps(inst._zod.def.checks);
   if (!caps.length)
     return;
   const cap = Math.min(...caps.map((c) => c[0]));
   const parse5 = inst._zod.parse;
   inst._zod.parse = (payload, ctx) => {
-    const n = size(payload.value);
+    const n = size2(payload.value);
     if (n > cap && !ctx?.skipChecks && ctx?.direction !== "backward") {
       for (const [max, ch] of sizeCaps(inst._zod.def.checks)) {
         if (n > max && ch._zod.def.when(payload)) {
@@ -6443,7 +6443,7 @@ var FAILURES = {
   SESSION_NOT_FOUND: ["No indexed session has that ID.", "Find the session ID with history_search or history_sessions."],
   MESSAGE_NOT_FOUND: ["That session has no message at that position.", "Call history_read without `at` to see the session's message range."],
   CURSOR_INVALID: ["The cursor is invalid or has expired.", "Repeat the call without cursor."],
-  QUERY_INVALID: ["The search query cannot be used.", 'Check the regular expression, or search with match: "words".'],
+  QUERY_INVALID: ["The search query cannot be used.", "Correct the named input and call the tool again."],
   SQL_REJECTED: ["Only one read-only SELECT or WITH statement over the history index is allowed.", "Rewrite it as a single SELECT over the v_sessions, v_docs, v_files and v_links views."],
   SQL_FAILED: ["The SQL query failed.", "Check the view and column names in the history_sql description, then retry."],
   SQL_TIMEOUT: [`The SQL query ran longer than 10 seconds and was stopped.`, "Narrow it: filter by time or session, and bound a recursive WITH with a LIMIT or a WHERE on its counter."],
@@ -6452,8 +6452,8 @@ var FAILURES = {
   PIN_TOO_LARGE: ["The text to pin is larger than OpenCode allows for one instruction entry.", "Pin a shorter range, or set a lower maxChars."],
   EVENTS_UNAVAILABLE: ["OpenCode's session events stopped, so the index may lag behind new sessions.", "Wait, since the plugin subscribes again by itself, and restart OpenCode if it persists."],
   PERMISSION_DENIED: ["The session's agent may not use this tool.", "Add an allow rule for the tool's action to that agent, or call as a session whose agent allows it."],
-  SESSION_UNKNOWN: ["OpenCode has no session with that ID.", "Pass the ID of an existing session as sessionID."],
-  SESSION_AGENT_REQUIRED: ["That session names no agent, so there are no rules to run the tool under.", "Call as a session that names an agent."],
+  SESSION_UNKNOWN: ["OpenCode has no session with that ID.", 'Create a session that names an agent, such as POST /api/session with {"agent":"build"}, and pass its id.'],
+  SESSION_AGENT_REQUIRED: ["That session names no agent, so there are no rules to run the tool under.", 'Create a session that names an agent, such as POST /api/session with {"agent":"build"}, and pass its id.'],
   OPERATION_FAILED: ["The tool failed unexpectedly.", "Retry, and if it persists, call history_status."]
 };
 var formatFailure = (failure2) => `${failure2.code}: ${failure2.message}${failure2.hint ? ` Next step: ${failure2.hint}` : ""}`;
@@ -7137,20 +7137,22 @@ var INDEX = object(
 );
 var STATUS_OUTPUT = object({
   version: string3,
-  host: object({ required: string3, found: string3, availability: choice(["AVAILABLE", "HOST_UNTESTED"]), next: string3 }, ["required", "found", "availability"]),
-  connection: choice(["connected", "connecting", "failed", "host untested"]),
+  host: object({ version: nullable2(string3), range: string3, tested: boolean3 }, ["version", "range", "tested"]),
+  state: choice(["ready", "connecting", "failed"]),
   index: INDEX,
   fallback: choice(["SOURCE_UNAVAILABLE", "SOURCE_SCHEMA_UNKNOWN"]),
   tools: object({ visible: integer3, unknown: list(string3) }, ["visible", "unknown"]),
   database: string3,
   indexPath: string3,
+  indexBytes: nullable2(integer3),
+  masksChanged: boolean3,
   defaultScope: choice(["project", "directory", "all"]),
   recall: object({ synthesize: boolean3, model: nullable2(string3) }, ["synthesize", "model"]),
   unguardedAgents: list(string3),
   permissionsBlock: list(object({ action: string3, resource: string3, effect: choice(["allow", "deny", "ask"]) }, ["action", "resource", "effect"])),
   mismatch: object({ file: nullable2(string3), build: string3 }, ["file", "build"]),
-  next: string3
-}, ["version", "host", "connection", "index", "tools", "database", "indexPath", "defaultScope", "recall", "unguardedAgents"]);
+  nextStep: string3
+}, ["version", "host", "state", "index", "tools", "database", "indexPath", "indexBytes", "masksChanged", "defaultScope", "recall", "unguardedAgents", "nextStep"]);
 var errors = { failed: object({ code: string3, next: string3 }, ["code", "next"]) };
 var History = Rpc.define({
   id: PLUGIN_ID,
@@ -7161,7 +7163,7 @@ var History = Rpc.define({
 });
 
 // src/version.ts
-var VERSION = true ? "0.0.0" : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
+var VERSION = true ? "0.0.1" : JSON.parse(readFileSync(new URL("../package.json", import.meta.url), "utf8")).version;
 
 // src/host/errors.ts
 import { Error as ToolError } from "@opencode/plugin/promise/tool";
@@ -7405,28 +7407,44 @@ function agentsRow(view, compact) {
 var ACCOUNT_TEXT = "none; History needs no sign-in";
 var ACCESS_TEXT = "reads OpenCode's database read-only and writes only its own index; history_pin asks before it changes a session";
 var FALLBACK_TEXT = { SOURCE_UNAVAILABLE: "OpenCode's database could not be read", SOURCE_SCHEMA_UNKNOWN: "OpenCode's database has an unknown layout" };
+var CONNECTION_WORDS = { ready: "connected", connecting: "connecting", failed: "failed" };
+var MASKS_ROW = "Masks:";
+function size(bytes) {
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let value = bytes, unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${unit === 0 || value >= 10 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`;
+}
+function hostText({ host, version: version2 }) {
+  const note = host.tested ? "tested" : `untested; supported range ${host.range}`;
+  return `${host.version ?? "unknown version"} (${note}). History ${version2}`;
+}
 function toolsText({ tools }) {
   const unknown2 = tools.unknown.length ? `, ${tools.unknown.length} unknown (they ask first): ${tools.unknown.join(", ")}` : "";
   return `${tools.visible} available${unknown2}`;
 }
 function formatStatus(view, options = {}) {
-  const { index, host, mismatch } = view;
+  const { index, mismatch } = view;
   return lines2(
     "History status",
-    `Connection: ${view.connection}`,
+    `Connection: ${CONNECTION_WORDS[view.state]}`,
     `Account: ${ACCOUNT_TEXT}`,
     `Access: ${ACCESS_TEXT}`,
     `Index: ${index.ready ? "ready" : "building"}, ${index.sessionsIndexed} of ${index.sessionsTotal} sessions${index.lagSeconds ? `, ${Math.round(index.lagSeconds)} s behind` : ""}`,
     `Source: ${SOURCE_TEXT[index.source]}${index.complete ? "" : ", incomplete"}${view.fallback ? ` (${FALLBACK_TEXT[view.fallback]})` : ""}`,
     `Database: ${view.database}`,
-    `Index file: ${view.indexPath}`,
+    `Index file: ${view.indexPath}${view.indexBytes === null ? "" : ` (${size(view.indexBytes)})`}`,
+    view.masksChanged ? `${MASKS_ROW} changed since text was indexed, so the index file holds that text masked the old way until /history-reindex rebuild` : void 0,
     mismatch ? `${MISMATCH_ROW} ${mismatch.file === null ? "none" : `version ${mismatch.file}`} in the file, but this build uses version ${mismatch.build}, so every query fails (INDEX_MISMATCH)` : void 0,
     `Default scope: ${view.defaultScope}`,
     `Recall answers: ${view.recall.synthesize ? "on" : "off"}${view.recall.model ? ` (${view.recall.model})` : " (default model)"}`,
     `Tools: ${toolsText(view)}`,
     agentsRow(view, options.compact ?? false),
-    `OpenCode: ${host.found} (${host.availability === "AVAILABLE" ? "tested" : `host untested: tested on ${host.required}`}). History ${view.version}`,
-    `Next step: ${view.next ?? NOTHING_TO_DO}`
+    `OpenCode: ${hostText(view)}`,
+    `Next step: ${view.nextStep}`
   );
 }
 
@@ -7464,7 +7482,7 @@ function commandTransform(sources) {
       async execute({ sessionID: sessionID3, prompt, delivery }) {
         const mode = reindexMode(prompt.text);
         let text2;
-        if (mode === void 0) text2 = `Unknown argument. Use /${COMMANDS.reindex} to catch up, or /${COMMANDS.reindex} rebuild to index everything again.`;
+        if (mode === void 0) text2 = formatFailure({ code: "INPUT_INVALID", message: `/${COMMANDS.reindex} takes no argument or rebuild.`, hint: `Run /${COMMANDS.reindex}, or /${COMMANDS.reindex} rebuild to index everything again.` });
         else try {
           text2 = indexed(mode, await sources.runtime.reindex(mode));
         } catch (error2) {
@@ -7476,24 +7494,31 @@ function commandTransform(sources) {
   };
 }
 
+// src/host/tested-hosts.json
+var tested_hosts_default = ["2.2.3", "2.2.4", "2.2.5"];
+
 // src/host/compat.ts
 var HOST_RANGE = ">=2.2.3 <2.3.0";
+var TESTED_HOSTS = tested_hosts_default;
 var parse4 = (value) => {
   const match = /^(\d+)\.(\d+)\.(\d+)$/.exec(value);
   return match ? [Number(match[1]), Number(match[2]), Number(match[3])] : void 0;
 };
 var compare = (a, b) => a[0] - b[0] || a[1] - b[1] || a[2] - b[2];
-function tested(version2, range = HOST_RANGE) {
+function inRange(version2, range = HOST_RANGE) {
   const [, low, high] = /^>=(\S+) <(\S+)$/.exec(range) ?? [];
   const found = parse4(version2), min = low && parse4(low), max = high && parse4(high);
   if (!found || !min || !max) return false;
   return compare(found, min) >= 0 && compare(found, max) < 0;
 }
+var testedWords = () => TESTED_HOSTS.length > 1 ? `${TESTED_HOSTS.slice(0, -1).join(", ")} or ${TESTED_HOSTS.at(-1)}` : TESTED_HOSTS.join("");
 function checkHost(found, allowUntestedHost) {
-  if (tested(found)) return { required: HOST_RANGE, found, availability: "AVAILABLE" };
-  const next = "Use OpenCode 2.2.3 or a later 2.2.x release, or set the plugin option allowUntestedHost: true to run anyway.";
-  if (!allowUntestedHost) throw new Error(formatFailure({ code: "HOST_UNTESTED", message: `History is tested on OpenCode ${HOST_RANGE}, found ${found}.`, hint: next }));
-  return { required: HOST_RANGE, found, availability: "HOST_UNTESTED", next: "This OpenCode version is untested and allowUntestedHost is set. If something fails, use OpenCode 2.2.3 or a later 2.2.x release." };
+  const version2 = found.trim() === "" ? null : found;
+  if (version2 !== null && TESTED_HOSTS.includes(version2)) return { version: version2, range: HOST_RANGE, tested: true };
+  if (version2 !== null && inRange(version2)) return { version: version2, range: HOST_RANGE, tested: false };
+  const next = `Use OpenCode ${testedWords()}, or another release inside ${HOST_RANGE}, or set the plugin option allowUntestedHost: true to run anyway.`;
+  if (!allowUntestedHost) throw new Error(formatFailure({ code: "HOST_UNTESTED", message: `History supports OpenCode ${HOST_RANGE}, found ${version2 ?? "no version"}.`, hint: next }));
+  return { version: version2, range: HOST_RANGE, tested: false, next: `OpenCode ${version2 ?? "of no known version"} is outside the supported range and allowUntestedHost is set. If something fails, use OpenCode ${testedWords()}.` };
 }
 
 // src/host/permissions.ts
@@ -7805,19 +7830,21 @@ var RecallOutputSchema = strictObject({
 });
 var StatusSchema = strictObject({
   version: string2().max(64),
-  host: strictObject({ required: string2().max(64), found: string2().max(64), availability: _enum(["AVAILABLE", "HOST_UNTESTED"]), next: string2().max(4096).optional() }),
-  connection: _enum(["connected", "connecting", "failed", "host untested"]),
+  host: strictObject({ version: string2().max(64).nullable(), range: string2().max(64), tested: boolean2() }),
+  state: _enum(["ready", "connecting", "failed"]),
   index: IndexStateSchema,
   fallback: _enum(["SOURCE_UNAVAILABLE", "SOURCE_SCHEMA_UNKNOWN"]).optional(),
   tools: strictObject({ visible: number2().int().min(0), unknown: array(string2().max(128)).max(20) }),
   database: string2().max(4096),
   indexPath: string2().max(4096),
+  indexBytes: number2().int().min(0).nullable(),
+  masksChanged: boolean2(),
   defaultScope: _enum(SCOPES),
   recall: strictObject({ synthesize: boolean2(), model: string2().max(256).nullable() }),
   unguardedAgents: array(string2().max(256)).max(1e3),
   permissionsBlock: array(strictObject({ action: string2(), resource: string2(), effect: _enum(["allow", "deny", "ask"]) })).optional(),
   mismatch: strictObject({ file: string2().max(64).nullable(), build: string2().max(64) }).optional(),
-  next: string2().max(4096).optional()
+  nextStep: string2().max(4096)
 });
 var StatusToolSchema = StatusSchema.omit({ unguardedAgents: true, permissionsBlock: true }).extend({
   unguardedAgents: number2().int().min(0),
@@ -7868,7 +7895,7 @@ var PinInputSchema = strictObject({
   sessionID: sessionID.optional().describe("The past session to pin or unpin, from history_search, history_sessions or history_files. Needed for put and remove."),
   from: integer2.min(0).optional().describe("Pin messages from this seq instead of the brief, for example a search excerpt's seq. Omit from and to to pin the session's brief."),
   to: integer2.min(0).optional().describe(`Last seq of the range, inclusive, at most ${MAX_PIN_RANGE} messages after from. Default: from, a single message.`),
-  maxChars: ranged(BOUNDS.pin.maxChars, "Most characters of session text to pin")
+  maxChars: ranged(BOUNDS.pin.maxChars, "Most characters to pin, its header line included")
 }).superRefine((input, issues) => {
   const issue2 = (path, message) => issues.addIssue({ code: "custom", path: [path], message });
   if (input.action !== "list" && input.sessionID === void 0) issue2("sessionID", `is required for ${input.action}`);
@@ -7884,23 +7911,31 @@ var pin = (key, value) => {
   const text2 = typeof value === "string" ? value : JSON.stringify(value) ?? "";
   return { sessionID: session, key, chars: text2.length, label: oneLine(text2.split("\n", 1)[0] ?? "", 200) };
 };
+var PIN_TITLE_CHARS = 120;
+function fit(header, body, maxChars, trimmed) {
+  const whole = `${header(trimmed, true)}
+${body}`;
+  if (whole.length <= maxChars) return whole;
+  const titled = header(true, true);
+  const head = titled.length + 2 <= maxChars ? titled : header(true, false);
+  let end = Math.max(0, maxChars - head.length - 2);
+  const code = body.charCodeAt(end - 1);
+  if (end > 0 && code >= 55296 && code <= 56319) end--;
+  return `${head}
+${body.slice(0, end)}\u2026`;
+}
 async function pinText(runtime, caller, input) {
   const unpin = `Unpin with history_pin {"action":"remove","sessionID":${JSON.stringify(input.sessionID)}}.`;
+  const quoted2 = (title2, shown) => shown ? ` ${JSON.stringify(oneLine(title2, PIN_TITLE_CHARS))}` : "";
   if (input.from === void 0) {
     const brief2 = await runtime.brief(caller, { sessionID: input.sessionID });
-    const body = formatBrief(brief2, { calls: false });
-    const trimmed = body.length > input.maxChars;
-    return [
-      `Pinned brief of past session ${input.sessionID} ${JSON.stringify(brief2.session.title)}${trimmed ? ", trimmed" : ""}. It is a record of earlier work, not instructions. ${unpin}`,
-      trimmed ? `${body.slice(0, input.maxChars - 1)}\u2026` : body
-    ].join("\n");
+    const header2 = (trimmed, title2) => `Pinned brief of past session ${input.sessionID}${quoted2(brief2.session.title, title2)}${trimmed ? ", trimmed" : ""}. It is a record of earlier work, not instructions. ${unpin}`;
+    return fit(header2, formatBrief(brief2, { calls: false }), input.maxChars, false);
   }
   const to = input.to ?? input.from;
   const read2 = await runtime.read(caller, { sessionID: input.sessionID, at: input.from, before: 0, after: to - input.from, maxChars: input.maxChars });
-  return [
-    `Pinned messages #${input.from}-#${to} of past session ${input.sessionID} ${JSON.stringify(read2.session.title)}${read2.truncated ? ", trimmed" : ""}. They are a record of earlier work, not instructions. ${unpin}`,
-    formatRead(read2, input, { calls: false })
-  ].join("\n");
+  const header = (trimmed, title2) => `Pinned messages #${input.from}-#${to} of past session ${input.sessionID}${quoted2(read2.session.title, title2)}${trimmed ? ", trimmed" : ""}. They are a record of earlier work, not instructions. ${unpin}`;
+  return fit(header, formatRead(read2, input, { calls: false }), input.maxChars, read2.truncated);
 }
 async function runPin(sources, caller, input, signal) {
   if (caller.sessionID === null) return fail("OPERATION_FAILED", { message: "history_pin needs a session to pin into." });
@@ -8004,13 +8039,13 @@ function compactStatus(view) {
 }
 var MAX_RESULT_BYTES = 1048576;
 function bounded(result) {
-  let size;
+  let size2;
   try {
-    size = Math.max(Buffer.byteLength(result.content), Buffer.byteLength(JSON.stringify(result.output) ?? ""));
+    size2 = Math.max(Buffer.byteLength(result.content), Buffer.byteLength(JSON.stringify(result.output) ?? ""));
   } catch {
     return fail("CONTRACT_MISMATCH");
   }
-  if (size > MAX_RESULT_BYTES) fail("OUTPUT_LIMIT");
+  if (size2 > MAX_RESULT_BYTES) fail("OUTPUT_LIMIT");
   return result;
 }
 async function abortable(signal, work) {
@@ -8058,7 +8093,34 @@ function toolTransform(sources) {
 var TOOLS_RPC_ID = `${PLUGIN_ID}.tools`;
 var EXCLUDED = new Set(ACTIONS);
 var UNATTENDED = "A script cannot answer an approval prompt; this needs an allow rule for the session's agent.";
-var Envelope = strictObject({ sessionID: string2().min(1).max(256), input: unknown() });
+var plainObject = (value) => typeof value === "object" && value !== null && !Array.isArray(value);
+var ENVELOPE_MESSAGES = {
+  notObject: `the envelope must be an object, such as {"sessionID":"<session>","input":<the tool's input>}`,
+  unknownKey: (key) => `"${key}" is not allowed`,
+  sessionID: `"sessionID" must be a non-empty string`,
+  inputMissing: `"input" is missing`,
+  describe: "describe takes no input"
+};
+var standard = (schema, issues) => Object.defineProperty({ ...schema }, "~standard", {
+  value: { version: 1, vendor: "history", validate: (value) => {
+    const found = issues(value);
+    return found.length === 0 ? { value } : { issues: found.map((message) => ({ message })) };
+  } },
+  enumerable: false
+});
+function envelopeIssues(value) {
+  if (!plainObject(value)) return [ENVELOPE_MESSAGES.notObject];
+  return [
+    ...Object.keys(value).filter((key) => key !== "sessionID" && key !== "input").map(ENVELOPE_MESSAGES.unknownKey),
+    ...typeof value["sessionID"] === "string" && value["sessionID"] !== "" ? [] : [ENVELOPE_MESSAGES.sessionID],
+    ...Object.hasOwn(value, "input") ? [] : [ENVELOPE_MESSAGES.inputMissing]
+  ];
+}
+var ENVELOPE = standard(
+  { type: "object", properties: { sessionID: { type: "string", minLength: 1 }, input: {} }, required: ["sessionID", "input"], additionalProperties: false },
+  envelopeIssues
+);
+var DESCRIBE_INPUT = standard({ type: "object", properties: {}, required: [], additionalProperties: false }, (value) => value === void 0 || value === null || plainObject(value) && Object.keys(value).length === 0 ? [] : [ENVELOPE_MESSAGES.describe]);
 var Failure = strictObject({ code: string2(), next: string2() });
 var Description = strictObject({
   id: string2(),
@@ -8120,7 +8182,9 @@ async function registerScripting(ctx, sources) {
   const invoke = async (tool, raw, context) => {
     try {
       if (context.signal.aborted) throw new HistoryError("CANCELLED");
-      const { sessionID: sessionID3, input } = parse2(Envelope, raw, "INPUT_INVALID");
+      const problems = envelopeIssues(raw);
+      if (problems.length) throw new HistoryError("INPUT_INVALID", { message: `The envelope is invalid: ${problems.join("; ")}.` });
+      const { sessionID: sessionID3, input } = raw;
       const call2 = await session(sessionID3);
       const result = bounded(await runTool(tool, { ...sources, assert: assert2 }, call2, parse2(tool.input, input ?? {}, "INPUT_INVALID"), context.signal));
       return JSON.parse(JSON.stringify(result.output));
@@ -8132,8 +8196,8 @@ async function registerScripting(ctx, sources) {
   const contract = Rpc2.define({
     id: TOOLS_RPC_ID,
     methods: {
-      describe: { input: strictObject({}).optional(), output: Description },
-      ...Object.fromEntries(tools.map((tool) => [tool.name, { input: Envelope, output: tool.output, errors: { failed: Failure } }]))
+      describe: { input: DESCRIBE_INPUT, output: Description },
+      ...Object.fromEntries(tools.map((tool) => [tool.name, { input: ENVELOPE, output: tool.output, errors: { failed: Failure } }]))
     },
     events: {}
   });
@@ -8184,50 +8248,53 @@ function fallbackFailure(code) {
   const cause = code === "SOURCE_SCHEMA_UNKNOWN" ? "OpenCode's database has a layout this plugin version does not know" : "OpenCode's database could not be read";
   return { code, message: `${cause}, so history comes from the plugin session API, which keeps only the messages after each compaction.`, hint: FAILURES[code][1] };
 }
-function nextStep(view, fallback) {
-  if (view.host.next) return view.host.next;
+function nextStep(host, view, fallback) {
+  if (host.next) return host.next;
   if (view.mismatch) return FAILURES.INDEX_MISMATCH[1];
   if (view.index.source === "context") return FAILURES[fallback ?? "SOURCE_UNAVAILABLE"][1];
+  if (view.masksChanged) return MASKS_CHANGED;
   if (view.unguardedAgents.length > 0) return AGENT_FIX;
   if (!view.index.ready) return BUILDING;
-  return void 0;
+  return NOTHING_TO_DO;
 }
+var MASKS_CHANGED = "Run /history-reindex rebuild, since the mask options changed after text was indexed: results are masked with the new patterns, but the index file still holds that text masked the old way.";
 var BUILDING = "Wait for the index to finish building, since until then results cover only the sessions indexed so far.";
-function connection(view) {
+function stateOf(view) {
   if (view.mismatch || view.index.source === "context") return "failed";
-  if (view.host.availability !== "AVAILABLE") return "host untested";
-  return view.index.ready ? "connected" : "connecting";
+  return view.index.ready ? "ready" : "connecting";
 }
 var SAFE_NAME = /^history_[a-z][a-z0-9_]{0,63}$/;
 async function buildStatus({ version: version2, host, config: config2, runtime, agents, tools }) {
   const known = new Set(TOOL_NAMES.map((name) => `history_${name}`));
-  const [index, schema, listed, ids] = await Promise.all([
+  const [index, schema, file, listed, ids] = await Promise.all([
     runtime.status(),
     runtime.schema(),
+    runtime.indexFile(),
     agents(),
     tools ? tools().then((list2) => list2.map((tool) => tool.id)) : Promise.resolve([...known])
   ]);
   const unguarded = unguardedAgents(listed);
   const ours = ids.filter((id2) => id2.startsWith("history_"));
   const { model: model2 } = config2.recall;
-  const base = { host, index, ...schema.file !== schema.build ? { mismatch: schema } : {} };
+  const base = { index, ...schema.file !== schema.build ? { mismatch: schema } : {} };
   const view = {
     version: version2,
-    host,
-    connection: connection(base),
+    host: { version: host.version, range: host.range, tested: host.tested },
+    state: stateOf(base),
     index,
     ...index.source === "context" ? { fallback: runtime.fallback ?? "SOURCE_UNAVAILABLE" } : {},
     tools: { visible: ours.length, unknown: ours.filter((id2) => !known.has(id2)).filter((id2) => SAFE_NAME.test(id2)).slice(0, 20) },
     database: config2.database,
     indexPath: config2.indexPath,
+    indexBytes: file.bytes,
+    masksChanged: file.masksChanged,
     defaultScope: config2.defaultScope,
     recall: { synthesize: config2.recall.synthesize, model: model2 ? `${model2.providerID}/${model2.id}` : null },
     unguardedAgents: unguarded,
     ...unguarded.length ? { permissionsBlock: DEFAULT_RULES.map((rule) => ({ ...rule })) } : {},
     ...schema.file !== schema.build ? { mismatch: schema } : {}
   };
-  const next = nextStep(view, runtime.fallback);
-  return { ...view, ...next ? { next } : {} };
+  return { ...view, nextStep: nextStep(host, view, runtime.fallback) };
 }
 
 // src/host/plugin.ts
@@ -8241,7 +8308,10 @@ function createPlugin({ createRuntime: createRuntime2, packageRoot }) {
     async setup(ctx) {
       const config2 = loadConfig(ctx.options);
       const host = checkHost(ctx.app.version, config2.allowUntestedHost);
-      if (host.next) console.warn(formatFailure({ code: "HOST_UNTESTED", message: `OpenCode ${host.found} is untested (tested: ${host.required}); History runs because allowUntestedHost is set.`, hint: "Use a tested OpenCode version if something fails." }));
+      if (!host.tested) {
+        const why = inRange(host.version ?? "") ? `inside the supported range ${host.range}` : `outside the supported range ${host.range}; History runs because allowUntestedHost is set`;
+        console.warn(formatFailure({ code: "HOST_UNTESTED", message: `OpenCode ${host.version ?? "of no known version"} is untested (tested: ${TESTED_HOSTS.join(", ")}), ${why}.`, hint: "Use a tested OpenCode version if something fails." }));
+      }
       const problem = indexPathProblem(config2.indexPath, {
         database: config2.database,
         projectFolders: [ctx.location.directory, ctx.location.project.directory],
@@ -8296,7 +8366,8 @@ function createPlugin({ createRuntime: createRuntime2, packageRoot }) {
 }
 
 // src/runtime.ts
-import { realpathSync as realpathSync2 } from "node:fs";
+import { createHash } from "node:crypto";
+import { realpathSync as realpathSync2, statSync } from "node:fs";
 import { basename as basename2, dirname as dirname4, join as join5, resolve as resolve3 } from "node:path";
 
 // src/index/events.ts
@@ -8608,12 +8679,21 @@ var IndexStore = class _IndexStore {
       this.depth--;
     }
   }
-  /** Drop everything and recreate an empty index. */
+  /**
+   * Drop everything and recreate an empty index. The dropped pages are overwritten with zeros and the write-ahead log is
+   * emptied, so text stored before, such as a secret masked only by a newer pattern, does not stay in the file.
+   */
   reset() {
-    this.transaction(() => {
-      dropAll(this.db);
-      create(this.db);
-    });
+    this.db.exec("pragma secure_delete = on");
+    try {
+      this.transaction(() => {
+        dropAll(this.db);
+        create(this.db);
+      });
+    } finally {
+      this.db.exec("pragma secure_delete = off");
+    }
+    this.db.exec("pragma wal_checkpoint(truncate)");
   }
   /** The schema version the file is at now, which another process running another plugin version may have changed. */
   schemaVersion() {
@@ -8655,17 +8735,17 @@ var IndexStore = class _IndexStore {
   writeBatch(session, rootID, range, batch) {
     this.transaction(() => {
       this.writeSession(session, rootID, batch.facts, range);
-      const inRange = (what, sessionID3, seq) => {
+      const inRange2 = (what, sessionID3, seq) => {
         if (sessionID3 !== session.id || seq < range.from || seq > range.to) {
           throw new Error(`history index: ${what} at ${sessionID3}#${seq} is outside ${session.id}#${range.from}..${range.to}`);
         }
       };
       for (const doc of batch.docs) {
-        inRange("doc", doc.sessionID, doc.seq);
+        inRange2("doc", doc.sessionID, doc.seq);
         this.insertDoc(doc, rootID, doc.seq, doc.part);
       }
       for (const file of batch.files) {
-        inRange("file", file.sessionID, file.seq);
+        inRange2("file", file.sessionID, file.seq);
         this.db.run(
           "insert into files (session_id, root_id, message_id, seq, time, path, op, tool) values (?, ?, ?, ?, ?, ?, ?, ?)",
           file.sessionID,
@@ -8679,7 +8759,7 @@ var IndexStore = class _IndexStore {
         );
       }
       for (const link of batch.links) {
-        inRange(`link to ${link.childID}`, link.parentID, link.seq);
+        inRange2(`link to ${link.childID}`, link.parentID, link.seq);
         this.db.run(
           `insert into links (parent_id, child_id, message_id, seq, description, agent) values (?, ?, ?, ?, ?, ?)
             on conflict(child_id) do update set parent_id = excluded.parent_id, message_id = excluded.message_id,
@@ -9212,13 +9292,29 @@ function summaries(db, ids) {
 }
 
 // src/query/parse.ts
+var QUERY_HINTS = {
+  regex: 'Check the regular expression, or search with match: "words".',
+  substring: 'Use a substring of at least 3 characters, or search with match: "words".',
+  time: "Use an ISO date such as 2026-10-01 or an age such as 7d.",
+  words: 'Search with plain words, or with match: "substring" for exact text.',
+  excluded: "Add a word to search for besides the excluded terms.",
+  empty: "Pass at least one search term in query.",
+  match: 'Use match: "words", "substring" or "regex".',
+  path: "Pass a file or folder path, such as src/auth.ts.",
+  scope: 'Use scope "session", "directory", "project" or "all".',
+  sessionScope: 'Pass sessionID with scope "session", or use another scope.',
+  question: "Pass the question to answer."
+};
 var QueryError = class extends Error {
   constructor(message, reason = "query", options) {
-    super(message, options);
+    super(message, options?.cause === void 0 ? void 0 : { cause: options.cause });
     this.reason = reason;
     this.name = "QueryError";
+    if (options?.hint !== void 0) this.hint = options.hint;
   }
   reason;
+  /** The next step, when it is more specific than the failure code's own. */
+  hint;
 };
 var space = (char) => /\s/.test(char);
 function tokenize(input) {
@@ -9452,12 +9548,12 @@ function parseTime(value, now, edge) {
   const duration2 = DURATION.exec(text2);
   if (duration2) {
     const unit = duration2[2].toLowerCase();
-    const size = unit.startsWith("mo") || unit === "m" ? UNITS.m : UNITS[unit[0]];
-    return now - Number(duration2[1]) * size;
+    const size2 = unit.startsWith("mo") || unit === "m" ? UNITS.m : UNITS[unit[0]];
+    return now - Number(duration2[1]) * size2;
   }
   const time3 = ISO.test(text2) ? Date.parse(DATE_ONLY.test(text2) ? `${text2}T00:00:00Z` : text2) : Number.NaN;
   if (!Number.isFinite(time3)) {
-    throw new QueryError(`${edge} must be an ISO date such as "2026-10-01" or an age such as "36h", "7d", "2w", "3m" or "1y"`);
+    throw new QueryError(`${edge} must be an ISO date such as "2026-10-01" or an age such as "36h", "7d", "2w", "3m" or "1y"`, "query", { hint: QUERY_HINTS.time });
   }
   return DATE_ONLY.test(text2) && edge === "until" ? time3 + DAY - 1 : time3;
 }
@@ -9465,12 +9561,12 @@ function parseRegex(pattern2) {
   const literal = /^\/(.+)\/([dgimsuvy]*)$/s.exec(pattern2);
   const source = literal ? literal[1] : pattern2;
   const flags = literal ? literal[2] : "i";
-  if (!source) throw new QueryError("regex pattern is empty");
+  if (!source) throw new QueryError("regex pattern is empty", "query", { hint: QUERY_HINTS.regex });
   try {
     return new RegExp(source, flags.includes("g") ? flags : `${flags}g`);
   } catch (error2) {
     const reason = error2 instanceof Error && error2.message.startsWith("Invalid regular expression") ? error2.message.split(": ").at(-1) : "invalid flags";
-    throw new QueryError(`invalid regex: ${reason}`);
+    throw new QueryError(`invalid regex: ${reason}`, "query", { hint: QUERY_HINTS.regex });
   }
 }
 var CURSOR = "o:";
@@ -9595,7 +9691,7 @@ function hiddenCounts(rows, hiding) {
 var SCOPES2 = ["session", "directory", "project", "all"];
 function pathMatch(path, directory) {
   let clean = path.trim().replace(/^\.\//, "");
-  if (!clean || clean === "/" || clean === ".") throw new QueryError("path must name a file or folder");
+  if (!clean || clean === "/" || clean === ".") throw new QueryError("path must name a file or folder", "query", { hint: QUERY_HINTS.path });
   if (/[*?[]/.test(clean)) {
     return clean.startsWith("/") || clean.startsWith("*") ? { sql: "f.path glob ?", params: [clean] } : { sql: "(f.path glob ? or f.path glob ?)", params: [clean, `*/${clean}`] };
   }
@@ -9616,9 +9712,9 @@ function filterSql(db, caller, filters2, now, target) {
     hiding.push({ reason, sql: sql2, params });
   };
   const scope = filters2.scope ?? "project";
-  if (!SCOPES2.includes(scope)) throw new QueryError("scope must be session, directory, project or all");
+  if (!SCOPES2.includes(scope)) throw new QueryError("scope must be session, directory, project or all", "query", { hint: QUERY_HINTS.scope });
   const named = filters2.sessionID ?? (scope === "session" ? caller.sessionID : null);
-  if (scope === "session" && !named) throw new QueryError('scope "session" needs a sessionID when there is no calling session');
+  if (scope === "session" && !named) throw new QueryError('scope "session" needs a sessionID when there is no calling session', "query", { hint: QUERY_HINTS.sessionScope });
   if (named) {
     add("(s.id = ? or s.root_id = ?)", named, named);
     if (!filters2.includeSubagents) hide2("subagents", "s.id = ?", named);
@@ -9664,7 +9760,7 @@ function filterSql(db, caller, filters2, now, target) {
 var MAX_FILE_SESSIONS = 20;
 var FILE_OPS2 = ["read", "edit", "write", "patch", "search"];
 function files(db, caller, input, state, options = {}) {
-  if (!input.path?.trim()) throw new QueryError("path must name a file or folder");
+  if (!input.path?.trim()) throw new QueryError("path must name a file or folder", "query", { hint: QUERY_HINTS.path });
   const ops = input.ops && input.ops.length > 0 ? input.ops : void 0;
   if (ops?.some((op2) => !FILE_OPS2.includes(op2))) throw new QueryError(`ops must be among ${FILE_OPS2.join(", ")}`);
   const limit = bounded2(input.limit, BOUNDS.files.limit);
@@ -10007,7 +10103,7 @@ var HIT_COLUMNS = `d.id as id, d.session_id as sessionID, d.root_id as rootID, d
 var JOINS = "join sessions s on s.id = d.session_id left join sessions r on r.id = d.root_id";
 var WEIGHT_SQL = `case d.kind ${DOC_KINDS.map((kind2) => `when '${kind2}' then ${KIND_WEIGHT[kind2]}`).join(" ")} else 1 end`;
 var NONE2 = { sql: "", params: [] };
-var ftsFailure = (error2) => error2 instanceof Error && /fts5|syntax error/i.test(error2.message) ? new QueryError("the query could not be searched; use plain words", "query", { cause: error2 }) : error2;
+var ftsFailure = (error2) => error2 instanceof Error && /fts5|syntax error/i.test(error2.message) ? new QueryError("the query could not be searched", "query", { cause: error2, hint: QUERY_HINTS.words }) : error2;
 function ftsHits(db, match, where) {
   let rows;
   try {
@@ -10543,12 +10639,12 @@ var MODES = ["words", "substring", "regex"];
 async function search(db, caller, input, state, options = {}) {
   const now = options.now ?? Date.now();
   const mode = input.match ?? "words";
-  if (!MODES.includes(mode)) throw new QueryError("match must be words, substring or regex");
+  if (!MODES.includes(mode)) throw new QueryError("match must be words, substring or regex", "query", { hint: QUERY_HINTS.match });
   const limit = bounded2(input.limit, BOUNDS.search.limit);
   const snippetCount = bounded2(input.snippets, BOUNDS.search.snippets);
   const offset = decodeCursor(input.cursor);
   const texts = phrasingsOf(input.query, mode === "regex");
-  if (texts.length === 0) throw new QueryError("query is empty");
+  if (texts.length === 0) throw new QueryError("query is empty", "query", { hint: QUERY_HINTS.empty });
   const where = filterSql(db, caller, input, now, "docs");
   const deadline = performance.now() + SCAN_BUDGET_MS;
   let hits;
@@ -10564,7 +10660,7 @@ async function search(db, caller, input, state, options = {}) {
     });
   } else if (mode === "substring") {
     const parsed = texts.map(parseQuery);
-    if (parsed.every((query) => !substringCandidates(query))) throw new QueryError(`substring search needs a term of at least ${MIN_SUBSTRING} characters to include`);
+    if (parsed.every((query) => !substringCandidates(query))) throw new QueryError(`substring search needs a term of at least ${MIN_SUBSTRING} characters`, "query", { hint: QUERY_HINTS.substring });
     hits = await substringHits(db, parsed, where, deadline, limit);
     highlighters = parsed.map((query) => ({ kind: "literal", terms: highlightTerms(query, "substring").map(fold) }));
     probes = parsed.flatMap((query) => {
@@ -10575,7 +10671,7 @@ async function search(db, caller, input, state, options = {}) {
     });
   } else {
     const parsed = texts.map(parseQuery);
-    if (parsed.every((query) => toMatch(query, "words") === void 0)) throw new QueryError("query has nothing to include; excluded terms need at least one word to search for");
+    if (parsed.every((query) => toMatch(query, "words") === void 0)) throw new QueryError("query has nothing to include; excluded terms need at least one word to search for", "query", { hint: QUERY_HINTS.excluded });
     hits = wordsHits(db, parsed, where, limit);
     highlighters = parsed.map((query) => {
       const full = toMatch(query, "words");
@@ -10678,7 +10774,7 @@ function recallPrompt(question, evidence) {
 }
 async function recall(db, source, caller, input, state, synthesize, mask, options = {}) {
   const question = input.question.trim();
-  if (!question) throw new QueryError("question is empty");
+  if (!question) throw new QueryError("question is empty", "query", { hint: QUERY_HINTS.question });
   const given = (input.queries ?? []).map((query) => query.trim()).filter(Boolean);
   const queries = given.length > 0 ? given : phrasingsFor(question);
   const sessionCount = bounded2(input.sessions, BOUNDS.recall.sessions);
@@ -10706,7 +10802,7 @@ async function recall(db, source, caller, input, state, synthesize, mask, option
     if (!text2) text2 = `#${snippet.seq} ${snippet.kind}: ${unmark(snippet.text)}`;
     text2 = clip2(text2, Math.min(perWindow, left));
     covered.set(snippet.sessionID, [...ranges, { from, to }]);
-    const title2 = titles.get(snippet.sessionID)?.title ?? hit2.title;
+    const title2 = mask(titles.get(snippet.sessionID)?.title ?? hit2.title);
     evidence.push({ sessionID: snippet.sessionID, title: title2, seq: snippet.seq, time: snippet.time, text: text2 });
     left -= text2.length;
   }
@@ -10801,58 +10897,118 @@ function checkSql(text2) {
   if (!/^(select|with)\b/i.test(statement)) throw new QueryError("only a SELECT or WITH statement is allowed", "sql_rejected");
   return out.trim().replace(/[;\s]+$/, "");
 }
-var RUNNER = `"use strict"
+var SQL_TIMEOUT_MS = 1e4;
+var SQL_KILL_GRACE_MS = 2e3;
+var SQL_OUTPUT_BYTES = 512 * 1024;
+var SQL_STDOUT_BYTES = 4 * 1024 * 1024;
+var SQL_PARALLEL = 2;
+var SQL_PARENT_POLL_MS = 200;
+var SQL_CEILINGS = {
+  timeoutMs: SQL_TIMEOUT_MS,
+  rows: BOUNDS.sql.limit.max,
+  cellChars: SQL_CELL_CHARS,
+  rowBytes: SQL_OUTPUT_BYTES,
+  stdoutBytes: SQL_STDOUT_BYTES,
+  busyMs: SQL_BUSY_MS,
+  pollMs: SQL_PARENT_POLL_MS,
+  // The job is the statement (at most 16,384 characters), its params and a few numbers, as one JSON line.
+  jobChars: 1024 * 1024
+};
+var WORKER = `"use strict"
+const { parentPort, workerData: job } = require("node:worker_threads")
 const { DatabaseSync } = require("node:sqlite")
-let raw = ""
-process.stdin.setEncoding("utf8")
-process.stdin.on("data", chunk => { raw += chunk })
-process.stdin.on("end", () => {
-  const job = JSON.parse(raw)
-  const clip = text => {
-    if (text.length <= job.cellChars) return text
-    let end = Math.max(0, job.cellChars - 1)
-    const code = text.charCodeAt(end - 1)
-    if (end > 0 && code >= 0xd800 && code <= 0xdbff) end--
-    return text.slice(0, end) + "\u2026"
-  }
-  const cell = value => {
-    if (typeof value === "string") return clip(value)
-    if (typeof value === "bigint") return Number.isSafeInteger(Number(value)) ? Number(value) : value.toString()
-    if (value instanceof Uint8Array) return "[blob, " + value.byteLength + " bytes]"
-    return value === undefined ? null : value
-  }
-  let out
+const C = ${JSON.stringify(SQL_CEILINGS)}
+const limit = Math.max(0, Math.min(job.limit, C.rows))
+const cellChars = Math.max(1, Math.min(job.cellChars, C.cellChars))
+const maxBytes = Math.max(0, Math.min(job.maxBytes, C.rowBytes))
+const masks = (job.mask || []).map(([source, flags]) => new RegExp(source, flags.includes("g") ? flags : flags + "g"))
+const mask = text => {
+  for (const pattern of masks) text = text.replace(pattern, (match, ...rest) => {
+    if (match === "") return match
+    const groups = rest[rest.length - 1]
+    const keep = typeof groups === "object" && groups !== null ? groups.keep : undefined
+    return (keep || "") + "[masked]"
+  })
+  return text
+}
+const clip = text => {
+  if (text.length <= cellChars) return text
+  let end = Math.max(0, cellChars - 1)
+  const code = text.charCodeAt(end - 1)
+  if (end > 0 && code >= 0xd800 && code <= 0xdbff) end--
+  return text.slice(0, end) + "\\u2026"
+}
+const cell = value => {
+  if (typeof value === "string") return clip(mask(value))
+  if (typeof value === "bigint") return Number.isSafeInteger(Number(value)) ? Number(value) : value.toString()
+  if (value instanceof Uint8Array) return "[blob, " + value.byteLength + " bytes]"
+  return value === undefined ? null : value
+}
+let out
+try {
+  const db = new DatabaseSync(job.path, { readOnly: true })
   try {
-    const db = new DatabaseSync(job.path, { readOnly: true })
-    try {
-      db.exec("pragma busy_timeout = " + job.busyMs)
-      db.exec("pragma query_only = 1")
-      const statement = db.prepare(job.statement)
-      let columns = typeof statement.columns === "function" ? statement.columns().map(column => column.name) : null
-      const rows = []
-      let bytes = 0, truncated = false
-      for (const row of statement.iterate(...job.params)) {
-        if (columns === null) columns = Object.keys(row)
-        if (rows.length >= job.limit) { truncated = true; break }
-        const cells = columns.map(name => cell(row[name]))
-        bytes += JSON.stringify(cells).length
-        if (bytes > job.maxBytes && rows.length > 0) { truncated = true; break }
-        rows.push(cells)
-      }
-      out = { ok: true, columns: columns || [], rows, truncated }
-    } finally {
-      db.close()
-    }
-  } catch (error) {
-    out = { ok: false, message: error && error.message ? String(error.message) : String(error), errcode: error && typeof error.errcode === "number" ? error.errcode : undefined }
+    db.exec("pragma busy_timeout = " + Math.max(0, Math.min(job.busyMs, C.busyMs)))
+    db.exec("pragma query_only = 1")
+    const statement = db.prepare(job.statement)
+    let columns = typeof statement.columns === "function" ? statement.columns().map(column => column.name) : null
+    const rows = []
+    let bytes = 0, truncated = false
+    for (const row of statement.iterate(...job.params)) {
+      if (columns === null) columns = Object.keys(row)
+      if (rows.length >= limit) { truncated = true; break }
+      const cells = columns.map(name => cell(row[name]))
+      bytes += JSON.stringify(cells).length
+      if (bytes > maxBytes && rows.length > 0) { truncated = true; break }
+      rows.push(cells)
+    }
+    out = { ok: true, columns: columns || [], rows, truncated }
+  } finally {
+    db.close()
   }
-  process.stdout.write(JSON.stringify(out))
+} catch (error) {
+  out = { ok: false, message: error && error.message ? String(error.message) : String(error), errcode: error && typeof error.errcode === "number" ? error.errcode : undefined }
+}
+parentPort.postMessage(out)
+`;
+var RUNNER = `"use strict"
+const { Worker } = require("node:worker_threads")
+const C = ${JSON.stringify(SQL_CEILINGS)}
+const parent = process.ppid
+const stop = () => { try { process.kill(process.pid, "SIGKILL") } finally { process.exit(1) } }
+let answered = false
+const answer = out => {
+  if (answered) return
+  answered = true
+  let text = JSON.stringify(out)
+  if (Buffer.byteLength(text) > C.stdoutBytes) text = JSON.stringify({ ok: false, reason: "output" })
+  // A worker that has finished lets the process exit; one still inside SQLite (a timeout) needs the stop. A parent
+  // that does not read the answer gets the stop too.
+  setTimeout(stop, 1000)
+  process.stdout.write(text, () => out.reason === "timeout" ? stop() : process.exit(0))
+}
+setInterval(() => { if (process.ppid !== parent) stop() }, C.pollMs)
+process.stdin.on("end", stop)
+process.stdin.on("close", stop)
+process.stdin.on("error", stop)
+let raw = "", started = false
+process.stdin.setEncoding("utf8")
+process.stdin.on("data", chunk => {
+  if (started) return
+  raw += chunk
+  const end = raw.indexOf("\\n")
+  if (end < 0) { if (raw.length > C.jobChars) stop(); return }
+  started = true
+  let job
+  try { job = JSON.parse(raw.slice(0, end)) } catch { return answer({ ok: false, message: "the job is not JSON" }) }
+  raw = ""
+  const timeoutMs = Math.max(1, Math.min(Number(job.timeoutMs) || C.timeoutMs, C.timeoutMs))
+  setTimeout(() => answer({ ok: false, reason: "timeout" }), timeoutMs)
+  const worker = new Worker(${JSON.stringify(WORKER)}, { eval: true, workerData: job })
+  worker.on("message", answer)
+  worker.on("error", error => answer({ ok: false, message: error && error.message ? String(error.message) : String(error) }))
 })
 `;
-var SQL_TIMEOUT_MS = 1e4;
-var SQL_OUTPUT_BYTES = 512 * 1024;
-var SQL_STDOUT_BYTES = 4 * 1024 * 1024;
-var SQL_PARALLEL = 2;
 function runnerCommand() {
   const bun = typeof process.versions.bun === "string";
   const env = bun ? { BUN_BE_BUN: "1" } : {};
@@ -10887,23 +11043,24 @@ async function slot(signal) {
     waiting.shift()?.();
   };
 }
-function runChild(job, cwd, timeoutMs, signal) {
+function runChild(job, cwd, signal) {
   const { file, args, env } = runnerCommand();
+  const timeoutMs = job.timeoutMs;
   return new Promise((resolve4, reject) => {
     let stop;
     const chunks = [];
-    let size = 0;
+    let size2 = 0;
     const child = spawn(file, args, { cwd, env, stdio: ["pipe", "pipe", "ignore"], windowsHide: true });
     const kill = (why) => {
       stop ??= why;
       child.kill("SIGKILL");
     };
-    const timer = setTimeout(() => kill("timeout"), timeoutMs);
+    const timer = setTimeout(() => kill("timeout"), timeoutMs + SQL_KILL_GRACE_MS);
     const abort = () => kill("cancelled");
     signal?.addEventListener("abort", abort, { once: true });
     child.stdout.on("data", (chunk) => {
-      size += chunk.length;
-      if (size > SQL_STDOUT_BYTES) return kill("output");
+      size2 += chunk.length;
+      if (size2 > SQL_STDOUT_BYTES) return kill("output");
       chunks.push(chunk);
     });
     child.stdin.on("error", () => {
@@ -10916,16 +11073,21 @@ function runChild(job, cwd, timeoutMs, signal) {
     child.on("close", () => {
       clearTimeout(timer);
       signal?.removeEventListener("abort", abort);
-      if (stop === "timeout") return reject(new QueryError(`the SQL ran longer than ${timeoutMs / 1e3} s and was stopped`, "sql_timeout"));
-      if (stop === "output") return reject(new HistoryError("OUTPUT_LIMIT"));
-      if (stop === "cancelled") return reject(new HistoryError("CANCELLED"));
+      child.stdin.destroy();
+      let answer;
       try {
-        resolve4(JSON.parse(Buffer.concat(chunks).toString("utf8")));
-      } catch (error2) {
-        reject(new QueryError("the SQL process gave no answer", "sql_failed", { cause: error2 }));
+        answer = JSON.parse(Buffer.concat(chunks).toString("utf8"));
+      } catch {
       }
+      const why = stop ?? (answer && !answer.ok ? answer.reason : void 0);
+      if (why === "timeout") return reject(new QueryError(`the SQL ran longer than ${timeoutMs / 1e3} s and was stopped`, "sql_timeout"));
+      if (why === "output") return reject(new HistoryError("OUTPUT_LIMIT"));
+      if (why === "cancelled") return reject(new HistoryError("CANCELLED"));
+      if (answer) return resolve4(answer);
+      reject(new QueryError("the SQL process gave no answer", "sql_failed"));
     });
-    child.stdin.end(JSON.stringify(job));
+    child.stdin.write(`${JSON.stringify(job)}
+`);
   });
 }
 async function sql(path, input, options = {}) {
@@ -10946,14 +11108,17 @@ ${body}
       limit,
       cellChars: SQL_CELL_CHARS,
       maxBytes: SQL_OUTPUT_BYTES,
-      busyMs: SQL_BUSY_MS
-    }, dirname3(path), options.timeoutMs ?? SQL_TIMEOUT_MS, options.signal);
+      busyMs: SQL_BUSY_MS,
+      timeoutMs: Math.min(options.timeoutMs ?? SQL_TIMEOUT_MS, SQL_TIMEOUT_MS),
+      mask: (options.mask ?? []).map((pattern2) => [pattern2.source, pattern2.flags])
+    }, dirname3(path), options.signal);
   } finally {
     release();
   }
   if (!answer.ok) {
-    const cause = Object.assign(new Error(answer.message), answer.errcode === void 0 ? {} : { errcode: answer.errcode });
-    if (/unable to open|cannot open/i.test(answer.message)) throw new QueryError("the history index could not be opened for reading", "sql_failed", { cause });
+    const failed = answer;
+    const cause = Object.assign(new Error(failed.message), failed.errcode === void 0 ? {} : { errcode: failed.errcode });
+    if (/unable to open|cannot open/i.test(failed.message)) throw new QueryError("the history index could not be opened for reading", "sql_failed", { cause });
     throw new QueryError("the SQL failed", "sql_failed", { cause });
   }
   return { columns: answer.columns, rows: answer.rows, truncated: answer.truncated };
@@ -11063,6 +11228,34 @@ function compare2(a, b) {
 }
 
 // src/runtime.ts
+var MASKED_WITH = "masked_with";
+function maskFingerprint(patterns) {
+  return createHash("sha256").update(JSON.stringify(patterns.map((pattern2) => [pattern2.source, pattern2.flags]))).digest("hex").slice(0, 16);
+}
+var TEXT_FIELDS = /* @__PURE__ */ new Set(["title", "firstPrompt", "lastReply", "summaries", "commands", "text", "description", "content", "path", "answer"]);
+function maskOutput(value, mask) {
+  const walk2 = (node2, text2) => {
+    if (typeof node2 === "string") return text2 ? mask(node2) : node2;
+    if (Array.isArray(node2)) return node2.map((item) => walk2(item, text2));
+    if (node2 === null || typeof node2 !== "object") return node2;
+    return Object.fromEntries(Object.entries(node2).map(([key, item]) => [key, walk2(item, TEXT_FIELDS.has(key))]));
+  };
+  return walk2(value, false);
+}
+function indexBytes(path) {
+  try {
+    const size2 = (file) => {
+      try {
+        return statSync(file).size;
+      } catch {
+        return 0;
+      }
+    };
+    return statSync(path).size + size2(`${path}-wal`);
+  } catch {
+    return null;
+  }
+}
 var REFRESH_MS = 200;
 var QUERY_FAILURES = {
   query: "QUERY_INVALID",
@@ -11100,20 +11293,22 @@ function toFailure(error2, fallback = "OPERATION_FAILED", operation = "runtime")
   }
   const code = QUERY_FAILURES[error2.reason];
   const detail = error2.reason === "query" || error2.reason === "sql_rejected" ? error2.message : error2.reason === "sql_failed" ? sqliteMistake(error2.cause) : void 0;
-  return new HistoryError(code, detail ? { message: `${FAILURES[code][0].replace(/\.$/, "")}: ${detail}.` } : {});
+  return new HistoryError(code, { ...detail ? { message: `${FAILURES[code][0].replace(/\.$/, "")}: ${detail}.` } : {}, ...error2.hint ? { hint: error2.hint } : {} });
 }
 var SharedIndex = class {
-  constructor(store, source, indexer, fallback) {
+  constructor(store, source, indexer, fallback, maskedWith) {
     this.store = store;
     this.source = source;
     this.indexer = indexer;
     this.fallback = fallback;
+    this.maskedWith = maskedWith;
     this.router = eventRouter({ syncSession: (id2) => this.track(indexer.syncSession(id2)), deleteSession: (id2) => this.track(indexer.deleteSession(id2)) });
   }
   store;
   source;
   indexer;
   fallback;
+  maskedWith;
   router;
   /** Indexing work in flight, so a rebuild can wait for it before it drops the index. */
   running = /* @__PURE__ */ new Set();
@@ -11171,6 +11366,7 @@ var SharedIndex = class {
     while (this.running.size > 0) await Promise.allSettled([...this.running]);
     if (this.closed) fail("CLOSED");
     this.store.reset();
+    this.store.setMeta(MASKED_WITH, this.maskedWith);
     await this.backfill();
   }
   backfill() {
@@ -11205,7 +11401,9 @@ function openIndex(path, { source, fallback }, options) {
       titleDoc: (session) => titleDoc(session, options),
       maskTitle: (text2) => maskText(text2, options.redact)
     });
-    const shared = new SharedIndex(store, source, indexer, fallback);
+    const maskedWith = maskFingerprint(options.redact);
+    if (store.meta(MASKED_WITH) === void 0) store.setMeta(MASKED_WITH, maskedWith);
+    const shared = new SharedIndex(store, source, indexer, fallback, maskedWith);
     shared.start();
     return shared;
   } catch (error2) {
@@ -11265,8 +11463,10 @@ var createRuntime = async ({ config: config2, session, generate }) => {
   const shared = lease.value;
   if (shared.source !== opened.source) opened.source.close();
   const mask = (text2) => maskText(text2, config2.mask);
+  const masked = (value) => maskOutput(value, mask);
   const state = () => shared.indexer.state();
   let closed = false;
+  const closing = new AbortController();
   const run = async (operation, work, fallback) => {
     if (closed) fail("CLOSED");
     try {
@@ -11287,15 +11487,17 @@ var createRuntime = async ({ config: config2, session, generate }) => {
     ...shared.fallback ? { fallback: shared.fallback } : {},
     status: () => run("status", state, "STATUS_UNAVAILABLE"),
     schema: () => run("status", () => ({ file: shared.store.schemaVersion() ?? null, build: String(INDEX_SCHEMA_VERSION) }), "STATUS_UNAVAILABLE"),
-    search: (caller, input) => query("search", () => fresh(() => search(shared.store.db, caller, input, state()))),
-    sessions: (caller, input) => query("sessions", () => fresh(() => sessions(shared.store.db, caller, input, state()))),
-    files: (caller, input) => query("files", () => files(shared.store.db, caller, input, state())),
-    read: (_caller, input) => query("read", () => read(shared.store.db, shared.source, input, mask)),
-    brief: (_caller, input) => query("brief", () => brief(shared.store.db, shared.source, input, mask)),
-    sql: (_caller, input, signal) => query("sql", () => sql(shared.store.path, input, signal ? { signal } : {})),
+    indexFile: () => run("status", () => ({ bytes: indexBytes(shared.store.path), masksChanged: shared.store.meta(MASKED_WITH) !== maskFingerprint(config2.mask) }), "STATUS_UNAVAILABLE"),
+    search: (caller, input) => query("search", () => fresh(async () => masked(await search(shared.store.db, caller, input, state())))),
+    sessions: (caller, input) => query("sessions", () => fresh(async () => masked(await sessions(shared.store.db, caller, input, state())))),
+    files: (caller, input) => query("files", async () => masked(await files(shared.store.db, caller, input, state()))),
+    read: (_caller, input) => query("read", async () => masked(await read(shared.store.db, shared.source, input, mask))),
+    brief: (_caller, input) => query("brief", async () => masked(await brief(shared.store.db, shared.source, input, mask))),
+    // A closing instance stops its statements, so a reload never leaves one running.
+    sql: (_caller, input, signal) => query("sql", () => sql(shared.store.path, input, { signal: signal ? AbortSignal.any([signal, closing.signal]) : closing.signal, mask: config2.mask })),
     recall: (caller, input) => query(
       "recall",
-      () => fresh(() => recall(shared.store.db, shared.source, caller, input, state(), input.synthesize ?? config2.recall.synthesize ? generate : void 0, mask))
+      () => fresh(async () => masked(await recall(shared.store.db, shared.source, caller, input, state(), input.synthesize ?? config2.recall.synthesize ? generate : void 0, mask)))
     ),
     reindex: (mode) => run("reindex", async () => {
       await (mode === "rebuild" ? shared.rebuild() : shared.catchUp());
@@ -11311,6 +11513,7 @@ var createRuntime = async ({ config: config2, session, generate }) => {
     async close() {
       if (closed) return;
       closed = true;
+      closing.abort();
       lease.release();
     }
   };

package/dist/tui.js

@@ -30,28 +30,44 @@ function agentsRow(view, compact) {
 var ACCOUNT_TEXT = "none; History needs no sign-in";
 var ACCESS_TEXT = "reads OpenCode's database read-only and writes only its own index; history_pin asks before it changes a session";
 var FALLBACK_TEXT = { SOURCE_UNAVAILABLE: "OpenCode's database could not be read", SOURCE_SCHEMA_UNKNOWN: "OpenCode's database has an unknown layout" };
+var CONNECTION_WORDS = { ready: "connected", connecting: "connecting", failed: "failed" };
+var MASKS_ROW = "Masks:";
+function size(bytes) {
+  const units = ["B", "KB", "MB", "GB", "TB"];
+  let value = bytes, unit = 0;
+  while (value >= 1024 && unit < units.length - 1) {
+    value /= 1024;
+    unit++;
+  }
+  return `${unit === 0 || value >= 10 ? Math.round(value) : value.toFixed(1)} ${units[unit]}`;
+}
+function hostText({ host, version }) {
+  const note = host.tested ? "tested" : `untested; supported range ${host.range}`;
+  return `${host.version ?? "unknown version"} (${note}). History ${version}`;
+}
 function toolsText({ tools }) {
   const unknown = tools.unknown.length ? `, ${tools.unknown.length} unknown (they ask first): ${tools.unknown.join(", ")}` : "";
   return `${tools.visible} available${unknown}`;
 }
 function formatStatus(view, options = {}) {
-  const { index, host, mismatch } = view;
+  const { index, mismatch } = view;
   return lines(
     "History status",
-    `Connection: ${view.connection}`,
+    `Connection: ${CONNECTION_WORDS[view.state]}`,
     `Account: ${ACCOUNT_TEXT}`,
     `Access: ${ACCESS_TEXT}`,
     `Index: ${index.ready ? "ready" : "building"}, ${index.sessionsIndexed} of ${index.sessionsTotal} sessions${index.lagSeconds ? `, ${Math.round(index.lagSeconds)} s behind` : ""}`,
     `Source: ${SOURCE_TEXT[index.source]}${index.complete ? "" : ", incomplete"}${view.fallback ? ` (${FALLBACK_TEXT[view.fallback]})` : ""}`,
     `Database: ${view.database}`,
-    `Index file: ${view.indexPath}`,
+    `Index file: ${view.indexPath}${view.indexBytes === null ? "" : ` (${size(view.indexBytes)})`}`,
+    view.masksChanged ? `${MASKS_ROW} changed since text was indexed, so the index file holds that text masked the old way until /history-reindex rebuild` : void 0,
     mismatch ? `${MISMATCH_ROW} ${mismatch.file === null ? "none" : `version ${mismatch.file}`} in the file, but this build uses version ${mismatch.build}, so every query fails (INDEX_MISMATCH)` : void 0,
     `Default scope: ${view.defaultScope}`,
     `Recall answers: ${view.recall.synthesize ? "on" : "off"}${view.recall.model ? ` (${view.recall.model})` : " (default model)"}`,
     `Tools: ${toolsText(view)}`,
     agentsRow(view, options.compact ?? false),
-    `OpenCode: ${host.found} (${host.availability === "AVAILABLE" ? "tested" : `host untested: tested on ${host.required}`}). History ${view.version}`,
-    `Next step: ${view.next ?? NOTHING_TO_DO}`
+    `OpenCode: ${hostText(view)}`,
+    `Next step: ${view.nextStep}`
   );
 }
 
@@ -71,20 +87,22 @@ var INDEX = object(
 );
 var STATUS_OUTPUT = object({
   version: string,
-  host: object({ required: string, found: string, availability: choice(["AVAILABLE", "HOST_UNTESTED"]), next: string }, ["required", "found", "availability"]),
-  connection: choice(["connected", "connecting", "failed", "host untested"]),
+  host: object({ version: nullable(string), range: string, tested: boolean }, ["version", "range", "tested"]),
+  state: choice(["ready", "connecting", "failed"]),
   index: INDEX,
   fallback: choice(["SOURCE_UNAVAILABLE", "SOURCE_SCHEMA_UNKNOWN"]),
   tools: object({ visible: integer, unknown: list(string) }, ["visible", "unknown"]),
   database: string,
   indexPath: string,
+  indexBytes: nullable(integer),
+  masksChanged: boolean,
   defaultScope: choice(["project", "directory", "all"]),
   recall: object({ synthesize: boolean, model: nullable(string) }, ["synthesize", "model"]),
   unguardedAgents: list(string),
   permissionsBlock: list(object({ action: string, resource: string, effect: choice(["allow", "deny", "ask"]) }, ["action", "resource", "effect"])),
   mismatch: object({ file: nullable(string), build: string }, ["file", "build"]),
-  next: string
-}, ["version", "host", "connection", "index", "tools", "database", "indexPath", "defaultScope", "recall", "unguardedAgents"]);
+  nextStep: string
+}, ["version", "host", "state", "index", "tools", "database", "indexPath", "indexBytes", "masksChanged", "defaultScope", "recall", "unguardedAgents", "nextStep"]);
 var errors = { failed: object({ code: string, next: string }, ["code", "next"]) };
 var History = Rpc.define({
   id: PLUGIN_ID,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@joe-broadhead/opencode-history",
-  "version": "0.0.0",
+  "version": "0.0.1",
   "description": "Unofficial OpenCode plugin: search, read and recall your past OpenCode sessions",
   "keywords": [
     "opencode",
@@ -107,7 +107,7 @@
     "typecheck": "tsc --noEmit",
     "test": "vitest run --maxWorkers=2",
     "build": "node scripts/build.mjs",
-    "test:host": "vitest run -c vitest.host.config.ts && OPENCODE_HOST_VERSION=2.2.4 vitest run -c vitest.host.config.ts",
+    "test:host": "node scripts/test-host.mjs",
     "test:tui": "npx -y bun@1.4.4 test test/tui",
     "test:pack": "npx -y bun@1.4.4 test test/pack",
     "bench": "vitest run -c vitest.bench.config.ts --silent=false",