@detergent-software/conductor 1.0.0-dev.2 → 1.0.0-dev.20

package/README.md

@@ -1,23 +1,63 @@
 # Conductor
 
-`@detergent-software/conductor`: the local daemon that runs the work loop for every conducted project on this machine, and its `conduct` CLI. The design, decisions and build order are in the Linear document *Conductor: design note* (project *Conductor daemon*). This package has build step 1, the skeleton (ATK-308), step 2, the session manager (ATK-309), and step 3, the watchers and `conduct wait` (ATK-310).
+`@detergent-software/conductor`: the local daemon that runs the work loop for every conducted project on this machine, and its `conduct` CLI. The design, decisions and build order are in the Linear document *Conductor: design note* (project *Conductor daemon*). This package has build step 1, the skeleton (ATK-308), step 2, the session manager (ATK-309), step 3, the watchers and `conduct wait` (ATK-310), the daemon's side of step 4, worker protocol v1's `conduct note` (ATK-311), step 5, the inbox with `conduct approve` / `revise` (ATK-312), step 6, the notifier (ATK-313), step 9, the conductor mod for Claude Code in `mod/` (ATK-265), step 8, the scheduler, settings and rules (ATK-315), the daemon's side of step 7, the console (ATK-314), step 12, the port broker (ATK-318), and step 13, the ADO Boards tracker (ATK-319).
 
 ## Commands
 
 ```text
 conduct serve                     run the daemon in this process (one per machine)
+conduct start                     start the daemon detached and wait until it answers (see Console)
 conduct stop                      stop the running daemon
-conduct status [--json]           the daemon's pid, port, projects and workers
+conduct status [--json]           the daemon's pid, port, projects, workers and held locks
 conduct project add <path>        register the project whose checkout holds .claude/conductor.json
 conduct project list [--json]     the registered projects
 conduct launch <item>             start a worker: worktree, background session, tab
     [--project <name>] [--probe] [--prompt <text>] [--conductor <name>]
 conduct retire <worker> [--force] stop a worker, remove its worktree and session
 conduct attach <worker>           wake a parked worker (no event text) and open it in a tab
+conduct inbox [--json]            what waits on you, with its commands and links (see Inbox)
+conduct approve <item> [--text <text>]
+                                  approve a plan: post "approve" on the item as you, wake its worker
+conduct revise <item> <text>      ask for another plan: post "revise: <text>", wake its worker
+conduct done <id>                 mark an inbox item done (a physical action, or one you handled)
+conduct notify [--json]           the notification profile, quiet hours, each channel's state
+conduct notify profile [<name>] [--until <when>]
+                                  switch where pushes go (see Notifications)
+conduct notify test [--kind <kind>] [--channel remote-control|pushover] [--raise]
+                                  push a sample item now, or raise a real one with --raise
+conduct queue [--json] [--fresh]  what the scheduler picks next and why the rest wait (see Scheduler)
+conduct pause [<project>] [--until <when>]
+                                  no new launches in a project, or in all of them, until a time
+conduct unpause [<project>]       launch again
+conduct focus <project> [--slots <n>] [--weight <n>] --until <when>
+                                  a project's slots or ordering weight, for a while (neither: it goes first)
+conduct why <event id | item> [--json]
+                                  the rule behind an action, and the events that led to it
+conduct console [--project <name>] [--here]
+                                  open the console in a Windows Terminal tab, or in this terminal (see Console)
+conduct escalations [--json]      what rules escalated to the console and it hasn't handled
+conduct escalations done <id> [--ask] <text>
+                                  the console's finding on an escalation; --ask puts it in the inbox
+conduct history [<range>] [--since <when>] [--until <when>] [--project <name>] [--json]
+                                  what a window of the log says: shipped, phases, waits, stalls, spend (see History)
+conduct retro [<range>] [--project <name>]
+                                  the same as a Markdown report
+conduct rules [--json]            the rules in force, what replaces what, any file refused (see Rules)
+conduct rules test <file> [--json]
+                                  dry-run the rules on a sample event; acts on nothing
+conduct note <item> <file>        post a phase note on the item and record its phase (see Notes)
+    [--worker <worker>]
 conduct wait <condition>          wait for an outside event (see Waits)
+conduct ports [<path>] [--prefer <slot>] [--json]
+                                  a checkout's dev ports from the port broker, or every worktree's (see Broker)
+conduct lock acquire|release|status <name> [--owner <id>] [--wait <minutes>]
+                                  a lock every project shares, such as chrome (see Broker)
+conduct events [--since <id>] [--follow]
+                                  the event log, one JSON event per line (see API)
 conduct install-startup           start the daemon at logon (Windows Task Scheduler)
 conduct install-startup --remove  remove that logon task
-conduct upgrade [--tag dev|latest]
+conduct install-mod [--remove]    install the conductor mod in Claude Code (see Mod)
+conduct upgrade [--tag dev|latest] [--allow-downgrade]
                                   stop the daemon, npm install the tag's newest version, start it again
 ```
 
@@ -34,12 +74,168 @@ The session manager owns the `claude --bg` sessions it launches, and only those:
 - **restarts:** a launch the daemon was stopped in adopts its session if one was started, and otherwise fails and removes its clean worktree.
 - **attach:** a parked worker is resumed with no event text, so it wakes idle and keeps running when its tab closes. An attached worker isn't parked until it registers a new wait, or until its turn has been over `sessions.idleMinutes` (`worker.detached`). The daemon can't see the tab, so this also delivers a wait that resolved while it was attached.
 - **park failures:** a session whose process outlives `claude stop` by 30 s logs one `worker.park-failed` per spell, and the park is tried again every 5 minutes.
-- **stalls:** a permission prompt open `sessions.permissionMinutes` (5), or idle `sessions.idleMinutes` (20) with no wait, logs one `worker.stalled` event per spell.
-- **spend:** tokens from the session's transcript and its subagents' (`~/.claude/projects/*/<session>.jsonl`), each message counted once, go into `spend` per worker and local day. It keeps input, output, cache read and cache write; `tokens` is their sum.
+- **stalls:** a permission prompt open `sessions.permissionMinutes` (5), or idle `sessions.idleMinutes` (20) with no wait, logs one `worker.stalled` event per spell, and `worker.stall-cleared` when that spell ends.
+- **spend:** tokens from the session's transcript and its subagents' (`~/.claude/projects/*/<session>.jsonl`), each message counted once, go into `spend` per worker and local day. It keeps input, output, cache read and cache write; `tokens` is their sum. A worker whose tokens in all, not counting cache reads, pass `inbox.runawayTokens` logs `worker.runaway` once per daemon run. Cache reads are left out because they are nearly all of a session's tokens (97% on ATK-312) at a tenth of the price.
 - **probes:** `--probe` names the worktree and session `probe-<item>` and gives it a prompt that works no issue, so tests stay out of the live fleet.
 
 Worker statuses: `launching`, `running`, `parked`, `stopped-unexpectedly`, `failed`, `exited`. Every step is an event (`worker.launched`, `worker.parked`, `worker.resumed`, …) on `GET /events`.
 
+## Notes
+
+A worker writes each phase note (`## <work skill> · <Phase>[ · <kind>: <one line>]`, such as `## work-issue · PR opened`) with `conduct note <item> <file>`. The daemon posts the file as a comment on the item in the tracker, then records the phase at once: on the worker (`phase` in `GET /fleet` and `conduct status`), on the item, and as a `note.posted` event. The worker is `--worker <worker>`, else the one whose worktree is the current checkout, else the project's live worker on that item. The project is the worker's, else the one whose tracker key (the Linear team, or the Boards `key`) is the item's key prefix.
+
+The work skill is the profile's `skills.work`. A note headed with one of `skills.aliases` counts the same, there and wherever the daemon reads notes (approvals, `conduct wait item … note`, the review-thread checks of `conduct wait pr … comment`). So when a project renames its work skill (ATK's `work-issue` became `work-item`), the old name goes in `aliases` and items in flight keep their phases.
+
+| Exit | Means | The worker then |
+|---|---|---|
+| 0 | posted | goes on |
+| 3 | nobody posted it: no daemon, one without notes, or the tracker refused it (such as a read-only key) | posts the note to the tracker itself, as before protocol v1 |
+| 1 | refused (no heading, no project) or unclear (the daemon or Linear didn't answer the write) | reads the message; when it says the note may be there, looks before posting again |
+
+On Linear the daemon uses the key the watchers read (below), so that key needs **Create comments** as well as Read. Comments it writes carry the key owner's name, as the Linear MCP's do. On ADO Boards it posts a markdown discussion comment as the `az login` identity.
+
+## Inbox
+
+The `inbox` table holds everything that waits on Jason, across projects. Each item records:
+
+- its kind;
+- the item and worker it is about;
+- one line of text;
+- the exact commands and links;
+- when it was raised.
+
+An item resolves itself when its condition is seen, and records what resolved it. `inbox.raised` and `inbox.resolved` events go on `GET /events`. The notifier pushes each new item to the phone (see Notifications).
+
+| Kind | Raised by | Resolved by |
+|---|---|---|
+| `plan` | a `Plan` note (`conduct note`), or an `approval` wait | the approval wait resolving (an `approve` or `revise:` comment), a `Plan approved` note, a newer Plan, or `conduct approve` / `revise` |
+| `merge` | a `Handoff · merge: <PR>` note; a `pr … merged` wait attaches to it | its PR wait resolving as merged, abandoned or closed, or a `Landed` note. A PR wait without the note raises nothing, because auto landing needs nobody |
+| `npm-otp` | a `Handoff · npm-otp` note (the `npm stage approve …` on its heading is the command), or an `npm` wait | the version on its tag, or a `Resumed` or `Landed` note |
+| `jason`, `human`, `scope`, `blocked`, `abandoned`, `failed` | a Handoff note of that kind | any later note on the item (such as `Resumed`), or `conduct done` |
+| `permission`, `stall` | `worker.stalled` | `worker.stall-cleared`, a park or resume, a new wait (stall only), or a daemon restart (it is raised again if it persists) |
+| `failed` | a failed launch, or a session that stopped unexpectedly | a new launch, the worker running again, or its retirement |
+| `runaway` | a worker passing `inbox.runawayTokens` (2M) input, output and cache-write tokens in all, once per worker | `conduct done`, or its retirement |
+| `ready-to-release`, `queue-drained` | the scheduler's default rules (see Scheduler) | `conduct done` |
+| `console` | the console's finding on an escalation, with `conduct escalations done <id> --ask` (see Console) | `conduct done` |
+
+Nothing raises `prod-approval` yet; `/release-atk` will. When a worker is retired, its open items resolve with it.
+
+For an item raised from a note:
+
+- The commands are the inline code on the note's heading and the lines of its shell-tagged fenced code blocks (`bash`, `sh`, `shell`, `powershell`, `pwsh`, `ps1`, `cmd`, `console`). An untagged block is output, not a command.
+- The links are the comment's URL and every URL in the note.
+
+`conduct approve ATK-312` (or the inbox id written `#12`; a bare number is refused, since it could mean an issue) posts `approve` on the item through the tracker, or `approve: <text>` with `--text`. It uses the same key as notes, so the comment carries Jason's name and counts as his answer. `conduct revise ATK-312 "<text>"` posts `revise: <text>`; every word after the item is the text, quoted or not. Either one then:
+
+1. resolves the plan item and the worker's open `approval` wait;
+2. has the session manager resume a parked worker with `[conductor] event: approval ATK-312: approve HH:MM`. The worker reads the comment on the tracker before it acts.
+
+If the tracker refuses the comment, nothing is resolved. Only a plan takes approve or revise; `conduct done <id>` resolves any item.
+
+## Notifications
+
+The notifier routes each new inbox item to the phone, on two channels:
+
+- **Remote Control:** the daemon appends `notify.requested` (`channel: "remote-control"`), and the conductor mod in the console pushes it with PushNotification. It reaches the phone only while the console is connected to Remote Control (see Mod). On Claude Code 2.1.296 these pushes are reported sent but never reach the phone (ATK-359), so the built-in `default` and `focus` also send to Pushover until a Claude Code release fixes it.
+- **Pushover:** sent from the daemon. The keys are `PUSHOVER_TOKEN` and `PUSHOVER_USER`, or else the Windows generic credential `atk-conductor-pushover` (`notify.pushover.credential`): its **user name is your Pushover user key** and its **password is the application's API token**. Save it with `cmdkey /generic:atk-conductor-pushover /user:<user key> /pass:<app token>` or in Credential Manager. A credential saved while the daemon runs is read on the next push. The keys are never logged or stored.
+
+**Profiles** pick the channels. A profile is a list of rules, and the first rule that matches an item says where it goes; when none matches, the item stays in the inbox, unpushed. Three are built in, and `notify.profiles` in `config.json` replaces one by name or adds more:
+
+```jsonc
+{
+  "quietHours": { "from": "22:00", "to": "07:00" },   // local; omit for none
+  "notify": {
+    "profile": "default",                            // the profile when none is switched to
+    "profiles": {
+      "default": [{ "to": ["remote-control", "pushover"] }],     // built in
+      "away": [{ "to": ["pushover"] }],                          // built in
+      "focus": [{ "kinds": ["npm-otp", "permission", "failed"], "to": ["remote-control", "pushover"] }],  // built in
+      "workday": [
+        { "projects": ["cadence"], "days": ["sat", "sun"], "to": [] },          // keep these off every channel
+        { "kinds": ["npm-otp"], "to": ["pushover", "remote-control"], "remind": { "afterMinutes": 10, "times": 5 } },
+        { "hours": "08:00-18:00", "to": ["remote-control"] }
+      ]
+    }
+  }
+}
+```
+
+A rule matches on `kinds` (inbox kinds), `projects`, `hours` (local, `HH:MM-HH:MM`, may run past midnight) and `days` (`sun` … `sat`, the day when the item is routed, so 01:00 on Saturday is `sat` even inside a Friday `22:00-02:00`); a rule with none of them matches everything. `conduct notify profile away` switches at once, without a restart, and the profile survives one. `--until 17:00` (the next 17:00), `--until 2026-10-12` (local midnight) or `--until 2026-10-12T09:00` hands back to the profile that was in force before. Switching to config.json's own `notify.profile` without `--until` hands the choice back to config.json. Each switch is a `notify.profile` event.
+
+- **Quiet hours** (`quietHours`): pushes are held (`notify.routed` with `outcome: "held"`). When they end, each channel gets one summary of the held items still open, such as `2 waiting since quiet hours: ATK-1 npm-otp, ATK-2 plan; 1 resolved meanwhile`, routed by the profile then in force. `conduct notify test` pushes at any hour.
+- **Dedupe:** the same project, item, kind and text pushed within `notify.dedupeMinutes` (30) to the channels it would go to now isn't pushed again; a newer note that replaces an item is the usual case. Its reminders carry on from the first push, on the newer item only. A copy that never reached the phone (held, or a failed push) gives way to the newer one.
+- **Reminders:** an open item is pushed again `notify.remind.afterMinutes` (30) after its last push, at most `notify.remind.times` (2) times, as `reminder 1/2: …`, on the channels the profile in force then gives it. A rule's own `remind` overrides that. A resolved item is never reminded. A first push that reached no channel (Pushover down, no credential) is tried again at the same interval without using up a reminder.
+- **Events:** `notify.routed` (the profile, the rule, the channels, `sent`, `held`, `deduped` or `none`), `notify.requested`, `notify.sent` and `notify.failed` (Pushover), `notify.channel` (a channel's state changed), `notify.profile`.
+
+`conduct notify` shows the profile, quiet hours and the last state of each channel: Pushover from its own answers, Remote Control from what the mod reports back from PushNotification after each push: `ok` (Claude Code reported it sent; see ATK-359 above for why that doesn't prove it reached the phone), `inactive` (Remote Control off, or mobile pushes off in Claude Code's config), `skipped` (not sent to the phone on purpose, such as while you are at the terminal: `user_present`) or `failing` (the call failed), each with its reason.
+
+## Rules
+
+Rules say what the conductor does when something happens (design note, section 9). Each is a `when` and a `do` in a fixed vocabulary, written in JSONC:
+
+```jsonc
+// ~/.conductor/rules.json
+[
+  { "when": "wait.kind == merge and wait.age > 2h", "do": "remind jason" },
+  { "when": "plan.tier == S and item.area in [docs, ops]", "do": "auto-approve after 15m" },
+  { "id": "runaway", "when": "spend.worker > 5M", "do": "inbox runaway" },   // replaces the default
+  { "id": "daily-cap", "do": "none" },                                        // switches a default off
+  { "when": "project == web and day == saturday", "do": "pause launches" }
+]
+```
+
+- **Sources, in order:** the item's project's `rules` (in its `.claude/conductor.json`, changed by PR), then `~/.conductor/rules.json`, then the built-in defaults: conduct-atk's behavior written as rules (`launch`, `retire-closed`, `park-on-wait`, `resume-on-wait`, `runaway`, `daily-cap`, `ready-to-release`, `queue-drained`, and `conductor-handoff`, which escalates a worker's `Handoff · conductor` note to the console). A rule with an `id` replaces the rule with the same id further down, so a file holds only the differences.
+- **when:** `and`, `or`, `not` and parentheses over comparisons (`==`, `!=`, `<`, `<=`, `>`, `>=`, `in [a, b]`, `<label> in item.labels`) and events. An event rule fires when one of its events happens: `note`, `plan`, `wait.resolved`, `run.failed`, `worker.idle`, `worker.exited`, `worker.permission`, `worker.waiting`, `inbox.raised`, `pr.comment`, `item.unblocked`, `item.closed`, `queue.pick`, `queue.drained`, `queue.ready-to-release`. A rule without one is a state rule, checked on each scheduler tick against each wait, inbox item, worker or project, or once for the machine, by the fields it reads. Fields: `project`, `item.id/area/labels/tier/priority`, `plan.tier`, `note.phase/kind`, `wait.kind/age`, `inbox.kind/age`, `worker.retries/phase`, `spend.worker/item/project/today`, `time`, `day`, `notify.profile`. Values carry units: `15m`, `2h`, `500k`, `2M`, `22:00`, `saturday`.
+- **do:** `launch`, `retire`, `park`, `resume worker`, `retry`, `pause launches [in <project>] [until <when> | for <duration>]`, `pause all launches …`, `unpause launches`, `focus [<project>] weight|slots <n> until <when>`, `auto-approve after <duration>`, `inbox <kind> ["<text>"]`, `remind jason`, `notify <channel> ["<text>"]`, `notify profile <name> [until <when>]`, `label add|remove human|triage|shipped-open`, `flag shipped-open`, `escalate console "<ask>"`, `none`. One string, or a list.
+- **Guardrails:** rules act inside Area locks, slots, quiet hours and config.json's limits. A rule that would go past one is refused when it loads: `focus … slots` over `scheduler.slots`, an override with no end or one over 14 days, `retire` on anything but `item.closed`, `launch` outside `queue.pick` / `item.unblocked`, `park` outside `worker.waiting`, `resume` outside `wait.resolved` / `pr.comment`, `retry` outside `run.failed`. `merge`, `publish`, `approve`, `delete` and `run` aren't in the vocabulary.
+- **Reload:** saving `rules.json` or a project's profile reloads its rules. A profile save takes only the `rules`; the rest of a profile changes with `conduct project add`. A file the conductor refuses leaves its last good rules in force, logs `rules.rejected` and raises a `failed` inbox item until it loads again (`rules.loaded`), including after a restart. `conduct project add` refuses a profile whose rules don't load, with or without the daemon.
+- **Checking:** `conduct rules` lists the rules in force (`project.atk:#2`, `machine:runaway`, `default:launch`) and what replaces what. `conduct rules test <file>` dry-runs a sample, such as `{ "event": "pr.comment", "project": "atk", "fields": { "wait.kind": "merge", "wait.age": "3h" } }` (leave out `event` for a state rule), and shows what fires, each action's guardrail, and why every other rule of the trigger didn't. Both read the files directly when the daemon isn't running.
+
+- **Why:** every action the conductor takes is an event that names its rule, directly (`rule`) or through the event that caused it (`data.cause`). `conduct why <event id>` follows that chain back and shows the rule as it fired; `conduct why ATK-315` does it for the item's newest actions.
+
+**How actions are carried out.** Every action is a `rule.fired` event that names its rule, then `rule.done` or `rule.failed`.
+
+- **The scheduler** does `launch` on `queue.pick` and `retire` on `item.closed` (see Scheduler).
+- **The session manager** asks the rules before each `park` and `resume`. A resume for a review comment is also a `pr.comment`.
+- **Event rules** run on the daemon's events.
+- **State rules** are checked each minute against every wait, inbox item, worker, project and the machine. Each fires once while it holds and again after it stops holding; a restart remembers which hold. A `pause launches` with no end, from a state rule, lifts when the rule stops holding (`rule.released`), and only the pause that rule set.
+
+What each action does:
+- `remind jason` pushes the subject's inbox item again: the wait's gate, or the worker's item.
+- `notify <channel>` pushes once. `notify profile` switches the profile.
+- `inbox <kind>` raises an item, once while it is open. `inbox runaway` is raised once per worker.
+- `pause` / `unpause` / `focus` set overrides that name the rule.
+- `label add|remove` edits one label on the item (the profile's human label for `human`), at most 20 times a day per item.
+- `escalate console` emits `console.escalated`, which wakes the console's model; the console reports back with `conduct escalations done` (see Console).
+- `retry` launches a failed launch again, or wakes a session that stopped unexpectedly with the fact. It does this once per item, whatever the rule says: a second failure stays in the inbox. `worker.retries` counts the earlier tries.
+- `auto-approve after N` pushes "auto-approves at HH:MM" where plans go. At the deadline, if the plan still waits (no `revise:`, no newer Plan), it posts `approve: auto-approved by the conductor: rule "<id>", no revise by HH:MM` as the key's owner, which the worker's approval wait reads. No default rule auto-approves. A Plan note's `**Size tier: S**` gives `plan.tier` (and `item.tier` later).
+- `launch` on `item.unblocked` brings the scheduler's next tick forward.
+- `launch` and `retry` start sessions, so they wait for `scheduler.mode` `on`, as the scheduler's own launches do. In `observe` they are logged, not done; every other action acts in any mode.
+
+The defaults `runaway` and `daily-cap` are the budget: a runaway inbox item past `inbox.runawayTokens` for one worker, and no new launches past `scheduler.dailyTokens` today until midnight. Both count tokens without cache reads.
+
+## Scheduler
+
+The scheduler moves conduct-atk's tick into the daemon (design note, section 8). Every `scheduler.tickSeconds` (120), and 10 s after a phase note, a retire, a failed launch or a cleared inbox item, it does three things.
+
+1. **Read.** It reads each conducted project's queue from its tracker: for Linear, the team's projects with a priority, the Area labels, every open item with its blockers, and the in-flight items. Each read is one request (plus pages), within the Linear watcher's rate budget. For ADO Boards, the profile's saved query (see ADO Boards), within the ADO watcher's budget.
+2. **Plan.** It works out the picks across projects, with the same order and reasons as conduct-atk's `planQueue`. A replay of conduct-atk's own Linear read is in the tests.
+   - **Order:** the tracker project's priority, then the conductor project's `weight` (profile, or `conduct focus --weight`), then the item's priority, then when it was created.
+   - **Areas:** one in-flight item per Area per project. An Area is held by every worker in flight and every started item, and by the Areas it covers or is covered by.
+   - **Not picked:** items labelled with the profile's human label, and items whose blockers are still open, which wait (pending, or "not being worked" when nothing will clear them).
+   - **Slots:** `scheduler.slots` (4) across projects and the profile's `slots` (2) per project, or `conduct focus --slots`, never more than the global ones. Slots count running workers only: a parked worker keeps its Area and frees its slot.
+   - **Holds:** quiet hours and `conduct pause` turn picks into waits that say why.
+3. **Act.** It runs the rules on what it found: `queue.pick` → `launch` (default `launch`), `item.closed` → `retire` (default `retire-closed`; a refused retire raises an inbox item once), `queue.drained` and `queue.ready-to-release` → an inbox item once a day. Each action is a `rule.fired` event, then `rule.done` or `rule.failed`. A launch that failed isn't tried again while its inbox item is open.
+
+`scheduler.mode` decides how far it goes:
+- **`on`** (the default): it acts.
+- **`observe`:** it reads, plans and logs each action once, and does none of them. Set it on a machine where conduct-atk's loop still launches.
+- **`off`:** it doesn't run; `conduct queue --fresh` still works out a plan on request.
+
+`conduct queue` shows the last plan (`--fresh` reads again): slots, holds, picks with their Area, and why each other item waits. A change of plan is a `scheduler.planned` event. A project whose read fails picks nothing that tick and logs `scheduler.read-failed` once, then `scheduler.read-recovered`. An item whose last open blocker closed is an `item.unblocked` event.
+
+**Overrides** end on their own: `conduct pause atk --until 17:00`, `conduct pause --until tomorrow` (every project), `conduct unpause atk`, `conduct focus atk --slots 3 --until monday`. `--until` takes `17:00` (the next one), `tomorrow`, a day, or a date and time. Each is an `override.set` event, which `conduct why` attributes to the command, and they show in `conduct rules`.
+
 ## Waits
 
 A worker waits by posting its note, running `conduct wait …` and ending the turn (worker protocol v1). The verbs take the repo, host and package from the worktree's `.claude/conductor.json`; the full form is accepted too, and is what the store keeps:
@@ -53,8 +249,8 @@ A worker waits by posting its note, running `conduct wait …` and ending the tu
 | `run atk-api-deploy 12345 done` | `run:ado:atk-api-deploy#12345:done` | the run completed, with its result |
 | `npm 8.5.0-dev.2 --tag dev` | `npm:@detergent-software/atk@8.5.0-dev.2:dev` | the dist-tag points at the version |
 | `health dev --version 1.2.3` / `--commit <sha>` | `health:dev:version=1.2.3` | the profile's `health.dev` URL answers with that version or commit |
-| `approval` | `approval:linear:ATK-310` | an `approve` / `revise:` comment by the Linear key's owner after the item's newest `<work skill> · Plan` note |
-| `item ATK-271 done` / `label human` / `note Landed` | `item:linear:ATK-271:state=done` | the state (name or type), a label, or a phase note |
+| `approval` | `approval:linear:ATK-310` (`approval:ado-boards:CAD-12` on Boards) | an `approve` / `revise:` comment by the Linear key's owner (on Boards, the `az login` identity) after the item's newest `<work skill> · Plan` note |
+| `item ATK-271 done` / `label human` / `note Landed` | `item:linear:ATK-271:state=done` | the state (name or type), a label (a tag on Boards), or a phase note |
 | `time 2026-10-10T09:00` | `time:2026-10-10T14:00:00.000Z` | the time has passed (no zone means local time) |
 
 - **With the daemon**, in a worker's worktree (or with `--worker <worker>`), `conduct wait` registers the wait and returns at once. The daemon parks the session when its turn ends and resumes it with `[conductor] event: <resolution> HH:MM` once the condition holds. The text is a fact, never an approval: the worker reads the source again. The daemon checks waits against the project's profile as registered (`conduct project add`), and refuses one it can't check, such as a `health` environment the profile has no URL for.
@@ -62,13 +258,94 @@ A worker waits by posting its note, running `conduct wait …` and ending the tu
 
 **Watchers.** One per API: Linear (GraphQL with `LINEAR_API_KEY` or the `atk-conductor-linear` credential, ported from conduct-atk), Azure DevOps (REST with the `az login` token), GitHub (`gh api`), npm (the registry's dist-tags, no cache) and `/health`. Time waits are the session manager's sweep. An API is asked nothing while no wait needs it. Otherwise it's asked once per `watchers.<api>.intervalSeconds`, within `perMinute` requests in any rolling minute shared by every project. Each pass covers all of that API's waits in as few requests as it can; Linear's is one request, filtered on `updatedAt` (with a 2-minute overlap) after the first. A pass that runs out of budget stops, and the next one starts a wait further on. A failing API waits twice as long each time (up to 10 minutes) and logs `watcher.failed` once, then `watcher.recovered`. A wait that can't be checked logs `wait.check-failed` once and stays open. Every `watchers.statsMinutes` (10) in which anything waited, a `watcher.stats` event records each API's passes, requests, budget skips, failures and waits.
 
+## ADO Boards
+
+A project whose work items live in Azure DevOps Boards (Cadence) sets `tracker.kind` to `ado-boards` (design note, section 12; ATK-319):
+
+```jsonc
+"tracker": {
+  "kind": "ado-boards",
+  "key": "CAD",                      // items are CAD-<work item id>: ADO's ids are numbers alone
+  "query": "Shared Queries/Conduct", // the saved query that is the queue, by path or id
+  "humanLabel": "human",             // a tag here
+  "priority": 3,                     // the queue's priority against other projects' (1 urgent … 4 low)
+  "areaRoot": "Emergent Software\\Cadence", // optional: an item's Area is its Area Path below it
+  "states": { "Blocked": "started" }        // optional, over the built-in state names
+  // "organization", "project": optional, the code host's by default
+}
+```
+
+| Tracker concept | On Boards |
+|---|---|
+| the queue | the saved query, a flat list, in its own order (by default the items tagged `conduct` that aren't Done or Removed, by Priority, then Backlog Priority; leaving closed items out keeps each read small). Its open items, and the in-flight ones, are one tracker project named after the query, with the profile's `priority`; within a priority the scheduler keeps the query's order. |
+| Area | the Area Path below `areaRoot` (`Web/Forms`); an item at the root holds none |
+| blockers | Predecessor links whose item is still open, inside the query or not |
+| human, labels | tags |
+| states | `New`, `Approved`, `To Do`, `Proposed` → unstarted; `Committed`, `Active`, `In Progress`, `Resolved` → started; `Done`, `Closed` → completed; `Removed` → canceled; `states` adds or overrides. A state neither names is never launched or retired. |
+| phase notes, `approve` / `revise:` | discussion comments: notes are posted as markdown; a comment typed in the web UI (HTML) is read as its text |
+
+Everything goes through the `az login` token. The reads (the scheduler's queue and the watchers' waits) take from the `ado` watcher's budget, as PR and pipeline waits do. A wait pass reads every waited item of a board in one batch, and an item's comments only when its rev or comment count moved. Notes and the rules' `label` edits (a patch of `System.Tags` alone, refused if the item changed since it was read) are writes, outside the budget, as on Linear.
+
+## Broker
+
+The broker shares what every project on the machine uses (ATK-318).
+
+**Ports.** Each profile declares its dev servers' base ports by name, such as ATK's `"ports": { "web": 3000, "api": 7071, "maxSlot": 50 }` or `{ "web": 3000 }`.
+- A main checkout serves on the base ports (slot 0).
+- Each worktree gets a slot from 1 to `maxSlot` (default 50) and serves on base + slot. `conduct ports <path>` gives it the first slot whose ports no other checkout of any registered project has and nothing listens on, `--prefer` first. It's the same answer each time after that.
+- A retired worker's worktree frees its slot, and so does a worktree whose directory is gone (at the next assignment).
+- Ports are compared, not slots, so projects with different bases stay apart too.
+- A project's dev scripts read the assignment with `--json`, as ATK's `scripts/dev-ports.mjs assign` does. They keep their own scheme when it exits 3: no daemon, an older one, or a checkout in no registered project.
+- The broker knows only the slots it gave out. A slot a script picked on its own while no daemon answered stays unknown until that worktree asks the broker; until then only the listening probe keeps the slot clear. So `--prefer` is the slot the script would pick itself (`dev-ports.mjs` passes the checkout's own slot or its own free-slot scan's). The preferred slot is taken without the listening probe, because the checkout's own servers may be what listens there.
+- A stored assignment follows its project's profile: when the base ports or `maxSlot` change, the worktree moves, its old slot first.
+
+**Locks.** `conduct lock acquire chrome` takes the lock every project's verify runs share. It answers the work-issue helper's JSON (`acquired`, `heldBy`, `since`, `refreshed`; `released` for a release; `verdict` for a status).
+- The owner is `--owner`, else the item of the worker whose worktree this is.
+- Acquiring again refreshes it. 30 minutes after its holder last acquired it, another owner may take it over.
+- `--wait <minutes>` asks again every 15 s until then.
+- Retiring a worker releases the locks its item holds (a probe's retire doesn't).
+- `conduct status` lists the locks held, each with its holder, its last acquire and whether it is stale.
+- Exit 3 when no daemon answers.
+
+Events: `ports.assigned`, `ports.freed`, `lock.acquired`, `lock.released`, `lock.taken-over`.
+
+## History
+
+`conduct history` and `conduct retro` read a window of the log and say what happened in it, so a review of a conducted run needs no transcripts. Both are queries over `conductor.db`, so they work without a daemon too (or with one older than this build).
+
+- **Window.**
+  - `<range>` is `today`, `yesterday`, a date (`2026-10-10`, that day), `A..B` (`2026-10-10..2026-10-11`, through B), or a span back from now (`24h`, the default; `7d`; `90m`).
+  - Instead of a range, `--since` and `--until` take a time each, such as `2026-10-11T09:00`, `yesterday` or `6h`.
+  - Times are local, and a window never reaches past now.
+- **What it measures:**
+  - **Shipped:** items with a Landed note in the window, with the time from their Started note.
+  - **Phases:** the time from each lifecycle note (Started, Done when or Repro, Plan, Plan approved, Verified, PR opened, Landed) to the item's next one, clipped to the window. Results are grouped by the tier on the item's newest Plan note (`?` without one). Handoff, Progress and Resumed notes fall inside a phase.
+  - **Plan latency:** from the newest Plan note to Plan approved, so a revision restarts the clock, plus the plans still waiting.
+  - **Waits:** the waits registered in the window, by what they held up: `plan`, `merge`, `checks`, `review`, `ci`, `npm-otp`, `time`, `item` and `health`.
+    - One PR event often resolves its merged, checks and comment waits together; they count once, under what happened.
+    - An open wait counts up to the window's end.
+    - Waits the manager closed itself (`worker retired`, `launch failed`) are counted apart.
+  - **Stalls and failures:**
+    - `worker.stalled` events, and Handoff notes by kind;
+    - failed launches, resumes and parks, workers stopped unexpectedly, refused or partial retires, failed rules and watchers;
+    - items launched more than once;
+    - unfinished items with their phase.
+  - **Inbox:** the items raised, by kind, with how long each took to resolve and how it was resolved: `conduct approve`/`revise`/`done`, a later note, the worker retired, or the condition seen.
+  - **Slots:** peak and average running workers, and running and parked hours by project and item.
+    - A slot is counted as the scheduler counts it, so a worker left attached and idle holds its slot the whole time.
+  - **Spend:** tokens by project and item. `spend` is kept per local day, so this covers the whole days the window touches.
+    - Tokens are input, output and cache writes; cache reads have their own column.
+  - **Rules:** how often each rule fired, and how its actions went.
+- `conduct retro` prints the same as Markdown. The console can post it on a Linear issue, or it can be pasted anywhere.
+
 ## Files
 
 Everything lives in `~/.conductor` (`CONDUCTOR_HOME` overrides it):
 
 | File | Holds |
 |---|---|
-| `config.json` | machine settings, JSONC (comments allowed), validated at startup; `sessions` holds `pollSeconds` (10), `settleSeconds` (5), `permissionMinutes` (5), `idleMinutes` (20); `watchers` holds `ado`, `github`, `health`, `linear` and `npm`, each `{ intervalSeconds, perMinute }` (30/60, 30/30, 30/30, 30/10, 20/30), and `statsMinutes` (10) |
+| `config.json` | machine settings, JSONC (comments allowed), validated at startup; `inbox.runawayTokens` (2000000, the `runaway` rule's number); `notify` and `quietHours` (see Notifications); `scheduler` holds `mode` (`on`, `observe` or `off`), `slots` (4, across projects, and the most any rule can give one project), `dailyTokens` (20000000, the `daily-cap` rule's number) and `tickSeconds` (120); `sessions` holds `pollSeconds` (10), `settleSeconds` (5), `permissionMinutes` (5), `idleMinutes` (20); `watchers` holds `ado`, `github`, `health`, `linear` and `npm`, each `{ intervalSeconds, perMinute }` (30/60, 30/30, 30/30, 30/10, 20/30), and `statsMinutes` (10) |
+| `rules.json` | machine rules, JSONC, reloaded on save (see Rules) |
 | `token` | the API token, readable by this user only; every request sends `Authorization: Bearer <token>` |
 | `conductor.pid`, `port` | the single-instance lock and where the API listens (`127.0.0.1`) |
 | `conductor.db` | SQLite state, including the append-only `events` log |
@@ -77,12 +354,33 @@ Everything lives in `~/.conductor` (`CONDUCTOR_HOME` overrides it):
 ## API
 
 - `GET /projects`: the registered projects. `POST /projects` with `{ "path": "<absolute path>" }` registers one.
-- `GET /events`: the event log as server-sent events. Add `?since=<id>` (or send `Last-Event-ID`) to replay from an id. Without either, the stream starts at the live end.
+- `GET /events`: the event log as server-sent events. Add `?since=<id>` (or send `Last-Event-ID`) to replay from an id. Without either, the stream starts at the live end. `conduct events` prints it one JSON event per line: the events after `--since` (all of them without it), or with `--follow` everything from there on (live without `--since`). `--follow` reconnects with `Last-Event-ID` when the daemon goes away, so a restart loses nothing, and prints the stream's state as lines without an id: `{"kind":"conduct.connected"}` and, once per outage, `{"kind":"conduct.disconnected","error":…}`.
 - `POST /shutdown`: a clean stop (`conduct stop`).
+- `GET /console/escalations`: the open escalations, oldest first (see Console).
+- `POST /console/escalations/:id` with `{ "text": "<finding>", "ask"?: true }`: the console's report on one; 201 with the escalation, the `console.handled` event's id and the inbox item `ask` raised. 404 when the id isn't an escalation, 409 when it is handled already or older than 14 days.
 - `GET /fleet`: the workers in flight, with session activity, waits and spend (today, total).
 - `POST /workers` with `{ "item": "ATK-309", "project"?, "probe"?, "prompt"?, "conductor"? }`: launch; answers 202 with the `launching` worker. `GET /workers/:id` shows it with its latest events.
 - `DELETE /workers/:id` (`?force=true`): retire; 409 with the unfinished work when it refuses.
 - `POST /workers/:id/attach`: wake if parked, mark attached, open the tab.
+- `POST /items/:id/notes` with `{ "body": "## work-issue · …", "worker"?: 1 }`: post a phase note (see Notes); 201 with the note and the worker. 409 when it won't post it; 502 when the tracker didn't take it, with `posted: "no"` or `"unknown"`.
+- `GET /inbox`: the open inbox items, oldest first.
+- `POST /inbox/:id/resolve`: Jason's answer (see Inbox). The body is `{ "action": "approve", "text"? }`, `{ "action": "revise", "text" }` or `{ "action": "done" }`.
+  - 200 with the item, the comment and the waits it resolved.
+  - 404 when there is no such item.
+  - 409 when the item is resolved already or isn't a plan.
+  - 502 with `posted` when the tracker didn't take the comment.
+- `GET /notify`: the profile (and until when), the profiles, quiet hours, the held count and each channel's state.
+- `POST /notify/profile` with `{ "name": "away", "until"?: "<ISO time>" }`: switch; 409 for a profile that doesn't exist.
+- `POST /notify/test` with `{ "kind"?: "npm-otp", "channel"?: "pushover", "raise"?: false }`: push a sample now and answer each channel's result, or with `raise` put a real item in the inbox (201).
+- `POST /notify/report` with `{ "channel": "remote-control", "result": "<PushNotification's answer>", "state"?: "ok" | "inactive" }`: the mod's report of a push.
+- `GET /rules`: the rules in force, each with its source, `ref`, `when`, `do` and the rules that replace it, plus any file refused and the live `overrides` (see Rules).
+- `GET /queue`: the scheduler's last plan; `?fresh=true` reads the trackers and plans now (see Scheduler).
+- `GET /overrides`, and `POST /overrides` with `{ "action": "pause", "project"?, "until"? }`, `{ "action": "unpause", "project"? }` or `{ "action": "focus", "project", "slots"?, "weight"?, "until" }` (and `by`, who set it): 201 with the overrides; 409 for an unknown project, a time past, or a focus over `scheduler.slots`.
+- `GET /history?since=<ISO time>&until=<ISO time>&project=<name>`: the report for that window (see History). Every parameter is optional; the default window is the 24 hours before `until` (default: now). 400 for a time it can't read, a window whose start isn't before its end, or an unknown parameter.
+- `GET /why/:id`: the event's chain of causes and the rule behind it; `GET /why?item=ATK-315` the same for the item's newest actions.
+- `POST /rules/test` with `{ "event"?: "pr.comment", "project"?: "atk", "fields"?: { … } }`: a dry run; 400 for a sample it can't read.
+- `GET /ports`: every worktree's port assignment. `POST /ports` with `{ "worktree": "<absolute path>", "prefer"?: 3 }`: the checkout's (see Broker); 200 with `assignment`, 409 when the path is in no registered project or no slot is free.
+- `GET /locks`: the locks held. `POST /locks/:name` with `{ "action": "acquire" | "release" | "status", "owner"? }`: 200 with the work-issue helper's lock JSON; 409 for an acquire or release without an owner.
 - `POST /waits` with `{ "worker": 1, "condition": "pr:ado:Emergent.AgenticToolkit#1850:merged" }`: a wait in its full form (see Waits), stored in its normal form; 201 with the wait. `GET /waits/:id` shows one, with its resolution once it has one.
 - A refusal (a duplicate launch, a bad condition, a busy worker) is a 409 with `error` and `details`.
 
@@ -96,7 +394,20 @@ conduct install-startup
 conduct project add <path to the project's main checkout>
 ```
 
-`conduct project add` walks up from the path it is given to the directory that holds `.claude/conductor.json`, and maps a worktree to its main checkout.
+`conduct project add` walks up from the path it is given to the directory that holds `.claude/conductor.json`, and maps a worktree to its main checkout. The daemon reloads a profile's `rules` when the file changes; every other change, such as a new `skills.work`, takes effect at the next `conduct project add`. An older daemon refuses a profile with fields it doesn't know, so upgrade the daemon before a profile that uses new ones lands. The same holds for the copy the daemon stored at `conduct project add`: after an `--allow-downgrade` to a version without those fields, the project shows `the stored profile no longer validates` and isn't conducted until a profile without them is added again.
+
+The profile's optional `work` section is for the project's work skill; the daemon only checks it:
+
+```jsonc
+"work": {
+  // Changes under these paths, and plans of these size tiers, land in review mode.
+  "landing": { "review": ["infra/", "pipelines/"], "reviewTiers": ["L"] },
+  // The pipelines that stage an npm package for a merge, by the key the work skill reports them under.
+  "releases": [{ "key": "cli", "pipeline": "pipelines/release-cli.yml", "package": "@detergent-software/atk" }],
+  // The project's own steps, which the work skill follows at its hook points.
+  "hooks": ".claude/work-hooks.md"
+}
+```
 
 The logon task runs `node` on the `cli.js` that ran `install-startup`. A global install keeps that path across upgrades, so the task needs registering once. To upgrade:
 
@@ -104,7 +415,7 @@ The logon task runs `node` on the `cli.js` that ran `install-startup`. A global
 conduct upgrade
 ```
 
-It takes the tag the installed version came from (`dev` for an `X.Y.Z-dev.N`, `latest` otherwise; `--tag` picks one), and does nothing when that tag's version is already installed. Otherwise it stops the daemon, runs `npm install --global @detergent-software/conductor@<tag>` and starts the daemon again: through the `Conductor` logon task when the task runs this `cli.js`, else as a detached `conduct serve`. A daemon that wasn't running stays stopped. If npm fails, the daemon still starts again on whatever npm left in place, and `upgrade` exits 1 with npm's output. A linked build (below) refuses: its `cli.js` isn't under npm's global `node_modules`.
+It takes the tag the installed version came from (`dev` for an `X.Y.Z-dev.N`, `latest` otherwise; `--tag` picks one), and does nothing when that tag's version is already installed. When the tag points at an older version (semver, so `1.2.0-dev.4` is older than `1.2.0`), it refuses before it stops anything and names that version; `--allow-downgrade` installs it anyway and reports `downgraded`. Otherwise it stops the daemon, runs `npm install --global @detergent-software/conductor@<the tag's version>` (the exact version it compared, in case the tag moves) and starts the daemon again: through the `Conductor` logon task when the task runs this `cli.js`, else as a detached `conduct serve`. A daemon that wasn't running stays stopped. If npm fails, the daemon still starts again on whatever npm left in place, and `upgrade` exits 1 with npm's output. A linked build (below) refuses: its `cli.js` isn't under npm's global `node_modules`.
 
 **From a checkout instead (development).** `npm link` puts the main checkout's build on PATH, so every worktree and the logon task run that build. Run it from the main checkout, and upgrade by pulling `develop`, building, then `conduct stop` and `conduct serve`:
 
@@ -117,6 +428,43 @@ conduct install-startup
 
 To switch from a linked build to the package: `conduct stop`, `npm rm --global @detergent-software/conductor` (removes the link), install the package as above, and run `conduct install-startup` again so the logon task points at the installed `cli.js`.
 
+## Console
+
+The console (design note, section 11) is the one Claude session that stays open beside the daemon. The conductor mod in it does the plumbing in code (see Mod). Its model wakes only for an escalation or for you, and runs the project's console skill (`/conductor-console`, installed by ATK). It has no loop: no Monitor, no heartbeat, no ticks. Everything it knows comes from the daemon, so a new console after a close loses nothing.
+
+```bash
+conduct console                   # a tab in Windows Terminal (window "conductor"), in the project's main checkout
+conduct console --here            # the same session in this terminal
+conduct console --project cadence # with several projects registered: whose checkout it runs in
+```
+
+It runs `claude -n conductor --permission-mode auto -- /conductor-console` with `CONDUCTOR_CONSOLE=1`. The skill starts the daemon if it isn't running (`conduct start`, detached, so it doesn't end with the session), then handles what waits.
+
+**Escalations.** A rule's `escalate console "<ask>"` appends `console.escalated` (the default `conductor-handoff` does it for a worker's `Handoff · conductor` note). The mod wakes the model with `[conductor] escalation #<id> on <item>: <ask>`. The console does the job and reports back with `conduct escalations done <id> "<what it found or did>"`, which logs `console.handled` with the escalation as its cause, so `conduct why <that event>` leads to the rule. With `--ask`, the finding also goes in the inbox as a `console` item, pushed like any other, for something only you can do. `conduct escalations` lists those not yet handled, from the last 14 days, including the ones raised while no console was open; the console reads it when it starts.
+
+**Moving from conduct-atk.** Stop the conduct-atk session, `conduct upgrade` (the scheduler now launches by default), `atk install` in the main checkout, then `conduct console`. A machine that keeps conduct-atk's loop sets `"scheduler": { "mode": "observe" }` in `config.json`.
+
+## Mod
+
+`mod/` is the conductor mod: a Claude Code plugin (a hooks module, code that costs no tokens) that does the console's plumbing. `conduct install-mod` installs it for this user from the package's own `mod/` folder, as a folder marketplace (`claude plugin install conductor --marketplace <package>/mod --scope user`). Claude Code reads a folder marketplace's plugin in place, so `conduct upgrade` replaces the mod along with the daemon; open sessions load the new version with `/reload-plugins`. `--remove` uninstalls it.
+
+- **Every session** shows a status line, `conductor 3▶ 2⏸ ✉2` (running, parked, inbox), from `GET /fleet` and `GET /inbox` every 30 s. It clears while no daemon answers.
+- **The console**, the session started with `CONDUCTOR_CONSOLE=1` (`conduct console` starts it; see Console), also gets:
+  - **the band** above the prompt while the inbox has items: one hotkey per item (a plan approves after a second press, `y`, since a digit typed into an empty prompt presses a band button; an npm OTP copies its `npm stage approve` line; the rest open the pane), and `o` for the pane;
+  - **the pane** (`/conductor`, `o`, or opened at the start, docked as a sidebar on a fullscreen terminal of 144 columns or more): the notification profile (a picker; buttons on mobile) and Remote Control's state, the inbox with each item's actions (approve, revise, copy a command, open a link, done), the workers by project (each project's rule has [pause] and [focus]; a row expands to attach and why), and today's spend;
+  - **commands answered in code**, never by the model: `/conductor`, `/inbox`, `/approve <item | #id>`, `/revise <item | #id> <text>`, `/attach <item | worker>`, `/notify [<profile> [--until <when>]]`, `/pause [<project>] [--until <when>]`, `/unpause [<project>]`, `/focus-project <project> [--until <when>]` (puts its items first, until midnight without `--until`; not `/focus`, which is Claude Code's own);
+  - **the stream**: it runs `node <package>/build/cli.js events --follow`, redraws on each event, toasts each new inbox item, and acts on three events:
+
+| Event | Data | The mod |
+|---|---|---|
+| `notify.requested` | `channel: "remote-control"`, `message` | pushes it to the phone (PushNotification), with no model turn, and reports every outcome to `POST /notify/report` (see Notifications). When the push comes back "Remote Control inactive" (PushNotification's `disabledReason` `no_transport`), mobile pushes are off in Claude Code's config (`config_off`), or the call fails, it toasts once, saying which; it says so again only after a push has reached the phone. A push Claude Code holds back while you are at the terminal (`user_present`) is reported as `skipped`, with no toast |
+| `console.escalated` | `text` | wakes the console's model once with `[conductor] escalation #<event id> on <item>: <text>`; nothing else wakes it |
+| `worker.message-requested` | `to`, `message` | sends the message to that worker's session |
+
+The notifier emits `notify.requested` (see Notifications), and the rules' `escalate console` action emits `console.escalated`. Nothing emits `worker.message-requested` yet.
+
+Its checks: `pnpm -C apps/conductor test` runs `mod/tests/model.spec.ts` (the logic, in CI). `claude plugin validate apps/conductor/mod` and `claude plugin test apps/conductor/mod` (the hooks against the engine, UI on the terminal, desktop, VS Code and mobile surfaces) need Claude Code, so they run locally. To try a change before installing it: `claude --plugin-dir apps/conductor/mod`.
+
 ## Releases
 
 `atk-conductor-release` (`pipelines/release-conductor.yml`) runs semantic-release on each push to `develop` or `main` that touches `apps/conductor/`. It counts only commits that touch this directory, writes `CHANGELOG.md`, tags `conductor-v<version>` (`X.Y.Z-dev.N` on `develop`), and stages the version on npm under `dev` or `latest`. A maintainer publishes it with the `npm stage approve <id> --otp=<code>` line from the run summary.
@@ -129,4 +477,6 @@ pnpm -C apps/conductor typecheck
 pnpm -C apps/conductor test
 pnpm -C apps/conductor build
 cd apps/conductor && node scripts/check-changelog.mjs
+claude plugin validate apps/conductor/mod
+claude plugin test apps/conductor/mod
 ```

package/build/broker-cli.js

@@ -0,0 +1,125 @@
+import { resolve } from 'node:path';
+import { z } from 'zod';
+import { lockVerdict } from "./broker.js";
+import { callApi, NotRunningError } from "./client.js";
+import { ConductorError } from "./errors.js";
+import { lockSchema, portAssignmentSchema } from "./store.js";
+import { daemonWorker, gitToplevel } from "./wait.js";
+// Exit code when no daemon brokered the request: none runs, an older one has no broker, or it
+// refused (a checkout in no registered project, no free slot). The caller keeps its own scheme,
+// as ATK's scripts/dev-ports.mjs and the work-issue helper's file lock do.
+export const NOT_BROKERED = 3;
+// How often `conduct lock acquire --wait` asks again, as the work-issue helper's lock does.
+const LOCK_POLL_MS = 15_000;
+const errorBody = z.object({ details: z.array(z.string()).optional(), error: z.string() });
+const lockAnswer = z.looseObject({ acquired: z.boolean().optional(), lock: z.string() });
+// The broker's locks for `conduct status`, or null from a daemon older than the broker.
+export async function heldLocks(paths, now = new Date()) {
+    const answer = await callApi(paths, { method: 'GET', path: '/locks' });
+    if (answer.status === 404)
+        return null;
+    if (answer.status !== 200) {
+        const refusal = errorBody.safeParse(answer.body).data;
+        throw new ConductorError(refusal?.error ?? `the API answered ${answer.status} for the locks`, refusal?.details ?? []);
+    }
+    return z
+        .object({ locks: z.array(lockSchema) })
+        .parse(answer.body)
+        .locks.map((lock) => ({ ...lock, verdict: lockVerdict(lock, null, now) === 'stale' ? 'stale' : 'held' }));
+}
+// `conduct lock <acquire|release|status> <name>`: the broker's named lock, such as chrome, which
+// verify skills of every project take turns with. Prints the work-issue helper's JSON. The owner
+// is --owner, else the item of the worker whose worktree this is.
+export async function lockCommand(paths, action, name, options, io) {
+    if (action !== 'acquire' && action !== 'release' && action !== 'status')
+        throw new ConductorError('usage: conduct lock <acquire|release|status> <name> [--owner <id>] [--wait <minutes>]');
+    if (!/^[\w-]+$/.test(name))
+        throw new ConductorError(`a lock name is letters, digits, _ and -, not "${name}"`);
+    let owner = options.owner?.trim() || null;
+    if (owner === null) {
+        const worker = await daemonWorker(paths, await gitToplevel(io.cwd), undefined);
+        if (worker === 'no-daemon')
+            return notBrokered(io, 'the conductor is not running');
+        if (worker === 'unreachable')
+            throw new ConductorError("the conductor didn't answer");
+        owner = worker?.item ?? null;
+        if (owner === null && action !== 'status')
+            throw new ConductorError('no worker of the conductor works in this checkout: pass --owner <id>');
+    }
+    const until = Date.now() + (options.waitMinutes ?? 0) * 60_000;
+    const sleep = io.sleep ?? ((ms) => new Promise((done) => setTimeout(done, ms)));
+    for (;;) {
+        const answer = await ask(paths, { body: { action, ...(owner === null ? {} : { owner }) }, method: 'POST', path: `/locks/${name}` });
+        if (!answer.ok)
+            return notBrokered(io, answer.why);
+        const body = lockAnswer.parse(answer.body);
+        if (action !== 'acquire' || body.acquired !== false || Date.now() >= until) {
+            io.out(JSON.stringify(body, null, 2));
+            return 0;
+        }
+        await sleep(LOCK_POLL_MS);
+    }
+}
+// One line per lock: name, holder, and its last acquire.
+export function lockLine(lock) {
+    return `  ${lock.name}  ${lock.holder} since ${new Date(lock.since).toLocaleString()}${lock.verdict === 'stale' ? '  (stale: free to take over)' : ''}`;
+}
+// `conduct ports [<path>]`: the checkout's dev ports from the broker, or every assignment.
+export async function portsCommand(paths, path, options, io) {
+    if (path === undefined) {
+        const answer = await ask(paths, { method: 'GET', path: '/ports' });
+        if (!answer.ok)
+            return notBrokered(io, answer.why);
+        const assignments = z.object({ assignments: z.array(portAssignmentSchema) }).parse(answer.body).assignments;
+        if (options.json)
+            io.out(JSON.stringify(assignments, null, 2));
+        else if (assignments.length === 0)
+            io.out('no worktree has ports from the conductor');
+        else
+            assignments.forEach((a) => io.out(portsLine(a)));
+        return 0;
+    }
+    const answer = await ask(paths, {
+        body: { worktree: resolve(io.cwd, path), ...(options.prefer === undefined ? {} : { prefer: options.prefer }) },
+        method: 'POST',
+        path: '/ports',
+    });
+    if (!answer.ok)
+        return notBrokered(io, answer.why);
+    const { assignment } = z.object({ assignment: portAssignmentSchema }).parse(answer.body);
+    io.out(options.json ? JSON.stringify(assignment, null, 2) : portsLine(assignment));
+    return 0;
+}
+// One line per checkout: project, slot, each port, then where.
+export function portsLine(a) {
+    const ports = Object.entries(a.ports)
+        .map(([name, port]) => `${name} ${port}`)
+        .join(' · ');
+    return `${a.project}  slot ${a.slot}  ${ports}  ${a.worktree}`;
+}
+// The body of a 200 answer, or why nothing was brokered.
+async function ask(paths, request) {
+    let answer;
+    try {
+        answer = await callApi(paths, request);
+    }
+    catch (error) {
+        if (error instanceof NotRunningError)
+            return { ok: false, why: 'the conductor is not running' };
+        throw error;
+    }
+    if (answer.status === 200)
+        return { body: answer.body, ok: true };
+    // A daemon from before the broker has no such route.
+    if (answer.status === 404)
+        return { ok: false, why: 'this conductor has no port broker (upgrade it)' };
+    const refusal = errorBody.safeParse(answer.body).data;
+    if (answer.status === 409 && refusal)
+        return { ok: false, why: [refusal.error, ...(refusal.details ?? [])].join('; ') };
+    throw new ConductorError(refusal?.error ?? `the API answered ${answer.status}`, refusal?.details ?? []);
+}
+function notBrokered(io, why) {
+    io.err(`not brokered: ${why}`);
+    return NOT_BROKERED;
+}
+//# sourceMappingURL=broker-cli.js.map