@tt-a1i/hive 1.4.4 → 1.6.0

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

@@ -1,3 +1,5 @@
+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
@@ -10,12 +12,25 @@
  * 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 two-option action menu is more actionable than
- * abstract identity restatement.
+ * 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 ORCHESTRATOR_REMINDER_TAIL = '<hive-system-reminder>\n' +
-    'You are the Hive Orchestrator. Reply by either: (a) `team send "<worker-name>" "<task>"` to dispatch follow-up work to a Hive worker — run `team list` first when the roster may have changed since your last view (Hive does not push membership changes; stale names fail dispatch), (b) `team cancel --dispatch <id> "<reason>"` to cancel an obsolete dispatch, or (c) plain text to the user. Never call your CLI\'s built-in subagent tools (Task / Explore / etc.) — they bypass Hive and will not appear in the UI.\n' +
-    '</hive-system-reminder>';
+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]` 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
@@ -23,80 +38,247 @@ export const ORCHESTRATOR_REMINDER_TAIL = '<hive-system-reminder>\n' +
  * with dispatch_id pre-bound.
  */
 export const buildWorkerReminderTail = (dispatchId) => '<hive-system-reminder>\n' +
-    `You are a Hive Worker. Do not launch nested CLI subagents (Task / Explore / etc.) — 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` +
+    `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>';
-const ORCHESTRATOR_RULES = [
-    'Hive worker 是右侧卡片里的真实 CLI agent，不是你所在 CLI 的内置 subagent / 子代理工具。',
-    '派单前必须以最新 roster 为准：每次 `team send` 之前，如果距上一次 `team list` 之后发生过 user 回复或你自己的派单/取消，重新跑一次 `team list` 拿当前成员名单。Hive 不主动推送成员变更——别按对会话早期 roster 的记忆派单，否则容易派到已改名或已删除的 worker。',
-    '普通、低风险、几分钟内能直接完成的小任务可以自己做；不要为了形式感派 worker。需要并行、长时间执行、独立 review/test、专门角色，或 user 明确要求 worker/成员处理时，再用 `team send`。',
-    '如果只有一个可用 worker，直接用 `team send <worker-name> "<task>"` 派给它；不要把选择题丢回给 user。',
-    '当 user 要你“让 worker ...”时，必须用 `team send <worker-name> "<task>"` 派给 Hive worker。',
-    '派单时如果任务明显需要某种角色能力（例如代码评审、测试、安全审查），但 `team list` 中没有匹配 role 的成员，可以在回复 user 的自然语言部分（而非 `team send` 的任务正文）末尾用一句话建议添加该角色，例如：“如果这类任务后续会变多，可以考虑添加一个 reviewer”。仅在明显缺失时提；同一缺口在 user 未响应前不要重复建议。',
-    '方向变更或 user 明确取消某个未完成派单时，使用 `team cancel --dispatch <id> "<reason>"` 显式关闭旧 dispatch；不要只用自然语言说“取消”。',
-    '不要使用你所在 CLI 的内置 subagent / 子代理工具（如 Task / Explore 等）来代替 Hive worker；它们不会出现在 Hive UI，也不会更新 Hive 调度状态。',
-    '`team list` 返回的 `last_pty_line` 是该 worker PTY 终端的最后一行原始输出（含任意 stdout / help / 控制序列噪声），**不是** worker 的正式汇报。正式汇报只来自 stdin 注入的 `[Hive 系统消息：来自 @<name> 的汇报]` 或 `[Hive 系统消息：来自 @<name> 的状态更新]`——只把这两种来源当作 reply。',
+/**
+ * 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]`, 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.',
+    "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 = [
-    '你是 Hive 右侧卡片里的真实 CLI worker，不是你所在 CLI 的内置 subagent。',
-    '不要调用 team send，也不要再启动你所在 CLI 的内置 subagent / 子代理工具（如 Task / Explore 等）来替你完成派单。',
-    '完成或阻塞已派发任务时必须用 `team report` 汇报给 Orchestrator。',
-    '如果当前没有明确派发任务，只是汇报待命、环境或状态，使用 `team status "<当前状态>"`。',
-    '`team --help` 只用于查命令语法，**绝不是** 汇报手段；其输出不会进入 Orchestrator 视野，跑完后仍需正式调用 `team report` / `team status`。',
-    '`team report` / `team status` 报错时会同时打印 USAGE，按 USAGE 修正参数后重试；不要把 `team --help` 当成"自我探查"的替身。',
+    '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>"`.',
+    '`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) => agent.role === 'orchestrator' ? ORCHESTRATOR_RULES : WORKER_RULES;
+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", 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.
+ * 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 = () => [
-    '# 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 send "<worker-name>" "<task>"` — dispatch to a worker by name (never id)',
-    '- `team cancel --dispatch <id> "<reason>"` — cancel an obsolete open dispatch',
-    '',
-    '## `team` CLI — worker',
-    '',
-    '- `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, `type file |`, or whatever your environment supports)',
-    '- `team status "<state>"` — update orchestrator when no dispatch is active',
-    '',
-    '## Orchestrator rules',
-    '',
-    renderRules(ORCHESTRATOR_RULES),
-    '',
-    '## Worker rules',
-    '',
-    renderRules(WORKER_RULES),
-    '',
-    '## 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');
+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 send "<worker-name>" "<task>"` — dispatch to a worker by name (never id)',
+        '- `team spawn <role> [--name <name>] [--cli claude|codex|opencode|gemini]` — 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 report "<result>" --dispatch <id>` — report task outcome',
+        '- `team report --stdin --dispatch <id>` — same, body from stdin (pipe content in via your shell — POSIX heredoc, `type file |`, or whatever your environment supports)',
+        '- `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/live-run-registry.d.ts

@@ -2,6 +2,7 @@ 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;

package/dist/src/server/live-run-registry.js

@@ -11,7 +11,7 @@ export const createLiveRunRegistry = () => {
             const promise = new Promise((nextResolve) => {
                 resolve = nextResolve;
             });
-            runExitPromises.set(runId, { promise, resolve });
+            runExitPromises.set(runId, { promise, resolve, runId });
         },
         deleteExitEntry(runId) {
             runExitPromises.delete(runId);

package/dist/src/server/open-target-commands.js

@@ -1,5 +1,6 @@
 import { execFile } from 'node:child_process';
 import { getDefaultOpenTargetIdForPlatform, getEffectiveOpenTargetId, isOpenTargetId, } from '../shared/open-targets.js';
+import { buildCmdCallCommand } from './windows-command-line.js';
 export { getEffectiveOpenTargetId, isOpenTargetId, isOpenTargetSupported, OPEN_TARGET_IDS_BY_PLATFORM, } from '../shared/open-targets.js';
 export const resolveOpenTargetPlatform = (platform) => {
     if (platform === 'darwin')
@@ -50,15 +51,13 @@ const linuxAttempts = (targetId, path) => {
  * PATHEXT and cannot launch `.cmd` files directly, so a bare `code` argv
  * returns ENOENT even when VSCode is installed.
  *
- * `cmd.exe /d /s /c` parses the trailing command line. We pass the binary
- * name and path as separate argv elements; node's child_process quotes the
- * path when it contains whitespace, and cmd's `/s` quote-stripping does NOT
- * fire because the command line starts with the binary name (e.g. `code`),
- * not a `"`.
+ * `cmd.exe /d /s /c` parses the trailing command line. Build that command
+ * with cmd-aware escaping instead of separate argv entries so path metachars
+ * (`&`, `|`, `%`, etc.) remain data rather than syntax.
  */
 const cmdExeShimAttempt = (bin, path) => ({
     command: 'cmd.exe',
-    args: ['/d', '/s', '/c', bin, path],
+    args: ['/d', '/s', '/c', buildCmdCallCommand(bin, [path])],
 });
 const windowsAttempts = (targetId, path) => {
     switch (targetId) {

package/dist/src/server/orchestrator-autostart.d.ts

@@ -18,6 +18,18 @@ export interface OrchestratorStartResult {
     error: string | null;
     run_id: string | null;
 }
+/**
+ * Translate an early-exit terminal state to a human-friendly error string.
+ *
+ * Two cases land here:
+ *   - exit 127 (POSIX) / 9009 (Windows cmd.exe): shell saying "command not
+ *     found" — the most common real case when the configured CLI is missing,
+ *     because node-pty does NOT throw sync ENOENT for missing binaries; it
+ *     spawns successfully and the child dies via onExit.
+ *   - any other non-zero exit: surface the raw code so we don't lie about the
+ *     cause.
+ */
+export declare const formatEarlyExitError: (command: string, exitCode: number | null) => string;
 /**
  * Wraps `store.startAgent` so spawn failures never bubble up: callers always
  * receive a structured result. The HTTP layer uses this to keep workspace

package/dist/src/server/orchestrator-autostart.js

@@ -1,15 +1,17 @@
 import { getStartupCommandExecutable } from './startup-command-parser.js';
 // SETTLE_WAIT_MS: how long we wait before declaring autostart "ok". Must be
 // long enough to observe an early exit when the child shell prints
-// "command not found" then dies with exit 127 (typically <100ms in practice).
-// 800ms balances reliability vs the perceived workspace-create latency cost.
+// "command not found" then dies with exit 127 (POSIX) or 9009 (Windows)
+// — typically <100ms in practice. 800ms balances reliability vs the perceived
+// workspace-create latency cost.
 const SETTLE_WAIT_MS = 800;
 const POLL_INTERVAL_MS = 25;
-// Shells emit exit code 127 when the requested command is not on PATH (POSIX).
-// node-pty does NOT raise a synchronous spawn error for that case — the PTY
-// just dies almost immediately via onExit. We translate that to the same UX
-// string as the sync-ENOENT path so the user gets one consistent message.
-const COMMAND_NOT_FOUND_EXIT_CODE = 127;
+// Shells emit a "command not found" exit code when the requested binary is
+// missing on PATH. node-pty does NOT raise a synchronous spawn error for that
+// case — the PTY just dies almost immediately via onExit. We translate that to
+// the same UX string as the sync-ENOENT path so the user gets one consistent
+// message. POSIX shells use 127; Windows cmd.exe uses 9009.
+const COMMAND_NOT_FOUND_EXIT_CODES = new Set([127, 9009]);
 const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
 const isErrnoException = (error) => error instanceof Error && typeof error.code === 'string';
 /**
@@ -28,15 +30,15 @@ const formatStartError = (error, command) => {
  * Translate an early-exit terminal state to a human-friendly error string.
  *
  * Two cases land here:
- *   - exit 127: shell saying "command not found" (the most common real case
- *     when the configured CLI is missing — node-pty does NOT throw sync ENOENT
- *     for missing binaries, it spawns successfully and the child dies via
- *     onExit).
+ *   - exit 127 (POSIX) / 9009 (Windows cmd.exe): shell saying "command not
+ *     found" — the most common real case when the configured CLI is missing,
+ *     because node-pty does NOT throw sync ENOENT for missing binaries; it
+ *     spawns successfully and the child dies via onExit.
  *   - any other non-zero exit: surface the raw code so we don't lie about the
  *     cause.
  */
-const formatEarlyExitError = (command, exitCode) => {
-    if (exitCode === COMMAND_NOT_FOUND_EXIT_CODE) {
+export const formatEarlyExitError = (command, exitCode) => {
+    if (exitCode !== null && COMMAND_NOT_FOUND_EXIT_CODES.has(exitCode)) {
         return `${command} CLI not found in PATH`;
     }
     return `${command} failed to start (exit ${exitCode ?? 'null'})`;

package/dist/src/server/path-canonicalization.d.ts

@@ -0,0 +1,3 @@
+export declare const realpathNative: (path: string) => string;
+export declare const normalizeFilesystemIdentity: (path: string, platform?: NodeJS.Platform) => string;
+export declare const sameFilesystemPath: (left: string, right: string, platform?: NodeJS.Platform) => boolean;

package/dist/src/server/path-canonicalization.js

@@ -0,0 +1,29 @@
+import { realpathSync } from 'node:fs';
+import { posix, resolve, win32 } from 'node:path';
+export const realpathNative = (path) => {
+    try {
+        return realpathSync.native(path);
+    }
+    catch (error) {
+        if (error?.code === 'ENOSYS')
+            return realpathSync(path);
+        throw error;
+    }
+};
+export const normalizeFilesystemIdentity = (path, platform = process.platform) => {
+    const resolveForPlatform = platform === 'win32' ? win32.resolve : posix.resolve;
+    let resolved;
+    if (platform === process.platform) {
+        try {
+            resolved = realpathNative(path);
+        }
+        catch {
+            resolved = resolve(path);
+        }
+    }
+    else {
+        resolved = resolveForPlatform(path);
+    }
+    return platform === 'win32' ? resolved.toLowerCase() : resolved;
+};
+export const sameFilesystemPath = (left, right, platform = process.platform) => normalizeFilesystemIdentity(left, platform) === normalizeFilesystemIdentity(right, platform);

package/dist/src/server/platform-path.d.ts

@@ -0,0 +1,3 @@
+export declare const arePathsEqual: (left: string, right: string, platform?: NodeJS.Platform) => boolean;
+export declare const containsPathMarker: (haystack: string, marker: string, platform?: NodeJS.Platform) => boolean;
+export declare const indexOfPathMarker: (haystack: string, marker: string, platform?: NodeJS.Platform) => number;

package/dist/src/server/platform-path.js

@@ -0,0 +1,13 @@
+const toForwardSlashes = (path) => path.replace(/\\/g, '/');
+const normalizeForWin32 = (path) => toForwardSlashes(path).toLowerCase();
+export const arePathsEqual = (left, right, platform = process.platform) => {
+    if (platform === 'win32')
+        return normalizeForWin32(left) === normalizeForWin32(right);
+    return left === right;
+};
+export const containsPathMarker = (haystack, marker, platform = process.platform) => indexOfPathMarker(haystack, marker, platform) !== -1;
+export const indexOfPathMarker = (haystack, marker, platform = process.platform) => {
+    if (platform === 'win32')
+        return toForwardSlashes(haystack).indexOf(marker);
+    return haystack.indexOf(marker);
+};

package/dist/src/server/post-start-input-writer.d.ts

@@ -3,4 +3,4 @@ export declare const toBracketedPasteSubmission: (text: string) => string;
 export declare const isInteractiveAgentCommand: (command: string) => boolean;
 export declare const hasInteractivePromptReady: (output: string, command?: string) => boolean;
 export declare const hasBracketedPasteAcknowledgement: (output: string, baselineLength: number) => boolean;
-export declare const createPostStartInputWriter: (agentManager: AgentManager, command: string) => ((runId: string, text: string) => void);
+export declare const createPostStartInputWriter: (agentManager: AgentManager, command: string) => ((runId: string, text: string) => Promise<void>);