brainclaw 1.26.2 → 1.27.0

package/dist/core/execution-adapters.js

@@ -5,6 +5,56 @@ import { buildClaimEnvPrefix, buildWorkerIdentityEnv } from './execution-profile
 import { getCapabilityProfile } from './agent-capability.js';
 import { nowISO } from './ids.js';
 import { ensureRuntimeDirs, getRuntimeLogPath, getRuntimeSignalPath, } from './runtime-signals.js';
+const CONTRACT_BOOTSTRAP_SOURCE = `'use strict';
+const fs = require('node:fs');
+const [ackPath, turnId, runId, nonce, expectedContractHash, expectedSnapshotHash, attemptEpoch, workspaceDigest, expectedWorkspaceB64] = process.argv.slice(2);
+const contractHash = process.env.BRAINCLAW_EXECUTION_CONTRACT_HASH || '';
+const snapshotHash = process.env.BRAINCLAW_CAPABILITY_SNAPSHOT_HASH || '';
+const normalize = (value) => {
+  let resolved = fs.realpathSync.native(value);
+  if (process.platform === 'win32') resolved = resolved.toLowerCase();
+  return resolved;
+};
+const expectedWorkspace = Buffer.from(expectedWorkspaceB64 || '', 'base64url').toString('utf8');
+const actualCwd = normalize(process.cwd());
+const accepted = contractHash === expectedContractHash
+  && snapshotHash === expectedSnapshotHash
+  && expectedWorkspace !== ''
+  && actualCwd === normalize(expectedWorkspace);
+let fd;
+try {
+  fd = fs.openSync(ackPath, 'wx');
+} catch (error) {
+  if (error && error.code === 'EEXIST') process.exit(79);
+  throw error;
+}
+try {
+  fs.writeFileSync(fd, JSON.stringify({
+    status: accepted ? 'accepted' : 'rejected',
+    turn_id: turnId,
+    run_id: runId,
+    nonce,
+    ...(attemptEpoch ? { attempt_epoch: Number(attemptEpoch) } : {}),
+    ...(workspaceDigest ? { workspace_digest: workspaceDigest } : {}),
+    contract_hash: contractHash,
+    capability_snapshot_hash: snapshotHash,
+    cwd: actualCwd,
+  }));
+} finally {
+  fs.closeSync(fd);
+}
+if (!accepted) process.exitCode = 78;
+`;
+/** Materialize the tiny child bootstrap used by both cmd.exe and POSIX shells. */
+export function writeContractBootstrapScript(scriptPath) {
+    fs.mkdirSync(path.dirname(scriptPath), { recursive: true });
+    try {
+        if (fs.readFileSync(scriptPath, 'utf8') === CONTRACT_BOOTSTRAP_SOURCE)
+            return;
+    }
+    catch { /* create or replace below */ }
+    fs.writeFileSync(scriptPath, CONTRACT_BOOTSTRAP_SOURCE, 'utf8');
+}
 // The turn-echo values are raw-embedded into a shell one-liner (see marker()),
 // so the `[A-Za-z0-9_-]` safety invariant documented on TurnEcho is LOAD-BEARING,
 // not cosmetic. A stray `"` desyncs cmd.exe quote-parity (no sentinel file is
@@ -18,7 +68,9 @@ const TURN_ECHO_SAFE = /^[A-Za-z0-9_-]+$/;
 export function buildAckWrapCommand(bashCommand, paths, isWin32, turnEcho) {
     if (turnEcho) {
         for (const [field, value] of Object.entries(turnEcho)) {
-            if (!TURN_ECHO_SAFE.test(value)) {
+            if (value === undefined)
+                continue;
+            if (!TURN_ECHO_SAFE.test(String(value))) {
                 throw new Error(`buildAckWrapCommand: turnEcho.${field} must match ${TURN_ECHO_SAFE} to be shell-safe for the completion sentinel (got ${JSON.stringify(value)})`);
             }
         }
@@ -32,12 +84,42 @@ export function buildAckWrapCommand(bashCommand, paths, isWin32, turnEcho) {
     const marker = (p, status) => {
         if (!turnEcho)
             return touch(p);
-        const body = JSON.stringify({ turn_id: turnEcho.turn_id, run_id: turnEcho.run_id, nonce: turnEcho.nonce, status });
+        const body = JSON.stringify({
+            turn_id: turnEcho.turn_id,
+            run_id: turnEcho.run_id,
+            nonce: turnEcho.nonce,
+            ...(turnEcho.contract_hash ? { contract_hash: turnEcho.contract_hash } : {}),
+            ...(turnEcho.capability_snapshot_hash ? { capability_snapshot_hash: turnEcho.capability_snapshot_hash } : {}),
+            ...(turnEcho.attempt_epoch !== undefined ? { attempt_epoch: turnEcho.attempt_epoch } : {}),
+            ...(turnEcho.workspace_digest ? { workspace_digest: turnEcho.workspace_digest } : {}),
+            status,
+        });
         return isWin32 ? `echo ${body}>"${p}"` : `printf '%s' '${body}' > "${p}"`;
     };
-    const redirected = `${bashCommand} > "${paths.stdoutLog}" 2> "${paths.stderrLog}"`;
-    return (`${touch(paths.ackPath)} && ` +
-        `( ${redirected} && ${marker(paths.completedPath, 'completed')} || ${marker(paths.failedPath, 'failed')} )`);
+    const ack = (() => {
+        if (!turnEcho?.contract_hash || !turnEcho.capability_snapshot_hash)
+            return touch(paths.ackPath);
+        if (!paths.contractBootstrapPath) {
+            throw new Error('buildAckWrapCommand: contracted turn requires contractBootstrapPath');
+        }
+        // This child reads the EFFECTIVE environment it received. It writes the
+        // actual values and exits non-zero on mismatch, so `&&` prevents worker exec.
+        if (!paths.expectedWorkspacePath) {
+            throw new Error('buildAckWrapCommand: contracted turn requires expectedWorkspacePath');
+        }
+        const expectedWorkspaceB64 = Buffer.from(paths.expectedWorkspacePath, 'utf8').toString('base64url');
+        return `"${process.execPath}" "${paths.contractBootstrapPath}" "${paths.ackPath}" "${turnEcho.turn_id}" "${turnEcho.run_id}" "${turnEcho.nonce}" "${turnEcho.contract_hash}" "${turnEcho.capability_snapshot_hash}" "${turnEcho.attempt_epoch ?? ''}" "${turnEcho.workspace_digest ?? ''}" "${expectedWorkspaceB64}"`;
+    })();
+    const stdinRedirect = paths.stdinFilePath ? ` < "${paths.stdinFilePath}"` : '';
+    const redirected = `${bashCommand}${stdinRedirect} > "${paths.stdoutLog}" 2> "${paths.stderrLog}"`;
+    const cleanup = paths.stdinFilePath
+        ? isWin32
+            ? ` & del /q "${paths.stdinFilePath}" > nul 2>&1`
+            : `; rm -f -- "${paths.stdinFilePath}"`
+        : '';
+    return (`${ack} && ` +
+        `( ${redirected} && ${marker(paths.completedPath, 'completed')} || ${marker(paths.failedPath, 'failed')} )` +
+        cleanup);
 }
 /**
  * Check if a binary is resolvable on the system PATH.
@@ -115,10 +197,51 @@ export class CliExecutionAdapter {
         return { canSpawn: true, reason: 'agent has spawnable profile' };
     }
     prepareManualCommand(invoke, options) {
+        const isWin32 = process.platform === 'win32';
+        const shell = isWin32 ? 'cmd' : (invoke.shell ? 'bash' : 'sh');
+        if (options.turnEcho?.contract_hash
+            && options.turnEcho.capability_snapshot_hash
+            && options.assignmentId
+            && (options.ackRoot ?? options.worktreePath)) {
+            const signalRoot = options.ackRoot ?? options.worktreePath;
+            ensureRuntimeDirs(signalRoot);
+            const runtimeRunId = options.turnEcho?.run_id;
+            const ackPath = getRuntimeSignalPath(signalRoot, options.assignmentId, 'ack', runtimeRunId);
+            const contractBootstrapPath = `${ackPath}.bootstrap.cjs`;
+            writeContractBootstrapScript(contractBootstrapPath);
+            const stdinFilePath = isWin32 && invoke.promptDelivery === 'stdin_pipe' && invoke.promptText
+                ? `${ackPath}.stdin`
+                : undefined;
+            if (stdinFilePath && invoke.promptText) {
+                fs.writeFileSync(stdinFilePath, invoke.promptText, { encoding: 'utf8', mode: 0o600 });
+            }
+            const wrapped = buildAckWrapCommand(invoke.bashCommand, {
+                ackPath,
+                completedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'completed', runtimeRunId),
+                failedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'failed', runtimeRunId),
+                stdoutLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stdout', runtimeRunId),
+                stderrLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stderr', runtimeRunId),
+                stdinFilePath,
+                contractBootstrapPath,
+                expectedWorkspacePath: options.worktreePath,
+            }, isWin32, options.turnEcho);
+            const contractEnv = isWin32
+                ? [
+                    options.claimId && options.claimId !== '(dry-run)' ? `set BRAINCLAW_CLAIM_ID=${options.claimId}` : undefined,
+                    `set BRAINCLAW_EXECUTION_CONTRACT_HASH=${options.turnEcho.contract_hash}`,
+                    `set BRAINCLAW_CAPABILITY_SNAPSHOT_HASH=${options.turnEcho.capability_snapshot_hash}`,
+                ].filter((item) => Boolean(item)).join(' && ') + ' && '
+                : `export ${[
+                    options.claimId && options.claimId !== '(dry-run)' ? `BRAINCLAW_CLAIM_ID="${options.claimId}"` : undefined,
+                    `BRAINCLAW_EXECUTION_CONTRACT_HASH="${options.turnEcho.contract_hash}"`,
+                    `BRAINCLAW_CAPABILITY_SNAPSHOT_HASH="${options.turnEcho.capability_snapshot_hash}"`,
+                ].filter((item) => Boolean(item)).join(' ')}; `;
+            return { command: `${contractEnv}${wrapped}`, shell, contractWrapped: true };
+        }
         const envPrefix = buildManualEnvPrefix(options.claimId);
         return {
             command: `${envPrefix}${invoke.bashCommand}`,
-            shell: process.platform === 'win32' ? 'cmd' : (invoke.shell ? 'bash' : 'sh'),
+            shell,
         };
     }
     start(invoke, options) {
@@ -131,7 +254,16 @@ export class CliExecutionAdapter {
         const env = buildWorkerIdentityEnv(process.env, {
             agent: options.agent,
             claimId: options.claimId,
-            extraEnv: { ...buildGitAttributionEnv(options.agent), ...(invoke.env ?? {}) },
+            extraEnv: {
+                ...buildGitAttributionEnv(options.agent),
+                ...(invoke.env ?? {}),
+                // Contract identity wins over any agent/invoke-provided environment.
+                // The child bootstrap independently verifies these effective values.
+                ...(options.turnEcho?.contract_hash ? { BRAINCLAW_EXECUTION_CONTRACT_HASH: options.turnEcho.contract_hash } : {}),
+                ...(options.turnEcho?.capability_snapshot_hash
+                    ? { BRAINCLAW_CAPABILITY_SNAPSHOT_HASH: options.turnEcho.capability_snapshot_hash }
+                    : {}),
+            },
         });
         if (invoke.promptDelivery === 'temp_file' && invoke.tempFilePath && invoke.promptText) {
             const dir = path.dirname(invoke.tempFilePath);
@@ -156,7 +288,8 @@ export class CliExecutionAdapter {
         // process just ignores stdout/stderr here. stdin stays a pipe when the
         // prompt is delivered that way (the grouped agent command inherits it).
         const useAckWrap = !!(options.assignmentId && (options.ackRoot ?? options.worktreePath));
-        const stdinTarget = needsStdin ? 'pipe' : 'ignore';
+        const useWindowsStdinFile = isWin32 && useAckWrap && Boolean(needsStdin);
+        const stdinTarget = needsStdin && !useWindowsStdinFile ? 'pipe' : 'ignore';
         const stdio = [stdinTarget, 'ignore', 'ignore'];
         // pln#476 + pln#520 step 4: wrap the spawn so the worker shell touches the
         // pre-exec `ack` sentinel, redirects logs at the shell level, and emits a
@@ -168,12 +301,25 @@ export class CliExecutionAdapter {
         if (useAckWrap) {
             const signalRoot = options.ackRoot ?? options.worktreePath;
             ensureRuntimeDirs(signalRoot);
+            const runtimeRunId = options.turnEcho?.run_id;
+            const ackPath = getRuntimeSignalPath(signalRoot, options.assignmentId, 'ack', runtimeRunId);
+            const contractBootstrapPath = `${ackPath}.bootstrap.cjs`;
+            if (options.turnEcho?.contract_hash && options.turnEcho.capability_snapshot_hash) {
+                writeContractBootstrapScript(contractBootstrapPath);
+            }
+            const stdinFilePath = useWindowsStdinFile ? `${ackPath}.stdin` : undefined;
+            if (stdinFilePath) {
+                fs.writeFileSync(stdinFilePath, invoke.promptText, { encoding: 'utf8', mode: 0o600 });
+            }
             const wrappedCmd = buildAckWrapCommand(invoke.bashCommand, {
-                ackPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'ack'),
-                completedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'completed'),
-                failedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'failed'),
-                stdoutLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stdout'),
-                stderrLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stderr'),
+                ackPath,
+                completedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'completed', runtimeRunId),
+                failedPath: getRuntimeSignalPath(signalRoot, options.assignmentId, 'failed', runtimeRunId),
+                stdoutLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stdout', runtimeRunId),
+                stderrLog: getRuntimeLogPath(signalRoot, options.assignmentId, 'stderr', runtimeRunId),
+                stdinFilePath,
+                contractBootstrapPath,
+                expectedWorkspacePath: options.worktreePath,
             }, isWin32, options.turnEcho);
             child = spawn(wrappedCmd, [], {
                 detached: !isWin32,
@@ -201,7 +347,7 @@ export class CliExecutionAdapter {
         // On Windows shell:true: this never fires for ENOENT (cmd.exe succeeds);
         // the isBinaryOnPath pre-check above catches that case instead.
         child.on('error', () => { });
-        if (needsStdin && child.stdin) {
+        if (needsStdin && !useWindowsStdinFile && child.stdin) {
             child.stdin.write(invoke.promptText);
             child.stdin.end();
         }

package/dist/core/execution-contract.js

@@ -0,0 +1,345 @@
+import crypto from 'node:crypto';
+import { z } from 'zod';
+import { getCapabilityProfile, dispatchCanCommit, } from './agent-capability.js';
+import { ExpectedArtifactSchema } from './loops/artifact-contract.js';
+export const EXECUTION_CONTRACT_VERSION = 1;
+export const EXECUTION_CONTRACT_PROTOCOL_VERSION = 1;
+const RoleCapabilitySchema = z.enum(['execute', 'coordinate', 'review', 'consult']);
+const ExecutionSurfaceSchema = z.enum(['cli', 'ide', 'extension', 'remote']);
+export const CapabilityRequirementSchema = z.object({
+    roles: z.array(RoleCapabilitySchema).default(['execute']),
+    required_surfaces: z.array(z.enum([
+        'mcp',
+        'hooks',
+        'skills',
+        'rules',
+        'auto_approve',
+        'cli_spawn',
+        'commit',
+        'inbox',
+    ])).default([]),
+    execution_surfaces: z.array(ExecutionSurfaceSchema).default([]),
+    model: z.string().min(1).optional(),
+    required_tools: z.array(z.string().min(1)).default([]),
+});
+export const CapabilityResolutionReasonSchema = z.object({
+    code: z.enum([
+        'agent_profile_missing',
+        'role_unsupported',
+        'surface_unsupported',
+        'execution_surface_mismatch',
+        'model_unsupported',
+        'tool_catalog_unattested',
+    ]),
+    requirement: z.string().min(1),
+    expected: z.string().optional(),
+    actual: z.string().optional(),
+});
+export const HarnessCapabilityBindingSchema = z.object({
+    adapter_id: z.string().min(1),
+    adapter_version: z.string().min(1),
+    requested_model: z.string().min(1).optional(),
+    resolved_model: z.string().min(1).optional(),
+    model_resolution: z.enum(['exact', 'defaulted', 'unattested']),
+});
+export const CapabilitySnapshotSchema = z.object({
+    schema_version: z.literal(1),
+    agent: z.string().min(1),
+    agent_id: z.string().min(1).optional(),
+    profile_name: z.string().min(1).optional(),
+    accepted: z.boolean(),
+    requested: CapabilityRequirementSchema,
+    resolved: z.object({
+        roles: z.array(RoleCapabilitySchema),
+        surfaces: z.array(z.string().min(1)),
+        execution_surface: ExecutionSurfaceSchema.optional(),
+        model: z.string().min(1).optional(),
+        invoke_binary: z.string().min(1).optional(),
+        tool_catalog_attested: z.boolean(),
+        harness: HarnessCapabilityBindingSchema.optional(),
+    }),
+    reasons: z.array(CapabilityResolutionReasonSchema),
+});
+export const ExecutionContractSchema = z.object({
+    schema_version: z.literal(EXECUTION_CONTRACT_VERSION),
+    minimum_reader_version: z.number().int().positive().max(EXECUTION_CONTRACT_VERSION).default(1),
+    identity: z.object({
+        loop_id: z.string().min(1),
+        turn_id: z.string().min(1),
+        logical_attempt_epoch: z.number().int().nonnegative(),
+        assignment_id: z.string().min(1),
+        run_id: z.string().min(1),
+        kind: z.enum(['review', 'ideation', 'implementation', 'research', 'debug']),
+        phase: z.string().min(1),
+        iteration: z.number().int().nonnegative(),
+    }),
+    artifact_contract: z.object({
+        completion_mode: z.enum(['file', 'mcp', 'either']),
+        expected_artifacts: z.array(ExpectedArtifactSchema),
+    }),
+    capability_requirement: CapabilityRequirementSchema,
+    workspace_policy: z.object({
+        scope: z.string().min(1),
+        cwd: z.string().min(1),
+        worktree_path: z.string().min(1).optional(),
+        isolation: z.enum(['worktree', 'shared_checkout', 'none']),
+        write_access: z.enum(['read_only', 'workspace', 'unrestricted']),
+    }),
+    timeout_policy: z.object({
+        dispatch_lease_ms: z.number().int().positive(),
+        grant_lease_ms: z.number().int().positive(),
+    }),
+    evidence_policy: z.object({
+        require_turn_id: z.literal(true),
+        require_run_id: z.literal(true),
+        require_nonce: z.literal(true),
+        artifact_hash: z.enum(['required', 'optional']),
+    }),
+    protocol: z.object({
+        name: z.literal('attempt-authority'),
+        minimum_version: z.number().int().positive().max(EXECUTION_CONTRACT_PROTOCOL_VERSION),
+    }),
+});
+export const ExecutionContractRefSchema = z.object({
+    version: z.literal(EXECUTION_CONTRACT_VERSION),
+    hash: z.string().regex(/^[a-f0-9]{64}$/),
+    snapshot_hash: z.string().regex(/^[a-f0-9]{64}$/),
+    turn_id: z.string().min(1),
+});
+export const RuntimeCapabilityObservationSchema = z.object({
+    contract_hash: z.string().regex(/^[a-f0-9]{64}$/),
+    capability_snapshot_hash: z.string().regex(/^[a-f0-9]{64}$/),
+    adapter_id: z.string().min(1).optional(),
+    adapter_version: z.string().min(1).optional(),
+    observed_surfaces: z.array(z.string().min(1)).default([]),
+    observed_model: z.string().min(1).optional(),
+    accepted_contract_hash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+    accepted_capability_snapshot_hash: z.string().regex(/^[a-f0-9]{64}$/).optional(),
+});
+function canonicalValue(value) {
+    if (typeof value === 'string')
+        return value.normalize('NFC');
+    if (Array.isArray(value))
+        return value.map(canonicalValue);
+    if (value && typeof value === 'object') {
+        const normalized = Object.entries(value)
+            .filter(([, item]) => item !== undefined)
+            .map(([key, item]) => [key.normalize('NFC'), canonicalValue(item)])
+            .sort(([left], [right]) => left < right ? -1 : left > right ? 1 : 0);
+        if (new Set(normalized.map(([key]) => key)).size !== normalized.length) {
+            throw new Error('canonical execution contract contains duplicate NFC-normalized keys');
+        }
+        return Object.fromEntries(normalized);
+    }
+    return value;
+}
+export function canonicalExecutionContract(contract) {
+    return JSON.stringify(canonicalValue(ExecutionContractSchema.parse(contract)));
+}
+export function executionContractHash(contract) {
+    return crypto.createHash('sha256').update(canonicalExecutionContract(contract), 'utf8').digest('hex');
+}
+export function capabilitySnapshotHash(snapshot) {
+    const canonical = JSON.stringify(canonicalValue(CapabilitySnapshotSchema.parse(snapshot)));
+    return crypto.createHash('sha256').update(canonical, 'utf8').digest('hex');
+}
+function profileSurfaces(profile) {
+    const surfaces = [
+        profile.hasMcp && 'mcp',
+        profile.hasHooks && 'hooks',
+        profile.hasSkills && 'skills',
+        profile.hasRules && 'rules',
+        profile.hasAutoApprove && 'auto_approve',
+        profile.runtime.canBeSpawnedCli && 'cli_spawn',
+        profile.runtime.inbox && 'inbox',
+        dispatchCanCommit(profile) && 'commit',
+    ].filter((value) => Boolean(value));
+    return [...new Set(surfaces)].sort();
+}
+function resolvedModel(profile, requested) {
+    if (!requested)
+        return profile.default_model;
+    if (profile.model_flag || profile.default_model === requested)
+        return requested;
+    return undefined;
+}
+export function resolveCapabilitySnapshot(agent, requirementInput, agentId, harness) {
+    const requested = CapabilityRequirementSchema.parse(requirementInput);
+    const harnessBinding = harness ? HarnessCapabilityBindingSchema.parse(harness) : undefined;
+    const profile = getCapabilityProfile(agent);
+    const reasons = [];
+    if (!profile) {
+        reasons.push({ code: 'agent_profile_missing', requirement: 'agent_profile', expected: agent });
+        return CapabilitySnapshotSchema.parse({
+            schema_version: 1,
+            agent,
+            agent_id: agentId,
+            accepted: false,
+            requested,
+            resolved: { roles: [], surfaces: [], tool_catalog_attested: false },
+            reasons,
+        });
+    }
+    const surfaces = profileSurfaces(profile);
+    for (const role of requested.roles) {
+        if (!profile.role_capabilities.includes(role)) {
+            reasons.push({
+                code: 'role_unsupported',
+                requirement: `role:${role}`,
+                expected: role,
+                actual: profile.role_capabilities.join(','),
+            });
+        }
+    }
+    for (const surface of requested.required_surfaces) {
+        if (!surfaces.includes(surface)) {
+            reasons.push({
+                code: 'surface_unsupported',
+                requirement: `surface:${surface}`,
+                expected: surface,
+                actual: surfaces.join(','),
+            });
+        }
+    }
+    if (requested.execution_surfaces.length > 0
+        && !requested.execution_surfaces.includes(profile.execution_env.surface)) {
+        reasons.push({
+            code: 'execution_surface_mismatch',
+            requirement: 'execution_surface',
+            expected: requested.execution_surfaces.join(','),
+            actual: profile.execution_env.surface,
+        });
+    }
+    const model = resolvedModel(profile, requested.model);
+    if (requested.model && !model) {
+        reasons.push({
+            code: 'model_unsupported',
+            requirement: 'model',
+            expected: requested.model,
+            actual: profile.default_model,
+        });
+    }
+    // Current profiles attest transport surfaces, not per-tool catalogs. Refuse
+    // named tools rather than guessing from hasMcp/hasSkills.
+    if (requested.required_tools.length > 0) {
+        reasons.push({
+            code: 'tool_catalog_unattested',
+            requirement: 'required_tools',
+            expected: requested.required_tools.join(','),
+            actual: 'unattested',
+        });
+    }
+    return CapabilitySnapshotSchema.parse({
+        schema_version: 1,
+        agent,
+        agent_id: agentId,
+        profile_name: profile.name,
+        accepted: reasons.length === 0,
+        requested,
+        resolved: {
+            roles: profile.role_capabilities,
+            surfaces,
+            execution_surface: profile.execution_env.surface,
+            model,
+            invoke_binary: profile.invoke_binary,
+            tool_catalog_attested: false,
+            harness: harnessBinding,
+        },
+        reasons,
+    });
+}
+export function executionContractRef(contract, snapshot) {
+    return {
+        version: contract.schema_version,
+        hash: executionContractHash(contract),
+        snapshot_hash: capabilitySnapshotHash(snapshot),
+        turn_id: contract.identity.turn_id,
+    };
+}
+export function assertExecutionContractIntegrity(contract, ref, snapshot, selectedAgent) {
+    const parsedContract = ExecutionContractSchema.parse(contract);
+    const parsedRef = ExecutionContractRefSchema.parse(ref);
+    const parsedSnapshot = CapabilitySnapshotSchema.parse(snapshot);
+    if (parsedRef.turn_id !== parsedContract.identity.turn_id) {
+        throw new Error(`execution contract turn mismatch: ${parsedRef.turn_id} != ${parsedContract.identity.turn_id}`);
+    }
+    const actualHash = executionContractHash(parsedContract);
+    if (parsedRef.hash !== actualHash) {
+        throw new Error(`execution contract hash mismatch: ${parsedRef.hash} != ${actualHash}`);
+    }
+    const actualSnapshotHash = capabilitySnapshotHash(parsedSnapshot);
+    if (parsedRef.snapshot_hash !== actualSnapshotHash) {
+        throw new Error(`capability snapshot hash mismatch: ${parsedRef.snapshot_hash} != ${actualSnapshotHash}`);
+    }
+    if (!parsedSnapshot.accepted) {
+        throw new Error('execution contract capability snapshot was not accepted');
+    }
+    if (JSON.stringify(parsedSnapshot.requested) !== JSON.stringify(parsedContract.capability_requirement)) {
+        throw new Error('execution contract capability requirement differs from its resolved snapshot');
+    }
+    if (selectedAgent && parsedSnapshot.agent !== selectedAgent.agent) {
+        throw new Error(`capability snapshot agent mismatch: ${parsedSnapshot.agent} != ${selectedAgent.agent}`);
+    }
+    if (selectedAgent && parsedSnapshot.agent_id !== selectedAgent.agent_id) {
+        throw new Error(`capability snapshot agent_id mismatch: ${parsedSnapshot.agent_id ?? 'none'} != ${selectedAgent.agent_id ?? 'none'}`);
+    }
+}
+/**
+ * Pre-crossing acceptance emitted by the frozen harness adapter. The child
+ * process still confirms the effective environment in its bootstrap ACK after
+ * spawn; this attestation proves, before authority crosses, that the selected
+ * adapter accepted the exact immutable contract it is about to deliver.
+ */
+export function attestHarnessContractAcceptance(expectedRef, snapshot, binding) {
+    const parsedSnapshot = CapabilitySnapshotSchema.parse(snapshot);
+    const parsedBinding = HarnessCapabilityBindingSchema.parse(binding);
+    if (!parsedSnapshot.accepted) {
+        throw new Error('harness cannot accept a rejected capability snapshot');
+    }
+    const frozen = parsedSnapshot.resolved.harness;
+    if (!frozen)
+        throw new Error('capability snapshot has no frozen harness binding');
+    if (frozen.adapter_id !== parsedBinding.adapter_id
+        || frozen.adapter_version !== parsedBinding.adapter_version
+        || frozen.requested_model !== parsedBinding.requested_model
+        || frozen.resolved_model !== parsedBinding.resolved_model) {
+        throw new Error(`harness acceptance mismatch: frozen ${frozen.adapter_id}@${frozen.adapter_version}, `
+            + `selected ${parsedBinding.adapter_id}@${parsedBinding.adapter_version}`);
+    }
+    return {
+        contract_hash: expectedRef.hash,
+        capability_snapshot_hash: expectedRef.snapshot_hash,
+    };
+}
+/**
+ * Deterministic capability selection/reselection. Input order is deliberately
+ * irrelevant so replaying the same candidate set produces the same worker.
+ * Callers can exclude a failed pre-cross candidate and run the resolver again.
+ */
+export function resolveExecutionCandidate(candidates, requirementInput, options = {}) {
+    const requirement = CapabilityRequirementSchema.parse(requirementInput);
+    const excluded = new Set((options.exclude ?? []).map(({ agent, agent_id }) => `${agent.normalize('NFC')}\0${(agent_id ?? '').normalize('NFC')}`));
+    const ordered = candidates
+        .filter(({ agent, agent_id }) => !excluded.has(`${agent.normalize('NFC')}\0${(agent_id ?? '').normalize('NFC')}`))
+        .map((candidate) => ({ ...candidate, agent: candidate.agent.normalize('NFC'), agent_id: candidate.agent_id?.normalize('NFC') }))
+        .sort((left, right) => (right.preference ?? 0) - (left.preference ?? 0)
+        || left.agent.localeCompare(right.agent, 'en')
+        || (left.agent_id ?? '').localeCompare(right.agent_id ?? '', 'en'));
+    const evaluated = ordered.map((candidate) => ({
+        ...candidate,
+        snapshot: resolveCapabilitySnapshot(candidate.agent, requirement, candidate.agent_id),
+    }));
+    const selected = evaluated.find((candidate) => candidate.snapshot.accepted);
+    return selected ? { kind: 'selected', selected, evaluated } : { kind: 'rejected', evaluated };
+}
+export function validateWorkerContractAcceptance(expectedRef, acceptedRef, launchStatus) {
+    const expected = { contract_hash: expectedRef.hash, capability_snapshot_hash: expectedRef.snapshot_hash };
+    if (expected.contract_hash === acceptedRef.contract_hash
+        && expected.capability_snapshot_hash === acceptedRef.capability_snapshot_hash)
+        return { kind: 'accepted' };
+    if (launchStatus === 'crossed') {
+        return { kind: 'post_crossing_anomaly', expected, accepted: acceptedRef, respawn: false };
+    }
+    return { kind: 'abort_and_reselect', expected, accepted: acceptedRef };
+}
+//# sourceMappingURL=execution-contract.js.map