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

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/mesh/mesh-refine-gates.d.ts

@@ -327,6 +327,92 @@ export declare function resolveRefineryAutoPublishSubmoduleMainCommits(mesh: any
     source?: string;
 };
 export declare function runMeshRefinePatchEquivalenceGate(repoRoot: string, baseHead: string, branchHead: string): Promise<MeshRefinePatchEquivalenceSummary>;
+/**
+ * Machine-readable sub-classification of a `patch_equivalence_failed` (and the
+ * related submodule-gitlink preflight blocks). The opaque top-level
+ * `patch_equivalence_failed` code is preserved for backward compatibility; this
+ * detailed reason is added ALONGSIDE it so coordinators no longer have to guess
+ * WHY the preflight blocked (the 2026-07-17 hidden-spinner convergence incident:
+ * the real cause was a diverged base + an unreachable submodule gitlink artifact,
+ * not a real patch conflict, but Refinery only returned the opaque code and the
+ * coordinator mis-attributed it to a stale daemon version).
+ */
+export type MeshRefinePatchEquivalenceDetailedReasonCode = 
+/** Worktree base diverged from target base (HEAD is not a descendant of origin/main). */
+'base_divergence'
+/** Submodule gitlink commit is not reachable from the submodule's remote main branch (publish needed). */
+ | 'submodule_unreachable'
+/** Genuine non-equivalent content: expected tree vs actual merge diff differ. */
+ | 'actual_patch_diff'
+/** Submodule gitlink trivial fast-forward mis-judged as non-equivalent (HEAD descends origin/main, patch-id equal, blocked only by the gitlink). */
+ | 'trivial_ff_misjudgment'
+/** Already identical to origin/main (ahead 0 / behind 0, no diff) — should be treated as success/no-op. */
+ | 'already_converged'
+/** Fallback when the classifier itself could not run (git error); keep the opaque code, note the reason. */
+ | 'unclassified';
+export type MeshRefinePatchEquivalenceFailureClassification = {
+    detailedReason: MeshRefinePatchEquivalenceDetailedReasonCode;
+    /** Human-readable one-line description of the sub-cause. */
+    detailedReasonDescription: string;
+    /** Suggested next action for the coordinator/owner (free-form, actionable). */
+    recommendedAction: string;
+    /** Structured supporting evidence: SHAs, ahead/behind, submodule reachability, patch-id comparison, diff stat. */
+    evidence: {
+        baseHead?: string;
+        branchHead?: string;
+        mergeBase?: string;
+        /** How many commits base (origin/main) is ahead of the branch's merge-base (branch is behind). */
+        behind?: number;
+        /** How many commits the branch is ahead of the merge-base. */
+        ahead?: number;
+        /** True when HEAD is NOT a descendant of the target base (diverged). */
+        baseDiverged?: boolean;
+        expectedPatchId?: string;
+        actualPatchId?: string;
+        patchIdEqual?: boolean;
+        /** Compact one-line diff stat summary of the residual/actual merge diff (best-effort). */
+        diffStat?: string;
+        /** Per-submodule gitlink reachability against submodule origin/main (best-effort). */
+        submoduleGitlinks?: Array<{
+            path: string;
+            baseCommit?: string;
+            branchCommit?: string;
+            /** True when branchCommit descends baseCommit (a strict fast-forward advance). */
+            fastForward?: boolean;
+            /** True when branchCommit is reachable from the submodule's local origin/main. */
+            reachableFromOriginMain?: boolean;
+        }>;
+        /** Effective auto-publish-submodule-main-commits policy value at classification time. */
+        autoPublishSubmoduleMainCommits?: boolean;
+        /** Set when the classifier itself errored (detailedReason === 'unclassified'). */
+        classifierError?: string;
+    };
+};
+/**
+ * Classify WHY a patch-equivalence preflight blocked, turning the opaque
+ * `patch_equivalence_failed` code into a machine-readable {@link
+ * MeshRefinePatchEquivalenceDetailedReasonCode} plus a recommended action and
+ * structured evidence. Read-only: runs only `git` inspection commands (rev-list,
+ * merge-base, diff --stat, submodule reachability probes) against the already-set
+ * worktree — it never mutates the repo.
+ *
+ * Priority of classification (first match wins):
+ *   1. already_converged     — ahead 0 & behind 0 & no residual diff
+ *   2. submodule_unreachable  — a changed gitlink commit is not reachable from the
+ *                               submodule's origin/main (publish needed)
+ *   3. trivial_ff_misjudgment — HEAD descends origin/main AND (excl. gitlinks) the
+ *                               patch-ids match — blocked only by a ff gitlink
+ *   4. base_divergence        — HEAD is not a descendant of the target base
+ *   5. actual_patch_diff      — genuine content divergence (the residual case)
+ *
+ * `targetBaseRef` is the ref the branch is meant to land on (e.g. 'origin/main'
+ * or the pinned baseHead SHA). `autoPublishSubmoduleMainCommits` is threaded in so
+ * the submodule_unreachable recommendation can name the current policy value.
+ */
+export declare function classifyPatchEquivalenceFailure(repoRoot: string, baseHead: string, branchHead: string, summary: MeshRefinePatchEquivalenceSummary, options?: {
+    targetBaseRef?: string;
+    autoPublishSubmoduleMainCommits?: boolean;
+}): Promise<MeshRefinePatchEquivalenceFailureClassification>;
 export type MeshWorktreePatchContainmentSummary = {
     /** True only when merging worktreeHead into ref introduces no new patch. */
     contained: boolean;

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;
@@ -419,6 +423,21 @@ export declare class CliProviderInstance implements ProviderInstance {
      * the dashboard tail-repair cache — a display value, not a completion decision.
      */
     private lastVisibleAssistantSummary;
+    /**
+     * NOTIF Defect-B: the final assistant summary this instance ALREADY parsed and
+     * cached for the current turn (lastCompletionSummary), if any. The evidence
+     * probe (completionFinalAssistantEvidence) is a POINT-SAMPLE: on a native-source
+     * provider (antigravity) the parsed screen and the native transcript can both
+     * momentarily yield no in-turn final assistant at the exact instant the
+     * completion gate fires — source='unavailable', missingEvidence=true — even
+     * though a prior poll already read the real answer off native-history and cached
+     * it here (the same value mesh_read_chat.summary shows). Consulting the cache at
+     * emit time lets that already-secured summary count as evidence, so the completion
+     * notification carries the answer instead of completion_diagnostic=missing_final_assistant
+     * with an empty summary. Returns '' when the cache is empty or was reset by the
+     * next turn (see lastCompletionSummary = null on onTurnStarted).
+     */
+    private cachedCompletionSummaryContent;
     private completionFinalAssistantEvidence;
     private completionFinalSummary;
     private buildCompletedFinalizationDiagnostic;
@@ -429,6 +448,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' | 'unsupported';
+        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/providers/spec/adapter.d.ts

@@ -79,6 +79,13 @@ export declare class TerminalAdapter {
         row: number;
         col: number;
     };
+    /** Current terminal geometry (columns × rows). Tracked here rather than
+     *  read off the screen buffer so a resize is reflected immediately, before
+     *  the next repaint. Consumed by the mesh_read_terminal viewport read. */
+    getScreenSize(): {
+        cols: number;
+        rows: number;
+    };
     send_keys(text: string): void;
     /** Forward runtime metadata (meshNodeId, workspaceLabel, lifecycle, …) to
      *  the underlying transport so it reaches the session registry. The spec

package/dist/providers/spec/cli-adapter.d.ts

@@ -1,5 +1,6 @@
 import type { CliAdapter, CliAdapterStatus } from '../../cli-adapter-types.js';
 import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+import { type MeshSendKeyItem, type MeshSendKeyName } from '../../cli-adapters/provider-cli-shared.js';
 import { type InteractivePromptResponse } from '../types/interactive-prompt.js';
 export declare class SpecCliAdapter implements CliAdapter {
     readonly cliType: string;
@@ -74,6 +75,69 @@ export declare class SpecCliAdapter implements CliAdapter {
     cancel(): void;
     isProcessing(): boolean;
     isReady(): boolean;
+    isAlive(): boolean;
+    private static readonly TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES;
+    private static readonly TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES;
+    /**
+     * MESH-READ-TERMINAL (feature 2: RAW terminal read). Least-privilege read
+     * of the CURRENT rendered viewport for mesh_read_terminal on the spec path
+     * (claude-cli / antigravity / codex-cli — the native-source providers that
+     * route through SpecCliAdapter). Mirrors ProviderCliAdapter.getTerminalScreenSnapshot:
+     *  - returns ONLY the driver's current viewport snapshot, the cursor
+     *    position and the terminal geometry — NO scrollback, NO parser/FSM
+     *    state, NO debug buffers;
+     *  - the payload is byte-bounded (UTF-8) with bottom-tail preservation so a
+     *    screen of multi-byte glyphs can never exceed the MCP payload cap;
+     *  - `hash` is over the FULL untruncated viewport so a caller can detect a
+     *    screen change across polls even when the returned text was truncated.
+     *
+     * SECURITY: the raw viewport can carry tokens / command args / env / user
+     * data. Callers MUST gate this on mesh ownership and MUST NOT log the text.
+     */
+    getTerminalScreenSnapshot(maxBytes?: number): {
+        text: string;
+        cursor: {
+            col: number;
+            row: number;
+        };
+        cols: number;
+        rows: number;
+        truncated: boolean;
+        originalBytes: number;
+        returnedBytes: number;
+        hash: string;
+    };
+    /**
+     * MESH-SEND-KEYS (feature 3: key injection). Inject a STRUCTURED key
+     * sequence into the spec-driven PTY for mesh_send_keys. Mirrors
+     * ProviderCliAdapter.injectKeys' modal fail-closed guard, then writes the
+     * whole encoded sequence in ONE pty_write dispatch (text+ENTER is a single
+     * contiguous string, so a submit key can never be separated from the text
+     * it submits).
+     *
+     * The spec path drives the child through the FsmDriver, not a directly-held
+     * ptyProcess — there is no adapter-level echo-gate/submit-retry FIFO to race
+     * against here (the driver serializes its own writes), so the only guard is
+     * the modal fail-closed: a NON-destructive injection into an actionable
+     * approval modal is refused (use mesh_approve) unless explicitly overridden.
+     * A destructive ESC/CTRL_C dismisses rather than confirms, so it is allowed
+     * past this gate (the tool layer owns the destructive double-gate + audit).
+     * This method NEVER logs the literal text — only key enums / byte length.
+     */
+    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;
+    }>;
     setOnStatusChange(cb: () => void): void;
     setOnPtyData(cb: (data: string) => void): void;
     writeRaw(data: string): void;

package/dist/providers/spec/fsm-driver.d.ts

@@ -126,6 +126,13 @@ export interface ISpecDriver {
         col: number;
     };
     getScreen(): string;
+    /** Current terminal geometry (columns × rows). Optional so a non-Fsm
+     *  ISpecDriver implementation (test doubles) need not provide it; the
+     *  mesh_read_terminal path falls back to a 0×0 geometry when absent. */
+    getScreenSize?(): {
+        cols: number;
+        rows: number;
+    };
     getSpecPath(): string;
     shutdown(): void;
     getStateHistory(): ReadonlyArray<DriverHistoryEntry>;
@@ -251,6 +258,10 @@ export declare class FsmDriver implements ISpecDriver {
         col: number;
     };
     getScreen(): string;
+    getScreenSize(): {
+        cols: number;
+        rows: number;
+    };
     /** Scrollback-inclusive screen as line array — used only for modal/button
      *  content extraction so a tall prompt's off-screen anchors stay matchable.
      *  Falls back to the viewport snapshot if scrollback read is unavailable. */

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.554",
   "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.554",
+    "@adhdev/session-host-core": "0.9.82-rc.554",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

package/src/cli-adapter-types.ts

@@ -6,6 +6,7 @@
 
 import type { ChatMessage } from './types.js';
 import type { InteractivePrompt, InteractivePromptResponse } from './providers/types/interactive-prompt.js';
+import type { MeshSendKeyItem, MeshSendKeyName } from './cli-adapters/provider-cli-shared.js';
 
 export interface CliAdapterStatus {
     status?: string;
@@ -118,6 +119,34 @@ export interface CliAdapter {
     cancel(): void;
     isProcessing(): boolean;
     isReady(): boolean;
+    // Liveness of the underlying process/PTY. Optional because not every adapter
+    // implementation exposes it (the spec-driven path historically did not); the
+    // MESH-STALL-WATCH watchdog must call it defensively (typeof guard) so a
+    // missing implementation never throws in the 5s tick.
+    isAlive?(): boolean;
+    // MESH-READ-TERMINAL (feature 2) / MESH-SEND-KEYS (feature 3). Optional
+    // because not every adapter implements the raw-terminal read / structured
+    // key-injection surface; callers (cli-provider-instance) MUST typeof-guard
+    // and return a clean unsupported result rather than throwing when absent.
+    // Both ProviderCliAdapter (PTY path) and SpecCliAdapter (native-source spec
+    // path — claude-cli / antigravity / codex-cli) implement them.
+    getTerminalScreenSnapshot?(maxBytes?: number): {
+        text: string;
+        cursor: { col: number; row: number };
+        cols: number;
+        rows: number;
+        truncated: boolean;
+        originalBytes: number;
+        returnedBytes: number;
+        hash: string;
+    };
+    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 }
+    >;
     setOnStatusChange(callback: () => void): void;
     updateRuntimeSettings?(settings: Record<string, unknown>): void;
     setCliScripts?(scripts: Record<string, unknown>): void;

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> {