@guilz-dev/belay 0.4.0 → 0.6.0

package/dist/core/judge-doctor.js

@@ -2,20 +2,30 @@ import { repoLocalStateDirFor } from '../config-io.js';
 import { normalizeJudgeProvider, scrubOptionsFromConfig } from './config.js';
 import { resolveJudgeCredential } from './judge-api-key.js';
 import { hasValidCloudConsent } from './judge-config.js';
+import { formatJudgeRecoveryHint, inferProviderIdFromFallbackReason, } from './judge-fallback-hints.js';
 import { discoverJudgeModels, modelPresenceFromDiscovery, } from './judge-model-discovery.js';
 import { detectJudgeRuntimeCapabilities, resolveJudgeTransport } from './judge-runtime-detection.js';
 import { createOllamaJudge, createOpenAiCompatibleJudge } from './verdict/judge.js';
 import { stopJudgeBrokerDaemon } from './verdict/judge-broker-service.js';
 import { getJudgeProviderCapabilities, getJudgeProviderSpec, isRemovedProviderId, normalizeLegacyProviderId, } from './verdict/judge-catalog.js';
 import { createJudgeFromConfig, resolveJudgeModel } from './verdict/judge-factory.js';
+import { resolveJudgeSmokeProbeTimeoutMs } from './verdict/judge-runtime-config.js';
 import { listRepoJudgeSessionBrokers, stopRepoJudgeSessionBroker, } from './verdict/judge-session-broker.js';
 import { clearJudgeSessionKillSwitch } from './verdict/judge-session-kill-switch.js';
+function judgeShadowAdvisory(warnings, message) {
+    warnings.push(`[judge shadow advisory] ${message}`);
+}
 export async function diagnoseJudge(config, repoRoot = process.cwd(), options = {}) {
     const shouldRunLiveProbe = options.liveProbe === true && !process.env.VITEST && !process.env.VITEST_WORKER_ID;
     const issues = [];
     const warnings = [];
     const notes = [];
     const judge = config.judge;
+    const gateMode = judge.mode ?? 'shadow';
+    notes.push(`Judge gate mode: ${gateMode} (sync Tier1 removed from hook gate; judge is shadow/async only)`);
+    if (gateMode === 'off') {
+        notes.push('Judge shadow is disabled (judge.mode=off).');
+    }
     const provider = normalizeJudgeProvider(judge.provider);
     const rawProviderId = judge.providerId ? String(judge.providerId) : undefined;
     if (rawProviderId && isRemovedProviderId(rawProviderId)) {
@@ -36,15 +46,19 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
     const capabilities = getJudgeProviderCapabilities(providerId);
     const transport = resolveJudgeTransport(judge);
     const runtime = detectJudgeRuntimeCapabilities(providerId);
+    const cursorAcpEnabled = transport === 'cursor-cli' &&
+        providerId === 'cursor' &&
+        config.judge.runtime?.session.enabled === true;
+    const effectiveTransport = cursorAcpEnabled ? 'cursor-acp' : transport;
     notes.push(`Judge providerId: ${providerId}`);
     notes.push(`Judge driver: ${provider}`);
     notes.push(`Judge model requested: ${judge.model}`);
-    notes.push(`Judge transport: ${transport}`);
+    notes.push(`Judge transport: ${effectiveTransport}`);
     if (config.policy.modelAssist.enabled) {
         warnings.push('policy.modelAssist is enabled but is not wired to v2 Tier1. Use top-level judge instead.');
     }
     if (capabilities?.requiresConsent && !hasValidCloudConsent(judge) && transport === 'http') {
-        issues.push('Cloud judge consent is not recorded. Tier1 cloud judge will fail closed until consent is granted.');
+        judgeShadowAdvisory(warnings, 'Cloud judge consent is not recorded. Shadow cloud judge will fail until consent is granted.');
     }
     else if (judge.cloudConsent?.accepted) {
         notes.push(`Cloud consent: accepted ${judge.cloudConsent.at} by ${judge.cloudConsent.by}`);
@@ -74,12 +88,12 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
     if (providerId === 'ollama') {
         notes.push(`Ollama endpoint: ${endpoint}`);
         if (discovery.modelIds.length === 0) {
-            issues.push(`Ollama endpoint unreachable or returned no models. Tier1 will fail closed.`);
+            judgeShadowAdvisory(warnings, 'Ollama endpoint unreachable or returned no models. Shadow judge will not run.');
         }
         else {
             const hasModel = modelCheck.status === 'found';
             if (!hasModel) {
-                issues.push(`Ollama model "${judge.model}" is not present. Pull it before enforce mode.`);
+                judgeShadowAdvisory(warnings, `Ollama model "${judge.model}" is not present. Pull it before enabling shadow comparisons.`);
             }
             else {
                 notes.push(`Ollama model "${judge.model}" is available.`);
@@ -103,7 +117,7 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
             context: { cwd: process.cwd(), repoRoot: process.cwd() },
         });
         if (warmResult.reason === 'ollama_unavailable' || warmResult.reason === 'ollama_parse_error') {
-            issues.push(`Ollama warm call failed: ${warmResult.reason}`);
+            judgeShadowAdvisory(warnings, `Ollama warm call failed: ${warmResult.reason}`);
         }
         else {
             notes.push('Ollama warm call succeeded.');
@@ -111,24 +125,29 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
         return { issues, warnings, notes, modelCheck };
     }
     if (transport === 'unavailable') {
-        issues.push('No judge transport is available (configure endpoint or install native CLI). Tier1 will fail closed to ask.');
+        judgeShadowAdvisory(warnings, 'No judge transport is available (configure endpoint or install native CLI). Shadow judge will not run.');
         return { issues, warnings, notes, modelCheck };
     }
     if (transport.endsWith('-cli')) {
         if (!runtime.cliTransport) {
-            issues.push(`Native CLI transport (${transport}) is not available. Tier1 judge will fail closed to ask.`);
+            judgeShadowAdvisory(warnings, `Native CLI transport (${transport}) is not available. Shadow judge will not run.`);
         }
         else if (!keyInfo.key && keyInfo.sourceKind !== 'host-session') {
-            issues.push('Judge API key is not set for the configured credential mode. Tier1 cloud judge will fail closed to ask.');
+            judgeShadowAdvisory(warnings, 'Judge API key is not set for the configured credential mode. Shadow cloud judge will not run.');
         }
         else {
-            notes.push(`Native CLI transport available: ${transport}`);
+            notes.push(cursorAcpEnabled
+                ? 'Cursor ACP transport available.'
+                : `Native CLI transport available: ${transport}`);
+            if (cursorAcpEnabled) {
+                notes.push(`Cursor ACP session transport enabled (max ${config.judge.runtime?.session.maxTurns ?? 'unknown'} turns).`);
+            }
             if (shouldRunLiveProbe) {
                 const smokeConfig = {
                     ...config,
                     judge: {
                         ...judge,
-                        timeoutMs: Math.min(judge.timeoutMs, 5000),
+                        timeoutMs: resolveJudgeSmokeProbeTimeoutMs(judge.timeoutMs),
                     },
                 };
                 const smokeJudge = createJudgeFromConfig(smokeConfig, { repoRoot });
@@ -140,10 +159,16 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
                     smokeJudge.lastTrace?.fallbackReason ??
                     smokeResult.reason;
                 if (smokeJudge.lastTrace?.provider === 'fallback') {
-                    issues.push(`Native CLI transport smoke probe failed (${smokeFallback}). Tier1 will fail closed to ask.`);
+                    const recoveryHint = formatJudgeRecoveryHint(inferProviderIdFromFallbackReason(smokeFallback, providerId), smokeFallback);
+                    const smokeLabel = cursorAcpEnabled ? 'Cursor ACP' : 'Native CLI transport';
+                    judgeShadowAdvisory(warnings, recoveryHint
+                        ? `${smokeLabel} smoke probe failed (${smokeFallback}). ${recoveryHint}`
+                        : `${smokeLabel} smoke probe failed (${smokeFallback}).`);
                 }
                 else {
-                    notes.push('Native CLI transport smoke probe succeeded.');
+                    notes.push(cursorAcpEnabled
+                        ? 'Cursor ACP smoke probe succeeded.'
+                        : 'Native CLI transport smoke probe succeeded.');
                 }
             }
         }
@@ -153,7 +178,7 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
         notes.push(`HTTP endpoint: ${judge.endpoint}`);
     }
     if (!keyInfo.key) {
-        issues.push('Judge API key is not set for the configured credential mode. Tier1 cloud judge will fail closed to ask.');
+        judgeShadowAdvisory(warnings, 'Judge API key is not set for the configured credential mode. Shadow cloud judge will not run.');
     }
     else {
         notes.push(`Credential source: ${keyInfo.source ?? keyInfo.sourceKind}`);
@@ -188,7 +213,7 @@ export async function diagnoseJudge(config, repoRoot = process.cwd(), options =
         });
         if (dryRun.reason.startsWith('openai_compatible_') ||
             dryRun.reason === 'outbound_scrub_failed') {
-            issues.push(`HTTP judge dry-run failed: ${dryRun.reason}`);
+            judgeShadowAdvisory(warnings, `HTTP judge dry-run failed: ${dryRun.reason}`);
         }
         else {
             notes.push('HTTP judge dry-run succeeded.');

package/dist/core/judge-fallback-hints.d.ts

@@ -0,0 +1,13 @@
+import type { ClassifyResult } from './types.js';
+export declare function extractJudgeFallbackReason(result: Pick<ClassifyResult, 'axes' | 'assessment'>): string | undefined;
+export declare function isJudgeInfrastructureFailure(result: Pick<ClassifyResult, 'axes' | 'assessment' | 'reason'>): boolean;
+export declare function inferProviderIdFromFallbackReason(fallbackReason: string | undefined, fallbackProviderId?: string): string;
+export declare function formatJudgeRecoveryHint(providerId: string, fallbackReason?: string): string | null;
+export declare function formatJudgeInfrastructureDenyMessage(params: {
+    providerId: string;
+    fallbackReason?: string;
+    command?: string;
+}): {
+    user_message: string;
+    agent_message: string;
+};

package/dist/core/judge-fallback-hints.js

@@ -0,0 +1,108 @@
+const INFRASTRUCTURE_FALLBACK_SUFFIXES = [
+    '_cli_nonzero',
+    '_cli_unavailable',
+    '_cli_parse_error',
+    '_cli_spawn_error',
+];
+const INFRASTRUCTURE_FALLBACK_REASONS = new Set([
+    'eval_timeout',
+    'connect_timeout',
+    'parse_timeout',
+    'session_unavailable',
+    'session_disabled',
+    'provider_not_allowlisted',
+    'guard_reset',
+    'kill_switch',
+    'non_json_response',
+    'parse_error',
+    'cli_error',
+    'timeout',
+    'version_mismatch',
+    'shadow_forced_spawn',
+    'unsafe_option_rejected',
+    'broker_busy_reset',
+]);
+function isInfrastructureFallbackReason(reason) {
+    if (INFRASTRUCTURE_FALLBACK_REASONS.has(reason)) {
+        return true;
+    }
+    return INFRASTRUCTURE_FALLBACK_SUFFIXES.some((suffix) => reason.endsWith(suffix));
+}
+function infrastructureSignal(signal) {
+    return isInfrastructureFallbackReason(signal);
+}
+export function extractJudgeFallbackReason(result) {
+    if (result.axes?.judgeFallbackReason) {
+        return result.axes.judgeFallbackReason;
+    }
+    return result.assessment.signals.find((signal) => isInfrastructureFallbackReason(signal));
+}
+export function isJudgeInfrastructureFailure(result) {
+    if (result.axes?.judgeProvider === 'fallback') {
+        return true;
+    }
+    const fallbackReason = extractJudgeFallbackReason(result);
+    if (fallbackReason && isInfrastructureFallbackReason(fallbackReason)) {
+        return true;
+    }
+    return result.assessment.signals.some(infrastructureSignal);
+}
+export function inferProviderIdFromFallbackReason(fallbackReason, fallbackProviderId = 'cursor') {
+    if (!fallbackReason) {
+        return fallbackProviderId;
+    }
+    const match = fallbackReason.match(/^(cursor|claude|codex)_/);
+    return match?.[1] ?? fallbackProviderId;
+}
+export function formatJudgeRecoveryHint(providerId, fallbackReason) {
+    if (!fallbackReason) {
+        return null;
+    }
+    if (fallbackReason.endsWith('_cli_nonzero') || fallbackReason.endsWith('_cli_unavailable')) {
+        switch (providerId) {
+            case 'cursor':
+                return 'Judge CLI is not authenticated. Run: agent login';
+            case 'claude':
+                return 'Claude CLI failed. Run: claude auth login';
+            case 'codex':
+                return 'Codex CLI failed. Check codex auth';
+            default:
+                return `Judge CLI transport failed (${fallbackReason}). Check ${providerId} CLI auth`;
+        }
+    }
+    if (fallbackReason.endsWith('_cli_parse_error')) {
+        return `Judge CLI returned an invalid response (${fallbackReason}). Retry after updating the ${providerId} CLI`;
+    }
+    if (fallbackReason.endsWith('_cli_spawn_error')) {
+        return `Judge CLI could not be started (${fallbackReason}). Install or repair the ${providerId} CLI`;
+    }
+    switch (fallbackReason) {
+        case 'eval_timeout':
+        case 'connect_timeout':
+        case 'parse_timeout':
+        case 'timeout':
+            return 'Judge timed out. Check network or increase judge.timeoutMs';
+        case 'session_unavailable':
+        case 'session_disabled':
+            return 'Judge session transport is unavailable. Run: belay doctor';
+        case 'kill_switch':
+            return 'Judge session kill switch is active. Run: belay judge status';
+        default:
+            if (isInfrastructureFallbackReason(fallbackReason)) {
+                return `Judge transport failed (${fallbackReason}). Run: belay doctor`;
+            }
+            return null;
+    }
+}
+export function formatJudgeInfrastructureDenyMessage(params) {
+    const fallbackReason = params.fallbackReason ?? 'judge_transport_unavailable';
+    const recoveryHint = formatJudgeRecoveryHint(params.providerId, fallbackReason) ??
+        'Judge transport is unavailable. Run: belay doctor';
+    const commandHint = params.command
+        ? ` For details: belay explain --command "${params.command}"`
+        : ' For details: belay explain';
+    return {
+        user_message: `Belay could not reach the Tier1 judge (${fallbackReason}). ${recoveryHint}. Then retry.${commandHint}`,
+        agent_message: `Belay denied this action because the Tier1 judge transport failed (${fallbackReason}). Repair judge infrastructure, then retry the exact same action.`,
+    };
+}

package/dist/core/path-utils.d.ts

@@ -5,6 +5,7 @@
  * fs-scope allowlist matching).
  */
 export declare function canonicalPath(targetPath: string): string;
+export declare function isPathOutsideRoot(relativePath: string): boolean;
 export declare function pathWithinRoot(root: string, targetPath: string): boolean;
 export declare function relativeWithinRepo(repoRoot: string, targetPath: string): string | null;
 export type WorkspaceRootMatch = {

package/dist/core/path-utils.js

@@ -36,6 +36,9 @@ export function canonicalPath(targetPath) {
     }
     return current;
 }
+export function isPathOutsideRoot(relativePath) {
+    return relativePath === '..' || relativePath.startsWith(`..${path.sep}`);
+}
 export function pathWithinRoot(root, targetPath) {
     const resolvedRoot = canonicalPath(root);
     const resolvedTarget = canonicalPath(targetPath);
@@ -43,7 +46,7 @@ export function pathWithinRoot(root, targetPath) {
     if (relativePath === '') {
         return true;
     }
-    return !relativePath.startsWith('..') && !path.isAbsolute(relativePath);
+    return !isPathOutsideRoot(relativePath) && !path.isAbsolute(relativePath);
 }
 function relativeWithinRoot(root, targetPath, options = {}) {
     const resolvedRoot = options.canonicalizeRoot === false ? path.resolve(root) : canonicalPath(root);
@@ -52,7 +55,7 @@ function relativeWithinRoot(root, targetPath, options = {}) {
     if (relativePath === '') {
         return '.';
     }
-    if (relativePath.startsWith('..') || path.isAbsolute(relativePath)) {
+    if (isPathOutsideRoot(relativePath) || path.isAbsolute(relativePath)) {
         return null;
     }
     return relativePath;

package/dist/core/recovery/capability.d.ts

@@ -0,0 +1,3 @@
+import type { CapabilityRequestV1 } from '../capability/request.js';
+/** Actions that cannot be closed by local git-worktree / file checkpoint recovery. */
+export declare function capabilityRequestsBlockRecovery(requests: CapabilityRequestV1[] | undefined): boolean;

package/dist/core/recovery/capability.js

@@ -0,0 +1,22 @@
+const NON_RECOVERABLE_ACTIONS = new Set([
+    'network.connect',
+    'git.ref.write',
+    'control_plane.write',
+    'secret.read',
+    'indeterminate',
+]);
+/** Actions that cannot be closed by local git-worktree / file checkpoint recovery. */
+export function capabilityRequestsBlockRecovery(requests) {
+    if (!requests?.length) {
+        return false;
+    }
+    for (const request of requests) {
+        if (NON_RECOVERABLE_ACTIONS.has(request.action)) {
+            return true;
+        }
+        if (request.evidence.level === 'indeterminate') {
+            return true;
+        }
+    }
+    return false;
+}

package/dist/core/recovery/fail-closed.d.ts

@@ -0,0 +1,6 @@
+import type { ClassifyResult } from '../types.js';
+export declare const RECOVERY_SUBSTRATE_UNAVAILABLE = "recovery_substrate_unavailable";
+export declare const RECOVERY_EXECUTION_FAILED = "recovery_execution_failed";
+export declare const RECOVERY_DIRTY_WORKTREE = "recovery_dirty_worktree";
+export declare function recoveryFailReasonFromSkip(skipReason: string): string;
+export declare function recoveryFailClosedResult(predicted: ClassifyResult, reason: string, signals?: string[]): ClassifyResult;

package/dist/core/recovery/fail-closed.js

@@ -0,0 +1,25 @@
+export const RECOVERY_SUBSTRATE_UNAVAILABLE = 'recovery_substrate_unavailable';
+export const RECOVERY_EXECUTION_FAILED = 'recovery_execution_failed';
+export const RECOVERY_DIRTY_WORKTREE = 'recovery_dirty_worktree';
+export function recoveryFailReasonFromSkip(skipReason) {
+    if (skipReason === 'transactional_command_failed' || skipReason === 'transactional_timed_out') {
+        return RECOVERY_EXECUTION_FAILED;
+    }
+    if (skipReason === 'dirty_worktree') {
+        return RECOVERY_DIRTY_WORKTREE;
+    }
+    return RECOVERY_SUBSTRATE_UNAVAILABLE;
+}
+export function recoveryFailClosedResult(predicted, reason, signals = []) {
+    return {
+        ...predicted,
+        verdict: 'deny_pending_approval',
+        reason,
+        assessment: {
+            ...predicted.assessment,
+            reversibility: 'irreversible',
+            confidence: 1,
+            signals: [...predicted.assessment.signals, 'recovery_fail_closed', ...signals],
+        },
+    };
+}

package/dist/core/recovery/index.d.ts

@@ -0,0 +1,3 @@
+export { capabilityRequestsBlockRecovery } from './capability.js';
+export { RECOVERY_DIRTY_WORKTREE, RECOVERY_EXECUTION_FAILED, RECOVERY_SUBSTRATE_UNAVAILABLE, recoveryFailClosedResult, recoveryFailReasonFromSkip, } from './fail-closed.js';
+export type { RecoveryBackend, RecoveryProofContext, RecoveryProofV1 } from './types.js';

package/dist/core/recovery/index.js

@@ -0,0 +1,2 @@
+export { capabilityRequestsBlockRecovery } from './capability.js';
+export { RECOVERY_DIRTY_WORKTREE, RECOVERY_EXECUTION_FAILED, RECOVERY_SUBSTRATE_UNAVAILABLE, recoveryFailClosedResult, recoveryFailReasonFromSkip, } from './fail-closed.js';

package/dist/core/recovery/types.d.ts

@@ -0,0 +1,20 @@
+import type { CapabilityRequestV1 } from '../capability/request.js';
+/** Backends that can mint a verifiable RecoveryProof (ADR: proof-only execution). */
+export type RecoveryBackend = 'git_worktree' | 'file_checkpoint';
+export interface RecoveryProofV1 {
+    version: 1;
+    backend: RecoveryBackend;
+    inputFingerprint: string;
+    resourceScope: string;
+    baseStateHash: string;
+    effectClosure: 'repo_local_fs';
+    issuedAt: string;
+    expiresAt: string;
+    probeSignals: string[];
+}
+export interface RecoveryProofContext {
+    repoRoot: string;
+    cwd: string;
+    command: string;
+    requests: CapabilityRequestV1[];
+}

package/dist/core/recovery/types.js

@@ -0,0 +1 @@
+export {};

package/dist/core/standing-allow.js

@@ -18,6 +18,9 @@ const STANDING_ALLOW_BLOCKED_REASONS = new Set([
     'protected_artifact',
     'pipe_to_shell',
     'command_substitution',
+    'outside_repo_mutation',
+    'outside_repo_redirect',
+    'control_plane_mutation',
 ]);
 export function standingAllowFile(config, repoLocalStateDir) {
     return `${belayStateDir(config, repoLocalStateDir)}/standing-allow.json`;

package/dist/core/transactional/diff-evaluator.js

@@ -51,7 +51,10 @@ export function evaluateTransactionalDiff(changes, ctx) {
         categories.add('large_deletion');
     }
     const categoryList = [...categories];
-    const dangerous = categoryList.includes('large_deletion');
+    const dangerous = categoryList.includes('large_deletion') ||
+        categoryList.includes('repo_outside') ||
+        categoryList.includes('sensitive_path') ||
+        categoryList.includes('control_plane');
     const base = {
         categories: categoryList,
         changes,

package/dist/core/transactional/eligibility.js

@@ -1,3 +1,4 @@
+import { capabilityRequestsBlockRecovery } from '../recovery/capability.js';
 const EXCLUDED_REASONS = new Set([
     'unparseable_shell',
     'external_effect',
@@ -26,6 +27,9 @@ export function isTransactionalEligible(config, kind, result) {
     if (EXCLUDED_REASONS.has(result.reason)) {
         return false;
     }
+    if (capabilityRequestsBlockRecovery(result.capabilityRequests)) {
+        return false;
+    }
     const { assessment } = result;
     if (assessment.external) {
         return false;

package/dist/core/transactional/git-worktree.d.ts

@@ -1,7 +1,12 @@
 import type { TransactionalFileChange, TransactionalSnapshot } from './types.js';
+export declare const TRANSACTIONAL_APPLY_TOCTOU = "transactional_apply_toctou";
+export declare function hashRepoFile(filePath: string): Promise<string>;
+export declare function captureRepoFileHashes(repoRoot: string, changes: TransactionalFileChange[]): Promise<Map<string, string | null>>;
 export declare function isGitWorktreeAvailable(repoRoot: string): Promise<boolean>;
-export declare function isDirtyWorktree(repoRoot: string): Promise<boolean>;
-export declare function createGitWorktreeSnapshot(repoRoot: string, stateDir: string): Promise<TransactionalSnapshot>;
+export declare function isDirtyWorktree(repoRoot: string, options?: {
+    ignoreRoots?: string[];
+}): Promise<boolean>;
+export declare function createGitWorktreeSnapshot(repoRoot: string, _stateDir: string): Promise<TransactionalSnapshot>;
 export declare function resolveWorktreeCwd(repoRoot: string, worktreePath: string, cwd: string): string;
 export interface ShellRunResult {
     exitCode: number | null;
@@ -10,4 +15,6 @@ export interface ShellRunResult {
 }
 export declare function runShellCommand(command: string, cwd: string, timeoutMs: number): Promise<ShellRunResult>;
 export declare function collectWorktreeChanges(worktreePath: string): Promise<TransactionalFileChange[]>;
-export declare function applyWorktreeChanges(worktreePath: string, repoRoot: string, changes: TransactionalFileChange[]): Promise<void>;
+export declare function applyWorktreeChanges(worktreePath: string, repoRoot: string, changes: TransactionalFileChange[], options?: {
+    baseHashes?: Map<string, string | null>;
+}): Promise<void>;

package/dist/core/transactional/git-worktree.js

@@ -1,10 +1,11 @@
 import { spawn } from 'node:child_process';
-import { randomUUID } from 'node:crypto';
+import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
-import { copyFile, mkdir, mkdtemp, rm } from 'node:fs/promises';
+import { copyFile, mkdir, mkdtemp, readFile, rm } from 'node:fs/promises';
 import os from 'node:os';
 import path from 'node:path';
-import { canonicalPath } from '../path-utils.js';
+import { canonicalPath, isPathOutsideRoot, pathWithinRoot } from '../path-utils.js';
+export const TRANSACTIONAL_APPLY_TOCTOU = 'transactional_apply_toctou';
 function execGit(repoRoot, args) {
     return new Promise((resolve, reject) => {
         const child = spawn('git', ['-C', repoRoot, ...args], {
@@ -24,6 +25,38 @@ function execGit(repoRoot, args) {
         });
     });
 }
+function porcelainRelativePath(line) {
+    if (line.length < 4) {
+        return null;
+    }
+    const relativePath = line.slice(3).trim();
+    return relativePath || null;
+}
+function isIgnoredDirtyPath(repoRoot, relativePath, ignoreRoots) {
+    if (ignoreRoots.length === 0) {
+        return false;
+    }
+    const absolutePath = canonicalPath(path.join(repoRoot, relativePath));
+    return ignoreRoots.some((root) => pathWithinRoot(root, absolutePath) ||
+        root === absolutePath ||
+        pathWithinRoot(absolutePath, root));
+}
+export async function hashRepoFile(filePath) {
+    const content = await readFile(filePath);
+    return createHash('sha256').update(content).digest('hex');
+}
+export async function captureRepoFileHashes(repoRoot, changes) {
+    const hashes = new Map();
+    for (const change of changes) {
+        const target = path.join(repoRoot, change.relativePath);
+        if (!existsSync(target)) {
+            hashes.set(change.relativePath, null);
+            continue;
+        }
+        hashes.set(change.relativePath, await hashRepoFile(target));
+    }
+    return hashes;
+}
 export async function isGitWorktreeAvailable(repoRoot) {
     try {
         await execGit(repoRoot, ['rev-parse', '--git-dir']);
@@ -33,18 +66,32 @@ export async function isGitWorktreeAvailable(repoRoot) {
         return false;
     }
 }
-export async function isDirtyWorktree(repoRoot) {
+export async function isDirtyWorktree(repoRoot, options) {
     try {
-        const status = await execGit(repoRoot, ['status', '--porcelain', '--untracked-files=no']);
-        return status.trim().length > 0;
+        const status = await execGit(repoRoot, ['status', '--porcelain']);
+        const ignoreRoots = (options?.ignoreRoots ?? []).map((root) => canonicalPath(root));
+        const repoRootCanonical = canonicalPath(repoRoot);
+        for (const line of status.split('\n')) {
+            if (!line.trim()) {
+                continue;
+            }
+            const relativePath = porcelainRelativePath(line);
+            if (!relativePath) {
+                continue;
+            }
+            if (isIgnoredDirtyPath(repoRootCanonical, relativePath, ignoreRoots)) {
+                continue;
+            }
+            return true;
+        }
+        return false;
     }
     catch {
         return true;
     }
 }
-export async function createGitWorktreeSnapshot(repoRoot, stateDir) {
-    const worktreePath = path.join(stateDir, `tx-${randomUUID().replaceAll('-', '')}`);
-    await mkdir(stateDir, { recursive: true });
+export async function createGitWorktreeSnapshot(repoRoot, _stateDir) {
+    const worktreePath = await mkdtemp(path.join(os.tmpdir(), 'belay-tx-'));
     await execGit(repoRoot, ['worktree', 'add', '--detach', worktreePath, 'HEAD']);
     return {
         worktreePath,
@@ -67,7 +114,7 @@ export async function createGitWorktreeSnapshot(repoRoot, stateDir) {
 export function resolveWorktreeCwd(repoRoot, worktreePath, cwd) {
     const resolvedCwd = canonicalPath(cwd);
     const relative = path.relative(canonicalPath(repoRoot), resolvedCwd);
-    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+    if (isPathOutsideRoot(relative) || path.isAbsolute(relative)) {
         return worktreePath;
     }
     if (relative === '') {
@@ -155,7 +202,30 @@ async function rollbackAppliedChanges(actions) {
         }
     }
 }
-export async function applyWorktreeChanges(worktreePath, repoRoot, changes) {
+async function assertRepoFilesUnchanged(repoRoot, changes, baseHashes) {
+    for (const change of changes) {
+        const target = path.join(repoRoot, change.relativePath);
+        const expected = baseHashes.get(change.relativePath);
+        const exists = existsSync(target);
+        if (expected === null) {
+            if (exists) {
+                throw new Error(TRANSACTIONAL_APPLY_TOCTOU);
+            }
+            continue;
+        }
+        if (!exists) {
+            throw new Error(TRANSACTIONAL_APPLY_TOCTOU);
+        }
+        const current = await hashRepoFile(target);
+        if (current !== expected) {
+            throw new Error(TRANSACTIONAL_APPLY_TOCTOU);
+        }
+    }
+}
+export async function applyWorktreeChanges(worktreePath, repoRoot, changes, options) {
+    if (options?.baseHashes) {
+        await assertRepoFilesUnchanged(repoRoot, changes, options.baseHashes);
+    }
     const backupRoot = await mkdtemp(path.join(os.tmpdir(), 'belay-tx-rollback-'));
     const rollbackActions = [];
     try {

package/dist/core/transactional/reasons.d.ts

@@ -1,4 +1,5 @@
 export declare const TRANSACTIONAL_ALREADY_APPLIED = "transactional_already_applied";
 export declare const TRANSACTIONAL_OBSERVED_RISK = "transactional_observed_risk";
 export declare const TRANSACTIONAL_APPLY_FAILED = "transactional_apply_failed";
+export { RECOVERY_DIRTY_WORKTREE, RECOVERY_EXECUTION_FAILED, RECOVERY_SUBSTRATE_UNAVAILABLE, } from '../recovery/fail-closed.js';
 export declare const TRANSACTIONAL_APPROVAL_BYPASS_REASONS: Set<string>;

package/dist/core/transactional/reasons.js

@@ -1,8 +1,12 @@
 export const TRANSACTIONAL_ALREADY_APPLIED = 'transactional_already_applied';
 export const TRANSACTIONAL_OBSERVED_RISK = 'transactional_observed_risk';
 export const TRANSACTIONAL_APPLY_FAILED = 'transactional_apply_failed';
+export { RECOVERY_DIRTY_WORKTREE, RECOVERY_EXECUTION_FAILED, RECOVERY_SUBSTRATE_UNAVAILABLE, } from '../recovery/fail-closed.js';
 export const TRANSACTIONAL_APPROVAL_BYPASS_REASONS = new Set([
     TRANSACTIONAL_OBSERVED_RISK,
     TRANSACTIONAL_ALREADY_APPLIED,
     TRANSACTIONAL_APPLY_FAILED,
+    'recovery_substrate_unavailable',
+    'recovery_execution_failed',
+    'recovery_dirty_worktree',
 ]);