agentus 0.3.2 → 0.3.3

package/docs/dev/03-release.md

@@ -195,6 +195,19 @@ git branch --set-upstream-to=origin/main main
 Judge the outcome by identity, not by "the push succeeded": `git ls-remote origin
 refs/heads/main` must equal the commit live is actually serving.
 
+> **Do not merge into the live tree before promoting.** `promote` decides whether to restart by
+> diffing **the live tree's old tip** against the commit it is promoting. If the live tree already
+> sits on that commit (e.g. someone ran `git merge --ff-only <dev-branch>` inside
+> `worktrees/agentus`), the diff is empty: promote prints `no server-side change`, ships the new web
+> bundle, and **leaves the old server process running** — a half release that looks green. Restart
+> detection is only as good as the tree it reads, so move `main` through the ref (`git push
+> origin <dev-branch>:main`), never by checking it out in the live worktree.
+>
+> If it already happened: the release is not done. Re-run the restart explicitly
+> (`scripts/relaunch.sh --port <live> --tree <live tree> --launcher <launcher> --launchd <label>`)
+> and then resume the slots promote captured, exactly as promote's step 6 would have. Prove it by
+> the startup log line for the new feature, not by the pid alone.
+
 ## Rollback
 
 The release path has no separate rollback mechanism — you revert the change and promote

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "agentus",
- "version": "0.3.2",
+ "version": "0.3.3",
  "description": "Multi-session web cockpit for ACP-speaking coding agents (Qoder CLI / Hermes). UI has no intelligence — the agent lives in spawned CLI subprocesses.",
  "license": "Apache-2.0",
  "repository": {
@@ -64,12 +64,12 @@
   "store-fold": "tsx scripts/qa/store-fold.mts",
   "live-stream": "tsx scripts/qa/live-stream.mts",
   "open-target": "tsx scripts/qa/open-target.mts",
- "rail-recent": "tsx scripts/qa/rail-recent.mts",
- "turn-pulse": "tsx scripts/qa/turn-pulse.mts",
- "resume-tail": "tsx scripts/qa/resume-tail.mts",
- "render-lag-sweep": "node scripts/qa/render-lag-sweep.mjs",
- "replay-window": "node scripts/qa/replay-window.mjs",
- "think-cadence": "node scripts/qa/think-cadence.mjs"
+  "rail-recent": "tsx scripts/qa/rail-recent.mts",
+  "turn-pulse": "tsx scripts/qa/turn-pulse.mts",
+  "resume-tail": "tsx scripts/qa/resume-tail.mts",
+  "render-lag-sweep": "node scripts/qa/render-lag-sweep.mjs",
+  "replay-window": "node scripts/qa/replay-window.mjs",
+  "think-cadence": "node scripts/qa/think-cadence.mjs"
  },
  "engines": {
   "node": ">=22.5"

package/packages/server/mock/agent.mjs

@@ -7,6 +7,10 @@
 //   MOCK_TOOL=1        -> prompt triggers a tool_call + requestPermission
 //   MOCK_THINK=1       -> emits agent_thought_chunk before the answer
 //   MOCK_SLOW_MS=n     -> delay between chunks (default 60)
+//   MOCK_SPAWN_MS=n    -> boot latency before the handshake answers (default 0). A real agent takes
+//                         seconds to come up (node + initialize + session/load) and that window is
+//                         where the cockpit's 「正在唤醒 agent 进程…」 state lives — a browser sweep
+//                         cannot observe a state that lasts 80 ms.
 //   MOCK_SINK=1        -> exit the process mid-turn (crash path for AC5/QA)
 import { randomUUID } from "node:crypto";
 import fs from "node:fs";
@@ -14,6 +18,10 @@ import { AgentSideConnection, RequestError, ndJsonStream } from "@agentclientpro
 import { Readable, Transform, Writable } from "node:stream";
 
 const SLOW = Number(process.env.MOCK_SLOW_MS || 60);
+/** Boot latency — deliberately BEFORE the stream is wired, so the slot sits in `starting` for as
+ *  long as QA asks. Defaults to 0: the mock is instant unless a sweep needs the wake window. */
+const SPAWN_MS = Number(process.env.MOCK_SPAWN_MS || 0);
+if (SPAWN_MS > 0) await new Promise((r) => setTimeout(r, SPAWN_MS));
 
 // The file a `[tool-diff]` turn pretends to edit: hermes hands the cockpit the whole file
 // before and after, so the approval surface has a path and a real change to show.

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

@@ -1276,7 +1276,34 @@ export class SessionManager {
     live.touchedAt = Date.now();
   }
 
-  /** Reclaim idle slots: stop the agent process of a session nobody has touched for the operator's
+  /** 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
@@ -1284,12 +1311,39 @@ 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()]) {
@@ -1303,10 +1357,20 @@ export class SessionManager {
         // 「刚点进去、没发消息、换个会话过一分钟 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);
-        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)`,
-        );
+        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

@@ -270,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";
@@ -278,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,
   });

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;