wotann 0.5.93 → 0.5.95

package/dist/security/skills-guard.js

@@ -7,9 +7,13 @@
  * escalation, agent config persistence, hardcoded secrets, and invisible text.
  */
 import { createHash } from "node:crypto";
-import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync, } from "node:fs";
+import { existsSync, lstatSync, readFileSync, readdirSync, realpathSync } from "node:fs";
 import { extname, isAbsolute, join, relative, resolve } from "node:path";
-export const TRUSTED_SKILL_REPOS = new Set(["openai/skills", "anthropics/skills", "huggingface/skills"]);
+export const TRUSTED_SKILL_REPOS = new Set([
+    "openai/skills",
+    "anthropics/skills",
+    "huggingface/skills",
+]);
 export const INSTALL_POLICY = {
     builtin: ["allow", "allow", "allow"],
     trusted: ["allow", "allow", "block"],
@@ -405,7 +409,14 @@ export function contentHash(path) {
     return `sha256:${h.digest("hex").slice(0, 16)}`;
 }
 function p(pattern, patternId, severity, category, description, recommendation) {
-    return { regex: new RegExp(pattern, "i"), patternId, severity, category, description, recommendation };
+    return {
+        regex: new RegExp(pattern, "i"),
+        patternId,
+        severity,
+        category,
+        description,
+        recommendation,
+    };
 }
 function buildScanResult(input) {
     const issues = deduplicateIssues(input.findings);
@@ -489,7 +500,17 @@ function checkStructure(skillDir) {
     return findings;
 }
 function structuralIssue(patternId, severity, category, file, match, description, recommendation) {
-    return { pattern: category, patternId, category, file, line: 0, match, severity, description, recommendation };
+    return {
+        pattern: category,
+        patternId,
+        category,
+        file,
+        line: 0,
+        match,
+        severity,
+        description,
+        recommendation,
+    };
 }
 function listFiles(root) {
     return listEntries(root).filter((entry) => {
@@ -524,7 +545,7 @@ function isInside(child, parent) {
 function worstSeverity(issues) {
     if (issues.length === 0)
         return "info";
-    return issues.reduce((worst, issue) => (SEVERITY_ORDER[issue.severity] < SEVERITY_ORDER[worst] ? issue.severity : worst), "info");
+    return issues.reduce((worst, issue) => SEVERITY_ORDER[issue.severity] < SEVERITY_ORDER[worst] ? issue.severity : worst, "info");
 }
 function compareIssueSeverity(a, b) {
     return SEVERITY_ORDER[a.severity] - SEVERITY_ORDER[b.severity];

package/dist/ui/components/v3/AppV3.d.ts

@@ -42,6 +42,7 @@ import React from "react";
 import type { AgentMessage, ProviderName, ProviderStatus } from "../../../core/types.js";
 import type { WotannRuntime } from "../../../core/runtime.js";
 import { type CapabilityProfile } from "../../capability-tier.js";
+import { type TranscriptMessageV3 } from "./Transcript.js";
 export interface AppV3Props {
     readonly version: string;
     readonly providers: readonly ProviderStatus[];
@@ -87,4 +88,23 @@ export interface AppV3Props {
      */
     readonly snippetDbPathOverride?: string;
 }
+/**
+ * Map an AgentMessage onto a v3 TranscriptMessage, PRESERVING each
+ * message's stable id. AgentMessage.id is assigned at creation (see
+ * makeMessageId / the assistant `assistantId`); we fall back to a
+ * positional id only for legacy messages that predate id assignment.
+ *
+ * Why a stable, non-positional id matters: it is the prerequisite for
+ * the Ink <Static> committed-history split (P1). <Static> keys items
+ * by identity to decide which rows it has ALREADY emitted, so a
+ * positional id would make it mis-detect new rows the moment a message
+ * is inserted mid-array. Preserving the message's own id also lets the
+ * assistant row keep one identity across its streamed deltas.
+ *
+ * Role coercion: AgentMessage's role is a wider union than v3's
+ * TranscriptRole. The runtime mostly emits `user`/`assistant`; anything
+ * else (e.g. `developer`) falls back to `system` so the row still
+ * renders without a missing-style crash.
+ */
+export declare function toTranscriptMessages(messages: readonly AgentMessage[]): readonly TranscriptMessageV3[];
 export declare function AppV3({ version: _version, providers, initialModel, initialProvider, initialMessages, runtime, profileOverride, columnsOverride, rowsOverride, uiStatePathOverride, statuslineConfigPathOverride, layoutConfigPathOverride, snippetDbPathOverride, }: AppV3Props): React.ReactElement;

package/dist/ui/components/v3/AppV3.js

@@ -46,6 +46,7 @@ import { buildAgentToolContext } from "../../../core/agent-tool-context.js";
 import { AGENT_TOOL_DEFINITIONS, executeAgentTool } from "../../../tools/agent-tools.js";
 import { ThemeProvider, useThemeTone } from "../../theme/context.js";
 import { PALETTES, ThemeManager } from "../../themes.js";
+import { unhandledCommandReason } from "../../help-registry.js";
 import { detectCapabilityProfile } from "../../capability-tier.js";
 import { detectTerminalCapabilities } from "../../terminal-capabilities.js";
 import { extractImageAttachmentsFromPaste, } from "../../image-attachments.js";
@@ -81,29 +82,49 @@ import { formatSlashResultMessage } from "./SystemMessageCard.js";
 import { resolveWotannHomeSubdir } from "../../../utils/wotann-home.js";
 import { RavensFlight, SigilStamp } from "../../animations.js";
 /**
- * Map an AgentMessage onto a v3 TranscriptMessage. The role taxonomy
- * matches one-to-one across v1/v2/v3; we just wrap each message with
- * a stable id (using the index since AgentMessage doesn't carry one).
+ * Map an AgentMessage onto a v3 TranscriptMessage, PRESERVING each
+ * message's stable id. AgentMessage.id is assigned at creation (see
+ * makeMessageId / the assistant `assistantId`); we fall back to a
+ * positional id only for legacy messages that predate id assignment.
+ *
+ * Why a stable, non-positional id matters: it is the prerequisite for
+ * the Ink <Static> committed-history split (P1). <Static> keys items
+ * by identity to decide which rows it has ALREADY emitted, so a
+ * positional id would make it mis-detect new rows the moment a message
+ * is inserted mid-array. Preserving the message's own id also lets the
+ * assistant row keep one identity across its streamed deltas.
  *
  * Role coercion: AgentMessage's role is a wider union than v3's
  * TranscriptRole. The runtime mostly emits `user`/`assistant`; anything
  * else (e.g. `developer`) falls back to `system` so the row still
  * renders without a missing-style crash.
  */
-function toTranscriptMessages(messages) {
+export function toTranscriptMessages(messages) {
     return messages.map((msg, i) => ({
-        id: `msg-${i}`,
+        id: msg.id ?? `msg-${i}`,
         role: normaliseRole(msg.role),
         content: msg.content,
         ...(msg.attachments !== undefined ? { attachments: msg.attachments } : {}),
     }));
 }
+/**
+ * Stable unique id for a host-created message, matching the side-pane
+ * id idiom (`${role}-${Date.now()}-${random}`). Assigned at creation so
+ * the transcript and the <Static> committed-history split key rows by a
+ * stable identity rather than array position.
+ */
+function makeMessageId(role) {
+    return `${role}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+}
 function normaliseRole(role) {
     if (role === "user" || role === "assistant" || role === "system" || role === "tool") {
         return role;
     }
     return "system";
 }
+/** Selectable tool-approval modes (ascending autonomy), mirroring the
+ *  runtime's RuntimePermissionMode — used by the /permission slash handler. */
+const PERMISSION_MODES = ["ask-always", "smart", "auto-approve", "autonomous"];
 function toTranscriptAttachments(images) {
     return Object.freeze(images.map((image) => ({
         kind: "image",
@@ -238,8 +259,15 @@ function AppV3Inner({ providers, initialModel, initialProvider, messages, isStre
         sideActiveRunRef.current?.abort();
         sideActiveRunRef.current = null;
     }, []);
+    // P2 — coarse uptime clock. In the alt-screen buffer, Ink erase-rewrites
+    // the WHOLE live frame on any state change, so a 1Hz tick forced a
+    // full-frame repaint (visible idle flicker) every second. Session uptime
+    // is ambient info that does not need second precision, so tick every 10s
+    // (paired with minute-granularity formatUptime). The COMPLETE streaming
+    // flicker fix is the inline + <Static> pivot (the AppV4 rebuild — see
+    // docs/phase-0-redesign/renderer-decision.md).
     useEffect(() => {
-        const id = setInterval(() => setNowMs(Date.now()), 1000);
+        const id = setInterval(() => setNowMs(Date.now()), 10_000);
         return () => clearInterval(id);
     }, []);
     // ── Keyboard wiring ───────────────────────────────────────────────
@@ -291,13 +319,27 @@ function AppV3Inner({ providers, initialModel, initialProvider, messages, isStre
     // length approximation that every surface can compute consistently.
     const usedTokens = useMemo(() => Math.ceil(messages.reduce((total, msg) => total + Math.max(1, Math.ceil(msg.content.length / 4)), 0)), [messages]);
     const maxTokens = runtime?.getMaxContextTokens?.() ?? 200_000;
+    // Real session cost from the runtime CostTracker (climbs as turns run);
+    // falls back to 0 when no runtime/tracker is present. Replaces the prior
+    // hardcoded costUsd={0}/cost={0} that made "$0.000" never move.
+    const sessionCostUsd = runtime?.getCostTracker?.().getTotalCost?.() ?? 0;
     const [contextTrend, setContextTrend] = useState([usedTokens]);
     const [queuedPrompts, setQueuedPrompts] = useState([]);
     const [pendingImages, setPendingImages] = useState([]);
     const pendingImagesRef = useRef(pendingImages);
     pendingImagesRef.current = pendingImages;
     const submitGateRef = useRef(null);
+    // P4 — throttle context-trend sampling. `usedTokens` recomputes on every
+    // streamed token, and the unthrottled effect fired a SECOND state update
+    // (on top of setMessages) per token, doubling React reconciliation work
+    // during a stream. Sample at most every 500ms so the sparkline still
+    // trends without the per-token double-render.
+    const lastTrendSampleRef = useRef(0);
     useEffect(() => {
+        const now = Date.now();
+        if (now - lastTrendSampleRef.current < 500)
+            return;
+        lastTrendSampleRef.current = now;
         setContextTrend((prev) => {
             const last = prev[prev.length - 1];
             if (last === usedTokens)
@@ -314,6 +356,7 @@ function AppV3Inner({ providers, initialModel, initialProvider, messages, isStre
     const startRuntimeTurn = useCallback((trimmed, imagesForTurn) => {
         const attachments = toTranscriptAttachments(imagesForTurn);
         const userMessage = {
+            id: makeMessageId("user"),
             role: "user",
             content: trimmed,
             ...(attachments.length > 0 ? { attachments } : {}),
@@ -373,6 +416,7 @@ function AppV3Inner({ providers, initialModel, initialProvider, messages, isStre
                             setMessages((prev) => [
                                 ...prev,
                                 {
+                                    id: makeMessageId("tool"),
                                     role: "tool",
                                     toolName: ev.toolName,
                                     toolCallId: ev.toolCallId,
@@ -479,7 +523,7 @@ function AppV3Inner({ providers, initialModel, initialProvider, messages, isStre
                         const formatted = formatSlashResultMessage({
                             command: cmd,
                             ok: false,
-                            reason: `Unknown command: ${cmd}. Type /help for the registered list.`,
+                            reason: unhandledCommandReason(cmd),
                         });
                         setMessages((prev) => [...prev, { role: "system", content: formatted }]);
                         stampSigil("error");
@@ -809,8 +853,8 @@ function AppV3Inner({ providers, initialModel, initialProvider, messages, isStre
     // too much." Provider status moved to the /providers slash command.
     const heavyChrome = process.env["WOTANN_TUI_HEAVY"] === "1";
     const mainSurface = showSplash ? (_jsxs(Box, { flexDirection: "column", children: [heavyChrome ? (_jsxs(_Fragment, { children: [_jsx(GradientBanner, { profile: profile, state: bannerState, variant: bannerVariant }), _jsx(ModeCycle, { profile: profile, currentMode: currentMode })] })) : null, showTour ? (_jsx(Box, { marginTop: heavyChrome ? 1 : 0, children: _jsx(OnboardingTour, { profile: profile, authChoices: tourAuthChoices, themeChoices: tourThemeChoices, onComplete: finishTour, onDismiss: skipTour }) })) : (_jsxs(Box, { flexDirection: "column", marginTop: heavyChrome ? 1 : 0, marginBottom: 1, paddingLeft: 2, children: [!heavyChrome && (_jsx(Box, { marginBottom: 1, children: _jsx(Text, { color: tone.primary, bold: true, children: "WOTANN" }) })), _jsx(Text, { color: tone.muted, children: "Ready. Type to begin, / for commands, @ to reference files." }), providers.length === 0 ? (_jsx(Box, { marginTop: 1, children: _jsx(NoProviderHint, {}) })) : heavyChrome ? (_jsx(Box, { marginTop: 1, children: _jsx(ProviderStrip, { providers: providers, profile: profile }) })) : null] }))] })) : (_jsx(Box, { flexDirection: "column", marginTop: 1, marginBottom: 1, children: _jsx(Transcript, { messages: transcriptMessages, profile: profile, terminalCapabilities: terminalCapabilities, visibleCount: transcriptVisibleCount, scrollOffset: transcriptScrollOffset }) }));
-    const statusBarRow = (_jsx(Box, { marginTop: statusBarPosition === "bottom" ? 1 : 0, marginBottom: statusBarPosition === "top" ? 1 : 0, children: _jsx(StatusBar, { model: initialModel, provider: initialProvider, mode: currentMode, usedTokens: usedTokens, maxTokens: maxTokens, costUsd: 0, reads: 0, edits: 0, bashCalls: 0, isStreaming: isStreaming, contextTrend: contextTrend, profile: profile }) }));
-    return (_jsxs(Box, { flexDirection: "column", children: [statusBarPosition === "top" && statusBarRow, _jsxs(Box, { flexDirection: sidePaneVisible && columns >= 80 ? "row" : "column", gap: 1, children: [_jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, children: mainSurface }), _jsx(SidePane, { visible: sidePaneVisible, snapshotMessages: sidePaneSnapshotMessages, localMessages: sidePaneLocalMessages, profile: profile, onDismiss: closeSidePane, onPinToHost: () => promoteSidePaneToHost(), children: _jsx(PromptInput, { onSubmit: handleSidePaneSubmit, onChange: setSidePaneDraft, onAbort: handleSidePaneAbort, isStreaming: sidePaneStreaming, value: sidePaneDraft, vimMode: vimMode, placeholder: "Ask in this fork (/pin, /unfork, /clear)", mode: "side" }) })] }), showTypedSlashPanel && (_jsx(Box, { marginBottom: 0, children: _jsx(TypedSlashPanel, { draft: draftValue, commands: paletteCommands }) })), isStreaming && (_jsx(Box, { paddingX: 2, marginTop: 1, children: _jsx(RavensFlight, { active: isStreaming, tone: tone, label: "thinking", width: 16 }) })), !isStreaming && petMode === "raven" && (_jsx(Box, { paddingX: 2, marginTop: 1, children: _jsx(RavensFlight, { active: true, tone: tone, label: "companion", width: 16 }) })), _jsx(Box, { marginTop: 1, paddingX: 2, children: _jsxs(Box, { gap: 1, children: [_jsx(SigilStamp, { kind: sigilKind, tone: tone, nonce: sigilNonce }), _jsx(Statusline, { profile: profile, segments: statuslineSegments, model: initialModel, effort: currentMode, sandbox: runtime?.getPermissionMode?.() ?? "—", tokensUsed: usedTokens, tokensTotal: maxTokens, cost: 0, goal: activeGoal, uptimeMs: nowMs - sessionStartedAt })] }) }), _jsx(Composer, { profile: profile, children: _jsx(PromptInput, { onSubmit: handleSubmit, onChange: handleChange, onAbort: handleAbort, onPasteImageText: handlePasteImageText, imageAttachmentCount: pendingImages.length, disabled: sidePaneVisible, isStreaming: isStreaming, value: draftValue, vimMode: vimMode, placeholder: sidePaneVisible ? "Side fork owns input (/unfork to return)" : "Ask anything" }) }), _jsx(OverlayPaletteMount, { commands: paletteCommands, onSelect: (cmd) => {
+    const statusBarRow = (_jsx(Box, { marginTop: statusBarPosition === "bottom" ? 1 : 0, marginBottom: statusBarPosition === "top" ? 1 : 0, children: _jsx(StatusBar, { model: initialModel, provider: initialProvider, mode: currentMode, usedTokens: usedTokens, maxTokens: maxTokens, costUsd: sessionCostUsd, reads: 0, edits: 0, bashCalls: 0, isStreaming: isStreaming, contextTrend: contextTrend, profile: profile }) }));
+    return (_jsxs(Box, { flexDirection: "column", children: [statusBarPosition === "top" && statusBarRow, _jsxs(Box, { flexDirection: sidePaneVisible && columns >= 80 ? "row" : "column", gap: 1, children: [_jsx(Box, { flexDirection: "column", flexGrow: 1, flexShrink: 1, children: mainSurface }), _jsx(SidePane, { visible: sidePaneVisible, snapshotMessages: sidePaneSnapshotMessages, localMessages: sidePaneLocalMessages, profile: profile, onDismiss: closeSidePane, onPinToHost: () => promoteSidePaneToHost(), children: _jsx(PromptInput, { onSubmit: handleSidePaneSubmit, onChange: setSidePaneDraft, onAbort: handleSidePaneAbort, isStreaming: sidePaneStreaming, value: sidePaneDraft, vimMode: vimMode, placeholder: "Ask in this fork (/pin, /unfork, /clear)", mode: "side" }) })] }), showTypedSlashPanel && (_jsx(Box, { marginBottom: 0, children: _jsx(TypedSlashPanel, { draft: draftValue, commands: paletteCommands }) })), isStreaming && (_jsx(Box, { paddingX: 2, marginTop: 1, children: _jsx(RavensFlight, { active: isStreaming, tone: tone, label: "thinking", width: 16 }) })), !isStreaming && petMode === "raven" && (_jsx(Box, { paddingX: 2, marginTop: 1, children: _jsx(RavensFlight, { active: true, tone: tone, label: "companion", width: 16 }) })), _jsx(Box, { marginTop: 1, paddingX: 2, children: _jsxs(Box, { gap: 1, children: [_jsx(SigilStamp, { kind: sigilKind, tone: tone, nonce: sigilNonce }), _jsx(Statusline, { profile: profile, segments: statuslineSegments, model: initialModel, effort: currentMode, sandbox: runtime?.getPermissionMode?.() ?? "—", tokensUsed: usedTokens, tokensTotal: maxTokens, cost: sessionCostUsd, goal: activeGoal, uptimeMs: nowMs - sessionStartedAt })] }) }), _jsx(Composer, { profile: profile, children: _jsx(PromptInput, { onSubmit: handleSubmit, onChange: handleChange, onAbort: handleAbort, onPasteImageText: handlePasteImageText, imageAttachmentCount: pendingImages.length, disabled: sidePaneVisible, isStreaming: isStreaming, value: draftValue, vimMode: vimMode, placeholder: sidePaneVisible ? "Side fork owns input (/unfork to return)" : "Ask anything" }) }), _jsx(OverlayPaletteMount, { commands: paletteCommands, onSelect: (cmd) => {
                     // Dispatch through the router with the empty arg + the real
                     // slash context (so /clear actually clears, etc.). Close the
                     // overlay after selection so muscle memory matches Codex/Crush.
@@ -983,6 +1027,28 @@ version: _version, providers, initialModel = "", initialProvider = "", initialMe
                 setVimMode(enabled);
                 themeManager.persist({ vimKeymap: enabled });
             },
+            // /theme — mirror the Ctrl+Y cycle (themeManager.setTheme + setPalette)
+            // so the slash command and the keybind switch themes identically.
+            getTheme: () => themeManager.getCurrent().name,
+            listThemes: () => themeManager.getThemeNames(),
+            setTheme: (name) => {
+                const ok = themeManager.setTheme(name);
+                if (ok)
+                    setPalette(themeManager.getCurrent().colors);
+                return ok;
+            },
+            // /permission — approval mode via the runtime's get/setPermissionMode
+            // (the same modes startRuntimeTurn threads into the agent loop).
+            getPermission: () => runtime?.getPermissionMode?.() ?? "smart",
+            listPermissions: () => PERMISSION_MODES,
+            setPermission: (mode) => {
+                if (!PERMISSION_MODES.includes(mode))
+                    return false;
+                if (runtime?.setPermissionMode === undefined)
+                    return false;
+                runtime.setPermissionMode(mode);
+                return true;
+            },
             // Quit is intentionally NOT wired here — the user
             // expects Ctrl+C to exit, and /quit prints an informational
             // message explaining that.

package/dist/ui/components/v3/Statusline.js

@@ -78,15 +78,18 @@ function formatCost(cost) {
 function formatUptime(ms) {
     if (ms === undefined || !Number.isFinite(ms) || ms < 0)
         return "—";
-    const totalSeconds = Math.floor(ms / 1000);
-    const h = Math.floor(totalSeconds / 3600);
-    const m = Math.floor((totalSeconds % 3600) / 60);
-    const s = totalSeconds % 60;
+    // Minute-granularity: session uptime is ambient, so the clock that feeds
+    // this ticks at 10s (P2 idle-flicker fix) and we never render seconds —
+    // a seconds display would step visibly at the coarse cadence. Sub-minute
+    // reads "<1m".
+    const totalMinutes = Math.floor(ms / 60_000);
+    const h = Math.floor(totalMinutes / 60);
+    const m = totalMinutes % 60;
     if (h > 0)
         return `${h}h${m.toString().padStart(2, "0")}m`;
     if (m > 0)
-        return `${m}m${s.toString().padStart(2, "0")}s`;
-    return `${s}s`;
+        return `${m}m`;
+    return `<1m`;
 }
 function truncateWith(value, max) {
     if (max <= 1)

package/dist/ui/help-registry.d.ts

@@ -58,3 +58,17 @@ export declare function searchHelp(query: string): readonly HelpEntry[];
  * added or removed without test updates.
  */
 export declare const HELP_ENTRY_COUNT: number;
+/**
+ * Canonical ids of every advertised slash command — first token only, so a
+ * help entry like "/save [name]" normalizes to "/save". Used at dispatch
+ * time to distinguish a *recognized-but-unwired* command (a real feature the
+ * TUI advertises but has not yet wired a handler for) from a genuine typo,
+ * so the failure message is honest instead of a misleading "Unknown command".
+ */
+export declare const ADVERTISED_COMMAND_IDS: ReadonlySet<string>;
+/**
+ * Honest failure reason for a slash command that resolved to no router
+ * handler. QB#6: never silent-success; here we also avoid mislabelling a
+ * real-but-unwired feature as a typo.
+ */
+export declare function unhandledCommandReason(command: string): string;

package/dist/ui/help-registry.js

@@ -308,3 +308,21 @@ export function searchHelp(query) {
  * added or removed without test updates.
  */
 export const HELP_ENTRY_COUNT = ALL_HELP_ENTRIES.length;
+/**
+ * Canonical ids of every advertised slash command — first token only, so a
+ * help entry like "/save [name]" normalizes to "/save". Used at dispatch
+ * time to distinguish a *recognized-but-unwired* command (a real feature the
+ * TUI advertises but has not yet wired a handler for) from a genuine typo,
+ * so the failure message is honest instead of a misleading "Unknown command".
+ */
+export const ADVERTISED_COMMAND_IDS = new Set(ALL_HELP_ENTRIES.map((entry) => entry.command.split(/\s+/)[0] ?? entry.command));
+/**
+ * Honest failure reason for a slash command that resolved to no router
+ * handler. QB#6: never silent-success; here we also avoid mislabelling a
+ * real-but-unwired feature as a typo.
+ */
+export function unhandledCommandReason(command) {
+    return ADVERTISED_COMMAND_IDS.has(command)
+        ? `${command} is a known command that isn't wired into the TUI yet. Type /help for commands you can run now.`
+        : `Unknown command: ${command}. Type /help for the registered list.`;
+}

package/dist/ui/raw-mode-guard.d.ts

@@ -38,6 +38,20 @@ export interface RawModeStream {
  * state is preserved when it works) inside a try/catch. If it throws
  * here, the resolver falls through to `/dev/tty` or refuses cleanly
  * instead of mounting Ink into the silent loop.
+ *
+ * Node 25 `_handle` exception (added 2026-05-28 — empirical evidence
+ * from user diagnostic): on Node v25.x, the probe call throws
+ *   "Cannot read properties of undefined (reading '_handle')"
+ * because the libuv TTY binding (`this._handle`) isn't initialized at
+ * probe time — Node 25 lazily binds it on first I/O. The same
+ * `setRawMode` call AT INK'S RENDER COMMIT succeeds because by then
+ * Ink has read from the stream and the binding is live. Treating
+ * this specific error as "passes" (optimistic) lets the mount
+ * proceed; the `mount-interactive-ink` Ink-throw backstop catches
+ * any genuine failure at render time and writes the same actionable
+ * guidance. False-positive cost: a runtime error message instead of
+ * a guard refusal — same end UX. True-positive value: working TUI
+ * under Node 25, which is the user's current default.
  */
 export declare function isRawModeCapable(stream: unknown): boolean;
 export interface ResolveStdinOptions {

package/dist/ui/raw-mode-guard.js

@@ -35,6 +35,20 @@ import { ReadStream } from "node:tty";
  * state is preserved when it works) inside a try/catch. If it throws
  * here, the resolver falls through to `/dev/tty` or refuses cleanly
  * instead of mounting Ink into the silent loop.
+ *
+ * Node 25 `_handle` exception (added 2026-05-28 — empirical evidence
+ * from user diagnostic): on Node v25.x, the probe call throws
+ *   "Cannot read properties of undefined (reading '_handle')"
+ * because the libuv TTY binding (`this._handle`) isn't initialized at
+ * probe time — Node 25 lazily binds it on first I/O. The same
+ * `setRawMode` call AT INK'S RENDER COMMIT succeeds because by then
+ * Ink has read from the stream and the binding is live. Treating
+ * this specific error as "passes" (optimistic) lets the mount
+ * proceed; the `mount-interactive-ink` Ink-throw backstop catches
+ * any genuine failure at render time and writes the same actionable
+ * guidance. False-positive cost: a runtime error message instead of
+ * a guard refusal — same end UX. True-positive value: working TUI
+ * under Node 25, which is the user's current default.
  */
 export function isRawModeCapable(stream) {
     if (stream === null || typeof stream !== "object")
@@ -48,10 +62,22 @@ export function isRawModeCapable(stream) {
         setRawMode(currentIsRaw);
         return true;
     }
-    catch {
-        return false;
+    catch (e) {
+        return isNode25HandleInitDefer(e);
     }
 }
+/**
+ * Detect the Node 25+ "_handle is undefined at probe time" pattern.
+ * Matches both the literal `_handle` reference and the broader libuv
+ * binding init-order race that surfaces under the same wording. Kept
+ * separate from `isRawModeCapable` so the rationale lives next to
+ * the matcher and the same logic can drive `probeStdinDetail`.
+ */
+function isNode25HandleInitDefer(e) {
+    if (!(e instanceof Error))
+        return false;
+    return e.message.includes("_handle");
+}
 /**
  * Open the controlling terminal as a raw-capable input stream, or
  * `null` if there is none (Windows without a console, detached

package/dist/ui/slash-commands/handlers/v3-intrinsics.d.ts

@@ -55,6 +55,18 @@ export interface ShellStateAccessor {
     readonly clearTranscript?: () => void;
     /** Enable/disable Vim composer mode for the active shell. */
     readonly setVimMode?: (enabled: boolean) => void;
+    /** Current theme name (e.g. "dark"). */
+    readonly getTheme?: () => string;
+    /** All selectable theme names — for `/theme` listing + validation. */
+    readonly listThemes?: () => readonly string[];
+    /** Switch the active theme; returns false if the name is unknown. */
+    readonly setTheme?: (name: string) => boolean;
+    /** Current tool-approval mode (e.g. "smart"). */
+    readonly getPermission?: () => string;
+    /** All selectable approval modes — for /permission listing + validation. */
+    readonly listPermissions?: () => readonly string[];
+    /** Switch the approval mode; returns false if the mode is unknown. */
+    readonly setPermission?: (mode: string) => boolean;
     /**
      * Optional quit handler. When provided, /quit and /exit will invoke
      * it; otherwise the handler returns an informational message.

package/dist/ui/slash-commands/handlers/v3-intrinsics.js

@@ -172,6 +172,59 @@ function buildVimHandler(state) {
         };
     };
 }
+/** Build the canonical `/theme` handler bound to a state accessor. */
+function buildThemeHandler(state) {
+    return (_ctx, arg) => {
+        const arg0 = arg.trim();
+        const names = state.getTheme !== undefined ? (state.listThemes?.() ?? []) : [];
+        if (arg0.length === 0 || arg0.toLowerCase() === "list") {
+            const current = state.getTheme?.() ?? "";
+            const lines = ["Themes:"];
+            for (const n of names)
+                lines.push(`${n === current ? "* " : "  "}${n}`);
+            lines.push("");
+            lines.push("Usage: `/theme <name>` switches the active theme (Ctrl+Y cycles).");
+            return { ok: true, message: lines.join("\n") };
+        }
+        if (typeof state.setTheme !== "function") {
+            return { ok: false, reason: "Theme switching is not wired in this shell." };
+        }
+        if (!state.setTheme(arg0)) {
+            return {
+                ok: false,
+                reason: `Unknown theme "${arg0}".` + (names.length > 0 ? ` Available: ${names.join(", ")}.` : ""),
+            };
+        }
+        return { ok: true, message: `Theme switched to "${arg0}".` };
+    };
+}
+/** Build the canonical `/permission` handler bound to a state accessor. */
+function buildPermissionHandler(state) {
+    return (_ctx, arg) => {
+        const arg0 = arg.trim().toLowerCase();
+        const modes = state.getPermission !== undefined ? (state.listPermissions?.() ?? []) : [];
+        if (arg0.length === 0 || arg0 === "status") {
+            const current = state.getPermission?.() ?? "";
+            const lines = ["Approval modes:"];
+            for (const m of modes)
+                lines.push(`${m === current ? "* " : "  "}${m}`);
+            lines.push("");
+            lines.push("Usage: `/permission <mode>` sets how tool calls are approved.");
+            return { ok: true, message: lines.join("\n") };
+        }
+        if (typeof state.setPermission !== "function") {
+            return { ok: false, reason: "Approval-mode switching is not wired in this shell." };
+        }
+        if (!state.setPermission(arg0)) {
+            return {
+                ok: false,
+                reason: `Unknown approval mode "${arg0}".` +
+                    (modes.length > 0 ? ` Available: ${modes.join(", ")}.` : ""),
+            };
+        }
+        return { ok: true, message: `Approval mode set to "${arg0}".` };
+    };
+}
 /** Build the canonical `/quit` handler (also bound to `/exit`). */
 function buildQuitHandler(state) {
     return () => {
@@ -221,6 +274,19 @@ export function buildV3IntrinsicCommands(state) {
             category: "Config",
             handler: buildVimHandler(state),
         },
+        {
+            id: "/theme",
+            description: "Show or switch the color theme (Ctrl+Y cycles)",
+            category: "Config",
+            handler: buildThemeHandler(state),
+        },
+        {
+            id: "/permission",
+            aliases: ["/permissions"],
+            description: "Show or set the tool-approval mode",
+            category: "Config",
+            handler: buildPermissionHandler(state),
+        },
         {
             id: "/clear",
             description: "Clear the transcript",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wotann",
-  "version": "0.5.93",
+  "version": "0.5.95",
   "description": "WOTANN — The All-Father of AI Agent Harnesses",
   "type": "module",
   "main": "dist/index.js",