@anhlp/alp-client 0.0.0-stage → 0.0.1-beta.4

package/src/integration-lock.js

@@ -0,0 +1,179 @@
+import { randomUUID } from 'node:crypto';
+import { mkdir, open, rename, rmdir, unlink } from 'node:fs/promises';
+import path from 'node:path';
+import { assertIntegrationName, bootTime } from './index.js';
+
+/**
+ * @typedef {{ pid: number, bootTime: number, startedAt: string, ready: boolean, lockVersion?: number, owner?: string }} IntegrationLockRecord
+ * @typedef {{
+ *   acquire(): Promise<{ acquired: boolean, lock: IntegrationLockRecord }>,
+ *   setReady(ready: boolean): Promise<boolean>,
+ *   release(): Promise<boolean>,
+ * }} IntegrationLock
+ */
+
+/**
+ * The single-owner lock of one integration service, at `<home>/integrations/<name>.lock`, with its
+ * mutation guard `<name>.lock.reclaim`. Each instance is single-use: acquire once, then setReady and
+ * release while it owns the lock.
+ *
+ * Single-host, same PID namespace, private local filesystem only. Never reap the mutation guard.
+ * @param {string} home the ALP_HOME the integration runs under
+ * @param {string} name the integration name, for example `web`
+ * @returns {IntegrationLock}
+ */
+export function createIntegrationLock(home, name) {
+  const file = path.join(home, 'integrations', `${assertIntegrationName(name)}.lock`);
+  const guard = `${file}.reclaim`;
+  /** @type {'new' | 'acquiring' | 'owned' | 'retired'} */
+  let phase = 'new';
+  /** This instance's lock while it owns it: the lifetime nonce and the file's identity. @type {{ owner: string, dev: number, ino: number } | undefined} */
+  let owned;
+  // The lock file as read: its record and the stats of the handle it was read through. Kept inside
+  // the factory so the published declarations name only IntegrationLock and its record.
+  /** @typedef {{ value: any, info: import('node:fs').Stats }} Snapshot */
+  /** @param {string} reason */
+  const recovery = reason => new Error(`${reason}. Stop ALL integration processes using this ALP_HOME before manual lock-only recovery of ${file} and ${guard}; see docs/modular-monorepo.md`);
+
+  /**
+   * @template T
+   * @param {() => Promise<T>} run
+   * @returns {Promise<T>}
+   */
+  async function guarded(run) {
+    await mkdir(path.dirname(file), { recursive: true, mode: 0o700 });
+    const deadline = Date.now() + 20_000;
+    for (;;) {
+      try { await mkdir(guard, { mode: 0o700 }); break; }
+      catch (error) {
+        if (/** @type {any} */ (error)?.code !== 'EEXIST') throw error;
+        if (Date.now() >= deadline) throw recovery('Integration mutation guard remains busy or abandoned');
+        await new Promise(resolve => setTimeout(resolve, 25));
+      }
+    }
+    const token = path.join(guard, `owner-${process.pid}-${randomUUID()}`);
+    // If token initialization/close fails, leave the guard: no speculative cleanup of shared paths.
+    try {
+      const handle = await open(token, 'wx', 0o600);
+      await handle.close();
+    } catch (error) { throw recovery(`Integration guard initialization failed: ${String(error)}`); }
+    try { return await run(); }
+    finally {
+      // Only this successful mkdir owner finalizes, once. Missing token may mean a replacement
+      // generation: never rmdir in that case. No contender removes any other owner's token.
+      try { await unlink(token); }
+      catch (error) { throw recovery(/** @type {any} */ (error)?.code === 'ENOENT' ? 'Integration guard ownership was lost' : `Integration guard token cleanup failed: ${String(error)}`); }
+      try { await rmdir(guard); }
+      catch (error) { throw recovery(`Integration guard cleanup failed: ${String(error)}`); }
+    }
+  }
+
+  /** @returns {Promise<Snapshot | undefined>} */
+  async function snapshot() {
+    let handle;
+    try { handle = await open(file, 'r'); }
+    catch (error) { if (/** @type {any} */ (error)?.code === 'ENOENT') return undefined; throw error; }
+    try {
+      const info = await handle.stat();
+      const raw = await handle.readFile('utf8');
+      let value;
+      try { value = JSON.parse(raw); } catch { value = undefined; }
+      return { value, info };
+    } finally { await handle.close(); }
+  }
+
+  /**
+   * @param {any} value
+   * @returns {value is IntegrationLockRecord}
+   */
+  function complete(value) {
+    return value && Number.isSafeInteger(value.pid) && value.pid > 0
+      && typeof value.bootTime === 'number' && Number.isFinite(value.bootTime) && value.bootTime > 0
+      && typeof value.startedAt === 'string' && Number.isFinite(Date.parse(value.startedAt))
+      && typeof value.ready === 'boolean'
+      && (value.lockVersion === undefined && value.owner === undefined
+        || value.lockVersion === 1 && typeof value.owner === 'string' && /^[a-f0-9-]{36}$/.test(value.owner));
+  }
+
+  /**
+   * @param {IntegrationLockRecord} value
+   * @returns {boolean}
+   */
+  function dead(value) {
+    try { process.kill(value.pid, 0); return false; }
+    catch (error) {
+      if (/** @type {any} */ (error)?.code !== 'ESRCH') return false; // EPERM and unknown errors never grant takeover.
+      // Approximate wall-clock boot metadata is context, never affirmative death evidence.
+      if (Math.abs(value.bootTime - bootTime()) > 30) throw recovery('Integration owner boot context is uncertain');
+      return true;
+    }
+  }
+
+  /**
+   * @param {Snapshot | undefined} current
+   * @returns {boolean}
+   */
+  function matches(current) {
+    return !!owned && current?.value?.owner === owned.owner
+      && current.info.dev === owned.dev && current.info.ino === owned.ino;
+  }
+
+  return {
+    async acquire() {
+      if (phase !== 'new') throw new Error('Integration lock instance has already been used');
+      phase = 'acquiring';
+      try {
+        return await guarded(async () => {
+          const current = await snapshot();
+          if (current) {
+            if (!complete(current.value)) throw recovery('Integration lock is malformed, incomplete or unsupported');
+            if (!dead(current.value)) { phase = 'retired'; return { acquired: false, lock: current.value }; }
+            await unlink(file);
+          }
+          /** @type {IntegrationLockRecord & { owner: string }} */
+          const value = { pid: process.pid, bootTime: bootTime(), startedAt: new Date().toISOString(), ready: false, lockVersion: 1, owner: randomUUID() };
+          const handle = await open(file, 'wx', 0o600);
+          let info;
+          try { await handle.writeFile(JSON.stringify(value)); info = await handle.stat(); }
+          finally { await handle.close(); }
+          owned = { owner: value.owner, dev: info.dev, ino: info.ino };
+          phase = 'owned';
+          return { acquired: true, lock: value };
+        });
+      } catch (error) { phase = 'retired'; owned = undefined; throw error; }
+    },
+
+    async setReady(ready) {
+      if (phase !== 'owned') return false;
+      return guarded(async () => {
+        if (phase !== 'owned') return false;
+        const current = await snapshot();
+        if (!current || !matches(current)) { phase = 'retired'; owned = undefined; return false; }
+        const value = { ...current.value, ready };
+        const tmp = `${file}.${randomUUID()}.tmp`;
+        const handle = await open(tmp, 'wx', 0o600);
+        let info;
+        try {
+          try { await handle.writeFile(JSON.stringify(value)); info = await handle.stat(); }
+          finally { await handle.close(); }
+          await rename(tmp, file);
+          owned = { owner: value.owner, dev: info.dev, ino: info.ino };
+          return true;
+        } finally { await unlink(tmp).catch(error => { if (error?.code !== 'ENOENT') throw error; }); }
+      });
+    },
+
+    async release() {
+      if (phase !== 'owned') return false;
+      return guarded(async () => {
+        if (phase !== 'owned') return false;
+        const current = await snapshot();
+        const ours = matches(current);
+        phase = 'retired'; owned = undefined;
+        if (!ours) return false;
+        await unlink(file);
+        return true;
+      });
+    },
+  };
+}

package/src/ipc.js

@@ -0,0 +1,92 @@
+import { MAX_FRAME } from '@anhlp/alp-protocol';
+import { AlpClientError } from './rpc/errors.js';
+import { createLineDecoder } from './rpc/framing.js';
+
+/**
+ * The Node transport of the ALP client: a Unix socket or Windows named pipe carrying
+ * newline-delimited JSON (plans/reference/ALPD.md §3). Node-only; the portable engine
+ * (`@anhlp/alp-client/portable`) never imports it. Socket discovery, the private-socket checks
+ * and daemon startup stay in the Node entry (`connect`, `ensureDaemon`).
+ *
+ * @typedef {import('./rpc/client.js').AlpTransport} AlpTransport
+ * @typedef {import('./rpc/client.js').TransportClose} TransportClose
+ * @typedef {{ maxFrame?: number, maxBufferedBytes?: number }} SocketTransportOptions
+ *   `maxBufferedBytes` bounds what may wait in the socket's write buffer; a send beyond it fails
+ *   as `send_failed` instead of growing memory while the daemon does not read.
+ */
+
+/**
+ * Wraps a connected or still-connecting socket (writes made while it connects are queued by
+ * Node). The transport owns the socket from then on.
+ * @param {import('node:net').Socket} socket
+ * @param {SocketTransportOptions} [options]
+ * @returns {AlpTransport}
+ */
+export function createSocketTransport(socket, { maxFrame = MAX_FRAME, maxBufferedBytes = 4 * MAX_FRAME } = {}) {
+  const decoder = createLineDecoder({ maxFrame });
+  /** @type {Set<(frame: string) => void>} */
+  const messages = new Set();
+  /** @type {Set<(close: TransportClose) => void>} */
+  const closes = new Set();
+  /** @type {TransportClose | undefined} */
+  let ended;
+  /** @param {TransportClose} close */
+  const end = close => {
+    if (ended) return;
+    ended = close;
+    socket.off('data', onData);
+    messages.clear();
+    const listeners = [...closes];
+    closes.clear();
+    for (const listener of listeners) listener(close);
+  };
+  /** @param {string} chunk */
+  const onData = chunk => {
+    if (ended) return;
+    let frames;
+    try { frames = decoder.push(chunk); } catch {
+      const error = new AlpClientError('ALP daemon frame exceeds size limit', { reason: 'protocol' });
+      socket.destroy();
+      return end({ error });
+    }
+    for (const frame of frames) {
+      if (ended) return;
+      for (const listener of [...messages]) listener(frame);
+    }
+  };
+  socket.setEncoding('utf8');
+  socket.on('data', onData);
+  socket.on('error', error => end({ error }));
+  socket.on('close', () => end({}));
+  if (socket.destroyed) end({});
+  // A socket alpd has half-closed (Node ends our side at once) or destroyed is gone, even before
+  // Node emits 'close' a tick later.
+  const gone = () => socket.destroyed || socket.writableEnded;
+  return {
+    get state() { return ended || gone() ? 'closed' : 'open'; },
+    send(frame) {
+      // Report the close now rather than on 'close', so the client is closed when the send fails.
+      if (!ended && gone()) end({});
+      if (ended) throw new AlpClientError('ALP daemon connection closed', { reason: 'send_failed' });
+      if (socket.writableLength + frame.length > maxBufferedBytes) throw new AlpClientError(`ALP socket write buffer is over ${maxBufferedBytes} bytes`, { reason: 'send_failed' });
+      socket.write(`${frame}\n`);
+    },
+    onMessage(listener) {
+      if (ended) return () => false;
+      messages.add(listener);
+      return () => messages.delete(listener);
+    },
+    onClose(listener) {
+      if (ended) return () => false;
+      closes.add(listener);
+      return () => closes.delete(listener);
+    },
+    close() {
+      // end() lets frames already written reach the daemon, as the client always did; once they
+      // have, the socket is destroyed, so a peer that never closes its side cannot hold it open.
+      // A side already ended (by this, or by Node after alpd's FIN) is destroyed by Node itself.
+      if (!socket.writableEnded) socket.end(() => socket.destroy());
+      end({});
+    },
+  };
+}

package/src/library-test.js

@@ -0,0 +1,41 @@
+import path from 'node:path';
+import { AlpError } from '@anhlp/alp-core/errors';
+import { getEntry } from '@anhlp/alp-core/library-edit';
+import { runHook, samplePayload } from '@anhlp/alp-core/hook-run';
+import { normalizeMcp } from '@anhlp/alp-core/validation';
+import { probeMcp } from './mcp-probe.js';
+import { probeAcp } from './acp-probe.js';
+import { probeAntigravity } from './antigravity-probe.js';
+import { loadProvider } from '@anhlp/alp-core/providers';
+
+/**
+ * Tries an MCP server, a hook or an ACP provider out (ALPD §43, §46). An MCP server is
+ * started and its tools listed; a provider is started and initialized; a hook runs once with a sample payload for its event, in the project (or the
+ * library when there is none), with the variables ALP gives hooks.
+ */
+export async function testEntry(kind, name, { root, library, templates, scope, timeoutMs } = {}) {
+  const entry = await getEntry(kind, name, { root, library, templates, scope });
+  const home = entry.source === 'project' ? path.join(path.resolve(root), '.alp') : library;
+  if (kind === 'mcp') {
+    const server = normalizeMcp({ mcpServers: { [name]: entry.content.server } }, path.join(home, 'mcp'), `${name}.json`).mcpServers[name];
+    const result = await probeMcp(server, { cwd: root ? path.resolve(root) : library, ...(timeoutMs ? { timeoutMs } : {}) });
+    return { kind, name, source: entry.source, ok: true, ...result };
+  }
+  if (kind === 'hooks') {
+    const hook = entry.content.hook;
+    const project = root ? path.resolve(root) : undefined;
+    const payload = samplePayload(hook.event, { project, agent: hook.match?.agent ?? 'main' });
+    const env = { ALP_EVENT: hook.event, ALP_SESSION: payload.session, ALP_AGENT: payload.agent, ALP_PROJECT: project ?? '', ALP_TASK: payload.task ?? '' };
+    const result = await runHook(hook, payload, { cwd: project ?? library, env, ...(timeoutMs ? { timeoutMs } : {}) });
+    const ok = result.exitCode === 0 && !result.timedOut;
+    return { kind, name, source: entry.source, ok, ...(hook.blocking && !ok ? { wouldBlock: true } : {}), payload, ...result };
+  }
+  if (kind === 'providers') {
+    const provider = await loadProvider(library, name);
+    const result = provider.kind === 'antigravity'
+      ? await probeAntigravity(provider, { cwd: root ? path.resolve(root) : library, ...(timeoutMs ? { timeoutMs } : {}) })
+      : await probeAcp(provider, { cwd: root ? path.resolve(root) : library, ...(timeoutMs ? { timeoutMs } : {}) });
+    return { kind, name, source: entry.source, ok: true, ...result };
+  }
+  throw new AlpError('INVALID_KIND', `Only mcp servers, hooks and providers can be tested, not ${kind}`);
+}

package/src/mcp-probe.js

@@ -0,0 +1,118 @@
+import { spawn } from 'node:child_process';
+import { createInterface } from 'node:readline';
+import { launchCommand } from '@anhlp/alp-core/providers';
+
+const PROTOCOL = '2025-06-18';
+const client = { name: 'alp', version: '1' };
+
+/**
+ * Starts an MCP server once and lists its tools (ALPD §43), for the Test button and
+ * `alp mcp test`. `server` is a normalized definition: { command, args, env, cwd } for
+ * stdio, or { url, headers } for HTTP. The server is stopped afterwards.
+ * @returns {Promise<{ server?: { name?: string, version?: string }, tools: Array<{ name: string, description?: string }> }>}
+ */
+export async function probeMcp(server, { cwd, timeoutMs = 15_000 } = {}) {
+  const session = server.url ? await httpSession(server, timeoutMs) : stdioSession(server, cwd, timeoutMs);
+  try {
+    const init = await session.request('initialize', { protocolVersion: PROTOCOL, capabilities: {}, clientInfo: client });
+    await session.notify('notifications/initialized');
+    const tools = [];
+    let cursor;
+    for (let page = 0; page < 20; page++) {
+      const result = await session.request('tools/list', cursor ? { cursor } : {});
+      for (const tool of result.tools ?? []) tools.push({ name: tool.name, ...(tool.description ? { description: tool.description } : {}) });
+      cursor = result.nextCursor;
+      if (!cursor) break;
+    }
+    return { ...(init.serverInfo ? { server: { name: init.serverInfo.name, version: init.serverInfo.version } } : {}), tools };
+  } finally {
+    await session.close();
+  }
+}
+
+/** A JSON-RPC session with a process over stdio; ACP providers are probed with it too. */
+export function stdioSession(server, cwd, timeoutMs) {
+  // Its own process group, so a launcher such as npx is stopped with what it started.
+  const env = { ...process.env, ...(server.env ?? {}) };
+  const launch = launchCommand(server.command, server.args ?? [], env);
+  const child = spawn(launch.command, launch.args, { cwd: server.cwd ?? cwd, env, stdio: ['pipe', 'pipe', 'pipe'], detached: true });
+  const signal = name => { try { process.kill(-child.pid, name); } catch { child.kill(name); } };
+  let stderr = '';
+  child.stderr.setEncoding('utf8');
+  child.stderr.on('data', chunk => { if (stderr.length < 4000) stderr += chunk; });
+  const pending = new Map();
+  let exited;
+  const failAll = error => { for (const { reject } of pending.values()) reject(error); pending.clear(); };
+  child.on('error', error => { exited = error; failAll(error); });
+  child.on('exit', code => {
+    exited = new Error(`${server.command} exited (${code ?? 'signal'})${stderr.trim() ? `: ${stderr.trim().split('\n').slice(-3).join(' ')}` : ''}`);
+    failAll(exited);
+  });
+  createInterface({ input: child.stdout }).on('line', line => {
+    let message;
+    try { message = JSON.parse(line); } catch { return; }
+    const waiting = pending.get(message.id);
+    if (!waiting) return;
+    pending.delete(message.id);
+    if (message.error) waiting.reject(new Error(`${message.error.message ?? 'MCP error'} (${message.error.code})`));
+    else waiting.resolve(message.result ?? {});
+  });
+  child.stdin.on('error', () => {});
+  let id = 0;
+  return {
+    request(method, params) {
+      if (exited) return Promise.reject(exited);
+      const current = ++id;
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { pending.delete(current); reject(new Error(`${method} got no answer within ${timeoutMs / 1000} s`)); }, timeoutMs);
+        pending.set(current, { resolve: value => { clearTimeout(timer); resolve(value); }, reject: error => { clearTimeout(timer); reject(error); } });
+        child.stdin.write(JSON.stringify({ jsonrpc: '2.0', id: current, method, params }) + '\n');
+      });
+    },
+    async notify(method) { if (!exited) child.stdin.write(JSON.stringify({ jsonrpc: '2.0', method }) + '\n'); },
+    async close() {
+      if (child.exitCode !== null || child.signalCode !== null) return;
+      const done = new Promise(resolve => child.once('exit', resolve));
+      child.stdin.end();
+      signal('SIGTERM');
+      const timer = setTimeout(() => signal('SIGKILL'), 2000);
+      await done;
+      clearTimeout(timer);
+    },
+  };
+}
+
+async function httpSession(server, timeoutMs) {
+  let sessionId;
+  let id = 0;
+  const post = async body => {
+    const response = await fetch(server.url, {
+      method: 'POST',
+      headers: { ...(server.headers ?? {}), 'content-type': 'application/json', accept: 'application/json, text/event-stream', ...(sessionId ? { 'mcp-session-id': sessionId } : {}), 'mcp-protocol-version': PROTOCOL },
+      body: JSON.stringify(body),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+    sessionId = response.headers.get('mcp-session-id') ?? sessionId;
+    if (!response.ok) throw new Error(`${server.url} answered ${response.status} ${response.statusText}`);
+    return response;
+  };
+  return {
+    async request(method, params) {
+      const current = ++id;
+      const response = await post({ jsonrpc: '2.0', id: current, method, params });
+      const text = await response.text();
+      // A streamable HTTP server answers with JSON or with server-sent events.
+      const messages = (response.headers.get('content-type') ?? '').includes('text/event-stream')
+        ? text.split('\n').filter(line => line.startsWith('data:')).map(line => { try { return JSON.parse(line.slice(5)); } catch { return undefined; } })
+        : [JSON.parse(text)];
+      const message = messages.find(entry => entry?.id === current);
+      if (!message) throw new Error(`${method}: no answer in the response`);
+      if (message.error) throw new Error(`${message.error.message ?? 'MCP error'} (${message.error.code})`);
+      return message.result ?? {};
+    },
+    async notify(method) { await post({ jsonrpc: '2.0', method }); },
+    async close() {
+      if (sessionId) await fetch(server.url, { method: 'DELETE', headers: { ...(server.headers ?? {}), 'mcp-session-id': sessionId }, signal: AbortSignal.timeout(timeoutMs) }).catch(() => {});
+    },
+  };
+}

package/src/portable.js

@@ -0,0 +1,28 @@
+/**
+ * The portable ALP client (docs/alp/client-sdk.md): the JSON-RPC engine, its errors, the reconnect
+ * helper and NDJSON framing. It runs in Node, browsers and React Native without polyfills: no Node
+ * built-ins, no process, no Buffer, no filesystem and no ALP core. Transports come separately:
+ * `@anhlp/alp-client/websocket` here, the Unix socket and named pipe in the Node entry.
+ */
+
+/**
+ * @typedef {import('./rpc/client.js').AlpTransport} AlpTransport
+ * @typedef {import('./rpc/client.js').TransportClose} TransportClose
+ * @typedef {import('./rpc/client.js').TransportState} TransportState
+ * @typedef {import('./rpc/client.js').AbortSignalLike} AbortSignalLike
+ * @typedef {import('./rpc/client.js').RequestOptions} RequestOptions
+ * @typedef {import('./rpc/client.js').AlpRpcClientOptions} AlpRpcClientOptions
+ * @typedef {import('./rpc/handshake.js').ClientInfo} ClientInfo
+ * @typedef {import('./rpc/reconnect.js').ReconnectOptions} ReconnectOptions
+ * @typedef {import('./rpc/reconnect.js').ReconnectingClient} ReconnectingClient
+ * @typedef {import('./rpc/reconnect.js').ReconnectState} ReconnectState
+ * @typedef {import('./rpc/reconnect.js').Backoff} Backoff
+ */
+export { PROTOCOL_VERSION, MAX_FRAME, AlpRpcError, ERROR } from '@anhlp/alp-protocol';
+export { AlpRpcClient, DEFAULT_MAX_PENDING } from './rpc/client.js';
+export { AlpClientError, CLIENT_ERROR, isAlpClientError } from './rpc/errors.js';
+export { createLineDecoder, utf8Length } from './rpc/framing.js';
+export { MAX_TIMER_MS, timerDelay } from './rpc/timers.js';
+export { hello } from './rpc/handshake.js';
+export { backoffDelay, createReconnectingClient, retryable } from './rpc/reconnect.js';
+export { attachments, base64Encode, conversation, sha256Hex, workspaceRegistry } from './rpc/registry.js';

package/src/prompt.js

@@ -0,0 +1,64 @@
+import { emitKeypressEvents } from 'node:readline';
+
+const dim = text => `\x1b[2m${text}\x1b[22m`;
+const cyan = text => `\x1b[36m${text}\x1b[39m`;
+
+export class Cancelled extends Error {
+  constructor() { super('Setup cancelled.'); }
+}
+
+/**
+ * A select box in the terminal: ↑/↓ (or k/j) move, Enter picks, Ctrl-C or Esc cancels.
+ * Choices are { label, value, hint? }; `initial` is the value highlighted first.
+ * @template T
+ * @param {{ message: string, choices: Array<{ label: string, value: T, hint?: string }>, initial?: T }} question
+ * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream }} [io]
+ * @returns {Promise<T>}
+ */
+export function select({ message, choices, initial }, { input = process.stdin, output = process.stdout } = {}) {
+  let index = Math.max(0, choices.findIndex(choice => choice.value === initial));
+  let drawn = 0;
+  const draw = () => {
+    if (drawn) output.write(`\x1b[${drawn}A\x1b[0J`);
+    const lines = [`${cyan('?')} ${message} ${dim('(↑/↓, Enter)')}`, ...choices.map((choice, at) =>
+      at === index ? cyan(`❯ ${choice.label}`) + (choice.hint ? ` ${dim(choice.hint)}` : '') : `  ${choice.label}${choice.hint ? ` ${dim(choice.hint)}` : ''}`)];
+    output.write(lines.join('\n') + '\n');
+    drawn = lines.length;
+  };
+  return new Promise((resolve, reject) => {
+    emitKeypressEvents(input);
+    const raw = input.isRaw;
+    input.setRawMode?.(true);
+    input.resume();
+    output.write('\x1b[?25l');
+    const done = (settle, value) => {
+      input.off('keypress', onKey);
+      input.setRawMode?.(raw ?? false);
+      input.pause();
+      output.write(`\x1b[${drawn}A\x1b[0J\x1b[?25h`);
+      if (settle === resolve) output.write(`${cyan('✔')} ${message} ${cyan(choices[index].label)}\n`);
+      settle(value);
+    };
+    const onKey = (text, key = {}) => {
+      if ((key.ctrl && key.name === 'c') || key.name === 'escape') return done(reject, new Cancelled());
+      if (key.name === 'return' || key.name === 'enter') return done(resolve, choices[index].value);
+      if (key.name === 'up' || key.name === 'k') index = (index + choices.length - 1) % choices.length;
+      else if (key.name === 'down' || key.name === 'j') index = (index + 1) % choices.length;
+      else return;
+      draw();
+    };
+    input.on('keypress', onKey);
+    draw();
+  });
+}
+
+/**
+ * A line of text, for a value the list does not offer.
+ * @param {string} message
+ * @param {{ input?: NodeJS.ReadStream, output?: NodeJS.WriteStream }} [io]
+ */
+export async function text(message, { input = process.stdin, output = process.stdout } = {}) {
+  const { createInterface } = await import('node:readline/promises');
+  const rl = createInterface({ input, output });
+  try { return (await rl.question(`${cyan('?')} ${message} `)).trim(); } finally { rl.close(); }
+}

package/src/render.js

@@ -0,0 +1,136 @@
+/**
+ * Text the CLI prints for sessions and run logs, kept apart from the commands so
+ * golden tests can render fixtures without an alpd (ALPD §39).
+ */
+
+const TASK_PAST = { create: 'created', update: 'updated', link: 'linked', start: 'started', close: 'closed', reopen: 'reopened', delegate: 'delegated', submit: 'submitted', release: 'released', gate: 'gated', clear: 'cleared a gate of', orphaned: 'reopened (its assignment ended with alpd)' };
+
+/** How long ago `since` was, as 42s, 3m05s or 2h10m. */
+export const ago = (since, now = Date.now()) => {
+  const seconds = Math.max(0, Math.round((now - Date.parse(since)) / 1000));
+  return seconds < 60 ? `${seconds}s` : seconds < 3600 ? `${Math.floor(seconds / 60)}m${String(seconds % 60).padStart(2, '0')}s` : `${Math.floor(seconds / 3600)}h${String(Math.floor(seconds % 3600 / 60)).padStart(2, '0')}m`;
+};
+/** A duration in the same form. */
+export const duration = ms => ago(new Date(0).toISOString(), ms);
+/** A token count as people say it: 164k, 1M. */
+const tokens = count => typeof count !== 'number' ? '?' : count >= 1_000_000 && count % 1_000_000 < 50_000 ? `${Math.round(count / 1_000_000)}M` : `${Math.round(count / 1000)}k`;
+
+/** `alp ps`: sessions as a tree, one line each. */
+export function renderPs(sessions) {
+  const lines = [];
+  const children = new Map();
+  for (const session of sessions) {
+    const key = session.parentId ?? '';
+    children.set(key, [...(children.get(key) ?? []), session]);
+  }
+  const print = (session, depth) => {
+    const status = session.parked ? `parked (${session.parked})` : session.status === 'running' || session.status === 'idle' ? (session.activeTurnId ? 'running' : session.busy ? 'waiting' : 'idle') : session.lastError?.code ?? session.status;
+    lines.push(`${'  '.repeat(depth)}${session.id}  ${session.agent}  ${session.runtime}:${session.model}  ${session.mode}  ${status}${depth ? '' : `  ${session.projectRoot}${session.title ? `  "${session.title}"` : ''}`}`);
+    for (const child of children.get(session.id) ?? []) print(child, depth + 1);
+  };
+  for (const root of children.get('') ?? []) print(root, 0);
+  return lines;
+}
+
+/** `alp log`: one line per run-log entry, with its time. */
+export function renderLog(rootId, entries) {
+  const lines = [];
+  const agents = new Map();
+  for (const entry of entries) {
+    const time = entry.ts.slice(11, 19);
+    let text;
+    switch (entry.event) {
+      case 'assignment.started':
+        agents.set(entry.assignmentId, entry.agent);
+        text = `${entry.parentAgent} → ${entry.agent} (${entry.mode}${entry.isolation === 'worktree' ? ', worktree' : ''}, ${entry.model}${entry.wait === false ? ', async' : ''}): ${entry.task.split('\n')[0].slice(0, 120)}`;
+        break;
+      case 'assignment.finished':
+        text = `${entry.agent} ${entry.status} after ${duration(entry.durationMs ?? 0)}${entry.handoff ? `, handoff ${entry.handoff.outcome}${entry.handoff.verdict ? `, verdict ${entry.handoff.verdict.result.toUpperCase()}` : ''}: ${entry.handoff.summary.split('\n')[0].slice(0, 120)}` : ''}${entry.error ? `: ${entry.error}` : ''}${entry.reconciled ? ' (after a restart)' : ''}`;
+        break;
+      case 'mail':
+        // Board pins are logged once, as board.pin, not per reader.
+        if (entry.kind === 'board') continue;
+        text = `✉ ${entry.kind} ${entry.from} → ${entry.to === rootId ? 'main' : agents.get(entry.to) ?? entry.to}${entry.body ? `: ${entry.body.split('\n')[0].slice(0, 120)}` : ''}`;
+        break;
+      case 'board.pin':
+        text = `${entry.kind === 'claim' ? '⚑' : entry.kind === 'decision' ? '◆' : '•'} ${entry.agent} pins ${entry.kind} ${entry.pinId}${entry.task ? ` for ${entry.task}` : ''}${entry.paths ? ` [${entry.paths.join(', ')}]` : ''}: ${entry.body.split('\n')[0].slice(0, 120)}`;
+        break;
+      case 'task':
+        text = `☐ ${entry.agent} ${TASK_PAST[entry.action] ?? entry.action} ${entry.id} "${entry.title}" → ${entry.status}${entry.detail ? `: ${entry.detail.split('\n')[0].slice(0, 120)}` : ''}`;
+        break;
+      case 'board.unpin':
+        text = `⚐ ${entry.pinId} by ${entry.agent} ${entry.reason === 'session_ended' ? 'released when its session ended' : 'taken down'}`;
+        break;
+      case 'human.question':
+        text = `? ${entry.agent} asks the user [${entry.questionId}]: ${entry.body.split('\n')[0].slice(0, 120)}`;
+        break;
+      case 'verify':
+        text = `${entry.skipped ? '–' : entry.passed ? '✓' : '✗'} verify in the ${entry.where}${entry.taskId ? ` for ${entry.taskId}` : ''}${entry.assignmentId ? ` (${entry.assignmentId})` : ''}: ${entry.skipped ? `skipped: ${entry.skipped}` : entry.detail}`;
+        break;
+      case 'epic.landed':
+        text = `◆ ${entry.agent} closed ${entry.id} "${entry.title}": ${entry.tasks} tasks, ${entry.reworked} reworked`;
+        break;
+      case 'notice':
+        text = `${entry.level === 'error' ? '‼' : entry.level === 'warning' ? '!' : 'ℹ'} ${entry.text}`;
+        break;
+      case 'assignment.parked':
+        text = `⏸ ${entry.agent} ${entry.assignmentId} parked: ${entry.reason}`;
+        break;
+      case 'assignment.resumed':
+        text = `▶ ${entry.agent} ${entry.assignmentId} resumed`;
+        break;
+      case 'instructions':
+        text = `# ${entry.agent} instructions ${entry.sha} (ALP.md ${entry.parts?.project}, AGENT.md ${entry.parts?.agent}, ${entry.chars} chars)`;
+        break;
+      case 'context':
+        // Before 0.6 the advice came at 60% and 80% of the window (ALPD §35); since, once near compaction (§57).
+        text = entry.level === 'soon'
+          ? `◔ ${entry.agent} context ${tokens(entry.tokens)}, compacts at ${tokens(entry.compactAt)}: told it is near`
+          : `◔ ${entry.agent} context ${entry.percent}% full: ${entry.level === 'now' ? 'told to hand off now' : 'told to plan a handoff'}`;
+        break;
+      case 'skill':
+        // alp_skill saving a skill (name, roles) shares the name with an agent using one (skill, via).
+        text = Array.isArray(entry.roles)
+          ? `✦ ${entry.agent} saved skill ${entry.name} for ${entry.roles.join(', ')}`
+          : `✦ ${entry.agent} uses skill ${entry.skill}${entry.via === 'skill' ? ' (Skill tool)' : ''}`;
+        break;
+      case 'compacted':
+        text = entry.failed
+          ? `✗ ${entry.agent}'s context could not be compacted${entry.error ? `: ${entry.error}` : ''}`
+          : `◑ ${entry.agent}'s context compacted${entry.preTokens !== undefined ? ` from ${tokens(entry.preTokens)}` : ''}${entry.postTokens !== undefined ? ` to ${tokens(entry.postTokens)}` : ''}${entry.trigger === 'manual' ? ' on request' : ''}`;
+        break;
+      case 'assignment.interrupted':
+        text = `⏹ ${entry.agent} ${entry.assignmentId} interrupted: ${entry.reason}; the next alpd continues it`;
+        break;
+      case 'assignment.recovered':
+        text = `↻ ${entry.agent} ${entry.assignmentId} reopened after alpd restarted`;
+        break;
+      case 'session.restarted':
+        text = `↻ ${entry.agent}'s native process stopped (${entry.error}); restart ${entry.restarts}`;
+        break;
+      case 'session.revived':
+        text = `▶ ${entry.agent} running again`;
+        break;
+      case 'session.revive_failed':
+        text = `✗ ${entry.agent} could not be restarted: ${entry.error}`;
+        break;
+      case 'human.answer':
+        text = `↳ ${entry.questionId} ${entry.outcome}${entry.answer !== undefined ? `: ${entry.answer.split('\n')[0].slice(0, 120)}` : ''}`;
+        break;
+      case 'hook':
+        text = entry.skipped ? `↪ ${entry.agent}'s ${entry.on} hook ${entry.hook} skipped: the workspace's hooks are not trusted`
+          : `${entry.blocked ? '⛔' : entry.error || entry.exitCode !== 0 || entry.timedOut ? '✗' : '↪'} ${entry.agent}'s ${entry.on} hook ${entry.hook} ${entry.error ? `could not run: ${entry.error}` : entry.timedOut ? 'timed out' : `exit ${entry.exitCode}`}${entry.durationMs !== undefined ? ` in ${duration(entry.durationMs)}` : ''}${entry.blocked ? ', refused it' : ''}${entry.output ? `: ${entry.output.split('\n')[0].slice(0, 120)}` : ''}`;
+        break;
+      case 'hook.trust':
+        text = `${entry.trusted ? '✓ the user trusts' : '✗ the user did not trust'} the hooks of ${entry.project}${entry.outcome ? ` (${entry.outcome})` : ''}`;
+        break;
+      case 'runtime.slip':
+        text = `⚠ ALP could not handle ${entry.agent}'s ${entry.method}: ${entry.error}; the session went on`;
+        break;
+      default:
+        text = `${entry.event}${entry.branch ? ` ${entry.branch}` : ''}${entry.status ? ` ${entry.status}` : ''}`;
+    }
+    lines.push(`${time}  ${text}`);
+  }
+  return lines;
+}