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

package/dist/index.js

@@ -124,6 +124,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;
@@ -419,10 +428,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 ? "3fc4f272513b6f628ec1732ef57d9ed94e08b8ff" : void 0) ?? "unknown";
+  const commitShort = readInjected(true ? "3fc4f272" : void 0) ?? (commit !== "unknown" ? commit.slice(0, 7) : "unknown");
+  const version = readInjected(true ? "0.9.82-rc.553" : void 0) ?? readInjected(typeof process !== "undefined" ? process.env?.ADHDEV_PKG_VERSION : void 0) ?? "unknown";
+  const builtAt = readInjected(true ? "2026-07-17T06:04:22.090Z" : void 0);
   cached = builtAt ? { commit, commitShort, version, builtAt } : { commit, commitShort, version };
   return cached;
 }
@@ -2988,6 +2997,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",
@@ -4134,6 +4145,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 |
@@ -8792,6 +8805,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") {
@@ -12584,6 +12604,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);
@@ -12785,7 +12881,7 @@ function normalizeCliProviderForRuntime(raw) {
     }
   };
 }
-var os5, path11, TerminalTranscriptAccumulator, buildCliSpawnEnv;
+var os5, path11, 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";
@@ -12948,6 +13044,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 = import_session_host_core2.sanitizeSpawnEnv;
   }
 });
@@ -18072,6 +18182,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();
       }
@@ -26827,11 +26941,12 @@ function appendBoundedText(current, chunk, maxChars) {
   if (current.length <= keepFromCurrent) return current + chunk;
   return current.slice(-keepFromCurrent) + chunk;
 }
-var os16, import_session_host_core6, FORCE_SUBMIT_SETTLE_MS, ProviderCliAdapter;
+var os16, import_crypto10, import_session_host_core6, FORCE_SUBMIT_SETTLE_MS, ProviderCliAdapter;
 var init_provider_cli_adapter = __esm({
   "src/cli-adapters/provider-cli-adapter.ts"() {
     "use strict";
     os16 = __toESM(require("os"));
+    import_crypto10 = require("crypto");
     init_logger();
     init_debug_config();
     init_terminal_screen();
@@ -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 = (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
+        };
+      }
+      /**
+       * 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();
       }
@@ -29436,6 +29653,7 @@ __export(index_exports, {
   resetConfig: () => resetConfig,
   resetDebugRuntimeConfig: () => resetDebugRuntimeConfig,
   resetState: () => resetState,
+  resolveAllowSendKeysDestructive: () => resolveAllowSendKeysDestructive,
   resolveAutoConvergeCodeChange: () => resolveAutoConvergeCodeChange,
   resolveChatMessageKind: () => resolveChatMessageKind,
   resolveConvergeRequiredTags: () => resolveConvergeRequiredTags,
@@ -39838,6 +40056,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 || {};
@@ -40695,6 +40970,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);
@@ -47307,6 +47588,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 = [];
@@ -47320,6 +47610,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
@@ -48498,6 +48798,124 @@ 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;
+    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 };
+    }
+    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 (!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
@@ -49459,6 +49877,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 });
     }
   }
@@ -64056,7 +64478,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) {
@@ -66201,7 +66638,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) {
@@ -71674,7 +72117,7 @@ var SessionHostPtyTransportFactory = class {
 };
 
 // src/cli-adapters/raw-terminal-io.ts
-var import_crypto10 = require("crypto");
+var import_crypto11 = require("crypto");
 var import_session_host_core11 = require("@adhdev/session-host-core");
 var BASE_KEY_SEQUENCES = {
   enter: "\r",
@@ -71772,7 +72215,7 @@ var RawTerminalAttachment = class _RawTerminalAttachment {
     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({
@@ -73338,6 +73781,7 @@ var V1_CONTRACT_VERSION = "1.0.0";
   resetConfig,
   resetDebugRuntimeConfig,
   resetState,
+  resolveAllowSendKeysDestructive,
   resolveAutoConvergeCodeChange,
   resolveChatMessageKind,
   resolveConvergeRequiredTags,