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

package/dist/index.mjs

@@ -119,6 +119,15 @@ function resolveDelegatedWorkerAutoApprove(meshPolicy, nodePolicy) {
   }
   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;
@@ -414,10 +423,10 @@ function readInjected(value) {
 }
 function getDaemonBuildInfo() {
   if (cached) return cached;
-  const commit = readInjected(true ? "178a437592e2f9544675a54768b48281804bdddb" : void 0) ?? "unknown";
-  const commitShort = readInjected(true ? "178a4375" : void 0) ?? (commit !== "unknown" ? commit.slice(0, 7) : "unknown");
-  const version = 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:25:41.391Z" : 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 version = 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:57:39.144Z" : void 0);
   cached = builtAt ? { commit, commitShort, version, builtAt } : { commit, commitShort, version };
   return cached;
 }
@@ -2982,6 +2991,8 @@ var init_dist = __esm({
       "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",
@@ -4128,6 +4139,8 @@ var init_coordinator_prompt = __esm({
 | \`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 |
@@ -8785,6 +8798,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") {
@@ -12582,6 +12602,82 @@ function sanitizeTerminalText(str) {
   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);
@@ -12783,7 +12879,7 @@ function normalizeCliProviderForRuntime(raw) {
     }
   };
 }
-var TerminalTranscriptAccumulator, buildCliSpawnEnv;
+var TerminalTranscriptAccumulator, MESH_SEND_KEY_ENCODING, MESH_DESTRUCTIVE_KEYS, MESH_SEND_KEYS_MAX_ITEMS, MESH_SEND_KEYS_MAX_TEXT_BYTES, buildCliSpawnEnv;
 var init_provider_cli_shared = __esm({
   "src/cli-adapters/provider-cli-shared.ts"() {
     "use strict";
@@ -12944,6 +13040,20 @@ var init_provider_cli_shared = __esm({
         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 = sanitizeSpawnEnv;
   }
 });
@@ -18074,6 +18184,10 @@ var init_terminal_screen = __esm({
       getCursorPosition() {
         return this.terminal.getCursorPosition();
       }
+      /** Current viewport dimensions (cols × rows). */
+      getSize() {
+        return { cols: this.cols, rows: this.rows };
+      }
       dispose() {
         this.terminal.dispose();
       }
@@ -26820,6 +26934,7 @@ __export(provider_cli_adapter_exports, {
   normalizeCliProviderForRuntime: () => normalizeCliProviderForRuntime
 });
 import * as os16 from "os";
+import { createHash as createHash4 } from "crypto";
 import { DEFAULT_SESSION_HOST_COLS as DEFAULT_SESSION_HOST_COLS4, DEFAULT_SESSION_HOST_ROWS as DEFAULT_SESSION_HOST_ROWS4 } from "@adhdev/session-host-core";
 function appendBoundedText(current, chunk, maxChars) {
   if (!chunk) return current.length <= maxChars ? current : current.slice(-maxChars);
@@ -27033,6 +27148,11 @@ var init_provider_cli_adapter = __esm({
       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
@@ -28611,6 +28731,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 hash = createHash4("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
+        };
+      }
+      /**
+       * 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) {
+          LOG.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) {
+          LOG.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);
+        LOG.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();
       }
@@ -39406,6 +39623,63 @@ function handlePtyResize(_h, args) {
   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" };
+  }
+  LOG.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) {
+      LOG.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 };
+    }
+    LOG.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 || {};
@@ -40263,6 +40537,12 @@ var DaemonCommandHandler = class {
         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);
@@ -43009,6 +43289,12 @@ var TerminalAdapter = class {
     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);
@@ -43347,6 +43633,9 @@ var FsmDriver = class {
   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. */
@@ -45384,8 +45673,10 @@ function readTailJsonlLines(filePath, maxBytes) {
 }
 
 // src/providers/spec/cli-adapter.ts
+init_provider_cli_shared();
 init_logger();
 import * as fs20 from "fs";
+import { createHash as createHash5 } from "crypto";
 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, "");
 }
@@ -45563,6 +45854,105 @@ var SpecCliAdapter = class _SpecCliAdapter {
   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 hash = createHash5("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
+    };
+  }
+  /**
+   * 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) {
+      LOG.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 });
+    LOG.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;
   }
@@ -46875,6 +47265,15 @@ var CliProviderInstance = class _CliProviderInstance {
    * 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 = [];
@@ -46888,6 +47287,16 @@ var CliProviderInstance = class _CliProviderInstance {
   // 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
@@ -47811,6 +48220,25 @@ var CliProviderInstance = class _CliProviderInstance {
     }
     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)) {
@@ -47874,12 +48302,19 @@ var CliProviderInstance = class _CliProviderInstance {
     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,
@@ -47887,8 +48322,9 @@ var CliProviderInstance = class _CliProviderInstance {
       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,
@@ -48066,6 +48502,128 @@ var CliProviderInstance = class _CliProviderInstance {
   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
@@ -48371,7 +48929,13 @@ var CliProviderInstance = class _CliProviderInstance {
         // 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;
@@ -49027,6 +49591,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 });
     }
   }
@@ -60068,6 +60636,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) => execFileSync7(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 = pathJoin2(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 {
+    execFileSync7(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 {
@@ -61387,9 +62099,23 @@ async function refineSyncBaseStage(self, ctx) {
         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,
@@ -61529,7 +62255,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);
@@ -61543,9 +62269,27 @@ async function refinePatchEquivalenceStage(self, ctx) {
   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,
@@ -62652,6 +63396,10 @@ async function finishMeshRefineJob(self, handle, args) {
     };
     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 = {
@@ -62659,7 +63407,10 @@ async function finishMeshRefineJob(self, handle, args) {
         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)) {
@@ -63629,7 +64380,22 @@ var MESH_FORWARDABLE_SESSION_COMMANDS = /* @__PURE__ */ new Set([
   // 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) {
@@ -65774,7 +66540,13 @@ var ProviderInstanceManager = class {
     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) {
+          LOG.warn("InstanceMgr", `[InstanceManager] Mesh stall check failed for ${id}: ${e.message}`);
+        }
         try {
           await instance.onTick();
         } catch (e) {
@@ -72920,6 +73692,7 @@ export {
   resetConfig,
   resetDebugRuntimeConfig,
   resetState,
+  resolveAllowSendKeysDestructive,
   resolveAutoConvergeCodeChange,
   resolveChatMessageKind,
   resolveConvergeRequiredTags,