pi-superagent 0.0.0-stage → 0.1.1

package/ADAPTATION.md

@@ -0,0 +1,71 @@
+# Adaptation ledger
+
+If you follow a request from GitHub into the code, you’ll cross a boundary at `src/core/`.
+DeepSeek’s dsh-superagent-prototype supplies the rules for opening a ticket, assigning a worker
+and recording the outcome. This project supplies the pieces that talk to GitHub, run pi and keep
+the worker’s terminal open in herdr.
+
+That split gives maintainers a place to start. For a question about what a *ready* report means,
+look in the engine. For a question about how that report becomes a GitHub comment, look in
+`src/pi/`. The tables below identify the upstream files and the local code on either side.
+
+## The baseline
+
+The files below match upstream commit `8c32a9dc5d72c033816c6a8110b37f40cf94fba4` byte for byte.
+The pinned revision is recorded in `vendor/dsh-superagent/UPSTREAM_SHA`.
+
+| Here | Upstream |
+| --- | --- |
+| `src/core/` | `src/core/` |
+| `test/core-engine.spec.ts` | `tests/core-engine.spec.ts` |
+| `vendor/dsh-superagent/docs/` | `docs/` |
+| `vendor/dsh-superagent/LICENSE` | `LICENSE` |
+
+Run these comparisons from the repository root. Each `diff` exits successfully for an exact match.
+
+```sh
+git clone https://github.com/deepseek-ai/dsh-superagent-prototype /tmp/upstream
+git -C /tmp/upstream checkout "$(cat vendor/dsh-superagent/UPSTREAM_SHA)"
+diff -r /tmp/upstream/src/core src/core
+diff /tmp/upstream/tests/core-engine.spec.ts test/core-engine.spec.ts
+diff -r /tmp/upstream/docs vendor/dsh-superagent/docs
+diff /tmp/upstream/LICENSE vendor/dsh-superagent/LICENSE
+```
+
+## Deviations
+
+There are currently no local deviations. Record any future change here with the affected file, upstream
+revision and reason. Maintainers will need that history when they apply the next upstream fix.
+
+## Local adapters
+
+The engine is synchronous and does no I/O of its own. The interfaces in `src/core/ports.ts` connect it to storage, processes and
+models. Their implementations live in `src/pi/`.
+
+| Port | Bound in | How |
+| --- | --- | --- |
+| `Repositories` | `store.ts` | synchronous `node:sqlite` in WAL mode with `synchronous=FULL`, one transaction per engine command |
+| `Policy` | `router.ts` (`policyOf`) | admits a trigger only from a person who is not on the bot list |
+| `SourceScope` | `router.ts` (`scopeOf`) | filters incoming authors by GitHub association or the configured login list |
+| `Assessor` | `assessor.ts`, `judge.ts` | candidates go one at a time to a headless pi judge, which answers with `ticket_decide` |
+| `Executor` | `executor.ts`, `herdr-workers.ts` | one pi session per assignment, in its own herdr tab, reached through files that outlive the router |
+| `Outbox` | `outbox.ts` | GitHub comments, queued once per id and marked sent only once GitHub accepts them |
+
+The engine accepts triggers directly. `source-github.ts` converts issues, comments and reviews
+into triggers and saves its read positions in the engine’s SQLite database. Upstream also ships a
+Feishu source, an executor, a panel and a store. This project supplies its own GitHub integration,
+herdr workers, panel (`server.ts`) and storage adapter (`store.ts`).
+
+Only the engine writes a ticket. The worker submits its assignment outcome through
+`ticket_report`. A *blocked* report carries the question that the router posts for the requester.
+
+## Tests
+
+`test/core-engine.spec.ts` is the upstream engine suite. `test/sqlite-engine.spec.ts` runs the
+same 113 cases against the local SQLite adapter, exercising the same transitions with persistent storage.
+
+## Taking an upstream change
+
+Copy the files listed in the baseline table to their corresponding local paths and update
+`vendor/dsh-superagent/UPSTREAM_SHA`. If a ticket transition changed, update `formal/Ticket.tla`.
+Run `npm run check` and `scripts/check-formal` against the new baseline.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 the pi-superagent authors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/NOTICE

@@ -0,0 +1,19 @@
+# NOTICE: vendored code
+
+`src/core/` and `test/core-engine.spec.ts` are copied, unchanged, from:
+
+- project: **dsh-superagent-prototype**, a DeepSeek research prototype
+- repository: https://github.com/deepseek-ai/dsh-superagent-prototype
+- commit: `8c32a9dc5d72c033816c6a8110b37f40cf94fba4` (2026-10-31, "feat: add the dsh-superagent research prototype")
+- license: MIT, full text in `vendor/dsh-superagent/LICENSE`
+
+`vendor/dsh-superagent/docs/` keeps upstream's nine design documents. They specify the state machine in
+`src/core`, and they are the place to look when one of its rules seems arbitrary: start with
+`001-domain.md` (the concepts, and the ones rejected), `002-authorization.md` (the gate and the admission
+table) or `003-execution.md` (reports and attention).
+
+Upstream calls its code a research prototype. This repository vendors the domain, not the deployment:
+upstream's executor, its Feishu and GitHub sources and its panel are replaced here by pi sessions in
+herdr, a GitHub source of this repository's own, and a local panel.
+
+[ADAPTATION.md](ADAPTATION.md) shows how to prove the copy is exact, and where each binding plugs in.

package/README.md

@@ -1,3 +1,99 @@
-# Temporary Holding Version
+# pi-superagent
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Open a GitHub issue and tell pi-superagent what you’d like to change. A coding agent works on it
+in a checkout on your machine and opens a pull request for you to review. If you ask for a
+revision, the same agent picks it up.
+
+You can follow the conversation on GitHub or open the agent’s terminal to see what it’s trying
+and lend a hand.
+
+## Install
+
+You’ll need Git, Node 22.19 or later, and three tools on a Mac or Linux machine. Pi runs the coding
+sessions. Herdr gives each session a terminal tab. The GitHub CLI (`gh`) lets the agent read issues
+and open pull requests using your account. [pi](https://github.com/earendil-works/pi) ·
+[herdr](https://herdr.dev) · [GitHub CLI](https://cli.github.com)
+
+Sign in to a model provider in pi and check that your model appears in `pi --list-models`. Then
+sign in to GitHub with an account that can write to the repository you want to use.
+
+```sh
+gh auth login
+gh auth setup-git
+pi install npm:pi-superagent
+npm install -g pi-superagent
+```
+
+The first install gives pi the extension. The second gives you the `superagent` command to start,
+stop and check on it. Keep the two at the same version when you update.
+
+## Try it on one issue
+
+Choose a repository and open herdr in your terminal.
+
+```sh
+superagent init your-org/your-repo
+herdr
+```
+
+Leave herdr open. In a second terminal, start the **router**, the background session that watches
+your repository and sends work to the right agent.
+
+```sh
+superagent start
+superagent status
+```
+
+In herdr, find the `superagent` workspace and wait for the first GitHub poll in the **engine log**
+tab. That first look records the issues already open. Now open a new issue with a small request.
+For example, “Show the keyboard shortcut next to Export in the Help menu.”
+
+When the router accepts the request, it replies on the issue and opens a **ticket**, its record of
+the work. A **worker** is the pi session assigned to that ticket. It gets its own checkout and a
+tab labeled with the issue number. You can type into the tab, though usually a comment on the
+issue is enough. If the worker needs a decision, it asks there.
+
+A code change comes back as a pull request. Review the diff as usual. The ticket stays open while
+you discuss the change and ends when you merge or close the PR. You can also ask a question, such
+as where the shortcut is defined. For that, an answer on the issue can finish the job.
+
+## While the worker runs
+
+- **On GitHub**, reply on the issue to add a detail, or on the pull request to request a revision.
+  To stop work before there’s a PR, close the issue. Reopening it makes a fresh request.
+- **In herdr**, open the tab with the issue number to see the worker’s commands and output. The
+  **engine log** tab shows what the router picked up and which requests it accepted.
+- **In the local panel**, look under *Needs a person* to see who’s waiting for an answer. You can
+  also see running workers, queued work and recent decisions. [Open the panel](http://127.0.0.1:8788/)
+
+By default, the router listens to authors GitHub identifies as owners, organization members or
+collaborators. You can choose particular logins, give the router its own GitHub account, or supply
+a custom workspace setup. Run `superagent stop` when you want to stop the router.
+[Operator guide](docs/operator-guide.md) · [Configuration examples](config.example.env)
+
+## How it works
+
+A separate pi session called the **judge** reads a new request and decides whether there’s work to
+do. Once a ticket is open, follow-up comments go straight to its worker. The worker reports the
+outcome through a tool call, which lets the router distinguish a finished run from a question or
+a crash. The router stores the ticket on disk, so after a restart it can find the worker and pick
+up the conversation. [Architecture](docs/architecture.md) · [Design decisions](docs/design-decisions.md)
+
+The ticket engine comes from DeepSeek’s dsh-superagent-prototype. Three TLA+ models check how
+tickets, incoming messages and worker tabs behave when events arrive in different orders.
+[Upstream project](https://github.com/deepseek-ai/dsh-superagent-prototype) ·
+[Adaptation ledger](ADAPTATION.md) · [Formal verification](docs/formal-verification.md)
+
+## Development
+
+```sh
+npm install
+npm run check            # Type-check and run the test suite
+npm run check:packed     # Install the tarball and exercise both the CLI and the pi extension
+scripts/check-formal     # Check all three models (about five minutes with a JDK)
+```
+
+The test suite clears `PI_SUPERAGENT_*` settings to isolate its router from yours.
+Publishing runs both npm checks before uploading the package.
+
+Both projects use the MIT license. [Upstream attribution](NOTICE)

package/config.example.env

@@ -0,0 +1,81 @@
+# pi-superagent settings.
+#
+# Copy this file to config.env in the state directory (~/.pi/superagent unless PI_SUPERAGENT_STATE says
+# otherwise), edit it, and run `superagent restart`. The start script reads it on every start, so
+# a restart by hand and a restart by the health check run the same router. A variable already set in the
+# environment wins over this file.
+#
+# One KEY=value per line, taken literally: no quotes, no $VARIABLES, no ~, and no comment after a value.
+# Each commented-out line shows a setting's default.
+
+# ---- GitHub, the only way in ----
+
+# The repository to watch. Unset, the router runs with intake switched off.
+PI_SUPERAGENT_GITHUB_REPO=your-org/your-repo
+
+# The account the agent replies from, if it has one of its own: its comments are never requests. Leave it
+# unset when you and the agent share an account. The agent's replies then carry a hidden marker instead,
+# and naming your own account here would discard every comment you write.
+#PI_SUPERAGENT_GITHUB_SELF=your-agent-bot
+
+# The agent's own GitHub account: a file holding a token for it (classic, repo scope), read on every call.
+# The router then reads the watched repository and posts every reply as that account. Give the account
+# access to the watched repository, set PI_SUPERAGENT_GITHUB_SELF to its login, and keep the file readable
+# only by you (chmod 600). Workers still act as the account gh is signed in as, and the router reads their
+# pull requests as that account too, since it opened them. Unset, the router acts as gh's account.
+#PI_SUPERAGENT_GITHUB_TOKEN_FILE=/absolute/path/to/token
+
+# Author patterns that are bots, never people. A * matches anything.
+#PI_SUPERAGENT_BOTS=pi-*,fleet-*
+
+# Who the router hears. Unset, only people with write access to the repository: GitHub's OWNER, MEMBER
+# (any member of the owning organization) and COLLABORATOR. Everyone else's issues, comments and reviews
+# are dropped before the judge sees them, because a request starts a worker with a shell on this machine.
+# Set, this comma-separated list of logins replaces that rule, so include your own. A * matches anything.
+#PI_SUPERAGENT_ALLOWED=your-login,a-teammate
+
+# ---- the router ----
+
+# Milliseconds between polls of GitHub when nothing else wakes the router.
+#PI_SUPERAGENT_TICK_MS=30000
+
+# The panel's port, on 127.0.0.1.
+#PI_SUPERAGENT_PANEL_PORT=8788
+
+# The judge's thinking level, in pi's names for them.
+#PI_SUPERAGENT_JUDGE_THINKING=low
+
+# Seconds `superagent stop` waits for the router to exit before closing its tab.
+#PI_SUPERAGENT_GRACE=30
+
+# ---- herdr ----
+
+# The herdr binary, if it is not on PATH.
+#PI_SUPERAGENT_HERDR=herdr
+
+# The workspace that holds the router and its workers.
+#PI_SUPERAGENT_HERDR_WORKSPACE=superagent
+
+# The router's agent name in herdr.
+#PI_SUPERAGENT_SESSION=superagent
+
+# ---- workers ----
+
+# Workers on a run at once. Workers parked between runs do not count; further tickets wait their turn.
+#PI_SUPERAGENT_MAX_WORKERS=4
+
+# An absolute path for the per-ticket workspaces. The default is the work directory in the state directory.
+#PI_SUPERAGENT_WORKTREES=/absolute/path/to/workspaces
+
+# By default a new worker clones the watched repository and checks out superagent/<ticket-id>.
+# Set this command to replace the default checkout. It runs with PI_SUPERAGENT_TICKET and
+# PI_SUPERAGENT_DIR set. It runs again whenever the ticket gets a fresh worker, so make it safe to repeat.
+# If it fails, the ticket fails with the command's own output.
+#PI_SUPERAGENT_PREPARE=[ -d .git ] || git clone --depth 1 https://github.com/your-org/your-repo .
+
+# Command names a worker may not run, comma-separated. Names only: no arguments, no paths.
+#PI_SUPERAGENT_BLOCKED=gh,ssh
+
+# Set to 1 to let workers start subagents, workflows and other sessions. Delegated work escapes the
+# ticket's mandate, workspace and report, so it is off by default.
+#PI_SUPERAGENT_ALLOW_DELEGATION=1

package/docs/architecture.md

@@ -0,0 +1,139 @@
+# Architecture
+
+A GitHub issue is where people talk about the work. A ticket is how pi-superagent remembers whose
+turn it is. The **router** keeps the two in step. It watches the repository, asks a **judge** to
+interpret new requests, and gives each accepted task to a **worker** with its own terminal and
+checkout.
+
+## Follow a comment through the system
+
+Imagine adding “Please keep the keyboard shortcut” to an issue while a worker is editing the menu.
+On its next poll, the router reads your comment through the GitHub CLI. The GitHub source turns it
+into a **trigger**, a message with an ID and a thread. The engine checks who sent it, finds the
+ticket that already owns the thread and queues the comment for that worker.
+
+A new thread takes one extra step. The judge reads the request and calls `ticket_decide`. An
+acceptance opens a ticket and queues an acknowledgement on GitHub. The worker later calls
+`ticket_report` with its outcome. If the report links a pull request, the router records that link
+before the engine processes the report. That’s how an issue can stay active through code review
+even after the worker has finished its first edit.
+
+## If the router restarts halfway through
+
+Suppose the router reads your comment and loses power a moment later. Whether the worker received
+it depends on where the router stopped. Three records let it resume the conversation.
+
+- **The GitHub read position** records how far the router has read. A poll saves its new position
+  at the start of the next poll, after the engine has received the triggers. On replay, stable IDs
+  let the engine recognize a comment, issue or review it has already seen.
+- **The ticket and worker records** say who has the assignment. Each engine command commits its
+  changes in one SQLite transaction. Worker starts, deliveries and stops follow that commit.
+  The worker’s tab and files can outlive the router, which uses a saved position to resume reading
+  the worker’s events and reports.
+- **The outbox** records what the router owes the GitHub thread. If a reply was pending when the
+  router stopped, a retry looks for the comment on GitHub before posting it again.
+
+## The parts
+
+### Ticket engine
+
+The vendored state machine lives in `src/core/`. `intake.ts` routes triggers to an existing ticket
+or queues an evaluation. `evals.ts` turns an accepted evaluation into a ticket.
+`assignments.ts` records reports and tracks the running assignment. `tickets.ts` handles stops,
+retries and wake-ups. `replies.ts` gives each acknowledgement or reply a stable queue key.
+The synchronous engine reaches storage, processes and models through the interfaces in `ports.ts`.
+
+### Router and intake
+
+`src/pi/extension.ts` creates the store, GitHub source, judge, executor, outbox and panel. By default
+the router polls every 30 seconds and also wakes when its pi session goes idle. A pass delivers new
+triggers, reconciles PRs and closed threads, evaluates requests, starts pending work, checks for quiet
+workers and flushes replies. Three consecutive GitHub poll failures set an error in `health.json`.
+
+`source-github.ts` tracks issues, comments and submitted reviews. It recognizes the router’s own
+comments by the bot login or a hidden marker. `scopeOf` in `router.ts` checks each author’s GitHub
+association or the configured login list before the trigger can reach a judge or worker.
+`gh-api.ts` runs the CLI asynchronously, paginates issue and PR lists, and reads comments forward
+from the saved position.
+
+### Judge
+
+`policyOf` in `router.ts` checks human authorship and bot patterns. For a request that needs a
+decision, `assessor.ts` assembles the thread, messages, existing tickets and issue link.
+`judge.ts` runs one candidate at a time in a headless pi session with a single tool, `ticket_decide`.
+The session excludes extensions, skills and context files. The router overrides an acceptance if
+an open ticket already owns the thread.
+
+### Workers
+
+`executor.ts` schedules an assignment and `herdr-workers.ts` starts pi in a new tab. By default the
+worker gets a clone of the watched repository on its own ticket branch. Under `workers/<session>/`,
+the router writes prompts to `inbox/` and the worker appends to `events.jsonl` and `reports.jsonl`.
+A restarted router can adopt the tab and resume reading those files.
+
+Inside the session, `worker-role.ts` registers `ticket_report` and the tool guards in `workspace.ts`.
+The worker observes the order of its own events, so it can report a run that ended without a
+report. A crash frees the slot immediately. On the first crash the router starts a replacement in
+the same workspace and includes the previous failure in its brief.
+
+A parked worker keeps its context and releases its slot. A finished worker’s tab stays open for
+ten minutes. If pi is still busy, the router checks again ten minutes later. At startup it also
+checks for tabs with no owning record or no corresponding herdr agent.
+
+### Pull requests and replies
+
+`pulls.ts` binds each reported PR to its ticket with `bindThread` before the engine processes
+the report. That order matters. A ready report on a ticket with an open PR leaves it awaiting review.
+When the PR leaves the watched repository’s open list, the follower checks whether it merged or
+closed and calls `threadClosed`. For another repository it checks every two minutes and routes
+comments and reviews through the qualified thread ID, `owner/repo#N`.
+
+`receipts.ts` formats reports, questions, crashes and launch failures for the GitHub thread.
+`outbox.ts` queues messages by ID. Failed posts remain pending, and a recurring launch failure
+produces one notice. The source recognizes the hidden `<!-- superagent -->` marker on outgoing
+comments. Sent entries expire after 30 days.
+
+### Panel and process management
+
+`server.ts` reads the engine store for each page or API request. It listens on `127.0.0.1:8788`
+by default and logs the chosen port if it has to bind a free one. It checks the Host header against
+loopback names and requires `x-superagent-request: 1` on API calls.
+
+`scripts/superagent` configures the repository, starts or stops the router and reports health.
+The macOS job in `launchd/` checks every five minutes. It restarts a down router and respects the
+operator’s stop marker.
+
+## The state directory
+
+The router stores its local state under `~/.pi/superagent`. Set `PI_SUPERAGENT_STATE` to use a different directory.
+
+| Path | What it holds |
+| --- | --- |
+| `tickets.db` | the engine's SQLite store, including read positions and the outbox |
+| `config.env` | deployment settings, read by the start script |
+| `engine.log` | the router's log, rotated at 5 MB |
+| `health.json`, `setup.json`, `ready` | what `superagent status` reads |
+| `workers/<session>/` | one directory per worker: its record, inbox, events and reports |
+| `work/<ticket>/` | one workspace per ticket |
+| `worker-bin/` | shims that refuse blocked commands, first on the PATH of each workspace's setup script |
+
+To start over, stop the router and delete the directory. On the next start, the first poll records existing open issues as history.
+
+## Where each guarantee lives
+
+| Guarantee | Enforced by | Proved in |
+| --- | --- | --- |
+| One ticket per thread | intake routing in the engine; the router overrules a second accept | `Ticket.tla` I4 |
+| A ticket completes only on a *ready* report | `core/assignments.ts` | `Ticket.tla` I2 |
+| A person's stop is final | guards in `core/tickets.ts` and `core/intake.ts` | `Ticket.tla` I1 |
+| One running assignment per ticket | the executor's launch guard | `Ticket.tla` I3 |
+| Each acknowledgement queued and sent once | outbox keys in `core/replies.ts` | `Ticket.tla` I5, I6 |
+| The initial poll treats existing open issues as history | the seed rule | `Intake.tla` C1 |
+| One request per open interval of an issue | the seen set | `Intake.tla` C2 |
+| No comment lost to a crash | deferred read positions | `Intake.tla` C3, C6 |
+| No trigger accepted twice | content-derived ids | `Intake.tla` C4 |
+| A bot never passes for a person | bot patterns and the policy gate | `Intake.tla` C5 |
+| Only authors admitted by the source scope reach the judge or a worker | the source scope, `scopeOf` | tests only |
+| A ticket with a pull request ends with it, as merged or closed | binding before the report, `threadClosed` | tests only |
+| A live agent's tab is never swept | the liveness check in `closeStaleTabs` | `Workers.tla` W2, W4 |
+| Dead workers' tabs do not pile up | the sweep and the linger close | `Workers.tla` W5 |

package/docs/design-decisions.md

@@ -0,0 +1,130 @@
+# Design decisions
+
+## Why work starts on GitHub
+
+A reviewer who spots a problem in a pull request already has the diff and a place to leave a
+comment. Asking them to copy that comment onto a separate task board would split the conversation
+just when the worker needs its context. Issues, comments and reviews therefore enter through the
+same source, `source-github.ts`. A new request can open a ticket, and feedback can reach the
+worker that made the change.
+
+**Check the author before routing the message.** An accepted request starts a worker with a shell
+on the operator’s machine. A comment on an existing ticket goes straight to that worker, so a
+permission check in the judge alone would miss follow-ups. The engine checks `scopeOf` first.
+By default it admits the GitHub associations `OWNER`, `MEMBER` and `COLLABORATOR`. A missing
+association fails the check. Setting `PI_SUPERAGENT_ALLOWED` replaces that rule with a login list.
+
+**Establish a baseline on the first poll.** An early version treated an entire backlog as new work
+when the operator connected a repository. The source now saves the initial set of open issues and
+seeds the review cursor. Closing and reopening an issue makes it eligible again. Its updated
+timestamp distinguishes the new trigger from the earlier one. See `Intake.tla` C1 and C2.
+
+**Save later read positions after delivery.** A poll stages its read position for the next poll to
+commit. If the router crashes after reading a comment but before the engine receives it, the old
+position lets the router read it again. Stable trigger IDs make that replay safe. The initial
+baseline commits immediately because it represents history already present at setup. TLC found
+the comment-loss case in the original implementation. The regression test reproduces that event
+order. See `Intake.tla` C3 and C6.
+
+## Deciding what deserves a ticket
+
+**Apply policy in code.** The router checks the author against current bot patterns even when a
+stored trigger identifies the author as human. An older trigger once caused an agent’s request
+for test approval to become a ticket to run the test. After the judge answers, the router also
+checks whether an open ticket already owns the thread. The judge once accepted a duplicate despite
+having the existing ticket in its prompt.
+
+**Give the judge one request at a time.** Judging in the operator’s pane tied it up for an entire
+model turn. Sending 41 candidates into one active turn produced answers out of order, and some
+candidates expired before the judge got to them. The assessor now reuses one headless pi session
+without extensions, skills or context files. It opens the session once because startup took 20 to
+45 seconds and concurrent requests used to start separate judges.
+
+## Running a worker
+
+A worker can write “done” in its terminal while the person who opened the issue is still waiting
+on GitHub. To finish a run, it calls `ticket_report` with an outcome. A *ready* report can carry
+the link to a PR. A *blocked* report carries the question the requester needs to answer. The other
+outcomes are *failed* and *cancelled*. Only the engine writes the result to the ticket.
+See `Ticket.tla` I2.
+
+If a run ends without a report, the router posts a failure on the thread. Launch errors and crashes
+also get a reply there, so the person who asked knows what happened. The outbox recognizes repeat
+failures. One broken setup command deserves one notice, even if the router tries it on every poll.
+A quiet worker is a different case. After 15 minutes of silence it appears on the panel, where the
+operator can see whether it needs help or is simply waiting for a build.
+
+**Keep tool use within the assignment.** Worker tool hooks check file edits and writes against the
+ticket workspace, block configured commands and disable delegation by default. The prepare hook
+also gets a PATH with shims for blocked commands. Operators can use these controls to restrict
+personal tools such as `gh`. The brief asks workers sharing the machine to run builds sequentially,
+bound parallel jobs and clean up processes when they finish.
+
+**Replace a crashed worker once.** The engine records the failed attempt, frees its slot and
+requeues unread comments. The replacement gets the original workspace and a brief explaining the
+crash. A second crash on the same ticket requires attention. The limit applies per router process
+and prevents a persistent fault from spawning a new tab every few seconds.
+
+**Count active work against the cap.** A parked worker retains its session for follow-ups and frees
+a slot for queued work. A reply can briefly take the active count above the cap. Counting every
+open session used to leave a queue of 22 tickets waiting while an idle worker occupied one of four
+slots.
+
+**Check the tab before closing it.** A finished worker gets ten minutes for follow-ups. The router
+closes its tab once pi is idle and checks again every ten minutes while it is busy. Startup cleanup
+handles tabs with no owning record or whose agent herdr no longer knows. Since herdr has no guarded
+close operation, the liveness check matters whenever someone could still be working in a tab.
+See `Workers.tla` W2, W4 and W5.
+
+## Ending a ticket
+
+**Respect an explicit stop.** Once a person stops a ticket, later messages, wake-ups and retries
+cannot resume it. Asking again creates a new ticket with its own history. See `Ticket.tla` I1.
+
+**Follow the GitHub conversation.** When an issue disappears from the open set, the router can
+observe the closure even if it cannot distinguish deletion, manual closure and closure by merge.
+It stops the ticket and queues a notice. For a ticket awaiting its own PR, the PR’s merge or close
+determines the outcome. Reopening an issue lets its author ask again.
+
+**Bind the PR before processing a ready report.** A worker that changes a repository opens a PR and
+includes its URL in its report. A number such as `#5` could also name an issue. Binding the URL
+first lets the engine hold the ticket open for review. Merging or closing the PR ends the ticket,
+and the issue receives the outcome. An investigation or deployment can finish with a ready report
+alone. The worker knows which repository it changed, even when the request originated elsewhere.
+
+The router calls the vendored engine’s `bindThread` and `threadClosed` transitions. It gets review
+activity on the watched repository during the regular poll. For a PR elsewhere it polls every two
+minutes, using three API calls per check.
+
+**Route review feedback to the worker.** A submitted review on a bound PR goes to its ticket.
+A review on an unrelated PR can reach the judge as a new request. GitHub accepts replies in the
+PR conversation through its issue number. Opening a PR alone produces no request, so a worker can
+deliver a change without triggering another worker to review it.
+
+## Operating the router
+
+**Keep ticket state in one store.** One router owns the synchronous SQLite store in its state
+directory. All writes from an engine command commit together. Recovery reopens the same directory.
+The router role is tied to the appointed process because pi also loads the extension in worker
+and judge sessions. Previously those sessions could each start a router.
+
+**Report health through exit codes.** A scheduled check can act on `superagent status`. Code 0
+means healthy or intentionally stopped. Code 1 indicates a router failure that a restart may fix.
+Code 2 directs the operator to a failing component, including a GitHub source that failed three
+polls in a row. Code 3 identifies a setup problem.
+
+**Limit panel access to local callers.** The panel binds to loopback, validates the Host header
+and requires `x-superagent-request: 1` for API calls. These checks prevent a page on another
+site from reading the queue or pausing the router through DNS rebinding.
+
+## Maintaining the engine
+
+The engine and its test suite match the pinned upstream revision. Local adapters live in
+`src/pi/`, so an upstream fix can be imported and compared directly with its source.
+[Adaptation ledger](../ADAPTATION.md)
+
+The three TLA+ models live beside the implementation. Their actions name the functions they mirror
+and their headers record the assumptions. When a transition changes, update its model and run
+`scripts/check-formal`. The intake model’s crash counterexample is one case where checking all
+orderings within a small bound found a failure the tests had missed.
+[Architecture](architecture.md) · [Formal verification](formal-verification.md)