@wopr-network/defcon 1.7.0 → 1.9.0

package/dist/src/api/router.d.ts

@@ -6,7 +6,8 @@ export interface ParsedRequest {
 }
 export interface ApiResponse {
     status: number;
-    body: unknown;
+    body?: unknown;
+    html?: string;
 }
 type Handler = (req: ParsedRequest) => Promise<ApiResponse>;
 interface MatchResult {

package/dist/src/api/server.d.ts

@@ -2,6 +2,7 @@ import http from "node:http";
 import type { Engine } from "../engine/engine.js";
 import type { McpServerDeps } from "../execution/mcp-server.js";
 import type { Logger } from "../logger.js";
+import type { UiSseAdapter } from "../ui/sse.js";
 export interface HttpServerDeps {
     engine: Engine;
     mcpDeps: McpServerDeps;
@@ -9,5 +10,7 @@ export interface HttpServerDeps {
     workerToken?: string;
     corsOrigins?: string[];
     logger?: Logger;
+    enableUi?: boolean;
+    uiSseAdapter?: UiSseAdapter;
 }
 export declare function createHttpServer(deps: HttpServerDeps): http.Server;

package/dist/src/api/server.js

@@ -2,6 +2,7 @@ import { createHash, timingSafeEqual } from "node:crypto";
 import http from "node:http";
 import { callToolHandler } from "../execution/mcp-server.js";
 import { consoleLogger } from "../logger.js";
+import { UI_HTML } from "../ui/index.html.js";
 import { Router } from "./router.js";
 function extractBearerToken(header) {
     if (!header)
@@ -274,6 +275,52 @@ export function createHttpServer(deps) {
         const result = await callToolHandler(deps.mcpDeps, "admin.gate.rerun", { entity_id: req.params.id, gate_name: req.params.gateName }, { adminToken: deps.adminToken, callerToken });
         return mcpResultToApi(result);
     });
+    // --- UI routes (optional, enabled via enableUi) ---
+    if (deps.enableUi) {
+        router.add("GET", "/ui", async () => {
+            // No auth here: browsers navigating to /ui can't send Authorization headers.
+            // Auth is handled in the browser (token prompt) and enforced on API calls.
+            return { status: 200, html: "UI" };
+        });
+        router.add("GET", "/api/ui/entity/:id/events", async (req) => {
+            const authErr = requireAdminToken(deps, req);
+            if (authErr)
+                return authErr;
+            const limitStr = req.query.get("limit");
+            const limit = limitStr !== null ? parseInt(limitStr, 10) : 100;
+            if (limitStr !== null && (!Number.isFinite(limit) || limit <= 0)) {
+                return { status: 400, body: { error: "invalid limit parameter" } };
+            }
+            const evts = await deps.mcpDeps.eventRepo.findByEntity(req.params.id, limit);
+            return { status: 200, body: evts };
+        });
+        router.add("GET", "/api/ui/entity/:id/invocations", async (req) => {
+            const authErr = requireAdminToken(deps, req);
+            if (authErr)
+                return authErr;
+            const invocations = await deps.mcpDeps.invocations.findByEntity(req.params.id);
+            return { status: 200, body: invocations };
+        });
+        router.add("GET", "/api/ui/entity/:id/gates", async (req) => {
+            const authErr = requireAdminToken(deps, req);
+            if (authErr)
+                return authErr;
+            const results = await deps.mcpDeps.gates.resultsFor(req.params.id);
+            return { status: 200, body: results };
+        });
+        router.add("GET", "/api/ui/events/recent", async (req) => {
+            const authErr = requireAdminToken(deps, req);
+            if (authErr)
+                return authErr;
+            const limitStr = req.query.get("limit");
+            const limit = limitStr !== null ? parseInt(limitStr, 10) : 200;
+            if (limitStr !== null && (!Number.isFinite(limit) || limit <= 0)) {
+                return { status: 400, body: { error: "invalid limit parameter" } };
+            }
+            const evts = await deps.mcpDeps.eventRepo.findRecent(limit);
+            return { status: 200, body: evts };
+        });
+    }
     // --- HTTP server ---
     const server = http.createServer(async (req, res) => {
         // CORS
@@ -297,6 +344,35 @@ export function createHttpServer(deps) {
             return;
         }
         const url = new URL(req.url ?? "/", `http://localhost`);
+        // SSE endpoint — handled before router (holds connection open)
+        if (deps.enableUi && url.pathname === "/api/ui/events" && req.method === "GET") {
+            const queryToken = url.searchParams.get("token") ?? undefined;
+            const headerToken = extractBearerToken(req.headers.authorization);
+            const callerToken = headerToken ?? queryToken;
+            const configuredToken = deps.adminToken?.trim() || undefined;
+            if (configuredToken) {
+                if (!callerToken) {
+                    res.writeHead(401, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Unauthorized" }));
+                    return;
+                }
+                const hashA = createHash("sha256").update(configuredToken).digest();
+                const hashB = createHash("sha256").update(callerToken).digest();
+                if (!timingSafeEqual(hashA, hashB)) {
+                    res.writeHead(401, { "Content-Type": "application/json" });
+                    res.end(JSON.stringify({ error: "Unauthorized" }));
+                    return;
+                }
+            }
+            res.writeHead(200, {
+                "Content-Type": "text/event-stream",
+                "Cache-Control": "no-cache",
+                Connection: "keep-alive",
+            });
+            res.write(":\n\n"); // SSE comment to establish connection
+            deps.uiSseAdapter?.addClient(res);
+            return;
+        }
         const match = router.match(req.method ?? "GET", url.pathname);
         if (!match) {
             res.writeHead(404, { "Content-Type": "application/json" });
@@ -337,6 +413,10 @@ export function createHttpServer(deps) {
             if (apiRes.status === 204) {
                 res.writeHead(204).end();
             }
+            else if (apiRes.html !== undefined) {
+                res.writeHead(200, { "Content-Type": "text/html; charset=utf-8" });
+                res.end(UI_HTML);
+            }
             else {
                 res.writeHead(apiRes.status, { "Content-Type": "application/json" });
                 res.end(JSON.stringify(apiRes.body));

package/dist/src/engine/engine.js

@@ -72,6 +72,9 @@ export class Engine {
         const entity = await this.entityRepo.get(entityId);
         if (!entity)
             throw new NotFoundError(`Entity "${entityId}" not found`);
+        if (entity.state === "cancelled") {
+            throw new ValidationError(`Entity "${entityId}" is cancelled and cannot be transitioned`);
+        }
         // 2. Load flow at entity's pinned version
         const flow = await this.flowRepo.getAtVersion(entity.flowId, entity.flowVersion);
         if (!flow)
@@ -466,6 +469,8 @@ export class Engine {
             const entity = entityMap.get(pending.entityId);
             if (!entity)
                 continue;
+            if (entity.state === "cancelled")
+                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)
@@ -545,6 +550,10 @@ export class Engine {
                 const claimed = await this.entityRepo.claim(flow.id, state.name, worker_id ?? `agent:${role}`);
                 if (!claimed)
                     continue;
+                if (claimed.state === "cancelled") {
+                    await this.entityRepo.release(claimed.id, worker_id ?? `agent:${role}`);
+                    continue;
+                }
                 const claimedVersionedFlow = await this.flowRepo.getAtVersion(claimed.flowId, claimed.flowVersion);
                 const claimedEffectiveFlow = claimedVersionedFlow ?? flow;
                 const canCreate = await this.checkConcurrency(claimedEffectiveFlow, claimed);

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

@@ -24,6 +24,14 @@ export type EngineEvent = {
     entityId: string;
     flowId: string;
     emittedAt: Date;
+} | {
+    type: "entity.cancelled";
+    entityId: string;
+    flowId: string;
+    cancelledBy: string;
+    reason: string | null;
+    cascade: boolean;
+    emittedAt: Date;
 } | {
     type: "invocation.created";
     entityId: string;

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

@@ -11,7 +11,7 @@ export async function executeSpawn(transition, parentEntity, flowRepo, entityRep
     const flow = await flowRepo.getByName(transition.spawnFlow);
     if (!flow)
         throw new NotFoundError(`Spawn flow "${transition.spawnFlow}" not found`);
-    const childEntity = await entityRepo.create(flow.id, flow.initialState, parentEntity.refs ?? undefined);
+    const childEntity = await entityRepo.create(flow.id, flow.initialState, parentEntity.refs ?? undefined, undefined, parentEntity.id);
     try {
         await entityRepo.appendSpawnedChild(parentEntity.id, {
             childId: childEntity.id,

package/dist/src/execution/admin-schemas.d.ts

@@ -119,6 +119,8 @@ export declare const AdminFlowPauseSchema: z.ZodObject<{
 }, z.core.$strip>;
 export declare const AdminEntityCancelSchema: z.ZodObject<{
     entity_id: z.ZodString;
+    cascade: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+    reason: z.ZodOptional<z.ZodString>;
 }, z.core.$strip>;
 export declare const AdminEntityResetSchema: z.ZodObject<{
     entity_id: z.ZodString;

package/dist/src/execution/admin-schemas.js

@@ -128,6 +128,8 @@ export const AdminFlowPauseSchema = z.object({
 });
 export const AdminEntityCancelSchema = z.object({
     entity_id: z.string().min(1),
+    cascade: z.boolean().optional().default(false),
+    reason: z.string().optional(),
 });
 export const AdminEntityResetSchema = z.object({
     entity_id: z.string().min(1),

package/dist/src/execution/cli.js

@@ -23,6 +23,7 @@ import { DrizzleInvocationRepository } from "../repositories/drizzle/invocation.
 import * as schema from "../repositories/drizzle/schema.js";
 import { entities, entityHistory, flowDefinitions, flowVersions, gateDefinitions, gateResults, invocations, stateDefinitions, transitionRules, } from "../repositories/drizzle/schema.js";
 import { DrizzleTransitionLogRepository } from "../repositories/drizzle/transition-log.repo.js";
+import { UiSseAdapter } from "../ui/sse.js";
 import { WebSocketBroadcaster } from "../ws/broadcast.js";
 import { createMcpServer, startStdioServer } from "./mcp-server.js";
 import { provisionWorktree } from "./provision-worktree.js";
@@ -153,6 +154,7 @@ program
     .option("--mcp-only", "Start MCP stdio only (no HTTP REST server)")
     .option("--http-port <number>", "Port for HTTP REST API", "3000")
     .option("--http-host <address>", "Host for HTTP REST API", "127.0.0.1")
+    .option("--ui", "Enable built-in web UI at /ui")
     .action(async (opts) => {
     const { db, sqlite } = openDb(opts.db);
     const entityRepo = new DrizzleEntityRepository(db);
@@ -184,6 +186,7 @@ program
         transitions: transitionLogRepo,
         eventRepo: new DrizzleEventRepository(db),
         engine,
+        withTransaction: (fn) => withTransaction(sqlite, fn),
     };
     const reaperInterval = parseInt(opts.reaperInterval, 10);
     if (Number.isNaN(reaperInterval) || reaperInterval < 1000) {
@@ -208,6 +211,9 @@ program
     const workerToken = process.env.DEFCON_WORKER_TOKEN || undefined;
     const startHttp = !opts.mcpOnly;
     const startMcp = !opts.httpOnly;
+    if (opts.mcpOnly && opts.ui) {
+        console.warn("Warning: --ui is ignored when --mcp-only is set (HTTP server is disabled)");
+    }
     try {
         validateAdminToken({ adminToken, startHttp, transport: opts.transport });
     }
@@ -240,13 +246,19 @@ program
             sqlite.close();
             process.exit(1);
         }
+        const uiSseAdapter = opts.ui ? new UiSseAdapter() : undefined;
         restHttpServer = createHttpServer({
             engine,
             mcpDeps: deps,
             adminToken,
             workerToken,
             corsOrigins: restCorsResult.origins ?? undefined,
+            enableUi: !!opts.ui,
+            uiSseAdapter,
         });
+        if (uiSseAdapter) {
+            eventEmitter.register(uiSseAdapter);
+        }
         if (adminToken) {
             const wsBroadcaster = new WebSocketBroadcaster({
                 server: restHttpServer,

package/dist/src/execution/mcp-server.d.ts

@@ -11,6 +11,7 @@ export interface McpServerDeps {
     eventRepo: IEventRepository;
     engine?: Engine;
     logger?: Logger;
+    withTransaction?: <T>(fn: () => T | Promise<T>) => Promise<T>;
 }
 export interface McpServerOpts {
     /** DEFCON_ADMIN_TOKEN — if set, admin.* tools require this token */

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

@@ -350,8 +350,16 @@ const TOOL_DEFINITIONS = [
     },
     {
         name: "admin.entity.cancel",
-        description: "Cancel an entity — fails active invocation, moves to 'cancelled' terminal state.",
-        inputSchema: { type: "object", properties: { entity_id: { type: "string" } }, required: ["entity_id"] },
+        description: "Cancel an entity — fails active invocation, moves to 'cancelled' terminal state. Use cascade to cancel all descendant entities.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                entity_id: { type: "string" },
+                cascade: { type: "boolean", description: "Recursively cancel all child entities" },
+                reason: { type: "string", description: "Cancellation reason" },
+            },
+            required: ["entity_id"],
+        },
     },
     {
         name: "admin.entity.reset",
@@ -755,31 +763,67 @@ async function handleAdminEntityCancel(deps, args) {
     const v = validateInput(AdminEntityCancelSchema, args);
     if (!v.ok)
         return v.result;
-    const entity = await deps.entities.get(v.data.entity_id);
+    const { entity_id, cascade, reason } = v.data;
+    const entity = await deps.entities.get(entity_id);
     if (!entity)
-        return errorResult(`Entity not found: ${v.data.entity_id}`);
-    const flow = await deps.flows.get(entity.flowId);
-    if (!flow)
-        return errorResult(`Flow not found for entity: ${v.data.entity_id}`);
-    const cancelledState = flow.states.find((s) => s.name === "cancelled");
-    if (!cancelledState)
-        return errorResult(`State 'cancelled' not found in flow '${flow.name}'`);
-    const invocations = await deps.invocations.findByEntity(v.data.entity_id);
-    for (const inv of invocations) {
-        if (inv.completedAt === null && inv.failedAt === null) {
-            await deps.invocations.fail(inv.id, "Cancelled by admin");
+        return errorResult(`Entity not found: ${entity_id}`);
+    if (entity.state === "cancelled" && !cascade)
+        return errorResult(`Entity ${entity_id} is already cancelled`);
+    const cancelled = [];
+    const MAX_CANCEL_DEPTH = 100;
+    async function cancelOne(eid, depth, visited) {
+        if (visited.has(eid))
+            return;
+        visited.add(eid);
+        if (depth > MAX_CANCEL_DEPTH) {
+            throw new Error(`cancelOne exceeded maximum recursion depth of ${MAX_CANCEL_DEPTH} — possible cycle or pathologically deep entity tree`);
+        }
+        const e = await deps.entities.get(eid);
+        const alreadyCancelled = !e || e.state === "cancelled";
+        if (!alreadyCancelled) {
+            const invocations = await deps.invocations.findByEntity(eid);
+            for (const inv of invocations) {
+                if (inv.completedAt === null && inv.failedAt === null) {
+                    await deps.invocations.fail(inv.id, reason ?? "Cancelled by admin");
+                }
+            }
+            await deps.entities.cancelEntity(eid);
+            await deps.transitions.record({
+                entityId: eid,
+                fromState: e.state,
+                toState: "cancelled",
+                trigger: "admin.cancel",
+                invocationId: null,
+                timestamp: new Date(),
+            });
+            if (deps.engine) {
+                await deps.engine.emit({
+                    type: "entity.cancelled",
+                    entityId: eid,
+                    flowId: e.flowId,
+                    cancelledBy: "admin",
+                    reason: reason ?? null,
+                    cascade: cascade ?? false,
+                    emittedAt: new Date(),
+                });
+            }
+            cancelled.push(eid);
+        }
+        if (cascade) {
+            const children = await deps.entities.findByParentId(eid);
+            for (const child of children) {
+                await cancelOne(child.id, depth + 1, visited);
+            }
         }
     }
-    await deps.entities.cancelEntity(v.data.entity_id);
-    await deps.transitions.record({
-        entityId: v.data.entity_id,
-        fromState: entity.state,
-        toState: "cancelled",
-        trigger: "admin.cancel",
-        invocationId: null,
-        timestamp: new Date(),
-    });
-    return jsonResult({ cancelled: true, entity_id: v.data.entity_id });
+    const run = () => cancelOne(entity_id, 0, new Set());
+    if (deps.withTransaction) {
+        await deps.withTransaction(run);
+    }
+    else {
+        await run();
+    }
+    return jsonResult({ cancelled: true, entity_id, cancelled_count: cancelled.length, cancelled_ids: cancelled });
 }
 async function handleAdminEntityReset(deps, args) {
     const v = validateInput(AdminEntityResetSchema, args);

package/dist/src/repositories/drizzle/entity.repo.d.ts

@@ -6,7 +6,7 @@ export declare class DrizzleEntityRepository implements IEntityRepository {
     private db;
     constructor(db: Db);
     private toEntity;
-    create(flowId: string, initialState: string, refs?: Refs, flowVersion?: number): Promise<Entity>;
+    create(flowId: string, initialState: string, refs?: Refs, flowVersion?: number, parentEntityId?: string): Promise<Entity>;
     get(id: string): Promise<Entity | null>;
     findByFlowAndState(flowId: string, state: string, limit?: number): Promise<Entity[]>;
     hasAnyInFlowAndState(flowId: string, stateNames: string[]): Promise<boolean>;
@@ -23,6 +23,7 @@ export declare class DrizzleEntityRepository implements IEntityRepository {
     reapExpired(ttlMs: number): Promise<string[]>;
     setAffinity(entityId: string, workerId: string, role: string, expiresAt: Date): Promise<void>;
     clearExpiredAffinity(): Promise<string[]>;
+    findByParentId(parentEntityId: string): Promise<Entity[]>;
     cancelEntity(entityId: string): Promise<void>;
     resetEntity(entityId: string, targetState: string): Promise<Entity>;
     updateFlowVersion(entityId: string, version: number): Promise<void>;

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

@@ -22,9 +22,10 @@ export class DrizzleEntityRepository {
             affinityWorkerId: row.affinityWorkerId ?? null,
             affinityRole: row.affinityRole ?? null,
             affinityExpiresAt: row.affinityExpiresAt ? new Date(row.affinityExpiresAt) : null,
+            parentEntityId: row.parentEntityId ?? null,
         };
     }
-    async create(flowId, initialState, refs, flowVersion) {
+    async create(flowId, initialState, refs, flowVersion, parentEntityId) {
         const now = Date.now();
         const id = crypto.randomUUID();
         const row = {
@@ -41,6 +42,7 @@ export class DrizzleEntityRepository {
             affinityWorkerId: null,
             affinityRole: null,
             affinityExpiresAt: null,
+            parentEntityId: parentEntityId ?? null,
         };
         await this.db.insert(entities).values(row);
         return this.toEntity(row);
@@ -188,6 +190,10 @@ export class DrizzleEntityRepository {
             .all();
         return rows.map((r) => r.id);
     }
+    async findByParentId(parentEntityId) {
+        const rows = await this.db.select().from(entities).where(eq(entities.parentEntityId, parentEntityId));
+        return rows.map((r) => this.toEntity(r));
+    }
     async cancelEntity(entityId) {
         await this.db
             .update(entities)

package/dist/src/repositories/drizzle/event.repo.d.ts

@@ -1,5 +1,5 @@
 import type { BetterSQLite3Database } from "drizzle-orm/better-sqlite3";
-import type { IEventRepository } from "../interfaces.js";
+import type { EventRow, IEventRepository } from "../interfaces.js";
 import type * as schema from "./schema.js";
 import { events } from "./schema.js";
 type Db = BetterSQLite3Database<typeof schema>;
@@ -8,5 +8,7 @@ export declare class DrizzleEventRepository implements IEventRepository {
     constructor(db: Db);
     emitDefinitionChanged(flowId: string | null, tool: string, payload: Record<string, unknown>): Promise<void>;
     findAll(): (typeof events.$inferSelect)[];
+    findByEntity(entityId: string, limit?: number): Promise<EventRow[]>;
+    findRecent(limit?: number): Promise<EventRow[]>;
 }
 export {};

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

@@ -1,4 +1,5 @@
 import { randomUUID } from "node:crypto";
+import { desc, eq } from "drizzle-orm";
 import { events } from "./schema.js";
 export class DrizzleEventRepository {
     db;
@@ -21,4 +22,16 @@ export class DrizzleEventRepository {
     findAll() {
         return this.db.select().from(events).all();
     }
+    findByEntity(entityId, limit = 100) {
+        return Promise.resolve(this.db
+            .select()
+            .from(events)
+            .where(eq(events.entityId, entityId))
+            .orderBy(desc(events.emittedAt))
+            .limit(limit)
+            .all());
+    }
+    findRecent(limit = 100) {
+        return Promise.resolve(this.db.select().from(events).orderBy(desc(events.emittedAt)).limit(limit).all());
+    }
 }

package/dist/src/repositories/drizzle/schema.d.ts

@@ -1326,6 +1326,25 @@ export declare const entities: import("drizzle-orm/sqlite-core").SQLiteTableWith
             identity: undefined;
             generated: undefined;
         }, {}, {}>;
+        parentEntityId: import("drizzle-orm/sqlite-core").SQLiteColumn<{
+            name: "parent_entity_id";
+            tableName: "entities";
+            dataType: "string";
+            columnType: "SQLiteText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {
+            length: number | undefined;
+        }>;
     };
     dialect: "sqlite";
 }>;

package/dist/src/repositories/drizzle/schema.js

@@ -95,10 +95,12 @@ export const entities = sqliteTable("entities", {
     affinityWorkerId: text("affinity_worker_id"),
     affinityRole: text("affinity_role"),
     affinityExpiresAt: integer("affinity_expires_at"),
+    parentEntityId: text("parent_entity_id"),
 }, (table) => ({
     flowStateIdx: index("entities_flow_state_idx").on(table.flowId, table.state),
     claimIdx: index("entities_claim_idx").on(table.flowId, table.state, table.claimedBy),
     affinityIdx: index("entities_affinity_idx").on(table.affinityWorkerId, table.affinityRole, table.affinityExpiresAt),
+    parentIdx: index("entities_parent_idx").on(table.parentEntityId),
 }));
 export const invocations = sqliteTable("invocations", {
     id: text("id").primaryKey(),
@@ -157,4 +159,6 @@ export const events = sqliteTable("events", {
     emittedAt: integer("emitted_at").notNull(),
 }, (table) => ({
     typeEmittedIdx: index("events_type_emitted_idx").on(table.type, table.emittedAt),
+    entityIdIdx: index("events_entity_id_idx").on(table.entityId),
+    emittedAtIdx: index("events_emitted_at_idx").on(table.emittedAt),
 }));

package/dist/src/repositories/interfaces.d.ts

@@ -35,6 +35,7 @@ export interface Entity {
     affinityWorkerId: string | null;
     affinityRole: string | null;
     affinityExpiresAt: Date | null;
+    parentEntityId: string | null;
 }
 /** A single agent invocation tied to an entity */
 export interface Invocation {
@@ -224,7 +225,7 @@ export interface CreateGateInput {
 /** Data-access contract for entity lifecycle operations. */
 export interface IEntityRepository {
     /** Create a new entity in the given flow's initial state. */
-    create(flowId: string, initialState: string, refs?: Refs, flowVersion?: number): Promise<Entity>;
+    create(flowId: string, initialState: string, refs?: Refs, flowVersion?: number, parentEntityId?: string): Promise<Entity>;
     /** Get an entity by ID, or null if not found. */
     get(id: string): Promise<Entity | null>;
     /** Find entities in a given flow and state, up to an optional limit. */
@@ -255,6 +256,8 @@ export interface IEntityRepository {
         childFlow: string;
         spawnedAt: string;
     }): Promise<void>;
+    /** Find all direct children of a parent entity. */
+    findByParentId(parentEntityId: string): Promise<Entity[]>;
     /** Move entity to 'cancelled' terminal state and clear claimedBy/claimedAt. */
     cancelEntity(entityId: string): Promise<void>;
     /** Move entity to targetState and clear claimedBy/claimedAt. Returns the updated entity. */
@@ -335,10 +338,23 @@ export interface ITransitionLogRepository {
     /** Get full transition history for an entity, ordered by timestamp. */
     historyFor(entityId: string): Promise<TransitionLog[]>;
 }
+/** A raw row from the events table. */
+export interface EventRow {
+    id: string;
+    type: string;
+    entityId: string | null;
+    flowId: string | null;
+    payload: Record<string, unknown> | null;
+    emittedAt: number;
+}
 /** Data-access contract for emitting definition-change events. */
 export interface IEventRepository {
     /** Emit a definition change event for a tool action. */
     emitDefinitionChanged(flowId: string | null, tool: string, payload: Record<string, unknown>): Promise<void>;
+    /** Get events for a specific entity, ordered by emittedAt descending. */
+    findByEntity(entityId: string, limit?: number): Promise<EventRow[]>;
+    /** Get the most recent events across all entities, ordered by emittedAt descending. */
+    findRecent(limit?: number): Promise<EventRow[]>;
 }
 /** Data-access contract for gate definitions and result recording. */
 export interface IGateRepository {

package/dist/src/ui/index.html.d.ts

@@ -0,0 +1 @@
+export declare const UI_HTML = "<!DOCTYPE html>\n<html lang=\"en\">\n<head>\n<meta charset=\"UTF-8\">\n<meta name=\"viewport\" content=\"width=device-width, initial-scale=1.0\">\n<title>DEFCON Dashboard</title>\n<style>\n*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }\nbody { background: #0d1117; color: #c9d1d9; font-family: 'Courier New', monospace; font-size: 14px; }\n#auth-overlay { position: fixed; inset: 0; background: #0d1117; display: flex; align-items: center; justify-content: center; z-index: 100; }\n#auth-box { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 32px; width: 360px; }\n#auth-box h2 { color: #58a6ff; margin-bottom: 16px; font-size: 18px; }\n#auth-box input { width: 100%; background: #0d1117; border: 1px solid #30363d; color: #c9d1d9; padding: 8px 12px; border-radius: 4px; font-family: inherit; font-size: 14px; margin-bottom: 12px; }\n#auth-box button { width: 100%; background: #238636; border: none; color: #fff; padding: 8px; border-radius: 4px; cursor: pointer; font-size: 14px; }\n#auth-box button:hover { background: #2ea043; }\nnav { background: #161b22; border-bottom: 1px solid #30363d; padding: 0 24px; display: flex; align-items: center; gap: 0; }\nnav h1 { color: #58a6ff; font-size: 16px; margin-right: 32px; padding: 14px 0; }\n.tab { background: none; border: none; color: #8b949e; padding: 14px 16px; cursor: pointer; font-family: inherit; font-size: 14px; border-bottom: 2px solid transparent; }\n.tab:hover { color: #c9d1d9; }\n.tab.active { color: #58a6ff; border-bottom-color: #58a6ff; }\n.tab-content { display: none; padding: 24px; }\n.tab-content.active { display: block; }\n.search-row { display: flex; gap: 8px; margin-bottom: 20px; }\n.search-row input { flex: 1; background: #161b22; border: 1px solid #30363d; color: #c9d1d9; padding: 8px 12px; border-radius: 4px; font-family: inherit; font-size: 14px; }\n.search-row button, .btn { background: #21262d; border: 1px solid #30363d; color: #c9d1d9; padding: 8px 16px; border-radius: 4px; cursor: pointer; font-family: inherit; font-size: 14px; }\n.search-row button:hover, .btn:hover { background: #30363d; }\n.timeline { display: flex; flex-direction: column; gap: 0; }\n.timeline-item { display: flex; gap: 16px; padding: 12px 0; border-bottom: 1px solid #21262d; }\n.timeline-dot { width: 10px; height: 10px; border-radius: 50%; background: #58a6ff; margin-top: 5px; flex-shrink: 0; }\n.timeline-dot.gate-pass { background: #3fb950; }\n.timeline-dot.gate-fail { background: #f85149; }\n.timeline-dot.invocation { background: #d2a8ff; }\n.timeline-body { flex: 1; }\n.timeline-ts { color: #8b949e; font-size: 12px; margin-bottom: 4px; }\n.timeline-label { font-weight: bold; color: #e6edf3; }\n.timeline-sub { color: #8b949e; font-size: 12px; margin-top: 2px; }\n.badge { display: inline-block; padding: 2px 8px; border-radius: 12px; font-size: 11px; font-weight: bold; }\n.badge-pass { background: #0d4429; color: #3fb950; }\n.badge-fail { background: #490202; color: #f85149; }\n.badge-pending { background: #1c2a3a; color: #58a6ff; }\n.badge-complete { background: #0d2d0d; color: #3fb950; }\n.badge-amber { background: #2d1f00; color: #e3b341; }\n.flow-select { background: #161b22; border: 1px solid #30363d; color: #c9d1d9; padding: 8px 12px; border-radius: 4px; font-family: inherit; font-size: 14px; margin-bottom: 20px; }\n.flow-graph { position: relative; display: flex; gap: 32px; flex-wrap: wrap; align-items: flex-start; padding: 16px; background: #161b22; border: 1px solid #30363d; border-radius: 8px; min-height: 200px; }\n.state-box { background: #0d1117; border: 1px solid #30363d; border-radius: 6px; padding: 12px 16px; min-width: 140px; }\n.state-box.initial { border-color: #58a6ff; }\n.state-box.terminal { border-color: #3fb950; }\n.state-name { font-weight: bold; color: #e6edf3; margin-bottom: 4px; }\n.state-count { color: #8b949e; font-size: 12px; }\n.workers-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 16px; margin-bottom: 24px; }\n.stat-card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }\n.stat-card .label { color: #8b949e; font-size: 12px; margin-bottom: 4px; }\n.stat-card .value { color: #e6edf3; font-size: 24px; font-weight: bold; }\ntable { width: 100%; border-collapse: collapse; }\nth { text-align: left; padding: 8px 12px; color: #8b949e; font-size: 12px; border-bottom: 1px solid #30363d; }\ntd { padding: 8px 12px; border-bottom: 1px solid #21262d; vertical-align: top; }\ntd.ts { color: #8b949e; font-size: 12px; white-space: nowrap; }\ntd.type-cell { color: #d2a8ff; font-size: 12px; white-space: nowrap; }\ntd.entity-cell { color: #58a6ff; font-size: 12px; font-family: monospace; }\ntd.payload-cell { color: #8b949e; font-size: 11px; max-width: 400px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; cursor: pointer; }\ntd.payload-cell.expanded { white-space: pre-wrap; word-break: break-all; }\n.filter-row { display: flex; gap: 8px; margin-bottom: 16px; align-items: center; }\n.filter-row select { background: #161b22; border: 1px solid #30363d; color: #c9d1d9; padding: 6px 10px; border-radius: 4px; font-family: inherit; font-size: 13px; }\n.filter-row label { color: #8b949e; font-size: 13px; }\n#sse-status { position: fixed; bottom: 12px; right: 16px; font-size: 11px; color: #8b949e; }\n#sse-status.connected { color: #3fb950; }\n#sse-status.error { color: #f85149; }\n.empty { color: #8b949e; text-align: center; padding: 32px; }\n.error-msg { color: #f85149; margin: 8px 0; font-size: 13px; }\n</style>\n</head>\n<body>\n\n<div id=\"auth-overlay\">\n  <div id=\"auth-box\">\n    <h2>DEFCON</h2>\n    <p style=\"color:#8b949e;margin-bottom:16px;font-size:13px;\">Enter your admin token to continue.</p>\n    <input type=\"password\" id=\"token-input\" placeholder=\"Admin token\" autocomplete=\"off\">\n    <div id=\"auth-error\" class=\"error-msg\" style=\"display:none\"></div>\n    <button onclick=\"doLogin()\">Connect</button>\n  </div>\n</div>\n\n<nav>\n  <h1>DEFCON</h1>\n  <button class=\"tab active\" onclick=\"showTab('entity-timeline', this)\">Timeline</button>\n  <button class=\"tab\" onclick=\"showTab('flow-graph', this)\">Flow Graph</button>\n  <button class=\"tab\" onclick=\"showTab('worker-dashboard', this)\">Workers</button>\n  <button class=\"tab\" onclick=\"showTab('event-log', this)\">Event Log</button>\n</nav>\n\n<!-- Entity Timeline -->\n<div id=\"entity-timeline\" class=\"tab-content active\">\n  <div class=\"search-row\">\n    <input id=\"entity-id-input\" type=\"text\" placeholder=\"Entity ID...\" onkeydown=\"if(event.key==='Enter')loadTimeline()\">\n    <button onclick=\"loadTimeline()\">Load</button>\n  </div>\n  <div id=\"timeline-container\"><p class=\"empty\">Enter an entity ID to view its timeline.</p></div>\n</div>\n\n<!-- Flow Graph -->\n<div id=\"flow-graph\" class=\"tab-content\">\n  <select id=\"flow-select\" class=\"flow-select\" onchange=\"loadFlowGraph()\">\n    <option value=\"\">-- Select a flow --</option>\n  </select>\n  <div id=\"graph-container\"><p class=\"empty\">Select a flow to visualize its state graph.</p></div>\n</div>\n\n<!-- Worker Dashboard -->\n<div id=\"worker-dashboard\" class=\"tab-content\">\n  <div style=\"display:flex;justify-content:space-between;align-items:center;margin-bottom:16px;\">\n    <h2 style=\"color:#e6edf3;font-size:16px;\">Worker Dashboard</h2>\n    <button class=\"btn\" onclick=\"loadDashboard()\">Refresh</button>\n  </div>\n  <div id=\"dashboard-container\"><p class=\"empty\">Loading...</p></div>\n</div>\n\n<!-- Event Log -->\n<div id=\"event-log\" class=\"tab-content\">\n  <div class=\"filter-row\">\n    <label>Filter by type:</label>\n    <select id=\"event-type-filter\" onchange=\"filterEventLog()\">\n      <option value=\"\">All</option>\n    </select>\n    <button class=\"btn\" onclick=\"loadEventLog()\">Refresh</button>\n  </div>\n  <div id=\"event-log-container\"><p class=\"empty\">Loading events...</p></div>\n</div>\n\n<div id=\"sse-status\">SSE: disconnected</div>\n\n<script>\nlet TOKEN = '';\nlet sseSource = null;\nlet allEvents = [];\nlet dashboardDebounceTimer = null;\n\nfunction scheduleDashboardRefresh() {\n  if (dashboardDebounceTimer) clearTimeout(dashboardDebounceTimer);\n  dashboardDebounceTimer = setTimeout(() => {\n    dashboardDebounceTimer = null;\n    if (document.getElementById('worker-dashboard').classList.contains('active')) {\n      loadDashboard();\n    }\n  }, 100);\n}\n\nfunction ts(ms) {\n  return new Date(typeof ms === 'number' ? ms : ms).toLocaleString();\n}\n\nfunction doLogin() {\n  const v = document.getElementById('token-input').value.trim();\n  if (!v) { showAuthError('Token required'); return; }\n  TOKEN = v;\n  sessionStorage.setItem('defcon-token', v);\n  verifyToken();\n}\n\nfunction showAuthError(msg) {\n  const el = document.getElementById('auth-error');\n  el.textContent = msg;\n  el.style.display = 'block';\n}\n\nfunction verifyToken() {\n  fetch('/api/ui/events/recent?limit=1', { headers: { Authorization: 'Bearer ' + TOKEN } })\n    .then(r => {\n      if (r.ok) {\n        document.getElementById('auth-overlay').style.display = 'none';\n        initApp();\n      } else {\n        showAuthError('Invalid token');\n        TOKEN = '';\n        sessionStorage.removeItem('defcon-token');\n      }\n    })\n    .catch(() => showAuthError('Connection failed'));\n}\n\nfunction initApp() {\n  connectSSE();\n  loadEventLog();\n  loadFlowList();\n  loadDashboard();\n}\n\nfunction connectSSE() {\n  if (sseSource) sseSource.close();\n  // Pass token via Authorization header using a fetch-based SSE reader to\n  // avoid exposing it in the URL (which appears in server logs).\n  // EventSource does not support custom headers, so we use fetch + ReadableStream.\n  const ctrl = new AbortController();\n  sseSource = ctrl; // store for close()\n  fetch('/api/ui/events', { headers: { Authorization: 'Bearer ' + TOKEN }, signal: ctrl.signal })\n    .then(r => {\n      if (!r.ok) { handleSseError(); return; }\n      const el = document.getElementById('sse-status');\n      el.textContent = 'SSE: connected';\n      el.className = 'connected';\n      const reader = r.body.getReader();\n      const decoder = new TextDecoder();\n      let buf = '';\n      function pump() {\n        reader.read().then(({ done, value }) => {\n          if (done) { handleSseError(); return; }\n          buf += decoder.decode(value, { stream: true });\n          const lines = buf.split('\n');\n          buf = lines.pop();\n          for (const line of lines) {\n            if (line.startsWith('data: ')) {\n              try {\n                const ev = JSON.parse(line.slice(6));\n                prependEventRow(ev);\n                scheduleDashboardRefresh();\n              } catch (_) {}\n            }\n          }\n          pump();\n        }).catch(handleSseError);\n      }\n      pump();\n    })\n    .catch(handleSseError);\n  function handleSseError() {\n    const el = document.getElementById('sse-status');\n    if (el) { el.textContent = 'SSE: reconnecting...'; el.className = 'error'; }\n    setTimeout(() => connectSSE(), 5000);\n  }\n}\n  sseSource.onopen = () => {\n    const el = document.getElementById('sse-status');\n    el.textContent = 'SSE: connected';\n    el.className = 'connected';\n  };\n  sseSource.onerror = () => {\n    const el = document.getElementById('sse-status');\n    el.textContent = 'SSE: reconnecting...';\n    el.className = 'error';\n  };\n  sseSource.onmessage = (e) => {\n    try {\n      const ev = JSON.parse(e.data);\n      prependEventRow(ev);\n      if (document.getElementById('worker-dashboard').classList.contains('active')) {\n        loadDashboard();\n      }\n    } catch (_) {}\n  };\n}\n\nfunction api(path) {\n  return fetch(path, { headers: { Authorization: 'Bearer ' + TOKEN } }).then(r => {\n    if (!r.ok) throw new Error('HTTP ' + r.status);\n    return r.json();\n  });\n}\n\nfunction showTab(id, btn) {\n  document.querySelectorAll('.tab-content').forEach(el => el.classList.remove('active'));\n  document.querySelectorAll('.tab').forEach(el => el.classList.remove('active'));\n  document.getElementById(id).classList.add('active');\n  btn.classList.add('active');\n  if (id === 'worker-dashboard') loadDashboard();\n  if (id === 'flow-graph') loadFlowList();\n}\n\n// \u2500\u2500 Entity Timeline \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nasync function loadTimeline() {\n  const id = document.getElementById('entity-id-input').value.trim();\n  if (!id) return;\n  const el = document.getElementById('timeline-container');\n  el.innerHTML = '<p class=\"empty\">Loading...</p>';\n  try {\n    const [entity, events, invocations, gates] = await Promise.all([\n      api('/api/entities/' + encodeURIComponent(id)),\n      api('/api/ui/entity/' + encodeURIComponent(id) + '/events'),\n      api('/api/ui/entity/' + encodeURIComponent(id) + '/invocations'),\n      api('/api/ui/entity/' + encodeURIComponent(id) + '/gates'),\n    ]);\n\n    // Build merged timeline\n    const rows = [];\n\n    if (entity && entity.id) {\n      rows.push({ t: new Date(entity.createdAt).getTime(), kind: 'entity', label: 'Entity created', sub: 'Flow: ' + entity.flowId + ' | State: ' + entity.state });\n    }\n\n    for (const ev of (Array.isArray(events) ? events : [])) {\n      rows.push({ t: ev.emittedAt, kind: ev.type, label: ev.type, sub: JSON.stringify(ev.payload || {}).slice(0, 120) });\n    }\n\n    for (const inv of (Array.isArray(invocations) ? invocations : [])) {\n      const st = inv.startedAt ? new Date(inv.startedAt).getTime() : (inv.createdAt ? new Date(inv.createdAt).getTime() : 0);\n      rows.push({ t: st, kind: 'invocation', label: 'Invocation: ' + inv.stage, sub: 'Status: ' + (inv.completedAt ? 'completed' : inv.failedAt ? 'failed' : 'pending') + (inv.signal ? ' | signal: ' + inv.signal : '') });\n    }\n\n    for (const g of (Array.isArray(gates) ? gates : [])) {\n      rows.push({ t: g.evaluatedAt ? new Date(g.evaluatedAt).getTime() : 0, kind: g.passed ? 'gate-pass' : 'gate-fail', label: 'Gate: ' + g.gateId, sub: g.passed ? 'PASSED' : 'FAILED' + (g.output ? ' \u2014 ' + g.output.slice(0, 80) : '') });\n    }\n\n    rows.sort((a, b) => a.t - b.t);\n\n    if (rows.length === 0) { el.innerHTML = '<p class=\"empty\">No data for this entity.</p>'; return; }\n\n    el.innerHTML = '<div class=\"timeline\">' + rows.map(r => {\n      let dotClass = 'timeline-dot';\n      if (r.kind === 'gate-pass') dotClass += ' gate-pass';\n      else if (r.kind === 'gate-fail') dotClass += ' gate-fail';\n      else if (r.kind === 'invocation') dotClass += ' invocation';\n      return '<div class=\"timeline-item\"><div class=\"' + dotClass + '\"></div><div class=\"timeline-body\"><div class=\"timeline-ts\">' + (r.t ? ts(r.t) : '\u2014') + '</div><div class=\"timeline-label\">' + esc(r.label) + '</div><div class=\"timeline-sub\">' + esc(r.sub || '') + '</div></div></div>';\n    }).join('') + '</div>';\n  } catch (e) {\n    el.innerHTML = '<p class=\"error-msg\">Error: ' + esc(String(e)) + '</p>';\n  }\n}\n\n// \u2500\u2500 Flow Graph \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nasync function loadFlowList() {\n  try {\n    const flows = await api('/api/flows');\n    const sel = document.getElementById('flow-select');\n    const prev = sel.value;\n    sel.innerHTML = '<option value=\"\">-- Select a flow --</option>';\n    for (const f of (Array.isArray(flows) ? flows : [])) {\n      const opt = document.createElement('option');\n      opt.value = f.id;\n      opt.textContent = f.name;\n      sel.appendChild(opt);\n    }\n    if (prev) { sel.value = prev; loadFlowGraph(); }\n  } catch (_) {}\n}\n\nasync function loadFlowGraph() {\n  const id = document.getElementById('flow-select').value;\n  const el = document.getElementById('graph-container');\n  if (!id) { el.innerHTML = '<p class=\"empty\">Select a flow.</p>'; return; }\n  el.innerHTML = '<p class=\"empty\">Loading...</p>';\n  try {\n    const [flow, status] = await Promise.all([api('/api/flows/' + encodeURIComponent(id)), api('/api/status')]);\n    const counts = {};\n    if (status && status.flows) {\n      for (const fstat of status.flows) {\n        if (fstat.flowId === id && fstat.states) {\n          for (const s of fstat.states) counts[s.state] = s.count;\n        }\n      }\n    }\n    const states = flow.states || [];\n    const transitions = flow.transitions || [];\n    const initial = flow.initialState;\n    const terminalSet = new Set();\n    for (const s of states) {\n      const hasOut = transitions.some(t => t.fromState === s.name);\n      if (!hasOut) terminalSet.add(s.name);\n    }\n\n    const boxes = states.map(s => {\n      let cls = 'state-box';\n      if (s.name === initial) cls += ' initial';\n      if (terminalSet.has(s.name)) cls += ' terminal';\n      return '<div class=\"' + cls + '\"><div class=\"state-name\">' + esc(s.name) + '</div><div class=\"state-count\">' + (counts[s.name] || 0) + ' entities</div>' + (s.agentRole ? '<div class=\"state-count\" style=\"color:#d2a8ff\">' + esc(s.agentRole) + '</div>' : '') + '</div>';\n    });\n\n    el.innerHTML = '<div class=\"flow-graph\">' + boxes.join('') + '</div>';\n    if (transitions.length) {\n      const list = transitions.map(t => '<tr><td>' + esc(t.fromState) + '</td><td style=\"color:#8b949e\">\u2192</td><td>' + esc(t.toState) + '</td><td style=\"color:#d2a8ff\">' + esc(t.trigger) + '</td><td>' + (t.gateId ? '<span class=\"badge badge-amber\">gated</span>' : '') + '</td></tr>').join('');\n      el.innerHTML += '<h3 style=\"color:#8b949e;font-size:13px;margin:16px 0 8px\">Transitions</h3><table><thead><tr><th>From</th><th></th><th>To</th><th>Trigger</th><th>Gate</th></tr></thead><tbody>' + list + '</tbody></table>';\n    }\n  } catch (e) {\n    el.innerHTML = '<p class=\"error-msg\">Error: ' + esc(String(e)) + '</p>';\n  }\n}\n\n// \u2500\u2500 Worker Dashboard \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nasync function loadDashboard() {\n  const el = document.getElementById('dashboard-container');\n  try {\n    const status = await api('/api/status');\n    let html = '<div class=\"workers-grid\">';\n    html += '<div class=\"stat-card\"><div class=\"label\">Active Invocations</div><div class=\"value\">' + (status.activeInvocations || 0) + '</div></div>';\n    html += '<div class=\"stat-card\"><div class=\"label\">Pending Claims</div><div class=\"value\">' + (status.pendingClaims || 0) + '</div></div>';\n    html += '<div class=\"stat-card\"><div class=\"label\">Total Entities</div><div class=\"value\">' + (status.totalEntities || 0) + '</div></div>';\n    html += '</div>';\n\n    if (status.flows && status.flows.length) {\n      html += '<h3 style=\"color:#e6edf3;font-size:14px;margin-bottom:12px;\">Flows</h3><table><thead><tr><th>Flow</th><th>State</th><th>Count</th></tr></thead><tbody>';\n      for (const f of status.flows) {\n        for (const s of (f.states || [])) {\n          html += '<tr><td style=\"color:#58a6ff\">' + esc(f.flowName || f.flowId) + '</td><td>' + esc(s.state) + '</td><td>' + s.count + '</td></tr>';\n        }\n      }\n      html += '</tbody></table>';\n    }\n    el.innerHTML = html;\n  } catch (e) {\n    el.innerHTML = '<p class=\"error-msg\">Error: ' + esc(String(e)) + '</p>';\n  }\n}\n\n// \u2500\u2500 Event Log \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nasync function loadEventLog() {\n  const el = document.getElementById('event-log-container');\n  try {\n    const fetched = await api('/api/ui/events/recent?limit=200');\n    const fetchedRows = Array.isArray(fetched) ? fetched : [];\n    // Merge: keep SSE-injected events not in the fetched set (by id), then prepend fetched\n    const fetchedIds = new Set(fetchedRows.map(e => e.id));\n    const sseOnly = allEvents.filter(e => !fetchedIds.has(e.id));\n    allEvents = [...sseOnly, ...fetchedRows];\n    updateEventTypeFilter();\n    renderEventLog();\n  } catch (e) {\n    el.innerHTML = '<p class=\"error-msg\">Error: ' + esc(String(e)) + '</p>';\n  }\n}\n\nfunction prependEventRow(ev) {\n  // Convert SSE event to EventRow format\n  const row = { id: ev.id || '', type: ev.type || '', entityId: ev.entityId || null, flowId: ev.flowId || null, payload: ev, emittedAt: ev.timestamp ? new Date(ev.timestamp).getTime() : Date.now() };\n  allEvents.unshift(row);\n  if (allEvents.length > 500) allEvents.pop();\n  updateEventTypeFilter();\n  renderEventLog();\n}\n\nfunction updateEventTypeFilter() {\n  const sel = document.getElementById('event-type-filter');\n  const cur = sel.value;\n  const types = [...new Set(allEvents.map(e => e.type))].sort();\n  sel.innerHTML = '<option value=\"\">All</option>' + types.map(t => '<option value=\"' + esc(t) + '\">' + esc(t) + '</option>').join('');\n  if (cur) sel.value = cur;\n}\n\nfunction filterEventLog() { renderEventLog(); }\n\nfunction renderEventLog() {\n  const filter = document.getElementById('event-type-filter').value;\n  const el = document.getElementById('event-log-container');\n  const filtered = filter ? allEvents.filter(e => e.type === filter) : allEvents;\n  if (!filtered.length) { el.innerHTML = '<p class=\"empty\">No events.</p>'; return; }\n  const rows = filtered.map(e => '<tr><td class=\"ts\">' + ts(e.emittedAt) + '</td><td class=\"type-cell\">' + esc(e.type) + '</td><td class=\"entity-cell\">' + esc(e.entityId || '\u2014') + \"</td><td class=\"payload-cell\" onclick=\"this.classList.toggle('expanded')\">\" + esc(JSON.stringify(e.payload || {})) + '</td></tr>').join('');\n  el.innerHTML = '<table><thead><tr><th>Time</th><th>Type</th><th>Entity</th><th>Payload</th></tr></thead><tbody>' + rows + '</tbody></table>';\n}\n\nfunction esc(s) {\n  return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/\"/g,'&quot;').replace(/'/g,'&#39;');\n}\n\n// \u2500\u2500 Init \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\n\nconst savedToken = sessionStorage.getItem('defcon-token');\nif (savedToken) {\n  TOKEN = savedToken;\n  document.getElementById('token-input').value = savedToken;\n  verifyToken();\n}\n</script>\n</body>\n</html>";

package/dist/src/ui/index.html.js

@@ -0,0 +1,465 @@
+export const UI_HTML = `<!DOCTYPE html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>DEFCON Dashboard</title>
+<style>
+*, *::before, *::after { box-sizing: border-box; margin: 0; padding: 0; }
+body { background: #0d1117; color: #c9d1d9; font-family: 'Courier New', monospace; font-size: 14px; }
+#auth-overlay { position: fixed; inset: 0; background: #0d1117; display: flex; align-items: center; justify-content: center; z-index: 100; }
+#auth-box { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 32px; width: 360px; }
+#auth-box h2 { color: #58a6ff; margin-bottom: 16px; font-size: 18px; }
+#auth-box input { width: 100%; background: #0d1117; border: 1px solid #30363d; color: #c9d1d9; padding: 8px 12px; border-radius: 4px; font-family: inherit; font-size: 14px; margin-bottom: 12px; }
+#auth-box button { width: 100%; background: #238636; border: none; color: #fff; padding: 8px; border-radius: 4px; cursor: pointer; font-size: 14px; }
+#auth-box button:hover { background: #2ea043; }
+nav { background: #161b22; border-bottom: 1px solid #30363d; padding: 0 24px; display: flex; align-items: center; gap: 0; }
+nav h1 { color: #58a6ff; font-size: 16px; margin-right: 32px; padding: 14px 0; }
+.tab { background: none; border: none; color: #8b949e; padding: 14px 16px; cursor: pointer; font-family: inherit; font-size: 14px; border-bottom: 2px solid transparent; }
+.tab:hover { color: #c9d1d9; }
+.tab.active { color: #58a6ff; border-bottom-color: #58a6ff; }
+.tab-content { display: none; padding: 24px; }
+.tab-content.active { display: block; }
+.search-row { display: flex; gap: 8px; margin-bottom: 20px; }
+.search-row input { flex: 1; background: #161b22; border: 1px solid #30363d; color: #c9d1d9; padding: 8px 12px; border-radius: 4px; font-family: inherit; font-size: 14px; }
+.search-row button, .btn { background: #21262d; border: 1px solid #30363d; color: #c9d1d9; padding: 8px 16px; border-radius: 4px; cursor: pointer; font-family: inherit; font-size: 14px; }
+.search-row button:hover, .btn:hover { background: #30363d; }
+.timeline { display: flex; flex-direction: column; gap: 0; }
+.timeline-item { display: flex; gap: 16px; padding: 12px 0; border-bottom: 1px solid #21262d; }
+.timeline-dot { width: 10px; height: 10px; border-radius: 50%; background: #58a6ff; margin-top: 5px; flex-shrink: 0; }
+.timeline-dot.gate-pass { background: #3fb950; }
+.timeline-dot.gate-fail { background: #f85149; }
+.timeline-dot.invocation { background: #d2a8ff; }
+.timeline-body { flex: 1; }
+.timeline-ts { color: #8b949e; font-size: 12px; margin-bottom: 4px; }
+.timeline-label { font-weight: bold; color: #e6edf3; }
+.timeline-sub { color: #8b949e; font-size: 12px; margin-top: 2px; }
+.badge { display: inline-block; padding: 2px 8px; border-radius: 12px; font-size: 11px; font-weight: bold; }
+.badge-pass { background: #0d4429; color: #3fb950; }
+.badge-fail { background: #490202; color: #f85149; }
+.badge-pending { background: #1c2a3a; color: #58a6ff; }
+.badge-complete { background: #0d2d0d; color: #3fb950; }
+.badge-amber { background: #2d1f00; color: #e3b341; }
+.flow-select { background: #161b22; border: 1px solid #30363d; color: #c9d1d9; padding: 8px 12px; border-radius: 4px; font-family: inherit; font-size: 14px; margin-bottom: 20px; }
+.flow-graph { position: relative; display: flex; gap: 32px; flex-wrap: wrap; align-items: flex-start; padding: 16px; background: #161b22; border: 1px solid #30363d; border-radius: 8px; min-height: 200px; }
+.state-box { background: #0d1117; border: 1px solid #30363d; border-radius: 6px; padding: 12px 16px; min-width: 140px; }
+.state-box.initial { border-color: #58a6ff; }
+.state-box.terminal { border-color: #3fb950; }
+.state-name { font-weight: bold; color: #e6edf3; margin-bottom: 4px; }
+.state-count { color: #8b949e; font-size: 12px; }
+.workers-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(200px, 1fr)); gap: 16px; margin-bottom: 24px; }
+.stat-card { background: #161b22; border: 1px solid #30363d; border-radius: 8px; padding: 16px; }
+.stat-card .label { color: #8b949e; font-size: 12px; margin-bottom: 4px; }
+.stat-card .value { color: #e6edf3; font-size: 24px; font-weight: bold; }
+table { width: 100%; border-collapse: collapse; }
+th { text-align: left; padding: 8px 12px; color: #8b949e; font-size: 12px; border-bottom: 1px solid #30363d; }
+td { padding: 8px 12px; border-bottom: 1px solid #21262d; vertical-align: top; }
+td.ts { color: #8b949e; font-size: 12px; white-space: nowrap; }
+td.type-cell { color: #d2a8ff; font-size: 12px; white-space: nowrap; }
+td.entity-cell { color: #58a6ff; font-size: 12px; font-family: monospace; }
+td.payload-cell { color: #8b949e; font-size: 11px; max-width: 400px; overflow: hidden; text-overflow: ellipsis; white-space: nowrap; cursor: pointer; }
+td.payload-cell.expanded { white-space: pre-wrap; word-break: break-all; }
+.filter-row { display: flex; gap: 8px; margin-bottom: 16px; align-items: center; }
+.filter-row select { background: #161b22; border: 1px solid #30363d; color: #c9d1d9; padding: 6px 10px; border-radius: 4px; font-family: inherit; font-size: 13px; }
+.filter-row label { color: #8b949e; font-size: 13px; }
+#sse-status { position: fixed; bottom: 12px; right: 16px; font-size: 11px; color: #8b949e; }
+#sse-status.connected { color: #3fb950; }
+#sse-status.error { color: #f85149; }
+.empty { color: #8b949e; text-align: center; padding: 32px; }
+.error-msg { color: #f85149; margin: 8px 0; font-size: 13px; }
+</style>
+</head>
+<body>
+
+<div id="auth-overlay">
+  <div id="auth-box">
+    <h2>DEFCON</h2>
+    <p style="color:#8b949e;margin-bottom:16px;font-size:13px;">Enter your admin token to continue.</p>
+    <input type="password" id="token-input" placeholder="Admin token" autocomplete="off">
+    <div id="auth-error" class="error-msg" style="display:none"></div>
+    <button onclick="doLogin()">Connect</button>
+  </div>
+</div>
+
+<nav>
+  <h1>DEFCON</h1>
+  <button class="tab active" onclick="showTab('entity-timeline', this)">Timeline</button>
+  <button class="tab" onclick="showTab('flow-graph', this)">Flow Graph</button>
+  <button class="tab" onclick="showTab('worker-dashboard', this)">Workers</button>
+  <button class="tab" onclick="showTab('event-log', this)">Event Log</button>
+</nav>
+
+<!-- Entity Timeline -->
+<div id="entity-timeline" class="tab-content active">
+  <div class="search-row">
+    <input id="entity-id-input" type="text" placeholder="Entity ID..." onkeydown="if(event.key==='Enter')loadTimeline()">
+    <button onclick="loadTimeline()">Load</button>
+  </div>
+  <div id="timeline-container"><p class="empty">Enter an entity ID to view its timeline.</p></div>
+</div>
+
+<!-- Flow Graph -->
+<div id="flow-graph" class="tab-content">
+  <select id="flow-select" class="flow-select" onchange="loadFlowGraph()">
+    <option value="">-- Select a flow --</option>
+  </select>
+  <div id="graph-container"><p class="empty">Select a flow to visualize its state graph.</p></div>
+</div>
+
+<!-- Worker Dashboard -->
+<div id="worker-dashboard" class="tab-content">
+  <div style="display:flex;justify-content:space-between;align-items:center;margin-bottom:16px;">
+    <h2 style="color:#e6edf3;font-size:16px;">Worker Dashboard</h2>
+    <button class="btn" onclick="loadDashboard()">Refresh</button>
+  </div>
+  <div id="dashboard-container"><p class="empty">Loading...</p></div>
+</div>
+
+<!-- Event Log -->
+<div id="event-log" class="tab-content">
+  <div class="filter-row">
+    <label>Filter by type:</label>
+    <select id="event-type-filter" onchange="filterEventLog()">
+      <option value="">All</option>
+    </select>
+    <button class="btn" onclick="loadEventLog()">Refresh</button>
+  </div>
+  <div id="event-log-container"><p class="empty">Loading events...</p></div>
+</div>
+
+<div id="sse-status">SSE: disconnected</div>
+
+<script>
+let TOKEN = '';
+let sseSource = null;
+let allEvents = [];
+let dashboardDebounceTimer = null;
+
+function scheduleDashboardRefresh() {
+  if (dashboardDebounceTimer) clearTimeout(dashboardDebounceTimer);
+  dashboardDebounceTimer = setTimeout(() => {
+    dashboardDebounceTimer = null;
+    if (document.getElementById('worker-dashboard').classList.contains('active')) {
+      loadDashboard();
+    }
+  }, 100);
+}
+
+function ts(ms) {
+  return new Date(typeof ms === 'number' ? ms : ms).toLocaleString();
+}
+
+function doLogin() {
+  const v = document.getElementById('token-input').value.trim();
+  if (!v) { showAuthError('Token required'); return; }
+  TOKEN = v;
+  sessionStorage.setItem('defcon-token', v);
+  verifyToken();
+}
+
+function showAuthError(msg) {
+  const el = document.getElementById('auth-error');
+  el.textContent = msg;
+  el.style.display = 'block';
+}
+
+function verifyToken() {
+  fetch('/api/ui/events/recent?limit=1', { headers: { Authorization: 'Bearer ' + TOKEN } })
+    .then(r => {
+      if (r.ok) {
+        document.getElementById('auth-overlay').style.display = 'none';
+        initApp();
+      } else {
+        showAuthError('Invalid token');
+        TOKEN = '';
+        sessionStorage.removeItem('defcon-token');
+      }
+    })
+    .catch(() => showAuthError('Connection failed'));
+}
+
+function initApp() {
+  connectSSE();
+  loadEventLog();
+  loadFlowList();
+  loadDashboard();
+}
+
+function connectSSE() {
+  if (sseSource) sseSource.close();
+  // Pass token via Authorization header using a fetch-based SSE reader to
+  // avoid exposing it in the URL (which appears in server logs).
+  // EventSource does not support custom headers, so we use fetch + ReadableStream.
+  const ctrl = new AbortController();
+  sseSource = ctrl; // store for close()
+  fetch('/api/ui/events', { headers: { Authorization: 'Bearer ' + TOKEN }, signal: ctrl.signal })
+    .then(r => {
+      if (!r.ok) { handleSseError(); return; }
+      const el = document.getElementById('sse-status');
+      el.textContent = 'SSE: connected';
+      el.className = 'connected';
+      const reader = r.body.getReader();
+      const decoder = new TextDecoder();
+      let buf = '';
+      function pump() {
+        reader.read().then(({ done, value }) => {
+          if (done) { handleSseError(); return; }
+          buf += decoder.decode(value, { stream: true });
+          const lines = buf.split('\n');
+          buf = lines.pop();
+          for (const line of lines) {
+            if (line.startsWith('data: ')) {
+              try {
+                const ev = JSON.parse(line.slice(6));
+                prependEventRow(ev);
+                scheduleDashboardRefresh();
+              } catch (_) {}
+            }
+          }
+          pump();
+        }).catch(handleSseError);
+      }
+      pump();
+    })
+    .catch(handleSseError);
+  function handleSseError() {
+    const el = document.getElementById('sse-status');
+    if (el) { el.textContent = 'SSE: reconnecting...'; el.className = 'error'; }
+    setTimeout(() => connectSSE(), 5000);
+  }
+}
+  sseSource.onopen = () => {
+    const el = document.getElementById('sse-status');
+    el.textContent = 'SSE: connected';
+    el.className = 'connected';
+  };
+  sseSource.onerror = () => {
+    const el = document.getElementById('sse-status');
+    el.textContent = 'SSE: reconnecting...';
+    el.className = 'error';
+  };
+  sseSource.onmessage = (e) => {
+    try {
+      const ev = JSON.parse(e.data);
+      prependEventRow(ev);
+      if (document.getElementById('worker-dashboard').classList.contains('active')) {
+        loadDashboard();
+      }
+    } catch (_) {}
+  };
+}
+
+function api(path) {
+  return fetch(path, { headers: { Authorization: 'Bearer ' + TOKEN } }).then(r => {
+    if (!r.ok) throw new Error('HTTP ' + r.status);
+    return r.json();
+  });
+}
+
+function showTab(id, btn) {
+  document.querySelectorAll('.tab-content').forEach(el => el.classList.remove('active'));
+  document.querySelectorAll('.tab').forEach(el => el.classList.remove('active'));
+  document.getElementById(id).classList.add('active');
+  btn.classList.add('active');
+  if (id === 'worker-dashboard') loadDashboard();
+  if (id === 'flow-graph') loadFlowList();
+}
+
+// ── Entity Timeline ──────────────────────────────────────────────
+
+async function loadTimeline() {
+  const id = document.getElementById('entity-id-input').value.trim();
+  if (!id) return;
+  const el = document.getElementById('timeline-container');
+  el.innerHTML = '<p class="empty">Loading...</p>';
+  try {
+    const [entity, events, invocations, gates] = await Promise.all([
+      api('/api/entities/' + encodeURIComponent(id)),
+      api('/api/ui/entity/' + encodeURIComponent(id) + '/events'),
+      api('/api/ui/entity/' + encodeURIComponent(id) + '/invocations'),
+      api('/api/ui/entity/' + encodeURIComponent(id) + '/gates'),
+    ]);
+
+    // Build merged timeline
+    const rows = [];
+
+    if (entity && entity.id) {
+      rows.push({ t: new Date(entity.createdAt).getTime(), kind: 'entity', label: 'Entity created', sub: 'Flow: ' + entity.flowId + ' | State: ' + entity.state });
+    }
+
+    for (const ev of (Array.isArray(events) ? events : [])) {
+      rows.push({ t: ev.emittedAt, kind: ev.type, label: ev.type, sub: JSON.stringify(ev.payload || {}).slice(0, 120) });
+    }
+
+    for (const inv of (Array.isArray(invocations) ? invocations : [])) {
+      const st = inv.startedAt ? new Date(inv.startedAt).getTime() : (inv.createdAt ? new Date(inv.createdAt).getTime() : 0);
+      rows.push({ t: st, kind: 'invocation', label: 'Invocation: ' + inv.stage, sub: 'Status: ' + (inv.completedAt ? 'completed' : inv.failedAt ? 'failed' : 'pending') + (inv.signal ? ' | signal: ' + inv.signal : '') });
+    }
+
+    for (const g of (Array.isArray(gates) ? gates : [])) {
+      rows.push({ t: g.evaluatedAt ? new Date(g.evaluatedAt).getTime() : 0, kind: g.passed ? 'gate-pass' : 'gate-fail', label: 'Gate: ' + g.gateId, sub: g.passed ? 'PASSED' : 'FAILED' + (g.output ? ' — ' + g.output.slice(0, 80) : '') });
+    }
+
+    rows.sort((a, b) => a.t - b.t);
+
+    if (rows.length === 0) { el.innerHTML = '<p class="empty">No data for this entity.</p>'; return; }
+
+    el.innerHTML = '<div class="timeline">' + rows.map(r => {
+      let dotClass = 'timeline-dot';
+      if (r.kind === 'gate-pass') dotClass += ' gate-pass';
+      else if (r.kind === 'gate-fail') dotClass += ' gate-fail';
+      else if (r.kind === 'invocation') dotClass += ' invocation';
+      return '<div class="timeline-item"><div class="' + dotClass + '"></div><div class="timeline-body"><div class="timeline-ts">' + (r.t ? ts(r.t) : '—') + '</div><div class="timeline-label">' + esc(r.label) + '</div><div class="timeline-sub">' + esc(r.sub || '') + '</div></div></div>';
+    }).join('') + '</div>';
+  } catch (e) {
+    el.innerHTML = '<p class="error-msg">Error: ' + esc(String(e)) + '</p>';
+  }
+}
+
+// ── Flow Graph ───────────────────────────────────────────────────
+
+async function loadFlowList() {
+  try {
+    const flows = await api('/api/flows');
+    const sel = document.getElementById('flow-select');
+    const prev = sel.value;
+    sel.innerHTML = '<option value="">-- Select a flow --</option>';
+    for (const f of (Array.isArray(flows) ? flows : [])) {
+      const opt = document.createElement('option');
+      opt.value = f.id;
+      opt.textContent = f.name;
+      sel.appendChild(opt);
+    }
+    if (prev) { sel.value = prev; loadFlowGraph(); }
+  } catch (_) {}
+}
+
+async function loadFlowGraph() {
+  const id = document.getElementById('flow-select').value;
+  const el = document.getElementById('graph-container');
+  if (!id) { el.innerHTML = '<p class="empty">Select a flow.</p>'; return; }
+  el.innerHTML = '<p class="empty">Loading...</p>';
+  try {
+    const [flow, status] = await Promise.all([api('/api/flows/' + encodeURIComponent(id)), api('/api/status')]);
+    const counts = {};
+    if (status && status.flows) {
+      for (const fstat of status.flows) {
+        if (fstat.flowId === id && fstat.states) {
+          for (const s of fstat.states) counts[s.state] = s.count;
+        }
+      }
+    }
+    const states = flow.states || [];
+    const transitions = flow.transitions || [];
+    const initial = flow.initialState;
+    const terminalSet = new Set();
+    for (const s of states) {
+      const hasOut = transitions.some(t => t.fromState === s.name);
+      if (!hasOut) terminalSet.add(s.name);
+    }
+
+    const boxes = states.map(s => {
+      let cls = 'state-box';
+      if (s.name === initial) cls += ' initial';
+      if (terminalSet.has(s.name)) cls += ' terminal';
+      return '<div class="' + cls + '"><div class="state-name">' + esc(s.name) + '</div><div class="state-count">' + (counts[s.name] || 0) + ' entities</div>' + (s.agentRole ? '<div class="state-count" style="color:#d2a8ff">' + esc(s.agentRole) + '</div>' : '') + '</div>';
+    });
+
+    el.innerHTML = '<div class="flow-graph">' + boxes.join('') + '</div>';
+    if (transitions.length) {
+      const list = transitions.map(t => '<tr><td>' + esc(t.fromState) + '</td><td style="color:#8b949e">→</td><td>' + esc(t.toState) + '</td><td style="color:#d2a8ff">' + esc(t.trigger) + '</td><td>' + (t.gateId ? '<span class="badge badge-amber">gated</span>' : '') + '</td></tr>').join('');
+      el.innerHTML += '<h3 style="color:#8b949e;font-size:13px;margin:16px 0 8px">Transitions</h3><table><thead><tr><th>From</th><th></th><th>To</th><th>Trigger</th><th>Gate</th></tr></thead><tbody>' + list + '</tbody></table>';
+    }
+  } catch (e) {
+    el.innerHTML = '<p class="error-msg">Error: ' + esc(String(e)) + '</p>';
+  }
+}
+
+// ── Worker Dashboard ─────────────────────────────────────────────
+
+async function loadDashboard() {
+  const el = document.getElementById('dashboard-container');
+  try {
+    const status = await api('/api/status');
+    let html = '<div class="workers-grid">';
+    html += '<div class="stat-card"><div class="label">Active Invocations</div><div class="value">' + (status.activeInvocations || 0) + '</div></div>';
+    html += '<div class="stat-card"><div class="label">Pending Claims</div><div class="value">' + (status.pendingClaims || 0) + '</div></div>';
+    html += '<div class="stat-card"><div class="label">Total Entities</div><div class="value">' + (status.totalEntities || 0) + '</div></div>';
+    html += '</div>';
+
+    if (status.flows && status.flows.length) {
+      html += '<h3 style="color:#e6edf3;font-size:14px;margin-bottom:12px;">Flows</h3><table><thead><tr><th>Flow</th><th>State</th><th>Count</th></tr></thead><tbody>';
+      for (const f of status.flows) {
+        for (const s of (f.states || [])) {
+          html += '<tr><td style="color:#58a6ff">' + esc(f.flowName || f.flowId) + '</td><td>' + esc(s.state) + '</td><td>' + s.count + '</td></tr>';
+        }
+      }
+      html += '</tbody></table>';
+    }
+    el.innerHTML = html;
+  } catch (e) {
+    el.innerHTML = '<p class="error-msg">Error: ' + esc(String(e)) + '</p>';
+  }
+}
+
+// ── Event Log ────────────────────────────────────────────────────
+
+async function loadEventLog() {
+  const el = document.getElementById('event-log-container');
+  try {
+    const fetched = await api('/api/ui/events/recent?limit=200');
+    const fetchedRows = Array.isArray(fetched) ? fetched : [];
+    // Merge: keep SSE-injected events not in the fetched set (by id), then prepend fetched
+    const fetchedIds = new Set(fetchedRows.map(e => e.id));
+    const sseOnly = allEvents.filter(e => !fetchedIds.has(e.id));
+    allEvents = [...sseOnly, ...fetchedRows];
+    updateEventTypeFilter();
+    renderEventLog();
+  } catch (e) {
+    el.innerHTML = '<p class="error-msg">Error: ' + esc(String(e)) + '</p>';
+  }
+}
+
+function prependEventRow(ev) {
+  // Convert SSE event to EventRow format
+  const row = { id: ev.id || '', type: ev.type || '', entityId: ev.entityId || null, flowId: ev.flowId || null, payload: ev, emittedAt: ev.timestamp ? new Date(ev.timestamp).getTime() : Date.now() };
+  allEvents.unshift(row);
+  if (allEvents.length > 500) allEvents.pop();
+  updateEventTypeFilter();
+  renderEventLog();
+}
+
+function updateEventTypeFilter() {
+  const sel = document.getElementById('event-type-filter');
+  const cur = sel.value;
+  const types = [...new Set(allEvents.map(e => e.type))].sort();
+  sel.innerHTML = '<option value="">All</option>' + types.map(t => '<option value="' + esc(t) + '">' + esc(t) + '</option>').join('');
+  if (cur) sel.value = cur;
+}
+
+function filterEventLog() { renderEventLog(); }
+
+function renderEventLog() {
+  const filter = document.getElementById('event-type-filter').value;
+  const el = document.getElementById('event-log-container');
+  const filtered = filter ? allEvents.filter(e => e.type === filter) : allEvents;
+  if (!filtered.length) { el.innerHTML = '<p class="empty">No events.</p>'; return; }
+  const rows = filtered.map(e => '<tr><td class="ts">' + ts(e.emittedAt) + '</td><td class="type-cell">' + esc(e.type) + '</td><td class="entity-cell">' + esc(e.entityId || '—') + "</td><td class="payload-cell" onclick="this.classList.toggle('expanded')">" + esc(JSON.stringify(e.payload || {})) + '</td></tr>').join('');
+  el.innerHTML = '<table><thead><tr><th>Time</th><th>Type</th><th>Entity</th><th>Payload</th></tr></thead><tbody>' + rows + '</tbody></table>';
+}
+
+function esc(s) {
+  return String(s).replace(/&/g,'&amp;').replace(/</g,'&lt;').replace(/>/g,'&gt;').replace(/"/g,'&quot;').replace(/'/g,'&#39;');
+}
+
+// ── Init ─────────────────────────────────────────────────────────
+
+const savedToken = sessionStorage.getItem('defcon-token');
+if (savedToken) {
+  TOKEN = savedToken;
+  document.getElementById('token-input').value = savedToken;
+  verifyToken();
+}
+</script>
+</body>
+</html>`;

package/dist/src/ui/sse.d.ts

@@ -0,0 +1,8 @@
+import type { ServerResponse } from "node:http";
+import type { EngineEvent, IEventBusAdapter } from "../engine/event-types.js";
+export declare class UiSseAdapter implements IEventBusAdapter {
+    private clients;
+    addClient(res: ServerResponse): void;
+    get clientCount(): number;
+    emit(event: EngineEvent): Promise<void>;
+}

package/dist/src/ui/sse.js

@@ -0,0 +1,23 @@
+export class UiSseAdapter {
+    clients = new Set();
+    addClient(res) {
+        this.clients.add(res);
+        res.on("close", () => this.clients.delete(res));
+    }
+    get clientCount() {
+        return this.clients.size;
+    }
+    async emit(event) {
+        const { emittedAt, ...rest } = event;
+        const msg = JSON.stringify({ ...rest, timestamp: emittedAt.toISOString() });
+        const frame = `data: ${msg}\n\n`;
+        for (const client of this.clients) {
+            try {
+                client.write(frame);
+            }
+            catch {
+                this.clients.delete(client);
+            }
+        }
+    }
+}

package/drizzle/0015_aberrant_luminals.sql

@@ -0,0 +1,2 @@
+CREATE INDEX `events_entity_id_idx` ON `events` (`entity_id`);--> statement-breakpoint
+CREATE INDEX `events_emitted_at_idx` ON `events` (`emitted_at`);

package/drizzle/0015_add_parent_entity_id.sql

@@ -0,0 +1,2 @@
+ALTER TABLE `entities` ADD `parent_entity_id` text;--> statement-breakpoint
+CREATE INDEX `entities_parent_idx` ON `entities` (`parent_entity_id`);

package/drizzle/meta/_journal.json

@@ -106,6 +106,13 @@
       "when": 1773031139526,
       "tag": "0014_smiling_crusher_hogan",
       "breakpoints": true
+    },
+    {
+      "idx": 15,
+      "version": "6",
+      "when": 1773200000001,
+      "tag": "0015_add_parent_entity_id",
+      "breakpoints": true
     }
   ]
-}
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@wopr-network/defcon",
-  "version": "1.7.0",
+  "version": "1.9.0",
   "type": "module",
   "packageManager": "pnpm@9.15.4",
   "engines": {