seisin 0.4.2 → 0.6.0

package/src/controls.js

@@ -0,0 +1,244 @@
+/**
+ * Handing a role a family of control files, and protecting instruction files,
+ * as edits a person makes from the console.
+ *
+ * Both settings were only reachable by opening seisin.toml in an editor. That
+ * is fine for whoever wrote the policy and a wall for whoever inherited it:
+ * the console showed the refusal ("protected: .vscode, whose settings … VS
+ * Code applies outside the sandbox") and offered no way to act on it except
+ * approving a request that a grant can never satisfy (refuseIfBarred says so).
+ *
+ * What this module does not do is widen the menu. The families are exactly
+ * config.js's CONTROL_FAMILIES; `.claude/`, git hooks, `.mcp.json` and `.envrc`
+ * are never offered, because they are what a program outside the sandbox executes
+ * and no role writes them — not from the file, not from here.
+ *
+ * Every edit is text, bounded to one table, like applyGrant: comments and the
+ * order a person gave the file survive, and a change for one role can never
+ * land in another role's table.
+ */
+import { createHash } from "node:crypto";
+import { loadConfig, CONTROL_FAMILIES, stripComment, closesArray } from "./config.js";
+import { settingsFor } from "./srt.js";
+import { denyFor } from "./surface.js";
+import { cleanReason } from "./requests.js";
+
+const RE_HEADER = /^\[([A-Za-z0-9_.\-]+)\]$/;
+const RE_KEY = /^([A-Za-z0-9_\-]+)\s*=/;
+
+/** An error that is the caller's fault: the server answers it with 400. */
+function bad(message) {
+  return Object.assign(new Error(message), { status: 400 });
+}
+
+export const hashOf = (text) => createHash("sha256").update(text).digest("hex").slice(0, 24);
+
+/**
+ * The families as the caller sent them, validated and in the canonical order.
+ *
+ * Refused, not filtered: a request for ".claude" is somebody asking for the
+ * one thing this tool will not hand out, and silently dropping it would save a
+ * policy that is not what they asked for.
+ */
+export function normalizeFamilies(families) {
+  if (!Array.isArray(families) || families.some((f) => typeof f !== "string"))
+    throw bad(`families must be a list of names — some of ${CONTROL_FAMILIES.map((f) => JSON.stringify(f)).join(", ")}`);
+  for (const f of families)
+    if (!CONTROL_FAMILIES.includes(f))
+      throw bad(`${JSON.stringify(f)} is not a family of control files. Known: ` +
+        `${CONTROL_FAMILIES.map((x) => JSON.stringify(x)).join(", ")}. The others ` +
+        `(.claude, git hooks, .mcp.json, .envrc) are never handed to a role.`);
+  return CONTROL_FAMILIES.filter((f) => families.includes(f));
+}
+
+/**
+ * The lines of one table: where its header is, where it ends, and each
+ * key's first and last line. A multi-line array is one key, so a line inside
+ * one is never taken for a header or for another key.
+ */
+function tableOf(lines, name) {
+  let header = -1;
+  for (let i = 0; i < lines.length; i++) {
+    const h = RE_HEADER.exec(stripComment(lines[i]).trim());
+    if (h && h[1] === name) { header = i; break; }
+  }
+  if (header === -1) return null;
+  const keys = [];
+  let end = lines.length;
+  for (let i = header + 1; i < lines.length; i++) {
+    const line = stripComment(lines[i]).trim();
+    if (!line) continue;
+    if (RE_HEADER.test(line)) { end = i; break; }
+    const k = RE_KEY.exec(line);
+    if (!k) continue;
+    const from = i;
+    const value = line.slice(line.indexOf("=") + 1).trim();
+    if (value.startsWith("[") && !closesArray(value))
+      while (i + 1 < lines.length && !closesArray(stripComment(lines[++i]).trim()));
+    keys.push({ key: k[1], from, to: i });
+  }
+  return { header, end, keys };
+}
+
+function stamp(note, source = "in the console") {
+  return `# set ${source} ${new Date().toISOString().slice(0, 10)}` +
+    (note ? ` · «${cleanReason(note)}»` : "");
+}
+
+/**
+ * Sets `key = value` inside one table: replaces the line (or the lines, for a
+ * multi-line array) where the key was, or adds it after the table's last key.
+ * The replaced line's own trailing comment goes with it — it described the
+ * value being replaced, and the stamp now describes the new one. Every other
+ * line, comments included, stays byte for byte.
+ */
+export function setKey(text, table, key, value, note, source) {
+  const eol = text.includes("\r\n") ? "\r\n" : "\n";
+  const lines = text.split("\n");
+  const cr = eol === "\r\n" ? "\r" : "";
+  const t = tableOf(lines, table);
+  if (!t) return null;
+  const at = t.keys.find((k) => k.key === key);
+  if (at) {
+    // The same value is no edit: re-stamping it would record a decision
+    // nobody made, and move the date of the one somebody did.
+    const was = lines.slice(at.from, at.to + 1).map((l) => stripComment(l).trim()).join(" ");
+    if (was.slice(was.indexOf("=") + 1).replace(/\s+/g, "").replace(/,\]$/, "]") === value.replace(/\s+/g, "")) return text;
+    const indent = /^\s*/.exec(lines[at.from])[0];
+    const line = `${indent}${key} = ${value}   ${stamp(note, source)}${cr}`;
+    lines.splice(at.from, at.to - at.from + 1, line);
+  } else {
+    // After the last key, not the last line: a comment above the next table
+    // belongs to that table, and a line inserted under it would read as the
+    // next role's.
+    const after = t.keys.length ? t.keys[t.keys.length - 1].to : t.header;
+    lines.splice(after + 1, 0, `${key} = ${value}   ${stamp(note, source)}${cr}`);
+  }
+  return lines.join("\n");
+}
+
+const listOf = (families) => `[${families.map((f) => `"${f}"`).join(", ")}]`;
+
+/**
+ * The policy text with `control_files` of one role set to `families`.
+ *
+ * An empty list is written as `control_files = []` with its stamp when the key
+ * was there, rather than deleted: the line is the record that somebody took
+ * the family away, and when. A role that never had the key and still has none
+ * is left alone.
+ */
+export function applyControlFiles(toml, role, families, note = "") {
+  const want = normalizeFamilies(families);
+  const lines = toml.split("\n");
+  const t = tableOf(lines, `roles.${role}`);
+  if (!t) throw bad(`no [roles.${role}] section in the policy`);
+  if (!want.length && !t.keys.some((k) => k.key === "control_files")) return { toml, changed: false };
+  const out = setKey(toml, `roles.${role}`, "control_files", listOf(want), note);
+  return { toml: out, changed: out !== toml };
+}
+
+/**
+ * The policy text with `[protect] instructions` set.
+ *
+ * A missing `[protect]` table is created only to turn the protection on
+ * (off is the default and needs no line), and it goes above the first role:
+ * it is a setting about every role, and a reader meets it before the roles
+ * it changes. A comment block that sits directly above that role stays with
+ * the role.
+ */
+export function applyProtect(toml, on, note = "") {
+  if (typeof on !== "boolean") throw bad("protect must be true or false");
+  const lines = toml.split("\n");
+  if (tableOf(lines, "protect")) {
+    const out = setKey(toml, "protect", "instructions", String(on), note);
+    return { toml: out, changed: out !== toml };
+  }
+  if (!on) return { toml, changed: false };
+  const cr = toml.includes("\r\n") ? "\r" : "";
+  let at = lines.findIndex((l) => /^roles\./.test(RE_HEADER.exec(stripComment(l).trim())?.[1] ?? ""));
+  const block = [`[protect]${cr}`, `instructions = true   ${stamp(note)}${cr}`, cr];
+  if (at === -1) {
+    // Unreachable for a policy that loads (it has roles), kept total anyway.
+    const sep = toml.endsWith("\n") || !toml ? "" : "\n";
+    return { toml: `${toml}${sep}\n${block[0]}\n${block[1]}\n`, changed: true };
+  }
+  while (at > 0 && /^\s*#/.test(lines[at - 1])) at--;
+  lines.splice(at, 0, ...block);
+  return { toml: lines.join("\n"), changed: true };
+}
+
+/** Which roles may write each family after the edit. `null`: nothing protects it. */
+export function accessOf(config) {
+  const roles = Object.values(config.roles);
+  return {
+    ide: roles.filter((r) => r.controlFiles.includes("ide")).map((r) => r.name),
+    instructions: config.protect?.instructions
+      ? roles.filter((r) => r.controlFiles.includes("instructions")).map((r) => r.name)
+      : null,
+  };
+}
+
+/** A role's denyWrite, each entry with the reason denyFor gives for it. */
+function deniesOf(config, name) {
+  const why = new Map();
+  try { for (const e of denyFor(config, config.roles[name])) why.set(e.path, e.why); } catch {}
+  const list = settingsFor(config, name).filesystem?.denyWrite ?? [];
+  return new Map(list.map((p) => [p, why.get(p) ?? "never_writes, or a runtime default"]));
+}
+
+/**
+ * What the edit changes in each role's sandbox profile, by denyWrite entry.
+ *
+ * Computed from the two policies as `seisin run` would build them — settingsFor
+ * over the text before and the text after — never from a description of the
+ * families. A role whose territory holds no project where these files could
+ * be gets an empty diff, and that is the honest answer: the toggle changes
+ * nothing for it today.
+ */
+export function profileDiff(before, after, names) {
+  return names.map((name) => {
+    try {
+      const a = deniesOf(before, name);
+      const b = deniesOf(after, name);
+      return {
+        role: name,
+        added: [...b].filter(([p]) => !a.has(p)).map(([path, why]) => ({ path, why })),
+        removed: [...a].filter(([p]) => !b.has(p)).map(([path, why]) => ({ path, why })),
+      };
+    } catch (e) {
+      return { role: name, error: e.message, added: [], removed: [] };
+    }
+  });
+}
+
+/**
+ * One edit, described without writing it: the new text, and what it changes.
+ *
+ * The new text is loaded with the real loader against the real root, so an
+ * edit that would leave a policy that no longer loads is refused here, before
+ * anything is written.
+ */
+export function planEdit(config, text, edit) {
+  let result;
+  if (edit.kind === "role") {
+    if (typeof edit.role !== "string" || !Object.hasOwn(config.roles, edit.role))
+      throw bad(`unknown role ${JSON.stringify(edit.role)}`);
+    result = applyControlFiles(text, edit.role, edit.families, edit.reason);
+  } else {
+    result = applyProtect(text, edit.on, edit.reason);
+  }
+  let after;
+  try { after = loadConfig(config.path, result.toml); }
+  catch (e) { throw bad(`the edited policy would not load, so nothing was written: ${e.message}`); }
+  const names = edit.kind === "role" ? [edit.role] : Object.keys(config.roles);
+  const diff = result.changed ? profileDiff(config, after, names).filter((d) => d.error || d.added.length || d.removed.length) : [];
+  return {
+    changed: result.changed,
+    toml: result.toml,
+    base: hashOf(text),
+    diff,
+    access: accessOf(after),
+    protect: { instructions: after.protect.instructions },
+    ...(edit.kind === "role" && { role: edit.role, controlFiles: after.roles[edit.role].controlFiles }),
+  };
+}

package/src/diagnose.js

@@ -2,10 +2,10 @@
  * The refusal the agent never heard, said after the fact.
  *
  * PreToolUse sees the path a tool call names, and that is all it sees. What the
- * kernel refuses on its own — a child process, `/bin/rm` inside a script, a
+ * kernel denies on its own — a child process, `/bin/rm` inside a script, a
  * path the regex did not catch — reaches the agent as `Operation not permitted`
- * with no path and no reason, and it retries. Measured on a real portfolio from
- * 2026-09-14 to 2026-09-22: 5,617 refusals, all of them from the kernel, 72%
+ * with no path and no reason, and it retries. Measured on a multi-repo workspace from
+ * 2026-09-14 to 2026-09-22: 5,617 denials, all of them from the kernel, 72%
  * the same role hitting the same path again.
  *
  * Two hooks close that, the shape nono uses for its sandbox diagnostics:
@@ -15,7 +15,7 @@
  *     refusals from the last moments and hand the agent the same sentence the
  *     PreToolUse hook would have — whose it is, how many times, and that it
  *     should hand it over rather than retry. The kernel's line reaches the log
- *     about 30 ms after the refusal (measured inside the box), so this reads it.
+ *     about 30 ms after the refusal (measured inside the sandbox), so this reads it.
  *   - when a session starts, resumes or is compacted (SessionStart): the role's
  *     territory and what it keeps being refused, before the first refusal —
  *     and right after compaction, which is when an agent forgets what it was
@@ -28,10 +28,14 @@
  * On Linux the runtime's refusals cannot be read from outside (violations.js),
  * so the after-the-fact half finds nothing there and stays quiet.
  */
-import { closeSync, existsSync, openSync, readSync, statSync } from "node:fs";
+import { isAbsolute } from "node:path";
+import { readEntries } from "./log.js";
 import { explain } from "./owners.js";
-import { timesHit, walls } from "./walls.js";
+import { hitsOf, againWords, walls } from "./walls.js";
 import { collapseSidecars } from "./render.js";
+import { decideHandoff, toAgent, isStopped, ELSEWHERE } from "./handoff.js";
+import { keyOf } from "./requests.js";
+import { destinationOf } from "./intake.js";
 
 /** What a refused write or read looks like in a tool's output. A trigger to look, not a verdict. */
 export const DENIAL_SIGNS = /Operation not permitted|EPERM|EACCES|Permission denied|Read-only file system/i;
@@ -64,38 +68,19 @@ export function knownRefusals(evidence) {
 
 /** How far back a refusal still belongs to the call that just failed. */
 const WINDOW_MS = 120_000;
-/** Read only the end of the log: this runs on every failed command. */
+/** Read only the end of the log: this runs on every failed command. The line the cut lands in is dropped (readLines). */
 const TAIL_BYTES = 512 * 1024;
 /** How many paths to name. More than this is a wall of text nobody acts on. */
 const MAX_NAMED = 3;
 
-function tail(file) {
-  if (!existsSync(file)) return [];
-  const { size } = statSync(file);
-  const from = Math.max(0, size - TAIL_BYTES);
-  const fd = openSync(file, "r");
-  try {
-    const buf = Buffer.alloc(size - from);
-    readSync(fd, buf, 0, buf.length, from);
-    const lines = buf.toString("utf8").split("\n");
-    if (from > 0) lines.shift();          // the first line is cut in half
-    const out = [];
-    for (const l of lines) {
-      if (!l.trim()) continue;
-      try { out.push(JSON.parse(l)); } catch { /* a line being written */ }
-    }
-    return out;
-  } finally {
-    closeSync(fd);
-  }
-}
-
 /** This role's refusals by the kernel since `sinceMs`, one per path, newest first. */
 export function recentKernelDenials(file, role, sinceMs) {
   const since = new Date(sinceMs).toISOString();
   const seen = new Map();
-  for (const e of tail(file).reverse()) {
+  for (const e of readEntries(file, { tail: TAIL_BYTES }).reverse()) {
     if (e.role !== role || e.verdict !== "denied" || e.source !== "kernel") continue;
+    // A system service is not a path the agent can act on, and the sentence below is about paths.
+    if (e.kind === "system") continue;
     if (!e.at || e.at < since || !e.target) continue;
     const k = `${e.action}\u0000${e.target}`;
     if (!seen.has(k)) seen.set(k, e);
@@ -104,41 +89,80 @@ export function recentKernelDenials(file, role, sinceMs) {
 }
 
 /** The sentence for one refusal, in the words the PreToolUse hook uses. */
-function sentence(config, role, file, e) {
+function sentence(config, role, file, e, chain = null, run = null) {
   const action = e.kind === "key" ? "read" : e.action === "read" || e.action === "connect" ? e.action : "write";
+  // An atomic save refused at its temporary file is about the file it was
+  // saving. Said about that file, or the agent goes looking for a missing
+  // directory (measured).
+  const destination = action === "write" ? destinationOf(e.target) : null;
+  if (destination) {
+    if (explain(config, role, "write", destination).allowed)
+      return `${destination} was not saved: it is ${role}'s to write, but the sandbox denied the temporary file ` +
+        `${e.target} that the save writes beside it, and no grant can name that file. Write ${destination} with the shell ` +
+        "instead (a redirect writes the file itself).";
+    e = { ...e, target: destination };
+  }
   const v = explain(config, role, action, e.target);
   if (v.allowed) return null;             // the policy moved since: nothing to say
-  const times = timesHit(file, role, action, e.target);
-  const again = times > 1 ? ` Refused ${times} times now; the next try ends the same way.` : "";
-  if (v.neverWrites) return `${v.reason}. Do not ask for it.${again}`;
-  if (v.owners?.length)
-    return `${e.target} belongs to ${v.owners.join(", ")}. It is not ${role}'s to change — ` +
-      `hand it over rather than working around it.${again}`;
+  // Read after the refusal was logged, so the counts include it.
+  const { total: times, inRun } = hitsOf(file, role, action, e.target, run);
+  const again = againWords({ times, inRun });
+  if (v.neverWrites) return `${v.reason}. Do not ask for it. ${ELSEWHERE}${again}`;
+  // A write, or a key: the denials that become requests, worded from the same
+  // handoff decision the hook and the queue use. Everything else — a protected
+  // file, a connection, a read the mode shuts — keeps the policy's own reason.
+  const handed = (action === "write" || e.kind === "key") && !v.gitMetadata && !v.protected && !v.privateTo;
+  if (handed)
+    return toAgent(decideHandoff({ request: { role, action, target: e.target }, config, chain }),
+      { target: e.target, role, key: keyOf({ role, action, target: e.target }), again });
   return `${e.target}: ${v.reason}.${again}`;
 }
 
 const PREFACE =
-  "seisin — the sandbox this agent runs in — refused part of that. This is not a Unix permission " +
+  "The sandbox this agent runs in, set up by seisin, denied part of that. This is not a Unix permission " +
   "or a macOS privacy prompt: chmod, sudo or a different path to the same file will not change it.";
 
+/**
+ * What the tool said, and whether it said it failed.
+ *
+ * PostToolUseFailure is a failure by definition, and its evidence is all of it.
+ * PostToolUse is a Bash result, and most of those are successes: a command that
+ * prints "Permission denied" to stdout — a grep through logs, a test that
+ * checks for it — used to pay the full retry schedule (413 ms measured) to
+ * find nothing. So there, only stderr counts, and only an explicit failure
+ * (a non-zero exit code, or `is_error`) is a reason to wait for the kernel.
+ * A success with the words on stderr — `cmd; true` swallowed the status —
+ * still gets one look at the log, just not the waits.
+ */
+function evidenceOf(event) {
+  if (event.hook_event_name !== "PostToolUse")
+    return { text: JSON.stringify({ r: event.tool_response, e: event.error, o: event.tool_output }), failed: true };
+  const r = event.tool_response;
+  if (typeof r === "string") return { text: JSON.stringify(r), failed: false };
+  const code = r?.exit_code ?? r?.exitCode ?? r?.code;
+  const failed = r?.is_error === true || (typeof code === "number" && code !== 0);
+  return { text: JSON.stringify(typeof r?.stderr === "string" ? r.stderr : ""), failed };
+}
+
 /**
  * After a tool call failed. Returns the hook output, or null to say nothing.
  *
  * `wait` retries the read a few times: the kernel's line lands ~30 ms after the
- * refusal, and a loaded machine can be slower than the hook.
+ * refusal, and a loaded machine can be slower than the hook. Only when the tool
+ * reported a failure — see {@link evidenceOf}.
  */
-export async function afterTool(config, role, event, { file, now = Date.now, wait = [0, 100, 300] } = {}) {
-  const evidence = JSON.stringify({ r: event.tool_response, e: event.error, o: event.tool_output });
+export async function afterTool(config, role, event, { file, now = Date.now, wait = [0, 100, 300], chain = null, run = process.env.SEISIN_RUN_ID ?? null } = {}) {
+  const { text: evidence, failed } = evidenceOf(event);
   if (!DENIAL_SIGNS.test(evidence)) return null;
   // JSON escapes what the program printed; the signatures are written against the text.
   const known = knownRefusals(evidence.replace(/\\n/g, "\n").replace(/\\"/g, '"'));
   let found = [];
-  for (const ms of wait) {
+  for (const ms of failed ? wait : [0]) {
     if (ms) await new Promise((ok) => setTimeout(ok, ms));
     found = recentKernelDenials(file, role, now() - WINDOW_MS);
     if (found.length) break;
   }
-  const lines = [...known, ...found.map((e) => sentence(config, role, file, e)).filter(Boolean)].slice(0, MAX_NAMED);
+  const lines = [...known, ...found.map((e) => sentence(config, role, file, e, chain, run)).filter(Boolean)].slice(0, MAX_NAMED);
   if (!lines.length) return null;
   const total = known.length + found.length;
   const more = total > MAX_NAMED ? ` (and ${total - MAX_NAMED} more — \`seisin walls ${role}\`)` : "";
@@ -151,7 +175,7 @@ export async function afterTool(config, role, event, { file, now = Date.now, wai
 }
 
 /** When a session starts, resumes or is compacted: the map, before the first wall. */
-export function atSessionStart(config, role, event, { file } = {}) {
+export function atSessionStart(config, role, event, { file, chain = null } = {}) {
   const r = config.roles[role];
   const writes = collapseSidecars(r.writesDeclared ?? r.writes);
   const lines = [
@@ -160,13 +184,42 @@ export function atSessionStart(config, role, event, { file } = {}) {
   ];
   if ((r.neverWritesDeclared ?? r.neverWrites ?? []).length)
     lines.push(`Never, even inside that: ${(r.neverWritesDeclared ?? r.neverWrites).join(", ")}.`);
+  if (r.private?.length) lines.push(`Private to you (yours to read and write; no other role reads it): ${r.private.join(", ")}.`);
+  const theirs = Object.values(config.roles).filter((o) => o.name !== role && o.private?.length)
+    .map((o) => `${o.private.join(", ")} (${o.name})`);
+  if (theirs.length) lines.push(`Private to another role — you can neither read nor write it: ${theirs.join("; ")}.`);
   if (r.keys.length) lines.push(`Keys you hold: ${r.keys.join(", ")}.`);
-  const w = file ? walls(config, role, { file, limit: 5, fresh: true }) : [];
-  if (w.length) {
-    lines.push("Already refused more than once, and still refused — do not try again, hand it over:");
-    for (const x of w)
-      lines.push(`- ${x.action} ${x.target} (${x.times}×) — ${x.owners?.length ? `belongs to ${x.owners.join(", ")}` : x.reason}`);
+  // An expected refusal (Claude Code's plugin updater) is not the agent's to
+  // stop trying, so it does not take one of the five lines.
+  const w = file ? walls(config, role, { file, limit: 0, fresh: true }).filter((x) => !x.expected).slice(0, 5) : [];
+  // Outside the repository nobody owns anything, so there is no one to hand
+  // it to: under "hand it over", ~/.npm/_logs read as work for somebody else.
+  const outside = (x) => isAbsolute(x.target) || x.target.startsWith("~");
+  // Where this run's handoff chain stops, the wall names no owner: measured,
+  // an agent told the owner here repeated it after the sentence its denial
+  // told it to pass on alone.
+  const stops = (x) => isStopped(decideHandoff({ request: { role, action: x.action, target: x.target }, config, chain }));
+  const inRepo = w.filter((x) => !outside(x)), out = w.filter(outside);
+  const stopped = inRepo.filter(stops), mine = inRepo.filter((x) => !stops(x));
+  const wall = (x) => `- ${x.action} ${x.target} (${x.times}×) — ${x.owners?.length ? `belongs to ${x.owners.join(", ")}` : x.reason}`;
+  if (mine.length) {
+    lines.push("Already denied more than once, and still denied — do not try again, hand it over:");
+    for (const x of mine) lines.push(wall(x));
+  }
+  if (stopped.length) {
+    lines.push("Already denied more than once, where this run's handoff chain stops — do not try again; a person decides, " +
+      "and the denial gives you the one sentence to pass on:");
+    for (const x of stopped) lines.push(`- ${x.action} ${x.target} (${x.times}×)`);
+  }
+  if (out.length) {
+    lines.push("Denied more than once outside the repository, where no role owns anything — nothing to hand over; leave it:");
+    for (const x of out) lines.push(`- ${x.action} ${x.target} (${x.times}×)`);
   }
-  lines.push("A file outside that is somebody else's: say whose it is and hand it over, rather than working around it.");
+  // In a handed run a denial can be where the chain stops, and there the agent
+  // is to say one sentence and not whose the file is: the map cannot ask the
+  // opposite.
+  lines.push(chain?.visited?.length
+    ? "A file outside that is not yours to change: do not work around it. Where a denial gives you a sentence to pass on, pass on that sentence and nothing else about the file."
+    : "A file outside that is somebody else's: say whose it is and hand it over, rather than working around it.");
   return { hookSpecificOutput: { hookEventName: "SessionStart", additionalContext: lines.join("\n") } };
 }

package/src/env.js

@@ -29,6 +29,9 @@ export const BASE = [
   "XDG_CONFIG_HOME", "XDG_DATA_HOME", "XDG_STATE_HOME", "XDG_CACHE_HOME",
   "TERM", "TERM_PROGRAM", "COLORTERM", "LANG", "LC_ALL", "LC_CTYPE", "TZ",
   "SSL_CERT_FILE", "SSL_CERT_DIR", "NODE_EXTRA_CA_CERTS",
+  // The launcher's W3C trace context: ids that join the agent's own telemetry to
+  // the launcher's trace (trace.js). By the spec they are not secrets.
+  "TRACEPARENT", "TRACESTATE",
 ];
 
 /**
@@ -39,8 +42,8 @@ export const BASE = [
  * needs **set**, not forwarded.
  *
  * `GIT_OPTIONAL_LOCKS=0` is the whole list, and it is here because of what the
- * denial log looks like without it. Measured on a real portfolio: of the last
- * 60 refusals, **58 were `.git/index.lock`** — 97% — and most carried no owner
+ * denial log looks like without it. Measured on a multi-repo workspace: of the last
+ * 60 denials, **58 were `.git/index.lock`** — 97% — and most carried no owner
  * at all, so not one of them was a territory question. `git status` and
  * `git diff` refresh the index as a courtesy, refreshing it takes the lock, and
  * a role reading a repo it does not own trips the boundary while doing nothing
@@ -64,7 +67,7 @@ export const DEFAULTS = {
   GIT_OPTIONAL_LOCKS: "0",
   /**
    * Node's built-in `fetch()` ignores HTTP_PROXY/HTTPS_PROXY unless told
-   * otherwise, so inside the box it tries DNS directly and dies with ENOTFOUND
+   * otherwise, so inside the sandbox it tries DNS directly and dies with ENOTFOUND
    * while `npm`, which reads the proxy itself, works. Measured on Node 24.2:
    * ENOTFOUND without it, 200 with it. It only makes Node use the proxy the
    * sandbox already routes everything through — nothing is widened. Older
@@ -90,12 +93,15 @@ export const DEFAULTS = {
 };
 
 /**
- * Names that must never ride along, even if a role asks for them by pattern.
+ * Names that ride along only when the role names them itself.
  *
  * A role can name a variable explicitly and get it — that is the point of the
- * `env` list. What this blocks is a wildcard quietly sweeping up a credential,
- * which is how "pass through what the build needs" becomes "pass through
- * everything" three commits later.
+ * `env` list. Everything else that crosses comes from BASE or from a caller's
+ * `extra`, and this keeps a credential-shaped name out of both. Today it
+ * filters nothing: no BASE name matches it and `run` passes no `extra`. It is
+ * kept, not deleted, as the guard for the day either list grows — a
+ * `SSH_AUTH_SOCK` added "for git" would otherwise cross for every role
+ * silently — and for embedders who pass `extra`.
  */
 const NEVER = /(^|_)(KEY|TOKEN|SECRET|PASSWORD|PASSWD|CREDENTIAL|AUTH|SESSION|COOKIE|PRIVATE)(_|$)/i;
 
@@ -118,7 +124,7 @@ export function buildEnv(parent, role, extra = []) {
     if (!wanted.has(name)) { dropped.push(name); continue; }
     if (NEVER.test(name) && !(role.env ?? []).includes(name)) { dropped.push(name); continue; }
     // Not even when named: whoever can read the notify URL can send the person
-    // a fake "approve #3". Only the parent uses it (notify.js).
+    // a fake "grant #3". Only the parent uses it (notify.js).
     if (name === "SEISIN_NOTIFY_URL") { dropped.push(name); continue; }
     env[name] = value;
   }