seisin 0.5.0 → 0.6.0

package/src/keys.js

@@ -28,10 +28,10 @@
  * still reaches the process and the agent can still read it. That is a strict
  * improvement over a plaintext file — the secret stops living on disk, the
  * policy holds a reviewable reference instead of a path, and every resolution
- * is logged without its value — but it is not "the agent never sees it". That
- * is `inject`, it costs terminating the role's TLS with a CA of your own, and
- * it is not built. `modeOf` refuses it by name rather than letting it read as
- * available.
+ * is logged without its value (`event: "key"`, see commands/run.js) — but it is not "the agent never sees it". That
+ * is `inject`, which costs terminating the role's TLS with a CA of your own and
+ * is Linux-only for now (see `injectGate` and `injectKeysOf` below); off Linux
+ * `modeOf` holds it, with the reason in the message.
  *
  * ## Why the value is never written down
  *
@@ -41,6 +41,7 @@
  */
 import { spawnSync } from "node:child_process";
 import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
 import { resolve, isAbsolute, delimiter } from "node:path";
 import { BASE, DEFAULTS } from "./env.js";
 import { SOCK_ENV } from "./spool.js";
@@ -197,7 +198,8 @@ const unterminate = (v) => v.replace(/\r?\n$/, "");
 function fromJson(obj, key, ref) {
   let v = Object.prototype.hasOwnProperty.call(obj, key) ? obj[key] : undefined;
   if (v === undefined && key.includes(".")) {
-    v = key.split(".").reduce((o, k) => (o && typeof o === "object" ? o[k] : undefined), obj);
+    v = key.split(".").reduce((o, k) =>
+      (o && typeof o === "object" && Object.hasOwn(o, k) ? o[k] : undefined), obj);
   }
   if (v === undefined) {
     const top = Object.keys(obj).slice(0, 8).join(", ");
@@ -251,7 +253,7 @@ function dotEnvValue(raw, ref, key) {
     const rest = v.slice(end + 1).trim();
     if (rest && !rest.startsWith("#"))
       throw new Error(
-        `key "${ref}": ${key}= has text after its closing quote (${rest.slice(0, 20)}…).\n` +
+        `key "${ref}": ${key}= has text after its closing quote.\n` +
         `  Loaders disagree on what that value is. Quote the whole value.`);
     const inner = v.slice(1, end);
     // Inside double quotes dotenv turns \n and \r into the characters — the
@@ -316,7 +318,7 @@ function fromDotEnv(text, key, ref) {
  * differently depending on where you were standing when you typed the command
  * is a key that works in your shell and fails in the agent's.
  */
-export function readFileRef(entry, root = ".") {
+export function readFileRef(entry, root = ".", { exact = false } = {}) {
   const hash = entry.ref.lastIndexOf("#");
   const path = hash === -1 ? entry.ref : entry.ref.slice(0, hash);
   const key = hash === -1 ? null : entry.ref.slice(hash + 1);
@@ -331,7 +333,11 @@ export function readFileRef(entry, root = ".") {
   }
   let value;
   if (key === null) {
-    value = unterminate(text);
+    // `exact` (run-file) hands the file over byte for byte: the file is the
+    // value, and an ssh key without its last newline is an invalid ssh key.
+    if (unterminate(text) === "")
+      throw new Error(`key "${entry.raw}": ${full} is empty. An empty credential is not a credential.`);
+    value = exact ? text : unterminate(text);
   } else {
     // Sniffed, not taken from the extension. The file that motivated this was
     // named `.txt` and the one before it `.env`; the name is a hint and the
@@ -354,8 +360,8 @@ export function readFileRef(entry, root = ".") {
  *   - **What seisin itself injects.** `SEISIN_ROLE` is how the hook inside the
  *     sandbox learns which role it is. A key called that would let a policy tell
  *     the hook it is somebody else — privilege confusion written in the one
- *     file that is supposed to prevent it. Same for the config path and the
- *     audit socket.
+ *     file that is supposed to prevent it. Same for the config path, the
+ *     audit socket and the handoff chain.
  *   - **What the child needs to be a child.** `keys = ["keychain://path"]`
  *     derives `PATH`, and the measured result is the sandbox failing with
  *     `env: node: No such file or directory` — a config mistake that reads
@@ -367,13 +373,15 @@ export function readFileRef(entry, root = ".") {
  * catches it and nobody debugs it from inside a sandbox.
  */
 export const RESERVED_ENV = new Set([
-  "SEISIN_ROLE", "SEISIN_CONFIG", SOCK_ENV,
+  // The last is handoff.js's CHAIN_ENV, spelled out: handoff.js reaches this
+  // module through owners.js, and importing it back would be a cycle.
+  "SEISIN_ROLE", "SEISIN_CONFIG", SOCK_ENV, "SEISIN_HANDOFF_CHAIN",
   ...BASE, ...Object.keys(DEFAULTS),
 ]);
 
 /**
  * Every delivered name a role's keys would claim — the variable, and for
- * `scratch` the `_FILE` that carries the path.
+ * `run-file` the `_FILE` that carries the path.
  *
  * Checked as a set because two keys resolving to one name is the other half of
  * the same failure: `keys = ["T=a://x", "T=b://y"]` used to deliver the second
@@ -417,7 +425,7 @@ export function entriesOf(role) {
 /**
  * The three ways a resolved value can reach a role.
  *
- * The middle one is called `scratch` and not `file`, which looks like a
+ * The middle one is called `run-file` and not `file`, which looks like a
  * cosmetic choice and is not. The runtime has a field named
  * `credentials.files`, it is the one that looks like seisin's `keys` (both take
  * paths), and on macOS it does **not** mask — it makes the file unreadable, so
@@ -427,12 +435,40 @@ export function entriesOf(role) {
  * runtime. A mode called `file` sitting ten centimetres from a runtime field
  * called `files` that fails that way is a trap with a date on it.
  *
- * `scratch` said what happened when it was named: the value landed in scratch
- * space and was removed after the run, which `file` does not say at all. Since
- * the 2026-09-23 fix it lands in the run's private directory instead (rundir.js),
- * and the name is a breaking rename listed in docs/glossary.md, not made here.
+ * `run-file` says what happens: the value lands in a file in the run directory
+ * (rundir.js) and goes when the run does, which `file` does not say at all. It
+ * was `scratch` until 0.6.0, from when the file sat in shared scratch space;
+ * since the 2026-09-23 fix it has not, and a name that says the place it left
+ * is the leak that fix closed, said again. RETIRED_MODES refuses the old name.
  */
-export const MODES = ["env", "scratch", "inject"];
+export const MODES = ["env", "run-file", "inject"];
+
+/**
+ * Mode names that were renamed, and the name now. Refused with that sentence
+ * wherever a mode is read (config.js for the policy, modeOf for a role built by
+ * hand), never read as the new one: a policy says one thing in one word.
+ */
+export const RETIRED_MODES = { scratch: "run-file" };
+
+/** The error for a mode that is not one, with the rename when there was one. */
+export function unknownMode(where, setting, mode) {
+  const now = Object.hasOwn(RETIRED_MODES, mode) ? RETIRED_MODES[mode] : null;
+  if (now)
+    return new Error(
+      `${where} ${setting} = "${mode}" was renamed "${now}" in seisin 0.6.0 — the file is ` +
+      `written to the run directory, not to scratch.\n` +
+      `  Change it to ${setting} = "${now}". Nothing else changes: same file, same _FILE variable.`);
+  return new Error(
+    `${where} ${setting} = "${mode}" is not a delivery mode. Known: ${MODES.join(", ")}.` +
+    // The one wrong answer named, because it is the word everybody
+    // reaches for and it is one letter from a runtime field that fails
+    // silently. Guessing costs a debugging session; saying so costs a line.
+    (mode === "file"
+      ? `\n  "file" is not one of them on purpose — the runtime has a "credentials.files" that ` +
+        `takes paths and, on macOS, makes them unreadable instead of masking. The mode that ` +
+        `hands a role a file is "run-file".`
+      : ""));
+}
 
 /**
  * How a role receives its reference keys, and where that is written.
@@ -453,9 +489,18 @@ export const MODES = ["env", "scratch", "inject"];
  * because the two available answers differ in what the agent can walk away
  * with, and picking one for somebody is picking how much a leak costs them.
  */
+/**
+ * The delivery mode a role declares for an entry — the role's `key_mode` first,
+ * else the provider's `mode`, else null. The precedence rule (role over
+ * provider) lives here so {@link modeOf} and {@link injectKeysOf} cannot drift.
+ */
+function declaredMode(config, role, entry) {
+  return role.keyMode ?? config.keyProviders?.[entry.scheme]?.mode ?? null;
+}
+
 export function modeOf(config, role, entry) {
   const provider = config.keyProviders?.[entry.scheme];
-  const mode = role.keyMode ?? provider?.mode ?? null;
+  const mode = declaredMode(config, role, entry);
   if (mode === null) {
     // A built-in scheme has no `[keys.providers.…]` table to put a default in —
     // declaring one is refused, because a scheme cannot mean two things. So
@@ -468,31 +513,125 @@ export function modeOf(config, role, entry) {
     throw new Error(
       `roles.${role.name}: key "${entry.raw}" has no delivery mode.\n` +
       `  Declare one beside the key: [roles.${role.name}] key_mode = "env".${second}\n` +
-      `  "env" passes the value as ${entry.name}; "scratch" writes it to a file in the ` +
+      `  "env" passes the value as ${entry.name}; "run-file" writes it to a file in the ` +
       `run's private directory, grants that one path, and removes it when the run ends.`);
   }
-  if (mode === "inject")
-    throw new Error(
-      `roles.${role.name}: key_mode = "inject" is not implemented.\n` +
-      `  It is the one mode where the agent never sees the value, and it is not free: the ` +
-      `runtime only masks a credential when the role's TLS is terminated with a CA of ` +
-      `seisin's own — MITM over all of that role's traffic, not just the host holding the ` +
-      `secret. It is refused rather than half-available.\n` +
-      `  Use "env" or "file" today. See docs/decisions.md.`);
-  if (!MODES.includes(mode))
-    throw new Error(
-      `roles.${role.name}: key_mode = "${mode}" is not a delivery mode. Known: ${MODES.join(", ")}.` +
-      // The one wrong answer named, because it is the word everybody
-      // reaches for and it is one letter from a runtime field that fails
-      // silently. Guessing costs a debugging session; saying so costs a line.
-      (mode === "file"
-        ? `\n  "file" is not one of them on purpose — the runtime has a "credentials.files" that ` +
-          `takes paths and, on macOS, makes them unreadable instead of masking. The mode that ` +
-          `hands a role a file is "scratch".`
-        : ""));
+  if (mode === "inject") injectGate(role);
+  if (!MODES.includes(mode)) throw unknownMode(`roles.${role.name}:`, "key_mode", mode);
   return mode;
 }
 
+/**
+ * `inject` is the mode where the agent never sees the value: the runtime hands
+ * the sandbox a sentinel and substitutes the real value on egress to the
+ * credential's declared hosts. It is Linux-only in this version — masked
+ * delivery is validated on the Linux backend; the macOS path is not enabled
+ * yet and is tracked upstream, where the fit for it is a credential computed
+ * per run rather than read from the environment
+ * (anthropics/sandbox-runtime#593). Until that lands, macOS `inject` is held
+ * rather than offered, with the alternatives in the message.
+ */
+function injectGate(role) {
+  if (process.platform === "linux") return;
+  throw new Error(
+    `roles.${role.name}: key_mode = "inject" is not available on ${process.platform} yet.\n` +
+    `  It is Linux-only for now; masked injection on macOS is tracked upstream ` +
+    `(anthropics/sandbox-runtime#593) and enables once that lands.\n` +
+    `  Use "env" or "run-file" here, or run this role on Linux. ` +
+    `See https://github.com/carlostapiacl/seisin/blob/main/docs/decisions.md.`);
+}
+
+/**
+ * The role's `inject` keys as `{ entry, name, hosts }`, the single source both
+ * the settings (srt.js) and `check` read. Throws when the policy is internally
+ * inconsistent — an inject key with no `inject_hosts` entry, or an
+ * `inject_hosts` entry naming a key that is not injected — because either one
+ * is a masked credential that silently injects nowhere, or a host list that
+ * guards nothing. Platform is NOT checked here: this answers "what does the
+ * policy say", and {@link injectGate} answers "can we run it here".
+ */
+export function injectKeysOf(config, role) {
+  const refs = entriesOf(role).filter((e) => e.kind === "ref");
+  const inject = refs.filter((e) => declaredMode(config, role, e) === "inject");
+  const hosts = role.injectHosts ?? {};
+  const out = inject.map((entry) => {
+    const h = hosts[entry.name];
+    if (!h)
+      throw new Error(
+        `roles.${role.name}: key "${entry.raw}" is injected but has no hosts.\n` +
+        `  A masked credential needs the host its token authenticates to:\n` +
+        `    [roles.${role.name}.inject_hosts]\n    ${entry.name} = ["api.example.com"]`);
+    return { entry, name: entry.name, hosts: h };
+  });
+  const named = new Set(out.map((c) => c.name));
+  for (const name of Object.keys(hosts))
+    if (!named.has(name))
+      throw new Error(
+        `roles.${role.name}.inject_hosts.${name}: no injected key delivers ${name}.\n` +
+        `  inject_hosts names the hosts a masked credential may reach; ${name} is not one. ` +
+        `Add a key that delivers it with key_mode = "inject", or remove the entry.`);
+  return out;
+}
+
+/**
+ * How long a provider's stdout is still read after it exits.
+ *
+ * Bytes written just before exit may still be in the pipe. A descendant that
+ * kept the pipe open is not the provider, and its silence is not an answer
+ * worth waiting a minute for.
+ */
+export const PROVIDER_DRAIN_MS = 250;
+
+const HELPER = fileURLToPath(new URL("./provider-run.js", import.meta.url));
+
+/**
+ * Run the provider through provider-run.js, which returns when the provider
+ * exits rather than when every holder of its stdout lets go, and stops it with
+ * SIGKILL at the deadline. The outer call has a deadline of its own, a little
+ * later, so a helper that never answers cannot hold the run either.
+ */
+function spawnProvider(argv, { env, timeoutMs }) {
+  const r = spawnSync(process.execPath,
+    [HELPER, String(timeoutMs), String(PROVIDER_MAX_BYTES), String(PROVIDER_DRAIN_MS), ...argv], {
+      encoding: "utf8", stdio: ["ignore", "pipe", "ignore"], env,
+      timeout: timeoutMs + 5_000, killSignal: "SIGKILL", maxBuffer: PROVIDER_MAX_BYTES * 2 + 4096,
+    });
+  let got = null;
+  try { got = JSON.parse(r.stdout ?? ""); } catch {}
+  if (!got) return { status: null, stdout: "", errBytes: 0, timedOut: true };
+  if (got.error) return { error: new Error(`spawn ${got.error}`) };
+  return {
+    status: got.status, stdout: Buffer.from(got.out, "base64").toString("utf8"),
+    errBytes: got.errBytes, timedOut: got.timedOut, tooBig: got.tooBig,
+  };
+}
+
+/** What a runner of the caller's own returned, in the shape spawnProvider returns. */
+function normalise(r) {
+  return {
+    ...r,
+    timedOut: r.error?.code === "ETIMEDOUT",
+    tooBig: r.error?.code === "ENOBUFS",
+    errBytes: Buffer.byteLength(r.stderr ?? ""),
+  };
+}
+
+/**
+ * The value as a provider or a file gave it, refused if it cannot be delivered.
+ *
+ * A NUL byte cannot be in an environment variable, and Node's refusal to set
+ * one quotes the whole string — the value, in the terminal. Checked here, by a
+ * message that does not carry it.
+ */
+function deliverable(entry, value) {
+  if (value.includes("\0"))
+    throw new Error(
+      `key "${entry.raw}": the value contains a NUL byte, which cannot be delivered.\n` +
+      `  The value is not shown. A credential with a NUL in it is binary; store it encoded ` +
+      `(base64) and decode it where it is used.`);
+  return value;
+}
+
 /**
  * Run a provider and hand back what it printed.
  *
@@ -509,14 +648,19 @@ export function modeOf(config, role, entry) {
  *     cannot measure and says ok lies more than one that says no. A role that
  *     starts without the credential it declared fails later, further away, and
  *     looking like something else.
- *   - **The value is not in the error.** `stderr` from the provider is passed
- *     through because it is how `op` says "not signed in", but `stdout` never
- *     is — a provider that prints the secret and then exits non-zero would
- *     otherwise put it in the terminal and the log.
+ *   - **The value is not in the error.** Neither stream of a failed provider is
+ *     shown. Taking stdout out of stderr was not enough: a provider that printed
+ *     the value only on stderr, or printed it beside other text on stdout, got
+ *     it into the terminal through the error meant to explain it. The error
+ *     says the exit status, how much was written to stderr, and the command to
+ *     run by hand to read it.
+ *
+ * `exact` hands the value back as printed. Without it exactly one trailing
+ * newline comes off, which is right for a variable and wrong for a file.
  */
-export function resolveRef(entry, provider, { run = spawnSync, root = ".", config = null, env = process.env } = {}) {
+export function resolveRef(entry, provider, { run = spawnSync, root = ".", config = null, env = process.env, exact = false, timeoutMs = PROVIDER_TIMEOUT_MS } = {}) {
   if (provider?.builtin === "file" || (provider === undefined && entry.scheme === "file"))
-    return readFileRef(entry, root);
+    return deliverable(entry, readFileRef(entry, root, { exact }));
   const argv = provider.command.map((part) => part.replaceAll("{ref}", entry.ref));
   /**
    * Found where no role can write, and handed the same PATH.
@@ -530,43 +674,46 @@ export function resolveRef(entry, provider, { run = spawnSync, root = ".", confi
    * caller's own, the argv is handed over as given: finding the program is part
    * of spawning it, and whoever replaced the spawn owns that too.
    */
-  const opts = { encoding: "utf8", timeout: PROVIDER_TIMEOUT_MS, maxBuffer: PROVIDER_MAX_BYTES };
+  const opts = { encoding: "utf8", timeout: timeoutMs, killSignal: "SIGKILL", maxBuffer: PROVIDER_MAX_BYTES };
   if (config && run === spawnSync) {
     argv[0] = resolveExecutable(argv[0], config, env);
     opts.env = { ...env, PATH: trustedPath(config, env).join(delimiter) };
   }
-  const r = run(argv[0], argv.slice(1), opts);
-  if (r.error?.code === "ETIMEDOUT")
+  const r = run === spawnSync
+    ? spawnProvider(argv, { env: opts.env, timeoutMs })
+    : normalise(run(argv[0], argv.slice(1), opts));
+  if (r.timedOut)
     throw new Error(
       `key "${entry.raw}": the ${entry.scheme} provider (${argv[0]}) did not answer in ` +
-      `${PROVIDER_TIMEOUT_MS / 1000} s and was stopped.\n` +
+      `${timeoutMs / 1000} s and was killed (SIGKILL).\n` +
       `  A provider that waits on a prompt nobody sees would otherwise hold the run forever.`);
+  if (r.tooBig)
+    throw new Error(
+      `key "${entry.raw}": the ${entry.scheme} provider (${argv[0]}) printed more than ` +
+      `${PROVIDER_MAX_BYTES / 1024 / 1024} MiB on stdout and was stopped.\n` +
+      `  A credential is bytes, not megabytes: check that the command prints one value.`);
   if (r.error)
     throw new Error(
       `key "${entry.raw}": could not run the ${entry.scheme} provider (${argv[0]}): ${r.error.message}`);
   if (r.status !== 0) {
-    // Whatever it printed on stdout is taken out of stderr before stderr is
-    // shown: a provider that echoes the secret to both and then fails would
-    // otherwise put it in the terminal through the error meant to explain it.
-    const leaked = (r.stdout ?? "").trim();
-    const clean = leaked.length >= 4 ? (r.stderr ?? "").split(leaked).join("‹redacted›") : (r.stderr ?? "");
-    const said = clean.trim().split("\n").slice(0, 3).map((l) => l.slice(0, 200)).join("\n    ");
     throw new Error(
-      `key "${entry.raw}": the ${entry.scheme} provider exited ${r.status ?? "on a signal"}.` +
-      (said ? `\n    ${said}` : "") +
-      `\n  Nothing is substituted for a key that did not resolve — the run stops here rather ` +
+      `key "${entry.raw}": the ${entry.scheme} provider exited ${r.status ?? "on a signal"}` +
+      (r.errBytes ? ` and wrote ${r.errBytes} bytes to stderr` : "") + `.\n` +
+      `  What it printed is not shown, because a provider can print the value. To read it, ` +
+      `run it yourself: ${argv.join(" ")}\n` +
+      `  Nothing is substituted for a key that did not resolve — the run stops here rather ` +
       `than starting a role without a credential it declared.`);
   }
+  const printed = r.stdout ?? "";
   // One trailing newline is the shell's, not the secret's: `security -w` and
   // `op read` both add one, and a token with a newline welded to it fails
   // authentication in a way that looks like a wrong token.
-  const value = (r.stdout ?? "").replace(/\r?\n$/, "");
-  if (value === "")
+  if (unterminate(printed) === "")
     throw new Error(
       `key "${entry.raw}": the ${entry.scheme} provider succeeded and printed nothing.\n` +
       `  An empty credential is not a credential. Check the reference — most providers exit 0 ` +
       `for a name they do not have.`);
-  return value;
+  return deliverable(entry, exact ? printed : unterminate(printed));
 }
 
 /**
@@ -576,12 +723,21 @@ export function resolveRef(entry, provider, { run = spawnSync, root = ".", confi
  * provider runs. A config with three bad references should say so once, and it
  * should say so without asking anyone's keychain for a password first.
  */
-export function resolveKeys(config, role, opts = {}) {
+export function resolveKeys(config, role, { record = () => {}, ...opts } = {}) {
   opts = { root: config.root ?? ".", config, ...opts };
-  const refs = role.keyEntries.filter((e) => e.kind === "ref");
+  const refs = entriesOf(role).filter((e) => e.kind === "ref");
   const plan = refs.map((entry) => ({ entry, mode: modeOf(config, role, entry) }));
-  return plan.map((p) => ({
-    ...p,
-    value: resolveRef(p.entry, config.keyProviders[p.entry.scheme], opts),
-  }));
+  return plan.map((p) => {
+    // `run-file` writes a file, and a file is handed over as the provider gave
+    // it; `env` drops the one trailing newline a shell adds. See resolveRef.
+    let value;
+    try {
+      value = resolveRef(p.entry, config.keyProviders[p.entry.scheme], { ...opts, exact: p.mode === "run-file" });
+    } catch (e) {
+      record({ entry: p.entry, mode: p.mode, ok: false });
+      throw e;
+    }
+    record({ entry: p.entry, mode: p.mode, ok: true });
+    return { ...p, value };
+  });
 }

package/src/kinds.js

@@ -19,6 +19,7 @@
  * clock, so it is the same answer on every screen that asks. It never changes
  * what is allowed; it changes what is said about a refusal.
  */
+import { homedir } from "node:os";
 import { CREDENTIAL_HOMES } from "./grants.js";
 
 /** Every kind, in the order a reader should deal with them, and the one line each says. */
@@ -205,3 +206,44 @@ export function kindsOf(targets, opts = {}) {
   }
   return out;
 }
+
+/**
+ * A refusal that is expected, and why — apart from the kinds above.
+ *
+ * The kinds name a path no role owns and the move that fits it. This is the
+ * other case: a path the agent program itself reaches for from inside the
+ * sandbox, that the boundary is right to refuse, and that no move fixes because
+ * nothing is wrong. Claude Code checks for plugin updates on start and writes
+ * the new version into `~/.claude/plugins/cache`; under seisin that write comes
+ * from inside the run and the kernel says no. Plugins run outside the sandbox,
+ * and they update there, from the Claude Code you start without seisin.
+ *
+ * Shown as a wall or as "denied repeatedly", it read as a role stuck on
+ * something to grant — and the only grant that would quiet it is a write into
+ * what Claude Code runs outside the sandbox. So every screen says it apart, as
+ * expected, and none counts it as friction. It changes no verdict.
+ *
+ * Only the cache: the rest of `~/.claude/plugins` (which plugins are installed,
+ * which marketplaces are trusted) is not housekeeping, and a write there stays
+ * an ordinary protected refusal, said in full.
+ */
+export const EXPECTED = {
+  plugins:
+    "Claude Code updating its plugins from inside the sandbox: plugins run outside it and update there, so the denial is expected — nothing to grant",
+};
+
+/**
+ * `{ kind, hint }` when the refusal of `target` is expected, else null.
+ *
+ * `target` as the log keeps it: absolute outside the repository. The home and
+ * `CLAUDE_CONFIG_DIR` are parameters so a test does not depend on the machine.
+ */
+export function expectedOf(target, { home = homedir(), env = process.env } = {}) {
+  const t = String(target ?? "").replace(/\\/g, "/");
+  const roots = [
+    env.CLAUDE_CONFIG_DIR,
+    home && `${home.replace(/\/+$/, "")}/.claude`,
+    "~/.claude",
+  ].filter(Boolean).map((r) => `${String(r).replace(/\/+$/, "")}/plugins/cache`);
+  return roots.some((r) => t === r || t.startsWith(r + "/")) ? { kind: "plugins", hint: EXPECTED.plugins } : null;
+}

package/src/lines.js

@@ -0,0 +1,26 @@
+/** Bounded newline framing for the audit channel and the stdio MCP server. */
+export function lineReader(consume, { maxBytes = 1_000_000, onTooLong } = {}) {
+  let buffer = "", bytes = 0, discarding = false;
+  return (chunk) => {
+    let from = 0;
+    for (;;) {
+      const nl = chunk.indexOf("\n", from);
+      const part = nl === -1 ? chunk.slice(from) : chunk.slice(from, nl);
+      if (!discarding) {
+        bytes += Buffer.byteLength(part);
+        if (bytes > maxBytes) {
+          buffer = ""; bytes = 0; discarding = true;
+          onTooLong?.();
+        } else buffer += part;
+      }
+      if (nl === -1) return;
+      // Discard the entire oversized frame, including any later chunks, up
+      // to its newline. Its suffix is never a fresh request. A burst of many
+      // valid frames, however, is not one oversized frame.
+      if (!discarding && buffer.trim()) consume(buffer);
+      buffer = ""; bytes = 0; discarding = false;
+      from = nl + 1;
+      if (from === chunk.length) return;
+    }
+  };
+}

package/src/log.js

@@ -306,7 +306,12 @@ export function alive(pid) {
  */
 function reapable(lock, staleMs) {
   let seen, mtime;
-  try { seen = readFileSync(lock, "utf8"); mtime = statSync(lock).mtimeMs; } catch { return true; }
+  try { seen = readFileSync(lock, "utf8"); mtime = statSync(lock).mtimeMs; }
+  catch (e) {
+    // Only a disappeared lock is an immediate retry. An unreadable lock or
+    // a directory at this name otherwise spins forever, bypassing deadline.
+    return e.code === "ENOENT";
+  }
   const pid = Number(seen.split(" ")[0]);
   const named = Number.isInteger(pid) && pid > 0;
   // A named holder that is alive is waited on, however long it takes: its age
@@ -499,7 +504,7 @@ export function read(file, { role, verdict, since, limit = 0 } = {}) {
     }
     const got = [];
     for (const e of readEntries(seg)) {
-      if (e.event === "rotated") continue; // a structural marker, not a decision
+      if (e.event === "rotated") continue; // an internal marker, not activity
       if (role && e.role !== role) continue;
       if (verdict && e.verdict !== verdict) continue;
       if (since && e.at < since) continue;