@celilo/cli 0.18.0 → 0.20.0

package/CELILO_SUBSYSTEMS.md

@@ -232,7 +232,9 @@ Creation, scheduling and freshness. A module declares an `on_backup` hook and a
 
 ## Events
 
-- **Event bus** — `packages/event-bus/src/index.ts` — `Bus`, `openBus`, `defineEvents`, `defineHandler`, `runDispatcher`, pattern matching + timer ticks (`emitDueTimerTicks`, `retentionSweep`). **Exactly one dispatcher per bus**: `runDispatcher` refuses to start while another dispatcher's process is alive (`assertSoleDispatcher` in `dispatcher.ts`, liveness via `bus.liveDispatchers()` — `kill(pid,0)`, not heartbeat age, since a tick blocks for as long as its slowest handler). The exclusion is here rather than in the systemd unit because a stranded dispatcher can sit outside the unit's cgroup where `KillMode` cannot reach it (#580). `bus.health()` reports `dispatcherCount`/`dispatchers` and a `duplicate_dispatcher` status; `checkDispatcher` (`services/fleet-checks.ts`) fails on more than one.
+- **Migration interrogation** — `apps/celilo/src/db/migration-status.ts` — `getMigrationStatus(sqlite, migrationsFolder)` reports applied count, latest applied migration BY TAG, and pending ones by name (joining `__drizzle_migrations.created_at` to drizzle journal `when`, which is exact). Surface: `celilo system migrate --status`, which opens the DB **read-only** on purpose — `getDb()` auto-migrates on open, so a status routed through it would repair what it claims to report and could never say "pending". Paired with `findSchemaDrift` (`db/schema-introspection.ts`), which is column-aware: a table COUNT cannot distinguish "the column migration applied" from "nothing happened", which is why a rollout asserting `backups.pid` had to reach for `sqlite3` over SSH. `checkSchemaDrift` (`services/fleet-checks.ts`) fails on a missing table, a missing column, OR an unapplied journal migration, and its summary names tables AND columns so the operator can see what was checked.
+- **Event bus** — `packages/event-bus/src/index.ts` — `Bus`, `openBus`, `defineEvents`, `defineHandler`, `runDispatcher`, pattern matching + timer ticks (`emitDueTimerTicks`, `retentionSweep`). **Exactly one dispatcher per bus**: `runDispatcher` refuses to start while another dispatcher's process is alive (`assertSoleDispatcher` in `dispatcher.ts`, liveness via `bus.liveDispatchers()` — `kill(pid,0)`, not heartbeat age, since a tick blocks for as long as its slowest handler). The exclusion is here rather than in the systemd unit because a stranded dispatcher can sit outside the unit's cgroup where `KillMode` cannot reach it (#580). `bus.health()` reports `dispatcherCount`/`dispatchers` and a `duplicate_dispatcher` status; `checkDispatcher` (`services/fleet-checks.ts`) fails on more than one. **Supervision** (`services/events-daemon.ts`): the unit is named `celilo-events.service` in BOTH the user and system scope, so the two are indistinguishable in every operator-facing string — `install-daemon` (which defaults to **user** scope) therefore refuses when the other scope's unit exists, and `checkDispatcher` compares the live pid against each installed unit's `MainPID` (`unitMainPid`) rather than merely testing that a unit file exists, since a file nobody is running is not supervision (#610).
+- **Dispatcher supervision (install / restart)** — `apps/celilo/src/services/events-daemon.ts` — `installDaemon`/`planDaemonInstall`/`uninstallDaemon`/`readInstalledUnit` write the systemd unit or launchd plist without touching supervisor state, and `restartDaemon` (+ pure `orphanDispatcherPids`, `resolveRestartScope`, `supervisorCommands`) is the one verb that DOES cycle it. CLI: `celilo events install-daemon|uninstall-daemon|show-daemon|restart-daemon [--system]`. `restart-daemon` exists because the dispatcher runs the code it LOADED: celilo-mgr sat 9 days on event-bus v0.1.8 after apt installed v0.2.0, running the very bug the release fixed (celilo#604). Two things make it non-trivial and both are load-bearing: (1) it stops any live dispatcher the supervisor does not own first — an ORPHAN (PPID 1) is invisible to `systemctl restart`, and `assertSoleDispatcher` then crash-loops the unit while the old code keeps serving; (2) it verifies on the BUS that a NEW pid is live reporting `BUS_VERSION`, never off systemctl's exit code, which returns 0 into exactly that crash loop. System scope shells `sudo systemctl` (the unit is root-owned; celilo runs unprivileged), covered by the scoped `/etc/sudoers.d/celilo-events-restart` conffile that `celilo-bootstrap` ships — a unit test asserts the argv and the grant cannot drift apart.
 
 ## Remote API (drive the CLI over the wire)
 
@@ -246,7 +248,7 @@ Run any celilo command on celilo-mgr over SSH instead of screen-scraping `ssh <h
 - **Access control** — `apps/celilo/src/services/api-access.ts` — `grantPrincipal`, `isAuthorized` (deny-by-default, `command:subcommand` grants), `renderAuthorizedKeys`. Table: `api_principals` (`apps/celilo/src/db/schema.ts`). CLI: `apps/celilo/src/cli/commands/api.ts` (`api grant|list|revoke|authorized-keys|key new`).
 - **Mid-run interview bridge (`kind:daemon` responder)** — `apps/celilo/src/services/remote-responder.ts` — `startRemoteResponder` bridges bus `interview.required.*` ↔ wire.
 - **Server provisioning** — the `celilo-bootstrap` deb (`packaging/celilo-bootstrap/scripts/postinst`) creates the non-root `celilo-api` landing account + sshd; membership in the `celilo` group + `/etc/sudoers.d/celilo` (`!use_pty`) gives api-serve DB access via the wrapper's sudo-drop.
-- **Self-upgrade (apt)** — `celilo apt-upgrade` (`apps/celilo/src/cli/commands/apt-upgrade.ts`) upgrades the deb-installed `celilo`/`celilo-bootstrap` packages (`apt-get update` → `--only-upgrade install`) then spawns a fresh `celilo system migrate` (ISS-0100). It's the RW target behind the MCP's registry-derived `celilo_apt_upgrade` tool; the celilo user's two apt invocations are scoped-sudo'd by `/etc/sudoers.d/celilo-apt-upgrade`, shipped by `celilo-bootstrap`. **This upgrades celilo ITSELF — not the modules it manages. For those, see Module auto-upgrade below; the two are routinely confused.**
+- **Self-upgrade (apt)** — `celilo apt-upgrade` (`apps/celilo/src/cli/commands/apt-upgrade.ts`) upgrades the deb-installed `celilo`/`celilo-bootstrap` packages (`apt-get update` → `--only-upgrade install`) then spawns a fresh `celilo system migrate` (ISS-0100), then `celilo events restart-daemon` so the dispatcher actually runs the code just installed — a failure there fails the whole command and names which steps DID complete, because "upgraded" while the dispatcher serves stale code is the silent state celilo#604 documents. It's the RW target behind the MCP's registry-derived `celilo_apt_upgrade` tool; the celilo user's two apt invocations are scoped-sudo'd by `/etc/sudoers.d/celilo-apt-upgrade`, shipped by `celilo-bootstrap`. **This upgrades celilo ITSELF — not the modules it manages. For those, see Module auto-upgrade below; the two are routinely confused.**
 - **Module auto-upgrade (registry-poll CD)** — the *pull* half of continuous deployment: celilo-mgr polls the registry and upgrades opted-in modules unattended. Spec: `openspec/specs/module-auto-upgrade/spec.md`. Entry points: `apps/celilo/src/cli/commands/module-upgrade.ts` — `runRegistryPoll` (the `--poll` path), `selectPollTargets` (pure: `autoUpgrade && latest && change ∉ {up-to-date, ahead}`), `upgradeOneModule` (update → backup → deploy → verify), `needsPreUpgradeBackup`, `pickAutoUpgrade`/`pickUpgradePolicy` (both fail closed/safe); `classifyVersionChange` in `module-update.ts` (treats a registry `+N` revision as a patch); `resolveDeployPosture` in `apps/celilo/src/services/deploy-posture.ts`. Trigger: celilo-mgmt's `registry-poll` subscription (`modules/celilo-mgmt/manifest.yml`) on `timer.tick.15m` with handler **`celilo module upgrade --poll`** — the flag is REQUIRED, since the dispatcher appends the event id positionally and a bare handler would consume it as the optional module name (silent: 3108 deliveries, 0 successes). Operator controls are framework config keys settable on ANY module (`FRAMEWORK_CONFIG_KEYS` in `module-config.ts`): `auto_upgrade` (opt-in, default false) and `upgrade_policy` (`by-semver`|`always-safe`|`always-fast`), validated at set time because both readers fail open. ⚠️ `always-safe` guarantees safe *posture*, NOT a backup — `needsPreUpgradeBackup` also requires the TARGET manifest to declare an `on_backup` hook, else it warns and proceeds. Confirm a data-bearing module declares `on_backup` before enabling `auto_upgrade` on it. The *build* half (app CI publishing a `.netapp` on merge) is not yet shipped — `openspec/changes/build-bus-poll-cd`.
 - **MCP service (`@celilo/mcp`)** — `packages/mcp/src/` — an operator-facing stdio MCP server (official `@modelcontextprotocol/sdk`, bin `celilo-mcp`) that drives a remote celilo server over the Remote API for an AI client. Two-item config (`config.ts`: `server` + `defaultUser`, env or `~/.config/celilo-mcp/config.json`). Dual-principal auth (`auth.ts`: `celilo-mcp auth setup` enrolls read-only `celilo-mcp-ro` + full `celilo-mcp-rw` ed25519 keypairs, prints the exact `celilo api grant` lines the operator runs server-side). Transport (`transport.ts`): reuses `@celilo/core` `runRemoteClient`, selecting the principal by `ssh -i <key>` and capturing structured output. Tool surface is generated LIVE from the server's command registry — `registry-fetch.ts` fetches `celilo commands --json` (+ `service list --json` for configured providers) over the RO principal on connect; `tools-from-registry.ts` (pure) projects that into one tool per runnable leaf, grouped by top-level command (`celilo_module_*`, `celilo_proxmox_*`, …), each with a Zod input schema from the leaf's args/flags and a read/write tag → RO/RW routing, plus a generic `celilo_run` escape hatch. Auto-detect hides provider-gated groups (e.g. `celilo_proxmox_*` until a Proxmox service is configured) and re-detects on a timer, emitting `notifications/tools/list_changed` when the surface changes. Coverage gate (`tests/coverage.test.ts`) asserts every registry leaf maps to a tool. Composite RO troubleshooting tools (`troubleshoot.ts` pure correlation + `troubleshoot-tools.ts` thin adapters): `celilo_assess_module <id>` and `celilo_fleet_status` correlate `celilo audit --json` (the drift backbone) with the `module list --json` roster into a per-module / fleet-wide verdict. Design: `openspec/changes/celilo-mcp-service/proposal.md`. (Distinct from the dev/ops `@celilo/mcp-server` below.)
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@celilo/cli",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "Celilo — home lab orchestration CLI",
   "type": "module",
   "bin": {
@@ -57,10 +57,10 @@
   },
   "dependencies": {
     "@aws-sdk/client-s3": "^3.1024.0",
-    "@celilo/capabilities": "^0.10.0",
+    "@celilo/capabilities": "^0.11.0",
     "@celilo/cli-display": "^0.1.10",
-    "@celilo/core": "^0.3.2",
-    "@celilo/event-bus": "^0.2.0",
+    "@celilo/core": "^0.5.0",
+    "@celilo/event-bus": "^0.3.0",
     "@clack/prompts": "^1.1.0",
     "ajv": "^8.18.0",
     "drizzle-orm": "^0.36.4",

package/src/api/remote-client.test.ts

@@ -72,7 +72,7 @@ test('renders a forwarded interview and sends the answer back', async () => {
   push({ type: 'interview', id: 'q1', kind: 'text', message: 'Hostname?' });
 
   const seen: Array<{ id: string }> = [];
-  const code = await runRemoteClient('ignored', ['module', 'deploy', 'site'], {
+  const outcome = await runRemoteClient('ignored', ['module', 'deploy', 'site'], {
     openTransport: () => transport,
     out: { write() {} },
     renderInterview: async (iv) => {
@@ -81,7 +81,7 @@ test('renders a forwarded interview and sends the answer back', async () => {
     },
   });
 
-  expect(code).toBe(0);
+  expect(outcome).toEqual({ status: 'result', exitCode: 0 });
   expect(seen).toHaveLength(1);
   expect(seen[0].id).toBe('q1');
   expect(writes.some((w) => w.includes('"command"'))).toBe(true);
@@ -89,3 +89,87 @@ test('renders a forwarded interview and sends the answer back', async () => {
   expect(answer).toBeDefined();
   expect(JSON.parse(answer as string)).toEqual({ type: 'answer', id: 'q1', value: 'myhost' });
 });
+
+/**
+ * Regression for the fabricated "operator declined".
+ *
+ * The default renderer prompts with clack, which reads keypresses off stdin
+ * whether or not stdin is a terminal. Driven over the MCP (stdin = the JSON-RPC
+ * stream) the next newline submitted the prompt at its `initialValue` — the
+ * question's `defaultValue` — so a breaking update nobody saw came back as a
+ * considered "no". With no terminal the client must say it cannot answer.
+ *
+ * And it must say so as `unanswerable`, NOT as an `answer` of any shape: an
+ * `answer` is what consumes the query and destroys a question nobody decided
+ * (celilo#609). The server parks and replies `blocked`.
+ */
+test('no TTY and no renderer → sends unanswerable and returns blocked, never an answer', async () => {
+  const writes: string[] = [];
+  const encoder = new TextEncoder();
+  let controller!: ReadableStreamDefaultController<Uint8Array>;
+  const stdout = new ReadableStream<Uint8Array>({
+    start(c) {
+      controller = c;
+    },
+  });
+  const push = (obj: unknown) => controller.enqueue(encoder.encode(`${JSON.stringify(obj)}\n`));
+
+  const transport: RemoteTransport = {
+    stdin: {
+      write(chunk: string) {
+        writes.push(chunk);
+        // What a #609 server does with "I can't decide": park, don't resolve.
+        if (chunk.includes('"unanswerable"')) {
+          push({
+            type: 'blocked',
+            sessionId: 'sess-1',
+            eventId: '42',
+            question: 'Apply breaking update for iptables (1.0.2+9 → 2.0.0+1)?',
+            key: 'module-upgrade:iptables.apply_breaking',
+          });
+          controller.close();
+        }
+      },
+    },
+    stdout,
+    kill() {},
+    exited: Promise.resolve(1),
+  };
+
+  push({ type: 'ready', protocolVersion: 1 });
+  push({
+    type: 'interview',
+    id: 'q1',
+    scope: 'module-upgrade:iptables',
+    key: 'apply_breaking',
+    kind: 'confirm',
+    message: 'Apply breaking update for iptables (1.0.2+9 → 2.0.0+1)?',
+    defaultValue: 'false',
+  });
+
+  // No `renderInterview` — exactly what runRemoteCapture used to do. bun test
+  // runs with a piped stdin, i.e. the MCP server's situation.
+  expect(process.stdin.isTTY).toBeFalsy();
+  const outcome = await runRemoteClient('ignored', ['module', 'update'], {
+    openTransport: () => transport,
+    out: { write() {} },
+  });
+
+  // Never an answer — that would consume the query.
+  expect(writes.find((w) => w.includes('"answer"'))).toBeUndefined();
+
+  const unanswerable = writes.find((w) => w.includes('"unanswerable"'));
+  expect(unanswerable).toBeDefined();
+  const parsed = JSON.parse(unanswerable as string) as { id: string; reason: string };
+  expect(parsed.id).toBe('q1');
+  expect(parsed.reason).toContain('module-upgrade:iptables.apply_breaking');
+
+  // And the caller is told where it stands rather than being handed a decline.
+  expect(outcome).toEqual({
+    status: 'blocked',
+    sessionId: 'sess-1',
+    eventId: '42',
+    question: 'Apply breaking update for iptables (1.0.2+9 → 2.0.0+1)?',
+    key: 'module-upgrade:iptables.apply_breaking',
+  });
+});

package/src/api/serve.ts

@@ -2,13 +2,19 @@
  * Remote API server — `celilo api-serve --principal=<id>` (Slices 1–3).
  *
  * Invoked as the sshd forced command for an enrolled key, so it starts already
- * authenticated as `principal`. Reads `command`/`answer` messages as NDJSON on
- * stdin/stdout, authorizes each command against the principal's grants
- * (deny-by-default), and — if allowed — runs it as a child `celilo` process,
- * translating the child's protocol-mode output into `progress`/`log` and a
- * terminal `result`. While a command runs, a remote responder bridges the event
- * bus to the wire so mid-run `interview`s are answered by the client. Every
- * attempt is audited to stderr.
+ * authenticated as `principal`. Reads `command`/`answer`/`unanswerable`/
+ * `attach`/`cancel` messages as NDJSON on stdin/stdout, authorizes each command
+ * against the principal's grants (deny-by-default), and — if allowed — runs it
+ * as a child `celilo` process, translating the child's protocol-mode output into
+ * `progress`/`log` and a terminal `result`. While a command runs, a remote
+ * responder bridges the event bus to the wire so mid-run `interview`s are
+ * answered by the client. Every attempt is audited to stderr.
+ *
+ * When the client cannot decide a question, the command **parks**: the query is
+ * left unanswered on the bus, the child stays alive past the end of the ssh
+ * session, its output is buffered in the session registry, and the client is
+ * told `blocked` with the session and query ids (celilo#609). Another responder
+ * answers by event id; a later `attach` collects the outcome.
  */
 
 import { createInterface } from 'node:readline';
@@ -16,16 +22,30 @@ import {
   API_PROTOCOL_VERSION,
   ClientMessageSchema,
   type ServerMessage,
+  ServerMessageSchema,
   translateOutputLine,
 } from '@celilo/core';
 import { parseArguments } from '../cli/parser';
 import { getEventBusPath } from '../config/paths';
 import { isAuthorized } from '../services/api-access';
+import { EVENT_TYPES } from '../services/bus-interview';
 import { type WireInterview, startRemoteResponder } from '../services/remote-responder';
+import {
+  SessionWriter,
+  abandonSession,
+  expiryReason,
+  readSession,
+  reapExpiredSessions,
+  replayOutput,
+  stillParked,
+} from './sessions';
 
 /** Exit code returned to the client when authz denies a command. */
 const EXIT_PERMISSION_DENIED = 126;
 
+/** How often an attached client polls a session's buffer for new output. */
+const ATTACH_POLL_MS = 250;
+
 function send(msg: ServerMessage): void {
   process.stdout.write(`${JSON.stringify(msg)}\n`);
 }
@@ -44,8 +64,20 @@ function opOf(argv: string[]): { command: string; subcommand?: string; label: st
   return { command: parsed.command, subcommand: parsed.subcommand, label };
 }
 
+/**
+ * Emit a message to the attached client (if any) AND to the session buffer, so
+ * output produced while nobody is attached is not lost.
+ */
+function emit(session: SessionWriter, msg: ServerMessage, attached: () => boolean): void {
+  session.append(msg);
+  if (attached()) send(msg);
+}
+
 /** Drain a child stream line-by-line, forwarding each line as a message. */
-async function pumpLines(stream: ReadableStream<Uint8Array>): Promise<void> {
+async function pumpLines(
+  stream: ReadableStream<Uint8Array>,
+  forward: (msg: ServerMessage) => void,
+): Promise<void> {
   const decoder = new TextDecoder();
   let buffer = '';
   for await (const chunk of stream) {
@@ -54,17 +86,17 @@ async function pumpLines(stream: ReadableStream<Uint8Array>): Promise<void> {
     while (nl >= 0) {
       const line = buffer.slice(0, nl);
       buffer = buffer.slice(nl + 1);
-      send(translateOutputLine(line));
+      forward(translateOutputLine(line));
       nl = buffer.indexOf('\n');
     }
   }
   if (buffer.length > 0) {
-    send(translateOutputLine(buffer));
+    forward(translateOutputLine(buffer));
   }
 }
 
 /** Run an authorized command as a child; returns its exit code. */
-async function runCommand(argv: string[]): Promise<number> {
+async function runCommand(argv: string[], forward: (msg: ServerMessage) => void): Promise<number> {
   // Re-invoke this same CLI as a child. The child is non-TTY (piped stdout) so
   // ProgressDisplay resolves to protocol mode and emits `[progress:*]` markers.
   const child = Bun.spawn([process.execPath, Bun.main, ...argv], {
@@ -73,49 +105,137 @@ async function runCommand(argv: string[]): Promise<number> {
     stderr: 'pipe',
   });
 
-  await Promise.all([pumpLines(child.stdout), pumpLines(child.stderr)]);
+  await Promise.all([pumpLines(child.stdout, forward), pumpLines(child.stderr, forward)]);
   const exitCode = await child.exited;
-  send({ type: 'result', success: exitCode === 0, exitCode });
+  forward({ type: 'result', success: exitCode === 0, exitCode });
   return exitCode;
 }
 
-async function handleCommand(
-  principal: string,
-  argv: string[],
-  busDbPath: string,
-  ask: (interview: WireInterview) => Promise<unknown>,
-): Promise<void> {
-  const { command, subcommand, label } = opOf(argv);
-
-  if (!(await isAuthorized(principal, command, subcommand))) {
-    send({ type: 'error', error: `permission denied: "${principal}" is not granted "${label}"` });
+/**
+ * Replay a parked session's buffered output to the attaching client, then tail
+ * it until the session goes terminal. Deny-by-default on the owning principal.
+ */
+async function handleAttach(principal: string, sessionId: string): Promise<void> {
+  const record = readSession(sessionId);
+  if (!record) {
+    send({ type: 'error', error: `no such session: ${sessionId}` });
+    send({ type: 'result', success: false, exitCode: 1 });
+    return;
+  }
+  if (record.principal !== principal) {
+    send({
+      type: 'error',
+      error: `permission denied: session ${sessionId} belongs to another principal`,
+    });
     send({ type: 'result', success: false, exitCode: EXIT_PERMISSION_DENIED });
-    audit(principal, label, 'deny');
+    audit(principal, `attach:${sessionId}`, 'deny');
     return;
   }
+  audit(principal, `attach:${sessionId}`, 'allow');
 
-  // Bridge the bus to the wire so mid-run interviews reach the client.
-  const responder = startRemoteResponder({ busDbPath, ask, emittedBy: `api:${principal}` });
-  try {
-    const exitCode = await runCommand(argv);
-    audit(principal, label, 'allow', exitCode);
-  } finally {
-    responder.close();
+  let cursor = 0;
+  for (;;) {
+    const { messages, next } = replayOutput(sessionId, cursor);
+    cursor = next;
+    for (const line of messages) {
+      const parsed = ServerMessageSchema.safeParse(JSON.parse(line));
+      if (!parsed.success) continue;
+      send(parsed.data);
+      if (parsed.data.type === 'result') return;
+    }
+    const current = readSession(sessionId);
+    if (!current) return;
+    // Still waiting on a decision → say so rather than tailing forever. Asked of
+    // the bus, not of the record: the answer arrives from a third party the
+    // owning process never hears from, so its `state` lags.
+    if (current.parkedEventId && stillParked(current, getEventBusPath())) {
+      send({
+        type: 'blocked',
+        sessionId,
+        eventId: current.parkedEventId,
+        question: current.question ?? '',
+        key: current.questionKey ?? undefined,
+      });
+      return;
+    }
+    await new Promise((r) => setTimeout(r, ATTACH_POLL_MS));
   }
 }
 
+/** Abandon a parked session on the operator's say-so, before its TTL. */
+function handleCancel(principal: string, sessionId: string): void {
+  const record = readSession(sessionId);
+  if (!record) {
+    send({ type: 'error', error: `no such session: ${sessionId}` });
+    send({ type: 'result', success: false, exitCode: 1 });
+    return;
+  }
+  if (record.principal !== principal) {
+    send({
+      type: 'error',
+      error: `permission denied: session ${sessionId} belongs to another principal`,
+    });
+    send({ type: 'result', success: false, exitCode: EXIT_PERMISSION_DENIED });
+    audit(principal, `cancel:${sessionId}`, 'deny');
+    return;
+  }
+  abandonSession(record, {
+    busDbPath: getEventBusPath(),
+    reason: `Session ${sessionId} was cancelled by ${principal} with "${record.question ?? 'the question'}" still unanswered.`,
+    emittedBy: `api:${principal}`,
+  });
+  audit(principal, `cancel:${sessionId}`, 'allow');
+  send({ type: 'result', success: true, exitCode: 0 });
+}
+
 export async function apiServeMode(principal: string): Promise<void> {
   send({ type: 'ready', protocolVersion: API_PROTOCOL_VERSION });
 
   const busDbPath = getEventBusPath();
-  const pendingAnswers = new Map<string, (value: unknown) => void>();
+  // A session whose owning process died (reboot, OOM) would otherwise stay
+  // parked forever, holding whatever its command holds.
+  reapExpiredSessions({ busDbPath });
+
+  // When the ssh client goes away, sshd hangs up its forced command. Ignoring
+  // SIGHUP is what lets a parked command outlive the session that started it —
+  // the TTL reaper, not the transport, is what bounds it now.
+  process.on('SIGHUP', () => {});
+
+  const pendingAnswers = new Map<
+    string,
+    { resolve: (value: unknown) => void; reject: (error: Error) => void; interview: WireInterview }
+  >();
+
+  /** Set while a command is running; the parked child outlives the transport. */
+  const live: { session: SessionWriter | null; clientAttached: boolean } = {
+    session: null,
+    clientAttached: true,
+  };
+  let commandRunning: Promise<void> | null = null;
 
   const ask = (interview: WireInterview): Promise<unknown> =>
-    new Promise((resolve) => {
-      pendingAnswers.set(interview.id, resolve);
+    new Promise((resolve, reject) => {
+      pendingAnswers.set(interview.id, { resolve, reject, interview });
+      if (!live.clientAttached) {
+        // Nobody to ask. Re-park on THIS question: a detached command that was
+        // answered and moved on is now waiting on a *different* event, and a
+        // record still naming the previous one is actively wrong — it hides the
+        // live question from `events list-unanswered`, and it aims the TTL
+        // reaper at a question that was already decided, so the reaper retires
+        // the session while the child is still alive and blocked.
+        live.session?.park({
+          eventId: interview.id,
+          eventType: EVENT_TYPES.interviewRequired(interview.scope, interview.key),
+          question: interview.message,
+          questionKey: `${interview.scope}.${interview.key}`,
+        });
+        return;
+      }
       send({
         type: 'interview',
         id: interview.id,
+        scope: interview.scope,
+        key: interview.key,
         kind: interview.kind,
         message: interview.message,
         description: interview.description,
@@ -126,6 +246,46 @@ export async function apiServeMode(principal: string): Promise<void> {
       });
     });
 
+  const handleCommand = async (argv: string[]): Promise<void> => {
+    const { command, subcommand, label } = opOf(argv);
+
+    if (!(await isAuthorized(principal, command, subcommand))) {
+      send({ type: 'error', error: `permission denied: "${principal}" is not granted "${label}"` });
+      send({ type: 'result', success: false, exitCode: EXIT_PERMISSION_DENIED });
+      audit(principal, label, 'deny');
+      return;
+    }
+
+    const writer = SessionWriter.create({ principal, argv });
+    live.session = writer;
+    const reaper = setTimeout(
+      () => {
+        if (writer.current.state !== 'parked') return;
+        abandonSession(writer.current, {
+          busDbPath,
+          reason: expiryReason(writer.current),
+          emittedBy: `api:${principal}`,
+        });
+        writer.finish('abandoned');
+      },
+      Math.max(0, writer.current.expiresAt - Date.now()),
+    );
+
+    // Bridge the bus to the wire so mid-run interviews reach the client.
+    const responder = startRemoteResponder({ busDbPath, ask, emittedBy: `api:${principal}` });
+    try {
+      const exitCode = await runCommand(argv, (msg) =>
+        emit(writer, msg, () => live.clientAttached),
+      );
+      writer.finish('finished');
+      audit(principal, label, 'allow', exitCode);
+    } finally {
+      clearTimeout(reaper);
+      responder.close();
+      live.session = null;
+    }
+  };
+
   const rl = createInterface({ input: process.stdin, terminal: false });
 
   for await (const line of rl) {
@@ -140,20 +300,64 @@ export async function apiServeMode(principal: string): Promise<void> {
     }
 
     if (msg.type === 'answer') {
-      const resolve = pendingAnswers.get(msg.id);
-      if (resolve) {
+      const pending = pendingAnswers.get(msg.id);
+      if (pending) {
         pendingAnswers.delete(msg.id);
-        resolve(msg.value);
+        live.session?.unpark();
+        pending.resolve(msg.value);
+      }
+      continue;
+    }
+
+    if (msg.type === 'unanswerable') {
+      // The client cannot decide. Do NOT resolve the question — park on it and
+      // tell the client where it stands. The responder, seeing `ask` reject,
+      // emits nothing on the bus, so the query is still there to be answered.
+      const pending = pendingAnswers.get(msg.id);
+      if (!pending) continue;
+      pendingAnswers.delete(msg.id);
+      const { interview } = pending;
+      pending.reject(new Error(msg.reason));
+      if (live.session) {
+        live.session.park({
+          eventId: msg.id,
+          eventType: EVENT_TYPES.interviewRequired(interview.scope, interview.key),
+          question: interview.message,
+          questionKey: `${interview.scope}.${interview.key}`,
+        });
+        send({
+          type: 'blocked',
+          sessionId: live.session.id,
+          eventId: msg.id,
+          question: interview.message,
+          key: `${interview.scope}.${interview.key}`,
+        });
       }
       continue;
     }
 
+    if (msg.type === 'attach') {
+      await handleAttach(principal, msg.sessionId);
+      continue;
+    }
+
+    if (msg.type === 'cancel') {
+      handleCancel(principal, msg.sessionId);
+      continue;
+    }
+
     if (msg.type === 'command') {
       // Fire-and-forget so the read loop keeps consuming `answer` messages while
       // the command runs — mid-run interviews are answered in-flight.
-      void handleCommand(principal, msg.argv, busDbPath, ask);
+      commandRunning = handleCommand(msg.argv);
+      void commandRunning;
     }
   }
 
+  // stdin closed: the client is gone. A parked command must NOT die with it —
+  // that is the bug. Stay alive (output goes to the session buffer) until the
+  // command finishes or the reaper abandons it.
+  live.clientAttached = false;
+  if (commandRunning) await commandRunning;
   process.exit(0);
 }