@anhlp/alp-client 0.0.0-stage → 0.10.0

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;
+}

package/src/service.js

@@ -0,0 +1,154 @@
+import { createHash } from 'node:crypto';
+import { mkdir, readFile, unlink, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { runCommand } from './command.js';
+
+/**
+ * alpd as a user service (ALPD §37): a LaunchAgent on macOS, a systemd user unit on
+ * Linux. The service manager starts alpd at login and starts it again after a crash;
+ * a clean stop (`alp daemon stop`, exit 0) stays stopped until `alp daemon start`.
+ * Paths can be redirected for tests: ALP_SERVICE_DIR for the definition's directory,
+ * ALP_LAUNCHCTL and ALP_SYSTEMCTL for the managers.
+ */
+
+/** Variables alpd reads, carried into the service when the installing shell sets them. */
+const CARRIED = ['ALP_RUN_LOG_DIR', 'ALP_CODEX_BIN', 'ALP_CLAUDE_BIN', 'ALP_ANTIGRAVITY_BIN', 'ALP_GH_BIN'];
+
+const escapeXml = value => value.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+const quoteUnit = value => `"${value.replace(/\\/g, '\\\\').replace(/"/g, '\\"')}"`;
+
+/**
+ * Where and how alpd for `home` is defined as a service on `platform`, or undefined
+ * where ALP has no service support. Each ALP_HOME gets its own service.
+ */
+export function serviceFor({ home, env = process.env, platform = process.platform, uid = process.getuid?.() ?? 0 }) {
+  const custom = path.resolve(home) !== path.join(os.homedir(), '.alp');
+  const suffix = custom ? createHash('sha256').update(path.resolve(home)).digest('hex').slice(0, 8) : '';
+  if (platform === 'darwin') {
+    const label = `com.alp.alpd${suffix ? `.${suffix}` : ''}`;
+    const directory = env.ALP_SERVICE_DIR || path.join(os.homedir(), 'Library', 'LaunchAgents');
+    const launchctl = env.ALP_LAUNCHCTL || 'launchctl';
+    const target = `gui/${uid}/${label}`;
+    const file = path.join(directory, `${label}.plist`);
+    return {
+      kind: 'launchd', name: label, file,
+      install: [[launchctl, ['bootout', target], { ignore: true }], [launchctl, ['bootstrap', `gui/${uid}`, file]]],
+      start: [[launchctl, ['kickstart', target]]],
+      uninstall: [[launchctl, ['bootout', target], { ignore: true }]],
+    };
+  }
+  if (platform === 'linux') {
+    const name = `alpd${suffix ? `-${suffix}` : ''}`;
+    const directory = env.ALP_SERVICE_DIR || path.join(env.XDG_CONFIG_HOME || path.join(os.homedir(), '.config'), 'systemd', 'user');
+    const systemctl = env.ALP_SYSTEMCTL || 'systemctl';
+    return {
+      kind: 'systemd', name, file: path.join(directory, `${name}.service`),
+      install: [[systemctl, ['--user', 'daemon-reload']], [systemctl, ['--user', 'enable', '--now', `${name}.service`]]],
+      start: [[systemctl, ['--user', 'start', `${name}.service`]]],
+      uninstall: [[systemctl, ['--user', 'disable', '--now', `${name}.service`], { ignore: true }]],
+      afterUninstall: [[systemctl, ['--user', 'daemon-reload'], { ignore: true }]],
+    };
+  }
+  return undefined;
+}
+
+/** The service definition that runs `entry` with `execPath` for `home`. */
+export function serviceDefinition(service, { home, entry, execPath = process.execPath, env = process.env }) {
+  const variables = { ALP_HOME: path.resolve(home), PATH: env.PATH ?? '' };
+  for (const name of CARRIED) if (env[name]) variables[name] = env[name];
+  const program = [execPath, entry, '--service'];
+  const fatal = path.join(path.resolve(home), 'logs', 'alpd.service.log');
+  if (service.kind === 'launchd') {
+    return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0">
+<dict>
+  <key>Label</key>
+  <string>${escapeXml(service.name)}</string>
+  <key>ProgramArguments</key>
+  <array>
+${program.map(arg => `    <string>${escapeXml(arg)}</string>`).join('\n')}
+  </array>
+  <key>EnvironmentVariables</key>
+  <dict>
+${Object.entries(variables).map(([key, value]) => `    <key>${escapeXml(key)}</key>\n    <string>${escapeXml(value)}</string>`).join('\n')}
+  </dict>
+  <key>RunAtLoad</key>
+  <true/>
+  <key>KeepAlive</key>
+  <dict>
+    <key>Crashed</key>
+    <true/>
+    <key>SuccessfulExit</key>
+    <false/>
+  </dict>
+  <key>ThrottleInterval</key>
+  <integer>10</integer>
+  <key>ProcessType</key>
+  <string>Background</string>
+  <key>StandardOutPath</key>
+  <string>${escapeXml(fatal)}</string>
+  <key>StandardErrorPath</key>
+  <string>${escapeXml(fatal)}</string>
+</dict>
+</plist>
+`;
+  }
+  return `[Unit]
+Description=ALP daemon (alpd) for ${path.resolve(home)}
+
+[Service]
+ExecStart=${program.map(quoteUnit).join(' ')}
+${Object.entries(variables).map(([key, value]) => `Environment=${quoteUnit(`${key}=${value}`)}`).join('\n')}
+Restart=on-failure
+RestartSec=10
+StandardOutput=append:${fatal}
+StandardError=append:${fatal}
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+/** The program an installed definition runs: [node, alpd.js], or undefined when it is not installed. */
+export async function installedProgram(service) {
+  const text = await readFile(service.file, 'utf8').catch(() => undefined);
+  if (text === undefined) return undefined;
+  if (service.kind === 'launchd') {
+    const array = text.match(/<key>ProgramArguments<\/key>\s*<array>([\s\S]*?)<\/array>/)?.[1] ?? '';
+    const unescape = value => value.replace(/&quot;/g, '"').replace(/&gt;/g, '>').replace(/&lt;/g, '<').replace(/&amp;/g, '&');
+    return [...array.matchAll(/<string>([\s\S]*?)<\/string>/g)].map(match => unescape(match[1])).slice(0, 2);
+  }
+  const line = text.match(/^ExecStart=(.*)$/m)?.[1] ?? '';
+  return [...line.matchAll(/"((?:[^"\\]|\\.)*)"/g)].map(match => match[1].replace(/\\(.)/g, '$1')).slice(0, 2);
+}
+
+async function runAll(steps, run) {
+  for (const [command, args, { ignore = false } = {}] of steps) {
+    const result = await run(command, args);
+    if (result.code !== 0 && !ignore) throw new Error(`${command} ${args.join(' ')} failed: ${(result.stderr || result.stdout).trim() || `exit ${result.code}`}`);
+  }
+}
+
+/** Writes the definition and loads it, which starts alpd. */
+export async function installService(service, options, run = runCommand) {
+  await mkdir(path.dirname(service.file), { recursive: true });
+  await mkdir(path.join(path.resolve(options.home), 'logs'), { recursive: true, mode: 0o700 });
+  await writeFile(service.file, serviceDefinition(service, options), { mode: 0o644 });
+  await runAll(service.install, run);
+}
+
+/** Starts an installed service's alpd. */
+export async function startService(service, run = runCommand) {
+  await runAll(service.start, run);
+}
+
+/** Unloads the service, which stops its alpd, and removes the definition; false when none was installed. */
+export async function uninstallService(service, run = runCommand) {
+  if (await installedProgram(service) === undefined) return false;
+  await runAll(service.uninstall, run);
+  await unlink(service.file).catch(error => { if (error.code !== 'ENOENT') throw error; });
+  await runAll(service.afterUninstall ?? [], run);
+  return true;
+}

package/src/setup.js

@@ -0,0 +1,150 @@
+import { copyFile, readFile, writeFile } from 'node:fs/promises';
+import path from 'node:path';
+import { parseArgs } from 'node:util';
+import { initProject } from '@anhlp/alp-core/init';
+import { MODELS } from '@anhlp/alp-core/models';
+import { fitEffort, modelEfforts } from '@anhlp/alp-core/profiles';
+import { resolveTeam } from '@anhlp/alp-core/teams';
+import { validateSettings } from '@anhlp/alp-core/validation';
+import { Cancelled, select, text } from './prompt.js';
+
+const PROVIDERS = ['claude', 'codex'];
+const PROVIDER_LABEL = { claude: 'Claude', codex: 'Codex' };
+/** Each seat's model and effort per provider. Main runs on the preferred provider's only; peers may run on any model of an enabled provider. */
+const DEFAULTS = {
+  main: { claude: ['claude-opus-5-5', 'high'], codex: ['gpt-6.1-sol', 'high'] },
+  worker: { claude: ['claude-opus-5-5', 'high'], codex: ['gpt-6.1-sol', 'high'] },
+  supervisor: { claude: ['claude-sonnet-5', 'medium'], codex: ['gpt-6-luna', 'medium'] },
+  oracle: { claude: ['claude-fable-5-1', 'high'], codex: ['gpt-6-astra', 'high'] },
+};
+const FLAGS = { main: 'model', worker: 'model', supervisor: 'supervisor', oracle: 'oracle' };
+const SEAT_LABEL = { main: 'main', worker: 'lead, reviewer', supervisor: 'supervisor', oracle: 'oracle' };
+const ANY_EFFORT = ['low', 'medium', 'high', 'xhigh', 'max'];
+
+/** Write Phở and Cafe's agent profiles into a project's .alp/settings.json, without installing software or calling models. */
+export async function setup(args, home) {
+  const { values, positionals } = parseArgs({ args, allowPositionals: true, options: Object.fromEntries(
+    ['runtime', 'prefer', ...PROVIDERS.flatMap(provider => Object.values(FLAGS).map(flag => `${provider}-${flag}`))].map(name => [name, { type: 'string' }]),
+  ) });
+  if (positionals.length > 1) throw new Error('setup takes at most one directory');
+  const root = path.resolve(positionals[0] ?? process.cwd());
+  const interactive = Boolean(process.stdin.isTTY && process.stdout.isTTY);
+  try {
+    const runtime = values.runtime ?? (interactive ? await select({ message: 'Runtime', initial: 'mix', choices: [
+      { label: 'Mix', value: 'mix', hint: 'Claude and Codex: main runs on one, the others can run on either' },
+      { label: 'Codex only', value: 'codex' },
+      { label: 'Claude only', value: 'claude' },
+    ] }) : undefined);
+    if (runtime === undefined) throw new Error('Pass --runtime codex, claude or mix when setup is not running in a terminal');
+    if (!['codex', 'claude', 'mix'].includes(runtime)) throw new Error('--runtime must be codex, claude or mix');
+    const prefer = values.prefer ?? (runtime !== 'mix' ? runtime : interactive ? await select({ message: 'Main runs on', initial: 'claude', choices: [
+      { label: 'Claude', value: 'claude', hint: 'Claude first for the others too' },
+      { label: 'Codex', value: 'codex', hint: 'Codex first for the others too' },
+    ] }) : 'claude');
+    if (!PROVIDERS.includes(prefer) || (runtime !== 'mix' && prefer !== runtime)) throw new Error('--prefer must be an enabled runtime');
+    // The preferred provider comes first: it is each agent's default, the other one a choice.
+    const enabled = runtime === 'mix' ? [prefer, ...PROVIDERS.filter(provider => provider !== prefer)] : [runtime];
+    for (const provider of PROVIDERS) {
+      for (const flag of Object.values(FLAGS)) {
+        if (!enabled.includes(provider) && values[`${provider}-${flag}`]) throw new Error(`--${provider}-${flag} is unavailable in ${runtime}-only mode`);
+      }
+    }
+    /** @type {Record<string, Array<{ provider: string, model: string, effort?: string }>>} */
+    const seats = {};
+    for (const [seat, flag] of Object.entries(FLAGS)) {
+      seats[seat] = (seat === 'main' ? [prefer] : enabled).map(provider => {
+        const option = `${provider}-${flag}`;
+        const [fallback, effort] = DEFAULTS[seat][provider];
+        const model = nativeModel(values[option] ?? fallback, provider, `--${option}`);
+        return { provider, model, effort: fitEffort(`${provider}:${model}`, effort) };
+      });
+    }
+    const peers = enabled.map(provider => `${provider}:*`);
+
+    const file = path.join(root, '.alp/settings.json');
+    const settings = await readFile(file, 'utf8').then(content => {
+      try { return JSON.parse(content); } catch (error) { throw new Error(`${file} is not valid JSON: ${error.message}`); }
+    }, error => {
+      if (error.code === 'ENOENT') return undefined;
+      throw new Error(`${file}: ${error.message}`);
+    });
+    const show = () => {
+      for (const [seat, choices] of Object.entries(seats)) console.log(`  ${SEAT_LABEL[seat]}: ${choices.map(describe).join(', ')}`);
+      console.log(`  peer: ${peers.join(', ')} (any model: whoever assigns a peer picks its model and effort for the task)`);
+    };
+    console.log(`Profiles for Phở and Cafe in ${file}:`);
+    show();
+    const replaced = ['pho', 'cafe'].filter(id => (settings?.team ?? settings?.profile)?.[id]);
+    if (replaced.length) console.log(`These replace the ${replaced.join(' and ')} profiles already in the file; a backup is kept in ${file}.bak.`);
+    if (interactive) {
+      for (;;) {
+        const next = await select({ message: 'Save these profiles?', initial: 'save', choices: [
+          { label: 'Save', value: 'save' },
+          { label: 'Change a model', value: 'change' },
+          { label: 'Cancel', value: 'cancel' },
+        ] });
+        if (next === 'cancel') throw new Cancelled();
+        if (next === 'save') break;
+        await change(seats);
+        show();
+      }
+    }
+    const profile = await profiles(root, home, seats, peers, settings);
+    validateSettings({ ...(settings ?? {}), team: { ...(settings?.profile ?? {}), ...(settings?.team ?? {}), ...profile } }, file);
+    if (!settings) await initProject(root, { library: home });
+    else if (replaced.length) await copyFile(file, `${file}.bak`);
+    const written = settings ?? JSON.parse(await readFile(file, 'utf8'));
+    const next = { ...written, team: { ...(written.profile ?? {}), ...(written.team ?? {}), ...profile } };
+    delete next.profile;
+    await writeFile(file, JSON.stringify(next, null, 2) + '\n');
+    console.log('Setup saved. New sessions in this project use these profiles; edit the file to change one agent. Run alp doctor to check that each CLI is installed and logged in.');
+  } catch (error) {
+    if (!(error instanceof Cancelled)) throw error;
+    console.log(error.message);
+  }
+}
+
+const describe = choice => `${choice.provider}:${choice.model}${choice.effort ? `:${choice.effort}` : ''}`;
+
+/** Pick one seat and provider, then its model and effort. */
+async function change(seats) {
+  const [seat, at] = await select({ message: 'Which model?', choices: Object.entries(seats).flatMap(([seat, choices]) =>
+    choices.map((choice, at) => ({ label: `${SEAT_LABEL[seat]} · ${PROVIDER_LABEL[choice.provider]}`, value: [seat, at], hint: describe(choice) }))) });
+  const current = seats[seat][at];
+  const offered = MODELS.filter(model => model.runtime === current.provider);
+  const picked = await select({ message: `${SEAT_LABEL[seat]} on ${PROVIDER_LABEL[current.provider]}`, initial: current.model, choices: [
+    ...offered.map(model => ({ label: model.label, value: model.id, hint: `${model.id} · ${model.description}` })),
+    { label: 'Other…', value: undefined, hint: 'type a model ID' },
+  ] });
+  const model = picked ?? nativeModel(await text(`${PROVIDER_LABEL[current.provider]} model ID:`), current.provider, 'The model ID');
+  const efforts = modelEfforts(`${current.provider}:${model}`) ?? ANY_EFFORT;
+  const effort = efforts.length > 1 ? await select({ message: 'Effort', initial: efforts.includes(current.effort) ? current.effort : DEFAULTS[seat][current.provider][1],
+    choices: efforts.map(effort => ({ label: effort, value: effort })) }) : efforts[0];
+  seats[seat][at] = { provider: current.provider, model, ...(effort ? { effort } : {}) };
+}
+
+/** Every Phở and Cafe agent's profiles, keeping each agent's own compaction setting. */
+async function profiles(root, home, seats, peers, settings) {
+  const profile = {};
+  for (const id of ['pho', 'cafe']) {
+    const team = await resolveTeam(root, id, { library: home });
+    const agents = {};
+    const seat = (name, choices) => {
+      agents[name] = { profiles: choices.map(choice => typeof choice === 'string' ? choice : describe(choice)), autocompact: (settings?.team ?? settings?.profile)?.[id]?.[name]?.autocompact ?? 'auto' };
+    };
+    for (const [name, member] of Object.entries(team.members)) {
+      if (name !== 'oracle') seat(name, name === team.main ? seats.main : member.role === 'peer' ? peers : seats.worker);
+    }
+    if (team.supervisor) seat(team.supervisor.agent, seats.supervisor);
+    if (team.members.oracle) seat('oracle', seats.oracle);
+    profile[id] = agents;
+  }
+  return profile;
+}
+
+/** A model for one provider: a native ID, or one prefixed with that provider. */
+function nativeModel(id, provider, where) {
+  const model = id.startsWith(`${provider}:`) ? id.slice(provider.length + 1) : id;
+  if (!model || /\s/.test(model) || /^(codex|claude):/.test(model) || (model.includes(':') && !id.startsWith(`${provider}:`))) throw new Error(`${where} expects a ${provider} model, got '${id}'`);
+  return model;
+}

package/src/supervise.d.ts

@@ -0,0 +1,12 @@
+export function holdDaemon(home: string, by?: string): Promise<void>;
+export function releaseHold(home: string): Promise<void>;
+export function daemonHeld(home: string): Promise<boolean>;
+export function startDaemon(options: { home: string; entry?: string; env?: NodeJS.ProcessEnv; timeoutMs?: number }): Promise<string>;
+export function superviseDaemon(options: {
+  home: string;
+  entry?: string | (() => string | undefined);
+  env?: NodeJS.ProcessEnv;
+  intervalMs?: number;
+  misses?: number;
+  log?: (message: string) => void;
+}): (() => Promise<void>) & { started: Promise<void> };

package/src/supervise.js

@@ -0,0 +1,85 @@
+import { mkdir, unlink, writeFile, stat } from 'node:fs/promises';
+import path from 'node:path';
+import { ensureDaemon, lockAlive, readLock } from './index.js';
+import { installedProgram, serviceFor, startService } from './service.js';
+
+/**
+ * Keeping alpd up (ALPD §40). Whoever starts alpd goes through its login service when
+ * one is installed, so the service keeps managing it; otherwise alpd starts detached.
+ * A deliberate `alp daemon stop` leaves a hold, which watchers respect: they start
+ * alpd again only when someone asks for it.
+ */
+
+const holdFile = home => path.join(home, 'state', 'alpd.held');
+
+/** Records that the user stopped alpd on purpose. */
+export async function holdDaemon(home, by = 'alp daemon stop') {
+  await mkdir(path.dirname(holdFile(home)), { recursive: true, mode: 0o700 });
+  await writeFile(holdFile(home), JSON.stringify({ by, at: new Date().toISOString() }) + '\n', { mode: 0o600 });
+}
+
+export async function releaseHold(home) {
+  await unlink(holdFile(home)).catch(() => {});
+}
+
+export async function daemonHeld(home) {
+  return stat(holdFile(home)).then(() => true, () => false);
+}
+
+/** Polls until an alpd for `home` is ready; returns its socket. */
+async function whenReady(home, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    const lock = await readLock(home);
+    if (lockAlive(lock) && lock.ready) return lock.socket;
+    await new Promise(resolve => setTimeout(resolve, 100));
+  }
+  throw new Error(`alpd did not become ready within ${timeoutMs / 1000} s; see ${path.join(home, 'logs')}`);
+}
+
+/**
+ * Starts alpd for `home` unless it runs, and lifts a hold: someone asked for it.
+ * Returns its socket.
+ */
+export async function startDaemon({ home, entry, env = process.env, timeoutMs = 15_000 }) {
+  await releaseHold(home);
+  const lock = await readLock(home);
+  if (lockAlive(lock)) return lock.ready ? lock.socket : whenReady(home, timeoutMs);
+  const service = serviceFor({ home, env });
+  if (service && await installedProgram(service)) {
+    await startService(service);
+    return whenReady(home, timeoutMs);
+  }
+  return ensureDaemon({ home, entry, env, timeoutMs });
+}
+
+/**
+ * Starts alpd now and starts it again whenever it is found down on `misses` checks in a
+ * row, `intervalMs` apart, unless the user holds it. Two misses let `alp daemon restart`
+ * and `install` finish their own stop and start first. Returns a function that stops
+ * watching, and resolves once a start it began has settled; alpd keeps running.
+ */
+export function superviseDaemon({ home, entry, env = process.env, intervalMs = 5_000, misses = 2, log = () => {} }) {
+  let stopped = false;
+  let missed = 0;
+  let starting;
+  const start = reason => {
+    starting ??= startDaemon({ home, entry: typeof entry === 'function' ? entry() : entry, env })
+      .then(() => log(`alpd ${reason}`), error => log(`could not start alpd: ${error?.message ?? error}`))
+      .finally(() => { starting = undefined; missed = 0; });
+    return starting;
+  };
+  const check = async () => {
+    if (stopped || starting) return;
+    if (lockAlive(await readLock(home))) { missed = 0; return; }
+    if (await daemonHeld(home)) { missed = 0; return; }
+    // Stopped while this check looked: start nothing.
+    if (++missed >= misses && !stopped) await start('was down; started it again');
+  };
+  const initial = start('started with Paseo');
+  const timer = setInterval(() => { void check(); }, intervalMs);
+  timer.unref?.();
+  const stop = () => { stopped = true; clearInterval(timer); return starting ?? Promise.resolve(); };
+  stop.started = initial;
+  return stop;
+}