@sigrun/tui 0.0.0-stage → 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,16 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-10-21
+### Added
+- First published release of the TUI (workspace package of
+  [@sigrun/sigrun](https://github.com/sigrun-ai/sigrun)): fullscreen
+  alt-screen UI with mouse support, per-keymap standard/vim/emacs
+  keymaps, themes from the shared tokens, turn-grouped transcript,
+  composer, help overlay, and OSC 52 clipboard.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Michael MacLeod
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,10 @@
-# Temporary Holding Version
+# @sigrun/tui
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+The sigrun terminal client — a pi-tui based TUI over the sigrun §5 API,
+spawned by the sigrun CLI (`sigrun run`), or standalone against a server
+URL (`sigrun-tui`). Optional companion of
+[@sigrun/sigrun](https://github.com/sigrun-ai/sigrun) (install separately:
+`npm i -g @sigrun/tui`).
+
+Part of the sigrun workspace; published from the repository root as
+`@sigrun/tui`.

package/dist/actions.d.ts

@@ -0,0 +1,78 @@
+/**
+ * The TUI action layer (Task C3, UI refresh): a channel-neutral union of
+ * everything the keymaps, pickers, mouse regions, and slash commands can
+ * ask the shell to do. {@link TuiApp} implements {@link ActionHost} and
+ * owns the focus state the focus/move/open actions drive.
+ *
+ * Focus targets: `composer` (the pi-tui Editor), `list` (the sidebar's
+ * conversation tree), `transcript` (the pane's focusable turns). The
+ * keymap decides WHICH action a key means per focus; the app decides
+ * what the action DOES per focus.
+ */
+/** The three focusable regions. */
+export type Focus = "composer" | "list" | "transcript";
+/** Every dispatchable intent. */
+export type Action = {
+    readonly type: "focus";
+    readonly target: Focus;
+} | {
+    readonly type: "focus-cycle";
+    readonly direction: 1 | -1;
+} | {
+    readonly type: "move";
+    readonly delta: number;
+} | {
+    readonly type: "page";
+    readonly direction: 1 | -1;
+    readonly half: boolean;
+} | {
+    readonly type: "edge";
+    readonly to: "top" | "bottom";
+} | {
+    readonly type: "prompt-jump";
+    readonly delta: 1 | -1;
+} | {
+    readonly type: "toggle-fold";
+} | {
+    readonly type: "open";
+} | {
+    readonly type: "copy";
+} | {
+    readonly type: "fork-here";
+} | {
+    readonly type: "edit-here";
+} | {
+    readonly type: "edit-in-vim";
+} | {
+    readonly type: "picker";
+    readonly kind: "conversation" | "model" | "command";
+} | {
+    readonly type: "new-conversation";
+} | {
+    readonly type: "cycle-thinking";
+} | {
+    readonly type: "search";
+    readonly direction: "forward" | "backward";
+} | {
+    readonly type: "search-next";
+    readonly reverse: boolean;
+} | {
+    readonly type: "answer-interaction";
+} | {
+    readonly type: "cancel-run";
+} | {
+    readonly type: "redraw";
+} | {
+    readonly type: "quit";
+} | {
+    readonly type: "help";
+} | {
+    readonly type: "command-line";
+} | {
+    readonly type: "run-command";
+    readonly line: string;
+};
+/** The dispatch surface {@link TuiApp} implements. */
+export interface ActionHost {
+    dispatch(action: Action): Promise<void>;
+}

package/dist/actions.js

@@ -0,0 +1,12 @@
+/**
+ * The TUI action layer (Task C3, UI refresh): a channel-neutral union of
+ * everything the keymaps, pickers, mouse regions, and slash commands can
+ * ask the shell to do. {@link TuiApp} implements {@link ActionHost} and
+ * owns the focus state the focus/move/open actions drive.
+ *
+ * Focus targets: `composer` (the pi-tui Editor), `list` (the sidebar's
+ * conversation tree), `transcript` (the pane's focusable turns). The
+ * keymap decides WHICH action a key means per focus; the app decides
+ * what the action DOES per focus.
+ */
+export {};

package/dist/api.d.ts

@@ -0,0 +1,147 @@
+/**
+ * The TUI's typed §5 HTTP client (Task 4).
+ *
+ * Wire shapes are the channel contract — imported from the
+ * `@sigrun/shared` package (`views`, plus `SessionMeta`/`SlashCommand`
+ * siblings), the single source of truth shared with the server and the
+ * webui (build-and-webui Task 1: the tui is a pure client of the wire,
+ * never a relative importer of server source).
+ *
+ * Identity seam (Task 2): the configured `user` rides EVERY request as the
+ * `X-Sigrun-User` header; absent/empty user omits it entirely — the
+ * server's naive mode. The bearer token (Task 7) rides every request as
+ * `authorization: Bearer <token>` when configured.
+ *
+ * Fail-loud: a non-2xx rejects with a {@link SigrunApiError} carrying the
+ * status and the server's parsed error body (`{error: ...}`), never a
+ * silent `undefined` the UI could misrender as empty state.
+ */
+import type { CommandRunResponse, CommandsResponse } from "@sigrun/shared/commands";
+import type { JobsResponse, JobRunResponse } from "@sigrun/shared/views";
+import type { JobRevisionWire, JobRunWire } from "@sigrun/shared/jobs";
+import type { SessionMeta, SessionMetaPatch } from "@sigrun/shared/session-meta";
+import type { AbortResponse, AmbientList, CompactResponse, ConfigureResponse, ConversationCreateResponse, ConversationForkResponse, ConversationList, ConversationViewWire, InteractionAnswered, InteractionList, ModelsResponse, SettingsResponse, SubmissionResponse } from "@sigrun/shared/views";
+export type { AbortResponse, AmbientList, AmbientWire, CompactResponse, ConfigureResponse, ConversationCreateResponse, ConversationForkResponse, ConversationList, ConversationSummary, ConversationViewWire, InteractionAnswered, InteractionList, InteractionWire, ModelEntry, ModelsResponse, SettingsResponse, SubmissionResponse, } from "@sigrun/shared/views";
+export type { CommandRunResponse, CommandsResponse, SlashCommand } from "@sigrun/shared/commands";
+export type { JobSpec, JobSchedule, JobAction, JobWire, JobRunWire, JobRevisionWire, } from "@sigrun/shared/jobs";
+export type { JobsResponse, JobRunResponse } from "@sigrun/shared/views";
+export type { SessionMeta, SessionMetaPatch } from "@sigrun/shared/session-meta";
+/** One answer to a pending interaction (the ONE generic route's body). */
+export interface InteractionAnswerInput {
+    readonly ids?: readonly string[];
+    readonly values?: Readonly<Record<string, string | number | boolean>>;
+    readonly text?: string;
+}
+/** `GET /v1/jobs/:id/runs`: the job's runs, newest first. */
+export interface JobRunsResponse {
+    readonly runs: readonly JobRunWire[];
+}
+/** `GET /v1/jobs/:id/revisions`: the job's revisions, newest first. */
+export interface JobRevisionsResponse {
+    readonly revisions: readonly JobRevisionWire[];
+}
+/** The `whenBusy` admission modes the server accepts (spec §7 item 3). */
+export type WhenBusyMode = "steer" | "followUp" | "reject";
+/** A non-2xx response: status + the server's parsed error body. */
+export declare class SigrunApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(method: string, path: string, status: number, body: unknown);
+}
+/** The fetch surface the client needs (the real thing or a test stub). */
+export type FetchLike = (input: string, init?: {
+    readonly method?: string;
+    readonly headers?: Record<string, string>;
+    readonly body?: string;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    json(): Promise<unknown>;
+    text(): Promise<string>;
+}>;
+export interface SigrunClientOptions {
+    /**
+     * The server's origin (e.g. `http://127.0.0.1:PORT`) — the TUI is a
+     * remote client, so unlike the webui there is no same-origin default.
+     */
+    readonly baseUrl: string;
+    /**
+     * The `X-Sigrun-User` identity (Task 2). Absent/empty/whitespace → the
+     * header is omitted entirely (the server's naive mode).
+     */
+    readonly user?: string;
+    /**
+     * A bearer token (Task 7): rides EVERY request as
+     * `authorization: Bearer <token>`. Absent/empty/whitespace → omitted.
+     * The launcher threads `SIGRUN_TOKEN` here — the env beats tui.json.
+     */
+    readonly token?: string;
+    /** Injected for tests; defaults to the ambient `fetch`. */
+    readonly fetch?: FetchLike;
+}
+/** The typed §5 client. See {@link SigrunClientOptions} for the seams. */
+export declare class SigrunClient {
+    #private;
+    constructor(options: SigrunClientOptions);
+    /** `GET /v1/conversations` — all durable conversations (Task 3). */
+    listConversations(): Promise<ConversationList>;
+    /** `GET /v1/conversations/:id` — the full wire view (one frame). */
+    getConversation(id: number): Promise<ConversationViewWire>;
+    /** `POST /v1/conversations` — the new id plus its first view frame. */
+    createConversation(): Promise<ConversationCreateResponse>;
+    /** `POST /v1/conversations/:id/fork` (absent `at` = the newest entry). */
+    forkConversation(id: number, at?: number): Promise<ConversationForkResponse>;
+    /**
+     * `POST /v1/conversations/:id/submissions` — plain text input; 202 at
+     * ADMISSION (§7.1) with the record as it stands. The TUI is
+     * fire-and-forget: the reply arrives as view revisions on the stream,
+     * not from this response.
+     */
+    submit(id: number, text: string, whenBusy?: WhenBusyMode): Promise<SubmissionResponse>;
+    /** `POST /v1/conversations/:id/abort`. */
+    abort(id: number): Promise<AbortResponse>;
+    /**
+     * `POST /v1/conversations/:id/compact` — admits a manual compaction;
+     * the summary entry arrives later as a view revision on the stream.
+     */
+    compact(id: number, instructions?: string): Promise<CompactResponse>;
+    /** `GET /v1/conversations/:id/meta`. */
+    getMeta(id: number): Promise<SessionMeta>;
+    /** `PATCH /v1/conversations/:id/meta` — merges; resolves to the new meta. */
+    patchMeta(id: number, patch: SessionMetaPatch): Promise<SessionMeta>;
+    /** `GET /v1/conversations/:id/interactions` — pending interactions. */
+    listInteractions(id: number): Promise<InteractionList>;
+    /** `POST .../interactions/:callId/answer` — the ONE generic answer route. */
+    answerInteraction(id: number, callId: string, answer: InteractionAnswerInput): Promise<InteractionAnswered>;
+    /** `GET /v1/conversations/:id/ambient`. */
+    getAmbient(id: number): Promise<AmbientList>;
+    /** `GET /v1/commands` — the slash-command catalog (a boot constant). */
+    getCommands(): Promise<CommandsResponse>;
+    /**
+     * `POST /v1/conversations/:id/commands/:name` — invoke an extension
+     * slash command (W5 Task 3): the server runs the winning declaration
+     * and resolves with its optional `{notice}`.
+     */
+    runCommand(id: number, name: string, args?: string): Promise<CommandRunResponse>;
+    /** `GET /v1/settings` — the effective settings (absent file = `{}`). */
+    getSettings(): Promise<SettingsResponse>;
+    /** `GET /v1/models` — the chat-model catalog (the model picker's items). */
+    listModels(): Promise<ModelsResponse>;
+    /**
+     * `POST /v1/conversations/:id/configure` — change the model and/or
+     * thinking level (T9c-i). At least one field is required (the server
+     * rejects an empty change as `invalid_body`).
+     */
+    configure(id: number, body: {
+        readonly model?: string;
+        readonly thinking?: string;
+    }): Promise<ConfigureResponse>;
+    /** `GET /v1/jobs` — the caller-visible jobs (`/jobs`, W4 Task 5). */
+    listJobs(): Promise<JobsResponse>;
+    /** `POST /v1/jobs/:id/run` — fire a job now (write access). */
+    runJob(id: string): Promise<JobRunResponse>;
+    /** `GET /v1/jobs/:id/runs` — the job's runs, newest first. */
+    listJobRuns(id: string, limit?: number): Promise<JobRunsResponse>;
+    /** `GET /v1/jobs/:id/revisions` — the job's revisions, newest first. */
+    listJobRevisions(id: string): Promise<JobRevisionsResponse>;
+}

package/dist/api.js

@@ -0,0 +1,185 @@
+/**
+ * The TUI's typed §5 HTTP client (Task 4).
+ *
+ * Wire shapes are the channel contract — imported from the
+ * `@sigrun/shared` package (`views`, plus `SessionMeta`/`SlashCommand`
+ * siblings), the single source of truth shared with the server and the
+ * webui (build-and-webui Task 1: the tui is a pure client of the wire,
+ * never a relative importer of server source).
+ *
+ * Identity seam (Task 2): the configured `user` rides EVERY request as the
+ * `X-Sigrun-User` header; absent/empty user omits it entirely — the
+ * server's naive mode. The bearer token (Task 7) rides every request as
+ * `authorization: Bearer <token>` when configured.
+ *
+ * Fail-loud: a non-2xx rejects with a {@link SigrunApiError} carrying the
+ * status and the server's parsed error body (`{error: ...}`), never a
+ * silent `undefined` the UI could misrender as empty state.
+ */
+/** A non-2xx response: status + the server's parsed error body. */
+export class SigrunApiError extends Error {
+    status;
+    body;
+    constructor(method, path, status, body) {
+        super(`sigrun api: ${method} ${path} failed with status ${status}`);
+        this.name = "SigrunApiError";
+        this.status = status;
+        this.body = body;
+    }
+}
+/** The typed §5 client. See {@link SigrunClientOptions} for the seams. */
+export class SigrunClient {
+    #baseUrl;
+    #fetch;
+    #headers;
+    constructor(options) {
+        // A trailing slash would double every route's leading one
+        // (`--server http://host/` → `//v1/...`) — normalize once.
+        this.#baseUrl = options.baseUrl.replace(/\/+$/, "");
+        this.#fetch =
+            options.fetch ??
+                ((input, init) => globalThis.fetch(input, init));
+        const user = options.user?.trim();
+        const token = options.token?.trim();
+        this.#headers = {
+            accept: "application/json",
+            ...(user === undefined || user === "" ? {} : { "x-sigrun-user": user }),
+            ...(token === undefined || token === ""
+                ? {}
+                : { authorization: `Bearer ${token}` }),
+        };
+    }
+    async #get(path) {
+        const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+            method: "GET",
+            headers: this.#headers,
+        });
+        if (!response.ok) {
+            throw new SigrunApiError("GET", path, response.status, await response.json().catch(() => undefined));
+        }
+        return (await response.json());
+    }
+    async #send(method, path, body) {
+        const response = await this.#fetch(`${this.#baseUrl}${path}`, {
+            method,
+            headers: { ...this.#headers, "content-type": "application/json" },
+            body: JSON.stringify(body),
+        });
+        if (!response.ok) {
+            throw new SigrunApiError(method, path, response.status, await response.json().catch(() => undefined));
+        }
+        return (await response.json());
+    }
+    /** `GET /v1/conversations` — all durable conversations (Task 3). */
+    listConversations() {
+        return this.#get("/v1/conversations");
+    }
+    /** `GET /v1/conversations/:id` — the full wire view (one frame). */
+    getConversation(id) {
+        return this.#get(`/v1/conversations/${id}`);
+    }
+    /** `POST /v1/conversations` — the new id plus its first view frame. */
+    createConversation() {
+        return this.#send("POST", "/v1/conversations", {});
+    }
+    /** `POST /v1/conversations/:id/fork` (absent `at` = the newest entry). */
+    forkConversation(id, at) {
+        return this.#send("POST", `/v1/conversations/${id}/fork`, {
+            ...(at === undefined ? {} : { at }),
+        });
+    }
+    /**
+     * `POST /v1/conversations/:id/submissions` — plain text input; 202 at
+     * ADMISSION (§7.1) with the record as it stands. The TUI is
+     * fire-and-forget: the reply arrives as view revisions on the stream,
+     * not from this response.
+     */
+    submit(id, text, whenBusy) {
+        return this.#send("POST", `/v1/conversations/${id}/submissions`, {
+            input: [{ type: "text", text }],
+            ...(whenBusy === undefined ? {} : { whenBusy }),
+        });
+    }
+    /** `POST /v1/conversations/:id/abort`. */
+    abort(id) {
+        return this.#send("POST", `/v1/conversations/${id}/abort`, {});
+    }
+    /**
+     * `POST /v1/conversations/:id/compact` — admits a manual compaction;
+     * the summary entry arrives later as a view revision on the stream.
+     */
+    compact(id, instructions) {
+        return this.#send("POST", `/v1/conversations/${id}/compact`, {
+            ...(instructions === undefined || instructions === ""
+                ? {}
+                : { instructions }),
+        });
+    }
+    /** `GET /v1/conversations/:id/meta`. */
+    getMeta(id) {
+        return this.#get(`/v1/conversations/${id}/meta`);
+    }
+    /** `PATCH /v1/conversations/:id/meta` — merges; resolves to the new meta. */
+    patchMeta(id, patch) {
+        return this.#send("PATCH", `/v1/conversations/${id}/meta`, patch);
+    }
+    /** `GET /v1/conversations/:id/interactions` — pending interactions. */
+    listInteractions(id) {
+        return this.#get(`/v1/conversations/${id}/interactions`);
+    }
+    /** `POST .../interactions/:callId/answer` — the ONE generic answer route. */
+    answerInteraction(id, callId, answer) {
+        return this.#send("POST", `/v1/conversations/${id}/interactions/${encodeURIComponent(callId)}/answer`, answer);
+    }
+    /** `GET /v1/conversations/:id/ambient`. */
+    getAmbient(id) {
+        return this.#get(`/v1/conversations/${id}/ambient`);
+    }
+    /** `GET /v1/commands` — the slash-command catalog (a boot constant). */
+    getCommands() {
+        return this.#get("/v1/commands");
+    }
+    /**
+     * `POST /v1/conversations/:id/commands/:name` — invoke an extension
+     * slash command (W5 Task 3): the server runs the winning declaration
+     * and resolves with its optional `{notice}`.
+     */
+    runCommand(id, name, args) {
+        return this.#send("POST", `/v1/conversations/${id}/commands/${encodeURIComponent(name)}`, {
+            args: args ?? "",
+        });
+    }
+    /** `GET /v1/settings` — the effective settings (absent file = `{}`). */
+    getSettings() {
+        return this.#get("/v1/settings");
+    }
+    /** `GET /v1/models` — the chat-model catalog (the model picker's items). */
+    listModels() {
+        return this.#get("/v1/models");
+    }
+    /**
+     * `POST /v1/conversations/:id/configure` — change the model and/or
+     * thinking level (T9c-i). At least one field is required (the server
+     * rejects an empty change as `invalid_body`).
+     */
+    configure(id, body) {
+        return this.#send("POST", `/v1/conversations/${id}/configure`, body);
+    }
+    /** `GET /v1/jobs` — the caller-visible jobs (`/jobs`, W4 Task 5). */
+    listJobs() {
+        return this.#get("/v1/jobs");
+    }
+    /** `POST /v1/jobs/:id/run` — fire a job now (write access). */
+    runJob(id) {
+        return this.#send("POST", `/v1/jobs/${encodeURIComponent(id)}/run`, {});
+    }
+    /** `GET /v1/jobs/:id/runs` — the job's runs, newest first. */
+    listJobRuns(id, limit) {
+        return this.#get(`/v1/jobs/${encodeURIComponent(id)}/runs` +
+            (limit === undefined ? "" : `?limit=${limit}`));
+    }
+    /** `GET /v1/jobs/:id/revisions` — the job's revisions, newest first. */
+    listJobRevisions(id) {
+        return this.#get(`/v1/jobs/${encodeURIComponent(id)}/revisions`);
+    }
+}

package/dist/clipboard.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Terminal clipboard (Task C3, UI refresh): OSC 52 writes the system
+ * clipboard through the terminal emulator. Inside tmux the sequence must
+ * be DCS-wrapped with every ESC doubled, or tmux eats it.
+ *
+ * `copyToTerminal` writes the sequence to the terminal; the app flashes
+ * "Copied" in the status bar on top of this.
+ */
+/** The environment slice the tmux detection reads. */
+export interface ClipboardEnv {
+    readonly TMUX?: string;
+}
+/** The OSC 52 sequence for `text` (base64 UTF-8), tmux-wrapped when needed. */
+export declare function osc52(text: string, env?: ClipboardEnv): string;
+/** The terminal surface the copy needs (pi-tui's `Terminal.write`). */
+export interface ClipboardTerminal {
+    write(data: string): void;
+}
+/** Write `text` to the system clipboard via the terminal. */
+export declare function copyToTerminal(terminal: ClipboardTerminal, text: string, env?: ClipboardEnv): void;

package/dist/clipboard.js

@@ -0,0 +1,19 @@
+/**
+ * Terminal clipboard (Task C3, UI refresh): OSC 52 writes the system
+ * clipboard through the terminal emulator. Inside tmux the sequence must
+ * be DCS-wrapped with every ESC doubled, or tmux eats it.
+ *
+ * `copyToTerminal` writes the sequence to the terminal; the app flashes
+ * "Copied" in the status bar on top of this.
+ */
+/** The OSC 52 sequence for `text` (base64 UTF-8), tmux-wrapped when needed. */
+export function osc52(text, env = process.env) {
+    const seq = `\x1b]52;c;${Buffer.from(text, "utf8").toString("base64")}\x07`;
+    if (env.TMUX === undefined || env.TMUX === "")
+        return seq;
+    return `\x1bPtmux;\x1b${seq.replaceAll("\x1b", "\x1b\x1b")}\x1b\\`;
+}
+/** Write `text` to the system clipboard via the terminal. */
+export function copyToTerminal(terminal, text, env = process.env) {
+    terminal.write(osc52(text, env));
+}

package/dist/editor-launch.d.ts

@@ -0,0 +1,34 @@
+export declare const VIM_NAMES: readonly string[];
+/** True when the basename of the first whitespace-separated token is a vim binary. */
+export declare function isVimFamily(command: string): boolean;
+/**
+ * Resolve a vim-family editor: configured → VISUAL → EDITOR (each used only
+ * when vim-family), then nvim/vim/vi on PATH. Undefined when nothing qualifies.
+ */
+export declare function resolveVimEditor(opts: {
+    configured?: string;
+    env: NodeJS.ProcessEnv;
+    which(name: string): string | undefined;
+}): string | undefined;
+/**
+ * Edit `text` in a vim-family editor via a temp file, suspending the TUI for
+ * the duration. The temp file is always removed; on failure the draft is
+ * untouched and stop/start remain balanced.
+ */
+export declare function editInVim(opts: {
+    text: string;
+    editor: string;
+    tui: {
+        stop(): void;
+        start(): void;
+        requestRender(force?: boolean): void;
+    };
+    spawnSync?: typeof import("node:child_process").spawnSync;
+    tmpDir?: string;
+}): {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    reason: string;
+};

package/dist/editor-launch.js

@@ -0,0 +1,70 @@
+import { spawnSync as realSpawnSync } from "node:child_process";
+import { randomBytes } from "node:crypto";
+import { readFileSync, unlinkSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { basename, join } from "node:path";
+export const VIM_NAMES = ["vim", "nvim", "vi"];
+/** True when the basename of the first whitespace-separated token is a vim binary. */
+export function isVimFamily(command) {
+    const first = command.trim().split(/\s+/)[0];
+    if (!first)
+        return false;
+    return VIM_NAMES.includes(basename(first));
+}
+/**
+ * Resolve a vim-family editor: configured → VISUAL → EDITOR (each used only
+ * when vim-family), then nvim/vim/vi on PATH. Undefined when nothing qualifies.
+ */
+export function resolveVimEditor(opts) {
+    for (const candidate of [opts.configured, opts.env.VISUAL, opts.env.EDITOR]) {
+        if (candidate && isVimFamily(candidate))
+            return candidate;
+    }
+    for (const name of ["nvim", "vim", "vi"]) {
+        const found = opts.which(name);
+        if (found)
+            return found;
+    }
+    return undefined;
+}
+/**
+ * Edit `text` in a vim-family editor via a temp file, suspending the TUI for
+ * the duration. The temp file is always removed; on failure the draft is
+ * untouched and stop/start remain balanced.
+ */
+export function editInVim(opts) {
+    const spawn = opts.spawnSync ?? realSpawnSync;
+    const file = join(opts.tmpDir ?? tmpdir(), `sigrun-prompt-${randomBytes(8).toString("hex")}.md`);
+    writeFileSync(file, opts.text, { encoding: "utf8", mode: 0o600 });
+    // The editor string splits on whitespace — quoted paths with spaces in
+    // the command or its arguments are NOT supported (a known limitation).
+    const [command, ...args] = opts.editor.trim().split(/\s+/);
+    try {
+        opts.tui.stop();
+        const result = spawn(command, [...args, file], { stdio: "inherit" });
+        if (result.error) {
+            return { ok: false, reason: `editor failed to launch: ${result.error.message}` };
+        }
+        if (result.status !== 0) {
+            return { ok: false, reason: `editor exited with status ${result.status}` };
+        }
+        let text;
+        try {
+            text = readFileSync(file, "utf8");
+        }
+        catch {
+            return { ok: false, reason: "edited file missing or unreadable" };
+        }
+        return { ok: true, text };
+    }
+    finally {
+        opts.tui.start();
+        opts.tui.requestRender(true);
+        try {
+            unlinkSync(file);
+        }
+        catch {
+            // already gone (editor deleted it) — nothing to clean up
+        }
+    }
+}

package/dist/keymaps/emacs.d.ts

@@ -0,0 +1,18 @@
+/**
+ * The emacs keymap (Task C5, UI refresh): modeless, chord-driven. `C-x`
+ * ("\x18") arms a 1 000 ms chord: `C-x b` conversation picker, `C-x o`
+ * focus cycle, `C-x C-c` quit, `C-x k` a consumed no-op (a mismatched
+ * follow-up is the emacs undefined-key beep — consumed, never typed).
+ * `M-x` opens the command picker; `C-s` / `C-r` search forward / backward
+ * (the app's search overlay turns them into next / previous while open);
+ * `C-g` cancels a live run, closes the search/picker (it passes through
+ * to the open overlay), or focuses the composer. `M-p` / `M-n` jump
+ * between prompts; `M-w` copy, `M-f` fork, `M-e` edit are outside-
+ * composer actions (in the composer `M-f` is the editor's word-forward —
+ * all three pass). `C-n` / `C-p` move outside the composer; `C-o`
+ * answers an interaction, `C-l` redraws, `C-h` opens the key reference.
+ * Every {@link RESERVED_KEYS} chord passes in every focus — ctrl+b is
+ * NEVER bound (no `C-x C-b` either).
+ */
+import { type Keymap } from "./types.js";
+export declare function createEmacsKeymap(): Keymap;