@scira/cli 0.1.8 → 0.1.9

package/dist/ui/ink/hooks/use-feed-lines.js

@@ -6,11 +6,6 @@ import { S_BAR, TOOL_ICONS, SPINNER_FRAMES } from "../constants.js";
 import { formatTime, fmtDuration, wrapText, computeLineLinks, displayWidth } from "../lib/utils.js";
 import { formatToolResultLines, formatToolResultPreview, feedToolItemId, isCollapsibleToolName, isToolItemCollapsed, canonicalToolName, displayToolName, } from "../lib/tool-result.js";
 import { markdownToSegLines } from "../lib/markdown.js";
-// Formatting a tool body (wrapping/parsing the result) is the expensive part of
-// building feed lines. The feed re-renders on every spinner/reasoning tick
-// (~20fps while busy), so without caching a large result would be re-parsed
-// dozens of times a second. Cache by content identity; completed items hit the
-// cache and only the live item (whose result is still growing) recomputes.
 const toolBodyCache = new Map();
 function cachedToolBody(themeKey, name, callId, summary, result, status, width, theme, expanded, input) {
     const key = `${themeKey}|${callId}|${name}|${status}|${width}|${expanded}|${result?.length ?? 0}|${input?.length ?? 0}`;
@@ -62,17 +57,12 @@ const isGH = (item) => item._tag === "gh";
 function renderSegNodes(segs, theme, defaultColor) {
     return segs.map((s, i) => {
         const inner = (_jsx(Text, { color: s.url ? (s.color ?? theme.accent) : (s.color ?? defaultColor), bold: s.bold, italic: s.italic, underline: s.url ? true : s.underline, dimColor: s.dim, children: s.text }));
-        // For URL segments, emit an OSC 8 terminal hyperlink so the terminal itself makes the
-        // text clickable (Cmd/Ctrl-click). fallback={false} keeps the visible text unchanged so
-        // the pre-computed line widths still hold on terminals without hyperlink support.
         return s.url
             ? _jsx(Link, { url: s.url, fallback: false, children: inner }, i)
             : React.cloneElement(inner, { key: i });
     });
 }
-export function useFeedLines(feed, innerWidth, 
-// eslint-disable-next-line @typescript-eslint/no-unused-vars
-reasoningTick, spinnerFrame, collapsedGroups, focusedGroupKey, itemExpandState, hoveredLineIdx, config) {
+export function useFeedLines(feed, innerWidth, _reasoningTick, spinnerFrame, collapsedGroups, focusedGroupKey, itemExpandState, hoveredLineIdx, config) {
     const theme = useTheme();
     return useMemo(() => {
         const bandBg = theme.userBandBackground ? { backgroundColor: theme.userBandBackground } : {};
@@ -172,9 +162,6 @@ reasoningTick, spinnerFrame, collapsedGroups, focusedGroupKey, itemExpandState,
                 const running = fi.status === "running";
                 const failed = fi.status === "error";
                 const itemId = feedToolItemId(feedIdx, fi.toolCallId);
-                // Route rendering through the Scira-canonical name (Claude/Codex builtins
-                // and `mcp__harness-tools__*` host tools map onto our renderers), but show
-                // the cleaned real name in the header.
                 const canon = canonicalToolName(fi.name);
                 const shownName = displayToolName(fi.name);
                 const collapsible = isCollapsibleToolName(canon) && !running;
@@ -187,9 +174,6 @@ reasoningTick, spinnerFrame, collapsedGroups, focusedGroupKey, itemExpandState,
                 const symColor = failed ? theme.error : theme.accentDim;
                 const nameColor = running ? theme.text : failed ? theme.error : theme.textDim;
                 const panelWidth = innerWidth - 4;
-                // Pass the raw name so dedicated built-in renderers (Edit diff, TodoWrite
-                // checklist, …) can key off it; the formatters canonicalize internally
-                // for the generic path.
                 const preview = formatToolResultPreview(fi.name, fi.summary, fi.result, fi.status);
                 const bodyLines = cachedToolBody(theme.accent, fi.name, fi.toolCallId ?? String(feedIdx), fi.summary, fi.result, fi.status, panelWidth, theme, !collapsed, fi.input);
                 if (collapsible)
@@ -261,6 +245,5 @@ reasoningTick, spinnerFrame, collapsedGroups, focusedGroupKey, itemExpandState,
             }
         });
         return { lines, toggleAtLine, groupToggleAtLine, linkAtLine, lastUserLineStart };
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [feed, innerWidth, reasoningTick, spinnerFrame, collapsedGroups, focusedGroupKey, itemExpandState, hoveredLineIdx, config, theme]);
+    }, [feed, innerWidth, _reasoningTick, spinnerFrame, collapsedGroups, focusedGroupKey, itemExpandState, hoveredLineIdx, config, theme]);
 }

package/dist/ui/ink/hooks/use-feed.js

@@ -2,7 +2,6 @@ import { useCallback, useRef, useState } from "react";
 export function useFeed() {
     const [feed, setFeed] = useState([]);
     const feedRef = useRef([]);
-    /** Keep feedRef in sync immediately so convo.json saves never read stale React state. */
     const applyFeed = useCallback((update) => {
         const next = update(feedRef.current);
         feedRef.current = next;

package/dist/ui/ink/hooks/use-keyboard.js

@@ -16,7 +16,6 @@ export function useKeyboard(o) {
     const { setScrollOffset, contentRows, maxScrollOffset, pendingRerun, setPendingRerun, busy, stopTurn, submitChat, toggleAllGroups, toggleFocusedGroup, focusPrevGroup, focusNextGroup, unfocusGroup, hasFocusedGroup } = o.chat;
     const { sessionsModalOpen, setSessionsModalOpen, sessionsModalIdx, setSessionsModalIdx, sessions, deleteSession, selectedIdx, setSelectedIdx, setHeroHidden, openRun, submitHome } = o.home;
     const deleteArmedRef = useRef(null);
-    // Quit requires confirmation: first Ctrl+C arms, second within the window quits.
     const quitArmedRef = useRef(false);
     const quitTimerRef = useRef(null);
     const editInput = (char, key) => {
@@ -95,10 +94,8 @@ export function useKeyboard(o) {
     useInput((char, key) => {
         if (char && (char.includes("[<") || /^\d+;\d+;\d+[Mm]$/u.test(char)))
             return;
-        // OSC background-color query responses leak as stdin when terminals reply to theme probes.
         if (char && (/\]11;rgb:/u.test(char) || /^11;rgb:/u.test(char)))
             return;
-        // Quit handling (all screens): Ctrl+C twice (with warning) or Ctrl+D.
         if (key.ctrl && char === "c") {
             if (busy) {
                 stopTurn();
@@ -114,7 +111,6 @@ export function useKeyboard(o) {
             if (quitTimerRef.current)
                 clearTimeout(quitTimerRef.current);
             quitTimerRef.current = setTimeout(() => { quitArmedRef.current = false; }, 3000);
-            // Don't let the disarm timer keep the process alive after a quit.
             quitTimerRef.current.unref?.();
             return;
         }
@@ -238,7 +234,6 @@ export function useKeyboard(o) {
             });
             return;
         }
-        // Cancel pendingRerun if user types something other than /rerun
         if (pendingRerun && char && !(inputText + char).trim().startsWith("/rerun")) {
             setPendingRerun(false);
         }

package/dist/ui/ink/hooks/use-session.js

@@ -14,14 +14,12 @@ export function useSession(o) {
     }, [currentRunPath]);
     const openRun = useCallback(async (runPath, initialQuestion) => {
         if (runPath !== currentRunPath) {
-            // Honor a plan-mode preference armed from the home screen, then disarm it.
             setPlanMode(pendingPlanModeRef.current);
             setPendingPlanMode(false);
         }
         setCurrentRunPath(runPath);
         setInputText("");
         setCursorPos(0);
-        // If a background session is already running for this path, reattach to it.
         const live = getSession(runPath);
         if (live) {
             startedRef.current = runPath;

package/dist/ui/ink/hooks/use-suggestions.js

@@ -37,7 +37,6 @@ export function useSuggestions({ inputText, setInputText, setCursorPos, sessions
         sessionMatchesRef.current = matches;
         return matches.map(sessionLabel);
     }, [inputText, sessions]);
-    // Refresh sessions when typing # if the list is empty
     React.useEffect(() => {
         if (inputText.startsWith("#") && sessions.length === 0) {
             void refreshSessions();

package/dist/ui/ink/lib/tool-result.js

@@ -2,11 +2,8 @@ import { diffLines } from "diff";
 import { markdownToSegLines } from "./markdown.js";
 import { wrapText } from "./utils.js";
 const HARNESS_TOOL_PREFIX = "mcp__harness-tools__";
-/** Map Claude Code / Codex built-in (and harness host) tool names onto Scira's renderers. */
 const CANONICAL_TOOL = {
-    // Scira host tools exposed to the CLI
     multiWebSearch: "webSearch",
-    // Claude Code built-ins
     Read: "readFile",
     Write: "writeFile",
     Edit: "editFile",
@@ -20,23 +17,15 @@ const CANONICAL_TOOL = {
     TodoWrite: "todo",
     WebFetch: "readUrl",
     WebSearch: "webSearch",
-    // Codex built-ins
     shell: "bash",
 };
-/** Strip the harness host-tool MCP prefix so `mcp__harness-tools__readUrl` reads as `readUrl`. */
 export function displayToolName(name) {
     return name.startsWith(HARNESS_TOOL_PREFIX) ? name.slice(HARNESS_TOOL_PREFIX.length) : name;
 }
-/**
- * Resolve a harness/CLI tool name to the Scira renderer key. The harness exposes
- * our host tools as `mcp__harness-tools__*` and the CLIs have their own builtin
- * names (Read, Bash, Grep, …); both should render like Scira's equivalents.
- */
 export function canonicalToolName(name) {
     const stripped = displayToolName(name);
     return CANONICAL_TOOL[stripped] ?? stripped;
 }
-/** Tools that start collapsed in the timeline (long output). */
 export const DEFAULT_COLLAPSED_TOOLS = new Set([
     "webSearch",
     "multiWebSearch",
@@ -57,8 +46,6 @@ export function isCollapsibleToolName(name) {
     return name.length > 0;
 }
 export function defaultCollapsedToolName(name) {
-    // Chrome DevTools MCP tools (prefixed `devtools_`) produce long browser
-    // snapshots/output, so collapse them by default like the built-in tools.
     if (name.startsWith("devtools_"))
         return true;
     return DEFAULT_COLLAPSED_TOOLS.has(name);
@@ -222,7 +209,6 @@ function formatListSkills(result, width, theme) {
     });
 }
 function formatShellOutput(result, width, theme) {
-    // Codex returns `{ exitCode, output }`; Claude returns the output string directly.
     let text = result;
     const obj = parseObj(result);
     if (obj && typeof obj.output === "string") {
@@ -333,7 +319,6 @@ function formatBody(name, result, width, theme) {
         }
     }
 }
-/** One-line preview for a collapsed tool header. */
 export function formatToolResultPreview(rawName, inputSummary, result, status) {
     const name = canonicalToolName(rawName);
     const input = inputSummary.replace(/\s+/gu, " ").trim();
@@ -364,7 +349,7 @@ export function formatToolResultPreview(rawName, inputSummary, result, status) {
                 return q ? `${q} · ${total} sources` : `${total} sources`;
             }
         }
-        catch { /* fall through */ }
+        catch { }
     }
     if (name === "xSearch") {
         try {
@@ -376,7 +361,7 @@ export function formatToolResultPreview(rawName, inputSummary, result, status) {
                 return q ? `${q} · ${total} posts` : `${total} posts`;
             }
         }
-        catch { /* fall through */ }
+        catch { }
     }
     if (name === "readFile" || name === "readWorkspaceFile") {
         const lines = result.split("\n").length;
@@ -389,7 +374,6 @@ export function formatToolResultPreview(rawName, inputSummary, result, status) {
     const first = result.replace(/\s+/gu, " ").trim();
     return first.length > 140 ? `${first.slice(0, 137)}…` : first;
 }
-// --- Dedicated renderers for Claude Code / Codex built-in tools ---
 function parseObj(s) {
     if (!s)
         return null;
@@ -401,7 +385,6 @@ function parseObj(s) {
         return null;
     }
 }
-/** Unified-ish diff between two strings: removed lines red, added green, a little context dim. */
 function diffSegLines(oldStr, newStr, width, theme) {
     const parts = diffLines(oldStr ?? "", newStr ?? "");
     const out = [];
@@ -427,7 +410,6 @@ function diffSegLines(oldStr, newStr, width, theme) {
 function pathHeader(p, theme) {
     return [seg("path  ", { dim: true, color: theme.textDim }), seg(String(p ?? ""), { color: theme.text })];
 }
-/** Edit / MultiEdit → file path + colored diff(s). */
 function formatEditBody(input, width, theme) {
     const lines = [pathHeader(input.file_path ?? input.notebook_path, theme)];
     const edits = Array.isArray(input.edits)
@@ -440,7 +422,6 @@ function formatEditBody(input, width, theme) {
     });
     return lines;
 }
-/** TodoWrite → checklist with status glyphs. */
 function formatTodoBody(input, width, theme) {
     const todos = Array.isArray(input.todos) ? input.todos : [];
     if (todos.length === 0)
@@ -454,7 +435,6 @@ function formatTodoBody(input, width, theme) {
         return wrapped.map((w, i) => [seg(i === 0 ? `${glyph} ` : "  ", { color }), seg(w, { color: status === "completed" ? theme.textDim : theme.text })]);
     });
 }
-/** Write → file path + content preview. */
 function formatWriteBody(input, width, theme) {
     const lines = [pathHeader(input.file_path, theme), blank()];
     const allLines = String(input.content ?? "").split("\n");
@@ -465,7 +445,6 @@ function formatWriteBody(input, width, theme) {
         lines.push([seg(`… +${allLines.length - shown.length} more lines`, { dim: true, color: theme.textDim })]);
     return lines;
 }
-/** WebFetch → url + fetched/answer text. */
 function formatWebFetchBody(input, result, width, theme) {
     const lines = [];
     const url = input?.url;
@@ -478,7 +457,6 @@ function formatWebFetchBody(input, result, width, theme) {
     }
     return lines;
 }
-/** Task / Agent (subagent) → description + output. */
 function formatSubagentBody(input, result, width, theme) {
     const lines = [];
     const desc = input?.description ?? input?.subagent_type;
@@ -491,7 +469,6 @@ function formatSubagentBody(input, result, width, theme) {
     }
     return lines;
 }
-/** ToolSearch → query + which tool reference it loaded. */
 function formatToolSearchBody(input, result, width, theme) {
     const lines = [];
     if (input?.query)
@@ -503,10 +480,6 @@ function formatToolSearchBody(input, result, width, theme) {
         lines.push(...plainLines(result, width, { color: theme.textDim }));
     return lines;
 }
-/**
- * Dedicated body for a Claude Code / Codex built-in tool, keyed by its real
- * (un-prefixed) name. Returns null to fall through to the generic renderer.
- */
 function formatBuiltinBody(real, rawInput, result, width, theme) {
     const input = parseObj(rawInput);
     switch (real) {
@@ -533,7 +506,6 @@ function formatBuiltinBody(real, rawInput, result, width, theme) {
             return null;
     }
 }
-/** Codex/Claude file mutation event → a single colored "<event>  <path>" line. */
 function formatFileChangeBody(fc, theme) {
     if (!fc)
         return null;
@@ -541,21 +513,15 @@ function formatFileChangeBody(fc, theme) {
     const color = event === "delete" ? theme.error : event === "create" ? theme.success : theme.accent;
     return [[seg(`${event}  `, { color }), seg(String(fc.path ?? ""), { color: theme.text })]];
 }
-/** Multi-line formatted tool output for the feed panel. */
 export function formatToolResultLines(rawName, inputSummary, rawResult, status, contentWidth, theme, expanded = true, rawInput) {
     const name = canonicalToolName(rawName);
     const real = displayToolName(rawName);
     if (!expanded)
         return [];
-    // Bound the text we lay out per render — a terminal can't show a 1MB result,
-    // and wrapping/parsing that much on every frame is what stalls the renderer.
-    // The full result stays in the stored feed; only what we format is capped.
     const MAX_RENDER = 60_000;
     const result = rawResult && rawResult.length > MAX_RENDER
         ? `${rawResult.slice(0, MAX_RENDER)}\n\n… [${rawResult.length - MAX_RENDER} more chars not shown]`
         : rawResult;
-    // Dedicated built-in tool rendering (diffs, checklists, …). Input-driven ones
-    // (Edit, Write, TodoWrite) render even while the tool is still running.
     if (status !== "error") {
         const builtin = formatBuiltinBody(real, rawInput, result ?? "", Math.max(16, contentWidth), theme);
         if (builtin && builtin.length > 0) {

package/dist/ui/ink/lib/utils.js

@@ -6,7 +6,6 @@ import { dirname, join, resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 import { FULL_MODE_TRIGGERS } from "../constants.js";
 export const pkgVersion = JSON.parse(readFileSync(join(dirname(fileURLToPath(import.meta.url)), "../../../../package.json"), "utf8")).version;
-/** Pipe text to the OS clipboard (pbcopy / clip / xclip). Resolves false when unavailable. */
 export async function copyToClipboard(text) {
     const cmd = process.platform === "darwin" ? "pbcopy" : process.platform === "win32" ? "clip" : "xclip";
     const args = cmd === "xclip" ? ["-selection", "clipboard"] : [];
@@ -38,7 +37,7 @@ export async function saveInputHistory(runDirectory, history) {
         await mkdir(dirname(file), { recursive: true });
         await Bun.write(file, JSON.stringify(history.slice(-50), null, 2));
     }
-    catch { /* non-fatal */ }
+    catch { }
 }
 export const CWD_DISPLAY = (() => {
     const home = homedir();
@@ -52,11 +51,9 @@ export function prettifyModelId(id) {
         .map((w) => (/^[0-9]/u.test(w) ? w : w.charAt(0).toUpperCase() + w.slice(1)))
         .join(" ");
 }
-/** Terminal-cell width of a string (CJK/emoji aware, strips ANSI). */
 export function displayWidth(text) {
     return Bun.stringWidth(text);
 }
-/** Longest prefix of `text` whose terminal-cell width fits in `width`; returns its char length. */
 function fitChars(text, width) {
     if (Bun.stringWidth(text) === text.length)
         return Math.min(text.length, width);
@@ -123,27 +120,7 @@ export function fmtTokens(n) {
         return `${(n / 1000).toFixed(1)}k`;
     return String(n);
 }
-/** Compact relative time, e.g. "now", "5m", "3h", "2d", "3w". */
-export function relativeTime(ms) {
-    if (!ms)
-        return "";
-    const diff = Date.now() - ms;
-    if (diff < 60_000)
-        return "now";
-    const mins = Math.floor(diff / 60_000);
-    if (mins < 60)
-        return `${mins}m ago`;
-    const hours = Math.floor(mins / 60);
-    if (hours < 24)
-        return `${hours}h ago`;
-    const days = Math.floor(hours / 24);
-    if (days < 7)
-        return `${days}d ago`;
-    const weeks = Math.floor(days / 7);
-    if (weeks < 5)
-        return `${weeks}w ago`;
-    return new Date(ms).toLocaleDateString();
-}
+export { relativeTime } from "../../../utils/time.js";
 function colorToAnsi(color) {
     if (!color)
         return [];
@@ -162,7 +139,6 @@ function colorToAnsi(color) {
     const code = named[color.toLowerCase()];
     return code ? [code] : [];
 }
-/** OSC 8 link with inline ANSI styling — avoids Ink Text props breaking the escape sequence. */
 export function ansiHyperlink(text, url, style) {
     const params = [];
     if (style?.bold)
@@ -193,7 +169,6 @@ export function computeLineLinks(segs, prefixCols = 0) {
     }
     return links;
 }
-/** Match an SGR mouse column (1-based) against link regions from computeLineLinks. */
 export function linkAtMouseColumn(links, x) {
     for (const l of links) {
         if (x >= l.start + 1 && x <= l.end + 1)
@@ -201,7 +176,6 @@ export function linkAtMouseColumn(links, x) {
     }
     return undefined;
 }
-/** Open a URL in the system browser. */
 export async function openExternalUrl(url) {
     const cmd = process.platform === "darwin" ? "open" : process.platform === "win32" ? "cmd" : "xdg-open";
     const args = process.platform === "win32" ? ["/c", "start", "", url] : [url];
@@ -214,12 +188,10 @@ export async function openExternalUrl(url) {
         return false;
     }
 }
-/** True if the prompt clearly asks for full, report-grade research. */
 export function wantsFullResearch(prompt) {
     const p = prompt.toLowerCase();
     return FULL_MODE_TRIGGERS.some((kw) => p.includes(kw));
 }
-/** Word-wrap input text and locate the caret in the wrapped output (no cursor char injection). */
 export function wrapInputWithCursor(text, width, caretPos) {
     const w = Math.max(1, width);
     const lines = [];
@@ -283,8 +255,6 @@ function toolOutputText(output) {
         return String(output);
     }
 }
-// Harness/CLI tool names mapped to Scira renderer keys. Kept local to avoid a
-// circular import with tool-result.ts (which imports from this file).
 const HARNESS_TOOL_PREFIX = "mcp__harness-tools__";
 const SUMMARY_CANONICAL = {
     multiWebSearch: "webSearch",
@@ -337,7 +307,6 @@ export function summarizeToolInput(rawName, input) {
         return "";
     }
 }
-/** Short one-line summary of a completed tool's output for the feed. */
 export function summarizeToolOutput(name, output) {
     const text = toolOutputText(output);
     if (name === "webSearch") {
@@ -352,7 +321,7 @@ export function summarizeToolOutput(name, output) {
                 return titles.length > 0 ? `${head} · ${titles.join(" · ")}` : head;
             }
         }
-        catch { /* fall through */ }
+        catch { }
     }
     if (name === "xSearch") {
         try {
@@ -371,7 +340,7 @@ export function summarizeToolOutput(name, output) {
                 return handles.length > 0 ? `${head} · ${handles.join(", ")}` : head;
             }
         }
-        catch { /* fall through */ }
+        catch { }
     }
     if (name === "readUrl") {
         const titleMatch = text.match(/^#\s+(.+)/m);

package/dist/ui/ink/session-manager.js

@@ -28,7 +28,6 @@ export function detachSubscriber(runPath) {
     const session = sessions.get(runPath);
     if (session)
         session.subscriber = null;
-    // deliberately NOT aborting — stream keeps running in the background
 }
 export function abortSession(runPath) {
     const session = sessions.get(runPath);
@@ -42,7 +41,6 @@ export function abortSession(runPath) {
 export function removeSession(runPath) {
     sessions.delete(runPath);
 }
-/** Merge full tool results from the session buffer into a feed snapshot before persisting. */
 export function mergeFeedToolResults(feed, buffer) {
     const toolById = new Map();
     for (const item of buffer) {
@@ -74,17 +72,14 @@ export function getSessionFeedBuffer(runPath) {
     const session = sessions.get(runPath);
     return session ? [...session.feedBuffer] : [];
 }
-/** Route a feed item to the correct subscriber method and buffer it. */
 export function sessionPushFeed(runPath, item) {
     const session = sessions.get(runPath);
     if (!session)
         return;
     const sub = session.subscriber;
     if (sub) {
-        // Route to fine-grained helpers for smooth streaming rendering
         if (item.kind === "text") {
             sub.appendText(item.text);
-            // Keep buffer in sync: merge into last text item or push new
             const last = session.feedBuffer.at(-1);
             if (last?.kind === "text") {
                 session.feedBuffer[session.feedBuffer.length - 1] = { ...last, text: last.text + item.text };
@@ -121,7 +116,6 @@ export function sessionPushFeed(runPath, item) {
         }
         sub.pushFeed(item);
     }
-    // No subscriber — always buffer
     if (item.kind === "tool" && (item.status === "done" || item.status === "error") && item.toolCallId) {
         const resultText = item.result;
         if (!resultText)
@@ -178,8 +172,6 @@ export function sessionSetApproval(runPath, pending) {
     if (!session)
         return;
     session.approvalPending = pending;
-    // NOTE: The resolve closure in pending is captured per-promise, so it correctly
-    // resolves even if the subscriber changed (user navigated away and back).
     if (pending) {
         session.subscriber?.onApprovalRequired(pending);
     }

package/dist/ui/ink/theme.js

@@ -70,7 +70,6 @@ function readTerminalProfile() {
         return "dark";
     return undefined;
 }
-/** Common standalone terminals that default to dark profiles when unset. */
 function readTermProgram() {
     const program = (process.env.TERM_PROGRAM ?? "").toLowerCase();
     if (!program)
@@ -115,7 +114,6 @@ function readEditorColorTheme() {
                 return inferred;
         }
         catch {
-            // try next settings file
         }
     }
     return undefined;
@@ -124,7 +122,6 @@ function readSystemAppearance() {
     if (process.platform === "darwin") {
         try {
             const r = Bun.spawnSync(["defaults", "read", "-g", "AppleInterfaceStyle"], { stdout: "pipe", stderr: "ignore" });
-            // The key is absent (and `defaults` exits non-zero) in light mode.
             return r.stdout.toString().trim() === "Dark" ? "dark" : "light";
         }
         catch {
@@ -141,7 +138,6 @@ function readSystemAppearance() {
                 return "light";
         }
         catch {
-            // fall through
         }
         const gtk = process.env.GTK_THEME;
         if (gtk && /dark/i.test(gtk))
@@ -157,14 +153,9 @@ export function detectTerminalTheme() {
         ?? readSystemAppearance()
         ?? "dark";
 }
-/** Input foreground matched to terminal appearance. */
 export function inputForegroundForAppearance(appearance) {
     return appearance === "dark" ? "ansi256(15)" : "ansi256(0)";
 }
-/**
- * Pick colors for rendering. When a locked theme disagrees with the terminal
- * background, follow the terminal so text stays readable.
- */
 export function resolveRenderingAppearance(configTheme, terminalAppearance) {
     if (configTheme === "auto")
         return terminalAppearance;
@@ -179,7 +170,6 @@ export function getTheme(theme) {
     const resolved = theme === "auto" ? detectTerminalTheme() : theme;
     return getThemeFromResolved(resolved);
 }
-/** Poll editor settings + system appearance while theme mode is auto. */
 export function watchAutoThemeChanges(onChange) {
     const cleanups = [];
     onChange();
@@ -191,11 +181,10 @@ export function watchAutoThemeChanges(onChange) {
                     try {
                         unwatchFile(path);
                     }
-                    catch { /* file may be gone */ }
+                    catch { }
                 });
             }
             catch {
-                // settings file not present yet
             }
         }
     }

package/dist/utils/desktop-notify.js

@@ -0,0 +1,26 @@
+/** Best-effort OS desktop notification. Never throws — notifications are a nicety. */
+export async function tryDesktopNotify(title, body) {
+    try {
+        if (process.platform === "darwin") {
+            const script = `display notification ${JSON.stringify(body)} with title ${JSON.stringify(title)}`;
+            await Bun.spawn(["osascript", "-e", script]).exited;
+        }
+        else if (process.platform === "linux" && Bun.which("notify-send")) {
+            await Bun.spawn(["notify-send", title, body]).exited;
+        }
+        else if (process.platform === "win32") {
+            const ps = [
+                `[void][Windows.UI.Notifications.ToastNotificationManager, Windows.UI.Notifications, ContentType=WindowsRuntime]`,
+                `$xml = [Windows.UI.Notifications.ToastNotificationManager]::GetTemplateContent("ToastBasicText02")`,
+                `$xml.GetElementsByTagName("text")[0].InnerText = ${JSON.stringify(title)}`,
+                `$xml.GetElementsByTagName("text")[1].InnerText = ${JSON.stringify(body)}`,
+                `$toast = [Windows.UI.Notifications.ToastNotification]::new($xml)`,
+                `[Windows.UI.Notifications.ToastNotificationManager]::CreateToastNotifier("Scira").Show($toast)`
+            ].join("; ");
+            await Bun.spawn(["powershell", "-NoProfile", "-Command", ps]).exited;
+        }
+    }
+    catch {
+        /* best-effort — never propagate notification failures */
+    }
+}