@tonoid/agent-loop 1.0.0 → 1.1.0

package/README.md

@@ -1,4 +1,4 @@
-# agent-loop
+# agent-loop: run coding agents on a schedule, across accounts, unattended
 
 Runs autonomous coding agents against your repositories on a schedule,
 unattended, across several provider accounts, without exhausting any of them
@@ -13,62 +13,77 @@ anywhere to run. If you are looking for something that shells out to an agent
 binary and waits on an exit code, this is not it, and [the section
 below](#how-it-uses-herdr) is the fastest way to find that out.
 
-Built against **herdr 0.8.0, protocol 19**.
+Built against **herdr 0.9.0, protocol 22**.
 
-## How it uses herdr
+[![npm](https://img.shields.io/npm/v/@tonoid/agent-loop?logo=npm)](https://www.npmjs.com/package/@tonoid/agent-loop)
+[![License MIT](https://img.shields.io/badge/License-MIT-green.svg)](./LICENSE)
+[![CI](https://github.com/tonoid/agent-loop/actions/workflows/ci.yml/badge.svg)](https://github.com/tonoid/agent-loop/actions/workflows/ci.yml)
 
-A tick decides what ought to be running. Everything it then does to a worker,
-it does through the `herdr` CLI:
+**Who it's for**: anyone already running coding agents by hand who wants them
+to run overnight instead, across more than one provider account, without a
+human deciding which account and without waking up to an exhausted quota.
 
-| What the loop needs | herdr call |
-|---|---|
-| the workspace a job's tabs belong in | `workspace list`, matched on the `herdrWorkspace` label |
-| a worker | `tab create --workspace <id> --cwd <worktree> --label <job>-<key> --env <VAR>=<account config dir> --no-focus` |
-| the pane that tab just opened | `pane list`, matched on cwd |
-| the agent itself | `agent start <name> --kind <provider> --pane <id> -- <account startArgs>` |
-| the brief delivered | `agent prompt <pane> <brief> --wait --until working` |
-| whether they are alive | `agent list` for the whole fleet, `agent get <pane>` for one |
-| why it is stuck | `agent read <pane> --source recent-unwrapped --lines <n>` |
-| a composer holding unsent text | `agent send-keys <pane> Enter` |
-| the worker gone | `tab close <tab>` |
-| you, when a worker is blocked | `notification show <title> --body <text>` |
-| a supported herdr | `api schema --json` for the protocol number |
+**Keywords**: unattended Claude Code, autonomous coding agent scheduler, run
+Claude Code on cron, multiple Claude accounts, agent orchestration, git
+worktree per agent, GitHub issue to pull request automation, AI code review
+bot, quota-aware agent router, self-hosted agent runner, herdr.
 
-Three consequences worth knowing before you read the code, because each one
-shaped it:
+> ⚠️ **Disclaimer**: the code in this project was generated with
+> [Claude Code](https://claude.com/claude-code) (Anthropic), then **tested and
+> reviewed manually** by a human. It is provided as is, without warranty.
+> Before pointing it at a repository you care about: read the Safety and
+> Limitations sections below in full, give it its own provider account, and run
+> it without `--live` first, which performs every read and refuses every write.
+> A loop you have never watched dry-run is a loop you do not know. Issues and
+> PRs welcome.
 
-**`agent_status` is the whole lifecycle.** A worker has no exit code and no pid
-here. `working`, `blocked` and `idle` are the only states the loop can observe,
-and every decision the monitor makes is built from one of those, the pane still
-being listed, and the worktree still being on disk. `blocked` notifies you once
-and then escalates on a timer; an agent that has vanished while its pane is
-still up is restarted exactly once, and one whose pane went with it has failed.
-A status herdr does not recognise becomes `missing`, which deliberately does
-nothing at all: holding cannot kill a live agent or tombstone an item, so a
-herdr that adds or renames a state stalls this loop rather than damaging
-anything with it.
+```
+$ agent-loop status
+
+loop: session 1.0% resets in 275m, weekly_all 46.0% resets in 4235m, weekly_scoped 14.0% resets in 4235m
+loop: refresh token expires in 25d
+main: session 8.0% resets in 175m, weekly_all 95.0% resets in 4475m, weekly_scoped 29.0% resets in 4475m
+main: refresh token expires in 13d
+spawns today: 3
+acme: paused nothing
+```
 
-**`tab create` is the only verb that accepts `--env`.** That single flag is the
-entire channel by which the router's account choice reaches a worker, which is
-why the account is decided before the tab exists and can never be changed
-after. It is also why `configEnv` is an account-level setting: `CLAUDE_CONFIG_DIR`
-for Claude Code, `CODEX_HOME` for Codex.
+A tick is one pass over every workspace. This is the whole operator view, and
+what cron writes to the log every two minutes:
 
-**herdr ids are not stable.** A pane id changes between rounds of the same
-logical worker, and a workspace id lasts until the herdr server restarts and
-then names somebody else's workspace. Nothing here caches one: the workspace is
-looked up by label and the pane by cwd, on every single spawn.
+```
+$ agent-loop tick --live
+
+SPAWN build b412 on loop (session 13.0% of 90.0 with 156m left -> 1 workers, 0 in flight)
+BUSY digest 20260820-0610 (agent working)
+HOLD review r408 (blocked 12m < 180m)
+DONE digest 20260820-0610 (done() true)
+SWEEP build /home/u/projects/acme/wt-build-b397 (done(b397))
+IDLE review
+TICK acme 2949ms
+TICK total 2987ms
+```
 
-Six of those verbs are reads: `workspace list`, `pane list`, `agent list`,
-`agent get`, `agent read` and `api schema`. Every other one is a write. Without
-`--live` the gate in `src/adapters/run.ts` permits exactly those six and refuses
-the rest by name, so a dry tick can survey your entire fleet and is incapable of
-touching it.
+Without `--live` every one of those verbs reads `WOULD spawn`, `WOULD sweep`,
+and nothing is written: the gate in `src/adapters/run.ts` refuses any command
+outside the read allowlist.
 
-`agent-loop check` compares your herdr's protocol number against the one this
-was tested on and warns when they differ. It never refuses to run on a
-mismatch: a newer herdr is usually fine, and a loop that stops dead at 2am
-because a dependency was upgraded is worse than one that says so and carries on.
+## Install
+
+```
+npm i -g @tonoid/agent-loop
+agent-loop kinds     # prints the job kinds: enough to prove the install
+```
+
+npm is the delivery mechanism, not the runtime. The package ships its
+TypeScript sources rather than a bundle, nothing is compiled at install time,
+and there are no runtime dependencies to fetch: the tarball is the `src/` tree,
+the `briefs/` the engine reads at spawn time, and the docs. The CLI's shebang is
+`#!/usr/bin/env bun`, so **bun has to be on the PATH of whoever runs it**. On a
+box without bun the install succeeds and the first run fails with
+`env: bun: No such file or directory`.
+
+To run a checkout as the real command instead, see [Development](#development).
 
 ## Prerequisites
 
@@ -89,33 +104,23 @@ because a dependency was upgraded is worse than one that says so and carries on.
   base is enough and each new worktree needs nothing. `agent-loop check`
   warns for any account missing it.
 
-Two things to know before running it. Workers start with permission prompts
-disabled, which is what makes them autonomous and also means they run
-unsandboxed as you. And all state lives under `~/.agent-loop/`, whatever else
-is on the box.
-
-## Install
+## Commands
 
 ```
-npm i -g @tonoid/agent-loop
-agent-loop kinds     # prints the job kinds: enough to prove the install
+agent-loop tick [--workspace <name>] [--live]   one pass over every workspace
+agent-loop check [<workspace folder>]           validate config and jobs
+agent-loop kinds [<kind>] [--json]              a kind's options, or its schema
+agent-loop status [--workspace <name>]          accounts, quota, paused jobs
+agent-loop pause|resume [<job>] --workspace <n> stop spawning; sweep and
+                                                monitor keep running
+agent-loop adopt <job> [<key>] --workspace <n>  record a spawned mark without
+                                                spawning: the cutover's import
+agent-loop adopt --list --workspace <n>         this workspace's marks
 ```
 
-npm is the delivery mechanism, not the runtime. The package ships its
-TypeScript sources rather than a bundle, nothing is compiled at install time,
-and there are no runtime dependencies to fetch: the tarball is the `src/` tree,
-the `briefs/` the engine reads at spawn time, and the docs. The CLI's shebang is
-`#!/usr/bin/env bun`, so **bun has to be on the PATH of whoever runs it**. On a
-box without bun the install succeeds and the first run fails with
-`env: bun: No such file or directory`.
-
-From a checkout instead, which is what you want if you are editing it:
-
-```
-bun install
-bun link          # puts agent-loop in ~/.bun/bin
-agent-loop kinds
-```
+`agent-loop check .` needs no `~/.agent-loop/config.yml`, so a service
+repository can run it in its own CI and catch a broken `job.yml` at the commit
+that broke it.
 
 ## Configure
 
@@ -220,6 +225,8 @@ label until somebody notices.
 kind: routine
 repo: web
 order: 5
+ignoresSpawnCap: true     # a scheduled slot is not what the cap is aimed at
+ignoresReserve: true      # ...and neither is the reserve, when the slot is the work
 brief: { extends: default/routine, append: ./brief.md }
 options:
   at: ["09:10", "21:10"]
@@ -227,6 +234,26 @@ options:
   doneWhen: ~/reports/{{key}}.md   # the artifact that ends the occurrence
 ```
 
+`ignoresSpawnCap` exempts a job from `maxSpawnsPerDay`, the box-wide runaway
+breaker. Set it on the jobs that spawn a handful of times a day on a schedule:
+the cap is sized for whichever workspace on the box actually loops, and when
+one of those spends the day's budget in an hour, a routine that shares the box
+misses its slot for something it has nothing to do with. Exempt spawns are
+still counted, so they show in the day's total and shorten what the capped jobs
+have left. The account's own `reserve`, `usageMax` and `maxConcurrent` still
+pace an exempt job.
+
+`ignoresReserve` is the same argument one layer down. The account `reserve` and
+`usageMax` pace the loop by making it wait for a window to roll, which is the
+right answer for a queue and the wrong one for a clock: a scheduled occurrence
+that waits long enough is not delayed, it is cancelled. On this box a digest job
+was starved on 2263 consecutive ticks across five days, 19 mailings that never
+went out while the loop ticked normally and logged the refusal every two
+minutes. A job with this set spends the reserve rather than skip, and only when
+no account has headroom at all, so the reserve still holds whenever the pacing
+model has any room to give. The account's own worker ceiling still applies:
+running two workers where one fits is a memory decision, not a quota one.
+
 Give a routine a `doneWhen` whenever its run produces one. Without it the only
 signal a routine has is its worktree disappearing, and that waits for the next
 slot: a run that finished at 09:38 is nudged at 09:40 and failed at 09:42 for
@@ -289,6 +316,61 @@ interval against.
 Moving existing cron-driven pipelines onto this loop has an order that keeps
 every step reversible: `docs/cutover.md`.
 
+## How it uses herdr
+
+A tick decides what ought to be running. Everything it then does to a worker,
+it does through the `herdr` CLI:
+
+| What the loop needs | herdr call |
+|---|---|
+| the workspace a job's tabs belong in | `workspace list`, matched on the `herdrWorkspace` label |
+| a worker | `tab create --workspace <id> --cwd <worktree> --label <job>-<key> --env <VAR>=<account config dir> --no-focus` |
+| the pane that tab just opened | `pane list`, matched on cwd |
+| the agent itself | `agent start <name> --kind <provider> --pane <id> -- <account startArgs>` |
+| the brief delivered | `agent prompt <pane> <brief> --wait --until working` |
+| whether they are alive | `agent list` for the whole fleet, `agent get <pane>` for one |
+| why it is stuck | `agent read <pane> --source recent-unwrapped --lines <n>` |
+| a composer holding unsent text | `agent send-keys <pane> Enter` |
+| the worker gone | `tab close <tab>` |
+| you, when a worker is blocked | `notification show <title> --body <text>` |
+| a supported herdr | `api schema --json` for the protocol number |
+
+Three consequences worth knowing before you read the code, because each one
+shaped it:
+
+**`agent_status` is the whole lifecycle.** A worker has no exit code and no pid
+here. `working`, `blocked` and `idle` are the only states the loop can observe,
+and every decision the monitor makes is built from one of those, the pane still
+being listed, and the worktree still being on disk. `blocked` notifies you once
+and then escalates on a timer; an agent that has vanished while its pane is
+still up is restarted exactly once, and one whose pane went with it has failed.
+A status herdr does not recognise becomes `missing`, which deliberately does
+nothing at all: holding cannot kill a live agent or tombstone an item, so a
+herdr that adds or renames a state stalls this loop rather than damaging
+anything with it.
+
+**`tab create` is the only verb that accepts `--env`.** That single flag is the
+entire channel by which the router's account choice reaches a worker, which is
+why the account is decided before the tab exists and can never be changed
+after. It is also why `configEnv` is an account-level setting: `CLAUDE_CONFIG_DIR`
+for Claude Code, `CODEX_HOME` for Codex.
+
+**herdr ids are not stable.** A pane id changes between rounds of the same
+logical worker, and a workspace id lasts until the herdr server restarts and
+then names somebody else's workspace. Nothing here caches one: the workspace is
+looked up by label and the pane by cwd, on every single spawn.
+
+Six of those verbs are reads: `workspace list`, `pane list`, `agent list`,
+`agent get`, `agent read` and `api schema`. Every other one is a write. Without
+`--live` the gate in `src/adapters/run.ts` permits exactly those six and refuses
+the rest by name, so a dry tick can survey your entire fleet and is incapable of
+touching it.
+
+`agent-loop check` compares your herdr's protocol number against the one this
+was tested on and warns when they differ. It never refuses to run on a
+mismatch: a newer herdr is usually fine, and a loop that stops dead at 2am
+because a dependency was upgraded is worse than one that says so and carries on.
+
 ## Workers
 
 A worker starts in the account's own config directory, so it inherits whatever
@@ -315,23 +397,23 @@ answer, the loop sends a `herdr` notification, once per item rather than once
 per tick, and only under `--live`. It is the only thing the loop will interrupt
 you for, which is what makes it worth reading.
 
-## Commands
-
-```
-agent-loop tick [--workspace <name>] [--live]   one pass over every workspace
-agent-loop check [<workspace folder>]           validate config and jobs
-agent-loop kinds [<kind>] [--json]              a kind's options, or its schema
-agent-loop status [--workspace <name>]          accounts, quota, paused jobs
-agent-loop pause|resume [<job>] --workspace <n> stop spawning; sweep and
-                                                monitor keep running
-agent-loop adopt <job> [<key>] --workspace <n>  record a spawned mark without
-                                                spawning: the cutover's import
-agent-loop adopt --list --workspace <n>         this workspace's marks
-```
-
-`agent-loop check .` needs no `~/.agent-loop/config.yml`, so a service
-repository can run it in its own CI and catch a broken `job.yml` at the commit
-that broke it.
+## Limitations
+
+- GitHub only. Labels are the state machine and every read goes through `gh`,
+  so there is no GitLab, Gitea or Forgejo support and adding one is not a small
+  change.
+- Workers run unsandboxed as you, with permission prompts disabled. That is
+  what makes them autonomous. Give the loop its own account and its own
+  worktree base, and read `briefs/default/core.md`, which is the contract every
+  worker works under.
+- One box. State lives in `~/.agent-loop/`, the daily spawn cap and the
+  in-flight count are per machine, and two machines sharing one provider
+  account do not know about each other.
+- The `grok` provider is wired but unverified: set `configEnv` on the account
+  before routing real work to it. `claude` and `codex` are the tested ones.
+- The herdr protocol is pinned to one tested number. A newer herdr warns and
+  runs; a herdr that renames `agent_status` stalls the monitor rather than
+  breaking it.
 
 ## Reading the source
 
@@ -341,38 +423,114 @@ in the repository. The numbers are stable and nothing in the code needs it: the
 README and `agent-loop kinds` are the current reference, and every rule the
 spec states is enforced by a test that names it.
 
-## Maintenance
+## Development
 
 ```
-bun test            # the whole suite: no network, no gh, no herdr
-bun run typecheck
-bun run test:live   # opts in to a real herdr, which has to be running
+git clone https://github.com/tonoid/agent-loop
+cd agent-loop
+bun install
+bun test
+```
+
+The suite is hermetic: no network, no `gh`, no herdr, no writes outside a
+temporary directory. `bun run test:live` opts in to a real herdr and is skipped
+unless `AGENT_LOOP_LIVE_HERDR=1`. CI runs `bun run typecheck` and `bun test` on
+every push and pull request.
+
+To run the checkout as the real command, so `git pull` updates the loop:
+
+```
+bun link          # puts agent-loop in ~/.bun/bin
 ```
 
-The suite is hermetic apart from `test:live`, which is skipped unless
-`AGENT_LOOP_LIVE_HERDR=1`. CI runs the typecheck and the suite on every push and
-pull request.
+That is worth knowing before you edit anything: with the checkout linked, cron
+runs your working tree, so an unfinished edit is live within one tick.
+
+## Releasing
 
-Releases are driven by the commit messages. Conventional commits landing on
-`main` are read by [release-please](https://github.com/googleapis/release-please),
-which keeps a pull request open carrying the next version and the changelog
-entry. Merging it tags the commit, cuts the GitHub release, and publishes to
-npm with provenance. Nothing else is manual, and the only secret involved is
-`NPM_TOKEN` in the repository's Actions secrets. So `feat:` and `fix:` prefixes
-are load-bearing: a commit without one ships no release and appears in no
-changelog.
+Versions come from the commit messages, so land work on `main` with
+[conventional commits](https://www.conventionalcommits.org):
 
-Publishing works despite this being a bun project because bun is never involved
-in it. `npm publish` uploads the sources as they are, and the tests that run
-before it are the only step that needs bun. What the version number promises is
-therefore the source in `src/`, not a build of it.
+| Prefix | Effect |
+|---|---|
+| `fix: ...` | patch, 1.0.0 to 1.0.1 |
+| `feat: ...` | minor, 1.0.0 to 1.1.0 |
+| `feat!: ...` or a `BREAKING CHANGE:` footer | major, 1.0.0 to 2.0.0 |
+| `docs:`, `chore:`, `test:`, `refactor:` | no release |
+
+The `release` workflow runs release-please on every push to `main`. It keeps a
+single release PR open ("chore(main): release X.Y.Z") holding the version bump
+and the new `CHANGELOG.md` section. Nothing publishes while that PR sits there.
+Merging it tags `vX.Y.Z`, cuts the GitHub release, and triggers the publish job,
+which runs the typecheck and the suite and then `npm publish` with the
+`NPM_TOKEN` repository secret.
+
+`.release-please-manifest.json` is the source of truth for what ships next, so
+let release-please edit it rather than bumping `package.json` by hand.
+
+Published releases carry npm [provenance](https://docs.npmjs.com/generating-provenance-statements),
+which links the tarball to the workflow run that built it. That needs the
+`id-token: write` permission the publish job already declares, and a **public
+repository**: the registry rejects a provenance bundle built from a private one,
+and it does so after the tag and the GitHub release already exist.
 
 When herdr changes its protocol, bump `TESTED_PROTOCOL` in
 `src/adapters/herdr.ts` and the version named at the top of this file. A
-mismatch is a warning from `agent-loop check` and never a refusal to run, so
-this is bookkeeping rather than a gate: the reason to keep it current is that
-the warning is worthless once it is always on.
+mismatch is a warning from `agent-loop check`, never a refusal to run, so this
+is bookkeeping: the point is that a warning which is always on is worth nothing.
+
+## Contributing
+
+Issues and pull requests are welcome:
+[github.com/tonoid/agent-loop/issues](https://github.com/tonoid/agent-loop/issues).
+
+A new job kind is the most useful thing you can add. Kinds are a closed
+registry rather than a plugin system (`src/kinds/`): implement `check`, `build`
+and `validateOptions`, register it, and `agent-loop kinds` documents it for
+free. Land work with [conventional commits](https://www.conventionalcommits.org)
+so the release notes write themselves, and run `bun run typecheck && bun test`
+before opening the pull request.
+
+## Safety
+
+This tool starts AI coding agents and lets them work unattended, so read this
+before pointing it at anything you care about.
+
+Workers run with permission prompts disabled, as your user, with no sandbox.
+They create branches, push them, open pull requests, apply labels, leave
+comments, and depending on the job's `mergeMode` they merge. Nobody approves
+any of that at the time it happens: that is the entire point of the loop, and
+it is also the risk. Everything they produce is machine-generated and has had
+no human review unless you review it.
+
+They also spend real quota on real accounts. The router holds back whatever
+`reserve` you configure and stops at `maxSpawnsPerDay`, but a misconfigured
+loop can still burn a week's allowance in an afternoon.
+
+Give it its own provider account and its own worktree base, keep it away from
+repositories where an unreviewed merge would matter, and treat the pull
+requests it opens as drafts from a fast, tireless colleague who is sometimes
+confidently wrong. The MIT warranty disclaimer is not a formality here.
+
+Not affiliated with Anthropic, OpenAI, xAI or GitHub. Claude, Claude Code,
+Codex and Grok are trademarks of their respective owners.
+
+## Credits
+
+**Created and maintained by [tonoid](https://www.tonoid.com)** - A microstartup
+studio building services like [2sync.com](https://2sync.com) or
+[refurb.me](https://www.refurb.me).
+
+| | |
+|---|---|
+| 💼 All tonoïd projects | [tonoid.com/projects](https://www.tonoid.com/projects) |
+| 📬 Contact | hello@tonoid.com |
+| 🐙 GitHub | [github.com/tonoid](https://github.com/tonoid) |
 
 ## License
 
-MIT.
+[MIT](./LICENSE) © [tonoid.com](https://tonoid.com).
+
+---
+
+**GitHub topics**: `claude-code` `codex` `ai-agents` `autonomous-agents` `agent-orchestration` `herdr` `cron` `scheduler` `git-worktree` `github-automation` `devops` `typescript` `bun` `self-hosted`

package/briefs/default/core.md

@@ -32,6 +32,25 @@ These are absolute. Breaking one is worse than not finishing the work.
 - Never rewrite history that is already pushed, and never `git checkout` a
   branch other than your own.
 
+## Absolute paths in shell commands
+
+Write every path in a shell command in full, from `/`. Never open a command
+with `cd` into your worktree and then name files relative to it.
+
+Nobody is here to answer a prompt. A permission rule that denies reading
+credentials is configured for you, and it holds even under bypass: it is what
+stops an unattended worker reading a secret. When a command's working directory
+cannot be resolved by reading the command itself, which is exactly what a
+leading `cd` does, the paths after it cannot be checked against that rule, and
+the run stops to ask a human who is not there. One such command left a worker
+blocked for the best part of an hour.
+
+    no    cd "{{worktree}}" && grep -n "thing" -A 20 apps/web/lib/x.ts
+    yes   grep -n "thing" -A 20 {{worktree}}/apps/web/lib/x.ts
+
+The same goes for `sed`, `cat`, `head`, `rg` and every other reader. Your
+worktree is at `{{worktree}}`; prefix it and the command runs unattended.
+
 ## Install first
 
 Install the repository's dependencies before you run anything else. A run that

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tonoid/agent-loop",
-  "version": "1.0.0",
+  "version": "1.1.0",
   "description": "Schedules autonomous coding agents across provider accounts and runs them as herdr agents in herdr panes.",
   "license": "MIT",
   "author": "melalj <3869766+melalj@users.noreply.github.com>",

package/src/adapters/herdr.ts

@@ -37,15 +37,31 @@ export type HerdrRead = Herdr
 
 // The herdr protocol this project was built and tested against. Section 9 of
 // the spec: check it, warn loudly on a mismatch, never refuse to run.
-export const TESTED_PROTOCOL = 19
+//
+// Moved to 22 for herdr 0.9.0, after checking the schema it bundles against
+// every call this adapter makes rather than against the version number alone.
+// AgentStatus still enumerates idle, working, blocked, done and unknown, which
+// is what toStatus below maps; AgentInfo and PaneInfo still require pane_id,
+// tab_id and agent_status, and still carry cwd; WorkspaceInfo still carries
+// workspace_id and label; and tab create, agent start, agent prompt, agent
+// read and notification show all still take the flags and enum values used
+// here. agent list, pane list and workspace list were also read back off a
+// live 0.9.0 and still answer in the envelope the readers here expect.
+export const TESTED_PROTOCOL = 22
 
-const KNOWN: AgentStatus[] = ["working", "blocked", "idle"]
+// Everything herdr's AgentStatus enum holds except "unknown", which is herdr
+// reporting that it has no status for this agent yet: a starting worker reads
+// that way for a few seconds, so it has to mean "no information" and not "gone".
+const KNOWN: AgentStatus[] = ["working", "blocked", "idle", "done"]
 
 function toStatus(s: unknown): AgentStatus {
   return KNOWN.includes(s as AgentStatus) ? (s as AgentStatus) : "missing"
 }
 
-export function makeHerdr(run: Runner): Herdr {
+// agent read answers with the terminal text itself rather than a JSON envelope,
+// so it takes the text runner: putting it through the JSON one turns every read
+// into a parse error, and the failure tail a monitor reports into "no transcript".
+export function makeHerdr(run: Runner, runText: (argv: string[]) => Promise<string>): Herdr {
   return {
     async agents() {
       const r = await run(["herdr", "agent", "list"])
@@ -105,10 +121,9 @@ export function makeHerdr(run: Runner): Herdr {
       await run(["herdr", "agent", "send-keys", target, ...keys])
     },
     async agentRead(target, lines) {
-      const r = await run([
+      return runText([
         "herdr", "agent", "read", target, "--source", "recent-unwrapped", "--lines", String(lines),
       ])
-      return String(r?.result?.output ?? "")
     },
     async agentStatus(target) {
       const r = await run(["herdr", "agent", "get", target])

package/src/cli.ts

@@ -93,9 +93,9 @@ if (cmd === "check") {
     deps: {
       which: (b) => Bun.which(b),
       ghAuth: async () => makeRunners(false).runText(["gh", "auth", "status"]).then(() => true, () => false),
-      protocol: () => makeHerdr(makeRunners(false).runJson).protocol(),
+      protocol: () => makeHerdr(makeRunners(false).runJson, makeRunners(false).runText).protocol(),
       herdrWorkspaces: async () =>
-        (await makeHerdr(makeRunners(false).runJson).workspaces()).map((w) => w.label),
+        (await makeHerdr(makeRunners(false).runJson, makeRunners(false).runText).workspaces()).map((w) => w.label),
       readConfig: async (p) => (await Bun.file(p).exists()) ? Bun.file(p).text() : null,
     },
   })
@@ -187,7 +187,7 @@ const ctxFor = (ws: WorkspaceConfig, marks: ReturnType<typeof openState>) =>
     lock: fileLock(),
     gh: makeGh(rj, rt),
     gitFor: (repo) => makeGit(rt, repo),
-    herdr: makeHerdr(rj),
+    herdr: makeHerdr(rj, rt),
     marks,
     global,
     usageFor: (a, at) => readers[a.provider](a, at),
@@ -264,7 +264,7 @@ async function memAvailableMb(): Promise<number> {
   }
 }
 
-const protocol = await makeHerdr(rj).protocol().catch(() => -1)
+const protocol = await makeHerdr(rj, rt).protocol().catch(() => -1)
 if (protocol !== TESTED_PROTOCOL) {
   console.log(`${stamp()} WARN herdr protocol ${protocol}, tested ${TESTED_PROTOCOL}`)
 }

package/src/config.ts

@@ -12,7 +12,8 @@ const KNOWN_PROVIDERS: Provider[] = ["claude", "codex", "grok"]
 // this at the commit that broke it (spec 3.5).
 const CONFIG_KEYS = [
   "accounts", "workspaces", "maxConcurrentPerAccount", "minFreeMb", "usageMax",
-  "releaseBefore", "maxSpawnsPerDay", "blockedTimeoutMin", "workerRateSeed",
+  "releaseBefore", "maxSpawnsPerDay", "blockedTimeoutMin", "holdTimeoutMin", "staleAgentMin",
+  "workerRunMin", "workerRateSeed",
 ]
 const ACCOUNT_KEYS = [
   "id", "provider", "configDir", "reserve", "reservePerWeekday", "weekendWeight", "soleConsumer", "maxConcurrent", "allowWhenUnreadable",
@@ -28,6 +29,20 @@ export const DEFAULTS = {
   releaseBefore: 120,
   maxSpawnsPerDay: 200,
   blockedTimeoutMin: 180,
+  // Deliberately the same number as the escalation timeout above: one clock to
+  // reason about, and a job whose runs legitimately outlast it is the reason to
+  // make this per-job rather than to raise it for the whole box.
+  holdTimeoutMin: 180,
+  // A finished worker that never exits is invisible to the monitor, because
+  // done() has already taken its claim away. Thirty minutes is long enough
+  // that a worker still writing its last comment is never cut off, and short
+  // enough that a lane does not spend a night starved behind it.
+  staleAgentMin: 30,
+  // Measured on simo over 2026-08-31..09-05: 154 paired spawn and done lines
+  // averaging 16.3 minutes. Rounded up, because the cost of overestimating is
+  // one worker fewer and the cost of underestimating is a run that meets its
+  // ceiling mid-task.
+  workerRunMin: 20,
   workerRateSeed: 0.35,
 } as const
 
@@ -192,6 +207,9 @@ export function parseConfig(text: string): { config: Config; errors: string[] }
       releaseBefore: num(raw.releaseBefore, "releaseBefore", DEFAULTS.releaseBefore, errs),
       maxSpawnsPerDay: num(raw.maxSpawnsPerDay, "maxSpawnsPerDay", DEFAULTS.maxSpawnsPerDay, errs),
       blockedTimeoutMin: num(raw.blockedTimeoutMin, "blockedTimeoutMin", DEFAULTS.blockedTimeoutMin, errs),
+      holdTimeoutMin: num(raw.holdTimeoutMin, "holdTimeoutMin", DEFAULTS.holdTimeoutMin, errs),
+      staleAgentMin: num(raw.staleAgentMin, "staleAgentMin", DEFAULTS.staleAgentMin, errs),
+      workerRunMin: num(raw.workerRunMin, "workerRunMin", DEFAULTS.workerRunMin, errs),
       workerRateSeed,
     },
     errors: errs,