openclaw-node-harness 2.0.4 → 2.1.0

package/bin/mesh-task-daemon.js

@@ -35,16 +35,29 @@ const { connect, StringCodec } = require('nats');
 const { createTask, TaskStore, TASK_STATUS, KV_BUCKET } = require('../lib/mesh-tasks');
 const { createSession, CollabStore, COLLAB_STATUS, COLLAB_KV_BUCKET } = require('../lib/mesh-collab');
 const { createPlan, autoRoutePlan, PlanStore, PLAN_STATUS, SUBTASK_STATUS, PLANS_KV_BUCKET } = require('../lib/mesh-plans');
+const { findRole, findRoleByScope, validateRequiredOutputs, checkForbiddenPatterns } = require('../lib/role-loader');
 const os = require('os');
+const path = require('path');
+
+// Role search directories
+const ROLE_DIRS = [
+  path.join(process.env.HOME || '/root', '.openclaw', 'roles'),
+  path.join(__dirname, '..', 'config', 'roles'),
+];
 
 const sc = StringCodec();
 const { NATS_URL } = require('../lib/nats-resolve');
 const BUDGET_CHECK_INTERVAL = 30000; // 30s
 const STALL_MINUTES = parseInt(process.env.MESH_STALL_MINUTES || '5'); // no heartbeat for this long → stalled
+const CIRCLING_STEP_TIMEOUT_MS = parseInt(process.env.MESH_CIRCLING_STEP_TIMEOUT_MS || String(10 * 60 * 1000)); // 10 min default
 const NODE_ID = os.hostname().toLowerCase().replace(/[^a-z0-9-]/g, '-');
 
 let nc, store, collabStore, planStore;
 
+// Active step timers for circling sessions — keyed by sessionId.
+// Cleared when the step completes normally; fires degrade logic if step hangs.
+const circlingStepTimers = new Map();
+
 // ── Logging ─────────────────────────────────────────
 
 function log(msg) {
@@ -223,15 +236,90 @@ async function handleComplete(msg) {
   const { task_id, result } = parseRequest(msg);
   if (!task_id) return respondError(msg, 'task_id is required');
 
-  const task = await store.markCompleted(task_id, result || { success: true });
-  if (!task) return respondError(msg, `Task ${task_id} not found`);
+  // Determine if this task requires human review before completing.
+  // requires_review logic:
+  //   - explicit true/false on task → honor it
+  //   - null (default) → auto-compute:
+  //     * mode: human → always (by definition)
+  //     * mode: soul → always (creative/strategic work, no mechanical verification)
+  //     * collab_mesh without metric → yes (peer review without mechanical check)
+  //     * solo_mesh WITH metric → no (metric IS the verification)
+  //     * solo_mesh WITHOUT metric → yes (no mechanical check = human must validate)
+  //     * local → no (Daedalus/companion handles these interactively)
+  const existingTask = await store.get(task_id);
+  if (!existingTask) return respondError(msg, `Task ${task_id} not found`);
+
+  let needsReview = existingTask.requires_review;
+  if (needsReview === null || needsReview === undefined) {
+    const mode = existingTask.collaboration ? 'collab_mesh' : (existingTask.tags?.includes('soul') ? 'soul' : 'solo_mesh');
+    const hasMetric = !!existingTask.metric;
+
+    if (mode === 'soul' || existingTask.tags?.includes('human')) {
+      needsReview = true;
+    } else if (mode === 'collab_mesh' && !hasMetric) {
+      needsReview = true;
+    } else if (mode === 'solo_mesh' && !hasMetric) {
+      needsReview = true;
+    } else {
+      needsReview = false;
+    }
+  }
 
-  const elapsed = task.started_at
-    ? ((new Date(task.completed_at) - new Date(task.started_at)) / 60000).toFixed(1)
-    : '?';
+  // Role-based post-completion validation — runs UNCONDITIONALLY on all tasks
+  // with a role, regardless of review status. Validation results are included
+  // in the pending_review metadata so human reviewers see structured checks.
+  let roleValidation = { passed: true, issues: [] };
+  if (existingTask.role) {
+    const role = findRole(existingTask.role, ROLE_DIRS);
+    if (role) {
+      const outputFiles = result?.artifacts || [];
+      const harnessFiles = (result?.harness?.violations || []).flatMap(v => v.files || []);
+      const allFiles = [...new Set([...outputFiles, ...harnessFiles])];
+
+      if (allFiles.length > 0) {
+        const reqResult = validateRequiredOutputs(role, allFiles, null);
+        if (!reqResult.passed) {
+          roleValidation.passed = false;
+          roleValidation.issues.push(...reqResult.failures.map(f => `[required_output] ${f.description}: ${f.detail}`));
+        }
+      }
 
-  log(`COMPLETE ${task_id} in ${elapsed}m: ${result?.summary || 'no summary'}`);
-  publishEvent('completed', task);
+      if (!roleValidation.passed) {
+        log(`ROLE VALIDATION FAILED for ${task_id} (role: ${role.id}): ${roleValidation.issues.length} issue(s)`);
+        for (const issue of roleValidation.issues) log(`  - ${issue}`);
+        needsReview = true; // force review if validation failed on auto-complete path
+      } else {
+        log(`ROLE VALIDATION PASSED for ${task_id} (role: ${role.id})`);
+      }
+    }
+  }
+
+  let task;
+  if (needsReview) {
+    // Gate: task goes to pending_review instead of completed
+    // Include role validation results in the review metadata
+    const enrichedResult = {
+      ...(result || { success: true }),
+      role_validation: roleValidation,
+    };
+    task = await store.markPendingReview(task_id, enrichedResult);
+    const elapsed = task.started_at
+      ? ((new Date(task.review_requested_at) - new Date(task.started_at)) / 60000).toFixed(1)
+      : '?';
+    log(`PENDING REVIEW ${task_id} in ${elapsed}m: ${result?.summary || 'no summary'}`);
+    log(`  Approve: mesh task approve ${task_id}  |  Reject: mesh task reject ${task_id} --reason "..."`);
+    publishEvent('pending_review', task);
+    // Update plan subtask status so `mesh plan show` reflects pending_review
+    await updatePlanSubtaskStatus(task_id, 'pending_review');
+    // Do NOT advance plan wave — task is not yet "completed" for dependency purposes
+  } else {
+    task = await store.markCompleted(task_id, result || { success: true });
+    const elapsed = task.started_at
+      ? ((new Date(task.completed_at) - new Date(task.started_at)) / 60000).toFixed(1)
+      : '?';
+    log(`COMPLETE ${task_id} in ${elapsed}m: ${result?.summary || 'no summary'}`);
+    publishEvent('completed', task);
+  }
 
   // NOTE: no cleanupTaskCollabSession here — collab tasks complete via
   // evaluateRound → markCompleted on the session, then store.markCompleted
@@ -241,8 +329,10 @@ async function handleComplete(msg) {
     collabStore.clearAuditErrorCount(task.collab_session_id);
   }
 
-  // Check if this task belongs to a plan
-  await checkPlanProgress(task_id, 'completed');
+  // Only advance plan if actually completed (not pending_review)
+  if (task.status === TASK_STATUS.COMPLETED) {
+    await checkPlanProgress(task_id, 'completed');
+  }
 
   respond(msg, task);
 }
@@ -262,10 +352,52 @@ async function handleFail(msg) {
   publishEvent('failed', task);
   await cleanupTaskCollabSession(task, `Parent task ${task_id} failed: ${reason}`);
 
-  // Check if this task belongs to a plan
+  // Phase F: Escalation — if the task has a role with escalation mapping,
+  // create an escalation task before cascading failure through the plan.
+  let escalated = false;
+  if (task.role) {
+    const role = findRole(task.role, ROLE_DIRS);
+    if (role && role.escalation) {
+      // Determine failure type for escalation routing
+      let failureType = 'on_metric_failure';
+      if (reason && reason.includes('Budget exceeded')) failureType = 'on_budget_exceeded';
+      if (reason && reason.includes('scope')) failureType = 'on_scope_violation';
+
+      const escalationTarget = role.escalation[failureType];
+      if (escalationTarget) {
+        const escalationTask = createTask({
+          task_id: `ESC-${task_id}-${Date.now()}`,
+          title: `[Escalation] ${task.title}`,
+          description: [
+            `Escalated from ${task_id} (role: ${task.role}, failure: ${failureType}).`,
+            `Original reason: ${reason}`,
+            '',
+            `Original description: ${task.description}`,
+          ].join('\n'),
+          budget_minutes: Math.ceil(task.budget_minutes * 1.5), // 50% more budget
+          metric: task.metric,
+          scope: task.scope,
+          success_criteria: task.success_criteria,
+          role: escalationTarget === 'human' ? null : escalationTarget,
+          requires_review: escalationTarget === 'human' ? true : null,
+          tags: [...(task.tags || []), 'escalation', `escalated_from:${task_id}`],
+          plan_id: task.plan_id,
+          subtask_id: task.subtask_id, // Wire back to original plan subtask for recovery
+        });
+        await store.put(escalationTask);
+        publishEvent('submitted', escalationTask);
+        log(`ESCALATED ${task_id} → ${escalationTask.task_id} (target role: ${escalationTarget})`);
+        escalated = true;
+      }
+    }
+  }
+
+  // Check if this task belongs to a plan (escalation doesn't block cascade —
+  // the escalation task is independent. If the plan has abort_on_critical_fail
+  // and this was critical, it still aborts. The escalation is a parallel attempt.)
   await checkPlanProgress(task_id, 'failed');
 
-  respond(msg, task);
+  respond(msg, { ...task, escalated, escalation_task_id: escalated ? `ESC-${task_id}-${Date.now()}` : null });
 }
 
 /**
@@ -367,6 +499,44 @@ async function handleCancel(msg) {
   respond(msg, task);
 }
 
+// ── Task Review (Approval Gate) ─────────────────────
+
+/**
+ * mesh.tasks.approve — Human approves a pending_review task.
+ * Transitions to completed and advances plan wave if applicable.
+ */
+async function handleTaskApprove(msg) {
+  const { task_id } = parseRequest(msg);
+  if (!task_id) return respondError(msg, 'task_id is required');
+
+  const task = await store.markApproved(task_id);
+  if (!task) return respondError(msg, `Task ${task_id} not found or not in pending_review status`);
+
+  log(`APPROVED ${task_id}: human review passed`);
+  publishEvent('completed', task);
+
+  // Now advance plan wave (this was blocked while in pending_review)
+  await checkPlanProgress(task_id, 'completed');
+
+  respond(msg, task);
+}
+
+/**
+ * mesh.tasks.reject — Human rejects a pending_review task.
+ * Re-queues the task with rejection reason injected for next attempt.
+ */
+async function handleTaskReject(msg) {
+  const { task_id, reason } = parseRequest(msg);
+  if (!task_id) return respondError(msg, 'task_id is required');
+
+  const task = await store.markRejected(task_id, reason || 'Rejected by reviewer');
+  if (!task) return respondError(msg, `Task ${task_id} not found or not in pending_review status`);
+
+  log(`REJECTED ${task_id}: ${reason || 'no reason'} — re-queued for retry`);
+  publishEvent('rejected', task);
+  respond(msg, task);
+}
+
 // ── Budget Enforcement + Stall Detection ────────────
 
 async function detectStalls() {
@@ -435,6 +605,9 @@ async function detectStalls() {
     );
     if (releasedTask) publishEvent('released', releasedTask);
 
+    // Update plan progress if this task belongs to a plan
+    await checkPlanProgress(task.task_id, 'failed');
+
     // Notify the agent's node (fire-and-forget)
     if (task.owner) {
       nc.publish(`mesh.agent.${task.owner}.stall`, sc.encode(JSON.stringify({
@@ -446,6 +619,31 @@ async function detectStalls() {
   }
 }
 
+/**
+ * Process proposed tasks — worker nodes write tasks with status "proposed"
+ * directly to KV. The lead daemon validates and transitions them.
+ */
+async function processProposals() {
+  const proposed = await store.list({ status: TASK_STATUS.PROPOSED });
+  for (const task of proposed) {
+    // Basic validation: must have title and origin
+    if (!task.title || !task.origin) {
+      task.status = TASK_STATUS.REJECTED;
+      task.result = { success: false, summary: 'Missing required fields (title, origin)' };
+      await store.put(task);
+      log(`REJECTED ${task.task_id}: missing required fields`);
+      publishEvent('rejected', task);
+      continue;
+    }
+
+    // Accept: transition to queued
+    task.status = TASK_STATUS.QUEUED;
+    await store.put(task);
+    log(`ACCEPTED proposal ${task.task_id} from ${task.origin}: "${task.title}"`);
+    publishEvent('submitted', task);
+  }
+}
+
 async function enforceBudgets() {
   const overBudget = await store.findOverBudget();
 
@@ -461,6 +659,19 @@ async function enforceBudgets() {
     );
     if (failedTask) publishEvent('failed', failedTask);
 
+    // Clean up any collab session for this task
+    if (collabStore && task.collab_session_id) {
+      try {
+        await collabStore.markAborted(task.collab_session_id, `Budget exceeded for task ${task.task_id}`);
+        log(`BUDGET → COLLAB: aborted session ${task.collab_session_id}`);
+      } catch (err) {
+        log(`BUDGET → COLLAB ERROR: ${err.message}`);
+      }
+    }
+
+    // Update plan progress if this task belongs to a plan
+    await checkPlanProgress(task.task_id, 'failed');
+
     // Publish notification so the agent knows
     nc.publish(`mesh.agent.${task.owner}.budget_exceeded`, sc.encode(JSON.stringify({
       task_id: task.task_id,
@@ -537,7 +748,23 @@ async function handleCollabJoin(msg) {
 
   // Check if recruiting should close → start first round
   if (collabStore.isRecruitingDone(session)) {
-    await startCollabRound(session.session_id);
+    // Circling Strategy: assign worker_node_id before starting
+    if (session.mode === 'circling_strategy' && session.circling) {
+      const freshSession = await collabStore.get(session.session_id);
+      if (freshSession.circling && !freshSession.circling.worker_node_id) {
+        // Assign all role IDs at recruiting close — stable for the session lifetime.
+        const workerNode = freshSession.nodes.find(n => n.role === 'worker') || freshSession.nodes[0];
+        freshSession.circling.worker_node_id = workerNode.node_id;
+        const reviewers = freshSession.nodes.filter(n => n.node_id !== workerNode.node_id);
+        freshSession.circling.reviewerA_node_id = reviewers[0]?.node_id || null;
+        freshSession.circling.reviewerB_node_id = reviewers[1]?.node_id || null;
+        await collabStore.put(freshSession);
+        log(`CIRCLING: Roles assigned → Worker: ${workerNode.node_id}, RevA: ${reviewers[0]?.node_id}, RevB: ${reviewers[1]?.node_id}`);
+      }
+      await startCirclingStep(session.session_id);
+    } else {
+      await startCollabRound(session.session_id);
+    }
   }
 
   respond(msg, session);
@@ -561,6 +788,12 @@ async function handleCollabLeave(msg) {
   if (session.status === COLLAB_STATUS.ACTIVE && session.nodes.length < session.min_nodes) {
     await collabStore.markAborted(session_id, `Below min_nodes: ${session.nodes.length} < ${session.min_nodes}`);
     publishCollabEvent('aborted', session);
+  } else if (session.status === COLLAB_STATUS.ACTIVE) {
+    // Re-check if the round is now complete (removed node excluded from quorum)
+    const updated = await collabStore.get(session_id);
+    if (updated && collabStore.isRoundComplete(updated)) {
+      await evaluateRound(session_id);
+    }
   }
 
   respond(msg, session);
@@ -636,11 +869,74 @@ async function handleCollabReflect(msg) {
   });
   publishCollabEvent('reflection_received', session);
 
+  // Circling Strategy: handle two-step barrier, artifact storage, directed handoffs
+  if (session.mode === 'circling_strategy' && session.circling) {
+    // Store circling artifacts
+    if (reflection.circling_artifacts && reflection.circling_artifacts.length > 0) {
+      const { current_subround, current_step } = session.circling;
+      const isWorker = reflection.node_id === session.circling.worker_node_id;
+      // Use stored reviewer IDs for stable identity (falls back to array-index if not set)
+      let nodeRole;
+      if (isWorker) {
+        nodeRole = 'worker';
+      } else if (session.circling.reviewerA_node_id && session.circling.reviewerB_node_id) {
+        nodeRole = reflection.node_id === session.circling.reviewerA_node_id ? 'reviewerA' : 'reviewerB';
+      } else {
+        const reviewerNodes = session.nodes.filter(n => n.node_id !== session.circling.worker_node_id);
+        nodeRole = reviewerNodes[0]?.node_id === reflection.node_id ? 'reviewerA' : 'reviewerB';
+      }
+
+      for (const art of reflection.circling_artifacts) {
+        const key = `sr${current_subround}_step${current_step}_${nodeRole}_${art.type}`;
+        await collabStore.storeArtifact(session_id, key, art.content);
+        log(`CIRCLING ARTIFACT: ${key} stored (${(art.content || '').length} chars)`);
+      }
+    } else if (reflection.parse_failed) {
+      // Parse failure: record and check retry threshold.
+      // If a node consistently fails, the barrier still advances (the reflection counts)
+      // but downstream nodes get [UNAVAILABLE] placeholders. After 3 failures for the
+      // same node+step, log a critical warning — the only full recovery is the daemon's
+      // global stall timeout. See: mesh-collab.js recordArtifactFailure / getArtifactFailureCount
+      const failCount = await collabStore.recordArtifactFailure(session_id, reflection.node_id);
+      log(`CIRCLING PARSE FAILURE: ${reflection.node_id} in ${session_id} (attempt ${failCount})`);
+      await collabStore.appendAudit(session_id, 'artifact_parse_failed', {
+        node_id: reflection.node_id,
+        step: session.circling.current_step,
+        subround: session.circling.current_subround,
+        failure_count: failCount,
+      });
+      if (failCount >= 3) {
+        log(`CIRCLING CRITICAL: ${reflection.node_id} failed ${failCount}x at SR${session.circling.current_subround}/Step${session.circling.current_step} — no artifacts will be available for downstream nodes`);
+      }
+    } else {
+      // No artifacts but not a parse failure — unexpected
+      log(`CIRCLING WARNING: ${reflection.node_id} submitted reflection without artifacts in ${session_id}`);
+    }
+
+    // Check if current circling step is complete (all 3 nodes submitted)
+    const freshSession = await collabStore.get(session_id);
+    if (collabStore.isCirclingStepComplete(freshSession)) {
+      clearCirclingStepTimer(session_id);
+      const nextState = await collabStore.advanceCirclingStep(session_id);
+      if (!nextState) {
+        log(`CIRCLING ERROR: advanceCirclingStep returned null for ${session_id}`);
+      } else if (nextState.phase === 'complete') {
+        // Finalization done — complete the session
+        await completeCirclingSession(session_id);
+      } else if (nextState.needsGate) {
+        // Automation tier gate — wait for human approval
+        log(`CIRCLING GATE: ${session_id} SR${nextState.subround} — waiting for human approval (tier ${freshSession.circling.automation_tier})`);
+        publishCollabEvent('circling_gate', freshSession);
+      } else {
+        // Auto-advance to next step
+        await startCirclingStep(session_id);
+      }
+    }
   // Sequential mode: advance turn, notify next node or evaluate round
   // Parallel mode: check if all reflections are in → evaluate convergence
   // NOTE: Node.js single-threaded event loop prevents concurrent execution of this
   // handler — no mutex needed. advanceTurn() is safe without CAS here.
-  if (session.mode === 'sequential') {
+  } else if (session.mode === 'sequential') {
     const nextNodeId = await collabStore.advanceTurn(session_id);
     if (nextNodeId) {
       // Notify only the next-turn node with accumulated intra-round intel
@@ -928,6 +1224,275 @@ async function evaluateRound(sessionId) {
   }
 }
 
+// ── Circling Strategy Functions ──────────────────────
+
+/**
+ * Start a circling step: compile directed inputs and notify each node.
+ * Called after advanceCirclingStep transitions the state machine.
+ * Also creates a new round in the session (for reflection storage).
+ */
+async function startCirclingStep(sessionId) {
+  const session = await collabStore.get(sessionId);
+  if (!session || !session.circling) return;
+
+  const { phase, current_subround, current_step } = session.circling;
+
+  // Record step start time for timeout rehydration after daemon restart
+  session.circling.step_started_at = new Date().toISOString();
+  await collabStore.put(session);
+
+  // Start a new round in the session for reflection storage
+  // (each step gets its own round to keep reflections organized)
+  const round = await collabStore.startRound(sessionId);
+  if (!round) {
+    log(`CIRCLING ERROR: startRound failed for ${sessionId} (aborted?)`);
+    return;
+  }
+
+  const freshSession = await collabStore.get(sessionId);
+  const parentTask = await store.get(freshSession.task_id);
+  const taskDescription = parentTask?.description || '';
+
+  const stepLabel = phase === 'init' ? 'Init'
+    : phase === 'finalization' ? 'Finalization'
+    : `SR${current_subround} Step${current_step}`;
+  log(`CIRCLING ${sessionId} ${stepLabel} START (${freshSession.nodes.length} nodes)`);
+
+  await collabStore.appendAudit(sessionId, 'circling_step_started', {
+    phase, subround: current_subround, step: current_step,
+    nodes: freshSession.nodes.map(n => n.node_id),
+  });
+  publishCollabEvent('circling_step_started', freshSession);
+
+  // Notify each node with their directed input
+  for (const node of freshSession.nodes) {
+    const directedInput = collabStore.compileDirectedInput(freshSession, node.node_id, taskDescription);
+
+    nc.publish(`mesh.collab.${sessionId}.node.${node.node_id}.round`, sc.encode(JSON.stringify({
+      session_id: sessionId,
+      task_id: freshSession.task_id,
+      round_number: freshSession.current_round,
+      directed_input: directedInput,
+      shared_intel: '',  // empty for circling — uses directed_input instead
+      my_scope: node.scope,
+      my_role: node.role,
+      mode: 'circling_strategy',
+      circling_phase: phase,
+      circling_step: current_step,
+      circling_subround: current_subround,
+    })));
+  }
+
+  // Set step-level timeout. If the barrier isn't met within CIRCLING_STEP_TIMEOUT_MS,
+  // mark unresponsive nodes as dead and force-advance with degraded input.
+  clearCirclingStepTimer(sessionId);
+  const stepSnapshot = { phase, subround: current_subround, step: current_step };
+  const timer = setTimeout(() => handleCirclingStepTimeout(sessionId, stepSnapshot), CIRCLING_STEP_TIMEOUT_MS);
+  circlingStepTimers.set(sessionId, timer);
+}
+
+/**
+ * Handle a circling step timeout. If the step hasn't advanced since the timer was set,
+ * mark nodes that haven't submitted as dead and force-advance.
+ */
+async function handleCirclingStepTimeout(sessionId, stepSnapshot) {
+  circlingStepTimers.delete(sessionId);
+
+  const session = await collabStore.get(sessionId);
+  if (!session || !session.circling) return;
+
+  const { phase, current_subround, current_step } = session.circling;
+
+  // Check if the step already advanced (timer is stale)
+  if (phase !== stepSnapshot.phase ||
+      current_subround !== stepSnapshot.subround ||
+      current_step !== stepSnapshot.step) {
+    return; // Step already moved on — nothing to do
+  }
+
+  log(`CIRCLING STEP TIMEOUT: ${sessionId} ${phase}/SR${current_subround}/Step${current_step} — forcing advance`);
+
+  const currentRound = session.rounds[session.rounds.length - 1];
+  if (!currentRound) return;
+
+  const submittedNodeIds = new Set(
+    currentRound.reflections
+      .filter(r => r.circling_step === current_step)
+      .map(r => r.node_id)
+  );
+
+  // Mark nodes that haven't submitted as dead
+  for (const node of session.nodes) {
+    if (node.status !== 'dead' && !submittedNodeIds.has(node.node_id)) {
+      await collabStore.setNodeStatus(sessionId, node.node_id, 'dead');
+      log(`CIRCLING STEP TIMEOUT: marked ${node.node_id} as dead (no submission within ${CIRCLING_STEP_TIMEOUT_MS / 60000}m)`);
+      await collabStore.appendAudit(sessionId, 'node_marked_dead', {
+        node_id: node.node_id,
+        reason: `Circling step timeout: no reflection for ${phase}/SR${current_subround}/Step${current_step}`,
+      });
+    }
+  }
+
+  // Re-check barrier with dead nodes excluded
+  const freshSession = await collabStore.get(sessionId);
+  if (collabStore.isCirclingStepComplete(freshSession)) {
+    const nextState = await collabStore.advanceCirclingStep(sessionId);
+    if (!nextState) {
+      log(`CIRCLING STEP TIMEOUT ERROR: advanceCirclingStep returned null for ${sessionId}`);
+    } else if (nextState.phase === 'complete') {
+      await completeCirclingSession(sessionId);
+    } else if (nextState.needsGate) {
+      log(`CIRCLING GATE: ${sessionId} SR${nextState.subround} — waiting for human approval (timeout-forced)`);
+      publishCollabEvent('circling_gate', freshSession);
+    } else {
+      await startCirclingStep(sessionId);
+    }
+  } else {
+    // Still not enough submissions even after marking dead nodes.
+    // All active nodes are dead — abort the session.
+    log(`CIRCLING STEP TIMEOUT: ${sessionId} — no active nodes remain. Aborting.`);
+    await collabStore.markAborted(sessionId, `All nodes timed out at ${phase}/SR${current_subround}/Step${current_step}`);
+    publishCollabEvent('aborted', await collabStore.get(sessionId));
+    await store.markReleased(session.task_id, `Circling session aborted: all nodes timed out`);
+  }
+}
+
+function clearCirclingStepTimer(sessionId) {
+  const existing = circlingStepTimers.get(sessionId);
+  if (existing) {
+    clearTimeout(existing);
+    circlingStepTimers.delete(sessionId);
+  }
+}
+
+/**
+ * Complete a circling session after finalization.
+ * Checks finalization votes: Worker converged + both Reviewers converged → COMPLETE.
+ * Any blocked vote → escalation gate (all tiers gate on finalization).
+ */
+async function completeCirclingSession(sessionId) {
+  clearCirclingStepTimer(sessionId);
+  const session = await collabStore.get(sessionId);
+  if (!session || !session.circling) return;
+
+  const lastRound = session.rounds[session.rounds.length - 1];
+  if (!lastRound) return;
+
+  // Check finalization votes
+  const blockedVotes = lastRound.reflections.filter(r => r.vote === 'blocked');
+
+  if (blockedVotes.length > 0) {
+    // Escalation: reviewer flagged critical concern
+    log(`CIRCLING ESCALATION ${sessionId}: ${blockedVotes.length} blocked vote(s) in finalization`);
+    await collabStore.appendAudit(sessionId, 'circling_escalation', {
+      blocked_nodes: blockedVotes.map(r => r.node_id),
+      summaries: blockedVotes.map(r => r.summary),
+    });
+    // Gate on finalization (all tiers)
+    publishCollabEvent('circling_gate', session);
+    return;
+  }
+
+  // All converged → complete
+  const finalArtifact = collabStore.getLatestArtifact(session, 'worker', 'workArtifact');
+  const completionDiff = collabStore.getLatestArtifact(session, 'worker', 'completionDiff');
+
+  log(`CIRCLING COMPLETED ${sessionId}: ${session.circling.current_subround} sub-rounds`);
+  await collabStore.markConverged(sessionId);
+
+  await collabStore.markCompleted(sessionId, {
+    artifacts: finalArtifact ? ['workArtifact'] : [],
+    summary: `Circling Strategy completed: ${session.circling.current_subround} sub-rounds, ${session.nodes.length} nodes. ${completionDiff ? 'CompletionDiff available.' : ''}`,
+    node_contributions: Object.fromEntries(
+      lastRound.reflections.map(r => [r.node_id, r.summary])
+    ),
+    circling_final_artifact: finalArtifact,
+    circling_completion_diff: completionDiff,
+  });
+  await collabStore.appendAudit(sessionId, 'session_completed', {
+    outcome: 'circling_finalized',
+    subrounds: session.circling.current_subround,
+    node_count: session.nodes.length,
+  });
+
+  // Complete parent task
+  const completedSession = await collabStore.get(sessionId);
+  await store.markCompleted(session.task_id, completedSession.result);
+  publishEvent('completed', await store.get(session.task_id));
+  publishCollabEvent('completed', completedSession);
+}
+
+/**
+ * mesh.collab.gate.approve — Human approves a circling tier gate.
+ * Resumes the circling protocol after a gate point.
+ */
+async function handleCirclingGateApprove(msg) {
+  const { session_id } = parseRequest(msg);
+  if (!session_id) return respondError(msg, 'session_id required');
+
+  const session = await collabStore.get(session_id);
+  if (!session || !session.circling) return respondError(msg, 'Not a circling session');
+
+  log(`CIRCLING GATE APPROVED: ${session_id} — resuming`);
+  await collabStore.appendAudit(session_id, 'gate_approved', {
+    phase: session.circling.phase,
+    subround: session.circling.current_subround,
+  });
+
+  // If finalization phase with blocked votes, the gate approve means "accept anyway"
+  if (session.circling.phase === 'complete' || session.circling.phase === 'finalization') {
+    // Force complete
+    const lastRound = session.rounds[session.rounds.length - 1];
+    const finalArtifact = collabStore.getLatestArtifact(session, 'worker', 'workArtifact');
+    await collabStore.markConverged(session_id);
+    await collabStore.markCompleted(session_id, {
+      artifacts: finalArtifact ? ['workArtifact'] : [],
+      summary: `Circling completed via gate approval after ${session.circling.current_subround} sub-rounds`,
+      node_contributions: Object.fromEntries(
+        (lastRound?.reflections || []).map(r => [r.node_id, r.summary])
+      ),
+      circling_final_artifact: finalArtifact,
+    });
+    const completedSession = await collabStore.get(session_id);
+    await store.markCompleted(session.task_id, completedSession.result);
+    publishEvent('completed', await store.get(session.task_id));
+    publishCollabEvent('completed', completedSession);
+  } else {
+    // Mid-protocol gate (tier 3) — resume next step
+    await startCirclingStep(session_id);
+  }
+
+  respond(msg, { approved: true });
+}
+
+/**
+ * mesh.collab.gate.reject — Human rejects a circling tier gate.
+ * Forces another sub-round.
+ */
+async function handleCirclingGateReject(msg) {
+  const { session_id } = parseRequest(msg);
+  if (!session_id) return respondError(msg, 'session_id required');
+
+  const session = await collabStore.get(session_id);
+  if (!session || !session.circling) return respondError(msg, 'Not a circling session');
+
+  log(`CIRCLING GATE REJECTED: ${session_id} — forcing another sub-round`);
+  await collabStore.appendAudit(session_id, 'gate_rejected', {
+    phase: session.circling.phase,
+    subround: session.circling.current_subround,
+  });
+
+  // Reset to circling phase, increment subround, step 1
+  session.circling.phase = 'circling';
+  session.circling.max_subrounds++; // allow one more
+  session.circling.current_step = 1;
+  session.circling.current_subround++;
+  await collabStore.put(session);
+
+  await startCirclingStep(session_id);
+  respond(msg, { rejected: true, new_subround: session.circling.current_subround });
+}
+
 // ── Collab Recruiting Timer ─────────────────────────
 
 /**
@@ -941,7 +1506,31 @@ async function checkRecruitingDeadlines() {
 
     if (session.nodes.length >= session.min_nodes) {
       log(`COLLAB RECRUIT DONE ${session.session_id}: ${session.nodes.length} nodes joined. Starting round 1.`);
-      await startCollabRound(session.session_id);
+      if (session.mode === 'circling_strategy' && session.circling) {
+        // Circling requires exactly 3 nodes (1 worker + 2 reviewers).
+        // Even if min_nodes was misconfigured, refuse to start with <3.
+        const hasWorker = session.nodes.some(n => n.role === 'worker');
+        const reviewerCount = session.nodes.filter(n => n.role === 'reviewer').length;
+        if (session.nodes.length < 3 || !hasWorker || reviewerCount < 2) {
+          log(`COLLAB RECRUIT FAILED ${session.session_id}: circling requires 1 worker + 2 reviewers, got ${session.nodes.length} nodes (worker: ${hasWorker}, reviewers: ${reviewerCount}). Aborting.`);
+          await collabStore.markAborted(session.session_id, `Circling requires 1 worker + 2 reviewers; got ${session.nodes.length} nodes`);
+          publishCollabEvent('aborted', await collabStore.get(session.session_id));
+          await store.markReleased(session.task_id, `Circling session failed: insufficient role distribution`);
+          continue;
+        }
+        // Assign all role IDs if not yet assigned
+        if (!session.circling.worker_node_id) {
+          const workerNode = session.nodes.find(n => n.role === 'worker') || session.nodes[0];
+          session.circling.worker_node_id = workerNode.node_id;
+          const reviewers = session.nodes.filter(n => n.node_id !== workerNode.node_id);
+          session.circling.reviewerA_node_id = reviewers[0]?.node_id || null;
+          session.circling.reviewerB_node_id = reviewers[1]?.node_id || null;
+          await collabStore.put(session);
+        }
+        await startCirclingStep(session.session_id);
+      } else {
+        await startCollabRound(session.session_id);
+      }
     } else {
       log(`COLLAB RECRUIT FAILED ${session.session_id}: only ${session.nodes.length}/${session.min_nodes} nodes. Aborting.`);
       await collabStore.markAborted(session.session_id, `Not enough nodes: ${session.nodes.length} < ${session.min_nodes}`);
@@ -952,6 +1541,46 @@ async function checkRecruitingDeadlines() {
   }
 }
 
+// ── Circling Step Timeout Sweep ──────────────────────
+
+/**
+ * Periodic sweep for stale circling steps. Handles timer rehydration after
+ * daemon restart — in-memory timers are lost on crash, but step_started_at
+ * in the session survives in JetStream KV.
+ *
+ * Runs every 60s. For each active circling session, checks if the current
+ * step has been running longer than CIRCLING_STEP_TIMEOUT_MS. If so, fires
+ * the timeout handler (which marks dead nodes and force-advances).
+ *
+ * Also serves as a safety net for timer drift or missed clearTimeout calls.
+ */
+async function sweepCirclingStepTimeouts() {
+  try {
+    const active = await collabStore.list({ status: COLLAB_STATUS.ACTIVE });
+    for (const session of active) {
+      if (session.mode !== 'circling_strategy' || !session.circling) continue;
+      if (session.circling.phase === 'complete') continue;
+      if (!session.circling.step_started_at) continue;
+
+      // Skip if an in-memory timer is already tracking this session
+      if (circlingStepTimers.has(session.session_id)) continue;
+
+      const elapsed = Date.now() - new Date(session.circling.step_started_at).getTime();
+      if (elapsed > CIRCLING_STEP_TIMEOUT_MS) {
+        log(`CIRCLING SWEEP: ${session.session_id} step stale (${(elapsed / 60000).toFixed(1)}m elapsed). Firing timeout handler.`);
+        const stepSnapshot = {
+          phase: session.circling.phase,
+          subround: session.circling.current_subround,
+          step: session.circling.current_step,
+        };
+        await handleCirclingStepTimeout(session.session_id, stepSnapshot);
+      }
+    }
+  } catch (err) {
+    log(`CIRCLING SWEEP ERROR: ${err.message}`);
+  }
+}
+
 // ── Plan Event Publishing ───────────────────────────
 
 function publishPlanEvent(eventType, plan) {
@@ -1136,6 +1765,11 @@ async function advancePlanWave(planId) {
       case 'solo_mesh':
       case 'collab_mesh': {
         // Submit as mesh task — inherit routing fields from parent task
+        // Auto-assign role from scope if subtask doesn't specify one
+        const subtaskRole = st.role || (st.scope && st.scope.length > 0
+          ? (findRoleByScope(st.scope, ROLE_DIRS)?.id || null)
+          : null);
+
         const meshTask = createTask({
           task_id: st.subtask_id,
           title: st.title,
@@ -1146,8 +1780,12 @@ async function advancePlanWave(planId) {
           success_criteria: st.success_criteria,
           tags: ['plan', planId],
           collaboration: st.delegation.collaboration || undefined,
+          plan_id: planId,
+          subtask_id: st.subtask_id,
+          role: subtaskRole,
           ...inheritedRouting,
         });
+        if (subtaskRole) log(`  → AUTO-ROLE ${st.subtask_id}: ${subtaskRole} (matched from scope)`);
         await store.put(meshTask);
         st.mesh_task_id = meshTask.task_id;
         publishEvent('submitted', meshTask);
@@ -1201,31 +1839,173 @@ async function advancePlanWave(planId) {
   publishPlanEvent('wave_started', plan);
 }
 
+/**
+ * Update a plan subtask's status without triggering wave advancement.
+ * Used for intermediate states like pending_review.
+ */
+async function updatePlanSubtaskStatus(taskId, newStatus) {
+  const task = await store.get(taskId);
+  if (!task || !task.plan_id) return;
+  const plan = await planStore.get(task.plan_id);
+  if (!plan) return;
+  const st = plan.subtasks.find(s => s.mesh_task_id === taskId || s.subtask_id === taskId);
+  if (!st) return;
+  st.status = newStatus;
+  await planStore.put(plan);
+  log(`PLAN SUBTASK ${st.subtask_id} → ${newStatus} (no wave advance)`);
+}
+
 // ── Plan Progress on Task Completion ────────────────
 
 /**
  * When a mesh task completes, check if it belongs to a plan and update accordingly.
- * Called after handleComplete/handleFail.
+ * Called after handleComplete/handleFail and from detectStalls/enforceBudgets.
  */
 async function checkPlanProgress(taskId, status) {
-  // Look for plans that reference this task
-  const allPlans = await planStore.list({ status: PLAN_STATUS.EXECUTING });
-  for (const plan of allPlans) {
-    const st = plan.subtasks.find(s => s.mesh_task_id === taskId || s.subtask_id === taskId);
-    if (!st) continue;
+  let plan = null;
+  let st = null;
+
+  // Fast path: O(1) lookup via plan_id back-reference on the task
+  const task = await store.get(taskId);
+  if (task && task.plan_id) {
+    plan = await planStore.get(task.plan_id);
+    if (plan) {
+      // Match by mesh_task_id, subtask_id, OR the task's subtask_id field
+      // (escalation tasks carry the original subtask_id for plan recovery)
+      st = plan.subtasks.find(s =>
+        s.mesh_task_id === taskId ||
+        s.subtask_id === taskId ||
+        (task.subtask_id && s.subtask_id === task.subtask_id)
+      );
+    }
+  }
 
-    st.status = status === 'completed' ? SUBTASK_STATUS.COMPLETED : SUBTASK_STATUS.FAILED;
+  // LEGACY: Remove after 2026-06-01. O(n*m) fallback for tasks created before
+  // plan_id back-reference was added. Track invocations to know when safe to delete.
+  if (!st) {
+    const allPlans = await planStore.list({ status: PLAN_STATUS.EXECUTING });
+    for (const p of allPlans) {
+      const found = p.subtasks.find(s => s.mesh_task_id === taskId || s.subtask_id === taskId);
+      if (found) {
+        plan = p;
+        st = found;
+        break;
+      }
+    }
+  }
+
+  if (!plan || !st) return;
+
+  // Escalation recovery: if a subtask was FAILED/BLOCKED but an escalation task
+  // completes successfully for it, override status to COMPLETED and unblock dependents.
+  const isEscalationRecovery = (
+    status === 'completed' &&
+    (st.status === SUBTASK_STATUS.FAILED || st.status === SUBTASK_STATUS.BLOCKED) &&
+    task && task.tags && task.tags.includes('escalation')
+  );
+
+  if (isEscalationRecovery) {
+    log(`ESCALATION RECOVERY ${plan.plan_id}: subtask ${st.subtask_id} recovered by ${taskId}`);
+    st.status = SUBTASK_STATUS.COMPLETED;
+    st.result = { success: true, summary: `Recovered by escalation task ${taskId}` };
+    // Unblock any dependents that were blocked by the original failure
+    for (const dep of plan.subtasks) {
+      if (dep.status === SUBTASK_STATUS.BLOCKED && dep.depends_on.includes(st.subtask_id)) {
+        dep.status = SUBTASK_STATUS.PENDING;
+        dep.result = null;
+        log(`  UNBLOCKED: ${dep.subtask_id} (dependency ${st.subtask_id} recovered)`);
+      }
+    }
     await planStore.put(plan);
+    publishPlanEvent('subtask_recovered', plan);
+    await advancePlanWave(plan.plan_id);
+    return;
+  }
+
+  st.status = status === 'completed' ? SUBTASK_STATUS.COMPLETED : SUBTASK_STATUS.FAILED;
+  await planStore.put(plan);
 
-    log(`PLAN PROGRESS ${plan.plan_id}: subtask ${st.subtask_id} → ${st.status}`);
+  log(`PLAN PROGRESS ${plan.plan_id}: subtask ${st.subtask_id} → ${st.status}`);
 
-    if (st.status === SUBTASK_STATUS.COMPLETED) {
-      publishPlanEvent('subtask_completed', plan);
-      await advancePlanWave(plan.plan_id);
+  if (st.status === SUBTASK_STATUS.COMPLETED) {
+    publishPlanEvent('subtask_completed', plan);
+    await advancePlanWave(plan.plan_id);
+    return;
+  }
+
+  // Subtask failed — apply failure policy
+  if (st.status === SUBTASK_STATUS.FAILED) {
+    publishPlanEvent('subtask_failed', plan);
+
+    // Cascade: block all transitive dependents
+    const blockedIds = cascadeFailure(plan, st.subtask_id);
+    await planStore.put(plan);
+
+    const policy = plan.failure_policy || 'continue_best_effort';
+
+    if (policy === 'abort_on_first_fail') {
+      await planStore.markAborted(plan.plan_id, `Subtask ${st.subtask_id} failed (abort_on_first_fail)`);
+      publishPlanEvent('aborted', await planStore.get(plan.plan_id));
+      log(`PLAN ABORTED ${plan.plan_id}: ${st.subtask_id} failed (abort_on_first_fail policy)`);
+      return;
     }
 
-    break;
+    if (policy === 'abort_on_critical_fail') {
+      // Check direct failure
+      if (st.critical) {
+        await planStore.markAborted(plan.plan_id, `Critical subtask ${st.subtask_id} failed (abort_on_critical_fail)`);
+        publishPlanEvent('aborted', await planStore.get(plan.plan_id));
+        log(`PLAN ABORTED ${plan.plan_id}: critical subtask ${st.subtask_id} failed`);
+        return;
+      }
+
+      // Check if cascade blocked any critical subtasks — a blocked critical is
+      // functionally equivalent to a failed critical (the plan can't achieve its goal)
+      const blockedCritical = plan.subtasks.filter(
+        s => blockedIds.has(s.subtask_id) && s.critical
+      );
+      if (blockedCritical.length > 0) {
+        const ids = blockedCritical.map(s => s.subtask_id).join(', ');
+        await planStore.markAborted(
+          plan.plan_id,
+          `Critical subtask(s) ${ids} blocked by failed dependency ${st.subtask_id} (abort_on_critical_fail)`
+        );
+        publishPlanEvent('aborted', await planStore.get(plan.plan_id));
+        log(`PLAN ABORTED ${plan.plan_id}: critical subtask(s) [${ids}] blocked by ${st.subtask_id}`);
+        return;
+      }
+    }
+
+    // continue_best_effort: try to advance independent branches
+    await advancePlanWave(plan.plan_id);
+  }
+}
+
+/**
+ * Cascade failure: BFS from failed subtask, mark all transitive dependents as BLOCKED.
+ * Mutates plan.subtasks in place.
+ * @returns {Set<string>} IDs of all newly-blocked subtasks
+ */
+function cascadeFailure(plan, failedSubtaskId) {
+  const blocked = new Set();
+  const queue = [failedSubtaskId];
+
+  while (queue.length > 0) {
+    const current = queue.shift();
+    for (const st of plan.subtasks) {
+      if (st.depends_on.includes(current) && !blocked.has(st.subtask_id)) {
+        if (st.status === SUBTASK_STATUS.PENDING || st.status === SUBTASK_STATUS.QUEUED) {
+          st.status = SUBTASK_STATUS.BLOCKED;
+          st.result = { success: false, summary: `Blocked by failed dependency: ${failedSubtaskId}` };
+          blocked.add(st.subtask_id);
+          queue.push(st.subtask_id);
+          log(`  CASCADE: ${st.subtask_id} blocked by ${failedSubtaskId}`);
+        }
+      }
+    }
   }
+
+  return blocked;
 }
 
 // ── Main ────────────────────────────────────────────
@@ -1265,6 +2045,8 @@ async function main() {
     'mesh.tasks.list':      handleList,
     'mesh.tasks.get':       handleGet,
     'mesh.tasks.cancel':    handleCancel,
+    'mesh.tasks.approve':   handleTaskApprove,
+    'mesh.tasks.reject':    handleTaskReject,
     // Collab handlers
     'mesh.collab.create':   handleCollabCreate,
     'mesh.collab.join':     handleCollabJoin,
@@ -1273,6 +2055,9 @@ async function main() {
     'mesh.collab.find':     handleCollabFind,
     'mesh.collab.reflect':  handleCollabReflect,
     'mesh.collab.recruiting': handleCollabRecruiting,
+    // Circling Strategy gate handlers
+    'mesh.collab.gate.approve': handleCirclingGateApprove,
+    'mesh.collab.gate.reject':  handleCirclingGateReject,
     // Plan handlers
     'mesh.plans.create':          handlePlanCreate,
     'mesh.plans.get':             handlePlanGet,
@@ -1300,12 +2085,16 @@ async function main() {
   }
 
   // Start enforcement loops
+  const proposalTimer = setInterval(processProposals, BUDGET_CHECK_INTERVAL);
   const budgetTimer = setInterval(enforceBudgets, BUDGET_CHECK_INTERVAL);
   const stallTimer = setInterval(detectStalls, BUDGET_CHECK_INTERVAL);
   const recruitTimer = setInterval(checkRecruitingDeadlines, 5000); // check every 5s
+  const circlingStepSweepTimer = setInterval(sweepCirclingStepTimeouts, 60000); // every 60s
+  log(`Proposal processing: every ${BUDGET_CHECK_INTERVAL / 1000}s`);
   log(`Budget enforcement: every ${BUDGET_CHECK_INTERVAL / 1000}s`);
   log(`Stall detection: every ${BUDGET_CHECK_INTERVAL / 1000}s (threshold: ${STALL_MINUTES}m)`);
   log(`Collab recruiting check: every 5s`);
+  log(`Circling step timeout sweep: every 60s (threshold: ${CIRCLING_STEP_TIMEOUT_MS / 60000}m)`);
 
 
   log('Task daemon ready.');
@@ -1313,6 +2102,7 @@ async function main() {
   // Shutdown handler
   const shutdown = async () => {
     log('Shutting down...');
+    clearInterval(proposalTimer);
     clearInterval(budgetTimer);
     clearInterval(stallTimer);
     clearInterval(recruitTimer);