@guilz-dev/belay 0.1.1 → 0.3.0

package/README.md

@@ -1,6 +1,7 @@
 # Belay
 
 [![npm version](https://img.shields.io/npm/v/@guilz-dev/belay)](https://www.npmjs.com/package/@guilz-dev/belay)
+[![skills.sh](https://skills.sh/b/guilz-dev/belay)](https://skills.sh/guilz-dev/belay)
 [![CI](https://github.com/guilz-dev/belay/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/guilz-dev/belay/actions/workflows/ci.yml)
 [![License](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
 
@@ -33,8 +34,8 @@ policy to maintain.
 | **Claude Code** | Supported | `.claude/settings.json` | `.claude/belay.config.json` |
 | **Codex** | Experimental | `.codex/config.toml` | `.codex/belay.config.json` |
 
-Pick the adapter at install time with `--adapter cursor|claude|codex` (or let
-`init-wizard` prompt). Hosts use different hook event names, but Belay registers
+Pick the adapter at install time with `--adapter cursor|claude|codex` (or use
+`belay config` interactively). Hosts use different hook event names, but Belay registers
 the same runners (`belay-tool-gate`, `belay-before-submit`, `belay-audit`) at
 equivalent lifecycle points:
 
@@ -67,8 +68,8 @@ audit instead of guessing.
 ## Quick start
 
 ```bash
-# Interactive setup (prompts for adapter, scope, skill, mode)
-npx @guilz-dev/belay init-wizard
+# Interactive setup (adapter, scope, skill, judge provider, credentials)
+belay config
 
 # Or non-interactive
 npx @guilz-dev/belay init --adapter claude   # Claude Code
@@ -130,6 +131,9 @@ Belay is a layered hook gate, not a static denylist. Higher layers are opt-in.
 - L3 command lists are **not security boundaries** by themselves — see
   [docs/ops/semver-policy.md](./docs/ops/semver-policy.md) and
   [docs/guarantee-table.md](./docs/guarantee-table.md).
+- At default L3, **local-recoverable mutations outside the repo** pass after Tier1
+  (e.g. IDE plan files). To deny repo-external writes at the OS boundary, enable L1-full
+  (`sandbox.runtime` ≠ `none`). Tier1 requires a working judge (local Ollama by default).
 - Adversarial resistance requires the full L1 stack:
   `belay init --preset l1-full-recommended`, verified with `belay sandbox status`.
 
@@ -148,12 +152,23 @@ and skill under `~/.cursor/`, so the gate is user-wide while `belay.config.json`
 approvals, and audit stay repo-local.
 
 **Skill-only.** The skill is just a UX layer (slash commands + guidance) and does
-**not** enable gating on its own:
+**not** enable gating on its own. Install from [skills.sh](https://skills.sh/guilz-dev/belay)
+or GitHub:
 
 ```bash
+# Cursor
 npx skills add guilz-dev/belay --skill belay -a cursor -y
+
+# Claude Code
+npx skills add guilz-dev/belay --skill belay -a claude-code -y
+
+# Codex
+npx skills add guilz-dev/belay --skill belay -a codex -y
 ```
 
+Running `npx skills add` also registers anonymous install telemetry on skills.sh,
+which is how the skill appears in the directory leaderboard.
+
 Runtime enforcement still requires `belay init` in the target repository.
 
 ## Dogfood → enforce
@@ -213,8 +228,9 @@ load.
 
 Notable settings:
 
-- **`policy.unknownLocalEffect: "deny"`** — fail-closed classification for
-  unrecognized local commands.
+- **`policy.unknownLocalEffect: "allow_flagged"`** (fresh default) — after Tier1
+  says recoverable, structurally unknown local commands run with an audit flag. Use
+  `"deny"` (via `belay dogfood`) to ask on those commands instead.
 - **`classifier.strictChains: true`** (default) — scans every `&&`, `|`, and `;`
   segment and keeps the strictest verdict. Override lists match exact command or
   segment keys only.
@@ -223,20 +239,37 @@ Notable settings:
   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.
-- **Cloud judge** — for `judge.provider: "openai-compatible"`, set
-  `judge.endpoint` and provide `BELAY_JUDGE_API_KEY` (or `OPENAI_API_KEY`), or
-  opt in with
-  `belay init --judge-provider openai-compatible --judge-endpoint <url> --accept-cloud-judge`.
-  Fresh installs default to local Ollama (`local-ollama`).
+- **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`:
+  `ollama`, `openai-compatible`, or `anthropic`); **host** is where hooks install
+  (`config.adapter`: `cursor`, `claude`, `codex`). Set `judge.endpoint` when needed;
+  credentials via `belay config credential mode project|apiKey` or env vars. Record egress
+  consent during `belay config` or via `belay judge consent` → `belay approve` →
+  `belay judge use … --cloud-consent-approval-id`. Cloud providers can use native CLI
+  transport without `judge.endpoint` when the host CLI is available (`codex-cli`,
+  `cursor-cli`, `claude-cli`); HTTP transport still requires endpoint and recorded consent.
+  Fresh installs default to the
+  host-matched provider (`cursor` → `cursor`, etc.). `belay judge use` remains available
+  as a secondary path.
+
+  Legacy `judge.model: auto` in config files is normalized to the provider catalog default on load
+  (with a warning); new `auto` values are rejected on CLI, `belay config set`, and `belay judge use`.
+  On an installed repo, interactive `belay config` defaults to judge-only setup without re-running
+  `init`. Model discovery is covered by unit tests with mocks; set `BELAY_LIVE_CLI_DISCOVERY=1` locally
+  for optional live CLI probes. Cloud egress consent is enforced for HTTP transport; native CLI
+  transport uses the host session and does not require `judge.endpoint`. `BELAY_JUDGE_MODEL_RESOLVED`
+  applies only under Vitest (test overrides).
 
 ## Command reference
 
 ```bash
 belay init [--adapter cursor|claude|codex] [--scope project|global]
            [--preset strict|standard|audit-first|l1-full-recommended]
-           [--with-skill] [--dogfood]
-belay init-wizard                # interactive install
-belay upgrade                    # refresh hooks + runtime, migrate config
+           [--migrate-judge-default] [--with-skill] [--dogfood]
+belay config                     # interactive setup (primary)
+belay config list|get|set|unset|judge|credential …
+belay upgrade [--migrate-judge-default]   # refresh hooks + runtime, migrate config
 belay dogfood [--enforce]        # toggle audit / enforce mode
 belay doctor [--fix]             # check (and repair) floor health
 belay status                     # show install scope / skill-only state
@@ -250,6 +283,13 @@ belay egress <start|stop|status|env>
 belay sandbox status
 belay approve <approval-id> [--scope once|domain|path]
 belay revoke <approval-id>
+belay judge status
+belay judge list
+belay judge use <ollama|codex|claude|cursor> [--model <id>] [--endpoint <url>]
+           [--accept-cloud] [--cloud-consent-approval-id <id>]
+           [--credential project|apiKey] [--key-stdin] [--key-env <NAME>]
+belay judge test
+belay judge consent <provider-id> [--endpoint <url>]
 ```
 
 ## Coexisting with existing hooks

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

@@ -4,11 +4,11 @@ import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { recordApproval } from '../../core/approval-service.js';
 import { issueApprovalToken } from '../../core/approval-token.js';
-import { fsScopeAllowlistPath, isCapabilityBrokerDemotionActive, loadFsScopeAllowlistSync, shouldSkipBrokerApprovedOnce, } from '../../core/capability/index.js';
+import { fsScopeAllowlistPath, isCapabilityBrokerDemotionActive, loadFsScopeAllowlistSync, shouldSkipBrokerApprovedOnce, shouldSkipBrokerApprovedRecord, } from '../../core/capability/index.js';
 import { resolveLayeredConfig, teamConfigPath } from '../../core/config-layers.js';
 import { classifyResultToGateVerdict, unnormalizedGateVerdict, } from '../../core/gate-contract.js';
 import { classifyGatedActionAsync, extractAgentAssessment, GateNormalizationError, gateEnabledForAction, normalizeGatedAction, } from '../../core/gate-engine.js';
-import { approvalCommandMatch, approvedApprovalsFile, buildRetryInstruction, canonicalStringify, classifierOptionsFromConfig, compactApprovals, configuredControlPlaneDir, createApprovalRecord, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubValue, toolFingerprint, } from '../../core/index.js';
+import { APPROVAL_EXECUTION_LEASE_MS, approvalCommandMatch, approvedApprovalsFile, buildRetryInstruction, canonicalStringify, classifierOptionsFromConfig, compactApprovals, configuredControlPlaneDir, createApprovalRecord, pendingApprovalsFile, resolveControlPlaneDir, scrubOptionsFromConfig, scrubValue, toolFingerprint, } from '../../core/index.js';
 import { notifyDeny } from '../../core/notify.js';
 import { isTransactionalEligible, runTransactionalExecution, TRANSACTIONAL_ALREADY_APPLIED, TRANSACTIONAL_APPROVAL_BYPASS_REASONS, } from '../../core/transactional/index.js';
 import { protectedArtifactRoots } from '../layouts/protected-paths.js';
@@ -142,7 +142,15 @@ async function consumeApprovedApproval(ctx, deps, kind, fingerprint) {
         await deps.writeApprovals(approved.filePath, approved.state);
         return null;
     }
-    const [approval] = approved.state.approvals.splice(index, 1);
+    const approval = approved.state.approvals[index];
+    if (approval.executionLeaseExpiresAt) {
+        await deps.writeApprovals(approved.filePath, approved.state);
+        return approval;
+    }
+    approved.state.approvals[index] = {
+        ...approval,
+        executionLeaseExpiresAt: new Date(Date.now() + APPROVAL_EXECUTION_LEASE_MS).toISOString(),
+    };
     await deps.writeApprovals(approved.filePath, approved.state);
     return approval;
 }
@@ -290,8 +298,8 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
         predictedAssessment: auditExtras.predictedAssessment,
         observedAssessment: auditExtras.observedAssessment,
         mode: ctx.config.mode,
-        schemaVersion: result.v2 ? 2 : 1,
-        ...(result.v2 ?? {}),
+        schemaVersion: result.axes ? 2 : 1,
+        ...(result.axes ?? {}),
         ...auditExtras.transactionalLayer,
     };
     if (result.reason === TRANSACTIONAL_ALREADY_APPLIED) {
@@ -314,10 +322,18 @@ async function gateDecisionToVerdict(ctx, deps, kind, result, auditExtras = {})
         });
     }
     const brokerActive = isCapabilityBrokerDemotionActive(ctx.config);
-    const approved = TRANSACTIONAL_APPROVAL_BYPASS_REASONS.has(result.reason) ||
-        shouldSkipBrokerApprovedOnce(brokerActive, result.reason)
-        ? null
-        : await consumeApprovedApproval(ctx, deps, kind, result.fingerprint);
+    let approved = null;
+    if (!TRANSACTIONAL_APPROVAL_BYPASS_REASONS.has(result.reason) &&
+        !shouldSkipBrokerApprovedOnce(brokerActive, result.reason)) {
+        const approvedState = await deps.loadApprovals(ctx, 'approved-approvals.json');
+        approvedState.state = compactApprovals(approvedState.state);
+        const matchedApproval = approvedState.state.approvals.find((entry) => entry.kind === kind &&
+            entry.fingerprint === result.fingerprint &&
+            entry.repoRoot === ctx.repoRoot);
+        if (!shouldSkipBrokerApprovedRecord(brokerActive, matchedApproval?.reason)) {
+            approved = await consumeApprovedApproval(ctx, deps, kind, result.fingerprint);
+        }
+    }
     if (approved) {
         await deps.appendAudit(ctx, {
             ...gateBase,