dsh-coding-sidebar 1.0.7 → 1.0.8

package/lib/types/agent-pty.d.ts

@@ -15,6 +15,20 @@ export declare function clampDims(cols: number, rows: number): {
     cols: number;
     rows: number;
 };
+/**
+ * Arm the Windows pre-ready resize gate for one freshly spawned pty.
+ * No-op on POSIX and for injected ptys without `onData`.
+ */
+export declare function armPtyResizeGate(pty: IPty): void;
+/**
+ * Best-effort resize for WebSocket-driven terminal views. Layout animation
+ * can briefly produce unusable dimensions, and node-pty can reject a resize
+ * after the socket setup's outer try/catch has returned. Ignore that one
+ * frame so the host stays alive and a later valid measurement can retry.
+ * Returns whether node-pty accepted the resize (or parked it for replay on
+ * the first output — the Windows pre-ready window).
+ */
+export declare function tryResizePty(pty: Pick<IPty, 'resize'>, cols: number, rows: number): boolean;
 /**
  * Serializable snapshot of one agent terminal — the shape the model sees
  * through `terminal_list` and the sidebar sees through the push endpoint.
@@ -36,6 +50,15 @@ export interface AgentTerminalSnapshot {
     exitCode?: number | null;
     /** Exit signal name if the process was killed by a signal; null otherwise. */
     exitSignal?: string | null;
+    /**
+     * The model's active `terminal_wait_for` on this terminal (the sidebar
+     * renders the wait banner from it). Present only while a wait is
+     * registered; carries the LATEST wait when several overlap.
+     */
+    waiting?: {
+        needle: string;
+        since: number;
+    };
 }
 /** One live agent terminal. */
 export interface AgentTerminalHandle {
@@ -59,6 +82,17 @@ export interface AgentTerminalHandle {
     exitCode?: number | null;
     /** Exit signal number once known (POSIX only; undefined on Windows). */
     exitSignal?: number | null;
+    /** Active wait_for registrations (skip bookkeeping; empty while idle). */
+    waits: AgentTerminalActiveWait[];
+}
+/** One active wait_for registration on a handle (banner + skip bookkeeping). */
+export interface AgentTerminalActiveWait {
+    /** The needle being awaited (shown on the sidebar wait banner). */
+    needle: string;
+    /** Epoch ms when the wait registered (age display / debugging). */
+    since: number;
+    /** Flipped by `skipWait()`; the waiting poll returns `skipped` within one tick. */
+    skipped: boolean;
 }
 /** Read result shape (mirrors the official tool-pty terminal_read contract). */
 export interface AgentTerminalReadResult {
@@ -73,14 +107,18 @@ export interface AgentTerminalReadResult {
 }
 /** Outcome of {@link AgentPtyRegistry.waitFor}. */
 export type AgentTerminalWaitResult = {
-    /** The needle was found in the transcript. */
+    /** The pattern that was awaited. */
     kind: 'found';
-    /** The matched substring. */
     needle: string;
     /** 0-based line index (in the retained transcript) where the needle first appeared. */
     line: number;
     /** 0-based column index within that line where the match starts. */
     column: number;
+    /**
+     * The text that actually matched — for multi-outcome patterns
+     * (e.g. `(BUILD_OK|BUILD_FAIL)`) this tells which alternative matched.
+     */
+    match: string;
     /** Elapsed wall-clock milliseconds from the wait start to the match. */
     elapsedMs: number;
 } | {
@@ -101,6 +139,11 @@ export type AgentTerminalWaitResult = {
     exitCode?: number | null;
     /** The exit signal name, if the process was killed by a signal. */
     exitSignal?: string | null;
+} | {
+    /** The user skipped the wait from the sidebar banner. */
+    kind: 'skipped';
+    /** The needle that was awaited. */
+    needle: string;
 };
 /** Snapshot projection of a handle (drops the pty reference and transcript). */
 export declare function snapshotOf(handle: AgentTerminalHandle): AgentTerminalSnapshot;
@@ -181,12 +224,27 @@ export declare class AgentPtyRegistry {
      * make event-driven wakeups unreliable. A 50ms poll is fast enough for
      * interactive use and simple enough to be obviously correct.
      * @param uuid - terminal to watch.
-     * @param needle - substring to search for (case-sensitive, verbatim).
+     * @param needle - JavaScript regular expression to search for
+     *   (case-sensitive); a pattern that fails to compile falls back to
+     *   verbatim substring matching. May cover several outcomes at once
+     *   (e.g. `(BUILD_OK|BUILD_FAIL)` for build success vs failure) — the
+     *   returned `match` reports the text that actually matched, so callers
+     *   can tell which outcome hit.
      * @param timeoutMs - max wait; default 10000 (10s). Clamped to ≥100ms.
      * @param signal - caller-owned cancellation; aborts the wait re-throwing.
-     * @returns one of `found` / `timeout` / `exited`.
+     *   A wait can also be skipped by the user from the sidebar banner
+     *   (`skipWait`), which resolves it with `{kind:'skipped'}`.
+     * @returns one of `found` / `timeout` / `exited` / `skipped`.
      */
     waitFor(uuid: string, needle: string, timeoutMs?: number, signal?: AbortSignal): Promise<AgentTerminalWaitResult>;
+    /**
+     * Mark every active wait on one terminal as skipped (the sidebar banner's
+     * skip button). Each waiting poll loop observes its record's flag within
+     * one 50ms tick and returns `{kind:'skipped'}`. Idempotent: 0 when nothing
+     * is waiting (a stale banner racing a wait that already resolved).
+     * @returns the number of waits that transitioned to skipped.
+     */
+    skipWait(uuid: string): number;
     /**
      * Send a POSIX signal to a terminal's foreground process.
      *

package/lib/types/bundle-route.d.ts

@@ -1,6 +1,6 @@
 import type { Context, SidebarHttpRequest, SidebarHttpResponse } from './context-types.ts';
 /** The chunk names the client may request (mirror of src/client/chunk-loader.ts). */
-export declare const CHUNK_NAMES: readonly ["terminal", "editor"];
+export declare const CHUNK_NAMES: readonly ["terminal", "editor", "locale"];
 export type ChunkName = (typeof CHUNK_NAMES)[number];
 /**
  * Build the /sidebar/bundle route handler. `fence` is the shared browser-

package/lib/types/client/EditorHost.d.ts

@@ -9,5 +9,5 @@ export declare function EditorHost(props: {
     expanded: string[];
     revealed: string[];
     onToggleDir: (path: string) => void;
-    onReferenceFile: (path: string) => void;
+    onReferenceFile: (path: string, isDir: boolean) => void;
 }): import("react").JSX.Element;

package/lib/types/client/FileTree.d.ts

@@ -27,8 +27,8 @@ export declare function FileTree(props: {
     onOpenWith?: (targetId: string, path: string) => void;
     /** Toggle one target's pinned state (the submenu row's pushpin). */
     onToggleOpenWithPin?: (targetId: string) => void;
-    /** Insert `@<relative path>` into the composer draft. */
-    onReferenceFile: (path: string) => void;
+    /** Insert `@<relative path>` into the composer draft (file vs directory). */
+    onReferenceFile: (path: string, isDir: boolean) => void;
     /** Bump to wipe the level cache and reload the visible set. */
     refreshTick: number;
     /** Upload into `dir` (absolute, inside the workspace); runs in the caller. */

package/lib/types/client/TreePanel.d.ts

@@ -17,7 +17,7 @@ export declare function TreePanel(props: {
     openWithSsh?: boolean;
     onOpenWith?: (targetId: string, path: string) => void;
     onToggleOpenWithPin?: (targetId: string) => void;
-    onReferenceFile: (path: string) => void;
+    onReferenceFile: (path: string, isDir: boolean) => void;
     /** Full-window presentation: the panel fills its host instead of docking
      *  at a fixed width. */
     full?: boolean;

package/lib/types/client/chunk-loader.d.ts

@@ -48,7 +48,7 @@
  * client.js); an edit that does land while a core HMR happens is caught by
  * the ETag comparison on the next activation.
  */
-export type ChunkName = 'terminal' | 'editor';
+export type ChunkName = 'terminal' | 'editor' | 'locale';
 /** The module exports a chunk factory provides (namespace-ish record). */
 export type ChunkExports = Record<string, unknown>;
 /**

package/lib/types/client/chunks/locale.d.ts

@@ -0,0 +1,3 @@
+/** Every non-zh/en dictionary keyed by its override id, ready for the
+ *  better-locale store's `register(ns, dicts)`. */
+export declare const localeDicts: Record<string, Record<string, string>>;

package/lib/types/client/conversation-draft.d.ts

@@ -1,14 +1,95 @@
 /**
- * Append text to the current session's composer draft through the
+ * Insert text into the current session's composer draft through the
  * conversation service — the shared path behind the explorer's @-reference
  * button and the viewer selection popup. The service is resolved lazily
  * through `ctx.get` (the inject-free read the app's own plugins use); a
  * missing service or scope degrades to a logged no-op, never a crash.
+ *
+ * File references additionally use DSH's own structured insert event
+ * (`slash/input-insert-reference`, see `insertFileReference`) instead of
+ * plain draft text: the native `@file` picker emits this event, and the
+ * conversation input machine mints one occurrence whose chip covers the
+ * whole reference. Plain text `@folder/file.ts` only ever gets DSH's
+ * folder-ref decoration (`@folder/`) — the file name stays undecorated — so
+ * plain append is the fallback, not the primary path, for files.
+ *
+ * Insert position (upstream issue #425): the draft store only exposes the
+ * whole string (`getSnapshot().draft` + `setDraft(text)`) — there is no
+ * caret API on the conversation service. The composer's `<textarea>` keeps
+ * its last selection even while unfocused, so the live caret is probed from
+ * the DOM (guarded by a value-sync check), and the text is spliced at that
+ * position, replacing any live selection — with whitespace-aware joins, an
+ * insert into the middle of a sentence keeps single-space separation like
+ * the append path. An unknown/stale caret falls back to appending at the
+ * end (the pre-fix behavior).
+ *
+ * The caret is also *restored* after the insert: committing a programmatic
+ * draft change resets the controlled textarea's caret (observed landing at
+ * the start of the value), which would make every later insert probe the
+ * reset position and drift the stack (A|B + C + D ended up as |DACB). The
+ * placement (`placeComposerCaretAfterInsert`) puts the caret right after the
+ * inserted text once the value commit lands — the index accounts for the
+ * separating space on the left, so stacked inserts stay at their running
+ * position (A|B + C + D → ACD|B).
  */
 import type { Context } from '../context-types.ts';
+/** A resolved composer caret/selection in draft coordinates. */
+export interface DraftCaret {
+    start: number;
+    end: number;
+}
 /**
- * Append `text` to the session's composer draft (space-separated, like the
- * @-mentions). Returns false — and logs — when the conversation service or
- * the session scope is unavailable.
+ * The spliced draft string (see {@link spliceInsert}); pure string math.
+ */
+export declare function insertAtCaret(draft: string, text: string, caret: DraftCaret | null): string;
+/**
+ * Resolve the composer's live caret from its DOM `<textarea>`. The draft
+ * store has no caret API, so the sidebar reads the composed input's selection
+ * directly; the value-sync check (`el.value === draft`) discards stale or
+ * wrong-composer reads — a caret must never be applied against a draft it
+ * was not measured on.
+ *
+ * Returns null when the composer is missing, disabled/read-only, out of
+ * sync with the store draft, or has no measurable selection (odd hosts
+ * report null selectionStart/End).
+ */
+export declare function probeComposerCaret(draft: string): DraftCaret | null;
+/**
+ * Restore the composer caret to `caretIndex` after a programmatic
+ * `setDraft` commit. A controlled textarea update resets the caret (React
+ * commits the value asynchronously and the browser moves the caret to the
+ * start/end), so the placement is scheduled and retried across at most two
+ * animation frames (setTimeout fallback), and only applied when the textarea
+ * still matches `expectedDraft` — a newer edit or a different composer wins
+ * the race untouched. The caret is clamped into the value bounds, mirroring
+ * how browsers clamp type-in positions.
+ */
+export declare function placeComposerCaretAfterInsert(expectedDraft: string, caretIndex: number): void;
+/**
+ * Insert `text` into the session's composer draft at the composer's live
+ * caret (see {@link probeComposerCaret}), falling back to appending at the
+ * end when the caret cannot be resolved. Returns false — and logs — when the
+ * conversation service or the session scope is unavailable.
  */
 export declare function appendToDraft(ctx: Context, sessionId: string, text: string): boolean;
+/**
+ * The DSH `@file` spelling for one relative path, mirroring the host grammar
+ * (`formatFileMention` in `@deepseek-ai/dsh-file-reference`): plain when
+ * there is no whitespace, quoted when there is, and `undefined` when the
+ * path contains a control character or an embedded quote the editor grammar
+ * cannot represent.
+ */
+export declare function fileMention(relativePath: string): {
+    mention: string;
+    label: string;
+} | undefined;
+/**
+ * Insert one FILE reference as a structured chip (like DSH's own `@` picker).
+ * The chip displays `@<basename>` but serializes to `@<relative path>` on
+ * send, so the reference stays a single link from trigger to basename.
+ *
+ * Directories are NOT handled here: DSH's folder grammar wants the trailing
+ * slash as plain text (`@dir/`) so completion can descend, which
+ * `appendToDraft` already covers.
+ */
+export declare function insertFileReference(ctx: Context, sessionId: string, relativePath: string): boolean;

package/lib/types/client/locales.d.ts

@@ -94,6 +94,7 @@ export declare const zh: {
     terminalDepsFailed: string;
     terminalDepsHint: string;
     terminalDepsProfile: string;
+    terminalShellNotFound: string;
     refresh: string;
     refreshUnsavedConfirm: string;
     save: string;
@@ -362,26 +363,6 @@ export declare const en: Record<keyof typeof zh, string>;
  * (`'sidebar'` is taken by DSH's own ui-sidebar, hence this distinct name).
  */
 export declare const LOCALE_NS = "betterSidebar";
-/** The ja dictionary (key-set-equal to zh, enforced by the type annotation). */
-export declare const ja: Record<keyof typeof zh, string>;
-export declare const de: Record<keyof typeof zh, string>;
-export declare const fr: Record<keyof typeof zh, string>;
-export declare const pt: Record<keyof typeof zh, string>;
-export declare const ko: Record<keyof typeof zh, string>;
-export declare const ar: Record<keyof typeof zh, string>;
-export declare const hi: Record<keyof typeof zh, string>;
-export declare const id: Record<keyof typeof zh, string>;
-export declare const tr: Record<keyof typeof zh, string>;
-export declare const vi: Record<keyof typeof zh, string>;
-export declare const th: Record<keyof typeof zh, string>;
-export declare const ru: Record<keyof typeof zh, string>;
-export declare const it: Record<keyof typeof zh, string>;
-export declare const nl: Record<keyof typeof zh, string>;
-export declare const sv: Record<keyof typeof zh, string>;
-export declare const pl: Record<keyof typeof zh, string>;
-export declare const zhHK: Record<keyof typeof zh, string>;
-export declare const zhTW: Record<keyof typeof zh, string>;
-export declare const zhMO: Record<keyof typeof zh, string>;
 /**
  * The better-locale override store attached by the client apply
  * (absent → no override; the zh/en chain runs). The store's `active`

package/lib/types/client/selection-popup.d.ts

@@ -0,0 +1,58 @@
+/**
+ * The floating "add selection to conversation" popup shared by the text
+ * viewer: a viewport-anchored button portaled to `document.body`, kept alive
+ * across the selection gesture and committed on click.
+ *
+ * Dismissal contract (upstream issue #425): the popup must never outlive its
+ * editor surface. The sidebar keeps every tab MOUNTED — switching tabs only
+ * flips the pane cell to `display:none` and collapsing the panel translates
+ * it off-screen — while the portaled `position:fixed` button stays pinned to
+ * its viewport anchor, ignoring both. The caller already hides on surface
+ * scrolls, selection collapse and content swaps; this hook adds the global
+ * dismissal that covers everything else:
+ *
+ * - any `mousedown` outside the button (tab bar, composer, another pane,
+ *   the collapse toggle, …) closes it;
+ * - `Escape` closes it;
+ * - the document going hidden (`visibilitychange`) or the window losing
+ *   focus closes it;
+ * - an `IntersectionObserver` on the editor surface closes it as soon as the
+ *   surface leaves the viewport — the tab-switch (`display:none`) and
+ *   panel-collapse (translated off-screen) paths have no DOM events of their
+ *   own, so the geometry signal is the only reliable one.
+ *
+ * The button's own `mousedown` is never treated as an outside click: the
+ * caller preventDefaults it to keep the selection/caret alive until the
+ * click commits (the hook's capture-phase listener runs first and must not
+ * hide for it).
+ */
+import { type RefObject } from 'react';
+/** The floating "add to conversation" action: payload + viewport anchor. */
+export interface SelectionPopup {
+    insert: string;
+    left: number;
+    top: number;
+}
+export interface SelectionPopupOptions {
+    /** Commit the payload into the composer draft (button click). */
+    onCommit(insert: string): void;
+    /**
+     * The DOM surface that must stay on screen for the popup to live: the
+     * CodeMirror host element. Called lazily (refs are null until the content
+     * loads).
+     */
+    getSurface(): HTMLElement | null;
+}
+export interface SelectionPopupControls {
+    /** The current popup (null = hidden). */
+    popup: SelectionPopup | null;
+    /** Attach to the portaled button element. */
+    buttonRef: RefObject<HTMLButtonElement>;
+    /** Anchor the popup above a selection (viewport-clamped). */
+    show(insert: string, left: number, top: number): void;
+    /** Hide the popup (idempotent). */
+    hide(): void;
+    /** The button's click: commit the stored payload, then hide. */
+    commit(): void;
+}
+export declare function useSelectionPopup(options: SelectionPopupOptions): SelectionPopupControls;

package/lib/types/client/service.d.ts

@@ -132,7 +132,7 @@ export interface TabComponentProps {
     /** The explorer's reveal-highlight set (ExplorerView; "Show in folder" targets). */
     revealed?: string[];
     onToggleDir?: (path: string) => void;
-    onReferenceFile?: (path: string) => void;
+    onReferenceFile?: (path: string, isDir: boolean) => void;
     onOpenFile?: (path: string) => void;
     onOpenDiff?: (tab: SidebarTab) => void;
     onSubagentJump?: (childSessionId: string) => void;

package/lib/types/client/terminal-font.d.ts

@@ -60,12 +60,35 @@ export declare const ICON_FONT_FALLBACKS: readonly string[];
  * @returns the stack with icon fallbacks merged in.
  */
 export declare function withIconFontFallbacks(stack: string): string;
+/**
+ * Guarantee the stack ends in a generic family, so a font the browser cannot
+ * resolve degrades to a monospace one.
+ *
+ * Without this a stack of unresolvable names (a misspelled family, or one only
+ * installed on the machine running the shell rather than the one running the
+ * browser) falls through to the browser's *standard* font, which is
+ * proportional — xterm then measures its cell from a proportional advance and
+ * the whole grid breaks, rather than merely losing the requested typeface.
+ *
+ * This does not sniff whether the named families exist (an explicit non-goal
+ * of the terminal font design): it only terminates the stack. A stack that
+ * already names a generic family is returned untouched, so a user who
+ * deliberately wrote one keeps it. Generics are matched unquoted only — a
+ * quoted `"monospace"` is a family *name*, not the keyword.
+ *
+ * @param stack - the resolved font-family value.
+ * @returns the stack, ending in a generic family.
+ */
+export declare function withMonospaceFallback(stack: string): string;
 /**
  * Resolve the xterm font options for the given prefs.
  *
  * The base family keeps its existing precedence — user pref > theme code
- * font > built-in stack — and then {@link withIconFontFallbacks} tops it up
- * so prompt icons resolve regardless of which base won.
+ * font > built-in stack. {@link withMonospaceFallback} then terminates the
+ * stack with a generic family so an unresolvable name degrades to a
+ * monospace instead of the proportional standard font, and finally
+ * {@link withIconFontFallbacks} tops it up so prompt icons resolve
+ * regardless of which base won.
  *
  * @param prefs - the current side card preferences.
  * @param themeFontFamily - the app's theme code font (`--ds-font-family-code`

package/lib/types/context-types.d.ts

@@ -430,10 +430,12 @@ export interface SidebarLocaleService {
 }
 /** The composer draft face the sidebar reaches through `ctx.conversation.input`. */
 export interface SidebarSessionInput {
-    /** The live input store (draft read for append). */
+    /** The live input store (draft read for append). `draftRev` is the machine's
+     *  span-CAS revision — required to mint a structured file-reference chip. */
     state: {
         getSnapshot(): {
             draft: string;
+            draftRev?: number;
         };
     };
     /** Replace the draft text (the input machine's single public write path). */

package/lib/types/index.d.ts

@@ -45,3 +45,12 @@ export interface SidebarSettingsFace {
  * {@link resolveSidebarConfig}.
  */
 export declare function apply(ctx: Context, config?: SidebarConfig): void;
+/**
+ * The WS close reason for a failed terminal attach. A missing configured
+ * shell gets a SHORT machine-readable marker (`shell-not-found:<name>`,
+ * capped by BYTES — a WS close reason allows at most 123 bytes, which `ws`
+ * validates with `Buffer.byteLength`) that the client maps to a localized,
+ * actionable banner; every other failure keeps the raw message (the
+ * model-side tool errors read it verbatim).
+ */
+export declare function wsCloseReasonOf(error: unknown): string;

package/lib/types/prefs-shared.d.ts

@@ -14,14 +14,16 @@ export interface SidebarPrefs {
     /** Default panel width as a percent of the window width (20–60). */
     defaultWidthPercent: number;
     /**
-     * Whether the sidebar auto-activates (opens the panel) and expands the
-     * Subagent page when the current conversation spawns a new subagent.
+     * Whether the sidebar auto-activates the Subagent page when the current
+     * conversation spawns a new subagent. Wide viewports also open the panel;
+     * narrow viewports prepare the tab without opening the full-screen drawer.
      */
     autoOpenSubagent: boolean;
     /**
-     * Whether the sidebar auto-activates (opens the panel) and expands the
-     * Jobs page when a NEW background job appears for the current
-     * conversation (any new job id, not just the first one).
+     * Whether the sidebar auto-activates the Jobs page when a NEW background
+     * job appears for the current conversation (any new job id, not just the
+     * first one). Wide viewports also open the panel; narrow viewports prepare
+     * the tab without opening the full-screen drawer.
      */
     autoOpenJobs: boolean;
     /**

package/lib/types/pty-manager.d.ts

@@ -134,6 +134,41 @@ export interface ShellResolutionOptions {
     /** File-existence probe override (defaults to `existsSync`). */
     exists?: (path: string) => boolean;
 }
+/** Inputs for resolving one configured shell into the executable path passed
+ * to node-pty. Injectable so the Windows-only search semantics stay covered
+ * on POSIX CI runners. */
+export interface ShellExecutableResolutionOptions {
+    /** Platform override (defaults to `process.platform`). */
+    platform?: NodeJS.Platform;
+    /** Environment override; Windows reads PATH/PATHEXT/SystemRoot plus the
+     * PowerShell well-known-location variables. */
+    env?: NodeJS.ProcessEnv;
+    /** File-existence probe override (defaults to `existsSync`). */
+    exists?: (path: string) => boolean;
+}
+/**
+ * Resolve the configured shell executable before handing it to node-pty.
+ *
+ * Windows' native backend does not consistently apply the shell's PATHEXT
+ * lookup to a bare value (`pwsh` / `cmd` can fail with the opaque
+ * `File not found:` error), so perform the lookup ourselves: an explicit
+ * path is accepted as-is when it exists (or with a PATHEXT suffix when the
+ * user omitted `.exe`), and a bare name is searched through PATH, System32,
+ * and PowerShell's known install directories.
+ *
+ * POSIX node-pty uses `execvp`, so a bare name would already follow PATH —
+ * but a wrong name made the pty die with a bare
+ * `[process exited with code N]`, so probe like Windows anyway: a path with
+ * a separator must exist; a bare name is searched along PATH (the colon
+ * form is fixed by the platform). A miss is a clear, actionable
+ * `shell-not-found` error instead of a cryptic exit code.
+ *
+ * @param shell - the configured shell (settings page or yaml `config.shell`).
+ * @param options - platform/env/exists injection points for tests.
+ * @returns the executable path passed to node-pty.
+ * @throws {SidebarError} `shell-not-found` when no candidate exists.
+ */
+export declare function resolveShellExecutable(shell: string, options?: ShellExecutableResolutionOptions): string;
 /**
  * The interactive shell for this platform, resolved like a terminal
  * emulator: an explicitly configured shell (the `shell` config field) wins,
@@ -166,3 +201,21 @@ export declare function shellDisplayName(shell: string): string;
  * defaults entirely, giving deployments full control over shell startup.
  */
 export declare function shellSpawnArgs(configured?: string[]): string[];
+/**
+ * Strip ONE pair of surrounding quotes from a configured shell path. Users
+ * paste Windows paths with spaces pre-quoted (`"C:\Program Files\…"`); the
+ * quotes are shell-input syntax, not part of the path. Unpaired quotes and
+ * shorter values stay verbatim.
+ */
+export declare function unquotePath(value: string): string;
+/**
+ * Split a settings-page shell-arguments string into argv with quote-aware
+ * grouping: `'…'` / `"…"` group whitespace, and characters inside quotes are
+ * LITERAL — a backslash is never an escape, so Windows paths survive intact
+ * (`-File "C:\my init\init.ps1"` → three tokens, the last containing spaces).
+ * The price is that an argument containing a literal quote character cannot
+ * be expressed; shell startup arguments never need one. An unclosed quote
+ * folds the remainder into the current token (settings input stays
+ * forgiving); an empty quote pair yields no argument.
+ */
+export declare function splitShellArgs(input: string): string[];

package/lib/types/wire.d.ts

@@ -6,12 +6,16 @@
  */
 import type { SidebarHttpRequest, SidebarHttpResponse } from './context-types.ts';
 /** Machine-readable error codes of the sidebar API. */
-export type SidebarErrorCode = 'bad-request' | 'not-found' | 'forbidden' | 'method-error' | 'too-large' | 'fs-error' | 'git-error' | 'pty-error' | 'pty-deps-missing' | 'job-error' | 'cdp-down' | 'sidechat-error' | 'subagents-unavailable' | 'settings-rejected' | 'settings-conflict' | 'internal';
+export type SidebarErrorCode = 'bad-request' | 'not-found' | 'forbidden' | 'method-error' | 'too-large' | 'fs-error' | 'git-error' | 'pty-error' | 'pty-deps-missing' | 'shell-not-found' | 'job-error' | 'cdp-down' | 'sidechat-error' | 'subagents-unavailable' | 'settings-rejected' | 'settings-conflict' | 'internal';
 /** One API failure with its wire code and HTTP status. */
 export declare class SidebarError extends Error {
     readonly code: SidebarErrorCode;
     readonly status: number;
-    constructor(code: SidebarErrorCode, message: string, status?: number);
+    /** Optional structured context (e.g. `{ shell }` for shell-not-found). */
+    readonly meta?: Record<string, string> | undefined;
+    constructor(code: SidebarErrorCode, message: string, status?: number, 
+    /** Optional structured context (e.g. `{ shell }` for shell-not-found). */
+    meta?: Record<string, string> | undefined);
 }
 /** Success envelope of one API method. */
 export interface SidebarOk<T> {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "dsh-coding-sidebar",
-  "version": "1.0.7",
+  "version": "1.0.8",
   "description": "DSH web plugin: a VSCode-like right sidebar (explorer / editor / terminal / git / browser), isolated per conversation session. Exposes the betterSidebar service for other plugins to register sidebar tabs and file viewers. KCoder-maintained fork of DSH-better-sidebar 0.17.2 (bottom panel removed, upstream-decoupled release line).",
   "type": "module",
   "repository": {