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

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

@@ -1527,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
@@ -1679,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,
@@ -1692,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,
@@ -2012,6 +2060,13 @@ export class CliProviderInstance implements ProviderInstance {
         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);
     }
 
@@ -2032,11 +2087,18 @@ export class CliProviderInstance implements ProviderInstance {
         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 }
+        | { 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);
     }
 
@@ -2072,7 +2134,14 @@ export class CliProviderInstance implements ProviderInstance {
             this.meshStallEmittedForAnchor = false;
             return;
         }
-        if (!this.adapter.isAlive()) {
+        // 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;
@@ -2541,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;

package/src/providers/spec/adapter.ts

@@ -175,6 +175,13 @@ export class TerminalAdapter {
         return { row: pos.row, col: pos.col };
     }
 
+    /** 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 } {
+        return { cols: this.cols, rows: this.rows };
+    }
+
     send_keys(text: string): void {
         this.recordEvent('input', capPreview(escapeControl(text)), text.length);
         this.pty?.write(text);

package/src/providers/spec/cli-adapter.ts

@@ -23,10 +23,17 @@ import { lastContiguousNumberedBlock } from './evaluator.js';
 import { executeNativeHistory } from './native-history-executor.js';
 import { detectBackgroundTaskActive } from './background-task-detector.js';
 import * as fs from 'node:fs';
+import { createHash } from 'node:crypto';
 import type { NativeHistoryConfig, Control, ControlAction } from './types.js';
 import type { CliAdapter, CliAdapterStatus } from '../../cli-adapter-types.js';
 import type { ChatMessage } from '../../types.js';
 import type { PtyTransportFactory } from '../../cli-adapters/pty-transport.js';
+import {
+    encodeMeshSendKeys,
+    truncateToByteTailByLine,
+    type MeshSendKeyItem,
+    type MeshSendKeyName,
+} from '../../cli-adapters/provider-cli-shared.js';
 import { LOG } from '../../logging/logger.js';
 import {
     buildClaudeInteractiveTuiAnswerSteps,
@@ -277,6 +284,121 @@ export class SpecCliAdapter implements CliAdapter {
         return this.spawned && !this.exited;
     }
 
+    // Process liveness for the MESH-STALL-WATCH watchdog (checkMeshWorkerStall).
+    // The spec path drives the child through the transport/driver rather than a
+    // directly-held ptyProcess handle, so liveness is tracked by the spawned/exited
+    // lifecycle flags — the same pair isReady() uses. A spawned, not-yet-exited
+    // session is alive. ProviderCliAdapter exposes the equivalent via `ptyProcess !== null`.
+    isAlive(): boolean {
+        return this.spawned && !this.exited;
+    }
+
+    // MESH-READ-TERMINAL / MESH-SEND-KEYS byte caps — same envelope as
+    // ProviderCliAdapter (32KiB default view, 64KiB absolute hard cap). Bytes,
+    // not chars: a multi-byte-glyph screen can exceed an MCP payload cap while
+    // the char count still looks safe.
+    private static readonly TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES = 32 * 1024;
+    private static readonly TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES = 64 * 1024;
+
+    /**
+     * 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 = SpecCliAdapter.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(
+            SpecCliAdapter.TERMINAL_SNAPSHOT_ABSOLUTE_MAX_BYTES,
+            Math.max(1024, Math.floor(maxBytes) || SpecCliAdapter.TERMINAL_SNAPSHOT_DEFAULT_MAX_BYTES),
+        );
+        let rawViewport = '';
+        try { rawViewport = this.driver.snapshot() || ''; } catch { rawViewport = ''; }
+        let cursor = { row: 0, col: 0 };
+        try { cursor = this.driver.getCursorPosition(); } catch { /* keep 0,0 */ }
+        // getScreenSize is optional on ISpecDriver; a test double may omit it.
+        let size = { cols: 0, rows: 0 };
+        try { size = this.driver.getScreenSize?.() ?? size; } catch { /* keep 0,0 */ }
+        const truncation = truncateToByteTailByLine(rawViewport, cap);
+        const hash = createHash('sha256').update(rawViewport, 'utf8').digest('hex').slice(0, 16);
+        return {
+            text: truncation.text,
+            cursor: { col: cursor.col, row: cursor.row },
+            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 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.
+     */
+    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.spawned || this.exited) throw new Error(`${this.cliName} is not running`);
+        const encoded = encodeMeshSendKeys(items);
+
+        // Modal fail-closed — a NON-destructive injection while parked on an
+        // actionable approval modal is refused so a modal choice can't be
+        // confirmed via send_keys and bypass the approval policy.
+        const modalActive = this.latestState?.status === 'approval';
+        if (modalActive && !encoded.hasDestructive && !opts.allowModalOverride) {
+            LOG.warn('SpecAdapter', `[${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 pty_write.
+        this.driver.dispatch({ kind: 'pty_write', data: encoded.sequence });
+        LOG.info('SpecAdapter', `[${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'),
+        };
+    }
+
     setOnStatusChange(cb: () => void): void {
         this.statusCallback = cb;
     }

package/src/providers/spec/fsm-driver.ts

@@ -122,6 +122,10 @@ export interface ISpecDriver {
     snapshot(): string;
     getCursorPosition(): { row: number; 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>;
@@ -443,6 +447,7 @@ export class FsmDriver implements ISpecDriver {
     snapshot(): string { return this.adapter.snapshot(); }
     getCursorPosition(): { row: number; col: number } { return this.adapter.getCursorPosition(); }
     getScreen(): string { return this.adapter.snapshot(); }
+    getScreenSize(): { cols: number; rows: number } { return this.adapter.getScreenSize(); }
 
     /** Scrollback-inclusive screen as line array — used only for modal/button
      *  content extraction so a tall prompt's off-screen anchors stay matchable.