@adhdev/daemon-core 0.9.82-rc.262 → 0.9.82-rc.263

package/dist/mesh/mesh-active-work.d.ts

@@ -83,6 +83,24 @@ export declare function buildMeshActiveWork(opts: BuildMeshActiveWorkOptions): {
     terminalDirectWork: MeshActiveWorkRecord[];
     summary: MeshActiveWorkSummary;
 };
+/**
+ * staleReason strings (produced by sessionStatusFromNodes above) that indicate the original
+ * node/session is GONE from the live mesh — i.e. the staleDirect record is an orphaned ledger
+ * artifact, not active or recoverable work. These are the only reasons safe to prune from the
+ * active staleDirect surface. The "no provider acknowledgement" reason is deliberately excluded:
+ * those entries have a still-live node/session (staleDispatchUnacknowledged) and represent
+ * recoverable dispatch failures, never orphans.
+ */
+export declare const PRUNABLE_ORPHAN_STALE_REASONS: ReadonlySet<string>;
+export type StaleDirectPruneClassification = 'prunable_orphan' | 'prunable_terminal' | 'preserve_unacknowledged' | 'preserve_active';
+/**
+ * Classify a direct-work record for the staleDirect prune path. Pure function — the prune tool
+ * uses this so the safety rules (never touch active work or recoverable unacknowledged dispatches)
+ * live next to the staleReason producers and are independently testable.
+ */
+export declare function classifyStaleDirectForPrune(record: Pick<MeshActiveWorkRecord, 'staleReason' | 'staleDispatchUnacknowledged' | 'terminal'>, opts?: {
+    includeTerminal?: boolean;
+}): StaleDirectPruneClassification;
 export declare function buildCompactStaleDirectWorkSummary(staleDirectWork: MeshActiveWorkRecord[], opts?: {
     sampleLimit?: number;
     detailHint?: string;

package/dist/mesh/mesh-fast-forward.d.ts

@@ -10,19 +10,50 @@ export interface MeshFastForwardNodeArgs {
     submoduleIgnorePaths?: string[];
     timeoutMs?: number;
     trigger?: 'manual' | 'idle_auto' | string;
+    /**
+     * Operation mode. 'merge' (default) absorbs upstream commits into the local
+     * branch via git merge --ff-only (requires ahead=0, behind>0). 'push' publishes
+     * local commits to origin via a strict ff-only push (requires HEAD to be a
+     * descendant of origin/<branch>); it never force-pushes, resets, or rebases.
+     */
+    mode?: 'merge' | 'push';
+    /**
+     * When mode='push', also fast-forward push submodule (e.g. oss) HEADs to their
+     * origin main branch. Gated by allowAutoPublishSubmoduleMainCommits — skipped
+     * unless that policy is true. Each submodule must still pass the descendant gate.
+     * Defaults false (root push only).
+     */
+    pushSubmodules?: boolean;
+    /**
+     * Mesh policy flag mirrored from RepoMeshPolicy.allowAutoPublishSubmoduleMainCommits.
+     * Submodule pushes are refused unless this is true.
+     */
+    allowAutoPublishSubmoduleMainCommits?: boolean;
 }
 export interface MeshFastForwardPlannedStep {
-    operation: 'refresh_upstream' | 'verify_clean_worktree' | 'verify_fast_forward' | 'merge_ff_only' | 'submodule_update' | 'verify_post_status';
+    operation: 'refresh_upstream' | 'verify_clean_worktree' | 'verify_fast_forward' | 'merge_ff_only' | 'submodule_update' | 'verify_post_status' | 'verify_push_descendant' | 'push_ff_only' | 'push_submodules_ff_only';
     description: string;
     safe: true;
     willMutateWorktree: boolean;
 }
+export interface MeshFastForwardSubmodulePushResult {
+    path: string;
+    commit?: string;
+    remote: string;
+    remoteBranch: string;
+    pushed: boolean;
+    skipped: boolean;
+    code: string;
+    refspec?: string;
+    error?: string;
+}
 export interface MeshFastForwardResult {
     success: boolean;
     code: string;
     nodeId?: string;
     meshId?: string;
     workspace: string;
+    mode: 'merge' | 'push';
     allowed: boolean;
     dryRun: boolean;
     willRun: boolean;
@@ -33,9 +64,18 @@ export interface MeshFastForwardResult {
     current?: GitRepoStatus;
     preStatus?: GitRepoStatus;
     postStatus?: GitRepoStatus;
+    /** Push target derived from the tracked upstream (mode='push'). */
+    pushTarget?: {
+        remote: string;
+        remoteBranch: string;
+        refspec: string;
+    };
+    /** Submodule ff-only push outcomes (mode='push' with pushSubmodules). */
+    submodulePushes?: MeshFastForwardSubmodulePushResult[];
     finalBranchConvergenceState?: Record<string, unknown>;
     operationError?: string;
     ledgerError?: string;
+    nextStep?: string;
     trigger?: string;
 }
 export declare function fastForwardMeshNode(args: MeshFastForwardNodeArgs): Promise<MeshFastForwardResult>;

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

@@ -14,7 +14,7 @@
  */
 import { EventEmitter } from 'events';
 import { MeshRuntimeStore } from './mesh-runtime-store.js';
-export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'p2p_dispatch_failed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_joined' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled' | 'direct_fast_forward' | 'delivery_unroutable';
+export type MeshLedgerKind = 'task_dispatched' | 'task_completed' | 'task_failed' | 'task_stalled' | 'task_approval_needed' | 'p2p_dispatch_failed' | 'session_launched' | 'session_auto_launch' | 'session_stopped' | 'checkpoint_created' | 'node_cloned' | 'node_joined' | 'node_removed' | 'coordinator_started' | 'recovery_attempted' | 'ledger_replicated' | 'ledger_reconciled' | 'direct_fast_forward' | 'delivery_unroutable' | 'direct_dispatch_pruned';
 export interface MeshLedgerEntry {
     id: string;
     meshId: string;

package/dist/mesh/mesh-runtime-store.d.ts

@@ -72,6 +72,12 @@ export declare class MeshRuntimeStore {
     updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void;
     cleanupTerminalDirectDispatches(olderThanMs: number): void;
     deleteDirectDispatches(meshId: string): void;
+    /**
+     * Delete specific direct dispatch rows by taskId for a mesh. Used by the staleDirect prune
+     * path to remove orphaned/terminal dispatch records whose node/session is no longer in the
+     * live mesh. Returns the number of rows actually deleted. No-op for an empty taskId list.
+     */
+    deleteDirectDispatchesByTaskId(meshId: string, taskIds: string[]): number;
     markStaleDirectDispatches(meshId: string, olderThanMs: number): void;
     setRemoteIdleSession(nodeId: string, sessionId: string, providerType: string, expiresAt: number, metadata?: any): void;
     getRemoteIdleSessions(): Array<{

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

@@ -243,6 +243,12 @@ export declare function getActiveDirectDispatches(meshId: string): DirectDispatc
 export declare function updateDirectDispatchStatus(meshId: string, sessionId: string, status: 'acked' | 'completed' | 'failed' | 'stale'): void;
 export declare function cleanupTerminalDirectDispatches(olderThanMs?: number): void;
 export declare function markStaleDirectDispatches(meshId: string, olderThanMs?: number): void;
+/**
+ * Delete specific direct dispatch rows by taskId. Returns the number of rows deleted.
+ * Used by the staleDirect prune path to evict orphaned/terminal dispatch records from the
+ * active staleDirect surface while leaving the append-only mesh ledger (audit history) intact.
+ */
+export declare function deleteDirectDispatchesByTaskId(meshId: string, taskIds: string[]): number;
 export type MeshToolCallRateResult = {
     rateLimitExceeded: boolean;
     callsInWindow: number;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.262",
+  "version": "0.9.82-rc.263",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

package/src/build-info.ts

@@ -0,0 +1,73 @@
+/**
+ * Daemon build stamp — single runtime source for "which commit is this running
+ * daemon built from?".
+ *
+ * The values are injected at BUILD time via tsup `define` (esbuild global
+ * replacement). Every build config that bundles daemon-core into a shippable
+ * daemon (daemon-core's own dist, daemon-standalone, daemon-cloud) replaces
+ * these `__DAEMON_BUILD_*` identifiers with the literal git commit/version that
+ * was current when the bundle was produced. See:
+ *   - oss/packages/daemon-core/tsup.config.ts      (standalone consumes this dist)
+ *   - packages/daemon-cloud/tsup.config.ts         (re-bundles daemon-core from source)
+ *
+ * If a bundle is produced WITHOUT the define (e.g. running src directly through
+ * tsx in dev, or a build env without git), the identifiers stay undefined and
+ * we fall back to `"unknown"` — never a ReferenceError, never a build failure.
+ *
+ * IMPORTANT (live-reflection caveat): a fresh local `daemon-core dist` rebuild +
+ * daemon restart is NOT enough to make a *cloud* daemon report a new commit —
+ * daemon-cloud ships its own re-bundle of daemon-core, so the build stamp only
+ * advances after the cloud daemon is rebuilt/redeployed and restarted. This is
+ * precisely the gap `mesh_status`'s `staleDaemonBuild` warning exists to surface.
+ */
+
+// These are replaced at build time by tsup `define`. `typeof` guards keep this
+// safe when the define is absent (the identifiers are simply not declared).
+declare const __DAEMON_BUILD_COMMIT__: string | undefined;
+declare const __DAEMON_BUILD_COMMIT_SHORT__: string | undefined;
+declare const __DAEMON_BUILD_VERSION__: string | undefined;
+declare const __DAEMON_BUILD_AT__: string | undefined;
+
+export interface DaemonBuildInfo {
+    /** Full 40-char git commit the daemon bundle was built from, or 'unknown'. */
+    commit: string;
+    /** Short (7-char) form of the same commit, or 'unknown'. */
+    commitShort: string;
+    /** package.json version baked in at build time, or 'unknown'. */
+    version: string;
+    /** ISO build timestamp if the build config injected one. */
+    builtAt?: string;
+}
+
+function readInjected(value: string | undefined): string | undefined {
+    if (typeof value !== 'string') return undefined;
+    const trimmed = value.trim();
+    if (!trimmed || trimmed === 'unknown') return undefined;
+    return trimmed;
+}
+
+let cached: DaemonBuildInfo | undefined;
+
+/**
+ * Resolve the build stamp baked into the running daemon bundle. Pure read of
+ * build-time constants — no I/O, safe to call from any runtime path. Cached.
+ */
+export function getDaemonBuildInfo(): DaemonBuildInfo {
+    if (cached) return cached;
+
+    const commit =
+        readInjected(typeof __DAEMON_BUILD_COMMIT__ !== 'undefined' ? __DAEMON_BUILD_COMMIT__ : undefined)
+        ?? 'unknown';
+    const commitShort =
+        readInjected(typeof __DAEMON_BUILD_COMMIT_SHORT__ !== 'undefined' ? __DAEMON_BUILD_COMMIT_SHORT__ : undefined)
+        ?? (commit !== 'unknown' ? commit.slice(0, 7) : 'unknown');
+    const version =
+        readInjected(typeof __DAEMON_BUILD_VERSION__ !== 'undefined' ? __DAEMON_BUILD_VERSION__ : undefined)
+        // Fall back to the runtime-injected package version env used elsewhere.
+        ?? readInjected(typeof process !== 'undefined' ? process.env?.ADHDEV_PKG_VERSION : undefined)
+        ?? 'unknown';
+    const builtAt = readInjected(typeof __DAEMON_BUILD_AT__ !== 'undefined' ? __DAEMON_BUILD_AT__ : undefined);
+
+    cached = builtAt ? { commit, commitShort, version, builtAt } : { commit, commitShort, version };
+    return cached;
+}

package/src/commands/router.ts

@@ -64,6 +64,7 @@ import {
     type WorktreeBootstrapState,
 } from '../mesh/worktree-bootstrap-config.js';
 import { buildMachineInfo, buildStatusSnapshot } from '../status/snapshot.js';
+import { getDaemonBuildInfo } from '../build-info.js';
 import { getSessionCompletionMarker } from '../status/snapshot.js';
 import { execNpmCommandSync, resolveCurrentGlobalInstallSurface, spawnDetachedDaemonUpgradeHelper } from './upgrade-helper.js';
 import { getMeshQueueRevision } from '../mesh/mesh-work-queue.js';
@@ -3521,6 +3522,8 @@ export class DaemonCommandRouter {
         const skippedSessionIds: string[] = [];
         const skippedLiveSessionIds: string[] = [];
         const skippedCoordinatorSessionIds: string[] = [];
+        const skippedLiveSessionReasons: Array<{ sessionId: string; reason: string }> = [];
+        const actedLiveDelegateSessionIds: string[] = [];
         const deleteUnsupportedSessionIds: string[] = [];
         const recordsRemainSessionIds: string[] = [];
         const errors: Array<{ sessionId: string; error: string }> = [];
@@ -3556,16 +3559,49 @@ export class DaemonCommandRouter {
             const surfaceKind = getSessionHostSurfaceKind(record);
             const liveRuntime = surfaceKind === 'live_runtime';
             const coordinatorSession = readStringValue(record?.meta?.meshCoordinatorFor) === args.meshId;
+            // A delegate session was launched by the coordinator specifically FOR this node
+            // (meta.meshNodeId === this node). It is 1:1 bound to the node, even when the node
+            // shares its daemon runtime with the main/other nodes. Removing the node should be
+            // able to stop its own delegate session — the shared-daemon concern only applies to
+            // sessions we matched by workspace alone (which could belong to the coordinator or to
+            // a sibling node that is still active).
+            const recordNodeId = readStringValue(record?.meta?.meshNodeId);
+            const recordMeshNodeFor = readStringValue(record?.meta?.meshNodeFor);
+            const delegateBoundToThisNode = !!recordNodeId
+                && recordNodeId === args.nodeId
+                && (!recordMeshNodeFor || recordMeshNodeFor === args.meshId);
             if (!hasExplicitSessionIds && coordinatorSession) {
                 skippedSessionIds.push(sessionId);
                 skippedCoordinatorSessionIds.push(sessionId);
                 continue;
             }
-            if (!hasExplicitSessionIds && liveRuntime) {
+            // Only the conservative shared-daemon guard for live sessions that are NOT a delegate
+            // explicitly bound to this node. Delegate-bound live sessions fall through and are
+            // stopped/deleted by the mode handlers below (which already record an intentional stop).
+            if (!hasExplicitSessionIds && liveRuntime && !delegateBoundToThisNode) {
                 skippedSessionIds.push(sessionId);
                 skippedLiveSessionIds.push(sessionId);
+                const matchedByWorkspaceOnly = !recordNodeId;
+                const reason = recordNodeId && recordNodeId !== args.nodeId
+                    ? `live_delegate_bound_to_other_node:${recordNodeId}`
+                    : matchedByWorkspaceOnly
+                        ? 'live_session_matched_by_workspace_only_no_node_binding'
+                        : 'live_session_not_bound_to_this_node';
+                skippedLiveSessionReasons.push({ sessionId, reason });
                 continue;
             }
+            if (!hasExplicitSessionIds && liveRuntime && delegateBoundToThisNode && args.mode === 'delete_stopped') {
+                // delete_stopped never stops live runtimes by contract — even bound delegates.
+                // Surface a clear reason instead of an unexplained skip so callers know to use
+                // stop / stop_and_delete to release a still-running bound delegate.
+                skippedSessionIds.push(sessionId);
+                skippedLiveSessionIds.push(sessionId);
+                skippedLiveSessionReasons.push({ sessionId, reason: 'live_delegate_preserved_by_delete_stopped_mode_use_stop_or_stop_and_delete' });
+                continue;
+            }
+            if (!hasExplicitSessionIds && liveRuntime && delegateBoundToThisNode) {
+                actedLiveDelegateSessionIds.push(sessionId);
+            }
             try {
                 if (args.mode === 'stop') {
                     if (!completed) {
@@ -3631,6 +3667,8 @@ export class DaemonCommandRouter {
             skippedSessionIds,
             skippedLiveSessionIds,
             skippedCoordinatorSessionIds,
+            ...(actedLiveDelegateSessionIds.length ? { actedLiveDelegateSessionIds } : {}),
+            ...(skippedLiveSessionReasons.length ? { skippedLiveSessionReasons } : {}),
             ...(deleteUnsupported ? {
                 deleteUnsupported: true,
                 effectiveCleanup: args.mode === 'stop_and_delete'
@@ -5783,7 +5821,11 @@ export class DaemonCommandRouter {
                     version: this.deps.statusVersion || 'unknown',
                     profile: 'metadata',
                 });
-                return { success: true, status: snapshot };
+                // Surface the daemon's build stamp so coordinators (mesh_status)
+                // can detect a running daemon that predates a just-merged fix and
+                // is awaiting deploy/restart. Sibling of `status` to avoid
+                // perturbing the dashboard status snapshot shape.
+                return { success: true, status: snapshot, daemonBuild: getDaemonBuildInfo() };
             }
 
             case 'get_machine_runtime_stats': {
@@ -6886,6 +6928,7 @@ export class DaemonCommandRouter {
                     ? args.submoduleIgnorePaths.filter((value: unknown): value is string => typeof value === 'string')
                     : undefined;
                 let nodeDaemonId: string | undefined;
+                let allowAutoPublishSubmoduleMainCommits = false;
                 if (meshId && nodeId) {
                     // preferInline so fast-forward can resolve inline-cache-only clone worktree nodes.
                     const meshRecord = await this.getMeshForCommand(meshId, args?.inlineMesh, { preferInline: true });
@@ -6897,6 +6940,7 @@ export class DaemonCommandRouter {
                     if (!submoduleIgnorePaths && Array.isArray(node?.policy?.submoduleIgnorePaths)) {
                         submoduleIgnorePaths = node.policy.submoduleIgnorePaths.filter((value: unknown): value is string => typeof value === 'string');
                     }
+                    allowAutoPublishSubmoduleMainCommits = mesh?.policy?.allowAutoPublishSubmoduleMainCommits === true;
                     nodeDaemonId = typeof node?.daemonId === 'string' ? node.daemonId.trim() : undefined;
                 }
                 // If the target node belongs to a remote daemon, forward the command there.
@@ -6921,6 +6965,9 @@ export class DaemonCommandRouter {
                     dryRun: args?.dryRun === true,
                     updateSubmodules: args?.updateSubmodules === true,
                     submoduleIgnorePaths,
+                    mode: args?.mode === 'push' ? 'push' : 'merge',
+                    pushSubmodules: args?.pushSubmodules === true,
+                    allowAutoPublishSubmoduleMainCommits,
                 }) as Promise<unknown>);
                 return result as CommandRouterResult;
             }

package/src/git/git-status.ts

@@ -1,5 +1,6 @@
-import type { GitRepoStatus, GitSubmoduleStatus, GitUpstreamFreshness } from './git-types.js';
+import type { DaemonBuildBehind, GitRepoStatus, GitSubmoduleStatus, GitUpstreamFreshness } from './git-types.js';
 import { GitCommandError, resolveGitRepository, runGit } from './git-executor.js';
+import { getDaemonBuildInfo, type DaemonBuildInfo } from '../build-info.js';
 
 type ResolvedGitRepo = { workspace: string; repoRoot: string | null; isGitRepo: boolean };
 
@@ -14,6 +15,12 @@ export interface GitStatusOptions {
    * Callers should opt into this only for convergence-critical surfaces.
    */
   refreshUpstream?: boolean;
+  /**
+   * Test/override seam for the daemon build stamp used by the stale-build
+   * detector. Production callers omit this so the real baked-in build commit
+   * (getDaemonBuildInfo) is used.
+   */
+  daemonBuildInfo?: DaemonBuildInfo;
 }
 
 interface GitUpstreamProbe {
@@ -54,6 +61,8 @@ export async function getGitRepoStatus(
       || stashCount > 0
       || submoduleDirty;
 
+    const daemonBuildBehind = await detectDaemonBuildBehind(repo, submodules, options);
+
     return {
       workspace: repo.workspace,
       repoRoot: repo.repoRoot,
@@ -78,6 +87,7 @@ export async function getGitRepoStatus(
       stashCount,
       lastCheckedAt,
       submodules,
+      ...(daemonBuildBehind ? { daemonBuildBehind } : {}),
     };
   } catch (error) {
     if (error instanceof GitCommandError) {
@@ -91,6 +101,68 @@ export async function getGitRepoStatus(
   }
 }
 
+/**
+ * Detect whether the running daemon's build commit is a STRICT ancestor of this
+ * workspace's HEAD (root) or any of its submodules' HEAD. This surfaces the
+ * "merged a fix to main but the live daemon still ships the old bundle" gap:
+ * once the fix is committed, the workspace HEAD advances past the daemon's
+ * baked-in build commit, but the daemon keeps the old behavior until it is
+ * rebuilt/redeployed and restarted.
+ *
+ * Conservative by construction — returns undefined unless ancestry is provable:
+ *   - build commit unknown → undefined
+ *   - build commit not an object in this repo/submodule (different repo) → skip
+ *   - build commit === HEAD (daemon is current) → undefined
+ *   - build commit NOT an ancestor of HEAD (daemon ahead / diverged) → undefined
+ * Any git error is swallowed (no warning) so a flaky probe never over-warns.
+ */
+async function detectDaemonBuildBehind(
+  repo: ResolvedGitRepo,
+  submodules: GitSubmoduleStatus[] | undefined,
+  options: GitStatusOptions,
+): Promise<DaemonBuildBehind | undefined> {
+  const build = options.daemonBuildInfo ?? getDaemonBuildInfo();
+  if (!build.commit || build.commit === 'unknown') return undefined;
+
+  // Check the root repo first, then each submodule. The daemon build commit is
+  // baked from the daemon-core (oss submodule) HEAD, so on an adhdev
+  // superproject worktree the match is expected on the `oss` submodule, not the
+  // root — checking both keeps the helper repo-agnostic.
+  const scopes: Array<{ scope: string; repoPath: string }> = [
+    { scope: 'root', repoPath: repo.repoRoot || repo.workspace },
+  ];
+  for (const sub of submodules || []) {
+    if (sub.repoPath && !sub.error) scopes.push({ scope: sub.path, repoPath: sub.repoPath });
+  }
+
+  for (const { scope, repoPath } of scopes) {
+    try {
+      // Build commit must be a real object in THIS repo, else it's a different repo.
+      await runGit(repoPath, ['cat-file', '-e', `${build.commit}^{commit}`], options);
+      const headResult = await runGit(repoPath, ['rev-parse', 'HEAD'], options);
+      const head = headResult.stdout.trim();
+      if (!head || head === build.commit) continue;
+      // Strict ancestor: build commit is reachable from HEAD but is not HEAD.
+      await runGit(repoPath, ['merge-base', '--is-ancestor', build.commit, 'HEAD'], options);
+      // No throw → build commit IS an ancestor of HEAD → daemon is behind.
+      return {
+        buildCommit: build.commit,
+        buildCommitShort: build.commitShort,
+        head,
+        scope,
+        warning:
+          `Live daemon was built from ${build.commitShort} which is behind ${scope === 'root' ? 'workspace' : scope} HEAD ${head.slice(0, 7)}. ` +
+          `Merged code is NOT live until the daemon is rebuilt/redeployed and restarted — a local dist rebuild alone does not update a cloud daemon.`,
+      };
+    } catch {
+      // cat-file / merge-base non-zero exit (commit absent or not an ancestor)
+      // or any git error → not a provable staleness for this scope; try next.
+      continue;
+    }
+  }
+  return undefined;
+}
+
 interface ParsedPorcelainStatus {
   branch: string | null;
   upstream: string | null;

package/src/git/git-types.ts

@@ -68,10 +68,30 @@ export interface GitRepoStatus extends GitRepoIdentity {
   lastCheckedAt: number;
   /** Submodule statuses when auto-discover is enabled */
   submodules?: GitSubmoduleStatus[];
+  /**
+   * Set when the running daemon's build commit is a STRICT ancestor of this
+   * repo's HEAD (or a submodule HEAD) — i.e. the live daemon predates committed
+   * code in this workspace and is awaiting a deploy/restart to catch up.
+   * Omitted entirely when no staleness is provable (unknown build, commit not
+   * present in repo, or build commit == HEAD) to avoid over-warning.
+   */
+  daemonBuildBehind?: DaemonBuildBehind;
   error?: string;
   reason?: GitFailureReason;
 }
 
+export interface DaemonBuildBehind {
+  /** Full build commit baked into the running daemon. */
+  buildCommit: string;
+  /** Short build commit. */
+  buildCommitShort: string;
+  /** HEAD commit the build commit is behind (repo or submodule). */
+  head: string;
+  /** Where the comparison matched: 'root' or the submodule path. */
+  scope: string;
+  warning: string;
+}
+
 export type GitFileChangeStatus =
   | 'added'
   | 'modified'

package/src/index.ts

@@ -217,9 +217,10 @@ export { buildMeshLedgerReconciliationEvidence, buildMeshLedgerReplicaEvidence }
 export type { AnyLedgerSlice, MeshLedgerReconciliationEvidence, MeshLedgerReplicaEvidence, MeshLedgerReplicaStatus } from './mesh/mesh-ledger-reconciliation.js';
 
 // ── Mesh Work Queue (GUPP) ──
-export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
+export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, insertDirectDispatch, getActiveDirectDispatches, updateDirectDispatchStatus, cleanupTerminalDirectDispatches, markStaleDirectDispatches, deleteDirectDispatchesByTaskId, recordMeshToolCall, assertNoDependencyCycle, hasPendingDependents, describeTaskDependencyState } from './mesh/mesh-work-queue.js';
 export type { MeshWorkQueueEntry, MeshTaskStatus, MeshTaskMode, MeshWorkQueueStats, MeshQueueMutationOptions, MeshTaskModeValidationResult, DirectDispatchRecord, MeshToolCallRateResult } from './mesh/mesh-work-queue.js';
-export { buildCompactStaleDirectWorkSummary, buildMeshActiveWork, buildMeshActiveWorkSummary } from './mesh/mesh-active-work.js';
+export { buildCompactStaleDirectWorkSummary, buildMeshActiveWork, buildMeshActiveWorkSummary, classifyStaleDirectForPrune, PRUNABLE_ORPHAN_STALE_REASONS } from './mesh/mesh-active-work.js';
+export type { StaleDirectPruneClassification } from './mesh/mesh-active-work.js';
 export type { MeshActiveWorkRecord, MeshActiveWorkStatus, MeshActiveWorkSummary, MeshActiveWorkSource, MeshStaleDirectWorkSummary } from './mesh/mesh-active-work.js';
 export { buildMeshAsyncRefineJobs, summarizeMeshAsyncRefineJobs, STALE_TERMINAL_REFINE_WINDOW_MS, RECENT_TERMINAL_REFINE_CAP } from './mesh/mesh-refine-status.js';
 export type { MeshAsyncRefineJobStatus, MeshAsyncRefineJobSummary, MeshAsyncRefineJobsSummary } from './mesh/mesh-refine-status.js';
@@ -306,6 +307,8 @@ export type {
 export { DaemonStatusReporter } from './status/reporter.js';
 export { buildSessionEntries, findCdpManager, hasCdpManager, isCdpConnected } from './status/builders.js';
 export { buildStatusSnapshot, buildMachineInfo } from './status/snapshot.js';
+export { getDaemonBuildInfo } from './build-info.js';
+export type { DaemonBuildInfo } from './build-info.js';
 export { normalizeManagedStatus, isManagedStatusWorking, isManagedStatusWaiting, normalizeActiveChatData } from './status/normalize.js';
 export type { ManagedStatus } from './status/normalize.js';
 export type { StatusSnapshotOptions, StatusSnapshot } from './status/snapshot.js';

package/src/mesh/mesh-active-work.ts

@@ -408,6 +408,37 @@ export function buildMeshActiveWork(opts: BuildMeshActiveWorkOptions): { activeW
     return { activeWork: records, staleDirectWork, staleDirectWorkNote, terminalDirectWork, summary };
 }
 
+/**
+ * staleReason strings (produced by sessionStatusFromNodes above) that indicate the original
+ * node/session is GONE from the live mesh — i.e. the staleDirect record is an orphaned ledger
+ * artifact, not active or recoverable work. These are the only reasons safe to prune from the
+ * active staleDirect surface. The "no provider acknowledgement" reason is deliberately excluded:
+ * those entries have a still-live node/session (staleDispatchUnacknowledged) and represent
+ * recoverable dispatch failures, never orphans.
+ */
+export const PRUNABLE_ORPHAN_STALE_REASONS: ReadonlySet<string> = new Set([
+    'direct task node is no longer in the live mesh',
+    'direct task session is not present in live session records',
+    'direct task has no node id',
+]);
+
+export type StaleDirectPruneClassification = 'prunable_orphan' | 'prunable_terminal' | 'preserve_unacknowledged' | 'preserve_active';
+
+/**
+ * Classify a direct-work record for the staleDirect prune path. Pure function — the prune tool
+ * uses this so the safety rules (never touch active work or recoverable unacknowledged dispatches)
+ * live next to the staleReason producers and are independently testable.
+ */
+export function classifyStaleDirectForPrune(
+    record: Pick<MeshActiveWorkRecord, 'staleReason' | 'staleDispatchUnacknowledged' | 'terminal'>,
+    opts: { includeTerminal?: boolean } = {},
+): StaleDirectPruneClassification {
+    if (record.staleDispatchUnacknowledged === true) return 'preserve_unacknowledged';
+    if (record.terminal === true) return opts.includeTerminal ? 'prunable_terminal' : 'preserve_active';
+    if (record.staleReason && PRUNABLE_ORPHAN_STALE_REASONS.has(record.staleReason)) return 'prunable_orphan';
+    return 'preserve_active';
+}
+
 export function buildCompactStaleDirectWorkSummary(
     staleDirectWork: MeshActiveWorkRecord[],
     opts: { sampleLimit?: number; detailHint?: string; note?: string } = {},