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

package/dist/mesh/mesh-ledger.d.ts

@@ -15,7 +15,7 @@
 import { EventEmitter } from 'events';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
 import { type MeshLedgerOriginatingCoordinatorV2 } from './contracts.js';
-export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'p2p_dispatch_failed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_joined' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled' | 'direct_fast_forward' | 'delivery_unroutable' | 'direct_dispatch_pruned' | 'event_held' | 'event_held_requeued' | 'task_reclaimed' | 'coordinator_operating_note' | 'coordinator_operating_note_tombstone' | 'mission_created' | 'mission_status_changed' | 'mission_goal_updated' | 'magi_dispatched' | 'magi_synthesis';
+export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'p2p_dispatch_failed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_joined' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled' | 'direct_fast_forward' | 'delivery_unroutable' | 'direct_dispatch_pruned' | 'event_held' | 'event_held_requeued' | 'task_reclaimed' | 'coordinator_operating_note' | 'coordinator_operating_note_tombstone' | 'mission_created' | 'mission_status_changed' | 'mission_goal_updated' | 'magi_dispatched' | 'magi_synthesis' | 'key_injection';
 export interface MeshLedgerEntry {
     id: string;
     meshId: string;

package/dist/providers/cli-provider-instance.d.ts

@@ -7,6 +7,7 @@
 import { type ProviderModule, type InputEnvelope } from './contracts.js';
 import type { ProviderInstance, ProviderState, InstanceContext, HotChatSessionState, SessionModalState } from './provider-instance.js';
 import { ProviderCliAdapter } from '../cli-adapters/provider-cli-adapter.js';
+import type { MeshSendKeyItem, MeshSendKeyName } from '../cli-adapters/provider-cli-shared.js';
 import type { PtyTransportFactory } from '../cli-adapters/pty-transport.js';
 import type { ChatMessage } from '../types.js';
 export { buildCliStructuredInputPrompt } from './cli-provider-input-prompt.js';
@@ -169,12 +170,15 @@ export declare class CliProviderInstance implements ProviderInstance {
      * with no approval never carries recency and is never held (no regression).
      */
     private static readonly APPROVAL_RESUME_GRACE_MS;
+    private static readonly MESH_WORKER_STALL_THRESHOLD_MS;
     private adapter;
     private context;
     private events;
     private lastStatus;
     private agentReadyEmitted;
     private generatingStartedAt;
+    private meshStallAnchorAt;
+    private meshStallEmittedForAnchor;
     private busyEpoch;
     private fastCollapseSynthesizedTaskId;
     private startupGraceCollapseAt;
@@ -429,6 +433,84 @@ export declare class CliProviderInstance implements ProviderInstance {
     private approvalResolutionFinalizationBlock;
     private scheduleCompletedDebounceFlush;
     private isMeshWorkerSession;
+    /**
+     * 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;
+    /**
+     * 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).
+     */
+    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;
+    }>;
+    /**
+     * 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): void;
     /**
      * 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

package/dist/providers/provider-instance.d.ts

@@ -164,6 +164,15 @@ export interface ProviderInstance {
     init(context: InstanceContext): Promise<void>;
     /** 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/dist/repo-mesh-types.d.ts

@@ -255,6 +255,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
@@ -374,6 +385,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
@@ -479,6 +495,13 @@ export declare function mergeAndNormalizePolicy(base: RepoMeshPolicy | undefined
  * launch path merges the envelope as a settingsOverride on top of the provider defaults.
  */
 export declare function resolveDelegatedWorkerAutoApprove(meshPolicy?: Pick<RepoMeshPolicy, 'delegatedWorkerAutoApprove'> | null, nodePolicy?: Pick<RepoMeshNodePolicy, 'delegatedWorkerAutoApprove'> | null): boolean;
+/**
+ * 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 declare function resolveAllowSendKeysDestructive(meshPolicy?: Pick<RepoMeshPolicy, 'allowSendKeysDestructive'> | null, nodePolicy?: Pick<RepoMeshNodePolicy, 'allowSendKeysDestructive'> | null): boolean;
 /**
  * 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.552",
+  "version": "0.9.82-rc.553",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -47,8 +47,8 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.552",
-    "@adhdev/session-host-core": "0.9.82-rc.552",
+    "@adhdev/mesh-shared": "0.9.82-rc.553",
+    "@adhdev/session-host-core": "0.9.82-rc.553",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

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

@@ -15,6 +15,7 @@
  */
 
 import * as os from 'os';
+import { createHash } from 'crypto';
 import type { CliAdapter, CliLaunchInfo } from '../cli-adapter-types.js';
 import type { InteractivePromptResponse } from '../providers/types/interactive-prompt.js';
 import { LOG } from '../logging/logger.js';
@@ -43,7 +44,11 @@ import {
     normalizeScreenSnapshot,
     promptLikelyVisible,
     sanitizeTerminalText,
+    truncateToByteTailByLine,
+    encodeMeshSendKeys,
     TerminalTranscriptAccumulator,
+    type MeshSendKeyItem,
+    type MeshSendKeyName,
     type CliChatMessage,
     type CliProviderModule,
     type CliScriptInput,
@@ -308,6 +313,11 @@ export class ProviderCliAdapter implements CliAdapter {
         result: any;
     } | null = null;
     private static readonly 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.
+    private static readonly TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES = 32 * 1024;
+    private static readonly 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
@@ -2297,6 +2307,131 @@ export class ProviderCliAdapter implements CliAdapter {
         };
     }
     isAlive(): boolean { 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): {
+        text: string;
+        cursor: { col: number; row: number };
+        cols: number;
+        rows: number;
+        truncated: boolean;
+        originalBytes: number;
+        returnedBytes: number;
+        hash: string;
+    } {
+        const cap = Math.min(
+            ProviderCliAdapter.TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES,
+            Math.max(1024, Math.floor(maxBytes) || ProviderCliAdapter.TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES),
+        );
+        // Current rendered viewport only — no scrollback, no parse composite.
+        const rawViewport = this.terminalScreen.getText() || '';
+        const size = this.terminalScreen.getSize();
+        const cursor = this.terminalScreen.getCursorPosition();
+        const truncation = truncateToByteTailByLine(rawViewport, cap);
+        const hash = 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: MeshSendKeyItem[],
+        opts: { allowModalOverride?: boolean } = {},
+    ): Promise<
+        | { ok: true; keys: MeshSendKeyName[]; hasDestructive: boolean; submits: boolean; bytes: number }
+        | { ok: false; refused: 'submit_race' | 'actionable_modal'; keys: MeshSendKeyName[]; hasDestructive: boolean }
+    > {
+        if (!this.ptyProcess) throw new Error(`${this.cliName} is not running`);
+        const encoded = encodeMeshSendKeys(items);
+
+        // (1) submit-race recheck — atomic w.r.t. the write below (no await between).
+        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 };
+        }
+
+        // (2) modal fail-closed — a NON-destructive injection into an actionable
+        //     modal is refused unless explicitly overridden.
+        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(',')} — use mesh_approve`);
+            return { ok: false, refused: 'actionable_modal', keys: encoded.keys, hasDestructive: encoded.hasDestructive };
+        }
+
+        // Atomic write: the full encoded sequence goes out in ONE writeToPty (which
+        // chains onto the write FIFO). text+ENTER is already one contiguous string,
+        // so the submit key can never be separated from the text it submits.
+        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(): void { this.schedulePendingOutboundFlush(); }
 
     async writeRaw(data: string | Buffer): Promise<void> {

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.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'] {