@adhdev/daemon-core 0.9.82-rc.165 → 0.9.82-rc.167

package/src/mesh/mesh-events.ts

@@ -556,6 +556,24 @@ function hasDispatchAfterTerminal(meshId: string, sessionId: string, terminalId:
     return false;
 }
 
+function hasUnterminalDirectDispatchLedgerEntry(meshId: string, sessionId: string): boolean {
+    // Some dispatch paths can persist task_dispatched before the direct-dispatch DB row is
+    // available. Recover routing from ledger order so coordinator self-targets still emit
+    // task_completed and pendingCoordinatorEvents.
+    const entries = readLedgerEntries(meshId, { tail: 200 });
+    for (let i = entries.length - 1; i >= 0; i--) {
+        const entry = entries[i];
+        if (entry.sessionId !== sessionId) continue;
+        if (entry.kind === 'task_completed' || entry.kind === 'task_failed' || entry.kind === 'task_stalled') {
+            return false;
+        }
+        if (entry.kind === 'task_dispatched' && entry.payload?.source === 'direct') {
+            return true;
+        }
+    }
+    return false;
+}
+
 function buildLongGeneratingCompletionReconciliation(args: {
     meshId: string;
     nodeId?: string;
@@ -1627,7 +1645,7 @@ export function setupMeshEventForwarding(components: DaemonComponents) {
         if (coordinatorMeshId) {
             try {
                 const activeDispatches = getActiveDirectDispatches(coordinatorMeshId);
-                if (activeDispatches.some(d => d.sessionId === instanceId)) {
+                if (activeDispatches.some(d => d.sessionId === instanceId) || hasUnterminalDirectDispatchLedgerEntry(coordinatorMeshId, instanceId)) {
                     meshIdFromDirectDispatch = coordinatorMeshId;
                 }
             } catch { /* best-effort */ }

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

@@ -729,7 +729,7 @@ export class CliProviderInstance implements ProviderInstance {
     }
 
     getSessionModalState(sessionId?: string): SessionModalState {
-        const adapterStatus = this.adapter.getStatus({ allowParse: false });
+        const adapterStatus = this.adapter.getStatus({ allowParse: true });
         const autoApproveActive = adapterStatus.status === 'waiting_approval' && this.shouldAutoApprove();
         const visibleStatus = autoApproveActive ? 'generating' : adapterStatus.status;
         const dirName = this.workingDir.split('/').filter(Boolean).pop() || 'session';

package/src/providers/external-sources.ts

@@ -0,0 +1,218 @@
+/**
+ * External provider sources — registry + active-selection state.
+ *
+ * A user can register one or more 3rd-party git URLs as provider sources.
+ * Each source clones into ~/.adhdev/external/<source-name>/, namespaced so
+ * that two sources can disk-coexist providing the same provider type.
+ *
+ * When two sources expose the same type, only one is "active" at a time.
+ * The active selection is persisted so a user's choice survives daemon
+ * restarts. When only one source provides a type, no explicit selection
+ * is needed and the loader falls through to that source.
+ */
+'use strict';
+
+import * as fs from 'node:fs';
+import * as os from 'node:os';
+import * as path from 'node:path';
+
+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>;
+}
+
+const SOURCES_FILENAME = 'providers-sources.json';
+const ACTIVE_FILENAME = 'providers-active.json';
+
+function adhdevDir(): string {
+    return path.join(os.homedir(), '.adhdev');
+}
+
+export function externalRoot(): string {
+    return path.join(adhdevDir(), 'external');
+}
+
+export function sourcesFilePath(): string {
+    return path.join(adhdevDir(), SOURCES_FILENAME);
+}
+
+export function activeFilePath(): string {
+    return path.join(adhdevDir(), ACTIVE_FILENAME);
+}
+
+function ensureAdhdevDir(): void {
+    const d = adhdevDir();
+    if (!fs.existsSync(d)) fs.mkdirSync(d, { recursive: true });
+}
+
+export function loadExternalSources(): ExternalSourcesFile {
+    const p = sourcesFilePath();
+    if (!fs.existsSync(p)) return { schema: 1, sources: [] };
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (!raw || typeof raw !== 'object') return { schema: 1, sources: [] };
+        const sources = Array.isArray(raw.sources) ? raw.sources.filter(isValidSource) : [];
+        return { schema: 1, sources };
+    } catch {
+        return { schema: 1, sources: [] };
+    }
+}
+
+export function saveExternalSources(file: ExternalSourcesFile): void {
+    ensureAdhdevDir();
+    const tmp = sourcesFilePath() + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, sourcesFilePath());
+}
+
+export function loadProvidersActive(): ProvidersActiveFile {
+    const p = activeFilePath();
+    if (!fs.existsSync(p)) return { schema: 1, active: {} };
+    try {
+        const raw = JSON.parse(fs.readFileSync(p, 'utf-8'));
+        if (!raw || typeof raw !== 'object') return { schema: 1, active: {} };
+        const active = raw.active && typeof raw.active === 'object' ? raw.active : {};
+        return { schema: 1, active };
+    } catch {
+        return { schema: 1, active: {} };
+    }
+}
+
+export function saveProvidersActive(file: ProvidersActiveFile): void {
+    ensureAdhdevDir();
+    const tmp = activeFilePath() + '.tmp';
+    fs.writeFileSync(tmp, JSON.stringify(file, null, 2) + '\n', 'utf-8');
+    fs.renameSync(tmp, activeFilePath());
+}
+
+function isValidSource(x: unknown): x is ExternalSource {
+    if (!x || typeof x !== 'object') return false;
+    const s = x as Record<string, unknown>;
+    return typeof s.name === 'string' && s.name.length > 0
+        && typeof s.url === 'string' && s.url.length > 0
+        && typeof s.ref === 'string' && s.ref.length > 0
+        && typeof s.addedAt === 'string';
+}
+
+/**
+ * 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 function deriveSourceName(url: string): string {
+    const m = url.match(/[/:]([^/:]+)\/([^/]+?)(?:\.git)?$/);
+    if (!m) return '@source';
+    const owner = m[1].toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+    const repo = m[2].toLowerCase().replace(/[^a-z0-9_-]/g, '-');
+    return `@${owner}-${repo}`;
+}
+
+/**
+ * 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 function inventoryExternalSources(): SourceInventoryEntry[] {
+    const root = externalRoot();
+    if (!fs.existsSync(root)) return [];
+    const out: SourceInventoryEntry[] = [];
+    let entries: fs.Dirent[];
+    try { entries = fs.readdirSync(root, { withFileTypes: true }); }
+    catch { return []; }
+    for (const sourceEntry of entries) {
+        if (!sourceEntry.isDirectory()) continue;
+        const sourceName = sourceEntry.name;
+        const sourceDir = path.join(root, sourceName);
+        const providers: Record<string, string[]> = {};
+        let categoryEntries: fs.Dirent[];
+        try { categoryEntries = fs.readdirSync(sourceDir, { withFileTypes: true }); }
+        catch { continue; }
+        for (const categoryEntry of categoryEntries) {
+            if (!categoryEntry.isDirectory()) continue;
+            const category = categoryEntry.name;
+            const categoryDir = path.join(sourceDir, category);
+            let typeEntries: fs.Dirent[];
+            try { typeEntries = fs.readdirSync(categoryDir, { withFileTypes: true }); }
+            catch { continue; }
+            const types: string[] = [];
+            for (const typeEntry of typeEntries) {
+                if (!typeEntry.isDirectory()) continue;
+                // Only count it as a provider if a manifest file exists
+                const typeDir = path.join(categoryDir, typeEntry.name);
+                const hasV1 = fs.existsSync(path.join(typeDir, 'provider.v1.json'));
+                const hasV0 = fs.existsSync(path.join(typeDir, 'provider.json'));
+                if (hasV1 || hasV0) types.push(typeEntry.name);
+            }
+            if (types.length > 0) providers[category] = types;
+        }
+        out.push({ sourceName, providers });
+    }
+    return out;
+}
+
+/**
+ * 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 function sourcesProviding(category: string, type: string): string[] {
+    const inventory = inventoryExternalSources();
+    return inventory
+        .filter(s => (s.providers[category] || []).includes(type))
+        .map(s => s.sourceName);
+}
+
+/**
+ * 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 function resolveActiveSource(
+    category: string,
+    type: string,
+    activeFile?: ProvidersActiveFile,
+): { source: string | null; ambiguous: boolean; candidates: string[] } {
+    const candidates = sourcesProviding(category, type);
+    if (candidates.length === 0) return { source: null, ambiguous: false, candidates };
+    if (candidates.length === 1) return { source: candidates[0], ambiguous: false, candidates };
+    const explicit = (activeFile ?? loadProvidersActive()).active[type];
+    if (explicit && candidates.includes(explicit)) {
+        return { source: explicit, ambiguous: false, candidates };
+    }
+    return { source: candidates[0], ambiguous: true, candidates };
+}

package/src/providers/provider-loader.ts

@@ -30,6 +30,10 @@ 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 type { ProviderSourceConfigSnapshot, ProviderUserDirSource } from '../config/provider-source-config.js';
 
@@ -215,6 +219,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 {
@@ -246,12 +277,12 @@ export class ProviderLoader {
    * Highest-priority editable overrides come first.
    */
   getProviderRoots(): string[] {
-    // Order matters: user customs > marketplace installs > upstream auto-sync.
-    // findProviderDirInternal walks this list in order to locate the provider
-    // dir containing the scripts/, so marketplace must be included here even
-    // though loadAll() also reads it directly.
-    const marketplaceDir = path.join(os.homedir(), '.adhdev', 'marketplace');
-    return [this.userDir, marketplaceDir, 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 {
@@ -343,16 +374,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);
@@ -363,15 +397,86 @@ export class ProviderLoader {
       this.log('Upstream loading disabled (sourceMode=no-upstream)');
     }
 
- // 2. Load marketplace installs from ~/.adhdev/marketplace/ (overrides upstream,
- //    but is itself overridden by user customs in step 3). These are providers the
- //    user explicitly installed via the Marketplace UI. They are NOT touched by
- //    upstream sync.
-    const marketplaceDir = path.join(os.homedir(), '.adhdev', 'marketplace');
-    if (fs.existsSync(marketplaceDir)) {
-      const marketplaceCount = this.loadDir(marketplaceDir);
-      if (marketplaceCount > 0) {
-        this.log(`Loaded ${marketplaceCount} marketplace-installed providers`);
+ // 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.`);
+        }
       }
     }
 
@@ -2132,14 +2237,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}`);
@@ -2151,6 +2282,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));
         }

package/src/providers/provider-trust.ts

@@ -0,0 +1,114 @@
+/**
+ * Provider trust classification.
+ *
+ * Each loaded provider gets a `trust` tag that the daemon and dashboard
+ * use to decide what to surface and what to gate behind a confirmation
+ * prompt. Trust is a function of *where* the provider came from
+ * (upstream / external / userDir) and the *shape of the manifest*
+ * (spec-only vs. carries JavaScript hooks).
+ *
+ * Rationale:
+ *   - Spec-only manifests are static declarative configuration; the
+ *     daemon's spec adapter walks the spec but never executes code
+ *     authored by the provider.
+ *   - Non-spec manifests ship JavaScript (tui-block builders consumed
+ *     by the SDK, scriptDir overrides, or explicit `overrides.* .path`
+ *     bindings). That code runs inside the daemon process with the
+ *     same privileges as adhdev itself.
+ *
+ * Source × shape decides the trust label:
+ *
+ *   layer    | spec-only           | non-spec
+ *   ---------|---------------------|-----------------------
+ *   user     | user-custom         | user-custom
+ *   upstream | trusted             | trusted-with-scripts
+ *   external | external-safe       | external-untrusted
+ *
+ * Dashboards should always show a badge for `trusted-with-scripts`
+ * (info — runs official JS), `external-safe` (info — declarative only,
+ * but 3rd-party), and `external-untrusted` (warning — runs JS from a
+ * 3rd-party). Activation of `external-untrusted` should require an
+ * explicit confirmation step that names the source URL.
+ */
+'use strict';
+
+export type ProviderTrust =
+    | 'user-custom'
+    | 'trusted'
+    | 'trusted-with-scripts'
+    | 'external-safe'
+    | 'external-untrusted';
+
+export type ProviderLayer = 'user' | 'upstream' | 'external';
+
+export interface ProviderManifestShape {
+    /** Has a `tui` block — SDK builders consume it as code paths. */
+    hasTui: boolean;
+    /** Has a non-empty `overrides` object — JS override paths. */
+    hasOverrides: boolean;
+    /** compatibility[].scriptDir or defaultScriptDir is set — JS scripts dir. */
+    hasScriptDir: boolean;
+}
+
+/**
+ * Inspect a manifest to decide whether it ships JavaScript hooks.
+ * Cheap; pure; safe to call on every provider load.
+ */
+export function inspectManifestShape(manifest: Record<string, unknown>): ProviderManifestShape {
+    const hasTui = !!manifest.tui && typeof manifest.tui === 'object'
+        && Object.keys(manifest.tui as Record<string, unknown>).length > 0;
+    const hasOverrides = !!manifest.overrides && typeof manifest.overrides === 'object'
+        && !Array.isArray(manifest.overrides)
+        && Object.keys(manifest.overrides as Record<string, unknown>).length > 0;
+    const compat = Array.isArray(manifest.compatibility) ? manifest.compatibility : [];
+    const compatHasScriptDir = compat.some((entry: any) => typeof entry?.scriptDir === 'string');
+    const hasScriptDir = compatHasScriptDir || typeof manifest.defaultScriptDir === 'string';
+    return { hasTui, hasOverrides, hasScriptDir };
+}
+
+/**
+ * Classify trust given the layer the provider was loaded from + the
+ * manifest's JS-hook footprint.
+ */
+export function classifyTrust(
+    layer: ProviderLayer,
+    shape: ProviderManifestShape,
+): ProviderTrust {
+    const isSpecOnly = !shape.hasTui && !shape.hasOverrides && !shape.hasScriptDir;
+    switch (layer) {
+        case 'user':
+            return 'user-custom';
+        case 'upstream':
+            return isSpecOnly ? 'trusted' : 'trusted-with-scripts';
+        case 'external':
+            return isSpecOnly ? 'external-safe' : 'external-untrusted';
+    }
+}
+
+/**
+ * Returns true when activation should require an explicit user confirm.
+ * Today only `external-untrusted` qualifies; future trust levels may
+ * fold in here.
+ */
+export function requiresConfirmation(trust: ProviderTrust): boolean {
+    return trust === 'external-untrusted';
+}
+
+/**
+ * Render a short human-readable rationale for the trust tag. Used by
+ * the dashboard's confirmation modal and the provider catalog tooltip.
+ */
+export function describeTrust(trust: ProviderTrust): string {
+    switch (trust) {
+        case 'user-custom':
+            return 'Hand-authored in ~/.adhdev/providers/. Runs your own code.';
+        case 'trusted':
+            return 'Official, declarative-only manifest from the ADHDev registry.';
+        case 'trusted-with-scripts':
+            return 'Official manifest from the ADHDev registry. Ships JavaScript hooks executed by the daemon.';
+        case 'external-safe':
+            return 'Manifest from a 3rd-party git source you added. Declarative-only — the daemon never runs JS from this source.';
+        case 'external-untrusted':
+            return 'Manifest from a 3rd-party git source you added. Ships JavaScript that the daemon will execute. Treat as untrusted code — review the source before enabling.';
+    }
+}

package/src/providers/sdk/v1/builders/cli/parse-approval.ts

@@ -44,6 +44,7 @@ export interface ModalTuiSpec {
   questionVariants?: ModalQuestionVariant[];
   buttonPattern: string;
   buttonFlags?: string;
+  buttonLabelGroup?: number;
   /**
    * Optional fallback for terminals that render all options on a single line
    * (e.g. Antigravity feedback survey: `[0] skip [1] yes [2] no [3] still using`).
@@ -136,12 +137,16 @@ function extractButtons(
 ): string[] {
   const buttonRe = compile(spec.buttonPattern, spec.buttonFlags ?? 'm');
   const out: string[] = [];
+  const labelGroup = Number.isInteger(spec.buttonLabelGroup) && (spec.buttonLabelGroup ?? 0) > 0
+    ? spec.buttonLabelGroup!
+    : 1;
   let i = windowStart;
   while (i < windowEnd) {
     const line = lines[i];
     const m = buttonRe.exec(line);
-    if (m && m[1]) {
-      let label = m[1].trim();
+    const captured = m?.[labelGroup] ?? (labelGroup === 1 && m && m.length > 2 ? m[m.length - 1] : undefined);
+    if (m && captured) {
+      let label = captured.trim();
       // Continuation lines: when enabled, append indented lines below until
       // the next button or blank.
       if (spec.continuationLines) {

package/src/providers/sdk/v1/index.ts

@@ -143,7 +143,7 @@ export const V1_PRIMITIVE_CATALOG = Object.freeze({
   ],
 } as const);
 
-/** Aggregate flat list — for marketplace catalog endpoint. */
+/** Aggregate flat list — for provider catalog endpoints. */
 export const V1_ALL_PRIMITIVES: ReadonlyArray<string> = Object.freeze(
   Object.values(V1_PRIMITIVE_CATALOG).flat(),
 );

package/src/providers/sdk/v1/sandbox/require-whitelist.ts

@@ -344,7 +344,7 @@ function canonicalize(p: string): string | null {
                 ? nodeFs.realpathSync.native(resolved)
                 : nodeFs.realpathSync(resolved);
         } catch {
-            // Root may not exist yet (e.g. marketplace dir created lazily);
+            // Root may not exist yet (e.g. external dir created lazily);
             // we still register the resolved path so future requires from
             // inside are gated once the directory shows up.
             return resolved;