@adhdev/daemon-core 0.9.82-rc.47 → 0.9.82-rc.470

package/dist/mesh/mesh-node-identity.d.ts

@@ -0,0 +1,310 @@
+/**
+ * Mesh node-identity & git-freshness helpers
+ *
+ * Extracted from commands/router.ts (behavior-preserving move). Contains:
+ *   - daemon-id / machine-id / hostname normalization + canonicalization
+ *   - inline-mesh node identity reconciliation and transient-state handling
+ *   - git-status normalization, branch-convergence, and freshness/staleness derivation
+ *   - the direct git-probe cache and remote git-status probe machinery
+ *
+ * router.ts re-exports every public symbol from here so existing import paths
+ * (e.g. `from '.../commands/router.js'`) keep working.
+ */
+import type { ProviderLoader } from '../providers/provider-loader.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 readMeshNodeDaemonId(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 shouldRefreshStalePendingAggregate(snapshot: any, options?: {
+    requireDirectPeerTruth?: boolean;
+}): boolean;
+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;
+    reporterMachineNickname: string | null;
+    reporterProviderVersions: Record<string, string> | null;
+    reporterDaemonBuildVersion: 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;
+    reporterMachineNickname?: string | null;
+    reporterProviderVersions?: Record<string, string> | null;
+    reporterDaemonBuildVersion?: string | null;
+}): void;
+export declare function inlineMeshCarriesTransientNodeTruth(inlineMesh: any): boolean;
+export declare function readInlineMeshNodeId(node: any): string;
+export declare function isDeadLocalWorktreeNode(node: any): boolean;
+export declare function foldMeshNodeIdentityToCanonical(node: any): any;
+export declare function normalizeInlineMeshNodeIdentity(inlineMesh: any): any;
+export declare function sanitizeInlineMesh(inlineMesh: any): any;
+export declare function reconcileInlineMeshCache(cached: any, incoming: any): any;
+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>;
+export declare function readCachedInlineMeshActiveSessions(node: any): string[];
+/**
+ * Wider session-ownership scan used ONLY by resolveRemoteMeshSessionOwnerDaemonId: collect
+ * EVERY session id a mesh node currently hosts. readCachedInlineMeshActiveSessions above only
+ * surfaces the node's single primary session (cachedStatus.activeSession) — other consumers
+ * depend on that one-session semantics, so it is left untouched. A worker hosting more than one
+ * session exposes its non-primary sessions only through the plural live-session arrays the
+ * coordinator carries: status.activeSessions / activeSessionDetails (built from live records on
+ * the aggregate snapshot, see get_mesh_status), or a worker's merged session report. A
+ * controlbar/modal command (invoke_provider_script / resolve_action / set_mode / …) targeting a
+ * non-primary remote session resolves its owner daemon only when those plural shapes are scanned
+ * too. Mirrors sessionStatusFromNodes' shape tolerance (mesh-active-work.ts): plural arrays of
+ * string ids OR objects keyed by id/sessionId/session_id/runtimeSessionId/instanceId, on both
+ * camelCase and snake_case, at the node root and under cachedStatus / lastProbe.
+ */
+export declare function collectMeshNodeHostedSessionIds(node: any): Set<string>;
+/**
+ * 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>;
+/**
+ * Canonical live-probe → freshness adapter. The coordinator-facing mesh_status
+ * (mcp-server `meshStatus`) builds each node entry from a SINGLE fresh git_status
+ * probe that either returns (live truth) or throws (peer unreachable). It used to
+ * hand-reconstruct the freshness INPUT inline — a synthetic `{ git, connection }`
+ * status plus the directTruthUnavailable/liveTruthProbed wiring — which is exactly
+ * how a field added to `buildMeshNodeDataFreshness`'s input contract ends up "wired
+ * on the daemon surface, null on the coordinator surface" (the rc.371
+ * null-everywhere regression). Routing every live-probe surface through this one
+ * adapter keeps the marker derivation canonical: there is a SINGLE place that turns
+ * a probe outcome into freshness args, so the two mesh_status surfaces cannot drift.
+ *
+ * `liveTruthProbed` true → the probe returned (live/self truth); false → it threw,
+ * so a configured peer is unreachable while an unconfigured node (no daemonId) falls
+ * through to the classifier's `unconfigured` branch.
+ */
+export declare function buildMeshNodeProbeFreshness(args: {
+    /** The git snapshot this probe stamped on the node entry (entry.git). */
+    git: unknown;
+    /** True when the fresh git_status probe RETURNED (live truth); false when it threw. */
+    liveTruthProbed: boolean;
+    isSelfNode: boolean;
+    /** The node's resolved daemonId; absent → unconfigured node. */
+    daemonId?: string;
+    /** The mesh node record, for held-git fallback when the probe did not return live. */
+    node?: any;
+    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;
+export declare const MESH_DIRECT_PROBE_REUSE_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;
+    /**
+     * Local (same-machine) git_status dedup. The bootstrap direct-truth hydrate
+     * and the per-node render loop both call getGitRepoStatus(refreshUpstream:true)
+     * for the same local workspace within one mesh_status call. Each such probe
+     * fans out ~13-15 git subprocesses, and because the two passes are separated by
+     * the render/hydrate work of every OTHER node they routinely straddle the
+     * getGitRepoStatus 1.5s TTL, so the second pass re-shells the whole ~14-process
+     * collection. Routing both through this cache (namespaced under a reserved
+     * daemon id so it never collides with a remote-peer key) collapses them to one
+     * collection per workspace per request, and reuses it across the reuse window
+     * so the dashboard auto-retry loop can't restart a fresh local probe seconds
+     * apart either.
+     */
+    private static readonly LOCAL_PROBE_DAEMON_ID;
+    probeLocal(workspace: string, probe: () => Promise<Record<string, unknown> | null>): Promise<Record<string, unknown> | null>;
+    /**
+     * 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;
+}>;

package/dist/mesh/mesh-queue-assignment.d.ts

@@ -0,0 +1,158 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+import type { RepoMeshSchedulingStrategy } from '../repo-mesh-types.js';
+export declare function __resetIdleAutoFastForwardForTests(): void;
+export declare function getMeshWithCache(components: DaemonComponents, meshId: string): any | undefined;
+export declare function tryAssignQueueTask(components: DaemonComponents, meshId: string, nodeId: string, sessionId: string, providerType: string): boolean;
+interface AwaitClaimBackoffState {
+    cycles: number;
+    nextAttemptAtMs: number;
+}
+export declare function __resetAutoLaunchAwaitClaimBackoffForTests(): void;
+export declare function __seedAutoLaunchAwaitClaimBackoffForTests(meshId: string, taskId: string, state: AwaitClaimBackoffState): void;
+/** Active assignments that hold the one-active-per-node / global-parallel invariant
+ *  (everything except read-only diagnoses, which run unbounded by the write cap). */
+export declare function activeWriteAssignedCount(meshId: string): number;
+/** Active read-only assignments, for the read-only safety cap. */
+export declare function activeReadonlyAssignedCount(meshId: string): number;
+/**
+ * Order eligible nodes for assignment per the mesh scheduling pipeline:
+ *   PRIORITY (schedulingPriority desc) → TIE-BREAK (strategy).
+ *
+ * The caller has already applied the TAG hard-filter and is responsible for the
+ * MAX-ALLOC capacity gate (the per-node launch/claim checks). This function only
+ * decides the *preference order* among nodes that are otherwise eligible.
+ *
+ * - 'first_eligible' (default): returns the input order verbatim and does NOT touch
+ *   the round-robin cursor — byte-for-byte the pre-feature behavior.
+ * - 'priority_only': schedulingPriority desc, then input order (load ignored).
+ * - 'least_loaded' (the user-facing 'spread' mode): schedulingPriority desc, then
+ *   active load asc, then — among nodes still tied at (priority, load) — the input
+ *   order is rotated by a per-mesh cursor that advances once per pass. The rotation
+ *   tie-break is ALWAYS on for least_loaded so a single 'spread' mode subsumes the
+ *   former separate 'round_robin' strategy (two equal-load nodes still alternate
+ *   fairly across passes instead of the lower index always winning).
+ * - 'round_robin': retained as an escape-hatch alias; behaves identically to
+ *   'least_loaded' now that least_loaded carries the rotation.
+ *
+ * `nodes` carries the original config/array index so the tie-break can fall back to
+ * deterministic input order. `bumpCursor` advances the round-robin cursor exactly
+ * once per scheduling pass (consulted for both 'least_loaded' and 'round_robin').
+ */
+interface RankableNode {
+    nodeId: string;
+    node: any;
+    index: number;
+}
+/** Test-only: resolve a mesh's effective scheduling strategy through the full
+ *  LOCAL-WINS path (`.adhdev/mesh.json` distribution → strategy, else stored policy).
+ *  Exposed so the repo-file overlay wiring can be exercised by a direct call. */
+export declare function __resolveSchedulingStrategyForTests(mesh: any): RepoMeshSchedulingStrategy;
+/** Test-only: the pure node-ordering stage (PRIORITY → TIE-BREAK). Exposed so the
+ *  scheduling pipeline can be unit-tested without standing up live CLI sessions. */
+export declare function __orderEligibleNodesForTests(meshId: string, strategy: RepoMeshSchedulingStrategy, nodes: RankableNode[], opts?: {
+    bumpCursor?: boolean;
+}): RankableNode[];
+/** One idle session eligible to claim a queued task, together with the resolved
+ *  mesh node record it belongs to. Local candidates come from live CLI instances,
+ *  remote candidates from the registered remote-idle-session store; the two arrive
+ *  with their `nodeId` under different serialization forms. */
+type IdleCandidate = {
+    nodeId: string;
+    sessionId: string;
+    providerType: string;
+    origin: 'local' | 'remote';
+    node: any;
+};
+/** Test-only: the pool-canonicalization + unique-node collapse stage. Exposed so
+ *  the mixed-form dedup invariant can be unit-tested without a live daemon. */
+export declare function __buildSchedulingPoolForTests(localCandidates: IdleCandidate[], remoteCandidates: IdleCandidate[]): {
+    pool: IdleCandidate[];
+    uniqueNodes: RankableNode[];
+};
+export declare function sessionHasActiveAssignment(meshId: string, sessionId: string): boolean;
+/**
+ * CANON-IDENTITY single-flight hardening (restart-safe, observation-based).
+ *
+ * The in-memory single-flight Set (mesh-task-inflight) is process-local and is LOST on a
+ * daemon restart — after a restart, a task still being generated by a live local worker is
+ * no longer marked in-flight, so requeueTask's Set check passes and would re-open the task
+ * for a duplicate second dispatch. This recovers the "still generating" signal from
+ * observable runtime state instead of the in-memory mark: a session is actively generating
+ * when its live local CLI instance reports an active (generating/streaming/…) status — the
+ * same predicate the dispatch active-work gate uses (sessionStateLooksActive).
+ *
+ * Local-only by design: it inspects THIS daemon's instanceManager. The primary cross-process
+ * fix (IpcTransport requeue delegating to the mesh-host daemon) keeps begin (dispatch) and
+ * check (requeue guard) co-located so the in-memory mark stays authoritative in the common
+ * path; this is the restart-safety net for sessions hosted on this daemon. A genuinely
+ * dead/stale session is not generating → returns false → the requeue proceeds as before.
+ */
+export declare function isSessionActivelyGenerating(components: DaemonComponents, sessionId: string): boolean;
+/**
+ * RECLAIM-FALSEPOS tri-state busy verdict for a session id.
+ *
+ * The binary isSessionActivelyGenerating() folds "absence of a positive generating
+ * signal" into a definitive NEGATIVE (returns false when the instance is absent). But a
+ * REMOTE session (never in THIS daemon's instanceManager) — or a locally-present session
+ * looked up under a skewed id form — then looks "not generating" and can be reclaimed out
+ * from under a worker that is genuinely mid-turn. This resolves an explicit three-way
+ * verdict instead:
+ *   - GENERATING       — a locally-present instance reports an active/streaming state.
+ *   - IDLE_CONFIRMED    — a locally-present instance reports a non-active (idle/terminal)
+ *                         state. Positive local evidence the worker is not working.
+ *   - UNKNOWN           — no locally-present instance matches (remote / gone / id-skew) or
+ *                         the observation failed. NEVER treated as IDLE_CONFIRMED.
+ *
+ * The lookup scans getByCategory('cli') with sessionIdsEquivalent (the same equivalence
+ * matching nodeHasActiveMeshWork / liveSessionCountForNode use) rather than a raw
+ * instanceManager.getInstance(id) Map.get, so an id-form-skewed but present session is
+ * found (closing the same id-form-skew hole class e245c2f9's F1 fixed elsewhere).
+ */
+export type SessionBusyVerdict = 'GENERATING' | 'IDLE_CONFIRMED' | 'UNKNOWN';
+export declare function resolveSessionBusyVerdict(components: DaemonComponents, sessionId: string): SessionBusyVerdict;
+export interface MeshQueueTriggerResult {
+    success: true;
+    meshId: string;
+    pendingBefore: number;
+    assignedBefore: number;
+    pendingAfter: number;
+    assignedAfter: number;
+    claimed: boolean;
+    newlyAssignedTasks: Array<{
+        id: string;
+        nodeId?: string;
+        sessionId?: string;
+    }>;
+    localIdleSessionsChecked: number;
+    remoteIdleSessionsChecked: number;
+    skippedSessions: Array<{
+        nodeId?: string;
+        sessionId?: string;
+        reason: string;
+        status?: string;
+    }>;
+    autoLaunchStarted: boolean;
+    /**
+     * True when a worker session is already on its way to claim a still-pending task —
+     * either launched this tick (autoLaunchStarted) or launched on a prior tick and still
+     * booting/awaiting-claim. Callers MUST treat this as "wait, do not launch another
+     * session": a second launch double-edits the worktree. Mutually informative with
+     * `noIdleMeshSessionAvailable`, which is suppressed whenever this is true.
+     */
+    autoLaunchPending?: boolean;
+    noIdleMeshSessionAvailable?: boolean;
+}
+export declare function triggerMeshQueue(components: DaemonComponents, meshId: string): Promise<MeshQueueTriggerResult>;
+export declare function maybeAutoFastForwardIdleNode(components: DaemonComponents, args: {
+    meshId: string;
+    nodeId: string;
+    sessionId?: string;
+    providerType?: string;
+}): Promise<void>;
+export declare function runIdleMaintenanceThenAssignQueue(components: DaemonComponents, args: {
+    meshId: string;
+    nodeId: string;
+    sessionId: string;
+    providerType: string;
+}): void;
+export {};

package/dist/mesh/mesh-reconcile-acked-hold.d.ts

@@ -0,0 +1,17 @@
+export declare const ACKED_DEATH_CONSECUTIVE_READ_FAILURES = 3;
+export declare function resolveTunedReconcileMs(envName: string, def: number, min: number, max: number): number;
+export declare function resolveAckedDeathDeadlineMs(): number;
+export declare function resolveAckedTranscriptFastTrackGraceMs(): number;
+export interface AckedHoldState {
+    liveConfirmedSinceAck: boolean;
+    consecutiveReadFailures: number;
+    transcriptIdleSinceMs?: number;
+}
+export declare const inFlightAckedHoldState: Map<string, AckedHoldState>;
+export declare function inFlightSynthKey(meshId: string, taskId: string): string;
+export declare function getHoldState(synthKey: string, meshId: string): AckedHoldState | undefined;
+export declare function setHoldState(synthKey: string, meshId: string, state: AckedHoldState): void;
+export declare function deleteHoldState(synthKey: string, meshId: string): void;
+export declare function rehydrateAckedHoldsForMesh(meshId: string): void;
+export declare function collectHeldSynthKeysForMesh(meshId: string): Set<string>;
+export declare function __resetReconcileInFlightSynthDebounceForTests(): void;

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

@@ -0,0 +1,6 @@
+export declare const DEFAULT_RECONCILE_INTERVAL_MS = 4000;
+export declare const DEFAULT_AUTO_PRUNE_MIN_AGE_MS: number;
+export declare function resolveAutoPruneMinAgeMs(): number;
+export declare const DEFAULT_PENDING_HELD_DRAIN_ESCALATE_MS = 12000;
+export declare function resolvePendingHeldDrainEscalateMs(): number;
+export declare function resolveReconcileIntervalMs(): number;

package/dist/mesh/mesh-reconcile-identity.d.ts

@@ -0,0 +1,6 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+import type { LocalMeshEntry } from '../repo-mesh-types.js';
+export declare function resolveCoordinatorDaemonIds(components: DaemonComponents): string[];
+export declare function daemonHostsMesh(mesh: LocalMeshEntry, daemonIds: string[]): boolean;
+export declare function daemonIdListIncludes(ids: readonly string[], id: string | undefined): boolean;
+export declare function resolveCoordinatorSelfIds(mesh: LocalMeshEntry, drainDaemonIds: string[]): string[];

package/dist/mesh/mesh-reconcile-loop.d.ts

@@ -0,0 +1,80 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+export { getMeshV2BackstopCounters, __resetMeshV2BackstopCountersForTests } from './mesh-reconcile-v2-backstop.js';
+export { __resetReconcileInFlightSynthDebounceForTests } from './mesh-reconcile-acked-hold.js';
+/**
+ * DRAIN-WITHOUT-INJECT guard. Classify, for a mesh on THIS daemon, whether a
+ * queue-drain caller (the MCP `get_pending_mesh_events` poll) may safely consume
+ * pending coordinator events — i.e. whether there is a surface that will actually
+ * deliver them.
+ *
+ * Root cause being guarded: `get_pending_mesh_events` marks rows drained=1
+ * atomically and unconditionally. When the live CLI coordinator for the mesh is
+ * GENERATING (or modal-parked), the reconcile loop correctly HOLDS its terminal
+ * events (drained=0) for the coordinator's next idle tick — but a concurrent MCP
+ * poll draining the SAME queue consumes those held rows into a tool result that
+ * the busy coordinator never surfaces as a turn, so the completion is lost
+ * forever (drained=1, never re-queued). The reconcile loop is the authoritative
+ * delivery path for a live CLI coordinator; the MCP poll must defer to it.
+ *
+ * Returns:
+ *  - hasLiveCliCoordinator: a CLI session with meshCoordinatorFor === meshId
+ *    exists on this daemon (the reconcile loop owns its delivery).
+ *  - deliverableNow: there is an IDLE live CLI coordinator (reconcile would
+ *    full-drain into it) — draining now is safe and equivalent.
+ *  - holdForReconcile: a live CLI coordinator exists but is non-idle
+ *    (generating / modal-parked). The MCP poll MUST NOT drain; the reconcile
+ *    loop holds the events undrained and injects them on the next idle tick.
+ *
+ * A mesh with NO live CLI coordinator on this daemon is a pure stdio MCP / LLM
+ * coordinator: the MCP tool result IS the only surface, so the poll legitimately
+ * drains (holdForReconcile=false). No regression to that path.
+ */
+export declare function resolveCoordinatorDrainDeliverability(components: Pick<DaemonComponents, 'instanceManager'>, meshId: string): {
+    hasLiveCliCoordinator: boolean;
+    deliverableNow: boolean;
+    holdForReconcile: boolean;
+};
+/**
+ * DRAIN-WITHOUT-INJECT guard for the `get_pending_mesh_events` daemon handler.
+ *
+ * Decides whether an incoming pending-events DRAIN must be held (return nothing,
+ * leave rows drained=0) because the only surface for those events is a LOCAL live
+ * CLI coordinator that is currently busy (generating / modal-parked) — in which
+ * case the reconcile loop owns delivery on the coordinator's next idle tick, and
+ * the poll draining them now would lose them.
+ *
+ * The hold applies ONLY when BOTH:
+ *   1) a live CLI coordinator for this mesh on THIS daemon is non-idle, AND
+ *   2) the drain is targeted at THIS daemon (the requested coordinatorDaemonId is
+ *      empty/broadcast, or matches one of this daemon's id forms).
+ *
+ * A REMOTE coordinator pulling our worker's events passes its own (remote)
+ * coordinatorDaemonId — condition (2) is false — so the drain proceeds and the
+ * remote pull is never blocked by our local coordinator's busy state. A pure
+ * stdio MCP coordinator (no live CLI session) never satisfies (1), so its tool
+ * result remains the surface and the drain proceeds. No regression to either.
+ *
+ * SELF-COORDINATOR INBOX LEVEL-DRAIN (Defect 2): the hold above assumes the ONLY
+ * surface for a busy local coordinator's events is a future PTY inject on its idle
+ * edge, so it defers to the reconcile loop. But when the drain caller IS the local
+ * coordinator reading its OWN inbox (the `get_pending_mesh_events` call whose events
+ * are returned in the caller's tool RESULT — a data queue the self-coordinating LLM
+ * consumes directly), the events ARE surfaced losslessly the moment the tool returns,
+ * with NO PTY write. A busy self-coordinating LLM that calls a mesh tool mid-turn would
+ * otherwise get an empty inbox (held) and only see the completion on its NEXT busy→idle
+ * edge — the measured ~59s strand. `callerIsSelfCoordinatorInboxRead` marks that safe
+ * caller: the hold is relaxed for it (return the events), while every OTHER drain (a
+ * backfill relay, a broadcast poll, a DIFFERENT coordinator that genuinely needs its PTY)
+ * still defers to the reconcile loop. This relaxes delivery INTO the coordinator's own
+ * inbox only — it never changes how events are injected into a live PTY prompt.
+ */
+export declare function shouldHoldPendingDrainForBusyLocalCoordinator(components: Pick<DaemonComponents, 'instanceManager'> & {
+    statusInstanceId?: string;
+}, meshId: string, requestedCoordinatorDaemonId?: string | null, callerIsSelfCoordinatorInboxRead?: boolean): boolean;
+export declare function __resetReclaimUnknownStreakForTests(): void;
+export declare function runMeshReconcileTick(components: DaemonComponents): Promise<void>;
+export declare function __resetUnresolvedForwardRejectionCountsForTests(): void;
+interface ReconcileLoopHandle {
+    stop(): void;
+}
+export declare function setupMeshReconcileLoop(components: DaemonComponents): ReconcileLoopHandle;

package/dist/mesh/mesh-reconcile-v2-backstop.d.ts

@@ -0,0 +1,16 @@
+declare const meshV2BackstopCounters: {
+    /** PHASE-4 transcript synthesis actually reconciled a missing completion. */
+    phase4SynthesisFired: number;
+    /** Acked-hold transcript fast-track promoted a synth ahead of the death deadline. */
+    ackedHoldFastTrackFired: number;
+    /** Acked-hold death-deadline backstop released a held synth (the 8-min net). */
+    ackedHoldDeathDeadlineFired: number;
+};
+/** Test/observability accessor for the v2 last-resort backstop counters (snapshot). */
+export declare function getMeshV2BackstopCounters(): Readonly<typeof meshV2BackstopCounters>;
+/** Test helper: zero the backstop counters so a case starts from a clean slate. */
+export declare function __resetMeshV2BackstopCountersForTests(): void;
+/** Bump a backstop counter and, under enforce, WARN that a last-resort net fired —
+ *  which under a healthy v2 contract should not happen (the real emit was lost). */
+export declare function recordBackstopFire(kind: keyof typeof meshV2BackstopCounters, detail: string): void;
+export {};