@bensandee/tooling 0.68.0 → 0.69.0

package/README.md

@@ -13,14 +13,14 @@ pnpm dlx @bensandee/tooling repo:sync
 
 ## Conventions
 
-The tool auto-detects project structure, CI platform, project type, and Docker packages from the filesystem. `.tooling.json` stores **overrides only** — omitted fields use detected defaults. Runtime commands (`docker:build`, `checks:run`, `release:changesets`) work without running `repo:sync` first.
+The tool auto-detects project structure, CI platform, project type, and Docker packages from the filesystem. `.tooling.json` stores **overrides only** -- omitted fields use detected defaults. Runtime commands (`docker:build`, `checks:run`, `release:changesets`) work without running `repo:sync` first.
 
 | Convention        | Detection                                             | Default                                  | Override via                         |
 | ----------------- | ----------------------------------------------------- | ---------------------------------------- | ------------------------------------ |
 | Project structure | `pnpm-workspace.yaml` present                         | `single`                                 | `structure` in `.tooling.json`       |
 | CI platform       | `.github/workflows/` or `.forgejo/workflows/` dir     | `none`                                   | `ci` in `.tooling.json`              |
 | Project type      | Dependencies in `package.json` (react, node, library) | `default`                                | `projectType` in `.tooling.json`     |
-| Docker packages   | `Dockerfile` or `docker/Dockerfile` in package dirs   | —                                        | `docker` map in `.tooling.json`      |
+| Docker packages   | `Dockerfile` or `docker/Dockerfile` in package dirs   | --                                       | `docker` map in `.tooling.json`      |
 | Formatter         | Existing prettier config detected                     | `oxfmt`                                  | `formatter` in `.tooling.json`       |
 | Release strategy  | Existing release config detected                      | monorepo: `changesets`, single: `simple` | `releaseStrategy` in `.tooling.json` |
 
@@ -56,24 +56,24 @@ The `--add` flag appends extra checks (must be defined in `package.json`):
 tooling checks:run --add e2e
 ```
 
-**Coverage is branch-aware by default.** With neither coverage flag, the `test` step runs via `pnpm run test:coverage` (producing `coverage/coverage-summary.json` for the `coverage:*` commands) **only on the repo's default branch** — PR and feature-branch runs skip the v8 instrumentation cost automatically. The current branch is read from `GITHUB_REF` / `GITHUB_REF_NAME` (set by GitHub _and_ Forgejo Actions), falling back to `git rev-parse --abbrev-ref HEAD` for local runs; tag and pull-request refs count as non-default. The default branch is `.tooling.json#defaultBranch` if set, otherwise detected via `git symbolic-ref refs/remotes/origin/HEAD`, otherwise `main`.
+**Coverage is branch-aware by default.** With neither coverage flag, the `test` step runs via `pnpm run test:coverage` (producing `coverage/coverage-summary.json` for the `coverage:*` commands) **only on the repo's default branch** -- PR and feature-branch runs skip the v8 instrumentation cost automatically. The current branch is read from `GITHUB_REF` / `GITHUB_REF_NAME` (set by GitHub _and_ Forgejo Actions), falling back to `git rev-parse --abbrev-ref HEAD` for local runs; tag and pull-request refs count as non-default. The default branch is `.tooling.json#defaultBranch` if set, otherwise detected via `git symbolic-ref refs/remotes/origin/HEAD`, otherwise `main`.
 
 Explicit flags always win, regardless of branch:
 
-- `--with-coverage` — force the `test` step to run with coverage.
-- `--no-coverage` — force it to run without coverage.
+- `--with-coverage` -- force the `test` step to run with coverage.
+- `--no-coverage` -- force it to run without coverage.
 
 If both are passed, `--no-coverage` wins.
 
-Because the decision is branch-aware, the generated CI workflow runs plain `pnpm ci:check` (no coverage flag) and lets `checks:run` decide — except when coverage is disabled in `.tooling.json`, where it passes `--no-coverage` to force it off everywhere.
+Because the decision is branch-aware, the generated CI workflow runs plain `pnpm ci:check` (no coverage flag) and lets `checks:run` decide -- except when coverage is disabled in `.tooling.json`, where it passes `--no-coverage` to force it off everywhere.
 
-**Extend the `check` script with `--add`, never a shell chain.** `repo:sync` generates `check` as a single rooted command (`bst checks:run`) and `ci:check` as `pnpm check --skip 'docker:*'`. When CI runs `pnpm ci:check`, pnpm appends the resolved `--skip 'docker:*'` (and any flags you add, e.g. `--no-coverage`) to the _end_ of the resolved script — so they reach `bst checks:run` only if that is the last command. Adding extra checks via an `&&` chain silently drops `--skip 'docker:*'` and any forwarded flag:
+**Extend the `check` script with `--add`, never a shell chain.** `repo:sync` generates `check` as a single rooted command (`bst checks:run`) and `ci:check` as `pnpm check --skip 'docker:*'`. When CI runs `pnpm ci:check`, pnpm appends the resolved `--skip 'docker:*'` (and any flags you add, e.g. `--no-coverage`) to the _end_ of the resolved script -- so they reach `bst checks:run` only if that is the last command. Adding extra checks via an `&&` chain silently drops `--skip 'docker:*'` and any forwarded flag:
 
 ```jsonc
-// ✓ forwarded flags reach bst checks:run
+// [ok] forwarded flags reach bst checks:run
 "check": "bst checks:run --add check:env-drift,check:custom"
 
-// ✗ --skip / --no-coverage land on check:custom instead
+// [x] --skip / --no-coverage land on check:custom instead
 "check": "bst checks:run && pnpm check:env-drift && pnpm check:custom"
 ```
 
@@ -99,29 +99,29 @@ Generated workflow files are regenerated on each `repo:sync` run. To preserve cu
 
 Custom blocks are anchored to the nearest preceding non-blank line. When `repo:sync` regenerates the workflow, it extracts custom blocks from the existing file, generates fresh content, then re-inserts each block after its anchor line. If the anchor line is no longer present (e.g. a step was renamed), the block is appended at the end of the file.
 
-To skip a workflow file entirely, add `# @bensandee/tooling:ignore` as the first line — `repo:sync` will leave the file untouched.
+To skip a workflow file entirely, add `# @bensandee/tooling:ignore` as the first line -- `repo:sync` will leave the file untouched.
 
 ### pnpm-workspace.yaml
 
-`repo:sync` manages `pnpm-workspace.yaml` with a narrow contract — mandated keys, a few seeded-on-creation keys, and everything else passed through verbatim.
+`repo:sync` manages `pnpm-workspace.yaml` with a narrow contract -- mandated keys, a few seeded-on-creation keys, and everything else passed through verbatim.
 
 **Mandated** (drift fails `repo:sync --check`):
 
 - `blockExoticSubdeps: true`
-- `minimumReleaseAge` — any non-negative number (`0` is valid)
+- `minimumReleaseAge` -- any non-negative number (`0` is valid)
 
 **Seeded on creation only** (free to change or remove afterward):
 
 - `minimumReleaseAgeExclude: ["@bensandee/*"]`
 - `packages: ["packages/*"]` (monorepos only)
 
-All other keys — `allowBuilds`, custom entries — are preserved verbatim through `repo:sync`. The generator emits the file for single-package repos too, not just monorepos.
+All other keys -- `allowBuilds`, custom entries -- are preserved verbatim through `repo:sync`. The generator emits the file for single-package repos too, not just monorepos.
 
 Opt out entirely with `"pnpmWorkspace": false` in `.tooling.json`; the generator then never inspects or writes the file.
 
 ### packageManager force-bump
 
-`repo:sync` rewrites `package.json#packageManager` when an existing value is `pnpm@<N>.x` with `N < 11`, setting it to the tooling's pinned pnpm version (currently `11.1.1`). This is delivered through `repo:sync` rather than Renovate because the mandated `pnpm-workspace.yaml` keys (`blockExoticSubdeps`) require pnpm 11+. Within-major bumps (`pnpm@11.x → 11.y`) remain Renovate's job; non-pnpm package managers (yarn, npm) are out of scope.
+`repo:sync` rewrites `package.json#packageManager` when an existing value is `pnpm@<N>.x` with `N < 11`, setting it to the tooling's pinned pnpm version (currently `11.1.1`). This is delivered through `repo:sync` rather than Renovate because the mandated `pnpm-workspace.yaml` keys (`blockExoticSubdeps`) require pnpm 11+. Within-major bumps (`pnpm@11.x -> 11.y`) remain Renovate's job; non-pnpm package managers (yarn, npm) are out of scope.
 
 ### Repository setup
 
@@ -141,7 +141,7 @@ Opt out entirely with `"pnpmWorkspace": false` in `.tooling.json`; the generator
 | `tooling release:trigger`        | Trigger a release workflow.                                                                                                                                                    |
 | `tooling workflow:dispatch`      | Dispatch a `workflow_dispatch` event for any workflow in any repo on the same git host. Flags: `--repo`, `--workflow` (required), `--ref`, `--input key=value` (repeatable).   |
 | `tooling forgejo:create-release` | Create a Forgejo release from a tag.                                                                                                                                           |
-| `tooling changesets:merge`       | Merge a changesets version PR.                                                                                                                                                 |
+| `tooling changesets:merge`       | Merge a changesets version PR. Gated on a live read of the PR; refuses an empty version PR.                                                                                    |
 | `tooling webhook:send <url>`     | POST a structured JSON release payload with HMAC-SHA256 auth. Flags: `--tag`, `--repository`, `--server-url`, `--actor`, `--prerelease`. Secret from `WEBHOOK_SECRET` env var. |
 
 #### `release:simple`
@@ -165,18 +165,18 @@ tooling release:simple --release-as major
 tooling release:simple --release-as 2.0.0
 
 # Create a prerelease
-tooling release:simple --release-as major --prerelease beta  # → 2.0.0-beta.0
+tooling release:simple --release-as major --prerelease beta  # -> 2.0.0-beta.0
 ```
 
 The generated release workflow exposes these as optional `workflow_dispatch` inputs (`bump` and `prerelease`), so bumps can also be controlled from the CI UI.
 
-**Authentication:** `release:simple` requires `RELEASE_TOKEN` (a Personal Access Token with write access on the target forge) on every platform — Forgejo, GitHub, and GitHub Enterprise alike. The runner's auto-injected token (`github.token` / Forgejo Actions' internal auth) is never used: `actions/checkout@v6` writes that token to git config as an `http.<serverUrl>/.extraheader`, which silently overrides URL-embedded credentials and authenticates pushes as the runner pseudo-user. On Forgejo that pseudo-user is `uid=-2`, which fails the pre-receive hook (`Internal Server Error`); on GitHub Enterprise the same shape can mask custom hook rejections. `release:simple` actively unsets the extraheader and rewrites the remote URL with `RELEASE_TOKEN` before pushing.
+**Authentication:** `release:simple` requires `RELEASE_TOKEN` (a Personal Access Token with write access on the target forge) on every platform -- Forgejo, GitHub, and GitHub Enterprise alike. The runner's auto-injected token (`github.token` / Forgejo Actions' internal auth) is never used: `actions/checkout@v6` writes that token to git config as an `http.<serverUrl>/.extraheader`, which silently overrides URL-embedded credentials and authenticates pushes as the runner pseudo-user. On Forgejo that pseudo-user is `uid=-2`, which fails the pre-receive hook (`Internal Server Error`); on GitHub Enterprise the same shape can mask custom hook rejections. `release:simple` actively unsets the extraheader and rewrites the remote URL with `RELEASE_TOKEN` before pushing.
 
 GitHub consumers that previously relied on `github.token` must mint a PAT (scope: `contents: write`) and store it as the `RELEASE_TOKEN` secret on the repo or org.
 
 #### `workflow:dispatch`
 
-Triggers a `workflow_dispatch` event for an arbitrary workflow in an arbitrary repo on the same git host — useful for release→deploy patterns where one repo's CI kicks off a workflow in another (e.g. an infra repo). `release:trigger` is a special case of this command, pinned to `release.yml` in the current repo.
+Triggers a `workflow_dispatch` event for an arbitrary workflow in an arbitrary repo on the same git host -- useful for release->deploy patterns where one repo's CI kicks off a workflow in another (e.g. an infra repo). `release:trigger` is a special case of this command, pinned to `release.yml` in the current repo.
 
 ```bash
 tooling workflow:dispatch \
@@ -191,22 +191,22 @@ On Forgejo it POSTs to the `actions/workflows/{workflow}/dispatches` API; on Git
 
 ##### Generated deploy step
 
-For the common release→deploy case, `repo:sync` can generate the dispatch step for you. Add a `deploy` block to `.tooling.json`:
+For the common release->deploy case, `repo:sync` can generate the dispatch step for you. Add a `deploy` block to `.tooling.json`:
 
 ```jsonc
 {
   "deploy": {
-    "dispatchRepo": "bensandee/ansible_infra", // required — repo whose workflow to trigger
-    "stack": "dirty_draft", // optional — defaults to the package name with '-' → '_'
-    "workflow": "deploy.yml", // optional — default "deploy.yml"
-    "ref": "main", // optional — default "main"
+    "dispatchRepo": "bensandee/ansible_infra", // required -- repo whose workflow to trigger
+    "stack": "dirty_draft", // optional -- defaults to the package name with '-' -> '_'
+    "workflow": "deploy.yml", // optional -- default "deploy.yml"
+    "ref": "main", // optional -- default "main"
   },
 }
 ```
 
-When `deploy` is set, `repo:sync` appends a **"Dispatch deploy"** step to the release workflow (`release.yml` for the `simple` strategy, `ci.yml` for `changesets`). The step runs `bst workflow:dispatch` only after a successful release — gated on `steps.release.outputs.pushed` (simple) or `steps.release.outputs.published` (changesets) — and forwards the release tag as the `release_tag` input. `dispatchRepo` is deliberately explicit: a deploy target is never inferred. The `release-it` strategy does not support deploy dispatch (`repo:sync` warns and skips the step). The resolved release token must have rights on `dispatchRepo`; supply a separate cross-repo token by adding its secret name to `postReleaseHookSecrets`.
+When `deploy` is set, `repo:sync` appends a **"Dispatch deploy"** step to the release workflow (`release.yml` for the `simple` strategy, `ci.yml` for `changesets`). The step runs `bst workflow:dispatch` only after a successful release -- gated on `steps.release.outputs.pushed` (simple) or `steps.release.outputs.published` (changesets) -- and forwards the release tag as the `release_tag` input. `dispatchRepo` is deliberately explicit: a deploy target is never inferred. The `release-it` strategy does not support deploy dispatch (`repo:sync` warns and skips the step). The resolved release token must have rights on `dispatchRepo`; supply a separate cross-repo token by adding its secret name to `postReleaseHookSecrets`.
 
-> **Note:** the `release_tag` input is sourced from the release step's `tag` output. On GitHub with the `changesets` strategy the release runs via `changesets/action`, which exposes no `tag` output — the deploy still fires, but `release_tag` is dispatched empty. The `simple` strategy and Forgejo `changesets` both populate it.
+> **Note:** the `release_tag` input is sourced from the release step's `tag` output. On GitHub with the `changesets` strategy the release runs via `changesets/action`, which exposes no `tag` output -- the deploy still fires, but `release_tag` is dispatched empty. The `simple` strategy and Forgejo `changesets` both populate it.
 
 #### Release assets
 
@@ -242,7 +242,7 @@ If the script runs but writes no files to `release-assets/`, `release:assets` fa
 | `command` | argv run before upload (optional; omit for pre-built files). Not interpreted by a shell. |
 | `name`    | Asset name in the release (optional; defaults to the file's basename).                   |
 
-Convention and overrides coexist — a repo can use both.
+Convention and overrides coexist -- a repo can use both.
 
 Works for both `changesets` and `simple` release strategies, on Forgejo (via API upload) and GitHub (via `gh release upload --clobber`). The asset step in the workflow is gated on the release itself having published/pushed, so failed releases never upload stale artifacts.
 
@@ -253,7 +253,7 @@ Works for both `changesets` and `simple` release strategies, on Forgejo (via API
 | `tooling coverage:summary` | Print a labeled per-package summary of the latest run. `--json` for machine-readable form.    |
 | `tooling coverage:check`   | Compare the latest run against `coverage-baseline.json`; exit non-zero on regression.         |
 | `tooling coverage:record`  | Append the latest run to a `bst/coverage-metrics` orphan branch (CI: push to default branch). |
-| `tooling coverage:status`  | Show recent coverage trend. Read-only — fetches the orphan branch, no checkout.               |
+| `tooling coverage:status`  | Show recent coverage trend. Read-only -- fetches the orphan branch, no checkout.              |
 
 The feature has two halves: a **CI history** that captures one record per commit on the default branch (visible to anyone with the repo), and a **local ratchet** that the agent (or developer) consults before declaring a task complete.
 
@@ -262,12 +262,12 @@ The feature has two halves: a **CI history** that captures one record per commit
 `repo:sync` enables coverage tracking automatically when a `vitest.config.ts` is present. The generated `vitest.config.ts` includes the `json-summary` reporter so each `pnpm test:coverage` writes `coverage/coverage-summary.json` alongside the human-readable HTML report. A generated `coverage.yml` workflow runs on push to the default branch and pipes:
 
 ```text
-pnpm test:coverage  →  coverage:summary  →  coverage:record  →  coverage:status
+pnpm test:coverage  ->  coverage:summary  ->  coverage:record  ->  coverage:status
 ```
 
 so every CI log ends with the trend table for the last 10 records.
 
-The history file (`coverage-history.jsonl`) lives on a dedicated `bst/coverage-metrics` orphan branch — never on `main`. This sidesteps branch protection (no privileged token needed beyond `contents: write`) and keeps `git log main` clean. `coverage:record` uses pure git plumbing (`hash-object` → `mktree` → `commit-tree` → `push --force-with-lease`) so the working tree is never touched, and concurrent CI runs are handled safely via compare-and-swap with retry.
+The history file (`coverage-history.jsonl`) lives on a dedicated `bst/coverage-metrics` orphan branch -- never on `main`. This sidesteps branch protection (no privileged token needed beyond `contents: write`) and keeps `git log main` clean. `coverage:record` uses pure git plumbing (`hash-object` -> `mktree` -> `commit-tree` -> `push --force-with-lease`) so the working tree is never touched, and concurrent CI runs are handled safely via compare-and-swap with retry.
 
 #### The local ratchet
 
@@ -275,7 +275,7 @@ A tracked `coverage-baseline.json` at the repo root captures the four overall to
 
 `repo:sync` also inserts a `<!-- @tooling:coverage-rule -->` managed block into `CLAUDE.md` describing the workflow:
 
-> Before declaring a task complete that touched files under `packages/*/src/`, run `pnpm test:coverage` then `pnpm exec bst coverage:check`. If any total dropped, add tests until parity is restored — or, if a touched file is genuinely not worth covering, exclude it via `coverage.exclude` in `vitest.config.ts` and explain why in the commit message. If all four are flat-or-up, run `pnpm exec bst coverage:check --update-baseline` and stage `coverage-baseline.json`.
+> Before declaring a task complete that touched files under `packages/*/src/`, run `pnpm test:coverage` then `pnpm exec bst coverage:check`. If any total dropped, add tests until parity is restored -- or, if a touched file is genuinely not worth covering, exclude it via `coverage.exclude` in `vitest.config.ts` and explain why in the commit message. If all four are flat-or-up, run `pnpm exec bst coverage:check --update-baseline` and stage `coverage-baseline.json`.
 
 Skip the rule for docs-only, config-only, dependency-bump, or test-only changes.
 
@@ -309,16 +309,16 @@ Or keep the local ratchet but skip the CI history append:
 { "coverage": { "history": "none" } }
 ```
 
-| Override field       | Default                  | Description                                                            |
-| -------------------- | ------------------------ | ---------------------------------------------------------------------- |
-| `history`            | `"orphan-branch"`        | `"none"` disables CI history; the local ratchet still works            |
-| `historyBranch`      | `"bst/coverage-metrics"` | Override the orphan branch name                                        |
-| `tolerancePp`        | `0.1`                    | Tolerance in percentage points before `coverage:check` flags a drop    |
-| `gateOnPullRequests` | `false`                  | Run coverage on PR builds too (deferred follow-up — currently a no-op) |
+| Override field       | Default                  | Description                                                             |
+| -------------------- | ------------------------ | ----------------------------------------------------------------------- |
+| `history`            | `"orphan-branch"`        | `"none"` disables CI history; the local ratchet still works             |
+| `historyBranch`      | `"bst/coverage-metrics"` | Override the orphan branch name                                         |
+| `tolerancePp`        | `0.1`                    | Tolerance in percentage points before `coverage:check` flags a drop     |
+| `gateOnPullRequests` | `false`                  | Run coverage on PR builds too (deferred follow-up -- currently a no-op) |
 
 #### Per-package re-sum
 
-The trimmed record's `packages` map is computed by aggregating files whose path starts with `packages/<name>/`, so monorepo packages get their own line/branch percentages without per-package vitest configs. Single-package repos collapse to one entry keyed by the directory basename. Per-package numbers are recorded but **not gated** — only the four overall totals control the ratchet.
+The trimmed record's `packages` map is computed by aggregating files whose path starts with `packages/<name>/`, so monorepo packages get their own line/branch percentages without per-package vitest configs. Single-package repos collapse to one entry keyed by the directory basename. Per-package numbers are recorded but **not gated** -- only the four overall totals control the ratchet.
 
 ### Docker
 
@@ -351,7 +351,7 @@ The `context` field defaults to `"."` (project root) when omitted. Versions for
 
 #### Per-package build args
 
-Each `docker` entry may declare `buildArgs` — a map of `ARG_NAME` to value that is passed to that package's `docker build` as `--build-arg ARG_NAME=<value>`. Args flow to the configured package only, so they don't trigger "unused build arg" warnings on sibling images. They apply to both `docker:build` and `docker:publish`, so CI-published images match local builds.
+Each `docker` entry may declare `buildArgs` -- a map of `ARG_NAME` to value that is passed to that package's `docker build` as `--build-arg ARG_NAME=<value>`. Args flow to the configured package only, so they don't trigger "unused build arg" warnings on sibling images. They apply to both `docker:build` and `docker:publish`, so CI-published images match local builds.
 
 ```json
 {
@@ -412,8 +412,8 @@ Each package is tagged independently using its own version, so packages in a mon
 | --------------------------- | -------- | --------------------------------------------------------------------- |
 | `DOCKER_REGISTRY_HOST`      | variable | Registry hostname (e.g. `code.orangebikelabs.com`)                    |
 | `DOCKER_REGISTRY_NAMESPACE` | variable | Full namespace for tagging (e.g. `code.orangebikelabs.com/bensandee`) |
-| `<REGISTRY>_USERNAME`       | secret   | Registry username — name depends on registry host (see below)         |
-| `<REGISTRY>_PASSWORD`       | secret   | Registry password — name depends on registry host (see below)         |
+| `<REGISTRY>_USERNAME`       | secret   | Registry username -- name depends on registry host (see below)        |
+| `<REGISTRY>_PASSWORD`       | secret   | Registry password -- name depends on registry host (see below)        |
 
 **Registry-specific secret names.** The workflow generator picks the secret reference at gen time from the registry host. The env-var name inside the step is always `DOCKER_USERNAME` / `DOCKER_PASSWORD` (so the CLI reads them under stable names), but the right-hand side of `${{ secrets.X }}` is registry-specific:
 
@@ -433,7 +433,7 @@ This rename exists because Forgejo's [act fork auto-injects](https://code.forgej
 
 ## Config file
 
-`.tooling.json` stores **overrides only** — fields where the project differs from what convention/detection produces. A fully conventional project has `{}` or no `.tooling.json` at all.
+`.tooling.json` stores **overrides only** -- fields where the project differs from what convention/detection produces. A fully conventional project has `{}` or no `.tooling.json` at all.
 
 Available override fields:
 
@@ -452,7 +452,7 @@ Available override fields:
 
 ## Debug logging
 
-All CLI commands support a `--verbose` flag for detailed debug output. Alternatively, set `TOOLING_DEBUG=true` as an environment variable — useful in CI workflows:
+All CLI commands support a `--verbose` flag for detailed debug output. Alternatively, set `TOOLING_DEBUG=true` as an environment variable -- useful in CI workflows:
 
 ```yaml
 env:
@@ -461,29 +461,161 @@ env:
 
 Debug output is prefixed with `[debug]` and includes exec results (exit codes, stdout/stderr), compose configuration details, container health statuses, and retry attempts.
 
-## Library API
+## The agent daemon's web control panel
 
-The `"."` export provides type-only exports for programmatic use:
+`agent:daemon --ui` serves an opt-in board that renders the `agent/<stage>[-<status>]` label state
+machine, shows the daemon's own live state, and lets you drive the transitions you would otherwise
+apply by hand with `bst issue:set-labels` -- plus read a branch's plan and reply on its pull request
+without leaving the page. It is off by default.
 
-```ts
-import type {
-  ProjectConfig,
-  GeneratorResult,
-  GeneratorContext,
-  Generator,
-  DetectedProjectState,
-  LegacyConfig,
-} from "@bensandee/tooling";
+The problem it solves is that a parked terminal is silent: `agent/plan-ready`,
+`agent/implement-mergeable`, `agent/review-ready` and every `-failed` are states where the machine
+has stopped and is waiting on a person, and nothing announces them. The board's lanes are ordered by
+what needs you, not by pipeline position.
+
+It also closes a real gap: **the board can kill a wedged run on a headless daemon.** The interactive
+`k` keypress needs a TTY, so under systemd there was previously no way to stop a stuck container
+short of a hand-run `docker kill`.
+
+```bash
+# Loopback, port 4600, token minted at startup and logged once.
+bst agent:daemon --ui
+```
+
+The startup log carries one clickable line -- open it and the token is exchanged for a session
+cookie, so it never sits in your history:
+
+```
+board: http://127.0.0.1:4600/?t=<token>
+board listening on http://127.0.0.1:4600
+```
+
+### Reaching it from a phone
+
+The documented deployment binds **loopback only** and publishes the board through a tailnet TLS
+terminator, so nothing is listening on your LAN at all and no phone is asked to trust a self-signed
+certificate:
+
+```bash
+bst agent:daemon --ui \
+  --ui-public-url https://box.tail1234.ts.net \
+  --ui-behind-tls
+
+# and, separately, whatever your terminator wants:
+tailscale serve --bg 4600
+```
+
+**Both flags are required, and each fails closed in a way that looks like a bug if you omit it:**
+
+- `--ui-public-url` adds the external hostname to the Host-header allowlist. Your browser sends
+  `Host: box.tail1234.ts.net`, not `127.0.0.1:4600`, so without it **every** proxied request is
+  rejected with a bare `403`. It is also what makes the startup line print the URL you can actually
+  open.
+- `--ui-behind-tls` marks the session cookie `Secure`. It has to be explicit: the daemon serves plain
+  HTTP and cannot see that something in front terminated TLS, and `X-Forwarded-Proto` is
+  attacker-supplied unless a trusted proxy is guaranteed -- which nothing here can guarantee.
+
+A non-loopback `--ui-bind` still works, but **pass `--ui-public-url` with it too.** The Host-header
+allowlist is built from the bind string literally, so `--ui-bind 0.0.0.0` allows the useless
+`Host: 0.0.0.0:4600` while your browser sends the machine's actual address -- and every request comes
+back a bare `403` with nothing to explain it. `--ui-public-url http://<host-or-ip>:4600` names the host
+you will really reach it at. Binding a specific address you then type verbatim needs nothing extra.
+
+### The board token, and the session it mints
+
+There is exactly one credential to be careful with, and its lifetime is the part people get wrong:
+
+|           | Board token                                                       | Session cookie it mints |
+| --------- | ----------------------------------------------------------------- | ----------------------- |
+| Lifetime  | the daemon **process** -- a service, so weeks                     | 12 hours                |
+| Scope     | label transitions + comments + kill, every repo the bot can write | the board, nothing else |
+| Holders   | one, shared                                                       | one browser             |
+| Persisted | never                                                             | never                   |
+
+The board token gates reaching the board at all, and everything it grants happens under the daemon's
+bot token. It is "short-lived" only relative to a config file; against the process it gates it is
+long-lived, and rotating it means restarting the daemon -- at which point a phone bookmark goes dead
+and you return to the log for a fresh link. That is the accepted cost of never persisting it.
+
+Session cookies are `HttpOnly`, `SameSite=Strict`, and expire after 12 hours. Every request is
+checked against a Host-header allowlist **and** an `Origin` check; neither replaces the other,
+because an `Origin` check alone does not defeat DNS rebinding.
+
+There is no second forge credential. **Everything the board writes -- labels and comments alike --
+is written under the daemon's own bot token**, so there is no operator PAT to mint and no account to
+connect. What that costs is authorship, and the next section is about why paying it is safe.
+
+### Reading a plan, and replying to one
+
+Three things a parked PR row offers beyond its label transitions:
+
+**`View doc`** shows that branch's plan or spec without a clone. The doc is located by the same
+`<kind>-<n>` naming convention the runs themselves use, and it is fetched **at the PR's head ref** --
+what you read is the plan as the run left it, not as the default branch has it. The page reports
+checkbox progress (`14 of 21 tasks`) and links out to the forge's own rendered view. The body itself
+is shown as **plain escaped text, never rendered markdown**: branch content is written by anyone who
+can push to it, and the board will not render it.
+
+**`Comment`** opens a form on the PR's own thread (never a backing issue, whose comments are replayed
+to every later run rather than windowed). Posting takes the same two-step confirm as kill, because
+the forge has no comment-edit API and nothing you post can be retracted from here.
+
+The comment is **authored by the daemon's bot account**, with a plain-prose suffix saying so:
+
+```
+Looks right, but rebase on main first.
+
+-- posted from the agent daemon control panel
 ```
 
-| Type                   | Description                                                                                     |
-| ---------------------- | ----------------------------------------------------------------------------------------------- |
-| `ProjectConfig`        | User config shape (persisted in `.tooling.json`)                                                |
-| `GeneratorContext`     | Context passed to generator functions (`exists`, `read`, `write`, `remove`, `confirmOverwrite`) |
-| `GeneratorResult`      | Result from a generator (created/updated/skipped files)                                         |
-| `Generator`            | Generator function signature: `(ctx: GeneratorContext) => Promise<GeneratorResult>`             |
-| `DetectedProjectState` | Detected existing project state (package manager, CI, etc.)                                     |
-| `LegacyConfig`         | Legacy config detection for migration                                                           |
+That is safe because the boundary the agent uses to tell its own words from yours is **marker-based,
+not author-based**: a run's own comments start with a reserved marker (`**agent:run**` and friends),
+and everything without one is treated as human feedback no matter who wrote it. So a bot-authored
+board comment reaches the next run exactly like one you typed in the forge's web UI. The attribution
+is a **suffix** for the same reason -- markers are matched at the start, so trailing prose can never
+be mistaken for one. The flip side: **the board refuses a comment whose text starts with a reserved
+agent marker.** Typing `**agent:run**` yourself would move the run's own watermark and silently hide
+every human comment written before it, so the form rejects it by name rather than posting something
+that lies to the next run.
+
+**The `N new comments` badge** on a parked row means: human comments on that PR newer than the last
+agent operation on it -- the same window the next run will actually read, computed from the same two
+functions, so the badge cannot promise the run something different. It appears on **pull request rows
+only**; an issue's comments are replayed to every run whole, so "new since the last run" has no
+meaning there and a number would be a lie. The counts are fetched in the daemon's poll cycle and
+memoized, so a row nothing has touched costs nothing and `GET /` still makes no forge call.
+
+### What it costs, and what it does not
+
+Reads are cheap, not free: the publishers write a snapshot into memory and `GET /` is a synchronous
+render off it, so **a board page load makes no forge call of its own**. What it does do is record
+that someone is watching, which arms a refresher that drains queued actions and re-searches the
+forge every few seconds until nobody is. That traffic is bounded by one refresher per daemon rather
+than by how many tabs are open, and it stops an idle window after the last reader's last request --
+a window derived from the poll interval, never shorter than two minutes. Closing the tab does not
+cut that short: the stream ends at once, but presence also counts that reader's last request, and
+nothing clears it early. The page renders its own
+staleness (`as of 12s ago`) rather than implying it is live. Opening a doc view or posting a comment
+hits the forge from the request itself -- those are explicit navigations you asked for, and they are
+the only two that do.
+
+**One honest caveat:** a request can still be delayed by a single in-flight _synchronous_ git `exec`
+in the run pipeline -- `clone`, `rev-parse`, `diff`, `status`, `commit`, `ls-remote` -- each of which
+briefly blocks the event loop, a `git clone --depth 1` being the longest. The container run itself
+does not block. Making those git calls async is out of scope, so the board is usually instant and
+occasionally waits out one clone.
+
+An action is **queued, not applied**, when the page comes back. The board never writes a label
+itself; the daemon drains queued actions -- at the top of its next claim cycle, and on the board
+refresher's own timer while a viewer is present -- which keeps it the only writer of agent labels in
+the process. A row says `queued` in either state, because the refresher applies it within a tick or
+two whatever the claim cycle is doing. Each action is re-checked against live labels when it is
+applied, and one whose target has since been claimed is skipped with the reason shown on the row
+rather than silently dropped. Kill is the exception: it writes no label, so it takes effect
+immediately rather than at a drain.
+
+`--ui` is refused together with `--once`, which runs a single cycle and returns -- the board would
+serve one page and then be a dead surface whose every control did nothing.
 
 ## Docker check
 
@@ -493,7 +625,7 @@ import type {
 
 A smoketest is a command that runs against the live Docker stack after all containers are healthy and HTTP health checks pass. This is useful for running integration tests, API contract checks, or any validation that requires the full stack to be running.
 
-**Auto-detection:** If the root `package.json` has a `"test:smoke"` script, it is automatically used as the smoketest command — no configuration needed.
+**Auto-detection:** If the root `package.json` has a `"test:smoke"` script, it is automatically used as the smoketest command -- no configuration needed.
 
 **Manual configuration:** For non-conventional command names, configure via `.tooling.json`:
 
@@ -519,82 +651,23 @@ services:
       - ANTHROPIC_API_KEY=${ANTHROPIC_API_KEY}
 ```
 
-**Unset variables are filled with an empty string, automatically.** Compose interpolates each file _before_ merging them, so on a host where `ANTHROPIC_API_KEY` is unset it prints `The "ANTHROPIC_API_KEY" variable is not set. Defaulting to a blank string.` on every invocation — including teardown, after the check has already passed. Before each stack comes up, `docker:check` asks compose which variables are still unset and sets each to the empty string compose was substituting anyway: the warnings go away and the value every container sees is unchanged. One line names what was filled.
+**Unset variables are filled with an empty string, automatically.** Compose interpolates each file _before_ merging them, so on a host where `ANTHROPIC_API_KEY` is unset it prints `The "ANTHROPIC_API_KEY" variable is not set. Defaulting to a blank string.` on every invocation -- including teardown, after the check has already passed. Before each stack comes up, `docker:check` asks compose which variables are still unset and sets each to the empty string compose was substituting anyway: the warnings go away and the value every container sees is unchanged. One line names what was filled.
 
 Two things follow from this that are worth knowing:
 
 - **Setting the value in the check overlay does not silence the warning.** The overlay overrides the _merged_ value, but the warning comes from interpolating the base file, which happens per-file beforehand. Nothing you can write in the overlay reaches it.
 - **`docker-compose.check.env` is the file that does feed interpolation.** Drop it beside the base compose file and `docker:check` auto-detects it and passes it to compose as `--env-file`. Use it when the check needs _real_ values rather than blanks. Override the location with `dockerCheck.envFile` in `.tooling.json`.
 
-**The `PORT` trap:** when a service publishes a `${PORT}`-parameterized port, `docker:check` allocates a free host port and injects it, so a check run never collides with something already bound on the host. Assigning `PORT` in `docker-compose.check.env` (or in the ambient environment) opts out of that — your value is used verbatim, collisions included.
+**The `PORT` trap:** when a service publishes a `${PORT}`-parameterized port, `docker:check` allocates a free host port and injects it, so a check run never collides with something already bound on the host. Assigning `PORT` in `docker-compose.check.env` (or in the ambient environment) opts out of that -- your value is used verbatim, collisions included.
 
-`docker-compose.check.env` is exempt from the bst-hook's env-file deny rules, so an agent working in the repo can create and read it. It is a committed, placeholder-holding file for a throwaway stack — do not put real secrets in it.
+`docker-compose.check.env` is exempt from the bst-hook's env-file deny rules, so an agent working in the repo can create and read it. It is a committed, placeholder-holding file for a throwaway stack -- do not put real secrets in it.
 
 ### Derived HTTP health checks
 
-A service with a published port but no compose-level `healthcheck:` automatically gets an HTTP health check — no configuration needed. That check is probed **from inside the service's own container network namespace** (`docker run --network container:<id> curlimages/curl ... http://localhost:<containerPort>/`), not from the process running `bst docker:check`.
-
-This matters because compose publishes a port in the _host's_ network namespace, not the caller's. On a normal developer machine those are the same thing, so probing `localhost:<hostPort>` directly works fine — but on a CI runner that shares the host's docker daemon over a mounted socket (the standard Forgejo/GitHub Actions runner shape), the job container's `localhost` is its own netns, and the published port is unreachable from it. Probing from inside the target's own namespace works in every topology, including that one.
-
-The probe image (`curlimages/curl`) is pinned by digest, and a `docker run` exit code of `125` (Docker's convention for "the daemon failed to start the container at all" — missing image, pull denied, daemon unreachable) fails the check immediately instead of waiting out the full timeout.
-
-**This only applies to auto-derived checks.** A health check you configure yourself via `.tooling.json`'s `dockerCheck.healthChecks` is still probed with a direct `fetch()` from wherever `bst docker:check` runs — an arbitrary user-supplied URL isn't necessarily compose-related at all, so making it reachable from the caller remains your responsibility.
-
-### Library API
+A service with a published port but no compose-level `healthcheck:` automatically gets an HTTP health check -- no configuration needed. That check is probed **from inside the service's own container network namespace** (`docker run --network container:<id> curlimages/curl ... http://localhost:<containerPort>/`), not from the process running `bst docker:check`.
 
-The `@bensandee/tooling/docker-check` export provides utilities for checking Docker Compose stacks programmatically.
+This matters because compose publishes a port in the _host's_ network namespace, not the caller's. On a normal developer machine those are the same thing, so probing `localhost:<hostPort>` directly works fine -- but on a CI runner that shares the host's docker daemon over a mounted socket (the standard Forgejo/GitHub Actions runner shape), the job container's `localhost` is its own netns, and the published port is unreachable from it. Probing from inside the target's own namespace works in every topology, including that one.
 
-#### Quick start
-
-```ts
-import { createRealExecutor, runDockerCheck } from "@bensandee/tooling/docker-check";
-import type { CheckConfig } from "@bensandee/tooling/docker-check";
-
-const config: CheckConfig = {
-  compose: {
-    cwd: "./deploy",
-    composeFiles: ["docker-compose.yaml"],
-    services: ["api", "db"],
-  },
-  buildCommand: ["pnpm", "image:build"],
-  healthChecks: [
-    {
-      name: "API",
-      url: "http://localhost:3000/health",
-      validate: async (res) => res.ok,
-    },
-  ],
-  smoketest: ["pnpm", "test:smoke"],
-  timeoutMs: 120_000,
-  pollIntervalMs: 5_000,
-};
-
-const result = await runDockerCheck(createRealExecutor(), config);
-if (!result.success) {
-  console.error(result.reason, result.message);
-}
-```
+The probe image (`curlimages/curl`) is pinned by digest, and a `docker run` exit code of `125` (Docker's convention for "the daemon failed to start the container at all" -- missing image, pull denied, daemon unreachable) fails the check immediately instead of waiting out the full timeout.
 
-#### Exports
-
-| Export                                 | Description                                                                  |
-| -------------------------------------- | ---------------------------------------------------------------------------- |
-| `runDockerCheck(executor, config)`     | Full lifecycle: build, compose up, health check polling, smoketest, teardown |
-| `createRealExecutor()`                 | Production executor (real shell, fetch, timers)                              |
-| `composeUp(executor, config)`          | Start compose services                                                       |
-| `composeDown(executor, config)`        | Stop and remove compose services                                             |
-| `composeLogs(executor, config)`        | Stream compose logs                                                          |
-| `composePs(executor, config)`          | List running containers                                                      |
-| `checkHttpHealth(executor, check)`     | Run a single HTTP health check                                               |
-| `getContainerHealth(executor, config)` | Check container-level health status                                          |
-
-#### Types
-
-| Type                  | Description                                                                                |
-| --------------------- | ------------------------------------------------------------------------------------------ |
-| `CheckConfig`         | Full check config (compose settings, build command, health checks, smoketest, timeouts)    |
-| `ComposeConfig`       | Docker Compose settings (cwd, compose files, env file, services)                           |
-| `HttpHealthCheck`     | Health check definition (name, URL, validate function)                                     |
-| `CheckResult`         | Result: `{ success: true, elapsedMs }` or `{ success: false, reason, message, elapsedMs }` |
-| `DockerCheckExecutor` | Side-effect abstraction (exec, fetch, timers) for testability                              |
-| `ContainerInfo`       | Container status info from `composePs`                                                     |
+**This only applies to auto-derived checks.** A health check you configure yourself via `.tooling.json`'s `dockerCheck.healthChecks` is still probed with a direct `fetch()` from wherever `bst docker:check` runs -- an arbitrary user-supplied URL isn't necessarily compose-related at all, so making it reachable from the caller remains your responsibility.

package/bin/bst.mjs

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+/**
+ * Stable bin target for `bst`.
+ *
+ * This file exists only so that `node_modules/.bin/bst` can be created, and it is committed
+ * rather than built for exactly that reason. pnpm links bins **during install**, and skips one
+ * whose target is missing -- so pointing `bin` straight at `dist/bin.mjs` works only in a tree
+ * that already happens to be built. A fresh checkout installs before it builds, pnpm warns
+ * (`Failed to create bin ... ENOENT`) and moves on, and building afterwards does not go back and
+ * create the link. Every later `pnpm exec bst` then fails with `Command "bst" not found`, which
+ * is what broke CI on this repo's own `check` script.
+ *
+ * The indirection costs one module load and makes the bin link independent of build state: the
+ * link always exists, and `dist/bin.mjs` only has to be there by the time someone runs it. When
+ * it is not, the failure is an explicit ERR_MODULE_NOT_FOUND naming the missing build output --
+ * a far better error than a command that appears not to exist.
+ *
+ * Consumers installing from the registry get both files (`files` ships `bin` and `dist`) and are
+ * unaffected either way, since a published tarball is always built.
+ *
+ * Loaded with a dynamic `await import` rather than a bare `import "../dist/bin.mjs"`, which is an
+ * unassigned import and trips `import(no-unassigned-import)`. Suppressing that rule would be the
+ * wrong trade for a file whose entire purpose is a side effect: the dynamic form says "run this"
+ * rather than "bring in these bindings", which is what is actually meant here.
+ */
+await import("../dist/bin.mjs");