@hotmeshio/long-tail 0.5.10 → 0.5.12

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

@@ -1,15 +1,22 @@
+import type { DiagnoseSection, DiagnoseVerbosity } from '../services/diagnostics';
 import type { LTApiResult } from '../types/sdk';
 export declare function diagnose(input: {
     workflowId: string;
     appId?: string;
+    maxEvents?: number;
+    /** Heavy sections to include (events, streams). Default: verdict only. */
+    include?: DiagnoseSection[];
+    /** Shorthand: 'full' includes events + streams; 'summary' (default) includes neither. */
+    verbosity?: DiagnoseVerbosity;
 }): 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,11 @@ 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,
+            include: input.include,
+            verbosity: input.verbosity,
+        });
         return { status: 200, data: diagnosis };
     }
     catch (err) {

package/build/api/escalations/list.d.ts

@@ -30,6 +30,7 @@ export declare function listEscalations(input: {
     offset?: number;
     sort_by?: string;
     order?: string;
+    search?: string;
 }, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * List escalations available for claim (pending and not actively claimed).
@@ -57,6 +58,7 @@ export declare function listAvailableEscalations(input: {
     offset?: number;
     sort_by?: string;
     order?: string;
+    search?: string;
 }, auth: LTApiAuth): Promise<LTApiResult>;
 /**
  * List all distinct escalation type values.

package/build/api/escalations/list.js

@@ -77,6 +77,7 @@ async function listEscalations(input, auth) {
             offset: input.offset,
             sort_by: input.sort_by,
             order: input.order,
+            search: input.search,
             visibleRoles,
         });
         return { status: 200, data: result };
@@ -117,6 +118,7 @@ async function listAvailableEscalations(input, auth) {
             offset: input.offset,
             sort_by: input.sort_by,
             order: input.order,
+            search: input.search,
             visibleRoles,
         });
         return { status: 200, data: result };

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, features, environment } }`
  */
 export declare function getSettings(req?: IncomingMessage): Promise<LTApiResult>;

package/build/api/settings.js

@@ -7,6 +7,8 @@ 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 features_1 = require("../modules/features");
+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 +35,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, features, environment } }`
  */
 async function getSettings(req) {
     try {
@@ -68,6 +71,14 @@ async function getSettings(req) {
                 ai: {
                     enabled: (0, llm_1.hasLLMApiKey)(),
                 },
+                features: (0, features_1.getFeatureFlags)(),
+                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/api/workflows/invocation.d.ts

@@ -23,12 +23,16 @@ export declare function invokeWorkflow(input: {
  *
  * Returns the HotMesh status code (0 = completed, 1 = running).
  * Resolves the workflow handle via task record or worker registry.
+ * `appId` selects the namespace for the job-entity fallback so a child
+ * running in another app resolves instead of 404ing against `durable`.
  *
  * @param input.workflowId — HotMesh workflow ID
+ * @param input.appId — HotMesh namespace for resolution (default: durable)
  * @returns `{ status: 200, data: { workflowId, status } }` or 404
  */
 export declare function getWorkflowStatus(input: {
     workflowId: string;
+    appId?: string;
 }): Promise<LTApiResult>;
 /**
  * Get the result of a completed workflow.
@@ -37,10 +41,12 @@ export declare function getWorkflowStatus(input: {
  * payload when complete. Never blocks — always returns immediately.
  *
  * @param input.workflowId — HotMesh workflow ID
+ * @param input.appId — HotMesh namespace for resolution (default: durable)
  * @returns `{ status: 200, data: { workflowId, result } }` or 202 if running
  */
 export declare function getWorkflowResult(input: {
     workflowId: string;
+    appId?: string;
 }): Promise<LTApiResult>;
 /**
  * Terminate a running workflow.

package/build/api/workflows/invocation.js

@@ -87,13 +87,16 @@ async function invokeWorkflow(input, auth) {
  *
  * Returns the HotMesh status code (0 = completed, 1 = running).
  * Resolves the workflow handle via task record or worker registry.
+ * `appId` selects the namespace for the job-entity fallback so a child
+ * running in another app resolves instead of 404ing against `durable`.
  *
  * @param input.workflowId — HotMesh workflow ID
+ * @param input.appId — HotMesh namespace for resolution (default: durable)
  * @returns `{ status: 200, data: { workflowId, status } }` or 404
  */
 async function getWorkflowStatus(input) {
     try {
-        const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId);
+        const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId, input.appId);
         const client = (0, workers_1.createClient)();
         const handle = await client.workflow.getHandle(resolved.taskQueue, resolved.workflowName, input.workflowId);
         const status = await handle.status();
@@ -115,11 +118,12 @@ async function getWorkflowStatus(input) {
  * payload when complete. Never blocks — always returns immediately.
  *
  * @param input.workflowId — HotMesh workflow ID
+ * @param input.appId — HotMesh namespace for resolution (default: durable)
  * @returns `{ status: 200, data: { workflowId, result } }` or 202 if running
  */
 async function getWorkflowResult(input) {
     try {
-        const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId);
+        const resolved = await (0, task_1.resolveWorkflowHandle)(input.workflowId, input.appId);
         const client = (0, workers_1.createClient)();
         const handle = await client.workflow.getHandle(resolved.taskQueue, resolved.workflowName, input.workflowId);
         const status = await handle.status();

package/build/modules/features.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Runtime feature flags surfaced to the dashboard via /api/settings.
+ *
+ * These gate UI affordances (nav entries, routes) that some deployments want to
+ * hide. Defaults are permissive (everything on); a deployment opts OUT through
+ * the `features` block of the `start()` config. The dashboard reads the resolved
+ * flags from `settings.features` and hides the corresponding nav item + route.
+ */
+export interface FeatureFlags {
+    /**
+     * Show the DB Maintenance admin page (nav entry + route).
+     * Default: true. Set `features.dbMaintenance: false` in start config to hide it.
+     */
+    dbMaintenance: boolean;
+}
+/** Merge a partial set of flags from the start config. Unspecified flags keep their default. */
+export declare function configureFeatureFlags(patch?: Partial<FeatureFlags>): void;
+/** The resolved feature flags reported to the dashboard. */
+export declare function getFeatureFlags(): FeatureFlags;

package/build/modules/features.js

@@ -0,0 +1,16 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.configureFeatureFlags = configureFeatureFlags;
+exports.getFeatureFlags = getFeatureFlags;
+const DEFAULT_FLAGS = {
+    dbMaintenance: true,
+};
+let flags = { ...DEFAULT_FLAGS };
+/** Merge a partial set of flags from the start config. Unspecified flags keep their default. */
+function configureFeatureFlags(patch) {
+    flags = { ...DEFAULT_FLAGS, ...(patch ?? {}) };
+}
+/** The resolved feature flags reported to the dashboard. */
+function getFeatureFlags() {
+    return { ...flags };
+}

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

@@ -37,34 +37,51 @@ const express_1 = require("express");
 const api = __importStar(require("../api/diagnostics"));
 const auth_1 = require("../modules/auth");
 const router = (0, express_1.Router)();
+const VALID_SECTIONS = new Set(['events', 'streams']);
+/** Parse a comma-separated `include` query param into the recognized heavy sections. */
+function parseInclude(raw) {
+    if (typeof raw !== 'string' || raw.trim() === '')
+        return undefined;
+    const sections = raw.split(',').map((s) => s.trim()).filter((s) => VALID_SECTIONS.has(s));
+    return sections.length > 0 ? sections : undefined;
+}
 /**
  * GET /api/diagnostics/jobs/:workflowId
- * Full diagnosis for a single workflow job.
+ * Compact diagnosis for a single workflow job — the verdict only by default
+ * (status, idle time, stream counts, escalation, findings).
  *
  * Query params:
- *   app_id — HotMesh namespace (default: durable)
+ *   app_id     — HotMesh namespace (default: durable)
+ *   max_events — cap on events returned when included (most recent kept; default: 500)
+ *   include    — comma-separated heavy sections to add: events, streams
+ *   verbosity  — 'summary' (default, verdict only) or 'full' (events + streams)
  */
 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,
+        include: parseInclude(req.query.include),
+        verbosity: req.query.verbosity === 'full' ? 'full' : 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 +89,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/routes/escalations/list.js

@@ -76,6 +76,7 @@ function registerListRoutes(router) {
             offset: req.query.offset ? parseInt(req.query.offset, 10) : undefined,
             sort_by: req.query.sort_by,
             order: req.query.order,
+            search: req.query.search,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });
@@ -94,6 +95,7 @@ function registerListRoutes(router) {
             offset: req.query.offset ? parseInt(req.query.offset, 10) : undefined,
             sort_by: req.query.sort_by,
             order: req.query.order,
+            search: req.query.search,
         }, req.auth);
         res.status(result.status).json(result.data ?? { error: result.error });
     });

package/build/routes/workflows/invocation.js

@@ -66,19 +66,27 @@ router.post('/:type/invoke', async (req, res) => {
 // ── Workflow observation ────────────────────────────────────────────────────
 /**
  * GET /api/workflows/:workflowId/status
- * Get the status of a workflow. Only the workflowId is needed.
+ * Get the status of a workflow. Optional `app_id` query param selects the
+ * HotMesh namespace for resolution (default: durable).
  */
 router.get('/:workflowId/status', async (req, res) => {
-    const result = await api.getWorkflowStatus({ workflowId: req.params.workflowId });
+    const result = await api.getWorkflowStatus({
+        workflowId: req.params.workflowId,
+        appId: typeof req.query.app_id === 'string' ? req.query.app_id : undefined,
+    });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 /**
  * GET /api/workflows/:workflowId/result
  * Return the workflow result if complete, or 202 if still running.
- * Never blocks — always returns immediately.
+ * Never blocks — always returns immediately. Optional `app_id` query param
+ * selects the HotMesh namespace for resolution (default: durable).
  */
 router.get('/:workflowId/result', async (req, res) => {
-    const result = await api.getWorkflowResult({ workflowId: req.params.workflowId });
+    const result = await api.getWorkflowResult({
+        workflowId: req.params.workflowId,
+        appId: typeof req.query.app_id === 'string' ? req.query.app_id : undefined,
+    });
     res.status(result.status).json(result.data ?? { error: result.error });
 });
 /**

package/build/sdk/index.d.ts

@@ -95,6 +95,7 @@ export declare function createClient(options?: LTClientOptions): {
             offset?: number;
             sort_by?: string;
             order?: string;
+            search?: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         listAvailable: (input: {
             role?: string;
@@ -105,6 +106,7 @@ export declare function createClient(options?: LTClientOptions): {
             offset?: number;
             sort_by?: string;
             order?: string;
+            search?: string;
         }, auth?: LTApiAuth) => Promise<LTApiResult<any>>;
         listTypes: typeof escalationsApi.listDistinctTypes;
         getStats: (input: {

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

@@ -17,26 +17,70 @@ export interface StreamSummary {
     pending: number;
     in_flight: number;
 }
+/** A large string field replaced with a bounded summary instead of the full payload. */
+export interface TruncatedString {
+    bytes: number;
+    preview: string;
+    truncated: true;
+}
+/** Pointer to the stream browser for the raw, untruncated message payloads. */
+export interface RawMessagesHint {
+    hint: string;
+    jid: string;
+}
+/** A stream message whose large `message` payload may have been summarized. */
+export type SummarizedStreamMessage = Omit<StreamMessage, 'message'> & {
+    message: string | TruncatedString;
+};
 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[];
-    stream_messages: {
-        worker: StreamMessage[];
-        engine: StreamMessage[];
+    /** Total events before any cap was applied (execution_events may be truncated to the most recent `maxEvents`). */
+    total_events: number;
+    events_truncated: boolean;
+    /**
+     * Full event timeline — present only when `include` contains `'events'` (or
+     * `verbosity: 'full'`). Large string attributes are summarized to
+     * `{ bytes, preview, truncated }`. Omitted by default to keep the verdict compact.
+     */
+    execution_events?: unknown[];
+    /**
+     * Raw engine + worker stream messages — present only when `include` contains
+     * `'streams'` (or `verbosity: 'full'`). Large `message` payloads are summarized.
+     * Omitted by default; see `raw_messages` for where to fetch the full payloads.
+     */
+    stream_messages?: {
+        worker: SummarizedStreamMessage[];
+        engine: SummarizedStreamMessage[];
     };
+    /** Pointer to `list_stream_messages` for the raw payloads (present when streams are omitted). */
+    raw_messages?: RawMessagesHint;
+}
+export type DiagnoseVerbosity = 'summary' | 'full';
+export type DiagnoseSection = 'events' | 'streams';
+export interface DiagnoseOptions {
+    maxEvents?: number;
+    /** Heavy sections to include in the response. Default: none (verdict only). */
+    include?: DiagnoseSection[];
+    /** Shorthand: `'full'` includes both events and streams; `'summary'` (default) includes neither. */
+    verbosity?: DiagnoseVerbosity;
 }
-export declare function diagnoseJob(workflowId: string, appId?: string): Promise<JobDiagnosis>;
+export declare function diagnoseJob(workflowId: string, appId?: string, options?: DiagnoseOptions): Promise<JobDiagnosis>;
 export declare function findStalledJobs(params: {
     appId?: string;
-    stalledMinutes?: number;
+    idleMinutes?: number;
     workflowType?: string | null;
     limit?: number;
 }): Promise<{
@@ -45,8 +89,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;
 }>;