janissary 0.5.0

package/dist/schedule-helpers.js

@@ -0,0 +1,76 @@
+const MONTHS = [
+    'january', 'february', 'march', 'april', 'may', 'june',
+    'july', 'august', 'september', 'october', 'november', 'december',
+];
+const WEEKDAYS = ['sunday', 'monday', 'tuesday', 'wednesday', 'thursday', 'friday', 'saturday'];
+const SCHEDULE_USAGE = 'Usage: schedule NAME <at TIME | on DATE [at TIME] | every N(m|h|d|w) | every DAY at TIME> COMMAND | schedule list | schedule cancel <name> | schedule clear';
+export function parseAtSchedule(tokens, now, parseTimeOfDay, fmtTime, nextOccurrenceOfTime) {
+    const tod = parseTimeOfDay(tokens[1] ?? '');
+    if (!tod)
+        return { error: `Invalid time: "${tokens[1] ?? ''}".` };
+    const command = tokens.slice(2).join(' ').trim();
+    if (!command)
+        return { error: 'No command to schedule.' };
+    return { action: 'add', entry: {
+            command, spec: `at ${fmtTime(tod)}`, recurring: false,
+            nextRun: nextOccurrenceOfTime(tod.hour, tod.minute, now),
+        } };
+}
+export function parseOnSchedule(tokens, now, parseMonthDay, parseTimeOfDay, fmtTime, nextDateTime) {
+    const md = parseMonthDay(tokens.slice(1));
+    if (!md)
+        return { error: 'Invalid date. Try "on august 12th" or "on 8/12".' };
+    let index = 1 + md.consumed;
+    let tod = { hour: 9, minute: 0 };
+    if (tokens[index]?.toLowerCase() === 'at') {
+        const t = parseTimeOfDay(tokens[index + 1] ?? '');
+        if (!t)
+            return { error: `Invalid time: "${tokens[index + 1] ?? ''}".` };
+        tod = t;
+        index += 2;
+    }
+    const command = tokens.slice(index).join(' ').trim();
+    if (!command)
+        return { error: 'No command to schedule.' };
+    return { action: 'add', entry: {
+            command, spec: `on ${MONTHS[md.month].slice(0, 3)} ${md.day} at ${fmtTime(tod)}`, recurring: false,
+            nextRun: nextDateTime(md.month, md.day, tod.hour, tod.minute, now),
+        } };
+}
+export function parseEverySchedule(tokens, now, parseInterval, parseTimeOfDay, fmtTime, nextOccurrenceOfTime, nextWeekday) {
+    const second = tokens[1] ?? '';
+    const interval = parseInterval(second);
+    if (interval !== undefined) {
+        const command = tokens.slice(2).join(' ').trim();
+        if (!command)
+            return { error: 'No command to schedule.' };
+        return { action: 'add', entry: {
+                command, spec: `every ${second.toLowerCase()}`, recurring: true,
+                intervalMs: interval, nextRun: now.getTime() + interval,
+            } };
+    }
+    const dayWord = second.toLowerCase();
+    let weekday;
+    if (dayWord !== 'day') {
+        const wd = dayWord.length >= 3 ? WEEKDAYS.findIndex((w) => w.startsWith(dayWord)) : -1;
+        if (wd < 0)
+            return { error: `Invalid interval or day: "${second}".` };
+        weekday = wd;
+    }
+    if (tokens[2]?.toLowerCase() !== 'at')
+        return { error: SCHEDULE_USAGE };
+    const tod = parseTimeOfDay(tokens[3] ?? '');
+    if (!tod)
+        return { error: `Invalid time: "${tokens[3] ?? ''}".` };
+    const command = tokens.slice(4).join(' ').trim();
+    if (!command)
+        return { error: 'No command to schedule.' };
+    const label = weekday === undefined ? 'day' : WEEKDAYS[weekday];
+    return { action: 'add', entry: {
+            command, spec: `every ${label} at ${fmtTime(tod)}`, recurring: true,
+            timeOfDay: tod, weekday,
+            nextRun: weekday === undefined
+                ? nextOccurrenceOfTime(tod.hour, tod.minute, now)
+                : nextWeekday(weekday, tod.hour, tod.minute, now),
+        } };
+}

package/dist/schedule-manager.js

@@ -0,0 +1,98 @@
+import { computeNextRun, fmtNextRun } from './schedule.js';
+import { messageBus } from './bus.js';
+// Owns the per-tab scheduled commands (keyed by tab label) and the 1-second firing loop: at each tick
+// it fires any entry whose next-run time has passed, reschedules recurring ones, and drops one-shots.
+// The controller owns the tabs and persistence; this module owns the schedule state and timing.
+export class ScheduleManager {
+    managers;
+    schedules = new Map();
+    timer;
+    constructor(managers) {
+        this.managers = managers;
+    }
+    // Begin the firing loop. `unref` so a pending tick never keeps the process alive on its own.
+    start() {
+        this.timer = setInterval(() => this.tick(), 1000);
+        this.timer.unref?.();
+    }
+    // Stop the firing loop (app shutdown).
+    stop() {
+        clearInterval(this.timer);
+    }
+    // A tab's scheduled commands, or undefined when it has none (raw — for persistence and the command
+    // context, both of which distinguish "no schedule" from "empty schedule").
+    get(label) {
+        return this.schedules.get(label);
+    }
+    // Replace a tab's scheduled commands. Persisting is the caller's concern (rehydrate/profile load
+    // restore without re-persisting; the `schedule` command persists separately).
+    set(label, entries) {
+        this.schedules.set(label, entries);
+    }
+    // Forget a tab's schedule (on tab close).
+    delete(label) {
+        this.schedules.delete(label);
+    }
+    // The schedule rows for a tab's view: id, spec, humanized next-run time, and the recurring flag.
+    view(label) {
+        return (this.schedules.get(label) ?? []).map((e) => ({
+            id: e.id, spec: e.spec, next: fmtNextRun(e.nextRun), recurring: e.recurring,
+        }));
+    }
+    // Fire any commands whose next-run time has passed, in every still-open tab. A recurring entry is
+    // rescheduled to its next run; a one-shot drops off. Tabs whose schedule changed are persisted
+    // (harness tabs excepted — they have no persisted agent state).
+    tick() {
+        const now = Date.now();
+        let changed = false;
+        for (const label of this.managers.tab.allLabels()) {
+            const tab = this.managers.tab.tabs.find((t) => t.label === label);
+            const sched = this.schedules.get(label);
+            if (!tab || !sched || sched.length === 0)
+                continue;
+            const remaining = this.fireDue(tab, sched, now);
+            if (!remaining)
+                continue;
+            this.schedules.set(label, remaining);
+            changed = true;
+            if (tab.view !== 'harness')
+                this.managers.tab.persist(this.managers.tab.buildAgentState(tab, { schedule: this.get(label) }));
+        }
+        if (changed)
+            messageBus.emit('state', { type: 'dirty' });
+    }
+    // Fire one tab's due entries, returning the surviving schedule (recurring entries rescheduled,
+    // one-shots dropped), or undefined when nothing fired.
+    fireDue(tab, sched, now) {
+        let isChanged = false;
+        const remaining = [];
+        for (const e of sched) {
+            if (e.nextRun > now || !this.fire(tab, e)) {
+                remaining.push(e);
+                continue;
+            }
+            isChanged = true;
+            if (e.recurring)
+                remaining.push({ ...e, nextRun: computeNextRun(e, new Date()) });
+        }
+        return isChanged ? remaining : undefined;
+    }
+    // Deliver a due entry to its tab: typed into a harness PTY as a line of input, or dispatched
+    // through an agent tab's command pipeline. Returns false when delivery must wait (the harness
+    // is not running), leaving the entry due so it retries on a later tick.
+    fire(tab, e) {
+        if (tab.view === 'harness') {
+            if (tab.harness?.status !== 'running' || !tab.harness.ptyId)
+                return false;
+            // Sent as one write, a long command's trailing \r can land inside the same burst the harness's
+            // own input parser treats as a paste, so it's read as inserted text rather than submit. Splitting
+            // the \r into its own write after the text has been processed mimics organic typing and avoids that.
+            const ptyId = tab.harness.ptyId;
+            this.managers.pty.input(ptyId, e.command);
+            setTimeout(() => this.managers.pty.input(ptyId, '\r'), 50);
+            return true;
+        }
+        this.managers.command.dispatchTo(tab.label, `${e.command} ## scheduled ##`);
+        return true;
+    }
+}

package/dist/schedule-parsing.js

@@ -0,0 +1,63 @@
+const MONTHS = [
+    'january', 'february', 'march', 'april', 'may', 'june',
+    'july', 'august', 'september', 'october', 'november', 'december',
+];
+const UNIT_MS = { m: 60_000, h: 3_600_000, d: 86_400_000, w: 604_800_000 };
+export { MONTHS };
+export function parseTimeOfDay(tok) {
+    // Anchored at both ends; bounded quantifiers only — not a ReDoS risk.
+    // eslint-disable-next-line security/detect-unsafe-regex
+    const m = /^(\d{1,2})(?::(\d{2}))?\s*(am|pm)?$/i.exec(tok.trim());
+    if (!m)
+        return undefined;
+    let hour = Number(m[1]);
+    const minute = m[2] ? Number(m[2]) : 0;
+    const ap = m[3]?.toLowerCase();
+    if (ap) {
+        if (hour < 1 || hour > 12)
+            return undefined;
+        if (ap === 'pm' && hour !== 12)
+            hour += 12;
+        if (ap === 'am' && hour === 12)
+            hour = 0;
+    }
+    else if (hour > 23) {
+        return undefined;
+    }
+    if (minute > 59)
+        return undefined;
+    return { hour, minute };
+}
+export function parseInterval(tok) {
+    const m = /^(\d+)(m|h|d|w)$/i.exec(tok.trim());
+    if (!m)
+        return undefined;
+    const n = Number(m[1]);
+    if (n <= 0)
+        return undefined;
+    return n * UNIT_MS[m[2].toLowerCase()];
+}
+export function parseMonthDay(tokens) {
+    const first = tokens[0];
+    if (!first)
+        return undefined;
+    const slash = /^(\d{1,2})\/(\d{1,2})$/.exec(first);
+    if (slash) {
+        const month = Number(slash[1]) - 1;
+        const day = Number(slash[2]);
+        if (month < 0 || month > 11 || day < 1 || day > 31)
+            return undefined;
+        return { month, day, consumed: 1 };
+    }
+    const lc = first.toLowerCase();
+    const month = lc.length >= 3 ? MONTHS.findIndex((m) => m.startsWith(lc)) : -1;
+    if (month < 0)
+        return undefined;
+    const dm = /^(\d{1,2})(?:st|nd|rd|th)?$/i.exec(tokens[1] ?? '');
+    if (!dm)
+        return undefined;
+    const day = Number(dm[1]);
+    if (day < 1 || day > 31)
+        return undefined;
+    return { month, day, consumed: 2 };
+}

package/dist/schedule-time.js

@@ -0,0 +1,34 @@
+export function nextOccurrenceOfTime(hour, minute, now) {
+    const d = new Date(now);
+    d.setHours(hour, minute, 0, 0);
+    if (d.getTime() <= now.getTime())
+        d.setDate(d.getDate() + 1);
+    return d.getTime();
+}
+export function nextWeekday(weekday, hour, minute, now) {
+    const d = new Date(now);
+    d.setHours(hour, minute, 0, 0);
+    let diff = (weekday - d.getDay() + 7) % 7;
+    if (diff === 0 && d.getTime() <= now.getTime())
+        diff = 7;
+    d.setDate(d.getDate() + diff);
+    return d.getTime();
+}
+export function nextDateTime(month, day, hour, minute, now) {
+    const year = now.getFullYear();
+    const d = new Date(year, month, day, hour, minute, 0, 0);
+    if (d.getTime() <= now.getTime())
+        d.setFullYear(year + 1);
+    return d.getTime();
+}
+export function computeNextRun(entry, now) {
+    if (entry.intervalMs)
+        return now.getTime() + entry.intervalMs;
+    if (entry.timeOfDay) {
+        const { hour, minute } = entry.timeOfDay;
+        return entry.weekday === undefined
+            ? nextOccurrenceOfTime(hour, minute, now)
+            : nextWeekday(entry.weekday, hour, minute, now);
+    }
+    return now.getTime();
+}

package/dist/schedule.js

@@ -0,0 +1,76 @@
+// Parsing and next-run math for the `schedule` command. Pure (no I/O) so it is fully
+// unit-testable; callers (the command + the scheduler tick) own the side effects.
+import { parseAtSchedule, parseOnSchedule, parseEverySchedule } from './schedule-helpers.js';
+import { parseTimeOfDay, parseInterval, parseMonthDay } from './schedule-parsing.js';
+export { parseTimeOfDay, parseInterval, parseMonthDay } from './schedule-parsing.js';
+import { nextOccurrenceOfTime, nextWeekday, nextDateTime } from './schedule-time.js';
+export { nextOccurrenceOfTime, nextWeekday, computeNextRun } from './schedule-time.js';
+import { fmtTime } from './schedule-display.js';
+export { fmtNextRun, formatSchedule } from './schedule-display.js';
+export const SCHEDULE_USAGE = 'Usage: schedule NAME [in TAB] <at TIME | on DATE [at TIME] | every N(m|h|d|w) | every DAY at TIME> COMMAND'
+    + ' | schedule list [in TAB] | schedule cancel <name> [in TAB] | schedule clear [in TAB]';
+// Parse a trailing `in <tab>` clause starting at `tokens[index]`. Returns the target label,
+// an empty object when the clause is absent, or an error when it is malformed or followed
+// by extra tokens (the clause must end the command).
+function parseInClause(tokens, index) {
+    const [keyword, target, ...extra] = tokens.slice(index);
+    if (keyword === undefined)
+        return {};
+    if (keyword.toLowerCase() !== 'in' || target === undefined || extra.length > 0)
+        return { error: SCHEDULE_USAGE };
+    return { target };
+}
+export function parseScheduleCommand(rest, now) {
+    const trimmed = rest.trim();
+    if (!trimmed)
+        return { error: SCHEDULE_USAGE };
+    const tokens = trimmed.split(/\s+/);
+    const head = tokens[0].toLowerCase();
+    if (head === 'list' || head === 'clear') {
+        const clause = parseInClause(tokens, 1);
+        if ('error' in clause)
+            return clause;
+        return { action: head, ...clause };
+    }
+    if (head === 'cancel') {
+        if (!tokens[1])
+            return { error: 'Usage: schedule cancel <name> [in TAB]' };
+        const clause = parseInClause(tokens, 2);
+        if ('error' in clause)
+            return clause;
+        return { action: 'cancel', id: tokens[1], ...clause };
+    }
+    // Otherwise the first token names the timer (becoming its id, shown in the schedule window
+    // and used by `schedule cancel <name>`), an optional `in <tab>` picks the tab the timer
+    // belongs to, and the remainder is the schedule form.
+    const name = tokens[0];
+    let bodyTokens = tokens.slice(1);
+    let target;
+    if (bodyTokens[0]?.toLowerCase() === 'in') {
+        if (!bodyTokens[1])
+            return { error: SCHEDULE_USAGE };
+        target = bodyTokens[1];
+        bodyTokens = bodyTokens.slice(2);
+    }
+    const body = parseScheduleBody(bodyTokens.join(' '), now);
+    if ('error' in body)
+        return body;
+    return { ...body, name, ...(target !== undefined && { target }) };
+}
+function parseScheduleBody(rest, now) {
+    const trimmed = rest.trim();
+    if (!trimmed)
+        return { error: SCHEDULE_USAGE };
+    const tokens = trimmed.split(/\s+/);
+    const head = tokens[0].toLowerCase();
+    if (head === 'at') {
+        return parseAtSchedule(tokens, now, parseTimeOfDay, fmtTime, nextOccurrenceOfTime);
+    }
+    if (head === 'on') {
+        return parseOnSchedule(tokens, now, parseMonthDay, parseTimeOfDay, fmtTime, nextDateTime);
+    }
+    if (head === 'every') {
+        return parseEverySchedule(tokens, now, parseInterval, parseTimeOfDay, fmtTime, nextOccurrenceOfTime, nextWeekday);
+    }
+    return { error: SCHEDULE_USAGE };
+}

package/dist/search-matches.js

@@ -0,0 +1,40 @@
+// Line types with no meaningful text to search: a terminal card renders a live PTY (no static
+// text) and a spacer is blank.
+const UNSEARCHABLE = new Set(['terminal', 'spacer']);
+// Compile a search pattern as a case-insensitive regex, or null for an empty or invalid pattern.
+// Pure — no Node imports — so both the server command and the web client (via the `@shared`
+// alias) can use it.
+export function compilePattern(pattern) {
+    if (!pattern)
+        return null;
+    try {
+        return new RegExp(pattern, 'i');
+    }
+    catch {
+        return null;
+    }
+}
+// Indices (into `lines`) of every searchable line whose text matches `pattern`, oldest first.
+// Returns [] for an empty or invalid pattern.
+export function findMatches(lines, pattern) {
+    const regex = compilePattern(pattern);
+    if (!regex)
+        return [];
+    const indices = [];
+    for (const [index, line] of lines.entries()) {
+        if (UNSEARCHABLE.has(line.type))
+            continue;
+        if (regex.test(line.text))
+            indices.push(index);
+    }
+    return indices;
+}
+// The first match's [start, end) character range in `text`, for substring highlighting. Null
+// when the pattern doesn't match (or is empty/invalid).
+export function matchRange(text, pattern) {
+    const regex = compilePattern(pattern);
+    const match = regex?.exec(text);
+    if (!match)
+        return null;
+    return { start: match.index, end: match.index + match[0].length };
+}

package/dist/security.js

@@ -0,0 +1,44 @@
+import { randomBytes, timingSafeEqual } from 'node:crypto';
+/** Mint a per-session token handed to the browser via the launch URL. */
+export function makeToken() {
+    return randomBytes(24).toString('base64url');
+}
+// A request is only accepted when its Host (and Origin, when present) are loopback. This is the
+// DNS-rebinding / stray-tab guard: even bound to 127.0.0.1, a remote page could otherwise try to
+// reach the shell server with a spoofed Host header.
+// Anchored at both ends; no nested quantifiers — not a ReDoS risk.
+// eslint-disable-next-line security/detect-unsafe-regex
+const LOOPBACK = /^(127\.0\.0\.1|\[::1\]|::1|localhost)(:\d+)?$/i;
+export function originAllowed(request) {
+    const host = request.headers.host ?? '';
+    if (!LOOPBACK.test(host))
+        return false;
+    const origin = request.headers.origin;
+    if (origin) {
+        try {
+            if (!LOOPBACK.test(new URL(origin).host))
+                return false;
+        }
+        catch {
+            return false;
+        }
+    }
+    return true;
+}
+/** Extract the `token` query param from a request URL. */
+export function tokenFromReq(request) {
+    try {
+        return new URL(request.url ?? '', 'http://localhost').searchParams.get('token');
+    }
+    catch {
+        return null;
+    }
+}
+/** Constant-time token comparison. */
+export function tokenMatches(expected, got) {
+    if (!got)
+        return false;
+    const a = Buffer.from(expected);
+    const b = Buffer.from(got);
+    return a.length === b.length && timingSafeEqual(a, b);
+}

package/dist/shell-manager.js

@@ -0,0 +1,139 @@
+import { spawnShell, executeShellCmd as executeShellCommand, queryShellPwd } from './shell.js';
+import { getConfig } from './config.js';
+import { getGithubToken } from './github-token.js';
+import { messageBus } from './bus.js';
+// The base name of the user's login shell (`bash`, `zsh`, …), used both to launch tab shells and to
+// label the `shell:<name>` connection in the panel/completion.
+export const SHELL_NAME = (process.env.SHELL || 'bash').split('/').pop() || 'bash';
+// Owns the per-tab persistent shells. Each tab (keyed by its label) gets one long-lived shell process
+// that preserves working directory and environment across commands; the manager spawns them lazily,
+// runs commands with streaming output, and tears them down.
+export class ShellManager {
+    managers;
+    shells = new Map();
+    // Serializes each tab's shell interactions (a command's execution, then its trailing pwd query)
+    // so at most one stdin write / stdout listener pair is ever live on a given shell at a time.
+    // Without this, a rapid-fire queued command (dispatched the instant the previous one goes idle)
+    // could attach its own listener while the previous command's still-in-flight pwd query is
+    // waiting on the same stdout stream — Node delivers that chunk to both listeners, leaking the
+    // pwd query's cwd line and its `__PWD_...__` marker into the next command's output.
+    shellQueues = new Map();
+    constructor(managers) {
+        this.managers = managers;
+    }
+    // Whether a tab currently has a live shell. Drives the connections panel and completion.
+    has(label) {
+        return this.shells.has(label);
+    }
+    // The tab's persistent shell, spawned on first use and respawned if the previous one died (its
+    // stdin no longer writable). A freshly spawned shell is `cd`'d into `cwd` so it starts in the tab's
+    // working directory — the workspace clone for a workspaced agent, or the saved cwd for a
+    // `--relaunch`'d tab. A nullish `cwd` leaves the shell in its default directory.
+    getShell(label, cwd) {
+        let shell = this.shells.get(label);
+        if (!shell || !shell.stdin?.writable) {
+            const tab = this.managers.tab.tabs.find((t) => t.label === label);
+            shell = spawnShell(0, { JANUS_AGENT_NAME: label }, {
+                workspaceDir: tab?.workspaceDir,
+                offline: tab?.offline,
+                githubToken: tab?.workspaceDir ? getGithubToken() : undefined,
+            });
+            this.shells.set(label, shell);
+            this.shellQueues.delete(label);
+            if (cwd)
+                shell.stdin.write(`cd "${cwd}"\n`);
+        }
+        return shell;
+    }
+    // Run a command with transcript streaming, busy state, and persistence. This is the high-level
+    // entry point for shell execution: it creates a running transcript entry, streams output as it
+    // arrives, finalizes the entry on completion, and persists the tab. Accepts an optional callback
+    // for when the full output is captured.
+    run(label, command, options) {
+        const index = Math.max(0, this.managers.tab.findIndex(label));
+        const cwd = this.managers.tab.cwdOf(label) ?? process.cwd();
+        const tab = this.managers.tab.tabs.find((t) => t.label === label);
+        if (!tab) {
+            options?.onComplete?.('');
+            return;
+        }
+        const before = tab.log.length;
+        const max = getConfig().transcriptMaxLines;
+        tab.log = [...tab.log, { input: command, output: '', running: true, cwd }];
+        if (tab.log.length > max)
+            tab.log = tab.log.slice(tab.log.length - max);
+        const trimmed = before + 1 - tab.log.length;
+        if (trimmed > 0)
+            messageBus.emit('transcript', { type: 'entries:trimmed', tabLabel: label, count: trimmed });
+        messageBus.emit('transcript', { type: 'entry:appended', tabLabel: label, entry: tab.log.at(-1), tab });
+        this.managers.tab.addBusy(label);
+        messageBus.emit('state', { type: 'dirty' });
+        const update = (output, running) => {
+            const t = this.managers.tab.tabs.find((x) => x.label === label);
+            if (t) {
+                const log = [...t.log];
+                const index_ = log.findLastIndex((e) => e.input === command && e.running);
+                if (index_ !== -1)
+                    log[index_] = { ...log[index_], output, running };
+                t.log = log;
+            }
+            if (!running) {
+                this.managers.tab.deleteBusy(label);
+                this.managers.tab.persist(this.managers.tab.buildAgentState(tab));
+            }
+            messageBus.emit('state', { type: 'dirty' });
+        };
+        this.execute(label, command, index, this.managers.tab.cwdOf(label), {
+            onChunk: (buffer) => update(buffer, true),
+            onDone: (result) => {
+                update(result, false);
+                this.managers.tab.markUnread(label);
+                if (result && tab)
+                    messageBus.emit('transcript', { type: 'entry:appended', tabLabel: label, entry: { input: '', output: result }, tab });
+                options?.onComplete?.(result);
+            },
+            onPwd: (pwd) => { this.managers.tab.setCwd(label, pwd); messageBus.emit('state', { type: 'dirty' }); },
+        });
+    }
+    // Low-level: run a command in the tab's persistent shell, spawning it if needed. `index` tags the
+    // streamed output so concurrent tabs don't cross sentinels. After the command completes the shell's
+    // pwd is queried and reported via `onPwd`. Chained onto `shellQueues` so this command's stdin
+    // write/listener pair never overlaps a still-in-flight pwd query from the previous command on
+    // the same shell (see `shellQueues`' comment).
+    execute(label, command, index, cwd, handlers) {
+        const shell = this.getShell(label, cwd);
+        const previous = this.shellQueues.get(label) ?? Promise.resolve();
+        const next = (async () => {
+            await previous;
+            await new Promise((resolve) => {
+                executeShellCommand(shell, command, index, handlers.onChunk, (result) => {
+                    handlers.onDone(result);
+                    queryShellPwd(shell, index, (pwd) => {
+                        if (pwd)
+                            handlers.onPwd(pwd);
+                        resolve();
+                    });
+                });
+            });
+        })();
+        this.shellQueues.set(label, next);
+    }
+    // Kill and forget a tab's shell. Returns whether a shell was actually open (drives the
+    // `connection close shell` result message). On `connection close shell` and tab close.
+    close(label) {
+        const shell = this.shells.get(label);
+        if (!shell)
+            return false;
+        shell.kill();
+        this.shells.delete(label);
+        this.shellQueues.delete(label);
+        return true;
+    }
+    // Kill every shell (app shutdown).
+    closeAll() {
+        for (const [, shell] of this.shells)
+            shell.kill();
+        this.shells.clear();
+        this.shellQueues.clear();
+    }
+}

package/dist/shell.js

@@ -0,0 +1,59 @@
+import { spawn } from 'node:child_process';
+import { sandboxSpawn } from './sandbox/index.js';
+// `sandbox`, when given a `workspaceDir`, confines the shell (and everything it spawns) to that
+// workspace (see sandbox.ts); omitted or workspaceDir-less, the shell runs exactly as before.
+export function spawnShell(_tabIndex, extraEnvironment, sandbox) {
+    const baseEnv = { ...process.env, ...extraEnvironment };
+    const { command, args, env } = sandboxSpawn(sandbox ?? {}, process.env.SHELL || 'bash', ['--norc', '--noprofile'], baseEnv);
+    const shell = spawn(command, args, {
+        stdio: ['pipe', 'pipe', 'pipe'],
+        env,
+    });
+    shell.stdout.setEncoding('utf8');
+    shell.stderr.setEncoding('utf8');
+    // Swallow EPIPE on stdin: the shell may exit while a write is in flight (e.g. during test cleanup).
+    shell.stdin.on('error', (err) => { if (err.code !== 'EPIPE')
+        throw err; });
+    return shell;
+}
+export function executeShellCmd(shell, command, tabIndex, onProgress, onComplete) {
+    const prompt = `__JS_END_${tabIndex}_${Date.now()}__`;
+    let outputBuffer = '';
+    const done = () => {
+        shell.stdout.removeListener('data', onChunk);
+        shell.stderr.removeListener('data', onChunk);
+    };
+    const onChunk = (chunk) => {
+        outputBuffer += chunk;
+        const endIndex = outputBuffer.indexOf(prompt);
+        if (endIndex === -1) {
+            onProgress(outputBuffer);
+        }
+        else {
+            const result = outputBuffer.slice(0, Math.max(0, endIndex)).trim();
+            done();
+            onComplete(result);
+        }
+    };
+    shell.stdout.on('data', onChunk);
+    shell.stderr.on('data', onChunk);
+    if (shell.stdin?.writable)
+        shell.stdin.write(`${command} 2>&1\necho "${prompt}"\n`);
+}
+export function queryShellPwd(shell, tabIndex, onResult) {
+    const prompt = `__PWD_${tabIndex}_${Date.now()}__`;
+    let buffer = '';
+    const onData = (chunk) => {
+        buffer += chunk;
+        const endIndex = buffer.indexOf(prompt);
+        if (endIndex !== -1) {
+            shell.stdout.removeListener('data', onData);
+            shell.stderr.removeListener('data', onData);
+            onResult(buffer.slice(0, Math.max(0, endIndex)).trim());
+        }
+    };
+    shell.stdout.on('data', onData);
+    shell.stderr.on('data', onData);
+    if (shell.stdin?.writable)
+        shell.stdin.write(`pwd\necho "${prompt}"\n`);
+}