@vincemakes/kiso-code 0.31.0 → 0.32.0

package/dist/index.js

@@ -24,25 +24,27 @@
  * 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";
 import { fileURLToPath } from "node:url";
 import { join } from "node:path";
-import { Body, Editor, bannerLines, currentGround, resolveGround, setGround, escapeTerminal, extensionsBannerText, idColumn, idleStatus, interactivePrompt, palette, renderSessionLine, sessionListFooter, sessionListRow } from "@vincemakes/kiso-tui";
+import { Body, Editor, PROMPT, bannerLines, currentGround, resolveGround, setGround, escapeTerminal, extensionsBannerText, idColumn, idleStatus, interactivePrompt, palette, renderSessionLine, sessionListFooter, sessionListRow } from "@vincemakes/kiso-tui";
 import { createAgent, disposeExtensions, loadExtensions, loadProjectExtensions, SessionStore, } from "@vincemakes/kiso-runtime";
 import { createFauxProvider } from "@vincemakes/kiso-evals";
 import { createCodingTools } from "@vincemakes/kiso-tools-node";
 import { MODES, getMode, modeExtensions, modeFromEnv, modeSystemPrompt, setMode } from "./mode.js";
+import { breakerExtension } from "./breaker.js";
 import { builtInLayer } from "./builtin.js";
-import { agentModel, atFiles, body, bodyLog, kisoHome, builtInExtensions, currentFaux, dock, extensionsDir, loadedExtensions, mergedConfig, mergedTempPaths, projectExtensions, sessionStoreRef, sessionsDir, setAgentModel, setBody, setConfigModels, setConfiguredWindow, setCurrentAgentExtensions, setCurrentFaux, setCurrentModelName, setExtensionLists, setMergedConfig, setSessionStore, userExtensions, VERSION, lastBinding, acceptDrift, setAcceptDrift } from "./state.js";
+import { agentModel, atFiles, body, bodyLog, codingToolOptions, kisoHome, builtInExtensions, currentFaux, dock, extensionsDir, loadedExtensions, mergedConfig, mergedTempPaths, modelChoice, projectExtensions, configModels, configuredWindow, agentBaseUrl, currentModelName, currentAgentExtensions, sessionStoreRef, sessionsDir, setAgentModel, setBody, setConfigModels, setConfiguredWindow, setCurrentAgentExtensions, setCurrentFaux, setCurrentModelName, setExtensionLists, setMergedConfig, setModelChoice, setSessionStore, userExtensions, VERSION, lastBinding, acceptDrift, setAcceptDrift } from "./state.js";
 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 +64,40 @@ 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
+    }
+}
+/** LT-1: the stream watchdog's bound from the environment — a non-negative
+ *  number of milliseconds (0 disables it); anything else is ignored. The
+ *  PTY rigs use it to trip the watchdog in seconds against a stub that
+ *  never finishes a stream. */
+function streamIdleFromEnv() {
+    const raw = process.env.KISO_STREAM_IDLE_MS;
+    if (raw === undefined || raw === "")
+        return undefined;
+    const n = Number(raw);
+    return Number.isFinite(n) && n >= 0 ? n : undefined;
+}
+/** 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 {
@@ -102,6 +138,17 @@ function readlineInput(rl) {
             /* readline has no ctrl+o binding — ignored (W15 rides the
              * editor path only). */
         },
+        onThink() {
+            /* §2.3: same as ctrl+o above — readline has no binding, and a
+             * dock-less session has no committed rows to reprint. */
+        },
+        onEditor() {
+            /* §2.4: readline has no ctrl+g, and a piped session has no
+             * composer to hand over. */
+        },
+        externalEdit() {
+            /* §2.4: nothing to suspend — this path never took the terminal. */
+        },
         onCopy() {
             /* readline has no ctrl+x binding — ignored. `/copy` still
              * works here: it is a typed command, not a key. */
@@ -186,6 +233,15 @@ function editorInput(editor) {
         onExpand(cb) {
             editor.onExpand(cb);
         },
+        onThink(cb) {
+            editor.onThink(cb);
+        },
+        onEditor(cb) {
+            editor.onEditor(cb);
+        },
+        externalEdit(edit) {
+            editor.externalEdit(edit);
+        },
         onCopy(cb) {
             editor.onCopy(cb);
         },
@@ -343,7 +399,15 @@ function makeLineInput() {
         // here", which is the argument W6 made for the box and the only part
         // of it that survives. A prompt character is a third thing saying
         // the same thing, and it cost the row a column.
-        dock.bindInput(() => editor.dockState(), "");
+        // OR-11 (a): ONE literal. The compositor draws this lead and the
+        // editor measures its rows against it; two copies is how they came
+        // to disagree by two columns in the first place.
+        const COMPOSER_LEAD = "";
+        dock.bindInput(() => editor.dockState(), COMPOSER_LEAD);
+        // …and BOTH renderers are live: the dock draws this row while it is
+        // active, the editor's own selfRender draws it (with the brick) when
+        // it is not. The budget follows whichever is drawing.
+        editor.setInputLead(() => (dock.active ? COMPOSER_LEAD : PROMPT));
         // TUI2-R3v2 ②: the click hit-test's wiring — the compositor places
         // the panel's option rows, so the compositor is what the editor asks
         // where they are. Neither side computes the other's geometry.
@@ -384,28 +448,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
@@ -553,6 +631,11 @@ function positiveIntEnv(name) {
     return Number.isFinite(n) && n > 0 ? n : undefined;
 }
 async function makeAgent(sessionId, input, modelFlag) {
+    // §2.5: the ONE source a reload reads for the model, seeded here from
+    // the startup flag. Without this a session started with `--model X`
+    // would silently revert to the env/config default on its first reload.
+    if (modelFlag !== undefined)
+        setModelChoice(modelFlag);
     // E3: the project-level trust gate runs BEFORE any extension load (the
     // mcp/skills merges must be in the env when the user-level extensions
     // load). Untrusted project capability is never loaded — never silently.
@@ -614,16 +697,19 @@ async function makeAgent(sessionId, input, modelFlag) {
     // generated extension into it so a first-time rule joins the chain
     // at the NEXT run (the run's policies are fixed at its start; run.ts
     // re-reads the config's extensions array per run).
-    const extensions = [...modeExtensions(), ...loadedExtensions];
+    // LT-2: the loop breaker at the chain HEAD — it speaks first when it speaks,
+    // so `decidedBy` names it; a deny there beats every tier, bypass included.
+    const extensions = [breakerExtension(), ...modeExtensions(), ...loadedExtensions];
     setCurrentAgentExtensions(extensions);
     // E6: the run-start context policy (captured once — exactOptionalPropertyTypes).
     const contextPolicy = contextPolicyFromEnv();
+    const idleFromEnv = streamIdleFromEnv(); // read once: a narrowed const, not a call per spread
     const definition = {
         model,
         store,
         // Area 5: the coding tools are bound to the workspace — every path
         // they touch is canonicalized inside cwd, escapes are refused.
-        tools: [...createCodingTools({ workspaceRoot: process.cwd(), excludeRoots: [kisoHome()] })], // DC-49
+        tools: [...createCodingTools(codingToolOptions())], // DC-49 — the options live in state.ts, shared with the `!` command's runner
         // Modes: the five tiers ride the E1 policy chain (mode:<tier>
         // extensions, current tier first) — the old static PERMISSION_POLICY
         // is gone, its semantics live in the "default" tier. The banner
@@ -668,8 +754,13 @@ async function makeAgent(sessionId, input, modelFlag) {
                 ...(sessionId !== undefined ? { promptCacheKey: sessionId } : {}),
                 ...(resolved.profile.baseUrl !== undefined ? { baseUrl: resolved.profile.baseUrl } : {}),
                 ...(resolved.profile.promptCaching !== undefined ? { promptCaching: resolved.profile.promptCaching } : {}),
+                // LT-1: the profile's stream watchdog bound, if it states one
+                ...(resolved.profile.streamIdleMs !== undefined ? { streamIdleMs: resolved.profile.streamIdleMs } : {}),
             }
             : { adapter: createFauxProvider(readFauxScript().slice(fauxSkipTurns)) }),
+        // LT-1: KISO_STREAM_IDLE_MS (the test rigs' knob) beats the profile —
+        // the last spread wins, which is why it sits after the profile's.
+        ...(idleFromEnv !== undefined ? { streamIdleMs: idleFromEnv } : {}),
     };
     return createAgent(definition);
 }
@@ -742,7 +833,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)
@@ -756,12 +847,137 @@ class CliUsageError extends Error {
  *  line (the previous conversation stays resumable — clear/switch
  *  never erase history). Faux sessions re-arm the scripted adapter at
  *  the NEW session's durable position, exactly like the picker path. */
-async function chatLoop(agent, firstId, input, autoCompact) {
+/** §2.5 — how many skills are IN FORCE, taken from the extension that
+ *  indexed them rather than by walking the directory again. The first
+ *  version re-scanned `KISO_SKILLS_DIR` for one number in one log line,
+ *  which is a second answer to a question already answered and free to
+ *  disagree with the first (lead's review of 5bee644, observation 2).
+ *  An extension that reports no count is reported as none, never guessed. */
+function skillCount() {
+    // `skills` is declared on the extension's own published type
+    // (extensions/skills/index.d.ts), not invented here.
+    const skills = loadedExtensions.find((e) => e.name === "skills");
+    return skills?.skills ?? 0;
+}
+/**
+ * §2.5 — the reload: the agent is CONSTRUCTED AGAIN on the same session.
+ *
+ * Nothing short of this reloads the whole surface. `run.ts` composes the
+ * system prompt and the approval chain per run, so mutating the shared
+ * extensions array reaches those — but the tool registry is built in the
+ * agent's constructor and has no unregister, and hooks are frozen into
+ * the session's config. Half a reload is worse than none: a prompt that
+ * announces a skill whose tool is not in the table is the DC-19 family.
+ *
+ * LOAD FIRST, SWAP ONLY ON SUCCESS. `loadExtensions` is deliberately
+ * loud, so tearing the old agent down first would leave a typo in an
+ * extension holding a live session with no agent and no way back. The
+ * cost is that two sets of MCP servers are briefly alive; a stdio server
+ * holding an exclusive resource — a port, a lock — fails to start twice
+ * and so fails the reload cleanly, which is the honest outcome.
+ *
+ * The conversation survives because the id does not change and its truth
+ * is the durable log on disk. The record never moves: a reload is
+ * invisible in it, because nothing the model said or did changes.
+ */
+async function reloadAgent(old, id, input) {
+    // Snapshot BEFORE makeAgent: it overwrites every one of these, so the
+    // old set would be unreachable by the time we needed to dispose it.
+    const oldLoaded = loadedExtensions;
+    const oldBuiltIn = builtInExtensions;
+    const oldUser = userExtensions;
+    const oldProject = projectExtensions;
+    const oldTemps = mergedTempPaths.splice(0);
+    // makeAgent publishes the config side BEFORE it can fail on the model,
+    // so a failure past the extension load would leave a NEW window, model
+    // name and profile table beside the OLD agent — and the failure line
+    // says nothing changed. Rather than soften the line, the snapshot makes
+    // it true: a failed reload is atomic, which is what load-then-swap
+    // promises. (Lead's review of 5bee644, observation 1.)
+    const oldCfg = {
+        // RL-F6: makeAgent publishes this BEFORE createAgent, and createAgent
+        // throws on a tool-name collision — a user extension exposing
+        // `read_file` is enough — so a failure CAN land after it. Left
+        // unrestored, the new array stands beside the old agent, whose config
+        // holds the old one by reference, and the don't-ask-again writer
+        // mutates whatever this is: a rule granted after a failed reload goes
+        // into an array nothing reads. RL-F3's family one level up, and the
+        // same symptom — the human grants a rule and is asked again on the
+        // very next identical call.
+        agentExtensions: currentAgentExtensions,
+        merged: mergedConfig,
+        models: configModels,
+        window: configuredWindow,
+        faux: currentFaux,
+        modelName: currentModelName,
+        choice: modelChoice,
+        agent: agentModel,
+        endpoint: agentBaseUrl,
+        delegation: process.env.KISO_DELEGATION_CONFIG_JSON,
+    };
+    let next;
+    try {
+        next = await makeAgent(id, input, modelChoice);
+    }
+    catch (err) {
+        // Nothing is swapped. Clean up whatever the failed attempt managed
+        // to create, put the old set's own temp paths back so exit still
+        // removes them, and restore the lists in case makeAgent got far
+        // enough to publish new ones.
+        for (const p of mergedTempPaths.splice(0)) {
+            try {
+                rmSync(p, { recursive: true, force: true });
+            }
+            catch {
+                // best-effort — the temp dir would be reaped by the OS
+            }
+        }
+        mergedTempPaths.push(...oldTemps);
+        setExtensionLists(oldBuiltIn, oldUser, oldProject, oldLoaded);
+        setCurrentAgentExtensions(oldCfg.agentExtensions);
+        setMergedConfig(oldCfg.merged);
+        setConfigModels(oldCfg.models);
+        setConfiguredWindow(oldCfg.window);
+        setCurrentFaux(oldCfg.faux);
+        setCurrentModelName(oldCfg.modelName);
+        setModelChoice(oldCfg.choice);
+        setAgentModel(oldCfg.agent, oldCfg.endpoint);
+        if (oldCfg.delegation === undefined)
+            delete process.env.KISO_DELEGATION_CONFIG_JSON;
+        else
+            process.env.KISO_DELEGATION_CONFIG_JSON = oldCfg.delegation;
+        bodyLog(`[reload] ${err instanceof Error ? err.message : String(err)} — nothing changed, the previous set is still in force`);
+        return old;
+    }
+    // The new set is built and sound; only now does the old one go.
+    old.close();
+    await disposeExtensions(oldLoaded);
+    for (const p of oldTemps) {
+        try {
+            rmSync(p, { recursive: true, force: true });
+        }
+        catch {
+            // best-effort — the temp dir would be reaped by the OS
+        }
+    }
+    bodyLog(`[reload] ${loadedExtensions.length} extensions, ${skillCount()} skills — the conversation is unchanged`);
+    return next;
+}
+async function chatLoop(first, firstId, input, autoCompact) {
     let id = firstId;
     let prev = null;
+    let agent = first;
+    // §2.5: a rebuilt agent re-enters on the SAME conversation, so it prints
+    // neither the opening banner nor the "switched — previous" line. The
+    // reload said what it did; repeating the session's opening would read
+    // as a new session, which is the one thing it is not.
+    let rebuilt = false;
     for (;;) {
         const session = await agent.session({ id, ...(acceptDrift() ? { acceptDrift: true } : {}) });
-        if (prev === null) {
+        if (rebuilt) {
+            rebuilt = false;
+        }
+        else if (prev === null) {
             bodyLog(`session ${id}\n`);
             // REL-0152-D5: a session with history says what that history WAS.
             // Resuming used to print this one line and drop you at an empty
@@ -778,11 +994,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 {
@@ -811,6 +1032,11 @@ async function chatLoop(agent, firstId, input, autoCompact) {
         const end = await chat(session, currentFaux, input, autoCompact, nav);
         if (end.next === "exit")
             return;
+        if (end.next === "reload") {
+            agent = await reloadAgent(agent, id, input);
+            rebuilt = true;
+            continue; // the same id, the same conversation, a new agent
+        }
         prev = id;
         id = end.id;
     }
@@ -830,10 +1056,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 +1206,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 +1439,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 +1460,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 +1498,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/state.d.ts

@@ -12,6 +12,14 @@ import type { KisoExtension, StoreRecord } from "@vincemakes/kiso-runtime";
  *  env vars (KISO_EXTENSIONS_DIR / KISO_MCP_CONFIG / KISO_SKILLS_DIR)
  *  still override their own path; nothing hard-codes ~/.kiso anymore. */
 export declare function kisoHome(): string;
+/** DC-49 — the workspace the coding tools may touch, and the one place it
+ *  is decided. The session's own tool set and the `!` command's runner both
+ *  need it, and two copies of a ruling-bearing literal is how a later DC-49
+ *  amendment reaches one caller and not the other. */
+export declare function codingToolOptions(): {
+    readonly workspaceRoot: string;
+    readonly excludeRoots: readonly string[];
+};
 export declare function sessionsDir(): string;
 /** E1: the extension scan directory — KISO_EXTENSIONS_DIR overrides. */
 export declare function extensionsDir(): string;
@@ -77,6 +85,15 @@ export interface LineInput {
     /** W15: the expand key (ctrl+o) — the chain-level action, never the
      *  editor's own interpretation. */
     onExpand(cb: () => void): void;
+    /** §2.3: the thinking key (ctrl+t) — the same chain-level shape as
+     *  onExpand. Optional: the readline input has no such key, and a
+     *  dock-less session has nothing to reprint. */
+    onThink?(cb: () => void): void;
+    /** §2.4: the external-editor key (ctrl+g). */
+    onEditor?(cb: () => void): void;
+    /** §2.4: hand the terminal over, run `edit`, take it back. The editor
+     *  owns the handover; the CLI owns the spawn. */
+    externalEdit?(edit: (text: string) => string | null): void;
     /** E1 §3: the copy key (ctrl+x) — the chain-level action, never the
      *  composer's own. The readline input ignores it; `/copy` is the
      *  route that works everywhere. */
@@ -178,6 +195,24 @@ export declare let configModels: Readonly<Record<string, import("./config.js").M
 export declare function setConfigModels(models: Readonly<Record<string, import("./config.js").ModelProfile>>): void;
 /** The name of the model currently driving the session ("faux" or the
  *  profile name / provider/model write / env model). */
+/**
+ * §2.5 — the profile the human CHOSE by name, and the only source a
+ * rebuild may read for the model.
+ *
+ * Not `currentModelName`: that holds whatever resolution produced, and
+ * an env-resolved session's name ("gpt-4o", "claude-sonnet-5") is not a
+ * key in `models`, so handing it back to `resolveModel` throws. Not the
+ * startup flag either, or a `/model` switch would silently revert on the
+ * first reload — the effort-axis round produced that bug once already
+ * from having two sources for the model.
+ *
+ * One variable, seeded by `makeAgent` from the startup flag and
+ * overwritten by `/model`. Undefined means "resolve exactly as this
+ * process did at startup", which is the right answer for a session that
+ * never named a profile.
+ */
+export declare let modelChoice: string | undefined;
+export declare function setModelChoice(value: string | undefined): void;
 export declare let currentModelName: string;
 export declare function setCurrentModelName(value: string): void;
 /** E1: the extensions loaded by makeAgent — their names feed the banner. */

package/dist/state.js

@@ -18,6 +18,13 @@ import { AT_CAP, AT_SKIP, Dock } from "@vincemakes/kiso-tui";
 export function kisoHome() {
     return process.env.KISO_HOME ?? join(homedir(), ".kiso");
 }
+/** DC-49 — the workspace the coding tools may touch, and the one place it
+ *  is decided. The session's own tool set and the `!` command's runner both
+ *  need it, and two copies of a ruling-bearing literal is how a later DC-49
+ *  amendment reaches one caller and not the other. */
+export function codingToolOptions() {
+    return { workspaceRoot: process.cwd(), excludeRoots: [kisoHome()] };
+}
 export function sessionsDir() {
     return join(kisoHome(), "sessions");
 }
@@ -246,6 +253,26 @@ export function setConfigModels(models) {
 }
 /** The name of the model currently driving the session ("faux" or the
  *  profile name / provider/model write / env model). */
+/**
+ * §2.5 — the profile the human CHOSE by name, and the only source a
+ * rebuild may read for the model.
+ *
+ * Not `currentModelName`: that holds whatever resolution produced, and
+ * an env-resolved session's name ("gpt-4o", "claude-sonnet-5") is not a
+ * key in `models`, so handing it back to `resolveModel` throws. Not the
+ * startup flag either, or a `/model` switch would silently revert on the
+ * first reload — the effort-axis round produced that bug once already
+ * from having two sources for the model.
+ *
+ * One variable, seeded by `makeAgent` from the startup flag and
+ * overwritten by `/model`. Undefined means "resolve exactly as this
+ * process did at startup", which is the right answer for a session that
+ * never named a profile.
+ */
+export let modelChoice;
+export function setModelChoice(value) {
+    modelChoice = value;
+}
 export let currentModelName = "faux";
 export function setCurrentModelName(value) {
     currentModelName = value;