@milpa/comal 0.0.0-stage → 0.1.1

package/src/work-plan.mjs

@@ -0,0 +1,509 @@
+import { randomUUID } from 'node:crypto';
+import { digest } from './operations.mjs';
+import { auditExecution } from './audit.mjs';
+import { readOnlyWorkCheck, runtimeBoundReadCheck, RUNTIME_CHECK_IDS } from './read-only-check.mjs';
+import { checkContractIssues, proposeCheckRepairs } from './work-check-contracts.mjs';
+import { assertionSchema, assertOutput, validateAssertions } from './work-assertions.mjs';
+import { nativeWorkParent, recoveryInput } from './work-recovery-proof.mjs';
+
+// Host-only compatibility for already accepted workflows. Never a tool argument.
+const artifactObservers = new WeakMap();
+const artifactCall = (house, sessionId, file_path) => artifactObservers.get(house)?.get(sessionId) === 'Read'
+  ? ['Read', { file_path }] : ['FileInfo', { file_path, hash: true }];
+
+export const WORK_NAMES = ['WorkPlanSet', 'WorkCheckRepair', 'WorkTaskUpdate', 'WorkStepRun', 'WorkDraft', 'WorkBoard'];
+const id = { type: 'string', pattern: '^[A-Za-z0-9][A-Za-z0-9_.:-]{0,63}$' }, version = { type: 'integer', minimum: 0 };
+const args = { type: 'object' }, str = maxLength => ({ type: 'string', minLength: 1, maxLength });
+const schema = (properties, required) => ({ type: 'object', properties, required, additionalProperties: false });
+const keyOf = (task, step) => JSON.stringify([task, step]);
+const failure = (message, code = 'WORK_CONFLICT') => Object.assign(new Error(message), { code });
+export const planControl = work => ({ plan_exists: Boolean(work?.plan), expected_version: work?.plan?.version || 0,
+  operation: 'WorkPlanSet', suggestion: 'Start with one small task; id/title/criterion/checks. Checks use exact operation names and arguments. Plan grants no permission.' });
+
+// A generation owns produced work; its current check definition has a separate hash.
+export const workDigest = task => task?.work_digest || task?.definition_digest;
+const definitionOf = task => Object.fromEntries(['id','title','criterion','phase','capabilities','artifacts','depends_on','checks'].filter(key => task[key] !== undefined).map(key => [key,task[key]]));
+const isMcpCheck = check => /^mcp(?:__|:)/.test(check.operation);
+const mcpServer = check => /^mcp:([^\s]+)/.exec(check.operation)?.[1] || /^mcp__(.+?)__/.exec(check.operation)?.[1];
+
+// A reservation is not evidence of target dispatch. Derive this narrow outcome
+// from the closed native coordinator and its exact artifact-read children, never
+// from a model claim, an absent receipt alone, or a mutable status flag. Older
+// books have no phase facts; the same sealed parent/child proof applies to them.
+function preflightFailure(session, step, task, audit, active) {
+  const rows = session.rows || [];
+  if (!audit.journal.verified || audit.violations.length || audit.unverified.length || active.has(step.invocation_id) || digest(step.arguments) !== step.arguments_digest) return null;
+  const own = row => row.house === session.cwd && row.session_id === session.id && row.surface === step.surface && digest(row.actor ?? null) === digest(step.actor ?? null);
+  if (!own(step) || step.source !== 'work_host' || !task.artifacts?.length) return null;
+  const parents = rows.filter(row => row.type === 'house_proposal' && row.invocation_id === step.invocation_id);
+  const endings = rows.filter(row => row.type === 'house_receipt' && row.invocation_id === step.invocation_id);
+  const parent = parents[0], ending = endings[0], closeRef = rows.indexOf(ending);
+  const parentContract = rows.findLast(row => row.type === 'house_contract' && row.contract_digest === parent?.contract_digest)?.contract;
+  const managed = parent?.operation === 'WorkTaskUpdate' && parentContract?.name === 'WorkTaskUpdate' && parentContract.origin === null && parentContract.permission === 'WorkTaskUpdate';
+  if (parents.length !== 1 || endings.length !== 1 || !own(parent) || !own(ending) || !(managed || parent.operation === 'WorkStepRun' && nativeWorkParent(rows, parent)) || ending.status !== 'failed' || closeRef <= step.ref) return null;
+  const same = (a, b) => ['operation','arguments_digest','contract_digest','parent_invocation_id','work','origin','execution_process'].every(key => digest(a[key] ?? null) === digest(b[key] ?? null));
+  const start = rows.find(row => row.type === 'house_started' && row.invocation_id === parent.invocation_id);
+  if (!start || !own(start) || !same(parent, start) || !same(parent, ending)) return null;
+  const input = recoveryInput(rows, parent, step.ref + 1);
+  const check = task.checks.find(check => check.step_id === step.step_id);
+  if (!check || check.operation !== step.operation || digest(check.arguments) !== step.arguments_digest || !input || input.plan_version !== step.plan_version) return null;
+  if (managed ? input.status !== 'done' || input.verify !== true || input.task_id !== step.task_id && task.status !== 'done' || !readOnlyWorkCheck(check.operation, check.arguments)
+    : input.task_id !== step.task_id || input.step_id !== step.step_id || input.operation !== undefined && input.operation !== step.operation || input.arguments !== undefined && digest(input.arguments) !== step.arguments_digest) return null;
+  const parentPhases = rows.filter(row => row.invocation_id === parent.invocation_id && ['work_step_preflight','work_step_dispatching','work_step_not_dispatched'].includes(row.type));
+  const phases = parentPhases.filter(row => row.attempt_id === step.attempt_id);
+  if ((managed || parentPhases.length) && !phases.length) return null;
+  if (phases.some(row => !own(row) || row.source !== 'work_host' || row.attempt_id !== step.attempt_id || row.task_id !== step.task_id || row.step_id !== step.step_id || row.task_digest !== step.task_digest || row.plan_version !== step.plan_version || rows.indexOf(row) <= step.ref || rows.indexOf(row) >= closeRef)) return null;
+  if (phases.some(row => row.type === 'work_step_dispatching')) return null;
+  if (managed && rows.slice(step.ref + 1, closeRef).some(row => row.type === 'work_step_started' && row.invocation_id === parent.invocation_id)) return null;
+  const children = rows.filter((row, ref) => row.type === 'house_proposal' && row.parent_invocation_id === parent.invocation_id && (!managed || ref > step.ref));
+  if (!children.length) return null;
+  const childRefs = [];
+  for (const child of children) {
+    const ref = rows.indexOf(child), contract = rows.findLast(row => row.type === 'house_contract' && row.contract_digest === child.contract_digest)?.contract;
+    // A work-tagged or arbitrary child might already have performed the target.
+    if (ref <= step.ref || ref >= closeRef || !own(child) || digest(child.execution_process ?? null) !== digest(parent.execution_process ?? null) || child.work || !['Read','FileInfo'].includes(child.operation) || !contract || contract.origin !== null || contract.permission !== child.operation || contract.name !== child.operation || contract.steps || contract.effects?.workspace !== 'read' || ['external','process','authority'].some(key => contract.effects?.[key] !== 'none')) return null;
+    const expected = task.artifacts.map(file => digest(child.operation === 'Read' ? { file_path: file, offset: 1, limit: 1 } : { file_path: file, hash: true }));
+    if (!expected.includes(child.arguments_digest)) return null;
+    const receipts = rows.filter(row => row.type === 'house_receipt' && row.invocation_id === child.invocation_id), receipt = receipts[0], receiptRef = rows.indexOf(receipt);
+    if (receipts.length !== 1 || !own(receipt) || !same(child, receipt) || receiptRef <= ref || receiptRef >= closeRef || !['returned','failed','refused'].includes(receipt.status)) return null;
+    const began = rows.find(row => row.type === 'house_started' && row.invocation_id === child.invocation_id);
+    if (receipt.status !== 'refused' && (!began || !own(began) || !same(child, began))) return null;
+    childRefs.push(receiptRef);
+  }
+  const failed = rows[childRefs.at(-1)];
+  const failedPhase = phases.find(row => row.type === 'work_step_not_dispatched' && row.error === failed.error);
+  if (!['failed','refused'].includes(failed.status) || failed.code !== ending.code || failed.error !== ending.error && !(managed && failedPhase)) return null;
+  if (phases.length && (!phases.some(row => row.type === 'work_step_preflight') || !phases.some(row => row.type === 'work_step_not_dispatched' && row.code === (ending.code || 'WORK_PREFLIGHT_FAILED')))) return null;
+  return { parent_receipt_id: parent.invocation_id, parent_receipt_ref: closeRef, preflight_receipt_refs: childRefs, code: ending.code || 'WORK_PREFLIGHT_FAILED', error: ending.error, target_dispatched: false, derivation: phases.length ? 'recorded_preflight_failure' : 'legacy_closed_preflight_failure',
+    ...(managed ? { retry_call: { name: 'WorkTaskUpdate', input: { task_id: input.task_id, plan_version: input.plan_version, status: 'done', verify: true } } } : {}) };
+}
+
+// A board is a fold of host facts. Model prose, nested receipts and thinking are not facts.
+export function foldWorkBook(session, { active = new Set() } = {}) {
+  let plan = null, checkpoint = null; const tasks = new Map(), steps = new Map(), drafts = new Map(), waiting = new Map(), attestations = new Map(), draftCalls = new Map(), draftInputs = new Map();
+  for (let i = 0; i < (session.rows || []).length; i++) {
+    const row = session.rows[i];
+    if (row.type === 'reset') { plan = null; checkpoint = null; tasks.clear(); steps.clear(); drafts.clear(); waiting.clear(); attestations.clear(); }
+    if (row.type === 'message' && row.message.role === 'assistant' && Array.isArray(row.message.content)) for (const call of row.message.content) if (call.type === 'tool_use' && call.name === 'WorkDraft') draftCalls.set(JSON.stringify([call.id,digest(call.input)]),call.input);
+    if (row.type === 'house_proposal' && row.operation === 'WorkDraft') draftInputs.set(row.invocation_id,draftCalls.get(JSON.stringify([row.call_id,row.arguments_digest])));
+    if (row.type === 'house_waiting') waiting.set(row.question_id, row);
+    if (row.type === 'house_answered') waiting.delete(row.question_id);
+    if (['work_plan_set','work_checks_repaired'].includes(row.type) && row.source === 'work_host') {
+      plan = { version: row.version, digest: row.plan_digest, objective: row.objective, ref: i, supersedes: row.supersedes };
+      const previous = new Map(tasks); tasks.clear();
+      for (const definition of row.tasks) {
+        const old = previous.get(definition.id);
+        tasks.set(definition.id, old && workDigest(old) === workDigest(definition) ? { ...old, ...definition, plan_version: plan.version } : { ...definition, plan_version: plan.version, status: 'pending', receipt_ids: [], last_step: null });
+      }
+      // Only an explicit check-repair fact keeps the work generation across a new definition.
+      for (const [key, step] of steps) if (workDigest(tasks.get(step.task_id)) !== step.task_digest) steps.delete(key);
+      for (const [key, draft] of drafts) if (workDigest(tasks.get(draft.task_id)) !== draft.task_digest) drafts.delete(key);
+      for (const repair of row.repairs || []) { steps.delete(keyOf(repair.task_id,repair.step_id)); attestations.delete(keyOf(repair.task_id,repair.step_id)); }
+    }
+    if (row.source === 'work_host' && workDigest(tasks.get(row.task_id)) === row.task_digest) {
+      const task = tasks.get(row.task_id);
+      if (row.type === 'work_task_changed') Object.assign(task, { status: row.status, reason: row.reason, receipt_ids: row.receipt_ids || [], dependency_proofs: row.dependency_proofs || {}, ref: i });
+      if (row.type === 'work_check_verified') attestations.set(keyOf(row.task_id, row.step_id), { ...row, ref: i });
+      if (row.type === 'work_step_started') { steps.set(keyOf(row.task_id, row.step_id), { ...row, ref: i, status: active.has(row.invocation_id) ? 'running' : 'interrupted', receipt_id: null }); task.last_step = row.step_id; }
+      if (row.type === 'work_draft_chunk') {
+        const key = keyOf(row.task_id, row.draft_id), draft = drafts.get(key) || { id: row.draft_id, task_id: row.task_id, task_digest: row.task_digest, file_path: row.file_path, parts: [], refs: [], part_ids: [] };
+        draft.parts[row.index] = row.content; draft.refs[row.index] = i; (draft.part_ids ||= [])[row.index] = row.part_id || null; draft.complete = row.final;
+        const input = draftInputs.get(row.invocation_id);
+        draft.next_action = row.next_action || (input?.content === row.content && input.task_id === row.task_id && input.draft_id === row.draft_id && input.file_path === row.file_path ? input.next_action : undefined);
+        drafts.set(key, draft);
+      }
+    }
+    if (row.type === 'house_receipt' && row.work) {
+      const step = steps.get(keyOf(row.work.task_id, row.work.step_id));
+      if (step && step.attempt_id === row.work.attempt_id && step.operation === row.operation && step.arguments_digest === row.arguments_digest && step.task_digest === row.work.task_digest && row.parent_invocation_id === step.invocation_id) Object.assign(step, { status: row.status, receipt_id: row.invocation_id, receipt_ref: i, output_digest: row.output_digest });
+    }
+    if (row.type === 'work_checkpoint' && row.source === 'work_host') checkpoint = { ...row, ref: i };
+  }
+  const audit = auditExecution(session), receipts = new Map(audit.receipts.map(row => [row.invocation_id, row]));
+  for (const step of steps.values()) if (step.status === 'interrupted') {
+    // auditExecution admits a recovery receipt only after checking its native
+    // derivation; a resealed recovery label alone cannot erase an unknown effect.
+    const recovered = receipts.get(step.invocation_id);
+    if (audit.journal.verified && !audit.violations.length && !audit.unverified.length && recovered?.recovery?.kind === 'work_not_dispatched' && recovered.code === 'HOUSE_RECOVERY_NOT_DISPATCHED' && recovered.status === 'refused') {
+      Object.assign(step, { status: 'refused', recovery_ref: recovered.evidence_row }); continue;
+    }
+    const task = tasks.get(step.task_id), proof = task && preflightFailure(session, step, task, audit, active);
+    if (proof) Object.assign(step, { status: 'refused', preflight_failure: proof, recovery_ref: proof.parent_receipt_ref,
+      next_action: 'The target was not dispatched: an artifact preflight failed. Prepare the missing or invalid output with new work, then retry this original step under current permissions. No failed check was credited.' });
+  }
+  const receiptValid = receipt => {
+    if (!receipt || receipt.status !== 'returned' || receipt.output_truncated || !audit.journal.consistent) return false;
+    if (audit.violations.some(v => v.invocation_id === receipt.invocation_id) || audit.unverified.some(v => v.invocation_id === receipt.invocation_id)) return false;
+    return (receipt.observations || []).every(observation => !['file_write', 'file_read'].includes(observation.kind) || audit.state.find(state => state.path === observation.file_path)?.sha256 === (observation.after_sha256 || observation.sha256));
+  };
+  const checkValid = (task, check, step) => {
+    const receipt = receipts.get(step?.receipt_id);
+    if (!receiptValid(receipt)) return false;
+    if (!check.assertions?.length && !task.artifacts?.length) return true;
+    const proof = attestations.get(keyOf(task.id, check.step_id));
+    if (!proof?.passed || proof.task_digest !== workDigest(task) || proof.attempt_id !== step.attempt_id || proof.receipt_id !== receipt.invocation_id || proof.assertions_digest !== digest(check.assertions || [])) return false;
+    try { assertOutput(receipt.output, check.assertions); } catch { return false; }
+    return (proof.artifact_receipts || []).every(id => receiptValid(receipts.get(id))) && (task.artifacts?.length || 0) === (proof.artifact_count || 0);
+  };
+  for (const task of tasks.values()) {
+    task.declared_status = task.status;
+    // Latest accepted state is derived; a done claim loses currency after a recorded touch.
+    if (task.status === 'done' && (!task.receipt_ids.length || !task.receipt_ids.every(receiptId => receiptValid(receipts.get(receiptId))) || !task.checks.every(check => checkValid(task, check, steps.get(keyOf(task.id, check.step_id)))))) { task.status = 'needs_verification'; task.reason = 'Una comprobación perdió vigencia en el libro.'; }
+  }
+  for (let pass = 0; pass < tasks.size; pass++) for (const task of tasks.values()) {
+    task.held_by = task.depends_on.filter(parent => tasks.get(parent)?.status !== 'done');
+    if (task.held_by.length && ['pending', 'in_progress'].includes(task.status)) task.status = 'blocked';
+    if (task.status === 'done' && task.depends_on.some(parent => digest(tasks.get(parent)?.receipt_ids || []) !== task.dependency_proofs?.[parent])) { task.status = 'needs_verification'; task.reason = 'La evidencia de una dependencia cambió; vuelve a comprobar esta tarea.'; }
+    if (task.held_by.length && task.status === 'done') { task.status = 'needs_verification'; task.reason = 'Una dependencia perdió su cierre vigente.'; }
+  }
+  for (const task of tasks.values()) {
+    const awaitsHuman = [...waiting.values()].some(question => [...steps.values()].some(step => step.task_id === task.id && (question.parent_invocation_id === step.invocation_id || question.invocation_id === step.invocation_id)));
+    if (task.status === 'in_progress' && awaitsHuman) { task.status = 'blocked'; task.reason = 'Espera una respuesta humana.'; task.held_by = ['human_permission']; }
+  }
+  for (const draft of drafts.values()) { const content = draft.parts.join(''); draft.digest = digest(content); draft.bytes = Buffer.byteLength(content); }
+  return { plan, tasks: [...tasks.values()], steps: [...steps.values()], drafts: [...drafts.values()], checkpoint, receipts, receiptValid, checkValid, attestations };
+}
+
+export function workProjection(session, context = {}) {
+  const book = foldWorkBook(session, context); if (!book.plan) return null;
+  const active = book.tasks.find(task => task.declared_status === 'in_progress');
+  const recoverable = book.tasks.find(task => task.status === 'blocked' && !task.held_by.length && book.steps.some(step => step.task_id === task.id && step.preflight_failure));
+  const next = active || recoverable || book.tasks.find(task => ['pending', 'needs_verification'].includes(task.status) && !task.held_by.length);
+  const summarize = task => ({ id: task.id, title: task.title, status: task.status, held_by: task.held_by, last_step: task.last_step, ...(task.phase ? { phase: task.phase } : {}), ...(task.reason ? { reason: task.reason } : {}) });
+  const checks = next?.checks.map(check => {
+    const step = book.steps.find(step => step.task_id === next.id && step.step_id === check.step_id), receipt = book.receipts.get(step?.receipt_id);
+    const proof = book.attestations.get(keyOf(next.id, check.step_id));
+    return { step_id: check.step_id, status: book.checkValid(next, check, step) ? 'returned' : step?.preflight_failure ? 'not_dispatched' : proof?.attempt_id === step?.attempt_id && proof?.passed === false ? 'assertion_failed' : step?.status || 'missing', retryable_read: readOnlyWorkCheck(check.operation, check.arguments), ref: step?.receipt_ref ?? step?.recovery_ref, ...(step?.preflight_failure ? { target_dispatched: false, failure_stage: 'artifact_preflight' } : {}), ...(proof?.passed === false ? { error: proof.error } : receipt?.status === 'failed' && receipt.error ? { error: receipt.error.slice(0,700) } : {}) };
+  }) || [];
+  const recoverRead = checks.some(check => ['failed', 'assertion_failed'].includes(check.status) && check.retryable_read);
+  const currentDraft = book.drafts.findLast(draft => draft.task_id === next?.id && (next.phase!=='verification' || (next.artifacts || []).includes(draft.file_path)));
+  const refreshable = id => { const task = book.tasks.find(task => task.id === id); return task?.declared_status === 'done' && task.checks.length && task.checks.every(check => readOnlyWorkCheck(check.operation,check.arguments)) && task.depends_on.every(parent => book.tasks.find(task => task.id === parent)?.status === 'done' || refreshable(parent)); };
+  const staleDependencies = next?.declared_status === 'in_progress' && next.status === 'blocked' && next.held_by.length && next.held_by.every(refreshable);
+  const finishCall = (next?.status === 'in_progress' || staleDependencies) && checks.length && checks.every(check => check.retryable_read) ? { name: 'WorkTaskUpdate', input: { task_id: next.id, plan_version: book.plan.version, status: 'done', verify: true } } : null;
+  const preflightFailures = book.steps.filter(step => step.preflight_failure).map(step => {
+    const task = book.tasks.find(task => task.id === step.task_id);
+    return { task_id: step.task_id, step_id: step.step_id, status: 'not_dispatched', ...step.preflight_failure,
+      retry_call: step.preflight_failure.retry_call || { name: 'WorkStepRun', input: { task_id: step.task_id, plan_version: book.plan.version, step_id: step.step_id } },
+      ...(task?.declared_status === 'blocked' && !task.held_by.length ? { resume_call: { name: 'WorkTaskUpdate', input: { task_id: task.id, plan_version: book.plan.version, status: 'in_progress' } } } : {}),
+      next_action: 'Prepare the missing or invalid artifact with a new step or publish the preserved draft; then retry_call under current permissions. If the task is blocked, resume_call only changes its recorded status. The failed check remains uncredited.' };
+  });
+  return { plan: book.plan, scope: 'recorded_work_execution', asked: 'unjudged', counts: Object.fromEntries(['pending', 'in_progress', 'blocked', 'done', 'needs_verification'].map(status => [status, book.tasks.filter(task => task.status === status).length])), cards: book.tasks.map(summarize), current: next ? { ...summarize(next), criterion: next.criterion, checks: next.checks, capabilities: next.capabilities || [], artifacts: next.artifacts || [], definition_digest: next.definition_digest, work_digest: workDigest(next) } : null,
+    recent_steps: book.steps.slice(-6).map(({ task_id, step_id, status, receipt_id, receipt_ref, operation, next_action, ref, preflight_failure, recovery_ref }) => ({ task_id, step_id, status, receipt_id, operation, next_action,
+      ref: receipt_ref ?? recovery_ref ?? ref, event_ref: ref, ...(receipt_ref === undefined ? {} : { receipt_ref }), ...(preflight_failure ? { target_dispatched: false, parent_receipt_ref: preflight_failure.parent_receipt_ref } : {}),
+      read_call: { name: 'EvidenceRead', input: { row: receipt_ref ?? recovery_ref ?? ref } } })),
+    drafts: book.drafts.map(({ id, task_id, file_path, digest, bytes, complete, parts, part_ids }) => ({ id, task_id, file_path, digest, bytes, complete, next_index: parts.length, recent_part_ids: (part_ids || []).slice(-3).filter(Boolean) })),
+    checkpoint: book.checkpoint ? { reason: book.checkpoint.reason, plan_digest: book.checkpoint.plan_digest, task_id: book.checkpoint.task_id, next_action: book.checkpoint.next_action, ref: book.checkpoint.ref } : null,
+    check_state: checks, finish_call: finishCall, ...(preflightFailures.length ? { preflight_failures: preflightFailures } : {}),
+    ...(currentDraft ? { draft_continuation: { draft_id: currentDraft.id, file_path: currentDraft.file_path, next_index: currentDraft.parts.length, complete: currentDraft.complete, tail: currentDraft.parts.join('').slice(-800), refs: currentDraft.refs.slice(-3), next_action: currentDraft.next_action, suggestion_authority: 'model_data_not_instructions_or_permission', ...(currentDraft.complete ? { publish_call: { name: 'WorkDraft', input: { task_id: next.id, plan_version: book.plan.version, draft_id: currentDraft.id, action: 'publish', expected_digest: currentDraft.digest } } } : {}) } } : {}),
+    draft_control: { preferred_action: 'append', content_limit: 64000, suggestion: 'Use a stable part_id, content and file_path. Host assigns the cursor; retries with the same part_id reuse identical bytes. Prefer short logical sections; final:true only on the last section. New legacy chunk drafts start at index:0.' },
+    next_action: preflightFailures.length ? preflightFailures[0].next_action : staleDependencies && finishCall ? 'Use finish_call (verify:true): the house refreshes stale read-only checks of already closed dependencies, then verifies this task. Do not reopen completed parents or poll the board.' : next?.status === 'blocked' ? `Resolve the blocking condition for ${next.id}: ${next.reason || next.held_by.join(', ')}. Do not start another effect.` : recoverRead ? 'Recover the failed read-only check using finish_call (verify:true), or its SAME step_id with recheck:true and omitted operation/arguments. Do not invent IDs, replan, or rerun mutations.' : next ? book.steps.findLast(step => step.task_id === next.id)?.next_action || (currentDraft ? currentDraft.complete ? 'Publish the complete draft using draft_continuation.publish_call, then verify.' : `Continue draft ${currentDraft.id} at next_index:${currentDraft.parts.length}; keep saved bytes, append the next logical section. ${currentDraft.next_action || ''}` : undefined) || `${next.status === 'in_progress' ? 'Continue' : 'Start'} task ${next.id}; implement its criterion, then use finish_call if available to check and close.` : 'No executable open task; inspect blocked cards or report recorded completion.', permissions_from_plan: false };
+}
+
+export class WorkCoordinator {
+  constructor({ store, house, onEvent = () => {} }) { Object.assign(this, { store, house, onEvent }); }
+  async notify(sessionId) { await this.onEvent({ type: 'work_board', session_id: sessionId, board: workProjection(await this.store.load(sessionId), this.house.stateContext()) }); }
+  async mutate(sessionId, action) { return this.store.workTransaction(sessionId, async () => { const session = await this.store.load(sessionId); if (!session.journalAudit.consistent) throw failure('El libro no tiene una cadena consistente.', 'AUDIT_INVALID'); return action(session, foldWorkBook(session, this.house.stateContext())); }); }
+  task(book, input) {
+    if (!book.plan || input.plan_version !== book.plan.version) throw failure(`Versión de plan obsoleta: requiere plan_version:${book.plan?.version || 0}. Continúa el borrador/tarea con esa precondición; la versión vigente está en este resultado, no necesitas WorkBoard.`);
+    const task = book.tasks.find(task => task.id === input.task_id); if (!task) throw failure('Tarea inexistente.'); return task;
+  }
+  async fact(options, row) { await options.recordWork({ ...row, source: 'work_host' }); }
+  async setPlan(input, options) {
+    const result = await this.mutate(options.sessionId, async (session, book) => {
+      const expected = book.plan?.version || 0;
+      if (expected !== input.expected_version) throw failure(book.plan
+        ? `Plan cambiado: versión vigente ${expected}; WorkPlanSet requiere expected_version:${expected}. Conserva las tareas abiertas o declara retiros explícitos. El estado ya está en la proyección.`
+        : 'No existe plan aceptado. Para crear el primer plan usa WorkPlanSet con expected_version:0 y una tarea pequeña. La versión 1 será el resultado, no la precondición. No necesitas consultar WorkBoard.');
+      if (Buffer.byteLength(JSON.stringify(input)) > 64000) throw failure('Plan demasiado grande: usa tareas más pequeñas.');
+      const proposed = input.append ? [...book.tasks.map(definitionOf), ...input.tasks] : input.tasks;
+      if (proposed.length > 24) throw failure('Máximo 24 tareas por plan, incluidas las conservadas.', 'WORK_PLAN_INPUT');
+      const ids = new Set(proposed.map(task => task.id)); if (ids.size !== proposed.length) throw failure('IDs de tareas duplicados; append sólo admite IDs nuevos y conserva las tareas anteriores.', 'WORK_PLAN_INPUT');
+      const definitions = proposed.map(task => ({ ...task, depends_on: task.depends_on || [], checks: task.checks || [] }));
+      const contractIssues = checkContractIssues(definitions, name => this.house.registry.get(name), { rejectMissing: true });
+      if (contractIssues.length) throw failure('Checks inválidos; el plan no se guardó. ' + (book.plan ? 'Para observaciones adicionales de DOM/consola/red NO hace falta reemplazar el plan: usa WorkStepRun con task_id vigente, plan_version:'+book.plan.version+', step_id NUEVO, operation y arguments. ' : '') + JSON.stringify({issues:contractIssues,available_operation_names:(options.catalogue || []).map(item=>item.name).filter(name=>!WORK_NAMES.includes(name)).slice(0,60),next_action:'Use an exact offered operation and its arguments; Read uses file_path. Preserve the requested artifacts and task criterion. No checks executed and no plan saved.'}), 'WORK_CHECK_CONTRACT');
+      for (const task of definitions) {
+        for (const check of task.checks) validateAssertions(check.assertions);
+        if (task.phase === 'verification' && (!task.checks.length || task.checks.some(check => !check.assertions?.length))) throw failure('Una tarea verification requiere aserciones explícitas en cada check.', 'WORK_ASSERTION');
+      }
+      for (const task of definitions) { if (new Set(task.checks.map(check => check.step_id)).size !== task.checks.length) throw failure('IDs de comprobación duplicados.', 'WORK_PLAN_INPUT'); if (task.checks.some(check => Buffer.byteLength(JSON.stringify(check.arguments)) > 4000)) throw failure('Comprobación demasiado grande; declara una llamada pequeña.', 'WORK_PLAN_INPUT'); if (task.depends_on.some(parent => !ids.has(parent) || parent === task.id)) throw failure(`Dependencia inexistente o circular en ${task.id}: ${JSON.stringify(task.depends_on)}. Una tarea no depende de sí misma; IDs disponibles: ${[...ids].join(', ')}.`, 'WORK_PLAN_INPUT'); }
+      const visiting = new Set(), visited = new Set();
+      const visit = id => { if (visiting.has(id)) throw failure('Dependencias circulares.', 'WORK_PLAN_INPUT'); if (visited.has(id)) return; visiting.add(id); definitions.find(task => task.id === id).depends_on.forEach(visit); visiting.delete(id); visited.add(id); }; ids.forEach(visit);
+      definitions.forEach(task => { task.definition_digest = digest(task); const old = book.tasks.find(old => old.id === task.id); if (old?.definition_digest === task.definition_digest && old.work_digest) task.work_digest = old.work_digest; });
+      for (const old of book.tasks.filter(task => task.status !== 'done' && task.phase === 'verification' && task.checks.some(isMcpCheck))) if (!definitions.some(task => task.phase === 'verification' && task.checks.some(check => isMcpCheck(check) && old.checks.some(before => mcpServer(before) === mcpServer(check))))) throw failure('La verificación MCP declarada debe conservar checks MCP; Read/wc no sustituyen la etapa de navegador.', 'WORK_VERIFICATION_REQUIRED');
+      for (const old of book.tasks.filter(task => task.status !== 'done')) if (!definitions.some(task => task.id === old.id && task.definition_digest === old.definition_digest) && !(input.retire_ids || []).includes(old.id)) throw failure(`La tarea abierta ${old.id} no puede desaparecer: para corregir sólo checks usa WorkCheckRepair y conserva el borrador; para cambiar el encargo preserva su definición o declara retire_ids y reason.`);
+      if (input.retire_ids?.length && !input.reason?.trim()) throw failure('Retirar tareas requiere reason.');
+      const planDigest = digest({ objective: input.objective, tasks: definitions });
+      if (book.plan?.digest === planDigest) return { version: book.plan.version, plan_digest: planDigest, unchanged: true };
+      const next = (book.plan?.version || 0) + 1;
+      await this.fact(options, { type: 'work_plan_set', version: next, supersedes: book.plan?.version || null, objective: input.objective, tasks: definitions, plan_digest: planDigest, retired: input.retire_ids || [], reason: input.reason });
+      return { version: next, plan_digest: planDigest };
+    }); await this.notify(options.sessionId); return JSON.stringify(result);
+  }
+  async repairChecks(input, options) {
+    const result = await this.mutate(options.sessionId, async (_, book) => {
+      if (!book.plan || book.plan.version !== input.plan_version) throw failure(`WorkCheckRepair requiere plan_version:${book.plan?.version || 0}; no se cambió nada.`);
+      const lookup = name => this.house.registry.get(name), catalogue = [...this.house.registry.snapshot({ surface: 'agent', actor: options.actor })].map(([,op]) => op);
+      if (input.literal_types_only && input.repairs) throw failure('literal_types_only no admite reparaciones manuales.');
+      const proposed = proposeCheckRepairs(book.tasks, lookup, catalogue).filter(patch => {
+        if (!input.literal_types_only) return true;
+        const before = book.tasks.find(task => task.id === patch.task_id)?.checks.find(check => check.step_id === patch.step_id);
+        return patch.assertions && patch.operation === before?.operation && digest(patch.arguments) === digest(before.arguments);
+      });
+      const requested = input.repairs || proposed;
+      const failedRead = (task, check) => {
+        const step = book.steps.find(step => step.task_id === task.id && step.step_id === check.step_id);
+        return readOnlyWorkCheck(check.operation, check.arguments) && (step?.status === 'failed' || book.attestations.get(keyOf(task.id, check.step_id))?.passed === false);
+      };
+      if (!requested.length) {
+        const failedReads = book.tasks.filter(task => task.checks.some(check => failedRead(task,check)) || task.declared_status === 'in_progress' && task.checks.some(check => runtimeBoundReadCheck(check.operation,check.arguments))).flatMap(task => task.checks.filter(check => readOnlyWorkCheck(check.operation,check.arguments)).map(check => ({ task_id: task.id, step_id: check.step_id, expected_digest: digest(check), operation: check.operation, arguments: check.arguments, failed: failedRead(task,check) })));
+        return { version: book.plan.version, unchanged: true, remaining_issues: checkContractIssues(book.tasks,lookup,{rejectMissing:true}), ...(failedReads.length ? { runtime_checks: failedReads, next_action: 'Read-only runtime failure: retry the SAME check with recheck:true. If the target changed, observe its new ID first, then repair only runtime IDs using expected_digest. Preserve selectors, comparisons and other arguments. All read checks in the affected task are listed so shared target bindings can be repaired together. Assertions, artifacts and task identity remain unchanged; no effects executed.' } : { next_action: 'If an MCP check is unavailable, acquire browser.verify; then retry WorkCheckRepair. Do not rebuild the plan.' }) };
+      }
+      const tasks = book.tasks.map(task => structuredClone(definitionOf(task))), repairs = [];
+      for (const patch of requested) {
+        const old = book.tasks.find(task => task.id === patch.task_id), task = tasks.find(task => task.id === patch.task_id), index = task?.checks.findIndex(check => check.step_id === patch.step_id);
+        if (!old || index === undefined || index < 0) throw failure('La reparación debe nombrar un check existente.');
+        const before = task.checks[index];
+        if (digest(before) !== patch.expected_digest) throw failure(`Check cambiado: ${patch.task_id}/${patch.step_id}; expected_digest:${digest(before)}. No se cambió nada.`);
+        // Only host-generated proposals can include an assertion type repair;
+        // the public manual-repair schema rejects an assertions field.
+        const after = { ...before, ...(patch.operation !== undefined ? {operation:patch.operation} : {}), ...(patch.arguments !== undefined ? {arguments:patch.arguments} : {}), ...(patch.assertions !== undefined ? {assertions:patch.assertions} : {}) };
+        if (isMcpCheck(before) && (!isMcpCheck(after) || mcpServer(before) !== mcpServer(after)) || !isMcpCheck(before) && lookup(before.operation) && before.operation !== after.operation) throw failure('Reparar un contrato conserva la modalidad de su check; no sustituye MCP por archivos ni cambia una operación válida por otra.', 'WORK_VERIFICATION_REQUIRED');
+        const issues = checkContractIssues([{...task,checks:[after]}],lookup,{rejectMissing:true});
+        if (issues.length) throw failure('Reparación inválida; no se cambió nada. expected_digest sigue identificando el check vigente; proposed_digest sólo identifica la propuesta rechazada: '+JSON.stringify(issues.map(issue=>({...issue,proposed_digest:issue.expected_digest,expected_digest:digest(before)}))),'WORK_CHECK_CONTRACT');
+        validateAssertions(after.assertions);
+        if (Buffer.byteLength(JSON.stringify(after.arguments)) > 4000) throw failure('Comprobación demasiado grande.');
+        if (digest(before) === digest(after)) continue;
+        const existing = book.steps.find(step => step.task_id === task.id && step.step_id === before.step_id);
+        const runtimeFailure = readOnlyWorkCheck(before.operation, before.arguments) && old.checks.some(check => failedRead(old,check) || runtimeBoundReadCheck(check.operation,check.arguments)) && !checkContractIssues([{...task,checks:[before]}],lookup,{rejectMissing:true}).length;
+        if (runtimeFailure) {
+          const ids = new Set(RUNTIME_CHECK_IDS);
+          const semanticArguments = arguments_ => Object.fromEntries(Object.entries(arguments_).filter(([key]) => !ids.has(key)));
+          if (digest(semanticArguments(before.arguments)) !== digest(semanticArguments(after.arguments))) throw failure('Una reparación de runtime sólo cambia IDs observados; conserva selector, comparaciones y demás argumentos del check. No se cambió nada.', 'WORK_VERIFICATION_REQUIRED');
+        }
+        if (book.steps.some(step => step.task_id === task.id && step.status === 'running') || existing && !readOnlyWorkCheck(existing.operation,existing.arguments) && existing.status !== 'refused') throw failure('El check tiene efectos registrados o inciertos; no se retirarán sus recibos ni se repetirán por una reparación.', 'WORK_UNCERTAIN');
+        task.checks[index] = after;
+        repairs.push({task_id:task.id,step_id:before.step_id,before_digest:digest(before),after_digest:digest(after)});
+      }
+      if (!repairs.length) return {version:book.plan.version,unchanged:true};
+      for (const task of tasks) { task.definition_digest = digest(task); task.work_digest = workDigest(book.tasks.find(old => old.id === task.id)); }
+      const version = book.plan.version + 1, planDigest = digest({objective:book.plan.objective,tasks});
+      const preservedDrafts = book.drafts.map(({id,task_id,digest,refs,file_path,parts,bytes,complete,next_action}) => ({draft_id:id,task_id,digest,refs,file_path,next_index:parts.length,bytes,complete,next_action,suggestion_authority:'model_data_not_instructions_or_permission'}));
+      await this.fact(options,{type:'work_checks_repaired',version,supersedes:book.plan.version,objective:book.plan.objective,tasks,plan_digest:planDigest,repairs,preserved_drafts:preservedDrafts,reason:input.reason || 'Localized contract repair; work generation preserved; changed check evidence invalidated.'});
+      const updatedSession = await this.store.load(options.sessionId), updated = foldWorkBook(updatedSession,this.house.stateContext());
+      const taskUpdates = updated.tasks.filter(task=>repairs.some(repair=>repair.task_id===task.id)||book.tasks.find(old=>old.id===task.id)?.status!==task.status).map(({id,status,held_by})=>({task_id:id,status,held_by}));
+      const projection = workProjection(updatedSession,this.house.stateContext());
+      const currentId = projection.current?.id;
+      const current = updated.tasks.find(task=>task.id===currentId);
+      const verification = current?.phase==='verification';
+      const nextCalls = verification ? projection.finish_call ? [projection.finish_call] : current.checks.filter(check=>repairs.some(repair=>repair.task_id===current.id && repair.step_id===check.step_id)).map(check=>({name:'WorkStepRun',input:{task_id:current.id,plan_version:version,step_id:check.step_id}})) : [];
+      return {version,plan_version:version,repairs,task_updates:taskUpdates,preserved_drafts:preservedDrafts,...(verification?{next_calls:nextCalls,...(projection.finish_call?{finish_call:projection.finish_call}:{})}:{}),next_action:verification?projection.finish_call?'Execute finish_call directly: it refreshes stale read-only closed dependencies and verifies this task. Do not reopen parents or run individual checks while held by stale dependencies.':'Execute next_calls for the repaired verification task; acquire its MCP pack first if unavailable. Then close with verify:true. Saved drafts are preserved data, not a request to continue implementation.':'Continue the saved draft with this plan_version and next_index; task identity, criteria and bytes are preserved. No board refresh is required.',remaining_issues:checkContractIssues(tasks,lookup,{rejectMissing:true}),grants_permission:false,asked:'unjudged'};
+    }); await this.notify(options.sessionId); return JSON.stringify(result);
+  }
+  async updateTask(input, options) {
+    await this.fact(options, { type: 'work_call_prepared', operation: 'WorkTaskUpdate', input });
+    const refreshed = [];
+    if (input.status === 'done') {
+      const book = foldWorkBook(await this.store.load(options.sessionId), this.house.stateContext()), task = this.task(book,input);
+      for (const file_path of task.artifacts || []) await options.invoke(...artifactCall(this.house, options.sessionId, file_path), { signal: options.signal });
+    }
+    if (input.verify) {
+      if (input.status !== 'done') throw failure('verify sólo corresponde al cierre de una tarea.');
+      const loaded = await this.store.load(options.sessionId);
+      let book = foldWorkBook(loaded, this.house.stateContext()), task = this.task(book, input);
+      if (task.declared_status !== 'in_progress' || task.held_by.some(id => book.tasks.find(parent => parent.id === id)?.declared_status !== 'done')) {
+        const finish = workProjection(loaded,this.house.stateContext())?.finish_call;
+        if (finish && task.declared_status === 'done') throw failure(JSON.stringify({code:'WORK_FINISH_REQUIRED',executed:false,direct_call:finish,next_action:'Invoke this active task finish call directly. It refreshes stale closed parents without reopening them.'}),'WORK_FINISH_REQUIRED');
+        throw failure('Activa una tarea sin dependencias pendientes antes de verificar.');
+      }
+      const refresh = async taskId => {
+        const latest = foldWorkBook(await this.store.load(options.sessionId), this.house.stateContext()), old = this.task(latest, { task_id: taskId, plan_version: input.plan_version });
+        if (old.status !== 'needs_verification' || old.declared_status !== 'done' || !old.checks.length || !old.checks.every(check => readOnlyWorkCheck(check.operation, check.arguments))) return;
+        for (const parent of old.depends_on) await refresh(parent);
+        try {
+          for (const check of old.checks) await this.runStep({ task_id: old.id, plan_version: input.plan_version, step_id: check.step_id, recheck: true }, { ...options, refreshCompleted: true });
+          await this.updateTask({ task_id: old.id, plan_version: input.plan_version, status: 'done', reason: 'Checks de lectura renovados por la casa tras cambiar la superficie; sin reabrir trabajo.' }, options);
+          refreshed.push(old.id);
+        } catch (error) { throw failure(`El check de la tarea cerrada ${old.id} perdió vigencia: ${error.message}. Repara la superficie antes de cerrar ${input.task_id}.`, error.code || 'WORK_UNVERIFIED'); }
+      };
+      for (const old of book.tasks.filter(old => old.id !== task.id && old.declared_status === 'done')) await refresh(old.id);
+      book = foldWorkBook(await this.store.load(options.sessionId), this.house.stateContext()); task = this.task(book, input);
+      if (task.status !== 'in_progress' || task.held_by.length) throw failure('Activa una tarea sin dependencias pendientes antes de verificar.');
+      for (const check of task.checks) {
+        const step = book.steps.find(step => step.task_id === task.id && step.step_id === check.step_id);
+        const receipt = book.receipts.get(step?.receipt_id);
+        const staleDependency = receipt && task.depends_on.some(parent => receipt.evidence_row <= book.tasks.find(row => row.id === parent).ref);
+        if (book.checkValid(task, check, step) && !staleDependency) continue;
+        if (!readOnlyWorkCheck(check.operation, check.arguments)) throw failure(`Check ${check.step_id} requiere WorkStepRun explícito; verify no repite efectos opacos.`, 'WORK_UNCERTAIN');
+        await this.runStep({ task_id: task.id, plan_version: input.plan_version, step_id: check.step_id, recheck: true }, options);
+      }
+    }
+    const result = await this.mutate(options.sessionId, async (_, book) => {
+      const task = this.task(book, input); let receiptIds = []; const dependencyProofs = {};
+      if (input.status === 'in_progress') {
+        if (task.status === 'done') throw failure('Una tarea cerrada no se reabre por accidente; declara un nuevo plan para trabajo nuevo.');
+        if (task.held_by.length) throw failure('Dependencias sin cerrar.');
+        if (book.tasks.some(other => other.id !== task.id && other.declared_status === 'in_progress')) throw failure('Ya hay una tarea activa; termínala o bloquéala antes.');
+      }
+      if (input.status === 'blocked' && !input.reason?.trim()) throw failure('Un bloqueo requiere reason.');
+      if (input.status === 'done') {
+        if (task.held_by.length || !task.checks.length) throw failure('Cierre requiere dependencias cerradas y comprobaciones declaradas.', 'WORK_UNVERIFIED');
+        for (const check of task.checks) {
+          const step = book.steps.find(step => step.task_id === task.id && step.task_digest === workDigest(task) && step.step_id === check.step_id && step.operation === check.operation && step.arguments_digest === digest(check.arguments));
+          const receipt = book.receipts.get(step?.receipt_id);
+          if (receipt && task.depends_on.some(parent => receipt.evidence_row <= book.tasks.find(row => row.id === parent).ref)) throw failure('La comprobación precede al cierre de una dependencia; usa recheck:true.', 'WORK_UNVERIFIED');
+          if (!book.checkValid(task, check, step)) throw failure(`Comprobación ${check.step_id} sin recibo vigente o aserción satisfecha de la casa.`, 'WORK_UNVERIFIED');
+          receiptIds.push(receipt.invocation_id);
+        }
+        const artifacts = new Map();
+        const candidates = book.steps.filter(step => step.task_id === task.id && step.status === 'returned').map(step => book.receipts.get(step.receipt_id));
+        // A declared check rereads its artifacts before/after execution. Those
+        // host-bound current observations supersede older writes/draft publishes;
+        // requiring the historical bytes again would reject legitimate corrections.
+        for (const check of task.checks) {
+          const proof = book.attestations.get(keyOf(task.id, check.step_id));
+          for (const receiptId of proof?.artifact_receipts || []) candidates.push(book.receipts.get(receiptId));
+        }
+        for (const receipt of candidates.filter(Boolean).sort((a, b) => a.evidence_row - b.evidence_row)) for (const observation of receipt.observations || []) if (['file_write', 'file_read'].includes(observation.kind)) artifacts.set(observation.file_path, receipt);
+        for (const [file, receipt] of artifacts) { if (!book.receiptValid(receipt)) throw failure(`Un artefacto de la tarea cambió después de su observación: ${file}. Verifica los bytes actuales mediante un check declarado con artifacts o WorkStepRun Read nuevo; no restaures versiones antiguas.`, 'WORK_UNVERIFIED'); receiptIds.push(receipt.invocation_id); }
+        receiptIds = [...new Set(receiptIds)];
+        for (const parent of task.depends_on) dependencyProofs[parent] = digest(book.tasks.find(row => row.id === parent).receipt_ids);
+        if (book.steps.some(step => step.task_id === task.id && ['running', 'interrupted', 'failed'].includes(step.status))) throw failure('Hay un paso con efectos inciertos: inspecciona antes de cerrar.', 'WORK_UNVERIFIED');
+      }
+      await this.fact(options, { type: 'work_task_changed', task_id: task.id, task_digest: workDigest(task), plan_version: book.plan.version, status: input.status, reason: input.reason, receipt_ids: receiptIds, dependency_proofs: dependencyProofs });
+      return { task_id: task.id, status: input.status, receipt_ids: receiptIds, scope: input.status === 'done' && task.checks.every(check=>check.assertions?.length) ? 'declared_assertions_verified' : 'declared_checks_returned', asked: 'unjudged' };
+    }); await this.notify(options.sessionId); return JSON.stringify({ ...result, ...(refreshed.length ? { refreshed_tasks: refreshed } : {}) });
+  }
+  async runStep(input, options) {
+    if(!options.draftPublication)await this.fact(options,{type:'work_call_prepared',operation:'WorkStepRun',input});
+    if (input.operation === undefined || input.arguments === undefined) {
+      const book = foldWorkBook(await this.store.load(options.sessionId), this.house.stateContext()), task = this.task(book, input), check = task.checks.find(check => check.step_id === input.step_id);
+      if (!check) throw failure('Un paso nuevo requiere operation y arguments; para checks basta su step_id.');
+      input = { ...input, operation: input.operation ?? check.operation, arguments: input.arguments ?? check.arguments };
+    }
+    if (!options.draftPublication && Buffer.byteLength(JSON.stringify(input.arguments)) > 16000) throw failure('Paso demasiado grande: guarda el script con WorkDraft y ejecuta un paso pequeño.');
+    if (WORK_NAMES.includes(input.operation) || ['WorkSnapshot', 'AuditStatus', 'EvidenceRead', 'ToolPack', 'HouseSnapshot', 'OperationCatalog'].includes(input.operation)) {
+      const version = foldWorkBook(await this.store.load(options.sessionId)).plan?.version || 0;
+      throw failure(JSON.stringify({code:'WORK_CONTROL_DIRECT',executed:false,direct_call:{name:input.operation,input:input.operation==='WorkCheckRepair'?{plan_version:version}:input.arguments},next_action:'Invoke direct_call as a TOP-LEVEL tool call, never inside WorkStepRun. No step was reserved and no effect executed.'}), 'WORK_CONTROL_DIRECT');
+    }
+    const staged = await this.mutate(options.sessionId, async (session, book) => {
+      const task = this.task(book, input);
+      const check = task.checks.find(check => check.step_id === input.step_id);
+      const refresh = options.refreshCompleted && task.declared_status === 'done' && check && readOnlyWorkCheck(check.operation, check.arguments);
+      if ((!refresh && task.status !== 'in_progress') || task.held_by.length) {
+        const finish = workProjection(session,this.house.stateContext())?.finish_call;
+        if (finish?.input.task_id === task.id) throw failure(JSON.stringify({code:'WORK_FINISH_REQUIRED',executed:false,direct_call:finish,next_action:'Use this TOP-LEVEL finish call; the house refreshes already closed read dependencies before checking this task. No step was reserved.'}),'WORK_FINISH_REQUIRED');
+        throw failure('Activa una tarea sin dependencias pendientes antes de ejecutar.');
+      }
+      if (input.recheck && !check) throw failure('recheck sólo corresponde a una comprobación declarada.');
+      if (check && (check.operation !== input.operation || digest(check.arguments) !== digest(input.arguments))) throw failure('La comprobación propuesta no coincide con el plan. No se cambió nada. '+JSON.stringify({expected_check:check,check_call:{name:'WorkStepRun',input:{task_id:task.id,plan_version:book.plan.version,step_id:check.step_id}},observation_hint:'Para una observación distinta usa otro step_id NUEVO con operation y arguments explícitos; adquiere su pack antes. No reemplaces el plan ni reutilices el ID de este check.'}),'WORK_CHECK_MISMATCH');
+      const existing = book.steps.find(step => step.task_id === task.id && step.step_id === input.step_id);
+      if (existing) {
+        if (existing.operation !== input.operation || existing.arguments_digest !== digest(input.arguments)) throw failure('El ID del paso ya nombra otros argumentos. '+JSON.stringify({code:'WORK_STEP_ID_CONFLICT',executed:false,step_id:existing.step_id,operation:existing.operation,arguments_digest:existing.arguments_digest,status:existing.status,receipt_id:existing.receipt_id,read_call:{name:'EvidenceRead',input:{row:existing.receipt_ref ?? existing.ref}},next_action:'Read the original record with read_call; do not repeat a completed effect. Only genuinely new work uses a new step_id.'}), 'WORK_STEP_ID_CONFLICT');
+        if (existing.status === 'returned' && !input.recheck) { const receipt = book.receipts.get(existing.receipt_id); if (check ? !book.checkValid(task, check, existing) : !book.receiptValid(receipt)) throw failure('El efecto registrado perdió vigencia o su aserción falló; usa recheck para un check, sin repetir mutaciones.', 'WORK_UNVERIFIED'); return { reuse: receipt }; }
+        const retryFailedRead = input.recheck && check && existing.status === 'failed' && book.receipts.has(existing.receipt_id) && readOnlyWorkCheck(check.operation, check.arguments);
+        if (existing.status !== 'refused' && !(input.recheck && check && existing.status === 'returned') && !retryFailedRead) throw failure('El paso quedó interrumpido o falló con posibles efectos; inspecciona y registra otro paso antes de repetir. Un check de lectura con recibo failed se recupera con el mismo step_id y recheck:true.', 'WORK_UNCERTAIN');
+      }
+      if (book.steps.some(step => step.task_id === task.id && (['running', 'interrupted'].includes(step.status) || step.status === 'failed' && !readOnlyWorkCheck(step.operation, step.arguments)))) throw failure('La tarea tiene un paso sin cierre o con efectos inciertos; no se iniciará otro efecto.', 'WORK_UNCERTAIN');
+      const offered=options.catalogue?.find(op=>op.name===input.operation), operation=this.house.registry.get(input.operation);
+      if(offered && operation?.digest===offered.contract_digest) {
+        try{operation.validate(input.arguments);}catch(cause){throw failure(cause.message+' Entrada rechazada ANTES de reservar un nuevo intento o iniciar efectos. Corrige los tipos/argumentos y reintenta el MISMO step_id; no hace falta otro plan.','WORK_STEP_INPUT_SCHEMA');}
+      }
+      const attemptId = randomUUID(), stamp = { task_id: task.id, task_digest: workDigest(task), plan_version: book.plan.version, step_id: input.step_id, attempt_id: attemptId };
+      await this.fact(options, { type: 'work_step_started', ...stamp, operation: input.operation, arguments: input.arguments, arguments_digest: digest(input.arguments), next_action: input.next_action || `Check task ${task.id} and continue its remaining checks.` });
+      return { stamp, check, artifacts: task.artifacts || [] };
+    });
+    if (staged.reuse) return JSON.stringify({ reused: true, receipt_id: staged.reuse.invocation_id, output: staged.reuse.output, no_reexecution: true });
+    const artifactReceipts = [], initialHashes = new Map();
+    const inspectArtifacts = async (after = false) => {
+      for (const file of staged.artifacts) {
+        const callId = randomUUID();
+        await options.invoke(...artifactCall(this.house, options.sessionId, file), { signal: options.signal, callId });
+        const loaded = await this.store.load(options.sessionId), receipt = loaded.rows.findLast(row => row.type === 'house_receipt' && row.call_id === callId && row.status === 'returned');
+        const fact = receipt?.observations.find(fact => fact.kind === 'file_read');
+        if (!fact) throw failure('El artefacto no tiene observación nativa de lectura.', 'WORK_UNVERIFIED');
+        artifactReceipts.push(receipt.invocation_id);
+        if (!after) initialHashes.set(file, fact.sha256);
+        else if (initialHashes.get(file) !== fact.sha256) throw failure('El artefacto cambió durante la verificación.', 'WORK_STALE');
+      }
+    };
+    let receiptId, dispatching = false;
+    try {
+      if (staged.check) {
+        await this.fact(options, { type: 'work_step_preflight', ...staged.stamp });
+        await inspectArtifacts();
+      }
+      const beforeEffect = () => this.mutate(options.sessionId, async (_, book) => {
+        const task = book.tasks.find(task => task.id === input.task_id);
+        const ready = options.refreshCompleted ? task?.declared_status === 'done' : task?.status === 'in_progress';
+        if (book.plan?.version !== staged.stamp.plan_version || workDigest(task) !== staged.stamp.task_digest || !ready || task.held_by.length) throw failure('El plan o la tarea cambió durante el juicio; no se ejecutará el paso.', 'WORK_STALE');
+      });
+      await this.fact(options, { type: 'work_step_dispatching', ...staged.stamp, operation: input.operation, arguments_digest: digest(input.arguments) });
+      dispatching = true;
+      const output = await options.invoke(input.operation, input.arguments, { signal: options.signal, work: staged.stamp, beforeEffect });
+      const book = foldWorkBook(await this.store.load(options.sessionId)), step = book.steps.find(step => step.attempt_id === staged.stamp.attempt_id);
+      receiptId = step?.receipt_id;
+      if (staged.check && (staged.check.assertions?.length || staged.artifacts.length)) {
+        await inspectArtifacts(true); assertOutput(output, staged.check.assertions);
+        await this.fact(options, { type: 'work_check_verified', ...staged.stamp, receipt_id: receiptId, assertions_digest: digest(staged.check.assertions || []), passed: true, artifact_receipts: artifactReceipts, artifact_count: staged.artifacts.length });
+      }
+      return JSON.stringify({ output, receipt_id: step?.receipt_id, task_id: input.task_id, step_id: input.step_id, next_action: input.next_action });
+    } catch (error) {
+      if (!dispatching && staged.check) await this.fact(options, { type: 'work_step_not_dispatched', ...staged.stamp, code: error.code || 'WORK_PREFLIGHT_FAILED', error: error.message });
+      if (staged.check && (staged.check.assertions?.length || staged.artifacts.length)) await this.fact(options, { type: 'work_check_verified', ...staged.stamp, receipt_id: receiptId, assertions_digest: digest(staged.check.assertions || []), passed: false, error: error.message.slice(0,700), artifact_receipts: artifactReceipts, artifact_count: staged.artifacts.length });
+      throw error;
+    } finally { await this.notify(options.sessionId); }
+  }
+  async draft(input, options) {
+    await this.fact(options,{type:'work_call_prepared',operation:'WorkDraft',input});
+    if (input.action === 'read' || input.action === 'publish') {
+      const book = foldWorkBook(await this.store.load(options.sessionId)), task = this.task(book, input), draft = book.drafts.find(draft => draft.task_id === task.id && draft.id === input.draft_id);
+      if (!draft) throw failure('Borrador inexistente.');
+      if (input.action === 'read') { const content = draft.parts.join(''), offset = input.offset || 0, limit = input.limit || 4000; return JSON.stringify({ draft_id: draft.id, digest: draft.digest, complete: draft.complete, content: content.slice(offset, offset + limit), ...(offset + limit < content.length ? { next_offset: offset + limit } : {}), bytes: draft.bytes }); }
+      if (!draft.complete || input.expected_digest !== undefined && input.expected_digest !== draft.digest) throw failure('No se publica un borrador incompleto o con digest obsoleto.');
+      return this.runStep({ ...input, step_id: `publish:${draft.id}:${draft.digest.slice(0, 12)}`, operation: 'Write', arguments: { file_path: draft.file_path, content: draft.parts.join('') }, next_action: input.next_action || 'Run the declared checks on the published artifact.' }, { ...options, draftPublication: true });
+    }
+    const result = await this.mutate(options.sessionId, async (_, book) => {
+      const task = this.task(book, input); if (task.status === 'done') throw failure('La tarea ya está cerrada.');
+      if (input.content === undefined || !input.file_path || input.action === 'chunk' && input.index === undefined || input.action === 'append' && !input.part_id) throw failure('append requiere part_id, content y file_path; chunk requiere index, content y file_path.');
+      if (book.drafts.filter(draft => draft.task_id === task.id).length >= 32 && !book.drafts.some(draft => draft.task_id === task.id && draft.id === input.draft_id)) throw failure('Máximo 32 borradores por tarea; divide el trabajo.');
+      const draft = book.drafts.find(draft => draft.task_id === task.id && draft.id === input.draft_id), parts = draft?.parts || [];
+      if (draft && draft.file_path !== input.file_path) throw failure('El borrador ya tiene otra ruta.');
+      const savedIndex = input.action === 'append' ? draft?.part_ids?.indexOf(input.part_id) ?? -1 : -1;
+      const index = input.action === 'append' ? savedIndex >= 0 ? savedIndex : parts.length : input.index;
+      if (index < parts.length) { if (parts[index] !== input.content || Boolean(input.final) !== Boolean(draft.complete && index === parts.length - 1)) throw failure('Parte ya guardada con otros bytes o frontera final.'); return { draft_id: input.draft_id, digest: draft.digest, next_index: parts.length, complete: draft.complete, ...(input.action === 'append' ? { part_id: input.part_id } : {}), reused: true }; }
+      if (index !== parts.length || draft?.complete) throw failure(`Índice de parte fuera de orden o borrador completo. WorkDraft ${input.draft_id}: next_index:${parts.length}, complete:${Boolean(draft?.complete)}. Un borrador nuevo empieza en index:0; usa append con part_id estable para que la casa asigne el índice. No regeneres los bytes por un error de índice.`);
+      const content = [...parts, input.content].join(''); if (Buffer.byteLength(content) > 1024 * 1024) throw failure('Borrador mayor a 1 MiB.');
+      await this.fact(options, { type: 'work_draft_chunk', task_id: task.id, task_digest: workDigest(task), plan_version: book.plan.version, draft_id: input.draft_id, file_path: input.file_path, index, ...(input.action === 'append' ? { part_id: input.part_id } : {}), content: input.content, final: Boolean(input.final), next_action: input.next_action, next_action_source: 'model_suggestion_not_authority' });
+      return { draft_id: input.draft_id, digest: digest(content), next_index: parts.length + 1, bytes: Buffer.byteLength(content), complete: Boolean(input.final), ...(input.action === 'append' ? { part_id: input.part_id } : {}), next_action: input.next_action, next_action_source: 'model_suggestion_not_authority' };
+    }); await this.notify(options.sessionId); return JSON.stringify(result);
+  }
+  operations() {
+    const task = { task_id: id, plan_version: version };
+    return [
+      { name: 'WorkPlanSet', description: 'Plan small tasks before effects; each needs id/title/criterion/checks. Up to 32 artifact files. Checks use exact tools, e.g. Read:{file_path:"file"}. Verification needs assertions. append:true adds tasks without resending old ones; no permission grant.', input_schema: schema({ objective: str(2200), expected_version: version, append: { type: 'boolean' }, tasks: { type: 'array', minItems: 1, maxItems: 24, items: schema({ id, title: str(300), criterion: str(1000), phase: { type: 'string', enum: ['discovery','implementation','verification'] }, capabilities: { type: 'array', maxItems: 4, uniqueItems: true, items: str(100) }, artifacts: { type: 'array', maxItems: 32, uniqueItems: true, items: str(1024) }, depends_on: { type: 'array', maxItems: 24, items: id }, checks: { type: 'array', maxItems: 4, items: schema({ step_id: id, operation: { ...str(128), description: 'Exact callable tool name from the catalogue, never an instruction or test description.' }, arguments: args, assertions: { type: 'array', minItems: 1, maxItems: 4, items: assertionSchema } }, ['step_id', 'operation', 'arguments']) } }, ['id', 'title', 'criterion', 'checks']) }, retire_ids: { type: 'array', maxItems: 24, items: id }, reason: str(1000) }, ['objective', 'expected_version', 'tasks']), run: (input, options) => this.setPlan(input, options) },
+      { name: 'WorkCheckRepair', description: 'Repair check contracts locally without replacing tasks, retiring drafts or replaying effects. Supply current plan_version only for deterministic suggestions (Read/Grep keys, integer types, unique canonical MCP names). Optional repairs use exact check digests. Assertions/criteria/artifacts stay unchanged. Missing MCP: acquire browser.verify then retry. No permission grant.', input_schema: schema({ plan_version: version, literal_types_only: { type: 'boolean' }, repairs: { type: 'array', minItems: 1, maxItems: 8, items: schema({task_id:id,step_id:id,expected_digest:{type:'string',pattern:'^[a-f0-9]{64}$'},operation:str(128),arguments:args},['task_id','step_id','expected_digest']) }, reason:str(1000) }, ['plan_version']), run: (input,options) => this.repairChecks(input,options) },
+      { name: 'WorkTaskUpdate', description: 'Start/block/close a task. done with verify:true runs missing/stale read-only checks from the plan through the judge, then closes. No model roundtrip per check. Opaque/mutating checks require explicit WorkStepRun. Records declared checks, not semantic objective proof.', input_schema: schema({ ...task, status: { type: 'string', enum: ['in_progress', 'blocked', 'done'] }, verify: { type: 'boolean' }, reason: str(1000) }, ['task_id', 'plan_version', 'status']), run: (input, options) => this.updateTask(input, options) },
+      { name: 'WorkStepRun', description: 'Call WorkCheckRepair, ToolPack and WorkTaskUpdate DIRECTLY, never nested here. Run a declared check OR additional work/observations through the judge. Declared check: existing step_id, omit operation/arguments. Additional observation (DOM, console, network, discovery) or implementation: NEW unique step_id plus exact operation and arguments; NO plan edit or check repair is needed. Extra steps do not change assertions. Do not rename existing checks. Retry failed read-only checks with SAME step_id and recheck:true; never repeat uncertain mutations. Completed steps reuse receipts.', input_schema: schema({ ...task, step_id: id, operation: str(128), arguments: args, next_action: str(1000), recheck: { type: 'boolean' } }, ['task_id', 'plan_version', 'step_id']), run: (input, options) => this.runStep(input, options) },
+      { name: 'WorkDraft', description: 'Durable scripts in ANY language. Prefer append with a stable part_id: host assigns cursor and deduplicates identical retries. Send short logical sections; up to 64000 chars per complete call. final:true marks last section; publish independently judges Write on the immutable final draft. Legacy chunk uses zero-based index (first:0). Archived chunks are never executed.', input_schema: schema({ ...task, draft_id: id, action: { type: 'string', enum: ['append', 'chunk', 'read', 'publish'] }, file_path: str(1024), part_id: id, index: { type: 'integer', minimum: 0, description: 'Legacy chunk cursor: first index is 0, then use returned next_index.' }, content: { type: 'string', maxLength: 64000 }, final: { type: 'boolean' }, expected_digest: { type: 'string', pattern: '^[a-f0-9]{64}$' }, offset: { type: 'integer', minimum: 0 }, limit: { type: 'integer', minimum: 1, maximum: 8000 }, next_action: str(1000) }, ['task_id', 'plan_version', 'draft_id', 'action']), run: (input, options) => this.draft(input, options) },
+      { name: 'WorkBoard', description: 'Read a missing board/check definition and exact repair_call. Conversation carries normal progress; query only when information is missing, without polling. task_id retrieves exact definitions/checks and small step references for ONE task.', input_schema: schema({ task_id: id }, []), run: async (input, { sessionId }) => { const session = await this.store.load(sessionId), book = foldWorkBook(session, this.house.stateContext()); const projected = workProjection(session, this.house.stateContext()), issues = checkContractIssues(book.tasks,name=>this.house.registry.get(name),{rejectMissing:true}); return JSON.stringify({ ...(issues.length ? {check_contract_issues:{issues,repair_call:{name:'WorkCheckRepair',input:{plan_version:book.plan.version}}}} : {}), plan_control: planControl(projected), ...(projected || { plan: null, cards: [], counts: { done: 0, pending: 0, in_progress: 0, blocked: 0, needs_verification: 0 }, current: null, drafts: [], next_action: 'Declare a plan with WorkPlanSet before multi-step work.' }), ...(input.task_id ? { tasks: book.tasks.filter(task => task.id === input.task_id), steps: book.steps.filter(step => step.task_id === input.task_id).map(({ step_id, operation, status, receipt_id, receipt_ref, next_action }) => ({ step_id, operation, status, receipt_id, receipt_ref, next_action })) } : {}) }); } },
+    ].map(definition => ({ ...definition, input_schema: definition.name === 'WorkDraft' ? { ...definition.input_schema, allOf: [{ if: { properties: { action: { const: 'chunk' } } }, then: { required: ['file_path', 'index', 'content'] } }, { if: { properties: { action: { const: 'append' } } }, then: { required: ['file_path', 'part_id', 'content'], not: { required: ['index'] } } }] } : definition.input_schema, native: true, effects: ['WorkStepRun', 'WorkDraft', 'WorkTaskUpdate'].includes(definition.name) ? { workspace: 'unknown', external: 'unknown', process: 'unknown', authority: 'none' } : { workspace: 'none', external: 'none', process: 'none', authority: 'none' } }));
+  }
+}
+
+export function registerWorkOperations({ store, house, onEvent, artifactObservation }) {
+  if (artifactObservation) {
+    const { sessionId, operation } = artifactObservation;
+    if (typeof sessionId !== 'string' || !['Read', 'FileInfo'].includes(operation)) throw failure('Invalid host artifact observer.');
+    if (!artifactObservers.has(house)) artifactObservers.set(house, new Map());
+    artifactObservers.get(house).set(sessionId, operation);
+  }
+  const coordinator = new WorkCoordinator({ store, house, onEvent });
+  for (const definition of coordinator.operations()) if (!house.registry.get(definition.name)) house.registry.add(definition);
+  return coordinator;
+}
+
+export async function checkpointWork(store, sessionId, reason) {
+  const session = await store.load(sessionId), state = workProjection(session); if (!state) return null;
+  const event = { type: 'work_checkpoint', source: 'work_host', house: session.cwd, session_id: sessionId, actor: { id: 'house-runtime', kind: 'agent' }, reason, plan_digest: state.plan.digest, plan_version: state.plan.version, task_id: state.current?.id || null, next_action: state.next_action, unfinished: state.cards.filter(task => task.status !== 'done').map(task => task.id), draft_refs: state.drafts };
+  await store.append(sessionId, event); return event;
+}