@adhdev/daemon-core 0.9.82-rc.21 → 0.9.82-rc.211

package/dist/mesh/preview-freshness.d.ts

@@ -0,0 +1,18 @@
+export type PreviewFreshnessStatus = 'fresh' | 'stale' | 'unknown' | 'not_configured';
+export interface PreviewFreshness {
+    status: PreviewFreshnessStatus;
+    lastPreviewCommit: string | null;
+    currentMainCommit: string | null;
+    currentMainCommitSource: 'origin/main' | 'HEAD' | 'unknown';
+    recordPath: string;
+    lastDeployedAt?: string;
+    lastTarget?: string;
+    previewVersion?: string;
+    targets: Record<'npm' | 'server' | 'web', {
+        commit: string | null;
+        deployedAt?: string;
+        status: PreviewFreshnessStatus;
+    }>;
+    nextAction: string;
+}
+export declare function buildPreviewFreshness(repoRoot: string): PreviewFreshness;

package/dist/mesh/refine-config.d.ts

@@ -0,0 +1,215 @@
+export declare const MESH_REFINE_VALIDATION_CATEGORIES: readonly ["typecheck", "test", "lint", "build"];
+export type MeshRefineValidationCategory = typeof MESH_REFINE_VALIDATION_CATEGORIES[number];
+export interface RepoMeshRefineValidationCommandConfig {
+    /** Executable name or a whitespace-tokenized command string. Never executed through a shell. */
+    command: string;
+    /** Optional explicit argv. Prefer this over shell-like command strings. */
+    args?: string[];
+    category?: MeshRefineValidationCategory;
+    cwd?: string;
+    timeoutMs?: number;
+    outputLimitBytes?: number;
+    env?: Record<string, string>;
+}
+export interface RepoMeshRefineConfig {
+    version: 1;
+    /**
+     * Narrow Refinery opt-in for monorepos with submodule gitlinks.
+     * When true, Refinery may non-force publish unreachable submodule gitlink
+     * commits to the submodule remote main branch after validation and
+     * patch-equivalence pass, then verify remote-main reachability.
+     */
+    allowAutoPublishSubmoduleMainCommits?: boolean;
+    validation?: {
+        required?: boolean;
+        /**
+         * M2-2 (v2): how Refinery sources its bootstrap stage.
+         *   'inherit' (default) — consume the worktree_bootstrap config/state:
+         *     skip when the node's bootstrap is 'ready' (staleInputs unchanged),
+         *     run the worktree_bootstrap definition when stale/never-ran.
+         *   'skip' — no bootstrap stage at all (validation commands run as-is).
+         */
+        bootstrap?: 'inherit' | 'skip';
+        /**
+         * DEPRECATED (M2-2): define bootstrap once in
+         * .adhdev/worktree_bootstrap.json instead. Still honored when no
+         * worktree_bootstrap config exists, with a deprecation warning; when
+         * both exist the worktree_bootstrap config wins.
+         */
+        bootstrapCommands?: RepoMeshRefineValidationCommandConfig[];
+        commands?: RepoMeshRefineValidationCommandConfig[];
+    };
+}
+export interface MeshRefineValidationCommandPlan {
+    command: string;
+    args: string[];
+    displayCommand: string;
+    category: MeshRefineValidationCategory | 'custom';
+    source: string;
+    cwd?: string;
+    timeoutMs?: number;
+    outputLimitBytes?: number;
+    env?: Record<string, string>;
+}
+export interface MeshRefineConfigLoadResult {
+    config?: RepoMeshRefineConfig;
+    source: string;
+    sourceType: 'mesh_policy' | 'repo_file' | 'unavailable' | 'invalid';
+    path?: string;
+    error?: string;
+}
+export interface MeshRefineValidationPlan {
+    source: string;
+    sourceType: MeshRefineConfigLoadResult['sourceType'];
+    /** M2-2: how the bootstrap stage is sourced ('inherit' consumes worktree_bootstrap; 'skip' disables it). */
+    bootstrapMode: 'inherit' | 'skip';
+    bootstrapCommands: MeshRefineValidationCommandPlan[];
+    commands: MeshRefineValidationCommandPlan[];
+    rejectedCommands: Array<Record<string, unknown>>;
+    /** M2-2: deprecation notices (e.g. validation.bootstrapCommands present). */
+    deprecationWarnings: string[];
+    suggestions: RepoMeshRefineValidationCommandConfig[];
+    suggestedConfig?: RepoMeshRefineConfig;
+    unavailableReason?: string;
+}
+export declare const MESH_REFINE_CONFIG_LOCATIONS: string[];
+export declare const MESH_REFINE_CONFIG_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "ADHDev Repo Mesh Refinery Config";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["version"];
+    readonly properties: {
+        readonly version: {
+            readonly const: 1;
+        };
+        readonly allowAutoPublishSubmoduleMainCommits: {
+            readonly type: "boolean";
+            readonly default: false;
+            readonly description: "When true, Refinery may non-force publish submodule gitlink commits referenced by the refined root tree to each submodule origin/main after validation and patch-equivalence pass, then verify reachability.";
+        };
+        readonly validation: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly required: {
+                    readonly type: "boolean";
+                    readonly default: true;
+                };
+                readonly bootstrap: {
+                    readonly enum: readonly ["inherit", "skip"];
+                    readonly default: "inherit";
+                    readonly description: "M2-2 (v2): 'inherit' consumes the worktree_bootstrap config/state (skip when ready, rerun when stale); 'skip' disables the bootstrap stage entirely.";
+                };
+                readonly commands: {
+                    readonly type: "array";
+                    readonly minItems: 1;
+                    readonly maxItems: 8;
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["command"];
+                        readonly properties: {
+                            readonly command: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly args: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly category: {
+                                readonly enum: readonly ["typecheck", "test", "lint", "build", "custom"];
+                            };
+                            readonly cwd: {
+                                readonly type: "string";
+                            };
+                            readonly timeoutMs: {
+                                readonly type: "number";
+                                readonly minimum: 1000;
+                                readonly maximum: 600000;
+                            };
+                            readonly outputLimitBytes: {
+                                readonly type: "number";
+                                readonly minimum: 1024;
+                                readonly maximum: 1048576;
+                            };
+                            readonly env: {
+                                readonly type: "object";
+                                readonly additionalProperties: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                };
+                readonly bootstrapCommands: {
+                    readonly type: "array";
+                    readonly maxItems: 4;
+                    readonly description: "DEPRECATED: define bootstrap once in .adhdev/worktree_bootstrap.json. Honored only when no worktree_bootstrap config exists (with a deprecation warning); worktree_bootstrap wins when both exist.";
+                    readonly items: {
+                        readonly type: "object";
+                        readonly additionalProperties: false;
+                        readonly required: readonly ["command"];
+                        readonly properties: {
+                            readonly command: {
+                                readonly type: "string";
+                                readonly minLength: 1;
+                            };
+                            readonly args: {
+                                readonly type: "array";
+                                readonly items: {
+                                    readonly type: "string";
+                                };
+                            };
+                            readonly category: {
+                                readonly enum: readonly ["typecheck", "test", "lint", "build", "custom"];
+                            };
+                            readonly cwd: {
+                                readonly type: "string";
+                            };
+                            readonly timeoutMs: {
+                                readonly type: "number";
+                                readonly minimum: 1000;
+                                readonly maximum: 600000;
+                            };
+                            readonly outputLimitBytes: {
+                                readonly type: "number";
+                                readonly minimum: 1024;
+                                readonly maximum: 1048576;
+                            };
+                            readonly env: {
+                                readonly type: "object";
+                                readonly additionalProperties: {
+                                    readonly type: "string";
+                                };
+                            };
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+export declare function isMeshConfigRecord(value: unknown): value is Record<string, unknown>;
+export declare function normalizeMeshCommandConfig(entry: unknown, source: string): {
+    command?: MeshRefineValidationCommandPlan;
+    rejected?: Record<string, unknown>;
+};
+export declare function validateMeshRefineConfig(config: unknown, source?: string): {
+    valid: boolean;
+    errors: string[];
+    bootstrapCommands: MeshRefineValidationCommandPlan[];
+    commands: MeshRefineValidationCommandPlan[];
+    rejectedCommands: Array<Record<string, unknown>>;
+    bootstrapMode: 'inherit' | 'skip';
+    deprecationWarnings: string[];
+};
+export declare function loadMeshRefineConfig(mesh: any, workspace: string): MeshRefineConfigLoadResult;
+export declare function suggestMeshRefineConfig(mesh: any, workspace: string): {
+    suggestions: RepoMeshRefineValidationCommandConfig[];
+    suggestedConfig?: RepoMeshRefineConfig;
+};
+export declare function resolveMeshRefineValidationPlan(mesh: any, workspace: string): MeshRefineValidationPlan;

package/dist/mesh/worktree-bootstrap-config.d.ts

@@ -0,0 +1,135 @@
+import { type MeshRefineValidationCommandPlan, type RepoMeshRefineValidationCommandConfig } from './refine-config.js';
+import type { MeshAsyncJobLifecycle } from '../repo-mesh-types.js';
+export type WorktreeBootstrapStatus = 'ready' | 'running' | 'failed' | 'not_configured' | 'disabled' | 'stale';
+export interface RepoMeshWorktreeBootstrapConfig {
+    version: 1;
+    enabled?: boolean;
+    runOnClone?: boolean;
+    required?: boolean;
+    commands?: RepoMeshRefineValidationCommandConfig[];
+    staleInputs?: string[];
+}
+export interface WorktreeBootstrapState extends MeshAsyncJobLifecycle {
+    status: WorktreeBootstrapStatus;
+    required: boolean;
+    configSource?: string;
+    configSourceType?: 'repo_file' | 'mesh_policy' | 'unavailable' | 'invalid';
+    lastCommand?: string;
+    exitCode?: number | null;
+    commandsRun?: Array<Record<string, unknown>>;
+    staleInputs?: string[];
+    /**
+     * M2-1: sha256 per staleInputs path recorded when the bootstrap reached
+     * 'ready'. evaluateWorktreeBootstrapState compares current file hashes
+     * against this to detect staleness (e.g. base merge changed a lockfile).
+     * Missing files hash to the literal 'absent'.
+     */
+    staleInputsDigest?: Record<string, string>;
+    /** M2-1: why an evaluated state resolved to stale (digest_mismatch | never_ran). */
+    staleReason?: string;
+}
+export interface WorktreeBootstrapConfigLoadResult {
+    config?: RepoMeshWorktreeBootstrapConfig;
+    source: string;
+    sourceType: 'repo_file' | 'mesh_policy' | 'unavailable' | 'invalid';
+    path?: string;
+    error?: string;
+}
+export declare const MESH_WORKTREE_BOOTSTRAP_CONFIG_LOCATIONS: string[];
+export declare const MESH_WORKTREE_BOOTSTRAP_CONFIG_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "ADHDev Repo Mesh Worktree Bootstrap Config";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["version"];
+    readonly properties: {
+        readonly version: {
+            readonly const: 1;
+        };
+        readonly enabled: {
+            readonly type: "boolean";
+            readonly default: true;
+        };
+        readonly runOnClone: {
+            readonly type: "boolean";
+            readonly default: true;
+        };
+        readonly required: {
+            readonly type: "boolean";
+            readonly default: true;
+        };
+        readonly staleInputs: {
+            readonly type: "array";
+            readonly maxItems: 16;
+            readonly items: {
+                readonly type: "string";
+                readonly minLength: 1;
+            };
+        };
+        readonly commands: {
+            readonly type: "array";
+            readonly minItems: 1;
+            readonly maxItems: 4;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["command"];
+                readonly properties: {
+                    readonly command: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly args: {
+                        readonly type: "array";
+                        readonly items: {
+                            readonly type: "string";
+                        };
+                    };
+                    readonly category: {
+                        readonly enum: readonly ["typecheck", "test", "lint", "build", "custom"];
+                    };
+                    readonly cwd: {
+                        readonly type: "string";
+                    };
+                    readonly timeoutMs: {
+                        readonly type: "number";
+                        readonly minimum: 1000;
+                        readonly maximum: 600000;
+                    };
+                    readonly outputLimitBytes: {
+                        readonly type: "number";
+                        readonly minimum: 1024;
+                        readonly maximum: 1048576;
+                    };
+                    readonly env: {
+                        readonly type: "object";
+                        readonly additionalProperties: {
+                            readonly type: "string";
+                        };
+                    };
+                };
+            };
+        };
+    };
+};
+export declare function validateMeshWorktreeBootstrapConfig(config: unknown, source?: string): {
+    valid: boolean;
+    errors: string[];
+    commands: MeshRefineValidationCommandPlan[];
+    rejectedCommands: Array<Record<string, unknown>>;
+};
+export declare function loadMeshWorktreeBootstrapConfig(mesh: any, workspace: string): WorktreeBootstrapConfigLoadResult;
+/** M2-1: hash staleInputs files so 'ready' can be invalidated when they change. */
+export declare function computeStaleInputsDigest(workspace: string, staleInputs: string[] | undefined): Record<string, string>;
+/**
+ * M2-1: the official bootstrap state contract. Resolves the effective state
+ * for a node workspace from config presence + the persisted last-run state +
+ * a staleInputs digest comparison. Read-only — never runs commands.
+ *
+ *   ready          — last run succeeded and staleInputs are unchanged
+ *   stale          — never ran, or a staleInputs file changed since 'ready'
+ *   running/failed — persisted lifecycle state passes through
+ *   not_configured / disabled / (invalid → failed) — from config resolution
+ */
+export declare function evaluateWorktreeBootstrapState(mesh: any, workspace: string, persisted?: WorktreeBootstrapState | null): WorktreeBootstrapState;
+export declare function runMeshWorktreeBootstrap(mesh: any, workspace: string): Promise<WorktreeBootstrapState>;

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

@@ -44,6 +44,8 @@ export declare class AcpProviderInstance implements ProviderInstance {
     private partialBlocks;
     /** Tool calls collected during current turn */
     private turnToolCalls;
+    /** Guard: prevent concurrent sendPrompt calls from racing on shared state */
+    private _sendPromptInFlight;
     private errorMessage;
     private errorReason;
     private stderrBuffer;

package/dist/providers/approval-utils.d.ts

@@ -4,4 +4,17 @@ export declare function pickApprovalButton(buttons: string[] | null | undefined,
     index: number;
     label: string;
 };
+export declare function pickAutoApprovalButton(buttons: string[] | null | undefined): {
+    index: number;
+    label: string;
+};
 export declare function formatAutoApprovalMessage(modalMessage?: string, buttonLabel?: string): string;
+/**
+ * Returns true when the given text (e.g. last assistant message content, or
+ * the tail of the PTY screen) looks like an active approval/input prompt
+ * rather than a completed assistant response. Used to prevent false
+ * idle/completion events when Claude Code surfaces a "Do you want to proceed?"
+ * style prompt that the PTY parser captures as an assistant turn while the
+ * session is still awaiting user input.
+ */
+export declare function looksLikeActiveApprovalPromptText(content: string): boolean;

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

@@ -45,15 +45,18 @@ export declare class CliProviderInstance implements ProviderInstance {
     private monitor;
     private generatingDebounceTimer;
     private generatingDebouncePending;
-    private lastApprovalEventAt;
+    private lastApprovalEventFingerprint;
     private autoApproveBusy;
     private autoApproveBusyTimer;
+    private lastAutoApprovalSignature;
     private controlValues;
     private summaryMetadata;
     private appliedEffectKeys;
     private historyWriter;
     private runtimeMessages;
     private lastPersistedHistoryMessages;
+    private lastAcknowledgedUserInputAt;
+    private externalBusyIdleFingerprint;
     private lastNativeSourceCanonicalCheckAt;
     private lastNativeSourceCanonicalCacheKey;
     private cachedSqliteDb;
@@ -63,6 +66,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     private suppressIdleHistoryReplay;
     private errorMessage;
     private errorReason;
+    private activeInteractivePrompt;
     private presentationMode;
     private providerSessionId?;
     private launchMode;
@@ -93,17 +97,47 @@ 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;
+    }): 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.
+     */
+    detachMeshAssignment(): void;
     onEvent(event: string, data?: any): void;
+    recordAcknowledgedUserInput(input: InputEnvelope | string): void;
     dispose(): void;
     private completedDebounceTimer;
     private completedDebouncePending;
+    private lastExternalCompletionProbe;
     private enforceFreshSessionLaunchIfNeeded;
     private completionHasFinalAssistantMessage;
+    private buildExternalTranscriptProbe;
+    private recordPendingTranscriptProbe;
+    private readExternalCompletionMessages;
+    private completionFinalAssistantEvidence;
+    private completionFinalSummary;
+    private externalNativeFinalFingerprint;
+    private getExternalNativeFinalReconciliation;
+    private buildCompletedFinalizationDiagnostic;
     private hasAdapterPendingResponse;
     private shouldSuppressStaleParsedBusyStatus;
-    private getCompletedFinalizationBlockReason;
+    private getCompletedFinalizationBlock;
     private scheduleCompletedDebounceFlush;
     private flushCompletedDebounceIfFinalized;
     private maybeAutoApproveStatus;
@@ -127,6 +161,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'].
@@ -429,8 +524,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 +664,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 +698,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).