agentus 0.3.1 → 0.3.3

package/packages/server/src/acp/session-manager.ts

@@ -159,6 +159,12 @@ interface LiveSession {
    *  so a second interrupting utterance that already started its own turn is not mistaken for
    *  "the one I cancelled is still running". */
   turnSeq: number;
+  /** When the operator last USED this slot — he opened it, or his page reported it as the one on
+   *  screen. In memory on purpose: this is the half of the idle rule that says "he was just here",
+   *  and the store's message clock (which survives restarts) is the other half. Reading only the
+   *  message clock reaped a slot he had clicked into a minute earlier (see `touch()` and the clock
+   *  in `startIdleReaper`). */
+  touchedAt: number;
   /** Text sinks for sessions that live on this connection but are NOT the one in the rail —
    *  today only the throwaway fork used to summarise the conversation for a title. Anything
    *  whose sessionId is not `info.acpSessionId` is routed here and never persisted. */
@@ -367,6 +373,10 @@ export class SessionManager {
       child, busy: false, pendingPermissions: new Map(), alwaysAllow: new Set(), stderrBuf: [],
       caps: { fork: false, load: false }, turnSeq: 0, collectors: new Map(), planReminderPending: true,
       planToken: randomUUID(),
+      // A brand-new process is, by definition, freshly used: the click that spawned it is the
+      // activity. Without this the slot inherits the store's message clock — yesterday's — and the
+      // reaper's first tick after the spawn kills the process the operator just asked for.
+      touchedAt: Date.now(),
       // Until this slot's first PROMPT, anything the agent says is its own history being replayed,
       // not an answer (see #onSessionUpdate). A resumed agent re-sends its whole transcript on
       // `session/load` — full-length blocks, no messageId — and persisting those wrote 1240 rows
@@ -515,6 +525,10 @@ export class SessionManager {
       child, busy: false, pendingPermissions: new Map(), alwaysAllow: new Set(), stderrBuf: [],
       caps: { fork: false, load: false }, turnSeq: 0, collectors: new Map(), planReminderPending: true,
       planToken: randomUUID(),
+      // A brand-new process is, by definition, freshly used: the click that spawned it is the
+      // activity. Without this the slot inherits the store's message clock — yesterday's — and the
+      // reaper's first tick after the spawn kills the process the operator just asked for.
+      touchedAt: Date.now(),
       // Until this slot's first PROMPT, anything the agent says is its own history being replayed,
       // not an answer (see #onSessionUpdate). A resumed agent re-sends its whole transcript on
       // `session/load` — full-length blocks, no messageId — and persisting those wrote 1240 rows
@@ -1007,7 +1021,7 @@ export class SessionManager {
         command: process.execPath,
         args: [path.join(path.dirname(fileURLToPath(import.meta.url)), "../../mcp/plan-server.mjs")],
         env: [
-          { name: "AGENTUS_PLAN_ENDPOINT", value: `http://127.0.0.1:${process.env.AGENTUS_PORT ?? 8787}` },
+          { name: "AGENTUS_PLAN_ENDPOINT", value: `http://127.0.0.1:${process.env.AGENTUS_PORT ?? 8788}` },
           { name: "AGENTUS_PLAN_TOKEN", value: live.planToken },
           { name: "AGENTUS_PLAN_SESSION", value: live.info.id },
         ],
@@ -1246,7 +1260,50 @@ export class SessionManager {
     this.#sessions.delete(live.info.id);
   }
 
-  /** Reclaim idle slots: stop the agent process of a session nobody has touched for the operator's
+  /** The operator just USED this slot: he opened it, or his page reported it as the one on screen.
+   *
+   *  Idempotent and cheap — the cockpit reports presence every few seconds, so while a slot is on
+   *  screen this is called continuously and the idle clock never runs out under a conversation he
+   *  is reading; the moment he switches away it stops, and the slot gets the full threshold from
+   *  the last report instead of from its last MESSAGE.
+   *
+   *  Only the in-memory clock moves. `info.lastAt` stays the store's message time on purpose: it is
+   *  what the rail's relative stamps and the "last activity" hint mean, and making it say 刚刚 for a
+   *  session nobody has written to would be the UI lying. */
+  touch(id: string): void {
+    const live = this.#sessions.get(id);
+    if (!live || live.info.status === "closed" || live.info.status === "reaped") return;
+    live.touchedAt = Date.now();
+  }
+
+  /** The `n` most recently USED sessions that are not archived — 「热备」, the slots whose process is
+   *  kept no matter how quiet they go. Explicitly a FLOOR, not a cap: it names which slots may not be
+   *  reclaimed for being idle; it never bounds how many may run.
+   *
+   *  Ranked over live AND COLD rows by the same clock the sweep uses (`max(touchedAt, lastActivity,
+   *  createdAt)`). Ranking only the live ones would leak the meaning: after a reap the seat would fall
+   *  to whatever still happens to hold a process, so a session nobody has opened in days could inherit
+   *  it and be shielded by the very rule that just fired on his own recent session.
+   *
+   *  Archived rows never take a seat — 归档 is 「收起来」, its process is meant to go — so the seat
+   *  passes to the next most recent one instead of being held by a row he put away. */
+  #warmSet(n: number): Set<string> {
+    const lastAt = this.#store.lastActivityAt();
+    return new Set(
+      this.#store
+        .listSessions(true)
+        .filter((r) => r.archivedAt == null)
+        .map((r) => ({
+          id: r.id,
+          at: Math.max(this.#sessions.get(r.id)?.touchedAt ?? 0, lastAt.get(r.id) ?? 0, r.createdAt),
+        }))
+        .sort((a, b) => b.at - a.at)
+        .slice(0, n)
+        .map((r) => r.id),
+    );
+  }
+
+  /** Reclaim slots: stop the agent process of a session nobody has touched for the operator's
    *  threshold. Deliberately NOT an archive — the row stays in 工作空间 wearing `reaped` and a click
    *  brings it back. AionUi ships exactly this switch (设置 → 系统 → 「Agent 空闲超时（分钟）」,
    *  default 5, 1–60) and the guards below are what its changelog had to add after the first version
@@ -1254,23 +1311,66 @@ export class SessionManager {
    *  one the operator is WATCHING right now (a reply that lands while he reads it must not be killed
    *  under him).
    *
-   *  `idleMs()` is read on every tick, so a settings change applies with no restart; 0 = off. */
-  startIdleReaper(opts: { idleMs: () => number; watched?: (id: string) => boolean; intervalMs?: number }): () => void {
+   *  TWO deadlines, and the difference is the whole point (2026-10-10): `idleMs` is the operator's
+   *  answer to 「空闲多久收掉」 for the sessions he is NOT working in, while the 热备 set (`warmSlots`,
+   *  the most recently used ones) is exempt from it — 「即使空闲也保留在那里」 — and only obeys its own
+   *  much longer `warmTtlMs`. A single time rule was what made 「我只是离开浏览器」 cost him the agent
+   *  of the session he had been in a minute earlier.
+   *
+   *  Every callback is read on EVERY tick, so a settings change applies with no restart (a restart
+   *  would kill exactly the slots this feature exists to keep alive cheaply); 0 = off for `idleMs`,
+   *  0 = 不过期 for `warmTtlMs`. */
+  startIdleReaper(opts: {
+    idleMs: () => number;
+    /** How many of the most recent sessions are 热备 — exempt from `idleMs`. Read per tick, like the
+     *  threshold itself: changing it in 设置 must apply without a restart (a restart would kill
+     *  exactly the slots this feature exists to keep alive cheaply). */
+    warmSlots: () => number;
+    /** How long a warm slot may stay untouched before even its exemption expires; 0 = 不过期.
+     *  Read per tick too, and it is a SEPARATE deadline from `idleMs` (hours, not minutes). */
+    warmTtlMs: () => number;
+    watched?: (id: string) => boolean;
+    intervalMs?: number;
+  }): () => void {
     const interval = opts.intervalMs ?? 30_000;
+    /** Two decimals where it matters: a QA run drives these thresholds in SECONDS, and 「0 min」 on
+     *  both sides of the message is a log line that cannot be read. */
+    const fmt = (ms: number): string =>
+      ms < 3_600_000 ? `${(ms / 60_000).toFixed(1)} min` : `${(ms / 3_600_000).toFixed(1)} h`;
     const tick = (): void => {
       const idleMs = opts.idleMs();
-      if (!(idleMs > 0)) return;
+      const warmTtlMs = opts.warmTtlMs();
+      // Either rule alone is a reason to sweep (idle off + a warm TTL still expires warm slots).
+      if (!(idleMs > 0) && !(warmTtlMs > 0)) return;
+      const warmN = opts.warmSlots();
+      const warm = warmN > 0 ? this.#warmSet(warmN) : null;
       const now = Date.now();
       let reaped = 0;
       for (const s of [...this.#sessions.values()]) {
         if (s.busy || s.pendingPermissions.size) continue;
         if (s.info.status === "starting" || s.info.status === "running") continue;
         if (opts.watched?.(s.info.id)) continue;
-        const lastAt = s.info.lastAt ?? s.info.createdAt;
-        if (now - lastAt < idleMs) continue;
-        console.log(
-          `[agentus] idle reap: ${s.info.id} (${Math.round((now - lastAt) / 60_000)} min idle, limit ${Math.round(idleMs / 60_000)} min)`,
-        );
+        // The clock is the LATER of two things: the last MESSAGE this session has (store time, which
+        // survives restarts) and the last time the operator actually USED the slot (`touchedAt` — the
+        // click that respawned it, or the page reporting it as the one on screen). Reading only the
+        // message clock is how a slot he had just opened got reaped a minute later (2026-10-10:
+        // 「刚点进去、没发消息、换个会话过一分钟 acp 就被回收」) — the fresh process inherited a
+        // days-old stamp, so the very next tick found it over the threshold.
+        const lastAt = Math.max(s.touchedAt, s.info.lastAt ?? 0, s.info.createdAt);
+        const age = now - lastAt;
+        if (warm?.has(s.info.id)) {
+          // 热备 = 「即使空闲也保留在这里」. The idle rule does not apply; only its own, much longer
+          // deadline does — otherwise five quiet slots are a permanent ~700 MB floor.
+          if (!(warmTtlMs > 0) || age < warmTtlMs) continue;
+          console.log(
+            `[agentus] warm slot expired: ${s.info.id} (${fmt(age)} untouched, warm ttl ${fmt(warmTtlMs)})`,
+          );
+        } else {
+          if (!(idleMs > 0) || age < idleMs) continue;
+          console.log(
+            `[agentus] idle reap: ${s.info.id} (${Math.round(age / 60_000)} min idle, limit ${Math.round(idleMs / 60_000)} min)`,
+          );
+        }
         this.#stop(s, "reaped");
         reaped += 1;
       }

package/packages/server/src/index.ts

@@ -25,7 +25,7 @@ import * as auth from "./auth.js";
 import { NotifyCenter } from "./notify/center.js";
 import type { BackendId, ClientCommand, PermissionDecision, PromptAttachment, ServerEvent } from "../../shared/src/index.js";
 
-const PORT = Number(process.env.AGENTUS_PORT ?? 8787);
+const PORT = Number(process.env.AGENTUS_PORT ?? 8788);
 // Data + web build resolve against THIS FILE, not the shell's cwd: `scripts/start.sh`
 // launches from the repo root while the dev server runs from packages/server, and a
 // cwd-relative path would silently open a second database (the operator's slots would
@@ -196,6 +196,10 @@ const notify = new NotifyCenter({
   operator: (req, url) => Boolean(auth.authenticate(req.headers, url)),
   // The companion artifact, so the phone panel in 设置 can show its size without a second request.
   apkPath: APK_FILE,
+  // The page reporting which session it is showing is also the idle reaper's clock: opening a slot
+  // (and staying in it) counts as USED, so switching away gives it a full threshold instead of
+  // reaping it on the next tick because its last MESSAGE was days ago.
+  onFocus: (sessionId: string) => mgr.touch(sessionId),
   // Username+password pairing: the phone types the same login the browser uses. The check and
   // its rate limit stay here, in auth.ts, so a phone cannot have a laxer door than the UI.
   credentials: (username, password, ip) => {
@@ -266,6 +270,11 @@ setHotwordSource((sessionId) => hotwordsFor(store, sessionId).map((h) => h.word)
   };
   const envIdle = envNum(process.env.AGENTUS_IDLE_KILL_MIN);
   const envIdleMs = envIdle != null ? envIdle * 60_000 : null;
+  // 热备 (warm slots): same ABSENT≠0 discipline as above. The TTL takes a FRACTION of a minute so the
+  // warm-EXPIRY path can be exercised in seconds rather than by waiting out a day.
+  const envWarm = envNum(process.env.AGENTUS_WARM_SLOTS);
+  const envWarmTtlMin = envNum(process.env.AGENTUS_WARM_TTL_MIN);
+  const envWarmTtlMs = envWarmTtlMin != null ? envWarmTtlMin * 60_000 : null;
   const envSweep = envNum(process.env.AGENTUS_IDLE_SWEEP_MS);
   const sweepMs = envSweep != null && envSweep >= 1000 ? envSweep : 30_000;
   const source = envIdleMs != null ? "AGENTUS_IDLE_KILL_MIN" : "settings.agent.idleKillMin";
@@ -274,8 +283,18 @@ setHotwordSource((sessionId) => hotwordsFor(store, sessionId).map((h) => h.word)
       envIdleMs != null ? envIdle : agentSettings().idleKillMin
     } min (${source}), sweep ${Math.round(sweepMs / 1000)}s, 0 = off`,
   );
+  // The warm set is the other half of the same decision (which slots survive being quiet) and it is
+  // NEVER inferred from the idle value: 「最近 N 个即使空闲也保留」 and 「其余空闲多久收」 are two
+  // answers. Printing both with their sources is what turns 「为什么它被收了」 into one glance.
+  console.log(
+    `[agentus] warm slots: ${envWarm ?? agentSettings().warmSlots} kept up to ${
+      envWarmTtlMs != null ? envWarmTtlMs / 3_600_000 : agentSettings().warmTtlHours
+    } h untouched (${envWarm != null || envWarmTtlMs != null ? "AGENTUS_WARM_*" : "settings.agent"}), 0 = off / never`,
+  );
   mgr.startIdleReaper({
     idleMs: () => envIdleMs ?? agentSettings().idleKillMin * 60_000,
+    warmSlots: () => envWarm ?? agentSettings().warmSlots,
+    warmTtlMs: () => envWarmTtlMs ?? agentSettings().warmTtlHours * 3_600_000,
     watched: (id) => notify.operatorWatching(id),
     intervalMs: sweepMs,
   });
@@ -1385,9 +1404,42 @@ termWss.on("connection", (ws: WebSocket, _req: IncomingMessage, url: URL) => {
     return;
   }
   const session = term;
+  // ---- backpressure, half two: OUR OWN socket queue ---------------------------
+  // The page's watermarks (see ToolPanel's TerminalTab) can only count bytes that REACH it;
+  // everything still queued in this process is invisible from there. A slow page plus a fast
+  // producer therefore grows node's send queue without bound — measured on a `yes` flood: ~340 MB
+  // queued in seconds while the page only ever received ~106 frames/s. So the socket's own backlog
+  // is an independent brake, OR-ed with the client's request into one pause state, and the chain it
+  // walks back is the same one: stop reading the child -> the pty helper blocks in write(1) -> the
+  // shell blocks in write(2).
+  const NET_HIGH = 1 << 20; // 1 MiB queued -> stop draining the pty
+  const NET_LOW = 256 * 1024;
+  let clientPaused = false;
+  let socketPaused = false;
+  let paused = false;
+  const applyPause = (): void => {
+    const want = clientPaused || socketPaused;
+    if (want === paused) return;
+    paused = want;
+    if (want) session.pause();
+    else session.resume();
+  };
   const send = (msg: unknown): void => {
-    if (ws.readyState === WebSocket.OPEN) ws.send(JSON.stringify(msg));
+    if (ws.readyState !== WebSocket.OPEN) return;
+    ws.send(JSON.stringify(msg));
+    if (!socketPaused && ws.bufferedAmount >= NET_HIGH) {
+      socketPaused = true;
+      applyPause();
+    }
   };
+  // `ws` emits no drain event for its send queue, so the way back up is a cheap poll that only
+  // runs while we are actually holding the pty back.
+  const backlogTimer = setInterval(() => {
+    if (socketPaused && ws.bufferedAmount <= NET_LOW) {
+      socketPaused = false;
+      applyPause();
+    }
+  }, 100);
   // The buffered tail goes out first, so a reconnect (or a second tab) lands on the scrollback the
   // way ttyd's RESUME does instead of a blank screen.
   if (session.buffer) send({ t: "term-data", id: session.id, data: session.buffer });
@@ -1410,12 +1462,20 @@ termWss.on("connection", (ws: WebSocket, _req: IncomingMessage, url: URL) => {
       }
     } else if (cmd.t === "term-resize" && typeof cmd.cols === "number" && typeof cmd.rows === "number") {
       session.resize(cmd.cols, cmd.rows);
+    } else if (cmd.t === "term-pause") {
+      // The page's emulator fell behind: hold the pty so the backlog cannot grow there instead.
+      clientPaused = true;
+      applyPause();
+    } else if (cmd.t === "term-resume") {
+      clientPaused = false;
+      applyPause();
     } else if (cmd.t === "term-close") {
       terms.kill(session.id);
       ws.close();
     }
   });
   const cleanup = (): void => {
+    clearInterval(backlogTimer);
     session.subscribers.delete(onData);
     terms.kill(session.id);
   };

package/packages/server/src/notify/center.ts

@@ -41,6 +41,10 @@ export interface NotifyCenterOptions {
   sessionTitle?: (sessionId: string) => string | null;
   /** The companion APK, so the web panel can report its size (optional). */
   apkPath?: string;
+  /** Called when the cockpit reports WHICH session it is showing (the presence route) — the one
+   *  signal that says "the operator is using this slot right now". The idle reaper needs it: a
+   *  message clock alone reaped slots nobody had written to (see SessionManager.touch). */
+  onFocus?: (sessionId: string) => void;
   log?: (line: string) => void;
 }
 
@@ -137,6 +141,8 @@ export class NotifyCenter {
   private readonly sessionTitle: ((sessionId: string) => string | null) | null;
   /** The APK the phone installs (optional): the web panel reports its size from here. */
   private readonly apkPath: string | null = null;
+  /** "The operator is on this session right now" — the idle reaper's use-activity clock. */
+  private readonly onFocus: ((sessionId: string) => void) | null = null;
 
   private state: NotifyState;
   private events: ActivityRecord[] = [];
@@ -176,6 +182,14 @@ export class NotifyCenter {
       call: Boolean(call),
       at: Date.now(),
     };
+    // The idle reaper's "he was just here" half. Only while the page says it is VISIBLE (or on a
+    // call): a tab left open on a session in the background must not keep an agent process alive
+    // forever, and `visible` is the page's own answer to "is anyone looking". A call counts for the
+    // same reason it counts as watching — the hands are free, the screen is not touched, and the
+    // session IS the conversation.
+    if (this.presence.sessionId && (this.presence.visible || this.presence.call)) {
+      this.onFocus?.(this.presence.sessionId);
+    }
     return this.presence;
   }
 
@@ -228,6 +242,7 @@ export class NotifyCenter {
     this.credentials = opts.credentials ?? null;
     this.sessionTitle = opts.sessionTitle ?? null;
     this.apkPath = opts.apkPath ?? null;
+    this.onFocus = opts.onFocus ?? null;
     this.state = this.loadState();
     this.events = this.loadEvents();
   }

package/packages/server/src/pty-helper.py

@@ -18,6 +18,15 @@ Wire format, all raw bytes:
                       stripping: a terminal emulator consumes the escape sequences, a <pre> cannot)
     fd 3           <- control channel, one command per line: "resize <cols> <rows>"
 
+**Never block on stdout.** stdout is a pipe into the server, and the server stops reading it on
+purpose when a consumer falls behind (see the flow-control notes in term.ts / index.ts: the brake is
+applied by pausing this process's stdout). A blocking `write(1)` would stop this loop dead — and this
+loop is also what forwards the keyboard, so a slow page would take Ctrl-C down with it and the
+operator would have nothing left to abort the flood with. So stdout is NON-BLOCKING, output
+accumulates in a local buffer, and reading the PTY is suspended while that buffer is at its cap: the
+backpressure travels back to the producing program instead of parking in here. The input path is
+never gated by output.
+
 Sizing: the initial size comes from AGENTUS_PTY_COLS / AGENTUS_PTY_ROWS, and `resize` applies
 TIOCSWINSZ to the master — the kernel then signals the child's foreground process group (SIGWINCH),
 which is what makes vim redraw at the new width.
@@ -36,6 +45,10 @@ import sys
 import termios
 
 CTL_FD = 3
+READ_CHUNK = 65536
+# Stop reading the PTY once this much output is waiting to go out: the producing program then blocks
+# in its own write(2), which is the backpressure we want and what keeps this buffer bounded.
+OUT_CAP = 1 << 20
 
 
 def set_winsize(fd: int, cols: int, rows: int) -> None:
@@ -70,35 +83,72 @@ def main() -> int:
         ctl = None  # no control channel: a fixed-size terminal is still a terminal
 
     stdin_fd = 0
-    running = True
-    while running:
-        watch = [master, stdin_fd] + ([CTL_FD] if ctl else [])
+    # Non-blocking stdout: the server stops reading it on purpose (flow control), and blocking here
+    # would freeze the input path with it.
+    try:
+        os.set_blocking(1, False)
+    except (OSError, AttributeError):
+        pass  # no os.set_blocking: the writes below fall back to blocking behaviour
+    pending = bytearray()
+    stdin_open = True
+    while True:
+        # While we are behind on output we stop reading the PTY — that IS the backpressure. stdin and
+        # the control channel stay watched, so a keystroke (Ctrl-C above all) is never stuck behind
+        # a flood.
+        readable = [stdin_fd] if stdin_open else []
+        if ctl is not None:
+            readable.append(CTL_FD)
+        if len(pending) < OUT_CAP:
+            readable.append(master)
+        writable = [1] if pending else []
         try:
-            ready, _, _ = select.select(watch, [], [])
+            ready_r, ready_w, _ = select.select(readable, writable, [])
         except OSError as exc:
             if exc.errno == errno.EINTR:
                 continue
             break
 
-        if master in ready:
+        if ready_w and pending:
+            try:
+                written = os.write(1, pending)
+                del pending[:written]
+            except (BlockingIOError, InterruptedError):
+                pass
+            except OSError:
+                break  # stdout is gone: the server died, so are we
+
+        if master in ready_r:
             try:
-                data = os.read(master, 65536)
+                data = os.read(master, READ_CHUNK)
+            except (BlockingIOError, InterruptedError):
+                data = None
             except OSError:
                 data = b""
-            if not data:
+            if data == b"":
                 break  # the child closed the pty: it is gone
-            os.write(1, data)
+            if data:
+                pending += data
 
-        if stdin_fd in ready:
+        if stdin_open and stdin_fd in ready_r:
             try:
-                data = os.read(stdin_fd, 65536)
+                data = os.read(stdin_fd, READ_CHUNK)
+            except (BlockingIOError, InterruptedError):
+                data = None
             except OSError:
                 data = b""
-            if not data:
-                break  # EOF: the browser went away, take the shell with us
-            os.write(master, data)
-
-        if ctl and CTL_FD in ready:
+            if data == b"":
+                # EOF: the browser went away. Let the child finish its exit path rather than
+                # dropping output we still owe the scrollback.
+                stdin_open = False
+                if ctl is None:
+                    break
+            elif data:
+                try:
+                    os.write(master, data)
+                except OSError:
+                    break
+
+        if ctl is not None and CTL_FD in ready_r:
             line = ctl.readline()
             if line == "":
                 ctl.close()
@@ -108,6 +158,14 @@ def main() -> int:
             if parts and parts[0] == "resize" and len(parts) == 3 and parts[1].isdigit() and parts[2].isdigit():
                 set_winsize(master, int(parts[1]), int(parts[2]))
 
+    # Best effort: hand over whatever is left, but never hang on it.
+    try:
+        while pending:
+            written = os.write(1, pending)
+            del pending[:written]
+    except OSError:
+        pass
+
     # Reap the child, then leave with its status so the server can report a real exit code.
     status = 0
     try:

package/packages/server/src/settings.ts

@@ -124,13 +124,28 @@ export interface AgentSettings {
   /** minutes of no activity before a live slot's agent process is stopped to reclaim memory;
    *  0 = never. The row and its transcript always survive — this only stops the process. */
   idleKillMin: number;
+  /** 「热备」= how many of the most recently USED sessions keep their agent process no matter how
+   *  quiet they go. A FLOOR, not a ceiling: it names the slots that may not be reclaimed for being
+   *  idle, it does not bound how many may run. Ranked over live AND cold rows by the same clock the
+   *  sweep uses — a slot already reaped must not hand its seat to a session nobody has touched in
+   *  days. Archived rows never occupy a seat. 0 = off (every slot obeys idleKillMin). */
+  warmSlots: number;
+  /** Hours a warm slot may go untouched before even its exemption expires. Without this the warm set
+   *  is a permanent memory floor (5 × ~137 MB RSS measured); with it, a cockpit left alone for a day
+   *  comes back to nothing running. 0 = 不过期. */
+  warmTtlHours: number;
 }
 
-export const AGENT_DEFAULT: AgentSettings = { idleKillMin: 5 };
+export const AGENT_DEFAULT: AgentSettings = { idleKillMin: 5, warmSlots: 5, warmTtlHours: 24 };
 
 /** What the settings page may offer: the ends of the number field. Server-side enforcement uses
  *  the same pair, so a hand-written request cannot store a nonsense value. */
 export const AGENT_IDLE_RANGE: [number, number] = [0, 60];
+/** 0 = off. The upper end is a memory decision (one live agent ≈ 137 MB RSS measured), not a limit
+ *  the server has to defend. */
+export const AGENT_WARM_RANGE: [number, number] = [0, 20];
+/** 0 = 不过期; a week is the longest span worth offering on the page. */
+export const AGENT_WARM_TTL_RANGE: [number, number] = [0, 168];
 
 /** The NUMERIC knobs. `interruptMode` is a two-way choice, not a slider, so it is deliberately
  *  outside both the range table and the loops that validate numbers. */
@@ -293,9 +308,15 @@ function pickCall(raw: unknown): CallSettings {
 function pickAgent(raw: unknown): AgentSettings {
   const out = { ...AGENT_DEFAULT };
   if (raw && typeof raw === "object") {
-    const v = Number((raw as Record<string, unknown>).idleKillMin);
-    const [lo, hi] = AGENT_IDLE_RANGE;
-    if (Number.isFinite(v) && v >= lo && v <= hi) out.idleKillMin = v;
+    const r = raw as Record<string, unknown>;
+    const take = (key: keyof AgentSettings, range: [number, number]): void => {
+      const v = Number(r[key]);
+      const [lo, hi] = range;
+      if (Number.isFinite(v) && v >= lo && v <= hi) out[key] = v;
+    };
+    take("idleKillMin", AGENT_IDLE_RANGE);
+    take("warmSlots", AGENT_WARM_RANGE);
+    take("warmTtlHours", AGENT_WARM_TTL_RANGE);
   }
   return out;
 }
@@ -369,6 +390,8 @@ export function publicSettings(): Record<string, unknown> {
     agent: cache.agent,
     agentDefaults: AGENT_DEFAULT,
     agentIdleRange: AGENT_IDLE_RANGE,
+    agentWarmRange: AGENT_WARM_RANGE,
+    agentWarmTtlRange: AGENT_WARM_TTL_RANGE,
     // the defaults, so the UI can offer "reset to Bailian defaults"
     defaults: { ...DEFAULTS, apiKey: undefined, baseUrl: undefined },
     updatedAt: cache.updatedAt,
@@ -495,18 +518,23 @@ export function savePrefs(patch: Record<string, unknown>): Settings {
 }
 
 /** Agent-process knobs: its own update, like theme/call, so a bad number here cannot lock the
- *  operator out of the page that would fix it. Range-checked against AGENT_IDLE_RANGE before it is
- *  stored — this number decides whether agent processes get killed, so it is not a text field. */
+ *  operator out of the page that would fix it. Range-checked against the section's range table
+ *  before it is stored — these numbers decide whether agent processes get killed, so they are not
+ *  text fields. */
 export function saveAgent(patch: Record<string, unknown>): Settings {
   const a = { ...cache.agent };
-  if ("idleKillMin" in patch) {
-    const raw = typeof patch.idleKillMin === "number" ? patch.idleKillMin : Number(patch.idleKillMin);
-    const [lo, hi] = AGENT_IDLE_RANGE;
+  const set = (key: keyof AgentSettings, range: [number, number], unit: string, off: string): void => {
+    if (!(key in patch)) return;
+    const raw = typeof patch[key] === "number" ? (patch[key] as number) : Number(patch[key]);
+    const [lo, hi] = range;
     if (!Number.isFinite(raw) || raw < lo || raw > hi) {
-      throw new Error(`invalid idleKillMin: ${JSON.stringify(patch.idleKillMin)} (expected ${lo}…${hi} minutes, 0 = off)`);
+      throw new Error(`invalid ${key}: ${JSON.stringify(patch[key])} (expected ${lo}…${hi} ${unit}, ${off})`);
     }
-    a.idleKillMin = raw;
-  }
+    a[key] = raw;
+  };
+  set("idleKillMin", AGENT_IDLE_RANGE, "minutes", "0 = off");
+  set("warmSlots", AGENT_WARM_RANGE, "slots", "0 = off");
+  set("warmTtlHours", AGENT_WARM_TTL_RANGE, "hours", "0 = never expires");
   cache = { ...cache, agent: a, updatedAt: Date.now() };
   persist();
   return cache;

package/packages/server/src/term.ts

@@ -40,9 +40,19 @@ export interface TermSession {
   /** Resize the tty (no-op on a pipe shell). The kernel then SIGWINCHes the child's foreground
    *  process group, which is what makes a full-screen program redraw at the new width. */
   resize: (cols: number, rows: number) => void;
+  /** Stop draining the child's output. The backpressure chain is: this pause -> we stop reading
+   *  the child's stdout -> the pty helper blocks in its own write(1) -> it stops reading the pty
+   *  master -> the shell/program blocks in write(2). That is the ONLY honest way to slow a fast
+   *  producer (xterm's own guidance: without it the emulator grows a write buffer until it is
+   *  unresponsive — see the flow-control note in ToolPanel's TerminalTab). */
+  pause: () => void;
+  resume: () => void;
 }
 
 const MAX_BUFFER = 256 * 1024;
+/** How long output is held to be coalesced, and the size that makes holding it pointless. */
+const FLUSH_MS = 8;
+const FLUSH_BYTES = 64 * 1024;
 
 /** The PTY helper that ships with the server. */
 function ptyHelperPath(): string | null {
@@ -135,9 +145,34 @@ export class TermService {
           /* the helper is gone; the exit event says so */
         }
       },
+      pause: (): void => {
+        child.stdout?.pause();
+        child.stderr?.pause();
+      },
+      resume: (): void => {
+        child.stdout?.resume();
+        child.stderr?.resume();
+      },
     };
-    const push = (chunk: string): void => {
-      session.buffer = (session.buffer + chunk).slice(-MAX_BUFFER);
+    // ---- output framing --------------------------------------------------------
+    // One `data` event per write(2) is what a pty hands us, and a full-screen program repainting
+    // (or `yes`) emits hundreds of them per second. Every one used to become its own WebSocket
+    // frame, and the browser then spends more time in message callbacks than in the emulator
+    // (upstream measured ~70% of the main thread: ttyd#247). Subscribers therefore get COALESCED
+    // frames — whatever lands inside one ~FLUSH_MS window ships as a single message.
+    //
+    // The scrollback buffer is deliberately NOT batched: a late joiner or a reconnect has to see
+    // every byte, and appending to a string costs nothing per frame.
+    let pending = "";
+    let flushTimer: NodeJS.Timeout | null = null;
+    const flush = (): void => {
+      if (flushTimer) {
+        clearTimeout(flushTimer);
+        flushTimer = null;
+      }
+      if (!pending) return;
+      const chunk = pending;
+      pending = "";
       for (const fn of session.subscribers) {
         try {
           fn(chunk);
@@ -146,6 +181,13 @@ export class TermService {
         }
       }
     };
+    const push = (chunk: string): void => {
+      session.buffer = (session.buffer + chunk).slice(-MAX_BUFFER);
+      pending += chunk;
+      // Past this size, holding it any longer only delays a redraw.
+      if (pending.length >= FLUSH_BYTES) flush();
+      else if (!flushTimer) flushTimer = setTimeout(flush, FLUSH_MS);
+    };
     child.stdout?.setEncoding("utf8");
     child.stderr?.setEncoding("utf8");
     // stderr is part of the terminal picture (a missing command prints there). With a pty both
@@ -155,6 +197,8 @@ export class TermService {
     child.on("exit", (code: number | null, signal: string | null) => {
       session.exited = { code, signal };
       push(`\r\n[process exited${code != null ? ` with code ${code}` : ""}${signal ? ` (${signal})` : ""}]\r\n`);
+      // The exit line must not wait out the coalescing window — nothing follows it.
+      flush();
       this.#sessions.delete(session.id);
     });
     child.on("error", (err: Error) => push(`\r\n[cannot start shell: ${err.message}]\r\n`));