@hotmeshio/long-tail 0.8.3 → 0.8.4

package/build/api/escalations/create.js

@@ -32,34 +32,13 @@ var __importStar = (this && this.__importStar) || (function () {
         return result;
     };
 })();
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createEscalation = createEscalation;
-const ajv_1 = __importDefault(require("ajv"));
 const escalationService = __importStar(require("../../services/escalation"));
 const roleService = __importStar(require("../../services/role"));
+const schema_validator_1 = require("../../services/role/schema-validator");
 const escalation_1 = require("../../types/escalation");
 const helpers_1 = require("./helpers");
-// strict: false — role metadata_schemas use the project's house extension
-// keywords (x-lt-widget etc., the same style as seeded form_schemas); Ajv 8's
-// strict mode throws at compile on any unknown keyword, which would turn every
-// metadata-bearing create for that role into a 500.
-const ajv = new ajv_1.default({ allErrors: true, strict: false });
-// Compiled validators cached per role+version, keyed by the schema's serialized
-// form so an admin's schema edit invalidates the stale validator on the next
-// create. Pinned versions are immutable, but the same key logic covers both.
-const validatorCache = new Map();
-function compileRoleValidator(cacheId, schema) {
-    const key = JSON.stringify(schema);
-    const cached = validatorCache.get(cacheId);
-    if (cached && cached.key === key)
-        return cached.validate;
-    const validate = ajv.compile(schema);
-    validatorCache.set(cacheId, { key, validate });
-    return validate;
-}
 // ── Create ────────────────────────────────────────────────────────────────
 /**
  * Create a standalone escalation (not tied to a workflow).
@@ -94,46 +73,26 @@ async function createEscalation(input, auth) {
         if (denied) {
             return { status: 403, error: `You must have write access to the "${role}" role or be a superadmin to create escalations for it` };
         }
-        // Validate metadata against the role's declared schema (if any). A
-        // metadata.schema_version pin selects that immutable snapshot; a pin that
-        // names a missing version is a 400, never a silent fall-through to latest.
-        if (input.metadata) {
-            const pinned = input.metadata[escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION];
-            if (pinned !== undefined && (!Number.isInteger(pinned) || pinned < 1)) {
-                return { status: 400, error: `metadata.${escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION} must be a positive integer` };
-            }
-            let schema;
-            if (pinned !== undefined) {
-                const snapshot = await roleService.getRoleSchema(role, pinned);
-                if (!snapshot) {
-                    return { status: 400, error: `Schema version ${pinned} does not exist for role "${role}"` };
-                }
-                schema = snapshot.metadata_schema;
+        // Validate the caller-supplied metadata against the role's metadata_schema
+        // (the queryable-facet contract). An escalation may carry a form-version pin
+        // (metadata.schema_version) chosen by the workflow author; that is a system
+        // key, not caller data, so it is excluded from validation. No version is
+        // stamped here — omitting it means the resolve UI renders the role's latest
+        // form at fetch time.
+        const metadata = input.metadata ?? {};
+        const metadataSchema = await roleService.getRoleMetadataSchema(role);
+        if (metadataSchema) {
+            let validate;
+            try {
+                validate = (0, schema_validator_1.compileSchemaValidator)(`${role}:meta`, metadataSchema);
             }
-            else {
-                schema = await roleService.getRoleMetadataSchema(role);
+            catch (compileErr) {
+                // A broken stored schema is the role admin's bug, not the creator's.
+                return { status: 422, error: `metadata_schema for role "${role}" is not a valid JSON Schema: ${compileErr.message}` };
             }
-            if (schema) {
-                let validate;
-                try {
-                    validate = compileRoleValidator(`${role}@${pinned ?? 'live'}`, schema);
-                }
-                catch (compileErr) {
-                    // A broken stored schema is the role admin's bug, not the creator's —
-                    // name it explicitly instead of surfacing an opaque 500.
-                    return {
-                        status: 422,
-                        error: `metadata_schema for role "${role}" is not a valid JSON Schema: ${compileErr.message}`,
-                    };
-                }
-                // The pin is a system key, not caller data — strip it so schemas with
-                // additionalProperties: false still validate the caller's bag.
-                const { [escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION]: _pin, ...callerMetadata } = input.metadata;
-                const valid = validate(callerMetadata);
-                if (!valid) {
-                    const msgs = (validate.errors ?? []).map((e) => `${e.instancePath || '(root)'} ${e.message}`).join('; ');
-                    return { status: 400, error: `metadata does not match the role schema: ${msgs}` };
-                }
+            const { [escalation_1.ESCALATION_METADATA_KEYS.SCHEMA_VERSION]: _pin, ...callerMetadata } = metadata;
+            if (!validate(callerMetadata)) {
+                return { status: 400, error: `metadata does not match the role schema: ${(0, schema_validator_1.formatValidationErrors)(validate)}` };
             }
         }
         const escalation = await escalationService.createEscalation({

package/build/api/escalations/resolve.js

@@ -60,7 +60,7 @@ const helpers_1 = require("./helpers");
  */
 async function resolveEscalation(input, auth) {
     try {
-        const { id, resolverPayload, metadata } = input;
+        const { id, metadata, resolverPayload } = input;
         if (!resolverPayload) {
             return { status: 400, error: 'resolverPayload is required' };
         }
@@ -82,6 +82,9 @@ async function resolveEscalation(input, auth) {
         const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
         if (denied)
             return denied;
+        // The resolver payload is stored exactly as submitted — its shape is the
+        // workflow's contract, formed by the caller (the React app maps the form to
+        // the payload via x-lt-bind before submitting). No server-side transform.
         // `metadata` (the outcome patch) is never written separately — it rides WITH the
         // resolverPayload to whichever path performs the resolve, so it merges inside the
         // single status='pending'-guarded UPDATE (HotMesh `resolve(metadata)`). Paths that
@@ -133,7 +136,7 @@ async function resolveEscalation(input, auth) {
  */
 async function resolveBySignalKey(input, auth) {
     try {
-        const { signalKey, resolverPayload, metadata } = input;
+        const { signalKey, metadata, resolverPayload } = input;
         if (!signalKey)
             return { status: 400, error: 'signalKey is required' };
         if (!resolverPayload)
@@ -147,6 +150,8 @@ async function resolveBySignalKey(input, auth) {
         const denied = await (0, helpers_1.assertWriteAccess)(auth.userId, escalation);
         if (denied)
             return { status: 404, error: 'Escalation not found' };
+        // The payload is delivered as the signal the parked workflow's condition()
+        // receives — stored exactly as submitted (the caller formed its shape).
         return resolveViaSignalKey(escalation, resolverPayload, metadata);
     }
     catch (err) {
@@ -166,12 +171,15 @@ async function resolveBySignalKey(input, auth) {
  */
 async function resolveByIds(input, auth) {
     try {
-        const { ids, resolverPayload, metadata } = input;
+        const { ids, metadata } = input;
         if (!Array.isArray(ids) || ids.length === 0) {
             return { status: 400, error: 'ids must be a non-empty array' };
         }
-        if (!resolverPayload)
+        if (!input.resolverPayload)
             return { status: 400, error: 'resolverPayload is required' };
+        // One pre-shaped payload for a homogeneous group of bookkeeping rows, stored
+        // as submitted — the caller forms the payload's shape.
+        const resolverPayload = input.resolverPayload;
         // Bulk resolve ("ack") is a write verb, gated PER ITEM: write_all roles may
         // resolve any item in the role; write_self roles may resolve only items assigned
         // to the caller (same rule single-resolve applies via assertWriteAccess). Global

package/build/api/escalations/single.js

@@ -51,14 +51,18 @@ const helpers_1 = require("./helpers");
  */
 async function getEscalation(input, auth) {
     try {
-        const escalation = await escalationService.getEscalation(input.id);
-        if (!escalation) {
+        // One query: the escalation plus its role's form, resolved to the version the
+        // row pinned (or the role's latest) and embedded as `form_schema`. The resolve
+        // UI renders from this without a second schema call, and the form is never
+        // stored on the row — it is JOINed in from the roles tables.
+        const detail = await escalationService.getEscalationWithFormSchema(input.id);
+        if (!detail) {
             return { status: 404, error: 'Escalation not found' };
         }
-        const denied = await (0, helpers_1.assertReadAccess)(auth.userId, escalation);
+        const denied = await (0, helpers_1.assertReadAccess)(auth.userId, detail.escalation);
         if (denied)
             return denied;
-        return { status: 200, data: escalation };
+        return { status: 200, data: { ...detail.escalation, form_schema: detail.form_schema } };
     }
     catch (err) {
         return { status: 500, error: err.message };

package/build/api/roles.d.ts

@@ -83,6 +83,7 @@ export declare function updateRole(input: {
     role: string;
     title?: string | null;
     description?: string | null;
+    /** The escalation resolve FORM schema (the JIT UI). Fields may carry x-lt-bind. */
     form_schema?: Record<string, any> | null;
     metadata_schema?: Record<string, any> | null;
     properties?: Record<string, any> | null;

package/build/scripts/twin-farm.d.ts

@@ -3,16 +3,19 @@
  *
  * Spins up the whole DIGITAL side of the physical/digital twin farm from one
  * command and plays every human part automatically, so a single run exercises
- * the full lifecycle: register → advertise → dispatch → print → settle, plus the
- * failure detour (cancel → service → back in the pool). The PHYSICAL side is the
- * app's farm-manager backend — `mock` by default (self-contained), or `http`
- * against a real print-farm-manager host once you wire the office up.
+ * the full lifecycle: onboard (register + bind) → advertise → dispatch → print →
+ * reconcile → settle, plus the failure detours (autonomous fail → inspect, and
+ * filament runout → change → resume). The PHYSICAL side is the app's Bambu
+ * backend — `BAMBU_BACKEND=mock` by default (a deterministic in-repo simulation),
+ * or `http` against a real Farm Manager Server once the office link is wired.
+ *
+ * Faults are injected deterministically via each order unit's `simOutcome` (the
+ * mock honors it), so the service escalations fire on demand — no racing.
  *
  * Usage:
  *   npm run twin:farm
  *   FLEET=6 ORDERS=10 UNITS=2 npm run twin:farm
- *   FAIL_PCT=25 npm run twin:farm                 # rehearse dead-machine → service
- *   FARM_MANAGER_URL=http://192.168.1.50:4000 npm run twin:farm   # preflight the office link
+ *   FAIL_PCT=30 FAIL_MODE=filament_runout npm run twin:farm   # fault → service → recover
  *   FLEET=4 ORDERS=4 KEEP=1 npm run twin:farm     # leave twins running to poke in the UI
  *
  * Env vars:
@@ -24,17 +27,13 @@
  *   FILAMENTS         comma-separated filament pool the fleet + orders draw from
  *                     (default "pla,petg")
  *   ARRIVAL_S         average seconds between order arrivals (default 2)
- *   FAIL_PCT          percent of print jobs to cancel mid-print, exercising the
- *                     service path (default 0). Best-effort: it races the
- *                     physical side, so raise MOCK_PRINT_SECONDS on the app for
- *                     a wider window (see README).
- *   POLL_MS           poll interval ms (default 750)
+ *   FAIL_PCT          percent of orders with one faulted unit (default 0)
+ *   FAIL_MODE         the injected fault: filament_runout | failed (default filament_runout)
+ *   POLL_MS           servicer/registrar poll interval ms (default 750)
  *   BROKER_IDLE       idle broker ticks before it self-terminates (default 40)
  *   RUN_BROKER        launch a broker (default 1; set 0 if one already runs)
  *   KEEP              1 = leave twins advertising at the end (default 0 = retire
  *                     them with a power-down so nothing lingers between runs)
- *   FARM_MANAGER_URL  optional: GET this before running and report reachability,
- *                     a preflight for the office laptop → farm-manager-host link
  *
  * Capabilities: each twin is registered with a capability profile (xl/pdac/soft).
  * By default the fleet is fully capable and only filament routes; set FLEET_CAPS

package/build/scripts/twin-farm.js

@@ -4,16 +4,19 @@
  *
  * Spins up the whole DIGITAL side of the physical/digital twin farm from one
  * command and plays every human part automatically, so a single run exercises
- * the full lifecycle: register → advertise → dispatch → print → settle, plus the
- * failure detour (cancel → service → back in the pool). The PHYSICAL side is the
- * app's farm-manager backend — `mock` by default (self-contained), or `http`
- * against a real print-farm-manager host once you wire the office up.
+ * the full lifecycle: onboard (register + bind) → advertise → dispatch → print →
+ * reconcile → settle, plus the failure detours (autonomous fail → inspect, and
+ * filament runout → change → resume). The PHYSICAL side is the app's Bambu
+ * backend — `BAMBU_BACKEND=mock` by default (a deterministic in-repo simulation),
+ * or `http` against a real Farm Manager Server once the office link is wired.
+ *
+ * Faults are injected deterministically via each order unit's `simOutcome` (the
+ * mock honors it), so the service escalations fire on demand — no racing.
  *
  * Usage:
  *   npm run twin:farm
  *   FLEET=6 ORDERS=10 UNITS=2 npm run twin:farm
- *   FAIL_PCT=25 npm run twin:farm                 # rehearse dead-machine → service
- *   FARM_MANAGER_URL=http://192.168.1.50:4000 npm run twin:farm   # preflight the office link
+ *   FAIL_PCT=30 FAIL_MODE=filament_runout npm run twin:farm   # fault → service → recover
  *   FLEET=4 ORDERS=4 KEEP=1 npm run twin:farm     # leave twins running to poke in the UI
  *
  * Env vars:
@@ -25,17 +28,13 @@
  *   FILAMENTS         comma-separated filament pool the fleet + orders draw from
  *                     (default "pla,petg")
  *   ARRIVAL_S         average seconds between order arrivals (default 2)
- *   FAIL_PCT          percent of print jobs to cancel mid-print, exercising the
- *                     service path (default 0). Best-effort: it races the
- *                     physical side, so raise MOCK_PRINT_SECONDS on the app for
- *                     a wider window (see README).
- *   POLL_MS           poll interval ms (default 750)
+ *   FAIL_PCT          percent of orders with one faulted unit (default 0)
+ *   FAIL_MODE         the injected fault: filament_runout | failed (default filament_runout)
+ *   POLL_MS           servicer/registrar poll interval ms (default 750)
  *   BROKER_IDLE       idle broker ticks before it self-terminates (default 40)
  *   RUN_BROKER        launch a broker (default 1; set 0 if one already runs)
  *   KEEP              1 = leave twins advertising at the end (default 0 = retire
  *                     them with a power-down so nothing lingers between runs)
- *   FARM_MANAGER_URL  optional: GET this before running and report reachability,
- *                     a preflight for the office laptop → farm-manager-host link
  *
  * Capabilities: each twin is registered with a capability profile (xl/pdac/soft).
  * By default the fleet is fully capable and only filament routes; set FLEET_CAPS
@@ -55,17 +54,17 @@ const UNITS = parseInt(process.env.UNITS || '2', 10);
 const FILAMENTS = (process.env.FILAMENTS || 'pla,petg').split(',').map((f) => f.trim()).filter(Boolean);
 const ARRIVAL_S = parseFloat(process.env.ARRIVAL_S || '2');
 const FAIL_PCT = parseInt(process.env.FAIL_PCT || '0', 10);
+const FAIL_MODE = (process.env.FAIL_MODE || 'filament_runout');
 const POLL_MS = parseInt(process.env.POLL_MS || '750', 10);
 const BROKER_IDLE = parseInt(process.env.BROKER_IDLE || '40', 10);
 const RUN_BROKER = process.env.RUN_BROKER !== '0';
 const KEEP = process.env.KEEP === '1';
-const FARM_MANAGER_URL = process.env.FARM_MANAGER_URL || '';
 const CAPABILITY_KEYS = ['xl', 'pdac', 'soft'];
 const MODELS = ['Fab-X1', 'Fab-X1C', 'Fab-P2', 'Fab-Mini'];
 let token = '';
 let userId = '';
 let done = false;
-const stats = { registered: 0, dispatched: 0, printed: 0, cancelled: 0, serviced: 0, settled: 0 };
+const stats = { registered: 0, dispatched: 0, printed: 0, faulted: 0, serviced: 0, settled: 0 };
 function ts() { return new Date().toISOString().slice(11, 19); }
 function sleep(ms) { return new Promise((r) => setTimeout(r, ms)); }
 function ageSeconds(iso) { return (Date.now() - new Date(iso).getTime()) / 1000; }
@@ -115,8 +114,9 @@ async function login() {
  */
 const TWIN_ROLE_CONFIG = [
     { role: 'print-jobs', title: 'Print Jobs', parent_role: null, sla_minutes: 5, target_per_hour: 30, priority_threshold_minutes: 5, description: 'Order demand — one print-job escalation per unit, claimed as a set.' },
-    { role: 'printer-fleet', title: 'Printer Fleet', parent_role: 'print-jobs', sla_minutes: 5, target_per_hour: 30, priority_threshold_minutes: 5, description: 'Twin availability adverts and in-flight print rows — the machines at work.', upstream_roles: ['print-servicer'] },
-    { role: 'print-servicer', title: 'Print Servicer', parent_role: null, sla_minutes: 10, target_per_hour: 10, priority_threshold_minutes: 10, description: 'Register unboxed machines and restore ones that fell offline.' },
+    { role: 'printer-fleet', title: 'Printer Fleet', parent_role: 'print-jobs', sla_minutes: 5, target_per_hour: 30, priority_threshold_minutes: 5, description: 'Twin availability adverts and in-flight print rows — the machines at work.', upstream_roles: ['print-onboarder', 'print-servicer'] },
+    { role: 'print-onboarder', title: 'Print Onboarder', parent_role: null, sla_minutes: 15, target_per_hour: 5, priority_threshold_minutes: 15, description: 'Register + bind a newly unboxed machine.' },
+    { role: 'print-servicer', title: 'Print Servicer', parent_role: null, sla_minutes: 10, target_per_hour: 10, priority_threshold_minutes: 10, description: 'Reload filament, inspect failures, restore offline machines.' },
 ];
 async function ensureTwinRoles() {
     const details = await api('GET', '/api/roles/details').catch(() => ({ roles: [] }));
@@ -160,6 +160,10 @@ function planFleet(batchTag) {
         return { printerId, wfId: printerId, filament, caps, model: MODELS[i % MODELS.length], serialNumber: `SN-${batchTag.slice(-6)}-${i}` };
     });
 }
+/** Evenly distribute FAIL_PCT across the order sequence (deterministic). */
+function hasFault(i) {
+    return Math.floor(((i + 1) * FAIL_PCT) / 100) > Math.floor((i * FAIL_PCT) / 100);
+}
 function planOrders(batchTag, fleet) {
     return Array.from({ length: ORDERS }, (_, i) => {
         const filament = FILAMENTS[i % FILAMENTS.length];
@@ -171,7 +175,8 @@ function planOrders(batchTag, fleet) {
         const cap = CAPABILITY_KEYS[i % CAPABILITY_KEYS.length];
         const capable = pool.filter((t) => t.caps[cap]).length;
         const require = (i % 2 === 0 && capable >= units) ? { [cap]: true } : {};
-        return { index: i, wfId: `${batchTag}-o${i}`, orderId: `TWIN-${batchTag.slice(-6)}-${i}`, filament, require, units };
+        const fault = hasFault(i) ? { unit: 0, mode: FAIL_MODE } : undefined;
+        return { index: i, wfId: `${batchTag}-o${i}`, orderId: `TWIN-${batchTag.slice(-6)}-${i}`, filament, require, units, fault };
     });
 }
 // ── Launch twins + broker + orders ────────────────────────────────────────────
@@ -198,7 +203,10 @@ async function placeOrder(spec) {
             orderId: spec.orderId,
             filament: spec.filament,
             require: spec.require,
-            units: Array.from({ length: spec.units }, (_, u) => ({ gcodeUrl: `https://example.com/${spec.orderId}-u${u}.gcode` })),
+            units: Array.from({ length: spec.units }, (_, u) => ({
+                gcodeUrl: `https://example.com/${spec.orderId}-u${u}.gcode`,
+                ...(spec.fault && spec.fault.unit === u ? { simOutcome: spec.fault.mode } : {}),
+            })),
             operatorId: userId,
         },
         metadata: { source: 'twin-farm' },
@@ -209,7 +217,7 @@ async function placeOrder(spec) {
 async function registerLoop(fleet) {
     while (!done) {
         try {
-            const resp = await api('GET', '/api/escalations/available?role=print-servicer&subtype=registering&limit=100');
+            const resp = await api('GET', '/api/escalations/available?role=print-onboarder&subtype=registering&limit=100');
             for (const esc of resp?.escalations ?? []) {
                 const spec = fleet.get(String(esc.metadata?.printerId ?? ''));
                 if (!spec)
@@ -238,17 +246,31 @@ async function registerLoop(fleet) {
             await sleep(POLL_MS);
     }
 }
-/** Resolve service escalations — the servicer realigning a downed machine. */
+/** The servicer's resolution for each escalation subtype the twin raises. Reloads
+ *  the SAME filament the machine had (from the escalation metadata) so a service
+ *  visit restores the machine rather than repurposing it. */
+function servicePayload(esc) {
+    const subtype = esc.subtype;
+    if (subtype === 'filament_change')
+        return { filamentLoaded: esc.metadata?.filament || 'pla', notes: 'Reloaded by twin-farm' };
+    if (subtype === 'failure_inspect')
+        return { action: 'reset', notes: 'Inspected by twin-farm' };
+    if (subtype === 'offline_investigate')
+        return { action: 'checked', notes: 'Reconnected by twin-farm' };
+    return { action: 'restored', notes: 'Auto-serviced by twin-farm' };
+}
+/** Resolve every servicer escalation (except registration) — filament changes,
+ *  failure inspections, offline investigations — the way a technician would. */
 async function serviceLoop() {
     while (!done) {
         try {
-            const resp = await api('GET', '/api/escalations/available?role=print-servicer&subtype=service&limit=100');
+            const resp = await api('GET', '/api/escalations/available?role=print-servicer&limit=100');
             for (const esc of resp?.escalations ?? []) {
                 await api('POST', `/api/escalations/${esc.id}/resolve`, {
-                    resolverPayload: { action: 'restored', notes: 'Auto-serviced by twin-farm' },
+                    resolverPayload: servicePayload(esc),
                 }).then(() => {
                     stats.serviced++;
-                    console.log(`[${ts()}]   [service]  ${esc.metadata?.printerId ?? esc.id.slice(0, 8)} restored [${stats.serviced}]`);
+                    console.log(`[${ts()}]   [service]  ${esc.subtype.padEnd(18)} ${esc.metadata?.printerId ?? esc.id.slice(0, 8)} [${stats.serviced}]`);
                 }).catch(() => { });
             }
         }
@@ -259,35 +281,6 @@ async function serviceLoop() {
             await sleep(POLL_MS);
     }
 }
-/** Cancel a deterministic fraction of in-flight prints — the power-outage /
- *  dead-machine drill. Best-effort: it races the physical side's resolve. */
-async function failLoop() {
-    if (FAIL_PCT <= 0)
-        return;
-    const acted = new Set();
-    while (!done) {
-        try {
-            const resp = await api('GET', '/api/escalations/available?role=printer-fleet&subtype=printing&limit=100');
-            for (const esc of resp?.escalations ?? []) {
-                const jobId = String(esc.metadata?.jobId ?? esc.id);
-                if (acted.has(jobId))
-                    continue;
-                if (jitter(jobId, 'fail') * 100 >= FAIL_PCT)
-                    continue;
-                acted.add(jobId);
-                await api('POST', `/api/escalations/${esc.id}/cancel`).then(() => {
-                    stats.cancelled++;
-                    console.log(`[${ts()}]   [FAIL]     cancelled print ${jobId} — machine went dark [${stats.cancelled}]`);
-                }).catch(() => { });
-            }
-        }
-        catch (err) {
-            logPollErr('fail', err);
-        }
-        if (!done)
-            await sleep(Math.min(POLL_MS, 300));
-    }
-}
 let lastPollErr = '';
 function logPollErr(loop, err) {
     const msg = `[${loop}] ${String(err?.message).slice(0, 80)}`;
@@ -316,7 +309,11 @@ async function orderLoop(orders) {
 async function settlementWatch(orders) {
     const settled = new Set();
     let stalled = 0;
-    const STALL_S = Math.max(40, ORDERS * (ARRIVAL_S + 8));
+    // Poll-driven twins add latency per order (poll pickup + print + report), and
+    // a fault adds a service round-trip, so the broker needs generous time to
+    // converge (it retries placement every tick via release-on-skip). This is a
+    // no-progress watchdog, not a deadline — steady settling keeps resetting it.
+    const STALL_S = Math.max(60, ORDERS * (ARRIVAL_S + 14));
     while (!done) {
         await sleep(1000);
         let progressed = false;
@@ -334,8 +331,9 @@ async function settlementWatch(orders) {
                     const ok = outcomes.filter((o) => o.outcome === 'success').length;
                     const bad = outcomes.length - ok;
                     stats.printed += ok;
+                    stats.faulted += bad;
                     stats.dispatched += outcomes.length;
-                    console.log(`[${ts()}]   [settle]   ${order.orderId} — ${ok} printed${bad ? `, ${bad} cancelled` : ''} [${stats.settled}/${ORDERS}]`);
+                    console.log(`[${ts()}]   [settle]   ${order.orderId} — ${ok} printed${bad ? `, ${bad} faulted` : ''} [${stats.settled}/${ORDERS}]`);
                 }
             }
             catch { /* 202 still running */ }
@@ -360,6 +358,10 @@ async function retireTwins(fleet) {
         console.log(`[${ts()}] KEEP=1 — leaving ${fleet.length} twins advertising`);
         return;
     }
+    if (stats.settled < ORDERS) {
+        console.log(`[${ts()}] ${stats.settled}/${ORDERS} settled — leaving twins up so the broker can finish (rerun with KEEP=1 to keep them)`);
+        return;
+    }
     await sleep(2000); // let any last twin re-advertise after a service visit
     let retired = 0;
     for (let sweep = 0; sweep < 4 && retired < fleet.length; sweep++) {
@@ -379,21 +381,6 @@ async function retireTwins(fleet) {
     }
     console.log(`[${ts()}] Retired ${retired} idle twin${retired === 1 ? '' : 's'}`);
 }
-// ── Optional office-link preflight ────────────────────────────────────────────
-async function preflightFarmManager() {
-    if (!FARM_MANAGER_URL)
-        return;
-    process.stdout.write(`[${ts()}] Preflight → ${FARM_MANAGER_URL} … `);
-    try {
-        const ctrl = new AbortController();
-        const t = setTimeout(() => ctrl.abort(), 4000);
-        const res = await fetch(FARM_MANAGER_URL, { signal: ctrl.signal }).finally(() => clearTimeout(t));
-        console.log(`reachable (HTTP ${res.status}). Set FARM_MANAGER_BACKEND=http + FARM_MANAGER_BASE_URL on the app to dispatch for real.`);
-    }
-    catch (err) {
-        console.log(`UNREACHABLE (${String(err?.message).slice(0, 60)}). Check the office wifi link — see the README connectivity walkthrough.`);
-    }
-}
 // ── Main ──────────────────────────────────────────────────────────────────────
 async function main() {
     const runId = Math.floor(Date.now() / 1000).toString();
@@ -401,17 +388,16 @@ async function main() {
     const fleet = planFleet(batchTag);
     const fleetById = new Map(fleet.map((t) => [t.printerId, t]));
     console.log(`\n  Twin Farm  ──  ${FLEET} printers, ${ORDERS} orders (≤${UNITS} units), filaments [${FILAMENTS.join(', ')}]`);
-    console.log(`  arrival=${ARRIVAL_S}s poll=${POLL_MS}ms fail=${FAIL_PCT}% broker=${RUN_BROKER ? `on (idle≤${BROKER_IDLE})` : 'external'} keep=${KEEP}`);
+    console.log(`  arrival=${ARRIVAL_S}s fail=${FAIL_PCT}% (${FAIL_MODE}) broker=${RUN_BROKER ? `on (idle≤${BROKER_IDLE})` : 'external'} keep=${KEEP}`);
     console.log(`  Server: ${BASE_URL}\n`);
     await login();
     await ensureTwinRoles();
-    await preflightFarmManager();
-    // 1. Launch the fleet — each twin raises a registration escalation and parks.
+    // 1. Launch the fleet — each twin onboards (register → bind) then advertises.
     console.log(`\n[${ts()}] Launching ${FLEET} twins …`);
     for (const spec of fleet)
         await startTwin(spec);
     // 2. Register + service loops start now so twins come online as they appear.
-    const humanLoops = [registerLoop(fleetById), serviceLoop(), failLoop()];
+    const humanLoops = [registerLoop(fleetById), serviceLoop()];
     // 3. Broker (once the humans are watching).
     if (RUN_BROKER) {
         await startBroker(batchTag);
@@ -433,7 +419,7 @@ async function main() {
     console.log(`\n[${ts()}] Done in ${elapsed}s`);
     console.log(`  Registered:  ${stats.registered}/${FLEET}`);
     console.log(`  Orders:      ${stats.settled}/${ORDERS} settled`);
-    console.log(`  Units:       ${stats.printed} printed${stats.cancelled ? `, ${stats.cancelled} cancelled` : ''} (${stats.dispatched} dispatched)`);
+    console.log(`  Units:       ${stats.printed} printed${stats.faulted ? `, ${stats.faulted} faulted` : ''} (${stats.dispatched} dispatched)`);
     console.log(`  Serviced:    ${stats.serviced}`);
     console.log(`\n  Dashboard: ${BASE_URL}/escalations\n`);
     process.exit(0);

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

@@ -29,6 +29,19 @@ export declare function searchEscalationsFaceted(opts: {
     escalations: LTEscalationRecord[];
     total: number;
 }>;
+/**
+ * Single-query escalation read for the resolve UI: the escalation row PLUS the
+ * role's escalation form, resolved to the version the escalation pinned
+ * (`metadata.schema_version`) or the role's latest when unpinned, JOINed from the
+ * roles tables and returned as `form_schema`. The form is NOT stored on the
+ * escalation — it rides in from lt_role_schemas/lt_roles on this one query, so a
+ * versioned JIT UI costs no per-row space and one SQL call to render. The version
+ * cast is guarded, so a non-numeric pin simply falls through to the latest form.
+ */
+export declare function getEscalationWithFormSchema(id: string): Promise<{
+    escalation: LTEscalationRecord;
+    form_schema: Record<string, any> | null;
+} | null>;
 /**
  * Distinct top-level metadata facet KEYS visible to the caller — feeds the faceted
  * UI's key autocomplete so it only ever offers facets that ACTUALLY exist in the

package/build/services/escalation/queries.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.searchEscalationsFaceted = searchEscalationsFaceted;
+exports.getEscalationWithFormSchema = getEscalationWithFormSchema;
 exports.listFacetKeys = listFacetKeys;
 exports.getEscalationStats = getEscalationStats;
 exports.listDistinctTypes = listDistinctTypes;
@@ -143,6 +144,32 @@ async function searchEscalationsFaceted(opts) {
     ]);
     return { escalations: (0, map_1.toEscalationRecords)(rows.rows), total: countRows.rows[0]?.total ?? 0 };
 }
+/**
+ * Single-query escalation read for the resolve UI: the escalation row PLUS the
+ * role's escalation form, resolved to the version the escalation pinned
+ * (`metadata.schema_version`) or the role's latest when unpinned, JOINed from the
+ * roles tables and returned as `form_schema`. The form is NOT stored on the
+ * escalation — it rides in from lt_role_schemas/lt_roles on this one query, so a
+ * versioned JIT UI costs no per-row space and one SQL call to render. The version
+ * cast is guarded, so a non-numeric pin simply falls through to the latest form.
+ */
+async function getEscalationWithFormSchema(id) {
+    await (0, client_1.ensureEscalationCompatView)();
+    const pool = (0, db_1.getPool)();
+    const { rows } = await pool.query(`SELECT e.*, COALESCE(ps.form_schema, r.form_schema) AS resolved_form_schema
+       FROM public.lt_escalations e
+       LEFT JOIN public.lt_roles r ON r.role = e.role
+       LEFT JOIN public.lt_role_schemas ps
+         ON ps.role = e.role
+        AND ps.version = CASE WHEN e.metadata->>'schema_version' ~ '^[0-9]+$'
+                              THEN (e.metadata->>'schema_version')::int END
+      WHERE e.id = $1`, [id]);
+    if (!rows[0])
+        return null;
+    const { resolved_form_schema, ...row } = rows[0];
+    const [escalation] = (0, map_1.toEscalationRecords)([row]);
+    return { escalation, form_schema: resolved_form_schema ?? null };
+}
 /**
  * Distinct top-level metadata facet KEYS visible to the caller — feeds the faceted
  * UI's key autocomplete so it only ever offers facets that ACTUALLY exist in the

package/build/services/orchestrator/condition.d.ts

@@ -1,10 +1,13 @@
 import type { Types } from '@hotmeshio/hotmesh';
 /**
  * HotMesh's escalation config plus long-tail sugar. `schemaVersion` pins the
- * role-schema version (lt_role_schemas) the resolver form should render; it is
- * folded into `metadata.schema_version` before the config reaches the engine,
- * so the pin rides the row's GIN-indexed metadata like any other facet. Omit
- * it and the resolver UI simply uses the role's latest schema.
+ * role form version (lt_role_schemas) the resolve UI renders; it is a
+ * compile-time LITERAL the workflow author sets, folded into
+ * `metadata.schema_version` before the config reaches the engine, so the pin
+ * rides the row's GIN-indexed metadata like any other facet. Folding is a pure
+ * transform — no query, no activity — so a pinned `conditionLT` costs exactly
+ * what an unpinned one does. Omit it and the resolve UI renders the role's latest
+ * form when the escalation is fetched.
  */
 export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
     schemaVersion?: number;
@@ -33,17 +36,20 @@ export type ConditionEscalationConfig = Types.ConditionQueueConfig & {
  * });
  * ```
  *
- * **Pin the role schema version (optional).** Role form/metadata schemas are
- * versioned (lt_role_schemas). Set `schemaVersion` when this wait depends on a
- * specific shape — e.g. a review form that gained a field the workflow expects
- * back. The resolver UI renders exactly that version for this escalation;
- * without it, the role's latest schema always applies.
+ * **Pin the role form version — a compile-time literal.** A role's escalation
+ * form is versioned (lt_role_schemas); its first form is version 1. Pass the
+ * version as a literal, paired with the generic `<T>` payload type, both bumped
+ * together when the form evolves. The literal folds into metadata for the same
+ * cost as an unpinned wait. Omit it and the resolve UI renders the role's latest
+ * form when the escalation is fetched.
  *
  * ```typescript
- * const decision = await conditionLT<{ approved: boolean; lotNumber: string }>(signalId, {
- *   role: 'reviewer',
+ * import { INTAKE_SCHEMA_VERSION, type IntakeResolverV1 } from './forms';
+ *
+ * const decision = await conditionLT<IntakeResolverV1>(signalId, {
+ *   role: INTAKE_ROLE,
  *   description: instructions,
- *   schemaVersion: 3,                     // render role schema v3 for this row
+ *   schemaVersion: INTAKE_SCHEMA_VERSION, // the form version this code is written for
  * });
  * ```
  *