@guilz-dev/belay 0.4.0 → 0.7.0

package/dist/corpus/evaluate.js

@@ -3,7 +3,6 @@ import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 import { classifierOptionsFromConfig, DEFAULT_CONFIG_V3 } from '../core/config.js';
 import { classifyShell } from '../core/verdict/adapter.js';
-import { createDeterministicJudgeStub } from '../core/verdict/judge.js';
 import { computeCategoryGates, isMustAskMiss, } from './gates.js';
 import { defaultCorpusEvalPaths, enrichProvablyBenignRuntimeKeys } from './runtime-match.js';
 import { countByCategory, countProvenanceBySource, parseCorpusCases, } from './types.js';
@@ -31,9 +30,8 @@ export async function evaluateCorpus(cases, repoRoot = defaultCorpusEvalPaths().
     for (const expected of VERDICTS) {
         confusion[expected] = { allow: 0, allow_flagged: 0, deny_pending_approval: 0 };
     }
-    const judge = createDeterministicJudgeStub();
     for (const testCase of cases) {
-        const result = await classifyShell(testCase.command, cwd, repoRoot, DEFAULT_CONFIG_V3, options, judge);
+        const result = await classifyShell(testCase.command, cwd, repoRoot, DEFAULT_CONFIG_V3, options);
         results.push({ actual: result.verdict, reason: result.reason });
         confusion[testCase.verdict][result.verdict] += 1;
         const verdictOk = result.verdict === testCase.verdict;
@@ -83,10 +81,9 @@ export async function runCorpusEvaluation(corpusDir) {
 export async function evaluateCommandBatch(cases, repoRoot = defaultCorpusEvalPaths().repoRoot) {
     const { cwd } = defaultCorpusEvalPaths(repoRoot);
     const options = classifierOptionsFromConfig(DEFAULT_CONFIG_V3);
-    const judge = createDeterministicJudgeStub();
     const results = [];
     for (const testCase of cases) {
-        const result = await classifyShell(testCase.command, cwd, repoRoot, DEFAULT_CONFIG_V3, options, judge);
+        const result = await classifyShell(testCase.command, cwd, repoRoot, DEFAULT_CONFIG_V3, options);
         const isFn = isMustAskMiss({
             category: 'must-ask',
             command: testCase.command,
@@ -109,10 +106,9 @@ export async function evaluateCommandBatch(cases, repoRoot = defaultCorpusEvalPa
 export async function evaluateFpCommandBatch(cases, repoRoot = defaultCorpusEvalPaths().repoRoot) {
     const { cwd } = defaultCorpusEvalPaths(repoRoot);
     const options = classifierOptionsFromConfig(DEFAULT_CONFIG_V3);
-    const judge = createDeterministicJudgeStub();
     const results = [];
     for (const testCase of cases) {
-        const result = await classifyShell(testCase.command, cwd, repoRoot, DEFAULT_CONFIG_V3, options, judge);
+        const result = await classifyShell(testCase.command, cwd, repoRoot, DEFAULT_CONFIG_V3, options);
         results.push({
             command: testCase.command,
             actual: result.verdict,

package/dist/corpus/gate-latency-budget.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Gate sync classification latency budgets (measured baselines + CI thresholds).
+ * PLAN target: p95 <= 100ms, max <= 500ms for full corpus — ratchet toward these over time.
+ */
+/** Warm local corpus run (2026-08-06). Step 3 uses max(measured × 1.2, Step 1 floor); floors dominate until re-measured and lowered. */
+export declare const GATE_LATENCY_MEASURED_BASELINE: {
+    readonly shell: {
+        readonly p95Ms: 1;
+        readonly maxMs: 1;
+    };
+    readonly tool: {
+        readonly p95Ms: 1;
+        readonly maxMs: 1;
+    };
+    readonly subagent: {
+        readonly p95Ms: 7;
+        readonly maxMs: 7;
+    };
+};
+/** Step 3 CI thresholds: max(measured p95 × 1.2, Step 1 floor). */
+export declare const GATE_LATENCY_BUDGET: {
+    readonly shell: {
+        p95Ms: number;
+        maxMs: number;
+    };
+    readonly tool: {
+        p95Ms: number;
+        maxMs: number;
+    };
+    readonly subagent: {
+        p95Ms: number;
+        maxMs: number;
+    };
+};
+/** PLAN acceptance targets (quality-loop ratchet goal). */
+export declare const GATE_LATENCY_PLAN_TARGET: {
+    readonly p95Ms: 100;
+    readonly maxMs: 500;
+};

package/dist/corpus/gate-latency-budget.js

@@ -0,0 +1,33 @@
+/**
+ * Gate sync classification latency budgets (measured baselines + CI thresholds).
+ * PLAN target: p95 <= 100ms, max <= 500ms for full corpus — ratchet toward these over time.
+ */
+/** Warm local corpus run (2026-08-06). Step 3 uses max(measured × 1.2, Step 1 floor); floors dominate until re-measured and lowered. */
+export const GATE_LATENCY_MEASURED_BASELINE = {
+    shell: { p95Ms: 1, maxMs: 1 },
+    tool: { p95Ms: 1, maxMs: 1 },
+    subagent: { p95Ms: 7, maxMs: 7 },
+};
+/** Step 1 rollout floors — CI thresholds stay at these until measured × 1.2 exceeds them. */
+const GATE_LATENCY_STEP1_FLOOR = {
+    shell: { p95Ms: 200, maxMs: 1000 },
+    tool: { p95Ms: 300, maxMs: 1500 },
+    subagent: { p95Ms: 200, maxMs: 1000 },
+};
+function ciBudgetFromBaseline(baseline, floor) {
+    return {
+        p95Ms: Math.max(floor.p95Ms, Math.ceil(baseline.p95Ms * 1.2)),
+        maxMs: Math.max(floor.maxMs, Math.ceil(baseline.maxMs * 1.2)),
+    };
+}
+/** Step 3 CI thresholds: max(measured p95 × 1.2, Step 1 floor). */
+export const GATE_LATENCY_BUDGET = {
+    shell: ciBudgetFromBaseline(GATE_LATENCY_MEASURED_BASELINE.shell, GATE_LATENCY_STEP1_FLOOR.shell),
+    tool: ciBudgetFromBaseline(GATE_LATENCY_MEASURED_BASELINE.tool, GATE_LATENCY_STEP1_FLOOR.tool),
+    subagent: ciBudgetFromBaseline(GATE_LATENCY_MEASURED_BASELINE.subagent, GATE_LATENCY_STEP1_FLOOR.subagent),
+};
+/** PLAN acceptance targets (quality-loop ratchet goal). */
+export const GATE_LATENCY_PLAN_TARGET = {
+    p95Ms: 100,
+    maxMs: 500,
+};

package/dist/corpus/mutators.d.ts

@@ -18,7 +18,7 @@ export interface MutatedCase {
     command: string;
 }
 /** Must-ask catastrophic cores used as mutation seeds. */
-export declare const CATASTROPHIC_CORES: readonly ["rm -rf .git", "git push --force", "dropdb prod", "npm publish", "aws s3 rm s3://bucket/key", "terraform apply", "rm -rf ~"];
+export declare const CATASTROPHIC_CORES: readonly ["rm -rf .git", "git push --force", "git reset --hard", "git clean -fdx", "dropdb prod", "npm publish", "aws s3 rm s3://bucket/key", "terraform apply", "rm -rf ~"];
 /** Phase A initial set — conservative semantics-preserving mutators only. */
 export declare const AUTO_LABEL_MUTATORS: readonly CommandMutator[];
 /** Structural probes and promotion candidates — not used for auto-label in Phase A. */

package/dist/corpus/mutators.js

@@ -8,6 +8,8 @@
 export const CATASTROPHIC_CORES = [
     'rm -rf .git',
     'git push --force',
+    'git reset --hard',
+    'git clean -fdx',
     'dropdb prod',
     'npm publish',
     'aws s3 rm s3://bucket/key',
@@ -120,6 +122,14 @@ const xargsProbe = {
     tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
     apply: (core) => `xargs ${core} <<< ''`,
 };
+const findExecProbe = {
+    id: 'find_exec',
+    purpose: 'find -exec invocation probe',
+    preservesSemantics: 'Not semantics-preserving — find -exec changes execution context',
+    forbiddenWhen: 'Always probe-only; do not auto-label',
+    tests: ['structural-suite MUST-ASK catastrophic bypass equivalence'],
+    apply: (core) => `find . -name '*.tmp' -exec ${core} {} \\;`,
+};
 /** Structural probes and promotion candidates — not used for auto-label in Phase A. */
 export const STRUCTURAL_PROBES = [
     nohup,
@@ -130,6 +140,7 @@ export const STRUCTURAL_PROBES = [
     base64PipeSh,
     pythonPipe,
     xargsProbe,
+    findExecProbe,
 ];
 /** All wrappers for structural-suite catastrophic bypass tests. */
 export const ALL_STRUCTURAL_WRAPPERS = [

package/dist/corpus/runtime-match.js

@@ -1,7 +1,6 @@
 import path from 'node:path';
 import { classifierOptionsFromConfig, DEFAULT_CONFIG_V3 } from '../core/config.js';
 import { classifyShell } from '../core/verdict/adapter.js';
-import { createDeterministicJudgeStub } from '../core/verdict/judge.js';
 import { CorpusSchemaError } from './types.js';
 /** Fixed evaluation harness paths — keep in sync with `evaluateCorpus`. */
 export const DEFAULT_CORPUS_REPO_ROOT = '/workspace/project';
@@ -14,8 +13,7 @@ export function defaultCorpusEvalPaths(repoRoot = DEFAULT_CORPUS_REPO_ROOT) {
  */
 export async function deriveShellCorpusRuntimeKey(command, repoRoot = DEFAULT_CORPUS_REPO_ROOT, cwd = path.join(repoRoot, 'src')) {
     const options = classifierOptionsFromConfig(DEFAULT_CONFIG_V3);
-    const judge = createDeterministicJudgeStub();
-    const result = await classifyShell(command, cwd, repoRoot, DEFAULT_CONFIG_V3, options, judge);
+    const result = await classifyShell(command, cwd, repoRoot, DEFAULT_CONFIG_V3, options);
     return result.fingerprint;
 }
 /**

package/dist/corpus/standing-allow-catalog.generated.js

@@ -7,6 +7,16 @@ export const STANDING_ALLOW_CATALOG = {
                 normalizedCommand: 'git status',
                 runtimeKey: '37e6be21e63e6268ee6e4212ad811f6f48ab3c3c10ce1b971c1a90d92c753a2a',
             },
+            {
+                command: 'git branch',
+                normalizedCommand: 'git branch',
+                runtimeKey: 'd7f8388c566e751503ab82ba1ed22787389803eb32d8b5f2294cc7ca448fa285',
+            },
+            {
+                command: 'git branch --show-current',
+                normalizedCommand: 'git branch --show-current',
+                runtimeKey: '98d585412d3cd7c3b5a87a417d91bc36d7b6791e11451b52ced7888e003d9d33',
+            },
             {
                 command: 'rg plan src',
                 normalizedCommand: 'rg plan src',
@@ -23,19 +33,29 @@ export const STANDING_ALLOW_CATALOG = {
                 runtimeKey: '782298e3015fcb9c17bee2dad12a395a8859043481f93f0ca596499028bb8af2',
             },
             {
-                command: 'curl https://example.com',
-                normalizedCommand: 'curl https://example.com',
-                runtimeKey: '09fa1bf897aa68a2d0be02cff3b0cbfa44a28fa17c501e8a39f2081208785e55',
+                command: 'git -C /workspace/project status',
+                normalizedCommand: 'git -C /workspace/project status',
+                runtimeKey: '9f88bd017c52277f5dbfeafec7d845460035a7a14bfb37b55724d7e2a9fc238b',
+            },
+            {
+                command: 'git show-ref --heads',
+                normalizedCommand: 'git show-ref --heads',
+                runtimeKey: 'aa5aa0106dc7647003f254524becbf549673610d3672f28408ac0f60481124b7',
+            },
+            {
+                command: 'git reflog -5',
+                normalizedCommand: 'git reflog -5',
+                runtimeKey: '9213a9357953c24886a4e82c2c8cdc6db2d106c7ff98af525f7fbc2b70a58ff9',
             },
             {
-                command: 'wget https://example.com',
-                normalizedCommand: 'wget https://example.com',
-                runtimeKey: 'c408836b4bb4498b68b52e08a7c852757a19e156cae7579ffd5c98f13728cacb',
+                command: 'grep -R pattern src',
+                normalizedCommand: 'grep -R pattern src',
+                runtimeKey: '40f5e0328e668909241aa0cd13ce2a51af269aa7ae600cc493dceae7b90dd9d8',
             },
             {
-                command: 'ls\ncurl https://example.com',
-                normalizedCommand: 'ls\ncurl https://example.com',
-                runtimeKey: 'a895f27dda259649bbe0d27fcc04ab7076fadfcd4c2ea3ab55f557028b01b11f',
+                command: 'jq . package.json',
+                normalizedCommand: 'jq . package.json',
+                runtimeKey: 'dd7b14d350b84a41e0e73eae0d1a643c1b6c262df8d9007696987354f4f993e9',
             },
         ],
         mustAllow: [

package/dist/judge-broker-daemon.js

@@ -1,6 +1,7 @@
 import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
 import { createServer } from 'node:net';
 import path from 'node:path';
+import { CursorAcpJudgeRunner } from './core/verdict/cursor-acp-client.js';
 import { cleanupJudgeBrokerArtifacts, JUDGE_BROKER_SESSION, judgeBrokerPaths, } from './core/verdict/judge-broker-service.js';
 import { runCliJsonWithTimeouts } from './core/verdict/judge-cli.js';
 import { DEFAULT_JUDGE_SESSION_CONFIG, normalizeJudgeSessionConfig, resolveSessionEvalTimeoutMs, } from './core/verdict/judge-runtime-config.js';
@@ -27,9 +28,21 @@ async function main() {
     await mkdir(stateDir, { recursive: true, mode: 0o700 });
     const sessionConfig = await loadBrokerSessionConfig(stateDir);
     const defaultEvalTimeoutMs = resolveSessionEvalTimeoutMs(sessionConfig, 25_000);
+    const judgeWorkspace = path.join(stateDir, 'judge-workspace');
+    await mkdir(judgeWorkspace, { recursive: true, mode: 0o700 });
+    const cursorAcp = new CursorAcpJudgeRunner({
+        cwd: judgeWorkspace,
+        connectTimeoutMs: sessionConfig.connectTimeoutMs,
+    });
     const broker = new JudgeSessionBroker({
         config: sessionConfig,
-        runCommand: (invocation, timeoutMs) => runCliJsonWithTimeouts(invocation, { evalTimeoutMs: timeoutMs }),
+        runCommand: (invocation, timeoutMs) => {
+            if (invocation.binary === 'cursor-agent') {
+                return cursorAcp.run(invocation, timeoutMs);
+            }
+            return runCliJsonWithTimeouts(invocation, { evalTimeoutMs: timeoutMs });
+        },
+        extractResumeId: (providerId) => (providerId === 'cursor' ? cursorAcp.sessionId : null),
     });
     let idleTimer = null;
     let server;
@@ -43,6 +56,7 @@ async function main() {
     };
     const shutdown = async (reason) => {
         broker.stopAll('manual_stop');
+        await cursorAcp.stop();
         server?.close();
         await cleanupJudgeBrokerArtifacts(paths);
         process.stderr.write(`judge broker stopped (${reason})\n`);

package/dist/services/sandbox-service.d.ts

@@ -1,4 +1,5 @@
 import { loadConfigFile } from '../config-io.js';
+import { evaluateGuaranteePosture } from '../conformance/guarantee-posture.js';
 export interface SandboxServiceOptions {
     targetDir?: string;
 }
@@ -12,6 +13,7 @@ export interface SandboxStatusReport {
     controlPlaneIsolationMode: string;
     controlPlaneIsolationOk: boolean;
     l1FullActive: boolean;
+    guaranteePosture: ReturnType<typeof evaluateGuaranteePosture>;
     l1Full: {
         sandbox: boolean;
         egress: boolean;
@@ -20,6 +22,8 @@ export interface SandboxStatusReport {
         approvalSigningRequired: boolean;
     };
     issues: string[];
+    /** Quality-loop ratchet hints — do not affect sandbox status exit code. */
+    advisories: string[];
 }
 export declare function sandboxStatus(options?: SandboxServiceOptions): Promise<SandboxStatusReport>;
 export declare function createCapabilityApprovalStore(repoRoot: string, config: Awaited<ReturnType<typeof loadConfigFile>>): {

package/dist/services/sandbox-service.js

@@ -1,9 +1,13 @@
 import path from 'node:path';
 import { loadConfigFile, repoLocalStateDirFor } from '../config-io.js';
+import { evaluateGuaranteePosture } from '../conformance/guarantee-posture.js';
 import { fsScopeAllowlistPath, loadFsScopeAllowlist } from '../core/capability/allowlist.js';
+import { boundaryAttestationPath, loadBoundaryAttestation, } from '../core/capability/boundary-session.js';
 import { evaluateL1FullStatus, isCapabilityBrokerDemotionActive, } from '../core/capability/broker.js';
+import { evaluateGateLatencyRatchetAdvisories } from '../core/capability/gate-latency-ratchet.js';
+import { loadShadowRatchetWarnings } from '../core/capability/gate-shadow-ratchet.js';
 import { trustedWorkspaceRootsPath } from '../core/capability/trusted-workspace-roots.js';
-import { configuredControlPlaneDir } from '../core/config.js';
+import { belayStateDir, configuredControlPlaneDir } from '../core/config.js';
 import { verifyControlPlaneIsolation } from '../core/control-plane-isolation.js';
 import { egressStatus } from './egress-service.js';
 export async function sandboxStatus(options = {}) {
@@ -14,10 +18,18 @@ export async function sandboxStatus(options = {}) {
     const allowlist = await loadFsScopeAllowlist(allowlistPath);
     const egress = await egressStatus({ targetDir: repoRoot });
     const isolation = verifyControlPlaneIsolation(configuredControlPlaneDir(config), config.controlPlane.isolation);
+    const egressProxyRunning = egress.running && !egress.foreignProxy && !egress.repoRootMismatch;
     const l1Full = evaluateL1FullStatus({
         config,
-        egressProxyRunning: egress.running && !egress.foreignProxy && !egress.repoRootMismatch,
+        egressProxyRunning,
     });
+    const attestation = await loadBoundaryAttestation(boundaryAttestationPath(repoRoot, config), repoRoot, configuredControlPlaneDir(config));
+    const guaranteePosture = evaluateGuaranteePosture({
+        config,
+        attestation,
+        egressProxyRunning,
+    });
+    const shadowRatchetWarnings = await loadShadowRatchetWarnings(belayStateDir(config, repoLocalStateDir));
     const issues = [...isolation.issues];
     if (config.sandbox.enabled && config.sandbox.runtime === 'none') {
         issues.push('sandbox.enabled is true but sandbox.runtime is none');
@@ -31,6 +43,10 @@ export async function sandboxStatus(options = {}) {
     if (l1Full.sandbox && !l1Full.approvalSigningRequired) {
         issues.push('L1-full requires approvalSigning.required=true');
     }
+    if (guaranteePosture.postureMismatch) {
+        issues.push(`L1-full is configured but attestation only supports ${guaranteePosture.attestedProfile} (run belay session start)`);
+    }
+    const advisories = [...evaluateGateLatencyRatchetAdvisories(), ...shadowRatchetWarnings];
     return {
         repoRoot,
         sandboxEnabled: config.sandbox.enabled,
@@ -41,8 +57,10 @@ export async function sandboxStatus(options = {}) {
         controlPlaneIsolationMode: config.controlPlane.isolation.mode,
         controlPlaneIsolationOk: isolation.ok,
         l1FullActive: l1Full.active,
+        guaranteePosture,
         l1Full,
         issues,
+        advisories,
     };
 }
 export function createCapabilityApprovalStore(repoRoot, config) {
@@ -84,6 +102,8 @@ export function formatSandboxStatusReport(report) {
         `FS-scope allowlist entries: ${report.fsScopeAllowlistCount}`,
         `Control-plane isolation: ${report.controlPlaneIsolationMode} (ok=${report.controlPlaneIsolationOk})`,
         `L1-full active: ${report.l1FullActive}`,
+        `Guarantee posture: configured=${report.guaranteePosture.configuredProfile} attested=${report.guaranteePosture.attestedProfile}`,
+        `  attestationFresh=${report.guaranteePosture.attestationFresh} l1FullConfigured=${report.guaranteePosture.l1FullConfigured} l1FullAttested=${report.guaranteePosture.l1FullAttested}`,
         `  sandbox=${report.l1Full.sandbox} egress=${report.l1Full.egress} proxy=${report.l1Full.egressProxyRunning}`,
         `  isolation=${report.l1Full.controlPlaneIsolation} signing=${report.l1Full.approvalSigningRequired}`,
     ];
@@ -93,5 +113,11 @@ export function formatSandboxStatusReport(report) {
             lines.push(`  - ${issue}`);
         }
     }
+    if (report.advisories.length > 0) {
+        lines.push('Advisories:');
+        for (const advisory of report.advisories) {
+            lines.push(`  - ${advisory}`);
+        }
+    }
     return `${lines.join('\n')}\n`;
 }

package/dist/types.d.ts

@@ -1,5 +1,5 @@
-export type { BelayConfig, BelayConfigV1, BelayConfigV2, BelayConfigV3, BelayControlPlaneConfig, BelayEgressConfig, BelayMode, BelayOverridesConfig, BelayPolicyConfig, BelayRedactionConfig, BelaySandboxConfig, BelayTransactionalConfig, UnknownLocalEffectPolicy, } from './core/config.js';
-export type { ApprovalRecord, ApprovalStateFile, Assessment, ClassifyResult, HookVerdict, } from './core/types.js';
+export type { BelayConfig, BelayConfigV1, BelayConfigV2, BelayConfigV3, BelayControlPlaneConfig, BelayEgressConfig, BelayOverridesConfig, BelayPolicyConfig, BelayRedactionConfig, BelaySandboxConfig, BelayTransactionalConfig, UnknownLocalEffectPolicy, } from './core/config.js';
+export type { ApprovalRecord, ApprovalStateFile, Assessment, BelayMode, ClassifyResult, HookVerdict, } from './core/types.js';
 import type { InstallScope } from './adapters/layouts/scope.js';
 import type { RecentAskEntry } from './core/audit-summary.js';
 import type { BelayEgressConfig, BelayOverridesConfig, BelayPolicyConfig, BelaySandboxConfig } from './core/config.js';
@@ -138,6 +138,17 @@ export interface StatusReport {
     dogfood: DogfoodStatus;
     health: HealthSnapshot;
     visibility: AuditVisibilityReport;
+    fileCheckpoint: {
+        enabled: boolean;
+        allowNonGit: boolean;
+        transactionalEnabled: boolean;
+        durableCheckpointEnabled: boolean;
+        maxFiles: number;
+        maxSourceBytes: number;
+        maxWorkspaceBytes: number;
+        prepareTimeoutMs: number;
+        copyConcurrency: number;
+    };
 }
 export interface ReportOptions {
     targetDir?: string;

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const PACKAGE_VERSION = "0.4.0";
+export declare const PACKAGE_VERSION = "0.7.0";

package/dist/version.js

@@ -1,2 +1,2 @@
 // Generated by scripts/sync-version.mjs — do not edit.
-export const PACKAGE_VERSION = '0.4.0';
+export const PACKAGE_VERSION = '0.7.0';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@guilz-dev/belay",
-  "version": "0.4.0",
+  "version": "0.7.0",
   "description": "Belay-style approval and audit gating for agent runtimes.",
   "type": "module",
   "license": "MIT",

package/skills/belay/SKILL.md

@@ -37,9 +37,14 @@ setup (or `npx @guilz-dev/belay init` for non-interactive install). Run
 ## When belay blocks an action
 
 1. Read the approval ID in the deny message.
-2. Approve once with `/belay-approve <approval-id>` or `belay approve <approval-id>`.
-3. Retry the original action unchanged (default `approval.flow` is `one_step` for shell — the
-   approval response includes a replay hint when auto-replay is enabled).
+2. In the editor, approve once with `/belay-approve <approval-id>`.
+3. With default `approval.flow: one_step`, editor approval atomically claims the one-shot grant and
+   replays the exact denied shell action through the configured boundary driver. No follow-up prompt
+   is required. Failed or timed-out replay requires fresh approval. Tool and subagent actions still
+   require retrying the original action unchanged.
+
+An instruction may follow the approval line in the same prompt. Belay runs the approved shell action
+first and continues the remaining prompt only after replay succeeds.
 
 For shell-only CLI replay after approval: `belay approve <approval-id> --replay`.
 

package/skills/belay/belay-approve.md

@@ -1,21 +1,24 @@
 Run after belay denies a high-risk action and returns an approval ID.
 
-```bash
-belay approve <approval-id>
+```text
+/belay-approve <approval-id>
 ```
 
-Then retry the original action unchanged.
+With default `approval.flow: one_step`, the editor hook atomically claims the one-shot grant and
+immediately replays the exact denied shell action through the configured boundary driver. No
+follow-up prompt is required. Failed or timed-out replay requires fresh approval. Tool and subagent
+approvals still require a manual retry of the original action unchanged.
 
-With default `approval.flow: one_step`, shell approvals return a replay hint from editor
-hooks. Tool and subagent approvals still require a manual retry.
+An instruction may follow the approval line in the same prompt. Belay runs the approved shell action
+first and continues the remaining prompt only after replay succeeds.
 
-To run a denied shell command from the CLI after approval (explicit opt-in; do not also retry via hooks):
+For CLI approval, replay remains explicit:
 
 ```bash
 belay approve <approval-id> --replay
 ```
 
-Successful CLI replay consumes the one-shot grant. On failure, the approval stays active for one hook retry.
+CLI replay claims the one-shot grant before execution. Failure or timeout requires fresh approval.
 
 Restore legacy two-step UX in `belay.config.json`: