@tshu-w/pi-agents 0.1.1 → 0.2.0

package/README.md

@@ -2,14 +2,14 @@
 
 Multi-agent runtime for [Pi](https://pi.dev): hand work to other agents and keep going while they run.
 
-https://github.com/user-attachments/assets/c1d48bc4-3b36-438e-976b-f76ae586ffdd
+https://github.com/user-attachments/assets/52dd1de6-bf26-45ea-8775-2b1a1a187f4f
 
 <details>
 <summary>Play by play</summary>
 
 1. Ask for three background reviews. Three Agents start, and the task panel lists them.
 2. Ask about `res.redirect` while they run. The first review finishes, and its notification arrives.
-3. `/agents` opens `review-application` to watch it work; `Ctrl+C` returns.
+3. `/tasks` opens `review-application` to watch it work; `Ctrl+C` returns.
 4. The other notifications arrive, and the main Agent reports each review.
 5. Ask for a summary of each file in `lib/`. A background Program starts one Agent per file; the panel shows three running and the rest queued.
 6. `Ctrl+Z` detaches and leaves the Session running. `pd agents` opens the workbench, and `Space` previews the Session.
@@ -19,9 +19,9 @@ https://github.com/user-attachments/assets/c1d48bc4-3b36-438e-976b-f76ae586ffdd
 </details>
 
 - **Async agents**: Agents run in parallel in the background and notify their parent when done.
-- **Programmatic delegation**: Split long-horizon tasks in code into [calls the model handles well](https://alexzhang13.github.io/blog/2026/harness/), as in [RLM](https://alexzhang13.github.io/blog/2025/rlm/).
+- **Dynamic workflows**: Extends Pi's [codemode](https://pi.dev/docs/latest/codemode) to recursively split long-horizon tasks into calls the model handles well, as in [RLM](https://alexzhang13.github.io/blog/2026/harness/).
 - **Inter-agent messaging**: Agents message each other, even in other Pi instances.
-- **Workbench**: All your Sessions in one view; keep them running after the terminal closes.
+- **Persistent agents**: Agents keep running after the terminal closes, with a workbench to manage them.
 
 ## Install
 
@@ -30,7 +30,7 @@ npm install -g @tshu-w/pi-agents
 pi install "$(npm root -g)/@tshu-w/pi-agents"
 ```
 
-Requires Pi 1.0.0 or later. Start Pi with `pd` (or `pi-agents`) in place of `pi`, and enable `program` with `{ "defaultTools": ["+program"] }` in `settings.json`.
+Requires Pi 1.0.0 or later. Start Pi with `pd` (or `pi-agents`) in place of `pi`, and enable `program`, which replaces Pi's `codemode`, with `{ "defaultTools": ["+program"] }` in `settings.json`.
 
 To use only the extension, without the workbench:
 
@@ -40,21 +40,23 @@ pi install npm:@tshu-w/pi-agents
 
 ## Usage
 
+Ask Pi in plain words; it starts Agents and Programs when the work calls for them.
+
+| Term | Meaning |
+|---|---|
+| Agent | A Pi conversation: yours, or one started with the `agent` tool |
+| Program | JavaScript the model runs with the `program` tool to call tools and Agents |
+| Workbench | `pd agents`: your recent Sessions, running or not, grouped by what they need from you |
+
 | Command | Does |
 |---|---|
-| `agent` tool | Starts, messages, and waits for Agents |
-| `program` tool | Runs JavaScript that calls tools and Agents |
-| `/agents` | Opens an Agent in the tree to watch and talk to it |
-| `/tasks` | Hides or shows the task panel |
+| `/program <path> [args]` | Runs a saved Program script, with `args` as its input |
+| `/tasks` | Opens an Agent or background Program to watch it; you can talk to Agents |
+| `/tasks panel` | Hides or shows the task panel |
 | `Ctrl+Z`, `/detach` | Leaves a Session running and returns to the shell |
 | `pd agents` | Opens the workbench |
 | `pd attach <session>` | Attaches to a Session, starting it if needed |
 
-## Limitations
-
-- Each Agent is one Pi Session; branches are not separate Agents. Use fork/clone to create independent Agents.
-- A Session can be open in only one Pi instance at a time; quit the other or `pd attach` to it.
-
 ## Configuration
 
 ```json
@@ -65,17 +67,22 @@ pi install npm:@tshu-w/pi-agents
 }
 ```
 
-Concurrency limits per root, and extensions loaded by child Agents.
+Each tree runs at most `maxConcurrent` child Agents at once and accepts at most `maxOutstanding` unfinished inputs. `extensions` lists extensions loaded by child Agents.
 
-## Docs
+## Limitations
 
-- [SPEC.md](docs/SPEC.md): Agents, messages, and limits
-- [PROGRAM.md](docs/PROGRAM.md): Programs and their API
-- [WORKBENCH.md](docs/WORKBENCH.md): the workbench, hosts, and the daemon
+- Each Agent is one Pi Session, so branches within it are not separate Agents; use `/fork` or `/clone` to make one.
+- A Session can be open in only one Pi instance at a time; quit the other or `pd attach` to it.
 
 ## Evaluation
 
-On [BrowseComp](https://arxiv.org/abs/2504.12516), async agents improved 7 of 8 models by up to 9 points; programmatic delegation kept accuracy with 20%+ fewer tokens.
+On [BrowseComp](https://arxiv.org/abs/2504.12516), async agents improved 7 of 8 models by up to 9 points; dynamic workflows kept accuracy with 20%+ fewer tokens.
+
+## Docs
+
+- [SPEC.md](docs/SPEC.md): Agents, messages, and limits
+- [PROGRAM.md](docs/PROGRAM.md): Programs and their API
+- [HOSTS.md](docs/HOSTS.md): hosted Sessions, the daemon, and the workbench
 
 ## License
 

package/bin/daemon.mjs

@@ -4,7 +4,7 @@
 import { readFile } from 'node:fs/promises';
 import { isAbsolute } from 'node:path';
 import { setTimeout as delay } from 'node:timers/promises';
-import { startHost } from '../src/host/client.mjs';
+import { settledHosts, startHost } from '../src/host/client.mjs';
 import { acquireLock, pruneLocks, reserve } from '../src/roots/locks.mjs';
 import { prepareDirectory, statePaths } from '../src/roots/paths.mjs';
 import { findRoot } from '../src/roots/discovery.mjs';
@@ -25,6 +25,8 @@ pruneLocks(paths.locks);
 const IDLE_MS = 30000;
 const PUBLISH_MS = 250;
 const RECHECK_MS = 1000;
+const OCCUPIED_WAIT_MS = 5000;
+const HOST_WAIT_MS = 3000;
 const version = await codeVersion();
 let waking = 0, delivering = 0, lastActivity = Date.now(), retiring = false, closing = false;
 const stop = new AbortController();
@@ -49,22 +51,28 @@ async function savedModel(file, signal) {
   }
 }
 
+/** The status of the Session's Pi once it accepts messages, checking that it runs the Session expected. */
+async function accepting(root, signal) {
+  try {
+    const status = await request(paths.session(root.id), { action: 'status' }, { signal, timeoutMs: 1000 });
+    if (status.id !== root.id || status.cwd !== root.cwd) throw new Error('Awakened Agent identity or cwd does not match its Session');
+    if (status.availabilityError) throw new Error(status.availabilityError);
+    if (status.ready) return status;
+  } catch (error) {
+    signal.throwIfAborted();
+    if (!['ENOENT', 'ECONNREFUSED', 'SOCKET_MODE'].includes(error.code)) throw error;
+  }
+}
+
 /** Waits until the woken Session accepts messages with its saved model. */
 async function ready(root, model, signal) {
   for (;;) {
-    try {
-      const status = await request(paths.session(root.id), { action: 'status' }, { signal, timeoutMs: 1000 });
-      if (status.id !== root.id || status.cwd !== root.cwd) throw new Error('Awakened Agent identity or cwd does not match its Session');
-      if (status.availabilityError) throw new Error(status.availabilityError);
-      if (status.ready) {
-        if (model && (status.model?.provider !== model.provider || status.model?.modelId !== model.modelId)) {
-          throw new Error(`Saved model ${model.provider}/${model.modelId} was not restored; refusing model fallback.`);
-        }
-        return;
+    const status = await accepting(root, signal);
+    if (status) {
+      if (model && (status.model?.provider !== model.provider || status.model?.modelId !== model.modelId)) {
+        throw new Error(`Saved model ${model.provider}/${model.modelId} was not restored; refusing model fallback.`);
       }
-    } catch (error) {
-      signal.throwIfAborted();
-      if (!['ENOENT', 'ECONNREFUSED'].includes(error.code)) throw error;
+      return;
     }
     await delay(50, undefined, { signal });
   }
@@ -82,7 +90,17 @@ const router = createRouter({
       if (typeof root.cwd !== 'string' || !root.cwd.trim() || !isAbsolute(root.cwd)) {
         throw Object.assign(new Error(`Agent ${id} requires a nonempty absolute working directory; refusing cwd fallback.`), { code: 'INVALID_CWD' });
       }
-      reserve(paths.locks, root.sessionFile, id).release();
+      // A host still starting Pi in the Session's cwd, as when a terminal has just opened the Session, may be
+      // starting this Session. The wait leaves the rest of the wake time for starting the Session here.
+      await settledHosts(paths, host => host.session?.id === id,
+        { starting: host => !host.session && host.cwd === root.cwd, timeoutMs: HOST_WAIT_MS });
+      // Another Pi may hold the Session briefly: one exiting releases it, one starting accepts the message once ready.
+      for (const deadline = performance.now() + OCCUPIED_WAIT_MS; ;) {
+        try { reserve(paths.locks, root.sessionFile, id).release(); break; }
+        catch (error) { if (error.code !== 'SESSION_OCCUPIED' || performance.now() > deadline) throw error; }
+        if (await accepting(root, combined)) return;
+        await delay(100, undefined, { signal: combined });
+      }
       // Pi restores a Session's model before extensions register their providers; name it explicitly.
       const model = await savedModel(root.sessionFile, combined);
       const args = [...launch.args, '--session', root.sessionFile, ...(model ? ['--model', `${model.provider}/${model.modelId}`] : [])];

package/bin/host.mjs

@@ -64,7 +64,9 @@ mirror.loadAddon(serializer);
 
 function start({ cols, rows }) {
   mirror.resize(cols, rows);
-  child = pty.spawn(config.pi, config.args, { name: env.TERM || 'xterm-256color', cols, rows, cwd: config.cwd, env });
+  // Pi learns of later attaches from the host, once it connects.
+  const attached = terminal ? '1' : '0';
+  child = pty.spawn(config.pi, config.args, { name: env.TERM || 'xterm-256color', cols, rows, cwd: config.cwd, env: { ...env, PI_AGENTS_HOST_ATTACHED: attached } });
   child.onData(data => {
     const text = completed(data);
     trackModes(text);
@@ -73,6 +75,12 @@ function start({ cols, rows }) {
     terminal?.socket.write(frame(FRAME.data, data));
   });
   child.onExit(({ exitCode }) => {
+    // No terminal saw why Pi failed, so its last screen goes to the log.
+    if (!attachedOnce && exitCode !== 0) {
+      const buffer = mirror.buffer.active;
+      const lines = Array.from({ length: buffer.length }, (_, i) => buffer.getLine(i)?.translateToString(true) ?? '');
+      console.error(`[pi-agents] Pi exited (${exitCode}) in ${config.cwd}:\n${lines.join('\n').trim()}`);
+    }
     server.close();
     rmSync(socketPath, { force: true });
     // Pi's last output can arrive after its exit; let it through before the final frame.

package/bin/pd.mjs

@@ -1,12 +1,13 @@
 #!/usr/bin/env node
-// The `pd` command: runs interactive Pi in a host and attaches this terminal; everything else
-// runs Pi directly.
+// The `pd` command: runs Pi in a host, attaching this terminal to interactive Pi and connecting
+// non-interactive Pi to the hosted Session; `--no-session` and package commands run Pi directly.
 import { spawn } from 'node:child_process';
 import { accessSync, constants } from 'node:fs';
 import { createRequire } from 'node:module';
-import { join, resolve } from 'node:path';
+import { dirname, join, resolve } from 'node:path';
 import { pathToFileURL } from 'node:url';
-import { attach, listHosts, startHost } from '../src/host/client.mjs';
+import { styleText } from 'node:util';
+import { attach, settledHosts, startHost } from '../src/host/client.mjs';
 import { detachKey, detachMatcher } from '../src/host/keys.mjs';
 import { discoverRoots, findRoot } from '../src/roots/discovery.mjs';
 import { agentDir, configuredSessionDir, defaultSessionDir, resolvePath, sessionDir, statePaths } from '../src/roots/paths.mjs';
@@ -17,14 +18,14 @@ const real = process.env.PATH.split(':').map(dir => join(dir, 'pi')).find(file =
   try { accessSync(file, constants.X_OK); return true; } catch { return false; }
 });
 if (!real) {
-  process.stderr.write('pd needs Pi: install it so that pi is on PATH.\n');
+  process.stderr.write(`${error('pd needs Pi: install it so that pi is on PATH.')}\n`);
   process.exit(1);
 }
 const args = process.argv.slice(2);
 const paths = statePaths();
 
 const COMMANDS = new Set(['install', 'remove', 'uninstall', 'update', 'list', 'config', 'auth', 'mcp']);
-const DIRECT_FLAGS = new Set(['-p', '--print', '--mode', '-h', '--help', '-v', '--version', '--export', '--list-models', '--no-session']);
+const DIRECT_FLAGS = new Set(['-h', '--help', '-v', '--version', '--export', '--list-models', '--no-session']);
 
 function runDirectly() {
   const child = spawn(real, args, { stdio: 'inherit' });
@@ -39,6 +40,10 @@ function runDirectly() {
   });
 }
 
+function error(text) {
+  return styleText('red', text, { stream: process.stderr });
+}
+
 function option(name, alias) {
   for (let i = 0; i < args.length; i++) {
     if (args[i] === '--') return;
@@ -48,51 +53,75 @@ function option(name, alias) {
 }
 
 
-async function attachAndReport(socket) {
+/** Attaches the terminal to the host at `socket`; `send`, if given, sends messages once attached, and its error is reported once detached. */
+async function attachAndReport(socket, send) {
   const tui = await import(pathToFileURL(createRequire(join(piPackage(real), 'package.json')).resolve('@earendil-works/pi-tui')).href);
-  const result = await attach(socket, { isDetach: detachMatcher(tui, detachKey(agentDir())) });
+  let sent;
+  const result = await attach(socket, { isDetach: detachMatcher(tui, detachKey(agentDir())), onAttach: () => { sent = send?.(); } });
+  const failure = await sent;
+  if (failure) process.stderr.write(`${error(failure)}\n`);
   const id = result.session?.id;
-  if (result.reason === 'exited') process.exit(result.exitCode ?? 0);
+  if (result.reason === 'exited') process.exit(failure ? 1 : result.exitCode ?? 0);
   if (result.reason === 'closed') {
-    process.stderr.write(`The host stopped unexpectedly. See ${paths.hostLog}\n`);
+    process.stderr.write(`${error(`The host stopped unexpectedly. See ${paths.hostLog}`)}\n`);
     process.exit(1);
   }
   if (result.reason === 'takeover') process.stdout.write('Attached in another terminal.\n');
-  process.stdout.write(`Pi keeps running. To reattach, run pd attach ${id ?? '<session>'}\n`);
-  process.exit(0);
+  process.stdout.write(`${styleText('dim', 'Pi keeps running. To reattach:')} pd attach ${id ?? '<session>'}\n`);
+  process.exit(failure ? 1 : 0);
 }
 
-/** The running host already holding the Session that `--session` or `-c` would open. */
-async function runningTarget(hosts) {
+/** The running host already holding the Session that `--session`, `--session-id`, or `-c` would open. */
+async function runningTarget() {
+  let running;
   const session = option('--session');
+  const sessionId = option('--session-id');
   if (session) {
     const file = resolve(session);
-    return hosts.find(host => host.session && (host.session.id.startsWith(session) || host.session.file === file));
-  }
-  if (args.includes('-c') || args.includes('--continue')) {
+    running = host => host.session && (host.session.id.startsWith(session) || host.session.file === file);
+  } else if (sessionId && option('--fork') === undefined) {
+    // With `--fork`, the ID names a new Session.
+    const file = await sessionById(sessionId);
+    // A Session without messages has no file yet; its host reports where it will be.
+    const directory = sessionDirOption() ?? defaultSessionDir(process.cwd());
+    running = host => host.session && (file
+      ? host.session.file === file
+      : host.session.id === sessionId && dirname(host.session.file) === directory && host.session.cwd === process.cwd());
+  } else if (args.includes('-c') || args.includes('--continue')) {
     const file = await recentSession();
-    return file && hosts.find(host => host.session?.file === file);
+    if (file) running = host => host.session?.file === file;
   }
+  return running && (await settledHosts(paths, running)).find(running);
 }
 
 /** The Session `-c` continues, chosen by Pi's own `continueRecent` rules. */
 async function recentSession() {
   const { findMostRecentSession } = await import(pathToFileURL(join(piPackage(real), 'dist/core/session-manager.js')).href);
-  const flag = option('--session-dir');
-  const configured = flag ? resolvePath(flag) : configuredSessionDir();
+  const configured = sessionDirOption();
   const fallback = defaultSessionDir(process.cwd());
   const directory = configured ?? fallback;
   // A configured directory may hold other cwds' Sessions.
   return findMostRecentSession(directory, directory === fallback ? undefined : process.cwd()) ?? undefined;
 }
 
+/** The Session `--session-id` would open, found by Pi's own rules, if it exists. */
+async function sessionById(id) {
+  const { SessionManager } = await import(pathToFileURL(join(piPackage(real), 'dist/core/session-manager.js')).href);
+  return SessionManager.findById(process.cwd(), id, sessionDirOption());
+}
+
+function sessionDirOption() {
+  const flag = option('--session-dir');
+  return flag ? resolvePath(flag) : configuredSessionDir();
+}
+
 async function attachCommand(query) {
   if (!query) {
-    process.stderr.write('Usage: pd attach <session>\n');
+    process.stderr.write(`${error('Usage: pd attach <session>')}\n`);
     process.exit(2);
   }
-  const hosts = await listHosts(paths);
-  const hosted = hosts.filter(host => host.session && (host.session.id.startsWith(query) || host.session.name === query));
+  const wanted = host => host.session && (host.session.id.startsWith(query) || host.session.name === query);
+  const hosted = (await settledHosts(paths, wanted)).filter(wanted);
   if (hosted.length === 1) return attachAndReport(hosted[0].socket);
   let roots = [];
   if (!hosted.length) {
@@ -104,8 +133,8 @@ async function attachCommand(query) {
   const matches = hosted.length ? hosted.map(host => host.session) : roots;
   if (matches.length !== 1) {
     process.stderr.write(matches.length
-      ? `"${query}" matches several Sessions:\n${matches.map(match => `  ${match.id}  ${match.name ?? ''}`).join('\n')}\n`
-      : `No Session matches "${query}".\n`);
+      ? `${error(`"${query}" matches several Sessions:`)}\n${matches.map(match => `  ${match.id}  ${match.name ?? ''}`).join('\n')}\n`
+      : `${error(`No Session matches "${query}".`)}\n`);
     process.exit(1);
   }
   const [root] = roots;
@@ -116,6 +145,20 @@ async function attachCommand(query) {
   return attachAndReport(socket);
 }
 
+/** Warns about the options a running Session does not apply. */
+function warnIgnored(options) {
+  const ignored = options.filter((arg, i) => !['--session', '--session-id', '--session-dir', '-c', '--continue'].includes(arg)
+    && !arg.startsWith('--session=') && !arg.startsWith('--session-id=') && !['--session', '--session-id', '--session-dir'].includes(options[i - 1]));
+  if (ignored.length) process.stderr.write(`${styleText('yellow', `The Session is already running; using it without applying: ${ignored.join(' ')}`, { stream: process.stderr })}\n`);
+}
+
+/** Pi's mode for `args` when it is not interactive: 'text', 'json', or 'rpc'. */
+function headlessMode() {
+  const mode = option('--mode');
+  if (mode === 'json' || mode === 'rpc') return mode;
+  if (!interactive || args.includes('-p') || args.includes('--print')) return 'text';
+}
+
 const interactive = process.stdin.isTTY && process.stdout.isTTY;
 if (args[0] === 'attach' && interactive) await attachCommand(args[1]);
 else if (args[0] === 'agents' && interactive) {
@@ -123,17 +166,22 @@ else if (args[0] === 'agents' && interactive) {
   await workbench({ pi: real, paths, sessionDir: sessionDir() });
   process.exit(0);
 }
-else if (!interactive || COMMANDS.has(args[0]) || args.some(arg => DIRECT_FLAGS.has(arg.split('=')[0]))) runDirectly();
+else if (COMMANDS.has(args[0]) || args.some(arg => DIRECT_FLAGS.has(arg.split('=')[0]))) runDirectly();
+else if (headlessMode()) {
+  const { runHeadless } = await import('../src/host/rpc-client.mjs');
+  await runHeadless({ pi: real, paths, args, mode: headlessMode(), findRunning: runningTarget, warnIgnored });
+}
 else {
-  const running = await runningTarget(await listHosts(paths));
+  const running = await runningTarget();
+  let send;
   if (running) {
-    // Pi already runs this Session, so options that would start it differently do not apply.
-    const ignored = args.filter((arg, i) => !['--session', '--session-dir', '-c', '--continue'].includes(arg)
-      && !arg.startsWith('--session=') && !['--session', '--session-dir'].includes(args[i - 1]));
-    if (ignored.length) process.stderr.write(`The Session is already running; attaching without applying: ${ignored.join(' ')}\n`);
+    // Pi already runs this Session: its messages reach it as follow-ups once attached, as Pi sends them once its TUI starts,
+    // and options that would start it differently do not apply.
+    const { startupMessages } = await import('../src/host/rpc-client.mjs');
+    send = await startupMessages({ pi: real, paths, args, running, warnIgnored });
   }
   const socket = running?.socket ?? await startHost(paths, {
     pi: real, args, cwd: process.cwd(), cols: process.stdout.columns, rows: process.stdout.rows, waitForTerminal: true,
   });
-  await attachAndReport(socket);
+  await attachAndReport(socket, send);
 }

package/docs/{WORKBENCH.md → HOSTS.md}

@@ -1,10 +1,12 @@
-# Pi Agents Workbench
+# Hosted Sessions
 
 ## 1. Overview
 
-The workbench shows the user's root Sessions in one terminal view. From it the
-user opens a Session, reads its latest result, or sends it a message. Sessions
-started with `pd` keep running after their terminal closes.
+`pd` runs each Pi Session in a host of its own, so the Session keeps running
+after its terminal closes, and terminals, scripts, and other programs can use
+it at once. The workbench, opened with `pd agents`, shows the user's root
+Sessions in one terminal view: from it the user opens a Session, reads its
+latest result, or sends it a message.
 
 Three kinds of process take part:
 
@@ -15,13 +17,12 @@ Three kinds of process take part:
 - **Workbench**: the daemon's terminal view, opened with `pd agents`.
 
 Every running root Session reports its state to the daemon. The daemon starts
-when a Session or the workbench first needs it, and exits 30 seconds after its
-last connection closes.
+when a Session or the workbench first needs it, and exits soon after its last
+connection closes.
 
 Files live in `${XDG_STATE_HOME:-~/.local/state}/pi/agents/`:
 
-- `workbench.json`: seen marks and which Sessions are listed. The file is
-  versioned.
+- `workbench.json`: seen marks and which Sessions are listed.
 - `host.log`, `daemon.log`: logs.
 
 Sockets and Session locks go in `$XDG_RUNTIME_DIR/pi-agents/`. macOS has no
@@ -43,15 +44,34 @@ load the extension, but run outside hosts and end with their terminal.
 
 - `pd [pi options]` starts Pi interactively in a new host and attaches the
   terminal. If the Session is already running in a host, `pd` attaches to it
-  instead.
+  instead, sending it the messages as follow-ups and ignoring other options.
 - `pd agents` opens the workbench.
 - `pd attach <session>` attaches to a Session, starting it first if it is not
   running.
-- Non-interactive starts (`-p`, `--mode`, piped stdin) and package commands
-  (`pd install`, `pd update`, ...) run Pi directly.
-
-A host inherits the environment of the process that asked for it, because Pi
-reads terminal features from the environment once, at startup.
+- Non-interactive starts (`-p`, `--mode json`, `--mode rpc`, piped stdin) work
+  as in Pi, on the Session in a host, so several of them and an attached
+  terminal can use one Session at once. Their commands act on that Session,
+  as `abort` stops whichever turn is running. Unlike Pi:
+  - Dialogs are not sent to them. A dialog waits while a terminal is attached
+    and is cancelled otherwise.
+  - Extensions see interactive mode, so what an extension writes to stdout
+    does not reach them; `/program` prints as with `pi -p`.
+  - `new_session`, `switch_session`, `fork`, and `clone` move only the caller
+    to the other Session.
+  - `-p` and `--mode json` wait until the Session is idle, then run their
+    messages back to back. Their output covers their own turns, including
+    input other clients add to them.
+  - `SIGINT`, `SIGTERM`, or `SIGHUP` (as from Ctrl+C, `kill`, or a closed
+    terminal) makes `-p` and `--mode json` withdraw their prompts that have
+    not started and stop their running turn, including input other clients
+    added to it. Killed with `SIGKILL`, they leave their turn running.
+  - An RPC client that ends leaves its turn running. One whose Session stops
+    opens it again; requests awaiting a response then fail.
+- `--no-session` starts and package commands (`pd install`, `pd update`, ...)
+  run Pi directly.
+
+A host keeps the options and environment of the process that started it, as
+Pi reads them only at startup.
 
 A Session running outside a host still appears in the workbench, but can be
 attached only after it exits.
@@ -61,26 +81,20 @@ attached only after it exits.
 Only one terminal is attached at a time. A new terminal takes over, and the
 previous one is told how to reattach.
 
-On attach, the host restores the screen and the terminal modes Pi has set
-(keyboard protocols, bracketed paste, mouse, title, program status). Images
-come back when the host then has Pi redraw.
-
-A host started from a terminal waits for that terminal to attach before it
-starts Pi, so Pi detects the terminal's colors and keyboard protocol just as it
-would without a host. A host started in the background passes the queries Pi
-sent at startup to the first terminal that attaches, and Pi finishes detecting
-then.
+On attach, the host restores Pi's screen and the terminal modes Pi has set.
+Pi detects the colors and keyboard protocol of the first terminal that
+attaches, as it would without a host.
 
 Closing the window, pressing `Ctrl+Z` (the `pi-agents.detach` keybinding), or
 running `/detach` detaches. The Session keeps running, and the terminal prints:
 
-    Pi keeps running. To reattach, run pd attach <session>
+    Pi keeps running. To reattach: pd attach <session>
 
-A host disables suspend, since a suspended Pi would stay stopped; `Ctrl+Z`
-detaches in its place.
+A host disables Pi's suspend.
 
-A detached Session exits once its tree has had no live work for 5 minutes. A
-message to a Session that is not running starts it in a host, detached.
+A detached Session exits after 10 minutes with no live work in its tree and no
+`pd --mode rpc` connected. A message to a Session that is not running starts it
+in a host, detached.
 
 ## 5. Workbench
 
@@ -95,7 +109,7 @@ Running owned Agents and Programs are counted, as in `3 agents running`.
 
 Rows are grouped by state, newest first in each group:
 
-- **Needs input**: a dialog waiting for the user, or a finished turn the user
+- **Needs attention**: a dialog waiting for the user, or a finished turn the user
   has not seen. A turn that failed after Pi's retries, or a host that exited
   abnormally, is marked failed.
 - **Working**: the Session or its tree has live work.
@@ -109,8 +123,7 @@ shows Pi's logo, the size of each group, and key hints.
 A turn counts as seen once it has been shown in an attached terminal or a
 preview. Sessions
 from before the workbench start out seen. A Session that holds its lock but is
-not reporting to the daemon, as while its Pi exits, shows as unknown (`?`); the
-daemon checks it again every second until that changes.
+not reporting to the daemon, as while its Pi exits, shows as unknown (`?`).
 
 Keys:
 
@@ -123,9 +136,10 @@ Keys:
   previewed Session. In the preview:
   - `Enter` sends a typed message; with none typed, it attaches.
   - `Ctrl+O` (`app.tools.expand`) attaches.
-  - The page keys of fullscreen mode (`tui.altScreen.pageUp`/`pageDown`)
-    scroll; with no message typed, `↑`/`↓` scroll too.
+  - It scrolls as fullscreen mode does; with no message typed, `↑`/`↓`
+    scroll too.
   - `Esc` clears a typed message; with none typed, it closes the preview.
+  - `Ctrl+Z` closes the preview.
 - `Ctrl+X` stops the current turn, as `app.interrupt` does.
 - `Ctrl+D` removes the selected Session from the list. Its file stays, and
   `/resume` brings it back. An idle Session in a host that no terminal is
@@ -154,9 +168,7 @@ Sessions reconnect to the new daemon.
 
 ## 7. Platform
 
-macOS and Linux. Every dependency is pure JavaScript or prebuilt: hosts use
-`@lydell/node-pty`, and a Session lock is a file that records the process
-holding it.
+macOS and Linux.
 
 ## Not in this version