@vincemakes/kiso-code 0.30.0 → 0.31.1

package/dist/index.js

@@ -24,6 +24,7 @@
  * makeAgent, and main.
  */
 import { appendFileSync, mkdirSync, readFileSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { spawn, spawnSync } from "node:child_process";
 import { newSessionId } from "./session-id.js";
 import { createInterface } from "node:readline";
 import { Readable } from "node:stream";
@@ -39,9 +40,10 @@ import { agentModel, atFiles, body, bodyLog, kisoHome, builtInExtensions, curren
 import { askUi, resolveProjectTrust } from "./trust-ui.js";
 import { isFirstRun, scaffoldFirstRun } from "./first-run.js";
 import { fauxSkip, readFauxScript } from "./faux-glue.js";
-import { chat, contextWindowTokens, displayCtxRatio } from "./chat.js";
+import { chat, contextWindowTokens, displayCtxRatio, statusModelLabel } from "./chat.js";
 import { loadProjectConfig, loadUserConfig, mergeConfigs, resolveAutoCompact, resolveContextWindow, resolveModel } from "./config.js";
-import { checkForUpdate } from "./update-check.js";
+import { oauthTokenThunk } from "./auth/token.js";
+import { checkForUpdate, knownUpdate, updateCardLines } from "./update-check.js";
 import { resume } from "./resume.js";
 import { resumeTail } from "./resume-tail.js";
 import { armByteTrace } from "./byte-trace.js";
@@ -61,6 +63,29 @@ export { applyProjectMerges } from "./trust-ui.js";
  *  exits, so the turn runs to its terminal and nothing else is read.
  *  Built on an EMPTY readline so every other member keeps the pipe
  *  path's exact semantics (auto-denied asks, no chips, no pops). */
+/** OR-4: hand a URL to the platform's opener, detached, and never let a
+ *  missing or failing opener touch the sign-in — the printed URL is the
+ *  path that always works. macOS `open`, Linux `xdg-open`; elsewhere the
+ *  URL stays printed (Windows is unsupported by the CLI as a whole). */
+function openInBrowser(url) {
+    const opener = process.platform === "darwin" ? "open" : process.platform === "linux" ? "xdg-open" : null;
+    if (opener === null)
+        return;
+    try {
+        spawn(opener, [url], { detached: true, stdio: "ignore" }).unref();
+    }
+    catch {
+        // the URL is on screen; opening it is the person's fallback
+    }
+}
+/** OR-3: the commands that own their own stdin reader (a hidden key prompt,
+ *  an OAuth paste prompt) or read nothing at all — never the editor.
+ *  OR-9 adds `update`: npm inherits the terminal for the install's own
+ *  progress and prompts, so no editor may hold stdin while it runs. */
+const CREDENTIAL_COMMANDS = new Set(["login", "logout", "auth", "update"]);
+/** OR-9: the one install command the README gives, which `kiso update`
+ *  runs and the failure message names. */
+const INSTALL_COMMAND = ["npm", "i", "-g", "@vincemakes/kiso-code@latest"];
 function taskFileInput(content) {
     const base = readlineInput(createInterface({ input: Readable.from([]), output: process.stdout }));
     return {
@@ -383,28 +408,42 @@ function bannerExtensionText() {
  *  resize; the resume list re-gates with the tier); off-TTY: the
  *  historical `[N extensions: ...]` standalone line (zero change). */
 /**
- * The update line, when there is one, appended after the opening.
+ * The update card, when there is one, appended after the opening.
  *
- * It never blocks: the caller does not await it, and the banner is
- * already drawn when this starts. If the check fails, times out, is
- * switched off, or finds nothing newer, this does nothing at all and
- * says nothing about having tried.
+ * Two painters, one card. The boot paints what the CACHE already knows,
+ * synchronously, so a known newer version is under the banner on the
+ * first frame; the check then runs fired-and-forgotten (at most one
+ * request a day) and paints only a version the boot did not. If the check
+ * fails, times out, is switched off, or finds nothing newer, it does
+ * nothing at all and says nothing about having tried.
  */
+/** OR-9: the version this process has already carded — the boot's cache
+ *  paint and the async check's answer never both card one version. */
+let updateShown = null;
+const updateDeps = () => ({ kisoHome: kisoHome(), version: VERSION, isTTY: process.stdout.isTTY === true, faux: currentFaux });
+/** OR-9 (owner, 2026-09-09): the update is a CARD under the banner — a
+ *  rule, a bold title, the version with the command that installs it, the
+ *  changelog, a rule — the shape the reference shows at every start. The
+ *  RAW channel (not `notice`, which strips SGR through escapeTerminal); a
+ *  raw cell lands at the transcript's end, never spliced mid-frame. A
+ *  declared exception to R2 law 1.1 (a notice wears no edge): a card is
+ *  not a notice, and the owner asked for the edges. */
+function paintUpdateCard(latest) {
+    if (latest === updateShown)
+        return;
+    updateShown = latest;
+    const p = palette();
+    const width = Math.min(process.stdout.columns ?? 80, 80);
+    const rule = `${p.dim}${"─".repeat(width)}${p.reset}`;
+    const [title, line, changelog] = updateCardLines(latest);
+    bodyLog(`${rule}\n${p.bold}${title}${p.reset}\n${line}\n${changelog}\n${rule}`, "words");
+}
 async function announceUpdate() {
     try {
-        const line = await checkForUpdate({ kisoHome: kisoHome(), version: VERSION, isTTY: process.stdout.isTTY === true, faux: currentFaux });
-        if (line === null)
+        const latest = await checkForUpdate(updateDeps());
+        if (latest === null)
             return;
-        // THE RAW CHANNEL, not `notice`. A notice renders through ErrorLine,
-        // which calls `escapeTerminal` — so every SGR in it is stripped and
-        // the line could only ever be full-strength prose. The raw channel
-        // is the one the banner itself uses: the styling is applied HERE, at
-        // composition, and the fold keeps the span intact (#16b).
-        //
-        // A turn may have started while the request was in flight. A raw
-        // cell is a cell like any other, so it lands at the transcript's
-        // end — never spliced into a frame the reader is mid-way through.
-        bodyLog(`${palette().dim}${line}${palette().reset}`, "words");
+        paintUpdateCard(latest);
     }
     catch {
         // belt and braces: checkForUpdate does not throw, and if it ever
@@ -607,7 +646,7 @@ async function makeAgent(sessionId, input, modelFlag) {
         setCurrentFaux(false);
         setCurrentModelName(resolved.name);
     }
-    setAgentModel(model); // v2b: the status bar shows it
+    setAgentModel(model, resolved?.profile.baseUrl); // v2b: the status bar shows it; OR-1: the endpoint rides along
     // W21: the extensions array is built ONCE per agent and shared with
     // the runtime by reference — the don't-ask-again writer pushes the
     // generated extension into it so a first-time rule joins the chain
@@ -647,13 +686,24 @@ async function makeAgent(sessionId, input, modelFlag) {
         // field survives for the callers that want a bound (subagents, the
         // SDK, `kiso run`); the interactive front door does not set one.
         // Modes: the five tiers join at the CHAIN HEAD, before the user/
-        // project extensions (the deny>ask>allow composition keeps a user
+        // project extensions (the deny>allow>ask composition keeps a user
         // deny winning over any mode tier — bypass included).
         extensions,
         ...(resolved !== null
             ? {
                 provider: resolved.profile.kind,
-                apiKey: resolved.apiKey,
+                // OR-1: exactly one sign-in shape reaches the adapter. An
+                // OAuth profile has no key to pass — it passes the thunk
+                // the adapter re-resolves per request instead.
+                ...(resolved.oauthProviderId !== undefined
+                    ? { oauth: oauthTokenThunk(resolved.oauthProviderId) }
+                    : { apiKey: resolved.apiKey ?? "none" }),
+                // OR-1: the ChatGPT backend's cache lane is the SESSION —
+                // one conversation's requests share a key, different
+                // conversations never do. The one entry point that hands
+                // no session id is `kiso sessions`, a read-only listing
+                // that streams nothing, so its absence costs no cache.
+                ...(sessionId !== undefined ? { promptCacheKey: sessionId } : {}),
                 ...(resolved.profile.baseUrl !== undefined ? { baseUrl: resolved.profile.baseUrl } : {}),
                 ...(resolved.profile.promptCaching !== undefined ? { promptCaching: resolved.profile.promptCaching } : {}),
             }
@@ -730,7 +780,7 @@ async function pickSession(agent, input) {
 function paintBootStatus(session) {
     if (!dock.active)
         return;
-    dock.setStatus(idleStatus(getMode() === "plan" ? "plan (read-only)" : getMode(), agentModel, displayCtxRatio(session)));
+    dock.setStatus(idleStatus(getMode() === "plan" ? "plan (read-only)" : getMode(), statusModelLabel(session), displayCtxRatio(session)));
 }
 /** PH-1a (finding PH-F12): a usage error raised from inside the TUI —
  *  main's finally still runs (dock teardown, agent close, temp cleanup)
@@ -766,11 +816,16 @@ async function chatLoop(agent, firstId, input, autoCompact) {
             // throws on profile drift — so one drifted session anywhere in the
             // history stopped kiso from starting at all.
             extensionsBanner();
-            // The one line the opening may gain (§7.10's ruling): "there is
-            // a newer kiso". FIRED AND FORGOTTEN — the banner above is
-            // already on screen and this never delays it. When the answer
-            // arrives it rides `body.notice`, the commit path notices
-            // already use, rather than a second channel into the frame.
+            // OR-9 (owner, 2026-09-09): the update card under the banner, at
+            // EVERY start while a newer version is known — §7.10's once-only
+            // line is superseded. What the cache knows is painted NOW, with
+            // no request, so the card is part of the opening rather than a
+            // late arrival; the check itself stays FIRED AND FORGOTTEN — the
+            // banner is already on screen and it never delays it — and it
+            // paints only a version the boot did not know.
+            const known = knownUpdate(updateDeps());
+            if (known !== null)
+                paintUpdateCard(known);
             void announceUpdate();
         }
         else {
@@ -789,7 +844,7 @@ async function chatLoop(agent, firstId, input, autoCompact) {
         // XP-1 §2.1: the switched-to session's OWN truth repaints the row —
         // the global display state never outlives the session it described
         // (pre-XP the row kept the previous session's /model selection).
-        setAgentModel(session.model);
+        setAgentModel(session.model, session.baseUrl);
         setCurrentModelName(session.model);
         paintBootStatus(session);
         const nav = {
@@ -803,6 +858,56 @@ async function chatLoop(agent, firstId, input, autoCompact) {
         id = end.id;
     }
 }
+/** A secret from the terminal: hidden input on a TTY, the whole of stdin
+ *  otherwise (a pipe, a heredoc) — never an argument, which shell history
+ *  would keep. */
+async function readSecret(prompt) {
+    if (process.stdin.isTTY !== true) {
+        return await new Promise((resolve) => {
+            let buf = "";
+            process.stdin.setEncoding("utf8");
+            process.stdin.on("data", (d) => {
+                buf += d;
+            });
+            process.stdin.on("end", () => resolve(buf.split("\n")[0] ?? ""));
+            process.stdin.resume();
+        });
+    }
+    return await new Promise((resolve) => {
+        let buf = "";
+        // OR-3: raw mode BEFORE the prompt — the hidden prompt must be hidden
+        // before it is shown. Written the other way round, a key that arrives
+        // between the prompt and setRawMode is echoed by the tty line
+        // discipline (the auth-tty gate caught it: a driver that types the
+        // instant the prompt appears saw the key on screen two runs in three).
+        process.stdin.setRawMode(true);
+        process.stdout.write(prompt);
+        process.stdin.resume();
+        process.stdin.setEncoding("utf8");
+        const onData = (chunk) => {
+            for (const ch of chunk) {
+                if (ch === "\r" || ch === "\n") {
+                    process.stdin.setRawMode(false);
+                    process.stdin.pause();
+                    process.stdin.off("data", onData);
+                    process.stdout.write("\n");
+                    resolve(buf);
+                    return;
+                }
+                if (ch === "\u0003") {
+                    process.stdin.setRawMode(false);
+                    process.stdout.write("\n");
+                    process.exit(130);
+                }
+                if (ch === "\u007f" || ch === "\b")
+                    buf = buf.slice(0, -1);
+                else
+                    buf += ch;
+            }
+        };
+        process.stdin.on("data", onData);
+    });
+}
 async function main() {
     // E group (the graceful-exit gate ③, R-G 0.1.48): a terminal closing
     // turns the in-flight stdout/stderr writes into EIO, and node's
@@ -918,7 +1023,20 @@ async function main() {
     // (entered here, dock-bound, trusted before any extension loads),
     // readline elsewhere. The trust question, chat, and resume all read
     // through it; main's finally closes it on every exit path.
-    const input = taskFile !== undefined ? taskFileInput(taskFile) : makeLineInput();
+    // OR-3 (owner, 2026-09-09): the credential commands never read the shared
+    // line input, and on a TTY makeLineInput() enters the raw-mode editor and
+    // sends the ground probe (CSI ?996n + OSC 11) BEFORE the command switch.
+    // `kiso login chatgpt` then had two readers on stdin: the editor swallowed
+    // the keystrokes, the terminal's OSC reply was typed into the login's own
+    // readline, the "open this URL" line vanished under the dock's repaint,
+    // and the sign-in never completed. These commands get an input over an
+    // EMPTY readable instead — no editor, no probe, stdin untouched — so the
+    // hidden key prompt and the OAuth paste prompt are the only readers.
+    const input = taskFile !== undefined
+        ? taskFileInput(taskFile)
+        : CREDENTIAL_COMMANDS.has(command ?? "")
+            ? readlineInput(createInterface({ input: Readable.from([]), output: process.stdout }))
+            : makeLineInput();
     // R3a — cross-session input history: ~/.kiso/history, one line per
     // entry, appended on submit, tail-500 at load (truncated by REWRITE
     // at startup so the file never grows unbounded). Unreadable file =
@@ -1095,6 +1213,91 @@ async function main() {
                 }
                 break;
             }
+            case "login":
+            case "logout":
+            case "auth": {
+                // the sign-in plan (2026-09-08), step 1: the credential store.
+                // `login <provider>` reads the key from a hidden prompt on a TTY
+                // or from stdin otherwise (never from an argument — shell history);
+                // `logout <provider>` deletes; `auth` lists, keys masked.
+                const { KNOWN_PROVIDERS, OAUTH_PROVIDERS, authPath, deleteCredential, maskSecret, readAuthFile, setCredential } = await import("./auth/credentials.js");
+                const provider = arg;
+                if (command === "auth") {
+                    const file = readAuthFile();
+                    const rows = Object.entries(file.credentials);
+                    const lines = [`credentials: ${authPath()}${rows.length === 0 ? " (none stored)" : ""}`];
+                    for (const [id, cred] of rows) {
+                        if (cred.type === "api-key")
+                            lines.push(`  ${id.padEnd(10)} api-key ${maskSecret(cred.key)}  saved ${new Date(cred.savedAt).toISOString().slice(0, 10)}`);
+                        else
+                            lines.push(`  ${id.padEnd(10)} oauth   ${cred.accountId ?? ""}  expires ${new Date(cred.expires).toISOString()}${cred.expires < Date.now() ? " (expired)" : ""}`);
+                    }
+                    const envs = ["ANTHROPIC_API_KEY", "OPENAI_API_KEY"].filter((k) => process.env[k] !== undefined);
+                    lines.push(`env vars set: ${envs.length ? envs.join(", ") : "none"} (a stored credential owns its provider; env applies only when nothing is stored)`);
+                    process.stdout.write(`${lines.join("\n")}\n`);
+                    break;
+                }
+                if (provider === undefined || !KNOWN_PROVIDERS.includes(provider)) {
+                    throw new CliUsageError(`kiso ${command} <provider> — one of: ${KNOWN_PROVIDERS.join(", ")}`);
+                }
+                if (command === "logout") {
+                    const had = deleteCredential(provider);
+                    process.stdout.write(had ? `signed out of ${provider}\n` : `nothing stored for ${provider}\n`);
+                    break;
+                }
+                if (OAUTH_PROVIDERS.includes(provider)) {
+                    // the subscription sign-in (plan step 2): the browser flow with a
+                    // paste path; the callback host/port can be moved by env for tests
+                    const { chatgptFlow } = await import("./auth/oauth/chatgpt.js");
+                    const { createInterface } = await import("node:readline");
+                    const rl = createInterface({ input: process.stdin, output: process.stdout });
+                    const cbPort = process.env.KISO_OAUTH_CALLBACK_PORT !== undefined ? Number(process.env.KISO_OAUTH_CALLBACK_PORT) : undefined;
+                    try {
+                        const cred = await chatgptFlow.login({
+                            notify: (line) => process.stdout.write(`${line}\n`),
+                            prompt: (q) => new Promise((resolve) => rl.question(q, resolve)),
+                            // OR-4: a person at a terminal gets the browser opened for
+                            // them; a pipe, a test rig or KISO_NO_BROWSER=1 gets the URL only.
+                            ...(process.stdout.isTTY === true && process.env.KISO_NO_BROWSER === undefined ? { open: openInBrowser } : {}),
+                            ...(cbPort !== undefined ? { callback: { host: process.env.KISO_OAUTH_CALLBACK_HOST ?? "127.0.0.1", port: cbPort } } : {}),
+                            ...(process.env.KISO_OAUTH_TOKEN_URL !== undefined ? { tokenUrl: process.env.KISO_OAUTH_TOKEN_URL } : {}),
+                        });
+                        setCredential(provider, cred);
+                        process.stdout.write(`signed in to ${provider} (${chatgptFlow.label}) — account ${cred.accountId ?? "?"}, expires ${new Date(cred.expires).toISOString()} — stored in ${authPath()}\n`);
+                    }
+                    finally {
+                        rl.close();
+                    }
+                    break;
+                }
+                const key = (await readSecret(`API key for ${provider}: `)).trim();
+                if (key === "")
+                    throw new CliUsageError(`kiso login ${provider}: no key given`);
+                setCredential(provider, { type: "api-key", key, savedAt: Date.now() });
+                process.stdout.write(`signed in to ${provider} with an API key (${maskSecret(key)}) — stored in ${authPath()}\n`);
+                break;
+            }
+            case "update": {
+                // OR-9: the command the update card names. A thin hand-off to
+                // the ONE install command the README gives — npm resolved from
+                // PATH, its stdio inherited so its progress, its prompts and
+                // its own errors are what the person sees, its exit code the
+                // outcome. kiso adds nothing to what npm knows: no version
+                // pinning, no registry, no elevation. A failure (a global
+                // prefix this user cannot write, a network that is down) is
+                // npm's to explain; the message names the manual command so
+                // the person can run it with whatever their setup needs.
+                const [bin, ...installArgs] = INSTALL_COMMAND;
+                const r = spawnSync(bin, installArgs, { stdio: "inherit" });
+                if (r.error !== undefined || r.status !== 0) {
+                    const why = r.error !== undefined ? `could not run npm (${r.error.message})` : `npm exited ${r.status ?? "on a signal"}`;
+                    process.stderr.write(`kiso update: ${why} — run it yourself: ${INSTALL_COMMAND.join(" ")}\n`);
+                    process.exitCode = r.status ?? 1;
+                    break;
+                }
+                process.stdout.write("kiso updated — the next `kiso` runs the new version\n");
+                break;
+            }
             case "help": {
                 // PH-1b (finding PH-F21): the CLI must be able to describe its
                 // own configuration — the old help listed five commands and
@@ -1108,6 +1311,11 @@ async function main() {
                     "  kiso resume              pick a session to continue (TTY picker)\n" +
                     "  kiso resume <id> [prompt]   continue a session (one-shot)\n" +
                     "  kiso sessions           list durable sessions\n" +
+                    "  kiso login <provider>    anthropic|openai|deepseek|zai: store an API key (hidden prompt, or stdin when piped);\n" +
+                    "                           chatgpt: sign in with a ChatGPT subscription (browser; unofficial third-party flow)\n" +
+                    "  kiso logout <provider>   remove the stored credential\n" +
+                    "  kiso auth               list stored credentials (keys masked)\n" +
+                    "  kiso update             install the latest release (npm i -g @vincemakes/kiso-code@latest)\n" +
                     "  kiso help               this help\n\n" +
                     "flags (any position):\n" +
                     "  --model <profile|provider/model>   pick the model (also /model in-session)\n" +

package/dist/mode.d.ts

@@ -6,7 +6,7 @@
  * switches take effect immediately. The extension NAME rides the runtime's decidedBy
  * field: an automated denial records decidedBy: "mode:<name>" — the
  * audit sell. User-level extensions stay on the chain AFTER the mode
- * tiers; a user deny always wins (the chain's deny>ask>allow
+ * tiers; a user deny always wins (the chain's deny>allow>ask
  * monotonicity — bypass cannot override an extension deny).
  */
 import type { KisoExtension } from "@vincemakes/kiso-runtime";
@@ -29,7 +29,7 @@ export declare function modeFromEnv(): Mode | undefined;
  *  extension name). The CURRENT tier is first: an all-allow chain records
  *  decidedBy = the FIRST SPEAKER, so an auto-allow under the startup mode
  *  names that mode honestly. Order never affects verdicts — the chain is
- *  deny>ask>allow over the SPEAKING verdicts (abstain = no opinion), so a
+ *  deny>allow>ask over the SPEAKING verdicts (abstain = no opinion), so a
  *  user extension's deny wins over any mode tier, bypass included (the
  *  monotonicity e2e pins it). */
 export declare function modeExtensions(): readonly KisoExtension[];

package/dist/mode.js

@@ -6,7 +6,7 @@
  * switches take effect immediately. The extension NAME rides the runtime's decidedBy
  * field: an automated denial records decidedBy: "mode:<name>" — the
  * audit sell. User-level extensions stay on the chain AFTER the mode
- * tiers; a user deny always wins (the chain's deny>ask>allow
+ * tiers; a user deny always wins (the chain's deny>allow>ask
  * monotonicity — bypass cannot override an extension deny).
  */
 export const MODES = ["manual", "default", "accept-edits", "plan", "bypass"];
@@ -78,7 +78,7 @@ function tierVerdict(tier, call) {
  *  extension name). The CURRENT tier is first: an all-allow chain records
  *  decidedBy = the FIRST SPEAKER, so an auto-allow under the startup mode
  *  names that mode honestly. Order never affects verdicts — the chain is
- *  deny>ask>allow over the SPEAKING verdicts (abstain = no opinion), so a
+ *  deny>allow>ask over the SPEAKING verdicts (abstain = no opinion), so a
  *  user extension's deny wins over any mode tier, bypass included (the
  *  monotonicity e2e pins it). */
 export function modeExtensions() {

package/dist/state.d.ts

@@ -156,7 +156,10 @@ export declare function setSessionStore(value: {
 }): void;
 /** The model name for the status bar — set by makeAgent. */
 export declare let agentModel: string;
-export declare function setAgentModel(value: string): void;
+/** OR-1: the live model's ENDPOINT, set in the same call as the model so
+ *  the two can never drift: the window lookup keys on (model, endpoint). */
+export declare let agentBaseUrl: string | undefined;
+export declare function setAgentModel(value: string, baseUrl?: string): void;
 /** merge round B: whether the agent runs on the faux provider (no real key) —
  *  set inside makeAgent, read by main for chat/resume's exhaustion check. */
 export declare let currentFaux: boolean;
@@ -213,7 +216,9 @@ export declare const CANCELLED: unique symbol;
 export interface LastBinding {
     readonly adapter: import("@vincemakes/kiso-core").Adapter;
     readonly model: string;
-    readonly provider?: "anthropic" | "openai-compat";
+    readonly provider?: "anthropic" | "openai-compat" | "openai-responses";
+    /** OR-1: the endpoint inherits with the adapter (the cost path keys on it). */
+    readonly baseUrl?: string;
     readonly scope?: import("@vincemakes/kiso-core").ContinuationScope;
     readonly reasoning?: import("@vincemakes/kiso-runtime/internal").ReasoningSetting;
 }

package/dist/state.js

@@ -213,8 +213,12 @@ export function setSessionStore(value) {
 }
 /** The model name for the status bar — set by makeAgent. */
 export let agentModel = "faux";
-export function setAgentModel(value) {
+/** OR-1: the live model's ENDPOINT, set in the same call as the model so
+ *  the two can never drift: the window lookup keys on (model, endpoint). */
+export let agentBaseUrl;
+export function setAgentModel(value, baseUrl) {
     agentModel = value;
+    agentBaseUrl = baseUrl;
 }
 /** merge round B: whether the agent runs on the faux provider (no real key) —
  *  set inside makeAgent, read by main for chat/resume's exhaustion check. */

package/dist/trust-ui.d.ts

@@ -37,6 +37,19 @@ export declare let pendingAsk: (() => void) | null;
 export declare function askPanel(input: LineInput, view: PanelView, opts?: {
     safer?: () => Promise<SaferAnswer>;
 }): Promise<PanelVerdict>;
+/**
+ * The dock-less fallback line → a verdict. `y…` allows. `n <reason>` / `no
+ * <reason>` DENIES WITH THE REASON — the words become the tool result and
+ * the run continues with the model seeing them, the same verdict the panel's
+ * "No + words" produces (chat.ts, the deny case). A bare `n`/`no`, or any
+ * other line, is the bare denial that aborts the run — unchanged. (LH-1 ruling
+ * 2026-09-08: the default refusal across arms is refuse-with-a-reason-and-
+ * continue, and the surface a piped or 0-row leg drives is this one.)
+ */
+export declare function parseFallbackAnswer(answer: string): {
+    action: "allow" | "deny";
+    reason: string;
+};
 /**
  * KC3.5 — the AskUI bridge: the panel the ask extension asks through.
  *

package/dist/trust-ui.js

@@ -104,12 +104,27 @@ opts) {
                 }
                 settled = true;
                 pendingAsk = null;
-                const yes = answer.trim().toLowerCase().startsWith("y");
-                resolve(yes ? { action: "allow", reason: "" } : { action: "deny", reason: "" });
+                resolve(parseFallbackAnswer(answer));
             });
         }
     });
 }
+/**
+ * The dock-less fallback line → a verdict. `y…` allows. `n <reason>` / `no
+ * <reason>` DENIES WITH THE REASON — the words become the tool result and
+ * the run continues with the model seeing them, the same verdict the panel's
+ * "No + words" produces (chat.ts, the deny case). A bare `n`/`no`, or any
+ * other line, is the bare denial that aborts the run — unchanged. (LH-1 ruling
+ * 2026-09-08: the default refusal across arms is refuse-with-a-reason-and-
+ * continue, and the surface a piped or 0-row leg drives is this one.)
+ */
+export function parseFallbackAnswer(answer) {
+    const line = answer.trim();
+    if (line.toLowerCase().startsWith("y"))
+        return { action: "allow", reason: "" };
+    const m = /^(?:n|no)\b[\s:,-]*(.*)$/is.exec(line);
+    return { action: "deny", reason: (m?.[1] ?? "").trim() };
+}
 /**
  * KC3.5 — the AskUI bridge: the panel the ask extension asks through.
  *

package/dist/update-check.d.ts

@@ -32,8 +32,6 @@ export interface UpdateCache {
     readonly checkedAt: number;
     /** the latest version the registry reported, if the check succeeded */
     readonly latest?: string;
-    /** the version already mentioned to this human — never mentioned twice */
-    readonly told?: string;
 }
 /**
  * Semver-ish "is b newer than a", for the shapes this line ever sees:
@@ -44,7 +42,15 @@ export interface UpdateCache {
 export declare function isNewer(current: string, latest: string): boolean;
 /** The one line, when there is one. Words only — a human can read it,
  *  paste it, and nothing about it needs colour to be understood (§1.2). */
-export declare const updateLine: (latest: string) => string;
+export declare const CHANGELOG_URL = "https://github.com/vincemakes/kiso/releases";
+/** OR-9 (owner, 2026-09-09): the card under the banner, as WORDS — a
+ *  title, the version with the command that installs it, the changelog.
+ *  The CLI styles them at composition; nothing here needs colour. */
+export declare function updateCardLines(latest: string): readonly string[];
+/** OR-9: what the cache already knows, with NO request — the boot paints
+ *  it under the banner before any check runs. Same silences as the check
+ *  (opt-out, faux without a seam, a pipe); a merely-recent cache speaks. */
+export declare function knownUpdate(deps: UpdateCheckDeps): string | null;
 export interface UpdateCheckDeps {
     readonly kisoHome: string;
     readonly version: string;

package/dist/update-check.js

@@ -51,7 +51,6 @@ function readCache(kisoHome) {
         return {
             checkedAt: c.checkedAt,
             ...(typeof c.latest === "string" ? { latest: c.latest } : {}),
-            ...(typeof c.told === "string" ? { told: c.told } : {}),
         };
     }
     catch {
@@ -97,7 +96,23 @@ export function isNewer(current, latest) {
 }
 /** The one line, when there is one. Words only — a human can read it,
  *  paste it, and nothing about it needs colour to be understood (§1.2). */
-export const updateLine = (latest) => `${latest} is out · npm i -g @vincemakes/kiso-code@latest`;
+export const CHANGELOG_URL = "https://github.com/vincemakes/kiso/releases";
+/** OR-9 (owner, 2026-09-09): the card under the banner, as WORDS — a
+ *  title, the version with the command that installs it, the changelog.
+ *  The CLI styles them at composition; nothing here needs colour. */
+export function updateCardLines(latest) {
+    return ["Update available", `New version ${latest} is available. Run kiso update`, `Changelog: ${CHANGELOG_URL}`];
+}
+/** OR-9: what the cache already knows, with NO request — the boot paints
+ *  it under the banner before any check runs. Same silences as the check
+ *  (opt-out, faux without a seam, a pipe); a merely-recent cache speaks. */
+export function knownUpdate(deps) {
+    const why = reasonNotToCheck(deps);
+    if (why !== null && why !== "recent")
+        return null;
+    const cached = readCache(deps.kisoHome);
+    return cached?.latest !== undefined && isNewer(deps.version, cached.latest) ? cached.latest : null;
+}
 /**
  * Should this launch even ask? Pure, so the reasons are testable without
  * a network, a clock or a terminal.
@@ -142,21 +157,14 @@ function reasonNotToCheck({ kisoHome, isTTY, faux, now = Date.now() }) {
 export async function checkForUpdate(deps) {
     const { kisoHome, version, now = Date.now() } = deps;
     const why = reasonNotToCheck(deps);
-    if (why !== null) {
-        // ONLY a recent check may still speak. The other three reasons are
-        // about the LINE, not about the request, so the cache is no way
-        // around them — an opt-out that still got announced, or a piped
-        // run that gained a row of kiso's prose, would be the feature
-        // ignoring the answer it was given.
-        if (why !== "recent")
-            return null;
-        const cached = readCache(kisoHome);
-        if (cached?.latest !== undefined && cached.told !== cached.latest && isNewer(version, cached.latest)) {
-            writeCache(kisoHome, { ...cached, told: cached.latest });
-            return updateLine(cached.latest);
-        }
-        return null;
-    }
+    // ONLY a recent check may still speak from cache. The other three
+    // reasons are about the CARD, not the request, so the cache is no way
+    // around them. OR-9: no `told` gate — a newer version is known at
+    // EVERY start (the card is shown every start; the once-only rule of
+    // §7.10 is superseded by the owner's 2026-09-09 ruling), only the
+    // REQUEST stays at most once a day.
+    if (why !== null)
+        return why === "recent" ? knownUpdate(deps) : null;
     let latest;
     try {
         const ctl = new AbortController();
@@ -177,15 +185,6 @@ export async function checkForUpdate(deps) {
     catch {
         // every failure is silence — see the header
     }
-    const prev = readCache(kisoHome);
-    const show = latest !== undefined && isNewer(version, latest) && prev?.told !== latest;
-    // `told` survives a check that learned nothing: forgetting it would
-    // re-announce a version this human has already been told about.
-    const told = show ? latest : prev?.told;
-    writeCache(kisoHome, {
-        checkedAt: now,
-        ...(latest === undefined ? {} : { latest }),
-        ...(told === undefined ? {} : { told }),
-    });
-    return show && latest !== undefined ? updateLine(latest) : null;
+    writeCache(kisoHome, { checkedAt: now, ...(latest === undefined ? {} : { latest }) });
+    return latest !== undefined && isNewer(version, latest) ? latest : null;
 }