@adhdev/daemon-standalone 0.9.82-rc.552 → 0.9.82-rc.554

package/dist/index.js

@@ -29898,6 +29898,15 @@ var require_dist3 = __commonJS({
       }
       return true;
     }
+    function resolveAllowSendKeysDestructive(meshPolicy, nodePolicy) {
+      if (typeof nodePolicy?.allowSendKeysDestructive === "boolean") {
+        return nodePolicy.allowSendKeysDestructive;
+      }
+      if (typeof meshPolicy?.allowSendKeysDestructive === "boolean") {
+        return meshPolicy.allowSendKeysDestructive;
+      }
+      return false;
+    }
     function resolveProviderMaxParallel(slots, providerType) {
       const wanted = typeof providerType === "string" ? providerType.trim().toLowerCase() : "";
       if (!wanted) return void 0;
@@ -30208,10 +30217,10 @@ var require_dist3 = __commonJS({
     }
     function getDaemonBuildInfo() {
       if (cached2) return cached2;
-      const commit = readInjected(true ? "178a437592e2f9544675a54768b48281804bdddb" : void 0) ?? "unknown";
-      const commitShort = readInjected(true ? "178a4375" : void 0) ?? (commit !== "unknown" ? commit.slice(0, 7) : "unknown");
-      const version2 = readInjected(true ? "0.9.82-rc.552" : void 0) ?? readInjected(typeof process !== "undefined" ? process.env?.ADHDEV_PKG_VERSION : void 0) ?? "unknown";
-      const builtAt = readInjected(true ? "2026-07-17T04:27:07.205Z" : void 0);
+      const commit = readInjected(true ? "23529650799df69f9a14f16f6c2b34db153f1b27" : void 0) ?? "unknown";
+      const commitShort = readInjected(true ? "23529650" : void 0) ?? (commit !== "unknown" ? commit.slice(0, 7) : "unknown");
+      const version2 = readInjected(true ? "0.9.82-rc.554" : void 0) ?? readInjected(typeof process !== "undefined" ? process.env?.ADHDEV_PKG_VERSION : void 0) ?? "unknown";
+      const builtAt = readInjected(true ? "2026-07-17T07:58:44.290Z" : void 0);
       cached2 = builtAt ? { commit, commitShort, version: version2, builtAt } : { commit, commitShort, version: version2 };
       return cached2;
     }
@@ -32799,6 +32808,8 @@ ${error48.message || ""}`;
           "mesh_send_task",
           "mesh_read_chat",
           "mesh_read_debug",
+          "mesh_read_terminal",
+          "mesh_send_keys",
           "mesh_launch_session",
           "mesh_git_status",
           "mesh_read_node_logs",
@@ -33951,6 +33962,8 @@ When you compose the task message you dispatch to a node, include these requirem
 | \`mesh_launch_session\` | Start a new agent session on a node |
 | \`mesh_read_chat\` | Read recent chat messages from a delegated agent session |
 | \`mesh_read_debug\` | Collect a daemon-side chat/parser debug bundle for a session |
+| \`mesh_read_terminal\` | Read a worker session's CURRENT raw terminal screen (the live rendered PTY viewport \u2014 prompt/modal/spinner/unparsed output), not the parsed chat. Byte-bounded (32KiB default, 64KiB max; bottom of screen kept). Use to see exactly what a worker is showing when mesh_read_chat is not enough (e.g. after a stall alert). Screen text may contain secrets \u2014 treat as sensitive |
+| \`mesh_send_keys\` | Inject a STRUCTURED key sequence into a worker's live PTY (text + named keys ENTER/ESC/CTRL_C/UP/DOWN/LEFT/RIGHT/TAB/BACKSPACE). For interactions mesh_send_task can't express \u2014 answer a non-approval prompt, navigate a picker, submit a typed line, or interrupt (CTRL_C). Use mesh_approve for approval modals (send_keys is refused on one). Destructive keys (CTRL_C/ESC) need confirm_destructive=true AND mesh policy allowSendKeysDestructive. Refused on a pending submit/echo race. Audited (key enums only) |
 | \`mesh_task_history\` | Read the task ledger \u2014 dispatches, completions, failures. Use to understand what has been done before deciding next steps |
 | \`mesh_ledger_query\` | Read-only ledger query along the kind/time/node axes (complement to task-axis mesh_task_history): filter by kind, since, node, tail \u2014 answer "what happened on node X / what failed since T" without scanning transcripts |
 | \`mesh_reconcile_ledger\` | Reconcile daemon-local ledgers over P2P \u2014 import missing entries from remote nodes into the coordinator local ledger |
@@ -38661,6 +38674,13 @@ Do NOT retry on this node. Consider reassigning to a different node or asking th
         return `[System] ${args.nodeLabel} has stopped${metadata}. Use mesh_read_chat once if you need to inspect its last output.`;
       }
       if (args.event === "monitor:no_progress") {
+        if (args.metadataEvent.meshWorkerStall === true) {
+          const observedStatus = readNonEmptyString2(args.metadataEvent.observedStatus);
+          const stalledMs = typeof args.metadataEvent.stalledMs === "number" ? args.metadataEvent.stalledMs : void 0;
+          const stalledSuffix = stalledMs !== void 0 ? ` for ${Math.round(stalledMs / 1e3)}s` : "";
+          const statusSuffix = observedStatus ? ` (observed status: ${observedStatus})` : "";
+          return `[System] ${args.nodeLabel}: PTY output unchanged${stalledSuffix}${statusSuffix}${metadata}. This is an informational stall \u2014 the worker's screen has been static regardless of its reported status; it may be genuinely idle, waiting, or wedged, so this is NOT a failure or auto-restart. Judge whether to inspect it: wait for pendingCoordinatorEvents/a completion event, or make one bounded mesh_read_chat check if you need to see its current screen, then wait again.`;
+        }
         return `[System] ${args.nodeLabel} is still reported as generating after a long interval${metadata}. Wait for pendingCoordinatorEvents or a completion/status event; if the user explicitly asks for status, make one bounded status check and then wait again.`;
       }
       if (args.event === "worktree_bootstrap_complete") {
@@ -42486,6 +42506,82 @@ ${rendered}`, "utf-8");
       const accumulator = new TerminalTranscriptAccumulator();
       return stripTerminalNoise(stripAnsi(accumulator.append(str)));
     }
+    function encodeMeshSendKeys(items) {
+      if (!Array.isArray(items) || items.length === 0) {
+        throw new Error("send_keys: sequence must be a non-empty array");
+      }
+      if (items.length > MESH_SEND_KEYS_MAX_ITEMS) {
+        throw new Error(`send_keys: sequence exceeds ${MESH_SEND_KEYS_MAX_ITEMS} items`);
+      }
+      const parts = [];
+      const keys = [];
+      let hasDestructive = false;
+      let submits = false;
+      let textBytes = 0;
+      for (const item of items) {
+        if (item && typeof item.text === "string") {
+          const text = item.text;
+          textBytes += Buffer.byteLength(text, "utf8");
+          if (textBytes > MESH_SEND_KEYS_MAX_TEXT_BYTES) {
+            throw new Error(`send_keys: total literal text exceeds ${MESH_SEND_KEYS_MAX_TEXT_BYTES} bytes`);
+          }
+          parts.push(text);
+          submits = false;
+          continue;
+        }
+        const keyName = item && typeof item.key === "string" ? item.key : "";
+        if (!(keyName in MESH_SEND_KEY_ENCODING)) {
+          throw new Error(`send_keys: unknown key '${keyName}'`);
+        }
+        const key2 = keyName;
+        parts.push(MESH_SEND_KEY_ENCODING[key2]);
+        keys.push(key2);
+        if (MESH_DESTRUCTIVE_KEYS.has(key2)) hasDestructive = true;
+        submits = key2 === "ENTER";
+      }
+      return { sequence: parts.join(""), keys, hasDestructive, submits };
+    }
+    function truncateToByteTailByLine(text, maxBytes) {
+      const input = String(text ?? "");
+      const originalBytes = Buffer.byteLength(input, "utf8");
+      if (originalBytes <= maxBytes) {
+        return { text: input, truncated: false, originalBytes, returnedBytes: originalBytes };
+      }
+      const lines = input.split("\n");
+      const kept = [];
+      let bytes = 0;
+      for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        const lineBytes = Buffer.byteLength(line, "utf8");
+        const joinCost = kept.length > 0 ? 1 : 0;
+        if (bytes + lineBytes + joinCost > maxBytes) break;
+        bytes += lineBytes + joinCost;
+        kept.unshift(line);
+      }
+      if (kept.length > 0) {
+        const out = kept.join("\n");
+        return {
+          text: out,
+          truncated: true,
+          originalBytes,
+          returnedBytes: Buffer.byteLength(out, "utf8")
+        };
+      }
+      const lastLine = lines[lines.length - 1] ?? "";
+      const buf = Buffer.from(lastLine, "utf8");
+      let slice = buf.subarray(Math.max(0, buf.length - maxBytes));
+      let decoded = slice.toString("utf8");
+      while (decoded.length > 0 && decoded.charCodeAt(0) === 65533 && slice.length > 0) {
+        slice = slice.subarray(1);
+        decoded = slice.toString("utf8");
+      }
+      return {
+        text: decoded,
+        truncated: true,
+        originalBytes,
+        returnedBytes: Buffer.byteLength(decoded, "utf8")
+      };
+    }
     function listCliScriptNames(scripts) {
       if (!scripts) return [];
       return Object.entries(scripts).filter(([, fn]) => typeof fn === "function").map(([name]) => name);
@@ -42690,6 +42786,10 @@ ${rendered}`, "utf-8");
     var os52;
     var path11;
     var TerminalTranscriptAccumulator;
+    var MESH_SEND_KEY_ENCODING;
+    var MESH_DESTRUCTIVE_KEYS;
+    var MESH_SEND_KEYS_MAX_ITEMS;
+    var MESH_SEND_KEYS_MAX_TEXT_BYTES;
     var buildCliSpawnEnv;
     var init_provider_cli_shared = __esm2({
       "src/cli-adapters/provider-cli-shared.ts"() {
@@ -42853,6 +42953,20 @@ ${rendered}`, "utf-8");
             this.ensureRow();
           }
         };
+        MESH_SEND_KEY_ENCODING = {
+          ENTER: "\r",
+          ESC: "\x1B",
+          CTRL_C: "",
+          UP: "\x1B[A",
+          DOWN: "\x1B[B",
+          RIGHT: "\x1B[C",
+          LEFT: "\x1B[D",
+          TAB: "	",
+          BACKSPACE: "\x7F"
+        };
+        MESH_DESTRUCTIVE_KEYS = /* @__PURE__ */ new Set(["CTRL_C", "ESC"]);
+        MESH_SEND_KEYS_MAX_ITEMS = 64;
+        MESH_SEND_KEYS_MAX_TEXT_BYTES = 4096;
         buildCliSpawnEnv = import_session_host_core22.sanitizeSpawnEnv;
       }
     });
@@ -48014,6 +48128,10 @@ The mesh has no work in flight. For each mission, decide its outcome: continue i
           getCursorPosition() {
             return this.terminal.getCursorPosition();
           }
+          /** Current viewport dimensions (cols × rows). */
+          getSize() {
+            return { cols: this.cols, rows: this.rows };
+          }
           dispose() {
             this.terminal.dispose();
           }
@@ -56766,6 +56884,7 @@ ${cont}` : cont;
       return current.slice(-keepFromCurrent) + chunk;
     }
     var os16;
+    var import_crypto10;
     var import_session_host_core6;
     var FORCE_SUBMIT_SETTLE_MS;
     var ProviderCliAdapter;
@@ -56773,6 +56892,7 @@ ${cont}` : cont;
       "src/cli-adapters/provider-cli-adapter.ts"() {
         "use strict";
         os16 = __toESM2(require("os"));
+        import_crypto10 = require("crypto");
         init_logger();
         init_debug_config();
         init_terminal_screen();
@@ -56974,6 +57094,11 @@ ${cont}` : cont;
           static MAX_ACCUMULATED_BUFFER = 262144;
           parsedStatusCache = null;
           static SCREEN_SNAPSHOT_MIN_INTERVAL_MS = 250;
+          // MESH-READ-TERMINAL (feature 2): byte caps for getTerminalScreenSnapshot.
+          // Byte, not char — a multi-byte-glyph screen can exceed an MCP payload cap
+          // while the char count still looks safe. 32KiB default, 64KiB absolute hard cap.
+          static TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES = 32 * 1024;
+          static TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES = 64 * 1024;
           // (FALSEIDLE Path-C) Consecutive gate-eligible getStatus polls a mesh/autonomous
           // session must show before the poll-static-idle confirm fires. 2 = one extra
           // status tick of hysteresis: enough to reject a single momentary-silence
@@ -58552,6 +58677,103 @@ ${lastSnapshot}`;
           isAlive() {
             return this.ptyProcess !== null;
           }
+          /**
+           * MESH-READ-TERMINAL (feature 2: RAW terminal read). Narrow, least-privilege
+           * read of the CURRENT rendered viewport for mesh_read_terminal. Deliberately
+           * NARROWER than getSnapshot()/getDebugSnapshot():
+           *  - It returns ONLY the terminal's current rendered viewport (what a human
+           *    would see on screen right now), the cursor position and the viewport
+           *    size. NO debug buffers, NO parser/FSM state, NO scrollback/history.
+           *  - It does NOT call getParseScreenText() (which may graft an older snapshot
+           *    onto the current frame for parse accuracy) — the caller asked for the
+           *    live viewport, not a parse-optimized composite.
+           *  - The payload is bounded in BYTES (UTF-8) with bottom-tail preservation so
+           *    a screen of multi-byte glyphs can never exceed the MCP payload cap. See
+           *    truncateToByteTailByLine.
+           *
+           * SECURITY NOTE: the raw viewport can contain tokens / command args / env
+           * values / user data. Callers MUST gate this on mesh ownership and MUST NOT
+           * log the returned text. Opt-in redaction is intentionally out of scope for
+           * this feature and left as a future enhancement.
+           *
+           * `maxBytes` is clamped to [1KiB, ABSOLUTE_MAX] (default 32KiB, hard cap 64KiB).
+           */
+          getTerminalScreenSnapshot(maxBytes = _ProviderCliAdapter.TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES) {
+            const cap = Math.min(
+              _ProviderCliAdapter.TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES,
+              Math.max(1024, Math.floor(maxBytes) || _ProviderCliAdapter.TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES)
+            );
+            const rawViewport = this.terminalScreen.getText() || "";
+            const size = this.terminalScreen.getSize();
+            const cursor = this.terminalScreen.getCursorPosition();
+            const truncation = truncateToByteTailByLine(rawViewport, cap);
+            const hash2 = (0, import_crypto10.createHash)("sha256").update(rawViewport, "utf8").digest("hex").slice(0, 16);
+            return {
+              text: truncation.text,
+              cursor,
+              cols: size.cols,
+              rows: size.rows,
+              truncated: truncation.truncated,
+              originalBytes: truncation.originalBytes,
+              returnedBytes: truncation.returnedBytes,
+              hash: hash2
+            };
+          }
+          /**
+           * MESH-SEND-KEYS (feature 3: key injection). Inject a STRUCTURED key sequence
+           * into the PTY for the mesh_send_keys tool. Reuses the same serialized write
+           * path as sends (writeToPty via writeRaw semantics) so the injection FIFO-
+           * orders behind any in-flight write.
+           *
+           * Two guards run INSIDE this method, immediately before the write, so they see
+           * a consistent snapshot of the adapter's submit/echo/queue state (no async gap
+           * between check and write — the encode is synchronous and the write is chained
+           * atomically after it):
+           *
+           *  1. submit-race recheck (echo-gate): even though writeToPty is FIFO, an
+           *     already-SCHEDULED echo-gated Enter (engine.submitPendingUntil in the
+           *     future), an armed stuck-submit retry (submitRetryTimer), or an in-flight
+           *     pending-outbound flush can submit at a DIFFERENT tick than our write —
+           *     so an injected literal could be submitted by a pending Enter, or our
+           *     ENTER could submit a half-typed pending body. When any of those is live
+           *     we REFUSE the injection rather than interleave.
+           *
+           *  2. modal fail-closed: if the session is parked on an actionable approval
+           *     modal, refuse a NON-destructive injection (ENTER/text/arrows) and direct
+           *     the caller to mesh_approve — so a modal choice can't be confirmed via
+           *     send_keys to bypass the approval policy. (A destructive ESC/CTRL_C, which
+           *     dismisses rather than confirms, is allowed to proceed past this gate; it
+           *     is separately gated by confirm_destructive + policy at the tool layer.)
+           *
+           * The caller (tool layer) owns the destructive-key double gate and the audit
+           * ledger. This method NEVER logs the literal text (only key enums / byte len).
+           */
+          async injectKeys(items, opts = {}) {
+            if (!this.ptyProcess) throw new Error(`${this.cliName} is not running`);
+            const encoded = encodeMeshSendKeys(items);
+            const now = Date.now();
+            const submitPending = this.engine.submitPendingUntil > now;
+            const submitRetryArmed = this.submitRetryTimer !== null;
+            const outboundBusy = this.pendingOutboundFlushInFlight || this.pendingOutboundQueue.length > 0;
+            if (submitPending || submitRetryArmed || outboundBusy) {
+              LOG2.warn("CLI", `[${this.cliType}] send_keys refused (submit_race): submitPending=${submitPending} submitRetry=${submitRetryArmed} outboundBusy=${outboundBusy} keys=${encoded.keys.join(",")}`);
+              return { ok: false, refused: "submit_race", keys: encoded.keys, hasDestructive: encoded.hasDestructive };
+            }
+            const modalActive = this.engine.hasActionableApproval();
+            if (modalActive && !encoded.hasDestructive && !opts.allowModalOverride) {
+              LOG2.warn("CLI", `[${this.cliType}] send_keys refused (actionable_modal): keys=${encoded.keys.join(",")} \u2014 use mesh_approve`);
+              return { ok: false, refused: "actionable_modal", keys: encoded.keys, hasDestructive: encoded.hasDestructive };
+            }
+            await this.writeToPty(encoded.sequence);
+            LOG2.info("CLI", `[${this.cliType}] send_keys injected keys=${encoded.keys.join(",") || "(text-only)"} bytes=${Buffer.byteLength(encoded.sequence, "utf8")} destructive=${encoded.hasDestructive}`);
+            return {
+              ok: true,
+              keys: encoded.keys,
+              hasDestructive: encoded.hasDestructive,
+              submits: encoded.submits,
+              bytes: Buffer.byteLength(encoded.sequence, "utf8")
+            };
+          }
           flushOutboundQueue() {
             this.schedulePendingOutboundFlush();
           }
@@ -59390,6 +59612,7 @@ ${lastSnapshot}`;
       resetConfig: () => resetConfig,
       resetDebugRuntimeConfig: () => resetDebugRuntimeConfig,
       resetState: () => resetState,
+      resolveAllowSendKeysDestructive: () => resolveAllowSendKeysDestructive,
       resolveAutoConvergeCodeChange: () => resolveAutoConvergeCodeChange,
       resolveChatMessageKind: () => resolveChatMessageKind,
       resolveConvergeRequiredTags: () => resolveConvergeRequiredTags,
@@ -69670,6 +69893,63 @@ ${effect.notification.body || ""}`.trim();
       if (!cols || !rows) return { success: false, error: "cols and rows required" };
       return { success: false, error: "PTY resize temporarily disabled", code: "PTY_RESIZE_DISABLED" };
     }
+    function handleReadTerminal(h, args) {
+      const targetSessionId = typeof args?.targetSessionId === "string" ? args.targetSessionId.trim() : "";
+      const sessionId = targetSessionId || h.currentSession?.sessionId || "";
+      if (!sessionId) return { success: false, error: "targetSessionId required" };
+      const session = h.ctx.sessionRegistry?.get(sessionId);
+      const instanceKey = session?.adapterKey || session?.instanceKey || sessionId;
+      const instance = h.ctx.instanceManager?.getInstance(instanceKey);
+      if (!instance) return { success: false, error: `Session not found: ${sessionId.split("_")[0]}` };
+      if (instance.category !== "cli" || typeof instance.getTerminalScreenSnapshot !== "function") {
+        return { success: false, error: "read_terminal is only supported for CLI (PTY) sessions" };
+      }
+      const requestedMaxBytes = typeof args?.maxBytes === "number" && Number.isFinite(args.maxBytes) ? args.maxBytes : void 0;
+      const snapshot = instance.getTerminalScreenSnapshot(requestedMaxBytes);
+      if (!snapshot) {
+        return { success: false, error: "read_terminal is only available for coordinator-spawned mesh worker sessions" };
+      }
+      LOG2.info("Command", `[readTerminal] session=${sessionId.split("_")[0]} bytes=${snapshot.returnedBytes}/${snapshot.originalBytes} truncated=${snapshot.truncated} cols=${snapshot.cols} rows=${snapshot.rows}`);
+      return { success: true, ...snapshot };
+    }
+    async function handleSendKeys(h, args) {
+      const targetSessionId = typeof args?.targetSessionId === "string" ? args.targetSessionId.trim() : "";
+      const sessionId = targetSessionId || h.currentSession?.sessionId || "";
+      if (!sessionId) return { success: false, error: "targetSessionId required" };
+      const items = Array.isArray(args?.sequence) ? args.sequence : null;
+      if (!items || items.length === 0) {
+        return { success: false, error: "sequence (non-empty array of {text}|{key}) required" };
+      }
+      const session = h.ctx.sessionRegistry?.get(sessionId);
+      const instanceKey = session?.adapterKey || session?.instanceKey || sessionId;
+      const instance = h.ctx.instanceManager?.getInstance(instanceKey);
+      if (!instance) return { success: false, error: `Session not found: ${sessionId.split("_")[0]}` };
+      if (instance.category !== "cli" || typeof instance.injectKeys !== "function") {
+        return { success: false, error: "send_keys is only supported for CLI (PTY) sessions" };
+      }
+      const DESTRUCTIVE = /* @__PURE__ */ new Set(["CTRL_C", "ESC"]);
+      const hasDestructiveRequested = items.some((it) => it && typeof it.key === "string" && DESTRUCTIVE.has(it.key));
+      if (hasDestructiveRequested && args?.confirm_destructive !== true) {
+        return {
+          success: false,
+          error: "destructive key (CTRL_C/ESC) requires confirm_destructive=true",
+          refused: "destructive_unconfirmed"
+        };
+      }
+      try {
+        const result = await instance.injectKeys(items, {
+          allowModalOverride: args?.allow_modal_override === true
+        });
+        if (!result.ok) {
+          LOG2.info("Command", `[sendKeys] session=${sessionId.split("_")[0]} refused=${result.refused} keys=${result.keys.join(",")} destructive=${result.hasDestructive}`);
+          return { success: false, error: `send_keys refused: ${result.refused}`, refused: result.refused, keys: result.keys, hasDestructive: result.hasDestructive };
+        }
+        LOG2.info("Command", `[sendKeys] session=${sessionId.split("_")[0]} injected keys=${result.keys.join(",") || "(text-only)"} bytes=${result.bytes} destructive=${result.hasDestructive} submits=${result.submits}`);
+        return { success: true, keys: result.keys, hasDestructive: result.hasDestructive, submits: result.submits, bytes: result.bytes };
+      } catch (e) {
+        return { success: false, error: `send_keys: ${e?.message || String(e)}` };
+      }
+    }
     function handleGetProviderSettings(h, args) {
       const loader = h.ctx.providerLoader;
       const { providerType } = args || {};
@@ -70523,6 +70803,12 @@ ${effect.notification.body || ""}`.trim();
             return handlePtyInput(this, args);
           case "pty_resize":
             return handlePtyResize(this, args);
+          // ─── MESH-READ-TERMINAL (feature 2): raw viewport read ──────────
+          case "read_terminal":
+            return handleReadTerminal(this, args);
+          // ─── MESH-SEND-KEYS (feature 3): structured key injection ────────
+          case "send_keys":
+            return handleSendKeys(this, args);
           // ─── Provider Settings (stream-commands.ts) ──────────
           case "get_provider_settings":
             return handleGetProviderSettings(this, args);
@@ -73225,6 +73511,12 @@ ${body}
         const pos = this.screen.getCursorPosition();
         return { row: pos.row, col: pos.col };
       }
+      /** Current terminal geometry (columns × rows). Tracked here rather than
+       *  read off the screen buffer so a resize is reflected immediately, before
+       *  the next repaint. Consumed by the mesh_read_terminal viewport read. */
+      getScreenSize() {
+        return { cols: this.cols, rows: this.rows };
+      }
       send_keys(text) {
         this.recordEvent("input", capPreview(escapeControl(text)), text.length);
         this.pty?.write(text);
@@ -73557,6 +73849,9 @@ ${body}
       getScreen() {
         return this.adapter.snapshot();
       }
+      getScreenSize() {
+        return this.adapter.getScreenSize();
+      }
       /** Scrollback-inclusive screen as line array — used only for modal/button
        *  content extraction so a tall prompt's off-screen anchors stay matchable.
        *  Falls back to the viewport snapshot if scrollback read is unavailable. */
@@ -75583,6 +75878,8 @@ ${body}
       return out;
     }
     var fs20 = __toESM2(require("fs"));
+    var import_node_crypto4 = require("crypto");
+    init_provider_cli_shared();
     init_logger();
     function stripAnsi3(text) {
       return String(text || "").replace(/\x1B\][^\x07]*(?:\x07|\x1B\\)/g, "").replace(/\x1B[P^_X][\s\S]*?(?:\x07|\x1B\\)/g, "").replace(/\x1B(?:[@-Z\\-_]|\[[0-?]*[ -/]*[@-~])/g, "");
@@ -75761,6 +76058,105 @@ ${body}
       isReady() {
         return this.spawned && !this.exited;
       }
+      // Process liveness for the MESH-STALL-WATCH watchdog (checkMeshWorkerStall).
+      // The spec path drives the child through the transport/driver rather than a
+      // directly-held ptyProcess handle, so liveness is tracked by the spawned/exited
+      // lifecycle flags — the same pair isReady() uses. A spawned, not-yet-exited
+      // session is alive. ProviderCliAdapter exposes the equivalent via `ptyProcess !== null`.
+      isAlive() {
+        return this.spawned && !this.exited;
+      }
+      // MESH-READ-TERMINAL / MESH-SEND-KEYS byte caps — same envelope as
+      // ProviderCliAdapter (32KiB default view, 64KiB absolute hard cap). Bytes,
+      // not chars: a multi-byte-glyph screen can exceed an MCP payload cap while
+      // the char count still looks safe.
+      static TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES = 32 * 1024;
+      static TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES = 64 * 1024;
+      /**
+       * MESH-READ-TERMINAL (feature 2: RAW terminal read). Least-privilege read
+       * of the CURRENT rendered viewport for mesh_read_terminal on the spec path
+       * (claude-cli / antigravity / codex-cli — the native-source providers that
+       * route through SpecCliAdapter). Mirrors ProviderCliAdapter.getTerminalScreenSnapshot:
+       *  - returns ONLY the driver's current viewport snapshot, the cursor
+       *    position and the terminal geometry — NO scrollback, NO parser/FSM
+       *    state, NO debug buffers;
+       *  - the payload is byte-bounded (UTF-8) with bottom-tail preservation so a
+       *    screen of multi-byte glyphs can never exceed the MCP payload cap;
+       *  - `hash` is over the FULL untruncated viewport so a caller can detect a
+       *    screen change across polls even when the returned text was truncated.
+       *
+       * SECURITY: the raw viewport can carry tokens / command args / env / user
+       * data. Callers MUST gate this on mesh ownership and MUST NOT log the text.
+       */
+      getTerminalScreenSnapshot(maxBytes = _SpecCliAdapter.TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES) {
+        const cap = Math.min(
+          _SpecCliAdapter.TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES,
+          Math.max(1024, Math.floor(maxBytes) || _SpecCliAdapter.TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES)
+        );
+        let rawViewport = "";
+        try {
+          rawViewport = this.driver.snapshot() || "";
+        } catch {
+          rawViewport = "";
+        }
+        let cursor = { row: 0, col: 0 };
+        try {
+          cursor = this.driver.getCursorPosition();
+        } catch {
+        }
+        let size = { cols: 0, rows: 0 };
+        try {
+          size = this.driver.getScreenSize?.() ?? size;
+        } catch {
+        }
+        const truncation = truncateToByteTailByLine(rawViewport, cap);
+        const hash2 = (0, import_node_crypto4.createHash)("sha256").update(rawViewport, "utf8").digest("hex").slice(0, 16);
+        return {
+          text: truncation.text,
+          cursor: { col: cursor.col, row: cursor.row },
+          cols: size.cols,
+          rows: size.rows,
+          truncated: truncation.truncated,
+          originalBytes: truncation.originalBytes,
+          returnedBytes: truncation.returnedBytes,
+          hash: hash2
+        };
+      }
+      /**
+       * MESH-SEND-KEYS (feature 3: key injection). Inject a STRUCTURED key
+       * sequence into the spec-driven PTY for mesh_send_keys. Mirrors
+       * ProviderCliAdapter.injectKeys' modal fail-closed guard, then writes the
+       * whole encoded sequence in ONE pty_write dispatch (text+ENTER is a single
+       * contiguous string, so a submit key can never be separated from the text
+       * it submits).
+       *
+       * The spec path drives the child through the FsmDriver, not a directly-held
+       * ptyProcess — there is no adapter-level echo-gate/submit-retry FIFO to race
+       * against here (the driver serializes its own writes), so the only guard is
+       * the modal fail-closed: a NON-destructive injection into an actionable
+       * approval modal is refused (use mesh_approve) unless explicitly overridden.
+       * A destructive ESC/CTRL_C dismisses rather than confirms, so it is allowed
+       * past this gate (the tool layer owns the destructive double-gate + audit).
+       * This method NEVER logs the literal text — only key enums / byte length.
+       */
+      async injectKeys(items, opts = {}) {
+        if (!this.spawned || this.exited) throw new Error(`${this.cliName} is not running`);
+        const encoded = encodeMeshSendKeys(items);
+        const modalActive = this.latestState?.status === "approval";
+        if (modalActive && !encoded.hasDestructive && !opts.allowModalOverride) {
+          LOG2.warn("SpecAdapter", `[${this.cliType}] send_keys refused (actionable_modal): keys=${encoded.keys.join(",")} \u2014 use mesh_approve`);
+          return { ok: false, refused: "actionable_modal", keys: encoded.keys, hasDestructive: encoded.hasDestructive };
+        }
+        this.driver.dispatch({ kind: "pty_write", data: encoded.sequence });
+        LOG2.info("SpecAdapter", `[${this.cliType}] send_keys injected keys=${encoded.keys.join(",") || "(text-only)"} bytes=${Buffer.byteLength(encoded.sequence, "utf8")} destructive=${encoded.hasDestructive}`);
+        return {
+          ok: true,
+          keys: encoded.keys,
+          hasDestructive: encoded.hasDestructive,
+          submits: encoded.submits,
+          bytes: Buffer.byteLength(encoded.sequence, "utf8")
+        };
+      }
       setOnStatusChange(cb) {
         this.statusCallback = cb;
       }
@@ -77049,6 +77445,15 @@ ${body}
        * with no approval never carries recency and is never held (no regression).
        */
       static APPROVAL_RESUME_GRACE_MS = 18e3;
+      // MESH-STALL-WATCH (feature 1: STALL detection): how long a coordinator-spawned
+      // mesh worker's raw PTY output (lastOutputAt) may stay unchanged before the
+      // status-agnostic stall watchdog fires ONE informational monitor:no_progress
+      // event. Unlike the StatusMonitor no-progress watchdog (which only runs while a
+      // turn is generating), this observes pure screen stasis regardless of the
+      // reported status — a worker parked idle, wedged mid-turn, or spawned with no
+      // output at all. 180s matches DEFAULT_MONITOR_CONFIG.noProgressThresholdSec so
+      // the two watchdogs agree on the same "long interval" bound.
+      static MESH_WORKER_STALL_THRESHOLD_MS = 18e4;
       adapter;
       context = null;
       events = [];
@@ -77062,6 +77467,16 @@ ${body}
       // first sets it; the other becomes a no-op.
       agentReadyEmitted = false;
       generatingStartedAt = 0;
+      // MESH-STALL-WATCH (feature 1): the lastOutputAt value the stall episode is
+      // currently armed against. A stall episode is "the raw PTY output has not
+      // advanced past this anchor". When the adapter has never emitted output
+      // (lastOutputAt === 0) the anchor is the spawn time (this.startedAt) so a
+      // worker that produced NOTHING is still caught. On any new output the anchor
+      // re-arms to the fresh lastOutputAt and meshStallEmittedForAnchor resets, so a
+      // single continuous stall fires AT MOST ONCE and a later stall re-arms cleanly.
+      // -1 = not yet initialised for this session.
+      meshStallAnchorAt = -1;
+      meshStallEmittedForAnchor = false;
       // FALSE-IDLE continuity epoch: monotonically bumped on EVERY entry into a busy
       // phase (→generating or →waiting_approval). The completedDebouncePending snapshots
       // this value at arm time (busyEpochAtArm); the flush guard requires it UNCHANGED
@@ -77985,6 +78400,25 @@ ${body}
         }
         return "";
       }
+      /**
+       * NOTIF Defect-B: the final assistant summary this instance ALREADY parsed and
+       * cached for the current turn (lastCompletionSummary), if any. The evidence
+       * probe (completionFinalAssistantEvidence) is a POINT-SAMPLE: on a native-source
+       * provider (antigravity) the parsed screen and the native transcript can both
+       * momentarily yield no in-turn final assistant at the exact instant the
+       * completion gate fires — source='unavailable', missingEvidence=true — even
+       * though a prior poll already read the real answer off native-history and cached
+       * it here (the same value mesh_read_chat.summary shows). Consulting the cache at
+       * emit time lets that already-secured summary count as evidence, so the completion
+       * notification carries the answer instead of completion_diagnostic=missing_final_assistant
+       * with an empty summary. Returns '' when the cache is empty or was reset by the
+       * next turn (see lastCompletionSummary = null on onTurnStarted).
+       */
+      cachedCompletionSummaryContent() {
+        const cached3 = this.lastCompletionSummary;
+        const content = typeof cached3?.content === "string" ? cached3.content.trim() : "";
+        return content;
+      }
       completionFinalAssistantEvidence(parsedMessages, turnStartedAt) {
         const turnClosed = !this.hasAdapterPendingResponse();
         if (this.completionHasFinalAssistantMessage(parsedMessages, turnStartedAt)) {
@@ -78048,12 +78482,19 @@ ${body}
         const lastVisibleRole = typeof lastVisible?.role === "string" ? lastVisible.role.trim().toLowerCase() : null;
         const lastVisibleKind = typeof lastVisible?.kind === "string" ? lastVisible.kind : null;
         const lastVisibleContentLength = lastVisible ? flattenContent(lastVisible.content).trim().length : 0;
+        const cachedSummary = evidence.present ? "" : this.cachedCompletionSummaryContent();
+        const creditedFromCache = !evidence.present && cachedSummary.length > 0;
+        const finalAssistantPresent = evidence.present || creditedFromCache;
+        const finalAssistantEvidenceSource = evidence.present ? evidence.source : creditedFromCache ? "cached-summary" : evidence.source;
+        const clearMissingBlock = creditedFromCache && args.blockReason === "missing_final_assistant";
+        const effectiveBlockReason = clearMissingBlock ? void 0 : args.blockReason;
         return {
           providerType: this.type,
           sessionId: this.instanceId,
           providerSessionId: this.providerSessionId || null,
           workspace: this.workingDir,
-          blockReason: args.blockReason,
+          ...effectiveBlockReason ? { blockReason: effectiveBlockReason } : {},
+          ...clearMissingBlock ? { originalBlockReason: args.blockReason } : {},
           emittedAfterFinalizationTimeout: args.emittedAfterFinalizationTimeout,
           waitedMs: args.waitedMs,
           maxWaitMs: COMPLETED_FINALIZATION_MAX_WAIT_MS,
@@ -78061,8 +78502,9 @@ ${body}
           latestVisibleStatus: args.latestVisibleStatus,
           parsedStatus: typeof parsed?.status === "string" ? parsed.status : parseError ? "parse_error" : "unknown",
           parseError: parseError || void 0,
-          finalAssistantPresent: evidence.present,
-          finalAssistantEvidenceSource: evidence.source,
+          finalAssistantPresent,
+          finalAssistantFromCachedSummary: !evidence.present && cachedSummary.length > 0,
+          finalAssistantEvidenceSource,
           visibleMessageCount: visibleMessages.length,
           lastVisibleRole,
           lastVisibleKind,
@@ -78240,6 +78682,128 @@ ${body}
       isMeshWorkerSession() {
         return !!(this.settings.meshNodeFor || this.settings.meshActiveTaskId || this.settings.meshNodeId || this.settings.launchedByCoordinator);
       }
+      /**
+       * MESH-READ-TERMINAL (feature 2: RAW terminal read). Public read of the
+       * CURRENT rendered PTY viewport for the mesh_read_terminal tool, delegating to
+       * the adapter's narrow getTerminalScreenSnapshot() (viewport + cursor + size
+       * only; no debug buffers / parser state / history; byte-bounded, bottom-tail
+       * preserved).
+       *
+       * Gated on isMeshWorkerSession(): this raw viewport can expose tokens /
+       * command args / env / user data, so only a coordinator-spawned worker session
+       * is readable. The MCP layer ALSO cross-checks mesh/session/node ownership
+       * (isMeshOwnedDelegateSession) — isMeshWorkerSession alone is a broad
+       * "delegated" gate, so the two together block cross-mesh access. Returns null
+       * for a non-mesh session so the daemon command surfaces a clean refusal.
+       */
+      getTerminalScreenSnapshot(maxBytes) {
+        if (!this.isMeshWorkerSession()) return null;
+        if (typeof this.adapter.getTerminalScreenSnapshot !== "function") return null;
+        return this.adapter.getTerminalScreenSnapshot(maxBytes);
+      }
+      /**
+       * MESH-SEND-KEYS (feature 3: key injection). Public entry for the
+       * mesh_send_keys tool, delegating to the adapter's injectKeys() (structured
+       * key encoding + atomic write + submit-race recheck + modal fail-closed).
+       *
+       * Gated on isMeshWorkerSession(): PTY input into a worker is a
+       * coordinator-only capability. The MCP layer ALSO cross-checks mesh/session/
+       * node ownership (isMeshOwnedDelegateSession) and owns the destructive-key
+       * double gate (confirm_destructive + policy) and the audit ledger. Returns a
+       * refusal object for a non-mesh session so the daemon command surfaces a clean
+       * error (never silently writes to a non-worker PTY).
+       */
+      async injectKeys(items, opts = {}) {
+        if (!this.isMeshWorkerSession()) {
+          return { ok: false, refused: "not_mesh_worker", keys: [], hasDestructive: false };
+        }
+        if (typeof this.adapter.injectKeys !== "function") {
+          return { ok: false, refused: "unsupported", keys: [], hasDestructive: false };
+        }
+        return this.adapter.injectKeys(items, opts);
+      }
+      /**
+       * MESH-STALL-WATCH (feature 1: STALL detection). Status-agnostic stall
+       * watchdog for coordinator-spawned mesh worker sessions. Driven by the
+       * ProviderInstanceManager's existing 5s onTick loop (NO new timer) — see
+       * ProviderInstanceManager.startTicking. Reuses the adapter's raw-PTY-output
+       * clock (lastOutputAt, bumped on every output chunk) as the sole signal: if a
+       * live worker's screen has been byte-for-byte unchanged for
+       * MESH_WORKER_STALL_THRESHOLD_MS (180s), fire ONE informational
+       * monitor:no_progress event down the existing task_stalled ledger +
+       * pendingCoordinatorEvent path.
+       *
+       * Deliberately status-agnostic: it does NOT read getStatus()'s reported status
+       * (which would couple it to the generating-only StatusMonitor and the
+       * idle-timeout FSM). A normally-idle worker CAN trip this after 3 quiet
+       * minutes; that is accepted and surfaced as an informational stall (NOT a
+       * failure/auto-restart) so the coordinator judges. getStatus/getState are NOT
+       * called here, so status heartbeats never move the stall anchor.
+       *
+       * Anchoring: the episode arms against the current lastOutputAt; a worker that
+       * has emitted nothing yet (lastOutputAt === 0) anchors on this.startedAt (spawn
+       * time) so a silent spawn is still caught. Any new output re-arms the anchor
+       * and clears the emitted flag, so one continuous stall emits at most once and a
+       * later stall re-arms cleanly.
+       */
+      checkMeshWorkerStall(now = Date.now()) {
+        if (!this.isMeshWorkerSession()) {
+          this.meshStallAnchorAt = -1;
+          this.meshStallEmittedForAnchor = false;
+          return;
+        }
+        if (typeof this.adapter.isAlive === "function" && !this.adapter.isAlive()) {
+          this.meshStallAnchorAt = -1;
+          this.meshStallEmittedForAnchor = false;
+          return;
+        }
+        let lastOutputAt;
+        try {
+          const status = this.adapter.getStatus({ allowParse: false });
+          lastOutputAt = typeof status?.lastOutputAt === "number" && Number.isFinite(status.lastOutputAt) ? status.lastOutputAt : 0;
+        } catch {
+          return;
+        }
+        const anchor = lastOutputAt > 0 ? lastOutputAt : this.startedAt;
+        if (this.meshStallAnchorAt === -1) {
+          this.meshStallAnchorAt = anchor;
+          this.meshStallEmittedForAnchor = false;
+          return;
+        }
+        if (anchor > this.meshStallAnchorAt) {
+          this.meshStallAnchorAt = anchor;
+          this.meshStallEmittedForAnchor = false;
+          return;
+        }
+        if (this.meshStallEmittedForAnchor) return;
+        const stalledMs = now - this.meshStallAnchorAt;
+        if (stalledMs < _CliProviderInstance.MESH_WORKER_STALL_THRESHOLD_MS) return;
+        this.meshStallEmittedForAnchor = true;
+        let observedStatus = "unknown";
+        try {
+          const s2 = this.adapter.getStatus({ allowParse: false })?.status;
+          if (typeof s2 === "string" && s2) observedStatus = s2;
+        } catch {
+        }
+        if (this.isMeshWorkerSession()) {
+          traceMeshEventStage("fired", this.meshTraceCtx("monitor:no_progress"), "mesh_worker_stall_watchdog");
+        }
+        const stalledSec = Math.round(stalledMs / 1e3);
+        this.pushEvent({
+          event: "monitor:no_progress",
+          agentKey: `${this.type}:cli`,
+          elapsedSec: stalledSec,
+          timestamp: now,
+          // MESH-STALL-WATCH marker: buildMeshSystemMessage generalizes the
+          // coordinator message (generating-specific → "PTY output unchanged")
+          // when this is set, since this watchdog fires status-agnostically.
+          meshWorkerStall: true,
+          lastOutputAt: this.meshStallAnchorAt,
+          stalledMs,
+          observedStatus,
+          taskId: this.completingTurnTaskId()
+        });
+      }
       /**
        * AUTOAPPROVE-FLAP-RECUR (Fix A+B): how long a busy blip / modal scroll-out may
        * persist before the in-progress settle gate is torn down. For a delegated
@@ -78545,7 +79109,13 @@ ${body}
             // delegated session's inbox preview blank — or, for a LOCAL worktree session,
             // stuck on the dispatched user task. If the parser DID surface assistant text,
             // prefer it; only fall back to '' when no assistant summary can be derived.
-            finalSummary: blockReason.startsWith("parsed_status:") ? this.completionFinalSummary(this.adapter?.getScriptParsedStatus()?.messages, pending.turnStartedAt) ?? "" : this.completionFinalSummary(this.adapter?.getScriptParsedStatus()?.messages, pending.turnStartedAt),
+            // NOTIF Defect-B: completionFinalSummary is a point-sample of native-history/
+            // screen at THIS instant; on a native-source provider (antigravity) it can be
+            // empty at the forced-emit instant even though a prior poll already cached the
+            // real answer (lastCompletionSummary). Fall back to the cache so the notification
+            // carries the summary that mesh_read_chat.summary already shows — consistent with
+            // completionDiagnostic.finalAssistantPresent being credited from the same cache.
+            finalSummary: this.completionFinalSummary(this.adapter?.getScriptParsedStatus()?.messages, pending.turnStartedAt) || this.cachedCompletionSummaryContent() || (blockReason.startsWith("parsed_status:") ? "" : void 0),
             completionDiagnostic
           });
           this.completedDebouncePending = null;
@@ -79201,6 +79771,10 @@ ${buttons.join("\n")}`;
             this.completedDebouncePending = null;
             continue;
           }
+          if (me.type === "monitor:no_progress" && this.isMeshWorkerSession()) {
+            traceMeshEventDrop("mesh_worker_stall_watchdog_owns_no_progress", this.meshTraceCtx("monitor:no_progress"));
+            continue;
+          }
           this.pushEvent({ event: me.type, agentKey: me.agentKey, message: me.message, elapsedSec: me.elapsedSec, timestamp: me.timestamp });
         }
       }
@@ -90157,6 +90731,150 @@ ${e?.stderr || ""}`
         };
       }
     }
+    async function classifyPatchEquivalenceFailure(repoRoot, baseHead, branchHead, summary, options = {}) {
+      const targetBaseRef = options.targetBaseRef || baseHead;
+      const autoPublish = options.autoPublishSubmoduleMainCommits;
+      const evidence = {
+        baseHead,
+        branchHead,
+        mergeBase: summary.mergeBase,
+        expectedPatchId: summary.expectedPatchId,
+        actualPatchId: summary.actualPatchId,
+        patchIdEqual: !!summary.expectedPatchId && summary.expectedPatchId === summary.actualPatchId,
+        ...autoPublish !== void 0 ? { autoPublishSubmoduleMainCommits: autoPublish } : {}
+      };
+      try {
+        const git = (args) => (0, import_node_child_process6.execFileSync)(GIT2, args, {
+          cwd: repoRoot,
+          encoding: "utf8",
+          maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+          windowsHide: true
+        });
+        const gitOk = (args) => {
+          try {
+            git(args);
+            return true;
+          } catch {
+            return false;
+          }
+        };
+        let ahead = 0;
+        let behind = 0;
+        try {
+          const out = git(["rev-list", "--left-right", "--count", `${targetBaseRef}...${branchHead}`]).trim();
+          const [left, right] = out.split(/\s+/).map((n) => Number.parseInt(n, 10));
+          behind = Number.isFinite(left) ? left : 0;
+          ahead = Number.isFinite(right) ? right : 0;
+        } catch {
+        }
+        evidence.ahead = ahead;
+        evidence.behind = behind;
+        const baseIsAncestor = gitOk(["merge-base", "--is-ancestor", targetBaseRef, branchHead]);
+        evidence.baseDiverged = !baseIsAncestor;
+        let diffStat = "";
+        try {
+          if (summary.mergedTree) {
+            diffStat = git(["diff", "--stat", baseHead, summary.mergedTree]).trim().split("\n").filter(Boolean).slice(-1)[0] || "";
+          } else {
+            diffStat = git(["diff", "--stat", baseHead, branchHead]).trim().split("\n").filter(Boolean).slice(-1)[0] || "";
+          }
+        } catch {
+        }
+        if (diffStat) evidence.diffStat = diffStat;
+        const submoduleGitlinks = [];
+        try {
+          const nameStatus = git(["diff", "--name-only", "--diff-filter=d", baseHead, branchHead]).trim();
+          const changedPaths = nameStatus ? nameStatus.split("\n").map((p) => p.trim()).filter(Boolean) : [];
+          for (const p of changedPaths) {
+            let baseCommit;
+            let branchCommit;
+            try {
+              const baseLs = git(["ls-tree", baseHead, "--", p]).trim();
+              const branchLs = git(["ls-tree", branchHead, "--", p]).trim();
+              const isGitlink = /(^|\s)160000\s/.test(baseLs) || /(^|\s)160000\s/.test(branchLs);
+              if (!isGitlink) continue;
+              baseCommit = baseLs.split(/\s+/)[2];
+              branchCommit = branchLs.split(/\s+/)[2];
+            } catch {
+              continue;
+            }
+            const submoduleRepo = (0, import_path14.join)(repoRoot, p);
+            let fastForward;
+            let reachableFromOriginMain;
+            if (branchCommit) {
+              if (baseCommit) {
+                fastForward = execGitOk(submoduleRepo, ["merge-base", "--is-ancestor", baseCommit, branchCommit]);
+              }
+              reachableFromOriginMain = execGitOk(submoduleRepo, ["merge-base", "--is-ancestor", branchCommit, "refs/remotes/origin/main"]);
+            }
+            submoduleGitlinks.push({ path: p, baseCommit, branchCommit, fastForward, reachableFromOriginMain });
+          }
+        } catch {
+        }
+        if (submoduleGitlinks.length) evidence.submoduleGitlinks = submoduleGitlinks;
+        const gitlinkFf = summary.gitlinkTrivialFastForward;
+        const noResidualDiff = !evidence.diffStat && (!summary.actualPatchId || summary.actualPatchId === "");
+        if (ahead === 0 && behind === 0 && noResidualDiff) {
+          return {
+            detailedReason: "already_converged",
+            detailedReasonDescription: "Branch is already identical to the target base (ahead 0, behind 0, no residual diff); the merge would be a no-op.",
+            recommendedAction: "Treat as already converged \u2014 no merge needed. Verify with `git range-diff` / patch-id, then mark the branch merged (or clean up the worktree).",
+            evidence
+          };
+        }
+        const unreachable = submoduleGitlinks.filter((g) => g.reachableFromOriginMain === false);
+        if (unreachable.length > 0) {
+          const paths = unreachable.map((g) => g.path).join(", ");
+          return {
+            detailedReason: "submodule_unreachable",
+            detailedReasonDescription: `Submodule gitlink commit(s) not reachable from submodule origin/main (publish needed): ${paths}.`,
+            recommendedAction: `Publish the submodule commit(s) to submodule origin/main, then retry mesh_refine_node (policy allowAutoPublishSubmoduleMainCommits=${autoPublish === void 0 ? "unknown" : autoPublish}).`,
+            evidence
+          };
+        }
+        const changedGitlinks = submoduleGitlinks.length > 0;
+        const allGitlinksFf = changedGitlinks && submoduleGitlinks.every((g) => g.fastForward === true);
+        const gateSawUnresolvedGitlinkFf = gitlinkFf?.resolved === false && Array.isArray(gitlinkFf.gitlinks) && gitlinkFf.gitlinks.some((g) => g.fastForward);
+        if (baseIsAncestor && (evidence.patchIdEqual || allGitlinksFf || gateSawUnresolvedGitlinkFf)) {
+          return {
+            detailedReason: "trivial_ff_misjudgment",
+            detailedReasonDescription: "HEAD descends the target base and the patch content matches; the block is a submodule gitlink trivial fast-forward that merge-tree refused, not a real divergence.",
+            recommendedAction: "Converge via the strict fast-forward-only bypass (verify HEAD descends origin/main and patch-id equality, then merge --ff-only) instead of the refine gate.",
+            evidence
+          };
+        }
+        if (!baseIsAncestor) {
+          return {
+            detailedReason: "base_divergence",
+            detailedReasonDescription: `Worktree base has diverged from ${targetBaseRef} (HEAD is not a descendant; ahead ${ahead}, behind ${behind}).`,
+            recommendedAction: `Rebase the branch onto ${targetBaseRef}, then retry mesh_refine_node.`,
+            evidence
+          };
+        }
+        return {
+          detailedReason: "actual_patch_diff",
+          detailedReasonDescription: "The merge introduces content not equivalent to the branch's cumulative patch (expected tree vs actual merge diff differ).",
+          recommendedAction: "Manual review required \u2014 inspect the residual diff; the branch content is not patch-equivalent to a clean merge onto the base.",
+          evidence
+        };
+      } catch (e) {
+        evidence.classifierError = e?.message || String(e);
+        return {
+          detailedReason: "unclassified",
+          detailedReasonDescription: "Patch-equivalence sub-cause could not be classified (git inspection failed); see classifierError.",
+          recommendedAction: "Inspect the refineStages and patchEquivalence summary manually to determine the cause.",
+          evidence
+        };
+      }
+    }
+    function execGitOk(cwd, args) {
+      try {
+        (0, import_node_child_process6.execFileSync)(GIT2, args, { cwd, encoding: "utf8", maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES, windowsHide: true });
+        return true;
+      } catch {
+        return false;
+      }
+    }
     async function checkWorktreeChangesPatchEquivalentInRef(repoRoot, ref, worktreeHead) {
       const startedAt = Date.now();
       try {
@@ -91474,9 +92192,23 @@ ${mergeTreeErr?.stderr || ""}`;
             error: submoduleHintPatchEquivalence.error,
             actionableHint: submoduleHintPatchEquivalence.actionableHint
           });
+          const classification = await classifyPatchEquivalenceFailure(
+            repoRoot,
+            baseHead,
+            ctx.branchHead,
+            submoduleHintPatchEquivalence,
+            {
+              targetBaseRef: baseHead,
+              autoPublishSubmoduleMainCommits: resolveRefineryAutoPublishSubmoduleMainCommits(ctx.mesh, node.workspace).enabled
+            }
+          );
           return { kind: "terminal", result: {
             success: false,
             code: "patch_equivalence_failed",
+            detailedReason: classification.detailedReason,
+            detailedReasonDescription: classification.detailedReasonDescription,
+            recommendedAction: classification.recommendedAction,
+            evidence: classification.evidence,
             convergenceStatus: "blocked_review",
             error: "Refinery patch-equivalence preflight failed (submodule gitlink conflict); merge/refine was not attempted.",
             branch,
@@ -91616,7 +92348,7 @@ ${tail}` : ""
       return { kind: "continue", ctx };
     }
     async function refinePatchEquivalenceStage(self, ctx) {
-      const { meshId, nodeId, args, repoRoot, baseHead, branch, baseBranch, validationSummary, refineStages } = ctx;
+      const { meshId, nodeId, args, repoRoot, baseHead, branch, baseBranch, mesh, node, validationSummary, refineStages } = ctx;
       const branchHead = ctx.branchHead;
       const patchEquivalenceStarted = Date.now();
       const patchEquivalence = await runMeshRefinePatchEquivalenceGate(repoRoot, baseHead, branchHead);
@@ -91630,9 +92362,27 @@ ${tail}` : ""
       if (!patchEquivalence.equivalent) {
         const alreadyMergedViaOtherPath = !patchEquivalence.actualPatchId && !!patchEquivalence.expectedPatchId;
         if (!alreadyMergedViaOtherPath) {
+          const classification = await classifyPatchEquivalenceFailure(
+            repoRoot,
+            baseHead,
+            branchHead,
+            patchEquivalence,
+            {
+              targetBaseRef: baseHead,
+              autoPublishSubmoduleMainCommits: resolveRefineryAutoPublishSubmoduleMainCommits(mesh, node.workspace).enabled
+            }
+          );
+          recordMeshRefineStage(refineStages, "patch_equivalence_classification", "failed", patchEquivalenceStarted, {
+            detailedReason: classification.detailedReason,
+            recommendedAction: classification.recommendedAction
+          });
           return { kind: "terminal", result: {
             success: false,
             code: "patch_equivalence_failed",
+            detailedReason: classification.detailedReason,
+            detailedReasonDescription: classification.detailedReasonDescription,
+            recommendedAction: classification.recommendedAction,
+            evidence: classification.evidence,
             convergenceStatus: "blocked_review",
             error: "Refinery patch-equivalence preflight failed; merge/refine was not attempted.",
             branch,
@@ -92739,6 +93489,10 @@ ${e?.stderr || ""}`;
         };
         if (typeof result.error === "string") ctx.error = result.error;
         if (typeof result.blockedReason === "string") ctx.blockedReason = result.blockedReason;
+        if (typeof result.detailedReason === "string") ctx.detailedReason = result.detailedReason;
+        if (typeof result.detailedReasonDescription === "string") ctx.detailedReasonDescription = result.detailedReasonDescription;
+        if (typeof result.recommendedAction === "string") ctx.recommendedAction = result.recommendedAction;
+        if (result.evidence && typeof result.evidence === "object") ctx.evidence = result.evidence;
         if (stage === "patch_equivalence" && result.patchEquivalence) {
           const pe = result.patchEquivalence;
           ctx.details = {
@@ -92746,7 +93500,10 @@ ${e?.stderr || ""}`;
             actualPatchId: pe.actualPatchId,
             status: pe.status,
             actionableHint: pe.actionableHint,
-            error: pe.error
+            error: pe.error,
+            ...typeof result.detailedReason === "string" ? { detailedReason: result.detailedReason } : {},
+            ...typeof result.recommendedAction === "string" ? { recommendedAction: result.recommendedAction } : {},
+            ...result.evidence && typeof result.evidence === "object" ? { evidence: result.evidence } : {}
           };
         }
         if (stage === "submodule_reachability" && Array.isArray(result.unreachableSubmoduleCommits)) {
@@ -93704,7 +94461,22 @@ ${e?.stderr || ""}`;
       // worker session that reaches the wrong daemon used to fuzzy-inject the task body into that
       // daemon's own CLI session (TASKECHO coordinator self-echo). Forwarding to the owning daemon
       // delivers it to the real worker instead. (findAdapter is also fail-closed as the backstop.)
-      "agent_command"
+      "agent_command",
+      // read_terminal (MESH-READ-TERMINAL feature 2): mesh_read_terminal reads the CURRENT
+      // rendered PTY viewport of a specific worker session. The live viewport lives ONLY on the
+      // OWNING session's adapter, so when the target is a REMOTE worker the coordinator has no
+      // local instance and the handler would return 'Session not found' — the exact
+      // remote-worker forwarding gap of mission 6938892f. Forward it to the owning worker daemon
+      // so it reads its own live screen. (It is read-only; unlike the mutations above it makes no
+      // state change, but it is session-scoped identically and must reach the owning daemon.)
+      "read_terminal",
+      // send_keys (MESH-SEND-KEYS feature 3): mesh_send_keys injects a structured key sequence
+      // into a specific worker session's PTY. The live PTY lives ONLY on the OWNING session's
+      // adapter, so a remote-worker target must be forwarded to the owning daemon or the handler
+      // returns 'Session not found' (same class as mission 6938892f). Unlike read_terminal this
+      // MUTATES the worker PTY, so forwarding to the real owner (not a wrong local session) is
+      // doubly important. The daemon re-enforces the destructive-key confirm gate after the forward.
+      "send_keys"
     ]);
     function normalizeCommandSource(source) {
       switch (source) {
@@ -95827,7 +96599,13 @@ ${e?.stderr || ""}`;
         if (this.tickTimer) return;
         this.tickInterval = intervalMs || this.tickInterval;
         this.tickTimer = setInterval(async () => {
+          const now = Date.now();
           for (const [id, instance] of this.instances) {
+            try {
+              instance.checkMeshWorkerStall?.(now);
+            } catch (e) {
+              LOG2.warn("InstanceMgr", `[InstanceManager] Mesh stall check failed for ${id}: ${e.message}`);
+            }
             try {
               await instance.onTick();
             } catch (e) {
@@ -101276,7 +102054,7 @@ data: ${JSON.stringify(msg.data)}
         });
       }
     };
-    var import_crypto10 = require("crypto");
+    var import_crypto11 = require("crypto");
     var import_session_host_core11 = require_dist();
     var BASE_KEY_SEQUENCES = {
       enter: "\r",
@@ -101374,7 +102152,7 @@ data: ${JSON.stringify(msg.data)}
         const sessionId = String(options.sessionId || "").trim();
         if (!sessionId) throw new Error("sessionId is required");
         const mode = options.mode || "read";
-        const clientId = options.clientId || `raw-terminal-${process.pid}-${(0, import_crypto10.randomUUID)().slice(0, 8)}`;
+        const clientId = options.clientId || `raw-terminal-${process.pid}-${(0, import_crypto11.randomUUID)().slice(0, 8)}`;
         const client = options.client || new import_session_host_core11.SessionHostClient({ endpoint: options.endpoint });
         await client.connect();
         const attachResponse = await client.request({