@vincemakes/kiso-code 0.14.0 → 0.15.0

package/README.md

@@ -1,9 +1,54 @@
 # @vincemakes/kiso-code
 
-The coding-agent reference product: kiso chat / kiso resume / kiso
-sessions. Install it or run directly with npx @vincemakes/kiso-code. Keyless faux
-mode out of the box; ANTHROPIC_API_KEY or OPENAI_API_KEY + OPENAI_BASE_URL
-switch to real providers.
+The coding agent that survives kill -9: durable sessions (append-only
+JSONL), pre-effect approvals, and honest recovery — an interrupted side
+effect is surfaced and asked about, never silently re-run.
 
-Requires Node >= 22. See the repository README for the framework
-overview.
+## Install and first session
+
+```sh
+npm install -g @vincemakes/kiso-code
+kiso                    # or: npx @vincemakes/kiso-code
+```
+
+With no key set you get **faux mode** — a scripted four-round demo of
+the full CLI (tools, approvals, sessions), zero keys. When the script
+runs out (about two user turns) the session exits with a set-a-key
+message; that exit is the design, not a crash.
+
+## A real model
+
+```sh
+# OpenAI-compatible (checked first; the key alone talks to OpenAI —
+# OPENAI_BASE_URL optionally retargets DeepSeek or any compat endpoint):
+export OPENAI_API_KEY=...      # OPENAI_MODEL (default gpt-4o)
+
+# or Anthropic:
+export ANTHROPIC_API_KEY=...   # ANTHROPIC_MODEL (default claude-sonnet-5)
+
+kiso
+```
+
+Named model profiles live in `~/.kiso/config.json` (the config stores
+the NAME of the env var holding each key, never the key itself); switch
+in-session with `/model`. Approval tiers: `--mode
+manual|default|accept-edits|plan|bypass` or `/mode` in-session.
+
+## The commands
+
+```text
+kiso [sessionId]             interactive session (default command)
+kiso resume                  pick a session to continue (TTY picker)
+kiso resume <id> ["prompt"]  continue a session, one-shot
+kiso sessions                list durable sessions
+kiso help                    usage + configuration reference
+```
+
+Sessions live under `~/.kiso/sessions`; kill the process — `kill -9`
+included — and `kiso resume` continues exactly where the log ends.
+
+**Platforms:** macOS / Linux (Node ≥ 22). Windows is unsupported.
+
+Full documentation — extensions (MCP, skills, subagents), the approval
+model, session recovery, configuration reference — in the
+[repository README](https://github.com/vincemakes/kiso#readme).

package/dist/chat.d.ts

@@ -76,7 +76,7 @@ export interface UsageDelta {
  * absent provider resolves like the tracer's "adapter" identity — the
  * total convention (INPUT_CONVENTIONS), never a crash.
  */
-export declare function usageFromEvent(route: string | undefined, ev: import("@vincemakes/kiso-core").Usage, prevTotal: number | null): UsageDelta;
+export declare function usageFromEvent(route: string | undefined, ev: import("@vincemakes/kiso-core").Usage, prevTotal: number | null, model?: string): UsageDelta;
 /** v2b: the spinner merged into the STATUS BAR (the v2a standalone glyph
  *  is gone) — docked only, 200ms rotation between the request and the
  *  first event. */

package/dist/chat.js

@@ -9,8 +9,10 @@ import { escapeTerminal, cacheHitPct, idleStatus, palette, renderEvent, renderRe
 import { deletionRiskHint, editFileDiff, writeFileDiff } from "@vincemakes/kiso-tui";
 import { canonicalTargetPath, shellProgressPath } from "@vincemakes/kiso-tools-node";
 import { canonicalizeUsage } from "@vincemakes/kiso-runtime";
+import { canonicalizeUsageForModel } from "@vincemakes/kiso-runtime/internal";
 import { dispatch } from "./dispatch.js";
 import { agentModel, body, bodyLog, configuredWindow, dock } from "./state.js";
+import { lookupModelMetadata } from "@vincemakes/kiso-runtime/internal";
 import { addDontAskAgainRule, askPanel, fixHintFor, pendingAsk, resolveUncertains } from "./trust-ui.js";
 import { FauxExhaustionError, failOnFauxExhaustion } from "./faux-glue.js";
 import { MODES, getMode, setMode } from "./mode.js";
@@ -37,7 +39,18 @@ export function contextWindowTokens() {
     if (windowOverride !== undefined)
         return windowOverride;
     const window = Number.parseInt(process.env.KISO_CONTEXT_WINDOW ?? "", 10);
-    return Number.isFinite(window) && window > 0 ? window : DEFAULT_CONTEXT_WINDOW;
+    if (Number.isFinite(window) && window > 0)
+        return window;
+    // PH-1c (finding PH-F15): the window follows the LIVE model when the
+    // metadata registry knows it — /model to a known model moves the
+    // window (and the microcompact threshold derived from it) without an
+    // env var. agentModel is the same live binding the status row shows;
+    // an unknown model keeps the 200k default — the registry never
+    // guesses, so neither do we.
+    const known = lookupModelMetadata(agentModel)?.capabilities.contextWindow;
+    if (known !== undefined && known !== null)
+        return known;
+    return DEFAULT_CONTEXT_WINDOW;
 }
 /**
  * B area: approximate context ratio — chars/4 of the projected messages vs
@@ -78,8 +91,13 @@ const CACHE_MISS_FLOOR = 1024;
  * absent provider resolves like the tracer's "adapter" identity — the
  * total convention (INPUT_CONVENTIONS), never a crash.
  */
-export function usageFromEvent(route, ev, prevTotal) {
-    const c = canonicalizeUsage(route ?? "adapter", ev);
+export function usageFromEvent(route, ev, prevTotal, 
+// PH-1c: the LIVE model — when given, the $cost keys on the model's
+// metadata entry (an unpriced model shows null, never a route-table
+// guess); omitted, the legacy route-keyed path stands (old callers,
+// old tests, unchanged bytes).
+model) {
+    const c = model === undefined ? canonicalizeUsage(route ?? "adapter", ev) : canonicalizeUsageForModel(model, undefined, route ?? "adapter", ev);
     const total = c.input + c.cacheRead + (c.cacheWrite ?? 0);
     let missed = null;
     // R-C item 4: min(prevTotal, total) is the part that could have been
@@ -596,7 +614,7 @@ submitTurn) {
                     body.textEnd();
                     break;
                 case "usage": {
-                    const delta = usageFromEvent(session.provider, ev, prevTotal);
+                    const delta = usageFromEvent(session.provider, ev, prevTotal, agentModel);
                     usage = delta.usage;
                     prevTotal = delta.total;
                     missed = delta.missed;

package/dist/config.d.ts

@@ -32,8 +32,15 @@ export interface ModelProfile {
     readonly kind: ProfileKind;
     readonly baseUrl?: string;
     readonly model: string;
-    /** The env var NAME holding the key — never the key itself. */
-    readonly apiKeyEnv: string;
+    /** The env var NAME holding the key — never the key itself.
+     *  PH-1c (finding PH-F19): OPTIONAL — an absent apiKeyEnv means an
+     *  unauthenticated endpoint (a local Ollama, a LAN proxy); the
+     *  adapter receives a placeholder key, and the profile no longer
+     *  demands a dummy env var to exist. */
+    readonly apiKeyEnv?: string;
+    /** PH-1c.1: opt-in Anthropic prompt caching for this profile —
+     *  default off (a request-byte cost behavior never flips silently). */
+    readonly promptCaching?: boolean;
 }
 export interface AutoCompactConfig {
     readonly thresholdRatio: number;

package/dist/config.js

@@ -68,15 +68,18 @@ export function parseConfig(text, source) {
                 fail(`models.${name}.kind`, `expected one of ${KINDS.join(", ")}`);
             if (typeof p.model !== "string" || p.model === "")
                 fail(`models.${name}.model`, "expected a model string");
-            if (typeof p.apiKeyEnv !== "string" || p.apiKeyEnv === "")
-                fail(`models.${name}.apiKeyEnv`, "expected an env var name (the config never stores keys)");
+            if (p.apiKeyEnv !== undefined && (typeof p.apiKeyEnv !== "string" || p.apiKeyEnv === ""))
+                fail(`models.${name}.apiKeyEnv`, "expected an env var name (the config never stores keys); omit it entirely for an unauthenticated local endpoint");
             if (p.baseUrl !== undefined && typeof p.baseUrl !== "string")
                 fail(`models.${name}.baseUrl`, "expected a string");
+            if (p.promptCaching !== undefined && typeof p.promptCaching !== "boolean")
+                fail(`models.${name}.promptCaching`, "expected a boolean");
             models[name] = {
                 kind: p.kind,
                 model: p.model,
-                apiKeyEnv: p.apiKeyEnv,
+                ...(typeof p.apiKeyEnv === "string" ? { apiKeyEnv: p.apiKeyEnv } : {}),
                 ...(typeof p.baseUrl === "string" ? { baseUrl: p.baseUrl } : {}),
+                ...(typeof p.promptCaching === "boolean" ? { promptCaching: p.promptCaching } : {}),
             };
         }
         out.models = models;
@@ -151,7 +154,9 @@ export function mergeConfigs(user, project) {
 }
 /** A profile is available when its apiKeyEnv var is set (the key exists). */
 export function profileAvailable(p) {
-    return process.env[p.apiKeyEnv] !== undefined;
+    // PH-1c (finding PH-F19): a keyless profile (no apiKeyEnv) is an
+    // unauthenticated endpoint — always available.
+    return p.apiKeyEnv === undefined || process.env[p.apiKeyEnv] !== undefined;
 }
 /** "provider/model" direct write → a profile. */
 export function directWriteProfile(value) {
@@ -205,6 +210,9 @@ export function resolveModel(modelFlag, merged) {
                 kind: "anthropic",
                 model: process.env.ANTHROPIC_MODEL ?? "claude-sonnet-5",
                 apiKeyEnv: "ANTHROPIC_API_KEY",
+                // PH-1c (finding PH-F19): symmetric with OPENAI_BASE_URL —
+                // proxies and compat gateways serve the anthropic dialect too.
+                ...(process.env.ANTHROPIC_BASE_URL !== undefined ? { baseUrl: process.env.ANTHROPIC_BASE_URL } : {}),
             },
             apiKey: process.env.ANTHROPIC_API_KEY,
         };
@@ -226,7 +234,9 @@ function resolveProfile(name, p) {
     if (!profileAvailable(p)) {
         throw new ConfigError(`model ${name}: unavailable — the env var ${p.apiKeyEnv} is not set (configs never store keys, only the env-var name)`);
     }
-    return { name, profile: p, apiKey: process.env[p.apiKeyEnv] };
+    // PH-1c (finding PH-F19): a keyless profile hands the adapter a
+    // placeholder — the SDKs require SOME string; the endpoint ignores it.
+    return { name, profile: p, apiKey: p.apiKeyEnv === undefined ? "none" : process.env[p.apiKeyEnv] };
 }
 /** Mode: env (KISO_MODE) beats config.mode; the --mode flag is applied by
  *  main before this runs (flags are the top of the chain). */

package/dist/dispatch.js

@@ -193,7 +193,11 @@ export function dispatch(line, ctx) {
                             const marks = [`profile: ${name}`, ...(profileAvailable(profile) ? [] : ["unavailable"]), ...(profile.model === agentModel ? ["current"] : [])];
                             return { label: `${profile.kind}/${profile.model}`, note: marks.join(" · ") };
                         }),
-                        typeHint: names.length === 0 ? "type provider/model directly (e.g. openai/deepseek-reasoner)" : "type provider/model directly",
+                        // PH-1a (finding PH-F4): the example must be a syntax
+                        // directWriteProfile actually ACCEPTS — the old
+                        // "openai/…" hint failed with "no such model profile"
+                        // on exactly the fresh-install path that shows it.
+                        typeHint: names.length === 0 ? "type provider/model directly (e.g. openai-compat/deepseek-reasoner)" : "type provider/model directly",
                         // the zero-profile copy is TODAY'S, verbatim: the
                         // user who sees it is exactly the user who needs
                         // the path spelled out
@@ -233,10 +237,19 @@ export function dispatch(line, ctx) {
                     }
                     else {
                         const adapter = await buildAdapter(profile.kind, {
-                            apiKey: process.env[profile.apiKeyEnv],
+                            // PH-1c (PH-F19): a keyless profile = an unauthenticated
+                            // endpoint — the placeholder satisfies the SDK's ctor.
+                            apiKey: profile.apiKeyEnv === undefined ? "none" : process.env[profile.apiKeyEnv],
                             ...(profile.baseUrl !== undefined ? { baseUrl: profile.baseUrl } : {}),
+                            ...(profile.promptCaching !== undefined ? { promptCaching: profile.promptCaching } : {}),
                         });
-                        ctx.session.setAdapter(adapter);
+                        // PH-1a (finding PH-F8, P0): the switch is ATOMIC —
+                        // adapter, model id, and provider route move together.
+                        // setAdapter alone left the session's frozen config
+                        // carrying the OLD model, so the status row claimed the
+                        // new model while every request still sent the old id
+                        // (and usage canonicalized under the old route).
+                        ctx.session.setModelBinding({ adapter, model: profile.model, provider: profile.kind });
                         setAgentModel(profile.model);
                         setCurrentModelName(arg);
                         body.notice(`model → ${arg} (${profile.model}) — takes effect on the next turn`);
@@ -336,9 +349,38 @@ export function dispatch(line, ctx) {
         return;
     }
     if (trimmed === "exit" || trimmed === "") {
+        // PH-1a (finding PH-F11): closing the input MID-RUN killed the very
+        // surface a later approval would ask through ("readline was
+        // closed", the v2b-era edge). On the DOCKED interactive surface the
+        // close now queues on the chain — the run finishes (approvals and
+        // all), then the REPL exits. DOCK-GATED on purpose: the pipe path
+        // is byte-pinned (a notice there would corrupt machine-read
+        // streams), a pipe's "exit" always arrives mid-run, and the
+        // approval panel the fix protects only exists on the dock. An idle
+        // exit is immediate, byte-for-byte as before, on every surface.
+        if (ctx.isRunning() && dock.active) {
+            if (trimmed === "exit")
+                body.notice("[exit queued — closing after the current run completes]");
+            ctx.chainRef.current = ctx.chainRef.current.then(async () => {
+                ctx.input.close();
+            });
+            return;
+        }
         ctx.input.close();
         return;
     }
+    // PH-1a (finding PH-F1): an unrecognized slash command is an ERROR,
+    // never a turn — the fallthrough used to hand "/clear", "/exit", or a
+    // typo to the model, burning a request on text the user meant as a
+    // command. A multi-line paste that merely begins with "/" is prose and
+    // still submits.
+    if (trimmed.startsWith("/") && !trimmed.includes("\n")) {
+        ctx.chainRef.current = ctx.chainRef.current.then(async () => {
+            bodyLog(`unknown command: ${escapeTerminal(trimmed.split(" ")[0] ?? trimmed)} — /help lists the commands`);
+            ctx.input.prompt();
+        });
+        return;
+    }
     // v2c: a turn submitted while another runs waits on the chain — the
     // live count rides the status bar (+N queued).
     ctx.submitTurn(line);

package/dist/index.d.ts

@@ -6,9 +6,10 @@
  *   kiso resume <sessionId> continue a session in one-shot mode
  *   kiso sessions           list durable sessions
  *
- * Provider selection (first match):
+ * Provider selection (first match — PH-1b corrected this header: the
+ * code has always checked OPENAI first, config.ts resolveModel):
+ *   OPENAI_API_KEY         → OpenAI-compatible (OPENAI_MODEL default gpt-4o, OPENAI_BASE_URL)
  *   ANTHROPIC_API_KEY      → Anthropic (ANTHROPIC_MODEL, default claude-sonnet-5)
- *   OPENAI_API_KEY         → OpenAI-compatible (OPENAI_MODEL, OPENAI_BASE_URL)
  *   neither                → faux mode: scripted model, zero keys, full CLI
  *
  * Sessions live under $KISO_HOME/sessions (default ~/.kiso/sessions) as

package/dist/index.js

@@ -6,9 +6,10 @@
  *   kiso resume <sessionId> continue a session in one-shot mode
  *   kiso sessions           list durable sessions
  *
- * Provider selection (first match):
+ * Provider selection (first match — PH-1b corrected this header: the
+ * code has always checked OPENAI first, config.ts resolveModel):
+ *   OPENAI_API_KEY         → OpenAI-compatible (OPENAI_MODEL default gpt-4o, OPENAI_BASE_URL)
  *   ANTHROPIC_API_KEY      → Anthropic (ANTHROPIC_MODEL, default claude-sonnet-5)
- *   OPENAI_API_KEY         → OpenAI-compatible (OPENAI_MODEL, OPENAI_BASE_URL)
  *   neither                → faux mode: scripted model, zero keys, full CLI
  *
  * Sessions live under $KISO_HOME/sessions (default ~/.kiso/sessions) as
@@ -26,7 +27,7 @@ import { readFileSync, realpathSync, rmSync } from "node:fs";
 import { createInterface } from "node:readline";
 import { fileURLToPath } from "node:url";
 import { join } from "node:path";
-import { Body, Editor, bannerLines, escapeTerminal, extensionsBannerText, idColumn, idleStatus, interactivePrompt, palette, renderSessionLine, sessionListFooter, sessionListRow } from "@vincemakes/kiso-tui";
+import { BADGE_GLYPH, Body, Editor, bannerLines, 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";
@@ -39,7 +40,7 @@ import { fauxSkip, readFauxScript } from "./faux-glue.js";
 import { autoCompactFromEnv, chat, contextWindowTokens, estimateCtxRatio } from "./chat.js";
 import { loadProjectConfig, loadUserConfig, mergeConfigs, resolveAutoCompact, resolveContextWindow, resolveModel } from "./config.js";
 import { resume } from "./resume.js";
-import { collectSessionCards } from "./session-cards.js";
+import { collectSessionCards, projectSessionCard } from "./session-cards.js";
 // The moved exports stay reachable from this entry — the test imports
 // (project-trust, coding-agent) never change (B4: zero assertion changes).
 export { applyProjectMerges } from "./trust-ui.js";
@@ -116,6 +117,22 @@ function readlineInput(rl) {
         closed: new Promise((resolve) => rl.on("close", () => resolve())),
     };
 }
+/* PH-1a (findings PH-F6/PH-F10, the exit-wedge dossier — recorded, NOT
+ * fixed here): node keeps TTY fds in blocking mode, macOS pty output
+ * buffers are ~1KB, and on an UNREAD terminal a departing process can
+ * wedge two ways: (a) process.exit's own flush of pending blocking-TTY
+ * writes, and (b) the editor teardown's uv_tty_set_mode → tcsetattr
+ * (TCSADRAIN), which waits for that same drain inside an ioctl. Both are
+ * pre-existing and both are masked by the DEFAULT SIGTERM/SIGHUP
+ * disposition (kernel-level death cuts through a parked loop). Two
+ * repairs were built and REVERTED on evidence this round: a JS signal
+ * handler (a caught signal needs the loop the wedge just parked — see
+ * the tcsetattr ruling at main's handler comment) and a
+ * setBlocking(false)-at-exit rule (a non-blocking TTY plus an immediate
+ * process.exit DROPS the queued tail — the banner's version line and the
+ * dock's CSI r vanished; node made TTYs blocking precisely to prevent
+ * that truncation, and that choice is load-bearing). A real fix needs a
+ * non-draining native restore path — the PH-F6 mini-spec. */
 /** The v2c TTY path: the editor's events map 1:1 onto the interface; the
  *  input row renders on every state change (the CLI's onRender wiring). */
 function editorInput(editor) {
@@ -245,14 +262,32 @@ function extensionsBanner(resume = []) {
  *  first, the CURRENT session excluded (it is not something to pick back
  *  up). Every field already exists behind the store's SessionMeta (the
  *  `kiso sessions` line shows the same data) — only the projection and
- *  the sort live here. */
-function recentSessions(id, agent) {
-    return agent
+ *  the sort live here.
+ *
+ *  TT-1B (W5 unification): each row carries the picker's badge glyph,
+ *  derived through the SAME projection the picker uses (session-cards —
+ *  one source of truth about durability; a second derivation would be
+ *  none). Only the 3 chosen sessions are opened — the read-only listing
+ *  rule holds (projectSessionCard's own guarantee), and the cost is
+ *  bounded by the list, never the home. */
+async function recentSessions(id, agent) {
+    const picked = agent
         .sessions()
         .filter((m) => m.id !== id)
         .sort((a, b) => b.updatedAt - a.updatedAt)
-        .slice(0, 3)
-        .map(({ title, events, runs, updatedAt }) => ({ title, events, runs, updatedAt }));
+        .slice(0, 3);
+    const store = sessionStoreRef;
+    const out = [];
+    for (const m of picked) {
+        let badge;
+        if (store !== null) {
+            const session = await agent.session({ id: m.id });
+            const card = projectSessionCard({ id: m.id, updatedAt: m.updatedAt, records: store.load(m.id), asks: session.pendingApprovals().length });
+            badge = BADGE_GLYPH[card.badge];
+        }
+        out.push({ title: m.title, events: m.events, runs: m.runs, updatedAt: m.updatedAt, ...(badge === undefined ? {} : { badge }) });
+    }
+    return out;
 }
 /**
  * A area: the coding-agent system prompt — ONE constant, byte-stable for the
@@ -452,6 +487,7 @@ async function makeAgent(sessionId, input, modelFlag) {
                 provider: resolved.profile.kind,
                 apiKey: resolved.apiKey,
                 ...(resolved.profile.baseUrl !== undefined ? { baseUrl: resolved.profile.baseUrl } : {}),
+                ...(resolved.profile.promptCaching !== undefined ? { promptCaching: resolved.profile.promptCaching } : {}),
             }
             : { adapter: createFauxProvider(readFauxScript().slice(fauxSkipTurns)) }),
     };
@@ -488,9 +524,12 @@ async function pickSession(agent, input) {
     }
     // a dock-less TTY (rows < 4) has no band to draw the picker in, so the
     // honest answer is the usage line this command has always printed.
+    // PH-1a (finding PH-F12): thrown, never process.exit'd from this depth
+    // — the old exit(2) skipped main's finally (dock.exit, agent.close,
+    // temp cleanup) and could leave the scroll region and lock residue
+    // behind. The entry catch translates the error back to exit code 2.
     if (input.pick === undefined || !dock.active) {
-        console.error('usage: kiso resume <sessionId> ["prompt"]');
-        process.exit(2);
+        throw new CliUsageError('usage: kiso resume <sessionId> ["prompt"]');
     }
     dock.setStatus("", PICKER_HINT);
     const picked = await new Promise((resolve) => {
@@ -525,6 +564,12 @@ function paintBootStatus(session) {
         return;
     dock.setStatus(idleStatus(getMode() === "plan" ? "plan (read-only)" : getMode(), agentModel, estimateCtxRatio(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)
+ *  and the entry catch exits with the historical code 2. */
+class CliUsageError extends Error {
+    exitCode = 2;
+}
 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
@@ -539,6 +584,20 @@ async function main() {
     // first makeAgent (the tier extensions read `current` live). The flag
     // is stripped from the positional args, so it works in any position.
     const args = process.argv.slice(2);
+    // PH-1a (finding PH-F2): --help/-h/--version/-v are FLAGS, not session
+    // ids. They used to fall through the default case and START A SESSION
+    // literally named "--help" (writing ~/.kiso/sessions/--help.jsonl) —
+    // the single highest-frequency new-user gesture, failing silently and
+    // destructively. Checked FIRST, before any other flag parsing, so
+    // `kiso --help` never trips the --model usage error either.
+    if (args.some((a) => a === "--help" || a === "-h")) {
+        args.length = 0;
+        args.push("help");
+    }
+    else if (args.some((a) => a === "--version" || a === "-v")) {
+        console.log(VERSION);
+        return;
+    }
     // merge round B: --model <profile|provider/model> — the top of the model
     // precedence chain; the value flows into makeAgent's config resolution.
     let modelFlag;
@@ -579,6 +638,21 @@ async function main() {
     // readline elsewhere. The trust question, chat, and resume all read
     // through it; main's finally closes it on every exit path.
     const input = makeLineInput();
+    // PH-1a (finding PH-F6, RESOLVED AS WON'T-FIX-IN-JS — the tcsetattr
+    // ruling): SIGTERM/SIGHUP deliberately keep their DEFAULT disposition.
+    // A JS handler that restored the terminal was built and then reverted
+    // on hard evidence: libuv's uv_tty_set_mode calls tcsetattr with
+    // TCSADRAIN, which WAITS for the pty's pending output to drain — on an
+    // unread terminal (exactly where signals tend to arrive) the editor's
+    // teardown parks the event loop in that ioctl forever, and a CAUGHT
+    // signal can only be dispatched by the loop it just parked. Catching
+    // the signal therefore converts kernel-guaranteed death into a death
+    // that may never happen — strictly worse than a dirty terminal. The
+    // default disposition keeps SIGTERM/SIGHUP lethal under every state;
+    // a signal death leaves raw mode/mouse on and `reset` is the fix (the
+    // same contract kill -9 has always had). A safe restore needs a
+    // non-draining native path (bytes-only restore, or tcflush-then-set)
+    // — its own mini-spec, not a hotfix.
     // v2d: the body renderer — active only where the dock is (a color
     // TTY with a real size); pipes run it in passthrough, byte-for-byte.
     setBody(new Body({
@@ -608,7 +682,7 @@ async function main() {
                 applyConfigMode();
                 const session = await agent.session({ id });
                 bodyLog(`session ${id}\n`);
-                extensionsBanner(recentSessions(id, agent));
+                extensionsBanner(await recentSessions(id, agent));
                 faux = currentFaux;
                 paintBootStatus(session); // TUI2-R2 ⑥: the idle-fresh screen says what it is
                 await chat(session, faux, input, resolveAutoCompact(mergedConfig));
@@ -683,14 +757,29 @@ async function main() {
                 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
+                // stopped, so a new user could never learn from the tool
+                // itself how to hand it a key.
                 const p = palette();
                 console.log(`${p.dim}${bannerLines(80, process.stdout.rows ?? 0, VERSION, "").join("\n")}${p.reset}\n\n` +
                     "kiso — the coding agent that survives kill -9\n\n" +
                     "  kiso [sessionId]         interactive session (default command)\n" +
                     "  kiso chat [sessionId]    same as above\n" +
+                    "  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 help               this help\n");
+                    "  kiso help               this help\n\n" +
+                    "flags (any position):\n" +
+                    "  --model <profile|provider/model>   pick the model (also /model in-session)\n" +
+                    "  --mode <tier>            approval tier: manual|default|accept-edits|plan|bypass\n" +
+                    "  --version                print the version\n\n" +
+                    "configuration:\n" +
+                    "  no key                   keyless faux demo (a scripted four-round session)\n" +
+                    "  OPENAI_API_KEY           OpenAI-compatible (OPENAI_MODEL, default gpt-4o;\n" +
+                    "                           OPENAI_BASE_URL for DeepSeek/compat endpoints) — checked first\n" +
+                    "  ANTHROPIC_API_KEY        Anthropic (ANTHROPIC_MODEL, default claude-sonnet-5)\n" +
+                    "  ~/.kiso/config.json      named model profiles (keys stay in env vars; see the README)\n");
                 break;
             }
             case undefined:
@@ -708,7 +797,7 @@ async function main() {
                 agent = await makeAgent(id, input, modelFlag);
                 const session = await agent.session({ id });
                 bodyLog(`session ${id}\n`);
-                extensionsBanner(recentSessions(id, agent));
+                extensionsBanner(await recentSessions(id, agent));
                 // finding E4-1: the same faux resolution the chat/resume cases
                 // carry (faux = currentFaux) — pre-patch the initial faux=true
                 // was passed here, so ANY provider failure in a bare-command
@@ -756,9 +845,31 @@ async function main() {
 // test imported src/index.js for its functions (harmless before the
 // first-run scaffold existed; the scaffold WRITES the home). The bin is
 // a symlink, so argv[1] is realpathed before the comparison.
+/** PH-1a (finding PH-F10): the explicit exit stays (v2a: natural drain is
+ *  racy on a TTY — readline leaves the stdio handles active), but on a
+ *  PIPE it now waits for both stdio streams to flush first — process.exit
+ *  does not drain a pipe's pending async writes, so `kiso sessions | head`
+ *  could lose its tail. TTY-GATED on purpose: a pipe's flush callbacks
+ *  always settle (the reader drains, or the break surfaces as EPIPE), but
+ *  an unread TTY's never do — waiting there would trade a truncation bug
+ *  for a hang (the exit-wedge dossier above editorInput). The TTY path keeps the
+ *  v2a immediate exit, byte-for-byte. */
+function exitFlushed(code) {
+    if (process.stdout.isTTY === true) {
+        process.exit(code);
+    }
+    let pending = 2;
+    const done = () => {
+        pending -= 1;
+        if (pending === 0)
+            process.exit(code);
+    };
+    process.stdout.write("", done);
+    process.stderr.write("", done);
+}
 if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === fileURLToPath(import.meta.url)) {
     main()
-        .then(() => process.exit(0))
+        .then(() => exitFlushed(0))
         .catch((err) => {
         // round 10: top-level errors are terminal-escaped. v2a: the exit is EXPLICIT
         // — natural drain is racy on a TTY (readline leaves the stdio handles
@@ -766,6 +877,6 @@ if (process.argv[1] !== undefined && realpathSync(process.argv[1]) === fileURLTo
         // ran (agent.close, dispose, temp cleanup) — nothing is skipped, no
         // lock is left behind; the exit code is honest.
         console.error(escapeTerminal(err instanceof Error ? err.message : String(err)));
-        process.exit(1);
+        exitFlushed(err instanceof CliUsageError ? err.exitCode : 1);
     });
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vincemakes/kiso-code",
-  "version": "0.14.0",
+  "version": "0.15.0",
   "description": "kiso CLI — the durable coding agent that survives kill -9: kiso chat / kiso resume / kiso sessions.",
   "type": "module",
   "license": "MIT",
@@ -18,19 +18,19 @@
     "test": "vitest run"
   },
   "dependencies": {
-    "@vincemakes/kiso-ask-ext": "0.14.0",
-    "@vincemakes/kiso-core": "0.14.0",
-    "@vincemakes/kiso-evals": "0.14.0",
-    "@vincemakes/kiso-mcp-ext": "0.14.0",
-    "@vincemakes/kiso-provider-anthropic": "0.14.0",
-    "@vincemakes/kiso-provider-openai": "0.14.0",
-    "@vincemakes/kiso-runtime": "0.14.0",
-    "@vincemakes/kiso-skills-ext": "0.14.0",
-    "@vincemakes/kiso-subagent-ext": "0.14.0",
-    "@vincemakes/kiso-task-ext": "0.14.0",
-    "@vincemakes/kiso-tools-node": "0.14.0",
-    "@vincemakes/kiso-tui": "0.14.0",
-    "@vincemakes/kiso-tui-cells": "0.14.0"
+    "@vincemakes/kiso-ask-ext": "0.15.0",
+    "@vincemakes/kiso-core": "0.15.0",
+    "@vincemakes/kiso-evals": "0.15.0",
+    "@vincemakes/kiso-mcp-ext": "0.15.0",
+    "@vincemakes/kiso-provider-anthropic": "0.15.0",
+    "@vincemakes/kiso-provider-openai": "0.15.0",
+    "@vincemakes/kiso-runtime": "0.15.0",
+    "@vincemakes/kiso-skills-ext": "0.15.0",
+    "@vincemakes/kiso-subagent-ext": "0.15.0",
+    "@vincemakes/kiso-task-ext": "0.15.0",
+    "@vincemakes/kiso-tools-node": "0.15.0",
+    "@vincemakes/kiso-tui": "0.15.0",
+    "@vincemakes/kiso-tui-cells": "0.15.0"
   },
   "devDependencies": {
     "@types/node": "^26.1.2",
@@ -40,6 +40,10 @@
   "engines": {
     "node": ">=22"
   },
+  "os": [
+    "darwin",
+    "linux"
+  ],
   "repository": {
     "type": "git",
     "url": "https://github.com/vincemakes/kiso.git",