@wopr-network/defcon 0.2.2 → 1.0.1

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

@@ -19,6 +19,8 @@ export interface ProcessSignalResult {
 export interface ClaimWorkResult {
     entityId: string;
     invocationId: string;
+    flowName: string;
+    stage: string;
     prompt: string;
     context: Record<string, unknown> | null;
 }
@@ -53,16 +55,8 @@ export declare class Engine {
         id: string;
         [key: string]: unknown;
     }>): Promise<Entity>;
-    claimWork(role: string, flowName?: string, worker_id?: string): Promise<ClaimWorkResult | null>;
-    /**
-     * Try to claim an existing unclaimed invocation for an already-claimed entity.
-     * Handles the race condition where another worker claims the invocation first
-     * (releases the entity claim and returns null so the caller can try the next candidate).
-     */
-    private tryClaimInvocation;
-    private setAffinityIfNeeded;
-    private buildPrompt;
-    private emitAndReturn;
+    claimWork(role: string, flowName?: string, worker_id?: string): Promise<ClaimWorkResult | "all_claimed" | null>;
+    private buildPromptForEntity;
     getStatus(): Promise<EngineStatus>;
     startReaper(intervalMs: number, entityTtlMs?: number): () => Promise<void>;
     private checkConcurrency;

package/dist/src/engine/engine.js

@@ -1,3 +1,4 @@
+import { NotFoundError, ValidationError } from "../errors.js";
 import { consoleLogger } from "../logger.js";
 import { DEFAULT_TIMEOUT_PROMPT } from "./constants.js";
 import { executeSpawn } from "./flow-spawner.js";
@@ -29,21 +30,21 @@ export class Engine {
         // 1. Load entity
         const entity = await this.entityRepo.get(entityId);
         if (!entity)
-            throw new Error(`Entity "${entityId}" not found`);
+            throw new NotFoundError(`Entity "${entityId}" not found`);
         // 2. Load flow
         const flow = await this.flowRepo.get(entity.flowId);
         if (!flow)
-            throw new Error(`Flow "${entity.flowId}" not found`);
+            throw new NotFoundError(`Flow "${entity.flowId}" not found`);
         // 3. Find transition
         const transition = findTransition(flow, entity.state, signal, { entity }, true, this.logger);
         if (!transition)
-            throw new Error(`No transition from "${entity.state}" on signal "${signal}" in flow "${flow.name}"`);
+            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 Error(`Gate "${transition.gateId}" not found`);
+                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
@@ -243,7 +244,7 @@ export class Engine {
     async createEntity(flowName, refs) {
         const flow = await this.flowRepo.getByName(flowName);
         if (!flow)
-            throw new Error(`Flow "${flowName}" not found`);
+            throw new NotFoundError(`Flow "${flowName}" not found`);
         const entity = await this.entityRepo.create(flow.id, flow.initialState, refs);
         await this.eventEmitter.emit({
             type: "entity.created",
@@ -264,7 +265,7 @@ export class Engine {
                     error: onEnterResult.error,
                     emittedAt: new Date(),
                 });
-                throw new Error(`onEnter failed for entity ${entity.id}: ${onEnterResult.error}`);
+                throw new ValidationError(`onEnter failed for entity ${entity.id}: ${onEnterResult.error}`);
             }
             if (onEnterResult.artifacts) {
                 await this.eventEmitter.emit({
@@ -295,89 +296,238 @@ export class Engine {
         return entity;
     }
     async claimWork(role, flowName, worker_id) {
+        // 1. Find candidate flows filtered by discipline
         let flows;
         if (flowName) {
             const flow = await this.flowRepo.getByName(flowName);
-            // Validate discipline match — null discipline flows are claimable by any role
-            flows = flow && (flow.discipline === null || flow.discipline === role) ? [flow] : [];
+            if (!flow)
+                throw new Error(`Flow "${flowName}" not found`);
+            flows = flow.discipline === null || flow.discipline === role ? [flow] : [];
         }
         else {
             const allFlows = await this.flowRepo.listAll();
             flows = allFlows.filter((f) => f.discipline === null || f.discipline === role);
         }
+        if (flows.length === 0)
+            return null;
+        const candidates = [];
+        const affinityInvocationIds = new Set();
         for (const flow of flows) {
-            // Try affinity match first if worker_id provided
+            // Affinity candidates first (if worker_id provided); capture IDs for step 4
             if (worker_id) {
                 const affinityUnclaimed = await this.invocationRepo.findUnclaimedWithAffinity(flow.id, role, worker_id);
-                for (const pending of affinityUnclaimed) {
-                    const claimed = await this.entityRepo.claimById(pending.entityId, `agent:${role}`);
-                    if (!claimed)
-                        continue;
-                    const result = await this.tryClaimInvocation(pending, claimed, flow, role, worker_id);
-                    if (result)
-                        return result;
+                for (const inv of affinityUnclaimed) {
+                    candidates.push({ invocation: inv, flow });
+                    affinityInvocationIds.add(inv.id);
                 }
             }
-            // Prefer claiming an existing unclaimed invocation created by processSignal
-            // to avoid creating a duplicate. Fall back to creating a new one if none exist.
             const unclaimed = await this.invocationRepo.findUnclaimedByFlow(flow.id);
-            for (const pending of unclaimed) {
-                const claimed = await this.entityRepo.claim(flow.id, pending.stage, `agent:${role}`);
-                if (!claimed)
-                    continue;
-                const result = await this.tryClaimInvocation(pending, claimed, flow, role, worker_id);
-                if (result)
-                    return result;
+            for (const inv of unclaimed)
+                candidates.push({ invocation: inv, flow });
+        }
+        // 3. Load entities for priority sorting + dedup candidates
+        const entityMap = new Map();
+        const uniqueEntityIds = [...new Set(candidates.map((c) => c.invocation.entityId))];
+        await Promise.all(uniqueEntityIds.map(async (eid) => {
+            const entity = await this.entityRepo.get(eid);
+            if (entity)
+                entityMap.set(eid, entity);
+        }));
+        // 4. Build affinity set for priority sorting using IDs already collected in step 2 (no re-query)
+        const affinitySet = new Set();
+        if (worker_id) {
+            for (const c of candidates) {
+                if (affinityInvocationIds.has(c.invocation.id)) {
+                    affinitySet.add(c.invocation.entityId);
+                }
+            }
+        }
+        // 5. Sort: affinity → entity priority → time in state (oldest first)
+        const now = Date.now();
+        candidates.sort((a, b) => {
+            const affinityA = affinitySet.has(a.invocation.entityId) ? 1 : 0;
+            const affinityB = affinitySet.has(b.invocation.entityId) ? 1 : 0;
+            if (affinityA !== affinityB)
+                return affinityB - affinityA;
+            const entityA = entityMap.get(a.invocation.entityId);
+            const entityB = entityMap.get(b.invocation.entityId);
+            const priA = entityA?.priority ?? 0;
+            const priB = entityB?.priority ?? 0;
+            if (priA !== priB)
+                return priB - priA;
+            const timeA = entityA?.createdAt?.getTime() ?? now;
+            const timeB = entityB?.createdAt?.getTime() ?? now;
+            return timeA - timeB;
+        });
+        // 6. Dedup: only try each invocation once (affinity candidates may overlap with unclaimed)
+        const seen = new Set();
+        const deduped = candidates.filter((c) => {
+            if (seen.has(c.invocation.id))
+                return false;
+            seen.add(c.invocation.id);
+            return true;
+        });
+        // 7. Try claiming in priority order (entity-first for safe locking)
+        for (const { invocation: pending, flow } of deduped) {
+            const entity = entityMap.get(pending.entityId);
+            if (!entity)
+                continue;
+            // Guard: entity state must still match the invocation's stage — if another worker
+            // transitioned the entity between candidate fetch and now, skip this candidate.
+            if (entity.state !== pending.stage)
+                continue;
+            const entityClaimToken = worker_id ?? `agent:${role}`;
+            const claimed = await this.entityRepo.claimById(entity.id, entityClaimToken);
+            if (!claimed)
+                continue;
+            // Post-claim state validation — entity may have transitioned between guard check and claim
+            if (claimed.state !== pending.stage) {
+                try {
+                    await this.entityRepo.release(claimed.id, entityClaimToken);
+                }
+                catch (releaseErr) {
+                    this.logger.error(`[engine] release() failed for entity ${claimed.id} after state mismatch:`, releaseErr);
+                }
+                continue;
+            }
+            let claimedInvocation;
+            try {
+                claimedInvocation = await this.invocationRepo.claim(pending.id, worker_id ?? `agent:${role}`);
             }
-            // No pre-existing unclaimed invocations — claim entity directly and create invocation
+            catch (err) {
+                this.logger.error(`[engine] invocationRepo.claim() failed for invocation ${pending.id}:`, err);
+                try {
+                    await this.entityRepo.release(claimed.id, entityClaimToken);
+                }
+                catch (releaseErr) {
+                    this.logger.error(`[engine] release() failed for entity ${claimed.id}:`, releaseErr);
+                }
+                continue;
+            }
+            if (!claimedInvocation) {
+                try {
+                    await this.entityRepo.release(claimed.id, entityClaimToken);
+                }
+                catch (err) {
+                    this.logger.error(`[engine] release() failed for entity ${claimed.id}:`, err);
+                }
+                continue;
+            }
+            if (worker_id) {
+                const windowMs = flow.affinityWindowMs ?? 300000;
+                try {
+                    await this.entityRepo.setAffinity(claimed.id, worker_id, role, new Date(Date.now() + windowMs));
+                }
+                catch (err) {
+                    this.logger.warn(`[engine] setAffinity failed for entity ${claimed.id} worker ${worker_id} — continuing:`, err);
+                }
+            }
+            const state = flow.states.find((s) => s.name === pending.stage);
+            const build = state
+                ? await this.buildPromptForEntity(state, claimed, flow)
+                : { prompt: pending.prompt, context: null };
+            await this.eventEmitter.emit({
+                type: "entity.claimed",
+                entityId: claimed.id,
+                flowId: flow.id,
+                agentId: worker_id ?? `agent:${role}`,
+                emittedAt: new Date(),
+            });
+            return {
+                entityId: claimed.id,
+                invocationId: claimedInvocation.id,
+                flowName: flow.name,
+                stage: pending.stage,
+                prompt: build.prompt,
+                context: build.context,
+            };
+        }
+        // 8. Fallback: no unclaimed invocations — claim entity directly and create invocation
+        for (const flow of flows) {
             const claimableStates = flow.states.filter((s) => !!s.promptTemplate);
             for (const state of claimableStates) {
-                const claimed = await this.entityRepo.claim(flow.id, state.name, `agent:${role}`);
+                const claimed = await this.entityRepo.claim(flow.id, state.name, worker_id ?? `agent:${role}`);
                 if (!claimed)
                     continue;
-                await this.setAffinityIfNeeded(claimed.id, flow, role, worker_id);
-                const build = await this.buildPrompt(state, claimed, flow);
+                const canCreate = await this.checkConcurrency(flow, claimed);
+                if (!canCreate) {
+                    await this.entityRepo.release(claimed.id, worker_id ?? `agent:${role}`);
+                    continue;
+                }
+                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);
-                return this.emitAndReturn(claimed, invocation.id, build, flow, role);
+                const entityClaimToken = worker_id ?? `agent:${role}`;
+                let claimedInvocation;
+                try {
+                    claimedInvocation = await this.invocationRepo.claim(invocation.id, entityClaimToken);
+                }
+                catch (err) {
+                    this.logger.error(`[engine] invocationRepo.claim() failed for invocation ${invocation.id}:`, err);
+                    try {
+                        await this.invocationRepo.fail(invocation.id, err instanceof Error ? err.message : String(err));
+                    }
+                    catch (failErr) {
+                        this.logger.error(`[engine] invocationRepo.fail() cleanup failed for invocation ${invocation.id}:`, failErr);
+                    }
+                    try {
+                        await this.entityRepo.release(claimed.id, entityClaimToken);
+                    }
+                    catch (releaseErr) {
+                        this.logger.error(`[engine] release() failed for entity ${claimed.id}:`, releaseErr);
+                    }
+                    continue;
+                }
+                if (!claimedInvocation) {
+                    // Another worker won the race and claimed this invocation — it is healthy.
+                    // Do NOT call fail(); just release our entity lock and move on.
+                    try {
+                        await this.entityRepo.release(claimed.id, entityClaimToken);
+                    }
+                    catch (err) {
+                        this.logger.error(`[engine] release() failed for entity ${claimed.id}:`, err);
+                    }
+                    continue;
+                }
+                if (worker_id) {
+                    const windowMs = flow.affinityWindowMs ?? 300000;
+                    try {
+                        await this.entityRepo.setAffinity(claimed.id, worker_id, role, new Date(Date.now() + windowMs));
+                    }
+                    catch (err) {
+                        this.logger.warn(`[engine] setAffinity failed for entity ${claimed.id} worker ${worker_id} — continuing:`, err);
+                    }
+                }
+                await this.eventEmitter.emit({
+                    type: "entity.claimed",
+                    entityId: claimed.id,
+                    flowId: flow.id,
+                    agentId: worker_id ?? `agent:${role}`,
+                    emittedAt: new Date(),
+                });
+                return {
+                    entityId: claimed.id,
+                    invocationId: claimedInvocation.id,
+                    flowName: flow.name,
+                    stage: state.name,
+                    prompt: build.prompt,
+                    context: build.context,
+                };
             }
         }
-        return null;
-    }
-    /**
-     * Try to claim an existing unclaimed invocation for an already-claimed entity.
-     * Handles the race condition where another worker claims the invocation first
-     * (releases the entity claim and returns null so the caller can try the next candidate).
-     */
-    async tryClaimInvocation(pending, claimed, flow, role, worker_id) {
-        const claimedInvocation = await this.invocationRepo.claim(pending.id, `agent:${role}`);
-        if (!claimedInvocation) {
-            try {
-                await this.entityRepo.release(claimed.id, `agent:${role}`);
-            }
-            catch (err) {
-                this.logger.error(`release() failed for entity ${claimed.id}:`, err);
+        // 9. No work claimed — distinguish "all entities busy" (short retry) from "empty backlog" (long retry)
+        for (const flow of flows) {
+            const claimableStateNames = flow.states.filter((s) => !!s.promptTemplate).map((s) => s.name);
+            if (claimableStateNames.length > 0) {
+                const hasAny = await this.entityRepo.hasAnyInFlowAndState(flow.id, claimableStateNames);
+                if (hasAny)
+                    return "all_claimed";
             }
-            return null;
-        }
-        await this.setAffinityIfNeeded(claimed.id, flow, role, worker_id);
-        const state = flow.states.find((s) => s.name === pending.stage);
-        const build = state ? await this.buildPrompt(state, claimed, flow) : { prompt: pending.prompt, context: null };
-        return this.emitAndReturn(claimed, claimedInvocation.id, build, flow, role);
-    }
-    async setAffinityIfNeeded(entityId, flow, role, worker_id) {
-        if (!worker_id)
-            return;
-        const affinityWindow = flow.affinityWindowMs ?? 300000;
-        try {
-            await this.entityRepo.setAffinity(entityId, worker_id, role, new Date(Date.now() + affinityWindow));
-        }
-        catch (err) {
-            this.logger.warn(`setAffinity failed for entity ${entityId} worker ${worker_id} — continuing:`, err);
         }
+        return null;
     }
-    async buildPrompt(state, entity, flow) {
+    async buildPromptForEntity(state, entity, flow) {
         const [invocations, gateResults] = await Promise.all([
             this.invocationRepo.findByEntity(entity.id),
             this.gateRepo.resultsFor(entity.id),
@@ -385,21 +535,6 @@ export class Engine {
         const enriched = { ...entity, invocations, gateResults };
         return buildInvocation(state, enriched, this.adapters, flow, this.logger);
     }
-    async emitAndReturn(entity, invocationId, build, flow, role) {
-        await this.eventEmitter.emit({
-            type: "entity.claimed",
-            entityId: entity.id,
-            flowId: flow.id,
-            agentId: `agent:${role}`,
-            emittedAt: new Date(),
-        });
-        return {
-            entityId: entity.id,
-            invocationId,
-            prompt: build.prompt,
-            context: build.context,
-        };
-    }
     async getStatus() {
         const allFlows = await this.flowRepo.listAll();
         const statusData = {};

package/dist/src/engine/flow-spawner.js

@@ -1,3 +1,4 @@
+import { NotFoundError } from "../errors.js";
 import { consoleLogger } from "../logger.js";
 /**
  * If the transition has a spawnFlow, look up that flow and create a new entity in it.
@@ -9,7 +10,7 @@ export async function executeSpawn(transition, parentEntity, flowRepo, entityRep
         return null;
     const flow = await flowRepo.getByName(transition.spawnFlow);
     if (!flow)
-        throw new Error(`Spawn flow "${transition.spawnFlow}" not found`);
+        throw new NotFoundError(`Spawn flow "${transition.spawnFlow}" not found`);
     const childEntity = await entityRepo.create(flow.id, flow.initialState, parentEntity.refs ?? undefined);
     try {
         await entityRepo.appendSpawnedChild(parentEntity.id, {

package/dist/src/engine/gate-command-validator.d.ts

@@ -2,5 +2,6 @@ export interface GateCommandValidation {
     valid: boolean;
     resolvedPath: string | null;
     error: string | null;
+    parts: string[] | null;
 }
 export declare function validateGateCommand(command: string): GateCommandValidation;

package/dist/src/engine/gate-command-validator.js

@@ -1,17 +1,33 @@
 import fs from "node:fs";
 import path from "node:path";
 import { fileURLToPath } from "node:url";
+import { splitShellWords } from "./shell-words.js";
 // Anchor project root and gates directory to module location, not process.cwd()
 const MODULE_DIR = path.dirname(fileURLToPath(import.meta.url));
 const PROJECT_ROOT = path.resolve(MODULE_DIR, "../..");
 const GATES_ROOT = path.resolve(PROJECT_ROOT, "gates");
 export function validateGateCommand(command) {
     if (!command || command.trim().length === 0) {
-        return { valid: false, resolvedPath: null, error: "Gate command is empty" };
+        return { valid: false, resolvedPath: null, error: "Gate command is empty", parts: null };
     }
-    const executable = command.split(/\s+/)[0];
+    let parts;
+    try {
+        parts = splitShellWords(command);
+    }
+    catch (err) {
+        return {
+            valid: false,
+            resolvedPath: null,
+            error: `Shell parse error: ${err instanceof Error ? err.message : String(err)}`,
+            parts: null,
+        };
+    }
+    if (parts.length === 0) {
+        return { valid: false, resolvedPath: null, error: "Gate command is empty", parts: null };
+    }
+    const executable = parts[0];
     if (path.isAbsolute(executable)) {
-        return { valid: false, resolvedPath: null, error: "Gate command must not use absolute paths" };
+        return { valid: false, resolvedPath: null, error: "Gate command must not use absolute paths", parts: null };
     }
     // Resolve relative to project root (command format is gates/<file> from project root)
     const resolved = path.resolve(PROJECT_ROOT, executable);
@@ -22,6 +38,7 @@ export function validateGateCommand(command) {
             valid: false,
             resolvedPath: null,
             error: `Gate command must start with 'gates/' and resolve inside the gates directory (resolved outside gates/)`,
+            parts: null,
         };
     }
     // Resolve symlinks to prevent symlink escape
@@ -32,7 +49,7 @@ export function validateGateCommand(command) {
     catch {
         // Path doesn't exist yet (gate script may be deployed separately) — treat lexical check as sufficient
         // but still reject if it would escape after symlink resolution
-        return { valid: true, resolvedPath: resolved, error: null };
+        return { valid: true, resolvedPath: resolved, error: null, parts };
     }
     const realRelative = path.relative(GATES_ROOT, realPath);
     if (realRelative.startsWith(`..${path.sep}`) || realRelative === ".." || path.isAbsolute(realRelative)) {
@@ -40,7 +57,8 @@ export function validateGateCommand(command) {
             valid: false,
             resolvedPath: null,
             error: `Gate command resolves via symlink to outside the gates directory`,
+            parts: null,
         };
     }
-    return { valid: true, resolvedPath: realPath, error: null };
+    return { valid: true, resolvedPath: realPath, error: null, parts };
 }

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

@@ -2,6 +2,7 @@ import { execFile } from "node:child_process";
 import { realpathSync } from "node:fs";
 import { resolve, sep } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
+import { GateError, NotFoundError, ValidationError } from "../errors.js";
 import { validateGateCommand } from "./gate-command-validator.js";
 import { checkSsrf } from "./ssrf-guard.js";
 // Anchor path-traversal checks to the project root. realpathSync resolves symlinks
@@ -50,8 +51,10 @@ export async function evaluateGate(gate, entity, gateRepo, flowGateTimeoutMs) {
             await gateRepo.record(entity.id, gate.id, false, msg);
             return { passed: false, timedOut: false, output: msg };
         }
-        const [, ...args] = renderedCommand.split(/\s+/);
-        const resolvedPath = validation.resolvedPath ?? renderedCommand.split(/\s+/)[0];
+        // validation.parts is guaranteed non-null when valid is true
+        const parts = validation.parts ?? [renderedCommand];
+        const [executable, ...args] = parts;
+        const resolvedPath = validation.resolvedPath ?? executable;
         const result = await runCommand(resolvedPath, args, effectiveTimeout);
         passed = result.exitCode === 0;
         output = result.output;
@@ -152,7 +155,7 @@ export async function evaluateGate(gate, entity, gateRepo, flowGateTimeoutMs) {
         }
     }
     else {
-        throw new Error(`Unknown gate type: ${gate.type}`);
+        throw new GateError(`Unknown gate type: ${gate.type}`);
     }
     await gateRepo.record(entity.id, gate.id, passed, output);
     return { passed, timedOut, output };
@@ -160,7 +163,7 @@ export async function evaluateGate(gate, entity, gateRepo, flowGateTimeoutMs) {
 async function runFunction(functionRef, entity, gate, effectiveTimeout) {
     const lastColon = functionRef.lastIndexOf(":");
     if (lastColon === -1) {
-        throw new Error(`Invalid functionRef "${functionRef}" — expected "path:exportName"`);
+        throw new ValidationError(`Invalid functionRef "${functionRef}" — expected "path:exportName"`);
     }
     const modulePath = functionRef.slice(0, lastColon);
     const exportName = functionRef.slice(lastColon + 1);
@@ -178,13 +181,13 @@ async function runFunction(functionRef, entity, gate, effectiveTimeout) {
         realPath = absPath;
     }
     if (!realPath.startsWith(GATES_DIR)) {
-        throw new Error("functionRef must resolve to a path inside the gates/ directory");
+        throw new ValidationError("functionRef must resolve to a path inside the gates/ directory");
     }
     const moduleUrl = pathToFileURL(realPath).href;
     const mod = await import(moduleUrl);
     const fn = mod[exportName];
     if (typeof fn !== "function") {
-        throw new Error(`Gate function "${exportName}" not found in ${modulePath}`);
+        throw new NotFoundError(`Gate function "${exportName}" not found in ${modulePath}`);
     }
     const timeout = effectiveTimeout;
     let timer;

package/dist/src/engine/handlebars.js

@@ -15,7 +15,17 @@ hbs.registerHelper("invocation_count", (entity, stage) => String(entity.invocati
 hbs.registerHelper("gate_passed", (entity, gateName) => (entity.gateResults?.some((g) => g.gateId === gateName && g.passed) ?? false) ? "true" : "");
 hbs.registerHelper("has_artifact", (entity, key) => entity.artifacts?.[key] !== undefined ? "true" : "");
 hbs.registerHelper("time_in_state", (entity) => String(Date.now() - new Date(entity.updatedAt).getTime()));
-const BUILTIN_HELPERS = new Set(["gt", "lt", "eq", "invocation_count", "gate_passed", "has_artifact", "time_in_state"]);
+hbs.registerHelper("total_invocations", (entity) => String(Array.isArray(entity.invocations) ? entity.invocations.length : 0));
+const BUILTIN_HELPERS = new Set([
+    "gt",
+    "lt",
+    "eq",
+    "invocation_count",
+    "gate_passed",
+    "has_artifact",
+    "time_in_state",
+    "total_invocations",
+]);
 /** Forbidden patterns in templates — OWASP A03 Injection prevention. */
 const UNSAFE_PATTERN = /\b(lookup|__proto__|constructor|__defineGetter__|__defineSetter__|__lookupGetter__|__lookupSetter__)\b|@root/;
 /** Validate a template string against the safe subset. Returns true if safe. */

package/dist/src/engine/shell-words.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Split a command string into words, respecting single quotes, double quotes,
+ * and backslash escapes. Follows POSIX shell quoting rules (simplified).
+ *
+ * - Single quotes: preserve everything literally (no escape sequences)
+ * - Double quotes: preserve content, but backslash escapes \\ and \"
+ * - Backslash outside quotes: escapes the next character
+ */
+export declare function splitShellWords(cmd: string): string[];

package/dist/src/engine/shell-words.js

@@ -0,0 +1,74 @@
+/**
+ * Split a command string into words, respecting single quotes, double quotes,
+ * and backslash escapes. Follows POSIX shell quoting rules (simplified).
+ *
+ * - Single quotes: preserve everything literally (no escape sequences)
+ * - Double quotes: preserve content, but backslash escapes \\ and \"
+ * - Backslash outside quotes: escapes the next character
+ */
+export function splitShellWords(cmd) {
+    const words = [];
+    let current = "";
+    let i = 0;
+    let inWord = false;
+    while (i < cmd.length) {
+        const ch = cmd[i];
+        if (ch === "'") {
+            inWord = true;
+            i++;
+            const start = i;
+            while (i < cmd.length && cmd[i] !== "'")
+                i++;
+            if (i >= cmd.length)
+                throw new Error("Unterminated single quote");
+            current += cmd.slice(start, i);
+            i++; // skip closing quote
+        }
+        else if (ch === '"') {
+            inWord = true;
+            i++;
+            while (i < cmd.length && cmd[i] !== '"') {
+                if (cmd[i] === "\\" && i + 1 < cmd.length) {
+                    const next = cmd[i + 1];
+                    if (next === '"' || next === "\\") {
+                        current += next;
+                        i += 2;
+                    }
+                    else {
+                        current += cmd[i];
+                        i++;
+                    }
+                }
+                else {
+                    current += cmd[i];
+                    i++;
+                }
+            }
+            if (i >= cmd.length)
+                throw new Error("Unterminated double quote");
+            i++; // skip closing quote
+        }
+        else if (ch === "\\" && i + 1 < cmd.length) {
+            inWord = true;
+            current += cmd[i + 1];
+            i += 2;
+        }
+        else if (ch === " " || ch === "\t") {
+            if (inWord) {
+                words.push(current);
+                current = "";
+                inWord = false;
+            }
+            i++;
+        }
+        else {
+            inWord = true;
+            current += ch;
+            i++;
+        }
+    }
+    if (inWord) {
+        words.push(current);
+    }
+    return words;
+}

package/dist/src/errors.d.ts

@@ -0,0 +1,13 @@
+export declare class DefconError extends Error {
+    constructor(msg: string);
+}
+export declare class NotFoundError extends DefconError {
+}
+export declare class ConflictError extends DefconError {
+}
+export declare class ValidationError extends DefconError {
+}
+export declare class GateError extends DefconError {
+}
+export declare class InternalError extends DefconError {
+}

package/dist/src/errors.js

@@ -0,0 +1,17 @@
+export class DefconError extends Error {
+    constructor(msg) {
+        super(msg);
+        this.name = new.target.name;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class NotFoundError extends DefconError {
+}
+export class ConflictError extends DefconError {
+}
+export class ValidationError extends DefconError {
+}
+export class GateError extends DefconError {
+}
+export class InternalError extends DefconError {
+}

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

@@ -1,3 +1,4 @@
+import { NotFoundError } from "../errors.js";
 import { consoleLogger } from "../logger.js";
 const DEFAULT_MODEL_TIER_MAP = {
     opus: "claude-opus-4-6",
@@ -29,7 +30,7 @@ export class ActiveRunner {
         if (flowName) {
             const flow = await this.flowRepo.getByName(flowName);
             if (!flow)
-                throw new Error(`Flow "${flowName}" not found`);
+                throw new NotFoundError(`Flow "${flowName}" not found`);
             flowId = flow.id;
         }
         while (true) {

package/dist/src/execution/cli.js

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
 import { createHash, timingSafeEqual } from "node:crypto";
-import { writeFileSync } from "node:fs";
+import { readdirSync, writeFileSync } from "node:fs";
 import { homedir } from "node:os";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
@@ -55,7 +55,22 @@ export function validateWorkerToken(opts) {
             "Set DEFCON_WORKER_TOKEN in your environment or use stdio transport for local-only access.");
     }
 }
-const MIGRATIONS_FOLDER = new URL("../../drizzle", import.meta.url).pathname;
+// Resolve drizzle migrations folder. Works for both tsx (src/) and compiled (dist/src/) contexts.
+const MIGRATIONS_FOLDER = (() => {
+    const candidates = ["../../drizzle", "../../../drizzle"].map((rel) => new URL(rel, import.meta.url).pathname);
+    const found = candidates.find((p) => {
+        try {
+            readdirSync(p);
+            return true;
+        }
+        catch {
+            return false;
+        }
+    });
+    if (!found)
+        throw new Error(`Cannot find drizzle migrations folder (tried: ${candidates.join(", ")})`);
+    return found;
+})();
 const REAPER_INTERVAL_DEFAULT = "30000"; // 30s
 const CLAIM_TTL_DEFAULT = "300000"; // 5min
 function openDb(dbPath) {

package/dist/src/execution/mcp-server.js

@@ -433,7 +433,7 @@ function errorResult(message) {
         isError: true,
     };
 }
-const RETRY_SHORT_MS = 30_000; // entities exist but all claimed
+const RETRY_SHORT_MS = 30_000; // work exists but all entities currently claimed
 const RETRY_LONG_MS = 300_000; // backlog empty
 function noWorkResult(retryAfterMs, role) {
     return jsonResult({
@@ -448,152 +448,41 @@ function constantTimeEqual(a, b) {
     return timingSafeEqual(hashA, hashB);
 }
 // ─── Tool Handlers ───
-const AFFINITY_WINDOW_MS = 5 * 60 * 1000; // 5 minutes
 async function handleFlowClaim(deps, args) {
     const v = validateInput(FlowClaimSchema, args);
     if (!v.ok)
         return v.result;
-    const log = deps.logger ?? consoleLogger;
     const { worker_id, role, flow: flowName } = v.data;
-    // 1. Find candidate flows filtered by discipline
-    let candidateFlows = [];
-    if (flowName) {
-        const flow = await deps.flows.getByName(flowName);
-        if (!flow)
-            return errorResult(`Flow not found: ${flowName}`);
-        // Discipline must match — null discipline flows are claimable by any role
-        if (flow.discipline !== null && flow.discipline !== role)
-            return noWorkResult(RETRY_LONG_MS, role);
-        candidateFlows = [flow];
-    }
-    else {
-        const allFlows = await deps.flows.list();
-        candidateFlows = allFlows.filter((f) => f.discipline === null || f.discipline === role);
+    if (!deps.engine) {
+        return errorResult("Engine not available — MCP server started without engine dependency");
     }
-    if (candidateFlows.length === 0)
-        return noWorkResult(RETRY_LONG_MS, role);
-    const allCandidates = [];
-    for (const flow of candidateFlows) {
-        const unclaimed = await deps.invocations.findUnclaimedByFlow(flow.id);
-        allCandidates.push(...unclaimed);
+    let result;
+    try {
+        result = await deps.engine.claimWork(role, flowName, worker_id);
     }
-    if (allCandidates.length === 0) {
-        // Determine if entities exist but are all claimed (short retry) vs empty backlog (long retry).
-        // Use hasAnyInFlowAndState (SELECT 1 LIMIT 1) to avoid loading full entity rows across all states.
-        let hasEntities = false;
-        for (const flow of candidateFlows) {
-            const stateNames = flow.states.filter((s) => s.promptTemplate !== null).map((s) => s.name);
-            if (await deps.entities.hasAnyInFlowAndState(flow.id, stateNames)) {
-                hasEntities = true;
-                break;
-            }
+    catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        const isNotFound = /not found|unknown flow/i.test(message);
+        if (isNotFound) {
+            return errorResult(message);
         }
-        return noWorkResult(hasEntities ? RETRY_SHORT_MS : RETRY_LONG_MS, role);
+        return jsonResult({ next_action: "check_back", retry_after_ms: RETRY_LONG_MS, message });
     }
-    // 3. Load entities for priority sorting
-    const entityMap = new Map();
-    const uniqueEntityIds = [...new Set(allCandidates.map((inv) => inv.entityId))];
-    await Promise.all(uniqueEntityIds.map(async (eid) => {
-        const entity = await deps.entities.get(eid);
-        if (entity)
-            entityMap.set(eid, entity);
-    }));
-    // 4. Check affinity for each entity
-    const flowByIdEarly = new Map(candidateFlows.map((f) => [f.id, f]));
-    const affinitySet = new Set();
-    const now = Date.now();
-    if (worker_id) {
-        await Promise.all(uniqueEntityIds.map(async (eid) => {
-            const entity = entityMap.get(eid);
-            const flow = entity ? flowByIdEarly.get(entity.flowId) : undefined;
-            const windowMs = flow?.affinityWindowMs ?? AFFINITY_WINDOW_MS;
-            const invocations = await deps.invocations.findByEntity(eid);
-            const lastCompleted = invocations
-                .filter((inv) => inv.completedAt !== null && inv.claimedBy === worker_id)
-                .sort((a, b) => (b.completedAt?.getTime() ?? 0) - (a.completedAt?.getTime() ?? 0));
-            if (lastCompleted.length > 0) {
-                const elapsed = now - (lastCompleted[0].completedAt?.getTime() ?? 0);
-                if (elapsed < windowMs) {
-                    affinitySet.add(eid);
-                }
-            }
-        }));
+    if (result === "all_claimed") {
+        return noWorkResult(RETRY_SHORT_MS, role);
     }
-    // 5. Sort candidates by priority algorithm
-    allCandidates.sort((a, b) => {
-        const entityA = entityMap.get(a.entityId);
-        const entityB = entityMap.get(b.entityId);
-        // Tier 1: Affinity (has affinity sorts first)
-        const affinityA = affinitySet.has(a.entityId) ? 1 : 0;
-        const affinityB = affinitySet.has(b.entityId) ? 1 : 0;
-        if (affinityA !== affinityB)
-            return affinityB - affinityA;
-        // Tier 2: Entity priority (higher priority sorts first)
-        const priA = entityA?.priority ?? 0;
-        const priB = entityB?.priority ?? 0;
-        if (priA !== priB)
-            return priB - priA;
-        // Tier 3: Time in state (longest waiting sorts first — earlier createdAt as stable proxy)
-        const timeA = entityA?.createdAt?.getTime() ?? now;
-        const timeB = entityB?.createdAt?.getTime() ?? now;
-        return timeA - timeB;
-    });
-    // 6. Build a flow lookup map
-    const flowById = new Map(candidateFlows.map((f) => [f.id, f]));
-    // 7. Try claiming in priority order (handle race conditions)
-    for (const invocation of allCandidates) {
-        let claimed;
-        try {
-            claimed = await deps.invocations.claim(invocation.id, worker_id ?? `agent:${role}`);
-        }
-        catch (err) {
-            log.error(`Failed to claim invocation ${invocation.id}:`, err);
-            continue;
-        }
-        if (claimed) {
-            const entity = entityMap.get(claimed.entityId);
-            if (entity) {
-                let claimedEntity;
-                try {
-                    claimedEntity = await deps.entities.claimById(entity.id, worker_id ?? `agent:${role}`);
-                }
-                catch (err) {
-                    log.error(`Failed to claimById for entity ${entity.id}:`, err);
-                    // Release the invocation claim so it can be reclaimed rather than orphaned.
-                    await deps.invocations.releaseClaim(claimed.id);
-                    continue;
-                }
-                if (!claimedEntity) {
-                    // Race condition: another worker claimed this entity first.
-                    // Release the invocation claim so it can be picked up by another worker.
-                    await deps.invocations.releaseClaim(claimed.id);
-                    continue;
-                }
-            }
-            const flow = entity ? flowById.get(entity.flowId) : undefined;
-            // Record affinity for the claiming worker
-            if (worker_id && entity && flow) {
-                const windowMs = flow.affinityWindowMs ?? 300000;
-                try {
-                    await deps.entities.setAffinity(claimed.entityId, worker_id, role, new Date(Date.now() + windowMs));
-                }
-                catch (err) {
-                    // Affinity is non-critical — log and continue with the successful claim.
-                    log.error(`Failed to set affinity for entity ${claimed.entityId} worker ${worker_id}:`, err);
-                }
-            }
-            return jsonResult({
-                worker_id: worker_id,
-                entity_id: claimed.entityId,
-                invocation_id: claimed.id,
-                flow: flow?.name ?? null,
-                stage: claimed.stage,
-                prompt: claimed.prompt,
-                context: claimed.context,
-            });
-        }
+    if (!result) {
+        return noWorkResult(RETRY_LONG_MS, role);
     }
-    return noWorkResult(RETRY_SHORT_MS, role);
+    return jsonResult({
+        worker_id: worker_id,
+        entity_id: result.entityId,
+        invocation_id: result.invocationId,
+        flow: result.flowName,
+        stage: result.stage,
+        prompt: result.prompt,
+        context: result.context,
+    });
 }
 async function handleFlowGetPrompt(deps, args) {
     const v = validateInput(FlowGetPromptSchema, args);

package/dist/src/main.d.ts

@@ -12,3 +12,4 @@ export declare function bootstrap(dbPath?: string): {
 };
 export * from "./api/wire-types.js";
 export * from "./engine/index.js";
+export { ConflictError, DefconError, GateError, InternalError, NotFoundError, ValidationError } from "./errors.js";

package/dist/src/main.js

@@ -26,3 +26,4 @@ export function bootstrap(dbPath = DB_PATH) {
 }
 export * from "./api/wire-types.js";
 export * from "./engine/index.js";
+export { ConflictError, DefconError, GateError, InternalError, NotFoundError, ValidationError } from "./errors.js";

package/dist/src/repositories/drizzle/entity.repo.js

@@ -1,4 +1,5 @@
 import { and, eq, inArray, isNull, lt, not } from "drizzle-orm";
+import { NotFoundError } from "../../errors.js";
 import { entities } from "./schema.js";
 export class DrizzleEntityRepository {
     db;
@@ -70,7 +71,7 @@ export class DrizzleEntityRepository {
         return this.db.transaction((tx) => {
             const rows = tx.select().from(entities).where(eq(entities.id, id)).limit(1).all();
             if (rows.length === 0)
-                throw new Error(`Entity not found: ${id}`);
+                throw new NotFoundError(`Entity not found: ${id}`);
             const row = rows[0];
             const now = Date.now();
             const mergedArtifacts = artifacts
@@ -91,7 +92,7 @@ export class DrizzleEntityRepository {
     async updateArtifacts(id, artifacts) {
         const rows = await this.db.select().from(entities).where(eq(entities.id, id)).limit(1);
         if (rows.length === 0)
-            throw new Error(`Entity not found: ${id}`);
+            throw new NotFoundError(`Entity not found: ${id}`);
         const existing = rows[0].artifacts ?? {};
         await this.db
             .update(entities)
@@ -145,7 +146,7 @@ export class DrizzleEntityRepository {
         this.db.transaction((tx) => {
             const rows = tx.select().from(entities).where(eq(entities.id, parentId)).limit(1).all();
             if (rows.length === 0)
-                throw new Error(`Entity ${parentId} not found`);
+                throw new NotFoundError(`Entity ${parentId} not found`);
             const row = rows[0];
             const artifacts = row.artifacts ?? {};
             const existing = (Array.isArray(artifacts.spawnedChildren) ? artifacts.spawnedChildren : []);

package/dist/src/repositories/drizzle/flow.repo.js

@@ -1,4 +1,5 @@
 import { and, eq } from "drizzle-orm";
+import { NotFoundError } from "../../errors.js";
 import { flowDefinitions, flowVersions, stateDefinitions, transitionRules } from "./schema.js";
 function toDate(v) {
     return v != null ? new Date(v) : null;
@@ -119,7 +120,7 @@ export class DrizzleFlowRepository {
         const now = Date.now();
         const current = this.db.select().from(flowDefinitions).where(eq(flowDefinitions.id, id)).all();
         if (current.length === 0)
-            throw new Error(`Flow not found: ${id}`);
+            throw new NotFoundError(`Flow not found: ${id}`);
         const updateValues = { updatedAt: now };
         if (changes.name !== undefined)
             updateValues.name = changes.name;
@@ -173,7 +174,7 @@ export class DrizzleFlowRepository {
     async updateState(stateId, changes) {
         const existing = this.db.select().from(stateDefinitions).where(eq(stateDefinitions.id, stateId)).all();
         if (existing.length === 0)
-            throw new Error(`State not found: ${stateId}`);
+            throw new NotFoundError(`State not found: ${stateId}`);
         const updateValues = {};
         if (changes.name !== undefined)
             updateValues.name = changes.name;
@@ -219,7 +220,7 @@ export class DrizzleFlowRepository {
     async updateTransition(transitionId, changes) {
         const existing = this.db.select().from(transitionRules).where(eq(transitionRules.id, transitionId)).all();
         if (existing.length === 0)
-            throw new Error(`Transition not found: ${transitionId}`);
+            throw new NotFoundError(`Transition not found: ${transitionId}`);
         const updateValues = {};
         if (changes.fromState !== undefined)
             updateValues.fromState = changes.fromState;
@@ -247,7 +248,7 @@ export class DrizzleFlowRepository {
     async snapshot(flowId) {
         const flow = await this.get(flowId);
         if (!flow)
-            throw new Error(`Flow not found: ${flowId}`);
+            throw new NotFoundError(`Flow not found: ${flowId}`);
         const now = Date.now();
         const id = crypto.randomUUID();
         const snapshotData = {
@@ -304,7 +305,7 @@ export class DrizzleFlowRepository {
             .where(and(eq(flowVersions.flowId, flowId), eq(flowVersions.version, version)))
             .all();
         if (versionRows.length === 0)
-            throw new Error(`Version ${version} not found for flow ${flowId}`);
+            throw new NotFoundError(`Version ${version} not found for flow ${flowId}`);
         const snap = versionRows[0].snapshot;
         this.db.transaction((tx) => {
             tx.delete(transitionRules).where(eq(transitionRules.flowId, flowId)).run();

package/dist/src/repositories/drizzle/gate.repo.js

@@ -1,5 +1,6 @@
 import { randomUUID } from "node:crypto";
 import { asc, eq, sql } from "drizzle-orm";
+import { InternalError } from "../../errors.js";
 import { gateDefinitions, gateResults } from "./schema.js";
 function toGate(row) {
     return {
@@ -45,7 +46,7 @@ export class DrizzleGateRepository {
         this.db.insert(gateDefinitions).values(values).run();
         const row = this.db.select().from(gateDefinitions).where(eq(gateDefinitions.id, id)).get();
         if (!row)
-            throw new Error(`Gate ${id} not found after insert`);
+            throw new InternalError(`Gate ${id} not found after insert`);
         return toGate(row);
     }
     async get(id) {
@@ -76,14 +77,14 @@ export class DrizzleGateRepository {
             .run();
         const row = this.db.select().from(gateResults).where(eq(gateResults.id, id)).get();
         if (!row)
-            throw new Error(`GateResult ${id} not found after insert`);
+            throw new InternalError(`GateResult ${id} not found after insert`);
         return toGateResult(row);
     }
     async update(id, changes) {
         this.db.update(gateDefinitions).set(changes).where(eq(gateDefinitions.id, id)).run();
         const row = this.db.select().from(gateDefinitions).where(eq(gateDefinitions.id, id)).get();
         if (!row)
-            throw new Error(`Gate ${id} not found after update`);
+            throw new InternalError(`Gate ${id} not found after update`);
         return toGate(row);
     }
     async resultsFor(entityId) {

package/dist/src/repositories/drizzle/invocation.repo.js

@@ -1,4 +1,5 @@
 import { and, asc, eq, isNotNull, isNull, sql } from "drizzle-orm";
+import { ConflictError, InternalError, NotFoundError } from "../../errors.js";
 import { entities, invocations } from "./schema.js";
 function toInvocation(row) {
     return {
@@ -41,7 +42,7 @@ export class DrizzleInvocationRepository {
             .run();
         const created = await this.get(id);
         if (!created)
-            throw new Error(`Invocation ${id} not found after insert`);
+            throw new InternalError(`Invocation ${id} not found after insert`);
         return created;
     }
     async get(id) {
@@ -68,16 +69,16 @@ export class DrizzleInvocationRepository {
         if (result.changes === 0) {
             const existing = this.db.select().from(invocations).where(eq(invocations.id, id)).all();
             if (existing.length === 0)
-                throw new Error(`Invocation ${id} not found`);
+                throw new NotFoundError(`Invocation ${id} not found`);
             if (existing[0].completedAt)
-                throw new Error(`Invocation ${id} already completed`);
+                throw new ConflictError(`Invocation ${id} already completed`);
             if (existing[0].failedAt)
-                throw new Error(`Invocation ${id} already failed`);
-            throw new Error(`Invocation ${id} concurrent modification detected`);
+                throw new ConflictError(`Invocation ${id} already failed`);
+            throw new ConflictError(`Invocation ${id} concurrent modification detected`);
         }
         const row = this.db.select().from(invocations).where(eq(invocations.id, id)).all();
         if (row.length === 0)
-            throw new Error(`Invocation ${id} not found after update`);
+            throw new InternalError(`Invocation ${id} not found after update`);
         return toInvocation(row[0]);
     }
     async fail(id, error) {
@@ -89,16 +90,16 @@ export class DrizzleInvocationRepository {
         if (result.changes === 0) {
             const existing = this.db.select().from(invocations).where(eq(invocations.id, id)).all();
             if (existing.length === 0)
-                throw new Error(`Invocation ${id} not found`);
+                throw new NotFoundError(`Invocation ${id} not found`);
             if (existing[0].completedAt)
-                throw new Error(`Invocation ${id} already completed`);
+                throw new ConflictError(`Invocation ${id} already completed`);
             if (existing[0].failedAt)
-                throw new Error(`Invocation ${id} already failed`);
-            throw new Error(`Invocation ${id} concurrent modification detected`);
+                throw new ConflictError(`Invocation ${id} already failed`);
+            throw new ConflictError(`Invocation ${id} concurrent modification detected`);
         }
         const row = this.db.select().from(invocations).where(eq(invocations.id, id)).all();
         if (row.length === 0)
-            throw new Error(`Invocation ${id} not found after update`);
+            throw new InternalError(`Invocation ${id} not found after update`);
         return toInvocation(row[0]);
     }
     async releaseClaim(id) {

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "@wopr-network/defcon",
-  "version": "0.2.2",
+  "version": "1.0.1",
   "type": "module",
+  "packageManager": "pnpm@9.15.4",
   "engines": {
     "node": ">=24.0.0"
   },
-  "packageManager": "pnpm@9.15.4",
   "main": "./dist/src/main.js",
   "bin": {
     "defcon": "./dist/src/execution/cli.js"
@@ -61,5 +61,15 @@
     "onlyBuiltDependencies": [
       "better-sqlite3"
     ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "release": {
+    "extends": "@wopr-network/semantic-release-config"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/wopr-network/defcon.git"
   }
 }