@lumi.ai/runner 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,138 @@
+# @lumi.ai/runner
+
+The **runner daemon** for [Lumi Crew](https://lumi-crew.web.app) — 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 one job at a time, and executes each as a headless Claude session.
+
+```bash
+npm i -g @lumi.ai/runner
+lumi-runner setup
+```
+
+## 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 — [lumi-crew.web.app](https://lumi-crew.web.app) |
+
+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
+lumi-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.
+
+For CI or headless provisioning there is a non-interactive path:
+
+```bash
+lumi-runner login --token <customToken> --api-key <key> --project <projectId>
+```
+
+## Commands
+
+| Command | What it does |
+|---|---|
+| `setup` | One-time onboarding: login → pick Ships → doctor → background service |
+| `login` | Connect this machine (browser approval, or `--token` 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 |
+| `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 |
+| `config list` / `set <key> <on\|off>` | `notifications`, `keepAwake` |
+
+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, and the background service.
+
+### Background service
+
+`lumi-runner service install` writes a real OS service — **no root required**:
+
+| OS | Mechanism | Note |
+|---|---|---|
+| macOS | `~/Library/LaunchAgents/com.lumi.runner.plist` (`RunAtLoad` + `KeepAlive`) | |
+| Linux | `~/.config/systemd/user/lumi-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.
+
+## 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.
+- **A desktop notification** fires on job start, finish and terminal failure, and when the daemon is
+  stopped with work in flight. Silence it with `lumi-runner config set notifications off`.
+- **SIGTERM releases the job.** The daemon aborts the session, hands the 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. `lumi-runner doctor` tells you when a Ship is missing them.
+
+The only thing stored locally is your own session, in `~/.lumi-runner/config.json` (mode `0600`).
+
+## 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 @lumi.ai/runner
+lumi-runner service install
+```
+
+You do **not** need to log in again. `~/.crew-runner` is migrated to `~/.lumi-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 `~/.lumi-runner`) |
+| `CREW_CLAUDE_BIN` | Path to the Claude binary (default: `claude` from `PATH`) |
+| `CREW_NO_NOTIFY` | Disable desktop notifications |
+| `CREW_NO_POWER` | Disable sleep inhibition |
+
+`CREW_RUNNER_HOME` is still honoured as a fallback for machines configured before the rename.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).