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

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

@@ -0,0 +1,162 @@
+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;
+    task?: {
+        difficulty?: string;
+        requiredTags?: string[];
+    };
+}): 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,84 @@
+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 reconcileZombieAssignedTasks(components: DaemonComponents, mesh: {
+    id: string;
+    nodes?: unknown[];
+}, selfIds: string[]): 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 {};

package/dist/mesh/mesh-refine-batch.d.ts

@@ -0,0 +1,68 @@
+/**
+ * Change-area analysis for one worktree node, used to order sibling nodes for
+ * batch refinement so that nodes least likely to conflict merge first.
+ *
+ * The heuristic is deliberately git-only and side-effect-free: it inspects the
+ * commits the node's branch adds on top of the base (`base..branch`) and records
+ *   - whether any submodule gitlink path is touched (high-conflict signal: the
+ *     batch must rebase later siblings onto the advanced submodule main), and
+ *   - the set of changed top-level paths (so siblings touching disjoint trees can
+ *     be ordered ahead of ones that overlap).
+ */
+export interface MeshRefineBatchNodeChangeArea {
+    nodeId: string;
+    workspace: string;
+    branch: string;
+    /** Top-level path segments changed by the branch vs. base (e.g. 'oss', 'packages'). */
+    changedTopLevelPaths: string[];
+    /** Full changed file list (bounded) for overlap detection. */
+    changedFiles: string[];
+    /** Submodule gitlink paths touched by the branch (subset of changedTopLevelPaths). */
+    touchedSubmodulePaths: string[];
+    /** True when the branch touches at least one submodule gitlink. */
+    touchesSubmodule: boolean;
+    /** Number of commits the branch is ahead of base; 0 means nothing to merge. */
+    aheadCount: number;
+    /** Non-fatal analysis error (e.g. base/branch unresolved); ordering falls back to neutral. */
+    error?: string;
+}
+export interface MeshRefineBatchOrderingResult {
+    /** Node IDs in the order they should be refined. */
+    order: string[];
+    /** Per-node change areas, keyed by node id, for plan transparency. */
+    changeAreas: Record<string, MeshRefineBatchNodeChangeArea>;
+    /** Human-readable explanation of why the order was chosen. */
+    rationale: string[];
+}
+/**
+ * Analyze one worktree node's change area against its merge base.
+ *
+ * @param baseRef  ref that the node will merge into (e.g. 'origin/main' or a SHA)
+ * @param branchRef the node's branch tip
+ * @param diffCwd  repo to run the diff in (the worktree itself is authoritative for
+ *                 `branch` resolution, but the diff `base..branch` is symmetric, so
+ *                 the worktree cwd works for both refs once base is a reachable SHA).
+ */
+export declare function analyzeMeshRefineNodeChangeArea(args: {
+    nodeId: string;
+    workspace: string;
+    branch: string;
+    baseRef: string;
+    branchRef: string;
+    diffCwd: string;
+    submodulePaths: Set<string>;
+}): Promise<MeshRefineBatchNodeChangeArea>;
+/**
+ * Order nodes for batch refinement to minimize cross-sibling conflicts.
+ *
+ * Heuristic (deterministic, stable):
+ *   1. Nodes that do NOT touch any submodule come first — they cannot advance the
+ *      submodule main, so they never force a later submodule rebase.
+ *   2. Within each group, fewer touched top-level paths first (smaller blast radius).
+ *   3. Tie-break by node id for determinism.
+ *
+ * Submodule-touching siblings are intrinsically serial: each one that merges
+ * advances oss main, so the next must rebase. Ordering them last keeps the
+ * non-submodule merges (which never need a submodule rebase) clean and up front.
+ */
+export declare function orderMeshRefineBatchNodes(changeAreas: MeshRefineBatchNodeChangeArea[]): MeshRefineBatchOrderingResult;