@adhdev/daemon-core 0.9.82-rc.196 → 0.9.82-rc.198

package/dist/mesh/mesh-delivery-policy.d.ts

@@ -0,0 +1,126 @@
+/**
+ * Possible delivery statuses for a session delivery record.
+ */
+export type MeshSessionDeliveryStatus = 'queued' | 'delivering' | 'delivered' | 'acked' | 'completed' | 'failed' | 'expired' | 'cancelled';
+/**
+ * Kind of delivery — controls priority and policy handling.
+ */
+export type MeshSessionDeliveryKind = 'task' | 'followup' | 'approval' | 'recovery' | 'system_notice';
+/**
+ * A session delivery decision — what to do when a task arrives for a session.
+ */
+export type MeshDeliveryDecision = 'immediate' | 'queued' | 'rejected';
+export interface MeshDeliveryPolicyResult {
+    decision: MeshDeliveryDecision;
+    reason: string;
+    /** When decision='queued', estimated deliver-after ISO timestamp if known. */
+    deliverAfter?: string;
+    /** Human-readable explanation for coordinator/operator. */
+    message: string;
+}
+/**
+ * Determine whether to deliver immediately, queue, or reject based on session status.
+ *
+ * This is a pure function — it does not write to any store.
+ */
+export declare function resolveDeliveryDecision(sessionStatus: string | undefined, opts?: {
+    kind?: MeshSessionDeliveryKind;
+    /** When true, busy session immediate injection is allowed (provider-specific capability). */
+    allowBusyInjection?: boolean;
+}): MeshDeliveryPolicyResult;
+export interface SessionDeliveryRecord {
+    id: string;
+    meshId: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    kind: MeshSessionDeliveryKind;
+    priority: number;
+    message: string;
+    status: MeshSessionDeliveryStatus;
+    deliverAfter?: string;
+    expiresAt?: string;
+    attemptCount: number;
+    sourceCoordinatorSessionId?: string;
+    sourceCoordinatorDaemonId?: string;
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+/**
+ * Create a delivery record in the store.
+ */
+export declare function createSessionDelivery(opts: {
+    meshId: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    kind: MeshSessionDeliveryKind;
+    message: string;
+    status: MeshSessionDeliveryStatus;
+    priority?: number;
+    deliverAfter?: string;
+    expiresAt?: string;
+    sourceCoordinatorSessionId?: string;
+    sourceCoordinatorDaemonId?: string;
+}): SessionDeliveryRecord;
+/**
+ * Update the status of a delivery record.
+ */
+export declare function updateSessionDeliveryStatus(id: string, status: MeshSessionDeliveryStatus, opts?: {
+    lastError?: string;
+    incrementAttempt?: boolean;
+}): void;
+/**
+ * Get active (non-terminal) deliveries for a mesh, optionally filtered by session.
+ */
+export declare function getActiveSessionDeliveries(meshId: string, sessionId?: string): {
+    id: string;
+    meshId: string;
+    nodeId: string | null;
+    sessionId: string | null;
+    providerType: string | null;
+    taskId: string | null;
+    kind: string;
+    priority: number;
+    message: string;
+    status: string;
+    deliverAfter: string | null;
+    expiresAt: string | null;
+    attemptCount: number;
+    sourceCoordinatorSessionId: string | null;
+    sourceCoordinatorDaemonId: string | null;
+    lastError: string | null;
+    createdAt: string;
+    updatedAt: string;
+}[];
+/**
+ * Record a completion conflict diagnostic when a duplicate event points to
+ * different task/session than the already-seen event with the same fingerprint.
+ */
+export declare function recordCompletionConflict(opts: {
+    meshId: string;
+    fingerprint: string;
+    conflictingTaskId?: string;
+    conflictingSessionId?: string;
+    originalTaskId?: string;
+    originalSessionId?: string;
+    event: string;
+}): void;
+/**
+ * Get recent completion conflicts for diagnostic inspection.
+ */
+export declare function getRecentCompletionConflicts(meshId: string, limitMs?: number): {
+    id: string;
+    meshId: string;
+    fingerprint: string;
+    conflictingTaskId: string | null;
+    conflictingSessionId: string | null;
+    originalTaskId: string | null;
+    originalSessionId: string | null;
+    event: string;
+    createdAt: string;
+}[];
+export declare function __clearSessionDeliveriesForTests(meshId: string): void;

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

@@ -80,4 +80,70 @@ export declare class MeshRuntimeStore {
     }>;
     deleteRemoteIdleSession(nodeId: string, sessionId: string): void;
     pruneExpiredRemoteIdleSessions(): void;
+    insertSessionDelivery(entry: {
+        id: string;
+        meshId: string;
+        nodeId?: string;
+        sessionId?: string;
+        providerType?: string;
+        taskId?: string;
+        kind: string;
+        priority?: number;
+        message: string;
+        status: string;
+        deliverAfter?: string;
+        expiresAt?: string;
+        sourceCoordinatorSessionId?: string;
+        sourceCoordinatorDaemonId?: string;
+        createdAt: string;
+        updatedAt: string;
+    }): void;
+    updateSessionDeliveryStatus(id: string, status: string, opts?: {
+        lastError?: string;
+        incrementAttempt?: boolean;
+    }): void;
+    getActiveSessionDeliveries(meshId: string, sessionId?: string): Array<{
+        id: string;
+        meshId: string;
+        nodeId: string | null;
+        sessionId: string | null;
+        providerType: string | null;
+        taskId: string | null;
+        kind: string;
+        priority: number;
+        message: string;
+        status: string;
+        deliverAfter: string | null;
+        expiresAt: string | null;
+        attemptCount: number;
+        sourceCoordinatorSessionId: string | null;
+        sourceCoordinatorDaemonId: string | null;
+        lastError: string | null;
+        createdAt: string;
+        updatedAt: string;
+    }>;
+    expireStaleSessionDeliveries(meshId: string): void;
+    deleteSessionDeliveries(meshId: string): void;
+    recordCompletionConflict(entry: {
+        id: string;
+        meshId: string;
+        fingerprint: string;
+        conflictingTaskId?: string;
+        conflictingSessionId?: string;
+        originalTaskId?: string;
+        originalSessionId?: string;
+        event: string;
+        createdAt: string;
+    }): void;
+    getRecentCompletionConflicts(meshId: string, limitMs?: number): Array<{
+        id: string;
+        meshId: string;
+        fingerprint: string;
+        conflictingTaskId: string | null;
+        conflictingSessionId: string | null;
+        originalTaskId: string | null;
+        originalSessionId: string | null;
+        event: string;
+        createdAt: string;
+    }>;
 }

package/dist/providers/spec/driver.d.ts

@@ -135,7 +135,15 @@ export declare class SpecDriver {
      *  explicit wake-up there's nothing to trigger the busy → idle
      *  downshift. */
     private busyExpiryTimer;
+    /** Pending idle-commit timer. Armed when the evaluator first returns idle;
+     *  fires after idle_hold_ms if no non-idle reading has cancelled it. */
+    private idleHoldTimer;
+    /** State snapshot captured when the idle hold was armed — emitted on commit. */
+    private pendingIdleState;
     private specWatcher;
+    /** Ring buffer of committed state transitions (max 50). */
+    private stateHistory;
+    private prevStateAt;
     constructor(opts: SpecDriverOpts);
     /** Subscribe to outbound events. Returns an unsubscribe fn. */
     subscribe(listener: (ev: DashboardEvent) => void): () => void;
@@ -147,6 +155,17 @@ export declare class SpecDriver {
         col: number;
     };
     shutdown(): void;
+    private cancelIdleHold;
+    private pushHistory;
+    getStateHistory(): ReadonlyArray<{
+        stateId: string;
+        label: string;
+        at: number;
+        durationMs: number;
+    }>;
+    getLastBusyAt(): number;
+    hasIdleHoldPending(): boolean;
+    getSpecPath(): string;
     private loadSpecOrThrow;
     private buildAdapterOpts;
     private armSpecWatcher;

package/dist/providers/spec/types.d.ts

@@ -249,6 +249,12 @@ export interface CliSpec {
          *  Absorbs per-frame flicker in TUIs that stream output through
          *  the same region as the spinner. */
         busy_hold_ms?: number;
+        /** Min time the idle state must remain matched before it is
+         *  committed. Filters transient idle flickers that appear during
+         *  approval dismissals, layout reflows, or brief spinner gaps.
+         *  Any non-idle reading within the window cancels the transition.
+         *  When omitted the idle transition is immediate (legacy behaviour). */
+        idle_hold_ms?: number;
         /** Min time after start() before a send_message is allowed to
          *  reach the PTY. Banner paints + auth flows + skill listings
          *  can keep the agent unable to accept input for several seconds

package/package.json

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

package/src/commands/router.ts

@@ -4178,6 +4178,25 @@ export class DaemonCommandRouter {
                 };
             }
 
+            case 'get_spec_debug': {
+                const sessionId = typeof args?.targetSessionId === 'string' ? args.targetSessionId.trim()
+                    : typeof args?.sessionId === 'string' ? args.sessionId.trim() : '';
+                if (!sessionId) return { success: false, error: 'targetSessionId required' };
+                const target = this.deps.sessionRegistry.get(sessionId);
+                if (!target) return { success: false, error: 'Session not found', sessionId };
+                const adapter = this.deps.cliManager.findAdapter(target.providerType, { instanceKey: sessionId })?.adapter;
+                const snapshot = (adapter && typeof (adapter as any).getDebugSnapshot === 'function')
+                    ? (adapter as any).getDebugSnapshot()
+                    : null;
+                return {
+                    success: true,
+                    sessionId,
+                    providerType: target.providerType,
+                    isSpecProvider: snapshot !== null,
+                    snapshot,
+                };
+            }
+
             // ── User-level coordinator-prompt files (~/.adhdev/coordinator-prompts/).
             //    These live on this daemon's filesystem and never sync to the
             //    cloud / other daemons — they're per-machine config. The

package/src/index.ts

@@ -232,6 +232,10 @@ export { buildMeshHostRequiredFailure, createDefaultMeshHostMetadata, isMeshHost
 export { triggerMeshQueue, drainPendingMeshCoordinatorEvents, getPendingMeshCoordinatorEvents, clearPendingMeshCoordinatorEvents, queuePendingMeshCoordinatorEvent, reconcileDirectDispatchCompletionFromTranscript } from './mesh/mesh-events.js';
 export type { PendingMeshCoordinatorEvent } from './mesh/mesh-events.js';
 
+// ── Mesh Delivery Policy ──
+export { resolveDeliveryDecision, createSessionDelivery, updateSessionDeliveryStatus, getActiveSessionDeliveries, recordCompletionConflict, getRecentCompletionConflicts } from './mesh/mesh-delivery-policy.js';
+export type { MeshSessionDeliveryStatus, MeshSessionDeliveryKind, MeshDeliveryDecision, MeshDeliveryPolicyResult, SessionDeliveryRecord } from './mesh/mesh-delivery-policy.js';
+
 // ── Mesh P2P Relay Failure Classification ──
 export {
   P2pRelayFailureError,

package/src/mesh/mesh-delivery-policy.ts

@@ -0,0 +1,298 @@
+import { randomUUID } from 'crypto';
+import { MeshRuntimeStore } from './mesh-runtime-store.js';
+
+/**
+ * Possible delivery statuses for a session delivery record.
+ */
+export type MeshSessionDeliveryStatus =
+    | 'queued'
+    | 'delivering'
+    | 'delivered'
+    | 'acked'
+    | 'completed'
+    | 'failed'
+    | 'expired'
+    | 'cancelled';
+
+/**
+ * Kind of delivery — controls priority and policy handling.
+ */
+export type MeshSessionDeliveryKind =
+    | 'task'
+    | 'followup'
+    | 'approval'
+    | 'recovery'
+    | 'system_notice';
+
+/**
+ * A session delivery decision — what to do when a task arrives for a session.
+ */
+export type MeshDeliveryDecision =
+    | 'immediate'     // Session is idle: deliver now, create an 'acked' delivery record
+    | 'queued'        // Session is busy: hold delivery until session becomes idle
+    | 'rejected';     // Session is terminal or unknown: cannot deliver
+
+export interface MeshDeliveryPolicyResult {
+    decision: MeshDeliveryDecision;
+    reason: string;
+    /** When decision='queued', estimated deliver-after ISO timestamp if known. */
+    deliverAfter?: string;
+    /** Human-readable explanation for coordinator/operator. */
+    message: string;
+}
+
+/**
+ * Session statuses where immediate delivery is allowed.
+ * The session is ready to accept new work.
+ */
+const IMMEDIATE_DELIVERY_STATUSES = new Set([
+    'idle',
+    'waiting_input',
+    'ready',
+]);
+
+/**
+ * Session statuses that indicate the session is busy but still alive.
+ * Delivery is queued rather than attempted immediately.
+ */
+const BUSY_DELIVERY_STATUSES = new Set([
+    'generating',
+    'running',
+    'streaming',
+    'busy',
+    'starting',
+    'initializing',
+    'waiting_approval',
+]);
+
+/**
+ * Session statuses that indicate the session is permanently unavailable.
+ * Delivery should be rejected.
+ */
+const TERMINAL_DELIVERY_STATUSES = new Set([
+    'stopped',
+    'failed',
+    'terminated',
+    'exited',
+    'closed',
+    'deleted',
+    'error',
+]);
+
+/**
+ * Determine whether to deliver immediately, queue, or reject based on session status.
+ *
+ * This is a pure function — it does not write to any store.
+ */
+export function resolveDeliveryDecision(
+    sessionStatus: string | undefined,
+    opts?: {
+        kind?: MeshSessionDeliveryKind;
+        /** When true, busy session immediate injection is allowed (provider-specific capability). */
+        allowBusyInjection?: boolean;
+    },
+): MeshDeliveryPolicyResult {
+    const status = (sessionStatus || '').trim().toLowerCase();
+
+    if (!status) {
+        return {
+            decision: 'rejected',
+            reason: 'unknown_session_status',
+            message: 'Session status is unknown. Delivery rejected (fail-closed). Use mesh_launch_session to start a fresh session.',
+        };
+    }
+
+    if (IMMEDIATE_DELIVERY_STATUSES.has(status)) {
+        return {
+            decision: 'immediate',
+            reason: `session_${status}`,
+            message: `Session is ${status} — delivery allowed immediately.`,
+        };
+    }
+
+    if (BUSY_DELIVERY_STATUSES.has(status)) {
+        if (opts?.allowBusyInjection) {
+            return {
+                decision: 'immediate',
+                reason: `session_${status}_busy_injection_allowed`,
+                message: `Session is ${status} but provider supports busy injection. Delivered immediately.`,
+            };
+        }
+        // approval-kind may be delivered to waiting_approval sessions
+        if (status === 'waiting_approval' && opts?.kind === 'approval') {
+            return {
+                decision: 'immediate',
+                reason: 'session_waiting_approval_approval_message',
+                message: 'Session is waiting for approval — approval message delivered immediately.',
+            };
+        }
+        return {
+            decision: 'queued',
+            reason: `session_${status}_busy`,
+            message: `Session is ${status}. Task queued for delivery when session becomes idle. Do not inject directly into a busy session.`,
+        };
+    }
+
+    if (TERMINAL_DELIVERY_STATUSES.has(status)) {
+        return {
+            decision: 'rejected',
+            reason: `session_${status}_terminal`,
+            message: `Session is ${status} (terminal). Delivery rejected. Launch a new session before dispatching tasks.`,
+        };
+    }
+
+    // Unknown/unrecognized status: fail-closed
+    return {
+        decision: 'rejected',
+        reason: 'unrecognized_session_status',
+        message: `Session status '${sessionStatus}' is not recognized. Delivery rejected (fail-closed). Inspect session state before retrying.`,
+    };
+}
+
+export interface SessionDeliveryRecord {
+    id: string;
+    meshId: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    kind: MeshSessionDeliveryKind;
+    priority: number;
+    message: string;
+    status: MeshSessionDeliveryStatus;
+    deliverAfter?: string;
+    expiresAt?: string;
+    attemptCount: number;
+    sourceCoordinatorSessionId?: string;
+    sourceCoordinatorDaemonId?: string;
+    lastError?: string;
+    createdAt: string;
+    updatedAt: string;
+}
+
+/**
+ * Create a delivery record in the store.
+ */
+export function createSessionDelivery(opts: {
+    meshId: string;
+    nodeId?: string;
+    sessionId?: string;
+    providerType?: string;
+    taskId?: string;
+    kind: MeshSessionDeliveryKind;
+    message: string;
+    status: MeshSessionDeliveryStatus;
+    priority?: number;
+    deliverAfter?: string;
+    expiresAt?: string;
+    sourceCoordinatorSessionId?: string;
+    sourceCoordinatorDaemonId?: string;
+}): SessionDeliveryRecord {
+    const now = new Date().toISOString();
+    const id = randomUUID();
+    const record: SessionDeliveryRecord = {
+        id,
+        meshId: opts.meshId,
+        nodeId: opts.nodeId,
+        sessionId: opts.sessionId,
+        providerType: opts.providerType,
+        taskId: opts.taskId,
+        kind: opts.kind,
+        priority: opts.priority ?? 0,
+        message: opts.message,
+        status: opts.status,
+        deliverAfter: opts.deliverAfter,
+        expiresAt: opts.expiresAt,
+        attemptCount: 0,
+        sourceCoordinatorSessionId: opts.sourceCoordinatorSessionId,
+        sourceCoordinatorDaemonId: opts.sourceCoordinatorDaemonId,
+        createdAt: now,
+        updatedAt: now,
+    };
+    MeshRuntimeStore.getInstance().insertSessionDelivery({
+        id,
+        meshId: opts.meshId,
+        nodeId: opts.nodeId,
+        sessionId: opts.sessionId,
+        providerType: opts.providerType,
+        taskId: opts.taskId,
+        kind: opts.kind,
+        priority: opts.priority ?? 0,
+        message: opts.message,
+        status: opts.status,
+        deliverAfter: opts.deliverAfter,
+        expiresAt: opts.expiresAt,
+        sourceCoordinatorSessionId: opts.sourceCoordinatorSessionId,
+        sourceCoordinatorDaemonId: opts.sourceCoordinatorDaemonId,
+        createdAt: now,
+        updatedAt: now,
+    });
+    return record;
+}
+
+/**
+ * Update the status of a delivery record.
+ */
+export function updateSessionDeliveryStatus(
+    id: string,
+    status: MeshSessionDeliveryStatus,
+    opts?: { lastError?: string; incrementAttempt?: boolean },
+): void {
+    try {
+        MeshRuntimeStore.getInstance().updateSessionDeliveryStatus(id, status, opts);
+    } catch { /* best-effort */ }
+}
+
+/**
+ * Get active (non-terminal) deliveries for a mesh, optionally filtered by session.
+ */
+export function getActiveSessionDeliveries(meshId: string, sessionId?: string) {
+    try {
+        return MeshRuntimeStore.getInstance().getActiveSessionDeliveries(meshId, sessionId);
+    } catch {
+        return [];
+    }
+}
+
+/**
+ * Record a completion conflict diagnostic when a duplicate event points to
+ * different task/session than the already-seen event with the same fingerprint.
+ */
+export function recordCompletionConflict(opts: {
+    meshId: string;
+    fingerprint: string;
+    conflictingTaskId?: string;
+    conflictingSessionId?: string;
+    originalTaskId?: string;
+    originalSessionId?: string;
+    event: string;
+}): void {
+    try {
+        MeshRuntimeStore.getInstance().recordCompletionConflict({
+            id: randomUUID(),
+            meshId: opts.meshId,
+            fingerprint: opts.fingerprint,
+            conflictingTaskId: opts.conflictingTaskId,
+            conflictingSessionId: opts.conflictingSessionId,
+            originalTaskId: opts.originalTaskId,
+            originalSessionId: opts.originalSessionId,
+            event: opts.event,
+            createdAt: new Date().toISOString(),
+        });
+    } catch { /* best-effort diagnostics */ }
+}
+
+/**
+ * Get recent completion conflicts for diagnostic inspection.
+ */
+export function getRecentCompletionConflicts(meshId: string, limitMs?: number) {
+    try {
+        return MeshRuntimeStore.getInstance().getRecentCompletionConflicts(meshId, limitMs);
+    } catch {
+        return [];
+    }
+}
+
+export function __clearSessionDeliveriesForTests(meshId: string): void {
+    MeshRuntimeStore.getInstance().deleteSessionDeliveries(meshId);
+}