@sjawhar/opencode-legion-envoy 9.1.0 → 9.3.0

package/skills/legion-controller/references/wakes.md

@@ -16,8 +16,9 @@ the issue header. Triage it as `skill://legion-controller/references/triage.md`
 
 ## `slot-free on <KEY>` (`{kind: "slot-free"}`)
 
-The daemon released `<KEY>`'s slot, because its tree finished or left the workflow, and no waiting
-root took it. Name the free slots; take nothing.
+The daemon released `<KEY>`'s slot and no waiting root took it: its tree finished or left the
+workflow, or the root returned the slot to wait on a person (`awaiting_person`, which also sends
+its own `awaiting-person` wake). Name the free slots; take nothing.
 
 ## `todo on <KEY>` (`{kind: "todo"}`)
 
@@ -50,12 +51,25 @@ take nothing for them.
 
 ## `unslotted on <KEY>` (`{kind: "unslotted", reason}`)
 
-A root that waited for a slot was moved from `todo` to the status `reason` names, by a person or by
-another session, so the daemon took it out of the workflow (`phase: done`) and starts nothing for
-it. Re-admit nothing, because the move was someone else's; `dispatch read` shows who claims it now.
-Tell the person in your summary: "<KEY> left Legion's waiting line: it was set to <status> while it
-waited for a slot, so Legion let it go; `todo` with the `legion` label queues it again". Other
-admission states: `skill://legion-controller/references/admission.md`.
+Either a root that waited for a slot was moved from `todo` to the status `reason` names, by a
+person or by another session, or a root waiting on a person (`awaiting_person`) could not be
+resumed — its `legion` label is gone, or a person or a session outside its tree took its Dispatch
+claim. Either way the daemon took it out of the workflow (`phase: done`) and starts nothing for it;
+`reason` says which. Re-admit nothing, because the move was someone else's; `dispatch read` shows
+who claims it now. Tell the person in your summary: "<KEY> left Legion's workflow: <reason as the
+wake gives it>; `todo` with the `legion` label queues it again". Other admission states:
+`skill://legion-controller/references/admission.md`.
+
+## `awaiting-person on <KEY>` (`{kind: "awaiting-person", reason}`)
+
+A root whose architect asked a person a question, or handed its spec to a person for approval, and
+now waits only on them: the daemon returned
+its slot and suspends the architect after its turn, keeping its session. Read
+`issues.<KEY>.waitingOn`. Do not park it or start anything, and take nothing for the slot it
+returned: it is no reason to label or admit an issue ([Free
+slots](skill://legion-controller/SKILL.md#free-slots)). The person's answer puts it at the front of
+`admission.waiting` by itself, and the next free slot resumes its architect. A lost label or a
+foreign Dispatch claim sends the separate `unslotted` wake.
 
 ## `held on <KEY>` (`{kind: "held", phase, role?, reason?}`)
 

package/skills/legion-worker/SKILL.md

@@ -19,7 +19,7 @@ You work one phase of one issue in a jj workspace every role of the issue shares
 
 ## Stop rules
 
-- **A refused completion is information, not a retry loop.** Quote the answer verbatim to the architect, so "my work is lost" and "my work belongs to an ended run" read differently. `HANDOFF_STALE_GENERATION` (the issue is on a newer run, or your turn began before the daemon recorded your task, which it then sends again) or `HANDOFF_NO_RUN` (your claim holds no task): push nothing further and tell the architect; when a task then arrives whose work is already committed, call `handoff_complete` again, and never redo the work or write a second handoff. `HANDOFF_NOT_CURRENT_PHASE`: the issue left your phase; report, never complete again. `HANDOFF_ALREADY_RECORDED`: the first answer stands, an acceptance or one of the four refusals the daemon records (`HANDOFF_STALE_GENERATION`, `HANDOFF_NOT_CURRENT_PHASE`, `READY_REQUIRED`, `HANDOFF_NOT_NEW`); if you did not see it, tell the architect. A refusal given before any fact is applied (READY's checks of the head among them) records nothing, so the corrected call at the same commit is applied. A reminder is not a task: after an accepted completion, a second call is refused.
+- **A refused completion is information, not a retry loop.** Quote the answer verbatim to the architect, so "my work is lost" and "my work belongs to an ended run" read differently. `HANDOFF_STALE_GENERATION` (the issue is on a newer run: your turn began before the daemon's task for that run reached you, and the answer names that task when it is queued) or `HANDOFF_NO_RUN` (your claim holds no task): push nothing further, end the turn without completing, and tell the architect; if the task then arrives (none may: the new run's phase can be another claim's) and its work is already committed, call `handoff_complete` again at the same commit in that task's turn, and never redo the work or write a second handoff. `HANDOFF_NOT_CURRENT_PHASE`: the issue left your phase; report, never complete again. `HANDOFF_ALREADY_RECORDED`: the first answer stands, an acceptance or one of the refusals the daemon records (`HANDOFF_NOT_CURRENT_PHASE`, `READY_REQUIRED`, `HANDOFF_NOT_NEW`, and `HANDOFF_STALE_GENERATION` only when the issue moved during the call); if you did not see it, tell the architect. A refusal given before any fact is applied (`HANDOFF_STALE_GENERATION`, `HANDOFF_NO_RUN` and READY's checks of the head among them) records nothing, so the corrected call at the same commit is applied. A reminder is not a task: after an accepted completion, a second call is refused.
 - **After your phase completes, the workspace is read-only for you**: no commit, no `jj new`, no edit to a tracked file, in any later turn until a new task names your phase. The active phase owns it, and you stay live only to answer questions.
 - **Never start another Legion role**: the daemon starts every phase worker.
 - **Never end your turn blocked on a decision someone else owns.** Send a product, scope, design, lifecycle or cross-phase decision to the owning architect as your role prompt says, with the issue, phase, verified observation, what you tried and the decision needed; a human-only to-do is a `dispatch ask`. Otherwise proceed: a phase that stops silently holds its issue until someone notices.
@@ -46,7 +46,7 @@ Read each by its `skill://` link: a read by path stops at 300 lines.
 ## Every role pushes its own commits
 
 - Before a push, read `jj -R "$LEGION_WORKSPACE" log -r 'ancestors(@, 5)'` (earlier phases' commits in it are expected) and run the identity check (`skill://legion-worker/references/default-branch-check.md`). Add no attribution trailer: the pane's jj adds `Omp-Session:`.
-- A push whose commits touch only `.legion/` ends its head's message with `skip-checks: true`, unless it is retro's push (the implementer's retro phase, before the merger's). Retro's push never carries the line, whatever paths it touches, because it is the last push before the merge and a base that requires a check will not merge a head whose checks never ran. No other push carries it. The daemon classifies a push by its paths, never by the trailer, so a wrong trailer can stall the issue but never makes it pass.
+- A push whose commits touch only `.legion/<issue>/` ends its head's message with `skip-checks: true`, unless it is retro's push (the implementer's retro phase, before the merger's). Retro's push never carries the line, whatever paths it touches, because it is the last push before the merge and a base that requires a check will not merge a head whose checks never ran. No other push carries it. The daemon classifies a push by its paths, never by the trailer, so a wrong trailer can stall the issue but never makes it pass.
 - A planner whose issue moved back from implementing starts on the remote tip, `jj -R "$LEGION_WORKSPACE" new legion/<KEY>@origin`, so its handoff never sits on the implementer's unpushed commits.
 
 ## PR body, review, and the merge gate

package/skills/legion-worker/references/merge-gate.md

@@ -23,10 +23,10 @@ it, and any other change to the head voids it.
   `task(agent="thermonuclear-code-quality")` once at that head — the head the round reviews —
   and records the verdict. The CI it reads is the checks that stand for the code under review:
   those GitHub ran for the newest push of the branch that started `pull_request` workflows, when
-  every commit above that push's head changes only `.legion/` (GitHub starts no workflow run for a
-  head whose commit message carries `skip-checks: true`, which every handoff-only push before
-  retro does; retro's push carries no such line, so its head does get GitHub's workflow runs of
-  its own). With `<o>/<r>`, `<n>`, `<base>`, `<headRefName>` and `<headRefOid>` from
+  every commit above that push's head changes only `.legion/<issue>/` (GitHub starts no workflow
+  run for a head whose commit message carries `skip-checks: true`, which every handoff-only push
+  before retro does; retro's push carries no such line, so its head does get GitHub's workflow runs
+  of its own). With `<o>/<r>`, `<n>`, `<base>`, `<headRefName>` and `<headRefOid>` from
   `gh pr view <n> --json baseRefName,headRefOid,headRefName`, four reads. The required set is the
   base branch's rulesets' required checks and its branch protection's, when it has any. Both
   branch endpoints take the base as a URL path, each segment escaped and each `/` kept (a raw `#`
@@ -46,8 +46,9 @@ it, and any other change to the head voids it.
   newest first). That commit's check-runs
   (`gh api repos/<o>/<r>/commits/<ci head>/check-runs --paginate --jq '.check_runs[] | [.name, .status, .conclusion] | @tsv'`):
   every required name present, `completed` and `success` (GitHub counts `neutral` and `skipped`
-  as passing for a required check). And the compare proving only `.legion/` changed since
-  (`gh api repos/<o>/<r>/compare/<ci head>...<headRefOid> --jq '{handoffsOnly: ([.files[].filename] | all(startswith(".legion/"))), files: (.files | length)}'`
+  as passing for a required check). And the compare proving only `.legion/<issue>/` changed since,
+  `<issue>` being your `LEGION_ISSUE` (another issue's `.legion/` is code to the daemon and READY)
+  (`gh api repos/<o>/<r>/compare/<ci head>...<headRefOid> --jq '{handoffsOnly: ([.files[] | .filename, (.previous_filename // empty)] | all(startswith(".legion/<issue>/"))), files: (.files | length)}'`
   prints `handoffsOnly` `true`; `false` means code was pushed since CI ran, so wait for the new
   push's runs and read the CI head again). GitHub's compare lists at most 300 files for the whole
   comparison, so `files` at 300 is a comparison GitHub cut at its cap and `handoffsOnly` decides
@@ -98,7 +99,7 @@ it, and any other change to the head voids it.
   `REQUEST_CHANGES` when the code is at fault, and your own commit to fix when your prose broke
   it. The architect reads your prose commits at its acceptance (*The architect's acceptance*,
   below), and that read is no new round. A round after a READY refusal is the one exception. Its
-  approval needs the tester's `E2E` line to name the head with only `.legion/` changed since. So
+  approval needs the tester's `E2E` line to name the head with only `.legion/<issue>/` changed since. So
   there you fix no prose yourself, and you name each prose finding in a `REQUEST_CHANGES`.
 
 A reviewer's phase ends with its completion, not with its review. Every round writes a handoff
@@ -109,7 +110,7 @@ whatever CI says and the issue leaves reviewing with it. The approval waits on n
 handoff-only commit either: it ends the round whatever CI says there, since the round reads no CI
 verdict, and a red the daemon reads later — at that commit or any above it — is the code's red
 and resumes the implementer from wherever the issue is (reviewing, retro or merging) without the
-reviewer. A head your own push changed beyond `.legion/` is the exception. The daemon marks it a
+reviewer. A head your own push changed beyond `.legion/<issue>/` is the exception. The daemon marks it a
 planned red and sends nothing back for it, so wait for its checks yourself (*Fix a prose-only
 finding yourself*, above). A review of a head the handoff push then replaces names a head the pull
 request no longer has. The daemon moves the issue once both are in — the decision GitHub reports
@@ -120,8 +121,8 @@ reviewing until you finish.
 
 - Between the reviewer's approval and retro the issue sits in `accepting` (Dispatch status
   `needs_review`), where no worker is started: the tree's architect reads the evidence (the
-  tester's handoff, the PR body's `E2E (implementer)` and `E2E (tester)` lines, the reviewer's
-  approval of the head by SHA, and for a parent that every child is done) and accepts with the
+  tester's handoff, the PR body's `E2E (implementer)` and `E2E (tester)` lines and the reviewer's
+  approval of the head by SHA; children still running do not hold it) and accepts with the
   `legion` tool's `sign_off`, which moves the issue to retro, or sends it back to `implementing`
   or `testing` with `request_backward_move` and a reason, which reaches the started worker's task
   as its `Reason:` line and counts a review round. The architect also reads the reviewer's own
@@ -130,7 +131,7 @@ reviewing until you finish.
   controller takes it"). The acceptance asks no `Production:` line of anyone: that line is written
   after the close (*The production check after the close*, below).
   CI red at the head in `accepting` returns the issue to `implementing` as it does in review. A
-  head the review App pushed beyond `.legion/` is the exception: the daemon marks it a planned red
+  head the review App pushed beyond `.legion/<issue>/` is the exception: the daemon marks it a planned red
   and acts on it nowhere, and GitHub holds the merge under the base branch's own rules.
 
 ## Retro

package/skills/legion-worker/references/skip-checks-trailer.md

@@ -8,7 +8,7 @@ sjawhar/legion.
 
 ## The shape GitHub honours
 
-A push whose commits touch only `.legion/` (a handoff-only push) ends its head's commit message
+A push whose commits touch only `.legion/<issue>/` (a handoff-only push) ends its head's commit message
 with `skip-checks: true` as the last line, preceded by two empty lines, so GitHub starts no
 workflow run for it and the daemon carries the code head's verdict to it — except retro's push,
 which never carries the line whatever paths it touches, for the reason the next section gives.

package/skills/legion-worker/references/tools.md

@@ -14,8 +14,9 @@ which you have; those need no runner.
 - `psql` — the Dispatch browser suite (`bun run e2e`) resets its database for every spec through
   `packages/dispatch/e2e/psql.ts`, which `seed.ts` calls, and the local stack (`bun run
   dispatch:local`, `packages/dispatch/e2e/local-instance.ts`) refuses to start without `go`,
-  `psql`, `flock` and `openssl` on `PATH`, and without `docker` too unless a `DATABASE_URL` is
-  given. The image carries `go`, `flock` and `openssl`, a `DATABASE_URL` stands in for `docker`,
+  `psql`, `flock`, `openssl` and `python3` on `PATH`, and without `docker` too unless a
+  `DATABASE_URL` is given. The image carries `go`, `flock`, `openssl` and `python3`, a
+  `DATABASE_URL` stands in for `docker`,
   and `psql` was the one a role had no way to supply — so a role whose change owes that suite can
   run it.
 - `redis-cli` — no repository of the project speaks Redis today; it is carried anyway, at about a