@codesona/runner 0.1.0 → 0.2.0

package/README.md

@@ -10,6 +10,9 @@ machine, with your own account and your own model choice.
 - Node.js 20.9 or later
 - Claude Code 2.1.306 or later, installed and logged in. Codex and Cursor are detected, and will be
   supported later.
+- For a Developer agent: git, with a credential helper that can reach your repositories over https,
+  and the toolchain your product builds with (.NET SDK, Node.js), installed by you. See
+  [Developer agents](#developer-agents).
 
 ## Getting started
 
@@ -38,8 +41,9 @@ again, and `restart` says so; `codesona-runner doctor --fix` sets the service up
 |---|---|
 | `codesona-runner start --machine-key <key>` | Pairs this machine with your workspace and sets up the background service. Options: `--url <url>` (an `https://` address), `--name <name>` (defaults to the machine's host name), `--no-service` (pair only; take sessions with `codesona-runner run`) |
 | `codesona-runner run` | Keeps the machine connected and runs the sessions Codesona hands it, until you stop it (Ctrl-C). One per machine: not while the background service runs |
-| `codesona-runner doctor` | Checks what this machine needs to run sessions: Node.js, the coding agent CLIs and Claude Code's login, Claude Code settings that would switch off Codesona's checks, the connection to Codesona, the clock, sleep settings and the background service. `--fix` puts right what needs no administrator (the background service only while it runs no session) and prints the exact `sudo` command for the rest |
+| `codesona-runner doctor` | Checks what this machine needs to run sessions: Node.js, the coding agent CLIs and Claude Code's login, Claude Code settings that would switch off Codesona's checks, git (its credential helper, commit signing, SSH remotes the background service cannot use), the connection to Codesona, the clock, sleep settings and the background service. `--fix` puts right what needs no administrator (the background service only while it runs no session) and prints the exact `sudo` command for the rest |
 | `codesona-runner status` | Shows whether this machine is connected, its agents and its sessions |
+| `codesona-runner prune` | Removes the Developer agents' repository worktrees and local task branches nobody touched for 14 days whose branch your repository's origin already has (at the same commit or a later one). It never removes work that was not pushed: a worktree with uncommitted changes, or a branch with commits origin lacks, is kept and listed. Not while the Runner runs sessions |
 | `codesona-runner restart` | Restarts the background service (`launchctl kickstart -k`), so it runs the Codesona Runner installed now and connects anew, and waits until it is connected. Not while it runs sessions: it says how many and leaves it alone; `--force` restarts it all the same, ending them. With no background service set up, it says so: stop `codesona-runner run` (Ctrl-C) and run it again |
 | `codesona-runner logout` | Disconnects this machine from Codesona, removes the background service and the Runner's files. If Codesona cannot be told, nothing is removed; `--local` removes this machine's side anyway (then disconnect it in Factory) |
 | `codesona-runner --version` | Shows the version |
@@ -49,6 +53,32 @@ them to Codesona first. While a session runs it keeps the Mac awake; an idle Mac
 and its agents' runs wait for it. `codesona-runner doctor` says which power settings would let it
 sleep or stay off, and the command that changes them.
 
+## Developer agents
+
+A Developer agent's sessions work in your product's repositories on this machine (Codesona Runner
+0.2.0 or later). Before such a session starts, the Runner checks that this machine's git can reach
+each repository (`git ls-remote`); if it cannot, the run is not taken and Factory shows why. Then it
+checks the repositories out: one bare clone per repository under `~/.codesona-runner/repos/`, and one
+worktree per agent at `~/.codesona-runner/agents/<agent>/repos/<repository>`, on the task's branch.
+The agent builds and tests there with the tools you installed, commits, and pushes with your git.
+
+- **Git and your credentials.** git runs as you, with your `~/.gitconfig` and your credential helper;
+  Codesona sends no token to this machine, and the repositories' URLs carry none. Set up a credential
+  helper and sign in once in a terminal: Git Credential Manager
+  (`brew install --cask git-credential-manager`), or `gh auth setup-git` for GitHub. The background
+  service has no SSH agent, so use https remotes; `codesona-runner doctor` warns of an SSH remote,
+  including one an `insteadOf` rule in your git config makes.
+- **Commit signing.** Sessions run with `commit.gpgsign` and `tag.gpgsign` off, so a signing setup
+  never waits for a PIN in the background and the agent's commits are not signed with your key.
+  `codesona-runner doctor` says when your git config signs commits.
+- **Your work and the agent's.** A worktree is the agent's: when it moves to another task its
+  uncommitted changes are cleared (build caches such as `node_modules`, `bin`, `obj`, `.nuget`,
+  `.gradle`, `target` and `dist` are kept), and its commits stay on their own branch. The Runner never
+  deletes a branch with commits origin lacks. `codesona-runner prune` clears worktrees and branches
+  that are done with.
+- **Toolchain.** The Runner does not install SDKs. It reports git, the .NET SDKs and Node.js it finds
+  to Codesona; a session that needs one you do not have says so.
+
 ## What it keeps on the machine
 
 Everything is under `~/.codesona-runner/` (only you can read it):
@@ -57,7 +87,9 @@ Everything is under `~/.codesona-runner/` (only you can read it):
   a day). The keys for the connection, for each agent and for each session live only in the running
   Runner's memory.
 - `agents/<agent>/`: each agent's working directory, with the instructions, skills and settings of
-  its sessions. Your coding agent CLI keeps its transcripts where it always does (`~/.claude`).
+  its sessions, and a Developer's worktrees under `repos/`. Your coding agent CLI keeps its transcripts
+  where it always does (`~/.claude`).
+- `repos/`: a bare clone of each repository a Developer agent works in, shared by its worktrees.
 - `outbox/`, `spool/`, `state/`: results and activity not yet delivered to Codesona, and what
   `codesona-runner status` shows. The background service's log is `state/runner.log`.