@tt-a1i/hive 1.4.3 → 1.5.0

package/dist/src/server/terminal-stream-hub.js

@@ -1,6 +1,7 @@
 import { createTerminalOutputFlow } from './terminal-flow-control.js';
 import { parseTerminalControlMessage, serializeTerminalError, serializeTerminalExit, serializeTerminalRestore, } from './terminal-protocol.js';
 import { TerminalStateMirror } from './terminal-state-mirror.js';
+import { attachWebSocketErrorHandler, sendWebSocketMessage } from './websocket-upgrade-safety.js';
 const normalizeTerminalInput = (raw, isBinary) => {
     const bytes = Buffer.isBuffer(raw)
         ? raw
@@ -85,8 +86,8 @@ export const createTerminalStreamHub = (store) => {
                 const payload = serializeTerminalExit(run.exitCode);
                 for (const viewer of state.viewers.values()) {
                     const controlSocket = viewer.controlSocket;
-                    if (controlSocket && controlSocket.readyState === controlSocket.OPEN)
-                        controlSocket.send(payload);
+                    if (controlSocket)
+                        sendWebSocketMessage(controlSocket, payload, `terminal ${runId} exit`);
                 }
                 if (state.exitInterval)
                     clearInterval(state.exitInterval);
@@ -103,18 +104,17 @@ export const createTerminalStreamHub = (store) => {
     return {
         attachControl(runId, clientId, socket, initialSize) {
             const state = getOrCreateState(runId, initialSize);
+            attachWebSocketErrorHandler(socket, `terminal ${runId} control`);
             const viewer = getOrCreateViewer(state, clientId);
             viewer.controlSocket = socket;
             startExitWatcher(runId, state);
             void state.mirror
                 .getSnapshot()
                 .then((snapshot) => {
-                if (socket.readyState === socket.OPEN)
-                    socket.send(serializeTerminalRestore(snapshot));
+                sendWebSocketMessage(socket, serializeTerminalRestore(snapshot), `terminal ${runId} restore`);
             })
                 .catch(() => {
-                if (socket.readyState === socket.OPEN)
-                    socket.send(serializeTerminalRestore(''));
+                sendWebSocketMessage(socket, serializeTerminalRestore(''), `terminal ${runId} restore`);
             });
             socket.on('message', (raw) => {
                 try {
@@ -131,7 +131,7 @@ export const createTerminalStreamHub = (store) => {
                         return;
                 }
                 catch (error) {
-                    socket.send(serializeTerminalError(error instanceof Error ? error.message : 'Invalid control message'));
+                    sendWebSocketMessage(socket, serializeTerminalError(error instanceof Error ? error.message : 'Invalid control message'), `terminal ${runId} control error`);
                 }
             });
             socket.on('close', () => {
@@ -142,6 +142,7 @@ export const createTerminalStreamHub = (store) => {
         },
         attachIo(runId, clientId, socket, initialSize) {
             const state = getOrCreateState(runId, initialSize);
+            attachWebSocketErrorHandler(socket, `terminal ${runId} io`);
             const viewer = getOrCreateViewer(state, clientId);
             viewer.ioSocket = socket;
             viewer.flowState?.close();
@@ -158,7 +159,12 @@ export const createTerminalStreamHub = (store) => {
                 },
             });
             socket.on('message', (raw, isBinary) => {
-                store.writeRunInput(runId, normalizeTerminalInput(raw, isBinary));
+                try {
+                    store.writeRunInput(runId, normalizeTerminalInput(raw, isBinary));
+                }
+                catch (error) {
+                    sendWebSocketMessage(socket, serializeTerminalError(error instanceof Error ? error.message : 'Failed to write terminal input'), `terminal ${runId} input error`);
+                }
             });
             socket.on('close', () => {
                 if (viewer.ioSocket === socket)
@@ -176,8 +182,8 @@ export const createTerminalStreamHub = (store) => {
                 state.mirror.dispose();
                 for (const viewer of state.viewers.values()) {
                     viewer.flowState?.close();
-                    viewer.ioSocket?.close();
-                    viewer.controlSocket?.close();
+                    viewer.ioSocket?.terminate();
+                    viewer.controlSocket?.terminate();
                 }
                 runStates.delete(runId);
             }

package/dist/src/server/terminal-ws-server.js

@@ -3,6 +3,7 @@ import { getLocalRequestRejection } from './local-request-guard.js';
 import { createTasksWebSocketServer } from './tasks-websocket-server.js';
 import { createTerminalStreamHub } from './terminal-stream-hub.js';
 import { readCookie } from './ui-auth-helpers.js';
+import { attachRawSocketErrorHandler, attachWebSocketServerErrorHandler, rejectWebSocketUpgrade, } from './websocket-upgrade-safety.js';
 const matchTerminalPath = (pathname) => {
     const match = /^\/ws\/terminal\/(?<runId>[^/]+)\/(?<channel>io|control)$/.exec(pathname);
     const groups = match?.groups;
@@ -24,13 +25,11 @@ const getInitialSize = (url) => {
     }
     return { cols, rows };
 };
-const rejectUpgrade = (socket, status) => {
-    socket.write(`HTTP/1.1 ${status}\r\n\r\n`);
-    socket.destroy();
-};
 export const createTerminalWebSocketServer = (server, store, tasksFileService) => {
     const ioWss = new WebSocketServer({ noServer: true });
     const controlWss = new WebSocketServer({ noServer: true });
+    attachWebSocketServerErrorHandler(ioWss, 'terminal io');
+    attachWebSocketServerErrorHandler(controlWss, 'terminal control');
     const tasksWss = createTasksWebSocketServer(server, store, tasksFileService);
     const hub = createTerminalStreamHub(store);
     const disposeTasksListener = store.registerTasksListener((workspaceId, content) => {
@@ -43,6 +42,26 @@ export const createTerminalWebSocketServer = (server, store, tasksFileService) =
         const token = readCookie(cookieHeader, 'hive_ui_token');
         return store.validateUiToken(token);
     };
+    let closed = false;
+    const closeAll = () => {
+        if (closed)
+            return;
+        closed = true;
+        // Order matters: dispose the publisher first so no new frames are
+        // queued onto sockets that are about to be torn down. Then forcibly
+        // terminate any open WS clients (terminate() skips the close
+        // handshake, which is what we need — a polite ws.close() would wait
+        // on the remote side and re-introduce the hang we're fixing).
+        disposeTasksListener();
+        for (const ws of ioWss.clients)
+            ws.terminate();
+        for (const ws of controlWss.clients)
+            ws.terminate();
+        tasksWss.close();
+        ioWss.close();
+        controlWss.close();
+        hub.close();
+    };
     server.on('upgrade', (request, socket, head) => {
         const url = new URL(request.url ?? '/', 'http://127.0.0.1');
         const pathname = url.pathname;
@@ -51,26 +70,29 @@ export const createTerminalWebSocketServer = (server, store, tasksFileService) =
             if (/^\/ws\/tasks\/.+/.test(pathname)) {
                 return;
             }
-            rejectUpgrade(socket, '404 Not Found');
+            attachRawSocketErrorHandler(socket, 'terminal upgrade');
+            rejectWebSocketUpgrade(socket, '404 Not Found');
             return;
         }
+        const detachRawSocketErrorHandler = attachRawSocketErrorHandler(socket, 'terminal upgrade');
         if (getLocalRequestRejection(request)) {
-            rejectUpgrade(socket, '403 Forbidden');
+            rejectWebSocketUpgrade(socket, '403 Forbidden');
             return;
         }
         if (!validateUpgradeSession(request)) {
-            rejectUpgrade(socket, '401 Unauthorized');
+            rejectWebSocketUpgrade(socket, '401 Unauthorized');
             return;
         }
         try {
             store.getLiveRun(match.runId);
         }
         catch {
-            rejectUpgrade(socket, '404 Not Found');
+            rejectWebSocketUpgrade(socket, '404 Not Found');
             return;
         }
         const wss = match.channel === 'io' ? ioWss : controlWss;
         wss.handleUpgrade(request, socket, head, (ws) => {
+            detachRawSocketErrorHandler();
             const clientId = getClientId(url);
             if (match.channel === 'io')
                 hub.attachIo(match.runId, clientId, ws, getInitialSize(url));
@@ -78,12 +100,10 @@ export const createTerminalWebSocketServer = (server, store, tasksFileService) =
                 hub.attachControl(match.runId, clientId, ws, getInitialSize(url));
         });
     });
-    server.on('close', () => {
-        disposeTasksListener();
-        hub.close();
-        ioWss.close();
-        controlWss.close();
-        tasksWss.close();
-    });
-    return { close: () => hub.close() };
+    // Kept as an idempotent fallback for callers that drive
+    // `app.server.close()` directly (e.g. unit tests in tests/server/*)
+    // and never see the runHiveCommand close path. closeAll() is guarded
+    // by `closed` so calling both is a no-op.
+    server.on('close', closeAll);
+    return { close: closeAll };
 };

package/dist/src/server/websocket-upgrade-safety.d.ts

@@ -0,0 +1,10 @@
+import type { Duplex } from 'node:stream';
+import type WebSocket from 'ws';
+import type { WebSocketServer } from 'ws';
+type UpgradeSocket = Duplex;
+export declare const attachRawSocketErrorHandler: (socket: UpgradeSocket, context: string) => () => Duplex;
+export declare const attachWebSocketServerErrorHandler: (wss: WebSocketServer, context: string) => void;
+export declare const attachWebSocketErrorHandler: (socket: WebSocket, context: string) => void;
+export declare const rejectWebSocketUpgrade: (socket: UpgradeSocket, status: string) => void;
+export declare const sendWebSocketMessage: (socket: WebSocket, payload: string, context: string) => boolean;
+export {};

package/dist/src/server/websocket-upgrade-safety.js

@@ -0,0 +1,35 @@
+const logSocketError = (context, error) => {
+    console.error(`[hive] ${context}`, error);
+};
+export const attachRawSocketErrorHandler = (socket, context) => {
+    const handler = (error) => logSocketError(`${context} socket error`, error);
+    socket.on('error', handler);
+    return () => socket.off('error', handler);
+};
+export const attachWebSocketServerErrorHandler = (wss, context) => {
+    wss.on('error', (error) => logSocketError(`${context} websocket server error`, error));
+};
+export const attachWebSocketErrorHandler = (socket, context) => {
+    socket.on('error', (error) => logSocketError(`${context} websocket error`, error));
+};
+export const rejectWebSocketUpgrade = (socket, status) => {
+    try {
+        socket.write(`HTTP/1.1 ${status}\r\nConnection: close\r\n\r\n`);
+    }
+    catch (error) {
+        logSocketError(`failed to reject websocket upgrade with ${status}`, error);
+    }
+    socket.destroy();
+};
+export const sendWebSocketMessage = (socket, payload, context) => {
+    if (socket.readyState !== socket.OPEN)
+        return false;
+    try {
+        socket.send(payload);
+        return true;
+    }
+    catch (error) {
+        logSocketError(`${context} send failed`, error);
+        return false;
+    }
+};

package/dist/src/server/windows-command-line.d.ts

@@ -0,0 +1,3 @@
+export declare const escapeCmdToken: (value: string) => string;
+export declare const buildCmdCommand: (command: string, args?: readonly string[]) => string;
+export declare const buildCmdCallCommand: (command: string, args?: readonly string[]) => string;

package/dist/src/server/windows-command-line.js

@@ -0,0 +1,9 @@
+const CMD_META_CHARS = /[\s"&<>|^()%]/u;
+export const escapeCmdToken = (value) => {
+    if (value.length === 0)
+        return '""';
+    const escaped = value.replace(/%/g, '%%').replace(/"/g, '""');
+    return CMD_META_CHARS.test(value) ? `"${escaped}"` : escaped;
+};
+export const buildCmdCommand = (command, args = []) => [command, ...args].map(escapeCmdToken).join(' ');
+export const buildCmdCallCommand = (command, args = []) => `call ${buildCmdCommand(command, args)}`;

package/dist/src/server/windows-filename.d.ts

@@ -0,0 +1,2 @@
+export declare const getWindowsFilenameError: (filename: string) => string | undefined;
+export declare const assertWindowsSafeFilename: (filename: string) => void;

package/dist/src/server/windows-filename.js

@@ -0,0 +1,33 @@
+const WINDOWS_DEVICE_NAMES = /^(con|prn|aux|nul|com[1-9\u00b9\u00b2\u00b3]|lpt[1-9\u00b9\u00b2\u00b3])$/iu;
+const WINDOWS_INVALID_FILENAME_CHARS = new Set(['<', '>', ':', '"', '/', '\\', '|', '?', '*']);
+const hasWindowsInvalidFilenameChar = (filename) => {
+    for (const char of filename) {
+        if (WINDOWS_INVALID_FILENAME_CHARS.has(char))
+            return true;
+        const code = char.codePointAt(0) ?? 0;
+        if (code >= 0 && code <= 31)
+            return true;
+    }
+    return false;
+};
+export const getWindowsFilenameError = (filename) => {
+    if (!filename.trim())
+        return 'filename must not be empty';
+    if (filename === '.' || filename === '..')
+        return 'filename must not be a relative segment';
+    if (hasWindowsInvalidFilenameChar(filename)) {
+        return 'filename contains characters Windows cannot create';
+    }
+    if (/[. ]$/u.test(filename))
+        return 'filename must not end with a space or period';
+    const stem = filename.split('.')[0] ?? filename;
+    if (WINDOWS_DEVICE_NAMES.test(stem)) {
+        return `filename uses reserved Windows device name: ${stem}`;
+    }
+    return undefined;
+};
+export const assertWindowsSafeFilename = (filename) => {
+    const error = getWindowsFilenameError(filename);
+    if (error)
+        throw new Error(error);
+};

package/dist/src/server/workflow-cli-policy.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Workflow CLI policy — controls which CLI a workflow's `agent()` spawns.
+ *
+ * Before this, the runner hard-coded `opts.cli ?? 'claude'`: a user who only
+ * had Codex set up would have every workflow agent that omitted `cli` spawn a
+ * `claude` it can't run. The policy makes the default configurable and lets
+ * the user constrain which CLIs workflow agents may use.
+ *
+ * Stored GLOBALLY in `app_state` (CLI availability is a machine-level fact, not
+ * per-workspace) under WORKFLOW_CLI_POLICY_KEY as a JSON `{default, allowed}`.
+ * An absent/malformed value reads back as DEFAULT_WORKFLOW_CLI_POLICY, which is
+ * unrestricted and defaults to `claude` — i.e. exactly the old behavior, so
+ * upgrading without configuring anything changes nothing.
+ */
+/** Canonical CLI set — mirrors the built-in command preset ids
+ *  (see command-preset-defaults.ts). The allowlist is a subset of these. */
+export declare const CANONICAL_WORKFLOW_CLIS: readonly ["claude", "codex", "opencode", "gemini"];
+export type WorkflowCli = (typeof CANONICAL_WORKFLOW_CLIS)[number];
+export declare const WORKFLOW_CLI_POLICY_KEY = "workflow.cli-policy";
+export interface WorkflowCliPolicy {
+    /** CLI used when an `agent()` call omits `cli` and isn't a custom template. */
+    default: string;
+    /** CLIs an explicit `opts.cli` (and the default fallback) may use. */
+    allowed: string[];
+}
+export declare const DEFAULT_WORKFLOW_CLI_POLICY: WorkflowCliPolicy;
+/**
+ * Lenient coercion used by the runtime reader: turn arbitrary stored data into
+ * a usable policy, never throwing. Junk in `allowed` is dropped; an empty
+ * result falls back to the full canonical default; a `default` outside the
+ * sanitized `allowed` is pulled back to the first allowed entry.
+ */
+export declare const normalizeWorkflowCliPolicy: (input: unknown) => WorkflowCliPolicy;
+/** Parse the raw `app_state` string. Absent / malformed → canonical default. */
+export declare const readWorkflowCliPolicy: (raw: string | null | undefined) => WorkflowCliPolicy;
+/**
+ * Strict validation for the settings API: reject bad input so a malformed
+ * policy can never be persisted (the reader tolerates junk, but we'd rather
+ * fail the write than silently store something the user didn't intend).
+ */
+export declare const assertValidWorkflowCliPolicy: (input: unknown) => WorkflowCliPolicy;
+export interface ResolveWorkflowCliInput {
+    /** `opts.cli` from the `agent()` call, if any. */
+    requestedCli?: string;
+    /** True when `agentType` resolved to a workspace custom role template. */
+    isCustomTemplate: boolean;
+    /** The custom template's `defaultCommand` (only consulted when custom). */
+    templateDefaultCommand?: string;
+    policy: WorkflowCliPolicy;
+}
+/**
+ * Resolve the CLI command a workflow agent should launch with.
+ *
+ * - An explicit `requestedCli` is ALWAYS validated against `allowed` (throws
+ *   if disallowed, so the orchestrator gets a clear, fixable error).
+ * - When omitted: a custom template keeps its own `defaultCommand` (the user
+ *   curated that role deliberately — exempt from the allowlist); a built-in
+ *   role falls back to `policy.default`.
+ */
+export declare const resolveWorkflowCli: ({ requestedCli, isCustomTemplate, templateDefaultCommand, policy, }: ResolveWorkflowCliInput) => string;

package/dist/src/server/workflow-cli-policy.js

@@ -0,0 +1,110 @@
+/**
+ * Workflow CLI policy — controls which CLI a workflow's `agent()` spawns.
+ *
+ * Before this, the runner hard-coded `opts.cli ?? 'claude'`: a user who only
+ * had Codex set up would have every workflow agent that omitted `cli` spawn a
+ * `claude` it can't run. The policy makes the default configurable and lets
+ * the user constrain which CLIs workflow agents may use.
+ *
+ * Stored GLOBALLY in `app_state` (CLI availability is a machine-level fact, not
+ * per-workspace) under WORKFLOW_CLI_POLICY_KEY as a JSON `{default, allowed}`.
+ * An absent/malformed value reads back as DEFAULT_WORKFLOW_CLI_POLICY, which is
+ * unrestricted and defaults to `claude` — i.e. exactly the old behavior, so
+ * upgrading without configuring anything changes nothing.
+ */
+/** Canonical CLI set — mirrors the built-in command preset ids
+ *  (see command-preset-defaults.ts). The allowlist is a subset of these. */
+export const CANONICAL_WORKFLOW_CLIS = ['claude', 'codex', 'opencode', 'gemini'];
+export const WORKFLOW_CLI_POLICY_KEY = 'workflow.cli-policy';
+export const DEFAULT_WORKFLOW_CLI_POLICY = {
+    default: 'claude',
+    allowed: [...CANONICAL_WORKFLOW_CLIS],
+};
+const isCanonical = (value) => typeof value === 'string' && CANONICAL_WORKFLOW_CLIS.includes(value);
+/** Canonical entries from `input`, deduped and in canonical order. */
+const sanitizeAllowed = (input) => {
+    if (!Array.isArray(input))
+        return [];
+    const set = new Set(input.filter(isCanonical));
+    return CANONICAL_WORKFLOW_CLIS.filter((cli) => set.has(cli));
+};
+/**
+ * Lenient coercion used by the runtime reader: turn arbitrary stored data into
+ * a usable policy, never throwing. Junk in `allowed` is dropped; an empty
+ * result falls back to the full canonical default; a `default` outside the
+ * sanitized `allowed` is pulled back to the first allowed entry.
+ */
+export const normalizeWorkflowCliPolicy = (input) => {
+    if (typeof input !== 'object' || input === null)
+        return DEFAULT_WORKFLOW_CLI_POLICY;
+    const record = input;
+    const allowed = sanitizeAllowed(record.allowed);
+    if (allowed.length === 0)
+        return DEFAULT_WORKFLOW_CLI_POLICY;
+    const requestedDefault = record.default;
+    const fallback = allowed[0];
+    const resolvedDefault = typeof requestedDefault === 'string' && allowed.includes(requestedDefault)
+        ? requestedDefault
+        : fallback;
+    return { default: resolvedDefault, allowed };
+};
+/** Parse the raw `app_state` string. Absent / malformed → canonical default. */
+export const readWorkflowCliPolicy = (raw) => {
+    if (raw === null || raw === undefined)
+        return DEFAULT_WORKFLOW_CLI_POLICY;
+    try {
+        return normalizeWorkflowCliPolicy(JSON.parse(raw));
+    }
+    catch {
+        return DEFAULT_WORKFLOW_CLI_POLICY;
+    }
+};
+/**
+ * Strict validation for the settings API: reject bad input so a malformed
+ * policy can never be persisted (the reader tolerates junk, but we'd rather
+ * fail the write than silently store something the user didn't intend).
+ */
+export const assertValidWorkflowCliPolicy = (input) => {
+    if (typeof input !== 'object' || input === null) {
+        throw new Error('workflow cli policy must be an object { default, allowed }');
+    }
+    const record = input;
+    if (!Array.isArray(record.allowed)) {
+        throw new Error('workflow cli policy `allowed` must be an array');
+    }
+    if (record.allowed.length === 0) {
+        throw new Error('workflow cli policy `allowed` must list at least one CLI');
+    }
+    const bad = record.allowed.find((entry) => !isCanonical(entry));
+    if (bad !== undefined) {
+        throw new Error(`workflow cli policy "allowed" has an unsupported CLI: ${JSON.stringify(bad)}. Supported: ${CANONICAL_WORKFLOW_CLIS.join(', ')}`);
+    }
+    if (typeof record.default !== 'string' || !record.allowed.includes(record.default)) {
+        throw new Error(`workflow cli policy "default" (${JSON.stringify(record.default)}) must be one of allowed: ${record.allowed.join(', ')}`);
+    }
+    // Dedupe + canonical order while preserving the (now-validated) selection.
+    return { default: record.default, allowed: sanitizeAllowed(record.allowed) };
+};
+/**
+ * Resolve the CLI command a workflow agent should launch with.
+ *
+ * - An explicit `requestedCli` is ALWAYS validated against `allowed` (throws
+ *   if disallowed, so the orchestrator gets a clear, fixable error).
+ * - When omitted: a custom template keeps its own `defaultCommand` (the user
+ *   curated that role deliberately — exempt from the allowlist); a built-in
+ *   role falls back to `policy.default`.
+ */
+export const resolveWorkflowCli = ({ requestedCli, isCustomTemplate, templateDefaultCommand, policy, }) => {
+    const explicit = requestedCli?.trim();
+    if (explicit) {
+        if (!policy.allowed.includes(explicit)) {
+            throw new Error(`Workflow agent cli '${explicit}' is not allowed in this workspace. ` +
+                `Allowed: ${policy.allowed.join(', ')}. ` +
+                `Pick an allowed cli, or change the workflow CLI policy in Settings.`);
+        }
+        return explicit;
+    }
+    if (isCustomTemplate && templateDefaultCommand)
+        return templateDefaultCommand;
+    return policy.default;
+};

package/dist/src/server/workflow-dispatch-awaiter.d.ts

@@ -0,0 +1,12 @@
+export interface ReportPayload {
+    text: string;
+    artifacts: string[];
+    status?: string;
+}
+export interface WorkflowDispatchAwaiter {
+    awaitReport(dispatchId: string, timeoutMs?: number): Promise<ReportPayload>;
+    notifyReport(dispatchId: string, payload: ReportPayload): void;
+    notifyCancel(dispatchId: string, reason: string): void;
+    cancelAll(reason: string): void;
+}
+export declare const createWorkflowDispatchAwaiter: () => WorkflowDispatchAwaiter;

package/dist/src/server/workflow-dispatch-awaiter.js

@@ -0,0 +1,80 @@
+// Default 10 minutes — workflows often run long. Callers may shorten via opts.
+const DEFAULT_TIMEOUT_MS = 10 * 60 * 1000;
+export const createWorkflowDispatchAwaiter = () => {
+    const pending = new Map();
+    // TIER 2 #10 — deferred-cancel state. The runner creates a dispatch
+    // and THEN calls awaitReport, with at least one microtask gap between
+    // the two. If notifyCancel(id) fires in that gap, it currently hits
+    // an empty `pending` map and no-ops; the subsequent awaitReport(id)
+    // then waits the full DEFAULT_TIMEOUT_MS (10 min) on a dispatch that
+    // is already cancelled. Remembering the cancel intent here lets
+    // awaitReport reject synchronously the instant it gets registered.
+    // We also remember any pre-arrived report payload for the same
+    // reason — defensive against a future ordering change.
+    const cancelledIds = new Map();
+    const reportedIds = new Map();
+    const take = (dispatchId) => {
+        const entry = pending.get(dispatchId);
+        if (entry) {
+            clearTimeout(entry.timer);
+            pending.delete(dispatchId);
+        }
+        return entry;
+    };
+    return {
+        awaitReport(dispatchId, timeoutMs = DEFAULT_TIMEOUT_MS) {
+            return new Promise((resolve, reject) => {
+                // Pre-arrived events: drain immediately, no timer / no entry.
+                const earlyReport = reportedIds.get(dispatchId);
+                if (earlyReport) {
+                    reportedIds.delete(dispatchId);
+                    resolve(earlyReport);
+                    return;
+                }
+                const earlyCancel = cancelledIds.get(dispatchId);
+                if (earlyCancel) {
+                    cancelledIds.delete(dispatchId);
+                    reject(new Error(`workflow dispatch ${dispatchId} cancelled: ${earlyCancel}`));
+                    return;
+                }
+                const timer = setTimeout(() => {
+                    pending.delete(dispatchId);
+                    reject(new Error(`workflow dispatch ${dispatchId} timeout after ${timeoutMs}ms`));
+                }, timeoutMs);
+                pending.set(dispatchId, { resolve, reject, timer });
+            });
+        },
+        notifyReport(dispatchId, payload) {
+            const entry = take(dispatchId);
+            if (entry) {
+                entry.resolve(payload);
+            }
+            else {
+                // Pre-arrival: stash for the eventual awaitReport call. Cap
+                // stash size implicitly by overwriting on duplicate id.
+                reportedIds.set(dispatchId, payload);
+            }
+        },
+        notifyCancel(dispatchId, reason) {
+            const entry = take(dispatchId);
+            if (entry) {
+                entry.reject(new Error(`workflow dispatch ${dispatchId} cancelled: ${reason}`));
+            }
+            else {
+                cancelledIds.set(dispatchId, reason);
+            }
+        },
+        cancelAll(reason) {
+            for (const [id, entry] of pending) {
+                clearTimeout(entry.timer);
+                entry.reject(new Error(`workflow dispatch ${id} cancelled: ${reason}`));
+            }
+            pending.clear();
+            // cancelAll happens at runtime close — anything waiting at that
+            // moment should fail loudly, but the deferred state can be
+            // safely dropped since no future awaitReport will run.
+            cancelledIds.clear();
+            reportedIds.clear();
+        },
+    };
+};

package/dist/src/server/workflow-feature.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Workflow experimental feature gate.
+ *
+ * Workflows (`team workflow run`, the scheduler, the UI drawer, and the chunk
+ * of orchestrator guidance that teaches them) are a power feature with sharp
+ * edges — runaway fan-outs, authoring footguns, no run-resume yet. They ship
+ * OFF by default; a user opts in from Settings. While off, the orchestrator is
+ * not even taught about workflows, which also keeps its always-on prompt lean.
+ *
+ * Stored GLOBALLY in `app_state` under WORKFLOW_ENABLED_KEY. Absent / anything
+ * other than the exact string "true" reads back as DISABLED.
+ */
+export declare const WORKFLOW_ENABLED_KEY = "workflow.enabled";
+export declare const readWorkflowEnabled: (raw: string | null | undefined) => boolean;
+export declare const serializeWorkflowEnabled: (enabled: boolean) => string;

package/dist/src/server/workflow-feature.js

@@ -0,0 +1,15 @@
+/**
+ * Workflow experimental feature gate.
+ *
+ * Workflows (`team workflow run`, the scheduler, the UI drawer, and the chunk
+ * of orchestrator guidance that teaches them) are a power feature with sharp
+ * edges — runaway fan-outs, authoring footguns, no run-resume yet. They ship
+ * OFF by default; a user opts in from Settings. While off, the orchestrator is
+ * not even taught about workflows, which also keeps its always-on prompt lean.
+ *
+ * Stored GLOBALLY in `app_state` under WORKFLOW_ENABLED_KEY. Absent / anything
+ * other than the exact string "true" reads back as DISABLED.
+ */
+export const WORKFLOW_ENABLED_KEY = 'workflow.enabled';
+export const readWorkflowEnabled = (raw) => raw === 'true';
+export const serializeWorkflowEnabled = (enabled) => (enabled ? 'true' : 'false');

package/dist/src/server/workflow-http-serializers.d.ts

@@ -0,0 +1,64 @@
+import type { LiveAgentRun } from './agent-runtime-types.js';
+import type { DispatchRecord } from './dispatch-ledger-store.js';
+import type { WorkflowRunRecord } from './workflow-run-store.js';
+import type { WorkflowScheduleRecord } from './workflow-schedule-store.js';
+export declare const serializeLiveAgentRun: (run: LiveAgentRun) => {
+    agent_id: string;
+    exit_code: number | null;
+    output: string;
+    pid: number | null;
+    run_id: string;
+    started_at: number;
+    status: import("./agent-manager.js").RunStatus;
+};
+export declare const serializeWorkflowRun: (run: WorkflowRunRecord) => {
+    agent_count: number;
+    args: unknown;
+    created_at: number;
+    error: string | null;
+    finished_at: number | null;
+    id: string;
+    name: string;
+    parent_run_id: string | null;
+    phase: string | null;
+    result: unknown;
+    script_hash: string | null;
+    script_path: string;
+    started_at: number;
+    status: import("./workflow-run-store.js").WorkflowRunStatus;
+    workspace_id: string;
+};
+export declare const serializeWorkflowDispatch: (dispatch: DispatchRecord & {
+    lastPtyLine?: string;
+}) => {
+    artifacts: string[];
+    created_at: number;
+    delivered_at: number | null;
+    from_agent_id: string | null;
+    id: string;
+    label: string | null;
+    last_pty_line: string | null;
+    phase: string | null;
+    reported_at: number | null;
+    report_text: string | null;
+    sequence: number | null;
+    status: import("./dispatch-ledger-store.js").DispatchStatus;
+    step_index: number | null;
+    submitted_at: number | null;
+    text: string;
+    to_agent_id: string;
+    workflow_run_id: string | null;
+    workspace_id: string;
+};
+export declare const serializeWorkflowSchedule: (schedule: WorkflowScheduleRecord) => {
+    args: unknown;
+    created_at: number;
+    cron: string;
+    enabled: boolean;
+    id: string;
+    last_run_at: number | null;
+    next_run_at: number;
+    script_path: string;
+    updated_at: number;
+    workspace_id: string;
+};