@adhdev/daemon-core 0.9.82-rc.37 → 0.9.82-rc.371

package/dist/commands/router.d.ts

@@ -14,6 +14,448 @@ 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 { awaitWithWarmupDeadline } from '../mesh/mesh-warmup-deadline.js';
+export declare function readProviderPriorityFromPolicy(policy: unknown): string[];
+/**
+ * Normalize a providerRoles array (RepoMeshNodePolicy.providerRoles) from raw
+ * tool args. Each entry binds a providerType to an optional `maxParallel` cap.
+ * Entries without a usable providerType are dropped; the last entry wins on
+ * duplicate providerType. Returns [] when no valid entries — callers then omit
+ * the field entirely (full backward compat). Routing is governed by required_tags;
+ * any legacy `role` field on the input is ignored.
+ */
+export declare function normalizeProviderRoles(value: unknown): Array<{
+    providerType: string;
+    maxParallel?: number;
+}>;
+export declare function readObjectRecord(value: unknown): Record<string, any>;
+export declare function readStringValue(...values: unknown[]): string | undefined;
+export declare function readBooleanValue(...values: unknown[]): boolean | undefined;
+export declare function summarizeRepoMeshStatusDebug(status: any): Record<string, unknown>;
+export declare function logRepoMeshStatusDebug(event: string, fields: Record<string, unknown>): void;
+export declare function buildMeshNodeDisplayLabel(node: Record<string, unknown>, nodeId: string, providerPriority: string[]): string;
+export declare function readMeshNodeMachineId(node: Record<string, unknown>): string | undefined;
+export declare function readMeshNodeHostname(node: Record<string, unknown>): string | undefined;
+export declare function buildMeshNodeMachineIdentity(node: Record<string, unknown>, opts: {
+    localMachineId?: string;
+    localDaemonId?: string;
+    coordinatorHostname?: string;
+    isSelfNode?: boolean;
+}): Record<string, unknown>;
+export declare function buildInlineMeshTransitGitStatus(node: any): Record<string, unknown> | undefined;
+export declare function buildLivePeerGitConnection(connection: Record<string, unknown>, timestamp?: string): Record<string, unknown>;
+export declare function recordInlineMeshDirectGitTruth(node: any, git: Record<string, unknown>, source: 'selected_coordinator_local_git' | 'selected_coordinator_mesh_p2p_git'): {
+    reporterPlatform: string | null;
+    reporterArch: string | null;
+};
+/**
+ * Persist the live self-reported platform/arch onto the local meshes.json node
+ * record so capability-tag os=/arch= self-heals across coordinator restarts.
+ *
+ * The in-memory stamp done by recordInlineMeshDirectGitTruth lives on the
+ * mesh_status assembly object and is discarded after the response; only a
+ * `local_config` mesh has a backing meshes.json node to write through to. Inline
+ * cache/bootstrap meshes have no local node to update, so we no-op for them.
+ * Fire-and-forget (same pattern as the worktreeBootstrap writer) — a persistence
+ * failure must never block the status response.
+ */
+export declare function persistNodeReporterPlatform(meshSource: 'inline_cache' | 'inline_bootstrap' | 'local_config', mesh: any, nodeId: string | undefined, reporter: {
+    reporterPlatform: string | null;
+    reporterArch: string | null;
+}): void;
+export declare function deriveMeshNodeHealthFromGit(git: Record<string, unknown> | null | undefined): 'online' | 'dirty' | 'degraded';
+export declare function applyInlineMeshBranchConvergence(mesh: any, node: any, status: Record<string, unknown>): void;
+export declare function summarizeInlineMeshBranchConvergence(nodes: Array<Record<string, unknown>>): Record<string, unknown>;
+/**
+ * Resolve the owning-node attribution for a mesh node record so a coordinator can
+ * stamp the TRUE owner onto a synthetic session entry instead of letting the
+ * dashboard fall back to the coordinator's own daemonId. Returns whichever of the
+ * owning node's `daemonId` / display machine name could be read from the node's
+ * (possibly multi-serialization-path) shape; both may be undefined for a node that
+ * never carried machine identity.
+ */
+export declare function resolveMeshNodeAttribution(node: unknown): {
+    daemonId?: string;
+    machineName?: string;
+};
+export declare function readCachedInlineMeshActiveSessionDetails(node: any): Array<Record<string, unknown>>;
+/**
+ * Transient per-node marker the mesh_status render loop stamps onto a node
+ * `status` at the two sites that obtain git truth from a FRESH probe this call
+ * (a successful local `getGitRepoStatus`, or a successful P2P `git_status`
+ * round-trip). finalizeMeshNodeStatus consumes and deletes it. Held/standing
+ * truth (node.lastGit / cachedStatus / inline transit) is deliberately NOT
+ * stamped — its absence is exactly how the freshness marker tells "live" apart
+ * from "cached". Internal only; never serialized in the response.
+ */
+export declare const MESH_NODE_LIVE_TRUTH_MARKER = "__liveTruthProbed";
+/**
+ * Build the additive per-node `dataFreshness` marker. This NEVER mutates any
+ * existing field — it only adds an explicit, machine-readable answer to the
+ * question the legacy fields blurred: is this node's data live (just probed),
+ * cached (held truth, maybe old), or absent because the peer was unreachable?
+ *
+ * The crucial separation: an UNREACHABLE peer (P2P probe failed / not connected)
+ * is no longer indistinguishable from an idle/EMPTY node. Both used to render as
+ * `health:'unknown'` with no sessions; now `dataFreshness.dataSource` and
+ * `reachable` tell them apart so a coordinator never reads a dead peer as "online
+ * but doing nothing".
+ */
+export declare function buildMeshNodeDataFreshness(args: {
+    status: Record<string, unknown>;
+    node?: any;
+    isSelfNode: boolean;
+    daemonId?: string;
+    /** True when this node was stamped with a fresh live git probe this call. */
+    liveTruthProbed: boolean;
+    /** True when direct-peer-truth accounting classified this node unavailable. */
+    directTruthUnavailable?: boolean;
+    now?: () => number;
+}): Record<string, unknown>;
+export declare function finalizeMeshNodeStatus(args: {
+    status: Record<string, unknown>;
+    node: any;
+    daemonId?: string;
+    isSelfNode: boolean;
+    /** True when direct-peer-truth accounting classified this node unavailable. */
+    directTruthUnavailable?: boolean;
+}): void;
+export declare const MESH_DIRECT_PROBE_TIMEOUT_MS: number;
+export declare const MESH_DIRECT_PROBE_RETRY_TIMEOUT_MS: number;
+export declare const MESH_DIRECT_PROBE_CONNECT_TIMEOUT_MS: number;
+/**
+ * De-duplicates and rate-limits per-peer git_status probes so a single mesh
+ * refresh — or a burst of refreshes from the dashboard auto-retry loop — cannot
+ * launch a storm of concurrent/back-to-back `refreshUpstream:true` commands to
+ * the same slow peer.
+ *
+ * Two gates, both keyed by `daemonId::workspace`:
+ *  - In-flight dedup: a second probe for a key with a probe already running
+ *    shares (awaits) the in-flight promise instead of issuing a second command.
+ *  - Recently-probed reuse: a successful probe younger than `reuseMs` is reused
+ *    verbatim instead of issuing a fresh probe. Failures are NOT cached (so a
+ *    transient timeout doesn't pin a peer to "no truth" for the whole window).
+ *
+ * Lives on the router instance so the gate spans separate mesh_status calls,
+ * which is exactly where the refresh storm happens.
+ */
+export declare class MeshGitProbeCache {
+    private readonly reuseMs;
+    private readonly now;
+    private inflight;
+    private recent;
+    constructor(reuseMs: number, now?: () => number);
+    private key;
+    /**
+     * Run `probe` for this peer, but reuse a fresh recent result or an in-flight
+     * probe for the same key when one is available. `probe` is only invoked when
+     * neither gate is satisfied.
+     */
+    probe(daemonId: string, workspace: string, probe: () => Promise<Record<string, unknown> | null>): Promise<Record<string, unknown> | null>;
+}
+export { awaitWithWarmupDeadline };
+/**
+ * Probe a remote peer's git_status with a bounded retry budget, but only while
+ * the peer is reported `connected`. A single slow (often TURN-relayed) peer can
+ * exceed one probe window; retrying — with the connection re-checked before each
+ * attempt so we abandon a peer that dropped — recovers it without blocking the
+ * mesh forever. Shared by the bootstrap hydrate path and the per-node render
+ * path so both treat a connected-but-slow peer identically.
+ *
+ * Returns the git status on success, or null if every attempt failed/timed out
+ * (caller decides how to classify). `getConnection` is consulted before each
+ * attempt; a non-`connected` state short-circuits the retry loop (the very first
+ * attempt always runs so a missing connection getter still gets one try).
+ */
+export declare function probeRemoteMeshGitStatusWithRetry(args: {
+    dispatchMeshCommand?: (daemonId: string, cmd: string, args: Record<string, unknown>) => Promise<unknown>;
+    daemonId: string;
+    workspace: string;
+    timeoutMs: number;
+    /** Per-attempt timeout for retries (attempts > 0); defaults to timeoutMs. */
+    retryTimeoutMs?: number;
+    /** Cold-open warmup budget per attempt; defaults to MESH_DIRECT_PROBE_CONNECT_TIMEOUT_MS. */
+    connectTimeoutMs?: number;
+    getConnection?: (daemonId: string) => Record<string, unknown> | null;
+    onConnection?: (connection: Record<string, unknown>) => void;
+}): Promise<Record<string, unknown> | null>;
+export declare function hydrateInlineMeshDirectTruth(args: {
+    mesh: any;
+    meshSource: 'inline_cache' | 'inline_bootstrap' | 'local_config';
+    dispatchMeshCommand?: (daemonId: string, cmd: string, args: Record<string, unknown>) => Promise<unknown>;
+    getMeshPeerConnectionStatus?: (daemonId: string) => Record<string, unknown> | null;
+    statusInstanceId?: string;
+    localMachineId?: string;
+    probeRemotePeers: boolean;
+    probeCache?: MeshGitProbeCache;
+}): Promise<{
+    directEvidenceCount: number;
+    localConfirmedCount: number;
+    peerAttemptedCount: number;
+    peerConfirmedCount: number;
+    standingEvidenceCount: number;
+    unavailableNodeIds: string[];
+    deadNodeIds: string[];
+}>;
+export declare function summarizeMeshSessionRecord(record: any): Record<string, unknown>;
+export declare function readLiveMeshNodeWorkspace(args: {
+    meshId: string;
+    nodeId: string;
+    liveSessionRecords: any[];
+    allowCoordinatorSession?: boolean;
+}): string;
+export declare function collectLiveMeshSessionRecords(args: {
+    meshId: string;
+    node: any;
+    nodeId: string;
+    liveSessionRecords: any[];
+    allowCoordinatorSession?: boolean;
+}): any[];
+export declare function buildHistoricalMeshSessions(args: {
+    meshId: string;
+    nodes: any[];
+    liveSessionRecords: any[];
+}): {
+    count: number;
+    sessions: Record<string, unknown>[];
+    instruction: string;
+} | undefined;
+export declare function applyCachedInlineMeshNodeStatus(status: Record<string, unknown>, node: any, options?: {
+    skipGit?: boolean;
+    skipError?: boolean;
+    skipHealth?: boolean;
+}): boolean;
+export declare function resolveProviderTypeFromPriority(args: {
+    nodeId: string;
+    providerPriority: string[];
+    providerLoader: ProviderLoader;
+    onStatusChange?: () => void;
+}): Promise<{
+    providerType?: string;
+    error?: string;
+}>;
+export type MeshCoordinatorConfigFormat = 'claude_mcp_json' | 'hermes_config_yaml';
+type MeshRefineStageStatus = 'passed' | 'failed' | 'skipped';
+type MeshRefinePatchEquivalenceSummary = {
+    status: MeshRefineStageStatus;
+    equivalent: boolean;
+    baseHead: string;
+    branchHead: string;
+    mergeBase?: string;
+    mergedTree?: string;
+    expectedPatchId?: string;
+    actualPatchId?: string;
+    durationMs: number;
+    error?: string;
+    stdout?: string;
+    stderr?: string;
+    actionableHint?: MeshRefineSubmoduleConflictHint;
+    /**
+     * Set when a `merge-tree` submodule conflict was reclassified as a trivial
+     * gitlink fast-forward and the gate passed via a synthesized merge tree.
+     */
+    gitlinkTrivialFastForward?: {
+        resolved: boolean;
+        gitlinks: Array<{
+            path: string;
+            baseCommit?: string;
+            branchCommit?: string;
+            fastForward: boolean;
+        }>;
+        reason?: string;
+    };
+};
+type MeshRefineEffectiveDiffSummary = {
+    status: MeshRefineStageStatus;
+    /** True when there is at least one root-tree change between base and branch (incl. gitlink bumps). */
+    hasEffectiveDiff: boolean;
+    baseHead: string;
+    branchHead: string;
+    /** Root-level paths that differ between base and branch (capped). */
+    changedPaths?: string[];
+    /** Submodule paths with uncommitted/divergent commits but NO committed gitlink bump in the root tree. */
+    submoduleHints?: Array<{
+        path: string;
+        reason: string;
+    }>;
+    durationMs: number;
+    error?: string;
+    stdout?: string;
+    stderr?: string;
+};
+type MeshRefineSubmoduleConflictHint = {
+    kind: 'submodule_conflict';
+    message: string;
+    conflicts: Array<{
+        path: string;
+        baseCommit?: string;
+        branchCommit?: string;
+    }>;
+    nextSteps: string[];
+};
+type MeshRefineAsyncJobStatus = 'accepted' | 'completed' | 'failed';
+export type MeshRefineJobHandle = {
+    success: true;
+    async: true;
+    status: MeshRefineAsyncJobStatus;
+    jobId: string;
+    interactionId: string;
+    meshId: string;
+    nodeId: string;
+    targetNodeId: string;
+    targetDaemonId?: string;
+    workspace?: string;
+    startedAt: string;
+    completedAt?: string;
+    duplicate?: boolean;
+    retryOfJobId?: string;
+    /**
+     * The coordinator daemon ID that initiated this refine job.
+     * When set, events for this job are scoped to that coordinator's
+     * pending-events queue instead of the shared broadcast queue.
+     */
+    targetCoordinatorDaemonId?: string;
+    eventDelivery: {
+        pendingEvents: true;
+        ledger: true;
+    };
+    evidence: {
+        pendingEventsCommand: 'get_pending_mesh_events';
+        ledgerCommand: 'get_mesh_ledger_slice';
+        taskHistoryKind: 'task_dispatched' | 'task_completed' | 'task_failed';
+    };
+};
+/**
+ * A spawn-resolution failure is when the executable itself could not be found by
+ * the OS spawn boundary — `spawn <cmd> ENOENT` — as opposed to the command
+ * running and exiting non-zero. On win32 this is the .cmd-shim case: libuv's
+ * spawn search appends only .com/.exe, so a bare `npm`/`npx`/`tsc` (which are
+ * .cmd shims) ENOENTs even though it is installed. It carries no stderr, so it
+ * must be detected by error.code/syscall, not by string-matching output.
+ */
+export declare function isSpawnResolutionError(error: any): boolean;
+export declare function describeSpawnError(error: any, command: string, spawnResolutionFailed: boolean): string;
+export declare function runMeshRefinePatchEquivalenceGate(repoRoot: string, baseHead: string, branchHead: string): Promise<MeshRefinePatchEquivalenceSummary>;
+export type MeshWorktreePatchContainmentSummary = {
+    /** True only when merging worktreeHead into ref introduces no new patch. */
+    contained: boolean;
+    ref: string;
+    worktreeHead: string;
+    mergeBase?: string;
+    mergedTree?: string;
+    /** patch-id of (ref -> synthesized merge tree); empty string when nothing new is added. */
+    residualPatchId?: string;
+    durationMs: number;
+    /** Set when the check could not run (treated conservatively as NOT contained). */
+    error?: string;
+};
+/**
+ * Patch-equivalence containment check for the worktree force-cleanup convergence
+ * guard. Answers a narrower question than {@link runMeshRefinePatchEquivalenceGate}:
+ * "are the worktree branch's changes ALREADY present in `ref` (e.g. origin/main),
+ * even though the worktree HEAD's commit SHA is not an ancestor of ref?"
+ *
+ * This is the cherry-pick / squash / rebase case: the same content landed on the
+ * default ref under a different commit SHA, so `merge-base --is-ancestor` (the
+ * primary cleanup guard) reports the worktree as un-converged and refuses to
+ * remove it. Refinery already accepts patch-equivalent landings via merge-tree +
+ * patch-id; this brings the same notion of "convergence" to the cleanup guard.
+ *
+ * Mechanism: synthesize the merge of `worktreeHead` into `ref` (reusing the same
+ * trivial-gitlink-fast-forward handling as the refine gate) and compute the
+ * patch-id of (ref -> mergedTree). If that residual diff is EMPTY, merging the
+ * worktree adds nothing new on top of ref — its changes are already present there
+ * and the worktree is safe to remove. A non-empty residual means the worktree
+ * still carries content not in ref, so it is NOT contained and must stay blocked.
+ *
+ * Conservative by construction: any merge-tree / patch-id failure, a genuine
+ * (non-trivial) submodule conflict, or any thrown error yields `contained: false`
+ * so an exception can never widen the cleanup allow-list.
+ */
+export declare function checkWorktreeChangesPatchEquivalentInRef(repoRoot: string, ref: string, worktreeHead: string): Promise<MeshWorktreePatchContainmentSummary>;
+/**
+ * No-op guard: detect a "silent no-op" merge before the Refinery merge runs.
+ *
+ * A silent no-op occurs when the refine target branch's ROOT tree is byte-identical
+ * to the merge base (origin/main). This is the trap where a submodule (e.g. oss) has
+ * real commits but the root branch never committed the gitlink (oss-pointer) bump, so
+ * the root diff Refinery would merge is empty. Merging that produces a merge commit with
+ * no content change — reported as "success" while the actual work never reaches main.
+ *
+ * A committed gitlink bump (the legitimate oss-pointer bump) DOES show up in the root
+ * tree diff (as a 160000-mode entry), so this guard does NOT block legitimate refines —
+ * it only fires when the root tree diff vs base is COMPLETELY empty.
+ *
+ * Runs after the patch-equivalence gate; the "already merged via other path" case
+ * (branch has real changes already present in base) is handled upstream and never
+ * reaches here, so an empty root diff at this point is genuinely a no-op.
+ */
+export declare function runMeshRefineEffectiveDiffGate(repoRoot: string, baseHead: string, branchHead: string): Promise<MeshRefineEffectiveDiffSummary>;
+/**
+ * Result of evaluating whether a `git merge-tree --write-tree` submodule
+ * conflict is in fact a trivial gitlink fast-forward that should pass the
+ * patch-equivalence gate.
+ *
+ * `git merge-tree` (and `git merge` with the default recursive strategy)
+ * refuses to 3-way merge gitlinks unless the case is "trivial" — and it
+ * treats *any* gitlink that differs across merge-base/base/branch as
+ * non-trivial, even when the branch-side commit is a strict descendant of the
+ * base-side commit (i.e. a real fast-forward). Refinery only ever wants to
+ * accept the branch's recorded gitlink, so a fast-forwardable bump is safe to
+ * resolve to the branch side without any conflict.
+ */
+type GitlinkTrivialFastForwardEvaluation = {
+    /** True only when the merge-tree conflict is *fully* explained by trivial-ff gitlinks. */
+    trivial: boolean;
+    /** Why the evaluation declined to treat the conflict as trivial (set when trivial=false). */
+    reason?: string;
+    /** Per-path detail for the changed gitlinks that were inspected. */
+    gitlinks: Array<{
+        path: string;
+        baseCommit?: string;
+        branchCommit?: string;
+        fastForward: boolean;
+    }>;
+};
+/**
+ * Return the changed gitlink paths between base and branch whose advance is a
+ * strict fast-forward (the base-side commit is an ancestor of the branch-side
+ * commit inside that submodule's repo). These are the paths whose patch-id hunk
+ * may legitimately differ when base has advanced the same submodule, so they
+ * are safe to exclude from the patch-equivalence comparison. A non-ff (genuinely
+ * diverged) gitlink is deliberately excluded from this set so it still fails the
+ * gate.
+ */
+export declare function collectFastForwardGitlinkPaths(repoRoot: string, baseHead: string, branchHead: string): string[];
+/**
+ * Decide whether a merge-tree submodule conflict between base and branch is a
+ * trivial gitlink fast-forward (and nothing else).
+ *
+ * The conflict is treated as trivial ONLY when:
+ *   1. at least one changed gitlink exists,
+ *   2. every changed gitlink fast-forwards (base-commit is an ancestor of the
+ *      branch-commit inside that submodule's repo), and
+ *   3. the *only* paths that changed on both sides of the merge (i.e. the paths
+ *      that could possibly produce a 3-way conflict — the intersection of
+ *      mergeBase→base and mergeBase→branch changes) are gitlinks. Any
+ *      overlapping non-gitlink path means a genuine content conflict could be
+ *      hiding behind the submodule failure, so we keep the block.
+ *
+ * If any of these fail, the conflict is left as a genuine block. This never
+ * passes a regular-file conflict or a diverged (non-ff) gitlink.
+ */
+export declare function evaluateGitlinkTrivialFastForward(repoRoot: string, baseHead: string, branchHead: string): GitlinkTrivialFastForwardEvaluation;
+export declare function buildMeshRefineValidationPlan(mesh: any, workspace: string): Record<string, unknown>;
+export declare function getMcpServersKey(format: MeshCoordinatorConfigFormat): 'mcpServers' | 'mcp_servers';
+export declare function parseMeshCoordinatorMcpConfig(text: string, format: MeshCoordinatorConfigFormat): Record<string, any>;
+export declare function serializeMeshCoordinatorMcpConfig(config: Record<string, any>, format: MeshCoordinatorConfigFormat): string;
+export declare function loadHermesCoordinatorBaseConfig(targetConfigPath: string): {
+    config: Record<string, any>;
+    sourceHome: string;
+    sourceConfigPath: string;
+};
+export declare function stripHermesCoordinatorTempModelProviderOverrides(config: Record<string, any>): Record<string, any>;
+export declare function copyHermesCoordinatorCredentialFiles(sourceHome: string, targetHome: string): void;
 export interface SessionHostControlPlane {
     getDiagnostics(payload?: {
         includeSessions?: boolean;
@@ -55,12 +497,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,26 +525,138 @@ 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;
     /** 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;
+    /** 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. */
+    private aggregateMeshStatusCache;
+    /** 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;
+    /** In-memory async Refinery jobs keyed by meshId:nodeId to reject/return duplicate in-flight requests. */
+    private runningRefineJobs;
+    /** Terminal async Refinery jobs preserve a clear answer after the worktree node has been removed. */
+    private terminalRefineJobs;
+    /** In-memory async batch Refinery jobs keyed by meshId (one batch convergence per mesh at a time). */
+    private runningRefineBatchJobs;
+    /** Terminal async batch Refinery jobs preserve the last batch outcome for late readers. */
+    private terminalRefineBatchJobs;
     constructor(deps: CommandRouterDeps);
+    private cloneJsonValue;
+    private hydrateCachedAggregateMeshStatusFromInline;
+    private getCachedAggregateMeshStatus;
+    private rememberAggregateMeshStatus;
+    getCachedInlineMeshNodes(): any[];
+    /**
+     * Resolve the REMOTE worker daemonId that owns a given session, when the session
+     * belongs to a mesh node hosted on a DIFFERENT daemon than this coordinator.
+     *
+     * The coordinator does not host remote-worker session instances in its own
+     * instanceManager/sessionRegistry — only their cached mesh-node metadata. A
+     * dashboard-issued session-scoped command (invoke_provider_script / resolve_action /
+     * set_mode / …) lands on the coordinator with a targetSessionId the coordinator can't
+     * find locally, and without forwarding it dies as "Live session not found". send_chat
+     * happens to survive (its target resolves to the worker by another route), but the
+     * controlbar commands do not — so the controlbar buttons appear to do nothing.
+     *
+     * Mirror the existing node-level remote-forward pattern (fast_forward_mesh_node etc.):
+     * scan the candidate mesh nodes for the one hosting the targetSessionId, and return its
+     * daemonId when that daemonId is a remote daemon (i.e. not this coordinator's own
+     * statusInstanceId). Returns undefined for a locally-hosted session (no forward — execute
+     * locally as before) or when ownership can't be resolved.
+     *
+     * The candidate set spans BOTH the cached inline-mesh nodes and the live aggregate
+     * mesh-status snapshots. The inline cache reliably carries only each node's single primary
+     * session (cachedStatus.activeSession), so a worker hosting more than one session exposes its
+     * non-primary sessions only on the aggregate snapshot nodes (status.activeSessions /
+     * activeSessionDetails, built from live session records). collectMeshNodeHostedSessionIds does
+     * the wider plural-shape scan so a controlbar/modal command targeting a non-primary remote
+     * session still resolves its owner — the singular readCachedInlineMeshActiveSessions semantics
+     * other consumers depend on stay untouched.
+     */
+    resolveRemoteMeshSessionOwnerDaemonId(sessionId: string): string | undefined;
+    /**
+     * Candidate nodes for remote-session owner resolution: the cached inline-mesh nodes (which
+     * carry each node's primary session) plus the nodes from every cached aggregate mesh-status
+     * snapshot (which carry each node's full live session list). getCachedInlineMeshNodes()
+     * returns a fresh array, so appending the aggregate nodes never mutates cached state.
+     */
+    private collectMeshSessionOwnerCandidateNodes;
     getCachedInlineMesh(meshId: string, inlineMesh?: unknown): any | undefined;
     private warmInlineMeshCache;
     private getMeshForCommand;
+    private invalidateAggregateMeshStatus;
+    /**
+     * 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 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;
     private normalizeMeshSessionCleanupMode;
     private sessionMatchesMeshNode;
+    /**
+     * Best-effort recursive removal of a managed worktree directory.
+     *
+     * The git-registry de-registration is the safety-critical step of worktree
+     * teardown; a leftover directory must never gate dropping the node from the
+     * mesh. On Windows, `fs.rmSync` can throw EINVAL/EPERM/EBUSY on submodule
+     * gitlink (`.git`) files, long paths, junctions, or while a just-stopped
+     * delegate session is still releasing a handle/cwd on the directory. This
+     * helper absorbs those errors (never throws), with bounded retries + backoff
+     * to give handles time to release, and reports whether residue remains.
+     */
+    private bestEffortRemoveWorktreeDir;
     private cleanupLocalWorktreeNode;
     private getWorktreeForceCleanupConvergence;
     private isCompletedHostedSession;
     private recordIntentionalMeshSessionStop;
     private cleanupMeshSessions;
-    private traceSessionHostAction;
     /**
      * Unified command routing.
      * Returns result for all commands:
@@ -113,6 +669,114 @@ export declare class DaemonCommandRouter {
      * @param source Log source ('ws' | 'p2p' | 'standalone' | etc.)
      */
     execute(cmd: string, args: any, source?: string): Promise<CommandRouterResult>;
+    private buildRefineJobKey;
+    private buildRefineJobHandle;
+    private queueRefineJobEvent;
+    private appendRefineJobLedger;
+    /**
+     * On daemon restart, scan all mesh ledgers for refine jobs that were dispatched
+     * but never completed/failed (i.e. the daemon died mid-job).  Re-queue each one
+     * so the job runs to completion automatically without coordinator intervention.
+     */
+    resumePendingRefineJobsOnStartup(): Promise<void>;
+    /**
+     * Synchronous refinery for a single worktree node — the gate pipeline that
+     * validates, preflights (patch-equivalence / submodule-reachability /
+     * no-op), merges, aligns submodules, cleans up the worktree node and
+     * (optionally) pushes. The body is a flat sequence of stage methods; each
+     * stage either returns a terminal CommandRouterResult (gate failure or a
+     * successful already-merged short-circuit) or `continue` with the extended
+     * context. Behavior — stage order, every early-exit, and every result shape —
+     * is identical to the previous single inlined body.
+     */
+    private executeMeshRefineNodeSynchronously;
+    /**
+     * resolve_refs stage: resolve the mesh / worktree node / source node /
+     * repoRoot, then the worktree branch, base branch, fetched base head and
+     * branch head. Seeds the RefineContext consumed by every later stage.
+     */
+    private refineResolveRefsStage;
+    /**
+     * validation stage: run the refinery validation gate (typecheck / test /
+     * lint / build per node config) and block on failure or when no allowlisted
+     * command was available. On pass, stores the summary on the context.
+     */
+    private refineValidationStage;
+    /**
+     * patch_equivalence stage: preflight that the worktree branch's cumulative
+     * patch is equivalent to base+branch. On a "behind base" branch, auto-rebase
+     * once and re-check; on an empty merge-tree with real branch changes, treat as
+     * already-merged-via-another-path and short-circuit to cleanup. Mutates the
+     * context's branchHead (after rebase) and patchEquivalence (rebased gate).
+     */
+    private refinePatchEquivalenceStage;
+    /**
+     * submodule_reachability stage: verify every submodule gitlink commit that
+     * would land via the merge is reachable from its configured remote main
+     * branch (optionally auto-publishing when policy allows). Blocks the merge
+     * when any commit is unreachable. Stores the result on the context.
+     */
+    private refineSubmoduleReachabilityStage;
+    /**
+     * effective_diff stage (no-op guard): block a silent no-op merge where the
+     * branch produces no effective root-tree diff against base — typically a
+     * submodule that has commits but whose root-level gitlink (pointer) bump was
+     * never committed, so the merge would land nothing real on main.
+     */
+    private refineEffectiveDiffStage;
+    /**
+     * merge + finalize stage: perform the --no-ff merge, align submodule
+     * checkouts after merge, clean up (remove) the worktree node per policy,
+     * append the refinery ledger entry, and (unless approval is required) push the
+     * base branch. Always terminal — produces the final CommandRouterResult.
+     */
+    private refineMergeAndFinalizeStage;
+    /**
+     * Batch refinery: converge multiple sibling worktree nodes onto the base branch
+     * in one sequential pipeline, absorbing the rebase + patch-equivalence churn that
+     * arises when several siblings touch the same submodule.
+     *
+     * Reuses executeMeshRefineNodeSynchronously per node — every node goes through the
+     * exact same validation / patch-equivalence / submodule-reachability / merge / cleanup
+     * gates, including its built-in auto-rebase onto fresh origin/<base>. Because each
+     * node fetches origin/<base> at the start of its own refine, a node merged earlier in
+     * the batch advances the base, and the next node's refine auto-rebases onto it before
+     * re-running patch-equivalence. No force-push, no reset — conflicting nodes are
+     * isolated as blocked_review while the rest of the batch proceeds.
+     */
+    private batchRefineMeshNodes;
+    /**
+     * Convergence core shared by the synchronous batch entry and the async batch job.
+     * Refines each node in order: the per-node refine pipeline fetches origin/<base>
+     * fresh, so each merged sibling advances the base before the next node's auto-rebase
+     * + patch-equivalence re-check. A blocked/failed node is isolated; the batch
+     * continues with the remaining nodes. Does NOT touch the per-node merge logic — it
+     * only sequences calls to executeMeshRefineNodeSynchronously and aggregates outcomes.
+     */
+    private runMeshRefineBatchConvergence;
+    private buildRefineBatchJobKey;
+    private buildRefineBatchJobHandle;
+    /**
+     * Emit a batch Refinery terminal/accepted event through the SAME pending-event +
+     * forward mechanism single-node refine uses (queueRefineJobEvent), so the
+     * coordinator's existing refine:accepted/completed/failed handling and message
+     * renderer apply unchanged. The aggregate per-node results ride along in `result`.
+     */
+    private queueRefineBatchJobEvent;
+    private appendRefineBatchJobLedger;
+    private finishMeshRefineBatchJob;
+    /**
+     * Async entry for the batch Refinery execute path. Mirrors startMeshRefineJob:
+     * resolves the plan synchronously (so target/ordering errors and the dry-run shape
+     * stay synchronous), then for execute=true registers an in-flight batch job, returns
+     * {async:true, status:'accepted', batch:true, ...plan} immediately, and runs the
+     * convergence loop in the background — emitting the same terminal refine event.
+     * Idempotent: a batch already in flight for this mesh returns the running handle
+     * with duplicate:true rather than spawning a second background job.
+     */
+    private startMeshRefineBatchJob;
+    private finishMeshRefineJob;
+    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.