agentus 0.4.2 → 0.4.3

package/README.md

@@ -50,11 +50,12 @@ logs in — you just have no backend to start a session on.
 
 A plain Hermes install drives sessions; the cockpit's own extras — per-session **thinking
 depth**, a permission mode that survives a restart, the **context-budget** field, the **status
-channel** (memory recall/save hints in the message stream), per-process skill roots, and a
+channel** (memory recall/save hints in the message stream), per-process skill roots, **background-job
+completion wake-ups** (a finished background process comes back as a turn of its own), and a
 **DeepSeek web backend** (search + extract on the model key) — come from the fork's integration
 build instead. That is a five-line install:
 [§ Which Hermes to run](docs/installation.md#which-hermes-to-run) — currently the tag
-`agentus/v0.22.0/merge-20261018-1005`, on Hermes `v0.22.0`.
+`agentus/v0.22.0/merge-20261018-1617`, on Hermes `v0.22.0`.
 
 The first slot you start will use the Hermes home **your own agent already uses**
 (`~/.hermes`) unless the backend row names another one — see "HERMES_HOME" below.

package/README.zh-CN.md

@@ -44,11 +44,12 @@ web bundle、配套 APK —— 然后直接退出，不启动任何东西）。
 照样能跑、照样能登录 —— 只是没有后端可以开会话。
 
 裸装的 Hermes 就能跑会话；驾驶舱自己的那几项能力 —— 按会话切换的**思考深度**、跨重启存活的**权限模式**、
-**上下文预算**输入框、把记忆召回 / 存记忆提示送进消息流的 **status 通道**、按进程指定的技能根，
+**上下文预算**输入框、把记忆召回 / 存记忆提示送进消息流的 **status 通道**、按进程指定的技能根、
+**后台任务完成唤醒**（后台进程跑完会自己开一个回合回来），
 以及 **DeepSeek 的 web 后端**（搜索 + 正文抓取，共用模型 key）—— 来自 fork 的集成构建（tag）。
 装法就五行：
 [§ 该跑哪份 Hermes](docs/installation.zh-CN.md#该跑哪份-hermes) —— 当前是 tag
-`agentus/v0.22.0/merge-20261018-1005`，基座 Hermes `v0.22.0`。
+`agentus/v0.22.0/merge-20261018-1617`，基座 Hermes `v0.22.0`。
 
 你启动的第一个 slot 会使用**你自己的 agent 已经在用的**那个 Hermes home（`~/.hermes`），除非后端那一行
 指定了另一个 —— 见下面的「HERMES_HOME」。

package/docs/installation.md

@@ -37,7 +37,9 @@ in the released build — a per-session **thinking depth** (ACP `reasoning_effor
 mode that survives a restart** and `session/load`, a free-form **context budget** (with
 256K/512K/768K/1M presets), the **status channel** that carries memory-recall / save hints into the
 cockpit's message stream, **per-process skill roots** (`HERMES_EXTERNAL_SKILLS_DIRS`, which is how a
-slot sees the cockpit's own skill without anything being written into your `~/.hermes`), and a
+slot sees the cockpit's own skill without anything being written into your `~/.hermes`),
+**background-job completion wake-ups** (a finished `terminal(background=true)` job is relayed back as
+a turn of its own, so the agent resumes instead of the turn simply ending), and a
 **DeepSeek web backend** (`search` + `extract` on top of `DEEPSEEK_API_KEY` — DeepSeek has no separate
 search key).
 They live on the ACP branches of the fork
@@ -53,7 +55,7 @@ ref and gets rebuilt, while a tag never moves — so pin the tag. The `agentus/`
 ours apart from upstream's own tags (`v0.22.0`, `v0.22.0+canary.*`), and the timestamp in the
 last segment sorts, so "newest" is a `sort -V`.
 
-**Current integration build: `agentus/v0.22.0/merge-20261018-1005`** — the newest tag on the fork,
+**Current integration build: `agentus/v0.22.0/merge-20261018-1617`** — the newest tag on the fork,
 built on Hermes `v0.22.0`. This line is for orientation only, not the source of truth: the
 `TAG=$(…)` step below resolves the newest one on every run, so read it there if this sentence
 ever looks stale.

package/docs/installation.zh-CN.md

@@ -34,7 +34,9 @@ brew install node                 # 或者 https://nodejs.org/en/download
 （ACP `reasoning_effort`）、**跨重启 / `session/load` 存活的权限模式**、可自由填写的**上下文预算**
 （带 256K/512K/768K/1M 预设）、把记忆召回 / 存记忆提示送进驾驶舱消息流的 **status 通道**，以及
 **按进程指定的技能根**（`HERMES_EXTERNAL_SKILLS_DIRS` —— 驾驶舱靠它让槽位看见自己的 skill，
-不往你的 `~/.hermes` 写任何东西），以及 **DeepSeek 的 web 后端**（`search` + `extract` 都复用
+不往你的 `~/.hermes` 写任何东西）、**后台任务完成唤醒**（`terminal(background=true)` 的进程跑完会被
+中继成一个新回合，agent 自己接着干，而不是回合就这么结束），以及 **DeepSeek 的 web 后端**
+（`search` + `extract` 都复用
 `DEEPSEEK_API_KEY` —— DeepSeek 没有单独的搜索密钥）。它们在 fork
 [`LiangYang666/hermes-agent`](https://github.com/LiangYang666/hermes-agent) 的 ACP 分支上，
 按基座版本各有一个**集成构建的 tag**，自成命名空间：
@@ -47,7 +49,7 @@ agentus/<hermes 内部版本>/merge-<YYYYMMDD-HHMM>
 tag。`agentus/` 这个前缀也把它和上游自己的 tag（`v0.22.0`、`v0.22.0+canary.*`）分开；最后一段是时间戳，
 可排序，所以「最新」就是一次 `sort -V`。
 
-**当前集成构建：`agentus/v0.22.0/merge-20261018-1005`** —— fork 上最新的那个 tag，基座 Hermes
+**当前集成构建：`agentus/v0.22.0/merge-20261018-1617`** —— fork 上最新的那个 tag，基座 Hermes
 `v0.22.0`。这行只为一眼看个大概，不是权威：下面的 `TAG=$(…)` 每次都会自己解析出最新，觉得这行过期就
 以它为准。
 

package/package.json

@@ -1,6 +1,6 @@
 {
  "name": "agentus",
- "version": "0.4.2",
+ "version": "0.4.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": {

package/packages/server/mock/agent.mjs

@@ -443,6 +443,45 @@ const agent = () => ({
       }, Math.min(slow * 2, 1000));
     }
 
+    // `[bg]` — a background process that outlives the turn (issue #22), in the three frames the fork's
+    // `acp_adapter/background.py` sends: a running snapshot, then the completion carrier, then the
+    // snapshot that clears the row. Deliberately AFTER the turn: that is the shape that matters — the
+    // session reads ready while the work continues, and the completion has to wake a new turn.
+    if (/\[bg\]|\[bg:\d+\]/.test(text)) {
+      // `[bg:<seconds>]` holds the row RUNNING that long, which is what the idle-reaper sweep needs: a
+      // task still running when the reap clock runs out (scripts/qa/reap-vs-background.mjs). `[bg]`
+      // alone keeps the original 1.4 s shape the wake sweeps are built on.
+      const hold = Number((/\[bg:(\d+)\]/.exec(text) || [])[1] || 0);
+      const runMs = hold ? hold * 1000 : 1400;
+      const taskId = `bg-${sessionId}-1`;
+      const snapshot = (rows) => ({
+        sessionUpdate: "agent_thought_chunk",
+        _meta: { hermes: { kind: "background", tasks: rows } },
+        content: { type: "text", text: "" },
+      });
+      const running = [{
+        id: taskId, command: "npm run build --workspace packages/web", pid: 4242,
+        status: "running", uptimeSeconds: 12,
+      }];
+      void send(agent._conn, sessionId, snapshot(running)).catch(() => undefined);
+      setTimeout(() => {
+        void send(agent._conn, sessionId, {
+          sessionUpdate: "agent_thought_chunk",
+          _meta: { hermes: {
+            kind: "completion",
+            text: "后台进程已结束（exit 0）：npm run build --workspace packages/web",
+            exitCode: 0,
+            processId: taskId,
+            command: "npm run build --workspace packages/web",
+          } },
+          content: { type: "text", text: "" },
+        }).catch(() => undefined);
+      }, runMs);
+      setTimeout(() => {
+        void send(agent._conn, sessionId, snapshot([])).catch(() => undefined);
+      }, runMs + 1200);
+    }
+
     // `[table]` — a table fixture for the sorting / full-screen sweep (scripts/qa/table-sweep.mjs).
     // Numeric AND text cells, deliberately NOT in any sorted order, and a local file link plus a
     // relative image, so "clicking a header reorders the rows" and "a relative path resolves" are

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

@@ -24,6 +24,7 @@ import type { Store, SessionRow, TitleSrc } from "../store/store.js";
 import { textOf, withText } from "../store/store.js";
 import type {
   AttachmentSummary,
+  BackgroundTask,
   BackendId,
   ConfigOptionView,
   PermissionDecision,
@@ -234,6 +235,15 @@ interface LiveSession {
   /** One log line per agent process the first time a frame is ignored, so a reader of the log can
    *  tell "the cockpit is dropping these on purpose" from "the agent stopped emitting them". */
   planFramesDropped?: boolean;
+  /** Latest background-process snapshot from the agent (issue #22): what is still running once the
+   *  turn is over. Transient STATE, never a transcript row — 「2 个后台任务在跑」 is true now and false in
+   *  five minutes, and a stored row would hang a dead process under a conversation from last month. */
+  background: BackgroundTask[];
+  /** Completion sentences that arrived while the turn was BUSY (#22), in order. Held rather than
+   *  dropped: the agent is the intended reader, and a completion lost to bad timing means work the
+   *  operator has to notice and redo by hand. Drained one at a time at turn-end — each opens its own
+   *  turn, and two at once is a race the agent cannot mediate. */
+  pendingCompletions: string[];
 }
 
 type Emitter = (evt: ServerEvent) => void;
@@ -246,12 +256,22 @@ export class SessionManager {
    *  the idle thresholds, because the requirement is that a change in 设置 applies to the very next
    *  turn with no restart and no session to hibernate. */
   #planHint: () => PlanHintSettings = () => ({ ...PREFS_DEFAULT.planHint });
+  /** Whether a finished background process may open a turn by itself (issue #22). A getter, not a
+   *  value: the operator's switch must apply to the next completion, with no restart and no session
+   *  to hibernate. Default ON — this is the CLI/gateway behaviour, and the whole point is that the
+   *  agent takes its own result instead of the operator noticing a stale screen. */
+  #completionWake: () => boolean = () => true;
 
   constructor(store: Store, emit: Emitter) {
     this.#store = store;
     this.#emit = emit;
   }
 
+  /** Wire the operator's 「后台任务完成唤醒」 switch in (index.ts → settings.agent.completionWake). */
+  setCompletionWakeSource(fn: () => boolean): void {
+    this.#completionWake = typeof fn === "function" ? fn : () => true;
+  }
+
   /** Wire the cockpit's plan-hint setting in. Optional on purpose: with no source wired the
    *  manager behaves exactly as it did before the setting existed (on, 仅首条). */
   setPlanHintSource(read: () => PlanHintSettings): void {
@@ -482,6 +502,7 @@ export class SessionManager {
         createdAt: now, modes: null, configOptions: [], commands: [],
       },
       child, busy: false, pendingPermissions: new Map(), alwaysAllow: new Set(), stderrBuf: [],
+      background: [], pendingCompletions: [],
       caps: { fork: false, load: false, image: false }, turnSeq: 0, collectors: new Map(), planReminderPending: true,
       planToken: randomUUID(),
       cockpitToken,
@@ -666,6 +687,7 @@ export class SessionManager {
         commands: normCommands(row.commands),
       },
       child, busy: false, pendingPermissions: new Map(), alwaysAllow: new Set(), stderrBuf: [],
+      background: [], pendingCompletions: [],
       caps: { fork: false, load: false, image: false }, turnSeq: 0, collectors: new Map(), planReminderPending: true,
       planToken: randomUUID(),
       cockpitToken,
@@ -1054,7 +1076,52 @@ export class SessionManager {
         s.info.status = "ready";
         this.#updateSession(s);
       }
+      // A completion that arrived mid-turn was held, not dropped (#22). Hand the first one back now —
+      // scheduled rather than awaited so this prompt's own teardown finishes first, and only one at a
+      // time because each opens its own turn.
+      this.#drainHeldCompletion(s);
+    }
+  }
+
+  /** Wake the agent for one finished background process, or hold it until the turn ends.
+   *
+   *  The gateway does exactly this (``_inject_watch_notification``): the completion is *for the agent* —
+   *  its own tool text says "you will be notified on exit — do more work instead of waiting" — so the
+   *  cockpit's job is to deliver it as a turn, not to decorate a screen. Two refusals are deliberate:
+   *  with the operator's switch off we say so in the log and drop it (that is the switch's meaning), and
+   *  while a turn is running we hold it, because a prompt would otherwise interrupt work the operator
+   *  started. */
+  #queueOrWakeCompletion(s: LiveSession, text: string): void {
+    if (!text) return;
+    if (!this.#completionWake()) {
+      console.log(`[agentus] background completion dropped for ${s.info.id}: 唤醒关闭`);
+      return;
+    }
+    if (s.busy) {
+      s.pendingCompletions.push(text);
+      return;
     }
+    void this.#wakeWithCompletion(s, text);
+  }
+
+  async #wakeWithCompletion(s: LiveSession, text: string): Promise<void> {
+    try {
+      // `origin` so the page labels the bubble as a background notice instead of presenting it as
+      // something the operator typed — the same mechanism the cockpit's cross-session `send` uses.
+      await this.prompt(s.info.id, text, [], { origin: { sessionId: "background", title: "后台任务完成" } });
+    } catch (err) {
+      // Lost a race for the floor (an operator prompt landed first): keep it for the next turn end
+      // instead of throwing away the agent's own result.
+      s.pendingCompletions.unshift(text);
+      console.log(`[agentus] completion held for ${s.info.id}: ${errMessage(err)}`);
+    }
+  }
+
+  #drainHeldCompletion(s: LiveSession): void {
+    if (!s.pendingCompletions.length || s.busy) return;
+    const next = s.pendingCompletions.shift();
+    if (!next) return;
+    setTimeout(() => void this.#wakeWithCompletion(s, next), 0).unref?.();
   }
 
   async cancel(sessionId: string): Promise<void> {
@@ -1646,6 +1713,14 @@ export class SessionManager {
         if (s.busy || s.pendingPermissions.size) continue;
         if (s.info.status === "starting" || s.info.status === "running") continue;
         if (opts.watched?.(s.info.id)) continue;
+        // A session whose agent still OWNS A RUNNING BACKGROUND PROCESS is not idle, whatever the clock
+        // says. Reaping it would SIGTERM the only process that can report that result (`#stop` kills the
+        // agent, not the process group), so the child would be left orphaned and unread — the exact
+        // silent failure #22 exists to remove: 「会话看起来结束了，活儿其实还在跑」. Reported by the
+        // operator as a question (2026-10-18: 「有后台进程的话，它还会被空闲回收吗？」) — it could.
+        // It is still bounded: only the long warm deadline (`warmTtlMs`) may reclaim it, so a runaway
+        // process cannot pin a slot forever.
+        const hasBackground = s.background.some((t) => t.status === "running");
         // 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
@@ -1661,6 +1736,13 @@ export class SessionManager {
           console.log(
             `[agentus] warm slot expired: ${s.info.id} (${fmt(age)} untouched, warm ttl ${fmt(warmTtlMs)})`,
           );
+        } else if (hasBackground) {
+          // Idle time is not the whole question: the agent still OWNS a running child, so the short
+          // clock does not apply — only the long deadline can reclaim it.
+          if (!(warmTtlMs > 0) || age < warmTtlMs) continue;
+          console.log(
+            `[agentus] idle reap: ${s.info.id} (background task still running after ${fmt(age)}, hard limit ${fmt(warmTtlMs)})`,
+          );
         } else {
           if (!(idleMs > 0) || age < idleMs) continue;
           console.log(
@@ -1684,6 +1766,18 @@ export class SessionManager {
 
   /** The list every client needs to be current: the rows PLUS what is already waiting for an
    *  answer. Sent on connect too, which is what makes a refreshed page show a live approval. */
+  /** Every live session's current background snapshot (issue #22), for a page that connects AFTER the
+   *  frame that carried it.
+   *
+   *  EMPTY ONES ARE INCLUDED (`tasks: []`), and that is not noise: the page clears a row when a session
+   *  is absent from this list AND treats a present-but-empty one as 「nothing running」. Omitting empties
+   *  made the two cases indistinguishable — every `sessions` frame (which is emitted for unrelated
+   *  reasons, e.g. a title change) then wiped a row the page had just drawn from a `background` frame.
+   *  An explicit `[]` is the same discipline the three rail buckets use. */
+  backgroundSnapshots(): { sessionId: string; tasks: BackgroundTask[] }[] {
+    return [...this.#sessions.values()].map((s) => ({ sessionId: s.info.id, tasks: s.background }));
+  }
+
   #emitSessions(): void {
     // ALL THREE buckets, every time. This is the SAME event the HTTP path builds (`sessionsEvent()`
     // in index.ts), and the client replaces its lists wholesale from whatever arrives — so emitting
@@ -1697,6 +1791,7 @@ export class SessionManager {
       cold: this.cold(),
       archived: this.archived(),
       pending: this.pendingPermissions(),
+      background: this.backgroundSnapshots(),
     });
   }
 
@@ -1775,6 +1870,22 @@ export class SessionManager {
     // extension door it does leave open. Honoured here rather than in the web, because the decision that
     // matters is 「do not persist」: a recall count belongs to the turn that is running, and writing it
     // into the transcript would put 「recalled 8 memories」 above a conversation from last month.
+    // Background work (issue #22): the same `_meta.hermes` door as the status line carries two more
+    // kinds. `background` is the agent's running snapshot — STATE, replaced wholesale, shown only while
+    // the turn is over and work continues; `completion` is a finished process asking to be read, which
+    // the agent must get as a TURN (ACP has no server->agent wake, so the prompt is the wake). Anything
+    // else is still ignored silently, which is what lets the fork and this server ship independently.
+    const bgTasks = backgroundTasksOf(u);
+    if (bgTasks) {
+      live.background = bgTasks;
+      this.#emit({ t: "background", sessionId: live.info.id, tasks: bgTasks });
+      return;
+    }
+    const finishedText = completionTextOf(u);
+    if (finishedText) {
+      this.#queueOrWakeCompletion(live, finishedText);
+      return;
+    }
     const statusText = statusLineOf(u);
     if (statusText) {
       this.#emit({ t: "status", sessionId: live.info.id, text: statusText, statusKind: statusKindOf(u) });
@@ -1966,6 +2077,13 @@ export class SessionManager {
     if (live.replacing) return;
     this.#dropPending(live);
     live.busy = false;
+    // The child that owned those background processes is gone with it; leaving the rows would draw
+    // 「1 个后台任务在跑」 under a session whose agent is dead (#22).
+    if (live.background.length) {
+      live.background = [];
+      this.#emit({ t: "background", sessionId: live.info.id, tasks: [] });
+    }
+    live.pendingCompletions = [];
     live.info.status = "error";
     live.info.lastError = `agent process exited (code=${code} sig=${sig})` + stderrTail(live);
     const row = this.#store.getSession(live.info.id);
@@ -2417,6 +2535,55 @@ function statusLineOf(u: Record<string, unknown>): string | null {
   return text || null;
 }
 
+/** The hermes extension kind on this frame, or null for an ordinary ACP update.
+ *
+ *  One reader for every kind, so adding one (completion/background, #22) does not mean another
+ *  defensive `_meta` walk — and so an unknown kind is still ignored SILENTLY, which is what lets the
+ *  fork and the server ship independently.
+ */
+function hermesKindOf(u: Record<string, unknown>): string | null {
+  const meta = u?._meta as { hermes?: { kind?: unknown } } | undefined;
+  const kind = meta?.hermes?.kind;
+  return typeof kind === "string" && kind ? kind : null;
+}
+
+function hermesPayload(u: Record<string, unknown>): Record<string, unknown> {
+  const meta = u?._meta as { hermes?: Record<string, unknown> } | undefined;
+  return meta?.hermes ?? {};
+}
+
+/** The completion sentence a finished background process produced (#22), or null. */
+function completionTextOf(u: Record<string, unknown>): string | null {
+  if (hermesKindOf(u) !== "completion") return null;
+  const text = hermesPayload(u).text;
+  return typeof text === "string" ? text.trim() : null;
+}
+
+/** The agent's running-process snapshot (#22). Dropped (not defaulted) when `tasks` is not an array:
+ *  a malformed frame must never blank a row the operator is reading. */
+function backgroundTasksOf(u: Record<string, unknown>): BackgroundTask[] | null {
+  if (hermesKindOf(u) !== "background") return null;
+  const raw = hermesPayload(u).tasks;
+  if (!Array.isArray(raw)) return null;
+  const out: BackgroundTask[] = [];
+  for (const t of raw) {
+    if (!t || typeof t !== "object") continue;
+    const r = t as Record<string, unknown>;
+    const id = typeof r.id === "string" ? r.id : "";
+    if (!id) continue;
+    const status = r.status === "exited" ? "exited" : "running";
+    out.push({
+      id,
+      command: typeof r.command === "string" ? r.command : "",
+      pid: typeof r.pid === "number" ? r.pid : null,
+      status,
+      uptimeSeconds: typeof r.uptimeSeconds === "number" ? r.uptimeSeconds : undefined,
+      exitCode: typeof r.exitCode === "number" ? r.exitCode : null,
+    });
+  }
+  return out;
+}
+
 function statusKindOf(u: Record<string, unknown>): string | undefined {
   const meta = u?._meta as { hermes?: { statusKind?: unknown } } | undefined;
   const kind = meta?.hermes?.statusKind;

package/packages/server/src/index.ts

@@ -209,6 +209,9 @@ const sessionsEvent = (): ServerEvent => ({
   cold: mgr.cold(),
   archived: mgr.archived(),
   pending: mgr.pendingPermissions(),
+  // Background snapshots (issue #22) ride this frame for the same reason pending approvals do: they are
+  // STATE, and a page that connects or refreshes after the agent last spoke still has to be current.
+  background: mgr.backgroundSnapshots(),
 });
 
 // 工作播报 (issue #16): one long-lived observer per watched session, in its own scratch home under
@@ -383,6 +386,10 @@ setHotwordSource((sessionId) => hotwordsFor(store, sessionId).map((h) => h.word)
   // The plan-tool hint: read per prompt, so the 设置 switch applies to the next turn with nothing
   // to restart (the session's own plan card is what it fills).
   mgr.setPlanHintSource(planHintSettings);
+  // Issue #22: a finished background process may open a turn by itself. Default on (the CLI/gateway
+  // behaviour); the switch exists because a synthetic turn spends tokens the operator may not want
+  // spent at 3am — and it is read live, so flipping it applies to the next completion.
+  mgr.setCompletionWakeSource(() => agentSettings().completionWake);
   mgr.startIdleReaper({
     idleMs: () => envIdleMs ?? agentSettings().idleKillMin * 60_000,
     warmSlots: () => envWarm ?? agentSettings().warmSlots,

package/packages/server/src/settings.ts

@@ -185,9 +185,15 @@ export interface AgentSettings {
    *  (`context`/`messages`/`plan`) is NOT gated: it cannot change anything, and it is what the
    *  工作播报 observer runs on. */
   cockpitSend: boolean;
+  /** Let a finished background process wake the agent with its own result (issue #22). ON by default:
+   *  this is what the CLI and the gateway already do, and the failure it prevents is the silent one —
+   *  a session that looks finished while a build is still running, whose result nobody ever reads. */
+  completionWake: boolean;
 }
 
-export const AGENT_DEFAULT: AgentSettings = { idleKillMin: 5, warmSlots: 5, warmTtlHours: 24, cockpitSend: false };
+export const AGENT_DEFAULT: AgentSettings = {
+  idleKillMin: 5, warmSlots: 5, warmTtlHours: 24, cockpitSend: false, completionWake: true,
+};
 
 /** The numeric half of `AgentSettings` — the keys the range-checked helpers may write. */
 type AgentNumberKey = "idleKillMin" | "warmSlots" | "warmTtlHours";
@@ -419,6 +425,7 @@ function pickAgent(raw: unknown): AgentSettings {
     take("warmSlots", AGENT_WARM_RANGE);
     take("warmTtlHours", AGENT_WARM_TTL_RANGE);
     if (typeof r.cockpitSend === "boolean") out.cockpitSend = r.cockpitSend;
+    if (typeof r.completionWake === "boolean") out.completionWake = r.completionWake;
   }
   return out;
 }
@@ -718,6 +725,10 @@ export function saveAgent(patch: Record<string, unknown>): Settings {
     if (typeof patch.cockpitSend !== "boolean") throw new Error("invalid cockpitSend: expected true or false");
     a.cockpitSend = patch.cockpitSend;
   }
+  if ("completionWake" in patch) {
+    if (typeof patch.completionWake !== "boolean") throw new Error("invalid completionWake: expected true or false");
+    a.completionWake = patch.completionWake;
+  }
   cache = { ...cache, agent: a, updatedAt: Date.now() };
   persist();
   return cache;

package/packages/shared/src/index.ts

@@ -169,7 +169,7 @@ export interface PermissionDiff {
 // ---- WS envelope (server -> browser) ----
 export type ServerEvent =
   | { t: "hello"; clientId: string; resumed: boolean }
-  | { t: "sessions"; sessions: SessionInfo[]; /** rows on disk with NO process and no archive flag — they belong in 工作空间 beside the live ones (a crashed slot must not look archived, and must not vanish from the rail either) */ cold?: SessionInfo[]; /** rows the operator explicitly archived (archivedAt set) — the 已归档 section, whatever their process state */ archived?: SessionInfo[]; /** requests already waiting for an answer, so a page that connects or refreshes learns about them (they are STATE; the events happened before it existed) */ pending?: PermissionRequestView[] }
+  | { t: "sessions"; sessions: SessionInfo[]; /** current background snapshots, for a page that connects AFTER the frame that carried them */ background?: { sessionId: string; tasks: BackgroundTask[] }[]; /** rows on disk with NO process and no archive flag — they belong in 工作空间 beside the live ones (a crashed slot must not look archived, and must not vanish from the rail either) */ cold?: SessionInfo[]; /** rows the operator explicitly archived (archivedAt set) — the 已归档 section, whatever their process state */ archived?: SessionInfo[]; /** requests already waiting for an answer, so a page that connects or refreshes learns about them (they are STATE; the events happened before it existed) */ pending?: PermissionRequestView[] }
   | { t: "session"; session: SessionInfo }
   | { t: "messages"; sessionId: string; messages: StoredMessage[]; hasMore: boolean; partial?: boolean }
   | { t: "message"; message: StoredMessage; /** text to APPEND for a streamed block that grew (absent
@@ -214,6 +214,15 @@ export type ServerEvent =
    *  conversation from last week). Carrier on the ACP side: an empty thought chunk tagged
    *  `_meta.hermes.kind = "status"`. */
   | { t: "status"; sessionId: string; text: string; statusKind?: string }
+  /** Background processes this session still has (issue #22) — the ACP equivalent of the desktop's
+   *  status stack, and the reason a turn can end while work goes on.
+   *
+   *  SNAPSHOT, replaced wholesale, never stored: the agent re-sends the whole list whenever it changes,
+   *  and the last one wins. A row is 「running」 or 「exited」 (with `exitCode`) — the exit is reported
+   *  once, because a process without `notify_on_complete` publishes no event and this frame is the only
+   *  witness it ever ended. Empty `tasks` = nothing runs; the page shows nothing.
+   *  Carrier on the ACP side: an empty thought chunk tagged `_meta.hermes.kind = "background"`. */
+  | { t: "background"; sessionId: string; tasks: BackgroundTask[] }
   /** The session's plan object — the TRUTH the card renders, not the transcript's frames. Sent on
    *  every change, and the same object is available over GET /api/sessions/:id/plan, so a page that
    *  loads after the agent process died still renders the real plan instead of nothing. */
@@ -241,6 +250,18 @@ export type ServerEvent =
  * this tab in the background (`document.hidden` — the page's own answer to 「我正在看就不弹」, made
  * where the fact lives), (3) draw it with `noticeId` as the notification `tag`. Everything about WHAT
  * happened and WHEN to say it is decided server-side. */
+/** One background process as the agent reports it (issue #22). Field names are the wire's, not the
+ *  registry's: `uptimeSeconds`/`exitCode` are normalised server-side so the page never has to know
+ *  whether it is reading `list_sessions()` or a completion event. */
+export interface BackgroundTask {
+  id: string;
+  command: string;
+  pid?: number | null;
+  status: "running" | "exited";
+  uptimeSeconds?: number;
+  exitCode?: number | null;
+}
+
 export interface WebNotice {
   /** `upsert` = show (or replace) the card for `noticeId`; `dismiss` = take it away. */
   op: "upsert" | "dismiss";