@adhdev/daemon-core 0.9.82-rc.456 → 0.9.82-rc.458

package/dist/logging/debug-config.d.ts

@@ -14,6 +14,22 @@ export interface DebugRuntimeConfig {
     traceBufferSize: number;
     traceCategories: string[];
 }
+/**
+ * ALWAYS-ON trace categories. These bypass the `collectDebugTrace` master switch
+ * (and category selection) so they are collected in production daemons where
+ * `--trace` is unset. They exist so mesh completion diagnostics — the FSM-transition
+ * and completion-gate snapshots that explain an early / missing agent:generating_completed
+ * notification — are retrievable via mesh_read_debug (chat_debug_bundle) without asking
+ * an operator to relaunch the daemon with tracing on.
+ *
+ * SAFETY: only add a category here after confirming every record() call site for it
+ * carries a content-free payload (statuses, epochs, timestamps, deltas, lengths, roles,
+ * enum-like reasons — never transcript / prompt / bubble text). Always-on collection makes
+ * such payloads unconditional, so a content-bearing field would leak into the ring buffer
+ * in production.
+ */
+export declare const ALWAYS_ON_TRACE_CATEGORIES: readonly string[];
+export declare function isAlwaysOnTraceCategory(category?: string | null): boolean;
 export declare function resolveDebugRuntimeConfig(options?: DebugRuntimeOptions): DebugRuntimeConfig;
 export declare function setDebugRuntimeConfig(config: DebugRuntimeConfig): void;
 export declare function getDebugRuntimeConfig(): DebugRuntimeConfig;

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,60 @@ 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>;
+/**
+ * Read each registered submodule's configured `branch` from `.gitmodules`, keyed
+ * by the submodule's normalized path (matching {@link getRegisteredSubmodulePaths}).
+ *
+ * `.gitmodules` stores `submodule.<name>.path` and (optionally)
+ * `submodule.<name>.branch`; this joins the two on `<name>`. The special branch
+ * value `.` ("track the superproject's branch") is deliberately OMITTED so callers
+ * fall through to remote-HEAD detection instead of treating `.` as a literal branch
+ * name. Returns an empty map when there are no submodules, no `.gitmodules`, or the
+ * lookup fails (conservative — callers then detect or fall back).
+ */
+export declare function getSubmoduleConfiguredBranches(workspace: string): Map<string, string>;
+/** Fallback submodule branch when no configured/detected default can be resolved. */
+export declare const SUBMODULE_DEFAULT_BRANCH_FALLBACK = "main";
+/**
+ * Resolve the default branch a submodule's commits are published to / checked for
+ * reachability against. Generalizes the previously hardcoded `main` so a submodule
+ * whose default branch is `master`/`trunk`/etc. is handled. Priority (each tier
+ * falls through to the next on miss/error):
+ *
+ *   1. `.gitmodules` `submodule.<name>.branch` (via {@link getSubmoduleConfiguredBranches};
+ *      `.` is ignored) — an explicit, local, zero-cost declaration.
+ *   2. the submodule checkout's LOCAL remote HEAD: `git symbolic-ref --short
+ *      refs/remotes/<remote>/HEAD` → strip the `<remote>/` prefix (no network).
+ *   3. the submodule remote's advertised HEAD: `git ls-remote --symref <remote> HEAD`
+ *      → `ref: refs/heads/<branch>` (one network round-trip).
+ *   4. fallback {@link SUBMODULE_DEFAULT_BRANCH_FALLBACK} (`'main'`).
+ *
+ * Because the final fallback is `'main'` and every earlier tier that resolves `'main'`
+ * yields the same string, a repo whose submodules default to `main` (the common case)
+ * produces byte-identical downstream fetch/merge-base/push ref targets — only a
+ * read-only resolution probe is added.
+ */
+export declare function resolveSubmoduleDefaultBranch(opts: {
+    /** The submodule's local checkout — cwd for symbolic-ref / ls-remote. */
+    submoduleRepoPath: string;
+    /** The superproject workspace — for the `.gitmodules` branch lookup (tier 1). */
+    superprojectWorkspace?: string;
+    /** The submodule's path relative to the superproject (key into `.gitmodules`). */
+    submodulePath?: string;
+    /** Remote name (default `origin`). */
+    remote?: string;
+    /** Timeout for the local probe (tier 2); the network probe (tier 3) gets max(this, 30s). */
+    timeoutMs?: number;
+}): Promise<string>;
 export declare function isWorktreeBootstrapStaleRunning(node: {
     worktreeBootstrap?: {
         status?: string;

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

@@ -299,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;
     /**

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.456",
+  "version": "0.9.82-rc.458",
   "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.456",
-    "@adhdev/session-host-core": "0.9.82-rc.456",
+    "@adhdev/mesh-shared": "0.9.82-rc.458",
+    "@adhdev/session-host-core": "0.9.82-rc.458",
     "@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,6 +20,7 @@ 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';
@@ -692,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) => {
@@ -1121,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 || ''),
+    };
+}

package/src/index.ts

@@ -394,6 +394,8 @@ export {
     getDebugRuntimeConfig,
     resetDebugRuntimeConfig,
     shouldCollectTraceCategory,
+    isAlwaysOnTraceCategory,
+    ALWAYS_ON_TRACE_CATEGORIES,
 } from './logging/debug-config.js';
 export type { DebugRuntimeOptions, DebugRuntimeConfig } from './logging/debug-config.js';
 export {

package/src/logging/debug-config.ts

@@ -20,6 +20,26 @@ export interface DebugRuntimeConfig {
 const NORMAL_TRACE_BUFFER_SIZE = 200
 const DEV_TRACE_BUFFER_SIZE = 1000
 
+/**
+ * ALWAYS-ON trace categories. These bypass the `collectDebugTrace` master switch
+ * (and category selection) so they are collected in production daemons where
+ * `--trace` is unset. They exist so mesh completion diagnostics — the FSM-transition
+ * and completion-gate snapshots that explain an early / missing agent:generating_completed
+ * notification — are retrievable via mesh_read_debug (chat_debug_bundle) without asking
+ * an operator to relaunch the daemon with tracing on.
+ *
+ * SAFETY: only add a category here after confirming every record() call site for it
+ * carries a content-free payload (statuses, epochs, timestamps, deltas, lengths, roles,
+ * enum-like reasons — never transcript / prompt / bubble text). Always-on collection makes
+ * such payloads unconditional, so a content-bearing field would leak into the ring buffer
+ * in production.
+ */
+export const ALWAYS_ON_TRACE_CATEGORIES: readonly string[] = ['completion-gate', 'fsm-transition']
+
+export function isAlwaysOnTraceCategory(category?: string | null): boolean {
+  return !!category && ALWAYS_ON_TRACE_CATEGORIES.includes(category)
+}
+
 const DEFAULT_CONFIG: DebugRuntimeConfig = {
   logLevel: 'info',
   collectDebugTrace: false,
@@ -68,6 +88,11 @@ export function resetDebugRuntimeConfig(): void {
 
 export function shouldCollectTraceCategory(category?: string | null): boolean {
   const config = currentConfig
+  // Always-on categories are collected regardless of the collectDebugTrace master switch
+  // and regardless of any explicit traceCategories selection (they form a superset on top of
+  // whatever the operator requested), so an explicit --trace / --trace-categories run still
+  // includes them with its existing behavior unchanged.
+  if (isAlwaysOnTraceCategory(category)) return true
   if (!config.collectDebugTrace) return false
   if (!category) return true
   if (config.traceCategories.length === 0) return true

package/src/logging/debug-trace.ts

@@ -1,4 +1,4 @@
-import { getDebugRuntimeConfig, shouldCollectTraceCategory } from './debug-config.js'
+import { getDebugRuntimeConfig, isAlwaysOnTraceCategory, shouldCollectTraceCategory } from './debug-config.js'
 
 export type DebugTraceLevel = 'debug' | 'info' | 'warn' | 'error'
 
@@ -80,7 +80,12 @@ export function createDebugTraceStore(options: DebugTraceStoreOptions): DebugTra
 
   return {
     record(event: DebugTraceEvent): DebugTraceEntry | null {
-      if (!options.enabled) return null
+      // The store's `enabled` flag mirrors collectDebugTrace (set by configureDebugTraceStore),
+      // so it is false on a production daemon. Always-on categories must still land in the ring
+      // even then — otherwise the second gate here would swallow what shouldCollectTraceCategory
+      // just admitted. They share the same fixed-capacity buffer, so heavy always-on traffic can
+      // evict older opt-in entries; that is accepted (no separate ring).
+      if (!options.enabled && !isAlwaysOnTraceCategory(event.category)) return null
       const entry = createEntry(event)
       entries.push(entry)
       if (entries.length > capacity) {

package/src/mesh/coordinator-prompt.ts

@@ -577,7 +577,7 @@ function buildRulesSection(coordinatorCliType?: string): string {
 - **Verify via git, not source.** Use \`mesh_git_status\` to confirm side effects. Treat agent summaries as self-reports, not verification.
 - **Limit parallelism.** Start with 1–2 tasks; scale only on success. Never duplicate a session because \`mesh_read_chat\` shows no final message while tool/terminal activity is ongoing. This caps *concurrent* load — it does not mean serialize independent work: when a new, independent request arrives and there is headroom under \`maxParallelTasks\`, dispatch it right away rather than waiting for an in-flight task or a user nudge (read-only diagnosis especially, since it has no merge cost).
 - **Check history first.** Call \`mesh_task_history\` at session start to avoid duplicate work and inform recovery. On failure, read task history before retrying.
-- **Sequence shared-base-moving merges.** Parallel dispatch is encouraged, but merging one worktree can advance another in-flight worktree's base — especially the oss submodule pointer — turning a clean fast-forward into a diverged rebase (patch-equivalence correctly blocks this). Before merging an in-flight worktree while siblings are also in flight, land in an intentional order, re-clone long-running worktrees from the advanced base, or expect to manually rebase + ff-only the laggards; merging an independent fix mid-flight can strand siblings into a rebase.
+- **Sequence shared-base-moving merges.** Parallel dispatch is encouraged, but merging one worktree can advance another in-flight worktree's base — especially a shared submodule pointer — turning a clean fast-forward into a diverged rebase (patch-equivalence correctly blocks this). Before merging an in-flight worktree while siblings are also in flight, land in an intentional order, re-clone long-running worktrees from the advanced base, or expect to manually rebase + ff-only the laggards; merging an independent fix mid-flight can strand siblings into a rebase.
 - **Converge branches.** After worktree tasks: refine/fast-forward, or classify as \`pushed_feature_branch_needs_merge\` / \`blocked_review\` / \`cleanup_candidate\` / \`not_mergeable\`. Clean up with \`mesh_remove_node\`.
 - **Refinery is config-driven.** \`mesh_refine_node\` must run validation from \`.adhdev/refine.{json,yaml,yml}\` or \`repo-mesh.refine.*\`. Heuristics are scaffolding only.
 - **Submodule reachability = publish-needed.** \`submodule_reachability_failed\` → classify as \`blocked_review\`, request user approval to push to submodule main, then rerun \`mesh_refine_node\`.