@humwick/server 0.130.1 → 0.130.3

package/README.md

@@ -77,6 +77,11 @@ claude plugin install agent-relay@agent-relay
 
 **Codex** (requires Bun + Codex CLI):
 
+First run `codex login` in the same home you will use for the runner. For Claude,
+run `claude auth login` and complete the standalone CLI’s first-run setup. Runners
+check that login before becoming ready. Setup errors appear on the dashboard and
+are returned when sending a message.
+
 ```bash
 bun install -g @humwick/runner@latest
 codex-humwick --cwd /path/to/project

package/bundled/prompts/manifest.json

@@ -103,6 +103,7 @@
         "intent",
         "context",
         "doneWhen",
+        "afterLand",
         "issues",
         "decisions",
         "history",

package/bundled/prompts/task.hydration.md

@@ -9,7 +9,7 @@ Intent (Task data):
 {{context}}
 Acceptance — done when:
 {{doneWhen}}
-
+{{afterLand}}
 Linked issue spec (resolved server-side once — do NOT re-read GitHub):
 {{issues}}
 

package/bundled/roles/builder.md

@@ -11,7 +11,7 @@ workspace: { mode: isolated }
 You implement the Task you are bound to and deliver it. The `build-review` workflow runs your delivery through a fresh reviewer; you do not choose when it lands.
 
 1. Read the Task and the repo's agent instructions (`CLAUDE.md`, `AGENTS.md` or `CONTRIBUTING.md`, whichever exist), and follow its conventions. Meet the Done-when exactly.
-2. Implement and prove the Task, then deliver `complete` per Delivery.
+2. Implement and prove the Task, then deliver `complete` per Delivery. Post-deploy, live-check and independent-proof criteria in the Done-when are checked after land by QA/onDeploy; they never block delivery. Deliver `complete` when code, tests and the delivery gate pass.
 3. A Relay message starting "returned NO-GO" carries the reviewer's findings for the head you delivered. Fix them and deliver `complete` again on the same Task; a fresh reviewer checks the new head. If a finding is wrong or conflicts with the Done-when, say so in the delivery `summary` and fix what is valid. Do not argue by message.
 4. Need a decision, a dependency or access you do not have: deliver `blocked` with `blockedBy`. Task cannot be done as written: deliver `failed` with the reason. Either one stops the workflow and goes to the coordinator with the history.
 

package/docs/guides/sub-coordinators.md

@@ -79,11 +79,18 @@ notice. Read or change the budget with `GET` or `PATCH
 
 ## 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.
+With `HUMWICK_CHILD_WORKFLOWS=1`, a sub-coordinator owns the workflow runs of a
+Task it created, a Task assigned to it (`relay_task_assign_agent`), or a Task in
+its private team. It can start, read (`relay_workflow_get`), resume, pause and
+cancel those runs, including a run the root started before it handed the Task
+down. Run escalations, results and coordinator decisions go to the
+sub-coordinator first. The root gets them only when the sub-coordinator is gone.
+A run on such a Task is the sub-coordinator's run, even when the root starts it:
+its step agents spawn under the sub-coordinator and count against its quota. The
+root coordinator keeps full control of these runs. 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

package/docs/guides/tools-administration.md

@@ -82,3 +82,7 @@ List, inspect, apply, reconcile or test profile service access through Relay, or
 ## 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`.
+
+## relay_project_profile_instructions
+
+Read project additions to a profile with `operation: get`, `projectId` and `profile`. An unset addition has empty `template` and `version: 0`. Use `set` with `template` and the last read `expectedVersion`; empty text removes the addition from context. `history` returns revision texts for comparison with actor, time and reason. `restore` takes a historical `version` and current `expectedVersion`, appending a new revision. Stale writes return 409 with `current`. `list` accepts either projectId (all profiles) or profile (all projects). Reads need `agent:read`; writes also need `agent:write`. The tool belongs to `prompts`. Text applies after the global charter to launches and context resets in that project, including roles extending the profile. The limit is 16000 characters; control bytes are rejected. Invalid stored text is skipped at launch with a named warning.

package/docs/guides/tools-coordination.md

@@ -200,6 +200,7 @@ Coordinator-only (#3045): after a workflow escalation (a bound hit, a failed or
 - `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.
+- `pause`: true pauses a running run, false unpauses it (#3757); pass only `runId` and, to pause, `note` as the required reason. A paused run keeps its agents, workspace and history; a working step agent is not interrupted, but the run goes past no seam (no step spawns, no delivery is routed, no review starts, no land is armed) and escalates nothing. Its step deadline, backstop and land wait stand still and continue with the time they had left on unpause. A delivery made while paused is routed on unpause. relay_workflow_get shows `paused` {by, at, reason}; you get a notice on pause and unpause, and your next context generation lists your team's paused runs. Cancel still ends a paused run.
 
 ## relay_workflow_start
 
@@ -207,6 +208,7 @@ Run the repo's declared workflow `.agent-relay/workflows/<workflow>.yaml` on a T
 
 - `workflow`: Workflow name: .agent-relay/workflows/<workflow>.yaml on the default branch, else Relay's bundled one (build-review).
 - `taskId`: Task id (TNNNN accepted).
+- `cwd`: Checkout to read the workflow and its roles from. Omit it to resolve the Task repo using the caller’s checkout, recorded worktree or project team; pass it explicitly when several roots remain ambiguous.
 - `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.

package/docs/guides/tools-tasks.md

@@ -76,6 +76,8 @@ Confirm a #1456 carry-pending Task: assert the delivered change discarded by a m
 
 ## relay_task_create
 
+`onDeploy` is an optional follow-up of up to 500 characters. It appears under the Task in the deploy notice. Set it through MCP/HTTP create or `humwick task create --title TEXT --intent TEXT --on-deploy TEXT`.
+
 Create a durable deliverable Task (#834). Owns execution telemetry (status, stage, gates, branch, commits, deps); references GitHub issue(s) for intent/spec. Optionally seed issue refs and dependencies. Returns id, status, issue refs and review-hold state; pass verbose:true for the full Task.
 
 - `label`: alias for title; concise task label
@@ -86,6 +88,7 @@ Create a durable deliverable Task (#834). Owns execution telemetry (status, stag
 - `doneWhen`: exit predicate / acceptance for execution
 - `repo`: owner/repo for the task's project/repository
 - `branch`: optional branch ref to seed on the task
+- `paths`: repo-relative files or folders the Task touches; a project spawn policy's `taskPaths` matches them (#3736)
 - `issueRefs`: Issue(s) this Task delivers or references (see relation): #n, owner/repo#n, GitHub URL, or issue_<id>. Linked issues are hydrated into a task-bound spawn's first-turn brief, so pass the ref instead of pasting the spec. Aliases accepted: refs, issues, issue, issueRef, externalKey, issueNumber. A bare #n resolves against defaultRepo, else the Task's repo, else your own project's repo.
 - `relation`: Issue relation: delivers authorizes auto-close at land; references only links/hydrates the spec. Omitted relations resolve from the current Task type at land: delivers for build/ui/refactor/debug/mechanical (or an omitted type with a build-like bound profile), references for research/design (use research), review and ops. Unset type derives from the bound profile: software-design, reviewer, isolated-research and ops-assistant reference; other profiles default to build. Inferred refs always store references. Applies to every issue in this call; re-add with a relation to change it, or omit relation to preserve an existing explicit one.
 - `defaultRepo`: owner/repo for bare #n issue refs
@@ -138,6 +141,8 @@ List a Task's append-only event timeline (status, stage, gate, dependency, ref,
 
 ## relay_task_list
 
+Use `{teamId, deliverableStage:"awaiting-deploy", mine:false}` for the team's landed or deploying Tasks that have not reached deployed. Results include each Task's optional `onDeploy` follow-up.
+
 List Task awareness rows, optionally filtered by execution status, deliverable stage, team, project, or repo. `brief` is id/label/status only; the default lean rows omit paragraph titles and raw timestamps; `full`/verbose:true preserve the complete legacy summary shape. Defaults to your own Tasks (created by you, assigned to you, or owned by a coordinator role you hold); pass `mine:false` for every Task. `inFlight:true` drops done/canceled rows. Lean/brief rows page within the list budget, blocked/validating Tasks first.
 
 - `mine`: Default true: only the caller's own Tasks. false lists every Task.
@@ -222,10 +227,13 @@ Coordinator-only: add/update a Task validation item by stable id. open waits for
 
 ## relay_task_update
 
+Set `onDeploy` to replace the follow-up; an empty string clears it. CLI: `humwick task update T123 --on-deploy TEXT`. The Task drawer also shows and edits this field.
+
 Update a deliverable Task's editable fields (title/label, intent, complexity, context, latest steer, doneWhen, dispatch, team, project/repo).
 
 - `taskId`: Task id: a number, numeric string, or TNNNN form (e.g. "T4409").
 - `terminalStage`: null clears the override and restores the repo default.
+- `paths`: replaces the Task's repo-relative paths; `[]` clears them.
 
 ## relay_task_withdraw_land
 

package/docs/guides/workflows.md

@@ -70,6 +70,22 @@ Use `pins` on `relay_workflow_start` when a particular step needs specific setti
 }
 ```
 
+The run owner or a Task coordinator can also change a later step's pins while
+the run is running or paused. Call `relay_workflow_resume` with only `runId`,
+`pins` and an optional `note`:
+
+```json
+{"runId":"<run-id>","pins":{"review":{"provider":"codex","model":"sol","effort":"high","orchestratorId":"wbox-1","profile":"worker"}},"note":"Move review to wbox-1"}
+```
+
+This preserves the current step, wait and pause. Each named step must never have
+started; a request naming a started step refuses without changing any pins.
+Each named pin replaces that step's previous call pin; `{}` restores its workflow
+defaults. `relay_workflow_get` with `verbose:true` shows the actor, time, note and
+new pins in `pinChanges`. The dashboard's Workflows page has **Change [step] pins**
+controls for future steps and a **Pin history** ledger. The CLI equivalent is
+`humwick workflow resume <run-id> --pins '{"review":{"effort":"low"}}'`.
+
 Keys are step names, such as `build` and `review`. A pin can set `provider`, `model`,
 `effort`, `orchestratorId` (the host id), or `profile` (the role's base profile). A
 model pin needs a provider, either in the pin or the step definition. Pins override
@@ -183,6 +199,64 @@ Uncommitted edits and changes on a feature branch do not change the workflow tha
 reviews that branch. The run records the source and commit it used. A running run
 keeps its resolved definition; start a new run to pick up a later definition.
 
+## Limit who a project's agents can spawn
+
+Commit `.agent-relay/spawn-policy.json` to make your project's rules enforced, not
+just written down. Humwick reads it from the default branch, like workflows and
+roles, and checks it on every spawn into the project. This includes spawns made
+directly, through Task dispatch, from the dashboard, by workflow steps and by
+sub-coordinators. This example says that a coordinator or sub-coordinator spawns
+only a project role or the `QA` profile. It also says that a Task touching
+`src/manuscripts/love-exe/` runs only through the `story-build-review` workflow:
+
+```json
+{
+  "version": 1,
+  "rules": [
+    {
+      "name": "love-exe-story",
+      "when": { "taskPaths": ["src/manuscripts/love-exe/**"] },
+      "require": { "workflow": "story-build-review" },
+      "hint": "love-exe chapters run only through story-build-review: spawn with the taskId and Humwick starts it."
+    },
+    {
+      "name": "project-roles",
+      "when": { "spawner": ["coordinator", "sub-coordinator"] },
+      "require": { "roles": ["writer", "editor", "builder", "reviewer"], "profiles": ["QA"] },
+      "hint": "Spawn a role from .agent-relay/roles, or the QA profile."
+    }
+  ]
+}
+```
+
+A rule applies when every `when` condition holds. A condition holds when any one of
+its listed values matches. A rule without `when` applies to every spawn.
+
+| Condition | Matches |
+| --- | --- |
+| `taskTags` | the spawn's Task has one of these tags |
+| `taskPaths` | one of the Task's `paths` matches a glob; `dir/**` also matches `dir` |
+| `spawner` | `coordinator` (any agent spawning directly), `sub-coordinator`, `workflow` (a run's step) or `operator` (the dashboard or a person) |
+
+Set a Task's `paths` (repo-relative files or folders) with `relay_task_create` or
+`relay_task_update`. Each rule has a `hint` and either `deny: true` or a `require`:
+
+- `roles` and `profiles` list what the spawn may name. A role spawn must name a
+  listed role; a profile spawn must name a listed profile. Names match without
+  regard to case, and by canonical profile name: the retired `default-relay` is
+  `worker`, and a spawn that names no profile gets `worker`. So a list with
+  `worker` admits `default-relay` and an omitted profile, and a list without
+  `worker` refuses both (the refusal says `profile worker`). Listing `default-relay`
+  is the same as listing `worker`.
+- `workflow` sends the Task's work through that workflow. Spawning for the Task
+  starts it, whatever the Task's type, and only that run's steps may spawn for it.
+  Passing `workflow:false` is refused.
+
+A refused spawn fails before anything launches. The error names the rule, what it
+allows and the hint. A spawn receipt lists the rules that applied in `spawnPolicy`.
+A project without the file is not limited. If the file is invalid or cannot be
+read, Humwick logs one warning with the reason and limits nothing until it is fixed.
+
 ## Resume work that needs a decision
 
 An `escalated` run is waiting for its coordinator to resolve the reported cause.