@vincemakes/kiso-code 0.31.0 → 0.31.1

package/dist/auth/oauth/chatgpt.js

@@ -164,6 +164,12 @@ export const chatgptFlow = {
         const flow = createAuthorizationFlow(redirectUri);
         const server = await startCallbackServer(flow.state, cb.host, cb.port);
         interaction.notify(`open this URL to sign in:\n  ${flow.url}`);
+        // OR-4 (owner, 2026-09-09): the URL is opened for the person when the
+        // caller can — the printed line stays the fallback and the paste path.
+        if (interaction.open !== undefined) {
+            interaction.open(flow.url);
+            interaction.notify("(opened in your browser — if nothing opened, copy the URL above)");
+        }
         let code = null;
         if (server !== null) {
             interaction.notify(`waiting for the browser to come back to ${redirectUri} … (or paste the redirected URL here)`);

package/dist/auth/oauth/index.d.ts

@@ -14,6 +14,11 @@ export interface LoginInteraction {
     /** Ask the person for a line (the pasted redirect URL or code when the
      *  local callback cannot be reached); resolves "" when unavailable. */
     readonly prompt: (question: string) => Promise<string>;
+    /** OR-4: open the authorize URL in the person's browser, when there is
+     *  one. OPTIONAL — the CLI passes it on a TTY; tests and pipes never do,
+     *  so nothing opens a browser under a test rig. The URL is always
+     *  printed too: this is a convenience, never the only path. */
+    readonly open?: (url: string) => void;
     readonly signal?: AbortSignal;
     /** Test seam: the callback listener's host/port (defaults 127.0.0.1:1455). */
     readonly callback?: {

package/dist/chat.d.ts

@@ -38,6 +38,15 @@ export declare function estimateCtxRatio(session: AgentSession): number;
  *  their continuation envelopes, the output reserve when known) over the
  *  window. Still ~ (chars/4). The auto-compact policy does NOT read this
  *  (see autoCompactRatio) — moving the policy's number is A1b's. */
+/** OR-8 (owner, 2026-09-09): the status row names the effort next to the
+ *  model — `gpt-5.6-sol · xhigh` — whenever the live binding carries one;
+ *  the provider's default shows as the bare model, as before. The effort
+ *  is the session's own (the durable profile), never the CLI's memory. */
+export declare function statusModelLabel(session: {
+    readonly reasoning?: {
+        readonly effort: string;
+    };
+}): string;
 export declare function displayCtxRatio(session: AgentSession): number;
 /** A1a: the number the auto-compact decision reads — the pre-A1a estimate,
  *  unchanged this round, named so a gate can pin that it did not move. */

package/dist/chat.js

@@ -69,6 +69,14 @@ export function estimateCtxRatio(session) {
  *  their continuation envelopes, the output reserve when known) over the
  *  window. Still ~ (chars/4). The auto-compact policy does NOT read this
  *  (see autoCompactRatio) — moving the policy's number is A1b's. */
+/** OR-8 (owner, 2026-09-09): the status row names the effort next to the
+ *  model — `gpt-5.6-sol · xhigh` — whenever the live binding carries one;
+ *  the provider's default shows as the bare model, as before. The effort
+ *  is the session's own (the durable profile), never the CLI's memory. */
+export function statusModelLabel(session) {
+    const effort = session.reasoning?.effort;
+    return effort !== undefined && effort !== "default" ? `${agentModel} · ${effort}` : agentModel;
+}
 export function displayCtxRatio(session) {
     return requestBudget(session.requestParts(), contextWindowTokens()).ratio;
 }
@@ -127,7 +135,24 @@ endpoint) {
         const m = Math.min(prevTotal, total) - c.cacheRead;
         missed = m > CACHE_MISS_FLOOR ? m : null;
     }
-    return { usage: { in: c.input, out: c.output, cache: c.cacheRead, known: ev.known }, total, missed, costUsd: c.costUsd };
+    // OR-10 (owner, 2026-09-09): a backend whose cache figure cannot be
+    // observed has no cache figure. The ChatGPT backend answers
+    // `cached_tokens` 0 to a third-party client on every request, so its 0
+    // and "not reported" are one value, and a CH 0% built on it claims a
+    // measurement that never happened. The registry ROW says which
+    // endpoints these are; the status row, the recap and the usage line
+    // already render a null cache as nothing ("an unmeasured cache is not
+    // a 0% cache"), so this is one decision at the one place the endpoint
+    // is known. The trace ledger is written by the runtime from the
+    // backend's own words and keeps its 0 — the display's rule, not the
+    // record's.
+    const unobservable = model !== undefined && lookupModelMetadata(model, endpoint)?.capabilities.promptCaching === "unobservable";
+    return {
+        usage: { in: c.input, out: c.output, cache: unobservable ? null : c.cacheRead, known: ev.known },
+        total,
+        missed: unobservable ? null : missed,
+        costUsd: c.costUsd,
+    };
 }
 /** v2b: the spinner merged into the STATUS BAR (the v2a standalone glyph
  *  is gone) — docked only, 200ms rotation between the request and the
@@ -791,6 +816,17 @@ submitTurn) {
                         // is a sentence addressed to a human; it needs no edge.
                         body.notice('answer truncated at max_tokens — say "continue" to finish');
                     }
+                    // OR-5 (the ChatGPT real leg, 2026-09-09): a run that ended in an
+                    // ERROR terminal printed nothing but the recap — the vendor's 400
+                    // lived in the durable log alone and the turn read as "took 1s".
+                    // A failure that fires silently is indistinguishable from a
+                    // crash, the one thing this product must never be: the mapped
+                    // error is named here, before the recap, code and status and the
+                    // provider's own words.
+                    if (ev.outcome.kind === "error") {
+                        const e = ev.outcome.error;
+                        body.notice(`run failed — ${e.code}${e.status !== undefined ? ` ${e.status}` : ""}${e.retryable ? " (retryable)" : ""}: ${escapeTerminal(e.message)}`);
+                    }
                     bodyLog(renderRecap({
                         seconds: Math.round((Date.now() - turnStart) / 1000),
                         // R3g: the work terms are NOT passed — the fold line
@@ -1083,7 +1119,7 @@ export async function chat(session, faux, input, autoCompact, nav) {
         // TUI2-R1 (E): the meter rides the idle row — both fields omitted
         // when unknown, so a session that has not called the model paints
         // exactly the pre-round row.
-        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), {
             cacheHitPct: cacheHitPct(runUsage),
             costUsd: spentUsd,
         }));

package/dist/config.js

@@ -31,6 +31,7 @@ import { readFileSync } from "node:fs";
 import { join } from "node:path";
 import { kisoHome } from "./state.js";
 import { AuthError, getCredential, providerIdOf } from "./auth/credentials.js";
+import { BUILTIN_MANIFESTS } from "@vincemakes/kiso-runtime/internal";
 const KINDS = ["openai-compat", "anthropic", "openai-responses"];
 const MODES_LIST = ["manual", "default", "accept-edits", "plan", "bypass"];
 export class ConfigError extends Error {
@@ -209,6 +210,15 @@ export function authForProfile(name, p) {
             throw new ConfigError(`model ${name}: signed in to ${providerId} with OAuth, but this profile's adapter needs an API key — run \`kiso login ${providerId}\` with a key, or \`kiso logout ${providerId}\` to use the env var ${p.apiKeyEnv ?? "(none configured)"}`);
         }
     }
+    // OR-2 (2026-09-09): a provider whose manifest takes NO API key (the ChatGPT
+    // backend: authMethods ["oauth"]) is never an "unauthenticated endpoint" —
+    // with nothing stored it is a profile waiting for its sign-in. Without this
+    // the keyless rule below handed it a placeholder key, `/model` said
+    // "available", and the adapter (an apiKey selects the first-party target)
+    // would have sent an unauthenticated request to the wrong URL.
+    if (providerId !== null && !manifestTakesKey(providerId)) {
+        throw new ConfigError(`model ${name}: unavailable — not signed in: run \`kiso login ${providerId}\` (this provider takes no API key)`);
+    }
     if (p.apiKeyEnv === undefined)
         return { type: "api-key", apiKey: "none", source: "none" };
     const fromEnv = process.env[p.apiKeyEnv];
@@ -217,6 +227,13 @@ export function authForProfile(name, p) {
     const hint = providerId !== null ? `run \`kiso login ${providerId}\` or set the env var ${p.apiKeyEnv}` : `set the env var ${p.apiKeyEnv}`;
     throw new ConfigError(`model ${name}: unavailable — no credential: ${hint} (configs never store keys, only the env-var name)`);
 }
+/** OR-2: does the provider's manifest admit an API key (or no auth at all)?
+ *  An unknown id answers yes — the keyless-endpoint rule stays for custom
+ *  origins; only a manifest that says OAuth-only takes the sign-in path. */
+function manifestTakesKey(providerId) {
+    const m = BUILTIN_MANIFESTS.find((x) => x.id === providerId);
+    return m === undefined || m.authMethods.includes("api-key") || m.authMethods.includes("none");
+}
 /** The reason a profile is unavailable, for the surfaces that print it. */
 export function unavailableReason(name, p) {
     try {

package/dist/dispatch.js

@@ -8,7 +8,7 @@ import { newSessionId } from "./session-id.js";
 import { buildAdapter, lookupModelMetadata, resolveContinuationScope, resolveReasoning } from "@vincemakes/kiso-runtime/internal";
 import { MODES, MODE_NOTE, getMode, setMode } from "./mode.js";
 import { clipboardWrite, lastAnswer } from "./clipboard.js";
-import { agentModel, body, bodyLog, configModels, dock, readContextLedger, sessionsDir, setAgentModel, setCurrentModelName, setLastBinding } from "./state.js";
+import { agentModel, body, bodyLog, configModels, dock, lastBinding, readContextLedger, sessionsDir, setAgentModel, setCurrentModelName, setLastBinding } from "./state.js";
 import { authForProfile, directWriteProfile, profileAvailable, unavailableReason } from "./config.js";
 /** The picker's CLI half (owner 2026-09-08): a profile's LEGAL effort levels
  *  and its default, from the registry, shown wherever the profile is listed
@@ -22,6 +22,43 @@ function effortNote(p) {
         return "effort: unknown";
     return `effort: ${effort.levels.map((l) => (l === effort.default ? `[${l}]` : l)).join(" · ")}`;
 }
+/** OR-7 — the pick panel's second axis, as DATA. `effortNote` above stays
+ *  the PRINTED list's string (a machine-readable surface whose bytes do
+ *  not move); the panel gets the levels structured so its cursor can walk
+ *  them, and so the bracket can mean "the cursor is here" rather than
+ *  "the registry default".
+ *
+ *  Where the cursor starts: the session's CURRENT effort when this model
+ *  has that level, else the model's default, else nowhere — a row whose
+ *  registry default is null (the model page states none) marks nothing,
+ *  and enter on it applies the profile alone. Nothing is invented. */
+function effortAxis(p) {
+    const reasoning = lookupModelMetadata(p.model, p.baseUrl)?.capabilities.reasoning ?? null;
+    if (reasoning === null)
+        return {};
+    const effort = reasoning.effort;
+    if (effort === null)
+        return {};
+    const levels = effort.levels;
+    const carried = lastBinding()?.reasoning?.effort;
+    const carriedIdx = carried === undefined || carried === "default" ? -1 : levels.indexOf(carried);
+    const defaultIdx = effort.default === null ? -1 : levels.indexOf(effort.default);
+    const level = carriedIdx >= 0 ? carriedIdx : defaultIdx;
+    // the forbidden set is per THINKING mode, and the panel applies its
+    // pick as thinking "default" — the same setting `/model <p> <e>`
+    // builds — so only pairs forbidden at that mode are dimmed here.
+    const disabled = (reasoning.forbidden ?? []).filter((f) => f.thinking === "default").map((f) => levels.indexOf(f.effort)).filter((i) => i >= 0);
+    return {
+        levels,
+        ...(level >= 0 ? { level } : {}),
+        ...(disabled.length > 0 ? { disabled } : {}),
+        // the sentence the coordination note asked for: said only when the
+        // cursor could NOT land where the previous selection asked.
+        ...(carried !== undefined && carried !== "default" && carriedIdx < 0 && defaultIdx >= 0
+            ? { levelNote: `effort ${carried} \u2192 ${levels[defaultIdx]}: the nearest this model supports` }
+            : {}),
+    };
+}
 /** What signs a profile in, for the listing: the env var's name, `oauth`
  *  for a subscription sign-in, or `no key` for an unauthenticated endpoint. */
 function signInNote(p) {
@@ -316,13 +353,17 @@ export function dispatch(line, ctx) {
             // surface and this round moves no bytes on one.
             if (arg === "" && dock.active && ctx.input.panelAsk !== undefined) {
                 const names = Object.keys(configModels);
+                let pickedLevel;
                 const picked = await new Promise((resolve) => {
                     ctx.input.panelAsk(modelPickView({
                         header: `model — current: ${agentModel}`,
                         options: names.map((name) => {
                             const profile = configModels[name];
-                            const marks = [`profile: ${name}`, ...(profileAvailable(profile) ? [] : ["unavailable"]), ...(profile.model === agentModel ? ["current"] : []), effortNote(profile)];
-                            return { label: `${profile.kind}/${profile.model}`, note: marks.join(" · ") };
+                            // the note keeps what tells two rows apart; the levels
+                            // left it for the axis below (they were being cut off
+                            // the end of the note column at 100 columns).
+                            const marks = [`profile: ${name}`, ...(profileAvailable(profile) ? [] : ["unavailable"]), ...(profile.model === agentModel ? ["current"] : [])];
+                            return { label: `${profile.kind}/${profile.model}`, note: marks.join(" · "), ...effortAxis(profile) };
                         }),
                         // PH-1a (finding PH-F4): the example must be a syntax
                         // directWriteProfile actually ACCEPTS — the old
@@ -337,14 +378,30 @@ export function dispatch(line, ctx) {
                     // DC-12 (design §4): a panel WAITING ON A HUMAN says ❯. The
                     // else-branch keeps ▸ — it names the current tier, which is
                     // what ▸ means everywhere else.
-                    ctx.isRunning() ? "❯ run paused" : `▸ ${getMode()}`), (v) => resolve(v.action === "picked" ? v.result : null));
+                    ctx.isRunning() ? "❯ run paused" : `▸ ${getMode()}`), (v) => {
+                        // OR-7: the level rides beside the result, so a pick
+                        // with no second axis is byte-for-byte the old one.
+                        if (v.action === "picked")
+                            pickedLevel = v.level;
+                        resolve(v.action === "picked" ? v.result : null);
+                    });
                 });
                 ctx.paintIdle();
                 if (picked === null) {
                     ctx.input.prompt();
                     return; // esc — nothing switched, nothing said
                 }
-                arg = "index" in picked ? names[picked.index] : picked.custom;
+                if ("index" in picked) {
+                    // OR-7: the panel hands back both axes and the command
+                    // string is where they meet — everything below is the
+                    // typed `/model <profile> <effort>` path, unchanged, so
+                    // the refusal wording and the durable revision are its.
+                    const name = names[picked.index];
+                    const level = pickedLevel === undefined ? undefined : effortAxis(configModels[name]).levels?.[pickedLevel];
+                    arg = level === undefined ? name : `${name} ${level}`;
+                }
+                else
+                    arg = picked.custom;
             }
             if (arg === "") {
                 bodyLog(`model: ${agentModel}`);
@@ -373,7 +430,13 @@ export function dispatch(line, ctx) {
                         bodyLog(`no such model profile: ${profName}`);
                     }
                     else if (!profileAvailable(profile)) {
-                        bodyLog(unavailableReason(arg, profile));
+                        // the PROFILE name, not the whole argument: what is
+                        // unavailable is the credential, and an effort token
+                        // riding along ("claude high: unavailable") reads as
+                        // though the level were part of the problem. The panel
+                        // began producing that token in OR-7; the typed path
+                        // could always produce it too.
+                        bodyLog(unavailableReason(profName, profile));
                     }
                     else {
                         const auth = authForProfile(profName, profile);
@@ -430,6 +493,12 @@ export function dispatch(line, ctx) {
                             setLastBinding(binding);
                             setAgentModel(profile.model, profile.baseUrl);
                             setCurrentModelName(arg);
+                            // OR-7 (owner, 2026-09-09): the status row is repainted BY the
+                            // switch — it used to keep the old model until the next
+                            // recap repainted it, so "takes effect on the next turn"
+                            // read as "did not take". Painted BEFORE the notice so the
+                            // frame that carries the notice already carries the row.
+                            ctx.paintIdle();
                             body.notice(`model → ${profName} (${profile.model}${effortTok !== undefined ? ` · ${effortTok}` : ""}) — takes effect on the next turn`);
                         }
                     }

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,10 +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 { oauthTokenThunk } from "./auth/token.js";
-import { checkForUpdate } from "./update-check.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";
@@ -62,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 {
@@ -384,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
@@ -742,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)
@@ -778,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 {
@@ -830,10 +873,15 @@ async function readSecret(prompt) {
             process.stdin.resume();
         });
     }
-    process.stdout.write(prompt);
     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) => {
@@ -975,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 =
@@ -1195,6 +1256,9 @@ async function main() {
                         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 } : {}),
                         });
@@ -1213,6 +1277,27 @@ async function main() {
                 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
@@ -1230,6 +1315,7 @@ async function main() {
                     "                           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/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;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@vincemakes/kiso-code",
-	"version": "0.31.0",
+	"version": "0.31.1",
 	"description": "kiso CLI — the durable coding agent that survives kill -9: kiso chat / kiso resume / kiso sessions.",
 	"type": "module",
 	"license": "MIT",
@@ -18,20 +18,20 @@
 		"test": "vitest run"
 	},
 	"dependencies": {
-		"@vincemakes/kiso-ask-ext": "0.31.0",
-		"@vincemakes/kiso-core": "0.31.0",
-		"@vincemakes/kiso-evals": "0.31.0",
-		"@vincemakes/kiso-mcp-ext": "0.31.0",
-		"@vincemakes/kiso-provider-anthropic": "0.31.0",
-		"@vincemakes/kiso-provider-openai": "0.31.0",
-		"@vincemakes/kiso-provider-openai-responses": "0.31.0",
-		"@vincemakes/kiso-runtime": "0.31.0",
-		"@vincemakes/kiso-skills-ext": "0.31.0",
-		"@vincemakes/kiso-subagent-ext": "0.31.0",
-		"@vincemakes/kiso-task-ext": "0.31.0",
-		"@vincemakes/kiso-tools-node": "0.31.0",
-		"@vincemakes/kiso-tui": "0.31.0",
-		"@vincemakes/kiso-tui-cells": "0.31.0"
+		"@vincemakes/kiso-ask-ext": "0.31.1",
+		"@vincemakes/kiso-core": "0.31.1",
+		"@vincemakes/kiso-evals": "0.31.1",
+		"@vincemakes/kiso-mcp-ext": "0.31.1",
+		"@vincemakes/kiso-provider-anthropic": "0.31.1",
+		"@vincemakes/kiso-provider-openai": "0.31.1",
+		"@vincemakes/kiso-provider-openai-responses": "0.31.1",
+		"@vincemakes/kiso-runtime": "0.31.1",
+		"@vincemakes/kiso-skills-ext": "0.31.1",
+		"@vincemakes/kiso-subagent-ext": "0.31.1",
+		"@vincemakes/kiso-task-ext": "0.31.1",
+		"@vincemakes/kiso-tools-node": "0.31.1",
+		"@vincemakes/kiso-tui": "0.31.1",
+		"@vincemakes/kiso-tui-cells": "0.31.1"
 	},
 	"devDependencies": {
 		"@types/node": "^26.1.2",

package/dist/diff.d.ts

@@ -1,32 +0,0 @@
-/**
- * v2e — the diff renderer: edit/write changes as inline ± lines, zero
- * dependencies, no syntax highlighting (the spec's scope line). Shown at
- * the approval moment ONLY — the frozen summary stays one line (v2d's
- * anti-leak principle), /last has the full data.
- *
- * edit_file diffs IN PLACE (the search→replace windows are known — no
- * general engine needed); write_file does a row-level LCS over the old
- * file (small files are the target). Context: 2 rows each side. The
- * RENDERER truncates (18 head + 18 tail + "… N lines"); the stats come
- * from the full diff.
- */
-/** The diff block's per-row kind. */
-export type DiffLine = {
-    kind: "-" | "+" | " ";
-    text: string;
-};
-export interface DiffResult {
-    /** The FULL diff (with context, not truncated) — the display truncates. */
-    lines: DiffLine[];
-    added: number;
-    removed: number;
-}
-/** The RENDERER's truncation: head + "… N lines (/last for full)" + tail. */
-export declare function truncateDiff(diff: DiffLine[]): DiffLine[];
-/** edit_file: the search→replace windows replace in place — the changed
- *  region is KNOWN, so the diff is the old window vs the new window,
- *  context from the surrounding file. */
-export declare function editFileDiff(oldContent: string, search: string, replace: string): DiffResult;
-/** write_file: a new file is all +; an existing file diffs row-level
- *  against its old content. */
-export declare function writeFileDiff(oldContent: string | null, newContent: string): DiffResult;

package/dist/diff.js

@@ -1,122 +0,0 @@
-/**
- * v2e — the diff renderer: edit/write changes as inline ± lines, zero
- * dependencies, no syntax highlighting (the spec's scope line). Shown at
- * the approval moment ONLY — the frozen summary stays one line (v2d's
- * anti-leak principle), /last has the full data.
- *
- * edit_file diffs IN PLACE (the search→replace windows are known — no
- * general engine needed); write_file does a row-level LCS over the old
- * file (small files are the target). Context: 2 rows each side. The
- * RENDERER truncates (18 head + 18 tail + "… N lines"); the stats come
- * from the full diff.
- */
-/** A line-level LCS diff — the classic two-row DP, ~small inputs. */
-function lcsDiff(oldLines, newLines) {
-    const n = oldLines.length;
-    const m = newLines.length;
-    const dp = Array.from({ length: n + 1 }, () => new Array(m + 1).fill(0));
-    for (let i = n - 1; i >= 0; i -= 1) {
-        for (let j = m - 1; j >= 0; j -= 1) {
-            dp[i][j] = oldLines[i] === newLines[j] ? dp[i + 1][j + 1] + 1 : Math.max(dp[i + 1][j], dp[i][j + 1]);
-        }
-    }
-    const out = [];
-    let i = 0;
-    let j = 0;
-    while (i < n && j < m) {
-        if (oldLines[i] === newLines[j]) {
-            out.push({ kind: " ", text: oldLines[i] });
-            i += 1;
-            j += 1;
-        }
-        else if (dp[i + 1][j] >= dp[i][j + 1]) {
-            out.push({ kind: "-", text: oldLines[i] });
-            i += 1;
-        }
-        else {
-            out.push({ kind: "+", text: newLines[j] });
-            j += 1;
-        }
-    }
-    while (i < n) {
-        out.push({ kind: "-", text: oldLines[i] });
-        i += 1;
-    }
-    while (j < m) {
-        out.push({ kind: "+", text: newLines[j] });
-        j += 1;
-    }
-    return out;
-}
-/** Keep 2 context rows around each change — the unified-style window. */
-function withContext(diff) {
-    const out = [];
-    let lastAdded = -10;
-    for (let k = 0; k < diff.length; k += 1) {
-        if (diff[k].kind === " ")
-            continue;
-        const from = Math.max(0, k - 2);
-        const to = Math.min(diff.length - 1, k + 2);
-        for (let c = from; c <= to; c += 1) {
-            if (c > lastAdded) {
-                out.push(diff[c]);
-                lastAdded = c;
-            }
-        }
-        lastAdded = to;
-    }
-    return out;
-}
-const MAX_DIFF_LINES = 40; // the RENDERED cap
-const TRUNCATE_KEEP = 18;
-/** The RENDERER's truncation: head + "… N lines (/last for full)" + tail. */
-export function truncateDiff(diff) {
-    if (diff.length <= MAX_DIFF_LINES)
-        return diff;
-    const omitted = diff.length - 2 * TRUNCATE_KEEP;
-    return [
-        ...diff.slice(0, TRUNCATE_KEEP),
-        { kind: " ", text: `… ${omitted} lines (/last for full)` },
-        ...diff.slice(diff.length - TRUNCATE_KEEP),
-    ];
-}
-function stats(diff) {
-    let added = 0;
-    let removed = 0;
-    for (const d of diff) {
-        if (d.kind === "+")
-            added += 1;
-        else if (d.kind === "-")
-            removed += 1;
-    }
-    return { added, removed };
-}
-/** edit_file: the search→replace windows replace in place — the changed
- *  region is KNOWN, so the diff is the old window vs the new window,
- *  context from the surrounding file. */
-export function editFileDiff(oldContent, search, replace) {
-    const oldLines = oldContent.split("\n");
-    const searchLines = search.split("\n");
-    const replaceLines = replace.split("\n");
-    // Locate the search window (the first occurrence — the edit tool's own
-    // semantics); no occurrence → the whole file is the old side.
-    let at = -1;
-    for (let i = 0; i + searchLines.length <= oldLines.length; i += 1) {
-        if (oldLines.slice(i, i + searchLines.length).join("\n") === search) {
-            at = i;
-            break;
-        }
-    }
-    const lines = at < 0 ? withContext(lcsDiff(oldLines, replaceLines)) : withContext(lcsDiff(oldLines, [...oldLines.slice(0, at), ...replaceLines, ...oldLines.slice(at + searchLines.length)]));
-    return { lines, ...stats(lines) };
-}
-/** write_file: a new file is all +; an existing file diffs row-level
- *  against its old content. */
-export function writeFileDiff(oldContent, newContent) {
-    if (oldContent === null) {
-        const lines = newContent.split("\n").map((text) => ({ kind: "+", text }));
-        return { lines, added: lines.length, removed: 0 };
-    }
-    const lines = withContext(lcsDiff(oldContent.split("\n"), newContent.split("\n")));
-    return { lines, ...stats(lines) };
-}