@b00dea/cockpit 0.0.0-bootstrap.0 → 0.1.0

package/dist/work-orders/contract.d.ts

@@ -0,0 +1,61 @@
+import { z } from 'zod';
+export declare const WORK_ORDER_ID: RegExp;
+declare const Check: z.ZodUnion<readonly [z.ZodObject<{
+    gate: z.ZodString;
+    select: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>, z.ZodArray<z.ZodString>]>;
+export type WorkOrderCheck = z.infer<typeof Check>;
+export declare const WorkOrderFrontMatter: z.ZodObject<{
+    id: z.ZodString;
+    objective: z.ZodString;
+    scope: z.ZodArray<z.ZodString>;
+    depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    gates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    criteria: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        check: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            gate: z.ZodString;
+            select: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodArray<z.ZodString>]>>;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    non_goals: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+export type WorkOrder = z.infer<typeof WorkOrderFrontMatter>;
+export type WorkOrderCriterion = WorkOrder['criteria'][number];
+export type ParsedFile<T> = Readonly<{
+    ok: true;
+    value: T;
+}> | Readonly<{
+    ok: false;
+    problems: readonly string[];
+}>;
+/** Parses `workorders/<id>.md`; the id the file declares must be the name it is stored under. */
+export declare function parseWorkOrder(bytes: Uint8Array, fileId: string): ParsedFile<WorkOrder>;
+/** The quick-path file `cockpit grade --criteria` reads: front-matter with criteria, and optionally scope and gates. */
+export declare const CriteriaFile: z.ZodObject<{
+    criteria: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        text: z.ZodString;
+        check: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+            gate: z.ZodString;
+            select: z.ZodOptional<z.ZodString>;
+        }, z.core.$strict>, z.ZodArray<z.ZodString>]>>;
+        source: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    scope: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    gates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+    objective: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export declare function parseCriteriaFile(bytes: Uint8Array): ParsedFile<z.infer<typeof CriteriaFile>>;
+/** The digest an acceptance binds: the contract, each cited source's bytes, and the base commits. */
+export declare function workOrderDigest(order: WorkOrder, sources: Readonly<Record<string, string>>, base: Readonly<Record<string, string>>): string;
+/**
+ * The accepted criteria a changed contract removes or rewrites. Adding a criterion strengthens an
+ * order; dropping one, or changing what one says or how it is checked, weakens it, and that is never
+ * an agent's decision.
+ */
+export declare function criteriaWeakening(accepted: WorkOrder, changed: WorkOrder): readonly string[];
+export declare function scopeMatches(scope: readonly string[], path: string): boolean;
+export {};

package/dist/work-orders/contract.js

@@ -0,0 +1,122 @@
+// Owns the work-order file: `workorders/<id>.md`, whose YAML front-matter is the whole contract an
+// order is accepted, checked and graded against, and whose Markdown body is free notes cockpit never
+// reads. One schema validates the front-matter; the digest binds it with the bytes of every source a
+// criterion cites and the commit each repository stood at when the order was accepted.
+import { createHash } from 'node:crypto';
+import { parseDocument } from 'yaml';
+import { z } from 'zod';
+// One inert word, never a path or an option: the CLI, the guard and the store each admit it before it names a file.
+export const WORK_ORDER_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const WORK_ORDER_LIMITS = Object.freeze({ bytes: 65_536, criteria: 12, scope: 64, textBytes: 2_048, arguments: 32, argumentBytes: 2_048 });
+const PRINTABLE = /^[^\x00-\x08\x0b-\x1f\x7f]*$/;
+const text = z.string().trim().min(1).refine(value => Buffer.byteLength(value) <= WORK_ORDER_LIMITS.textBytes && PRINTABLE.test(value), `at most ${WORK_ORDER_LIMITS.textBytes} bytes without control characters`);
+// `path` in the cockpit's own repository, or `<sibling slug>:path` in a sibling; never absolute or climbing.
+const REPOSITORY_PATH = /^(?:[a-z0-9][a-z0-9-]{0,63}:)?(?![/])(?!.*(?:^|[/:])\.\.(?:\/|$))[A-Za-z0-9._@+\-/*?]+$/;
+const repositoryPath = z.string().max(1_024).regex(REPOSITORY_PATH, 'a relative path, optionally <sibling slug>:path, without .. or a leading /');
+const sourcePath = repositoryPath.refine(value => !/[*?]/.test(value), 'a source names one file, without wildcards');
+const argument = z.string().min(1).refine(value => Buffer.byteLength(value) <= WORK_ORDER_LIMITS.argumentBytes && !/[\x00-\x1f\x7f]/.test(value), 'a bounded argument without control characters');
+const GateCheck = z.object({
+    gate: z.string().regex(/^[a-z][a-z0-9-]{0,63}$/, 'a declared [testing] gate id'),
+    // A selected value that starts with `-` would reach the product's tool as an option of its own.
+    select: z.string().max(4_096).regex(/^(?:spec|file|test|route):[^-]/, 'spec|file|test|route:<value>').optional(),
+}).strict();
+const Check = z.union([GateCheck, z.array(argument).min(1).max(WORK_ORDER_LIMITS.arguments)]);
+const Criterion = z.object({
+    id: z.string().regex(/^[A-Za-z][A-Za-z0-9_-]{0,31}$/, 'a short identifier such as AC1'),
+    text,
+    check: Check.optional(),
+    source: sourcePath.optional(),
+}).strict();
+const Criteria = z.array(Criterion).min(1).max(WORK_ORDER_LIMITS.criteria)
+    .refine(rows => new Set(rows.map(row => row.id)).size === rows.length, 'each criterion id is used once');
+export const WorkOrderFrontMatter = z.object({
+    id: z.string().regex(WORK_ORDER_ID, 'letters, digits, dot, underscore or hyphen, at most 128'),
+    objective: text,
+    scope: z.array(repositoryPath).min(1).max(WORK_ORDER_LIMITS.scope).describe('Paths and globs the work may change.'),
+    depends_on: z.array(z.string().regex(WORK_ORDER_ID)).max(32).default([]),
+    gates: z.array(z.string().regex(/^[a-z][a-z0-9-]{0,63}$/)).max(16).default([]).describe('Declared [testing] gates that must pass at work check.'),
+    criteria: Criteria,
+    non_goals: z.array(text).max(32).default([]),
+}).strict();
+function frontMatter(bytes) {
+    if (bytes.byteLength > WORK_ORDER_LIMITS.bytes)
+        return { ok: false, problems: [`the file exceeds ${WORK_ORDER_LIMITS.bytes} bytes`] };
+    let source;
+    try {
+        source = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
+    }
+    catch (error) {
+        if (!(error instanceof TypeError))
+            throw error;
+        return { ok: false, problems: ['the file is not UTF-8'] };
+    }
+    const lines = source.replace(/^/, '').split(/\r?\n/);
+    const end = lines.indexOf('---', 1);
+    if (lines[0] !== '---' || end < 0)
+        return { ok: false, problems: ['the file must start with YAML front-matter between two --- lines'] };
+    const document = parseDocument(lines.slice(1, end).join('\n'), { uniqueKeys: true, prettyErrors: false });
+    if (document.errors.length)
+        return { ok: false, problems: document.errors.map(error => `front-matter is not YAML: ${error.message.split('\n')[0]}`) };
+    return { ok: true, value: document.toJS({ maxAliasCount: 0 }) };
+}
+function issues(error) {
+    return error.issues.map(issue => `${issue.path.length ? issue.path.join('.') : 'front-matter'}: ${issue.message}`);
+}
+/** Parses `workorders/<id>.md`; the id the file declares must be the name it is stored under. */
+export function parseWorkOrder(bytes, fileId) {
+    const read = frontMatter(bytes);
+    if (!read.ok)
+        return read;
+    const parsed = WorkOrderFrontMatter.safeParse(read.value);
+    if (!parsed.success)
+        return { ok: false, problems: issues(parsed.error) };
+    if (parsed.data.id !== fileId)
+        return { ok: false, problems: [`id: the file workorders/${fileId}.md declares id ${parsed.data.id}; they must match`] };
+    if (parsed.data.depends_on.includes(parsed.data.id))
+        return { ok: false, problems: ['depends_on: an order cannot depend on itself'] };
+    return { ok: true, value: parsed.data };
+}
+/** The quick-path file `cockpit grade --criteria` reads: front-matter with criteria, and optionally scope and gates. */
+export const CriteriaFile = z.object({ criteria: Criteria, scope: z.array(repositoryPath).max(WORK_ORDER_LIMITS.scope).default([]),
+    gates: z.array(z.string().regex(/^[a-z][a-z0-9-]{0,63}$/)).max(16).default([]), objective: text.optional() }).strict();
+export function parseCriteriaFile(bytes) {
+    const read = frontMatter(bytes);
+    if (!read.ok)
+        return read;
+    const parsed = CriteriaFile.safeParse(read.value);
+    return parsed.success ? { ok: true, value: parsed.data } : { ok: false, problems: issues(parsed.error) };
+}
+function canonical(value) {
+    if (Array.isArray(value))
+        return value.map(canonical);
+    if (value === null || typeof value !== 'object')
+        return value;
+    return Object.fromEntries(Object.keys(value).sort().map(key => [key, canonical(value[key])]));
+}
+/** The digest an acceptance binds: the contract, each cited source's bytes, and the base commits. */
+export function workOrderDigest(order, sources, base) {
+    return createHash('sha256').update(JSON.stringify(canonical({ order, sources, base }))).digest('hex');
+}
+/**
+ * The accepted criteria a changed contract removes or rewrites. Adding a criterion strengthens an
+ * order; dropping one, or changing what one says or how it is checked, weakens it, and that is never
+ * an agent's decision.
+ */
+export function criteriaWeakening(accepted, changed) {
+    return accepted.criteria.flatMap(before => {
+        const after = changed.criteria.find(row => row.id === before.id);
+        if (!after)
+            return [`${before.id} is removed`];
+        return JSON.stringify(canonical(after)) === JSON.stringify(canonical(before)) ? [] : [`${before.id} is rewritten`];
+    });
+}
+// `**` crosses directories, `*` and `?` stay within one; a plain entry also covers what is below it.
+export function scopeMatches(scope, path) {
+    return scope.some(entry => {
+        if (!/[*?]/.test(entry))
+            return path === entry || path.startsWith(`${entry.replace(/\/$/, '')}/`);
+        const pattern = entry.split(/(\*\*\/?|\*|\?)/).map(part => part === '**' || part === '**/' ? '(?:.*/)?' + (part === '**' ? '.*' : '')
+            : part === '*' ? '[^/]*' : part === '?' ? '[^/]' : part.replace(/[.+^${}()|[\]\\]/g, '\\$&')).join('');
+        return new RegExp(`^${pattern}$`).test(path);
+    });
+}

package/dist/work-orders/store.d.ts

@@ -0,0 +1,158 @@
+import { z } from 'zod';
+export declare const WORK_RECORD_DIRECTORY = ".cockpit/work-orders";
+declare const CheckResult: z.ZodObject<{
+    criterion: z.ZodString;
+    kind: z.ZodEnum<{
+        argv: "argv";
+        gate: "gate";
+    }>;
+    passed: z.ZodBoolean;
+    outcome: z.ZodString;
+    output: z.ZodString;
+}, z.core.$strict>;
+export type CheckResult = z.infer<typeof CheckResult>;
+export declare const WorkRecord: z.ZodObject<{
+    format: z.ZodLiteral<"cockpit-work-order/v1">;
+    id: z.ZodString;
+    state: z.ZodEnum<{
+        abandoned: "abandoned";
+        accepted: "accepted";
+        checked: "checked";
+        done: "done";
+        graded: "graded";
+        partial: "partial";
+    }>;
+    accepted: z.ZodObject<{
+        at: z.ZodString;
+        by: z.ZodEnum<{
+            agent: "agent";
+            ci: "ci";
+            person: "person";
+        }>;
+        digest: z.ZodString;
+        order: z.ZodObject<{
+            id: z.ZodString;
+            objective: z.ZodString;
+            scope: z.ZodArray<z.ZodString>;
+            depends_on: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            gates: z.ZodDefault<z.ZodArray<z.ZodString>>;
+            criteria: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                text: z.ZodString;
+                check: z.ZodOptional<z.ZodUnion<readonly [z.ZodObject<{
+                    gate: z.ZodString;
+                    select: z.ZodOptional<z.ZodString>;
+                }, z.core.$strict>, z.ZodArray<z.ZodString>]>>;
+                source: z.ZodOptional<z.ZodString>;
+            }, z.core.$strict>>;
+            non_goals: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>;
+        sources: z.ZodRecord<z.ZodString, z.ZodString>;
+        base: z.ZodRecord<z.ZodString, z.ZodString>;
+    }, z.core.$strict>;
+    amendments: z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        by: z.ZodEnum<{
+            agent: "agent";
+            ci: "ci";
+            person: "person";
+        }>;
+        from: z.ZodString;
+        to: z.ZodString;
+        weakened: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    attempts: z.ZodNumber;
+    checks: z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        digest: z.ZodString;
+        results: z.ZodArray<z.ZodObject<{
+            criterion: z.ZodString;
+            kind: z.ZodEnum<{
+                argv: "argv";
+                gate: "gate";
+            }>;
+            passed: z.ZodBoolean;
+            outcome: z.ZodString;
+            output: z.ZodString;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    grade: z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        digest: z.ZodString;
+        mode: z.ZodEnum<{
+            checks: "checks";
+            independent: "independent";
+            self: "self";
+        }>;
+        passed: z.ZodBoolean;
+        criteria: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            verdict: z.ZodEnum<{
+                met: "met";
+                unclear: "unclear";
+                unmet: "unmet";
+            }>;
+            note: z.ZodString;
+        }, z.core.$strict>>;
+        outOfScope: z.ZodArray<z.ZodString>;
+        evaluator: z.ZodOptional<z.ZodObject<{
+            tool: z.ZodString;
+            fallbacks: z.ZodArray<z.ZodObject<{
+                tool: z.ZodString;
+                code: z.ZodString;
+                message: z.ZodString;
+            }, z.core.$strict>>;
+        }, z.core.$strict>>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+    notes: z.ZodArray<z.ZodObject<{
+        at: z.ZodString;
+        by: z.ZodEnum<{
+            agent: "agent";
+            ci: "ci";
+            person: "person";
+        }>;
+        kind: z.ZodEnum<{
+            answer: "answer";
+            note: "note";
+            question: "question";
+        }>;
+        text: z.ZodString;
+        answers: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    closure: z.ZodOptional<z.ZodObject<{
+        at: z.ZodString;
+        by: z.ZodEnum<{
+            agent: "agent";
+            ci: "ci";
+            person: "person";
+        }>;
+        how: z.ZodEnum<{
+            abandoned: "abandoned";
+            "checks-passed": "checks-passed";
+            graded: "graded";
+            partial: "partial";
+            "self-reported": "self-reported";
+        }>;
+        note: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+export type WorkRecord = z.infer<typeof WorkRecord>;
+/** Keeps the end of a command's output, where a runner prints its summary, within the record's bound. */
+export declare function outputTail(value: string): string;
+export interface WorkStore {
+    readonly read: (id: string) => Promise<WorkRecord | undefined>;
+    readonly list: () => Promise<readonly WorkRecord[]>;
+    /** Runs `change` holding the order's lock; it returns the next record, or undefined to write nothing. */
+    readonly update: <T>(id: string, change: (current: WorkRecord | undefined) => Promise<{
+        record?: WorkRecord;
+        value: T;
+    }>) => Promise<T>;
+    readonly recover: (id: string, apply: boolean) => Promise<Readonly<{
+        id: string;
+        lock: 'none' | 'live' | 'unknown' | 'dead' | 'removed';
+        holder?: string;
+    }>>;
+}
+export declare function createWorkStore(root: string): WorkStore;
+export {};

package/dist/work-orders/store.js

@@ -0,0 +1,197 @@
+// 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 { lstat, mkdir, open, readFile, readdir, rename, rm } from 'node:fs/promises';
+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(),
+    amendments: z.array(z.object({ at, by, from: z.string().length(64), to: z.string().length(64), weakened: z.array(z.string()).max(64) }).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(),
+    notes: z.array(z.object({ at, by: z.enum(['agent', 'person', 'ci']), kind: z.enum(['note', 'question', 'answer']), text: note,
+        answers: z.number().int().min(1).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(),
+}).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 holder as pid@start, so a reused pid never keeps a dead writer's lock alive.
+const holder = async () => {
+    const observed = await observeProcessStart(process.pid, processHost(executeProbe));
+    return observed.state === 'present' ? `${process.pid}@${observed.start}` : `${process.pid}`;
+};
+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');
+        const recorded = await holder();
+        try {
+            const handle = await open(path, 'wx', 0o644);
+            try {
+                await handle.writeFile(`${recorded}\n`);
+            }
+            finally {
+                await handle.close();
+            }
+        }
+        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`);
+        }
+        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) => {
+            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;
+            }
+            const recorded = text.trim();
+            const [pidText, start] = recorded.split('@', 2);
+            const observed = await observeProcessStart(Number(pidText), processHost(executeProbe));
+            // A lock whose writer is still running, or cannot be shown gone, is never removed: the write it guards may be in progress.
+            if (!isProcessGone(start, observed))
+                return { id, lock: observed.state === 'unknown' ? 'unknown' : 'live', holder: recorded };
+            if (!apply)
+                return { id, lock: 'dead', holder: recorded };
+            await rm(path, { force: true });
+            return { id, lock: 'removed', holder: recorded };
+        },
+    };
+    return store;
+}

package/docs/README.md

@@ -0,0 +1,65 @@
+# 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.
+- [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, browser checks and
+  test tiers.
+
+## 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.