deadbyte-mcp 0.8.7

package/src/agent-runtime.mjs

@@ -0,0 +1,874 @@
+import { randomBytes, sign as cryptoSign, verify as cryptoVerify } from 'node:crypto';
+import { access, mkdir, open, readFile, readdir, rename, rm, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { canonicalJson } from './canonical-json.mjs';
+import { executeContainedTransform, CONTAINED_TRANSFORM_OPERATIONS } from './contained-executor.mjs';
+import { executeProof } from './executor.mjs';
+import { sha256Bytes, sha256File } from './hash.mjs';
+import { resolveExistingInside, resolveWorkspace, validatePortableRelativePath } from './path-policy.mjs';
+import { runtimeIdentity } from './runtime-identity.mjs';
+import { loadPrivateSigningKey, loadPublicVerifyKey, signReceiptBytes, verifyReceiptBytes } from './trust.mjs';
+import { verifyReceipt } from './verifier.mjs';
+import { DEADBYTE_VERSION, MCP_PROTOCOL_VERSION } from './version.mjs';
+
+export const AGENT_PLAN_SCHEMA = 'deadbyte.agent-plan.v1';
+export const AGENT_EVENT_SCHEMA = 'deadbyte.agent-event.v1';
+export const AGENT_TASK_RECEIPT_SCHEMA = 'deadbyte.agent-task-receipt.v1';
+const AGENT_CANCEL_SCHEMA = 'deadbyte.agent-cancel.v1';
+export const AGENT_TASK_ID_RE = /^[0-9a-f]{64}$/;
+export const AGENT_STEP_ID_RE = /^[A-Za-z0-9._-]{1,48}$/;
+const SUBMISSION_ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+const ZERO_HASH = '0'.repeat(64);
+const MAX_STEPS = 32;
+const MAX_EVENTS = 512;
+const MAX_ERROR_CHARS = 2048;
+const EVENT_FILE_RE = /^(\d{6})\.json$/;
+const containedOperationSet = new Set(CONTAINED_TRANSFORM_OPERATIONS);
+const agentRuntimePath = fileURLToPath(import.meta.url);
+const AGENT_PLAN_SIGNATURE_DOMAIN = Buffer.from('DEADBYTE-AGENT-PLAN-V1\0', 'utf8');
+const AGENT_EVENT_SIGNATURE_DOMAIN = Buffer.from('DEADBYTE-AGENT-EVENT-V1\0', 'utf8');
+const AGENT_CANCEL_SIGNATURE_DOMAIN = Buffer.from('DEADBYTE-AGENT-CANCEL-V1\0', 'utf8');
+
+function sha256Object(value) {
+  return sha256Bytes(Buffer.from(canonicalJson(value), 'utf8'));
+}
+
+function signAgentEnvelope(signingKey, domain, body) {
+  const bytes = Buffer.from(canonicalJson(body), 'utf8');
+  const signature = cryptoSign(null, Buffer.concat([domain, bytes]), signingKey.privateKey);
+  return {
+    ...body,
+    attestation: {
+      algorithm: 'ed25519',
+      key_id: signingKey.keyId,
+      signature_base64: signature.toString('base64')
+    }
+  };
+}
+
+function verifyAgentEnvelope(verifyKey, domain, envelope, label) {
+  const { attestation, ...body } = envelope ?? {};
+  if (attestation?.algorithm !== 'ed25519' || attestation?.key_id !== verifyKey.keyId || typeof attestation?.signature_base64 !== 'string') {
+    throw new Error(`${label} signature metadata mismatch`);
+  }
+  const signature = Buffer.from(attestation.signature_base64, 'base64');
+  if (signature.length !== 64 || signature.toString('base64') !== attestation.signature_base64) {
+    throw new Error(`${label} signature encoding mismatch`);
+  }
+  const bytes = Buffer.from(canonicalJson(body), 'utf8');
+  if (!cryptoVerify(null, Buffer.concat([domain, bytes]), verifyKey.publicKey, signature)) {
+    throw new Error(`${label} signature verification failed`);
+  }
+  return body;
+}
+
+function taskIdFor(workspaceId, submissionId) {
+  return sha256Object({ schema: 'deadbyte.agent-submission.v1', workspace_id: workspaceId, submission_id: submissionId });
+}
+
+function receiptIdFor(taskId, stepId, attempt, planSha256) {
+  return sha256Object({ schema: 'deadbyte.agent-step-receipt-id.v1', task_id: taskId, step_id: stepId, attempt, plan_sha256: planSha256 }).slice(0, 24);
+}
+
+function truncateError(error) {
+  const text = error instanceof Error ? error.message : String(error);
+  return text.length <= MAX_ERROR_CHARS ? text : `${text.slice(0, MAX_ERROR_CHARS)}…`;
+}
+
+function exists(file) {
+  return access(file).then(() => true, () => false);
+}
+
+function taskRelative(taskId, suffix = '') {
+  return `.deadbyte-agent/tasks/${taskId}${suffix ? `/${suffix}` : ''}`;
+}
+
+function eventName(seq) {
+  return `${String(seq).padStart(6, '0')}.json`;
+}
+function normalizeInput(input, seenSteps) {
+  if (!input || typeof input !== 'object' || Array.isArray(input)) throw new Error('step input must be an object');
+  if (input.kind === 'workspace') {
+    validatePortableRelativePath(input.path);
+    return { kind: 'workspace', path: input.path };
+  }
+  if (input.kind === 'step_output') {
+    if (!AGENT_STEP_ID_RE.test(input.step_id ?? '') || !seenSteps.has(input.step_id)) {
+      throw new Error(`step input references unknown or future step '${String(input.step_id)}'`);
+    }
+    return { kind: 'step_output', step_id: input.step_id };
+  }
+  throw new Error('step input kind must be workspace or step_output');
+}
+
+function retryLimit(value) {
+  const n = value ?? 0;
+  if (!Number.isInteger(n) || n < 0 || n > 2) throw new Error('retry_limit must be an integer in [0, 2]');
+  return n;
+}
+
+export function normalizeAgentPlan({ workspaceId, submissionId, title = '', steps }) {
+  if (!/^[A-Za-z0-9._-]{1,64}$/.test(workspaceId ?? '')) throw new Error('invalid workspace_id');
+  if (!SUBMISSION_ID_RE.test(submissionId ?? '')) throw new Error('invalid submission_id');
+  if (typeof title !== 'string' || title.length > 120) throw new Error('title must be <=120 characters');
+  if (!Array.isArray(steps) || steps.length < 1 || steps.length > MAX_STEPS) throw new Error(`steps must contain 1-${MAX_STEPS} items`);
+
+  const seen = new Set();
+  const normalizedSteps = [];
+  for (const raw of steps) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('step must be an object');
+    if (!AGENT_STEP_ID_RE.test(raw.step_id ?? '')) throw new Error(`invalid step_id '${String(raw.step_id)}'`);
+    if (seen.has(raw.step_id)) throw new Error(`duplicate step_id '${raw.step_id}'`);
+
+    if (raw.kind === 'checkpoint') {
+      if (typeof raw.message !== 'string' || raw.message.length < 1 || raw.message.length > 512) {
+        throw new Error('checkpoint message must be 1-512 characters');
+      }
+      normalizedSteps.push({ step_id: raw.step_id, kind: 'checkpoint', message: raw.message, retry_limit: 0 });
+    } else if (raw.kind === 'proof_execute') {
+      normalizedSteps.push({
+        step_id: raw.step_id,
+        kind: 'proof_execute',
+        input: normalizeInput(raw.input, seen),
+        retry_limit: retryLimit(raw.retry_limit)
+      });
+    } else if (raw.kind === 'contained_transform') {
+      if (!containedOperationSet.has(raw.operation)) throw new Error(`unsupported contained operation '${String(raw.operation)}'`);
+      normalizedSteps.push({
+        step_id: raw.step_id,
+        kind: 'contained_transform',
+        operation: raw.operation,
+        input: normalizeInput(raw.input, seen),
+        retry_limit: retryLimit(raw.retry_limit)
+      });
+    } else {
+      throw new Error(`unsupported agent step kind '${String(raw.kind)}'`);
+    }
+    seen.add(raw.step_id);
+  }
+  const body = {
+    schema: AGENT_PLAN_SCHEMA,
+    workspace_id: workspaceId,
+    submission_id: submissionId,
+    title,
+    steps: normalizedSteps
+  };
+  return Object.freeze({ ...body, plan_sha256: sha256Object(body) });
+}
+
+async function workspaceContext(workspacePath, taskId = null, auth = {}) {
+  const rootReal = await resolveWorkspace(workspacePath);
+  const agentRoot = path.join(rootReal, '.deadbyte-agent');
+  const tasksRoot = path.join(agentRoot, 'tasks');
+  const common = {
+    rootReal,
+    agentRoot,
+    tasksRoot,
+    signingKeyPath: auth.signingKeyPath ?? null,
+    verifyKeyPath: auth.verifyKeyPath ?? null
+  };
+  await mkdir(tasksRoot, { recursive: true });
+  if (!taskId) return common;
+  if (!AGENT_TASK_ID_RE.test(taskId)) throw new Error('invalid task_id');
+  const taskDir = path.join(tasksRoot, taskId);
+  return {
+    ...common,
+    taskDir,
+    planPath: path.join(taskDir, 'plan.json'),
+    eventsDir: path.join(taskDir, 'events'),
+    outputsDir: path.join(taskDir, 'outputs'),
+    lockPath: path.join(taskDir, 'run.lock.json'),
+    cancelPath: path.join(taskDir, 'cancel.request.json'),
+    taskReceiptPath: path.join(taskDir, 'task-receipt.json')
+  };
+}
+async function loadPlan(ctx) {
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(ctx.planPath, 'utf8'));
+  } catch (error) {
+    throw new Error(`agent task plan unavailable: ${error?.code ?? truncateError(error)}`);
+  }
+  if (!parsed || parsed.schema !== AGENT_PLAN_SCHEMA || !AGENT_TASK_ID_RE.test(parsed.task_id ?? '')) {
+    throw new Error('agent task plan schema mismatch');
+  }
+  const verifyKey = await loadPublicVerifyKey(ctx.verifyKeyPath);
+  const signed = verifyAgentEnvelope(verifyKey, AGENT_PLAN_SIGNATURE_DOMAIN, parsed, 'agent plan');
+  const { task_id: taskId, plan_sha256: claimed, ...body } = signed;
+  if (taskId !== path.basename(ctx.taskDir)) throw new Error('agent task id/path mismatch');
+  if (!/^[0-9a-f]{64}$/.test(claimed ?? '') || sha256Object(body) !== claimed) throw new Error('agent task plan hash mismatch');
+  return parsed;
+}
+
+async function readEvents(ctx) {
+  let names;
+  try { names = await readdir(ctx.eventsDir); } catch (error) { throw new Error(`agent event directory unavailable: ${error?.code ?? truncateError(error)}`); }
+  const numbered = names.filter(name => EVENT_FILE_RE.test(name)).sort();
+  if (numbered.length > MAX_EVENTS) throw new Error(`agent event journal exceeds ${MAX_EVENTS} events`);
+  const events = [];
+  const verifyKey = await loadPublicVerifyKey(ctx.verifyKeyPath);
+  let previous = ZERO_HASH;
+  for (let i = 0; i < numbered.length; i += 1) {
+    const expectedName = eventName(i + 1);
+    if (numbered[i] !== expectedName) throw new Error(`agent event sequence gap at ${expectedName}`);
+    const event = JSON.parse(await readFile(path.join(ctx.eventsDir, numbered[i]), 'utf8'));
+    const signed = verifyAgentEnvelope(verifyKey, AGENT_EVENT_SIGNATURE_DOMAIN, event, 'agent event');
+    if (signed.schema !== AGENT_EVENT_SCHEMA || signed.seq !== i + 1 || signed.task_id !== path.basename(ctx.taskDir)) throw new Error(`agent event ${expectedName} identity mismatch`);
+    const { event_sha256: claimed, ...body } = signed;
+    if (!/^[0-9a-f]{64}$/.test(claimed ?? '') || body.prev_sha256 !== previous || sha256Object(body) !== claimed) throw new Error(`agent event ${expectedName} hash-chain mismatch`);
+    events.push(event);
+    previous = claimed;
+  }
+  return events;
+}
+async function appendEvent(ctx, events, type, { stepId = undefined, payload = {} } = {}) {
+  if (events.length >= MAX_EVENTS) throw new Error(`agent event journal exceeds ${MAX_EVENTS} events`);
+  const seq = events.length + 1;
+  const body = {
+    schema: AGENT_EVENT_SCHEMA,
+    seq,
+    task_id: path.basename(ctx.taskDir),
+    created_at_utc: new Date().toISOString(),
+    prev_sha256: events.at(-1)?.event_sha256 ?? ZERO_HASH,
+    type,
+    ...(stepId === undefined ? {} : { step_id: stepId }),
+    payload
+  };
+  const signedBody = { ...body, event_sha256: sha256Object(body) };
+  const signingKey = await loadPrivateSigningKey(ctx.signingKeyPath);
+  const event = signAgentEnvelope(signingKey, AGENT_EVENT_SIGNATURE_DOMAIN, signedBody);
+  const finalPath = path.join(ctx.eventsDir, eventName(seq));
+  const tempPath = `${finalPath}.${process.pid}.${randomBytes(6).toString('hex')}.tmp`;
+  await writeFile(tempPath, `${canonicalJson(event)}\n`, { flag: 'wx' });
+  await rename(tempPath, finalPath);
+  events.push(event);
+  return event;
+}
+
+function deriveTaskState(plan, events) {
+  const steps = new Map(plan.steps.map(step => [step.step_id, {
+    step_id: step.step_id,
+    kind: step.kind,
+    state: 'pending',
+    attempts: 0,
+    result: null,
+    error: null
+  }]));
+  let state = 'pending';
+  let reason = null;
+  let activeStepId = null;
+  for (const event of events) {
+    const step = event.step_id ? steps.get(event.step_id) : null;
+    if (event.type === 'run_started' && !['succeeded', 'failed', 'cancelled'].includes(state)) state = 'running';
+    if (event.type === 'step_started' && step) {
+      step.state = 'running';
+      step.attempts = Math.max(step.attempts, Number(event.payload?.attempt ?? 0));
+      step.output_path = event.payload?.output_path ?? null;
+      step.receipt_path = event.payload?.receipt_path ?? null;
+      step.error = null;
+      activeStepId = step.step_id;
+      state = 'running';
+    }
+    if (['step_failed', 'step_interrupted_no_effect'].includes(event.type) && step) {
+      step.state = 'pending';
+      step.error = event.payload?.error ?? event.type;
+      activeStepId = null;
+      state = 'running';
+    }
+    if (event.type === 'step_succeeded' && step) {
+      step.state = 'succeeded';
+      step.result = event.payload ?? {};
+      step.error = null;
+      activeStepId = null;
+      if (!['failed', 'cancelled'].includes(state)) state = 'running';
+    }
+    if (event.type === 'checkpoint_waiting' && step) {
+      step.state = 'waiting_approval';
+      activeStepId = step.step_id;
+      state = 'paused';
+      reason = 'checkpoint';
+    }
+    if (event.type === 'checkpoint_approved' && step) {
+      step.state = 'succeeded';
+      step.result = { decision: event.payload?.decision ?? 'approve' };
+      activeStepId = null;
+      state = 'running';
+      reason = null;
+    }
+    if (event.type === 'task_paused') {
+      state = 'paused';
+      reason = event.payload?.reason ?? 'paused';
+    }
+    if (event.type === 'task_failed') {
+      state = 'failed';
+      reason = event.payload?.reason ?? 'step_failed';
+      activeStepId = null;
+    }
+    if (event.type === 'task_cancelled') {
+      state = 'cancelled';
+      reason = event.payload?.reason ?? 'cancelled';
+      activeStepId = null;
+    }
+    if (event.type === 'task_completed') {
+      state = 'succeeded';
+      reason = null;
+      activeStepId = null;
+    }
+  }
+  if (events.length === 1 && events[0]?.type === 'task_created') state = 'pending';
+  const list = plan.steps.map(step => ({ ...steps.get(step.step_id) }));
+  return {
+    state,
+    reason,
+    active_step_id: activeStepId,
+    steps: list,
+    completed_steps: list.filter(step => step.state === 'succeeded').length,
+    journal_head_sha256: events.at(-1)?.event_sha256 ?? ZERO_HASH
+  };
+}
+
+async function readCancelRequest(ctx) {
+  if (!await exists(ctx.cancelPath)) return null;
+  let parsed;
+  try {
+    parsed = JSON.parse(await readFile(ctx.cancelPath, 'utf8'));
+  } catch {
+    throw new Error('agent cancel request malformed');
+  }
+  const verifyKey = await loadPublicVerifyKey(ctx.verifyKeyPath);
+  const signed = verifyAgentEnvelope(verifyKey, AGENT_CANCEL_SIGNATURE_DOMAIN, parsed, 'agent cancel request');
+  if (signed.schema !== AGENT_CANCEL_SCHEMA || signed.task_id !== path.basename(ctx.taskDir)) {
+    throw new Error('agent cancel request identity mismatch');
+  }
+  if (typeof signed.reason !== 'string' || signed.reason.length < 1 || signed.reason.length > 256) {
+    throw new Error('agent cancel request reason invalid');
+  }
+  return signed;
+}
+
+async function consumeCancelRequest(ctx, events) {
+  const request = await readCancelRequest(ctx);
+  if (!request) return null;
+  await appendEvent(ctx, events, 'task_cancelled', {
+    payload: { reason: request.reason, requested_at_utc: request.requested_at_utc }
+  });
+  await rm(ctx.cancelPath, { force: true }).catch(() => {});
+  return request;
+}
+
+async function processExists(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch { return false; }
+}
+async function acquireTaskLock(ctx) {
+  const runtime = await runtimeIdentity();
+  for (let pass = 0; pass < 2; pass += 1) {
+    let handle;
+    try {
+      handle = await open(ctx.lockPath, 'wx', 0o600);
+      const lock = {
+        schema: 'deadbyte.agent-lock.v1',
+        task_id: path.basename(ctx.taskDir),
+        pid: process.pid,
+        runtime_instance_nonce: runtime.instance_nonce,
+        created_at_utc: new Date().toISOString()
+      };
+      await handle.writeFile(`${canonicalJson(lock)}\n`);
+      await handle.close();
+      return lock;
+    } catch (error) {
+      if (handle) await handle.close().catch(() => {});
+      if (error?.code !== 'EEXIST') throw error;
+      let existing;
+      try { existing = JSON.parse(await readFile(ctx.lockPath, 'utf8')); } catch { throw new Error('agent task lock is malformed; refusing mutation'); }
+      if (await processExists(existing?.pid)) throw new Error(`agent task is busy under pid ${existing.pid}`);
+      await rm(ctx.lockPath, { force: true });
+    }
+  }
+  throw new Error('agent task lock acquisition failed');
+}
+
+async function releaseTaskLock(ctx) {
+  await rm(ctx.lockPath, { force: true });
+}
+
+async function resolveStepInput(rootReal, step, derived) {
+  if (step.input.kind === 'workspace') {
+    await resolveExistingInside(rootReal, step.input.path);
+    return step.input.path;
+  }
+  const source = derived.steps.find(candidate => candidate.step_id === step.input.step_id);
+  if (!source || source.state !== 'succeeded' || typeof source.result?.output_path !== 'string') {
+    throw new Error(`step '${step.step_id}' input dependency '${step.input.step_id}' has no successful output`);
+  }
+  await resolveExistingInside(rootReal, source.result.output_path);
+  return source.result.output_path;
+}
+async function verifiedStepResult(ctx, step, attempt, outputPath, receiptPath, verifyKeyPath, verifyReceiptFn) {
+  const outputAbs = path.join(ctx.rootReal, ...outputPath.split('/'));
+  const receiptAbs = path.join(ctx.rootReal, ...receiptPath.split('/'));
+  const outputExists = await exists(outputAbs);
+  const receiptExists = await exists(receiptAbs);
+  if (!outputExists && !receiptExists) return { kind: 'none' };
+  if (!receiptExists) return { kind: 'orphan_output', reason: 'output exists without signed receipt' };
+
+  const checked = await verifyReceiptFn({ workspacePath: ctx.rootReal, receiptPath, verifyKeyPath });
+  if (checked?.ok !== true) return { kind: 'invalid_receipt', reason: checked?.reason ?? 'receipt verification failed' };
+  let receipt;
+  try { receipt = JSON.parse(await readFile(receiptAbs, 'utf8')); } catch { return { kind: 'invalid_receipt', reason: 'receipt JSON unreadable' }; }
+  const expectedOperation = step.kind === 'proof_execute' ? 'proof_execute' : 'contained_transform';
+  if (receipt.operation !== expectedOperation || receipt.output?.path !== outputPath) {
+    return { kind: 'invalid_receipt', reason: 'receipt operation/output binding mismatch' };
+  }
+  if (step.kind === 'contained_transform' && receipt.execution?.operation !== step.operation) {
+    return { kind: 'invalid_receipt', reason: 'receipt contained operation mismatch' };
+  }
+  return {
+    kind: 'verified',
+    payload: {
+      attempt,
+      kind: step.kind,
+      ...(step.operation ? { operation: step.operation } : {}),
+      output_path: outputPath,
+      output_sha256: checked.output_sha256,
+      receipt_path: receiptPath,
+      receipt_sha256: checked.receipt_sha256,
+      request_sha256: checked.request_sha256,
+      recovered: true
+    }
+  };
+}
+async function createTaskReceipt(ctx, plan, events, derived, signingKeyPath) {
+  if (await exists(ctx.taskReceiptPath)) throw new Error('task receipt already exists');
+  const signingKey = await loadPrivateSigningKey(signingKeyPath);
+  const stepReceipts = derived.steps
+    .filter(step => step.kind !== 'checkpoint' && step.state === 'succeeded')
+    .map(step => ({
+      step_id: step.step_id,
+      kind: step.kind,
+      ...(step.result?.operation ? { operation: step.result.operation } : {}),
+      output_path: step.result?.output_path,
+      output_sha256: step.result?.output_sha256,
+      receipt_path: step.result?.receipt_path,
+      receipt_sha256: step.result?.receipt_sha256,
+      request_sha256: step.result?.request_sha256
+    }));
+  const checkpoints = derived.steps
+    .filter(step => step.kind === 'checkpoint' && step.state === 'succeeded')
+    .map(step => ({ step_id: step.step_id, decision: step.result?.decision ?? 'approve' }));
+  const body = {
+    schema: AGENT_TASK_RECEIPT_SCHEMA,
+    task_id: plan.task_id,
+    plan_sha256: plan.plan_sha256,
+    event_head_sha256: derived.journal_head_sha256,
+    created_at_utc: events[0]?.created_at_utc,
+    completed_at_utc: new Date().toISOString(),
+    package_version: DEADBYTE_VERSION,
+    mcp_protocol_version: MCP_PROTOCOL_VERSION,
+    agent_runtime_sha256: await sha256File(agentRuntimePath),
+    runtime: await runtimeIdentity(),
+    step_receipts: stepReceipts,
+    checkpoints
+  };
+  const receiptSha256 = sha256Object(body);
+  const signedBody = { ...body, receipt_sha256: receiptSha256 };
+  const signature = signReceiptBytes(signingKey.privateKey, Buffer.from(canonicalJson(signedBody), 'utf8'));
+  const receipt = {
+    ...signedBody,
+    attestation: {
+      algorithm: 'ed25519',
+      key_id: signingKey.keyId,
+      signature_base64: signature.toString('base64')
+    }
+  };
+  await writeFile(ctx.taskReceiptPath, `${canonicalJson(receipt)}\n`, { flag: 'wx' });
+  return receipt;
+}
+
+async function verifyTaskReceiptEnvelope(receipt, plan, derived, verifyKeyPath) {
+  if (receipt.schema !== AGENT_TASK_RECEIPT_SCHEMA || receipt.task_id !== plan.task_id || receipt.plan_sha256 !== plan.plan_sha256) {
+    return { ok: false, reason: 'task receipt identity mismatch' };
+  }
+  if (receipt.event_head_sha256 !== derived.journal_head_sha256) return { ok: false, reason: 'task receipt event-head mismatch' };
+  if (receipt.package_version !== DEADBYTE_VERSION || receipt.mcp_protocol_version !== MCP_PROTOCOL_VERSION) {
+    return { ok: false, reason: 'task receipt runtime version mismatch' };
+  }
+  if (receipt.agent_runtime_sha256 !== await sha256File(agentRuntimePath)) return { ok: false, reason: 'task receipt agent runtime hash mismatch' };
+  const currentRuntime = await runtimeIdentity();
+  if (receipt.runtime?.mcp_server_sha256 !== currentRuntime.mcp_server_sha256 ||
+      receipt.runtime?.mcp_protocol_version !== MCP_PROTOCOL_VERSION || receipt.runtime?.package_version !== DEADBYTE_VERSION) {
+    return { ok: false, reason: 'task receipt runtime identity mismatch' };
+  }
+  const verifyKey = await loadPublicVerifyKey(verifyKeyPath);
+  if (receipt.attestation?.algorithm !== 'ed25519' || receipt.attestation?.key_id !== verifyKey.keyId) {
+    return { ok: false, reason: 'task receipt attestation mismatch' };
+  }  const { attestation, receipt_sha256: claimed, ...body } = receipt;
+  if (!/^[0-9a-f]{64}$/.test(claimed ?? '') || sha256Object(body) !== claimed) return { ok: false, reason: 'task receipt hash mismatch' };
+  const signature = Buffer.from(attestation.signature_base64 ?? '', 'base64');
+  if (!verifyReceiptBytes(verifyKey.publicKey, Buffer.from(canonicalJson({ ...body, receipt_sha256: claimed }), 'utf8'), signature)) {
+    return { ok: false, reason: 'task receipt signature mismatch' };
+  }
+  const expectedSteps = derived.steps.filter(step => step.kind !== 'checkpoint' && step.state === 'succeeded');
+  if (!Array.isArray(receipt.step_receipts) || receipt.step_receipts.length !== expectedSteps.length) return { ok: false, reason: 'task receipt step count mismatch' };
+  for (const step of expectedSteps) {
+    const bound = receipt.step_receipts.find(item => item.step_id === step.step_id);
+    if (!bound || bound.kind !== step.kind || bound.receipt_path !== step.result?.receipt_path ||
+        bound.receipt_sha256 !== step.result?.receipt_sha256 || bound.request_sha256 !== step.result?.request_sha256 ||
+        bound.output_sha256 !== step.result?.output_sha256 || bound.output_path !== step.result?.output_path ||
+        (step.result?.operation ?? null) !== (bound.operation ?? null)) {
+      return { ok: false, reason: `task receipt step binding mismatch for '${step.step_id}'` };
+    }
+  }
+  const expectedCheckpoints = derived.steps.filter(step => step.kind === 'checkpoint' && step.state === 'succeeded')
+    .map(step => ({ step_id: step.step_id, decision: step.result?.decision ?? 'approve' }));
+  if (canonicalJson(receipt.checkpoints ?? []) !== canonicalJson(expectedCheckpoints)) return { ok: false, reason: 'task receipt checkpoint binding mismatch' };
+  return { ok: true, receipt_sha256: claimed };
+}
+
+async function verifyTaskReceipt(ctx, plan, events, verifyKeyPath, verifyReceiptFn) {
+  if (events.at(-1)?.type !== 'task_completed') return { ok: false, reason: 'task is not completed' };
+  let receipt;
+  try { receipt = JSON.parse(await readFile(ctx.taskReceiptPath, 'utf8')); } catch { return { ok: false, reason: 'task receipt missing or unreadable' }; }
+  const completion = events.at(-1);
+  const derived = deriveTaskState(plan, events.slice(0, -1));
+  const envelope = await verifyTaskReceiptEnvelope(receipt, plan, derived, verifyKeyPath);
+  if (!envelope.ok) return envelope;
+  if (receipt.event_head_sha256 !== completion.prev_sha256 || completion.payload?.task_receipt_sha256 !== envelope.receipt_sha256) {
+    return { ok: false, reason: 'task receipt/event-head binding mismatch' };
+  }  let verifiedCount = 0;
+  for (const step of derived.steps.filter(item => item.kind !== 'checkpoint' && item.state === 'succeeded')) {
+    const bound = receipt.step_receipts.find(item => item.step_id === step.step_id);
+    const checked = await verifyReceiptFn({ workspacePath: ctx.rootReal, receiptPath: bound.receipt_path, verifyKeyPath });
+    if (checked?.ok !== true || checked.receipt_sha256 !== bound.receipt_sha256 || checked.output_sha256 !== bound.output_sha256 ||
+        checked.request_sha256 !== bound.request_sha256) {
+      return { ok: false, reason: `underlying step receipt verification failed for '${step.step_id}'` };
+    }
+    verifiedCount += 1;
+  }
+  return {
+    ok: true,
+    task_id: plan.task_id,
+    plan_sha256: plan.plan_sha256,
+    task_receipt_sha256: envelope.receipt_sha256,
+    signature_valid: true,
+    journal_head_sha256: completion.event_sha256,
+    step_receipts_verified: verifiedCount
+  };
+}
+async function reconcileInterrupted(ctx, plan, events, derived, verifyKeyPath, verifyReceiptFn) {
+  if (!derived.active_step_id) return derived;
+  const planStep = plan.steps.find(step => step.step_id === derived.active_step_id);
+  const stateStep = derived.steps.find(step => step.step_id === derived.active_step_id);
+  if (!planStep || !stateStep || stateStep.state !== 'running') return derived;
+  const verdict = await verifiedStepResult(
+    ctx,
+    planStep,
+    stateStep.attempts,
+    stateStep.output_path,
+    stateStep.receipt_path,
+    verifyKeyPath,
+    verifyReceiptFn
+  );
+  if (verdict.kind === 'verified') {
+    await appendEvent(ctx, events, 'step_succeeded', { stepId: planStep.step_id, payload: verdict.payload });
+  } else if (verdict.kind === 'none') {
+    await appendEvent(ctx, events, 'step_interrupted_no_effect', {
+      stepId: planStep.step_id,
+      payload: { attempt: stateStep.attempts, error: 'previous runtime ended before observable side effect' }
+    });
+  } else {
+    await appendEvent(ctx, events, 'task_paused', {
+      stepId: planStep.step_id,
+      payload: { reason: `interrupted_${verdict.kind}`, detail: verdict.reason }
+    });
+  }
+  return deriveTaskState(plan, events);
+}
+
+async function completeTask(ctx, plan, events, derived, signingKeyPath, verifyKeyPath) {
+  if (derived.completed_steps !== plan.steps.length) return derived;
+  let receipt;
+  if (await exists(ctx.taskReceiptPath)) {
+    try { receipt = JSON.parse(await readFile(ctx.taskReceiptPath, 'utf8')); }
+    catch {
+      await appendEvent(ctx, events, 'task_paused', { payload: { reason: 'existing_task_receipt_unreadable' } });
+      return deriveTaskState(plan, events);
+    }
+  } else {
+    receipt = await createTaskReceipt(ctx, plan, events, derived, signingKeyPath);
+  }
+  const envelope = await verifyTaskReceiptEnvelope(receipt, plan, derived, verifyKeyPath);
+  if (!envelope.ok) {
+    await appendEvent(ctx, events, 'task_paused', { payload: { reason: `existing_task_receipt_${envelope.reason}` } });
+    return deriveTaskState(plan, events);
+  }
+  await appendEvent(ctx, events, 'task_completed', { payload: { task_receipt_sha256: envelope.receipt_sha256 } });
+  return deriveTaskState(plan, events);
+}
+export function createAgentRuntime({
+  signingKeyPath,
+  verifyKeyPath,
+  executeProofFn = executeProof,
+  executeContainedTransformFn = executeContainedTransform,
+  verifyReceiptFn = verifyReceipt
+}) {
+  if (!signingKeyPath) throw new Error('agent runtime requires signing key path');
+  if (!verifyKeyPath) throw new Error('agent runtime requires verify key path');
+  const auth = Object.freeze({ signingKeyPath, verifyKeyPath });
+
+  async function submit({ workspacePath, workspaceId, submissionId, title = '', steps }) {
+    const base = await workspaceContext(workspacePath, null, auth);
+    const normalized = normalizeAgentPlan({ workspaceId, submissionId, title, steps });
+    const taskId = taskIdFor(workspaceId, submissionId);
+    const ctx = await workspaceContext(base.rootReal, taskId, auth);
+    const signingKey = await loadPrivateSigningKey(signingKeyPath);
+    const storedPlan = signAgentEnvelope(signingKey, AGENT_PLAN_SIGNATURE_DOMAIN, { ...normalized, task_id: taskId });
+
+    if (await exists(ctx.taskDir)) {
+      const existing = await loadPlan(ctx);
+      if (existing.plan_sha256 !== normalized.plan_sha256) throw new Error('submission_id already exists with a different plan');
+      return { status: 'existing', task_id: taskId, plan_sha256: existing.plan_sha256, state: deriveTaskState(existing, await readEvents(ctx)).state };
+    }
+
+    await mkdir(ctx.taskDir);
+    await mkdir(ctx.eventsDir);
+    await mkdir(ctx.outputsDir);
+    await writeFile(ctx.planPath, `${canonicalJson(storedPlan)}\n`, { flag: 'wx' });
+    const events = [];
+    await appendEvent(ctx, events, 'task_created', {
+      payload: { plan_sha256: normalized.plan_sha256, submission_id: submissionId, title, step_count: normalized.steps.length }
+    });
+    return { status: 'accepted', task_id: taskId, plan_sha256: normalized.plan_sha256, state: 'pending' };
+  }
+  async function status({ workspacePath, taskId }) {
+    const ctx = await workspaceContext(workspacePath, taskId, auth);
+    const plan = await loadPlan(ctx);
+    const events = await readEvents(ctx);
+    const derived = deriveTaskState(plan, events);
+    return {
+      status: 'ok',
+      task_id: taskId,
+      plan_sha256: plan.plan_sha256,
+      ...derived,
+      journal_verified: true
+    };
+  }
+
+  async function events({ workspacePath, taskId, fromSeq = 1, limit = 100 }) {
+    if (!Number.isInteger(fromSeq) || fromSeq < 1) throw new Error('from_seq must be an integer >=1');
+    if (!Number.isInteger(limit) || limit < 1 || limit > 200) throw new Error('limit must be an integer in [1, 200]');
+    const ctx = await workspaceContext(workspacePath, taskId, auth);
+    const plan = await loadPlan(ctx);
+    const all = await readEvents(ctx);
+    return {
+      status: 'ok', task_id: taskId, plan_sha256: plan.plan_sha256,
+      journal_verified: true, journal_head_sha256: all.at(-1)?.event_sha256 ?? ZERO_HASH,
+      events: all.slice(fromSeq - 1, fromSeq - 1 + limit)
+    };
+  }
+  async function cancel({ workspacePath, taskId, reason = 'operator_request' }) {
+    if (typeof reason !== 'string' || reason.length < 1 || reason.length > 256) throw new Error('cancel reason must be 1-256 characters');
+    const ctx = await workspaceContext(workspacePath, taskId, auth);
+    const plan = await loadPlan(ctx);
+    const current = deriveTaskState(plan, await readEvents(ctx));
+    if (['succeeded', 'failed', 'cancelled'].includes(current.state)) {
+      return { status: 'terminal', task_id: taskId, state: current.state };
+    }
+    const signingKey = await loadPrivateSigningKey(signingKeyPath);
+    const request = signAgentEnvelope(signingKey, AGENT_CANCEL_SIGNATURE_DOMAIN, {
+      schema: AGENT_CANCEL_SCHEMA, task_id: taskId,
+      requested_at_utc: new Date().toISOString(), reason
+    });
+    try {
+      await writeFile(ctx.cancelPath, `${canonicalJson(request)}\n`, { flag: 'wx' });
+      return { status: 'requested', task_id: taskId, state: current.state };
+    } catch (error) {
+      if (error?.code !== 'EEXIST') throw error;
+      return { status: 'existing', task_id: taskId, state: current.state };
+    }
+  }
+
+  async function approve({ workspacePath, taskId, stepId, decision = 'approve' }) {
+    if (!AGENT_STEP_ID_RE.test(stepId ?? '')) throw new Error('invalid step_id');
+    if (!['approve', 'reject'].includes(decision)) throw new Error('decision must be approve or reject');
+    const ctx = await workspaceContext(workspacePath, taskId, auth);
+    await acquireTaskLock(ctx);
+    try {
+      const plan = await loadPlan(ctx);
+      const journal = await readEvents(ctx);
+      const derived = deriveTaskState(plan, journal);
+      const step = derived.steps.find(item => item.step_id === stepId);
+      if (!step || step.kind !== 'checkpoint') throw new Error(`checkpoint '${stepId}' not found`);
+      if (step.state === 'succeeded') return { status: 'existing', task_id: taskId, step_id: stepId, state: derived.state };
+      if (step.state !== 'waiting_approval') throw new Error(`checkpoint '${stepId}' is not waiting for approval`);
+      if (decision === 'reject') {
+        await appendEvent(ctx, journal, 'checkpoint_rejected', { stepId, payload: { decision } });
+        await appendEvent(ctx, journal, 'task_cancelled', { stepId, payload: { reason: 'checkpoint_rejected' } });
+      } else {
+        await appendEvent(ctx, journal, 'checkpoint_approved', { stepId, payload: { decision } });
+      }
+      const after = deriveTaskState(plan, journal);
+      return { status: decision === 'approve' ? 'approved' : 'rejected', task_id: taskId, step_id: stepId, ...after };
+    } finally {
+      await releaseTaskLock(ctx);
+    }
+  }
+
+  async function verify({ workspacePath, taskId }) {
+    const ctx = await workspaceContext(workspacePath, taskId, auth);
+    const plan = await loadPlan(ctx);
+    const journal = await readEvents(ctx);
+    return verifyTaskReceipt(ctx, plan, journal, verifyKeyPath, verifyReceiptFn);
+  }
+
+  function stepAttemptPaths(plan, step, attempt) {
+    const receiptId = receiptIdFor(plan.task_id, step.step_id, attempt, plan.plan_sha256);
+    return {
+      receipt_id: receiptId,
+      receipt_path: `evidence/${receiptId}.json`,
+      output_path: taskRelative(plan.task_id, `outputs/${step.step_id}.attempt-${attempt}.bin`)
+    };
+  }
+
+  async function executeStep(ctx, plan, step, stateStep, inputPath, paths) {
+    const common = {
+      workspacePath: ctx.rootReal,
+      input: inputPath,
+      output: paths.output_path,
+      signingKeyPath,
+      receiptId: paths.receipt_id
+    };
+    if (step.kind === 'proof_execute') return executeProofFn(common);
+    if (step.kind === 'contained_transform') {
+      return executeContainedTransformFn({ ...common, operation: step.operation });
+    }
+    throw new Error(`step '${step.step_id}' is not executable`);
+  }
+
+  async function run({ workspacePath, taskId, maxSteps = 8 }) {
+    if (!Number.isInteger(maxSteps) || maxSteps < 1 || maxSteps > MAX_STEPS) throw new Error(`max_steps must be an integer in [1, ${MAX_STEPS}]`);
+    const ctx = await workspaceContext(workspacePath, taskId, auth);
+    await acquireTaskLock(ctx);
+    try {
+      const plan = await loadPlan(ctx);
+      const journal = await readEvents(ctx);
+      let derived = deriveTaskState(plan, journal);
+      if (['succeeded', 'failed', 'cancelled'].includes(derived.state)) {
+        return { status: 'terminal', task_id: taskId, ...derived };
+      }
+      derived = await reconcileInterrupted(ctx, plan, journal, derived, verifyKeyPath, verifyReceiptFn);
+      if (derived.state === 'paused' && derived.reason !== 'checkpoint') {
+        return { status: 'paused', task_id: taskId, ...derived };
+      }
+      if (derived.completed_steps === plan.steps.length) {
+        derived = await completeTask(ctx, plan, journal, derived, signingKeyPath, verifyKeyPath);
+        return { status: derived.state === 'succeeded' ? 'completed' : derived.state, task_id: taskId, ...derived };
+      }
+      if (await consumeCancelRequest(ctx, journal)) {
+        derived = deriveTaskState(plan, journal);
+        return { status: 'cancelled', task_id: taskId, ...derived };
+      }
+      await appendEvent(ctx, journal, 'run_started', { payload: { max_steps: maxSteps } });
+      derived = deriveTaskState(plan, journal);
+
+      let consumed = 0;
+      while (consumed < maxSteps) {
+        if (await consumeCancelRequest(ctx, journal)) {
+          derived = deriveTaskState(plan, journal);
+          return { status: 'cancelled', task_id: taskId, ...derived };
+        }
+
+        const next = plan.steps.find(step => derived.steps.find(item => item.step_id === step.step_id)?.state !== 'succeeded');
+        if (!next) {
+          derived = await completeTask(ctx, plan, journal, derived, signingKeyPath, verifyKeyPath);
+          return { status: derived.state === 'succeeded' ? 'completed' : derived.state, task_id: taskId, ...derived };
+        }
+        const stateStep = derived.steps.find(item => item.step_id === next.step_id);
+        if (next.kind === 'checkpoint') {
+          if (stateStep.state === 'waiting_approval') {
+            return { status: 'paused', task_id: taskId, ...derived };
+          }
+          await appendEvent(ctx, journal, 'checkpoint_waiting', {
+            stepId: next.step_id,
+            payload: { message: next.message }
+          });
+          derived = deriveTaskState(plan, journal);
+          return { status: 'paused', task_id: taskId, ...derived };
+        }
+
+        const attempt = stateStep.attempts + 1;
+        const paths = stepAttemptPaths(plan, next, attempt);
+        const inputPath = await resolveStepInput(ctx.rootReal, next, derived);
+        await appendEvent(ctx, journal, 'step_started', {
+          stepId: next.step_id,
+          payload: {
+            attempt,
+            input_path: inputPath,
+            output_path: paths.output_path,
+            receipt_path: paths.receipt_path
+          }
+        });
+        derived = deriveTaskState(plan, journal);
+        consumed += 1;
+
+        try {
+          await executeStep(ctx, plan, next, stateStep, inputPath, paths);
+          const verdict = await verifiedStepResult(
+            ctx, next, attempt, paths.output_path, paths.receipt_path,
+            verifyKeyPath, verifyReceiptFn
+          );
+          if (verdict.kind !== 'verified') {
+            await appendEvent(ctx, journal, 'task_paused', {
+              stepId: next.step_id,
+              payload: { reason: `post_execute_${verdict.kind}`, detail: verdict.reason ?? 'missing evidence' }
+            });
+            derived = deriveTaskState(plan, journal);
+            return { status: 'paused', task_id: taskId, ...derived };
+          }
+          await appendEvent(ctx, journal, 'step_succeeded', {
+            stepId: next.step_id,
+            payload: { ...verdict.payload, recovered: false }
+          });
+          derived = deriveTaskState(plan, journal);
+        } catch (error) {
+          const verdict = await verifiedStepResult(
+            ctx, next, attempt, paths.output_path, paths.receipt_path,
+            verifyKeyPath, verifyReceiptFn
+          );
+          if (verdict.kind === 'verified') {
+            await appendEvent(ctx, journal, 'step_succeeded', { stepId: next.step_id, payload: verdict.payload });
+            derived = deriveTaskState(plan, journal);
+            continue;
+          }
+          if (verdict.kind !== 'none') {
+            await appendEvent(ctx, journal, 'task_paused', {
+              stepId: next.step_id,
+              payload: { reason: `execution_${verdict.kind}`, detail: verdict.reason ?? truncateError(error) }
+            });
+            derived = deriveTaskState(plan, journal);
+            return { status: 'paused', task_id: taskId, ...derived };
+          }
+          await appendEvent(ctx, journal, 'step_failed', {
+            stepId: next.step_id,
+            payload: { attempt, error: truncateError(error) }
+          });
+          derived = deriveTaskState(plan, journal);
+          if (attempt > next.retry_limit) {
+            await appendEvent(ctx, journal, 'task_failed', {
+              stepId: next.step_id,
+              payload: { reason: 'retry_exhausted', attempts: attempt, error: truncateError(error) }
+            });
+            derived = deriveTaskState(plan, journal);
+            return { status: 'failed', task_id: taskId, ...derived };
+          }
+        }
+      }
+      return { status: 'yielded', task_id: taskId, ...derived };
+    } finally {
+      await releaseTaskLock(ctx);
+    }
+  }
+
+  return Object.freeze({ submit, run, status, events, cancel, approve, verify });
+}