Spawn worker pool
spawn_workersSpawn a pool of queue workers in one call to claim tasks, run your command per task, and exit when the queue drains.
Instructions
Spawn a pool of queue workers in one call (#6). Opens pane(s) running the native hyperpanes worker runner bound to queue: it claims tasks and runs command (via sh -c, so $HP_TASK_PAYLOAD / $HP_TASK_ID / $HP_FENCING_TOKEN / $HP_QUEUE are in the environment) for each, acking on exit 0 and nacking on non-zero, until the queue drains — then the pane exits. count = how many competing workers; by default each gets ITS OWN pane (layout:"pane-per-worker") so you can watch one agent per pane — pass layout:"single-pane" for the legacy one-pane-runs-N behaviour. isolation:"worktree" runs each task in a throwaway git worktree that auto-removes (needs cwd to be a git repo) and REQUIRES base — the explicit committish each task worktree forks from, passed to the runner as --base (the call fails without it). stream:true renders a Claude child's --output-format stream-json events as readable progress instead of the silence a bare claude -p gives you; logDir tees each task's raw output to a file that outlives the pane; lingerSecs keeps the pane open after the queue drains. The runner binary defaults to hyperpanes on PATH (override with HYPERPANES_WORKER_BIN on the bridge). env/accounts/meta/project/subtitle pass through to each worker pane spec — merge order: env is the shared base, accounts[i % len] sets each pane's CLAUDE_CONFIG_DIR and wins over env (rotation requires layout:"pane-per-worker" when count > 1; single-pane shares one process env, so the call fails loudly). Every worker pane is stamped with default org meta role="worker", task="queue:", parent=<this bridge's pane> (so worker send_to_parent works out of the box); caller meta wins over those defaults. Returns the spawned pane ids.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| cwd | No | runner working directory; required (a git repo) for isolation:"worktree" | |
| env | No | env vars set on every worker pane | |
| base | No | fork point committish for isolation:"worktree" task worktrees (REQUIRED with it): "main" for independent work, the goal's integration branch for a dependent wave | |
| meta | No | free-form org metadata merged OVER the stamped defaults (role="worker", task="queue:<queue>", parent=<this bridge's HYPERPANES_PANE_ID>) — an explicit key always wins | |
| color | No | ||
| count | No | competing workers (default 1); one pane each unless layout:"single-pane" | |
| queue | Yes | the work queue to drain | |
| layout | No | "pane-per-worker" (default) = one visible pane per worker; "single-pane" = one runner pane multiplexing all N | |
| logDir | No | tee each task's raw output to <dir>/<queue>-<taskId>.log, so the transcript survives the pane closing | |
| stream | No | render the child's Claude stream-json events as readable progress (pair with `--output-format stream-json --verbose` in `command`) | |
| command | Yes | shell command run per claimed task; reads the task from $HP_TASK_PAYLOAD etc. | |
| project | No | open worker panes in a remembered project (see list_projects): defaults cwd + color from it | |
| accounts | No | CLAUDE_CONFIG_DIR account rotation: under layout:"pane-per-worker" (default), worker pane i gets env.CLAUDE_CONFIG_DIR = accounts[i % accounts.length], winning over env.CLAUDE_CONFIG_DIR. Rotation needs one pane per worker: with layout:"single-pane" and count > 1 the call FAILS (one process env cannot rotate per-worker); single-pane with count 1 gets accounts[0] | |
| subtitle | No | secondary header line set on every worker pane | |
| windowId | No | ||
| isolation | No | "worktree" = run each task in a throwaway git worktree (default "none"); requires `base` | |
| lingerSecs | No | hold each worker pane open this many seconds after the queue drains (default 0 = close immediately) |