@adhdev/daemon-core 0.9.82-rc.31 → 0.9.82-rc.310

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

@@ -0,0 +1,116 @@
+/**
+ * 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[];
+export interface MeshMissionRecord {
+    id: string;
+    meshId: string;
+    title: string;
+    goal: string;
+    status: MeshMissionStatus;
+    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;
+export declare function upsertMeshMission(meshId: string, input: {
+    id?: string;
+    title: string;
+    goal?: string;
+    status?: string;
+}): 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[];
+/**
+ * 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.
+ *
+ * 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;
+}): 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-reconcile-loop.d.ts

@@ -0,0 +1,7 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+export declare function runMeshReconcileTick(components: DaemonComponents): Promise<void>;
+interface ReconcileLoopHandle {
+    stop(): void;
+}
+export declare function setupMeshReconcileLoop(components: DaemonComponents): ReconcileLoopHandle;
+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;

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

@@ -0,0 +1,62 @@
+import type { MeshLedgerEntry } from './mesh-ledger.js';
+import type { PendingMeshCoordinatorEvent } from './mesh-events.js';
+import type { MeshAsyncJobLifecycle } from '../repo-mesh-types.js';
+export type MeshAsyncRefineJobStatus = 'accepted' | 'running' | 'completed' | 'failed';
+export interface MeshAsyncRefineJobSummary extends MeshAsyncJobLifecycle {
+    jobId: string;
+    interactionId?: string;
+    status: MeshAsyncRefineJobStatus;
+    meshId?: string;
+    nodeId?: string;
+    targetNodeId?: string;
+    targetDaemonId?: string;
+    workspace?: string;
+    branch?: string;
+    into?: string;
+    retryOfJobId?: string;
+    lastEvent?: string;
+    lastLedgerKind?: string;
+    lastUpdatedAt?: string;
+    instruction: string;
+}
+export declare function buildMeshAsyncRefineJobs(args: {
+    meshId?: string;
+    ledgerEntries?: MeshLedgerEntry[];
+    pendingEvents?: PendingMeshCoordinatorEvent[];
+}): MeshAsyncRefineJobSummary[];
+/** Terminal refine jobs older than this (relative to the newest job in the set) are
+ * "stale" — already-resolved historical refinery rejections/successes that should not
+ * keep inflating the status counts in mesh_status. 6h covers a long working session
+ * while still folding multi-day-old residue. */
+export declare const STALE_TERMINAL_REFINE_WINDOW_MS: number;
+/** Cap on how many recent terminal jobs are counted even if all fall inside the freshness
+ * window — prevents a burst of refines from dominating the summary. */
+export declare const RECENT_TERMINAL_REFINE_CAP = 8;
+export interface MeshAsyncRefineJobsSummary {
+    /** Count of jobs reflected in `byStatus` (active jobs + recent terminal jobs). */
+    total: number;
+    byStatus: Record<string, number>;
+    /** Terminal jobs dropped from the counts because they are stale residue. */
+    staleTerminal: number;
+    /** Non-terminal (accepted/running) jobs still in flight. */
+    activeJobs: MeshAsyncRefineJobSummary[];
+}
+/**
+ * Build a compact summary of refine jobs that folds stale terminal jobs.
+ *
+ * The full job list (from `buildMeshAsyncRefineJobs`) is derived from a recent ledger
+ * window and deduped by jobId, but it still includes every terminal (completed/failed)
+ * job that happens to fall in that window — including multi-day-old refinery rejections
+ * that have long since been resolved. Those stale terminals inflate `byStatus.failed`
+ * and read as "current breakage" when they are historical noise.
+ *
+ * Active (accepted/running) jobs are always counted. Terminal jobs are counted only when
+ * they are recent: within `STALE_TERMINAL_REFINE_WINDOW_MS` of the newest job's activity
+ * time AND among the `RECENT_TERMINAL_REFINE_CAP` most-recent terminals. Everything else
+ * is folded into `staleTerminal` and excluded from `byStatus`.
+ *
+ * Freshness is measured relative to the newest job in the set (not wall-clock), so the
+ * result is deterministic for a given input — important for tests and for stale-clock
+ * environments.
+ */
+export declare function summarizeMeshAsyncRefineJobs(jobs: MeshAsyncRefineJobSummary[]): MeshAsyncRefineJobsSummary;

package/dist/mesh/mesh-review-inbox.d.ts

@@ -0,0 +1,90 @@
+/**
+ * M4.0: Review inbox — derive review items from existing truth.
+ *
+ * No new store: review items are a query-time projection of
+ *   - mesh_status node statuses (daemon-owned branchConvergence), and
+ *   - the task ledger (completion evidence envelopes + refine job results).
+ *
+ * Scope (M4.0): host-daemon-local nodes only. Remote nodes are excluded and
+ * surfaced via remoteNodesExcluded/excludedRemoteNodeIds until the
+ * daemon↔daemon P2P relay path is live-verified (M4.2).
+ */
+import type { MeshLedgerEntry } from './mesh-ledger.js';
+export type MeshReviewInboxReason = 'merge_candidate' | 'refine_blocked_review';
+export interface MeshReviewInboxConvergence {
+    status: string;
+    reason: string | null;
+    nextStep: string | null;
+    needsConvergence: boolean;
+}
+export interface MeshReviewInboxEvidence {
+    available: boolean;
+    /** Ledger kind of the entry the evidence came from. */
+    kind?: 'task_completed' | 'task_failed';
+    /** 'task_completion' = ordinary worker completion envelope; 'refine_job' = Refinery result. */
+    source?: 'task_completion' | 'refine_job';
+    timestamp?: string;
+    taskId?: string;
+    sessionId?: string;
+    /** M2-3 bootstrap stage from the refine validation gate: cached|ran|failed|skipped|legacy|not_configured. */
+    bootstrap?: Record<string, unknown> | null;
+    validation?: Record<string, unknown> | null;
+    checkpoint?: Record<string, unknown> | null;
+    worker?: {
+        status: string;
+        classification?: string;
+        changedFiles: string[];
+        changedFilesTruncated?: true;
+        validationResults: Array<Record<string, unknown>>;
+        errors: string[];
+        requiresUserAction: boolean;
+    } | null;
+    finalBranchConvergenceState?: Record<string, unknown>;
+    refineJob?: Record<string, unknown>;
+}
+export interface MeshReviewInboxDiffFile {
+    path: string;
+    status?: string;
+    insertions?: number;
+    deletions?: number;
+    binary?: boolean;
+    oldPath?: string;
+}
+export interface MeshReviewInboxDiffSummary {
+    baseRef: string;
+    files: MeshReviewInboxDiffFile[];
+    totalFiles: number;
+    totalInsertions: number;
+    totalDeletions: number;
+    truncated: boolean;
+    error?: string;
+}
+export interface MeshReviewInboxItem {
+    nodeId: string;
+    workspace: string | null;
+    branch: string | null;
+    defaultBranch: string | null;
+    isLocalWorktree: boolean;
+    reviewReason: MeshReviewInboxReason;
+    convergence: MeshReviewInboxConvergence;
+    evidence: MeshReviewInboxEvidence;
+    transcriptHandle: Record<string, unknown> | null;
+    /** Latest non-terminal Refinery job for this node (accepted/running), if any. */
+    activeRefineJob: Record<string, unknown> | null;
+    lastActivityAt: string | null;
+    /** Filled by the daemon command with a bounded base-branch diff probe; null when the workspace is not locally readable. */
+    diffSummary?: MeshReviewInboxDiffSummary | null;
+}
+export interface MeshReviewInboxDerivation {
+    items: MeshReviewInboxItem[];
+    remoteNodesExcluded: boolean;
+    excludedRemoteNodeIds: string[];
+}
+/**
+ * Derive review inbox items from mesh_status node statuses and a bounded
+ * ledger tail. Pure and read-only; the caller attaches diffSummary separately.
+ */
+export declare function deriveMeshReviewInboxItems(args: {
+    nodes: Array<Record<string, unknown>>;
+    ledgerEntries: MeshLedgerEntry[];
+}): MeshReviewInboxDerivation;

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

@@ -0,0 +1,70 @@
+import type { DaemonComponents } from '../boot/daemon-lifecycle.js';
+export type WorkerDelegateRejectionReason = 'not_cli' | 'no_workspace' | 'no_worker_envelope' | 'coordinator_not_dispatch_target' | 'mesh_unresolved';
+export interface WorkerDelegateRouting {
+    /** True when the source session is a mesh worker whose events must route to a coordinator. */
+    isDelegate: boolean;
+    /** Resolved mesh id (runtime stamp, direct-dispatch recovery, or workspace lookup). */
+    meshId: string;
+    /** Resolved node id within the mesh, or '' when it cannot be determined. */
+    nodeId: string;
+    /** Human-readable node label for the coordinator system message. */
+    nodeLabel: string;
+    /** Coordinator daemon anchor (prefixed id) when the worker carries one; '' otherwise. */
+    coordinatorDaemonId: string;
+    /** Source session workspace (best-effort; '' when the session/workspace is missing). */
+    workspace: string;
+    /** Source session id echoed back, so diagnostics can name the dropped event's origin. */
+    sessionId: string;
+    /** Why routing was rejected (isDelegate=false), for fail-loud diagnostics (R4). */
+    rejectionReason?: WorkerDelegateRejectionReason;
+}
+interface ResolveDeps {
+    /** Resolve a mesh by id (local config + inline cache). */
+    getMeshById: (meshId: string) => any | undefined;
+    /** Resolve a mesh by workspace path (cached repo lookup). */
+    getMeshByWorkspace: (workspace: string) => any | undefined;
+}
+/**
+ * Resolve how a source CLI session's mesh events should route to a coordinator.
+ *
+ * This is the single authoritative interpretation of the worker envelope. It folds
+ * together every signal that previously lived in inline branches:
+ *  - runtime stamps (meshNodeFor / meshNodeId)
+ *  - the coordinator anchor (meshCoordinatorDaemonId) and launch marker (launchedByCoordinator,
+ *    meshCoordinatorNodeId) — any one proves delegation even if the node/mesh stamp was dropped
+ *  - direct-dispatch recovery: a coordinator session that is itself a dispatch target
+ *  - workspace→mesh fallback when no runtime mesh id survived
+ *
+ * Returns isDelegate=false (with a rejectionReason) instead of throwing, so the caller
+ * can either ignore non-delegate events or surface a diagnostic.
+ */
+export declare function resolveWorkerDelegateRouting(components: DaemonComponents, instanceId: string, deps: ResolveDeps): WorkerDelegateRouting;
+/** Ledger stream that collects delivery_unroutable diagnostics (no real mesh id exists for them). */
+export declare const UNROUTABLE_DIAGNOSTIC_STREAM = "__unroutable__";
+export declare function __resetUnroutableDiagnosticsForTests(): void;
+/** True only for rejections that represent a silently-dropped delegate event worth a diagnostic. */
+export declare function isUnroutableDelegateRejection(routing: WorkerDelegateRouting): boolean;
+/**
+ * R4: record that a worker event with a valid envelope could not be routed to a coordinator.
+ * Writes a `delivery_unroutable` ledger entry (deduped within a short window) so operators see
+ * WHY a completion never arrived instead of it vanishing. No-op for non-diagnostic rejections.
+ */
+export declare function recordUnroutableDelegateEvent(routing: WorkerDelegateRouting, eventName: string): boolean;
+export interface UnroutableDeliveryDiagnostic {
+    timestamp: string;
+    event: string;
+    sessionId?: string;
+    workspace?: string;
+    coordinatorDaemonId?: string;
+}
+/**
+ * R4 visibility: recent delivery_unroutable diagnostics, newest first. Surfaced in mesh_status
+ * so an operator/coordinator can see that completions were dropped (envelope present, mesh
+ * unresolved) rather than the drops being invisible in a ledger nobody reads. The diagnostics
+ * live in a single shared stream because an unroutable event has no resolvable mesh.
+ */
+export declare function getRecentUnroutableDeliveries(opts?: {
+    sinceMs?: number;
+    limit?: number;
+}): UnroutableDeliveryDiagnostic[];
+export {};