@adhdev/daemon-core 0.9.82-rc.455 → 0.9.82-rc.457

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

@@ -15,4 +15,14 @@ export interface PreviewFreshness {
     }>;
     nextAction: string;
 }
-export declare function buildPreviewFreshness(repoRoot: string): PreviewFreshness;
+/**
+ * Gate: does this repository actually configure the preview-deploy pipeline?
+ *
+ * The preview-freshness surface embeds this project's private release-pipeline
+ * instructions (`npm run deploy:preview`, smoke preview, …). Those are only
+ * meaningful in a repo that ships the pipeline. An external repo joined to a
+ * mesh must not have that guidance leak into its coordinator prompt, so this
+ * gate keeps the surface off unless a concrete pipeline artifact is present.
+ */
+export declare function isPreviewPipelineConfigured(repoRoot: string): boolean;
+export declare function buildPreviewFreshness(repoRoot: string): PreviewFreshness | null;

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

@@ -29,6 +29,15 @@ export interface WorktreeBootstrapState extends MeshAsyncJobLifecycle {
     staleReason?: string;
 }
 export declare const WORKTREE_BOOTSTRAP_STALE_RUNNING_MS: number;
+/**
+ * Enumerate registered submodule paths for a worktree, generically (no hardcoded
+ * 'oss'/'adhdev-providers'). Reads `.gitmodules` via `git config --file .gitmodules
+ * --get-regexp path`, whose lines are `submodule.<name>.path <relativePath>`. Paths
+ * are returned normalized to forward slashes (git porcelain always emits '/'),
+ * trailing slash stripped. Returns an empty set when there are no submodules or the
+ * lookup fails — callers must then treat any change as dirty (conservative).
+ */
+export declare function getRegisteredSubmodulePaths(workspace: string): Set<string>;
 export declare function isWorktreeBootstrapStaleRunning(node: {
     worktreeBootstrap?: {
         status?: string;

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

@@ -6,6 +6,31 @@ import type { ProviderModule } from './contracts.js';
  * decline, which distinguishes it from a generic numbered menu or prose list.
  */
 export declare function hasNegativeApprovalOption(buttons: string[] | null | undefined): boolean;
+/**
+ * True when a button reliably identifies a tool-CONSENT modal on its own — a
+ * scoped permission-grant affirmative such as:
+ *   - "Yes, allow all edits in tmp/ during this session"
+ *   - "Yes, and don't ask again for example.com"
+ *   - "Yes, allow reading from etc/ from this project"
+ *   - "Always allow"
+ *
+ * These options only ever appear in a genuine approval/permission prompt; a
+ * /model or /mode picker ("1. Default  2. Opus  3. Sonnet") never offers a
+ * "grant this scope" choice. They therefore serve as a SECOND reliable
+ * structural anchor alongside {@link hasNegativeApprovalOption}.
+ *
+ * Why this exists (tall-diff fallback, #137): when a Write/Edit diff is tall,
+ * the trailing decline option ("3. No") can scroll off the bottom of the
+ * captured PTY frame, leaving only "1. Yes" + "2. Yes, allow … this session".
+ * hasNegativeApprovalOption then reads false and the auto-approve gate bails —
+ * a delegated worker sits forever on a modal it could safely have approved. The
+ * grant-scope affirmative lets the gate recognize the consent modal WITHOUT
+ * seeing the off-frame decline. The gate still selects the plain "Yes"
+ * (allow-once) via pickApprovalButton, never the broader grant, and the settle
+ * gate still requires a stable modal — so a half-rendered frame never fires.
+ * Kept deliberately narrow so no picker/confirm modal can trip it.
+ */
+export declare function hasReliableApprovalAffirmative(buttons: string[] | null | undefined): boolean;
 export declare function getApprovalPositiveHints(provider?: Pick<ProviderModule, 'approvalPositiveHints'> | null): string[];
 export declare function pickApprovalButton(buttons: string[] | null | undefined, provider?: Pick<ProviderModule, 'approvalPositiveHints'> | null): {
     index: number;

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

@@ -115,6 +115,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     private autoApproveSettleTimer;
     private autoApproveInactiveSince;
     private autoApproveMaskSince;
+    private stalledApprovalNudgeEpisode;
     private readonly manualAttendance;
     private controlValues;
     private summaryMetadata;
@@ -298,6 +299,10 @@ export declare class CliProviderInstance implements ProviderInstance {
      */
     private completingTurnTaskId;
     private meshTraceCtx;
+    private completionTraceOn;
+    private fsmTraceOn;
+    private recordCompletionGateTrace;
+    private recordFsmTransitionTrace;
     private flushCompletedDebounceIfFinalized;
     private maybeAutoApproveStatus;
     /**
@@ -355,7 +360,9 @@ export declare class CliProviderInstance implements ProviderInstance {
     get cliName(): string;
     private shouldAutoApprove;
     /** @see ProviderInstance.noteManualInteraction */
-    noteManualInteraction(now?: number): void;
+    noteManualInteraction(now?: number, opts?: {
+        passive?: boolean;
+    }): void;
     /**
      * Whether auto-approve should be treated as active *right now* for display
      * and firing decisions: the configured intent AND the user is not currently
@@ -366,6 +373,28 @@ export declare class CliProviderInstance implements ProviderInstance {
      */
     private autoApproveEffectivelyActive;
     private autoApproveMaskStalled;
+    /**
+     * NOTIF-APPROVAL-MASKED (Q1b): surface a delegated worker's STALLED auto-approve modal
+     * to the mesh COORDINATOR, decoupled from the dashboard visible-status mask.
+     *
+     * When auto-approve is configured but the episode never settles (modal parse miss / the
+     * settle gate never satisfied), getState()/detectStatusTransition() fold the raw
+     * `waiting_approval` into `generating` to suppress dashboard flicker — so
+     * detectStatusTransition()'s `waiting_approval` arm never runs and NO agent:waiting_approval
+     * event is emitted. The coordinator's real-time approval-nudge delivery then has no input and
+     * the worker's stuck modal is never surfaced (the live ~25s stall). The dashboard mask is
+     * intentional and stays; this emits the coordinator nudge exactly ONCE, gated on the SAME
+     * raw-waiting_approval + mask-stalled signal resolveModalParkStatus() distinguishes, the
+     * instant the mask-stall threshold trips (the same moment getState un-folds the mask).
+     *
+     * Only delegated worker sessions qualify: a foreground session has no coordinator to notify,
+     * and its own dashboard mask already reveals the modal on stall. A normally-resolving
+     * auto-approve never reaches AUTO_APPROVE_MASK_STALL_MS, so it emits nothing here; and if a
+     * masked approval clears just as this fires, rc.455's isApprovalNudgeResolved stale-drop
+     * discards the nudge coordinator-side without noise. Dedup is per-episode (keyed on the
+     * mask-clock value) so a modal that flaps between parsed/unparsed states is announced once.
+     */
+    private maybeEmitStalledApprovalNudge;
     private recordAutoApproval;
     recordApprovalSelection(buttonText: string): void;
     private formatMarkerTimestamp;

package/dist/providers/manual-attendance.d.ts

@@ -61,3 +61,19 @@ export declare class ManualAttendanceTracker {
  * pure read commands (read_chat / list_chats — passive polling, not driving).
  */
 export declare const MANUAL_ATTENDANCE_COMMANDS: ReadonlySet<string>;
+/**
+ * The subset of {@link MANUAL_ATTENDANCE_COMMANDS} that are PASSIVE view-only
+ * actions — foregrounding a session's tab / opening its panel. They convey "I am
+ * looking at this session", not "I am driving it", and carry no user input.
+ *
+ * For a foreground (base-node) session these still attend: a user who
+ * foregrounds their own session should get the quiet window so an incoming
+ * approval stays visible for them to act on. But for a DELEGATED worker session
+ * a passive peek must NOT attend — a coordinator merely opening a worker's panel
+ * to watch progress would otherwise suppress that worker's delegated
+ * auto-approve for the whole window (secondary cause, #137). The per-instance
+ * hook decides: it drops a passive stamp only when the session is a delegated
+ * worker, so explicit input (controlbar / resolve_action / pty_input) still
+ * attends a worker and a foreground session is unaffected.
+ */
+export declare const MANUAL_ATTENDANCE_PASSIVE_VIEW_COMMANDS: ReadonlySet<string>;

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

@@ -200,8 +200,15 @@ export interface ProviderInstance {
      * input). Provider-common signal that suppresses auto-approve for a short
      * window so the user can drive the session manually; background mesh worker
      * sessions never receive it, so their delegated auto-approve is unaffected.
+     *
+     * `opts.passive` marks a view-only action (select_session / open_panel). A
+     * delegated worker session ignores passive stamps so a coordinator merely
+     * watching its panel does not suppress its delegated auto-approve; explicit
+     * input still attends. Foreground sessions attend on passive views too.
      */
-    noteManualInteraction?(now?: number): void;
+    noteManualInteraction?(now?: number, opts?: {
+        passive?: boolean;
+    }): void;
     /** cleanup */
     dispose(): void;
 }

package/dist/providers/provider-loader.d.ts

@@ -55,10 +55,15 @@ export declare class ProviderLoader {
     private logFn;
     private versionArchive;
     private scriptsCache;
+    /**
+     * 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;
+    private readonly providerTarballUrl;
     /** Inject VersionArchive so resolve() can auto-detect installed versions */
     setVersionArchive(archive: VersionArchive): void;
-    private static readonly GITHUB_TARBALL_URL;
-    private static readonly REGISTRY_BASE_URL;
     private static readonly META_FILE;
     private static readonly REGISTRY_META_FILE;
     private static readonly REPO_PROVIDER_DIRNAME;
@@ -85,6 +90,16 @@ export declare 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;
     });
     private migrateMarketplaceDirToExternal;
     private log;

package/dist/providers/spec/fsm-driver.d.ts

@@ -181,6 +181,11 @@ export declare class FsmDriver implements ISpecDriver {
      *  (−1 = whole screen), or a `section:<id>` / `<region>#ignore:<pat>` string
      *  when the clause scopes to a section or declares an ignore_lines filter. */
     private regionLastChangedAt;
+    /** COMPLETION-EARLYNOTIFY stable-eval trace: last stable/not-stable verdict
+     *  recorded per stable region, so the trace fires only when the verdict FLIPS
+     *  (not every quiet frame). Cleared on every transition alongside
+     *  regionLastChangedAt. Diagnostic-only — never consulted by the FSM. */
+    private stableVerdictCache;
     /** Timer that re-runs evaluate() when a time-condition would flip true
      *  with no PTY frame to trigger it. */
     private wakeTimer;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.455",
+  "version": "0.9.82-rc.457",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,8 +46,8 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.455",
-    "@adhdev/session-host-core": "0.9.82-rc.455",
+    "@adhdev/mesh-shared": "0.9.82-rc.457",
+    "@adhdev/session-host-core": "0.9.82-rc.457",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",
     "ajv-formats": "^3.0.1",

package/src/boot/daemon-lifecycle.ts

@@ -180,6 +180,8 @@ export async function initDaemonComponents(config: DaemonInitConfig): Promise<Da
         logFn: config.providerLogFn,
         sourceMode: providerSourceMode,
         userDir: appConfig.providerDir,
+        registryUrl: appConfig.registryUrl,
+        providerTarballUrl: appConfig.providerTarballUrl,
     });
 
     // Boot-time auto-sync is intentionally disabled. The user picks which

package/src/commands/handler.ts

@@ -20,13 +20,14 @@ import type { ProviderModule, ProviderScripts } from '../providers/contracts.js'
 import type { DaemonAgentStreamManager } from '../agent-stream/index.js';
 import type { CliAdapter } from '../cli-adapter-types.js';
 import { loadConfig } from '../config/config.js';
+import { resolveRegistryBaseUrl } from '../config/registry-resolver.js';
 import { ChatHistoryWriter } from '../config/chat-history.js';
 import type { SessionRegistry, SessionRuntimeTarget } from '../sessions/registry.js';
 import { reconcileIdeRuntimeSessions } from '../sessions/reconcile.js';
 import { LOG } from '../logging/logger.js';
 import { resolveLegacyProviderScript, type LegacyStringScript } from './provider-script-resolver.js';
 import { sha256Hex } from '../system/hash.js';
-import { MANUAL_ATTENDANCE_COMMANDS } from '../providers/manual-attendance.js';
+import { MANUAL_ATTENDANCE_COMMANDS, MANUAL_ATTENDANCE_PASSIVE_VIEW_COMMANDS } from '../providers/manual-attendance.js';
 
 // Sub-module imports
 import * as Chat from './chat-commands.js';
@@ -393,15 +394,18 @@ export class DaemonCommandHandler implements CommandHelpers {
      */
     private noteManualAttendanceIfApplicable(cmd: string, args: any): void {
         if (!MANUAL_ATTENDANCE_COMMANDS.has(cmd)) return;
+        // Passive view-only actions (select_session / open_panel) attend a
+        // foreground session but NOT a delegated worker — the instance decides.
+        const passive = MANUAL_ATTENDANCE_PASSIVE_VIEW_COMMANDS.has(cmd);
         const sessionId = this._currentRoute.session?.sessionId
             || (typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim() : '');
         if (!sessionId) return;
         const session = this._ctx.sessionRegistry?.get(sessionId);
         const instanceKey = session?.adapterKey || session?.instanceKey || sessionId;
         const instance = this._ctx.instanceManager?.getInstance(instanceKey) as
-            { noteManualInteraction?: (now?: number) => void } | undefined;
+            { noteManualInteraction?: (now?: number, opts?: { passive?: boolean }) => void } | undefined;
         try {
-            instance?.noteManualInteraction?.();
+            instance?.noteManualInteraction?.(undefined, { passive });
         } catch {
             // attendance is best-effort — never block command dispatch
         }
@@ -689,7 +693,7 @@ export class DaemonCommandHandler implements CommandHelpers {
         const https = require('https') as typeof import('https');
         const fs = require('fs') as typeof import('fs');
         const path = require('path') as typeof import('path');
-        const REGISTRY = 'https://api.adhf.dev/api/v1/registry';
+        const REGISTRY = resolveRegistryBaseUrl(loadConfig().registryUrl);
 
         function fetchText(url: string, timeoutMs: number): Promise<string> {
             return new Promise((resolve, reject) => {
@@ -1118,7 +1122,7 @@ export class DaemonCommandHandler implements CommandHelpers {
         if (!installed.success) return installed;
 
         const https = require('https') as typeof import('https');
-        const REGISTRY = 'https://api.adhf.dev/api/v1/registry';
+        const REGISTRY = resolveRegistryBaseUrl(loadConfig().registryUrl);
 
         function fetchJson(url: string): Promise<any> {
             return new Promise((resolve, reject) => {

package/src/commands/low-family/daemon-lifecycle.ts

@@ -19,6 +19,10 @@ const CHANNEL_SERVER_URL: Record<ReleaseChannel, string> = {
     stable: 'https://api.adhf.dev',
     preview: 'https://api-preview.adhf.dev',
 };
+// Vendor-managed serverUrls. A serverUrl equal to one of these (or unset) is
+// steered to the channel default on upgrade; any other value is a user-set
+// custom/self-host URL that must be preserved across upgrades.
+const VENDOR_SERVER_URLS = new Set<string>(Object.values(CHANNEL_SERVER_URL));
 
 function normalizeReleaseChannel(value: unknown): ReleaseChannel | null {
     if (typeof value !== 'string') return null;
@@ -51,7 +55,16 @@ export const daemonLifecycleHandlers: Record<string, LowFamilyHandler> = {
             // Check channel-pinned dist-tag and resolve it to a concrete install version.
             const latest = String(execNpmCommandSync(['view', `${pkgName}@${npmTag}`, 'version'], { encoding: 'utf-8', timeout: 10000 }, npmSurface)).trim();
             LOG.info('Upgrade', `Latest ${pkgName}@${npmTag}: v${latest}`);
-            updateConfig({ updateChannel: channel, serverUrl: CHANNEL_SERVER_URL[channel] } as any);
+            // Only steer serverUrl to the channel's vendor default when the current
+            // value is unset or already a vendor default. A self-hoster's custom
+            // serverUrl must survive the upgrade instead of being clobbered.
+            const currentServerUrl = typeof loadConfig().serverUrl === 'string' ? loadConfig().serverUrl.trim() : '';
+            const useVendorServerUrl = currentServerUrl === '' || VENDOR_SERVER_URLS.has(currentServerUrl);
+            updateConfig(
+                useVendorServerUrl
+                    ? { updateChannel: channel, serverUrl: CHANNEL_SERVER_URL[channel] } as any
+                    : { updateChannel: channel } as any,
+            );
             let currentInstalled: string | null = null;
             try {
                 const currentJson = String(execNpmCommandSync(['ls', '-g', pkgName, '--depth=0', '--json'], {

package/src/commands/med-family/mesh-crud.ts

@@ -12,6 +12,7 @@
 import { daemonIdsEquivalent, meshNodeIdMatches, normalizeMeshNodeId } from '@adhdev/mesh-shared';
 import { resolveMeshHostStatus, normalizeMeshDaemonRole } from '../../mesh/mesh-host-ownership.js';
 import {
+    getRegisteredSubmodulePaths,
     loadMeshWorktreeBootstrapConfig,
     runMeshWorktreeBootstrap,
     type WorktreeBootstrapState,
@@ -81,6 +82,83 @@ export async function decideOssCloneSync(
     return 'skip_diverged';
 }
 
+/**
+ * Sync every registered submodule of a freshly-cloned worktree to its clone source
+ * node's working submodule HEAD, applying decideOssCloneSync's origin-tip-priority
+ * rewind guard per submodule.
+ *
+ * Generic over the submodule set: the paths come from `.gitmodules` via
+ * getRegisteredSubmodulePaths, so this operates identically over EVERY registered
+ * submodule (oss, adhdev-providers, …) instead of a hardcoded 'oss' literal. In a
+ * repo whose only synced submodule is `oss` the emitted git commands are byte-identical
+ * to the original oss-only path.
+ *
+ * Best-effort by design: a failure on one submodule is logged and skipped; it never
+ * blocks the other submodules or the clone. A submodule is only ever advanced to a
+ * STRICTLY-NEWER source SHA — the fresh (origin/main-derived) worktree tip is never
+ * rewound onto a behind/diverged source.
+ */
+export async function syncClonedWorktreeSubmodules(
+    worktreePath: string,
+    sourceWorkspace: string,
+    rg: (ctx: GitRepoIdentity, argv: string[], opts?: { timeoutMs?: number }) => Promise<unknown>,
+): Promise<void> {
+    const submodulePaths = getRegisteredSubmodulePaths(worktreePath);
+    if (submodulePaths.size === 0) return;
+
+    const sourceCtx: GitRepoIdentity = { workspace: sourceWorkspace, repoRoot: sourceWorkspace, isGitRepo: true };
+    const worktreeCtx: GitRepoIdentity = { workspace: worktreePath, repoRoot: worktreePath, isGitRepo: true };
+    const readStdout = (out: unknown): string =>
+        (typeof out === 'string' ? out : (out as any)?.stdout ?? '').trim();
+
+    for (const submodulePath of submodulePaths) {
+        try {
+            // Read the source node's working submodule SHA.
+            const sourceStatusOut = await rg(sourceCtx, ['submodule', 'status', submodulePath], { timeoutMs: 10000 });
+            const sourceSha = readStdout(sourceStatusOut).match(/^[+\- ]?([0-9a-f]{40})/)?.[1];
+            if (!sourceSha) continue;
+
+            // Read the worktree's freshly-checked-out submodule HEAD.
+            const subCtx: GitRepoIdentity = {
+                workspace: `${worktreePath}/${submodulePath}`,
+                repoRoot: `${worktreePath}/${submodulePath}`,
+                isGitRepo: true,
+            };
+            const worktreeSubSha = readStdout(await rg(subCtx, ['rev-parse', 'HEAD'], { timeoutMs: 10000 }));
+            if (!worktreeSubSha || worktreeSubSha === sourceSha) continue;
+
+            // Bring the source node's submodule HEAD into the worktree submodule object
+            // DB so both SHAs are resolvable for the ancestry (rewind) guard below.
+            await rg(subCtx, ['fetch', `${sourceWorkspace}/${submodulePath}`, 'HEAD'], { timeoutMs: 60000 });
+
+            // Rewind guard: the worktree submodule HEAD was just checked out from the
+            // FRESH (origin/main-derived) root base. Only advance to the source SHA when
+            // it is strictly newer — never rewind to a stale source.
+            let action: OssCloneSyncAction;
+            try {
+                action = await decideOssCloneSync(subCtx, worktreeSubSha, sourceSha, rg);
+            } catch (decideErr: any) {
+                action = 'skip_diverged';
+                console.warn(`[mesh] ${submodulePath} submodule sync guard could not resolve ancestry (kept fresh worktree HEAD): ${decideErr?.message ?? decideErr}`);
+            }
+
+            if (action === 'advance') {
+                await rg(subCtx, ['checkout', sourceSha], { timeoutMs: 10000 });
+                await rg(worktreeCtx, ['add', submodulePath], { timeoutMs: 10000 });
+                await rg(worktreeCtx, ['commit', '-m', `chore: sync ${submodulePath} to source node HEAD on clone`], { timeoutMs: 10000 });
+                console.log(`[mesh] Advanced ${submodulePath} submodule to newer source HEAD ${sourceSha.slice(0, 8)} in worktree`);
+            } else if (action === 'skip_rewind') {
+                console.warn(`[mesh] Skipped ${submodulePath} submodule rewind on clone: source node ${submodulePath} ${sourceSha.slice(0, 8)} is an ancestor of the fresh worktree ${submodulePath} ${worktreeSubSha.slice(0, 8)} — kept fresher worktree HEAD`);
+            } else if (action === 'skip_diverged') {
+                console.warn(`[mesh] Skipped ${submodulePath} submodule sync on clone: source node ${submodulePath} ${sourceSha.slice(0, 8)} diverged from the fresh worktree ${submodulePath} ${worktreeSubSha.slice(0, 8)} — kept worktree HEAD (coordinator reconciles)`);
+            }
+        } catch (subErr: any) {
+            // Per-submodule best-effort: never let one submodule's failure block the rest.
+            console.warn(`[mesh] ${submodulePath} submodule sync to source HEAD failed (best-effort):`, subErr?.message ?? subErr);
+        }
+    }
+}
+
 export const meshCrudHandlers: Record<string, MedFamilyHandler> = {
     list_meshes: async (ctx: MedFamilyContext, _args: any) => {
         try {
@@ -1019,57 +1097,13 @@ export const meshCrudHandlers: Record<string, MedFamilyHandler> = {
                         );
                         submodulesInitialized = true;
 
-                        // Sync oss submodule to source node HEAD (best-effort)
+                        // Sync every registered submodule to the clone source node's
+                        // working HEAD (best-effort, generic over .gitmodules — no
+                        // hardcoded 'oss'; the rewind guard is applied per submodule).
                         const sourceWorkspace = sourceNode.repoRoot || sourceNode.workspace;
                         if (sourceWorkspace) {
-                            try {
-                                const { runGit: rg } = await import('../../git/git-executor.js');
-                                const sourceCtx = { workspace: sourceWorkspace, repoRoot: sourceWorkspace, isGitRepo: true };
-                                const worktreeCtx = { workspace: result.worktreePath, repoRoot: result.worktreePath, isGitRepo: true };
-
-                                // Read source node's oss submodule SHA
-                                const sourceStatusOut = await rg(sourceCtx, ['submodule', 'status', 'oss'], { timeoutMs: 10000 });
-                                const sourceStatusLine = (typeof sourceStatusOut === 'string' ? sourceStatusOut : (sourceStatusOut as any)?.stdout ?? '').trim();
-                                const sourceShaMatch = sourceStatusLine.match(/^[+\- ]?([0-9a-f]{40})/);
-                                const sourceSha = sourceShaMatch?.[1];
-
-                                if (sourceSha) {
-                                    // Read worktree's current oss HEAD
-                                    const ossCtx = { workspace: `${result.worktreePath}/oss`, repoRoot: `${result.worktreePath}/oss`, isGitRepo: true };
-                                    const worktreeOssHeadOut = await rg(ossCtx, ['rev-parse', 'HEAD'], { timeoutMs: 10000 });
-                                    const worktreeOssSha = (typeof worktreeOssHeadOut === 'string' ? worktreeOssHeadOut : (worktreeOssHeadOut as any)?.stdout ?? '').trim();
-
-                                    if (worktreeOssSha && worktreeOssSha !== sourceSha) {
-                                        // Bring the source node's oss HEAD into the worktree object DB so
-                                        // both SHAs are resolvable for the ancestry (rewind) guard below.
-                                        await rg(ossCtx, ['fetch', `${sourceWorkspace}/oss`, 'HEAD'], { timeoutMs: 60000 });
-
-                                        // Rewind guard: the worktree oss HEAD was just checked out from the
-                                        // FRESH (origin/main-derived) root base. Only advance to the source
-                                        // SHA when it is strictly newer — never rewind to a stale source.
-                                        let ossAction: OssCloneSyncAction;
-                                        try {
-                                            ossAction = await decideOssCloneSync(ossCtx, worktreeOssSha, sourceSha, rg);
-                                        } catch (decideErr: any) {
-                                            ossAction = 'skip_diverged';
-                                            console.warn(`[mesh] oss submodule sync guard could not resolve ancestry (kept fresh worktree HEAD): ${decideErr?.message ?? decideErr}`);
-                                        }
-
-                                        if (ossAction === 'advance') {
-                                            await rg(ossCtx, ['checkout', sourceSha], { timeoutMs: 10000 });
-                                            await rg(worktreeCtx, ['add', 'oss'], { timeoutMs: 10000 });
-                                            await rg(worktreeCtx, ['commit', '-m', 'chore: sync oss to source node HEAD on clone'], { timeoutMs: 10000 });
-                                            console.log(`[mesh] Advanced oss submodule to newer source HEAD ${sourceSha.slice(0, 8)} in worktree`);
-                                        } else if (ossAction === 'skip_rewind') {
-                                            console.warn(`[mesh] Skipped oss submodule rewind on clone: source node oss ${sourceSha.slice(0, 8)} is an ancestor of the fresh worktree oss ${worktreeOssSha.slice(0, 8)} — kept fresher worktree HEAD`);
-                                        } else if (ossAction === 'skip_diverged') {
-                                            console.warn(`[mesh] Skipped oss submodule sync on clone: source node oss ${sourceSha.slice(0, 8)} diverged from the fresh worktree oss ${worktreeOssSha.slice(0, 8)} — kept worktree HEAD (coordinator reconciles)`);
-                                        }
-                                    }
-                                }
-                            } catch (ossErr: any) {
-                                console.warn('[mesh] oss submodule sync to source HEAD failed (best-effort):', ossErr.message);
-                            }
+                            const { runGit: rg } = await import('../../git/git-executor.js');
+                            await syncClonedWorktreeSubmodules(result.worktreePath, sourceWorkspace, rg);
                         }
                     } catch (subErr: any) {
                         // Submodule init is best-effort; don't fail the clone

package/src/config/config.ts

@@ -123,6 +123,22 @@ export interface ADHDevConfig {
  // Optional explicit provider override root (for example a local adhdev-providers checkout)
     providerDir?: string;
 
+    /**
+     * Optional provider registry base URL override (for example a self-hosted
+     * registry). Highest-priority source in the registry resolver, ahead of the
+     * `ADHDEV_REGISTRY_URL` env var and the vendor default. See
+     * `config/registry-resolver.ts`.
+     */
+    registryUrl?: string;
+
+    /**
+     * Optional provider tarball (archive) URL override so self-hosters can point
+     * the daemon at their own provider mirror instead of the vendor GitHub repo.
+     * Highest-priority source, ahead of `ADHDEV_PROVIDER_TARBALL_URL` and the
+     * vendor default. See `config/registry-resolver.ts`.
+     */
+    providerTarballUrl?: string;
+
     /** Preferred daemon update channel. Defaults to stable/latest. */
     updateChannel?: ReleaseChannel;
 
@@ -233,6 +249,8 @@ function normalizeConfig(raw: unknown): ADHDevConfig & { activeWorkspaceId?: str
         ideSettings: isPlainObject(parsed.ideSettings) ? parsed.ideSettings : {},
         providerSourceMode: resolveProviderSourceMode(parsed.providerSourceMode, parsed.disableUpstream),
         providerDir: asOptionalString(parsed.providerDir),
+        registryUrl: asOptionalString(parsed.registryUrl),
+        providerTarballUrl: asOptionalString(parsed.providerTarballUrl),
         updateChannel: parsed.updateChannel === 'preview' ? 'preview' : 'stable',
         terminalSizingMode: parsed.terminalSizingMode === 'fit' ? 'fit' : 'measured',
     };

package/src/config/registry-resolver.ts

@@ -0,0 +1,100 @@
+/**
+ * Registry / provider-distribution URL resolver.
+ *
+ * Single source of truth for the ADHDev provider *registry* base URL and the
+ * provider *tarball* (GitHub) URL. Self-hosters can repoint both away from the
+ * vendor defaults so the daemon never phones home to `api.adhf.dev` /
+ * `github.com/vilmire/adhdev-providers`.
+ *
+ * Resolution priority (highest first):
+ *   1. Explicit config field    — `config.registryUrl` / `config.providerTarballUrl`
+ *   2. Environment variable      — `ADHDEV_REGISTRY_URL` / `ADHDEV_PROVIDER_TARBALL_URL`
+ *   3. Vendor default            — existing URLs (unchanged for default users)
+ *
+ * Default users get byte-identical behavior: the vendor defaults equal the
+ * literals these functions replaced.
+ */
+
+/** Vendor default registry base URL (no trailing slash). */
+export const DEFAULT_REGISTRY_BASE_URL = 'https://api.adhf.dev/api/v1/registry';
+
+/** Vendor default provider tarball URL (GitHub main branch archive). */
+export const DEFAULT_PROVIDER_TARBALL_URL =
+    'https://github.com/vilmire/adhdev-providers/archive/refs/heads/main.tar.gz';
+
+/** Env var that overrides the registry base URL. */
+export const REGISTRY_URL_ENV_VAR = 'ADHDEV_REGISTRY_URL';
+
+/** Env var that overrides the provider tarball URL. */
+export const PROVIDER_TARBALL_URL_ENV_VAR = 'ADHDEV_PROVIDER_TARBALL_URL';
+
+function cleanString(value: unknown): string | undefined {
+    return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function stripTrailingSlashes(url: string): string {
+    return url.replace(/\/+$/, '');
+}
+
+/**
+ * Resolve the provider registry base URL.
+ *
+ * @param configuredUrl explicit config value (config.registryUrl); highest priority.
+ * @param env process env source (defaults to process.env; injectable for tests).
+ * @returns the resolved base URL with any trailing slash stripped, so callers
+ *   can safely append `/providers`, `/providers/<type>`, etc.
+ */
+export function resolveRegistryBaseUrl(
+    configuredUrl?: string | null,
+    env: NodeJS.ProcessEnv = process.env,
+): string {
+    const resolved =
+        cleanString(configuredUrl) ??
+        cleanString(env[REGISTRY_URL_ENV_VAR]) ??
+        DEFAULT_REGISTRY_BASE_URL;
+    return stripTrailingSlashes(resolved);
+}
+
+/**
+ * Resolve the provider tarball (archive) URL.
+ *
+ * @param configuredUrl explicit config value (config.providerTarballUrl); highest priority.
+ * @param env process env source (defaults to process.env; injectable for tests).
+ */
+export function resolveProviderTarballUrl(
+    configuredUrl?: string | null,
+    env: NodeJS.ProcessEnv = process.env,
+): string {
+    return (
+        cleanString(configuredUrl) ??
+        cleanString(env[PROVIDER_TARBALL_URL_ENV_VAR]) ??
+        DEFAULT_PROVIDER_TARBALL_URL
+    );
+}
+
+/** Parsed tarball request target for callers that issue raw hostname/path requests. */
+export interface TarballRequestTarget {
+    /** Full resolved tarball URL. */
+    url: string;
+    /** Hostname component (e.g. `github.com`). */
+    hostname: string;
+    /** Path component including any query string (e.g. `/vilmire/...tar.gz`). */
+    path: string;
+}
+
+/**
+ * Resolve the provider tarball URL and split it into `{ url, hostname, path }`
+ * for callers that build raw `https.request` options (e.g. HEAD ETag probes).
+ */
+export function resolveProviderTarballTarget(
+    configuredUrl?: string | null,
+    env: NodeJS.ProcessEnv = process.env,
+): TarballRequestTarget {
+    const url = resolveProviderTarballUrl(configuredUrl, env);
+    const parsed = new URL(url);
+    return {
+        url,
+        hostname: parsed.hostname,
+        path: parsed.pathname + (parsed.search || ''),
+    };
+}