salidium 0.2.3 → 0.2.4

package/bundle/salidium.mjs

@@ -21651,7 +21651,7 @@ function explainerCwd() {
   mkdirSync(dir, { recursive: true, mode: 448 });
   return dir;
 }
-function runProcess(invocation, timeoutMs) {
+function runProcess(invocation, timeoutMs, signal) {
   return new Promise((resolve2, reject) => {
     const path = trustedPathEntries().join(delimiter2);
     const child = spawn(invocation.command, invocation.args, {
@@ -21666,14 +21666,29 @@ function runProcess(invocation, timeoutMs) {
     let err = "";
     let outBytes = 0;
     let settled = false;
+    let timer;
+    const cleanup = () => {
+      if (timer)
+        clearTimeout(timer);
+      signal?.removeEventListener("abort", abort);
+    };
     const fail = (error51) => {
       if (settled)
         return;
       settled = true;
-      clearTimeout(timer);
+      cleanup();
       reject(error51);
     };
-    const timer = setTimeout(() => {
+    const abort = () => {
+      child.kill("SIGKILL");
+      fail(new Error("explainer canceled"));
+    };
+    signal?.addEventListener("abort", abort, { once: true });
+    if (signal?.aborted) {
+      abort();
+      return;
+    }
+    timer = setTimeout(() => {
       child.kill("SIGKILL");
       fail(new Error(`explainer timed out after ${timeoutMs}ms`));
     }, timeoutMs);
@@ -21697,7 +21712,7 @@ function runProcess(invocation, timeoutMs) {
       if (settled)
         return;
       settled = true;
-      clearTimeout(timer);
+      cleanup();
       if (code === 0)
         resolve2(out);
       else
@@ -21793,7 +21808,7 @@ function createClaudeExplainerBackend(resolvedCommand) {
         throw new Error("trusted claude command is unavailable");
       const invocation = buildClaudeInvocation(request, command);
       return {
-        output: await runProcess(invocation, request.timeoutMs),
+        output: await runProcess(invocation, request.timeoutMs, request.signal),
         model: invocation.model
       };
     }
@@ -21811,7 +21826,7 @@ function createCodexExplainerBackend(resolvedCommand) {
       writeFileSync(schemaPath, JSON.stringify(request.schema), { mode: 384 });
       const invocation = buildCodexInvocation(request, schemaPath, command);
       return {
-        output: await runProcess(invocation, request.timeoutMs),
+        output: await runProcess(invocation, request.timeoutMs, request.signal),
         model: invocation.model
       };
     }
@@ -22087,7 +22102,8 @@ async function explainWithStatus(state, opts = {}) {
       evidence,
       schema: SCHEMA,
       model,
-      timeoutMs
+      timeoutMs,
+      signal: opts.signal
     });
     raw = result.output;
     generatedBy = result.model;
@@ -23076,6 +23092,8 @@ var SessionCoordinator = class _SessionCoordinator {
   closed = false;
   flushFailures = 0;
   explanationStatus;
+  /** Owns the one provider call this coordinator may have in flight. */
+  explanationAbort;
   /** The stop in force for this session; the registry pushes a change to every live coordinator. */
   cadence;
   idleEndTimer;
@@ -23107,11 +23125,11 @@ var SessionCoordinator = class _SessionCoordinator {
       flushThreshold: 250,
       checkpointEvery: 500,
       explain: envAllows,
-      // The registry passes the stored stop; a coordinator loaded without one keeps the behaviour
-      // that shipped, which is a fresh explanation at every turn end.
-      cadence: envAllows ? "turn" : "off",
+      // Fail closed when a caller does not pass a stored preference. Model work must always be an
+      // explicit opt-in, including in future coordinator call sites that bypass the registry.
+      cadence: "off",
       idleEndMs: IDLE_END_MS,
-      explainSession: explainWithStatus,
+      explainSession: (state2, signal) => explainWithStatus(state2, { signal }),
       now: Date.now,
       ...args.options
     };
@@ -23282,6 +23300,7 @@ var SessionCoordinator = class _SessionCoordinator {
     this.cadence = cadence;
     if (cadence === "off") {
       this.clearIdleEnd();
+      this.explanationAbort?.abort();
       this.explanationStatus = "disabled";
     } else if (wasOff) {
       this.explanationStatus = void 0;
@@ -23341,7 +23360,7 @@ var SessionCoordinator = class _SessionCoordinator {
     }
     if (this.state.internal)
       return;
-    if (this.explanationStatus === "generating")
+    if (this.explanationAbort)
       return;
     if (this.explainedSeq === this.state.latestSeq)
       return;
@@ -23352,14 +23371,22 @@ var SessionCoordinator = class _SessionCoordinator {
     this.explanationStatus = "generating";
     this.scheduleSummary();
     const seq = this.state.latestSeq;
-    void this.opts.explainSession(this.state).then((result) => {
+    const controller = new AbortController();
+    this.explanationAbort = controller;
+    void this.opts.explainSession(this.state, controller.signal).then((result) => {
+      if (controller.signal.aborted)
+        return;
       if (result.status === "generated")
         this.ingest([result.event]);
       this.explanationStatus = result.status;
       this.explainedSeq = result.status === "generated" ? this.state.latestSeq : seq;
     }).catch(() => {
+      if (controller.signal.aborted)
+        return;
       this.explanationStatus = "failed";
     }).finally(() => {
+      if (this.explanationAbort === controller)
+        this.explanationAbort = void 0;
       this.scheduleSummary();
     });
   }
@@ -23434,6 +23461,7 @@ var SessionCoordinator = class _SessionCoordinator {
   close() {
     this.closed = true;
     this.clearIdleEnd();
+    this.explanationAbort?.abort();
     if (this.summaryTimer)
       clearTimeout(this.summaryTimer);
     this.checkpoint();
@@ -23465,7 +23493,7 @@ var SessionRegistry = class {
    * The stop every coordinator is loaded with. Held here rather than read from the store on each
    * load: it is one value for the whole daemon, and a coordinator is created on the ingest path.
    */
-  explainerCadence = "turn";
+  explainerCadence = "off";
   /** Handed to every coordinator this registry loads; see `CoordinatorOptions.now`. */
   now;
   /** Reads the daemon's current helper routing at call time, so settings apply without a restart. */
@@ -25450,7 +25478,7 @@ var VERSION = (() => {
   }
 })();
 var DEFAULT_SETTINGS = {
-  explainerCadence: "turn",
+  explainerCadence: "off",
   explainerBackend: "auto",
   explainerModel: null
 };
@@ -25548,9 +25576,9 @@ async function startDaemon(overrides = {}) {
   const activeExplainer = () => explainedConfiguration(stored.explainerBackend, stored.explainerModel, process.env);
   const registry2 = new SessionRegistry(store, {
     explainerCadence: effectiveCadence(stored.explainerCadence),
-    explainSession: (state) => {
+    explainSession: (state, signal) => {
       const active = activeExplainer();
-      return explainWithStatus(state, { mode: active.mode, model: active.model });
+      return explainWithStatus(state, { mode: active.mode, model: active.model, signal });
     },
     ...overrides.now ? { now: overrides.now } : {}
   });
@@ -25915,6 +25943,36 @@ function renderAudit(r, opts) {
 `;
 }
 
+// src/explanationMode.ts
+var LOCAL_ONLY = {
+  value: "off",
+  label: "Local only",
+  detail: "No model calls"
+};
+var WHEN_DONE = {
+  value: "session",
+  label: "When done",
+  detail: "One model call after a session ends"
+};
+var EACH_REPLY = {
+  value: "turn",
+  label: "Each reply",
+  detail: "One model call after each agent reply"
+};
+var EXPLANATION_MODES = [LOCAL_ONLY, WHEN_DONE, EACH_REPLY];
+function explanationMode(cadence) {
+  if (cadence === "session") return WHEN_DONE;
+  if (cadence === "turn") return EACH_REPLY;
+  return LOCAL_ONLY;
+}
+function parseExplanationMode(value) {
+  const normalized2 = value?.trim().toLowerCase();
+  if (normalized2 === "off" || normalized2 === "local" || normalized2 === "local-only") return "off";
+  if (normalized2 === "session" || normalized2 === "when-done") return "session";
+  if (normalized2 === "turn" || normalized2 === "each-reply") return "turn";
+  return void 0;
+}
+
 // src/integrations.ts
 import { existsSync as existsSync8 } from "node:fs";
 import { join as join11 } from "node:path";
@@ -26265,11 +26323,164 @@ function integrationById(id) {
   return providerIntegrationRegistry.get(id);
 }
 
+// src/terminalUi.ts
+var RESET = "\x1B[0m";
+var ANSI2 = {
+  bold: "\x1B[1m",
+  accent: "\x1B[38;2;143;166;255m",
+  accentBackground: "\x1B[48;2;59;91;219m\x1B[38;2;255;255;255m",
+  textMuted: "\x1B[38;2;142;142;139m",
+  rail: "\x1B[38;2;91;91;88m",
+  ok: "\x1B[38;2;95;207;136m",
+  warn: "\x1B[38;2;224;168;60m",
+  danger: "\x1B[38;2;240;115;106m",
+  claude: "\x1B[38;2;231;155;125m",
+  codex: "\x1B[38;2;79;196;163m"
+};
+function paint(enabled, code, value) {
+  return enabled ? `${code}${value}${RESET}` : value;
+}
+var TerminalUi = class {
+  color;
+  constructor(color = false) {
+    this.color = color;
+  }
+  tone(value, tone) {
+    const code = tone === "muted" ? ANSI2.textMuted : tone === "claude" ? ANSI2.claude : tone === "codex" ? ANSI2.codex : ANSI2[tone];
+    return paint(this.color, code, value);
+  }
+  bold(value) {
+    return paint(this.color, ANSI2.bold, value);
+  }
+  rail(glyph) {
+    return paint(this.color, ANSI2.rail, glyph);
+  }
+  header(firstRun) {
+    const brand = paint(this.color, ANSI2.accentBackground, " SALIDIUM ");
+    const mode = this.tone(firstRun ? "FIRST-RUN SETUP" : "AGENT SETUP", "muted");
+    return `
+  ${brand}  ${mode}
+  ${this.tone("Connect your coding agents", "muted")}
+`;
+  }
+  section(label) {
+    return `
+  ${this.tone("\u25C6", "accent")}  ${this.bold(label.toUpperCase())}
+`;
+  }
+  copy(text) {
+    return `  ${this.rail("\u2502")}  ${text}
+`;
+  }
+  spacer() {
+    return `  ${this.rail("\u2502")}
+`;
+  }
+  status(mark2, label, detail, tone) {
+    return `  ${this.rail("\u2502")}  ${this.tone(mark2, tone)} ${this.bold(label.padEnd(14))} ${this.tone(detail, "muted")}
+`;
+  }
+  path(provider, providerId, value) {
+    const tone = providerId === "claude-code" ? "claude" : "codex";
+    return [
+      `  ${this.rail("\u2502")}  ${this.tone(provider, tone)}
+`,
+      `  ${this.rail("\u2502")}  ${this.rail("\u2514\u2500")} ${this.tone(value, "muted")}
+`
+    ].join("");
+  }
+  attention(text) {
+    return `  ${this.rail("\u2502")}  ${this.tone("!", "warn")} ${text}
+`;
+  }
+  item(mark2, text, tone) {
+    return `  ${this.rail("\u2502")}  ${this.tone(mark2, tone)} ${text}
+`;
+  }
+  failure(text) {
+    return `  ${this.rail("\u2502")}  ${this.tone("\xD7", "danger")} ${text}
+`;
+  }
+  choices(label, options, selectedIndex) {
+    const selected = (value) => this.color ? paint(true, ANSI2.accentBackground, ` ${value} `) : `[ ${value} ]`;
+    const idle = (value) => this.tone(` ${value} `, "muted");
+    const rendered = options.map((option, index) => index === selectedIndex ? selected(option) : idle(option)).join(" ");
+    return `  ${this.rail("\u251C\u2500")} ${this.bold(label)}  ${rendered}`;
+  }
+  choice(label, yes) {
+    return this.choices(label, ["No", "Yes"], yes ? 1 : 0);
+  }
+  close(mark2, text, tone = "muted") {
+    return `  ${this.rail("\u2514\u2500")} ${this.tone(mark2, tone)} ${text}
+`;
+  }
+  open(url2, opened, firstRun = false) {
+    const label = opened ? "OPENED" : "LOCAL URL";
+    const mark2 = opened ? "\u2197" : "\u2192";
+    const urlRail = firstRun ? "\u251C\u2500" : "\u2514\u2500";
+    const next = firstRun ? `  ${this.rail("\u2514\u2500")} ${this.tone("NEXT", "muted")} ${this.bold("npx salidium")}
+` : "";
+    return `
+  ${this.tone("\u25C6", "accent")}  ${this.bold(label)}
+  ${this.rail(urlRail)} ${this.tone(mark2, "accent")} ${this.tone(url2, "accent")}
+${next}
+`;
+  }
+  running(explanations, detail) {
+    return [
+      this.section("Running"),
+      this.status("\u2713", "Salidium", "Background service is active", "ok"),
+      this.status(
+        "\u25CF",
+        "Explanations",
+        `${explanations} \xB7 ${detail}`,
+        explanations === "Local only" ? "ok" : "accent"
+      ),
+      this.item("\u2192", "Stop service: salidium stop", "muted"),
+      this.close("\u2192", "Stop model calls: salidium explanations off")
+    ].join("");
+  }
+};
+function supportsTerminalColor(isTty, environment2 = process.env) {
+  return isTty && !("NO_COLOR" in environment2) && environment2.TERM !== "dumb";
+}
+function homeRelative(path, userHome2) {
+  if (path === userHome2) return "~";
+  return path.startsWith(`${userHome2}/`) ? `~${path.slice(userHome2.length)}` : path;
+}
+function selectionKeyResult(key, selectedIndex, optionCount) {
+  const last = Math.max(0, optionCount - 1);
+  const selected = Math.max(0, Math.min(last, selectedIndex));
+  if (key === "") return { selectedIndex: selected, aborted: true };
+  if (key === "\r" || key === "\n") return { selectedIndex: selected, decision: selected };
+  if (key === "\x1B") return { selectedIndex: 0, decision: 0 };
+  if (key === "\x1B[D") return { selectedIndex: Math.max(0, selected - 1) };
+  if (key === "\x1B[C" || key === "	" || key === " ")
+    return { selectedIndex: Math.min(last, selected + 1) };
+  if (/^[1-9]$/.test(key)) {
+    const direct = Number(key) - 1;
+    if (direct <= last) return { selectedIndex: direct, decision: direct };
+  }
+  return { selectedIndex: selected };
+}
+function consentKeyResult(key, selected) {
+  if (key === "y" || key === "Y") return { selected: true, decision: true };
+  if (key === "n" || key === "N") return { selected: false, decision: false };
+  if (key === "	" || key === " ") return { selected: !selected };
+  const result = selectionKeyResult(key, selected ? 1 : 0, 2);
+  return {
+    selected: result.selectedIndex === 1,
+    ...result.decision === void 0 ? {} : { decision: result.decision === 1 },
+    ...result.aborted ? { aborted: true } : {}
+  };
+}
+
 // src/onboarding.ts
 function names(providers) {
   return providers.map((provider) => provider.name).join(", ");
 }
 async function runFirstRunOnboarding(context, io, options = {}) {
+  const ui = new TerminalUi(io.color);
   const integrations = options.integrations ?? providerIntegrations;
   const detected = integrations.filter((provider) => provider.detect(context).detected);
   const hookCapable = detected.filter((provider) => provider.liveHooksSupported(context));
@@ -26284,45 +26495,66 @@ async function runFirstRunOnboarding(context, io, options = {}) {
     const status = inspections.get(provider.id)?.status;
     return status === "not-configured" || status === "partial";
   });
-  const configured = hookCapable.filter(
-    (provider) => inspections.get(provider.id)?.status === "configured"
-  );
   const shouldDescribe = Boolean(options.firstRun || pending.length || invalid.length);
   if (shouldDescribe) {
-    io.write(
-      detected.length > 0 ? `Detected: ${names(detected)}.
-` : "Detected: no supported coding agents. Salidium will watch for Claude Code or Codex history when available.\n"
-    );
+    io.write(ui.header(Boolean(options.firstRun)));
+    io.write(ui.section("Agents"));
+    if (detected.length === 0) {
+      io.write(ui.item("\u25CB", "No supported coding agents detected", "muted"));
+      io.write(ui.close("\u2192", "Start Claude Code or Codex, then run Salidium again", "accent"));
+    } else {
+      for (const provider of detected) {
+        const inspection = inspections.get(provider.id);
+        const detail = inspection?.status === "configured" ? "Connected" : provider.liveHooksSupported(context) ? "Detected" : "History only";
+        io.write(
+          ui.status(
+            inspection?.status === "configured" ? "\u2713" : "\u25CF",
+            provider.name,
+            detail,
+            provider.id === "claude-code" ? "claude" : "codex"
+          )
+        );
+      }
+    }
     if (historyOnly.length > 0) {
+      io.write(ui.spacer());
       io.write(
-        `History-only on native Windows: ${names(historyOnly)} transcripts are imported, but POSIX live hooks are not installed.
-`
+        ui.attention(
+          `Native Windows imports ${names(historyOnly)} history; live POSIX hooks are unavailable`
+        )
       );
     }
-    if (configured.length > 0) io.write(`Already connected: ${names(configured)}.
-`);
     for (const provider of invalid) {
       const inspection = inspections.get(provider.id);
+      io.write(ui.spacer());
       io.write(
-        `Needs attention: ${provider.name} configuration was not changed because ${inspection?.issue ?? "it could not be read safely"}.
-`
+        ui.attention(
+          `${provider.name} was not changed: ${inspection?.issue ?? "its settings could not be read safely"}`
+        )
       );
     }
   }
   let consent = "not-needed";
+  let explainerCadence;
   const changed = [];
   const guidance = [];
   if (pending.length > 0) {
-    io.write("Permission requested: add Salidium hooks while preserving existing settings in:\n");
-    for (const provider of pending) {
-      io.write(`  ${provider.name}: ${inspections.get(provider.id)?.settingsPath}
-`);
-    }
+    io.write(ui.section("Permission"));
+    io.write(ui.copy("Salidium will add its hooks. Existing settings stay intact."));
+    io.write(ui.spacer());
+    for (const [index, provider] of pending.entries()) {
+      const settingsPath3 = inspections.get(provider.id)?.settingsPath;
+      if (settingsPath3)
+        io.write(ui.path(provider.name, provider.id, homeRelative(settingsPath3, context.userHome)));
+      if (index < pending.length - 1) io.write(ui.spacer());
+    }
+    io.write(ui.spacer());
     let approved = Boolean(options.assumeYes);
     if (options.assumeYes) {
       consent = "approved";
     } else if (io.interactive) {
-      approved = await io.confirm(`Connect ${names(pending)}? [y/N] `);
+      const question = pending.length === 1 ? `Connect ${pending[0]?.name}?` : "Connect both agents?";
+      approved = await io.confirm(question);
       consent = approved ? "approved" : "declined";
     } else {
       consent = "non-interactive";
@@ -26333,36 +26565,80 @@ async function runFirstRunOnboarding(context, io, options = {}) {
           const result = provider.install(context);
           changed.push(result);
           io.write(
-            result.changed ? `Connected: ${provider.name}.
-` : `Connected: ${provider.name} (no changes needed).
-`
+            ui.status("\u2713", provider.name, result.changed ? "Connected" : "Already connected", "ok")
           );
           guidance.push(...provider.guidance(result));
         } catch (error51) {
           io.write(
-            `Needs attention: ${provider.name} could not be connected: ${error51 instanceof Error ? error51.message : String(error51)}.
-`
+            ui.failure(
+              `${provider.name} could not be connected: ${error51 instanceof Error ? error51.message : String(error51)}`
+            )
           );
         }
       }
     } else if (consent === "non-interactive") {
       io.write(
-        "No provider settings changed because this terminal is non-interactive. Re-run with --yes to approve setup, or use salidium install-hooks later.\n"
+        ui.close(
+          "\u25CB",
+          "No changes made. Re-run with --yes, or use salidium install-hooks later.",
+          "muted"
+        )
       );
     } else {
-      io.write("No provider settings changed. Use salidium install-hooks when you are ready.\n");
+      io.write(ui.close("\u25CB", "No changes made. Use salidium install-hooks when ready.", "muted"));
+    }
+  }
+  if (options.firstRun) {
+    io.write(ui.section("Explanations"));
+    io.write(ui.copy("Reports, evidence, and quantities stay local."));
+    io.write(ui.copy("Only the written Why and How can call a model."));
+    io.write(ui.spacer());
+    let selectedIndex = 0;
+    if (io.interactive && !options.assumeYes) {
+      selectedIndex = await io.select(
+        "Written Why + How",
+        EXPLANATION_MODES.map((mode2) => mode2.label),
+        0
+      );
     }
+    explainerCadence = EXPLANATION_MODES[selectedIndex]?.value ?? "off";
+    const mode = explanationMode(explainerCadence);
+    io.write(
+      ui.close(
+        explainerCadence === "off" ? "\u2713" : "\u25CF",
+        `${mode.label} \xB7 ${mode.detail}`,
+        explainerCadence === "off" ? "ok" : "accent"
+      )
+    );
   }
   const validations = detected.flatMap((provider) => provider.validate(context));
   const attention = validations.filter((validation) => validation.level === "attention");
   if (shouldDescribe || changed.length > 0) {
-    if (attention.length === 0) io.write("Setup checks passed.\n");
-    else for (const validation of attention) io.write(`Needs attention: ${validation.message}.
-`);
+    const ready = [];
+    if (detected.length === 0) {
+      ready.push({ mark: "\u25CB", text: "Waiting for Claude Code or Codex", tone: "muted" });
+    } else if (attention.length === 0) {
+      ready.push({ mark: "\u2713", text: "Setup checks passed", tone: "ok" });
+    } else {
+      for (const validation of attention)
+        ready.push({ mark: "!", text: validation.message, tone: "warn" });
+    }
+    for (const instruction of guidance)
+      ready.push({ mark: "!", text: `Codex: ${instruction}`, tone: "warn" });
+    io.write(ui.section("Ready"));
+    for (const row of ready.slice(0, -1)) io.write(ui.item(row.mark, row.text, row.tone));
+    const last = ready.at(-1);
+    if (last) io.write(ui.close(last.mark, last.text, last.tone));
   }
-  for (const instruction of guidance) io.write(`Codex requires one more action: ${instruction}
-`);
-  return { detected, changed, guidance, validations, consent };
+  return {
+    detected,
+    changed,
+    guidance,
+    validations,
+    consent,
+    ...explainerCadence ? { explainerCadence } : {},
+    presented: shouldDescribe || changed.length > 0
+  };
 }
 
 // src/render.ts
@@ -26555,6 +26831,9 @@ Usage:
   salidium stop                 Stop the background daemon
   salidium restart              Stop it, start it again, and open the UI (--no-open to skip)
   salidium status               Show daemon status
+  salidium explanations         Show whether written explanations can call a model
+  salidium explanations off|when-done|each-reply
+                                Change model-call frequency without stopping local reports
   salidium open                 Open the UI in your browser
   salidium show [session]       Print the report for a session as text (default: most recent)
                                 --detail=summary|detail|source, --width=N
@@ -26631,35 +26910,70 @@ async function main(argv) {
     }
     case "start": {
       const running = await ensureDaemon();
+      const explanations = await currentExplanationState(running, "reachable");
       process.stdout.write(
         `daemon running on http://127.0.0.1:${running.port} (pid ${running.pid})
+Explanations: ${explanationStateLabel(explanations)}
 `
       );
       return 0;
     }
     case "up": {
       const context = { userHome, salidiumHome };
-      await runFirstRunOnboarding(
+      const color = supportsTerminalColor(Boolean(process.stdout.isTTY));
+      const firstRun = !existsSync9(daemonPaths(salidiumHome).db);
+      const onboarding = await runFirstRunOnboarding(
         context,
         {
           interactive: Boolean(process.stdin.isTTY && process.stdout.isTTY),
-          confirm: confirmSetup,
+          color,
+          confirm: (question) => confirmSetup(question, color),
+          select: (question, options, selectedIndex) => selectTerminalOption(question, options, selectedIndex, color),
           write: (text) => process.stdout.write(text)
         },
         {
           assumeYes,
-          firstRun: !existsSync9(daemonPaths(salidiumHome).db)
+          firstRun
         }
       );
-      for (const validation of essentialValidations()) {
-        if (validation.level === "attention")
+      if (onboarding.explainerCadence) {
+        writeSettings(salidiumHome, {
+          ...readSettings(salidiumHome),
+          explainerCadence: onboarding.explainerCadence
+        });
+      }
+      const systemAttention = essentialValidations().filter(
+        (validation) => validation.level === "attention"
+      );
+      if (systemAttention.length > 0 && onboarding.presented) {
+        const ui2 = new TerminalUi(color);
+        process.stdout.write(ui2.section("System"));
+        for (const validation of systemAttention.slice(0, -1))
+          process.stdout.write(ui2.item("!", validation.message, "warn"));
+        const last = systemAttention.at(-1);
+        if (last) process.stdout.write(ui2.close("!", last.message, "warn"));
+      } else {
+        for (const validation of systemAttention)
           process.stdout.write(`Needs attention: ${validation.message}.
 `);
       }
       const running = await ensureDaemon();
       if (!noOpen && process.stdout.isTTY) openBrowser(uiUrl(running));
-      process.stdout.write(`${uiUrl(running)}
+      const url2 = uiUrl(running);
+      const ui = new TerminalUi(color);
+      const state = await currentExplanationState(running, "reachable");
+      if (onboarding.presented) {
+        process.stdout.write(
+          ui.open(url2, !noOpen && Boolean(process.stdout.isTTY), Boolean(firstRun))
+        );
+      } else if (process.stdout.isTTY) {
+        const mode = explanationMode(state.effective);
+        process.stdout.write(ui.running(mode.label, mode.detail));
+        process.stdout.write(ui.open(url2, !noOpen));
+      } else {
+        process.stdout.write(`${url2}
 `);
+      }
       return 0;
     }
     case "open": {
@@ -26729,6 +27043,13 @@ async function main(argv) {
 ` : `daemon (pid ${stopped.pid}) was asked to stop and is still running
 `
       );
+      const storedMode = readSettings(salidiumHome).explainerCadence;
+      if (storedMode !== "off") {
+        process.stdout.write(
+          `Explanations remain set to ${explanationMode(storedMode).label} for the next start. Disable them with: salidium explanations off
+`
+        );
+      }
       return stopped === void 0 || stopped.signaled && stopped.exited ? 0 : 1;
     }
     /*
@@ -26761,9 +27082,13 @@ async function main(argv) {
 `);
       const running = await ensureDaemon();
       if (!noOpen) openBrowser(uiUrl(running));
-      process.stdout.write(`daemon running (pid ${running.pid})
+      const explanations = await currentExplanationState(running, "reachable");
+      process.stdout.write(
+        `daemon running (pid ${running.pid})
+Explanations: ${explanationStateLabel(explanations)}
 ${uiUrl(running)}
-`);
+`
+      );
       return 0;
     }
     case "status": {
@@ -26773,6 +27098,9 @@ ${uiUrl(running)}
         d && presence !== "absent" ? `running: pid ${d.pid}, port ${d.port}, since ${d.startedAt}${presence === "unresponsive" ? "; not answering" : ""}
 ` : "not running\n"
       );
+      const explanations = await currentExplanationState(d, presence);
+      process.stdout.write(`Explanations: ${explanationStateLabel(explanations)}
+`);
       const context = { userHome, salidiumHome };
       for (const provider of providerIntegrations) {
         const detection = provider.detect(context);
@@ -26782,6 +27110,75 @@ ${uiUrl(running)}
       }
       return presence === "reachable" ? 0 : 1;
     }
+    case "explanations": {
+      const d = readDaemonJson(salidiumHome);
+      const presence = await presenceOf(d);
+      if (!arg) {
+        const state2 = await currentExplanationState(d, presence);
+        const mode = explanationMode(state2.effective);
+        process.stdout.write(
+          `Explanations: ${explanationStateLabel(state2)}
+${mode.detail}. Reports, evidence, and quantities stay local.
+Change with: salidium explanations off|when-done|each-reply
+`
+        );
+        return 0;
+      }
+      const cadence = parseExplanationMode(arg);
+      if (!cadence) {
+        process.stderr.write(
+          "Choose off, when-done, or each-reply. Example: salidium explanations off\n"
+        );
+        return 2;
+      }
+      if (presence === "unresponsive") {
+        process.stderr.write(
+          `daemon pid ${d?.pid ?? "unknown"} is running but did not answer; the setting was not changed
+`
+        );
+        return 1;
+      }
+      let state;
+      if (d && presence === "reachable") {
+        try {
+          const response = await fetch(`http://127.0.0.1:${d.port}/api/settings/explainer`, {
+            method: "PUT",
+            headers: {
+              Authorization: `Bearer ${d.token}`,
+              "Content-Type": "application/json"
+            },
+            body: JSON.stringify({ cadence }),
+            signal: AbortSignal.timeout(2e3)
+          });
+          if (!response.ok) {
+            process.stderr.write(`daemon refused the explanation setting (${response.status})
+`);
+            return 1;
+          }
+          const settings = ExplainerSettingsSchema.parse(await response.json());
+          state = explanationStateFromApi(settings);
+        } catch {
+          process.stderr.write(
+            "daemon stopped answering; the explanation setting was not changed\n"
+          );
+          return 1;
+        }
+      } else {
+        writeSettings(salidiumHome, {
+          ...readSettings(salidiumHome),
+          explainerCadence: cadence
+        });
+        state = localExplanationState();
+      }
+      const chosen = explanationMode(cadence);
+      process.stdout.write(`Saved: ${chosen.label} \xB7 ${chosen.detail}
+`);
+      if (state.effective !== cadence)
+        process.stdout.write(
+          "Local only is active because the daemon environment prevents model calls.\n"
+        );
+      return 0;
+    }
     case "install-hooks":
     case "uninstall-hooks": {
       const remove = cmd === "uninstall-hooks";
@@ -27096,6 +27493,36 @@ function formatBytes(bytes) {
 function uiUrl(d) {
   return `http://127.0.0.1:${d.port}/#token=${d.token}`;
 }
+function explanationStateFromApi(settings) {
+  return {
+    stored: settings.cadence,
+    effective: settings.envOff ? "off" : settings.cadence,
+    envOff: settings.envOff
+  };
+}
+function localExplanationState() {
+  const stored = readSettings(salidiumHome).explainerCadence;
+  const effective = effectiveCadence(stored);
+  return { stored, effective, envOff: effective !== stored };
+}
+async function currentExplanationState(daemon, presence) {
+  if (daemon && presence === "reachable") {
+    try {
+      const response = await fetch(`http://127.0.0.1:${daemon.port}/api/settings/explainer`, {
+        headers: { Authorization: `Bearer ${daemon.token}` },
+        signal: AbortSignal.timeout(2e3)
+      });
+      if (response.ok)
+        return explanationStateFromApi(ExplainerSettingsSchema.parse(await response.json()));
+    } catch {
+    }
+  }
+  return localExplanationState();
+}
+function explanationStateLabel(state) {
+  const mode = explanationMode(state.effective);
+  return `${mode.label}${state.envOff && state.stored !== "off" ? " (forced by environment)" : ""} \xB7 ${mode.detail}`;
+}
 async function alive(d) {
   try {
     const res = await fetch(`http://127.0.0.1:${d.port}/api/info`, {
@@ -27263,14 +27690,94 @@ function openBrowser(url2) {
   } catch {
   }
 }
-async function confirmSetup(question) {
-  const prompt = createInterface({ input: process.stdin, output: process.stdout });
-  try {
-    const answer = await prompt.question(question);
-    return /^(y|yes)$/i.test(answer.trim());
-  } finally {
-    prompt.close();
+async function confirmSetup(question, color) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) {
+    const prompt = createInterface({ input: process.stdin, output: process.stdout });
+    try {
+      const answer = await prompt.question(`${question} [y/N] `);
+      return /^(y|yes)$/i.test(answer.trim());
+    } finally {
+      prompt.close();
+    }
   }
+  const ui = new TerminalUi(color);
+  const input = process.stdin;
+  const output = process.stdout;
+  const wasRaw = Boolean(input.isRaw);
+  let selected = false;
+  const render = () => output.write(`\x1B[?25l\r\x1B[2K${ui.choice(question, selected)}`);
+  return new Promise((resolve2, reject) => {
+    const finish = (decision) => {
+      input.off("data", onData);
+      input.setRawMode(wasRaw);
+      if (!wasRaw) input.pause();
+      render();
+      output.write("\x1B[?25h\n");
+      resolve2(decision);
+    };
+    const onData = (data) => {
+      const result = consentKeyResult(String(data), selected);
+      selected = result.selected;
+      if (result.aborted) {
+        input.off("data", onData);
+        input.setRawMode(wasRaw);
+        if (!wasRaw) input.pause();
+        output.write("\x1B[?25h\n");
+        reject(new Error("Aborted with Ctrl+C"));
+        return;
+      }
+      if (result.decision !== void 0) {
+        finish(result.decision);
+        return;
+      }
+      render();
+    };
+    input.setRawMode(true);
+    input.resume();
+    input.on("data", onData);
+    render();
+  });
+}
+async function selectTerminalOption(question, options, initialIndex, color) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return initialIndex;
+  const ui = new TerminalUi(color);
+  const input = process.stdin;
+  const output = process.stdout;
+  const wasRaw = Boolean(input.isRaw);
+  let selectedIndex = initialIndex;
+  const render = () => output.write(`\x1B[?25l\r\x1B[2K${ui.choices(question, options, selectedIndex)}`);
+  return new Promise((resolve2, reject) => {
+    const finish = (decision) => {
+      input.off("data", onData);
+      input.setRawMode(wasRaw);
+      if (!wasRaw) input.pause();
+      selectedIndex = decision;
+      render();
+      output.write("\x1B[?25h\n");
+      resolve2(decision);
+    };
+    const onData = (data) => {
+      const result = selectionKeyResult(String(data), selectedIndex, options.length);
+      selectedIndex = result.selectedIndex;
+      if (result.aborted) {
+        input.off("data", onData);
+        input.setRawMode(wasRaw);
+        if (!wasRaw) input.pause();
+        output.write("\x1B[?25h\n");
+        reject(new Error("Aborted with Ctrl+C"));
+        return;
+      }
+      if (result.decision !== void 0) {
+        finish(result.decision);
+        return;
+      }
+      render();
+    };
+    input.setRawMode(true);
+    input.resume();
+    input.on("data", onData);
+    render();
+  });
 }
 function essentialValidations() {
   const validations = [];
@@ -27333,6 +27840,7 @@ async function doctor() {
     lines.push("settings file is invalid; optional explanations are safely off until it is fixed");
     problems++;
   }
+  lines.push(`explanations ${explanationStateLabel(localExplanationState())}`);
   const context = { userHome, salidiumHome };
   for (const provider of providerIntegrations) {
     const detection = provider.detect(context);