deadbyte-mcp 0.8.7

package/src/autonomous-supervisor.mjs

@@ -0,0 +1,86 @@
+import { readdir } from 'node:fs/promises';
+import path from 'node:path';
+
+const GOAL_ID_RE = /^[0-9a-f]{64}$/;
+const TERMINAL = new Set(['succeeded', 'cancelled', 'paused']);
+
+function delay(ms, signal) {
+  if (signal?.aborted) return Promise.resolve();
+  return new Promise(resolve => {
+    const timer = setTimeout(resolve, ms);
+    timer.unref?.();
+    signal?.addEventListener('abort', () => { clearTimeout(timer); resolve(); }, { once: true });
+  });
+}
+
+async function listGoalIds(policy) {
+  const root = path.join(policy.evidence_dir, 'goals');
+  let entries;
+  try { entries = await readdir(root, { withFileTypes: true }); }
+  catch (error) { if (error?.code === 'ENOENT') return []; throw error; }
+  return entries.filter(item => item.isDirectory() && GOAL_ID_RE.test(item.name))
+    .map(item => item.name).sort();
+}
+export function startAutonomousSupervisor({ runtime, policy = runtime?.policy,
+  idleDelayMs = 750, maxCycles = 32, logger = console } = {}) {
+  if (!runtime || !policy) throw new Error('autonomous supervisor requires runtime + policy');
+  if (policy.planner.backend !== 'openai_compatible') {
+    throw new Error('autonomous supervisor requires openai_compatible planner backend');
+  }
+  if (!Number.isInteger(idleDelayMs) || idleDelayMs < 25 || idleDelayMs > 60_000) {
+    throw new Error('autonomous supervisor idleDelayMs out of range');
+  }
+  if (!Number.isInteger(maxCycles) || maxCycles < 1 || maxCycles > 32) {
+    throw new Error('autonomous supervisor maxCycles out of range');
+  }
+  const abort = new AbortController();
+  const failures = new Map();
+  let passes = 0;
+
+  async function pass() {
+    let runnable = 0;
+    for (const goalId of await listGoalIds(policy)) {
+      if (abort.signal.aborted) break;
+      let status;
+      try { status = await runtime.status({ goalId }); }
+      catch (error) { logger.warn?.(`DEADBYTE supervisor status ${goalId}: ${String(error)}`); continue; }
+      if (TERMINAL.has(status.state)) { failures.delete(goalId); continue; }
+      runnable += 1;
+      const failure = failures.get(goalId);
+      if (failure && Date.now() < failure.retry_at) continue;
+      try {
+        const result = await runtime.run({ goalId, maxCycles });
+        failures.delete(goalId);
+        if (result.status === 'input_required') {
+          throw new Error('provider-backed supervisor unexpectedly requested client sampling');
+        }
+      } catch (error) {
+        const previous = failures.get(goalId)?.count ?? 0;
+        const count = Math.min(previous + 1, 12);
+        const retryMs = Math.min(300_000, 1_000 * (2 ** Math.min(count - 1, 8)));
+        failures.set(goalId, { count, retry_at: Date.now() + retryMs, error: String(error) });
+        logger.warn?.(`DEADBYTE supervisor retry ${goalId} in ${retryMs}ms: ${String(error)}`);
+      }
+    }
+    passes += 1;
+    return runnable;
+  }
+
+  const done = (async () => {
+    while (!abort.signal.aborted) {
+      let runnable = 0;
+      try { runnable = await pass(); }
+      catch (error) { logger.error?.(`DEADBYTE supervisor scan failed: ${String(error)}`); }
+      if (abort.signal.aborted) break;
+      await delay(runnable > 0 ? 25 : idleDelayMs, abort.signal);
+    }
+  })();
+
+  return Object.freeze({
+    get running() { return !abort.signal.aborted; },
+    get passes() { return passes; },
+    failures,
+    async scanNow() { return pass(); },
+    async stop() { abort.abort(); await done; }
+  });
+}

package/src/canonical-json.mjs

@@ -0,0 +1,17 @@
+function canonicalize(value) {
+  if (Array.isArray(value)) {
+    return value.map(canonicalize);
+  }
+  if (value !== null && typeof value === 'object') {
+    const out = {};
+    for (const key of Object.keys(value).sort()) {
+      out[key] = canonicalize(value[key]);
+    }
+    return out;
+  }
+  return value;
+}
+
+export function canonicalJson(value) {
+  return JSON.stringify(canonicalize(value));
+}

package/src/coding-mcp-tools.mjs

@@ -0,0 +1,143 @@
+import * as z from 'zod/v4';
+import { CODING_TASK_ID_RE, CODING_STEP_ID_RE } from './coding-task-runtime.mjs';
+import {
+  codingBenchmarkRunOutputSchema, codingCommandRunOutputSchema,
+  codingFileReadOutputSchema, codingFileWriteOutputSchema,
+  codingReceiptVerifyOutputSchema, codingSearchOutputSchema, codingSessionStatusOutputSchema, codingStatOutputSchema,
+  codingTaskApproveOutputSchema, codingTaskCancelOutputSchema,
+  codingTaskEventsOutputSchema, codingTaskRunOutputSchema,
+  codingTaskStatusOutputSchema, codingTaskSubmitOutputSchema,
+  codingTaskVerifyOutputSchema, codingTextReplaceOutputSchema,
+  codingTreeOutputSchema, codingStructuredResult
+} from './coding-output-contracts.mjs';
+
+const HEX64 = /^[0-9a-f]{64}$/;
+const HEX24 = /^[0-9a-f]{24}$/;
+const ID = /^[A-Za-z0-9._-]{1,64}$/;
+const rootId = z.string().regex(ID);
+const commandId = z.string().regex(ID);
+const taskId = z.string().regex(CODING_TASK_ID_RE);
+const stepId = z.string().regex(CODING_STEP_ID_RE);
+const relPath = z.string().min(1).max(512);
+const hex64 = z.string().regex(HEX64);
+const receiptId = z.string().regex(HEX24);
+const commandShape = {
+  root_id: rootId, command_id: commandId, script_path: relPath,
+  script_sha256: hex64, args: z.array(z.string().max(2048)).max(64).default([]),
+  cwd: relPath.default('.'), timeout_ms: z.number().int().min(100).max(900000).nullable().default(null)
+};
+
+const taskStep = z.union([
+  z.strictObject({ step_id: stepId, kind: z.literal('checkpoint'), message: z.string().min(1).max(512) }),
+  z.strictObject({ step_id: stepId, kind: z.literal('write'), root_id: rootId, path: relPath,
+    content: z.string().max(524288), encoding: z.enum(['utf8','base64']).default('utf8'),
+    expected_sha256: z.string().regex(/^(?:absent|[0-9a-f]{64})$/), retry_limit: z.number().int().min(0).max(2).default(0) }),
+  z.strictObject({ step_id: stepId, kind: z.literal('replace'), root_id: rootId, path: relPath,
+    old_string: z.string().min(1).max(262144), new_string: z.string().max(524288), expected_sha256: hex64,
+    expected_replacements: z.number().int().min(1).max(64).default(1), retry_limit: z.number().int().min(0).max(2).default(0) }),
+  z.strictObject({ step_id: stepId, kind: z.literal('command'), ...commandShape,
+    expect_exit_code: z.number().int().default(0), retry_limit: z.number().int().min(0).max(2).default(0) }),
+  z.strictObject({ step_id: stepId, kind: z.literal('benchmark'), ...commandShape,
+    warmups: z.number().int().min(0).max(3).default(1), iterations: z.number().int().min(1).max(20).default(5),
+    baseline_median_ms: z.number().positive().nullable().default(null), max_regression_pct: z.number().min(0).max(1000).default(5),
+    retry_limit: z.number().int().min(0).max(2).default(0) })
+]);
+
+function result(schema, value, isError = false) { return codingStructuredResult(schema, value, isError); }
+function fail(schema, error) { return result(schema, { status: 'failed', error: String(error) }, true); }
+export function registerCodingTools(server, { codingRuntime, taskRuntime }) {
+  if (!codingRuntime || !taskRuntime) throw new Error('coding tool registration requires runtimes');
+
+  server.registerTool('coding_session_status', {
+    description: 'Read coding-plane policy/lease status. This never arms or renews authority.',
+    inputSchema: z.strictObject({}), outputSchema: codingSessionStatusOutputSchema
+  }, async () => { try { return result(codingSessionStatusOutputSchema, await codingRuntime.sessionStatus()); } catch (error) { return fail(codingSessionStatusOutputSchema, error); } });
+
+  server.registerTool('coding_tree', {
+    description: 'List a bounded source tree inside a coding-policy root. Denied paths are omitted.',
+    inputSchema: z.strictObject({ root_id: rootId, path: relPath.default('.'), max_depth: z.number().int().min(0).max(12).default(4), max_entries: z.number().int().min(1).max(2000).default(500) }),
+    outputSchema: codingTreeOutputSchema
+  }, async ({ root_id, path, max_depth, max_entries }) => { try { return result(codingTreeOutputSchema, await codingRuntime.tree({ rootId: root_id, path, maxDepth: max_depth, maxEntries: max_entries })); } catch (error) { return fail(codingTreeOutputSchema, error); } });
+
+  server.registerTool('coding_stat', {
+    description: 'Read bounded metadata for one path inside an active coding-policy root.',
+    inputSchema: z.strictObject({ root_id: rootId, path: relPath.default('.'), hash: z.boolean().default(false) }),
+    outputSchema: codingStatOutputSchema
+  }, async ({ root_id, path, hash }) => { try { return result(codingStatOutputSchema, await codingRuntime.stat({ rootId: root_id, relativePath: path, hash })); } catch (error) { return fail(codingStatOutputSchema, error); } });
+
+  server.registerTool('coding_search', {
+    description: 'Deterministic literal content search using the existing coding tree/read authority.',
+    inputSchema: z.strictObject({ root_id: rootId, path: relPath.default('.'), pattern: z.string().min(1).max(256),
+      mode: z.literal('literal').default('literal'), case_sensitive: z.boolean().default(false),
+      max_results: z.number().int().min(1).max(1000).default(200), max_file_bytes: z.number().int().min(1).max(4194304).default(262144) }),
+    outputSchema: codingSearchOutputSchema
+  }, async ({ root_id, path, pattern, mode, case_sensitive, max_results, max_file_bytes }) => {
+    try { return result(codingSearchOutputSchema, await codingRuntime.search({ rootId: root_id, path, pattern, mode, caseSensitive: case_sensitive, maxResults: max_results, maxFileBytes: max_file_bytes })); }
+    catch (error) { return fail(codingSearchOutputSchema, error); }
+  });
+
+  server.registerTool('coding_file_read', {
+    description: 'Read one bounded file inside an active coding lease.',
+    inputSchema: z.strictObject({ root_id: rootId, path: relPath, encoding: z.enum(['utf8','base64']).default('utf8') }), outputSchema: codingFileReadOutputSchema
+  }, async ({ root_id, path, encoding }) => { try { return result(codingFileReadOutputSchema, await codingRuntime.fileRead({ rootId: root_id, relativePath: path, encoding })); } catch (error) { return fail(codingFileReadOutputSchema, error); } });
+  server.registerTool('coding_file_write', {
+    description: 'Atomically write one file with an absent/SHA-256 precondition and signed coding receipt.',
+    inputSchema: z.strictObject({ root_id: rootId, path: relPath, content: z.string().max(524288), encoding: z.enum(['utf8','base64']).default('utf8'), expected_sha256: z.string().regex(/^(?:absent|[0-9a-f]{64})$/) }),
+    outputSchema: codingFileWriteOutputSchema
+  }, async ({ root_id, path, content, encoding, expected_sha256 }) => { try { return result(codingFileWriteOutputSchema, await codingRuntime.fileWrite({ rootId: root_id, relativePath: path, content, encoding, expectedSha256: expected_sha256 })); } catch (error) { return fail(codingFileWriteOutputSchema, error); } });
+
+  server.registerTool('coding_text_replace', {
+    description: 'Perform an exact bounded text replacement under SHA-256 precondition and signed receipt.',
+    inputSchema: z.strictObject({ root_id: rootId, path: relPath, old_string: z.string().min(1).max(262144), new_string: z.string().max(524288), expected_sha256: hex64, expected_replacements: z.number().int().min(1).max(64).default(1) }),
+    outputSchema: codingTextReplaceOutputSchema
+  }, async ({ root_id, path, old_string, new_string, expected_sha256, expected_replacements }) => { try { return result(codingTextReplaceOutputSchema, await codingRuntime.textReplace({ rootId: root_id, relativePath: path, oldString: old_string, newString: new_string, expectedSha256: expected_sha256, expectedReplacements: expected_replacements })); } catch (error) { return fail(codingTextReplaceOutputSchema, error); } });
+
+  server.registerTool('coding_command_run', {
+    description: 'Run one allowlisted hash-pinned script with shell=false, bounded argv/output/time, and a signed observation receipt.',
+    inputSchema: z.strictObject(commandShape), outputSchema: codingCommandRunOutputSchema
+  }, async ({ root_id, command_id, script_path, script_sha256, args, cwd, timeout_ms }) => { try { return result(codingCommandRunOutputSchema, await codingRuntime.commandRun({ rootId: root_id, commandId: command_id, scriptPath: script_path, scriptSha256: script_sha256, args, cwd, timeoutMs: timeout_ms })); } catch (error) { return fail(codingCommandRunOutputSchema, error); } });
+  server.registerTool('coding_benchmark_run', {
+    description: 'Run a bounded benchmark profile and judge median regression against an optional baseline.',
+    inputSchema: z.strictObject({ ...commandShape, warmups: z.number().int().min(0).max(3).default(1), iterations: z.number().int().min(1).max(20).default(5), baseline_median_ms: z.number().positive().nullable().default(null), max_regression_pct: z.number().min(0).max(1000).default(5) }),
+    outputSchema: codingBenchmarkRunOutputSchema
+  }, async ({ root_id, command_id, script_path, script_sha256, args, cwd, timeout_ms, warmups, iterations, baseline_median_ms, max_regression_pct }) => { try { return result(codingBenchmarkRunOutputSchema, await codingRuntime.benchmarkRun({ rootId: root_id, commandId: command_id, scriptPath: script_path, scriptSha256: script_sha256, args, cwd, timeoutMs: timeout_ms, warmups, iterations, baselineMedianMs: baseline_median_ms, maxRegressionPct: max_regression_pct })); } catch (error) { return fail(codingBenchmarkRunOutputSchema, error); } });
+
+  server.registerTool('coding_receipt_verify', {
+    description: 'Verify one Ed25519 coding-action receipt against policy and request identity.',
+    inputSchema: z.strictObject({ receipt_id: receiptId }), outputSchema: codingReceiptVerifyOutputSchema
+  }, async ({ receipt_id }) => { try { const value = await codingRuntime.receiptVerify({ receiptId: receipt_id }); return result(codingReceiptVerifyOutputSchema, value, value.ok !== true); } catch (error) { return fail(codingReceiptVerifyOutputSchema, error); } });
+
+  server.registerTool('coding_task_submit', {
+    description: 'Submit a durable typed coding plan for edit/build/test/benchmark/checkpoint execution.',
+    inputSchema: z.strictObject({ submission_id: z.string().regex(ID), title: z.string().max(120).default(''), steps: z.array(taskStep).min(1).max(32) }),
+    outputSchema: codingTaskSubmitOutputSchema
+  }, async ({ submission_id, title, steps }) => { try { return result(codingTaskSubmitOutputSchema, await taskRuntime.submit({ submissionId: submission_id, title, steps })); } catch (error) { return fail(codingTaskSubmitOutputSchema, error); } });
+  server.registerTool('coding_task_run', {
+    description: 'Advance one durable coding task by bounded steps with retry/checkpoint/crash reconciliation.',
+    inputSchema: z.strictObject({ task_id: taskId, max_steps: z.number().int().min(1).max(32).default(8) }), outputSchema: codingTaskRunOutputSchema
+  }, async ({ task_id, max_steps }) => { try { return result(codingTaskRunOutputSchema, await taskRuntime.run({ taskId: task_id, maxSteps: max_steps })); } catch (error) { return fail(codingTaskRunOutputSchema, error); } });
+
+  server.registerTool('coding_task_status', {
+    description: 'Read derived coding-task state from the authenticated event journal.',
+    inputSchema: z.strictObject({ task_id: taskId }), outputSchema: codingTaskStatusOutputSchema
+  }, async ({ task_id }) => { try { return result(codingTaskStatusOutputSchema, await taskRuntime.status({ taskId: task_id })); } catch (error) { return fail(codingTaskStatusOutputSchema, error); } });
+
+  server.registerTool('coding_task_events', {
+    description: 'Read a bounded authenticated coding-task event slice.',
+    inputSchema: z.strictObject({ task_id: taskId, from_seq: z.number().int().min(1).default(1), limit: z.number().int().min(1).max(200).default(100) }), outputSchema: codingTaskEventsOutputSchema
+  }, async ({ task_id, from_seq, limit }) => { try { return result(codingTaskEventsOutputSchema, await taskRuntime.events({ taskId: task_id, fromSeq: from_seq, limit })); } catch (error) { return fail(codingTaskEventsOutputSchema, error); } });
+  server.registerTool('coding_task_cancel', {
+    description: 'Request signed cooperative cancellation between coding steps.',
+    inputSchema: z.strictObject({ task_id: taskId, reason: z.string().min(1).max(256).default('operator_request') }), outputSchema: codingTaskCancelOutputSchema
+  }, async ({ task_id, reason }) => { try { return result(codingTaskCancelOutputSchema, await taskRuntime.cancel({ taskId: task_id, reason })); } catch (error) { return fail(codingTaskCancelOutputSchema, error); } });
+
+  server.registerTool('coding_task_approve', {
+    description: 'Approve or reject a coding checkpoint. Approval does not arm or extend coding authority.',
+    inputSchema: z.strictObject({ task_id: taskId, step_id: stepId, decision: z.enum(['approve','reject']).default('approve') }), outputSchema: codingTaskApproveOutputSchema
+  }, async ({ task_id, step_id, decision }) => { try { return result(codingTaskApproveOutputSchema, await taskRuntime.approve({ taskId: task_id, stepId: step_id, decision })); } catch (error) { return fail(codingTaskApproveOutputSchema, error); } });
+
+  server.registerTool('coding_task_verify', {
+    description: 'Verify the signed coding task receipt, journal binding, and every action receipt.',
+    inputSchema: z.strictObject({ task_id: taskId }), outputSchema: codingTaskVerifyOutputSchema
+  }, async ({ task_id }) => { try { const value = await taskRuntime.verify({ taskId: task_id }); return result(codingTaskVerifyOutputSchema, value, value.ok !== true); } catch (error) { return fail(codingTaskVerifyOutputSchema, error); } });
+}

package/src/coding-output-contracts.mjs

@@ -0,0 +1,189 @@
+import * as z from 'zod/v4';
+
+const HEX64_RE = /^[0-9a-f]{64}$/;
+const HEX24_RE = /^[0-9a-f]{24}$/;
+const TASK_ID_RE = /^[0-9a-f]{64}$/;
+const STEP_ID_RE = /^[A-Za-z0-9._-]{1,48}$/;
+const hex64 = z.string().regex(HEX64_RE);
+const receiptId = z.string().regex(HEX24_RE);
+const taskId = z.string().regex(TASK_ID_RE);
+const stepId = z.string().regex(STEP_ID_RE);
+const jsonObject = z.record(z.string(), z.json());
+const taskState = z.enum(['pending', 'running', 'paused', 'failed', 'cancelled', 'succeeded']);
+const codingKind = z.enum(['checkpoint', 'write', 'replace', 'command', 'benchmark']);
+
+function requireFields(value, ctx, fields) {
+  for (const field of fields) if (value[field] === undefined) ctx.addIssue({ code: 'custom', path: [field], message: `${field} is required` });
+}
+function statusContract({ statuses, shape = {}, successStatuses, successRequired = [], errorStatuses = ['failed'] }) {
+  return z.strictObject({ status: z.enum(statuses), error: z.string().optional(), ...shape }).superRefine((value, ctx) => {
+    if (value.error !== undefined) {
+      if (!errorStatuses.includes(value.status)) ctx.addIssue({ code: 'custom', path: ['error'], message: 'error is not valid for this status' });
+      return;
+    }
+    if (errorStatuses.includes(value.status) && !successStatuses.includes(value.status)) {
+      ctx.addIssue({ code: 'custom', path: ['error'], message: 'error is required for this status' });
+      return;
+    }
+    if (successStatuses.includes(value.status)) requireFields(value, ctx, successRequired);
+  });
+}
+const codingStepSchema = z.strictObject({
+  step_id: stepId, kind: codingKind,
+  state: z.enum(['pending', 'running', 'succeeded', 'waiting_approval']),
+  attempts: z.number().int().min(0), result: jsonObject.nullable(), error: z.string().nullable(),
+  receipt_id: receiptId.nullable(), request_sha256: hex64.nullable()
+});
+const derivedShape = {
+  state: taskState,
+  reason: z.string().nullable(),
+  active_step_id: stepId.nullable(),
+  steps: z.array(codingStepSchema).max(32),
+  completed_steps: z.number().int().min(0).max(32),
+  journal_head_sha256: hex64
+};
+const attestationSchema = z.strictObject({
+  algorithm: z.literal('ed25519'), key_id: hex64, signature_base64: z.string().min(1)
+});
+const eventSchema = z.strictObject({
+  schema: z.literal('deadbyte.coding-task-event.v1'), seq: z.number().int().min(1), task_id: taskId,
+  created_at_utc: z.string().min(1), prev_sha256: hex64, type: z.string().min(1).max(64),
+  step_id: stepId.optional(), payload: jsonObject, event_sha256: hex64, attestation: attestationSchema
+});
+
+export const codingSessionStatusOutputSchema = statusContract({
+  statuses: ['ok', 'failed'],
+  shape: { configured: z.literal(true).optional(), armed: z.boolean().optional(), reason: z.string().optional(),
+    expires_at_utc: z.string().nullable().optional(), root_ids: z.array(z.string()).max(64).optional(),
+    command_ids: z.array(z.string()).max(64).optional(), policy_sha256: hex64.optional() },
+  successStatuses: ['ok'], successRequired: ['configured', 'armed', 'reason', 'expires_at_utc', 'root_ids', 'command_ids', 'policy_sha256']
+});
+export const codingTreeOutputSchema = statusContract({
+  statuses: ['ok', 'failed'],
+  shape: {
+    root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(),
+    entries: z.array(z.strictObject({ path: z.string().min(1), type: z.enum(['file', 'directory', 'symlink', 'other']), bytes: z.number().int().min(0) })).max(2000).optional(),
+    truncated: z.boolean().optional()
+  },
+  successStatuses: ['ok'], successRequired: ['root_id', 'path', 'entries', 'truncated']
+});
+export const codingStatOutputSchema = statusContract({
+  statuses: ['ok', 'failed'],
+  shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(),
+    type: z.enum(['file','directory','symlink','other']).optional(), bytes: z.number().int().min(0).optional(),
+    mtime_utc: z.string().min(1).optional(), sha256: hex64.nullable().optional() },
+  successStatuses: ['ok'], successRequired: ['root_id','path','type','bytes','mtime_utc','sha256']
+});
+export const codingSearchOutputSchema = statusContract({
+  statuses: ['ok', 'failed'],
+  shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(),
+    pattern: z.string().min(1).max(256).optional(), mode: z.literal('literal').optional(), case_sensitive: z.boolean().optional(),
+    matches: z.array(z.strictObject({ path: z.string().min(1).max(512), line: z.number().int().min(1),
+      column: z.number().int().min(1), preview: z.string().max(512) })).max(1000).optional(),
+    files_scanned: z.number().int().min(0).optional(), bytes_scanned: z.number().int().min(0).optional(), truncated: z.boolean().optional() },
+  successStatuses: ['ok'], successRequired: ['root_id','path','pattern','mode','case_sensitive','matches','files_scanned','bytes_scanned','truncated']
+});
+export const codingFileReadOutputSchema = statusContract({
+  statuses: ['ok', 'failed'],
+  shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(), encoding: z.enum(['utf8', 'base64']).optional(),
+    bytes: z.number().int().min(0).optional(), sha256: hex64.optional(), content: z.string().optional() },
+  successStatuses: ['ok'], successRequired: ['root_id', 'path', 'encoding', 'bytes', 'sha256', 'content']
+});
+export const codingFileWriteOutputSchema = statusContract({
+  statuses: ['committed', 'failed'],
+  shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(), previous_sha256: hex64.nullable().optional(),
+    sha256: hex64.optional(), bytes: z.number().int().min(0).optional(), created: z.boolean().optional(), receipt_id: receiptId.optional(),
+    receipt_sha256: hex64.optional(), request_sha256: hex64.optional() },
+  successStatuses: ['committed'], successRequired: ['root_id', 'path', 'previous_sha256', 'sha256', 'bytes', 'created', 'receipt_id', 'receipt_sha256', 'request_sha256']
+});
+export const codingTextReplaceOutputSchema = statusContract({
+  statuses: ['committed', 'failed'],
+  shape: { root_id: z.string().min(1).max(64).optional(), path: z.string().min(1).max(512).optional(), previous_sha256: hex64.optional(),
+    sha256: hex64.optional(), bytes: z.number().int().min(0).optional(), replacements: z.number().int().min(1).max(64).optional(),
+    receipt_id: receiptId.optional(), receipt_sha256: hex64.optional(), request_sha256: hex64.optional() },
+  successStatuses: ['committed'], successRequired: ['root_id', 'path', 'previous_sha256', 'sha256', 'bytes', 'replacements', 'receipt_id', 'receipt_sha256', 'request_sha256']
+});
+export const codingCommandRunOutputSchema = statusContract({
+  statuses: ['passed', 'observed_failure', 'failed'],
+  shape: { root_id: z.string().min(1).max(64).optional(), command_id: z.string().min(1).max(64).optional(), executable_sha256: hex64.optional(), script_sha256: hex64.optional(),
+    exit_code: z.number().int().nullable().optional(), signal: z.string().nullable().optional(), timed_out: z.boolean().optional(), timeout_ms: z.number().int().min(100).optional(),
+    elapsed_ms: z.number().min(0).optional(), stdout: z.string().optional(), stderr: z.string().optional(), receipt_id: receiptId.optional(), receipt_sha256: hex64.optional(), request_sha256: hex64.optional() },
+  successStatuses: ['passed', 'observed_failure'],
+  successRequired: ['root_id', 'command_id', 'executable_sha256', 'script_sha256', 'exit_code', 'signal', 'timed_out', 'timeout_ms', 'elapsed_ms', 'stdout', 'stderr', 'receipt_id', 'receipt_sha256', 'request_sha256'],
+  errorStatuses: ['failed']
+});
+export const codingBenchmarkRunOutputSchema = statusContract({
+  statuses: ['passed', 'regression', 'failed'],
+  shape: { root_id: z.string().min(1).max(64).optional(), command_id: z.string().min(1).max(64).optional(), warmups: z.number().int().min(0).max(3).optional(),
+    iterations: z.number().int().min(1).max(20).optional(), samples_ms: z.array(z.number().min(0)).max(20).optional(), median_ms: z.number().min(0).optional(),
+    p95_ms: z.number().min(0).optional(), baseline_median_ms: z.number().positive().nullable().optional(), max_regression_pct: z.number().min(0).optional(),
+    regression_pct: z.number().nullable().optional(), verdict: z.enum(['pass', 'regression']).optional(), receipt_id: receiptId.optional(), receipt_sha256: hex64.optional(), request_sha256: hex64.optional() },
+  successStatuses: ['passed', 'regression'], successRequired: ['root_id', 'command_id', 'warmups', 'iterations', 'samples_ms', 'median_ms', 'p95_ms', 'baseline_median_ms', 'max_regression_pct', 'regression_pct', 'verdict', 'receipt_id', 'receipt_sha256', 'request_sha256'],
+  errorStatuses: ['failed']
+});
+export const codingReceiptVerifyOutputSchema = z.strictObject({
+  status: z.literal('failed').optional(), error: z.string().optional(),
+  ok: z.boolean().optional(), reason: z.string().optional(), receipt_id: receiptId.optional(), receipt_sha256: hex64.optional(),
+  operation: z.enum(['coding_file_write', 'coding_text_replace', 'coding_command_run', 'coding_benchmark_run']).optional(),
+  request_sha256: hex64.optional(), signature_valid: z.literal(true).optional()
+}).superRefine((value, ctx) => {
+  if (value.status === 'failed') { requireFields(value, ctx, ['error']); return; }
+  if (value.ok === undefined) { ctx.addIssue({ code: 'custom', path: ['ok'], message: 'ok is required' }); return; }
+  if (!value.ok) { requireFields(value, ctx, ['reason']); return; }
+  requireFields(value, ctx, ['receipt_id', 'receipt_sha256', 'operation', 'request_sha256', 'signature_valid']);
+});
+
+export const codingTaskSubmitOutputSchema = statusContract({
+  statuses: ['accepted', 'existing', 'failed'],
+  shape: { task_id: taskId.optional(), plan_sha256: hex64.optional(), state: taskState.optional() },
+  successStatuses: ['accepted', 'existing'], successRequired: ['task_id', 'plan_sha256', 'state']
+});
+export const codingTaskRunOutputSchema = z.strictObject({
+  status: z.enum(['terminal', 'paused', 'completed', 'cancelled', 'failed', 'yielded', 'succeeded']), error: z.string().optional(), task_id: taskId.optional(),
+  ...Object.fromEntries(Object.entries(derivedShape).map(([key, schema]) => [key, schema.optional()]))
+}).superRefine((value, ctx) => {
+  if (value.error !== undefined) { if (value.status !== 'failed') ctx.addIssue({ code: 'custom', path: ['error'], message: 'error wrapper requires status=failed' }); return; }
+  requireFields(value, ctx, ['task_id', ...Object.keys(derivedShape)]);
+});
+export const codingTaskStatusOutputSchema = statusContract({
+  statuses: ['ok', 'failed'],
+  shape: { task_id: taskId.optional(), plan_sha256: hex64.optional(),
+    ...Object.fromEntries(Object.entries(derivedShape).map(([key, schema]) => [key, schema.optional()])), journal_verified: z.literal(true).optional() },
+  successStatuses: ['ok'], successRequired: ['task_id', 'plan_sha256', ...Object.keys(derivedShape), 'journal_verified']
+});
+export const codingTaskEventsOutputSchema = statusContract({
+  statuses: ['ok', 'failed'],
+  shape: { task_id: taskId.optional(), plan_sha256: hex64.optional(), journal_verified: z.literal(true).optional(),
+    journal_head_sha256: hex64.optional(), events: z.array(eventSchema).max(200).optional() },
+  successStatuses: ['ok'], successRequired: ['task_id', 'plan_sha256', 'journal_verified', 'journal_head_sha256', 'events']
+});
+export const codingTaskCancelOutputSchema = statusContract({
+  statuses: ['terminal', 'requested', 'existing', 'failed'],
+  shape: { task_id: taskId.optional(), state: taskState.optional() },
+  successStatuses: ['terminal', 'requested', 'existing'], successRequired: ['task_id', 'state']
+});
+export const codingTaskApproveOutputSchema = z.strictObject({
+  status: z.enum(['existing', 'approved', 'rejected', 'failed']), error: z.string().optional(),
+  task_id: taskId.optional(), step_id: stepId.optional(),
+  ...Object.fromEntries(Object.entries(derivedShape).map(([key, schema]) => [key, schema.optional()]))
+}).superRefine((value, ctx) => {
+  if (value.error !== undefined) { if (value.status !== 'failed') ctx.addIssue({ code: 'custom', path: ['error'], message: 'error wrapper requires status=failed' }); return; }
+  requireFields(value, ctx, ['task_id', 'step_id', 'state']);
+  if (value.status !== 'existing') requireFields(value, ctx, Object.keys(derivedShape));
+});
+export const codingTaskVerifyOutputSchema = z.strictObject({
+  status: z.literal('failed').optional(), error: z.string().optional(), ok: z.boolean().optional(), reason: z.string().optional(),
+  task_id: taskId.optional(), plan_sha256: hex64.optional(), task_receipt_sha256: hex64.optional(), signature_valid: z.literal(true).optional(),
+  journal_head_sha256: hex64.optional(), action_receipts_verified: z.number().int().min(0).max(32).optional()
+}).superRefine((value, ctx) => {
+  if (value.status === 'failed') { requireFields(value, ctx, ['error']); return; }
+  if (value.ok === undefined) { ctx.addIssue({ code: 'custom', path: ['ok'], message: 'ok is required' }); return; }
+  if (!value.ok) { requireFields(value, ctx, ['reason']); return; }
+  requireFields(value, ctx, ['task_id', 'plan_sha256', 'task_receipt_sha256', 'signature_valid', 'journal_head_sha256', 'action_receipts_verified']);
+});
+
+export function codingStructuredResult(schema, object, isError = false) {
+  const parsed = schema.safeParse(object);
+  if (!parsed.success) throw new Error(`DEADBYTE coding output contract violation: ${z.prettifyError(parsed.error)}`);
+  return { isError, structuredContent: parsed.data, content: [{ type: 'text', text: JSON.stringify(parsed.data) }] };
+}