@hotmeshio/long-tail 0.5.10 → 0.5.11

package/build/api/controlplane.d.ts

@@ -99,4 +99,5 @@ export declare function listStreamMessages(input: {
     workflow_name?: string | null;
     jid?: string | null;
     aid?: string | null;
+    dad?: string | null;
 }): Promise<LTApiResult>;

package/build/api/controlplane.js

@@ -196,6 +196,7 @@ async function listStreamMessages(input) {
             workflow_name: input.workflow_name,
             jid: input.jid,
             aid: input.aid,
+            dad: input.dad,
         });
         return { status: 200, data: result };
     }

package/build/api/diagnostics.d.ts

@@ -2,14 +2,16 @@ import type { LTApiResult } from '../types/sdk';
 export declare function diagnose(input: {
     workflowId: string;
     appId?: string;
+    maxEvents?: number;
 }): Promise<LTApiResult>;
 export declare function stalledJobs(input: {
     appId?: string;
-    stalledMinutes?: number;
+    idleMinutes?: number;
     workflowType?: string;
     limit?: number;
 }): Promise<LTApiResult>;
 export declare function orphanedSignals(input: {
     appId?: string;
+    withinHours?: number;
     limit?: number;
 }): Promise<LTApiResult>;

package/build/api/diagnostics.js

@@ -6,7 +6,7 @@ exports.orphanedSignals = orphanedSignals;
 const diagnostics_1 = require("../services/diagnostics");
 async function diagnose(input) {
     try {
-        const diagnosis = await (0, diagnostics_1.diagnoseJob)(input.workflowId, input.appId);
+        const diagnosis = await (0, diagnostics_1.diagnoseJob)(input.workflowId, input.appId, { maxEvents: input.maxEvents });
         return { status: 200, data: diagnosis };
     }
     catch (err) {

package/build/api/settings.d.ts

@@ -4,9 +4,10 @@ import type { LTApiResult } from '../types/sdk';
  * Return platform settings for the current deployment.
  *
  * Includes telemetry configuration (trace URL), escalation claim duration
- * options, and event transport details (socket.io, NATS, or none).
+ * options, event transport details (socket.io, NATS, or none), and an
+ * environment block (long-tail + HotMesh versions, Node env/version).
  *
  * @param req — the incoming HTTP request, used to derive NATS WS URL from headers when proxying
- * @returns `{ status: 200, data: { telemetry, escalation, events } }`
+ * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, environment } }`
  */
 export declare function getSettings(req?: IncomingMessage): Promise<LTApiResult>;

package/build/api/settings.js

@@ -7,6 +7,7 @@ const nats_1 = require("../lib/events/nats");
 const socketio_1 = require("../lib/events/socketio");
 const nats_ws_proxy_1 = require("../lib/events/nats-ws-proxy");
 const config_1 = require("../modules/config");
+const version_1 = require("../modules/version");
 const sso_1 = require("../modules/sso");
 const defaults_1 = require("../modules/defaults");
 const llm_1 = require("../services/llm");
@@ -33,10 +34,11 @@ function resolveNatsWsUrl(adapter, req) {
  * Return platform settings for the current deployment.
  *
  * Includes telemetry configuration (trace URL), escalation claim duration
- * options, and event transport details (socket.io, NATS, or none).
+ * options, event transport details (socket.io, NATS, or none), and an
+ * environment block (long-tail + HotMesh versions, Node env/version).
  *
  * @param req — the incoming HTTP request, used to derive NATS WS URL from headers when proxying
- * @returns `{ status: 200, data: { telemetry, escalation, events } }`
+ * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, environment } }`
  */
 async function getSettings(req) {
     try {
@@ -68,6 +70,13 @@ async function getSettings(req) {
                 ai: {
                     enabled: (0, llm_1.hasLLMApiKey)(),
                 },
+                environment: {
+                    longTailVersion: version_1.LONG_TAIL_VERSION,
+                    hotmeshVersion: version_1.HOTMESH_VERSION,
+                    nodeEnv: config_1.config.NODE_ENV,
+                    nodeVersion: process.version,
+                    eventTransport: transport,
+                },
             },
         };
     }

package/build/modules/version.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Runtime version constants for the environment block surfaced by /api/settings.
+ *
+ * The HotMesh SDK version is read from its package.json — node module
+ * resolution finds it in both dev (source) and prod (the runtime image's
+ * node_modules), and resolveJsonModule handles the static import at compile time.
+ */
+export declare const HOTMESH_VERSION: string;
+/**
+ * The long-tail app version. Read from the root package.json at runtime via the
+ * process working directory (which is the app root in both dev and the Docker
+ * image, where CMD runs `node build/index.js` from /app). A static
+ * `../package.json` import would resolve to build/package.json after compile —
+ * a path the Dockerfile does not copy — so this reads from cwd instead.
+ */
+export declare const LONG_TAIL_VERSION: string;

package/build/modules/version.js

@@ -0,0 +1,34 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LONG_TAIL_VERSION = exports.HOTMESH_VERSION = void 0;
+const fs_1 = require("fs");
+const path_1 = require("path");
+const package_json_1 = __importDefault(require("@hotmeshio/hotmesh/package.json"));
+/**
+ * Runtime version constants for the environment block surfaced by /api/settings.
+ *
+ * The HotMesh SDK version is read from its package.json — node module
+ * resolution finds it in both dev (source) and prod (the runtime image's
+ * node_modules), and resolveJsonModule handles the static import at compile time.
+ */
+exports.HOTMESH_VERSION = package_json_1.default.version ?? 'unknown';
+/**
+ * The long-tail app version. Read from the root package.json at runtime via the
+ * process working directory (which is the app root in both dev and the Docker
+ * image, where CMD runs `node build/index.js` from /app). A static
+ * `../package.json` import would resolve to build/package.json after compile —
+ * a path the Dockerfile does not copy — so this reads from cwd instead.
+ */
+exports.LONG_TAIL_VERSION = readLongTailVersion();
+function readLongTailVersion() {
+    try {
+        const raw = (0, fs_1.readFileSync)((0, path_1.resolve)(process.cwd(), 'package.json'), 'utf8');
+        return JSON.parse(raw).version ?? 'unknown';
+    }
+    catch {
+        return 'unknown';
+    }
+}

package/build/routes/controlplane.js

@@ -123,6 +123,7 @@ router.get('/stream-messages', auth_1.requireBuilder, async (req, res) => {
         workflow_name: req.query.workflow_name || undefined,
         jid: req.query.jid || undefined,
         aid: req.query.aid || undefined,
+        dad: req.query.dad || undefined,
     });
     res.status(result.status).json(result.data ?? { error: result.error });
 });

package/build/routes/diagnostics.js

@@ -42,29 +42,33 @@ const router = (0, express_1.Router)();
  * Full diagnosis for a single workflow job.
  *
  * Query params:
- *   app_id — HotMesh namespace (default: durable)
+ *   app_id     — HotMesh namespace (default: durable)
+ *   max_events — cap on events returned (most recent kept; default: 500)
  */
 router.get('/jobs/:workflowId', auth_1.requireAdmin, async (req, res) => {
     const result = await api.diagnose({
         workflowId: req.params.workflowId,
         appId: typeof req.query.app_id === 'string' ? req.query.app_id : undefined,
+        maxEvents: req.query.max_events ? Number(req.query.max_events) : undefined,
     });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 /**
  * GET /api/diagnostics/stalled
- * Running jobs with no recent progress.
+ * Running jobs with no recent status change. A frozen updated_at is the NORMAL
+ * signature of a workflow waiting at a condition()/waitFor()/sleepFor() — each
+ * row is classified `likely: waiting | no_recent_progress` accordingly.
  *
  * Query params:
- *   app_id          — HotMesh namespace (default: durable)
- *   stalled_minutes — minimum minutes since last event (default: 5)
- *   workflow_type   — filter by workflow function name
- *   limit           — max results (default: 50, max: 200)
+ *   app_id        — HotMesh namespace (default: durable)
+ *   idle_minutes  — minimum minutes since last status change (default: 5)
+ *   workflow_type — filter by workflow function name
+ *   limit         — max results (default: 50, max: 200)
  */
 router.get('/stalled', auth_1.requireAdmin, async (req, res) => {
     const result = await api.stalledJobs({
         appId: typeof req.query.app_id === 'string' ? req.query.app_id : undefined,
-        stalledMinutes: req.query.stalled_minutes ? Number(req.query.stalled_minutes) : undefined,
+        idleMinutes: req.query.idle_minutes ? Number(req.query.idle_minutes) : undefined,
         workflowType: typeof req.query.workflow_type === 'string' ? req.query.workflow_type : undefined,
         limit: req.query.limit ? Number(req.query.limit) : undefined,
     });
@@ -72,15 +76,19 @@ router.get('/stalled', auth_1.requireAdmin, async (req, res) => {
 });
 /**
  * GET /api/diagnostics/orphaned-signals
- * Suspended jobs with no escalation row.
+ * Suspended waiters with no escalation row, within a recent time window. The
+ * window keeps this off a full-history scan of the partitioned worker_streams
+ * table — widen `within_hours` deliberately to reach older orphans.
  *
  * Query params:
- *   app_id — HotMesh namespace (default: durable)
- *   limit  — max results (default: 100, max: 500)
+ *   app_id       — HotMesh namespace (default: durable)
+ *   within_hours — recent window to scan (default: 24, max: 720)
+ *   limit        — max results (default: 100, max: 500)
  */
 router.get('/orphaned-signals', auth_1.requireAdmin, async (req, res) => {
     const result = await api.orphanedSignals({
         appId: typeof req.query.app_id === 'string' ? req.query.app_id : undefined,
+        withinHours: req.query.within_hours ? Number(req.query.within_hours) : undefined,
         limit: req.query.limit ? Number(req.query.limit) : undefined,
     });
     res.status(result.status).json(result.data ?? { error: result.error });

package/build/services/controlplane/index.js

@@ -129,9 +129,10 @@ async function getStreamMessages(schema, params) {
     const workflowName = params.workflow_name ?? null;
     const jid = params.jid ?? null;
     const aid = params.aid ?? null;
+    const dad = params.dad ?? null;
     const pool = (0, db_1.getPool)();
-    const queryParams = [streamName, status, msgType, topic, workflowName, jid, aid, limit, offset];
-    const countParams = [streamName, status, msgType, topic, workflowName, jid, aid];
+    const queryParams = [streamName, status, msgType, topic, workflowName, jid, aid, dad, limit, offset];
+    const countParams = [streamName, status, msgType, topic, workflowName, jid, aid, dad];
     const [messagesRes, countRes] = await Promise.all([
         pool.query((0, stream_messages_sql_1.LIST_STREAM_MESSAGES)(schema, sortColumn, sortOrder, source), queryParams).catch(() => ({ rows: [] })),
         pool.query((0, stream_messages_sql_1.COUNT_STREAM_MESSAGES)(schema, source), countParams).catch(() => ({ rows: [{ count: 0 }] })),

package/build/services/controlplane/stream-messages-sql.d.ts

@@ -9,13 +9,14 @@ export declare const VALID_SORT_ORDERS: Set<string>;
  * with different schemas and must never be commingled in a single query.
  *
  * Parameters: $1 = stream_name, $2 = status, $3 = msg_type,
- *             $4 = topic, $5 = workflow_name, $6 = jid, $7 = aid,
- *             $8 = limit, $9 = offset
+ *             $4 = topic, $5 = workflow_name, $6 = jid, $7 = aid, $8 = dad,
+ *             $9 = limit, $10 = offset
  */
 export declare function LIST_STREAM_MESSAGES(schema: string, sortColumn: string, sortOrder: string, source: 'engine' | 'worker'): string;
 /**
  * Count stream messages matching the filter criteria.
  *
- * Parameters: $1 = stream_name, $2 = status, $3 = msg_type
+ * Parameters: $1 = stream_name, $2 = status, $3 = msg_type,
+ *             $4 = topic, $5 = workflow_name, $6 = jid, $7 = aid, $8 = dad
  */
 export declare function COUNT_STREAM_MESSAGES(schema: string, source: 'engine' | 'worker'): string;

package/build/services/controlplane/stream-messages-sql.js

@@ -42,8 +42,10 @@ const STATUS_CASE = `
  *   $5 = workflow_name filter (NULL = all, worker-only)
  *   $6 = jid filter (NULL = all, worker-only)
  *   $7 = aid filter (NULL = all, worker-only)
+ *   $8 = dad filter (NULL = all, worker-only — pins one execution dimension)
  */
-/** Engine WHERE: supports stream_name, status, and jid (v0.18.0). */
+/** Engine WHERE: supports stream_name, status, and jid (v0.18.0). engine_streams
+ * has no aid/dad columns, so $7/$8 are accepted but inert here. */
 const ENGINE_WHERE_CLAUSE = `
   WHERE ($1::text IS NULL OR stream_name ILIKE $1)
     AND ($2::text IS NULL OR ${STATUS_CASE} = $2)
@@ -51,7 +53,8 @@ const ENGINE_WHERE_CLAUSE = `
     AND ($4::text IS NULL)
     AND ($5::text IS NULL)
     AND ($6::text IS NULL OR jid = $6)
-    AND ($7::text IS NULL)`;
+    AND ($7::text IS NULL)
+    AND ($8::text IS NULL)`;
 const WORKER_WHERE_CLAUSE = `
   WHERE ($1::text IS NULL OR stream_name ILIKE $1)
     AND ($2::text IS NULL OR ${STATUS_CASE} = $2)
@@ -59,7 +62,8 @@ const WORKER_WHERE_CLAUSE = `
     AND ($4::text IS NULL OR topic = $4)
     AND ($5::text IS NULL OR workflow_name = $5)
     AND ($6::text IS NULL OR jid = $6)
-    AND ($7::text IS NULL OR aid = $7)`;
+    AND ($7::text IS NULL OR aid = $7)
+    AND ($8::text IS NULL OR dad = $8)`;
 /**
  * List stream messages with pagination, filtering, and sorting.
  *
@@ -67,8 +71,8 @@ const WORKER_WHERE_CLAUSE = `
  * with different schemas and must never be commingled in a single query.
  *
  * Parameters: $1 = stream_name, $2 = status, $3 = msg_type,
- *             $4 = topic, $5 = workflow_name, $6 = jid, $7 = aid,
- *             $8 = limit, $9 = offset
+ *             $4 = topic, $5 = workflow_name, $6 = jid, $7 = aid, $8 = dad,
+ *             $9 = limit, $10 = offset
  */
 function LIST_STREAM_MESSAGES(schema, sortColumn, sortOrder, source) {
     const select = source === 'engine'
@@ -94,12 +98,13 @@ function LIST_STREAM_MESSAGES(schema, sortColumn, sortOrder, source) {
     return `
     SELECT * FROM (${select}) AS q
     ORDER BY ${sortColumn} ${sortOrder}, id DESC
-    LIMIT $8::int OFFSET $9::int`;
+    LIMIT $9::int OFFSET $10::int`;
 }
 /**
  * Count stream messages matching the filter criteria.
  *
- * Parameters: $1 = stream_name, $2 = status, $3 = msg_type
+ * Parameters: $1 = stream_name, $2 = status, $3 = msg_type,
+ *             $4 = topic, $5 = workflow_name, $6 = jid, $7 = aid, $8 = dad
  */
 function COUNT_STREAM_MESSAGES(schema, source) {
     const table = source === 'engine' ? 'engine_streams' : 'worker_streams';

package/build/services/controlplane/types.d.ts

@@ -51,6 +51,8 @@ export interface StreamMessagesParams {
     workflow_name?: string | null;
     jid?: string | null;
     aid?: string | null;
+    /** Dimension/ancestor path (worker-only) — pins one execution among siblings sharing an aid. */
+    dad?: string | null;
 }
 export interface StreamMessagesResult {
     messages: StreamMessage[];

package/build/services/diagnostics/index.d.ts

@@ -21,22 +21,32 @@ export interface JobDiagnosis {
     workflow_id: string;
     app_id: string;
     status: 'running' | 'completed' | 'failed' | 'not_found';
-    stalled_for_ms: number | null;
+    /**
+     * Milliseconds since the last execution event. NOT a fault signal on its own —
+     * a workflow can sit at a condition()/waitFor()/sleepFor() for days legitimately.
+     * Read `findings` for the actual interpretation.
+     */
+    idle_for_ms: number | null;
     workflow_type: string | null;
     last_event_at: string | null;
     stream_summary: StreamSummary;
     escalation: EscalationSummary;
     findings: Finding[];
     execution_events: unknown[];
+    /** Total events before any cap was applied (execution_events may be truncated to the most recent `maxEvents`). */
+    total_events: number;
+    events_truncated: boolean;
     stream_messages: {
         worker: StreamMessage[];
         engine: StreamMessage[];
     };
 }
-export declare function diagnoseJob(workflowId: string, appId?: string): Promise<JobDiagnosis>;
+export declare function diagnoseJob(workflowId: string, appId?: string, options?: {
+    maxEvents?: number;
+}): Promise<JobDiagnosis>;
 export declare function findStalledJobs(params: {
     appId?: string;
-    stalledMinutes?: number;
+    idleMinutes?: number;
     workflowType?: string | null;
     limit?: number;
 }): Promise<{
@@ -45,8 +55,10 @@ export declare function findStalledJobs(params: {
 }>;
 export declare function findOrphanedSignals(params: {
     appId?: string;
+    withinHours?: number;
     limit?: number;
 }): Promise<{
     orphans: unknown[];
     total: number;
+    within_hours: number;
 }>;

package/build/services/diagnostics/index.js

@@ -15,34 +15,56 @@ const ESCALATION_BY_JOB = `
   WHERE workflow_id = $1
   ORDER BY created_at DESC LIMIT 5
 `;
+// "No recent status change" is NOT the same as "broken": HotMesh only bumps
+// jobs.updated_at when status changes, so a frozen updated_at is the normal
+// signature of a workflow waiting at a condition()/waitFor()/sleepFor(). We
+// classify each row with `has_open_escalation` (a cheap, workflow_id-indexed
+// EXISTS bounded by the outer LIMIT) so callers can tell a healthy wait
+// (`likely = waiting`) from a candidate worth a closer look (`no_recent_progress`).
 const STALLED_JOBS = (appId) => `
   SELECT
-    REPLACE(j.key, $1, '') AS workflow_id,
-    j.entity               AS workflow_type,
-    j.status,
-    j.created_at,
-    j.updated_at,
-    EXTRACT(EPOCH FROM (NOW() - j.updated_at)) * 1000 AS stalled_ms
-  FROM "${appId}".jobs j
-  WHERE j.status > 0
-    AND j.is_live = TRUE
-    AND j.updated_at < NOW() - ($2 || ' minutes')::INTERVAL
-    AND ($3::text IS NULL OR j.entity = $3)
-  ORDER BY j.updated_at ASC
-  LIMIT $4
+    q.*,
+    CASE WHEN q.has_open_escalation THEN 'waiting' ELSE 'no_recent_progress' END AS likely
+  FROM (
+    SELECT
+      REPLACE(j.key, $1, '') AS workflow_id,
+      j.entity               AS workflow_type,
+      j.status,
+      j.created_at,
+      j.updated_at,
+      EXTRACT(EPOCH FROM (NOW() - j.updated_at)) * 1000 AS idle_ms,
+      EXISTS (
+        SELECT 1 FROM public.hmsh_escalations e
+        WHERE e.workflow_id = REPLACE(j.key, $1, '') AND e.status = 'pending'
+      ) AS has_open_escalation
+    FROM "${appId}".jobs j
+    WHERE j.status > 0
+      AND j.is_live = TRUE
+      AND j.updated_at < NOW() - ($2 || ' minutes')::INTERVAL
+      AND ($3::text IS NULL OR j.entity = $3)
+    ORDER BY j.updated_at ASC
+    LIMIT $4
+  ) q
 `;
+// Bounded by a recent-time window ($1 = within_hours) so this never degenerates
+// into a full-history scan of the HASH-partitioned worker_streams table. The
+// `aid LIKE '%/waiter'` predicate is a suffix wildcard (not index-backed), so
+// the time window is what keeps the intermediate scan small; widening it trades
+// cost for reach. The NOT EXISTS anti-join on hmsh_escalations (workflow_id
+// indexed) is the high-value signal — a suspended waiter with no escalation row.
 const ORPHANED_SIGNALS = (appId) => `
   WITH committed_waiters AS (
     SELECT
-      ws.jid                                AS job_id,
-      ws.message->'data'->>'signalId'       AS signal_id,
-      ws.message->'data'->>'queueConfig'    AS queue_config,
+      ws.jid                                     AS job_id,
+      ws.message::jsonb->'data'->>'signalId'     AS signal_id,
+      ws.message::jsonb->'data'->>'queueConfig'  AS queue_config,
       ws.workflow_name,
-      ws.created_at                         AS suspended_at
+      ws.created_at                              AS suspended_at
     FROM "${appId}".worker_streams ws
     WHERE ws.aid LIKE '%/waiter'
       AND ws.expired_at IS NOT NULL
       AND ws.dead_lettered_at IS NULL
+      AND ws.created_at > NOW() - ($1 || ' hours')::INTERVAL
   ),
   live_jobs AS (
     SELECT REPLACE(key, 'hmsh:${appId}:j:', '') AS wid
@@ -54,7 +76,7 @@ const ORPHANED_SIGNALS = (appId) => `
     cw.signal_id,
     cw.workflow_name,
     cw.suspended_at,
-    EXTRACT(EPOCH FROM (NOW() - cw.suspended_at)) * 1000 AS stalled_ms,
+    EXTRACT(EPOCH FROM (NOW() - cw.suspended_at)) * 1000 AS waiting_ms,
     cw.queue_config IS NULL AS missing_queue_config
   FROM committed_waiters cw
   JOIN live_jobs lj ON lj.wid = cw.job_id
@@ -62,11 +84,14 @@ const ORPHANED_SIGNALS = (appId) => `
     SELECT 1 FROM public.hmsh_escalations e WHERE e.workflow_id = cw.job_id
   )
   ORDER BY cw.suspended_at ASC
-  LIMIT $1
+  LIMIT $2
 `;
+/** Default cap on events returned in the payload — keeps a high-activity workflow from returning a huge response. */
+const DEFAULT_MAX_EVENTS = 500;
 // ── diagnoseJob ──────────────────────────────────────────────────────────────
-async function diagnoseJob(workflowId, appId = 'durable') {
+async function diagnoseJob(workflowId, appId = 'durable', options = {}) {
     const pool = (0, db_1.getPool)();
+    const maxEvents = Math.max(options.maxEvents ?? DEFAULT_MAX_EVENTS, 1);
     let resolved;
     try {
         resolved = await (0, resolve_1.resolveWorkflowHandle)(workflowId);
@@ -91,9 +116,14 @@ async function diagnoseJob(workflowId, appId = 'durable') {
     const isFailed = events.some(e => e.event_type === 'workflow_execution_failed');
     const status = isCompleted ? 'completed' : isFailed ? 'failed' : 'running';
     const lastEventAt = lastEvent?.event_time ?? null;
-    const stalledMs = status === 'running' && lastEventAt
+    const idleMs = status === 'running' && lastEventAt
         ? now - new Date(lastEventAt).getTime()
         : null;
+    // Cap the events returned in the payload (keep the most recent) so a
+    // high-activity workflow can't produce a huge response. Pattern matching
+    // still runs over the full in-memory event set.
+    const eventsTruncated = events.length > maxEvents;
+    const cappedEvents = eventsTruncated ? events.slice(-maxEvents) : events;
     const allMessages = [...workerMessages, ...engineMessages];
     const streamSummary = {
         worker_total: workerMessages.length,
@@ -104,12 +134,12 @@ async function diagnoseJob(workflowId, appId = 'durable') {
     };
     const findings = execution
         ? (0, patterns_1.matchPatterns)(execution, workerMessages, engineMessages, escalationRow)
-        : [{ condition: 'export_unavailable', confidence: 0.9, severity: 'warning', evidence: ['Execution export unavailable — job may have expired or HotMesh engine is not running'], treatment: [] }];
+        : [{ condition: 'export_unavailable', confidence: 0.9, severity: 'warning', evidence: ['Execution export unavailable — job may have expired or HotMesh engine is not running'], guidance: [] }];
     return {
         workflow_id: workflowId,
         app_id: appId,
         status,
-        stalled_for_ms: stalledMs,
+        idle_for_ms: idleMs,
         workflow_type: resolved.workflowName,
         last_event_at: lastEventAt,
         stream_summary: streamSummary,
@@ -123,33 +153,40 @@ async function diagnoseJob(workflowId, appId = 'durable') {
             created_at: escalationRow?.created_at ?? null,
         },
         findings,
-        execution_events: events,
+        execution_events: cappedEvents,
+        total_events: events.length,
+        events_truncated: eventsTruncated,
         stream_messages: { worker: workerMessages, engine: engineMessages },
     };
 }
 // ── findStalledJobs ──────────────────────────────────────────────────────────
 async function findStalledJobs(params) {
     const appId = params.appId ?? 'durable';
-    const stalledMinutes = params.stalledMinutes ?? 5;
+    const idleMinutes = params.idleMinutes ?? 5;
     const limit = Math.min(params.limit ?? 50, 200);
     const keyPrefix = `hmsh:${appId}:j:`;
+    // Fail loud: let a query error surface (the api layer maps it to a 500). A
+    // silent empty result would hide a missing schema or a broken query.
     const pool = (0, db_1.getPool)();
     const { rows } = await pool.query(STALLED_JOBS(appId), [
         keyPrefix,
-        String(stalledMinutes),
+        String(idleMinutes),
         params.workflowType ?? null,
         limit,
-    ]).catch(() => ({ rows: [] }));
+    ]);
     return { jobs: rows, total: rows.length };
 }
 // ── findOrphanedSignals ──────────────────────────────────────────────────────
 async function findOrphanedSignals(params) {
     const appId = params.appId ?? 'durable';
+    const withinHours = Math.min(Math.max(params.withinHours ?? 24, 1), 720);
     const limit = Math.min(params.limit ?? 100, 500);
+    // Fail loud: let a query error surface (the api layer maps it to a 500). A
+    // silent empty result would hide a missing schema or a broken query — exactly
+    // what previously masked a JSON-operator bug on the text `message` column.
     const pool = (0, db_1.getPool)();
-    const { rows } = await pool.query(ORPHANED_SIGNALS(appId), [limit])
-        .catch(() => ({ rows: [] }));
-    return { orphans: rows, total: rows.length };
+    const { rows } = await pool.query(ORPHANED_SIGNALS(appId), [String(withinHours), limit]);
+    return { orphans: rows, total: rows.length, within_hours: withinHours };
 }
 // ── helpers ──────────────────────────────────────────────────────────────────
 function notFound(workflowId, appId) {
@@ -157,13 +194,15 @@ function notFound(workflowId, appId) {
         workflow_id: workflowId,
         app_id: appId,
         status: 'not_found',
-        stalled_for_ms: null,
+        idle_for_ms: null,
         workflow_type: null,
         last_event_at: null,
         stream_summary: { worker_total: 0, engine_total: 0, dead_lettered: 0, pending: 0, in_flight: 0 },
         escalation: { exists: false, id: null, status: null, signal_key: null, role: null, type: null, created_at: null },
-        findings: [{ condition: 'not_found', confidence: 1, severity: 'critical', evidence: ['Workflow ID not found — no task record or job entity'], treatment: [] }],
+        findings: [{ condition: 'not_found', confidence: 1, severity: 'critical', evidence: ['Workflow ID not found — no task record or job entity'], guidance: [] }],
         execution_events: [],
+        total_events: 0,
+        events_truncated: false,
         stream_messages: { worker: [], engine: [] },
     };
 }

package/build/services/diagnostics/patterns.d.ts

@@ -5,15 +5,25 @@ export interface Finding {
     confidence: number;
     severity: 'critical' | 'warning' | 'info';
     evidence: string[];
-    treatment: RecoveryOption[];
+    /**
+     * Read-only diagnostic guidance: what the condition means and where a human
+     * should look next. This is NOT recovery — HotMesh state only moves forward
+     * and cannot be unwound, so guidance never prescribes mutating job state.
+     */
+    guidance: Guidance[];
 }
-export interface RecoveryOption {
+export interface Guidance {
     action: string;
     note: string;
     [key: string]: unknown;
 }
 /**
- * Match event stream + stream messages against known failure patterns.
+ * Match event stream + stream messages against known workflow conditions.
  * Returns findings ordered by severity (critical first).
+ *
+ * Healthy long-waits are a first-class outcome here, not an omission: a
+ * workflow suspended at `condition()`/`waitFor()`/`sleepFor()` can sit for days
+ * legitimately, so we classify those explicitly rather than treating a frozen
+ * job as broken.
  */
 export declare function matchPatterns(execution: WorkflowExecution, workerMessages: StreamMessage[], engineMessages: StreamMessage[], escalationRow: Record<string, unknown> | null): Finding[];