@sjawhar/pi-legion 19.31.1 → 19.31.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/dist/legion.js CHANGED
@@ -18355,6 +18355,7 @@ function roleForPhase(phase) {
18355
18355
  return "tester";
18356
18356
  case "reviewing":
18357
18357
  return "reviewer";
18358
+ case "admitted":
18358
18359
  case "accepting":
18359
18360
  return "architect";
18360
18361
  case "merging":
@@ -27107,6 +27108,9 @@ var legionIssue = object({
27107
27108
  memoryDrawnAt: timestamp.optional(),
27108
27109
  phaseEntry: number2().int().nonnegative().optional(),
27109
27110
  givenEntry: number2().int().nonnegative().optional(),
27111
+ entryQueuedAt: timestamp.optional(),
27112
+ entryConfirmedAt: timestamp.optional(),
27113
+ architectStalls: array(_enum2(["took-nothing", "claim-unreachable", "slow-before-gate"])).optional(),
27110
27114
  treeMovedAt: timestamp.optional(),
27111
27115
  quietHours: number2().nonnegative().optional(),
27112
27116
  assignments: array(legionAssignment).optional()
@@ -29799,7 +29803,7 @@ import { logger as logger3 } from "@oh-my-pi/pi-utils";
29799
29803
  // package.json
29800
29804
  var package_default = {
29801
29805
  name: "@sjawhar/pi-legion",
29802
- version: "19.31.1",
29806
+ version: "19.31.3",
29803
29807
  license: "Apache-2.0",
29804
29808
  type: "module",
29805
29809
  omp: {
@@ -29811,7 +29815,7 @@ var package_default = {
29811
29815
  ]
29812
29816
  },
29813
29817
  legion: {
29814
- daemonApiVersion: 144
29818
+ daemonApiVersion: 146
29815
29819
  },
29816
29820
  repository: {
29817
29821
  type: "git",
@@ -1,6 +1,6 @@
1
1
  ---
2
2
  name: legion-controller
3
- description: Use when you are a Legion project's controller session, on any controller wake (triage, slot-free, todo, tick, unslotted, awaiting-person, tree-stalled, parked-decision, held, worker-died, worker-stalled, update-stalled, provider-errors), weekly-plan ranking, backlog stewardship, a clear defect or finding ask a role sends, an issue a person asks you to file, the daily report, an architect's escalation, or a person's message or mention.
3
+ description: Use when you are a Legion project's controller session, on any controller wake (triage, slot-free, todo, tick, unslotted, awaiting-person, tree-stalled, architect-stalled, parked-decision, held, worker-died, worker-stalled, update-stalled, provider-errors), weekly-plan ranking, backlog stewardship, a clear defect or finding ask a role sends, an issue a person asks you to file, the daily report, an architect's escalation, or a person's message or mention.
4
4
  ---
5
5
 
6
6
  # Legion Controller
@@ -74,6 +74,7 @@ Wake details: `skill://legion-controller/references/wakes.md`.
74
74
  | `unslotted on <KEY>` | Re-admit nothing; name it in your summary |
75
75
  | `awaiting-person on <KEY>` | Nothing: do not park or re-admit it, and take nothing for its slot, which it keeps while it waits |
76
76
  | `tree-stalled on <KEY>` | Read the tree and decide: ask a role what it waits on, move an issue back a phase, or park the tree only as [Rules](#rules) allows |
77
+ | `architect-stalled on <KEY>` | Read the root's architect claim in `read_state`, then for the first arm take nothing while it is `working`, since the task reaches it when that turn ends, and name it in the day's report, or else `compact` that claim and use `fresh_session` only when it still does not take its task; for the second, `fresh_session` on a failed or retired claim; for the third, decide what the time means (`skill://legion-controller/references/wakes.md`) |
77
78
  | `parked-decision on <KEY>` | `skill://legion-controller/references/parked-decisions.md#deciding` |
78
79
  | `held on <KEY>` | Nothing, unless `reason: "escalated"`: then an escalation, decided from the failed claim's `failure` in `read_state` and the limits in `settings` (`skill://legion-controller/references/escalation.md#an-escalated-hold`) |
79
80
  | `worker-died on <KEY>` (`role: "architect"`) | Nothing when the root's `phase` is `done`: the tree is parked already. Otherwise restart the tree when you find no cause or its cause is gone, and ask whether to park it when the cause stays (`skill://legion-controller/references/wakes.md#ask-whether-to-park-a-tree`) |
@@ -168,6 +168,71 @@ Legion, do as [A tree that waits on an event outside Legion](#a-tree-that-waits-
168
168
  The daemon starts nothing for this wake, and tells you once for
169
169
  each tree: the next movement of that tree is what lets it tell you again.
170
170
 
171
+ ## `architect-stalled on <KEY>` (`{kind: "architect-stalled", role: "architect", reason}`)
172
+
173
+ A root whose own architect is not taking the work the daemon states it is owed.
174
+ `reason` begins with the arm that raised it, and one root raises each arm once per run, so two wakes of one root are two different facts:
175
+
176
+ - "the architect took nothing": the task of the entry the architect's `phases` row names was first queued to its claim more than ten minutes ago and no turn of that claim confirmed it.
177
+ The claim keeps one such moment, for the entry it was last queued a task of: when that entry's task was first queued, so a task the daemon sent again for that entry is counted from that first queueing and not from the send.
178
+ A process of the claim that dies or that the daemon replaces in the middle of a turn of that task — a crash, an out-of-memory kill, a relaunch onto the current plugin, a stalled turn the daemon ends — leaves the task to be sent again to the relaunched agent.
179
+ Such a task counts only while the claim is ready, working or idle, and from the moment the relaunched agent said it was ready where that is later than that first queueing, so the relaunch of an architect that was working its task raises no wake.
180
+ The daemon writes no second start of that entry while its task stands, so this wake is the one thing left.
181
+ A task the root's own record has superseded — one that carries an entry, of a run before its generation or of an entry the row has moved past — raises this arm not at all: the daemon writes the start of the entry the row names instead, and that start's task takes the held task's place.
182
+ A task that carries no entry, such as the one a wake of the architect's released pod gives, raises it not at all either, and no start takes its place: the daemon sends it first, and sends the entry's task once a turn has taken it.
183
+
184
+ - "the architect's claim cannot be reached": the claim is failed or retired and no start of the root's run is the daemon's next move for it, or the root has no architect claim at all, no start of one was queued in the last ten minutes, and the work of its entry has stood that same bound.
185
+ A start the outbox is running is that next move, and so is a start queued in the last ten minutes unless it has already run against the claim and left it failed or retired.
186
+ While such a start will relaunch a failed or retired claim, the daemon raises no such wake, because that start resumes the session the claim kept.
187
+ The claim reads failed or retired while the outbox runs that start, until the run relaunches it.
188
+ A start that has run against the claim and left it failed or retired, which the daemon retries on its backoff, does not hold the wake back, and neither does one that has stood owed for longer than ten minutes.
189
+ A root waiting on a person raises it as any root does, and its reason then says that the root waits: the daemon queues the next start of its architect only when that wait is answered.
190
+ For a root with no claim, the reason also says whether the daemon wrote the start of its architect again in the same transaction as the wake.
191
+
192
+ - "the root is slow before its gate": the root stands at `admitted` with no design-gate step registered, 90 minutes after it was admitted or after its architect's entry was last raised, whichever is later.
193
+ An architect that is writing a spec raises this one, and that is healthy work: the wake reports it and decides nothing.
194
+
195
+ The daemon tells you of an arm only while a controller is registered for the project.
196
+ An arm that holds while none is registered is told at the first pass after one registers.
197
+
198
+ Read `issues.<KEY>.architectStalls` to see every arm that holds for that root now, by the arm's value: `took-nothing`, `claim-unreachable` or `slow-before-gate`.
199
+ The daemon reads that key by the same rules as this wake, and it lists an arm whether or not you were told of it.
200
+ `legion state` prints the same key.
201
+
202
+ Read `issues.<KEY>.entryQueuedAt` and `entryConfirmedAt` to see the handshake the daemon and that architect have: when the task of its entry was queued to its claim, and when a turn of that claim confirmed it.
203
+ Those two times are the architect's in every phase the root stands in.
204
+ At `admitted`, `phaseEntry` and `givenEntry` are the architect's as well.
205
+ Past `admitted`, they are the numbers of the role that works the phase the root stands in, and that role is the architect again only in `accepting`.
206
+ Read `gatedSteps` to see where each step of its gate stands.
207
+
208
+ For the first arm, read the root's architect claim in `read_state` (`issues.<KEY>.architect`).
209
+ The daemon sends that task no second time while it stands, so you are the one who acts on it:
210
+
211
+ 1. When the claim's `state` is `working`, it is in a turn, and the task reaches it when that turn ends.
212
+ Take nothing, and name the root in the day's report.
213
+
214
+ 2. Otherwise the task did not reach its session.
215
+ `compact` that claim with the `legion` tool, with the root's key as the issue and `architect` as the role.
216
+ The daemon shortens the claim's session and sends it the task it owes again.
217
+ A refusal of `compact` names the door to use in its place.
218
+
219
+ 3. Use `fresh_session` on that claim only when it still does not take its task after the compaction.
220
+ A new session loses everything the old one held.
221
+
222
+ For the second arm, read the root's architect claim in `read_state` too.
223
+ A `failed` or `retired` claim this wake names has no start that will relaunch it: no start of its run was queued in the last ten minutes, or the one the queue holds has run against it and left it as it is, which the daemon retries on its backoff.
224
+ It takes nothing the daemon sends.
225
+ `fresh_session` on it, with the root's key as the issue and `architect` as the role, starts it again.
226
+ When the reason says the root waits on a person, take no `fresh_session` while it waits, since the start the answer queues relaunches the session the claim kept, and `fresh_session` would discard it.
227
+ Name that root in the day's report with what it waits on (`issues.<KEY>.waitingOn`: the ask, or the version of its gate), so a person knows the tree has no architect that can run until they answer.
228
+ That wake is the arm's one wake of the root's run: the daemon marks the arm told for the run, and the answer starts no new run, so it does not tell you again when the wait is answered or when the start the answer queues fails against the claim.
229
+ So at each `tick` after `issues.<KEY>.waitingOn` is gone, read `issues.<KEY>.architectStalls`, which lists an arm whether or not you were told of it, and when it lists `claim-unreachable`, take `fresh_session` on that claim as for any other claim of this arm.
230
+ A root with no architect claim has no claim for `compact` or `fresh_session` to reach, and each answers `NO_CLAIM` for it.
231
+ When the reason says the daemon wrote the start of its architect again, take nothing, because that start creates the claim when it runs, and name the root in the day's report.
232
+ When the reason says no start of one queued in the last ten minutes waits to create it, or a later `read_state` still shows no `architect` for the root, name it in the day's report as a root the daemon could not start.
233
+
234
+ For the third, decide what the time means — a tree whose spec is long is working, and a tree whose architect has nothing to show is an escalation (`skill://legion-controller/references/escalation.md`).
235
+
171
236
  ## `parked-decision on <KEY>` (`{kind: "parked-decision", decision, root, ref, actor, version?, reason?}`)
172
237
 
173
238
  A person's spec decision, or answer, resolution or reply on an ask, on a tree Legion is not
@@ -35,7 +35,9 @@ as the fingerprint decides (*The reviewer*, below, and
35
35
  commit, so every push to the branch is work whose head gets GitHub's workflow runs of its own.
36
36
  With `<o>/<r>`, `<n>`, `<base>` and `<headRefOid>` from
37
37
  `gh pr view <n> --json baseRefName,headRefOid`, two reads. The required set is the
38
- base branch's rulesets' required checks and its branch protection's, when it has any. Both
38
+ base branch's rulesets' required checks and its branch protection's, when it has any.
39
+ A check the base does not require holds no approval. You neither wait for it nor re-run it for the approval, and the daemon reads no verdict from it either. Read its result all the same. A red one whose log shows that the change breaks something is a correctness finding like any other. A red one that shows no fault of the change is named in the review body and decides nothing.
40
+ Both
39
41
  branch endpoints take the base as a URL path, each segment escaped and each `/` kept (a raw `#`
40
42
  or `%` reads another branch), built in the same command from the name GitHub returns, never
41
43
  pasted or carried over from an earlier command:
@@ -49,10 +51,13 @@ as the fingerprint decides (*The reviewer*, below, and
49
51
  ```
50
52
 
51
53
  A read GitHub refuses stops the command there, and is reported to the architect, never guessed.
54
+ With that read refused, the required set is unknown, so no required item can be judged: do not approve, and wait with a `WAITING` line naming the refused read. The architect has the read made with a credential that can make it, or asks a person, and the review goes on from its answer.
52
55
  The head's check-runs
53
56
  (`gh api repos/<o>/<r>/commits/<headRefOid>/check-runs --paginate --jq '.check_runs[] | [.name, .status, .conclusion] | @tsv'`):
54
57
  every required name present, `completed` and `success` (GitHub counts `neutral` and `skipped`
55
- as passing for a required check). A required check
58
+ as passing for a required check).
59
+ When the list holds more than one run of a required name, the newest run decides, the one with the latest `started_at`. An older run of that name, whatever its conclusion, is no result: never re-run a job for a `cancelled` row that a newer run of the same name has superseded. Read the whole list before you choose. `--paginate` runs `--jq` once per page, so take the newest of each name over the merged list, not inside the `--jq`. A commit status is read the same way: the newest status of each context decides.
60
+ A required check
56
61
  `queued`, `requested`, `waiting`, `pending` or `in_progress`: wait. One `completed` as `cancelled`, or absent from a run at the
57
62
  head that holds its job: on a `pull_request` run, re-run that run's
58
63
  failed and cancelled jobs, once, then wait — never the whole run, which runs again every job that
@@ -80,6 +85,7 @@ as the fingerprint decides (*The reviewer*, below, and
80
85
  the head has settled.
81
86
  For such an item, what the base requires is more than its status checks: a `code_scanning` rule, which the read above prints under `code_scanning:`, requires an analysis no status-check list names.
82
87
  Read the merge state first, whatever the head's other runs show (`gh pr view <n> --repo <o>/<r> --json mergeable,mergeStateStatus`): a head that conflicts with its base (`DIRTY`) has no merge ref, so GitHub starts no `pull_request` run for it, while a `pull_request_target` run, which GitHub builds from the base with no merge ref, can be green beside the missing item.
88
+ A merge state of `UNKNOWN` is one GitHub has not computed yet: read it again after a minute, and for up to five minutes. A state still `UNKNOWN` after that, or a read that fails twice, is reported to the architect with the answer GitHub gave, as a refused read is: do not approve, and wait with a `WAITING` line naming the read. A read that GitHub answers with a rate limit waits for the reset the answer names, and is then made again.
83
89
  Count the head's runs: `gh api repos/<o>/<r>/commits/<headRefOid>/check-runs --jq .total_count`.
84
90
  A head GitHub computes no merge for (`DIRTY`) takes a merge of its base forward, which is the implementer's push, and never the remedy below; the daemon itself sends such a head back to implementing, so it never waits in the issue's `mergeWait` once a read has answered for it.
85
91
  A commit status is no check run, so read the head's commit statuses as well as the check-runs list above, every page: `gh api --paginate 'repos/<o>/<r>/commits/<headRefOid>/status?per_page=100' --jq '.statuses[] | [.context, .state] | @tsv'`.
@@ -96,6 +102,7 @@ as the fingerprint decides (*The reviewer*, below, and
96
102
  A job reports its `name:`, an expression there evaluated for each matrix entry, or else its key, with ` (<matrix values>)` after it for a matrix job; a job of a reusable workflow reports `<calling job> / <job>` and runs on the calling file's `on:`; and for a `code_scanning` rule the jobs that run the tool's analysis report under their own names, while the tool's own check run (`CodeQL`) is the code-scanning App's, made when an analysis uploads, so a head whose analysis jobs ran with no `CodeQL` run is no head this test matches.
97
103
  Third, neither list holds a run of it.
98
104
  That head takes the remedy.
105
+ A head with more than one required item that has no run takes the remedy when its first part holds for the head and at least one item meets the second and third parts: the close and reopen is one act for the whole head. Before you close, tell the architect about every other such item in the same message, by its case. Each of them is then waited for as its own case says, and none of them is a reason to reopen a second time. A head with any item in a case that says never close and reopen it takes no remedy for any of its items.
99
106
  A head that matches none of these cases takes no remedy: tell the architect, do not approve, and wait with a `WAITING` line naming what you wait on; the architect takes it to a person, since GitHub has more cases than these, so an unknown case costs a person's look rather than a wrong action.
100
107
  So does a head whose required item still has no run once every run the reopen started has concluded (before then the item is missing only because its run has not started): tell the architect, do not approve, and wait with a `WAITING` line naming what you wait on, and never reopen it a second time.
101
108
  Close the pull request, wait a minute, and reopen it at the same head: in cybermonklabs/legion a reopen within about a minute of the close can have its new CI run cancelled by the close's own run, which leaves a failing `ci-ok` (`.github/workflows/tests-closed.yaml`).
@@ -104,13 +111,13 @@ as the fingerprint decides (*The reviewer*, below, and
104
111
  So tell the architect before you close, and say why.
105
112
  Do not approve until the required item's run at the head has concluded green: the remedy is how it gets a run, not a reason to approve without one.
106
113
  It is for no other state: not a check that is running, not a check that is red, and not a head GitHub holds for a review the repository requires.
107
- A head whose checks are still running is waited for, unapproved: in the two lists above, a check run whose status is `queued`, `requested`, `waiting`, `pending` or `in_progress`, or a commit status whose state is `pending`, is running, not missing.
114
+ A head whose required checks are still running is waited for, unapproved: in the two lists above, a check run whose status is `queued`, `requested`, `waiting`, `pending` or `in_progress`, or a commit status whose state is `pending`, is running, not missing.
108
115
  For a GitHub Actions job, GitHub ends that wait itself: a job still queued for a self-hosted runner after 24 hours is cancelled, a running job ends at its own `timeout-minutes` or at GitHub's execution limit, 6 hours on a GitHub-hosted runner and 5 days on a self-hosted one, which fails it, and every workflow run ends at 35 days, its waiting included (GitHub's Actions limits page); the settlement of that conclusion moves the round.
109
116
  A run `waiting` on an environment's approval waits on a person, up to 30 days, and a check run no Actions job owns, another GitHub App's or one a workflow created through the API, or a commit status left `pending`, has no such bound and ends only when whoever made it ends it: one that stands longer than its CI usually takes is the architect's to raise with a person, so tell the architect, naming the run, do not approve, and wait with a `WAITING` line naming what you wait on.
110
117
  The daemon's own count in the issue's `mergeWait`, `checkRuns`, is only the runs a CI settlement applied, so a zero there is no evidence of what GitHub holds: read the two lists on GitHub before you act.
111
118
  Approval is refused while any `before_merge` check of the issue's own Verification document has no pass standing at the head being reviewed: `REQUEST_CHANGES` naming each such check by its block id, and `dispatch results --issue <issue>` is the read that decides it, under the check's own line saying whether a pass stands and from which roles. That answer leaves out a pass at another commit, a pass recorded under an older wording of the check and a retracted pass, each of which the command still prints; a fail recorded after a pass leaves that pass standing until someone retracts it.
112
119
  A check carrying `ci_check` is CI's: the one result that `dispatch results` derives from the named run decides it (`skill://legion-worker/references/ci-checks.md`). While that run has not concluded, wait for it by its name, and do not approve or request changes for that check. Wait the same way where GitHub could not be read. When no run of that name answers after the head's checks settle, tell the architect as a finding and request no changes for it.
113
- A check whose `run` is a whole test suite has wrong words, which the architect rewrites: tell the architect as a finding, wait for the rewrite with a `WAITING` line naming it, and request no changes for it.
120
+ A check whose `run` is a whole test suite and has no pass standing at the head has wrong words, which the architect rewrites: tell the architect as a finding, wait for the rewrite with a `WAITING` line naming it, and request no changes for it. One that has a pass standing at the head is a finding for the architect too, and its pass decides the check, so the review goes on.
114
121
  An issue with no Verification document, or whose Verification document holds no `before_merge` check, is a gap you name in the review body, never a review that asks for changes: say which of the two it is, and tell the architect, who writes the checks. Your own findings and the checks that do exist still decide the review, and on an issue that has none the architect's acceptance is the gate.
115
122
  A result proves the head it was recorded at. A result a child recorded against a root's check proves nothing for the root, since it was recorded at the child's head, and a child never records the result that proves a root's check. A child that carries part of a root's requirement proves it with a check on the child's own Verification document whose `serves` names that requirement, at the child's own head. A root's own checks are proven at the root's own head, or, for an `after_merge` check, on the branch the root's pull request merged into or on the repository's default branch, in the root's last round.
116
123
  On a docs-only PR the `Thermo` line still records the simplify pass and the defects it
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@sjawhar/pi-legion",
3
- "version": "19.31.1",
3
+ "version": "19.31.3",
4
4
  "license": "Apache-2.0",
5
5
  "type": "module",
6
6
  "omp": {
@@ -12,7 +12,7 @@
12
12
  ]
13
13
  },
14
14
  "legion": {
15
- "daemonApiVersion": 144
15
+ "daemonApiVersion": 146
16
16
  },
17
17
  "repository": {
18
18
  "type": "git",