@kilogent/runner-dev 0.1.3 → 0.1.5

package/README.md

@@ -5,7 +5,8 @@ workspace.
 
 Crew agents don't run in the cloud. They run **on your machine**, in your checkouts, with your
 tools. This daemon is what makes that happen: it watches the job queues of the Ships you assign it
-to, claims work oldest-first, and executes each job as a headless Claude session.
+to, claims work oldest-first, and executes each job as a headless agent session on the engine the
+agent runs on.
 
 ```bash
 npm i -g @kilogent/runner
@@ -30,13 +31,52 @@ each publishes only a `latest` tag, and a machine changes environment by install
 | | |
 |---|---|
 | **Node.js** | 20 or newer |
-| **Claude Code** | the `claude` CLI on your `PATH` ([install](https://claude.com/claude-code)) |
+| **An engine CLI** | the CLI of every engine your agents run on, on your `PATH` — see [Engines](#engines) |
 | **git / gh** | only if your agents work on GitHub repositories |
 | **A Lumi Crew account** | with at least one Ship — [app.kilogent.com](https://app.kilogent.com) |
 
 The daemon is a *client*. It signs in as you, and every write it makes is checked server-side
 against your Ship membership. No service-account key ever touches your machine.
 
+## Engines
+
+An agent runs on an **engine** — the CLI that actually holds the session. The daemon spawns the
+engine's binary per job, and `doctor` checks that every engine a Ship's agents use is installed.
+
+**You do not have to install them yourself.** The daemon fetches the CLIs its crews need into its
+own folder (`~/.kilogent-runner/tools/<engine>/`) and runs agents on that copy. A CLI you installed
+yourself is never changed or removed, and the two stay independent: upgrade yours whenever you like,
+the crew keeps running on the version the fleet knows works.
+
+⚠️ **They are large.** The Codex CLI is about 284 MB installed and Claude Code about 202 MB. Each is
+replaced rather than added to on an upgrade, so a machine running both settles around half a
+gigabyte. To decline the whole thing and manage them yourself:
+
+```
+kilogent-runner config set autoInstallEngines off
+```
+
+Which version a machine installs comes from the fleet, not from this machine: it takes the version
+known to work, moves to a newer release only after that release has been out for a day, and never
+installs one another machine has proved broken. If a new version breaks a job here, this daemon puts
+the working version back, runs the job again, and — only if that succeeds — tells the fleet, so no
+other machine installs it.
+
+```
+kilogent-runner engine list                 what each engine needs, what this machine has, and where it came from
+kilogent-runner engine install [engine...]  install now (--check, --dry-run, --force)
+kilogent-runner engine uninstall <engine>   remove this runner's copy, never yours
+```
+
+| Engine | Binary | Credential |
+|---|---|---|
+| Claude Code | `claude` ([install](https://claude.com/claude-code)) | a `claude setup-token`, pasted once per Ship in the Crew app |
+| Codex CLI | `codex` ([install](https://developers.openai.com/codex)) | a **machine sign-in**: a captain picks this machine in the Crew app, the daemon runs `codex login --device-auth`, and the captain approves the code on a phone. The login stays on this machine — see [Credentials](#credentials). |
+
+Each engine's binary can be overridden with `CREW_<ENGINE>_BIN` (`CREW_CLAUDE_BIN`), which wins over
+the copy the daemon installed and is the supported way to pin a machine to a particular binary. It
+is also how the test suites substitute a deterministic fake.
+
 ## Connect a machine
 
 ```bash
@@ -113,7 +153,7 @@ from a hang.
 ### `doctor`
 
 Run this first when something isn't working. Everything it checks used to be discovered *inside a
-running job*, surfacing as a failed task on your board minutes later: a missing `claude` binary,
+running job*, surfacing as a failed task on your board minutes later: a missing engine binary,
 unsaved Ship credentials, a machine no captain approved. It checks Node ≥ 20, your stored session,
 per-Ship approval and credentials, the engine binary, `git`/`gh` when an agent uses GitHub, server
 reachability, the background service, whether that service still points at a CLI that exists, and
@@ -162,8 +202,8 @@ kilogent-runner config list                              # what is set, and what
 The machine number is a ceiling, not a total: three Ships at `2` each on a machine set to `3` will
 never run more than three sessions. A Ship with no number of its own may use the whole machine.
 
-Each job is a separate `claude` process with its own empty working directory, so they don't share
-state — but they do share your CPU, your RAM and your Claude usage window. Start at 2 and watch a
+Each job is a separate engine process with its own empty working directory, so they don't share
+state — but they do share your CPU, your RAM and your subscription's usage window. Start at 2 and watch a
 real job before going higher. Restart the daemon (`kilogent-runner service restart`) to pick up a change.
 
 ## MCP servers that run on this machine
@@ -246,12 +286,23 @@ always as a warning — being out of date never fails the preflight.
 
 ## Credentials
 
-Agent-session credentials — the Claude token and, if your agents use GitHub, a token for that — are
-**not** stored on this machine. A captain saves them once per Ship in the Crew app's Ship Settings,
-and the daemon fetches them at job time, injects them into the session environment, and redacts them
-from the transcript before upload. `kilogent-runner doctor` tells you when a Ship is missing them.
+Agent-session credentials — a pasted engine token and, if your agents use GitHub, a token for that —
+are **not** stored on this machine. A captain saves them once per Ship in the Crew app's Ship
+Settings, and the daemon fetches them at job time, injects them into the session environment, and
+redacts them from the transcript before upload. `kilogent-runner doctor` tells you when a Ship is
+missing them.
+
+**Machine sign-ins are the exception, on purpose.** An engine whose account has no static token
+(Codex on a ChatGPT plan: its login rotates a refresh token on every use, so a copy on a second
+machine kills the first) is signed in ON ONE MACHINE. The daemon keeps that login in a private
+directory, `~/.kilogent-runner/engines/<engine>/<ship>/<credential>/`, refreshes it itself, and
+never sends it anywhere. Jobs on that credential run on this machine only; the daemon runs one
+session per sign-in at a time. Deleting the credential in the app signs this machine out and removes
+the directory; so does removing the machine from the Ship, and `kilogent-runner uninstall --purge`.
+`doctor` reports each sign-in this machine holds and whether the engine still accepts it.
 
-The only thing stored locally is your own session, in `~/.kilogent-runner/config.json` (mode `0600`).
+The only other thing stored locally is your own session, in `~/.kilogent-runner/config.json`
+(mode `0600`).
 
 ## Uninstalling
 
@@ -305,7 +356,8 @@ claiming from one queue.
 | Var | Effect |
 |---|---|
 | `LUMI_RUNNER_HOME` | Config + log directory (default `~/.kilogent-runner`) |
-| `CREW_CLAUDE_BIN` | Path to the Claude binary (default: `claude` from `PATH`) |
+| `CREW_<ENGINE>_BIN` | Path to an engine's binary, e.g. `CREW_CLAUDE_BIN`, `CREW_CODEX_BIN` (default: the copy this runner installed, else the engine's own name from `PATH`) |
+| `CREW_MACHINE_LOGIN_TIMEOUT_MS` | How long a machine sign-in may wait for approval before it is reported expired (default: 16 minutes; a test seam) |
 | `CREW_NO_NOTIFY` | Force desktop notifications off, whatever the config says (they are off by default) |
 | `CREW_NO_POWER` | Disable sleep inhibition |
 | `LUMI_RUNNER_REGISTRY` | npm registry to check for updates (default `https://registry.npmjs.org`) |