windows-development-sandbox 1.5.0 → 1.9.0

package/dist/cli/tui/list/list-screen.js

@@ -1,18 +1,27 @@
 import { Text } from '../text.js';
 import { Theme } from '../theme.js';
+/** Lists longer than this say how to search. */
+const LONG_LIST = 12;
 export class ListScreen {
     o;
     category = 0;
     focus = 'list';
+    /** The list has the keyboard (false while the menu's navigation has it): the highlight is drawn softer. */
+    active = true;
     cursor = 0;
     offset = 0;
     query = '';
     searching = false;
     notice;
     checked;
+    /** The entries shown for the last query and category (the items never change, so only those two matter). */
+    shown;
+    /** What a search looks in, per entry, lowercased once. */
+    haystacks;
     constructor(o) {
         this.o = o;
         this.notice = o.notice;
+        this.query = o.startQuery ?? '';
         this.checked = new Set(o.items.flatMap((item, i) => (item.checked ? [i] : [])));
         const start = o.startAt === undefined ? -1 : o.items.findIndex((item) => item.value === o.startAt);
         const startCategory = start >= 0 ? o.items[start].category : o.startCategory;
@@ -23,21 +32,26 @@ export class ListScreen {
     }
     /** Indexes of the entries shown now: all matches of the search, else the current category's, else all. */
     visible() {
+        const key = this.query + '\0' + this.category;
+        if (this.shown?.key !== key)
+            this.shown = { key, indexes: this.matching() };
+        return this.shown.indexes;
+    }
+    matching() {
         const all = this.o.items.map((_, i) => i);
         if (this.query.trim()) {
             const words = this.query.toLowerCase().split(/\s+/).filter(Boolean);
-            const label = (id) => this.o.categories?.find((c) => c.id === id)?.label ?? '';
-            return all.filter((i) => {
-                const it = this.o.items[i];
-                const hay = [it.label, Text.strip(it.hint ?? ''), it.description, it.keywords, it.section, label(it.category)]
-                    .join(' ')
-                    .toLowerCase();
-                return words.every((w) => hay.includes(w));
-            });
+            const hays = (this.haystacks ??= this.o.items.map((it) => [it.label, Text.strip(it.hint ?? ''), it.description, it.keywords, it.section, this.categoryLabel(it.category)]
+                .join(' ')
+                .toLowerCase()));
+            return all.filter((i) => words.every((w) => hays[i].includes(w)));
         }
         const cat = this.o.categories?.[this.category];
         return cat ? all.filter((i) => this.o.items[i].category === cat.id) : all;
     }
+    categoryLabel(id) {
+        return this.o.categories?.find((c) => c.id === id)?.label ?? '';
+    }
     rows(visible) {
         const rows = [];
         let section;
@@ -45,7 +59,7 @@ export class ListScreen {
         for (const index of visible) {
             const it = this.o.items[index];
             const heading = searchAll
-                ? [this.o.categories?.find((c) => c.id === it.category)?.label, it.section].filter(Boolean).join(' › ')
+                ? [this.categoryLabel(it.category), it.section].filter(Boolean).join(' › ')
                 : it.section;
             if (heading && heading !== section)
                 rows.push({ kind: 'section', text: heading });
@@ -57,40 +71,69 @@ export class ListScreen {
     render(size) {
         const visible = this.visible();
         this.cursor = Math.min(this.cursor, Math.max(0, visible.length - 1));
-        const sideWidth = this.o.categories
+        const sideWidth = this.o.categories && !this.external
             ? Math.min(32, Math.max(...this.o.categories.map((c) => Text.width(c.label))) + 7)
             : 0;
         const rest = size.width - 1 - (sideWidth ? sideWidth + 3 : 0);
         const detailsRight = rest >= 100;
         const detailsWidth = detailsRight ? Math.min(52, Math.floor(rest * 0.38)) : rest;
         const listWidth = detailsRight ? rest - detailsWidth - 3 : rest;
+        const top = this.topLines(size.width, visible.length);
+        const details = this.detailsLines(visible[this.cursor], detailsWidth);
+        const bottomDetails = !detailsRight && size.height - top.length >= 14 ? details.slice(0, 6) : [];
+        const rows = this.rows(visible);
+        const room = size.height - top.length - (bottomDetails.length ? bottomDetails.length + 1 : 0);
+        // A list longer than the room keeps one row for "▲ / ▼ more".
+        const listHeight = rows.length > room ? room - 1 : room;
+        const listLines = this.listLines(visible, rows, listHeight, listWidth);
+        const sideLines = sideWidth ? this.sideLines(sideWidth) : [];
+        const body = [...top];
+        const height = Math.max(listLines.length, detailsRight ? details.length : 0, sideLines.length);
+        for (let i = 0; i < Math.min(height, size.height - top.length); i++) {
+            const side = sideWidth ? Text.fit(sideLines[i] ?? '', sideWidth) + ' ' + Theme.dim(Theme.glyph.vline) + ' ' : '';
+            const main = Text.fit(listLines[i] ?? '', listWidth);
+            const right = detailsRight ? ' ' + Theme.dim(Theme.glyph.vline) + ' ' + (details[i] ?? '') : '';
+            body.push(side + main + right);
+        }
+        if (bottomDetails.length) {
+            // The details sit at the bottom, whatever the length of the list.
+            while (body.length < size.height - bottomDetails.length - 1)
+                body.push(sideWidth
+                    ? Text.fit(sideLines[body.length - top.length] ?? '', sideWidth) + ' ' + Theme.dim(Theme.glyph.vline)
+                    : '');
+            body.push(Theme.dim(' ' + Theme.glyph.line.repeat(size.width - 3)), ...bottomDetails.map((l) => ' ' + l));
+        }
+        return { path: this.o.path, status: this.o.status, body, keys: this.keys(), notice: this.notice };
+    }
+    /** The rows above the list: the tabs, the intro, the search box (with a blank row after them). */
+    topLines(width, matches) {
         const top = [];
-        if (this.o.tabs)
-            top.push(' ' +
+        if (this.o.tabs) {
+            const row = ' ' +
                 this.o.tabs.items
                     .map((tab, i) => i === this.o.tabs.active
                     ? tab.paint(' ' + tab.badge + ' ' + tab.label + ' ')
                     : Theme.muted('  ' + tab.label + '  '))
                     .join(' ') +
-                Theme.muted('   tab switches'), '');
+                Theme.muted('   tab switches');
+            top.push(Text.truncate(row, width - 1), '');
+        }
         const intro = typeof this.o.intro === 'string' ? [this.o.intro] : (this.o.intro ?? []);
         for (const line of intro)
-            top.push(...Text.wrap(line, size.width - 3).map((l) => ' ' + Theme.muted(l)));
+            top.push(...Text.wrap(line, width - 3).map((l) => ' ' + Theme.muted(l)));
         if (this.searching || this.query)
             top.push(' ' +
                 Theme.accent(Theme.glyph.search) +
                 ' ' +
                 this.query +
                 (this.searching ? Theme.accent('▏') : '') +
-                Theme.muted('   ' + visible.length + ' match' + (visible.length === 1 ? '' : 'es')));
+                Theme.muted('   ' + matches + ' match' + (matches === 1 ? '' : 'es')));
         if (top.length)
             top.push('');
-        const details = this.detailsLines(visible[this.cursor], detailsWidth);
-        const bottomDetails = !detailsRight && size.height - top.length >= 14 ? details.slice(0, 6) : [];
-        const rows = this.rows(visible);
-        const room = size.height - top.length - (bottomDetails.length ? bottomDetails.length + 1 : 0);
-        // A list longer than the room keeps one row for "▲ / ▼ more".
-        const listHeight = rows.length > room ? room - 1 : room;
+        return top;
+    }
+    /** The rows of the list that fit: scrolled to keep the cursor in view, with "▲ above / ▼ more" under them. */
+    listLines(visible, rows, listHeight, listWidth) {
         const cursorRow = rows.findIndex((r) => r.kind === 'item' && r.index === visible[this.cursor]);
         if (cursorRow >= 0) {
             // Keep the heading above the first entry in view, and the cursor inside the window.
@@ -113,26 +156,10 @@ export class ListScreen {
             listLines.push(Theme.muted('   ' +
                 (above > 0 ? '▲ ' + above + ' above' : '') +
                 (above > 0 && below > 0 ? '   ' : '') +
-                (below > 0 ? '▼ ' + below + ' more' : '')));
-        }
-        const sideLines = this.sideLines(sideWidth);
-        const body = [...top];
-        const height = Math.max(listLines.length, detailsRight ? details.length : 0, sideLines.length);
-        for (let i = 0; i < Math.min(height, size.height - top.length); i++) {
-            const side = sideWidth ? Text.fit(sideLines[i] ?? '', sideWidth) + ' ' + Theme.dim(Theme.glyph.vline) + ' ' : '';
-            const main = Text.fit(listLines[i] ?? '', listWidth);
-            const right = detailsRight ? ' ' + Theme.dim(Theme.glyph.vline) + ' ' + (details[i] ?? '') : '';
-            body.push(side + main + right);
-        }
-        if (bottomDetails.length) {
-            // The details sit at the bottom, whatever the length of the list.
-            while (body.length < size.height - bottomDetails.length - 1)
-                body.push(sideWidth
-                    ? Text.fit(sideLines[body.length - top.length] ?? '', sideWidth) + ' ' + Theme.dim(Theme.glyph.vline)
-                    : '');
-            body.push(Theme.dim(' ' + Theme.glyph.line.repeat(size.width - 3)), ...bottomDetails.map((l) => ' ' + l));
+                (below > 0 ? '▼ ' + below + ' more' : '') +
+                (this.searching || this.query ? '' : '   / search')));
         }
-        return { path: this.o.path, status: this.o.status, body, keys: this.keys(), notice: this.notice };
+        return listLines;
     }
     rowLine(row, visible, width) {
         if (row.kind === 'section')
@@ -156,7 +183,9 @@ export class ListScreen {
             ' ';
         if (!selected)
             return ' ' + line;
-        return this.focus === 'list' ? ' ' + Theme.selected(Text.strip(line)) : ' ' + Theme.accent(Text.strip(line));
+        return this.focus === 'list' && this.active
+            ? ' ' + Theme.selected(Text.strip(line))
+            : ' ' + Theme.accent(Text.strip(line));
     }
     sideLines(width) {
         if (!this.o.categories)
@@ -199,12 +228,14 @@ export class ListScreen {
         if (this.searching)
             return [
                 ['type', 'to search', 1],
-                ['↵', this.o.multi ? 'done' : (this.o.enterLabel ?? 'open'), 1],
+                ['↵', this.o.multi ? 'done' : this.enterLabel(this.valueAt(this.visible()[this.cursor])), 1],
                 ['esc', 'clear search', 0],
                 ['↑↓', 'move', 4],
             ];
         const current = this.visible()[this.cursor];
+        const value = current === undefined ? undefined : this.o.items[current].value;
         const flips = current !== undefined && this.o.items[current].flip;
+        const long = this.o.items.length > LONG_LIST;
         return [
             ...(this.o.multi
                 ? [
@@ -212,16 +243,19 @@ export class ListScreen {
                     ...(this.o.enterTicks ? [] : [['↵', 'done', 1]]),
                     ['a', 'tick all shown', 6],
                 ]
-                : [['↵', this.o.enterLabel ?? 'open', 1], ...(flips ? [['space', 'flip', 1]] : [])]),
-            ...this.actionsNow().map((a) => [
+                : [
+                    ...(this.enterLabel(value) ? [['↵', this.enterLabel(value), 1]] : []),
+                    ...(flips ? [['space', 'flip', 1]] : []),
+                ]),
+            ...this.actionsNow(value).map((a) => [
                 a.ctrl ? 'ctrl+' + a.key : a.key,
                 a.label,
                 a.ctrl ? 0 : (a.importance ?? 2),
             ]),
             ...(this.o.tabs ? [['tab', 'scope', 3]] : []),
-            ...(this.o.categories ? [['←→', 'categories', 3]] : []),
+            ...(this.o.categories && !this.external ? [['←→', 'categories', 3]] : []),
             ['↑↓', 'move', 5],
-            ['/', 'search', 6],
+            ['/', 'search', long ? 3 : 6],
             ['esc', this.o.escapeLabel ?? 'back', 0],
         ];
     }
@@ -229,14 +263,53 @@ export class ListScreen {
     setNotice(text) {
         this.notice = text;
     }
+    /** The categories are shown by the menu's navigation, which drives them (no sidebar of its own). */
+    get external() {
+        return this.o.categoryNav === 'external';
+    }
+    enterLabel(value) {
+        const label = this.o.enterLabel;
+        return (typeof label === 'function' ? label(this.currentCategory, value) : label) ?? 'open';
+    }
+    valueAt(index) {
+        return index === undefined ? undefined : this.o.items[index].value;
+    }
+    /** The categories of the list (empty without any). */
+    get categories() {
+        return this.o.categories ?? [];
+    }
+    /** Opens a category (the menu's navigation does this); a search in progress ends. */
+    setCategory(id) {
+        const index = this.categories.findIndex((c) => c.id === id);
+        if (index < 0 || index === this.category)
+            return;
+        this.category = index;
+        this.query = '';
+        this.searching = false;
+        this.cursor = 0;
+        this.offset = 0;
+    }
+    /** Whether the list has the keyboard (the highlight is drawn softer when it has not). */
+    setActive(on) {
+        this.active = on;
+    }
     /** The id of the category open in the sidebar (undefined without a sidebar). */
     get currentCategory() {
         return this.o.categories?.[this.category]?.id;
     }
-    /** The extra keys that work now (they may depend on the category). */
-    actionsNow() {
+    /** The extra keys that work now (they may depend on the category and on the highlighted entry). */
+    actionsNow(value) {
         const actions = this.o.actions;
-        return typeof actions === 'function' ? actions(this.currentCategory) : (actions ?? []);
+        const all = typeof actions === 'function' ? actions(this.currentCategory) : (actions ?? []);
+        return all.filter((a) => !a.applies || (value !== undefined && a.applies(value)));
+    }
+    /** The value under the cursor (undefined: the list is empty). */
+    get current() {
+        return this.valueAt(this.visible()[this.cursor]);
+    }
+    /** The text of the search (empty: none). */
+    get searchText() {
+        return this.query;
     }
     /** Keys are going into the search box (digits and letters are text, not shortcuts). */
     get isSearching() {
@@ -250,15 +323,10 @@ export class ListScreen {
         const visible = this.visible();
         const current = visible[this.cursor];
         this.notice = undefined;
-        const ctrlAction = key.ctrl ? this.actionsNow().find((a) => a.ctrl && a.key === key.name) : undefined;
+        const value = this.valueAt(current);
+        const ctrlAction = key.ctrl ? this.actionsNow(value).find((a) => a.ctrl && a.key === key.name) : undefined;
         if (ctrlAction)
-            return {
-                done: {
-                    kind: 'action',
-                    key: 'ctrl+' + ctrlAction.key,
-                    value: current === undefined ? undefined : this.o.items[current].value,
-                },
-            };
+            return { done: { kind: 'action', key: 'ctrl+' + ctrlAction.key, value } };
         const move = (by) => {
             this.cursor = Math.max(0, Math.min(visible.length - 1, this.cursor + by));
         };
@@ -318,7 +386,9 @@ export class ListScreen {
             const n = this.o.tabs.items.length;
             return { done: { kind: 'tab', index: (this.o.tabs.active + (key.shift ? n - 1 : 1)) % n } };
         }
-        if (this.o.categories && !this.query) {
+        if (this.external && !this.query && !this.searching && key.name === 'left')
+            return { done: { kind: 'back' } };
+        if (this.o.categories && !this.external && !this.query) {
             if (key.name === 'left' && this.focus === 'list') {
                 this.focus = 'side';
                 return;
@@ -370,15 +440,9 @@ export class ListScreen {
             }
             return { done: { kind: 'pick', value: it.value } };
         }
-        const action = !this.searching && key.text ? this.actionsNow().find((a) => !a.ctrl && a.key === key.text) : undefined;
+        const action = !this.searching && key.text ? this.actionsNow(value).find((a) => !a.ctrl && a.key === key.text) : undefined;
         if (action)
-            return {
-                done: {
-                    kind: 'action',
-                    key: action.key,
-                    value: current === undefined ? undefined : this.o.items[current].value,
-                },
-            };
+            return { done: { kind: 'action', key: action.key, value } };
         return;
     }
     toggle(index) {

package/dist/cli/tui/list/list-types.d.ts

@@ -26,9 +26,11 @@ export interface Category {
     label: string;
     description?: string;
 }
-export interface ListAction {
+export interface ListAction<T = unknown> {
     key: string;
     label: string;
+    /** Only while an entry this accepts is highlighted: the key bar and the key itself ignore it otherwise. */
+    applies?: (value: T) => boolean;
     /** Pressed with Ctrl (ctrl+s ...); works while searching too. */
     ctrl?: boolean;
     /** How long it survives in a narrow footer: 0 never goes, bigger goes earlier (default 2). */
@@ -69,8 +71,10 @@ export interface ListOptions<T> {
     /** Start on this entry (and its category). */
     startAt?: T;
     startCategory?: string;
+    /** Start with this search typed (it shows every match in all categories; Esc clears it). */
+    startQuery?: string;
     /** Extra keys; a function picks them by the open category. */
-    actions?: ListAction[] | ((category: string | undefined) => ListAction[]);
+    actions?: ListAction<T>[] | ((category: string | undefined) => ListAction<T>[]);
     notice?: string;
     empty?: string;
     tabs?: {
@@ -79,6 +83,8 @@ export interface ListOptions<T> {
     };
     /** What Esc does, for the footer ("back", "quit"). */
     escapeLabel?: string;
-    /** What Enter does, for the footer ("open", "edit", "start"). */
-    enterLabel?: string;
+    /** What Enter does, for the footer ("open", "edit", "start"); a function picks it by entry ("": none). */
+    enterLabel?: string | ((category: string | undefined, value: T | undefined) => string);
+    /** Where the categories are listed: in a sidebar of the list itself (default) or in the menu's own navigation. */
+    categoryNav?: 'own' | 'external';
 }

package/dist/cli/tui/nav.d.ts

@@ -0,0 +1,29 @@
+export interface NavCategory {
+    readonly label: string;
+    /** The category open in the list. */
+    readonly current: boolean;
+}
+export interface NavSection {
+    readonly label: string;
+    /** Something is waiting in this section (unsaved changes). */
+    readonly marked?: boolean;
+    /** The categories of the open section (other sections are drawn without theirs). */
+    readonly categories: readonly NavCategory[];
+}
+export interface NavState {
+    readonly sections: readonly NavSection[];
+    /** Index of the open section. */
+    readonly active: number;
+    /** The navigation has the keyboard (else the list has it). */
+    readonly focused: boolean;
+    /** A dialog or sub-screen is shown over the menu: everything is drawn grey. */
+    readonly dimmed?: boolean;
+}
+export declare class SideNav {
+    /** Columns the navigation takes on a terminal `termWidth` columns wide (without the divider). */
+    static width(termWidth: number): number;
+    /** Exactly `height` lines, each `SideNav.width(termWidth)` columns wide. */
+    static render(nav: NavState, termWidth: number, height: number): string[];
+    private static section;
+    private static category;
+}

package/dist/cli/tui/nav.js

@@ -0,0 +1,67 @@
+// The navigation on the left of every menu screen: the sections as a tree (the open one shows its categories), with
+// the way you are standing marked. Narrow terminals get a slim column of numbers instead of names. Pure (tested).
+import { Text } from './text.js';
+import { Theme } from './theme.js';
+/** Terminals narrower than this get the slim column. */
+const SLIM_BELOW = 80;
+const SLIM_WIDTH = 5;
+export class SideNav {
+    /** Columns the navigation takes on a terminal `termWidth` columns wide (without the divider). */
+    static width(termWidth) {
+        if (termWidth < SLIM_BELOW)
+            return SLIM_WIDTH;
+        return termWidth >= 130 ? 28 : 24;
+    }
+    /** Exactly `height` lines, each `SideNav.width(termWidth)` columns wide. */
+    static render(nav, termWidth, height) {
+        const width = SideNav.width(termWidth);
+        const slim = width === SLIM_WIDTH;
+        const lines = [];
+        nav.sections.forEach((section, i) => {
+            const open = i === nav.active;
+            const hasCategories = open && section.categories.length > 0;
+            const standing = open && !hasCategories;
+            lines.push({ text: SideNav.section(nav, section, i, width, slim, standing), stop: standing });
+            if (!hasCategories)
+                return;
+            section.categories.forEach((cat, c) => {
+                const last = c === section.categories.length - 1;
+                lines.push({ text: SideNav.category(nav, cat, last, width, slim), stop: cat.current });
+            });
+        });
+        const at = Math.max(0, lines.findIndex((l) => l.stop));
+        const start = lines.length > height ? Math.min(Math.max(0, at - Math.floor(height / 2)), lines.length - height) : 0;
+        const shown = lines.slice(start, start + height).map((l) => l.text);
+        while (shown.length < height)
+            shown.push(' '.repeat(width));
+        return shown;
+    }
+    static section(nav, section, index, width, slim, standing) {
+        const open = index === nav.active;
+        const live = !nav.dimmed;
+        // The open section has a marker, so it shows without colour.
+        const lead = open ? (section.categories.length ? '▾' : Theme.glyph.pointer) : ' ';
+        const mark = section.marked ? Theme.changed(Theme.glyph.changed) : ' ';
+        const inner = slim
+            ? lead + (index + 1) + mark + '  '
+            : Text.fit(lead + (index + 1) + ' ' + (open && live ? Theme.bold(section.label) : section.label), width - 3) +
+                ' ' +
+                mark +
+                ' ';
+        if (standing && live && nav.focused)
+            return Theme.selected(Text.fit(inner, width));
+        if (!live || !open)
+            return Theme.muted(Text.fit(inner, width));
+        return nav.focused ? Text.fit(inner, width) : Theme.accent(Text.fit(inner, width));
+    }
+    static category(nav, cat, last, width, slim) {
+        const live = !nav.dimmed;
+        const plain = slim
+            ? '  ' + (cat.current ? Theme.glyph.on : Theme.glyph.dot) + '  '
+            : '  ' + (cat.current ? Theme.glyph.pointer : last ? '└' : '├') + ' ' + cat.label;
+        const line = Text.fit(plain, width);
+        if (!cat.current || !live)
+            return Theme.muted(line);
+        return nav.focused ? Theme.selected(line) : Theme.accentBold(line);
+    }
+}

package/dist/cli/tui/terminal.d.ts

@@ -10,6 +10,8 @@ export interface Key {
 export declare class ExitRequested extends Error {
     constructor();
 }
+/** Whether this terminal is known to take synchronized updates (AGENT_SANDBOX_SYNC_UPDATE=1 or 0 overrides). */
+export declare function supportsSyncUpdate(env?: NodeJS.ProcessEnv): boolean;
 export declare class Terminal {
     private readonly stdin;
     private readonly stdout;
@@ -18,17 +20,22 @@ export declare class Terminal {
     private queue;
     private waiting;
     private resizeHandler;
+    private readonly sync;
     private readonly onKeypress;
     private readonly onResize;
     constructor(stdin?: NodeJS.ReadStream, stdout?: NodeJS.WriteStream);
     get width(): number;
     get height(): number;
+    /** Keys can be read from a real terminal here (the menu refuses to open without one). */
+    get interactive(): boolean;
     /** Called after the window was resized (the screen draws itself again). */
     onResized(handler: (() => void) | null): void;
     start(): void;
     /** Gives the terminal back exactly as it was (also on errors: callers use try/finally). */
     stop(): void;
     get running(): boolean;
+    /** Key presses are waiting to be read (the screen may skip a draw and show the result of the last one). */
+    get hasKeys(): boolean;
     /** Draws a whole screen: `lines` are cut to the width and padded to the height; unchanged rows are not rewritten. */
     render(lines: string[]): void;
     /** The next key press. Ctrl+C rejects with ExitRequested. */

package/dist/cli/tui/terminal.js

@@ -1,6 +1,7 @@
 // The terminal while the menu owns it: the alternate screen (your scrollback stays as it was), raw keys, a cursor that
-// is hidden, and redraws that only rewrite the rows that changed (no flicker). suspend() hands the terminal back for
-// a command's own output; resume() takes it again.
+// is hidden, and redraws that only rewrite the rows that changed, in one write (inside a synchronized update where the
+// terminal has one), so nothing flickers. stop() hands the terminal back for a command's own output; start() takes it
+// again.
 import readline from 'node:readline';
 import { Text } from './text.js';
 /** Ctrl+C: leave the menu at once (callers let it propagate to the top). */
@@ -10,6 +11,17 @@ export class ExitRequested extends Error {
         this.name = 'ExitPromptError';
     }
 }
+/** DEC 2026: the terminal shows a frame only when it is complete. Others ignore it, so only these are asked. */
+const SYNC_BEGIN = '\x1b[?2026h';
+const SYNC_END = '\x1b[?2026l';
+/** Whether this terminal is known to take synchronized updates (AGENT_SANDBOX_SYNC_UPDATE=1 or 0 overrides). */
+export function supportsSyncUpdate(env = process.env) {
+    const forced = env.AGENT_SANDBOX_SYNC_UPDATE;
+    if (forced === '1' || forced === '0')
+        return forced === '1';
+    const program = env.TERM_PROGRAM ?? '';
+    return Boolean(env.WT_SESSION) || ['vscode', 'WezTerm', 'iTerm.app', 'ghostty', 'contour'].includes(program);
+}
 export class Terminal {
     stdin;
     stdout;
@@ -18,6 +30,7 @@ export class Terminal {
     queue = [];
     waiting = null;
     resizeHandler = null;
+    sync = supportsSyncUpdate();
     onKeypress = (str, key) => this.push(str, key);
     onResize = () => {
         this.frame = [];
@@ -33,6 +46,10 @@ export class Terminal {
     get height() {
         return Math.max(12, this.stdout.rows ?? 30);
     }
+    /** Keys can be read from a real terminal here (the menu refuses to open without one). */
+    get interactive() {
+        return Boolean(this.stdin.isTTY);
+    }
     /** Called after the window was resized (the screen draws itself again). */
     onResized(handler) {
         this.resizeHandler = handler;
@@ -66,21 +83,24 @@ export class Terminal {
     get running() {
         return this.active;
     }
+    /** Key presses are waiting to be read (the screen may skip a draw and show the result of the last one). */
+    get hasKeys() {
+        return this.queue.length > 0;
+    }
     /** Draws a whole screen: `lines` are cut to the width and padded to the height; unchanged rows are not rewritten. */
     render(lines) {
         const { width, height } = this;
         // One column is left free: writing the last column can scroll older consoles.
         const rows = Array.from({ length: height }, (_, i) => Text.fit(lines[i] ?? '', width - 1));
-        let out = '';
-        rows.forEach((row, i) => {
-            if (this.frame[i] !== row)
-                out += '\x1b[' + (i + 1) + ';1H' + row + '\x1b[0m';
-        });
-        if (this.frame.length !== rows.length)
-            out = '\x1b[H\x1b[2J' + rows.map((r, i) => '\x1b[' + (i + 1) + ';1H' + r + '\x1b[0m').join('');
+        // A different height (or nothing drawn yet: after a resize or a start) repaints everything.
+        const repaint = this.frame.length !== rows.length;
+        const out = (repaint ? '\x1b[H\x1b[2J' : '') +
+            rows
+                .map((row, i) => (repaint || this.frame[i] !== row ? '\x1b[' + (i + 1) + ';1H' + row + '\x1b[0m' : ''))
+                .join('');
         this.frame = rows;
         if (out)
-            this.stdout.write(out);
+            this.stdout.write(this.sync ? SYNC_BEGIN + out + SYNC_END : out);
     }
     /** The next key press. Ctrl+C rejects with ExitRequested. */
     key() {

package/dist/cli/validate.d.ts

@@ -12,6 +12,6 @@ export declare function validPythonSpec(spec: string): boolean;
 export declare function checkHarness(name: string | undefined, harnesses: string[]): void;
 export declare const PROJECT_ACTIONS: readonly ["list", "choose", "add", "remove", "include", "exclude", "all", "roots"];
 /** `sandbox projects <action> [value] [folder]`: the action, then what it needs. Pure (no file checks). */
-export declare function validateProjectsArgs(args: string[]): void;
+export declare function validateProjectsArgs(args: string[], canAsk?: boolean): void;
 /** Fails with what is wrong and what is valid, before anything is started. */
 export declare function validateOptions(ctx: Context): void;

package/dist/cli/validate.js

@@ -44,11 +44,11 @@ export function checkHarness(name, harnesses) {
 const LAUNCHING = new Set(['launch', 'generate', 'host-claude']);
 export const PROJECT_ACTIONS = ['list', 'choose', 'add', 'remove', 'include', 'exclude', 'all', 'roots'];
 /** `sandbox projects <action> [value] [folder]`: the action, then what it needs. Pure (no file checks). */
-export function validateProjectsArgs(args) {
+export function validateProjectsArgs(args, canAsk = false) {
     const [action = 'list', value, folder] = args;
     if (!PROJECT_ACTIONS.includes(action))
         unknownValue('projects action', action, PROJECT_ACTIONS, 'sandbox projects with no action lists your projects.');
-    if (['add', 'remove', 'include', 'exclude'].includes(action) && !value)
+    if (['add', 'remove', 'include', 'exclude'].includes(action) && !value && !canAsk)
         fail('Which folder?', 'Usage: sandbox projects ' + action + ' <folder>   (. = this folder)');
     if (action === 'all' && value !== undefined && !['on', 'off'].includes(value))
         unknownValue('value for projects all', value, ['on', 'off'], 'sandbox projects all on|off');
@@ -64,7 +64,7 @@ export function validateOptions(ctx) {
     if (['launch', 'generate', 'restart', 'doctor'].includes(o.command))
         checkHarness(o.harness, harnesses);
     if (o.command === 'projects')
-        validateProjectsArgs(o.positionals);
+        validateProjectsArgs(o.positionals, Boolean(process.stdin.isTTY));
     if (!LAUNCHING.has(o.command))
         return;
     if (o.node !== undefined && !validNodeSpec(o.node))

package/dist/cli/version.d.ts

@@ -0,0 +1,2 @@
+/** The text for a version-only command line (`--version`, `-v`, with or without `--short`), or null for any other. */
+export declare function versionText(argv: readonly string[], packageRoot: string): string | null;

package/dist/cli/version.js

@@ -0,0 +1,11 @@
+// `sandbox --version`: the version and where it runs from; `--version --short` is the plain number (the updater and the
+// installer compare it to the version they just installed).
+import { packageVersion } from '../core/package-info.js';
+import { describeCopy } from '../host/install/index.js';
+/** The text for a version-only command line (`--version`, `-v`, with or without `--short`), or null for any other. */
+export function versionText(argv, packageRoot) {
+    const flags = argv.filter((a) => a !== '--short');
+    if (flags.length === 0 || flags.some((a) => a !== '--version' && a !== '-v'))
+        return null;
+    return argv.includes('--short') ? packageVersion() : packageVersion() + ' (' + describeCopy(packageRoot) + ')';
+}