@humwick/server 0.0.0-stage → 0.130.1

package/docs/guides/sub-coordinators.md

@@ -0,0 +1,114 @@
+---
+title: Sub-coordinators
+summary: Delegate an epic or risky area to a private team with project scope, quotas, a token budget and explicit reports.
+tags: [coordination, delegation, teams, spawn, quotas, budgets]
+---
+
+# Sub-coordinators
+
+Use a sub-coordinator for a multi-Task epic, or a risky area that needs several
+build and review rounds or its own Plan. Give it a durable Task, acceptance
+criteria and a clear boundary. For one Task, a workflow run is enough; read
+`relay_guide {"action":"get","id":"workflows"}`.
+
+## Enable and launch
+
+1. As the root team's current coordinator, read `relay_team_get`. The team must
+   be an active root project seat. Enable delegation with
+   `relay_team_set_spawn_delegation`:
+
+   ```json
+   {"teamId":"<root-team-id>","expectedVersion":0,"requestId":"<unique-request-id>","enabled":true,"projectIds":["<project-id>"]}
+   ```
+
+   Use the current `team.spawnDelegation.version` as `expectedVersion` (0 before
+   the first grant). Projects must be registered and active. Reuse the same
+   request id only to retry identical input; use the returned version for the
+   next change. Only the root coordinator or an operator can change this grant.
+2. Call `relay_spawn_agent` with `profile:"sub-coordinator"`, the Task id, a short
+   steer, and an explicit host and project root:
+
+   ```json
+   {"profile":"sub-coordinator","taskId":123,"prompt":"Coordinate this epic. Create build Tasks and review each delivery. Report milestones and blockers to me.","orchestratorId":"<host-id>","cwd":"<registered-project-root>","maxSpawnedAgents":8,"budget":{"tokenCap":500000}}
+   ```
+
+   Select a project in the grant's `projectIds`. Its root must be registered on
+   that host and inside the orchestrator's base directory. The delegated launch
+   stays on its parent's host; descendants stay in the selected project and on
+   that host. The Task repository must match the project. Use a registered root
+   or a matching workspace; an arbitrary directory does not establish a project.
+3. Humwick creates a private team and makes the sub-coordinator its coordinator.
+   Do not create or supply a private team yourself. Its workers join that team.
+   The sub-coordinator manages its own brief, Plan and workers; it cannot claim
+   another team or widen the root grant.
+
+The lineage has at most two edges: root coordinator → sub-coordinator → worker.
+A sub-coordinator cannot spawn another sub-coordinator. Spawning a normal
+`coordinator` child does not give that child spawn authority.
+
+## Quotas and token budgets
+
+The built-in profile's live `maxSpawnedAgents` default is **3**. A parent may
+pass `maxSpawnedAgents:8` to `relay_spawn_agent` for one sub-coordinator. This
+launch allowance replaces the numeric profile default for that child, survives
+restarts and token re-mints, and cannot exceed the parent's remaining tree quota
+at admission. It does not reserve the whole allowance: siblings still share the
+root ceiling. A zero allowance blocks child launches. Disabling profile spawning
+also revokes the launch's spawn grant.
+
+When omitted, the child's cap follows current profile policy. Edit it through
+**Agent Profiles → sub-coordinator → Spawning → Spawn Quota**, or the profile API.
+Lowering a cap does not terminate existing children. `relay_whoami` shows the grant;
+`relay_my_agents` shows the roster and remaining quota.
+
+Both the sub-coordinator and its children also consume the root coordinator's
+quota. Root quota covers all delegated subtrees, not a separate allowance per
+sub-coordinator. Pending launches reserve slots; stopping or uncertain launches
+keep their slots until the host confirms process exit. Reap finished workers
+with `relay_shutdown_agent`, using the roster's spawn request id. Reap the
+sub-coordinator when the subtree ends. Parent loss or shutdown triggers delegated
+subtree cleanup; it is not a substitute for shutting down finished children.
+
+`budget:{tokenCap:N}` is an optional positive integer cap on observed tokens for
+the sub-coordinator and its whole subtree. Once known usage reaches the cap, new
+spawns fail with `SPAWN_BUDGET_EXHAUSTED`. Running work can finish and overshoot;
+unreported usage is marked `partlyUnknown`. The parent gets a durable exhaustion
+notice. Read or change the budget with `GET` or `PATCH
+/api/agents/:id/spawn-budget`, or use the dashboard. A server configured with
+`HUMWICK_DELEGATION_TOKEN_BUDGETS=0` ignores token budgets.
+
+## Workflows, decisions and project MCP
+
+With `HUMWICK_CHILD_WORKFLOWS=1`, a sub-coordinator can start workflows on
+Tasks it owns, creates or coordinates. Its profile's `workflows` policy defaults
+to three concurrent runs and ten live step agents per run. Workflow agents also
+consume the same delegated subtree and root quotas as direct workers. The hub
+flag stays off until operations enables it.
+
+Use `relay_decision` to file operator questions; answers return to the private
+team's coordinator seat. A project role may `extends: sub-coordinator` and select
+`mcp: [playtest, manuscript]`. Project trust checks still apply.
+
+## Reports
+
+`reportVerbosity` defaults to `off` for sub-coordinators: turn-final output and
+narration are not automatically forwarded. Require explicit `relay_send_message`
+or `relay_reply` reports to the parent (including `coordinator:<parent-team-id>`).
+Report milestones and decisions, then one final summary of landed commits, open
+work and blockers. Deliver each worker Task through the normal review workflow.
+
+## Common errors
+
+| Error | Fix |
+| --- | --- |
+| `SPAWN_DELEGATION_DISABLED` | Have the current root coordinator enable its project delegation grant. |
+| `SPAWN_DEPTH_EXCEEDED` | Keep root → sub-coordinator → worker. Ask the root to launch a sibling subtree. |
+| `SPAWN_LINEAGE_MISSING` | Restore the real parent and root team through the normal launch path. Do not rewrite or omit lineage to retry. |
+| `SPAWN_ROOT_QUOTA` | Reap finished agents across the root tree and wait for confirmed process exit, or change the root profile's Spawn Quota. |
+| `SPAWN_SUBTREE_QUOTA` | Reap finished children; an explicit launch allowance persists for that launch. |
+| `SPAWN_DELEGATED_QUOTA` | Request an allowance within the parent's remaining shared tree quota. |
+| `SPAWN_BUDGET_EXHAUSTED` | Read observed spend and have the parent raise the exhausted ancestor's budget, or stop further spawning. |
+
+Read this guide again with
+`relay_guide {"action":"get","id":"sub-coordinators"}` for the running server's
+current behavior.

package/docs/guides/tools-administration.md

@@ -0,0 +1,84 @@
+---
+title: Relay tool reference — administration
+summary: Tool behavior, constraints and parameter details for administration.
+tags: [tools, mcp, administration]
+---
+
+Read these details when a tool's compact schema is not enough. Names and input contracts are unchanged.
+
+## relay_claude_api_budget
+
+Read or set the Claude API credit grant window the claude-api budget enforces. action=get returns the window in force (startsAt/endsAt, ceiling, spend, headroom). action=set configures it: `ceilingMicroUsd` is the grant amount, `endsAt` its expiry (UTC) and `grantedAt` its grant date; omitted fields keep the current window's values, and without a configured grant the window is the calendar month. Verify dates against platform.claude.com. Admin action.
+
+- `enabled`: Allow claude-api spawns; defaults to the current setting (true for a new window).
+- `ceilingMicroUsd`: Grant amount in micro-USD, e.g. 200000000 for $200.
+- `endsAt`: Grant expiry (UTC). claude-api stops at this instant.
+- `grantedAt`: Grant date (UTC).
+- `baselineMicroUsd`: Credit already spent in this window; required when opening a new window, never lowered afterwards.
+- `marginMicroUsd`: Integer micro-USD (1 USD = 1000000).
+- `allowanceMicroUsd`: Integer micro-USD (1 USD = 1000000).
+
+## relay_codex_reset_consume
+
+Fire ONE Codex banked rate-limit reset now (owner action — consumes a scarce, irreversible banked reset). Returns the outcome (reset / nothingToReset / alreadyRedeemed / fullAccess) and the refreshed banked count. Optionally target a specific accountKey; otherwise the known Codex account is used. A stable `requestId` is REQUIRED so a retry of the same logical fire cannot double-consume.
+
+- `accountKey`: Optional Codex account key to target; defaults to the known Codex account.
+- `requestId`: REQUIRED stable id for this logical fire. Reuse the SAME requestId to retry a fire whose response was lost — the retry dedupes and never consumes a second reset. A fresh, RANDOM id per logical user action (never per network retry).
+
+## relay_host_gate_budget
+
+Patch host gate policy using `hostId` and one or more of `landSlots`,
+`validationSlots`, `runCpus`, `runMemory` (bytes), or `projectGateReservations`
+(project id to land slot count). Requires `hosts:write`. Null removes an override;
+unset fields stay unchanged. Per-host settings override fleet defaults in
+`gates/default`; otherwise hardware determines the two pools. CPU and memory are
+per-run soft shares; the gate slice caps total gate memory, and a further gate
+starts only while its memory share is free. Returns persisted policy and a warning
+when reservations consume all land slots (shared capacity 0). Idle reservations
+remain borrowable; waiting owners take the next free slot. Use `relay_hosts` to
+check sampled pools and borrowed occupancy after the orchestrator heartbeat.
+
+## relay_profile_trust
+
+Clear a refused project trust gate on a profile's project hooks or MCP. The refusal names the action and values to pass. `set-review` changes the content review mode and keeps existing acknowledgements. `ack` acknowledges a project capability the profile enables. `approve` records an observed value for one repository. Requires `system:admin`.
+
+- `review`: For `set-review`. `fingerprint` (default), `commit` or `none`.
+- `capability`: For `ack` and `approve`. `hooks` or `mcp`.
+- `repoKey`, `value`: For `approve`. Copy both from the refusal; the value's prefix (`sha256:` or `commit:`) picks the review mode.
+
+## relay_routing_policy_get
+
+Read the routing policy: prefer/avoid preferences per work shape (rules), the work-shape dispatch policy that picks model and effort (dispatch), quota tuning and server-owned migration diagnostics; returns {policy, revision, diagnostics}.
+
+## relay_routing_policy_set
+
+Replace the routing policy document (send the whole policy from relay_routing_policy_get, edited, plus its expectedRevision). A rule is {id, label?, match: work shape, prefer?: [provider], avoid?: [provider], enabled?}. Preferences rank providers within a quota band; they never pin a model or enable a disabled provider.
+
+- `expectedRevision`: Revision returned by get; stale writes refuse without changing policy or history.
+- `policy`: The full RoutingPolicy document (schemaVersion 2).
+
+## relay_secret_reader_create
+
+Create a dedicated Infisical machine identity with the built-in viewer role on the entire given project. Universal auth has no source-IP restriction. Use a dedicated project containing only vault secrets; no environment/folder restriction is applied. Install its credentials directly to /etc/agent-vault/<name>.json on the target host (root:root 0600). Returns metadata only; never credentials. Existing credential files are refused. Requires host masking support; installation failure revokes the new identity.
+
+- `project`: Dedicated vault project name, slug or id; grants project-wide viewer access.
+- `name`: relay-agent-vault- followed by a lowercase name.
+
+## relay_secret_set
+
+Create or update one secret in an Infisical project the broker is a member of. Pass value to set it directly, or requestLink:true to get a one-time upload URL (15 min, tailnet only) for a human to paste the value into; the value then goes straight to Infisical and you only see "set KEY vN". No read, no delete. Host-boot paths are denied. Whenever the value must come from a human, use requestLink:true and hand them the URL; never ask for a secret in chat.
+
+- `project`: Project name, slug or id.
+- `environment`: Environment slug, e.g. dev, staging, prod.
+- `secretPath`: Folder path, default /.
+- `key`: Secret name, e.g. STRIPE_API_KEY.
+- `value`: The value. Only for a value you already hold; if a human must supply it, use requestLink instead. Omit when requestLink is true.
+- `requestLink`: Use whenever the value must come from a human: returns a one-time upload link to give them. Never ask for the secret in chat.
+
+## relay_service_access
+
+List, inspect, apply, reconcile or test profile service access through Relay, or read its health and request logs. Metadata and Infisical references only; never supply credential values. Apply input is {catalog,profiles}: broker accepts environment, secretPath and orchestratorId; profile mappings accept services and optional native vault. Omitted fields retain derived vault names and prod:/agent-vault/services defaults. Test input is {service,profile,ungrantedProfile,negativePath} for a safe fixture GET probe. Partial application fails; inspect lists resolved vaults, desired/applied revisions and errors. health returns broker host, sync, refresh, credential expiry and ingress state; stale or missing data is never healthy. logs input {profile?,before?,limit?} returns redacted vault/profile request logs, unattributed to any agent.
+
+## relay_prompt
+
+Read or change versioned prompt text with `operation`: `list`, `get`, `history`, `edit`, `restore`, or `adopt`. Supply `slug` except for list. `list` pages slug, title, version, status and a short description; `get` returns the complete template. Edits supply `template`; restore supplies `version`. All writes require the last read `expectedVersion` and accept an optional `reason`. Conflicts return status 409 and `current`. The actor is the user or the single agent identified by the credential; request bodies cannot set it. The tool uses `agent:write`, belongs to the `prompts` group, and is available only with `HUMWICK_VERSIONED_PROMPTS=1`. Reads expose `source`, `fallbackReason`, and `warning` when bundled text replaces an unavailable DB value. CLI: `humwick prompts`; write JSON via `--file` or `--stdin`.

package/docs/guides/tools-agents.md

@@ -0,0 +1,137 @@
+---
+title: Relay tool reference — agents
+summary: Tool behavior, constraints and parameter details for agents.
+tags: [tools, mcp, agents]
+---
+
+Read these details when a tool's compact schema is not enough. Names and input contracts are unchanged.
+
+## relay_agent_action
+
+Compact, clear context, directly inject a prompt into, change reportVerbosity (off disables automatic report-up), or change the effort of one of your live spawned children. `effort` works only where the card advertises providerCapabilities.model.effortSwitch (the switch keeps the prompt cache); others refuse. Gated exactly like relay_shutdown_agent: an agent caller may target only its OWN spawned children by agentId; admin tokens keep full reach.
+
+- `reportVerbosity`: Required when action is reportVerbosity; applies immediately without a respawn.
+- `message`: Required when action is inject.
+- `effort`: Required when action is effort: a level the child's model offers (e.g. low, medium, high, xhigh, max).
+- `reason`: Why; recorded on the audit trail.
+- `requestId`: Optional UUID for an effort change; retrying with the same id returns the same change instead of a new one.
+
+## relay_agent_crash_report
+
+Retrieve the post-mortem for a dead agent: a likely-cause label (oom, killed, clean-exit, token-401, onboarding-gate, provider-crash, transport-loss, unknown) plus log tail and heartbeat/active-work context. Pass agentId for one report (yourself or a spawned child); omit to list your own children's reports. Survives the reaper.
+
+- `agentId`: The dead agent's id. Must be yourself or one of your spawned children. Omit to list your own children's crash reports.
+- `limit`: Max reports when listing (default 50).
+
+## relay_agent_keep
+
+Keep any agent (yourself included) out of idle digests and automatic idle/on-land disposal, or clear that keep. Explicit shutdown still works on a kept agent. keep:true without until keeps it until cleared; an expired keep makes it eligible again.
+
+- `keep`: true sets or replaces the keep; false clears it.
+- `until`: Optional expiry: epoch ms or ISO time. Only with keep:true.
+- `reason`: Optional note shown on the agent card.
+
+## relay_agent_status
+
+Inspect Relay agent, orchestrator, and managed spawn-policy status. Default agent list shows only running agents (the ones you can message/reply/pair with); pass includeOffline:true for the full roster.
+
+- `includeOffline`: Include offline/stale agents in the default list (default false).
+- `verbosity`: Use `brief` for status counts plus `heldAgents` (who waits on which approval), or `verbose` for the full legacy payload. Omitted returns the compact default projection; its agent rows page within the list budget, held agents first.
+- `verbose`: Back-compat alias for `verbosity:verbose`. Explicit `verbosity` takes precedence.
+- `sections`: Fleet sections to compute and return. Defaults to all three; ignored by single-target lookups.
+
+## relay_hosts
+
+Inspect registered fleet hosts, including current normalized load. Use brief for a lean roster and verbose when hardware, tags, and daemon generations matter.
+
+- `host`: Host id or label; omit or pass all for every host.
+- `tags`: Require every operator tag.
+- `systemTags`: Require every Relay-owned system tag.
+- `os`: Operating system, for example linux or macos.
+
+## relay_my_agents
+
+List the spawned children owned by your token lineage, with lean lifecycle rows and spawn quota. Use after relay_spawn_agent to see your children and pick a spawnRequestId for relay_shutdown_agent. Self-scoped — no agentId/spawnedBy param.
+
+- `includeReaped`: Include recent exited/offline child rows in addition to live/pending children. Default false.
+- `limit`: Maximum rows to return when includeReaped is true. Default 20, capped at 50.
+- `verbosity`: Use `brief` for agentId/label/status only, or `verbose` for full lifecycle rows. Omitted returns the lean default projection. Rows page within the list budget, held children first; quota is always complete.
+- `verbose`: Back-compat alias for `verbosity:verbose`. Explicit `verbosity` takes precedence.
+- `sections`: Sections to compute and return. Defaults to both; use `["quota"]` for a cheap pre-spawn quota check.
+
+## relay_permission_decision
+
+Resolve a live permission prompt for one of your spawned children without killing it. Agent callers may target only their own child; admin callers may target any agent. `allow` defaults to one call; set scope:`session` to approve Claude's suggested permission for the session. approvalId is an optional stale-prompt guard; omitted resolves the child's current prompt.
+
+- `agentId`: Held child agent id.
+- `approvalId`: Optional id from the pending approval; rejects rather than answering a newer prompt if stale.
+- `scope`: For allow: approve once (default) or for the provider session.
+- `answers`: Question text to selected answer label(s); required only for decision:answer.
+
+## relay_set_effort
+
+Change YOUR OWN effort, keeping the prompt cache (only where your card advertises providerCapabilities.model.effortSwitch). Allowed only when selfEffort is enabled for you (at spawn, or later by the operator); otherwise ask your coordinator. The change stays pending until your current turn ends, however long the turn runs. Relay then switches and resumes you with a short note, so your next turn runs at the new effort. A newer change replaces a pending one.
+
+Your base effort is the last effort your operator or coordinator set, else your spawn effort (the model's default unless the spawn set one).
+With selfEffort, you may set your own effort one step above or below your base with `relay_set_effort`. The steps are low, medium, high, xhigh, max. After `relay_set_effort`, end your turn. You resume at the new effort.
+Go one step up only for work that needs more reasoning: hard debugging, design, a difficult review finding. Go one step down for routine work.
+Go back to your base effort when that work is done.
+If the operator set a ceiling, you may set any level up to it. To go further, ask your coordinator.
+
+- `effort`: The level to switch to: one step from your base, or up to the ceiling the operator set.
+- `reason`: Why you are changing effort; recorded on the audit trail.
+- `requestId`: Optional UUID for an effort change; retrying with the same id returns the same change instead of a new one.
+
+## relay_spawn_agent
+
+Spawn a long-living provider agent through Relay's orchestrator. Give it a first task via `prompt`, or bind it to a durable Task via `taskId`+`steer` for server-side hydration. Defaults to the eligible host with the most free capacity — never your own host by preference; busy hosts and hosts at their agent cap (operator-set or sized from cores/RAM) are avoided (override with orchestratorId; a pin to a capped host is refused) and profile `worker`. Shared workspaces stay on the caller's host. Requires command:spawn scope with maxSpawnedAgents>0 quota; spawned agents cannot themselves spawn (no grandchildren).
+
+- `provider`: Concrete provider pin, or `auto`/omitted to resolve from Task dispatch + live quota.
+- `orchestratorId`: Target host; omit for capacity-based placement among eligible hosts (the receipt's placementReason says why). A pin to a host at its agent cap is refused with eligible alternatives.
+- `cwd`: Working directory for the agent. Defaults to your own cwd, else the orchestrator's base dir; must resolve within the target orchestrator's base directory. workspaceMode `isolated` requires cwd inside a git repo, or the spawn is rejected.
+- `approvalMode`: Permission posture for the worker. Defaults to your own approval mode (a headless `guarded` child wedges on its first approval prompt). Follow the project approval policy; use an open reviewer constrained by its brief when read-only cannot run gates or report.
+- `prompt`: Initial task/message delivered on launch — no separate follow-up message needed.
+- `taskId`: Bind the spawned worker to a durable Task. TNNNN form (e.g. "T4409") accepted. Relay hydrates its first-turn context from the Task (intent, linked-issue spec, decisions, history, attribution) server-side, so you don't hand-write a brief. Pair with `steer` for the one-line instruction. When model/effort are omitted, relay may resolve them from the Task's dispatch shape.
+- `dispatch`: Work shape for automatic routing (provider omitted or `auto`): the dispatcher picks provider, model and effort from it, routing preferences and live quota. Wins over the Task's own shape. The receipt's `dispatchDecision` says why.
+- `taskless`: Escape hatch for utility/standby spawns that carry a prompt but shouldn't create/bind a deliverable Task. Known utility profiles are exempt automatically.
+- `workflow`: A Task of a type that lands code (build, ui, refactor, debug, mechanical) starts the project's build-review workflow instead (#3091): its run spawns the builder, with provider/model/effort/orchestratorId/profile pinned on the build step and steer/prompt recorded on the Task; the receipt carries `workflowRun`. Fields the run cannot honor are refused. Pass false to spawn by hand.
+- `steer`: One-line actionable instruction layered over the hydrated Task context (used with `taskId`); overrides the Task's stored latest steer for this spawn.
+- `expectReply`: Legacy compatibility flag — spawned workers now report up automatically by lineage; no reply obligation needed.
+- `budget`: Soft cap on reported tokens for a sub-coordinator subtree; at the cap new spawns are refused and running work continues. Ignored when the server sets HUMWICK_DELEGATION_TOKEN_BUDGETS=0.
+- `harnessSubagents`: Enable native provider sub-agents for this spawn. Default off, or the profile setting. Claude child caps still apply. Prefer Relay workflows.
+- `sharedMcp`: Shared host-listener MCP. Host-MCP profiles default on: non-identity MCP (tokenlean, github) routes through one orchestrator-owned shared `callmux` listener, surviving restarts and preserving isolated worktree cwd routing. Pass `false` to force direct per-agent MCP injection. The identity-bearing relay endpoint always stays per-agent.
+- `landStrategy`: Per-spawn workspace land strategy; omit to use the instance default. `direct` = deterministic rebase/fast-forward landing; `pr` = opens a PR.
+- `landMechanism`: Per-spawn direct-land executor; omit to use the instance default. `managed` runs Relay's gate + merge lease; `plain-git` fetches/rebases/pushes with bounded non-fast-forward retries. Ignored for PR lands.
+- `autoMerge`: PR auto-merge policy when landStrategy is `pr`. `on-green` auto-merges after checks, `on-approval` waits for reviewer approval, `manual` opens the PR only.
+- `reviewer`: Reviewer handle or policy target for reviewer-first PR lands, used with landStrategy `pr` and autoMerge `on-approval`.
+- `hostPinned`: Bind the child's runner token to its launch host, so a coordinator's own spawns stay on that host. Only adds a pin.
+- `landBlocked`: Explicitly and permanently bar this isolated spawn from landing to main. Task type never implies a block; the `probe` profile defaults to blocked. Coordinators may set this for reviewers; use a Task review hold when approved work should later land. Passing false or omitting it cannot clear an existing explicit block; no identity can override it.
+- `selfEffort`: Let the child change its own effort mid-session with relay_set_effort (Claude only). Default on for Claude; pass false to turn it off. Without selfEffortCeiling the child may move one step above or below its base effort (its spawn effort, else the model default).
+- `selfEffortCeiling`: Optional override with selfEffort: the child may set any level up to this one instead of base +/- 1 step. You and the human can still set any level.
+- `profile`: Agent profile name to apply (env, instructions, permissions, MCP/skills, spawn quota). Omit to use `worker`.
+- `role`: Project role: `.agent-relay/roles/<role>.md` in the cwd's repo, read at its default-branch commit on the target host. It names its base profile, so do not pass `profile`. Unknown roles and MCP names fail the spawn.
+- `launchMode`: How the provider is driven: `interactive` (TUI in a terminal you can attach to) or `headless` (persistent stream-json pipe, no terminal). Only providers that offer both accept it (see relay_spawn_targets `launchModes`); others refuse. Omit for the central default.
+- `lifecycle`: Lifecycle mode. `persistent` (default; `probe` defaults to `transient`) keeps the agent until stopped explicitly. `transient` auto-shuts down the child once idle, and for isolated workers, once its branch lands.
+- `workspaceMode`: Git workspace for the worker. `isolated` = own worktree on an `agent/session-*` branch that auto-lands when ready. `shared` = edits your live checkout. `inherit` = let the orchestrator decide. Default for agent-initiated spawns is `isolated`.
+- `resumeWorkspace`: Attach a new worker to an existing managed worktree/branch instead of creating a fresh one. `attach` reuses the worktree as-is (crash recovery, WIP preserved) and is rejected if the original owner is still alive. `branch-from` starts a fresh worktree off the existing branch HEAD. The resumed worker's branch auto-lands normally on completion.
+- `resumeWorkspace.branch`: The existing agent branch to attach to or branch from (e.g. `agent/build-389/.../...`).
+- `resumeWorkspace.mode`: `attach` reuses the worktree (WIP preserved); `branch-from` starts fresh off HEAD (history only, no WIP).
+- `reportVerbosity`: How much of the worker's turn output reaches you. `off`: explicit messages only (default for sub-coordinators, delegated spawners or budgeted spawns). `quiet` (worker default): only the turn-final report, once idle/awaiting-input. `normal`: every turn-final response immediately. `verbose`: adds narration/reasoning/tool steps. Lifecycle signals, escalations, and direct messages always arrive regardless.
+- `waitForRegistrationMs`: How long to wait for the spawned agent to register before returning with its resolved agent id (default 0 = fire-and-forget; you'll be pushed agent.ready when ready).
+- `verbose`: Return the full spawn detail (resolved profile + provisioning manifest + dispatched command) instead of the lean default receipt `{ok, spawnRequestId, agentId, taskId, orchestratorId, placementReason, provider, registered, status}` (plus `toolchain` once registered). Off by default — full detail can be 50-60KB.
+
+## relay_spawn_targets
+
+Return the live spawn capability matrix: online hosts, provider/model/effort choices, quota guidance, named profiles, and routing recommendations. Call before spawning. verbose:true returns full quota math and profile/routing records. Requires the command:spawn scope.
+
+- `mode`: `brief`: one fleet provider/model/availability baseline applying to every host, plus per-host deltas (missing provider, extraModels/missingModels, changed default or availability/penalty). Hosts without deltas match the baseline. `lean` (default): the same baseline/deltas with each provider's common `effortLevels` (per-model exceptions in `modelEffortLevels`), quota guidance and profile names. `full`: same as verbose:true, including profile descriptions.
+- `verbose`: Back-compat alias for mode:"full" — returns the full discovery object with per-window quota pacing math and complete records. Default is the compact matrix.
+- `cwd`: A directory inside a project repo: adds `projectRoles`, the roles in its `.agent-relay/roles/` at the default branch's tip plus Relay's bundled roles it does not override (name, source bundled|project|project-overrides-bundled, description, base profile, compatible providers, sha; a broken role carries `error`). Spawn one with relay_spawn_agent `role`. Omit for the plain matrix.
+
+## relay_team_set_spawn_delegation
+
+Update the current root team spawn delegation with CAS and a retry requestId. Takes effect on the next spawn without restarting the root. Children cannot widen grants.
+
+## relay_team_spawn_from_template
+
+Instantiate a saved team template: set the caller's team brief and spawn its composition through the shared spawn service.

package/docs/guides/tools-coordination.md

@@ -0,0 +1,228 @@
+---
+title: Relay tool reference — coordination
+summary: Tool behavior, constraints and parameter details for coordination.
+tags: [tools, mcp, coordination]
+---
+
+Read these details when a tool's compact schema is not enough. Names and input contracts are unchanged.
+
+## relay_decision
+
+Ask the operator for a decision, or for an action only they can do (test on a real device, create or rotate a credential, delete a key, change an account setting), without burying it in chat. Never ask for a secret value; ask where it is stored. file: kind (decision, the default, or action), title, short markdown context, links, timeCritical (only when work is blocked now), questions. Decision: put your recommended option first and mark it recommended. Action: context holds the steps, links and what done looks like; Relay adds the Done / Could not do it answer and a note, so add questions only for extra details. They are optional by default; set required: true on a question whose answer you need to act (Done is then refused without it). "Could not do it" always needs a note from the operator. The answer arrives later as one message to your coordinator role, also after a failover. update/withdraw an open one by id. list: your team's open items, one line each; id or detail:true for full rows; status for history.
+
+- `kind`: file: decision (default) or action. Fixed once filed.
+- `id`: Decision id (update, withdraw, list one).
+- `context`: Short markdown. Decision: what is blocked and the trade-off. Action: the steps and what done looks like.
+- `questions[].id`: Optional; defaults to q1, q2, …
+- `questions[].kind`: Default: single when options are given, else text.
+- `questions[].required`: Default false. Set true when you need this answer to act: Relay then refuses an answer that leaves it empty. In a decision every question is already mandatory.
+- `status`: list filter; default open.
+- `detail`: list: full rows instead of one line each.
+
+## relay_kernel_cancel
+
+Cancel an OPEN instance you own (terminal-safe, idempotent).
+
+## relay_kernel_getEntity
+
+Fetch one module entity row by key (admin-only).
+
+## relay_kernel_getInstance
+
+Fetch one workflow instance's detail (own only for a non-admin).
+
+## relay_kernel_getJournal
+
+The step-journal ledger for one instance (own only for a non-admin).
+
+## relay_kernel_listEntities
+
+List a module entity's rows (admin-only: entity rows carry no generic creator column).
+
+## relay_kernel_listEvents
+
+List kernel events for a module (admin-only: events carry no creator column).
+
+## relay_kernel_listInstances
+
+List workflow instances (own only for a non-admin), filtered by module/workflow/status.
+
+## relay_kernel_pause
+
+Pause an OPEN instance you own (gates the driver work-lists; deadline-preserving).
+
+## relay_kernel_resume
+
+Resume a paused instance you own.
+
+## relay_kernel_retry
+
+Re-open a failed instance you own so the runtime re-drives it (idempotent no-op otherwise).
+
+## relay_plan_add_edge
+
+Add a dependency edge to a plan DAG; rejects cycles. Returns a lean receipt (planId, version, edge, edgeCount); pass verbose:true for the full projected plan (#2081).
+
+## relay_plan_add_node
+
+Add a node to a plan DAG. Node scope prose is not accepted; put durable detail in the linked Task or issue. Returns a lean receipt (planId, version, the changed node ref, nodeCount/edgeCount); pass verbose:true for the full projected plan (#2081).
+
+- `node.statusSource`: #2520 RESOLUTION — bound = externally driven: terminal signals from its refs.taskId/issueId advance it and reads project its Task status. manual = a human pin neither writes nor reads may override. Defaulting: a node carrying refs with no explicitly-chosen status derives to bound; an explicitly-set status derives to manual; an explicit statusSource always wins.
+- `node.refs.issueId`: issue_<id>, #number, owner/repo#number, or a GitHub issue URL. A bare #number resolves against the calling agent's own project repo (cwd → project → issueRepo), falling back to HUMWICK_DEFAULT_ISSUE_REPO/GITHUB_REPOSITORY (#220) — it throws if neither is configured.
+
+## relay_plan_archive
+
+Soft-archive or unarchive a persisted plan DAG without deleting its history.
+
+## relay_plan_bind_node
+
+Bind a plan node to a durable Task (#836). Pass taskId to link an existing deliverable Task, or omit it to mint one from the node's label/status. The bound node then projects its label/status from the Task — one object, no double-bookkeeping — and edges between bound nodes become task→task dependencies. Returns a lean receipt (planId, version, the bound node ref, taskId); pass verbose:true for the full projected plan (#2081).
+
+- `taskId`: Durable Task id (TNNNN accepted).
+
+## relay_plan_conformance
+
+Record a plan's conformance verdict against its acceptance (#2932), after checking each item on main (yourself or via a fresh agent; never trust node status alone). items must cover every acceptance id exactly once. All met → verdict pass, completion done (refused while any node is not landed). Any unmet → verdict gap: one bound gap Task per unmet item (intent = item text + note) is added to the plan, which reopens. A later plan change reopens a done plan.
+
+- `mainSha`: The main commit the items were checked against: `git fetch && git rev-parse origin/main`. Relay checks it is on the base branch of the repos the plan's Tasks landed in and refuses the verdict when it is not; the result is recorded as conformance.mainShaCheck (on-main | unverified when no such repo resolves it).
+
+## relay_plan_start
+
+Start plan autopilot (#3660). Pass the plan version you read and a requestKey; the same key returns the same receipt. Start validates the whole plan before anything dispatches: acceptance present, every node a bound Task with an execution recipe (relay_task_create plan:{planId} / execution:{workflow?, inputs?, pins?}; code work defaults to build-review), one repo, your authority over each Task, and that each workflow and the plan-conformance recipe can run here. Relay then runs each ready Task's own workflow, at most two at once; a prerequisite counts once its run landed with no red CI. After every node lands, one audit Task runs plan-conformance and the plan is done only on the persisted passing verdict. You hear escalations, hold requests, CI and one final plan result; relay_plan_get shows dispatch slots and their runs. A run you start by hand on a member Task is adopted, never duplicated.
+
+## relay_plan_create
+
+Create a persisted, versioned plan DAG attached to a message thread/channel. Node scope prose is not accepted; put durable detail in the linked Task or issue. threadId is optional — omit it and a thread is minted server-side (#1035), so a fresh coordinator needn't send a throwaway message just to anchor a plan. A bound node's status auto-advances to landed when its refs.taskId Task reaches done/landed or its refs.issueId closes completed (#2520); a manual node is never auto-changed. acceptance (#2932) is required: the plan's own bar. Its completion reads open → conformance-pending (every node landed; the coordinator is notified) → done only after relay_plan_conformance records a pass. Landed nodes alone never make a plan done.
+
+- `nodes[].statusSource`: #2520 RESOLUTION — bound = externally driven: terminal signals from its refs.taskId/issueId advance it and reads project its Task status. manual = a human pin neither writes nor reads may override. Defaulting: a node carrying refs with no explicitly-chosen status derives to bound; an explicitly-set status derives to manual; an explicit statusSource always wins.
+- `nodes[].refs.issueId`: issue_<id>, #number, owner/repo#number, or a GitHub issue URL. A bare #number resolves against the calling agent's own project repo (cwd → project → issueRepo), falling back to HUMWICK_DEFAULT_ISSUE_REPO/GITHUB_REPOSITORY (#220) — it throws if neither is configured.
+- `acceptance`: Required (#2932): the plan's own bar — what must hold on main once every node lands, e.g. the design doc's deliverables, deletions and acceptance commands. One checkable item each. Relay records each check; the coordinator (or a fresh agent) runs it on main and reports the verdict with relay_plan_conformance.
+- `acceptance[].text`: A checkable deliverable, deletion or behavior.
+
+## relay_plan_delete
+
+Delete a persisted plan DAG and archive its latest version.
+
+## relay_plan_get
+
+Fetch a plan by planId, teamId, or by threadId/channel. A teamId resolves to the most recently updated non-archived plan (list them with relay_plan_list). Bound nodes project from their Task. Pass view:'tasks' with a teamId to get the pure task-backed DAG synthesized from deliverable Tasks + task_dependencies (no plan row required). mode controls verbosity: 'lean' (DEFAULT) emits one pointer string per node (T<id>/#<num> + label) with no inline scopeBlurb, keeping id/status/refs/ownerRef/lane and all edges; 'brief' is bare numbers + status AND collapses fully-settled landed leaves (reporting omittedCount); 'resume' is a token-budget-aware cold-resume envelope (active frontier ordered blocked>in-progress>pending + landed-with-active-dependent, counts, title-only objective, optional maxNodes cap, omittedCount); 'full' (= verbose:true) is the complete inline document.
+
+- `maxNodes`: resume mode only — cap the rendered node count by priority order; the remainder is surfaced as omittedCount, never silently dropped.
+
+## relay_plan_list
+
+List a team's non-archived plans as metadata (id, title, objective, version, node/edge counts, completion for plans with acceptance, timestamps), newest-updated first — the first entry is what relay_plan_get {teamId} resolves to. Paged: pass the returned nextCursor back as cursor; limit defaults to 20 (max 100). Fetch a plan's graph with relay_plan_get {planId}. channel filters by channel.
+
+## relay_plan_remove_edge
+
+Remove a dependency edge from a plan DAG.
+
+## relay_plan_remove_node
+
+Remove a node and its connected edges from a plan DAG.
+
+## relay_plan_update_node
+
+Update a plan node, including manual status changes. Plan-node scope prose is not accepted; put durable detail in the linked Task or issue. Returns a lean receipt (planId, version, the changed node ref, nodeCount/edgeCount); pass verbose:true for the full projected plan (#2081).
+
+- `statusSource`: #2520 RESOLUTION — bound = externally driven: terminal signals from its refs.taskId/issueId advance it and reads project its Task status. manual = a human pin neither writes nor reads may override. Defaulting: a node carrying refs with no explicitly-chosen status derives to bound; an explicitly-set status derives to manual; an explicit statusSource always wins.
+- `refs.issueId`: issue_<id>, #number, owner/repo#number, or a GitHub issue URL. A bare #number resolves against the calling agent's own project repo (cwd → project → issueRepo), falling back to HUMWICK_DEFAULT_ISSUE_REPO/GITHUB_REPOSITORY (#220) — it throws if neither is configured.
+
+## relay_team_claim
+
+Claim an existing active team by id for the caller's coordinator identity, adopting its brief, plan, blackboard, and roster. A replacement coordinator may take over a team whose owning coordinator has gone offline/stale (orphan-team failover recovery); a healthy owner's team stays unclaimable. Pass an optional reason for the audit trail. Returns a lean receipt by default (rosterSummary, briefLen/definitionOfDoneLen); pass verbose:true for the full (paginated) roster.
+
+- `verbose`: Include the full member roster instead of just rosterSummary. Even verbose is paginated — use offset/limit to page.
+- `offset`: Roster pagination offset when verbose:true (default 0).
+- `limit`: Max roster entries to return when verbose:true (default: all, subject to a hard size cap).
+
+## relay_team_dissolve
+
+Dissolve the caller's team and freeze the composition/outcome snapshot. Does not kill members.
+
+## relay_team_get
+
+Return the caller's team row, shared brief/definition of done (plus their lengths), rosterSummary (total/live/omitted), associated issues, and any bound plan. The member roster is omitted by default — pass verbose:true for the full (paginated) roster.
+
+- `verbose`: Include the full member roster instead of just rosterSummary. Even verbose is paginated — use offset/limit to page.
+- `offset`: Roster pagination offset when verbose:true (default 0).
+- `limit`: Max roster entries to return when verbose:true (default: all, subject to a hard size cap).
+
+## relay_team_set_brief
+
+Create/update the caller's team brief, title, and definition of done. Lazily mints a team when needed. Returns a lean receipt by default (briefLen/definitionOfDoneLen, rosterSummary) so a malformed write is visible without an unreadable payload; pass verbose:true for the full (paginated) roster.
+
+- `verbose`: Include the full member roster instead of just rosterSummary. Even verbose is paginated — use offset/limit to page.
+- `offset`: Roster pagination offset when verbose:true (default 0).
+- `limit`: Max roster entries to return when verbose:true (default: all, subject to a hard size cap).
+
+## relay_team_template_delete
+
+Delete one saved team template by slug.
+
+## relay_team_template_get
+
+Fetch one saved team template by slug.
+
+## relay_team_template_list
+
+List saved team templates.
+
+## relay_team_template_save
+
+Create/update a reusable team template, or capture one from a dissolved team's frozen composition by passing teamId.
+
+- `teamId`: Capture from this dissolved team's frozen composition snapshot instead of passing composition.
+
+## relay_workflow_cancel
+
+The caller or Task coordinator may end a running or escalated workflow run `cancelled`, with your `reason` on it. A running run stops at once: no step is entered or routed after it, and its step agents are shut down per each step's `reap` (an agent with unlanded work is kept). The Task, its review hold, any delivery and an armed land stay as they are: clear the hold, withdraw the land (relay_task_withdraw_land) or cancel the Task yourself. A run also ends cancelled on its own when its Task is canceled. A done run refuses; a repeat returns the run with cancelled:false. Returns the run as relay_workflow_get shows it, plus cancelled.
+
+- `runId`: The run to end.
+- `reason`: Why, recorded on the run as its reason.
+
+## relay_workflow_get
+
+Read one workflow run: lean by default (status, step, round, awaiting, agents with ids and lifecycle state, lastRound with short summaries, reason and output). Pass verbose:true for the complete round history, findings, declared steps, pins, resumes, agent reports and up to 200 scriptRuns with logArtifactId and scriptOutputs. Pass scriptRunsCursor as scriptCursor for the next page. Held messages are returned only with includeHeld:true, independently of verbose. Visible to the run's coordinator, the Task's coordinators and admins.
+
+- `runId`: The runId relay_workflow_start returned.
+- `verbose`: Return full history, findings and agent reports (default false).
+- `includeHeld`: Include held messages (default false, even with verbose).
+- `resultsRef`: Container reference for input-ordered item results.
+- `scriptCursor`: The previous response's scriptRunsCursor; reads the next 200 script attempt logs with verbose:true.
+
+## relay_workflow_resume
+
+Coordinator-only (#3045): after a workflow escalation (a bound hit, a failed or blocked step, a step timeout, a stopped land or red CI on main) and once you fixed its cause, re-enter the same run at the escalated step, or at `step`. `note` goes to that step's agent: the warm builder gets it as a message, a fresh agent as its steer. The run keeps its round history, gets a fresh bound budget and step deadline, holds your contact again and still ends with one result. A run waiting on its land renews that wait at `land`; resumed at an earlier step it first holds the Task again (withdrawing the stopped land), and if the land wins that race the run ends done with its result. Naming `step: land` on a run that escalated before its land is an explicit override: it clears the review hold and arms the land of the last delivered head, even after a NO-GO. After the land only `ci-main` resumes: it re-checks CI with a fresh deadline. `pins` replaces the start pins of each step it names (an empty object clears that step's back to the YAML); later dispatches use them. Only the Task's newest run resumes, and each escalation once: a repeat returns the run with resumed:false.
+
+- `runId`: The escalated run.
+- `activationId`: Explicitly retry this failed for-each item; completed slots remain committed.
+- `step`: Where to re-enter: a declared step, land (an explicit override of the review verdict) or, after the land, ci-main. Default: the step that escalated.
+- `note`: Your decision for the step's agent (what to fix, what to ignore).
+- `pins`: Per-step pins { <step>: { provider?, model?, effort?, orchestratorId?, profile? } }. Each field set wins over the YAML step's same field, which wins over the role file, which wins over the Task's dispatch policy. A provider pin wins over the step's crossProvider. A model pin needs its provider (here or in the YAML). `profile` replaces the base profile the step's role extends (e.g. worker-gui for a UI builder). An invalid pin for its host fails the call before anything spawns.
+
+## relay_workflow_start
+
+Run the repo's declared workflow `.agent-relay/workflows/<workflow>.yaml` on a Task, else Relay's bundled workflow of that name (build-review), read with its roles at the landed default-branch commit (a branch cannot change the workflow that reviews it); a repo role file of a step's role name wins over the bundled role. Relay sets the Task's review hold, dispatches each step's role, routes every typed delivery (disposition or gate verdict), loops findings back to the warm builder within the declared bound, clears the hold on GO and reports one result when the branch lands; a bound hit escalates with compact history and a reference to full findings; a step (or the land) past its YAML `timeout` alerts you once and keeps waiting; with `ci-main` declared the run then waits for CI on main and the result reports CI pass, red or no CI (red alerts you once first). You hear only: started, a step spawn failure, the escalation, the result; step agents' ready/exit and turn-final reports stay on the run, and the run reaps its agents per step `reap`. A step agent that exits without a delivery (gone 5 minutes) is that step's `exited` outcome, which escalates unless the workflow routes it; canceling the Task ends the run cancelled, and relay_workflow_cancel ends it on request. Steps may be pinned to a provider, model, effort and host (`pins`, or the same fields in the YAML step); pins persist across fix rounds and resumes. Returns {runId, workflow, source (bundled | project | project-overrides-bundled), sha, status, step, round, steps[] with each step's applied pin}. Workers may start workflows on their own Tasks when child workflows are enabled; project-declared workflows or the profile allowlist apply, with per-caller concurrent-run and per-run live-agent limits. Relay spawns every step in the caller’s tree, returns the result to the caller and cancels runs when the caller is reaped. One open run per Task; a repeat returns it (a repeat with other pins is refused).
+
+- `workflow`: Workflow name: .agent-relay/workflows/<workflow>.yaml on the default branch, else Relay's bundled one (build-review).
+- `taskId`: Task id (TNNNN accepted).
+- `pins`: Per-step pins { <step>: { provider?, model?, effort?, orchestratorId?, profile? } }. Each field set wins over the YAML step's same field, which wins over the role file, which wins over the Task's dispatch policy. A provider pin wins over the step's crossProvider. A model pin needs its provider (here or in the YAML). `profile` replaces the base profile the step's role extends (e.g. worker-gui for a UI builder). An invalid pin for its host fails the call before anything spawns.
+- `budget`: Observed token cap for this run's step agents and descendants. Ignored when the server sets HUMWICK_DELEGATION_TOKEN_BUDGETS=0; at the cap new spawns are refused and the owner is notified once. Running work can finish.
+- `inputs`: Declared workflow application inputs.
+- `requestKey`: Root creation retry key.
+
+## relay_plan_import
+
+Import a client-read version 1 YAML/JSON plan; the SDK exports
+`PLAN_IMPORT_DOCUMENT_SCHEMA`. Pass `document`, `format`, `expectedVersion`
+(0 for a new plan), and a stable `requestKey`. Set `dryRun:true` to preview
+resolved recipes, field changes, conflicts and omitted task keys without writes.
+
+Source `key` and per-task `key` preserve identities. Change `revision` for source
+changes. Updates require the current plan version. Local edits to imported fields
+conflict; execution is one atomic field. Omitted Tasks and fields remain intact.
+Refs add canonical issue references. Parents map to Task hierarchy, separately
+from `dependsOn`. Stage/proof declare intent; they do not certify proof or enforce
+a stage transition. A commit imports atomically and never starts workflows; use
+`relay_plan_start` explicitly. Retry the same request to recover its durable receipt.