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

package/src/commands/stream-commands.ts

@@ -134,6 +134,131 @@ export function handlePtyResize(_h: CommandHelpers, args: any): CommandResult {
     return { success: false, error: 'PTY resize temporarily disabled', code: 'PTY_RESIZE_DISABLED' };
 }
 
+interface TerminalSnapshotInstance extends ProviderInstance {
+    getTerminalScreenSnapshot?(maxBytes?: number): {
+        text: string;
+        cursor: { col: number; row: number };
+        cols: number;
+        rows: number;
+        truncated: boolean;
+        originalBytes: number;
+        returnedBytes: number;
+        hash: string;
+    } | null;
+}
+
+/**
+ * MESH-READ-TERMINAL (feature 2: RAW terminal read). Reads the CURRENT rendered
+ * PTY viewport of a specific mesh worker session for the mesh_read_terminal tool.
+ *
+ * This is the daemon-side `read_terminal` verb. It runs BOTH on the coordinator
+ * (for a locally-hosted worker) and, after router forwarding
+ * (MESH_FORWARDABLE_SESSION_COMMANDS + _meshDirectDispatch), on the OWNING remote
+ * worker daemon — where the live viewport actually exists. The instance's
+ * getTerminalScreenSnapshot() is gated on isMeshWorkerSession() (returns null for
+ * a non-mesh session), which the MCP layer complements with a mesh/session/node
+ * ownership cross-check. SECURITY: the raw viewport can contain tokens / args /
+ * env / user data — never logged here (only its byte size / truncation flag are).
+ */
+export function handleReadTerminal(h: CommandHelpers, args: any): CommandResult {
+    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) as TerminalSnapshotInstance | undefined;
+    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
+        : undefined;
+    const snapshot = instance.getTerminalScreenSnapshot(requestedMaxBytes);
+    if (!snapshot) {
+        // getTerminalScreenSnapshot returns null when the session is NOT a mesh
+        // worker — the raw-viewport read is scoped to coordinator-delegated workers.
+        return { success: false, error: 'read_terminal is only available for coordinator-spawned mesh worker sessions' };
+    }
+    // Log size/truncation ONLY — never the screen text (may carry secrets).
+    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 };
+}
+
+interface KeyInjectableInstance extends ProviderInstance {
+    injectKeys?(
+        items: Array<{ text: string } | { key: string }>,
+        opts?: { allowModalOverride?: boolean },
+    ): Promise<
+        | { ok: true; keys: string[]; hasDestructive: boolean; submits: boolean; bytes: number }
+        | { ok: false; refused: string; keys: string[]; hasDestructive: boolean }
+    >;
+}
+
+/**
+ * MESH-SEND-KEYS (feature 3: key injection). Inject a structured key sequence into
+ * a specific mesh worker session's PTY for the mesh_send_keys tool.
+ *
+ * Daemon-side `send_keys` verb. Like read_terminal it runs on the coordinator for
+ * a local worker and, after router forwarding (MESH_FORWARDABLE_SESSION_COMMANDS +
+ * _meshDirectDispatch), on the OWNING remote worker daemon. The instance's
+ * injectKeys() is gated on isMeshWorkerSession(); the MCP layer complements it with
+ * mesh/session/node ownership + the destructive-key double gate (confirm_destructive
+ * + mesh policy) + audit ledger.
+ *
+ * Defense-in-depth here: even though the MCP layer gates destructive keys, the
+ * daemon re-enforces confirm_destructive so a direct/forwarded send_keys that
+ * contains CTRL_C/ESC without confirm is refused at the boundary too.
+ * SECURITY: never logs the literal text body (only key enums / byte counts).
+ */
+export async function handleSendKeys(h: CommandHelpers, args: any): Promise<CommandResult> {
+    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) as KeyInjectableInstance | undefined;
+    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' };
+    }
+
+    // Defense-in-depth destructive gate: refuse CTRL_C/ESC without confirm_destructive
+    // even at the daemon boundary (the MCP layer is the primary gate + policy check).
+    const DESTRUCTIVE = new Set(['CTRL_C', 'ESC']);
+    const hasDestructiveRequested = items.some((it: any) => 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: any) {
+        // Encode/validation errors (unknown key, over-limit) surface as a clean failure.
+        return { success: false, error: `send_keys: ${e?.message || String(e)}` };
+    }
+}
+
 // ─── Provider Settings ────────────────────────
 
 export function handleGetProviderSettings(h: CommandHelpers, args: any): CommandResult {

package/src/index.ts

@@ -143,6 +143,7 @@ export type {
 export {
   DEFAULT_MESH_POLICY,
   resolveDelegatedWorkerAutoApprove,
+  resolveAllowSendKeysDestructive,
   resolveMagiSessionCleanupMode,
   magiAutoLaunchedSessionCleanupDecision,
   MESH_SCHEDULING_STRATEGIES,

package/src/mesh/coordinator-prompt.ts

@@ -743,6 +743,8 @@ const TOOLS_SECTION = `## Available Tools
 | \`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 — 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 — 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 — 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 — 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 — answer "what happened on node X / what failed since T" without scanning transcripts |
 | \`mesh_reconcile_ledger\` | Reconcile daemon-local ledgers over P2P — import missing entries from remote nodes into the coordinator local ledger |

package/src/mesh/mesh-events-utils.ts

@@ -356,6 +356,21 @@ export function buildMeshSystemMessage(args: {
         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') {
+        // MESH-STALL-WATCH (feature 1: STALL detection): the status-agnostic stall
+        // watchdog fires this event regardless of the reported status — a worker's
+        // raw PTY output was byte-for-byte unchanged past the stall bound. Surface
+        // the generalized "output unchanged" wording (with the observed status,
+        // stalled duration and taskId as context) and make explicit this is
+        // INFORMATIONAL — a quiet/idle worker can trip it; it is NOT a failure or
+        // auto-restart. The generating-only StatusMonitor copy keeps its original
+        // phrasing.
+        if (args.metadataEvent.meshWorkerStall === true) {
+            const observedStatus = readNonEmptyString(args.metadataEvent.observedStatus);
+            const stalledMs = typeof args.metadataEvent.stalledMs === 'number' ? args.metadataEvent.stalledMs : undefined;
+            const stalledSuffix = stalledMs !== undefined ? ` for ${Math.round(stalledMs / 1000)}s` : '';
+            const statusSuffix = observedStatus ? ` (observed status: ${observedStatus})` : '';
+            return `[System] ${args.nodeLabel}: PTY output unchanged${stalledSuffix}${statusSuffix}${metadata}. This is an informational stall — 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') {

package/src/mesh/mesh-ledger.ts

@@ -82,6 +82,12 @@ export type MeshLedgerKind =
     // magi_synthesis  payload: { source:'magi', consensusGroupId, missionId?, panel?, question?, synthesis }
     | 'magi_dispatched'
     | 'magi_synthesis'
+    // MESH-SEND-KEYS (feature 3): audit trail for coordinator PTY key injections
+    // via mesh_send_keys. Records the key ENUMS, destructive flag and result —
+    // NEVER the literal text body (may carry tokens / user data).
+    // payload: { keys: string[], hasDestructive: boolean, result: 'injected'|'refused'|'error',
+    //            refused?: string, submits?: boolean, confirmDestructive?: boolean }
+    | 'key_injection'
     ;
 
 export interface MeshLedgerEntry {

package/src/providers/cli-provider-instance.ts

@@ -16,6 +16,7 @@ import { normalizeInteractivePrompt, normalizeInteractivePromptResponse, type In
 import { ProviderCliAdapter } from '../cli-adapters/provider-cli-adapter.js';
 import { shortHash } from '../system/hash.js';
 import type { CliProviderModule } from '../cli-adapters/provider-cli-adapter.js';
+import type { MeshSendKeyItem, MeshSendKeyName } from '../cli-adapters/provider-cli-shared.js';
 import { createCliAdapter } from './spec/route.js';
 import type { PtyRuntimeMetadata, PtyTransportFactory } from '../cli-adapters/pty-transport.js';
 import { StatusMonitor } from './status-monitor.js';
@@ -252,6 +253,16 @@ export class CliProviderInstance implements ProviderInstance {
      */
     private static readonly APPROVAL_RESUME_GRACE_MS = 18_000;
 
+    // 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.
+    private static readonly MESH_WORKER_STALL_THRESHOLD_MS = 180_000;
+
     private adapter: ProviderCliAdapter;
     private context: InstanceContext | null = null;
     private events: ProviderEvent[] = [];
@@ -265,6 +276,16 @@ export class CliProviderInstance implements ProviderInstance {
     // first sets it; the other becomes a no-op.
     private agentReadyEmitted = false;
     private generatingStartedAt: number = 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.
+    private meshStallAnchorAt = -1;
+    private 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
@@ -1966,6 +1987,167 @@ export class CliProviderInstance implements ProviderInstance {
             || 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?: number): {
+        text: string;
+        cursor: { col: number; row: number };
+        cols: number;
+        rows: number;
+        truncated: boolean;
+        originalBytes: number;
+        returnedBytes: number;
+        hash: string;
+    } | null {
+        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: MeshSendKeyItem[],
+        opts: { allowModalOverride?: boolean } = {},
+    ): Promise<
+        | { ok: true; keys: MeshSendKeyName[]; hasDestructive: boolean; submits: boolean; bytes: number }
+        | { ok: false; refused: 'submit_race' | 'actionable_modal' | 'not_mesh_worker'; keys: MeshSendKeyName[]; hasDestructive: boolean }
+    > {
+        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: number = Date.now()): void {
+        if (!this.isMeshWorkerSession()) {
+            // Not (or no longer) a mesh worker — drop any armed episode so a session
+            // whose mesh markers were detached does not carry a stale anchor.
+            this.meshStallAnchorAt = -1;
+            this.meshStallEmittedForAnchor = false;
+            return;
+        }
+        if (!this.adapter.isAlive()) {
+            // Dead PTY: nothing to watch. agent:stopped covers the exit; re-arm on
+            // the next live session so a restart starts a fresh episode.
+            this.meshStallAnchorAt = -1;
+            this.meshStallEmittedForAnchor = false;
+            return;
+        }
+
+        let lastOutputAt: number;
+        try {
+            // allowParse:false — a cheap status read that must NOT trigger parsing
+            // and must NOT mutate lastOutputAt (getState/getStatus never bump it).
+            const status = this.adapter.getStatus({ allowParse: false }) as { lastOutputAt?: unknown };
+            lastOutputAt = typeof status?.lastOutputAt === 'number' && Number.isFinite(status.lastOutputAt)
+                ? status.lastOutputAt
+                : 0;
+        } catch {
+            return; // defensive: a failed status read just skips this tick
+        }
+
+        // The anchor is the last raw output; before any output, the spawn time so a
+        // silent worker is still caught.
+        const anchor = lastOutputAt > 0 ? lastOutputAt : this.startedAt;
+
+        if (this.meshStallAnchorAt === -1) {
+            // First observation this session — arm against the current anchor.
+            this.meshStallAnchorAt = anchor;
+            this.meshStallEmittedForAnchor = false;
+            return;
+        }
+
+        if (anchor > this.meshStallAnchorAt) {
+            // New output advanced the clock — re-arm the episode against it.
+            this.meshStallAnchorAt = anchor;
+            this.meshStallEmittedForAnchor = false;
+            return;
+        }
+
+        if (this.meshStallEmittedForAnchor) return; // already fired for this stall
+
+        const stalledMs = now - this.meshStallAnchorAt;
+        if (stalledMs < CliProviderInstance.MESH_WORKER_STALL_THRESHOLD_MS) return;
+
+        this.meshStallEmittedForAnchor = true;
+
+        // observedStatus is surfaced as context only — deliberately NOT stamped as
+        // the reconciliation-triggering `status` field (which would let
+        // buildNoProgressCompletionReconciliation mistake an idle stall for a
+        // completion). See mesh-events-stale.buildNoProgressCompletionReconciliation.
+        let observedStatus = 'unknown';
+        try {
+            const s = (this.adapter.getStatus({ allowParse: false }) as { status?: unknown })?.status;
+            if (typeof s === 'string' && s) observedStatus = s;
+        } catch { /* best-effort context only */ }
+
+        if (this.isMeshWorkerSession()) {
+            traceMeshEventStage('fired', this.meshTraceCtx('monitor:no_progress'), 'mesh_worker_stall_watchdog');
+        }
+
+        const stalledSec = Math.round(stalledMs / 1000);
+        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
@@ -3527,6 +3709,20 @@ export class CliProviderInstance implements ProviderInstance {
                 this.completedDebouncePending = null;
                 continue;
             }
+            // MESH-STALL-WATCH dedupe: for a coordinator-spawned mesh worker the
+            // status-agnostic stall watchdog (checkMeshWorkerStall) owns the
+            // monitor:no_progress alert. The StatusMonitor here fires its OWN
+            // generating-only no-progress on the SAME 180s bound, which would
+            // double-emit into the task_stalled ledger + coordinator inbox for the
+            // one stall. Suppress the StatusMonitor's copy for mesh workers only —
+            // the completion-reconciliation branch above (which turns a no-progress
+            // WITH final-assistant into a real completion) still runs, so genuine
+            // idle-reconciled completions are unaffected. Non-mesh sessions keep the
+            // original StatusMonitor behavior untouched.
+            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 });
         }
     }

package/src/providers/provider-instance-manager.ts

@@ -211,7 +211,18 @@ export class ProviderInstanceManager {
         this.tickInterval = intervalMs || this.tickInterval;
 
         this.tickTimer = setInterval(async () => {
+            const now = Date.now();
             for (const [id, instance] of this.instances) {
+                // MESH-STALL-WATCH (feature 1: STALL detection): a status-agnostic
+                // watchdog for coordinator-spawned mesh worker sessions, driven by
+                // THIS existing 5s tick (no separate timer). Cheap (reads the
+                // adapter's raw-output clock only) and a no-op for non-mesh /
+                // non-CLI instances, so it runs before the per-instance onTick.
+                try {
+                    instance.checkMeshWorkerStall?.(now);
+                } catch (e) {
+                    LOG.warn('InstanceMgr', `[InstanceManager] Mesh stall check failed for ${id}: ${(e as Error).message}`);
+                }
                 try {
                     await instance.onTick();
                 } catch (e) {

package/src/providers/provider-instance.ts

@@ -195,6 +195,16 @@ export interface ProviderInstance {
  /** Tick — periodic status refresh (IDE: readChat, Extension: stream collection) */
     onTick(): Promise<void>;
 
+    /**
+     * MESH-STALL-WATCH (feature 1: STALL detection). Status-agnostic stall
+     * watchdog for coordinator-spawned mesh worker sessions, invoked from the
+     * ProviderInstanceManager's existing tick loop (no separate timer). Fires ONE
+     * informational monitor:no_progress event when a live worker's raw PTY output
+     * has been unchanged past the stall threshold. Optional — only CLI instances
+     * (which own a PTY / lastOutputAt clock) implement it; a no-op elsewhere.
+     */
+    checkMeshWorkerStall?(now?: number): void;
+
  /** Return current status */
     getState(): ProviderState;
 

package/src/repo-mesh-types.ts

@@ -350,6 +350,17 @@ export interface RepoMeshPolicy {
      * A node policy may override this per-node (RepoMeshNodePolicy.delegatedWorkerAutoApprove).
      */
     delegatedWorkerAutoApprove?: boolean;
+    /**
+     * MESH-SEND-KEYS (feature 3): opt-in to allow the coordinator to inject
+     * DESTRUCTIVE keys (CTRL_C / ESC) into a worker PTY via mesh_send_keys. These
+     * can kill or derail the worker process, and delegatedWorkerAutoApprove is a
+     * TOOL-CONSENT policy, not a PTY-input authorization — so a destructive key
+     * injection additionally requires this explicit mesh-owner opt-in AND a
+     * per-call confirm_destructive=true. Defaults to false (destructive keys
+     * refused). Non-destructive keys (text/ENTER/arrows/TAB/BACKSPACE) are
+     * unaffected. A node policy may override per-node.
+     */
+    allowSendKeysDestructive?: boolean;
     /**
      * What to do with delegated session-host records for a node when it is removed.
      * Defaults to 'preserve' so completed work can be reviewed later and live
@@ -473,6 +484,11 @@ export interface RepoMeshNodePolicy {
      * precedence over the mesh-level policy for worker sessions launched onto this node.
      */
     delegatedWorkerAutoApprove?: boolean;
+    /**
+     * MESH-SEND-KEYS (feature 3): per-node override for
+     * RepoMeshPolicy.allowSendKeysDestructive.
+     */
+    allowSendKeysDestructive?: boolean;
     /**
      * Optional associated/external repos that must be checked alongside this node.
      * These are explicit policy/config entries only; Repo Mesh does not auto-discover
@@ -734,6 +750,25 @@ export function resolveDelegatedWorkerAutoApprove(
     return true;
 }
 
+/**
+ * MESH-SEND-KEYS (feature 3): resolve whether DESTRUCTIVE key injection
+ * (CTRL_C/ESC via mesh_send_keys) is permitted for a node. Node policy overrides
+ * mesh policy; DEFAULTS TO FALSE (fail-closed) — a destructive key still requires
+ * a per-call confirm_destructive=true on top of this opt-in.
+ */
+export function resolveAllowSendKeysDestructive(
+    meshPolicy?: Pick<RepoMeshPolicy, 'allowSendKeysDestructive'> | null,
+    nodePolicy?: Pick<RepoMeshNodePolicy, 'allowSendKeysDestructive'> | null,
+): boolean {
+    if (typeof nodePolicy?.allowSendKeysDestructive === 'boolean') {
+        return nodePolicy.allowSendKeysDestructive;
+    }
+    if (typeof meshPolicy?.allowSendKeysDestructive === 'boolean') {
+        return meshPolicy.allowSendKeysDestructive;
+    }
+    return false;
+}
+
 /**
  * Resolve the enforced per-(node, provider) maxParallel cap from a node's resolved
  * capability slots, or undefined when no matching slot declares a finite cap. Used