maesttro 0.1.2 → 0.2.0

package/README.md

@@ -1,9 +1,10 @@
 # maesttro
 
 Isolated Docker sandbox for local coding agents — `claude`, `opencode`, `codex`,
-and others — running under a dedicated bot GitHub identity, never your personal
-`~/.ssh` or `~/.config/gh`. Install once, then `maesttro` just works from any
-project.
+and others. Inside the sandbox, `gh` and `git` act as the Maesttro GitHub App's
+bot, using a token that is scoped to the current repo and lasts at most an hour.
+Your personal `~/.ssh` and `~/.config/gh` are never used. Install once, then
+`maesttro` just works from any project.
 
 Companion piece to Maesttro's orchestration side: this is the local, single-
 machine entry point — a curated, versioned way to run any supported client
@@ -39,9 +40,10 @@ resolves against the same registry:
 npm i -g @esatto/maesttro
 ```
 
-**From source** (the package lives in the `stagehand/` directory of the Maesttro monorepo):
+**From source** (the package lives in the `stagehand/` directory of the Maesttro monorepo;
+the CLI is TypeScript bundled to `dist/` with Bun):
 ```bash
-npm i -g ./stagehand
+cd stagehand && bun run build && npm i -g .
 ```
 
 ---
@@ -49,23 +51,76 @@ npm i -g ./stagehand
 ## Usage
 
 ```bash
-maesttro setup /path/to/bot-token.txt   # one-time: build image, create volume, auth bot
+maesttro setup                           # one-time: build image, create volume, log in to GitHub
+maesttro login / logout / status         # manage the GitHub login
 maesttro list                            # see available clients
 maesttro doctor                          # health check anytime
 
-maesttro                                 # launch the default client (claude)
-maesttro opencode                        # launch opencode instead
-maesttro codex                           # launch codex instead
+maesttro                                 # from a repo root: new session clone + default client (claude)
+maesttro opencode                        # same, with opencode
+maesttro codex                           # same, with codex
 maesttro bash                            # plain shell inside the sandbox, for debugging
+maesttro sessions                        # list this repo's kept sessions
+maesttro resume <id>                     # continue one
+maesttro push [branch]                   # push a branch a session created (shows what goes out, asks first)
 
 maesttro update                          # bump the package + rebuild image with refreshed configs
 ```
 
 ---
 
+## Sessions: what an agent can and can't touch
+
+Run `maesttro` from the root of a repository (git 2.48+ required). Each run is a
+**session** with its own isolated clone, `.worktrees/maesttro-<id>`, detached at
+`origin/<default branch>` and mounted at `/workspace`. That clone is the only
+part of the repo the container sees:
+
+- Your real `.git` is never mounted, and neither is your main checkout or any
+  uncommitted work there. The container works in a `git clone --shared` that
+  borrows the real object store read-only.
+- The host never runs git inside the clone, so agent-authored git config, hooks
+  or attributes can't make your host git run anything.
+- The agent commits on its own branch in the clone. It **cannot push**:
+  the sandbox's GitHub token is read-only for code.
+- When a branch is ready, the agent asks you to run `maesttro push <branch>`
+  from the repo root. That command pushes only branches a session created,
+  never the default branch or branches that existed before. It shows you the
+  commits and diff first.
+- To review a session's work, read it through the main repo
+  (`git -C <repo> log refs/maesttro/<id>/<branch>`) rather than `cd`-ing into
+  the clone, so your shell prompt or IDE doesn't run git on agent-authored config.
+- Every launch backs up the repo's branches and tags into a single bundle file
+  under `~/.config/maesttro/backups/`, so any earlier state can be restored.
+
+`maesttro push` is plain git, so it works the same for Azure DevOps, GitLab and
+other hosts.
+
+## GitHub access
+
+Inside a session, `gh` works for **that repo only** (issues, pull requests,
+comments). It acts as the Maesttro GitHub App's bot:
+
+- `maesttro login` runs once. It's a GitHub device flow, and your token is kept in the OS keychain.
+- Each launch asks the Maesttro broker for a token that is scoped to the repo and lasts at most an hour. The CLI refreshes it quietly and revokes it when you exit.
+- The token can read code and write issues and PRs, but can't push, merge or delete branches.
+- Commits are authored by you (your repo's `user.name` / `user.email`) and committed by the bot.
+- The broker is reached over the tailnet. Off the tailnet, the session still starts, just without `gh`.
+
+## Your instructions come along
+
+At every container start, `maesttro configure` copies your host
+`~/.claude/CLAUDE.md`, `~/.config/opencode/AGENTS.md`, `~/.codex/AGENTS.md` and
+`~/.claude/{agents,commands,skills}` into the sandbox, read-only at the
+source, and adds a short section explaining the sandbox rules. Credentials and
+settings files are never copied.
+
+Upgrading from 0.1.x: the first launch removes the token you pasted before;
+revoke that token on GitHub as well.
+
 ## Curated clients
 
-Defined in `src/clients.js`, installed in `docker/Dockerfile`, configured via
+Defined in `src/clients.ts`, installed in `docker/Dockerfile`, configured via
 `docker/configs/<client>/`:
 
 | Key | Client | Package |
@@ -74,7 +129,7 @@ Defined in `src/clients.js`, installed in `docker/Dockerfile`, configured via
 | `opencode` | opencode | `opencode-ai` |
 | `codex` | OpenAI Codex CLI | `@openai/codex` |
 
-Adding a new client: add an entry to `src/clients.js`, an install line in
+Adding a new client: add an entry to `src/clients.ts`, an install line in
 `docker/Dockerfile`, and a `docker/configs/<key>/` directory with any default
 config — then `maesttro update` rebuilds the image with it included.
 
@@ -82,27 +137,16 @@ config — then `maesttro update` rebuilds the image with it included.
 
 ## How `maesttro update` keeps configs current
 
-`docker/configs/<client>/` files are baked into the image at build time —
-they become each client's out-of-the-box defaults inside the sandbox. When you
-publish a new version of `maesttro` with updated curated configs:
-
-```bash
-maesttro update
-```
-
-does two things, in order:
-1. `npm i -g maesttro@latest` — refreshes the installed package files
-   (including the bundled `docker/` directory) in place
-2. Rebuilds the sandbox image from that same, now-refreshed, `docker/`
-   directory
-
-Because the Dockerfile path is resolved relative to the running script's own
-install location, step 2 automatically picks up whatever step 1 just wrote —
-no extra plumbing needed to keep the two in sync.
+`docker/configs/<client>/` holds the curated client defaults. They aren't baked
+into the image: at every container start, `maesttro configure` runs from your
+installed package, which is mounted read-only, and merges them into each client's
+config, keeping your own keys. So `maesttro update` has two steps:
+1. `npm i -g maesttro@latest` refreshes the package, including `docker/configs/`,
+   which the next session picks up.
+2. It rebuilds the sandbox image, for new client and tool versions.
 
-Your bot identity (in the `maesttro-home` volume) and your project files are
-untouched by an update — only the image (client versions + curated configs)
-gets refreshed.
+Your session state (in the `maesttro-home` volume) and your project files are
+untouched by an update.
 
 ---
 
@@ -110,8 +154,11 @@ gets refreshed.
 
 | Mount | Source | Purpose |
 |---|---|---|
-| `/home/agent` | `maesttro-home` named volume | Bot's persistent identity (`gh` auth, per-client session state). Survives across runs, lives only in Docker. |
-| `/workspace` | current host directory | The project being worked on — repo-level config comes along automatically. |
+| `/home/agent` | `maesttro-home` named volume | Per-client session state. Survives across runs, lives only in Docker. Holds no GitHub credential. |
+| `/home/agent/.config/gh-maesttro` (read-only) | per-session temp dir on host | The session's GitHub token (`hosts.yml`). The CLI refreshes it before its 1 h expiry and revokes it on exit. |
+| `<repo>/.git/objects` (read-only, same absolute path) | your repo's object store | Base history, borrowed by the clone through its `alternates`. The real `.git` is never mounted. |
+| `/workspace` | the session clone (`.worktrees/<id>`) | The working directory: a `git clone --shared` detached at the default branch. |
+| `/opt/maesttro`, `/opt/maesttro-host` (read-only) | this package; your instruction files | Used by `maesttro configure` at container start. |
 | `/home/agent/.claude/skills` (read-only) | `~/agent-shared/skills` on host, if present | Reusable skills/house-style files shared across sessions. Read-only. |
 
 Nothing from your personal `~/.ssh` or `~/.config/gh` is ever mounted.
@@ -123,22 +170,41 @@ Nothing from your personal `~/.ssh` or `~/.config/gh` is ever mounted.
 ```
 maesttro/
 ├── package.json
-├── bin/maesttro.js         # entry point, dispatches subcommands
 ├── src/
-│   ├── clients.js            # curated client registry
-│   ├── setup.js               # `maesttro setup`
-│   ├── update.js              # `maesttro update`
-│   ├── doctor.js               # `maesttro doctor`
-│   ├── launch.js                # `maesttro` / `maesttro <client>` / `maesttro list`
-│   └── paths.js                  # locates bundled Dockerfile wherever npm installs the package
+│   ├── cli.ts       # entry point, bundled to dist/maesttro.js
+│   ├── main.ts      # dispatches subcommands
+│   ├── clients.ts   # curated client registry
+│   ├── setup.ts     # `maesttro setup`
+│   ├── update.ts    # `maesttro update`
+│   ├── doctor.ts    # `maesttro doctor`
+│   ├── launch.ts    # `maesttro` / `maesttro <client>` / `maesttro list`
+│   ├── paths.ts     # locates bundled Dockerfile wherever npm installs the package
+│   ├── account.ts, device-flow.ts, credential-store.ts, github-login.ts
+│   │                # `maesttro login` / `logout` / `status`, keychain storage
+│   └── github-session.ts, broker-client.ts, session-dir.ts, refresher.ts
+│                    # per-session GitHub token: mint, mount, refresh, revoke
+├── broker/          # server-side token broker (not published; see libretto)
+├── tests/
 └── docker/
     ├── Dockerfile
+    ├── gitconfig    # → /etc/gitconfig: SSH→HTTPS, gh as credential helper
     └── configs/
         ├── claude/
         ├── opencode/
         └── codex/
 ```
 
+## Trying it locally
+
+```bash
+bun run stagehand:sandbox
+```
+
+This starts a self-contained sandbox (Docker-in-Docker, the real broker, a fake
+GitHub, a demo repo, a fake login) and drops you into a shell where `maesttro`
+is this checkout's build. No credentials needed. See libretto
+`Modules/stagehand.md` → "Local sandbox".
+
 ## Publishing
 
 Released by CI, not by hand: bumping `version` in `package.json` and merging
@@ -150,6 +216,5 @@ registry it was installed from.
 
 - Fill in real curated defaults in `docker/configs/*` (currently placeholders)
 - Pin exact client CLI versions in the Dockerfile once stable
-- Decide whether each client gets its own bot token/volume for finer audit
-  trail, or shares one (current setup: shared)
+- Decide whether each client gets its own volume, or shares one (current setup: shared)
 - Homebrew tap as an alternative install path for non-Node users — optional