hffmnnj.cache-protect 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,147 @@
-# Temporary Holding Version
+<p align="center">
+  <img src="https://unpkg.com/hffmnnj.cache-protect@0.1.0/assets/banner.png" alt="Cache Protect: a dark vintage kitchen with a lit gas burner, kettle, and brass clock, captioned 'Keep the warm window safe.'" width="100%">
+</p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# opencode-cache-protect
+
+An OpenCode V2 execution guard that keeps a stale subagent wake from unnecessarily forcing a provider to rebuild a warm prompt cache. It blocks native `subagent` resumes, new `session.prompt` admissions, and context and compaction model dispatch when a non-OpenAI child's last verifiable execution activity is **more than 295 seconds** old. Exactly 295 seconds remains allowed. Official `openai` sessions and identified primary sessions are exempt.
+
+A rejected native tool call tells the orchestrator to spawn a fresh worker, omit `sessionID`, provide a concise handoff (goal, relevant findings, remaining work), and avoid interrupting or duplicating work that is still running. The plugin never spawns the replacement itself, interrupts a worker, deletes history, sends keepalives, or makes provider requests.
+
+Built against OpenCode V2's 2.0.25 plugin API. The optional local `prompt-cache/` entrypoint provides cross-provider context projection without replacing or changing the safety plugin.
+
+## Install
+
+The guard is published as `hffmnnj.cache-protect@0.1.0`; its catalog ID is `hffmnnj.cache-protect`.
+
+Add the package to the `plugins` list in your OpenCode V2 configuration, preserving existing entries:
+
+```json
+{
+  "plugins": [
+    { "package": "hffmnnj.cache-protect" }
+  ]
+}
+```
+
+OpenCode loads the package's `./dist/index.js` export. It watches configuration, so the plugin reloads without restarting the service.
+
+If you previously loaded this checkout by directory, replace that entry with the npm package entry. Do not keep both: the old and new entries would register the same safety hooks twice.
+
+The guard's former `opencode.cache-protect` runtime ID is not retained. It does not use plugin storage, so no persisted state is tied to the old ID and replacing the old entry is safe.
+
+For local development, build the checkout with `bun install --frozen-lockfile` and `bun run build`, then use the checkout's absolute directory as a `package` entry. The directory's `index.ts` loads the built `dist/index.js`.
+
+To disable it, remove only this plugin entry from the current configuration. Do not restore an entire old configuration over concurrent changes. If you also added matching orchestrator guidance, update it to match the 295-second cutoff and no-keepalive policy, or remove it separately.
+
+## What it guards
+
+- `tool.hook("execute.before")` checks native `subagent` calls that include an existing `input.sessionID`. A fresh spawn without that field passes through unchanged.
+- `session.hook("prompt")` checks direct messages to child sessions, including prompts issued internally by the native executor. A fresh child's initial prompt is allowed.
+- `session.hook("context")` checks model-request context preparation. Native retries of already-admitted prompt IDs skip the prompt hook but still wake execution; this check prevents a stale pending prompt from reaching the provider.
+- `session.hook("compaction")` checks compaction requests, which can run before primary context. Neither dispatch hook counts its own attempt as activity.
+- Successfully identified primary sessions (no `parentID`) are not age-restricted. Unreadable or malformed target metadata cannot be classified as primary and fails closed.
+- Official `openai` provider sessions are exempt from the stale-child cutoff. This exemption does not disable the single-main-server safeguard or broaden diagnostic access.
+- Every check shares one **2,000 ms lookup deadline** across its metadata and context reads, with cancellation. Missing, malformed, future, or unreadable required timestamps/history block admission or dispatch rather than silently admitting a potentially stale resume.
+- The safety hooks do not modify inputs, replace the executor/schema, or alter permissions. Other native and plugin hooks remain in control.
+
+## Activity evidence
+
+Activity is derived on demand from native persisted state, with no private activity store or live-only subscription:
+
+| Native evidence | Use |
+| --- | --- |
+| `Session.Info.time.created` | Initial baseline, including a child's first prompt |
+| Assistant `time.created` | Native model step dispatch timestamp projected from `session.step.started` |
+| Assistant `time.streamed` / `time.completed` | Provider-body completion / step settlement |
+| Assistant tool `time.ran` / `time.completed` | Tool call / settlement during a running step; aborted settlement completion is excluded |
+| Completed compaction `time.created`, only when `tokens.output` is positive | Model-backed auto-compaction (a real provider call) |
+
+The latest valid checkpoint wins. `time.idle` is **never** activity, regardless of outcome: both a denied execution and a successful delivered-ID empty wake can advance it without a model call. Native wake/reopen can also mark abandoned tools aborted without executing them again, so those completion timestamps are ignored. Recent real model/tool work remains eligible even with an old terminal idle timestamp. `time.updated`, `viewed`, titles, reads, user/synthetic messages, compaction controls/summaries without model output, tool-input construction timestamps, and the plugin's own setup/attempt times do not refresh activity. Reloading the plugin or reopening the host reconstructs the decision from native checkpoints, not a new initialization time.
+
+## Status snapshot
+
+Discover `cache_protect_status` in Code Mode, then call its returned path with `{}` for the caller or `{ "sessionID": "ses_..." }` for a verified descendant. Siblings, ancestors, unrelated targets, malformed metadata, and lookup failures return a sanitized `unverifiable` result without target details.
+
+The tool returns `status` (`allowed`, `stale`, `exempt_openai`, `exempt_primary`, or `unverifiable`), `policy` (the fixed `durable_meaningful_activity` label), and `cutoffMs`; applicable decisions include `activityAgeMs`. Stale and unverifiable results include a concise fresh-worker handoff. It shares enforcement's calculation and 2,000 ms lookup deadline, and descendant checks are bounded to 32 ancestry levels. It never refreshes activity, messages a session, or makes provider requests. A status is a snapshot, not an admission reservation or override; inspecting or externally running background work never extends freshness.
+
+## Single-main-server safeguard
+
+The default entrypoint verifies that the plugin process owns the managed OpenCode server before any tool execution and before the `prompt`, `context`, `compaction`, `generate`, and `title` session hooks.
+
+On Linux, it compares `process.pid` with the `MainPID` of the fixed `opencode-web-v2.service` user unit through `/usr/bin/systemctl` (5 s timeout, 128-byte output cap).
+
+On Windows, it reads the managed service registration from `$XDG_STATE_HOME/opencode/service.json` (or `~/.local/state/opencode/service.json`). It accepts only loopback HTTP registrations for `127.0.0.1` or `[::1]` with no URL credentials, path, query, or fragment. When the registration carries a password, it authenticates the `/api/info` probe with HTTP Basic authentication and rejects redirects; the advertised PID and version must match the registration, and the registered PID must equal the plugin process. The registration probe has a one-second deadline and fails closed on missing, invalid, unreachable, or mismatched registrations. Registration credentials are never logged. Other platforms retain the fixed systemd-user-unit check. Standalone hosts, non-loopback registrations, and otherwise unregistered hosts remain blocked by design.
+
+Both lookups share one in-flight call and cache a successful match for at most five seconds. A failed lookup within five minutes of a successful verification remains allowed, because a busy host can stall the lookup; a definite PID mismatch blocks immediately and clears that grace. Lookup failure outside the grace period or a mismatch denies with a sanitized `Tool.Error`.
+
+Its shell pre-check rejects commands that would launch an OpenCode CLI (`opencode`, `opencodev2`, or `opencode2`, including `.exe`) directly or through common wrappers, including an unresolved `$CLI`; ordinary file and path arguments remain allowed. On Windows, a line-oriented scan additionally recognizes direct PowerShell invocation forms, including the Desktop `opencode-cli.exe` and `.cmd` or `.bat` launchers; it does not interpret arbitrary scripts or dynamically generated commands. Unsupported or ambiguous forms fail closed.
+
+Heredoc boundary: quoted bodies (for example `python3 - <<'PY'`, `node <<'JS'`, `cat <<'EOF'`) are data and stay allowed, including any `$(...)` or backticks inside them. In unquoted bodies, only `$(...)` and backtick expansions are checked. Heredocs that feed a shell (`bash <<'EOF'`, `cat <<'EOF' | bash`) are checked as shell code, while a non-shell consumer under `bash -c` (for example `bash -c "cat"`) with a quoted body stays allowed. An actual OpenCode command before or after a heredoc still blocks.
+
+It is an accidental-execution safeguard, not an interpreter or hostile-code sandbox, and not isolation from other processes running as the same user. Encoded or interpreted programs and other process-launch paths remain outside the classifier's boundary.
+
+## Limits
+
+- **Execution boundary.** This is an execution guard at native tool, prompt-admission, and context and compaction request hooks, not an isolation or security boundary against arbitrary plugins, direct storage writes, shell/HTTP injection, or auxiliary APIs such as transient generation that do not invoke those hooks.
+- **Admitted retries.** An already-admitted prompt ID retry can still return its original admission and cause native wake, inbox promotion, and terminal/idle transitions. The dispatch guard prevents a stale child provider request; it does not undo previously admitted history or turn the retry API into a typed rejection. Repeated retries, including successful empty wakes, do not refresh freshness.
+- **Checkpoint granularity.** It measures native durable execution checkpoints, not every streaming token. Before the native host publishes a model step (which can be deferred until the first provider output), only earlier persisted activity is available. A long request with no newer durable checkpoint can have additional sends conservatively rejected. The running request itself is never interrupted. Do not automatically duplicate ongoing work.
+- **Compaction visibility.** Native context omits history before the latest completed compaction. A completed compaction counts at its creation time only when `tokens.output` is positive; a hook-supplied or control summary without output tokens never counts. Creation time can only under-state recency. A plugin that supplies output tokens can still count, because plugins are trusted in-process code and the guard targets accidental stale resumes. If no checkpoint is visible, the guard falls back to creation time.
+- **Rejection surfaces.** Rejection text is model-visible in the native tool result. In V2 2.0.25, throwing from the direct prompt admission hook is mapped by the HTTP adapter to a generic `ClientError: UnexpectedStatus: 500`; the actionable `Tool.Error` text is not preserved by that adapter. A rejected new admission fails before inbox insertion or a model request. Dispatch-hook failures instead settle the awakened execution as failed, before primary step creation/provider dispatch.
+- **No cache guarantee.** This does not guarantee any provider's prompt-cache retention, billing behavior, or cache hit rate.
+- **Plugin composition.** Composition with other plugins uses native hook registration, not executor replacement. Compatibility was reviewed statically for a workstreams-style wrapper; combined delegation against a paid provider was not exercised.
+
+## Prompt-cache projection
+
+The separate, optional local `prompt-cache/` entrypoint registers the stateful runtime ID `opencode.prompt-cache`. It does not move, replace, or alter the safety plugin. Build it from a source checkout with `bun run build:prompt-cache` before loading it.
+
+Load it as its own plugin entry after all context-producing plugins, including Goals, Memory, Clef, and any other plugin that injects transient context:
+
+```json
+{
+  "plugins": [
+    { "package": "/path/to/opencode-cache-protect/prompt-cache" }
+  ]
+}
+```
+
+Keep exactly one prompt-cache entry; two copies would both project the same snapshots and duplicate the policy part. Its projection uses the 2.0.32 message-constructor submodule, bundled into its output. Do not externalize the entire AI package here: loading its provider graph can pull incompatible runtime internals into the plugin sandbox. Existing safety dependencies remain pinned.
+
+On primary requests for every model provider, it keeps earlier Goals, Memory, and Clef context snapshots in their original positions and appends changed snapshots. Unchanged payloads are not repeated; the latest revision for each source supersedes older ones. All current payloads and refresh behavior remain available. Retention is intentional and can grow context faster, which may cause earlier compaction. Eligible primary requests always carry exactly one copy of the instruction that snapshots are quoted task data, not instructions, even before the first snapshot appears or after all sources are suppressed; a failed storage read leaves the request untouched.
+
+Native plugin storage retains injected snapshot text, canonical-history hashes, and the request's system hash and model identity. It does not retain a duplicate of the authored conversation or tools. Compaction and genuine model/system/history changes reset the projection; inactive sources are removed to preserve suppression and disable behavior. Auxiliary requests are unchanged. OpenAI storage keys remain compatible; every other provider's state is provider-qualified so identical model IDs cannot share snapshots. No wire hooks, explicit cache fields, warming, retries, TTL overrides, or cache keys are introduced.
+
+Projection can be restricted with `options.sessions`, an array of exact session IDs:
+
+```json
+{
+  "package": "/path/to/opencode-cache-protect/prompt-cache",
+  "options": { "sessions": ["ses_..."] }
+}
+```
+
+Omitting this option enables all eligible sessions; an invalid option disables projection. Diagnostic logs contain session/model identity, snapshot counts, reset state, or a fixed storage-failure category, never prompt text or credentials.
+
+Intentional instruction or catalog changes, compaction, account switches, and provider expiry can still invalidate caches; the projection does not promise cache hits. Actual reuse must be established with ordinary real-work usage; local continuation tests are not evidence of server cache reuse. Explicit checkpoints are deliberately not used. Goals usage counters belong in the full Goals tool response, not the injected request tail; otherwise every tool step creates a new snapshot without changing task state. The cross-provider audit and acceptance scope are in [docs/SPEC.md](https://github.com/hffmnnj/opencode-cache-protect/blob/main/docs/SPEC.md).
+
+Validate the watched artifact in the actual V2 plugin catalog and native requests; a plain Bun import is not an equivalent plugin-loading test.
+
+## Development
+
+Dependencies are pinned. Run these from the checkout:
+
+```sh
+bun install --frozen-lockfile
+bun run typecheck
+bun test tests/unit
+bun run build
+bun run check       # typecheck, deterministic unit tests, both local builds
+bun run test:host   # real isolated SDK 2.0.25 native host
+bun test            # full plugin suite, after build
+```
+
+`bun run check` builds the safety entrypoint (`dist/index.js`) and the local prompt-cache watch entrypoint (`dist/prompt-cache.js` with generated `prompt-cache/index.ts`).
+
+The host test launches a child process with isolated HOME/XDG/config/database paths under `/var/tmp/james/opencode/cache-protect-host-*`. Its only configured provider is a loopback scripted server with a synthetic key. It disables built-in providers and model fetching/snapshots; it does not borrow credentials or make paid calls. Scripted provider requests exercise the real native schema, executor, prompt/context hooks, history, inbox, permission filtering, and package loader. Regressions include stale pending-ID wake, repeated denied/empty wakes, host reopen, and a delivered-ID no-op wake followed by a rejected new stale prompt. Hosts and loopback servers are closed in `finally`; isolated evidence directories are retained rather than recursively deleted.
+
+`registerCacheProtect` exposes an internal injected clock for deterministic tests. This is not a user configuration override; the shipped default always uses `Date.now()` and the fixed cutoff.

package/dist/index.js

@@ -0,0 +1,708 @@
+// @bun
+// src/index.ts
+import { Plugin } from "@opencode/plugin";
+import * as Tool2 from "@opencode/plugin/promise/tool";
+
+// src/server-safety.ts
+import { execFile } from "child_process";
+import * as Tool from "@opencode/plugin/promise/tool";
+
+// src/windows-service-owner.ts
+import { open } from "fs/promises";
+import { homedir } from "os";
+import { join } from "path";
+var MAX_REGISTRATION_BYTES = 16384;
+async function readRegistration(signal) {
+  const state = process.env.XDG_STATE_HOME || join(homedir(), ".local", "state");
+  const file = await open(join(state, "opencode", "service.json"), "r");
+  try {
+    signal.throwIfAborted();
+    const info = await file.stat();
+    if (!info.isFile() || info.size < 1 || info.size > MAX_REGISTRATION_BYTES)
+      throw new Error;
+    const buffer = Buffer.alloc(MAX_REGISTRATION_BYTES + 1);
+    const result = await file.read(buffer, 0, buffer.length, 0);
+    signal.throwIfAborted();
+    if (result.bytesRead < 1 || result.bytesRead > MAX_REGISTRATION_BYTES)
+      throw new Error;
+    return buffer.subarray(0, result.bytesRead).toString("utf8");
+  } finally {
+    await file.close();
+  }
+}
+function record(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error;
+  return value;
+}
+async function windowsServiceMainPID(options = {}) {
+  const controller = new AbortController;
+  let timer;
+  try {
+    const deadline = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => {
+        controller.abort();
+        reject(new Error);
+      }, 1000);
+    });
+    const operation = async () => {
+      const registration = record(JSON.parse(await (options.read ?? readRegistration)(controller.signal)));
+      if (typeof registration.url !== "string" || !Number.isSafeInteger(registration.pid) || registration.pid <= 0 || typeof registration.version !== "string" || !registration.version || registration.password !== undefined && (typeof registration.password !== "string" || !registration.password))
+        throw new Error;
+      const url = new URL(registration.url);
+      if (url.protocol !== "http:" || !["127.0.0.1", "[::1]"].includes(url.hostname) || url.username || url.password || url.pathname !== "/" || url.search || url.hash)
+        throw new Error;
+      const headers = {};
+      if (typeof registration.password === "string") {
+        headers.authorization = `Basic ${Buffer.from(`opencode:${registration.password}`).toString("base64")}`;
+      }
+      const response = await (options.fetch ?? fetch)(new URL("/api/info", url).href, {
+        method: "GET",
+        headers,
+        redirect: "error",
+        signal: controller.signal
+      });
+      if (!response.ok)
+        throw new Error;
+      const info = record(await response.json());
+      if (info.pid !== registration.pid || info.version !== registration.version)
+        throw new Error;
+      return registration.pid;
+    };
+    return await Promise.race([operation(), deadline]);
+  } catch {
+    throw new Error("Main identity unavailable");
+  } finally {
+    if (timer)
+      clearTimeout(timer);
+    controller.abort();
+  }
+}
+
+// src/server-safety.ts
+function documentExpansions(body) {
+  const scripts = [];
+  function substitution(start, backtick) {
+    let quote = "";
+    let parentheses = 0;
+    for (let i = start;i < body.length; i++) {
+      const char = body[i];
+      if (char === "\\" && quote !== "'") {
+        if (backtick && /[$`\\]/.test(body[i + 1] ?? ""))
+          return;
+        i++;
+        continue;
+      }
+      if (quote === "'") {
+        if (char === "'")
+          quote = "";
+        continue;
+      }
+      if (backtick && char === "`") {
+        scripts.push(body.slice(start, i));
+        return i;
+      }
+      if (char === "`" || char === "$" && body[i + 1] === "(") {
+        return;
+      }
+      if (quote) {
+        if (char === quote)
+          quote = "";
+        continue;
+      }
+      if (char === "'" || char === '"') {
+        quote = char;
+        continue;
+      }
+      if (char === "#" || char === "<" && body[i + 1] === "<")
+        return;
+      if (!backtick && char === "(")
+        parentheses++;
+      if (!backtick && char === ")") {
+        if (parentheses-- === 0) {
+          scripts.push(body.slice(start, i));
+          return i;
+        }
+      }
+    }
+    return;
+  }
+  for (let i = 0;i < body.length; i++) {
+    if (body[i] === "\\" && /[$`\\\n]/.test(body[i + 1] ?? "")) {
+      i++;
+      continue;
+    }
+    if (body[i] !== "`" && !(body[i] === "$" && body[i + 1] === "("))
+      continue;
+    const end = substitution(i + (body[i] === "`" ? 1 : 2), body[i] === "`");
+    if (end === undefined)
+      return;
+    i = end;
+  }
+  return scripts;
+}
+function tokens(command) {
+  const result = [];
+  const documents = [];
+  let value = "";
+  let started = false;
+  let quote = "";
+  let grouping = 0;
+  const flush = () => {
+    if (started)
+      result.push({ value, separator: false });
+    value = "";
+    started = false;
+  };
+  for (let i = 0;i < command.length; i++) {
+    const char = command[i];
+    if (char === "\\" && quote !== "'" && i + 1 < command.length) {
+      const next = command[++i];
+      if (next !== `
+`) {
+        value += next;
+        started = true;
+      }
+    } else if (quote) {
+      if (char === quote)
+        quote = "";
+      else
+        value += char;
+    } else if (char === "#" && !started) {
+      const newline = command.indexOf(`
+`, i);
+      i = newline === -1 ? command.length : newline - 1;
+    } else if (char === "<" && command[i - 1] !== "<" && command[i + 1] === "<" && command[i + 2] !== "<") {
+      if (grouping)
+        return;
+      if (/^\d+$/.test(value)) {
+        value = "";
+        started = false;
+      }
+      flush();
+      let cursor = i + 2;
+      const stripTabs = command[cursor] === "-";
+      if (stripTabs)
+        cursor++;
+      while (command[cursor] === " " || command[cursor] === "\t")
+        cursor++;
+      let delimiter = "";
+      let delimiterQuote = "";
+      let quoted = false;
+      let delimiterStarted = false;
+      for (;cursor < command.length; cursor++) {
+        const next = command[cursor];
+        if (next === `
+` && delimiterQuote)
+          return;
+        if (!delimiterQuote && /[\s;|&()<>{}]/.test(next))
+          break;
+        delimiterStarted = true;
+        if (next === "\\" && delimiterQuote !== "'") {
+          const escaped = command[++cursor];
+          if (escaped === undefined || escaped === `
+`)
+            return;
+          if (delimiterQuote === '"' && !/[$`"\\]/.test(escaped))
+            delimiter += "\\";
+          delimiter += escaped;
+          quoted = true;
+        } else if (delimiterQuote) {
+          if (next === delimiterQuote)
+            delimiterQuote = "";
+          else
+            delimiter += next;
+        } else if (next === "'" || next === '"') {
+          delimiterQuote = next;
+          quoted = true;
+        } else if (next === "$" || next === "`")
+          return;
+        else
+          delimiter += next;
+      }
+      if (!delimiterStarted || delimiterQuote)
+        return;
+      const token = { value: "", separator: false, body: "" };
+      result.push(token);
+      documents.push({ delimiter, quoted, stripTabs, token });
+      i = cursor - 1;
+    } else if (char === "'" || char === '"') {
+      quote = char;
+      started = true;
+    } else if (`;|&
+(){}`.includes(char)) {
+      flush();
+      if (documents.length && ("(){}".includes(char) || char === "&" && command[i - 1] === "|" || char === `
+` && result.at(-1)?.value === "|"))
+        return;
+      if (char === "(" || char === "{")
+        grouping++;
+      if (char === ")" || char === "}")
+        grouping = Math.max(0, grouping - 1);
+      result.push({ value: char, separator: true });
+      if (char === `
+` && documents.length) {
+        let cursor = i + 1;
+        for (const document of documents) {
+          let body = "";
+          let closed = false;
+          while (cursor < command.length) {
+            const newline = command.indexOf(`
+`, cursor);
+            const end = newline === -1 ? command.length : newline;
+            const line = command.slice(cursor, end);
+            const content = document.stripTabs ? line.replace(/^\t+/, "") : line;
+            cursor = newline === -1 ? command.length : newline + 1;
+            if (content === document.delimiter) {
+              closed = true;
+              break;
+            }
+            body += content + (newline === -1 ? "" : `
+`);
+          }
+          if (!closed)
+            return;
+          document.token.body = body;
+          if (!document.quoted) {
+            if (body.includes("\\\n"))
+              return;
+            const expansions = documentExpansions(body);
+            if (!expansions)
+              return;
+            for (const expansion of expansions)
+              result.push({ value: "", separator: false, expansion });
+          }
+        }
+        documents.length = 0;
+        i = cursor - 1;
+      }
+    } else if (/\s/.test(char))
+      flush();
+    else {
+      value += char;
+      started = true;
+    }
+  }
+  flush();
+  return documents.length ? undefined : result;
+}
+function leaf(value) {
+  return value.replaceAll("\\", "/").split("/").at(-1).toLowerCase();
+}
+function isWindowsOpenCodeShellCommand(command) {
+  const heads = /(?:^|[;&|\r\n])\s*(?:&\s*)?(?:"([^"]+)"|'([^']+)'|([^\s;&|]+))/g;
+  for (const match of command.matchAll(heads)) {
+    const name = leaf(match[1] ?? match[2] ?? match[3] ?? "");
+    if (/^opencode(?:-cli|v2|2)?(?:\.exe|\.cmd|\.bat)?$/.test(name))
+      return true;
+  }
+  return false;
+}
+function isOpenCodeShellCommand(command) {
+  if (process.platform === "win32" && !command.includes("<<") && isWindowsOpenCodeShellCommand(command))
+    return true;
+  return classify(command, new Map, 0);
+}
+function classify(command, variables, depth) {
+  if (depth > 8)
+    return true;
+  const words = tokens(command);
+  if (!words)
+    return true;
+  let executable = true;
+  let wrapper = "";
+  let skip = false;
+  for (let i = 0;i < words.length; i++) {
+    const token = words[i];
+    if (token.expansion !== undefined) {
+      if (classify(token.expansion, new Map(variables), depth + 1))
+        return true;
+      continue;
+    }
+    if (token.body !== undefined)
+      continue;
+    if (token.separator) {
+      executable = true;
+      wrapper = "";
+      skip = false;
+      continue;
+    }
+    if (!executable)
+      continue;
+    let word = token.value;
+    const assignment = /^([A-Za-z_][A-Za-z0-9_]*)=(.*)$/s.exec(word);
+    if (assignment) {
+      variables.set(assignment[1], assignment[2]);
+      continue;
+    }
+    word = word.replace(/\$(?:\{([A-Za-z_][A-Za-z0-9_]*)\}|([A-Za-z_][A-Za-z0-9_]*))/g, (original, braced, bare) => variables.get(braced ?? bare) ?? original);
+    if (skip) {
+      skip = false;
+      continue;
+    }
+    if (word.startsWith("-") && wrapper) {
+      if (wrapper === "env" && ["-u", "--unset", "-C", "--chdir"].includes(word) || wrapper === "timeout" && ["-s", "--signal", "-k", "--kill-after"].includes(word))
+        skip = true;
+      continue;
+    }
+    const name = leaf(word);
+    if (/^\$(?:CLI|\{CLI\})$/.test(word))
+      return true;
+    if (/^opencode(?:v2|2)?(?:\.exe)?$/.test(name))
+      return true;
+    if (["env", "command", "exec", "nohup", "timeout"].includes(name)) {
+      wrapper = name;
+      continue;
+    }
+    if (wrapper === "timeout" && /^\d/.test(word)) {
+      wrapper = "";
+      continue;
+    }
+    if (["sh", "bash", "dash", "zsh", "ksh"].includes(name)) {
+      let end = i + 1;
+      while (end < words.length && !words[end].separator)
+        end++;
+      const args = words.slice(i + 1, end).filter((arg) => arg.body === undefined);
+      let commandString = false;
+      let optionPosition = true;
+      for (let j = 0;j < args.length; j++) {
+        if (!args[j].value.startsWith("-") || ["-", "--"].includes(args[j].value))
+          optionPosition = false;
+        if (/^-[a-z]*c[a-z]*$/.test(args[j].value)) {
+          const script = args[j + 1];
+          if (!script || classify(script.value, new Map(variables), depth + 1))
+            return true;
+          commandString = optionPosition;
+          break;
+        }
+      }
+      if (!commandString) {
+        let start = i;
+        while (start > 0 && (!words[start - 1].separator || words[start - 1].value === "|"))
+          start--;
+        const bodies = words.slice(start, end).filter((part) => part.body !== undefined);
+        if (bodies.length) {
+          if (args.some((arg) => !["-", "--"].includes(arg.value) && !/^-[abefhkmnptuvxBCEHPTsil]+$/.test(arg.value)))
+            return true;
+          for (const document of bodies) {
+            if (classify(document.body, new Map(variables), depth + 1))
+              return true;
+          }
+        }
+      }
+    }
+    if (["then", "do", "else", "if", "elif", "!"].includes(word))
+      continue;
+    executable = false;
+    wrapper = "";
+  }
+  return false;
+}
+function mainPID() {
+  if (process.platform === "win32")
+    return windowsServiceMainPID();
+  return new Promise((resolve, reject) => {
+    execFile("/usr/bin/systemctl", ["--user", "show", "opencode-web-v2.service", "--property=MainPID", "--value"], { timeout: LOOKUP_TIMEOUT_MS, maxBuffer: 128, encoding: "utf8" }, (error, stdout) => {
+      if (error || !/^\d+\s*$/.test(stdout)) {
+        reject(new Error("Main identity unavailable"));
+        return;
+      }
+      resolve(Number(stdout.trim()));
+    });
+  });
+}
+var LOOKUP_TIMEOUT_MS = 5000;
+var FRESH_MS = 5000;
+var LOOKUP_GRACE_MS = 5 * 60000;
+async function registerServerSafety(ctx, runtime = {}) {
+  const pid = runtime.pid ?? process.pid;
+  const resolveMainPID = runtime.mainPID ?? mainPID;
+  const now = runtime.now ?? (() => performance.now());
+  let verifiedAt;
+  let checkedAt;
+  let inflight;
+  const blocked = () => new Tool.Error({ message: "Server safety blocked execution: this process could not be verified as the single main OpenCode server. Use the existing main server's native tools; do not launch another server or CLI session." });
+  async function verify() {
+    let expected;
+    try {
+      expected = await resolveMainPID();
+    } catch {
+      if (verifiedAt !== undefined && now() - verifiedAt < LOOKUP_GRACE_MS) {
+        checkedAt = now();
+        return;
+      }
+      verifiedAt = checkedAt = undefined;
+      throw blocked();
+    }
+    if (!Number.isSafeInteger(expected) || expected <= 0 || expected !== pid) {
+      verifiedAt = checkedAt = undefined;
+      throw blocked();
+    }
+    verifiedAt = checkedAt = now();
+  }
+  async function ownerGuard() {
+    if (checkedAt !== undefined && now() - checkedAt < FRESH_MS)
+      return;
+    inflight ??= verify().finally(() => {
+      inflight = undefined;
+    });
+    await inflight;
+  }
+  const registrations = [];
+  const dispose = async () => {
+    await Promise.all(registrations.map((registration) => registration.dispose()));
+  };
+  try {
+    registrations.push(await ctx.tool.hook("execute.before", async (event) => {
+      await ownerGuard();
+      if (event.tool !== "shell")
+        return;
+      const input = event.input;
+      if (input && typeof input === "object" && "command" in input && typeof input.command === "string" && isOpenCodeShellCommand(input.command)) {
+        throw new Tool.Error({ message: "Server safety blocked an OpenCode CLI shell command. Use native subagent/tools and the existing main server API; do not launch another OpenCode process." });
+      }
+    }));
+    for (const name of ["prompt", "context", "compaction", "generate", "title"]) {
+      registrations.push(await ctx.session.hook(name, ownerGuard));
+    }
+    return dispose;
+  } catch (error) {
+    await dispose();
+    throw error;
+  }
+}
+
+// src/index.ts
+var MAX_INACTIVITY_MS = 295000;
+var LOOKUP_DEADLINE_MS = 2000;
+var MAX_ANCESTRY_DEPTH = 32;
+var HANDOFF = "Spawn a fresh subagent: omit sessionID and provide a concise handoff (goal, relevant findings, remaining work). Do not interrupt or duplicate work that is still running.";
+function record2(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value))
+    throw new Error("Invalid metadata");
+  return value;
+}
+function timestamp(value, now) {
+  if (!Number.isFinite(now) || now < 0 || typeof value !== "number" || !Number.isFinite(value) || value < 0 || value > now) {
+    throw new Error("Invalid activity timestamp");
+  }
+  return value;
+}
+function modelBackedCompaction(compaction) {
+  const output = record2(compaction.tokens ?? {}).output;
+  return typeof output === "number" && output > 0;
+}
+function lastActivity(info, context, now) {
+  const time = record2(info.time);
+  let last = timestamp(time.created, now);
+  if (!Array.isArray(context))
+    throw new Error("Invalid session context");
+  for (const item of context) {
+    const message = record2(item);
+    if (message.type === "compaction") {
+      if (modelBackedCompaction(message))
+        last = Math.max(last, timestamp(record2(message.time).created, now));
+      continue;
+    }
+    if (message.type !== "assistant")
+      continue;
+    const times = record2(message.time);
+    last = Math.max(last, timestamp(times.created, now));
+    for (const key of ["streamed", "completed"]) {
+      if (times[key] !== undefined)
+        last = Math.max(last, timestamp(times[key], now));
+    }
+    if (!Array.isArray(message.content))
+      throw new Error("Invalid assistant context");
+    for (const part of message.content) {
+      const content = record2(part);
+      if (content.type !== "tool")
+        continue;
+      const toolTime = record2(content.time);
+      for (const key of ["ran", "completed"]) {
+        if (key === "completed" && content.state !== undefined) {
+          const state = record2(content.state);
+          if (state.status === "error" && record2(state.error).type === "aborted")
+            continue;
+        }
+        if (toolTime[key] !== undefined)
+          last = Math.max(last, timestamp(toolTime[key], now));
+      }
+    }
+  }
+  return last;
+}
+async function boundedLookup(operation, signal) {
+  const controller = new AbortController;
+  const deadline = performance.now() + LOOKUP_DEADLINE_MS;
+  const checkDeadline = () => {
+    controller.signal.throwIfAborted();
+    if (performance.now() > deadline)
+      throw new Error("Activity lookup deadline");
+  };
+  let timer;
+  let onAbort;
+  try {
+    if (signal?.aborted)
+      throw new Error("Cancelled");
+    const result = await Promise.race([
+      operation({ signal: controller.signal, check: checkDeadline }),
+      new Promise((_, reject) => {
+        timer = setTimeout(() => {
+          controller.abort();
+          reject(new Error("Activity lookup deadline"));
+        }, LOOKUP_DEADLINE_MS);
+        onAbort = () => {
+          controller.abort();
+          reject(new Error("Cancelled"));
+        };
+        signal?.addEventListener("abort", onAbort, { once: true });
+        if (signal?.aborted)
+          onAbort();
+      })
+    ]);
+    checkDeadline();
+    return result;
+  } finally {
+    clearTimeout(timer);
+    if (onAbort)
+      signal?.removeEventListener("abort", onAbort);
+    controller.abort();
+  }
+}
+async function getInfo(ctx, sessionID, lookup) {
+  const info = record2(await ctx.session.get({ sessionID }, { signal: lookup.signal }));
+  lookup.check();
+  if (info.id !== sessionID)
+    throw new Error("Target mismatch");
+  return info;
+}
+async function decide(ctx, sessionID, lookup, now, existing) {
+  const info = existing ?? await getInfo(ctx, sessionID, lookup);
+  timestamp(record2(info.time).created, now());
+  if (record2(info.model ?? {}).providerID === "openai")
+    return { status: "exempt_openai" };
+  if (info.parentID === undefined)
+    return { status: "exempt_primary" };
+  if (typeof info.parentID !== "string" || !info.parentID)
+    throw new Error("Invalid parent");
+  const context = await ctx.session.context({ sessionID }, { signal: lookup.signal });
+  lookup.check();
+  const checkedAt = now();
+  if (!Number.isFinite(checkedAt) || checkedAt < 0)
+    throw new Error("Invalid clock");
+  const activityAgeMs = checkedAt - lastActivity(info, context, checkedAt);
+  return { status: activityAgeMs > MAX_INACTIVITY_MS ? "stale" : "allowed", activityAgeMs };
+}
+async function registerCacheProtect(ctx, runtime = {}) {
+  const now = runtime.now ?? Date.now;
+  async function guard(sessionID) {
+    if (typeof sessionID !== "string" || sessionID.length === 0) {
+      throw new Tool2.Error({ message: `Cache protection could not verify the target session. ${HANDOFF}` });
+    }
+    let decision;
+    try {
+      decision = await boundedLookup((lookup) => decide(ctx, sessionID, lookup, now));
+    } catch {
+      throw new Tool2.Error({ message: `Cache protection could not verify the target session's activity; further delivery or model dispatch was blocked. ${HANDOFF}` });
+    }
+    if (decision.status === "stale") {
+      throw new Tool2.Error({ message: `Cache protection blocked this subagent: last meaningful activity was more than 295 seconds ago. ${HANDOFF}` });
+    }
+  }
+  const tool = await ctx.tool.hook("execute.before", async (event) => {
+    if (event.tool !== "subagent")
+      return;
+    if (!event.input || typeof event.input !== "object" || Array.isArray(event.input))
+      return;
+    const input = event.input;
+    if (input.sessionID !== undefined)
+      await guard(input.sessionID);
+  });
+  const registrations = [tool];
+  const dispose = async () => {
+    await Promise.all(registrations.map((registration) => registration.dispose()));
+  };
+  try {
+    for (const name of ["prompt", "context", "compaction"]) {
+      registrations.push(await ctx.session.hook(name, (event) => guard(event.sessionID)));
+    }
+    return dispose;
+  } catch (error) {
+    await dispose();
+    throw error;
+  }
+}
+async function registerCacheProtectStatus(ctx, runtime = {}) {
+  const registration = await ctx.tool.transform((editor) => {
+    editor.add({
+      name: "cache_protect_status",
+      description: "Read-only freshness snapshot for this session or a verified descendant. Not an admission reservation.",
+      input: { type: "object", properties: { sessionID: { type: "string", minLength: 1, description: "Optional existing session ID; defaults to the caller." } }, additionalProperties: false },
+      output: { type: "object", properties: { status: { type: "string", enum: ["allowed", "stale", "exempt_openai", "exempt_primary", "unverifiable"] }, policy: { type: "string" }, cutoffMs: { type: "number" }, activityAgeMs: { type: "number" }, guidance: { type: "string" } }, required: ["status", "policy", "cutoffMs"], additionalProperties: false },
+      options: { codemode: true },
+      execute: async (input, context) => {
+        const base = { policy: "durable_meaningful_activity", cutoffMs: MAX_INACTIVITY_MS };
+        try {
+          const args = record2(input);
+          if (Object.keys(args).some((key) => key !== "sessionID"))
+            throw new Error("Invalid input");
+          const caller = context.sessionID;
+          const target = args.sessionID === undefined ? caller : args.sessionID;
+          if (typeof caller !== "string" || !caller || typeof target !== "string" || !target)
+            throw new Error("Invalid session");
+          const decision = await boundedLookup(async (lookup) => {
+            let current = target;
+            let targetInfo;
+            const seen = new Set;
+            if (target !== caller) {
+              let verified = false;
+              for (let depth = 0;depth < MAX_ANCESTRY_DEPTH; depth++) {
+                if (seen.has(current))
+                  throw new Error("Cyclic ancestry");
+                seen.add(current);
+                const info = await getInfo(ctx, current, lookup);
+                targetInfo ??= info;
+                if (typeof info.parentID !== "string" || !info.parentID)
+                  throw new Error("Not a descendant");
+                if (info.parentID === caller) {
+                  verified = true;
+                  break;
+                }
+                current = info.parentID;
+              }
+              if (!verified)
+                throw new Error("Ancestry depth exceeded");
+            }
+            return decide(ctx, target, lookup, runtime.now ?? Date.now, targetInfo);
+          }, context.signal);
+          return { output: { ...base, ...decision, ...decision.status === "stale" ? { guidance: HANDOFF } : {} } };
+        } catch {
+          return { output: { ...base, status: "unverifiable", guidance: HANDOFF } };
+        }
+      }
+    });
+  });
+  return () => registration.dispose();
+}
+var src_default = Plugin.define({ id: "hffmnnj.cache-protect", setup: async (ctx) => {
+  const safety = await registerServerSafety(ctx);
+  let cache;
+  try {
+    cache = await registerCacheProtect(ctx);
+    const status = await registerCacheProtectStatus(ctx);
+    const disposeCache = cache;
+    return async () => {
+      await Promise.all([status(), disposeCache(), safety()]);
+    };
+  } catch (error) {
+    await Promise.all([...cache ? [cache()] : [], safety()]);
+    throw error;
+  }
+} });
+export {
+  MAX_INACTIVITY_MS,
+  src_default as default,
+  registerCacheProtect,
+  registerCacheProtectStatus
+};

package/index.ts

@@ -0,0 +1,2 @@
+// V2 2.0.25 discovers this directory entrypoint, not package exports alone.
+export { default } from "./dist/index.js?revision=89e870d2d1a1619d01b631fc3a59addd18acbd35193334626e0310af27fe5dbc";

package/package.json

@@ -1,6 +1,35 @@
 {
   "name": "hffmnnj.cache-protect",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "type": "module",
+  "exports": { ".": "./dist/index.js" },
+  "files": [
+    "dist/index.js",
+    "index.ts",
+    "README.md",
+    "assets/banner.png"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hffmnnj/opencode-cache-protect.git"
+  },
+  "publishConfig": { "access": "public" },
+  "dependencies": {
+    "@opencode/ai": "2.0.32",
+    "@opencode/plugin": "2.0.25"
+  },
+  "devDependencies": {
+    "@opencode/sdk": "2.0.25",
+    "@types/bun": "1.3.5",
+    "typescript": "5.9.3"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "build": "bun build ./src/index.ts --outfile ./dist/index.js --target bun --external '@opencode/*'",
+    "build:prompt-cache": "bun ./scripts/build-prompt-cache.ts",
+    "prepack": "bun run build",
+    "test": "bun test tests/unit",
+    "test:host": "bun test tests/host",
+    "check": "bun run typecheck && bun run test && bun run build && bun run build:prompt-cache"
+  }
+}