@b00dea/cockpit 0.0.0-stage → 0.1.1

package/dist/command-table.js

@@ -0,0 +1,664 @@
+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) {
+    return value.length <= 256 && /^[a-z][a-z0-9]*(?:[._-][a-z0-9]+)*$/.test(value);
+}
+/** The order a newcomer meets the commands in, as the README's "Commands at a glance" table names it. */
+export const commandStages = Object.freeze([
+    { id: 'set-up', title: 'Set up' },
+    { id: 'generate-and-verify', title: 'Generate and verify' },
+    { id: 'run-the-stack', title: 'Run the stack' },
+    { id: 'diagnose', title: 'Diagnose' },
+    { id: 'test-and-grade', title: 'Test and grade' },
+]);
+/**
+ * A group is a first command word whose commands are named `<group> <subcommand>`. Each subcommand
+ * keeps its own row, options and handler, so an option one subcommand reads is never accepted and
+ * ignored by another.
+ */
+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
+ * as its subcommand; `subcommand` is absent when none follows, so the caller can show the group.
+ */
+export function commandSpelling(args) {
+    const [first, second, ...rest] = args;
+    const group = commandGroups.find(row => row.name === first);
+    if (!group)
+        return { name: first, rest: second === undefined ? [] : [second, ...rest] };
+    if (second === undefined || second.startsWith('-'))
+        return { name: undefined, group: group.name, rest: second === undefined ? [] : [second, ...rest] };
+    return { name: `${group.name} ${second}`, group: group.name, rest };
+}
+const FLAG_DESCRIPTIONS = Object.freeze({
+    'accept-defaults': 'Accept the displayed defaults with their exact SHA-256 digest',
+    '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',
+    ask: 'Record the note as an open question, which blocks the order until it is answered',
+    apply: 'Apply the displayed reversible operation',
+    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',
+    'dry-run': 'Preview without writing or installing anything',
+    follow: 'Continue collecting logs until cancelled',
+    from: 'Path to an existing local repository',
+    gate: 'Declared product gate to run',
+    image: 'Local container image the runtime measurement probe runs; it is never pulled',
+    'instruction-pointer': 'Offer a marked AGENTS.md link for this separate sibling',
+    interactive: 'Ask for explicit approval in a terminal',
+    json: 'Emit one machine-readable JSON response',
+    mode: 'Declared gate execution mode',
+    mount: 'How the stack uses the sibling: always, none or profile:<name>',
+    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 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',
+    target: 'Agent tool to set up; comma-separate several (claudecode,opencode)',
+    text: 'Text of the note or answer',
+    var: 'Environment variable mapping for the sibling',
+    verdict: 'Under [work] grading = "self": met or unmet',
+    with: 'With --scaffold-compose: backing services to add, from postgres and redis, separated by commas',
+    'work-order': 'Work-order identifier',
+    'write-probe-specifications': 'Write a probe-specification file for the current manifest to this new path, with the probe fields left for you',
+    'write-instruction-pointers': 'Write the reviewed instruction links into opted-in sibling guides',
+    'write-instruction-files': 'Write the reviewed AGENTS.md and CLAUDE.md changes that let every agent tool load a sibling\'s instructions',
+});
+export function describePublicOption(name) {
+    const description = FLAG_DESCRIPTIONS[name];
+    if (!description)
+        throw new Error(`Public option --${name} has no help description.`);
+    return description;
+}
+// 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) {
+    return { kind: 'value', role, repetition: 'singleton', ...(required ? { required: true } : {}) };
+}
+const str = (agent, fallback) => ({ type: 'string', ...fallback === undefined ? {} : { default: fallback }, ...agent ? { agent } : {} });
+const bool = (agent) => ({ type: 'boolean', default: false, ...agent ? { agent } : {} });
+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,
+        positional: { min: 0, max: 0, roles: [] }, options: {},
+        cwdRole: 'canonical-root', configuration: 'resolved',
+        forbidden: { presence: [] }, ...extra };
+}
+function unavailable(reason) { return { availability: 'unavailable', reason }; }
+const browserAdmission = Object.freeze({ requires: 'browser-preapproval' });
+// --interactive asks for a person at a terminal, so an agent invocation never carries it.
+const personFlag = Object.freeze({ forbidden: Object.freeze({ presence: Object.freeze(['interactive']) }) });
+export function isWorkHandler(value) {
+    return value.startsWith('work-') || value.startsWith('browser-') || value === 'test-run' || value === 'grade-criteria';
+}
+const sources = [
+    {
+        name: 'init',
+        stage: 'set-up',
+        summary: 'Preview, then accept, a first cockpit setup for one or more agent tools',
+        usage: '[<root>] [options]',
+        handler: 'init',
+        visibility: 'public',
+        ordinary: ordinary('init', {
+            configuration: 'none',
+            positional: Object.freeze({ min: 1, max: 1, roles: Object.freeze(['confined-root']) }),
+            forbidden: Object.freeze({ presence: Object.freeze(['interactive', 'answers', 'accept-preview', 'accept-defaults']) }),
+        }),
+        flags: { target: str(value('surface-target', true)), registry: str(value('confined-path')),
+            interactive: bool(), json: jsonFlag,
+            answers: str(), 'accept-preview': str(), 'accept-defaults': str(),
+            'reset-answer': str(value('field')), 'accept-reset': str(value('sha256')),
+            'scaffold-compose': str(), command: str(), port: str(), with: str() },
+    },
+    {
+        name: 'setup',
+        stage: 'set-up',
+        summary: 'Clone or locate the declared sibling repositories and link them',
+        handler: 'setup',
+        visibility: 'public',
+        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',
+        summary: 'Add or remove a repository in cockpit.toml (sibling add, sibling remove)',
+        usage: 'add|remove <slug> [options]',
+        handler: 'sibling',
+        visibility: 'public',
+        ordinary: unavailable('sibling add and remove rewrite cockpit.toml'),
+        flags: { config: str(), create: bool(), from: str(), remote: str(), dir: str(), var: str(), purpose: str(), mount: str(),
+            'instruction-pointer': bool(), json: bool() },
+    },
+    {
+        name: 'tool',
+        stage: 'set-up',
+        summary: 'Add or remove an agent tool in cockpit.toml (tool add, tool remove)',
+        usage: `add|remove <${SURFACE_TARGETS.join('|')}> [options]`,
+        handler: 'tool',
+        visibility: 'public',
+        // 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',
+        stage: 'set-up',
+        summary: 'Turn a validated shell registry into data shell scripts can source',
+        handler: 'registry-resolve',
+        visibility: 'public',
+        ordinary: ordinary('registry-resolve', { configuration: 'none' }),
+        flags: { registry: str(value('confined-path', true)), 'siblings-root': str(value('confined-path', true)), adoption: str(value('confined-path', true)), json: jsonFlag },
+    },
+    {
+        name: 'upgrade',
+        stage: 'set-up',
+        summary: 'Move the exact cockpit pin to a newer version and re-run sync',
+        usage: '[<version>] [options]',
+        handler: 'upgrade',
+        visibility: 'public',
+        // The install is exact and its sync child decides as sync does, so an agent runs the real upgrade
+        // exactly where [autonomy] sync lets it sync; the version is the one positional.
+        ordinary: ordinary('upgrade', {
+            positional: Object.freeze({ min: 0, max: 1, roles: Object.freeze(['version']) }), requires: 'autonomy-sync'
+        }),
+        flags: { config: configFlag, 'dry-run': bool(flag) },
+    },
+    {
+        name: 'sync',
+        stage: 'generate-and-verify',
+        summary: 'Write the Compose ownership override and agent files from cockpit.toml',
+        handler: 'sync',
+        visibility: 'public',
+        // 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',
+            admittedWhileUnsynced: true }),
+        flags: { config: configFlag, 'dry-run': bool(flag), adopt: { type: 'string', multiple: true }, interactive: bool(), json: jsonFlag },
+    },
+    {
+        name: 'check',
+        stage: 'generate-and-verify',
+        summary: 'Report generated files that no longer match cockpit.toml',
+        handler: 'check',
+        visibility: 'public',
+        ordinary: ordinary('check', { admittedWhileUnsynced: true }),
+        flags: configured,
+    },
+    {
+        name: 'selftest',
+        stage: 'generate-and-verify',
+        summary: 'Test whether agent tools enforce the generated controls',
+        handler: 'selftest',
+        visibility: 'public',
+        ordinary: ordinary('selftest', { forbidden: Object.freeze({ presence: Object.freeze(['interactive']) }) }),
+        flags: { config: configFlag, 'probe-specifications': str(value('confined-path', true)), 'write-probe-specifications': str(),
+            interactive: bool(), json: jsonFlag },
+    },
+    {
+        name: 'runtime',
+        stage: 'run-the-stack',
+        summary: 'Measure the local container runtime (runtime measure) and record the result for this machine',
+        usage: 'measure [options]',
+        handler: 'runtime',
+        visibility: 'public',
+        // The probe runs a disposable stack under its own project, cleans it up, and records the result
+        // only in this machine's ignored state, so an agent can measure before its first `up`.
+        ordinary: ordinary('runtime', {
+            positional: Object.freeze({ min: 1, max: 1, roles: Object.freeze(['operation']), operations: Object.freeze(['measure']) }),
+        }),
+        flags: { config: configFlag, image: str(value('local-image', true)), json: jsonFlag },
+    },
+    {
+        name: 'up',
+        stage: 'run-the-stack',
+        summary: 'Start or resume the declared environment',
+        handler: 'up',
+        visibility: 'public',
+        ordinary: ordinary('up'),
+        flags: { ...configured, profile: profileFlag },
+    },
+    {
+        name: 'preflight',
+        stage: 'run-the-stack',
+        summary: 'Check that the environment is healthy and ready for work',
+        handler: 'preflight',
+        visibility: 'public',
+        ordinary: ordinary('preflight'),
+        flags: configured,
+    },
+    {
+        name: 'session',
+        stage: 'run-the-stack',
+        summary: 'Keep the environment available for one command, then release it',
+        usage: '[options] -- <command> [args...]',
+        handler: 'session',
+        visibility: 'public',
+        // 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(), profile: { type: 'string', multiple: true } },
+    },
+    {
+        name: 'logs',
+        stage: 'run-the-stack',
+        summary: 'Show recent logs for one declared service',
+        handler: 'logs',
+        visibility: 'public',
+        ordinary: ordinary('logs'),
+        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',
+        summary: 'Release this checkout and stop the stack if no other holder remains',
+        handler: 'sleep',
+        visibility: 'public',
+        ordinary: ordinary('sleep'),
+        flags: configured,
+    },
+    {
+        name: 'down',
+        stage: 'run-the-stack',
+        summary: 'Stop and remove the stack (on the active local Docker context)',
+        handler: 'down',
+        visibility: 'public',
+        // down removes only the containers and networks cockpit created; reset, which deletes data, stays out.
+        ordinary: ordinary('down'),
+        flags: configured,
+    },
+    {
+        name: 'reset',
+        stage: 'run-the-stack',
+        summary: 'Preview a reset, then approve it interactively or apply it as [autonomy] reset allows (on the active local Docker context)',
+        handler: 'reset',
+        visibility: 'public',
+        // Reset deletes stack data, so an agent applies one only where [autonomy] reset = "agent".
+        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',
+        summary: 'Report environment problems without changing anything',
+        handler: 'doctor',
+        visibility: 'public',
+        ordinary: ordinary('doctor'),
+        flags: configured,
+    },
+    // A gate runs only the stages a person declared in the reviewed cockpit.toml, which is the trust
+    // `up` already has; a selector reaches a stage only through the arguments that stage declares.
+    { name: 'test-run', handler: 'test-run', stage: 'test-and-grade', summary: 'Run a declared product test gate and report which tests it selected', visibility: 'public',
+        ordinary: ordinary('test-run'),
+        flags: { ...configured, gate: str(value('declared-gate', true)), mode: str(value('gate-mode'), 'canonical'), select: str(value('gate-selector')) } },
+    // A gated step passes for the agent only where [work.gates] says agent; under person the command
+    // waits for the digest a person types after --interactive, which no agent invocation carries.
+    { name: 'work status', handler: 'work-status', stage: 'test-and-grade', summary: 'Report each work order, its state and how it closed', visibility: 'public',
+        ordinary: ordinary('work-status'),
+        flags: { ...configured, 'work-order': str(value('identifier')) } },
+    { name: 'work accept', handler: 'work-accept', stage: 'test-and-grade', summary: 'Accept a work order, or a change to an accepted one, as [work.gates] allows', visibility: 'public',
+        ordinary: ordinary('work-accept', personFlag),
+        flags: { ...configured, 'work-order': workOrderFlag, interactive: bool() } },
+    { 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, 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), 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',
+        ordinary: ordinary('work-grade'),
+        flags: { ...configured, 'work-order': workOrderFlag, verdict: str(value('label')), note: str(value('label')), evaluator: str(value('evaluator-tool')) } },
+    { 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 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'),
+        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 },
+    { name: 'grade', handler: 'grade-criteria', stage: 'test-and-grade', summary: 'Independently grade uncommitted work against a criteria file, with no work order', visibility: 'public',
+        ordinary: ordinary('grade-criteria'),
+        flags: { ...configured, criteria: str(value('confined-path', true)), evaluator: str(value('evaluator-tool')) } },
+    // Driving signs in and captures the application, so it runs unprompted only on the data posture a
+    // 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),
+        // 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')), 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);
+    return { ...command,
+        options: Object.fromEntries(entries.map(([name, { agent: _agent, ...option }]) => [name, option])),
+        ordinary: command.ordinary.availability === 'available'
+            ? { ...command.ordinary, options: Object.fromEntries(entries.flatMap(([name, { agent }]) => agent ? [[name, agent]] : [])) }
+            : command.ordinary };
+});
+export const internalCommands = Object.freeze([Object.freeze({
+        name: 'guard-evaluate', handler: 'guard-evaluate', visibility: 'internal',
+        ordinary: Object.freeze({ availability: 'unavailable', reason: 'the guard hook calls this internally; it is not a user command' }),
+        argv: GUARD_HANDLER_ARGV, options: Object.freeze({ harness: Object.freeze({ type: 'string' }) }),
+    })]);
+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) {
+    return typeof path === 'string' && path !== '/' && isAbsolute(path) && normalize(path) === path
+        && !path.endsWith('/') && !/[\x00-\x1f\x7f-\x9f\\\uD800-\uDFFF]/u.test(path)
+        && Buffer.byteLength(path) <= GUARD_INPUT_LIMITS.pathBytes;
+}
+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 inner = innerCommand(argv);
+    if (argv[0] !== 'session' || !inner || cwd !== authority.canonicalRoot)
+        return 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) {
+    const candidate = snapshotJson(input);
+    const captured = snapshotJson(authority);
+    if (!record(candidate)
+        || Object.keys(candidate).sort().join(',') !== 'argv,cwd,executable'
+        || !record(captured)
+        || 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)
+        || !Array.isArray(source.allowedRoots) || source.allowedRoots.length > GUARD_INPUT_LIMITS.paths
+        || !source.allowedRoots.every(canonicalPath) || !source.allowedRoots.includes(source.canonicalRoot)
+        || !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
+            && Buffer.byteLength(arg) <= GUARD_INPUT_LIMITS.wordBytes && !/[\x00-\x1f\x7f-\x9f\uD800-\uDFFF]/u.test(arg)))
+        return undefined;
+    const args = candidate.argv;
+    // A group member is named by its first two words; its options follow both.
+    const spelling = commandSpelling(args);
+    const definition = commands.find(row => row.name === spelling.name);
+    const available = definition?.ordinary;
+    if (!definition || definition.visibility !== 'public' || available?.availability !== 'available')
+        return undefined;
+    const grammar = available;
+    const paths = new Set();
+    const confined = (path) => {
+        if (!path || path.includes('\\') || path.split('/').includes('..') || /[*?\[\]]/.test(path))
+            return false;
+        const absolute = resolve(source.canonicalRoot, path);
+        if (!canonicalPath(absolute) || !source.allowedRoots.some(root => absolute === root || absolute.startsWith(root + '/')))
+            return false;
+        paths.add(absolute);
+        return true;
+    };
+    if (grammar.configuration === 'resolved' && !confined(source.configPath))
+        return undefined;
+    const reads = [];
+    const positionals = [];
+    const options = new Map();
+    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('-')) {
+            positionals.push(arg);
+            continue;
+        }
+        if (!arg.startsWith('--') || arg === '--')
+            return undefined;
+        const equal = arg.indexOf('=');
+        const name = arg.slice(2, equal < 0 ? undefined : equal);
+        const option = grammar.options[name];
+        if (!option || options.has(name) && option.repetition !== 'repeated' || grammar.forbidden.presence.includes(name))
+            return undefined;
+        if (option.kind === 'flag') {
+            if (equal >= 0)
+                return undefined;
+            options.set(name, true);
+            continue;
+        }
+        const text = equal < 0 ? words[++index] : arg.slice(equal + 1);
+        if (!text || text.startsWith('-'))
+            return undefined;
+        if (option.role === 'confined-path')
+            reads.push(resolve(source.canonicalRoot, text));
+        const valid = option.role === 'confined-path' ? confined(text)
+            : option.role === 'resolved-config' ? confined(text) && resolve(source.canonicalRoot, text) === source.configPath
+                : option.role === 'declared-service' ? source.services.includes(text)
+                    : option.role === 'declared-gate' ? source.gates.includes(text)
+                        : 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 === '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);
+    }
+    if (positionals.length < grammar.positional.min || positionals.length > grammar.positional.max
+        || 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] === '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)
+        || typeof inspectPath !== 'function' || [...paths].some(path => !inspectPath(path)))
+        return undefined;
+    return { executable: source.executable, cwd: source.canonicalRoot, argv: [...args],
+        ...(reads.length ? { reads } : {}) };
+}