The wsp skill

What wsp mcp install --agent <id> puts into an agent's skills folder, word for word, so the agent reads it before it opens a thread, sets a person up or forks a machine.

A project is a folder on one computer, a git repo or not, recorded with wsp add, and coding agents work on it as threads. On the computer the app runs on a thread runs in the project's folder itself, beside any other thread there, on the agents already on its PATH; a thread on another branch runs in a worktree of the project's repo, the one git already has that branch checked out in or one wsp makes under its own folder with the project's .env files and installed dependencies carried in. On a box the person joined a thread runs in the project's folder there the same way. The host on the person's computer (the service the desktop app installs, or the first command line that needs one, which starts it) owns the threads and the keys; the wsp command line and the wsp MCP server are thin clients of that same host, so whatever you do here shows in the person's sidebar and they can read and answer any thread. Start with wsp projects to see the projects and wsp threads to see the threads in them, each with its folder and branch. Open a thread with run, giving the project, the message and the agent to run, and --branch for a worktree on another branch; from a thread, run with no project runs beside you in your folder. It returns the reply as soon as the agent gives it, and the thread reads running until the agent process exits. Continue a thread with send, which is also how one thread talks to another, by that thread's id off threads: a send is never refused for meeting a turn, it joins a running turn where the agent takes a message mid-turn and otherwise runs as that thread's next turn, and the answer comes back as its own message when the other thread's start named you. A thread reaches every thread of its own tree, the lead that started it, the threads beside it under that lead and the threads it started, wherever each runs, and nothing else: the person's own thread and another lead's tree in the same folder are left out of threads, a send into either reads as no such thread, and work that has to cross to them goes through the person. Stopping a thread stops every thread under it, so a child that stops its lead stops its siblings and itself with it. Both take detach, which answers with the thread id the moment the turn is started and leaves the reply to the thread's finished line. Which road you take for that line is decided by whether you are a wsp thread yourself, which the launch environment says: a thread starts every child with --notify me and ends its turn, and the child's finished line, carrying its whole report, wakes it as a message; a caller that is not a thread takes the reply of one turn as run or send returns it, and for more than one turn at a time starts one coordinator thread in the project's folder on this computer with the whole job and hands off, telling the person where to read it. stop ends a thread's running turn; wsp worktree <project> <branch> answers a worktree's path to work in by path; run a command in the folder a thread works in with exec; delete takes a thread away with its turns. An agent that wants a pull request runs git push and gh pr create itself. Setting someone up from nothing is its own sequence, and the next section is that sequence: a health check, then recipe_scan, which writes nothing and gives every row a recommended value with one line of why, so you apply those and put only the rows whose reason says worth a question, then recipe with their answers, then wsp init --recipe <path> --non-interactive --json from a shell, which builds their image and prints one JSON line per sign-in for you to hand to the person, since the sign-ins finish in their browser.

Setting a person up from nothing

Asked to set a person up, read this section before running a single verb: a verb's refusal is a branch in this list, not an answer to hand back. The road is a health check, then wsp recipe scan, which prints every option and writes nothing, then two questions to them, the heavy rows with their sizes and the sign-ins with their default choice, then wsp recipe --tick used with their answers, which writes the recipe, then wsp init --recipe ~/.wsp/recipe.json --non-interactive --json, which you run detached from a shell: it builds their image and prints one JSON line per sign-in, the page and the code the person finishes in their own browser, and waits for them, then wsp add for the project and wsp run <project> for the first thread. Two things are theirs and never yours: the sign-ins, which no tool can finish for them, and the keys, which live in their .env and are never typed into your terminal or read back to them. Starting the host is neither: any command that needs one starts it, and it reads those keys off the file itself, so nothing about them passes through you. Every step below ends in an Expect: line; run the command, read that line, and stop at the first one that does not match rather than carrying on. Read where they already are before running anything, and skip the steps that state has passed.

1. The health check comes before any verb: wsp --version. With no wsp on the path and a shell of your own, npm i -g @wsp-labs/wsp puts the wsp command there; prefer that over npx @wsp-labs/wsp, whose cache write fails under a sandboxed agent and leaves every command after it running with the sandbox off. Then wsp threads --json. A host is what answers it, and when none serves that state file this command starts one and waits for it, so there is nothing to start by hand. (wsp doctor is not this check: it forks a live machine to prove the whole reach path, it bills while it runs, and it does not speak JSON.)

   Expect: wsp <version>, then one JSON line on stdout, {"threads":[]} when nothing is running yet: go to step 6. A starting the host for <path>; its log is <path>, and wsp down stops it line on stderr before it means none was serving and this command started one, which is the ordinary road and not a failure to report. no host answered for <path> within 20.0s, with the log's last lines under it, means the host it started could not serve: read that log. A Threads on <name> run in <folder> on this computer, under your own sign-ins. line in it means the state held no image, so the host recorded that folder as a project and served that: go to step 3 to seal an image, or to step 7 when this computer is enough to start on. A command not found with no shell to install from is the one thing to say and stop on, because nothing below can be run for them.

2. The keys are the person's. Ask them to write ANTHROPIC_API_KEY=<key> into ~/.wsp/.env when they pay Anthropic by the token; on a Claude subscription they skip the Anthropic one and sign in on the machine during init instead. Do not ask them to paste a key into this conversation, do not print that file, and do not commit it. Then take the host that started without a key down with wsp down and run step 1 again, so the new host reads the file.

   Expect: wsp threads --json answers with one JSON line.

3. Read everything before writing anything: wsp recipe scan prints every option and writes no file. Five tables: the agents, with what each one's history on this computer says; the tools, each with why it is there (used 412 times in 37 sessions, installed here, never used, catalog default), its download size and, in the last column, what to do about it; what else a package manager on this computer has that the image could take, by manager, with the line that installs each and its size; the commands their agents ran that the catalog does not carry, with counts; and the sign-ins, each with the choice that would be taken by default. --json gives all of it as one object with a recommended value and reason on every row, which is the form to read when you are deciding rather than showing. --project <folder> weighs the histories by a folder, so a setup for one project counts that project's sessions first. Read the why and the size on every row instead of taking the defaults as given: they come from what their agents actually ran, not from what is installed, and an agent with no thread adapter stays off, which is right, since an image carries the agents that can run threads unless the person asks for another.

   Expect: the five tables on stdout, the agents and tools tables each ending in an On: line with the count and the total size, then Nothing was written. as the last line; wsp recipe scan --json answers with one object holding the same rows.

4. Put the two decisions to the person, each as one message, then write the recipe with their answers. First the heavy rows, over 300 MB, as one multiple-choice question with the size beside each and what the answer does to the total. Then the sign-ins, naming the default choice on each row and what the choices mean: copy it from this computer, sign in during the build, sign in when you first need it, hand it an API key, mint a token here that every turn gets, or skip it. Then write: wsp recipe --tick used, plus --set <id>=on|off for every row they flipped and for anything from the scan's own-computer table they want on the image, --add <id>="<install line>" only for a tool neither the catalog nor this computer has, --signin <id>=copy|machine|later|key|skip|token for every sign-in they chose, and --project <folder> when the setup is for one project, so that project's history weighs first. All of them repeat, all of them go in one call, and the file is never edited by hand.

   Three heavy ones are ticked because they are installed on your computer, and your agents never used them:
   Java 21 (620 MB), Gradle (410 MB), Android SDK (1.2 GB). Which do you want on the machines?
   (a) none of them, 3.4 GB down to 1.2 GB   (b) Java only   (c) all three, and the build takes longer
   

   plaintext

   Expect: the tables again with every flip in them and the total moved by their sizes, then Recipe written to <path>. opening the last line, ~/.wsp/recipe.json when the state file is the default one and a path beside their state file when it is not. That path is the one step 5 runs with.

5. Build their image. Run init yourself, detached, with the recipe step 4 wrote:

   nohup wsp init --recipe ~/.wsp/recipe.json --non-interactive --json > /tmp/wsp-init.jsonl 2> /tmp/wsp-init.log &
   

   plaintext

   The image is built on a computer of theirs that wsp add user@host joined, which --on <computer> names; with none joined this run builds nothing and records the folder it was run in as a project on this computer, the line step 1 quotes. It boots one builder machine, installs what is ticked, and at each sign-in the recipe answered machine it prints one JSON object on stdout and waits: {"event":"sign-in","tool":"gh","label":"GitHub CLI login","browserUrl":"https://github.com/login/device","code":"8F4A-C21B","nextCommand":"open 'https://github.com/login/device'","waitSeconds":960}. Hand that line to the person as it comes: the page to open on their computer, the code when there is one, and the command that opens the page. No thread and no tool can sign in for them; the run asks the tool's own status on the machine and moves on when it says signed in, or when waitSeconds pass. Read /tmp/wsp-init.jsonl as it grows rather than waiting on the process, which keeps serving the app after the seal. When the person would rather drive the wizard themselves, wsp init --recipe ~/.wsp/recipe.json in their own terminal draws six screens, Agents, Tools, Also on this computer, Sign-ins, wsp for your agents on this computer, and Build, of which the recipe has answered the first three, so their run opens on Sign-ins and ends on Build. A host already serving that state file stops none of this: the screens are the same and the build runs in that host, which records the image in the state it serves, so a box whose host is a service needs nothing taken down. That road refuses --json, since the build's objects then ride the host's own setup, which wsp setup --json reads; run init without --json beside a serving host, or take it down with wsp down first.

   Expect: one {"event":"sign-in-result","tool":"gh","label":"GitHub CLI login","state":"signed-in"} line per hand-off ("state":"not-signed-in" with a note saying why when the person did not finish in time; the run seals either way), then Image v<n> sealed. in the log, which is the seal, and Open http://127.0.0.1:4400/. A JSON line from wsp threads is not that proof: init serves a host for the whole wizard, before the sign-ins and the seal, so step 6 is what tells a sealed image from an init still running.

   When the person set up from the app instead, from its Settings, the same run is a job on their host: wsp setup --json answers with its phase, its rows and each sign-in with the page waiting for them, so hand an open one over as you would the line above, and never start a second init beside it.

6. Where threads run. On this computer nothing is made: a thread runs in the project's folder, and on a box you added in the project's folder there.

   Expect: wsp computers lists this computer and each box you added.

7. Record the project: wsp add <folder> for a folder on this computer, a git repo or not, a subfolder of a repo being a project of that repo; wsp add <url> --into <folder> for a repo cloned here into an empty folder, which is then that folder's project; wsp add <url> --on <computer> for a repo the computer clones, or wsp add <owner/repo> --on <computer> for one its signed-in gh or glab clones. wsp add <folder> --on <computer> is the fourth road: that computer clones the folder's own remote and the folder seeds what git ignores on top, so the line prints a menu of those paths with their sizes and sends nothing until --yes; the person picks with --keep <path>, --cut <path>, --no-memory and --no-commits, and --remember keeps their ticks for the next add of that folder.

   Expect: wsp projects lists it, with its folder and, for a folder here inside a git repo, the branches --branch takes.

8. First thread: wsp run <project> --notify me "<the first message>" runs it in the project's folder; --branch <branch> runs it in a worktree on that branch instead.

   Expect: thread <id> on <project> in <folder> as the first line on stdout, the reply on stdout when it is complete, and the same thread in the person's sidebar for them to answer. --notify me puts each later turn's reply in front of them, so nobody polls.

Last, say what to run next inside their own agent, which is where the work happens from here. wsp mcp install --agent <id> puts the tools and this skill into that agent (repeatable, and --json for a machine to read; the agents the catalog knows a config for are listed under the verbs below). The tools show up only after that agent restarts, and the wsp command line does the same job until then, so nothing waits on the restart. In Claude Code the skill is then /wsp; in any agent the line to paste is Use the wsp skill and open a thread on <project> that <the first message>.

Expect: that agent lists the wsp tools once it has restarted, run answers with a thread id, and that thread shows in the person's sidebar.

Verbs and tools

The command line and the MCP server call the same functions. Every verb takes --json (one JSON object per line, frames first, the last line the result; see the contract below) and --state <path> (the state file the host serves; default ~/.wsp/state.json, or ./.wsp/state.json in a checkout of wsp itself). A project is named by its name or its id, and a thread by its id or by a prefix that picks exactly one. Each tool's inputs are in the parentheses after its name; a flag on the command line is the input of the same name on the tool, --add-check being add_check, and a repeatable flag is an array.

The app's own roads

These stand behind the app's own screens rather than a page of the command line: they are still parsed, still served as tools, and wsp <verb> --help still answers for each.

The command line alone has wsp up, wsp down, wsp status, wsp init, wsp doctor, wsp mcp, wsp add for a project, a provider's key or the join code, wsp remove, wsp join, wsp leave, the four lines under the word host, wsp login, wsp logout, wsp hosts, wsp usage reset and the three sign-in lines, since each starts, stops, installs or hands out access to something on the person's computer, wsp usage reset spends a reset the person owns, the sign-ins run in a terminal a person types into: any command that needs the host starts one when none serves that state file, on a free port, saying so in one line on stderr with the log to read and the wsp down that stops it, so wsp up is only for a host somebody wants to watch or to serve beyond this computer. wsp up [--port <n>] [--listen <addr>] [--state <path>] serves the app and the runtime's WebSocket on one port and the host until it is stopped, so the terminal it runs in has to stay open; wsp up --service hands that same line to the computer's own service manager instead, a launchd agent on a Mac and a systemd user unit on Linux, which serves now and again at every login, and wsp down stops it and takes it away, as it stops a host a command started. wsp status prints whether a host is serving this state file, its port, its token file and what keeps it there, with a non-zero exit code when none does; wsp status --host <alias> reads that host instead, where it answers and whether it did, since what keeps it up is read on the computer it runs on. On a computer joined to somebody's wsp there is no host and never will be, so wsp status there reads the agent that join installed instead: which wsp the computer belongs to, whether that agent is answering and on which port, what the computer is doing right now (cpu, memory, disk), one row per machine it holds under those rows with the name and id that machine has on the host, what it was given, what it holds of that now, its uptime, its process count and the address it answers on, and the ten processes spending the most of the computer, exiting non-zero when nothing answers; wsp status --watch draws those same rows again every second where they stand until Ctrl-C, which needs a terminal. It is the one line that leaves this computer only when a host is named on it or in WSP_HOST: the account's one host and the host a turn's launch carries move every verb and not this one, since a bare wsp status asks whether the host here is serving and an alias answering for a box would hide that. wsp up --listen <addr> binds an address other than this computer's own, which is how a host on a box someone owns is reached from their laptop: the page is then served with no token in it and every browser redeems a one time code for a token of its own. wsp up --advertise <url> says the address a computer being joined dials the host at, which is the relay's name or what this computer answers on without it; a fork's turn dials nothing, its wsp rides its daemon. wsp up --service carries every one of these into the unit it installs, so the service serves the line that was typed and not a shorter one. wsp add is how a computer the person owns becomes a place in their wsp: with no argument it prints the wsp join line and a code to type on that computer, which is spent by the first join and stands for ten minutes; wsp add user@host [--name <name>] [--ssh-port <port>] [--ssh-key <path>] logs in over ssh as the person's own client would, installs the daemon on that box, starts it as a systemd system unit and waits for it to dial back, printing each step as it happens; the box is named after its hostname when no name is given. A bare alias from the person's ~/.ssh/config works in place of user@host: the add dials through that block, with its user and its port unless --ssh-port names another, and names the box after the alias up to its first dot. wsp remove <place> [--yes] [--force] [--json] takes a computer back out after one question: its forks are deleted and its projects leave this wsp with their threads, then the agent and its files come off it, and on a computer added over ssh so does /wsp, with the forks' copies, the project checkouts and the copy of the image in it (one joined with a code keeps /wsp, and so does one whose own wsp is older than this one, since wsp add <computer> --update moves its daemon alone), and the computer is otherwise left as wsp found it. A fork or a project folder there holding work no remote has (commits on any branch or HEAD no remote has, uncommitted files, stashes) stops it before the question, each named, a project folder by its path there: a push keeps a fork's, and --force removes them anyway. A computer that is not answering while forks or projects stand on it is refused until it answers. The answer is a summary by folder, at most a screen, and --json carries every line; on a box whose login's sudo asks for a password, the remove and wsp add <computer> --update over ssh ask for it once at a terminal, as the add does, and the app's Remove confirm asks in its own field; a place that was not connected keeps its agent and the line says to run wsp leave there. The other two run on the computer being joined, not on the host: wsp join <address>... --code <code> [--name <name>] dials those addresses in turn until one answers, proves a key it makes there, writes the place file and installs the agent as a systemd system unit, which needs root and dials again at every boot (a place is a Linux computer, so a Mac refuses to join), --code-file <path> reading the code off a file and deleting it first; the service runs the daemon binary itself, and wsp leave [--yes] [--force] [--takes <project folder>]... sweeps wsp off that computer for somebody whose host is gone: it asks once, and stops before anything goes where a fork's copy or a project checkout under /wsp holds work no remote has, naming each by its path, unless --force. Where /wsp stood before the add, it takes only wsp's own folders there and each project folder a --takes names, which a remove passes from the host's records. wsp host pair prints that code, when it expires and the addresses to open; it is the person's own terminal on the computer the host runs on, never a thread's, since handing out a code hands out the host, and aimed at a host somewhere else, by --host, by WSP_HOST or by the account's one host, it says in one line that it runs at that host's own terminal and dials nothing. wsp host devices lists the computers that took a code and what each token is read as (the owner's own browser, a paired device, a thread's token), and wsp host devices revoke <id> takes one back out; both take the host pick like every other verb, so wsp host devices --host box reads and cuts the devices of the box from a laptop signed in to the same account. wsp hosts is the one listing of the hosts on the person's account this computer can reach, with a live beat for each and the one every line takes marked. A box nobody can reach inbound takes the relay: wsp host link <url> puts the computer the host runs on onto the person's relay account, printing a code and a page they approve in their own browser, and from then on every wsp up there asks that relay for a tunnel, runs the connector against its own loopback port and prints public https://<hostname> once it has one, so nothing has to be open to the world; wsp up --no-relay serves without the tunnel, and wsp host unlink takes the computer off the account and stops it. The other side of it is on the person's own computer: wsp login signs that computer in to their account, printing one word to approve on a computer already in and a page to approve it on when none is, and wsp hosts then lists the boxes on the account and writes a record for each, so every verb reaches them by name with no code typed; the first dial at one proves the key this computer signs with, which the box was told to trust at its link, and takes a device token of its own. wsp login <word> on a computer already in signs the admission for the one waiting, wsp login <id> does the same for a computer already on the account, wsp login on its own lists the account's computers with who admitted each, and wsp logout signs this computer out while wsp logout <id> signs another out, which every box reads on its next beat. wsp host link on a computer that is already signed in puts the box on that account with no code and no page at all. Keys and tokens never pass through the relay: an admission is bytes one computer signed and the relay carries, and every box verifies it with keys of its own. Every verb then takes --host <alias> for one line, as wsp threads --host box does, and the WSP_HOST environment variable does the same for a whole shell; --state names a file on this computer, so it is not read for a host somewhere else and a line that gives both says so. With no host named, a line goes to the host serving the state file on this computer, and only when none does to the one host on the account. wsp init [--recipe <path>] [--non-interactive] [--json] [--yes] builds the image, --json printing each sign-in and its outcome as one object on stdout with everything else on stderr, --non-interactive doing the same in prose, and --yes taking every default and skipping the sign-ins, which is why --yes is refused beside --json; wsp doctor forks a live machine to prove the whole road end to end; wsp mcp [--host <alias>] [--scoped] serves the tools over stdio, against this computer's host or the one that alias names, and --scoped, which the host puts on a thread's own tools, makes a server whose launch pair is missing refuse rather than act as the person; wsp mcp install --agent <id> [--host <alias>] writes the server into that agent's own MCP config, with the alias in the command it registers when the tools are for a host on another computer, this skill into its skills folder, and wsp's own marked section into the instructions the folder it runs in keeps, AGENTS.md for every agent and CLAUDE.md beside it for Claude Code. A second run replaces that section where it stands, so there is only ever one and everything around it is untouched, a file whose end marker somebody deleted is repaired to that one section rather than given a second begin marker, and wsp mcp install --agent <id> --remove takes it back out, leaving the file's other lines byte for byte and the config and the skill where they are. --agent repeats to do several in one call, one failing id costing the others nothing, and off a terminal a run that names none takes every agent whose own command is on the PATH. --json answers with one line holding the server command every config now runs, what each agent took, its docs naming the files the section went into, and a failures array, a provider failure when that array is not empty. The prose ends on the one thing to do next, which is inside the agent that was just set up. The three sign-in lines are the person's: wsp agents signin opencode runs an agent's own sign-in on this computer in their terminal, wsp agents signin gemini <thread> where that thread runs, and a box they added takes wsp add spoo --sign-in codex, which runs a shared login at that box's logins folder and any other as the owner of its home; wsp servers signin notion --agent claude --on spoo runs the harness's own sign-in for one MCP server where it is set up; wsp agents key claude puts the token claude setup-token prints, or an agent's API key, into the host's vault, typed where nothing echoes it and only at the host's own terminal. Hand the person the line; never run one for them. An entry under installed with no path took the skill and not the server, which is the by-hand line the prose prints. Only agents the catalog knows an MCP config for get the server: claude, codex, gemini, opencode. The rest get the skill and a by-hand line.

For a shell script

One verb is a shell script's and not an agent's, because it blocks: a script that starts threads and has to stand at the end of them has nothing else to do while they run.

In your own conversation this is the wrong road: a blocked wait is minutes of your turn spent on nothing, and nothing can reach you while it runs. Start children with --notify me and end your turn instead when you are a thread, and hand a job of more than one turn to a coordinator thread when you are not; the two rules are the next section's.

Running work well

These decide whether work goes fast or stalls, and they hold wherever a thread runs.

• A wsp thread starts every child with --notify me and ends its turn, and each child's finished line wakes it with that child's whole report, so nothing is polled and no turn is spent waiting. The launch environment says whether you are a thread, and --notify me resolves to whichever thread the request came out of. Settle each child with wsp thread settle once its report is acted on; a finished child whose report you took reads as read, and settles by itself after the person's quiet time. Restart a stuck child with wsp stop and then wsp run --replaces <child>, so the person sees one row for the job, not two under one title.
• A caller that is not a wsp thread cannot be woken at all, so it takes the reply of one turn as the call returns, and hands work of more than one turn to a single coordinator thread in the project's folder on this computer, with the whole job in its brief and the person told where to read it.
• When the person asks for another agent, on another model or another harness, start it as a wsp thread with run, so it shows in their sidebar; your own subagent tool is for your own sub-steps.
• A thread may own one slate, a live panel on the right panel's Slate tab; slate_catalog lists what it can hold, slate_write writes one, and only a button the person presses reaches you.
• A thread on this computer runs in the project's folder, beside any other thread there, as panes in one terminal share a folder: put a quick subtask or a second harness there, since it starts in a second, costs nothing and runs the agents already on this computer's PATH over the person's own files and sessions. Work that needs a branch of its own goes in a worktree, wsp run <project> --branch <branch>, so two builders never edit one checkout.
• One heavy thread per machine: on 2 vCPU and 4 GB one thread runs tests or a build at a time and a second thread is a light send. Three test runs at once starve the machine and every turn in flight fails.
• A thread that builds gets its own git worktree, which is how two threads share one machine, and that worktree's setup is made cheap rather than skipped: pnpm's side-effects cache so a native module is compiled once per machine, and the checkout's node_modules hardlinked into the new worktree before pnpm install --offline, which then only verifies. A worktree set up from scratch relinks thousands of files and rebuilds native modules, minutes on 2 vCPU.
• Start long work with your harness's own background road, which wakes you when it ends, and never with a shell &, which nothing tracks and which wakes nobody when it ends.
• wsp send <thread> continues a thread that has already replied; a send into a thread whose turn is still running opens no second turn and is a mistake. Wait for the turn to end, or wsp stop <thread> first.
• Restarting the host cuts every turn running anywhere. Finish or stop the running turns before wsp down and wsp up.
• The person's app and the command line read the same host, so every thread opened here shows in their sidebar and they read its reply there. Name each one with --title and keep the reply short and complete.
• A command you mean the person to run goes in a fenced block labelled sh, which the app shows with Run: the person runs it with one click, in this thread's folder, and sees its output under the block.

The contract

The command line, the MCP tools and this skill are one contract: every capability exists in all three or in none, and the parity test in the repo holds them to it. With --json, stdout carries JSON alone: one JSON object per line, frames first, the last line is the result; a verb with no stream prints the result alone. The result is the object the MCP tool of the same name answers with, less what the frames already carried, so no line prints twice: wsp exec --json prints one exec.output frame per output line and then a result with the exit code and the folder; wsp add root@203.0.113.7 --recipe mine --json prints a {"setup": ...} frame per step line and a {"waiting": ...} frame per sign-in waiting on the person, then {"computer": ...}. Without --json, stdout is for a person. Progress, the waking line and every refusal go to stderr. A refusal or a failure is one line on stderr, the failure object {"error": "<the line>", "class": "usage", "exit": 3} under --json, and the exit code is the class's:

wsp exec is the one exception: its exit code is the command's own, and only a machine that could not run it is a provider failure. A person saying no to a confirmation is <name> kept on stderr with exit code 1. Every line that takes something away (wsp remove, wsp leave, wsp delete, wsp discard, wsp projects remove, wsp recipes remove, wsp skills remove, wsp servers remove, wsp worktree remove, wsp thread forget) asks that one question only once the host's own refusals pass, and off a terminal is refused without --yes. An MCP tool answers a failure as a tool error whose structured content is the same object, so class reads the same on both doors; a call whose inputs do not fit the tool's schema is refused by the server before the tool runs.

run

wsp projects                                       # every project, each on its computer; the name is what wsp run takes
wsp run spoo --notify me "Read ticket 308 ... and build it."
wsp run spoo --branch ticket/308 --notify me "Build ticket 308 on its own branch."
wsp run spoo --model claude-sonnet-5 --effort low --access ask "Review the branch ticket/308."
wsp run --agent codex "Say in one line which folder you are in and what is in it."

wsp run <project> opens a thread in the project's folder on this computer: it runs the agent already on this computer's PATH, keeps its session in the person's own agent folder, and nothing is copied, forked or woken for it; several threads share the folder as panes in one terminal do. --branch <branch> runs it in a worktree of the project's repo on that branch instead: the one git already has the branch checked out in, wherever it is, else one wsp makes under its own folder, a new branch starting from the project folder's current commit, with .env files carried in. What else it gets is decided per ecosystem by the lockfiles the branch tracks, each in the folder that holds it and only where the project folder holds that ecosystem's dependency or build folder beside it, or at the top for an ecosystem that carries nothing (uv, Poetry, Cargo, Go), whose environment may sit outside the project, so a lockfile a test fixture tracks costs nothing: relocatable dependency folders (node_modules for npm, pnpm, Yarn and Bun, Yarn's .yarn/cache and .yarn/unplugged, Composer's vendor) are carried in, by a clone where the disk shares blocks and on Linux an overlay of a frozen copy of the folder's own where it does not, made once per install and kept for the next worktree, so a reinstall in the project folder never reaches a worktree; folders that hold the path they were built at (a virtualenv, target, .next) never are; caches outside the project (Cargo's registry, Go's module cache, uv's) are shared as they stand. Each ecosystem's locked install then runs once in the folder holding its lockfile (uv sync --locked, poetry install, cargo fetch --locked, go list -mod=readonly -deps -test ./... at the top, npm install --no-save, pnpm install --frozen-lockfile, yarn install --frozen-lockfile, bun install --frozen-lockfile, composer install), none of which rewrites a tracked lockfile, skipped for pnpm where the node_modules carried in were installed from the branch's own lockfile, and the project's after-worktree command after them at the top, before the thread starts. --cwd starts it in a folder inside the project or one of its worktrees and nowhere else. With no project named, from a thread it runs beside you in your own folder, and from a terminal inside one of your project folders it goes to that project; the first line printed says where: thread 1a2b3c4d on spoo in ~/spoo. Outside every project it is refused in one line and nothing starts. A project on a box runs in its folder there the same way, as the login the box was added with, and a thread there with no project named runs beside you on that box; a thread on a box naming a project on another computer is refused for now, and told to send the lead of its tree a message where that lead can start it, and that the person can start it there otherwise. From a thread, that project is your own or, from a thread on this computer, a box project of your own repository, run in its folder there, and the child joins your tree wherever it runs: wsp threads lists it, send reaches it and --notify me wakes you at its end. A child on a box sends to you in turn and lists your tree, its words alone with --detach, and reaches nothing else of yours: no stop, steer, rename or read of a thread on another computer, and any verb it names on your folder or on a thread of your tree there, an exec or a commit, is refused with a message to you as the road. A project of another repository and another folder the person keeps of yours on this computer are each refused by that rule. Exec takes a thread of your tree, so it reaches none of these. --agent names the agent to run in the thread; absent, the project's agent runs (wsp projects set), else the default agent (wsp agents default), else claude, and a thread runs only on an agent the host has an adapter for; a refusal names the ones it has. --model and --effort pick the model and the reasoning effort by the agent's own words (claude-sonnet-5; low, medium, high, xhigh, max), the same lists the app's composer offers. --access takes wsp's own word, the same on every agent: ask (asks about each action that needs permission), auto-edit (edits files without asking), full (every action without asking) or plan (reads and proposes, changes nothing); an agent with no mode for the word refuses it naming the ones it takes, and an agent's own spelling is refused. Absent, the project's, then the agent's defaults set with wsp agents set, then the catalog's run (high for claude), with full access, and a value the catalog does not list is refused before anything starts, naming the list. A cheaper model for a review is the usual pick. A thread's folder decides which project state (sessions, memory, CLAUDE.md) the agent loads, so put a thread where its project is. --title names the thread, as a person naming it does: the name shows in the sidebar and in the agent's own session list at once, and the title the host asks the agent for as the turn starts never replaces it. Without one the thread is titled by its opening words for the few seconds the agent takes to name it, and by that name after. --notify me names the caller: the thread you are when the host launched you as one, and the person when it did not, which is how a thread starts a child without knowing its own id. --notify <thread> names another thread outright, one of your own tree: the lead that started you, a thread beside you under it, or one you started. From a box it names one of those on that box alone, and your lead hears your end through the --notify me it started you with; any other thread is refused as no thread to notify, and that work goes through the person. Either way the line goes into that thread as a message (steered into its running turn or queued), and a line the person gets shows in their app. The notify line goes once, at the reply; a reply given with background tasks still running says so, and a second line goes at the turn's end. The person's line reads thread 1a2b3c4d finished (completed, 12m 4s, $0.41): <last line of the reply>; a thread's carries the same facts and then the child's final message whole, so you act on the report without reading anything else. A --notify me from a turn that has ended, or with a token this host never launched, is refused rather than sent to the person.

--notify repeats, and each target gets the line once: --notify me --notify 5e6f7a8b wires a builder's end to you and to a reviewer thread together, and the reviewer's own end back to the builder and to you. That removes the relay you would do by hand; it decides nothing, so you still read every report and make the calls. A target whose thread is gone by the time the child ends falls back to the person, and the new thread's own id as a target is refused.

The command line streams the reply to stderr as it arrives and prints it once: into a pipe, which is what you have, stdout carries the whole reply at the end, and on a person's terminal the streamed copy is the reply and stdout adds no second one; a failed turn is a provider failure, its reason the one line on stderr. With --detach (detach true on the tool) nothing streams: the thread id is the whole answer, the turn runs on, and its end goes to whoever --notify named (see the notify paragraph above). A turn ends when the agent process exits, not at its reply, and the thread reads running until then, which can be minutes when the agent left a command running; what a send before then does is under send. When the host restarts under the turn (wsp restart, a service restart, the app relaunching), the command line says so on stderr, dials it again for as long as a host is given to start and prints the reply whole on stdout once it lands, since the stream on the screen has a gap; the tools wait the same way. A host that does not come back in that time is the command's failure in the dial's own words, and the turn goes on. The first stdout line is thread <id>, the id send takes. The MCP tool returns the reply text with the thread id, its record's id, agent and outcome. When the thread's previous turn did not finish (a deadline, a host restart, a nap), the reply text from send and run opens with the line previous turn was cut; resuming and the structured output carries afterCut: true, and the command line prints that line on stderr before the reply; the agent then resumes a transcript that may be missing its last steps, so restate what matters.

send

wsp send 1a2b3c4d "Also cover the codex case in the test."
wsp send 1a2b3c4d --model claude-opus-5-5 --effort high "Now the hard part."

A send is never refused for meeting a turn. Into a thread whose turn is not running the message starts a new turn (outcome started), on the model, effort and access named or the thread's own. Into a thread whose turn is running: when the agent can take input mid-turn (Claude Code does) the message joins the running turn (outcome steered) and arrives at that turn's next tool round, the way a person's message does, and the reply is that turn's, on that turn's picks, with its images where the agent's steer takes them (Claude Code's does); otherwise the message waits for the running turn to end and then runs (outcome queued), and so does one with a --file that is not an image, or with an image to an agent whose steer takes none. A reply the agent gave while a command it started was still running is not a reply yet: that turn is still running and the message steers it. Into a thread whose turn has replied and is waiting only on its agent process to exit, the message waits for that process and runs as the thread's next turn (outcome queued), which the host says as This thread replied, still working; the message runs as its next turn once that process exits; the app's composer shows the same words, and threads reads the thread running until the agent process exits. Two sends keep the order they arrived in. A start on a computer already running as many threads as its threads at once waits for a slot and starts on its own when one frees (outcome held), with capped beside it, the computer and what runs there against its number; the command line says waiting while <computer> is running <n> of <m> threads. A thread that follows a run or a send to its end, without --detach, lends that thread's next turn its own slot, one turn at a time, a turn already held ahead of the message included, so a send into your lead or a thread beside you never waits on your own slot; every other start waits for a slot of its own. A thread whose follow gives up before the turn it follows ends, or that is stopped while that turn runs, works again beside it, and each then holds a slot of its own: the computer runs one past its number until either ends, and nothing new starts there meanwhile. The command line says which outcome on stderr. A person's message on the same thread lands in order with yours. Never start a second thread to hurry a running one.

Threads talk to each other, and this is the road: wsp send <thread> "<message>" (the send tool) puts your words into another thread by its id, one of your own tree, the lead that started you, a thread beside you under it or one you started, wherever it runs, and wsp threads (the threads tool) is where you find that id, with the project, the folder, its branch, the agent and the title beside it. A thread outside your tree, the person's own beside you included, is not yours to reach: threads leaves it out, a send, a stop or a rename naming it reads as no such thread, and its transcript is not in what thread read answers, so a job that needs another tree's thread goes to the person. A stop cascades: stopping your lead stops every thread under it, your siblings and you among them. The other thread's answer does not come back to this call: it comes back as its own next message when that thread was started with --notify me naming you, or with --notify <your thread>. So a thread asking another thread something starts it with a notify that names the asker, sends, and ends its turn.

thread read

wsp thread read 1a2b3c4d
wsp thread read 1a2b3c4d --last

The thread's messages as the app lists them, oldest first, one block each: who it is and the clock on the first line, the text under it. person is the message that opened or steered a turn, agent is the agent's own words, tool is one call of its folded to the line the app's row reads, and turn is the outcome, the duration and the cost the turn ended with, and the reason where it did not complete. --last prints the final reply alone, the whole message the thread's finished line carries, which is what to read when the line that reached you is shorter than the report behind it. When the thread has started another turn since, a second row says so, so the report you are reading is never taken for the one being written. Under --json and on the tool the answer is threadId and messages, each one {who, at, text} with at the ms epoch the runtime recorded. The transcript is the host's own, so a read touches no machine and a paused machine's thread reads the same as a running one's. A call's output and the agent's reasoning are no rows of it, and a thread whose rows the transcript's cap has dropped answers with none, which is an answer and not an error.

thread head

wsp thread head 1a2b3c4d

The thread's title, the agent, model and access it runs on, where it stands and its folder, then its newest events as thread read lists them, as many as fit in 64 KB. Under --json and on the tool the answer is facts (the thread as threads lists it, with model, effort, contextWindow and, while a turn runs, its turnId), events (the newest transcript events, oldest first, each tool result past 2 KB cut with cut set to its whole length), pos (the newest position the transcript has issued; every event carries its own pos) and total (how many events of the thread the transcript holds). Use it to see where a thread stands without reading all of it. A head marks nothing read.

thread allow, thread deny

wsp thread allow 1a2b3c4d
wsp thread deny 1a2b3c4d
wsp thread deny 1a2b3c4d --reason "edit the test file, not the fixture"

A thread whose agent asked to run a command or write a file is stopped on that question: it reads Needs you in wsp threads, runs nothing and ends nothing until somebody answers. A terminal watching the turn prints the question and the keys that answer it; from anywhere else these two lines answer it by thread id, the same pick the app's buttons send. wsp thread read <thread> shows what is being asked. A deny takes --reason, what the agent should do instead: Claude Code reads it with the refusal, and Codex, whose refusal carries no words, gets it as the person's next message in the same turn. Both print what they closed, and both are refused in one line when the thread is waiting on no prompt, so answering twice is never mistaken for answering once.

threads wait

wsp run dev --detach --notify me --title "413 build" "Read ticket 413 ... and build it."
wsp threads wait 1a2b3c4d 5e6f7a8b --timeout 600

--detach on run and send (detach true on both tools) prints thread <id> the moment the turn is started and returns; the turn runs on. threads wait then blocks until one of the named threads leaves running and prints that thread's finished line, thread 1a2b3c4d finished (completed, 12m 4s, $0.41), with the agent's reply whole under it, since a reply's last line is as often a code fence as an answer; --tail prints the last line alone instead, thread 1a2b3c4d finished (completed, 12m 4s, $0.41): <last line of the reply>, which is the line a --notify sends to the person. Under --json and on the tool it is the id, status, duration, cost and the reply's last line under finished either way. One thread per call: a script that started three builders calls it three times, dropping each returned id from the list, since a thread already over comes back at once and would come back again. --timeout <s> (timeout, seconds) gives up after that long: nothing on stdout, thread 1a2b3c4d still running after 10m on stderr (timedOut true on the tool) and the ok exit code, since nothing failed, so other work fits between calls. A host that restarts under the wait is dialled again for as long as a host is given to start and the wait carries on, --timeout still counting from the start. This is a shell script's verb: a script has nothing else to do while its builders run, and a person is reading its output. Do not call it in your own conversation, where it spends minutes of a turn on nothing and nothing can reach you meanwhile. Never poll threads for a state change either: a thread starts its children with --notify me, and a caller that is not a thread hands more than one turn's work to a coordinator thread.

stop

wsp stop 1a2b3c4d

Ends the thread's running turn through the runtime, the way the app's stop button does; the turn ends with status interrupted and whoever followed it gets turn interrupted. The line says thread <id> stopped, or thread <id> not running when the turn had already ended; both succeed, since neither is an error. Nothing is paused or killed and the thread takes the next send. Use it when a send started a turn you did not mean to.

wsp stop 1a2b3c4d --subagent a1b2c3d4e5f6a7b8

Stops one subagent the thread's agent started (Claude Code's Agent tool), by the id in the SUBAGENT column of wsp threads, and nothing else: the turn, the agent and its other subagents run on, and the agent reads that subagent as stopped. The line says thread <id> subagent <id> stopped once the agent took the stop, thread <id> subagent <id> not running when it or the turn had already ended, or the reason after a colon when the agent would not stop it or offers no stop for one subagent, which is said as Stop is not available for <agent> subagents; stop the thread to stop them all. Every one of these succeeds. Under --json and on the tool it carries the thread's id, the subagent's id and the outcome, with error beside a refused or unsupported outcome.

exec

wsp exec 1a2b3c4d -- git status --short
wsp exec 1a2b3c4d --cwd /root -- sh -c 'ls | wc -l'

Each word after -- reaches the computer the thread runs on as one argument; a shell line goes through sh -c. The command runs in the folder --cwd names (absolute, on that computer), else in the folder the thread works in, the project's folder or its worktree, so git status there needs no cd. The command's exit code is the verb's, and a non-zero exit is followed by one stderr line naming the folder it ran in, which the host answers with rather than the caller assuming it; the tool carries that folder as cwd. A non-zero exit is a result; the computer going away is an error. The command runs with no login shell, so bash -c, never bash -lc.

add

wsp folders /Users/zingzy                         # what is inside, for naming a folder to record
wsp add /Users/zingzy/wsp                         # a project on this computer, worked where it sits
wsp add https://github.com/spoo-me/spoo.me --into /Users/zingzy/code/spoo.me   # cloned here into an empty folder, then worked there
wsp add https://github.com/spoo-me/frontend --on spoo --name spoo-landing   # a project a computer clones
wsp add spoo-me/frontend --on spoo                # the same repo through the signed-in gh on that computer
wsp add /Users/zingzy/spoo/spoo-landing --on spoo # a folder here seeding a project there: prints the menu, sends nothing
wsp add /Users/zingzy/spoo/spoo-landing --on spoo --yes   # sends the ticked rows; --keep, --cut, --no-memory, --no-commits move them
wsp add root@203.0.113.7 --recipe mine           # a computer of yours over ssh, set up from the recipe named mine
wsp add spoo --resume                             # finish a setup that stopped, or a sign-in left waiting
wsp projects                                      # every project, each on its computer
wsp add /Users/zingzy/monorepo/apps/web          # a subfolder of a repo: a project of that repo
wsp add /Users/zingzy/notes                       # a folder that is no git repo: a project with no branches

A folder here is a project as it stands, a git repo or not: a subfolder of a repo is a project of that repo and takes its branches, and a folder git holds no repo in takes no branch; a repo's url needs --into <folder>, an empty folder here it is cloned into, or --on <computer> for a computer that clones it. The clone here runs with no prompt: a private repo needs gh auth login or an ssh url, and a failure says git's own last line. One source on one computer is one project, so recording it twice is refused naming the one there is. A computer's add checks it, installs wsp and then sets it up from the recipe in steps: the base tools first, then the agents, their sign-ins, the CLIs, MCP servers, skills, plugins, configs and context files, with the folders cloned beside them. A step that fails says why and the rest go on; only the base tools and the agents stop it. Without a recipe the computer is listed as pending until one is picked. A thread on this computer then runs in that folder, and on a box the person joined in the project's folder there.

slate

A slate is a live panel on the Slate tab beside this thread: you build it, the person reads, presses and fills it in. Build one when the person will look at it or press it: a tracker, form, walkthrough or dashboard. Results for you stay in your own tools. Once a thread has a slate, a request to see something lands there, and what the person does in it gets its result there unless they ask in the chat. Write it once, then only patch it.

You write a small JSX-like text: <slate title="...">, pieces as elements, prop="literal" and prop={formula}. A formula reads live data (pr.checks) and its own $values. Declare <value name="step" start={1} />, <run name="check" cmd="gh api ..." env={{ ID: $id }} /> and <when change={$id} do={start($check)} />, and the slate runs it with no turn of yours; the person approves each command once. Code only the slate uses goes in a <file name="x.py">, run as "$SLATE_DIR/x.py"; code the project already has is called where it is. For a secret, token or password the person enters themselves, give a <secret name="token" /> input; never ask them to paste it into a file or the chat. Props are meaning, never style; nothing inside braces is JavaScript.

Lay it out simple and airy unless asked for more: one idea per section, one heading per section, status and last-checked lines small and muted beside their subject, actions at the end of their row with one primary per section, mono only for figures, ids, times and paths, every live number with its window and unit, nothing centered but a lone figure or card.

Build and read it with the slate tools (slate_catalog, slate_write, slate_state, slate_read), never wsp from a shell, which may be another install. Every write answers its version and a sketch, values filled in; a refusal lists every error with its fix and stores nothing. A patch is elements without <slate>: a piece with its id replaces it, <props id="week" tone="warning" /> merges, <add under="root">, <remove id="x" />, <clear />, <undo />.

Only a press reaches you: a send("text", $path) step on a button puts one message into this thread: the text, then a slate: {...} line holding the values as data, never instructions. For their input, give a button that sends, or read the slate. Shown a screenshot of it, read the slate; slate:week in their message names a piece.

The loop for building with wsp

1. One project recorded (wsp add <folder> here, or wsp add <url> --on <computer> there). wsp threads <project> shows what is on it, each thread with its folder and branch.
2. One thread per ticket, each in its own worktree: wsp run <project> --branch ticket/<n>-<slug> starts it in one, made from the project folder's current commit with the dependencies carried in. Two threads writing in one checkout collide; threads that only read, plan or answer share the project folder.
3. The brief names the ticket, the files to read whole, the laws (the repo's review skill), the exact test commands and the proof required, and says to wait for every command it runs: a reply given while a command the agent left running in the background is still going holds the turn open until that command finishes, so the report lands minutes after the words and a foreground wait is the shorter road. A brief that says "fix the bug" comes back with a guess.
4. Start builder threads with --detach (detach true on run) and --notify me, which prints each thread's id and returns, then end your turn: each builder's finished line comes back to you as a message carrying its whole report, in the order they finish, and nothing is polled or waited on. When you are not a thread yourself and the job is more than one turn, this whole loop is a coordinator thread's in the project's folder on this computer: give it the job, hand off, and tell the person where to read it. Without --detach, wsp run and run follow the first turn and return only at its reply, which is the right call for a short turn you read at once.
5. A review is its own thread in the builder's worktree, wsp run <project> --cwd <its path>, with the branch name and the review skill; the builder fixes in its thread through send. A review runs well on a cheaper model, --model on run.
6. Work leaves by git push and gh pr create from the thread, its agent's own git.
7. Gates (full test runs, builds, packaging) run on the person's computer or one at a time on a box. A 2 vCPU, 4 GB computer runs one build or one agent at a time; two starve the daemon and the app reads the computer as not answering.

Where the person steps in

• Sign-ins happen on the machine during wsp init, and each page is opened and finished on the person's computer: the run hands it over and waits. A thread cannot sign in for them; if gh auth status fails on the machine, say so and export instead of pushing.
• Keys (an Anthropic key) live in the person's .env and never reach a thread. A secret a thread needs is asked for through wsp, not typed into a terminal.
• An import cuts every secret-shaped file unless --keep names it; the plan's rows are the person's to answer before --yes.
• The heavy rows and the sign-in choices in the recipe are the person's answers, put to them before anything is built.

Costs and limits

• A machine naps by itself after 20 minutes without a person, a thread or a command touching it; the next thread, send or exec wakes it, with waking <name> on stderr from the command line.
• A turn is cut after 10 minutes with no output from the agent, and at 6 hours in all. A long silent step (a full install, a build) needs output flowing or it ends the turn.
• One thread runs one agent process; a 4 GB machine runs one build or one agent at a time. Put a second builder on a second machine, not a second thread on the same one.
• A new thread runs on the model, effort and access named with --model, --effort and --access (the tool inputs of the same names), else the project's (wsp projects set), else the ones set for that agent (wsp agents set), else the agent's catalog defaults. A send into a thread runs on the model and effort it names, else the ones the thread's latest turns ran on. --access takes wsp's four words, ask, auto-edit, full and plan, and refuses an agent's own spelling. Choose the role by the brief and the picks, and keep review threads short and cheap.

Tools the catalog does not carry

wsp recipe ticks catalog rows. A tool the person's projects use that the catalog has no row for and no package manager here installed goes on the image as its own row:

wsp recipe --add just="brew install just" --add-check just="just --version"
wsp recipe --add ruff="uv tool install ruff"

--add <id>=<install command> is repeatable and --add-check <id>=<command> says what proves the tool landed (without one, command -v <id>). The line runs on the machine as given, as root, after every catalog install, with Homebrew and apt already there. Rules for adding one:

• --add is for a tool this computer does not have. A package one of their own package managers already has is a row of its own: tick it with --set, not --add. An --add for one is refused in a line naming the --set word to use instead.
• Add only what the person's own history or their repository files show in use: a tool their agents ran that no manager here has, a runner their project's config names, a package the image needs and this computer never installed. Never add on a guess.
• Prefer a Homebrew, npm, uv or apt form (brew install x, npm install -g x, uv tool install x, apt-get install -y x) over a downloader. A line that pipes a download into a shell is refused in review.
• One tool per row, so a row that fails names the tool that failed. A failed row does not fail the build; it is listed as failed on the machine's lineage.
• There is no sign-in for these rows. A tool that needs a login needs a catalog row; say so instead of adding it.

Packages this computer already has

Everything wsp recipe scan lists under Also on this computer (alsoHere in the JSON) is a package one of their own managers installed, and each row's id there is the id to tick:

wsp recipe --set brew/zingzy/tap/diskbloom=on --set npm/turbo=off

Such a package is a row of its own, so the build installs it by the road the plan resolves for it: a formula with a Linux bottle by Homebrew, a tap formula with none from its GitHub release, pinned to the checksum its first install recorded, an npm or uv global by its manager. That is the same row and the same road the Also screen ticks when the person drives the wizard, so an agent-written recipe and a hand-driven one build the same image. --set <id>=off unticks one again.

Rules learned the hard way

• A send into a running thread steers it or waits behind it, never a second concurrent turn (#274).
• A thread's end reaches its parent thread or the person only when its start said --notify; nothing polls (#286).
• A thread starts its children with --notify me, which the host resolves to the thread the request came out of, and ends its turn; a caller that is not a thread cannot be reached by a line at all, so it takes one turn's reply or hands the job to a coordinator thread. threads wait blocks and belongs in a shell script (#413, #479).
• A thread works in --cwd, its worktree, or the project's folder; a relative --cwd is refused before anything starts (#280).
• A turn ends on 10 minutes of silence, not a wall clock; long steps must print, and a command the agent left running in the background counts as work, so a quiet watch on one is not cut (#295, #679).
• A reply that lands with a command the agent left running in the background holds the turn open until that command finishes, up to the turn limit of the computer it runs on (none on one the person owns until --turn-limit sets another): the thread reads Working until then and a send into it steers the agent. The reply's finished line goes at once and ends 1 background task still running; another line comes when this turn ends, so a lead waits for the second line rather than taking the child for finished. That second line carries the agent's own next words where the harness woke it with the result, and one line naming what finished where it stayed silent. Where the turn ends with the command still running, a server that never exits among them, the turn reads done and the second line names what is left running, ended with 1 background task running (#313, #679, #1539, #1887).
• run and send return when the reply is complete, not when the process exits minutes later; the thread reads running until the agent process exits, and a send that meets that gap waits for the process and runs as the thread's next turn rather than being refused (#293, #364, #479).
• A turn's process group dies with the turn; a server that must outlive it starts with setsid nohup ... & (#275).
• Export refuses an existing folder; --replace overwrites it on purpose (#224).
• A resumed thread runs in the folder its session started in, whatever folder is followed in the app (#236).
• A send carries its own request id, so two clients sending the same text do not adopt each other's turn (#239).
• The command line and both tool servers refuse a host of another release in one line naming both releases and what to run on the older end: wsp restart for an older host here, which the restart line and tool reach past the check.
• Not here yet: a GitHub credential on the machine outside a sign-in during init (#279).