@chorus-aidlc/chorus 0.10.0 → 0.11.0

package/cli/client-args.mjs

@@ -0,0 +1,146 @@
+// cli/client-args.mjs
+// Argument parsing + help text for the `chorus` client subcommands (`daemon`,
+// `login`). Extracted from chorus.mjs so it is pure and unit-testable — the
+// entry-point module runs side effects (server launch, process.exit) at import
+// time and cannot be imported into a test. chorus.mjs imports these helpers.
+//
+// Zero dependencies — ships verbatim in the npm package alongside chorus.mjs.
+
+/**
+ * The daemon lifecycle sub-actions (background-mode control). `run` (the
+ * default long-lived daemon) is intentionally NOT in this set — it is the
+ * absence of a recognized sub-action token.
+ */
+export const DAEMON_ACTIONS = new Set(["stop", "status", "restart", "logs"]);
+
+/** Known agent backends. Only `claude-code` is implemented; the rest reserve
+ * the extension point (see daemon-agent-selection). Exported for the resolver
+ * the --agent task wires in; parsing here does not validate the value. */
+export const KNOWN_AGENTS = new Set(["claude-code"]);
+
+/**
+ * Parse the client-subcommand flags out of an arg list. Recognizes the
+ * pre-existing `--url` / `--api-key` / `--sigint-timeout` (space and `=` forms)
+ * and boolean `--yolo`, plus the new `--agent <type>` (space + `=`), boolean
+ * `--chorus-only`, `--verbose`, `-d`/`--detach`, and `--help`/`-h`.
+ *
+ * Only keys that appear are set, so callers can distinguish "unset" from
+ * "false" (important for layered env/flag precedence downstream).
+ *
+ * @param {string[]} argv
+ * @returns {{
+ *   url?: string, apiKey?: string, yolo?: boolean, sigintTimeout?: string,
+ *   agent?: string, chorusOnly?: boolean, verbose?: boolean, detach?: boolean,
+ *   help?: boolean,
+ * }}
+ */
+export function parseClientFlags(argv) {
+  const out = {};
+  for (let i = 0; i < argv.length; i++) {
+    const a = argv[i];
+    if (a === "--url") out.url = argv[i + 1];
+    else if (a.startsWith("--url=")) out.url = a.slice("--url=".length);
+    else if (a === "--api-key") out.apiKey = argv[i + 1];
+    else if (a.startsWith("--api-key=")) out.apiKey = a.slice("--api-key=".length);
+    else if (a === "--yolo") out.yolo = true;
+    else if (a === "--sigint-timeout") out.sigintTimeout = argv[i + 1];
+    else if (a.startsWith("--sigint-timeout=")) out.sigintTimeout = a.slice("--sigint-timeout=".length);
+    else if (a === "--agent") out.agent = argv[i + 1];
+    else if (a.startsWith("--agent=")) out.agent = a.slice("--agent=".length);
+    else if (a === "--chorus-only") out.chorusOnly = true;
+    else if (a === "--verbose") out.verbose = true;
+    else if (a === "-d" || a === "--detach") out.detach = true;
+    else if (a === "--help" || a === "-h") out.help = true;
+  }
+  return out;
+}
+
+/**
+ * Determine the daemon lifecycle sub-action from the args following `daemon`.
+ * The sub-action MUST be the very FIRST token (`chorus daemon stop`), so we
+ * inspect only `rest[0]` — not any non-flag token. Checking the first
+ * positional anywhere would misread a flag *value* that happens to equal an
+ * action verb (`daemon --url stop` → "stop"); pinning to `rest[0]` avoids that.
+ * Anything else (no args, a flag-leading list like `daemon -d` / `daemon --url …`,
+ * or an unknown leading token) is the normal long-lived daemon (`run`).
+ *
+ * @param {string[]} rest  argv after the `daemon` subcommand token
+ * @returns {"run"|"stop"|"status"|"restart"|"logs"}
+ */
+export function parseDaemonAction(rest) {
+  const first = rest[0];
+  if (first && DAEMON_ACTIONS.has(first)) return /** @type any */ (first);
+  return "run";
+}
+
+/**
+ * Help text for `chorus daemon [--help]`. Pure — takes the version so the
+ * caller (which already read package.json) does no IO here.
+ * @param {string} version
+ * @returns {string}
+ */
+export function daemonHelpText(version) {
+  return `
+Chorus daemon v${version} — connect to a remote Chorus server, subscribe to the
+agent notification stream, and wake a local headless agent on task dispatch.
+
+USAGE
+  chorus daemon [options]              Run the daemon (foreground)
+  chorus daemon -d [options]           Run the daemon in the background (detached)
+  chorus daemon stop                   Stop the background daemon
+  chorus daemon status                 Show whether the background daemon is running
+  chorus daemon restart                Restart the background daemon
+  chorus daemon logs                   Show the background daemon log
+
+OPTIONS
+  --url <url>              Remote Chorus server URL            (env: CHORUS_URL)
+  --api-key <cho_...>      Agent API key                       (env: CHORUS_API_KEY)
+  --agent <type>           Local agent backend to wake         (env: CHORUS_AGENT)
+                           (default: claude-code; only claude-code is implemented)
+  --yolo                   Full autonomy for the woken agent   (env: CHORUS_YOLO=1)
+                           (--dangerously-skip-permissions: Bash, file writes, any
+                           command). This is the DEFAULT permission mode.
+  --chorus-only            Restrict the woken agent to Chorus  (env: CHORUS_CHORUS_ONLY=1)
+                           MCP tools only (no Bash / file edits) — reclaims the
+                           safe posture from the default yolo.
+  -d, --detach             Run detached in the background (pidfile + logfile)
+  --verbose                More detailed per-wake logging
+  --sigint-timeout <ms>    Grace window after SIGINT before a forceful kill
+                           (env: CHORUS_DAEMON_SIGINT_TIMEOUT; default 10000)
+  -h, --help               Show this help message
+
+CREDENTIALS
+  Resolution order: flags > CHORUS_URL/CHORUS_API_KEY env >
+  ~/.chorus/daemon.json (from 'chorus login') > Claude Code plugin config.
+  On a TTY with no resolvable credentials, the daemon prompts to complete them.
+
+EXAMPLES
+  chorus daemon                        # Foreground, default yolo (TTY confirms once)
+  chorus daemon --chorus-only          # Restrict the woken agent to Chorus tools
+  chorus daemon -d                     # Background; see 'chorus daemon logs'
+  chorus daemon stop                   # Stop the background daemon
+`;
+}
+
+/**
+ * Help text for `chorus login [--help]`.
+ * @param {string} version
+ * @returns {string}
+ */
+export function loginHelpText(version) {
+  return `
+Chorus login v${version} — authenticate as an agent and save credentials to
+~/.chorus/daemon.json (0600) for later use by 'chorus daemon'.
+
+USAGE
+  chorus login [options]               Validate a key and persist credentials
+
+OPTIONS
+  --url <url>              Remote Chorus server URL            (env: CHORUS_URL)
+  --api-key <cho_...>      Agent API key                       (env: CHORUS_API_KEY)
+  -h, --help               Show this help message
+
+  With no flags, login prompts interactively for the URL and a masked API key,
+  validates them against the server, and on success saves the credentials.
+`;
+}

package/cli/control-handler.mjs

@@ -0,0 +1,180 @@
+// cli/control-handler.mjs
+// Daemon-side handler for reverse control commands (子3 — daemon-interrupt-resume,
+// Tech Design "Architecture" / q1=a double-check). The SSE listener forks a
+// `type:"control"` event here (NOT to the wake router) — see sse-listener.mjs.
+//
+// The single safety property this module enforces is the DOUBLE-CHECK (q1=a): act
+// ONLY when BOTH hold —
+//   1. event.targetConnectionUuid === this daemon's OWN registered connectionUuid, AND
+//   2. the waker's in-memory execution registry holds a RUNNING child for the
+//      command's `${entityType}:${entityUuid}`.
+// On either mismatch the command is IGNORED and LOGGED (memory: no-silent-errors),
+// so a stale / recycled connection uuid can never make the daemon kill the wrong
+// subprocess (Tech Design "Risks": mis-kill after a reconnect).
+//
+// On a verified match it (a) sets a per-entity "interrupting" flag on the waker so
+// the waker reports the resulting exit as interrupted(reason="user") rather than a
+// crash, then (b) invokes the injected killer (process-killer.killProcessTree) on
+// the live child. The kill is fire-and-forget from the listener's perspective; this
+// handler never throws into the SSE loop.
+//
+// Plain ESM, zero new deps. The killer + connectionUuid getter are injected so the
+// handler is unit-testable without a real subprocess or SSE stream.
+
+import { killProcessTree } from "./process-killer.mjs";
+
+const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+
+/**
+ * Build the `onControl(event)` callback the SseListener invokes for a
+ * `type:"control"` event.
+ *
+ * @param {{
+ *   waker: {
+ *     executions: Map<string, { entityType: string, entityUuid: string, child?: any, status: string }>,
+ *     markInterrupting?: (entityType: string, entityUuid: string) => void,
+ *   },
+ *   getConnectionUuid: () => (string|null),  This daemon's registered connection uuid
+ *                                            (null until the SSE handshake reports it).
+ *   killer?: (child: any, opts: any) => Promise<any>,  Injectable; defaults to killProcessTree.
+ *   sigintTimeoutMs?: number,                           Layered-resolved escalation window.
+ *   redispatchResume?: (entityType: string, entityUuid: string) => void,  Re-run a wake
+ *                                            for a resumed entity (子3); injected by the daemon.
+ *   deliverTurn?: (turnUuid?: string) => void, Dispatch a PRECISE pending turn by uuid
+ *                                            (子2 — origin-only live delivery). On a
+ *                                            `deliver_turn` control event (after the Check-1
+ *                                            connection match) the handler invokes this with
+ *                                            the event's `turnUuid` so ONLY that one new
+ *                                            pending `human_instruction` turn runs — not a
+ *                                            connection-wide sweep that would also drag every
+ *                                            other still-pending turn along. Injected by the
+ *                                            daemon (`backfill.pendingTurnsOnly`); the
+ *                                            arg-less form (reconnect) still sweeps all.
+ *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
+ * }} deps
+ * @returns {(event: any) => void}  The onControl callback (synchronous, non-throwing).
+ */
+export function createControlHandler(deps) {
+  const waker = deps.waker;
+  const getConnectionUuid = deps.getConnectionUuid;
+  const killer = deps.killer ?? killProcessTree;
+  const sigintTimeoutMs = deps.sigintTimeoutMs;
+  const redispatchResume = deps.redispatchResume;
+  const deliverTurn = deps.deliverTurn;
+  const logger = deps.logger ?? NOOP_LOGGER;
+
+  /** Registry key for a resource — MUST match waker.#execKey. */
+  const execKey = (entityType, entityUuid) => `${entityType}:${entityUuid}`;
+
+  /**
+   * Handle one control event. Synchronous + non-throwing: it performs the
+   * double-check and kicks off the (async) kill fire-and-forget, returning
+   * immediately so the SSE consumer never blocks. `interrupt` (kill), `resume`
+   * (re-dispatch wake), and `deliver_turn` (origin-only live delivery — trigger the
+   * pending-turns sweep) are acted on; any other/unknown command is ignored + logged
+   * (forward-compatible).
+   * @param {{ type?: string, command?: string, targetConnectionUuid?: string, entityType?: string, entityUuid?: string }} event
+   */
+  return function onControl(event) {
+    try {
+      if (!event || event.type !== "control") {
+        logger.warn(`[Chorus] control-handler received non-control event; ignoring`);
+        return;
+      }
+      if (
+        event.command !== "interrupt" &&
+        event.command !== "resume" &&
+        event.command !== "deliver_turn"
+      ) {
+        // Forward-compatible: the wire enum may grow.
+        logger.warn(`[Chorus] control command "${event.command}" not supported; ignoring`);
+        return;
+      }
+
+      const { command, targetConnectionUuid, entityType, entityUuid } = event;
+
+      // --- Check 1: connection-uuid match (applies to every command) ---
+      const myConnectionUuid = getConnectionUuid?.() ?? null;
+      if (!myConnectionUuid || targetConnectionUuid !== myConnectionUuid) {
+        // Not ours (stale/recycled uuid, or handshake not yet complete). Ignore.
+        logger.info(
+          `[Chorus] control: ignoring ${command} for connection ${targetConnectionUuid} ` +
+            `(this daemon is ${myConnectionUuid ?? "<unregistered>"})`
+        );
+        return;
+      }
+
+      // --- deliver_turn: origin-only live delivery (子2). The session's origin connection
+      //     (THIS one — Check 1 passed) was pinged that a SPECIFIC new pending
+      //     `human_instruction` turn (`event.turnUuid`) awaits. Dispatch ONLY that turn — not
+      //     a connection-wide sweep, which would also drag every other still-pending turn of
+      //     this connection along (the multi-wake bug). No entity is carried on the wire (the
+      //     turn is read by uuid), and there is NO running-child requirement (mirrors
+      //     `resume`); the read resolves the text from the persisted turn. Idempotent with
+      //     reconnect backfill via the shared `seen` set (key turn:{uuid}). A `deliver_turn`
+      //     missing `turnUuid` (older server) falls back to the full sweep so it still runs. ---
+      if (command === "deliver_turn") {
+        const turnUuid = typeof event.turnUuid === "string" ? event.turnUuid : undefined;
+        logger.info(
+          `[Chorus] control: deliver_turn for connection ${targetConnectionUuid} ` +
+            (turnUuid ? `(turn ${turnUuid})` : "(no turnUuid — full sweep fallback)"),
+        );
+        try {
+          deliverTurn?.(turnUuid);
+        } catch (err) {
+          logger.warn(`[Chorus] control: deliver_turn failed: ${err}`);
+        }
+        return;
+      }
+
+      if (typeof entityType !== "string" || typeof entityUuid !== "string") {
+        logger.warn(`[Chorus] control: ${command} missing entityType/entityUuid; ignoring`);
+        return;
+      }
+
+      // --- resume: re-dispatch the wake for this entity (子3). No running-child
+      //     check — the subprocess is gone (it was interrupted); the wake path will
+      //     re-spawn and `--resume` the existing session. ---
+      if (command === "resume") {
+        logger.info(`[Chorus] control: resuming ${entityType}:${entityUuid} (re-dispatch wake)`);
+        try {
+          redispatchResume?.(entityType, entityUuid);
+        } catch (err) {
+          logger.warn(`[Chorus] control: resume re-dispatch failed for ${entityType}:${entityUuid}: ${err}`);
+        }
+        return;
+      }
+
+      // --- interrupt path: Check 2 — in-memory entity ownership (running child) ---
+      const key = execKey(entityType, entityUuid);
+      const entry = waker?.executions?.get(key);
+      if (!entry || entry.status !== "running" || !entry.child) {
+        // Either we never ran this entity, it's only queued (no child yet), or the
+        // wake already finished (race: interrupt arrived after exit). Safe no-op.
+        logger.info(
+          `[Chorus] control: no running subprocess for ${key} on this daemon; ignoring interrupt`
+        );
+        return;
+      }
+
+      // --- Both checks passed: mark interrupting (so the waker reports reason=user),
+      //     then kill the tree. ---
+      logger.info(`[Chorus] control: interrupting running subprocess for ${key} (pid=${entry.child.pid})`);
+      try {
+        waker.markInterrupting?.(entityType, entityUuid);
+      } catch (err) {
+        logger.warn(`[Chorus] control: markInterrupting failed for ${key}: ${err}`);
+      }
+
+      // Fire-and-forget the kill: the waker observes the child's exit and reports
+      // the interrupted state. The killer never throws, but guard the promise
+      // anyway so a rejection can't surface as an unhandled rejection.
+      Promise.resolve(killer(entry.child, { sigintTimeoutMs, logger })).catch((err) => {
+        logger.warn(`[Chorus] control: killProcessTree rejected for ${key}: ${err}`);
+      });
+    } catch (err) {
+      // Absolute backstop — a control event must never crash the SSE loop.
+      logger.error(`[Chorus] control-handler unexpected error: ${err}`);
+    }
+  };
+}

package/cli/credentials.mjs

@@ -0,0 +1,155 @@
+// cli/credentials.mjs
+// Layered resolution of the Chorus server URL + `cho_` API key for the daemon
+// and login subcommands. Plain ESM, zero dependencies — ships verbatim in the
+// npm package alongside chorus.mjs (see package.json `files`).
+//
+// Precedence (first complete pair wins):
+//   1. explicit flags        --url / --api-key
+//   2. environment           CHORUS_URL / CHORUS_API_KEY
+//   3. login file            ~/.chorus/daemon.json   (written by `chorus login`)
+//   4. plugin fallback       ~/.claude/settings.json  → .env.CHORUS_URL / .env.CHORUS_API_KEY
+//
+// The CC chorus plugin does NOT persist credentials to a file — it reads
+// CHORUS_URL / CHORUS_API_KEY from the environment, which users configure in
+// the `env` block of ~/.claude/settings.json. Tier 4 reads that block as a
+// best-effort last resort (file may be absent or differently shaped — read
+// defensively). Verified against the 0.10.0 plugin: bin/*.sh all read the two
+// env vars; .chorus/state.json holds session state, never credentials.
+
+import { readFileSync } from "node:fs";
+import { homedir } from "node:os";
+import { join } from "node:path";
+
+/** Absolute path to the login file written by `chorus login`. */
+export function loginFilePath() {
+  return join(homedir(), ".chorus", "daemon.json");
+}
+
+/** Absolute path to the Claude Code user settings file (plugin fallback source). */
+export function claudeSettingsPath() {
+  return join(homedir(), ".claude", "settings.json");
+}
+
+/**
+ * Read a JSON file, returning `null` on any error (missing / unreadable /
+ * malformed). Never throws — callers treat a null as "source absent".
+ * @param {string} path
+ * @returns {Record<string, unknown> | null}
+ */
+function readJsonSafe(path) {
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed = JSON.parse(raw);
+    return parsed && typeof parsed === "object" ? parsed : null;
+  } catch {
+    return null;
+  }
+}
+
+/** A non-empty string, or undefined. Trims; empty/whitespace → undefined. */
+function nonEmpty(value) {
+  if (typeof value !== "string") return undefined;
+  const trimmed = value.trim();
+  return trimmed.length > 0 ? trimmed : undefined;
+}
+
+/**
+ * Read the recorded yolo acknowledgement (`yoloAckAt`) from the login file, if
+ * present. Returns the ISO-8601 string, or null when the file is absent /
+ * unreadable / carries no ack. Never throws (a missing ack just means "not yet
+ * confirmed"). The ack lives in the same `~/.chorus/daemon.json` as the
+ * credentials — there is no separate ack file (daemon-permission-mode spec).
+ *
+ * @param {{ readJson?: (p: string) => (Record<string, unknown>|null), loginPath?: string }} [deps]
+ * @returns {string | null}
+ */
+export function readYoloAck(deps = {}) {
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+  const file = readJson(loginPath);
+  return file ? nonEmpty(file.yoloAckAt) ?? null : null;
+}
+
+/**
+ * @typedef {Object} ResolvedCredentials
+ * @property {string} url
+ * @property {string} apiKey
+ * @property {"flag"|"env"|"login-file"|"plugin-fallback"} source
+ */
+
+/**
+ * @typedef {Object} ResolveDeps  Injectable IO for tests (no real disk/env).
+ * @property {Record<string, string|undefined>} [env]
+ * @property {(path: string) => (Record<string, unknown>|null)} [readJson]
+ * @property {string} [loginPath]
+ * @property {string} [settingsPath]
+ */
+
+/**
+ * Resolve credentials from the four layered sources, in fixed precedence.
+ *
+ * @param {{ url?: string, apiKey?: string }} flags  Explicit --url / --api-key.
+ * @param {ResolveDeps} [deps]
+ * @returns {ResolvedCredentials}
+ * @throws {Error} when no source yields a complete url+apiKey pair. The message
+ *   lists every source that was tried and how to supply credentials.
+ */
+export function resolveCredentials(flags = {}, deps = {}) {
+  const env = deps.env ?? process.env;
+  const readJson = deps.readJson ?? readJsonSafe;
+  const loginPath = deps.loginPath ?? loginFilePath();
+  const settingsPath = deps.settingsPath ?? claudeSettingsPath();
+
+  const tried = [];
+
+  // 1. Explicit flags
+  tried.push("--url/--api-key flags");
+  {
+    const url = nonEmpty(flags.url);
+    const apiKey = nonEmpty(flags.apiKey);
+    if (url && apiKey) return { url, apiKey, source: "flag" };
+  }
+
+  // 2. Environment variables
+  tried.push("CHORUS_URL / CHORUS_API_KEY environment variables");
+  {
+    const url = nonEmpty(env.CHORUS_URL);
+    const apiKey = nonEmpty(env.CHORUS_API_KEY);
+    if (url && apiKey) return { url, apiKey, source: "env" };
+  }
+
+  // 3. Login file (~/.chorus/daemon.json)
+  tried.push(`login file (${loginPath}, run \`chorus login\`)`);
+  {
+    const file = readJson(loginPath);
+    if (file) {
+      const url = nonEmpty(file.url);
+      const apiKey = nonEmpty(file.apiKey);
+      if (url && apiKey) return { url, apiKey, source: "login-file" };
+    }
+  }
+
+  // 4. Plugin fallback (~/.claude/settings.json → env block)
+  tried.push(`Claude Code plugin config (${settingsPath} → env.CHORUS_URL/CHORUS_API_KEY)`);
+  {
+    const settings = readJson(settingsPath);
+    const envBlock =
+      settings && typeof settings.env === "object" && settings.env !== null
+        ? /** @type {Record<string, unknown>} */ (settings.env)
+        : null;
+    if (envBlock) {
+      const url = nonEmpty(envBlock.CHORUS_URL);
+      const apiKey = nonEmpty(envBlock.CHORUS_API_KEY);
+      if (url && apiKey) return { url, apiKey, source: "plugin-fallback" };
+    }
+  }
+
+  throw new Error(
+    "Could not resolve Chorus credentials (url + cho_ API key). Tried, in order:\n" +
+      tried.map((t, i) => `  ${i + 1}. ${t}`).join("\n") +
+      "\n\nSupply credentials with one of:\n" +
+      "  • flags:   chorus daemon --url <https://...> --api-key <cho_...>\n" +
+      "  • env:     CHORUS_URL=<https://...> CHORUS_API_KEY=<cho_...> chorus daemon\n" +
+      "  • login:   chorus login   (persists to ~/.chorus/daemon.json)\n"
+  );
+}

package/cli/daemon-agent.mjs

@@ -0,0 +1,38 @@
+// cli/daemon-agent.mjs
+// Pure resolution + validation of the daemon's `--agent <type>` selection. The
+// flag/env exist to RESERVE the extension point for future agent backends
+// (e.g. codex); only `claude-code` is implemented in this change. Resolving an
+// unknown value is a hard error (no silent fallback). Zero dependencies.
+
+/** The agent backends the daemon recognizes. Only `claude-code` is implemented. */
+export const KNOWN_AGENTS = ["claude-code"];
+
+/** The default agent backend when neither --agent nor CHORUS_AGENT is set. */
+export const DEFAULT_AGENT = "claude-code";
+
+/**
+ * Resolve the agent type from flag → env → default, and validate it.
+ * Precedence: explicit `--agent` flag > CHORUS_AGENT env > DEFAULT_AGENT.
+ *
+ * @param {{ agent?: string }} flags
+ * @param {Record<string, string|undefined>} env
+ * @returns {{ ok: true, agent: string } | { ok: false, value: string, error: string }}
+ *   `ok:false` carries the offending value and a human-actionable error naming
+ *   the accepted types — the caller exits non-zero and prints `error`.
+ */
+export function resolveAgentType(flags, env) {
+  const raw =
+    (typeof flags.agent === "string" && flags.agent.trim()) ||
+    (typeof env.CHORUS_AGENT === "string" && env.CHORUS_AGENT.trim()) ||
+    DEFAULT_AGENT;
+  if (!KNOWN_AGENTS.includes(raw)) {
+    return {
+      ok: false,
+      value: raw,
+      error:
+        `Unknown --agent "${raw}". Accepted: ${KNOWN_AGENTS.join(", ")}. ` +
+        `(Only ${DEFAULT_AGENT} is implemented; the flag reserves the slot for future agents.)`,
+    };
+  }
+  return { ok: true, agent: raw };
+}

package/cli/daemon-banner.mjs

@@ -0,0 +1,80 @@
+// cli/daemon-banner.mjs
+// Pure formatter for the daemon's boxed startup banner — one screen summarizing
+// the daemon's posture. No IO: `formatBanner(info)` returns a string the caller
+// writes. Degrades box-drawing to plain lines when `isTTY` is false so piped /
+// redirected output stays clean and never depends on terminal width.
+//
+// SECURITY: the banner shows the credential SOURCE, never the raw API key
+// (owner decision: no masking needed because the key is simply not displayed).
+// Zero dependencies — ships in the npm package alongside chorus.mjs.
+
+/**
+ * @typedef {Object} BannerInfo
+ * @property {string} version          chorus CLI version.
+ * @property {string} url              remote server URL.
+ * @property {string} agentName        authenticated agent name.
+ * @property {string} agentUuid        authenticated agent uuid.
+ * @property {"yolo"|"chorus"} permissionMode
+ * @property {string} credentialSource resolved credential source (flag/env/login-file/…).
+ * @property {string} agentType        local agent backend (e.g. claude-code).
+ * @property {string|null} claudePath  resolved claude path, or null when not found.
+ * @property {string} [connection]     connection state line (default "connecting…").
+ */
+
+/** Right-pad to width (banner box alignment). */
+function pad(s, width) {
+  return s.length >= width ? s : s + " ".repeat(width - s.length);
+}
+
+/**
+ * Build the banner's labelled rows (label, value) in display order. Pure — also
+ * used by tests to assert content independently of the box framing.
+ * @param {BannerInfo} info
+ * @returns {Array<[string, string]>}
+ */
+export function bannerRows(info) {
+  const permission =
+    info.permissionMode === "yolo"
+      ? "YOLO ⚠  (full autonomy — Bash/write/any command)"
+      : "chorus-only (Chorus MCP tools only)";
+  const claude = info.claudePath ? `found: ${info.claudePath}` : "NOT FOUND — install `claude` or set CHORUS_CLAUDE_PATH";
+  return [
+    ["Version", `chorus v${info.version}`],
+    ["Server", info.url],
+    ["Agent", `${info.agentName} (${info.agentUuid})`],
+    ["Agent type", info.agentType],
+    ["Permission", permission],
+    ["Credentials", `source: ${info.credentialSource}`],
+    ["Connection", info.connection ?? "connecting…"],
+    ["claude CLI", claude],
+  ];
+}
+
+/**
+ * Format the startup banner. On a TTY, draws a Unicode box; otherwise emits
+ * plain `label: value` lines (no box-drawing chars, no width math) so piped
+ * output is clean. Never throws.
+ * @param {BannerInfo} info
+ * @param {{ isTTY?: boolean }} [opts]
+ * @returns {string}
+ */
+export function formatBanner(info, opts = {}) {
+  const rows = bannerRows(info);
+  const isTTY = opts.isTTY ?? false;
+
+  if (!isTTY) {
+    // Plain mode: stable, greppable, no box-drawing.
+    const lines = ["Chorus daemon", ...rows.map(([k, v]) => `  ${k}: ${v}`)];
+    return lines.join("\n") + "\n";
+  }
+
+  const labelW = Math.max(...rows.map(([k]) => k.length));
+  const body = rows.map(([k, v]) => `${pad(k, labelW)}  ${v}`);
+  const title = "Chorus daemon";
+  const innerW = Math.max(title.length, ...body.map((l) => l.length));
+  const top = "┌" + "─".repeat(innerW + 2) + "┐";
+  const bottom = "└" + "─".repeat(innerW + 2) + "┘";
+  const sep = "├" + "─".repeat(innerW + 2) + "┤";
+  const line = (s) => `│ ${pad(s, innerW)} │`;
+  return [top, line(title), sep, ...body.map(line), bottom].join("\n") + "\n";
+}