@guilz-dev/belay 0.8.1 → 0.9.1

package/README.md

@@ -122,7 +122,13 @@ approved shell action first, then lets the remaining prompt continue. CLI replay
 
 Approvals are one-shot and expire after 15 minutes by default. Every decision is
 written to `.cursor/belay/audit.ndjson`, `.claude/belay/audit.ndjson`, or
-`.codex/belay/audit.ndjson` (depending on the adapter).
+`.codex/belay/audit.ndjson` (depending on the adapter). Schema v3 preserves ISO
+timestamps, fingerprints, and `approvalCorrelationId` for metrics joins. Dogfood
+readiness counts only the active cohort (runtime bundle + authorization-relevant
+config + boundary profile); legacy placeholder logs should be archived via
+`belay upgrade` before trusting readiness. See
+[config schema — audit log](./docs/config-schema.md#audit-log-ndjson-schema-v3) and
+[dogfood audit remediation](./docs/dogfood-audit-remediation-2026-08-22.ja.md).
 
 In **audit mode** (`mode: "audit"`), would-be denials are recorded
 (`wouldBlock: true`) but execution still continues, and no approval IDs are
@@ -135,12 +141,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 +155,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 +295,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 +353,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/claude/runtime-entry.js

@@ -162,6 +162,7 @@ export async function runShellGateHook() {
             command,
             payload,
             toolName: 'Bash',
+            sourceEvent: 'PreToolUse',
         });
         jsonResponse(gateVerdictToClaudePreToolUseResponse(verdict));
     }
@@ -261,6 +262,7 @@ export async function runToolGateHook(_eventName) {
             cwd,
             payload: normalizedPayload,
             toolName,
+            sourceEvent: 'PreToolUse',
         });
         jsonResponse(gateVerdictToClaudePreToolUseResponse(verdict));
     }

package/dist/adapters/codex/runtime-entry.js

@@ -180,6 +180,7 @@ export async function runToolGateHook(eventName) {
             command: kind === 'shell' ? extractString(normalizedPayload.tool_input, 'command') : undefined,
             payload: normalizedPayload,
             toolName,
+            sourceEvent: eventName,
         });
         jsonResponse(gateVerdictToCodexPreToolUseResponse(verdict));
     }
@@ -209,6 +210,7 @@ export async function runShellGateHook() {
             command,
             payload,
             toolName: 'Shell',
+            sourceEvent: 'PreToolUse',
         });
         jsonResponse(gateVerdictToCodexPreToolUseResponse(verdict));
     }

package/dist/adapters/cursor/hooks.d.ts

@@ -1,2 +1,6 @@
-import type { HooksFile } from '../../types.js';
+import type { HookEntry, HooksFile } from '../../types.js';
+/** Legacy Belay-managed Shell preToolUse gate duplicated beforeShellExecution. */
+export declare function legacyManagedShellPreToolUseEntry(platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HookEntry;
+export declare function removeLegacyManagedShellPreToolUse(hooks: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HooksFile;
 export declare function mergeCursorHooksFile(current: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): HooksFile;
+export declare function hasDuplicateCursorShellGates(hooks: HooksFile, platform: NodeJS.Platform, hooksDir: string, repoRoot: string): boolean;

package/dist/adapters/cursor/hooks.js

@@ -10,10 +10,37 @@ function mergeHookEntry(current, expected, placement) {
     }
     return [...filtered, expected];
 }
+/** Legacy Belay-managed Shell preToolUse gate duplicated beforeShellExecution. */
+export function legacyManagedShellPreToolUseEntry(platform, hooksDir, repoRoot) {
+    const managed = getManagedHookEntries(platform, hooksDir, repoRoot);
+    const referencePreToolUse = managed.find((entry) => entry.event === 'preToolUse' && entry.definition.matcher === 'Write')?.definition;
+    if (!referencePreToolUse) {
+        throw new Error('managed hook definitions missing for legacy Shell migration');
+    }
+    return {
+        command: referencePreToolUse.command,
+        matcher: 'Shell',
+    };
+}
+export function removeLegacyManagedShellPreToolUse(hooks, platform, hooksDir, repoRoot) {
+    const legacy = legacyManagedShellPreToolUseEntry(platform, hooksDir, repoRoot);
+    const preToolUse = hooks.hooks.preToolUse;
+    if (!Array.isArray(preToolUse)) {
+        return hooks;
+    }
+    return {
+        ...hooks,
+        hooks: {
+            ...hooks.hooks,
+            preToolUse: preToolUse.filter((entry) => !entryMatches(entry, legacy)),
+        },
+    };
+}
 export function mergeCursorHooksFile(current, platform, hooksDir, repoRoot) {
+    const withoutLegacyShell = removeLegacyManagedShellPreToolUse(current, platform, hooksDir, repoRoot);
     const next = {
-        version: current.version || 1,
-        hooks: { ...current.hooks },
+        version: withoutLegacyShell.version || 1,
+        hooks: { ...withoutLegacyShell.hooks },
     };
     const managedEntries = getManagedHookEntries(platform, hooksDir, repoRoot);
     for (const { event, definition } of managedEntries) {
@@ -24,3 +51,11 @@ export function mergeCursorHooksFile(current, platform, hooksDir, repoRoot) {
     }
     return next;
 }
+export function hasDuplicateCursorShellGates(hooks, platform, hooksDir, repoRoot) {
+    const legacy = legacyManagedShellPreToolUseEntry(platform, hooksDir, repoRoot);
+    const preToolUse = hooks.hooks.preToolUse;
+    if (!Array.isArray(preToolUse)) {
+        return false;
+    }
+    return preToolUse.some((entry) => entryMatches(entry, legacy));
+}

package/dist/adapters/cursor/runtime-entry.js

@@ -65,6 +65,7 @@ export async function runShellGateHook() {
             kind: 'shell',
             cwd,
             command,
+            sourceEvent: 'beforeShellExecution',
         });
         jsonResponse(gateVerdictToCursorResponse(verdict));
     }
@@ -87,6 +88,7 @@ export async function runToolGateHook(eventName) {
                 kind: 'subagent',
                 cwd,
                 payload,
+                sourceEvent: eventName,
             });
             jsonResponse(gateVerdictToCursorResponse(verdict));
             return;
@@ -97,6 +99,7 @@ export async function runToolGateHook(eventName) {
                 cwd,
                 payload,
                 toolName,
+                sourceEvent: eventName,
             });
             jsonResponse(gateVerdictToCursorResponse(verdict));
             return;
@@ -107,6 +110,7 @@ export async function runToolGateHook(eventName) {
                 cwd,
                 payload,
                 toolName,
+                sourceEvent: eventName,
             });
             jsonResponse(gateVerdictToCursorResponse(verdict));
             return;
@@ -116,6 +120,7 @@ export async function runToolGateHook(eventName) {
                 kind: 'subagent',
                 cwd,
                 payload,
+                sourceEvent: eventName,
             });
             jsonResponse(gateVerdictToCursorResponse(verdict));
             return;

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>;
@@ -41,6 +46,7 @@ export declare function evaluateGatedAction(ctx: GateRuntimeContext, deps: GateR
     command?: string;
     payload?: Record<string, unknown>;
     toolName?: string;
+    sourceEvent?: string;
 }): Promise<GateVerdict>;
 /** R39: unmapped Codex tools ask via pending approval — not hard deny without approval path. */
 export declare function gateUnmappedToolVerdict(ctx: GateRuntimeContext, deps: GateRuntimeDeps, toolName: string, payload: Record<string, unknown>): Promise<GateVerdict>;