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

package/src/mesh/mesh-refine-gates.ts

@@ -556,6 +556,262 @@ export async function runMeshRefinePatchEquivalenceGate(
     }
 }
 
+/**
+ * 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 async function classifyPatchEquivalenceFailure(
+    repoRoot: string,
+    baseHead: string,
+    branchHead: string,
+    summary: MeshRefinePatchEquivalenceSummary,
+    options: { targetBaseRef?: string; autoPublishSubmoduleMainCommits?: boolean } = {},
+): Promise<MeshRefinePatchEquivalenceFailureClassification> {
+    const targetBaseRef = options.targetBaseRef || baseHead;
+    const autoPublish = options.autoPublishSubmoduleMainCommits;
+    const evidence: MeshRefinePatchEquivalenceFailureClassification['evidence'] = {
+        baseHead,
+        branchHead,
+        mergeBase: summary.mergeBase,
+        expectedPatchId: summary.expectedPatchId,
+        actualPatchId: summary.actualPatchId,
+        patchIdEqual: !!summary.expectedPatchId && summary.expectedPatchId === summary.actualPatchId,
+        ...(autoPublish !== undefined ? { autoPublishSubmoduleMainCommits: autoPublish } : {}),
+    };
+    try {
+        const git = (args: string[]): string => execFileSync(GIT, args, {
+            cwd: repoRoot,
+            encoding: 'utf8',
+            maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES,
+            windowsHide: true,
+        });
+        const gitOk = (args: string[]): boolean => {
+            try { git(args); return true; } catch { return false; }
+        };
+
+        // ahead/behind of branch vs the target base ref. left = base-only (behind),
+        // right = branch-only (ahead).
+        let ahead = 0;
+        let behind = 0;
+        try {
+            const out = git(['rev-list', '--left-right', '--count', `${targetBaseRef}...${branchHead}`]).trim();
+            const [left, right] = out.split(/\s+/).map(n => Number.parseInt(n, 10));
+            behind = Number.isFinite(left) ? left : 0;
+            ahead = Number.isFinite(right) ? right : 0;
+        } catch { /* keep zeros */ }
+        evidence.ahead = ahead;
+        evidence.behind = behind;
+        // HEAD (branchHead) diverged from the target base = base is NOT an ancestor
+        // of the branch. behind>0 with the base ref not reachable from HEAD.
+        const baseIsAncestor = gitOk(['merge-base', '--is-ancestor', targetBaseRef, branchHead]);
+        evidence.baseDiverged = !baseIsAncestor;
+
+        // Residual/actual diff stat (best-effort): what the merge would still introduce.
+        let diffStat = '';
+        try {
+            if (summary.mergedTree) {
+                diffStat = git(['diff', '--stat', baseHead, summary.mergedTree]).trim().split('\n').filter(Boolean).slice(-1)[0] || '';
+            } else {
+                diffStat = git(['diff', '--stat', baseHead, branchHead]).trim().split('\n').filter(Boolean).slice(-1)[0] || '';
+            }
+        } catch { /* diff stat is best-effort */ }
+        if (diffStat) evidence.diffStat = diffStat;
+
+        // Changed gitlink reachability against each submodule's local origin/main.
+        const submoduleGitlinks: NonNullable<MeshRefinePatchEquivalenceFailureClassification['evidence']['submoduleGitlinks']> = [];
+        try {
+            const nameStatus = git(['diff', '--name-only', '--diff-filter=d', baseHead, branchHead]).trim();
+            const changedPaths = nameStatus ? nameStatus.split('\n').map(p => p.trim()).filter(Boolean) : [];
+            for (const p of changedPaths) {
+                // Only submodule (gitlink, mode 160000) entries.
+                let baseCommit: string | undefined;
+                let branchCommit: string | undefined;
+                try {
+                    const baseLs = git(['ls-tree', baseHead, '--', p]).trim();
+                    const branchLs = git(['ls-tree', branchHead, '--', p]).trim();
+                    const isGitlink = /(^|\s)160000\s/.test(baseLs) || /(^|\s)160000\s/.test(branchLs);
+                    if (!isGitlink) continue;
+                    baseCommit = baseLs.split(/\s+/)[2];
+                    branchCommit = branchLs.split(/\s+/)[2];
+                } catch { continue; }
+                const submoduleRepo = pathJoin(repoRoot, p);
+                let fastForward: boolean | undefined;
+                let reachableFromOriginMain: boolean | undefined;
+                if (branchCommit) {
+                    if (baseCommit) {
+                        fastForward = execGitOk(submoduleRepo, ['merge-base', '--is-ancestor', baseCommit, branchCommit]);
+                    }
+                    reachableFromOriginMain = execGitOk(submoduleRepo, ['merge-base', '--is-ancestor', branchCommit, 'refs/remotes/origin/main']);
+                }
+                submoduleGitlinks.push({ path: p, baseCommit, branchCommit, fastForward, reachableFromOriginMain });
+            }
+        } catch { /* submodule inspection is best-effort */ }
+        if (submoduleGitlinks.length) evidence.submoduleGitlinks = submoduleGitlinks;
+
+        // Existing gate signal: the merge-tree trivial-ff evaluation, if the gate
+        // captured it (a genuine non-trivial submodule conflict lands here too).
+        const gitlinkFf = summary.gitlinkTrivialFastForward;
+
+        // ── Classification (first match wins) ────────────────────────────────
+        const noResidualDiff = !evidence.diffStat && (!summary.actualPatchId || summary.actualPatchId === '');
+
+        // 1. already_converged: nothing ahead, nothing behind, no residual diff.
+        if (ahead === 0 && behind === 0 && noResidualDiff) {
+            return {
+                detailedReason: 'already_converged',
+                detailedReasonDescription: 'Branch is already identical to the target base (ahead 0, behind 0, no residual diff); the merge would be a no-op.',
+                recommendedAction: 'Treat as already converged — no merge needed. Verify with `git range-diff` / patch-id, then mark the branch merged (or clean up the worktree).',
+                evidence,
+            };
+        }
+
+        // 2. submodule_unreachable: a changed gitlink is not reachable from the
+        //    submodule's origin/main. This is the publish-needed artifact.
+        const unreachable = submoduleGitlinks.filter(g => g.reachableFromOriginMain === false);
+        if (unreachable.length > 0) {
+            const paths = unreachable.map(g => g.path).join(', ');
+            return {
+                detailedReason: 'submodule_unreachable',
+                detailedReasonDescription: `Submodule gitlink commit(s) not reachable from submodule origin/main (publish needed): ${paths}.`,
+                recommendedAction: `Publish the submodule commit(s) to submodule origin/main, then retry mesh_refine_node (policy allowAutoPublishSubmoduleMainCommits=${autoPublish === undefined ? 'unknown' : autoPublish}).`,
+                evidence,
+            };
+        }
+
+        // 3. trivial_ff_misjudgment: HEAD descends the target base AND the non-gitlink
+        //    patch-ids are equal, so the ONLY thing blocking is a fast-forward gitlink
+        //    that merge-tree refused. (Either the gate flagged an unresolved gitlink
+        //    ff, or every changed gitlink is a proven ff.)
+        const changedGitlinks = submoduleGitlinks.length > 0;
+        const allGitlinksFf = changedGitlinks && submoduleGitlinks.every(g => g.fastForward === true);
+        const gateSawUnresolvedGitlinkFf = gitlinkFf?.resolved === false && Array.isArray(gitlinkFf.gitlinks) && gitlinkFf.gitlinks.some(g => g.fastForward);
+        if (baseIsAncestor && (evidence.patchIdEqual || allGitlinksFf || gateSawUnresolvedGitlinkFf)) {
+            return {
+                detailedReason: 'trivial_ff_misjudgment',
+                detailedReasonDescription: 'HEAD descends the target base and the patch content matches; the block is a submodule gitlink trivial fast-forward that merge-tree refused, not a real divergence.',
+                recommendedAction: 'Converge via the strict fast-forward-only bypass (verify HEAD descends origin/main and patch-id equality, then merge --ff-only) instead of the refine gate.',
+                evidence,
+            };
+        }
+
+        // 4. base_divergence: HEAD is not a descendant of the target base.
+        if (!baseIsAncestor) {
+            return {
+                detailedReason: 'base_divergence',
+                detailedReasonDescription: `Worktree base has diverged from ${targetBaseRef} (HEAD is not a descendant; ahead ${ahead}, behind ${behind}).`,
+                recommendedAction: `Rebase the branch onto ${targetBaseRef}, then retry mesh_refine_node.`,
+                evidence,
+            };
+        }
+
+        // 5. actual_patch_diff: genuine non-equivalent content.
+        return {
+            detailedReason: 'actual_patch_diff',
+            detailedReasonDescription: 'The merge introduces content not equivalent to the branch\'s cumulative patch (expected tree vs actual merge diff differ).',
+            recommendedAction: 'Manual review required — inspect the residual diff; the branch content is not patch-equivalent to a clean merge onto the base.',
+            evidence,
+        };
+    } catch (e: any) {
+        evidence.classifierError = e?.message || String(e);
+        return {
+            detailedReason: 'unclassified',
+            detailedReasonDescription: 'Patch-equivalence sub-cause could not be classified (git inspection failed); see classifierError.',
+            recommendedAction: 'Inspect the refineStages and patchEquivalence summary manually to determine the cause.',
+            evidence,
+        };
+    }
+}
+
+/** Small helper: run a git command in `cwd` and return whether it exited 0. */
+function execGitOk(cwd: string, args: string[]): boolean {
+    try {
+        execFileSync(GIT, args, { cwd, encoding: 'utf8', maxBuffer: REFINE_PATCH_EQUIVALENCE_OUTPUT_LIMIT_BYTES, windowsHide: true });
+        return true;
+    } catch {
+        return false;
+    }
+}
+
 export type MeshWorktreePatchContainmentSummary = {
     /** True only when merging worktreeHead into ref introduces no new patch. */
     contained: boolean;

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

@@ -16,6 +16,7 @@ import { normalizeInteractivePrompt, normalizeInteractivePromptResponse, type In
 import { ProviderCliAdapter } from '../cli-adapters/provider-cli-adapter.js';
 import { shortHash } from '../system/hash.js';
 import type { CliProviderModule } from '../cli-adapters/provider-cli-adapter.js';
+import type { MeshSendKeyItem, MeshSendKeyName } from '../cli-adapters/provider-cli-shared.js';
 import { createCliAdapter } from './spec/route.js';
 import type { PtyRuntimeMetadata, PtyTransportFactory } from '../cli-adapters/pty-transport.js';
 import { StatusMonitor } from './status-monitor.js';
@@ -252,6 +253,16 @@ export class CliProviderInstance implements ProviderInstance {
      */
     private static readonly APPROVAL_RESUME_GRACE_MS = 18_000;
 
+    // MESH-STALL-WATCH (feature 1: STALL detection): how long a coordinator-spawned
+    // mesh worker's raw PTY output (lastOutputAt) may stay unchanged before the
+    // status-agnostic stall watchdog fires ONE informational monitor:no_progress
+    // event. Unlike the StatusMonitor no-progress watchdog (which only runs while a
+    // turn is generating), this observes pure screen stasis regardless of the
+    // reported status — a worker parked idle, wedged mid-turn, or spawned with no
+    // output at all. 180s matches DEFAULT_MONITOR_CONFIG.noProgressThresholdSec so
+    // the two watchdogs agree on the same "long interval" bound.
+    private static readonly MESH_WORKER_STALL_THRESHOLD_MS = 180_000;
+
     private adapter: ProviderCliAdapter;
     private context: InstanceContext | null = null;
     private events: ProviderEvent[] = [];
@@ -265,6 +276,16 @@ export class CliProviderInstance implements ProviderInstance {
     // first sets it; the other becomes a no-op.
     private agentReadyEmitted = false;
     private generatingStartedAt: number = 0;
+    // MESH-STALL-WATCH (feature 1): the lastOutputAt value the stall episode is
+    // currently armed against. A stall episode is "the raw PTY output has not
+    // advanced past this anchor". When the adapter has never emitted output
+    // (lastOutputAt === 0) the anchor is the spawn time (this.startedAt) so a
+    // worker that produced NOTHING is still caught. On any new output the anchor
+    // re-arms to the fresh lastOutputAt and meshStallEmittedForAnchor resets, so a
+    // single continuous stall fires AT MOST ONCE and a later stall re-arms cleanly.
+    // -1 = not yet initialised for this session.
+    private meshStallAnchorAt = -1;
+    private meshStallEmittedForAnchor = false;
     // FALSE-IDLE continuity epoch: monotonically bumped on EVERY entry into a busy
     // phase (→generating or →waiting_approval). The completedDebouncePending snapshots
     // this value at arm time (busyEpochAtArm); the flush guard requires it UNCHANGED
@@ -1506,6 +1527,26 @@ export class CliProviderInstance implements ProviderInstance {
         return '';
     }
 
+    /**
+     * 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(): string {
+        const cached = this.lastCompletionSummary;
+        const content = typeof cached?.content === 'string' ? cached.content.trim() : '';
+        return content;
+    }
+
     private completionFinalAssistantEvidence(parsedMessages: unknown, turnStartedAt?: number): CompletionFinalAssistantEvidence {
         // (FALSEIDLE FixB) UPPER-BOUND turn-end evidence. completionHasFinalAssistantMessage is a
         // pure message-content check ("does the last visible bubble read as a finalized assistant
@@ -1658,12 +1699,39 @@ export class CliProviderInstance implements ProviderInstance {
         const lastVisibleKind = typeof (lastVisible as any)?.kind === 'string' ? (lastVisible as any).kind : null;
         const lastVisibleContentLength = lastVisible ? flattenContent(lastVisible.content).trim().length : 0;
 
+        // NOTIF Defect-B: when the live evidence probe momentarily yields no in-turn
+        // final assistant (source='unavailable'/external-native with present=false) but
+        // a prior poll already parsed and CACHED the real answer for this turn
+        // (lastCompletionSummary — the same value mesh_read_chat.summary surfaces),
+        // credit the cache as evidence. This flips finalAssistantPresent to true and
+        // records the cached source so the completion notification carries
+        // completion_diagnostic=present with the summary, instead of
+        // missing_final_assistant with an empty payload. Only ever UPGRADES a
+        // point-sample miss — a genuine present=true is unchanged, and an empty cache
+        // leaves the missing-evidence diagnostic exactly as before.
+        const cachedSummary = evidence.present ? '' : this.cachedCompletionSummaryContent();
+        const creditedFromCache = !evidence.present && cachedSummary.length > 0;
+        const finalAssistantPresent = evidence.present || creditedFromCache;
+        const finalAssistantEvidenceSource = evidence.present
+            ? evidence.source
+            : (creditedFromCache ? 'cached-summary' : evidence.source);
+        // When the cached summary rescues the evidence, the turn is no longer
+        // "missing final assistant" — clear that blockReason so isMissingFinalAssistant‑
+        // Diagnostic()/isWeakCompletionEvidence() no longer flag it (both key off
+        // blockReason='missing_final_assistant' independently of finalAssistantPresent)
+        // and the coordinator log's formatCompletionMetadata reads
+        // completion_diagnostic=present (empty blockReason → 'present'). The ORIGINAL
+        // reason is preserved under originalBlockReason for diagnostics.
+        const clearMissingBlock = creditedFromCache && args.blockReason === 'missing_final_assistant';
+        const effectiveBlockReason = clearMissingBlock ? undefined : args.blockReason;
+
         return {
             providerType: this.type,
             sessionId: this.instanceId,
             providerSessionId: this.providerSessionId || null,
             workspace: this.workingDir,
-            blockReason: args.blockReason,
+            ...(effectiveBlockReason ? { blockReason: effectiveBlockReason } : {}),
+            ...(clearMissingBlock ? { originalBlockReason: args.blockReason } : {}),
             emittedAfterFinalizationTimeout: args.emittedAfterFinalizationTimeout,
             waitedMs: args.waitedMs,
             maxWaitMs: COMPLETED_FINALIZATION_MAX_WAIT_MS,
@@ -1671,8 +1739,9 @@ export class CliProviderInstance implements ProviderInstance {
             latestVisibleStatus: args.latestVisibleStatus,
             parsedStatus: typeof parsed?.status === 'string' ? parsed.status : (parseError ? 'parse_error' : 'unknown'),
             parseError: parseError || undefined,
-            finalAssistantPresent: evidence.present,
-            finalAssistantEvidenceSource: evidence.source,
+            finalAssistantPresent,
+            finalAssistantFromCachedSummary: !evidence.present && cachedSummary.length > 0,
+            finalAssistantEvidenceSource,
             visibleMessageCount: visibleMessages.length,
             lastVisibleRole,
             lastVisibleKind,
@@ -1966,6 +2035,188 @@ export class CliProviderInstance implements ProviderInstance {
             || this.settings.meshNodeId || this.settings.launchedByCoordinator);
     }
 
+    /**
+     * MESH-READ-TERMINAL (feature 2: RAW terminal read). Public read of the
+     * CURRENT rendered PTY viewport for the mesh_read_terminal tool, delegating to
+     * the adapter's narrow getTerminalScreenSnapshot() (viewport + cursor + size
+     * only; no debug buffers / parser state / history; byte-bounded, bottom-tail
+     * preserved).
+     *
+     * Gated on isMeshWorkerSession(): this raw viewport can expose tokens /
+     * command args / env / user data, so only a coordinator-spawned worker session
+     * is readable. The MCP layer ALSO cross-checks mesh/session/node ownership
+     * (isMeshOwnedDelegateSession) — isMeshWorkerSession alone is a broad
+     * "delegated" gate, so the two together block cross-mesh access. Returns null
+     * for a non-mesh session so the daemon command surfaces a clean refusal.
+     */
+    getTerminalScreenSnapshot(maxBytes?: number): {
+        text: string;
+        cursor: { col: number; row: number };
+        cols: number;
+        rows: number;
+        truncated: boolean;
+        originalBytes: number;
+        returnedBytes: number;
+        hash: string;
+    } | null {
+        if (!this.isMeshWorkerSession()) return null;
+        // Defensive: not every CliAdapter implementation exposes the raw-terminal
+        // read (the surface is declared optional on CliAdapter). Returning null
+        // for an adapter that lacks it surfaces a clean unsupported refusal at
+        // the daemon command instead of "getTerminalScreenSnapshot is not a
+        // function" — the failure mode that broke mesh_read_terminal on the
+        // spec-driven path before SpecCliAdapter implemented it.
+        if (typeof this.adapter.getTerminalScreenSnapshot !== 'function') return null;
+        return this.adapter.getTerminalScreenSnapshot(maxBytes);
+    }
+
+    /**
+     * MESH-SEND-KEYS (feature 3: key injection). Public entry for the
+     * mesh_send_keys tool, delegating to the adapter's injectKeys() (structured
+     * key encoding + atomic write + submit-race recheck + modal fail-closed).
+     *
+     * Gated on isMeshWorkerSession(): PTY input into a worker is a
+     * coordinator-only capability. The MCP layer ALSO cross-checks mesh/session/
+     * node ownership (isMeshOwnedDelegateSession) and owns the destructive-key
+     * double gate (confirm_destructive + policy) and the audit ledger. Returns a
+     * refusal object for a non-mesh session so the daemon command surfaces a clean
+     * error (never silently writes to a non-worker PTY).
+     */
+    async injectKeys(
+        items: MeshSendKeyItem[],
+        opts: { allowModalOverride?: boolean } = {},
+    ): Promise<
+        | { ok: true; keys: MeshSendKeyName[]; hasDestructive: boolean; submits: boolean; bytes: number }
+        | { ok: false; refused: 'submit_race' | 'actionable_modal' | 'not_mesh_worker' | 'unsupported'; keys: MeshSendKeyName[]; hasDestructive: boolean }
+    > {
+        if (!this.isMeshWorkerSession()) {
+            return { ok: false, refused: 'not_mesh_worker', keys: [], hasDestructive: false };
+        }
+        // Defensive: injectKeys is optional on CliAdapter. An adapter without it
+        // yields a clean 'unsupported' refusal instead of throwing
+        // "injectKeys is not a function" — the failure that broke mesh_send_keys
+        // on the spec-driven path before SpecCliAdapter implemented it.
+        if (typeof this.adapter.injectKeys !== 'function') {
+            return { ok: false, refused: 'unsupported', keys: [], hasDestructive: false };
+        }
+        return this.adapter.injectKeys(items, opts);
+    }
+
+    /**
+     * MESH-STALL-WATCH (feature 1: STALL detection). Status-agnostic stall
+     * watchdog for coordinator-spawned mesh worker sessions. Driven by the
+     * ProviderInstanceManager's existing 5s onTick loop (NO new timer) — see
+     * ProviderInstanceManager.startTicking. Reuses the adapter's raw-PTY-output
+     * clock (lastOutputAt, bumped on every output chunk) as the sole signal: if a
+     * live worker's screen has been byte-for-byte unchanged for
+     * MESH_WORKER_STALL_THRESHOLD_MS (180s), fire ONE informational
+     * monitor:no_progress event down the existing task_stalled ledger +
+     * pendingCoordinatorEvent path.
+     *
+     * Deliberately status-agnostic: it does NOT read getStatus()'s reported status
+     * (which would couple it to the generating-only StatusMonitor and the
+     * idle-timeout FSM). A normally-idle worker CAN trip this after 3 quiet
+     * minutes; that is accepted and surfaced as an informational stall (NOT a
+     * failure/auto-restart) so the coordinator judges. getStatus/getState are NOT
+     * called here, so status heartbeats never move the stall anchor.
+     *
+     * Anchoring: the episode arms against the current lastOutputAt; a worker that
+     * has emitted nothing yet (lastOutputAt === 0) anchors on this.startedAt (spawn
+     * time) so a silent spawn is still caught. Any new output re-arms the anchor
+     * and clears the emitted flag, so one continuous stall emits at most once and a
+     * later stall re-arms cleanly.
+     */
+    checkMeshWorkerStall(now: number = Date.now()): void {
+        if (!this.isMeshWorkerSession()) {
+            // Not (or no longer) a mesh worker — drop any armed episode so a session
+            // whose mesh markers were detached does not carry a stale anchor.
+            this.meshStallAnchorAt = -1;
+            this.meshStallEmittedForAnchor = false;
+            return;
+        }
+        // Defensive: not every CliAdapter implementation exposes isAlive() — the
+        // spec-driven adapter (SpecCliAdapter, used by native-source providers like
+        // antigravity-cli) historically had none, so an unguarded call threw
+        // `this.adapter.isAlive is not a function` on EVERY 5s tick, disabling stall
+        // detection for those sessions entirely. A missing method is treated as alive
+        // (the session lifecycle drops the anchor via isMeshWorkerSession()/exit paths),
+        // never as a throw. When present, a dead process drops the armed episode.
+        if (typeof this.adapter.isAlive === 'function' && !this.adapter.isAlive()) {
+            // Dead PTY: nothing to watch. agent:stopped covers the exit; re-arm on
+            // the next live session so a restart starts a fresh episode.
+            this.meshStallAnchorAt = -1;
+            this.meshStallEmittedForAnchor = false;
+            return;
+        }
+
+        let lastOutputAt: number;
+        try {
+            // allowParse:false — a cheap status read that must NOT trigger parsing
+            // and must NOT mutate lastOutputAt (getState/getStatus never bump it).
+            const status = this.adapter.getStatus({ allowParse: false }) as { lastOutputAt?: unknown };
+            lastOutputAt = typeof status?.lastOutputAt === 'number' && Number.isFinite(status.lastOutputAt)
+                ? status.lastOutputAt
+                : 0;
+        } catch {
+            return; // defensive: a failed status read just skips this tick
+        }
+
+        // The anchor is the last raw output; before any output, the spawn time so a
+        // silent worker is still caught.
+        const anchor = lastOutputAt > 0 ? lastOutputAt : this.startedAt;
+
+        if (this.meshStallAnchorAt === -1) {
+            // First observation this session — arm against the current anchor.
+            this.meshStallAnchorAt = anchor;
+            this.meshStallEmittedForAnchor = false;
+            return;
+        }
+
+        if (anchor > this.meshStallAnchorAt) {
+            // New output advanced the clock — re-arm the episode against it.
+            this.meshStallAnchorAt = anchor;
+            this.meshStallEmittedForAnchor = false;
+            return;
+        }
+
+        if (this.meshStallEmittedForAnchor) return; // already fired for this stall
+
+        const stalledMs = now - this.meshStallAnchorAt;
+        if (stalledMs < CliProviderInstance.MESH_WORKER_STALL_THRESHOLD_MS) return;
+
+        this.meshStallEmittedForAnchor = true;
+
+        // observedStatus is surfaced as context only — deliberately NOT stamped as
+        // the reconciliation-triggering `status` field (which would let
+        // buildNoProgressCompletionReconciliation mistake an idle stall for a
+        // completion). See mesh-events-stale.buildNoProgressCompletionReconciliation.
+        let observedStatus = 'unknown';
+        try {
+            const s = (this.adapter.getStatus({ allowParse: false }) as { status?: unknown })?.status;
+            if (typeof s === 'string' && s) observedStatus = s;
+        } catch { /* best-effort context only */ }
+
+        if (this.isMeshWorkerSession()) {
+            traceMeshEventStage('fired', this.meshTraceCtx('monitor:no_progress'), 'mesh_worker_stall_watchdog');
+        }
+
+        const stalledSec = Math.round(stalledMs / 1000);
+        this.pushEvent({
+            event: 'monitor:no_progress',
+            agentKey: `${this.type}:cli`,
+            elapsedSec: stalledSec,
+            timestamp: now,
+            // MESH-STALL-WATCH marker: buildMeshSystemMessage generalizes the
+            // coordinator message (generating-specific → "PTY output unchanged")
+            // when this is set, since this watchdog fires status-agnostically.
+            meshWorkerStall: true,
+            lastOutputAt: this.meshStallAnchorAt,
+            stalledMs,
+            observedStatus,
+            taskId: this.completingTurnTaskId(),
+        });
+    }
+
     /**
      * AUTOAPPROVE-FLAP-RECUR (Fix A+B): how long a busy blip / modal scroll-out may
      * persist before the in-progress settle gate is torn down. For a delegated
@@ -2359,9 +2610,15 @@ export class CliProviderInstance implements ProviderInstance {
                 // delegated session's inbox preview blank — or, for a LOCAL worktree session,
                 // stuck on the dispatched user task. If the parser DID surface assistant text,
                 // prefer it; only fall back to '' when no assistant summary can be derived.
-                finalSummary: blockReason.startsWith('parsed_status:')
-                    ? (this.completionFinalSummary(this.adapter?.getScriptParsedStatus()?.messages, pending.turnStartedAt) ?? '')
-                    : this.completionFinalSummary(this.adapter?.getScriptParsedStatus()?.messages, pending.turnStartedAt),
+                // NOTIF Defect-B: completionFinalSummary is a point-sample of native-history/
+                // screen at THIS instant; on a native-source provider (antigravity) it can be
+                // empty at the forced-emit instant even though a prior poll already cached the
+                // real answer (lastCompletionSummary). Fall back to the cache so the notification
+                // carries the summary that mesh_read_chat.summary already shows — consistent with
+                // completionDiagnostic.finalAssistantPresent being credited from the same cache.
+                finalSummary: (this.completionFinalSummary(this.adapter?.getScriptParsedStatus()?.messages, pending.turnStartedAt)
+                    || this.cachedCompletionSummaryContent()
+                    || (blockReason.startsWith('parsed_status:') ? '' : undefined)),
                 completionDiagnostic,
             });
             this.completedDebouncePending = null;
@@ -3527,6 +3784,20 @@ export class CliProviderInstance implements ProviderInstance {
                 this.completedDebouncePending = null;
                 continue;
             }
+            // MESH-STALL-WATCH dedupe: for a coordinator-spawned mesh worker the
+            // status-agnostic stall watchdog (checkMeshWorkerStall) owns the
+            // monitor:no_progress alert. The StatusMonitor here fires its OWN
+            // generating-only no-progress on the SAME 180s bound, which would
+            // double-emit into the task_stalled ledger + coordinator inbox for the
+            // one stall. Suppress the StatusMonitor's copy for mesh workers only —
+            // the completion-reconciliation branch above (which turns a no-progress
+            // WITH final-assistant into a real completion) still runs, so genuine
+            // idle-reconciled completions are unaffected. Non-mesh sessions keep the
+            // original StatusMonitor behavior untouched.
+            if (me.type === 'monitor:no_progress' && this.isMeshWorkerSession()) {
+                traceMeshEventDrop('mesh_worker_stall_watchdog_owns_no_progress', this.meshTraceCtx('monitor:no_progress'));
+                continue;
+            }
             this.pushEvent({ event: me.type, agentKey: me.agentKey, message: me.message, elapsedSec: me.elapsedSec, timestamp: me.timestamp });
         }
     }

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

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

package/src/providers/provider-instance.ts

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