@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/command-table.d.ts

@@ -1,10 +1,10 @@
 import type { ParseArgsConfig } from 'node:util';
-import type { GuardInvocationProfile } from './guards/evaluator.js';
+import { type GuardInvocationProfile } from './guards/evaluator.js';
 import { GUARD_HANDLER_ARGV } from './guards/harness-adapter.js';
 export declare function isRecordedAnswerField(value: string): boolean;
-export type WorkHandlerIdentifier = 'work-status' | 'work-accept' | 'work-check' | 'work-note' | 'work-answer' | 'work-grade' | 'work-signoff' | 'work-recover' | 'work-verify' | 'grade-criteria' | 'browser-drive' | 'browser-screenshot' | 'test-run';
-export type HandlerIdentifier = WorkHandlerIdentifier | 'check' | 'doctor' | 'down' | 'init' | 'logs' | 'preflight' | 'registry-resolve' | 'reset' | 'runtime' | 'setup' | 'selftest' | 'sibling' | 'tool' | 'session' | 'sleep' | 'sync' | 'up' | 'upgrade';
-export type CommandStage = 'set-up' | 'generate-and-verify' | 'run-the-stack' | 'diagnose' | 'test-and-grade';
+export type WorkHandlerIdentifier = 'work-status' | 'work-accept' | 'work-check' | 'work-note' | 'work-decide' | 'work-answer' | 'work-acknowledge' | 'work-grade' | 'work-signoff' | 'work-recover' | 'work-verify' | 'grade-criteria' | 'browser-drive' | 'browser-screenshot' | 'test-run';
+export type HandlerIdentifier = WorkHandlerIdentifier | 'check' | 'confirm' | 'docs-check' | 'doctor' | 'down' | 'exec' | 'init' | 'logs' | 'preflight' | 'ps' | 'rebuild' | 'registry-resolve' | 'reset' | 'restart' | 'runtime' | 'setup' | 'selftest' | 'sibling' | 'tool' | 'session' | 'sleep' | 'stacks' | 'sync' | 'up' | 'upgrade' | 'use' | 'pull';
+type CommandStage = 'set-up' | 'generate-and-verify' | 'run-the-stack' | 'diagnose' | 'test-and-grade';
 /** The order a newcomer meets the commands in, as the README's "Commands at a glance" table names it. */
 export declare const commandStages: readonly Readonly<{
     id: CommandStage;
@@ -41,14 +41,14 @@ export interface CommandDefinition {
     ordinary: OrdinaryCommandMetadata;
 }
 export declare function describePublicOption(name: string): string;
-type OrdinaryValueRole = 'confined-path' | 'resolved-config' | 'declared-service' | 'declared-gate' | 'gate-mode' | 'gate-selector' | 'identifier' | 'label' | 'field' | 'tail' | 'since' | 'sha256' | 'surface-target' | 'local-image' | 'evaluator-tool';
-export interface OrdinaryOption {
+type OrdinaryValueRole = 'confined-path' | 'resolved-config' | 'declared-service' | 'declared-gate' | 'gate-mode' | 'gate-selector' | 'identifier' | 'route' | 'label' | 'field' | 'tail' | 'since' | 'sha256' | 'surface-target' | 'local-image' | 'evaluator-tool' | 'compose-profile';
+interface OrdinaryOption {
     readonly kind: 'flag' | 'value';
     readonly role: 'boolean' | OrdinaryValueRole;
-    readonly repetition: 'singleton';
+    readonly repetition: 'singleton' | 'repeated';
     readonly required?: true;
 }
-export type OrdinaryCommandMetadata = Readonly<{
+type OrdinaryCommandMetadata = Readonly<{
     availability: 'unavailable';
     reason: string;
 }> | Readonly<{
@@ -58,7 +58,7 @@ export type OrdinaryCommandMetadata = Readonly<{
     positional: Readonly<{
         min: number;
         max: number;
-        roles: readonly ['confined-root'] | readonly ['operation'] | readonly ['version'] | readonly [];
+        roles: readonly ['confined-root'] | readonly ['operation'] | readonly ['version'] | readonly ['slug', 'confined-root'] | readonly ['operation', 'surface-target'] | readonly [];
         operations?: readonly string[];
     }>;
     options: Readonly<Record<string, OrdinaryOption>>;
@@ -67,11 +67,12 @@ export type OrdinaryCommandMetadata = Readonly<{
     forbidden: Readonly<{
         presence: readonly string[];
     }>;
+    admittedWhileUnsynced?: true;
     requires?: OrdinaryGrant;
 }>;
 export declare function isWorkHandler(value: HandlerIdentifier): value is WorkHandlerIdentifier;
 export declare const commands: readonly CommandDefinition[];
-export interface InternalCommandDefinition {
+interface InternalCommandDefinition {
     readonly name: 'guard-evaluate';
     readonly handler: 'guard-evaluate';
     readonly visibility: 'internal';
@@ -87,7 +88,7 @@ export interface InternalCommandDefinition {
     }>;
 }
 export declare const internalCommands: readonly InternalCommandDefinition[];
-export interface OrdinaryInvocationAuthority {
+interface OrdinaryInvocationAuthority {
     readonly executable: string;
     readonly canonicalRoot: string;
     readonly allowedRoots: readonly string[];
@@ -97,8 +98,14 @@ export interface OrdinaryInvocationAuthority {
     readonly gates: readonly string[];
     /** What the configuration grants an agent: browser preapproval, and the [autonomy] decisions set to agent. */
     readonly grants: readonly OrdinaryGrant[];
+    /** Compose profiles an agent may name with --profile; any other starts services no person declared for it. */
+    readonly profiles: readonly string[];
 }
 export type OrdinaryGrant = 'browser-preapproval' | 'autonomy-sync' | 'autonomy-reset';
+/** The commands the guard admits while a non-widening edit of cockpit.toml waits for sync. */
+export declare const UNSYNCED_ADMITTED_COMMANDS: readonly string[];
+/** The same commands as prose, for the hold that names them: "cockpit sync and check". */
+export declare const UNSYNCED_ADMITTED_PROSE: string;
 /**
  * The inner command of an exact `session --config <configured file> -- <command…>` run from the
  * cockpit root, or undefined. The guard admits the session only when it admits the inner command,
@@ -107,6 +114,7 @@ export type OrdinaryGrant = 'browser-preapproval' | 'autonomy-sync' | 'autonomy-
 export declare function ordinarySessionCommand(argv: readonly string[], cwd: string, authority: Readonly<{
     canonicalRoot: string;
     configPath: string;
+    profiles: readonly string[];
 }>): readonly string[] | undefined;
 /** Classify one exact candidate; the caller authenticates filesystem and executable authority. */
 export declare function resolveOrdinaryInvocation(input: GuardInvocationProfile, authority: OrdinaryInvocationAuthority, inspectPath: (path: string) => boolean): GuardInvocationProfile | undefined;

package/dist/command-table.js

@@ -2,6 +2,7 @@ import { SURFACE_TARGETS } from './surfaces/contract.js';
 import { isAbsolute, normalize, resolve } from 'node:path';
 import { WORK_ORDER_ID } from './work-orders/contract.js';
 import { snapshotJson } from './environment/contract.js';
+import { innerCommand, WRAPPING_COMMANDS } from './guards/evaluator.js';
 import { GUARD_HANDLER_ARGV } from './guards/harness-adapter.js';
 import { GUARD_INPUT_LIMITS } from './guards/invocation-parser.js';
 export function isRecordedAnswerField(value) {
@@ -23,6 +24,7 @@ export const commandStages = Object.freeze([
 export const commandGroups = Object.freeze([
     { name: 'work', summary: 'Accept, check, grade and close work orders' },
     { name: 'browser', summary: 'Drive, inspect and capture the declared application in a browser' },
+    { name: 'docs', summary: 'Check living documents and decision records against the repositories' },
 ]);
 /**
  * The public command an argv names, and the arguments after it. A group word takes the next word
@@ -42,6 +44,7 @@ const FLAG_DESCRIPTIONS = Object.freeze({
     'accept-preview': 'Accept the displayed init preview with its exact SHA-256 digest',
     'accept-reset': 'Accept the displayed answer reset with its exact SHA-256 digest',
     abandon: 'Close the order as abandoned; --note says why',
+    clear: 'Serve the sibling from its declared checkout again',
     adopt: 'Move one existing harness settings path under cockpit ownership',
     adoption: 'Path to the legacy adoption shell data',
     answers: 'Path to the init answers file',
@@ -50,6 +53,7 @@ const FLAG_DESCRIPTIONS = Object.freeze({
     command: 'With --scaffold-compose: the command that starts the app, as words separated by spaces',
     config: 'Path to cockpit.toml',
     create: 'Create a new local sibling repository',
+    decision: 'With work note: record the text as a decision the order made, resolved with work decide before signoff. With work decide: number of the decision to resolve, as work status lists it',
     criteria: 'Path to a file whose YAML front-matter lists the criteria to grade',
     dir: 'Directory for the sibling checkout',
     evaluator: 'Grade with only this agent tool (codexcli, claudecode or opencode), with no fallback to another',
@@ -66,16 +70,24 @@ const FLAG_DESCRIPTIONS = Object.freeze({
     note: 'What was checked, or what was and was not done',
     partial: 'Close the order as partly done; --note says what is left',
     port: 'With --scaffold-compose: the port the app listens on inside its container',
+    profile: 'Compose profile to activate beside environment.profiles; repeat it for several',
     'probe-specifications': 'Path to the harness probe specifications; with --write-probe-specifications, the earlier file whose filled rows for unchanged cells carry forward',
     purpose: 'Short purpose of the sibling repository',
     question: 'Number of the open question to answer, as work status lists it',
     registry: 'Path to the legacy registry input',
+    reason: 'With --none: why the decision is not a lasting one',
+    record: 'Write a new decision record under [docs] decisions for the decision',
+    'record-file': 'An existing decision record under [docs] decisions that cites the order',
+    supersedes: 'With --record: the number of the decision record the new one supersedes, which is marked superseded',
+    none: 'Resolve the decision as not lasting; --reason says why',
     'reset-answer': 'Preview clearing one recorded init answer field',
     remote: 'Repository remote URL recorded for the sibling',
     role: 'Declared browser role',
+    'fail-on-findings': 'Exit 2 when a route has console errors, uncaught errors or failed requests, for a criterion that wants a clean route',
+    route: 'Declared browser route to visit, by name or path; every declared route when omitted',
     'scaffold-compose': 'Write a starting compose.yml for the app in this directory, relative to the root, once; it refuses when a Compose file exists',
     select: 'Optional subset of the gate to run',
-    service: 'Declared service whose logs are collected',
+    service: 'Declared Compose service the command acts on',
     'siblings-root': 'Root directory containing sibling checkouts',
     since: 'Collect logs no older than this duration',
     tail: 'Maximum number of log records to collect',
@@ -97,6 +109,13 @@ export function describePublicOption(name) {
 }
 // Mirrors EvaluatorTool in schema.ts, which this data table may not import.
 const EVALUATOR_TOOLS = ['codexcli', 'claudecode', 'opencode'];
+// Mirrors UNCONFIRMABLE_ANSWERS in schema.ts. Every answer is admitted, so confirm itself names the
+// person an answer needs instead of the guard refusing it unexplained.
+const UNCONFIRMED_ANSWER_WORDS = Object.freeze(['cockpit.name', 'sibling', 'estate.runnable', 'ports.bases',
+    'environment.install_policies', 'environment.test_data', 'environment.compose_files', 'environment.machine', 'environment.posture',
+    'testing', 'guards']);
+// A declared route's name or its path; the command checks it against the declared routes.
+const ROUTE_SELECTOR = /^(?:[a-z0-9][a-z0-9_-]{0,63}|\/(?!\/)[^\s#\x00-\x1f\x7f]{0,511})$/;
 const EXACT_VERSION = /^(0|[1-9]\d*)\.(0|[1-9]\d*)\.(0|[1-9]\d*)(?:-[0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*)?$/;
 const flag = Object.freeze({ kind: 'flag', role: 'boolean', repetition: 'singleton' });
 function value(role, required = false) {
@@ -108,6 +127,8 @@ const configFlag = str(value('resolved-config', true));
 const jsonFlag = bool(flag);
 const configured = { config: configFlag, json: jsonFlag };
 const workOrderFlag = str(value('identifier', true));
+const profileFlag = { type: 'string', multiple: true, agent: { kind: 'value', role: 'compose-profile', repetition: 'repeated' } };
+const serviceFlag = str(value('declared-service', true));
 // The flags and their roles are filled in from `flags` when the table is built.
 function ordinary(command, extra = {}) {
     return { availability: 'available', executableRole: 'installed-cockpit', command,
@@ -150,6 +171,28 @@ const sources = [
         ordinary: ordinary('setup', { forbidden: Object.freeze({ presence: Object.freeze(['write-instruction-pointers', 'write-instruction-files']) }) }),
         flags: { config: configFlag, 'write-instruction-pointers': bool(), 'write-instruction-files': bool(), json: jsonFlag },
     },
+    {
+        name: 'use',
+        stage: 'set-up',
+        summary: 'Serve a sibling from another of its checkouts, such as a worktree',
+        usage: '<slug> <checkout> | <slug> --clear [options]',
+        handler: 'use',
+        visibility: 'public',
+        // The checkout must already lie inside a directory the guard lets the agent write, so an agent
+        // can point the stack at its own worktree but never widen its reach to a new directory.
+        ordinary: ordinary('use', { positional: Object.freeze({ min: 1, max: 2, roles: Object.freeze(['slug', 'confined-root']) }) }),
+        flags: { config: configFlag, clear: bool(flag), json: jsonFlag },
+    },
+    {
+        name: 'pull',
+        stage: 'set-up',
+        summary: 'Fast-forward the cockpit and its siblings to their upstreams',
+        handler: 'pull',
+        visibility: 'public',
+        // Fetch and a fast-forward only: it never merges, rebases, stashes or touches a modified checkout.
+        ordinary: ordinary('pull'),
+        flags: configured,
+    },
     {
         name: 'sibling',
         stage: 'set-up',
@@ -168,9 +211,25 @@ const sources = [
         usage: `add|remove <${SURFACE_TARGETS.join('|')}> [options]`,
         handler: 'tool',
         visibility: 'public',
-        // Classified with sibling add and remove: both rewrite cockpit.toml.
-        ordinary: unavailable('tool add and remove rewrite cockpit.toml'),
-        flags: { config: str(), 'dry-run': bool(), json: bool() },
+        // tool add edits only [surfaces] tools, and an added tool never widens what agents may do, so the
+        // agent syncs it as [autonomy] sync allows. tool remove deletes that tool's guard, so it is a person's.
+        ordinary: ordinary('tool', { positional: Object.freeze({ min: 2, max: 2, roles: Object.freeze(['operation', 'surface-target']),
+                operations: Object.freeze(['add']) }) }),
+        flags: { config: configFlag, 'dry-run': bool(flag), json: jsonFlag },
+    },
+    {
+        name: 'confirm',
+        stage: 'set-up',
+        summary: 'Confirm an init answer no person stated by running the observation that verifies it',
+        usage: '<answer> [options]',
+        handler: 'confirm',
+        visibility: 'public',
+        // It removes an entry from unconfirmed only after an observation of this machine and the running
+        // stack passes, and records that observation where only cockpit writes; the guard then treats the
+        // removal as non-widening. It refuses the answers a person must confirm.
+        ordinary: ordinary('confirm', { positional: Object.freeze({ min: 1, max: 1, roles: Object.freeze(['operation']),
+                operations: UNCONFIRMED_ANSWER_WORDS }) }),
+        flags: configured,
     },
     {
         name: 'registry-resolve',
@@ -204,7 +263,8 @@ const sources = [
         // Adoption rewrites cockpit.toml and moves a team's harness settings, so it stays a person's. A
         // real sync rewrites the guard's own files from a configuration the guard already pins and
         // holds every call after an edit to, so it is an agent's only where [autonomy] sync = "agent".
-        ordinary: ordinary('sync', { forbidden: Object.freeze({ presence: Object.freeze(['interactive', 'adopt']) }), requires: 'autonomy-sync' }),
+        ordinary: ordinary('sync', { forbidden: Object.freeze({ presence: Object.freeze(['interactive', 'adopt']) }), requires: 'autonomy-sync',
+            admittedWhileUnsynced: true }),
         flags: { config: configFlag, 'dry-run': bool(flag), adopt: { type: 'string', multiple: true }, interactive: bool(), json: jsonFlag },
     },
     {
@@ -213,7 +273,7 @@ const sources = [
         summary: 'Report generated files that no longer match cockpit.toml',
         handler: 'check',
         visibility: 'public',
-        ordinary: ordinary('check'),
+        ordinary: ordinary('check', { admittedWhileUnsynced: true }),
         flags: configured,
     },
     {
@@ -247,7 +307,7 @@ const sources = [
         handler: 'up',
         visibility: 'public',
         ordinary: ordinary('up'),
-        flags: configured,
+        flags: { ...configured, profile: profileFlag },
     },
     {
         name: 'preflight',
@@ -265,9 +325,10 @@ const sources = [
         usage: '[options] -- <command> [args...]',
         handler: 'session',
         visibility: 'public',
-        // The guard admits `session --config <file> -- <command>` only when it admits the inner command.
+        // The guard admits `session --config <file> [--profile <name>]... -- <command>` only when it
+        // admits the inner command.
         ordinary: unavailable('session wraps an arbitrary foreground command'),
-        flags: { config: str() },
+        flags: { config: str(), profile: { type: 'string', multiple: true } },
     },
     {
         name: 'logs',
@@ -276,9 +337,49 @@ const sources = [
         handler: 'logs',
         visibility: 'public',
         ordinary: ordinary('logs'),
-        flags: { config: configFlag, service: str(value('declared-service', true)), tail: str(value('tail'), '100'), since: str(value('since'), '15m'),
+        flags: { config: configFlag, service: serviceFlag, tail: str(value('tail'), '100'), since: str(value('since'), '15m'),
             follow: bool(flag), json: jsonFlag },
     },
+    {
+        name: 'ps',
+        stage: 'run-the-stack',
+        summary: 'Show the state and health of each service in this checkout\'s stack',
+        handler: 'ps',
+        visibility: 'public',
+        ordinary: ordinary('ps'),
+        flags: configured,
+    },
+    // The service verbs act only on this checkout's own leased stack, as up does, so an agent runs
+    // them as it runs up; reset, which deletes data, stays gated.
+    {
+        name: 'restart',
+        stage: 'run-the-stack',
+        summary: 'Restart one service of this checkout\'s stack and wait until it is healthy',
+        handler: 'restart',
+        visibility: 'public',
+        ordinary: ordinary('restart'),
+        flags: { ...configured, service: serviceFlag },
+    },
+    {
+        name: 'rebuild',
+        stage: 'run-the-stack',
+        summary: 'Rebuild one service\'s image, replace its container and wait until it is healthy',
+        handler: 'rebuild',
+        visibility: 'public',
+        ordinary: ordinary('rebuild'),
+        flags: { ...configured, service: serviceFlag },
+    },
+    {
+        name: 'exec',
+        stage: 'run-the-stack',
+        summary: 'Run a command inside one service\'s container of this checkout\'s stack',
+        usage: '--service <name> [options] -- <command> [args...]',
+        handler: 'exec',
+        visibility: 'public',
+        // The grammar admits the spelling; the evaluator judges the container command.
+        ordinary: ordinary('exec'),
+        flags: { config: configFlag, service: serviceFlag },
+    },
     {
         name: 'sleep',
         stage: 'run-the-stack',
@@ -308,6 +409,21 @@ const sources = [
         ordinary: ordinary('reset', { requires: 'autonomy-reset' }),
         flags: { config: configFlag, interactive: bool(), apply: bool(Object.freeze({ ...flag, required: true })), json: jsonFlag },
     },
+    {
+        name: 'stacks',
+        stage: 'run-the-stack',
+        summary: 'List every stack on this machine, or preview and remove those whose checkout is gone (stacks prune)',
+        usage: '[prune] [options]',
+        handler: 'stacks',
+        visibility: 'public',
+        // Listing and the prune preview change nothing. --apply removes only stacks whose checkout is
+        // gone; the command itself refuses one that deletes volumes unless [autonomy] reset allows it.
+        ordinary: ordinary('stacks', {
+            positional: Object.freeze({ min: 0, max: 1, roles: Object.freeze(['operation']), operations: Object.freeze(['prune']) }),
+            ...personFlag,
+        }),
+        flags: { config: configFlag, apply: bool(flag), interactive: bool(), json: jsonFlag },
+    },
     {
         name: 'doctor',
         stage: 'diagnose',
@@ -333,12 +449,20 @@ const sources = [
     { name: 'work check', handler: 'work-check', stage: 'test-and-grade', summary: "Run every criterion's check and the order's gates", visibility: 'public',
         ordinary: ordinary('work-check'),
         flags: { ...configured, 'work-order': workOrderFlag } },
-    { name: 'work note', handler: 'work-note', stage: 'test-and-grade', summary: 'Record a note on an order, or with --ask an open question that blocks it', visibility: 'public',
+    { name: 'work note', handler: 'work-note', stage: 'test-and-grade', summary: 'Record a note on an order, an open question with --ask, or a decision with --decision', visibility: 'public',
         ordinary: ordinary('work-note'),
-        flags: { ...configured, 'work-order': workOrderFlag, text: str(value('label', true)), ask: bool(flag) } },
+        flags: { ...configured, 'work-order': workOrderFlag, text: str(value('label', true)), ask: bool(flag), decision: bool(flag) } },
+    // Resolving a decision passes no gate of its own: a --none resolution is shown in the signoff prompt, which the signoff gate covers.
+    { name: 'work decide', handler: 'work-decide', stage: 'test-and-grade', summary: 'Resolve a recorded decision: write or cite its decision record, or say it is not lasting', visibility: 'public',
+        ordinary: ordinary('work-decide'),
+        flags: { ...configured, 'work-order': workOrderFlag, decision: str(value('tail', true)), record: bool(flag), 'record-file': str(value('label')),
+            supersedes: str(value('label')), none: bool(flag), reason: str(value('label')) } },
     { name: 'work answer', handler: 'work-answer', stage: 'test-and-grade', summary: 'Answer an open question on an order, as [work.gates] allows', visibility: 'public',
         ordinary: ordinary('work-answer', personFlag),
         flags: { ...configured, 'work-order': workOrderFlag, question: str(value('tail', true)), text: str(value('label', true)), interactive: bool() } },
+    { name: 'work acknowledge', handler: 'work-acknowledge', stage: 'test-and-grade', summary: 'Acknowledge that an order weakened tests, as [work.gates] allows', visibility: 'public',
+        ordinary: ordinary('work-acknowledge', personFlag),
+        flags: { ...configured, 'work-order': workOrderFlag, note: str(value('label', true)), interactive: bool() } },
     // Grading hands the order to an evaluator running apart from the agent that did the work, unless
     // [work] grading names checks or self.
     { name: 'work grade', handler: 'work-grade', stage: 'test-and-grade', summary: 'Grade an accepted order the way [work] grading says', visibility: 'public',
@@ -347,12 +471,11 @@ const sources = [
     { name: 'work signoff', handler: 'work-signoff', stage: 'test-and-grade', summary: 'Close a graded order as done, or any open one as partial or abandoned', visibility: 'public',
         ordinary: ordinary('work-signoff', personFlag),
         flags: { ...configured, 'work-order': workOrderFlag, partial: bool(flag), abandon: bool(flag), note: str(value('label')), interactive: bool() } },
-    // Inspection only reports the holder. --apply deletes the lock once a pid probe calls its holder
-    // dead, and that probe sees only this machine's process table: a holder running in a container or
-    // on another host that shares the checkout looks dead to it, so a person confirms it is gone.
+    // Inspection only reports the holder. --apply removes the lock only once the command has shown its
+    // holder gone where a pid probe cannot see: the lock's host and the containers cockpit labels.
     { name: 'work recover', handler: 'work-recover', stage: 'test-and-grade', summary: "Inspect or remove a crashed command's work-order lock", visibility: 'public',
-        ordinary: ordinary('work-recover', { forbidden: Object.freeze({ presence: Object.freeze(['apply']) }) }),
-        flags: { ...configured, 'work-order': workOrderFlag, apply: bool() } },
+        ordinary: ordinary('work-recover'),
+        flags: { ...configured, 'work-order': workOrderFlag, apply: bool(flag) } },
     { name: 'work verify', handler: 'work-verify', stage: 'test-and-grade', summary: 'Check every record against its order; in CI, pass the steps gated on ci', visibility: 'public',
         ordinary: ordinary('work-verify'),
         flags: configured },
@@ -363,10 +486,15 @@ const sources = [
     // person wrote down as safe for that.
     { name: 'browser drive', handler: 'browser-drive', stage: 'test-and-grade', summary: 'Drive the declared application browser surfaces', visibility: 'public',
         ordinary: ordinary('browser-drive', browserAdmission),
-        flags: { ...configured, role: str(value('identifier')) } },
+        // Findings are evidence by default; this makes them fail the command, for a criterion that wants a clean route.
+        flags: { ...configured, role: str(value('identifier')), route: str(value('route')), 'fail-on-findings': bool(flag) } },
     { name: 'browser screenshot', handler: 'browser-screenshot', stage: 'test-and-grade', summary: 'Capture the declared application surfaces', visibility: 'public',
         ordinary: ordinary('browser-screenshot', browserAdmission),
-        flags: { ...configured, role: str(value('identifier')) } },
+        flags: { ...configured, role: str(value('identifier')), route: str(value('route')) } },
+    // Reads documents and runs read-only Git, like check; it writes nothing, so an agent runs it freely.
+    { name: 'docs check', handler: 'docs-check', stage: 'test-and-grade', summary: 'Report removed paths and make targets living docs still cite, and broken decision records', visibility: 'public',
+        ordinary: ordinary('docs-check'),
+        flags: configured },
 ];
 export const commands = sources.map(({ flags, ...command }) => {
     const entries = Object.entries(flags);
@@ -384,6 +512,8 @@ export const internalCommands = Object.freeze([Object.freeze({
 const ORDINARY_GRANTS = ['browser-preapproval', 'autonomy-sync', 'autonomy-reset'];
 // An image reference or ID as Docker spells it; the command itself refuses one that is not local.
 const LOCAL_IMAGE = /^[A-Za-z0-9][A-Za-z0-9._/:@-]{0,255}$/;
+// The spelling environment.profiles accepts.
+const COMPOSE_PROFILE = /^[a-z0-9][a-z0-9_.-]{0,63}$/;
 // A selected value that starts with `-` would reach the product's tool as an option of its own.
 const GATE_SELECTOR = /^(?:spec|file|test|route):[^-]/;
 function canonicalPath(path) {
@@ -394,19 +524,31 @@ function canonicalPath(path) {
 function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+/** The commands the guard admits while a non-widening edit of cockpit.toml waits for sync. */
+export const UNSYNCED_ADMITTED_COMMANDS = Object.freeze(commands.flatMap(row => row.ordinary.availability === 'available' && row.ordinary.admittedWhileUnsynced ? [row.name] : []));
+/** The same commands as prose, for the hold that names them: "cockpit sync and check". */
+export const UNSYNCED_ADMITTED_PROSE = `cockpit ${new Intl.ListFormat('en', { type: 'conjunction' }).format(UNSYNCED_ADMITTED_COMMANDS)}`;
 /**
  * The inner command of an exact `session --config <configured file> -- <command…>` run from the
  * cockpit root, or undefined. The guard admits the session only when it admits the inner command,
  * so a session never runs what the agent could not run directly.
  */
 export function ordinarySessionCommand(argv, cwd, authority) {
-    const separator = argv.indexOf('--');
-    if (argv[0] !== 'session' || separator < 0 || separator === argv.length - 1 || cwd !== authority.canonicalRoot)
+    const inner = innerCommand(argv);
+    if (argv[0] !== 'session' || !inner || cwd !== authority.canonicalRoot)
         return undefined;
-    const options = argv.slice(1, separator);
-    const config = options.length === 2 && options[0] === '--config' ? options[1]
-        : options.length === 1 && options[0].startsWith('--config=') ? options[0].slice('--config='.length) : undefined;
-    return config && resolve(cwd, config) === authority.configPath ? argv.slice(separator + 1) : undefined;
+    const options = argv.slice(1, argv.length - inner.words.length - 1);
+    let config;
+    for (let index = 0; index < options.length; index++) {
+        const [name, inline] = options[index].startsWith('--') && options[index].includes('=')
+            ? [options[index].slice(0, options[index].indexOf('=')), options[index].slice(options[index].indexOf('=') + 1)]
+            : [options[index], options[++index]];
+        if (name === '--config' && config === undefined && inline !== undefined)
+            config = inline;
+        else if (name !== '--profile' || inline === undefined || !authority.profiles.includes(inline))
+            return undefined;
+    }
+    return config && resolve(cwd, config) === authority.configPath ? inner.words : undefined;
 }
 /** Classify one exact candidate; the caller authenticates filesystem and executable authority. */
 export function resolveOrdinaryInvocation(input, authority, inspectPath) {
@@ -415,7 +557,7 @@ export function resolveOrdinaryInvocation(input, authority, inspectPath) {
     if (!record(candidate)
         || Object.keys(candidate).sort().join(',') !== 'argv,cwd,executable'
         || !record(captured)
-        || Object.keys(captured).sort().join(',') !== 'allowedRoots,canonicalRoot,configPath,executable,gates,grants,services')
+        || Object.keys(captured).sort().join(',') !== 'allowedRoots,canonicalRoot,configPath,executable,gates,grants,profiles,services')
         return undefined;
     const source = captured;
     if (!canonicalPath(source.executable) || !canonicalPath(source.canonicalRoot) || !canonicalPath(source.configPath)
@@ -424,6 +566,7 @@ export function resolveOrdinaryInvocation(input, authority, inspectPath) {
         || !Array.isArray(source.services) || !source.services.every(service => typeof service === 'string' && /^[a-z0-9][a-z0-9_.-]{0,127}$/.test(service))
         || !Array.isArray(source.gates) || !source.gates.every(gate => typeof gate === 'string' && /^[a-z][a-z0-9-]{0,63}$/.test(gate))
         || !Array.isArray(source.grants) || !source.grants.every(grant => ORDINARY_GRANTS.includes(grant))
+        || !Array.isArray(source.profiles) || !source.profiles.every(profile => typeof profile === 'string' && COMPOSE_PROFILE.test(profile))
         || candidate.executable !== source.executable || candidate.cwd !== source.canonicalRoot
         || !Array.isArray(candidate.argv) || candidate.argv.length === 0 || candidate.argv.length > GUARD_INPUT_LIMITS.words
         || !candidate.argv.every(arg => typeof arg === 'string' && arg.length > 0
@@ -452,7 +595,12 @@ export function resolveOrdinaryInvocation(input, authority, inspectPath) {
     const reads = [];
     const positionals = [];
     const options = new Map();
-    const words = spelling.rest;
+    const wraps = WRAPPING_COMMANDS.has(definition.name);
+    const separator = wraps ? spelling.rest.indexOf('--') : -1;
+    // The wrapped command is required and is the only thing after `--`.
+    if (wraps && (separator < 0 || separator === spelling.rest.length - 1))
+        return undefined;
+    const words = separator < 0 ? spelling.rest : spelling.rest.slice(0, separator);
     for (let index = 0; index < words.length; index++) {
         const arg = words[index];
         if (!arg.startsWith('-')) {
@@ -464,7 +612,7 @@ export function resolveOrdinaryInvocation(input, authority, inspectPath) {
         const equal = arg.indexOf('=');
         const name = arg.slice(2, equal < 0 ? undefined : equal);
         const option = grammar.options[name];
-        if (!option || options.has(name) || grammar.forbidden.presence.includes(name))
+        if (!option || options.has(name) && option.repetition !== 'repeated' || grammar.forbidden.presence.includes(name))
             return undefined;
         if (option.kind === 'flag') {
             if (equal >= 0)
@@ -484,15 +632,17 @@ export function resolveOrdinaryInvocation(input, authority, inspectPath) {
                         : option.role === 'gate-mode' ? ['canonical', 'full', 'staged'].includes(text)
                             : option.role === 'gate-selector' ? GATE_SELECTOR.test(text)
                                 : option.role === 'identifier' ? WORK_ORDER_ID.test(text)
-                                    : option.role === 'label' ? true
-                                        : option.role === 'field' ? isRecordedAnswerField(text)
-                                            : option.role === 'tail' ? /^[1-9]\d{0,4}$/.test(text) && Number(text) <= 10_000
-                                                : option.role === 'since' ? text.length <= 64 && (/^\d+(?:\.\d+)?[smhd]$/.test(text)
-                                                    || /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,9})?(?:Z|[+-]\d\d:\d\d)$/.test(text) && Number.isFinite(Date.parse(text)))
-                                                    : option.role === 'surface-target' ? text.split(',').every(tool => SURFACE_TARGETS.some(target => target === tool))
-                                                        : option.role === 'evaluator-tool' ? EVALUATOR_TOOLS.includes(text)
-                                                            : option.role === 'local-image' ? LOCAL_IMAGE.test(text)
-                                                                : option.role === 'sha256' && /^[a-f0-9]{64}$/.test(text);
+                                    : option.role === 'route' ? ROUTE_SELECTOR.test(text)
+                                        : option.role === 'label' ? true
+                                            : option.role === 'field' ? isRecordedAnswerField(text)
+                                                : option.role === 'tail' ? /^[1-9]\d{0,4}$/.test(text) && Number(text) <= 10_000
+                                                    : option.role === 'since' ? text.length <= 64 && (/^\d+(?:\.\d+)?[smhd]$/.test(text)
+                                                        || /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d(?:\.\d{1,9})?(?:Z|[+-]\d\d:\d\d)$/.test(text) && Number.isFinite(Date.parse(text)))
+                                                        : option.role === 'surface-target' ? text.split(',').every(tool => SURFACE_TARGETS.some(target => target === tool))
+                                                            : option.role === 'evaluator-tool' ? EVALUATOR_TOOLS.includes(text)
+                                                                : option.role === 'local-image' ? LOCAL_IMAGE.test(text)
+                                                                    : option.role === 'compose-profile' ? source.profiles.includes(text)
+                                                                        : option.role === 'sha256' && /^[a-f0-9]{64}$/.test(text);
         if (!valid)
             return undefined;
         options.set(name, text);
@@ -501,7 +651,9 @@ export function resolveOrdinaryInvocation(input, authority, inspectPath) {
         || positionals.some((word, index) => grammar.positional.roles[index] === 'operation'
             ? !grammar.positional.operations?.includes(word)
             : grammar.positional.roles[index] === 'version' ? !EXACT_VERSION.test(word)
-                : grammar.positional.roles[index] !== 'confined-root' || !confined(word))
+                : grammar.positional.roles[index] === 'slug' ? !/^[a-z0-9][a-z0-9-]{0,62}$/.test(word)
+                    : grammar.positional.roles[index] === 'surface-target' ? !SURFACE_TARGETS.some(target => target === word)
+                        : grammar.positional.roles[index] !== 'confined-root' || !confined(word))
         || Object.entries(grammar.options).some(([name, option]) => option.required && !options.has(name))
         // A dry run writes nothing, so no grant gates it.
         || grammar.requires !== undefined && !options.has('dry-run') && !source.grants.includes(grammar.requires)

package/dist/config/load.d.ts

@@ -1,9 +1,14 @@
 import { type ConfigSourceSnapshot, type EnvironmentCommandOutcome, type EnvironmentDiagnostic, type SourceProvenance } from '../environment/contract.js';
 import { type EffectivePolicy } from '../autonomy.js';
-import { CockpitConfig, type EvaluatorTool } from '../schema.js';
+import { browserDataQualifies, CockpitConfig, type EvaluatorTool } from '../schema.js';
+/** An explicit request_preapproval wins; otherwise preapproval follows the declared data posture. */
+export declare const browserPreapprovalRequested: (browser: Readonly<{
+    request_preapproval?: boolean | undefined;
+    data: Parameters<typeof browserDataQualifies>[0];
+}>) => boolean;
 import { type BoundedRead } from '../bounded-read.js';
 export declare const STRUCTURED_INPUT_BYTE_LIMIT = 1048576;
-export type BoundedInputRead = BoundedRead;
+type BoundedInputRead = BoundedRead;
 export declare function readBoundedInput(path: string): Promise<BoundedInputRead>;
 declare const loadedConfigProjectionBrand: unique symbol;
 export type LoadedConfigProjection = LoadedCockpitConfig;
@@ -29,7 +34,7 @@ export interface LoadedCockpitConfig {
 export interface MachineFloorConfigProjection {
     readonly kind: 'machine-floor-config-projection';
 }
-export interface ConsumedMachineFloorConfig {
+interface ConsumedMachineFloorConfig {
     readonly cockpitName: string;
     readonly source: SourceProvenance;
     readonly runtimeSha256: string;
@@ -39,7 +44,7 @@ export interface ConsumedMachineFloorConfig {
         freeDiskMb: number;
     }>;
 }
-export interface WorkEnvironmentConfigProjection {
+interface WorkEnvironmentConfigProjection {
     readonly kind: 'work-environment-config-projection';
 }
 export interface ConsumedWorkEnvironmentConfig {
@@ -66,6 +71,10 @@ export interface ConsumedWorkEnvironmentConfig {
     readonly generatedHostPaths: readonly string[];
     readonly browser?: ReturnType<typeof projectBrowserConfig>;
     readonly testing?: ReturnType<typeof projectTestingConfig>;
+    readonly docs?: Readonly<{
+        decisions?: string;
+        decisionsIndex?: string;
+    }>;
 }
 declare function projectBrowserConfig(declaredBrowser: NonNullable<CockpitConfig['browser']>): {
     engine: "chromium" | "firefox" | "webkit";
@@ -139,6 +148,7 @@ declare function projectTestingConfig(declaredTesting: NonNullable<CockpitConfig
         }[];
     };
     nativeHookInstall: "explicit-native" | "inspect";
+    testFiles?: string[] | undefined;
     nativeHookPolicy?: {
         path: string;
         sha256: string;
@@ -162,6 +172,8 @@ export declare function loadAutonomyPolicy(configPath: string): Promise<Readonly
 }> | Readonly<{
     refusal: EnvironmentDiagnostic;
 }>>;
+/** The configuration `bytes` declare, or undefined when they are not UTF-8 TOML the schema accepts. */
+export declare function parseCockpitConfigBytes(bytes: Uint8Array): CockpitConfig | undefined;
 export declare function loadCockpitConfig(inputPath: string): Promise<EnvironmentCommandOutcome<LoadedCockpitConfig>>;
 /**
  * The evaluators work grade and cockpit grade try, in order. Left unset, they are the listed agent