@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/work-orders/store.js

@@ -0,0 +1,291 @@
+// Owns the record cockpit keeps of each work order, `.cockpit/work-orders/<id>.json`: what was
+// accepted and by whom, the checks cockpit ran, the grade, notes and questions, and how the order
+// closed. Records are committed so the `work verify` CI job can read them, and only cockpit writes
+// them: the guard denies an agent's write below `.cockpit/work-orders/`, because an unkeyed record
+// an agent wrote there would read as cockpit's own. A write holds the order's lock file, which a
+// crashed writer leaves behind until `work recover --apply` removes it.
+import { randomUUID } from 'node:crypto';
+import { existsSync } from 'node:fs';
+import { link, lstat, mkdir, open, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import { hostname } from 'node:os';
+import { join } from 'node:path';
+import { z } from 'zod';
+import { isProcessGone, observeProcessStart, processHost } from '../environment/claims.js';
+import { hasErrorCode, RefusalError } from '../environment/contract.js';
+import { executeProbe } from '../environment-exec/execute.js';
+import { DECIDERS, WORK_GRADING } from '../schema.js';
+import { WORK_ORDER_ID, WorkOrderFrontMatter } from './contract.js';
+export const WORK_RECORD_DIRECTORY = '.cockpit/work-orders';
+const RECORD_LIMIT_BYTES = 1_048_576;
+const OUTPUT_TAIL_BYTES = 4_096;
+const at = z.string().datetime();
+const by = z.enum(DECIDERS);
+const note = z.string().min(1).max(4_096);
+const CheckResult = z.object({
+    criterion: z.string().max(64),
+    kind: z.enum(['argv', 'gate']),
+    passed: z.boolean(),
+    // How the check ended: an exit status, a gate verdict, or why it could not run.
+    outcome: z.string().max(256),
+    output: z.string().max(OUTPUT_TAIL_BYTES * 2),
+}).strict();
+const Verdict = z.object({ id: z.string().max(64), verdict: z.enum(['met', 'unmet', 'unclear']), note: z.string().max(4_096) }).strict();
+const Grade = z.object({
+    at, digest: z.string().length(64), mode: z.enum(WORK_GRADING), passed: z.boolean(),
+    criteria: z.array(Verdict).max(64), outOfScope: z.array(z.string().max(1_100)).max(512),
+    // Which evaluator answered and those passed over on the way; absent when no evaluator ran.
+    evaluator: z.object({ tool: z.string().max(64), fallbacks: z.array(z.object({ tool: z.string().max(64), code: z.string().max(64), message: z.string().max(8_192) }).strict()).max(8) }).strict().optional(),
+    note: note.optional(),
+}).strict();
+export const WorkRecord = z.object({
+    format: z.literal('cockpit-work-order/v1'),
+    id: z.string().regex(WORK_ORDER_ID),
+    state: z.enum(['accepted', 'checked', 'graded', 'done', 'partial', 'abandoned']),
+    accepted: z.object({
+        at, by, digest: z.string().length(64),
+        // The accepted contract, so a later amendment can be compared criterion by criterion.
+        order: WorkOrderFrontMatter,
+        sources: z.record(z.string(), z.string().length(64)),
+        base: z.record(z.string(), z.string().regex(/^[a-f0-9]{40,64}$/)),
+    }).strict(),
+    // `weakened` names what the amendment removed; `review` each change a model, or a person where none grades, judges
+    // against the bar, with its text before and after. An agent's amendment is judged at the next grade.
+    amendments: z.array(z.object({ at, by, from: z.string().length(64), to: z.string().length(64), weakened: z.array(z.string()).max(64),
+        review: z.array(z.object({ field: z.string().max(64), before: z.string().max(131_072), after: z.string().max(131_072) }).strict()).max(128) }).strict()).max(256),
+    // A person's (or, where [work.gates] allows, an agent's or CI's) acknowledgement that the change weakened tests:
+    // it covers exactly the findings its digest names, so a later weakening needs its own.
+    acknowledgements: z.array(z.object({ at, by, digest: z.string().length(64), findings: z.array(z.string().max(1_100)).max(256), note }).strict()).max(256),
+    attempts: z.number().int().min(0),
+    checks: z.object({ at, digest: z.string().length(64), results: z.array(CheckResult).max(64) }).strict().optional(),
+    grade: Grade.optional(),
+    // A grade found the agent's amendments lowered the bar. It outlives the grade a later check or grade
+    // replaces, and only an amendment a person or CI accepts clears it, so the next amendment stays theirs.
+    amendmentsFailedReview: z.object({ at, note: z.string().max(4_096) }).strict().optional(),
+    // A decision is resolved by a later `resolution` note naming it in `resolves`: with `record`, the decision
+    // record it is written in; without, `text` says why it made no lasting decision. The latest resolution counts.
+    notes: z.array(z.object({ at, by: z.enum(['agent', 'person', 'ci']), kind: z.enum(['note', 'question', 'answer', 'decision', 'resolution']), text: note,
+        answers: z.number().int().min(1).optional(), resolves: z.number().int().min(1).optional(), record: z.string().max(1_100).optional() }).strict()).max(1_024),
+    closure: z.object({ at, by, how: z.enum(['graded', 'checks-passed', 'self-reported', 'partial', 'abandoned']), note: note.optional() }).strict().optional(),
+    // Each lock `work recover --apply` removed: the holder it named and what was checked to call it gone.
+    recoveries: z.array(z.object({ at, holder: z.string().max(1_024), checked: z.array(z.string().max(1_024)).max(16) }).strict()).max(256).optional(),
+}).strict();
+/** Keeps the end of a command's output, where a runner prints its summary, within the record's bound. */
+export function outputTail(value) {
+    const bytes = Buffer.from(value);
+    return bytes.byteLength <= OUTPUT_TAIL_BYTES ? value : `[...]${bytes.subarray(bytes.byteLength - OUTPUT_TAIL_BYTES).toString('utf8')}`;
+}
+// A lock names its writer: pid and start, so a reused pid never keeps a dead writer's lock alive, and
+// the host and whether it ran in a container, because a pid means nothing outside the process table
+// it came from. Docker names a container's host after the container, unless it shares the machine's network.
+const LockHolder = z.object({ pid: z.number().int().min(1), start: z.string().max(256).optional(), host: z.string().min(1).max(255), container: z.boolean() }).strict();
+const inContainer = () => existsSync('/.dockerenv') || existsSync('/run/.containerenv');
+const holder = async () => {
+    const observed = await observeProcessStart(process.pid, processHost(executeProbe));
+    return { pid: process.pid, ...observed.state === 'present' ? { start: observed.start } : {}, host: hostname(), container: inContainer() };
+};
+// Whether the holder is shown running or gone, looking first where a pid probe cannot; anything unproven is unknown.
+async function judgeHolder(found, containers) {
+    const here = hostname();
+    const listed = containers.state === 'listed' ? containers.containers : [];
+    const checked = [`the lock was written by process ${found.pid} on host ${found.host}${found.container ? ' inside a container' : ''}`, `this machine is host ${here}`,
+        (containers.state === 'listed' ? `Docker context ${containers.context} lists ${listed.length} cockpit-labelled container(s)${listed.length
+            ? `: ${listed.map(row => `${row.name} (${row.running ? 'running' : 'stopped'})`).join(', ')}` : ''}`
+            : containers.state === 'no-docker' ? `no Docker client is installed (${containers.reason}), so no container on this machine runs cockpit`
+                : `Docker could not be read: ${containers.reason}`).slice(0, 1_024)];
+    if (containers.state === 'unavailable')
+        return { lock: 'unknown', checked };
+    if (found.host !== here || found.container) {
+        const writer = /^[a-f0-9]{12}$/.test(found.host) ? listed.find(row => row.id.startsWith(found.host)) : undefined;
+        if (!writer)
+            return { lock: 'unknown', checked: [...checked, 'the writer ran on another host or in a container this machine does not list, whose processes this machine cannot see'] };
+        return { lock: writer.running ? 'live' : 'dead', checked: [...checked, `container ${writer.name}, which wrote it, is ${writer.running ? 'running' : 'stopped, so none of its processes runs'}`] };
+    }
+    const observed = await observeProcessStart(found.pid, processHost(executeProbe));
+    const lock = isProcessGone(found.start, observed) ? 'dead' : observed.state === 'unknown' ? 'unknown' : 'live';
+    return { lock, checked: [...checked, `process ${found.pid} on this machine is ${lock === 'dead' ? 'gone' : observed.state === 'unknown' ? `not observable (${observed.reason})` : 'running'}`] };
+}
+export function createWorkStore(root) {
+    const directory = join(root, WORK_RECORD_DIRECTORY);
+    const pathOf = (id, suffix) => {
+        if (!WORK_ORDER_ID.test(id))
+            throw new RefusalError(`work order id ${JSON.stringify(id)} is not an id`);
+        return join(directory, `${id}${suffix}`);
+    };
+    const read = async (id) => {
+        const path = pathOf(id, '.json');
+        let bytes;
+        try {
+            const status = await lstat(path);
+            if (!status.isFile() || status.size > RECORD_LIMIT_BYTES)
+                throw new RefusalError(`${WORK_RECORD_DIRECTORY}/${id}.json is not a regular file of at most 1 MiB`);
+            bytes = await readFile(path);
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT'))
+                return undefined;
+            throw error;
+        }
+        let value;
+        try {
+            value = JSON.parse(bytes.toString('utf8'));
+        }
+        catch (error) {
+            if (!(error instanceof SyntaxError))
+                throw error;
+            value = undefined;
+        }
+        const parsed = WorkRecord.safeParse(value);
+        if (!parsed.success || parsed.data.id !== id) {
+            throw new RefusalError(`${WORK_RECORD_DIRECTORY}/${id}.json is not a cockpit work-order record; restore it with git restore -- ${WORK_RECORD_DIRECTORY}/${id}.json`);
+        }
+        return parsed.data;
+    };
+    const lock = async (id) => {
+        await mkdir(directory, { recursive: true });
+        const path = pathOf(id, '.lock');
+        // The holder is written before the lock appears, by linking a finished file into place, so a
+        // crash never leaves a lock that names nobody and so could never be shown gone.
+        const staged = `${path}.${randomUUID()}.tmp`;
+        await writeFile(staged, `${JSON.stringify(await holder())}\n`, { flag: 'wx', mode: 0o644 });
+        try {
+            await link(staged, path);
+        }
+        catch (error) {
+            if (!hasErrorCode(error, 'EEXIST'))
+                throw error;
+            throw new RefusalError(`work order ${id} is locked by another cockpit command (${WORK_RECORD_DIRECTORY}/${id}.lock); wait for it, or if it crashed run npx --no cockpit work recover --config <your cockpit.toml> --work-order ${id} --apply`);
+        }
+        finally {
+            await rm(staged, { force: true });
+        }
+        return async () => { await rm(path, { force: true }); };
+    };
+    const write = async (record) => {
+        const checked = WorkRecord.parse(record);
+        const bytes = `${JSON.stringify(checked, null, 2)}\n`;
+        if (Buffer.byteLength(bytes) > RECORD_LIMIT_BYTES)
+            throw new RefusalError(`the ${record.id} record would exceed 1 MiB`);
+        const path = pathOf(record.id, '.json');
+        const staged = `${path}.${randomUUID()}.tmp`;
+        const handle = await open(staged, 'wx', 0o644);
+        try {
+            await handle.writeFile(bytes);
+            await handle.sync();
+        }
+        finally {
+            await handle.close();
+        }
+        try {
+            await rename(staged, path);
+        }
+        catch (error) {
+            await rm(staged, { force: true });
+            throw error;
+        }
+    };
+    const store = {
+        read,
+        list: async () => {
+            let names;
+            try {
+                names = await readdir(directory);
+            }
+            catch (error) {
+                if (hasErrorCode(error, 'ENOENT'))
+                    return [];
+                throw error;
+            }
+            const ids = names.filter(name => name.endsWith('.json')).map(name => name.slice(0, -'.json'.length)).filter(id => WORK_ORDER_ID.test(id)).sort();
+            return Promise.all(ids.map(async (id) => (await read(id))));
+        },
+        update: async (id, change) => {
+            const release = await lock(id);
+            try {
+                const result = await change(await read(id));
+                if (result.record)
+                    await write(result.record);
+                return result.value;
+            }
+            finally {
+                await release();
+            }
+        },
+        recover: async (id, apply, containers) => {
+            const path = pathOf(id, '.lock');
+            let text;
+            try {
+                text = await readFile(path, 'utf8');
+            }
+            catch (error) {
+                if (hasErrorCode(error, 'ENOENT'))
+                    return { id, lock: 'none' };
+                throw error;
+            }
+            let parsed;
+            try {
+                parsed = JSON.parse(text);
+            }
+            catch (error) {
+                if (!(error instanceof SyntaxError))
+                    throw error;
+            }
+            const found = LockHolder.safeParse(parsed);
+            const shown = text.trim().slice(0, 1_024);
+            if (!found.success)
+                return { id, lock: 'unknown', holder: shown, checked: ['the lock does not name its holder the way cockpit writes one'] };
+            // A lock whose writer is still running, or cannot be shown gone, is never removed: the write it guards may be in progress.
+            const judged = await judgeHolder(found.data, await containers());
+            if (judged.lock !== 'dead' || !apply)
+                return { id, lock: judged.lock, holder: shown, checked: judged.checked };
+            // The lock is taken over rather than deleted, so no other writer slips in before the recovery is recorded.
+            // Two recoveries that both judged it dead must not both replace it and then each delete the other's: each
+            // links its holder at the takeover name, which only one can create, and only that one replaces the lock.
+            const ours = `${path}.${randomUUID()}.tmp`;
+            const takeover = `${path}.takeover`;
+            await writeFile(ours, `${JSON.stringify(await holder())}\n`, { flag: 'wx', mode: 0o644 });
+            try {
+                try {
+                    await link(ours, takeover);
+                }
+                catch (error) {
+                    if (!hasErrorCode(error, 'EEXIST'))
+                        throw error;
+                    throw new RefusalError(`another work recover is taking over the lock on ${id}; rerun work recover once it finishes, `
+                        + `or if none is running, a person removes ${WORK_RECORD_DIRECTORY}/${id}.lock.takeover, which a crashed recovery left`);
+                }
+                let replaced = false;
+                try {
+                    let current;
+                    try {
+                        current = await readFile(path, 'utf8');
+                    }
+                    catch (error) {
+                        if (!hasErrorCode(error, 'ENOENT'))
+                            throw error;
+                    }
+                    if (current !== text)
+                        throw new RefusalError(`the lock on ${id} changed while it was being recovered; rerun work recover`);
+                    await rename(takeover, path);
+                    replaced = true;
+                }
+                finally {
+                    if (!replaced)
+                        await rm(takeover, { force: true });
+                }
+            }
+            finally {
+                await rm(ours, { force: true });
+            }
+            try {
+                const record = await read(id);
+                if (record)
+                    await write({ ...record, recoveries: [...record.recoveries ?? [], { at: new Date().toISOString(), holder: shown, checked: [...judged.checked] }] });
+                return { id, lock: 'removed', holder: shown, checked: judged.checked, recorded: record !== undefined };
+            }
+            finally {
+                await rm(path, { force: true });
+            }
+        },
+    };
+    return store;
+}

package/docs/README.md

@@ -0,0 +1,68 @@
+# Cockpit documentation
+
+cockpit is the local environment coding agents work from: every repository of the product in reach,
+the product running on the checkouts they edit, the same instructions, skills and guard in every agent
+tool from one `cockpit.toml`, and work orders checked against criteria you set and graded the way you choose. The instructions and
+guard need only Git and Node.js; the stack and grading switch on when configured. New here: read [Getting started](getting-started.md)
+chapter 1, which needs one repository and no Docker.
+
+This index lists every page for people using cockpit on their own products, grouped by what you
+are trying to do. To work on cockpit itself, start with [CONTRIBUTING.md](https://github.com/b0dea/cockpit/blob/main/CONTRIBUTING.md); the
+contributor pages live separately under docs/contributing/.
+
+## Learn
+
+- [Tutorial](tutorial.md): run the Compose-first example end to end.
+- [Getting started](getting-started.md): one repository, one tool and no Docker first, then more
+  repositories and a Compose stack; includes the guide and safety contract for an AI agent setting
+  cockpit up.
+- [Concepts](concepts.md): the glossary and the terms diagnostics use.
+- [FAQ](faq.md): short answers, including when not to use cockpit.
+
+## Guides
+
+- [Joining a team's cockpit](joining-a-team.md): install and verify a cockpit from a fresh clone.
+- [Environment lifecycle](environment.md): setup, bring-up, health, logs, reset and seeding;
+  worktrees, Compose profiles, one-service commands and pruning stacks across the machine.
+- [Compose patterns](compose-patterns.md): vendor stubs, TLS and data restore in plain Compose.
+- [Harness surfaces](harness-surfaces.md): what `sync` writes for each agent tool, and overlays.
+- [Extending cockpit](extending.md): supported extension points, what an upgrade replaces and the build-beside pattern.
+- [Safety and autonomy](safety-and-autonomy.md): what guards allow, ask about and deny.
+- [Work and browser workflows](work-and-browser.md): work orders, grading, test protection,
+  decisions, browser checks and test tiers.
+- [Living documents and decision records](docs-check.md): find documents that cite removed paths
+  or make targets, and decision records whose numbers, index or statuses disagree.
+
+## Reference
+
+The command list, CLI reference, configuration reference and capability matrix are generated from
+the source and change with it. Troubleshooting combines hand-written recovery guidance with a
+generated diagnostic index.
+
+- [Configuration essentials](configuration-essentials.md): the tables a typical `cockpit.toml`
+  sets, each linked to its full reference entry.
+- [Command list](command-list.md)
+- [CLI reference](cli-reference.md)
+- [Configuration reference](configuration-reference.md)
+- [Capability matrix](capability-matrix.md)
+- [Troubleshooting](troubleshooting.md): hand-written remedies followed by the generated table
+  of codes with a fixed remedy.
+
+## Examples
+
+Each example is a cockpit you can copy and run; its README gives the exact commands.
+
+- [examples/minimal](https://github.com/b0dea/cockpit/blob/main/examples/minimal/README.md): one service, one port and one health check
+  in a plain `compose.yml`, for a running stack.
+- [examples/compose-first](https://github.com/b0dea/cockpit/blob/main/examples/compose-first/README.md): a cockpit that keeps its own
+  `compose.yml`.
+- [examples/docs-only](https://github.com/b0dea/cockpit/blob/main/examples/docs-only/README.md): no environment, for a repository of
+  documents or a product not yet built.
+- [examples/extended](https://github.com/b0dea/cockpit/blob/main/examples/extended/README.md): a custom Compose service and
+  product-specific checks kept beside cockpit.
+
+## Background
+
+- [Architecture and design](architecture.md): why cockpit is shaped this way, non-goals, and
+  extension seams.
+- [Release policy](release-policy.md): supported runtimes, deprecation and migration.

package/docs/architecture.md

@@ -0,0 +1,136 @@
+# Architecture and design
+
+This page is for integrators and contributors who want the reasoning behind cockpit: the problem it
+solves, the design decisions that follow, and where in the source to extend it. The fields and
+commands themselves are in the generated [configuration reference](configuration-reference.md) and
+[CLI reference](cli-reference.md).
+
+## The problem cockpit solves
+
+Agent work across several repositories of one product fails in predictable, mechanical ways:
+
+1. **No shared environment.** Each agent sees one checkout. Nothing boots the product it is
+   changing, so "it works" means "it compiles".
+2. **File access is not instruction.** Granting an agent a sibling directory does not tell it
+   what that repository is, how it is tested, or which commands are safe there.
+3. **Guards do not carry across tools.** A hook written for one harness does nothing in another,
+   and each harness spells permissions differently.
+4. **Environments collide.** Two agents on one machine fight over ports, volumes and the right to
+   stop the stack.
+5. **Completion is self-reported.** The session that did the work also declares it done.
+
+There are three ways to respond. A planning tool describes the work and leaves the environment
+to you. A sandbox isolates the agent from your machine, and from the product. cockpit boots the
+product the agent is editing, from the checkouts it is editing, and gives every harness the same
+rules about it.
+
+## Design decisions
+
+### Two axes: mount and acquire
+
+A sibling declares how the stack uses it (`mount`) separately from how it reaches disk
+(`acquire`). Neither is derived from the other. Collapsing them produces a preflight that reports
+healthy while the stack mounts the wrong checkout, or none.
+
+### Configuration that parses does something
+
+Every schema field is consumed by code. A field that is accepted and then ignored reads as a
+control the next person relies on, so it is a defect. Where a harness offers no
+mechanism for a restriction, cockpit emits nothing and records the feature as `unavailable`
+rather than writing a setting that binds nothing.
+
+### Generated files are committed and drift-checked
+
+Generated surfaces and Compose files are written into your repository, committed, and compared
+byte for byte by `cockpit check`. This sits between vendoring (copies that silently go stale) and
+a hidden runtime dependency (nothing to review). You can read every line an agent will load, and
+CI fails when a line changes without the configuration changing.
+
+### TypeScript decides, shell runs the hooks
+
+Configuration, validation, codegen, drift and state live in the TypeScript CLI, and every child
+process goes through one executor. Guards and hooks stay in shell, because every harness invokes
+them directly on each tool call and they must behave identically under all of them with no
+interpreter start-up cost.
+
+### Leases, locks and destruction
+
+These rules came from failures on shared machines:
+
+- **Ports are leased, not derived.** Two checkouts of one product would compute the same port from
+  the same configuration. A lease records who holds each port family.
+- **Locks are directory creations.** Creating a directory either succeeds or fails atomically, and
+  a process that dies leaves the directory behind for inspection instead of a half-written file.
+- **Unknown is not dead.** A lock or holder whose liveness cannot be established is reported, not
+  stolen. Age alone never justifies removing it.
+- **Classification overrides intent.** Destructive commands act only on resources whose cockpit
+  labels and records match, so "just delete it" cannot be expressed. The question cockpit asks
+  is "can I account for everything I am about to destroy?", not "does this look dangerous?".
+
+### Why the evaluator is independent
+
+Self-assessment is overconfident: an agent that wrote the code also wrote the account of it. The
+evaluator is a separate subagent that reruns the declared verification commands, grades each
+acceptance criterion from that output, and may abstain when the output is not enough to decide. Abstention
+is a valid result; it is what turns a likely false pass into a visible gap.
+
+### Prior art
+
+Spec and workflow tools also generate files into repositories. cockpit adds three things they
+typically lack: a drift check against installed generated files, a `--dry-run` preview of every
+write, and CLI and configuration references generated from the source so they cannot go stale.
+
+## Non-goals
+
+- **Not a planner.** cockpit does not decide what work to do. Pair it with a spec or workflow tool.
+- **Not a sandbox.** It does not isolate an agent from your machine; see
+  [Safety and autonomy](safety-and-autonomy.md).
+- **No telemetry.** The only network request cockpit makes itself is `doctor` reading the latest
+  published version from the npm registry, skipped when `CI` or `NO_UPDATE_NOTIFIER` is set.
+- **Not a monorepo or build-system replacement.** It can manage one repository or several, but
+  delegates each repository's build and dependency graph to that repository's own tools.
+- **No per-test containers.** One stack per checkout, shared across the agent's work.
+
+## Processing path
+
+Configuration is declared and loaded, the environment is observed, policy code decides, the
+environment application orders the work, and the shared executor runs child processes.
+Postchecks verify results before command handlers print them. The
+[Cockpit evidence boundary](concepts.md#cockpit-evidence-boundary) applies at every step: a
+parsed declaration is not an observation, a dispatched command is not a successful postcheck,
+and a generated file does not show that its harness loaded it.
+
+## Surface overlays
+
+Use a [Cockpit surface overlay](concepts.md#cockpit-surface-overlay) for product-specific rules,
+subagents, skills and hooks. Overlay merging belongs to `packages/cockpit/src/surfaces/merge.ts`;
+rendering continues through the existing surface code, and publication stays within
+[Cockpit generated ownership](concepts.md#cockpit-generated-ownership).
+[Ownership and extension](harness-surfaces.md#ownership-and-extension) covers the `replaces` rule
+and the review procedure.
+
+## Guards
+
+Extend policy in `packages/cockpit/src/guards/evaluator.ts`, then adapt its decision through the
+per-harness adapters. Do not interpret guard policy in shell or rebuild it in a CLI
+handler. A harness mechanism that has not been probed beside a deliberately broken control stays
+`instructed` or `unavailable`; see [Capability states](harness-surfaces.md#capability-states).
+
+## Runtime behavior
+
+Add a public command to `packages/cockpit/src/command-table.ts`, bind it in
+`packages/cockpit/src/cli.ts`, and order environment work through the environment application
+(`packages/cockpit/src/environment/application/`). Every child process crosses
+`packages/cockpit/src/environment-exec/execute.ts`; health and lifecycle verdicts stay in their
+existing modules. Add a schema field only together with the code that consumes it.
+
+The runtime sequence and recovery rules are in [Environment](environment.md). A new diagnostic
+needs one actionable remedy in [Troubleshooting](troubleshooting.md).
+
+## Harnesses
+
+A custom harness declares one row for every feature, with the evidence described in
+[Custom harnesses](harness-surfaces.md#custom-harnesses). Probe the exact harness version beside
+a deliberately broken control before changing a capability claim. Repository tests verify
+cockpit's side of the contract; native loading and enforcement need their own check through
+`cockpit selftest`.

package/docs/capability-matrix.md

@@ -0,0 +1,58 @@
+# Capability matrix
+
+<!-- Generated by `npm run references`; edit its sources, not this file. -->
+
+<!-- Source manifest: 7db847121f6f4cf7fc6608625e755acc97326e8320ea425b807d7de8a283f70c -->
+
+This generated page is for users checking what cockpit actually enforces in each agent tool. Each cell holds one of four states:
+
+- `enforced`: a dated run of the real tool, beside a deliberately broken control, showed it refusing the forbidden operation.
+- `instructed`: cockpit writes the guidance or setting, but nothing makes the agent follow it.
+- `generated`: cockpit writes the files, but nobody has checked that the tool even loads them.
+- `unavailable`: cockpit writes nothing for this cell.
+
+Only a dated run of the real tool changes a state; writing a file or passing cockpit's own tests never does.
+
+Written says whether `sync` writes the tool's files for a cockpit.toml that lists no tools: the tools whose guard firing is measured are the default `[surfaces] tools`, and any other tool is written only once listed (`npx --no cockpit tool add <tool> --config <your cockpit.toml>`).
+
+Guard firing is the generated hook refusing a protected operation. Instruction loading is the tool reading the guidance cockpit writes for it, including the guides of sibling repositories. Skills are the tool loading the skills cockpit renders: `cockpit-setup`, `cockpit-explain`, `cockpit-fix` and `cockpit-work`. The session-start check is the tool running `cockpit check` as a session starts and showing its drift report to the agent. Remote MCP servers are the tool connecting to an approved streamable HTTP server with the credential cockpit spells for it: an environment reference or a headers helper. Worktree grants are the tool letting the agent write a checkout `cockpit use` serves from outside the declared one, through a machine-local file cockpit writes.
+
+| Tool | Written | Guard firing | Instruction loading | Skills | Session-start check | Remote MCP servers | Worktree grants |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| Claude Code (`claudecode`) | by default | enforced | instructed | instructed | instructed | instructed (needs a person) | enforced (needs a person) |
+| Codex (`codexcli`) | by default | enforced (needs a person) | instructed | instructed | instructed (needs a person) | instructed | unavailable |
+| OpenCode (`opencode`) | by default | enforced | instructed | instructed | unavailable | instructed | enforced |
+| Cursor (`cursor`) | when listed | unavailable | generated | generated | unavailable | unavailable | unavailable |
+| Grok Build (`grokcli`) | when listed | unavailable | generated | generated | unavailable | unavailable | unavailable |
+
+## Measurements
+
+Each line gives the date and tool version of the run and what it showed.
+
+- Claude Code, guard firing (2026-11-01, version 2.1.316): with the exact push pre-allowed by permissions, the hook refused git push to a protected branch and the remote stayed empty while git status ran; the same checkout without the hook pushed.
+- Codex, guard firing (2026-11-01, version 0.165.0): only after a person trusts the hook: untrusted, Codex skipped it and git push ran; trusted (forced with --dangerously-bypass-hook-trust), it refused the push. Trust is per machine and cockpit doctor warns until it is given.
+- OpenCode, guard firing (2026-11-01, version 1.19.4): the plugin refused git push and a native read of a secrets file while an unprotected read stayed allowed; before read was routed through the guard, the same read returned the file.
+- Claude Code, instruction loading (2026-11-03, version 2.1.317): in a workspace Claude Code had not trusted, a sibling guide copied into the root AGENTS.md that CLAUDE.md imports loaded, with or without Claude Code's user option for reading AGENTS.md, while the undeclared sibling's guide and the decoy did not; nothing loaded through a committed CLAUDE.md @-import of a link to the guide or of its relative path, through permissions.additionalDirectories with CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD in the settings env (ignored until a person trusts the workspace), or through --add-dir with that variable set.
+- Codex, instruction loading (2026-11-03, version 0.166.0): a sibling guide copied into the root AGENTS.md loaded while the undeclared sibling's guide and the decoy did not; nothing loaded through a line in AGENTS.md telling the agent to read a link to the guide, through --add-dir naming the sibling, or through project_doc_fallback_filenames naming the link, and Codex dropped the end of a project AGENTS.md past 32 KiB.
+- OpenCode, instruction loading (2026-11-03, version 1.19.5): a sibling guide copied into the root AGENTS.md loaded, as did a guide named through a link in the opencode.jsonc instructions list, while the undeclared sibling's guide and the decoy did not.
+- Claude Code, session-start check (2026-11-03, version 2.1.317): a SessionStart hook in .claude/settings.json ran under claude -p and the agent quoted its stdout back, while a hook under a misspelled event name never ran and Claude Code named it as ignored.
+- Codex, session-start check (2026-11-03, version 0.166.0): only after a person trusts the hook, as for the guard: a trusted SessionStart hook in .codex/hooks.json ran under codex exec and the agent quoted its stdout back, while a hook under a misspelled event name never ran.
+- Claude Code, remote MCP servers (2026-11-04, version 2.1.318): from a project .mcp.json, Claude Code sent the Authorization header a ${NAME} reference named while a $NAME control went out literally; it ran a headersHelper given with --mcp-config, but refused to run one from the project file until a person trusts the workspace, and a misspelled headerHelper sent nothing.
+- Codex, remote MCP servers (2026-11-04, version 0.166.0): from a project .codex/config.toml in a directory Codex had not been told to trust, codex exec sent the bearer_token_env_var and env_http_headers values and the http_headers_helper output, named a misspelled http_header_helper as ignored, and sent a ${NAME} written in http_headers literally.
+- OpenCode, remote MCP servers (2026-11-04, version 1.19.5): opencode mcp list sent headers expanded from {env:NAME} in a project opencode.jsonc while a ${NAME} control went out literally; its remote server schema has no headers helper, so a server that declares one is not written for it.
+- Claude Code, worktree grants (2026-11-04, version 2.1.318): a directory in .claude/settings.local.json permissions.additionalDirectories was written and the control refused, and a malformed twin granted nothing; measured in an untrusted workspace, so whether it combines with the committed list once a person trusts the workspace is unmeasured.
+- Codex, worktree grants (2026-11-04, version 0.166.0): Codex reads no machine-local project file; --add-dir at start made the worktree writable and without it the write was refused, so cockpit use prints that flag and writes nothing.
+- OpenCode, worktree grants (2026-11-04, version 1.19.5): the machine-local grant file holding the worktree path allowed the write and the control was denied, and a pattern naming a missing grant file stopped OpenCode at start, naming the file.
+
+## Without a measurement
+
+- Guard firing in Cursor and Grok Build: no guard adapter is checked in, so cockpit generates no guard hook.
+- Instruction loading in Cursor: cockpit's instructions and the sibling guides it copies reach Cursor only through the root AGENTS.md, and .cursor/rules holds only rules overlays; no run of the tool beside a broken control has shown that it loads either.
+- Instruction loading in Grok Build: cockpit writes the files, but no run of the tool beside a broken control has shown that it loads them.
+- Skills in Claude Code (`.claude/skills`), Codex (`.agents/skills`) and OpenCode (`.opencode/skills`): a person has not yet reviewed whether the tool loads and triggers them as written.
+- Skills in Cursor (`.cursor/skills`) and Grok Build (`.grok/skills`): cockpit writes the files, but no run of the tool beside a broken control has shown that it loads them.
+- Session-start check in OpenCode: OpenCode 1.19.5 delivers session.created to a plugin, but no run has shown a plugin putting text in the agent's context, so cockpit generates no session-start check.
+- Session-start check in Cursor and Grok Build: cockpit generates no hook for this tool.
+- Remote MCP servers in Cursor and Grok Build: cockpit writes no remote MCP server for this tool: its remote transport and header spelling have not been checked.
+- Worktree grants in Cursor and Grok Build: the tool was not installed where this was measured, so cockpit use writes nothing for it.
+- Browser native transports (the playwright MCP tools and the pinned Playwright CLI) in Claude Code, Codex and OpenCode: cockpit declares them and the browser skill says each still needs a person's paired call beside a broken control; no cockpit command runs or records that call, so the browser commands drive the browser through cockpit's own project client instead.