@hotmeshio/long-tail 0.5.11 → 0.5.12

package/build/api/diagnostics.d.ts

@@ -1,8 +1,13 @@
+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;

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, { maxEvents: input.maxEvents });
+        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

@@ -8,6 +8,6 @@ import type { LTApiResult } from '../types/sdk';
  * 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, auth, ai, environment } }`
+ * @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,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 features_1 = require("../modules/features");
 const version_1 = require("../modules/version");
 const sso_1 = require("../modules/sso");
 const defaults_1 = require("../modules/defaults");
@@ -38,7 +39,7 @@ function resolveNatsWsUrl(adapter, req) {
  * 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, auth, ai, environment } }`
+ * @returns `{ status: 200, data: { telemetry, escalation, events, auth, ai, features, environment } }`
  */
 async function getSettings(req) {
     try {
@@ -70,6 +71,7 @@ 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,

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/routes/diagnostics.js

@@ -37,19 +37,32 @@ 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)
- *   max_events — cap on events returned (most recent kept; default: 500)
+ *   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 });
 });

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/diagnostics/index.d.ts

@@ -17,6 +17,21 @@ 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;
@@ -32,18 +47,37 @@ export interface JobDiagnosis {
     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[];
+    /**
+     * 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 declare function diagnoseJob(workflowId: string, appId?: string, options?: {
+export type DiagnoseVerbosity = 'summary' | 'full';
+export type DiagnoseSection = 'events' | 'streams';
+export interface DiagnoseOptions {
     maxEvents?: number;
-}): Promise<JobDiagnosis>;
+    /** 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, options?: DiagnoseOptions): Promise<JobDiagnosis>;
 export declare function findStalledJobs(params: {
     appId?: string;
     idleMinutes?: number;

package/build/services/diagnostics/index.js

@@ -88,10 +88,39 @@ const ORPHANED_SIGNALS = (appId) => `
 `;
 /** 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', 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);
@@ -135,7 +164,7 @@ async function diagnoseJob(workflowId, appId = 'durable', options = {}) {
     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'], guidance: [] }];
-    return {
+    const diagnosis = {
         workflow_id: workflowId,
         app_id: appId,
         status,
@@ -153,11 +182,33 @@ async function diagnoseJob(workflowId, appId = 'durable', options = {}) {
             created_at: escalationRow?.created_at ?? null,
         },
         findings,
-        execution_events: cappedEvents,
         total_events: events.length,
         events_truncated: eventsTruncated,
-        stream_messages: { worker: workerMessages, engine: engineMessages },
     };
+    // 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) {
@@ -200,9 +251,7 @@ function notFound(workflowId, appId) {
         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'], guidance: [] }],
-        execution_events: [],
         total_events: 0,
         events_truncated: false,
-        stream_messages: { worker: [], engine: [] },
     };
 }

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.
  *