wireal-run 0.1.0

package/LICENSE

@@ -0,0 +1,55 @@
+# PolyForm Internal Use License 1.0.0
+
+<https://polyformproject.org/licenses/internal-use/1.0.0>
+
+## Acceptance
+
+In order to get any license under these terms, you must agree to them as both strict obligations and conditions to all your licenses.
+
+## Copyright License
+
+The licensor grants you a copyright license for the software to do everything you might do with the software that would otherwise infringe the licensor's copyright in it for any permitted purpose. However, you may only make changes or new works based on the software according to [Changes and New Works License](#changes-and-new-works-license), and you may not distribute the software.
+
+## Changes and New Works License
+
+The licensor grants you an additional copyright license to make changes and new works based on the software for any permitted purpose.
+
+## Patent License
+
+The licensor grants you a patent license for the software that covers patent claims the licensor can license, or becomes able to license, that you would infringe by using the software.
+
+## Fair Use
+
+You may have "fair use" rights for the software under the law. These terms do not limit them.
+
+## Internal Business Use
+
+Use of the software for the internal business operations of you and your company is use for a permitted purpose.
+
+## No Other Rights
+
+These terms do not allow you to sublicense or transfer any of your licenses to anyone else, or prevent the licensor from granting licenses to anyone else. These terms do not imply any other licenses.
+
+## Patent Defense
+
+If you make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+## Violations
+
+The first time you are notified in writing that you have violated any of these terms, or done anything with the software not covered by your licenses, your licenses can nonetheless continue if you come into full compliance with these terms, and take practical steps to correct past violations, within 32 days of receiving notice. Otherwise, all your licenses end immediately.
+
+## No Liability
+
+***As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.***
+
+## Definitions
+
+The **licensor** is the individual or entity offering these terms, and the **software** is the software the licensor makes available under these terms.
+
+**You** refers to the individual or entity agreeing to these terms.
+
+**Your company** is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. **Control** means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+**Your licenses** are all the licenses granted to you for the software under these terms.
+
+**Use** means anything you do with the software requiring one of your licenses.

package/README.md

@@ -0,0 +1,75 @@
+# wireal-run
+
+The Wireal runner. It watches one folder on your machine, claims the tasks your
+[Wireal](https://wireal.co) workspace has made ready, and runs Claude Code or
+the Codex CLI on each one in its own git worktree.
+
+```sh
+npx wireal-run login
+npx wireal-run run
+```
+
+The first command signs this machine in. The second binds the folder you are in
+to a workspace and starts the agents your workspace's roster names — the ones
+whose CLI it finds on your PATH.
+
+| Command | What it does |
+| --- | --- |
+| `wireal-run login` | Sign in to Wireal on this machine |
+| `wireal-run run` | Claim ready tasks and run an agent on each |
+| `wireal-run usage` | Show what is left of each agent's limits |
+| `wireal-run rename [name]` | Rename this folder's runner |
+| `wireal-run status` | Show this folder's runner binding |
+| `wireal-run unbind` | Remove this folder's runner binding |
+| `wireal-run logout` | Forget the saved session |
+
+Useful flags on `run`: `--workspace <name>` to bind a folder the first time,
+`--agents <n>` to cap how many run at once (`0` only reports in), `--repo
+<path>` to work on another folder, `--once` to take one round and stop.
+
+The saved sign-in refreshes itself: the runner rotates its token a minute
+before it runs out, so a run left going overnight keeps working. Rotation is
+one token at a time across every `wireal-run` on the machine, and a refresh
+that cannot take the lock waits rather than racing, because the server treats a
+token used twice as stolen and revokes the whole sign-in. If that does happen,
+`wireal-run login` is the only way back, and the runner says so once and stops
+instead of retrying for hours.
+
+One runner to a folder: a second `run` in a folder another runner already
+holds names the process holding it and stops rather than claiming the same
+tasks twice. A runner that died without cleaning up is taken over on the next
+start, as is one whose note predates the last boot, and `--force` takes the
+folder from a runner that is still going. It works the same on macOS, Linux
+and Windows; folders are matched as Windows compares them there.
+
+On Windows the runner finds `claude` and `codex` through `PATHEXT`, starts an
+`npm` shim through the shell that can run it, and takes its name from the
+console title or the ConEmu task. Nothing here needs Orca: the Orca tab is
+read only when Orca itself started the terminal.
+
+While it runs, `1`–`9` attaches to an agent's screen, `ctrl-g` detaches, and
+`q` quits. The machine is kept awake for as long as the runner is up, so an
+agent is never cut off by the lid or the idle timer; the cup in the header
+steams while that hold is in place, and `--allow-sleep` starts without it. The
+tab takes the runner's name while it holds it, and gives the name back when you
+quit.
+
+A new binding is named after the terminal it was made in — the tmux window, the
+screen session or the Orca tab — and falls back to the folder. `wireal-run
+rename <name>` renames it later; `wireal-run rename` with no name takes the
+terminal's name again. A runner already running picks the new name up on its
+next heartbeat, so the app follows without a restart.
+
+The runner reads each signed-in CLI's own usage limits without starting an
+agent: Codex every few minutes, Claude about once an hour, which is as often as
+Anthropic gives them out. Between reads it falls back to what is already on
+disk — the last figures it read, kept beside its session file, and the ones
+Codex writes into its own rollouts — so the 5-hour and 7-day columns are filled
+in before you hand out work, here and in the app. An agent whose window is over
+the workspace's pause limit is held back rather than claiming a task.
+
+Agents are configured in the app, not here: the roster, the model each one
+uses, the merge policy and the checks to run before a merge all live in your
+workspace. Full setup at [wireal.co/docs](https://wireal.co/docs).
+
+Requires Node 22 or newer, git, and the agent CLIs you want to host.