@adhdev/daemon-core 0.9.82-rc.44 → 0.9.82-rc.440

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

@@ -16,6 +16,19 @@ type PersistableCliHistoryMessage = {
     senderName?: string;
     receivedAt?: number;
 };
+/**
+ * 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 declare function computeTurnAnchoredDurationMs(engineTurnStartedAt: number | undefined, generatingStartedAt: number, now: number): {
+    durationMs: number;
+    anchor: 'turn-start' | 'generatingStartedAt' | 'none';
+};
 export declare function buildCliStructuredInputPrompt(input: InputEnvelope, options?: {
     materializeDir?: string;
 }): string;
@@ -36,24 +49,80 @@ export declare class CliProviderInstance implements ProviderInstance {
     private cliArgs;
     readonly type: string;
     readonly category: "cli";
+    /**
+     * Quiet period an approval modal's signature must be stable before
+     * auto-approve sends the approve key. Guards against firing on a prompt
+     * that is still streaming into the PTY (the "resolves too fast" symptom):
+     * while the modal text/buttons are still changing, every frame yields a
+     * new signature and the settle clock restarts. Once the prompt finishes
+     * rendering the signature holds and the key is sent after this window.
+     * Bounded + small so genuine approvals stay timely. The FSM is already
+     * authoritative over the `waiting_approval` state; this only delays the
+     * keystroke until the modal *content* has settled.
+     */
+    private static readonly AUTO_APPROVE_SETTLE_MS;
+    /**
+     * Busy-side hysteresis for the settle gate. A momentary `generating` flip
+     * while the SAME approval modal's button block is still on screen (its
+     * question line scrolled out of the captured frame, only the buttons + a
+     * residual `esc to interrupt` spinner remain) briefly reports
+     * status!=waiting_approval. Without hysteresis that flip wipes the settle
+     * clock, and the modal→generating→modal flap restarts the 600ms window
+     * every time so auto-approve never fires. We keep the in-progress settle
+     * gate warm across an inactive blip up to this bound; only once the modal
+     * has genuinely stayed gone this long (a real resolution → idle) is the
+     * gate cleared. Bounded so a genuinely new, later approval still re-settles
+     * from scratch rather than firing on a stale timestamp.
+     */
+    private static readonly AUTO_APPROVE_GATE_HYSTERESIS_MS;
+    /**
+     * STATUS-MISMATCH: upper bound on how long the auto-approve→`generating` SURFACE
+     * mask may hide a worker's `waiting_approval` (status + activeModal) before we give
+     * up and surface the real prompt. The mask exists because auto-approve is expected
+     * to resolve the modal momentarily; but if it STALLS without ever calling
+     * resolveModal — the modal signature never settles for AUTO_APPROVE_SETTLE_MS (a
+     * perpetually-flapping/streaming prompt), no concrete modal is ever captured, or the
+     * modal is a picker/non-affirmative we never auto-pick — the mask would persist
+     * forever and read_chat / mesh_status / the dashboard would NEVER see the pending
+     * approval (the coordinator cannot mesh_approve what it cannot see). Once an episode
+     * exceeds this bound we stop masking. Generously larger than
+     * AUTO_APPROVE_SETTLE_MS (600) + AUTO_APPROVE_GATE_HYSTERESIS_MS (1500) so a
+     * legitimately slow-settling / blip-flapping prompt is never unmasked early; a
+     * genuine never-resolving stall surfaces within this window. The settle gate keeps
+     * running underneath, so a prompt that finally stabilises still auto-approves, and
+     * mesh_approve (raw FSM, unmasked) works throughout.
+     */
+    private static readonly AUTO_APPROVE_MASK_STALL_MS;
     private adapter;
     private context;
     private events;
     private lastStatus;
+    private agentReadyEmitted;
     private generatingStartedAt;
+    private fastCollapseSynthesizedTaskId;
+    private startupGraceCollapseAt;
     private settings;
     private monitor;
     private generatingDebounceTimer;
     private generatingDebouncePending;
-    private lastApprovalEventAt;
+    private lastApprovalEventFingerprint;
     private autoApproveBusy;
     private autoApproveBusyTimer;
+    private lastAutoApprovalSignature;
+    private pendingAutoApprovalSignature;
+    private pendingAutoApprovalSince;
+    private autoApproveSettleTimer;
+    private autoApproveInactiveSince;
+    private autoApproveMaskSince;
+    private readonly manualAttendance;
     private controlValues;
     private summaryMetadata;
     private appliedEffectKeys;
     private historyWriter;
     private runtimeMessages;
     private lastPersistedHistoryMessages;
+    private lastAcknowledgedUserInputAt;
+    private recentUserInputAcks;
     private lastNativeSourceCanonicalCheckAt;
     private lastNativeSourceCanonicalCacheKey;
     private cachedSqliteDb;
@@ -63,6 +132,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     private suppressIdleHistoryReplay;
     private errorMessage;
     private errorReason;
+    private activeInteractivePrompt;
     private presentationMode;
     private providerSessionId?;
     private launchMode;
@@ -93,20 +163,185 @@ export declare class CliProviderInstance implements ProviderInstance {
     setPresentationMode(mode: 'terminal' | 'chat'): void;
     getPresentationMode(): 'terminal' | 'chat';
     getHotChatSessionState(): HotChatSessionState;
-    getSessionModalState(): SessionModalState;
+    getSessionModalState(sessionId?: string): SessionModalState;
     updateSettings(newSettings: Record<string, any>): void;
+    /**
+     * Stamp a direct-dispatch mesh assignment on this instance.
+     * setupMeshEventForwarding reads settings.meshNodeFor + meshActiveTaskId to
+     * route generating_completed back to the originating coordinator. Without
+     * this stamp, mesh_send_task --direct targets a plain CLI session whose
+     * completion events silently drop because the forwarder has nothing to
+     * match against.
+     */
+    attachMeshAssignment(assignment: {
+        meshId: string;
+        nodeId?: string;
+        taskId?: string;
+        coordinatorDaemonId?: string;
+        coordinatorSessionId?: string;
+    }): void;
+    /**
+     * Clear a previously-attached mesh assignment after the task reaches a
+     * terminal state. Leaving meshNodeFor pinned would route this session's
+     * subsequent unrelated turns (e.g. ad-hoc dashboard chats) to the
+     * coordinator as if they were task completions.
+     *
+     * MESHID-DROP-ON-DETACH (Fix C): a coordinator-LAUNCHED worker session
+     * (launchedByCoordinator) holds its mesh membership (meshNodeFor / meshNodeId /
+     * meshCoordinatorDaemonId) at the SESSION level — set once at launch
+     * (mesh_launch_session / queue auto-launch), independent of any single task.
+     * The original detach wiped meshNodeFor + meshNodeId together with the
+     * task-level meshActiveTaskId, so the FIRST task completion stripped the
+     * membership and EVERY subsequent completion forwarded with meshId absent —
+     * resolveWorkerDelegateRouting fell to mesh_unresolved and the coordinator
+     * rejected the forward "meshId required". For a launched member we therefore
+     * clear ONLY the task-level marker (meshActiveTaskId) and preserve the
+     * session-level membership so its next task's completion still resolves.
+     * A task-less ad-hoc turn on a preserved-membership session is NOT misrouted:
+     * its completion carries no taskId and the session holds no active assignment,
+     * so the forwarder's WARMUPGAP guard skips the dispatch-row flip (it only
+     * injects a benign task-less notification). A NON-launched session (a plain CLI
+     * session adopted by mesh_send_task --direct, launchedByCoordinator falsy)
+     * keeps the original full clear so an ad-hoc session is never left pinned.
+     */
+    detachMeshAssignment(): void;
+    /**
+     * The resolved modal-park status of this session, or null when it is not
+     * parked on a modal awaiting a human answer. Mirrors the overlay logic in
+     * getState(): an active AskUserQuestion interactive prompt resolves to
+     * waiting_choice; otherwise the adapter's waiting_approval (tool consent)
+     * counts — UNLESS auto-approve will dismiss it, in which case the session is
+     * effectively generating and is NOT modal-parked. This is the single signal
+     * the mesh force-inject guard consults, and the same status string the
+     * reconcile loop reads off get_status_metadata. Lowercase literals only —
+     * the SessionStatus enum is forked across modules and waiting_choice is
+     * absent from some of them.
+     */
+    resolveModalParkStatus(): 'waiting_choice' | 'waiting_approval' | null;
+    /**
+     * NOTIF-HELD-DRAIN: true when this `waiting_approval` is a routine, transient tool-consent
+     * of an autonomously-progressing mesh session rather than a genuine human-await modal —
+     * i.e. it is a mesh coordinator/worker session, a turn is actively in flight
+     * (hasAdapterPendingResponse), and no human is attending it by hand. Such a consent is
+     * driven to resolution by the harness/operator as part of the in-flight turn, so holding
+     * the mesh's completion events behind it (modal_parked) is the false-positive that stalls
+     * delivery. Narrow by design: manual attendance or a non-progressing session falls through
+     * to the genuine-modal classification.
+     */
+    private isTransientToolConsent;
+    /** True when this session is parked on a modal awaiting a human answer. */
+    isModalParked(): boolean;
+    /**
+     * PTY-OVERTRUST-DRAIN (Defect B). The deliverability/drain status the mesh
+     * reconcile loop must consult — the RAW adapter turn-state, with the
+     * auto-approve "hold-idle" visual mask STRIPPED.
+     *
+     * getState().status overlays `autoApproveHoldIdle`/`autoApproveActive` to paint a
+     * genuinely-idle adapter as `generating` (a UI-flicker suppression while an
+     * auto-approve key-press settles — see getState() ~:800). That mask is correct
+     * for the dashboard, but the reconcile loop trusts it as "the coordinator is
+     * busy" and therefore HOLDS a worker's completion under
+     * `generating_no_idle_coordinator` even though the coordinator's PTY is at a real
+     * turn end and would accept the inject as a turn — the completion is stranded.
+     *
+     * This accessor reports the drain truth instead:
+     *   - 'modal_parked' — a GENUINE human-await modal (AskUserQuestion / a non-
+     *     transient tool-consent). Still excluded from drain (a force-inject here
+     *     writes raw keystrokes the modal eats → data corruption). Mirrors
+     *     isModalParked(), evaluated first so a parked session never reads idle.
+     *   - 'idle' — the RAW adapter is at a turn end (adapter.getStatus(allowParse:false)
+     *     === 'idle') and the session is not modal-parked. Drain-eligible REGARDLESS
+     *     of the auto-approve mask. This is the case the mask used to hide.
+     *   - 'generating' — the raw adapter is genuinely mid-turn. Held (a raw PTY write
+     *     into a generating claude-cli is not consumed as a turn → data loss). The
+     *     intentional removal of force-inject-into-generating is preserved.
+     *   - 'other' — any other raw status (error / starting / waiting_choice handled by
+     *     modal-park above). Not a drain target.
+     *
+     * Uses allowParse:false (engine.activeModal only, side-effect-free) so it never
+     * mutates the very auto-approve mask state the diagnostics read.
+     */
+    getDrainStatus(): 'idle' | 'generating' | 'modal_parked' | 'other';
     onEvent(event: string, data?: any): void;
+    recordAcknowledgedUserInput(input: InputEnvelope | string): void;
+    /** Drop user-input ack entries older than the dedup window so the map can't grow unbounded. */
+    private pruneRecentUserInputAcks;
     dispose(): void;
     private completedDebounceTimer;
     private completedDebouncePending;
+    private lastExternalCompletionProbe;
     private enforceFreshSessionLaunchIfNeeded;
     private completionHasFinalAssistantMessage;
+    private buildExternalTranscriptProbe;
+    private recordPendingTranscriptProbe;
+    private readExternalCompletionMessages;
+    private completionFinalAssistantEvidence;
+    private completionFinalSummary;
+    private buildCompletedFinalizationDiagnostic;
     private hasAdapterPendingResponse;
     private shouldSuppressStaleParsedBusyStatus;
-    private getCompletedFinalizationBlockReason;
+    private getCompletedFinalizationBlock;
+    private hasApprovalResolutionEvidence;
+    private approvalResolutionFinalizationBlock;
     private scheduleCompletedDebounceFlush;
+    private isMeshWorkerSession;
+    /**
+     * ARCH-REFACTOR R1: the taskId to attribute the CURRENTLY-completing turn to.
+     * Prefers the per-turn binding (engine.currentTurnTaskId, set when the turn was
+     * submitted and surviving until the next turn starts) over the last-write-wins
+     * session scalar (settings.meshActiveTaskId). The scalar is retained only as a
+     * backward-compat alias for the "current/last assignment" and is the source of the
+     * NOTIF-MISDELIVER / TASK-MSG-MISROUTE race: a second task attaching before this
+     * turn completes overwrites it. Returns undefined for a non-task ad-hoc turn.
+     */
+    private completingTurnTaskId;
+    private meshTraceCtx;
     private flushCompletedDebounceIfFinalized;
     private maybeAutoApproveStatus;
+    /**
+     * Re-drive the auto-approve check after the settle quiet window elapses.
+     * The PTY may have gone silent once the approval prompt finished painting,
+     * so no status-change frame is guaranteed to re-enter maybeAutoApproveStatus
+     * — this timer-driven re-check picks up the now-settled modal and fires.
+     * Deliberately lighter than detectStatusTransition(): it only re-evaluates
+     * the approval decision; the next real PTY frame refreshes visible status.
+     */
+    private recheckAutoApproveSettled;
+    /**
+     * Emit the queue-claim agent:ready event at most once per session. Both the
+     * boot-time starting→idle one-shot and the fsmReadySeen re-arm call this; the
+     * agentReadyEmitted guard ensures the second caller is a no-op so a worker is
+     * never claimed twice and a queued task is never double-dispatched.
+     */
+    private emitAgentReadyOnce;
+    /**
+     * GENERATING-BOUNDARY synthetic emit for a first turn that started AND finished
+     * inside the startup-grace window without the FSM ever observing a 'generating'
+     * frame (an unobservably-fast turn). Synthesizes the agent:generating_started +
+     * agent:generating_completed pair so the mesh coordinator learns the worker went
+     * idle. Returns true iff it synthesized.
+     *
+     * Two callers share this defense line:
+     *  - 'startup_grace_fast_collapse' — the starting→idle transition (the FSM whose
+     *    spec lacks/hadn't-synced the starting→busy edge collapses starting→idle
+     *    directly, with no intervening 'generating' frame).
+     *  - 'startup_grace_idle_turn_collapse' — the idle→idle no-status-change poll
+     *    (the launch settle already drained starting→idle BEFORE the first turn, so
+     *    the turn runs+completes while status stays 'idle' the whole time and
+     *    detectStatusTransition never re-enters its change block — the live rc.403
+     *    Probe1 miss).
+     *
+     * False-positive safety (must NOT fire on a benign boot): currentTurnTaskId is
+     * set ONLY by onTurnStarted (a real turn STARTED this boot) and persists past
+     * completion, so it excludes a true idle boot (null) and a queued-pending first
+     * turn that only runs after grace (onTurnStarted not yet called → null).
+     * !hasAdapterPendingResponse() excludes a turn still mid-flight. generating
+     * never armed (generatingStartedAt===0 && !generatingDebouncePending) means the
+     * whole idle→busy→idle never happened for this turn. The once-per-turn guard
+     * (fastCollapseSynthesizedTaskId) keeps the re-polled idle-stayed caller from
+     * re-emitting every poll.
+     */
+    private maybeSynthesizeStartupGraceCollapse;
     private detectStatusTransition;
     private pushEvent;
     private flushEvents;
@@ -117,6 +352,18 @@ export declare class CliProviderInstance implements ProviderInstance {
     get cliType(): string;
     get cliName(): string;
     private shouldAutoApprove;
+    /** @see ProviderInstance.noteManualInteraction */
+    noteManualInteraction(now?: number): void;
+    /**
+     * Whether auto-approve should be treated as active *right now* for display
+     * and firing decisions: the configured intent AND the user is not currently
+     * attending this session by hand. When a human is attending, auto-approve is
+     * held so the modal stays visible and they can drive it via the controlbar.
+     * Provider-agnostic — the attendance signal is the command set, never any
+     * CLI-specific modal text.
+     */
+    private autoApproveEffectivelyActive;
+    private autoApproveMaskStalled;
     private recordAutoApproval;
     recordApprovalSelection(buttonText: string): void;
     private formatMarkerTimestamp;
@@ -127,6 +374,8 @@ export declare class CliProviderInstance implements ProviderInstance {
     private mergeConversationMessages;
     private formatApprovalRequestMessage;
     private promoteProviderSessionId;
+    private shouldHydrateExistingProviderHistory;
+    private shouldSuppressFreshLaunchStartupReplay;
     private syncCanonicalSavedHistoryIfNeeded;
     private restorePersistedHistoryFromCurrentSession;
     private getProbeDirectories;

package/dist/providers/contracts.d.ts

@@ -10,6 +10,14 @@ import type { ProviderSummaryMetadata } from '../shared-types.js';
 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;
@@ -294,10 +302,89 @@ 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;
@@ -378,6 +465,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'].
@@ -394,6 +489,16 @@ 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[];
     /** Delay before submitting typed CLI input (provider-specific TUI tuning) */
     sendDelayMs?: number;
     /** Submit key used after typing into CLI PTY (default: carriage return) */
@@ -429,8 +534,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;
     /**
@@ -561,20 +674,25 @@ 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'. */
     listSessions?: string;
 }
 /**
- * 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. */
@@ -590,7 +708,23 @@ 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).
@@ -863,4 +997,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/dist/providers/external-sources.d.ts

@@ -0,0 +1,71 @@
+export interface ExternalSource {
+    /** Unique short identifier, e.g. "@vendor-x". User-supplied or derived from the URL. */
+    name: string;
+    /** Full git URL (https://, git@, …). */
+    url: string;
+    /** Branch / tag / commit-ish to track. Defaults to `main`. */
+    ref: string;
+    /** ISO timestamp when first registered. */
+    addedAt: string;
+}
+export interface ExternalSourcesFile {
+    /** Schema version — bump if shape changes. */
+    schema: 1;
+    sources: ExternalSource[];
+}
+/**
+ * Per-type active source selection. Only types reachable from more than
+ * one source need an entry — single-source types have no ambiguity.
+ *
+ * Shape: { active: { "<type>": "<source-name>" } }
+ */
+export interface ProvidersActiveFile {
+    schema: 1;
+    active: Record<string, string>;
+}
+export declare function externalRoot(): string;
+export declare function sourcesFilePath(): string;
+export declare function activeFilePath(): string;
+export declare function loadExternalSources(): ExternalSourcesFile;
+export declare function saveExternalSources(file: ExternalSourcesFile): void;
+export declare function loadProvidersActive(): ProvidersActiveFile;
+export declare function saveProvidersActive(file: ProvidersActiveFile): void;
+/**
+ * Derive a short identifier from a git URL when the user didn't supply one.
+ *   https://github.com/vendor/extra-providers.git → "@vendor-extra-providers"
+ *   git@github.com:vendor/extra-providers       → "@vendor-extra-providers"
+ *
+ * Idempotent; safe to call before validation since it produces a string
+ * regardless of input shape.
+ */
+export declare function deriveSourceName(url: string): string;
+/**
+ * Return the per-source category/type tree currently on disk under
+ * ~/.adhdev/external/<source>/. Used by the conflict detector and by
+ * list_provider_sources.
+ */
+export interface SourceInventoryEntry {
+    sourceName: string;
+    /** Map: category → list of provider types. */
+    providers: Record<string, string[]>;
+}
+export declare function inventoryExternalSources(): SourceInventoryEntry[];
+/**
+ * For a given category+type, list every source that currently exposes it.
+ * Returns source names in disk-walk order; callers can use the first one
+ * when no explicit active selection exists.
+ */
+export declare function sourcesProviding(category: string, type: string): string[];
+/**
+ * Resolve which source should be active for a given category+type.
+ *   - If exactly one source provides it → that source.
+ *   - If multiple sources provide it → the one named in providers-active.json
+ *     (when present) or null (ambiguous; loader should warn and pick
+ *     the first deterministically so daemon doesn't refuse to boot).
+ *   - If none → null.
+ */
+export declare function resolveActiveSource(category: string, type: string, activeFile?: ProvidersActiveFile): {
+    source: string | null;
+    ambiguous: boolean;
+    candidates: string[];
+};