pi-superagent 0.0.0-stage → 0.1.0

package/ADAPTATION.md

@@ -0,0 +1,73 @@
+# Adaptation ledger
+
+The engine in `src/core/` is DeepSeek's, copied from upstream without a single change. This file is the
+record that keeps that true: the commit it was copied from, how to prove the copy is exact, and where
+everything that is *not* upstream plugs in.
+
+## The baseline
+
+Upstream commit `8c32a9dc5d72c033816c6a8110b37f40cf94fba4`, also recorded in
+`vendor/dsh-superagent/UPSTREAM_SHA`. At that commit these are byte-identical:
+
+| 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` |
+
+To prove it, compare against a fresh clone. Every `diff` should print nothing:
+
+```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
+```
+
+## Deviations
+
+None. If one is ever unavoidable, list it here with the file, the upstream commit it was measured
+against, what changed and why, so that the next upstream fix can still be merged by hand.
+
+## Where this repository plugs in
+
+The engine is synchronous and does no I/O of its own. Everything that touches a process, the network or
+a model reaches it through an interface in `src/core/ports.ts`, and every binding of those interfaces
+lives 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` | `extension.ts` | every thread is listened to |
+| `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 |
+
+Sources are not a port upstream; the engine simply receives Triggers. `source-github.ts` produces them
+from issues, comments and reviews, with read positions kept in the same SQLite file as the engine's state.
+
+Upstream ships its own executor, Feishu and GitHub sources, panel and SQLite store. None of them are
+vendored: this repository replaces them with pi sessions in herdr, the GitHub source above, the panel in
+`server.ts`, and the store in `store.ts`.
+
+Two of upstream's rules carry through every binding:
+
+- **A report is a tool call, not prose.** A worker's `ticket_report` call sets the state of its
+  assignment; a question in a *blocked* report becomes the ticket's request for a person.
+- **Only the engine writes a ticket.** A worker that could edit its own ticket could mark its own work
+  done.
+
+## Tests
+
+`test/core-engine.spec.ts` is upstream's engine suite, unchanged. `test/sqlite-engine.spec.ts` runs the
+same 113 cases against the SQLite store, with one line changed, because durability can only be tested
+against a store that survives the process.
+
+## Taking an upstream change
+
+Copy upstream's `src/core/`, `tests/core-engine.spec.ts` and `docs/` over their counterparts here, update
+`UPSTREAM_SHA`, and run `npm run check` and `scripts/check-formal`. If a ticket transition changed,
+change `formal/Ticket.tla` to match before trusting the result.

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,152 @@
-# 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. An agent does the work and answers you there.**
+
+pi-superagent watches one GitHub repository. When someone opens an issue, comments on one, or reviews a
+pull request, a judge reads it and decides whether a person has asked for something concrete. If one has,
+a ticket opens and a worker starts: a full [pi](https://github.com/earendil-works/pi) session in its own
+tab of herdr, a terminal multiplexer for coding agents, where you can watch it work, type into it, or take
+over. The worker finishes by calling a report tool, and the result arrives on the issue as a reply. Work
+that changes a repository arrives as a pull request, and the ticket stays open until it is merged.
+
+There are no labels to learn and no board to tend. The issue is the request, a comment is a follow-up,
+and closing the issue is the stop.
+
+The ticket engine underneath is DeepSeek's
+[dsh-superagent-prototype](https://github.com/deepseek-ai/dsh-superagent-prototype), vendored
+byte-for-byte. This repository binds it to pi, herdr and GitHub.
+
+## How a request travels
+
+1. **Trigger.** A new issue is a request; so is a comment on an issue or a pull request, and so is a
+   submitted review. Only people with write access to the repository are heard: on a public repository
+   anyone can open an issue, and a request starts a worker with a shell on your machine. On its first
+   look at a repository the router records what is already there and fires none of it.
+2. **Judgement.** The judge, a headless pi session, reads the request with its link and answers through
+   a tool: *accept*, *ignore* (chatter, a note to a colleague, a thread that already has a ticket) or
+   *stop*.
+3. **Work.** An accept opens a ticket and posts the judge's acknowledgement on the issue. A worker starts
+   in a workspace of its own, briefed with the ticket's mandate. Every later comment a person writes on
+   the thread goes straight to that worker.
+4. **Report.** The worker ends every run by calling `ticket_report`, and the router posts the report on
+   the issue. A *blocked* report asks you a question there, and your reply goes straight back to the
+   worker. A run that ends without a report, a worker that crashes, and a launch that fails are posted
+   too, each with what you can do next. A crashed worker is replaced once, without anyone asking.
+5. **Pull request.** Work that changes a repository, in any repository, goes out as a pull request the
+   worker opens and names in its report. The ticket then waits for review: comments and reviews on the
+   pull request go to the same worker. The merge ends the ticket, and the issue hears it is done; closing
+   the pull request unmerged ends it too. Work that changes no repository, such as an answer, an
+   investigation or a deployment, ends with its report.
+
+Closing the issue stops its ticket and says so on the thread. Reopening the issue starts the request again.
+
+## Why it is built this way
+
+pi-superagent grew out of a setup where agents polled markdown cards, prompts were typed into terminal
+panes, and a classifier guessed from prose whether a person had answered. Every failure there was the
+same defect in a different hat: **state recorded as text, transitions guessed by readers.** Three rules
+answer it:
+
+- **A worker reports through a tool call, never in prose.** "Done" in a chat message changes nothing.
+- **Only the engine writes a ticket.** A worker that could edit its own ticket could mark its own work done.
+- **A restart loses nothing and repeats nothing.** A read position commits only once the engine holds
+  what it produced, every trigger carries an id the engine accepts once, and every outgoing message
+  carries an id the outbox posts once.
+
+The ticket lifecycle, the GitHub intake and the worker sweep are specified in TLA+ and checked
+exhaustively, 1.5 million distinct states in all, by one command.
+
+## Install
+
+Use macOS or Linux with Git, Node 22.19 or later, [pi](https://github.com/earendil-works/pi),
+[herdr](https://herdr.dev), and the [GitHub CLI](https://cli.github.com).
+Sign into a model provider in pi and confirm your model appears in `pi --list-models`.
+Use a GitHub account with write access to the repository you want to watch.
+
+```sh
+gh auth login
+gh auth setup-git
+pi install npm:pi-superagent
+npm install -g pi-superagent
+```
+
+Pi loads the extension in router and worker sessions. The global npm install puts the
+`superagent` command on your PATH. Use the same package version for both.
+
+## Run your first ticket
+
+Substitute the GitHub repository you want the worker to change. `init` checks the local tools
+and your GitHub access, then saves the repository in `~/.pi/superagent/config.env`.
+
+```sh
+superagent init your-org/your-repo
+herdr                      # keep it open, then use another terminal
+superagent start
+superagent status
+```
+
+Wait for the first GitHub poll in the **engine log** tab, then open a new issue asking for a small
+change. The first poll records existing issues as the starting point. Watch for the acknowledgement
+on your issue. The worker clones the watched repository into its own directory, switches to a ticket
+branch, and posts the pull request on the issue. Request a change on the PR to send it back to the
+worker. Merge when you are satisfied.
+
+To supply your own workspace setup, set `PI_SUPERAGENT_PREPARE`. A replacement worker keeps the same
+ticket directory. To narrow who can start work or give the router its own GitHub identity, see
+[`config.example.env`](config.example.env). Stop the router with `superagent stop`.
+
+## Watching it
+
+Everything happens in the herdr workspace `superagent`:
+
+| Tab | What it shows |
+| --- | --- |
+| `engine log` | the router's log as it happens: every poll, judgement, launch and receipt |
+| `engine` | the router itself, a pi session that stays quiet while its loop runs in the background |
+| one per ticket | that ticket's worker, live, labelled `#141 · <issue title>` |
+
+The panel at <http://127.0.0.1:8788/> answers three questions at a glance: does anything need me, what
+is running, and what did the judge decide.
+
+## Documentation
+
+| Read | When you want |
+| --- | --- |
+| [Operator guide](docs/operator-guide.md) | to ask for work, watch it, and fix what goes wrong |
+| [Architecture](docs/architecture.md) | the map: what runs, in what order, and which file owns each rule |
+| [Design decisions](docs/design-decisions.md) | the reasons, each with the failure that taught it |
+| [Formal verification](docs/formal-verification.md) | what the TLA+ specifications prove, and what they do not |
+| [Adaptation ledger](ADAPTATION.md) | how the vendored engine is bound, and how to prove it unmodified |
+
+## Repository layout
+
+| Path | What it holds |
+| --- | --- |
+| `src/core/` | the vendored engine: tickets, evaluations, assignments, the outbox queue |
+| `src/pi/extension.ts` | the router: wires the parts together and runs the loop |
+| `src/pi/source-github.ts`, `gh-api.ts` | GitHub in: issues, comments and reviews become triggers |
+| `src/pi/pulls.ts` | pull requests: bound to their ticket, followed until merged or closed |
+| `src/pi/assessor.ts`, `judge.ts` | the judge: one candidate at a time, answered through `ticket_decide` |
+| `src/pi/executor.ts`, `herdr-workers.ts` | workers: pi sessions in herdr tabs, and records that outlive the router |
+| `src/pi/worker-role.ts`, `report-tool.ts`, `workspace.ts` | inside a worker: the report tool, the guard, the workspace |
+| `src/pi/outbox.ts`, `receipts.ts` | GitHub out: what each ending says, each message posted once |
+| `src/pi/store.ts` | the engine's SQLite store |
+| `src/pi/server.ts` | the panel and its local API |
+| `scripts/superagent` | start, stop, restart and status, with exit codes a health check can read |
+| `formal/` | the TLA+ specifications |
+
+## Development
+
+```sh
+npm install
+npm run check            # typecheck and the full suite: no model calls, no network
+npm run check:packed     # pack, install globally into a temporary prefix, run both halves from there
+scripts/check-formal     # model-check all three specifications (about five minutes; needs a JDK)
+```
+
+`npm publish` runs the first two first and stops on a failure.
+
+The suite clears every `PI_SUPERAGENT_*` variable before it runs (`test/setup.ts`), so no test can reach a
+live router.
+
+MIT licensed. The vendored engine is MIT licensed too; see [NOTICE](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,160 @@
+# Architecture
+
+This is the map: what runs, in what order, and which file owns each rule. The reasons behind the rules
+are in [design-decisions.md](design-decisions.md); the proofs about them are in
+[formal-verification.md](formal-verification.md).
+
+## The path of one request
+
+```
+ GitHub: issues, comments, reviews                     the only way in
+     │  polled every 30 s through the gh CLI            gh-api.ts
+     ▼
+ GitHub source        seed rule · deferred read positions · own-writing filter
+     │  Trigger: content-derived id, thread #N           source-github.ts
+     ▼
+ engine               scope: write access only          src/core, router.ts
+     │                policy gate: a person, not a bot
+     │  Evaluation: the thread's waiting triggers
+     ▼
+ judge                one candidate at a time, answered through ticket_decide
+     │  accept                                          assessor.ts, judge.ts
+     ▼
+ engine               ticket + pending assignment; acknowledgement queued
+     ▼
+ executor             a pi worker in its own herdr tab and workspace
+     │  ticket_report: ready · blocked · failed · cancelled, and any pull requests
+     ▼                                                  executor.ts, herdr-workers.ts
+ engine               pull requests bound first; the report lands on the ticket;
+     │                the receipt is queued
+     ▼
+ outbox               the comment, posted on the issue once  outbox.ts
+     ⋮
+ pull request         merged or closed: the ticket ends, and the issue hears it
+                      read each poll, or every 2 min elsewhere   pulls.ts
+```
+
+A crash anywhere on this path loses nothing and doubles nothing:
+
+- **GitHub to source.** Read positions are staged during a poll and committed at the next one, after the
+  engine holds every trigger they produced. A crash replays the last poll instead of skipping it.
+- **Source to engine.** Trigger ids derive from content: a comment from its author, time and body; an
+  issue from its number, title and last update; a review from GitHub's own id. The engine accepts an id
+  once, so a replay is a no-op.
+- **Inside the engine.** Each command is one SQLite transaction: its writes land together or not at all.
+- **Engine to executor.** The engine's calls to start, deliver to and stop a worker run only after the
+  command commits, so a worker never acts on a write that could still roll back.
+- **Executor and worker.** A worker writes its events and reports to files; the router reads them from a
+  cursor it persists. A restarted router resumes reading where the last one stopped, and adopts the
+  running worker instead of starting a second.
+- **Outbox to GitHub.** A message is marked sent only once GitHub accepts it. A retry first looks for the
+  comment on the issue, in case the last attempt landed before the process died.
+
+## The parts
+
+**The engine: `src/core/` (vendored, unmodified).** The state machine. `intake.ts` hands a trigger to the
+ticket that owns its thread and queues an Evaluation only when no ticket does; `evals.ts` turns an
+accepted Evaluation into a ticket; `assignments.ts` records reports and keeps one running assignment per
+ticket; `tickets.ts` stops, retries and wakes tickets; `replies.ts` queues acknowledgements and replies,
+each under a key that is queued once. The engine is synchronous and does no I/O of its own: everything
+that touches a process, the network or a model arrives through a port in `ports.ts`.
+
+**The router: `src/pi/extension.ts`.** The composition root. It builds the store, the GitHub source, the
+outbox, the judge, the executor and the panel, then runs the loop. Every 30 seconds, and whenever its own
+pi session goes idle, the loop polls GitHub, hands new triggers to the engine, stops tickets whose thread
+has closed, lets the engine start due evaluations, launches queued work, flags workers on a run that
+have gone quiet for 15 minutes, and flushes the outbox. Three failed polls in a row put an error in `health.json`.
+
+**GitHub in: `source-github.ts` and `gh-api.ts`.** The source reads issues, issue and pull-request
+comments, and submitted reviews. Its first look at a repository records what already exists and fires
+none of it. Its read positions commit one poll late, as described above. It ignores its own writing,
+recognized by the account it posts from or by the hidden marker every reply carries, and it marks
+authors matching the bot patterns as not human. Every trigger carries its author's association with the
+repository, and the router's scope (`scopeOf` in `router.ts`) files one from anyone without write access
+as filtered: it reaches neither the judge nor a worker. `gh-api.ts` talks to GitHub through the `gh` CLI, so the
+credentials stay in the operator's keyring; every call is asynchronous, issue and pull-request lists are
+paginated, and comments are read forward from the cursor.
+
+**Pull requests: `pulls.ts`.** A report may name the pull requests its work opened. The executor hands
+them to the router before the engine reads the report, and the router binds each one to the ticket with
+the engine's `bindThread`, so a *ready* report waits for it instead of completing the ticket. Each poll,
+the follower asks GitHub about every followed pull request that is no longer open in the watched
+repository and reports the merge or close through `threadClosed`, which ends the ticket. A pull request
+in another repository is read every two minutes, and its comments and reviews become triggers on its own
+thread, `owner/repo#N`, with the read position committed once the engine holds them.
+
+**The judge: `assessor.ts` and `judge.ts`.** The engine's policy gate, defined in `router.ts`, admits a
+trigger only from a person who is not on the bot list. That check is code, not a model call. An admitted
+trigger becomes a candidate: the thread, its messages, the tickets already on it, and a link to the
+issue. The assessor sends candidates to the judge one at a time. The judge is a headless pi session with
+no extensions, skills or context files and a single tool, `ticket_decide`. If the judge accepts a thread
+that already has an open ticket, the router overrules it: that thread's messages belong to its worker.
+
+**Workers: `executor.ts`, `herdr-workers.ts` and `worker-role.ts`.** Each running assignment gets one
+worker, a pi session that herdr starts in a new tab, in a workspace of its own. Router and worker talk
+through files in `workers/<session>/`: inputs land in `inbox/`, and the worker appends events and reports
+to `events.jsonl` and `reports.jsonl`. The files and the tab outlive the router, which is why a restart
+adopts workers rather than replacing them. Inside the worker, `worker-role.ts` registers `ticket_report`
+and the guard from `workspace.ts`: no delegation tools, no blocked commands, no writes outside the
+workspace. It also files any run that ends without a report as a failure: only the worker process knows
+the order of its own events, so only it can tell for certain. A crash frees the worker's slot at once, and
+the router answers the ticket's first crash with the engine's retry: a fresh worker, told what happened. Only workers on a run count against the cap: a worker between runs is parked, keeping its
+session for follow-ups while its slot goes to the queue. A finished worker's tab lingers for ten minutes
+of follow-up and closes once its pi sits idle, checked again every ten minutes while it is busy. At startup the router also closes worker tabs that no record owns or whose agent herdr no longer
+knows.
+
+**GitHub out: `outbox.ts` and `receipts.ts`.** Every way a run ends (a report, a question, a crash, a run
+with no report, a launch that fails) becomes a message on the thread that says what happened and what the
+person can do next; `receipts.ts` holds the wording. Acknowledgements, receipts and notices are queued
+under ids, and an id is never queued twice: a launch that fails on every poll posts once. A message counts as sent only once GitHub accepts it; a failed post stays pending for
+the next pass. Every comment ends with an invisible marker, `<!-- superagent -->`, which lets the source
+recognize the agent's writing even when the agent and the operator share one GitHub account. Sent entries
+are pruned after 30 days.
+
+**The panel: `server.ts`.** A page and a small JSON API on 127.0.0.1, port 8788 by default, computed
+from the engine's store on every request, so the page can show no count the API would deny. It refuses
+any Host header other than 127.0.0.1 or localhost, and any API call without `x-superagent-request: 1`,
+so a web page elsewhere cannot read or steer it. If the port is taken, the panel binds a free one and logs
+which; it never takes the router down.
+
+**The start script: `scripts/superagent`.** Starts the router as a pi agent in a herdr tab, stops it, and
+reports its health as an exit code: 0 healthy, 1 down, 2 a part is failing, 3 waiting for setup. The
+launchd job in `launchd/` runs it every five minutes, restarts a router that is down, and leaves alone a
+router that was stopped on purpose.
+
+## The state directory
+
+Everything the system knows lives in one directory, `~/.pi/superagent` unless `PI_SUPERAGENT_STATE` says
+otherwise.
+
+| 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. The next first look treats every open issue 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 |
+| Issues older than the router fire nothing | 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 |
+| A stranger reaches neither the judge nor 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 |