brainclaw 1.26.2 → 1.27.0

package/dist/core/execution.js

@@ -9,11 +9,12 @@
  */
 import fs from 'node:fs';
 import { resolveConcurrencyLimit, resolveResourceKey } from './agent-capability.js';
-import { getRuntimeSignalPath } from './runtime-signals.js';
+import { getRuntimeSignalPath, readContractAck } from './runtime-signals.js';
 import { appendAuditEntry } from './audit.js';
 import { loadAllSessions } from './identity.js';
 import { loadConfig } from './config.js';
 import { loadAssignment } from './assignments.js';
+import { recordExecutionContractAnomaly } from './agentruns.js';
 import { defaultExecutionAdapter, } from './execution-adapters.js';
 function sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
@@ -29,26 +30,54 @@ function sleep(ms) {
  * bclaw_assignment_update; the ack file lets us recognize a healthy
  * spawn anyway).
  */
-export function getAssignmentAckPath(cwd, assignmentId) {
-    return getRuntimeSignalPath(cwd, assignmentId, 'ack');
+export function getAssignmentAckPath(cwd, assignmentId, runId) {
+    return getRuntimeSignalPath(cwd, assignmentId, 'ack', runId);
 }
-function isAssignmentAcked(assignmentId, cwd) {
+function isAssignmentAcked(assignmentId, cwd, runId) {
     // Fast path: the brief-ack sentinel was written by the worker shell.
-    if (fs.existsSync(getAssignmentAckPath(cwd, assignmentId)))
+    if (fs.existsSync(getAssignmentAckPath(cwd, assignmentId, runId)))
         return true;
+    // A v2 generation must acknowledge its own run-scoped bootstrap. The stable
+    // Assignment may already be running/completed because of a prior epoch.
+    if (runId)
+        return false;
     // Standard path: the worker called bclaw_assignment_update via MCP and
     // moved the assignment past the offered/created state.
     const assignment = loadAssignment(assignmentId, cwd);
     return !!assignment && assignment.status !== 'created' && assignment.status !== 'offered';
 }
-async function waitForAssignmentHandshake(assignmentId, cwd, timeoutMs) {
+async function waitForAssignmentHandshake(assignmentId, cwd, timeoutMs, runId) {
     const deadline = Date.now() + timeoutMs;
     while (Date.now() < deadline) {
-        if (isAssignmentAcked(assignmentId, cwd))
+        if (isAssignmentAcked(assignmentId, cwd, runId))
             return true;
         await sleep(100);
     }
-    return isAssignmentAcked(assignmentId, cwd);
+    return isAssignmentAcked(assignmentId, cwd, runId);
+}
+function normalizeWorkspacePath(value) {
+    try {
+        const resolved = fs.realpathSync.native(value);
+        return process.platform === 'win32' ? resolved.toLowerCase() : resolved;
+    }
+    catch {
+        return undefined;
+    }
+}
+function contractAckMatches(assignmentId, cwd, turnEcho, expectedWorkspacePath) {
+    if (!turnEcho.contract_hash || !turnEcho.capability_snapshot_hash)
+        return true;
+    const parsed = readContractAck(cwd, assignmentId, turnEcho.run_id);
+    const expectedWorkspace = expectedWorkspacePath ? normalizeWorkspacePath(expectedWorkspacePath) : undefined;
+    return parsed?.status === 'accepted'
+        && parsed.turn_id === turnEcho.turn_id
+        && parsed.run_id === turnEcho.run_id
+        && parsed.nonce === turnEcho.nonce
+        && parsed.contract_hash === turnEcho.contract_hash
+        && parsed.capability_snapshot_hash === turnEcho.capability_snapshot_hash
+        && (turnEcho.attempt_epoch === undefined || parsed.attempt_epoch === turnEcho.attempt_epoch)
+        && (turnEcho.workspace_digest === undefined || parsed.workspace_digest === turnEcho.workspace_digest)
+        && (!expectedWorkspace || parsed.cwd === expectedWorkspace);
 }
 // ── Helpers ────────────────────────────────────────────────
 /** Parse a duration string like '4h', '30m', '1d' to milliseconds. */
@@ -149,8 +178,41 @@ export function executeDispatchedCommand(invoke, options) {
  */
 export async function attemptExecution(invoke, options) {
     const adapter = options.adapter ?? defaultExecutionAdapter;
+    const contracted = Boolean(options.turnEcho?.contract_hash && options.turnEcho.capability_snapshot_hash);
+    const fenceContractedGeneration = (reason, processInfo) => {
+        if (options.turnEcho) {
+            try {
+                recordExecutionContractAnomaly(options.turnEcho.run_id, {
+                    source: 'bootstrap_ack',
+                    reason,
+                }, options.cwd);
+            }
+            catch { /* a rejected/missing ack remains the fallback fence */ }
+        }
+        return {
+            execution_status: processInfo?.pid ? 'delivered_and_started' : 'inbox_only',
+            pid: processInfo?.pid,
+            started_at: processInfo?.started_at,
+            error: `${reason}; contracted generation is fenced and MUST NOT be respawned`,
+            failure_kind: 'contract_acceptance_anomaly',
+            execution_reason: 'contract_acceptance_anomaly',
+        };
+    };
+    const prepareManual = () => {
+        // A custom adapter cannot self-attest that its opaque command contains the
+        // native bootstrap/env/sentinel fence. Until the adapter contract becomes
+        // declarative, only the core adapter may emit contracted manual launches.
+        if (contracted && adapter !== defaultExecutionAdapter)
+            return undefined;
+        const manual = adapter.prepareManualCommand(invoke, { ...options, ackRoot: options.cwd });
+        if (contracted && !manual.contractWrapped)
+            return undefined;
+        return manual;
+    };
     // No invoke command available (IDE-only agents, etc.)
     if (!invoke) {
+        if (contracted)
+            return fenceContractedGeneration('no contract-capable invoke command is available after crossing');
         return { execution_status: 'inbox_only', execution_reason: 'no_invoke_command' };
     }
     const spawnCheck = adapter.canSpawn(options.agent);
@@ -162,7 +224,9 @@ export async function attemptExecution(invoke, options) {
     // (1) autoExecute explicitly disabled: a deliberate manual handoff, NOT a
     // failure. Prepend BRAINCLAW_CLAIM_ID so manual copy-paste still routes.
     if (!options.autoExecute) {
-        const manual = adapter.prepareManualCommand(invoke, options);
+        const manual = prepareManual();
+        if (!manual)
+            return fenceContractedGeneration('execution adapter cannot produce a contract-wrapped manual command');
         return {
             execution_status: 'command_ready_manual',
             command: manual.command,
@@ -174,7 +238,9 @@ export async function attemptExecution(invoke, options) {
     // failure of the caller's intent. Surface spawnCheck.reason (previously
     // dropped) instead of returning a bare manual command.
     if (!spawnCheck.canSpawn) {
-        const manual = adapter.prepareManualCommand(invoke, options);
+        const manual = prepareManual();
+        if (!manual)
+            return fenceContractedGeneration(`agent is not spawnable and the adapter cannot produce a contract-wrapped manual command: ${spawnCheck.reason}`);
         return {
             execution_status: 'command_ready_manual',
             command: manual.command,
@@ -200,7 +266,9 @@ export async function attemptExecution(invoke, options) {
             scope: options.agent,
             after: { reason: 'no_worktree', refused: true },
         }, options.cwd);
-        const manual = adapter.prepareManualCommand(invoke, options);
+        const manual = prepareManual();
+        if (!manual)
+            return fenceContractedGeneration('worktree is missing and the adapter cannot produce a contract-wrapped manual command');
         return {
             execution_status: 'command_ready_manual',
             command: manual.command,
@@ -223,7 +291,9 @@ export async function attemptExecution(invoke, options) {
                 scope: options.agent,
                 after: { reason: instanceCheck.reason, active_sessions: instanceCheck.activeSessions, skipped: true },
             }, options.cwd);
-            const manual = adapter.prepareManualCommand(invoke, options);
+            const manual = prepareManual();
+            if (!manual)
+                return fenceContractedGeneration(`capacity is exhausted and the adapter cannot produce a contract-wrapped manual command: ${instanceCheck.reason}`);
             return {
                 execution_status: 'command_ready_manual',
                 command: manual.command,
@@ -251,7 +321,7 @@ export async function attemptExecution(invoke, options) {
             const parsedEnvTimeout = envTimeout ? Number.parseInt(envTimeout, 10) : NaN;
             const handshakeTimeoutMs = options.handshakeTimeoutMs ??
                 (Number.isFinite(parsedEnvTimeout) && parsedEnvTimeout > 0 ? parsedEnvTimeout : 30_000);
-            const handshakeOk = await waitForAssignmentHandshake(options.assignmentId, options.cwd, handshakeTimeoutMs);
+            const handshakeOk = await waitForAssignmentHandshake(options.assignmentId, options.cwd, handshakeTimeoutMs, options.turnEcho?.run_id);
             if (!handshakeOk) {
                 appendAuditEntry({
                     actor: options.dispatcherAgent,
@@ -262,7 +332,10 @@ export async function attemptExecution(invoke, options) {
                     scope: options.agent,
                     after: { reason: `No assignment handshake within ${handshakeTimeoutMs}ms`, pid: result.pid, command: invoke.bashCommand },
                 }, options.cwd);
-                const manual = adapter.prepareManualCommand(invoke, options);
+                if (contracted) {
+                    return fenceContractedGeneration(`spawn launched but contract bootstrap did not acknowledge within ${handshakeTimeoutMs}ms`, { pid: result.pid, started_at: result.started_at });
+                }
+                const manual = prepareManual();
                 return {
                     execution_status: 'command_ready_manual',
                     command: manual.command,
@@ -273,6 +346,43 @@ export async function attemptExecution(invoke, options) {
                     pid: result.pid,
                 };
             }
+            if (options.turnEcho && !contractAckMatches(options.assignmentId, options.cwd, options.turnEcho, options.worktreePath)) {
+                const accepted = readContractAck(options.cwd, options.assignmentId, options.turnEcho.run_id);
+                let anomalyPersistenceError;
+                try {
+                    recordExecutionContractAnomaly(options.turnEcho.run_id, {
+                        source: 'bootstrap_ack',
+                        reason: 'bootstrap rejected, omitted or changed the immutable execution contract',
+                        accepted_contract_hash: accepted?.contract_hash,
+                        accepted_capability_snapshot_hash: accepted?.capability_snapshot_hash,
+                    }, options.cwd);
+                }
+                catch (error) {
+                    anomalyPersistenceError = error instanceof Error ? error.message : String(error);
+                }
+                appendAuditEntry({
+                    actor: options.dispatcherAgent,
+                    actor_id: options.dispatcherAgentId,
+                    action: 'spawn_failed',
+                    item_id: options.assignmentId,
+                    item_type: 'agent_run',
+                    scope: options.agent,
+                    after: {
+                        reason: 'post-crossing execution-contract acceptance mismatch or missing ack; respawn=false',
+                        pid: result.pid,
+                        accepted,
+                        anomaly_persistence_error: anomalyPersistenceError,
+                    },
+                }, options.cwd);
+                return {
+                    execution_status: 'delivered_and_started',
+                    started_at: result.started_at,
+                    pid: result.pid,
+                    error: `Worker/bootstrap did not acknowledge execution contract ${options.turnEcho.contract_hash ?? 'legacy'} exactly; run is anomalous and MUST NOT be respawned`,
+                    failure_kind: 'contract_acceptance_anomaly',
+                    execution_reason: 'contract_acceptance_anomaly',
+                };
+            }
         }
         // Audit success
         appendAuditEntry({
@@ -303,8 +413,12 @@ export async function attemptExecution(invoke, options) {
             scope: options.agent,
             after: { error: errorMsg, command: invoke.bashCommand },
         }, options.cwd);
-        // Graceful fallback — include BRAINCLAW_CLAIM_ID for manual routing
-        const manual = adapter.prepareManualCommand(invoke, options);
+        // Once a contracted generation crossed, an uncertain spawn outcome can
+        // never degrade to a second/manual launch. Legacy dispatch keeps fallback.
+        if (contracted) {
+            return fenceContractedGeneration(`spawn failed after the launch fence crossed (${errorMsg})`);
+        }
+        const manual = prepareManual();
         return {
             execution_status: 'command_ready_manual',
             command: manual.command,

package/dist/core/harness-adapters/base.js

@@ -0,0 +1,150 @@
+import { buildInvokeCommand, getCapabilityProfile } from '../agent-capability.js';
+import { resolveBinaryOnPath } from '../execution-adapters.js';
+import { z } from 'zod';
+const TerminalResultClaimSchema = z.object({
+    schema_version: z.literal(1),
+    status: z.enum(['completed', 'blocked', 'failed', 'partial']),
+    summary: z.string().min(1),
+    body: z.string().min(1).optional(),
+    artifact_type: z.string().min(1).optional(),
+    review_verdict: z.enum(['approve', 'request_changes']).optional(),
+}).strict();
+const TERMINAL_RESULT_PROTOCOL = `
+
+Brainclaw native terminal result contract:
+Your final assistant message MUST be exactly one JSON object with this shape and no markdown fence:
+{"schema_version":1,"status":"completed|blocked|failed|partial","summary":"...","body":"optional details","artifact_type":"optional Loop artifact type","review_verdict":"approve|request_changes (required for review verdict work)"}
+Do not infer or omit review_verdict when the task requires a review verdict.`;
+export function withTerminalResultProtocol(input) {
+    return { ...input, prompt: `${input.prompt}${TERMINAL_RESULT_PROTOCOL}` };
+}
+export function parseTerminalResultClaim(text) {
+    const parsed = parseJsonObject(text.trim());
+    const claim = TerminalResultClaimSchema.safeParse(parsed);
+    if (!claim.success)
+        return undefined;
+    return { ...claim.data, raw_output_refs: [], diagnostics: [] };
+}
+export function applyTerminalResultClaim(base, terminalText) {
+    const structured = terminalText ? parseTerminalResultClaim(terminalText) : undefined;
+    if (!structured) {
+        base.diagnostics.push({
+            kind: 'protocol', code: 'invalid_result_claim',
+            message: 'terminal assistant output was not a strict Brainclaw result-claim v1 object',
+        });
+        if (base.status === 'completed')
+            base.status = 'partial';
+        return base;
+    }
+    if (base.status !== 'completed') {
+        return {
+            ...base,
+            summary: structured.summary,
+            body: structured.body,
+            artifact_type: structured.artifact_type,
+            review_verdict: structured.review_verdict,
+        };
+    }
+    return {
+        ...base,
+        status: structured.status,
+        summary: structured.summary,
+        body: structured.body,
+        artifact_type: structured.artifact_type,
+        review_verdict: structured.review_verdict,
+    };
+}
+export function declaredProbe(adapterId, adapterVersion, agent, protocols, options = {}, requireInstalledExecutable = false) {
+    const profile = getCapabilityProfile(agent);
+    const executable = profile?.invoke_binary;
+    const resolvedExecutable = executable && requireInstalledExecutable
+        ? (options.resolveExecutable ?? resolveBinaryOnPath)(executable)
+        : executable;
+    const available = Boolean(profile?.runtime.canBeSpawnedCli && executable && resolvedExecutable);
+    return {
+        adapter_id: adapterId,
+        adapter_version: adapterVersion,
+        agent,
+        executable,
+        availability: available ? 'declared' : 'unavailable',
+        supported_output_protocols: protocols,
+        model_attestation: profile?.model_flag ? 'cli_selectable' : 'unattested',
+        diagnostics: !profile
+            ? [`unknown agent profile: ${agent}`]
+            : requireInstalledExecutable && executable && !resolvedExecutable
+                ? [`executable not found on PATH: ${executable}`]
+                : [],
+    };
+}
+export function resolveDeclaredBinding(probe, requestedModel, rejectModel) {
+    if (probe.availability === 'unavailable') {
+        throw new Error(`harness_capability_rejected: ${probe.adapter_id} is unavailable for ${probe.agent}`);
+    }
+    const rejection = requestedModel && rejectModel?.(requestedModel);
+    if (rejection)
+        throw new Error(`harness_capability_rejected: ${rejection}`);
+    return {
+        adapter_id: probe.adapter_id,
+        adapter_version: probe.adapter_version,
+        agent: probe.agent,
+        requested_model: requestedModel,
+        resolved_model: requestedModel,
+        // A CLI model flag proves selection intent, not that the installed account
+        // can serve that name. We pass the exact string and never configure a
+        // fallback, but keep the resolution honest until runtime observes it.
+        model_resolution: requestedModel ? 'unattested' : 'defaulted',
+        probe,
+    };
+}
+export function buildProfileInvocation(input) {
+    const invoke = buildInvokeCommand(input.binding.agent, input.prompt, {
+        mode: input.mode,
+        platform: input.platform,
+        model: input.binding.resolved_model,
+    });
+    if (!invoke)
+        throw new Error(`harness_prepare_failed: no invoke command for ${input.binding.agent}`);
+    return {
+        adapter_id: input.binding.adapter_id,
+        adapter_version: input.binding.adapter_version,
+        invoke,
+        output_protocol: 'text',
+        requested_model: input.binding.requested_model,
+        resolved_model: input.binding.resolved_model,
+    };
+}
+export function genericOutcome(observation) {
+    const diagnostics = [];
+    if (observation.timed_out)
+        diagnostics.push({ kind: 'transport', code: 'timeout', message: 'execution timed out' });
+    if (observation.cancelled)
+        diagnostics.push({ kind: 'transport', code: 'cancelled', message: 'execution was cancelled' });
+    if (observation.exit_code === undefined) {
+        diagnostics.push({ kind: 'transport', code: 'unknown_exit', message: 'process exit code was not observed' });
+    }
+    else if (observation.exit_code !== 0) {
+        diagnostics.push({ kind: 'transport', code: 'nonzero_exit', message: `process exited with ${observation.exit_code}` });
+    }
+    const text = observation.stdout.trim() || observation.stderr.trim();
+    return {
+        status: observation.timed_out || observation.cancelled || (observation.exit_code !== undefined && observation.exit_code !== 0)
+            ? 'failed'
+            : observation.exit_code === 0 ? 'completed' : 'partial',
+        summary: text.slice(0, 1000) || 'harness completed without terminal text',
+        body: text || undefined,
+        raw_output_refs: [],
+        diagnostics,
+    };
+}
+export function parseJsonObject(text) {
+    try {
+        const value = JSON.parse(text);
+        return value !== null && typeof value === 'object' && !Array.isArray(value)
+            ? value
+            : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+//# sourceMappingURL=base.js.map

package/dist/core/harness-adapters/claude.js

@@ -0,0 +1,39 @@
+import { applyTerminalResultClaim, buildProfileInvocation, declaredProbe, genericOutcome, parseJsonObject, resolveDeclaredBinding, withTerminalResultProtocol } from './base.js';
+export class ClaudeHarnessAdapter {
+    id = 'claude-cli';
+    version = '1';
+    matches(agent) { return ['claude-code', 'claude-sonnet'].includes(agent.trim().toLowerCase()); }
+    probe(agent, options) {
+        return declaredProbe(this.id, this.version, agent, ['json', 'text'], options, true);
+    }
+    resolve(agent, requestedModel, options) {
+        return resolveDeclaredBinding(this.probe(agent, options), requestedModel, (model) => /fable/i.test(model) ? `Claude model '${model}' is not attested by the installed harness` : undefined);
+    }
+    prepare(input) {
+        const prepared = buildProfileInvocation(withTerminalResultProtocol(input));
+        prepared.invoke.args.push('--output-format', 'json');
+        prepared.invoke.bashCommand += ' --output-format "json"';
+        return { ...prepared, output_protocol: 'json' };
+    }
+    parseOutcome(observation) {
+        const base = genericOutcome(observation);
+        const parsed = parseJsonObject(observation.stdout.trim());
+        const terminalSuccess = parsed?.type === 'result'
+            && parsed.subtype === 'success'
+            && parsed.is_error === false
+            && typeof parsed.result === 'string';
+        const result = terminalSuccess ? parsed.result : undefined;
+        const observedModel = typeof parsed?.model === 'string' ? parsed.model : undefined;
+        if (!parsed && observation.stdout.trim()) {
+            base.diagnostics.push({ kind: 'protocol', code: 'invalid_json', message: 'Claude output was not valid JSON' });
+        }
+        else if (!terminalSuccess) {
+            base.diagnostics.push({ kind: 'protocol', code: 'missing_terminal_result', message: 'Claude did not emit a successful terminal result object' });
+        }
+        if (base.status === 'completed' && !terminalSuccess)
+            base.status = 'partial';
+        const claimed = terminalSuccess ? applyTerminalResultClaim(base, result) : base;
+        return { ...claimed, observed_model: observedModel };
+    }
+}
+//# sourceMappingURL=claude.js.map

package/dist/core/harness-adapters/codex.js

@@ -0,0 +1,57 @@
+import { applyTerminalResultClaim, buildProfileInvocation, declaredProbe, genericOutcome, parseJsonObject, resolveDeclaredBinding, withTerminalResultProtocol } from './base.js';
+export class CodexHarnessAdapter {
+    id = 'codex-cli';
+    version = '1';
+    matches(agent) { return agent.trim().toLowerCase() === 'codex'; }
+    probe(agent, options) {
+        return declaredProbe(this.id, this.version, agent, ['jsonl', 'text'], options, true);
+    }
+    resolve(agent, requestedModel, options) {
+        return resolveDeclaredBinding(this.probe(agent, options), requestedModel);
+    }
+    prepare(input) {
+        const prepared = buildProfileInvocation(withTerminalResultProtocol(input));
+        prepared.invoke.args.push('--json');
+        prepared.invoke.bashCommand += ' --json';
+        return { ...prepared, output_protocol: 'jsonl' };
+    }
+    parseOutcome(observation) {
+        const base = genericOutcome(observation);
+        const lines = observation.stdout.split(/\r?\n/).map((line) => line.trim()).filter(Boolean);
+        const parsed = lines.map((line) => ({ line, value: parseJsonObject(line) }));
+        const objects = parsed.map((item) => item.value).filter((item) => Boolean(item));
+        const invalidCount = parsed.filter((item) => !item.value).length;
+        const agentMessages = objects.flatMap((event) => {
+            const item = event.item;
+            if (event.type !== 'item.completed' || !item || typeof item !== 'object')
+                return [];
+            const record = item;
+            return record.type === 'agent_message' && typeof record.text === 'string' ? [record.text] : [];
+        });
+        const result = agentMessages.at(-1);
+        const terminalSuccess = objects.some((event) => event.type === 'turn.completed');
+        const reversed = [...objects].reverse();
+        const failure = reversed.find((event) => event.type === 'turn.failed')
+            ?? reversed.find((event) => event.type === 'error');
+        const failureMessage = typeof failure?.message === 'string'
+            ? failure.message
+            : failure?.error && typeof failure.error === 'object' && typeof failure.error.message === 'string'
+                ? failure.error.message
+                : undefined;
+        if (invalidCount > 0) {
+            base.diagnostics.push({ kind: 'protocol', code: 'invalid_jsonl', message: `${invalidCount} Codex output line(s) were not valid JSON objects` });
+        }
+        if (failure) {
+            base.diagnostics.push({ kind: 'protocol', code: 'terminal_failure', message: failureMessage ?? 'Codex emitted a terminal failure event' });
+            base.status = 'failed';
+        }
+        else if (base.status === 'completed' && (!terminalSuccess || !result || invalidCount > 0)) {
+            base.diagnostics.push({ kind: 'protocol', code: 'missing_terminal_result', message: 'Codex did not emit a complete successful terminal result' });
+            base.status = 'partial';
+        }
+        if (failure)
+            return { ...base, summary: failureMessage?.slice(0, 1000) ?? base.summary };
+        return applyTerminalResultClaim(base, result);
+    }
+}
+//# sourceMappingURL=codex.js.map

package/dist/core/harness-adapters/harvest.js

@@ -0,0 +1,109 @@
+import fs from 'node:fs';
+import { loadAgentRun, recordRuntimeCapabilityObservation } from '../agentruns.js';
+import { loadAssignment } from '../assignments.js';
+import { findReservationByAssignmentId } from '../loops/attempt-reservation.js';
+import { executionContractForGeneration } from '../loops/attempt-authority.js';
+import { resolveTurnGenerationChain } from '../loops/attempt-generations.js';
+import { getRuntimeLogPath, readCompletionSignals, readContractAck } from '../runtime-signals.js';
+import { normalizeHarnessClaimToLaneResult, parseHarnessOutcome } from './result.js';
+function readLog(file) {
+    try {
+        return fs.readFileSync(file, 'utf8');
+    }
+    catch {
+        return '';
+    }
+}
+/**
+ * Convert terminal native-harness logs into the existing untrusted LaneResult
+ * ingress. Reconciliation still owns identity checks, evidence sealing and
+ * every protocol gate.
+ */
+export function harvestHarnessObservation(assignmentId, cwd, persist = true) {
+    const assignment = loadAssignment(assignmentId, cwd);
+    const reservation = findReservationByAssignmentId(assignmentId, cwd);
+    const resolvedGeneration = reservation ? resolveTurnGenerationChain(cwd, reservation.turn_id) : undefined;
+    const generation = resolvedGeneration && (resolvedGeneration.status === 'active' || resolvedGeneration.status === 'settled')
+        ? resolvedGeneration.latest_generation
+        : undefined;
+    const generationContract = reservation && generation
+        ? executionContractForGeneration(reservation, generation)
+        : undefined;
+    const ref = generationContract?.ref ?? reservation?.execution_contract_ref;
+    const reservedHarness = reservation?.capability_snapshot?.resolved.harness;
+    const projectedHarness = assignment?.capability_snapshot?.resolved.harness;
+    if (reservedHarness && projectedHarness && JSON.stringify(reservedHarness) !== JSON.stringify(projectedHarness)) {
+        throw new Error(`assignment ${assignmentId} harness binding diverges from the authoritative reservation`);
+    }
+    const harness = reservedHarness ?? projectedHarness;
+    if (!assignment || !reservation || !ref || !harness || harness.adapter_id === 'prompt-only')
+        return undefined;
+    const signals = readCompletionSignals(cwd, assignmentId, generation?.run_id);
+    const terminal = signals.completed ?? signals.failed;
+    if (!terminal)
+        return undefined;
+    const stdoutLog = getRuntimeLogPath(cwd, assignmentId, 'stdout', generation?.run_id);
+    const stderrLog = getRuntimeLogPath(cwd, assignmentId, 'stderr', generation?.run_id);
+    const bothTerminalSignals = Boolean(signals.completed && signals.failed);
+    const observation = {
+        exit_code: bothTerminalSignals ? undefined : signals.completed ? 0 : 1,
+        stdout: readLog(stdoutLog),
+        stderr: readLog(stderrLog),
+        completed_at: terminal.at,
+    };
+    const claim = parseHarnessOutcome(harness.adapter_id, observation, harness.adapter_version);
+    claim.raw_output_refs = [stdoutLog, stderrLog];
+    if (reservation.execution_contract?.identity.kind === 'review'
+        && claim.status === 'completed'
+        && !claim.review_verdict) {
+        claim.status = 'partial';
+        claim.diagnostics.push({
+            kind: 'protocol', code: 'missing_review_verdict',
+            message: 'review result-claim v1 must carry review_verdict=approve|request_changes',
+        });
+    }
+    claim.artifact_type ??= reservation.expected_artifacts.find((item) => item.completion_policy === 'required')?.loop_artifact_type
+        ?? reservation.expected_artifacts[0]?.loop_artifact_type;
+    const protocolDiagnostics = claim.diagnostics.filter((item) => item.kind === 'protocol');
+    const protocolStatus = claim.status === 'partial'
+        ? 'partial'
+        : protocolDiagnostics.length > 0 ? 'invalid' : claim.body ? 'valid' : 'absent';
+    const ack = readContractAck(cwd, assignmentId, generation?.run_id);
+    const missingHash = '0'.repeat(64);
+    const runtimeObservation = {
+        contract_hash: terminal.contract_hash ?? missingHash,
+        capability_snapshot_hash: terminal.capability_snapshot_hash ?? missingHash,
+        adapter_id: harness.adapter_id,
+        adapter_version: harness.adapter_version,
+        observed_surfaces: ['cli'],
+        observed_model: claim.observed_model,
+        accepted_contract_hash: ack?.contract_hash,
+        accepted_capability_snapshot_hash: ack?.capability_snapshot_hash,
+    };
+    const activeRunId = generation?.run_id ?? reservation.child_ids.run_id;
+    const run = loadAgentRun(activeRunId, cwd);
+    if (run && persist) {
+        recordRuntimeCapabilityObservation(run.id, runtimeObservation, {
+            adapter_id: harness.adapter_id,
+            adapter_version: harness.adapter_version,
+            transport_status: bothTerminalSignals ? 'failed' : signals.completed ? 'completed' : 'failed',
+            protocol_status: protocolStatus,
+            message: claim.diagnostics.map((item) => `${item.code}: ${item.message}`).join('; ') || undefined,
+        }, cwd);
+    }
+    return {
+        lane: normalizeHarnessClaimToLaneResult(claim, {
+            assignment_id: assignmentId,
+            turn_id: reservation.turn_id,
+            run_id: activeRunId,
+            nonce: terminal.nonce,
+            attempt_epoch: terminal.attempt_epoch,
+            workspace_digest: terminal.workspace_digest,
+            execution_contract_hash: terminal.contract_hash,
+            capability_snapshot_hash: terminal.capability_snapshot_hash,
+        }),
+        stdout_log: stdoutLog,
+        stderr_log: stderrLog,
+    };
+}
+//# sourceMappingURL=harvest.js.map

package/dist/core/harness-adapters/index.js

@@ -0,0 +1,8 @@
+export * from './types.js';
+export * from './prompt-only.js';
+export * from './codex.js';
+export * from './claude.js';
+export * from './registry.js';
+export * from './result.js';
+export * from './harvest.js';
+//# sourceMappingURL=index.js.map

package/dist/core/harness-adapters/prompt-only.js

@@ -0,0 +1,13 @@
+import { buildProfileInvocation, declaredProbe, genericOutcome, resolveDeclaredBinding } from './base.js';
+export class PromptOnlyHarnessAdapter {
+    id = 'prompt-only';
+    version = '1';
+    matches() { return true; }
+    probe(agent, options) { return declaredProbe(this.id, this.version, agent, ['text'], options); }
+    resolve(agent, requestedModel, options) {
+        return resolveDeclaredBinding(this.probe(agent, options), requestedModel);
+    }
+    prepare = buildProfileInvocation;
+    parseOutcome = genericOutcome;
+}
+//# sourceMappingURL=prompt-only.js.map