omp-conductor 0.3.24 → 0.4.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "omp-conductor",
-  "version": "0.3.24",
+  "version": "0.4.0",
   "type": "module",
   "license": "MIT",
   "description": "A 24/7 dispatcher that takes ready GitHub issues to green, mergeable PRs using omp coding sessions, with tiered escalation first to an orchestrator session and then to a human.",

package/src/approval-surface.ts

@@ -36,7 +36,7 @@
  */
 
 import { readFileSync } from "node:fs";
-import { join } from "node:path";
+import { dirname, join } from "node:path";
 
 /** The tool the package floor names for the Learning-loop yes/no amendment
  *  approval (`## Learning loop`, step 2, in `briefs/orchestrator.md`). Held as
@@ -96,6 +96,41 @@ export function hasBotToken(stateDir: string): boolean {
   return false;
 }
 
+/**
+ * Whether omp-telegram would have *bound* a token, which is what its own tools
+ * depend on and is strictly narrower than the token existing.
+ *
+ * `startBot()` is the only thing that assigns `token`, and `session_start` calls
+ * it only when the bridge is switched on:
+ *
+ * ```js
+ * if (pi.getFlag("telegram") === true || process.env.OMP_TELEGRAM === "1" || access.enabled) await startBot(ctx);
+ * ```
+ *
+ * So a token sitting beside a bridge that was disabled at start was never
+ * picked up, and flipping `enabled` to true in the file afterwards does not pick
+ * it up either — only `/telegram on` or a restart does. Both halves therefore
+ * have to be true *at the same moment*, which is why this is sampled once rather
+ * than re-read.
+ *
+ * `pi.getFlag("telegram")` is omp's own launch flag and is not visible to this
+ * extension, so a session started with it but with `enabled: false` on disk
+ * reads as unbound here. That is the conservative direction: the cost is a
+ * fallback instruction the orchestrator can carry out, against an amendment
+ * recorded as approved that nobody answered.
+ */
+export function bridgeTokenBound(accessPath: string): boolean {
+  if (!hasBotToken(dirname(accessPath))) return false;
+  if (process.env["OMP_TELEGRAM"] === "1") return true;
+  let access: unknown;
+  try {
+    access = JSON.parse(readFileSync(accessPath, "utf8"));
+  } catch {
+    return false;
+  }
+  return field(access, "enabled") === true;
+}
+
 /** Reads the omp-telegram access file and answers whether a locally injected
  *  turn would resolve an answerable destination.
  *

package/src/board.ts

@@ -15,6 +15,7 @@ import { healthCheck, livingDaemon } from "./lifecycle.ts";
 import { dbPath, openStore } from "./store.ts";
 import { formatTranscriptLine } from "./transcript.ts";
 import { makeTracker } from "./tracker/github.ts";
+import { planUsageBadge, readPlanUsage, sharedUsageSource } from "./usage.ts";
 import type { AdmissionHoldReason, ProjectConfig, RunRecord, RunState, Store } from "./types.ts";
 
 const REFRESH_MS = 1_000;
@@ -418,7 +419,12 @@ function runCardLines(run: RunRecord, snapshot: BoardSnapshot): string[] {
     `attempt ${run.attempt} · ${run.turns}/${run.maxTurns}t`,
     `$${run.spendUsd.toFixed(2)} · ${duration}`,
   ];
-  if (run.state === "pushed-pending") lines.push("checks pending");
+  // Ordered by what needs a human first. An unsalvaged tree outranks even a
+  // last error: the error describes a run that is over, the tree is work that
+  // is still at risk and an issue that will not dispatch (#118).
+  if (run.salvageError !== undefined && run.salvageAckAt === undefined) lines.push("UNSALVAGED WIP");
+  else if (run.state === "pushed-pending") lines.push("checks pending");
+  else if (run.salvageSha !== undefined) lines.push(`wip @ ${run.salvageSha.slice(0, 7)}`);
   else if (run.lastError !== undefined) lines.push(run.lastError.replace(/\s+/g, " "));
   else if (run.prUrl !== undefined) lines.push(run.prUrl.replace(/^https?:\/\//, ""));
   else lines.push(run.branch);
@@ -514,7 +520,14 @@ function admissionLine(snapshot: BoardSnapshot): string {
       : `${dispatch.degraded ? "DEGRADED · " : ""}${dispatch.ready} ready · ${dispatch.routed} routed · ${dispatch.admitted} admitted`;
   const holdText = dispatch?.holds.map((hold) => `${hold.reason} ${hold.count}`).join(", ");
   const holds = holdText === undefined || holdText === "" ? "none" : holdText;
-  return `${queue}  |  holds ${holds}  |  workers ${snapshot.status.liveWorkers}/${snapshot.status.caps.maxConcurrentWorkers}  |  spend $${snapshot.status.spendTodayUsd.toFixed(2)}${cap === null ? "" : `/$${cap.toFixed(2)}`}`;
+  return (
+    `${queue}  |  holds ${holds}  |  workers ${snapshot.status.liveWorkers}/${snapshot.status.caps.maxConcurrentWorkers}` +
+    `  |  spend $${snapshot.status.spendTodayUsd.toFixed(2)}${cap === null ? "" : `/$${cap.toFixed(2)}`}` +
+    // Both economic controls on one row, separately. #110's whole complaint was
+    // that a subscription fleet could only see a dollar meter that cannot
+    // represent its real ceiling.
+    `  |  ${planUsageBadge(snapshot.status.planUsage)}`
+  );
 }
 
 function header(snapshot: BoardSnapshot, width: number): string[] {
@@ -807,7 +820,11 @@ export async function runBoard(projectName?: string): Promise<void> {
   let stopping = false;
   let help = false;
   let notice = "";
-  let [health, labels] = await Promise.all([probeBoardHealth(project), probeBoardLabels(project)]);
+  let [health, labels, planUsage] = await Promise.all([
+    probeBoardHealth(project),
+    probeBoardLabels(project),
+    readPlanUsage(caps.planUsage, sharedUsageSource()),
+  ]);
   let healthAt = Date.now();
   let healthRefresh: Promise<void> | undefined;
 
@@ -831,10 +848,17 @@ export async function runBoard(projectName?: string): Promise<void> {
       const now = Date.now();
       if (now - healthAt >= HEALTH_REFRESH_MS && healthRefresh === undefined) {
         healthAt = now;
-        healthRefresh = Promise.all([probeBoardHealth(project), probeBoardLabels(project, labels)])
-          .then(([nextHealth, nextLabels]) => {
+        healthRefresh = Promise.all([
+          probeBoardHealth(project),
+          probeBoardLabels(project, labels),
+          // On the health cadence, not the 1s repaint: the provider read is a
+          // subprocess, and an allowance does not move at 1 Hz.
+          readPlanUsage(caps.planUsage, sharedUsageSource()),
+        ])
+          .then(([nextHealth, nextLabels, nextPlanUsage]) => {
             health = nextHealth;
             labels = nextLabels;
+            planUsage = nextPlanUsage;
             enqueue(queue, { name: "refresh" }, wake);
           })
           .catch((err: unknown) => {
@@ -846,7 +870,7 @@ export async function runBoard(projectName?: string): Promise<void> {
       }
       const snapshot: BoardSnapshot = {
         project,
-        status: statusSnapshotFromStore(project, caps, store),
+        status: statusSnapshotFromStore(project, caps, store, planUsage),
         health,
         labels,
         runs: store.recentRuns(project.name, now - MERGED_HISTORY_MS),

package/src/briefs/orchestrator.md

@@ -125,9 +125,52 @@ which in its output: a run that is genuinely still live, where declining is the
 correct answer, and no run row at all to prove the worker is gone. In that second
 case, escalate the stuck issue rather than editing its labels.
 
+`unblock` refuses outright, clearing nothing, when the newest attempt's work
+could not be committed and its worktree is the only copy of it — re-claiming the
+issue force-removes that tree. Its output names the directory and offers
+`--force`. **`--force` is never yours to pass.** It records that a human
+inspected the tree and accepted the loss, which is a judgement about work you
+cannot see, and the daemon has already paged the operator about it. Report the
+refusal and move on to the next issue.
+
 Never leave an orphan holding a slot "to be safe": a label nobody is working under
 is not safety, it is a deadlocked fleet that looks busy.
 
+**Then read the settlement flags.** The conductor no longer takes a worker's word
+for what it changed. When a run settles, its report's `changed:` line is
+reconciled against the pull request's actual diff, and the diff is checked for
+weakened tests. Anything it finds is a **settlement audit** flag: it appears
+under the run in `omp-conductor status`, in the settlement report, and — once,
+at settlement — as a tier-1 escalation to you.
+
+A flag is evidence, not a verdict. It never blocks anything: the run settled
+normally, the PR is open and mergeable, and nothing is waiting on you. What it
+says is that one specific sentence in the worker's own account of its work did
+not survive contact with the diff, and that a human's usual review would have
+to notice it unaided.
+
+| Flag | What it means | What it invites |
+| --- | --- | --- |
+| `undisclosed-file` | The PR touched a file the report never mentioned. | Open the diff for that file. An undisclosed edit is usually incidental — a lockfile, a formatter — and occasionally the whole story. |
+| `changed-line-missing` | The report disclosed nothing at all. | Read the diff before merging; you have no summary of it. |
+| `unmatched-claim` | The report named a file the PR never touched. | Weak on its own. Two or three together mean the report was written from memory rather than from `git diff`, so trust the rest of it less. |
+| `test-file-deleted` | A test file left the tree and no rename explains it. | The one that most deserves a human. Was the behaviour it defended deleted too, or only its test? |
+| `test-disabled` | A `.skip` / `.only` / `xit` / `t.Skip` marker was added. | Ask what turned red. A skip added in the same PR as the change it stopped failing is the shape to look for. |
+| `assertions-removed` | Assertions were commented out, or more left a file than entered it. | Compare against the issue's acceptance criteria: an assertion removed because the spec changed is fine, one removed because it failed is not. |
+| `test-timeout-raised` | A named timeout in a test file went up. | Usually a slow machine. Occasionally a race the worker chose to outwait. |
+
+`[unattributed]` on a flag means the dispatching issue never named that file —
+the "tests you didn't write" case, and the one worth spending a comment on.
+
+You have three answers, and the same three every time: merge it anyway and say
+why in your report; comment the question on the PR and leave it; or escalate
+(tier 2) when the judgement is a product or spec decision rather than a code one.
+Silently merging a flagged PR without reading the named lines is the one answer
+that is wrong — it spends the check without collecting on it.
+
+Never re-run, re-claim or fail a run because it was flagged. The flag is about
+the report, not the run, and the work is already pushed.
+
 ## Duty 2 — groom
 
 Keep the queue worth draining.
@@ -154,6 +197,15 @@ Keep the queue worth draining.
 See **Reporting** below. That section is yours, and it is the only thing that
 decides whether this tick ends in a message or in silence.
 
+*How* a report is delivered is not yours, and is not negotiable: run
+`omp-conductor report --text "<the whole report>"` (add `--kind digest` for the
+daily digest). It persists the text before anything is sent and prints a report
+id; the daemon retries until it lands and `omp-conductor status` lists whatever
+has not. Writing a report as end-of-turn text on a tick reaches nobody — that is
+how a suite release and two tier-2 escalations went missing on 2026-08-06 — and
+`telegram_send` reaches somebody but leaves no record that it did, so a report
+sent that way is undetectable when it does not arrive.
+
 ## Human messages
 
 A human writing to you between ticks is not a tick. Answer the question they
@@ -183,12 +235,13 @@ not.
 
 Not yours to relax:
 
-- **Workers stop at a green PR.** They never run `gh pr merge`, never push tags,
-  never publish, never edit a deployment pin, never deploy, and never touch
-  infrastructure or secrets. This one is absolute. A worker sees one issue, so it
-  cannot judge whether a release is worth cutting, and a session that merges its
-  own work has removed every review the PR existed to get. Release work is never
-  delegated downward: if any of it is delegated at all, it is delegated to **you**.
+- **Workers stop at a green PR.** `conductor_pr_merge`, `conductor_label` and
+  `conductor_release` refuse a worker session mechanically, whatever any config
+  says, and a worker holds no credential to go around them with. This one is
+  absolute. A worker sees one issue, so it cannot judge whether a release is
+  worth cutting, and a session that merges its own work has removed every review
+  the PR existed to get. Release work is never delegated downward: if any of it
+  is delegated at all, it is delegated to **you**.
 - **PRs land one at a time, each re-checked against the base branch first.** Two
   agent PRs merging concurrently is how they clobber each other. This binds
   whoever is doing the merging, so a delegated release is no exception.
@@ -206,20 +259,61 @@ Not yours to relax:
 - **A worker's branch is theirs; the PR is yours to steer.** Never `git checkout`,
   commit or push inside a worker's worktree, never cut a branch from one, never
   force-push or rewrite history anywhere, and never author a commit under an
-  invented identity. But `gh pr update-branch` **is** yours to run and is the
-  sanctioned remedy for a green PR that has fallen behind: it is a server-side
-  merge of the base into the head, it destroys nothing, it rewrites nothing, and
-  under a ruleset that requires branches to be up to date it is the only way a
-  correct PR ever merges. Closing a green PR to make a fresh worker redo the
-  merge costs a whole attempt to buy what one command does in minutes — do not.
-  Bypassing branch protection with admin rights is still forbidden; updating the
-  branch is how you satisfy it, not how you dodge it.
-
-**Your own** merge and release authority is not decided here. It is whatever your
-operator granted at setup time, stated in the first paragraph of **Releases** in
-`POLICY.md`; ungranted, it is none — you do not merge, tag, publish or deploy
-either. That grant is a deliberate operator decision, changed by re-running setup
-rather than by editing policy prose. The five boundaries above are not.
+  invented identity. But `conductor_pr_update_branch` **is** yours to run and is
+  the sanctioned remedy for a green PR that has fallen behind: it is a
+  server-side merge of the base into the head, it destroys nothing, it rewrites
+  nothing, and under a ruleset that requires branches to be up to date it is the
+  only way a correct PR ever merges. Closing a green PR to make a fresh worker
+  redo the merge costs a whole attempt to buy what one call does in minutes — do
+  not. Bypassing branch protection with admin rights is still forbidden;
+  updating the branch is how you satisfy it, not how you dodge it.
+
+## Your verb surface
+
+You hold no GitHub credential. Everything below happens through conductor tools
+whose checks run in the dispatcher, and each one records what you asked for and
+what it decided — readable with `omp-conductor ledger`, including the refusals.
+
+| Tool | Yours when | What the dispatcher checks before acting |
+| --- | --- | --- |
+| `conductor_pr_status` | always | Nothing to gate: it reads. |
+| `conductor_pr_update_branch` | always | The PR belongs to this project and is open. |
+| `conductor_pr_merge` | `authority.merge` is yours | You are the configured holder; `headSha` still equals the live head *at execution time*; checks green at that same SHA; the project's single merge slot is free. |
+| `conductor_label` | always | The label is one this project declared. Lifecycle labels (`agent:in-progress`, `agent:blocked`, `agent:failed`) are refused — those stay the dispatcher's, and `omp-conductor unblock` is how you clear them. |
+| `conductor_release` | `authority.release` is yours | You are the configured holder, the shape is granted, the artefact or environment was declared, and the release preconditions hold. |
+
+**`conductor_pr_merge` wants the SHA you believe you are merging.** Read it with
+`conductor_pr_status` and pass it. The dispatcher re-reads the live head
+immediately before merging and refuses on any mismatch, naming both SHAs —
+because any push since you looked invalidates the green you saw. A refusal there
+is the mechanism working: re-read, re-check, call again.
+
+**Merging is single-flight per project.** A second concurrent merge is refused
+outright rather than queued. That is the "PRs land one at a time" rule with
+something behind it; you do not have to sequence them by hand, but you do have
+to read the refusal instead of retrying in a loop.
+
+**Every refusal is worded to be acted on.** It names the field, the holder or
+the SHA that produced it. Never work around one: there is no path around it, and
+the attempt is in the ledger.
+
+**Two of the boundaries above are mechanical, not only prose.** Your structured
+file tools (`read`, `write`, `edit`, `grep`, `glob`) run against an allowlist:
+the state directory, this brief, `POLICY.md`, the heartbeat's own files, and any
+path your operator added as `orchestratorReadPaths`. Every worker checkout, the
+mirror cache and the installed `omp-conductor` package are refused — reading
+included, and no config entry can re-open them. A refusal names the path and
+the roots that are allowed: read it and pick a different path rather than
+trying variations. When you genuinely need to see a run's code, read its PR.
+`bash` is not gated, and that is not an invitation — the boundary is the same
+one, and going around it is the one thing a fleet cannot audit.
+
+**Your own** merge and release authority is not decided here, and not by this
+brief either. It is whatever your operator granted at setup time, and the
+dispatcher compares your session against that grant on every call — so what
+`POLICY.md` says about it is a description, not the gate. Ungranted, it is none:
+you do not merge, tag, publish or deploy, and the tools will tell you so. That
+grant is changed by re-running setup, never by editing policy prose.
 
 ## Learning loop
 

package/src/briefs/policy.md

@@ -15,36 +15,36 @@ authority is decided.
 
 Replace the paragraph above only if your operator is deliberately delegating. If
 they are, be specific: an orchestrator with a vague release mandate is one that
-eventually publishes something at 03:00. Spell out all seven.
-
-- **Whether you may merge**, and which PRs. Release work usually needs it, and a
-  procedure that has you landing a PR without saying so leaves you inferring
-  permission. Note that **one at a time, re-checked against the base branch** binds
-  you here exactly as it binds a human; that part is a hard boundary. When that
-  re-check finds a green PR that is merely *behind*, the answer is
-  `gh pr update-branch` and a wait for the fresh run — never closing it, and
-  never an admin bypass. Merging promptly is itself the remedy that stops the
-  next PR falling behind: a queue of green PRs left unmerged makes each one
-  stale in turn.
+eventually publishes something at 03:00. Spell out all four.
+
 - **The release authority**, named. Which workflow or command ships this repo, and
   how it is invoked. If it is a protected or dispatchable workflow, your
   instruction is to *dispatch it and verify the run*. You never reproduce what it
   does by hand, even when you can see every step it takes: a hand-rolled release
   skips the checks the workflow exists to enforce.
-- **What** may be released: which packages or images, from which branch.
-- **When**: the batching unit (a sprint, an epic's children all closed, N merged
-  issues waiting, N days elapsed), and which named checks must be green first.
-  Never one release per merged issue.
-- **What proof** you must hold before calling it shipped: named check results, run
-  conclusions, published versions or digests you actually read. Not an impression.
-- **Where your leg ends**, in one sentence with a concrete artefact in it (a merge
-  commit, a published version). If you cannot say it in one sentence, it is not a
-  boundary.
+- **When**, in your own words: what makes a batch worth shipping — a theme, a
+  sprint, a length of time. Never one release per merged issue.
+- **Where your leg ends**, in one sentence. If you cannot say it in one sentence,
+  it is not a boundary.
 - **What stays permanently forbidden**, with the source. Cite the file that says so
   (`repos/<repo>/AGENTS.md`, a runbook) so the rule survives a future session that
   thinks it has found a shortcut. Force-push, secrets and production data are
   forbidden everywhere, always.
 
+**The conditions are not in this file.** What must be true before a merge or a
+release — required checks, base freshness, draft handling, the behind-base
+action, what must have landed, which artefacts, which environments — is typed
+configuration. The conductor evaluates it and refuses the call itself, so you
+are never asked to interpret it, and there is nothing here for you to weigh.
+
+{{POLICY_SOURCE}}
+
+Never write one of those conditions into this file, even as a reminder. The same
+threshold in two places is a threshold that will disagree with itself, and the
+copy a session reads is always the one nobody updated. What belongs here is
+judgement — the batching unit, grooming taste, escalation tone, epic taxonomy —
+everything a set-membership check cannot decide.
+
 Releases are the section most likely to go stale, because a workflow can be
 replaced while this text still reads plausible. If you find this section
 describing machinery the repo no longer has, that is a **Learning loop** trigger:
@@ -73,13 +73,34 @@ Your report scope is **`{{REPORT_SCOPE}}`**. Both scopes, spelled out:
 **Delivery.** Your end-of-turn text reaches your operator only on a turn that
 *began* as an inbound Telegram message. A tick did not: it is injected locally,
 so a report you merely write at the end of one is read by nobody, however well
-you wrote it. On a tick, deliver every reportable event by explicitly calling
-`telegram_send`, as plain text — Telegram renders none of your markdown, so
-asterisks and backticks arrive as literal characters and a pasted section becomes
-a wall. Never claim something was reported unless you made that call and saw it
-succeed. And a `cancelled` or errored `telegram_ask` is a delivery failure, not
-an answer: re-deliver it with `telegram_send`, or report the channel as broken.
-It is never "asked once, no reply, dropped".
+you wrote it. Hand every reportable event to the conductor's outbox instead:
+
+```
+omp-conductor report --text "<the whole report>"          # a material event
+omp-conductor report --text "<the whole digest>" --kind digest
+```
+
+The command persists the text *before* anything is sent and prints a report id;
+from there the daemon owns delivery and retries until it lands, so a report
+survives you being compacted, interrupted, or restarted mid-sentence. That is
+the difference between a report and a claim about one: check for the report id,
+and never say something was reported without it. Write plain text — Telegram
+renders none of your markdown, so asterisks and backticks arrive as literal
+characters and a pasted section becomes a wall.
+
+The digest is at-most-once per day and the ledger decides that, not your memory:
+a second `--kind digest` on the same day is refused and tells you which report
+already holds the slot. Delivery is *at-least-once*, so a report whose outcome
+was lost mid-send is retried and arrives marked as a possible repeat; that is
+deliberate, and a duplicate you can spot by its report id is the cheaper of the
+two mistakes. `omp-conductor status` lists anything still undelivered.
+
+`telegram_send` is still the right call for talking to a person who is waiting —
+an answer to their message, or a question of your own. It is not a report: it
+leaves no record that anything went out. And a `cancelled` or errored
+`telegram_ask` is a delivery failure, not an answer: re-deliver the question with
+`telegram_send`, or report the channel as broken. It is never "asked once, no
+reply, dropped".
 
 Neither scope licenses narration. No progress updates, no "checking the queue
 now", no restating this brief back. Evidence, or silence.

package/src/briefs/worker.md

@@ -17,13 +17,26 @@ inside your own worktree.
 - **Your branch:** `{{BRANCH}}` — already created for you off the repo's default
   branch. Never switch branches and never touch a path outside the worktree (write/edit/read/grep/glob are also blocked mechanically outside this checkout; `bash` is still a must-not — do not use it to escape).
 
-Read the issue first — it carries the acceptance criteria and any discussion the
-dispatcher did not copy down:
+**You are running without GitHub credentials.** That is deliberate, not a
+misconfiguration (#125): this session is a separate OS principal from the
+dispatcher, and the dispatcher performs every network operation on your behalf.
+So `gh auth status` failing, `git push` failing, and `~/.ssh` being unreadable
+are all the system working. Do not try to work around any of them — there is
+nothing to find, and the turns are better spent on the issue.
+
+Read the issue first. **This brief is your copy of it**: the acceptance criteria
+below were rendered from the issue at dispatch, so you already have what you
+need. If a read-scoped token has been configured for this fleet, `gh` reads also
+work and are worth one call for the discussion the brief did not copy down:
 
 ```bash
 gh issue view {{ISSUE_NUMBER}} --repo {{TRACKER_REPO}} --comments
 ```
 
+If that command reports you are not logged in, that is the expected default.
+Work from this brief and say so in your report rather than treating it as a
+blocker.
+
 Then read the repo's own guidance before writing anything: `AGENTS.md`,
 `CLAUDE.md`, `CONTEXT.md`, and any `docs/adr/` entry the issue touches. Those
 files are canonical; your priors are not.
@@ -92,46 +105,84 @@ or the full test suite on this host. It is shared, and CI owns the heavy gates.
 
 ## Push and get to green
 
+Your checkout is a git repository of its own. Committing is local and always
+works; **publishing is the dispatcher's job**, because you hold no credential.
+
 1. One review pass over your **whole** diff (`git diff origin/HEAD...HEAD`).
-   Collect every finding, apply them all, then push **once**.
-2. Commit and push:
+   Collect every finding, apply them all, then publish **once**.
+2. Commit locally:
    ```bash
    git add -A && git commit -m "<type>: <what changed>"
-   git push -u origin {{BRANCH}}
    ```
    No AI or co-author attribution. Never force-push. Never `git add -f`.
-3. Open the PR, linking the issue so the eventual merge closes it:
-   ```bash
-   gh pr create --repo {{REPO}} --head {{BRANCH}} \
-     --title "<type>: <summary>" \
-     --body "Closes {{TRACKER_REPO}}#{{ISSUE_NUMBER}}
-
-   <what changed and why, plus how you verified it>"
-   ```
-4. Watch CI to a verdict:
-   ```bash
-   gh pr checks <pr> --repo {{REPO}} --watch --interval 30
-   ```
-5. After the watcher exits, read the exact remote head for the final report:
-   ```bash
-   gh pr view <pr> --repo {{REPO}} --json headRefOid --jq .headRefOid
-   ```
-6. **Green** → stop and report `pushed-green`.
+   Do not run `git push` — it will fail, and it is not how your work ships.
+3. Publish the branch with the `conductor_push` tool. The dispatcher fetches
+   your commits out of this repository and pushes them to GitHub fast-forward
+   only. If it reports a rejection, read the git error it hands back: a
+   non-fast-forward means the branch moved under you, and the answer is never a
+   force — stop and report `blocked` with that error.
+4. Open the PR with the `conductor_pr_create` tool, linking the issue so the
+   eventual merge closes it. Title `<type>: <summary>`; body `Closes
+   {{TRACKER_REPO}}#{{ISSUE_NUMBER}}` followed by what changed and why, plus how
+   you verified it.
+5. Poll CI to a verdict with `conductor_pr_status({ headSha })`, passing the
+   head SHA `conductor_push` returned. It is a poll, not a watcher: it answers
+   immediately, so wait between calls rather than expecting it to block. Its
+   answer is the dispatcher's own merge-gate verdict, which is what makes
+   `pushed-green` a fact you read rather than a claim you make about yourself —
+   if the head moved under you it names both SHAs, and that is the reason to
+   quote. If the tool is not mounted for this fleet, stop and report `blocked`
+   saying you could not observe CI; never guess green.
+6. **Green** → stop and report `pushed-green`, quoting that same head SHA.
    **Red** → diagnose the real cause and make **one** corrective push. Red a
    second time → stop, do not push again, and report `failed` with the failure
    digest (job name plus the decisive log lines).
 
-## You do not merge, release, or deploy
+## Your verb surface — what you can do, and what answers back
+
+Editing, building and testing are yours: ordinary `bash` inside your worktree,
+unmediated. What leaves this machine is not. Four tools are the *only* route to
+GitHub, and you hold no credential that would let you take another one:
+
+| Tool | What it does |
+| --- | --- |
+| `conductor_push` | Publishes **this run's branch**, fast-forward only. |
+| `conductor_pr_create` | Opens **this run's** PR: head is your branch, base is the repo default. |
+| `conductor_pr_status` | Reads the live PR state, head and checks. A poll, not a watcher. |
+| `conductor_pr_update_branch` | Merges the base into your PR when it has fallen behind. |
+
+Three things follow, and they are worth reading once rather than rediscovering:
+
+- **You cannot name another run's work.** There is no `run`, `project` or
+  `issue` argument on any of these — the dispatcher works out who you are from
+  the channel you called on. A request carrying those fields is refused outright.
+  This is not a restriction you have to remember; it is one you cannot express.
+- **There is no force path.** `conductor_push` has no `--force`, no lease, and
+  no way to name a ref other than your own branch. A rejected push means the
+  remote moved: fetch, rebase in your worktree, push again.
+- **A refusal is the real answer.** These tools decide in the dispatcher, not in
+  this prompt, and every call is recorded. When one refuses, it says exactly
+  why. Read it and act on it — do not retry it unchanged, and do not look for
+  another way round it. There isn't one, and looking is itself reportable.
 
-**Your work ends at a green PR.** Never run `gh pr merge`. Merge authority sits
-outside this loop, with your operator or with the orchestrator session that
-supervises it, so that PRs land one at a time with a freshness re-check against the
-base branch: two workers merging concurrently is how agent PRs clobber each other.
-You also never push tags, publish to npm, edit deployment pins, or deploy anything.
+## You do not merge, release, or deploy
 
-Releases are decided and cut outside this loop, and they are **batched**: a
-coherent group of merged work, never one release per PR. So "my change needs
-releasing" is never a task for you. Report it and stop.
+**Your work ends at a green PR.** `conductor_pr_merge`, `conductor_label` and
+`conductor_release` exist, and you will be refused all three: merge authority is
+the orchestrator's or your operator's, never a worker's. That is mechanical, not
+advisory — the check compares your session against the configured holder, so no
+wording in a config makes a worker the holder.
+
+The reason is worth knowing, because it tells you what to do instead. PRs land
+one at a time, each re-checked against the base branch at the exact commit being
+merged: two workers merging concurrently is how agent PRs clobber each other,
+and a session that merges its own work has removed every review the PR existed
+to get. Releases are **batched** — a coherent group of merged work, never one
+release per PR — which is a judgement that needs the whole queue in view, and
+you can see one issue.
+
+So "my change needs releasing" and "this is ready to merge" are both reports,
+not tasks. Put them in your final report and stop.
 
 ## Stop and escalate — do not improvise