@hotmeshio/long-tail 0.21.2 → 0.22.1

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

@@ -1,4 +1,4 @@
-import type { AccumulatedItem, LTEscalationRecord } from '../../types';
+import type { AccumulatedItem, ContainerSelector, LTEscalationRecord } from '../../types';
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
 /** Names the second row of a reciprocal add or removal. Exactly one selector. */
 export interface ReciprocalInput {
@@ -16,6 +16,11 @@ export interface AccumulateItemInput {
     metadata?: Record<string, any>;
     assertClaim?: boolean;
     reciprocal?: ReciprocalInput;
+    /**
+     * The person who caused the add, when a trusted service performs it for
+     * them. Recorded as the entry's actor; the caller's rights still gate the write.
+     */
+    initiatedBy?: string;
 }
 /**
  * Add ONE item to an accumulator escalation (a `conditional` wait declared
@@ -59,10 +64,14 @@ export declare function accumulateItemByMetadata(input: {
     key: string;
     value: string;
     restrictRoles?: string[];
+    /** Narrows the container beyond the facet: type, subtype, extra facet guards. */
+    container?: ContainerSelector;
 } & Omit<AccumulateItemInput, 'assertClaim'>, auth: LTApiAuth): Promise<LTApiResult>;
 export interface RemoveItemInput {
     itemKey: string;
     reciprocal?: Omit<ReciprocalInput, 'payload'>;
+    /** The person who caused the removal; see {@link AccumulateItemInput.initiatedBy}. */
+    initiatedBy?: string;
 }
 /**
  * Remove ONE held item from a pending accumulator escalation, one guarded

package/build/api/escalations/accumulate.js

@@ -44,6 +44,8 @@ exports.getEscalationItems = getEscalationItems;
 exports.getEscalationItemsBySignalKey = getEscalationItemsBySignalKey;
 const escalationService = __importStar(require("../../services/escalation"));
 const resolver_validation_1 = require("../../services/escalation/resolver-validation");
+const userService = __importStar(require("../../services/user"));
+const uuid_1 = require("../../lib/uuid");
 const enforcement_cache_1 = require("../../services/role/enforcement-cache");
 const escalation_1 = require("../../types/escalation");
 const helpers_1 = require("./helpers");
@@ -69,20 +71,61 @@ const NO_ACCUMULATOR_FOR_FACET = 'No pending accumulator found for this metadata
 /**
  * The container a facet names: the highest priority pending row that carries
  * the facet AND the accumulator declaration, within the given roles (null =
- * unscoped). A release or remediation row sharing the facet is never a
- * candidate, so a by-facet add lands on the open container or nowhere.
+ * unscoped) and the selector's guards. A release or remediation row sharing
+ * the facet is never a candidate, and neither is the add's own reciprocal row,
+ * so a by-facet add lands on the open container or nowhere.
  */
-async function pickAccumulatorByFacet(key, value, roles) {
+async function pickAccumulatorByFacet(key, value, roles, selector, excludeId) {
     if (roles !== null && roles.length === 0)
         return null;
     const found = await escalationService.searchByFacets({
         roles: roles ?? undefined,
-        facets: { [key]: value },
+        types: selector?.types,
+        subtypes: selector?.subtypes,
+        facets: { ...selector?.facets, [key]: value },
         status: 'pending',
         exists: [escalation_1.ESCALATION_ACCUMULATE_KEYS.COUNT],
-        limit: 1,
+        limit: excludeId ? 2 : 1,
     });
-    return found.escalations[0] ?? null;
+    return found.escalations.find((row) => row.id !== excludeId) ?? null;
+}
+const isStringList = (v) => Array.isArray(v) && v.every((s) => typeof s === 'string' && s.length > 0);
+/** The selector's shape error, or null when it is absent or well formed. */
+function containerSelectorError(selector) {
+    if (selector === undefined)
+        return null;
+    if (!selector || typeof selector !== 'object' || Array.isArray(selector))
+        return 'container must be an object';
+    if (selector.types !== undefined && !isStringList(selector.types))
+        return 'container.types must be an array of strings';
+    if (selector.subtypes !== undefined && !isStringList(selector.subtypes))
+        return 'container.subtypes must be an array of strings';
+    if (selector.facets !== undefined && (!selector.facets || typeof selector.facets !== 'object' || Array.isArray(selector.facets))) {
+        return 'container.facets must be an object';
+    }
+    return null;
+}
+function isNarrowed(selector) {
+    return !!(selector?.types?.length || selector?.subtypes?.length
+        || (selector?.facets && Object.keys(selector.facets).length));
+}
+/**
+ * The entry's actor: the caller, or the user a global-access caller names as
+ * the initiator. Attribution only; it never widens what the caller may write.
+ */
+async function resolveActor(initiatedBy, auth) {
+    if (initiatedBy === undefined || initiatedBy === auth.userId)
+        return { actor: auth.userId };
+    if (typeof initiatedBy !== 'string' || !(0, uuid_1.isUuid)(initiatedBy)) {
+        return { error: { status: 400, error: 'initiatedBy must be a user id' } };
+    }
+    if (!(await userService.hasGlobalEscalationAccess(auth.userId))) {
+        return { error: { status: 403, error: 'initiatedBy requires global escalation access' } };
+    }
+    if (!(await userService.getUser(initiatedBy))) {
+        return { error: { status: 400, error: 'initiatedBy names no user' } };
+    }
+    return { actor: initiatedBy };
 }
 function reciprocalSelectorCount(r) {
     return (r.id ? 1 : 0) + (r.signalKey ? 1 : 0) + (r.key !== undefined ? 1 : 0);
@@ -158,6 +201,9 @@ async function accumulateItem(input, auth) {
         const { id, itemKey, metadata } = input;
         if (!itemKey)
             return { status: 400, error: 'itemKey is required' };
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
         const escalation = await escalationService.getEscalation(id);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
@@ -183,7 +229,7 @@ async function accumulateItem(input, auth) {
             itemKey,
             payload: payload.payload,
             metadata: { ...metadata, resolved_by: auth.userId },
-            actor: auth.userId,
+            actor: initiator.actor,
             assertClaim: input.assertClaim ? auth.userId : undefined,
             resolvedBy: await (0, resolve_1.resolverIdentity)(auth),
             reciprocal: reciprocal.reciprocal,
@@ -206,6 +252,9 @@ async function accumulateItemBySignalKey(input, auth) {
             return { status: 400, error: 'signalKey is required' };
         if (!itemKey)
             return { status: 400, error: 'itemKey is required' };
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
         const escalation = await escalationService.getEscalationBySignalKey(signalKey);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
@@ -226,7 +275,7 @@ async function accumulateItemBySignalKey(input, auth) {
             itemKey,
             payload: payload.payload,
             metadata: { ...metadata, resolved_by: auth.userId },
-            actor: auth.userId,
+            actor: initiator.actor,
             resolvedBy: await (0, resolve_1.resolverIdentity)(auth),
             reciprocal: reciprocal.reciprocal,
         });
@@ -254,6 +303,12 @@ async function accumulateItemByMetadata(input, auth) {
             return { status: 400, error: 'key and value are required' };
         if (!itemKey)
             return { status: 400, error: 'itemKey is required' };
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
+        const selectorError = containerSelectorError(input.container);
+        if (selectorError)
+            return { status: 400, error: selectorError };
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
         const allowedRoles = (0, metadata_1.restrictScopeRoles)(writeScope.allRoles, writeScope.global, input.restrictRoles);
         const reciprocal = await gateReciprocal(input.reciprocal, auth);
@@ -261,13 +316,17 @@ async function accumulateItemByMetadata(input, auth) {
             return reciprocal.error;
         const resolvedBy = await (0, resolve_1.resolverIdentity)(auth);
         const outcome = { ...metadata, resolved_by: auth.userId };
+        // A narrowed selector picks in Long Tail, then adds by id; the by-id
+        // statement re-checks pending under its lock, and type, subtype and the
+        // accumulator declaration are fixed at creation.
         const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
-        if (enforcing.size === 0 || input.payload === undefined) {
+        const narrowed = isNarrowed(input.container);
+        if (!narrowed && (enforcing.size === 0 || input.payload === undefined)) {
             const result = await escalationService.accumulateItemByMetadata(key, value, {
                 itemKey,
                 payload: input.payload,
                 metadata: outcome,
-                actor: auth.userId,
+                actor: initiator.actor,
                 resolvedBy,
                 roles: allowedRoles ?? undefined,
                 reciprocal: reciprocal.reciprocal,
@@ -276,7 +335,7 @@ async function accumulateItemByMetadata(input, auth) {
                 return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
             return accumulateOutcomeResult(result, itemKey, result.escalation?.workflow_id ?? null);
         }
-        const row = await pickAccumulatorByFacet(key, value, allowedRoles);
+        const row = await pickAccumulatorByFacet(key, value, allowedRoles, input.container, reciprocal.reciprocal?.id);
         if (!row)
             return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };
         if (!isAccumulator(row))
@@ -288,7 +347,7 @@ async function accumulateItemByMetadata(input, auth) {
             itemKey,
             payload: payload.payload,
             metadata: outcome,
-            actor: auth.userId,
+            actor: initiator.actor,
             resolvedBy,
             reciprocal: reciprocal.reciprocal,
         });
@@ -311,6 +370,9 @@ async function removeItem(input, auth) {
         const { id, itemKey } = input;
         if (!itemKey)
             return { status: 400, error: 'itemKey is required' };
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
         const escalation = await escalationService.getEscalation(id);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
@@ -328,7 +390,7 @@ async function removeItem(input, auth) {
         if ('error' in reciprocal)
             return reciprocal.error;
         const result = await escalationService.removeAccumulatedItem(escalation.id, {
-            itemKey, actor: auth.userId, reciprocal: reciprocal.reciprocal,
+            itemKey, actor: initiator.actor, reciprocal: reciprocal.reciprocal,
         });
         return removeOutcomeResult(result, itemKey);
     }
@@ -343,6 +405,9 @@ async function removeItemBySignalKey(input, auth) {
             return { status: 400, error: 'signalKey is required' };
         if (!itemKey)
             return { status: 400, error: 'itemKey is required' };
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
         const escalation = await escalationService.getEscalationBySignalKey(signalKey);
         if (!escalation)
             return { status: 404, error: 'Escalation not found' };
@@ -357,7 +422,7 @@ async function removeItemBySignalKey(input, auth) {
         if ('error' in reciprocal)
             return reciprocal.error;
         const result = await escalationService.removeAccumulatedItemBySignalKey(signalKey, {
-            itemKey, actor: auth.userId, reciprocal: reciprocal.reciprocal,
+            itemKey, actor: initiator.actor, reciprocal: reciprocal.reciprocal,
         });
         return removeOutcomeResult(result, itemKey);
     }
@@ -372,13 +437,16 @@ async function removeItemByMetadata(input, auth) {
             return { status: 400, error: 'key and value are required' };
         if (!itemKey)
             return { status: 400, error: 'itemKey is required' };
+        const initiator = await resolveActor(input.initiatedBy, auth);
+        if ('error' in initiator)
+            return initiator.error;
         const writeScope = await (0, helpers_1.getEscalationWriteScope)(auth.userId);
         const allowedRoles = (0, metadata_1.restrictScopeRoles)(writeScope.allRoles, writeScope.global, input.restrictRoles);
         const reciprocal = await gateReciprocal(input.reciprocal, auth);
         if ('error' in reciprocal)
             return reciprocal.error;
         const result = await escalationService.removeAccumulatedItemByMetadata(key, value, {
-            itemKey, actor: auth.userId, roles: allowedRoles ?? undefined, reciprocal: reciprocal.reciprocal,
+            itemKey, actor: initiator.actor, roles: allowedRoles ?? undefined, reciprocal: reciprocal.reciprocal,
         });
         if (result.outcome === 'not-found')
             return { status: 404, error: NO_ACCUMULATOR_FOR_FACET };

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

@@ -1,5 +1,6 @@
 import { type ProvisionIfAbsent } from './helpers';
 import type { LTApiAuth, LTApiResult } from '../../types/sdk';
+import type { ScanAvailability } from '../../types';
 /**
  * Intersect the caller's scope roles with an optional caller-supplied
  * restriction (e.g. a scan step's expected queues). Global scope with no
@@ -57,4 +58,8 @@ export declare function resolveByMetadata(input: {
     metadata?: Record<string, any>;
     restrictRoles?: string[];
     extraFacets?: Record<string, any>;
+    /** Narrows the pick to a claim state; 'mine' is the resolver's live claim. */
+    availability?: ScanAvailability;
+    /** Resolves only this row, when it still matches every other condition. */
+    assertId?: string;
 }, auth: LTApiAuth): Promise<LTApiResult>;

package/build/api/escalations/metadata.js

@@ -42,6 +42,7 @@ const helpers_1 = require("./helpers");
 const resolver_validation_1 = require("../../services/escalation/resolver-validation");
 const enforcement_cache_1 = require("../../services/role/enforcement-cache");
 const resolve_1 = require("./resolve");
+const uuid_1 = require("../../lib/uuid");
 /**
  * Intersect the caller's scope roles with an optional caller-supplied
  * restriction (e.g. a scan step's expected queues). Global scope with no
@@ -138,6 +139,9 @@ async function resolveByMetadata(input, auth) {
         if (!input.resolverPayload) {
             return { status: 400, error: 'resolverPayload is required' };
         }
+        if (input.assertId !== undefined && !(0, uuid_1.isUuid)(input.assertId)) {
+            return { status: 404, error: 'No pending escalation found for this metadata, or insufficient role permissions' };
+        }
         const resolved = await (0, helpers_1.resolveAssignee)(input.assignee, auth);
         if ('error' in resolved)
             return resolved.error;
@@ -159,12 +163,12 @@ async function resolveByMetadata(input, auth) {
         // writing; the payload validates here, then a second asserted pass claims
         // + resolves the same row with pending re-checked inside the statement.
         const enforcing = await (0, enforcement_cache_1.getEnforcingRoles)();
-        let result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, enforcing.size > 0 ? [...enforcing] : null, null, input.extraFacets);
+        let result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, enforcing.size > 0 ? [...enforcing] : null, input.assertId ?? null, input.extraFacets, input.availability);
         if (result.outcome === 'validation_required' && result.row) {
             const report = await (0, resolver_validation_1.checkResolverPayload)(result.row, input.resolverPayload, undefined, resolveUserId);
             if (report)
                 return (0, resolve_1.validationFailure)(report);
-            result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, null, result.row.id, input.extraFacets);
+            result = await escalationService.resolveByMetadataAtomic(input.key, input.value, resolveUserId, input.resolverPayload, input.metadata, writeAllRoles, writeSelfRoles, null, result.row.id, input.extraFacets, input.availability);
             // The asserted row left pending between the two passes — a concurrent
             // resolution won the row; surface it as the conflict it is.
             if (result.outcome === 'not_found') {

package/build/api/scan-codes/choice.js

@@ -110,12 +110,13 @@ async function executeScanChoice(input, auth) {
         // showed. A row that moved on (resolved, claimed away, re-routed) is the
         // same double-actor race a second scan loses.
         const located = await (0, locate_1.locateForStep)(step, ctx, 2);
-        if (!located || !located.escalations.some((e) => e.id === input.escalationId)) {
+        const presented = located?.escalations.find((e) => e.id === input.escalationId);
+        if (!presented) {
             return decorate((0, context_1.conflict)('the item is no longer in the presented state'), ctx, input);
         }
         // 6. Dispatch through the same atomic executors a direct scan uses.
         const synthesized = { query: step.query, verb: choice.verb, params: choice.params };
-        const result = await (0, verbs_1.dispatchChoiceVerb)(synthesized, ctx, located.escalations[0]);
+        const result = await (0, verbs_1.dispatchChoiceVerb)(synthesized, ctx, presented);
         return decorate(result, ctx, input);
     }
     catch (err) {

package/build/api/scan-codes/verbs.d.ts

@@ -2,7 +2,12 @@ import { type ScanExecuteResponse, type ScanStep } from '../../types';
 import type { LTApiResult } from '../../types/sdk';
 import { type StepContext } from './context';
 export declare function claimStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
-export declare function resolveStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
+/**
+ * Resolves the row the step's query names: the scanned target, the extra
+ * facets, and the claim state, all inside the atomic statement. A presented
+ * choice passes the row it showed, so the resolve lands on that row or misses.
+ */
+export declare function resolveStep(step: ScanStep, ctx: StepContext, presentedId?: string): Promise<LTApiResult<ScanExecuteResponse> | null>;
 export declare function escalateStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
 export declare function releaseStep(step: ScanStep, ctx: StepContext): Promise<LTApiResult<ScanExecuteResponse> | null>;
 /**

package/build/api/scan-codes/verbs.js

@@ -88,7 +88,12 @@ async function claimStep(step, ctx) {
         return result;
     return (0, context_1.executed)(result.data.escalation, step);
 }
-async function resolveStep(step, ctx) {
+/**
+ * Resolves the row the step's query names: the scanned target, the extra
+ * facets, and the claim state, all inside the atomic statement. A presented
+ * choice passes the row it showed, so the resolve lands on that row or misses.
+ */
+async function resolveStep(step, ctx, presentedId) {
     const rendered = await templated(step, ctx, (tpl) => ({
         resolverPayload: scanCodeService.interpolateScanTemplate(step.params?.resolverPayload ?? {}, tpl),
         metadata: (0, context_1.interpolatedMetadata)(step, ctx, tpl),
@@ -102,6 +107,8 @@ async function resolveStep(step, ctx) {
         metadata: { ...rendered.metadata, ...(0, context_1.provenance)(ctx) },
         restrictRoles: step.query?.roles,
         extraFacets: step.query?.facets,
+        availability: step.query?.availability,
+        assertId: presentedId,
     }, ctx.auth);
     if (result.status === 404)
         return null;
@@ -189,7 +196,7 @@ async function dispatchChoiceVerb(step, ctx, row) {
         case types_1.SCAN_VERBS.CLAIM_SHOW_DETAIL:
             return (await claimStep(step, ctx)) ?? (await missReason(step, ctx, 'the item is no longer claimable'));
         case types_1.SCAN_VERBS.RESOLVE:
-            return (await resolveStep(step, ctx)) ?? (await missReason(step, ctx, 'the item is no longer resolvable'));
+            return (await resolveStep(step, ctx, row.id)) ?? (await missReason(step, ctx, 'the item is no longer resolvable'));
         case types_1.SCAN_VERBS.ESCALATE:
             return (await escalateStep(step, ctx)) ?? (await missReason(step, ctx, 'the item already moved on'));
         case types_1.SCAN_VERBS.RELEASE:
@@ -283,7 +290,10 @@ async function accumulateStep(step, ctx) {
             itemKey: rendered.itemKey,
             payload: rendered.payload,
             metadata: rendered.metadata,
-            restrictRoles: options.containerRoles,
+            restrictRoles: options.container?.roles ?? options.containerRoles,
+            container: options.container
+                ? { types: options.container.types, subtypes: options.container.subtypes, facets: options.container.facets }
+                : undefined,
             ...(options.reciprocal === false ? {} : { reciprocal: { id: item.id } }),
         };
     }

package/build/api/workflows/invocation.d.ts

@@ -21,14 +21,16 @@ export declare function invokeWorkflow(input: {
 /**
  * Get the execution status of a workflow.
  *
- * Returns the HotMesh status code (0 = completed, 1 = running).
+ * Returns the HotMesh status code (above 0 running, 0 closed, below 0
+ * terminated) with the state it implies: `running`, `completed` or `failed`,
+ * `terminated` when an interrupt ended it, and `error` for a failed run.
  * 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
+ * @returns `{ status: 200, data: { workflowId, status, state, terminated, error? } }` or 404
  */
 export declare function getWorkflowStatus(input: {
     workflowId: string;
@@ -38,11 +40,13 @@ export declare function getWorkflowStatus(input: {
  * Get the result of a completed workflow.
  *
  * Returns 202 if the workflow is still running, 200 with the result
- * payload when complete. Never blocks — always returns immediately.
+ * payload when complete, and 200 with `state: 'failed'` (plus `terminated`
+ * and `error` when known) when it failed or was terminated. 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
+ * @returns `{ status: 200, data: { workflowId, state, result } }` or 202 if running
  */
 export declare function getWorkflowResult(input: {
     workflowId: string;

package/build/api/workflows/invocation.js

@@ -41,6 +41,7 @@ exports.exportWorkflow = exportWorkflow;
 const workers_1 = require("../../workers");
 const exportService = __importStar(require("../../services/export"));
 const task_1 = require("../../services/task");
+const workflow_state_1 = require("../../services/workflow-state");
 const workflow_invocation_1 = require("../../services/workflow-invocation");
 const crud_1 = require("../../services/escalation/crud");
 const configService = __importStar(require("../../services/config"));
@@ -91,24 +92,26 @@ async function invokeWorkflow(input, auth) {
 /**
  * Get the execution status of a workflow.
  *
- * Returns the HotMesh status code (0 = completed, 1 = running).
+ * Returns the HotMesh status code (above 0 running, 0 closed, below 0
+ * terminated) with the state it implies: `running`, `completed` or `failed`,
+ * `terminated` when an interrupt ended it, and `error` for a failed run.
  * 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
+ * @returns `{ status: 200, data: { workflowId, status, state, terminated, error? } }` or 404
  */
 async function getWorkflowStatus(input) {
     try {
         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();
+        const reading = await (0, workflow_state_1.readWorkflowState)(handle);
         return {
             status: 200,
-            data: { workflowId: input.workflowId, status },
+            data: { workflowId: input.workflowId, ...reading },
         };
     }
     catch (err) {
@@ -121,28 +124,42 @@ async function getWorkflowStatus(input) {
  * Get the result of a completed workflow.
  *
  * Returns 202 if the workflow is still running, 200 with the result
- * payload when complete. Never blocks — always returns immediately.
+ * payload when complete, and 200 with `state: 'failed'` (plus `terminated`
+ * and `error` when known) when it failed or was terminated. 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
+ * @returns `{ status: 200, data: { workflowId, state, result } }` or 202 if running
  */
 async function getWorkflowResult(input) {
     try {
         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();
-        if (status !== 0) {
+        const reading = await (0, workflow_state_1.readWorkflowState)(handle);
+        if (reading.state === workflow_state_1.WORKFLOW_STATES.RUNNING) {
             return {
                 status: 202,
                 data: { workflowId: input.workflowId, status: 'running' },
             };
         }
+        if (reading.state === workflow_state_1.WORKFLOW_STATES.FAILED) {
+            return {
+                status: 200,
+                data: {
+                    workflowId: input.workflowId,
+                    state: reading.state,
+                    terminated: reading.terminated,
+                    ...(reading.error ? { error: reading.error } : {}),
+                    result: null,
+                },
+            };
+        }
         const result = await handle.result();
         return {
             status: 200,
-            data: { workflowId: input.workflowId, result },
+            data: { workflowId: input.workflowId, state: reading.state, result },
         };
     }
     catch (err) {

package/build/lib/cli/commands/workflows.js

@@ -45,6 +45,7 @@ exports.terminateWorkflow = terminateWorkflow;
 const picocolors_1 = __importDefault(require("picocolors"));
 const client_1 = require("../client");
 const format_1 = require("../format");
+const workflow_state_1 = require("../../../shared/workflow-state");
 const COLUMNS = [
     { key: 'workflow_type', label: 'Type', width: 24 },
     { key: 'task_queue', label: 'Queue', width: 16 },
@@ -72,13 +73,17 @@ async function invokeWorkflow(type, opts) {
     console.log(`\n  ${picocolors_1.default.green('✓')} Started ${picocolors_1.default.bold(type)} → ${picocolors_1.default.dim(data.workflowId)}\n`);
 }
 async function getWorkflowStatus(id, opts) {
-    const data = await (0, client_1.apiFetch)(`/workflows/status/${id}`);
+    const data = await (0, client_1.apiFetch)(`/workflows/${encodeURIComponent(id)}/status`);
     if (opts.json) {
         console.log(JSON.stringify(data, null, 2));
         return;
     }
-    const status = data.status === 0 ? picocolors_1.default.green('completed') : picocolors_1.default.blue('running');
-    console.log(`\n  ${data.workflowId}  ${status}\n`);
+    const state = data.state === workflow_state_1.WORKFLOW_STATES.COMPLETED
+        ? picocolors_1.default.green('completed')
+        : data.state === workflow_state_1.WORKFLOW_STATES.FAILED
+            ? picocolors_1.default.red(data.terminated ? 'failed (terminated)' : 'failed')
+            : picocolors_1.default.blue('running');
+    console.log(`\n  ${data.workflowId}  ${state}${data.error ? picocolors_1.default.dim(`  ${data.error}`) : ''}\n`);
 }
 async function getWorkflowResult(id, opts) {
     const { server, token } = await (await Promise.resolve().then(() => __importStar(require('../auth')))).resolveAuth();
@@ -121,6 +126,6 @@ async function getWorkflowEnvelopes(id, opts) {
     console.log();
 }
 async function terminateWorkflow(id) {
-    await (0, client_1.apiFetch)(`/workflows/terminate/${id}`, { method: 'POST' });
+    await (0, client_1.apiFetch)(`/workflows/${encodeURIComponent(id)}/terminate`, { method: 'POST' });
     console.log(`\n  ${picocolors_1.default.green('✓')} Terminated ${picocolors_1.default.dim(id)}\n`);
 }

package/build/lib/db/index.d.ts

@@ -1,12 +1,17 @@
-import { Client, Pool } from 'pg';
+import { Client, Pool, type ClientConfig } from 'pg';
+/** `pg.Client` that carries an 'error' listener from construction. */
+declare class GuardedClient extends Client {
+    constructor(config?: string | ClientConfig);
+}
 export declare function getPool(): Pool;
 export declare function closePool(): Promise<void>;
 /**
- * HotMesh connection descriptor: `{ class: Client, options: postgres_options }`.
+ * HotMesh connection descriptor: `{ class: GuardedClient, options: postgres_options }`.
  * Use this everywhere HotMesh / Durable APIs need a connection config
  * instead of importing `pg` and `postgres_options` directly.
  */
 export declare function getConnection(): {
-    class: typeof Client;
+    class: typeof GuardedClient;
     options: Record<string, unknown>;
 };
+export {};

package/build/lib/db/index.js

@@ -5,10 +5,29 @@ exports.closePool = closePool;
 exports.getConnection = getConnection;
 const pg_1 = require("pg");
 const config_1 = require("../../modules/config");
+const logger_1 = require("../logger");
+/** A new connection that cannot be established within this window fails instead of hanging. */
+const CONNECT_TIMEOUT_MS = 10_000;
 let pool = null;
+/** A lost socket fails the pending query; its 'error' event must never end the process. */
+function onConnectionError(error) {
+    logger_1.loggerRegistry.debug(`[lt-db] connection error: ${error.message}`);
+}
+function onIdleConnectionLost(error) {
+    logger_1.loggerRegistry.warn(`[lt-db] pooled connection lost: ${error.message}`);
+}
+/** `pg.Client` that carries an 'error' listener from construction. */
+class GuardedClient extends pg_1.Client {
+    constructor(config) {
+        super(config);
+        this.on('error', onConnectionError);
+    }
+}
 function getPool() {
     if (!pool) {
         pool = new pg_1.Pool({
+            connectionTimeoutMillis: CONNECT_TIMEOUT_MS,
+            keepAlive: true,
             ...config_1.postgres_options,
             // Long-tail's shared tables live in public. Postgres's default
             // search_path is `"$user", public`: if any schema shares the connecting
@@ -20,6 +39,9 @@ function getPool() {
             // the engine fully qualifies its app schemas.
             options: '-c search_path=public',
         });
+        pool.on('error', onIdleConnectionLost);
+        // pg-pool drops its own listener while a client is checked out
+        pool.on('connect', (client) => client.on('error', onConnectionError));
     }
     return pool;
 }
@@ -30,10 +52,10 @@ async function closePool() {
     }
 }
 /**
- * HotMesh connection descriptor: `{ class: Client, options: postgres_options }`.
+ * HotMesh connection descriptor: `{ class: GuardedClient, options: postgres_options }`.
  * Use this everywhere HotMesh / Durable APIs need a connection config
  * instead of importing `pg` and `postgres_options` directly.
  */
 function getConnection() {
-    return { class: pg_1.Client, options: config_1.postgres_options };
+    return { class: GuardedClient, options: config_1.postgres_options };
 }