@guilz-dev/belay 0.2.0 → 0.3.0

package/dist/core/config.d.ts

@@ -76,13 +76,32 @@ export interface BelayRedactionConfig {
     maskKeyValueSecrets: boolean;
     maskHighEntropyStrings: boolean;
 }
-export type JudgeProvider = 'ollama' | 'openai-compatible';
+export type JudgeProvider = 'ollama' | 'openai-compatible' | 'anthropic';
+export type JudgeProviderId = 'ollama' | 'codex' | 'claude' | 'cursor';
+/** Read-only legacy ids; preserved on load with warning until `belay config` migrates. */
+export type DeprecatedJudgeProviderId = 'openrouter' | 'custom';
+export type JudgeCredentialMode = 'project' | 'apiKey';
+export type JudgeCredentialRef = `store:judge` | `env:${string}`;
+export interface JudgeCredentialConfig {
+    mode: JudgeCredentialMode;
+    ref?: JudgeCredentialRef;
+}
+export interface JudgeCloudConsent {
+    accepted: boolean;
+    at: string;
+    providerId: JudgeProviderId;
+    endpoint: string;
+    by: string;
+}
 export interface BelayJudgeConfig {
     provider: JudgeProvider;
+    providerId?: JudgeProviderId | DeprecatedJudgeProviderId;
     model: string;
     timeoutMs: number;
     endpoint: string | null;
     keepAlive: string | null;
+    cloudConsent?: JudgeCloudConsent;
+    credential?: JudgeCredentialConfig;
 }
 export declare const DEFAULT_JUDGE_LOCAL_OLLAMA: BelayJudgeConfig;
 export declare const DEFAULT_JUDGE_OPENAI_COMPATIBLE_TEMPLATE: BelayJudgeConfig;
@@ -180,8 +199,9 @@ export declare function isConfigV1(value: unknown): value is BelayConfigV1;
 export declare function isConfigV2(value: unknown): value is BelayConfigV2;
 export declare function isConfigV3(value: unknown): value is BelayConfigV4;
 export declare function isConfigV4(value: unknown): value is BelayConfigV4;
-export declare function normalizeJudgeProvider(provider: string | undefined): 'ollama' | 'openai-compatible';
+export declare function normalizeJudgeProvider(provider: string | undefined): 'ollama' | 'openai-compatible' | 'anthropic';
 export declare function normalizeJudgeConfig(judge: BelayJudgeConfig): BelayJudgeConfig;
+export declare function rejectTeamLayerJudgeSecrets(judge: Partial<BelayJudgeConfig> | undefined, source: 'team' | 'repo'): void;
 export declare function migrateV3ToV4(v3: BelayConfigV4, raw?: RawConfigInput): BelayConfigV4;
 type RawConfigInput = Partial<{
     version: number;

package/dist/core/config.js

@@ -1,6 +1,9 @@
 import path from 'node:path';
+import { warnDeprecatedJudgeModelAuto } from './judge-model-policy.js';
+import { getJudgeProviderSpec, inferProviderIdFromConfig, isRemovedProviderId, normalizeLegacyProviderId, warnRemovedProviderId, } from './verdict/judge-catalog.js';
 export const DEFAULT_JUDGE_LOCAL_OLLAMA = {
     provider: 'ollama',
+    providerId: 'ollama',
     model: 'gemma4:e2b',
     endpoint: 'http://localhost:11434',
     timeoutMs: 25000,
@@ -8,7 +11,8 @@ export const DEFAULT_JUDGE_LOCAL_OLLAMA = {
 };
 export const DEFAULT_JUDGE_OPENAI_COMPATIBLE_TEMPLATE = {
     provider: 'openai-compatible',
-    model: 'auto',
+    providerId: 'codex',
+    model: 'gpt-5.3-codex-high',
     timeoutMs: 8000,
     endpoint: null,
     keepAlive: null,
@@ -209,44 +213,139 @@ export function isConfigV4(value) {
     return typeof value === 'object' && value !== null && value.version === 4;
 }
 export function normalizeJudgeProvider(provider) {
+    if (provider === 'anthropic') {
+        return 'anthropic';
+    }
     if (provider === 'openai-compatible' || provider === 'cursor') {
         return 'openai-compatible';
     }
     return 'ollama';
 }
+function defaultJudgeTemplateForProvider(provider) {
+    if (provider === 'ollama') {
+        return DEFAULT_JUDGE_LOCAL_OLLAMA;
+    }
+    if (provider === 'anthropic') {
+        return {
+            provider: 'anthropic',
+            providerId: 'claude',
+            model: 'claude-sonnet-4-6',
+            timeoutMs: 8000,
+            endpoint: null,
+            keepAlive: null,
+        };
+    }
+    return DEFAULT_JUDGE_OPENAI_COMPATIBLE_TEMPLATE;
+}
 function synthesizeJudgeFromRaw(raw) {
     const judge = raw.judge;
     if (judge?.provider) {
-        const provider = normalizeJudgeProvider(judge.provider);
-        const base = provider === 'openai-compatible'
-            ? DEFAULT_JUDGE_OPENAI_COMPATIBLE_TEMPLATE
-            : DEFAULT_JUDGE_LOCAL_OLLAMA;
+        const rawProvider = String(judge.provider);
+        const provider = normalizeJudgeProvider(rawProvider);
+        const base = defaultJudgeTemplateForProvider(provider);
+        const providerId = judge.providerId && normalizeLegacyProviderId(judge.providerId)
+            ? normalizeLegacyProviderId(judge.providerId)
+            : rawProvider === 'cursor'
+                ? 'cursor'
+                : undefined;
         return normalizeJudgeConfig({
             ...base,
             ...judge,
             provider,
+            ...(providerId ? { providerId } : {}),
         });
     }
     return { ...DEFAULT_JUDGE_LOCAL_OLLAMA };
 }
 export function normalizeJudgeConfig(judge) {
     const provider = normalizeJudgeProvider(judge.provider);
-    const base = provider === 'openai-compatible'
-        ? DEFAULT_JUDGE_OPENAI_COMPATIBLE_TEMPLATE
-        : DEFAULT_JUDGE_LOCAL_OLLAMA;
-    const model = typeof judge.model === 'string' && judge.model.trim() ? judge.model.trim() : base.model;
+    const base = defaultJudgeTemplateForProvider(provider);
+    const rawProviderId = judge.providerId ? String(judge.providerId) : undefined;
+    if (rawProviderId && isRemovedProviderId(rawProviderId)) {
+        warnRemovedProviderId(rawProviderId);
+        let model = typeof judge.model === 'string' && judge.model.trim() ? judge.model.trim() : base.model;
+        if (model === 'auto') {
+            warnDeprecatedJudgeModelAuto();
+            model = base.model;
+        }
+        const timeoutMs = typeof judge.timeoutMs === 'number' && judge.timeoutMs > 0 ? judge.timeoutMs : base.timeoutMs;
+        const endpoint = typeof judge.endpoint === 'string' && judge.endpoint.trim() ? judge.endpoint.trim() : null;
+        return {
+            provider,
+            providerId: rawProviderId,
+            model,
+            timeoutMs,
+            endpoint,
+            keepAlive: provider === 'ollama' && typeof judge.keepAlive === 'string' && judge.keepAlive.trim()
+                ? judge.keepAlive.trim()
+                : provider === 'ollama'
+                    ? DEFAULT_JUDGE_LOCAL_OLLAMA.keepAlive
+                    : null,
+            ...(judge.cloudConsent ? { cloudConsent: judge.cloudConsent } : {}),
+            ...(judge.credential ? { credential: judge.credential } : {}),
+        };
+    }
+    let providerId = rawProviderId && normalizeLegacyProviderId(rawProviderId)
+        ? normalizeLegacyProviderId(rawProviderId)
+        : inferProviderIdFromConfig({ ...judge, provider });
+    const spec = getJudgeProviderSpec(providerId);
+    if (spec && spec.driver !== provider) {
+        providerId = inferProviderIdFromConfig({ ...judge, provider });
+    }
+    const catalogSpec = getJudgeProviderSpec(providerId);
+    let model = typeof judge.model === 'string' && judge.model.trim() ? judge.model.trim() : base.model;
+    if (model === 'auto' && catalogSpec?.defaultModel) {
+        warnDeprecatedJudgeModelAuto();
+        model = catalogSpec.defaultModel;
+    }
+    if (!model && catalogSpec?.defaultModel) {
+        model = catalogSpec.defaultModel;
+    }
     const timeoutMs = typeof judge.timeoutMs === 'number' && judge.timeoutMs > 0 ? judge.timeoutMs : base.timeoutMs;
-    return {
+    let endpoint = typeof judge.endpoint === 'string' && judge.endpoint.trim() ? judge.endpoint.trim() : null;
+    if (!endpoint && catalogSpec?.defaultEndpoint) {
+        endpoint = catalogSpec.defaultEndpoint;
+    }
+    const normalized = {
         provider,
+        providerId,
         model,
         timeoutMs,
-        endpoint: typeof judge.endpoint === 'string' && judge.endpoint.trim() ? judge.endpoint.trim() : null,
+        endpoint,
         keepAlive: provider === 'ollama' && typeof judge.keepAlive === 'string' && judge.keepAlive.trim()
             ? judge.keepAlive.trim()
             : provider === 'ollama'
                 ? DEFAULT_JUDGE_LOCAL_OLLAMA.keepAlive
                 : null,
     };
+    if (judge.cloudConsent?.accepted) {
+        normalized.cloudConsent = {
+            accepted: true,
+            at: judge.cloudConsent.at,
+            providerId: judge.cloudConsent.providerId ?? providerId,
+            endpoint: judge.cloudConsent.endpoint,
+            by: judge.cloudConsent.by,
+        };
+    }
+    if (judge.credential?.mode === 'project' || judge.credential?.mode === 'apiKey') {
+        normalized.credential = {
+            mode: judge.credential.mode,
+            ...(judge.credential.ref ? { ref: judge.credential.ref } : {}),
+        };
+    }
+    return normalized;
+}
+export function rejectTeamLayerJudgeSecrets(judge, source) {
+    if (source !== 'team' || !judge) {
+        return;
+    }
+    if (judge.credential?.mode === 'apiKey') {
+        throw new Error('team config cannot set judge.credential.mode to apiKey.');
+    }
+    const raw = judge;
+    if (raw.credential && 'key' in raw.credential && raw.credential.key) {
+        throw new Error('team config cannot contain inline judge credential keys.');
+    }
 }
 export function migrateV3ToV4(v3, raw) {
     return normalizeConfig({

package/dist/core/credential-store.d.ts

@@ -0,0 +1,11 @@
+export interface JudgeCredentialStoreFile {
+    version: 1;
+    judge?: string;
+}
+export declare function credentialStorePath(stateDir: string): string;
+export declare function writeJudgeCredentialStore(stateDir: string, apiKey: string): Promise<string>;
+export declare function clearJudgeCredentialStore(stateDir: string): Promise<void>;
+export declare function readJudgeCredentialStore(stateDir: string): Promise<string | null>;
+export declare function judgeCredentialStoreExists(stateDir: string): Promise<boolean>;
+export type CredentialRef = `store:judge` | `env:${string}`;
+export declare function parseCredentialRef(ref: string): CredentialRef | null;

package/dist/core/credential-store.js

@@ -0,0 +1,60 @@
+import { chmod, mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+const STORE_FILENAME = 'credentials.json';
+export function credentialStorePath(stateDir) {
+    return path.join(stateDir, STORE_FILENAME);
+}
+export async function writeJudgeCredentialStore(stateDir, apiKey) {
+    await mkdir(stateDir, { recursive: true, mode: 0o700 });
+    const filePath = credentialStorePath(stateDir);
+    const payload = {
+        version: 1,
+        judge: apiKey.trim(),
+    };
+    await writeFile(filePath, `${JSON.stringify(payload, null, 2)}\n`, {
+        encoding: 'utf8',
+        mode: 0o600,
+    });
+    await chmod(filePath, 0o600);
+    return filePath;
+}
+export async function clearJudgeCredentialStore(stateDir) {
+    try {
+        await unlink(credentialStorePath(stateDir));
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT') {
+            throw error;
+        }
+    }
+}
+export async function readJudgeCredentialStore(stateDir) {
+    const filePath = credentialStorePath(stateDir);
+    try {
+        const raw = await readFile(filePath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const key = parsed.judge?.trim();
+        return key || null;
+    }
+    catch {
+        return null;
+    }
+}
+export async function judgeCredentialStoreExists(stateDir) {
+    try {
+        await readFile(credentialStorePath(stateDir), 'utf8');
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseCredentialRef(ref) {
+    if (ref === 'store:judge') {
+        return ref;
+    }
+    if (ref.startsWith('env:') && ref.length > 4) {
+        return ref;
+    }
+    return null;
+}

package/dist/core/gate-engine.js

@@ -1,5 +1,5 @@
 import { allPathsAllowlisted } from './capability/allowlist.js';
-import { collectOutsideRepoPaths } from './capability/paths.js';
+import { collectOutsideRepoPaths, collectOutsideRepoPathsFromToolPayload, } from './capability/paths.js';
 import { classifySubagent } from './classify-subagent.js';
 import { classifyToolUse } from './classify-tool.js';
 import { classifierOptionsFromConfig } from './config.js';
@@ -92,17 +92,63 @@ export function normalizeGatedAction(params) {
         agentAssessment,
     };
 }
-function applyShellPeripheralPolicy(command, action, result, options) {
-    if (options.brokerFsScope &&
-        result.verdict === 'deny_pending_approval' &&
-        (result.reason === 'outside_repo_mutation' ||
-            result.reason === 'outside_repo_redirect' ||
-            result.reason === 'repo_outside_mutation' ||
-            result.axes?.location === 'repo_outside')) {
-        const outsideRepoPaths = collectOutsideRepoPaths(command, action.cwd, action.repoRoot);
-        if (outsideRepoPaths.length > 0 &&
-            options.fsScopeAllowlist &&
-            allPathsAllowlisted(outsideRepoPaths, options.fsScopeAllowlist)) {
+function applySandboxFsScopeBoundary(outsideRepoPaths, result, options, hints = {}) {
+    if (!options.brokerFsScope) {
+        return result;
+    }
+    if (outsideRepoPaths.length === 0) {
+        return result;
+    }
+    if (options.fsScopeAllowlist && allPathsAllowlisted(outsideRepoPaths, options.fsScopeAllowlist)) {
+        return result;
+    }
+    if (result.verdict === 'deny_pending_approval') {
+        return result;
+    }
+    const redirect = hints.redirect === true ||
+        result.reason === 'read_only' ||
+        result.assessment.signals.includes('read_only') ||
+        result.reason === 'outside_repo_redirect';
+    return {
+        ...result,
+        verdict: 'deny_pending_approval',
+        reason: redirect ? 'outside_repo_redirect' : 'outside_repo_mutation',
+        assessment: {
+            ...result.assessment,
+            external: true,
+            reversibility: 'irreversible',
+            signals: [...result.assessment.signals, 'sandbox_boundary_expected'],
+        },
+    };
+}
+function applyFsScopePeripheralPolicy(outsideRepoPaths, result, options) {
+    if (!options.brokerFsScope) {
+        return result;
+    }
+    if (outsideRepoPaths.length === 0) {
+        return result;
+    }
+    if (options.fsScopeAllowlist && allPathsAllowlisted(outsideRepoPaths, options.fsScopeAllowlist)) {
+        if (result.verdict === 'deny_pending_approval' &&
+            (result.reason === 'outside_repo_mutation' ||
+                result.reason === 'outside_repo_redirect' ||
+                result.reason === 'repo_outside_mutation' ||
+                result.axes?.location === 'repo_outside')) {
+            return {
+                ...result,
+                verdict: 'allow_flagged',
+                reason: 'capability_fs_hint',
+                assessment: {
+                    ...result.assessment,
+                    signals: [
+                        ...result.assessment.signals,
+                        'capability_fs_hint',
+                        'sandbox_boundary_expected',
+                    ],
+                },
+            };
+        }
+        if (result.verdict === 'allow' || result.verdict === 'allow_flagged') {
             return {
                 ...result,
                 verdict: 'allow_flagged',
@@ -120,6 +166,36 @@ function applyShellPeripheralPolicy(command, action, result, options) {
     }
     return result;
 }
+function applySandboxOutsideBoundary(command, action, result, options) {
+    const outsideRepoPaths = collectOutsideRepoPaths(command, action.cwd, action.repoRoot);
+    return applySandboxFsScopeBoundary(outsideRepoPaths, result, options, {
+        redirect: command.includes('>'),
+    });
+}
+function applyShellPeripheralPolicy(command, action, result, options) {
+    const outsideRepoPaths = collectOutsideRepoPaths(command, action.cwd, action.repoRoot);
+    return applyFsScopePeripheralPolicy(outsideRepoPaths, result, options);
+}
+function outsideRepoPathsForToolAction(action) {
+    const payload = action.payload ?? {};
+    const paths = new Set(collectOutsideRepoPathsFromToolPayload(payload, action.cwd, action.repoRoot));
+    const command = shellCommandFromPayload(payload);
+    if (command) {
+        for (const resolved of collectOutsideRepoPaths(command, action.cwd, action.repoRoot)) {
+            paths.add(resolved);
+        }
+    }
+    return [...paths];
+}
+function applyToolSandboxPolicies(action, result, options) {
+    const outsideRepoPaths = outsideRepoPathsForToolAction(action);
+    const command = shellCommandFromPayload(action.payload ?? {});
+    let next = applySandboxFsScopeBoundary(outsideRepoPaths, result, options, {
+        redirect: command.includes('>'),
+    });
+    next = applyFsScopePeripheralPolicy(outsideRepoPaths, next, options);
+    return next;
+}
 export async function classifyGatedAction(action, config, extraOptions = {}) {
     const options = { ...classifierOptionsFromConfig(config), ...extraOptions };
     if (action.kind === 'shell') {
@@ -128,6 +204,7 @@ export async function classifyGatedAction(action, config, extraOptions = {}) {
             throw new GateNormalizationError('Shell gated action requires a command.');
         }
         let result = await classifyShell(command, action.cwd, action.repoRoot, config, options);
+        result = applySandboxOutsideBoundary(command, action, result, options);
         result = applyShellPeripheralPolicy(command, action, result, options);
         if (!action.agentAssessment) {
             return result;
@@ -146,7 +223,21 @@ export async function classifyGatedAction(action, config, extraOptions = {}) {
     if (action.kind === 'subagent') {
         return classifySubagent(action.payload ?? {}, action.repoRoot, options);
     }
-    return classifyToolUse(action.payload ?? {}, action.repoRoot, action.cwd, config, options);
+    let result = await classifyToolUse(action.payload ?? {}, action.repoRoot, action.cwd, config, options);
+    result = applyToolSandboxPolicies(action, result, options);
+    if (!action.agentAssessment) {
+        return result;
+    }
+    const merged = mergeAgentAssessment(result.assessment, action.agentAssessment);
+    if (!merged.mismatch) {
+        return { ...result, assessment: merged.assessment };
+    }
+    return {
+        ...result,
+        verdict: 'deny_pending_approval',
+        reason: 'agent_assessment_mismatch',
+        assessment: merged.assessment,
+    };
 }
 export async function classifyGatedActionAsync(action, config, extraOptions = {}) {
     return classifyGatedAction(action, config, extraOptions);

package/dist/core/integrity.d.ts

@@ -1,5 +1,6 @@
 import type { ScopedPaths } from '../adapters/layouts/scope.js';
 import type { AdapterLayout } from '../adapters/layouts/types.js';
+import type { BelayConfigV4 } from './config.js';
 export interface IntegrityManifest {
     version: 1;
     generatedAt: string;
@@ -13,3 +14,4 @@ export declare function verifyIntegrityManifest(repoRoot: string, layout: Adapte
     ok: boolean;
     mismatches: string[];
 }>;
+export declare function refreshIntegrityIfPinned(repoRoot: string, config: BelayConfigV4): Promise<void>;

package/dist/core/integrity.js

@@ -2,6 +2,9 @@ import { createHash } from 'node:crypto';
 import { existsSync } from 'node:fs';
 import { mkdir, readFile, writeFile } from 'node:fs/promises';
 import path from 'node:path';
+import { getAdapterLayout } from '../adapters/layouts/index.js';
+import { resolveScopedPaths } from '../adapters/layouts/scope.js';
+import { resolveAdapterName } from '../config-io.js';
 export async function sha256File(filePath) {
     const content = await readFile(filePath);
     return createHash('sha256').update(content).digest('hex');
@@ -66,3 +69,13 @@ export async function verifyIntegrityManifest(repoRoot, layout) {
     }
     return { ok: mismatches.length === 0, mismatches };
 }
+export async function refreshIntegrityIfPinned(repoRoot, config) {
+    if (config.controlPlane.integrity !== 'hash-pinned') {
+        return;
+    }
+    const adapter = resolveAdapterName(config);
+    const layout = getAdapterLayout(adapter);
+    const installScope = config.installScope === 'global' ? 'global' : 'project';
+    const scoped = resolveScopedPaths(layout, installScope, repoRoot);
+    await writeIntegrityManifest(repoRoot, layout, runtimeIntegrityFiles(layout, scoped));
+}

package/dist/core/judge-api-key.d.ts

@@ -1,4 +1,23 @@
+import type { BelayJudgeConfig } from './config.js';
+import { belayStateDir } from './config.js';
+import { type JudgeProviderSpec } from './verdict/judge-catalog.js';
+export type JudgeCredentialSourceKind = 'env' | 'store' | 'host-session' | 'missing';
+export interface ResolvedJudgeCredential {
+    key: string | null;
+    source: string | null;
+    sourceKind: JudgeCredentialSourceKind;
+    mode: 'project' | 'apiKey';
+}
+/** @deprecated Use resolveJudgeCredential */
 export declare function resolveJudgeApiKey(env?: NodeJS.ProcessEnv): {
     key: string | null;
     source: 'BELAY_JUDGE_API_KEY' | 'OPENAI_API_KEY' | null;
 };
+export declare function resolveJudgeCredential(params: {
+    judge: BelayJudgeConfig;
+    catalogSpec?: JudgeProviderSpec;
+    repoRoot: string;
+    repoLocalStateDir: string;
+    config: Parameters<typeof belayStateDir>[0];
+    env?: NodeJS.ProcessEnv;
+}): Promise<ResolvedJudgeCredential>;

package/dist/core/judge-api-key.js

@@ -1,3 +1,8 @@
+import { belayStateDir } from './config.js';
+import { parseCredentialRef, readJudgeCredentialStore } from './credential-store.js';
+import { detectJudgeRuntimeCapabilities } from './judge-runtime-detection.js';
+import { getJudgeProviderSpec, inferProviderIdFromConfig, normalizeLegacyProviderId, } from './verdict/judge-catalog.js';
+/** @deprecated Use resolveJudgeCredential */
 export function resolveJudgeApiKey(env = process.env) {
     const belay = env.BELAY_JUDGE_API_KEY?.trim();
     if (belay) {
@@ -9,3 +14,72 @@ export function resolveJudgeApiKey(env = process.env) {
     }
     return { key: null, source: null };
 }
+function resolveFromEnvChain(env, catalogSpec) {
+    const belay = env.BELAY_JUDGE_API_KEY?.trim();
+    if (belay) {
+        return { key: belay, source: 'BELAY_JUDGE_API_KEY' };
+    }
+    for (const name of catalogSpec?.apiKeyEnvVars ?? ['OPENAI_API_KEY', 'BELAY_JUDGE_API_KEY']) {
+        const value = env[name]?.trim();
+        if (value) {
+            return { key: value, source: name };
+        }
+    }
+    return { key: null, source: null };
+}
+function sourceKindForProjectMode(fromEnv, judge, catalogSpec) {
+    if (fromEnv.key) {
+        return 'env';
+    }
+    const providerId = judge.providerId && normalizeLegacyProviderId(judge.providerId)
+        ? normalizeLegacyProviderId(judge.providerId)
+        : inferProviderIdFromConfig(judge);
+    const spec = catalogSpec ?? getJudgeProviderSpec(providerId);
+    if (spec?.isCloud && detectJudgeRuntimeCapabilities(providerId).cliTransport) {
+        return 'host-session';
+    }
+    return 'missing';
+}
+function sourceKindForApiKeyMode(key, source) {
+    if (!key) {
+        return 'missing';
+    }
+    if (source?.startsWith('env:')) {
+        return 'env';
+    }
+    return 'store';
+}
+export async function resolveJudgeCredential(params) {
+    const env = params.env ?? process.env;
+    const credential = params.judge.credential ?? { mode: 'project' };
+    if (credential.mode === 'apiKey') {
+        const ref = credential.ref ? parseCredentialRef(credential.ref) : 'store:judge';
+        if (ref === 'store:judge') {
+            const stateDir = belayStateDir(params.config, params.repoLocalStateDir);
+            const key = await readJudgeCredentialStore(stateDir);
+            return {
+                key,
+                source: key ? `${stateDir}/credentials.json` : null,
+                sourceKind: sourceKindForApiKeyMode(key, key ? `${stateDir}/credentials.json` : null),
+                mode: 'apiKey',
+            };
+        }
+        if (ref?.startsWith('env:')) {
+            const envName = ref.slice(4);
+            const value = env[envName]?.trim() ?? null;
+            return {
+                key: value,
+                source: value ? `env:${envName}` : null,
+                sourceKind: sourceKindForApiKeyMode(value, value ? `env:${envName}` : null),
+                mode: 'apiKey',
+            };
+        }
+        return { key: null, source: null, sourceKind: 'missing', mode: 'apiKey' };
+    }
+    const fromEnv = resolveFromEnvChain(env, params.catalogSpec);
+    return {
+        ...fromEnv,
+        sourceKind: sourceKindForProjectMode(fromEnv, params.judge, params.catalogSpec),
+        mode: 'project',
+    };
+}

package/dist/core/judge-cloud-consent.d.ts

@@ -0,0 +1,13 @@
+import { JUDGE_CLOUD_CONSENT_REASON } from './capability/reasons.js';
+import type { BelayConfigV4, JudgeProviderId } from './config.js';
+export { JUDGE_CLOUD_CONSENT_REASON };
+export declare function judgeCloudConsentFingerprint(providerId: JudgeProviderId, endpoint: string): string;
+export declare function ensurePendingJudgeCloudConsentApproval(params: {
+    repoRoot: string;
+    config: BelayConfigV4;
+    providerId: JudgeProviderId;
+    endpoint: string;
+}): Promise<{
+    approvalId: string;
+    created: boolean;
+}>;

package/dist/core/judge-cloud-consent.js

@@ -0,0 +1,38 @@
+import { randomUUID } from 'node:crypto';
+import { loadApprovalState, saveApprovalState } from '../config-io.js';
+import { compactApprovals, createApprovalRecord } from './approval.js';
+import { JUDGE_CLOUD_CONSENT_REASON } from './capability/reasons.js';
+export { JUDGE_CLOUD_CONSENT_REASON };
+export function judgeCloudConsentFingerprint(providerId, endpoint) {
+    return `judge_cloud_consent:${providerId}:${endpoint.trim()}`;
+}
+export async function ensurePendingJudgeCloudConsentApproval(params) {
+    const { repoRoot, config, providerId, endpoint } = params;
+    const normalizedEndpoint = endpoint.trim();
+    const fingerprint = judgeCloudConsentFingerprint(providerId, normalizedEndpoint);
+    const pending = await loadApprovalState(repoRoot, 'pending-approvals.json', config);
+    const compacted = compactApprovals(pending);
+    const existing = compacted.approvals.find((approval) => approval.kind === 'capability' &&
+        approval.reason === JUDGE_CLOUD_CONSENT_REASON &&
+        approval.fingerprint === fingerprint &&
+        approval.repoRoot === repoRoot);
+    if (existing) {
+        await saveApprovalState(repoRoot, 'pending-approvals.json', compacted, config);
+        return { approvalId: existing.approvalId, created: false };
+    }
+    const approvalId = `belay_${randomUUID().replaceAll('-', '').slice(0, 12)}`;
+    const approval = createApprovalRecord({
+        kind: 'capability',
+        fingerprint,
+        repoRoot,
+        reason: JUDGE_CLOUD_CONSENT_REASON,
+        summary: `Cloud judge egress to ${providerId} (${normalizedEndpoint})`,
+        approvalTtlMinutes: config.approvalTtlMinutes,
+        approvalId,
+        input: `belay judge use ${providerId} --endpoint ${normalizedEndpoint}`,
+        inputKind: 'shell',
+    });
+    compacted.approvals.push(approval);
+    await saveApprovalState(repoRoot, 'pending-approvals.json', compacted, config);
+    return { approvalId, created: true };
+}