mandrel 2.123.0 → 2.125.0

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.
Files changed (105) hide show
  1. package/.agents/README.md +1 -1
  2. package/.agents/docs/agentrc-reference.json +2 -0
  3. package/.agents/docs/configuration.md +6 -3
  4. package/.agents/docs/runbooks/dispatch-board.md +174 -0
  5. package/.agents/docs/runbooks/dispatch.md +219 -0
  6. package/.agents/docs/runbooks/session-titles.md +52 -0
  7. package/.agents/runtime-deps.json +2 -2
  8. package/.agents/schemas/agentrc.schema.json +85 -3
  9. package/.agents/schemas/audit-rules.schema.json +1 -1
  10. package/.agents/schemas/story-deliver-terminal.schema.json +7 -2
  11. package/.agents/scripts/acceptance-eval.js +11 -2
  12. package/.agents/scripts/check-doc-links.js +4 -4
  13. package/.agents/scripts/dispatch.js +400 -0
  14. package/.agents/scripts/lib/audit-baselines/surface-entry.js +2 -2
  15. package/.agents/scripts/lib/audit-exceptions/globs.js +2 -2
  16. package/.agents/scripts/lib/audit-exceptions/scope.js +2 -2
  17. package/.agents/scripts/lib/audit-suite/selector.js +3 -3
  18. package/.agents/scripts/lib/baselines/bundle-size-scorer.js +3 -3
  19. package/.agents/scripts/lib/baselines/components.js +2 -2
  20. package/.agents/scripts/lib/baselines/kinds/_crap-new-method-gate.js +2 -2
  21. package/.agents/scripts/lib/bdd-runner-detect.js +3 -4
  22. package/.agents/scripts/lib/child-detached.js +48 -0
  23. package/.agents/scripts/lib/child-exec.js +11 -0
  24. package/.agents/scripts/lib/close-validation/base-sync-revalidation.js +2 -2
  25. package/.agents/scripts/lib/config/delivery-routing.js +15 -12
  26. package/.agents/scripts/lib/config/gates/coverage.schema.js +1 -1
  27. package/.agents/scripts/lib/config/handoff.js +21 -6
  28. package/.agents/scripts/lib/config/temp-paths.js +26 -0
  29. package/.agents/scripts/lib/config-settings-schema-delivery.js +64 -10
  30. package/.agents/scripts/lib/config-settings-schema-quality.js +1 -1
  31. package/.agents/scripts/lib/coverage-baseline.js +3 -3
  32. package/.agents/scripts/lib/coverage-capture-delta.js +2 -2
  33. package/.agents/scripts/lib/coverage-capture-own-fix.js +2 -2
  34. package/.agents/scripts/lib/dispatch/environments.js +135 -0
  35. package/.agents/scripts/lib/dispatch/launch-cloud.js +164 -0
  36. package/.agents/scripts/lib/dispatch/launch-local.js +77 -0
  37. package/.agents/scripts/lib/dispatch/liveness.js +21 -0
  38. package/.agents/scripts/lib/dispatch/record.js +54 -0
  39. package/.agents/scripts/lib/dispatch/status.js +285 -0
  40. package/.agents/scripts/lib/dispatch/targets.js +101 -0
  41. package/.agents/scripts/lib/dispatch/verdict.js +207 -0
  42. package/.agents/scripts/lib/generated/agentrc-validator.js +2 -2
  43. package/.agents/scripts/lib/git-test-guard.js +119 -0
  44. package/.agents/scripts/lib/git-utils.js +3 -0
  45. package/.agents/scripts/lib/maintainability-utils.js +4 -4
  46. package/.agents/scripts/lib/observability/handoff-telemetry.js +2 -0
  47. package/.agents/scripts/lib/observability/source-classifier.js +2 -0
  48. package/.agents/scripts/lib/orchestration/acceptance-eval-decision.js +3 -2
  49. package/.agents/scripts/lib/orchestration/block-class-recovery.js +44 -0
  50. package/.agents/scripts/lib/orchestration/code-review.js +35 -19
  51. package/.agents/scripts/lib/orchestration/diff-magnitude.js +1 -1
  52. package/.agents/scripts/lib/orchestration/git-cleanup/phases/filters.js +3 -3
  53. package/.agents/scripts/lib/orchestration/plan-persist/audit-attribution.js +3 -4
  54. package/.agents/scripts/lib/orchestration/review-history.js +9 -10
  55. package/.agents/scripts/lib/orchestration/review-providers/code-review.js +9 -2
  56. package/.agents/scripts/lib/orchestration/review-providers/codex-cli.js +8 -5
  57. package/.agents/scripts/lib/orchestration/review-providers/codex.js +3 -11
  58. package/.agents/scripts/lib/orchestration/review-providers/mi-exemptions.js +2 -2
  59. package/.agents/scripts/lib/orchestration/review-providers/review-depth.js +22 -0
  60. package/.agents/scripts/lib/orchestration/review-providers/security-review.js +10 -2
  61. package/.agents/scripts/lib/orchestration/review-providers/types.js +2 -0
  62. package/.agents/scripts/lib/orchestration/review-providers/ultrareview.js +13 -2
  63. package/.agents/scripts/lib/orchestration/single-story-close/phases/confirm-merge.js +40 -15
  64. package/.agents/scripts/lib/orchestration/single-story-close/runner.js +2 -0
  65. package/.agents/scripts/lib/orchestration/story-deliver-terminal.js +8 -1
  66. package/.agents/scripts/lib/orchestration/story-handoff.js +222 -54
  67. package/.agents/scripts/lib/orchestration/story-stage-publish.js +147 -0
  68. package/.agents/scripts/lib/orchestration/ticketing/reads.js +2 -0
  69. package/.agents/scripts/lib/test-temp.js +5 -5
  70. package/.agents/scripts/lib/test-tiers.js +3 -3
  71. package/.agents/scripts/lib/util/glob-match.js +64 -0
  72. package/.agents/scripts/lib/wave-runner/footprint.js +3 -3
  73. package/.agents/scripts/run-tests.js +2 -1
  74. package/.agents/scripts/session-title.js +187 -0
  75. package/.agents/scripts/single-story-confirm-merge.js +7 -0
  76. package/.agents/scripts/single-story-init.js +6 -3
  77. package/.agents/workflows/helpers/audit-lens-core.md +4 -0
  78. package/.agents/workflows/helpers/code-review.md +8 -1
  79. package/.agents/workflows/helpers/deliver-digest.md +22 -23
  80. package/.agents/workflows/helpers/deliver-light.md +4 -1
  81. package/.agents/workflows/helpers/deliver-reference.md +55 -24
  82. package/.agents/workflows/helpers/deliver-story-reference.md +10 -3
  83. package/.agents/workflows/helpers/deliver-story.md +27 -7
  84. package/.agents/workflows/helpers/qa-core.md +2 -0
  85. package/.agents/workflows/mandrel-deliver.md +14 -4
  86. package/.agents/workflows/mandrel-orchestrate.md +2 -0
  87. package/.agents/workflows/mandrel-plan.md +4 -0
  88. package/README.md +8 -0
  89. package/bin/mandrel.js +35 -13
  90. package/docs/CHANGELOG.md +29 -0
  91. package/lib/cli/dispatch.js +27 -0
  92. package/lib/cli/ui/accounts.js +81 -0
  93. package/lib/cli/ui/board-model.js +372 -0
  94. package/lib/cli/ui/board.css +525 -0
  95. package/lib/cli/ui/board.html +80 -0
  96. package/lib/cli/ui/board.js +676 -0
  97. package/lib/cli/ui/log-tail.js +89 -0
  98. package/lib/cli/ui/panel-model.js +100 -0
  99. package/lib/cli/ui/preferences.js +136 -0
  100. package/lib/cli/ui/request-guard.js +108 -0
  101. package/lib/cli/ui/server.js +211 -0
  102. package/lib/cli/ui/sources.js +202 -0
  103. package/lib/cli/ui/story-detail.js +92 -0
  104. package/lib/cli/ui.js +114 -0
  105. package/package.json +2 -2
@@ -71,7 +71,9 @@ dispatchable and nothing in flight, with the undone Stories and their unmet
71
71
  blockers named; land a blocker or add it to `--ids`. **4** — `blocked`: a Story
72
72
  carries `agent::blocked` with `blockedReason`, the protocol's HITL pause
73
73
  ([`instructions.md` § 1.J](../../instructions.md)). Blocked outranks a wedge,
74
- but not a cycle.
74
+ but not a cycle. Only an operator-owned block lands here: a close that ends
75
+ `blocked.recovery: "agent"` leaves its Story `agent::closing` (in flight), and
76
+ you fix and resume it before the next close.
75
77
 
76
78
  **Resuming an exit-4 `blocked`.** Read the friction comment with
77
79
  `gh issue view <id> --comments`, and resume only once the operator has
@@ -419,8 +421,18 @@ then the shipped standalone ratchets CI's `baselines` job runs —
419
421
  and `check-cyclomatic.js` — in the worktree. It runs **before** the credited
420
422
  run because a fix commit afterwards would void that run's credit.
421
423
 
422
- - **One pass, every finding.** Every check runs, even after a finding. Any
423
- finding settles one `fix-required` whose `detail` lists each finding on its
424
+ - **The fast lane runs first.** Each `delivery.handoff.firstChecks` entry,
425
+ in config order, then close's independent baseline compare
426
+ (`check-baselines`, scoring committed rows, so under admitted lanes it waits
427
+ for the overlapped duplication re-score to join; the first checks run beside
428
+ that scan). A finding there settles `fix-required` naming the check and
429
+ quoting its failure rows, and none of typecheck, lint, format,
430
+ quality-preview, the ratchets or the held review starts; `--report-all`
431
+ lists it and runs the rest. A clean lane starts the held review, then the
432
+ checks below.
433
+ - **One pass, every finding.** After the fast lane, every check runs, even
434
+ after a finding. Any finding settles one `fix-required` whose `detail` lists
435
+ each finding on its
424
436
  own line, in check order, and whose `findings[]` carries `{ check, detail,
425
437
  evidencePath }` per failing check; the envelope's `evidencePath` is the
426
438
  first one's in check order. No suite runs before the credited run. Only a
@@ -635,13 +647,16 @@ review; post-seat checks wait for a real run, because it seats nothing.
635
647
  ## Held review at hand-off {#held-review}
636
648
 
637
649
  The one home of this rule; the digest and the worker contract point here.
638
- `story-handoff.js` starts the Story-scope code review once base-merge settles
639
- HEAD — pinned to the post-merge HEAD, before preflight's first check (and
640
- before a `test`-depositor seat, whose generated-only commit keeps the digest)
641
- — so it runs alongside preflight, and awaits it after the push, skipping the
642
- computation when a deposit already matches the diff digest. A precheck
643
- refusal or a base merge that does not settle (conflict, failed fetch, missing
644
- merge driver) starts no review. The envelope's `reviewMs` sits beside the run's
650
+ `story-handoff.js` starts the Story-scope code review once preflight's fast
651
+ lane passes — the `delivery.handoff.firstChecks` entries and close's
652
+ independent baseline compare — before its first credited check (and before a
653
+ `test`-depositor seat, whose generated-only commit keeps the digest), so it
654
+ runs alongside the rest of preflight, and awaits it after the push, skipping
655
+ the computation when a deposit already matches the diff digest. A fast-lane
656
+ finding starts no review: its fix changes the diff, so that review would be
657
+ thrown away. A precheck refusal, a base merge that does not settle (conflict,
658
+ failed fetch, missing merge driver) or any stop before preflight starts no
659
+ review either. The envelope's `reviewMs` sits beside the run's
645
660
  `suiteTimings`. The same computation stands alone for a manual re-run:
646
661
 
647
662
  ```bash
@@ -661,20 +676,36 @@ node <main-repo>/.agents/scripts/story-review-compute.js --story <storyId> --cwd
661
676
  raw diff. It never stops the handoff on a provider throw — the step reports
662
677
  `error` and close computes the review itself.
663
678
  - **A CRITICAL is the worker's to fix.** The handoff settles `fix-required`
664
- naming the deposit. It never cuts preflight short: every check runs to its
665
- own result. One that has landed before the credited run would begin stops
666
- the handoff there — no `test`-depositor seat, no run, no full-suite lock,
667
- no credit, no push. One that lands while the run is in flight aborts it
668
- (the SIGTERM a Ctrl-C sends; the child frees the full-suite lock), records
669
- no credit and pushes nothing; a CRITICAL after the run still settles after
670
- the push. Any earlier stop still awaits the review and appends its result
671
- to `steps[]` once, so no provider is orphaned and one envelope carries both
672
- findings, each with its own evidence path; `status` and `failedStep` stay
673
- the first stop's, and a review `error` never blocks. Fix, commit, and re-run the handoff
674
- (the fix commit voided the credit, so it re-runs the suite, pushes and
675
- re-computes) — the acceptance loop's redraft discipline, bounded by
676
- `delivery.acceptanceEval.maxRounds`. Still CRITICAL at the cap → take the
677
- blocked path. Anything else goes in the hand-off as the severity tally.
679
+ naming the deposit. On a first run it never cuts preflight short: every
680
+ check runs to its own result. One that has landed before the credited run
681
+ would begin stops the handoff there — no `test`-depositor seat, no run, no
682
+ full-suite lock, no credit, no push. One that lands while the run is in
683
+ flight aborts it (the SIGTERM a Ctrl-C sends; the child frees the
684
+ full-suite lock), records no credit and pushes nothing; a CRITICAL after the
685
+ run still settles after the push. Any earlier stop still awaits the review
686
+ and appends its result to `steps[]` once, so no provider is orphaned and one
687
+ envelope carries both findings, each with its own evidence path; `status`
688
+ and `failedStep` stay the first stop's unless the review blocks, and a
689
+ review `error` never blocks. Fix, commit, and re-run the handoff.
690
+ - **The fix is retried review-first.** When the previous run (its state file
691
+ holds `{ state, envelope }`) stopped on `review-critical` and its preflight
692
+ had passed at that run's head, the next run merges the base, then awaits
693
+ the held review before the duplication re-score, the static seat and
694
+ preflight. Still CRITICAL → it settles at once and lists every step it did
695
+ not run as `skipped` (`review-first retry: held review still CRITICAL`).
696
+ Clean → it continues as a normal handoff, and close adopts the deposit. Any
697
+ other prior stop, no state file, and `--report-all` run as before.
698
+ - **The round cap is script-enforced.** A *CRITICAL round* is a run in
699
+ `story-review-history-<id>.json` holding a CRITICAL that is not
700
+ `unverified`, not `ungrounded` and not overridden; an adopted deposit adds
701
+ no run. When the review settles CRITICAL, the envelope carries
702
+ `reviewRound: { round, cap }`, where `cap` is
703
+ `delivery.acceptanceEval.maxRounds` read by the acceptance gate's own rule
704
+ (below 1 counts as 1). At `round >= cap` the handoff settles `blocked`
705
+ (cause `review-cap`), flips `agent::blocked` and posts a `friction` comment
706
+ listing each open CRITICAL's title. The cap is checked only on a CRITICAL,
707
+ so once an operator clears the block a fix that reviews clean hands off.
708
+ Anything else goes in the hand-off as the severity tally.
678
709
  - **Close adopts, else computes — and deposits.** When the deposit's digest
679
710
  equals the digest of the diff at close's held-review start, close starts no
680
711
  review and posts the deposit after PR-open. A base-sync merge that moves
@@ -381,9 +381,16 @@ PR, and not when the CI digest recorded a red against that head.
381
381
 
382
382
  ## Step 4 — CI watch + fix recovery
383
383
 
384
- Enter this step **only** when Step 3 returned `blocked` with
385
- `blockClass: "checks-failed"` (a required check went red), or when a
386
- `--no-wait-merge` run left the PR for you to shepherd. When a required check is
384
+ Enter this step when Step 3 returned `blocked` with `blocked.recovery:
385
+ "agent"` — `checks-failed` (a required check went red), `queue-ejected`,
386
+ `checks-pending-timeout`, an advisory-gate red or `api-race-other` — or when
387
+ a `--no-wait-merge` run left the PR for you to shepherd. Those blocks leave
388
+ the Story at `agent::closing` (`merged-flip-failed` is also `agent`, but the
389
+ merge already landed: re-run its `nextCommand`). The fix is this session's,
390
+ in this turn ([`deliver-story.md` § Drive to merge](deliver-story.md#drive-to-merge)).
391
+ An `operator` class (`branch-protection-human-required`, `arm-failure`,
392
+ `predicate-refused`, `merge-queue-rest-unsupported`) carries `agent::blocked`
393
+ and waits for a human. When a required check is
387
394
  red, the agent owns the green-CI outcome, not just the push: CI runs on a
388
395
  different OS and concurrency, and coverage rounding, platform-conditional
389
396
  branches, and timing-sensitive tests routinely drift from the dev host.
@@ -137,12 +137,31 @@ child, and never end your turn while it is still running: "close is running"
137
137
  is not a return value. On a host that limits background commands (cloud,
138
138
  `-p`, Agent SDK, CI) a one-Story close still runs in the foreground but adds
139
139
  `--merge-watch-mode async`, so its merge wait moves into the background
140
- confirm (reference § Async merge-confirm mode). Branch on the envelope's `status` per **digest § 6**
141
- (`landed` → Step 7; `pending` → run `nextCommand`; `blocked`/`checks-failed`
142
- → Step 4; `failed` → diagnose, re-run; a `phase: base-sync` conflict comes
143
- back with labels untouched — resolve it in `workCwd`, commit, run
144
- `nextCommand`, and take the blocked path only if you cannot). Gate output is
145
- captured.
140
+ confirm (reference § Async merge-confirm mode). Gate output is captured.
141
+
142
+ ### Drive to merge {#drive-to-merge}
143
+
144
+ **Once the PR is open, the land is yours until it merges.** A red check, a
145
+ conflict or a slow CI run is the next step of the delivery, not where it
146
+ ends. Loop on the envelope's `status` (**digest § 6**) until `landed`:
147
+
148
+ 1. **`landed`** → Step 7.
149
+ 2. **`pending`** → run `nextCommand`. When it can outlive the host's
150
+ foreground ceiling, run it in the background and resume when it exits;
151
+ never end the turn on prose over an unconfirmed merge.
152
+ 3. **`failed`** → diagnose, fix, re-run close; a `phase: base-sync`
153
+ conflict comes back with labels untouched — resolve it in `workCwd`,
154
+ commit, run `nextCommand`, and take the blocked path only if you cannot.
155
+ 4. **`blocked`, `blocked.recovery: "agent"`** (the Story stays
156
+ `agent::closing`) → apply the friction comment's remedy in this turn:
157
+ read the CI digest, fix at source per
158
+ [`rules/ci-remediation.md`](../../rules/ci-remediation.md), commit, push,
159
+ re-watch, then run `nextCommand` (reference § Step 4).
160
+ 5. **Pause only** on `blocked.recovery: "operator"` (close already set
161
+ `agent::blocked`), a PR a human closed, a `capacity` /
162
+ `unreproducible-tier` verdict filed with `--block`, or the third failure
163
+ with the same fix shape ([`instructions.md` § 1.I](../../instructions.md)) — for the last two, flip
164
+ `agent::blocked` with `update-ticket-state.js` and say why.
146
165
 
147
166
  Internals, merge-wait budgets, the slow-CI **async** confirm mode, the
148
167
  `autoMerge` policy and every close flag: reference § Step 3.
@@ -158,7 +177,8 @@ shipped [schema](../../schemas/story-deliver-terminal.schema.json)).
158
177
  ## Steps 4–6 — Recovery (**recovery-only**) {#recover}
159
178
 
160
179
  A `landed` envelope means everything ran — go to Step 7. Enter recovery **only**
161
- when the envelope routes you there; procedures are reference §§ Step 4–6.
180
+ when [§ Drive to merge](#drive-to-merge) routes you there; procedures are
181
+ reference §§ Step 4–6.
162
182
  Two rules the spine keeps: a red **disarms auto-merge**,
163
183
  so only a green on a NEW head SHA re-arms it — a re-run is refused; fix at source
164
184
  and push ([`rules/ci-remediation.md`](../../rules/ci-remediation.md)). And a
@@ -56,6 +56,8 @@ resolves to an empty record), `consoleAllowlist` (default `[]`), and
56
56
 
57
57
  ## Session & ledger (temp/qa/)
58
58
 
59
+ Title the session `node .agents/scripts/session-title.js --event qa --summary "<surface>"` when it starts and `--event qa-done` with the same summary at the `/mandrel-plan` hand-off ([runbook](../../docs/runbooks/session-titles.md)).
60
+
59
61
  Resolve the session and its ledger path **once**, up front, via
60
62
  [`qa-session.js`](../../scripts/lib/qa/qa-session.js):
61
63
 
@@ -76,7 +76,8 @@ to an attended run.
76
76
  Stories first — **announce it**. It hard-errors (exit 1) on an id that is
77
77
  neither a Story nor an Epic, on an Epic with no open children, or on edges
78
78
  it cannot read — a missing gate would co-dispatch against an unlanded
79
- blocker.
79
+ blocker. Then title the session `node .agents/scripts/session-title.js --event deliver --ids <ids>` with the
80
+ ids as typed (the Epic id for an Epic), again on a resume ([runbook](../docs/runbooks/session-titles.md)).
80
81
 
81
82
  2. **Announce (N>1).** Present the resolved order and proceed — do not wait
82
83
  for confirmation; the operator can interject mid-run to change it.
@@ -115,14 +116,18 @@ to an attended run.
115
116
  - **2 / 3 / 4** — `cycleError` / `wedged` / `blocked`: stop the loop and
116
117
  route per reference. **4** is the protocol's HITL pause
117
118
  ([`instructions.md` § 1.J](../instructions.md)) — surface it and wait for
118
- the operator; never poll.
119
+ the operator; never poll. On exit 4, a `blocked` envelope or any HITL
120
+ pause, title the session `--event blocked --ids <blocked ids>`. A CI red the session can fix leaves its Story
121
+ at `agent::closing`, so it never reaches exit 4.
119
122
 
120
123
  4. **Land what the workers hand back** (§ Closing what the workers hand back —
121
124
  the beat renders each command), then, with every Story landed, run the
122
125
  **per-run epilogue (N>1)**:
123
126
  `node .agents/scripts/plan-run-epilogue.js --stories 101,102`; N=1 has none
124
127
  ([reference](helpers/deliver-reference.md)). Every close rolls its container
125
- Epic up from its children.
128
+ Epic up from its children. With every Story landed (an N=1 `landed`
129
+ envelope, an N>1 `done: true`), title the session `--event delivered` with
130
+ the step 1 ids.
126
131
 
127
132
  5. **Correct what the change invalidated.** If a memory you recalled this
128
133
  session is now wrong — a trap this landed, a budget it moved — fix that entry
@@ -151,7 +156,10 @@ resume what it names.
151
156
 
152
157
  **Reading the outcome.** Each close ends the Story in one schema-validated
153
158
  envelope — `landed` | `pending` | `blocked` | `failed`; statuses, exits and
154
- fields are digest § 6. `pending` is **not** a failure — run its `nextCommand`.
159
+ fields are digest § 6. Drive each close you run to merge before starting the
160
+ next — [`deliver-story.md` § Drive to merge](helpers/deliver-story.md#drive-to-merge):
161
+ run `pending`'s `nextCommand`, resolve a `base-sync` conflict, and fix, push
162
+ and resume a `blocked.recovery: "agent"` block yourself.
155
163
 
156
164
  **Branch model (authoritative).** `story-<id>` → PR → `main` (squash +
157
165
  required checks), per digest § 2; dependent Stories land sequentially. The
@@ -165,6 +173,8 @@ table is reference § Ceremony.
165
173
  - **Land or block — never a silent local build** (digest § 2). Attended delivers
166
174
  default to close-and-land (`delivery.routing.closeAndLand: true`); rest at
167
175
  `agent::closing` only when a human owns the merge.
176
+ - **A run ends at `landed` or an operator-owned block** — never at a red
177
+ check or a conflict this session can fix.
168
178
  - **`/mandrel-deliver` never plans.** Planned tickets come from
169
179
  [`/mandrel-plan`](mandrel-plan.md), and a refused prompt **escalates**: the
170
180
  light path ends, and the escalation's `nextCommand` is what owns the work —
@@ -43,6 +43,8 @@ annotation, which the inventory already carries.
43
43
 
44
44
  ## Start — record authority before the first sweep
45
45
 
46
+ Title the session `node .agents/scripts/session-title.js --event orchestrate` ([runbook](../docs/runbooks/session-titles.md)).
47
+
46
48
  1. Ask the operator which actions this run may take unattended, using the
47
49
  host's question idiom (`.agents/instructions.md` § 1.A), offering each
48
50
  action with its default:
@@ -51,6 +51,8 @@ node .agents/scripts/plan-context.js --seed "<seed>"
51
51
  # or: --seed-file <path> | --tickets 123,456 | --amends #<id>
52
52
  ```
53
53
 
54
+ **Title the session** ([runbook](../docs/runbooks/session-titles.md)): `node .agents/scripts/session-title.js --event plan-seed --summary "<3–6 words>"` in seed / seed-file mode, `--event plan-ticket --ids <ids>` in tickets / amends mode.
55
+
54
56
  It writes the envelope and **`stories.template.json`** (step 2's skeleton) to
55
57
  `<tempRoot>/plan-<slug>/` and prints a digest naming both; `--out` overrides
56
58
  the path. Persist auto-discovers the envelope from `--plan-dir` and derives
@@ -159,6 +161,8 @@ is the **terminal** flip after receipts land; stdout is pure JSON. Tickets mode
159
161
  rewrites a one-for-one source in place, else comments on and closes each
160
162
  source id ([ref](helpers/plan-reference.md)).
161
163
 
164
+ After a clean persist, title the session `node .agents/scripts/session-title.js --event planned --ids <ids>`: the Epic id when one was created or adopted, else the created Story ids ([runbook](../docs/runbooks/session-titles.md)).
165
+
162
166
  ## Constraints
163
167
 
164
168
  - `/mandrel-plan` never starts delivery — its Stories land via
package/README.md CHANGED
@@ -81,6 +81,14 @@ unplanned work: it authors a receipt Story on the fly and escalates to
81
81
  The full process — labels, state, review, troubleshooting — is in
82
82
  [`docs/SDLC.md`](docs/SDLC.md).
83
83
 
84
+ ### The dispatch board
85
+
86
+ `npx mandrel ui` serves a local board on `http://127.0.0.1:4319/` that shows
87
+ every Story's column and environment, and dispatches, resumes or stops a
88
+ delivery when you drag a card (the same actions as `mandrel dispatch`). It is
89
+ bound to your machine and guarded by a per-run token; see the
90
+ [dispatch board runbook](.agents/docs/runbooks/dispatch-board.md).
91
+
84
92
  ## Audits
85
93
 
86
94
  The `/audit-*` workflows are read-only lenses that examine the codebase along
package/bin/mandrel.js CHANGED
@@ -13,7 +13,7 @@ import { fileURLToPath, pathToFileURL } from 'node:url';
13
13
  const __dirname = path.dirname(fileURLToPath(import.meta.url));
14
14
 
15
15
  /**
16
- * @typedef {{ description: string, knownFlags: Set<string> }} SubcommandMeta
16
+ * @typedef {{ description: string, knownFlags: string[] }} SubcommandMeta
17
17
  * @type {Map<string, SubcommandMeta>}
18
18
  */
19
19
  const SUBCOMMANDS = new Map([
@@ -21,7 +21,7 @@ const SUBCOMMANDS = new Map([
21
21
  'init',
22
22
  {
23
23
  description: 'install and configure mandrel in the current project',
24
- knownFlags: new Set([
24
+ knownFlags: [
25
25
  '--assume-yes',
26
26
  '--skip-github',
27
27
  '--owner',
@@ -30,14 +30,14 @@ const SUBCOMMANDS = new Map([
30
30
  '--project-number',
31
31
  '--operator-handle',
32
32
  '--dry-run',
33
- ]),
33
+ ],
34
34
  },
35
35
  ],
36
36
  [
37
37
  'sync',
38
38
  {
39
39
  description: 'materialize .agents/ payload from installed package',
40
- knownFlags: new Set(['--dry-run']),
40
+ knownFlags: ['--dry-run'],
41
41
  },
42
42
  ],
43
43
  [
@@ -47,7 +47,7 @@ const SUBCOMMANDS = new Map([
47
47
  // No --dry-run: the projection scripts have no preview mode, and
48
48
  // accepting the flag while syncing for real overwrote .claude/ on an
49
49
  // operator who asked for a preview. Reject it at the dispatcher.
50
- knownFlags: new Set([]),
50
+ knownFlags: [],
51
51
  },
52
52
  ],
53
53
  [
@@ -55,42 +55,64 @@ const SUBCOMMANDS = new Map([
55
55
  {
56
56
  description: 'regenerate .claude/agents/ from .agents/agents/',
57
57
  // Same contract as sync-commands: no preview mode, so no --dry-run.
58
- knownFlags: new Set([]),
58
+ knownFlags: [],
59
59
  },
60
60
  ],
61
61
  [
62
62
  'doctor',
63
63
  {
64
64
  description: 'run readiness checks and report remedies',
65
- knownFlags: new Set([]),
65
+ knownFlags: [],
66
66
  },
67
67
  ],
68
68
  [
69
69
  'update',
70
70
  {
71
71
  description: 'upgrade mandrel to the newest published version',
72
- knownFlags: new Set(['--dry-run', '--install-cmd']),
72
+ knownFlags: ['--dry-run', '--install-cmd'],
73
73
  },
74
74
  ],
75
75
  [
76
76
  'migrate',
77
77
  {
78
78
  description: 'apply version-keyed migrations for a version range',
79
- knownFlags: new Set(['--from', '--to', '--dry-run']),
79
+ knownFlags: ['--from', '--to', '--dry-run'],
80
80
  },
81
81
  ],
82
82
  [
83
83
  'explain',
84
84
  {
85
85
  description: 'print resolved config values and their sources',
86
- knownFlags: new Set(['--json']),
86
+ knownFlags: ['--json'],
87
+ },
88
+ ],
89
+ [
90
+ 'dispatch',
91
+ {
92
+ description: 'start, resume or stop a Story in a named environment',
93
+ knownFlags: [
94
+ '--env',
95
+ '--resume',
96
+ '--stop',
97
+ '--status',
98
+ '--json',
99
+ '--done-limit',
100
+ '--dry-run',
101
+ ],
102
+ },
103
+ ],
104
+ [
105
+ 'ui',
106
+ {
107
+ description: 'serve the local dispatch board on 127.0.0.1',
108
+ knownFlags: ['--port'],
87
109
  },
88
110
  ],
89
111
  [
90
112
  'uninstall',
91
113
  {
92
114
  description: 'reverse a recorded install using the install ledger',
93
- knownFlags: new Set(['--include-github', '--dry-run']),
115
+ knownFlags: ['--include-github', '--dry-run'],
94
116
  },
95
117
  ],
96
118
  ]);
@@ -165,7 +187,7 @@ const UNIVERSAL_FLAGS = new Set(['--help', '-h']);
165
187
  * Only flag names are checked (`--flag=value` is split).
166
188
  *
167
189
  * @param {string} subName
168
- * @param {Set<string>} knownFlags
190
+ * @param {string[]} knownFlags
169
191
  * @param {string[]} argv
170
192
  * @returns {string | null}
171
193
  */
@@ -174,7 +196,7 @@ function findUnknownFlag(subName, knownFlags, argv) {
174
196
  if (!arg.startsWith('-')) continue;
175
197
  const flagName = arg.includes('=') ? arg.slice(0, arg.indexOf('=')) : arg;
176
198
  if (UNIVERSAL_FLAGS.has(flagName)) continue;
177
- if (!knownFlags.has(flagName)) {
199
+ if (!knownFlags.includes(flagName)) {
178
200
  const names = [...knownFlags].sort().join(', ');
179
201
  const hint = names.length > 0 ? ` Known flags: ${names}\n` : '';
180
202
  return (
package/docs/CHANGELOG.md CHANGED
@@ -15,6 +15,35 @@ All notable changes to this project will be documented in this file.
15
15
  -->
16
16
  <!-- markdownlint-disable-file MD004 MD012 MD037 -->
17
17
 
18
+ ## [2.125.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.124.0...mandrel-v2.125.0) (2026-11-19)
19
+
20
+
21
+ ### Added
22
+
23
+ * add `mandrel ui`: a local board that shows every Story and dispatches by drag ([#6111](https://github.com/dsj1984/mandrel/issues/6111)) ([#6118](https://github.com/dsj1984/mandrel/issues/6118)) ([94cfb12](https://github.com/dsj1984/mandrel/commit/94cfb12f2ddf88f38fe63462532c9607788241d7))
24
+ * dispatch a Story to a named environment with `mandrel dispatch` (local launch) ([#6108](https://github.com/dsj1984/mandrel/issues/6108)) ([#6116](https://github.com/dsj1984/mandrel/issues/6116)) ([90f0576](https://github.com/dsj1984/mandrel/commit/90f05766e57a6371ae1aec6a06d86a3e6af9805c))
25
+ * dispatch a Story to an Anthropic cloud environment by firing a Claude routine ([#6110](https://github.com/dsj1984/mandrel/issues/6110)) ([#6117](https://github.com/dsj1984/mandrel/issues/6117)) ([d3d286c](https://github.com/dsj1984/mandrel/commit/d3d286cf24f253cd96645858b8d131820d4d37f3))
26
+ * dispatch board Settings: a gear icon opens per-browser board preferences, including how many Done Stories to show ([#6123](https://github.com/dsj1984/mandrel/issues/6123)) ([#6126](https://github.com/dsj1984/mandrel/issues/6126)) ([6ea0360](https://github.com/dsj1984/mandrel/commit/6ea0360e64dc9407e4929d1f8046be713e0c2772))
27
+ * dispatch board shows which GitHub and Claude accounts it uses, and opens Environments and Connections in the side panel from header icons ([#6122](https://github.com/dsj1984/mandrel/issues/6122)) ([#6125](https://github.com/dsj1984/mandrel/issues/6125)) ([4aecdca](https://github.com/dsj1984/mandrel/commit/4aecdca2fcd01bbac2447e4acea3e21d1e6f4acb))
28
+ * publish a Story's delivery stage to GitHub so remote runs show their progress ([#6109](https://github.com/dsj1984/mandrel/issues/6109)) ([#6114](https://github.com/dsj1984/mandrel/issues/6114)) ([430c8ec](https://github.com/dsj1984/mandrel/commit/430c8eca1e989cd01cc30ad02d785a80ee57b1c3))
29
+ * show on each dispatch-board card whether its delivery is alive and where it stands, with a detail popout per Story ([#6121](https://github.com/dsj1984/mandrel/issues/6121)) ([#6124](https://github.com/dsj1984/mandrel/issues/6124)) ([8c6e2dd](https://github.com/dsj1984/mandrel/commit/8c6e2dd1150b50985841bbd0119307330ddf0b74))
30
+ * title the host session with a state glyph as plan, deliver, orchestrate, audit and QA runs progress ([#6119](https://github.com/dsj1984/mandrel/issues/6119)) ([#6120](https://github.com/dsj1984/mandrel/issues/6120)) ([a0ebec9](https://github.com/dsj1984/mandrel/commit/a0ebec92ebb9364a26f98446633f2e6e603ad191))
31
+
32
+ ## [2.124.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.123.0...mandrel-v2.124.0) (2026-11-17)
33
+
34
+
35
+ ### Added
36
+
37
+ * a Story's first held review is an exhaustive deep pass that sweeps every instance of each defect class ([#6100](https://github.com/dsj1984/mandrel/issues/6100)) ([#6102](https://github.com/dsj1984/mandrel/issues/6102)) ([ba0b87f](https://github.com/dsj1984/mandrel/commit/ba0b87f20709a37152885826f04493ae7ddddf16))
38
+ * deliver drives the PR to merge: agent-recoverable CI reds and conflicts are fixed in-session, only operator-owned blocks pause ([#6091](https://github.com/dsj1984/mandrel/issues/6091)) ([#6092](https://github.com/dsj1984/mandrel/issues/6092)) ([07caf64](https://github.com/dsj1984/mandrel/commit/07caf6459d1ffd8e266b530529f0f28670837226))
39
+ * story-handoff bounds the held-review loop, retries a review-critical fix review-first, and fails fast on cheap blocking gates ([#6099](https://github.com/dsj1984/mandrel/issues/6099)) ([#6103](https://github.com/dsj1984/mandrel/issues/6103)) ([9a4db8a](https://github.com/dsj1984/mandrel/commit/9a4db8aca84b54c1b4b518e8a8f4a6c911a1c580))
40
+
41
+
42
+ ### Fixed
43
+
44
+ * **deps:** replace picomatch with minimatch behind one glob seam ([#6093](https://github.com/dsj1984/mandrel/issues/6093)) ([2db3b96](https://github.com/dsj1984/mandrel/commit/2db3b969e15f7b749f0bac1502c590a8ccdbf035))
45
+ * **test:** give suite-admission AC-6's first backfiller its own window (refs [#6105](https://github.com/dsj1984/mandrel/issues/6105)) ([#6106](https://github.com/dsj1984/mandrel/issues/6106)) ([896851e](https://github.com/dsj1984/mandrel/commit/896851e220733a242ad32773e37b52005cbfd2f9))
46
+
18
47
  ## [2.123.0](https://github.com/dsj1984/mandrel/compare/mandrel-v2.122.0...mandrel-v2.123.0) (2026-11-17)
19
48
 
20
49
 
@@ -0,0 +1,27 @@
1
+ // lib/cli/dispatch.js
2
+ /**
3
+ * `mandrel dispatch` subcommand: the operator-facing face of
4
+ * `.agents/scripts/dispatch.js`. Both call `runDispatch`, so they share one
5
+ * envelope and one set of exit codes; this module only maps the code onto
6
+ * the process.
7
+ *
8
+ * Injectable seams (used by tests): `exit` replaces setting
9
+ * `process.exitCode`; every other key is passed to `runDispatch`.
10
+ */
11
+
12
+ import { runDispatch } from '../../.agents/scripts/dispatch.js';
13
+
14
+ /**
15
+ * @param {string[]} argv
16
+ * @param {{ exit?: (code: number) => void } & Parameters<typeof runDispatch>[1]} [deps]
17
+ * @returns {Promise<void>}
18
+ */
19
+ export default async function run(argv, deps = {}) {
20
+ const {
21
+ exit = (code) => {
22
+ process.exitCode = code;
23
+ },
24
+ ...rest
25
+ } = deps;
26
+ exit(await runDispatch(argv, rest));
27
+ }
@@ -0,0 +1,81 @@
1
+ // lib/cli/ui/accounts.js
2
+ /**
3
+ * Which GitHub login and Claude account the board and its local launches
4
+ * act as. Both probes run in parallel, the result is reused for `ttlMs`, and
5
+ * nothing here logs a value: account fields leave only in the response.
6
+ *
7
+ * @module cli/ui/accounts
8
+ */
9
+
10
+ import { runGh } from '../../../.agents/scripts/lib/gh-exec.js';
11
+
12
+ const TIMEOUT_MS = 10_000;
13
+ const LOGIN_RE = /^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})$/;
14
+ const ACCOUNT_FIELDS = ['email', 'orgName', 'subscriptionType', 'authMethod'];
15
+ const FIRST_PARTY = 'firstParty';
16
+
17
+ async function githubLogin(env, runner) {
18
+ const r = await runGh(
19
+ ['api', 'user', '--jq', '.login'],
20
+ { env, timeout: TIMEOUT_MS },
21
+ runner,
22
+ );
23
+ const login = !r.error && r.status === 0 ? (r.stdout ?? '').trim() : '';
24
+ return LOGIN_RE.test(login)
25
+ ? { login }
26
+ : { login: null, reason: 'login-unavailable' };
27
+ }
28
+
29
+ function parseJson(text) {
30
+ try {
31
+ return JSON.parse(text);
32
+ } catch {
33
+ return null;
34
+ }
35
+ }
36
+
37
+ /** The whitelisted account summary from `claude auth status --json`, or `null`. */
38
+ function accountOf(status) {
39
+ if (status?.loggedIn !== true) return null;
40
+ const account = {};
41
+ for (const field of ACCOUNT_FIELDS) {
42
+ if (typeof status[field] === 'string') account[field] = status[field];
43
+ }
44
+ const provider = status.apiProvider;
45
+ if (typeof provider === 'string' && provider !== FIRST_PARTY) {
46
+ account.apiProvider = provider;
47
+ }
48
+ return account;
49
+ }
50
+
51
+ async function claudeAccount(runner) {
52
+ const r = await runner('claude', ['auth', 'status', '--json'], {
53
+ shell: process.platform === 'win32',
54
+ timeout: TIMEOUT_MS,
55
+ });
56
+ return !r.error && r.status === 0 ? accountOf(parseJson(r.stdout)) : null;
57
+ }
58
+
59
+ /**
60
+ * @param {{ env: Record<string, string|undefined>, runner: Function,
61
+ * ttlMs?: number, now?: () => number }} deps
62
+ * @returns {() => Promise<{ github: { login: string|null, reason?: string },
63
+ * claude: object|null }>}
64
+ */
65
+ export function createAccountProbe({
66
+ env,
67
+ runner,
68
+ ttlMs = 60_000,
69
+ now = Date.now,
70
+ }) {
71
+ let cached = null;
72
+ return () => {
73
+ if (cached && now() - cached.at < ttlMs) return cached.promise;
74
+ const promise = Promise.all([
75
+ githubLogin(env, runner),
76
+ claudeAccount(runner),
77
+ ]).then(([github, claude]) => ({ github, claude }));
78
+ cached = { at: now(), promise };
79
+ return promise;
80
+ };
81
+ }