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

package/src/cli-adapters/provider-cli-shared.ts

@@ -482,6 +482,178 @@ export function sanitizeTerminalText(str: string): string {
     return stripTerminalNoise(stripAnsi(accumulator.append(str)));
 }
 
+// ─── MESH-SEND-KEYS (feature 3: key injection) ─────────────────────────────
+//
+// The coordinator injects a STRUCTURED key sequence into a worker PTY — never
+// raw/base64 bytes (auditability + safety). Each item is either literal UTF-8
+// `text` or a named `key` from this closed enum; the encoder maps each key to its
+// exact terminal byte sequence. Keeping raw bytes out of the input surface means
+// the ledger can record the key ENUM (not the body text) and the destructive-key
+// gate can reason about a small, known set.
+
+/** Named PTY keys the send-keys tool accepts (closed enum). */
+export type MeshSendKeyName =
+    | 'ENTER' | 'ESC' | 'CTRL_C'
+    | 'UP' | 'DOWN' | 'LEFT' | 'RIGHT'
+    | 'TAB' | 'BACKSPACE';
+
+/** Exact terminal byte sequence for each named key. */
+export const MESH_SEND_KEY_ENCODING: Record<MeshSendKeyName, string> = {
+    ENTER: '\r',
+    ESC: '\x1b',
+    CTRL_C: '\x03',
+    UP: '\x1b[A',
+    DOWN: '\x1b[B',
+    RIGHT: '\x1b[C',
+    LEFT: '\x1b[D',
+    TAB: '\t',
+    BACKSPACE: '\x7f',
+};
+
+// Destructive keys: they can kill or derail the worker process. CTRL_C sends
+// SIGINT (kills the running command / the agent's turn); ESC dismisses / cancels
+// modals and pickers. delegatedWorkerAutoApprove is a TOOL-CONSENT policy, NOT a
+// PTY-input authorization — so these MUST NOT ride the auto-approve pathway; they
+// require an explicit confirm + mesh-policy opt-in. Text / ENTER / arrows / TAB /
+// BACKSPACE are non-destructive and need no confirm.
+export const MESH_DESTRUCTIVE_KEYS: ReadonlySet<MeshSendKeyName> = new Set<MeshSendKeyName>(['CTRL_C', 'ESC']);
+
+export type MeshSendKeyItem = { text: string } | { key: MeshSendKeyName };
+
+export interface MeshSendKeysEncodeResult {
+    /** The concatenated byte sequence to write to the PTY (single atomic write). */
+    sequence: string;
+    /** Named keys present, in order (for audit — text bodies are NOT recorded). */
+    keys: MeshSendKeyName[];
+    /** True if any item is a destructive key (CTRL_C / ESC). */
+    hasDestructive: boolean;
+    /** True if the sequence submits (ends with an ENTER/CR) — informational. */
+    submits: boolean;
+}
+
+/** Per-call limits (auditability + safety — no unbounded blast). */
+export const MESH_SEND_KEYS_MAX_ITEMS = 64;
+export const MESH_SEND_KEYS_MAX_TEXT_BYTES = 4096;
+
+/**
+ * Validate + encode a structured key sequence into the exact bytes to write.
+ * Throws on an invalid key name, an over-limit item count, or an over-limit
+ * total text byte length. text+ENTER (or any text followed by ENTER) is encoded
+ * as ONE contiguous string so the caller can submit it in a single atomic write
+ * — no interleaving between the text and its submit key.
+ */
+export function encodeMeshSendKeys(items: MeshSendKeyItem[]): MeshSendKeysEncodeResult {
+    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: string[] = [];
+    const keys: MeshSendKeyName[] = [];
+    let hasDestructive = false;
+    let submits = false;
+    let textBytes = 0;
+    for (const item of items) {
+        if (item && typeof (item as { text?: unknown }).text === 'string') {
+            const text = (item as { text: string }).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; // literal text after a submit re-opens the line
+            continue;
+        }
+        const keyName = item && typeof (item as { key?: unknown }).key === 'string'
+            ? (item as { key: string }).key
+            : '';
+        if (!(keyName in MESH_SEND_KEY_ENCODING)) {
+            throw new Error(`send_keys: unknown key '${keyName}'`);
+        }
+        const key = keyName as MeshSendKeyName;
+        parts.push(MESH_SEND_KEY_ENCODING[key]);
+        keys.push(key);
+        if (MESH_DESTRUCTIVE_KEYS.has(key)) hasDestructive = true;
+        submits = key === 'ENTER';
+    }
+    return { sequence: parts.join(''), keys, hasDestructive, submits };
+}
+
+/**
+ * MESH-READ-TERMINAL (feature 2): result of a byte-bounded, bottom-tail terminal
+ * screen truncation. The bound is in BYTES (UTF-8), not characters, because a
+ * screen full of multi-byte glyphs can blow past an MCP payload cap even when the
+ * character count looks safe. The bottom (tail) of the screen is preserved — the
+ * prompt, an active modal and the most recent output all live at the bottom — so
+ * a truncated read still shows the coordinator the actionable frame.
+ */
+export interface ByteTailTruncation {
+    text: string;
+    truncated: boolean;
+    /** UTF-8 byte length of the full input before truncation. */
+    originalBytes: number;
+    /** UTF-8 byte length of the returned (possibly truncated) text. */
+    returnedBytes: number;
+}
+
+/**
+ * Truncate `text` to at most `maxBytes` UTF-8 bytes, preserving whole lines from
+ * the BOTTOM up (the prompt/modal/recent output). Never splits a line and never
+ * splits a UTF-8 code point (whole-line granularity guarantees valid UTF-8). If
+ * even the single last line exceeds the bound, that line is hard-clipped on a
+ * safe UTF-8 boundary from its END so the tail is still returned intact-ish.
+ */
+export function truncateToByteTailByLine(text: string, maxBytes: number): ByteTailTruncation {
+    const input = String(text ?? '');
+    const originalBytes = Buffer.byteLength(input, 'utf8');
+    if (originalBytes <= maxBytes) {
+        return { text: input, truncated: false, originalBytes, returnedBytes: originalBytes };
+    }
+    // Split on newlines, keeping the newline characters so reassembly is exact.
+    const lines = input.split('\n');
+    const kept: string[] = [];
+    let bytes = 0;
+    // Walk from the last line upward, adding lines while they fit. Account for the
+    // '\n' rejoin cost (1 byte) between kept lines.
+    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'),
+        };
+    }
+    // Degenerate case: the single last line alone exceeds maxBytes. Hard-clip its
+    // TAIL on a UTF-8 code-point boundary (Buffer slice can split a multi-byte
+    // sequence, so decode-and-recut with the replacement-char guard).
+    const lastLine = lines[lines.length - 1] ?? '';
+    const buf = Buffer.from(lastLine, 'utf8');
+    let slice = buf.subarray(Math.max(0, buf.length - maxBytes));
+    // Trim leading bytes until the decode has no leading replacement char (i.e. we
+    // landed on a valid code-point boundary).
+    let decoded = slice.toString('utf8');
+    while (decoded.length > 0 && decoded.charCodeAt(0) === 0xfffd && slice.length > 0) {
+        slice = slice.subarray(1);
+        decoded = slice.toString('utf8');
+    }
+    return {
+        text: decoded,
+        truncated: true,
+        originalBytes,
+        returnedBytes: Buffer.byteLength(decoded, 'utf8'),
+    };
+}
+
 export function listCliScriptNames(scripts: CliScripts | undefined): string[] {
     if (!scripts) return [];
     return Object.entries(scripts)

package/src/cli-adapters/terminal-screen.ts

@@ -56,6 +56,11 @@ export class TerminalScreen {
         return this.terminal.getCursorPosition();
     }
 
+    /** Current viewport dimensions (cols × rows). */
+    getSize(): { cols: number; rows: number } {
+        return { cols: this.cols, rows: this.rows };
+    }
+
     dispose(): void {
         this.terminal.dispose();
     }

package/src/commands/handler.ts

@@ -564,6 +564,10 @@ export class DaemonCommandHandler implements CommandHelpers {
             // ─── PTY Raw I/O (stream-commands.ts) ─────────
             case 'pty_input': return Stream.handlePtyInput(this, args);
             case 'pty_resize': return Stream.handlePtyResize(this, args);
+            // ─── MESH-READ-TERMINAL (feature 2): raw viewport read ──────────
+            case 'read_terminal': return Stream.handleReadTerminal(this, args);
+            // ─── MESH-SEND-KEYS (feature 3): structured key injection ────────
+            case 'send_keys': return Stream.handleSendKeys(this, args);
 
             // ─── Provider Settings (stream-commands.ts) ──────────
             case 'get_provider_settings': return Stream.handleGetProviderSettings(this, args);

package/src/commands/router-refine.ts

@@ -35,6 +35,7 @@ import {
     RefineContext,
     RefineExecFileAsync,
     RefineStageOutcome,
+    classifyPatchEquivalenceFailure,
     recordMeshRefineStage,
     resolveRefineryAutoPublishSubmoduleMainCommits,
     runMeshRefineEffectiveDiffGate,
@@ -616,9 +617,20 @@ export async function refineSyncBaseStage(self: DaemonCommandRouter, ctx: Refine
                         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,
@@ -801,7 +813,7 @@ export async function refineValidationStage(self: DaemonCommandRouter, ctx: Refi
 export async function refinePatchEquivalenceStage(self: DaemonCommandRouter, ctx: RefineContext): Promise<RefineStageOutcome> {
             // DS2: node/execFileAsync are no longer needed here — the rebase moved to
             // sync_base — and branchHead/patchEquivalence are no longer mutated in-stage.
-            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);
@@ -826,9 +838,24 @@ export async function refinePatchEquivalenceStage(self: DaemonCommandRouter, ctx
                 // branch itself has no changes (degenerate), which is NOT already-merged.
                 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,
@@ -2278,6 +2305,15 @@ export async function finishMeshRefineJob(self: DaemonCommandRouter, handle: Mes
             };
             if (typeof result.error === 'string') ctx.error = result.error;
             if (typeof result.blockedReason === 'string') ctx.blockedReason = result.blockedReason;
+            // Detailed patch-equivalence sub-cause classification (base_divergence,
+            // submodule_unreachable, actual_patch_diff, trivial_ff_misjudgment,
+            // already_converged, unclassified) + recommended action + evidence.
+            // Promoted onto blockerContext so coordinators reading task_failed ledger
+            // entries see the cause without parsing the free-form error string.
+            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;
             // Patch equivalence details
             if (stage === 'patch_equivalence' && result.patchEquivalence) {
                 const pe = result.patchEquivalence as Record<string, unknown>;
@@ -2287,6 +2323,9 @@ export async function finishMeshRefineJob(self: DaemonCommandRouter, handle: Mes
                     status: pe.status,
                     actionableHint: pe.actionableHint,
                     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 } : {}),
                 };
             }
             // Submodule reachability details

package/src/commands/router.ts

@@ -212,6 +212,21 @@ const MESH_FORWARDABLE_SESSION_COMMANDS = new Set([
     // 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',
+    // 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: string): CommandLogEntry['source'] {

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 {