toolroll 0.9.104 → 0.9.105

package/dist/runner.d.ts

@@ -1,324 +0,0 @@
-/**
- * A machine that may be given work.
- *
- * Auth is here from the first commit, and that is a deliberate ordering rather
- * than diligence for its own sake. A control plane that dispatches work to
- * unauthenticated runners for six months grows six months of code that assumes
- * the caller is whoever it says it is, and retrofitting identity into that is
- * how the retrofit gets a hole in it. It costs almost nothing to do now.
- *
- * **The token is never stored.** Registration mints one, prints it once, and
- * keeps only a hash. There is no command that recovers it, because a control
- * plane able to hand back a runner's credential is one whose database is worth
- * stealing — and because the same rule governs secrets everywhere else in this
- * design: the control plane holds metadata, the runner holds values.
- *
- * Liveness is separate from a lease expiring, and the distinction matters at
- * 3am. A lease expires because time passed; a runner is dead because it
- * stopped saying otherwise. Reaping on the first tells you a task is free
- * again. Reaping on the second tells you a *machine* is gone, and everything
- * it was holding — claims and worktrees alike — needs recovering together.
- */
-import { type AcpProviderId } from "./acp-agents.js";
-import type { AcpAttestation } from "./store.js";
-import { type Store, type Mutation } from "./store.js";
-import { type ProviderId } from "./provider.js";
-import type { ReadinessObservation } from "./phase-routing.js";
-/** A runner's repo binding, in the same canonical form task filing uses —
- * the claim gate compares these by equality, so both sides must resolve
- * through one convention (MCP gateway spec v6, the runner tuple). */
-export declare function canonicalRepos(repos: readonly string[]): string[];
-export type Runner = {
-    name: string;
-    host: string;
-    /** How many tasks it will hold at once. */
-    capacity: number;
-    repos: string[];
-    agents: string[];
-    registeredAt: string;
-    heartbeatAt: string;
-    retiredAt: string | null;
-    /** The queue column's theme note (v19) — operator prose, display only. */
-    queueNote?: string | null;
-};
-export type Registration = {
-    runner: Runner;
-    token: string;
-    /** What the previous holder of this name was still holding, taken back. */
-    reclaimed: Reclaim | null;
-};
-export type AuthResult = {
-    ok: true;
-    runner: Runner;
-} | {
-    ok: false;
-    reason: "unknown" | "bad-token" | "retired" | "expired";
-};
-/** v101: a runner's token lasts a year from its registration; registering again (every start does) renews it. */
-export declare const RUNNER_TOKEN_MS: number;
-/**
- * How long a runner may go quiet before it is presumed gone.
- *
- * Four heartbeats (RUNNER_HEARTBEAT_MS): one slow check-in never declares a busy
- * machine dead, and a machine that really is gone holds its name for a minute,
- * not three (docs/plans/actors-lessons.md). A clean stop doesn't wait even that
- * long: a draining or stopped holder never blocks the next start
- * (registerRunnerIfIdle).
- */
-export declare const DEFAULT_LIVENESS_MS = 60000;
-/** How often a live runner says so: `up`'s runner heartbeat and every watch lease renewal. */
-export declare const RUNNER_HEARTBEAT_MS = 15000;
-/** The longest a watch lease may be taken or renewed for (durable-actors' MAX_HOST_LEASE_DURATION_MS): a crashed
- * holder's projects are free within a minute. The store clamps every ttl to it. */
-export { MAX_WATCH_LEASE_MS } from "./store.js";
-export type RegisterOptions = {
-    name: string;
-    host: string;
-    capacity?: number;
-    repos?: readonly string[];
-    agents?: readonly string[];
-    now: Date;
-    /** Injected so a test can assert on a token it chose. */
-    newToken?: () => string;
-    mutation?: Mutation;
-};
-export declare function register(store: Store, options: RegisterOptions): Registration;
-/**
- * Whether this caller is who it says it is.
- *
- * Compared in constant time. The comparison is between hashes rather than
- * secrets, so the practical risk is slight — but a timing-variable equality on
- * a credential path is the kind of thing that gets copied into somewhere it
- * matters, and there is no reason to leave the example lying around.
- */
-export declare function authenticate(store: Store, name: string, token: string): AuthResult;
-/**
- * "I am still here." Authenticated AND ATOMIC (arc 2 findings 25/33): the
- * hash is verified and the heartbeat stamped in one write transaction, so
- * a takeover that rotates the credential between the check and the touch
- * cannot receive a stale incarnation's pulse — after rotation commits, the
- * very next heartbeat refuses, and the caller must treat that as fatal.
- */
-export declare function heartbeat(store: Store, name: string, token: string, now: Date): AuthResult;
-/**
- * Extend a live runner's project binding using that runner's own credential.
- *
- * `up` owns both the credential and the registry watcher, so a project the
- * operator admitted through its console can join without a second operator
- * ceremony or a restart. Authentication and the additive write share one
- * transaction: a replaced process cannot widen its successor's binding.
- */
-export declare function addRunnerReposAuthed(store: Store, args: {
-    name: string;
-    token: string;
-    repos: readonly string[];
-}, now: Date): AuthResult;
-/**
- * Narrow a live runner's binding when a project is removed, under the same
- * credential and transaction as addRunnerReposAuthed. `up` calls it only
- * after that project's watch has stopped admitting work.
- */
-export declare function removeRunnerRepoAuthed(store: Store, args: {
-    name: string;
-    token: string;
-    repo: string;
-}, now: Date): AuthResult;
-/**
- * The one runner-name rule (arc 2 finding 13): nonempty, control-free, at
- * most 60 characters — the console form's rule, now shared by every door.
- */
-export declare const RUNNER_NAME_MAX = 60;
-/** The most tasks one worker may be set to run at once (the console's register form says the same). */
-export declare const RUNNER_CAPACITY_MAX = 64;
-/** A capacity as typed; changing an existing worker may use zero to drain it. */
-export declare function parseRunnerCapacity(value: string, { allowZero }?: {
-    allowZero?: boolean | undefined;
-}): number | null;
-export declare function validRunnerName(name: string): boolean;
-/** A generated base name: lowercase [a-z0-9-], collapsed, trimmed. The
- * suffix budget (finding 24) is the CALLER's arithmetic — truncate the
- * base to `RUNNER_NAME_MAX - suffix.length` before appending. */
-export declare function normalizeRunnerName(raw: string): string;
-/**
- * The atomic take-or-refuse door (arc 2 findings 1/15/16/26/31): ONE write
- * transaction that proves the name is free — absent, retired, or dead by
- * the same predicate recovery uses, with NO unexpired watch lease — then
- * finishes every open run the dead holder left (requeueing what no newer
- * live claim owns), reclaims, and rotates. Two racers serialize: one wins,
- * the other gets the typed refusal.
- */
-export declare function registerRunnerIfIdle(store: Store, options: RegisterOptions & {
-    /**
-     * Whether the name's current holder is proved gone (runner-process.ts): every process it handed its credential to
-     * has exited, verified by identity. Asked only while the holder still blocks the name, inside this transaction;
-     * a proof retires that holder and lapses its watch leases here, so a stale heartbeat never outlives its processes.
-     */
-    previousGone?: (holder: {
-        runner: Runner;
-        credentialHash: string;
-    }) => {
-        gone: true;
-        detail: string;
-    } | {
-        gone: false;
-        why: string;
-    };
-}): (Registration & {
-    ok: true;
-    recoveredRuns: number;
-    signedOff: string | null;
-}) | {
-    ok: false;
-    reason: "runner-alive" | "watch-live";
-    detail: string;
-} | {
-    ok: false;
-    reason: "runner-draining";
-    detail: string;
-    until: string;
-};
-/**
- * The authenticated lease door (arc 2 findings 15/26): credential verified
- * and lease acquired/renewed in the SAME transaction — after a takeover
- * rotates the hash, a stale incarnation can neither acquire nor renew. A
- * takeover of an expired lease recovers the superseded incarnation INSIDE
- * this transaction, so no crash can separate "B owns the lease" from "A
- * was recovered".
- */
-export declare function acquireWatchLeaseAuthed(store: Store, args: {
-    runner: string;
-    token: string;
-    repo: string;
-    owner: string;
-    ttlMs: number;
-}, now: Date): {
-    ok: true;
-    generation: number;
-    superseded: string | null;
-    recovered: number;
-} | {
-    ok: false;
-    reason: "unknown" | "bad-token" | "retired" | "expired" | "watch-busy" | "unauthorized-repo";
-    holder?: string;
-    until?: string;
-};
-/** The renewal, equally authenticated: a false answer is FATAL to the
- * caller — a loop that keeps admitting work after losing its lease or its
- * credential is the exact hole the doors exist to close. */
-export declare function heartbeatWatchLeaseAuthed(store: Store, args: {
-    runner: string;
-    token: string;
-    repo: string;
-    owner: string;
-    ttlMs: number;
-}, now: Date): boolean;
-/**
- * Retirement fenced by THIS holder's credential (arc 2 finding 28): a
- * successor that already rotated makes the predecessor's cleanup a typed
- * no-op instead of retiring the winner.
- */
-export declare function retireRunnerIfCurrent(store: Store, name: string, token: string, now: Date): {
-    ok: true;
-} | {
-    ok: false;
-    reason: "unknown" | "bad-token" | "retired" | "expired";
-};
-export declare function isAlive(runner: Runner, now: Date, livenessMs?: number): boolean;
-/** Runners that have stopped saying they are there. */
-export declare function deadRunners(store: Store, now: Date, livenessMs?: number): Runner[];
-/** What a re-registration takes back from the previous holder of its name. */
-export type Reclaim = {
-    runner: string;
-    /** Lease ids released because the machine holding them is gone. */
-    claims: string[];
-    /** Worktree paths handed back to the pool. */
-    worktrees: string[];
-};
-/** What one reconcile pass took back from a proven-dead runner. */
-export type Recovery = Reclaim & {
-    /** Run ids finished as failed/interrupted because the machine that opened
-     * them is gone — including runs whose claim a reaper or the runner itself
-     * had already released (P0.1a). */
-    runs: number[];
-    /** Built-in task ids returned to the queue because no newer live lease
-     * owned them once the dead runner's rows were settled. */
-    requeued: string[];
-};
-/** Whether a pass found anything at all to take back. */
-export declare function recoveredAnything(one: Recovery): boolean;
-/**
- * Take back everything a dead runner was holding.
- *
- * Claims, open runs, and worktrees together, in one pass, because they are
- * halves of the same fact: the machine is gone. Recovering one and not the
- * others leaves a task dispatchable with its working copy still checked out
- * to a process that no longer exists — which fails later, further away, and
- * looks like a git problem rather than a scheduling one — or a run record
- * that stays open forever after its lease was released and a successor
- * finished the work (P0.1a: the real run 1501).
- *
- * Runs settle through the same transactional walk the takeover door uses
- * (`recoverRunnerWork`), AFTER this runner's claims are released: the walk
- * finishes every open run recorded against the runner outside a live held
- * session as failed/interrupted, and requeues its task only when no newer
- * live lease owns it. A finished outcome is never rewritten; a successor's
- * claim, run, worktree, and task state are somebody else's rows and stay
- * exactly as they were.
- *
- * Worktrees are handed back **unverified**. Nobody watched what the dead
- * process was doing when it stopped, so the directory on disk is a claim about
- * the past rather than a description of the present, and something has to look
- * before it is reused.
- */
-export declare function recoverDead(store: Store, now: Date, livenessMs?: number): Recovery[];
-export declare function hashToken(token: string): string;
-/**
- * What ONE machine can say about a provider without spending a token:
- * the binary answers `--version`; where a cheap identity probe exists
- * (codex, openrouter: `login status`) whether it is logged in; where a key
- * env var is required (openrouter) whether it is present; and, for an
- * attested provider (gemini), whether the installed version is inside the
- * range this build proved. Claude has no non-spending login check, so an
- * installed claude is UNKNOWN — stated, never upgraded to ready.
- *
- * Every answer carries the probe's own words. The observation is the
- * runner's and is recorded under its name only through the authenticated
- * road below; a runner never reports for another machine.
- */
-export type ReadinessProbe = (file: string, args: readonly string[], options?: {
-    timeoutMs?: number;
-    omitEnv?: readonly string[];
-}) => Promise<{
-    code: number;
-    stdout: string;
-    stderr: string;
-    notFound: boolean;
-    timedOut: boolean;
-}>;
-export declare function observeProviderReadiness(probe: ReadinessProbe, env?: Record<string, string | undefined>, providers?: readonly ProviderId[], 
-/** An ACP agent's live check on this runner (store.acpAttestationFor), when the caller can read one. */
-acpChecked?: (provider: AcpProviderId) => AcpAttestation | null): Promise<Omit<ReadinessObservation, "runner" | "observedAt">[]>;
-/**
- * Record a runner's observations under its OWN authenticated name: the
- * credential is verified and the rows written in one transaction, so a
- * replaced incarnation cannot report for its successor, and no caller can
- * report for a machine it does not hold the token of.
- */
-export declare function reportProviderReadinessAuthed(store: Store, args: {
-    name: string;
-    token: string;
-    observations: readonly Omit<ReadinessObservation, "runner" | "observedAt">[];
-}, now: Date): AuthResult;
-/** A worker's lifecycle row (service_lifecycle). */
-export declare const workerComponent: (name: string) => string;
-/**
- * The stop begins (durable-actors' draining report), fenced by this holder's credential: from now this runner takes
- * no new work (claim.ts acquire refuses). `until` is a schedule, never proof that the holder exited.
- */
-export declare function drainRunnerIfCurrent(store: Store, name: string, token: string, now: Date, until: Date): boolean;
-/** A runner's drain as its own lifecycle row reports it (only the current registration's row counts): null when it
- * isn't draining; ended once its bound passed or it reported stopped. */
-export declare function drainOf(store: Store, runner: Runner, now: Date): {
-    until: string;
-    ended: boolean;
-} | null;

package/dist/sample-project.d.ts

@@ -1,31 +0,0 @@
-import { type ExecResult, type RunOptions } from "./exec.js";
-import type { Store } from "./store.js";
-export type GitRun = (file: string, args: readonly string[], options: RunOptions) => Promise<ExecResult>;
-export type SampleOutcome = {
-    ok: true;
-    path: string;
-    created: boolean;
-} | {
-    ok: false;
-    reason: "no-root" | "exists" | "failed";
-    message: string;
-};
-/** Make (or find again) the sample project in `root`, the folder projects go in. */
-export declare function createSampleProject(root: string | null, git?: GitRun): Promise<SampleOutcome>;
-/** The sample's own check: its one test file, run by Node's test runner. Fixed here; never anyone's input. */
-export declare const SAMPLE_CHECK_COMMAND = "node --test";
-/** Who the sample's check is recorded as approved by: Toolroll itself, never the person who clicked (no step-up). */
-export declare const SAMPLE_CHECK_ACTOR = "toolroll";
-/**
- * The sample project's check, set as part of making it, so its first result reads checked: the fixed command above,
- * recorded as Toolroll's (SAMPLE_CHECK_ACTOR), with the person who added the sample named in the ledger line. Only
- * for a sample this request just made (the caller passes createSampleProject's `created: true`; a folder found again
- * is never armed), only for the folder this made (our marker in its .git), and only while the project has never had
- * a check at all (no verify_command row, live or revoked, for it or its quick check): a check someone cleared stays
- * cleared, and one someone approved is never replaced. It takes no command: this is not a way to set a project's
- * check. True when it set one now.
- */
-export declare function registerSampleCheck(store: Pick<Store, "transact" | "handle" | "setVerifyCommand" | "recordAction">, made: {
-    path: string;
-    created: boolean;
-}, repo: string, addedBy: string, now: Date): boolean;

package/dist/sandbox-launch.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/sandbox-runtime.d.ts

@@ -1,128 +0,0 @@
-import type { FsReadRestrictionConfig, FsWriteRestrictionConfig } from "@anthropic-ai/sandbox-runtime";
-/** The engine and its exact version, as the console and the words say it. */
-export declare const SANDBOX_RUNTIME: {
-    name: string;
-    version: string;
-};
-/** "Anthropic's sandbox-runtime 0.0.79": how every surface names the engine. */
-export declare const sandboxRuntimeWords: () => string;
-/**
- * One launch's sandbox, as the runtime's own config: what it may not read (and the exact paths read again inside
- * those), where it may write (and what stays unwritable there), the extra macOS services it may look up, and its
- * network (open, or only through this run's proxy; a tool broker rides the runtime's second relay).
- */
-export type SrtTerms = {
-    readConfig: FsReadRestrictionConfig;
-    writeConfig: FsWriteRestrictionConfig;
-    allowMachLookup: string[];
-    /** macOS: the launch may reach the keychain's services (securityd). Only a build's agent: every other launch is
-     * denied them (SEATBELT_NO_KEYCHAIN). */
-    keychain?: boolean;
-    /** macOS: a project check's launch, whose Chromium may register and reach its own service (SEATBELT_CHROMIUM). */
-    browser?: boolean;
-    network: {
-        kind: "open";
-    } | {
-        kind: "proxy";
-        httpPort: number;
-        socksPort?: number;
-        token?: string;
-        localServices: boolean;
-        unixSockets: string[];
-    };
-};
-/** A deny-by-default profile, as the runtime's are: inside another sandbox one can't be applied (an allow-by-default one
- * still can, so it proves nothing). */
-export declare const SEATBELT_PROBE = "(version 1)(deny default)(allow process-exec)(allow process-fork)(allow file-read*)(allow sysctl-read)(allow mach-lookup)";
-/** Why the runtime can't sandbox here, or null when it can (checked before every launch; nothing runs bare). */
-export declare function sandboxRuntimeProblem(platform?: NodeJS.Platform): string | null;
-/** POSIX shell words. */
-export declare function shellQuote(words: readonly string[]): string;
-/**
- * The runtime sets a sandboxed command's TMPDIR itself (to $CLAUDE_CODE_TMPDIR of the process asking, or /tmp/claude):
- * the launch's own temp folder when it has one, so it keeps it; otherwise /tmp/claude, made if missing.
- */
-export declare function withRuntimeTemp<T>(temp: string | undefined, make: () => T): T;
-/**
- * Toolroll's own Seatbelt rules, appended to the end of the runtime's profile (Seatbelt takes the last rule that
- * matches). Static: constants here, never made from a launch's data.
- *
- * Terminals: a pseudo-terminal of the launch's own (node-pty, `script`, a test that drives a shell), and no other. The
- * runtime's `allowPty` opens reads and writes on every /dev/ttys device, the operator's own open terminals among them,
- * and its baseline already reads them (a read steals what is typed there). macOS marks a terminal the sandboxed process
- * made with the `com.apple.sandbox.pty` extension (for that terminal only: a device number used again later outside is
- * not covered), so only those are opened by name. A terminal handed down open (a live terminal's own) stays usable.
- */
-export declare const SEATBELT_PTY: string;
-/** Last in every profile: no other terminal opened by name, and no keystrokes pushed into any terminal (TIOCSTI,
- * _IOW('t', 114, char)), its own controlling terminal included. */
-export declare const SEATBELT_NO_OTHER_TERMINAL: string;
-/**
- * Last in every launch's profile but a build agent's: the keychain's services. The runtime's
- * baseline lets every sandboxed process ask securityd, so it reads the login keychain's items whose access list lets
- * any program read them (anthropics/sandbox-runtime#755). Build agents keep it (Claude Code signs in from the keychain).
- */
-export declare const SEATBELT_NO_KEYCHAIN: string;
-/**
- * First after the profile's default deny: a mach service lookup the profile doesn't allow is still denied, unreported.
- * On macOS 26.5 a reported mach-lookup denial now and then never answers: bootstrap_look_up blocks in launchd for good
- * (seen as npm stuck in Node's DNS setup, dns_configuration_copy → com.apple.SystemConfiguration.DNSConfiguration, about
- * 1 launch in 70 under load; never with the report off). Every allow after it still wins, so what is reachable is the
- * same; only the report goes.
- */
-export declare const SEATBELT_QUIET_MACH_DENY = "(deny mach-lookup (with no-report))";
-/**
- * Chromium, a project check's launch only: Playwright's default browser (its Chromium headless shell) registers its
- * port rendezvous service as org.chromium.Chromium.MachPortRendezvousServer.<its pid> at start, and its helpers look
- * it up. Exactly that name. Chromium takes the prefix from its bundle id with no switch or variable to change it, and
- * Seatbelt can't tie the pid to the caller, so the residual (another pid's name registered or looked up) is written
- * up in SECURITY.md. Chrome for Testing (`channel: "chromium"`, headed runs) gets nothing: such a check runs Not
- * sandboxed.
- */
-export declare const SEATBELT_CHROMIUM: string;
-/** Toolroll's rules for a launch's terms, in order: its own terminal (unless its read denies cover the devices), a
- * check's Chromium service, then the denies that must come last. */
-export declare function seatbeltRulesFor(terms: SrtTerms): string;
-/** The runtime's own quoting (its utils/shell-quote.js): a word bare when nothing in it is special, otherwise in single
- * quotes with a quote inside as '"'"'. */
-export declare function srtQuote(words: readonly string[]): string;
-/** The words of a line srtQuote made, or null for any other line (an operator, a second command, other quoting). */
-export declare function srtWords(line: string): string[] | null;
-/**
- * `command` (the runtime's macOS invocation) with `rules` appended to its profile, made again from its words. The
- * runtime's invocation is exactly `env [-u NAME]… [NAME=value]… /usr/bin/sandbox-exec -p <profile> <shell> -c
- * <command>`, each word quoted its way, and `<command>` is `expected` when given. Any other line (an operator, a word
- * before `env` or after the command, another program) is refused, so the launch doesn't run.
- */
-export declare function withSeatbeltRules(command: string, rules: string, expected?: string): string;
-/** The runtime's macOS invocation for `file args` run from `cwd`: a command line for /bin/sh. */
-export declare function srtMacosCommand(file: string, args: readonly string[], terms: SrtTerms, cwd?: string, temp?: string): string;
-/**
- * macOS: what every sandboxed launch runs first, outside the sandbox, before it execs the runtime's command: a session of
- * its own (setsid, syscall 147), so no terminal of whoever started Toolroll is its controlling terminal to reach. A
- * launch that is a session leader already (a live terminal's program, its own terminal made for it) keeps that one; any
- * other that still has a controlling terminal (getsid, syscall 310) is refused. Perl with -t reads neither PERL5OPT nor
- * PERL5LIB, and -X keeps its taint warnings off the launch's output.
- */
-export declare const DETACH: readonly string[];
-/** The Linux helper (sandbox-launch.ts) and the environment variable its launch is handed in. */
-export declare const SANDBOX_LAUNCH_SPEC = "TOOLROLL_SANDBOX_LAUNCH";
-export declare const sandboxLaunchHelper: () => string;
-/** What the Linux helper is given: the command, where it runs, and the terms. */
-export type SandboxLaunchSpec = {
-    file: string;
-    args: string[];
-    cwd: string;
-    terms: SrtTerms;
-    temp?: string;
-};
-/**
- * `file args` inside the runtime's sandbox, as a spawn: on macOS `/bin/sh -c <its command>` in a session of its own
- * (DETACH); on Linux the helper,
- * handed the launch in its environment (never its arguments, which other users can list).
- */
-export declare function srtSpawn(file: string, args: readonly string[], terms: SrtTerms, cwd?: string, temp?: string, platform?: NodeJS.Platform): {
-    file: string;
-    args: string[];
-    env: Record<string, string>;
-};

package/dist/scan.d.ts

@@ -1,32 +0,0 @@
-/**
- * Finding git repositories on disk.
- *
- * This is the first thing Toolroll does and the only thing it does before
- * the operator has configured anything, so it has to be fast, total, and
- * strictly read-only. It reads directory entries. It never opens a file, never
- * follows a symlink, and never descends into a repository it has found.
- */
-export type ScanOptions = {
-    /** Directory levels below each root to examine. A root itself is depth 0. */
-    maxDepth?: number;
-    /** Directory names never descended into. */
-    skip?: ReadonlySet<string>;
-    /** Dot-directories are skipped by default; worktrees come from git, not the walk. */
-    includeHidden?: boolean;
-};
-/**
- * Directories that hold other people's code, build output, or caches. Skipping
- * these is most of the difference between a scan that takes a second and one
- * that takes a minute — a single checkout's `node_modules` can hold thousands
- * of vendored repositories, none of which are yours.
- */
-export declare const DEFAULT_SKIP: ReadonlySet<string>;
-export declare const DEFAULT_MAX_DEPTH = 6;
-/**
- * Every repository at or below `roots`, sorted and deduplicated.
- *
- * Unreadable directories are skipped rather than raised: a scan of a home
- * directory will always meet something it cannot open, and that must not be
- * the reason the operator sees nothing.
- */
-export declare function findRepos(roots: readonly string[], options?: ScanOptions): Promise<string[]>;