@adhdev/daemon-core 0.9.82-rc.327 → 0.9.82-rc.329

package/src/git/git-status.ts

@@ -1,6 +1,13 @@
 import type { DaemonBuildBehind, GitRepoStatus, GitSubmoduleStatus, GitUpstreamFreshness } from './git-types.js';
 import { GIT_STATUS_TIMEOUT_MS, GitCommandError, resolveGitRepository, runGit } from './git-executor.js';
 import { getDaemonBuildInfo, type DaemonBuildInfo } from '../build-info.js';
+import {
+  type ChangeImpactConfig,
+  type ChangeImpactKind,
+  type ChangeImpactTarget,
+  globToRegExp,
+  loadChangeImpactConfig,
+} from './change-impact-config.js';
 
 type ResolvedGitRepo = { workspace: string; repoRoot: string | null; isGitRepo: boolean };
 
@@ -12,9 +19,42 @@ type ResolvedGitRepo = { workspace: string; repoRoot: string | null; isGitRepo:
  */
 const lastKnownGoodStatus = new Map<string, GitRepoStatus>();
 
+/**
+ * Memoized Change Impact evaluation, keyed by the inputs that can change the
+ * verdict: the scope repo path, the buildCommit..HEAD pair, and the resolved
+ * config source. The daemonBuildBehind probe runs on every mesh_status /
+ * mesh_git_status / fast_forward / git-monitor hit; without this, each hit
+ * re-shells `git diff` for the identical commit range. The cache stays correct
+ * because HEAD or a config edit perturbs the key, forcing re-evaluation.
+ */
+interface ChangeImpactEvalEntry {
+  isDaemonAffecting: boolean;
+  affectedPackages: string[];
+}
+const changeImpactEvalCache = new Map<string, ChangeImpactEvalEntry>();
+
+/**
+ * Best-effort cache of the loaded Change Impact config per repo root, keyed by the
+ * config sourceKey (path+mtime). A new sourceKey (config edited/added/removed)
+ * supersedes the entry. Avoids re-reading + re-parsing the config file on every
+ * status probe while still honoring on-disk edits.
+ */
+interface ChangeImpactConfigCacheEntry {
+  sourceKey: string;
+  config: ChangeImpactConfig | null;
+}
+const changeImpactConfigCache = new Map<string, ChangeImpactConfigCacheEntry>();
+
 /** Test seam: clear the last-known-good status cache between cases. */
 export function __resetGitStatusCacheForTests(): void {
   lastKnownGoodStatus.clear();
+  changeImpactEvalCache.clear();
+  changeImpactConfigCache.clear();
+}
+
+/** Test-only introspection: number of memoized Change Impact evaluations. */
+export function __changeImpactEvalCacheSizeForTests(): number {
+  return changeImpactEvalCache.size;
 }
 
 /**
@@ -43,6 +83,17 @@ export interface GitStatusOptions {
    * (getDaemonBuildInfo) is used.
    */
   daemonBuildInfo?: DaemonBuildInfo;
+  /**
+   * Change Impact policy override. When provided, the daemonBuildBehind
+   * classifier uses this declarative config instead of auto-loading the repo's
+   * `.adhdev/change-impact.*` file. When omitted, getGitRepoStatus auto-loads the
+   * repo config (cached); when neither is present the built-in ADHDev default
+   * policy applies, preserving the legacy behavior exactly.
+   *
+   * Pass `null` to force the built-in default policy and skip auto-loading (used
+   * to assert legacy parity in tests).
+   */
+  changeImpactConfig?: ChangeImpactConfig | null;
 }
 
 interface GitUpstreamProbe {
@@ -177,7 +228,7 @@ async function collectGitRepoStatus(
  * same process surface as the daemon tooling, so it is classified as
  * daemon-affecting (conservative). Unknown package → daemon-affecting.
  */
-const DAEMON_RUNTIME_PACKAGES = new Set([
+const DEFAULT_DAEMON_RUNTIME_PACKAGES = [
   'daemon-core',
   'daemon-standalone',
   'session-host-core',
@@ -187,14 +238,66 @@ const DAEMON_RUNTIME_PACKAGES = new Set([
   'terminal-mux-cli',
   'ghostty-vt-node',
   'mcp-server',
-]);
+];
 
-const WEB_ONLY_PACKAGES = new Set([
+const DEFAULT_WEB_ONLY_PACKAGES = [
   'web-core',
   'web-standalone',
   'web-devconsole',
   'terminal-render-web',
-]);
+];
+
+/**
+ * Built-in recommended action/command per impact classification. A change-impact
+ * config may override any of these via `impactTargets`; missing keys fall back here.
+ */
+const DEFAULT_IMPACT_TARGETS: Record<ChangeImpactKind, ChangeImpactTarget> = {
+  daemon: {
+    recommendedCommand: 'Redeploy + restart the daemon (a local dist rebuild alone does not update a cloud daemon).',
+  },
+  web: {
+    recommendedCommand: 'Redeploy the web app (no daemon restart required).',
+  },
+  none: {
+    recommendedCommand: 'No action required.',
+  },
+};
+
+/**
+ * The resolved Change Impact policy: the built-in ADHDev defaults merged with any
+ * config override. This is what the classifier consults — git-status only knows the
+ * facts (changed files/packages), policy is data.
+ */
+interface ResolvedChangeImpactPolicy {
+  daemonRuntimePackages: Set<string>;
+  webOnlyPackages: Set<string>;
+  /** Compiled config globs for additional non-runtime root files (on top of built-ins). */
+  nonRuntimeRootFilePatterns: RegExp[];
+  impactTargets: Record<ChangeImpactKind, ChangeImpactTarget>;
+}
+
+function resolveChangeImpactPolicy(config: ChangeImpactConfig | null | undefined): ResolvedChangeImpactPolicy {
+  // A field provided in config REPLACES the built-in default for that field; an
+  // omitted field falls back to the ADHDev default, so a repo with no config (or a
+  // partial config) behaves exactly as before.
+  const daemonRuntimePackages = new Set(
+    config?.daemonRuntimePackages && config.daemonRuntimePackages.length
+      ? config.daemonRuntimePackages
+      : DEFAULT_DAEMON_RUNTIME_PACKAGES,
+  );
+  const webOnlyPackages = new Set(
+    config?.webOnlyPackages && config.webOnlyPackages.length
+      ? config.webOnlyPackages
+      : DEFAULT_WEB_ONLY_PACKAGES,
+  );
+  const nonRuntimeRootFilePatterns = (config?.nonRuntimeRootFilePatterns || []).map(globToRegExp);
+  const impactTargets: Record<ChangeImpactKind, ChangeImpactTarget> = {
+    daemon: config?.impactTargets?.daemon ?? DEFAULT_IMPACT_TARGETS.daemon,
+    web: config?.impactTargets?.web ?? DEFAULT_IMPACT_TARGETS.web,
+    none: config?.impactTargets?.none ?? DEFAULT_IMPACT_TARGETS.none,
+  };
+  return { daemonRuntimePackages, webOnlyPackages, nonRuntimeRootFilePatterns, impactTargets };
+}
 
 /**
  * Root-level (non-package) files that demonstrably cannot change what the daemon
@@ -210,8 +313,11 @@ const WEB_ONLY_PACKAGES = new Set([
  * real-world case (e.g. `.verify-patch-equiv-rc292`), so they are matched broadly;
  * docs are matched by the `docs/` prefix or a markdown/text-doc extension at a
  * filename we recognize as documentation (README/CHANGELOG/LICENSE/NOTICE).
+ *
+ * Config-supplied `nonRuntimeRootFilePatterns` are matched in ADDITION to these
+ * built-ins, so a repo can extend (never narrow) the benign set declaratively.
  */
-function isNonRuntimeRootFile(file: string): boolean {
+function isNonRuntimeRootFile(file: string, policy: ResolvedChangeImpactPolicy): boolean {
   const base = file.slice(file.lastIndexOf('/') + 1);
   // Verify/convergence markers: dotfiles whose name signals a transient marker.
   if (/^\.(?:verify|marker|converge|ff-verify|patch-equiv|live-verify)\b/i.test(base)) return true;
@@ -221,19 +327,24 @@ function isNonRuntimeRootFile(file: string): boolean {
   if (/^(?:README|CHANGELOG|LICENSE|NOTICE|AUTHORS|CONTRIBUTING|CODEOWNERS)(?:\.[A-Za-z0-9]+)?$/i.test(base)) {
     return true;
   }
+  // Config-declared additional non-runtime root globs.
+  for (const re of policy.nonRuntimeRootFilePatterns) {
+    if (re.test(file)) return true;
+  }
   return false;
 }
 
 /**
  * Determine whether the changes between buildCommit..HEAD touch any daemon-runtime
- * package. Returns isDaemonAffecting:true conservatively when the changed-file set
- * can't be obtained or any changed path is outside the known web-only package set
- * AND is not a recognized non-runtime root file (marker/doc/license).
+ * package, per the resolved policy. Returns isDaemonAffecting:true conservatively
+ * when the changed-file set can't be obtained or any changed path is outside the
+ * known web-only package set AND is not a recognized non-runtime root file.
  */
 async function classifyDaemonBuildChange(
   repoPath: string,
   buildCommit: string,
   options: GitStatusOptions,
+  policy: ResolvedChangeImpactPolicy,
 ): Promise<{ isDaemonAffecting: boolean; affectedPackages: string[] }> {
   try {
     const diff = await runGit(repoPath, ['diff', '--name-only', `${buildCommit}..HEAD`], options);
@@ -254,7 +365,7 @@ async function classifyDaemonBuildChange(
     for (const file of files) {
       const match = file.match(/(?:^|\/)packages\/([^/]+)\//);
       if (!match) {
-        if (!isNonRuntimeRootFile(file)) sawRuntimeAmbiguousNonPackage = true;
+        if (!isNonRuntimeRootFile(file, policy)) sawRuntimeAmbiguousNonPackage = true;
         continue;
       }
       pkgs.add(match[1]);
@@ -267,7 +378,7 @@ async function classifyDaemonBuildChange(
     // file changed) — i.e. nothing runtime-ambiguous remains.
     const allBenign =
       !sawRuntimeAmbiguousNonPackage &&
-      affectedPackages.every((p) => WEB_ONLY_PACKAGES.has(p) && !DAEMON_RUNTIME_PACKAGES.has(p));
+      affectedPackages.every((p) => policy.webOnlyPackages.has(p) && !policy.daemonRuntimePackages.has(p));
     return { isDaemonAffecting: !allBenign, affectedPackages };
   } catch {
     // diff probe failed → can't prove web-only; stay conservative.
@@ -275,6 +386,46 @@ async function classifyDaemonBuildChange(
   }
 }
 
+/**
+ * Resolve the Change Impact config to apply for this status read. Priority:
+ *   - options.changeImpactConfig === null → force built-in default policy (no load).
+ *   - options.changeImpactConfig provided → use it verbatim (override seam).
+ *   - otherwise → auto-load the repo's `.adhdev/change-impact.*` (cached by sourceKey).
+ * Returns the (possibly null) config plus the sourceKey used for cache invalidation.
+ */
+function resolveChangeImpactConfigForRepo(
+  repoRoot: string | null,
+  options: GitStatusOptions,
+): { config: ChangeImpactConfig | null; sourceKey: string } {
+  if (options.changeImpactConfig === null) {
+    return { config: null, sourceKey: 'forced-default' };
+  }
+  if (options.changeImpactConfig !== undefined) {
+    // Injected override — key it to its content so a different injected config
+    // re-evaluates rather than reusing a prior verdict.
+    let key = 'injected';
+    try {
+      key = `injected:${JSON.stringify(options.changeImpactConfig)}`;
+    } catch {
+      // Non-serializable override (shouldn't happen) — fall back to a constant key.
+    }
+    return { config: options.changeImpactConfig, sourceKey: key };
+  }
+  if (!repoRoot) {
+    return { config: null, sourceKey: 'no-repo-root' };
+  }
+  const loaded = loadChangeImpactConfig(repoRoot);
+  const cached = changeImpactConfigCache.get(repoRoot);
+  if (cached && cached.sourceKey === loaded.sourceKey) {
+    return { config: cached.config, sourceKey: loaded.sourceKey };
+  }
+  // An invalid config is conservatively ignored (built-in default policy applies),
+  // mirroring the "fail safe" rule — never let a malformed config silence warnings.
+  const config = loaded.sourceType === 'repo_file' ? loaded.config ?? null : null;
+  changeImpactConfigCache.set(repoRoot, { sourceKey: loaded.sourceKey, config });
+  return { config, sourceKey: loaded.sourceKey };
+}
+
 async function detectDaemonBuildBehind(
   repo: ResolvedGitRepo,
   submodules: GitSubmoduleStatus[] | undefined,
@@ -283,6 +434,9 @@ async function detectDaemonBuildBehind(
   const build = options.daemonBuildInfo ?? getDaemonBuildInfo();
   if (!build.commit || build.commit === 'unknown') return undefined;
 
+  const { config, sourceKey: configKey } = resolveChangeImpactConfigForRepo(repo.repoRoot, options);
+  const policy = resolveChangeImpactPolicy(config);
+
   // 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
@@ -307,12 +461,22 @@ async function detectDaemonBuildBehind(
       // Inspect WHICH packages changed in buildCommit..HEAD. A daemon rebuild/restart
       // is only actually required when a daemon-runtime package changed; if only web /
       // render packages changed, the daemon is unaffected and just the web deploy is
-      // pending. Conservative: any probe failure → treat as daemon-affecting.
-      const { isDaemonAffecting, affectedPackages } = await classifyDaemonBuildChange(
-        repoPath,
-        build.commit,
-        options,
-      );
+      // pending. Conservative: any probe failure → treat as daemon-affecting. The
+      // verdict is memoized on (repoPath, buildCommit, head, config) to suppress
+      // re-evaluation on the hot status path.
+      const evalKey = `${repoPath}${build.commit}${head}${configKey}`;
+      let evaluated = changeImpactEvalCache.get(evalKey);
+      if (!evaluated) {
+        evaluated = await classifyDaemonBuildChange(repoPath, build.commit, options, policy);
+        changeImpactEvalCache.set(evalKey, evaluated);
+      }
+      const { isDaemonAffecting, affectedPackages } = evaluated;
+      const kind: ChangeImpactKind = isDaemonAffecting
+        ? 'daemon'
+        : affectedPackages.length > 0
+          ? 'web'
+          : 'none';
+      const target = policy.impactTargets[kind];
       const scopeLabel = scope === 'root' ? 'workspace' : scope;
       const benignDetail = affectedPackages.length > 0
         ? `only web packages changed (${affectedPackages.join(', ')})`
@@ -330,6 +494,8 @@ async function detectDaemonBuildBehind(
         scope,
         isDaemonAffecting,
         ...(affectedPackages && affectedPackages.length > 0 ? { affectedPackages } : {}),
+        recommendedAction: kind,
+        recommendedCommand: target.recommendedCommand,
         warning,
       };
     } catch {

package/src/git/index.ts

@@ -26,6 +26,22 @@ export type { GitCommandResult as GitExecutorCommandResult, GitExecutorOptions,
 export { getGitRepoStatus, parsePorcelainV2Status } from './git-status.js';
 export type { GitStatusOptions } from './git-status.js';
 
+export {
+  CHANGE_IMPACT_CONFIG_LOCATIONS,
+  CHANGE_IMPACT_CONFIG_SCHEMA,
+  globToRegExp,
+  loadChangeImpactConfig,
+  suggestChangeImpactConfig,
+  validateChangeImpactConfig,
+} from './change-impact-config.js';
+export type {
+  ChangeImpactConfig,
+  ChangeImpactConfigLoadResult,
+  ChangeImpactConfigSuggestion,
+  ChangeImpactKind,
+  ChangeImpactTarget,
+} from './change-impact-config.js';
+
 export { getGitDiffSummary, getGitFileDiff } from './git-diff.js';
 export type { GitDiffOptions, GitFileDiffResult } from './git-diff.js';
 

package/src/index.ts

@@ -233,8 +233,8 @@ export type { AnyLedgerSlice, MeshLedgerReconciliationEvidence, MeshLedgerReplic
 // ── Mesh Work Queue (GUPP) ──
 export { enqueueTask, recordDirectDispatchTask, getQueue, claimNextTask, updateTaskStatus, updateSessionTaskStatus, cancelTask, requeueTask, getMeshQueueStats, getMeshQueueRevision, normalizeMeshTaskMode, validateMeshTaskModeRequest, buildMeshNodeCapabilityTags, nodeSatisfiesRequiredTags, normalizeMeshCapabilityTags, resolveConvergeRequiredTags, 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, classifyStaleDirectForPrune, PRUNABLE_ORPHAN_STALE_REASONS } from './mesh/mesh-active-work.js';
-export type { StaleDirectPruneClassification } from './mesh/mesh-active-work.js';
+export { buildCompactStaleDirectWorkSummary, buildMeshActiveWork, buildMeshActiveWorkSummary, classifyStaleDirectForPrune, pruneStaleDirectDispatches, PRUNABLE_ORPHAN_STALE_REASONS } from './mesh/mesh-active-work.js';
+export type { StaleDirectPruneClassification, StaleDirectPruneResult, PruneStaleDirectDispatchesOptions } 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';

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

@@ -1,5 +1,7 @@
 import type { MeshLedgerEntry } from './mesh-ledger.js';
+import { appendLedgerEntry } from './mesh-ledger.js';
 import type { MeshWorkQueueEntry, DirectDispatchRecord } from './mesh-work-queue.js';
+import { deleteDirectDispatchesByTaskId } from './mesh-work-queue.js';
 import { meshNodeIdMatches } from '@adhdev/mesh-shared';
 
 export type MeshActiveWorkSource = 'queue' | 'direct';
@@ -440,6 +442,158 @@ export function classifyStaleDirectForPrune(
     return 'preserve_active';
 }
 
+/**
+ * Outcome of one staleDirect prune pass. Pure data — callers (the MCP tool, the
+ * daemon reconcile loop) format/log this however they need. The MCP tool wraps it in
+ * its JSON response; the reconcile loop logs prunedCount when > 0.
+ */
+export interface StaleDirectPruneResult {
+    mode: 'execute' | 'dry_run';
+    includeTerminal: boolean;
+    /** Total staleDirect (+terminal when included) candidates surfaced this pass. */
+    candidateCount: number;
+    /** Records classified prunable AND (when minAgeMs > 0) old enough to auto-prune. */
+    prunable: MeshActiveWorkRecord[];
+    prunedCount: number;
+    /** Prunable by classification but younger than the age gate — only populated when minAgeMs > 0. */
+    skippedTooYoung: MeshActiveWorkRecord[];
+    preservedUnacknowledged: MeshActiveWorkRecord[];
+    /** Prunable orphans/terminals with no store-backed row to delete (ledger-only audit). */
+    preservedLedgerOnly: MeshActiveWorkRecord[];
+    preservedNotOrphan: MeshActiveWorkRecord[];
+}
+
+export interface PruneStaleDirectDispatchesOptions {
+    meshId: string;
+    /** Active direct dispatches from MeshRuntimeStore (getActiveDirectDispatches). */
+    directDispatches: DirectDispatchRecord[];
+    /** Ledger tail used to attribute remote/terminal dispatches (readLedgerEntries). */
+    ledgerEntries?: MeshLedgerEntry[];
+    queue?: MeshWorkQueueEntry[];
+    /** Live mesh nodes (decorated with live session details) — drives orphan detection. */
+    nodes?: any[];
+    /** When true, actually delete + append the audit ledger entry. Default false (dry run). */
+    execute?: boolean;
+    /** Include terminal (idle/failed) direct rows as prune candidates. Default false. */
+    includeTerminal?: boolean;
+    /**
+     * Minimum age (ms, measured from createdAt/dispatchedAt) before a prunable orphan is
+     * eligible. 0 (default) prunes immediately regardless of age — the manual prune behavior.
+     * The daemon auto-prune passes a conservative threshold so a node/session that is only
+     * transiently invisible is never pruned on the spot.
+     */
+    minAgeMs?: number;
+    /** Audit source string written into the direct_dispatch_pruned ledger payload. */
+    source?: string;
+    now?: number;
+}
+
+/**
+ * Shared staleDirect prune core. Single source of truth for the prune decision + the
+ * mutation (store-row delete + audit-ledger append) used by BOTH the manual MCP tool
+ * (mesh_prune_stale_direct, minAgeMs=0) and the daemon reconcile loop's auto-prune
+ * PHASE (minAgeMs > 0). Pure decision logic via buildMeshActiveWork + classifyStaleDirectForPrune;
+ * the only side effects (on execute) are deleteDirectDispatchesByTaskId and a single
+ * direct_dispatch_pruned ledger entry — never touching the append-only audit history of the
+ * pruned dispatches themselves.
+ *
+ * Safety rules (identical for manual + auto):
+ *  - Only records classified as staleDirectWork against the CURRENT live mesh are eligible.
+ *  - Of those, only orphans (node/session gone) — and terminals when includeTerminal — are prunable.
+ *    Fresh unacknowledged dispatch failures (node/session still live) are always preserved.
+ *  - Only store-backed rows (taskId present in MeshRuntimeStore) are deleted; ledger-only remote
+ *    entries are preserved.
+ *  - When minAgeMs > 0, a prunable orphan younger than the gate is held back (skippedTooYoung).
+ *    This applies ONLY to the auto path; the manual path passes minAgeMs=0 (immediate).
+ *
+ * Idempotent: a deleted row no longer appears in getActiveDirectDispatches, so a second pass
+ * over the same orphan finds nothing to prune.
+ */
+export function pruneStaleDirectDispatches(opts: PruneStaleDirectDispatchesOptions): StaleDirectPruneResult {
+    const now = opts.now ?? Date.now();
+    const includeTerminal = opts.includeTerminal === true;
+    const execute = opts.execute === true;
+    const minAgeMs = Math.max(0, opts.minAgeMs ?? 0);
+
+    const activeWorkEvidence = buildMeshActiveWork({
+        meshId: opts.meshId,
+        queue: opts.queue,
+        ledgerEntries: opts.ledgerEntries,
+        directDispatches: opts.directDispatches,
+        nodes: opts.nodes,
+        now,
+        includeTerminalDirect: includeTerminal,
+    });
+
+    const candidates = [
+        ...activeWorkEvidence.staleDirectWork,
+        ...(includeTerminal ? activeWorkEvidence.terminalDirectWork : []),
+    ];
+    // Only prune store-backed dispatch rows (taskIds present in MeshRuntimeStore). Ledger-only
+    // remote entries have no store row to delete and are pure audit history — leave them alone.
+    const storeTaskIds = new Set(opts.directDispatches.map(d => d.taskId));
+
+    const prunable: MeshActiveWorkRecord[] = [];
+    const skippedTooYoung: MeshActiveWorkRecord[] = [];
+    const preservedUnacknowledged: MeshActiveWorkRecord[] = [];
+    const preservedLedgerOnly: MeshActiveWorkRecord[] = [];
+    const preservedNotOrphan: MeshActiveWorkRecord[] = [];
+    for (const record of candidates) {
+        const classification = classifyStaleDirectForPrune(record, { includeTerminal });
+        if (classification === 'preserve_unacknowledged') {
+            preservedUnacknowledged.push(record);
+            continue;
+        }
+        if (classification === 'preserve_active') {
+            preservedNotOrphan.push(record);
+            continue;
+        }
+        // prunable_orphan | prunable_terminal — only delete store-backed rows; ledger-only remote
+        // entries have no store row to delete and are pure audit history.
+        if (!storeTaskIds.has(record.taskId)) {
+            preservedLedgerOnly.push(record);
+            continue;
+        }
+        // Age gate (auto path only): hold back orphans that are too fresh — a node/session that is
+        // only transiently invisible must not be pruned the instant it disappears.
+        if (minAgeMs > 0) {
+            const ageRef = record.dispatchedAt || record.createdAt;
+            const ageMs = elapsedSince(ageRef, now);
+            if (ageMs < minAgeMs) {
+                skippedTooYoung.push(record);
+                continue;
+            }
+        }
+        prunable.push(record);
+    }
+
+    let prunedCount = 0;
+    if (execute && prunable.length) {
+        prunedCount = deleteDirectDispatchesByTaskId(opts.meshId, prunable.map(r => r.taskId));
+        appendLedgerEntry(opts.meshId, {
+            kind: 'direct_dispatch_pruned',
+            payload: {
+                source: opts.source || 'prune_stale_direct',
+                prunedCount,
+                taskIds: prunable.map(r => r.taskId),
+                reasons: Array.from(new Set(prunable.map(r => r.staleReason || (r.terminal ? 'terminal' : 'unknown')))),
+            },
+        });
+    }
+
+    return {
+        mode: execute ? 'execute' : 'dry_run',
+        includeTerminal,
+        candidateCount: candidates.length,
+        prunable,
+        prunedCount,
+        skippedTooYoung,
+        preservedUnacknowledged,
+        preservedLedgerOnly,
+        preservedNotOrphan,
+    };
+}
+
 export function buildCompactStaleDirectWorkSummary(
     staleDirectWork: MeshActiveWorkRecord[],
     opts: { sampleLimit?: number; detailHint?: string; note?: string } = {},

package/src/mesh/mesh-events-coordinator.ts

@@ -21,7 +21,7 @@ import {
     findRecentTerminalLedgerEvidence,
     hasDispatchAfterTerminal,
     hasUnterminalDirectDispatchLedgerEntry,
-    buildLongGeneratingCompletionReconciliation,
+    buildNoProgressCompletionReconciliation,
 } from './mesh-events-stale.js';
 import {
     buildMeshSystemMessage,
@@ -125,7 +125,7 @@ function shouldSuppressIntentionalCleanupStop(args: {
     sessionId?: string;
     nodeId?: string;
 }): boolean {
-    if (args.event !== 'agent:stopped' && args.event !== 'monitor:long_generating') return false;
+    if (args.event !== 'agent:stopped' && args.event !== 'monitor:no_progress') return false;
     if (isIntentionalCleanupStopMetadata(args.metadataEvent)) return true;
     return hasRecentIntentionalCleanupStop(args.meshId, args.sessionId, args.nodeId);
 }
@@ -453,7 +453,8 @@ function resolveAutoFastForwardPolicy(mesh: any): { enabled: boolean; maxBehind?
 function sessionStateLooksActive(state: any): boolean {
     const status = readNonEmptyString(state?.status).toLowerCase();
     const chatStatus = readNonEmptyString(state?.activeChat?.status).toLowerCase();
-    const active = new Set(['generating', 'streaming', 'long_generating', 'working', 'starting', 'waiting_approval']);
+    // 'long_generating' is retained as a legacy alias for the renamed 'no_progress' busy status.
+    const active = new Set(['generating', 'streaming', 'no_progress', 'long_generating', 'working', 'starting', 'waiting_approval']);
     return active.has(status) || active.has(chatStatus);
 }
 
@@ -1329,7 +1330,7 @@ const MESH_COORDINATOR_EVENTS = new Set([
     'agent:waiting_approval',
     'agent:stopped',
     'agent:ready',
-    'monitor:long_generating',
+    'monitor:no_progress',
     'refine:accepted',
     'refine:completed',
     'refine:failed',
@@ -1341,7 +1342,7 @@ const EVENT_TO_LEDGER_KIND: Record<string, MeshLedgerKind> = {
     'agent:generating_completed': 'task_completed',
     'agent:waiting_approval': 'task_approval_needed',
     'agent:stopped': 'task_failed',
-    'monitor:long_generating': 'task_stalled',
+    'monitor:no_progress': 'task_stalled',
 };
 
 export function isMeshCoordinatorEvent(eventName: unknown): eventName is string {
@@ -1419,24 +1420,24 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
         return { success: true, forwarded: 0, suppressed: true, intentionalCleanupStop: true };
     }
 
-    if (args.event === 'monitor:long_generating') {
-        const reconciledCompletion = buildLongGeneratingCompletionReconciliation({
+    if (args.event === 'monitor:no_progress') {
+        const reconciledCompletion = buildNoProgressCompletionReconciliation({
             meshId: args.meshId,
             nodeId: args.nodeId,
             nodeLabel: args.nodeLabel,
             metadataEvent: args.metadataEvent,
             sourceInstanceId: args.sourceInstanceId,
         });
-        if (reconciledCompletion?.source === 'long_generating_reconciliation') {
-            LOG.info('MeshEvents', `Reconciled long-generating monitor to completion for session ${eventSessionId || '(unknown session)'}`);
+        if (reconciledCompletion?.source === 'no_progress_reconciliation') {
+            LOG.info('MeshEvents', `Reconciled no-progress monitor to completion for session ${eventSessionId || '(unknown session)'}`);
             return injectMeshSystemMessage(components, {
                 ...args,
                 event: 'agent:generating_completed',
                 metadataEvent: reconciledCompletion,
             });
         }
-        if (reconciledCompletion?.source === 'long_generating_terminal_ledger_suppression') {
-            LOG.info('MeshEvents', `Suppressed long-generating monitor because terminal ledger evidence already exists for session ${eventSessionId || '(unknown session)'}`);
+        if (reconciledCompletion?.source === 'no_progress_terminal_ledger_suppression') {
+            LOG.info('MeshEvents', `Suppressed no-progress monitor because terminal ledger evidence already exists for session ${eventSessionId || '(unknown session)'}`);
             return {
                 success: true,
                 forwarded: 0,
@@ -1483,7 +1484,7 @@ function injectMeshSystemMessage(components: DaemonComponents, args: {
                 if (
                     (terminalProviderSessionId && terminalProviderSessionId === eventProviderSessionId)
                     || (terminalFinalSummary && terminalFinalSummary === eventFinalSummary)
-                    || args.metadataEvent.source === 'long_generating_reconciliation'
+                    || args.metadataEvent.source === 'no_progress_reconciliation'
                 ) {
                     LOG.info('MeshEvents', `Suppressed duplicate completion with existing terminal ledger evidence for mesh ${args.meshId} session ${eventSessionId}`);
                     return { success: true, forwarded: 0, suppressed: true, duplicateCompletion: true, terminalLedgerEvidence: true };

package/src/mesh/mesh-events-stale.ts

@@ -235,7 +235,7 @@ export function reconcileDirectDispatchCompletionFromTranscript(args: {
     return { reconciled: true, kind, workerResult, ledgerEntryId: entry.id };
 }
 
-export function buildLongGeneratingCompletionReconciliation(args: {
+export function buildNoProgressCompletionReconciliation(args: {
     meshId: string;
     nodeId?: string;
     nodeLabel: string;
@@ -265,8 +265,8 @@ export function buildLongGeneratingCompletionReconciliation(args: {
             providerType,
             providerSessionId,
             finalSummary,
-            source: 'long_generating_reconciliation',
-            reconciledFromEvent: 'monitor:long_generating',
+            source: 'no_progress_reconciliation',
+            reconciledFromEvent: 'monitor:no_progress',
             timestamp: args.metadataEvent.timestamp ?? Date.now(),
             completionDiagnostic: {
                 ...(completionDiagnostic || {}),
@@ -283,7 +283,7 @@ export function buildLongGeneratingCompletionReconciliation(args: {
     if (!terminal) return null;
     return {
         ...args.metadataEvent,
-        source: 'long_generating_terminal_ledger_suppression',
+        source: 'no_progress_terminal_ledger_suppression',
         terminalLedgerKind: terminal.kind,
         terminalLedgerAt: terminal.timestamp,
     };

package/src/mesh/mesh-events-utils.ts

@@ -137,8 +137,8 @@ export function buildMeshSystemMessage(args: {
 }): string {
     const metadata = formatCompletionMetadata(args.metadataEvent);
     if (args.event === 'agent:generating_completed') {
-        if (args.metadataEvent.source === 'long_generating_reconciliation') {
-            return `[System] ${args.nodeLabel} already has completion evidence${metadata}. The long-generating monitor reconciled the terminal handoff and marked the session complete; wait for the queued completion event/status refresh before doing any manual transcript check.`;
+        if (args.metadataEvent.source === 'no_progress_reconciliation') {
+            return `[System] ${args.nodeLabel} already has completion evidence${metadata}. The no-progress monitor reconciled the terminal handoff and marked the session complete; wait for the queued completion event/status refresh before doing any manual transcript check.`;
         }
         const reviewNote = args.metadataEvent.reviewRecommended === true
             ? ' Completion evidence is insufficient — verify via git status or provider_session_id before assuming the task is done. Use mesh_read_chat once if needed, but do not poll repeatedly.'
@@ -173,7 +173,7 @@ export function buildMeshSystemMessage(args: {
         }
         return `[System] ${args.nodeLabel} has stopped${metadata}. Use mesh_read_chat once if you need to inspect its last output.`;
     }
-    if (args.event === 'monitor:long_generating') {
+    if (args.event === 'monitor:no_progress') {
         return `[System] ${args.nodeLabel} is still reported as generating after a long interval${metadata}. Wait for pendingCoordinatorEvents or a completion/status event; if the user explicitly asks for status, make one bounded status check and then wait again.`;
     }
     if (args.event === 'worktree_bootstrap_complete') {