@tt-a1i/hive 1.4.4 → 1.5.0

package/dist/src/server/team-operations.d.ts

@@ -2,14 +2,19 @@ import type { TeamListItem } from '../shared/types.js';
 import type { AgentRuntime } from './agent-runtime.js';
 import type { DispatchRecord } from './dispatch-ledger-store.js';
 import type { MessageLogHandle, MessageLogRecord } from './message-log-store.js';
+import type { WorkflowDispatchAwaiter } from './workflow-dispatch-awaiter.js';
 import type { WorkspaceStore } from './workspace-store.js';
 export declare const formatUnknownWorkerError: (workerName: string, roster: readonly TeamListItem[]) => string;
 export interface TeamOperationsInput {
     agentRuntime: AgentRuntime;
     createDispatch: (input: {
         fromAgentId?: string;
+        label?: string;
+        phase?: string;
+        stepIndex?: number;
         text: string;
         toAgentId: string;
+        workflowRunId?: string;
         workspaceId: string;
     }) => DispatchRecord;
     deleteDispatch: (dispatchId: string) => void;
@@ -30,11 +35,20 @@ export interface TeamOperationsInput {
         workspaceId: string;
     }) => DispatchRecord | undefined;
     markDispatchSubmitted: (dispatchId: string) => void;
+    workflowDispatchAwaiter: WorkflowDispatchAwaiter;
     workspaceStore: WorkspaceStore;
+    /** Auto-dismiss an ephemeral orchestrator-spawned worker after its
+     *  dispatch report. Wired in runtime-store-helpers to remove the worker
+     *  completely (stop run, drop launch config, drop the row). M11. */
+    dismissEphemeralWorker?: (workspaceId: string, workerId: string) => void;
 }
 export interface DispatchTaskInput {
     fromAgentId?: string;
     hivePort?: string;
+    workflowRunId?: string;
+    stepIndex?: number;
+    phase?: string;
+    label?: string;
 }
 export interface ReportTaskInput {
     artifacts?: string[];
@@ -57,7 +71,7 @@ export interface ReportTaskResult {
     forwardError: string | null;
     forwarded: boolean;
 }
-export declare const createTeamOperations: ({ agentRuntime, createDispatch, deleteDispatch, deleteMessage, findOpenDispatch, findOpenDispatchById, insertMessage, markDispatchCancelled, markDispatchReportedByWorker, markDispatchSubmitted, workspaceStore, }: TeamOperationsInput) => {
+export declare const createTeamOperations: ({ agentRuntime, createDispatch, deleteDispatch, deleteMessage, findOpenDispatch, findOpenDispatchById, insertMessage, markDispatchCancelled, markDispatchReportedByWorker, markDispatchSubmitted, workflowDispatchAwaiter, workspaceStore, dismissEphemeralWorker, }: TeamOperationsInput) => {
     cancelTask(workspaceId: string, dispatchId: string, input: CancelTaskInput): {
         dispatch: DispatchRecord;
         forwardError: string | null;

package/dist/src/server/team-operations.js

@@ -1,5 +1,6 @@
 import { ConflictError, PtyInactiveError } from './http-errors.js';
 import { createReportMessage, createSendMessage, createStatusMessage, createUserInputMessage, } from './runtime-message-builders.js';
+import { getWorkflowAgentId } from './workspace-store-support.js';
 /* Roster snapshot embedded in the 409 the orchestrator sees when it
    dispatches to a missing name. Format prioritizes the orchestrator's
    parsing path: bullet-per-member with role + live status + pending
@@ -23,7 +24,7 @@ export const formatUnknownWorkerError = (workerName, roster) => {
     ].join('\n');
 };
 const reportForwardErrorMessage = (error) => error instanceof Error ? error.message : String(error);
-export const createTeamOperations = ({ agentRuntime, createDispatch, deleteDispatch, deleteMessage, findOpenDispatch, findOpenDispatchById, insertMessage, markDispatchCancelled, markDispatchReportedByWorker, markDispatchSubmitted, workspaceStore, }) => {
+export const createTeamOperations = ({ agentRuntime, createDispatch, deleteDispatch, deleteMessage, findOpenDispatch, findOpenDispatchById, insertMessage, markDispatchCancelled, markDispatchReportedByWorker, markDispatchSubmitted, workflowDispatchAwaiter, workspaceStore, dismissEphemeralWorker, }) => {
     const ensureWorkerRun = async (workspaceId, workerId, hivePort) => {
         if (agentRuntime.getActiveRunByAgentId(workspaceId, workerId)) {
             return;
@@ -45,10 +46,25 @@ export const createTeamOperations = ({ agentRuntime, createDispatch, deleteDispa
             throw error;
         }
     };
+    const cancelUndeliveredDispatch = (workspaceId, workerId, dispatchId, reason, workflowRunId) => {
+        const cancelled = markDispatchCancelled({ dispatchId, reason, workspaceId });
+        if (!cancelled)
+            return;
+        try {
+            workspaceStore.markTaskCancelled(workspaceId, workerId);
+        }
+        catch (error) {
+            console.error('[hive] swallowed:teamDispatch.markTaskCancelled', error);
+        }
+        if (workflowRunId !== undefined) {
+            workflowDispatchAwaiter.notifyCancel(dispatchId, reason);
+        }
+    };
     const dispatchTask = async (workspaceId, workerId, text, input = {}) => {
         const message = createSendMessage(workspaceId, workerId, text, input.fromAgentId);
         const messageHandle = insertMessage(message);
         let dispatch;
+        let pendingMarked = false;
         try {
             const dispatchInput = {
                 text,
@@ -57,18 +73,69 @@ export const createTeamOperations = ({ agentRuntime, createDispatch, deleteDispa
             };
             if (input.fromAgentId)
                 dispatchInput.fromAgentId = input.fromAgentId;
+            if (input.workflowRunId !== undefined)
+                dispatchInput.workflowRunId = input.workflowRunId;
+            if (input.stepIndex !== undefined)
+                dispatchInput.stepIndex = input.stepIndex;
+            if (input.phase !== undefined)
+                dispatchInput.phase = input.phase;
+            if (input.label !== undefined)
+                dispatchInput.label = input.label;
             dispatch = createDispatch(dispatchInput);
+            const dispatchId = dispatch.id;
             if (input.fromAgentId) {
                 const sender = workspaceStore.getAgent(workspaceId, input.fromAgentId);
                 await ensureWorkerRun(workspaceId, workerId, input.hivePort ?? '');
                 const worker = workspaceStore.getWorker(workspaceId, workerId);
-                markDispatchSubmitted(dispatch.id);
-                agentRuntime.writeSendPrompt(workspaceId, workerId, dispatch.id, sender.name, worker.description, text);
+                const isWorkflowDispatch = input.workflowRunId !== undefined || input.fromAgentId === getWorkflowAgentId(workspaceId);
+                markDispatchSubmitted(dispatchId);
+                workspaceStore.markTaskDispatched(workspaceId, workerId);
+                pendingMarked = true;
+                try {
+                    const writePrompt = agentRuntime.writeSendPrompt(workspaceId, workerId, dispatchId, sender.name, worker.description, text);
+                    void writePrompt.catch((error) => {
+                        // `team send` is intentionally asynchronous (§3.3). A worker that
+                        // exits during paste-submit did not receive actionable work, so
+                        // close the open dispatch instead of leaving a fake pending task.
+                        try {
+                            cancelUndeliveredDispatch(workspaceId, workerId, dispatchId, reportForwardErrorMessage(error), input.workflowRunId);
+                        }
+                        catch (cancelError) {
+                            if (!isWorkflowDispatch)
+                                console.error('[hive] swallowed:teamDispatch.cancelUndelivered', cancelError);
+                        }
+                        if (!isWorkflowDispatch)
+                            console.error('[hive] swallowed:teamDispatch.writePrompt', error);
+                    });
+                }
+                catch (error) {
+                    try {
+                        cancelUndeliveredDispatch(workspaceId, workerId, dispatchId, reportForwardErrorMessage(error), input.workflowRunId);
+                    }
+                    catch (cancelError) {
+                        if (!isWorkflowDispatch)
+                            console.error('[hive] swallowed:teamDispatch.cancelUndelivered', cancelError);
+                    }
+                    if (!isWorkflowDispatch)
+                        console.error('[hive] swallowed:teamDispatch.writePrompt', error);
+                }
+            }
+            else {
+                workspaceStore.markTaskDispatched(workspaceId, workerId);
+                pendingMarked = true;
             }
-            workspaceStore.markTaskDispatched(workspaceId, workerId);
             return dispatch;
         }
         catch (error) {
+            if (pendingMarked) {
+                try {
+                    workspaceStore.markTaskCancelled(workspaceId, workerId);
+                }
+                catch {
+                    // Best-effort compensation for the in-memory pending count; the
+                    // durable send message is deleted below.
+                }
+            }
             if (dispatch)
                 deleteDispatch(dispatch.id);
             deleteMessage(messageHandle);
@@ -164,17 +231,19 @@ export const createTeamOperations = ({ agentRuntime, createDispatch, deleteDispa
             const status = input.status;
             const artifacts = input.artifacts ?? [];
             const worker = workspaceStore.getWorker(workspaceId, workerId);
-            if (input.requireActiveRun === true &&
-                !agentRuntime.getActiveRunByAgentId(workspaceId, `${workspaceId}:orchestrator`)) {
-                throw new PtyInactiveError(`No active run for agent: ${workspaceId}:orchestrator`);
-            }
             const openDispatch = findOpenDispatch(workspaceId, workerId, input.dispatchId);
-            if (!openDispatch && input.dispatchId) {
-                throw new ConflictError(`No open dispatch for worker: ${worker.name}`);
-            }
             if (!openDispatch) {
                 throw new ConflictError(`No open dispatch for worker: ${worker.name}`);
             }
+            const isWorkflowDispatch = openDispatch.fromAgentId === getWorkflowAgentId(workspaceId);
+            // Pre-check the orchestrator PTY only when the report is heading there.
+            // Workflow-sourced dispatches don't need an orchestrator: the runner
+            // is in-process and will resolve its awaiter directly.
+            if (input.requireActiveRun === true && !isWorkflowDispatch) {
+                if (!agentRuntime.getActiveRunByAgentId(workspaceId, `${workspaceId}:orchestrator`)) {
+                    throw new PtyInactiveError(`No active run for agent: ${workspaceId}:orchestrator`);
+                }
+            }
             const messageHandle = insertMessage(createReportMessage(workspaceId, workerId, text, status, artifacts));
             try {
                 const dispatch = markDispatchReportedByWorker({
@@ -190,6 +259,24 @@ export const createTeamOperations = ({ agentRuntime, createDispatch, deleteDispa
                 workspaceStore.markTaskReported(workspaceId, workerId);
                 let forwardError = null;
                 let forwarded = false;
+                // Workflow-sourced dispatches: the source is the in-process runner, not a
+                // PTY. Resolve its awaiting Promise instead of injecting into orchestrator
+                // stdin (which would do nothing — `__workflow__` has no PTY).
+                if (dispatch.fromAgentId === getWorkflowAgentId(workspaceId)) {
+                    try {
+                        workflowDispatchAwaiter.notifyReport(dispatch.id, {
+                            artifacts,
+                            text,
+                            ...(status ? { status } : {}),
+                        });
+                        forwarded = true;
+                    }
+                    catch (error) {
+                        forwardError = reportForwardErrorMessage(error);
+                        console.error('[hive] swallowed:teamReport.workflowForward', error);
+                    }
+                    return { dispatch, forwardError, forwarded };
+                }
                 if (input.requireActiveRun === true) {
                     try {
                         agentRuntime.writeReportPrompt(workspaceId, worker.name, workerId, text, artifacts, {
@@ -202,6 +289,24 @@ export const createTeamOperations = ({ agentRuntime, createDispatch, deleteDispa
                         console.error('[hive] swallowed:teamReport.forward', error);
                     }
                 }
+                // M11: if this worker was spawned with `team spawn --ephemeral`, this
+                // first successful report is its trigger to auto-dismiss. Deferred via
+                // queueMicrotask so the orchestrator's forward write lands BEFORE the
+                // worker's PTY is torn down (otherwise the inject + dismiss race).
+                // Skipped for workflow dispatches — workflow workers are managed by
+                // the runner's own finally block.
+                if (worker.ephemeral === true &&
+                    worker.spawnedBy === 'orchestrator' &&
+                    dismissEphemeralWorker) {
+                    queueMicrotask(() => {
+                        try {
+                            dismissEphemeralWorker(workspaceId, workerId);
+                        }
+                        catch (error) {
+                            console.error('[hive] swallowed:teamReport.ephemeralDismiss', error);
+                        }
+                    });
+                }
                 return { dispatch, forwardError, forwarded };
             }
             catch (error) {

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

@@ -14,7 +14,11 @@ export const parseTerminalControlMessage = (raw) => {
     }
     const resizeCols = asInteger(cols);
     const resizeRows = asInteger(rows);
-    if (parsed.type === 'resize' && resizeCols !== undefined && resizeRows !== undefined) {
+    if (parsed.type === 'resize' &&
+        resizeCols !== undefined &&
+        resizeRows !== undefined &&
+        resizeCols > 0 &&
+        resizeRows > 0) {
         const message = {
             type: 'resize',
             cols: resizeCols,
@@ -22,10 +26,12 @@ export const parseTerminalControlMessage = (raw) => {
         };
         const parsedPixelWidth = asInteger(pixelWidth);
         const parsedPixelHeight = asInteger(pixelHeight);
-        if (parsedPixelWidth !== undefined)
+        if (parsedPixelWidth !== undefined && parsedPixelWidth >= 0) {
             message.pixelWidth = parsedPixelWidth;
-        if (parsedPixelHeight !== undefined)
+        }
+        if (parsedPixelHeight !== undefined && parsedPixelHeight >= 0) {
             message.pixelHeight = parsedPixelHeight;
+        }
         return message;
     }
     throw new Error('Invalid terminal control message');

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) => {
@@ -71,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));

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;