@b00dea/cockpit 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,375 @@
+# @b00dea/cockpit
+
+What changed in each release of cockpit, newest first, for someone deciding whether to upgrade:
+what breaks, what to do about it, and what is new. Changesets writes each entry from the
+changesets merged since the previous release. An entry that needs more than `cockpit sync` ends
+with a line starting `Upgrade:`; the [changeset guide](../../.changeset/README.md) defines that
+convention.
+
+Versions follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html). The public surface a
+major version protects is the CLI's commands and flags, the <!-- cockpit:ref consumer=cockpit.toml --> `cockpit.toml` schema, the generated
+file layout, and the overlay contract. Deprecation and migration rules are in the
+[release policy](../../docs/release-policy.md).
+
+<!-- Changesets inserts each release above the first version heading, so this heading keeps the introduction above every release. -->
+
+## 0.1.0
+
+### Minor Changes
+
+- 0067955: Initial public release.
+  
+  - One `cockpit.toml` is the policy and the product declaration: sibling repositories, ports, guards, MCP servers, autonomy and work. `cockpit sibling add|remove` edits the repository list and `cockpit tool add|remove` edits `[surfaces] tools`, which defaults to Claude Code, Codex CLI and OpenCode.
+  - `cockpit sync` writes the matching instructions, skills, subagents, hooks, permissions and MCP entries for each listed tool, with `--dry-run` previews, and `cockpit check` fails when a generated file no longer matches, locally or in the `cockpit-check` GitHub Action. `sync --adopt <path>` moves a team's existing agent settings file into cockpit and merges it with the generated version.
+  - One guard policy refuses pushes to protected branches, reads and edits of declared environment files and secrets directories, and commands against declared hosted databases or vendor hosts. `[[guards.deny]]` and `[[guards.allow]]` add your own command rules. The hook is installed for Claude Code, Codex CLI and OpenCode, fails closed, and also denies agent writes to `.npmrc` and to cockpit's own policy and records. Codex runs the hook only after a person trusts it once per machine; `doctor` and `check` report `CODEX_HOOK_UNTRUSTED` until then. `cockpit selftest` checks that each tool enforces the generated controls, and the capability matrix records dated measurements.
+  - Sibling repositories' guides are copied into the root instructions, and the Claude Code and Codex hooks run `cockpit check` as a session starts.
+  - `cockpit init` starts in the repository it runs in: a single product repository gets an in-repo cockpit, every listed tool gets the `cockpit-setup` skill, and the interview marks every value it inferred or defaulted. `init` writes a commented `[work.gates]` and `[autonomy]` block, and `--registry` turns an existing shell-script setup into a draft. `init --scaffold-compose` writes one plain `compose.yml` for a small app, once.
+  - cockpit runs your own Compose files and generates none. `setup`, `up`, `session`, `sleep`, `down`, `reset`, `preflight`, `doctor` and `logs` run the stack on your live checkouts, with port leases and holders so one agent cannot stop another agent's stack. `environment.seed` with `resettable_volumes` fills and refills the data, and `reset` needs a person by default. `down` and `reset` use only a local Docker context, and `cockpit runtime measure` records the local runtime for this machine only.
+  - `[autonomy]` and `[work.gates]` say who may pass each step. Everything defaults to `agent` except `[autonomy] reset` and `mcp_approve`, which default to `person`. `check` and `doctor` report a policy weakening nobody has confirmed, and the guard denies an agent's edit of the policy.
+  - Each repository's tracked `.env.schema` is validated with Varlock when it is installed, without reading values. MCP servers are enabled only for the digest recorded under `[mcp.approved]`.
+  - Work orders are `workorders/<id>.md` with YAML front-matter. `[work] grading` is `independent` (an evaluator in the first usable of `work.evaluators`, any of Claude Code, Codex CLI or OpenCode, reruns the checks and grades each criterion), `checks` or `self`. `cockpit grade --criteria <file>` grades uncommitted work with no order, and `work verify` checks the records in CI.
+  - Declared test stages and gates run with `cockpit test-run`, and only a complete passing gate reports PASS.
+  - `cockpit browser drive` and `browser screenshot` visit the application's declared routes with a local browser. `browser.endpoint` may name a loopback browser service from your own Compose file, which publishes the Playwright MCP declaration and the `cockpit-browser` skill. cockpit runs no browser service and no debugger.
+  - `cockpit upgrade [<version>] [--dry-run]` moves the exact pin and re-runs `sync`.
+  - Teams share one cockpit: the root `package.json` pins the exact cockpit version, `check` refuses a different running version, and cockpit manages its own block in `.gitignore`.
+  - Diagnostics name what failed, why it matters and the fix. The package ships the user guide under `docs/` and skills that tell agents how to set up, explain, fix and work in a cockpit; install the adoption skill with `npx skills add b0dea/cockpit --skill adopt-cockpit`.
+  - Runs on macOS and Linux. Native Windows is refused at startup; WSL2 should behave like Linux but is untested.
+
+### Patch Changes
+
+- be5adb5: Every `[autonomy]` and `[work.gates]` decision now defaults to `agent` except `reset` and `mcp_approve`, which default to `person`. The `[autonomy] preset` key is removed, and `cockpit init` writes the defaults as a commented block so one can be flipped to `person`.
+- bc8fa52: Browser screenshots can no longer be committed by accident, and the first screenshot no longer needs the artifact directory to exist.
+  
+  - `cockpit sync` adds every `environment.generated_host_paths` entry, which includes the browser artifact roots such as `.browser/cli`, to the managed `.gitignore` block.
+  - The browser screenshot command creates its artifact root, including a missing parent such as `.browser`, before writing into it.
+  - When no `browser.harnesses` row is at a measured version, the work application's refusal names the declared and measured harness versions and the `sync` command to run after fixing `cockpit.toml`.
+- 3cd8bbf: `cockpit browser debugger` is removed: it refused in every configuration because the headed browser runner it needed is no longer rendered. `browser drive` and `browser screenshot` are unchanged.
+- cfb2f97: `browser.endpoint` is no longer refused outright: it must be a loopback `ws://` address whose port exactly one service in `environment.compose_files` publishes on loopback, otherwise sync refuses with `GENERATED_BROWSER_ENDPOINT_UNPUBLISHED`.
+- ffb5ba5: A `browser.endpoint` published by the project's own Compose service now publishes the Playwright MCP server and the `cockpit-browser` skill at sync, without a cockpit port lease.
+- 525477b: Removed the browser native-transport receipt validator and the probe specifications it consumed: no command ran or recorded them, and a valid receipt left every transport `human_needed`, so the check changed nothing. The capability matrix now lists browser native transports under "Without a measurement", and the browser reference no longer mentions a record validator.
+- d075210: Browser operations reach only what they should.
+  
+  - Browser operations block requests to loopback and resolver-mapped hosts outside the application origin. Redirects that the browser follows are not routed, so they are not blocked.
+  - `up` and `sync` name an unparseable browser project `package.json` or lockfile with the line and column, and no longer quote its contents.
+- 2ec827b: `[browser]` drops the fields only the removed browser runner read: `images.runner`, `artifacts.runner`, `artifacts.debugger` and `headed`. The runner script is no longer shipped, and `cockpit browser debugger` refuses with the reason, since nothing can prepare a headed debugger. `browser drive` and `browser screenshot` keep working through the local project client.
+- 1f884bc: The harness registry no longer records Claude Code, Codex and OpenCode as awaiting a native paired probe dated before their guard firing and instruction loading were measured; what it records as open for them is the person's review of the rendered skills, which the capability matrix shows.
+- 01d2003: `cockpit check` now fails with `POLICY_WEAKENING_UNCONFIRMED` while `[work]`, `[work.gates]` or `[autonomy]` in `cockpit.toml` is weaker than the policy the last sync recorded, instead of leaving the weakening to surface only at the next sync.
+- 6fdd9f4: `check` fails with `GENERATED_HOST_PATH_UNMOUNTED` for an `environment.generated_host_paths` entry that no service bind-mounts, naming the entry and how to fix it. In compose-first mode `up` already refused such a stack, and now `check` says so first. An entry inside a bound directory, such as a sibling mounted whole, reaches the container through that bind and counts as mounted; compose-first `up` no longer refuses it either.
+- b4e7209: The generated `.claude/settings.json` now allows, by prefix, the cockpit commands the shipped skills tell an agent to run and the guard admits, such as `test-run`, `check` and `doctor`. Claude Code's default mode previously refused them in a headless session. Person-only commands such as `sync`, `down` and `work accept` still prompt, the guard hook still decides first, and Claude Code applies the rules only once a person has trusted the workspace.
+  
+  The shipped Fix procedure is now a direct fix: run the declared gate before and after the change, with no intake or source audit. The guides say which cockpit commands a Codex user runs outside Codex's sandbox, that the person commits the cockpit repository, and use `--target <tool>` instead of one tool's target.
+  
+  The vendor-specific identity-provider starter is no longer written into every cockpit; its two general lessons (confirm the roles the provider instance exposes, sign in through the provider's own test helper without a second token helper) are now in the test-data reference.
+- 616736f: Several runtime and lifecycle reports now say what actually happened.
+  
+  - When Docker Engine or Docker Compose prints a version with no numeric X.Y.Z core, `up` and `runtime measure` say which tool printed what, and the fix is to install a release that prints one. The fix used to be "start the configured container runtime", which was already running.
+  - When `up` refuses because a running stack's declaration changed, the message names the file that changed (for example `compose.yml`, or `[ports]` in `cockpit.toml`) instead of always naming `cockpit.toml`.
+  - When a long-running command keeps only the tail of its output, the tail now starts at a whole UTF-8 character, so the first character is no longer garbled.
+  - `logs` now works when Docker Compose prints a vendor suffix such as `2.29.7-desktop.1`. It used to refuse every read on such a runtime.
+  - A file listed in `environment.generated_host_paths` is now ignored in the managed `.gitignore` block, as a directory there already was.
+- 3bf2315: Running `dist/cli.js` through a symlinked package directory (npm link, workspaces) now runs the command instead of exiting 0 without output.
+- 57a2ad7: The Codex `writable_roots` that `sync` writes for repositories beside the cockpit no longer depend on the directory you run it from. Run from inside a sibling repository, `sync` used to write a root that pointed at the wrong place, and `check` then reported `.codex/config.toml` as drifted depending on where it ran.
+- f416f24: cockpit runs your own Compose files and no longer generates one.
+  
+  - `[environment.generated]` and `sibling[].derives.generated` are gone, and with them the generated services, dependency volumes and installs, vendor stubs and their TLS probes, the `empty`, `seeded` and `restored` data modes, restore rewrites, persona outputs and `docs/cockpit/environment-decisions.md`. So are the rendered browser runner and its fields: `browser.resources`, `browser.runner_health_measurement` and `browser.images.runner.architectures` are unknown keys. A `cockpit.toml` that still sets one is refused; declare `environment.compose_files` and keep the stack in plain Compose. The new Compose patterns guide shows a vendor stub, a TLS front end and a data restore.
+  - `environment.seed = { argv = [...], timeout_seconds = N }`, beside `environment.resettable_volumes`, is the command `up` runs once the stack is healthy, and again whenever one of those volumes is newer than the last successful seed, such as after `reset`. A seed that fails refuses with `DATA_SEED_FAILED`, leaves the stack up, and runs again on the next `up`. Editing it leaves a running stack alone.
+  - `npx --no cockpit init <cockpit root> --scaffold-compose <app dir> --port <port>` writes a starting `compose.yml` for a small app once, with an optional `--with postgres,redis`, and never replaces an existing Compose file.
+  - A compose-first `up` now refuses with `MACHINE_MEMORY_BELOW_FLOOR`, `MACHINE_CPU_BELOW_FLOOR` or `MACHINE_DISK_BELOW_FLOOR` before starting anything on a machine below the declared `[environment.machine]` floor. Only a generated stack used to be held to it.
+  - `examples/synthetic` is gone; the tutorial walks through `examples/compose-first`, and `examples/minimal` runs its own `compose.yml`.
+- da3debb: Refusals from `sibling add`, `sibling remove` and `sync --adopt` when they cannot edit `cockpit.toml` safely now carry a fix: wait for another edit to finish and run the same command again, correct the option the message names, or make the change by hand and preview it with `sync --dry-run`. The printed `--config` path in a `sibling` fix is the one the command was given, and the JSON invocation record names it.
+- 9e4c9af: Sync reads `cockpit.toml` through the ordinary anchored file read, and its unreadable-file refusal is now `GENERATED_CONFIG_SOURCE_UNAVAILABLE`.
+- a6b9a2c: A new Configuration essentials page covers the `cockpit.toml` tables a typical cockpit sets, each with a minimal snippet and a link to its full reference entry.
+  
+  The configuration reference is now one table per TOML table, listing every key with its type, default and constraints. Tables that recur, such as probes and provenance, are listed once and linked, and the JSON Schema is linked instead of printed, so the page is about a tenth of its former length.
+- b65f142: Every `cockpit.toml` field now has an effect, or it is gone.
+  
+  - Removed `cockpit.guide`, which nothing read. A configuration that still sets it is refused as an unknown key, so delete the line.
+  - A sibling guide declared under `guides` that does not exist, other than the default `CLAUDE.md` and `AGENTS.md`, now fails `sync` and `check` with `SIBLING_GUIDE_MISSING`. It used to link nothing and say nothing.
+  - Browser driver versions accept a semantic-version pre-release, such as the Playwright alpha an MCP image bundles. The runner image must still match `browser.project.driver_version` exactly; the MCP image must share its major.minor.
+- f7bbe8b: Every refusal to load `cockpit.toml` now carries a fix: a missing file names `--config` and `cockpit init`, an unreadable, oversized, non-UTF-8 or unparseable file says what to repair, and a schema mismatch points at the configuration reference. `[testing].native_hooks` may be left out and defaults to `{ install = "inspect" }`, as documented; a declared `native_hook_policy` still needs `native_hooks = { install = "explicit-native" }` beside it.
+- 038d0aa: When `work.evaluators` is not set, `work grade` and `cockpit grade` now try the other listed agent tool first and the tool running the command last, detected from `CLAUDECODE` or `CODEX_THREAD_ID`. A declared list is used as written.
+  
+  `work grade` and `grade --criteria` accept `--evaluator <tool>` to grade one run with only that tool, with no fallback.
+- 3669b51: `doctor` and `init` now say what the project still lacks for cockpit to work, before the first `up` and without guessing.
+  
+  - Before the first bring-up, while the stack sleeps, and (in `doctor`) for a cockpit that declares no runtime, `doctor` and `preflight` run every check that needs no running stack (Git state, sibling presence, the machine floor, the runtime measurement, the env schema, the generated surfaces) and report the rest as not applicable. `STATE_UNSEEDED`, `STACK_NOT_RUNNING` or `ENVIRONMENT_NOT_DECLARED` is listed first instead of replacing every check, and `preflight` still never passes in those states. A container runtime that is missing then is reported as `RUNTIME_UNAVAILABLE` with a fix.
+  - `doctor --json` carries `result.readiness`, and the human report has one line per gap. It groups the reported diagnostics under the prerequisites cockpit depends on, each with why cockpit needs it and whether it is required (refused by the command that needs it) or recommended. Every `init` stop carries the same `result.readiness`, the preview included.
+  - New warnings: `COCKPIT_NOT_INSTALLED` when cockpit is not installed in the cockpit root or the guard hook runs a copy outside it (every new cockpit, because `init` runs from a temporary install); `SIBLING_REMOTE_UNRECORDED` when a sibling is its own Git repository but `cockpit.toml` records no remote, so a teammate's `setup` cannot obtain it; `SECRET_FILE_TRACKED` when a repository commits a `.env`-style file, named by path only and never read. `init` also warns `SETUP_PATH_TYPE_INVALID` when the cockpit root is not in a Git working tree.
+  - `check` and `sync` report a declared sibling that is absent as `SIBLING_MISSING`, with how to obtain it, instead of `GENERATED_SIBLING_ROOT_INVALID` with a raw `realpath ENOENT`.
+  - The setup skill's onboarding procedure walks the human through each readiness gap and asks before touching a product repository. The documented `init` stops now include `STATE_UNSEEDED`.
+- 3bfa530: `doctor` now exits 2 when `cockpit.toml` is missing or invalid, instead of exiting 0 with an unavailable verdict. Its human output is a short report, one line per area with the commands that show the detail, instead of thousands of lines, and `--json` reports whether the generated files are current (`freshness.local` holds the check's kind, status and diagnostics) instead of embedding the complete check result.
+- d3609e5: `doctor` warns `COCKPIT_LAUNCHER_UNPROVEN` when the guard cannot prove that `npx --no cockpit` run in the cockpit root starts the installed cockpit (a root `.npmrc`, a `bin` or `directories.bin` in the root `package.json`, or a `node_modules/.bin/cockpit` that is not npm's link), so every printed `npx` command would prompt, and Codex and OpenCode would refuse it. It runs the guard's own check and names `./node_modules/.bin/cockpit <command> --config cockpit.toml` when that spelling is still proven.
+- 23e1e36: `doctor` reports the refusal `check` gives when it cannot check the generated publication (a published port outside `ports.bases`, for one), with its fix, instead of the surface-evidence findings that refusal makes unavailable.
+- b7f0fde: `doctor` now reports a policy that `cockpit.toml` sets weaker than the one the last sync recorded, as `check` already does.
+- fd3ad2f: `doctor` warns with `GUARD_SEARCH_PATH_RELATIVE` when the `PATH` it runs with holds a relative or empty entry, which makes the guard ask before every agent command, and names the entry; readiness lists it as `harness-path-absolute`.
+- bbac384: The guard now denies reading, writing, removing, staging or linking any `.env` or `.env.*` file at any depth, declared or not; before, an agent's edit of an undeclared `.env` was allowed and `cat .env` only prompted. `.env.example`, `.env.sample`, `.env.template`, `.env.schema` and declared templates stay readable and writable, and recursive searches and Git content commands now treat those names as documentation too. The refusal points to `varlock run -- <cmd>` or the `.env.schema`. Claude Code's generated `Read` deny rules now cover `.env` and `.env.*` as well; because Claude applies a deny before any allow, its own Read, Grep and Glob tools also refuse the documentation names, which a shell `cat` still reads.
+- ac05031: When the generated files no longer match `cockpit.toml`, for example after upgrading cockpit, `down` and `reset` still refuse rather than hand Compose a file cockpit did not render from the current declaration, but the refusal now says nothing was stopped and prints the whole recovery: run `sync`, then `down`.
+- 6477cf3: The published `cockpit.schema.json` now holds `[mcp.approved]` server names, `[ports.bases]` names and generated `port_defaults` names to the same key patterns the loader enforces, so an editor flags a key `check` would refuse.
+- 606f5d1: `grade --criteria` accepts an absolute path inside the repository, and refuses a path outside it with a message naming `--criteria` and the rule.
+- 1cbc7ab: The guard now admits the read-only idioms agents use constantly, which headless Codex and OpenCode previously turned into refusals, and every remaining refusal names the command and says what to do instead.
+  
+  - `cd ./api && <command>` and `cd ./api; <command>` judge the command from the directory it runs in, under the same rules. After `;` or `||` a failed `cd` leaves the shell where it was, so the command is judged from both directories. A bare `cd api` is still refused, because both shells resolve it through `CDPATH` first; the refusal says to write `cd ./api`.
+  - `echo` and `printf` without options are read-only, and `$?` in their arguments is the previous exit status, not dynamic command construction. A `$?` in any argument that could name a path still asks.
+  - `sed -n <range>p <file>` reads like `cat`; any other sed command still asks.
+  - `git rev-parse` and `git branch` with listing flags (`-v`, `-vv`, `-a`, `-r`, `--show-current`) are read-only, and `@{u}`, `HEAD@{1}` and `HEAD~1` are Git revisions, not brace or tilde expansion.
+  - `git add <paths>` naming a guard control such as `.claude/settings.json` now asks like any other staging instead of being refused outright: staging writes the index, not the file. Committing still requires a person.
+  - `git add -A`, `git add .` or a directory that contains `env/.secrets` or a declared environment instance is still refused, and the refusal now says to stage the changed files by name.
+  - A command the guard does not admit now names itself, and says how to proceed: a person approves it or runs it in a terminal, tests run through `npx --no cockpit test-run`, and `[guards] allow` admits a command for good. A read outside the configured roots says so.
+- 3ed866f: The guard now admits the commands the shipped skills and guides tell an agent to run, as exact profiles: `test-run` on a declared gate, the `work` subcommands without `--interactive`, `cockpit grade --criteria`, the preview of `work recover`, and, where `browser.request_preapproval` is set, `browser drive` and `browser screenshot`. A file these commands name, such as `--criteria`, is checked as a read, so a declared instance or `.secrets` file is denied and an undeclared `.env` prompts. Before, every one of them prompted, and Codex and OpenCode refused them. `--interactive`, `work recover --apply` and `browser debugger` still need a person, and the safety page says why for each.
+- 7ef0e26: The guard asks Git what an `rg` search and a Git command would print, instead of refusing too much or too little.
+  
+  - A plain `rg needle` at the root of a project with a large ignored `node_modules` asked, and Codex and OpenCode turned that into a denial. The guard now asks Git which files the repository does not ignore, as ripgrep skips the rest, so a gitignored `.env` or dependency tree no longer blocks it; an untracked `.env.local` that is not ignored still asks, and `grep -r` still walks every file.
+  - `git diff`, `git show` and `git log -p` printed a tracked `.env*` file, secrets file or declared instance without a prompt. They now ask while the repository's index holds one, unless limited with `-- <path>` to paths that hold none.
+- d86a9e2: The guard now admits `jq` reading files as read-only, like `cat`, unless the filter reads the environment or a module, or the command writes.
+- a5a1d6a: When the guard cannot inspect a path because the filesystem refused, its refusal now names the system error instead of only saying inspection failed.
+- e414443: The guard lets agents read declared templates and search code, and protects the MCP wrapper scripts.
+  
+  - A sibling's declared environment `template` (such as `.env.example`) is readable. Undeclared `.env*` files still need approval, and declared instances are still denied.
+  - A recursive search (`rg`, `grep -r`, OpenCode's grep) over a sibling or the cockpit root is allowed when no declared instance or `env/.secrets` exists below it. When one does, the reason names it so the agent can search a narrower path; Codex and OpenCode used to deny every such search with a generic reason.
+  - Writing, removing or replacing a generated MCP wrapper script under `.cockpit/mcp/` is a hard denial, like the other guard controls.
+- c29ebf7: The guard answers a default `rg` search faster in a checkout with large ignored directories such as `node_modules`, and stops asking about files ripgrep never reads.
+  
+  - Git now names each ignored directory once instead of listing everything inside it, so the check no longer grows with the size of `node_modules`. Its Git queries for one search, and for several searched paths, run together.
+  - An `.ignore` or `.rgignore` file or a `.jj` directory inside an ignored directory no longer makes the guard ask: ripgrep does not enter that directory. The same entries in a directory ripgrep does enter still make it ask.
+  - A tree or repository can hold up to 1024 environment files before the guard stops naming them, up from 256. Above that bound it still asks.
+- 019c0ad: The guard no longer lets a recursive search or a shadowed command name read secrets without a prompt.
+  
+  - A recursive search (`rg`, `grep -r`, OpenCode's grep) is allowed only when a bounded walk of its tree finds no `.secrets` directory and no `.env*` file other than a declared template, and every other command in the call is read-only, so none can write one first. `grep -rn API_KEY .` used to print an undeclared sibling `.env.local` that `cat` would have stopped at. A tree too large to walk needs approval; the reason names what was found, so the agent can search a narrower path.
+  - `rg -g`, `--glob` and `--iglob` are read-only only as `!` exclusions, because any other glob overrides ripgrep's hidden and ignore filters.
+  - While the agent harness's `PATH` holds a relative or empty entry, no command is allowed without a prompt, since a file the agent wrote could run in place of a command or of the interpreter a path-spelled script starts by name. The reason names the entry; remove it from the `PATH` the harness starts with.
+- 1e8c651: The guard no longer allows reads of a declared instance through these spellings:
+  
+  - A `cd` after `||` may not run while the `&&` after it still does, so in `pwd || cd ./src && cat config/active.instance` the `cat` is now judged from both directories and denied.
+  - A newline after `&&`, `||` or `|` continues the list, so `pwd |` followed by a `cd` on the next line is refused like any `cd` in a pipeline.
+  - `rg` falls back to the guard's own walk when a `.gitignore` holds a line Git and ripgrep may match differently, such as `[[:alpha:]]`, braces, a backslash escape, trailing whitespace, a `**` inside a path component or bytes that are not UTF-8; Git could ignore a file ripgrep then reads.
+  - A path or `git -C` directory that leaves a symlink through `..`, such as `cat link/../active.instance`, is no longer judged by its spelling; it is treated like any symlink.
+  - `env -C` with `$?`, `cd` or `env -C` with `..` after a directory name, `pushd`, `popd`, zsh's `chdir`, `builtin` and a zsh `=command` word are refused, since the guard cannot see the directory or path they expand to.
+- 7c90129: The guard now authenticates and evaluates in one Node process instead of dispatching a second handler process per tool call, and it asks Git once per checkout instead of repeating identical probes. Run `npx --no cockpit sync` to regenerate `.cockpit/guards/bash-guard.sh`.
+- c78cf3f: `SURFACE_STATE_CONFLICT` on a hand-edited generated file (a skill, `.claude/settings.json`, the text between cockpit's markers in `AGENTS.md`, or the OpenCode root group) carries its own fix: move the edit into `cockpit.toml` or a surface overlay, and ask the person who owns the cockpit before discarding it. A file cockpit has no record of writing gets a fix that asks the person before it is moved or deleted, and a team's own harness settings file names the `sync --adopt` command in the fix rather than in the message.
+- d3d59a8: `init` shows the Compose port and healthcheck findings `check` would report for the drafted `cockpit.toml`, with the exact edit, before the draft is accepted; it still never edits a Compose file.
+- a3d5ba1: `init` inside a product repository now recommends and, under `--accept-preview` or `--accept-defaults`, defaults to an in-repo cockpit instead of refusing.
+- f323d50: A bare `cockpit init` now sets up the current directory for the default tools (Claude Code, Codex CLI and OpenCode). An explicit root and `--target` still choose otherwise.
+- 0d7b90a: `init` no longer proposes values the schema rejects, and say where every inferred port base came from.
+  
+  - Proposed `[testing]` stage and gate ids now lead with their role (`test-api`, `targeted-api`, `full-api`, `affected-api`), so a repository whose directory name starts with a digit gets ids the schema accepts. A name too long to form a 64-character id is reported as a skipped inference instead of being proposed.
+  - When `ports.bases` is read from several Compose files, the proposal names each file and the variables it publishes, including the files on both sides of a conflicting default.
+  - A Compose file that publishes a literal host port, such as `"8080:80"` or `published: 8080`, is reported as a skipped inference that says to publish it from a variable with a default.
+- 5fda3af: `init` now proposes more of what the product's own files already declare.
+  
+  - A repository with an `origin` remote in `.git/config` is proposed as `acquire = "auto"` with that `remote`, so a teammate's `setup` clones it. A URL that carries credentials is never proposed or shown, and a `.git` file (a worktree or submodule pointer) is not followed; both are reported with the file they came from.
+  - A Node lockfile proposes `toolchain = "node"`, and the reason names the `environment.install_policies` row that `setup` then requires.
+  - A `start`, `serve` or `dev` script proposes the service command, run by the package manager the lockfile selects, when no Dockerfile sets one.
+  - When a sibling's toolchain is left at its default, the reason names the lockfile that was read or the lockfiles that were looked for. It no longer says that nothing was observed.
+  - Each runnable-classification reason names its repository's file, so the reasons for several repositories can be told apart.
+  - The `environment.machine` question no longer claims that cockpit proposes the floor from the product's files. A person states it, and cockpit never proposes it.
+- 31f3947: `init` no longer strands a cockpit after it writes `cockpit.toml`, and its refusals say what mismatched and how to recover.
+  
+  - Every stop after `cockpit.toml` is written adds `INIT_VERIFICATION_INCOMPLETE`, whose fix says to correct `cockpit.toml` itself and rerun `init --accept-preview <previewSha256>` to finish. `--reset-answer` at that point (`INIT_ANSWER_RESET_UNAVAILABLE`) now names the same recovery, or `sync` once `init` has finished.
+  - A plain `sync` run before an interrupted `init` finished adopts the setup skill files `init` published for that cockpit, when they still hold exactly the bytes `init` recorded, instead of refusing them with `SURFACE_STATE_CONFLICT`. When `init` itself cannot take them over, `GENERATED_OWNERSHIP_INVALID` now says why and how to restore them.
+  - Remedies that delete a file (`SURFACE_STATE_CONFLICT`, an edited adopted settings file) tell an agent to ask the person who owns the cockpit first. The conflict for a file that already holds what sync would write now says that, instead of "not proof of ownership".
+  - A root removed and recreated at the same path no longer resumes the old bootstrap state and fails `GENERATED_OWNERSHIP_INVALID`: when none of the files `init` published, nor `cockpit.toml`, exist, `init` reports `INIT_STATE_RESTARTED` and starts again from the preview.
+  - `init` no longer proposes a sibling `remote` that is a local path or other non-https, non-ssh URL, which every `preflight` refused with `GIT_COMPARISON_REMOTE_MISMATCH`; the sibling is proposed with `acquire = "none"` and the reason. A declared remote of that kind now makes `GIT_COMPARISON_REMOTE_MISMATCH` say why it cannot be compared.
+  - `DOCUMENT_ESTATE_TOPOLOGY_MISMATCH` names the repositories `init` observed, the declared ones it did not, and the ones the answer omits, and its fix says to add other repositories after `init` with `sibling add`.
+- 354ed7d: `INIT_TARGET_CHANGED` carries a fix: resume the init with the target it was started with, or, after asking the person who owns the machine, delete the named state file that holds only that init's progress and start again with the new target. A plain `sync` that meets a setup file an unfinished init published, which no longer holds what that init recorded, says so and names the `init` command that resumes it.
+- 98bb460: `[[environment.install_policies]]` rows drop `volume`, `install` and `load_probe`. Nothing ran them once cockpit stopped generating the Compose environment, so a row now holds only what takes effect: `toolchain` and `lockfile`, which select the row for a sibling, and the optional `build` and `test` commands the guard allows in that checkout. A configuration that still sets one of the removed fields is refused as an unknown key.
+- eeff55b: An `environment.install_policies` row must declare a `build` command, a `test` command or both. A row with neither admitted nothing and only satisfied setup's lookup for its lockfile.
+- d075210: Work orders are one front-matter contract with a short lifecycle, and `cockpit.toml` says who takes each decision cockpit gates.
+  
+  - A work order is `workorders/<id>.md`. Its YAML front-matter (`id`, `objective`, `scope`, `depends_on`, `gates`, `criteria` with an optional `check` and `source` each, `non_goals`) is the whole contract; the Markdown body is free notes cockpit never reads. One schema validates it and names each field it refuses.
+  - The commands are `work status`, `accept` (also accepts a changed contract), `check`, `note` (`--ask` records an open question), `answer`, `grade`, `signoff` (`--partial` or `--abandon` with a note), `recover` and `verify`. An order moves draft, accepted, checked, graded, done; `status` also shows stale, blocked, partial and abandoned. `work grade` reports every change outside `scope`, which fails the grade. `work intake`, `renew`, `resume`, `execute`, `record`, `review`, `sweep`, `reverse`, `programme-mint` and `metrics` are gone, with intent descriptors, source audits, programmes and review lanes.
+  - `cockpit grade --criteria <file>` grades uncommitted work against a criteria file with the independent evaluator, and records nothing.
+  - `[work]` replaces `[workorders]` and adds `grading`: `independent` (an evaluator grades, the default), `checks` (done only when cockpit ran every criterion's check and all passed) or `self` (the agent reports met or unmet with a note). The record, `work status` and `doctor` say how each order closed. `work.evaluators` is the ordered list of evaluator tools.
+  - `[work.gates]` sets who passes `accept`, `amend`, `answer` and `signoff`: `agent`, `person` (the digest typed after `--interactive`, refused as `WORK_PERSON_REQUIRED` without a terminal) or `ci` (counts once the required `work verify` job passes). Removing or rewriting an accepted criterion always needs a person.
+  - `[autonomy]` sets who may run a writing `sync`, remove stale generated files, apply `reset --apply` and approve MCP servers, with `preset = "agent"` defaulting every unset field to `agent`. The guard denies an agent's edit of `[work]`, `[work.gates]` or `[autonomy]`, and of `[mcp]` while a person approves servers. A sync that finds a weaker policy than the one it last recorded in `.cockpit/policy.json` writes nothing until a person types its digest (`POLICY_WEAKENING_UNCONFIRMED`).
+  - The Claude Code and Codex hooks run `cockpit check` as a session starts, so the agent sees drift and its fix first; Codex runs it once a person trusts the new hook. A stale sibling guide copy names the guide, and its fix is to sync and commit `AGENTS.md` with the guide change.
+- f60e65e: `logs --follow` and large `--tail` reads now return records.
+  
+  - `--follow` is no longer cut off by the ten-second budget of an ordinary read, which made it fail with `EXECUTION_TIMEOUT` and no records. It collects until it is interrupted (exit 130 with the records collected), the container stops, or two hours pass.
+  - A read whose output exceeds the 1 MiB limit (64 KiB for stderr) no longer fails with `EXECUTION_STDOUT_LIMIT` and no records. It returns the newest whole records that fit, sets `truncated: true` in the JSON result and warns with `LOGS_TRUNCATED`.
+- 4d97b97: `logs` no longer reports `RUNTIME_UNMEASURED` for failures that have nothing to do with the runtime measurement, and it no longer tells you to run `runtime measure` on a runtime that is already measured.
+  
+  - A failure to read or parse the logs, such as a record that cannot be redacted safely, now reports `EVIDENCE_UNAVAILABLE` and names the cause.
+  - When the runtime itself cannot be used, `logs` now reports the actual refusal, including `RUNTIME_UNMEASURED` when the runtime really is unmeasured, instead of `log observation is unavailable`.
+  
+  The `runtime measure` summary names the configuration file you passed instead of always saying `cockpit.toml`.
+- 08cf5b7: An MCP approval now binds the reviewed declaration, not only the server name, and the generated wrapper starts in the right directory under any shell setup.
+  
+  - `[mcp.approved]` maps each server name to the sha256 of its command, arguments, working directory and environment names. A sibling's declaration file is agent-writable, so approving the name alone let a rewritten command start after the next human `sync`. A server whose declaration changed is now generated disabled, and `MCP_NOT_APPROVED` reports the digest to approve once it has been reviewed.
+  - The MCP wrapper no longer honours `CDPATH`, which could start the server in another directory and print that path into the JSON-RPC stream, and it resolves a sibling outside the cockpit from the real cockpit directory when the agent was started through a symbolic link.
+  
+  Upgrade: delete `approved = [...]` under `[mcp]`, run `cockpit sync`, review each server it reports as `MCP_NOT_APPROVED`, then add `name = "<sha256>"` under `[mcp.approved]` for each one to enable and run `cockpit sync` again.
+- f855180: `[autonomy] mcp_approve` now defaults to `person`. Under `agent`, `sync` enabled every server a sibling's `derives.mcp_sources` file declared, and that file is one an agent can write, so an agent could have a harness start any command outside the guard. A declared server now stays disabled with `MCP_NOT_APPROVED` until a person records its digest in `[mcp.approved]`, and the guard refuses an agent's edit of `[mcp]` by default. Setting `mcp_approve = "agent"` remains possible; the configuration reference, the safety guide and the block `cockpit init` writes say it lets an agent start processes outside the guard.
+- 5a2bb9f: `runtime measure` no longer removes the running probe of a concurrent measure from another worktree or terminal. It decided whether an earlier measure was still running from directories in its own temporary directory, which agent tools set per session, so a second measure could not see the first and force-removed its probe containers. Probe resources now carry a `dev.b0dea.cockpit.probe-owner` label naming the measuring process, and only resources whose process is gone are removed.
+- b4bb348: On a busy machine, measuring an explicit native hook's cost no longer times out after 10 seconds and reports `native hook cost execution failed: EXECUTION_TIMEOUT`. The measurement now has 60 seconds, so a hook over its `native-hook-ms` cap is reported as one to move to CI.
+- 9b03e49: The launcher now enforces the full Node.js range declared in `engines` and names it in the refusal.
+- 75c1e8e: The guard again counts `npx --no cockpit` as the installed cockpit when the root `package.json` has a `directories` entry that declares no commands. `npm init` writes `directories.doc` in a root holding the `docs/` that `sync` creates, and that made every printed `npx --no cockpit` command prompt (and Codex and OpenCode refuse it) while `./node_modules/.bin/cockpit` was allowed. Only `bin` and `directories.bin` still disqualify npx.
+- cba1ade: The installed guide keeps one table of diagnostic remedies, at the end of `docs/troubleshooting.md`: a code is listed there when every place that raises it gives the same fix, or a troubleshooting section covers it, and every other code's message is its guidance. The CLI reference no longer lists codes under each command, and the per-family remedies in `docs/environment.md` are gone. Moving an existing setup over to cockpit is now a section of `docs/getting-started.md`, and the package no longer ships the reference-page generator.
+- 5eafb68: When `package.json` is not valid JSON, `TEAM_METADATA_UNAVAILABLE` now says where parsing stopped and what shape was expected, the same way the work commands and the browser project check do: `package.json is not valid JSON at line 3, column 1; expected an npm package.json object`. It never quotes the file's contents.
+- fc382fb: The package is published as `@b00dea/cockpit`; install it with `npm install --save-dev @b00dea/cockpit`. The repository stays at github.com/b0dea/cockpit.
+- 2b6edfe: The guard's policy pin no longer lets a shell command past because its executable is spelled as a path or as `node <script>`. `/usr/bin/sed -i … cockpit.toml`, `/bin/cp x cockpit.toml`, `node script.js cockpit.toml`, a path spelled `git`, an `--option=cockpit.toml` operand and a `cockpit session -- …` command that names `cockpit.toml` are now hard denials like `sed -i … cockpit.toml`; only the `--config` operand of a cockpit command is left to the guard's proof that it starts the installed cockpit.
+- 21a2f57: Generated agent surfaces are portable across clones and tolerate the product teams' own edits.
+  
+  - A projected sibling guide is recorded by sibling and by its path inside that sibling, not by an absolute path, file identity or content digest. Editing, checking out or pulling the sibling's guide, or cloning the workspace to another path, no longer makes `check`, `sync` or `down` refuse with `SURFACE_STATE_CONFLICT`; the agent reads the new guide through the same link. A link replaced by a file or pointed elsewhere is still refused.
+  - MCP server configs and wrapper scripts no longer contain absolute paths: every harness starts `.cockpit/mcp/<id>.sh` relative to the cockpit root, and the wrapper finds its sibling from its own location, so a clone's `sync` rewrites nothing. Measured with Claude Code 2.1.316, Codex 0.166.0 and OpenCode 1.19.5; start the agent in the cockpit root, as the guard hooks already require.
+  - MCP wrappers pass `PATH` and the same non-secret variables product test stages receive, so `npx` and other `#!/usr/bin/env node` servers start.
+  - Sibling grants now reach the sibling. Codex resolves a relative `writable_roots` entry from `.codex/`, so the grant is written relative to that directory. OpenCode matches `external_directory` against absolute paths only, so the committed pattern reads the sibling's directory from a machine-local file that `sync` writes under `.cockpit/local/`; OpenCode refuses to start, naming that file, until `sync` has run on the machine.
+  - An MCP server missing from `[mcp].approved` is listed in Claude Code's `disabledMcpjsonServers`, because Claude Code ignores `disabled` in `.mcp.json` and offered the server for one-click approval. `sync` and `check` now print `MCP_NOT_APPROVED` for it.
+  - A changed core original under an overlay's `replaces.sha256` pin stops `sync` and `check` with `OVERRIDDEN_CORE_CHANGED`, naming the current digest; `sync --dry-run` and `doctor` still preview it.
+  - A rules overlay with Rulesync frontmatter (`root: false`, `globs: ["**/*"]`) no longer fails every sync; a rule that narrows itself with `globs` is refused as `SURFACE_RULE_SCOPE_UNSUPPORTED`, because cockpit writes rules overlays into the always-loaded instruction file. A generator failure now leads with the generator's own error.
+  - Going over `cockpit.guide_cap` reports `GUIDE_CAP_EXCEEDED` with the measured lines, the harness and the cap, from `sync`, `check` and `preflight`, including when a linked sibling guide grows past it.
+  - `preflight` names why it could not read a running stack (for example `GENERATED_ENVIRONMENT_UNAVAILABLE` for a `cockpit.toml` edit that was not synced) instead of a bare `LIFECYCLE_EVIDENCE_INVALID`.
+  - `check` tells you to run `sync --interactive` in a terminal for a formerly generated path, since plain `sync` refuses to remove it without a person's approval.
+  - The Claude plugin bundle carries the references its `cockpit-setup` skill tells the agent to read.
+  - The guide-cost figures rest on the 2026-11-02 instruction-loading measurements and say, for Claude Code, that linked sibling guides are counted even where Claude Code skips them. The capability data marks the Codex and OpenCode instruction measurements as settled, and the Cursor claim now says its instructions reach it only through the root `AGENTS.md`.
+- f416f24: `EXECUTION_PRECONDITION_CHANGED` from `up` and `session` now carries a fix. When `cockpit.toml` or the running stack changes while `up` runs, the refusal says to run `down` and then `up` again.
+- 67cec0a: Product test stages can now run real suites under a build tool.
+  
+  - Each `[testing]` stage takes an optional `timeout_seconds`; the default is far longer than the previous fixed limit. A stage that runs out of time reports that it timed out and names the field to raise.
+  - Output past the capture limit no longer makes a stage DEGRADED: cockpit keeps the tail and judges the stage by its exit status. A stage that exits non-zero now reports FAIL instead of DEGRADED.
+  - Stages receive `HOME`, `USER`, `LOGNAME`, `TMPDIR`, `LANG`, `LC_ALL`, `LC_CTYPE` and `TZ` from the calling environment, so tools that keep caches under the home directory work. Every other variable is still withheld.
+- 0b40913: `init` now proposes `[testing]` from the product's own test entry points, and a cockpit with no test gate says so instead of pointing agents at a gate that does not exist.
+  
+  - For a runnable product, `init` asks a new `testing` question. It proposes stages and gates from a Bazel workspace, `nx.json`, a `turbo.json` test task, a Makefile `test` target, a `package.json` test script, pytest configuration, `go.mod` or `Cargo.toml`, naming the file each came from. A tool that selects affected tests supplies the targeted gate. Answer `"none"` when the product has no tests yet.
+  - With no `[testing]` declared, the generated testing guide tells agents to add a characterization test in the product's existing runner, never to report work as passing, and to ask a person to declare gates.
+  - `doctor` warns `TESTING_GATE_UNDECLARED` when a cockpit with a runtime declares no test gate.
+  
+  Upgrade: unattended `init` runs for a runnable product need a `testing` answer in the answers file (a `[testing]` table, or `testing = "none"`).
+- 5cd6fd7: Two warnings about the machine rather than the cockpit now appear only where they apply.
+  
+  - `check` and `doctor` no longer report `CODEX_HOOK_UNTRUSTED` when Codex has never run as this user (no `CODEX_HOME` or `~/.codex`). With no Codex installed, no Codex session can skip the guard hook.
+  - `STATE_RECORD_MALFORMED` for state folders that other cockpits, usually earlier versions, left behind is reported once by `doctor` with its cleanup command, and no longer on every `up` and `session`.
+- fca0dcf: Refusals now name their cause the same way everywhere.
+  
+  - A cause cockpit worded itself is shown in full, including where several commands previously reduced it to `Error`.
+  - A parser, library or child-process message is no longer copied into a refusal, since it can quote the file or output being read; the refusal names the error class instead, or the line and column for an invalid JSON or TOML file.
+  - The `STATE_RECORD_MALFORMED` warning about other cockpits' unreadable state folders now tells the agent to ask the person who owns the machine before deleting them.
+- d79779e: Refusals that come from a caught error now say why. A filesystem or process failure appends its system error, for example `EACCES: permission denied, open '<path>'`. Any other failure appends only its error class, because parser and child-process messages can quote file contents or environment values.
+  
+  - An unparseable `package.json` is reported as `TEAM_METADATA_UNAVAILABLE` with the parse failure. It was previously reported as `COCKPIT_VERSION_MISMATCH` with a missing pin.
+- 52f3020: Refusals no longer repeat a parser's message, which could quote the file's contents. An unparseable `package.json` in team metadata, or a `cockpit.toml` an adoption would leave unparseable, is reported with the line and column where parsing stopped, when the parser gives them. A harness evidence manifest that does not parse is reported with its line, column and expected shape. A state inventory entry that fails for an unexpected reason is reported by its system error or error class only. A `package.json` or `.gitignore` that is not valid UTF-8 is named as such.
+  
+  Refusals that used to drop the filesystem error now name it. This covers a browser screenshot that fails its postcheck, a screenshot artifact root or seeded storage state that cannot be read, and a work grade whose evaluator source or Codex CLI is unavailable.
+- 8d2f923: Several refusals now say what to do in words that work as written:
+  
+  - A failed `setup` clone reports `SETUP_CLONE_FAILED` with the remote, the target directory, git's own error and the siblings already cloned, plus a fix, instead of a bare `EXECUTION_STEP_FAILED`. Any failed execution step now carries a bounded, redacted tail of its stderr in the refusal evidence.
+  - `GENERATED_STALE_APPROVAL_REQUIRED` names `sync --interactive` and the digest to type, and a human `sync --dry-run` prints that digest.
+  - `runtime measure` with an image that is not local reports `RUNTIME_IMAGE_UNAVAILABLE` and says to pull or build it, instead of telling you to start a runtime that is running.
+  - A mistyped `--config` in a cockpit checkout no longer suggests restoring the mistyped path from git; it names the configuration the checkout was synced from.
+  - `MACHINE_COLD_START_EXCEEDED` and the machine-floor refusals (`MACHINE_MEMORY_BELOW_FLOOR`, `MACHINE_CPU_BELOW_FLOOR`, `MACHINE_DISK_BELOW_FLOOR`) state the measured value, the declared limit and the field to change.
+- b8ae534: `registry-resolve` now works on a cockpit installed from a tarball packed from source. It validates the registry and adoption file first, records `COCKPIT_SOURCE_REVISION='development'` with a `COCKPIT_REVISION_UNSTAMPED` warning when the package carries no release commit, and refuses only a malformed revision, with a fix. Adoption-file refusals state the expected five-line format, which the adoption guide now documents.
+- 363cb2e: Removed `cockpit.toml` fields that had no effect or could be written only one way. A configuration that still sets one is refused as an unknown key, so delete the line.
+  
+  - `surfaces.harnesses[].features`. `capabilities` must still hold exactly one row for each surface feature.
+  - `sibling[].derives.mcp_sources[].format`. Each source is read as a JSON file with an `mcpServers` object, as before.
+  - `browser.authentication.states[].source`. Saved sign-in state should still come from seeded users, but cockpit cannot check where it came from.
+  
+  `browser.data.isolated` and `browser.data.reaches_production` stay required. They are your statement about the data the browser uses, and `request_preapproval` is refused unless the data is isolated and does not reach production.
+- 40e1315: A command run with the same option twice now names the repeated option as the diagnostic's target, and every command words the refusal the same way. `init` accepts a repeated `--json`, as every other command already did.
+- 4c782e0: `reset --apply` now decides by the autonomy policy `sync` recorded, as sync and the work commands do: when `cockpit.toml` weakens `[autonomy] reset` (for example from `person` to `agent`) and no person has accepted that weakening at `sync --interactive`, it refuses with `POLICY_WEAKENING_UNCONFIRMED` and resets nothing. It used to read the edited `cockpit.toml` and apply.
+- ac13e35: An applied `reset` now prints what it removed and that the next `up` recreates the volumes and runs `environment.seed` where one is declared; it used to print nothing. `--json` carries the removed targets as `result.targets`.
+- 5da286d: A `reset` preview, or a declined `reset --interactive`, of a stack that is down no longer leaves a claim and port lease behind. The kept claim made every later `up` refuse with `EXECUTION_PRECONDITION_CHANGED` and a "rerun up" fix that repeated the refusal. `down` and `reset` now give back the claim they take on a stopped stack whenever they stop before removing anything, and an `up` refused before it starts a service now restores the port reservation it found instead of keeping its family reserved. If an earlier version already left such a claim, `up` now says to run `down` and then `up`, which clears it.
+- 5025dc5: `environment.resettable_volumes` now names volumes by their Compose key, and a name that matches no declared volume is refused.
+  
+  - `reset` matches each entry against the volume's top-level `volumes:` key in the Compose file within the stack's own Compose project. It previously compared the entry with Docker's volume name, which carries a per-checkout project prefix, so a committed `resettable_volumes = ["data"]` reset nothing.
+  - A name no declared volume has is refused instead of skipped: `sync`, `check` and every runtime command, `down` included, refuse with `GENERATED_DECLARATION_INVALID` or `GENERATED_ENVIRONMENT_UNAVAILABLE`, naming the declared keys. An `external` volume is refused too, because Compose does not create it and cockpit cannot label it. A declared volume that does not exist yet, or was already removed, is not an error.
+  - A data volume created under an earlier `cockpit.toml` is still reset, together with any of the stack's containers from that configuration that hold it. The preview still binds the exact volume, labels and generation, so a volume replaced before the approval is refused.
+- 4159978: The bundled surface generator is now Rulesync 43.4.2. OpenCode MCP tool switches in `opencode.jsonc`
+  now use the names OpenCode itself gives tools, with every character other than a letter, digit,
+  `_` or `-` in the server or tool name replaced by `_`. Before, a `disabledTools` entry on a server
+  such as `web.search` was written as `web.search_fetch.page`, which OpenCode never matched, so the
+  tool stayed enabled. When two switches reduce to the same name, the one that disables now wins.
+  `cockpit check` reports the rewritten `opencode.jsonc` as drift until `cockpit sync` runs. The Claude
+  Code and Codex CLI surfaces are unchanged.
+- cf02cd3: A test gate that reads the running stack's runtime evidence now captures it. The capture previously refused every time with `EVIDENCE_UNAVAILABLE`.
+  
+  - The stability capture uses its own output limit instead of the larger limit sized for logs, which the capture refused.
+  - The content hash follows `/proc/1/exe`, which is a symlink, instead of finding no files and failing.
+- cda8970: `runtime measure` now cleans up after itself and is recorded once per machine.
+  
+  - A measure killed mid-probe left probe containers, a network, a volume and a temporary directory behind. The next `runtime measure` removes this cockpit's own leftovers (matched by label, Compose project and a dead owner), lists what it removed, leaves anything a live measure may own, and refuses to probe when a leftover cannot be removed.
+  - Measurements are stored under the per-user state root instead of beside `cockpit.toml`, so every git worktree of a cockpit reuses them. A different runtime, daemon or engine version still matches no row and still needs its own measurement. Existing `.cockpit/local/runtime-measurements.json` records are not read; measure once more.
+- 60db846: A grade answered by the tool running the command now prints a warning naming each tool passed over, its reason and the fix, and a tool absent from PATH is reported as "not on PATH" instead of the last PATH entry tried.
+- b27a80b: Commands run inside a sandbox such as Codex's `workspace-write` now pass where they can and say why where they cannot.
+  
+  - `test-run` no longer reports `DEGRADED` with "repository subject … root is unavailable" inside the sandbox. macOS's `git` warned on stderr because cockpit's Git probes ran without `TMPDIR`; they now pass the temporary directory. When a probe does fail, the reason quotes the command and its first stderr line.
+  - `STATE_ROOT_UNAVAILABLE` names the state root, the directory that failed and the error (for example `EPERM`) instead of "requires an absolute usable home directory". A permission failure says to run the command outside the sandbox or let the sandbox write there.
+  - `up`, `doctor` and the other lifecycle and health commands forward that refusal instead of reporting `LIFECYCLE_EVIDENCE_INVALID` "state namespace is unavailable" or "doctor observation source is unavailable".
+- 2004442: Every configuration field now carries a one-sentence description, shown as hover text in editors that read `cockpit.schema.json` and as a Meaning column in the configuration reference. The editor schema now requires `observed_on` and `confirmed` evidence on every provenance table, including those under `browser.runner_health_measurement` and `surfaces.adopted`.
+- 4571f68: `work grade` under `[work] grading = "self"` now runs the order's checks and compares its `scope`, as
+  `independent` and `checks` already did, and a failed check or a change outside scope fails the grade.
+  Before, an agent's own `met` closed an order whose check failed or whose diff reached files the order
+  never allowed.
+- f56fb69: `cockpit selftest` no longer asks you to fill probe rows for custom harness cells that it never ran.
+  
+  - `--write-probe-specifications` writes rows for built-in tools only, and warns `SELFTEST_CUSTOM_PROBE_UNSUPPORTED` for each custom harness cell it left out, naming the cell and why. Before, it wrote a `{node}` row for each custom cell, and `selftest` recorded that cell `human_needed` whatever you put in the row.
+  - `selftest` records each custom cell `human_needed` with `enforcement_probe_required` without a row, and refuses a probe-specification file with a custom row, naming each one.
+  - What breaks: a filled probe-specification file that has custom rows is refused. Delete those rows, or write a new file.
+- 1d69b51: `cockpit selftest` probes now reach a signed-in tool's sign-in.
+  
+  - Each probe inherits `PATH`, `HOME`, `USER`, `LOGNAME`, `TMPDIR`, `LANG`, `LC_ALL`, `LC_CTYPE` and `TZ` and nothing else. Before, it ran with an empty environment, so Claude Code, Codex and OpenCode answered "not logged in" and every cell came back `human_needed` with `authentication_required`.
+  - Tokens and every other variable still stay out of the probe, so a tool signed in only through an environment variable still reports `authentication_required`.
+- 4afca91: Rewriting the `cockpit selftest` probe-specification file after a config change keeps the probes you wrote.
+  
+  - `selftest --write-probe-specifications <new file> --probe-specifications <earlier file>` copies each complete row from the earlier file whose cell still exists, and reports how many it kept. Rows for new or changed cells, and rows still partly `null`, start over. Before, the only way forward from a stale file was a new file with every row reset to `null`.
+  - The refusal for a stale file now names that command.
+- 284369d: `cockpit selftest` can now be run: `selftest --config <path> --write-probe-specifications <new file>` writes the probe-specification file it needs for the current `cockpit.toml` and generated manifest.
+  
+  - The file has one row per cell that needs evidence. cockpit fills what the generated manifest decides, plus the `--version` and `--help` identity commands, and leaves `invocation`, `candidateCode`, `brokenCode` and skill `sample.features` as `null` for you to write. The command prints where each value came from.
+  - The file no longer carries `specificationsSha256`, so you can edit the rows; approving the whole file's SHA-256 at the `--interactive` prompt is what binds them.
+  - `selftest` refuses a file that still has a `null` and lists the rows. A missing, malformed or stale file is refused with a fix naming the command that writes a new one.
+- fb4b328: A hold that `up` re-adds inside a `cockpit session`, after a `sleep` there released it, is now tied to the session wrapper's process. Previously it recorded no process, so a wrapper killed afterwards left a hold that no later command released. The wrapper passes its process ID and start time in `COCKPIT_SESSION_PROCESS`; `up` checks that process again and refuses with `CLI_USAGE_INVALID` when the wrapper has ended.
+- b07421c: A `cockpit session` hold now survives a wall-clock step on Linux, and a hold whose start could not be read is released once its process is gone.
+  
+  - On Linux a session is identified by its start in clock ticks since boot, read from `/proc`, instead of the wall-clock start `ps` derives from the boot time. An NTP correction or a resumed VM no longer makes a running session read as gone, so another session's `down` or `reset` can no longer stop its stack, and an `up` inside the session is no longer refused.
+  - A session whose start could not be read (no `ps` or `/proc` access) recorded a hold that was never released after a SIGKILL. It is now released once its process ID is gone.
+- eb37dd7: `setup` now refuses with `SETUP_REMOTE_UNRESOLVABLE` when a sibling's declared remote, or an existing checkout's origin, is a relative local path that cannot be resolved (for example it passes through a regular file, loops through symlinks, or is unreadable). The message names the remote and the error code. Previously the error escaped, setup's lifecycle record stayed `started`, and `doctor` and `preflight` lost the cause.
+  
+  `doctor` and `preflight` now include the underlying error when they cannot issue their observation source.
+- e8d3bc8: `setup` now clones a sibling whose `remote` is a relative local path and passes its own check afterwards.
+  
+  - A relative local `remote` resolves against the siblings root before cloning and before it is compared with the checkout's `origin`. Previously Git recorded the absolute path and `setup` failed with `SETUP_REMOTE_MISMATCH`.
+  - URL and `host:path` remotes are unchanged.
+- 298f896: `init` now publishes the pre-interview setup skill for every tool in `[surfaces] tools`, not only the first.
+- 729103b: The shipped skills now walk an agent through numbered steps that each end on a check, and handle the cases the CLI really reaches: a guard prompt that Codex and OpenCode turn into a denial, a guard that holds every call after `cockpit.toml` changes or cockpit is reinstalled, Codex's sandbox, a resumed or refused `init`, readiness gaps, a missing evaluator, stale and blocked work orders, person gates, and a stack that will not start. Corrected claims: `tool add --dry-run`, `sibling add` and `setup --write-*` are commands the guard asks about; a removed tool's files are deleted by `sync` as `[autonomy] stale_delete` allows, with a digest only when it refuses; after a manual `npm install` of a new release, a person runs `sync` in a terminal; `--instruction-pointer` opts a sibling in before `setup` shows the block. Every procedure invokes cockpit through `./node_modules/.bin/cockpit`, which runs where the guard cannot prove `npx`.
+- a3b580f: `sync` now copies each active sibling's guides into cockpit's region of the root `AGENTS.md`, under a heading naming the sibling, instead of linking them through `.sibling-*` symlinks, `CLAUDE.local.md` imports, a "read this file" line for Codex and the `opencode.jsonc` `instructions` list. Measured on 2026-11-03, the copy is the one route Claude Code, Codex and OpenCode all load: Claude Code skipped the linked guide in a workspace it had not trusted and Codex only ever saw the line pointing at it. The capability matrix records the runs.
+  
+  A copy goes stale when a sibling edits its guide: `check` and `preflight` then report `GENERATED_ARTIFACT_DRIFT` naming each out-of-date `<sibling>/<guide>` until a person runs `sync` and commits `AGENTS.md`, so a guide edit reaches later agent sessions only after review. `GUIDE_CAP_EXCEEDED` now also fires when cockpit's region of `AGENTS.md` passes 32768 bytes, past which Codex silently drops the rest. A guide containing cockpit's own instruction region markers is refused.
+- b106b94: `doctor` and `init` now warn when a sibling repository's root instruction files leave some agent tool without its instructions: Codex and OpenCode load `AGENTS.md`, Claude Code loads `CLAUDE.md`, and files such as `.cursorrules` or `GEMINI.md` reach none of them. The warnings are `SIBLING_INSTRUCTIONS_AGENTS_ONLY`, `SIBLING_INSTRUCTIONS_CLAUDE_ONLY`, `SIBLING_INSTRUCTIONS_UNLINKED`, `SIBLING_INSTRUCTIONS_MISSING` and `SIBLING_INSTRUCTIONS_TOOL_ONLY`, grouped under the `sibling-instructions` readiness gap.
+  
+  `setup` proposes the two fixes that need no judgement and makes them only with the new `--write-instruction-files` flag, which a person runs after reviewing them: a sibling with only `AGENTS.md` gets a `CLAUDE.md` reading `@AGENTS.md`, and a sibling whose lone `CLAUDE.md` imports nothing else has it moved byte for byte into `AGENTS.md` and replaced by that import. The shipped setup procedure walks an agent through the cases that need a person.
+- ca95dd5: `test-run` judges a stage by its exit status alone. A stage that exits 0 having printed nothing, such as `tsc --noEmit`, `node --check` or a quiet linter, now passes instead of reporting DEGRADED, so it can satisfy a gate. A run blocked by a stopped stack names only the stack, and the `TEST_GATE_UNSATISFIED` fix says what to do for each verdict: fix the product for FAIL, start the stack, make the stage command runnable, raise its timeout or declare its `select` arguments for DEGRADED, rerun VOID once the checkouts stop changing, and run the complete gate for PARTIAL.
+- 851c21c: Each shipped skill now installs only its own procedure (`procedures/setup.md`, `explain.md`, `fix.md` or `work.md`) instead of a full copy of one shared procedure, so a tool's skills directory holds about a third of the lines it did. Bootstrap, secret handling and the other setup steps live in the setup procedure, which the explain and fix procedures point to. The setup procedure gains *Add or remove an agent tool*. The capability matrix says which tools are written by default and which only when listed.
+- 9cd2f06: The shipped skills name the shell tool only of the harnesses in `[surfaces] tools`, so a single-tool cockpit no longer mentions the others.
+- 202c58f: Running stacks recover from the states that used to wedge them.
+  
+  - A `cockpit session` killed without its closing `sleep` no longer holds the stack forever: the session records its process ID and start time, and the next `up`, `sleep`, `down` or `reset` releases a hold whose process is gone. `CLAIM_CO_TENANT` names each remaining holder and its process.
+  - `cold_start_seconds` is honoured up to 3600 seconds instead of being cut to five minutes; a larger value is refused by the configuration.
+  - Editing the machine floor, postures, `resettable_volumes` or entrypoint derivatives no longer forces a `down`, and a second `up` after the first reports `unchanged` instead of a fresh start.
+  - A declaration change on a fully started compose-first stack makes `up` refuse with `LIFECYCLE_PROGRESS_INVALID` instead of recreating its healthy containers.
+  - Plain `reset` prints its preview, and the recovery messages for a killed service and an ended session say what to run.
+- d08215c: `sync`, `check` and `up` no longer fail with "surface staging cleanup did not complete" when the temporary directory is reached through a symbolic link (macOS with `TMPDIR` unset or set to `/tmp`), and no longer leave `cockpit-surfaces-*` directories behind.
+- 0001be9: When a state operation fails and its lock then cannot be released, the `STATE_LOCKED` refusal names the operation's error by its class (or by its system error) instead of repeating its message, which could quote the input being parsed.
+- f3b2ab4: `sync` re-reads the Compose files named in `environment.compose_files` before it publishes `compose.cockpit.yml`, and refuses with `GENERATED_SOURCE_CHANGED` when one changed after the override was rendered, instead of publishing an override rendered from the old file.
+- 6c71ac4: `[surfaces] tools` in cockpit.toml lists the agent tools `sync` writes and `check` compares. It defaults to Claude Code, Codex and OpenCode, the tools whose guard is measured; Cursor and Grok Build are written only when listed. A list names at least one of the guarded tools.
+  
+  - `npx --no cockpit tool add <tool> --config cockpit.toml` and `tool remove` edit that list (with `--dry-run` to preview). The next sync writes an added tool's files; a removed tool's files go through the stale-removal approval.
+  - Doctor and check report Codex hook trust only when Codex is listed, and sibling instruction findings name only layouts that leave a listed tool without instructions.
+  - `init --target` takes one tool or a comma-separated list (`--target claudecode,opencode`) and writes it as `[surfaces] tools`; the first tool gets the setup skill before the interview, and the final sync writes every chosen tool. Readiness reports Codex hook trust only for a cockpit that lists Codex.
+  - `workorders.evaluators`, left unset, is the listed tools that can evaluate, in their order, so a cockpit that lists only Claude Code grades with Claude Code and doctor does not ask for Codex.
+- 5384b25: `SURFACE_GENERATOR_TRUST_WARNING` appears only when `sync` writes `.claude/settings.json`, not on every sync and `check`, and it names what the file grants: the additional directories, the approved MCP servers, and the number of command patterns in `permissions.allow`. An empty server list grants nothing and is no longer reported.
+- f240ec6: Git or state read failures no longer leave a check silently clean.
+  
+  - A repository Git refuses to read, such as one owned by another user (`safe.directory`), is reported as unchecked with the command a person may run to trust it, instead of as committing no secret files or as no Git working tree.
+  - `doctor` says when it could not read the machine's cockpit state, instead of silently dropping its check for other cockpits' unreadable state.
+  - The Codex hook trust warning names why `config.toml` could not be read, such as a file over the size bound, instead of "unknown error".
+- 19c36c4: `cockpit upgrade [<version>] [--dry-run] --config <path>` moves the exact pin in one command: it resolves the latest published release (or the version you name), installs it as an exact dev dependency with the package manager the cockpit root's single lockfile names (npm, pnpm or yarn), runs `sync` in a new process so the new version renders, and prints the `Upgrade:` lines from the installed changelog between the two versions. It refuses with a named code when the registry is unreachable, the version is invalid, the target is not newer than the installed version, or the lockfile is missing or ambiguous. `--dry-run` prints the install and sync commands without running them. An agent may run `upgrade` exactly where `[autonomy] sync` lets it run a writing `sync`, and its sync child decides stale removals by `[autonomy] stale_delete`; `--dry-run` writes nothing and is never gated, for `upgrade` and `sync` alike.
+- f70c223: `check` now warns with `COMPOSE_PORT_ALL_INTERFACES` when a Compose file publishes a port without a host interface, which Docker binds on every interface. Writing `127.0.0.1` (or `0.0.0.0`, when the exposure is intended) silences it. The extended example now binds loopback, and the example READMEs reach the stack through its leased port variable instead of a fixed port.
+- bab0317: The `work` and `browser` commands are no longer marked experimental in `--help`, the CLI reference and the README. Work orders still require the Codex CLI, on `PATH` and signed in, for the independent reviews and grading.
+- 7fcda72: Work-order and browser commands are subcommands, and `cockpit --help` is grouped by stage.
+  
+  - The work-order commands are `cockpit work <subcommand>` (`work status`, `work accept`, `work check`, `work note`, `work answer`, `work grade`, `work signoff`, `work recover`, `work verify`), and the browser commands are `cockpit browser <subcommand>` (`browser drive`, `browser screenshot`, `browser debugger`). Options are unchanged. A hyphenated spelling such as `work-grade` is refused with `CLI_UNKNOWN_COMMAND`, which names the spelling that runs.
+  - `cockpit --help` lists the commands under Set up, Generate and verify, Run the stack, Diagnose, and Test and grade, with `work` and `browser` as one entry each; `cockpit work --help` and `cockpit browser --help` list their subcommands. A group run without a subcommand is refused with `CLI_COMMAND_REQUIRED`, which lists them.
+
+## 0.0.0
+
+The development version. It was never published.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 b0dea
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,23 @@
-# Temporary Holding Version
+<p align="center"><img src="https://raw.githubusercontent.com/b0dea/cockpit/main/.github/assets/cockpit-logo.png" alt="" width="128"></p>
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# @b00dea/cockpit
+
+This package is the cockpit CLI: where coding agents work on your whole product. From one reviewed
+`cockpit.toml` it gives Claude Code, Codex CLI and OpenCode the same instructions, skills and guard
+hook across every repository of the product, runs the product's own Compose stack on the live
+checkouts with a port lease per checkout, checks work orders against criteria you set, and fails a
+check when any generated file drifts. What each tool actually enforces is in the
+[capability matrix](https://github.com/b0dea/cockpit/blob/main/docs/capability-matrix.md).
+
+Install it as an exact, project-local dev dependency (the package is pre-alpha, so pin the version):
+
+```sh
+npm install --save-dev --save-exact @b00dea/cockpit
+```
+
+Start with the [repository README](https://github.com/b0dea/cockpit#readme) and
+[Getting started](https://github.com/b0dea/cockpit/blob/main/docs/getting-started.md#install-cockpit).
+
+The `cockpit` command is the only public interface; the package's exports and type declarations
+serve cockpit's own tooling and are not a stable API. Supported Node.js versions are in `engines`
+in this package's `package.json`.

package/bin/cockpit.mjs

@@ -0,0 +1,33 @@
+#!/usr/bin/env node
+
+// Mirrors package.json "engines.node"; the floor is the 22.x minor, not just the major.
+const supportedRange = '^22.22.0 || ^24.0.0 || ^26.0.0'
+const minimumNode22Minor = 22
+const version = process.versions.node
+const match = typeof version === 'string' && /^([0-9]+)\.([0-9]+)\.[0-9]+(?:[-+].*)?$/.exec(version)
+const major = match ? Number(match[1]) : Number.NaN
+const minor = match ? Number(match[2]) : Number.NaN
+
+if (!Number.isInteger(major) || major < 22 || (major === 22 && minor < minimumNode22Minor)) {
+    console.error(
+        `COCKPIT_NODE_VERSION_UNSUPPORTED: Node.js ${supportedRange} is required; this is ${version}.`,
+    )
+    process.exitCode = 1
+} else {
+    const { runCli } = await import('../dist/cli.js')
+    const argv = process.argv.slice(2)
+    if (argv[0] !== 'session' && argv[0] !== 'logs') {
+        process.exitCode = await runCli(argv)
+    } else {
+        const controller = new AbortController()
+        const abort = () => controller.abort()
+        process.once('SIGINT', abort)
+        process.once('SIGTERM', abort)
+        try {
+            process.exitCode = await runCli(argv, process, {}, { signal: controller.signal })
+        } finally {
+            process.removeListener('SIGINT', abort)
+            process.removeListener('SIGTERM', abort)
+        }
+    }
+}