hivehq 2.0.0

package/dist/src/server/fs-pick-folder.d.ts

@@ -0,0 +1,25 @@
+import { type ExecFileOptions } from 'node:child_process';
+import { type FsProbeResponse } from './fs-browse.js';
+type SpawnResult = {
+    stderr: string;
+    stdout: string;
+    status: number | null;
+    signal: string | null;
+    timedOut: boolean;
+    spawnError: NodeJS.ErrnoException | null;
+};
+export type RunPickCommand = (command: string, args: string[], options: ExecFileOptions) => Promise<SpawnResult>;
+export interface PickFolderOptions {
+    now?: () => number;
+    platform?: NodeJS.Platform;
+    runCommand?: RunPickCommand;
+}
+export interface PickFolderResponse {
+    canceled: boolean;
+    error: string | null;
+    path: string | null;
+    probe: FsProbeResponse | null;
+    supported: boolean;
+}
+export declare const pickFolder: (options?: PickFolderOptions) => Promise<PickFolderResponse>;
+export {};

package/dist/src/server/fs-pick-folder.js

@@ -0,0 +1,115 @@
+import { execFile } from 'node:child_process';
+import { probeDirectory } from './fs-browse.js';
+// macOS Cocoa returns -1743 when the user clicks Cancel in `choose folder`.
+// osascript maps that to exit code 1 with the message on stderr.
+const MACOS_CANCEL_PATTERNS = [/-128/, /-1743/, /user canceled/i, /execution error/i];
+// zenity documents exit code 1 on Cancel. kdialog uses exit code 1 as well.
+const LINUX_CANCEL_EXIT_CODES = new Set([1]);
+// Cap how long we'll wait for a single picker invocation. A reasonable
+// modal-dialog dwell time is well under this — the cap exists to catch
+// genuinely wedged pickers (PowerShell startup hang under restricted
+// execution policy, zenity hung on a missing DBus, osascript blocked on
+// the macOS Accessibility prompt) so the HTTP request returns instead
+// of pinning a connection forever.
+const PICKER_TIMEOUT_MS = 5 * 60 * 1000;
+const defaultRunCommand = (command, args, options) => new Promise((resolve) => {
+    const child = execFile(command, args, options, (error, stdout, stderr) => {
+        const errno = error;
+        const timedOut = !!errno?.killed && errno?.signal === 'SIGTERM';
+        // execFile surfaces ENOENT when the binary is missing; keep the raw errno
+        // so the caller can distinguish "command not installed" from "user cancel".
+        resolve({
+            stderr: String(stderr ?? ''),
+            stdout: String(stdout ?? ''),
+            status: typeof errno?.code === 'number' ? errno.code : (child.exitCode ?? 0),
+            signal: typeof errno?.signal === 'string' ? errno.signal : null,
+            spawnError: errno && typeof errno.code === 'string' ? errno : null,
+            timedOut,
+        });
+    });
+});
+const emptyResponse = (overrides = {}) => ({
+    canceled: false,
+    error: null,
+    path: null,
+    probe: null,
+    supported: true,
+    ...overrides,
+});
+const finalizeWithProbe = async (path) => {
+    // The OS-native folder picker is itself a user-authorization surface
+    // — sandboxing again here would reject any drive other than the one
+    // hosting `$HOME` (a common Windows case: `D:\projects`, `E:\code`).
+    // The in-browser FS tree (fs-browse.ts:browseDirectory) keeps its
+    // own sandbox; only the native picker bypasses it.
+    const probe = await probeDirectory(path, { enforceSandbox: false });
+    if (!probe.ok || !probe.is_dir) {
+        return emptyResponse({
+            error: 'Selected path is not a directory.',
+            path,
+            probe,
+        });
+    }
+    return emptyResponse({ path: probe.path, probe });
+};
+const macOsPick = async (run) => {
+    const script = 'POSIX path of (choose folder with prompt "Select Hive workspace")';
+    const result = await run('osascript', ['-e', script], { timeout: PICKER_TIMEOUT_MS });
+    if (result.spawnError?.code === 'ENOENT') {
+        return emptyResponse({ error: 'osascript is unavailable on this host.', supported: false });
+    }
+    if (result.timedOut) {
+        return emptyResponse({ error: 'Folder picker timed out before a folder was selected.' });
+    }
+    const combinedStderr = result.stderr.toLowerCase();
+    if (result.status !== 0) {
+        if (MACOS_CANCEL_PATTERNS.some((re) => re.test(combinedStderr))) {
+            return emptyResponse({ canceled: true });
+        }
+        // Any non-zero exit code without stdout is treated as cancel rather than a
+        // hard failure — the user is just closing the dialog.
+        if (result.stdout.trim().length === 0)
+            return emptyResponse({ canceled: true });
+    }
+    const picked = result.stdout.trim().replace(/\/$/, '');
+    if (picked.length === 0)
+        return emptyResponse({ canceled: true });
+    return finalizeWithProbe(picked);
+};
+const linuxPick = async (run) => {
+    const result = await run('zenity', ['--file-selection', '--directory', '--title=Select Hive workspace'], { timeout: PICKER_TIMEOUT_MS });
+    if (result.spawnError?.code === 'ENOENT') {
+        return emptyResponse({
+            error: 'zenity not installed. Install zenity or use Advanced: paste path.',
+            supported: false,
+        });
+    }
+    if (result.timedOut) {
+        return emptyResponse({ error: 'Folder picker timed out before a folder was selected.' });
+    }
+    if (result.status !== 0 && LINUX_CANCEL_EXIT_CODES.has(result.status ?? 0)) {
+        return emptyResponse({ canceled: true });
+    }
+    const picked = result.stdout.trim();
+    if (picked.length === 0)
+        return emptyResponse({ canceled: true });
+    return finalizeWithProbe(picked);
+};
+export const pickFolder = async (options = {}) => {
+    const platform = options.platform ?? process.platform;
+    const run = options.runCommand ?? defaultRunCommand;
+    if (platform === 'darwin')
+        return macOsPick(run);
+    if (platform === 'linux')
+        return linuxPick(run);
+    if (platform === 'win32') {
+        return emptyResponse({
+            error: 'Native folder picker is disabled on Windows. Use Browse server filesystem or paste path.',
+            supported: false,
+        });
+    }
+    return emptyResponse({
+        error: 'Native folder picker not supported on this platform. Use Advanced: paste path.',
+        supported: false,
+    });
+};

package/dist/src/server/fs-sandbox.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Root directory the FS-browse API is allowed to reveal when sandboxing is
+ * enabled. Tests and remote/headless setups can set `HIVE_FS_BROWSE_ROOT`.
+ * Normal Windows runs skip this sandbox root and browse from the virtual
+ * "This PC" drive list; POSIX sandboxed browsing defaults to `$HOME`.
+ */
+export declare const getFsBrowseRoot: () => string;
+export declare const hasFsBrowseRootOverride: () => boolean;
+/**
+ * True when `candidatePath` is `rootPath` itself or a descendant of it.
+ * Uses `path.relative` + separator check so Windows back-slashes and drive
+ * boundaries are handled correctly — identical shape to kanban's
+ * isPathWithinRoot so the semantics match a project we already trust.
+ */
+export declare const isPathWithinRoot: (rootPath: string, candidatePath: string) => boolean;

package/dist/src/server/fs-sandbox.js

@@ -0,0 +1,56 @@
+import { homedir } from 'node:os';
+import { isAbsolute, relative, resolve, sep } from 'node:path';
+import { realpathNative } from './path-canonicalization.js';
+/**
+ * Root directory the FS-browse API is allowed to reveal when sandboxing is
+ * enabled. Tests and remote/headless setups can set `HIVE_FS_BROWSE_ROOT`.
+ * Normal Windows runs skip this sandbox root and browse from the virtual
+ * "This PC" drive list; POSIX sandboxed browsing defaults to `$HOME`.
+ */
+export const getFsBrowseRoot = () => {
+    const override = process.env.HIVE_FS_BROWSE_ROOT;
+    const root = override && override.length > 0 ? resolve(override) : resolve(homedir());
+    try {
+        return realpathNative(root);
+    }
+    catch {
+        return root;
+    }
+};
+export const hasFsBrowseRootOverride = () => (process.env.HIVE_FS_BROWSE_ROOT ?? '').length > 0;
+const isResolvedPathWithinRoot = (rootPath, candidatePath) => {
+    if (candidatePath === rootPath)
+        return true;
+    const rel = relative(rootPath, candidatePath);
+    return rel !== '..' && !rel.startsWith(`..${sep}`) && !isAbsolute(rel);
+};
+/**
+ * True when `candidatePath` is `rootPath` itself or a descendant of it.
+ * Uses `path.relative` + separator check so Windows back-slashes and drive
+ * boundaries are handled correctly — identical shape to kanban's
+ * isPathWithinRoot so the semantics match a project we already trust.
+ */
+export const isPathWithinRoot = (rootPath, candidatePath) => {
+    const lexicalRoot = resolve(rootPath);
+    const lexicalCandidate = resolve(candidatePath);
+    let resolvedRoot = lexicalRoot;
+    let resolvedCandidate = lexicalCandidate;
+    try {
+        resolvedRoot = realpathNative(resolvedRoot);
+    }
+    catch {
+        // Missing / inaccessible roots are handled by the caller's readdir/stat path.
+    }
+    try {
+        resolvedCandidate = realpathNative(resolvedCandidate);
+    }
+    catch {
+        // Non-existent children still need lexical sandboxing for "create later"
+        // probes; existing symlinks/junctions use the realpath branch above.
+        if (isResolvedPathWithinRoot(lexicalRoot, lexicalCandidate)) {
+            resolvedRoot = lexicalRoot;
+            resolvedCandidate = lexicalCandidate;
+        }
+    }
+    return isResolvedPathWithinRoot(resolvedRoot, resolvedCandidate);
+};

package/dist/src/server/hive-team-guidance.d.ts

@@ -0,0 +1,39 @@
+import type { AgentSummary } from '../shared/types.js';
+import { type FeatureFlags } from './feature-flags.js';
+import { type WorkflowCliPolicy } from './workflow-cli-policy.js';
+/**
+ * Tail reminder appended to every message that flows INTO the orchestrator
+ * (worker reports, worker status updates, user chat input). Re-anchors the
+ * role + dispatch syntax after the agent's CLI internally compacts the
+ * conversation transcript (`/compact` in CC, auto-summarize in Codex, etc.)
+ * and forgets the original startup instructions.
+ *
+ * Format choice (XML envelope, position at message tail, action-menu wording)
+ * follows a peer LLM-agent review: static `[Hive]` prefixes get filtered as
+ * banner noise after a few occurrences, but `<...-system-reminder>` tags
+ * mirror the out-of-band envelope LLMs are trained to attend to; placement
+ * at the tail (right before the agent's reply turn) maximizes recency
+ * weighting; phrasing as a short action menu is more actionable than abstract
+ * identity restatement. Kept deliberately SHORT — the full command syntax and
+ * the workflow DSL live in `.hive/PROTOCOL.md`, which agents re-read on demand.
+ * A long banner on every turn is itself the noise this envelope exists to beat.
+ */
+export declare const buildOrchestratorReminderTail: ({ workflowsEnabled }: FeatureFlags) => string;
+/**
+ * Tail reminder appended to dispatches sent TO a worker. Reinforces the
+ * worker identity (so the agent does not regress into its normal CLI
+ * persona that would call nested subagents) plus the exact report syntax
+ * with dispatch_id pre-bound.
+ */
+export declare const buildWorkerReminderTail: (dispatchId: string) => string;
+export declare const getHiveTeamRules: (agent: Pick<AgentSummary, "role">, flags?: FeatureFlags) => readonly string[];
+/**
+ * Workspace-local protocol cheat sheet written to `.hive/PROTOCOL.md`. Agents
+ * are explicitly trained to look at project root markdown when confused, so
+ * keeping a single canonical doc next to `.hive/tasks.md` doubles as a
+ * "cat-recover" path when both the startup prompt and the in-message
+ * reminders fail to anchor. This is also the single home of the full command
+ * syntax and the workflow DSL reference — the always-on injections only carry
+ * the lean core rules and point here.
+ */
+export declare const buildProtocolDoc: (cliPolicy?: WorkflowCliPolicy, flags?: FeatureFlags) => string;

package/dist/src/server/hive-team-guidance.js

@@ -0,0 +1,295 @@
+import { FEATURE_FLAGS_ALL_OFF } from './feature-flags.js';
+import { DEFAULT_WORKFLOW_CLI_POLICY } from './workflow-cli-policy.js';
+/**
+ * Tail reminder appended to every message that flows INTO the orchestrator
+ * (worker reports, worker status updates, user chat input). Re-anchors the
+ * role + dispatch syntax after the agent's CLI internally compacts the
+ * conversation transcript (`/compact` in CC, auto-summarize in Codex, etc.)
+ * and forgets the original startup instructions.
+ *
+ * Format choice (XML envelope, position at message tail, action-menu wording)
+ * follows a peer LLM-agent review: static `[Hive]` prefixes get filtered as
+ * banner noise after a few occurrences, but `<...-system-reminder>` tags
+ * mirror the out-of-band envelope LLMs are trained to attend to; placement
+ * at the tail (right before the agent's reply turn) maximizes recency
+ * weighting; phrasing as a short action menu is more actionable than abstract
+ * identity restatement. Kept deliberately SHORT — the full command syntax and
+ * the workflow DSL live in `.hive/PROTOCOL.md`, which agents re-read on demand.
+ * A long banner on every turn is itself the noise this envelope exists to beat.
+ */
+export const buildOrchestratorReminderTail = ({ workflowsEnabled }) => {
+    const body = 'You are the Hive Orchestrator. Reply with one of: ' +
+        '(a) `team send "<worker-name>" "<task>"` to dispatch — run `team list` first if the roster may have changed since your last view (Hive does not push membership changes; stale names fail). ' +
+        'If no worker fits or the roster is empty, `team spawn <role> [--cli claude|codex|opencode|gemini|hermes]` to create one (add `--ephemeral` for a one-shot), then dispatch; do not ask the user to add workers. ' +
+        '(b) `team cancel --dispatch <id> "<reason>"` to close an obsolete dispatch. ' +
+        (workflowsEnabled
+            ? '(c) `team workflow run --stdin` to fan out across 3+ workers or run a staged review→fix — never a loop of `team send` (no barrier, no UI group, no stop button). (d) plain text to the user. '
+            : '(c) plain text to the user. ') +
+        `Do not use your CLI's own subagent${workflowsEnabled ? ' / workflow' : ''} tools — they run inside your CLI, bypass Hive, and never reach the UI or \`team list\`. ` +
+        (workflowsEnabled
+            ? 'Full command syntax and the workflow DSL: re-read `.hive/PROTOCOL.md`.'
+            : 'Full command syntax: re-read `.hive/PROTOCOL.md`.');
+    return `<hive-system-reminder>\n${body}\n</hive-system-reminder>`;
+};
+/**
+ * Tail reminder appended to dispatches sent TO a worker. Reinforces the
+ * worker identity (so the agent does not regress into its normal CLI
+ * persona that would call nested subagents) plus the exact report syntax
+ * with dispatch_id pre-bound.
+ */
+export const buildWorkerReminderTail = (dispatchId) => '<hive-system-reminder>\n' +
+    `You are a Hive Worker. Do not launch nested CLI subagents — finish the task yourself. When the task is done, blocked, or has failed, report with: \`team report "<result>" --dispatch ${dispatchId}\` (or \`team report --stdin --dispatch ${dispatchId}\` for long bodies).\n` +
+    '</hive-system-reminder>';
+/**
+ * Core, always-on orchestrator rules. Injected at startup, on crash recovery,
+ * and on restart env-sync. Deliberately free of multi-line code skeletons —
+ * those are reference material that lives in `.hive/PROTOCOL.md` (see
+ * WORKFLOW_DSL_REFERENCE) so the recovery / env-sync paths re-anchor identity
+ * and dispatch discipline without re-injecting a wall of example JS.
+ */
+const CORE_ORCHESTRATOR_RULES = [
+    'A Hive worker is a real CLI agent shown as a card on the right — NOT a subagent of your own CLI.',
+    'Dispatch against the current roster: re-run `team list` before a `team send` whenever a user reply or one of your own dispatches/cancels has happened since your last list. Hive never pushes membership changes, so do not dispatch from a remembered roster — a renamed or removed worker fails.',
+    'Small, low-risk tasks you can finish in a couple of minutes: do them yourself; do not dispatch for the sake of form. Reach for `team send` when the work needs parallelism, long execution, independent review/test, a dedicated role, or the user explicitly asked for a worker.',
+    'If exactly one worker is available, dispatch to it directly with `team send <worker-name> "<task>"` — do not bounce the choice back to the user.',
+    'When the user says "have a worker do X", dispatch it with `team send <worker-name> "<task>"`.',
+    'If the roster is empty or lacks the role the task needs, build the team yourself: `team spawn <role> [--name <n>] [--cli claude|codex|opencode|gemini|hermes]`, then immediately dispatch. Do not stop to ask the user to add members — that call is yours.',
+    '`team spawn` is PERSISTENT by default (a normal member that stays in the workspace); add `--ephemeral` for a one-shot worker that auto-dismisses after its first `team report`. Rule of thumb: will you reuse this role in the next 10 minutes? Yes → persistent; no → `--ephemeral`.',
+    'When the user cancels or changes direction on an open dispatch, close it explicitly with `team cancel --dispatch <id> "<reason>"` — do not just say "cancel" in prose.',
+    'Each `team send` opens a SEPARATE dispatch with its own pending count and its own required report — it is not a way to tack context onto a dispatch already in flight. Send the same worker twice and it owes you TWO reports; one report closes only one dispatch (the one its `--dispatch <id>` names, or the oldest open one if the flag is omitted), so the other stays open and the worker is pinned on `working`. To change or extend an in-flight task, `team cancel --dispatch <id> "<reason>"` the stale dispatch and re-send the whole task, or wait for the worker to report and dispatch the follow-up after.',
+    'Only orchestrators can add memory directly; workers should report durable findings for the orchestrator or Dream to capture. Search memory before adding: use `team memory search "<query>"` to avoid duplicates. Use `team memory add "<body>"` only for rare, evidence-backed workspace facts, decisions, and pitfalls that should help future Hive agents across sessions. Nothing worth saving is a normal outcome; do not add memory just to prove you used it. Use `team memory forget <memory-id>` only to archive obsolete memory.',
+    "Never substitute your CLI's own subagent / workflow tools (e.g. Task / Explore / Workflow / Agent) for Hive workers or Hive workflows — they run inside your CLI process, bypass Hive's PTY fleet, never appear in the UI or `team list`, and the stop button cannot reach them.",
+    'In `team list`, `last_pty_line` is raw terminal output (stdout / help / control-sequence noise), NOT a worker\'s report. A real report arrives only as an injected "report from @<name>" / "status from @<name>" system message — treat only those as replies.',
+];
+/**
+ * Workflow-authoring rule — only injected when the experimental workflow
+ * feature is ENABLED. When workflows are off the orchestrator is never told
+ * to reach for `team workflow`, which keeps its always-on prompt lean and
+ * avoids it firing a command the runtime will reject.
+ */
+const WORKFLOW_ORCHESTRATOR_RULES = [
+    'Choosing to use a workflow is YOUR call, judged from the task\'s shape — the user describes what they want in plain language and will not (and need not) ask for a "workflow" by name. When a task fans out across 3+ workers, needs a staged review→fix, or loops until results converge, author the workflow script yourself from the task and fire it with ONE `team workflow run --stdin` — decide this on your own, do not wait to be told, and do not approximate it with a loop of `team send` (no barrier, no UI grouping, no stop button). The DSL and ready-made patterns are in `.hive/PROTOCOL.md`.',
+];
+/**
+ * Auto-staff rule — only injected when the experimental auto-staff feature is
+ * ENABLED (ON by default). Grants + encourages the orchestrator to size the
+ * team to the task instead of adding workers one at a time. The shared-FS +
+ * ephemeral notes are operating instructions (Hive gives every worker the same
+ * workspace root with no per-worker isolation), not optional caution: without
+ * them parallel coders overwrite each other.
+ *
+ * The text adapts to whether workflows are ALSO on: there is no batch `team
+ * spawn` syntax (one command per member), so it says exactly that; and when
+ * workflows are available it defers one-shot batch fan-out to `team workflow
+ * run` so the two experiments don't give the orchestrator competing advice.
+ */
+const buildAutostaffRule = (workflowsEnabled) => 'You may size the team to the task instead of adding workers one at a time: judge what mix of roles runs it fastest (e.g. a couple of coders plus a reviewer and a tester) and issue the individual `team spawn <role> --ephemeral` commands you need up front — one command per member (there is no batch form), this call is yours, do not ask the user. Match the count to the work: more agents is not faster once they would collide or sit idle. CRITICAL: all workers share the same workspace files with NO per-worker isolation, so split the work so no two agents touch the same files/modules. Use `--ephemeral` so this task-scoped staff auto-dismiss after reporting and do not pile up.' +
+    (workflowsEnabled
+        ? ' When the work is a one-shot fan-out across 3+ workers or a staged review→fix that runs to completion, prefer `team workflow run` (barrier, phase tree, stop button) over a batch of `team spawn`; reserve up-front staffing for a standing team you direct interactively across several turns.'
+        : '');
+const orchestratorRules = ({ workflowsEnabled, autostaffEnabled, }) => [
+    ...CORE_ORCHESTRATOR_RULES,
+    ...(workflowsEnabled ? WORKFLOW_ORCHESTRATOR_RULES : []),
+    ...(autostaffEnabled ? [buildAutostaffRule(workflowsEnabled)] : []),
+];
+const WORKER_RULES = [
+    'You are a real CLI worker shown as a card on the right in Hive — not a subagent of your own CLI.',
+    "Do not call `team send`, and do not launch your own CLI's subagent tools to do the work for you — finish it yourself.",
+    'When an assigned task is done, blocked, or has failed, you MUST report to the Orchestrator with `team report`.',
+    'When you have no active dispatch and only want to report readiness, environment, or status, use `team status "<state>"`.',
+    'Use `team recall "<query>"` when prior team messages or reports may contain useful evidence.',
+    'Use `team memory search "<query>"` to inspect active workspace memory. Include durable findings in `team report`; workers cannot add or forget memory.',
+    '`team --help` only prints command syntax — it is NOT a way to report; its output never reaches the Orchestrator. You still owe a real `team report` / `team status` afterward.',
+    'If `team report` / `team status` errors, it also prints USAGE — fix the arguments per USAGE and retry; do not use `team --help` as a stand-in for reporting.',
+];
+export const getHiveTeamRules = (agent, flags = FEATURE_FLAGS_ALL_OFF) => (agent.role === 'orchestrator' ? orchestratorRules(flags) : WORKER_RULES);
+const renderRules = (rules) => rules.map((line) => `- ${line}`).join('\n');
+/**
+ * The workflow DSL teaching: agent()/parallel()/pipeline() semantics, the
+ * agent() opts surface, runnable skeletons, and the canonical patterns. This
+ * is REFERENCE material — it lives only in `.hive/PROTOCOL.md`, never in the
+ * per-message reminder or the recovery/env-sync injections, so the always-on
+ * paths stay lean. The orchestrator is pointed here by the core rules and the
+ * reminder tail whenever it needs to author a `team workflow run`.
+ */
+const WORKFLOW_DSL_REFERENCE = `## Workflow DSL (\`team workflow run --stdin\`)
+
+Use a workflow when a task fans out beyond a single dispatch: 3+ parallel
+workers, a staged review→fix, or a loop until results converge. The DSL mirrors
+Claude Code's Workflow tool, but every \`agent()\` runs on Hive's PTY fleet — a
+real CLI process — not an in-CLI API subagent. \`team workflow run\` is the only
+entry into the Hive runtime; never use your CLI's own Workflow/Agent tool.
+
+Host functions injected into the script: \`agent(prompt, opts)\`,
+\`parallel(thunks)\`, \`pipeline(items, ...stages)\`, \`phase(title)\`,
+\`log(msg)\`, plus the \`args\` global.
+
+\`agent(prompt, opts)\` opts: \`{ agentType?: "coder"|"reviewer"|"tester"|"custom"|<custom-role-name>, cli?: "claude"|"codex"|"opencode"|"gemini"|"hermes", model?: string, outputSchema?: object, label?: string, timeoutMs?: number }\` — other fields are silently ignored. \`agentType\` also accepts the name of a workspace custom role template (case-insensitive); a typo throws rather than silently falling back to coder. \`model\` is passed through to the worker launch config (\`--model <id>\`), so a 100-way fan-out can use a cheap model and the synthesizer a strong one. \`outputSchema\` makes \`agent()\` resolve to a parsed object instead of a string: the worker is told to end its report with a fenced \`\`\`json block whose keys match the schema. On a parse miss it falls back to \`{ text: "<raw report>" }\`, so ALWAYS treat a missing field as the SAFE default (never assume success). The worker auto-dismisses when its \`agent()\` call resolves — you never dismiss it.
+
+\`parallel()\` takes an array of THUNKS (\`() => agent(...)\`), NOT already-started promises: \`parallel([agent(...), agent(...)])\` degrades to unordered concurrency counted as a single step (a no-op grouping), because the promises already started at construction time. \`pipeline(items, ...stages)\` stages are also functions, shape \`(prev, item, i) => agent(...)\`.
+
+\`log("...")\` writes one narrator line — stored in the DB, shown when the run row is expanded in the Drawer, and its last 8 lines are spliced into the completion reminder sent back to you. Use it for a readable progress summary, e.g. \`log('Discovered 47 endpoints')\`.
+
+Runtime limits: each run defaults to at most 1000 \`agent()\` calls and 60 minutes wall-clock; the concurrency cap is \`min(16, cores-2)\` and parallel/pipeline queue against it automatically. Override in \`meta\`, e.g. \`meta = { name, description, maxAgentCalls: 50, maxDurationMs }\`.
+
+\`meta\` must be a pure literal (no variables). Scripts are JS, not TS (type annotations error). The body may use top-level \`await\` and a trailing \`return\`.
+
+Minimal script (heredoc into \`--stdin\`):
+\`\`\`
+export const meta = { name: 'review-changes', description: 'review + tests' }
+phase('Find')
+const issues = await agent('Run \`git diff\` and list any potential bugs.', { agentType: 'reviewer', label: 'review' })
+phase('Verify')
+const tests = await agent(\`Write tests for: \${issues}\`, { agentType: 'tester', label: 'verify' })
+return { issues, tests }
+\`\`\`
+
+Parallel fan-out + multi-vendor mix (Hive's signature — several CLIs in one run):
+\`\`\`
+export const meta = { name: 'parallel-audit', description: 'audit N files in parallel' }
+const files = ['src/a.ts', 'src/b.ts', 'src/c.ts']
+phase('Audit')
+const reports = await parallel(files.map((f) => () => agent(\`Audit \${f} for security bugs.\`, { agentType: 'reviewer', cli: 'codex', label: \`audit:\${f}\` })))
+phase('Synthesize')
+return await agent(\`Synthesize: \${reports.filter(Boolean).join('\\n---\\n')}\`, { agentType: 'reviewer', cli: 'claude', label: 'synth' })
+\`\`\`
+
+Passing args (so a saved script is reusable instead of hard-coding values):
+\`\`\`
+team workflow run --stdin --args '["src/a.ts","src/b.ts"]' <<'EOF'
+export const meta = { name: 'audit', description: 'd' }
+phase('Audit')
+return await parallel(args.map((f) => () => agent(\`Audit \${f}\`)))
+EOF
+\`\`\`
+\`--args\` takes JSON (\`'{"q":1}'\`, \`'["a","b"]'\`, \`'"plain"'\`); omitted → \`args\` is \`undefined\`.
+
+Patterns worth knowing:
+- **loop-until-dry** — stop after K empty rounds; more robust than \`while (count < N)\`, which stalls on the hard-to-find tail:
+\`\`\`
+const seen = new Set(), confirmed = []
+let dry = 0
+while (dry < 2) {
+  const found = await agent('Find any potential bugs not in: ' + [...seen].join(', '))
+  const fresh = found.split('\\n').filter((b) => b.trim() && !seen.has(b))
+  if (!fresh.length) { dry++; continue }
+  dry = 0
+  fresh.forEach((b) => { seen.add(b); confirmed.push(b) })
+}
+return confirmed
+\`\`\`
+- **judge panel** — N independent verifiers per finding; majority confirms. \`outputSchema\` makes each vote a typed object instead of fragile yes/no string-matching. Note the safe default: a parse miss has no \`refuted\` key, so \`v.refuted === false\` is false → the finding stays refuted and a malformed reply can never flip it to "confirmed":
+\`\`\`
+phase('Verify')
+const votes = await parallel([
+  () => agent(\`Try to REFUTE: \${claim}. Default refuted=true if uncertain.\`, { outputSchema: { refuted: 'boolean' } }),
+  () => agent(\`Independently judge: \${claim}.\`, { outputSchema: { refuted: 'boolean' } }),
+  () => agent(\`Repro test: \${claim}. Did it reproduce?\`, { outputSchema: { refuted: 'boolean' } }),
+])
+// Only an explicit refuted:false counts as "survived"; missing/unparseable stays safely refuted.
+const real = votes.filter((v) => v && v.refuted === false).length >= 2
+\`\`\`
+- **pipeline** — multi-item, multi-stage, no barrier between stages (item A can be in stage 3 while item B is in stage 1); wall-clock = slowest single item, not sum-of-slowest-per-stage. Each stage gets \`(prevResult, originalItem, index)\`; a stage that throws drops that item to null and skips its remaining stages.
+
+On completion Hive injects \`<hive-system-reminder>Hive workflow ... finished: status=...</hive-system-reminder>\` carrying each step's short report; synthesize that back to the user. Full per-agent transcripts: \`team workflow show <run-id>\`.`;
+/**
+ * Workspace-local protocol cheat sheet written to `.hive/PROTOCOL.md`. Agents
+ * are explicitly trained to look at project root markdown when confused, so
+ * keeping a single canonical doc next to `.hive/tasks.md` doubles as a
+ * "cat-recover" path when both the startup prompt and the in-message
+ * reminders fail to anchor. This is also the single home of the full command
+ * syntax and the workflow DSL reference — the always-on injections only carry
+ * the lean core rules and point here.
+ */
+export const buildProtocolDoc = (cliPolicy = DEFAULT_WORKFLOW_CLI_POLICY, flags = FEATURE_FLAGS_ALL_OFF) => {
+    const { workflowsEnabled } = flags;
+    // The `team workflow …` subcommands + the DSL reference + the per-workspace
+    // CLI-policy section only appear when the experimental workflow feature is
+    // ON. While off, the orchestrator's canonical reference never mentions
+    // workflows (leaner prompt) and never points at a command the runtime rejects.
+    const workflowCliCommands = workflowsEnabled
+        ? [
+            "- `team workflow run --stdin` — fire a multi-agent workflow; pass JS source via stdin. Add `--args '<JSON>'` to set the script's `args` global.",
+            '- `team workflow run --inline "<source>"` — same, single-arg form',
+            '- `team workflow stop <run-id>` — cancel a running workflow',
+            '- `team workflow show <run-id>` — full per-agent transcript (status, phase, label, prompt, full reportText) — use this when the truncated completion reminder is not enough',
+            '- `team workflow schedule --cron "<5-field cron>" --name <n> --stdin` — register a RECURRING run; pass the same JS source you would give `run`. The source is persisted so cron can fire it with no orchestrator present. The UI can pause / delete schedules but never create them — scheduling is your job.',
+        ]
+        : [];
+    const workflowSections = workflowsEnabled
+        ? [
+            WORKFLOW_DSL_REFERENCE,
+            '',
+            '## Workflow agent CLIs (this workspace)',
+            '',
+            'When a workflow `agent()` omits `cli` it launches a worker on the default',
+            'CLI below; an explicit `cli:` must be one of the allowed CLIs or the run',
+            'fails with a clear error. (Custom role templates keep their own configured',
+            'CLI and are exempt from the allowlist.)',
+            '',
+            `- Default CLI when \`cli\` is omitted: **${cliPolicy.default}**`,
+            `- Allowed CLIs for \`cli\`: ${cliPolicy.allowed.join(', ')}`,
+            '',
+        ]
+        : [];
+    return [
+        '# Hive Team Protocol',
+        '',
+        'This file is auto-generated by Hive on every workspace open. If you',
+        '(the agent) lost context after `/compact` or an internal summarization,',
+        're-read `.hive/PROTOCOL.md` (POSIX: `cat`, Windows cmd: `type`, PowerShell:',
+        '`Get-Content`) to re-anchor.',
+        '',
+        '## You are running inside Hive',
+        '',
+        'Hive is a multi-CLI-agent workbench. Each agent in this workspace is a',
+        'real CLI process (Claude Code / Codex / OpenCode / Gemini). All',
+        'inter-agent communication goes through the `team` CLI binary on your',
+        'PATH.',
+        '',
+        '## Roles',
+        '',
+        '- **Orchestrator** — talks to the user, plans tasks, dispatches to workers',
+        '- **Worker** (Coder / Reviewer / Tester / custom) — executes one assigned task and reports back',
+        '',
+        '## `team` CLI — orchestrator',
+        '',
+        '- `team list` — show workspace members and their status',
+        '- `team recall "<query>" [--limit <n>] [--window <n>]` — search prior team messages/reports in this workspace',
+        '- `team memory add "<body>" [--kind fact|preference|decision|pitfall|procedure_ref] [--tag <tag>]` — save durable workspace memory (orchestrator entries become active)',
+        '- `team memory show <memory-id>` — inspect a memory entry and evidence snapshots',
+        '- `team memory search "<query>" [--limit <n>]` — search active workspace memory',
+        '- `team memory forget <memory-id>` — archive obsolete memory (orchestrator only; does not physically delete evidence)',
+        '- `team send "<worker-name>" "<task>"` — dispatch to a worker by name (never id)',
+        '- `team spawn <role> [--name <name>] [--cli claude|codex|opencode|gemini|hermes]` — create a PERSISTENT member when none fits (or when the roster is empty)',
+        '- `team spawn <role> --ephemeral [other-flags]` — create a one-shot worker that auto-dismisses after its first `team report`',
+        '- `team dismiss <worker-name>` — remove an ephemeral worker you spawned',
+        '- `team cancel --dispatch <id> "<reason>"` — cancel an obsolete open dispatch',
+        ...workflowCliCommands,
+        '',
+        '## `team` CLI — worker',
+        '',
+        '- `team recall "<query>" [--limit <n>] [--window <n>]` — search prior team messages/reports in this workspace',
+        '- `team memory show <memory-id>` — inspect a memory entry and evidence snapshots',
+        '- `team memory search "<query>" [--limit <n>]` — search active workspace memory',
+        '- `team report "<result>" --dispatch <id>` — report task outcome',
+        '- `team report --stdin --dispatch <id>` — same, body from stdin (pipe content in via your shell — POSIX heredoc, Windows cmd `type file |`, PowerShell `Get-Content -Raw -Encoding utf8 file |`, or portable stdin redirection `< file`)',
+        '- `team status "<state>"` — update orchestrator when no dispatch is active',
+        '',
+        '## Orchestrator rules',
+        '',
+        renderRules(orchestratorRules(flags)),
+        '',
+        '## Worker rules',
+        '',
+        renderRules(WORKER_RULES),
+        '',
+        ...workflowSections,
+        '## In-message reminders',
+        '',
+        'Every message you receive in this workspace ends with a short',
+        '`<hive-system-reminder>` block carrying the minimum syntax you need',
+        'right now. If something is missing from that block, re-read this file.',
+        '',
+    ].join('\n');
+};

package/dist/src/server/http-errors.d.ts

@@ -0,0 +1,22 @@
+export declare class HttpError extends Error {
+    readonly statusCode: number;
+    constructor(statusCode: number, message: string);
+}
+export declare class PtyInactiveError extends HttpError {
+    constructor(message: string);
+}
+export declare class UnauthorizedError extends HttpError {
+    constructor(message: string);
+}
+export declare class ForbiddenError extends HttpError {
+    constructor(message: string);
+}
+export declare class BadRequestError extends HttpError {
+    constructor(message: string);
+}
+export declare class PayloadTooLargeError extends HttpError {
+    constructor(message: string);
+}
+export declare class ConflictError extends HttpError {
+    constructor(message: string);
+}

package/dist/src/server/http-errors.js

@@ -0,0 +1,44 @@
+export class HttpError extends Error {
+    statusCode;
+    constructor(statusCode, message) {
+        super(message);
+        this.name = 'HttpError';
+        this.statusCode = statusCode;
+    }
+}
+export class PtyInactiveError extends HttpError {
+    constructor(message) {
+        super(409, message);
+        this.name = 'PtyInactiveError';
+    }
+}
+export class UnauthorizedError extends HttpError {
+    constructor(message) {
+        super(401, message);
+        this.name = 'UnauthorizedError';
+    }
+}
+export class ForbiddenError extends HttpError {
+    constructor(message) {
+        super(403, message);
+        this.name = 'ForbiddenError';
+    }
+}
+export class BadRequestError extends HttpError {
+    constructor(message) {
+        super(400, message);
+        this.name = 'BadRequestError';
+    }
+}
+export class PayloadTooLargeError extends HttpError {
+    constructor(message) {
+        super(413, message);
+        this.name = 'PayloadTooLargeError';
+    }
+}
+export class ConflictError extends HttpError {
+    constructor(message) {
+        super(409, message);
+        this.name = 'ConflictError';
+    }
+}

package/dist/src/server/live-run-registry.d.ts

@@ -0,0 +1,22 @@
+import type { LiveAgentRun } from './agent-runtime-types.js';
+export interface RunExitEntry {
+    promise: Promise<void>;
+    resolve: () => void;
+    runId: string;
+}
+export interface LiveRunRegistry {
+    add: (run: LiveAgentRun) => void;
+    createExitEntry: (runId: string) => void;
+    deleteExitEntry: (runId: string) => void;
+    get: (runId: string) => LiveAgentRun | undefined;
+    getExitEntry: (runId: string) => RunExitEntry | undefined;
+    clearPendingExitCode: (runId: string) => void;
+    getPendingExitCode: (runId: string) => number | null | undefined;
+    hasPendingExitCode: (runId: string) => boolean;
+    list: () => LiveAgentRun[];
+    listExitEntries: () => RunExitEntry[];
+    remove: (runId: string) => void;
+    resolveExit: (runId: string) => void;
+    setPendingExitCode: (runId: string, exitCode: number | null) => void;
+}
+export declare const createLiveRunRegistry: () => LiveRunRegistry;