@tshu-w/pi-agents 0.1.1 → 0.2.1

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,30 +1,36 @@
 #!/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, hostSessionFile, 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';
+import { defaultSessionDir, resolvePath, sessionDir, statePaths } from '../src/roots/paths.mjs';
 import { piPackage } from '../src/pi.mjs';
 import { markedFiles } from '../src/daemon/sessions.mjs';
+import { argGroups } from '../src/host/rpc-client.mjs';
 
 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 dist = file => import(pathToFileURL(join(piPackage(real), 'dist', file)).href);
+// Pi's own parsing, so that `pd` reads every argument as `pi` does.
+const { parseArgs } = await dist('cli/args.js');
+const { ENV_SESSION_DIR, getAgentDir } = await dist('config.js');
+const parsed = parseArgs(args);
 
 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']);
 
 function runDirectly() {
   const child = spawn(real, args, { stdio: 'inherit' });
@@ -39,60 +45,80 @@ function runDirectly() {
   });
 }
 
-function option(name, alias) {
-  for (let i = 0; i < args.length; i++) {
-    if (args[i] === '--') return;
-    if (args[i] === name || args[i] === alias) return args[i + 1] ?? '';
-    if (args[i].startsWith(`${name}=`)) return args[i].slice(name.length + 1);
-  }
+function error(text) {
+  return styleText('red', text, { stream: process.stderr });
 }
 
 
-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(getAgentDir())), 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) {
-  const session = option('--session');
+/** The running host already holding the Session that `--session`, `--session-id`, or `-c` would open. */
+async function runningTarget() {
+  let running;
+  const { session, sessionId } = parsed;
   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) || hostSessionFile(host) === file);
+  } else if (sessionId && parsed.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 = await sessionDirOption() ?? defaultSessionDir(process.cwd(), getAgentDir());
+    running = host => host.session && (file
+      ? hostSessionFile(host) === file
+      : host.session.id === sessionId && dirname(hostSessionFile(host)) === directory && host.session.cwd === process.cwd());
+  } else if (parsed.continue) {
     const file = await recentSession();
-    return file && hosts.find(host => host.session?.file === file);
+    if (file) running = host => hostSessionFile(host) === 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 fallback = defaultSessionDir(process.cwd());
+  const { findMostRecentSession } = await dist('core/session-manager.js');
+  const configured = await sessionDirOption();
+  const fallback = defaultSessionDir(process.cwd(), getAgentDir());
   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 dist('core/session-manager.js');
+  return SessionManager.findById(process.cwd(), id, await sessionDirOption());
+}
+
+/** The session directory configured for Pi in this cwd, as Pi resolves it: `--session-dir`, its environment variable, then its settings. */
+async function sessionDirOption() {
+  const configured = parsed.sessionDir || process.env[ENV_SESSION_DIR] || (await dist('core/settings-manager.js')).SettingsManager.create(process.cwd(), getAgentDir()).getSessionDir();
+  return configured ? resolvePath(configured) : undefined;
+}
+
 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 +130,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 +142,18 @@ async function attachCommand(query) {
   return attachAndReport(socket);
 }
 
+/** Warns about the options a running Session does not apply. */
+function warnIgnored(options) {
+  const ignored = argGroups(parseArgs, options).filter(([option]) => !['--session', '--session-id', '--session-dir', '-c', '--continue'].includes(option)).flat();
+  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() {
+  if (parsed.mode === 'json' || parsed.mode === 'rpc') return parsed.mode;
+  if (!interactive || parsed.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 +161,24 @@ 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]) || parsed.help || parsed.version || parsed.export !== undefined || parsed.listModels !== undefined || parsed.noSession) {
+  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/HOSTS.md

@@ -0,0 +1,111 @@
+# Hosted Sessions
+
+## 1. Overview
+
+`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:
+
+- **Host**: one per Session. It runs Pi's full TUI in a pseudo-terminal and relays it to whichever terminal is attached.
+- **Daemon**: one per user. It tracks Sessions, delivers messages, and starts hosts.
+- **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 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.
+- `host.log`, `daemon.log`: logs.
+
+Sockets and Session locks go in `$XDG_RUNTIME_DIR/pi-agents/`. macOS has no `XDG_RUNTIME_DIR`, so there they go in `runtime/` under the state directory.
+
+## 2. Setup
+
+Install with npm to get the `pd` command, also named `pi-agents`, then have Pi load the extension from the same copy, so the command and the extension are always the same version:
+
+```sh
+npm install -g @tshu-w/pi-agents
+pi install "$(npm root -g)/@tshu-w/pi-agents"
+```
+
+`pd` runs whichever `pi` is on `PATH`. Sessions started with plain `pi` also load the extension, but run outside hosts and end with their terminal.
+
+## 3. Commands
+
+- `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, 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 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.
+
+## 4. Attach and detach
+
+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 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` (`pi-agents.detach`), or running `/detach` detaches. The Session keeps running, and the terminal prints:
+
+```text
+Pi keeps running. To reattach: pd attach <session>
+```
+
+A host disables Pi's suspend.
+
+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
+
+The list shows running Sessions, Sessions that ran without a terminal (started here, woken by a message, or detached), Sessions opened here, and Sessions with an unseen turn. Older Sessions are reached with `/resume`.
+
+Each row shows a root Session's name and what it did last. The name is the Session name, or else the first line of its first message. While the Session works, the row shows the running tool; otherwise, the start of its last reply. Running owned Agents and Programs are counted, as in `3 agents running`.
+
+Rows are grouped by state, newest first in each group:
+
+- **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.
+- **Completed**: everything else.
+
+While a Session works, its icon spins. Otherwise the shape tells whether Pi is still running (`●`) or has exited (`○`), and the color marks a finished (green) or failed (red) turn, or a dialog waiting for the user (yellow). The header 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 (`?`).
+
+Keys:
+
+- `Enter` (`tui.select.confirm`) attaches; detaching returns here.
+- `Space` previews the selected Session below the list: the conversation since the last compaction, with thinking left out, and each run of tool calls, branch summary, and custom message folded to one line, such as `... (6 tool calls: bash, read, edit)`. The preview follows the Session as it works. The input keeps `@<session>` at its start, so a message goes to the previewed Session. In the preview:
+  - With no message typed, `Enter` attaches, as `Ctrl+O` (`app.tools.expand`) always does.
+  - It scrolls as fullscreen mode does; with no message typed, `↑`/`↓` (`tui.select.up`/`tui.select.down`) scroll too.
+  - `Esc` (`tui.select.cancel`) clears a typed message; with none typed, it or `Space` closes the preview, as `Ctrl+Z` always does.
+- `Ctrl+X` stops the current turn, as `app.interrupt` does.
+- `Ctrl+D` (`app.session.delete`) 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 attached to quits first; any other running Session must quit itself.
+- `Ctrl+Z` (`pi-agents.detach`) exits the workbench, as detaching leaves a Session; every Session keeps running.
+
+The input at the bottom:
+
+- `@` on an empty input opens Pi's session picker. The chosen Session is selected in the list, and the input starts with `@<session>`; the text after it goes to that Session as a user message.
+- `/resume` opens Pi's session picker over all directories, newest first, and attaches the chosen Session.
+- `/quit` exits the workbench, as do `Esc` and `Ctrl+C` (`app.clear`) twice on an empty input.
+- Any other text starts a new Session in the current directory with Pi's default settings, detached.
+
+## 6. Upgrades
+
+A host keeps running the version it started with until its Session exits. When the daemon sees a newer pi-agents version, it restarts once idle, and Sessions reconnect to the new daemon.
+
+## 7. Platform
+
+macOS and Linux.
+
+## Not in this version
+
+Attaching several terminals to one Session, Sessions on other machines, model-written summaries, and a confirmation before quitting while work is running. Keeping Sessions alive across host crashes and reboots needs a durable runtime, which [Pi Durable](https://earendil.com/posts/pi-durable/) explores.