@b00dea/cockpit 0.1.0 → 0.1.1

package/docs/getting-started.md

@@ -32,6 +32,10 @@ npm install --save-dev --save-exact @b00dea/cockpit
 npx --no cockpit init . --target claudecode
 ```
 
+With pnpm or yarn, install with `pnpm add -D -E @b00dea/cockpit` or `yarn add -D -E @b00dea/cockpit`
+and run `pnpm exec cockpit` or `yarn cockpit` wherever this guide runs cockpit through `npx --no`. `init`
+detects `pnpm-lock.yaml` or `yarn.lock` and writes the matching commands into what it proposes.
+
 Replace `claudecode` with `codexcli` or `opencode` for those tools, or list several, yours first
 (`--target claudecode,opencode`). `init` records them as `[surfaces] tools` and installs the
 `cockpit-setup` skill for each listed tool. The default tools are `claudecode`, `codexcli` and
@@ -90,25 +94,40 @@ same procedure.
 A clean-looking configuration with invented values in it is the failure cockpit exists to prevent.
 The agent follows these rules for the whole setup:
 
-1. **Ask the human first, and wait for a yes,** before writing into a product repository (a
-   Dockerfile, Compose file, `.env.schema` or anything else in a sibling checkout), creating a Git
-   remote or hosted repository, running a destructive command (`down`, `reset`, `sync --interactive`
-   removals, deleting files), running `cockpit sync --adopt`, or accepting an `init` digest. A person
-   approves or runs staging and the commit of the cockpit: the agent hands them the command.
+1. **Ask the human first, and wait for a yes,** before creating a Git remote or hosted repository,
+   running a destructive command (`reset`, `sync --interactive` removals, deleting files), running
+   `cockpit sync --adopt`, accepting an `init` digest, or changing a product repository in any other
+   way than the next sentences allow (adopting a test framework or a dependency, for example). A
+   person approves or runs staging and the commit of the cockpit: the agent hands them the command.
+   A Dockerfile, Compose file or `.env.schema` the product needs goes on a new branch in that
+   sibling's checkout, started with no uncommitted changes, and the hand-back shows its diff against
+   the branch it started from. Nothing is pushed, so the person reviews it before it reaches anyone
+   else.
 2. **Show the exact preview before asking:** the `sync --dry-run` listing, the `init` preview with its
    `previewSha256`, the answers file or the defaults digest. Consent binds to those bytes, and a
    digest from anything but the latest pending run is refused.
 3. **Never invent a configuration value.** A port, image, command, health check, purpose or name
    comes from a file the agent read or from the human; otherwise it leaves a named gap and asks.
-4. **Inferred values need confirmation.** `init` proposes values with `provenance.kind = "inferred"`
-   and the file each came from; they become answers only on the human's word.
+4. **Only what init read exactly is the agent's to accept.** `init` labels each proposal with
+   `provenance.kind`: `derived` (the complete answer, read from the named file and line),
+   `measured` (observed on this machine) or `inferred` (a hint or guess). A field whose
+   `confirmedBy` is `"agent"` may be answered with `"derived"` (below); `init` checks the value
+   against what it read, and bring-up proves it. Every other field, and every security boundary
+   (the `guards` hosts, protected branches, guard and MCP allow-lists), becomes an answer only on the
+   human's word.
 5. **Ask for every non-local host.** The `guards` answer lists the database and live vendor API hosts
    of production, staging and shared environments. Variable names come from env templates, never
    values; each host comes from the human.
 6. **Defaults never reach into a product repository.** "Use sensible defaults" covers `init` answers
-   only. A pointer in a sibling's **AGENTS.md**, a Compose file or a `package.json` still needs an
-   explicit yes to that exact change. Every answer the agent chose itself is marked `"agent-default"`
-   (below), and its report ends with each default, its field and its value.
+   only. A pointer in a sibling's **AGENTS.md** or a change to its `package.json` still needs an
+   explicit yes to that exact change, and a product file goes on a branch as rule 1 says. Every
+   answer the agent chose itself is marked `"agent-default"` (below), and its report ends with each
+   default, its field and its value.
+7. **Confirm a default only by observing it.** The agent clears an `unconfirmed` entry only with
+   `cockpit confirm`, which runs the observation that verifies that answer on this machine and
+   records it. The trust decisions (`guards`, `testing`, `environment.install_policies`, `sibling`,
+   `environment.posture`) and the answers no observation settles (`cockpit.name`, `estate.runnable`,
+   `environment.test_data`) stay a person's (below).
 
 These rules are instructions, not enforcement. The guard cockpit installs later blocks some commands;
 see [Safety and autonomy](safety-and-autonomy.md).
@@ -135,9 +154,48 @@ guards = "agent-default"
 ```
 
 Each such field is written under `unconfirmed` at the top of `cockpit.toml`, listed in
-`result.unconfirmed`, and reported by `doctor` as `DECLARATION_UNCONFIRMED` until a person confirms
-the value, deletes its `unconfirmed` entry and runs `cockpit sync`. An `environment.machine` floor
-the file does not attribute is recorded as unattributed, because cockpit never proposes one.
+`result.unconfirmed`, and reported by `doctor` as `DECLARATION_UNCONFIRMED` until it is confirmed. An
+`environment.machine` floor the file does not attribute is recorded as unattributed, because no file
+records its free disk or cold start time.
+
+Three answers are facts about this machine and the running product, so an agent confirms them by
+observation, one at a time:
+
+```sh
+./node_modules/.bin/cockpit confirm ports.bases --config cockpit.toml --json
+```
+
+| Answer | The observation that confirms it |
+|---|---|
+| `ports.bases` | `preflight` passes with the stack up and its port family leased on the declared bases |
+| `environment.compose_files` | `check` passes, which parses the Compose files and resolves the stack's topology |
+| `environment.machine` | the runtime measured on this machine meets the declared memory, CPU and free-disk floor |
+
+When the observation passes, `confirm` removes that one entry from `unconfirmed` (comments and every
+other byte stay) and records what ran, when, its result and an evidence digest in
+`.cockpit/local/answer-confirmations`. That file is machine-local and ignored, because the evidence is
+about this machine, and the guard denies agent writes to it. The guard treats the removed entry as
+non-widening only while that record matches the configuration on disk, so the agent's own sync
+applies it where `[autonomy] sync = "agent"`; any other edit, or a clone without the record, leaves
+it to a person. A failed observation is refused with `CONFIRM_OBSERVATION_FAILED` beside the
+diagnostics that explain it.
+
+Every other answer is refused with `CONFIRM_PERSON_REQUIRED`: the trust decisions, and
+`cockpit.name`, `estate.runnable` and `environment.test_data`, which state what the owner wants rather
+than anything a machine can show. A person confirms the value with whoever owns the product, corrects
+it if it is wrong, deletes its `unconfirmed` entry and runs `cockpit sync` in a terminal.
+
+A field whose `interview.outstanding` entry says `confirmedBy = "agent"` can instead be marked
+`"derived"`, with or without a value: `init` answers it with the value it read, refuses
+(`DOCUMENT_CONFIGURATION_ANSWER_NOT_DERIVED`) a value that differs or a field it read no complete value
+for, and writes a `# Derived:` comment naming the source instead of an `unconfirmed` entry:
+
+```toml
+[provenance]
+"cockpit.name" = "derived"
+"ports.bases" = "derived"
+"environment.compose_files" = "derived"
+```
 
 ### Walk through readiness
 
@@ -147,9 +205,18 @@ has an `id`, a `level` (a `required` gap is refused by the command that needs it
 warns), `needs` (why cockpit needs it) and `findings` (each diagnostic with its message and fix).
 `noFinding` lists the prerequisites no check reported; a check that could not run reports nothing, so
 it is not proof. Take the gaps one at a time, required first: what is missing, why, and the exact change
-you propose. Judgement calls (which test runner to adopt, whether the existing tests prove anything)
-are the human's. The cockpit directory must be a Git working tree, committed and clean, before
-`preflight` passes; a new one reports `GIT_STATE_UNHEALTHY` until a person stages and commits it.
+you propose.
+
+Whether the existing tests prove anything is the agent's judgement, made on evidence. For each
+proposed gate, name the behaviours its tests exercise, then break one of them on purpose, run the
+gate, watch it go red, and restore the file so the checkout is as it was found; that edit needs no
+yes, because it is undone before the step ends. Write the behaviours into the gate's `changes` text
+and report the judgement, with the red run's output, in the hand-back. A gate that stays green on the
+break proves nothing about that behaviour, and the report says so. Adopting a new test framework in a
+product repository stays the human's call.
+
+The cockpit directory must be a Git working tree, committed and clean, before `preflight` passes; a
+new one reports `GIT_STATE_UNHEALTHY` until a person stages and commits it.
 
 ## The init interview
 
@@ -178,14 +245,22 @@ depends on what it finds:
   `mount = "none"`).
 - **A declared runtime** adds questions about the machine floor and posture the product needs.
 
-Proposals come only from exact sources: a Dockerfile's `EXPOSE`, `CMD` and `ENTRYPOINT`, a
+Each outstanding field lists its `proposals`, and `confirmedBy` says who settles it: `"agent"` when a
+`derived` proposal answers the whole field (today `cockpit.name`, `ports.bases` and
+`environment.compose_files`, when the files leave no gap), `"person"` otherwise. A source `init`
+could not read, or two that disagree, such as a host port with no default or a memory limit set twice
+with different values, leaves the field to the person. Proposals come only from exact sources: a Dockerfile's `EXPOSE`, `CMD` and `ENTRYPOINT`, a
 `package.json` `start`, `serve` or `dev` script, the `node` toolchain a lockfile names, each
 repository's `origin` remote (a URL carrying credentials is skipped, never shown), variable names
 (never values) in env templates such as `.env.example`, an existing Compose file, the `services:` of
 GitHub workflows, and test entry points such as a Makefile `test` target, a `package.json` test script
 or `go.mod`. A name that suggests a database or vendor endpoint, such as `DATABASE_URL`, becomes a
-`guards` question about its host. Sources `init` could not use are listed in
-`interview.inferenceSkipped`.
+`guards` question about its host. For the machine floor, `init` sums the memory and CPU limits of the
+services the Compose file starts by default (`deploy.resources.limits` or `mem_limit` and `cpus`,
+times their replicas), and where no limit records one it measures this machine's container runtime
+(`measured`, which refuses a smaller machine until someone lowers it). Free disk and the cold start
+time have no source and are never proposed. Sources `init` could not use, including a runtime it
+could not measure, are listed in `interview.inferenceSkipped`.
 
 ### Without a terminal
 
@@ -193,12 +268,15 @@ An agent or CI job has no terminal, so `--interactive` refuses with `INIT_TERMIN
 consent and answers as arguments instead; there is no blanket `--yes`.
 
 1. Run the `--json` preview. It returns the `previewSha256` and, under `interview.outstanding`, every
-   field the interview will still ask, in order, each with a `why` and the values `init` could propose.
+   field the interview will still ask, in order, each with a `why`, its `proposals` and `confirmedBy`.
 2. Write the answers as TOML keyed by field, and show them to the human with the digest.
 3. Rerun with `--accept-preview <previewSha256>` and `--answers <file>`. The run stops at the first
    unanswered field, or at `configuration.defaults`, where `result.question.document` is the review
-   draft (an array of lines) and `result.question.expectedSha256` covers its values. The human reads
-   the draft before accepting that digest.
+   draft (an array of lines). Its provenance comments split the surfaced defaults in two: schema
+   defaults and the cockpit's own layout, which the agent accepts, and the security boundaries
+   (protected branches, guard allow and deny lists, approved MCP servers, resettable volumes,
+   generated host paths), which a person confirms. `result.question.expectedSha256` covers only the
+   second group, and the human reads it before accepting that digest.
 4. Rerun with `--accept-defaults <expectedSha256>` as well. A digest that is not the pending one is
    refused (`INIT_PREVIEW_NOT_ACCEPTED`, `INIT_DEFAULTS_NOT_ACCEPTED`).
 
@@ -239,11 +317,11 @@ vendor_endpoint_hosts = []
 | `environment.install_policies` | the build and test commands per toolchain and lockfile; `[]` for none |
 | `environment.test_data` | exactly the boolean keys `seeded_data` and `signed_in_users`; `false` states it is not needed |
 | `environment.compose_files` | the Compose files that run the product, relative to the cockpit root |
-| `environment.machine` | the runtime floor: `runtime_memory_mb`, `runtime_cpus`, `free_disk_mb`, `cold_start_seconds`; never proposed |
+| `environment.machine` | the runtime floor: `runtime_memory_mb`, `runtime_cpus`, `free_disk_mb`, `cold_start_seconds`; memory and CPUs are proposed, free disk and cold start never |
 | `environment.posture` | `addressing`, `authentication` and `posture_requirements` ([Declare environment postures](environment.md#declare-environment-postures)) |
 | `testing` | the product's `[testing]` stages and gates; `"none"` records that it has no tests yet, so no work can be graded PASS and `doctor` warns (`TESTING_GATE_UNDECLARED`) |
 | `guards` | `hosted_db_hosts` and `vendor_endpoint_hosts` of every non-local environment; `[]` for both records that none exists |
-| `provenance` | optional; `"human"` (the default) or `"agent-default"` per field |
+| `provenance` | optional; `"human"` (the default), `"agent-default"` or `"derived"` per field. An `"agent-default"` answer stays under `unconfirmed` until `cockpit confirm` observes it or a person confirms it ([Mark the answers you chose](#mark-the-answers-you-chose)) |
 
 A key that names no field is refused. Recorded answers are kept, so the same file can be passed on every
 run; a different value for a recorded field is refused (`INIT_ANSWER_CONFLICT`) before anything is
@@ -277,7 +355,7 @@ compose_files = ["compose.yml"]
 `[ports.bases]` variable, and a service without a healthcheck warns. The rules are in
 [Environment lifecycle](environment.md#environment-modes); a working layout is
 [examples/compose-first](https://github.com/b0dea/cockpit/blob/main/examples/compose-first/README.md). Changing a product's Compose file is a
-product change: ask first.
+product change: an agent makes it on a branch, as the [safety contract](#safety-contract) says.
 
 **Data.** `seed` and `resettable_volumes` fill and wipe the stack's data
 ([Demo data, test users and roles](environment.md#demo-data-test-users-and-roles)). `cockpit reset` previews the change and needs a person
@@ -557,6 +635,12 @@ group stops, `session` calls `sleep`, which stops the stack only if no other che
 it. Interrupting `session` stops only the process group it started, and a `session` inside another
 is refused. Use plain `up` only when the stack should outlive one command.
 
+While it runs, `ps` shows each service, and `restart`, `rebuild` and `exec` act on one of them by its
+`--service` name; `up --profile <name>` adds a Compose profile. To work on a sibling in a worktree,
+`use <slug> <checkout>` points this cockpit checkout's stack at it, `pull` fast-forwards every
+checkout, and `stacks prune` removes the stack a deleted worktree left behind. All of them are in
+[Environment lifecycle](environment.md#serve-a-sibling-from-a-worktree).
+
 To remove the stack and its containers, run `down`. It reads the active Docker context once,
 refuses one that is not local, and deletes only from that daemon, so a deletion never lands on a
 remote daemon or on a context switched mid-command

package/docs/harness-surfaces.md

@@ -171,8 +171,9 @@ refused even the `test-run` its own skill asks for. The generated `.claude/setti
 allows, by prefix, the cockpit commands the shipped skills tell an agent to run and the guard
 admits (see [Cockpit commands an agent can run](safety-and-autonomy.md#cockpit-commands-an-agent-can-run)),
 spelled both as `npx --no cockpit <command>` and as `./node_modules/.bin/cockpit <command>`.
-Person-only commands such as `sync`, `down` and `work accept` keep prompting. The guard hook still
-runs first, and its ask or deny wins over a rule. Claude Code ignores a project's allow rules
+Commands that are always a person's, such as `init` and `sibling add`, have no rule and keep
+prompting. A command the policy decides, such as `sync` or `work accept`, has a rule: the guard hook
+still runs first, and its ask or deny wins over a rule. Claude Code ignores a project's allow rules
 until a person has trusted the workspace by starting Claude Code there once. Measured with Claude
 Code 2.1.316 on 2026-11-02 beside a command with no rule.
 
@@ -248,6 +249,52 @@ environment and pass `PATH`, the same non-secret variables product test stages r
 `USER`, `LOGNAME`, `TMPDIR`, `LANG`, `LC_ALL`, `LC_CTYPE`, `TZ`) and the declared environment
 names.
 
+### Remote servers
+
+A remote (streamable HTTP) server is declared in the same file, in Claude Code's spelling:
+
+```json
+{ "mcpServers": {
+  "tracker": { "type": "http", "url": "https://mcp.example.test/mcp",
+               "headers": { "Authorization": "Bearer ${TRACKER_TOKEN}" } },
+  "docs": { "type": "http", "url": "https://docs.example.test/mcp", "headersHelper": "bin/mcp-headers docs" }
+} }
+```
+
+The URL must use `https`, or `http` only to a loopback host, and may carry no user information,
+credential-named query parameter or `${...}` reference. Each header value is exactly `${NAME}`, or
+`Bearer ${NAME}` in `Authorization`; a literal is refused, so no credential enters a tracked file.
+`headersHelper` is a command and plain arguments, relative to the sibling, that prints a JSON object
+of headers when the tool connects; it runs without a shell, so quoting and expansion belong in the
+script. SSE servers are refused because Codex cannot connect to them. The approval digest covers the
+URL, the header references and the helper's command, arguments and directory, so changing any of
+them needs a new approval. Like a local server's command, the helper script's content is not in the
+digest.
+
+| Tool | Header references | Headers helper |
+| --- | --- | --- |
+| Claude Code | `headers` in `.mcp.json`, expanded from its environment | `headersHelper` |
+| Codex | `bearer_token_env_var` and `env_http_headers` in `.codex/config.toml` | `http_headers_helper` |
+| OpenCode | `{env:NAME}` in the `headers` of a `remote` server | none: the server is not written |
+| Cursor, Grok Build | not written | not written |
+
+A tool that cannot carry a server's credential gets nothing for that server, rather than a server
+that starts and fails to authenticate; `sync` and `check` report `MCP_TRANSPORT_UNAVAILABLE` with the
+tools it was left out of. The [capability matrix](capability-matrix.md) records the run behind each
+cell. Claude Code runs a `headersHelper` from the project `.mcp.json` only after a person trusts the
+workspace; until then it connects without those headers.
+
+A header reference resolves from the environment the agent tool was launched in, so a tool started
+from a desktop launcher may not see a variable set in a shell profile. A helper reads the credential
+when the tool connects instead, wherever it keeps it. The helper runs through a generated wrapper,
+`.cockpit/mcp/<id>.headers.sh`, started from the cockpit root like a local server's wrapper: it
+changes to the sibling and passes the same inherited variables, without the header names.
+
+`doctor` checks each approved server without starting it or using the network: a local server's
+command and a remote server's helper must resolve (`MCP_COMMAND_UNRESOLVED`), and every environment
+name it reads must be set where doctor runs (`MCP_ENVIRONMENT_UNSET`). It names variables, never
+values.
+
 Browser transport is published only for harnesses that can use it. A harness with no applicable
 MCP server receives no MCP-only output; its instructions, skills and permissions still publish.
 Verify the result with `./node_modules/.bin/cockpit check --config cockpit.toml --json` after
@@ -294,6 +341,26 @@ project root, so the committed pattern is `{file:.cockpit/local/opencode-grant-<
 substitutes the absolute sibling directory that `sync` writes to that machine-local, ignored file,
 and refuses to start, naming the file, until `sync` has run on the machine.
 
+A checkout `cockpit use` serves from outside the declared one needs a grant that names a path on one
+machine, which no committed file can hold. Measured on 2026-11-04, each run writing into the granted
+directory and into an ungranted control directory beside it:
+
+- Claude Code 2.1.318, `claude -p --permission-mode acceptEdits`: a directory listed in
+  `.claude/settings.local.json` `permissions.additionalDirectories` was written and the control was
+  refused. A twin whose list was a string was reported as not loaded, and granted nothing. The run
+  was in an untrusted workspace, where Claude Code ignored the committed `.claude/settings.json`
+  list, so whether the two lists combine once a person trusts the workspace is unmeasured. `use`
+  writes the served checkout there.
+- OpenCode 1.19.5, `opencode run`: the grant file holding the worktree path allowed the write, the
+  control was denied, and a pattern naming a missing grant file stopped OpenCode at start, naming the
+  file. `use` and `sync` write the served checkout there.
+- Codex 0.166.0, `codex exec`: Codex reads no machine-local project file; its only per-project user
+  setting is the trust level. `--add-dir <dir>` at start made the worktree writable beside the
+  committed writable roots, and without it the same write was refused. `use` writes nothing for
+  Codex and prints that flag.
+
+Cursor and Grok Build were not installed, so `use` writes nothing for them and says so.
+
 The `[cockpit].guide_cap` limit applies to always-loaded guidance, copied sibling guides included;
 going over it makes `sync`, `check` and `preflight` report `GUIDE_CAP_EXCEEDED` with the measured
 lines and the cap. The same code reports cockpit's region of **AGENTS.md** passing 32768 bytes,

package/docs/safety-and-autonomy.md

@@ -28,7 +28,12 @@ A cockpit command is allowed only when it matches an exact available public comm
 application verifies the executable and working root; the command resolver checks the bounded
 complete argument vector, resolved configuration path, declared services, permitted option roles
 and inspected paths. Internal guard transport and public commands marked unavailable are excluded.
-Declared project build and test commands are allowed only as their exact argument vectors in their
+The command after `session --` or `exec --` is judged as one more invocation, so neither admits
+what the guard would refuse on its own. `exec` runs it in a product container whose files the
+guard cannot see, so a read-only proof about host paths does not carry over: the name-based
+denials (`.env*` and the rest) still apply to it, and it is admitted only by a `[guards] allow`
+rule or as a declared build or test command; otherwise it asks, which Codex and OpenCode turn into
+a denial. Declared project build and test commands are allowed only as their exact argument vectors in their
 own checkout. A wildcard over a command family never grants permission.
 
 ## Hard controls and prompts
@@ -69,7 +74,8 @@ truncating `dd` or `tee` writes, `ln` onto either file, a `chmod` mode that drop
 permission or is copied with `--reference`, a patch delete or move, a Write tool call with empty
 content, and a `>` redirect. Editing the configuration in place stays permitted, including bounded
 `dd conv=notrunc` and `tee` append forms under the normal write checks; the edit takes effect only
-after a human runs `sync`.
+after `sync` runs, and only a person's sync applies an edit that
+[widens what agents may do](#edits-the-guard-has-not-applied).
 
 Writing anywhere under a `.git` directory is a hard denial, because Git configuration chooses
 programs that read-only Git commands run. For the same reason, so is every `git config` form other
@@ -220,19 +226,24 @@ cockpit commands in
 
 | Command | Decision | Why |
 | --- | --- | --- |
-| `npx --no cockpit check --config cockpit.toml`, and likewise `doctor`, `preflight`, `logs --service <service>` and `sync --dry-run` | allowed | They read and report; nothing they do changes a file the guard relies on. |
+| `npx --no cockpit check --config cockpit.toml`, and likewise `doctor`, `preflight`, `ps`, `logs --service <service>`, `stacks`, `stacks prune`, `docs check` and `sync --dry-run` | allowed | They read and report; nothing they do changes a file the guard relies on. |
 | `npx --no -- cockpit --help`, `npx --no cockpit up --help`, and the version | allowed | They print and exit before any command runs. |
-| `npx --no cockpit up --config cockpit.toml`, and likewise `sleep` and `down` | allowed | They act only on the stack cockpit declared and owns; `down` keeps data volumes, and deletes only from the local Docker daemon it fixes at the start of the run. |
+| `npx --no cockpit up --config cockpit.toml`, and likewise `sleep`, `down`, `restart --service <service>` and `rebuild --service <service>` | allowed | They act only on the stack cockpit declared and owns; `down` keeps data volumes, and deletes only from the local Docker daemon it fixes at the start of the run. |
+| `up --profile <profile>` | allowed for a profile in `environment.profiles` that mounts no sibling with `gate = "operator"`, otherwise a prompt | Another profile starts services no person declared for agents, and an operator-gated sibling touches live data or local hardware. |
+| `npx --no cockpit exec --config cockpit.toml --service <service> -- <command>` | allowed when a `[guards] allow` rule or a declared build or test command admits `<command>`, otherwise a prompt | The command runs in a container whose files the guard cannot see, so it is never proven read-only, and the name-based denials still apply to it. |
+| `npx --no cockpit pull --config cockpit.toml` | allowed | It only fetches and fast-forwards, and leaves a modified or diverged checkout as it was. |
+| `npx --no cockpit use <slug> <checkout> --config cockpit.toml`, and `use <slug> --clear` | allowed for a checkout inside a directory the agent may already write, otherwise a prompt | The choice is recorded for this checkout of the cockpit only, so it never widens what the agent can reach. |
 | `npx --no cockpit runtime measure --config cockpit.toml --image <local-image>` | allowed | The probe runs a disposable stack under its own project, removes it, and records the result only in this machine's git-ignored state; `cockpit.toml` never changes. |
-| `npx --no cockpit session --config cockpit.toml -- <command>` | the decision for `<command>` | A session runs its command as the agent could run it directly, so it never admits more. |
+| `npx --no cockpit session --config cockpit.toml -- <command>`, with a `--profile` that `up` admits | the decision for `<command>` | A session runs its command as the agent could run it directly, so it never admits more. |
 | `npx --no cockpit test-run --config cockpit.toml --gate <gate>`, with an optional `--mode` and a `--select <kind>:<value>` whose value does not start with `-` | allowed for a gate `cockpit.toml` declares | The gate runs only the stages a person declared in the reviewed configuration, the trust `up` already has. |
-| `npx --no cockpit work status --config cockpit.toml`, `work accept`, `work check`, `work note`, `work answer`, `work grade`, `work signoff`, `work recover` without `--apply`, `work verify` and `cockpit grade --criteria <file>`, each with its own options | allowed | They report, or take a step [`[work.gates]`](#who-decides) gives the agent; a step it gives a person waits for the digest typed after `--interactive`, which no agent invocation carries. Grading runs in a separate evaluator. |
-| `npx --no cockpit sync --config cockpit.toml`, and `upgrade`, whose sync child writes | allowed where `[autonomy] sync = "agent"`, otherwise a prompt | It regenerates the files the configuration already declares; the guard holds every call after `cockpit.toml` changes until a person syncs, so an agent's sync never publishes an edit of its own. |
+| `npx --no cockpit work status --config cockpit.toml`, `work accept`, `work check`, `work note`, `work decide`, `work answer`, `work acknowledge`, `work grade`, `work signoff`, `work recover` (with or without `--apply`), `work verify` and `cockpit grade --criteria <file>`, each with its own options | allowed | They report, or take a step [`[work.gates]`](#who-decides) gives the agent; a step it gives a person waits for the digest typed after `--interactive`, which no agent invocation carries. Grading runs in a separate evaluator. `work recover --apply` removes a lock only once it has shown the holder gone on the lock's own host and among the containers cockpit labels. |
+| `npx --no cockpit sync --config cockpit.toml`, and `upgrade`, whose sync child writes | allowed where `[autonomy] sync = "agent"`, otherwise a prompt | It regenerates the files the configuration declares; after `cockpit.toml` changes, the guard admits it only when the edit [does not widen](#edits-the-guard-has-not-applied) what agents may do, so an agent's sync never publishes a widening of its own. |
+| `npx --no cockpit tool add <tool> --config cockpit.toml`, with an optional `--dry-run` | allowed | It edits only `[surfaces] tools`, and an added tool [does not widen](#edits-the-guard-has-not-applied) what agents may do, so the agent's sync applies it. |
 | `npx --no cockpit reset --config cockpit.toml --apply` | allowed where `[autonomy] reset = "agent"`, otherwise a prompt | It deletes stack data. |
-| `npx --no cockpit browser drive --config cockpit.toml`, and likewise `screenshot`, with an optional `--role` | allowed where `browser.request_preapproval` is set, otherwise a prompt | They sign in and capture the declared application, so they run unprompted only on the isolated, non-production data the configuration must declare before it can set preapproval. |
-| `work accept`, `work answer` and `work signoff` with `--interactive` | a prompt, which Codex and OpenCode turn into a denial | `--interactive` asks for a person at a terminal to type the digest of what it shows. |
-| `work recover --apply` | a prompt, which Codex and OpenCode turn into a denial | It deletes a lock once a process probe calls its holder dead, and that probe sees only this machine's processes: a holder in a container or on another host that shares the checkout looks dead to it. |
-| `sync --adopt`, `sync --interactive`, `reset --interactive`, `sibling add` and every other command | a prompt, which Codex and OpenCode turn into a denial | They rewrite `cockpit.toml` or a team's own settings, ask for a person, or delete data. |
+| `npx --no cockpit stacks prune --config cockpit.toml --apply` | allowed; the command itself refuses a prune that deletes volumes unless `[autonomy] reset = "agent"` | It removes only stacks whose checkout is gone, which bringing the stack up again recreates, and their data only where a reset could delete it. |
+| `npx --no cockpit browser drive --config cockpit.toml`, and likewise `screenshot`, with an optional `--role` | allowed where `browser.request_preapproval` is on, otherwise a prompt | They sign in and capture the declared application, so they run unprompted only on the isolated, non-production data the configuration declares. Preapproval is on by default exactly when `browser.data` is isolated, not restored and not reaching production, and off otherwise; an explicit `request_preapproval` wins, and `true` on a posture that does not qualify is refused. `drive` also accepts `--fail-on-findings`. |
+| `work accept`, `work answer`, `work acknowledge` and `work signoff` with `--interactive` | a prompt, which Codex and OpenCode turn into a denial | `--interactive` asks for a person at a terminal to type the digest of what it shows. |
+| `sync --adopt`, `sync --interactive`, `reset --interactive`, `stacks prune --interactive`, `sibling add`, `sibling remove`, `tool remove` and every other command | a prompt, which Codex and OpenCode turn into a denial | They widen what agents may do through `cockpit.toml`, rewrite a team's own settings, ask for a person, or delete data. |
 
 A file such a command names, like `--criteria`, is checked as a read:
 the command may quote it in a refusal. A declared instance, a file below `.secrets` or a `.env` or
@@ -339,7 +350,7 @@ templates too, which `cat` in a shell still reads.
 | --- | --- | --- |
 | `sync` | whether the guard lets an agent run a writing `sync`; under `ci` a writing sync runs only where `CI` is set | `agent` |
 | `stale_delete` | whether `sync` removes a file it generated before and no longer generates without a person typing the stale-removal digest | `agent` |
-| `reset` | whether `reset --apply` deletes stack data without a person; otherwise a person approves the preview with `--interactive` | `person` |
+| `reset` | whether `reset --apply`, and a `stacks prune --apply` that deletes volumes, delete stack data without a person; otherwise a person approves the preview with `--interactive` | `person` |
 | `mcp_approve` | `person`: sync enables only the MCP servers whose digest a person recorded in `[mcp.approved]`, and `MCP_NOT_APPROVED` names the rest; `agent`: sync enables every declared server as declared now, which lets an agent start processes outside the guard, because a sibling's MCP source is a file the agent can write and each harness starts an enabled server outside every guard boundary | `person` |
 
 <!-- cockpit:ref path=packages/cockpit/src/guards/policy-pin.ts --> The guard pins the policy: an agent's edit, write or patch that would change `[work]`,
@@ -371,6 +382,39 @@ A local `person` gate is best-effort: cockpit cannot tell a person from a progra
 The only enforced human gate is a required CI job behind a protected environment whose reviewers must
 approve it, such as the [`work verify` job](work-and-browser.md#who-passes-each-gate).
 
+### Edits the guard has not applied
+
+<!-- cockpit:ref path=packages/cockpit/src/guards/policy-change.ts --> Once `cockpit.toml` differs
+from the configuration the guards were generated from, the guard loads both, the earlier from the
+copy sync keeps in `.cockpit/local/guard-config`, and compares them with defaults applied. An edit that does
+not widen what agents may do holds every tool call except `cockpit sync` and `cockpit check`, which
+the agent may run under the rules above, and the hold says so (`GUARD_CONFIG_UNSYNCED`). Any other
+edit holds every call, that sync included, until a person runs `sync` in a terminal, and the hold
+names each field that widens.
+
+An edit does not widen only when every difference is one of these:
+
+- descriptive or host-only fields: a sibling's `purpose`, `host_reason` and `rebuild_inputs`,
+  `cockpit.guide_cap`, `[ports]`, `environment.entrypoint_derivatives`, `environment.machine` and
+  `docs.living`;
+- added agent tools, `unconfirmed` answers and sibling operator gates;
+- removed Compose files, Compose profiles and resettable volumes, and an install policy that admits no
+  command it did not.
+
+Every other difference widens. That includes any change, in either direction, to `[guards]`,
+`[work]`, `[autonomy]`, `[mcp]`, `[testing]` (whose stages `test-run` runs unprompted) and `[browser]`;
+a new sibling, wherever its directory is; a sibling's changed `dir`, `guides` (sync copies each guide
+into the root `AGENTS.md`), environment files or derived MCP sources; and every command field, such
+as `environment.seed`. A field the classification has no rule for widens too, so a field added to
+the schema is a person's decision until a rule says otherwise. A missing or mismatched
+copy of the generated configuration cannot show an edit safe, so it holds as a widening edit does.
+`check` reports the same classification: `GUARD_CONFIG_UNSYNCED` as a warning, `GUARD_CONFIG_WIDENED`
+as an error naming the fields.
+
+Whoever runs it, sync refuses a guide that is, or links to, a `.env` or `.env.*` file, a file below a
+`.secrets` directory or a declared environment instance (`PROJECTION_GUIDE_SECRET`), so a guide never
+copies what the guard keeps from agents into the root `AGENTS.md`.
+
 ## Native adapter behavior
 
 The [transport and adapter owner](https://github.com/b0dea/cockpit/blob/main/packages/cockpit/src/guards/harness-adapter.ts) translates a

package/docs/troubleshooting.md

@@ -121,7 +121,8 @@ the harness enforces anything.
 ### MCP and restrictions
 
 For `MCP_INPUT_INVALID` or `MCP_DECLARATION_INVALID`, correct the declaration, digest,
-same-name environment reference, or confined working directory named by the message.
+same-name environment reference, confined working directory, or remote server URL, header
+reference or `headersHelper` named by the message.
 `MCP_COMMAND_CONFLICT` means two sources give one server name different commands; make them agree or give them distinct names. `MCP_NOT_APPROVED` leaves a declared
 server disabled because `[mcp.approved]` has no entry for it, or its declaration changed since it
 was approved; a person, only after reviewing its command, arguments, working directory, environment
@@ -129,6 +130,9 @@ names and sources, sets its name to the sha256 in the message under `[mcp.approv
 While `[autonomy] mcp_approve` is `person`, the default, the guard refuses an agent's edit of `[mcp]`. `MCP_APPROVAL_UNKNOWN` means the allowlist names no
 declaration. `MCP_EXECUTABLE_UNAVAILABLE` comes from the generated wrapper when its declared
 executable is absent or not executable; restore that executable rather than changing the wrapper.
+`MCP_TRANSPORT_UNAVAILABLE` names a remote server left out of the tools that cannot carry its
+credential, such as OpenCode for a server with a `headersHelper`; see
+[Remote servers](harness-surfaces.md#remote-servers) for what each tool can carry.
 
 For `RESTRICTION_INPUT_INVALID`, `RESTRICTION_ADAPTER_INVALID`, `RESTRICTION_EVENT_UNADAPTED`,
 `RESTRICTION_TEMPLATE_INVALID` or `RESTRICTION_OUTPUT_LIMIT`, correct the named guard policy,
@@ -202,7 +206,17 @@ progress per checkout. A state diagnostic's target names the exact directory.
 
 These records are how cockpit knows which containers and ports a stack owns. Do not edit them by
 hand, and do not delete them while the stack runs: its containers would keep running with nothing
-that knows about them. To clear one cockpit's state:
+that knows about them.
+
+A stack whose worktree was deleted, and state folders an earlier cockpit build left, are removed by
+`stacks prune`, which previews by default and removes only what no checkout can reach; see
+[List and prune stacks across the machine](environment.md#list-and-prune-stacks-across-the-machine).
+`doctor` warns with `STACKS_ORPHANED` when it finds such a stack, and with `STATE_RECORD_MALFORMED`
+for another cockpit's state folder this version cannot read; `up` and `sleep` ignore that folder's
+port leases.
+
+`stacks prune` keeps a stack whose checkout still exists. To clear the state of a checkout you still
+have:
 
 1. Stop the stack and release its claims from the cockpit directory:
    `./node_modules/.bin/cockpit down --config cockpit.toml`.
@@ -212,10 +226,7 @@ that knows about them. To clear one cockpit's state:
    `rm -rf "$HOME/Library/Application Support/cockpit/state/v1/cockpits/cockpit_duo_<hash>"`.
 
 When this cockpit's own state cannot be read, runtime commands refuse with
-`STATE_RECORD_MALFORMED` or `STATE_FORMAT_UNSUPPORTED` until you clear it. Unreadable state of
-another cockpit, such as a directory left by an earlier cockpit build, does not stop you: `up` and
-`sleep` ignore its port leases, and only `doctor` warns with `STATE_RECORD_MALFORMED`, naming that
-directory and the `rm -rf` command. Remove it with the same steps once no cockpit uses it.
+`STATE_RECORD_MALFORMED` or `STATE_FORMAT_UNSUPPORTED` until you clear it this way.
 
 <!-- cockpit:diagnostic-index:begin -->
 ## Codes with a fixed remedy
@@ -226,6 +237,7 @@ Every diagnostic message names what failed and how to fix it. These codes always
 | --- | --- |
 | `AUTONOMY_CI_ONLY` | push the change and let the CI job run the command, or have a person change the field in cockpit.toml and accept the change at sync |
 | `AUTONOMY_PERSON_REQUIRED` | a person runs the same command with --interactive in a terminal outside CI, or a person changes the field in cockpit.toml and accepts the change at sync |
+| `BROWSER_ROUTE_FINDINGS` | this run asked for a clean route (--fail-on-findings). Read result.receipt.surfaces[].diagnostics, including excerpt.messages where present: fix the product for each console error, uncaught page error and failed request that matters, then rerun npx --no cockpit browser drive --config <your cockpit.toml> --route <name> --fail-on-findings; third-party traffic never counts |
 | `CLAIM_CO_TENANT` | [see above](#common-refusal-guidance) |
 | `COCKPIT_LAUNCHER_UNPROVEN` | run cockpit as ./node_modules/.bin/cockpit <command> --config <your cockpit.toml> from the cockpit root, or remove what stops npx from proving it: a .npmrc in the cockpit root, a bin or directories.bin in its package.json, or a node_modules/.bin/cockpit that npm install did not link to the installed package |
 | `COCKPIT_REVISION_UNSTAMPED` | install a released @b00dea/cockpit when the resolved data must name the exact cockpit source commit |
@@ -233,7 +245,13 @@ Every diagnostic message names what failed and how to fix it. These codes always
 | `COMPOSE_FILE_UNREADABLE` | make environment.compose_files name a readable Compose file inside the cockpit root, then run npx --no cockpit check --config <your cockpit.toml> |
 | `CONFIG_ENCODING_INVALID` | save the configuration as UTF-8, then retry |
 | `DATA_SEED_UNAVAILABLE` | make sure the Docker daemon this stack runs on answers docker volume ls, then rerun npx --no cockpit up --config <your cockpit.toml> |
-| `DECLARATION_UNCONFIRMED` | confirm each value with whoever owns the product and correct it in cockpit.toml if it is wrong, delete each confirmed entry from unconfirmed, then run npx --no cockpit sync --config <your cockpit.toml> |
+| `DECISION_INDEX_ENTRY_MISSING` | correct the link to the record's current file name, or remove the entry if the record was deleted on purpose |
+| `DECISION_LINK_UNRESOLVED` | correct the number or link to name an existing record, or restore the record it names |
+| `DECISION_NUMBER_REUSED` | renumber the later record to the next free number, then update the index and every supersedes line that cites it |
+| `DECISION_UNINDEXED` | add a line linking the record to the decision index |
+| `DOCS_NOT_DECLARED` | add a [docs] table to cockpit.toml: living = ["README.md", "docs/**/*.md"] lists the documents that must stay true, and the optional decisions = "docs/adr" and decisions_index = "docs/adr/README.md" name the decision records and their index; then rerun npx --no cockpit docs check --config <your cockpit.toml> |
+| `DOCS_REFERENCE_REMOVED` | cite the path that replaced it (a rename is named in the message), or rewrite or delete the sentence if what it described is gone; then rerun npx --no cockpit docs check --config <your cockpit.toml> |
+| `DOCS_TARGET_REMOVED` | cite the target or command that replaced it, or rewrite or delete the sentence if the step is gone; then rerun npx --no cockpit docs check --config <your cockpit.toml> |
 | `DOCUMENT_ESTATE_TOPOLOGY_MISMATCH` | declare one sibling for each repository the message says init observed, with that slug and dir, and no other; add any other repository after init with npx --no cockpit sibling add <slug> --config <your cockpit.toml> |
 | `DOCUMENT_GUARD_HOSTS_NONE` | list the hosts in guards.hosted_db_hosts and guards.vendor_endpoint_hosts and run npx --no cockpit sync --config <your cockpit.toml> once a non-local environment exists |
 | `DOCUMENT_RUNTIME_NOT_DECLARED` | once a product runs, declare environment.compose_files and run npx --no cockpit sync --config <your cockpit.toml> |
@@ -257,9 +275,11 @@ Every diagnostic message names what failed and how to fix it. These codes always
 | `LOGS_TRUNCATED` | lower --tail to the number of recent records you need, or read the older records from the container runtime directly |
 | `MCP_APPROVAL_UNKNOWN` | [see above](#mcp-and-restrictions) |
 | `MCP_COMMAND_CONFLICT` | [see above](#mcp-and-restrictions) |
+| `MCP_COMMAND_UNRESOLVED` | install the command or correct it in the sibling's MCP declaration, then run npx --no cockpit sync --config <your cockpit.toml>; a changed declaration needs a person to approve its new sha256 under [mcp.approved] |
 | `MCP_DECLARATION_INVALID` | [see above](#mcp-and-restrictions) |
 | `MCP_INPUT_INVALID` | [see above](#mcp-and-restrictions) |
 | `MCP_NOT_APPROVED` | [see above](#mcp-and-restrictions) |
+| `MCP_TRANSPORT_UNAVAILABLE` | [see above](#mcp-and-restrictions) |
 | `OUTPUT_EXISTS` | choose a new path; replacement requires a future explicit option |
 | `PORT_FAMILY_COLLISION` | [see above](#common-refusal-guidance) |
 | `PORT_LEASE_EXHAUSTED` | [see above](#common-refusal-guidance) |
@@ -313,6 +333,7 @@ Every diagnostic message names what failed and how to fix it. These codes always
 | `SKILL_RENDER_INVENTORY_INVALID` | [see above](#sibling-projection-and-skills) |
 | `SKILL_STANDING_COST_EXCEEDED` | [see above](#sibling-projection-and-skills) |
 | `SKILL_TOOL_EQUIVALENCE_MISSING` | [see above](#sibling-projection-and-skills) |
+| `STACKS_ORPHANED` | [see above](#clear-cockpit-state) |
 | `STATE_FORMAT_UNSUPPORTED` | [see above](#clear-cockpit-state) |
 | `STATE_RECORD_MALFORMED` | [see above](#clear-cockpit-state) |
 | `SURFACE_ADOPTION_REFUSED` | [see above](#merge-ownership-and-generation) |
@@ -357,5 +378,5 @@ Every diagnostic message names what failed and how to fix it. These codes always
 | `UPGRADE_VERSION_INVALID` | give a full version such as 1.2.3, not a range or tag |
 | `WORK_CHECK_FAILED` | read result.results: fix the product for a check that failed, make one that did not run runnable from the cockpit root, then rerun npx --no cockpit work check --config <your cockpit.toml> --work-order <id> |
 | `WORK_PERSON_REQUIRED` | stop and ask a person to run the same command with --interactive in a terminal outside CI, read what it shows, and type the digest; never type it for them |
-| `WORK_VERIFY_FAILED` | for an order changed since acceptance, run npx --no cockpit work accept --config <your cockpit.toml> --work-order <id> or revert the change; for a done order without a passing grade, regrade it with work grade |
+| `WORK_VERIFY_FAILED` | for an order changed since acceptance, run npx --no cockpit work accept --config <your cockpit.toml> --work-order <id> or revert the change; for a done order without a passing grade, regrade it with work grade; for a decision record that is missing or no longer cites its order, restore it from git or put back its "Work order: <id>" line |
 <!-- cockpit:diagnostic-index:end -->

package/docs/tutorial.md

@@ -145,13 +145,14 @@ with data, add `resettable_volumes` and `seed` as
 
 ## Bring the stack up
 
-With Docker running, measure the runtime once with a local image, then start the stack, run one
-command against it, and remove it:
+With Docker running, measure the runtime once with a local image, then start the stack, list its
+services, run one command against it, and remove it:
 
 ```sh
 docker pull node:22-alpine
 ./node_modules/.bin/cockpit runtime measure --config cockpit.toml --image node:22-alpine
 ./node_modules/.bin/cockpit up --config cockpit.toml
+./node_modules/.bin/cockpit ps --config cockpit.toml
 ./node_modules/.bin/cockpit session --config cockpit.toml -- sh -c 'curl -fsS "http://127.0.0.1:$API_HOST_PORT/health"'
 ./node_modules/.bin/cockpit down --config cockpit.toml
 ```