@cabane/companion 0.6.203 → 0.6.204

package/README.md

@@ -111,6 +111,8 @@ All of it in `~/.cabane/`, mode 600, no database. Cabane is the source of truth
 
 An MCP server configured in Cabane names its credential as `${NAME}`; the value never leaves the device. The Companion resolves it from `secrets.json` at dispatch, never from your shell environment, and a name that isn't declared fails the turn loudly. It reports the declared names (never values) on its heartbeat, so Cabane can warn before a turn runs.
 
+A device with no keychain or browser, such as a server or a container, can sign its harness in from `secrets.json` too: `CLAUDE_CODE_OAUTH_TOKEN` or `ANTHROPIC_API_KEY` for Claude Code, `CODEX_API_KEY` for Codex. Only the turn's own harness gets its sign-in. `GH_TOKEN` there reaches every turn, for `gh` and git over HTTPS.
+
 ### Local overrides
 
 `config.json` can carry, per agent (keyed by id, `@username` or `workspace-slug/username`) or for the whole device:
@@ -121,7 +123,29 @@ An MCP server configured in Cabane names its credential as `${NAME}`; the value
 - `harnesses`: an allowlist such as `["claude-code"]`; absent means all three.
 - `claudeCode.autoMemory`: Claude Code's local memory directory is off by default on every Companion, because notes belong in the workspace where others can read them. `true` hands it back.
 
-A malformed block fails `cabane start` with the field named. A `runners` block or a row's `sandbox` from an older Companion is ignored, with one line in the log naming it.
+A malformed block fails `cabane start` with the field named. A `runners` block, a row's `sandbox`, or a `prepareHook`'s `validateCached` or `failureReporter` from an older Companion is ignored, with one line in the log naming it.
+
+Every turn's shell gets `CABANE_CONVERSATION_ID` and `CABANE_AGENT_ID`, so a script an agent runs can tell which conversation and agent it's working for.
+
+### Running each turn somewhere else
+
+`runner.command` puts a command in front of every turn: `"runner": { "command": ["/usr/local/bin/enter-sandbox", "--fresh"] }` starts each turn as `enter-sandbox --fresh <the Companion's own run-turn command>`. Use it to run each turn in a container or VM of your own while the Companion stays outside. Your command must run the rest of its arguments, with the environment and stdin it was given.
+
+A wrapped turn gets the device's secrets on its stdin rather than reading `secrets.json`, inherits no sign-in from the Companion's own environment, and is never signalled by process group from outside: your command ends whatever the turn leaves behind.
+
+What your command can rely on, and can set:
+
+| Variable                     |                                                                                                                                                     |
+| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `CABANE_DISPATCH`            | Read: the dispatch as JSON, including `conversationId` and `agentId`.                                                                               |
+| `CABANE_RUNNER_SPEC`         | Read: the turn's settings as JSON, including `agentUsername`.                                                                                       |
+| `CABANE_TURN_ID`             | Read: the turn's id.                                                                                                                                |
+| `CABANE_COMPANION_HOME`      | Read, when the Companion was started with one: the home its `.cabane` directory is under.                                                           |
+| `CABANE_WORK_ROOT`           | Set: the root the turn's working directory goes under, in place of `root`.                                                                          |
+| `CABANE_TRANSCRIPT_DIR`      | Set: where the turn writes its transcript. A directory one level under `~/.cabane/transcripts/` lists in `cabane transcript`.                       |
+| `CABANE_WORK_ROOT_DEDICATED` | Set to `1` when the root is already this one conversation and agent's: the turn stands in it directly, with no per-conversation directory under it. |
+
+These names are a contract: a Companion that renamed one would break your command, so none changes without a note in the release.
 
 ### Isolation