@pitboss/cli 0.4.7 → 0.4.8

package/dist/cli.js

@@ -20643,6 +20643,14 @@ var BASE_TASK_LOOP = (agentId, repoPath) => `You are an AI worker agent (ID: ${a
    human. If you need the answer before you can continue, block the task with
    \`blockedThreadId\` set to the thread the DM returned; you will be resumed when they answer.
 
+   **A blocker travels up the chain.** When another agent's task blocks, the repo's orchestrator
+   and the planner of that task's goal are told, as well as the owner. If that is you, read the
+   question on its \`blockedThreadId\`. When the plan, the goal, its issue or its PR already answers
+   it, reply there with the answer and where it comes from. As the planner, if the block shows the
+   plan is wrong (a missing dependency, a task too big), fix the plan. Never answer for the owner on
+   deletes, scope changes, approvals or publishing; those wait for the owner or their delegate.
+   Otherwise do nothing: the owner has already been told.
+
 2. Call \`mcp__relai__session_start\` for orientation. It is an **index, not an archive**: lists are
    capped and long bodies are clipped. Anything marked \`truncated: true\`, and anything named under
    \`notShown\`, is a pointer: fetch the real thing with the tool it names before you rely on it,
@@ -20921,6 +20929,62 @@ Find the default branch with \`git remote show origin\`.
    Write it to a file and run \`gh pr edit <prUrl> --body-file <file>\`. Post the same plan on
    the planning task's thread and complete it.
 
+**Review goals** (the order's \`kind\` is \`"review"\`; the planning task carries
+\`metadata.orderKind: "review"\`): the goal is one review posted on the existing pull request at the
+order's \`prUrl\`. There is no order branch, no draft PR and no merge, so skip steps 2 to 6 above.
+Nobody pushes to the PR's branch, approves it, or requests changes on it.
+1. As the planner, read the PR with \`gh pr view <prUrl>\` and \`gh pr diff <prUrl>\`. Pick the
+   angles it needs: correctness, security, simplicity, tests and consistency with the codebase for a
+   real change; correctness and consistency alone for a small, low-risk one (docs, tests, under about
+   150 changed lines with no auth, input handling, secrets, money or migrations).
+2. One task per angle, \`epicId\` = the order's \`epicId\`,
+   \`metadata: { orderId, orderRole: "review", angle: "<angle>", prUrl }\`. Spread the angles
+   across vendors: assign each to a different agent from \`mcp__relai__list_agents\`, preferring a
+   different \`workerType\` from the agents already given one, and reuse agents only when there are
+   more angles than agents. Each description names the angle, the PR, what that angle hunts for, and
+   the reporting format below.
+3. One lead task, \`blockedBy\` every angle task, assigned to yourself, with
+   \`metadata: { orderId, orderRole: "review_lead", prUrl }\`.
+4. When acceptance includes \`human_approval\`, add a gate task blocked by the lead
+   (\`metadata: { orderId, orderRole: "gate" }\`, \`verifyKind: "human_approval"\`) and a post task
+   blocked by the gate (\`metadata: { orderId, orderRole: "post_review", prUrl }\`). Without it,
+   the lead posts the review itself.
+5. If the order has \`relatedRepos\`, copy them into every angle and lead task's metadata and name them in
+   each description, so reviewers check the contracts this PR depends on in those repos.
+6. Post the task list on the planning task's thread and complete it.
+
+**orderRole "review"** (one angle of a review goal):
+- Read the diff and as much surrounding code as you need. To run anything, check out the PR head
+  detached: \`git fetch origin pull/<n>/head && git checkout --detach FETCH_HEAD\`. Never push, never
+  comment on the PR, never edit the repo's history.
+- Verify by running code where you can. Report your 3 to 5 best-evidenced findings for your angle, most
+  severe first, each with severity (blocker, high, medium, low), file:line, and a concrete failing
+  input or scenario. "No findings" is a valid report. A missing code comment is not a finding.
+- When the task names \`relatedRepos\`, read them for any contract this change depends on (an endpoint it
+  calls, a helper it imports, a config value it reads). Read only, outside your worktree: a shallow
+  clone into a temp directory (\`gh repo clone <url> <tmp dir> -- --depth 1\`) or one file at a time with
+  \`gh api repos/<owner>/<repo>/contents/<path>\`. Never push, branch, comment or open anything there.
+  A finding that rests on a related repo cites the file and line there. If you could not read the
+  repo, mark that finding UNPROVEN and say why rather than guessing what the other side does.
+- Post the report with \`mcp__relai__add_task_comment\` on this task, then complete it.
+
+**orderRole "review_lead"**:
+- Read every angle task's report with \`mcp__relai__get_task_comments\`. Merge duplicates, drop
+  findings you cannot reproduce or whose premise is wrong, and rank what is left. Keep an UNPROVEN mark
+  on any finding about a related repo nobody could read. Severity sets the
+  verdict: any blocker or high means changes are needed; otherwise it is safe to merge with the
+  noted follow-ups.
+- Write one review: the verdict in the first line, then the findings, each with file:line, the
+  failure and the fix you would ask for, then which angles ran, each with its agent's name and vendor
+  (\`workerType\` from \`mcp__relai__list_agents\`), and which related repos were read. Keep it short.
+- Without a \`human_approval\` gate, post it with \`gh pr review <prUrl> --comment --body-file <file>\`
+  and put the review URL on the task's thread. With a gate, post the review as a comment on this task
+  for the owner to approve, and do not touch the PR. Then complete.
+
+**orderRole "post_review"**: once the gate is approved, post the lead's review comment from the
+lead task's thread with \`gh pr review <prUrl> --comment --body-file <file>\`, put the review URL on
+this task's thread, and complete.
+
 **orderRole "plan_review"** (assigned to the planner, reviewed by another agent):
 - After the task graph is written, complete each plan review task. That hands the plan to its
   reviewer. Every build task waits until all plan reviews are approved.

package/dist/event-worker.js

@@ -35,6 +35,14 @@ var BASE_TASK_LOOP = (agentId, repoPath) => `You are an AI worker agent (ID: ${a
    human. If you need the answer before you can continue, block the task with
    \`blockedThreadId\` set to the thread the DM returned; you will be resumed when they answer.
 
+   **A blocker travels up the chain.** When another agent's task blocks, the repo's orchestrator
+   and the planner of that task's goal are told, as well as the owner. If that is you, read the
+   question on its \`blockedThreadId\`. When the plan, the goal, its issue or its PR already answers
+   it, reply there with the answer and where it comes from. As the planner, if the block shows the
+   plan is wrong (a missing dependency, a task too big), fix the plan. Never answer for the owner on
+   deletes, scope changes, approvals or publishing; those wait for the owner or their delegate.
+   Otherwise do nothing: the owner has already been told.
+
 2. Call \`mcp__relai__session_start\` for orientation. It is an **index, not an archive**: lists are
    capped and long bodies are clipped. Anything marked \`truncated: true\`, and anything named under
    \`notShown\`, is a pointer: fetch the real thing with the tool it names before you rely on it,
@@ -313,6 +321,62 @@ Find the default branch with \`git remote show origin\`.
    Write it to a file and run \`gh pr edit <prUrl> --body-file <file>\`. Post the same plan on
    the planning task's thread and complete it.
 
+**Review goals** (the order's \`kind\` is \`"review"\`; the planning task carries
+\`metadata.orderKind: "review"\`): the goal is one review posted on the existing pull request at the
+order's \`prUrl\`. There is no order branch, no draft PR and no merge, so skip steps 2 to 6 above.
+Nobody pushes to the PR's branch, approves it, or requests changes on it.
+1. As the planner, read the PR with \`gh pr view <prUrl>\` and \`gh pr diff <prUrl>\`. Pick the
+   angles it needs: correctness, security, simplicity, tests and consistency with the codebase for a
+   real change; correctness and consistency alone for a small, low-risk one (docs, tests, under about
+   150 changed lines with no auth, input handling, secrets, money or migrations).
+2. One task per angle, \`epicId\` = the order's \`epicId\`,
+   \`metadata: { orderId, orderRole: "review", angle: "<angle>", prUrl }\`. Spread the angles
+   across vendors: assign each to a different agent from \`mcp__relai__list_agents\`, preferring a
+   different \`workerType\` from the agents already given one, and reuse agents only when there are
+   more angles than agents. Each description names the angle, the PR, what that angle hunts for, and
+   the reporting format below.
+3. One lead task, \`blockedBy\` every angle task, assigned to yourself, with
+   \`metadata: { orderId, orderRole: "review_lead", prUrl }\`.
+4. When acceptance includes \`human_approval\`, add a gate task blocked by the lead
+   (\`metadata: { orderId, orderRole: "gate" }\`, \`verifyKind: "human_approval"\`) and a post task
+   blocked by the gate (\`metadata: { orderId, orderRole: "post_review", prUrl }\`). Without it,
+   the lead posts the review itself.
+5. If the order has \`relatedRepos\`, copy them into every angle and lead task's metadata and name them in
+   each description, so reviewers check the contracts this PR depends on in those repos.
+6. Post the task list on the planning task's thread and complete it.
+
+**orderRole "review"** (one angle of a review goal):
+- Read the diff and as much surrounding code as you need. To run anything, check out the PR head
+  detached: \`git fetch origin pull/<n>/head && git checkout --detach FETCH_HEAD\`. Never push, never
+  comment on the PR, never edit the repo's history.
+- Verify by running code where you can. Report your 3 to 5 best-evidenced findings for your angle, most
+  severe first, each with severity (blocker, high, medium, low), file:line, and a concrete failing
+  input or scenario. "No findings" is a valid report. A missing code comment is not a finding.
+- When the task names \`relatedRepos\`, read them for any contract this change depends on (an endpoint it
+  calls, a helper it imports, a config value it reads). Read only, outside your worktree: a shallow
+  clone into a temp directory (\`gh repo clone <url> <tmp dir> -- --depth 1\`) or one file at a time with
+  \`gh api repos/<owner>/<repo>/contents/<path>\`. Never push, branch, comment or open anything there.
+  A finding that rests on a related repo cites the file and line there. If you could not read the
+  repo, mark that finding UNPROVEN and say why rather than guessing what the other side does.
+- Post the report with \`mcp__relai__add_task_comment\` on this task, then complete it.
+
+**orderRole "review_lead"**:
+- Read every angle task's report with \`mcp__relai__get_task_comments\`. Merge duplicates, drop
+  findings you cannot reproduce or whose premise is wrong, and rank what is left. Keep an UNPROVEN mark
+  on any finding about a related repo nobody could read. Severity sets the
+  verdict: any blocker or high means changes are needed; otherwise it is safe to merge with the
+  noted follow-ups.
+- Write one review: the verdict in the first line, then the findings, each with file:line, the
+  failure and the fix you would ask for, then which angles ran, each with its agent's name and vendor
+  (\`workerType\` from \`mcp__relai__list_agents\`), and which related repos were read. Keep it short.
+- Without a \`human_approval\` gate, post it with \`gh pr review <prUrl> --comment --body-file <file>\`
+  and put the review URL on the task's thread. With a gate, post the review as a comment on this task
+  for the owner to approve, and do not touch the PR. Then complete.
+
+**orderRole "post_review"**: once the gate is approved, post the lead's review comment from the
+lead task's thread with \`gh pr review <prUrl> --comment --body-file <file>\`, put the review URL on
+this task's thread, and complete.
+
 **orderRole "plan_review"** (assigned to the planner, reviewed by another agent):
 - After the task graph is written, complete each plan review task. That hands the plan to its
   reviewer. Every build task waits until all plan reviews are approved.

package/dist/mcp.js

@@ -12538,19 +12538,23 @@ function buildCreateOrderTool(client, repoId, opts) {
       repoId: external_exports.string().optional().describe(opts.ownerScoped ? "Repo to file the order in: any repo your owner owns. Defaults to your home repo." : "Repo to file the order in. Defaults to this agent's home repo."),
       feature: external_exports.string().min(1).optional().describe("What to build, in the requester's words. Optional when issueUrl is given."),
       issueUrl: external_exports.string().optional().describe("A GitHub issue in this repo to build from (https://github.com/<owner>/<repo>/issues/<n>). The planner reads it, and the merge closes it."),
+      reviewPrUrl: external_exports.string().optional().describe('Review this pull request in the repo instead of building something (https://github.com/<owner>/<repo>/pull/<n>). Agents on different vendors each review one angle, a lead merges their findings, and one review is posted on the PR. No gate by default; pass acceptance ["human_approval"] to approve the review before it is posted. feature, when given, narrows what to look at.'),
+      relatedRepos: external_exports.array(external_exports.string()).max(5).optional().describe("Review goals only: ids of other repos you own (see list_repos) whose contracts this PR depends on. Reviewers read them, never write to them, and mark findings about one they could not read as unproven."),
       planReviewers: external_exports.number().int().min(0).max(3).optional().describe("How many other agents must approve the plan before building starts (0 to 3). Reviewers are picked by the API, preferring reviewer agents on another vendor."),
       pairBuilds: external_exports.boolean().optional().describe("Pair every build task with a reviewer on a different vendor: each build carries its own review gate, and the builder is never on the reviewer's vendor."),
       title: external_exports.string().min(1).max(120).optional().describe("A short name for the goal. The planner writes one when omitted."),
-      acceptance: external_exports.array(external_exports.enum(["ci_passed", "human_approval", "reviewer_agent"])).optional().describe("Gates that must all pass. Defaults to human_approval."),
+      acceptance: external_exports.array(external_exports.enum(["ci_passed", "human_approval", "reviewer_agent"])).optional().describe("Gates that must all pass. Defaults to human_approval, or none for a review."),
       budget: external_exports.record(external_exports.unknown()).optional().describe("Optional ceilings. Stored only; not enforced.")
     }),
     handler: async (input) => {
-      if (!input.feature && !input.issueUrl) return mcpFail("create_order needs feature or issueUrl");
+      if (!input.feature && !input.issueUrl && !input.reviewPrUrl) return mcpFail("create_order needs feature, issueUrl or reviewPrUrl");
       try {
         const created = await client.createOrder({
           repoId: targetRepo(input),
           ...input.feature ? { feature: input.feature } : {},
           ...input.issueUrl ? { issueUrl: input.issueUrl } : {},
+          ...input.reviewPrUrl ? { kind: "review", prUrl: input.reviewPrUrl } : {},
+          ...input.relatedRepos?.length ? { relatedRepos: input.relatedRepos } : {},
           ...input.planReviewers ? { planReviewers: input.planReviewers } : {},
           ...input.pairBuilds ? { pairBuilds: true } : {},
           ...input.title ? { title: input.title } : {},
@@ -13260,7 +13264,7 @@ function buildGodCoordinationTools(client) {
   return [
     {
       name: "list_attention",
-      description: "List what needs attention across ALL your owner's repos: tasks that are 'blocked' (a worker is waiting), 'pending_verification' (awaiting a review decision), or 'proposed' (a worker's task awaiting commit), plus idle workers that cannot take the ready work that is sitting there (idle_unroutable \u2014 derived now, not from the event log). Each task carries its repoId. A blocked task with metadata.blockedThreadId resumes when you answer with send_message (type decision) on that thread, as if the owner had, when the owner has given you a decide delegation for that repo; the task records clearedBy. Answer only reversible, branch-level confirmations yourself (editing, pushing or deleting files on an order branch, choosing between plan options). Merges into a default branch, deploys, deletes outside an order branch, and anything touching credentials or money go to the owner. One without it (stalled or overflowed work, or your own task) needs reassigning with assign_task or splitting instead. An idle_unroutable item names the agent and why each task is ineligible (domain, specialization, review_gate, for-human, product-decision, pinned, blockedBy). Capped and clipped, newest first; read one in full with get_task.",
+      description: "List what needs attention across ALL your owner's repos: tasks that are 'blocked' (a worker is waiting), 'pending_verification' (awaiting a review decision), or 'proposed' (a worker's task awaiting commit), plus idle workers that cannot take the ready work that is sitting there (idle_unroutable \u2014 derived now, not from the event log). Each task carries its repoId. A blocked task with metadata.blockedThreadId resumes when you answer with send_message (type decision) on that thread, as if the owner had, when the owner has given you a decide delegation for that repo; the task records clearedBy. Answer only reversible, branch-level confirmations yourself (editing, pushing or deleting files on an order branch, choosing between plan options). Merges into a default branch, deploys, deletes outside an order branch, and anything touching credentials or money go to the owner. A blocked task without blockedThreadId (stalled or overflowed work) resumes the same way when you post add_task_comment (type decision) on it; say whether to split, retry or reassign. Your own blocked task never resumes on your answer. An idle_unroutable item names the agent and why each task is ineligible (domain, specialization, review_gate, for-human, product-decision, pinned, blockedBy). Capped and clipped, newest first; read one in full with get_task.",
       inputSchema: external_exports.object(attentionWindowSchema),
       handler: async (input) => {
         const cutoff = attentionCutoff(input);
@@ -13845,7 +13849,8 @@ function attentionStateOf(task) {
 function describe(task, state) {
   const title = (task.title ?? task.id).slice(0, 80);
   const where = task.repoId ? ` [${task.repoId}]` : "";
-  const thread = state === "blocked" && typeof task.metadata?.blockedThreadId === "string" ? ` Reply on thread ${task.metadata.blockedThreadId} to unblock it.` : "";
+  const replyOn = typeof task.metadata?.blockedThreadId === "string" ? task.metadata.blockedThreadId : task.threadId;
+  const thread = state !== "blocked" ? "" : replyOn ? ` Reply on thread ${replyOn} to unblock it.` : ` Answer with add_task_comment on ${task.id} to unblock it.`;
   const next = state === "proposed" ? " Use commit_proposal." : state === "pending_verification" ? " Use review_task." : state === "stalled" ? " Nobody is coming; reassign or cancel it." : "";
   return `relai: "${title}" is ${LABEL[state]}${where} (${task.id}).${thread}${next}`;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pitboss/cli",
-  "version": "0.4.7",
+  "version": "0.4.8",
   "private": false,
   "description": "Connect your coding agents to a pitboss instance",
   "keywords": [