@b00dea/cockpit 0.1.0 → 0.1.1

package/dist/environment/state.js

@@ -1,4 +1,4 @@
-import { access, link, lstat, mkdir, open, opendir, readdir, realpath, rename, rmdir, unlink } from 'node:fs/promises';
+import { access, link, lstat, mkdir, open, opendir, readdir, realpath, rename, rm, rmdir, unlink } from 'node:fs/promises';
 import { closeSync, constants, fstatSync, lstatSync, openSync, readSync, renameSync } from 'node:fs';
 import { createHash, randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
@@ -11,6 +11,7 @@ import { ANSWER_PROVENANCES } from '../init/render.js';
 import { SURFACE_TARGETS } from '../surfaces/contract.js';
 import { checkoutId as deriveCheckoutId } from './identity.js';
 import { redactSensitiveText } from './sensitive.js';
+import { sha256Hex } from '../sha256.js';
 import { hasErrorCode, ENVIRONMENT_CODES, errorCause, RefusalError, snapshotEnvironmentObservation, snapshotJson, isCanonicalTimestamp, } from './contract.js';
 const OWNER = 'environment-state';
 export const observationDeclarations = Object.freeze([
@@ -418,7 +419,7 @@ export function authenticateStateNamespace(value) {
         ? value
         : undefined;
 }
-export function authenticateBootstrapStateNamespace(value) {
+function authenticateBootstrapStateNamespace(value) {
     return value !== null && typeof value === 'object' && issuedBootstrapNamespaces.has(value)
         ? value
         : undefined;
@@ -932,6 +933,10 @@ export async function readState(address) {
             return { kind: 'missing', path: stableAddress.path };
         return malformed(stableAddress, error);
     }
+    return decodeStateRecord(stableAddress, bytes);
+}
+/** A record's bytes as read from an address that has already been checked safe, validated against that address. */
+function decodeStateRecord(stableAddress, bytes) {
     let parsed;
     try {
         const source = new TextDecoder('utf-8', { fatal: true }).decode(bytes);
@@ -2011,3 +2016,138 @@ export async function transactState(namespace, address, options, update) {
         throw operationFailure;
     return issueStatePublication(result, stableAddress);
 }
+function stackStatePaths(value, stackId) {
+    return [
+        { kind: 'coordination', path: value.paths.coordination(stackId).path },
+        { kind: 'lifecycle', path: value.paths.lifecycle(stackId).path },
+        { kind: 'lifecycle-history', path: lifecycleHistoryAddress(value, stackId).path },
+        { kind: 'data-outcome', path: value.paths.dataOutcome(stackId).path },
+    ];
+}
+async function readStackStateFiles(value, stackId) {
+    const files = [];
+    let coordination;
+    for (const { kind, path } of stackStatePaths(value, stackId)) {
+        let bytes;
+        // Bytes, not parsed records: a record this version cannot parse is still this stack's and is
+        // bound by its digest like any other.
+        try {
+            bytes = await readRegularFileNoFollow(path, () => ownedPathIsSafe(value.root, path, 'file'));
+        }
+        catch (error) {
+            if (hasErrorCode(error, 'ENOENT'))
+                continue;
+            throw error;
+        }
+        files.push({ kind, path, sha256: sha256Hex(bytes) });
+        if (kind === 'coordination')
+            coordination = decodeStateRecord(value.paths.coordination(stackId), bytes);
+    }
+    return { files, coordination };
+}
+/** The record files a stack has under one cockpit's namespace, read as bytes so an unparseable record is listed too. */
+export async function inspectStackState(value, stackId) {
+    const read = await inspectStackRecords(value, stackId);
+    return read.kind === 'complete' || read.kind === 'indeterminate' ? { ...read, value: read.value.files } : read;
+}
+/** `inspectStackState`, plus the coordination record decoded from the bytes it read rather than from a second read. */
+export async function inspectStackRecords(value, stackId) {
+    const authenticated = authenticateStateNamespace(value);
+    if (!authenticated || !stackIdentity.test(stackId))
+        return refusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, 'stack state inspection requires an issued namespace and a stack id', 'stack state');
+    try {
+        return { kind: 'complete', value: await readStackStateFiles(authenticated, stackId) };
+    }
+    catch (error) {
+        return refusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, `stack state could not be read safely: ${errorCause(error)}`, authenticated.cockpitRoot);
+    }
+}
+/**
+ * Deletes a stack's record files, which releases its port lease, only when each file still holds the
+ * exact bytes `expected` names and no other file has appeared. It runs under the root port lock, so
+ * no `up` leases ports from a view that still counts the lease, and under the cockpit's own state
+ * lock, so no transaction rewrites a record between the check and the removal.
+ */
+export async function removeStackState(value, stackId, expected, options) {
+    const authenticated = authenticateStateNamespace(value);
+    if (!authenticated || !stackIdentity.test(stackId) || !holderIdentity.test(options.ownerId)) {
+        return refusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, 'stack state removal requires an issued namespace, a stack id and a holder', 'stack state');
+    }
+    const scope = { kind: 'state-scoped-lock' };
+    issuedScopedLocks.set(scope, Object.freeze({ namespace: authenticated, path: authenticated.paths.stateLock }));
+    const key = (files) => files.map(({ kind, path, sha256 }) => `${kind}\0${path}\0${sha256}`).sort().join('\n');
+    try {
+        const locked = await withStateRootPortLock(authenticated, { ownerId: options.ownerId, contentionTimeoutMs: 2_000 }, () => withStateScopedLock(authenticated, scope, { ownerId: options.ownerId, contentionTimeoutMs: 2_000 }, async () => {
+            const { files: current } = await readStackStateFiles(authenticated, stackId);
+            if (key(current) !== key(expected))
+                return { kind: 'changed', reason: `the state of ${stackId} changed since it was previewed` };
+            for (const { path } of current)
+                await unlink(path);
+            for (const directory of new Set(current.map(({ path }) => dirname(path))))
+                await syncDirectory(directory);
+            return { kind: 'removed', paths: current.map(({ path }) => path) };
+        }));
+        return locked.kind === 'complete' ? locked.value : locked;
+    }
+    catch (error) {
+        return refusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, `stack state could not be removed safely: ${errorCause(error)}`, authenticated.cockpitRoot);
+    }
+}
+const NAMESPACE_FINGERPRINT_ENTRIES = 4_096;
+async function namespaceFingerprint(path) {
+    const hash = createHash('sha256');
+    let entries = 0;
+    const walk = async (directory) => {
+        for (const name of (await readdir(directory)).sort()) {
+            if (++entries > NAMESPACE_FINGERPRINT_ENTRIES)
+                throw new RefusalError('state folder exceeds its entry boundary');
+            const child = join(directory, name);
+            const status = await lstat(child, { bigint: true });
+            if (!privatelyOwned({ uid: Number(status.uid), mode: Number(status.mode) }))
+                throw new RefusalError(`${child} is not privately owned`);
+            hash.update(`${relative(path, child)}\0${status.mode}\0${status.size}\0${status.mtimeNs}\n`);
+            if (status.isDirectory())
+                await walk(child);
+        }
+    };
+    const status = await lstat(path);
+    if (status.isSymbolicLink() || !status.isDirectory() || !privatelyOwned(status))
+        throw new RefusalError(`${path} is not a private directory`);
+    await walk(path);
+    return hash.digest('hex');
+}
+function otherNamespacePath(value, path) {
+    return typeof path === 'string' && isAbsolute(path) && dirname(path) === join(value.root, 'cockpits')
+        && path !== value.cockpitRoot && !basename(path).startsWith('.');
+}
+/** A digest of another cockpit's state folder that this version cannot read: every entry's path, mode, size and modification time. */
+export async function inspectStateNamespaceFolder(value, path) {
+    const authenticated = authenticateStateNamespace(value);
+    if (!authenticated || !otherNamespacePath(authenticated, path))
+        return refusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, 'only another cockpit\'s state folder can be inspected for removal', String(path));
+    try {
+        return { kind: 'complete', value: await namespaceFingerprint(path) };
+    }
+    catch (error) {
+        return refusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, `state folder could not be inspected: ${errorCause(error)}`, path);
+    }
+}
+/** Deletes another cockpit's unreadable state folder, under the root port lock, only while it still matches `fingerprint`. */
+export async function removeStateNamespaceFolder(value, path, fingerprint, options) {
+    const authenticated = authenticateStateNamespace(value);
+    if (!authenticated || !otherNamespacePath(authenticated, path) || !digest.test(fingerprint) || !holderIdentity.test(options.ownerId)) {
+        return refusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, 'only another cockpit\'s previewed state folder can be removed', String(path));
+    }
+    try {
+        return await withStateRootPortLock(authenticated, { ownerId: options.ownerId, contentionTimeoutMs: 2_000 }, async () => {
+            if (await namespaceFingerprint(path) !== fingerprint)
+                return { kind: 'changed', reason: `${path} changed since it was previewed` };
+            await rm(path, { recursive: true });
+            await syncDirectory(dirname(path));
+            return { kind: 'removed', paths: [path] };
+        });
+    }
+    catch (error) {
+        return refusal(ENVIRONMENT_CODES.STATE_RECORD_MALFORMED, `state folder could not be removed safely: ${errorCause(error)}`, path);
+    }
+}

package/dist/environment/tool-registration.js

@@ -8,6 +8,7 @@ import { createHash } from 'node:crypto';
 import { readFile } from 'node:fs/promises';
 import { parse, TomlError } from 'smol-toml';
 import { loadCockpitConfig } from '../config/load.js';
+import { canonicalJson } from '../canonical-json.js';
 import { setSurfaceTools } from '../config/surface-tools-toml.js';
 import { writeVerifiedConfig } from '../config/verified-write.js';
 import { cockpitCommand } from '../fix-catalogue.js';
@@ -16,11 +17,6 @@ import { harnessFact, SURFACE_TARGETS } from '../surfaces/harness-registry.js';
 import { ENVIRONMENT_CODES, errorCause } from './contract.js';
 import { refusalOutcome as refused } from '../refusal.js';
 const EDIT_BY_HAND_FIX = 'edit the tools list under [surfaces] in cockpit.toml by hand, then run npx --no cockpit sync --config <your cockpit.toml> --dry-run';
-/** Key order must not matter when two parsed configurations are compared. */
-function canonical(value) {
-    return JSON.stringify(value, (_key, item) => item !== null && typeof item === 'object' && !Array.isArray(item)
-        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : 1)) : item);
-}
 function done(artifact, result) {
     return { status: 0, diagnostics: [], destination: null, artifact, result };
 }
@@ -63,8 +59,8 @@ export async function runToolChange(input) {
         const issue = parsed.error.issues[0];
         return refused(ENVIRONMENT_CODES.CONFIG_SCHEMA_INVALID, `${input.operation === 'add' ? 'adding' : 'removing'} ${tool} would leave cockpit.toml invalid (${issue ? `${issue.path.join('.') || '(root)'}: ${issue.message}` : 'schema'}); nothing was written`, 'surfaces.tools', 'change what the message names first, then run the command again');
     }
-    const expected = canonical({ ...config, surfaces: { ...config.surfaces, tools: after } });
-    const exact = (candidate) => canonical(candidate) === expected;
+    const expected = canonicalJson({ ...config, surfaces: { ...config.surfaces, tools: after } });
+    const exact = (candidate) => canonicalJson(candidate) === expected;
     if (!exact(parsed.data)) {
         return refused(ENVIRONMENT_CODES.CONFIG_SCHEMA_INVALID, 'the edit would change more than the tools list; nothing was written', 'surfaces.tools', EDIT_BY_HAND_FIX);
     }

package/dist/environment-exec/execute.d.ts

@@ -30,21 +30,21 @@ export type ForegroundProcessOutcome = Readonly<{
     started: boolean;
     terminationConfirmed: boolean;
 }>;
-export interface StepExecution {
+interface StepExecution {
     id: string;
     exitCode: number;
     signal: NodeJS.Signals | null;
     stdoutBytes: number;
     stderrBytes: number;
 }
-export interface ProbeStepExecution extends StepExecution {
+interface ProbeStepExecution extends StepExecution {
     started: boolean;
     stdoutObservedBytes: number;
     stderrObservedBytes: number;
     stdoutRetainedBytes: number;
     stderrRetainedBytes: number;
 }
-export interface CompensationFailure {
+interface CompensationFailure {
     id: string;
     code: ExecutionFailureCode;
 }
@@ -91,6 +91,8 @@ export type ExecuteProbeOutcome = {
 /** The outcome when this executor produced it for exactly `step`; undefined for any other value. */
 export declare function authenticatedExecutionOutcome(outcome: unknown, step: ExecutionStep): ExecuteProbeOutcome | undefined;
 /** Runs one operator/agent session process while retaining ownership of its whole process group. */
+/** Whether a foreground process inherits a terminal on both stdin and stdout, so it may ask for one of its own. */
+export declare function foregroundTerminal(): boolean;
 export declare function executeForegroundProcess(input: ForegroundProcessInput, options?: Readonly<{
     signal?: AbortSignal;
 }>): Promise<ForegroundProcessOutcome>;
@@ -100,3 +102,4 @@ export declare function executeProbe(step: ExecutionStep, options?: {
 export declare function executePlan(plan: ExecutionPlan, options?: {
     signal?: AbortSignal;
 }): Promise<ExecutePlanOutcome>;
+export {};

package/dist/environment-exec/execute.js

@@ -867,6 +867,10 @@ function captureForegroundInput(input) {
     }
 }
 /** Runs one operator/agent session process while retaining ownership of its whole process group. */
+/** Whether a foreground process inherits a terminal on both stdin and stdout, so it may ask for one of its own. */
+export function foregroundTerminal() {
+    return process.stdin.isTTY === true && process.stdout.isTTY === true;
+}
 export async function executeForegroundProcess(input, options = {}) {
     const captured = captureForegroundInput(input);
     let signal;

package/dist/fix-catalogue.d.ts

@@ -1,5 +1,5 @@
 import type { Diagnostic } from './environment/contract.js';
-export type ConfiguredCommand = 'setup' | 'sync' | 'check' | 'selftest' | 'upgrade' | 'up' | 'sleep' | 'session' | 'down' | 'reset' | 'preflight' | 'doctor' | 'logs' | 'runtime measure' | 'sibling add' | 'sibling remove';
+export type ConfiguredCommand = 'setup' | 'sync' | 'check' | 'confirm' | 'selftest' | 'upgrade' | 'up' | 'sleep' | 'session' | 'down' | 'reset' | 'preflight' | 'doctor' | 'logs' | 'runtime measure' | 'sibling add' | 'sibling remove' | 'stacks' | 'stacks prune' | 'docs check' | 'use' | 'pull';
 export interface FixContext {
     readonly resolvedConfigPath: string | null;
     readonly generatedTargets: readonly string[];

package/dist/generated-environment/adopt.js

@@ -10,6 +10,7 @@
  * back, so a refused adoption does not silently leave the team's settings moved aside.
  */
 import { sha256Hex } from '../sha256.js';
+import { canonicalJson } from '../canonical-json.js';
 import { basename, dirname, resolve } from 'node:path';
 import { parse, TomlError } from 'smol-toml';
 import { loadCockpitConfig, STRUCTURED_INPUT_BYTE_LIMIT } from '../config/load.js';
@@ -30,11 +31,6 @@ function tomlFailure(error) {
     return error instanceof TomlError ? `TOML error at line ${error.line}, column ${error.column}` : errorCause(error);
 }
 const ADOPT_BY_HAND_FIX = 'move the settings file to cockpit/adopted/<the same path>, add its [[surfaces.adopted]] row to cockpit.toml by hand with the fields the configuration reference lists, then run npx --no cockpit sync --config <your cockpit.toml>';
-/** Key order must not matter when two parsed configurations are compared. */
-function canonical(value) {
-    return JSON.stringify(value, (_key, item) => item !== null && typeof item === 'object' && !Array.isArray(item)
-        ? Object.fromEntries(Object.entries(item).sort(([a], [b]) => a < b ? -1 : 1)) : item);
-}
 function adoptionTable(row) {
     return [
         '[[surfaces.adopted]]',
@@ -160,7 +156,7 @@ export async function runSyncAdoption(input, synchronize, adapterOverrides = {})
     catch (error) {
         return refused(ENVIRONMENT_CODES.CONFIG_PARSE_INVALID, `recording the adoption would leave cockpit.toml unparseable (${tomlFailure(error)}); nothing was moved`, configPath, ADOPT_BY_HAND_FIX);
     }
-    if (!candidateConfig.success || canonical(candidateConfig.data) !== canonical(expected)) {
+    if (!candidateConfig.success || canonicalJson(candidateConfig.data) !== canonicalJson(expected)) {
         return refused(ENVIRONMENT_CODES.CONFIG_SCHEMA_INVALID, 'recording the adoption would change more than the [[surfaces.adopted]] rows; nothing was moved', configPath, ADOPT_BY_HAND_FIX);
     }
     const moved = [];
@@ -187,7 +183,7 @@ export async function runSyncAdoption(input, synchronize, adapterOverrides = {})
                 const restored = await writeVerifiedConfig({
                     path: configPath, expectedSha256: sha256Hex(nextText), temporaryTag: 'adopt',
                     edit: () => originalText,
-                    isExactChange: (value) => canonical(value) === canonical(config),
+                    isExactChange: (value) => canonicalJson(value) === canonicalJson(config),
                     messages: {
                         changedBefore: { message: 'cockpit.toml changed after the adoption was recorded, so its [[surfaces.adopted]] rows were left in place', fix },
                         changedDuring: { message: 'cockpit.toml changed while the adoption was being undone, so its [[surfaces.adopted]] rows were left in place', fix },
@@ -230,7 +226,7 @@ export async function runSyncAdoption(input, synchronize, adapterOverrides = {})
         written = await writeVerifiedConfig({
             path: configPath, expectedSha256: loaded.result.source.sha256, temporaryTag: 'adopt',
             edit: () => nextText,
-            isExactChange: (value) => canonical(value) === canonical(expected),
+            isExactChange: (value) => canonicalJson(value) === canonicalJson(expected),
             messages: {
                 changedBefore: { message: 'cockpit.toml changed since it was read', fix: `let the other edit finish, then have a human approve ${rerun} again` },
                 changedDuring: { message: 'cockpit.toml changed while the adoption was being recorded', fix: `let the other edit finish, then have a human approve ${rerun} again` },

package/dist/guards/answer-confirmation.d.ts

@@ -0,0 +1,41 @@
+import { UNCONFIRMABLE_ANSWERS, type CockpitConfig } from '../schema.js';
+export type UnconfirmedAnswerName = typeof UNCONFIRMABLE_ANSWERS[number];
+export type ConfirmingObservation = 'preflight' | 'check' | 'runtime-floor';
+export type AnswerConfirmation = Readonly<{
+    by: 'observation';
+    observation: ConfirmingObservation;
+    verifies: string;
+}> | Readonly<{
+    by: 'person';
+    trustDecision: boolean;
+    why: string;
+}>;
+export declare const ANSWER_CONFIRMATIONS: Readonly<Record<UnconfirmedAnswerName, AnswerConfirmation>>;
+export declare const ANSWER_CONFIRMATION_PATH: string;
+export type AnswerConfirmationRecord = Readonly<{
+    observation: ConfirmingObservation;
+    ranAt: string;
+    result: 'passed';
+    evidenceSha256: string;
+    configurationSha256: string;
+}>;
+type Records = Readonly<Partial<Record<UnconfirmedAnswerName, AnswerConfirmationRecord>>>;
+/**
+ * The digest a record binds to: the whole configuration except the `unconfirmed` list, so confirming
+ * one answer leaves the records of the others current, and any other edit leaves every record stale.
+ */
+export declare function confirmationConfigurationSha256(config: CockpitConfig): string;
+/** Every well-formed record the bytes hold, or none when they are absent or not a current-format file. */
+export declare function parseAnswerConfirmations(bytes: Uint8Array | undefined): Records;
+export declare function encodeAnswerConfirmations(records: Records): string;
+/**
+ * The answers whose recorded observation passed against exactly `config`. A missing, malformed or
+ * stale record confirms nothing, and no record confirms an answer only a person may.
+ */
+export declare function confirmedAnswers(bytes: Uint8Array | undefined, config: CockpitConfig): ReadonlySet<string>;
+export declare function isUnconfirmedAnswerName(value: string): value is UnconfirmedAnswerName;
+/** The confirmation a person makes, for the answers only a person may confirm. */
+export declare function personConfirmationFix(answers: readonly string[], configPath?: string): string;
+/** How each listed answer is confirmed: the observation an agent runs, or the person who must. */
+export declare function unconfirmedFix(answers: readonly UnconfirmedAnswerName[]): string;
+export {};

package/dist/guards/answer-confirmation.js

@@ -0,0 +1,109 @@
+// Owns who may confirm each init answer listed under `unconfirmed`, and the record of the
+// observations that confirmed one. A person keeps every answer that is a trust decision and every
+// answer no observation settles exactly; an agent may confirm the rest with `cockpit confirm`, which
+// runs the observation and records it here. The guard then lets the agent's own sync apply the
+// removed entry, but only while the record matches the configuration on disk.
+//
+// The record is machine-local, under `.cockpit/local`: the observation is evidence about this machine
+// and its running stack, which another clone has not seen, so there a removed entry still waits for a
+// person. The directory is a guard control directory, so no agent tool call may write it; only the
+// cockpit process that ran the observation does.
+import { canonicalJson } from '../canonical-json.js';
+import { exactKeys } from '../exact-keys.js';
+import { cockpitCommand } from '../fix-catalogue.js';
+import { UNCONFIRMABLE_ANSWERS } from '../schema.js';
+import { sha256Hex } from '../sha256.js';
+import { GUARD_LOCAL_PATHS } from './local-identity.js';
+export const ANSWER_CONFIRMATIONS = Object.freeze({
+    'ports.bases': { by: 'observation', observation: 'preflight',
+        verifies: 'preflight passes with the stack up, its port family leased on the declared bases and every listener and health observation passing' },
+    'environment.compose_files': { by: 'observation', observation: 'check',
+        verifies: 'check passes, which parses the declared Compose files with docker compose config and resolves the stack\'s topology from them' },
+    'environment.machine': { by: 'observation', observation: 'runtime-floor',
+        verifies: 'the container runtime measured on this machine meets the declared memory, CPU and free-disk floor' },
+    guards: { by: 'person', trustDecision: true, why: 'it sets which commands and hosts the guard denies' },
+    testing: { by: 'person', trustDecision: true, why: 'it decides which tests grade the agent\'s own work' },
+    'environment.install_policies': { by: 'person', trustDecision: true, why: 'it sets the build and test commands the guard admits' },
+    sibling: { by: 'person', trustDecision: true, why: 'it sets each repository\'s purpose and the roots agents may write' },
+    'environment.posture': { by: 'person', trustDecision: true, why: 'it decides browser preapproval and what data agents are exposed to' },
+    'cockpit.name': { by: 'person', trustDecision: false,
+        why: 'a name is a choice, and no observation shows it is the one the owner wants; it scopes Compose projects, state and generated files' },
+    'estate.runnable': { by: 'person', trustDecision: false,
+        why: 'a stack that starts shows the declared services run, not that a repository declared not runnable should stay out' },
+    'environment.test_data': { by: 'person', trustDecision: false,
+        why: 'it states what local work needs (seeded data, signed-in users), and no observation shows a need is absent' },
+});
+export const ANSWER_CONFIRMATION_PATH = `${GUARD_LOCAL_PATHS.directory}/answer-confirmations`;
+const FORMAT = 'cockpit-answer-confirmations/v1';
+const RECORD_KEYS = ['observation', 'ranAt', 'result', 'evidenceSha256', 'configurationSha256'];
+const SHA256 = /^[a-f0-9]{64}$/;
+const TIMESTAMP = /^\d{4}-\d\d-\d\dT\d\d:\d\d:\d\d\.\d{3}Z$/;
+/**
+ * The digest a record binds to: the whole configuration except the `unconfirmed` list, so confirming
+ * one answer leaves the records of the others current, and any other edit leaves every record stale.
+ */
+export function confirmationConfigurationSha256(config) {
+    const { unconfirmed: _unconfirmed, ...observed } = config;
+    return sha256Hex(canonicalJson(observed));
+}
+function validRecord(answer, value) {
+    const confirmation = ANSWER_CONFIRMATIONS[answer];
+    if (!confirmation || confirmation.by !== 'observation' || value === null || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const row = value;
+    return exactKeys(row, RECORD_KEYS) && row.observation === confirmation.observation && row.result === 'passed'
+        && typeof row.ranAt === 'string' && TIMESTAMP.test(row.ranAt) && Number.isFinite(Date.parse(row.ranAt))
+        && typeof row.evidenceSha256 === 'string' && SHA256.test(row.evidenceSha256)
+        && typeof row.configurationSha256 === 'string' && SHA256.test(row.configurationSha256);
+}
+/** Every well-formed record the bytes hold, or none when they are absent or not a current-format file. */
+export function parseAnswerConfirmations(bytes) {
+    if (!bytes)
+        return {};
+    let value;
+    try {
+        value = JSON.parse(Buffer.from(bytes).toString('utf8'));
+    }
+    catch (error) {
+        if (error instanceof SyntaxError)
+            return {};
+        throw error;
+    }
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        return {};
+    const file = value;
+    const confirmations = file.confirmations;
+    if (!exactKeys(file, ['format', 'confirmations']) || file.format !== FORMAT
+        || confirmations === null || typeof confirmations !== 'object' || Array.isArray(confirmations))
+        return {};
+    return Object.fromEntries(Object.entries(confirmations).filter(([answer, row]) => validRecord(answer, row)));
+}
+export function encodeAnswerConfirmations(records) {
+    return `${JSON.stringify({ format: FORMAT, confirmations: records }, null, 2)}\n`;
+}
+/**
+ * The answers whose recorded observation passed against exactly `config`. A missing, malformed or
+ * stale record confirms nothing, and no record confirms an answer only a person may.
+ */
+export function confirmedAnswers(bytes, config) {
+    const digest = confirmationConfigurationSha256(config);
+    return new Set(Object.entries(parseAnswerConfirmations(bytes))
+        .filter(([, row]) => row.configurationSha256 === digest).map(([answer]) => answer));
+}
+export function isUnconfirmedAnswerName(value) {
+    return UNCONFIRMABLE_ANSWERS.includes(value);
+}
+/** The confirmation a person makes, for the answers only a person may confirm. */
+export function personConfirmationFix(answers, configPath) {
+    return `a person confirms ${answers.join(', ')} with whoever owns the product, corrects cockpit.toml if a value is wrong, deletes ${answers.length === 1 ? 'its entry' : 'each entry'} from unconfirmed, then runs ${cockpitCommand('sync', configPath === undefined ? {} : { config: configPath })} in a terminal outside the agent`;
+}
+/** How each listed answer is confirmed: the observation an agent runs, or the person who must. */
+export function unconfirmedFix(answers) {
+    const observed = answers.flatMap(answer => {
+        const confirmation = ANSWER_CONFIRMATIONS[answer];
+        return confirmation.by === 'observation'
+            ? [`run ${cockpitCommand('confirm', { operand: answer })}, which confirms ${answer} only if ${confirmation.verifies}`] : [];
+    });
+    const person = answers.filter(answer => ANSWER_CONFIRMATIONS[answer].by === 'person');
+    return [...observed, ...person.length ? [personConfirmationFix(person)] : []].join('; ');
+}

package/dist/guards/evaluator.d.ts

@@ -1,3 +1,19 @@
+/**
+ * The cockpit commands that run the words after their `--` as a command of their own, and where it
+ * runs: a session's on the host, exec's inside a product container that mounts the checkouts and
+ * may hold their credentials. The guard judges that command as an invocation of its own, so
+ * wrapping a command never admits more than running it directly.
+ */
+export declare const WRAPPING_COMMANDS: ReadonlyMap<string, 'host' | 'container'>;
+/**
+ * The command a wrapping cockpit command runs, from its arguments after the launcher: the words
+ * after its first `--`, and where they run. Undefined when the command wraps none or names no
+ * command after `--`.
+ */
+export declare function innerCommand(argv: readonly string[]): Readonly<{
+    words: readonly string[];
+    runs: 'host' | 'container';
+}> | undefined;
 export interface GuardInvocationProfile {
     readonly executable: string;
     readonly cwd: string;
@@ -17,12 +33,12 @@ export interface GuardProtectedIdentity {
     readonly identity: string | null;
     readonly ancestors: readonly string[];
 }
-export interface GuardDeclaredAllow {
+interface GuardDeclaredAllow {
     readonly argv: readonly string[];
     readonly reason: string;
     readonly cwd?: string;
 }
-export interface GuardDeclaredDeny {
+interface GuardDeclaredDeny {
     readonly match: 'prefix' | 'contains';
     readonly argv: readonly string[];
     readonly reason: string;
@@ -68,7 +84,7 @@ export interface GuardEvaluationPolicy {
     readonly cockpitLaunchers: readonly GuardInvocationProfile[];
     readonly projectCommands: readonly GuardProjectCommand[];
 }
-export interface PathInspectionRequest {
+interface PathInspectionRequest {
     readonly path: string;
     readonly cwd: string;
     /**
@@ -111,3 +127,4 @@ export declare function guardIdentity(status: {
 export declare function foldGuardSpelling(path: string): string;
 /** Hard boundaries are independent of grants and are evaluated across the complete capture. */
 export declare function evaluateGuard(input: unknown, policy: unknown, inspect: PathInspection): GuardDecision;
+export {};

package/dist/guards/evaluator.js

@@ -7,6 +7,25 @@ import { renderGuardProjectCommand } from '../environment/install-policy.js';
 import { GUARD_LOCAL_PATHS } from './local-identity.js';
 import { classifyReadOnlyInvocation, cockpitLauncherPrefix } from './read-only.js';
 import { SURFACE_EXECUTION_CONTROL_PATHS } from '../surfaces/harness-registry.js';
+/**
+ * The cockpit commands that run the words after their `--` as a command of their own, and where it
+ * runs: a session's on the host, exec's inside a product container that mounts the checkouts and
+ * may hold their credentials. The guard judges that command as an invocation of its own, so
+ * wrapping a command never admits more than running it directly.
+ */
+export const WRAPPING_COMMANDS = new Map([['session', 'host'], ['exec', 'container']]);
+/**
+ * The command a wrapping cockpit command runs, from its arguments after the launcher: the words
+ * after its first `--`, and where they run. Undefined when the command wraps none or names no
+ * command after `--`.
+ */
+export function innerCommand(argv) {
+    const runs = argv.length ? WRAPPING_COMMANDS.get(argv[0]) : undefined;
+    if (!runs)
+        return undefined;
+    const separator = argv.indexOf('--');
+    return separator < 0 || separator === argv.length - 1 ? undefined : { words: argv.slice(separator + 1), runs };
+}
 // An agent able to rewrite any of these can switch the guard off, grant itself commands or run code
 // when a harness starts: the published guard transport, every harness registration that launches it,
 // the manifest that authenticates both, Claude's local settings, where `disableAllHooks` would switch
@@ -1029,16 +1048,23 @@ export function evaluateGuard(input, policy, inspect) {
         holdAsk(invocation, ask(UNPROVEN_LAUNCHER));
         return { operands: invocation.argv.slice(prefix) };
     };
-    // A session runs the words after `--` as a command, with no shell, in its own directory, so
-    // that command is judged as one more invocation: the session never admits more than it would.
+    // A session runs the words after `--` as a command, with no shell, in its own directory, and exec
+    // runs them in a product container that mounts the checkouts and may hold their credentials, so
+    // that command is judged as one more invocation: neither admits more than the guard would. The
+    // name-based denials apply to exec's command as to any other, but a read-only proof is about the
+    // host's files and exec's command sees the container's, so only a declared allow rule or a
+    // build or test command admits it.
+    const containerCommands = new Set();
     const invocations = input.invocations.flatMap((invocation) => {
         const cockpit = provenCockpit(invocation);
-        const separator = cockpit?.[0] === 'session' ? cockpit.indexOf('--') : -1;
-        const command = separator < 0 ? [] : cockpit.slice(separator + 1);
-        if (!command.length)
+        const command = cockpit && innerCommand(cockpit);
+        if (!command)
             return [invocation];
-        return [invocation, { executable: command[0], argv: command.slice(1), cwd: invocation.cwd, wrapped: false, redirects: [],
-                words: command.map((value, index) => ({ role: index ? 'argument' : 'executable', value })) }];
+        const inner = { executable: command.words[0], argv: command.words.slice(1), cwd: invocation.cwd, wrapped: false, redirects: [],
+            words: command.words.map((value, index) => ({ role: index ? 'argument' : 'executable', value })) };
+        if (command.runs === 'container')
+            containerCommands.add(inner);
+        return [invocation, inner];
     });
     const accesses = new Map(invocations.map((invocation) => {
         const cockpit = provenCockpit(invocation);
@@ -1215,6 +1241,12 @@ export function evaluateGuard(input, policy, inspect) {
             continue;
         const matches = (profile, cwd) => profile.executable === invocation.executable
             && cwd === invocation.cwd && profile.argv.length === invocation.argv.length && profile.argv.every((word, i) => word === invocation.argv[i]);
+        if (containerCommands.has(invocation)) {
+            if (resolved.projectCommands.some((profile) => matches(profile, profile.checkoutRoot)))
+                continue;
+            return ask(`${named(invocation)} runs inside the product container, whose filesystem the guard cannot see, so no read-only proof about host paths covers it. `
+                + `The guard admits it only as a declared build or test command or under a [guards] allow rule; a person approves it or runs it in a terminal, or admits it for good under [guards] allow in ${posix.basename(resolved.configPath)}.`);
+        }
         if (!readOnly.has(invocation) && !resolved.cockpitInvocations.some((profile) => matches(profile, profile.cwd))
             && !resolved.projectCommands.some((profile) => matches(profile, profile.checkoutRoot))) {
             const config = /^[\w./@%+=:,-]+$/.test(resolved.configPath) ? resolved.configPath : `'${resolved.configPath.replaceAll("'", "'\\''")}'`;

package/dist/guards/local-identity.d.ts

@@ -16,13 +16,17 @@ export interface GuardHandlerIdentity {
 export declare const GUARD_LOCAL_PATHS: Readonly<{
     readonly directory: '.cockpit/local';
     readonly identity: '.cockpit/local/guard-identity';
+    readonly generatedConfig: '.cockpit/local/guard-config';
     readonly ignore: '.cockpit/local/.gitignore';
 }>;
 export declare function encodeGuardLocalIdentity(identity: GuardHandlerIdentity): string;
 /** The exact identity the bytes carry, or undefined when they are not a complete current-format file. */
 export declare function parseGuardLocalIdentity(bytes: string): GuardHandlerIdentity | undefined;
-/** Publish the identity after the tracked surfaces it authenticates; the reason names what failed. */
-export declare function writeGuardLocalIdentity(root: string, identity: GuardHandlerIdentity): Promise<{
+/**
+ * Publish the identity after the tracked surfaces it authenticates, with the configuration text it
+ * names written first; the reason names what failed.
+ */
+export declare function writeGuardLocalIdentity(root: string, identity: GuardHandlerIdentity, configText: string): Promise<{
     readonly kind: 'complete';
 } | {
     readonly kind: 'refusal';

package/dist/guards/local-identity.js

@@ -6,12 +6,14 @@
 import { exactKeys } from '../exact-keys.js';
 import { randomBytes } from 'node:crypto';
 import { lstat, mkdir, rename, rm, writeFile } from 'node:fs/promises';
-import { join } from 'node:path';
+import { basename, join } from 'node:path';
 import { readBoundedInput } from '../config/load.js';
 import { errorCause, hasErrorCode } from '../environment/contract.js';
 export const GUARD_LOCAL_PATHS = Object.freeze({
     directory: '.cockpit/local',
     identity: '.cockpit/local/guard-identity',
+    // The exact configuration the guards were generated from, so a later edit can be compared with it.
+    generatedConfig: '.cockpit/local/guard-config',
     ignore: '.cockpit/local/.gitignore',
 });
 // The guard script reads this file with `read` one line at a time, so the layout is lines rather
@@ -88,9 +90,13 @@ async function replaceFile(directory, name, bytes) {
         await rm(temporary, { force: true });
     }
 }
-/** Publish the identity after the tracked surfaces it authenticates; the reason names what failed. */
-export async function writeGuardLocalIdentity(root, identity) {
-    return writeCockpitLocalFiles(root, [{ name: 'guard-identity', bytes: encodeGuardLocalIdentity(identity) }]);
+/**
+ * Publish the identity after the tracked surfaces it authenticates, with the configuration text it
+ * names written first; the reason names what failed.
+ */
+export async function writeGuardLocalIdentity(root, identity, configText) {
+    return writeCockpitLocalFiles(root, [{ name: basename(GUARD_LOCAL_PATHS.generatedConfig), bytes: configText },
+        { name: basename(GUARD_LOCAL_PATHS.identity), bytes: encodeGuardLocalIdentity(identity) }]);
 }
 /** Replace machine-local files under `.cockpit/local`, a directory that ignores itself; the reason names what failed. */
 export async function writeCockpitLocalFiles(root, files) {