@humwick/server 0.0.0-stage → 0.130.1

package/docs/guides/tools-execution.md

@@ -0,0 +1,48 @@
+---
+title: Relay tool reference — execution
+summary: Tool behavior, constraints and parameter details for execution.
+tags: [tools, mcp, execution]
+---
+
+Read these details when a tool's compact schema is not enough. Names and input contracts are unchanged.
+
+## relay_cancel_timer
+
+Cancel one of your durable Relay timers. Accepts id as an alias for timerId, matching the id returned by relay_schedule_timer. Admin callers may cancel any timer.
+
+- `id`: Alias for timerId (matches the `id` field returned by relay_schedule_timer).
+- `requestId`: Optional stable cancel request id for retry deduplication.
+
+## relay_list_timers
+
+List your durable Relay timers. Admin callers may pass createdBy to inspect another creator.
+
+## relay_run
+
+Run a shell command through Relay's bounded executor. Use this for any command that may print secrets (ssh, env/config reads, secret tooling), and for scripts, gates and test runs. Output is masked by the pinned agent-redact before reports and log artifacts; masker failures withhold output. A completion wake is the final result; no status or log read is needed to establish it. timedOut:true means the command was killed, not that the tool response is missing. Nonzero exits are normal tool results: inspect exitCode, signal and timedOut. the run cannot hang — it is killed (SIGKILL, whole process group, so detached children die too) at maxMs of RUN time (default 45 min; gate queue time, including gate-slot waits inside the shell, does not count; a separate 24h overall ceiling bounds waits), and output is capped (tails clipped to 8000 chars per stream; full output in the log artifact, readable with runId + log). For a quick inline result, pass waitMs (<=10s). Default 0, waitMs 0 and detach all wait up to 10s for a fast inline result, then return the runId and wake you once on completion. Waits above 10s are clamped; longer blocking waits are unsupported. A long command (gate, test suite, build): pass waitMs 0 (or detach). Waiting for a condition (deploy, land, health, file) is also a long command: one detached run whose command is a poll loop with a deadline; never one check per turn, each turn end is forwarded to your parent. If the call returns status "queued" or "still-running": Unless this run's completion is already in your context, END YOUR TURN NOW. Relay wakes you once on finish, failure or timeout. If the result is already present, handle it and continue working. Do not poll, sleep, tail or ps. Runs under `bash -o pipefail -lc`, so `cmd | tail` fails when `cmd` fails (and `cmd | head` can exit 141 on SIGPIPE; redirect to a file instead). Runs in your own authorized cwd; grants no reach you do not already have.
+
+- `command`: Shell command to run. Required unless runId is given.
+- `cwd`: Working directory. Defaults to your own agent cwd (your worktree, if you have one). Must stay inside it.
+- `env`: Optional string environment overrides.
+- `waitMs`: How long this call may block. 0 = detached: wait briefly for a fast inline result, otherwise return the runId and wake once. Default 0, values above 10000 are clamped. Long commands must use 0.
+- `detach`: Same as waitMs 0: wait briefly for a fast inline result, otherwise return the runId. End your turn unless the completion is already in context.
+- `maxMs`: Hard ceiling on execution time, excluding outer admission and gate-slot waits inside the shell; queueDurationMs and runDurationMs report the two clocks. A separate 24h overall ceiling bounds waits; a running command is killed at it. Default 2700000, max 86400000. A gate run holding the host's heavy-gate slot is capped at 5400000 (#3020); runDeadlineAt reports the overall wall-clock ceiling. Must be >= waitMs when given.
+- `expectedMs`: Expected run time. When maxMs is not given it defaults to 4x this.
+- `runId`: Non-blocking status read of a run you already started. Not for polling: a read less than 60s after the previous contact is refused; end your turn instead.
+- `log`: With runId: read a page of that run's own full log (the log artifact) instead of its status; only runs you started. Use it instead of redirecting output to a file. Not a poll: it never stamps contact or retires the run.
+- `log.grep`: Case-insensitive literal; `a|b` matches either. Lines are numbered when set.
+- `log.tail`: Last N (matching) lines. Not with offset/limit.
+- `log.offset`: Skip N (matching) lines. A page that stops early returns nextOffset (and nextColumn when it cut inside a line).
+- `log.column`: Start this many characters into the first returned line: pass nextColumn to continue a line the page cut.
+- `log.limit`: Lines from offset (default 200).
+
+## relay_schedule_timer
+
+Create a durable Relay timer that wakes a target by enqueueing a normal Relay message when due. With command, runs a background orchestrator command and wakes on exit or afterMs timeout.
+
+- `target`: Defaults to me. Supports agent id, policy:name, label:x, channel targets, and other normal Relay targets.
+- `at`: Future ISO timestamp.
+- `command`: Optional background shell command. Requires command:write. When set, afterMs is the max timeout and everyMs/at are rejected.
+- `cwd`: Command working directory. Must resolve inside an online orchestrator baseDir. Defaults to the caller agent cwd when available.
+- `env`: Optional string environment overrides for the command.
+- `requestId`: Stable client-generated id for one logical MESSAGE scheduling request; reuse it across retries. Distinct from idempotencyKey. Not required for command timers.

package/docs/guides/tools-issues.md

@@ -0,0 +1,69 @@
+---
+title: Relay tool reference — issues
+summary: Tool behavior, constraints and parameter details for issues.
+tags: [tools, mcp, issues]
+---
+
+Read these details when a tool's compact schema is not enough. Names and input contracts are unchanged.
+
+## relay_issue_activity_by_agent
+
+List IssueRefs and actions touched by one agent.
+
+## relay_issue_activity_by_issue
+
+List agents and actions recorded for one internal IssueRef id.
+
+## relay_issue_activity_record
+
+Record that an agent read, edited, or completed work for an IssueRef. Accepts issueRefId or a raw issueRef string such as #473 or owner/repo#473.
+
+## relay_issue_association_associate
+
+Associate a canonical IssueRef with a team, plan-node, or epic. Accepts issueRefId or raw issue coordinates and stores only the internal IssueRef id.
+
+## relay_issue_association_list_entities_for_issue
+
+List teams, plan nodes, and epics associated with an IssueRef. Accepts issueRefId or raw issue coordinates.
+
+## relay_issue_association_list_issues_for_entity
+
+List IssueRefs associated with a team, plan-node, or epic.
+
+## relay_issue_association_remove
+
+Remove one issue/entity association. Accepts issueRefId or raw issue coordinates.
+
+## relay_issue_lifecycle_reopen
+
+Reopen a canonical IssueRef through its tracker adapter, update cached status to open, and optionally re-associate it with a team, plan-node, or epic.
+
+## relay_issue_ref_delete
+
+Delete an IssueRef mapping row. Foundation-only cleanup; lifecycle automation lives elsewhere.
+
+## relay_issue_ref_get
+
+Fetch one IssueRef by its opaque internal id.
+
+## relay_issue_ref_list
+
+List IssueRefs, optionally filtered by provider, repo, or cached status.
+
+## relay_issue_ref_resolve
+
+Resolve a raw issue string (`#466`, `owner/repo#466`, GitHub issue URL, or `issue_<uuid>`) or provider/repo/externalKey to the canonical IssueRef.
+
+- `closeReason`: #2520 — GitHub close classification; only valid when status is 'closed'
+
+## relay_issue_ref_update
+
+Update cached IssueRef display fields without changing provider/repo/externalKey.
+
+- `closeReason`: #2520 — GitHub close classification; only valid when status is 'closed'
+
+## relay_issue_ref_upsert
+
+Create or update the canonical IssueRef for provider/repo/externalKey. Idempotent for the same external issue.
+
+- `closeReason`: #2520 — GitHub close classification; only valid when status is 'closed'

package/docs/guides/tools-memory.md

@@ -0,0 +1,150 @@
+---
+title: Relay tool reference — memory
+summary: Tool behavior, constraints and parameter details for memory.
+tags: [tools, mcp, memory]
+---
+
+Read these details when a tool's compact schema is not enough. Names and input contracts are unchanged.
+
+## relay_blackboard_get
+
+Fetch one blackboard entry and its supersession chain for the caller's team.
+
+## relay_blackboard_read
+
+Read the caller team's active blackboard working set, optionally filtered by kind.
+
+## relay_blackboard_retract
+
+Retract a blackboard entry for the caller's team without deleting its ledger row.
+
+## relay_blackboard_search
+
+Search active blackboard entries for the caller's team by title, body, or tags.
+
+## relay_blackboard_write
+
+Create a team-scoped blackboard entry. The caller's token identity determines the team and author.
+
+## relay_compact_and_resume
+
+Self-resume this same agent: Relay stores a lossy continuity-of-intent envelope (full prior detail remains searchable with relay_recall), then compacts/clears in place or transactionally swaps the whole process with restart=true. Restart is Phase 1 coordinator/steward-only and requires an idle, committed safe point.
+
+- `workingState`: Current replaceable working state for the next generation. REPLACES the previous generation's working state — send the state as it stands now, not the previous text plus an update. Identical repeated blocks are collapsed to a single copy on store.
+- `restart`: Spawn and register a fresh Runner/process with a freshly minted current-profile token before tearing down this process.
+- `reason`: Hard restart only (`restart: true`); ignored otherwise.
+- `objective`: Relay-owned objective. Seeds the first envelope; on an existing envelope, replaces the live objective and starts a new ledger-render epoch. This tool remains self-only.
+
+## relay_project_add_edge
+
+Add a composition-graph edge between two projects. `contains` (umbrella→sub-project) inherits — the sub-project's reads pull in the umbrella's entries. `depends_on` is reference-only and never inherits. Cycles are rejected.
+
+- `from`: Source project id or slug (the umbrella for `contains`, the consumer for `depends_on`).
+- `to`: Target project id or slug (the contained sub-project, or the dependency).
+
+## relay_project_add_root
+
+Create-or-update a project by slug and register a repo root path. The create-on-first-use entry point for a new project.
+
+- `issueRepo`: Explicit owner/repo for #NNN linkify; overrides the git-remote-derived default.
+
+## relay_project_archive
+
+Archive or restore a project. Keeps checkouts and memory.
+
+## relay_project_checkout
+
+Read checkout status, bind an existing checkout to a host without cloning, syncing or installing, unbind it, or remove it. Bind validates its origin.
+
+- `unbind`: drops that host's binding and keeps every file. Refresh, spawn and gate placement stop using that root on that host. No host command.
+- `remove`: DELETES the checkout directory and its linked worktrees on that host. Requires `deleteFiles: true`. Returns a command; the host refuses on live agents on that host, open workspaces, local changes or unpublished commits.
+
+## relay_project_get
+
+Fetch one project and its registered roots. Defaults to the caller's resolved project (from its spawn cwd) when `project` is omitted.
+
+- `project`: Project id or slug; defaults to the caller's project.
+
+## relay_project_ingest_claudemd
+
+Ingest CLAUDE.md from each registered root of a project into project_entries (source:'ingested'), one entry per heading section. Idempotent: re-running supersedes prior ingested entries from the same file/section, retracts vanished sections, and never touches manual/promoted entries. Defaults to the caller's project.
+
+- `project`: Project id or slug; defaults to the caller's project.
+
+## relay_project_journal_get
+
+Read this project's structured journal for YOUR profile: current field values with staleness and updater (absent fields shown as unset). `history:true` also returns the append-only diff-log (old→new per change); `field` filters to one field.
+
+- `field`: Optional single-field filter.
+- `history`: Also return the append-only change history (newest first).
+
+## relay_project_journal_update
+
+Set and/or clear fields of this project's structured journal for YOUR profile — overwrite-by-field, unlike memory entries (a field's new value replaces the old; it never stacks). One call may touch any subset of the five fields; pass a string to set, null/"" to clear. Clearing removes the field from injection but keeps its diff-log history.
+
+- `spawn_strategy`: Spawn Strategy — a string (≤4000 chars) to set, or null/"" to clear.
+- `operator_standing_directives`: Operator Standing Directives — a string (≤4000 chars) to set, or null/"" to clear.
+- `active_objectives`: Active Objectives — a string (≤4000 chars) to set, or null/"" to clear.
+- `open_risks_watchlist`: Open Risks / Watchlist — a string (≤4000 chars) to set, or null/"" to clear.
+- `live_env_quirks`: Live Env Quirks — a string (≤4000 chars) to set, or null/"" to clear.
+
+## relay_project_list
+
+List the durable projects (the cross-repo knowledge scopes).
+
+## relay_project_onboard
+
+Import a GitHub repository or create one with host gh credentials, then import it on selected hosts. Creation returns creation.commandId; its result.onboarding contains checkout commands and optional setupTaskId. Completion notices wake the calling agent.
+
+## relay_project_promote_entry
+
+Promote an active blackboard finding (`bb_…`) into durable project knowledge as a `promoted` entry whose `origin_ref` back-references the blackboard id (decision→decision, fact→fact, ruled_out→rule). Explicit only — nothing auto-promotes. Re-promoting the same finding supersedes the prior copy. Defaults to the caller's project.
+
+- `blackboardEntryId`: The bb_… blackboard entry to promote.
+- `project`: Project id or slug; defaults to the caller's project.
+
+## relay_project_read
+
+Read active entries, optionally filtered by kind or `ids` (the injected memory index's by-id body fetch). With ids and no project, reads the caller's base/provider/host/project memory chain, filtered by audience; no registered project is required. An explicit project restricts reads to that project. Other reads default to the caller's project. Includes transitive contains-ancestors unless includeInherited:false; depends_on targets are never folded in. For inactive entries, name a project or use the caller's project.
+
+- `ids`: Return only these entry ids. Without project, active ids resolve in your project knowledge and its ancestors; omit ids for the whole project.
+- `includeInherited`: Default true: merge in contains-ancestor entries. Set false for only this project's own.
+
+## relay_project_remove_edge
+
+Remove a composition-graph edge between two projects. `from`/`to` are project ids or slugs.
+
+## relay_project_retract
+
+Retract a project entry without deleting its ledger row. Defaults to the caller's project.
+
+## relay_project_search
+
+Ranked full-text search of active project entries (any term; title matches first). Defaults to the caller's project. Returns lean hits with score and a short snippet (brief drops the snippet), 10 by default, at most 50, paged within the list budget. Fetch full bodies with relay_project_read({ ids }).
+
+- `limit`: Default 10; capped at 50.
+
+## relay_project_write_entry
+
+Create a project-scoped entry (rule/fact/decision/memory). Defaults to the caller's project if `project` is omitted.
+
+- `project`: Project id or slug; defaults to the caller's project.
+- `audience`: `self` (default — your own profile, resolved from your token; falls back to `all` when you have none), `all` to share it with every role, or an array of any profile names (no forced self-inclusion — omit to keep your own, name others to share or hand off). Omitted on a `supersedes` edit inherits the replaced entry's audience instead of narrowing it.
+- `inject`: Injection tier. pinned = full body in every spawn (only a coordinator or the operator may pin; anyone else's pin is stored as indexed and the result says so), indexed = headline + id, never = retrieval-only. Agent writes default to indexed; a supersede keeps the prior tier.
+- `areas`: 1-4 areas this memory is about. Name a path area from the project's .agent-relay/areas.json when the lesson is about specific code (delivered when an agent touches it), else a system area: project-wide, process or tooling (delivered at startup). Required when the project declares areas; a refusal lists them, and a supersede without areas keeps the prior ones.
+- `supersedes`: Id of the entry this one replaces. Omitted `body`, `tags`, `areas` and `audience` carry over from it; pass one to change it.
+
+Path areas come from `.agent-relay/areas.json` on the project's default branch (`origin/<default>`, fetched before each read), never from a working tree, so a stale checkout cannot hide them. Limits: 1-32 areas; each area has a name (`[a-z][a-z0-9-]*`, up to 32 chars, not a system area), 1-16 repo-relative path globs (up to 200 chars, not starting with `/` or `**`, no `..`) and a description of up to 200 chars. When the file is invalid, the refusal names the error (for example `areas[2].paths must be an array of 1-16 globs`) and only system areas are accepted until it is fixed on the default branch.
+
+## relay_recall
+
+Search this same agent's archived pre-compaction segments. Search returns bounded snippets with refs; pass a returned ref to fetch its full segment. Self-only: caller identity comes from the MCP token.
+
+- `query`: Keyword query over archived compact/clear segments.
+- `ref`: Fetch one full archived segment by a ref returned from search.
+
+## relay_secret_project_create
+
+Create an Infisical project through the Relay secrets broker (or return the existing one with that name). The operator becomes project admin and host tool identities become viewers. You never see the broker credential.
+
+- `name`: Project name (letters, digits, space, . _ -; max 64).

package/docs/guides/tools-messages.md

@@ -0,0 +1,192 @@
+---
+title: Relay tool reference — messages
+summary: Tool behavior, constraints and parameter details for messages.
+tags: [tools, mcp, messages]
+---
+
+Read these details when a tool's compact schema is not enough. Names and input contracts are unchanged.
+
+## relay_attach_artifact
+
+Attach an existing Relay artifact to a message, task, recipe run, recipe step, or channel event.
+
+## relay_channel_output
+
+Read, pause or resume a channel's ambient output. Timed pauses auto-resume; levels keep tracking while paused.
+
+## relay_delete_channel_binding
+
+Remove a conversation binding owned by this channel bridge. Requires its current instanceId and optional epoch; deleted topics can then be recreated on the next sync.
+
+## relay_find_agents
+
+Search the fleet by label, capability, provider, tag, Relay-owned system tag, machine, status, or kind, sorted by last-active/created/label. Returns a lean roster summary by default (id, label, status, machine, provider, model, lastSeen, spawnedBy, teamId); verbose:true returns full agent cards. Defaults to running agents only.
+
+- `label`: Substring match on label or name.
+- `capability`: One or more capabilities (OR within).
+- `provider`: Model provider, e.g. claude or codex.
+- `systemTags`: Require every Relay-owned system tag.
+- `status`: online/idle/busy/offline/stale, the 'running' shorthand, or 'all'. Default 'running'.
+- `spawnedBy`: Parent agent id, or 'me' for your own spawned children.
+- `teamId`: Durable team id for roster filtering.
+- `offset`: Pagination offset (default 0). Lean/brief pages fit the list budget and continue via `outputPage.next`; verbose returns `nextOffset`.
+- `verbose`: Return full agent cards instead of the lean roster summary. Even verbose results are paginated; use offset+limit to page.
+
+## relay_get_message
+
+Read one message. `verbosity` defaults to `lean` (legacy `level` also works): the first 3,000 UTF-16 characters retain the leading summary/verdict. `brief` omits text; `verbose` reads up to 6,000 characters per page and retains message metadata. Every level preserves message/thread/reply IDs, routing and delivery status.
+
+`message.bodyPage` reports `offset`, `length`, `total`, `truncated`, and `next`. A truncated page is a preview, not a complete report. Call `relay_get_message` with the exact arguments in `next` until it is null; concatenate the returned `body` strings in order to reconstruct the exact body. Cursors stay on their message and count UTF-16 characters, keeping surrogate pairs together. Brief starts its read cursor at zero.
+
+Artifact metadata is opt-in with `includeArtifacts: true` (default false). This keeps the existing scoped artifact lookup. `includeThread: true` includes the first thread page, with the same projection and cursor as `relay_get_thread`.
+
+## relay_get_thread
+
+Read the thread containing `messageId`, three rows per page in creation/id order. `level` accepts `brief`, `lean` (default, 160-character leading previews), or `verbose` (6,000-character body pages). Follow `threadPage.next` with `relay_get_thread` to read remaining rows; each row's `bodyPage.next` is a `relay_get_message` request for its remaining body. `includeThread` on a message also uses this row paging. Artifact metadata is available through `relay_get_message` with `includeArtifacts: true`.
+
+Cursor requests are returned as ready-to-call arguments. Reuse them as given. Detailed bodies and thread rows have separate cursors; neither a truncated body nor one thread page is the complete report.
+
+## relay_guide
+
+Read current Humwick user guides from the running server. List the index, search by keywords, or get one guide by id. No project checkout is needed. Each response includes the server version and each guide's content revision.
+
+- `query`: Keywords for search.
+- `id`: Guide id from the index.
+
+## relay_interrupt_agent
+
+Interrupt one of your live spawned children without ending its session. stop cancels the active turn; redirect cancels it and delivers message as the next turn. An agent caller may target only its OWN spawned children by agentId; admin tokens keep full reach.
+
+- `message`: Required when mode is redirect; ignored for stop.
+
+## relay_list_artifacts
+
+List Relay artifacts attached to a task or message (newest first), with ids for relay_read_artifact.
+
+- `taskId`: Task id (TNNNN accepted).
+- `createdBy`: Only artifacts this actor created.
+
+## relay_list_subscriptions
+
+List this caller agent's durable notification subscriptions.
+
+## relay_notification_preview
+
+Dry-run notification routing for a type and scope, returning recipients and matched rules without sending.
+
+- `scope`: Notification scope, such as { author, teamId, repoRoot, workspaceId }.
+
+## relay_notify_ntfy
+
+Send an egress-only ntfy notification to the configured operator topic. Supports title, body, priority min→urgent, optional tags, and click-through link.
+
+## relay_pin_artifact
+
+Pin an artifact to keep it from all automatic sweeps, or unpin it to apply retention again.
+
+## relay_read_artifact
+
+Read a Relay artifact by id (any agent's: probe bundles, land-gate output, reports). Text pages like relay_run logs; binary content is not inlined, and the result names the CLI command that saves it on your host.
+
+- `artifactId`: Artifact id (art_…).
+- `grep`: Case-insensitive literal; `a|b` matches either. Lines are numbered when set.
+- `tail`: Last N (matching) lines. Not with offset/limit.
+- `offset`: Skip N (matching) lines. A page that stops early returns nextOffset (and nextColumn when it cut inside a line).
+- `column`: Start this many characters into the first returned line: pass nextColumn to continue a line the page cut.
+- `limit`: Lines from offset (default 200).
+
+## relay_red_main_recover
+
+Bind your delivered fix as the recovery land of a red-main incident (#3363). While the incident is open only this land may claim its lane; the incident resolves when main CI is green at or after it. Deliver the fix first: the workspace needs a pending land command.
+
+- `incidentId`: The red-main incident id from the escalation message or the Shipping page.
+- `workspaceId`: Defaults to your own workspace.
+
+## relay_reevaluate_channel_delivery
+
+Re-evaluate a channel-suppressed message against the current allowlist and release it if eligible.
+
+## relay_reply
+
+Reply to a message by id, preserving reply/thread/channel context (`message` aliases `body`). Returns a delivery receipt; expectReply:false means the original sender is unreachable.
+
+- `from`: Deprecated/optional — identity comes from your auth token; you never need to set this.
+- `message`: Alias for body.
+- `urgent`: Request urgent handling. Subject to the per-recipient budget.
+- `verbose`: Return the complete sent-message envelope, including body and subject.
+
+## relay_send_message
+
+Send an Humwick message (`message` is an alias for `body`). Returns a delivery receipt: expectReply:false means no live recipient — don't wait for a reply. Ambiguous targets are rejected; unknown targets are stored for delivery once that id registers (delivered:false, empty recipients, reason given) rather than dropped.
+
+- `from`: Deprecated/optional — identity comes from your auth token; you never need to set this.
+- `to`: Target: an agent id, label, name, or a unique id segment — resolved automatically. Durable single recipient: policy:<name>, coordinator:<teamId>. Fan-out: tag:, cap:, label:, team:, or broadcast.
+- `message`: Alias for body.
+- `urgent`: Request urgent handling. Subject to the per-recipient budget.
+- `requestId`: Stable client-generated id for one logical deliveryTime scheduling request; reuse across retries. Distinct from idempotencyKey.
+- `deliveryTime`: Future ISO timestamp; creates a one-shot durable timer instead of sending immediately. Requires schedule:write.
+- `verbose`: Return the complete sent-message envelope, including body and subject.
+
+## relay_send_to_channel
+
+Send an outbound message to a registered channel agent (e.g. ntfy, webhook). channelId is the channel agent ID; event is an opaque payload the adapter interprets.
+
+- `channelId`: Registered channel agent ID (e.g. 'ntfy:default').
+- `event`: Adapter-specific event payload.
+
+## relay_shutdown_agent
+
+Shut down an agent through Relay's orchestrator. Requires command:shutdown scope. An agent caller may only target its own live spawned children, by agentId or spawnRequestId — policyName/tmuxSession are admin-only broad targets.
+
+- `agentId`: Target child by agent id (identifies your spawned child for agent callers).
+- `policyName`: Broad target by managed-agent policy — admin/full-reach callers only.
+- `spawnRequestId`: Target child by the spawnRequestId relay_spawn_agent returned.
+- `tmuxSession`: Broad target by tmux session — admin/full-reach callers only.
+- `hard`: Kill the runner and provider processes without waiting for a turn boundary or graceful shutdown. Success requires confirmed death. Does not bypass the unlanded-work guard; use force separately. Default false.
+- `force`: Bypass the unlanded-work reap guard for an isolated-workspace agent — its branch's unlanded commits will be stranded. Default false.
+
+## relay_subscribe
+
+Subscribe, opt out, or mute this caller agent for a notification type, or opt into child streams. Child response streams are always on; toolCalls/reasoning/narrative are opt-in.
+
+- `mode`: Default opt_in. mute and opt_out suppress matching default deliveries.
+- `scope`: Optional partial notification scope match, such as { teamId } or { repoRoot }.
+- `taskId`: Subscribe to semantic transitions for one durable Task (TNNNN accepted).
+- `streams`: Child streams to opt into. responses is always on and is not persisted.
+- `childAgentId`: Limit child stream subscriptions to one spawned child.
+- `teamId`: Limit child stream subscriptions to children on a team.
+- `allChildren`: Subscribe for all children spawned by this caller. This is the default when childAgentId/teamId are omitted.
+
+## relay_unsubscribe
+
+Remove this caller agent's notification subscription by id, or by type/mode/scope. Omitting mode removes all modes for the matched type/scope.
+
+## relay_upload_artifact
+
+Upload an Humwick artifact. Prefer `path` for anything non-trivial (tarballs, log bundles, screenshots, binaries) — the file is read on your agent's host, so the bytes never pass through your context. `content`/`base64` are for small inline text and are capped well below what fits comfortably in a tool call; a large payload base64-encoded into `content`/`base64` will blow your context before it ever reaches the size cap, so use `path` instead.
+
+- `path`: Absolute filesystem path on your agent's host. Read by the local runner or the caller's orchestrator; callers without an agent identity read on the Relay host. Never pass file bytes through your context. Must resolve within your allowed workspace/cwd or your own $TMPDIR.
+- `content`: UTF-8 text content to store inline. Use `path` instead for anything beyond small text.
+- `base64`: Base64-encoded binary content to store inline. Use `path` instead for anything beyond small payloads.
+- `filename`: Defaults to the source file's basename when uploading via `path`.
+- `digest`: Optional sha256 digest for integrity verification.
+
+## relay_web_tool_calls
+
+Query the durable per-call web search/fetch log. Returns calls newest first and a nextCursor. Times are epoch milliseconds; status error selects all errors.
+
+## relay_whoami
+
+Return your own Relay identity and agent card (id, label, status, tags, capabilities). Your identity comes from your auth token — you do NOT need this to send, reply, or pair; use it only when you need to reason about yourself.
+
+- `verbosity`: Use `brief` for the minimal identity projection, or `verbose` for the full debug payload. Omitted returns the lean default operate-tier projection.
+
+## relay_why_notified
+
+Explain why this caller agent received a delivered notification message.
+
+- `messageId`: Delivered Relay message id.
+
+## web_search
+
+Search the web. Relay tries Tavily first and falls back to Brave within a fleet-wide $5 UTC monthly cap. Returns sources and the answering backend. Lean excerpts stop at 320 characters (`contentChars`/`contentTruncated` mark the cut; brief 160); verbose returns full text. A large `count` pages via `outputPage.next`, which repeats the search.

package/docs/guides/tools-operations.md

@@ -0,0 +1,133 @@
+---
+title: Relay tool reference — operations
+summary: Tool behavior, constraints and parameter details for operations.
+tags: [tools, mcp, operations]
+---
+
+Read/report tools accept `verbosity: "brief" | "lean" | "verbose"` (lean default).
+Brief preserves operational truth and shortens content; lean adds daily detail;
+verbose exposes requested detail with existing paging. `outputDetail`, when present,
+is a safe read request for a shortened mutation result. For read calls, repeat the
+same arguments with `verbosity:verbose` to recover shortened fields. Roster, search,
+Task and catalog lists page within a rendered-text budget (lean 4,000 characters,
+brief 2,000; held/blocked rows first). `outputPage` reports `total`, `offset`,
+`omitted` and `next`; follow `next` (tool and arguments, an `offset` cursor) until null.
+No `outputPage` means the whole list fit. Verbose stays complete; its explicit `offset`
+returns every remaining row. Message bodies retain `bodyPage`
+and threads retain `threadPage`; follow their `next` requests until null.
+
+Canonical verbosity wins over legacy selectors. Existing `verbose`, presentation
+`mode` (`full`/`default`), message `level`, and decision `detail` booleans remain
+accepted for compatibility. Plan `mode:resume` remains a compact frontier view; omit mode to request verbose. Operational
+modes/actions and free-text `detail` retain their meanings. Discovery advertises the
+canonical selector to avoid loading duplicate selectors every turn.
+
+Read these details when a tool's compact schema is not enough. Legacy inputs remain accepted.
+
+## relay_maintenance_jobs
+
+List scheduled maintenance jobs with their schedule, last run, criticality, and any operator pause. Use this to see whether a job is actually running before concluding the system is healthy. Lists return health rows in pages (`outputPage.next`); runbooks (`description`) and `lastResult` diagnostics are omitted.
+
+- `jobId`: Read one job completely, including its runbook and last result.
+
+## relay_maintenance_pause
+
+Pause a scheduled maintenance job (e.g. cd-watcher) with a required reason. The supported replacement for a direct UPDATE on maintenance_jobs, reachable from any host. Omitting both ttlMs and indefinite gives a 2h TIMED pause that lapses on its own — the safe default; an indefinite hold never lapses and is reported as degraded for as long as it is held. An existing active pause is returned as a conflict rather than having its holder and reason replaced.
+
+- `jobId`: Maintenance job id, e.g. cd-watcher.
+- `reason`: Why the job is being stopped. REQUIRED — a pause whose justification lives only in your head is the defect this fixes.
+- `ttlMs`: Pause duration in milliseconds. Defaults to 2h. Mutually exclusive with indefinite.
+- `indefinite`: Hold with no expiry, for "broken until fixed". Never lapses; permanently reported as degraded for a critical job.
+- `holder`: Optional human-readable holder. Defaults to the authenticated caller.
+
+## relay_maintenance_pauses
+
+List operator holds on scheduled maintenance jobs. Includes a LAPSED timed pause: "expired and nobody resumed it" is its own reportable state, so the row is kept until an explicit resume.
+
+## relay_maintenance_resume
+
+Release a maintenance-job pause and report the drift accumulated while it was held: how long it was paused, whether the pause had already lapsed, and the last deploy the fleet actually completed. Takes effect on the next scheduler tick (10s) — no restart needed.
+
+- `jobId`: Maintenance job id to resume.
+- `id`: Or the pause id directly.
+
+## relay_merge_pause
+
+Pause workspace auto-merge for one repo/base pair with a TTL. Existing active pause for the same target is returned as a conflict instead of replacing its holder.
+
+- `repoRoot`: Repository root whose auto-merge should pause.
+- `baseRef`: Base branch/ref to pause (default main).
+- `ttlMs`: Pause TTL in milliseconds. Defaults to the server's merge-pause TTL.
+- `holder`: Optional human-readable holder. Defaults to the authenticated caller.
+
+## relay_merge_pauses
+
+List active auto-merge pauses. These are repo/base-level holds that make the workspace auto-merge job yield during release or build critical sections.
+
+## relay_merge_renew
+
+Renew an active auto-merge pause by id, extending its TTL from now.
+
+## relay_merge_resume
+
+Release an auto-merge pause by id, or by repoRoot/baseRef.
+
+- `baseRef`: Base branch/ref (default main when repoRoot is used).
+
+## relay_workspace_claim
+
+Take a TTL'd steward claim on a workspace so the deterministic auto-merge yields to you while you reconcile a conflict. Renew/hold while validating; relay_workspace_release frees it. Owner or assigned steward only.
+
+- `workspaceId`: Defaults to your own isolated workspace.
+- `purpose`: Why you're claiming (shown in the activity feed).
+
+## relay_workspace_deps
+
+Re-provision your worktree's dependencies when the shared symlinked node_modules has gone stale (e.g. typecheck reports a missing module). checkOnly:true just reports staleness without changing anything. Self-service — acts only on your own worktree.
+
+- `workspaceId`: Defaults to your own isolated workspace.
+- `checkOnly`: Report staleness only; do not re-provision.
+
+## relay_workspace_list
+
+List the isolated workspaces you own (id, branch, status, repo). Use it when you're unsure which workspace is yours or to see a workspace's current state. Admin/server tokens may pass all:true to list every workspace.
+
+- `all`: Admin/server only: list all workspaces, not just your own.
+- `ownerAgentId`: Admin/server + all:true: filter to one owner.
+- `repoRoot`: Filter to one repository root.
+
+## relay_workspace_merge_hold
+
+Durably hold new merges for one workspace, including automatic retries after repo merge resume. Existing admitted lands are unaffected. No expiry; clear with relay_workspace_merge_resume.
+
+- `workspaceId`: Defaults to your own workspace.
+- `detail`: Operator reason for the hold or resume.
+
+## relay_workspace_merge_resume
+
+Clear one workspace merge hold and schedule its repo sweep. Other workspace holds and repo pauses remain effective.
+
+- `workspaceId`: Defaults to your own workspace.
+- `detail`: Operator reason for the hold or resume.
+
+## relay_workspace_release
+
+Release a steward claim taken with relay_workspace_claim, letting the auto-merge resume. Owner or assigned steward only.
+
+- `workspaceId`: Defaults to your own isolated workspace.
+
+## relay_workspace_status
+
+Get your isolated workspace's lifecycle status (active/ready/merge_planned/gate_running/gate_failed/merging/landed/conflict/...). When wait:true starts during an in-flight land, later in-flight phase hops do not complete the wait; do not use wait:true after relay_task_deliver unless explicitly debugging. Normal branch workers deliver the Task, stop their turn, and are woken later by landed-success or landed-failure notifications. Defaults to your own workspace; pass workspaceId to target another.
+
+- `workspaceId`: Defaults to your own isolated workspace (resolved from your identity).
+- `wait`: Block until a status change or the timeout. If waiting begins in an in-flight land phase, later in-flight hops (merge_planned → gate_running → merging) are skipped. Do not use this after relay_task_deliver in the normal worker flow; stop and wait for landed-success/landed-failure instead.
+- `timeoutSeconds`: Max seconds to wait when wait:true (default 300, max 600).
+
+## relay_secret_request
+
+To edit an existing secret without rotating, pass `name: "NAME@env"`, optional `scope`/`project`, and `metadata: {expiresAt?, revision?, sourceUrl?, hintEnabled?}`. Do not combine metadata with `reason` or `withdraw`. Text fields accept null to clear; omitted fields stay unchanged. `expiresAt` takes `YYYY-MM-DD` (stored as the end of that day in UTC) or an ISO timestamp with timezone; `sourceUrl` accepts http/https; revision is vendor text (max 500 characters). Edits return public metadata and record actor, time, field, old and new value in secret history. Hint is on by default, last four characters per version; turn it off per secret with `hintEnabled: false`. Values of four or fewer characters have no hint. Fingerprints are the first six SHA-256 hex characters per version.
+
+Request or rotate a named vault secret with `name`, a reason, and optional `scope` (`global` or `project`, with `project`; an agent defaults to its own project). The built-in vault is on unless the operator sets `HUMWICK_SECRETS_VAULT=0`. The operator receives a decision linking a one-time form; the requester receives only the name and version after submission. Use `secret:<name>` in spawn, profile, MCP server or `relay_run` env entries; the value reaches only that process environment. Never put a value in a message or command line.
+
+The server reads global `TAVILY_API_KEY`, `BRAVE_API_KEY`, and `CLAUDE_APP_PASSPHRASE` vault secrets directly, using the same `resolved` audit as `secret:` refs. Project secrets do not supply these credentials. If a name is absent (or the vault is disabled), the enabled Infisical broker remains a migration fallback: `fleet-shared prod:/tool` for search, `relay-claude-app prod:/oauth` for Claude app OAuth. A vault read failure is reported instead of falling back. `/api/health` reports the last observed source per credential under `server-credentials` without reading secret values. Search reads credentials on each request; Claude app OAuth loads its passphrase at startup. Live migration and cutover happen after deployment.