@guilz-dev/belay 0.8.1 → 0.9.0

package/README.md

@@ -135,12 +135,13 @@ Belay is a layered hook gate, not a static denylist. Higher layers are opt-in.
 | Layer | Role | Enabled by |
 |-------|------|------------|
 | **L1** Containment | Egress proxy, sandbox capability broker | `egress` / `sandbox` config |
-| **L2** Observation | Transactional git-worktree diff | `policy.transactional` |
+| **L2** Observation | Transactional mirror and durable checkpoint observation | `policy.transactional` |
 | **L3** Prediction | Policy rules + command heuristics | default |
 | **L4** Approval | Human one-shot / scoped approvals | default |
 
 - Normalized shell authorization uses only canonical `EffectPlan` requirements.
-  Command lists, legacy overrides, corpus labels, and shell standing allows are inert.
+  Command lists, legacy overrides, corpus labels, and legacy standing-allow records for shell,
+  tool, and subagent actions are inert at runtime.
 - Payload-free reads are `allow`; reversible repository-local writes (including implicit
   download output) are `allow_flagged`. Outside-repository writes, external mutation,
   explicit payload/file/secret sends, high-stakes effects, and partial/indeterminate plans
@@ -148,6 +149,52 @@ Belay is a layered hook gate, not a static denylist. Higher layers are opt-in.
 - Adversarial resistance requires the full L1 stack:
   `belay init --preset l1-full-recommended`, verified with `belay sandbox status`.
 
+### Contained unknown execution (opt-in)
+
+For an eligible repository-local `unknown_local_effect`, an operator may opt into one disposable
+Docker run instead of taking the ordinary approval path. No command allowlist is involved:
+EffectPlan remains the shell authority, and executable names, prefixes, fingerprints, corpus
+membership, Rails, RSpec, and fictional command names all use the same effect-based eligibility
+route. The original host command is blocked after mediation.
+
+Enable it only with an operator-provisioned image and explicit local Docker substrate:
+
+```json
+{
+  "sandbox": {
+    "enabled": true,
+    "runtime": "container",
+    "containedExecution": {
+      "enabled": true,
+      "image": "registry.example/contained-runner:2026-08-18",
+      "dockerExecutable": "/usr/local/bin/docker",
+      "dockerHost": "unix:///var/run/docker.sock"
+    }
+  }
+}
+```
+
+Run `belay session start` after changing this configuration. It binds a fresh signed capability to
+the configured Docker executable, local Unix daemon, and immutable image ID; image-tag drift,
+tampering, stale proof, or config changes require another session start. v1 never builds or pulls
+an image automatically and always uses network `none`.
+
+Belay copies the current workspace to a bounded metadata-free mirror, mounts only that mirror in
+the container at the original guest path, and discards it after one run. Workspace changes are
+discarded; there is no diff/apply or host replay. Guest output is scrubbed and retained only as
+16 KiB tails. This boundary scrub is mandatory even when ordinary audit `redaction.*` options are
+disabled. A nonzero guest exit is reported as contained failure and does not create an approval.
+
+In audit mode Belay's contained route reports `wouldMediate` and performs no contained execution:
+it reads no attestation and runs neither a mirror nor a container. The gate returns `allow`, so the
+host hook delegates the original invocation as ordinary audit pass-through; it is not a contained
+route host replay.
+In enforce mode, only pre-execution Docker substrate or daemon unavailability returns to the normal
+approval path. Missing, stale, or tampered attestation/capability; missing or mismatched image;
+mirror/lease failure; create/inspect/start failure; timeout; and cleanup uncertainty fail closed
+without approval. This route is not L1-full;
+see the [guarantee table](./docs/guarantee-table.md) for its exact boundary and residual risks.
+
 ## Install options
 
 ```bash
@@ -242,18 +289,21 @@ Notable settings:
 - **`classifier.strictChains: true`** (default) — scans every `&&`, `|`, and `;`
   segment into the EffectPlan and keeps the strictest policy projection. Legacy
   `overrides.allow` / `overrides.external` lists are accepted only for config
-  compatibility; shell authorization ignores them and `belay doctor` warns when
-  either list is non-empty.
+  compatibility; shell authorization ignores them. **`belay doctor` fails** when either
+  list is non-empty (ADR-005). Remove legacy lists; improve EffectPlan semantics or use
+  one-shot approval instead.
 - **`controlPlane.enabled: true`** — stores approval state under
   `~/.config/belay/` (or `XDG_CONFIG_HOME/belay`), shared across repos for the
   current OS user. `upgrade` migrates repo-local approvals in; disabling merges
   them back. File-mutation tools and shell redirects cannot write control-plane
   paths while it is enabled.
-- **`policy.transactional.checkpoint.enabled: true`** — after enabling the
-  transactional git-worktree runner, persist repo-local pre-images and expose them through
-  `belay recover list`. Restore is conflict-checked and always requires a signed
-  out-of-band, exact one-shot approval. Network, remote Git, databases, processes, and
-  repo-external effects are outside this guarantee.
+- **`policy.transactional.checkpoint.enabled: true`** — after enabling the transactional
+  runner, persist repo-local pre-images and expose them through `belay recover list`. Clean Git
+  uses `git_worktree`; dirty Git and non-Git directories use `file_checkpoint` when separately
+  enabled (`policy.transactional.fileCheckpoint.enabled` and, for non-Git roots,
+  `allowNonGit: true`) with an attested workspace-isolating boundary. Restore is conflict-checked
+  and always requires a signed out-of-band, exact one-shot approval. Network, remote Git,
+  databases, processes, and repo-external effects are outside this guarantee.
 - **Cloud judge** — configure with `belay config` (interactive) or `belay config set judge.providerId <id>`.
   Providers: `ollama`, `codex`, `claude`, `cursor`. **Provider** is the vendor/service
   (`judge.providerId`); **driver** is the API compatibility layer (`judge.provider`:
@@ -297,7 +347,7 @@ belay status                     # show install scope / skill-only state
 belay metrics                    # would-block / verdict summary
 belay report                     # audit log report
 belay recover [advice] [--command "rm important.ts"] # advisory candidates only
-belay recover status                          # checkpoint backend and state counts
+belay recover status                          # checkpoint backend, eligibility, and state counts
 belay recover list                            # proven repo-local recovery points
 belay recover show <checkpoint-id>
 belay recover apply <checkpoint-id>           # signed OOB exact one-shot approval required

package/dist/adapters/shared/gate-runtime.d.ts

@@ -1,4 +1,6 @@
 import { type ApprovalReplayHint } from '../../core/approval-replay.js';
+import { type ExecuteContainedDockerParams, executeContainedDocker } from '../../core/contained-execution/docker.js';
+import { type ContainedExecutionMirrorHandle, type ContainedExecutionMirrorOptions } from '../../core/contained-execution/mirror.js';
 import { type GatedActionKind, type GatePermissionResponse, type GateVerdict } from '../../core/gate-contract.js';
 import { GateNormalizationError } from '../../core/gate-engine.js';
 import { type BelayConfigV3 } from '../../core/index.js';
@@ -30,6 +32,9 @@ export interface GateRuntimeDeps {
         stdout?: string;
         stderr?: string;
     }>;
+    readSignedAttestation: (filePath: string) => Promise<unknown>;
+    withContainedExecutionMirror: <T>(options: ContainedExecutionMirrorOptions, operation: (mirror: ContainedExecutionMirrorHandle) => Promise<T>) => Promise<T>;
+    executeContainedDocker: (params: ExecuteContainedDockerParams) => ReturnType<typeof executeContainedDocker>;
 }
 export declare function createDefaultGateRuntimeDeps(): GateRuntimeDeps;
 export declare function resolveGateConfig(ctx: Pick<GateRuntimeContext, 'layout' | 'repoRoot' | 'configPath'>, deps: GateRuntimeDeps): Promise<BelayConfigV3>;

package/dist/adapters/shared/gate-runtime.js

@@ -7,11 +7,13 @@ import { buildReplayHint, buildRetryInstructionForConfig, canAutoReplay, getExec
 import { claimApprovedForReplay, gateApprovalStoreFromDeps, recordApproval, } from '../../core/approval-service.js';
 import { issueApprovalToken } from '../../core/approval-token.js';
 import { buildAuditActionSnapshot, buildAuditReplayContext, } from '../../core/audit-replay-context.js';
+import { boundedUtf8Tail } from '../../core/bounded-output.js';
 import { mutateApprovalStateWithRetry } from '../../core/capability/approval-state-mutation.js';
 import { APPROVAL_STATE_VERSION_V3 } from '../../core/capability/approval-v3.js';
+import { readSignedAttestationFile } from '../../core/capability/boundary-attestation-sign.js';
 import { isEgressProxyActive } from '../../core/capability/boundary-egress.js';
 import { isBoundaryCleanupError, safeBoundaryCleanupResourceId, } from '../../core/capability/boundary-run.js';
-import { resolveBoundaryDriverContext, runBoundaryAgentCommand, } from '../../core/capability/boundary-session.js';
+import { boundaryAttestationPath, resolveBoundaryDriverContext, runBoundaryAgentCommand, } from '../../core/capability/boundary-session.js';
 import { hashCapabilityRequests } from '../../core/capability/capability-request-hash.js';
 import { recordGateApprovalAsk, scheduleGateShadowAudit, } from '../../core/capability/gate-shadow-audit.js';
 import { canConsumeCapabilityGrantLease } from '../../core/capability/grant-consumption.js';
@@ -19,17 +21,21 @@ import { approvalGrantBundleExhausted, consumeApprovedRecordGrantBundle, consume
 import { loadClassifierAuthorization } from '../../core/capability/grant-loader.js';
 import { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload, fsScopeAllowlistPath, isCapabilityBrokerDemotionActive, loadFsScopeAllowlistSync, loadTrustedWorkspaceRootsSync, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, trustedWorkspaceRootsPath, validateTrustedWorkspaceRootCandidate, } from '../../core/capability/index.js';
 import { resolveLayeredConfig, teamConfigPath } from '../../core/config-layers.js';
+import { ContainedDockerBoundaryUnavailableError, executeContainedDocker, } from '../../core/contained-execution/docker.js';
+import { isContainedUnknownExecutionEligible } from '../../core/contained-execution/eligibility.js';
+import { ContainedExecutionFailureError } from '../../core/contained-execution/failure.js';
+import { withContainedExecutionMirror, } from '../../core/contained-execution/mirror.js';
+import { CONTAINED_EXECUTION_OUTPUT_SCRUB_OPTIONS, isContainedExecutionApprovalFallbackReason, } from '../../core/contained-execution/policy.js';
 import { effectPlanAuditFields, hashEffectPlan } from '../../core/effect-ir/audit.js';
 import { buildCapabilityEffectPlan } from '../../core/effect-ir/build.js';
 import { classifyResultToGateVerdict, unnormalizedGateVerdict, } from '../../core/gate-contract.js';
 import { classifyGatedActionAsync, extractAgentAssessment, GateNormalizationError, gateEnabledForAction, normalizeGatedAction, } from '../../core/gate-engine.js';
-import { approvalCommandMatch, approvedApprovalsFile, belayStateDir, canonicalStringify, classifierOptionsFromConfig, configuredControlPlaneDir, hashValue, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubValue, toolFingerprint, } from '../../core/index.js';
+import { approvalCommandMatch, approvedApprovalsFile, belayStateDir, canonicalStringify, classifierOptionsFromConfig, configuredControlPlaneDir, hashValue, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubString, scrubValue, toolFingerprint, } from '../../core/index.js';
 import { extractJudgeFallbackReason, formatJudgeInfrastructureDenyMessage, inferProviderIdFromFallbackReason, isJudgeInfrastructureFailure, } from '../../core/judge-fallback-hints.js';
 import { notifyDeny } from '../../core/notify.js';
 import { canonicalPath } from '../../core/path-utils.js';
 import { recoveryFailClosedResult, recoveryFailReasonFromSkip, } from '../../core/recovery/fail-closed.js';
 import { fingerprintReplayPayload } from '../../core/replay-scrub.js';
-import { loadStandingAllow, resolveStandingAllowMatch, standingAllowFile, } from '../../core/standing-allow.js';
 import { FILE_CHECKPOINT_ISOLATION_UNAVAILABLE, isTransactionalEligible, runTransactionalExecution, TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, } from '../../core/transactional/index.js';
 import { egressStatus } from '../../services/egress-service.js';
 import { PACKAGE_VERSION } from '../../version.js';
@@ -51,6 +57,25 @@ function auditProvenance(config) {
         configFingerprint: hashValue(canonicalStringify(config)),
     };
 }
+function preservedContainedAuditMetadata(record) {
+    const safe = {};
+    if (record.wouldMediate === true)
+        safe.wouldMediate = true;
+    if (typeof record.receiptHash === 'string' && /^[a-f0-9]{64}$/.test(record.receiptHash)) {
+        safe.receiptHash = record.receiptHash;
+    }
+    if (typeof record.imageId === 'string' && /^sha256:[a-f0-9]{64}$/.test(record.imageId)) {
+        safe.imageId = record.imageId;
+    }
+    if (record.mirrorBackend === 'file_copy')
+        safe.mirrorBackend = record.mirrorBackend;
+    if (record.exitCode === null || Number.isSafeInteger(record.exitCode)) {
+        safe.exitCode = record.exitCode;
+    }
+    if (typeof record.timedOut === 'boolean')
+        safe.timedOut = record.timedOut;
+    return safe;
+}
 function adapterIdFromContext(ctx) {
     if (ctx.config.adapter === 'cursor' ||
         ctx.config.adapter === 'claude' ||
@@ -99,7 +124,7 @@ export function createDefaultGateRuntimeDeps() {
                 delete record.assessment;
             }
             const scrubbed = scrubValue(record, scrubOptionsFromConfig(ctx.config));
-            Object.assign(scrubbed, provenance);
+            Object.assign(scrubbed, provenance, preservedContainedAuditMetadata(record));
             await writeFile(auditPath, `${JSON.stringify(scrubbed)}\n`, {
                 encoding: 'utf8',
                 flag: 'a',
@@ -135,6 +160,9 @@ export function createDefaultGateRuntimeDeps() {
                 runOptions: { mountReadOnly: false },
             });
         },
+        readSignedAttestation: readSignedAttestationFile,
+        withContainedExecutionMirror,
+        executeContainedDocker,
     };
 }
 export async function resolveGateConfig(ctx, deps) {
@@ -364,6 +392,197 @@ async function discardApprovedApproval(ctx, deps, approvalId) {
         throw new Error(`Failed to discard rejected approval ${approvalId}`);
     }
 }
+function scrubMediatedOutput(value) {
+    const source = boundedUtf8Tail(value);
+    const scrubbed = boundedUtf8Tail(scrubString(source.value, CONTAINED_EXECUTION_OUTPUT_SCRUB_OPTIONS));
+    return { value: scrubbed.value, truncated: source.truncated || scrubbed.truncated };
+}
+function normalizeContainedFailure(error) {
+    if (error instanceof ContainedExecutionFailureError) {
+        return error;
+    }
+    if (error?.code === 'ENOENT') {
+        return new ContainedExecutionFailureError('contained_execution_capability_invalid', {
+            cause: error,
+        });
+    }
+    return new ContainedExecutionFailureError('contained_execution_boundary_failed', { cause: error });
+}
+function containedAuditBase(kind, mode, result) {
+    const planFields = effectPlanAuditFields(result.effectPlan);
+    return {
+        event: gateAuditEventName(kind),
+        kind,
+        fingerprint: result.fingerprint,
+        mode,
+        schemaVersion: result.axes ? 2 : 1,
+        effectPlanVersion: planFields.effectPlanVersion,
+        effectIRHash: planFields.effectIRHash,
+        effectPlanSignals: planFields.effectPlanSignals,
+        effectPlanOpacity: planFields.effectPlanOpacity,
+        effectPlanDisposition: planFields.effectPlanDisposition,
+        effectPlanCompleteness: planFields.effectPlanCompleteness,
+        wouldMediate: true,
+    };
+}
+async function mediateContainedUnknownExecution(params) {
+    const { ctx, deps, action, command } = params;
+    const result = { ...params.result, wouldMediate: true };
+    if (ctx.config.mode === 'audit') {
+        await deps.appendAudit(ctx, {
+            ...containedAuditBase(action.kind, ctx.config.mode, result),
+            verdict: result.verdict,
+            reason: result.reason,
+            wouldBlock: true,
+            permission: 'allow',
+        });
+        return classifyResultToGateVerdict({
+            result,
+            mode: ctx.config.mode,
+            permission: 'allow',
+            wouldBlock: true,
+        });
+    }
+    const controlPlaneDir = configuredControlPlaneDir(ctx.config);
+    const attestationPath = boundaryAttestationPath(ctx.repoRoot, ctx.config);
+    const protectedRoots = [
+        ...new Set([
+            ...protectedArtifactRoots(ctx.layout, ctx.repoRoot, controlPlaneDir),
+            attestationPath,
+        ]),
+    ];
+    const checkpoint = ctx.config.policy.transactional.fileCheckpoint;
+    const containedConfig = ctx.config.sandbox.containedExecution;
+    if (!containedConfig?.enabled) {
+        return null;
+    }
+    let execution;
+    let mirrorBackend;
+    try {
+        let signedAttestation;
+        try {
+            signedAttestation = await deps.readSignedAttestation(attestationPath);
+        }
+        catch (error) {
+            throw new ContainedExecutionFailureError('contained_execution_capability_invalid', {
+                cause: error,
+            });
+        }
+        execution = await deps.withContainedExecutionMirror({
+            sourceRoot: ctx.repoRoot,
+            controlPlaneRoots: protectedRoots,
+            limits: {
+                maxFiles: checkpoint.maxFiles,
+                maxSourceBytes: checkpoint.maxSourceBytes,
+                maxWorkspaceBytes: checkpoint.maxWorkspaceBytes,
+                prepareTimeoutMs: checkpoint.prepareTimeoutMs,
+            },
+        }, async (mirror) => {
+            mirrorBackend = mirror.backend;
+            return deps.executeContainedDocker({
+                repoRoot: ctx.repoRoot,
+                controlPlaneDir,
+                protectedRoots,
+                config: containedConfig,
+                mirror,
+                guestCwd: action.cwd,
+                command,
+                inputFingerprint: result.fingerprint,
+                signedAttestation,
+            });
+        });
+    }
+    catch (error) {
+        if (error instanceof ContainedDockerBoundaryUnavailableError &&
+            isContainedExecutionApprovalFallbackReason(error.reason)) {
+            return null;
+        }
+        const failure = normalizeContainedFailure(error);
+        const reason = failure.code;
+        const failedResult = {
+            ...result,
+            verdict: 'deny_pending_approval',
+            reason,
+        };
+        await deps.appendAudit(ctx, {
+            ...containedAuditBase(action.kind, ctx.config.mode, failedResult),
+            verdict: failedResult.verdict,
+            reason,
+            wouldBlock: true,
+            permission: 'deny',
+            ...(mirrorBackend ? { mirrorBackend } : {}),
+        });
+        const sessionHint = failure.remediation === 'session-start' ? ' Run `belay session start`, then retry.' : '';
+        return classifyResultToGateVerdict({
+            result: failedResult,
+            mode: ctx.config.mode,
+            permission: 'deny',
+            wouldBlock: true,
+            user_message: `Belay could not confirm safe contained execution (${reason}).${sessionHint}`,
+            agent_message: `Belay denied the original host command because contained execution failed closed (${reason}).` +
+                sessionHint,
+        });
+    }
+    const stdout = scrubMediatedOutput(execution.stdout);
+    const stderr = scrubMediatedOutput(execution.stderr);
+    const mediatedExecution = {
+        exitCode: execution.exitCode,
+        signal: execution.signal,
+        timedOut: execution.timedOut,
+        stdout: stdout.value,
+        stderr: stderr.value,
+        stdoutTruncated: execution.stdoutTruncated || stdout.truncated,
+        stderrTruncated: execution.stderrTruncated || stderr.truncated,
+        receiptHash: execution.receiptHash,
+        workspaceChangesDiscarded: true,
+    };
+    const reason = execution.exitCode === 0 && !execution.timedOut
+        ? 'contained_execution_complete'
+        : 'contained_execution_failed';
+    const mediatedResult = {
+        ...result,
+        verdict: 'allow',
+        reason,
+        mediatedExecution,
+    };
+    await deps.appendAudit(ctx, {
+        ...containedAuditBase(action.kind, ctx.config.mode, mediatedResult),
+        verdict: mediatedResult.verdict,
+        reason,
+        wouldBlock: false,
+        permission: 'deny',
+        receiptHash: execution.receiptHash,
+        imageId: execution.receipt.imageId,
+        mirrorBackend,
+        exitCode: execution.exitCode,
+        timedOut: execution.timedOut,
+    });
+    const status = execution.timedOut
+        ? 'timed out'
+        : execution.exitCode === 0
+            ? 'completed successfully'
+            : `failed with exit ${execution.exitCode}`;
+    const output = [
+        mediatedExecution.stdout
+            ? `stdout tail${mediatedExecution.stdoutTruncated ? ' (truncated)' : ''}:\n${mediatedExecution.stdout}`
+            : '',
+        mediatedExecution.stderr
+            ? `stderr tail${mediatedExecution.stderrTruncated ? ' (truncated)' : ''}:\n${mediatedExecution.stderr}`
+            : '',
+    ]
+        .filter(Boolean)
+        .join('\n');
+    return classifyResultToGateVerdict({
+        result: mediatedResult,
+        mode: ctx.config.mode,
+        permission: 'deny',
+        wouldBlock: false,
+        user_message: `Belay contained execution ${status}; the original host command was not run and workspace changes were discarded. Receipt: ${execution.receiptHash}.` +
+            (output ? `\n${output}` : ''),
+        agent_message: `Belay already ran this command once inside the contained boundary (${status}). Do not retry it on the host. Receipt: ${execution.receiptHash}.` +
+            (output ? `\n${output}` : ''),
+    });
+}
 export async function evaluateGatedAction(ctx, deps, params) {
     let action;
     try {
@@ -462,6 +681,20 @@ export async function evaluateGatedAction(ctx, deps, params) {
         egressProxyActive,
     };
     const predicted = await classifyGatedActionAsync(action, ctx.config, enrichedClassifierOptions);
+    if (action.kind === 'shell' &&
+        action.command &&
+        isContainedUnknownExecutionEligible(ctx.config, action, predicted)) {
+        const mediated = await mediateContainedUnknownExecution({
+            ctx,
+            deps,
+            action,
+            command: action.command,
+            result: predicted,
+        });
+        if (mediated) {
+            return mediated;
+        }
+    }
     let result = predicted;
     let predictedAssessment;
     let observedAssessment;
@@ -787,35 +1020,6 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
             agent_message: agentMessage,
         });
     }
-    if (kind !== 'shell' &&
-        result.verdict === 'deny_pending_approval' &&
-        ctx.config.mode === 'enforce' &&
-        !TRANSACTIONAL_APPROVAL_BYPASS_REASONS.has(result.reason)) {
-        const standingAllowPath = standingAllowFile(ctx.config, ctx.layout.repoLocalStateDir(ctx.repoRoot));
-        const standingState = await loadStandingAllow(standingAllowPath);
-        const standingMatch = resolveStandingAllowMatch({
-            kind,
-            result,
-            repoRoot: ctx.repoRoot,
-            state: standingState,
-        });
-        if (standingMatch) {
-            await deps.appendAudit(ctx, {
-                ...gateBase,
-                verdict: 'allow',
-                reason: 'standing_allow',
-                standingAllowSource: standingMatch.source,
-                wouldBlock: false,
-                permission: 'allow',
-            });
-            return classifyResultToGateVerdict({
-                result: { ...result, verdict: 'allow', reason: 'standing_allow' },
-                mode: ctx.config.mode,
-                permission: 'allow',
-                wouldBlock: false,
-            });
-        }
-    }
     const brokerActive = isCapabilityBrokerDemotionActive(ctx.config);
     let approved = null;
     if (!TRANSACTIONAL_APPROVAL_BYPASS_REASONS.has(result.reason) &&