@hotmeshio/long-tail 0.5.10 → 0.5.12

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,43 @@ 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;
+/** Strings larger than this (UTF-8 bytes) are summarized rather than returned in full. */
+const LARGE_STRING_BYTES = 1024;
+/** How many leading characters of a summarized string to keep as a preview. */
+const PREVIEW_CHARS = 200;
+/** Recursion depth cap for summarizing nested event attributes. */
+const SUMMARIZE_MAX_DEPTH = 6;
+/** Replace an over-threshold string with a bounded summary; pass small strings through unchanged. */
+function summarizeString(value) {
+    const bytes = Buffer.byteLength(value, 'utf8');
+    if (bytes <= LARGE_STRING_BYTES)
+        return value;
+    return { bytes, preview: value.slice(0, PREVIEW_CHARS), truncated: true };
+}
+/** Recursively summarize large string leaves in an event attribute tree (result/output/input/error payloads). */
+function summarizeDeep(value, depth = 0) {
+    if (typeof value === 'string')
+        return summarizeString(value);
+    if (value === null || typeof value !== 'object' || depth >= SUMMARIZE_MAX_DEPTH)
+        return value;
+    if (Array.isArray(value))
+        return value.map((v) => summarizeDeep(v, depth + 1));
+    const out = {};
+    for (const [k, v] of Object.entries(value)) {
+        out[k] = summarizeDeep(v, depth + 1);
+    }
+    return out;
+}
 // ── 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);
+    const includeEvents = options.verbosity === 'full' || !!options.include?.includes('events');
+    const includeStreams = options.verbosity === 'full' || !!options.include?.includes('streams');
     let resolved;
     try {
         resolved = await (0, resolve_1.resolveWorkflowHandle)(workflowId);
@@ -91,9 +145,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 +163,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: [] }];
-    return {
+        : [{ condition: 'export_unavailable', confidence: 0.9, severity: 'warning', evidence: ['Execution export unavailable — job may have expired or HotMesh engine is not running'], guidance: [] }];
+    const diagnosis = {
         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 +182,62 @@ async function diagnoseJob(workflowId, appId = 'durable') {
             created_at: escalationRow?.created_at ?? null,
         },
         findings,
-        execution_events: events,
-        stream_messages: { worker: workerMessages, engine: engineMessages },
+        total_events: events.length,
+        events_truncated: eventsTruncated,
     };
+    // Heavy sections are opt-in. Large string payloads are summarized either way
+    // so an included section can't reintroduce the 100–200KB blow-up.
+    if (includeEvents) {
+        diagnosis.execution_events = cappedEvents.map((e) => e && typeof e === 'object'
+            ? { ...e, attributes: summarizeDeep(e.attributes) }
+            : e);
+    }
+    if (includeStreams) {
+        diagnosis.stream_messages = {
+            worker: summarizeMessages(workerMessages),
+            engine: summarizeMessages(engineMessages),
+        };
+    }
+    else {
+        diagnosis.raw_messages = {
+            hint: 'Use list_stream_messages (Control Plane) filtered by jid (and aid/dad) for the full raw message payloads.',
+            jid: workflowId,
+        };
+    }
+    return diagnosis;
+}
+/** Summarize the large `message` payload of each stream message; everything else passes through. */
+function summarizeMessages(messages) {
+    return messages.map((m) => ({ ...m, message: summarizeString(m.message) }));
 }
 // ── 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 +245,13 @@ 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: [] }],
-        execution_events: [],
-        stream_messages: { worker: [], engine: [] },
+        findings: [{ condition: 'not_found', confidence: 1, severity: 'critical', evidence: ['Workflow ID not found — no task record or job entity'], guidance: [] }],
+        total_events: 0,
+        events_truncated: false,
     };
 }

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[];

package/build/services/diagnostics/patterns.js

@@ -2,8 +2,13 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.matchPatterns = matchPatterns;
 /**
- * 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.
  */
 function matchPatterns(execution, workerMessages, engineMessages, escalationRow) {
     const findings = [];
@@ -36,13 +41,18 @@ function matchPatterns(execution, workerMessages, engineMessages, escalationRow)
                 `${openSignals.length} open signal(s) with no matching resolution`,
                 `No escalation row in hmsh_escalations for this workflow`,
                 queueConfig == null
-                    ? `Worker result missing queueConfig — escalation INSERT was skipped (pre-0.22 SDK)`
-                    : `Worker result has queueConfig but escalation INSERT did not complete`,
-                ...(signalId ? [`Signal key: ${signalId}`] : []),
+                    ? `Worker result missing queueConfig — no escalation row was written (pre-0.22 SDK)`
+                    : `Worker result has queueConfig but no escalation row was written`,
+                ...(signalId ? [`Awaited signal key: ${signalId}`] : []),
             ],
-            treatment: [
-                { action: 'create_escalation_row', note: 'INSERT missing row into public.hmsh_escalations' },
-                ...(signalId ? [{ action: 'resolve_by_signal_key', signal_key: signalId, note: 'POST /api/escalations/resolve-by-signal-key after inserting escalation row' }] : []),
+            guidance: [
+                {
+                    action: 'inspect_worker_result',
+                    note: signalId
+                        ? `Workflow is parked on signal "${signalId}" with no escalation backing it, so the normal escalation lifecycle will not resume it. Inspect the worker result payload via the stream browser (list_stream_messages filtered by jid) to confirm the missing queueConfig.`
+                        : 'Workflow is parked on a signal with no escalation backing it. Inspect the worker result payload via the stream browser (list_stream_messages filtered by jid).',
+                },
+                { action: 'escalate_to_engineering', note: 'Resolving an orphaned wait requires engineering review of the deploy/SDK version. Do not hand-edit escalation or job state — HotMesh state cannot be unwound.' },
             ],
         });
     }
@@ -59,11 +69,12 @@ function matchPatterns(execution, workerMessages, engineMessages, escalationRow)
             confidence: 0.99,
             severity: 'info',
             evidence: [
-                `Workflow suspended — escalation exists (status: pending)`,
+                `Healthy wait — workflow suspended at a condition with a pending escalation`,
+                `This is NOT stalled: a workflow can wait here for days legitimately. A frozen updated_at is the normal signature of a wait, not a fault.`,
                 ...(escalationRow.role ? [`Role: ${escalationRow.role}, Type: ${escalationRow.type}`] : []),
                 ...(escalationRow.id ? [`Escalation id: ${escalationRow.id}`] : []),
             ],
-            treatment: [{ action: 'none', note: 'Waiting for human to claim and resolve escalation' }],
+            guidance: [{ action: 'none', note: 'No action required — waiting for a human to claim and resolve the escalation through the normal lifecycle.' }],
         });
     }
     // ── Pattern: dead_lettered_activity ──────────────────────────────────────
@@ -77,7 +88,7 @@ function matchPatterns(execution, workerMessages, engineMessages, escalationRow)
                 `${deadWorker.length} worker message(s) dead-lettered, ${deadEngine.length} engine message(s) dead-lettered`,
                 ...samples.map(m => `aid: ${m.aid ?? 'engine'}, retries: ${m.retry_attempt}/${m.max_retry_attempts}, stream: ${m.stream_name}`),
             ],
-            treatment: [{
+            guidance: [{
                     action: 'investigate_dead_letter',
                     count: deadWorker.length + deadEngine.length,
                     note: 'Message exhausted retries — check worker health and DB connectivity',
@@ -91,7 +102,7 @@ function matchPatterns(execution, workerMessages, engineMessages, escalationRow)
             confidence: 0.85,
             severity: 'warning',
             evidence: leaks.map(m => `aid: ${m.aid}, claimed by: ${m.reserved_by ?? 'unknown'}, open for ${Math.round((now - new Date(m.reserved_at).getTime()) / 1000)}s`),
-            treatment: [{ action: 'check_worker_health', note: 'Worker claimed message but never ACKd — check for crashed workers' }],
+            guidance: [{ action: 'check_worker_health', note: 'Worker claimed message but never ACKd — check for crashed workers' }],
         });
     }
     // ── Pattern: terminal_failure ─────────────────────────────────────────────
@@ -106,7 +117,7 @@ function matchPatterns(execution, workerMessages, engineMessages, escalationRow)
                 `Workflow terminated with failure`,
                 ...(attrs?.error ? [`Error: ${attrs.error}`] : []),
             ],
-            treatment: [{ action: 'none', note: 'Workflow terminated — review error and restart if needed' }],
+            guidance: [{ action: 'none', note: 'Workflow terminated — review error and restart if needed' }],
         });
     }
     // ── Pattern: never_started ────────────────────────────────────────────────
@@ -117,7 +128,7 @@ function matchPatterns(execution, workerMessages, engineMessages, escalationRow)
             confidence: 0.90,
             severity: 'critical',
             evidence: [`Workflow created but no activities have run — engine may not be consuming this stream`],
-            treatment: [{ action: 'check_engine_health', note: 'Check engine health and stream backlog for this workflow type' }],
+            guidance: [{ action: 'check_engine_health', note: 'Check engine health and stream backlog for this workflow type' }],
         });
     }
     // ── Default: healthy ──────────────────────────────────────────────────────
@@ -128,7 +139,7 @@ function matchPatterns(execution, workerMessages, engineMessages, escalationRow)
             confidence: 0.95,
             severity: 'info',
             evidence: [isCompleted ? 'Workflow completed normally' : 'Workflow is running — no anomalies detected'],
-            treatment: [{ action: 'none', note: 'No intervention required' }],
+            guidance: [{ action: 'none', note: 'No intervention required' }],
         });
     }
     // Critical first

package/build/services/escalation/queries.d.ts

@@ -15,6 +15,7 @@ export declare function listEscalations(filters: {
     visibleRoles?: string[];
     sort_by?: string;
     order?: string;
+    search?: string;
 }): Promise<{
     escalations: LTEscalationRecord[];
     total: number;
@@ -32,6 +33,7 @@ export declare function listAvailableEscalations(filters: {
     visibleRoles?: string[];
     sort_by?: string;
     order?: string;
+    search?: string;
 }): Promise<{
     escalations: LTEscalationRecord[];
     total: number;

package/build/services/escalation/queries.js

@@ -4,9 +4,11 @@ exports.getEscalationStats = getEscalationStats;
 exports.listDistinctTypes = listDistinctTypes;
 exports.listEscalations = listEscalations;
 exports.listAvailableEscalations = listAvailableEscalations;
+const db_1 = require("../../lib/db");
 const client_1 = require("./client");
 const map_1 = require("./map");
 const types_1 = require("./types");
+const sql_1 = require("./sql");
 /**
  * Default sort is priority ASC, created_at ASC. A user-chosen `sort_by` maps to
  * a single column (DESC unless `order='asc'`), matching the legacy behavior.
@@ -20,6 +22,50 @@ function buildOrderBy(sortBy, order) {
         { column: 'created_at', direction: 'asc' },
     ];
 }
+/**
+ * ORDER BY clause for the raw search query. `sortBy` is checked against the
+ * SORTABLE_COLUMNS whitelist before interpolation, so it is injection-safe.
+ */
+function buildSearchOrderBy(sortBy, order) {
+    const dir = order === 'asc' ? 'ASC' : 'DESC';
+    if (sortBy && types_1.SORTABLE_COLUMNS.has(sortBy)) {
+        return `${sortBy} ${dir}`;
+    }
+    return 'priority ASC, created_at ASC';
+}
+/**
+ * Server-side free-text search over the `lt_escalations` view. Runs when a
+ * caller supplies a non-empty `search` term — the SDK `client.list()` cannot do
+ * free-text, so this is raw SQL on the shared table (see ./sql.ts). All other
+ * filters combine with the term (AND).
+ */
+async function searchEscalations(params) {
+    await (0, client_1.ensureEscalationCompatView)();
+    const pool = (0, db_1.getPool)();
+    // Coerce empty strings to NULL so an absent filter (e.g. assigned_to='') does
+    // not become `column = ''` and match zero rows. Mirrors the SDK path's
+    // `if (filters.x)` truthiness guards.
+    const filterArgs = [
+        params.status || null,
+        params.role || null,
+        params.roles && params.roles.length ? params.roles : null,
+        params.type || null,
+        params.subtype || null,
+        params.priority ?? null,
+        params.assigned_to || null,
+        params.available ?? null,
+        params.search,
+    ];
+    const orderBy = buildSearchOrderBy(params.sort_by, params.order);
+    const [rows, countRows] = await Promise.all([
+        pool.query((0, sql_1.searchEscalationsQuery)(orderBy), [...filterArgs, params.limit, params.offset]),
+        pool.query(sql_1.COUNT_SEARCH_ESCALATIONS, filterArgs),
+    ]);
+    return {
+        escalations: (0, map_1.toEscalationRecords)(rows.rows),
+        total: countRows.rows[0]?.total ?? 0,
+    };
+}
 async function getEscalationStats(visibleRoles, period) {
     const client = await (0, client_1.escalations)();
     return client.stats({
@@ -32,6 +78,26 @@ async function listDistinctTypes() {
     return client.listDistinctTypes();
 }
 async function listEscalations(filters) {
+    // Active claim semantics: assigned_to-active and `claimed` both mean "held now".
+    const heldNow = !!(filters.assigned_to || filters.claimed);
+    // Free-text search → server-side SQL path (the SDK list() has no free-text).
+    if (filters.search) {
+        return searchEscalations({
+            status: filters.status,
+            role: filters.role,
+            roles: filters.visibleRoles,
+            type: filters.type,
+            subtype: filters.subtype,
+            priority: filters.priority,
+            assigned_to: filters.assigned_to,
+            available: heldNow ? false : undefined,
+            search: filters.search,
+            limit: filters.limit ?? 50,
+            offset: filters.offset ?? 0,
+            sort_by: filters.sort_by,
+            order: filters.order,
+        });
+    }
     const client = await (0, client_1.escalations)();
     // Shared filter — passed to both list() and count() so totals stay in sync.
     const where = {
@@ -44,8 +110,7 @@ async function listEscalations(filters) {
     };
     if (filters.assigned_to)
         where.assignedTo = filters.assigned_to;
-    // Active claim semantics: assigned_to-active and `claimed` both mean "held now".
-    if (filters.assigned_to || filters.claimed)
+    if (heldNow)
         where.available = false;
     const [rows, total] = await Promise.all([
         client.list({
@@ -62,6 +127,23 @@ async function listEscalations(filters) {
  * List available escalations: pending AND (unassigned OR expired claim).
  */
 async function listAvailableEscalations(filters) {
+    // Free-text search → server-side SQL path (available = pending + no active claim).
+    if (filters.search) {
+        return searchEscalations({
+            status: 'pending',
+            role: filters.role,
+            roles: filters.visibleRoles,
+            type: filters.type,
+            subtype: filters.subtype,
+            priority: filters.priority,
+            available: true,
+            search: filters.search,
+            limit: filters.limit ?? 50,
+            offset: filters.offset ?? 0,
+            sort_by: filters.sort_by,
+            order: filters.order,
+        });
+    }
     const client = await (0, client_1.escalations)();
     const where = {
         status: 'pending',

package/build/services/escalation/sql.d.ts

@@ -8,6 +8,13 @@
  * table. Clears both `assigned_until` and `claim_expires_at`.
  */
 export declare const RELEASE_EXPIRED_CLAIMS = "UPDATE public.hmsh_escalations\nSET assigned_to = NULL,\n    assigned_until = NULL,\n    claimed_at = NULL,\n    claim_expires_at = NULL,\n    updated_at = NOW()\nWHERE status = 'pending'\n  AND assigned_to IS NOT NULL\n  AND assigned_until <= NOW()";
+/** Count matching the search WHERE (params $1–$9). */
+export declare const COUNT_SEARCH_ESCALATIONS = "SELECT COUNT(*)::int AS total\n  FROM public.lt_escalations\n  WHERE ($1::text IS NULL OR status = $1)\n    AND ($2::text IS NULL OR role = $2)\n    AND ($3::text[] IS NULL OR role = ANY($3))\n    AND ($4::text IS NULL OR type = $4)\n    AND ($5::text IS NULL OR subtype = $5)\n    AND ($6::int IS NULL OR priority = $6)\n    AND ($7::text IS NULL OR assigned_to = $7)\n    AND ($8::boolean IS NULL OR available = $8)\n    AND ($9::text IS NULL OR (\n          description ILIKE '%' || $9 || '%'\n       OR type ILIKE '%' || $9 || '%'\n       OR subtype ILIKE '%' || $9 || '%'\n       OR role ILIKE '%' || $9 || '%'\n       OR workflow_id ILIKE '%' || $9 || '%'\n       OR origin_id ILIKE '%' || $9 || '%'\n       OR id::text ILIKE '%' || $9 || '%'\n       OR metadata::text ILIKE '%' || $9 || '%'\n    ))";
+/**
+ * Build the search SELECT. `orderBy` is composed from a whitelist by the caller
+ * (never raw user input), so it is safe to interpolate; everything else is bound.
+ */
+export declare function searchEscalationsQuery(orderBy: string): string;
 /**
  * Atomic resolve by metadata with signal guard.
  *

package/build/services/escalation/sql.js

@@ -11,7 +11,8 @@
 // `hmsh_escalations` here rather than composed from generic SDK calls.
 // ---------------------------------------------------------------------------
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RESOLVE_BY_METADATA_ATOMIC = exports.RELEASE_EXPIRED_CLAIMS = void 0;
+exports.RESOLVE_BY_METADATA_ATOMIC = exports.COUNT_SEARCH_ESCALATIONS = exports.RELEASE_EXPIRED_CLAIMS = void 0;
+exports.searchEscalationsQuery = searchEscalationsQuery;
 /**
  * Sweep expired claims back to the available pool.
  *
@@ -31,6 +32,54 @@ SET assigned_to = NULL,
 WHERE status = 'pending'
   AND assigned_to IS NOT NULL
   AND assigned_until <= NOW()`;
+/**
+ * Free-text escalation search.
+ *
+ * The SDK's `client.list()` filters by structured columns only — it has no
+ * free-text predicate. Long-tail's contract needs a search box that matches a
+ * correlation key (order id, ticket id) or any visible field across the WHOLE
+ * result set, not just the current page. That is server-side SQL here (over the
+ * `lt_escalations` view, which adds the computed `available` flag), following the
+ * same raw-SQL-on-the-shared-table pattern as the atomic resolve below — so the
+ * filter flows SQL→service→API→route→dashboard rather than being faked client-side.
+ *
+ * All structured filters are optional and combine with the search term (AND).
+ * `metadata::text ILIKE` scans the JSONB as text (the GIN index is containment-only
+ * and cannot serve ILIKE) — bounded in practice by the other filters and the page.
+ *
+ * $1 status, $2 role, $3 roles (text[] visibleRoles), $4 type, $5 subtype,
+ * $6 priority, $7 assigned_to, $8 available (bool), $9 search.
+ * The list query adds $10 limit, $11 offset.
+ */
+const SEARCH_ESCALATIONS_WHERE = `\
+  FROM public.lt_escalations
+  WHERE ($1::text IS NULL OR status = $1)
+    AND ($2::text IS NULL OR role = $2)
+    AND ($3::text[] IS NULL OR role = ANY($3))
+    AND ($4::text IS NULL OR type = $4)
+    AND ($5::text IS NULL OR subtype = $5)
+    AND ($6::int IS NULL OR priority = $6)
+    AND ($7::text IS NULL OR assigned_to = $7)
+    AND ($8::boolean IS NULL OR available = $8)
+    AND ($9::text IS NULL OR (
+          description ILIKE '%' || $9 || '%'
+       OR type ILIKE '%' || $9 || '%'
+       OR subtype ILIKE '%' || $9 || '%'
+       OR role ILIKE '%' || $9 || '%'
+       OR workflow_id ILIKE '%' || $9 || '%'
+       OR origin_id ILIKE '%' || $9 || '%'
+       OR id::text ILIKE '%' || $9 || '%'
+       OR metadata::text ILIKE '%' || $9 || '%'
+    ))`;
+/** Count matching the search WHERE (params $1–$9). */
+exports.COUNT_SEARCH_ESCALATIONS = `SELECT COUNT(*)::int AS total\n${SEARCH_ESCALATIONS_WHERE}`;
+/**
+ * Build the search SELECT. `orderBy` is composed from a whitelist by the caller
+ * (never raw user input), so it is safe to interpolate; everything else is bound.
+ */
+function searchEscalationsQuery(orderBy) {
+    return `SELECT *\n${SEARCH_ESCALATIONS_WHERE}\n  ORDER BY ${orderBy}\n  LIMIT $10 OFFSET $11`;
+}
 /**
  * Atomic resolve by metadata with signal guard.
  *

package/build/services/task/resolve.d.ts

@@ -4,9 +4,11 @@ import type { ResolvedHandle } from './types';
  * HotMesh needs to get a workflow handle.
  *
  * 1. Look up lt_tasks by workflow_id — returns workflow_type and task_queue.
- * 2. If no task record (e.g., orchestrators/containers), fall back to
- *    durable.jobs (entity) + lt_config_workflows (task_queue).
+ * 2. If no task record (e.g., orchestrators/containers, or a child running in
+ *    another app), fall back to `<appId>.jobs` (entity) + lt_config_workflows
+ *    (task_queue). `appId` selects the HotMesh namespace to scan — children of
+ *    a workflow live under their own app's schema, not always `durable`.
  * 3. If task_queue is null (pre-migration record), fall back to lt_config_workflows.
  * 4. Throws if the workflow cannot be resolved.
  */
-export declare function resolveWorkflowHandle(workflowId: string): Promise<ResolvedHandle>;
+export declare function resolveWorkflowHandle(workflowId: string, appId?: string): Promise<ResolvedHandle>;

package/build/services/task/resolve.js

@@ -9,12 +9,14 @@ const sql_1 = require("./sql");
  * HotMesh needs to get a workflow handle.
  *
  * 1. Look up lt_tasks by workflow_id — returns workflow_type and task_queue.
- * 2. If no task record (e.g., orchestrators/containers), fall back to
- *    durable.jobs (entity) + lt_config_workflows (task_queue).
+ * 2. If no task record (e.g., orchestrators/containers, or a child running in
+ *    another app), fall back to `<appId>.jobs` (entity) + lt_config_workflows
+ *    (task_queue). `appId` selects the HotMesh namespace to scan — children of
+ *    a workflow live under their own app's schema, not always `durable`.
  * 3. If task_queue is null (pre-migration record), fall back to lt_config_workflows.
  * 4. Throws if the workflow cannot be resolved.
  */
-async function resolveWorkflowHandle(workflowId) {
+async function resolveWorkflowHandle(workflowId, appId = 'durable') {
     const pool = (0, db_1.getPool)();
     // 1. Try lt_tasks first (leaf workflows)
     const { rows } = await pool.query(sql_1.RESOLVE_TASK_BY_WORKFLOW_ID, [workflowId]);
@@ -29,9 +31,10 @@ async function resolveWorkflowHandle(workflowId) {
             return { taskQueue: configRows[0].task_queue, workflowName: workflow_type };
         }
     }
-    // 2. Fall back to durable.jobs — handles orchestrators/containers that
-    //    have no lt_tasks record but do have a job with an entity tag.
-    const { rows: jobRows } = await pool.query(sql_1.RESOLVE_JOB_ENTITY, [`hmsh:durable:j:${workflowId}`]);
+    // 2. Fall back to <appId>.jobs — handles orchestrators/containers that
+    //    have no lt_tasks record but do have a job with an entity tag, and
+    //    children running in a non-default namespace.
+    const { rows: jobRows } = await pool.query((0, sql_1.RESOLVE_JOB_ENTITY)(appId), [`hmsh:${appId}:j:${workflowId}`]);
     if (jobRows.length > 0 && jobRows[0].entity) {
         const entity = jobRows[0].entity;
         // 2a. Try lt_config_workflows for task_queue