toolroll 0.5.0

package/dist/supervisor.mjs

@@ -0,0 +1,297 @@
+#!/usr/bin/env node
+/**
+ * The held-session supervisor (Parity II Phase 2, spec v5 P4 / v6 W7+W9).
+ *
+ * A minimal, zero-dependency parent for one held agent process. Its whole
+ * value is PARENTHOOD: while this process lives and has not reaped its
+ * child, POSIX guarantees the child's PID cannot be reused — so a kill
+ * ordered through this process can never hit an innocent stranger, which
+ * no PID-plus-timestamp guess can promise. Everything else here is a dumb
+ * byte pump.
+ *
+ * Invocation (by exec.ts only):
+ *   node supervisor.mjs <agent-binary> <agent-args...>
+ *   env: SO_HELD_SOCKET  — unix socket path for the control channel
+ *        SO_HELD_COOKIE  — 128-bit hex cookie; every socket verb must carry it
+ *        SO_HELD_GRACE_MS — EOF→SIGKILL grace (default 10s)
+ *        SO_HELD_DIAGNOSTIC_FD — private observer diagnostic pipe (optional)
+ *
+ * Protocol, in order:
+ *   1. The control socket is created FIRST (mode 0600), so a fencer can
+ *      always reach a supervisor that got as far as spawning.
+ *   2. The agent spawns DETACHED into its own fresh process group.
+ *   3. stdout emits exactly ONE control frame before any relayed agent
+ *      byte: {"so_supervisor":"ready","agentPgid":N,"supervisorPid":N}
+ *      or {"so_supervisor":"spawn-failed","message":...}. Everything after
+ *      the ready frame is the agent's stream, byte for byte.
+ *   4. stdin bytes relay to the agent verbatim. stdin EOF (the owner ended
+ *      the hold, or died — the pipe broke) starts the AUTONOMOUS FENCE:
+ *      EOF to the agent, grace, then SIGKILL of its whole group. SIGTERM
+ *      and SIGHUP take the same road (the hard-stop sweep's contract).
+ *   5. Socket verbs, one JSON line per connection, cookie-checked:
+ *      {"cookie":..,"verb":"status"} → {"ok":true,"alive":bool,...}
+ *      {"cookie":..,"verb":"kill"}   → group SIGKILL via the held handle,
+ *      answered only after the group is PROVEN gone (ESRCH poll, 5s bound).
+ *   6. The supervisor exits when the agent has exited and the relay has
+ *      flushed; the socket file is unlinked on the way out.
+ */
+
+// The source supervisor is also exercised directly by the TypeScript test
+// runner; its shared helper comes from the normal production build there.
+const { stopProcessTree, observeProcessTree, sampleProcessTree } = await import(new URL("./process-tree.js", import.meta.url).href).catch(error => {
+  if (error.code !== "ERR_MODULE_NOT_FOUND") throw error;
+  return import(new URL("../dist/process-tree.js", import.meta.url).href);
+});
+import { spawn } from "node:child_process";
+import { createServer } from "node:net";
+import { chmodSync, unlinkSync, writeSync } from "node:fs";
+
+const socketPath = process.env["SO_HELD_SOCKET"] ?? "";
+const cookie = process.env["SO_HELD_COOKIE"] ?? "";
+const graceMs = Math.max(1000, Number(process.env["SO_HELD_GRACE_MS"] ?? 10_000) || 10_000);
+const [agentFile, ...agentArgs] = process.argv.slice(2);
+
+const frame = payload => {
+  process.stdout.write(`${JSON.stringify(payload)}\n`);
+};
+
+if (socketPath === "" || cookie === "" || agentFile === undefined) {
+  frame({ so_supervisor: "spawn-failed", message: "missing SO_HELD_SOCKET, SO_HELD_COOKIE, or agent argv" });
+  process.exit(2);
+}
+
+let exited = false;
+let exitCode = null;
+let fencing = false;
+let server = null;
+let killsInFlight = 0;
+const descendantPids = new Set();
+let treeUnknown = false;
+let exitWanted = false;
+let drain = null;
+let relayClosed = false;
+let relayDeadline = null;
+
+/** The exit road, deferred while a kill verb's reply is still owed: the
+ * fencer must HEAR that the group is proven gone before the process that
+ * proved it disappears. */
+const maybeExit = () => {
+  if (!exitWanted || killsInFlight > 0) return;
+  cleanup();
+  for (const connection of pending) connection.destroy();
+  process.exit(exitCode ?? 1);
+};
+
+const cleanup = () => {
+  try {
+    server?.close();
+  } catch {
+    // Already closed.
+  }
+  try {
+    unlinkSync(socketPath);
+  } catch {
+    // Never existed, or already gone.
+  }
+};
+
+/** True while ANY member of the agent's group survives. */
+const groupAlive = pgid => {
+  try {
+    process.kill(-pgid, 0);
+    return true;
+  } catch (error) {
+    return error.code !== "ESRCH";
+  }
+};
+const descendantsAlive = () => treeUnknown || [...descendantPids].some(pid => {
+  try { process.kill(pid, 0); return true; } catch (error) { return error.code !== "ESRCH"; }
+});
+const holdGone = pgid => relayClosed && !groupAlive(pgid) && !descendantsAlive();
+
+/** All exit roads share one drain. In particular, child.close must not
+ * outrun an EOF fence that is still waiting for a detached tool to die. */
+const killGroupSettled = pgid => drain ??= Promise.resolve().then(async () => {
+  if (child !== undefined && !exited) stopProcessTree(child);
+  try {
+    process.kill(-pgid, "SIGKILL");
+  } catch {
+    // Group already gone — proving below still runs.
+  }
+  const deadline = Date.now() + 5_000;
+  while (Date.now() < deadline) {
+    if (holdGone(pgid)) return true;
+    await new Promise(pass => setTimeout(pass, 50));
+  }
+  return holdGone(pgid);
+});
+
+// The control socket comes up BEFORE the agent spawns.
+const pending = new Set();
+server = createServer(connection => {
+  pending.add(connection);
+  connection.on("close", () => pending.delete(connection));
+  let buffered = "";
+  connection.on("data", chunk => {
+    buffered += String(chunk);
+    const cut = buffered.indexOf("\n");
+    if (cut === -1) {
+      if (buffered.length > 4096) connection.destroy();
+      return;
+    }
+    const line = buffered.slice(0, cut);
+    buffered = "";
+    let order = null;
+    try {
+      order = JSON.parse(line);
+    } catch {
+      connection.destroy();
+      return;
+    }
+    if (order === null || typeof order !== "object" || order.cookie !== cookie) {
+      // Wrong cookie: one refusal, no detail, connection over.
+      connection.end(`${JSON.stringify({ ok: false })}\n`);
+      return;
+    }
+    if (order.verb === "status") {
+      const pgid = child?.pid;
+      const group = pgid !== undefined && groupAlive(pgid);
+      connection.end(
+        `${JSON.stringify({ ok: true, alive: !exited || !relayClosed || group || descendantsAlive(), groupAlive: group, agentPgid: pgid ?? null, exitCode })}\n`,
+      );
+      return;
+    }
+    if (order.verb === "kill") {
+      const pgid = child?.pid;
+      if (pgid === undefined) {
+        connection.end(`${JSON.stringify({ ok: true, killed: false, settled: false, exitCode })}\n`);
+        return;
+      }
+      const killed = !exited;
+      killsInFlight += 1;
+      killGroupSettled(pgid).then(settled => {
+        // The reply counts as owed until the write side has FLUSHED —
+        // exiting on the mere call would let process death eat the FIN.
+        let settledReply = false;
+        const done = () => {
+          if (settledReply) return;
+          settledReply = true;
+          killsInFlight -= 1;
+          maybeExit();
+        };
+        try {
+          connection.on("finish", done);
+          connection.on("close", done);
+          connection.end(`${JSON.stringify({ ok: true, killed, settled, exitCode })}\n`);
+          setTimeout(done, 2_000).unref();
+        } catch {
+          done();
+        }
+      });
+      return;
+    }
+    connection.end(`${JSON.stringify({ ok: false })}\n`);
+  });
+});
+
+let child;
+server.on("error", error => {
+  frame({ so_supervisor: "spawn-failed", message: `control socket: ${String(error)}` });
+  process.exit(1);
+});
+server.listen(socketPath, () => {
+  try {
+    chmodSync(socketPath, 0o600);
+  } catch {
+    // Best effort; the parent directory is already private.
+  }
+
+  child = spawn(agentFile, agentArgs, {
+    detached: true,
+    stdio: ["pipe", "pipe", "pipe"],
+  });
+
+  child.on("error", error => {
+    frame({ so_supervisor: "spawn-failed", message: String(error) });
+    cleanup();
+    process.exit(1);
+  });
+
+  observeProcessTree(child, {
+    onDescendant: pid => descendantPids.add(pid),
+    onObservationFailure: failure => {
+      // A dedicated pipe, never the untrusted agent's stdout/stderr. The
+      // agent gets exactly three stdio descriptors and cannot inherit it.
+      if (process.env["SO_HELD_DIAGNOSTIC_FD"] === "3") writeSync(3, `${JSON.stringify(failure)}\n`);
+    },
+    onUnknown: () => { treeUnknown = true; },
+  });
+  child.on("spawn", () => {
+    frame({ so_supervisor: "ready", agentPgid: child.pid, supervisorPid: process.pid });
+    // Relay AFTER the frame: agent bytes buffered meanwhile flow next.
+    child.stdout.pipe(process.stdout, { end: false });
+    child.stderr.pipe(process.stderr, { end: false });
+    process.stdin.pipe(child.stdin, { end: false });
+    process.stdin.on("end", () => fence());
+    process.stdin.on("error", () => fence());
+  });
+
+  child.on("exit", (code, signal) => {
+    exited = true;
+    exitCode = code ?? (signal === null ? 1 : 143);
+    // A tool may inherit stdout/stderr and keep `close` from ever firing.
+    // Start cleanup at root exit, while retaining the relay until flushed.
+    if (child.pid !== undefined) void killGroupSettled(child.pid);
+    relayDeadline = setTimeout(() => {
+      if (relayClosed) return;
+      // Open pipes after the drain bound may belong to an unobserved,
+      // detached writer. Do not call the hold successfully completed.
+      treeUnknown = true;
+      exitCode = 126;
+      child.stdout.destroy();
+      child.stderr.destroy();
+    }, 5_000);
+  });
+
+  child.on("close", code => {
+    relayClosed = true;
+    clearTimeout(relayDeadline);
+    // stdio flushed and the process reaped. The GROUP may still have
+    // members — a tool the agent launched can outlive its leader (round-6
+    // finding 4) — so the whole group is drained and PROVEN gone before
+    // custody releases; the whole-tree invariant is the group, never the
+    // one pid.
+    exitCode = exitCode ?? code ?? 1;
+    const pgid = child.pid;
+    const drained = pgid !== undefined ? killGroupSettled(pgid) : Promise.resolve(false);
+    drained.then(settled => {
+      // Match exec.ts's containment refusal. A clean root exit is not a
+      // clean hold when descendants remain or observation failed.
+      if (!settled || treeUnknown) exitCode = 126;
+      exitWanted = true;
+      maybeExit();
+    });
+  });
+});
+
+/** EOF → grace → group SIGKILL. Idempotent; every exit road converges here. */
+const fence = () => {
+  if (fencing || exited || child === undefined) return;
+  fencing = true;
+  // Preserve witnesses before a cooperative root can exit and orphan its
+  // tools between the observer's periodic snapshots.
+  sampleProcessTree(child);
+  try {
+    child.stdin.end();
+  } catch {
+    // Already closed.
+  }
+  const timer = setTimeout(() => {
+    if (!exited && child.pid !== undefined) void killGroupSettled(child.pid);
+  }, graceMs);
+  timer.unref();
+};
+
+process.on("SIGTERM", () => fence());
+process.on("SIGHUP", () => fence());
+process.on("SIGINT", () => fence());

package/dist/surface.d.ts

@@ -0,0 +1,63 @@
+/**
+ * The declared command guide (arc 5): the agent-facing surface as data,
+ * dumped by `contract --commands`. This is DOCUMENTATION with a stable
+ * shape, not authority — legacy verbs do not execute from it,
+ * and the runtime envelope remains the truth. Its honest limits ride the
+ * envelope itself as SURFACE_NOTES, because a source comment is invisible
+ * to consumers (arc-5 review, finding 1).
+ *
+ * What the tests DO hold to the code: every root here is a routed verb
+ * and every routed verb appears here; every declared flag lives in the
+ * parser's global vocabulary with the declared arity; the subcommand
+ * inventories for task/publish/config/approver/routine/contest match the
+ * exported action lists their dispatchers consult; keyed mutations
+ * declare --key; notableReasons come from DOCUMENTED_REASONS. What they
+ * CANNOT prove — that a given flag is read by a given handler — is why
+ * SURFACE_NOTES.flags says "intended".
+ */
+import { type SessionDescriptor } from './session-contract.js';
+export type CommandFlag = {
+    readonly name: string;
+    readonly takesValue: boolean;
+    readonly meaning: string;
+};
+export type CommandRow = {
+    /** What you type after `toolroll` (subcommands included). */
+    readonly invocation: string;
+    /** The `command` field the envelope answers with, where it differs
+     * from the invocation (the no-verb report answers as "scan"). */
+    readonly envelopeCommand?: string;
+    readonly synopsis: string;
+    /** Who this act belongs to. "operator" rows are ceremonies or
+     * infrastructure: an agent must not invoke them even when credentials
+     * are within reach — the credential IS the person. The operator() helper
+     * omits flag detail on purpose; an explicit row may document flags when
+     * its command contract requires them. A schema is never permission. */
+    readonly audience: "agent" | "operator";
+    readonly agentMayInvoke: boolean;
+    /** Truthful retry semantics, not a boolean:
+     *  keyed — takes --key; same key returns the first answer.
+     *  identity-idempotent — repeating it converges (same lease, same
+     *    path, same managed file); no key needed.
+     *  unkeyed — a mutation without replay protection: do not blind-retry.
+     *  none — a read. */
+    readonly mutation: "keyed" | "identity-idempotent" | "unkeyed" | "none";
+    readonly positionals?: readonly {
+        name: string;
+        required: boolean;
+        meaning: string;
+    }[];
+    readonly flags?: readonly CommandFlag[];
+    readonly notableReasons?: readonly string[];
+    /** Session schemas are executable input contracts, not a grant of authority. */
+    readonly inputSchema?: SessionDescriptor['inputSchema'];
+};
+/** The guide's limits, stated machine-readably in every dump. */
+export declare const SURFACE_NOTES: {
+    readonly authority: "documentation is not permission; session descriptors also drive parser and request validation; legacy entries remain advisory";
+    readonly flags: "session flags are exact per operation; legacy flags are intended per command and may use a global parser vocabulary";
+    readonly reasons: "curated, not exhaustive — the runtime `reason` field is the truth; ignore tokens you do not recognize";
+    readonly database: "local database commands wait up to 15 seconds for another writer; an exhausted wait returns database-busy and names the selected file";
+};
+export declare const SURFACE_SCHEMA_VERSION = 1;
+export declare const COMMAND_GUIDE: readonly CommandRow[];