@adhdev/daemon-core 0.9.82-rc.46 → 0.9.82-rc.461

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

@@ -0,0 +1,189 @@
+/**
+ * M3: Mission persistence (minimal form).
+ *
+ * A mission is a persistent record of a multi-task goal so the plan lives in
+ * the system rather than in the coordinator LLM's context. Coordinator
+ * sessions can die or compact; a new coordinator reads the mission back at
+ * launch and continues.
+ *
+ * Explicit non-goals (see docs/mesh-product-plan-v2.md Phase M3): this is not
+ * a workflow engine and there is no automatic takeover daemon. Progress is
+ * never stored — it is derived from queue task statuses (mission_id) at
+ * query time.
+ */
+import { type MeshMissionStats } from './mesh-task-stats.js';
+export type MeshMissionStatus = 'active' | 'paused' | 'completed' | 'abandoned';
+export declare const MESH_MISSION_STATUSES: MeshMissionStatus[];
+/**
+ * Provenance of a mission. `magi` marks an inline mission auto-created by a
+ * mesh_magi_review fan-out (one per cross-verification run). `coordinator` (the
+ * default semantic for an unstamped/legacy mission) marks a coordinator- or
+ * user-authored mission. Used to bound the accumulation of completed MAGI missions
+ * out of the default mesh_mission_list surface — see listMeshMissionSummaries.
+ */
+export type MeshMissionSource = 'magi' | 'coordinator';
+export interface MeshMissionRecord {
+    id: string;
+    meshId: string;
+    title: string;
+    goal: string;
+    status: MeshMissionStatus;
+    /**
+     * Optional provenance tag. Absent on missions created before this field existed
+     * and on coordinator/user missions that don't bother stamping it — both are
+     * treated as coordinator missions (never auto-hidden). Only explicit `magi`
+     * missions are bounded out of the default list once completed.
+     */
+    source?: MeshMissionSource;
+    createdAt: string;
+    updatedAt: string;
+}
+export interface MeshMissionTaskAggregate {
+    total: number;
+    pending: number;
+    assigned: number;
+    completed: number;
+    failed: number;
+    cancelled: number;
+    /** Pending tasks held back by a dependency failure (blockedReason set). */
+    blocked: number;
+    /** Latest updatedAt across the mission's tasks, or null with no tasks. */
+    lastActivityAt: string | null;
+}
+export interface MeshMissionSummary extends MeshMissionRecord {
+    tasks: MeshMissionTaskAggregate;
+    /**
+     * Operational rollup (durations / attempts) derived from the ledger via
+     * computeMeshMissionStats. Optional: only populated by surfaces that opt in
+     * (e.g. mesh_status), since the rollup scans a bounded ledger tail per
+     * mission. Absent on the lightweight task-aggregate-only summaries.
+     */
+    stats?: MeshMissionStats;
+}
+/**
+ * Slim mission summary for the mesh_status compact (default) surface. Drops the
+ * full `goal` text — which can be hundreds of chars per mission and is repeated
+ * for every mission on every status call — keeping only a short preview plus a
+ * `goalTruncated` flag when the original was longer. The stored goal is never
+ * mutated; this is an output-only projection. Coordinators that need the full
+ * goal call mesh_status with verbose=true, or read the mission directly via
+ * mesh_mission_upsert / getMeshMission.
+ */
+export interface MeshMissionSlimSummary extends Omit<MeshMissionSummary, 'goal'> {
+    /** Short preview of the goal (≤ GOAL_PREVIEW_MAX chars), '' when goal empty. */
+    goalPreview: string;
+    /** True when the stored goal was longer than the preview (full text elided). */
+    goalTruncated: boolean;
+}
+/** Max chars of goal text retained in the slim (compact) mission summary. */
+export declare const GOAL_PREVIEW_MAX = 120;
+/**
+ * Shorter goal preview used by the mesh_status compact (LLM coordinator) surface.
+ * The coordinator only needs to recognize a mission, not read its full goal, and
+ * mesh_status repeats every live mission on every poll — so the status preview is
+ * tighter than the dashboard / mesh_mission_list preview (GOAL_PREVIEW_MAX).
+ */
+export declare const COMPACT_STATUS_GOAL_PREVIEW_MAX = 80;
+export declare function upsertMeshMission(meshId: string, input: {
+    id?: string;
+    title: string;
+    goal?: string;
+    status?: string;
+    source?: MeshMissionSource;
+}): MeshMissionRecord;
+export declare function getMeshMissions(meshId: string, statuses?: MeshMissionStatus[]): MeshMissionRecord[];
+export declare function getMeshMission(meshId: string, missionId: string): MeshMissionRecord | null;
+/** Aggregate task statuses for a mission at query time (no stored progress). */
+export declare function summarizeMissionTasks(meshId: string, missionId: string): MeshMissionTaskAggregate;
+export declare function summarizeMeshMission(meshId: string, mission: MeshMissionRecord): MeshMissionSummary;
+/** Active mission summaries for mesh_status / coordinator prompt injection. */
+export declare function getActiveMeshMissionSummaries(meshId: string): MeshMissionSummary[];
+/**
+ * Mission summaries for the mesh_status dashboard surface: every active/paused
+ * mission plus a capped, newest-first slice of completed/abandoned history so
+ * the dashboard can render a collapsible "history" section without unbounded
+ * payload growth. Returned newest-first within each group (active/paused first,
+ * then history), so the frontend can split on `status` directly.
+ *
+ * Compact mode (the default) elides each mission's full `goal` text — which is
+ * repeated verbatim on every status poll and dominates the payload when a mesh
+ * has many missions — returning only a short `goalPreview` + `goalTruncated`
+ * flag. Pass `verbose: true` to get the full `goal` text per mission. The stored
+ * goal is untouched in both modes; this is an output-only projection.
+ */
+export declare function getMeshStatusMissionSummaries(meshId: string, options?: {
+    historyLimit?: number;
+    verbose?: boolean;
+    withStats?: boolean;
+}): MeshMissionSummary[] | MeshMissionSlimSummary[];
+/** Folded completed/abandoned history for the mesh_status compact surface. */
+export interface MeshStatusMissionsHistoryFold {
+    /** Total completed + abandoned missions. */
+    count: number;
+    /** Count by lifecycle status (e.g. { completed, abandoned }). */
+    byStatus: Record<string, number>;
+    /** Newest-first id list (capped) so each folded mission stays addressable. */
+    missionIds: string[];
+    note: string;
+}
+/** Compact mesh_status mission projection: live detail + folded history. */
+export interface MeshStatusMissionsCompact {
+    /**
+     * Active + paused missions, goal-elided to COMPACT_STATUS_GOAL_PREVIEW_MAX and
+     * WITHOUT the operational `stats` rollup — the `tasks` aggregate already carries
+     * progress, and stats (durations/retries) is a verbose/dashboard concern.
+     */
+    live: MeshMissionSlimSummary[];
+    /** Completed + abandoned missions folded to counts + ids; null when none. */
+    historyFold: MeshStatusMissionsHistoryFold | null;
+}
+/**
+ * Mission projection for the mesh_status COMPACT (LLM coordinator) surface.
+ *
+ * Unlike getMeshStatusMissionSummaries (which emits every live mission plus a
+ * capped slice of full-detail history, each carrying a stats rollup), this keeps
+ * per-mission detail ONLY for live (active/paused) missions and folds the whole
+ * completed/abandoned history into a counts + id-list summary. Combined with the
+ * tighter goal preview and dropped stats, this is what keeps the compact
+ * mesh_status payload bounded as a mesh accumulates missions — the missions
+ * section previously dominated the payload (full goalPreview + tasks + stats per
+ * mission, for every live mission and up to 10 history missions, on every poll).
+ *
+ * The stored missions are untouched; this is an output-only projection. Full
+ * mission detail (goal text + stats + history) stays available via
+ * mesh_status verbose=true or mesh_mission_list.
+ */
+export declare function getMeshStatusMissionsCompact(meshId: string, options?: {
+    previewMax?: number;
+    historyIdLimit?: number;
+}): MeshStatusMissionsCompact;
+/**
+ * Read-only mission listing for the mesh_mission_list tool. Returns summaries
+ * (record + live task aggregate) for missions matching `statuses` — or every
+ * mission when `statuses` is omitted/empty — newest-first by updatedAt. Unlike
+ * getMeshStatusMissionSummaries this does NOT cap or group by lifecycle, so a
+ * coordinator can deliberately surface paused/abandoned/completed missions that
+ * the live status view would hide or truncate.
+ *
+ * MAGI bounding: by default this EXCLUDES completed MAGI missions (source==='magi'
+ * && status==='completed') — a mesh_magi_review fan-out auto-creates one inline
+ * mission per run and auto-closes it on collection, so without this they accumulate
+ * unbounded and drown out coordinator missions in the list. In-progress MAGI missions
+ * (active/paused) are still shown so a running cross-verification stays visible. Pass
+ * `includeMagi: true` to return every mission including completed MAGI ones. A mission
+ * with no `source` (legacy / coordinator) is never affected.
+ *
+ * Compact (the default) elides each goal to a capped preview + goalTruncated
+ * flag; verbose returns the full goal text. The stored goal is never mutated.
+ */
+export declare function listMeshMissionSummaries(meshId: string, options?: {
+    statuses?: MeshMissionStatus[];
+    verbose?: boolean;
+    includeMagi?: boolean;
+}): MeshMissionSummary[] | MeshMissionSlimSummary[];
+/**
+ * M3-3: render active missions as a prompt section for {{mission}}.
+ * Empty string when no active mission — the prompt stays byte-identical to
+ * the pre-M3 output in that case (regression guarantee).
+ */
+export declare function buildMissionPromptSection(meshId: string): string;

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 {};