deadbyte-mcp 0.8.7

package/src/autonomous-planner.mjs

@@ -0,0 +1,290 @@
+import { canonicalJson } from './canonical-json.mjs';
+import { validatePortableRelativePath } from './path-policy.mjs';
+
+export const AUTONOMOUS_DECISION_SCHEMA = 'deadbyte.autonomous-decision.v1';
+const ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+const SHA256_RE = /^[0-9a-f]{64}$/;
+function strictKeys(value, allowed, label) {
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error(`${label} must be object`);
+  for (const key of Object.keys(value)) if (!allowed.includes(key)) throw new Error(`${label} unknown field '${key}'`);
+}
+function text(value, name, max, min = 0) {
+  if (typeof value !== 'string' || value.length < min || value.length > max) throw new Error(`${name} invalid`);
+  return value;
+}
+function normalizeOperation(raw) {
+  strictKeys(raw, ['kind','path','content','encoding','expected_sha256','old_string','new_string','expected_replacements'], 'planner patch operation');
+  validatePortableRelativePath(raw.path);
+  if (raw.kind === 'write') {
+    if (!['utf8','base64'].includes(raw.encoding ?? 'utf8')) throw new Error('planner write encoding invalid');
+    if (typeof raw.content !== 'string' || raw.content.length > 524288) throw new Error('planner write content invalid');
+    if (raw.expected_sha256 !== 'absent' && !SHA256_RE.test(raw.expected_sha256 ?? '')) throw new Error('planner write expected_sha256 invalid');
+    return { kind:'write', path:raw.path, content:raw.content, encoding:raw.encoding ?? 'utf8', expected_sha256:raw.expected_sha256 };
+  }
+  if (raw.kind === 'replace') {
+    if (!SHA256_RE.test(raw.expected_sha256 ?? '')) throw new Error('planner replace expected_sha256 invalid');
+    text(raw.old_string,'planner old_string',262144,1); text(raw.new_string,'planner new_string',524288);
+    const count = raw.expected_replacements ?? 1;
+    if (!Number.isInteger(count) || count < 1 || count > 64) throw new Error('planner expected_replacements invalid');
+    return { kind:'replace', path:raw.path, expected_sha256:raw.expected_sha256,
+      old_string:raw.old_string, new_string:raw.new_string, expected_replacements:count };
+  }
+  if (raw.kind === 'delete') {
+    if (!SHA256_RE.test(raw.expected_sha256 ?? '')) throw new Error('planner delete expected_sha256 invalid');
+    return { kind:'delete', path:raw.path, expected_sha256:raw.expected_sha256 };
+  }
+  throw new Error('planner patch kind invalid');
+}
+function boundedInteger(value, name, min, max, fallback) {
+  const normalized = value ?? fallback;
+  if (!Number.isInteger(normalized) || normalized < min || normalized > max) throw new Error(`${name} invalid`);
+  return normalized;
+}
+function normalizeDelegatedOperation(raw) {
+  strictKeys(raw, ['kind','path','offset','max_bytes','cursor','limit','hash','hash_files','pattern','case_sensitive',
+    'max_results','max_files','max_file_bytes','search_id','include_external','profile_id','cwd','session_id','action_id'],
+  'planner delegated operation');
+  const exact = keys => strictKeys(raw, ['kind',...keys], `planner delegated ${raw.kind ?? 'operation'}`);
+  const simple = kind => ({ kind });
+  if (raw.kind === 'machine_stat') {
+    exact(['path','hash']);
+    if (raw.path !== undefined && raw.path !== '.') validatePortableRelativePath(raw.path);
+    return { kind:raw.kind, path:raw.path ?? '.', hash:raw.hash === true };
+  }
+  if (raw.kind === 'machine_list') {
+    exact(['path','cursor','limit','hash_files']);
+    if (raw.path !== undefined && raw.path !== '.') validatePortableRelativePath(raw.path);
+    if (raw.cursor !== undefined && raw.cursor !== null) text(raw.cursor,'planner machine cursor',2048,1);
+    return { kind:raw.kind, path:raw.path ?? '.', cursor:raw.cursor ?? null,
+      limit:boundedInteger(raw.limit,'planner machine list limit',1,500,100), hash_files:raw.hash_files === true };
+  }
+  if (raw.kind === 'machine_read') {
+    exact(['path','offset','max_bytes','hash']);
+    validatePortableRelativePath(raw.path);
+    return { kind:raw.kind, path:raw.path, offset:boundedInteger(raw.offset,'planner machine read offset',0,Number.MAX_SAFE_INTEGER,0),
+      max_bytes:boundedInteger(raw.max_bytes,'planner machine read max_bytes',1,262144,65536), hash:raw.hash === true };
+  }
+  if (raw.kind === 'observation_search_start') {
+    exact(['path','pattern','case_sensitive','max_results','max_files','max_bytes','max_file_bytes']);
+    if (raw.path !== undefined && raw.path !== '.') validatePortableRelativePath(raw.path);
+    return { kind:raw.kind, path:raw.path ?? '.', pattern:text(raw.pattern,'planner search pattern',256,1),
+      case_sensitive:raw.case_sensitive === true,
+      max_results:boundedInteger(raw.max_results,'planner search max_results',1,1000,200),
+      max_files:boundedInteger(raw.max_files,'planner search max_files',1,10000,2000),
+      max_bytes:boundedInteger(raw.max_bytes,'planner search max_bytes',1,64*1024*1024,4*1024*1024),
+      max_file_bytes:boundedInteger(raw.max_file_bytes,'planner search max_file_bytes',1,4*1024*1024,262144) };
+  }
+  if (['observation_search_status','observation_search_cancel'].includes(raw.kind)) {
+    exact(['search_id']);
+    if (!SHA256_RE.test(raw.search_id ?? '')) throw new Error('planner search_id invalid');
+    return { kind:raw.kind, search_id:raw.search_id };
+  }
+  if (raw.kind === 'observation_search_page') {
+    exact(['search_id','cursor','limit']);
+    if (!SHA256_RE.test(raw.search_id ?? '')) throw new Error('planner search_id invalid');
+    if (raw.cursor !== undefined && raw.cursor !== null) text(raw.cursor,'planner search cursor',2048,1);
+    return { kind:raw.kind, search_id:raw.search_id, cursor:raw.cursor ?? null,
+      limit:boundedInteger(raw.limit,'planner search page limit',1,500,100) };
+  }
+  if (raw.kind === 'observation_process_list') {
+    exact(['include_external','cursor','limit']);
+    if (raw.cursor !== undefined && raw.cursor !== null) text(raw.cursor,'planner process cursor',2048,1);
+    return { kind:raw.kind, include_external:raw.include_external === true, cursor:raw.cursor ?? null,
+      limit:boundedInteger(raw.limit,'planner process list limit',1,500,100) };
+  }
+  if (raw.kind === 'observation_system_status' || raw.kind === 'process_list') { exact([]); return simple(raw.kind); }
+  if (raw.kind === 'process_start') {
+    exact(['profile_id','cwd']);
+    if (!ID_RE.test(raw.profile_id ?? '')) throw new Error('planner process profile_id invalid');
+    if (raw.cwd !== undefined && raw.cwd !== '.') validatePortableRelativePath(raw.cwd);
+    return { kind:raw.kind, profile_id:raw.profile_id, cwd:raw.cwd ?? '.' };
+  }
+  if (['process_read','process_status','process_terminate'].includes(raw.kind)) {
+    exact(raw.kind === 'process_read' ? ['session_id','offset','max_bytes'] : ['session_id']);
+    if (!SHA256_RE.test(raw.session_id ?? '')) throw new Error('planner process session_id invalid');
+    if (raw.kind !== 'process_read') return { kind:raw.kind, session_id:raw.session_id };
+    return { kind:raw.kind, session_id:raw.session_id,
+      offset:boundedInteger(raw.offset,'planner process read offset',0,Number.MAX_SAFE_INTEGER,0),
+      max_bytes:boundedInteger(raw.max_bytes,'planner process read max_bytes',1,262144,65536) };
+  }
+  if (raw.kind === 'process_action') {
+    exact(['session_id','action_id']);
+    if (!SHA256_RE.test(raw.session_id ?? '')) throw new Error('planner process session_id invalid');
+    if (!ID_RE.test(raw.action_id ?? '')) throw new Error('planner process action_id invalid');
+    return { kind:raw.kind, session_id:raw.session_id, action_id:raw.action_id };
+  }
+  throw new Error('planner delegated operation kind invalid');
+}
+function normalizePlan(raw) {
+  strictKeys(raw, ['title','reason','steps'], 'planner plan');
+  const title = text(raw.title, 'planner plan title', 160, 1);
+  if (!Array.isArray(raw.steps) || raw.steps.length < 1 || raw.steps.length > 24) throw new Error('planner plan steps invalid');
+  const seen = new Set(); let activeCount = 0; let seenNonCompleted = false; let seenPending = false;
+  const steps = raw.steps.map((item,index) => {
+    strictKeys(item, ['step_id','title','status','result'], `planner plan step ${index}`);
+    if (!ID_RE.test(item.step_id ?? '') || seen.has(item.step_id)) throw new Error('planner plan step_id invalid or duplicate');
+    seen.add(item.step_id);
+    const stepTitle = text(item.title, 'planner plan step title', 240, 1);
+    if (!['pending','running','completed','failed'].includes(item.status)) throw new Error('planner plan step status invalid');
+    if (item.status === 'completed') {
+      if (seenNonCompleted) throw new Error('planner plan completed steps must form an immutable prefix');
+    } else if (item.status === 'running' || item.status === 'failed') {
+      if (seenPending || activeCount > 0) throw new Error('planner plan may have at most one active step before pending suffix');
+      activeCount += 1; seenNonCompleted = true;
+    } else {
+      seenNonCompleted = true; seenPending = true;
+    }
+    if ((item.status === 'pending' || item.status === 'running') && item.result !== undefined) {
+      throw new Error('planner plan result requires completed or failed status');
+    }
+    const result = item.result === undefined ? undefined : text(item.result,'planner plan step result',1024,1);
+    return { step_id:item.step_id, title:stepTitle, status:item.status, ...(result === undefined ? {} : { result }) };
+  });
+  const reason = raw.reason === undefined ? undefined : text(raw.reason,'planner plan reason',512,1);
+  return { title, steps, ...(reason === undefined ? {} : { reason }) };
+}
+export function parsePlannerDecision(rawText, policy) {
+  if (typeof rawText !== 'string' || rawText.length < 2 || rawText.length > policy.limits.max_context_bytes) throw new Error('planner response size invalid');
+  let raw;
+  try { raw = JSON.parse(rawText); } catch { throw new Error('planner response must be strict JSON only'); }
+  strictKeys(raw, ['schema','action','summary','reads','operations','operation','profile_id','reason','plan'], 'planner decision');
+  if (raw.schema !== AUTONOMOUS_DECISION_SCHEMA) throw new Error('planner decision schema mismatch');
+  const summary = text(raw.summary ?? '', 'planner summary', 1024);
+  const plan = raw.plan === undefined ? null : normalizePlan(raw.plan);
+  const withPlan = decision => plan === null ? decision : { ...decision, plan };
+  if (raw.action === 'inspect') {
+    if (!Array.isArray(raw.reads) || raw.reads.length < 1 || raw.reads.length > 8) throw new Error('planner inspect reads invalid');
+    const reads = raw.reads.map((item, index) => {
+      strictKeys(item, ['path','max_bytes'], `planner read ${index}`); validatePortableRelativePath(item.path);
+      const maxBytes = item.max_bytes ?? 65536;
+      if (!Number.isInteger(maxBytes) || maxBytes < 1 || maxBytes > 262144) throw new Error('planner read max_bytes invalid');
+      return { path:item.path, max_bytes:maxBytes };
+    });
+    return withPlan({ schema:AUTONOMOUS_DECISION_SCHEMA, action:'inspect', summary, reads });
+  }
+  if (raw.action === 'patch') {
+    if (!Array.isArray(raw.operations) || raw.operations.length < 1 || raw.operations.length > policy.limits.max_files_per_diff) throw new Error('planner patch operations invalid');
+    return withPlan({ schema:AUTONOMOUS_DECISION_SCHEMA, action:'patch', summary, operations:raw.operations.map(normalizeOperation) });
+  }
+  if (raw.action === 'run_profile') {
+    if (!ID_RE.test(raw.profile_id ?? '') || !policy.profiles[raw.profile_id]) throw new Error('planner profile_id invalid');
+    return withPlan({ schema:AUTONOMOUS_DECISION_SCHEMA, action:'run_profile', summary, profile_id:raw.profile_id });
+  }
+  if (raw.action === 'delegate') {
+    return withPlan({ schema:AUTONOMOUS_DECISION_SCHEMA, action:'delegate', summary,
+      operation:normalizeDelegatedOperation(raw.operation) });
+  }
+  if (raw.action === 'finish') return withPlan({ schema:AUTONOMOUS_DECISION_SCHEMA, action:'finish', summary });
+  if (raw.action === 'pause') return withPlan({ schema:AUTONOMOUS_DECISION_SCHEMA, action:'pause', summary, reason:text(raw.reason ?? 'planner_pause','planner pause reason',512,1) });
+  throw new Error('planner action invalid');
+}
+function plannerStateBytes(state) {
+  return Buffer.byteLength(canonicalJson(state),'utf8');
+}
+function elideContextPayload(item) {
+  if (!item || typeof item !== 'object' || typeof item.content !== 'string') return item;
+  const { content, ...rest } = item;
+  return { ...rest, content_elided:true, content_bytes:Buffer.byteLength(content,'utf8') };
+}
+function elideObservationPayload(item) {
+  if (!item || typeof item !== 'object') return item;
+  const copy = { ...item }; let changed = false;
+  for (const field of ['stdout_excerpt','stderr_excerpt']) {
+    if (typeof copy[field] !== 'string') continue;
+    copy[`${field}_bytes`] = Buffer.byteLength(copy[field],'utf8');
+    copy[`${field}_elided`] = true;
+    delete copy[field]; changed = true;
+  }
+  return changed ? copy : item;
+}
+function compactPlannerState(state, limit) {
+  if (plannerStateBytes(state) <= limit) return state;
+  const contexts = [...state.contexts]; const observations = [...state.observations];
+  let candidate = { ...state, contexts, observations };
+  const fits = () => plannerStateBytes(candidate) <= limit;
+  for (let i = 0; i < Math.max(0,contexts.length - 1) && !fits(); i += 1) {
+    contexts[i] = elideContextPayload(contexts[i]);
+  }
+  for (let i = 0; i < Math.max(0,observations.length - 1) && !fits(); i += 1) {
+    observations[i] = elideObservationPayload(observations[i]);
+  }
+  if (!fits() && candidate.tree.length > 128) {
+    const originalEntries = candidate.tree.length;
+    candidate = { ...candidate, tree:candidate.tree.slice(0,128),
+      tree_compaction:{ original_entries:originalEntries, kept_entries:128 } };
+  }
+  for (let i = Math.max(0,contexts.length - 1); i < contexts.length && !fits(); i += 1) {
+    contexts[i] = elideContextPayload(contexts[i]);
+  }
+  for (let i = Math.max(0,observations.length - 1); i < observations.length && !fits(); i += 1) {
+    observations[i] = elideObservationPayload(observations[i]);
+  }
+  if (!fits()) throw new Error('autonomous planner context exceeds policy budget after compaction');
+  return candidate;
+}
+export function buildPlannerPrompt({ goal, policy, view }) {
+  const profiles = Object.entries(policy.profiles).map(([id,p]) => ({ id, kind:p.kind,
+    required_for_release:p.required_for_release, description:p.description }));
+  let state = { goal, mutation_epoch:view.mutation_epoch, planner_round:view.planner_round,
+    tree:view.tree ?? [], contexts:view.contexts ?? [], observations:view.observations ?? [],
+    active_plan:view.active_plan ?? null, recent_decisions:view.recent_decisions ?? [], profiles };
+  state = compactPlannerState(state,policy.limits.max_context_bytes);
+  const stateJson = canonicalJson(state);
+  return [
+    'You are the DEADBYTE R24 autonomous coding planner.',
+    'Return exactly one JSON object and no Markdown or prose outside JSON.',
+    `The object schema is ${AUTONOMOUS_DECISION_SCHEMA}.`,
+    'Allowed actions: inspect, patch, delegate, run_profile, finish, pause.',
+    'For nontrivial work, include plan={title,steps:[{step_id,title,status,result?}],reason?} on decisions and keep it authoritative across rounds.',
+    'Plan statuses must be a completed prefix, then at most one running/failed step, then pending suffix. Completed steps are immutable across updates.',
+    'If active_plan is complete, request finish instead of more work. If active_plan is incomplete, do not request finish.',
+    'The plan is coordination state only; release profiles, Native Diff verification, and signed receipts remain the proof authority.',
+    'inspect: reads=[{path,max_bytes}] for source context you still need.',
+    'patch: operations are DEADBYTE Native Diff operations (write, replace, delete) and MUST use exact SHA-256 preconditions from supplied context.',
+    'run_profile: profile_id must be one of the policy profile ids in state.',
+    'delegate: operation is one bounded existing-runtime action. Allowed kinds: machine_stat, machine_list, machine_read, observation_search_start, observation_search_status, observation_search_page, observation_search_cancel, observation_process_list, observation_system_status, process_start, process_read, process_status, process_list, process_action, process_terminate.',
+    'Delegate paths are relative to the goal root. Process start accepts only profile_id and cwd; process_action accepts only session_id and fixed action_id. Never emit raw stdin, executable, PID, environment, shell command, or process arguments.',
+    'finish only when the goal is actually satisfied. Required release profiles are enforced by the engine and cannot be bypassed.',
+    'Never invent a file SHA. If content is elided or the current SHA/content is missing, choose inspect first.',
+    'Compacted context keeps identity/evidence metadata but intentionally removes stale payload bytes.',
+    'Prefer surgical exact replace operations over whole-file writes.',
+    'If an observed build/test/benchmark failed, diagnose from the evidence and change the source rather than claiming success.',
+    `STATE=${stateJson}`,
+    'Example shape: {"schema":"deadbyte.autonomous-decision.v1","action":"inspect","summary":"need parser source","reads":[{"path":"src/parser.mjs","max_bytes":65536}]}'
+  ].join('\n');
+}
+
+async function readBoundedResponse(response, limit) {
+  const length = Number(response.headers.get('content-length') ?? '0');
+  if (Number.isFinite(length) && length > limit) throw new Error('planner HTTP response exceeds content-length budget');
+  const bytes = Buffer.from(await response.arrayBuffer());
+  if (bytes.length > limit) throw new Error('planner HTTP response exceeds byte budget');
+  return bytes.toString('utf8');
+}
+export async function requestProviderDecision(policy, prompt, fetchImpl = fetch) {
+  if (policy.planner.backend !== 'openai_compatible') throw new Error('provider planner backend is not openai_compatible');
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), policy.planner.timeout_ms); timer.unref?.();
+  const headers = { 'content-type':'application/json', 'accept':'application/json' };
+  if (policy.planner.api_key_env) {
+    const secret = process.env[policy.planner.api_key_env];
+    if (typeof secret !== 'string' || secret.length < 1) throw new Error(`planner API key env '${policy.planner.api_key_env}' is unavailable`);
+    headers.authorization = `Bearer ${secret}`;
+  }
+  try {
+    const response = await fetchImpl(policy.planner.endpoint, {
+      method:'POST', redirect:'error', signal:controller.signal, headers,
+      body:JSON.stringify({ model:policy.planner.model, temperature:0,
+        max_tokens:policy.planner.max_tokens,
+        messages:[{ role:'system', content:'Return strict JSON only.' },{ role:'user', content:prompt }] })
+    });
+    const rawBody = await readBoundedResponse(response, policy.planner.max_response_bytes);
+    if (!response.ok) throw new Error(`planner HTTP ${response.status}: ${rawBody.slice(0,512)}`);
+    let parsed;
+    try { parsed = JSON.parse(rawBody); } catch { throw new Error('planner HTTP response is not JSON'); }
+    const content = parsed?.choices?.[0]?.message?.content;
+    if (typeof content !== 'string') throw new Error('planner HTTP response missing choices[0].message.content');
+    return { backend:'openai_compatible', model:typeof parsed.model === 'string' ? parsed.model : policy.planner.model,
+      raw_text:content };
+  } finally { clearTimeout(timer); }
+}

package/src/autonomous-policy.mjs

@@ -0,0 +1,146 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile } from 'node:fs/promises';
+import path from 'node:path';
+import { decodeUtf8Strict } from './text-policy.mjs';
+import { validatePortableRelativePath } from './path-policy.mjs';
+
+export const AUTONOMOUS_POLICY_SCHEMA = 'deadbyte.autonomous-policy.v1';
+export const AUTONOMOUS_LEASE_SCHEMA = 'deadbyte.autonomous-lease.v1';
+export const AUTONOMOUS_GRANT_SCHEMA = 'deadbyte.autonomous-grant.v2';
+const SHA256_RE = /^[0-9a-f]{64}$/;
+const ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
+const ENV_RE = /^[A-Z][A-Z0-9_]{0,63}$/;
+const sha256Bytes = bytes => createHash('sha256').update(bytes).digest('hex');
+function integer(value, name, min, max, fallback) {
+  const n = value ?? fallback;
+  if (!Number.isInteger(n) || n < min || n > max) throw new Error(`${name} must be in [${min}, ${max}]`);
+  return n;
+}
+function finite(value, name, min, max, fallback) {
+  const n = value ?? fallback;
+  if (!Number.isFinite(n) || n < min || n > max) throw new Error(`${name} must be in [${min}, ${max}]`);
+  return n;
+}
+function normalizePlanner(raw) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('autonomous planner missing');
+  const backend = raw.backend;
+  if (!['client_sampling', 'openai_compatible'].includes(backend)) throw new Error('autonomous planner backend invalid');
+  const common = { backend, max_tokens: integer(raw.max_tokens, 'planner.max_tokens', 256, 16384, 4096) };
+  if (backend === 'client_sampling') return common;
+  if (typeof raw.endpoint !== 'string') throw new Error('planner.endpoint required');
+  const endpoint = new URL(raw.endpoint);
+  const loopback = ['127.0.0.1', 'localhost', '::1'].includes(endpoint.hostname);
+  if (endpoint.protocol !== 'https:' && !(endpoint.protocol === 'http:' && loopback)) {
+    throw new Error('planner endpoint must be HTTPS or loopback HTTP');
+  }
+  if (endpoint.username || endpoint.password || endpoint.hash) throw new Error('planner endpoint credentials/fragments forbidden');
+  if (typeof raw.model !== 'string' || raw.model.length < 1 || raw.model.length > 128) throw new Error('planner.model invalid');
+  const apiKeyEnv = raw.api_key_env ?? null;
+  if (apiKeyEnv !== null && !ENV_RE.test(apiKeyEnv)) throw new Error('planner.api_key_env invalid');
+  return {
+    ...common, endpoint: endpoint.toString(), model: raw.model, api_key_env: apiKeyEnv,
+    timeout_ms: integer(raw.timeout_ms, 'planner.timeout_ms', 1000, 300000, 60000),
+    max_response_bytes: integer(raw.max_response_bytes, 'planner.max_response_bytes', 4096, 2 * 1024 * 1024, 512 * 1024)
+  };
+}
+function normalizeProfile(id, raw, codingPolicy) {
+  if (!ID_RE.test(id)) throw new Error(`invalid autonomous profile '${id}'`);
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error(`autonomous profile '${id}' malformed`);
+  if (!['command','benchmark'].includes(raw.kind)) throw new Error(`autonomous profile '${id}' kind invalid`);
+  if (!ID_RE.test(raw.root_id ?? '') || !codingPolicy.roots[raw.root_id]) throw new Error(`autonomous profile '${id}' root invalid`);
+  if (!ID_RE.test(raw.command_id ?? '') || !codingPolicy.commands[raw.command_id]) throw new Error(`autonomous profile '${id}' command invalid`);
+  validatePortableRelativePath(raw.script_path);
+  if (!SHA256_RE.test(raw.script_sha256 ?? '')) throw new Error(`autonomous profile '${id}' script hash invalid`);
+  const args = raw.args ?? [];
+  if (!Array.isArray(args) || args.length > 64 || args.some(v => typeof v !== 'string' || v.length > 2048 || v.includes('\0'))) {
+    throw new Error(`autonomous profile '${id}' args invalid`);
+  }
+  const cwd = raw.cwd ?? '.';
+  if (cwd !== '.') validatePortableRelativePath(cwd);
+  const base = {
+    kind: raw.kind, root_id: raw.root_id, command_id: raw.command_id,
+    script_path: raw.script_path, script_sha256: raw.script_sha256,
+    args: [...args], cwd,
+    timeout_ms: raw.timeout_ms === null || raw.timeout_ms === undefined ? null : integer(raw.timeout_ms, `profiles.${id}.timeout_ms`, 100, 900000, 300000),
+    required_for_release: raw.required_for_release === true,
+    run_after_mutation: raw.run_after_mutation === true,
+    description: typeof raw.description === 'string' ? raw.description.slice(0, 256) : ''
+  };
+  if (raw.kind === 'command') {
+    return { ...base, expect_exit_code: integer(raw.expect_exit_code, `profiles.${id}.expect_exit_code`, -2147483648, 2147483647, 0) };
+  }
+  return {
+    ...base,
+    warmups: integer(raw.warmups, `profiles.${id}.warmups`, 0, 3, 1),
+    iterations: integer(raw.iterations, `profiles.${id}.iterations`, 1, 20, 5),
+    baseline_median_ms: raw.baseline_median_ms ?? null,
+    max_regression_pct: finite(raw.max_regression_pct, `profiles.${id}.max_regression_pct`, 0, 1000, 5)
+  };
+}
+
+export async function loadAutonomousPolicy(policyPath, codingPolicy) {
+  if (!policyPath) throw new Error('missing DEADBYTE autonomous policy path');
+  if (!codingPolicy?.policy_sha256) throw new Error('autonomous policy requires loaded coding policy');
+  const absolute = path.resolve(policyPath);
+  const bytes = await readFile(absolute);
+  const raw = JSON.parse(decodeUtf8Strict(bytes));
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw) || raw.schema !== AUTONOMOUS_POLICY_SCHEMA || raw.enabled !== true) {
+    throw new Error('autonomous policy schema/enabled mismatch');
+  }
+  if (typeof raw.lease_file !== 'string' || !path.isAbsolute(raw.lease_file)) throw new Error('autonomous lease_file must be absolute');
+  if (typeof raw.evidence_dir !== 'string' || !path.isAbsolute(raw.evidence_dir)) throw new Error('autonomous evidence_dir must be absolute');
+  if (raw.coding_policy_sha256 !== codingPolicy.policy_sha256) throw new Error('autonomous policy coding_policy_sha256 mismatch');
+  const rootIds = Array.isArray(raw.root_ids) ? [...new Set(raw.root_ids)] : [];
+  if (rootIds.length < 1 || rootIds.some(id => !ID_RE.test(id) || !codingPolicy.roots[id])) throw new Error('autonomous root_ids invalid');
+  const profiles = {};
+  for (const [id, value] of Object.entries(raw.profiles ?? {})) profiles[id] = normalizeProfile(id, value, codingPolicy);
+  const limits = raw.limits ?? {};
+  const policy = {
+    schema: AUTONOMOUS_POLICY_SCHEMA, enabled: true, policy_path: absolute,
+    lease_file: path.resolve(raw.lease_file), evidence_dir: path.resolve(raw.evidence_dir),
+    coding_policy_sha256: codingPolicy.policy_sha256, root_ids: rootIds,
+    planner: normalizePlanner(raw.planner), profiles,
+    limits: {
+      max_iterations: integer(limits.max_iterations, 'limits.max_iterations', 1, 64, 12),
+      max_mutations: integer(limits.max_mutations, 'limits.max_mutations', 1, 128, 24),
+      max_wall_ms: limits.max_wall_ms === null ? null : integer(limits.max_wall_ms, 'limits.max_wall_ms', 60000, 14_400_000, 1_800_000),
+      max_context_bytes: integer(limits.max_context_bytes, 'limits.max_context_bytes', 65536, 8 * 1024 * 1024, 1024 * 1024),
+      max_diff_bytes: integer(limits.max_diff_bytes, 'limits.max_diff_bytes', 65536, 8 * 1024 * 1024, 1024 * 1024),
+      max_files_per_diff: integer(limits.max_files_per_diff, 'limits.max_files_per_diff', 1, 32, 8)
+    }
+  };
+  policy.policy_sha256 = sha256Bytes(bytes);
+  await mkdir(policy.evidence_dir, { recursive: true });
+  return Object.freeze(policy);
+}
+
+export async function autonomousSessionStatus(policy, now = new Date()) {
+  let lease;
+  try { lease = JSON.parse(decodeUtf8Strict(await readFile(policy.lease_file))); }
+  catch (error) {
+    return { configured:true, armed:false, reason:error?.code === 'ENOENT' ? 'disarmed' : 'invalid-lease', expires_at_utc:null };
+  }
+  if (!lease || ![AUTONOMOUS_GRANT_SCHEMA, AUTONOMOUS_LEASE_SCHEMA].includes(lease.schema)) {
+    return { configured:true, armed:false, reason:'lease-schema', expires_at_utc:null };
+  }
+  if (lease.policy_sha256 !== policy.policy_sha256) return { configured:true, armed:false, reason:'policy-digest', expires_at_utc:null };
+  if (typeof lease.instance_nonce !== 'string' || !SHA256_RE.test(lease.instance_nonce)) return { configured:true, armed:false, reason:'nonce-invalid', expires_at_utc:null };
+  const roots = Array.isArray(lease.root_ids) ? [...new Set(lease.root_ids)] : [];
+  if (roots.length < 1 || roots.some(id => !policy.root_ids.includes(id))) return { configured:true, armed:false, reason:'roots-invalid', expires_at_utc:null };
+  if (lease.schema === AUTONOMOUS_GRANT_SCHEMA) {
+    return { configured:true, armed:true, reason:'standing-grant', expires_at_utc:null,
+      remaining_ms:null, standing:true, instance_nonce:lease.instance_nonce, root_ids:roots };
+  }
+  const expires = Date.parse(lease.expires_at_utc);
+  if (!Number.isFinite(expires)) return { configured:true, armed:false, reason:'expiry-invalid', expires_at_utc:null };
+  if (expires <= now.getTime()) return { configured:true, armed:false, reason:'expired', expires_at_utc:lease.expires_at_utc };
+  return { configured:true, armed:true, reason:'legacy-timed-lease', expires_at_utc:lease.expires_at_utc,
+    remaining_ms:expires-now.getTime(), standing:false, instance_nonce:lease.instance_nonce, root_ids:roots };
+}
+
+export async function assertAutonomousArmed(policy, rootId = null, now = new Date()) {
+  const status = await autonomousSessionStatus(policy, now);
+  if (!status.armed) throw new Error(`autonomous plane is disarmed: ${status.reason}`);
+  if (rootId !== null && !status.root_ids.includes(rootId)) throw new Error(`autonomous root '${rootId}' is outside active lease`);
+  return status;
+}