@chorus-aidlc/chorus 0.10.0 → 0.11.1

package/cli/event-router.mjs

@@ -0,0 +1,248 @@
+// cli/event-router.mjs
+// Routes incoming SSE notification events to wakes. Plain ESM adaptation of
+// packages/openclaw-plugin/src/event-router.ts — but instead of OpenClaw's
+// runEmbeddedAgent, it enqueues onto the per-root-idea WakeQueue so the daemon
+// spawns headless Claude with correct serialization.
+//
+// Flow: SSE `new_notification` → fetch full detail via MCP → if it's a wake
+// action, resolve the root-idea key and enqueue the wake. Never throws into the
+// SSE loop.
+
+const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+
+export class EventRouter {
+  /**
+   * @param {{
+   *   mcpClient: { callTool: (name: string, args?: Record<string, unknown>) => Promise<any> },
+   *   waker: { keyFor: (n: any) => Promise<{ key: string, rootIdeaUuid: string|null, directIdeaUuid: string|null }>, wake: (n: any, key: string, attribution?: any) => Promise<void>, markQueued?: (n: any, key: string, attribution?: any) => void },
+   *   queue: { enqueue: (key: string, task: () => Promise<void>) => void },
+   *   wakeActions: Set<string>,
+   *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
+   * }} opts
+   */
+  constructor(opts) {
+    this.mcp = opts.mcpClient;
+    this.waker = opts.waker;
+    this.queue = opts.queue;
+    this.wakeActions = opts.wakeActions;
+    this.logger = opts.logger ?? NOOP_LOGGER;
+    // Shared dedup set: the daemon passes the SAME Set to the reconnect backfill
+    // so a notification handled live is never re-woken on reconnect, and a
+    // duplicate live delivery is dropped. Keyed by notificationUuid, marked at
+    // dispatch time (before any async work) so concurrent dispatches for the
+    // same uuid collapse to one wake.
+    this.seen = opts.seen ?? new Set();
+  }
+
+  /**
+   * Handle one SSE event. Synchronous + non-throwing: it kicks off async
+   * fetch/route work and returns immediately so the SSE consumer never blocks.
+   * @param {{ type?: string, notificationUuid?: string }} event
+   */
+  dispatch(event) {
+    if (event?.type !== "new_notification") {
+      return; // count_update etc. — ignore quietly
+    }
+    if (!event.notificationUuid) {
+      this.logger.warn("[Chorus] new_notification missing notificationUuid, skipping");
+      return;
+    }
+    if (this.seen.has(event.notificationUuid)) {
+      return; // already handled (e.g. live delivery then reconnect backfill)
+    }
+    this.seen.add(event.notificationUuid);
+    this.#fetchAndRoute(event.notificationUuid).catch((err) => {
+      this.logger.error(`[Chorus] failed to route notification ${event.notificationUuid}: ${err}`);
+    });
+  }
+
+  /** @param {string} notificationUuid */
+  async #fetchAndRoute(notificationUuid) {
+    const result = await this.mcp.callTool("chorus_get_notifications", {
+      status: "unread",
+      limit: 50,
+      autoMarkRead: false,
+    });
+    const notifications = result?.notifications;
+    if (!Array.isArray(notifications)) {
+      this.logger.warn("[Chorus] could not fetch notifications list");
+      return;
+    }
+    const n = notifications.find((x) => x?.uuid === notificationUuid);
+    if (!n) {
+      this.logger.warn(`[Chorus] notification ${notificationUuid} not in unread list`);
+      return;
+    }
+    if (!this.wakeActions.has(n.action)) {
+      this.logger.info(`[Chorus] action "${n.action}" is not a wake action — ignoring`);
+      return;
+    }
+
+    // 子2 — daemon-instruction-injection: a `human_instruction` is NOT woken from the
+    // notification path. Its live delivery is the origin-only `deliver_turn` control ping
+    // (precise `turnUuid` → pending-turns sweep), and its recovery is the reconnect
+    // pending-turn backfill — BOTH keyed on `turn:{uuid}` in the shared `seen` set. The
+    // `new_notification` SSE event ALSO arrives here (the action is in WAKE_ACTIONS so the
+    // reconnect notification backfill can re-derive autonomous wakes), but acting on it
+    // here would run the SAME instruction a SECOND time under a DIFFERENT dedup key
+    // (`notificationUuid` vs `turn:{uuid}`) — the double-execution bug — and would fan the
+    // wake out to EVERY connection of the agent rather than the session's origin. So the
+    // notification path explicitly defers `human_instruction` to the turn-keyed paths.
+    if (n.action === "human_instruction") {
+      this.logger.info(
+        `[Chorus] human_instruction ${notificationUuid} is delivered via deliver_turn / pending-turn backfill — not the notification path; ignoring here`
+      );
+      return;
+    }
+
+    await this.#resolveAndEnqueue(n, notificationUuid);
+  }
+
+  /**
+   * Re-dispatch a RESUME (子3 — daemon-interrupt-resume): the reverse control
+   * channel delivered a `command:"resume"` for an entity, so re-run its wake. Unlike
+   * a notification this is NOT fetched from the unread list and has no
+   * notificationUuid — it is a synthetic, entity-generic `resource_resumed` wake.
+   * It flows through the SAME keyFor → markQueued → enqueue path as any wake, so the
+   * per-direct-idea serialization holds and the spawner's on-disk transcript probe
+   * naturally selects `claude --resume <directIdeaUuid>` (the session already
+   * exists). Synchronous + non-throwing, mirroring `dispatch`.
+   * @param {{ entityType?: string, entityUuid?: string }} target
+   */
+  dispatchResume(target) {
+    const entityType = target?.entityType;
+    const entityUuid = target?.entityUuid;
+    if (typeof entityType !== "string" || typeof entityUuid !== "string" || !entityUuid) {
+      this.logger.warn("[Chorus] resume dispatch missing entityType/entityUuid, skipping");
+      return;
+    }
+    const n = { action: "resource_resumed", entityType, entityUuid };
+    this.#resolveAndEnqueue(n, `resume:${entityType}:${entityUuid}`).catch((err) => {
+      this.logger.error(`[Chorus] failed to dispatch resume for ${entityType}:${entityUuid}: ${err}`);
+    });
+  }
+
+  /**
+   * Re-dispatch a backfilled PENDING TURN (子1 — daemon-session-conversation). On
+   * reconnect, the backfill re-derives unstarted turns from the TURN TABLE (the
+   * canonical source — see backfill.mjs) rather than from a possibly-lost notification
+   * ping, so a dropped delivery never loses an instruction. Each pending turn already
+   * carries its session anchor (`sessionId` + `directIdeaUuid`) and — for a
+   * `human_instruction` — its canonical free-text body (`promptText`). We re-run it
+   * through the SAME markQueued → enqueue path as a live wake, BUT skip `keyFor`'s
+   * lineage round-trip: the session key is reconstructed DIRECTLY from the turn's
+   * own ids (which are authoritative), so backfill needs no network beyond the
+   * pending-turns read. Deduped via the shared `seen` set keyed on the turn uuid so a
+   * pending turn already handled live (or by an earlier backfill) is not re-run.
+   * Synchronous + non-throwing, mirroring `dispatch`/`dispatchResume`.
+   *
+   * Only `human_instruction` pending turns are re-dispatched here: autonomous turns
+   * (task_assigned / mentioned / elaboration / resume) are re-driven by the
+   * notification backfill (their notifications are re-fetched), whereas a
+   * human_instruction's actionable payload lives ONLY on the turn — so the turn table
+   * is its sole reliable backfill source.
+   *
+   * @param {{ turnUuid?: string, sessionId?: string, directIdeaUuid?: string|null,
+   *           trigger?: string, promptText?: string|null }} pending
+   */
+  dispatchPendingTurn(pending) {
+    const turnUuid = pending?.turnUuid;
+    const sessionId = pending?.sessionId;
+    if (typeof turnUuid !== "string" || !turnUuid) {
+      this.logger.warn("[Chorus] pending-turn dispatch missing turnUuid, skipping");
+      return;
+    }
+    if (typeof sessionId !== "string" || !sessionId) {
+      this.logger.warn(`[Chorus] pending-turn ${turnUuid} missing sessionId, skipping`);
+      return;
+    }
+    // Only human_instruction is re-derived from the turn table (see doc above).
+    if (pending.trigger !== "human_instruction") {
+      return;
+    }
+    const instruction =
+      typeof pending.promptText === "string" ? pending.promptText.trim() : "";
+    if (!instruction) {
+      this.logger.warn(
+        `[Chorus] pending human_instruction turn ${turnUuid} has no promptText — skipping`
+      );
+      return;
+    }
+    // Shared dedup: a turn uuid keys the seen set so a backfilled pending turn already
+    // handled (live or earlier backfill) does not re-run. Marked BEFORE async work, as
+    // the live path does, so concurrent backfills collapse to one wake.
+    const seenKey = `turn:${turnUuid}`;
+    if (this.seen.has(seenKey)) return;
+    this.seen.add(seenKey);
+
+    const directIdeaUuid =
+      typeof pending.directIdeaUuid === "string" ? pending.directIdeaUuid : null;
+    // Reconstruct the wake's session anchor DIRECTLY from the turn's own ids (no
+    // lineage round-trip). The waker anchors the Claude session on
+    // `directIdeaUuid ?? entityUuid`, and the per-direct-idea queue keys on the same —
+    // so set entityUuid = sessionId so both align with the canonical session.
+    //
+    // Execution entity (子3 follow-up): an idea-anchored conversation reports its
+    // execution against the real idea (`idea:<directIdeaUuid>` — a valid entity); an
+    // AD-HOC conversation has no content entity, so it reports against the conversation
+    // itself (`daemon_session:<sessionId>`). Previously the ad-hoc branch reported
+    // `task:<sessionId>`, which the server DROPS (no Task with that uuid) — so the
+    // running/interrupt state never reached the UI. Because the ad-hoc anchor IS the
+    // sessionId, the execution entityUuid, the Claude `--resume` anchor, and the
+    // per-session UI match key are all the same value.
+    const n = {
+      action: "human_instruction",
+      // The session business key IS the entity anchor here: directIdeaUuid for an
+      // idea-anchored session, else the ad-hoc session id (the original entity uuid).
+      entityType: directIdeaUuid ? "idea" : "daemon_session",
+      entityUuid: directIdeaUuid ? directIdeaUuid : sessionId,
+      instructionText: instruction,
+    };
+    const key = directIdeaUuid ? `idea:${directIdeaUuid}` : `entity:daemon_session:${sessionId}`;
+    const attribution = { key, rootIdeaUuid: directIdeaUuid, directIdeaUuid };
+
+    // Mark queued (snapshot) then enqueue on the same per-direct-idea lane as a live
+    // wake — non-throwing so a missing/failed hook never breaks backfill.
+    try {
+      this.waker.markQueued?.(n, key, attribution);
+    } catch (err) {
+      this.logger.warn(`[Chorus] markQueued failed for pending turn ${turnUuid}: ${err}`);
+    }
+    this.queue.enqueue(key, () => this.waker.wake(n, key, attribution));
+  }
+
+  /**
+   * Resolve a wake's serialization key + idea attribution, mark it queued, and
+   * enqueue it on the per-direct-idea queue. Shared by the notification path
+   * (`#fetchAndRoute`) and the resume re-dispatch (`dispatchResume`). `label` is a
+   * human-readable id for logs (a notificationUuid, or a synthetic resume label).
+   * keyFor may hit the network (lineage), so it runs before enqueue; the wake itself
+   * runs on the queue. `attribution` carries both the direct idea (session anchor, in
+   * the key) and the resolved root idea (for the snapshot), threaded explicitly so
+   * the snapshot's root is never derived from the direct-idea key.
+   * @param {any} n  A notification (or synthetic resume) with at least action +
+   *                 entityType + entityUuid.
+   * @param {string} label
+   */
+  async #resolveAndEnqueue(n, label) {
+    let key;
+    let attribution;
+    try {
+      const resolved = await this.waker.keyFor(n);
+      key = resolved.key;
+      attribution = resolved;
+    } catch (err) {
+      this.logger.warn(`[Chorus] could not resolve wake key for ${label}: ${err}`);
+      return;
+    }
+    // Mark the resource queued (emits a snapshot) BEFORE enqueue, so the server
+    // sees it waiting even while it sits behind a same-direct-idea wake. Optional +
+    // non-throwing so a missing/failed hook never breaks routing.
+    try {
+      this.waker.markQueued?.(n, key, attribution);
+    } catch (err) {
+      this.logger.warn(`[Chorus] markQueued failed for ${label}: ${err}`);
+    }
+    this.queue.enqueue(key, () => this.waker.wake(n, key, attribution));
+  }
+}

package/cli/interrupt-reporter.mjs

@@ -0,0 +1,87 @@
+// cli/interrupt-reporter.mjs
+// Reports a wake's `interrupted` outcome (reason = "user" | "crash") back to the
+// Chorus server (子3 — daemon-interrupt-resume). The waker calls this after a
+// wake's subprocess exits:
+//   • interrupt-initiated exit (the control handler set the "interrupting" flag)
+//       → reason = "user"
+//   • unexpected non-zero exit with NO interrupt flag → reason = "crash"
+//   • clean exit (code 0) → nothing is reported (unchanged behavior).
+//
+// The outcome is recorded on the server's EXECUTION row (keyed connection + entity),
+// NOT on the Task model — the daemon executes task / idea / proposal / document
+// wakes, so the interrupted state is entity-generic. This module therefore reports
+// for ANY recognized entity kind (not just tasks) and carries the daemon's own
+// `connectionUuid` so the server can target the right execution row.
+//
+// Transport: the SHARED daemon REST client (`cli/daemon-rest-client.mjs`) owns the actual
+// `POST /api/daemon/report-interrupt` request, its Bearer auth, and the no-silent-errors
+// transport contract — this module is the thin domain wrapper that validates the
+// entity/reason and maps the call into the client's `reportInterrupt` payload. It adds NO
+// new npm dependency (CLAUDE.md pitfall #9) and no shell-out. It is fire-and-forget and
+// NEVER throws into the wake path: a failure is LOGGED by the shared client (memory:
+// no-silent-errors) and the returned result is swallowed.
+
+import { createDaemonRestClient } from "./daemon-rest-client.mjs";
+
+const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+
+/** Interrupt reason values the server's report-interrupt endpoint accepts. */
+export const INTERRUPT_REASONS = new Set(["user", "crash"]);
+
+/** Entity kinds the server's DaemonExecution (and report-interrupt) accept. Includes
+ *  `daemon_session` — an ad-hoc conversation is its own execution entity, so its
+ *  interrupted/resumable state must be reportable too (else ad-hoc Interrupt→Resume is
+ *  broken: the row would never go sticky `interrupted`+`user` and Resume could never
+ *  fire). Mirrors the server's CONTROL_ENTITY_TYPES. */
+const REPORTABLE_ENTITY_TYPES = new Set([
+  "task",
+  "idea",
+  "proposal",
+  "document",
+  "daemon_session",
+]);
+
+/**
+ * Build a `reportInterrupt(entityType, entityUuid, reason)` function the waker
+ * invokes when a wake's subprocess exits in an interrupted/crashed state.
+ *
+ * @param {{
+ *   url: string,                          Chorus base URL.
+ *   apiKey: string,                       `cho_` agent API key.
+ *   getConnectionUuid: () => string|null, The daemon's registered connection uuid
+ *                                         (learned from the SSE handshake). The
+ *                                         server targets the execution row by
+ *                                         connection + entity, so this is required;
+ *                                         a null/absent value skips the report.
+ *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
+ *   fetchImpl?: typeof fetch,             Injectable for tests.
+ * }} opts
+ * @returns {(entityType: string, entityUuid: string, reason: "user"|"crash") => Promise<void>}
+ */
+export function createInterruptReporter(opts) {
+  const logger = opts.logger ?? NOOP_LOGGER;
+  // The shared client owns the request, Bearer auth, the connectionUuid guard, and the
+  // surface-not-swallow transport contract. This wrapper keeps only the interrupt-domain
+  // validation (entity kind / reason) that is NOT the client's concern.
+  const client = createDaemonRestClient({
+    url: opts.url,
+    apiKey: opts.apiKey,
+    getConnectionUuid: opts.getConnectionUuid ?? (() => null),
+    fetchImpl: opts.fetchImpl,
+    logger,
+  });
+
+  return async function reportInterrupt(entityType, entityUuid, reason) {
+    if (!REPORTABLE_ENTITY_TYPES.has(entityType) || !entityUuid || !INTERRUPT_REASONS.has(reason)) {
+      logger.warn(
+        `[Chorus] refusing to report interrupt: bad entity/reason (${entityType}:${entityUuid}, ${reason})`,
+      );
+      return;
+    }
+    // The client resolves the connectionUuid lazily, validates it (logging
+    // "no connection uuid yet" when absent), POSTs the exact server payload, and logs the
+    // failure cause on a network error / non-2xx. We swallow the structured result so a
+    // failed report can never crash the wake path.
+    await client.reportInterrupt({ entityType, entityUuid, reason });
+  };
+}

package/cli/lineage.mjs

@@ -0,0 +1,155 @@
+// cli/lineage.mjs
+// Resolves any inbound Chorus notification to its idea attribution, so the daemon
+// can anchor one Claude session per DIRECT idea (the entity's directly-attached
+// idea) while still reporting the ROOT idea for observability.
+//
+// Resolution is fully SERVER-SIDE: every notification is resolved by a single
+// call to the standalone REST endpoint
+//   GET /api/entities/{type}/{uuid}/root-idea   (Bearer <cho_ agent key>)
+// which is the single source of truth for entity → idea attribution (it closes
+// the document-attribution gap and defines multi-idea semantics). The endpoint
+// returns BOTH `rootIdeaUuid` (topmost ancestor) and `directIdeaUuid` (the first
+// idea node on the lineage — the entity's directly-attached idea). There is
+// intentionally NO client-side lineage walk — the whole point of this change is
+// to stop the daemon re-implementing the Chorus data model.
+//
+// The daemon anchors the Claude `--session-id` on the DIRECT idea (so a human can
+// `claude --resume <idea-uuid>` to take over), and reports the ROOT idea in its
+// execution snapshot — the two are threaded separately, never derived from each
+// other (see waker.mjs).
+//
+// Uses global fetch (Node 18+), exactly like sse-listener.mjs, so it adds no
+// dependency and reuses the same Bearer auth path. On any failure (unreachable
+// server, non-2xx, malformed body) it returns both ids as null so the caller
+// falls back to a per-entity session key — "no idea ancestor" is a normal,
+// non-fatal outcome.
+
+const NOOP_LOGGER = { info() {}, warn() {}, error() {} };
+
+export class LineageResolver {
+  /**
+   * @param {{
+   *   url: string,        Chorus base URL.
+   *   apiKey: string,     `cho_` agent API key.
+   *   logger?: { info(m:string):void, warn(m:string):void, error(m:string):void },
+   *   fetchImpl?: typeof fetch,  Injectable for tests.
+   * }} opts
+   */
+  constructor(opts) {
+    this.url = opts.url.replace(/\/$/, "");
+    this.apiKey = opts.apiKey;
+    this.logger = opts.logger ?? NOOP_LOGGER;
+    this.fetchImpl = opts.fetchImpl ?? globalThis.fetch;
+    /**
+     * Per-run cache keyed by `${type}:${uuid}`. Holds the full attribution
+     * `{ rootIdeaUuid, directIdeaUuid }` so repeats of the same entity single-flight.
+     * @type {Map<string, { rootIdeaUuid: string|null, directIdeaUuid: string|null }>}
+     */
+    this.cache = new Map();
+  }
+
+  /**
+   * Resolve an event to its idea attribution `{ rootIdeaUuid, directIdeaUuid }`.
+   * One REST call per notification; the per-run cache single-flights repeats of
+   * the same entity. On any failure both ids are null (caller falls back to a
+   * per-entity key). Never throws.
+   * @param {{ entityType?: string, entityUuid?: string }} event
+   * @returns {Promise<{ rootIdeaUuid: string|null, directIdeaUuid: string|null }>}
+   */
+  async resolve(event) {
+    const entityType = event?.entityType;
+    const entityUuid = event?.entityUuid;
+    if (!entityType || !entityUuid) {
+      this.logger.warn("[Chorus] lineage: event missing entityType/entityUuid");
+      return { rootIdeaUuid: null, directIdeaUuid: null };
+    }
+    // An ad-hoc conversation (`daemon_session`) has NO idea ancestor by definition, and
+    // the root-idea endpoint does not accept it (it would 400). Short-circuit to the
+    // null attribution the caller would fall back to anyway — avoiding a guaranteed-failing
+    // round-trip + a spurious warn on every ad-hoc resume. The caller then anchors the
+    // Claude session on the entity uuid (= the ad-hoc sessionId), which is exactly right.
+    if (entityType === "daemon_session") {
+      return { rootIdeaUuid: null, directIdeaUuid: null };
+    }
+    const cacheKey = `${entityType}:${entityUuid}`;
+    const cached = this.cache.get(cacheKey);
+    if (cached) return cached;
+
+    const result = await this.#resolveViaServer(entityType, entityUuid);
+    this.cache.set(cacheKey, result);
+    return result;
+  }
+
+  /**
+   * Back-compat convenience: resolve an event to just its root idea uuid (or null).
+   * @param {{ entityType?: string, entityUuid?: string }} event
+   * @returns {Promise<string|null>}
+   */
+  async rootIdeaFor(event) {
+    return (await this.resolve(event)).rootIdeaUuid;
+  }
+
+  /**
+   * Call GET /api/entities/{type}/{uuid}/root-idea and return
+   * `{ rootIdeaUuid, directIdeaUuid }` (each string | null). Returns both null on
+   * any error so the caller degrades to a per-entity session key — never throws.
+   * @param {string} entityType @param {string} entityUuid
+   * @returns {Promise<{ rootIdeaUuid: string|null, directIdeaUuid: string|null }>}
+   */
+  async #resolveViaServer(entityType, entityUuid) {
+    const NONE = { rootIdeaUuid: null, directIdeaUuid: null };
+    const endpoint =
+      `${this.url}/api/entities/${encodeURIComponent(entityType)}/` +
+      `${encodeURIComponent(entityUuid)}/root-idea`;
+    let response;
+    try {
+      response = await this.fetchImpl(endpoint, {
+        headers: { Authorization: `Bearer ${this.apiKey}`, Accept: "application/json" },
+      });
+    } catch (err) {
+      this.logger.warn(`[Chorus] lineage: request failed for ${entityType}:${entityUuid}: ${err}`);
+      return NONE;
+    }
+    if (!response.ok) {
+      this.logger.warn(
+        `[Chorus] lineage: server returned ${response.status} for ${entityType}:${entityUuid}`
+      );
+      return NONE;
+    }
+    let body;
+    try {
+      body = await response.json();
+    } catch (err) {
+      this.logger.warn(`[Chorus] lineage: bad JSON for ${entityType}:${entityUuid}: ${err}`);
+      return NONE;
+    }
+    // API envelope: { success: true, data: { rootIdeaUuid, directIdeaUuid, lineage, ... } }.
+    const data = body && typeof body === "object" ? body.data : undefined;
+    if (!data || typeof data !== "object" || !("rootIdeaUuid" in data)) {
+      this.logger.warn(
+        `[Chorus] lineage: unexpected response shape for ${entityType}:${entityUuid}`
+      );
+      return NONE;
+    }
+    const root = data.rootIdeaUuid;
+    if (root !== null && typeof root !== "string") {
+      this.logger.warn(`[Chorus] lineage: non-string rootIdeaUuid for ${entityType}:${entityUuid}`);
+      return NONE;
+    }
+    // directIdeaUuid is the daemon's session anchor. Older servers may omit it
+    // (pre-directIdeaUuid endpoint): treat a missing/non-string value as null so
+    // the caller falls back to a per-entity key rather than misanchoring.
+    const directRaw = data.directIdeaUuid;
+    const direct = typeof directRaw === "string" ? directRaw : null;
+    if (directRaw !== undefined && directRaw !== null && typeof directRaw !== "string") {
+      this.logger.warn(
+        `[Chorus] lineage: non-string directIdeaUuid for ${entityType}:${entityUuid}`
+      );
+    }
+    this.logger.info(
+      `[Chorus] lineage: ${entityType}:${entityUuid} → root ${root ?? "none"}, direct ${direct ?? "none"}` +
+        (typeof data.resolvedVia === "string" ? ` (${data.resolvedVia})` : "")
+    );
+    return { rootIdeaUuid: root, directIdeaUuid: direct };
+  }
+}

package/cli/login.mjs

@@ -0,0 +1,151 @@
+// cli/login.mjs
+// `chorus login` — validate a Chorus url + cho_ API key and persist them to
+// ~/.chorus/daemon.json (0600). On validation failure, nothing is written.
+// Plain ESM; the only dependency is the in-repo MCP SDK (via chorus-client).
+
+import { mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { dirname } from "node:path";
+import { createInterface } from "node:readline";
+
+import { loginFilePath } from "./credentials.mjs";
+import { validateAndFetchIdentity } from "./chorus-client.mjs";
+
+/**
+ * Prompt for a line of input. When `mask` is true, typed characters are not
+ * echoed (used for the secret API key — cli-auth spec "interactive key entry
+ * is masked").
+ *
+ * @param {string} query
+ * @param {{ mask?: boolean, input?: NodeJS.ReadableStream, output?: NodeJS.WritableStream }} [opts]
+ * @returns {Promise<string>}
+ */
+export function prompt(query, opts = {}) {
+  const input = opts.input ?? process.stdin;
+  const output = opts.output ?? process.stdout;
+  const mask = opts.mask ?? false;
+
+  return new Promise((resolve) => {
+    const rl = createInterface({ input, output, terminal: true });
+    if (mask) {
+      // Suppress echo: intercept the readline-internal write so typed chars
+      // (and the key itself) never render. The prompt string still shows.
+      const writeToOutput = /** @type {(s: string) => void} */ (
+        rl._writeToOutput?.bind(rl)
+      );
+      rl._writeToOutput = (str) => {
+        if (str === query || str.includes("\n") || str.includes("\r")) {
+          if (writeToOutput) writeToOutput(str);
+          else output.write(str);
+        }
+        // otherwise swallow — no echo of secret characters
+      };
+    }
+    rl.question(query, (answer) => {
+      rl.close();
+      if (mask) output.write("\n");
+      resolve(answer.trim());
+    });
+  });
+}
+
+/**
+ * Persist credentials + identity to the login file with owner-only perms.
+ *
+ * Writing the file with a fresh credential object intentionally OMITS any
+ * `yoloAckAt` that a previous file carried — a credential change (re-login)
+ * clears the yolo acknowledgement, so the next yolo TTY start re-confirms once
+ * (daemon-permission-mode spec). To preserve an existing ack across an
+ * unrelated rewrite, the caller must read it first and pass it in `data`.
+ *
+ * @param {{ url: string, apiKey: string, agentUuid: string, agentName: string, yoloAckAt?: string }} data
+ * @param {{ path?: string, write?: (p: string, c: string, o: object) => void, mkdir?: (p: string, o: object) => void }} [deps]
+ */
+export function writeLoginFile(data, deps = {}) {
+  const path = deps.path ?? loginFilePath();
+  const write = deps.write ?? writeFileSync;
+  const mkdir = deps.mkdir ?? mkdirSync;
+  mkdir(dirname(path), { recursive: true });
+  write(path, JSON.stringify(data, null, 2) + "\n", { mode: 0o600 });
+  return path;
+}
+
+/**
+ * Record (or refresh) the yolo acknowledgement in the existing login file,
+ * preserving the credentials already on disk. Reads the current file, merges
+ * `yoloAckAt`, and rewrites with 0600. Used by the daemon after an interactive
+ * TTY yolo confirmation — it does NOT touch url/apiKey/identity.
+ *
+ * No-silent-errors: a read/parse failure is surfaced to the caller (throws), so
+ * the daemon can log it rather than silently losing the ack.
+ *
+ * @param {string} yoloAckAt  ISO-8601 timestamp of the confirmation.
+ * @param {{ path?: string, read?: (p: string) => string, write?: typeof writeLoginFile }} [deps]
+ * @returns {string} the file path written
+ */
+export function recordYoloAck(yoloAckAt, deps = {}) {
+  const path = deps.path ?? loginFilePath();
+  const read = deps.read ?? ((p) => readFileSync(p, "utf8"));
+  const write = deps.write ?? writeLoginFile;
+  // Start from the existing file when present, else an empty object: a TTY user
+  // whose credentials come from env / flags has no login file yet, but the ack
+  // must still persist (else they'd re-confirm yolo on every start). A file
+  // carrying only `yoloAckAt` is harmless — resolveCredentials simply falls
+  // through it, and a later `chorus login` overwrites (clearing the ack).
+  let current = {};
+  try {
+    const parsed = JSON.parse(read(path));
+    if (parsed && typeof parsed === "object") current = parsed;
+  } catch {
+    // missing / unreadable / malformed → treat as empty (start fresh)
+  }
+  return write({ ...current, yoloAckAt }, { path });
+}
+
+/**
+ * Run the login flow: collect url + key (flags or interactive), validate
+ * against the server, and on success persist + echo identity. Returns an exit
+ * code (0 success, non-zero failure). Never throws.
+ *
+ * @param {{ url?: string, apiKey?: string }} flags
+ * @param {{
+ *   validate?: typeof validateAndFetchIdentity,
+ *   write?: typeof writeLoginFile,
+ *   prompt?: typeof prompt,
+ *   log?: (m: string) => void,
+ *   errLog?: (m: string) => void,
+ * }} [deps]
+ * @returns {Promise<number>}
+ */
+export async function runLogin(flags = {}, deps = {}) {
+  const validate = deps.validate ?? validateAndFetchIdentity;
+  const write = deps.write ?? writeLoginFile;
+  const ask = deps.prompt ?? prompt;
+  const log = deps.log ?? ((m) => process.stdout.write(m + "\n"));
+  const errLog = deps.errLog ?? ((m) => process.stderr.write(m + "\n"));
+
+  let url = typeof flags.url === "string" && flags.url.trim() ? flags.url.trim() : "";
+  let apiKey = typeof flags.apiKey === "string" && flags.apiKey.trim() ? flags.apiKey.trim() : "";
+
+  if (!url) url = await ask("Chorus URL: ");
+  if (!apiKey) apiKey = await ask("Chorus API key (cho_...): ", { mask: true });
+
+  if (!url || !apiKey) {
+    errLog("Login aborted: both a URL and an API key are required.");
+    return 1;
+  }
+
+  let identity;
+  try {
+    identity = await validate({ url, apiKey });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    errLog(`Login failed: ${msg}`);
+    errLog("Credentials were NOT saved.");
+    return 1;
+  }
+
+  const path = write({ url, apiKey, agentUuid: identity.uuid, agentName: identity.name });
+  log(`Logged in as ${identity.name} (${identity.uuid}).`);
+  log(`Credentials saved to ${path}.`);
+  return 0;
+}