deadbyte-mcp 0.8.9 → 0.9.0

package/src/autonomous-plan.mjs

@@ -0,0 +1,181 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+
+export const AUTONOMOUS_PLAN_SCHEMA = 'deadbyte.autonomous-plan.v1';
+const PLAN_ID_SCHEMA = 'deadbyte.autonomous-plan-id.v1';
+const HEX64 = /^[0-9a-f]{64}$/;
+const ID = /^[A-Za-z0-9._-]{1,64}$/;
+
+function sha256Object(value) {
+  return createHash('sha256').update(Buffer.from(canonicalJson(value),'utf8')).digest('hex');
+}
+
+function text(value,label,max) {
+  if (typeof value !== 'string' || value.length < 1 || value.length > max) throw new Error(`${label} invalid`);
+  return value;
+}
+
+function id(value,label) {
+  if (typeof value !== 'string' || !ID.test(value)) throw new Error(`${label} invalid`);
+  return value;
+}
+
+function hash(value,label) {
+  if (typeof value !== 'string' || !HEX64.test(value)) throw new Error(`${label} invalid`);
+  return value;
+}
+
+function normalizeEvidence(evidence) {
+  if (!Array.isArray(evidence) || evidence.length < 1 || evidence.length > 32) {
+    throw new Error('plan step completion evidence required');
+  }
+  return evidence.map((item,index) => {
+    if (!item || typeof item !== 'object' || Array.isArray(item)) throw new Error(`plan evidence ${index} invalid`);
+    const keys = Object.keys(item).sort();
+    if (canonicalJson(keys) !== canonicalJson(['id','kind','sha256'])) throw new Error(`plan evidence ${index} fields invalid`);
+    return {
+      kind:id(item.kind,`plan evidence ${index} kind`),
+      id:id(item.id,`plan evidence ${index} id`),
+      sha256:hash(item.sha256,`plan evidence ${index} sha256`)
+    };
+  });
+}
+
+function normalizeStepIdentity(raw,index) {
+  if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error(`plan step ${index} invalid`);
+  return {
+    step_id:id(raw.step_id,`plan step ${index} step_id`),
+    intent:text(raw.intent,`plan step ${index} intent`,512)
+  };
+}
+
+function assertUniqueStepIds(steps) {
+  const seen = new Set();
+  for (const step of steps) {
+    if (seen.has(step.step_id)) throw new Error(`plan step_id '${step.step_id}' duplicated`);
+    seen.add(step.step_id);
+  }
+}
+
+function assertPlan(plan) {
+  if (!plan || typeof plan !== 'object' || Array.isArray(plan) || plan.schema !== AUTONOMOUS_PLAN_SCHEMA) {
+    throw new Error('autonomous plan schema invalid');
+  }
+  hash(plan.plan_id,'plan_id');
+  if (!Number.isInteger(plan.plan_version) || plan.plan_version < 1) throw new Error('plan_version invalid');
+  if (plan.parent_plan_version !== null && (!Number.isInteger(plan.parent_plan_version) || plan.parent_plan_version < 1 || plan.parent_plan_version >= plan.plan_version)) {
+    throw new Error('parent_plan_version invalid');
+  }
+  text(plan.title,'plan title',160);
+  hash(plan.reason_sha256,'plan reason_sha256');
+  if (!Array.isArray(plan.steps) || plan.steps.length < 1 || plan.steps.length > 24) throw new Error('plan steps invalid');
+  assertUniqueStepIds(plan.steps);
+  let active = 0;
+  let seenMutable = false;
+  let seenPending = false;
+  for (const [index,step] of plan.steps.entries()) {
+    const identity = normalizeStepIdentity(step,index);
+    if (identity.step_id !== step.step_id || identity.intent !== step.intent) throw new Error(`plan step ${index} identity invalid`);
+    if (!['pending','active','completed'].includes(step.status)) throw new Error(`plan step ${index} status invalid`);
+    if (step.status === 'completed') {
+      if (seenMutable) throw new Error('plan completed steps must form an immutable prefix');
+      normalizeEvidence(step.evidence);
+    } else {
+      seenMutable = true;
+      if (step.evidence !== undefined) throw new Error(`plan step ${index} evidence requires completed status`);
+      if (step.status === 'active') {
+        if (seenPending || active > 0) throw new Error('plan may have at most one active step before pending suffix');
+        active += 1;
+      } else {
+        seenPending = true;
+      }
+    }
+  }
+  const complete = plan.steps.every(step => step.status === 'completed');
+  if (!complete && active !== 1) throw new Error('incomplete plan requires exactly one active step');
+  if (complete && active !== 0) throw new Error('complete plan cannot have active step');
+  return plan;
+}
+
+function completedPrefixLength(plan) {
+  let count = 0;
+  for (const step of plan.steps) {
+    if (step.status !== 'completed') break;
+    count += 1;
+  }
+  return count;
+}
+
+function normalizeSuffixStep(raw,index,status) {
+  const step = normalizeStepIdentity(raw,index);
+  if (raw.evidence !== undefined) throw new Error(`replan suffix step '${step.step_id}' cannot carry completion evidence`);
+  return { ...step, status };
+}
+
+export function createPlan({ goalId, title, steps, reasonHash }) {
+  hash(goalId,'goalId');
+  text(title,'plan title',160);
+  hash(reasonHash,'reasonHash');
+  if (!Array.isArray(steps) || steps.length < 1 || steps.length > 24) throw new Error('plan steps invalid');
+  const normalized = steps.map((step,index) => ({ ...normalizeStepIdentity(step,index), status:index === 0 ? 'active' : 'pending' }));
+  assertUniqueStepIds(normalized);
+  return assertPlan({
+    schema:AUTONOMOUS_PLAN_SCHEMA,
+    plan_id:sha256Object({ schema:PLAN_ID_SCHEMA, goal_id:goalId }),
+    plan_version:1,
+    parent_plan_version:null,
+    title,
+    steps:normalized,
+    reason_sha256:reasonHash
+  });
+}
+
+export function replanPlan(previous,{ steps, reasonHash }) {
+  assertPlan(previous);
+  hash(reasonHash,'reasonHash');
+  if (!Array.isArray(steps) || steps.length < 1 || steps.length > 24) throw new Error('replan steps invalid');
+  const locked = completedPrefixLength(previous);
+  if (steps.length < locked) throw new Error('replan cannot remove completed prefix');
+  for (let index = 0; index < locked; index += 1) {
+    if (canonicalJson(steps[index]) !== canonicalJson(previous.steps[index])) {
+      throw new Error(`replan cannot modify completed prefix step '${previous.steps[index].step_id}'`);
+    }
+  }
+  if (steps.length === locked) throw new Error('replan requires an active or pending suffix');
+  const completed = previous.steps.slice(0,locked).map(step => structuredClone(step));
+  const suffix = steps.slice(locked).map((step,index) => normalizeSuffixStep(step,locked + index,index === 0 ? 'active' : 'pending'));
+  const combined = [...completed,...suffix];
+  assertUniqueStepIds(combined);
+  return assertPlan({
+    schema:AUTONOMOUS_PLAN_SCHEMA,
+    plan_id:previous.plan_id,
+    plan_version:previous.plan_version + 1,
+    parent_plan_version:previous.plan_version,
+    title:previous.title,
+    steps:combined,
+    reason_sha256:reasonHash
+  });
+}
+
+export function completePlanStep(previous,{ stepId, evidence }) {
+  assertPlan(previous);
+  id(stepId,'stepId');
+  const activeIndex = previous.steps.findIndex(step => step.status === 'active');
+  if (activeIndex < 0) throw new Error('plan has no active step to complete');
+  if (previous.steps[activeIndex].step_id !== stepId) throw new Error(`plan step '${stepId}' is not active`);
+  const checkedEvidence = normalizeEvidence(evidence);
+  const steps = previous.steps.map(step => structuredClone(step));
+  steps[activeIndex] = { ...steps[activeIndex], status:'completed', evidence:checkedEvidence };
+  if (activeIndex + 1 < steps.length) steps[activeIndex + 1] = { ...steps[activeIndex + 1], status:'active' };
+  return assertPlan({ ...previous, steps });
+}
+
+export function planIsComplete(plan) {
+  assertPlan(plan);
+  return plan.steps.every(step => step.status === 'completed');
+}
+
+export function activePlanStep(plan) {
+  assertPlan(plan);
+  return plan.steps.find(step => step.status === 'active') ?? null;
+}

package/src/autonomous-planner-contracts.mjs

@@ -71,3 +71,47 @@ export function parseStrictJsonText(schema, text, label) {
   if (!checked.success) throw new Error(`${label} response contract mismatch`);
   return checked.data;
 }
+
+const r34PlanStepSchema = z.strictObject({
+  step_id:z.string().regex(ID),
+  intent:z.string().min(1).max(512)
+});
+const r34EvidenceSchema = z.strictObject({
+  kind:z.string().regex(ID),
+  id:z.string().regex(ID),
+  sha256:z.string().regex(HEX64)
+});
+const r34PatchOperationSchema = z.discriminatedUnion('kind',[
+  z.strictObject({kind:z.literal('write'),path:relPath,content:z.string().max(524288),
+    encoding:z.enum(['utf8','base64']).default('utf8'),expected_sha256:z.string().regex(/^(?:absent|[0-9a-f]{64})$/)}),
+  z.strictObject({kind:z.literal('replace'),path:relPath,old_string:z.string().min(1).max(262144),
+    new_string:z.string().max(524288),expected_sha256:z.string().regex(HEX64),
+    expected_replacements:z.number().int().min(1).max(64).default(1)}),
+  z.strictObject({kind:z.literal('delete'),path:relPath,expected_sha256:z.string().regex(HEX64)})
+]);
+const r34ActionSchema = z.discriminatedUnion('kind',[
+  z.strictObject({kind:z.literal('patch'),operations:z.array(r34PatchOperationSchema).min(1).max(32)}),
+  z.strictObject({kind:z.literal('run_profile'),profile_id:z.string().regex(ID)}),
+  z.strictObject({kind:z.literal('delegate'),operation:z.record(z.string(),z.json())})
+]);
+const r34ReadSchema = z.strictObject({
+  path:relPath,
+  max_bytes:z.number().int().min(1).max(262144).default(65536)
+});
+
+export const r34PlannerDecisionSchema = z.discriminatedUnion('kind',[
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('plan_create'),
+    title:z.string().min(1).max(160),reason:z.string().min(1).max(512).optional(),
+    steps:z.array(r34PlanStepSchema).min(1).max(24)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('inspect'),
+    reads:z.array(r34ReadSchema).min(1).max(8)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('act'),action:r34ActionSchema}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('step_complete'),
+    step_id:z.string().regex(ID),evidence:z.array(r34EvidenceSchema).min(1).max(32)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('replan'),
+    reason:z.string().min(1).max(512),steps:z.array(r34PlanStepSchema).min(1).max(24)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('pause'),
+    reason:z.string().min(1).max(1000)}),
+  z.strictObject({schema:z.literal('deadbyte.autonomous-decision.v2'),kind:z.literal('finish'),
+    summary:z.string().min(1).max(1024).optional()})
+]);

package/src/autonomous-planner.mjs

@@ -1,7 +1,11 @@
+import { createHash } from 'node:crypto';
 import { canonicalJson } from './canonical-json.mjs';
+import { buildLoopContext } from './autonomous-context-engine.mjs';
+import { r34PlannerDecisionSchema } from './autonomous-planner-contracts.mjs';
 import { validatePortableRelativePath } from './path-policy.mjs';
 
 export const AUTONOMOUS_DECISION_SCHEMA = 'deadbyte.autonomous-decision.v1';
+export const AUTONOMOUS_R34_DECISION_SCHEMA = 'deadbyte.autonomous-decision.v2';
 const ID_RE = /^[A-Za-z0-9._-]{1,64}$/;
 const SHA256_RE = /^[0-9a-f]{64}$/;
 function strictKeys(value, allowed, label) {
@@ -178,6 +182,73 @@ export function parsePlannerDecision(rawText, policy) {
   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 assertR34UniqueSteps(steps,label) {
+  const seen = new Set();
+  for (const step of steps) {
+    if (seen.has(step.step_id)) throw new Error(`${label} duplicate step_id '${step.step_id}'`);
+    seen.add(step.step_id);
+  }
+}
+
+export function parseR34PlannerDecision(rawText, policy) {
+  if (typeof rawText !== 'string' || rawText.length < 2 || rawText.length > policy.limits.max_context_bytes) {
+    throw new Error('R34 planner structured response size invalid');
+  }
+  const trimmed = rawText.trim();
+  if (!trimmed.startsWith('{') || !trimmed.endsWith('}')) {
+    throw new Error('R34 planner structured response must be one raw JSON object');
+  }
+  let raw;
+  try { raw = JSON.parse(trimmed); }
+  catch (error) { throw new Error(`R34 planner JSON invalid: ${error.message}`); }
+  const checked = r34PlannerDecisionSchema.safeParse(raw);
+  if (!checked.success) throw new Error('R34 planner decision contract mismatch');
+  const decision = checked.data;
+  if (decision.schema !== AUTONOMOUS_R34_DECISION_SCHEMA) throw new Error('R34 planner decision schema mismatch');
+
+  if (decision.kind === 'plan_create') {
+    assertR34UniqueSteps(decision.steps,'R34 plan_create');
+    return decision;
+  }
+  if (decision.kind === 'inspect') {
+    return { ...decision, reads:decision.reads.map(item => {
+      validatePortableRelativePath(item.path);
+      return { path:item.path, max_bytes:item.max_bytes };
+    }) };
+  }
+  if (decision.kind === 'act') {
+    if (decision.action.kind === 'patch') {
+      if (decision.action.operations.length > policy.limits.max_files_per_diff) throw new Error('R34 patch operation count exceeds policy');
+      return { ...decision, action:{ kind:'patch', operations:decision.action.operations.map(normalizeOperation) } };
+    }
+    if (decision.action.kind === 'run_profile') {
+      if (!policy.profiles?.[decision.action.profile_id]) throw new Error('R34 planner profile_id invalid');
+      return decision;
+    }
+    if (decision.action.kind === 'delegate') {
+      return { ...decision, action:{ kind:'delegate', operation:normalizeDelegatedOperation(decision.action.operation) } };
+    }
+    throw new Error('R34 planner authority or unsupported action');
+  }
+  if (decision.kind === 'step_complete') return decision;
+  if (decision.kind === 'replan') {
+    assertR34UniqueSteps(decision.steps,'R34 replan');
+    return decision;
+  }
+  if (decision.kind === 'pause' || decision.kind === 'finish') return decision;
+  throw new Error('R34 planner decision kind unsupported');
+}
+
+export async function requestR34ProviderDecision(policy,prompt,fetchImpl = fetch) {
+  const response = await requestProviderDecision(policy,prompt,fetchImpl);
+  return {
+    backend:response.backend,
+    model:response.model,
+    raw_response_sha256:createHash('sha256').update(Buffer.from(response.raw_text,'utf8')).digest('hex'),
+    decision:parseR34PlannerDecision(response.raw_text,policy)
+  };
+}
+
 function plannerStateBytes(state) {
   return Buffer.byteLength(canonicalJson(state),'utf8');
 }
@@ -223,12 +294,26 @@ function compactPlannerState(state, limit) {
   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 state = buildLoopContext({
+    goal,
+    policy,
+    loopState:{
+      phase:view.loop?.phase ?? null,
+      mutation_epoch:Number.isInteger(view.mutation_epoch) ? view.mutation_epoch : (view.loop?.mutation_epoch ?? 0),
+      planner_round:Number.isInteger(view.planner_round) ? view.planner_round : (view.loop?.planner_round ?? 0),
+      plan:view.loop?.plan ?? view.active_plan ?? null,
+      active_plan:view.active_plan ?? view.loop?.plan ?? null,
+      current_step:view.loop?.current_step ?? null,
+      plan_id:view.loop?.plan_id ?? null,
+      plan_version:view.loop?.plan_version ?? null,
+      replan_count:view.loop?.replan_count ?? 0
+    },
+    tree:view.tree ?? [],
+    contexts:view.contexts ?? [],
+    observations:view.observations ?? [],
+    decisions:view.recent_decisions ?? [],
+    projectMemory:view.project_memory ?? null
+  });
   const stateJson = canonicalJson(state);
   return [
     'You are the DEADBYTE R24 autonomous coding planner.',

package/src/autonomous-policy.mjs

@@ -21,6 +21,15 @@ function finite(value, name, min, max, fallback) {
   if (!Number.isFinite(n) || n < min || n > max) throw new Error(`${name} must be in [${min}, ${max}]`);
   return n;
 }
+function normalizeProviderCircuit(raw) {
+  const value=raw ?? {};
+  if (!value || typeof value !== 'object' || Array.isArray(value)) throw new Error('planner.circuit invalid');
+  return Object.freeze({
+    failure_threshold:integer(value.failure_threshold,'planner.circuit.failure_threshold',1,32,3),
+    open_ms:integer(value.open_ms,'planner.circuit.open_ms',100,3_600_000,30_000),
+    half_open_probe_limit:integer(value.half_open_probe_limit,'planner.circuit.half_open_probe_limit',1,8,1)
+  });
+}
 function normalizePlanner(raw) {
   if (!raw || typeof raw !== 'object' || Array.isArray(raw)) throw new Error('autonomous planner missing');
   const backend = raw.backend;
@@ -40,7 +49,8 @@ function normalizePlanner(raw) {
   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)
+    max_response_bytes: integer(raw.max_response_bytes, 'planner.max_response_bytes', 4096, 2 * 1024 * 1024, 512 * 1024),
+    circuit:normalizeProviderCircuit(raw.circuit)
   };
 }
 function normalizeProfile(id, raw, codingPolicy) {
@@ -106,7 +116,10 @@ export async function loadAutonomousPolicy(policyPath, codingPolicy) {
       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)
+      max_files_per_diff: integer(limits.max_files_per_diff, 'limits.max_files_per_diff', 1, 32, 8),
+      max_stalled_cycles: integer(limits.max_stalled_cycles, 'limits.max_stalled_cycles', 1, 32, 2),
+      max_post_replan_stalls: integer(limits.max_post_replan_stalls, 'limits.max_post_replan_stalls', 1, 32, 2),
+      max_replans: integer(limits.max_replans, 'limits.max_replans', 1, 32, 8)
     }
   };
   policy.policy_sha256 = sha256Bytes(bytes);

package/src/autonomous-progress.mjs

@@ -0,0 +1,127 @@
+import { createHash } from 'node:crypto';
+import { canonicalJson } from './canonical-json.mjs';
+
+const POSITIVE_REASONS = Object.freeze([
+  'new_source_identity',
+  'new_profile_evidence',
+  'verified_mutation_epoch_advanced',
+  'acceptance_failure_resolved',
+  'plan_step_completed',
+  'diagnostic_narrowed',
+  'interrupted_action_recovered',
+  'release_readiness_improved'
+]);
+
+const STALL_REASONS = Object.freeze([
+  'equivalent_decision_no_new_evidence',
+  'identical_read_repeated',
+  'identical_profile_failure_repeated',
+  'equivalent_replan',
+  'plan_oscillation'
+]);
+
+function sha256Object(value) {
+  return createHash('sha256').update(Buffer.from(canonicalJson(value),'utf8')).digest('hex');
+}
+
+function stripPlannerText(value) {
+  if (Array.isArray(value)) return value.map(stripPlannerText);
+  if (!value || typeof value !== 'object') return value;
+  const out = {};
+  for (const [key,item] of Object.entries(value)) {
+    if (['rationale','summary','explanation','planner_reason'].includes(key)) continue;
+    out[key] = stripPlannerText(item);
+  }
+  return out;
+}
+
+function finiteNumber(value,fallback = 0) {
+  return Number.isFinite(value) ? value : fallback;
+}
+
+function add(reasons,reason,condition) {
+  if (condition && !reasons.includes(reason)) reasons.push(reason);
+}
+
+export function judgeProgress({ before = {}, after = {}, decision = {}, evidence = {} } = {}) {
+  const positive = [];
+  const stalled = [];
+  const regressed = [];
+
+  add(positive,'new_source_identity',evidence.new_source_identity === true ||
+    (typeof before.source_sha256 === 'string' && typeof after.source_sha256 === 'string' && before.source_sha256 !== after.source_sha256));
+  add(positive,'new_profile_evidence',evidence.new_profile_evidence === true);
+  add(positive,'verified_mutation_epoch_advanced',evidence.native_diff_verified === true &&
+    Number.isInteger(before.mutation_epoch) && Number.isInteger(after.mutation_epoch) && after.mutation_epoch > before.mutation_epoch);
+  add(positive,'acceptance_failure_resolved',finiteNumber(before.acceptance_failures) > finiteNumber(after.acceptance_failures));
+  add(positive,'plan_step_completed',evidence.step_evidence_verified === true &&
+    finiteNumber(after.completed_steps) > finiteNumber(before.completed_steps));
+  add(positive,'diagnostic_narrowed',evidence.diagnostic_narrowed === true);
+  add(positive,'interrupted_action_recovered',evidence.interrupted_action_recovered === true);
+  add(positive,'release_readiness_improved',evidence.release_readiness_improved === true ||
+    (before.release_ready === false && after.release_ready === true));
+
+  add(stalled,'equivalent_decision_no_new_evidence',evidence.equivalent_decision === true);
+  add(stalled,'identical_read_repeated',evidence.same_source_sha === true);
+  add(stalled,'identical_profile_failure_repeated',evidence.identical_profile_failure === true);
+  add(stalled,'equivalent_replan',evidence.equivalent_replan === true);
+  add(stalled,'plan_oscillation',evidence.plan_oscillation === true);
+
+  add(regressed,'acceptance_failures_increased',finiteNumber(after.acceptance_failures) > finiteNumber(before.acceptance_failures));
+  add(regressed,'release_readiness_regressed',before.release_ready === true && after.release_ready === false);
+
+  let verdict = 'stalled';
+  let score = 0;
+  let reasonCodes;
+  if (positive.length > 0) {
+    verdict = 'progress';
+    score = positive.length;
+    reasonCodes = positive;
+  } else if (regressed.length > 0) {
+    verdict = 'regressed';
+    score = -regressed.length;
+    reasonCodes = regressed;
+  } else {
+    reasonCodes = stalled.length > 0 ? stalled : ['no_machine_progress_signal'];
+  }
+
+  const fingerprint = sha256Object({
+    before:stripPlannerText(before),
+    after:stripPlannerText(after),
+    decision:stripPlannerText(decision),
+    evidence:stripPlannerText(evidence),
+    verdict,
+    reason_codes:reasonCodes
+  });
+
+  return Object.freeze({ verdict, score, reason_codes:Object.freeze([...reasonCodes]), fingerprint });
+}
+
+function integerLimit(limits,name) {
+  const value = limits?.[name];
+  if (!Number.isInteger(value) || value < 1 || value > 32) throw new Error(`progress ${name} invalid`);
+  return value;
+}
+
+export function stallDisposition({ history = [], limits } = {}) {
+  if (!Array.isArray(history)) throw new Error('progress history must be an array');
+  const maxStalled = integerLimit(limits,'max_stalled_cycles');
+  const maxPostReplan = integerLimit(limits,'max_post_replan_stalls');
+  const maxReplans = integerLimit(limits,'max_replans');
+  const replanCount = history.filter(item => item === 'replan').length;
+  if (replanCount >= maxReplans) return { action:'wait', reason:'replan_limit_reached' };
+
+  let trailingStalls = 0;
+  for (let index = history.length - 1; index >= 0 && history[index] === 'stalled'; index -= 1) trailingStalls += 1;
+  const lastReplan = history.lastIndexOf('replan');
+  if (lastReplan >= 0 && trailingStalls >= maxPostReplan) {
+    return { action:'wait', reason:'post_replan_stall_threshold_reached' };
+  }
+  if (lastReplan < 0 && trailingStalls >= maxStalled) {
+    return { action:'replan', reason:'stall_threshold_reached' };
+  }
+  return { action:'continue', reason:'within_progress_budget' };
+}
+
+export const AUTONOMOUS_PROGRESS_POSITIVE_REASONS = POSITIVE_REASONS;
+export const AUTONOMOUS_PROGRESS_STALL_REASONS = STALL_REASONS;