@adhdev/daemon-core 0.9.82-rc.46 → 0.9.82-rc.461

package/src/providers/provider-loader.ts

@@ -18,10 +18,12 @@ import * as path from 'path';
 import * as os from 'os';
 import * as chokidar from 'chokidar';
 import { registerIDEDefinition } from '../detection/ide-detector.js';
+import { sha256Hex } from '../system/hash.js';
 import { LOG } from '../logging/logger.js';
 import { VersionArchive } from './version-archive.js';
 import type {
   ProviderCompatibilityEntry,
+  ProviderControlDef,
   ProviderModule,
   ProviderCategory,
   ProviderScripts,
@@ -30,8 +32,39 @@ import type {
   ResolvedProvider,
 } from './contracts.js';
 import { validateProviderDefinition } from './provider-schema.js';
+import {
+  loadProvidersActive,
+  resolveActiveSource,
+} from './external-sources.js';
 import type { ProviderSourceMode } from '../config/config.js';
+import {
+  resolveRegistryBaseUrl,
+  resolveProviderTarballUrl,
+  resolveProviderTarballTarget,
+} from '../config/registry-resolver.js';
 import type { ProviderSourceConfigSnapshot, ProviderUserDirSource } from '../config/provider-source-config.js';
+import { executeNativeHistory } from './spec/native-history-executor.js';
+import { createNativeHistoryDispatcher, type ReaderId } from './native-history/dispatcher.js';
+
+/**
+ * Adds a provider-script root to the require whitelist. Wrapped in a
+ * try/catch + null check so a loader hot-path can't crash on a path
+ * that doesn't exist yet or one the whitelist hook rejects.
+ *
+ * The require-whitelist module is loaded lazily on first call. Eagerly
+ * top-level importing it pulls `node:fs.realpathSync.native` into
+ * module evaluation, which breaks unit tests that partially mock `fs`
+ * (e.g. test/commands/get-logs-incremental.test.ts mocks only
+ * existsSync + readFileSync). Lazy load keeps that mock surface valid.
+ */
+function registerProviderScriptRootSafely(root: string | null | undefined): void {
+  if (!root || typeof root !== 'string') return;
+  try {
+    const { registerProviderScriptRoot } =
+      require('./sdk/v1/sandbox/require-whitelist.js') as typeof import('./sdk/v1/sandbox/require-whitelist.js');
+    registerProviderScriptRoot(root);
+  } catch { /* boot-time only — swallow */ }
+}
 
 interface ProviderAvailabilityState {
   installed: boolean;
@@ -61,6 +94,78 @@ export interface MachineProviderConfig {
   lastVerification?: MachineProviderCheckResult;
 }
 
+/**
+ * Translate a spec `control_bar` array into the web-facing
+ * `ProviderControlDef[]` shape the dashboard renders.
+ *
+ * The two shapes are distinct: `control_bar` entries are daemon-side
+ * `{ id, label, visible_when_state, action }` records driving
+ * SpecCliAdapter.invokeScript, while the dashboard's chat bar reads
+ * `ProviderControlDef` (`{ id, type, label, placement, ... }`). Spec
+ * providers (claude-cli / codex-cli) historically declared *only*
+ * `control_bar`, so the dashboard saw no controls at all — the Model / Mode
+ * pickers never rendered. This bridges that gap without changing how the
+ * controls actually dispatch.
+ *
+ * Script-name contract: the dashboard sends the control's
+ * `listScript` / `setScript` / `invokeScript` name through
+ * `invoke_provider_script`, which gates on `provider.scripts[<name>]` and then
+ * routes to `SpecCliAdapter.invokeScript(<name>)` — which matches the name
+ * against `control_bar[].id`. So every synthesized script name MUST equal the
+ * control id (the loader stubs `provider.scripts[id]` from the same source).
+ *
+ * Mapping:
+ *   open_picker  → select (dynamic): list + set both keyed on the control id;
+ *                  the adapter distinguishes LIST vs SELECT by the presence of
+ *                  a choice arg, so one id serves both roles.
+ *   send_keys    → action: one-shot keystroke (stop, cycle_mode).
+ *   attach_image → skipped: it needs an image blob from a file picker, not a
+ *                  bare bar button; surfacing it as an `action` would only
+ *                  produce a button that errors with "requires args.blob".
+ */
+function synthesizeControlsFromControlBar(specControls: any[]): ProviderControlDef[] {
+  const out: ProviderControlDef[] = [];
+  specControls.forEach((ctl, index) => {
+    const id = typeof ctl?.id === 'string' ? ctl.id.trim() : '';
+    const actionType = ctl?.action?.type;
+    if (!id || !actionType) return;
+    const label = typeof ctl?.label === 'string' && ctl.label.trim() ? ctl.label : id;
+    // Preserve the spec's state gating so the web bar can mirror the daemon's
+    // FsmDriver.handleClickControl enforcement (otherwise the button renders in
+    // states where the daemon would silently drop the click).
+    const visibleWhenState = Array.isArray(ctl?.visible_when_state)
+      ? ctl.visible_when_state.filter((s: unknown): s is string => typeof s === 'string')
+      : undefined;
+    if (actionType === 'open_picker') {
+      out.push({
+        id,
+        type: 'select',
+        label,
+        placement: 'bar',
+        dynamic: true,
+        listScript: id,
+        setScript: id,
+        readFrom: id,
+        order: index,
+        ...(visibleWhenState && visibleWhenState.length > 0 ? { visibleWhenState } : {}),
+      });
+    } else if (actionType === 'send_keys') {
+      out.push({
+        id,
+        type: 'action',
+        label,
+        placement: 'bar',
+        invokeScript: id,
+        resultDisplay: 'none',
+        order: index,
+        ...(visibleWhenState && visibleWhenState.length > 0 ? { visibleWhenState } : {}),
+      });
+    }
+    // attach_image intentionally skipped — see fn doc.
+  });
+  return out;
+}
+
 type CliDetectionEntry = {
   id: string;
   displayName: string;
@@ -86,13 +191,21 @@ export class ProviderLoader {
   private versionArchive: VersionArchive | null = null;
   private scriptsCache = new Map<string, Partial<ProviderScripts>>();
 
+  /**
+   * Resolved registry base URL and provider tarball URL. Resolution order:
+   * explicit config field (constructor option) → env var → vendor default.
+   * See `config/registry-resolver.ts`.
+   */
+  private readonly registryBaseUrl: string;
+  private readonly providerTarballUrl: string;
+
   /** Inject VersionArchive so resolve() can auto-detect installed versions */
   setVersionArchive(archive: VersionArchive): void {
     this.versionArchive = archive;
   }
 
-  private static readonly GITHUB_TARBALL_URL = 'https://github.com/vilmire/adhdev-providers/archive/refs/heads/main.tar.gz';
   private static readonly META_FILE = '.meta.json';
+  private static readonly REGISTRY_META_FILE = '.registry-meta.json';
   private static readonly REPO_PROVIDER_DIRNAME = 'adhdev-providers';
   private static readonly SIBLING_MARKER_FILE = '.adhdev-provider-root';
   private static readonly SIBLING_ENV_VAR = 'ADHDEV_USE_SIBLING_PROVIDERS';
@@ -176,9 +289,21 @@ export class ProviderLoader {
      * probing; production code should leave this unset.
      */
     probeStarts?: string[];
+    /**
+     * Explicit provider registry base URL override (config.registryUrl).
+     * Highest-priority resolver source, ahead of ADHDEV_REGISTRY_URL + default.
+     */
+    registryUrl?: string;
+    /**
+     * Explicit provider tarball URL override (config.providerTarballUrl).
+     * Highest-priority resolver source, ahead of ADHDEV_PROVIDER_TARBALL_URL + default.
+     */
+    providerTarballUrl?: string;
   }) {
     this.logFn = options?.logFn || LOG.forComponent('Provider').asLogFn();
     this.probeStarts = options?.probeStarts ?? [process.cwd(), __dirname];
+    this.registryBaseUrl = resolveRegistryBaseUrl(options?.registryUrl);
+    this.providerTarballUrl = resolveProviderTarballUrl(options?.providerTarballUrl);
 
     // Default directory for auto-downloads
     this.defaultProvidersDir = path.join(os.homedir(), '.adhdev', 'providers');
@@ -193,6 +318,33 @@ export class ProviderLoader {
       sourceMode: options?.sourceMode,
       disableUpstream: options?.disableUpstream,
     });
+
+    // One-time migration: ~/.adhdev/marketplace → ~/.adhdev/external.
+    // The directory was renamed when the "marketplace" install model was
+    // dropped in favour of explicit external git sources. Best-effort:
+    // if the rename fails we leave both dirs in place and log so the user
+    // can investigate.
+    this.migrateMarketplaceDirToExternal();
+  }
+
+  private migrateMarketplaceDirToExternal(): void {
+    try {
+      const home = os.homedir();
+      const oldDir = path.join(home, '.adhdev', 'marketplace');
+      const newDir = path.join(home, '.adhdev', 'external');
+      if (!fs.existsSync(oldDir)) return;
+      if (fs.existsSync(newDir)) {
+        // Both exist — don't merge. Leave old in place; surface in logs so
+        // the user can decide what to keep. Loader still loads from
+        // external/ only, so old marketplace/ becomes inert.
+        this.log(`Migration skipped: both ~/.adhdev/marketplace and ~/.adhdev/external exist (marketplace dir is now inert and can be removed manually).`);
+        return;
+      }
+      fs.renameSync(oldDir, newDir);
+      this.log(`Migrated ~/.adhdev/marketplace → ~/.adhdev/external (one-time rename after provider source-layer cleanup).`);
+    } catch (e: any) {
+      this.log(`Marketplace→external migration failed: ${e?.message || e}`);
+    }
   }
 
   private log(msg: string): void {
@@ -224,7 +376,12 @@ export class ProviderLoader {
    * Highest-priority editable overrides come first.
    */
   getProviderRoots(): string[] {
-    return [this.userDir, this.upstreamDir];
+    // Order matters: user customs > external (3rd-party sources) > upstream
+    // (official auto-sync). findProviderDirInternal walks this list in order
+    // to locate the provider dir containing the scripts/, so external must
+    // be included here even though loadAll() also reads it directly.
+    const externalDir = path.join(os.homedir(), '.adhdev', 'external');
+    return [this.userDir, externalDir, this.upstreamDir];
   }
 
   getSourceConfig(): ProviderSourceConfigSnapshot {
@@ -316,16 +473,19 @@ export class ProviderLoader {
 
  /**
  * Load all providers (3-tier priority)
- * 1. .upstream/ (GitHub auto-download — primary source)
- * 2. User custom (~/.adhdev/providers/ excluding .upstream)
- * User custom always wins (highest priority).
+ * 1. ~/.adhdev/providers/.upstream/ — official git, auto-synced
+ * 2. ~/.adhdev/external/ — 3rd-party git sources, user-added,
+ *    bundled providers may include arbitrary JS (untrusted by default)
+ * 3. ~/.adhdev/providers/ (excluding .upstream) — user-authored customs,
+ *    always wins
+ * Highest priority listed last (overwrites earlier loads).
  * If .upstream/ is empty, call fetchLatest() before loadAll().
  */
   loadAll(): void {
     this.providers.clear();
     this.providerAvailability.clear();
 
- // 1. Load upstream (GitHub auto-download — primary source)
+ // 1. Load upstream (GitHub auto-download — primary official source)
     let upstreamCount = 0;
     if (!this.disableUpstream && fs.existsSync(this.upstreamDir)) {
       upstreamCount = this.loadDir(this.upstreamDir);
@@ -336,7 +496,90 @@ export class ProviderLoader {
       this.log('Upstream loading disabled (sourceMode=no-upstream)');
     }
 
- // 2. Load user custom (excluding .upstream — highest priority, never auto-updated)
+ // 2. Load external providers from ~/.adhdev/external/<source-name>/
+ //    (3rd-party git sources). Overrides upstream but is itself overridden
+ //    by user customs in step 3.
+ //
+ //    Each registered source is a separate subdirectory so two sources can
+ //    both expose the same provider type without overwriting each other.
+ //    When more than one source provides the same type, providers-active.json
+ //    chooses the active one; without an explicit choice we deterministically
+ //    pick the first in disk-walk order and log the ambiguity so the user
+ //    can resolve it from the dashboard.
+ //
+ //    Any non-spec manifest (tui block / overrides / scriptDir) coming from
+ //    an external source runs JavaScript the daemon hasn't audited, so
+ //    dashboards must surface an "untrusted source" badge before letting
+ //    the user enable them.
+    const externalDir = path.join(os.homedir(), '.adhdev', 'external');
+    if (fs.existsSync(externalDir)) {
+      // Legacy layout (pre-source-namespace): manifests sit directly at
+      // external/<category>/<type>/. Detect by presence of category dirs at
+      // the root and migrate inline by treating the whole tree as a single
+      // implicit source. Loader behavior unchanged for legacy callers.
+      const rootEntries = (() => {
+        try { return fs.readdirSync(externalDir, { withFileTypes: true }); }
+        catch { return [] as fs.Dirent[]; }
+      })();
+      const KNOWN_CATEGORIES = new Set(['cli', 'ide', 'extension', 'acp']);
+      const looksLegacy = rootEntries.some(e => e.isDirectory() && KNOWN_CATEGORIES.has(e.name));
+      if (looksLegacy) {
+        // Tree shape predates per-source dirs — treat the whole thing as a
+        // single anonymous source so existing installs keep working until
+        // they're migrated to a real source registration.
+        const externalCount = this.loadDir(externalDir);
+        if (externalCount > 0) {
+          this.log(`Loaded ${externalCount} external providers (legacy unnamed source)`);
+        }
+      } else {
+        // New layout: external/<source-name>/<category>/<type>/…
+        const activeFile = loadProvidersActive();
+        let totalLoaded = 0;
+        const ambiguousTypes: { type: string; chosen: string; candidates: string[] }[] = [];
+        // Per-source load, then filter by active-selection: for each type
+        // present in more than one source, only the active source's copy
+        // is left in this.providers.
+        for (const sourceEntry of rootEntries) {
+          if (!sourceEntry.isDirectory()) continue;
+          const sourceDir = path.join(externalDir, sourceEntry.name);
+          const sourceLoaded = this.loadDir(sourceDir);
+          if (sourceLoaded > 0) {
+            totalLoaded += sourceLoaded;
+            this.log(`Loaded ${sourceLoaded} providers from external source "${sourceEntry.name}"`);
+          }
+        }
+        // Resolve ambiguities — when the same type came from multiple
+        // sources, the last load wins by default. Replay with the active
+        // selection so the user-chosen source ends up winning.
+        for (const [type] of this.providers) {
+          const prov = this.providers.get(type);
+          if (!prov) continue;
+          const resolved = resolveActiveSource(prov.category, type, activeFile);
+          if (resolved.candidates.length <= 1) continue;
+          if (resolved.ambiguous) {
+            ambiguousTypes.push({ type, chosen: resolved.source ?? '?', candidates: resolved.candidates });
+          }
+          if (resolved.source && resolved.source !== '?') {
+            const sourceDir = path.join(externalDir, resolved.source);
+            // Reload only this source's copy of the conflicting type so it
+            // overwrites whatever else won the initial pass.
+            const reloadCount = this.loadDir(sourceDir);
+            // reloadCount is a sanity check — we expect ≥1
+            if (reloadCount === 0) {
+              this.log(`Active source "${resolved.source}" no longer provides ${type}`);
+            }
+          }
+        }
+        if (totalLoaded > 0) {
+          this.log(`Loaded ${totalLoaded} external providers (3rd-party sources)`);
+        }
+        for (const a of ambiguousTypes) {
+          this.log(`Ambiguous provider "${a.type}" — provided by [${a.candidates.join(', ')}], defaulted to "${a.chosen}". Set the active source from the dashboard to silence this warning.`);
+        }
+      }
+    }
+
+ // 3. Load user custom (excluding .upstream — highest priority, never auto-updated)
     if (fs.existsSync(this.userDir)) {
       const userCount = this.loadDir(this.userDir, ['.upstream']);
       if (userCount > 0) {
@@ -909,18 +1152,28 @@ export class ProviderLoader {
 
         for (const entry of compat) {
           if (this.matchesVersion(currentVersion, entry.ideVersion)) {
-            const loaded = this.loadScriptsFromDir(type, entry.scriptDir);
-            if (loaded) {
-              resolved.scripts = loaded;
-              this.debugLog(`  [compatibility] ${type} v${currentVersion} → ${entry.scriptDir}`);
-              resolved._resolvedScriptDir = entry.scriptDir;
-              resolved._resolvedScriptsSource = `compatibility:${entry.ideVersion}`;
-              if (providerDir) {
-                const fullDir = path.join(providerDir, entry.scriptDir);
-                resolved._resolvedScriptsPath = fs.existsSync(path.join(fullDir, 'scripts.js'))
-                  ? path.join(fullDir, 'scripts.js')
-                  : fullDir;
+            // entry.scriptDir is optional now — spec-driven providers (agy,
+            // codex on >=0.137, claude on >=2.1) only ship `spec` here, so
+            // there's nothing to load from the filesystem. SpecCliAdapter
+            // takes over via the `spec` path later in this method.
+            if (entry.scriptDir) {
+              const loaded = this.loadScriptsFromDir(type, entry.scriptDir);
+              if (loaded) {
+                resolved.scripts = loaded;
+                this.debugLog(`  [compatibility] ${type} v${currentVersion} → ${entry.scriptDir}`);
+                resolved._resolvedScriptDir = entry.scriptDir;
+                resolved._resolvedScriptsSource = `compatibility:${entry.ideVersion}`;
+                if (providerDir) {
+                  const fullDir = path.join(providerDir, entry.scriptDir);
+                  resolved._resolvedScriptsPath = fs.existsSync(path.join(fullDir, 'scripts.js'))
+                    ? path.join(fullDir, 'scripts.js')
+                    : fullDir;
+                }
+                matched = true;
               }
+            } else {
+              // Spec-only entry — still counts as a match so the
+              // defaultScriptDir fallback below doesn't kick in.
               matched = true;
             }
             break; // first match wins
@@ -988,7 +1241,12 @@ export class ProviderLoader {
     }
 
  // 3. Composite override (OS + version)
-    if (base.overrides) {
+ //    Legacy shape: base.overrides is an Array<{ when: {os,version}, scripts }>.
+ //    v1 manifests (Phase 3-4) repurposed `overrides` as an object map of
+ //    capability overrides (e.g. { detectStatus: { path, schema } }), which is
+ //    consumed by the SDK builders, not by this resolver. Only iterate when
+ //    the field is in the legacy array shape.
+    if (Array.isArray(base.overrides)) {
       for (const override of base.overrides) {
         const osMatch = !override.when.os || override.when.os === currentOs;
         const verMatch = !override.when.version || (currentVersion && this.matchesVersion(currentVersion, override.when.version));
@@ -996,6 +1254,40 @@ export class ProviderLoader {
           resolved.scripts = { ...resolved.scripts, ...override.scripts };
         }
       }
+    } else if (base.overrides && typeof base.overrides === 'object') {
+      // v1 manifest shape: { detectStatus: { path }, parseSession: { path }, ... }
+      // Each script name maps to a path inside the provider directory. We load
+      // the file and merge its export(s) into resolved.scripts. Lets a
+      // provider override a single primitive (e.g. just detectStatus) while
+      // letting the SDK synthesize the rest from the tui block.
+      const providerDir = this.findProviderDirInternal(base.type);
+      if (providerDir) {
+        for (const [scriptName, override] of Object.entries(base.overrides as Record<string, any>)) {
+          if (!override || typeof override.path !== 'string') continue;
+          const fullPath = path.join(providerDir, override.path);
+          if (!fs.existsSync(fullPath)) {
+            this.log(`  [overrides] ${base.type}: ${scriptName} path not found: ${fullPath}`);
+            continue;
+          }
+          try {
+            // Override scripts go through the same whitelist gate as the
+            // main scripts dir. Use the provider parent root so a v1
+            // override can still require ../_shared helpers.
+            registerProviderScriptRootSafely(path.dirname(path.dirname(providerDir)));
+            delete require.cache[require.resolve(fullPath)];
+            const fn = require(fullPath);
+            const target = typeof fn === 'function' ? fn : (fn && fn[scriptName]);
+            if (typeof target === 'function') {
+              resolved.scripts = { ...resolved.scripts, [scriptName]: target } as any;
+              this.log(`  [overrides] ${base.type}: ${scriptName} loaded from ${override.path}`);
+            } else {
+              this.log(`  [overrides] ${base.type}: ${scriptName} export missing in ${override.path}`);
+            }
+          } catch (e: any) {
+            this.log(`  [overrides] ${base.type}: ${scriptName} require failed: ${e?.message || e}`);
+          }
+        }
+      }
     }
 
     if ((resolved.category === 'cli' || resolved.category === 'acp') && resolved.spawn?.command) {
@@ -1006,6 +1298,135 @@ export class ProviderLoader {
       };
     }
 
+    // (spec migration) Late-binding spec.json native-history hook. Runs
+    // *after* every script-loading path (compatibility / defaultScriptDir /
+    // overrides) so it deterministically wins over a legacy v1 scripts.js
+    // export. Three modes, picked by spec.json's native_history block:
+    //   1. source     — declarative jsonl/sqlite executor (new-provider path,
+    //                   no daemon change needed for new on-disk formats)
+    //   2. override_path — provider-supplied reader file (escape hatch for
+    //                   exotic formats); module default-exports a reader fn
+    //   3. reader     — built-in reader id (claude-cli / codex-cli /
+    //                   antigravity-cli / hermes-cli), kept for backwards
+    //                   compatibility with the four shipped providers
+    if (providerDir) {
+      try {
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const fs = require('node:fs');
+        // eslint-disable-next-line @typescript-eslint/no-var-requires
+        const path = require('node:path');
+        // Pick the right spec file for the detected CLI version. Resolution
+        // order:
+        //   1. compatibility[i].spec where ideVersion matches currentVersion
+        //      (lets a provider ship specs/2.0.json, specs/2.1.json, etc.
+        //      alongside the matching scriptDir)
+        //   2. specs/default.json — explicit fallback
+        //   3. spec.json — legacy single-spec layout
+        // Missing files fall through silently to the next candidate.
+        const candidates: string[] = [];
+        if (Array.isArray((base as any).compatibility)) {
+          for (const entry of (base as any).compatibility) {
+            if (typeof entry?.spec !== 'string') continue;
+            // If currentVersion is unknown (cli-manager hasn't probed yet)
+            // we still let compatibility entries that don't pin a version
+            // through, plus any entry whose pin matches.
+            const matches = !entry.ideVersion
+              || (currentVersion && this.matchesVersion(currentVersion, entry.ideVersion))
+              || !currentVersion;
+            if (matches) candidates.push(path.join(providerDir, entry.spec));
+          }
+        }
+        candidates.push(path.join(providerDir, 'specs', 'default.json'));
+        candidates.push(path.join(providerDir, 'spec.json'));
+        const specPath = candidates.find((p: string) => fs.existsSync(p));
+        if (specPath) {
+          // Hand the resolved spec path off to route.ts via a hidden field
+          // so the routing layer doesn't have to repeat the candidate walk.
+          (resolved as any)._resolvedSpecPath = specPath;
+          // Extract control_bar + native_history directly from the JSON header.
+          let specControls: any[] | undefined;
+          let nh: any | undefined;
+          try {
+            const rawSpec = JSON.parse(fs.readFileSync(specPath, 'utf8'));
+            specControls = rawSpec.control_bar;
+            nh = rawSpec.native_history;
+          } catch { /* unreadable spec — leave controls/native unavailable */ }
+          // Stub each control_bar entry as a provider.scripts.<id>. The
+          // upstream invoke_provider_script gate checks that the script
+          // name exists on provider.scripts before calling adapter.invokeScript;
+          // for spec providers the *actual* dispatch happens inside
+          // SpecCliAdapter.invokeScript which maps the name to control_bar.
+          // The stub is just a presence marker so the gate doesn't reject.
+          if (specControls && specControls.length > 0) {
+            resolved.scripts = { ...(resolved.scripts || {}) };
+            for (const ctl of specControls) {
+              if (!(resolved.scripts as any)[ctl.id]) {
+                (resolved.scripts as any)[ctl.id] = (..._args: unknown[]) => ({
+                  __spec_control: true,
+                  controlId: ctl.id,
+                  actionType: ctl.action.type,
+                });
+              }
+            }
+            // Bridge the spec control_bar into the web-facing controls schema so
+            // the dashboard chat bar actually renders Model/Mode pickers. Only
+            // synthesize when the provider hasn't already declared its own
+            // `controls` in provider.v1.json (e.g. hermes-cli) — an explicit
+            // declaration wins and must not be clobbered.
+            const hasDeclaredControls = Array.isArray((resolved as any).controls)
+              && (resolved as any).controls.length > 0;
+            if (!hasDeclaredControls) {
+              const synthesized = synthesizeControlsFromControlBar(specControls);
+              if (synthesized.length > 0) {
+                resolved.controls = synthesized;
+              }
+            }
+          }
+          if (nh) {
+            let reader: ((input: any) => any) | null = null;
+            let format = 'spec';
+
+            if (nh.source) {
+              format = `spec-${nh.source.kind}`;
+              reader = (input: any) => executeNativeHistory(nh, input);
+            } else if (nh.override_path) {
+              const overrideFile = path.resolve(providerDir, nh.override_path);
+              if (fs.existsSync(overrideFile)) {
+                try {
+                  registerProviderScriptRootSafely(path.dirname(path.dirname(providerDir)));
+                  delete require.cache[require.resolve(overrideFile)];
+                  // eslint-disable-next-line @typescript-eslint/no-var-requires
+                  const mod = require(overrideFile);
+                  const fn = typeof mod === 'function' ? mod : (mod && typeof mod.default === 'function' ? mod.default : null);
+                  if (fn) {
+                    format = 'spec-override';
+                    reader = (input: any) => fn(input);
+                  }
+                } catch { /* fall through — leave native unavailable */ }
+              }
+            } else if (nh.reader) {
+              const dispatch = createNativeHistoryDispatcher(nh.reader as ReaderId);
+              format = nh.reader;
+              reader = (input: any) => dispatch(input);
+            }
+
+            if (reader) {
+              resolved.scripts = { ...(resolved.scripts || {}) };
+              (resolved.scripts as any).readNativeHistory = reader;
+              (resolved as any).nativeHistory = {
+                format,
+                watchPath: undefined,
+                scripts: { readSession: 'readNativeHistory' },
+                mode: 'native-source',
+              };
+            }
+          }
+        }
+      } catch {
+        // Best-effort — spec wiring failure must not break legacy providers.
+      }
+    }
+
     return resolved;
   }
 
@@ -1016,16 +1437,27 @@ export class ProviderLoader {
   private loadScriptsFromDir(type: string, scriptDir: string): Partial<ProviderScripts> | null {
     const providerDir = this.findProviderDirInternal(type);
     if (!providerDir) {
-      this.log(`  [loadScriptsFromDir] ${type}: providerDir not found`);
+      // No provider dir for this type — a spec-only provider with no
+      // legacy scripts/v1 layout is a normal configuration, not a
+      // problem to surface at INFO. resolve() calls this on every
+      // request; INFO spam every 200ms drowns out the real signal.
+      this.debugLog(`[loadScriptsFromDir] ${type}: providerDir not found`);
       return null;
     }
 
     const dir = path.join(providerDir, scriptDir);
     if (!fs.existsSync(dir)) {
-      this.log(`  [loadScriptsFromDir] ${type}: dir not found: ${dir}`);
+      this.debugLog(`[loadScriptsFromDir] ${type}: dir not found: ${dir}`);
       return null;
     }
 
+    // Register the provider's *parent root* (e.g. .../adhdev-providers/) so
+    // the require whitelist gates every script + every _shared helper this
+    // provider may reach. Picking the grandparent (one above the category
+    // dir `cli/`) lets sibling helpers in `_shared` resolve while still
+    // blocking `../../etc/...` escapes. Idempotent.
+    registerProviderScriptRootSafely(path.dirname(path.dirname(providerDir)));
+
     // Return cached scripts if available (cleared on reload/watch)
     const cached = this.scriptsCache.get(dir);
     if (cached) return cached;
@@ -1036,7 +1468,7 @@ export class ProviderLoader {
       try {
         delete require.cache[require.resolve(scriptsJs)];
         const loaded = require(scriptsJs);
-        this.log(`  [loadScriptsFromDir] ${type}: loaded scripts.js from ${dir} (${Object.keys(loaded).length} exports)`);
+        this.debugLog(`[loadScriptsFromDir] ${type}: loaded scripts.js from ${dir} (${Object.keys(loaded).length} exports)`);
         this.scriptsCache.set(dir, loaded);
         return loaded;
       } catch (e) {
@@ -1067,13 +1499,17 @@ export class ProviderLoader {
           awaitWriteFinish: { stabilityThreshold: 200, pollInterval: 50 },
         });
 
+        let reloadTimer: ReturnType<typeof setTimeout> | null = null;
         const handleChange = (filePath: string) => {
           if (/[\/\\]fixtures[\/\\]/.test(filePath)) {
             return;
           }
           if (filePath.endsWith('.js') || filePath.endsWith('.json')) {
-            this.log(`File changed: ${path.basename(filePath)}, reloading...`);
-            this.reload();
+            if (reloadTimer) clearTimeout(reloadTimer);
+            reloadTimer = setTimeout(() => {
+              this.log(`File changed: ${path.basename(filePath)}, reloading...`);
+              this.reload();
+            }, 300);
           }
         };
 
@@ -1124,13 +1560,115 @@ export class ProviderLoader {
  * 
  * @returns Whether an update occurred
  */
+  /**
+   * Sync providers from the ADHDev registry (registry.adhf.dev).
+   *
+   * Downloads only providers whose server checksum differs from the locally
+   * cached checksum. Falls back gracefully to the GitHub tarball path if the
+   * registry is unreachable or returns an unexpected response.
+   *
+   * Returns `{ updated: true }` when at least one provider file changed on disk,
+   * `{ updated: false }` when everything is already current, or
+   * `{ updated: false, error }` when the registry couldn't be reached and we
+   * should proceed to the GitHub tarball fallback.
+   */
+  async fetchFromRegistry(): Promise<{ updated: boolean; error?: string }> {
+    if (this.disableUpstream) {
+      this.log('Registry sync skipped (sourceMode=no-upstream)');
+      return { updated: false };
+    }
+    this.log(`Registry sync starting (${this.registryBaseUrl})...`);
+
+    const https = require('https') as typeof import('https');
+    const regMetaPath = path.join(this.upstreamDir, ProviderLoader.REGISTRY_META_FILE);
+
+    // Load cached checksums
+    let cachedChecksums: Record<string, string> = {};
+    try {
+      if (fs.existsSync(regMetaPath)) {
+        cachedChecksums = JSON.parse(fs.readFileSync(regMetaPath, 'utf-8')).checksums ?? {};
+      }
+    } catch { }
+
+    try {
+      // 1. Fetch provider list
+      const listUrl = `${this.registryBaseUrl}/providers`;
+      const listBody = await new Promise<string>((resolve, reject) => {
+        const req = https.get(listUrl, { headers: { 'User-Agent': 'adhdev-daemon', 'Accept': 'application/json' }, timeout: 10000 }, (res) => {
+          if (res.statusCode !== 200) { reject(new Error(`registry list HTTP ${res.statusCode}`)); return; }
+          const chunks: Buffer[] = [];
+          res.on('data', (c: Buffer) => chunks.push(c));
+          res.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+        });
+        req.on('error', reject);
+        req.on('timeout', () => { req.destroy(); reject(new Error('registry list timeout')); });
+      });
+
+      const list = JSON.parse(listBody) as { providers: Array<{ type: string; category: string; checksum: string; version: string }> };
+      if (!Array.isArray(list.providers)) throw new Error('unexpected registry response shape');
+
+      let updatedCount = 0;
+
+      for (const entry of list.providers) {
+        const { type, category, checksum, version } = entry;
+        const cacheKey = `${category}/${type}`;
+        if (cachedChecksums[cacheKey] === checksum) continue; // already current
+
+        // Download this provider's manifest
+        const dlUrl = `${this.registryBaseUrl}/providers/${type}/${version}/download`;
+        const manifestBody = await new Promise<string>((resolve, reject) => {
+          const req = https.get(dlUrl, { headers: { 'User-Agent': 'adhdev-daemon', 'Accept': 'application/json' }, timeout: 30000 }, (res) => {
+            if (res.statusCode !== 200) { reject(new Error(`registry download HTTP ${res.statusCode} for ${type}@${version}`)); return; }
+            const chunks: Buffer[] = [];
+            res.on('data', (c: Buffer) => chunks.push(c));
+            res.on('end', () => resolve(Buffer.concat(chunks).toString('utf-8')));
+          });
+          req.on('error', reject);
+          req.on('timeout', () => { req.destroy(); reject(new Error(`download timeout for ${type}`)); });
+        });
+
+        // Verify checksum
+        const actualChecksum = sha256Hex(manifestBody);
+        if (actualChecksum !== checksum) {
+          this.log(`⚠ Registry checksum mismatch for ${type}@${version} — skipping`);
+          continue;
+        }
+
+        // Write to upstream dir
+        const providerDir = path.join(this.upstreamDir, category, type);
+        fs.mkdirSync(providerDir, { recursive: true });
+        fs.writeFileSync(path.join(providerDir, 'provider.json'), manifestBody, 'utf-8');
+
+        cachedChecksums[cacheKey] = checksum;
+        updatedCount++;
+        this.log(`✓ Registry updated: ${category}/${type}@${version}`);
+      }
+
+      // Persist updated checksums
+      fs.mkdirSync(this.upstreamDir, { recursive: true });
+      fs.writeFileSync(regMetaPath, JSON.stringify({
+        checksums: cachedChecksums,
+        syncedAt: new Date().toISOString(),
+        providerCount: list.providers.length,
+      }, null, 2));
+
+      this.log(`Registry sync complete: ${list.providers.length} providers, ${updatedCount} updated`);
+      return { updated: updatedCount > 0 };
+    } catch (e: any) {
+      this.log(`⚠ Registry sync failed (falling back to GitHub tarball): ${e?.message}`);
+      return { updated: false, error: e?.message };
+    }
+  }
+
   async fetchLatest(): Promise<{ updated: boolean; error?: string }> {
     if (this.disableUpstream) {
       this.log('Upstream fetch skipped (sourceMode=no-upstream)');
       return { updated: false };
     }
     const https = require('https') as typeof import('https');
-    const { execSync } = require('child_process') as typeof import('child_process');
+    const { exec } = require('child_process') as typeof import('child_process');
+    const { promisify } = require('util');
+    const execAsync = promisify(exec);
 
     const metaPath = path.join(this.upstreamDir, ProviderLoader.META_FILE);
     let prevEtag = '';
@@ -1152,13 +1690,17 @@ export class ProviderLoader {
       return { updated: false };
     }
 
+    // Resolve the tarball target (config → env → vendor default) once so the
+    // HEAD probe and the download below hit the same (possibly self-hosted) URL.
+    const tarballTarget = resolveProviderTarballTarget(this.providerTarballUrl);
+
     try {
  // Step 1: HEAD request to check ETag
       const etag = await new Promise<string>((resolve, reject) => {
         const options = {
           method: 'HEAD',
-          hostname: 'github.com',
-          path: '/vilmire/adhdev-providers/archive/refs/heads/main.tar.gz',
+          hostname: tarballTarget.hostname,
+          path: tarballTarget.path,
           headers: { 'User-Agent': 'adhdev-launcher' },
           timeout: 10000,
         };
@@ -1203,11 +1745,11 @@ export class ProviderLoader {
       const tmpExtract = path.join(os.tmpdir(), `adhdev-providers-extract-${Date.now()}`);
 
  // Download tarball
-      await this.downloadFile(ProviderLoader.GITHUB_TARBALL_URL, tmpTar);
+      await this.downloadFile(tarballTarget.url, tmpTar);
 
  // Extract
       fs.mkdirSync(tmpExtract, { recursive: true });
-      execSync(`tar -xzf "${tmpTar}" -C "${tmpExtract}"`, { timeout: 30000 });
+      await execAsync(`tar -xzf "${tmpTar}" -C "${tmpExtract}"`, { timeout: 30000 });
 
  // Tarball internal structure: adhdev-providers-main/ide/... → strip 1 level
       const extracted = fs.readdirSync(tmpExtract);
@@ -1310,20 +1852,22 @@ export class ProviderLoader {
         etag,
         timestamp,
         lastCheck: new Date(timestamp).toISOString(),
-        source: ProviderLoader.GITHUB_TARBALL_URL,
+        source: this.providerTarballUrl,
       }, null, 2));
     } catch { }
   }
 
-  /** Count provider files (provider.js or provider.json) */
+  /** Count provider files (provider.v1.json or provider.json — at most one per dir). */
   private countProviders(dir: string): number {
     if (!fs.existsSync(dir)) return 0;
     let count = 0;
     const scan = (d: string) => {
       try {
-        for (const entry of fs.readdirSync(d, { withFileTypes: true })) {
+        const entries = fs.readdirSync(d, { withFileTypes: true });
+        const hasManifest = entries.some(e => e.name === 'provider.v1.json' || e.name === 'provider.json');
+        if (hasManifest) count++;
+        for (const entry of entries) {
           if (entry.isDirectory()) scan(path.join(d, entry.name));
-          else if (entry.name === 'provider.json') count++;
         }
       } catch { }
     };
@@ -1372,11 +1916,15 @@ export class ProviderLoader {
       return args ? args.map((arg) => /\s/.test(arg) ? JSON.stringify(arg) : arg).join(' ') : '';
     }
     const schemaDef = this.getSettingsSchema(providerType)[key];
-    const defaultVal = schemaDef
-      ? (key === 'autoApprove' && schemaDef.type === 'boolean'
-        ? true
-        : schemaDef.default)
-      : undefined;
+    // (fix) Previously this hard-coded `autoApprove` boolean default to `true`,
+    // overriding whatever schemaDef.default the provider.json declared. That
+    // surfaced as soon as a provider added an `autoApprove` schema entry with
+    // default=false: the user had never opted in but the daemon treated the
+    // session as auto-approve, which then triggered recordAutoApproval every
+    // time the CLI showed an approval modal — producing a flood of system
+    // "Auto-approved: ..." messages and keeping the session pinned to
+    // generating while modals cycled in and out. Trust the schemaDef.default.
+    const defaultVal = schemaDef ? schemaDef.default : undefined;
 
     const config = this.readConfig();
     const userVal = config?.providerSettings?.[providerType]?.[key];
@@ -1490,10 +2038,17 @@ export class ProviderLoader {
       ...this.getSyntheticSettings(type, provider),
       ...(provider.settings || {}),
     };
+    // (fix) Previously this clause forced `autoApprove.default = true` for any
+    // boolean autoApprove schema, even when the provider.json explicitly set
+    // `default: false`. Combined with the synthetic-settings fallback at
+    // getSyntheticSettings (which also defaults autoApprove to true when the
+    // provider doesn't supply one), that meant CLI providers silently turned on
+    // auto-approval, producing a flood of "Auto-approved: ..." system messages
+    // every time an approval modal appeared and pinning the session to
+    // generating while modals cycled. Trust the provider's declared default.
     if (result.autoApprove?.type === 'boolean') {
       result.autoApprove = {
         ...result.autoApprove,
-        default: true,
         public: true,
         label: result.autoApprove.label || 'Auto Approve',
         description: result.autoApprove.description || 'Automatically approve actionable prompts without sending approval alerts.',
@@ -1518,7 +2073,10 @@ export class ProviderLoader {
     if (!provider.settings?.autoApprove) {
       result.autoApprove = {
         type: 'boolean',
-        default: true,
+        // (fix) Safe default is *off*. Auto-approving every modal without the
+        // user opting in produced silent-bash-execution surprises and the
+        // "Auto-approved: ..." system-message flood seen on AGY/Codex.
+        default: false,
         public: true,
         label: 'Auto Approve',
         description: 'Automatically approve actionable prompts without sending approval alerts.',
@@ -1581,23 +2139,32 @@ export class ProviderLoader {
     const cat = provider.category;
 
     const searchRoots = this.getProviderRoots();
+    const hasManifest = (dir: string) =>
+      fs.existsSync(path.join(dir, 'provider.v1.json')) || fs.existsSync(path.join(dir, 'provider.json'));
+    const readManifestType = (dir: string): string | null => {
+      for (const file of ['provider.v1.json', 'provider.json']) {
+        const p = path.join(dir, file);
+        if (!fs.existsSync(p)) continue;
+        try {
+          const data = JSON.parse(fs.readFileSync(p, 'utf-8'));
+          if (typeof data?.type === 'string') return data.type;
+        } catch { /* skip */ }
+      }
+      return null;
+    };
     for (const root of searchRoots) {
       if (!fs.existsSync(root)) continue;
       const candidate = this.getProviderDir(root, cat, type);
-      if (fs.existsSync(path.join(candidate, 'provider.json'))) return candidate;
+      if (hasManifest(candidate)) return candidate;
       // Scan category dir for type match
       const catDir = path.join(root, cat);
       if (fs.existsSync(catDir)) {
         try {
           for (const entry of fs.readdirSync(catDir, { withFileTypes: true })) {
             if (!entry.isDirectory()) continue;
-            const jsonPath = path.join(catDir, entry.name, 'provider.json');
-            if (fs.existsSync(jsonPath)) {
-              try {
-                const data = JSON.parse(fs.readFileSync(jsonPath, 'utf-8'));
-                if (data.type === type) return path.join(catDir, entry.name);
-              } catch { /* skip */ }
-            }
+            const entryDir = path.join(catDir, entry.name);
+            const manifestType = readManifestType(entryDir);
+            if (manifestType === type) return entryDir;
           }
         } catch { /* skip */ }
       }
@@ -1690,17 +2257,44 @@ export class ProviderLoader {
         return;
       }
 
-      // Check if this directory has provider.json
+      // v1-first manifest selection. provider.v1.json (the SDK-shape
+      // manifest with `overrides`, `tui`, `source`, `canonicalHistory`)
+      // wins over provider.json (legacy). Without this branch the v1
+      // file is silently ignored — that's how the codex-cli `overrides`
+      // path and the tui-block builders went un-honored for the first
+      // pass of SDK rollout.
+      const hasV1 = entries.some(e => e.name === 'provider.v1.json');
       const hasJson = entries.some(e => e.name === 'provider.json');
 
-      if (hasJson) {
-        const jsonPath = path.join(d, 'provider.json');
+      if (hasV1 || hasJson) {
+        const manifestFile = hasV1 ? 'provider.v1.json' : 'provider.json';
+        const jsonPath = path.join(d, manifestFile);
         try {
           const raw = fs.readFileSync(jsonPath, 'utf-8');
           const mod = JSON.parse(raw) as Omit<ProviderModule, 'extensionIdPattern'> & {
             extensionIdPattern?: RegExp | string;
           };
 
+          // Validate v1 manifests against the SDK schema. Failures are
+          // surfaced as a single warning line with all issues attached
+          // so manifest authors don't need to guess which field is wrong.
+          // Loading still proceeds — bricking the daemon on a single
+          // bad field would be worse than running with a known warning.
+          if (hasV1 && mod?.category === 'cli') {
+            try {
+              const { validateCliProviderManifest, formatManifestValidationIssues } =
+                require('./sdk/v1/validators/manifest.js') as typeof import('./sdk/v1/validators/manifest.js');
+              const validation = validateCliProviderManifest(mod);
+              if (!validation.ok) {
+                this.log(`⚠ ${jsonPath}: schema validation failed:\n${formatManifestValidationIssues(validation.issues)}`);
+              }
+            } catch (e: any) {
+              // Validator load failed — log once and continue so a
+              // broken validator can't take down provider loading.
+              this.log(`⚠ ${jsonPath}: validator unavailable: ${e?.message || e}`);
+            }
+          }
+
           // Restore RegExp fields from JSON (extensionIdPattern)
           if (typeof mod.extensionIdPattern === 'string') {
             const flags = mod.extensionIdPattern_flags || '';
@@ -1712,6 +2306,22 @@ export class ProviderLoader {
             ...(extensionIdPattern instanceof RegExp ? { extensionIdPattern } : {}),
           };
 
+          // v1 manifests use `nativeHistory` as the canonical field name.
+          // Legacy v0 manifests use `canonicalHistory`. The daemon's
+          // runtime + downstream code reads `provider.nativeHistory`, so
+          // for legacy manifests we copy `canonicalHistory` into
+          // `nativeHistory` here. We also keep `canonicalHistory`
+          // populated in both directions (deprecated alias) so any
+          // external consumers still reading the old name keep working
+          // during the one-release deprecation window.
+          const nh = (normalizedProvider as any).nativeHistory;
+          const ch = (normalizedProvider as any).canonicalHistory;
+          if (nh && !ch) {
+            (normalizedProvider as any).canonicalHistory = nh;
+          } else if (ch && !nh) {
+            (normalizedProvider as any).nativeHistory = ch;
+          }
+
           const validation = validateProviderDefinition(normalizedProvider);
           for (const warning of validation.warnings) {
             this.log(`⚠ ${jsonPath}: ${warning}`);
@@ -1725,6 +2335,10 @@ export class ProviderLoader {
             const scriptsPath = path.join(d, 'scripts.js');
             if (!hasCompatibility && fs.existsSync(scriptsPath)) {
               try {
+                // Gate the IDE/extension scripts.js (legacy single-file
+                // format) under the same whitelist. `d` here is the
+                // provider dir; its grandparent contains _shared.
+                registerProviderScriptRootSafely(path.dirname(path.dirname(d)));
                 delete require.cache[require.resolve(scriptsPath)];
                 const scripts = require(scriptsPath) as Partial<ProviderScripts>;
                 normalizedProvider.scripts = scripts;
@@ -1733,14 +2347,40 @@ export class ProviderLoader {
               }
             }
 
+            // Classify trust based on which on-disk layer this manifest
+            // came from + whether it ships JavaScript hooks. The dashboard
+            // uses this to render trust badges; non-spec external manifests
+            // need an explicit user confirm before activation.
+            const externalDirAbs = path.join(os.homedir(), '.adhdev', 'external');
+            const layer: 'user' | 'upstream' | 'external' = d.startsWith(externalDirAbs)
+              ? 'external'
+              : (d.startsWith(this.userDir) && !d.includes('.upstream') ? 'user' : 'upstream');
+            try {
+              const { inspectManifestShape, classifyTrust } =
+                require('./provider-trust.js') as typeof import('./provider-trust.js');
+              const shape = inspectManifestShape(mod as Record<string, unknown>);
+              const trust = classifyTrust(layer, shape);
+              (normalizedProvider as any)._sourceLayer = layer;
+              (normalizedProvider as any)._sourceTrust = trust;
+              (normalizedProvider as any)._manifestShape = shape;
+              // For external-namespaced layouts (external/<source>/…) record
+              // which source the manifest came from so dashboards can name
+              // it in the trust badge.
+              if (layer === 'external') {
+                const rel = path.relative(externalDirAbs, d);
+                const firstSeg = rel.split(path.sep)[0];
+                if (firstSeg && firstSeg !== '..') (normalizedProvider as any)._sourceName = firstSeg;
+              }
+            } catch { /* best-effort — trust is enrichment, not gating */ }
+
             const existed = this.providers.has(normalizedProvider.type);
             this.providers.set(normalizedProvider.type, normalizedProvider);
             count++;
-            // Identify source tier for debugging
-            const source = d.startsWith(this.userDir) && !d.includes('.upstream')
-              ? 'user' : 'upstream';
+            const source = (normalizedProvider as any)._sourceLayer ?? 'upstream';
             const overrideWarning = existed && source === 'user' ? ' ⚠ OVERRIDES upstream' : '';
-            this.log(`  ${existed ? '🔄' : '✅'} ${normalizedProvider.type} (${normalizedProvider.category}) — ${normalizedProvider.name} [${source}]${overrideWarning}`);
+            const sourceName = (normalizedProvider as any)._sourceName;
+            const sourceLabel = sourceName ? `${source}/${sourceName}` : source;
+            this.log(`  ${existed ? '🔄' : '✅'} ${normalizedProvider.type} (${normalizedProvider.category}) — ${normalizedProvider.name} [${sourceLabel}]${overrideWarning}`);
           }
         } catch (e) {
           this.log(`⚠ Failed to load ${jsonPath}: ${(e as Error).message}`);
@@ -1752,6 +2392,11 @@ export class ProviderLoader {
         for (const entry of entries) {
           if (!entry.isDirectory()) continue;
           if (entry.name.startsWith('_') || entry.name.startsWith('.')) continue;
+          // `examples/` is a documentation / scaffold tree (e.g. stub-cli),
+          // not a real provider source. SDK authors copy from here when
+          // writing a new provider; daemon-core tests reference the
+          // manifest by path. Keep it off the dashboard's provider list.
+          if (d === dir && entry.name === 'examples') continue;
           if (excludeDirs && d === dir && excludeDirs.includes(entry.name)) continue;
           scan(path.join(d, entry.name));
         }