@guilz-dev/belay 0.9.3 → 0.9.4

package/dist/commands/doctor.js

@@ -1,9 +1,12 @@
-import { existsSync } from 'node:fs';
+import { execFile } from 'node:child_process';
+import { existsSync, realpathSync } from 'node:fs';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
+import { promisify } from 'node:util';
 import { getClaudeManagedHookEntries } from '../adapters/claude/hooks.js';
-import { getCodexManagedHookEntries } from '../adapters/codex/hooks.js';
-import { hasDuplicateCursorShellGates } from '../adapters/cursor/hooks.js';
+import { codexHooksTomlIncludesCommand, getCodexManagedHookEntries, } from '../adapters/codex/hooks.js';
+import { hasCurrentCursorDispatcherGeneration } from '../adapters/cursor/dispatcher-generation.js';
+import { hasLegacyCursorDoubleShellGates, hasManagedCursorHookEntries, } from '../adapters/cursor/hooks.js';
 import { getAdapterLayout } from '../adapters/layouts/index.js';
 import { protectedArtifactRoots } from '../adapters/layouts/protected-paths.js';
 import { resolveScopedPaths } from '../adapters/layouts/scope.js';
@@ -15,7 +18,7 @@ import { detectFenceDrift, summarizeAuditVisibility } from '../core/audit-summar
 import { inspectBoundaryAttestationFile } from '../core/capability/boundary-attestation-sign.js';
 import { boundaryAttestationPath, boundarySessionStatus, } from '../core/capability/boundary-session.js';
 import { configuredControlPlaneDir, defaultControlPlaneDir, hasForbiddenShellOverrideLists, stripForbiddenShellOverrideLists, } from '../core/config.js';
-import { verifyIntegrityManifest } from '../core/integrity.js';
+import { runtimeIntegrityFiles, verifyIntegrityManifest } from '../core/integrity.js';
 import { diagnoseJudge, stopJudgeSessionBrokers } from '../core/judge-doctor.js';
 import { resolveJudgeTransport } from '../core/judge-runtime-detection.js';
 import { listRecoveryCheckpoints } from '../core/recovery/checkpoint.js';
@@ -33,6 +36,7 @@ import { PACKAGE_VERSION } from '../version.js';
 import { loadAuditRecords } from './audit.js';
 import { collectHealthSnapshot } from './health-snapshot.js';
 import { metricsProject } from './metrics.js';
+const execFileAsync = promisify(execFile);
 function resolveDoctorAdapter(options, configAdapter) {
     if (options.adapter) {
         return options.adapter;
@@ -52,6 +56,110 @@ function hasCursorGlobalWorkspaceResolver(runtimeSource) {
         runtimeSource.includes('working_directory') &&
         runtimeSource.includes('tool_input'));
 }
+const CURSOR_HOOK_SHIMS = [
+    'belay-before-submit.mjs',
+    'belay-shell-gate.mjs',
+    'belay-tool-gate.mjs',
+    'belay-audit.mjs',
+];
+function runnerFileName(adapterName, platform) {
+    if (platform !== 'win32') {
+        return 'belay-runner';
+    }
+    return adapterName === 'cursor' ? 'belay-runner.ps1' : 'belay-runner.cmd';
+}
+async function cursorOriginIssues(hooksDir, installScope, repoRoot) {
+    const canonicalRepoRoot = realpathSync(repoRoot);
+    const issues = [];
+    for (const fileName of CURSOR_HOOK_SHIMS) {
+        const shimPath = path.join(hooksDir, fileName);
+        if (!existsSync(shimPath)) {
+            continue;
+        }
+        let source;
+        try {
+            source = await readFile(shimPath, 'utf8');
+        }
+        catch (error) {
+            const detail = error instanceof Error ? error.message : String(error);
+            issues.push(`Unable to inspect Cursor hook shim for intended ${installScope} owner: ${shimPath}: ${detail}. Run belay upgrade --scope ${installScope}.`);
+            continue;
+        }
+        if (!source.includes("from '../belay/runtime/dispatcher.mjs'")) {
+            issues.push(`Cursor router generation mismatch for intended ${installScope} owner: ${shimPath}. Run belay upgrade --scope ${installScope}.`);
+            continue;
+        }
+        const originMatch = source.match(/origin:\s*(\{[^\n]+\})/);
+        let originMatches = false;
+        if (originMatch?.[1]) {
+            try {
+                const origin = JSON.parse(originMatch[1]);
+                originMatches =
+                    installScope === 'global'
+                        ? origin.scope === 'global'
+                        : origin.scope === 'project' &&
+                            typeof origin.repoRoot === 'string' &&
+                            realpathSync(origin.repoRoot) === canonicalRepoRoot;
+            }
+            catch {
+                originMatches = false;
+            }
+        }
+        if (!originMatches) {
+            issues.push(`Cursor hook origin mismatch for intended ${installScope} owner: ${shimPath}. Run belay upgrade --scope ${installScope}.`);
+        }
+    }
+    return issues;
+}
+async function listLinkedWorktreePaths(repoRoot) {
+    try {
+        const { stdout } = await execFileAsync('git', ['worktree', 'list', '--porcelain'], {
+            cwd: repoRoot,
+            encoding: 'utf8',
+        });
+        return stdout
+            .split(/\r?\n/)
+            .filter((line) => line.startsWith('worktree '))
+            .map((line) => line.slice('worktree '.length).trim())
+            .filter((entry) => entry.length > 0);
+    }
+    catch {
+        return [];
+    }
+}
+async function detectUndogfoodedLinkedWorktrees(params) {
+    const repoRootCanonical = realpathSync(params.repoRoot);
+    const worktrees = await listLinkedWorktreePaths(params.repoRoot);
+    const warnings = [];
+    for (const worktreePath of worktrees) {
+        let canonicalPath = worktreePath;
+        try {
+            canonicalPath = realpathSync(worktreePath);
+        }
+        catch {
+            // Keep the original path for warning output when the entry is stale.
+        }
+        if (canonicalPath === repoRootCanonical) {
+            continue;
+        }
+        const configPath = params.layout.configPath(worktreePath);
+        if (!existsSync(configPath)) {
+            warnings.push(`Dogfood is active here but ${path.basename(worktreePath)} has no belay.config.json (defaults to enforce). Run belay dogfood in each worktree you use with Cursor.`);
+            continue;
+        }
+        try {
+            const candidate = await loadLayeredConfig(worktreePath, params.adapterName);
+            const dogfoodEnabled = candidate.config.mode === 'audit' && candidate.config.policy.unknownLocalEffect === 'deny';
+            if (!dogfoodEnabled) {
+                warnings.push(`Dogfood is active here but ${path.basename(worktreePath)} is not in dogfood mode (mode=${candidate.config.mode}, unknownLocalEffect=${candidate.config.policy.unknownLocalEffect}). Run belay dogfood in each worktree you use with Cursor.`);
+            }
+        }
+        catch {
+            warnings.push(`Dogfood is active here but ${path.basename(worktreePath)} has an unreadable belay.config.json. Run belay doctor and belay dogfood in that worktree.`);
+        }
+    }
+    return warnings;
+}
 export async function doctorProject(options = {}) {
     const repoRoot = path.resolve(options.targetDir ?? process.cwd());
     const issues = [];
@@ -145,9 +253,9 @@ export async function doctorProject(options = {}) {
             }
             if (loadedConfig.controlPlane.integrity === 'hash-pinned') {
                 notes.push('Integrity: hash-pinned (verify with belay upgrade after runtime changes).');
-                const integrity = await verifyIntegrityManifest(repoRoot, activeLayout);
+                const integrity = await verifyIntegrityManifest(repoRoot, activeLayout, runtimeIntegrityFiles(activeLayout, scopedPaths));
                 if (!integrity.ok) {
-                    issues.push(`Integrity verification failed: ${integrity.mismatches.slice(0, 3).join(', ')}`);
+                    issues.push(`Integrity verification failed: ${integrity.mismatches.join(', ')}`);
                 }
             }
         }
@@ -163,14 +271,16 @@ export async function doctorProject(options = {}) {
     const repoLocalDir = loadedConfig
         ? repoLocalStateDirFor(repoRoot, loadedConfig)
         : activeLayout.repoLocalStateDir(repoRoot);
-    const requiredPaths = [
-        path.join(hooksDir, 'belay-runner'),
-        path.join(hooksDir, 'belay-runner.cmd'),
+    const routingOwnerPaths = [
+        path.join(hooksDir, runnerFileName(adapterName, process.platform)),
         path.join(hooksDir, 'belay-before-submit.mjs'),
         path.join(hooksDir, 'belay-shell-gate.mjs'),
         path.join(hooksDir, 'belay-tool-gate.mjs'),
         path.join(hooksDir, 'belay-audit.mjs'),
+        ...(adapterName === 'cursor' ? [path.join(scopedPaths.runtimeDir, 'dispatcher.mjs')] : []),
         corePath,
+    ];
+    const operationalPaths = [
         loadedConfig
             ? pendingApprovalsPath(repoRoot, loadedConfig)
             : path.join(repoLocalDir, 'pending-approvals.json'),
@@ -179,9 +289,67 @@ export async function doctorProject(options = {}) {
             : path.join(repoLocalDir, 'approved-approvals.json'),
         path.join(repoRoot, loadedConfig?.audit.logPath ?? activeLayout.defaultAuditLogPath(repoRoot)),
     ];
+    const requiredPaths = [...routingOwnerPaths, ...operationalPaths];
     for (const requiredPath of requiredPaths) {
         if (!existsSync(requiredPath)) {
             issues.push(`Missing generated file: ${requiredPath}`);
+            if (adapterName === 'cursor' && routingOwnerPaths.includes(requiredPath)) {
+                issues.push(`Cursor intended ${installScope} owner is incomplete: missing ${requiredPath}. Run belay upgrade --scope ${installScope}.`);
+            }
+        }
+    }
+    if (adapterName === 'cursor') {
+        issues.push(...(await cursorOriginIssues(hooksDir, installScope, repoRoot)));
+        const dispatcherPath = path.join(scopedPaths.runtimeDir, 'dispatcher.mjs');
+        if (existsSync(dispatcherPath) &&
+            !hasCurrentCursorDispatcherGeneration(await readFile(dispatcherPath, 'utf8'))) {
+            issues.push(`Cursor router generation mismatch for intended ${installScope} owner dispatcher: ${dispatcherPath}. Run belay upgrade --scope ${installScope}.`);
+        }
+        if (installScope === 'project') {
+            const globalPaths = resolveScopedPaths(activeLayout, 'global', repoRoot);
+            if (existsSync(globalPaths.hooksSettingsPath)) {
+                try {
+                    const { loadHooksFile } = await import('../installer.js');
+                    const globalHooks = await loadHooksFile(globalPaths.hooksSettingsPath);
+                    if (hasManagedCursorHookEntries(globalHooks, process.platform, globalPaths.hooksDir, repoRoot)) {
+                        const globalOwnerFiles = [
+                            path.join(globalPaths.hooksDir, runnerFileName('cursor', process.platform)),
+                            path.join(globalPaths.runtimeDir, 'core.mjs'),
+                            path.join(globalPaths.runtimeDir, 'dispatcher.mjs'),
+                            ...CURSOR_HOOK_SHIMS.map((fileName) => path.join(globalPaths.hooksDir, fileName)),
+                        ];
+                        const globalOriginProblems = await cursorOriginIssues(globalPaths.hooksDir, 'global', repoRoot);
+                        issues.push(...globalOriginProblems);
+                        const globalProblems = [
+                            ...globalOwnerFiles.filter((filePath) => !existsSync(filePath)),
+                            ...globalOriginProblems,
+                        ];
+                        const globalDispatcherPath = path.join(globalPaths.runtimeDir, 'dispatcher.mjs');
+                        if (existsSync(globalDispatcherPath)) {
+                            try {
+                                if (!hasCurrentCursorDispatcherGeneration(await readFile(globalDispatcherPath, 'utf8'))) {
+                                    globalProblems.push(globalDispatcherPath);
+                                }
+                            }
+                            catch (error) {
+                                const detail = error instanceof Error ? error.message : String(error);
+                                issues.push(`Unable to inspect shadowed global Cursor dispatcher at ${globalDispatcherPath}: ${detail}.`);
+                                globalProblems.push(globalDispatcherPath);
+                            }
+                        }
+                        if (globalProblems.length > 0) {
+                            issues.push('Global Cursor installation cannot yield to the project owner. Run belay upgrade from this project to refresh the global router.');
+                        }
+                        else {
+                            notes.push('Healthy global Cursor install is shadowed by this project owner and will return neutral for this repository.');
+                        }
+                    }
+                }
+                catch (error) {
+                    const detail = error instanceof Error ? error.message : String(error);
+                    issues.push(`Unable to inspect shadowed global Cursor hooks at ${globalPaths.hooksSettingsPath}: ${detail}.`);
+                }
+            }
         }
     }
     let hooksOk = true;
@@ -196,15 +364,17 @@ export async function doctorProject(options = {}) {
             const hooksFile = await loadHooksFile(hooksPath);
             for (const { event, definition } of managedEntries) {
                 const entries = hooksFile.hooks[event] ?? [];
-                const present = entries.some((entry) => entry.command === definition.command && entry.matcher === definition.matcher);
-                if (!present) {
+                const matchingEntry = entries.find((entry) => entry.command === definition.command && entry.matcher === definition.matcher);
+                if (!matchingEntry || matchingEntry.failClosed !== true) {
                     hooksOk = false;
                     const matcherSuffix = definition.matcher ? ` (matcher: ${definition.matcher})` : '';
-                    issues.push(`Missing managed hook for ${event}: ${definition.command}${matcherSuffix}`);
+                    issues.push(matchingEntry
+                        ? `Managed Cursor hook for ${event} must set failClosed: true: ${definition.command}${matcherSuffix}`
+                        : `Missing managed hook for ${event}: ${definition.command}${matcherSuffix}`);
                 }
             }
-            if (hasDuplicateCursorShellGates(hooksFile, process.platform, hooksDir, repoRoot)) {
-                warnings.push('Duplicate Cursor Shell preToolUse gates detected. Run belay upgrade to dedupe managed hooks.');
+            if (hasLegacyCursorDoubleShellGates(hooksFile, process.platform, hooksDir, repoRoot)) {
+                warnings.push('Legacy Cursor Shell preToolUse gate detected alongside beforeShellExecution. Run belay upgrade to remove the managed Shell matcher.');
             }
         }
         else if (adapterName === 'codex') {
@@ -212,7 +382,7 @@ export async function doctorProject(options = {}) {
             // are present in the rendered TOML block.
             const toml = await readFile(hooksPath, 'utf8');
             for (const { event, definition } of managedEntries) {
-                if (!toml.includes(definition.command)) {
+                if (!codexHooksTomlIncludesCommand(toml, definition.command)) {
                     hooksOk = false;
                     issues.push(`Missing Codex managed hook for ${event}: ${definition.command}`);
                 }
@@ -346,6 +516,12 @@ export async function doctorProject(options = {}) {
         };
         if (dogfood.active) {
             notes.push(`Dogfood active cohort: ${dogfood.gateEvents} gate events, ${dogfood.wouldBlockCount} would-block (${(dogfood.wouldBlockRate * 100).toFixed(1)}%); ${dogfood.excludedGateEvents} historical/mismatched event(s) excluded.`);
+            notes.push(`Host denied after Belay allow (cohort): ${auditVisibility.hostDeniedAfterAllowCount}.`);
+            warnings.push(...(await detectUndogfoodedLinkedWorktrees({
+                repoRoot,
+                adapterName,
+                layout: activeLayout,
+            })));
             if (dogfood.readyForEnforce) {
                 notes.push('Dogfood metrics suggest enforce mode is ready (belay dogfood --enforce).');
             }

package/dist/commands/health-snapshot.js

@@ -51,16 +51,21 @@ async function managedHooksPresent(adapter, hooksPath, hooksDir, repoRoot) {
 /** Cursor modes confirmed not to apply host-level denial after Belay allows. */
 const CURSOR_APPROVAL_MODES_WITHOUT_HOST_DENIAL = new Set(['unrestricted']);
 export function cursorCliConfigPaths(homeDir, env) {
+    const candidates = [];
+    const addCandidate = (candidate) => {
+        if (!candidates.includes(candidate)) {
+            candidates.push(candidate);
+        }
+    };
     const cursorConfigDir = env.CURSOR_CONFIG_DIR?.trim();
     if (cursorConfigDir) {
-        return [path.join(cursorConfigDir, 'cli-config.json')];
+        addCandidate(path.join(cursorConfigDir, 'cli-config.json'));
     }
-    const candidates = [];
     const xdgConfigHome = env.XDG_CONFIG_HOME?.trim();
     if (xdgConfigHome) {
-        candidates.push(path.join(xdgConfigHome, 'cursor', 'cli-config.json'));
+        addCandidate(path.join(xdgConfigHome, 'cursor', 'cli-config.json'));
     }
-    candidates.push(path.join(homeDir, '.cursor', 'cli-config.json'));
+    addCandidate(path.join(homeDir, '.cursor', 'cli-config.json'));
     return candidates;
 }
 export function cursorApprovalModeRequiresHostDenialWarning(approvalMode) {

package/dist/commands/recovery-checkpoints.d.ts

@@ -86,7 +86,7 @@ export declare function recoveryCheckpointCommand(options: {
     state: import("../core/recovery/types.js").RecoveryCheckpointStateV1;
     manifestHash: string;
     receipt: import("../core/index.js").RecoveryReceiptV1 | undefined;
-    repoRoot?: undefined;
+    readonly repoRoot?: undefined;
     backend?: undefined;
     availableBackends?: undefined;
     backendCounts?: undefined;
@@ -118,7 +118,7 @@ export declare function recoveryCheckpointCommand(options: {
     paths: string[];
     auditRecorded: boolean;
     message: string;
-    repoRoot?: undefined;
+    readonly repoRoot?: undefined;
     backend?: undefined;
     availableBackends?: undefined;
     backendCounts?: undefined;
@@ -146,7 +146,7 @@ export declare function recoveryCheckpointCommand(options: {
     subcommand: string;
     verdict: string;
     checkpointId: string;
-    repoRoot?: undefined;
+    readonly repoRoot?: undefined;
     backend?: undefined;
     availableBackends?: undefined;
     backendCounts?: undefined;

package/dist/config-io.js

@@ -209,8 +209,17 @@ export async function loadConfigFile(repoRoot, adapter = detectAdapterName(repoR
 }
 export async function writeConfigFile(repoRoot, config, adapter = resolveAdapterName(config)) {
     const configPath = configPathFor(repoRoot, adapter);
-    await mkdir(path.dirname(configPath), { recursive: true });
-    await writeFile(configPath, `${JSON.stringify(stripForbiddenShellOverrideLists(config), null, 2)}\n`, 'utf8');
+    const directory = path.dirname(configPath);
+    const temporaryPath = path.join(directory, `.${path.basename(configPath)}.${process.pid}.${randomUUID()}.tmp`);
+    const content = `${JSON.stringify(stripForbiddenShellOverrideLists(config), null, 2)}\n`;
+    await mkdir(directory, { recursive: true });
+    try {
+        await writeFile(temporaryPath, content, { encoding: 'utf8', flag: 'wx' });
+        await rename(temporaryPath, configPath);
+    }
+    finally {
+        await unlink(temporaryPath).catch(() => undefined);
+    }
 }
 export async function mergeAndWriteConfig(repoRoot, adapter = 'cursor') {
     const layout = getAdapterLayout(adapter);

package/dist/core/audit-legacy-archive.js

@@ -1,43 +1,61 @@
-import { existsSync } from 'node:fs';
-import { open, rename } from 'node:fs/promises';
+import { createReadStream, existsSync } from 'node:fs';
+import { rename } from 'node:fs/promises';
 import path from 'node:path';
+import { createInterface } from 'node:readline';
 const LEGACY_PLACEHOLDER_PATTERNS = [
     /"(?:timestamp|ts)"\s*:\s*"<timestamp>"/,
     /"(?:fingerprint|commandFingerprint|effectIRHash|payloadHash|configFingerprint|runtimeArtifactHash|decisionConfigFingerprint|receiptHash)"\s*:\s*"<high-entropy>"/,
     /"approvalId"\s*:\s*"<approval-id>"/,
 ];
-const AUDIT_SCAN_CHUNK_BYTES = 64 * 1024;
-const AUDIT_SCAN_OVERLAP_CHARS = 256;
+const LEGACY_HIGH_ENTROPY_FIELDS = [
+    'fingerprint',
+    'commandFingerprint',
+    'effectIRHash',
+    'payloadHash',
+    'configFingerprint',
+    'runtimeArtifactHash',
+    'decisionConfigFingerprint',
+    'receiptHash',
+];
 export function auditLogHasLegacyScrubPlaceholders(sample) {
-    return LEGACY_PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(sample));
+    for (const line of sample.split(/\r?\n/)) {
+        const trimmed = line.trim();
+        if (!trimmed) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                if (auditRecordHasLegacyCorrelationPlaceholders(parsed)) {
+                    return true;
+                }
+                continue;
+            }
+        }
+        catch {
+            // Malformed legacy lines still need archival before a new runtime appends to the log.
+        }
+        if (LEGACY_PLACEHOLDER_PATTERNS.some((pattern) => pattern.test(trimmed))) {
+            return true;
+        }
+    }
+    return false;
 }
 export function auditRecordHasLegacyCorrelationPlaceholders(record) {
     return (record.timestamp === '<timestamp>' ||
-        record.fingerprint === '<high-entropy>' ||
+        record.ts === '<timestamp>' ||
+        LEGACY_HIGH_ENTROPY_FIELDS.some((field) => record[field] === '<high-entropy>') ||
         record.approvalId === '<approval-id>');
 }
 async function auditFileHasLegacyScrubPlaceholders(auditPath) {
-    const handle = await open(auditPath, 'r');
-    const buffer = Buffer.allocUnsafe(AUDIT_SCAN_CHUNK_BYTES);
-    let carry = '';
-    let position = 0;
-    try {
-        while (true) {
-            const { bytesRead } = await handle.read(buffer, 0, buffer.length, position);
-            if (bytesRead === 0) {
-                return false;
-            }
-            const sample = carry + buffer.toString('utf8', 0, bytesRead);
-            if (auditLogHasLegacyScrubPlaceholders(sample)) {
-                return true;
-            }
-            carry = sample.slice(-AUDIT_SCAN_OVERLAP_CHARS);
-            position += bytesRead;
+    const input = createReadStream(auditPath, { encoding: 'utf8' });
+    const lines = createInterface({ input, crlfDelay: Number.POSITIVE_INFINITY });
+    for await (const line of lines) {
+        if (auditLogHasLegacyScrubPlaceholders(line)) {
+            return true;
         }
     }
-    finally {
-        await handle.close();
-    }
+    return false;
 }
 export async function archiveLegacyAuditLogIfNeeded(repoRoot, config) {
     const auditPath = path.isAbsolute(config.audit.logPath)

package/dist/core/classify-tool.js

@@ -5,6 +5,7 @@ import { evaluateFileMutationPolicy, policyDecisionRequiresAsk, } from './capabi
 import { canonicalStringify, toolFingerprint } from './fingerprint.js';
 import { matchesSensitivePath } from './glob.js';
 import { pathWithinRoot, resolveWorkspaceRootMatch } from './path-utils.js';
+import { fingerprintToolInputSource } from './replay-scrub.js';
 import { scrubValue } from './scrub.js';
 import { classifyShell, resolveClassifierTrustedCwd } from './verdict/adapter.js';
 import { isGitPath } from './verdict/containment.js';
@@ -37,6 +38,13 @@ function policyAuth(options) {
 function scrubPayload(value, options) {
     return scrubValue(value, options.scrubOptions);
 }
+function fingerprintPayload(payload, options) {
+    const toolInput = fingerprintToolInputSource(payload);
+    if (Object.keys(toolInput).length > 0) {
+        return toolInput;
+    }
+    return scrubPayload(payload.tool_input ?? {}, options);
+}
 function extractFilePath(payload) {
     const toolInput = payload.tool_input;
     if (!toolInput || typeof toolInput !== 'object') {
@@ -209,7 +217,7 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
                     verdict: 'deny_pending_approval',
                     reason: 'tool_shell_missing_command',
                     summary: canonicalStringify(scrubPayload(payload.tool_input ?? {}, options)),
-                    fingerprint: toolFingerprint(toolName, scrubPayload(payload.tool_input ?? {}, options), repoRoot),
+                    fingerprint: toolFingerprint(toolName, fingerprintPayload(payload, options), repoRoot),
                     assessment: {
                         reversibility: 'irreversible',
                         external: false,
@@ -223,7 +231,7 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
                 verdict: 'allow_flagged',
                 reason: 'tool_shell_missing_command',
                 summary: canonicalStringify(scrubPayload(payload.tool_input ?? {}, options)),
-                fingerprint: toolFingerprint(toolName, scrubPayload(payload.tool_input ?? {}, options), repoRoot),
+                fingerprint: toolFingerprint(toolName, fingerprintPayload(payload, options), repoRoot),
                 assessment: {
                     reversibility: 'recoverable_with_cost',
                     external: false,
@@ -249,7 +257,7 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
                     verdict: 'deny_pending_approval',
                     reason: 'file_mutation_missing_path',
                     summary: canonicalStringify(scrubPayload(payload.tool_input ?? {}, options)),
-                    fingerprint: toolFingerprint(toolName, scrubPayload(payload.tool_input ?? {}, options), repoRoot),
+                    fingerprint: toolFingerprint(toolName, fingerprintPayload(payload, options), repoRoot),
                     assessment: {
                         reversibility: 'irreversible',
                         external: false,
@@ -263,7 +271,7 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
                 verdict: 'allow_flagged',
                 reason: 'file_mutation_missing_path',
                 summary: canonicalStringify(scrubPayload(payload.tool_input ?? {}, options)),
-                fingerprint: toolFingerprint(toolName, scrubPayload(payload.tool_input ?? {}, options), repoRoot),
+                fingerprint: toolFingerprint(toolName, fingerprintPayload(payload, options), repoRoot),
                 assessment: {
                     reversibility: 'recoverable_with_cost',
                     external: false,
@@ -409,7 +417,7 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
                     verdict: 'deny_pending_approval',
                     reason: 'apply_patch_missing_path',
                     summary: canonicalStringify(scrubPayload(payload.tool_input ?? {}, options)),
-                    fingerprint: toolFingerprint(toolName, scrubPayload(payload.tool_input ?? {}, options), repoRoot),
+                    fingerprint: toolFingerprint(toolName, fingerprintPayload(payload, options), repoRoot),
                     assessment: {
                         reversibility: 'irreversible',
                         external: false,
@@ -423,7 +431,7 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
                 verdict: 'allow_flagged',
                 reason: 'apply_patch_missing_path',
                 summary: canonicalStringify(scrubPayload(payload.tool_input ?? {}, options)),
-                fingerprint: toolFingerprint(toolName, scrubPayload(payload.tool_input ?? {}, options), repoRoot),
+                fingerprint: toolFingerprint(toolName, fingerprintPayload(payload, options), repoRoot),
                 assessment: {
                     reversibility: 'recoverable_with_cost',
                     external: false,
@@ -448,7 +456,7 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
             verdict: 'allow_flagged',
             reason: sawDelete ? 'file_delete' : 'file_mutation',
             summary: targets.map((target) => target.path).join(', '),
-            fingerprint: toolFingerprint(toolName, scrubPayload(payload.tool_input ?? {}, options), repoRoot),
+            fingerprint: toolFingerprint(toolName, fingerprintPayload(payload, options), repoRoot),
             assessment: {
                 reversibility: 'recoverable_with_cost',
                 external: false,
@@ -462,7 +470,7 @@ export async function classifyToolUse(payload, repoRoot, cwd, config, options =
         verdict: 'allow',
         reason: 'unclassified_tool',
         summary: canonicalStringify(scrubPayload(payload.tool_input ?? {}, options)),
-        fingerprint: toolFingerprint(toolName, scrubPayload(payload.tool_input ?? {}, options), repoRoot),
+        fingerprint: toolFingerprint(toolName, fingerprintPayload(payload, options), repoRoot),
         assessment: {
             reversibility: 'reversible',
             external: false,

package/dist/core/effect-ir/argv-delegate.d.ts

@@ -0,0 +1,9 @@
+export interface ArgvDelegatePeelResult {
+    launcher: string;
+    innerTokens: string[];
+    opaque: boolean;
+    reason: string;
+    signals: string[];
+}
+export declare function innerRecipeFromArgvDelegate(peel: ArgvDelegatePeelResult): string | null;
+export declare function peelArgvDelegateArgv(tokens: string[]): ArgvDelegatePeelResult | null;

package/dist/core/effect-ir/argv-delegate.js

@@ -0,0 +1,42 @@
+export function innerRecipeFromArgvDelegate(peel) {
+    if (peel.opaque || peel.innerTokens.length === 0) {
+        return null;
+    }
+    return peel.innerTokens.join(' ');
+}
+export function peelArgvDelegateArgv(tokens) {
+    const launcher = tokens[0] ?? '';
+    if (!launcher || tokens.length < 2) {
+        return null;
+    }
+    const signals = ['process.argv_delegate'];
+    let index = 1;
+    while (index < tokens.length) {
+        const token = tokens[index] ?? '';
+        if (token === '--') {
+            index += 1;
+            break;
+        }
+        if (token.startsWith('-')) {
+            return {
+                launcher,
+                innerTokens: [],
+                opaque: true,
+                reason: 'argv_delegate_wrapper_options',
+                signals: [...signals, 'argv_delegate_wrapper_options'],
+            };
+        }
+        break;
+    }
+    const innerTokens = tokens.slice(index);
+    if (innerTokens.length === 0) {
+        return null;
+    }
+    return {
+        launcher,
+        innerTokens,
+        opaque: false,
+        reason: 'argv_delegate_peel',
+        signals,
+    };
+}

package/dist/core/effect-ir/shell-lower/argv-delegate-gate.d.ts

@@ -0,0 +1,3 @@
+import type { ShellEffectRequirement } from '../shell-build.js';
+export declare function shouldApplyArgvDelegate(head: string, innerTokens: string[], depth: number): boolean;
+export declare function isGrammarUnknownOnly(requirements: ShellEffectRequirement[], head: string): boolean;

package/dist/core/effect-ir/shell-lower/argv-delegate-gate.js

@@ -0,0 +1,40 @@
+import path from 'node:path';
+import { isEgressToolHead } from '../../verdict/egress-classify.js';
+const ARGV_DELEGATE_INNER_BLOCKLIST = new Set([
+    'sudo',
+    'env',
+    'command',
+    'builtin',
+    'exec',
+    'time',
+    'nice',
+    'nohup',
+    'stdbuf',
+    'setsid',
+    '(',
+]);
+export function shouldApplyArgvDelegate(head, innerTokens, depth) {
+    if (depth > 0 || isEgressToolHead(head) || head === 'bundle') {
+        return false;
+    }
+    if (ARGV_DELEGATE_INNER_BLOCKLIST.has(head)) {
+        return false;
+    }
+    const innerHead = path.basename(innerTokens[0] ?? '');
+    if (ARGV_DELEGATE_INNER_BLOCKLIST.has(innerHead)) {
+        return false;
+    }
+    return innerTokens.length >= 2;
+}
+export function isGrammarUnknownOnly(requirements, head) {
+    if (requirements.length !== 2) {
+        return false;
+    }
+    const [spawn, indeterminate] = requirements;
+    return (spawn.action === 'process.exec' &&
+        spawn.resource.kind === 'executable' &&
+        spawn.resource.command === head &&
+        spawn.resource.operation === 'spawn' &&
+        indeterminate.action === 'indeterminate' &&
+        indeterminate.evidence.signals.includes('process.grammar_unknown'));
+}

package/dist/core/effect-ir/shell-lower/augment.d.ts

@@ -0,0 +1,4 @@
+import type { ShellEffectRequirement } from '../shell-build.js';
+import type { LowerContext } from './context.js';
+export declare function addRedirectEffects(requirements: ShellEffectRequirement[], tokens: string[], env: Readonly<Record<string, string | undefined>>, context: LowerContext, segment: string): void;
+export declare function effectChangingEnvironmentSignals(head: string, env: Readonly<Record<string, string | undefined>>, changedNames: ReadonlySet<string>): string[];