@tshu-w/pi-agents 0.0.0-stage → 0.1.1

package/README.md

@@ -1,3 +1,82 @@
-# Temporary Holding Version
+# pi-agents
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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
+
+<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.
+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.
+7. Type a message in the preview to send it to the Session.
+8. `Enter` attaches to the Session with the reply.
+
+</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/).
+- **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.
+
+## Install
+
+```sh
+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`.
+
+To use only the extension, without the workbench:
+
+```sh
+pi install npm:@tshu-w/pi-agents
+```
+
+## Usage
+
+| 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 |
+| `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
+"pi-agents": {
+  "maxConcurrent": 3,
+  "maxOutstanding": 8,
+  "extensions": []
+}
+```
+
+Concurrency limits per root, and extensions loaded by child Agents.
+
+## Docs
+
+- [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
+
+## 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.
+
+## License
+
+[AGPL-3.0](LICENSE)

package/bin/daemon.mjs

@@ -0,0 +1,204 @@
+// The per-user daemon: tracks root Sessions, routes messages between them, and starts a host for
+// a Session that is offline. Runs while a Session or the workbench is connected, exits once idle
+// otherwise, and restarts once idle after pi-agents is updated.
+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 { acquireLock, pruneLocks, reserve } from '../src/roots/locks.mjs';
+import { prepareDirectory, statePaths } from '../src/roots/paths.mjs';
+import { findRoot } from '../src/roots/discovery.mjs';
+import { listen, request } from '../src/roots/transport.mjs';
+import { recoverSocket } from '../src/roots/socket-recovery.mjs';
+import { createSessions } from '../src/daemon/sessions.mjs';
+import { createRouter } from '../src/daemon/router.mjs';
+import { codeVersion } from '../src/daemon/version.mjs';
+
+const [sessionDir] = process.argv.slice(2);
+if (!sessionDir) throw new Error('Daemon requires the session directory');
+const paths = statePaths();
+await prepareDirectory(paths.runtime);
+let lock;
+try { lock = acquireLock({ stateDir: paths.locks, sessionId: 'daemon' }); }
+catch (error) { if (error.code === 'SESSION_OCCUPIED') process.exit(0); throw error; }
+pruneLocks(paths.locks);
+const IDLE_MS = 30000;
+const PUBLISH_MS = 250;
+const RECHECK_MS = 1000;
+const version = await codeVersion();
+let waking = 0, delivering = 0, lastActivity = Date.now(), retiring = false, closing = false;
+const stop = new AbortController();
+const sessions = await createSessions(paths, sessionDir);
+const workbenches = new Set();
+const channels = new Map();
+
+/** The model Pi restores for the Session: the last one set or used on its active branch, which ends at its last entry. */
+async function savedModel(file, signal) {
+  const entries = new Map();
+  let leaf;
+  for (const line of (await readFile(file, { encoding: 'utf8', signal })).split('\n')) {
+    let entry;
+    try { entry = JSON.parse(line); } catch { continue; }
+    if (typeof entry?.id !== 'string' || entry.type === 'session') continue;
+    entries.set(entry.id, entry);
+    leaf = entry;
+  }
+  for (let entry = leaf; entry; entry = entries.get(entry.parentId)) {
+    if (entry.type === 'model_change') return { provider: entry.provider, modelId: entry.modelId };
+    if (entry.type === 'message' && entry.message?.role === 'assistant') return { provider: entry.message.provider, modelId: entry.message.model };
+  }
+}
+
+/** 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;
+      }
+    } catch (error) {
+      signal.throwIfAborted();
+      if (!['ENOENT', 'ECONNREFUSED'].includes(error.code)) throw error;
+    }
+    await delay(50, undefined, { signal });
+  }
+}
+
+const router = createRouter({
+  deliverToSession: (message, options) => request(paths.session(message.recipient), { action: 'deliver', message }, options),
+  async wake(id, { signal, launch }) {
+    if (!launch) throw Object.assign(new Error(`Agent ${id} is offline`), { code: 'OFFLINE' });
+    waking++;
+    try {
+      const combined = AbortSignal.any([signal, stop.signal]);
+      const root = await findRoot(sessionDir, id, { extraFiles: sessions.files(), signal: combined });
+      if (!root) throw Object.assign(new Error(`No root Agent ${id}`), { code: 'UNKNOWN_AGENT' });
+      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();
+      // 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}`] : [])];
+      const socket = await startHost(paths, { pi: launch.command, args, cwd: root.cwd, env: launch.env });
+      try { await ready(root, model, combined); }
+      catch (error) {
+        // A Session that cannot take the message does not stay running unseen.
+        try { process.kill(Number(/h-(\d+)\.sock$/.exec(socket)[1]), 'SIGTERM'); } catch {}
+        throw error;
+      }
+    } finally { waking--; lastActivity = Date.now(); }
+  },
+});
+
+let publishing;
+function changed() {
+  if (publishing || !workbenches.size) return;
+  publishing = delay(PUBLISH_MS).then(async () => {
+    publishing = undefined;
+    const list = await sessions.list();
+    for (const workbench of workbenches) workbench.send({ type: 'sessions', sessions: list });
+    // A Pi that reported its end holds the Session lock until it exits, which nothing else announces.
+    if (list.some(row => row.status === 'unknown')) setTimeout(changed, RECHECK_MS).unref();
+  }).catch(error => console.error(`[pi-agents] Listing Sessions failed: ${error.message}`));
+}
+
+const text = value => typeof value === 'string' ? value : undefined;
+function sessionState(value) {
+  if (!value || typeof value !== 'object' || typeof value.id !== 'string' || !value.id) return;
+  const turn = value.turn && Number.isFinite(value.turn.at) ? { at: value.turn.at, failed: value.turn.failed === true } : undefined;
+  return {
+    id: value.id, sessionFile: text(value.sessionFile), cwd: text(value.cwd), name: text(value.name), title: text(value.title),
+    host: text(value.host), attached: value.attached === true, working: value.working === true, blocked: value.blocked === true,
+    tool: text(value.tool), reply: text(value.reply), agents: Number.isSafeInteger(value.agents) ? value.agents : 0,
+    ...(turn ? { turn } : {}),
+  };
+}
+
+function openSession(channel) {
+  const reported = new Set();
+  channel.onMessage(message => {
+    if (message?.type === 'state') {
+      const state = sessionState(message.state);
+      if (!state) return;
+      reported.add(state.id);
+      channels.set(state.id, channel);
+      sessions.update(state);
+    } else if (message?.type === 'end' && typeof message.id === 'string' && reported.delete(message.id)) {
+      if (channels.get(message.id) === channel) channels.delete(message.id);
+      sessions.end(message.id);
+    } else return;
+    changed();
+  });
+  channel.signal.addEventListener('abort', () => {
+    lastActivity = Date.now();
+    if (closing) return;
+    for (const id of reported) {
+      if (channels.get(id) === channel) channels.delete(id);
+      sessions.end(id, { abnormal: true });
+    }
+    changed();
+  }, { once: true });
+}
+
+function openWorkbench(channel) {
+  workbenches.add(channel);
+  channel.onMessage(message => {
+    if (typeof message?.id !== 'string') return;
+    if (message.type === 'interrupt') channels.get(message.id)?.send({ type: 'interrupt', id: message.id });
+    else if (message.type === 'show' || message.type === 'hide' || message.type === 'see') {
+      sessions[message.type](message.id);
+      changed();
+    }
+  });
+  channel.signal.addEventListener('abort', () => { workbenches.delete(channel); lastActivity = Date.now(); }, { once: true });
+  void sessions.list().then(list => channel.send({ type: 'sessions', sessions: list }),
+    error => console.error(`[pi-agents] Listing Sessions failed: ${error.message}`));
+}
+
+await recoverSocket(paths.daemon);
+const server = await listen(paths.daemon, {
+  serialize: false,
+  status: () => ({ ready: true, pid: process.pid, version }),
+  async accept(message, options) {
+    delivering++;
+    try { return await router.accept(message, options); }
+    finally { delivering--; }
+  },
+  stream(input, channel) {
+    lastActivity = Date.now();
+    // A newly started Pi may run updated code; this daemon then hands over once idle.
+    void codeVersion().then(current => { if (current !== version) retiring = true; }, () => {});
+    if (input.role === 'workbench') openWorkbench(channel);
+    else openSession(channel);
+  },
+});
+
+const idleTimer = setInterval(() => {
+  if (closing || waking || delivering) return;
+  if (retiring) return shutdown(server.close());
+  if (Date.now() - lastActivity < IDLE_MS) return;
+  const closed = server.closeIfIdle(IDLE_MS);
+  if (closed) shutdown(closed);
+}, 1000);
+
+// Connected Sessions reconnect to the next daemon.
+function shutdown(closed = server.close()) {
+  if (closing) return;
+  closing = true;
+  clearInterval(idleTimer);
+  stop.abort();
+  void closed.finally(async () => {
+    await sessions.saved();
+    lock.release();
+    process.exit(0);
+  });
+}
+process.once('SIGTERM', () => shutdown());
+process.once('SIGINT', () => shutdown());

package/bin/host.mjs

@@ -0,0 +1,170 @@
+// Runs one interactive Pi in a pseudo-terminal and relays it to at most one attached terminal.
+// Started detached by `pi` or the daemon; exits when Pi exits.
+import { rmSync } from 'node:fs';
+import net from 'node:net';
+import { createRequire } from 'node:module';
+import { FRAME, frame, json, readFrames } from '../src/host/frames.mjs';
+import { prepareDirectory, statePaths } from '../src/roots/paths.mjs';
+
+const require = createRequire(import.meta.url);
+const pty = require('@lydell/node-pty');
+const { Terminal } = require('@xterm/headless');
+const { SerializeAddon } = require('@xterm/addon-serialize');
+
+const config = JSON.parse(process.env.PI_AGENTS_HOST_CONFIG);
+const paths = statePaths();
+const socketPath = paths.host(process.pid);
+
+// Terminal modes Pi sets that the screen mirror does not keep; replayed to each newly attached terminal.
+const MODE = /\x1b\[>\d*u|\x1b\[<\d*u|\x1b\[>4;\d*m|\x1b\[\?(?:2031|2004|1000|1002|1003|1006|1004|25)[hl]|\x1b\](?:0|2|7501);[^\x07\x1b]*(?:\x07|\x1b\\)/g;
+const modes = new Map();
+function trackModes(data) {
+  for (const [sequence] of data.matchAll(MODE)) {
+    if (sequence.startsWith('\x1b[<')) modes.delete('keyboard');
+    else if (sequence.startsWith('\x1b[>4;')) modes.set('modifyOtherKeys', sequence);
+    else if (sequence.startsWith('\x1b[>')) modes.set('keyboard', sequence);
+    else if (sequence.startsWith('\x1b[?')) modes.set(sequence.slice(0, -1), sequence);
+    // Program status (OSC 7501): Pi reports it only on change, so a terminal attaching later needs the last one.
+    else if (sequence.startsWith('\x1b]7501;state=clear')) modes.delete('status');
+    else if (sequence.startsWith('\x1b]7501;')) modes.set('status', sequence);
+    else modes.set('title', sequence);
+  }
+}
+
+// Pi's startup queries: keyboard protocol, program status, device attributes, and colors. Pi waits for the
+// replies, so those it sent before any terminal attached are passed to the first one.
+const QUERY = /\x1b\[\?u|\x1b\[c|\x1b\]7501;\?[^\x07\x1b]*(?:\x07|\x1b\\)|\x1b\](?:10|11|4;\d+);\?(?:\x07|\x1b\\)/g;
+let queries = '';
+let attachedOnce = false;
+
+// Pi's output may split a control sequence across chunks; its unfinished end waits for the next chunk.
+const SEQUENCE = /^(?:\x1b\[[0-?]*[ -/]*[@-~]|\x1b\][^\x07\x1b]*(?:\x07|\x1b\\))/;
+let partial = '';
+function completed(data) {
+  const text = partial + data;
+  const start = Math.max(text.lastIndexOf('\x1b['), text.lastIndexOf('\x1b]'));
+  const end = start >= 0 && !SEQUENCE.test(text.slice(start)) ? start : text.endsWith('\x1b') ? text.length - 1 : text.length;
+  partial = text.length - end > 4096 ? '' : text.slice(end);
+  return text.slice(0, end);
+}
+
+const COLOR_SCHEME_REPORT = /\x1b\[\?997;([12])n/;
+const COLOR_SCHEME_WAIT_MS = 300;
+let colorScheme = '1';
+let session, terminal, control, child;
+
+await prepareDirectory(paths.runtime);
+rmSync(socketPath, { force: true });
+
+const env = { ...process.env, PI_AGENTS_HOST: socketPath, PI_AGENTS_HOST_PID: String(process.pid) };
+delete env.PI_AGENTS_HOST_CONFIG;
+const mirror = new Terminal({ cols: config.cols, rows: config.rows, allowProposedApi: true, scrollback: 1000 });
+const serializer = new SerializeAddon();
+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 });
+  child.onData(data => {
+    const text = completed(data);
+    trackModes(text);
+    if (!attachedOnce) for (const [query] of text.matchAll(QUERY)) queries += query;
+    mirror.write(data);
+    terminal?.socket.write(frame(FRAME.data, data));
+  });
+  child.onExit(({ exitCode }) => {
+    server.close();
+    rmSync(socketPath, { force: true });
+    // Pi's last output can arrive after its exit; let it through before the final frame.
+    setTimeout(() => {
+      terminal?.socket.end(frame(FRAME.exited, { session, exitCode }));
+      setTimeout(() => process.exit(0), 100).unref();
+    }, 100);
+  });
+}
+// Started for a terminal, Pi waits for it, so its startup queries reach the terminal.
+if (!config.waitForTerminal) start(config);
+else setTimeout(() => { if (!child) process.exit(0); }, 10000).unref();
+
+function resize({ cols, rows }) {
+  mirror.resize(cols, rows);
+  child.resize(cols, rows);
+}
+
+// Moves the cursor below the screen's content, so what the terminal prints next does not overwrite it.
+function belowContent() {
+  const buffer = mirror.buffer.active;
+  if (buffer.type !== 'normal') return '';
+  const cursor = buffer.baseY + buffer.cursorY;
+  let last = buffer.length - 1;
+  while (last > cursor && !buffer.getLine(last)?.translateToString(true).trim()) last--;
+  return last > cursor ? `\x1b[${last - cursor}B` : '';
+}
+
+function detach(reason) {
+  terminal.socket.write(frame(FRAME.data, belowContent()));
+  terminal.socket.end(frame(FRAME.detached, { reason, session }));
+}
+
+function setAttached(next) {
+  if (terminal && next !== terminal) detach('takeover');
+  terminal = next;
+  control?.write(frame(FRAME.control, { type: 'attached', attached: Boolean(terminal) }));
+}
+
+function attach(socket, size) {
+  const next = { socket, colorReply: false };
+  setAttached(next);
+  const first = !attachedOnce;
+  attachedOnce = true;
+  if (!child) return start(size);
+  resize(size);
+  socket.write(frame(FRAME.data, '\x1b[H\x1b[2J' + serializer.serialize() + [...modes.values()].join('') + (first ? queries : '') + partial));
+  queries = '';
+  // Pi re-queries the terminal's colors when it receives a color scheme report.
+  if (modes.get('\x1b[?2031') === '\x1b[?2031h') {
+    socket.write(frame(FRAME.data, '\x1b[?996n'));
+    setTimeout(() => { if (terminal === next && !next.colorReply) child.write(`\x1b[?997;${colorScheme}n`); }, COLOR_SCHEME_WAIT_MS);
+  }
+  // A size change makes Pi redraw, which brings back images the mirror cannot keep.
+  child.resize(Math.max(size.cols - 1, 1), size.rows);
+  setTimeout(() => { if (terminal === next) child.resize(size.cols, size.rows); }, 100);
+}
+
+function status() {
+  return { pid: process.pid, cwd: config.cwd, session, attached: Boolean(terminal) };
+}
+
+const server = net.createServer(socket => {
+  socket.on('error', () => {});
+  readFrames(socket, (type, body) => {
+    if (type === FRAME.status) socket.end(frame(FRAME.status, status()));
+    else if (type === FRAME.attach) attach(socket, json(body));
+    else if (type === FRAME.resize && terminal?.socket === socket && child) resize(json(body));
+    else if (type === FRAME.detached && terminal?.socket === socket) {
+      detach('detach');
+      setAttached(undefined);
+    }
+    else if (type === FRAME.data && terminal?.socket === socket && child) {
+      const reply = body.toString('latin1').match(COLOR_SCHEME_REPORT);
+      if (reply) { terminal.colorReply = true; colorScheme = reply[1]; }
+      child.write(body);
+    } else if (type === FRAME.control) {
+      control = socket;
+      const message = json(body);
+      if (message.type === 'session') session = message.session;
+      else if (message.type === 'detach' && terminal) {
+        detach('detach');
+        setAttached(undefined);
+      }
+      socket.write(frame(FRAME.control, { type: 'attached', attached: Boolean(terminal) }));
+    }
+  });
+  socket.on('close', () => {
+    if (terminal?.socket === socket) setAttached(undefined);
+    if (control === socket) control = undefined;
+  });
+});
+server.listen(socketPath);
+process.on('SIGHUP', () => {});
+process.on('SIGTERM', () => child ? child.kill('SIGTERM') : process.exit(0));

package/bin/pd.mjs

@@ -0,0 +1,139 @@
+#!/usr/bin/env node
+// The `pd` command: runs interactive Pi in a host and attaches this terminal; everything else
+// runs 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 { pathToFileURL } from 'node:url';
+import { attach, listHosts, 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 { piPackage } from '../src/pi.mjs';
+import { markedFiles } from '../src/daemon/sessions.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.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']);
+
+function runDirectly() {
+  const child = spawn(real, args, { stdio: 'inherit' });
+  // The terminal delivers Ctrl+C to Pi too; Pi decides what it means.
+  process.on('SIGINT', () => {});
+  child.on('exit', (code, signal) => {
+    if (signal) {
+      process.removeAllListeners(signal);
+      process.kill(process.pid, signal);
+    }
+    else process.exit(code ?? 1);
+  });
+}
+
+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);
+  }
+}
+
+
+async function attachAndReport(socket) {
+  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())) });
+  const id = result.session?.id;
+  if (result.reason === 'exited') process.exit(result.exitCode ?? 0);
+  if (result.reason === 'closed') {
+    process.stderr.write(`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);
+}
+
+/** The running host already holding the Session that `--session` or `-c` would open. */
+async function runningTarget(hosts) {
+  const session = option('--session');
+  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')) {
+    const file = await recentSession();
+    return file && hosts.find(host => host.session?.file === file);
+  }
+}
+
+/** 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 directory = configured ?? fallback;
+  // A configured directory may hold other cwds' Sessions.
+  return findMostRecentSession(directory, directory === fallback ? undefined : process.cwd()) ?? undefined;
+}
+
+async function attachCommand(query) {
+  if (!query) {
+    process.stderr.write('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));
+  if (hosted.length === 1) return attachAndReport(hosted[0].socket);
+  let roots = [];
+  if (!hosted.length) {
+    const extraFiles = await markedFiles(paths);
+    const exact = await findRoot(sessionDir(), query, { extraFiles });
+    roots = exact ? [exact] : (await discoverRoots(sessionDir(), { extraFiles }))
+      .filter(root => root.id.startsWith(query) || root.name === 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`);
+    process.exit(1);
+  }
+  const [root] = roots;
+  const socket = await startHost(paths, {
+    pi: real, args: ['--session', root.sessionFile], cwd: root.cwd,
+    cols: process.stdout.columns, rows: process.stdout.rows, waitForTerminal: true,
+  });
+  return attachAndReport(socket);
+}
+
+const interactive = process.stdin.isTTY && process.stdout.isTTY;
+if (args[0] === 'attach' && interactive) await attachCommand(args[1]);
+else if (args[0] === 'agents' && interactive) {
+  const { workbench } = await import('../src/workbench.mjs');
+  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 {
+  const running = await runningTarget(await listHosts(paths));
+  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`);
+  }
+  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);
+}