@hotmeshio/long-tail 0.5.7 → 0.5.10

package/build/api/escalations/metadata.js

@@ -125,10 +125,26 @@ async function resolveByMetadata(input, auth) {
         if (result.outcome === 'not_found') {
             return { status: 404, error: 'No pending escalation found for this metadata, or insufficient role permissions' };
         }
+        if (result.outcome === 'conflict') {
+            return { status: 409, error: 'A concurrent resolution is already in progress for this escalation' };
+        }
         if (result.outcome === 'resolved') {
             return { status: 200, data: { escalation: result.escalation } };
         }
-        // Signal-backed escalation — signal the workflow, conditionLT resolves durably
+        // Atomic conditionLT escalation (signal_key set) — SDK resolve atomically marks
+        // resolved AND delivers the signal to the waiting condition(), resuming the workflow.
+        if (result.signalKey) {
+            const resolved = await escalationService.resolveEscalation(result.escalationId, input.resolverPayload);
+            if (!resolved) {
+                return { status: 409, error: 'Escalation not available for resolution' };
+            }
+            return {
+                status: 200,
+                data: { signaled: true, escalationId: result.escalationId, workflowId: result.workflowId },
+            };
+        }
+        // Legacy conditionLT escalation (metadata.signal_id set) — signal the workflow,
+        // conditionLT interceptor resolves durably via ltResolveEscalation.
         const { createClient } = await Promise.resolve().then(() => __importStar(require('../../workers')));
         const client = createClient();
         const handle = await client.workflow.getHandle(result.taskQueue, result.workflowType, result.workflowId);

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

@@ -103,12 +103,19 @@ export declare function claimByMetadata(key: string, value: string, userId: stri
     candidatesExist: number;
 }) | null>;
 export interface ResolveByMetadataResult {
-    /** 'resolved' = done atomically. 'signal_required' = signal_id present, caller must signal. */
-    outcome: 'resolved' | 'signal_required' | 'not_found';
+    /**
+     * 'resolved'        = done atomically in SQL (no signal backing).
+     * 'signal_required' = signal backing present, caller must deliver the signal.
+     * 'conflict'        = signal_id row already claimed by a concurrent caller; skip re-signal.
+     * 'not_found'       = no pending escalation matched the metadata filter.
+     */
+    outcome: 'resolved' | 'signal_required' | 'conflict' | 'not_found';
     /** The resolved escalation (when outcome = 'resolved') */
     escalation?: LTEscalationRecord;
-    /** Signal info (when outcome = 'signal_required') */
+    /** Legacy conditionLT signal info (when signalId is set, caller uses handle.signal) */
     signalId?: string;
+    /** Atomic conditionLT signal key (when signalKey is set, caller uses SDK resolve to atomically mark+signal) */
+    signalKey?: string;
     escalationId?: string;
     workflowId?: string;
     workflowType?: string;

package/build/services/escalation/crud.js

@@ -402,10 +402,15 @@ async function resolveByMetadataAtomic(key, value, userId, resolverPayload, meta
         });
         return { outcome: 'resolved', escalation };
     }
+    // Signal_id row already claimed by a concurrent caller — skip re-signal to prevent duplicate delivery.
+    if (row.signal_id && row.signal_already_claimed) {
+        return { outcome: 'conflict', escalationId: row.target_id };
+    }
     // Signal-backed escalation — return the signal info for the caller to deliver.
     return {
         outcome: 'signal_required',
-        signalId: row.signal_id,
+        signalId: row.signal_id ?? undefined,
+        signalKey: row.signal_key ?? undefined,
         escalationId: row.target_id,
         workflowId: row.target_workflow_id,
         workflowType: row.target_workflow_type,

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

@@ -11,13 +11,23 @@ export declare const RELEASE_EXPIRED_CLAIMS = "UPDATE public.hmsh_escalations\nS
 /**
  * Atomic resolve by metadata with signal guard.
  *
- * Single query, two outcomes:
- * 1. No `metadata.signal_id` → claim + resolve atomically. `resolved` is populated.
- * 2. `metadata.signal_id` present → resolve CTE skips (guard in WHERE). `resolved`
- *    is null, but `target_id`, `signal_id`, and workflow routing are returned so
- *    the caller can signal the workflow directly.
+ * Single query, four outcomes:
+ * 1. No signal backing → claim + resolve atomically. `resolved` is populated.
+ * 2. `metadata.signal_id` present, row unclaimed → claim the row (preventing concurrent
+ *    duplicate signals via FOR UPDATE serialization), then return signal info so the
+ *    caller can signal the workflow. `signal_already_claimed = false`.
+ * 3. `metadata.signal_id` present, row already claimed and claim not expired →
+ *    a concurrent caller is handling the signal. `signal_already_claimed = true`;
+ *    caller returns 409 without re-signaling.
+ * 4. `signal_key` present (atomic conditionLT) → `claimed` and `resolved` both skip.
+ *    Caller invokes SDK resolve to atomically mark resolved + deliver the signal.
+ *
+ * Signal_id hardening: the `claimed` CTE runs for signal_id rows (previously excluded).
+ * This stamps `assigned_to` on the row inside the FOR UPDATE transaction, so a
+ * concurrent second caller sees `signal_already_claimed = true` and aborts.
+ * The `resolved` CTE still skips signal_id rows — the workflow resolves durably.
  *
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
  */
-export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND (target.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE public.hmsh_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";
+export declare const RESOLVE_BY_METADATA_ATOMIC = "WITH target AS MATERIALIZED (\n  SELECT *\n  FROM public.hmsh_escalations\n  WHERE metadata @> $1::jsonb\n    AND status = 'pending'\n    AND ($5::text[] IS NULL OR role = ANY($5))\n  ORDER BY priority ASC, created_at ASC\n  LIMIT 1\n  FOR UPDATE\n),\nclaimed AS (\n  UPDATE public.hmsh_escalations e\n  SET assigned_to = COALESCE(e.assigned_to, $2),\n      claimed_at = COALESCE(e.claimed_at, NOW()),\n      assigned_until = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.assigned_until\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      claim_expires_at = CASE\n        WHEN e.assigned_to IS NOT NULL AND e.assigned_until > NOW() THEN e.claim_expires_at\n        ELSE NOW() + INTERVAL '5 minutes' END,\n      metadata = CASE WHEN $4::jsonb IS NOT NULL\n        THEN COALESCE(e.metadata, '{}'::jsonb) || $4::jsonb\n        ELSE e.metadata END,\n      updated_at = NOW()\n  FROM target\n  WHERE e.id = target.id\n    AND target.signal_key IS NULL\n  RETURNING e.*\n),\nresolved AS (\n  UPDATE public.hmsh_escalations e\n  SET status = 'resolved',\n      resolved_at = NOW(),\n      resolver_payload = $3,\n      updated_at = NOW()\n  FROM claimed\n  WHERE e.id = claimed.id\n    AND (claimed.metadata->>'signal_id') IS NULL\n  RETURNING e.*\n)\nSELECT\n  resolved.*,\n  target.id AS target_id,\n  target.metadata->>'signal_id' AS signal_id,\n  target.signal_key AS signal_key,\n  target.workflow_id AS target_workflow_id,\n  target.workflow_type AS target_workflow_type,\n  target.task_queue AS target_task_queue,\n  (target.assigned_to IS NOT NULL\n    AND target.assigned_until IS NOT NULL\n    AND target.assigned_until > NOW()) AS signal_already_claimed,\n  CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome\nFROM target\nLEFT JOIN resolved ON resolved.id = target.id";

package/build/services/escalation/sql.js

@@ -34,11 +34,21 @@ WHERE status = 'pending'
 /**
  * Atomic resolve by metadata with signal guard.
  *
- * Single query, two outcomes:
- * 1. No `metadata.signal_id` → claim + resolve atomically. `resolved` is populated.
- * 2. `metadata.signal_id` present → resolve CTE skips (guard in WHERE). `resolved`
- *    is null, but `target_id`, `signal_id`, and workflow routing are returned so
- *    the caller can signal the workflow directly.
+ * Single query, four outcomes:
+ * 1. No signal backing → claim + resolve atomically. `resolved` is populated.
+ * 2. `metadata.signal_id` present, row unclaimed → claim the row (preventing concurrent
+ *    duplicate signals via FOR UPDATE serialization), then return signal info so the
+ *    caller can signal the workflow. `signal_already_claimed = false`.
+ * 3. `metadata.signal_id` present, row already claimed and claim not expired →
+ *    a concurrent caller is handling the signal. `signal_already_claimed = true`;
+ *    caller returns 409 without re-signaling.
+ * 4. `signal_key` present (atomic conditionLT) → `claimed` and `resolved` both skip.
+ *    Caller invokes SDK resolve to atomically mark resolved + deliver the signal.
+ *
+ * Signal_id hardening: the `claimed` CTE runs for signal_id rows (previously excluded).
+ * This stamps `assigned_to` on the row inside the FOR UPDATE transaction, so a
+ * concurrent second caller sees `signal_already_claimed = true` and aborts.
+ * The `resolved` CTE still skips signal_id rows — the workflow resolves durably.
  *
  * $1 = metadata filter (jsonb), $2 = userId, $3 = resolver_payload (jsonb),
  * $4 = metadata patch (jsonb, nullable), $5 = allowed roles (text[], null = no filter)
@@ -70,7 +80,7 @@ claimed AS (
       updated_at = NOW()
   FROM target
   WHERE e.id = target.id
-    AND (target.metadata->>'signal_id') IS NULL
+    AND target.signal_key IS NULL
   RETURNING e.*
 ),
 resolved AS (
@@ -81,15 +91,20 @@ resolved AS (
       updated_at = NOW()
   FROM claimed
   WHERE e.id = claimed.id
+    AND (claimed.metadata->>'signal_id') IS NULL
   RETURNING e.*
 )
 SELECT
   resolved.*,
   target.id AS target_id,
   target.metadata->>'signal_id' AS signal_id,
+  target.signal_key AS signal_key,
   target.workflow_id AS target_workflow_id,
   target.workflow_type AS target_workflow_type,
   target.task_queue AS target_task_queue,
+  (target.assigned_to IS NOT NULL
+    AND target.assigned_until IS NOT NULL
+    AND target.assigned_until > NOW()) AS signal_already_claimed,
   CASE WHEN resolved.id IS NOT NULL THEN 'resolved' ELSE 'signal_required' END AS outcome
 FROM target
 LEFT JOIN resolved ON resolved.id = target.id`;

package/build/services/yaml-workflow/deployer.js

@@ -49,6 +49,7 @@ const logger_1 = require("../../lib/logger");
 const system_events_1 = require("../../lib/events/system-events");
 const namespaceService = __importStar(require("../namespace"));
 const deployer_helpers_1 = require("./deployer-helpers");
+const pipe_validator_1 = require("./pipe-validator");
 // Re-export helpers so existing `import * from './deployer'` consumers keep working
 var deployer_helpers_2 = require("./deployer-helpers");
 Object.defineProperty(exports, "buildMergedYaml", { enumerable: true, get: function () { return deployer_helpers_2.buildMergedYaml; } });
@@ -90,6 +91,10 @@ async function deployAppId(appId, version) {
     await namespaceService.registerNamespace(appId);
     const mergedYaml = await (0, deployer_helpers_1.buildMergedYaml)(appId, version);
     logger_1.loggerRegistry.debug(`[yaml-workflow] merged YAML for ${appId} v${version}:\n${mergedYaml}`);
+    // Structural guard: reject YAML with malformed @pipe rows before they reach
+    // the HotMesh engine. A bad pipe passes deploy() silently but causes
+    // collation errors on every execution, poisoning the stream.
+    (0, pipe_validator_1.validatePipeStructure)(mergedYaml);
     const engine = await getEngine(appId);
     try {
         const manifest = await engine.deploy(mergedYaml);

package/build/services/yaml-workflow/pipe-validator.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Structural validator for HotMesh YAML pipe syntax.
+ *
+ * HotMesh collation errors are silent at deploy time but catastrophic at
+ * runtime — a single malformed @pipe in an activated workflow poisons the
+ * engine's stream, causing every execution attempt to fail with a
+ * collation-error until the database is wiped.
+ *
+ * This module provides:
+ *   validatePipeStructure  — throws on any structurally invalid @pipe
+ *   repairPipeStructure    — auto-repairs safe-to-fix patterns, then validates
+ *
+ * Call repairPipeStructure before storing or deploying any YAML.
+ *
+ * ## What constitutes a valid @pipe row
+ *
+ * An @pipe value is a YAML sequence. Each element (row) must be one of:
+ *   1. A YAML sequence (array)          — operands row OR function call row
+ *   2. A YAML mapping with '@pipe' key  — nested sub-pipe
+ *
+ * Invalid row types that cause collation errors:
+ *   - A bare string:  '{@object.create}'     → must be ['{@object.create}']
+ *   - A number/bool:  42, true               → must be wrapped in an array
+ *   - A double-nested sequence: [[...]]      → row itself is an array of arrays
+ */
+export interface PipeViolation {
+    path: string;
+    rowIndex: number;
+    rowValue: unknown;
+    message: string;
+    repairable: boolean;
+}
+/**
+ * Parse the YAML and check every @pipe for structural violations.
+ * Throws a descriptive error listing all violations if any are found.
+ */
+export declare function validatePipeStructure(yamlContent: string): void;
+/**
+ * Auto-repair safe violations (bare strings/scalars → array rows), then
+ * validate that no unfixable violations remain.
+ *
+ * Returns the repaired YAML string. Throws if unfixable violations exist.
+ */
+export declare function repairPipeStructure(yamlContent: string): string;

package/build/services/yaml-workflow/pipe-validator.js

@@ -0,0 +1,215 @@
+"use strict";
+/**
+ * Structural validator for HotMesh YAML pipe syntax.
+ *
+ * HotMesh collation errors are silent at deploy time but catastrophic at
+ * runtime — a single malformed @pipe in an activated workflow poisons the
+ * engine's stream, causing every execution attempt to fail with a
+ * collation-error until the database is wiped.
+ *
+ * This module provides:
+ *   validatePipeStructure  — throws on any structurally invalid @pipe
+ *   repairPipeStructure    — auto-repairs safe-to-fix patterns, then validates
+ *
+ * Call repairPipeStructure before storing or deploying any YAML.
+ *
+ * ## What constitutes a valid @pipe row
+ *
+ * An @pipe value is a YAML sequence. Each element (row) must be one of:
+ *   1. A YAML sequence (array)          — operands row OR function call row
+ *   2. A YAML mapping with '@pipe' key  — nested sub-pipe
+ *
+ * Invalid row types that cause collation errors:
+ *   - A bare string:  '{@object.create}'     → must be ['{@object.create}']
+ *   - A number/bool:  42, true               → must be wrapped in an array
+ *   - A double-nested sequence: [[...]]      → row itself is an array of arrays
+ */
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validatePipeStructure = validatePipeStructure;
+exports.repairPipeStructure = repairPipeStructure;
+const jsYaml = __importStar(require("js-yaml"));
+// ── internal traversal ────────────────────────────────────────────────────────
+function isPlainObject(v) {
+    return typeof v === 'object' && v !== null && !Array.isArray(v);
+}
+function collectPipeViolations(node, path, violations) {
+    if (Array.isArray(node)) {
+        node.forEach((item, i) => collectPipeViolations(item, `${path}[${i}]`, violations));
+        return;
+    }
+    if (!isPlainObject(node))
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        const childPath = `${path}.${key}`;
+        if (key === '@pipe') {
+            if (!Array.isArray(value)) {
+                violations.push({
+                    path: childPath,
+                    rowIndex: -1,
+                    rowValue: value,
+                    message: `@pipe value must be a sequence (array), got ${typeof value}`,
+                    repairable: false,
+                });
+                continue;
+            }
+            value.forEach((row, i) => {
+                if (Array.isArray(row)) {
+                    // Valid row — but check for double-nested arrays: [[...]]
+                    if (row.length > 0 && row.every((el) => Array.isArray(el))) {
+                        violations.push({
+                            path: childPath,
+                            rowIndex: i,
+                            rowValue: row,
+                            message: `row ${i} is a double-nested array (array of arrays) — each @pipe row must be a flat array`,
+                            repairable: false,
+                        });
+                    }
+                }
+                else if (isPlainObject(row) && '@pipe' in row) {
+                    // Valid nested sub-pipe — recurse into it
+                    collectPipeViolations(row, `${childPath}[${i}]`, violations);
+                }
+                else if (typeof row === 'string') {
+                    // '{@fn}' as bare string — repairable: wrap in array
+                    violations.push({
+                        path: childPath,
+                        rowIndex: i,
+                        rowValue: row,
+                        message: `row ${i} is a bare string "${row}" — must be an array row like ['${row}']`,
+                        repairable: true,
+                    });
+                }
+                else if (typeof row === 'number' || typeof row === 'boolean') {
+                    violations.push({
+                        path: childPath,
+                        rowIndex: i,
+                        rowValue: row,
+                        message: `row ${i} is a bare scalar ${JSON.stringify(row)} — must be wrapped in an array`,
+                        repairable: true,
+                    });
+                }
+                else {
+                    violations.push({
+                        path: childPath,
+                        rowIndex: i,
+                        rowValue: row,
+                        message: `row ${i} has unexpected type ${typeof row}`,
+                        repairable: false,
+                    });
+                }
+            });
+        }
+        else {
+            collectPipeViolations(value, childPath, violations);
+        }
+    }
+}
+// ── public API ────────────────────────────────────────────────────────────────
+/**
+ * Parse the YAML and check every @pipe for structural violations.
+ * Throws a descriptive error listing all violations if any are found.
+ */
+function validatePipeStructure(yamlContent) {
+    let parsed;
+    try {
+        parsed = jsYaml.load(yamlContent);
+    }
+    catch (err) {
+        throw new Error(`YAML parse error: ${err.message}`);
+    }
+    const violations = [];
+    collectPipeViolations(parsed, 'root', violations);
+    if (violations.length > 0) {
+        const detail = violations
+            .map((v) => `  • ${v.path}[${v.rowIndex}]: ${v.message}`)
+            .join('\n');
+        throw new Error(`Malformed @pipe structure — ${violations.length} violation(s) detected. ` +
+            `This YAML will cause HotMesh collation errors at runtime and must not be deployed.\n${detail}`);
+    }
+}
+/**
+ * Auto-repair safe violations (bare strings/scalars → array rows), then
+ * validate that no unfixable violations remain.
+ *
+ * Returns the repaired YAML string. Throws if unfixable violations exist.
+ */
+function repairPipeStructure(yamlContent) {
+    let parsed;
+    try {
+        parsed = jsYaml.load(yamlContent);
+    }
+    catch (err) {
+        throw new Error(`YAML parse error: ${err.message}`);
+    }
+    const repairCount = { n: 0 };
+    repairNode(parsed, repairCount);
+    if (repairCount.n > 0) {
+        // Re-serialize — use lineWidth: -1 to prevent wrapping
+        yamlContent = jsYaml.dump(parsed, { lineWidth: -1, noRefs: true, quotingType: "'" });
+    }
+    // Final validation pass — throws if unfixable violations remain
+    validatePipeStructure(yamlContent);
+    return yamlContent;
+}
+function repairNode(node, count) {
+    if (Array.isArray(node)) {
+        node.forEach((item) => repairNode(item, count));
+        return;
+    }
+    if (!isPlainObject(node))
+        return;
+    for (const [key, value] of Object.entries(node)) {
+        if (key === '@pipe' && Array.isArray(value)) {
+            const rows = value;
+            for (let i = 0; i < rows.length; i++) {
+                const row = rows[i];
+                if (typeof row === 'string' || typeof row === 'number' || typeof row === 'boolean') {
+                    rows[i] = [row];
+                    count.n++;
+                }
+                else if (isPlainObject(row) && '@pipe' in row) {
+                    repairNode(row, count);
+                }
+                else if (Array.isArray(row)) {
+                    repairNode(row, count);
+                }
+            }
+        }
+        else {
+            repairNode(value, count);
+        }
+    }
+}

package/build/system/workflows/mcp-workflow-builder/index.js

@@ -35,6 +35,7 @@ var __importStar = (this && this.__importStar) || (function () {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.mcpWorkflowBuilder = mcpWorkflowBuilder;
 const hotmesh_1 = require("@hotmeshio/hotmesh");
+const pipe_validator_1 = require("../../../services/yaml-workflow/pipe-validator");
 const activities = __importStar(require("./activities"));
 const prompts_1 = require("./prompts");
 const { loadBuilderTools, loadReferenceSection, callBuilderLLM, } = hotmesh_1.Durable.workflow.proxyActivities({
@@ -212,8 +213,20 @@ async function mcpWorkflowBuilder(envelope) {
                 });
                 continue;
             }
-            // Fix known @pipe anti-patterns before returning
-            const fixedYaml = fixPipePatterns(result.yaml);
+            // Fix known @pipe anti-patterns, then structurally validate —
+            // throws if unfixable violations remain, blocking deployment of poison YAML.
+            let fixedYaml = fixPipePatterns(result.yaml);
+            try {
+                fixedYaml = (0, pipe_validator_1.repairPipeStructure)(fixedYaml);
+            }
+            catch (pipeErr) {
+                messages.push({ role: 'assistant', content });
+                messages.push({
+                    role: 'user',
+                    content: `The generated YAML has structural @pipe errors that would cause runtime collation failures:\n${pipeErr.message}\n\nFix all @pipe rows: every row must be an array like ['{@fn}'] or [value1, value2]. Never use a bare string as a pipe row.`,
+                });
+                continue;
+            }
             return {
                 type: 'return',
                 data: {

package/build/tsconfig.tsbuildinfo

@@ -1 +1 @@
-{"root":["../index.ts","../vitest.config.ts","../vitest.integration.config.ts","../adapters/express.ts","../api/agent-subscriptions.ts","../api/agents.ts","../api/auth-sso.ts","../api/auth.ts","../api/bot-accounts.ts","../api/capabilities.ts","../api/controlplane.ts","../api/dba.ts","../api/diagnostics.ts","../api/exports.ts","../api/files.ts","../api/index.ts","../api/insight.ts","../api/knowledge.ts","../api/maintenance.ts","../api/namespaces.ts","../api/overview.ts","../api/pipelines.ts","../api/roles.ts","../api/settings.ts","../api/tasks.ts","../api/topics.ts","../api/users.ts","../api/workflow-sets.ts","../api/escalations/bulk.ts","../api/escalations/cancel.ts","../api/escalations/claim.ts","../api/escalations/create.ts","../api/escalations/helpers.ts","../api/escalations/index.ts","../api/escalations/list.ts","../api/escalations/metadata.ts","../api/escalations/resolve.ts","../api/escalations/single.ts","../api/mcp/index.ts","../api/mcp/servers.ts","../api/mcp/tools.ts","../api/workflows/config.ts","../api/workflows/discovery.ts","../api/workflows/index.ts","../api/workflows/invocation.ts","../api/yaml-workflows/cron.ts","../api/yaml-workflows/crud.ts","../api/yaml-workflows/deploy.ts","../api/yaml-workflows/helpers.ts","../api/yaml-workflows/index.ts","../api/yaml-workflows/versions.ts","../bin/ltc.ts","../lib/cli/auth.ts","../lib/cli/client.ts","../lib/cli/compile.ts","../lib/cli/format.ts","../lib/cli/init.ts","../lib/cli/output.ts","../lib/cli/scanner.ts","../lib/cli/types.ts","../lib/cli/commands/escalations.ts","../lib/cli/commands/knowledge.ts","../lib/cli/commands/mcp.ts","../lib/cli/commands/pipelines.ts","../lib/cli/commands/status.ts","../lib/cli/commands/streams.ts","../lib/cli/commands/users.ts","../lib/cli/commands/workflows.ts","../lib/db/index.ts","../lib/db/migrate.ts","../lib/events/callback.ts","../lib/events/index.ts","../lib/events/matching.ts","../lib/events/memory.ts","../lib/events/nats-ws-proxy.ts","../lib/events/nats.ts","../lib/events/publish.ts","../lib/events/socketio.ts","../lib/events/system-events.ts","../lib/logger/index.ts","../lib/logger/pino.ts","../lib/storage/index.ts","../lib/storage/local.ts","../lib/storage/mime.ts","../lib/storage/s3.ts","../lib/storage/types.ts","../lib/telemetry/honeycomb.ts","../lib/telemetry/index.ts","../modules/auth.ts","../modules/config.ts","../modules/defaults.ts","../modules/ltconfig.ts","../modules/maintenance.ts","../modules/sso.ts","../modules/utils.ts","../routes/agents.ts","../routes/auth-sso.ts","../routes/auth.ts","../routes/bot-accounts.ts","../routes/capabilities.ts","../routes/controlplane.ts","../routes/dba.ts","../routes/delegation.ts","../routes/diagnostics.ts","../routes/docs.ts","../routes/exports.ts","../routes/file-browser.ts","../routes/files.ts","../routes/index.ts","../routes/insight.ts","../routes/knowledge.ts","../routes/maintenance.ts","../routes/mcp-endpoint.ts","../routes/mcp.ts","../routes/namespaces.ts","../routes/nats-credentials.ts","../routes/oauth.ts","../routes/overview.ts","../routes/pipelines.ts","../routes/roles.ts","../routes/settings.ts","../routes/tasks.ts","../routes/topics.ts","../routes/users.ts","../routes/workflow-sets.ts","../routes/escalations/bulk.ts","../routes/escalations/index.ts","../routes/escalations/list.ts","../routes/escalations/metadata.ts","../routes/escalations/resolve.ts","../routes/escalations/single.ts","../routes/workflows/config.ts","../routes/workflows/discovery.ts","../routes/workflows/index.ts","../routes/workflows/invocation.ts","../routes/yaml-workflows/cron.ts","../routes/yaml-workflows/crud.ts","../routes/yaml-workflows/deployment.ts","../routes/yaml-workflows/index.ts","../routes/yaml-workflows/versions.ts","../scripts/process-helpers.ts","../scripts/process.ts","../scripts/token.ts","../sdk/index.ts","../services/dba.ts","../services/hotmesh-utils.ts","../services/workflow-invocation.ts","../services/agent/index.ts","../services/agent/input-mapper.ts","../services/agent/sql.ts","../services/agent/subscription-sql.ts","../services/agent/subscriptions.ts","../services/agent/trigger-registry.ts","../services/auth/bot-api-key.ts","../services/auth/delegation.ts","../services/auth/index.ts","../services/auth/service-token.ts","../services/auth/sql.ts","../services/config/cache.ts","../services/config/index.ts","../services/config/provider.ts","../services/config/read.ts","../services/config/sql.ts","../services/config/write.ts","../services/controlplane/index.ts","../services/controlplane/quorum-bridge.ts","../services/controlplane/sql.ts","../services/controlplane/stream-messages-sql.ts","../services/controlplane/types.ts","../services/cron/index.ts","../services/diagnostics/index.ts","../services/diagnostics/patterns.ts","../services/escalation/bulk.ts","../services/escalation/client.ts","../services/escalation/crud.ts","../services/escalation/index.ts","../services/escalation/map.ts","../services/escalation/queries.ts","../services/escalation/sql.ts","../services/escalation/types.ts","../services/escalation-strategy/default.ts","../services/escalation-strategy/index.ts","../services/escalation-strategy/mcp.ts","../services/export/client.ts","../services/export/index.ts","../services/export/post-process.ts","../services/export/types.ts","../services/iam/activity.ts","../services/iam/bots.ts","../services/iam/context.ts","../services/iam/credentials.ts","../services/iam/envelope.ts","../services/iam/ephemeral.ts","../services/iam/index.ts","../services/iam/principal.ts","../services/iam/resolve.ts","../services/iam/sql.ts","../services/insight/index.ts","../services/insight/prompts.ts","../services/interceptor/activity-interceptor.ts","../services/interceptor/completion.ts","../services/interceptor/context.ts","../services/interceptor/escalation.ts","../services/interceptor/index.ts","../services/interceptor/lifecycle.ts","../services/interceptor/state.ts","../services/interceptor/types.ts","../services/interceptor/activities/config.ts","../services/interceptor/activities/escalation.ts","../services/interceptor/activities/index.ts","../services/interceptor/activities/task.ts","../services/interceptor/activities/workflow.ts","../services/llm/detect.ts","../services/llm/index.ts","../services/llm/translate.ts","../services/llm/types.ts","../services/llm/providers/anthropic.ts","../services/llm/providers/openai.ts","../services/maintenance/index.ts","../services/mcp/adapter.ts","../services/mcp/db.ts","../services/mcp/exposure.ts","../services/mcp/external-server.ts","../services/mcp/index.ts","../services/mcp/register-tool.ts","../services/mcp/seed-service-account.ts","../services/mcp/server-lifecycle.ts","../services/mcp/server-tools.ts","../services/mcp/server.ts","../services/mcp/sql.ts","../services/mcp/types.ts","../services/mcp/workflow-compiler-server.ts","../services/mcp/workflow-server.ts","../services/mcp/client/connection-dispatch.ts","../services/mcp/client/connection-lifecycle.ts","../services/mcp/client/connection-test.ts","../services/mcp/client/connection.ts","../services/mcp/client/index.ts","../services/mcp/client/tools.ts","../services/mcp/db-server/index.ts","../services/mcp/db-server/schemas.ts","../services/mcp/db-server/tools.ts","../services/mcp/playwright-server/index.ts","../services/mcp/playwright-server/lifecycle.ts","../services/mcp/playwright-server/schemas.ts","../services/mcp/playwright-server/tools.ts","../services/namespace/index.ts","../services/namespace/sql.ts","../services/namespace/types.ts","../services/oauth/crypto.ts","../services/oauth/db.ts","../services/oauth/index.ts","../services/oauth/sql.ts","../services/oauth/state.ts","../services/oauth/providers/anthropic.ts","../services/oauth/providers/github.ts","../services/oauth/providers/google.ts","../services/oauth/providers/index.ts","../services/oauth/providers/microsoft.ts","../services/oauth/providers/mock.ts","../services/oauth/providers/registry.ts","../services/oauth/providers/types.ts","../services/orchestrator/condition.ts","../services/orchestrator/index.ts","../services/orchestrator/types.ts","../services/overview/index.ts","../services/overview/sql.ts","../services/pipelines/enrichment.ts","../services/pipelines/events.ts","../services/pipelines/execution-builder.ts","../services/pipelines/index.ts","../services/pipelines/queries.ts","../services/pipelines/sql.ts","../services/pipelines/types.ts","../services/role/index.ts","../services/role/sql.ts","../services/role/types.ts","../services/task/crud.ts","../services/task/index.ts","../services/task/process.ts","../services/task/resolve.ts","../services/task/sql.ts","../services/task/types.ts","../services/topics/index.ts","../services/topics/sql.ts","../services/topics/system-topics.ts","../services/user/auth.ts","../services/user/crud.ts","../services/user/index.ts","../services/user/rbac.ts","../services/user/roles.ts","../services/user/seed-admin.ts","../services/user/sql.ts","../services/user/sso-provision.ts","../services/user/types.ts","../services/workers/registry.ts","../services/workflow-sets/db.ts","../services/workflow-sets/index.ts","../services/workflow-sets/sql.ts","../services/yaml-workflow/builder-regenerate.ts","../services/yaml-workflow/db-utils.ts","../services/yaml-workflow/db-versions.ts","../services/yaml-workflow/db.ts","../services/yaml-workflow/deployer-helpers.ts","../services/yaml-workflow/deployer.ts","../services/yaml-workflow/generator.ts","../services/yaml-workflow/index.ts","../services/yaml-workflow/input-analyzer-helpers.ts","../services/yaml-workflow/input-analyzer.ts","../services/yaml-workflow/invoke.ts","../services/yaml-workflow/sql.ts","../services/yaml-workflow/types.ts","../services/yaml-workflow/durable-compiler/index.ts","../services/yaml-workflow/durable-compiler/parser.ts","../services/yaml-workflow/durable-compiler/prompts.ts","../services/yaml-workflow/durable-compiler/types.ts","../services/yaml-workflow/pattern-detector/array-source.ts","../services/yaml-workflow/pattern-detector/collapse.ts","../services/yaml-workflow/pattern-detector/index.ts","../services/yaml-workflow/pattern-detector/run-detection.ts","../services/yaml-workflow/pattern-detector/types.ts","../services/yaml-workflow/pipeline/analyze.ts","../services/yaml-workflow/pipeline/extract-helpers.ts","../services/yaml-workflow/pipeline/extract.ts","../services/yaml-workflow/pipeline/index.ts","../services/yaml-workflow/pipeline/prompt-templates.ts","../services/yaml-workflow/pipeline/prompts.ts","../services/yaml-workflow/pipeline/validate.ts","../services/yaml-workflow/pipeline/build/dag-assembly.ts","../services/yaml-workflow/pipeline/build/dag.ts","../services/yaml-workflow/pipeline/build/index.ts","../services/yaml-workflow/pipeline/build/iteration.ts","../services/yaml-workflow/pipeline/build/metadata.ts","../services/yaml-workflow/pipeline/build/transform.ts","../services/yaml-workflow/pipeline/build/utils.ts","../services/yaml-workflow/pipeline/build/wiring.ts","../services/yaml-workflow/pipeline/compile/index.ts","../services/yaml-workflow/pipeline/compile/llm-call.ts","../services/yaml-workflow/pipeline/compile/parse-plan.ts","../services/yaml-workflow/pipeline/compile/summarize.ts","../services/yaml-workflow/workers/callbacks.ts","../services/yaml-workflow/workers/events.ts","../services/yaml-workflow/workers/index.ts","../services/yaml-workflow/workers/register.ts","../services/yaml-workflow/workers/scope.ts","../start/adapters.ts","../start/config.ts","../start/graph-workflows.ts","../start/index.ts","../start/server.ts","../start/socket-auth.ts","../start/workers.ts","../system/index.ts","../system/activities/claude-code.ts","../system/activities/file-storage.ts","../system/activities/http.ts","../system/activities/knowledge.ts","../system/activities/oauth.ts","../system/activities/schema-exchange.ts","../system/activities/sql.ts","../system/activities/triage/cache.ts","../system/activities/triage/context.ts","../system/activities/triage/discovery.ts","../system/activities/triage/index.ts","../system/activities/triage/llm.ts","../system/activities/triage/tools.ts","../system/mcp-servers/claude-code.ts","../system/mcp-servers/docs.ts","../system/mcp-servers/events.ts","../system/mcp-servers/file-storage.ts","../system/mcp-servers/http-fetch.ts","../system/mcp-servers/human-queue-schemas.ts","../system/mcp-servers/human-queue.ts","../system/mcp-servers/knowledge.ts","../system/mcp-servers/oauth.ts","../system/mcp-servers/schema-exchange.ts","../system/mcp-servers/translation.ts","../system/mcp-servers/vision-prompts.ts","../system/mcp-servers/vision.ts","../system/mcp-servers/workflow-compiler.ts","../system/mcp-servers/workflow.ts","../system/mcp-servers/admin/agent-subscriptions.ts","../system/mcp-servers/admin/agents.ts","../system/mcp-servers/admin/bot-accounts.ts","../system/mcp-servers/admin/controlplane.ts","../system/mcp-servers/admin/diagnostics.ts","../system/mcp-servers/admin/escalations.ts","../system/mcp-servers/admin/exports.ts","../system/mcp-servers/admin/index.ts","../system/mcp-servers/admin/maintenance.ts","../system/mcp-servers/admin/mcp-servers.ts","../system/mcp-servers/admin/overview.ts","../system/mcp-servers/admin/pipelines.ts","../system/mcp-servers/admin/schemas.ts","../system/mcp-servers/admin/settings.ts","../system/mcp-servers/admin/tasks.ts","../system/mcp-servers/admin/topics.ts","../system/mcp-servers/admin/users.ts","../system/mcp-servers/admin/workflow-config.ts","../system/mcp-servers/admin/workflows.ts","../system/mcp-servers/admin/yaml-workflows.ts","../system/mcp-servers/db-query/index.ts","../system/mcp-servers/db-query/schemas.ts","../system/mcp-servers/db-query/tools.ts","../system/seed/index.ts","../system/seed/tool-manifests-admin.ts","../system/seed/tool-manifests-data.ts","../system/seed/tool-manifests-escalation.ts","../system/seed/tool-manifests-events.ts","../system/seed/tool-manifests-knowledge.ts","../system/seed/tool-manifests-workflows.ts","../system/workflows/tool-result-guard.ts","../system/workflows/capability-invoke/activities.ts","../system/workflows/capability-invoke/index.ts","../system/workflows/mcp-deterministic/activities.ts","../system/workflows/mcp-deterministic/index.ts","../system/workflows/mcp-query/index.ts","../system/workflows/mcp-query/prompts.ts","../system/workflows/mcp-query/strategy-advisors.ts","../system/workflows/mcp-query/types.ts","../system/workflows/mcp-query/activities/caches.ts","../system/workflows/mcp-query/activities/discovery.ts","../system/workflows/mcp-query/activities/index.ts","../system/workflows/mcp-query/activities/llm.ts","../system/workflows/mcp-query/activities/tool-executor.ts","../system/workflows/mcp-query/activities/tool-loader.ts","../system/workflows/mcp-query-router/activities.ts","../system/workflows/mcp-query-router/index.ts","../system/workflows/mcp-query-router/prompts.ts","../system/workflows/mcp-triage/activities-proxy.ts","../system/workflows/mcp-triage/index.ts","../system/workflows/mcp-triage/prompts.ts","../system/workflows/mcp-triage/response-builders.ts","../system/workflows/mcp-triage/response.ts","../system/workflows/mcp-triage/types.ts","../system/workflows/mcp-triage-deterministic/activities.ts","../system/workflows/mcp-triage-deterministic/index.ts","../system/workflows/mcp-triage-router/activities.ts","../system/workflows/mcp-triage-router/index.ts","../system/workflows/mcp-workflow-builder/index.ts","../system/workflows/mcp-workflow-builder/prompts.ts","../system/workflows/mcp-workflow-builder/activities/caches.ts","../system/workflows/mcp-workflow-builder/activities/index.ts","../system/workflows/mcp-workflow-builder/activities/llm.ts","../system/workflows/mcp-workflow-builder/activities/tool-loader.ts","../system/workflows/mcp-workflow-planner/index.ts","../system/workflows/mcp-workflow-planner/prompts.ts","../system/workflows/mcp-workflow-planner/activities/analyze.ts","../system/workflows/mcp-workflow-planner/activities/index.ts","../system/workflows/mcp-workflow-planner/activities/persist.ts","../system/workflows/mcp-workflow-planner/activities/plan.ts","../system/workflows/shared/discovery.ts","../system/workflows/shared/index.ts","../system/workflows/shared/llm-caller.ts","../system/workflows/shared/prompts.ts","../system/workflows/shared/strategy-advisors.ts","../system/workflows/shared/tool-executor.ts","../system/workflows/shared/tool-loader.ts","../system/workflows/shared/types.ts","../types/agent.ts","../types/auth.ts","../types/config.ts","../types/delegation.ts","../types/discovery.ts","../types/envelope.ts","../types/escalation-strategy.ts","../types/escalation.ts","../types/events.ts","../types/export.ts","../types/express.d.ts","../types/index.ts","../types/logger.ts","../types/maintenance.ts","../types/mcp.ts","../types/oauth.ts","../types/sdk.ts","../types/startup.ts","../types/task.ts","../types/telemetry.ts","../types/tool-context.ts","../types/user.ts","../types/workflow-set.ts","../types/workflow.ts","../types/yaml-workflow.ts","../workers/index.ts"],"version":"5.9.3"}
+{"root":["../index.ts","../vitest.config.ts","../vitest.integration.config.ts","../adapters/express.ts","../api/agent-subscriptions.ts","../api/agents.ts","../api/auth-sso.ts","../api/auth.ts","../api/bot-accounts.ts","../api/capabilities.ts","../api/controlplane.ts","../api/dba.ts","../api/diagnostics.ts","../api/exports.ts","../api/files.ts","../api/index.ts","../api/insight.ts","../api/knowledge.ts","../api/maintenance.ts","../api/namespaces.ts","../api/overview.ts","../api/pipelines.ts","../api/roles.ts","../api/settings.ts","../api/tasks.ts","../api/topics.ts","../api/users.ts","../api/workflow-sets.ts","../api/escalations/bulk.ts","../api/escalations/cancel.ts","../api/escalations/claim.ts","../api/escalations/create.ts","../api/escalations/helpers.ts","../api/escalations/index.ts","../api/escalations/list.ts","../api/escalations/metadata.ts","../api/escalations/resolve.ts","../api/escalations/single.ts","../api/mcp/index.ts","../api/mcp/servers.ts","../api/mcp/tools.ts","../api/workflows/config.ts","../api/workflows/discovery.ts","../api/workflows/index.ts","../api/workflows/invocation.ts","../api/yaml-workflows/cron.ts","../api/yaml-workflows/crud.ts","../api/yaml-workflows/deploy.ts","../api/yaml-workflows/helpers.ts","../api/yaml-workflows/index.ts","../api/yaml-workflows/versions.ts","../bin/ltc.ts","../lib/cli/auth.ts","../lib/cli/client.ts","../lib/cli/compile.ts","../lib/cli/format.ts","../lib/cli/init.ts","../lib/cli/output.ts","../lib/cli/scanner.ts","../lib/cli/types.ts","../lib/cli/commands/escalations.ts","../lib/cli/commands/knowledge.ts","../lib/cli/commands/mcp.ts","../lib/cli/commands/pipelines.ts","../lib/cli/commands/status.ts","../lib/cli/commands/streams.ts","../lib/cli/commands/users.ts","../lib/cli/commands/workflows.ts","../lib/db/index.ts","../lib/db/migrate.ts","../lib/events/callback.ts","../lib/events/index.ts","../lib/events/matching.ts","../lib/events/memory.ts","../lib/events/nats-ws-proxy.ts","../lib/events/nats.ts","../lib/events/publish.ts","../lib/events/socketio.ts","../lib/events/system-events.ts","../lib/logger/index.ts","../lib/logger/pino.ts","../lib/storage/index.ts","../lib/storage/local.ts","../lib/storage/mime.ts","../lib/storage/s3.ts","../lib/storage/types.ts","../lib/telemetry/honeycomb.ts","../lib/telemetry/index.ts","../modules/auth.ts","../modules/config.ts","../modules/defaults.ts","../modules/ltconfig.ts","../modules/maintenance.ts","../modules/sso.ts","../modules/utils.ts","../routes/agents.ts","../routes/auth-sso.ts","../routes/auth.ts","../routes/bot-accounts.ts","../routes/capabilities.ts","../routes/controlplane.ts","../routes/dba.ts","../routes/delegation.ts","../routes/diagnostics.ts","../routes/docs.ts","../routes/exports.ts","../routes/file-browser.ts","../routes/files.ts","../routes/index.ts","../routes/insight.ts","../routes/knowledge.ts","../routes/maintenance.ts","../routes/mcp-endpoint.ts","../routes/mcp.ts","../routes/namespaces.ts","../routes/nats-credentials.ts","../routes/oauth.ts","../routes/overview.ts","../routes/pipelines.ts","../routes/roles.ts","../routes/settings.ts","../routes/tasks.ts","../routes/topics.ts","../routes/users.ts","../routes/workflow-sets.ts","../routes/escalations/bulk.ts","../routes/escalations/index.ts","../routes/escalations/list.ts","../routes/escalations/metadata.ts","../routes/escalations/resolve.ts","../routes/escalations/single.ts","../routes/workflows/config.ts","../routes/workflows/discovery.ts","../routes/workflows/index.ts","../routes/workflows/invocation.ts","../routes/yaml-workflows/cron.ts","../routes/yaml-workflows/crud.ts","../routes/yaml-workflows/deployment.ts","../routes/yaml-workflows/index.ts","../routes/yaml-workflows/versions.ts","../scripts/process-helpers.ts","../scripts/process.ts","../scripts/token.ts","../sdk/index.ts","../services/dba.ts","../services/hotmesh-utils.ts","../services/workflow-invocation.ts","../services/agent/index.ts","../services/agent/input-mapper.ts","../services/agent/sql.ts","../services/agent/subscription-sql.ts","../services/agent/subscriptions.ts","../services/agent/trigger-registry.ts","../services/auth/bot-api-key.ts","../services/auth/delegation.ts","../services/auth/index.ts","../services/auth/service-token.ts","../services/auth/sql.ts","../services/config/cache.ts","../services/config/index.ts","../services/config/provider.ts","../services/config/read.ts","../services/config/sql.ts","../services/config/write.ts","../services/controlplane/index.ts","../services/controlplane/quorum-bridge.ts","../services/controlplane/sql.ts","../services/controlplane/stream-messages-sql.ts","../services/controlplane/types.ts","../services/cron/index.ts","../services/diagnostics/index.ts","../services/diagnostics/patterns.ts","../services/escalation/bulk.ts","../services/escalation/client.ts","../services/escalation/crud.ts","../services/escalation/index.ts","../services/escalation/map.ts","../services/escalation/queries.ts","../services/escalation/sql.ts","../services/escalation/types.ts","../services/escalation-strategy/default.ts","../services/escalation-strategy/index.ts","../services/escalation-strategy/mcp.ts","../services/export/client.ts","../services/export/index.ts","../services/export/post-process.ts","../services/export/types.ts","../services/iam/activity.ts","../services/iam/bots.ts","../services/iam/context.ts","../services/iam/credentials.ts","../services/iam/envelope.ts","../services/iam/ephemeral.ts","../services/iam/index.ts","../services/iam/principal.ts","../services/iam/resolve.ts","../services/iam/sql.ts","../services/insight/index.ts","../services/insight/prompts.ts","../services/interceptor/activity-interceptor.ts","../services/interceptor/completion.ts","../services/interceptor/context.ts","../services/interceptor/escalation.ts","../services/interceptor/index.ts","../services/interceptor/lifecycle.ts","../services/interceptor/state.ts","../services/interceptor/types.ts","../services/interceptor/activities/config.ts","../services/interceptor/activities/escalation.ts","../services/interceptor/activities/index.ts","../services/interceptor/activities/task.ts","../services/interceptor/activities/workflow.ts","../services/llm/detect.ts","../services/llm/index.ts","../services/llm/translate.ts","../services/llm/types.ts","../services/llm/providers/anthropic.ts","../services/llm/providers/openai.ts","../services/maintenance/index.ts","../services/mcp/adapter.ts","../services/mcp/db.ts","../services/mcp/exposure.ts","../services/mcp/external-server.ts","../services/mcp/index.ts","../services/mcp/register-tool.ts","../services/mcp/seed-service-account.ts","../services/mcp/server-lifecycle.ts","../services/mcp/server-tools.ts","../services/mcp/server.ts","../services/mcp/sql.ts","../services/mcp/types.ts","../services/mcp/workflow-compiler-server.ts","../services/mcp/workflow-server.ts","../services/mcp/client/connection-dispatch.ts","../services/mcp/client/connection-lifecycle.ts","../services/mcp/client/connection-test.ts","../services/mcp/client/connection.ts","../services/mcp/client/index.ts","../services/mcp/client/tools.ts","../services/mcp/db-server/index.ts","../services/mcp/db-server/schemas.ts","../services/mcp/db-server/tools.ts","../services/mcp/playwright-server/index.ts","../services/mcp/playwright-server/lifecycle.ts","../services/mcp/playwright-server/schemas.ts","../services/mcp/playwright-server/tools.ts","../services/namespace/index.ts","../services/namespace/sql.ts","../services/namespace/types.ts","../services/oauth/crypto.ts","../services/oauth/db.ts","../services/oauth/index.ts","../services/oauth/sql.ts","../services/oauth/state.ts","../services/oauth/providers/anthropic.ts","../services/oauth/providers/github.ts","../services/oauth/providers/google.ts","../services/oauth/providers/index.ts","../services/oauth/providers/microsoft.ts","../services/oauth/providers/mock.ts","../services/oauth/providers/registry.ts","../services/oauth/providers/types.ts","../services/orchestrator/condition.ts","../services/orchestrator/index.ts","../services/orchestrator/types.ts","../services/overview/index.ts","../services/overview/sql.ts","../services/pipelines/enrichment.ts","../services/pipelines/events.ts","../services/pipelines/execution-builder.ts","../services/pipelines/index.ts","../services/pipelines/queries.ts","../services/pipelines/sql.ts","../services/pipelines/types.ts","../services/role/index.ts","../services/role/sql.ts","../services/role/types.ts","../services/task/crud.ts","../services/task/index.ts","../services/task/process.ts","../services/task/resolve.ts","../services/task/sql.ts","../services/task/types.ts","../services/topics/index.ts","../services/topics/sql.ts","../services/topics/system-topics.ts","../services/user/auth.ts","../services/user/crud.ts","../services/user/index.ts","../services/user/rbac.ts","../services/user/roles.ts","../services/user/seed-admin.ts","../services/user/sql.ts","../services/user/sso-provision.ts","../services/user/types.ts","../services/workers/registry.ts","../services/workflow-sets/db.ts","../services/workflow-sets/index.ts","../services/workflow-sets/sql.ts","../services/yaml-workflow/builder-regenerate.ts","../services/yaml-workflow/db-utils.ts","../services/yaml-workflow/db-versions.ts","../services/yaml-workflow/db.ts","../services/yaml-workflow/deployer-helpers.ts","../services/yaml-workflow/deployer.ts","../services/yaml-workflow/generator.ts","../services/yaml-workflow/index.ts","../services/yaml-workflow/input-analyzer-helpers.ts","../services/yaml-workflow/input-analyzer.ts","../services/yaml-workflow/invoke.ts","../services/yaml-workflow/pipe-validator.ts","../services/yaml-workflow/sql.ts","../services/yaml-workflow/types.ts","../services/yaml-workflow/durable-compiler/index.ts","../services/yaml-workflow/durable-compiler/parser.ts","../services/yaml-workflow/durable-compiler/prompts.ts","../services/yaml-workflow/durable-compiler/types.ts","../services/yaml-workflow/pattern-detector/array-source.ts","../services/yaml-workflow/pattern-detector/collapse.ts","../services/yaml-workflow/pattern-detector/index.ts","../services/yaml-workflow/pattern-detector/run-detection.ts","../services/yaml-workflow/pattern-detector/types.ts","../services/yaml-workflow/pipeline/analyze.ts","../services/yaml-workflow/pipeline/extract-helpers.ts","../services/yaml-workflow/pipeline/extract.ts","../services/yaml-workflow/pipeline/index.ts","../services/yaml-workflow/pipeline/prompt-templates.ts","../services/yaml-workflow/pipeline/prompts.ts","../services/yaml-workflow/pipeline/validate.ts","../services/yaml-workflow/pipeline/build/dag-assembly.ts","../services/yaml-workflow/pipeline/build/dag.ts","../services/yaml-workflow/pipeline/build/index.ts","../services/yaml-workflow/pipeline/build/iteration.ts","../services/yaml-workflow/pipeline/build/metadata.ts","../services/yaml-workflow/pipeline/build/transform.ts","../services/yaml-workflow/pipeline/build/utils.ts","../services/yaml-workflow/pipeline/build/wiring.ts","../services/yaml-workflow/pipeline/compile/index.ts","../services/yaml-workflow/pipeline/compile/llm-call.ts","../services/yaml-workflow/pipeline/compile/parse-plan.ts","../services/yaml-workflow/pipeline/compile/summarize.ts","../services/yaml-workflow/workers/callbacks.ts","../services/yaml-workflow/workers/events.ts","../services/yaml-workflow/workers/index.ts","../services/yaml-workflow/workers/register.ts","../services/yaml-workflow/workers/scope.ts","../start/adapters.ts","../start/config.ts","../start/graph-workflows.ts","../start/index.ts","../start/server.ts","../start/socket-auth.ts","../start/workers.ts","../system/index.ts","../system/activities/claude-code.ts","../system/activities/file-storage.ts","../system/activities/http.ts","../system/activities/knowledge.ts","../system/activities/oauth.ts","../system/activities/schema-exchange.ts","../system/activities/sql.ts","../system/activities/triage/cache.ts","../system/activities/triage/context.ts","../system/activities/triage/discovery.ts","../system/activities/triage/index.ts","../system/activities/triage/llm.ts","../system/activities/triage/tools.ts","../system/mcp-servers/claude-code.ts","../system/mcp-servers/docs.ts","../system/mcp-servers/events.ts","../system/mcp-servers/file-storage.ts","../system/mcp-servers/http-fetch.ts","../system/mcp-servers/human-queue-schemas.ts","../system/mcp-servers/human-queue.ts","../system/mcp-servers/knowledge.ts","../system/mcp-servers/oauth.ts","../system/mcp-servers/schema-exchange.ts","../system/mcp-servers/translation.ts","../system/mcp-servers/vision-prompts.ts","../system/mcp-servers/vision.ts","../system/mcp-servers/workflow-compiler.ts","../system/mcp-servers/workflow.ts","../system/mcp-servers/admin/agent-subscriptions.ts","../system/mcp-servers/admin/agents.ts","../system/mcp-servers/admin/bot-accounts.ts","../system/mcp-servers/admin/controlplane.ts","../system/mcp-servers/admin/diagnostics.ts","../system/mcp-servers/admin/escalations.ts","../system/mcp-servers/admin/exports.ts","../system/mcp-servers/admin/index.ts","../system/mcp-servers/admin/maintenance.ts","../system/mcp-servers/admin/mcp-servers.ts","../system/mcp-servers/admin/overview.ts","../system/mcp-servers/admin/pipelines.ts","../system/mcp-servers/admin/schemas.ts","../system/mcp-servers/admin/settings.ts","../system/mcp-servers/admin/tasks.ts","../system/mcp-servers/admin/topics.ts","../system/mcp-servers/admin/users.ts","../system/mcp-servers/admin/workflow-config.ts","../system/mcp-servers/admin/workflows.ts","../system/mcp-servers/admin/yaml-workflows.ts","../system/mcp-servers/db-query/index.ts","../system/mcp-servers/db-query/schemas.ts","../system/mcp-servers/db-query/tools.ts","../system/seed/index.ts","../system/seed/tool-manifests-admin.ts","../system/seed/tool-manifests-data.ts","../system/seed/tool-manifests-escalation.ts","../system/seed/tool-manifests-events.ts","../system/seed/tool-manifests-knowledge.ts","../system/seed/tool-manifests-workflows.ts","../system/workflows/tool-result-guard.ts","../system/workflows/capability-invoke/activities.ts","../system/workflows/capability-invoke/index.ts","../system/workflows/mcp-deterministic/activities.ts","../system/workflows/mcp-deterministic/index.ts","../system/workflows/mcp-query/index.ts","../system/workflows/mcp-query/prompts.ts","../system/workflows/mcp-query/strategy-advisors.ts","../system/workflows/mcp-query/types.ts","../system/workflows/mcp-query/activities/caches.ts","../system/workflows/mcp-query/activities/discovery.ts","../system/workflows/mcp-query/activities/index.ts","../system/workflows/mcp-query/activities/llm.ts","../system/workflows/mcp-query/activities/tool-executor.ts","../system/workflows/mcp-query/activities/tool-loader.ts","../system/workflows/mcp-query-router/activities.ts","../system/workflows/mcp-query-router/index.ts","../system/workflows/mcp-query-router/prompts.ts","../system/workflows/mcp-triage/activities-proxy.ts","../system/workflows/mcp-triage/index.ts","../system/workflows/mcp-triage/prompts.ts","../system/workflows/mcp-triage/response-builders.ts","../system/workflows/mcp-triage/response.ts","../system/workflows/mcp-triage/types.ts","../system/workflows/mcp-triage-deterministic/activities.ts","../system/workflows/mcp-triage-deterministic/index.ts","../system/workflows/mcp-triage-router/activities.ts","../system/workflows/mcp-triage-router/index.ts","../system/workflows/mcp-workflow-builder/index.ts","../system/workflows/mcp-workflow-builder/prompts.ts","../system/workflows/mcp-workflow-builder/activities/caches.ts","../system/workflows/mcp-workflow-builder/activities/index.ts","../system/workflows/mcp-workflow-builder/activities/llm.ts","../system/workflows/mcp-workflow-builder/activities/tool-loader.ts","../system/workflows/mcp-workflow-planner/index.ts","../system/workflows/mcp-workflow-planner/prompts.ts","../system/workflows/mcp-workflow-planner/activities/analyze.ts","../system/workflows/mcp-workflow-planner/activities/index.ts","../system/workflows/mcp-workflow-planner/activities/persist.ts","../system/workflows/mcp-workflow-planner/activities/plan.ts","../system/workflows/shared/discovery.ts","../system/workflows/shared/index.ts","../system/workflows/shared/llm-caller.ts","../system/workflows/shared/prompts.ts","../system/workflows/shared/strategy-advisors.ts","../system/workflows/shared/tool-executor.ts","../system/workflows/shared/tool-loader.ts","../system/workflows/shared/types.ts","../types/agent.ts","../types/auth.ts","../types/config.ts","../types/delegation.ts","../types/discovery.ts","../types/envelope.ts","../types/escalation-strategy.ts","../types/escalation.ts","../types/events.ts","../types/export.ts","../types/express.d.ts","../types/index.ts","../types/logger.ts","../types/maintenance.ts","../types/mcp.ts","../types/oauth.ts","../types/sdk.ts","../types/startup.ts","../types/task.ts","../types/telemetry.ts","../types/tool-context.ts","../types/user.ts","../types/workflow-set.ts","../types/workflow.ts","../types/yaml-workflow.ts","../workers/index.ts"],"version":"5.9.3"}

package/docs/hitl-guide.md

@@ -594,6 +594,54 @@ metadata: {
 
 ---
 
+## Resolving from System Code
+
+When a backend service (not the dashboard UI) needs to resolve an escalation — for example, an ingress handler that receives a webhook or processes a domain event — use the escalation SDK methods directly.
+
+### By escalation ID
+
+Use when you already have the escalation UUID (e.g. stored in your own DB alongside the order):
+
+```typescript
+const result = await lt.escalations.resolve({
+  id: escalationId,
+  resolverPayload: { approved: true, targetStatus: 'ready' },
+});
+```
+
+This routes through the full resolution path and works for all escalation types — atomic `conditionLT` (signal_key), legacy `conditionLT` (signal_id), and re-run-style escalations.
+
+### By metadata key-value pair
+
+Use when you know a domain identifier (e.g. `orderId`) but not the escalation UUID. `resolveByMetadata` finds the highest-priority pending escalation matching the key-value pair and resolves it atomically — no pre-flight lookup, no TOCTOU:
+
+```typescript
+const result = await lt.escalations.resolveByMetadata({
+  key: 'orderId',
+  value: orderId,
+  resolverPayload: { approved: true, targetStatus: 'ready' },
+});
+
+if (result.status === 404) {
+  // No pending escalation for this orderId
+}
+```
+
+This works for all escalation types including atomic `conditionLT` rows (those with `signal_key` set). The routing is transparent — the caller does not need to know which pattern the workflow used.
+
+### By signal key
+
+When the signal key is deterministic and known to the caller (e.g. `station-done-${workflowId}`), use the direct signal-key path to skip the metadata lookup:
+
+```typescript
+await lt.escalations.resolveBySignalKey({
+  signalKey: `station-done-${workflowId}`,
+  resolverPayload: { approved: true },
+});
+```
+
+---
+
 ## Cancelling Escalations
 
 Escalations can be cancelled at any point before they are resolved. Cancellation is terminal — a cancelled escalation cannot be re-opened.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hotmeshio/long-tail",
-  "version": "0.5.7",
+  "version": "0.5.10",
   "description": "Long Tail Workflows — Durable AI workflows with human-in-the-loop escalation. Powered by PostgreSQL.",
   "main": "./build/index.js",
   "types": "./build/index.d.ts",
@@ -98,6 +98,7 @@
     "@playwright/test": "^1.58.2",
     "@types/bcryptjs": "^2.4.6",
     "@types/express": "^5.0.0",
+    "@types/js-yaml": "^4.0.9",
     "@types/jsonwebtoken": "^9.0.10",
     "@types/node": "^20.19.33",
     "@types/pg": "^8.10.0",