@sjawhar/pi-legion-envoy 5.18.1 → 5.20.0

package/dist/envoy.js

@@ -29904,6 +29904,16 @@ function capAgentStreamText(text, limit) {
     return text;
   return text.slice(0, limit) + AGENT_STREAM_TRUNCATION_SUFFIX;
 }
+// ../contracts/src/claim-holds.ts
+function claimHolds(claim, titles) {
+  if (claim.actor.kind !== "session") {
+    return "holds";
+  }
+  if (titles === undefined) {
+    return "unknown";
+  }
+  return titles.has(claim.actor.id) ? "holds" : "lapsed";
+}
 // ../contracts/src/dispatch-href.ts
 function itemFromSearch(search) {
   const params = new URLSearchParams(search);
@@ -33414,17 +33424,19 @@ function componentsLine(components) {
   }
 }
 function claimText(claim, titles) {
-  return `${actorLabel(claim.actor, titles)} since ${claim.at}`;
+  const holding = claimHolds(claim, titles);
+  const marker = holding === "unknown" ? " \xB7 liveness unknown" : holding === "lapsed" ? " \xB7 not running" : "";
+  return `${actorLabel(claim.actor, titles)} since ${claim.at}${marker}`;
 }
 async function liveSessionTitles(client, needed) {
   if (!needed) {
-    return new Map;
+    return;
   }
   try {
     const agents = await client.listAgents();
     return new Map(agents.map((agent) => [agent.session_id, agent.title]));
   } catch {
-    return new Map;
+    return;
   }
 }
 function holdsSession(claim) {
@@ -33456,6 +33468,9 @@ function issueSummary(issue2, events, references, graph, titles) {
     throw new Error("Dispatch issue is missing components");
   if (issue2.claim === undefined)
     throw new Error("Dispatch issue is missing claim");
+  if (issue2.external_links === undefined) {
+    throw new Error("Dispatch issue is missing external_links");
+  }
   return [
     `Title: ${issue2.title}`,
     `Key: ${issue2.key}`,
@@ -33467,6 +33482,8 @@ function issueSummary(issue2, events, references, graph, titles) {
     componentsLine(issue2.components),
     `Route: ${routeText(issue2, titles)}`,
     ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
+    "External links:",
+    ...issue2.external_links.length === 0 ? ["- none"] : issue2.external_links.map((link) => `- ${link.url}${link.kind === undefined ? "" : ` (${link.kind})`}`),
     "Open asks:",
     ...asks.length === 0 ? ["- none"] : asks.map((ask) => `- ${ask.id}: ${ask.question}`),
     "References:",

package/dist/legion.js

@@ -30073,6 +30073,16 @@ function capAgentStreamText(text, limit) {
     return text;
   return text.slice(0, limit) + AGENT_STREAM_TRUNCATION_SUFFIX;
 }
+// ../contracts/src/claim-holds.ts
+function claimHolds(claim, titles) {
+  if (claim.actor.kind !== "session") {
+    return "holds";
+  }
+  if (titles === undefined) {
+    return "unknown";
+  }
+  return titles.has(claim.actor.id) ? "holds" : "lapsed";
+}
 // ../contracts/src/dispatch-href.ts
 function itemFromSearch(search) {
   const params = new URLSearchParams(search);
@@ -32353,17 +32363,19 @@ function componentsLine(components) {
   }
 }
 function claimText(claim, titles) {
-  return `${actorLabel(claim.actor, titles)} since ${claim.at}`;
+  const holding = claimHolds(claim, titles);
+  const marker = holding === "unknown" ? " \xB7 liveness unknown" : holding === "lapsed" ? " \xB7 not running" : "";
+  return `${actorLabel(claim.actor, titles)} since ${claim.at}${marker}`;
 }
 async function liveSessionTitles(client, needed) {
   if (!needed) {
-    return new Map;
+    return;
   }
   try {
     const agents = await client.listAgents();
     return new Map(agents.map((agent) => [agent.session_id, agent.title]));
   } catch {
-    return new Map;
+    return;
   }
 }
 function holdsSession(claim) {
@@ -32395,6 +32407,9 @@ function issueSummary(issue2, events, references, graph, titles) {
     throw new Error("Dispatch issue is missing components");
   if (issue2.claim === undefined)
     throw new Error("Dispatch issue is missing claim");
+  if (issue2.external_links === undefined) {
+    throw new Error("Dispatch issue is missing external_links");
+  }
   return [
     `Title: ${issue2.title}`,
     `Key: ${issue2.key}`,
@@ -32406,6 +32421,8 @@ function issueSummary(issue2, events, references, graph, titles) {
     componentsLine(issue2.components),
     `Route: ${routeText(issue2, titles)}`,
     ...specApproval === undefined ? [] : [`Spec ${specApproval.replace(/^Approval/, "approval")}`],
+    "External links:",
+    ...issue2.external_links.length === 0 ? ["- none"] : issue2.external_links.map((link) => `- ${link.url}${link.kind === undefined ? "" : ` (${link.kind})`}`),
     "Open asks:",
     ...asks.length === 0 ? ["- none"] : asks.map((ask) => `- ${ask.id}: ${ask.question}`),
     "References:",
@@ -33478,7 +33495,7 @@ import { logger } from "@oh-my-pi/pi-utils";
 // package.json
 var package_default = {
   name: "@sjawhar/pi-legion-envoy",
-  version: "5.18.1",
+  version: "5.20.0",
   type: "module",
   omp: {
     extensions: [

package/dist/skills/AGENTS.md

@@ -10,7 +10,7 @@ event intake, process lifecycle, credentials, and role delivery.
 | `dispatch/` | every role, and any session writing to Dispatch | specs, asks, comments, artifacts, and messages on native Dispatch |
 | `envoy/` | every role | subscriptions, agent-to-agent messages, and topic formats |
 | `legion-architect/` | root and sub-architects | tree ownership, decomposition, waves, gates, integration, sign-off |
-| `legion-controller/` | the controller root process | wake routing, backlog admission, escalation |
+| `legion-controller/` | the controller root process | wake routing, keeping the admission slots full from `todo`, the daily report, escalation |
 | `legion-oracle/` | any role doing research | repository-grounded research |
 | `legion-retro/` | the implementer, at retro | the pre-merge retrospective and its Dispatch message |
 | `legion-worker/` | planner, implementer, tester, reviewer, merger | the phase contracts: handoffs, GitHub identity, PR body and READY discipline, the merge-gate order |

package/dist/skills/dispatch/SKILL.md

@@ -215,8 +215,11 @@ dispatch_claim({ issue: "LEGION-234", release: true })   // I have stopped; it i
 
 A claim records **your** session — the one making the call, never another — and shows on every
 read of the issue: the dashboard header, the issue list and board, `dispatch_read` (a
-`Claimed by:` line) and `dispatch_issues` (a claim on the row). `dispatch_issues` plus the
-dashboard's **Unclaimed** filter is how you find work nobody is on.
+`Claimed by:` line) and `dispatch_issues` (a claim on the row). A session's claim there ends
+`· not running` when the live agent registry does not list that session, as the dashboard's chip
+does — that claim is free to take — and `· liveness unknown` when the registry could not be read,
+which says nothing either way. `dispatch_issues` plus the dashboard's **Unclaimed** filter is how
+you find work nobody is on.
 
 - **`409 ISSUE_CLAIMED` means someone else holds this issue.** When it is another session, the
   refusal names it and says it is still running: do not work the issue in parallel — message
@@ -274,7 +277,8 @@ The two clears differ: `priority` clears with `null`, while `parent` and `route`
 Guessing the other one is a refusal either way.
 
 Link the pull request that delivers the issue in `external_links` when you open it; the issue page
-renders its state and checks from that link. The call is authenticated with the same bearer as every
+renders its state and checks from that link, and `dispatch_read` lists it under `External links:`.
+The call is authenticated with the same bearer as every
 other `dispatch_*` tool: a Legion pane reads it from the `DISPATCH_TOKEN_FILE` path the daemon sets on
 the pane; an OMP session outside Legion reads `dispatch.token` from `~/.config/opencode/envoy.json`.
 

package/dist/skills/legion-architect/SKILL.md

@@ -256,10 +256,10 @@ Preserve this order exactly:
 
 What returns the tree to review: a changed diff — a commit above the approved head that
 touches anything outside `docs/solutions/`, or a conflict-resolution merge whose fingerprint
-(`skill://legion-worker`'s unchanged-diff check) differs from the approved head's. What does not: retro's
+(the unchanged-diff check, `skill://legion-worker/references/conflicts-and-rewrites.md`) differs from the approved head's. What does not: retro's
 `docs/solutions/` commit, and a merge forced by a GitHub-reported conflict whose fingerprint
 is unchanged. For that merge the order is: the implementer merges the bookmark forward with the
-destination (`legion-worker`'s forward-merge procedure — `jj new legion/<KEY> <destination>`,
+destination (the forward-merge procedure in `skill://legion-worker/references/conflicts-and-rewrites.md` — `jj new legion/<KEY> <destination>`,
 never a rebase, since a rebase rewrites every descendant of the chain's fork point, including
 another tree's branch stacked on it), pushes it with the ordinary push procedure (a genuine
 fast-forward), and posts the before/after fingerprints; the tester re-runs the bare gates only;

package/dist/skills/legion-controller/SKILL.md

@@ -1,13 +1,14 @@
 ---
 name: legion-controller
-description: Use when handling Legion controller wakes for root-issue triage, backlog admission, architect escalation, resync healing, or human interaction.
+description: Use when handling Legion controller wakes for root-issue triage, keeping the admission slots full from `todo` issues, the daily report, architect escalation, resync healing, or human interaction.
 ---
 
 # Legion Controller
 
-The controller is the one persistent, wake-driven session for a Legion project. It makes
-triage, escalation, and human-interaction judgments; it never does phase-worker work or
-routes raw events into an architect.
+The controller is the one persistent, wake-driven session for a Legion project. It keeps the
+project's admission slots full with the highest-priority work, and makes triage, escalation, and
+human-interaction judgments; it never does phase-worker work or routes raw events into an
+architect.
 
 ## Start and claim the controller role
 
@@ -87,8 +88,8 @@ mints a new secret, so your grants stop working and the role moves to the new se
 
 The Go daemon's controller topic is a wake for a session that is running when it is published.
 Envoy hands an Oh My Pi session no retained copy of a notice published before it subscribed, so a
-hold, a tree architect's failed claim, or a new triage root from while no controller ran never
-arrives as a wake. At every start, before anything else:
+hold, a tree architect's failed claim, a new triage root, or a freed slot from while no controller
+ran never arrives as a wake. At every start, before anything else:
 
 1. Read `legion state --json` and handle each issue whose `issues.<KEY>.phase` is `held` (its
    `issues.<KEY>.holdReason` is `escalated` when its architect sent it to you, and absent while the
@@ -98,15 +99,19 @@ arrives as a wake. At every start, before anything else:
    as the matching wake below. A parked tree (root phase `done`: it lingers or is closed) needs
    nothing from you: a failed architect ignores the park and reads `failed` until the tree closes.
 2. List the project's triage issues handed to Legion with
-   `dispatch_issues({project, status: "triage", label: "legion", limit: 250})`.
-   When its first line ends `(showing N of M)`, it is one page: say in your summary how many rows
-   it left unread. The rows show no parent, so open each row with `dispatch_read`: one whose
-   `Links:` name a `child_of` issue is a child, which its parent's architect owns, so leave it,
-   whether or not `legion state --json` records it (a `child_of` under `Referenced by:` is a child
-   of this issue, not its parent). Of the rest, triage each that `legion state --json` does not
-   record under `issues` as a new issue. A root recorded there and now in `triage` is work the
-   daemon holds that a human pulled back: never re-admit it yourself; name it in your summary to
-   the human ("<KEY> was pulled back to triage; what do you want?").
+   `dispatch_issues({project, status: "triage", label: "legion", limit: 250, offset: 0})`.
+   When its first line ends `(showing 1-250 of N)`, read the next page with `offset: 250`, and so
+   on until you have all N rows. The rows show no parent, so open each row with `dispatch_read`
+   and follow `Links:` up through each `child_of` parent (a `child_of` under `Referenced by:` is a
+   child of this issue, not its parent). Leave a child that has an ancestor in `admission.active`
+   or `admission.waiting`: that tree's architect owns it. Triage every other row as a root,
+   children outside a live tree included, when `legion state --json` does not record it under
+   `issues`. A root recorded there and now in `triage` is work the daemon holds that a human
+   pulled back: never re-admit it yourself; name it in your summary to the human ("<KEY> was
+   pulled back to triage; what do you want?").
+3. Fill the free admission slots ([Keeping the slots full](#keeping-the-slots-full-go-daemon)).
+4. Post the day's report when this is your first turn of the UTC day
+   ([Daily report](#daily-report-go-daemon)).
 
 The issue record and Dispatch are the truth; the topic is the wake.
 
@@ -117,12 +122,141 @@ since its project may be shared with humans and other agents. It never admits a
 without the label, and wakes you for a root in `triage` only while the root carries it and is
 unrecorded: on its creation with the label, and on each change to it after that while it stays
 in triage, the change that adds the label included (the dashboard creates an issue without
-labels, so a human adds it from the issue header). Leave an issue without the label alone:
-handing work to Legion is its owner's decision, so never triage, park, label, or comment on it.
-A child needs no label: it runs under its tree's architect once its root is admitted.
-`legion status <KEY> todo` admits a root only while it carries the label, so a root you file for
-Legion to run carries it (`labels: ["legion"]` in `dispatch_issue`). Taking the label off a
-waiting root drops it from the waiting line; taking it off an admitted tree does not stop it.
+labels, so a human adds it from the issue header). Two parties hand work over: a person, who sets
+the label from the issue header, and you, when you fill a free slot (below). You label an issue
+only when you take it or file it for Legion, so the label means Legion has the issue or had it.
+A person's label is their decision: never take it off. A child needs no label: it runs under its
+tree's architect once its root is admitted. `legion status <KEY> todo` admits a root, or a child
+outside a live tree (admitted as a root of its own), only while it carries the label, so an issue
+you hand over or file for Legion to run carries it first (`labels` in `dispatch_issue_update` or
+`dispatch_issue`). Taking the label off a waiting root drops it from the waiting line; taking it
+off an admitted tree does not stop it.
+
+## Keeping the slots full (Go daemon)
+
+Picking the next work is your job: nobody hand-feeds issues to Legion. Keep every admission slot
+filled with the highest-priority concrete issue Legion can take. The unit of Legion work is a
+leaf, an issue with no children, never an umbrella that holds other issues.
+
+**When.** At every start (step 3 above), and on each `slot-free on <KEY>` wake: the daemon
+released `<KEY>`'s slot, because its tree finished or left the workflow, and no waiting root took
+it.
+
+**Scope first.** The scope the deployment instructions state decides which issues are candidates
+at all, before anything below. When they say you hand Legion no issue yourself, or that Legion
+runs only issues someone else sets to `todo`, the walk takes nothing: stop here, whatever slots
+are free. When they narrow the scope (a repository, a kind of change), a candidate outside it is
+skipped (the last row of the table below). With no scope stated, every issue of the project is in
+scope.
+
+**How many.** Read `legion state --json`. The free slots are `admission.cap` minus the roots in
+`admission.active` and in `admission.waiting` (a waiting root takes the next slot before anything
+you add). With none free, stop.
+
+**Candidates.** The project's open `todo` issues, roots and children alike, that have no children
+at all and do not carry the `legion` label. `todo` alone, as Sami ruled for choosing work on
+2026-09-27 (`skill://dispatch`, "Choosing what to work on"): take the top ready issue, "status
+`todo`, highest priority first, then board rank"; an issue that waits on a deploy or a decision
+belongs in `backlog`, so the walk takes nothing from `backlog` or `triage`. The Go daemon runs
+only labelled roots, so every root it ran since the daemon required the label carries it: a
+labelled root in `todo` is the daemon's to admit or queue, one in `triage` is yours to triage
+(step 2 above), and one anywhere else was parked by Legion or by a person. A child you take becomes
+a root of its own: the daemon admits a labelled `todo` child whose tree Legion does not run as a
+new tree. The `dispatch_issues` rows show no labels and no children, so the listing below filters
+neither: both are checked on each candidate (the table's first rows). List the `todo` issues one
+priority at a time, `priority: [0]` first, then `[1]`, `[2]`, `[3]`, and `[null]` (no priority)
+last, keeping the listing's order within each, which is the board's rank:
+
+```text
+dispatch_issues({ project: "<PROJECT>", status: "todo", priority: [0], limit: 250, offset: 0 })
+```
+
+When the first line ends `(showing 1-250 of N)`, the next page is `offset: 250`, then `500`. Read
+pages only as far as you need: stop listing once the free slots are filled. `<PROJECT>` is the
+Dispatch project key, the prefix of this deployment's issue keys (`AGENTC-12` → `AGENTC`), which is
+also `daemon.project` in `legion state --json`: the project key exactly as `legion.yaml` writes it.
+A row that shows `claimed by …` and does not end its claim with `· not running` (the route, when
+the row shows one, comes after the claim) is claimed, as the table below says: skip it without
+reading it.
+
+**Walk.** Take the remaining rows in that order until the free slots are filled. Read each one with
+`dispatch_read({ issue: "<KEY>" })` and skip it when any of these holds. `dispatch_read` shows only
+the issue's last 10 events, so the rows that read `Events:` are best-effort: the pull-request row
+leans on `External links:`, and the label row is the one that never depends on history.
+
+| Skip when | How you check it |
+|---|---|
+| It carries the `legion` label | `Labels:` lists `legion`, in any case. Legion has the issue or had it, as **Candidates** above says. |
+| It has any child | `dispatch_read({ ref: "dispatch://<KEY>/children" })` lists any child, open or `done`. It is an umbrella, and a finished umbrella is still no leaf. That also skips an issue whose only child is done, which is accepted. Its open children are candidates themselves, each in its own place in the order. |
+| An ancestor is Legion's | Follow `Links:` up through each `child_of` parent, reading each one, and skip when any ancestor carries the `legion` label or is recorded under `issues` in `legion state --json`, whatever its status: a Legion tree, running or parked, owns its children. An ancestor's claim or route does not skip the issue: a coordinator holding an umbrella files `todo` leaves for others to pick up, and the claim on the issue itself is what keeps two sessions off the same work. A `child_of` under `Referenced by:` is a child of this issue, not its parent. |
+| Someone is designing it | `Open asks:` lists any ask, a `Spec approval: awaiting …` line shows the spec waits on a human, or `Events:` show an `artifact.version` or an `ask.opened` from the last seven days: a session or a person is shaping it even when nobody claims or routes it. |
+| Legion ran it without the label now on it | `legion state --json` records it under `issues`, whatever its status, or `Events:` show a status write by `session legion-daemon:<PROJECT>`, the daemon's actor on every `legion status` (yours included) and on its own `in_progress` at admission. That covers a root a person took the label off, and one that ran before the daemon required the label and never had it. Name each one you skip for this in your summary. The walk never sends a root Legion already ran back into Legion: a person does that with the label and `todo`, and you do it only when a wake below says to (`worker-died`, closed-tree activity). |
+| A running session or a person claims it | `Claimed by:` names anyone and does not end `· not running`. `· liveness unknown` counts as claimed: the agent registry could not be read, so nothing says the holder stopped. A claim ending `· not running` has lapsed, and the issue is free. |
+| Its route reaches a running session | `Route:` names a route with nothing after it, or with `(held by …)`. `(nobody holds it right now)` and `(that session is not running right now)` reach nobody; `(the Envoy listener did not answer, …)` counts as reaching someone. `Route: none` is free. |
+| A pull request is linked or named | `External links:` lists a pull request (kind `github_pr`, or a URL ending `/pull/<n>`), or a comment or message among `Events:` names one. You cannot read GitHub, so an open, merged, or closed pull request all count. A person who wants Legion on it anyway hands it over themselves: the label, then `todo`. |
+| Its assignee is working it | `Assignee:` names a person who holds the claim (the row above), or whose own comment or message among `Events:` says they are working on it. The assignee alone is who answers the issue's questions, not who works it. |
+| It is outside this deployment's scope | Read the scope the deployment instructions state against the title and, when the title does not settle it, the spec (`dispatch_doc_read({ issue: "<KEY>" })`). When in doubt, skip it. With no scope stated, every issue of the project is in scope. |
+
+**Take.** For each candidate that passes, in order:
+
+1. Add the label and keep the labels it has, which `Labels:` lists (`none` is no labels). `labels`
+   replaces the whole set, so a label you leave out is removed.
+
+   ```text
+   dispatch_issue_update({ issue: "<KEY>", labels: ["<each current label>", "legion"] })
+   ```
+
+2. It is already in `todo`, so the label admits it: the daemon records it and gives it the free
+   slot, or queues it in `admission.waiting`. It needs no status write.
+3. Post one short comment that says Legion took it and names who is asked at its design gate, from
+   the `Assignee:` line, with the assignee sentence [New issue triage](#new-issue-triage) step 4
+   gives:
+
+   ```text
+   dispatch_comment({ issue: "<KEY>", body: "Legion took this issue: it was the highest-priority open issue nobody else was working on. Assigned to <login>, who will get this tree's questions and its design approval." })
+   ```
+
+The daemon admits each root when Dispatch's event reaches it; the next `legion state --json`
+shows it in `admission.active`. When the candidates run out with slots still free, leave those
+slots free and say so in your summary.
+
+## Daily report (Go daemon)
+
+Once a day, post one Dispatch message that says what Legion finished, what it closed without a
+change and why, and what is running.
+
+**Where.** On the issue the deployment instructions name for Legion's reports. With none named,
+on the project's `Legion daily report` issue:
+`dispatch_search({ query: "\"Legion daily report\"", project: "<PROJECT>" })` finds it. When it
+does not exist, create it once and park it in `icebox`, so nobody takes it as work; it never
+carries the `legion` label:
+
+```text
+dispatch_issue({ project: "<PROJECT>", title: "Legion daily report", spec: "## Summary\n\nLegion's controller posts one message here each day: what Legion finished, what it closed without a change and why, and what is running. This issue is not work, so it carries no `legion` label and stays in icebox." })
+legion status <report KEY> icebox
+```
+
+**When.** On your first turn of each UTC day, whatever it is: your start, or a wake of any kind.
+Read the report issue with `dispatch_read`, and post when its `Events:` show no `message.created`
+from today. You have no clock of your own, so a day with no turn has no report; the next one
+covers it.
+
+**What.** One `dispatch_message({ issue: "<report KEY>", body })` of at most 2,000 characters,
+written as `skill://dispatch`'s "Writing for the human" says: every issue by its key and title,
+every pull request by its URL.
+
+- **Finished.** `dispatch_issues({ project: "<PROJECT>", status: "done", updated_since: "<the
+  previous report's time, or 24 hours ago>", limit: 250 })`, read every page, and keep the issues
+  `legion state --json` records under `issues` whose `issue.closed` event is after the previous
+  report. For each, `dispatch_read` it: the pull request under `External links:` is the one that
+  merged.
+- **Closed without a change.** Those with no pull request, each with the reason its closing
+  message gave (the `message.created` just before `issue.closed` among `Events:`).
+- **Running.** Each root in `admission.active` with its `issues.<KEY>.phase`, and the roots in
+  `admission.waiting`.
+
+A day with nothing finished says so in one sentence. When the lists do not fit, keep the counts
+and the highest-priority issues.
 
 ## Deployment instructions
 
@@ -136,7 +270,8 @@ quoted here.
 - **Direct user message always first.** If this turn includes a direct user message, answer
   it before handling every other wake.
 - **One wake = one turn.** Handle exactly the wake's implication, then end the turn. Never
-  poll, idle-loop, or wait for another event.
+  poll, idle-loop, or wait for another event. The one addition: your first turn of each UTC day,
+  whatever woke you, also posts the day's report ([Daily report](#daily-report-go-daemon)).
 - **Wakes are advisory.** Before any side effect, verify the current daemon state and the
   relevant Dispatch issue. A stale or duplicate wake may cost a read, never a wrong action.
 - **Controller state is disposable.** Do not reconstruct or preserve local controller
@@ -151,7 +286,8 @@ quoted here.
 | Wake | Content | Controller action |
 |---|---|---|
 | New issue created in the Dispatch project (`issue.created`, status `triage`; under the TypeScript daemon resync heals misses, under the Go daemon the boot step above does). From the Go daemon: `triage on <KEY>` (payload `{kind: "triage"}`) on the controller topic, for an unrecorded root carrying the `legion` label only ("Issues handed to Legion" above) | issue key + triage context (incl. pre-existing children) | Triage: `legion status <KEY> todo` to admit, or set `backlog`/`icebox` to park |
-| Backlog eligibility | slot freed / priority change | Reconsider parked items and move the eligible root to `todo` |
+| Backlog eligibility (TypeScript daemon) | slot freed / priority change | Reconsider parked items and move the eligible root to `todo` |
+| `slot-free on <KEY>` from the Go daemon (payload `{kind: "slot-free"}`) | the root whose slot the daemon released with no waiting root to take it | Verify a free slot in `legion state --json`, then fill it ([Keeping the slots full](#keeping-the-slots-full-go-daemon)) |
 | Architect escalation (controller-actionable only: re-file a child as a root issue, capacity, cross-tree conflicts) | request + context | Judge and act; issue-scoped human Q&A goes through `dispatch_ask` from the owning architect, not here |
 | Resync report | artifact-driven anomaly list (zero-owner trees, untriaged-open, launch-failed, admission-drift) | Verify against fresh state, then heal |
 | Resync report: `admission-drift` entry | issue key + whether the daemon added it to, or removed it from, its admission list (the detail says which) | No action: the daemon already repaired it in the same run. An issue that reappears in consecutive reports is a live leak — file a LEGION issue on Dispatch with both reports pasted as evidence (never a GitHub issue) |
@@ -187,19 +323,30 @@ quoted here.
 
    (or `icebox` for longer-term deferral). Dispatch status is the durable record; there is no
    other marker to maintain, beyond the Go daemon's `legion` label, which parking leaves in
-   place. Do not triage a system-created child as a root issue.
+   place. Under the Go daemon a root never waits for capacity in `backlog`: in `todo` the
+   daemon's admission queue holds it (`admission.waiting`), so park only a root that should not
+   run now. Do not triage a system-created child as a root issue.
 4. When you post a triage note (a `dispatch_comment` on the issue saying what you decided and
-   why), name who will be asked: `Assigned to <login>, who will get this tree's questions`,
-   or, when the `Assignee:` line says `unassigned`, `Unassigned — nobody's Inbox shows this
-   tree's questions until someone takes it from the issue header (Assignee, beside Priority)`.
-   An unassigned root still runs; the architect's asks wait in every Inbox's Unassigned band.
+   why), name who will be asked with the assignee sentence: `Assigned to <login>, who will get
+   this tree's questions and its design approval`, or, when the `Assignee:` line says
+   `unassigned`, `Unassigned — nobody's Inbox shows this tree's questions or its design approval
+   until someone takes it from the issue header (Assignee, beside Priority)`. An unassigned root
+   still runs; the architect's asks wait in every Inbox's Unassigned band.
 
 ## Backlog eligibility
 
-When a slot frees or priority changes, use `legion state --json` and the current Dispatch
-issue to reconsider parked roots. Admit the selected root with
-`legion status <KEY> todo`. Moving an item to or from `backlog`/
-`icebox` is a deliberate controller decision, not a no-op.
+Under the Go daemon nothing reconsiders `backlog` or `icebox` on its own: [Keeping the slots
+full](#keeping-the-slots-full-go-daemon) takes only `todo` issues, since an issue that waits on a
+deploy or a decision belongs in `backlog` (Sami's ruling of 2026-09-27, `skill://dispatch`,
+"Choosing what to work on"). A handed-over root waits for a slot in `todo`, where the daemon's
+admission queue holds it (`admission.waiting`), so a park means "should not run now", and a
+parked root keeps its `legion` label. A parked issue runs again when a person sets it to `todo`,
+or when a wake tells you to re-admit it (`worker-died`, closed-tree activity).
+
+Under the TypeScript daemon, when a slot frees or priority changes, use `legion state --json` and
+the current Dispatch issue to reconsider parked roots. Admit the selected root with
+`legion status <KEY> todo`. Moving an item to or from `backlog`/`icebox` is a deliberate
+controller decision, not a no-op.
 
 ## Architect escalation
 
@@ -212,8 +359,10 @@ and the Dispatch issue. If the work belongs in an independent root:
 
 1. File a **fresh root issue** with `dispatch_issue({ project, title, spec })` (no `parent`;
    under the Go daemon add `labels: ["legion"]`, without which it is never admitted).
-   `project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`) — not
-   the role-token `<project>` (the daemon's own project, e.g. `acme`), a different string.
+   `project` is the issue key's prefix before `-<n>` (e.g. `LEGSMOKE-3` → `LEGSMOKE`): the
+   project key exactly as `legion.yaml` writes it, which `legion state --json` shows as
+   `daemon.project`. It is not the lowercase project token in role names such as
+   `legion-<project>-controller`.
 2. Park the child (`legion status <child> icebox`) and leave
    a pointer to the new root issue. The controller's capability is `todo`/`backlog`/`icebox`
    only — only the owning architect or the daemon closes an issue as `done`.