@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.491

package/src/providers/cli-provider-status-helpers.ts

@@ -0,0 +1,123 @@
+/**
+ * CLI provider status/launch pure helpers.
+ *
+ * Pure move out of cli-provider-instance.ts (no behavior change): the
+ * side-effect-free status predicates, the turn-anchored duration computation,
+ * the forced-new-session script resolver, the adapter-ready poll, and the lazy
+ * node:sqlite DatabaseSync loader. cli-provider-instance re-exports the
+ * public symbols (computeTurnAnchoredDurationMs, getForcedNewSessionScriptName,
+ * waitForCliAdapterReady) so existing importers/tests keep their path.
+ */
+
+import * as path from 'path';
+import { createRequire } from 'node:module';
+import type { ProviderModule } from './contracts.js';
+
+export function isIdleStatus(value: unknown): boolean {
+    const status = typeof value === 'string' ? value.trim().toLowerCase() : '';
+    return !status || status === 'idle' || status === 'ready';
+}
+
+export function getMessageTime(message: unknown): number {
+    if (!message || typeof message !== 'object') return 0;
+    const record = message as { receivedAt?: unknown; timestamp?: unknown };
+    const value = Number(record.receivedAt ?? record.timestamp ?? 0);
+    return Number.isFinite(value) ? value : 0;
+}
+
+export function hasNonEmptyCliModalButtons(activeModal: unknown): boolean {
+    const buttons = (activeModal as any)?.buttons;
+    return Array.isArray(buttons) && buttons.some((button) => String(button || '').trim().length > 0);
+}
+
+export function isCliGeneratingLikeStatus(status: unknown): boolean {
+    return status === 'generating' || status === 'streaming' || status === 'no_progress' || status === 'long_generating' || status === 'starting';
+}
+
+/**
+ * NOTIF Defect-2a: the REPORTED short-generating duration, anchored on the IMMUTABLE turn
+ * start. generatingStartedAt is reset to 0 on every mid-turn waiting_approval/idle blip and
+ * re-armed on the next →generating, so a long turn that blips would otherwise measure only the
+ * final 1.5-2.5s sliver. engine.currentTurnStartedAt (set once at onTurnStarted, surviving
+ * mid-turn blips until the next turn starts) is preferred; generatingStartedAt is the fallback
+ * for turns that never recorded an engine turn start. Returns 0 when neither anchor is set.
+ * Pure / unit-testable.
+ */
+export function computeTurnAnchoredDurationMs(
+    engineTurnStartedAt: number | undefined,
+    generatingStartedAt: number,
+    now: number,
+): { durationMs: number; anchor: 'turn-start' | 'generatingStartedAt' | 'none' } {
+    const engineStart = typeof engineTurnStartedAt === 'number' && Number.isFinite(engineTurnStartedAt)
+        ? engineTurnStartedAt
+        : 0;
+    if (engineStart > 0) return { durationMs: now - engineStart, anchor: 'turn-start' };
+    if (generatingStartedAt > 0) return { durationMs: now - generatingStartedAt, anchor: 'generatingStartedAt' };
+    return { durationMs: 0, anchor: 'none' };
+}
+
+let CachedDatabaseSync: (new (path: string, options?: { readOnly?: boolean }) => {
+    prepare(sql: string): { get(...params: Array<string | number>): unknown };
+    close(): void;
+}) | null = null;
+
+export function getDatabaseSync() {
+    if (CachedDatabaseSync) return CachedDatabaseSync;
+    const requireFn = typeof require === 'function'
+        ? require
+        : createRequire(path.join(process.cwd(), '__adhdev_sqlite_loader__.js'));
+    const sqliteModule = requireFn(`node:${'sqlite'}`) as {
+        DatabaseSync: typeof CachedDatabaseSync;
+    };
+    CachedDatabaseSync = sqliteModule.DatabaseSync;
+    if (!CachedDatabaseSync) {
+        throw new Error('node:sqlite DatabaseSync unavailable');
+    }
+    return CachedDatabaseSync;
+}
+
+export function getForcedNewSessionScriptName(
+    provider: ProviderModule | undefined,
+    launchMode: 'new' | 'resume' | 'manual',
+): string | null {
+    if (!provider || launchMode !== 'new') return null;
+    const resume = provider.resume;
+    if (!resume?.supported) return null;
+    if (Array.isArray(resume.newSessionArgs) && resume.newSessionArgs.length > 0) return null;
+
+    const controls = Array.isArray((provider as any).controls) ? (provider as any).controls : [];
+    for (const control of controls) {
+        if (control?.type !== 'action') continue;
+        if (typeof control?.confirmTitle === 'string' && control.confirmTitle.trim()) continue;
+        if (typeof control?.confirmMessage === 'string' && control.confirmMessage.trim()) continue;
+        if (typeof control?.confirmLabel === 'string' && control.confirmLabel.trim()) continue;
+        const invokeScript = typeof control?.invokeScript === 'string' ? control.invokeScript.trim() : '';
+        if (!invokeScript) continue;
+        const controlId = typeof control?.id === 'string' ? control.id.trim() : '';
+        if (controlId === 'new_session' || /^new.?session$/i.test(invokeScript)) {
+            return invokeScript;
+        }
+    }
+
+    return null;
+}
+
+export async function waitForCliAdapterReady(
+    adapter: { isReady?: () => boolean; getStatus?: () => { status?: string } },
+    options?: { timeoutMs?: number; pollMs?: number },
+): Promise<void> {
+    const timeoutMs = Math.max(100, options?.timeoutMs ?? 15_000);
+    const pollMs = Math.max(10, options?.pollMs ?? 50);
+    const deadline = Date.now() + timeoutMs;
+
+    while (Date.now() < deadline) {
+        if (adapter?.isReady?.()) return;
+        const status = adapter?.getStatus?.()?.status;
+        if (status === 'stopped') {
+            throw new Error('CLI runtime stopped before it became ready');
+        }
+        await new Promise((resolve) => setTimeout(resolve, pollMs));
+    }
+
+    throw new Error(`CLI runtime did not become ready within ${timeoutMs}ms`);
+}

package/src/providers/cli-provider-transcript-merge.ts

@@ -0,0 +1,114 @@
+// Transcript assembly helpers extracted from cli-provider-instance.ts.
+// Pure move — no behavior change. `mergeConversationMessages` was a private
+// method reading only `this.runtimeMessages`; it now takes that array as a
+// parameter. `buildExternalTranscriptProbe` used no instance state.
+
+import { flattenContent } from './contracts.js';
+import { normalizeChatMessages, resolveChatMessageKind, isUserFacingChatMessage } from './chat-message-normalization.js';
+import type { ChatMessage } from '../types.js';
+import type { ExternalTranscriptProbe } from './cli-provider-instance-types.js';
+
+export function mergeConversationMessages(
+    runtimeMessages: Array<{ key: string; message: ChatMessage }>,
+    parsedMessages: any[],
+): ChatMessage[] {
+    if (runtimeMessages.length === 0) return normalizeChatMessages(parsedMessages);
+
+    type MergeEntry = { message: ChatMessage; index: number; source: 'parsed' | 'runtime'; runtimeKey?: string };
+    const parsedEntries: MergeEntry[] = parsedMessages.map((message, index) => ({
+        message,
+        index,
+        source: 'parsed',
+    }));
+    const getRole = (message: ChatMessage): string => typeof message.role === 'string'
+        ? message.role.trim().toLowerCase()
+        : '';
+    const runtimeEntries: MergeEntry[] = runtimeMessages.map((entry, index) => ({
+        message: entry.message,
+        index: parsedMessages.length + index,
+        source: 'runtime' as const,
+        runtimeKey: entry.key,
+    })).filter((entry) => {
+        const meta = entry.message.meta && typeof entry.message.meta === 'object' && !Array.isArray(entry.message.meta)
+            ? entry.message.meta as Record<string, unknown>
+            : {};
+        if (meta.runtimeInputAck !== true) return true;
+        const runtimeText = flattenContent(entry.message.content).replace(/\s+/g, ' ').trim();
+        if (!runtimeText) return false;
+        return !parsedEntries.some((parsedEntry) => {
+            const parsedRole = getRole(parsedEntry.message);
+            if (parsedRole !== 'user' && parsedRole !== 'human') return false;
+            const parsedText = flattenContent(parsedEntry.message.content).replace(/\s+/g, ' ').trim();
+            return parsedText === runtimeText;
+        });
+    });
+    const getTime = (message: ChatMessage): number => {
+        const value = typeof message.receivedAt === 'number'
+            ? message.receivedAt
+            : typeof message.timestamp === 'number'
+                ? message.timestamp
+                : 0;
+        return Number.isFinite(value) && value > 0 ? value : 0;
+    };
+
+    const isRuntimeOverlay = (entry: MergeEntry): boolean => {
+        if (entry.source !== 'runtime') return false;
+        const key = typeof entry.runtimeKey === 'string' ? entry.runtimeKey.trim().toLowerCase() : '';
+        if (key.startsWith('auto_approval:')) return true;
+        return !isUserFacingChatMessage(entry.message);
+    };
+    const shouldKeepParsedBeforeUntimedRuntime = (message: ChatMessage): boolean => {
+        const role = getRole(message);
+        return role === 'user' || role === 'human';
+    };
+    const shouldKeepParsedAfterUntimedRuntime = (message: ChatMessage): boolean => {
+        const role = getRole(message);
+        if (role !== 'assistant') return false;
+        const kind = resolveChatMessageKind(message);
+        return kind === 'standard' || kind === 'terminal';
+    };
+
+    return normalizeChatMessages([...parsedEntries, ...runtimeEntries]
+        .sort((a, b) => {
+            const aTime = getTime(a.message);
+            const bTime = getTime(b.message);
+            if (aTime && bTime && aTime !== bTime) return aTime - bTime;
+            if (a.source !== b.source && aTime !== bTime) {
+                const parsedEntry = a.source === 'parsed' ? a : b.source === 'parsed' ? b : null;
+                const runtimeEntry = a.source === 'runtime' ? a : b.source === 'runtime' ? b : null;
+                if (parsedEntry && runtimeEntry && isRuntimeOverlay(runtimeEntry) && getTime(parsedEntry.message) === 0 && getTime(runtimeEntry.message) > 0) {
+                    if (shouldKeepParsedBeforeUntimedRuntime(parsedEntry.message)) {
+                        return a.source === 'parsed' ? -1 : 1;
+                    }
+                    if (shouldKeepParsedAfterUntimedRuntime(parsedEntry.message)) {
+                        return a.source === 'parsed' ? 1 : -1;
+                    }
+                }
+            }
+            // Many provider-owned CLI transcripts (including Hermes CLI in debug bundles)
+            // do not carry timestamps on parsed messages. In that case there is no safe
+            // clock basis for interleaving timestamped runtime/system messages into the
+            // provider transcript. Keep user prompts before runtime overlays, but do not
+            // let timed runtime/system/tool/internal overlays become the final chat turns
+            // after an untimed parsed assistant transcript.
+            return a.index - b.index;
+        })
+        .map((entry) => entry.message));
+}
+
+export function buildExternalTranscriptProbe(messages: unknown[], sourcePath?: string, sourceMtimeMs?: number): ExternalTranscriptProbe {
+    const visibleMessages = messages.filter((message: any) => isUserFacingChatMessage(message as ChatMessage));
+    const lastVisible = visibleMessages[visibleMessages.length - 1] as ChatMessage | undefined;
+    const readAt = Date.now();
+    const mtimeMs = Number(sourceMtimeMs) || 0;
+    return {
+        readAt,
+        msgCount: messages.length,
+        lastRole: typeof lastVisible?.role === 'string' ? lastVisible.role.trim().toLowerCase() : null,
+        lastKind: typeof (lastVisible as any)?.kind === 'string' ? (lastVisible as any).kind : null,
+        contentLen: lastVisible ? flattenContent(lastVisible.content).trim().length : 0,
+        sourcePath: typeof sourcePath === 'string' && sourcePath ? sourcePath : null,
+        sourceMtimeMs: mtimeMs || null,
+        mtimeAgeMs: mtimeMs ? Math.max(0, readAt - mtimeMs) : null,
+    };
+}

package/src/providers/contracts.d.ts

@@ -401,7 +401,62 @@ export interface ProviderModule {
     spawnArgBuilder?: (config: Record<string, string>) => string[];
     /** ACP agent auth methods (multiple supported — in priority order) */
     auth?: AcpAuthMethod[];
+    /**
+     * Repo Mesh coordinator capability and MCP ingestion behavior.
+     * Providers must declare this rather than relying on daemon hardcoded CLI quirks.
+     */
+    meshCoordinator?: ProviderMeshCoordinatorConfig;
+}
+export type MeshCoordinatorMcpConfigMode = 'auto_import' | 'manual' | 'none';
+export type MeshCoordinatorMcpConfigFormat = 'claude_mcp_json' | 'hermes_config_yaml';
+export interface ProviderMeshCoordinatorConfig {
+    supported: boolean;
+    reason?: string;
+    mcpConfig?: {
+        mode: MeshCoordinatorMcpConfigMode;
+        format?: MeshCoordinatorMcpConfigFormat;
+        path?: string;
+        serverName?: string;
+        configPathCommand?: string;
+        requiresRestart?: boolean;
+        instructions?: string;
+        template?: string;
+    };
+    systemPromptInjection?: MeshCoordinatorSystemPromptInjection;
+    delegatedWorkerIsolation?: MeshCoordinatorDelegatedWorkerIsolation;
 }
+export type MeshCoordinatorSystemPromptInjection = {
+    mode: 'cli_arg';
+    flag: string;
+} | {
+    mode: 'config_override';
+    flag: string;
+    template: string;
+} | {
+    mode: 'context_file';
+    path: string;
+    wrapper?: string;
+} | {
+    mode: 'env_var';
+    name: string;
+};
+export interface MeshCoordinatorDelegatedWorkerIsolation {
+    env?: {
+        unset?: string[];
+    };
+    args?: MeshCoordinatorDelegatedWorkerArgRule[];
+}
+export type MeshCoordinatorDelegatedWorkerArgRule = {
+    mode: 'empty_mcp_config';
+    flag: string;
+    strictFlag?: string;
+} | {
+    mode: 'config_override';
+    flag: string;
+    key: string;
+    value: string;
+    dedupeKey?: string;
+};
 export interface ProviderResumeCapability {
     supported: boolean;
     stopStrategy?: 'command' | 'ctrl_c';

package/src/providers/contracts.ts

@@ -15,6 +15,14 @@ import type { ChatMessageKind } from './chat-message-normalization.js';
 export type ReadChatTurnStatus = 'open' | 'waiting_approval' | 'complete' | 'error';
 
 export interface ReadChatResult {
+  /**
+   * Declared chat contract version. Absent or `'1.0'` → legacy v1 payload
+   * (current shape). `'2.0'` → v2 payload conforming to transcript-v2.ts
+   * (ReadChatResultV2). Validators in read-chat-contract.ts route on this
+   * field. A1 only adds the field; A2 will make v2 the daemon-internal
+   * canonical form and reject unrecognised versions at provider load time.
+   */
+  contractVersion?: import('./transcript-v2.js').ChatContractVersion;
   messages: ChatMessage[];
   status: AgentStatus;
   activeModal?: ModalInfo | null;
@@ -382,11 +390,99 @@ export interface ProviderMeshCoordinatorConfig {
     requiresRestart?: boolean;
     /** User-facing setup explanation for manual modes. */
     instructions?: string;
-    /** Copyable setup template. Supports {{meshId}}, {{adhdevMcpCommand}}, {{workspace}}, {{serverName}}. */
+    /** Copyable setup template. Supports {{meshId}}, {{adhdevMcpCommand}}, {{adhdevMcpArgs}}, {{workspace}}, {{serverName}}. */
     template?: string;
   };
+  /**
+   * How the coordinator system prompt reaches the launched CLI. Replaces the
+   * old hard-coded `if (cliType === 'claude-cli') push --append-system-prompt`
+   * branches in router.ts: a new CLI now ships its injection rule in its
+   * provider.v1.json, no daemon code change needed. Users can override the
+   * rendered prompt or the injection mechanism per-provider; if omitted, no
+   * system prompt is injected (safe default — won't crash spawn with a flag
+   * the CLI doesn't recognize).
+   */
+  systemPromptInjection?: MeshCoordinatorSystemPromptInjection;
+  /**
+   * How coordinator-launched worker sessions are isolated from coordinator-only
+   * MCP/tools/config. Provider-specific CLI quirks belong here, not in daemon
+   * launch code.
+   */
+  delegatedWorkerIsolation?: MeshCoordinatorDelegatedWorkerIsolation;
 }
 
+export interface MeshCoordinatorDelegatedWorkerIsolation {
+  /** Environment variables to unset for delegated worker sessions. */
+  env?: {
+    unset?: string[];
+  };
+  /** Spawn-argument rules applied before launching a delegated worker. */
+  args?: MeshCoordinatorDelegatedWorkerArgRule[];
+}
+
+export type MeshCoordinatorDelegatedWorkerArgRule =
+  | {
+      mode: 'empty_mcp_config';
+      /** CLI flag that points at an MCP config file, e.g. '--mcp-config'. */
+      flag: string;
+      /** Optional CLI flag that forces only the provided MCP config to be used. */
+      strictFlag?: string;
+    }
+  | {
+      mode: 'config_override';
+      /** CLI config flag, e.g. '-c' or '--config'. */
+      flag: string;
+      /** Config key to set for worker isolation. */
+      key: string;
+      /** Config value to set. */
+      value: string;
+      /** Optional broader key prefix used for duplicate detection. */
+      dedupeKey?: string;
+    };
+
+/**
+ * Declarative description of how a CLI accepts a session-scoped system prompt.
+ *
+ * Modes:
+ *   - cli_arg          → push `flag` + prompt onto spawn args                (Claude)
+ *   - config_override  → push `flag` + a templated key=value config override (Codex)
+ *   - context_file     → write prompt into a workspace markdown the CLI
+ *                        auto-loads as project context                       (Gemini, Antigravity)
+ *   - env_var          → expose prompt to the spawned process as $name       (Hermes)
+ *
+ * The prompt text is templated with `{prompt}` (raw) or `{prompt_json}`
+ * (JSON-encoded for embedding inside config-override strings).
+ */
+export type MeshCoordinatorSystemPromptInjection =
+  | {
+      mode: 'cli_arg';
+      /** Spawn-args flag, e.g. '--append-system-prompt'. The prompt becomes the next argv. */
+      flag: string;
+    }
+  | {
+      mode: 'config_override';
+      /** Spawn-args flag, e.g. '-c'. Followed by `template` with placeholders rendered. */
+      flag: string;
+      /** Template using {prompt} or {prompt_json}, e.g. 'developer_instructions={prompt_json}'. */
+      template: string;
+    }
+  | {
+      mode: 'context_file';
+      /** Workspace-relative file path the CLI auto-loads, e.g. 'AGENTS.md' or 'GEMINI.md'. */
+      path: string;
+      /**
+       * Optional wrapper around the prompt. Use `{prompt}` placeholder. Existing
+       * wrapper-delimited blocks are replaced rather than duplicated, so re-launching
+       * a coordinator doesn't pile up copies. If omitted, the prompt is appended raw.
+       */
+      wrapper?: string;
+    }
+  | {
+      mode: 'env_var';
+      /** Env-var name, e.g. 'HERMES_EPHEMERAL_SYSTEM_PROMPT'. */
+      name: string;
+    };
+
 export interface ProviderCompatibilityEntry {
   ideVersion: string;
   scriptDir: string;
@@ -472,6 +568,14 @@ export interface ProviderModule {
   extensionIdPattern_flags?: string;
   compatibility?: ProviderCompatibilityEntry[];
   defaultScriptDir?: string;
+  /**
+   * v1 declarative tui block (spinner/settledPrompt/modal/dispatchOrder/etc).
+   * When present, the daemon's CliScriptRunner builds canonical
+   * (input → verdict) functions from this and injects them into provider
+   * scripts as `sdk.declarativeDetectStatus` and `sdk.declarativeParseApproval`.
+   * v0 / verified-tier providers can omit this entirely.
+   */
+  tui?: Record<string, unknown>;
   /**
    * Scripts that can run at the IDE main-page level (not just inside the extension webview session frame).
    * Default: ['listModes', 'setMode', 'listModels', 'setModel'].
@@ -490,6 +594,63 @@ export interface ProviderModule {
     /** Auto-implement spawn config — controls how this provider is invoked for autonomous script generation */
     autoImpl?: ProviderAutoImplSpawnConfig;
   };
+  /**
+   * MAGI-KIND-PANEL (model axis): template for expanding an `initialModel` selection
+   * into launch args for a CLI provider. `{{model}}` is substituted with the model
+   * string; e.g. `['--model', '{{model}}']` for claude-cli → `--model opus`. Applied
+   * at session launch when `initialModel` is passed AND this provider is a plain CLI
+   * (ACP providers instead route the model through setConfigOption). A CLI provider
+   * with no template silently ignores `initialModel` at launch (best-effort; a model
+   * request never fails a launch). Absent → no launch-time model selection for CLI.
+   */
+  modelLaunchArgs?: string[];
+  /**
+   * BRAIN-ROUTING (model axis): suggested model values for this provider, surfaced
+   * as dropdown options in the new-session dialog (e.g. claude ['opus','sonnet',
+   * 'haiku']; codex ['gpt-5.5','gpt-5-codex']). Advisory only — the UI allows free
+   * text too, so the list going stale never blocks a model the provider accepts.
+   */
+  modelOptions?: string[];
+  /**
+   * BRAIN-ROUTING (thinking axis): template for expanding an `initialThinkingLevel`
+   * selection into launch args for a CLI provider, parallel to modelLaunchArgs.
+   * `{{level}}` is substituted with the provider-appropriate reasoning-effort value
+   * (already mapped from the standard low|medium|high level, see thinkingLevelMap).
+   * Examples: claude-cli `['--effort', '{{level}}']` → `--effort high`; codex-cli
+   * `['-c', 'model_reasoning_effort={{level}}']`. Applied at session launch when
+   * `initialThinkingLevel` is passed AND this provider is a plain CLI. A CLI provider
+   * with no template silently ignores the thinking level (best-effort; never fails a
+   * launch). ACP providers instead route thinking through setConfigOption('thought_level').
+   */
+  thinkingLaunchArgs?: string[];
+  /**
+   * BRAIN-ROUTING (thinking axis): optional per-provider mapping from the standard
+   * thinking levels (`low`|`medium`|`high`) to this provider's own reasoning-effort
+   * vocabulary, used to fill `{{level}}` in thinkingLaunchArgs. e.g. claude-cli might
+   * map `{ high: 'max' }`; codex-cli `{ high: 'xhigh' }`. A level absent from the map
+   * passes through unchanged (so `medium` → `medium` by default).
+   */
+  thinkingLevelMap?: Partial<Record<'low' | 'medium' | 'high', string>>;
+  /**
+   * BRAIN-ROUTING (thinking axis): the reasoning-effort values this provider actually
+   * accepts, surfaced as the thinking-level dropdown options in the new-session
+   * dialog (e.g. claude ['low','medium','high','max']; codex ['minimal','low',
+   * 'medium','high','xhigh']). Absent → the UI falls back to the standard
+   * low/medium/high. These are the provider's OWN vocabulary and are passed through
+   * verbatim as initialThinkingLevel (not remapped by thinkingLevelMap, which only
+   * translates the mesh's standard low/medium/high presets).
+   */
+  thinkingLevelOptions?: string[];
+  /**
+   * BRAIN-ROUTING (thinking axis, runtime-control providers): the `controls[].id`
+   * of a runtime reasoning-effort control to drive for the thinking level when the
+   * provider has no `thinkingLaunchArgs` (e.g. hermes-cli's `reasoning` select,
+   * which types `/reasoning <level>` into the PTY via its setScript). At launch,
+   * initialThinkingLevel (after thinkingLevelMap) is applied by invoking that
+   * control's setScript with `{ value: <level> }`. Ignored if the id doesn't match a
+   * control. Providers that use thinkingLaunchArgs don't need this.
+   */
+  thinkingControlId?: string;
   /** Delay before submitting typed CLI input (provider-specific TUI tuning) */
   sendDelayMs?: number;
   /** Submit key used after typing into CLI PTY (default: carriage return) */
@@ -525,8 +686,16 @@ export interface ProviderModule {
   /** History behavior config — controls message filtering and collapse during replay */
   historyBehavior?: ProviderHistoryBehavior;
   /**
-   * Canonical history sync config — for providers that maintain native history files.
-   * When set, daemon syncs from native format into ADHDev JSONL store on each tick.
+   * Native history config — for providers that maintain native history files.
+   * When set, daemon reads/lists provider-native transcripts directly. This is
+   * the canonical v1 field name; the legacy `canonicalHistory` field name is
+   * still accepted by the loader and aliased onto this field at load time.
+   */
+  nativeHistory?: NativeHistoryConfig;
+  /**
+   * @deprecated Legacy v0 alias for {@link ProviderModule.nativeHistory}.
+   * Loader populates this from `nativeHistory` so existing internal readers
+   * keep working during the transition. Remove after one release.
    */
   canonicalHistory?: ProviderCanonicalHistoryConfig;
   /**
@@ -672,7 +841,7 @@ export interface ProviderHistoryBehavior {
  * daemon-core. They let each provider own native transcript file discovery and
  * parsing while daemon-core only validates/pages the normalized result.
  */
-export interface ProviderCanonicalHistoryScriptsConfig {
+export interface NativeHistoryScriptsConfig {
   /** Reads one native session. Default: 'readNativeHistory'. */
   readSession?: string;
   /** Lists native sessions with summary metadata. Default: 'listNativeHistory'. */
@@ -680,13 +849,19 @@ export interface ProviderCanonicalHistoryScriptsConfig {
 }
 
 /**
- * Canonical history sync config — for providers that maintain their own native history files.
+ * @deprecated Use {@link NativeHistoryScriptsConfig}. Retained as an alias for
+ * one release so external consumers that referenced the old name keep compiling.
+ */
+export type ProviderCanonicalHistoryScriptsConfig = NativeHistoryScriptsConfig;
+
+/**
+ * Native history config — for providers that maintain their own native history files.
  *
  * Preferred mode is provider-owned scripts via `scripts`. `format` is now an
  * opaque provider label retained for diagnostics/backward compatibility; daemon
  * live paths must not branch on provider-specific format values.
  */
-export interface ProviderCanonicalHistoryConfig {
+export interface NativeHistoryConfig {
   /** Opaque provider-owned history format label. */
   format?: string;
   /** Optional native history glob/template for diagnostics only. */
@@ -702,8 +877,25 @@ export interface ProviderCanonicalHistoryConfig {
    * Omitted mode defaults to 'native-source'.
    */
   mode?: 'native-source' | 'materialized-mirror' | 'disabled';
+  /**
+   * Chat transcript contract version this provider's read_chat output
+   * conforms to. See transcript-v2.ts for the v2 invariants. Absent or `'1.0'`
+   * → legacy v1 payload (current behaviour). `'2.0'` → strict v2 payload
+   * (stable providerUnitKey/bubbleId/sequence, strict enums, honest coverage).
+   *
+   * A1 only surfaces this field; validators in read-chat-contract.ts route
+   * on it. A2 makes v2 the daemon-internal canonical form and rejects
+   * unrecognised values at provider load time.
+   */
+  contractVersion?: import('./transcript-v2.js').ChatContractVersion;
 }
 
+/**
+ * @deprecated Use {@link NativeHistoryConfig}. Retained as an alias for one
+ * release so external consumers that referenced the old name keep compiling.
+ */
+export type ProviderCanonicalHistoryConfig = NativeHistoryConfig;
+
 /**
  * Auto-implement spawn config — controls how the provider is spawned for autonomous AI-driven
  * provider script implementation (dev-auto-implement.ts).
@@ -1021,4 +1213,13 @@ export interface ProviderControlDef {
   order?: number;
  /** Hide this control when condition not met */
   hidden?: boolean;
+ /**
+  * FSM state ids in which this control should be visible (mirrors the spec's
+  * `control_bar[].visible_when_state`). When omitted the control is always
+  * visible. The daemon enforces this on click (FsmDriver.handleClickControl),
+  * so the web bar must mirror the same gating to avoid showing a button that
+  * the daemon would silently drop. Uses raw FSM state ids (e.g. 'idle',
+  * 'busy'), not the derived dashboard status.
+  */
+  visibleWhenState?: string[];
 }

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

@@ -63,8 +63,8 @@ export class ExtensionProviderInstance implements ProviderInstance {
         this.settings = context.settings || {};
         this.monitor.updateConfig({
             approvalAlert: this.settings.approvalAlert !== false,
-            longGeneratingAlert: this.settings.longGeneratingAlert !== false,
-            longGeneratingThresholdSec: this.settings.longGeneratingThresholdSec || 180,
+            noProgressAlert: (this.settings.noProgressAlert ?? this.settings.longGeneratingAlert) !== false,
+            noProgressThresholdSec: this.settings.noProgressThresholdSec ?? this.settings.longGeneratingThresholdSec ?? 180,
         });
     }
 
@@ -171,11 +171,15 @@ export class ExtensionProviderInstance implements ProviderInstance {
     }
 
     updateSettings(newSettings: Record<string, any>): void {
-        this.settings = { ...newSettings };
+        // Merge (not replace): a key omitted from newSettings preserves its existing
+        // value, a key present (even false) overrides. Mirrors cli/ide-provider-instance
+        // so partial updates do not wipe launch-time settings (e.g. autoApprove) while a
+        // full settings object still applies explicit values.
+        this.settings = { ...this.settings, ...newSettings };
         this.monitor.updateConfig({
             approvalAlert: this.settings.approvalAlert !== false,
-            longGeneratingAlert: this.settings.longGeneratingAlert !== false,
-            longGeneratingThresholdSec: this.settings.longGeneratingThresholdSec || 180,
+            noProgressAlert: (this.settings.noProgressAlert ?? this.settings.longGeneratingAlert) !== false,
+            noProgressThresholdSec: this.settings.noProgressThresholdSec ?? this.settings.longGeneratingThresholdSec ?? 180,
         });
     }
 
@@ -247,9 +251,10 @@ export class ExtensionProviderInstance implements ProviderInstance {
                 : 'immediate',
         });
 
- // Monitor check (cooldown based notification) — keep monitor events (long_generating etc)
+ // Monitor check (cooldown based notification) — keep monitor events (no_progress etc)
         const agentKey = `${this.type}:ext`;
-        const monitorEvents = this.monitor.check(agentKey, agentStatus, now, progressFingerprint);
+        const approvalPending = agentStatus === 'waiting_approval';
+        const monitorEvents = this.monitor.check(agentKey, agentStatus, now, progressFingerprint, approvalPending);
         for (const me of monitorEvents) {
             this.pushEvent({ event: me.type, agentKey: me.agentKey, message: me.message, elapsedSec: me.elapsedSec, timestamp: me.timestamp });
         }