@adhdev/daemon-core 0.9.82-rc.350 → 0.9.82-rc.352

package/dist/logging/logger.d.ts

@@ -7,7 +7,7 @@
  * 1. daemonLog(category, msg, level) — explicit per-category logging
  * 2. installGlobalInterceptor() — Auto-intercept console.log (once on daemon start)
  * 3. Recent log ring buffer — for remote transmission via P2P/WS
- * 4. File logging — ~/Library/Logs/adhdev/daemon.log (10MB rolling)
+ * 4. File logging — ~/.adhdev/logs/daemon-YYYY-MM-DD.log (date-based rolling)
  *
  * use:
  * import { daemonLog, LOG } from './daemon-logger';

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' | 'direct_dispatch_pruned' | 'event_held';
+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' | 'event_held' | 'task_reclaimed';
 export interface MeshLedgerEntry {
     id: string;
     meshId: string;

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

@@ -6,6 +6,7 @@ export declare class MeshRuntimeStore {
     private readonly migratedMeshIds;
     private fingerprintSweepCounter;
     private walWriteCounter;
+    private toolCallLogCounter;
     private static readonly WAL_CHECK_INTERVAL;
     private static readonly WAL_MAX_BYTES;
     private constructor();
@@ -190,6 +191,15 @@ export declare class MeshRuntimeStore {
         createdAt: string;
         updatedAt: string;
     }>;
+    /**
+     * Bug B watchdog support: true when at least one delivery record for the task has
+     * reached a confirmed-handed-off status (delivered / acked / completed). The
+     * assigned-stranded watchdog uses this to distinguish a dispatch that was never
+     * confirmed (reclaimable) from one that WAS handed to the worker (a genuinely
+     * in-flight or completion-lost task, which is PHASE 4's responsibility, not this
+     * watchdog's). Indexed by (mesh_id, task_id).
+     */
+    taskHasConfirmedDelivery(meshId: string, taskId: string): boolean;
     expireStaleSessionDeliveries(meshId: string): void;
     deleteSessionDeliveries(meshId: string): void;
     recordCompletionConflict(entry: {

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

@@ -60,6 +60,14 @@ export interface MeshWorkQueueEntry {
     requeueCount?: number;
     /** Max automatic requeue attempts. When requeueCount reaches this, task is auto-failed. */
     maxRetries?: number;
+    /**
+     * Bug B: number of times the reconcile assigned-stranded watchdog has reclaimed this
+     * row from 'assigned' back to 'pending' because its dispatch was never confirmed
+     * delivered. Separate from requeueCount (operator/execution retries) and bounded by
+     * MAX_STRANDED_RECLAIMS so a permanently-undeliverable target auto-fails rather than
+     * cycling reclaim→re-dispatch→strand forever.
+     */
+    strandedReclaimCount?: number;
     /** Last automatic queue session spin-up attempt, for mesh_view_queue/debug visibility. */
     autoLaunch?: {
         status: 'skipped' | 'started' | 'failed' | 'completed';
@@ -230,6 +238,26 @@ export declare function requeueTask(meshId: string, taskId: string, opts?: {
     /** Per-task retry cap override. Falls back to mesh policy maxTaskRetries (default 1). */
     maxRetries?: number;
 } & MeshQueueMutationOptions): MeshWorkQueueEntry | null;
+/**
+ * Bug B: reclaim a task stuck in 'assigned' because its dispatch was never confirmed.
+ *
+ * claimNextTask atomically marks a row 'assigned' BEFORE the fire-and-forget dispatch
+ * runs. If that dispatch neither rejects (→ no .catch requeue) nor is confirmed
+ * delivered — a relay that hangs without acking, or a confirm timer lost across a
+ * daemon restart — the row stays 'assigned' forever, contributing 0 pending so PHASE 3
+ * reconcile never re-examines it. This returns such a row to 'pending' and clears its
+ * dead assignment ownership (node / session / provider / dispatchTimestamp) — the same
+ * ownership-clear requeueTask applies — so PHASE 3 can re-dispatch it onto a fresh idle
+ * session.
+ *
+ * Guarded to 'assigned' rows only (a completion/cancel that already moved the row off
+ * 'assigned' must never be resurrected) and bounded by MAX_STRANDED_RECLAIMS (beyond
+ * which the task is failed so dependents unblock).
+ */
+export declare function reclaimStrandedAssignedTask(meshId: string, taskId: string, opts?: {
+    reason?: string;
+    ageMs?: number;
+} & MeshQueueMutationOptions): MeshWorkQueueEntry | null;
 /**
  * Update the status of the task currently assigned to a specific session.
  */

package/dist/providers/approval-utils.d.ts

@@ -1,4 +1,11 @@
 import type { ProviderModule } from './contracts.js';
+/**
+ * True when any of the given button labels reads as a decline/negative option
+ * (No / Deny / Cancel / Skip / …). Used as the second half of an approval-modal
+ * structural anchor: a real approval modal offers BOTH an affirmative and a
+ * decline, which distinguishes it from a generic numbered menu or prose list.
+ */
+export declare function hasNegativeApprovalOption(buttons: string[] | null | undefined): boolean;
 export declare function getApprovalPositiveHints(provider?: Pick<ProviderModule, 'approvalPositiveHints'> | null): string[];
 export declare function pickApprovalButton(buttons: string[] | null | undefined, provider?: Pick<ProviderModule, 'approvalPositiveHints'> | null): {
     index: number;

package/dist/providers/cli-provider-instance.d.ts

@@ -48,6 +48,20 @@ export declare class CliProviderInstance implements ProviderInstance {
      * keystroke until the modal *content* has settled.
      */
     private static readonly AUTO_APPROVE_SETTLE_MS;
+    /**
+     * Busy-side hysteresis for the settle gate. A momentary `generating` flip
+     * while the SAME approval modal's button block is still on screen (its
+     * question line scrolled out of the captured frame, only the buttons + a
+     * residual `esc to interrupt` spinner remain) briefly reports
+     * status!=waiting_approval. Without hysteresis that flip wipes the settle
+     * clock, and the modal→generating→modal flap restarts the 600ms window
+     * every time so auto-approve never fires. We keep the in-progress settle
+     * gate warm across an inactive blip up to this bound; only once the modal
+     * has genuinely stayed gone this long (a real resolution → idle) is the
+     * gate cleared. Bounded so a genuinely new, later approval still re-settles
+     * from scratch rather than firing on a stale timestamp.
+     */
+    private static readonly AUTO_APPROVE_GATE_HYSTERESIS_MS;
     private adapter;
     private context;
     private events;
@@ -64,6 +78,7 @@ export declare class CliProviderInstance implements ProviderInstance {
     private pendingAutoApprovalSignature;
     private pendingAutoApprovalSince;
     private autoApproveSettleTimer;
+    private autoApproveInactiveSince;
     private controlValues;
     private summaryMetadata;
     private appliedEffectKeys;

package/dist/providers/sdk/v1/builders/cli/detect-status.d.ts

@@ -57,6 +57,7 @@ interface ModalSpec {
     }>;
     buttonPattern: string;
     buttonFlags?: string;
+    buttonLabelGroup?: number;
 }
 export type DispatchGroup = 'spinner' | 'modal' | 'settled-prompt' | 'cue-ordering' | 'error-detection' | 'approval-stitching';
 export interface DispatchOrderSpec {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@adhdev/daemon-core",
-  "version": "0.9.82-rc.350",
+  "version": "0.9.82-rc.352",
   "description": "ADHDev daemon core — CDP, IDE detection, providers, command execution",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -46,7 +46,7 @@
   "author": "vilmire",
   "license": "AGPL-3.0-or-later",
   "dependencies": {
-    "@adhdev/mesh-shared": "0.9.82-rc.350",
+    "@adhdev/mesh-shared": "0.9.82-rc.352",
     "@adhdev/session-host-core": "*",
     "@agentclientprotocol/sdk": "^0.16.1",
     "ajv": "^8.20.0",

package/src/commands/upgrade-helper.ts

@@ -292,13 +292,14 @@ async function waitForPidExit(pid: number, timeoutMs: number): Promise<void> {
   }
 }
 
-export function stopSessionHostProcesses(appName: string): void {
+export async function stopSessionHostProcesses(appName: string): Promise<void> {
   const pidFile = path.join(os.homedir(), '.adhdev', `${appName}-session-host.pid`);
+  let killedPid: number | null = null;
   try {
     if (fs.existsSync(pidFile)) {
       const pid = Number.parseInt(fs.readFileSync(pidFile, 'utf8').trim(), 10);
       if (Number.isFinite(pid) && pid !== process.pid && isManagedSessionHostPid(pid)) {
-        killPid(pid);
+        if (killPid(pid)) killedPid = pid;
       }
     }
   } catch {
@@ -310,6 +311,31 @@ export function stopSessionHostProcesses(appName: string): void {
       // noop
     }
   }
+
+  // The session-host process keeps node-pty's `conpty.node` memory-mapped. On
+  // Windows a mapped native addon stays EXCLUSIVELY locked until the process
+  // fully exits and tears down the mapping — and that teardown lags `taskkill`
+  // by an indeterminate interval. `taskkill` only *requests* termination, so
+  // returning immediately lets the caller run `npm install` while conpty.node
+  // is still locked, which makes npm's copy-to-staging fail with EBUSY (the
+  // intermittent Windows upgrade failure). Wait for the killed process to
+  // actually disappear — like we already do for the parent daemon pid — so the
+  // file handle is released before the install runs. (POSIX can replace an open
+  // file freely, so the wait is harmless there.)
+  if (killedPid !== null) {
+    await waitForPidExit(killedPid, 15000);
+  }
+}
+
+// npm copies the current install's files into a staging dir before swapping in
+// the new version. On Windows that copy of `conpty.node` can still race a
+// just-killed session-host whose mapping hasn't been released yet, surfacing as
+// EBUSY/EPERM. Treat those as transient and retry with backoff.
+function isRetriableInstallLockError(error: any): boolean {
+  const code = error?.code;
+  if (code === 'EBUSY' || code === 'EPERM') return true;
+  const text = `${error?.message || ''} ${error?.stderr || ''}`;
+  return /\bEBUSY\b|\bEPERM\b|resource busy or locked/i.test(text);
 }
 
 function removeDaemonPidFile(): void {
@@ -412,23 +438,40 @@ async function runDaemonUpgradeHelper(payload: DaemonUpgradeHelperPayload): Prom
     await waitForPidExit(payload.parentPid, 15000);
   }
 
-  stopSessionHostProcesses(sessionHostAppName);
+  await stopSessionHostProcesses(sessionHostAppName);
   removeDaemonPidFile();
   cleanupStaleGlobalInstallDirs(payload.packageName, installCommand.surface);
 
   const spec = `${payload.packageName}@${payload.targetVersion || 'latest'}`;
   appendUpgradeLog(`Installing ${spec}`);
-  const installOutput = execFileSync(
-    installCommand.command,
-    installCommand.args,
-    {
-      encoding: 'utf8',
-      stdio: 'pipe',
-      maxBuffer: 20 * 1024 * 1024,
-      env: buildInstallEnvWithNodeOnPath(),
-      ...installCommand.execOptions,
-    },
-  );
+  // Windows can still race a lingering conpty.node mapping even after the
+  // session-host exits, so retry the install on transient lock errors there.
+  const maxInstallAttempts = process.platform === 'win32' ? 3 : 1;
+  let installOutput = '';
+  for (let attempt = 1; attempt <= maxInstallAttempts; attempt++) {
+    try {
+      installOutput = String(execFileSync(
+        installCommand.command,
+        installCommand.args,
+        {
+          encoding: 'utf8',
+          stdio: 'pipe',
+          maxBuffer: 20 * 1024 * 1024,
+          env: buildInstallEnvWithNodeOnPath(),
+          ...installCommand.execOptions,
+        },
+      ));
+      break;
+    } catch (error: any) {
+      if (attempt < maxInstallAttempts && isRetriableInstallLockError(error)) {
+        appendUpgradeLog(`Install attempt ${attempt} hit a file lock (${error?.code || 'lock'}); cleaning staging and retrying after backoff`);
+        cleanupStaleGlobalInstallDirs(payload.packageName, installCommand.surface);
+        await new Promise((resolve) => setTimeout(resolve, attempt * 1500));
+        continue;
+      }
+      throw error;
+    }
+  }
   if (installOutput.trim()) {
     appendUpgradeLog(installOutput.trim());
   }

package/src/index.ts

@@ -252,6 +252,11 @@ export { buildMeshHostRequiredFailure, createDefaultMeshHostMetadata, isMeshHost
 // ── Mesh Events ──
 export { triggerMeshQueue, drainPendingMeshCoordinatorEvents, getPendingMeshCoordinatorEvents, clearPendingMeshCoordinatorEvents, queuePendingMeshCoordinatorEvent, reconcileDirectDispatchCompletionFromTranscript } from './mesh/mesh-events.js';
 export type { PendingMeshCoordinatorEvent } from './mesh/mesh-events.js';
+// The coordinator-side preview surfaced from a worker's completion/status event
+// (finalSummary / workerResult.summary / lastMessagePreview). Same data the mobile
+// inbox is fed; reused by mesh_read_chat's cache fallback when the live P2P read path
+// is unavailable (saturated/unreachable peer).
+export { resolveMeshSurfacedSessionPreview, readMeshCompletionSummary } from './mesh/mesh-events-utils.js';
 
 // ── Mesh Delivery Policy ──
 export { resolveDeliveryDecision, createSessionDelivery, updateSessionDeliveryStatus, getActiveSessionDeliveries, markSessionDeliveriesTerminal, recordCompletionConflict, getRecentCompletionConflicts } from './mesh/mesh-delivery-policy.js';

package/src/logging/command-log.ts

@@ -15,11 +15,13 @@ import * as path from 'path';
 import * as os from 'os';
 
 // ─── Config ──────────────────────────────────
-const LOG_DIR = process.platform === 'win32'
-    ? path.join(process.env.LOCALAPPDATA || process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'adhdev', 'logs')
-    : process.platform === 'darwin'
-        ? path.join(os.homedir(), 'Library', 'Logs', 'adhdev')
-        : path.join(os.homedir(), '.local', 'share', 'adhdev', 'logs');
+// Command history lives under the unified ADHDev home (~/.adhdev/logs/) next to
+// the daemon log, on every platform. Honor ADHDEV_CONFIG_DIR for isolated homes.
+// Keep this in sync with logger.ts LOG_DIR.
+const ADHDEV_HOME = process.env.ADHDEV_CONFIG_DIR && process.env.ADHDEV_CONFIG_DIR.trim()
+    ? process.env.ADHDEV_CONFIG_DIR.trim()
+    : path.join(os.homedir(), '.adhdev');
+const LOG_DIR = path.join(ADHDEV_HOME, 'logs');
 
 const MAX_FILE_SIZE = 5 * 1024 * 1024; // 5MB
 const MAX_DAYS = 7;

package/src/logging/logger.ts

@@ -7,7 +7,7 @@
  * 1. daemonLog(category, msg, level) — explicit per-category logging
  * 2. installGlobalInterceptor() — Auto-intercept console.log (once on daemon start)
  * 3. Recent log ring buffer — for remote transmission via P2P/WS
- * 4. File logging — ~/Library/Logs/adhdev/daemon.log (10MB rolling)
+ * 4. File logging — ~/.adhdev/logs/daemon-YYYY-MM-DD.log (date-based rolling)
  * 
  * use:
  * import { daemonLog, LOG } from './daemon-logger';
@@ -37,11 +37,17 @@ export function setLogLevel(level: LogLevel): void {
 
 export function getLogLevel(): LogLevel { return currentLevel; }
 // ─── File logging (date-based rolling) ──────────────────────────────
-const LOG_DIR = process.platform === 'win32'
-    ? path.join(process.env.LOCALAPPDATA || process.env.APPDATA || path.join(os.homedir(), 'AppData', 'Local'), 'adhdev', 'logs')
-    : process.platform === 'darwin'
-        ? path.join(os.homedir(), 'Library', 'Logs', 'adhdev')
-        : path.join(os.homedir(), '.local', 'share', 'adhdev', 'logs');
+// Logs live under the unified ADHDev home (~/.adhdev/logs/) on every platform,
+// alongside config.json, providers/, history/, daemon.pid and session-host.log.
+// Earlier builds wrote to OS-specific dirs (~/Library/Logs/adhdev on macOS,
+// ~/.local/share/adhdev/logs on Linux, %LOCALAPPDATA%/adhdev/logs on Windows),
+// which made the daemon log undiscoverable next to everything else under
+// ~/.adhdev and inconsistent with session-host.log. Honor ADHDEV_CONFIG_DIR so
+// isolated/standalone namespaces keep their logs in their own home.
+const ADHDEV_HOME = process.env.ADHDEV_CONFIG_DIR && process.env.ADHDEV_CONFIG_DIR.trim()
+    ? process.env.ADHDEV_CONFIG_DIR.trim()
+    : path.join(os.homedir(), '.adhdev');
+const LOG_DIR = path.join(ADHDEV_HOME, 'logs');
 
 const MAX_LOG_SIZE = 5 * 1024 * 1024; // 5MB per day
 const MAX_LOG_DAYS = 7; // 7-day retention

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

@@ -168,6 +168,46 @@ function statusFromTerminal(entry: MeshLedgerEntry): MeshActiveWorkStatus {
     return 'failed';
 }
 
+const LEDGER_ONLY_STALE_REASON =
+    'direct task dispatch has no provider acknowledgement, transcript append, or active runtime transition';
+
+/**
+ * Single source of truth for classifying whether a direct dispatch is ledger-only
+ * stale (dispatched but never acknowledged: no provider ack, no transcript append,
+ * no runtime transition) and whether that staleness is "fresh unacknowledged"
+ * (target session still live) vs. an orphaned historical record.
+ *
+ * Previously this predicate was inlined in all three dispatch-classification blocks
+ * (MeshRuntimeStore path, remote-ledger path, full-ledger path) and had drifted —
+ * e.g. one block gated `isIdleUnacknowledged` on `!isTerminal` and another did not.
+ * Extracting it keeps the three callers byte-for-byte consistent. Status derivation
+ * stays per-block: it genuinely differs by data source and is passed in via `status`.
+ */
+function classifyDirectDispatch(params: {
+    /** Final classified status of the dispatch. */
+    status: MeshActiveWorkStatus;
+    /** True when a real terminal row applies (completed/failed/stale); excludes approval_needed. Gates the stale verdict. */
+    isTerminalRow: boolean;
+    /** True when any terminal-derived status exists (incl. approval_needed). Used to detect "no transition". */
+    hasTerminalStatus: boolean;
+    /** Live session status from the mesh nodes, if any. */
+    liveStatus?: string;
+    /** Live stale reason from the mesh nodes, if any. */
+    liveStaleReason?: string;
+    /** Whether the dispatch targeted an already-idle session. */
+    dispatchedToIdleSession: boolean;
+}): { ledgerOnlyStaleReason: string | undefined; isFreshUnacknowledged: boolean } {
+    const { status, isTerminalRow, hasTerminalStatus, liveStatus, liveStaleReason, dispatchedToIdleSession } = params;
+    const isNoTransition = !hasTerminalStatus && !liveStatus;
+    const isIdleUnacknowledged = status === 'idle';
+    const ledgerOnlyStaleReason =
+        !isTerminalRow && (isIdleUnacknowledged || isNoTransition || (dispatchedToIdleSession && isIdleUnacknowledged))
+            ? LEDGER_ONLY_STALE_REASON
+            : undefined;
+    const isFreshUnacknowledged = Boolean(ledgerOnlyStaleReason && !liveStaleReason);
+    return { ledgerOnlyStaleReason, isFreshUnacknowledged };
+}
+
 export function buildMeshActiveWorkSummary(activeWork: MeshActiveWorkRecord[]): MeshActiveWorkSummary {
     const statusCounts: Record<MeshActiveWorkStatus, number> = {
         pending: 0,
@@ -239,12 +279,14 @@ export function buildMeshActiveWork(opts: BuildMeshActiveWorkOptions): { activeW
             const status: MeshActiveWorkStatus = isTerminal
                 ? (dbStatus === 'completed' ? 'idle' : 'failed')
                 : live.status || (dbStatus === 'acked' ? 'generating' : 'assigned');
-            const isNoTransition = !isTerminal && !live.status;
-            const isIdleUnacknowledged = status === 'idle' && !isTerminal;
-            const ledgerOnlyStaleReason = !isTerminal && (isIdleUnacknowledged || isNoTransition || (dispatch.dispatchedToIdleSession && isIdleUnacknowledged))
-                ? 'direct task dispatch has no provider acknowledgement, transcript append, or active runtime transition'
-                : undefined;
-            const isFreshUnacknowledged = Boolean(ledgerOnlyStaleReason && !live.staleReason);
+            const { ledgerOnlyStaleReason, isFreshUnacknowledged } = classifyDirectDispatch({
+                status,
+                isTerminalRow: isTerminal,
+                hasTerminalStatus: isTerminal,
+                liveStatus: live.status,
+                liveStaleReason: live.staleReason,
+                dispatchedToIdleSession: dispatch.dispatchedToIdleSession === true,
+            });
             const { title, summary } = summarizeMessage(dispatch.message || '');
             const record: MeshActiveWorkRecord = {
                 taskId: dispatch.taskId,
@@ -291,15 +333,16 @@ export function buildMeshActiveWork(opts: BuildMeshActiveWorkOptions): { activeW
             const live = sessionStatusFromNodes(opts.nodes, dispatch.nodeId, dispatch.sessionId);
             const status = terminalStatus || live.status || 'assigned';
             const terminalRow = Boolean(terminal && terminal.kind !== 'task_approval_needed');
-            const dispatchedToIdleSession = dispatch.payload?.dispatchedToIdleSession === true;
-            const isNoTransition = !terminalStatus && !live.status;
-            const isIdleUnacknowledged = status === 'idle';
-            const ledgerOnlyStaleReason = !terminalRow && (isIdleUnacknowledged || isNoTransition || (dispatchedToIdleSession && isIdleUnacknowledged))
-                ? 'direct task dispatch has no provider acknowledgement, transcript append, or active runtime transition'
-                : undefined;
+            const { ledgerOnlyStaleReason, isFreshUnacknowledged } = classifyDirectDispatch({
+                status,
+                isTerminalRow: terminalRow,
+                hasTerminalStatus: Boolean(terminalStatus),
+                liveStatus: live.status,
+                liveStaleReason: live.staleReason,
+                dispatchedToIdleSession: dispatch.payload?.dispatchedToIdleSession === true,
+            });
             const message = readString(dispatch.payload?.message) || readString(dispatch.payload?.summary) || '';
             const { title, summary } = summarizeMessage(message);
-            const isFreshUnacknowledged = Boolean(ledgerOnlyStaleReason && !live.staleReason);
             const record: MeshActiveWorkRecord = {
                 taskId,
                 source: 'direct',
@@ -344,15 +387,16 @@ export function buildMeshActiveWork(opts: BuildMeshActiveWorkOptions): { activeW
             const live = sessionStatusFromNodes(opts.nodes, dispatch.nodeId, dispatch.sessionId);
             const status = terminalStatus || live.status || 'assigned';
             const terminalRow = Boolean(terminal && terminal.kind !== 'task_approval_needed');
-            const dispatchedToIdleSession = dispatch.payload?.dispatchedToIdleSession === true;
-            const isNoTransition = !terminalStatus && !live.status;
-            const isIdleUnacknowledged = status === 'idle';
-            const ledgerOnlyStaleReason = !terminalRow && (isIdleUnacknowledged || isNoTransition || (dispatchedToIdleSession && isIdleUnacknowledged))
-                ? 'direct task dispatch has no provider acknowledgement, transcript append, or active runtime transition'
-                : undefined;
+            const { ledgerOnlyStaleReason, isFreshUnacknowledged } = classifyDirectDispatch({
+                status,
+                isTerminalRow: terminalRow,
+                hasTerminalStatus: Boolean(terminalStatus),
+                liveStatus: live.status,
+                liveStaleReason: live.staleReason,
+                dispatchedToIdleSession: dispatch.payload?.dispatchedToIdleSession === true,
+            });
             const message = readString(dispatch.payload?.message) || readString(dispatch.payload?.summary) || '';
             const { title, summary } = summarizeMessage(message);
-            const isFreshUnacknowledged = Boolean(ledgerOnlyStaleReason && !live.staleReason);
             const record: MeshActiveWorkRecord = {
                 taskId,
                 source: 'direct',