@wopr-network/defcon 1.3.0 → 1.5.0

package/dist/src/api/wire-types.d.ts

@@ -12,6 +12,7 @@ export type ClaimResponse = {
     invocation_id: string;
     flow: string | null;
     stage: string;
+    agent_role: string | null;
     prompt: string;
     context: Record<string, unknown> | null;
     worker_notice?: string;

package/dist/src/config/seed-loader.js

@@ -63,6 +63,7 @@ async function parseSeedAndLoad(json, flowRepo, gateRepo, db) {
                 timeoutMs: g.timeoutMs,
                 failurePrompt: g.failurePrompt,
                 timeoutPrompt: g.timeoutPrompt,
+                outcomes: g.outcomes,
             });
             gateNameToId.set(g.name, gate.id);
         }
@@ -75,6 +76,7 @@ async function parseSeedAndLoad(json, flowRepo, gateRepo, db) {
                 initialState: f.initialState,
                 maxConcurrent: f.maxConcurrent,
                 maxConcurrentPerRepo: f.maxConcurrentPerRepo,
+                claimRetryAfterMs: f.claimRetryAfterMs,
                 gateTimeoutMs: f.gateTimeoutMs,
                 createdBy: f.createdBy,
                 discipline: f.discipline,
@@ -85,11 +87,13 @@ async function parseSeedAndLoad(json, flowRepo, gateRepo, db) {
             for (const s of flowStates) {
                 await flowRepo.addState(flow.id, {
                     name: s.name,
+                    agentRole: s.agentRole,
                     modelTier: s.modelTier,
                     mode: s.mode,
                     promptTemplate: s.promptTemplate,
                     constraints: s.constraints,
                     onEnter: s.onEnter,
+                    retryAfterMs: s.retryAfterMs,
                 });
             }
             const flowTransitions = parsed.transitions.filter((t) => t.flowName === f.name);

package/dist/src/config/zod-schemas.d.ts

@@ -7,6 +7,7 @@ export declare const FlowDefinitionSchema: z.ZodObject<{
     maxConcurrent: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     maxConcurrentPerRepo: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     affinityWindowMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+    claimRetryAfterMs: z.ZodOptional<z.ZodNumber>;
     gateTimeoutMs: z.ZodOptional<z.ZodNumber>;
     version: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     createdBy: z.ZodOptional<z.ZodString>;
@@ -22,6 +23,7 @@ export declare const OnEnterSchema: z.ZodObject<{
 export declare const StateDefinitionSchema: z.ZodObject<{
     name: z.ZodString;
     flowName: z.ZodString;
+    agentRole: z.ZodOptional<z.ZodString>;
     modelTier: z.ZodOptional<z.ZodString>;
     mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
         passive: "passive";
@@ -34,12 +36,17 @@ export declare const StateDefinitionSchema: z.ZodObject<{
         artifacts: z.ZodArray<z.ZodString>;
         timeout_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
     }, z.core.$strip>>;
+    retryAfterMs: z.ZodOptional<z.ZodNumber>;
 }, z.core.$strip>;
 export declare const CommandGateSchema: z.ZodObject<{
     name: z.ZodString;
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"command">;
     command: z.ZodString;
 }, z.core.$strip>;
@@ -48,6 +55,10 @@ export declare const FunctionGateSchema: z.ZodObject<{
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"function">;
     functionRef: z.ZodString;
 }, z.core.$strip>;
@@ -56,6 +67,10 @@ export declare const ApiGateSchema: z.ZodObject<{
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"api">;
     apiConfig: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>;
@@ -64,6 +79,10 @@ export declare const GateDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"command">;
     command: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
@@ -71,6 +90,10 @@ export declare const GateDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"function">;
     functionRef: z.ZodString;
 }, z.core.$strip>, z.ZodObject<{
@@ -78,6 +101,10 @@ export declare const GateDefinitionSchema: z.ZodDiscriminatedUnion<[z.ZodObject<
     timeoutMs: z.ZodOptional<z.ZodNumber>;
     failurePrompt: z.ZodOptional<z.ZodString>;
     timeoutPrompt: z.ZodOptional<z.ZodString>;
+    outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        proceed: z.ZodOptional<z.ZodBoolean>;
+        toState: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
     type: z.ZodLiteral<"api">;
     apiConfig: z.ZodRecord<z.ZodString, z.ZodUnknown>;
 }, z.core.$strip>], "type">;
@@ -101,6 +128,7 @@ export declare const SeedFileSchema: z.ZodObject<{
         maxConcurrent: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         maxConcurrentPerRepo: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         affinityWindowMs: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        claimRetryAfterMs: z.ZodOptional<z.ZodNumber>;
         gateTimeoutMs: z.ZodOptional<z.ZodNumber>;
         version: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         createdBy: z.ZodOptional<z.ZodString>;
@@ -111,6 +139,7 @@ export declare const SeedFileSchema: z.ZodObject<{
     states: z.ZodArray<z.ZodObject<{
         name: z.ZodString;
         flowName: z.ZodString;
+        agentRole: z.ZodOptional<z.ZodString>;
         modelTier: z.ZodOptional<z.ZodString>;
         mode: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
             passive: "passive";
@@ -123,12 +152,17 @@ export declare const SeedFileSchema: z.ZodObject<{
             artifacts: z.ZodArray<z.ZodString>;
             timeout_ms: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
         }, z.core.$strip>>;
+        retryAfterMs: z.ZodOptional<z.ZodNumber>;
     }, z.core.$strip>>;
     gates: z.ZodDefault<z.ZodOptional<z.ZodArray<z.ZodDiscriminatedUnion<[z.ZodObject<{
         name: z.ZodString;
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         failurePrompt: z.ZodOptional<z.ZodString>;
         timeoutPrompt: z.ZodOptional<z.ZodString>;
+        outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            proceed: z.ZodOptional<z.ZodBoolean>;
+            toState: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         type: z.ZodLiteral<"command">;
         command: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
@@ -136,6 +170,10 @@ export declare const SeedFileSchema: z.ZodObject<{
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         failurePrompt: z.ZodOptional<z.ZodString>;
         timeoutPrompt: z.ZodOptional<z.ZodString>;
+        outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            proceed: z.ZodOptional<z.ZodBoolean>;
+            toState: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         type: z.ZodLiteral<"function">;
         functionRef: z.ZodString;
     }, z.core.$strip>, z.ZodObject<{
@@ -143,6 +181,10 @@ export declare const SeedFileSchema: z.ZodObject<{
         timeoutMs: z.ZodOptional<z.ZodNumber>;
         failurePrompt: z.ZodOptional<z.ZodString>;
         timeoutPrompt: z.ZodOptional<z.ZodString>;
+        outcomes: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+            proceed: z.ZodOptional<z.ZodBoolean>;
+            toState: z.ZodOptional<z.ZodString>;
+        }, z.core.$strip>>>;
         type: z.ZodLiteral<"api">;
         apiConfig: z.ZodRecord<z.ZodString, z.ZodUnknown>;
     }, z.core.$strip>], "type">>>>;

package/dist/src/config/zod-schemas.js

@@ -10,6 +10,7 @@ export const FlowDefinitionSchema = z.object({
     maxConcurrent: z.number().int().min(0).optional().default(0),
     maxConcurrentPerRepo: z.number().int().min(0).optional().default(0),
     affinityWindowMs: z.number().int().min(0).optional().default(300000),
+    claimRetryAfterMs: z.number().int().min(0).optional(),
     gateTimeoutMs: z.number().int().min(1).optional(),
     version: z.number().int().min(1).optional().default(1),
     createdBy: z.string().optional(),
@@ -36,6 +37,7 @@ export const OnEnterSchema = z.object({
 export const StateDefinitionSchema = z.object({
     name: z.string().min(1),
     flowName: z.string().min(1),
+    agentRole: z.string().optional(),
     modelTier: z.string().optional(),
     mode: z.enum(["passive", "active"]).optional().default("passive"),
     promptTemplate: z
@@ -47,13 +49,19 @@ export const StateDefinitionSchema = z.object({
         .optional(),
     constraints: z.record(z.string(), z.unknown()).optional(),
     onEnter: OnEnterSchema.optional(),
+    retryAfterMs: z.number().int().min(0).optional(),
 });
 // Gate: discriminated union on `type`
+const GateOutcomeSchema = z.object({
+    proceed: z.boolean().optional(),
+    toState: z.string().min(1).optional(),
+});
 const BaseGateSchema = z.object({
     name: z.string().min(1),
     timeoutMs: z.number().int().min(1).optional(),
     failurePrompt: z.string().optional(),
     timeoutPrompt: z.string().min(1).optional(),
+    outcomes: z.record(z.string(), GateOutcomeSchema).optional(),
 });
 export const CommandGateSchema = BaseGateSchema.extend({
     type: z.literal("command"),

package/dist/src/engine/engine.d.ts

@@ -54,7 +54,15 @@ export declare class Engine {
     undrainWorker(workerId: string): void;
     isDraining(workerId: string): boolean;
     listDrainingWorkers(): string[];
+    emit(event: import("./event-types.js").EngineEvent): Promise<void>;
     processSignal(entityId: string, signal: string, artifacts?: Artifacts, triggeringInvocationId?: string): Promise<ProcessSignalResult>;
+    /**
+     * Evaluate a gate and return a routing decision:
+     * - `proceed`  — gate passed, continue to transition.toState
+     * - `redirect` — gate outcome maps to a different toState
+     * - `block`    — gate failed or timed out; caller should return this as the signal result
+     */
+    private resolveGate;
     createEntity(flowName: string, refs?: Record<string, {
         adapter: string;
         id: string;

package/dist/src/engine/engine.js

@@ -39,6 +39,9 @@ export class Engine {
     listDrainingWorkers() {
         return Array.from(this.drainingWorkers);
     }
+    async emit(event) {
+        await this.eventEmitter.emit(event);
+    }
     async processSignal(entityId, signal, artifacts, triggeringInvocationId) {
         // 1. Load entity
         const entity = await this.entityRepo.get(entityId);
@@ -52,83 +55,20 @@ export class Engine {
         const transition = findTransition(flow, entity.state, signal, { entity }, true, this.logger);
         if (!transition)
             throw new ValidationError(`No transition from "${entity.state}" on signal "${signal}" in flow "${flow.name}"`);
-        // 4. Evaluate gate if present
-        const gatesPassed = [];
-        if (transition.gateId) {
-            const gate = await this.gateRepo.get(transition.gateId);
-            if (!gate)
-                throw new NotFoundError(`Gate "${transition.gateId}" not found`);
-            const gateResult = await evaluateGate(gate, entity, this.gateRepo, flow.gateTimeoutMs);
-            if (!gateResult.passed) {
-                // Persist gate failure into entity artifacts for retry context
-                const priorFailures = Array.isArray(entity.artifacts?.gate_failures)
-                    ? entity.artifacts.gate_failures
-                    : [];
-                await this.entityRepo.updateArtifacts(entityId, {
-                    gate_failures: [
-                        ...priorFailures,
-                        {
-                            gateId: gate.id,
-                            gateName: gate.name,
-                            output: gateResult.output,
-                            failedAt: new Date().toISOString(),
-                        },
-                    ],
-                });
-                if (gateResult.timedOut) {
-                    await this.eventEmitter.emit({
-                        type: "gate.timedOut",
-                        entityId,
-                        gateId: gate.id,
-                        emittedAt: new Date(),
-                    });
-                }
-                else {
-                    await this.eventEmitter.emit({
-                        type: "gate.failed",
-                        entityId,
-                        gateId: gate.id,
-                        emittedAt: new Date(),
-                    });
-                }
-                let resolvedTimeoutPrompt;
-                if (gateResult.timedOut) {
-                    const rawTemplate = gate.timeoutPrompt ?? flow.timeoutPrompt ?? DEFAULT_TIMEOUT_PROMPT;
-                    try {
-                        const hbs = getHandlebars();
-                        const template = hbs.compile(rawTemplate);
-                        resolvedTimeoutPrompt = template({
-                            entity,
-                            flow,
-                            gate: { name: gate.name, output: gateResult.output },
-                        });
-                    }
-                    catch (err) {
-                        this.logger.error("[engine] Failed to render timeoutPrompt template:", err);
-                        resolvedTimeoutPrompt = DEFAULT_TIMEOUT_PROMPT;
-                    }
-                }
-                return {
-                    gated: true,
-                    gateTimedOut: gateResult.timedOut,
-                    gateOutput: gateResult.output,
-                    gateName: gate.name,
-                    failurePrompt: gate.failurePrompt ?? undefined,
-                    timeoutPrompt: resolvedTimeoutPrompt,
-                    gatesPassed,
-                    terminal: false,
-                };
-            }
-            gatesPassed.push(gate.name);
-            await this.eventEmitter.emit({
-                type: "gate.passed",
-                entityId,
-                gateId: gate.id,
-                emittedAt: new Date(),
-            });
+        // 4. Evaluate gate — returns a routing decision or a block result to return immediately.
+        const routing = transition.gateId
+            ? await this.resolveGate(transition.gateId, entity, flow)
+            : { kind: "proceed", gatesPassed: [] };
+        if (routing.kind === "block") {
+            return { gated: true, ...routing, terminal: false };
         }
+        // Gate passed or redirected — determine the actual destination.
+        const toState = routing.kind === "redirect" ? routing.toState : transition.toState;
+        const trigger = routing.kind === "redirect" ? routing.trigger : signal;
+        const spawnFlow = routing.kind === "redirect" ? null : transition.spawnFlow;
+        const { gatesPassed } = routing;
         // 5. Transition entity
-        let updated = await this.entityRepo.transition(entityId, transition.toState, signal, artifacts);
+        let updated = await this.entityRepo.transition(entityId, toState, trigger, artifacts);
         // Clear gate_failures on successful transition so stale failures don't bleed into future agent prompts
         await this.entityRepo.updateArtifacts(entityId, { gate_failures: [] });
         // Keep the in-memory entity in sync so buildInvocation sees the cleared failures
@@ -139,25 +79,25 @@ export class Engine {
             entityId,
             flowId: flow.id,
             fromState: entity.state,
-            toState: transition.toState,
-            trigger: signal,
+            toState,
+            trigger,
             emittedAt: new Date(),
         });
         const result = {
-            newState: transition.toState,
+            newState: toState,
             gatesPassed,
             gated: false,
             terminal: false,
         };
         // 6b. Execute onEnter hook if defined on the new state
-        const newStateDef = flow.states.find((s) => s.name === transition.toState);
+        const newStateDef = flow.states.find((s) => s.name === toState);
         if (newStateDef?.onEnter) {
             const onEnterResult = await executeOnEnter(newStateDef.onEnter, updated, this.entityRepo);
             if (onEnterResult.skipped) {
                 await this.eventEmitter.emit({
                     type: "onEnter.skipped",
                     entityId,
-                    state: transition.toState,
+                    state: toState,
                     emittedAt: new Date(),
                 });
             }
@@ -165,20 +105,20 @@ export class Engine {
                 await this.eventEmitter.emit({
                     type: "onEnter.failed",
                     entityId,
-                    state: transition.toState,
+                    state: toState,
                     error: onEnterResult.error,
                     emittedAt: new Date(),
                 });
                 await this.transitionLogRepo.record({
                     entityId,
                     fromState: entity.state,
-                    toState: transition.toState,
-                    trigger: signal,
+                    toState,
+                    trigger,
                     invocationId: triggeringInvocationId ?? null,
                     timestamp: new Date(),
                 });
                 return {
-                    newState: transition.toState,
+                    newState: toState,
                     gatesPassed,
                     gated: false,
                     onEnterFailed: true,
@@ -190,7 +130,7 @@ export class Engine {
                 await this.eventEmitter.emit({
                     type: "onEnter.completed",
                     entityId,
-                    state: transition.toState,
+                    state: toState,
                     artifacts: onEnterResult.artifacts ?? {},
                     emittedAt: new Date(),
                 });
@@ -211,15 +151,15 @@ export class Engine {
                 ]);
                 const enriched = { ...updated, invocations, gateResults };
                 const build = await buildInvocation(newStateDef, enriched, this.adapters, flow, this.logger);
-                const invocation = await this.invocationRepo.create(entityId, transition.toState, build.prompt, build.mode, undefined, build.systemPrompt || build.userContent
+                const invocation = await this.invocationRepo.create(entityId, toState, build.prompt, build.mode, undefined, build.systemPrompt || build.userContent
                     ? { systemPrompt: build.systemPrompt, userContent: build.userContent }
-                    : undefined);
+                    : undefined, newStateDef.agentRole ?? null);
                 result.invocationId = invocation.id;
                 await this.eventEmitter.emit({
                     type: "invocation.created",
                     entityId,
                     invocationId: invocation.id,
-                    stage: transition.toState,
+                    stage: toState,
                     emittedAt: new Date(),
                 });
             }
@@ -229,13 +169,13 @@ export class Engine {
         await this.transitionLogRepo.record({
             entityId,
             fromState: entity.state,
-            toState: transition.toState,
-            trigger: signal,
+            toState,
+            trigger,
             invocationId: triggeringInvocationId ?? null,
             timestamp: new Date(),
         });
         // 9. Spawn child flows
-        const spawned = await executeSpawn(transition, updated, this.flowRepo, this.entityRepo, this.logger);
+        const spawned = await executeSpawn({ spawnFlow }, updated, this.flowRepo, this.entityRepo, this.logger);
         if (spawned) {
             result.spawned = [spawned.id];
             await this.eventEmitter.emit({
@@ -246,14 +186,93 @@ export class Engine {
                 emittedAt: new Date(),
             });
         }
-        // 10. Mark terminal — no invocation is created for terminal states (handled above),
-        //     but we surface terminality in the result for callers.
-        if (isTerminal(flow, transition.toState)) {
+        // 10. Mark terminal
+        if (isTerminal(flow, toState)) {
             result.terminal = true;
             result.spawned = result.spawned ?? [];
         }
         return result;
     }
+    /**
+     * Evaluate a gate and return a routing decision:
+     * - `proceed`  — gate passed, continue to transition.toState
+     * - `redirect` — gate outcome maps to a different toState
+     * - `block`    — gate failed or timed out; caller should return this as the signal result
+     */
+    async resolveGate(gateId, entity, flow) {
+        const gate = await this.gateRepo.get(gateId);
+        if (!gate)
+            throw new NotFoundError(`Gate "${gateId}" not found`);
+        const gateResult = await evaluateGate(gate, entity, this.gateRepo, flow.gateTimeoutMs);
+        const namedOutcome = gateResult.outcome && gate.outcomes ? gate.outcomes[gateResult.outcome] : undefined;
+        if (namedOutcome?.toState) {
+            const outcomeLabel = gateResult.outcome ?? gate.name;
+            await this.eventEmitter.emit({
+                type: "gate.redirected",
+                entityId: entity.id,
+                gateId: gate.id,
+                outcome: outcomeLabel,
+                toState: namedOutcome.toState,
+                emittedAt: new Date(),
+            });
+            return {
+                kind: "redirect",
+                toState: namedOutcome.toState,
+                trigger: `gate:${gate.name}:${outcomeLabel}`,
+                gatesPassed: [gate.name],
+            };
+        }
+        if (namedOutcome?.proceed || (!namedOutcome && gateResult.passed)) {
+            await this.eventEmitter.emit({
+                type: "gate.passed",
+                entityId: entity.id,
+                gateId: gate.id,
+                emittedAt: new Date(),
+            });
+            return { kind: "proceed", gatesPassed: [gate.name] };
+        }
+        // Gate failed — persist failure context and emit event
+        const priorFailures = Array.isArray(entity.artifacts?.gate_failures)
+            ? entity.artifacts.gate_failures
+            : [];
+        await this.entityRepo.updateArtifacts(entity.id, {
+            gate_failures: [
+                ...priorFailures,
+                { gateId: gate.id, gateName: gate.name, output: gateResult.output, failedAt: new Date().toISOString() },
+            ],
+        });
+        await this.eventEmitter.emit({
+            type: gateResult.timedOut ? "gate.timedOut" : "gate.failed",
+            entityId: entity.id,
+            gateId: gate.id,
+            emittedAt: new Date(),
+        });
+        let timeoutPrompt;
+        if (gateResult.timedOut) {
+            const rawTemplate = gate.timeoutPrompt ?? flow.timeoutPrompt ?? DEFAULT_TIMEOUT_PROMPT;
+            try {
+                const hbs = getHandlebars();
+                timeoutPrompt = hbs.compile(rawTemplate)({
+                    entity,
+                    flow,
+                    gate: { name: gate.name, output: gateResult.output },
+                });
+            }
+            catch (err) {
+                this.logger.error("[engine] Failed to render timeoutPrompt template:", err);
+                timeoutPrompt = DEFAULT_TIMEOUT_PROMPT;
+            }
+        }
+        return {
+            kind: "block",
+            gateTimedOut: gateResult.timedOut,
+            gateOutput: gateResult.output,
+            gateName: gate.name,
+            failurePrompt: gate.failurePrompt ?? undefined,
+            timeoutPrompt,
+            gatesPassed: [],
+        };
+    }
     async createEntity(flowName, refs, payload) {
         const flow = await this.flowRepo.getByName(flowName);
         if (!flow)
@@ -312,7 +331,7 @@ export class Engine {
             const build = await buildInvocation(initialState, enriched, this.adapters, flow, this.logger);
             await this.invocationRepo.create(entity.id, flow.initialState, build.prompt, build.mode, undefined, build.systemPrompt || build.userContent
                 ? { systemPrompt: build.systemPrompt, userContent: build.userContent }
-                : undefined);
+                : undefined, initialState.agentRole ?? null);
         }
         return entity;
     }
@@ -484,7 +503,7 @@ export class Engine {
                 const build = await this.buildPromptForEntity(state, claimed, flow);
                 const invocation = await this.invocationRepo.create(claimed.id, state.name, build.prompt, build.mode, undefined, build.systemPrompt || build.userContent
                     ? { systemPrompt: build.systemPrompt, userContent: build.userContent }
-                    : undefined);
+                    : undefined, state.agentRole ?? null);
                 const entityClaimToken = worker_id ?? `agent:${role}`;
                 let claimedInvocation;
                 try {

package/dist/src/engine/event-types.d.ts

@@ -68,6 +68,13 @@ export type EngineEvent = {
     entityId: string;
     gateId: string;
     emittedAt: Date;
+} | {
+    type: "gate.redirected";
+    entityId: string;
+    gateId: string;
+    outcome: string;
+    toState: string;
+    emittedAt: Date;
 } | {
     type: "flow.spawned";
     entityId: string;

package/dist/src/engine/flow-spawner.d.ts

@@ -1,8 +1,10 @@
 import type { Logger } from "../logger.js";
-import type { Entity, IEntityRepository, IFlowRepository, Transition } from "../repositories/interfaces.js";
+import type { Entity, IEntityRepository, IFlowRepository } from "../repositories/interfaces.js";
 /**
  * If the transition has a spawnFlow, look up that flow and create a new entity in it.
  * The spawned entity inherits the parent entity's refs.
  * Returns the spawned entity, or null if no spawn is configured.
  */
-export declare function executeSpawn(transition: Transition, parentEntity: Entity, flowRepo: IFlowRepository, entityRepo: IEntityRepository, logger?: Logger): Promise<Entity | null>;
+export declare function executeSpawn(transition: {
+    spawnFlow: string | null | undefined;
+}, parentEntity: Entity, flowRepo: IFlowRepository, entityRepo: IEntityRepository, logger?: Logger): Promise<Entity | null>;

package/dist/src/engine/gate-evaluator.d.ts

@@ -3,6 +3,10 @@ export interface GateEvalResult {
     passed: boolean;
     timedOut: boolean;
     output: string;
+    /** Named outcome from structured JSON output, if the gate emitted one. */
+    outcome?: string;
+    /** Human-readable message from structured JSON output. */
+    message?: string;
 }
 export declare function resolveGateTimeout(gateTimeoutMs: number | null | undefined, flowGateTimeoutMs: number | null | undefined): number;
 /**

package/dist/src/engine/gate-evaluator.js

@@ -59,6 +59,33 @@ export async function evaluateGate(gate, entity, gateRepo, flowGateTimeoutMs) {
         passed = result.exitCode === 0;
         output = result.output;
         timedOut = result.timedOut;
+        // Parse structured JSON outcome from the last non-empty output line.
+        // Gate scripts can emit { outcome: string, message?: string } as their final line
+        // to enable named outcome routing (e.g. "blocked" → toState: "fixing").
+        const lastLine = result.output
+            .split("\n")
+            .map((l) => l.trim())
+            .filter(Boolean)
+            .at(-1);
+        if (lastLine?.startsWith("{")) {
+            try {
+                const parsed = JSON.parse(lastLine);
+                if (typeof parsed.outcome === "string") {
+                    const outcomeResult = {
+                        passed,
+                        timedOut,
+                        output: result.output,
+                        outcome: parsed.outcome,
+                        message: typeof parsed.message === "string" ? parsed.message : undefined,
+                    };
+                    await gateRepo.record(entity.id, gate.id, passed, result.output);
+                    return outcomeResult;
+                }
+            }
+            catch {
+                // Not JSON — treat output as plain text, fall through to normal path
+            }
+        }
     }
     else if (gate.type === "function") {
         try {

package/dist/src/execution/active-runner.js

@@ -104,7 +104,7 @@ export class ActiveRunner {
                 await this.entityRepo.updateArtifacts(invocation.entityId, { stuck: true, stuckAt: new Date().toISOString() });
                 return;
             }
-            await this.invocationRepo.create(invocation.entityId, invocation.stage, invocation.prompt, invocation.mode, undefined, { ...(invocation.context ?? {}), retryCount: retryCount + 1 });
+            await this.invocationRepo.create(invocation.entityId, invocation.stage, invocation.prompt, invocation.mode, undefined, { ...(invocation.context ?? {}), retryCount: retryCount + 1 }, invocation.agentRole);
             return;
         }
         // Gate timed out — re-queue after backoff instead of failing.
@@ -113,7 +113,7 @@ export class ActiveRunner {
         if (result.gated && result.gateTimedOut) {
             const retryAfterMs = 30000;
             this.logger.info(`[active-runner] gate timed out for entity ${invocation.entityId}, re-queuing after ${retryAfterMs}ms`);
-            await this.invocationRepo.create(invocation.entityId, invocation.stage, invocation.prompt, invocation.mode, undefined, invocation.context ?? undefined);
+            await this.invocationRepo.create(invocation.entityId, invocation.stage, invocation.prompt, invocation.mode, undefined, invocation.context ?? undefined, invocation.agentRole);
             await sleep(retryAfterMs, signal);
             return;
         }