@adhdev/daemon-core 0.9.82-rc.49 → 0.9.82-rc.490

package/dist/commands/router.d.ts

@@ -14,6 +14,11 @@ import { DaemonCliManager } from './cli-manager.js';
 import type { ProviderLoader } from '../providers/provider-loader.js';
 import type { ProviderInstanceManager } from '../providers/provider-instance-manager.js';
 import { SessionRegistry } from '../sessions/registry.js';
+import type { RepoMeshSessionCleanupMode } from '../repo-mesh-types.js';
+import { MeshRefineBatchJobHandle, MeshRefineBatchTerminalJob, MeshRefineJobHandle, MeshRefineTerminalJob } from '../mesh/mesh-refine-gates.js';
+export * from '../mesh/mesh-node-identity.js';
+export * from '../mesh/mesh-refine-gates.js';
+export * from '../mesh/mesh-coordinator-config.js';
 export interface SessionHostControlPlane {
     getDiagnostics(payload?: {
         includeSessions?: boolean;
@@ -55,12 +60,14 @@ export interface CommandRouterDeps {
         value: any[];
     };
     sessionRegistry: SessionRegistry;
-    /** Callback for CDP manager creation after launch_ide */
+    /** Callback after CDP manager created (transport-specific extras) */
     onCdpManagerCreated?: (ideType: string, manager: DaemonCdpManager) => void;
     /** Callback after IDE connected (e.g., startAgentStreamPolling) */
     onIdeConnected?: () => void;
     /** Callback after status change (stop_ide, restart) */
     onStatusChange?: () => void;
+    /** Callback when a mesh state is invalidated */
+    onMeshStateChange?: (meshId: string) => void;
     /** Callback after chat-related commands */
     onPostChatCommand?: () => void;
     /** Get a connected CDP manager (for agent stream reset check) */
@@ -81,34 +88,211 @@ export interface CommandRouterResult {
     success: boolean;
     [key: string]: unknown;
 }
+/**
+ * Confine a spec path to ~/.adhdev/providers, defeating both prefix-bypass
+ * (e.g. ".../providers-evil") and symlink escape. Resolves the real path of
+ * the *parent* directory (the file may not exist yet for writes), requires the
+ * basename to be a literal `*.json`, and re-joins under the verified parent so
+ * the returned path can't point outside the tree. Used by get/write_spec_source.
+ */
+export declare function normalizeStandaloneHostCommandUrl(hostAddress: string): string;
+export declare function buildMemberJoinNode(mesh: any, args: any, fallbackDaemonId?: string): Record<string, unknown> | null;
 export declare class DaemonCommandRouter {
-    private deps;
+    /** Public (not private) so the extracted ./router-refine.ts orchestration can reach it via `self`. */
+    deps: CommandRouterDeps;
     /** In-memory cache for cloud-originating meshes passed via inlineMesh.
      *  Allows the MCP server to query mesh data via get_mesh even when
      *  the mesh doesn't exist in the local meshes.json file. */
     private inlineMeshCache;
-    /** Coordinator-owned whole-mesh aggregate status snapshots. Browser callers read this by default. */
-    private aggregateMeshStatusCache;
+    /** Tombstones for inline mesh nodes removed via remove_mesh_node, keyed by
+     *  meshId → set of removed nodeIds. The dashboard keeps echoing the removed
+     *  node in the inlineMesh it attaches to every command; without a tombstone,
+     *  reconcileInlineMeshCache MERGEs it straight back (resurrection). A
+     *  tombstoned node is skipped during reconcile only while its workspace is
+     *  absent from disk — a genuine re-registration (same nodeId, workspace back
+     *  on disk) clears the tombstone and merges normally, preserving clone
+     *  worktree visibility and legitimate node re-creation. */
+    private removedInlineMeshNodeIds;
+    /** Coordinator-owned whole-mesh aggregate status snapshots. Browser callers read this by default.
+     *  Public (not private) so the extracted ./router-aggregate-status.ts orchestration can reach it via `self`. */
+    aggregateMeshStatusCache: Map<string, {
+        builtAt: number;
+        snapshot: any;
+        queueRevision: string;
+    }>;
+    /** Shared per-peer git_status probe dedup + recently-probed reuse gate.
+     *  Spans separate mesh_status/get_mesh calls so the dashboard auto-retry
+     *  loop cannot storm a slow peer with back-to-back refreshUpstream probes. */
+    private meshGitProbeCache;
+    /** Meshes with a background SWR freshen (async mesh_status refresh) already in
+     *  flight — so a burst of interactive detail-opens serves the cached snapshot
+     *  and coalesces onto ONE background refresh instead of storming the peers. */
+    private swrRefreshInFlight;
+    /** In-memory async Refinery jobs keyed by meshId:nodeId to reject/return duplicate in-flight requests.
+     *  Public (not private) so the extracted ./router-refine.ts orchestration can reach it via `self`. */
+    runningRefineJobs: Map<string, MeshRefineJobHandle>;
+    /** Terminal async Refinery jobs preserve a clear answer after the worktree node has been removed. */
+    terminalRefineJobs: Map<string, MeshRefineTerminalJob>;
+    /** In-memory async batch Refinery jobs keyed by meshId (one batch convergence per mesh at a time). */
+    runningRefineBatchJobs: Map<string, MeshRefineBatchJobHandle>;
+    /** Terminal async batch Refinery jobs preserve the last batch outcome for late readers. */
+    terminalRefineBatchJobs: Map<string, MeshRefineBatchTerminalJob>;
     constructor(deps: CommandRouterDeps);
-    private cloneJsonValue;
     private hydrateCachedAggregateMeshStatusFromInline;
     private getCachedAggregateMeshStatus;
     private rememberAggregateMeshStatus;
+    getCachedInlineMeshNodes(): any[];
+    resolveRemoteMeshSessionOwnerDaemonId(sessionId: string, ownerNodeIdHint?: string): string | undefined;
     getCachedInlineMesh(meshId: string, inlineMesh?: unknown): any | undefined;
     private warmInlineMeshCache;
-    private getMeshForCommand;
-    private invalidateAggregateMeshStatus;
+    getMeshForCommand(meshId: string, inlineMesh?: unknown, options?: {
+        preferInline?: boolean;
+    }): Promise<{
+        mesh: any;
+        inline: boolean;
+        source: 'inline_cache' | 'inline_bootstrap' | 'local_config';
+    } | null>;
+    invalidateAggregateMeshStatus(meshId: string): void;
+    /**
+     * Build the MedFamilyContext handed to RF-ROUTER MED family handlers. Binds the
+     * router-private collaborators those handlers need (mesh resolution, owner
+     * gating, inline-cache mutation, worktree / session cleanup, refine job
+     * starters, IDE stop/launch) plus the inline-mesh and git-probe caches. The
+     * `launchIde` field closes over the freshly-built context so restart_session /
+     * restart_ide invoke the IDE launch directly instead of recursing through
+     * executeDaemonCommand('launch_ide').
+     */
+    private buildMedFamilyContext;
+    /**
+     * Build the HighFamilyContext handed to RF-ROUTER HIGH family handlers. Binds
+     * the router-private collaborators those handlers need (mesh resolution, the
+     * aggregate-status memory cache + its bound read/write helpers, the
+     * running-refine-job table, inline-mesh + git-probe caches, and the router's
+     * own `execute` for the get_mesh_review_inbox mesh_status re-entry). HIGH
+     * handlers reach more router-owned state than MED, but the binding shape is
+     * the same: bound methods + direct field references, none reachable from
+     * `deps`.
+     */
+    private buildHighFamilyContext;
     private requireMeshHostMutationOwner;
     private updateInlineMeshNode;
     private removeInlineMeshNode;
-    private normalizeMeshSessionCleanupMode;
-    private sessionMatchesMeshNode;
-    private cleanupLocalWorktreeNode;
-    private getWorktreeForceCleanupConvergence;
-    private isCompletedHostedSession;
-    private recordIntentionalMeshSessionStop;
-    private cleanupMeshSessions;
-    private traceSessionHostAction;
+    /**
+     * WORKTREE-BOOTSTRAP-COORD-STATE: mark a worktree node's bootstrap as reaching a
+     * terminal state (complete / failed) in THIS daemon's mesh view.
+     *
+     * Root cause this fixes: clone_mesh_node forwards the clone+bootstrap to the
+     * source node's daemon (the worktree's machine). persistWorktreeSetupState
+     * therefore flips worktreeBootstrap.status to 'complete' on the WORKER daemon's
+     * mesh object — never on the coordinator's. The coordinator only ever holds the
+     * 'running' state it stamped from the forwarded clone reply. The claim path's
+     * bootstrap gate (mesh-event-forwarding agent:ready / mesh-queue-assignment)
+     * reads the coordinator's mesh via getMeshWithCache, sees status==='running'
+     * forever, and DEFERS every claim — so the worktree_bootstrap_complete re-fire
+     * (triggerMeshQueue) loops against a gate that never opens: claim never lands,
+     * the idle session is re-registered each tick, and auto-launch keeps spawning
+     * fresh sessions (runaway worktree-session multiplication).
+     *
+     * Called from the worktree_bootstrap_complete/_failed event handler BEFORE the
+     * queue re-fire so the gate sees the terminal state and the deferred claim can
+     * finally land. Updates the inline cache (clone worktree nodes are inline-only)
+     * and, when the node also exists in local config, persists there too; both paths
+     * invalidate the aggregate status cache. Best-effort and idempotent.
+     */
+    markWorktreeBootstrapTerminalState(meshId: string, nodeId: string, status: 'complete' | 'failed', opts?: {
+        workspace?: string;
+    }): void;
+    private tombstoneRemovedInlineMeshNode;
+    /** Filter an incoming inline mesh against this mesh's tombstones before it is
+     *  reconciled into the cache. A tombstoned node is dropped only while its
+     *  workspace is still absent from disk; if the workspace is back (genuine
+     *  re-registration), the tombstone is cleared and the node merges normally. */
+    private applyInlineMeshNodeTombstones;
+    normalizeMeshSessionCleanupMode(value: unknown): RepoMeshSessionCleanupMode;
+    sessionMatchesMeshNode(record: any, node: any, nodeId: string, sessionIds?: Set<string>): boolean;
+    bestEffortRemoveWorktreeDir(dir: string): Promise<{
+        removed: boolean;
+        residue: boolean;
+        error?: string;
+    }>;
+    precheckLocalWorktreeRemovable(args: {
+        mesh: any;
+        node: any;
+        nodeId: string;
+        force?: boolean;
+    }): Promise<{
+        ok: true;
+    } | {
+        ok: false;
+        code: string;
+        error: string;
+        recoveryHint: string;
+    }>;
+    cleanupLocalWorktreeNode(args: {
+        mesh: any;
+        node: any;
+        nodeId: string;
+        force?: boolean;
+    }): Promise<{
+        success: true;
+        skipped?: boolean;
+        removedPath?: string;
+        repoRoot?: string;
+        reason?: string;
+        fallback?: string;
+        forced?: boolean;
+        convergence?: Record<string, unknown>;
+        recovered?: boolean;
+        residue?: boolean;
+        residueWarning?: string;
+        residueError?: string;
+        branchRefDeleted?: boolean;
+        branchRefReason?: string;
+        branchRefForced?: boolean;
+        branchRefWarning?: string;
+    } | {
+        success: false;
+        code: string;
+        error: string;
+        recoveryHint: string;
+        convergence?: Record<string, unknown>;
+    }>;
+    getWorktreeForceCleanupConvergence(args: {
+        repoRoot: string;
+        workspace: string;
+        node: any;
+    }): Promise<{
+        allow: boolean;
+        status?: string;
+        source?: string;
+        ref?: string;
+        error?: string;
+    }>;
+    isCompletedHostedSession(record: any): boolean;
+    recordIntentionalMeshSessionStop(args: {
+        meshId: string;
+        nodeId: string;
+        node: any;
+        sessionId: string;
+        mode: RepoMeshSessionCleanupMode;
+        source: 'mesh_cleanup_sessions' | 'mesh_remove_node' | 'magi_session_cleanup';
+        action: 'stop_session' | 'delete_session_force';
+    }): Promise<void>;
+    cleanupMeshSessions(args: {
+        meshId: string;
+        nodeId: string;
+        node: any;
+        mode: RepoMeshSessionCleanupMode;
+        sessionIds?: string[];
+        dryRun?: boolean;
+        source?: 'mesh_cleanup_sessions' | 'mesh_remove_node' | 'magi_session_cleanup';
+        requireAutoLaunchedForTaskIds?: Record<string, string>;
+        reclaimOrphans?: boolean;
+        liveMeshNodeIds?: string[];
+    }): Promise<{
+        success: boolean;
+        [key: string]: unknown;
+    }>;
     /**
      * Unified command routing.
      * Returns result for all commands:
@@ -121,6 +305,10 @@ export declare class DaemonCommandRouter {
      * @param source Log source ('ws' | 'p2p' | 'standalone' | etc.)
      */
     execute(cmd: string, args: any, source?: string): Promise<CommandRouterResult>;
+    resumePendingRefineJobsOnStartup(): Promise<void>;
+    private batchRefineMeshNodes;
+    private startMeshRefineBatchJob;
+    private startMeshRefineJob;
     /**
      * Daemon-level command execution (IDE start/stop/restart, CLI, detect, logs).
      * Returns null if not handled at this level → caller delegates to CommandHandler.

package/dist/commands/upgrade-helper.d.ts

@@ -39,6 +39,46 @@ export declare function buildPinnedGlobalInstallCommand(options: {
 }): PinnedGlobalInstallCommand;
 export declare function getNpmExecOptions(platform?: NodeJS.Platform): NpmExecOptions;
 export declare function execNpmCommandSync(args: string[], options?: ExecFileSyncOptions, surface?: Pick<CurrentGlobalInstallSurface, 'npmExecutable' | 'npmArgsPrefix' | 'execOptions'>): Buffer | string;
-export declare function stopSessionHostProcesses(appName: string): void;
+export declare function stopSessionHostProcesses(appName: string): Promise<void>;
+/**
+ * Enumerate processes that have a locked native addon (conpty.node /
+ * ghostty-vt.dll) of *this* install memory-mapped.
+ *
+ * `stopSessionHostProcesses()` only knows the single managed session-host pid, so
+ * any *foreign* holder — e.g. an orphaned `pty_*probe*.cjs` left in `%TEMP%` — is
+ * invisible to it and keeps the addon locked through every install retry, dooming
+ * the upgrade with EBUSY. This scans by the module's full path so we only ever
+ * target a holder of the exact `packageRoot` being replaced (never an unrelated
+ * install's copy). Windows-only — these locks don't exist on POSIX.
+ */
+export declare function listForeignNativeAddonHolders(packageRoot: string | null | undefined): Array<{
+    pid: number;
+    commandLine: string | null;
+}>;
+/**
+ * Terminate every foreign process holding this install's native addon mapped,
+ * then wait for each to actually exit so the mapping is released before npm
+ * copies the file into its staging dir. Returns what it found/killed so the
+ * caller can surface an actionable recovery message on failure.
+ */
+export declare function stopForeignNativeAddonHolders(packageRoot: string | null | undefined, options?: {
+    parentPid?: number;
+}): Promise<Array<{
+    pid: number;
+    commandLine: string | null;
+    killed: boolean;
+}>>;
+/**
+ * Best-effort removal of a leftover npm staging entry.
+ *
+ * A stale staging dir can hold a locked native binary — e.g. `ghostty-vt.dll`
+ * from `@adhdev/ghostty-vt-node` still mapped by a lingering session-host
+ * process — which makes `rmSync` throw `EPERM` on Windows. Staging cleanup is
+ * only housekeeping: the leftover is inert and npm creates its own fresh
+ * staging dir for the real install, so a lock on an old leftover must NOT abort
+ * the upgrade. Log and continue instead of letting the error propagate.
+ */
+export declare function safeRemoveStaleEntry(target: string, label: string): void;
+export declare function cleanupStaleGlobalInstallDirs(pkgName: string, surface: CurrentGlobalInstallSurface): void;
 export declare function spawnDetachedDaemonUpgradeHelper(payload: DaemonUpgradeHelperPayload): void;
 export declare function maybeRunDaemonUpgradeHelperFromEnv(): Promise<boolean>;

package/dist/config/chat-history.d.ts

@@ -110,12 +110,23 @@ export declare function readProviderChatHistory(agentType: string, options?: {
     excludeRecentCount?: number;
     historyBehavior?: ProviderHistoryBehavior;
     scripts?: ProviderNativeHistoryScripts;
+    excludeInProgressTurn?: boolean;
+    sessionStartedAtMs?: number;
+    envOverrides?: Record<string, string>;
+    forceRefresh?: boolean;
+    instanceId?: string;
 }): {
     messages: HistoryMessage[];
     hasMore: boolean;
     source: 'provider-native' | 'adhdev-mirror' | 'native-unavailable';
     sourcePath?: string;
     sourceMtimeMs?: number;
+    providerSessionId?: string;
+    workspace?: string;
+    nativeHistoryCoverage?: string;
+    partialReason?: string;
+    unavailableReason?: string;
+    ownerConfirmed?: boolean;
 };
 export declare function listProviderHistorySessions(agentType: string, options?: {
     canonicalHistory?: ProviderCanonicalHistoryConfig;

package/dist/config/config.d.ts

@@ -71,6 +71,20 @@ export interface ADHDevConfig {
     disableUpstream?: boolean;
     providerSourceMode?: ProviderSourceMode;
     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;
     /**
@@ -86,6 +100,11 @@ export declare function isStableMachineId(machineId?: string | null): boolean;
  * Get the config directory path
  */
 export declare function getConfigDir(): string;
+/**
+ * Get the daemon runtime data directory (~/.adhdev/daemon/).
+ * Distinct from the user-config dir so runtime state can be cleared independently.
+ */
+export declare function getDaemonDataDir(): string;
 /**
  * Load configuration from disk
  */

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

@@ -6,6 +6,7 @@
  * uses this file as the single source of truth.
  */
 import type { LocalMeshEntry, LocalMeshNodeEntry, RepoMeshPolicy, RepoMeshNodePolicy, RepoMeshNodeCapabilities, RepoMeshCoordinatorConfig, RepoMeshHostMetadata, RepoMeshDaemonRole } from '../repo-mesh-types.js';
+import type { MagiKindPanelMap, MagiSlot, DifficultyBrainMap } from '@adhdev/mesh-shared';
 /**
  * Normalize a Git remote URL into a stable identity string.
  * e.g. "git@github.com:user/repo.git" → "github.com/user/repo"
@@ -101,16 +102,80 @@ export interface AddNodeOptions {
     repoRoot?: string;
     daemonId?: string;
     machineId?: string;
+    capabilities?: string[];
     userOverrides?: Partial<RepoMeshNodeCapabilities>;
     policy?: RepoMeshNodePolicy;
     isLocalWorktree?: boolean;
     worktreeBranch?: string;
     clonedFromNodeId?: string;
+    worktreeBootstrap?: LocalMeshNodeEntry['worktreeBootstrap'];
     role?: RepoMeshDaemonRole;
+    /** Owning daemon's machine nickname. Defaults to this daemon's local
+     *  config.machineNickname when omitted — a node is always added by (and on)
+     *  the daemon that owns its workspace (self/base node or a local worktree
+     *  clone), so the local config is the correct source. */
+    machineNickname?: string;
 }
 export declare function addNode(meshId: string, opts: AddNodeOptions): LocalMeshNodeEntry | undefined;
 export declare function removeNode(meshId: string, nodeId: string): boolean;
 export declare function updateNode(meshId: string, nodeId: string, opts: {
     userOverrides?: Partial<RepoMeshNodeCapabilities>;
     policy?: RepoMeshNodePolicy;
+    /** Operator-defined custom capability tags used by mesh queue matching.
+     *  Passing an array replaces the node's custom tags (empty/whitespace
+     *  entries dropped, deduped); an empty result clears them. Omit to leave
+     *  the existing tags untouched. */
+    capabilities?: string[];
+    worktreeBootstrap?: LocalMeshNodeEntry['worktreeBootstrap'];
+    /** Per-node instruction surfaced in the coordinator prompt. Pass an
+     *  empty string or undefined to clear it. */
+    systemPrompt?: string;
+    /** Live self-reported platform/arch from the owning daemon's git_status
+     *  envelope. Persisted distinctly from userOverrides (auto-detected, not
+     *  operator intent) so capability-tag os=/arch= self-heals across loads. */
+    reportedPlatform?: string;
+    reportedArch?: string;
+    /** Owning daemon's self-reported machine nickname, carried on the
+     *  git_status envelope. Persisted so the friendly label survives across
+     *  coordinator restarts (mirrors reportedPlatform/reportedArch). */
+    reportedMachineNickname?: string;
+    /** Owning daemon's self-reported provider CLI/ACP versions + build version,
+     *  carried on the git_status envelope. Persisted distinctly from userOverrides
+     *  (auto-detected observability, not operator intent), mirroring the
+     *  reportedPlatform/reportedArch self-heal so the value survives restarts and
+     *  is overwritten by the next report. */
+    reportedProviderVersions?: Record<string, string>;
+    reportedDaemonBuildVersion?: string;
 }): LocalMeshNodeEntry | undefined;
+/**
+ * Validate + normalize a kind-panel's slots (the SOLE MAGI slot normalizer): provider
+ * required per slot, trims strings, drops empties, clamps replica counts, and carries
+ * an optional per-slot `model`. Throws on structurally invalid input (empty list / no
+ * provider) so the write returns a clear error. Returns the normalized slot array.
+ */
+export declare function normalizeMagiSlots(slots: unknown): MagiSlot[];
+/** All configured kind-panels (machine-local), keyed by task_kind. Empty when none. */
+export declare function listMagiKindPanels(): MagiKindPanelMap;
+/** The slot list for one task_kind, or undefined when the kind is not configured. */
+export declare function getMagiKindPanel(kind: string): MagiSlot[] | undefined;
+/**
+ * Upsert the slot list for one task_kind. Unlike named panels this ALWAYS overwrites
+ * (a kind has exactly one binding) — the editor pushes the full desired slot set.
+ * Returns the normalized, persisted slots.
+ */
+export declare function setMagiKindPanel(kind: string, slots: unknown): MagiSlot[];
+/** Remove the binding for one task_kind. Returns true when a binding was removed. */
+export declare function removeMagiKindPanel(kind: string): boolean;
+/**
+ * The difficulty→brain presets, machine-local. When nothing is configured yet,
+ * returns the sensible DEFAULT_DIFFICULTY_BRAINS so the coordinator always has a
+ * usable mapping (the operator can override via setDifficultyBrains). Returns a
+ * normalized copy — never the stored reference.
+ */
+export declare function getDifficultyBrains(): DifficultyBrainMap;
+/**
+ * Replace the difficulty→brain presets wholesale (the editor pushes the full map).
+ * Passing an empty/normalized-empty map clears the override, so getDifficultyBrains
+ * falls back to the defaults again. Returns the normalized, persisted map.
+ */
+export declare function setDifficultyBrains(map: unknown): DifficultyBrainMap;

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

@@ -0,0 +1,199 @@
+/**
+ * Repo-shared declarative mesh config — `.adhdev/mesh.json`
+ *
+ * A repo-committed, machine-independent file carrying ONLY the repo-shared
+ * coordinator-prompt config and operating notes:
+ *
+ *   - coordinator       — systemPromptOverride (local wins, else repo) and
+ *                         systemPromptAppend (repo append + local append BOTH
+ *                         stack, repo first).
+ *   - operatingNotes    — repo-declared baseline notes merged with the runtime
+ *                         ledger notes; on duplicate text the ledger note wins.
+ *   - limits            — advisory-only (`maxNoteChars`, `maxNotes`,
+ *                         `coordinator.maxPromptChars`); recorded, never enforced in v1.
+ *
+ * POLICY IS NOT HERE. RepoMeshPolicy (the 15 scheduling/approval fields) is
+ * MACHINE-LOCAL only — it lives in meshes.json and is never sourced from, merged
+ * with, or overlaid by a repo file. There is no `policy` zone and no
+ * `policy.scheduling` overlay in mesh.json; the scheduler reads the stored
+ * machine-local policy directly. The repo file shapes the coordinator prompt and
+ * operating notes, nothing else.
+ *
+ * The coordinator/operatingNotes merge is **in-memory only**: the on-disk
+ * machine-local `meshes.json` is never mutated by this module.
+ *
+ * FILE SEPARATION: refine / worktree-bootstrap / change-impact configs live in
+ * their OWN `.adhdev/*` files with their own loaders — they are NOT inlined into
+ * mesh.json. `loadRepoSettings` (config/repo-settings.ts) assembles all of them
+ * into one object for consumers.
+ *
+ * SECURITY: declarative only. JSON/YAML is parsed; arbitrary JS (.js) is NOT
+ * supported, so loading a config can never execute code.
+ */
+import type { RepoMeshCoordinatorConfig, LocalMeshEntry } from '../repo-mesh-types.js';
+import type { CoordinatorOperatingNote } from '../mesh/coordinator-prompt.js';
+export interface RepoMeshDeclarativeCoordinatorConfig {
+    /** Full mesh-level system prompt override. Same semantics as
+     *  RepoMeshCoordinatorConfig.systemPromptOverride; LOCAL-WINS. */
+    systemPromptOverride?: string;
+    /** Mesh-level append stacked after the base prompt. Both the repo append
+     *  and the machine-local append apply; the repo append comes first. */
+    systemPromptAppend?: string;
+    /** Advisory only in v1 — recorded but never enforced. */
+    maxPromptChars?: number;
+}
+export interface RepoMeshDeclarativeLimits {
+    /** Advisory only in v1 — recorded but never enforced. */
+    maxNoteChars?: number;
+    /** Advisory only in v1 — recorded but never enforced. */
+    maxNotes?: number;
+}
+/**
+ * Parsed + normalized `.adhdev/mesh.json` shape. Every field is optional except
+ * version so a repo can declare only the zone(s) it cares about. Policy is NOT a
+ * zone here — it is machine-local (meshes.json) only.
+ */
+export interface RepoMeshDeclarativeConfig {
+    version: 1;
+    coordinator?: RepoMeshDeclarativeCoordinatorConfig;
+    operatingNotes?: CoordinatorOperatingNote[];
+    limits?: RepoMeshDeclarativeLimits;
+}
+export interface RepoMeshJsonConfigLoadResult {
+    config?: RepoMeshDeclarativeConfig;
+    /** Relative location matched, or 'unavailable'/'invalid' marker. */
+    source: string;
+    sourceType: 'repo_file' | 'unavailable' | 'invalid';
+    /** Absolute path of the matched file, when one was read. */
+    path?: string;
+    error?: string;
+}
+export declare const MESH_JSON_CONFIG_LOCATIONS: string[];
+export declare const MESH_JSON_CONFIG_SCHEMA: {
+    readonly $schema: "https://json-schema.org/draft/2020-12/schema";
+    readonly title: "ADHDev Repo Mesh Declarative Config";
+    readonly type: "object";
+    readonly additionalProperties: false;
+    readonly required: readonly ["version"];
+    readonly properties: {
+        readonly version: {
+            readonly const: 1;
+        };
+        readonly coordinator: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly systemPromptOverride: {
+                    readonly type: "string";
+                };
+                readonly systemPromptAppend: {
+                    readonly type: "string";
+                };
+                readonly maxPromptChars: {
+                    readonly type: "number";
+                    readonly minimum: 1;
+                };
+            };
+        };
+        readonly operatingNotes: {
+            readonly type: "array";
+            readonly maxItems: 200;
+            readonly items: {
+                readonly type: "object";
+                readonly additionalProperties: false;
+                readonly required: readonly ["text"];
+                readonly properties: {
+                    readonly text: {
+                        readonly type: "string";
+                        readonly minLength: 1;
+                    };
+                    readonly category: {
+                        readonly enum: readonly ["provider_quirk", "pattern_to_avoid", "recovery_lesson"];
+                    };
+                    readonly createdAt: {
+                        readonly type: "string";
+                    };
+                    readonly sourceCoordinator: {
+                        readonly type: "string";
+                    };
+                };
+            };
+        };
+        readonly limits: {
+            readonly type: "object";
+            readonly additionalProperties: false;
+            readonly properties: {
+                readonly maxNoteChars: {
+                    readonly type: "number";
+                    readonly minimum: 1;
+                };
+                readonly maxNotes: {
+                    readonly type: "number";
+                    readonly minimum: 1;
+                };
+            };
+        };
+    };
+};
+/**
+ * Validate + normalize a parsed `.adhdev/mesh.json` object into a typed
+ * RepoMeshDeclarativeConfig. Returns the config plus any non-fatal warnings;
+ * `valid` is false only when the document is structurally unusable (not an
+ * object / wrong version). Unknown top-level keys are tolerated (dropped) so a
+ * newer repo file authored against a future schema still loads its known zones.
+ */
+export declare function normalizeRepoMeshDeclarativeConfig(parsed: unknown): {
+    valid: boolean;
+    config?: RepoMeshDeclarativeConfig;
+    errors: string[];
+};
+/**
+ * Load the repo-shared declarative mesh config for a coordinator workspace.
+ *
+ * Resolution: the coordinator node workspace is checked first; if it carries no
+ * `.adhdev/mesh.json`, the calling process cwd is tried as a fallback (per the
+ * design: "workspace path = coordinator node workspace's .adhdev/mesh.json,
+ * else calling cwd"). The first existing file across both bases (and the
+ * json/yaml/yml variants) wins.
+ *
+ * Read/parse errors never throw — they resolve to a sourceType:'invalid'
+ * result so a broken repo file degrades to "no repo base" instead of blocking
+ * coordinator launch.
+ */
+export declare function loadRepoMeshJsonConfig(workspace?: string): RepoMeshJsonConfigLoadResult;
+/**
+ * Effective coordinator config. systemPromptOverride: local wins, else repo.
+ * systemPromptAppend: repo append + local append BOTH stack (repo first). Other
+ * coordinator fields (providerType, preferredNodeId, …) are carried from the
+ * machine-local config unchanged.
+ */
+export declare function mergeEffectiveCoordinatorConfig(repoCoord: RepoMeshDeclarativeCoordinatorConfig | undefined, localCoord: RepoMeshCoordinatorConfig | undefined): RepoMeshCoordinatorConfig;
+/**
+ * Effective operating notes = repo-declared baseline ⊕ runtime ledger notes.
+ * Dedup by trimmed text with the LEDGER note winning (repo duplicates dropped),
+ * so a runtime note's freshest wording/category survives. Order: repo baseline
+ * first, then ledger notes. Returns undefined when nothing usable remains so the
+ * prompt's "## Operating Notes" section is omitted exactly as before.
+ */
+export declare function mergeEffectiveOperatingNotes(repoNotes: CoordinatorOperatingNote[] | undefined, ledgerNotes: CoordinatorOperatingNote[] | undefined): CoordinatorOperatingNote[] | undefined;
+/**
+ * Produce an in-memory effective mesh by layering the repo declarative config
+ * UNDER the machine-local mesh entry — coordinator zone ONLY. Policy is
+ * machine-local and is left exactly as the stored mesh carries it (never sourced
+ * from the repo file). Returns a new object; the input mesh and on-disk
+ * meshes.json are never mutated. operatingNotes are merged separately at launch
+ * (they ride the prompt context, not the mesh).
+ */
+export declare function applyRepoMeshConfig<T extends Pick<LocalMeshEntry, 'coordinator'>>(mesh: T, repoConfig: RepoMeshDeclarativeConfig | null | undefined): T;
+/**
+ * Build a `.adhdev/mesh.json` DRAFT from a machine-local mesh entry. This is a
+ * scaffold for the operator to review and commit — NOT an automatic migration.
+ * It captures the coordinator prompt override/append so a repo can adopt the
+ * current machine's prompt customization as the shared base. Policy is NOT
+ * exported — it is machine-local only and has no place in mesh.json. Operating
+ * notes are intentionally NOT exported either: those are runtime ledger lessons,
+ * and a repo should declare baseline notes deliberately.
+ */
+export declare function buildMeshJsonConfigScaffold(mesh: Pick<LocalMeshEntry, 'coordinator'>): RepoMeshDeclarativeConfig;
+/** Serialize a scaffold to the canonical 2-space JSON draft text. */
+export declare function serializeMeshJsonConfigScaffold(config: RepoMeshDeclarativeConfig): string;