maesttro 0.2.0 → 0.3.0

package/README.md

@@ -1,7 +1,7 @@
 # maesttro
 
-Isolated Docker sandbox for local coding agents — `claude`, `opencode`, `codex`,
-and others. Inside the sandbox, `gh` and `git` act as the Maesttro GitHub App's
+Isolated Docker runner for local coding agents — `opencode`, `claude`,
+and others. Inside the runner, `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.
@@ -56,12 +56,12 @@ maesttro login / logout / status         # manage the GitHub login
 maesttro list                            # see available clients
 maesttro doctor                          # health check anytime
 
-maesttro                                 # from a repo root: new session clone + default client (claude)
+maesttro                                 # from a repo root: new session clone + default client (opencode)
 maesttro opencode                        # same, with opencode
-maesttro codex                           # same, with codex
-maesttro bash                            # plain shell inside the sandbox, for debugging
+maesttro --strict [client]               # same, with no GitHub token in the runner (no `gh`)
+maesttro bash                            # plain shell inside the runner, for debugging
 maesttro sessions                        # list this repo's kept sessions
-maesttro resume <id>                     # continue one
+maesttro resume <id>                     # continue one, in the mode it started with
 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
@@ -82,7 +82,7 @@ part of the repo the container sees:
 - 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.
+  the runner'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
@@ -107,12 +107,21 @@ comments). It acts as the Maesttro GitHub App's bot:
 - 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`.
 
+The write side is coarse. GitHub has no finer grant than "issues" and "pull
+requests", so the same token that lets the agent comment and open PRs also lets
+it edit label definitions and milestones, edit or close other people's issues and
+comments, and submit reviews. If that is more than you want to hand an agent,
+start the session with `maesttro --strict`: no token is minted and none reaches
+the runner. Local git and `maesttro push` work as usual; `gh` and `git fetch` on a
+private repo don't, and the agent hands GitHub actions to you instead. Resuming a
+strict session stays strict; `maesttro resume <id> --no-strict` lifts it.
+
 ## 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
+`~/.claude/CLAUDE.md`, `~/.config/opencode/AGENTS.md` and
+`~/.claude/{agents,commands,skills}` into the runner, read-only at the
+source, and adds a short section explaining the runner rules. Credentials and
 settings files are never copied.
 
 Upgrading from 0.1.x: the first launch removes the token you pasted before;
@@ -125,25 +134,40 @@ Defined in `src/clients.ts`, installed in `docker/Dockerfile`, configured via
 
 | Key | Client | Package |
 |---|---|---|
-| `claude` (default) | Claude Code | `@anthropic-ai/claude-code` |
-| `opencode` | opencode | `opencode-ai` |
-| `codex` | OpenAI Codex CLI | `@openai/codex` |
+| `opencode` (default) | opencode | `opencode-ai` |
+| `claude` | Claude Code | `@anthropic-ai/claude-code` |
 
 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.
+config — then `maesttro update` rebuilds the runner image with it included.
+
+### Maesttro provider
+
+Every launch builds opencode's config on your machine: your own
+`~/.config/opencode/opencode.json(c)`, with secrets removed, and Maesttro's
+config on top (`$MAESTTRO_URL`, default `http://100.64.0.2`). Only the result
+is mounted into the runner, read-only, and copied into place at start. Your
+raw config never enters the container, and your host's config is never written.
+
+Injected: a `maesttro` provider (Orchestrate) at `/v1`, a `dgx-spark` provider
+(lorem direct on the DGX), compaction, default model `maesttro/maesttro`, and
+thinking blocks shown. The two providers replace yours of the same name; the
+rest (`mcp`, `plugin`, other providers) is merged. Removed secrets are listed
+at launch by path. `{env:X}` / `$X` references are kept.
+
+Claude Code gets no Maesttro config and uses its own defaults and login.
 
 ---
 
 ## How `maesttro update` keeps configs current
 
 `docker/configs/<client>/` holds the curated client defaults. They aren't baked
-into the image: at every container start, `maesttro configure` runs from your
+into the runner 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.
+2. It rebuilds the runner image, for new client and tool versions.
 
 Your session state (in the `maesttro-home` volume) and your project files are
 untouched by an update.
@@ -155,7 +179,7 @@ untouched by an update.
 | Mount | Source | Purpose |
 |---|---|---|
 | `/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. |
+| `/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. Not mounted in `--strict` sessions, or when GitHub access is unavailable. |
 | `<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. |
@@ -189,9 +213,7 @@ maesttro/
     ├── Dockerfile
     ├── gitconfig    # → /etc/gitconfig: SSH→HTTPS, gh as credential helper
     └── configs/
-        ├── claude/
-        ├── opencode/
-        └── codex/
+        └── opencode/
 ```
 
 ## Trying it locally
@@ -214,7 +236,6 @@ registry it was installed from.
 
 ## Open items
 
-- 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 volume, or shares one (current setup: shared)
 - Homebrew tap as an alternative install path for non-Node users — optional