pi-superagent 0.0.0-stage → 0.1.0

package/docs/design-decisions.md

@@ -0,0 +1,230 @@
+# Design decisions
+
+Each section states a rule the system keeps and the failure that taught it. Where each rule lives is
+mapped in [architecture.md](architecture.md); the proofs are in [formal-verification.md](formal-verification.md).
+
+## GitHub is the only way in
+
+Every request arrives as an issue, a comment or a review on one repository. There is no command-line
+submission, no board and no label vocabulary.
+
+Each extra door grows its own answers to "is this a person?" and "is this addressed to me?", and the
+agent's behavior then depends on which door a request happened to use. With one door, the identity rules
+live in one file (`source-github.ts`), and who is heard and who may start work in two functions
+(`scopeOf` and `policyOf` in `router.ts`).
+
+## Only people with write access are heard
+
+The router hears an author only when GitHub says they can write to the repository: the OWNER, MEMBER and
+COLLABORATOR author associations. Anyone else's issue, comment or review is stored as filtered and goes no
+further: no judgement, no ticket, no input to a running worker. `PI_SUPERAGENT_ALLOWED` replaces the rule
+with a list of logins.
+
+On a public repository anyone can open an issue, and an accepted issue starts a worker with a shell on
+the operator's machine. The judge cannot be that boundary, since a stranger's request reads like the
+owner's. The admission gate cannot either: a comment on an issue that already has a ticket goes straight
+to its worker and is never admitted again. So the check sits at the source scope, the engine's first step,
+where it covers every way in. An author whose association is missing counts as having none.
+
+## The first look is silent
+
+The first time the source sees a repository, it records every open issue and fires none of them. Only
+issues opened afterward are requests.
+
+The first version, pointed at a repository with a backlog, fired every open issue at once. A backlog is
+history, not a queue of fresh requests. Closing and reopening an issue, though, is a person saying "go
+again": a closed issue leaves the seen set and fires when it returns, under a new trigger id, because the
+id includes the issue's last update. The review cursor seeds the same way. (`Intake.tla` C1, C2.)
+
+## Read positions commit late; seeds commit at once
+
+A poll stages its read positions, and they commit at the start of the next poll, once the engine holds
+every trigger they produced.
+
+Committing at the moment of reading leaves a window: if the process dies between reading a comment and
+handing it to the engine, the saved position already points past a request the engine never saw, and
+that request is gone. A position that commits late can only cause a replay, and replays are free because
+the engine accepts each trigger id once. A seed is the mirror image: losing one would replay the backlog,
+and a seed can never swallow a request, so it commits immediately. The model checker found the early
+commit in shipped code; the fix ships with the counterexample as a regression test. (`Intake.tla` C3, C6.)
+
+## Code admits; the model judges
+
+A policy gate in code admits a trigger only from a person who is not on the bot list. Only then does
+the judge see it. When the judge accepts a thread that already has an open ticket, the router overrules
+it and records an ignore.
+
+A model's verdicts wobble; the deterministic layer keeps a wobble from turning bot traffic, the agent's
+own comments or a duplicate into work. Both checks were learned. A trigger stored before bot names were
+matched as patterns still said "human", and an agent asking the operator to approve a test became a ticket
+to run it; the gate now checks the author again. And the judge once opened a second ticket on a thread
+whose first ticket was right there in its prompt.
+
+## The judge works alone, one question at a time
+
+Judgements go to a headless pi session that loads no extensions, skills or context files, never to the
+operator's own pane, and the assessor hands it one candidate per turn.
+
+Judging in the operator's pane made the pane look frozen for every model turn. Sending candidates in a
+burst was worse: 41 of them steered into one running turn came back out of order, and the tail expired
+unanswered. The judge is also opened once and shared: opening a session takes 20 to 45 seconds, and
+before that rule every eval arriving in the window opened its own.
+
+## Workers report through a tool, never in prose
+
+A worker ends its assignment by calling `ticket_report` with a state: ready, blocked, failed or
+cancelled. Only *ready* completes a ticket.
+
+A model that says "done" in prose while having done nothing must be unable to complete anything. In the
+lifecycle model, completing without a *ready* report is not merely untested but unreachable
+(`Ticket.tla` I2). A run that ends without a report completes nothing either: the worker files it as a
+failure, and the person hears about it on the thread.
+
+## Every ending reaches the thread
+
+Whatever ends a worker's run is posted on the issue: its report, its question, a crash, a run that ended
+without a report, a launch that never got going. Each message says what happened and what the person can
+do next. The one exception is the 15-minute quiet flag, which stays on the panel: a long build is not news.
+
+The person who asked is on GitHub, not on the panel. An ending they cannot see is a request that died in
+silence, and a question they cannot see is a worker waiting forever. The same ending posts once per
+assignment, so a launch that fails on every poll says so once, not every 30 seconds.
+
+## A worker is fenced in
+
+Inside a worker, a guard refuses delegation tools, refuses blocked commands, and refuses writes outside
+the ticket's workspace. The workspace's setup script, which runs before pi does, meets the blocked
+commands as refusing shims first on its PATH. The brief also tells the worker that the machine is shared.
+
+Delegated work leaves the mandate, the workspace and the report behind. Blocked commands are the
+operator's personal tools (`gh`, for instance), and the operator's identity is not the worker's to use.
+The shared-machine brief exists because workers run side by side with each other and with people:
+sequential builds, bounded parallel jobs, and no process left running after the report.
+
+## A crash gets one fresh worker, not a loop
+
+When a worker crashes, the router retries the ticket once on its own, through the engine's retry. The
+crashed attempt ends on record, the comments it never read go to the new worker, and the new worker's brief
+says what happened, because the old one's changes are still in the workspace. A second crash on the same
+ticket waits for a person. Either way, the crashed worker's slot is freed at once.
+
+A lost tab or a killed process is usually bad luck, and one retry rides it out without waking anyone. A
+worker that crashes every time is a bug, and looping on it would open a new tab every few seconds while
+hiding the problem. One retry per ticket per router process is the same bound that startup recovery uses,
+and the lifecycle model already covers it: `Ticket.tla` lets a retry happen at any moment after a failed
+report.
+
+## A person's stop is final
+
+Once a person stops a ticket, nothing revives it: no new message, no wake-up, no retry. A request made
+again becomes a new ticket.
+
+A stop is a person saying "not now". An agent that resumes what it was told to stop teaches everyone that
+their words do not count. (`Ticket.tla` I1.)
+
+## A closed conversation stops its ticket
+
+GitHub ends a conversation in three ways: a merge closes the issue it names, a close says no, and a
+deletion says never mind. All three look the same from a poll, because the thread leaves the set of open
+issues and pull requests. The router then stops the ticket with a person's stop, posts one notice on the
+thread, and stays quiet until the issue is reopened. A ticket that follows its own pull request is the
+exception: that pull request's merge or close ends it, as merged or as closed, not as a stop.
+
+Closing the issue is the one stop that needs no tool and no knowledge of the system. Tickets on threads
+from other sources are left alone: the router can only tell whether a GitHub thread is open.
+
+## Work that changes a repository ends with its pull request
+
+A worker whose work changes a repository opens a pull request and names it in `ticket_report`. The router
+binds the pull request to the ticket before the engine reads the report, so *ready* then means awaiting
+review rather than done. Comments and reviews on the pull request go to the worker. The merge ends the
+ticket as merged, a close ends it as closed, and the router says which on the issue. A report that names
+no pull request ends the ticket as before.
+
+The work decides, not the request. A deployment, an answer or an investigation changes no repository, and a
+ticket made to wait for a pull request would never end; the worker knows by the end of its run whether it
+opened one. The worker opens it, not the router, because the worker knows which repository the work
+belongs in: the watched repository is often only where people ask. Only a pull request URL counts, since
+`#5` may be an issue, and a ticket bound to an issue would wait for a merge that never comes. The binding
+comes first because the engine completes a ticket on a *ready* report unless it already follows an open
+pull request. The lifecycle itself is the vendored engine's (`bindThread`, `threadClosed`, and upstream's
+`docs/003-execution.md`); the router feeds it facts.
+
+The watched repository's pull requests cost nothing extra: their comments and reviews arrive with every
+poll. One in another repository is read every two minutes, three calls each time, so a dozen open reviews
+stay well inside GitHub's hourly limit.
+
+## A review is a request; opening a pull request is not
+
+A submitted review, whether it requests changes or approves, is a person speaking about delivered work,
+on a conversation the ticket already owns. It fires a fresh judgement, and the reply lands in the pull
+request's own conversation (on GitHub a pull request is also issue N, so no second address is needed).
+
+Opening a pull request is a delivery, not a request. Treating every opening as a trigger would make the
+agent a mandatory reviewer of its own output, a loop that feeds itself.
+
+## Only work holds a slot
+
+The cap counts workers on a run. A worker between runs, waiting on a person's answer or simply done, is
+parked: it keeps its session and its context, and its slot goes to the next ticket in the queue. A reply
+puts it back on a run, even past the cap for a while.
+
+A slot is the machine's capacity, and an idle session uses almost none of it. When every live worker held
+a slot, a queue of 22 tickets waited while one of the four slots belonged to a worker that had finished its
+run without saying so.
+
+## A tab is closed only when nobody is in it
+
+A finished worker's tab stays open for ten minutes of follow-up and then closes only if its pi sits idle;
+while the agent is busy, the router looks again every ten minutes instead of giving up.
+The startup sweep closes a worker tab only when no record owns it or herdr no longer knows its agent.
+
+Worker tabs do outlive their purpose: a restart adopts a worker, a stop starts a newer one, and the older
+tab stays behind, so a sweep has to exist. But herdr has no guarded close, and a tab is someone's
+terminal. The liveness check is the single guard that keeps the sweep away from an agent that is still
+working. (`Workers.tla` W2, W4, W5.)
+
+## One router, one store, one state directory
+
+One router runs at a time, and one process holds the engine. The store is synchronous SQLite, and
+everything the system knows lives in one directory.
+
+The engine's commands are atomic only if the store is synchronous: an asynchronous driver would turn that
+atomicity into a comment. One directory makes the crash model concrete. A restart is "start again with
+this directory", which is exactly what the specifications model. One router per process matters too: the
+judge and every worker load this same extension, and each of them used to boot a router of its own.
+
+## Health is an exit code
+
+`superagent status` answers with a number: 0 healthy, 1 down, 2 a part is failing, 3 waiting for setup.
+A router that fails three polls in a row reports its GitHub source as failing.
+
+A scheduled check should act without reading prose, and each code has one remedy: a restart may fix 1
+and fixes neither 2 nor 3. A router that cannot reach GitHub otherwise looks healthy forever, answering
+nothing.
+
+## The panel is local and cannot be steered from a web page
+
+The panel binds 127.0.0.1, refuses any Host header but 127.0.0.1 and localhost, and serves its API only
+to callers that send `x-superagent-request: 1`.
+
+A browser will not let another site forge either one. Without them, any page you visit could read the
+queue, or pause the engine, by rebinding a hostname to localhost.
+
+## The engine stays byte-identical to upstream
+
+`src/core/` and its test suite are vendored from upstream and never edited. Every adaptation, from the
+judge's prompt to the GitHub shapes, lives in `src/pi/`.
+
+The engine is the part the lifecycle specification models and upstream maintains. Untouched, an upstream
+fix can be re-vendored by copying, and the specification keeps describing the code that runs. The
+[adaptation ledger](../ADAPTATION.md) says how to prove the copy is exact.
+
+## The specifications live beside the code
+
+`formal/` holds three TLA+ specifications, and `scripts/check-formal` checks all of them exhaustively in
+about five minutes. Every action names the function it mirrors; every header states what the model
+leaves out.
+
+A proof that cannot be re-run in one command rots. These are cheap to keep honest, and they have paid:
+the intake specification found a request-losing bug in shipped code.

package/docs/formal-verification.md

@@ -0,0 +1,106 @@
+# Formal verification
+
+Three parts of pi-superagent, the places where a bad ordering would quietly lose or duplicate work, are
+specified in TLA+ and checked exhaustively by TLC, the TLA+ model checker:
+
+| Specification | Models | States explored (distinct) | Claims |
+| --- | --- | --- | --- |
+| [`Ticket.tla`](../formal/Ticket.tla) | the engine's ticket lifecycle (`src/core`) | 12,325,891 (1,398,882) | 7 |
+| [`Intake.tla`](../formal/Intake.tla) | the GitHub source (`source-github.ts`) | 565,551 (113,281) | 6 |
+| [`Workers.tla`](../formal/Workers.tla) | worker records, tabs and agents (`herdr-workers.ts`) | 347 (94) | 5 |
+
+Every claim holds in every reachable state. The specifications have already paid for themselves: the
+intake model found a bug in shipped code, a read position saved before the engine held its triggers, so
+that a crash at the wrong moment lost a request for good. TLC printed the exact interleaving, and the fix
+shipped with that interleaving as a regression test. Along the way TLC also caught two mistakes in the
+models themselves (a dropped evaluation batch, and a stopped ticket brought back to life), which is
+exactly what a checker is for.
+
+## Running the checks
+
+```sh
+scripts/check-formal    # all three specifications, about five minutes
+```
+
+The script needs a JDK (`brew install openjdk`, or point `JAVA` at one) and downloads `tla2tools.jar` to
+`~/.cache/tla2tools/` on first use. It exits 0 only when every specification is checked to completion. A
+missing JDK, a parse error, a violated claim or a truncated run each exits 1 with a short reason: a check
+that stays silent is treated as a failed one.
+
+## What each specification proves
+
+### `Ticket.tla`: the ticket lifecycle
+
+- **I1 StopAbsorbing.** A ticket a person stopped is never live again.
+- **I2 DoneFromReady.** A completed ticket always has a *ready* report, so completing without one is
+  unreachable, not merely untested.
+- **I3 OneRunning.** A ticket has at most one running assignment.
+- **I4 NoSecondTicket.** No ticket is created for a thread that a live ticket already follows, in any
+  interleaving, including a follow-up that arrives in the middle of an evaluation.
+- **I5 OutboxOnce and I6 SentMonotonic.** Each acknowledgement is queued at most once and sent at most
+  once, and a sent message stays sent.
+- **LT_Delivered.** Under the stated fairness, every incoming message eventually reaches intake: intake
+  never stalls.
+
+### `Intake.tla`: the GitHub source
+
+- **C1 SeedSilence.** An issue that was open at the first look is never accepted unless it is closed and
+  reopened.
+- **C2 ReopenOnce.** An issue fires at most one request per open interval.
+- **C3 NoGhostCommit.** The committed read position never passes a comment the engine has not accepted.
+  This is the claim that found the bug: commit at read time, and TLC produces a crash that loses a request.
+- **C4 NoDoubleAccept.** Acceptance is by id and permanent: a replayed trigger adds nothing, and nothing
+  accepted is ever lost.
+- **C5 BotNeverHuman.** A bot's comment is never accepted as a person's.
+- **C6 NoLoss.** Through a crash, every posted comment is eventually accepted, and every issue opened
+  after the first look eventually fires.
+
+### `Workers.tla`: tabs, records and the sweep
+
+- **W1 OneLive.** A ticket has at most one live worker.
+- **W2 SweepKeepsLiveAgents and W4 NoTabLossUnderWork.** A worker whose record is live and whose agent is
+  alive always keeps its tab. The sweep's liveness check makes this an invariant rather than a race.
+- **W3 NoResurrect.** A record only moves forward, from free to live to ended, and returns to free only
+  when it is retired. An ended record never becomes live again.
+- **W5 ZombieTabsGone.** After any finite number of launches, every dead agent's tab is eventually closed:
+  the workspace cannot fill up with abandoned tabs.
+
+## Why the results mean something
+
+**Each action mirrors real code.** Every action in a specification names the function whose guards it
+copies. When that function changes, the action must change with it, and the check must run again.
+
+**Each header says what the model leaves out.** Leaving behavior out narrows what a claim covers. A claim
+holds for the behaviors the model includes, and for a left-out feature only as far as that feature's code
+passes through the same guards. For example, every path that could resume a ticket checks the same
+`ended.by === 'human'` guard that I1 relies on. The headers list what is missing so that a reader can
+check this for themselves.
+
+**The bounds are small on purpose.** Two threads, two ticket slots and four messages; two issues, two
+comments and one crash; two workers and three launches. Small bounds let TLC visit every state in
+minutes, and ordering bugs almost always show up at small sizes. They are still bounds, not a proof for
+every size, and each header states its own.
+
+**Liveness rests on stated fairness.** The "eventually" claims (LT_Delivered, C6, W5) assume that an
+action which stays enabled eventually happens. Each specification writes its fairness assumptions down,
+next to the claims, so they can be argued with. Crashes and launches are bounded, so "eventually" always
+has an end.
+
+**Lessons from TLC, so you can skip them.** A property with primed variables (`[][...]_vars`) goes under
+`PROPERTY`, never `INVARIANT`. `UNCHANGED` takes a tuple `<<...>>`, not a set. An action that assigns
+`x'` must not also list `x` in its `UNCHANGED`: the contradiction silently disables the action, and only
+`-coverage 1` will show it. A specification whose runs can finish needs an explicit stuttering step
+(`Terminate == UNCHANGED vars`), or TLC reports every finished run as a deadlock; stuck work is then
+caught by the liveness claims. And naming a state `open` broke the parse, which is why the intake model
+says `opened`.
+
+## What the proofs do not say
+
+A model proves things about the model. These cover the control flow described above, not the judge's
+decisions, GitHub's behavior (status codes, rate limits, pagination), SQLite, herdr, or the network.
+Newer behavior is tested but not modeled: reviews, the stop on a closed conversation, the outbox's check
+before a retry, and how each way a worker's run ends reaches the thread.
+
+What the specifications do guarantee: no implementation that follows these transitions can reach a
+forbidden state, and the liveness claims hold under the stated fairness. When the code a specification
+mirrors changes, upstream's ticket transitions included, the specification must change with it.

package/docs/operator-guide.md

@@ -0,0 +1,137 @@
+# Operator guide
+
+Everything you need to ask for work, watch it happen, and set it right when it goes wrong.
+
+## Asking for work
+
+Open an issue on the watched repository (`PI_SUPERAGENT_GITHUB_REPO`) and say plainly what you want
+done:
+
+```
+Title: Rename the Export button to "Ship"
+Body:  The primary button in the header should say Ship instead of Export. Keep the keyboard shortcut.
+```
+
+Within about a minute the judge's acknowledgement appears on the issue, and a tab named for the issue
+opens in the `superagent` herdr workspace with the worker inside. When the worker finishes, its report
+arrives on the issue as a reply.
+
+The judge accepts a concrete action someone asks the agent to take, even one that calls itself a test.
+It ignores chatter, notes addressed to other people, and new requests on a thread that already has an
+open ticket. An ignore posts nothing on the issue; the reason is in the engine log.
+
+- **Who can ask.** People with write access to the repository: its owner, members of the organization
+  that owns it, and collaborators. Anyone else's issues, comments and reviews are dropped before the judge
+  sees them, and the panel counts them as filtered. To hear someone else, add them as a collaborator. To
+  hear fewer people, list the logins in `PI_SUPERAGENT_ALLOWED`; the list then replaces the rule.
+- **Follow-ups.** Comment on the same issue. While its ticket is open, your comments go straight to its
+  worker.
+- **Pull requests.** When the work changes a repository, the worker opens a pull request and names it in
+  its report, and the receipt on the issue links it. The ticket then waits for review, shown on the panel
+  as `review of #N`: your comments and reviews on the pull request go to the same worker. Merge it, and
+  the ticket ends and the issue says it is done. Close it unmerged, and the ticket ends too; a comment on
+  the issue starts the work again. A pull request in another repository works the same way, checked every
+  two minutes. A request that changes no repository, such as a question, an investigation or an
+  operation, ends with its report.
+- **Who opens the pull request.** The worker, with the `gh` on this machine, so the pull request's author
+  is whoever `gh` is signed in as. Blocking `gh` for workers (`PI_SUPERAGENT_BLOCKED`) turns pull requests
+  off: workers then report without one.
+- **The agent's own account.** By default the router reads and replies as the account `gh` is signed in
+  as, so its comments look like yours apart from a hidden marker. To give it an account of its own, put a
+  token for that account in a file only you can read, set `PI_SUPERAGENT_GITHUB_TOKEN_FILE` to the file
+  and `PI_SUPERAGENT_GITHUB_SELF` to the account's login, give the account access to the watched
+  repository, and restart. The engine log's `router.start` line then says `githubAs="token file"`.
+  Workers still act as `gh`'s account, so their pull requests are yours, and the router reads those pull
+  requests as that account too.
+- **Pull requests no ticket opened.** A comment or a submitted review on one reaches the judge like any
+  other request, and the answer lands in the pull request's conversation.
+- **Questions from a worker.** A worker that needs you reports *blocked* with one question. The question
+  is posted on the issue (and listed on the panel under *Needs a person*); answer it with a comment.
+- **Stopping.** Close the issue. Within one poll the ticket stops and says so on the thread. A ticket
+  waiting on its own pull request ends with that pull request instead, as above. Reopen the issue to run the request again. Without GitHub, the panel
+  API stops a ticket too:
+  `curl -X POST -H 'x-superagent-request: 1' http://127.0.0.1:8788/api/tickets/<id>/stop`.
+
+## Watching
+
+- **The herdr workspace `superagent`.** The `engine log` tab streams every poll, judgement, launch and
+  receipt. Each worker has its own tab, labelled `#<issue> · <title>`; it is an ordinary pi session, so
+  you can read along, type into it, or press Esc to interrupt it.
+- **The panel** at <http://127.0.0.1:8788/>. It shows what needs a person, what is running and queued,
+  and what the judge decided.
+- **The log itself:** `tail -F ~/.pi/superagent/engine.log`. Each line is one event with its fields, so
+  `grep eval.decided` lists every judgement with its reason.
+
+## Running it
+
+```sh
+superagent status    # 0 healthy · 1 down · 2 a part is failing · 3 waiting for setup
+superagent restart   # safe at any time: workers keep running and the new router adopts them
+superagent stop      # leaves a marker, so the health check will not restart it
+superagent start     # clears the marker
+```
+
+In a checkout, the same script is `scripts/superagent`.
+
+Settings live in `~/.pi/superagent/config.env`. [`config.example.env`](../config.example.env), shipped
+with the package, explains each setting and its default. Restart to apply a change.
+
+On macOS, the launchd job in [`launchd/`](../launchd/com.example.superagent-health.plist) runs `status`
+every five minutes and starts a router that is down. It leaves a deliberately stopped router alone.
+Install it once:
+
+```sh
+plist="$(npm root -g)/pi-superagent/launchd/com.example.superagent-health.plist"   # launchd/ in a checkout
+sed "s|__HOME__|$HOME|g" "$plist" > ~/Library/LaunchAgents/com.example.superagent-health.plist
+launchctl load ~/Library/LaunchAgents/com.example.superagent-health.plist
+```
+
+The job finds `superagent`, `pi` and `herdr` on its own PATH: Homebrew's directories, `/usr/local/bin` and
+`~/.npm-global/bin`. If `command -v superagent` or `command -v pi` prints a directory outside those, as nvm's
+do, add it to the job's PATH. From a checkout, replace `superagent` in the job with the script's full path.
+
+## Capacity
+
+Up to four workers can be on a run at once (`PI_SUPERAGENT_MAX_WORKERS`); further tickets wait their
+turn, queued on the panel. A worker between runs, waiting on your answer or simply done, is *parked*: it
+keeps its tab and everything it knows, but gives up its slot, so the queue keeps moving. A reply puts it
+back on a run. The judge answers one request at a time. Every worker's brief says the machine is shared:
+sequential builds, bounded parallel jobs, nothing left running after the report.
+
+A worker on a run that emits nothing for 15 minutes is flagged on the panel, and only there, under *Needs a
+person*: steer it, stop it, or accept its work. The flag does not stop the worker. If it is only running a
+long build, let it be; the flag clears when the worker reports.
+
+## When something goes wrong
+
+**No acknowledgement after a few minutes.** Run `status` first. Then
+`grep eval.decided ~/.pi/superagent/engine.log | tail`: `kind=ignore` comes with the judge's reason, and a
+clearer comment or a reopened issue asks again. A `judge.prompt` line with no `eval.decided` after it
+means the judge is wedged; `restart` fixes it.
+
+**Someone else's issue gets no acknowledgement.** Check that they can write to the repository, or that
+their login is in `PI_SUPERAGENT_ALLOWED` when that is set. The panel's count of filtered triggers rises
+by one for each request it dropped this way.
+
+**A ticket stays open after its worker reported ready.** It is waiting for its pull request: the panel
+shows `review of #N`. Merge or close the pull request; the ticket ends within one poll, or within two
+minutes for a pull request in another repository.
+
+**`status` exits 2.** Read `~/.pi/superagent/health.json`. A failing `source` means the router cannot
+reach GitHub; check `gh auth status`. The error clears on the next good poll.
+
+**`status` exits 3.** Read `~/.pi/superagent/setup.json`: it names what is missing and where to fix it.
+
+**A worker looks stuck.** Open its tab and read it. Type into it to steer, or press Esc to interrupt.
+
+**The issue says the worker stopped without reporting a result.** It ended a run without calling
+`ticket_report`, so whatever it concluded is still in its tab. The worker is still open: a reply on the
+issue steers it, and closing the issue drops the ticket.
+
+**The issue says the worker crashed.** The router has already started a fresh worker on it, once, and the
+new worker's brief says what happened. If the issue says the fresh worker crashed too, nothing runs the
+ticket until `superagent restart`, and closing the issue drops it.
+
+**The issue says a worker could not start.** The notice quotes the error, usually from the setup script
+(`PI_SUPERAGENT_PREPARE`). The router retries on every poll, without posting again, until the cause is
+fixed or the issue is closed.

package/formal/Intake.cfg

@@ -0,0 +1,18 @@
+CONSTANTS
+  i1 = "i1"
+  i2 = "i2"
+  c1 = "c1"
+  c2 = "c2"
+
+SPECIFICATION Spec
+
+INVARIANT
+  TypeOK
+  C1_SeedSilence
+  C2_ReopenOnce
+  C5_BotNeverHuman
+
+PROPERTY
+  C3_NoGhostCommit
+  C4_NoDoubleAccept
+  C6_NoLoss