toolroll 0.9.62 → 0.9.63

package/CHANGELOG.md

@@ -1,5 +1,34 @@
 # Changelog
 
+## 0.9.63 — 2026-10-13
+
+- **Scheduled flows run on their own.** Sign a flow once with limits
+  (runs a day, budget, end date); its on-time firings build without a
+  person, and the script it runs is checked again when it fires.
+- **Secrets in the OS keychain.** Tool keys, the Linear key, Google mail and
+  flow secrets move into the macOS Keychain or Linux Secret Service, never
+  argv or the database. OAuth tools give each run a short-lived token, never
+  the refresh token. Settings shows how each tool's runs get credentials.
+- **Builds stay in their own checkout.** A build can't read or write another
+  project's or another task's checkout, and a checkout swapped for a link
+  is refused at the next launch.
+- **Safer cleanup.** Removing finished checkouts runs git with hooks,
+  filters and nested-repo config switched off.
+- **Attack suite.** Every bypass found in review is a permanent test, run by
+  the Quick check whenever sandbox or secrets code changes.
+- **Tool secrets stay outside the build.** A broker outside the sandbox
+  holds them. Codex refuses tools that carry secrets. Shared dependencies and
+  `git gc` work inside the fence.
+- **Tighter sandbox.** Builds can no longer rename folders above protected
+  paths or inspect other processes' memory; tool servers get only the
+  environment they need.
+- **Tools with secrets need the macOS sandbox.** A build without it, and
+  every build on Linux, leaves those tools out and says why.
+- **`toolroll doctor`.** Checks that Toolroll's service holds no key a build
+  could read, and lists the steps to fix it. It reads only.
+- **Research tools answer every refusal**, even when the service accepts the
+  rest with an empty reply.
+
 ## 0.9.62 — 2026-10-12
 
 - **Release checks in minutes.** The upgrade path runs on a sample, CI's

package/README.md

@@ -409,7 +409,7 @@ do not loosen when you leave the room:
 | touch a default branch | builds land on `toolroll/<task>` in a leased worktree; push + PR happen only under a publication grant naming the exact repo, branch prefix, and base |
 | approve its own work | approval nonces are minted only on screens that restate the digest-bound terms, and require your approver token typed again — **no LLM sits in any approval path** — and the [agent fence](#what-an-agent-can-reach) keeps your remembered login, runner tokens and the database out of the agent's reach |
 | act on an irreversible option | `reversible` is a schema field; irreversible choices never auto-apply, and answering one from a phone takes a second minted confirmation tap |
-| see Toolroll's secrets | the [agent fence](#what-an-agent-can-reach) blocks your login, runner and bot tokens, stored provider keys and project tool secrets at the operating system; other providers' keys are stripped from each agent's environment; secrets live in 0600 files, never in the database, URLs, or logs |
+| see Toolroll's secrets | the [agent fence](#what-an-agent-can-reach) blocks your login, runner and bot tokens, stored provider keys and project tool secrets at the operating system; other providers' keys are stripped from each agent's environment; tool secrets rest sealed in the OS keychain ([how](#how-build-sessions-are-protected)) and other secrets in 0600 files, never in the database, URLs, or logs |
 | spend while idle | **an LLM never polls** — the daemon does every no-judgement chore at zero token cost and wakes an agent only on a real event |
 | spend without being counted | every provider spawn is stamped *before* it spends, so cost is measured, never asserted |
 | guess at a judgement call | it parks a typed decision — recap, options with reversibility, recommendation, evidence — and the other eleven tasks keep going |
@@ -572,6 +572,13 @@ runner and coordinator tokens, chat bot tokens, the database and its backups,
 other runs' evidence) — everything there except the build's own worktree —
 and `~/.toolroll` (stored provider keys and project tool secrets).
 
+Seatbelt and bubblewrap deny the whole checkout pool and allow the build’s own
+checkout back, covering other projects created after launch too. Codex keeps
+the own checkout’s ancestors traversable and denies each other project folder
+found in trusted checkout pools at launch. A project added after a Codex build
+starts is covered on the next launch. Own Git data, linked shared dependencies
+and launch tools remain available.
+
 | | Auto | Full access |
 |---|---|---|
 | **Codex / OpenRouter** (any OS) | Codex's workspace sandbox (workspace writes, no network) with the fence | Codex's sandbox widened to write anywhere with network, with the fence |
@@ -581,8 +588,49 @@ and `~/.toolroll` (stored provider keys and project tool secrets).
 Each attempt records how it was fenced. Two limits to know: in **API-key
 mode** an agent's own provider key is in its environment, so its shell can
 read it (subscription mode, the default, puts no key there); and a project's
-own tool secrets reach that project's tools. Reviews and the lead chat run
-with no tools and are confined to their own files. See [SECURITY.md](SECURITY.md).
+own tool secrets reach that project's tools. They stay in a per-run broker
+outside the fence: the agent gets only its address and a token that stops
+working when the run ends, and on macOS it can't read another process's
+arguments or environment. Reviews and the lead chat run with no tools and are
+confined to their own files. See [SECURITY.md](SECURITY.md).
+
+### How build sessions are protected
+
+A build runs as your own user, so Toolroll keeps the secrets it holds (tool
+keys and sign-ins, the Linear key, a Google mail connection, flow webhook
+secrets) away from it in layers:
+
+- **The fence.** The operating system denies the build Toolroll's own
+  folders, your home configuration and other projects (the table above).
+- **The broker.** A run's tools are served by a broker in Toolroll's own
+  process, outside the fence. The agent gets only the broker's local address
+  and a key for that run, which stops working when the run ends. Another
+  run's key opens nothing.
+- **The keychain.** At rest, secrets are in the macOS Keychain (through
+  `security`, with the value on its input) or the Linux Secret Service (the
+  system's `secret-tool`, value on its input). A fenced build can still ask
+  the keychain for an item, so each is sealed with a key in `tool-secrets`
+  beside Toolroll's database. Toolroll makes that folder when it starts,
+  before any build, and records which key it made; a folder, key or link put
+  there by anything else is refused. What a build reads is ciphertext.
+  Secrets are read only when a run starts. Files from before move into the
+  keychain the first time they are used, and the plaintext copy is removed.
+  Where there is no keychain, or the keyring doesn't answer, secrets stay in
+  owner-only files, and Settings and `toolroll integrations` say so.
+- **Short-lived tokens.** A service connected by signing in gives each run
+  a fresh access token of its own, made outside the fence when the run starts
+  and limited to read access for research steps where the service allows.
+  The refresh token never leaves Toolroll, and one renewal runs at a time
+  across Toolroll's processes. If a renewed sign-in can't be saved, the run
+  doesn't start and every token made for it is revoked. The run's token is
+  revoked when the run ends, or runs out on its own where the service has no
+  way to revoke it. Keys you paste in stay in the broker. Settings → Tools
+  shows which each tool uses.
+
+What remains: any program of yours running outside the fence (not started by
+a build) can read what you can, including Toolroll's folder and the keychain.
+Toolroll protects your secrets from its builds, not from other software you
+run.
 
 Every new-task and task-scope form has the same two-choice control. A task's
 choice is durable through planning rewrites and is sealed into the approved

package/dist/agent-fence.d.ts

@@ -1,5 +1,15 @@
 /** How a launch was fenced, as recorded on the run and said on the task. */
 export type FenceMethod = "codex-profile" | "macos-sandbox" | "linux-bubblewrap" | "claude-rules" | "none";
+/** Only the plane's recorded repository may supply an own-Git exemption. */
+export type WorktreeBinding = {
+    main: string;
+    gitdir: string;
+};
+export declare class CheckoutBindingError extends Error {
+}
+export declare const HARDENED_GIT_ARGS: readonly ["--no-optional-locks", "-c", "core.fsmonitor=false", "-c", "core.hooksPath=/dev/null"];
+export declare function checkoutGitEnv(base?: Readonly<NodeJS.ProcessEnv>): Record<string, string>;
+export declare function trustedWorktreeBinding(repository: string, worktree: string, poolRoots?: readonly (string | null)[]): WorktreeBinding;
 /**
  * Every path an agent must not reach: the Toolroll state folder
  * beside the database (all of it, except the folder that holds this run's
@@ -14,11 +24,17 @@ export declare function agentFence(options: {
     home?: string;
     extra?: readonly string[];
     boundary?: TaskBoundary | null;
+    binding?: WorktreeBinding | null;
+    runFolders?: RunFolders;
 }): string[];
-/** The task's boundary: `shell` joins the OS fence; `fileTools` only Claude's file-tool deny rules. */
+/** The task's boundary: `shell` joins the OS fence; `fileTools` only Claude's file-tool deny rules; `readOnly` and
+ * `lookup` are other tasks' git metadata and checkout roots (see FenceGrants). */
 export type TaskBoundary = {
+    protectedShell?: string[];
     shell: string[];
     fileTools: string[];
+    readOnly: string[];
+    lookup: string[];
 };
 /**
  * Everything outside a task's own folders that a build could otherwise
@@ -32,19 +48,145 @@ export declare function taskBoundary(options: {
     worktree: string;
     provider: string;
     home?: string;
+    binding?: WorktreeBinding | null;
 }): TaskBoundary;
+/** Where launches keep their private folders (the system temp folder), and this launch's own tool folder. */
+export type RunFolders = {
+    root: string;
+    own: string | null;
+};
+/** The prefixes of every launch's private folders: its tools' config and a Codex build's own home. */
+export declare const RUN_FOLDER_PREFIXES: readonly ["so-tools-", "so-codex-"];
+export declare function runFolders(own: string | null, root?: string): RunFolders;
+/**
+ * What a fence gives back beside its denied paths. Each is narrow and none
+ * ever writes: `readOnly` is read, never written (other tasks' git
+ * metadata); `readable` is read and run inside a denied folder (the shared
+ * dependencies this checkout links); `lookup` is only looked up, never
+ * listed or read (the deps root and the copy linked, other tasks' checkout
+ * roots); `runFolders` denies every launch folder in the temp folder but
+ * this launch's own (macOS: by pattern, so a later one is denied too);
+ * `pool` denies the plane's checkout pools whole and gives this build's own
+ * checkout back (CheckoutPool).
+ */
+export type FenceGrants = {
+    readOnly: string[];
+    readable: string[];
+    lookup: string[];
+    runFolders?: RunFolders;
+    pool?: CheckoutPool;
+};
+export declare const NO_GRANTS: FenceGrants;
+/**
+ * The plane's checkout pools, denied whole: every project's worktrees, and any made there after launch. `agentFence`
+ * drops a path at or above the checkout, so the deny lives here and each sandbox gives back, right after it, only
+ * `own` (this build's checkout, read and written) and `lookup` (the folders between, looked up, never listed).
+ */
+export type CheckoutPool = {
+    deny: string[];
+    own: string | null;
+    lookup: string[];
+    gitPaths?: string[];
+};
+/**
+ * The pool deny for one launch. `roots` come from the plane's own records (the pool beside the database, and the one
+ * the recorded checkout was made in), never from the checkout. A root that holds this checkout's own Git data (the
+ * binding's gitdir or the repository's .git) is never denied whole: it is split around that data instead, entry by
+ * entry, so it is denied as far as it can be (fail closed by denying more, never by refusing). A root inside the
+ * checkout, the home folder, a folder above it or / is left alone: the first is the build's own work, the others the
+ * whole machine.
+ */
+export declare function checkoutPool(options: {
+    roots: readonly (string | null)[];
+    worktree: string | null;
+    binding?: WorktreeBinding | null;
+    home?: string;
+}, list?: (path: string) => string[]): CheckoutPool;
+/** The grants for one build: its task boundary's git rules, the shared dependencies its checkout links, and the
+ * checkout pools (`poolRoots`, from the plane's records) denied around its own checkout. */
+export declare function fenceGrants(options: {
+    databaseFile: string | null;
+    worktree: string | null;
+    boundary?: TaskBoundary | null;
+    runFolders?: RunFolders;
+    linked?: {
+        repo: string;
+        setupDigest: string | null;
+    } | null;
+    poolRoots?: readonly (string | null)[];
+    binding?: WorktreeBinding | null;
+    home?: string;
+}): FenceGrants;
+/**
+ * Git settings every fenced build runs with (GIT_CONFIG_COUNT, after any the
+ * caller already set): `git gc` never expires a reflog, so it never rewrites
+ * another task's reflog, which the fence would refuse mid-collection.
+ */
+export declare function fencedGitEnv(base?: Readonly<Record<string, string | undefined>>): Record<string, string>;
 /**
  * Codex's own sandbox, fenced. Auto: the `:workspace` profile Codex's
  * `--sandbox workspace-write` already gives (workspace and temp writes, no
  * network). Full access: the same profile widened to write anywhere with
  * network on, instead of no sandbox at all. Either way the fenced paths are
- * denied, which in Codex outranks any write or read grant.
+ * denied, which in Codex outranks any write or read grant. The checkout pools
+ * are never `flattened` (which leaves what is made after launch readable): see
+ * `codexPool`, which denies them around the build's own checkout, written back.
+ */
+export declare function codexFenceArgv(fence: readonly string[], fullAccess: boolean, grants?: FenceGrants): string[];
+/**
+ * Codex cannot deny an ancestor and still traverse it to the own checkout. Deny existing
+ * siblings individually, from the trusted pool roots and a fresh listing, never through
+ * flattened or name patterns. A project added after launch is covered on the next launch;
+ * Seatbelt and bubblewrap retain the stronger whole-pool rule for later-created projects.
+ */
+export declare function codexPool(pool: CheckoutPool, list?: (path: string) => string[]): {
+    read: string[];
+    deny: string[];
+    write: string[];
+};
+/** Secret-looking names denied by pattern inside a folder `flattened` makes read-only, so one written there after
+ * launch is denied too (the database and its journals, tokens, login and other text files). */
+export declare const SPLIT_SECRET_PATTERNS: readonly ["orders.db*", "*token*", "up-login*", "*.txt", "*secret*", "*password*", "*credential*", "*.pem", "*.key"];
+/**
+ * A fence as plain denied and read-only paths, for a sandbox that can't
+ * grant inside a denied folder (Codex: a deny outranks any grant): a denied
+ * folder holding something readable becomes read-only, with each of its
+ * entries not on the way to what is readable denied instead. Fails closed: a
+ * folder that can't be listed stays denied whole and its grant is dropped.
+ * Residual: an entry made after launch in a read-only folder is denied only
+ * when its name matches SPLIT_SECRET_PATTERNS; any other new entry there is
+ * readable (never writable) until the next launch. The macOS fence has no
+ * such gap: it denies the folder and grants back only the readable path.
+ */
+export declare function flattened(fence: readonly string[], grants?: FenceGrants, list?: (path: string) => string[]): {
+    deny: string[];
+    readOnly: string[];
+};
+/** Claude's own file tools refuse the fenced paths in every mode (its shell is fenced by the macOS sandbox), and
+ * never edit a read-only one. */
+export declare function claudeFenceSettings(fence: readonly string[], readOnly?: readonly string[]): string;
+/**
+ * The folders the user owns above each path (never `/`, nor the path itself), and each `roots` folder itself when the
+ * user owns it. A Seatbelt path rule follows the name, not the folder: renaming one of these would bring a fenced path
+ * back under a name no rule mentions. A folder the user doesn't own can't be renamed by a build anyway.
+ */
+export declare function ownedAncestors(paths: readonly string[], roots?: readonly string[], uid?: number | undefined): string[];
+/**
+ * A Seatbelt profile that allows everything except reading or writing the
+ * fenced paths, less what `grants` gives back (a later Seatbelt rule
+ * outranks an earlier one). Whatever the paths, the process can't read
+ * another's arguments and environment (`kern.procargs`, which `ps -E` and
+ * KERN_PROCARGS2 use) or inspect a process outside its own sandbox:
+ * `process-info*` limited by target alone doesn't stop the sysctl. It can't
+ * take another process's task port either (`task_for_pid`, what lldb attaches
+ * with; a task name port too), so a tool server's or Toolroll's own memory
+ * and environment stay out of reach. Last, every folder of the user's above
+ * a fenced or read-only path and above the temp folder (and the temp folder
+ * itself) can't be renamed or removed, though what is inside them stays
+ * writable as before. The checkout pools are denied first, and the build's own
+ * checkout given back right after, so every later deny still holds inside it.
  */
-export declare function codexFenceArgv(fence: readonly string[], fullAccess: boolean): string[];
-/** Claude's own file tools refuse the fenced paths in every mode (its shell is fenced by the macOS sandbox). */
-export declare function claudeFenceSettings(fence: readonly string[]): string;
-/** A Seatbelt profile that allows everything except reading or writing the fenced paths. */
-export declare function macosFenceProfile(fence: readonly string[]): string;
+export declare function macosFenceProfile(fence: readonly string[], grants?: FenceGrants): string;
 export declare const SANDBOX_EXEC = "/usr/bin/sandbox-exec";
 /**
  * Whether this machine can run an agent inside the macOS fence (checked once). Not from inside another
@@ -58,13 +200,16 @@ export declare function macosFenceAvailable(platform?: NodeJS.Platform, probe?:
     stderr: string;
 }): boolean;
 /** The spawn that runs `file args` inside the macOS fence (same process: sandbox-exec replaces itself with the agent). */
-export declare function macosFenced(file: string, args: readonly string[], fence: readonly string[]): {
+export declare function macosFenced(file: string, args: readonly string[], fence: readonly string[], grants?: FenceGrants): {
     file: string;
     args: string[];
 };
 export declare function linuxFenceAvailable(platform?: NodeJS.Platform, probe?: () => boolean): boolean;
-/** The spawn that runs `file args` inside the Linux fence: the whole filesystem as it is, except each fenced path masked. */
-export declare function linuxFenced(file: string, args: readonly string[], fence: readonly string[]): {
+/** The spawn that runs `file args` inside the Linux fence: the whole filesystem as it is, the checkout pools masked
+ * and the build's own checkout bound back read-write over them, then every fenced path masked whole (an empty
+ * folder, or /dev/null for a file), so what is made there after launch is masked too; then only the explicit grants
+ * bound back read-only (bubblewrap binds from the original root, so a grant inside a mask still reaches its files). */
+export declare function linuxFenced(file: string, args: readonly string[], fence: readonly string[], grants?: FenceGrants): {
     file: string;
     args: string[];
 };