toolroll 0.5.0

package/dist/issues.d.ts

@@ -0,0 +1,41 @@
+/**
+ * GitHub Issues, through `gh`.
+ *
+ * No new credential: `gh` is already authenticated on any machine where the
+ * rest of this tool works, which is the same reason pull requests are read
+ * that way. Nothing here holds a token.
+ *
+ * Two things it deliberately will not do.
+ *
+ * **It will not write dependency edges.** GitHub grew native `blocked_by`
+ * relations and sub-issues, and the design says to use them *where a
+ * capability probe confirms them* — including a `gh` new enough to expose the
+ * fields. This adapter has confirmed neither the endpoint shape nor the
+ * version behaviour against a live repository, so it refuses instead of
+ * guessing, and refuses rather than emulating. An invented edge would make our
+ * scheduler disagree with what every human on the repository can see.
+ *
+ * **It will not reach the network on the scheduler's hot path.** Reading is a
+ * round trip per repository, and GitHub allows five thousand authenticated
+ * requests an hour; a scheduler polling dependencies for a hundred issues once
+ * a minute would exhaust that before doing any real work. §4's answer is a
+ * materialised snapshot read out of band, which is the scheduler's job to hold
+ * — this module just makes each read explicit and bounded so that when the
+ * scheduler arrives it is obvious what costs a network call.
+ */
+import type { Deps } from "./graph.js";
+import { type GraphBackend, type Runner } from "./backend.js";
+/** A network round trip; bounded like the pull request read it sits beside. */
+export declare const ISSUE_TIMEOUT_MS = 20000;
+/** Enough to see a backlog without paginating. */
+export declare const DEFAULT_LIMIT = 100;
+export type IssuesOptions = {
+    repo: string;
+    runner?: Runner;
+    limit?: number;
+    /** Overridden when a caller is spending a shared budget; see `remote.ts`. */
+    timeoutMs?: number;
+    /** Whether `gh` is new enough for the dependency fields; see `graph.ts`. */
+    deps?: Deps;
+};
+export declare function githubIssues(options: IssuesOptions): GraphBackend;

package/dist/issues.js

@@ -0,0 +1,131 @@
+/**
+ * GitHub Issues, through `gh`.
+ *
+ * No new credential: `gh` is already authenticated on any machine where the
+ * rest of this tool works, which is the same reason pull requests are read
+ * that way. Nothing here holds a token.
+ *
+ * Two things it deliberately will not do.
+ *
+ * **It will not write dependency edges.** GitHub grew native `blocked_by`
+ * relations and sub-issues, and the design says to use them *where a
+ * capability probe confirms them* — including a `gh` new enough to expose the
+ * fields. This adapter has confirmed neither the endpoint shape nor the
+ * version behaviour against a live repository, so it refuses instead of
+ * guessing, and refuses rather than emulating. An invented edge would make our
+ * scheduler disagree with what every human on the repository can see.
+ *
+ * **It will not reach the network on the scheduler's hot path.** Reading is a
+ * round trip per repository, and GitHub allows five thousand authenticated
+ * requests an hour; a scheduler polling dependencies for a hundred issues once
+ * a minute would exhaust that before doing any real work. §4's answer is a
+ * materialised snapshot read out of band, which is the scheduler's job to hold
+ * — this module just makes each read explicit and bounded so that when the
+ * scheduler arrives it is obvious what costs a network call.
+ */
+import { run } from "./exec.js";
+import { ok, no, edgesNotEmulated, describeFailure, parseJson, } from "./backend.js";
+const GH = "gh";
+/** A network round trip; bounded like the pull request read it sits beside. */
+export const ISSUE_TIMEOUT_MS = 20_000;
+/** Enough to see a backlog without paginating. */
+export const DEFAULT_LIMIT = 100;
+export function githubIssues(options) {
+    const { repo, runner = run, limit = DEFAULT_LIMIT, timeoutMs = ISSUE_TIMEOUT_MS, deps = "unverified", } = options;
+    const call = (args) => runner(GH, args, { cwd: repo, timeoutMs });
+    return {
+        name: "github-issues",
+        deps,
+        /**
+         * Every open issue. Without confirmed edges there is no dependency order
+         * to apply, so "ready" here means "open" — which is exactly why a backend
+         * in this state is not an autonomous-scheduling default.
+         */
+        async listReady() {
+            const result = await call([
+                "issue",
+                "list",
+                "--state",
+                "open",
+                "--limit",
+                String(limit),
+                "--json",
+                "number,title,state",
+            ]);
+            if (result.code !== 0)
+                return no("unreachable", describeFailure(result));
+            const parsed = parseJson(result.stdout);
+            if (!Array.isArray(parsed))
+                return no("unreadable", "gh returned something that is not a list");
+            return ok(parsed.map(readIssue).filter((task) => task !== null));
+        },
+        async get(id) {
+            const result = await call(["issue", "view", id, "--json", "number,title,state"]);
+            // gh returns non-zero for a missing issue, which is an answer rather
+            // than a fault: null means "not there", and the caller can tell that
+            // apart from "we could not ask".
+            if (result.code !== 0) {
+                return isMissing(result.stderr) ? ok(null) : no("unreachable", describeFailure(result));
+            }
+            const task = readIssue(parseJson(result.stdout));
+            return task === null ? no("unreadable", "gh returned an issue in a shape we do not know") : ok(task);
+        },
+        /**
+         * `gh issue create` prints the new issue's URL and nothing else, so the
+         * number is read back off the end of it. Parsed strictly: a URL we cannot
+         * read means we do not know what was created, and reporting a made-up id
+         * would be worse than reporting the failure.
+         */
+        async create(spec) {
+            const result = await call([
+                "issue",
+                "create",
+                "--title",
+                spec.title,
+                "--body",
+                spec.body ?? "Filed by Toolroll.",
+            ]);
+            if (result.code !== 0)
+                return no("rejected", describeFailure(result));
+            const number = /\/issues\/(\d+)\s*$/.exec(result.stdout.trim());
+            if (number?.[1] === undefined) {
+                return no("unreadable", "the issue was created, but gh did not print a URL we could read");
+            }
+            return ok(number[1]);
+        },
+        /**
+         * GitHub has two states, so everything terminal closes and everything
+         * else reopens. The mapping is lossy and says so rather than inventing
+         * labels to carry the difference — a `failed` task and a `done` one look
+         * the same to GitHub, and pretending otherwise would put our vocabulary
+         * into somebody else's tracker.
+         */
+        async setState(id, state) {
+            const closing = state === "done" || state === "failed" || state === "cancelled";
+            const result = await call(["issue", closing ? "close" : "reopen", id]);
+            if (result.code !== 0)
+                return no("rejected", describeFailure(result));
+            return ok(undefined);
+        },
+        async addEdge() {
+            return edgesNotEmulated("GitHub Issues");
+        },
+    };
+}
+function readIssue(record) {
+    if (typeof record !== "object" || record === null)
+        return null;
+    const raw = record;
+    const number = raw["number"];
+    if (typeof number !== "number")
+        return null;
+    return {
+        id: String(number),
+        title: typeof raw["title"] === "string" ? raw["title"] : "",
+        state: String(raw["state"]).toUpperCase() === "CLOSED" ? "done" : "queued",
+    };
+}
+function isMissing(stderr) {
+    const text = stderr.toLowerCase();
+    return text.includes("could not resolve") || text.includes("not found");
+}

package/dist/job-object-helper.ps1

@@ -0,0 +1,252 @@
+# The Windows Job Object helper (docs/PROCESS_CONTAINMENT_PLAN.md).
+#
+# Runs OUTSIDE the job it owns. Invoked by containment.ts only:
+#   powershell -NoProfile -NonInteractive -ExecutionPolicy Bypass -File job-object-helper.ps1 <pipe> <base64 json [file, ...args]>
+#
+# Protocol over the named pipe the controller listens on:
+#   helper -> controller   "attached"          the target was created SUSPENDED, assigned to a
+#                                              kill-on-close / no-breakaway job, then resumed
+#                          "failed <detail>"   the target never ran
+#                          "empty"             the job reports zero active processes
+#   controller -> helper   "kill"              TerminateJobObject, then report "empty" and exit
+# The helper exits with the root's exit code as soon as the job is empty;
+# members that outlive the root's natural exit are terminated after 2 s.
+# The controller's death closes the pipe: the helper terminates the job and exits, and the
+# job handle closing (kill-on-close) ends anything that raced that.
+#
+# The target inherits this helper's stdin/stdout/stderr (the controller's pipes), its
+# environment and its working directory verbatim; argv is re-quoted with the same rules
+# libuv uses, never re-parsed through a shell.
+
+param(
+  [Parameter(Position = 0)] [string] $Pipe,
+  # The target's argv - file first - as base64(UTF-8 JSON array): one opaque
+  # token, so PowerShell's own command-line parsing can never touch a quote,
+  # a space or a percent sign the controller passed.
+  [Parameter(Position = 1)] [string] $Encoded,
+  [string] $JobName,
+  [string] $QueryName
+)
+
+$ErrorActionPreference = "Stop"
+
+Add-Type -TypeDefinition @"
+using System;
+using System.Runtime.InteropServices;
+using System.Text;
+public static class SoJob {
+  [StructLayout(LayoutKind.Sequential, CharSet = CharSet.Unicode)]
+  public struct STARTUPINFO {
+    public int cb; public string lpReserved; public string lpDesktop; public string lpTitle;
+    public int dwX; public int dwY; public int dwXSize; public int dwYSize; public int dwXCountChars; public int dwYCountChars;
+    public int dwFillAttribute; public int dwFlags; public short wShowWindow; public short cbReserved2;
+    public IntPtr lpReserved2; public IntPtr hStdInput; public IntPtr hStdOutput; public IntPtr hStdError;
+  }
+  [StructLayout(LayoutKind.Sequential)]
+  public struct PROCESS_INFORMATION { public IntPtr hProcess; public IntPtr hThread; public int dwProcessId; public int dwThreadId; }
+  [StructLayout(LayoutKind.Sequential)]
+  public struct JOBOBJECT_BASIC_LIMIT_INFORMATION {
+    public long PerProcessUserTimeLimit; public long PerJobUserTimeLimit; public uint LimitFlags;
+    public UIntPtr MinimumWorkingSetSize; public UIntPtr MaximumWorkingSetSize; public uint ActiveProcessLimit;
+    public UIntPtr Affinity; public uint PriorityClass; public uint SchedulingClass;
+  }
+  [StructLayout(LayoutKind.Sequential)]
+  public struct IO_COUNTERS {
+    public ulong ReadOperationCount; public ulong WriteOperationCount; public ulong OtherOperationCount;
+    public ulong ReadTransferCount; public ulong WriteTransferCount; public ulong OtherTransferCount;
+  }
+  [StructLayout(LayoutKind.Sequential)]
+  public struct JOBOBJECT_EXTENDED_LIMIT_INFORMATION {
+    public JOBOBJECT_BASIC_LIMIT_INFORMATION BasicLimitInformation; public IO_COUNTERS IoInfo;
+    public UIntPtr ProcessMemoryLimit; public UIntPtr JobMemoryLimit; public UIntPtr PeakProcessMemoryUsed; public UIntPtr PeakJobMemoryUsed;
+  }
+  [StructLayout(LayoutKind.Sequential)]
+  public struct JOBOBJECT_BASIC_ACCOUNTING_INFORMATION {
+    public long TotalUserTime; public long TotalKernelTime; public long ThisPeriodTotalUserTime; public long ThisPeriodTotalKernelTime;
+    public uint TotalPageFaultCount; public uint TotalProcesses; public uint ActiveProcesses; public uint TotalTerminatedProcesses;
+  }
+  public const int JobObjectBasicAccountingInformation = 1;
+  public const int JobObjectExtendedLimitInformation = 9;
+  public const uint JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE = 0x2000;
+  public const uint CREATE_SUSPENDED = 0x4;
+  public const uint CREATE_UNICODE_ENVIRONMENT = 0x400;
+  public const int STARTF_USESTDHANDLES = 0x100;
+  [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)] public static extern IntPtr CreateJobObjectW(IntPtr attributes, string name);
+  [DllImport("kernel32.dll", SetLastError = true)] public static extern bool SetInformationJobObject(IntPtr job, int infoClass, IntPtr info, uint length);
+  [DllImport("kernel32.dll", SetLastError = true)] public static extern bool QueryInformationJobObject(IntPtr job, int infoClass, IntPtr info, uint length, IntPtr returned);
+  [DllImport("kernel32.dll", SetLastError = true)] public static extern bool AssignProcessToJobObject(IntPtr job, IntPtr process);
+  [DllImport("kernel32.dll", SetLastError = true)] public static extern bool TerminateJobObject(IntPtr job, uint exitCode);
+  [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)] public static extern bool CreateProcessW(string application, StringBuilder commandLine, IntPtr processAttributes, IntPtr threadAttributes, bool inheritHandles, uint creationFlags, IntPtr environment, string currentDirectory, ref STARTUPINFO startupInfo, out PROCESS_INFORMATION processInformation);
+  [DllImport("kernel32.dll", SetLastError = true)] public static extern uint ResumeThread(IntPtr thread);
+  [DllImport("kernel32.dll", SetLastError = true)] public static extern bool TerminateProcess(IntPtr process, uint exitCode);
+  [DllImport("kernel32.dll", SetLastError = true)] public static extern uint WaitForSingleObject(IntPtr handle, uint milliseconds);
+  [DllImport("kernel32.dll", SetLastError = true)] public static extern bool GetExitCodeProcess(IntPtr process, out uint exitCode);
+  [DllImport("kernel32.dll", SetLastError = true)] public static extern IntPtr GetStdHandle(int which);
+  [DllImport("kernel32.dll", SetLastError = true)] public static extern bool CloseHandle(IntPtr handle);
+
+  /** libuv's quoting rules: the target sees exactly the argv the controller passed. */
+  public static string Quote(string arg) {
+    if (arg.Length == 0) return "\"\"";
+    bool plain = true;
+    foreach (char c in arg) { if (c == ' ' || c == '\t' || c == '"' || c == '\n' || c == '\r') { plain = false; break; } }
+    if (plain) return arg;
+    var sb = new StringBuilder();
+    sb.Append('"');
+    int backslashes = 0;
+    foreach (char c in arg) {
+      if (c == '\\') { backslashes++; continue; }
+      if (c == '"') { sb.Append('\\', backslashes * 2 + 1); sb.Append('"'); backslashes = 0; continue; }
+      sb.Append('\\', backslashes); sb.Append(c); backslashes = 0;
+    }
+    sb.Append('\\', backslashes * 2);
+    sb.Append('"');
+    return sb.ToString();
+  }
+
+  [DllImport("kernel32.dll", CharSet = CharSet.Unicode, SetLastError = true)] public static extern IntPtr OpenJobObjectW(uint access, bool inherit, string name);
+  public static string Inspect(string name) {
+    IntPtr job = OpenJobObjectW(4, false, name); // JOB_OBJECT_QUERY only
+    if (job == IntPtr.Zero) return Marshal.GetLastWin32Error() == 2 ? "empty" : "unknown";
+    try { return ActiveProcesses(job) == 0 ? "empty" : "populated"; }
+    catch { return "unknown"; }
+    finally { CloseHandle(job); }
+  }
+  public static IntPtr MakeJob(string name) {
+    IntPtr job = CreateJobObjectW(IntPtr.Zero, name);
+    int createdError = Marshal.GetLastWin32Error();
+    if (job != IntPtr.Zero && createdError == 183) { CloseHandle(job); throw new Exception("job name already exists"); }
+    if (job == IntPtr.Zero) throw new Exception("CreateJobObject failed: " + Marshal.GetLastWin32Error());
+    var info = new JOBOBJECT_EXTENDED_LIMIT_INFORMATION();
+    // Kill on close; NO breakaway flags, so nothing inside may leave the job.
+    info.BasicLimitInformation.LimitFlags = JOB_OBJECT_LIMIT_KILL_ON_JOB_CLOSE;
+    int size = Marshal.SizeOf(typeof(JOBOBJECT_EXTENDED_LIMIT_INFORMATION));
+    IntPtr buffer = Marshal.AllocHGlobal(size);
+    try {
+      Marshal.StructureToPtr(info, buffer, false);
+      if (!SetInformationJobObject(job, JobObjectExtendedLimitInformation, buffer, (uint)size)) throw new Exception("SetInformationJobObject failed: " + Marshal.GetLastWin32Error());
+    } finally { Marshal.FreeHGlobal(buffer); }
+    return job;
+  }
+
+  public static uint ActiveProcesses(IntPtr job) {
+    int size = Marshal.SizeOf(typeof(JOBOBJECT_BASIC_ACCOUNTING_INFORMATION));
+    IntPtr buffer = Marshal.AllocHGlobal(size);
+    try {
+      if (!QueryInformationJobObject(job, JobObjectBasicAccountingInformation, buffer, (uint)size, IntPtr.Zero)) throw new Exception("QueryInformationJobObject failed: " + Marshal.GetLastWin32Error());
+      var info = (JOBOBJECT_BASIC_ACCOUNTING_INFORMATION)Marshal.PtrToStructure(buffer, typeof(JOBOBJECT_BASIC_ACCOUNTING_INFORMATION));
+      return info.ActiveProcesses;
+    } finally { Marshal.FreeHGlobal(buffer); }
+  }
+
+  public static PROCESS_INFORMATION StartSuspended(string commandLine) {
+    var si = new STARTUPINFO();
+    si.cb = Marshal.SizeOf(typeof(STARTUPINFO));
+    si.dwFlags = STARTF_USESTDHANDLES;
+    si.hStdInput = GetStdHandle(-10); si.hStdOutput = GetStdHandle(-11); si.hStdError = GetStdHandle(-12);
+    PROCESS_INFORMATION pi;
+    var cmd = new StringBuilder(commandLine);
+    if (!CreateProcessW(null, cmd, IntPtr.Zero, IntPtr.Zero, true, CREATE_SUSPENDED | CREATE_UNICODE_ENVIRONMENT, IntPtr.Zero, null, ref si, out pi)) {
+      throw new Exception("CreateProcess failed: " + Marshal.GetLastWin32Error());
+    }
+    return pi;
+  }
+}
+"@
+
+if ($QueryName) {
+  if ($QueryName -cnotmatch '^Global\\so-[A-Za-z0-9._-]+-[a-f0-9]{64}$') { Write-Output "unknown"; exit 0 }
+  Write-Output ([SoJob]::Inspect($QueryName)); exit 0
+}
+if ($JobName -cnotmatch '^Global\\so-[A-Za-z0-9._-]+-[a-f0-9]{64}$') { throw "invalid job custody name" }
+$name = $Pipe
+if ($name.StartsWith("\\.\pipe\")) { $name = $name.Substring(9) }
+# Duplex control requires an overlapped handle: on .NET Framework a pending
+# asynchronous read on a synchronous PipeStream can serialize a concurrent
+# write. That would delay the empty reply until another order arrives.
+$client = New-Object System.IO.Pipes.NamedPipeClientStream(".", $name, [System.IO.Pipes.PipeDirection]::InOut, [System.IO.Pipes.PipeOptions]::Asynchronous)
+$client.Connect(5000)
+$writer = New-Object System.IO.StreamWriter($client)
+$writer.AutoFlush = $true
+$reader = New-Object System.IO.StreamReader($client)
+
+function Send([string] $line) { try { $writer.Write($line + "`n") } catch { } }
+
+$job = [IntPtr]::Zero
+$pi = $null
+try {
+  [string[]]$targetArguments = ConvertFrom-Json -InputObject ([System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String($Encoded)))
+  if ($targetArguments.Count -lt 1) { throw "the target argv is empty" }
+  # Admission arrives only after the controller durably records this helper.
+  $job = [SoJob]::MakeJob($JobName)
+  Send "ready"
+  $admission = $reader.ReadLineAsync()
+  if (-not $admission.Wait(15000) -or $admission.Result -cne "go") { throw "job admission refused" }
+  $parts = @()
+  foreach ($arg in $targetArguments) { $parts += [SoJob]::Quote([string]$arg) }
+  $pi = [SoJob]::StartSuspended(($parts -join " "))
+  if (-not [SoJob]::AssignProcessToJobObject($job, $pi.hProcess)) {
+    $code = [System.Runtime.InteropServices.Marshal]::GetLastWin32Error()
+    [void][SoJob]::TerminateProcess($pi.hProcess, 126)
+    Send ("failed AssignProcessToJobObject failed with Win32 error " + $code + " - the target never ran")
+    exit 126
+  }
+  if ([SoJob]::ResumeThread($pi.hThread) -eq [uint32]::MaxValue) { throw "ResumeThread failed" }
+  Send "attached"
+} catch {
+  if ($pi -ne $null -and $pi.hProcess -ne [IntPtr]::Zero) { [void][SoJob]::TerminateProcess($pi.hProcess, 126) }
+  if ($job -ne [IntPtr]::Zero) { [void][SoJob]::TerminateJobObject($job, 126); [void][SoJob]::CloseHandle($job) }
+  Send ("failed " + $_.Exception.Message)
+  exit 126
+}
+
+# Orders from the controller are read asynchronously on this one thread (a
+# PowerShell runspace is single-threaded; ReadLineAsync polls without one). The
+# pipe closing - the controller died - is itself the order to terminate.
+$pendingRead = $reader.ReadLineAsync()
+$pipeClosed = $false
+function NextOrders {
+  $found = @()
+  while ($script:pendingRead -ne $null -and $script:pendingRead.IsCompleted) {
+    $line = $null
+    try { $line = $script:pendingRead.Result } catch { $line = $null }
+    if ($line -eq $null) { $script:pipeClosed = $true; $script:pendingRead = $null; $found += "closed"; break }
+    $found += $line.Trim()
+    $script:pendingRead = $reader.ReadLineAsync()
+  }
+  return $found
+}
+
+$exitCode = 1
+$rootExited = $false
+$rootExitedAt = $null
+while ($true) {
+  if (-not $rootExited -and [SoJob]::WaitForSingleObject($pi.hProcess, 50) -eq 0) {
+    $rootExited = $true
+    $rootExitedAt = Get-Date
+    $c = [uint32]0
+    if ([SoJob]::GetExitCodeProcess($pi.hProcess, [ref]$c)) { $exitCode = [int]$c }
+  }
+  foreach ($order in (NextOrders)) {
+    # A stop from the controller, or the controller's death (pipe closed):
+    # end every member now. "release" needs nothing here - the helper exits
+    # on its own the moment the job is proven empty.
+    if ($order -eq "kill" -or $order -eq "closed") { [void][SoJob]::TerminateJobObject($job, 137); if (-not $rootExited) { $rootExited = $true; $rootExitedAt = Get-Date; $exitCode = 137 } }
+  }
+  if ($rootExited) {
+    $active = [SoJob]::ActiveProcesses($job)
+    if ($active -eq 0) { Send "empty"; break }
+    # The root is gone but members remain (a detached grandchild): natural
+    # exit cleans them up too, after a short grace for the ordinary case.
+    if (((Get-Date) - $rootExitedAt).TotalMilliseconds -gt 2000) { [void][SoJob]::TerminateJobObject($job, 137) }
+  }
+  Start-Sleep -Milliseconds 50
+}
+[void][SoJob]::CloseHandle($pi.hThread)
+[void][SoJob]::CloseHandle($pi.hProcess)
+[void][SoJob]::CloseHandle($job)
+# This is a dedicated helper process. A pending .NET pipe read can prevent
+# PowerShell's normal host shutdown, and disposing its shared stream can
+# wait for that read. The kernel has already proved the job empty and all
+# owned process/job handles are closed. Exit the helper process directly;
+# Windows closes the pipe and cancels pending IO without a disposal wait.
+[Environment]::Exit($exitCode)

package/dist/jsonl-discriminants.d.ts

@@ -0,0 +1,11 @@
+/** Bounded structural metadata for an event whose text may exceed the wire
+ * cap. Long JSON strings become null in a small skeleton, but every escape
+ * is still validated. JSON.parse proves the remaining structure. Unknown,
+ * malformed or over-complex input never earns permission to discard it. */
+export declare function jsonlDiscriminants(): {
+    push(bytes: Buffer): void;
+    finish(): {
+        type: string;
+        itemType: string | null;
+    } | null;
+};

package/dist/jsonl-discriminants.js

@@ -0,0 +1,93 @@
+/** Bounded structural metadata for an event whose text may exceed the wire
+ * cap. Long JSON strings become null in a small skeleton, but every escape
+ * is still validated. JSON.parse proves the remaining structure. Unknown,
+ * malformed or over-complex input never earns permission to discard it. */
+export function jsonlDiscriminants() {
+    const skeleton = Buffer.allocUnsafe(64 * 1024);
+    const token = Buffer.allocUnsafe(256);
+    let size = 0;
+    let tokenSize = 0;
+    let longString = false;
+    let inString = false;
+    let escaped = false;
+    let unicode = 0;
+    let invalid = false;
+    const emit = (byte) => {
+        if (size >= skeleton.length)
+            invalid = true;
+        else
+            skeleton[size++] = byte;
+    };
+    const remember = (byte) => {
+        if (tokenSize < token.length)
+            token[tokenSize++] = byte;
+        else
+            longString = true;
+    };
+    return {
+        push(bytes) {
+            for (const byte of bytes) {
+                if (invalid)
+                    return;
+                if (!inString) {
+                    if (byte === 34) {
+                        inString = true;
+                        tokenSize = 0;
+                        longString = false;
+                        remember(byte);
+                    }
+                    else if (byte === 32 || byte === 9 || byte === 13) {
+                        if (size === 0 || skeleton[size - 1] !== 32)
+                            emit(32);
+                    }
+                    else
+                        emit(byte);
+                    continue;
+                }
+                remember(byte);
+                if (unicode > 0) {
+                    if (!(byte >= 48 && byte <= 57 || byte >= 65 && byte <= 70 || byte >= 97 && byte <= 102))
+                        invalid = true;
+                    unicode--;
+                }
+                else if (escaped) {
+                    escaped = false;
+                    if (byte === 117)
+                        unicode = 4;
+                    else if (![34, 92, 47, 98, 102, 110, 114, 116].includes(byte))
+                        invalid = true;
+                }
+                else if (byte === 92)
+                    escaped = true;
+                else if (byte === 34) {
+                    inString = false;
+                    // A long key also becomes null, which is invalid JSON: refuse
+                    // classification rather than invent a possibly colliding key.
+                    const value = longString ? Buffer.from("null") : token.subarray(0, tokenSize);
+                    for (const one of value)
+                        emit(one);
+                }
+                else if (byte < 32)
+                    invalid = true;
+            }
+        },
+        finish() {
+            if (invalid || inString)
+                return null;
+            try {
+                const event = JSON.parse(skeleton.toString("utf8", 0, size));
+                if (event === null || typeof event !== "object" || Array.isArray(event))
+                    return null;
+                const { type, item } = event;
+                if (typeof type !== "string")
+                    return null;
+                const itemType = item !== null && typeof item === "object" && !Array.isArray(item)
+                    ? item["type"] : null;
+                return { type, itemType: typeof itemType === "string" ? itemType : null };
+            }
+            catch {
+                return null;
+            }
+        },
+    };
+}

package/dist/keys.d.ts

@@ -0,0 +1,104 @@
+/**
+ * Provider API keys, managed instead of ambient (the gap the gemini
+ * live-auth work exposed): one 0600 file per provider under
+ * ~/.toolroll/keys/ (or an older ~/.standing-orders/keys/), written from the settings card or piped into
+ * the CLI — never typed into an argv, never rendered back, never stored
+ * in the database a backup might carry.
+ *
+ * The injection contract lives in the invocation gateway: a stored key is
+ * added to EXACTLY its own provider's child environment at spawn, where
+ * the adapter's foreign-credential strip has already shed everybody
+ * else's. The plane's own process never needs the key in its environment
+ * at all — a restart or a rotation is a file write, not a relaunch — and
+ * an ambient env var still works as the fallback it always was (the file,
+ * being deliberate, wins).
+ */
+import type { ProviderId } from "./provider.js";
+/** The ONE env name each provider's own harness reads its key from —
+ * where a managed key is INJECTED. */
+export declare const PROVIDER_KEY_ENV: Record<ProviderId, string>;
+/** EVERY env name a provider reads its OWN key from — what subscription
+ * mode STRIPS so an ambient key cannot override the login. gemini reads
+ * two; the rest read one. */
+export declare const OWN_KEY_ENV: Record<ProviderId, readonly string[]>;
+export declare function keysDir(home?: string): string;
+/**
+ * How a provider authenticates (the operator's ruling 2026-08-29: keep
+ * BOTH, prefer the subscription). "subscription" uses the CLI's OWN login
+ * — a Claude/ChatGPT plan, a Google cached login — and the API key is
+ * kept but NOT handed to the process, so its own auth wins. "api-key"
+ * hands the stored (or ambient) key to the process. openrouter has no
+ * login and is always api-key.
+ */
+export type AuthMode = "subscription" | "api-key";
+/** Providers that CAN authenticate without an API key (a subscription or
+ * cached login). openrouter cannot — it is api-key only. */
+export declare const SUBSCRIPTION_CAPABLE: Record<ProviderId, boolean>;
+/** The default when nothing is set: subscription where it exists (prefer
+ * the plan the operator already pays for), api-key otherwise. */
+export declare const DEFAULT_AUTH_MODE: Record<ProviderId, AuthMode>;
+export declare function readAuthMode(provider: ProviderId, home?: string): AuthMode;
+/**
+ * The auth mode as an AUTHORITY reads it (raw authority repair): an absent
+ * file is the provider's default, but a file that is present and says
+ * neither `subscription` nor `api-key` is a stated problem — never the
+ * subscription default a lenient read would coerce it to. A provider with
+ * no subscription login is the key, whatever the file says.
+ */
+export declare function readAuthModeStrict(provider: ProviderId, home?: string): {
+    ok: true;
+    mode: AuthMode;
+} | {
+    ok: false;
+    problem: string;
+};
+export declare function setAuthMode(provider: ProviderId, mode: AuthMode, home?: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "no-subscription";
+};
+export declare function keyFileFor(provider: ProviderId, home?: string): string;
+/** Shape check only — never a validity claim. A key is printable ASCII
+ * without whitespace, bounded; anything else is a paste accident. */
+export declare function plausibleKey(value: string): boolean;
+export declare function saveProviderKey(provider: ProviderId, value: string, home?: string): {
+    ok: true;
+} | {
+    ok: false;
+    reason: "implausible";
+};
+export declare function readProviderKey(provider: ProviderId, home?: string): string | null;
+export declare function clearProviderKey(provider: ProviderId, home?: string): boolean;
+/**
+ * A live credential check that spends NO tokens: each provider exposes a
+ * cheap authenticated GET (its model list, or a key-info route) whose only
+ * job here is to make the provider's own auth boundary answer yes or no.
+ * Injectable fetcher (the converse.ts precedent) so tests never touch the
+ * network. Distinguishes a REJECTED key (bad/expired/wrong provider) from
+ * an UNREACHABLE provider (offline, blocked) — the operator needs to know
+ * which, because only one of them means "fix the key".
+ */
+export type KeyVerdict = {
+    ok: true;
+} | {
+    ok: false;
+    reason: "rejected";
+    status: number;
+} | {
+    ok: false;
+    reason: "unreachable";
+} | {
+    ok: false;
+    reason: "unexpected";
+    status: number;
+};
+export declare function verifyProviderKey(provider: ProviderId, value: string, fetcher?: typeof fetch, timeoutMs?: number): Promise<KeyVerdict>;
+/** Words for a verdict, safe to render on any surface (never the key). */
+export declare function verdictWords(provider: ProviderId, verdict: KeyVerdict): string;
+/** What a surface may say about a key: that it exists and when it last
+ * changed — NEVER the value, never a prefix, never a length. */
+export declare function keyStatus(provider: ProviderId, home?: string): {
+    set: boolean;
+    updatedAt: string | null;
+};