portless-studio 0.1.2 → 0.1.4

package/dist/core/terminals/terminal-history.js

@@ -0,0 +1,53 @@
+/**
+ * What Studio keeps about terminals between runs, in `terminals.json` next to the config: the
+ * terminals that were running when it stopped, so they can run again, and the last commands run
+ * in each folder, offered when a new terminal opens there. See docs/terminals.md.
+ */
+export const EMPTY_TERMINAL_HISTORY = { running: [], recentCommands: {} };
+/** Commands remembered per folder. */
+export const MAX_RECENT_COMMANDS = 20;
+/** Reads `terminals.json`; anything it cannot read is left out rather than failing. */
+export function parseTerminalHistory(input) {
+    if (typeof input !== "object" || input === null)
+        return { running: [], recentCommands: {} };
+    const raw = input;
+    const running = Array.isArray(raw.running) ? raw.running.filter(isSavedTerminal) : [];
+    const recentCommands = {};
+    if (typeof raw.recentCommands === "object" && raw.recentCommands !== null) {
+        for (const [folder, list] of Object.entries(raw.recentCommands)) {
+            if (folder === "__proto__" || !Array.isArray(list))
+                continue;
+            const commands = list.filter((item) => typeof item === "string" && item.trim() !== "");
+            if (commands.length > 0)
+                recentCommands[folder] = commands.slice(0, MAX_RECENT_COMMANDS);
+        }
+    }
+    return { running, recentCommands };
+}
+/** Puts `command` first in the folder's list, once, and keeps the newest `MAX_RECENT_COMMANDS`. */
+export function rememberCommand(recent, cwd, command) {
+    const wanted = command.trim();
+    const copy = {};
+    for (const [folder, list] of Object.entries(recent))
+        copy[folder] = [...list];
+    if (wanted === "")
+        return copy;
+    const list = (copy[cwd] ?? []).filter((item) => item !== wanted);
+    copy[cwd] = [wanted, ...list].slice(0, MAX_RECENT_COMMANDS);
+    return copy;
+}
+function isSavedTerminal(value) {
+    if (typeof value !== "object" || value === null)
+        return false;
+    const item = value;
+    const optionalText = (field) => field === null || typeof field === "string";
+    return (typeof item.command === "string" &&
+        typeof item.cwd === "string" &&
+        item.cwd !== "" &&
+        typeof item.title === "string" &&
+        typeof item.startedAt === "number" &&
+        (item.startedBy === "program" || item.startedBy === "person") &&
+        optionalText(item.project) &&
+        optionalText(item.worktree) &&
+        optionalText(item.branch));
+}

package/dist/core/terminals/terminal.js

@@ -1,7 +1,3 @@
-/**
- * A terminal Studio runs: one command in one project folder, with its output kept so the page,
- * the CLI and agents can read it. See docs/terminals.md.
- */
 // Control sequences: CSI (colors, cursor), OSC (window title) and two-character escapes.
 const ESCAPES = new RegExp([
     String.raw `\u001b\[[0-?]*[ -/]*[@-~]`,

package/dist/server/application/port-discovery.js

@@ -1,10 +1,16 @@
 import { projectOf, suggestName, } from "../../core/ports/detected-port.js";
 import { containerProjectInfo } from "../../core/ports/docker-container.js";
+import { arrangeDetected, } from "../../core/ports/helper-ports.js";
+/** Only the main Detected list of `discoverPortGroups`. */
+export async function discoverPorts(scanner, projects, context) {
+    return (await discoverPortGroups(scanner, projects, context)).detected;
+}
 /**
  * Listening ports a person would want to name: they answer HTTP, have no portless route, and are
- * not Studio, the proxy or something the config ignores. Sorted by port.
+ * not Studio, the proxy or something the config ignores. Debuggers, ephemeral ports and ports of a
+ * server that already has a name go to `otherPorts` (see `arrangeDetected`). Sorted by port.
  */
-export async function discoverPorts(scanner, projects, context) {
+export async function discoverPortGroups(scanner, projects, context) {
     const skippedPorts = new Set([
         ...context.routes.map((route) => route.port),
         ...context.excludedPorts,
@@ -14,7 +20,8 @@ export async function discoverPorts(scanner, projects, context) {
     const published = containerPorts(context.containers ?? [], skippedPorts, ignored);
     // A port whose process we cannot read belongs to another user or the system (printing, DNS),
     // never to a dev server this person started. A container's port is shown as the container.
-    const candidates = (await scanner.scan()).filter((port) => port.pid !== null &&
+    const scanned = await scanner.scan();
+    const candidates = scanned.filter((port) => port.pid !== null &&
         !skippedPorts.has(port.port) &&
         !published.has(port.port) &&
         !isIgnoredProcess(port.processName, ignored));
@@ -25,7 +32,7 @@ export async function discoverPorts(scanner, projects, context) {
         Promise.all(fromContainers.map(([port]) => scanner.answersHttp(port))),
     ]);
     const template = context.config.nameTemplate;
-    return [
+    const found = [
         ...candidates
             .filter((port, index) => answers[index] && isDevServer(port, projects))
             .map((port) => toDetected(port, projects, template)),
@@ -33,6 +40,31 @@ export async function discoverPorts(scanner, projects, context) {
             .filter((_, index) => containerAnswers[index])
             .map(([port, container]) => containerDetected(port, container, template)),
     ].sort((a, b) => a.port - b.port);
+    return arrangeDetected({
+        detected: found,
+        debuggers: await debuggerProbes(scanner, found),
+        ephemeralRange: context.ephemeralRange ?? null,
+        showEphemeral: context.config.showEphemeralPorts,
+        routes: listeningRoutes(context.routes, scanned),
+    });
+}
+const UNKNOWN = "unknown";
+async function debuggerProbes(scanner, found) {
+    const probe = scanner.probeDebugger?.bind(scanner);
+    if (!probe)
+        return new Map();
+    const answers = await Promise.all(found.map((item) => probe(item.port).catch(() => UNKNOWN)));
+    return new Map(found.map((item, index) => [item.port, answers[index] ?? UNKNOWN]));
+}
+/** Routes whose port a readable process listens on now; a closed route claims no siblings. */
+function listeningRoutes(routes, scanned) {
+    const byPort = new Map(scanned.map((port) => [port.port, port]));
+    return routes.flatMap((route) => {
+        const listener = byPort.get(route.port);
+        if (!listener || listener.pid === null)
+            return [];
+        return [{ name: route.name, port: route.port, pid: listener.pid, cwd: listener.cwd }];
+    });
 }
 /** Published port -> container, without the ports the filters skip. */
 function containerPorts(containers, skippedPorts, ignored) {
@@ -111,5 +143,6 @@ function toDetected(port, projects, nameTemplate) {
         cwd: port.cwd,
         suggestedName: info === null ? null : suggestName(info, nameTemplate, port.port),
         ...(project === null ? {} : { project }),
+        ...(port.startedAt === undefined ? {} : { startedAt: port.startedAt }),
     };
 }

package/dist/server/application/studio-runtime.js

@@ -8,7 +8,7 @@ import { appError } from "./app-error.js";
 import { memoryAutoNamedStore, } from "./auto-named-store.js";
 import { AutoNamer } from "./auto-namer.js";
 import { IconResolver } from "./icon-resolver.js";
-import { discoverPorts } from "./port-discovery.js";
+import { discoverPortGroups } from "./port-discovery.js";
 import { EventLog, eventsBetween } from "./studio-events.js";
 import { SYSTEM_NOTIFICATION_KINDS } from "./system-notifier.js";
 /** Keeps the projects in memory only; for tests and for `init`, which runs once. */
@@ -43,6 +43,7 @@ export class StudioRuntime {
     #icons;
     #routeProjectStore;
     #containers;
+    #ephemeralRange;
     #shortUrls;
     #ready = Promise.resolve();
     /** Last project seen per route name; null until read from the store. */
@@ -85,6 +86,7 @@ export class StudioRuntime {
         this.#notifier = options.notifier ?? null;
         this.#routeProjectStore = options.routeProjectStore ?? memoryRouteProjectStore();
         this.#containers = options.containers ?? null;
+        this.#ephemeralRange = options.ephemeralRange ?? null;
         this.#shortUrls = options.shortUrls ?? null;
         this.#shortUrls?.onChange(() => this.#notify());
         const noIcons = {
@@ -147,14 +149,15 @@ export class StudioRuntime {
     async readSnapshot(options = {}) {
         const state = await this.#registry.readSnapshot();
         const config = await this.#currentConfig();
-        const detected = await this.#detect(state, config, false);
-        this.#lastDetected = JSON.stringify(detected);
+        const found = await this.#detect(state, config, false);
+        this.#lastDetected = JSON.stringify(found);
         const routes = await this.#detailedRoutes(state.routes);
         const snapshot = {
             proxy: state.proxy,
             portless: state.portless,
             routes,
-            detected,
+            detected: found.detected,
+            otherPorts: found.otherPorts,
             autoName: config.autoName,
             readAt: state.readAt,
         };
@@ -183,7 +186,7 @@ export class StudioRuntime {
     /** One fresh scan with the current config, filtered the same way as the snapshot. */
     async detectPorts() {
         const state = await this.#registry.readSnapshot();
-        return this.#detect(state, await this.#currentConfig(), true);
+        return (await this.#detect(state, await this.#currentConfig(), true)).detected;
     }
     /** The config in effect: the file as last read, or the defaults while it is broken. */
     settings() {
@@ -195,11 +198,12 @@ export class StudioRuntime {
      */
     async stoppablePids() {
         const state = await this.#registry.readSnapshot();
-        const detected = await this.#detect(state, await this.#currentConfig(), true);
+        const found = await this.#detect(state, await this.#currentConfig(), true);
         const pids = new Map();
-        for (const item of detected)
+        for (const item of [...found.detected, ...found.otherPorts]) {
             if (item.pid !== null)
                 pids.set(item.pid, item.port);
+        }
         const pidByPort = this.#pidByPort();
         for (const route of state.routes) {
             const pid = pidByPort.get(route.port);
@@ -215,7 +219,8 @@ export class StudioRuntime {
      */
     async openableFolders() {
         const state = await this.#registry.readSnapshot();
-        const detected = await this.#detect(state, await this.#currentConfig(), false);
+        const found = await this.#detect(state, await this.#currentConfig(), false);
+        const detected = [...found.detected, ...found.otherPorts];
         const routes = await this.#detailedRoutes(state.routes);
         const folders = new Set();
         for (const item of [...routes, ...detected]) {
@@ -278,9 +283,11 @@ export class StudioRuntime {
     }
     async #detect(state, config, fresh) {
         const scan = await this.#scanPorts(fresh ? 0 : config.scanIntervalMs);
+        const probeDebugger = this.#scanner.probeDebugger?.bind(this.#scanner);
         const cached = {
             scan: async () => scan.ports,
             answersHttp: (port) => this.#scanner.answersHttp(port),
+            ...(probeDebugger ? { probeDebugger } : {}),
         };
         const forwarderPort = this.#shortUrls?.publicPort() ?? null;
         const excludedPorts = [
@@ -289,18 +296,23 @@ export class StudioRuntime {
             state.proxy.port,
             ...scan.proxyPorts,
         ].filter((port) => port !== null);
-        const found = await discoverPorts(cached, this.#projects, {
+        const found = await discoverPortGroups(cached, this.#projects, {
             config,
             routes: state.routes,
             excludedPorts,
             containers: scan.containers,
+            ephemeralRange: await this.#readEphemeralRange(),
         });
-        return found.map((item) => {
+        const withProject = (item) => {
             if (item.cwd === null || !item.project)
                 return item;
             const project = itemProjectAt(this.#projects.read(item.cwd), item.cwd);
             return project === null ? item : { ...item, project };
-        });
+        };
+        return {
+            detected: found.detected.map(withProject),
+            otherPorts: found.otherPorts.map(withProject),
+        };
     }
     /** Reuses a scan younger than `maxAgeMs`, and shares one scan between concurrent callers. */
     #scanPorts(maxAgeMs) {
@@ -314,6 +326,12 @@ export class StudioRuntime {
         });
         return this.#scanning;
     }
+    /** A range that cannot be read turns the ephemeral rule off rather than failing the scan. */
+    async #readEphemeralRange() {
+        if (!this.#ephemeralRange)
+            return null;
+        return this.#ephemeralRange().catch(() => null);
+    }
     /** Docker is optional: any failure to read it means no containers, never a failed scan. */
     async #readContainers() {
         if (!this.#containers)
@@ -340,19 +358,20 @@ export class StudioRuntime {
         try {
             let state = await this.#registry.readSnapshot();
             const config = await this.#currentConfig();
-            let detected = await this.#detect(state, config, true);
-            // Each step reads the routes again after the previous one changed them.
-            if (config.autoName && (await this.#namer.name(detected)) > 0) {
+            const first = await this.#detect(state, config, true);
+            // Each step reads the routes again after the previous one changed them. Other ports are
+            // helpers of a named server, debuggers or temporary ports: auto mode never names them.
+            if (config.autoName && (await this.#namer.name(first.detected)) > 0) {
                 state = await this.#registry.readSnapshot();
             }
             if (await this.#removeAbandonedAutoNames(state, config)) {
                 state = await this.#registry.readSnapshot();
             }
-            detected = await this.#detect(state, config, false);
+            const found = await this.#detect(state, config, false);
             const healthChanged = await this.#probeRoutes(state.routes);
             const routes = await this.#detailedRoutes(state.routes);
-            this.#observe({ ...state, routes, detected }, config);
-            if (healthChanged || JSON.stringify(detected) !== this.#lastDetected)
+            this.#observe({ ...state, routes, detected: found.detected }, config);
+            if (healthChanged || JSON.stringify(found) !== this.#lastDetected)
                 this.#notify();
         }
         catch (error) {
@@ -384,6 +403,7 @@ export class StudioRuntime {
             return {
                 ...route,
                 ...(listener?.pid == null ? {} : { listenerPid: listener.pid }),
+                ...(listener?.startedAt === undefined ? {} : { startedAt: listener.startedAt }),
                 ...(project === null ? {} : { project }),
                 ...(health === undefined ? {} : { health }),
             };

package/dist/server/application/terminals.js

@@ -1,5 +1,6 @@
 import { err, ok } from "../../core/result.js";
 import { OutputBuffer } from "../../core/terminals/output-buffer.js";
+import { rememberCommand, } from "../../core/terminals/terminal-history.js";
 import { appError } from "./app-error.js";
 const DEFAULT_MAX_OUTPUT = 2 * 1024 * 1024;
 const DEFAULT_GRACE_MS = 3_000;
@@ -9,6 +10,13 @@ const DEFAULT_COLS = 120;
 const DEFAULT_ROWS = 30;
 const MAX_COMMAND_CHARS = 8 * 1024;
 const MAX_TITLE_CHARS = 60;
+const DEFAULT_PERSIST_DELAY_MS = 300;
+/**
+ * A command that ended this shortly before Studio stopped counts as running then: a service
+ * manager stops Studio's commands together with Studio, and their exits can arrive first.
+ */
+const RECENT_EXIT_MS = 2_000;
+const RESTART_NOTE = "\r\n[Studio] Stopped by a Studio restart. Run it again to start it.\r\n";
 /**
  * The terminals Studio runs. Each keeps its last `maxOutputChars` of output, numbered so a client
  * can resume where it stopped. From a page, commands run only in folders Studio shows; a local
@@ -25,6 +33,11 @@ export class TerminalManager {
     #namingTimeoutMs;
     #processTree;
     #homeDir;
+    #history;
+    #persistDelayMs;
+    #recent = null;
+    #persistTimer;
+    #closing = false;
     #entries = new Map();
     #watchers = new Set();
     /** Folders a local program ran a terminal in. */
@@ -45,6 +58,8 @@ export class TerminalManager {
         this.#namingTimeoutMs = options.namingTimeoutMs ?? DEFAULT_NAMING_TIMEOUT_MS;
         this.#processTree = options.processTree;
         this.#homeDir = options.homeDir;
+        this.#history = options.history;
+        this.#persistDelayMs = options.persistDelayMs ?? DEFAULT_PERSIST_DELAY_MS;
     }
     get mode() {
         return this.#spawner.mode;
@@ -73,6 +88,7 @@ export class TerminalManager {
         const wanted = title.trim().slice(0, MAX_TITLE_CHARS);
         entry.info = { ...entry.info, title: wanted || entry.defaultTitle };
         this.#publishStatus(entry);
+        this.#schedulePersist();
         return ok({ ...entry.info });
     }
     async create(request, origin) {
@@ -87,69 +103,97 @@ export class TerminalManager {
             return cwd;
         if (origin.trusted)
             this.#trustedFolders.add(cwd.value);
-        const id = `t${this.#nextId++}`;
-        const cols = readSize(request.cols, DEFAULT_COLS);
-        const rows = readSize(request.rows, DEFAULT_ROWS);
         const naming = readNaming(request.name);
-        const defaultTitle = (command.value || this.#spawner.shellName || "shell").slice(0, MAX_TITLE_CHARS);
-        const title = request.title?.trim().slice(0, MAX_TITLE_CHARS) || defaultTitle;
         const project = await this.#projectOf(cwd.value);
-        const entry = {
-            defaultTitle,
-            info: {
-                id,
-                title,
-                cwd: cwd.value,
-                command: command.value ?? "",
-                project: project?.name ?? null,
-                worktree: project?.worktree ?? null,
-                branch: project?.branch ?? null,
-                ports: [],
-                status: "running",
-                exitCode: null,
-                startedAt: this.#now(),
-                endedAt: null,
-                pid: null,
-                mode: this.#spawner.mode,
-                cols,
-                rows,
-                nextSeq: 0,
-                naming,
-            },
-            request: {
-                command: command.value,
-                cwd: cwd.value,
-                cols,
-                rows,
-                env: {
-                    TERM: "xterm-256color",
-                    COLUMNS: String(cols),
-                    LINES: String(rows),
-                    PORTLESS_STUDIO_TERMINAL: id,
-                },
-            },
-            buffer: new OutputBuffer(this.#maxOutput),
-            process: null,
-            stopTimers: [],
-            watchers: new Set(),
-            baseline: null,
-            namingTimer: undefined,
-        };
+        const entry = this.#newEntry({
+            id: `t${this.#nextId++}`,
+            command: command.value,
+            cwd: cwd.value,
+            title: request.title,
+            cols: readSize(request.cols, DEFAULT_COLS),
+            rows: readSize(request.rows, DEFAULT_ROWS),
+            naming,
+            project,
+            startedBy: origin.trusted ? "program" : "person",
+            startedAt: this.#now(),
+        });
         if (naming)
             entry.baseline = await this.#portsInUse();
         const started = await this.#spawn(entry);
         if (!started.ok)
             return started;
-        this.#entries.set(id, entry);
+        this.#entries.set(entry.info.id, entry);
+        if (command.value) {
+            this.#recent = rememberCommand(this.#recentCommands(), cwd.value, command.value);
+        }
         if (naming)
             this.#startNaming(entry);
         else
             this.#updateWorkspaceWatch();
         this.#changed();
+        this.#schedulePersist();
         if (this.#watchers.size > 0)
             void this.#refreshPorts();
         return ok({ ...entry.info });
     }
+    /** The last commands run in each folder, newest first. */
+    recentCommands() {
+        return Object.fromEntries(Object.entries(this.#recentCommands()).map(([folder, list]) => [folder, [...list]]));
+    }
+    /**
+     * Brings back the terminals that were running when Studio last stopped: listed as stopped by a
+     * restart (`ask`), started again unless they are a plain shell (`always`), or forgotten
+     * (`never`). Folders that no longer exist are skipped. Call it once, on start.
+     */
+    async restore(mode) {
+        if (this.#closing)
+            return;
+        const saved = this.#history?.read().running ?? [];
+        if (mode === "never" || saved.length === 0) {
+            if (saved.length > 0)
+                this.#persistNow();
+            return;
+        }
+        const restored = [];
+        for (const item of saved) {
+            if (this.#entries.size >= this.#maxTerminals)
+                break;
+            const cwd = this.#folders.directory(item.cwd);
+            if (cwd === null)
+                continue;
+            if (item.startedBy === "program")
+                this.#trustedFolders.add(cwd);
+            const entry = this.#newEntry({
+                id: `t${this.#nextId++}`,
+                command: item.command || null,
+                cwd,
+                title: item.title,
+                cols: DEFAULT_COLS,
+                rows: DEFAULT_ROWS,
+                naming: null,
+                project: { name: item.project ?? "", worktree: item.worktree, branch: item.branch },
+                startedBy: item.startedBy,
+                startedAt: item.startedAt,
+            });
+            if (item.project === null) {
+                entry.info = { ...entry.info, project: null, worktree: null, branch: null };
+            }
+            entry.info = { ...entry.info, status: "exited", stoppedByRestart: true };
+            this.#append(entry, RESTART_NOTE);
+            this.#entries.set(entry.info.id, entry);
+            restored.push(entry);
+        }
+        this.#changed();
+        this.#persistNow();
+        if (mode !== "always")
+            return;
+        for (const entry of restored) {
+            if (this.#closing)
+                return;
+            if (entry.info.command !== "")
+                await this.restart(entry.info.id);
+        }
+    }
     input(id, text) {
         const entry = this.#entries.get(id);
         if (!entry)
@@ -166,6 +210,7 @@ export class TerminalManager {
             return notFound(id);
         if (!entry.process || entry.info.status !== "running")
             return ok({ ...entry.info });
+        entry.stoppedOnPurpose = true;
         this.#escalate(entry, entry.process);
         return ok({ ...entry.info });
     }
@@ -177,16 +222,36 @@ export class TerminalManager {
         const current = entry.process;
         if (current && entry.info.status === "running") {
             const ended = new Promise((resolve) => current.onExit(() => resolve()));
+            entry.stoppedOnPurpose = true;
             this.#escalate(entry, current);
             await ended;
         }
         this.#append(entry, `\r\n[Studio] restarted: ${entry.info.command || "shell"}\r\n`);
+        if (entry.info.project === null) {
+            const project = await this.#projectOf(entry.info.cwd);
+            if (project) {
+                entry.info = {
+                    ...entry.info,
+                    project: project.name,
+                    worktree: project.worktree ?? null,
+                    branch: project.branch ?? null,
+                };
+            }
+        }
         const started = await this.#spawn(entry);
         if (!started.ok)
             return started;
-        entry.info = { ...entry.info, status: "running", exitCode: null, endedAt: null };
+        entry.stoppedOnPurpose = false;
+        entry.info = {
+            ...entry.info,
+            status: "running",
+            exitCode: null,
+            endedAt: null,
+            stoppedByRestart: false,
+        };
         entry.info.startedAt = this.#now();
         this.#publishStatus(entry);
+        this.#schedulePersist();
         this.#updateWorkspaceWatch();
         if (this.#watchers.size > 0)
             void this.#refreshPorts();
@@ -205,6 +270,7 @@ export class TerminalManager {
         entry.watchers.clear();
         this.#updateWorkspaceWatch();
         this.#changed();
+        this.#schedulePersist();
         return ok(undefined);
     }
     read(id, from, maxChars) {
@@ -225,8 +291,16 @@ export class TerminalManager {
         entry.watchers.add(watcher);
         return ok(() => entry.watchers.delete(watcher));
     }
-    /** Studio is stopping: every command gets SIGTERM and SIGKILL right away. */
+    /**
+     * Studio is stopping: the terminals still running are written down for the next start, then
+     * every command gets SIGTERM and SIGKILL right away.
+     */
     closeAll() {
+        if (!this.#closing) {
+            this.#persistNow(true);
+            this.#closing = true;
+            clearTimeout(this.#persistTimer);
+        }
         for (const entry of this.#entries.values()) {
             this.#clearTimers(entry);
             if (entry.process && entry.info.status === "running") {
@@ -267,10 +341,108 @@ export class TerminalManager {
             }
             entry.info.ports = [];
             this.#publishStatus(entry);
+            this.#schedulePersist();
             this.#updateWorkspaceWatch();
         });
         return ok(undefined);
     }
+    #newEntry(fields) {
+        const defaultTitle = (fields.command || this.#spawner.shellName || "shell").slice(0, MAX_TITLE_CHARS);
+        const title = fields.title?.trim().slice(0, MAX_TITLE_CHARS) || defaultTitle;
+        const { id, cols, rows } = fields;
+        return {
+            defaultTitle,
+            info: {
+                id,
+                title,
+                cwd: fields.cwd,
+                command: fields.command ?? "",
+                project: fields.project?.name ?? null,
+                worktree: fields.project?.worktree ?? null,
+                branch: fields.project?.branch ?? null,
+                ports: [],
+                status: "running",
+                exitCode: null,
+                startedAt: fields.startedAt,
+                endedAt: null,
+                pid: null,
+                mode: this.#spawner.mode,
+                cols,
+                rows,
+                nextSeq: 0,
+                naming: fields.naming,
+                startedBy: fields.startedBy,
+                stoppedByRestart: false,
+            },
+            request: {
+                command: fields.command,
+                cwd: fields.cwd,
+                cols,
+                rows,
+                env: {
+                    TERM: "xterm-256color",
+                    COLUMNS: String(cols),
+                    LINES: String(rows),
+                    PORTLESS_STUDIO_TERMINAL: id,
+                },
+            },
+            buffer: new OutputBuffer(this.#maxOutput),
+            process: null,
+            stopTimers: [],
+            watchers: new Set(),
+            baseline: null,
+            namingTimer: undefined,
+            stoppedOnPurpose: false,
+        };
+    }
+    #recentCommands() {
+        this.#recent ??= this.#history?.read().recentCommands ?? {};
+        return this.#recent;
+    }
+    #schedulePersist() {
+        if (!this.#history || this.#closing || this.#persistTimer)
+            return;
+        this.#persistTimer = setTimeout(() => {
+            this.#persistTimer = undefined;
+            this.#persistNow();
+        }, this.#persistDelayMs);
+        this.#persistTimer.unref?.();
+    }
+    /**
+     * Writes the terminals that run and the recent commands. When Studio stops, commands that just
+     * ended without anyone asking count as running too.
+     */
+    #persistNow(stopping = false) {
+        const history = this.#history;
+        if (!history || this.#closing)
+            return;
+        clearTimeout(this.#persistTimer);
+        this.#persistTimer = undefined;
+        const now = this.#now();
+        const running = [...this.#entries.values()]
+            .filter((entry) => entry.info.status === "running" ||
+            entry.info.stoppedByRestart === true ||
+            (stopping &&
+                !entry.stoppedOnPurpose &&
+                entry.info.endedAt !== null &&
+                now - entry.info.endedAt <= RECENT_EXIT_MS))
+            .map(({ info }) => ({
+            command: info.command,
+            cwd: info.cwd,
+            title: info.title,
+            startedAt: info.startedAt,
+            startedBy: info.startedBy ?? "person",
+            project: info.project,
+            worktree: info.worktree,
+            branch: info.branch,
+        }));
+        try {
+            history.write({ running, recentCommands: this.#recentCommands() });
+        }
+        catch {
+            // A full disk or a read-only config folder: terminals keep working, they just are not kept.
+        }
+    }
     #escalate(entry, child) {
         this.#clearTimers(entry);
         child.interrupt();