@adhdev/daemon-core 0.9.82-rc.406 → 0.9.82-rc.408

package/src/mesh/mesh-reconcile-loop.ts

@@ -97,33 +97,86 @@ function resolveReconcileIntervalMs(): number {
     return DEFAULT_RECONCILE_INTERVAL_MS;
 }
 
-// RECONCILE-SYNTH-PREEMPTS-COMPLETION in-flight debounce. PHASE 4 only synthesizes a missing
-// completion when the worker session reads `idle`. But a worker that is GENUINELY generating
-// (it emitted agent:generating_started — the dispatch row is 'acked' — and has not yet
-// completed) can momentarily read `idle` mid-turn: a CLI PTY parser sees an inter-turn blip
-// between tool calls, or the read_chat probe races a brief settle. A single such idle read
-// must NOT fabricate a completion for an in-flight task — doing so writes a synthesized
-// terminal that then masks the REAL completion when it lands seconds later
+// R4f (GENERATING-BOUNDARY, acked-hold redesign). PHASE 4 only synthesizes a missing completion
+// when the worker session reads `idle`. But a worker that is GENUINELY generating (it emitted
+// agent:generating_started — the dispatch row is 'acked' — and has not yet completed) can
+// momentarily read `idle` mid-turn (a CLI PTY inter-tool-call settle, or the final assistant text
+// already rendered while the turn's generating_completed lifecycle close still lags). A premature
+// synth writes a terminal that then masks the worker's REAL completion when it lands seconds later
 // (drop:duplicate_completion_terminal_ledger; the observed 71s task a250fb44 lost its [System]
-// notification this way). We require the session to read `idle` on CONSECUTIVE reconcile ticks
-// before synthesizing for an `acked` (started-generating) dispatch — a transient mid-turn idle
-// flicker clears on the next ~4s tick, whereas a genuinely-settled (completed-but-lost) or dead
-// session reads idle every tick. A dispatch that was never acked (worker never started) is NOT
-// debounced here: there is no in-flight generation to protect, and the downstream grace gate +
-// stale-summary guard remain the backstops for that lost-dispatch case.
+// notification this way; the R4e 53s task synth fired 16s BEFORE the worker's real emit).
 //
-// Keyed by `${meshId}::${taskId}`. The map is pruned each PHASE-4 pass to the set of currently
-// active dispatches, so a completed/pruned task's counter is dropped (no unbounded growth).
-const REQUIRED_CONSECUTIVE_IDLE_TICKS_FOR_INFLIGHT_SYNTH = 2;
-const inFlightIdleObservationCounts = new Map<string, number>();
+// R4 → R4e used FINITE timers (consecutive ticks / MIN_IDLE_SETTLE / ACKED_TURN_SETTLE) to delay the
+// synth. That class of fix is fundamentally a RACE: the worker's real emit latency is variable and
+// unbounded (win32 idle reads can flip before the emit arrives), so ANY finite timer eventually
+// loses to a slow-enough turn — and the synth pre-empts the real completion. R4e live-FAILED for
+// exactly this reason.
+//
+// R4f redesign (direction B). An `acked` task means the worker ECHOED generating_started (the
+// taskId flip) — it is alive and mid-turn, so it WILL eventually emit a real terminal. We therefore
+// HOLD the synth INDEFINITELY for an acked task. This is safe against the emit actually arriving:
+// when the worker's real generating_completed lands, it writes a terminal ledger, and
+// reconcileDirectDispatchCompletionFromTranscript's hasTerminalLedgerAfterDispatch check makes any
+// later synth an idempotent no-op (alreadyTerminal). So the hold never costs a missed notification —
+// the real emit always wins, no matter how late.
+//
+// The indefinite hold is released ONLY by a genuine-DEATH / emit-loss BACKSTOP — never a finite
+// timer that races normal lag:
+//   (a) liveness failure — read_chat reports the session is gone, OR N consecutive read failures
+//       accumulate (a transport/session-gone signal, counted as death rather than swallowed via
+//       `continue`). A worker that died mid-turn will never emit, so the synth must eventually fire.
+//   (b) an absolute LONG death-deadline — time since the generating_started ack exceeds
+//       ACKED_DEATH_DEADLINE_MS, a backstop set FAR above any observed emit latency (default 8 min)
+//       so it does not race a normal slow turn; it only catches a worker that is genuinely wedged or
+//       whose emit was permanently lost. This is a notification-loss net, not a completion timer.
+//
+// A dispatch that was never acked (worker never started) is NOT held here: there is no in-flight
+// generation to protect, so it keeps the existing first-idle-tick synth behavior (its lost-dispatch
+// case is covered by the downstream grace + stale-summary guards). The map is pruned each PHASE-4
+// pass to the set of currently active dispatches, so a completed/pruned task's state is dropped (no
+// unbounded growth). Keyed by `${meshId}::${taskId}`.
+
+// R4f backstop (a): how many CONSECUTIVE read_chat failures (transport error / success:false /
+// no payload) for an acked task are treated as a death signal that releases the indefinite hold.
+// A single failed read is a transient probe blip; a session that genuinely died reads-fail every
+// tick, so a small streak distinguishes the two without racing a live-but-slow worker.
+const ACKED_DEATH_CONSECUTIVE_READ_FAILURES = 3;
+
+// R4f backstop (b): the absolute death-deadline. An acked task is held indefinitely until this much
+// time has elapsed since its generating_started ack (dispatch.updatedAt); past it, a persistently
+// idle session is synthesized as a notification-loss net. This is set FAR above any observed emit
+// latency (R4e's worst case was ~16s) so it does NOT race a normal slow turn — it only catches a
+// genuinely wedged worker or a permanently-lost emit. Read at call time so tests can tune it.
+function resolveTunedReconcileMs(envName: string, def: number, min: number, max: number): number {
+    const raw = readNonEmptyString(process.env[envName]);
+    if (raw) {
+        const parsed = Number.parseInt(raw, 10);
+        if (Number.isFinite(parsed) && parsed >= min && parsed <= max) return parsed;
+    }
+    return def;
+}
+function resolveAckedDeathDeadlineMs(): number {
+    // Default 8 min — FAR above the variable emit latency the finite R4..R4e timers raced (R4e's
+    // worst case was ~16s); by the time this fires a live worker would long since have emitted its
+    // real terminal. The env-override floor is 0 so tests can force the deadline (production never
+    // sets it that low); the ceiling is 60min so a mis-set env cannot disable the loss-net forever.
+    return resolveTunedReconcileMs('MESH_INFLIGHT_ACKED_DEATH_DEADLINE_MS', 8 * 60_000, 0, 60 * 60_000);
+}
+
+// Per-task in-flight hold state for an acked dispatch:
+//   - liveConfirmedSinceAck: we have seen at least one conclusive read (idle OR generating) since
+//     the ack — proves the session is reachable, so a later read FAILURE is a genuine liveness loss
+//     rather than a node that was never reachable.
+//   - consecutiveReadFailures: streak of inconclusive read_chat results (death backstop (a)).
+const inFlightAckedHoldState = new Map<string, { liveConfirmedSinceAck: boolean; consecutiveReadFailures: number }>();
 
 function inFlightSynthKey(meshId: string, taskId: string): string {
     return `${meshId}::${taskId}`;
 }
 
-// Test hook: clear the in-flight idle debounce state between cases.
+// Test hook: clear the in-flight acked-hold state between cases.
 export function __resetReconcileInFlightSynthDebounceForTests(): void {
-    inFlightIdleObservationCounts.clear();
+    inFlightAckedHoldState.clear();
 }
 
 interface LiveCoordinator {
@@ -1231,6 +1284,50 @@ function readChatPayloadStatus(payload: Record<string, unknown> | null): string
     return readNonEmptyString(payload?.status).toLowerCase();
 }
 
+// R4e fix (3): peek the pending-events queue for a REAL (worker-emitted) terminal completion
+// already queued for a task — used to yield the in-flight synth to the worker's own emit. Broad
+// peek (no daemon-id scoping) matched precisely by taskId, so a worker stamp in any daemon-id form
+// is still recognized. Best-effort: a peek failure returns false (proceed to synth — never block
+// delivery). A prior SYNTH's still-queued pending event also names this taskId, but a synth always
+// writes its terminal ledger atomically, so hasTerminalLedgerAfterDispatch downstream already
+// no-ops that case — this guard is specifically for an as-yet-unledgered worker emit in flight.
+function realTerminalEmitPendingForTask(meshId: string, taskId: string): boolean {
+    let pending: readonly PendingMeshCoordinatorEvent[];
+    try {
+        pending = getPendingMeshCoordinatorEvents(meshId);
+    } catch {
+        return false;
+    }
+    return pending.some(e =>
+        readNonEmptyString(e.metadataEvent?.taskId) === taskId
+        && (e.event === 'agent:generating_completed' || e.event === 'agent:stopped'));
+}
+
+// R4e fix (2): one fresh read_chat status read for the worker session, via the same local/remote
+// transport PHASE 4 uses. Returns the lowercased status, or null when the read is inconclusive
+// (transport error, success:false, no payload) — callers treat null as "no new evidence, proceed".
+async function reprobeWorkerStatus(
+    components: DaemonComponents,
+    args: { isLocalNode: boolean; nodeDaemonId: string; readArgs: Record<string, unknown> },
+): Promise<string | null> {
+    try {
+        if (args.isLocalNode) {
+            const r = await components.commandHandler.handle('read_chat', args.readArgs);
+            if (r && (r as { success?: boolean }).success === false) return null;
+            return readChatPayloadStatus(unwrapReadChatPayload(r));
+        }
+        if (components.dispatchMeshCommand) {
+            const r = await components.dispatchMeshCommand(args.nodeDaemonId, 'read_chat', args.readArgs);
+            const p = unwrapReadChatPayload(r);
+            if (p && (p as { success?: boolean }).success === false) return null;
+            return readChatPayloadStatus(p);
+        }
+    } catch {
+        return null;
+    }
+    return null;
+}
+
 // PHASE 4 helper. For every active (non-terminal) direct dispatch this daemon
 // hosts, confirm the worker session is idle via a read_chat and — if a final
 // assistant summary is present but no terminal ledger exists for that dispatch —
@@ -1251,17 +1348,17 @@ async function reconcileUnterminatedDirectDispatches(
     const dispatches = getActiveDirectDispatches(mesh.id);
     if (dispatches.length === 0) return; // cheap exit — nothing dispatched, nothing to reconcile
 
-    // Prune the in-flight idle debounce map to the tasks still active in THIS mesh, so a
-    // completed/pruned task's counter is dropped (the map never grows without bound).
+    // Prune the in-flight acked-hold map to the tasks still active in THIS mesh, so a
+    // completed/pruned task's state is dropped (the map never grows without bound).
     const activeTaskKeys = new Set(
         dispatches
             .map(d => readNonEmptyString(d.taskId))
             .filter(Boolean)
             .map(taskId => inFlightSynthKey(mesh.id, taskId)),
     );
-    for (const key of inFlightIdleObservationCounts.keys()) {
+    for (const key of inFlightAckedHoldState.keys()) {
         if (key.startsWith(`${mesh.id}::`) && !activeTaskKeys.has(key)) {
-            inFlightIdleObservationCounts.delete(key);
+            inFlightAckedHoldState.delete(key);
         }
     }
 
@@ -1292,51 +1389,111 @@ async function reconcileUnterminatedDirectDispatches(
             ...(providerType ? { agentType: providerType, providerType } : {}),
         };
 
+        const synthKey = inFlightSynthKey(mesh.id, taskId);
+        const isAcked = dispatch.status === 'acked';
+
+        // R4f: read the worker session. A FAILED read (transport error / success:false / no payload)
+        // is no longer silently swallowed for an acked task — it is the liveness side of the
+        // death backstop (a). We classify the read result and route an acked failure into the
+        // failure counter; a never-acked (or non-acked) failure keeps the old best-effort `continue`.
         let payload: Record<string, unknown> | null = null;
+        let readFailed = false;
         try {
             if (isLocalNode) {
                 const result = await components.commandHandler.handle('read_chat', readArgs);
-                if (result && (result as { success?: boolean }).success === false) continue;
-                payload = unwrapReadChatPayload(result);
+                if (result && (result as { success?: boolean }).success === false) {
+                    readFailed = true;
+                } else {
+                    payload = unwrapReadChatPayload(result);
+                }
             } else if (dispatchMeshCommand) {
                 const result = await dispatchMeshCommand(nodeDaemonId, 'read_chat', readArgs);
                 payload = unwrapReadChatPayload(result);
-                if (payload && (payload as { success?: boolean }).success === false) continue;
+                if (payload && (payload as { success?: boolean }).success === false) { payload = null; readFailed = true; }
             } else {
-                continue; // remote node but no P2P transport — can't read; retry next tick
+                continue; // remote node but no P2P transport — can't read; retry next tick (not a death signal)
             }
         } catch {
-            continue; // best-effort; session may be gone or node offline — retry next tick
+            readFailed = true; // session may be gone or node offline
         }
-        if (!payload) continue;
+        if (!payload && !readFailed) continue; // null payload that wasn't a hard failure — retry next tick
+
+        if (readFailed || !payload) {
+            // R4f backstop (a) — liveness failure. For a never-acked dispatch there is no in-flight
+            // turn to protect, so a read failure is a transient probe blip → retry next tick (old
+            // behavior). For an ACKED dispatch that we had previously confirmed live, a streak of
+            // consecutive read failures means the worker session genuinely went away mid-turn and
+            // will never emit its real completion — count it. The actual terminal cleanup of a
+            // gone session is owned by PHASE 2.5 (stranded reclaim) / PHASE 5 (orphan prune); here
+            // we only record the death observation and STOP holding so those nets can take over,
+            // rather than pinning the row on an indefinite hold for a session that is already gone.
+            if (isAcked) {
+                const prior = inFlightAckedHoldState.get(synthKey);
+                const failures = (prior?.consecutiveReadFailures ?? 0) + 1;
+                const liveConfirmedSinceAck = prior?.liveConfirmedSinceAck ?? false;
+                inFlightAckedHoldState.set(synthKey, { liveConfirmedSinceAck, consecutiveReadFailures: failures });
+                if (liveConfirmedSinceAck && failures >= ACKED_DEATH_CONSECUTIVE_READ_FAILURES) {
+                    LOG.warn('MeshReconcile', `Acked-hold death signal: task ${taskId} on node ${nodeId} (mesh ${mesh.id}) read_chat failed ${failures}x consecutively after a live-confirmed ack — worker session presumed gone mid-turn; releasing the indefinite synth hold to the stranded-reclaim / orphan-prune nets`);
+                }
+            }
+            continue; // no readable transcript this tick → cannot synth here; retry / let backstops act
+        }
+
+        // Read succeeded (a conclusive idle/generating status) → the session is reachable: reset the
+        // failure streak and mark it live-confirmed-since-ack, so a LATER read failure is recognized
+        // as a genuine liveness loss (backstop a) rather than a node that was never reachable.
+        inFlightAckedHoldState.set(synthKey, { liveConfirmedSinceAck: true, consecutiveReadFailures: 0 });
 
         // Only act on a session that has actually settled to idle. A generating /
         // waiting_approval session is mid-turn — synthesizing a completion now would
         // be wrong. (idle is the only status the MCP poll path reconciles too.)
-        const synthKey = inFlightSynthKey(mesh.id, taskId);
+        const nowMs = Date.now();
         if (readChatPayloadStatus(payload) !== 'idle') {
-            // Not idle → the worker is mid-turn. Reset any partial idle streak so a single
-            // idle blip during a long generation never accumulates toward the synth threshold.
-            inFlightIdleObservationCounts.delete(synthKey);
+            // Not idle → the worker is genuinely mid-turn (a clear live signal). Keep the
+            // live-confirmed flag set (above) but otherwise just wait for the real emit.
             continue;
         }
 
-        // RECONCILE-SYNTH-PREEMPTS-COMPLETION: a dispatch whose worker was OBSERVED to start
-        // generating (the agent:generating_started ack flipped the row to 'acked') and has no
-        // terminal yet is potentially still in-flight — its `idle` read here may be a transient
-        // mid-turn flicker, not a settled completion. Require CONSECUTIVE idle observations
-        // before synthesizing for such a task: a flicker clears next tick (counter reset above),
-        // while a genuinely-settled (completed-but-lost) or dead session reads idle every tick
-        // and crosses the threshold within ~one extra interval. A never-acked dispatch (worker
-        // never started) is exempt — there is no in-flight generation to pre-empt, and its
-        // lost-dispatch case is still covered by the downstream grace + stale-summary guards.
-        if (dispatch.status === 'acked') {
-            const idleStreak = (inFlightIdleObservationCounts.get(synthKey) ?? 0) + 1;
-            inFlightIdleObservationCounts.set(synthKey, idleStreak);
-            if (idleStreak < REQUIRED_CONSECUTIVE_IDLE_TICKS_FOR_INFLIGHT_SYNTH) {
-                LOG.info('MeshReconcile', `In-flight synth hold: task ${taskId} on node ${nodeId} (mesh ${mesh.id}) read idle ${idleStreak}/${REQUIRED_CONSECUTIVE_IDLE_TICKS_FOR_INFLIGHT_SYNTH} consecutive tick(s) after generating_started — deferring completion synth until the idle settle is confirmed (guards against a mid-turn idle flicker pre-empting the real completion)`);
+        // R4f GENERATING-BOUNDARY (acked-hold): a dispatch whose worker was OBSERVED to start
+        // generating (the agent:generating_started ack flipped the row to 'acked') is ALIVE and
+        // mid-turn — it WILL eventually emit a real terminal. An `idle` read here is therefore
+        // presumed a TRANSIENT mid-turn window (a PTY inter-tool-call settle, or final text already
+        // rendered while the lifecycle close lags), NOT a settled completion. We HOLD the synth
+        // INDEFINITELY rather than racing the worker's (variable, unbounded) emit latency with a
+        // finite timer — the failure mode of R4..R4e. This is safe: when the worker's real emit
+        // lands it writes a terminal ledger, and reconcileDirectDispatchCompletionFromTranscript's
+        // hasTerminalLedgerAfterDispatch makes any later synth an idempotent no-op, so the real emit
+        // always wins no matter how late. The hold is released ONLY by the death backstops:
+        //   (a) consecutive read failures after a live-confirmed ack (handled above), or
+        //   (b) the absolute ACKED_DEATH_DEADLINE_MS since the ack — a notification-loss net set FAR
+        //       above any observed emit latency, so it catches a genuinely-wedged worker / lost emit
+        //       without racing a normal slow turn.
+        // A never-acked dispatch (worker never started) is exempt — no in-flight generation to
+        // pre-empt; it keeps the first-idle-tick synth, with the downstream grace + stale-summary
+        // guards as its backstops.
+        if (isAcked) {
+            const ackedAtMs = Date.parse(readNonEmptyString(dispatch.updatedAt));
+            const sinceAckMs = Number.isFinite(ackedAtMs) ? nowMs - ackedAtMs : Number.POSITIVE_INFINITY;
+            const deathDeadlineMs = resolveAckedDeathDeadlineMs();
+            if (sinceAckMs < deathDeadlineMs) {
+                LOG.info('MeshReconcile', `Acked-hold: task ${taskId} on node ${nodeId} (mesh ${mesh.id}) read idle ${Number.isFinite(sinceAckMs) ? Math.round(sinceAckMs / 1000) + 's' : '∞'} since the generating_started ack — HOLDING synth indefinitely (worker is alive and will emit; a later real emit is idempotent). Death backstop fires at ${Math.round(deathDeadlineMs / 1000)}s or on consecutive read failures.`);
                 continue;
             }
+            LOG.warn('MeshReconcile', `Acked-hold death deadline reached: task ${taskId} on node ${nodeId} (mesh ${mesh.id}) still idle ${Math.round(sinceAckMs / 1000)}s after the ack (deadline ${Math.round(deathDeadlineMs / 1000)}s) — synthesizing the missing completion as a notification-loss net (a real emit, if it ever lands, no-ops idempotently).`);
+        }
+
+        // R4f (auxiliary, was R4e fix 3) — worker-emit priority. Secondary check: if the worker's
+        // REAL terminal emit for this task has already arrived in the pending-events queue (queued
+        // for delivery to the coordinator) but not yet written a terminal ledger, YIELD — let the
+        // genuine emit surface rather than racing it with a synth that would win the taskId-anchored
+        // fingerprint dedup and mask it. Under the R4f acked-hold this is now an auxiliary belt-and-
+        // suspenders check (the indefinite hold already defers an acked synth); it still guards the
+        // never-acked path and the post-death-deadline acked synth from racing an emit caught in
+        // flight at synth-commit time.
+        if (realTerminalEmitPendingForTask(mesh.id, taskId)) {
+            inFlightAckedHoldState.delete(synthKey);
+            LOG.info('MeshReconcile', `Worker-emit priority: task ${taskId} on node ${nodeId} (mesh ${mesh.id}) has a real terminal completion already queued — yielding synth to the worker's own emit`);
+            continue;
         }
 
         const messages = Array.isArray(payload.messages) ? payload.messages as ChatMessage[] : [];
@@ -1369,6 +1526,21 @@ async function reconcileUnterminatedDirectDispatches(
             continue;
         }
 
+        // R4f (auxiliary, was R4e fix 2) — live re-probe immediately before committing the synth. A
+        // fresh read right now catches a worker that resumed generating since this tick's first read
+        // so it is never falsely completed off a stale snapshot. Best-effort: an inconclusive
+        // re-probe (transport error/null) falls through to the synth — we already hold a valid idle
+        // read from the top of THIS tick, so a re-probe failure must not re-introduce a
+        // notification-miss. Under the R4f acked-hold this matters mainly for the never-acked path
+        // and the post-death-deadline acked synth (the indefinite hold already deferred a live acked
+        // turn); it stays as a final live-state guard at synth-commit time.
+        const reprobeStatus = await reprobeWorkerStatus(components, { isLocalNode, nodeDaemonId, readArgs });
+        if (reprobeStatus && reprobeStatus !== 'idle') {
+            inFlightAckedHoldState.delete(synthKey);
+            LOG.info('MeshReconcile', `Live re-probe defer: task ${taskId} on node ${nodeId} (mesh ${mesh.id}) read '${reprobeStatus}' at synth-commit time — worker resumed generating; deferring synth to a later tick`);
+            continue;
+        }
+
         const providerSessionId = readNonEmptyString(payload.providerSessionId);
         const coordinatorDaemonId = selfIds.find(id => !!id);
         try {

package/src/mesh/mesh-refine-gates.ts

@@ -1160,6 +1160,9 @@ export async function alignRefinerySubmodulesAfterMerge(
         includeSubmodules: true,
         submoduleIgnorePaths: options.submoduleIgnorePaths,
         timeoutMs: 15_000,
+        // Decision path — the out-of-sync submodule set drives a mutating `submodule
+        // update`. Must not act on a TTL-cached status; bypass the C1 cache.
+        forceFresh: true,
     });
     const outOfSyncPaths = (preStatus.submodules || [])
         .filter(submodule => submodule.dirty || submodule.outOfSync || !!submodule.error)
@@ -1193,6 +1196,9 @@ export async function alignRefinerySubmodulesAfterMerge(
             includeSubmodules: true,
             submoduleIgnorePaths: options.submoduleIgnorePaths,
             timeoutMs: 15_000,
+            // Re-read AFTER `submodule update` mutated the tree — MUST be fresh, never the
+            // cached preStatus from moments ago (which would falsely report still-dirty).
+            forceFresh: true,
         });
         const remaining = (postStatus.submodules || [])
             .filter(submodule => updatePaths.includes(submodule.path) && (submodule.dirty || submodule.outOfSync || !!submodule.error));

package/src/mesh/mesh-runtime-store.ts

@@ -3,7 +3,7 @@ import { dirname, join } from 'path';
 import { LOG } from '../logging/logger.js';
 import { loadBetterSqlite3 } from '../system/load-better-sqlite3.js';
 import { getLedgerDir } from './mesh-ledger.js';
-import { nodeSatisfiesRequiredTags } from './mesh-work-queue.js';
+import { nodeSatisfiesRequiredTags, isTaskReadonly } from './mesh-work-queue.js';
 import { meshNodeIdMatches, daemonIdsEquivalent, expandDaemonIdForms } from '@adhdev/mesh-shared';
 import type { MeshTaskStatus, MeshWorkQueueEntry } from './mesh-work-queue.js';
 import type BetterSqlite3 from 'better-sqlite3';
@@ -752,11 +752,12 @@ export class MeshRuntimeStore {
                 return deps.every(depId => depStatus.get(depId) === 'completed');
             };
 
-            // Per-candidate node-conflict gate: write tasks (anything other than
-            // live_debug_readonly) require an idle node; read-only tasks bypass the
-            // node-busy check so N read-only diagnoses can run on one node at once.
+            // Per-candidate node-conflict gate: write tasks require an idle node; read-only
+            // tasks bypass the node-busy check so N read-only diagnoses can run on one node
+            // at once. Read-only classification is decided solely by isTaskReadonly (the
+            // single predicate shared with the cap counters / auto-launch / guardrail).
             const nodeConflictAllows = (candidate: MeshWorkQueueEntry): boolean => {
-                if (candidate.taskMode === 'live_debug_readonly') return true;
+                if (isTaskReadonly(candidate)) return true;
                 return !nodeBusy;
             };
 

package/src/mesh/mesh-scheduling-runtime.ts

@@ -22,6 +22,7 @@ import {
 } from '../repo-mesh-types.js';
 import { normalizeMeshNodeId } from '@adhdev/mesh-shared';
 import type { MeshWorkQueueEntry } from './mesh-work-queue.js';
+import { isTaskReadonly } from './mesh-work-queue.js';
 
 /** Per-(node, provider) cap and its current consumption. */
 export interface MeshNodeProviderSchedulingRuntime {
@@ -80,10 +81,6 @@ interface MeshLike {
     nodes?: Array<{ id?: string; nodeId?: string; node_id?: string; policy?: RepoMeshNodePolicy | null; isLocalWorktree?: boolean }> | null;
 }
 
-function isReadonly(task: MeshWorkQueueEntry): boolean {
-    return task.taskMode === 'live_debug_readonly';
-}
-
 function isAssigned(task: MeshWorkQueueEntry): boolean {
     return task.status === 'assigned';
 }
@@ -112,8 +109,8 @@ export function buildMeshSchedulingRuntime(
     const maxReadonlyParallelTasks = resolveMaxReadonlyParallelTasks(maxParallelTasks);
 
     const assignedTasks = (Array.isArray(queue) ? queue : []).filter(isAssigned);
-    const activeWriteAssigned = assignedTasks.filter(t => !isReadonly(t)).length;
-    const activeReadonlyAssigned = assignedTasks.filter(isReadonly).length;
+    const activeWriteAssigned = assignedTasks.filter(t => !isTaskReadonly(t)).length;
+    const activeReadonlyAssigned = assignedTasks.filter(isTaskReadonly).length;
     const globalWriteCapReached = activeWriteAssigned >= maxParallelTasks;
     const globalReadonlyCapReached = activeReadonlyAssigned >= maxReadonlyParallelTasks;
 
@@ -126,7 +123,7 @@ export function buildMeshSchedulingRuntime(
         const nodeId = typeof task.assignedNodeId === 'string' ? task.assignedNodeId.trim() : '';
         if (!nodeId) continue;
         assignedByNode.set(nodeId, (assignedByNode.get(nodeId) ?? 0) + 1);
-        if (!isReadonly(task)) {
+        if (!isTaskReadonly(task)) {
             writeAssignedByNode.set(nodeId, (writeAssignedByNode.get(nodeId) ?? 0) + 1);
         }
         const provider = typeof task.assignedProviderType === 'string' ? task.assignedProviderType : '';

package/src/mesh/mesh-work-queue.ts

@@ -18,6 +18,29 @@ export const ACTIVE_MESH_QUEUE_STATUSES: MeshActiveTaskStatus[] = ['pending', 'a
 export const HISTORICAL_MESH_QUEUE_STATUSES: MeshHistoricalTaskStatus[] = ['completed', 'failed', 'cancelled'];
 export const MESH_TASK_MODES: MeshTaskMode[] = ['code_change', 'validation', 'live_debug_readonly', 'launch_app', 'convergence'];
 
+/**
+ * QUEUE-NODE-SERIALIZATION: single source of truth for "is this task read-only?".
+ *
+ * Read-only classification used to be inlined as `task.taskMode === 'live_debug_readonly'`
+ * at every enforcement site (node-conflict claim gate, auto-launch isolation, the
+ * write/readonly cap counters, the write guardrail). That spread-out comparison is the
+ * exact recurring-defect class — one site drifting from the others silently makes the same
+ * task read-only at some gates and write at others, i.e. partial serialization. All sites
+ * MUST call this predicate so the classification is decided in exactly one place.
+ *
+ * Two orthogonal inputs feed the same boolean axis (kept backward-compatible):
+ *   • `readonly === true` — the explicit boolean axis (new API surface).
+ *   • `taskMode === 'live_debug_readonly'` — the original enum value, preserved as an
+ *     OR-fallback so existing live_debug_readonly tasks keep behaving identically.
+ *
+ * Accepts any task-like shape (full {@link MeshWorkQueueEntry} or a bare
+ * `{ readonly?, taskMode? }`) so the daemon-core and mcp-server boundaries can share it.
+ */
+export function isTaskReadonly(task: { readonly?: boolean; taskMode?: MeshTaskMode | string } | null | undefined): boolean {
+    if (!task) return false;
+    return task.readonly === true || task.taskMode === 'live_debug_readonly';
+}
+
 export interface MeshTaskModeValidationResult {
     valid: boolean;
     taskMode?: MeshTaskMode;
@@ -410,13 +433,15 @@ export function normalizeMeshTaskMode(value: unknown): MeshTaskMode | undefined
     return (MESH_TASK_MODES as string[]).includes(normalized) ? normalized : undefined;
 }
 
-export function validateMeshTaskModeRequest(mode: unknown, message: string): MeshTaskModeValidationResult {
+export function validateMeshTaskModeRequest(mode: unknown, message: string, readonly?: boolean): MeshTaskModeValidationResult {
     const taskMode = normalizeMeshTaskMode(mode);
-    if (!taskMode) {
-        return { valid: true, violations: [] };
-    }
-    if (taskMode !== 'live_debug_readonly') {
-        return { valid: true, taskMode, violations: [] };
+    // QUEUE-NODE-SERIALIZATION: the write guardrail (reject deploy/push/edit commands on a
+    // read-only task) is driven by the unified read-only axis, not by the enum alone — so a
+    // task flagged read-only via the explicit `readonly:true` boolean is guarded identically
+    // to a legacy live_debug_readonly task. isTaskReadonly is the single classifier.
+    const isReadonly = isTaskReadonly({ readonly, taskMode });
+    if (!isReadonly) {
+        return taskMode ? { valid: true, taskMode, violations: [] } : { valid: true, violations: [] };
     }
     const text = message || '';
     // Only flag keywords that look like real commands (code/command context) and
@@ -447,6 +472,14 @@ export interface MeshWorkQueueEntry {
     message: string;
     status: MeshTaskStatus;
     taskMode?: MeshTaskMode;
+    /**
+     * QUEUE-NODE-SERIALIZATION: explicit read-only axis, orthogonal to taskMode. When
+     * true the task is treated as read-only by every scheduling gate (no node-busy
+     * isolation, counted under the read-only cap, write commands rejected) regardless of
+     * its taskMode. Decided exclusively through {@link isTaskReadonly}; `taskMode ===
+     * 'live_debug_readonly'` remains an OR-fallback so legacy rows behave unchanged.
+     */
+    readonly?: boolean;
     /** If specified, only this node can claim the task (used by legacy mesh_send_task) */
     targetNodeId?: string;
     /** If specified, only this runtime session can claim the task */
@@ -722,6 +755,8 @@ export function enqueueTask(
         targetNodeId?: string;
         targetSessionId?: string;
         taskMode?: MeshTaskMode | string;
+        /** QUEUE-NODE-SERIALIZATION: explicit read-only axis (orthogonal to taskMode). */
+        readonly?: boolean;
         requiredTags?: string[];
         /** M1: tasks that must complete before this one is claimable. */
         dependsOn?: string[];
@@ -734,7 +769,8 @@ export function enqueueTask(
     } & MeshQueueMutationOptions,
 ): MeshWorkQueueEntry {
     requireMeshHostQueueOwner(opts);
-    const modeValidation = validateMeshTaskModeRequest(opts?.taskMode, message);
+    const readonly = opts?.readonly === true;
+    const modeValidation = validateMeshTaskModeRequest(opts?.taskMode, message, readonly);
     if (!modeValidation.valid) {
         throw new Error(`live_debug_readonly_guardrail_violation: forbidden operations (${modeValidation.violations.join(', ')})`);
     }
@@ -763,6 +799,7 @@ export function enqueueTask(
             message,
             status: 'pending',
             taskMode: modeValidation.taskMode,
+            ...(readonly ? { readonly: true } : {}),
             targetNodeId: opts?.targetNodeId,
             targetSessionId: opts?.targetSessionId,
             requiredTags: resolvedRequiredTags,
@@ -806,6 +843,8 @@ export function recordDirectDispatchTask(
         assignedNodeId?: string;
         assignedSessionId?: string;
         taskMode?: MeshTaskMode | string;
+        /** QUEUE-NODE-SERIALIZATION: explicit read-only axis (orthogonal to taskMode). */
+        readonly?: boolean;
         dispatchedAt?: string;
     },
 ): MeshWorkQueueEntry | null {
@@ -813,7 +852,8 @@ export function recordDirectDispatchTask(
     if (!missionId) return null;
     const taskId = typeof opts.id === 'string' ? opts.id.trim() : '';
     if (!taskId) return null;
-    const modeValidation = validateMeshTaskModeRequest(opts.taskMode, message);
+    const readonly = opts.readonly === true;
+    const modeValidation = validateMeshTaskModeRequest(opts.taskMode, message, readonly);
     if (!modeValidation.valid) {
         throw new Error(`live_debug_readonly_guardrail_violation: forbidden operations (${modeValidation.violations.join(', ')})`);
     }
@@ -829,6 +869,7 @@ export function recordDirectDispatchTask(
             message,
             status: 'assigned',
             ...(modeValidation.taskMode ? { taskMode: modeValidation.taskMode } : {}),
+            ...(readonly ? { readonly: true } : {}),
             missionId,
             ...(opts.assignedNodeId ? { targetNodeId: opts.assignedNodeId, assignedNodeId: opts.assignedNodeId } : {}),
             ...(opts.assignedSessionId ? { targetSessionId: opts.assignedSessionId, assignedSessionId: opts.assignedSessionId } : {}),