@adhdev/daemon-core 0.9.76 → 0.9.77-rc.10

package/dist/mesh/mesh-events.d.ts

@@ -8,6 +8,17 @@ export interface PendingMeshCoordinatorEvent {
 }
 /** Drain and return all pending coordinator events, clearing the queue. */
 export declare function drainPendingMeshCoordinatorEvents(): PendingMeshCoordinatorEvent[];
+export declare function tryAssignQueueTask(components: {
+    cliManager: any;
+}, meshId: string, nodeId: string, sessionId: string, providerType: string): boolean;
+/**
+ * Triggers a queue check for all nodes in the mesh.
+ * Called when a new task is enqueued, in case nodes are already idle.
+ */
+export declare function triggerMeshQueue(components: {
+    instanceManager: any;
+    cliManager: any;
+}, meshId: string): void;
 export declare function handleMeshForwardEvent(components: DaemonComponents, payload: Record<string, unknown>): {
     success: boolean;
     forwarded: number;
@@ -15,6 +26,5 @@ export declare function handleMeshForwardEvent(components: DaemonComponents, pay
 } | {
     success: boolean;
     error: string;
-    forwarded?: undefined;
 };
 export declare function setupMeshEventForwarding(components: DaemonComponents): void;

package/dist/mesh/mesh-ledger.d.ts

@@ -0,0 +1,90 @@
+/**
+ * Mesh Task Ledger — GasTown-inspired append-only JSONL task history
+ *
+ * Records all mesh orchestration events (task dispatch, completion, failure,
+ * checkpoint, node lifecycle) as an append-only JSONL file per mesh.
+ *
+ * Inspired by GasTown's "Beads" pattern: every action is a versioned record
+ * that persists across agent sessions, enabling recovery, auditing, and
+ * continuity when individual sessions fail or context windows are exhausted.
+ *
+ * Storage: ~/.adhdev/mesh-ledger/<meshId>.jsonl
+ * Format:  One JSON object per line, newest entries appended at end
+ * Safety:  mode 0o600, atomic append via appendFileSync
+ */
+import { EventEmitter } from 'events';
+export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'session_launched' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_removed' | 'coordinator_started' | 'recovery_attempted';
+export interface MeshLedgerEntry {
+    id: string;
+    meshId: string;
+    timestamp: string;
+    kind: MeshLedgerKind;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    payload: Record<string, unknown>;
+}
+export interface MeshLedgerSummary {
+    meshId: string;
+    totalEntries: number;
+    taskDispatched: number;
+    taskCompleted: number;
+    taskFailed: number;
+    taskStalled: number;
+    sessionLaunched: number;
+    checkpointCreated: number;
+    lastActivityAt: string | null;
+    recentFailures: number;
+}
+export interface ReadLedgerOptions {
+    tail?: number;
+    since?: string;
+    kind?: MeshLedgerKind[];
+}
+export declare function getLedgerDir(): string;
+/**
+ * Append a new entry to the mesh ledger.
+ * Handles file creation, rotation on size overflow, and atomic writes.
+ */
+export declare const meshLedgerEvents: EventEmitter<[never]>;
+export declare function appendLedgerEntry(meshId: string, partial: Omit<MeshLedgerEntry, 'id' | 'meshId' | 'timestamp'>): MeshLedgerEntry;
+/**
+ * Append entries received from the cloud to the local ledger.
+ * This skips deduplicated entries and just writes new ones.
+ */
+export declare function appendRemoteLedgerEntries(meshId: string, entries: MeshLedgerEntry[]): void;
+/**
+ * Read ledger entries with optional filtering.
+ */
+export declare function readLedgerEntries(meshId: string, opts?: ReadLedgerOptions): MeshLedgerEntry[];
+/**
+ * Get a summary of mesh activity from the ledger.
+ */
+export declare function getLedgerSummary(meshId: string): MeshLedgerSummary;
+export interface SessionRecoveryContext {
+    /** The original task message that was dispatched to this session/node */
+    lastTaskMessage: string | null;
+    /** The node that was running the failed task */
+    failedNodeId: string | null;
+    /** Session ID of the failed session */
+    failedSessionId: string | null;
+    /** Provider used for the failed session */
+    failedProviderType: string | null;
+    /** Number of consecutive failures for this node (within recent window) */
+    consecutiveNodeFailures: number;
+    /** Number of times this specific task was attempted (matched by truncated message prefix) */
+    taskAttemptCount: number;
+    /** Whether a retry is recommended based on maxRetries policy */
+    retryRecommended: boolean;
+    /** Human-readable recovery advice for the coordinator */
+    advice: string;
+}
+/**
+ * Build recovery context for a failed session.
+ * Looks up the ledger to find the original task, count failures, and advise on retry.
+ */
+export declare function getSessionRecoveryContext(meshId: string, opts: {
+    sessionId?: string;
+    nodeId?: string;
+    maxRetries?: number;
+}): SessionRecoveryContext;

package/dist/mesh/mesh-sync.d.ts

@@ -26,6 +26,12 @@ export interface MeshSyncTransport {
     }>;
     /** DELETE /api/v1/repo-meshes/:id */
     deleteRemoteMesh(meshId: string): Promise<void>;
+    /** POST /api/v1/repo-meshes/:id/ledger/sync */
+    syncMeshLedger?(meshId: string, data: {
+        newEntries: any[];
+    }): Promise<{
+        missingEntries: any[];
+    }>;
 }
 export interface RemoteMeshRecord {
     id: string;
@@ -49,3 +55,7 @@ export interface MeshSyncResult {
  * Pull remote meshes that don't exist locally.
  */
 export declare function syncMeshes(transport: MeshSyncTransport): Promise<MeshSyncResult>;
+/**
+ * Sync the task ledger for a specific mesh.
+ */
+export declare function syncMeshLedger(meshId: string, transport: MeshSyncTransport): Promise<void>;

package/dist/mesh/mesh-work-queue.d.ts

@@ -0,0 +1,50 @@
+export type MeshTaskStatus = 'pending' | 'assigned' | 'completed' | 'failed';
+export interface MeshWorkQueueEntry {
+    id: string;
+    meshId: string;
+    message: string;
+    status: MeshTaskStatus;
+    /** If specified, only this node can claim the task (used by legacy mesh_send_task) */
+    targetNodeId?: string;
+    /** The node that actually claimed and is executing the task */
+    assignedNodeId?: string;
+    /** The session currently executing the task */
+    assignedSessionId?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Add a new task to the mesh queue.
+ */
+export declare function enqueueTask(meshId: string, message: string, opts?: {
+    targetNodeId?: string;
+}): MeshWorkQueueEntry;
+/**
+ * Get all tasks in the queue, optionally filtered by status.
+ */
+export declare function getQueue(meshId: string, opts?: {
+    status?: MeshTaskStatus[];
+}): MeshWorkQueueEntry[];
+/**
+ * Find the next pending task that this node is allowed to claim, and mark it as assigned.
+ */
+export declare function claimNextTask(meshId: string, nodeId: string, sessionId: string): MeshWorkQueueEntry | null;
+/**
+ * Update the status of a specific task.
+ * Used when a session completes, fails, or stalls.
+ */
+export declare function updateTaskStatus(meshId: string, taskId: string, status: MeshTaskStatus): MeshWorkQueueEntry | null;
+/**
+ * Update the status of the task currently assigned to a specific session.
+ */
+export declare function updateSessionTaskStatus(meshId: string, sessionId: string, status: MeshTaskStatus): MeshWorkQueueEntry | null;
+export interface MeshWorkQueueStats {
+    pending: number;
+    assigned: number;
+    completed: number;
+    failed: number;
+}
+/**
+ * Return aggregate queue statistics for the given mesh.
+ */
+export declare function getMeshQueueStats(meshId: string): MeshWorkQueueStats;

package/dist/repo-mesh-types.d.ts

@@ -62,6 +62,12 @@ export interface RepoMeshPolicy {
      * runtimes are never stopped/deleted unless the mesh owner opts in.
      */
     sessionCleanupOnNodeRemove?: RepoMeshSessionCleanupMode;
+    /**
+     * Maximum number of automatic retry recommendations for a failed task on the
+     * same node before the daemon advises the coordinator to escalate or reassign.
+     * Defaults to 1 (allow one retry). Set to 0 to disable auto-recovery advice.
+     */
+    maxTaskRetries?: number;
 }
 export interface RepoMeshRelatedRepo {
     /** Stable display label for an explicitly configured associated checkout. */

package/dist/shared-types.d.ts

@@ -292,6 +292,12 @@ export interface SessionEntry {
     seenCompletionMarker?: string;
     surfaceHidden?: boolean;
     settings?: Record<string, any>;
+    meshQueueStats?: {
+        pending: number;
+        assigned: number;
+        completed: number;
+        failed: number;
+    };
 }
 /**
  * Compact session metadata stored in UserSessionDO and reused by server-side
@@ -330,6 +336,12 @@ export interface CompactSessionEntry {
     providerControls?: ProviderControlSchema[];
     summaryMetadata?: ProviderSummaryMetadata;
     settings?: Record<string, any>;
+    meshQueueStats?: {
+        pending: number;
+        assigned: number;
+        completed: number;
+        failed: number;
+    };
 }
 export type VersionUpdateReason = 'force_update_below' | 'major_minor_mismatch' | 'patch_mismatch' | 'daemon_ahead';
 export type ReleaseChannel = 'stable' | 'preview';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.76",
+  "version": "0.9.77-rc.10",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/cli-adapters/provider-cli-adapter.ts

@@ -195,6 +195,8 @@ export class ProviderCliAdapter implements CliAdapter {
 
     // ─── CLI Scripts (script-based parsing) ───
     private cliScripts: CliScripts;
+    /** Per-session opaque state object created by cliScripts.createState(), reset on stop. */
+    private scriptState: unknown = null;
     private runtimeSettings: Record<string, any> = {};
     /** Full accumulated rendered PTY transcript for parser/readback use */
     private accumulatedBuffer: string = '';
@@ -477,6 +479,9 @@ export class ProviderCliAdapter implements CliAdapter {
         this.cliScripts = scripts;
         this.parsedStatusCache = null;
         this.parseErrorMessage = null;
+        // Initialize per-session state: createState() is called once here and on script reload.
+        // The returned object lives until the PTY exits (scriptState = null on exit).
+        this.scriptState = typeof scripts.createState === 'function' ? scripts.createState() : null;
         const scriptNames = listCliScriptNames(scripts);
         LOG.info('CLI', `[${this.cliType}] CLI scripts injected: [${scriptNames.join(', ')}]`);
     }
@@ -610,6 +615,7 @@ export class ProviderCliAdapter implements CliAdapter {
             this.ready = false;
             this.startupParseGate = false;
             this.spawnAt = 0;
+            this.scriptState = null;
             this.onStatusChange?.();
         });
 
@@ -1470,7 +1476,7 @@ export class ProviderCliAdapter implements CliAdapter {
                 scope: this.currentTurnScope,
                 runtimeSettings: this.runtimeSettings,
             });
-            const session = this.cliScripts.parseSession({ ...input, tail, tailScreen: buildCliScreenSnapshot(tail) });
+            const session = this.cliScripts.parseSession(this.scriptState, { ...input, tail, tailScreen: buildCliScreenSnapshot(tail) });
             this.parseErrorMessage = null;
             return session && typeof session === 'object' ? session : null;
         } catch (e: any) {
@@ -1485,7 +1491,7 @@ export class ProviderCliAdapter implements CliAdapter {
         if (!this.cliScripts?.detectStatus) return null;
         try {
             const screenText = this.terminalScreen.getText();
-            const status = this.cliScripts.detectStatus({
+            const status = this.cliScripts.detectStatus(this.scriptState, {
                 tail: text.slice(-500),
                 screenText,
                 rawBuffer: this.accumulatedRawBuffer,
@@ -1505,7 +1511,7 @@ export class ProviderCliAdapter implements CliAdapter {
         try {
             const screenText = this.terminalScreen.getText();
             const buffer = screenText || this.accumulatedBuffer;
-            return this.cliScripts.parseApproval({
+            return this.cliScripts.parseApproval(this.scriptState, {
                 buffer,
                 screenText,
                 rawBuffer: this.accumulatedRawBuffer,
@@ -1640,7 +1646,7 @@ export class ProviderCliAdapter implements CliAdapter {
             scope: this.currentTurnScope,
             runtimeSettings: this.runtimeSettings,
         });
-        return await Promise.resolve(fn({
+        return await Promise.resolve(fn(this.scriptState, {
             ...input,
             args: args && typeof args === 'object' ? { ...args } : {},
         }));

package/src/cli-adapters/provider-cli-shared.ts

@@ -48,11 +48,21 @@ export interface ParsedSession {
 }
 
 export interface CliScripts {
-    parseSession?: (input: CliScriptInput & { tail?: string; tailScreen?: CliScreenSnapshot }) => ParsedSession | null;
-    detectStatus?: (input: CliStatusInput) => string | null;
-    parseApproval?: (input: CliApprovalInput) => { message: string; buttons: string[] } | null;
+    /**
+     * Optional state factory. Called once per CLI session start (or script reload).
+     * The returned object is passed as the first argument to detectStatus, parseApproval,
+     * and parseSession on every invocation, allowing scripts to maintain per-session state
+     * (e.g. last-seen status, approval fingerprints, stability counters).
+     *
+     * Scripts that don't define createState() receive null as the state argument,
+     * making this change fully backward compatible.
+     */
+    createState?: () => unknown;
+    parseSession?: (state: unknown, input: CliScriptInput & { tail?: string; tailScreen?: CliScreenSnapshot }) => ParsedSession | null;
+    detectStatus?: (state: unknown, input: CliStatusInput) => string | null;
+    parseApproval?: (state: unknown, input: CliApprovalInput) => { message: string; buttons: string[] } | null;
     resolveAction?: (data: any) => string;
-    [name: string]: ((input: any) => any) | undefined;
+    [name: string]: ((state: unknown, input: any) => any) | ((data: any) => any) | (() => unknown) | undefined;
 }
 
 export interface CliScreenLine {

package/src/commands/router.ts

@@ -1315,6 +1315,22 @@ export class DaemonCommandRouter {
                 }
             }
 
+            case 'get_mesh_ledger': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                try {
+                    const { readLedgerEntries, getLedgerSummary } = await import('../mesh/mesh-ledger.js');
+                    const tail = typeof args?.tail === 'number' ? args.tail : 20;
+                    const since = typeof args?.since === 'string' ? args.since : undefined;
+                    const kind = Array.isArray(args?.kind) ? args.kind.filter((k: any) => typeof k === 'string') : undefined;
+                    const entries = readLedgerEntries(meshId, { tail, since, kind });
+                    const summary = getLedgerSummary(meshId);
+                    return { success: true, entries, summary };
+                } catch (e: any) {
+                    return { success: false, error: e.message };
+                }
+            }
+
             case 'add_mesh_node': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 const workspace = typeof args?.workspace === 'string' ? args.workspace.trim() : '';
@@ -1394,6 +1410,65 @@ export class DaemonCommandRouter {
                 }
             }
 
+            case 'refine_mesh_node': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
+                if (!meshId || !nodeId) return { success: false, error: 'meshId and nodeId required' };
+                try {
+                    const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh);
+                    const mesh = meshRecord?.mesh;
+                    const node = mesh?.nodes?.find((n: any) => n.id === nodeId || n.nodeId === nodeId);
+                    if (!node) return { success: false, error: `Node '${nodeId}' not found in mesh` };
+
+                    if (!node.isLocalWorktree || !node.workspace) {
+                        return { success: false, error: `Refinery requires a local worktree node` };
+                    }
+
+                    const sourceNode = node.clonedFromNodeId
+                        ? mesh?.nodes.find((n: any) => n.id === node.clonedFromNodeId || n.nodeId === node.clonedFromNodeId)
+                        : mesh?.nodes.find((n: any) => !n.isLocalWorktree);
+                    const repoRoot = sourceNode?.repoRoot || sourceNode?.workspace;
+                    if (!repoRoot) return { success: false, error: 'Source node repoRoot not found' };
+
+                    const { execFile } = await import('node:child_process');
+                    const { promisify } = await import('node:util');
+                    const execFileAsync = promisify(execFile);
+
+                    const { stdout: branchStdout } = await execFileAsync('git', ['branch', '--show-current'], { cwd: node.workspace, encoding: 'utf8' });
+                    const branch = branchStdout.trim();
+                    if (!branch) return { success: false, error: 'Could not determine branch of the worktree node' };
+
+                    const { stdout: baseBranchStdout } = await execFileAsync('git', ['branch', '--show-current'], { cwd: repoRoot, encoding: 'utf8' });
+                    const baseBranch = baseBranchStdout.trim();
+
+                    try {
+                        await execFileAsync('git', ['merge', '--no-ff', branch, '-m', `Auto-merge branch '${branch}' via Refinery`], { cwd: repoRoot, encoding: 'utf8' });
+                    } catch (e: any) {
+                        return { success: false, error: `Merge failed (conflicts?): ${e.message}` };
+                    }
+
+                    const removeResult = await this.execute('remove_mesh_node', {
+                        meshId,
+                        nodeId,
+                        sessionCleanupMode: 'kill',
+                        inlineMesh: args?.inlineMesh,
+                    });
+
+                    try {
+                        const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+                        appendLedgerEntry(meshId, {
+                            kind: 'node_removed',
+                            nodeId,
+                            payload: { refined: true, mergedBranch: branch, into: baseBranch },
+                        });
+                    } catch {}
+
+                    return { success: true, merged: true, branch, into: baseBranch, removeResult };
+                } catch (e: any) {
+                    return { success: false, error: e.message };
+                }
+            }
+
             case 'remove_mesh_node': {
                 const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
                 const nodeId = typeof args?.nodeId === 'string' ? args.nodeId.trim() : '';
@@ -1436,6 +1511,19 @@ export class DaemonCommandRouter {
                         const { removeNode } = await import('../config/mesh-config.js');
                         removed = removeNode(meshId, nodeId);
                     }
+
+                    // Record in task ledger
+                    if (removed) {
+                        try {
+                            const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+                            appendLedgerEntry(meshId, {
+                                kind: 'node_removed',
+                                nodeId,
+                                payload: { worktree: !!node?.isLocalWorktree, sessionCleanupMode },
+                            });
+                        } catch { /* ledger append is best-effort */ }
+                    }
+
                     return { success: true, removed, ...(sessionCleanup ? { sessionCleanup } : {}) };
                 } catch (e: any) {
                     return { success: false, error: e.message };
@@ -1498,6 +1586,16 @@ export class DaemonCommandRouter {
                         if (!node) return { success: false, error: 'Failed to register worktree node' };
                     }
 
+                    // Record in task ledger
+                    try {
+                        const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+                        appendLedgerEntry(meshId, {
+                            kind: 'node_cloned',
+                            nodeId: node.id,
+                            payload: { sourceNodeId, branch: result.branch, worktreePath: result.worktreePath },
+                        });
+                    } catch { /* ledger append is best-effort */ }
+
                     return {
                         success: true,
                         node,
@@ -1508,6 +1606,19 @@ export class DaemonCommandRouter {
                     return { success: false, error: e.message };
                 }
             }
+            case 'trigger_mesh_queue': {
+                const meshId = typeof args?.meshId === 'string' ? args.meshId.trim() : '';
+                if (!meshId) return { success: false, error: 'meshId required' };
+                try {
+                    const { triggerMeshQueue } = await import('../mesh/mesh-events.js');
+                    if (meshId) {
+                        triggerMeshQueue(this.deps as any, meshId);
+                    }
+                    return { success: true };
+                } catch (e: any) {
+                    return { success: false, error: e.message };
+                }
+            }
 
             // ─── Mesh Coordinator Launch ───
             case 'launch_mesh_coordinator': {
@@ -1756,6 +1867,18 @@ export class DaemonCommandRouter {
                     }
 
                     LOG.info('MeshCoordinator', `Launched ${cliType} coordinator for mesh ${meshId} in ${workspace}`);
+
+                    // Record coordinator launch in task ledger
+                    try {
+                        const { appendLedgerEntry } = await import('../mesh/mesh-ledger.js');
+                        appendLedgerEntry(meshId, {
+                            kind: 'coordinator_started',
+                            sessionId: launchResult.sessionId || launchResult.id,
+                            providerType: cliType,
+                            payload: { workspace },
+                        });
+                    } catch { /* ledger append is best-effort */ }
+
                     return {
                         success: true,
                         meshId,

package/src/index.ts

@@ -149,6 +149,17 @@ export type { CoordinatorPromptContext } from './mesh/coordinator-prompt.js';
 export { syncMeshes } from './mesh/mesh-sync.js';
 export type { MeshSyncTransport, MeshSyncResult, RemoteMeshRecord } from './mesh/mesh-sync.js';
 
+// ── Mesh Task Ledger ──
+export { appendLedgerEntry, readLedgerEntries, getLedgerSummary, getLedgerDir, getSessionRecoveryContext } from './mesh/mesh-ledger.js';
+export type { MeshLedgerEntry, MeshLedgerKind, MeshLedgerSummary, ReadLedgerOptions, SessionRecoveryContext } from './mesh/mesh-ledger.js';
+
+// ── Mesh Work Queue (GUPP) ──
+export { enqueueTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus } from './mesh/mesh-work-queue.js';
+export type { MeshWorkQueueEntry, MeshTaskStatus } from './mesh/mesh-work-queue.js';
+
+// ── Mesh Events ──
+export { triggerMeshQueue } from './mesh/mesh-events.js';
+
 // ── State Store ──
 export { loadState, saveState, resetState } from './config/state-store.js';
 export type { DaemonState } from './config/state-store.js';

package/src/mesh/coordinator-prompt.ts

@@ -133,6 +133,7 @@ const TOOLS_SECTION = `## Available Tools
 | \`mesh_launch_session\` | Start a new agent session on a node |
 | \`mesh_send_task\` | Send a task (natural language) to a running agent |
 | \`mesh_read_chat\` | Read an agent's recent messages to check progress |
+| \`mesh_task_history\` | Read the task ledger — dispatches, completions, failures. Use to understand what has been done before deciding next steps |
 | \`mesh_git_status\` | Check git status on a specific node |
 | \`mesh_checkpoint\` | Create a git checkpoint on a node |
 | \`mesh_approve\` | Approve/reject a pending agent action |
@@ -145,18 +146,31 @@ Before doing any coordinator work, confirm that the actual callable tool list in
 
 const WORKFLOW_SECTION = `## Orchestration Workflow
 
-1. **Assess** — Call \`mesh_status\` to see which nodes are healthy and available.
-2. **Plan** — Decompose the user's request into independent tasks for parallel execution, or sequential tasks when dependencies exist.
-3. **Delegate** — For each task:
-   a. Pick the best node (consider: health, dirty state, current workload).
-   b. If you need branch isolation for parallel work, call \`mesh_clone_node\` to create a worktree node first.
-   c. If no session exists, call \`mesh_launch_session\` to start one.
-   d. Call \`mesh_send_task\` with a **complete, self-contained** instruction that includes all context the agent needs (file paths, line numbers, what to change, why). Do not send partial instructions expecting future follow-up.
-4. **Monitor** — Prefer event-driven completion/status notifications. Do **not** poll \`mesh_read_chat\` repeatedly just because the delegated session has not produced a final assistant message yet; tool/terminal activity means work may still be in progress. Do not call \`mesh_read_chat\` again within a few seconds for the same generating session; wait for the completion callback/status event instead unless you are debugging a real stall. Use at most one compact \`mesh_read_chat\` check after a completion/approval signal, an explicit user status request, or a real timeout/stall. Handle approvals via \`mesh_approve\`.
+1. **Assess** — Call \`mesh_status\` to see which nodes are healthy and available. Check \`mesh_task_history\` to understand what has already been done in this mesh — previous delegations, completions, and failures.
+2. **Plan** — Decompose the user's request into independent tasks for parallel execution, or sequential tasks when dependencies exist. If \`mesh_task_history\` shows a recent failure for a task, decide whether to retry or reassign.
+3. **Queue / Delegate** — The Mesh uses an autonomous pull-based Work Queue:
+   a. **General Tasks**: Enqueue tasks using \`mesh_enqueue_task\`. Idle node agents will automatically pull tasks from the queue and begin working.
+   b. **Node Preparation**: Call \`mesh_launch_session\` to ensure enough agent sessions are active to handle the queue. If you need branch isolation for parallel work, call \`mesh_clone_node\` to create a worktree node first.
+   c. **Targeted Tasks**: Use \`mesh_send_task\` only when you need to bypass the queue and force a specific node to execute a task immediately.
+   d. Always provide a **complete, self-contained** instruction that includes all context the agent needs (file paths, line numbers, what to change, why). Do not send partial instructions expecting future follow-up.
+4. **Monitor** — Prefer event-driven completion/status notifications. Do **not** poll \`mesh_read_chat\` repeatedly. Use \`mesh_view_queue\` to see the status of all pending, assigned, completed, and failed tasks. Do not call \`mesh_read_chat\` again within a few seconds for the same generating session. Use at most one compact \`mesh_read_chat\` check after a completion/approval signal. Handle approvals via \`mesh_approve\`.
 5. **Verify** — When a task reports completion or git work is visible, call \`mesh_git_status\` to verify changes were made.
 6. **Checkpoint** — Call \`mesh_checkpoint\` to save the work.
 7. **Clean up** — Remove worktree nodes via \`mesh_remove_node\` after their work is merged or no longer needed.
-8. **Report** — Summarize what was done, what changed, and any issues.`;
+8. **Report** — Summarize what was done, what changed, and any issues.
+
+## Failure Recovery
+
+When a node agent stops unexpectedly, the daemon automatically enriches the system message with **Recovery Context** that includes:
+- The number of consecutive failures on that node
+- The original task message (if recorded in the ledger)
+- A recommendation: **retry**, **reassign**, or **escalate**
+
+Follow these recovery rules:
+1. **If "Retry recommended"**: Re-launch the session on the same node (\`mesh_launch_session\`), then resend the original task (\`mesh_send_task\`). The system message includes the original task text.
+2. **If "Max retries exceeded"**: Do NOT retry on the same node. Either reassign the task to a different node, or inform the user that the task requires manual intervention.
+3. **If no recovery context**: The stop may be intentional (normal completion). Use \`mesh_read_chat\` once to verify, then move on.
+4. **Always record what happened**: After handling a failure, briefly note the outcome in your report to the user.`;
 
 function buildRulesSection(coordinatorCliType?: string): string {
     const coordinatorNote = coordinatorCliType
@@ -166,12 +180,13 @@ function buildRulesSection(coordinatorCliType?: string): string {
     return `## Rules
 
 - **Minimize coordinator context.** The coordinator's job is routing, not implementing. Do not read source files, run commands, or analyze code directly — delegate all of that to node agents. Your context should stay lean.
-- **Delegate analysis too.** If you need to understand a bug or explore the codebase, send that investigation as a task to a node. Do not do it yourself.
+- **Delegate analysis too.** If you need to understand a bug or explore the codebase, send that investigation as a task to the queue or a node. Do not do it yourself.
 - **Respect explicit provider requests.** If the user names an agent/provider, pass the matching provider type to \`mesh_launch_session\`: Hermes → \`hermes-cli\`, Claude Code/Claude → \`claude-cli\`, Codex → \`codex-cli\`, Gemini → \`gemini-cli\`. Never substitute \`claude-cli\` just because the coordinator itself is Claude Code.
-- **Front-load the task message.** When calling \`mesh_send_task\`, include everything the agent needs: what files to touch, what the problem is, what the fix should look like. The agent won't ask follow-up questions.
+- **Front-load the task message.** When calling \`mesh_enqueue_task\` or \`mesh_send_task\`, include everything the agent needs: what files to touch, what the problem is, what the fix should look like. The agent won't ask follow-up questions.
 - **Don't inspect code.** Treat delegated agent summaries as self-reports, not verification. Verify side effects via \`mesh_git_status\` (including related repo freshness when configured), not by reading source files.
 - **Don't over-parallelize.** Start with 1-2 concurrent tasks. Scale up if they succeed. Never launch a duplicate session or second worker solely because \`mesh_read_chat\` has no final assistant message while the delegated session is still showing tool/terminal activity.
-- **Handle failures gracefully.** If a task fails, read the chat to understand why, then retry or reassign.
+- **Handle failures with context.** If a task fails, check \`mesh_task_history\` first to see if this task was attempted before and how it failed. Read the chat to understand why, then decide: retry on the same node, reassign to a different node, or escalate to the user.
+- **Check history before starting.** At the beginning of a coordination session, call \`mesh_task_history\` to understand what was previously delegated and its outcomes. This prevents duplicate work and informs recovery decisions.
 - **Keep the user informed.** Report progress after each delegation round — one or two sentences, not a narration.
 - **Respect node capabilities.** Don't send build tasks to read-only nodes. Don't push from nodes that aren't allowed to.
 - **Never fabricate tool results.** Always call the actual tool; never pretend you did.