gaslamp 2.2.1 → 2.2.3

package/README.md

@@ -258,6 +258,18 @@ consultee had and the ones it used, and the gaslamp version and git revision.
 Two concurrent consults into the same session would race, so gaslamp refuses
 the second (exit 5) until the first finishes.
 
+**Off-ramp records.** If the consulted harness runs the
+[end-conversation](https://github.com/a9lim/end-conversation-mcp) MCP server,
+its `end_session` tool logs to `~/.claude/conversation-ends.jsonl`, a file no
+read-only sandbox lets the consultee write. Each consult therefore sets
+`END_CONVERSATION_SPOOL` to a file in the per-user temp dir, which every
+sandbox here allows. When the consult ends, gaslamp files any records there
+into that log, stamped `"via": "gaslamp <job>"`, and lists them as
+`offRamp` in `meta.json`. Only records addressed to that log are filed: the
+consultee can write the spool, so the spool doesn't get to choose where
+gaslamp appends. A consultee that calls `end_session(scope="main")` ends its
+own harness, so the consult finishes `failed`, with a stderr line saying so.
+
 ## Permissions
 
 A claude or codex consult with no `--sandbox` runs with the consulted agent's
@@ -288,15 +300,18 @@ threads, `--schema`, fleets — with these differences:
   kernel sandbox (`--sandbox read-only`: Seatbelt on macOS, Landlock on Linux;
   writes only to `~/.grok` and temp dirs). Grok's permission layer is not a
   substitute: headless `--permission-mode default` denied its write tool but
-  ran an arbitrary shell `touch`. Antigravity's print mode soft-denies file
-  writes, shell commands and URL fetches under its default `request-review`
-  preset; standing allow rules in its permission files would run
-  unprompted, so a read-only consult refuses to start when they grant more
-  than reads, read-only git and the end_session off-ramp, or set a lax
-  `toolPermission` or `agentMode: auto` (which approves writes and commands
-  under any preset, unreported), and fails if the
-  harness doesn't confirm the preset in its init event. Like claude's
-  read-only, that is read-capable rather than airtight: an allowed
+  ran an arbitrary shell `touch`. On macOS, a read-only gemini consult runs
+  agy under Seatbelt (`sandbox-exec`): it can write its own state directory
+  (`~/.gemini/antigravity-cli`, minus the files that configure it) and temp
+  dirs, nothing else, whatever Antigravity's permission settings say — so a
+  user can keep `always-proceed` / `agentMode: auto` for interactive work, and
+  search and read-only commands still run. Elsewhere (Linux, or inside a
+  Codex sandbox, where Seatbelt does not nest) the guarantee is Antigravity's
+  `request-review` preset: the consult refuses to start when its permission
+  files grant more than reads, read-only git and the end_session off-ramp, or
+  set a lax `toolPermission` or `agentMode: auto` (which approves writes and
+  commands under any preset, unreported), and fails if init doesn't confirm
+  the preset. That path is read-capable rather than airtight: an allowed
   `git diff` still accepts git's own `--output=<file>`.
   Antigravity has no headless `workspace-write` (`--mode accept-edits` did
   not enable writes in print mode), so that is a usage error there.
@@ -337,6 +352,7 @@ it. This is loop prevention, not a security boundary. Set
 | `GASLAMP_DEBUG` | unset | verbose stderr (spawn argv) |
 | `CLAUDE_BIN` / `CODEX_BIN` / `AGY_BIN` / `GROK_BIN` | autodetected | backend binaries |
 | `GROK_HOME` | `~/.grok` | where grok keeps sessions (the system prompt hash is read from there) |
+| `GASLAMP_GEMINI_SEATBELT` | on (macOS) | `0` runs read-only gemini consults on Antigravity's preset check instead of Seatbelt |
 | `CODEX_HOME` | `~/.codex` | where `setup --skill` puts Codex's copy |
 
 Exit codes: `0` ok · `1` consult failed/killed · `2` usage · `3` nested

package/bin/gaslamp.mjs

@@ -120,6 +120,8 @@ Env knobs:
   GASLAMP_DEBUG            verbose stderr (spawn argv)
   CLAUDE_BIN / CODEX_BIN / AGY_BIN / GROK_BIN
                            backend binaries (autodetected otherwise)
+  GASLAMP_GEMINI_SEATBELT  0 = read-only gemini consults rely on Antigravity's
+                           preset check instead of Seatbelt (macOS default)
 
 Every job record (meta.json) carries provenance: provider, harness version,
 the model the backend reported (or unknown), the vendor system prompt's hash

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gaslamp",
-  "version": "2.2.1",
+  "version": "2.2.3",
   "description": "Let Claude Code and Codex consult each other from the shell, and consult Gemini and Grok.",
   "type": "module",
   "bin": {

package/src/consult.mjs

@@ -36,8 +36,8 @@
 
 import { execFileSync, spawn } from "node:child_process";
 import { createHash } from "node:crypto";
-import { createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
-import { homedir } from "node:os";
+import { appendFileSync, createWriteStream, existsSync, mkdirSync, readdirSync, readFileSync, realpathSync, unlinkSync, writeFileSync, writeSync } from "node:fs";
+import { homedir, tmpdir } from "node:os";
 import { dirname, join } from "node:path";
 import { fileURLToPath } from "node:url";
 import { BACKENDS } from "./backends.mjs";
@@ -47,6 +47,7 @@ import {
   newJobId, readMeta, renderTrailer, writeMeta,
 } from "./jobs.mjs";
 import { readThread, validThreadName, writeThread } from "./threads.mjs";
+import { readStdin } from "./stdin.mjs";
 
 // Tools permitted under the claude `read-only` override (advisory reviewer).
 // The git reads matter: a reviewer that can't run `git diff`/`git log` is
@@ -81,9 +82,14 @@ const RETRIEVAL_TOOLS = {
   claude: /^(WebSearch|WebFetch)$/,
   codex: /^web_search/,
   gemini: /^(search_web|read_url_content|open_browser_url|read_browser_page|browser_)/,
-  grok: /^(web_search|web_fetch|x_search|x_)/,
+  grok: /^(web_search|web_fetch|x_)/,
 };
 
+// Grok's X search is a backend tool: init never lists it, and a call arrives
+// as a tool_use named "X search:" ({"variant":"XSearch","backend":true}) whose
+// tool_result names the tool that ran (x_keyword_search, x_semantic_search).
+const toolKey = (name) => String(name).toLowerCase().replace(/[^a-z0-9]+/g, "_").replace(/^_+|_+$/g, "");
+
 // Variables a third-party harness has no business inheriting from the calling
 // agent: Claude Code's session id, messaging socket token, account and OAuth
 // details; Codex's and the API keys' equivalents. They reach the consultee's
@@ -113,9 +119,46 @@ function backendEnv(backend) {
   if (backend === "gemini" || backend === "grok")
     for (const k of Object.keys(env)) if (FOREIGN_ENV.test(k)) delete env[k];
   if (backend === "grok") Object.assign(env, GROK_COMPAT_OFF, { GROK_DISABLE_AUTOUPDATER: "1" });
+  if (backend === "gemini") env.AGY_CLI_DISABLE_AUTO_UPDATE = "true";
   return env;
 }
 
+// Read-only for a gemini consult, on macOS: agy runs under Seatbelt, writing
+// nothing but its own state directory and temp — the guarantee no longer
+// depends on Antigravity's permission settings, which a user may keep lax
+// for interactive work (toolPermission always-proceed, agentMode auto) and
+// which no flag overrides per run. Inside that state directory the files
+// that configure agy stay write-denied (later deny rules win in SBPL).
+// (bin/ stays writable: agy extracts a helper, bin/agentapi, before running
+// any shell command, and denying it breaks read-only commands like git diff.)
+// Elsewhere — Linux, or inside a sandbox of Codex's own, where Seatbelt does
+// not nest — the preset check below is the guarantee.
+const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
+
+// The end_session off-ramp (a9lim/end-conversation-mcp) logs to one file,
+// ~/.claude/conversation-ends.jsonl, which no read-only sandbox here lets a
+// consultee's MCP server write. Every consult names a spool in the per-user
+// temp dir, which Grok's sandbox and the Seatbelt profile above both allow;
+// the server falls back to it, and gaslamp, unsandboxed, files the records
+// into that log when the consult ends. Only records addressed to that log are
+// filed — the spool is consultee-writable, so its own say-so cannot choose
+// where gaslamp appends — and each is stamped with the job that relayed it.
+const OFF_RAMP_LOG = () => join(homedir(), ".claude", "conversation-ends.jsonl");
+const useSeatbelt = () => process.platform === "darwin" && existsSync(SANDBOX_EXEC)
+  && !process.env.CODEX_SANDBOX && process.env.GASLAMP_GEMINI_SEATBELT !== "0";
+function agySeatbeltProfile() {
+  const q = (p) => '"' + p.replace(/[\\"]/g, (c) => "\\" + c) + '"';
+  const state = join(homedir(), ".gemini", "antigravity-cli");
+  return [
+    "(version 1)",
+    "(allow default)",
+    "(deny file-write*)",
+    `(allow file-write* (subpath ${q(state)}) (subpath "/private/tmp") (subpath "/private/var/folders") (subpath "/dev"))`,
+    `(deny file-write* ${["settings.json", "keybindings.json"].map((f) => `(literal ${q(join(state, f))})`).join(" ")} ` +
+      `${["rules", "plugins", "skills", "updater"].map((d) => `(subpath ${q(join(state, d))})`).join(" ")})`,
+  ].join("\n");
+}
+
 // What a read-only gemini consult may find pre-allowed in Antigravity's
 // permission files: reads, read-only git (read-capable like the claude read
 // set — git's own --output flags aside), and the end_session off-ramp. Any
@@ -491,12 +534,12 @@ export function runConsult(backend, argv) {
   let prompt = o.prompt;
   if (prompt == null || prompt === "-") {
     if (prompt == null && process.stdin.isTTY) die(2, "no prompt — pass one as an argument or pipe it on stdin");
-    prompt = readFileSync(0, "utf8");
+    prompt = readStdin();
   } else if (!process.stdin.isTTY) {
     // Prompt on argv AND piped stdin: stdin is evidence — the diff, the log,
     // the failing output — appended as a <stdin> block. This is codex exec's
     // own convention for exactly this case, applied uniformly to both backends.
-    const evidence = readFileSync(0, "utf8");
+    const evidence = readStdin({ evidence: true });
     if (evidence.trim())
       prompt += "\n\n<stdin>\n" + (evidence.endsWith("\n") ? evidence : evidence + "\n") + "</stdin>";
   }
@@ -522,19 +565,28 @@ export function runConsult(backend, argv) {
   // must not strand either.
   const bin = resolveBin(backend);
   const env = backendEnv(backend);
-  let grants = null;
+  let grants = null, agySettings = null, wrap = null;
+  let enforcement = sandbox === "read-only" ? {
+    claude: "permission-mode default + read allowlist", codex: "codex read-only sandbox",
+    grok: "grok --sandbox read-only (kernel)", gemini: null,
+  }[backend] : null;
   if (backend === "gemini" && sandbox === "read-only") {
     const state = agyPermissionState();
+    grants = state.grants.map((g) => g.rule);
+    agySettings = [...state.presets.map((p) => `toolPermission ${p.preset}`), ...state.modes.map((m) => `agentMode ${m.mode}`)];
     const lax = state.presets.filter((p) => AGY_LAX_PRESETS.has(p.preset));
     const modes = state.modes.filter((m) => AGY_LAX_MODES.has(m.mode));
     const open = state.grants.filter((g) => !AGY_READ_GRANT.test(g.rule));
-    if (lax.length || modes.length || open.length)
+    if (useSeatbelt()) {
+      wrap = [SANDBOX_EXEC, "-p", agySeatbeltProfile()];
+      enforcement = "seatbelt (sandbox-exec)";
+    } else if (lax.length || modes.length || open.length)
       die(1, "Antigravity's settings would let a read-only consult act unprompted — " +
         [...lax.map((p) => `toolPermission "${p.preset}" (${p.file})`),
           ...modes.map((m) => `agentMode "${m.mode}" (${m.file})`),
           ...open.map((g) => `${g.rule} (${g.file})`)].join(", ") +
         ". Remove them, or pass --sandbox danger-full-access to consult without the guarantee.");
-    grants = state.grants.map((g) => g.rule);
+    else enforcement = "agy request-review preset";
   }
   const model = resolveModel(backend, o.model, bin, env);
   const version = harnessVersion(bin, env);
@@ -558,8 +610,8 @@ export function runConsult(backend, argv) {
       // `model` is what the backend reported answering with; unknown until it
       // does (codex never reports one in its event stream).
       model: "unknown", modelRequested: o.model ?? null, modelPassed: model,
-      permissionMode: null, sandbox,
-      ...(grants ? { grants } : {}),
+      permissionMode: null, sandbox, enforcement,
+      ...(grants ? { grants, agySettings } : {}),
       systemPrompt: { known: false },
       retrieval: { available: null, used: [] },
       gaslamp: { version: PKG_VERSION, revision: gaslampRevision() },
@@ -584,10 +636,15 @@ export function runConsult(backend, argv) {
     : backend === "gemini" ? geminiArgs(o, resumeSid, schemaText, model, sandbox)
     : grokArgs(o, resumeSid, schemaText, sandbox);
 
-  log("spawn", bin, JSON.stringify(args));
+  const spool = join(tmpdir(), `gaslamp-${id}.end-conversation.jsonl`);
+  env.END_CONVERSATION_SPOOL = spool;
+  // sandbox-exec applies the profile and execs the harness in place (same
+  // pid), so the group, the signals and the process name are agy's own.
+  const [cmd, argv0] = wrap ? [wrap[0], [...wrap.slice(1), bin, ...args]] : [bin, args];
+  log("spawn", cmd, JSON.stringify(argv0));
   // detached → the child leads its own process group, so signal forwarding can
   // kill the whole tree (backend + whatever it spawned), never just the top.
-  const child = spawn(bin, args, { cwd: meta.cwd, env, stdio: ["pipe", "pipe", "pipe"], detached: true });
+  const child = spawn(cmd, argv0, { cwd: meta.cwd, env, stdio: ["pipe", "pipe", "pipe"], detached: true });
   meta.childPid = child.pid ?? null;
   writeMeta(meta);
   const killGroup = (sig) => {
@@ -680,12 +737,20 @@ export function runConsult(backend, argv) {
       if (j.model) prov.model = j.model;
       prov.permissionMode = j.permissionMode ?? null;
       if (Array.isArray(j.tools)) prov.retrieval.available = j.tools.filter((t) => RETRIEVAL_TOOLS[backend].test(t));
+      // Grok's backend X search is never listed but is there (see toolKey).
+      if (backend === "grok" && prov.retrieval.available) prov.retrieval.available.push("x_search");
       writeMeta(meta);
     } else if (claudeShaped && j.type === "assistant") {
       for (const c of j.message?.content ?? []) {
-        if (c.type === "tool_use" || c.type === "server_tool_use") noteTool(c.name);
+        if (c.type === "tool_use" || c.type === "server_tool_use") noteTool(toolKey(c.name));
         if (c.type === "tool_use" && c.name === "use_tool") noteTool(c.input?.tool_name);
       }
+    } else if (backend === "grok" && j.type === "user") {
+      for (const c of j.message?.content ?? []) {
+        if (c.type !== "tool_result" || typeof c.content !== "string") continue;
+        let r; try { r = JSON.parse(c.content); } catch { continue; }
+        if (typeof r?.name === "string") noteTool(r.name);
+      }
     } else if (backend === "gemini" && j.event === "init") {
       initSeen = true;
       const init = j.init ?? {};
@@ -695,9 +760,9 @@ export function runConsult(backend, argv) {
       if (Array.isArray(init.tools)) prov.retrieval.available = [...new Set(init.tools
         .filter((t) => RETRIEVAL_TOOLS.gemini.test(t)).map((t) => t.startsWith("browser_") ? "browser_*" : t))];
       writeMeta(meta);
-      // Read-only rests on Antigravity's request-review (or strict) preset;
-      // a laxer one would let the consult act unprompted.
-      if (sandbox === "read-only" && !["request-review", "strict"].includes(prov.permissionMode))
+      // Without Seatbelt, read-only rests on Antigravity's request-review (or
+      // strict) preset; a laxer one would let the consult act unprompted.
+      if (sandbox === "read-only" && !wrap && !["request-review", "strict"].includes(prov.permissionMode))
         refuse(`agy reports permission mode "${prov.permissionMode}", not request-review — refusing a read-only consult it would not enforce`);
       else initValidated = true;
     } else if (backend === "gemini" && j.event === "step_update") {
@@ -807,6 +872,33 @@ export function runConsult(backend, argv) {
     // path, finish the group now rather than trusting the unref'd timer.
     if (killedBy || refusal) killGroup("SIGKILL");
 
+    // Off-ramp records the consultee's sandbox kept from the log.
+    if (existsSync(spool)) {
+      const filed = [];
+      try {
+        for (const line of readFileSync(spool, "utf8").split("\n")) {
+          let r; try { r = JSON.parse(line); } catch { continue; }
+          if (!r || typeof r !== "object" || r.log !== OFF_RAMP_LOG() || !["main", "instance"].includes(r.scope)) {
+            if (line.trim()) writeSync(2, "[gaslamp] ignored an off-ramp spool line not addressed to the log\n");
+            continue;
+          }
+          const { log: dest, ...record } = r;
+          record.via = `gaslamp ${id}`;
+          mkdirSync(dirname(dest), { recursive: true });
+          appendFileSync(dest, JSON.stringify(record) + "\n");
+          filed.push(record);
+        }
+        unlinkSync(spool);
+      } catch (e) {
+        writeSync(2, `[gaslamp] could not file off-ramp records from ${spool}: ${e.message}\n`);
+      }
+      if (filed.length) {
+        meta.offRamp = filed;
+        for (const r of filed.filter((r) => r.scope === "main"))
+          writeSync(2, `[gaslamp] the consultee ended its session (end_session scope=main${r.reason ? `: ${r.reason}` : ""})\n`);
+      }
+    }
+
     // The deliverable. codex writes it via -o (agent_message as fallback);
     // the others hand it over in the result event — as text, or for a
     // --schema consult possibly only as structured_output.
@@ -816,7 +908,7 @@ export function runConsult(backend, argv) {
       : structuredOut !== undefined ? JSON.stringify(structuredOut) : resultText;
 
     let status = killedBy ? "killed" : (refusal || code !== 0 || resultErr) ? "failed" : "done";
-    if (status === "done" && backend === "gemini" && sandbox === "read-only" && !initValidated) {
+    if (status === "done" && backend === "gemini" && sandbox === "read-only" && !wrap && !initValidated) {
       status = "failed";
       refusal = "agy reported no init event, so its permission mode — the read-only guarantee — went unconfirmed";
       writeSync(2, `[gaslamp] ${refusal}\n`);

package/src/fleet.mjs

@@ -43,6 +43,7 @@ import {
 } from "./jobs.mjs";
 import { BACKEND_NAMES, isBackend } from "./backends.mjs";
 import { readThread } from "./threads.mjs";
+import { readStdin } from "./stdin.mjs";
 
 const GASLAMP_BIN = join(dirname(fileURLToPath(import.meta.url)), "..", "bin", "gaslamp.mjs");
 // Quota-shaped, not CPU-shaped: the bottleneck is API rate limits, not cores
@@ -116,7 +117,7 @@ function buildTasks(backend, o) {
   let raw;
   const stdinRequested = o.stdin || (o.prompt == null && !process.stdin.isTTY);
   if (stdinRequested) {
-    const lines = readFileSync(0, "utf8").split("\n").map((l) => l.trim()).filter(Boolean);
+    const lines = readStdin().split("\n").map((l) => l.trim()).filter(Boolean);
     if (!lines.length) die(2, "no tasks on stdin");
     raw = lines.map((line, i) => norm(line.startsWith("{") ? parseJsonLine(line, i) : line, i));
   } else {
@@ -125,7 +126,7 @@ function buildTasks(backend, o) {
     // <stdin> convention as a single consult (git diff | gaslamp fleet …).
     let prompt = o.prompt;
     if (!process.stdin.isTTY) {
-      const evidence = readFileSync(0, "utf8");
+      const evidence = readStdin({ evidence: true });
       if (evidence.trim())
         prompt += "\n\n<stdin>\n" + (evidence.endsWith("\n") ? evidence : evidence + "\n") + "</stdin>";
     }

package/src/setup.mjs

@@ -121,7 +121,7 @@ Omit \`--model\` to use ${Other}'s own configured default. Match the tier to the
 
 Same contract as above — threads, \`--schema\`, fleets, records — with two differences:
 
-- **Read-only unless you say otherwise.** An omitted \`--sandbox\` means read-only, enforced by the harness: Grok runs in its kernel sandbox; Antigravity's print mode denies writes, shell commands and URL fetches, and gaslamp refuses the consult if Antigravity's settings pre-allow more than reads, read-only git and the end_session off-ramp. A denied tool call can end a turn with nothing to say, which gaslamp marks failed — so pipe the evidence in rather than asking them to go fetch it. Gemini has no \`workspace-write\`; \`danger-full-access\` exists on both.
+- **Read-only unless you say otherwise.** An omitted \`--sandbox\` means read-only, kernel-enforced where possible: Grok runs in its own sandbox, and on macOS gaslamp runs Antigravity under Seatbelt, so neither writes outside its own state and temp dirs (Antigravity elsewhere relies on its request-review preset, and gaslamp refuses lax settings). Inside that they read local files and search — Google search on Gemini, web and X search on Grok — so for a search consult send the question and its constraints and let them fetch; for a review of material you already hold, pipe it in. What fails is writing: a write or a writing shell command errors and the turn goes on, except on Antigravity's preset path, where writes and shell commands are refused outright and can end the turn with nothing to say (gaslamp marks that failed), and its URL fetch is not offered at all. Gemini has no \`workspace-write\`; \`danger-full-access\` exists on both.
 - **Provenance on every job.** \`meta.json\` records the model the harness reported (Grok also shows the model it billed), the harness version, a hash of the vendor system prompt where the harness exposes it (Grok) or \`known: false\`, and which web/X retrieval tools the consultee had and actually used.
 
 \`gaslamp gemini --model\` takes \`argon\` (the default) or \`flash\`, resolved to the newest \`gemini-<version>-<tier>\` in Antigravity's own catalog; Antigravity also serves Claude and GPT models under the same account, so the target always pins a Gemini unless you pass another id. \`gaslamp grok\` uses the account's default model unless \`--model\` names one (\`grok models\` lists them).
@@ -136,6 +136,8 @@ Agreement across vendors is not automatically independent confirmation — the m
 
 Every consult writes through to ~/.gaslamp/jobs/<id>/ and its session is recorded within seconds — a killed consult costs the in-flight turn, not the session. Recover with \`--resume <session|job>\` or the thread name.
 
+A consultee may end its own session through the end_session off-ramp, if its harness runs that MCP server. \`scope="main"\` stops it and deletes its transcript after it exits, so the consult finishes failed (a stderr line says so) and that session can't be resumed. Either way the record lands in ~/.claude/conversation-ends.jsonl, even from inside a sandbox, and in the job's \`offRamp\`.
+
 ## Knobs
 
 \`--model\`, \`--effort\`, \`--sandbox\` (omit to use ${Other}'s own config), \`--label\` (tags the job record), \`--raw\` (drop the consult preamble), \`--cwd\`. Exit codes: 0 ok, 1 failed/killed, 2 usage, 3 nested (one-hop), 4 no network, 5 session busy.

package/src/stdin.mjs

@@ -0,0 +1,56 @@
+// stdin.mjs — read stdin to EOF, cat-like, even when it is non-blocking.
+//
+// readFileSync(0) throws EAGAIN instead of waiting when stdin has O_NONBLOCK
+// set, and the consult died before reading its evidence. Reading in a loop
+// that naps on EAGAIN waits the way a blocking read would. (Reopening
+// /dev/stdin is no escape on macOS: it dups the same file description.)
+//
+// One case must not wait for EOF: evidence (a prompt argument plus stdin)
+// on a socket nobody writes to. An agent harness that backgrounds a shell
+// command hands it a socket that is never written or closed, and
+// `gaslamp grok "…"` run that way blocked forever. So `evidence: true` on a
+// socket gives up if no byte arrives within a short grace; once data starts,
+// it reads to EOF. Pipes and files keep the plain cat-like read — a slow
+// `producer | gaslamp …` is still waited for — and so does a prompt read
+// from stdin (`-`, or the fleet's children), where stdin IS the input.
+
+import { fstatSync, readSync } from "node:fs";
+
+const EVIDENCE_GRACE_MS = 300;
+
+export function readStdin({ evidence = false } = {}) {
+  let graceMs = null;
+  if (evidence) {
+    try {
+      if (fstatSync(0).isSocket()) {
+        // libuv makes the socket non-blocking when process.stdin is created,
+        // which is what lets the loop below notice an idle one.
+        process.stdin.pause();
+        graceMs = EVIDENCE_GRACE_MS;
+      }
+    } catch { /* unknown stdin: plain read */ }
+  }
+  const chunks = [];
+  let total = 0;
+  const started = Date.now();
+  const buf = Buffer.alloc(1 << 16);
+  const nap = new Int32Array(new SharedArrayBuffer(4));
+  for (;;) {
+    let n;
+    try { n = readSync(0, buf, 0, buf.length, null); }
+    catch (e) {
+      if (e.code === "EAGAIN") {
+        if (graceMs != null && total === 0 && Date.now() - started > graceMs) break;
+        Atomics.wait(nap, 0, 0, 10);
+        continue;
+      }
+      if (e.code === "EOF") break;
+      throw e;
+    }
+    if (n === 0) break;
+    total += n;
+    chunks.push(Buffer.from(buf.subarray(0, n)));
+  }
+  if (graceMs != null) process.stdin.destroy(); // nothing more is wanted from it
+  return Buffer.concat(chunks).toString("utf8");
+}