@kilogent/runner-dev 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 CodeBridger
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,317 @@
+# @kilogent/runner
+
+The **runner daemon** for [Lumi Crew](https://crew.kilogent.com) — your agentic organization
+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.
+
+```bash
+npm i -g @kilogent/runner
+kilogent-runner setup
+```
+
+## Which package to install
+
+There are **two**, one per environment. They install side by side — different command names,
+different config directories, different service labels — so one machine can run both.
+
+| Package | Command | Workspace |
+| --- | --- | --- |
+| `@kilogent/runner` | `kilogent-runner` | production |
+| `@kilogent/runner-dev` | `kilogent-runner-dev` | development |
+
+The Machines page in your workspace prints the one that matches it. **The package IS the channel**:
+each publishes only a `latest` tag, and a machine changes environment by installing the other one.
+
+## Requirements
+
+| | |
+|---|---|
+| **Node.js** | 20 or newer |
+| **Claude Code** | the `claude` CLI on your `PATH` ([install](https://claude.com/claude-code)) |
+| **git / gh** | only if your agents work on GitHub repositories |
+| **A Lumi Crew account** | with at least one Ship — [crew.kilogent.com](https://crew.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.
+
+## Connect a machine
+
+```bash
+kilogent-runner setup
+```
+
+That's the whole thing. It opens your browser at Crew's `/connect` page, where you pick which Ships
+this machine should serve and approve it in one click. The CLI is polling and collects its session,
+runner id and Ship list from the approval — nothing is copied or pasted. If you approve as a
+**captain**, the machine is authorized on your Ships immediately.
+
+`setup` then runs `doctor` and offers to install the background service.
+
+### A server or VPS
+
+`setup` is interactive and refuses without a terminal, but it does not need a browser **on that
+machine**:
+
+```bash
+kilogent-runner setup --no-browser
+```
+
+It prints the approval link and an 8-character code. Open the link anywhere you do have a browser,
+approve this Ship, and the server finishes on its own — nothing is pasted back.
+
+For CI or unattended provisioning, where nobody is at a terminal at all, paste a Ship key from the
+Daemons page instead — that page prints this command with the two values already filled in:
+
+```bash
+kilogent-runner login --key <shipKey> --api-key <firebaseWebApiKey> --project <projectId>
+```
+
+A key exists only once a captain has approved the machine on that Ship's Daemons page, and it only
+appears in that list after one of the two flows above. So this is the **second** visit to a machine,
+not the first.
+
+### More than one account
+
+One machine can serve Ships belonging to **different people**. Run `setup` again and choose *Add
+Ships, from this or another account*; the second person approves in their own browser, with their
+own sign-in.
+
+Nothing is taken away by that. Approving only ever ADDS Ships, so the machine keeps every key and
+every Ship it already had — the `/connect` page can only see the Ships of whoever is signed in to
+it, so it is never allowed to decide that the others should go. To stop serving one, say so
+explicitly: `kilogent-runner ship remove <shipId>`.
+
+A machine ends up with one identity per account that approved it — `status` lists them — because a
+runner id belongs to an account rather than to hardware. Only `setup`'s *Disconnect and start over*
+removes anything, and it asks twice.
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `setup` | One-time onboarding: login → pick Ships → doctor → background service |
+| `login` | Connect this machine (browser approval, `--no-browser` for a server, or `--key` for CI) |
+| `ship add [ids…]` / `remove` / `list` | Which Ships this machine serves (omit ids to pick from a list) |
+| `doctor` | **Preflight** — can this machine actually run a job? Non-zero exit if not |
+| `service install` / `uninstall` / `restart` / `status` | Run the daemon in the background, always |
+| `uninstall` | Remove the service, then tell you the `npm rm -g` step (`--purge` also clears config) |
+| `start` | Run the daemon in the foreground |
+| `status` | Ships, approval state, current job, queue depth, today's tokens |
+| `logs [-f]` | The daemon's own rotating log file |
+| `update [--check]` | Install the latest published version and restart (see **Staying current**) |
+| `config list` / `set <key> <value>` | `notifications`, `keepAwake`, `autoUpdate`, `checkEvery`, `parallel` |
+
+Global flags: `--json` (machine-readable stdout, and never prompts), `-y/--yes`, `--no-color`.
+
+Without a TTY the CLI does not prompt at all — it fails naming the flag that would have answered the
+question, because a wizard blocking on a hidden stdin inside a systemd unit is indistinguishable
+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,
+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
+whether the **service's own `PATH`** can still reach the binaries your jobs spawn — which is a
+different question from whether your shell can (see below).
+
+### Background service
+
+`kilogent-runner service install` writes a real OS service — **no root required**:
+
+| OS | Mechanism | Note |
+|---|---|---|
+| macOS | `~/Library/LaunchAgents/com.kilogent.runner.plist` (`RunAtLoad` + `KeepAlive`) | |
+| Linux | `~/.config/systemd/user/kilogent-runner.service` (`Restart=always`) | run `sudo loginctl enable-linger $USER` or it stops at logout |
+| Windows | Task Scheduler, at logon | no auto-restart; use pm2 for a true always-on box |
+
+Your `PATH` is captured into the unit at install time. launchd and systemd start processes with a
+minimal environment, so without that `claude`, `git` and `gh` would not be found.
+
+**It is captured once, and a restart does not refresh it.** `service restart` re-runs the unit
+exactly as written, so a daemon keeps the `PATH` of whatever shell first installed it. Install a
+tool somewhere new afterwards — `~/.local/bin`, a Homebrew prefix, an nvm switch — and the daemon
+cannot see it, while every check you can run by hand (`which claude`, `kilogent-runner doctor`) is
+answered by your *current* shell and looks fine. The symptom is a job that fails minutes later
+with `spawn claude ENOENT`.
+
+Two things close that gap: `doctor` reports it as **Service PATH**, and `kilogent-runner setup` now
+reinstalls the service (rather than merely restarting it) when your environment has drifted from
+the installed unit. To fix it directly, from a shell where the tool works:
+
+```bash
+kilogent-runner service install    # rewrites the unit with your current PATH
+```
+
+## How many jobs at once
+
+One, until you say otherwise — the same behaviour this daemon has always had.
+
+```bash
+kilogent-runner config set parallel 3                    # this machine, across every Ship
+kilogent-runner config set parallel 1 --ship shp_abc123  # cap one Ship's share of it
+kilogent-runner config set parallel default --ship shp_abc123   # back to the machine number
+kilogent-runner config list                              # what is set, and what each Ship gets
+```
+
+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
+real job before going higher. Restart the daemon (`kilogent-runner service restart`) to pick up a change.
+
+## MCP servers that run on this machine
+
+A Ship can register MCP connections its agents reach. Most are remote — an `https://` address the
+session talks to. Two kinds are **local**: a program this machine starts (`npx -y some-mcp-server`,
+`node ./my-server.mjs`), and a server already listening on this machine's own loopback address
+(`http://127.0.0.1:3000/mcp`).
+
+**Those are off until you allow them, one Ship at a time.**
+
+```bash
+kilogent-runner config set local-mcp on --ship shp_abc123    # this Ship may run programs here
+kilogent-runner config set local-mcp off --ship shp_abc123   # stop allowing it
+kilogent-runner doctor                                       # which Ships have local connections, and whether they may run
+```
+
+There is no machine-wide form on purpose. A captain registers these in a browser and may not be the
+person who owns this computer — and if this daemon serves several Ships, a single switch would enrol
+every one of them, including any added later. So it is granted per Ship, by you, here.
+
+What a Ship gets when you allow it: the connections a captain registered **on that Ship**, activated
+on the agent running the job, and nothing else. The daemon writes them into the session's config
+file — your own `~/.claude.json` and any `.mcp.json` lying around are still invisible to every agent
+session, exactly as before.
+
+Credentials for these live on the Ship, not here: a captain marks a variable secret and it is stored
+where nothing reads it back, then handed to the program at start and scrubbed from the transcript.
+Press **Test** on the connection in Ship Settings and this machine runs the test and reports what it
+found — the Crew backend cannot reach a program on your laptop, so it asks you instead. Restart the
+daemon (`kilogent-runner service restart`) after changing this.
+
+## Staying current
+
+**This machine updates itself.** Every half hour the daemon asks npm whether there is a newer
+version of the package it was installed from. When there is, it stops claiming new work, lets the
+jobs it is already running **finish**, installs the new version, and exits — launchd and systemd
+restart it, which is what picks up the new code. A captain sees all of it on the Daemons page.
+
+It only ever does this when the background service is installed and running, because "exit and be
+restarted" is the whole mechanism: a daemon you started by hand in a terminal tells you about the
+update and leaves it to you. Windows is the same — the running file is locked there and the
+scheduled task does not restart on exit — so `kilogent-runner update` prints the command instead.
+
+```bash
+kilogent-runner update --check     # is there a newer version?
+kilogent-runner update             # install it now and restart the service
+```
+
+To pin a machine to a version:
+
+```bash
+npm i -g @kilogent/runner@0.5.7
+kilogent-runner config set autoUpdate off
+```
+
+Other settings, all machine-wide:
+
+```bash
+kilogent-runner config set checkEvery 360     # ask less often (minutes, 5–1440)
+```
+
+A version is never installed twice: three failed attempts at the same one and the machine stops
+trying until a different version is published. `kilogent-runner doctor` reports whether you are behind,
+always as a warning — being out of date never fails the preflight.
+
+## While a job runs
+
+- **Idle sleep is inhibited** (`caffeinate` / `systemd-inhibit`, best-effort on Windows), so a
+  laptop doesn't suspend mid-session. It cannot veto you choosing Shut Down — no background process
+  gets that veto on macOS, and it shouldn't.
+- **Desktop notifications are off by default.** They fire on job start, finish, terminal failure and
+  on a daemon stopped with work in flight — which on a busy machine is an interruption every few
+  minutes carrying nothing the task board and the Daemons live log do not already show. Turn them on
+  with `kilogent-runner config set notifications on`. (Sleep inhibition is a separate setting and stays
+  on: "don't close the lid" is `keepAwake`, not a notification.)
+- **SIGTERM releases the job.** The daemon aborts every running session, hands each job back to the
+  queue with its retry budget **unspent**, and only then writes itself offline. Stopping the daemon
+  never costs you an attempt.
+
+## 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.
+
+The only thing stored locally is your own session, in `~/.kilogent-runner/config.json` (mode `0600`).
+
+## Uninstalling
+
+Remove the service **before** the package:
+
+```bash
+kilogent-runner uninstall
+npm rm -g @kilogent/runner
+```
+
+Order matters, and getting it wrong is silent. The launchd plist / systemd unit records an
+*absolute path* to the CLI inside `node_modules` — it has to, since the OS needs something to exec.
+`npm rm -g` deletes that file but knows nothing about your service, so the service stays registered
+and keeps respawning a binary that is no longer there, roughly every ten seconds, for as long as
+the machine lives. npm cannot help here: since npm 7 it does not run `preuninstall`/`postuninstall`
+scripts at all, so no package can clean up after itself.
+
+Already removed the package? Reinstall it, uninstall properly, then remove it again:
+
+```bash
+npm i -g @kilogent/runner && kilogent-runner uninstall && npm rm -g @kilogent/runner
+```
+
+`kilogent-runner doctor` reports a machine that is already in this state, naming the missing path.
+
+Neither command touches `~/.kilogent-runner`. That directory is this machine's **identity** — the
+runner id each account knows it by, and its Ship keys — so uninstalling and reinstalling keeps the
+approvals your captains already granted. Add `--purge` to delete it too, and expect to be approved
+again from scratch, by every account.
+
+## Upgrading from `crew-runner`
+
+This package was previously distributed inside the Lumi monorepo as `@lumi/crew-runner`, with a
+`crew-runner` command. If that's what you have:
+
+```bash
+crew-runner service uninstall
+npm rm -g @lumi/crew-runner
+npm i -g @kilogent/runner
+kilogent-runner service install
+```
+
+You do **not** need to log in again. `~/.crew-runner` is migrated to `~/.kilogent-runner` automatically
+on the first run, which keeps your machine's identity — and therefore the approvals your captain
+already granted it. `service install` also removes the old `com.lumi.crew-runner` /
+`crew-runner.service` unit if the uninstall above was skipped, so you never end up with two daemons
+claiming from one queue.
+
+## Environment variables
+
+| Var | Effect |
+|---|---|
+| `LUMI_RUNNER_HOME` | Config + log directory (default `~/.kilogent-runner`) |
+| `CREW_CLAUDE_BIN` | Path to the Claude binary (default: `claude` from `PATH`) |
+| `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`) |
+
+`CREW_RUNNER_HOME` is still honoured as a fallback for machines configured before the rename.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).