hivehq 2.0.0

package/dist/src/server/ui-auth.js

@@ -0,0 +1,32 @@
+import { randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+import { HIVE_REMOTE_SECRET_HEADER } from './remote-loopback-auth.js';
+export const createUiAuth = () => {
+    const token = randomUUID();
+    // 32 bytes of CSPRNG entropy, fresh every boot. base64url so it travels as a
+    // clean header value. Held only in this closure.
+    const tunnelSecret = randomBytes(32).toString('base64url');
+    const expected = Buffer.from(tunnelSecret);
+    return {
+        getToken() {
+            return token;
+        },
+        validate(input) {
+            return input === token;
+        },
+        isTunnelRequest(request) {
+            const raw = request.headers[HIVE_REMOTE_SECRET_HEADER];
+            const got = Array.isArray(raw) ? raw[0] : raw;
+            if (typeof got !== 'string' || got.length === 0)
+                return false;
+            const candidate = Buffer.from(got);
+            // length check first: timingSafeEqual throws on mismatched lengths, and a
+            // length difference is not secret anyway.
+            if (candidate.length !== expected.length)
+                return false;
+            return timingSafeEqual(candidate, expected);
+        },
+        getTunnelSecret() {
+            return tunnelSecret;
+        },
+    };
+};

package/dist/src/server/version-service.d.ts

@@ -0,0 +1,16 @@
+export interface VersionInfoPayload {
+    current_version: string;
+    install_hint: string;
+    latest_version: string;
+    package_name: string;
+    release_url: string;
+    update_available: boolean;
+}
+export interface VersionService {
+    getVersionInfo: () => Promise<VersionInfoPayload>;
+}
+export declare const compareVersions: (left: string, right: string) => number;
+export declare const createVersionService: (options?: {
+    fetchLatestVersion?: () => Promise<string>;
+    now?: () => number;
+}) => VersionService;

package/dist/src/server/version-service.js

@@ -0,0 +1,72 @@
+import { PACKAGE_NAME, readPackageVersion } from './package-version.js';
+const VERSION_CACHE_MS = 6 * 60 * 60 * 1000;
+const REGISTRY_URL = 'https://registry.npmjs.org/hivehq/latest';
+const parseVersion = (version) => {
+    const [core = '', prerelease = ''] = version.split('-', 2);
+    const [major = 0, minor = 0, patch = 0] = core.split('.').map((part) => Number.parseInt(part, 10));
+    return {
+        core: [major || 0, minor || 0, patch || 0],
+        prerelease,
+    };
+};
+export const compareVersions = (left, right) => {
+    const a = parseVersion(left);
+    const b = parseVersion(right);
+    for (let index = 0; index < 3; index += 1) {
+        const delta = (a.core[index] ?? 0) - (b.core[index] ?? 0);
+        if (delta !== 0)
+            return delta;
+    }
+    if (a.prerelease === b.prerelease)
+        return 0;
+    if (!a.prerelease)
+        return 1;
+    if (!b.prerelease)
+        return -1;
+    return a.prerelease.localeCompare(b.prerelease, undefined, { numeric: true });
+};
+const buildVersionInfo = (currentVersion, latestVersion) => ({
+    current_version: currentVersion,
+    // Show `hive update` as the primary upgrade path now that the subcommand
+    // exists; it prints the npm fallback if its own spawn fails, so users
+    // running on Windows / Linux without a working npm in PATH still recover.
+    install_hint: 'hive update',
+    latest_version: latestVersion,
+    package_name: PACKAGE_NAME,
+    release_url: `https://www.npmjs.com/package/${PACKAGE_NAME}/v/${latestVersion}`,
+    update_available: compareVersions(latestVersion, currentVersion) > 0,
+});
+export const createVersionService = (options = {}) => {
+    const currentVersion = readPackageVersion();
+    const now = options.now ?? Date.now;
+    const fetchLatestVersion = options.fetchLatestVersion ??
+        (async () => {
+            const response = await fetch(REGISTRY_URL, { signal: AbortSignal.timeout(1500) });
+            if (!response.ok)
+                throw new Error(`npm registry returned ${response.status}`);
+            const body = (await response.json());
+            if (typeof body.version !== 'string' || !body.version.trim()) {
+                throw new Error('npm registry response did not include a version');
+            }
+            return body.version;
+        });
+    let cached = null;
+    return {
+        getVersionInfo: async () => {
+            const currentTime = now();
+            if (cached && cached.expiresAt > currentTime)
+                return cached.info;
+            try {
+                const latestVersion = await fetchLatestVersion();
+                const info = buildVersionInfo(currentVersion, latestVersion);
+                cached = { expiresAt: currentTime + VERSION_CACHE_MS, info };
+                return info;
+            }
+            catch {
+                const info = buildVersionInfo(currentVersion, currentVersion);
+                cached = { expiresAt: currentTime + VERSION_CACHE_MS, info };
+                return info;
+            }
+        },
+    };
+};

package/dist/src/server/webhook-notifier.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Outbound completion/attention webhook. The user supplies a single URL (stored
+ * in app_state); the runtime POSTs a small JSON payload on server-side lifecycle
+ * events so they can wire their own Slack / Discord / Feishu / ntfy / Telegram
+ * without Hive taking on a relay, mobile app, or account system.
+ *
+ * Best-effort by design: fire-and-forget with a timeout, all errors swallowed —
+ * a flaky webhook must never block or fail a report/exit. This is a personal,
+ * local-trust setting: the URL is whatever the user typed, and a 127.0.0.1-bound
+ * runtime can reach localhost/intranet, so we only enforce an http(s) scheme and
+ * leave the rest to the operator (documented in the Settings UI).
+ */
+export declare const WEBHOOK_URL_KEY = "notifications.webhook-url";
+export type WebhookEventType = 'report_received' | 'agent_stopped' | 'workflow_finished';
+export interface WebhookEvent {
+    type: WebhookEventType;
+    workspaceId: string;
+    agentId?: string;
+    agentName?: string;
+    summary?: string;
+    at: number;
+}
+export declare const readWebhookUrl: (raw: string | null | undefined) => string | null;
+interface WebhookNotifierOptions {
+    getUrl: () => string | null;
+    /** Injectable for tests; defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    timeoutMs?: number;
+}
+export declare const createWebhookNotifier: ({ getUrl, fetchImpl, timeoutMs, }: WebhookNotifierOptions) => {
+    notify: (event: WebhookEvent) => void;
+};
+export type WebhookNotifier = ReturnType<typeof createWebhookNotifier>;
+export {};

package/dist/src/server/webhook-notifier.js

@@ -0,0 +1,47 @@
+/**
+ * Outbound completion/attention webhook. The user supplies a single URL (stored
+ * in app_state); the runtime POSTs a small JSON payload on server-side lifecycle
+ * events so they can wire their own Slack / Discord / Feishu / ntfy / Telegram
+ * without Hive taking on a relay, mobile app, or account system.
+ *
+ * Best-effort by design: fire-and-forget with a timeout, all errors swallowed —
+ * a flaky webhook must never block or fail a report/exit. This is a personal,
+ * local-trust setting: the URL is whatever the user typed, and a 127.0.0.1-bound
+ * runtime can reach localhost/intranet, so we only enforce an http(s) scheme and
+ * leave the rest to the operator (documented in the Settings UI).
+ */
+export const WEBHOOK_URL_KEY = 'notifications.webhook-url';
+export const readWebhookUrl = (raw) => {
+    const trimmed = raw?.trim();
+    return trimmed ? trimmed : null;
+};
+const isHttpUrl = (raw) => {
+    try {
+        const url = new URL(raw);
+        return url.protocol === 'http:' || url.protocol === 'https:';
+    }
+    catch {
+        return false;
+    }
+};
+export const createWebhookNotifier = ({ getUrl, fetchImpl = fetch, timeoutMs = 5000, }) => {
+    const notify = (event) => {
+        const url = readWebhookUrl(getUrl());
+        if (!url || !isHttpUrl(url))
+            return;
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        void fetchImpl(url, {
+            method: 'POST',
+            headers: { 'content-type': 'application/json' },
+            body: JSON.stringify(event),
+            signal: controller.signal,
+        })
+            .catch(() => {
+            // Personal-trust, best-effort: a dead or slow webhook must not affect
+            // the report/exit path that triggered it.
+        })
+            .finally(() => clearTimeout(timer));
+    };
+    return { notify };
+};

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/worker-output-tracker.d.ts

@@ -0,0 +1,14 @@
+import type { PtyOutputBus } from './pty-output-bus.js';
+export interface WorkerOutputTracker {
+    attach: (workspaceId: string, agentId: string, runId: string, initialOutput: string) => void;
+    closeAll: () => void;
+    detach: (workspaceId: string, agentId: string) => void;
+    getLastPtyLine: (workspaceId: string, agentId: string) => string | null;
+}
+/**
+ * Maintains a headless terminal mirror per active agent run so the team-list
+ * endpoint can report each worker's last output line without requiring a
+ * connected UI viewer. Created on run start (via `attach`) and torn down on
+ * run exit (via `detach`).
+ */
+export declare const createWorkerOutputTracker: (outputBus: PtyOutputBus) => WorkerOutputTracker;

package/dist/src/server/worker-output-tracker.js

@@ -0,0 +1,50 @@
+import { TerminalStateMirror } from './terminal-state-mirror.js';
+const trackerKey = (workspaceId, agentId) => `${workspaceId}:${agentId}`;
+/**
+ * Maintains a headless terminal mirror per active agent run so the team-list
+ * endpoint can report each worker's last output line without requiring a
+ * connected UI viewer. Created on run start (via `attach`) and torn down on
+ * run exit (via `detach`).
+ */
+export const createWorkerOutputTracker = (outputBus) => {
+    const tracked = new Map();
+    const disposeEntry = (entry) => {
+        entry.unsubscribe();
+        entry.mirror.dispose();
+    };
+    return {
+        attach(workspaceId, agentId, runId, initialOutput) {
+            const key = trackerKey(workspaceId, agentId);
+            const existing = tracked.get(key);
+            if (existing) {
+                if (existing.runId === runId)
+                    return;
+                disposeEntry(existing);
+            }
+            const mirror = new TerminalStateMirror();
+            if (initialOutput.length > 0)
+                mirror.write(initialOutput);
+            const unsubscribe = outputBus.subscribe(runId, (chunk) => {
+                mirror.write(chunk);
+            });
+            tracked.set(key, { mirror, runId, unsubscribe });
+        },
+        closeAll() {
+            for (const entry of tracked.values())
+                disposeEntry(entry);
+            tracked.clear();
+        },
+        detach(workspaceId, agentId) {
+            const key = trackerKey(workspaceId, agentId);
+            const entry = tracked.get(key);
+            if (!entry)
+                return;
+            disposeEntry(entry);
+            tracked.delete(key);
+        },
+        getLastPtyLine(workspaceId, agentId) {
+            const entry = tracked.get(trackerKey(workspaceId, agentId));
+            return entry ? entry.mirror.lastPtyLine() : null;
+        },
+    };
+};

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", "hermes"];
+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', 'hermes'];
+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;