agentus 0.4.2 → 0.4.4

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

@@ -17,6 +17,7 @@ import type { Duplex } from "node:stream";
 import { WebSocketServer, WebSocket } from "ws";
 import type { PermissionRequestView, PlanSnapshot, ServerEvent } from "../../../shared/src/index.js";
 import { DEFAULT_NOTIFY_RULES } from "./types.js";
+import { WebPushService } from "./webpush.js";
 import type {
   ActionCallback,
   ActivityObject,
@@ -98,6 +99,33 @@ function tapTarget(url: string, prefer: OpenTarget["prefer"] = "app"): Pick<Acti
   return { deeplink: url, open: { url, prefer: prefer ?? "auto" } };
 }
 
+/** The session a notice points at, from its `open` URL (`/?session=<id>`). */
+function sessionOfOpen(open: string | null | undefined): string | null {
+  if (!open) return null;
+  try {
+    return new URL(open, "http://local").searchParams.get("session");
+  } catch {
+    return null;
+  }
+}
+
+/** A subscription as the settings card may see it: the device, never the endpoint.
+ *  The endpoint is a long-lived capability URL (whoever holds it can post to that browser's push
+ *  service) — the card only needs to tell one device from another, so host + tail is enough. */
+function publicSub(rec: { endpoint: string; ua?: string; createdAt: number; lastOkAt?: number; fails: number; lastError?: string }) {
+  let host = "";
+  try { host = new URL(rec.endpoint).host; } catch { host = "?"; }
+  return {
+    host,
+    tail: rec.endpoint.slice(-6),
+    ua: rec.ua,
+    createdAt: rec.createdAt,
+    lastOkAt: rec.lastOkAt,
+    fails: rec.fails,
+    lastError: rec.lastError,
+  };
+}
+
 /** How a finished turn reads on a lock screen: 「用时 1m12s」.
  *
  *  The protocol's own answer (`stopReason: end_turn`) is a fact about the wire, not about the
@@ -166,6 +194,8 @@ export class NotifyCenter {
   private onActionCb: ((e: ActionEvent) => void) | null = null;
   /** The page channel's sink: index.ts fans this out to every cockpit websocket. */
   private onNoticeCb: ((n: WebNotice) => void) | null = null;
+  /** The third channel: the only one that reaches a LOCKED screen (see webpush.ts). */
+  private readonly push: WebPushService;
   private timers: NodeJS.Timeout[] = [];
   private wss: WebSocketServer | null = null;
   /** Which session the cockpit is showing, and whether its tab is visible. Deliberately in
@@ -278,6 +308,7 @@ export class NotifyCenter {
     this.sessionPlan = opts.sessionPlan ?? null;
     this.apkPath = opts.apkPath ?? null;
     this.onFocus = opts.onFocus ?? null;
+    this.push = new WebPushService(opts.dataDir, { log: (l) => this.log(l) });
     this.state = this.loadState();
     this.events = this.loadEvents();
   }
@@ -528,11 +559,56 @@ export class NotifyCenter {
     this.onNoticeCb = cb;
   }
 
-  /** Emit one page notice, gated on the web channel's own switches. */
+  /** Emit one page notice, gated on the web channel's own switches — and hand the same notice to the
+   *  push services, so 「关屏也能收」 needs no second decision path (and cannot drift from the page's). */
   private notice(n: Omit<WebNotice, "at">, rule: keyof Omit<NotifyWebRules, "enabled">): void {
     const web = this.rules().web;
     if (!web.enabled || !web[rule]) return;
+    this.emitNotice(n);
+  }
+
+  /** The page + push half of a notice, without any rule gate — for the two cleanups (「跑完了」撤掉
+   *  「运行中」卡、批准后撤掉批准卡) that must happen even when the rule that would have SENT the card
+   *  is off. Taking a dead card off the screen is not an interruption, which is why these two calls
+   *  skip the switches; the push side follows the same logic, or a locked phone would keep a card
+   *  advertising a decision that was already made. */
+  private emitNotice(n: Omit<WebNotice, "at">): void {
     this.onNoticeCb?.({ ...n, at: Date.now() });
+    this.pushNotice(n);
+  }
+
+  /** The push renderer of a notice. Narrower than the page channel on purpose:
+   *
+   *   · 「运行中」 never pushes. A lock-screen card saying "still running" is noise by definition, and
+   *     what was asked for is 完成 and 需要批准 — the two things that want a human.
+   *   · a notice about the session he is LOOKING AT never pushes. The page channel leaves presence to
+   *     the page (`document.hidden`); a push cannot see that, so the server judges here. A phone
+   *     buzzing about the window already on screen is pure interruption.
+   *   · a dismiss IS pushed: it takes the stale card off the lock screen (the worker closes the
+   *     notification by tag), which is the same unconditional cleanup the other two channels do.
+   *
+   *  Fire-and-forget: a push service being slow or dead must never delay the frame to the phone or the
+   *  page. Each send records its own outcome on the subscription (fails / lastError) for the UI to show. */
+  private pushNotice(n: Omit<WebNotice, "at">): void {
+    if (!this.push.subscriptions().length) return;
+    if (n.kind === "agent_running") return; // never pushed, so a dismiss for it has nothing to close
+    const sessionId = sessionOfOpen(n.open);
+    if (sessionId && this.watching(sessionId)) return;
+    const dismiss = n.op === "dismiss";
+    const payload = dismiss
+      ? { op: "dismiss", noticeId: n.noticeId }
+      : { op: "upsert", noticeId: n.noticeId, kind: n.kind, title: n.title, body: n.body, open: n.open, sticky: Boolean(n.sticky) };
+    // 审批卡要活到有人动手：TTL 一天，urgency high（叫醒设备）。完成/出错一小时就够。
+    const approval = n.kind === "approval";
+    void this.push
+      .broadcast(payload, dismiss
+        ? { urgency: "very-low", ttlSec: 300 }
+        : { urgency: approval ? "high" : "normal", ttlSec: approval ? 86_400 : 3_600 })
+      .then((results) => {
+        const bad = results.filter((r) => !r.ok);
+        if (bad.length) this.log(`[notify] web push: ${bad.length}/${results.length} 未送达（${bad[0]?.error ?? ""}）`);
+      })
+      .catch((e: Error) => this.log(`[notify] web push threw: ${e.message}`));
   }
 
   // ---- actions -------------------------------------------------------------
@@ -609,6 +685,54 @@ export class NotifyCenter {
       }) && true;
     }
 
+    // ---- 网页推送（关屏也能收）-----------------------------------------------------
+    // The public key has to reach the browser to subscribe; the SUBSCRIPTION LIST must not — it says
+    // how many devices listen to this cockpit. So the whole group sits behind the operator gate, the
+    // same reason the APK and the root certificate do.
+    if (p === "/api/notify/webpush" || p.startsWith("/api/notify/webpush/")) {
+      if (!isOperator()) return json(401, { error: "operator auth required" }) && true;
+      const subs = () => this.push.subscriptions().map(publicSub);
+
+      if (p === "/api/notify/webpush" && req.method === "GET") {
+        return json(200, { ok: true, publicKey: this.push.publicKey(), subs: subs() }) && true;
+      }
+
+      if (p === "/api/notify/webpush/subscribe" && req.method === "POST") {
+        const body = await readBody();
+        const rec = this.push.subscribe({
+          endpoint: body.endpoint,
+          keys: (body.keys ?? {}) as { p256dh?: unknown; auth?: unknown },
+          ua: body.ua,
+        });
+        if ("error" in rec) return json(400, { error: rec.error }) && true;
+        this.log(`[notify] 网页推送已订阅：${new URL(rec.endpoint).host}（共 ${this.push.subscriptions().length} 台）`);
+        return json(200, { ok: true, subs: subs() }) && true;
+      }
+
+      if (p === "/api/notify/webpush/unsubscribe" && req.method === "POST") {
+        const body = await readBody();
+        const removed = this.push.unsubscribe(String(body.endpoint ?? ""));
+        return json(200, { ok: true, removed, subs: subs() }) && true;
+      }
+
+      // The test button: proves the WHOLE chain (our VAPID key → push service → service worker →
+      // lock screen). A test that only logged to the server would prove none of it.
+      if (p === "/api/notify/webpush/test" && req.method === "POST") {
+        if (!this.push.subscriptions().length) return json(400, { error: "这台服务器还没有任何浏览器订阅" }) && true;
+        const results = await this.push.broadcast({
+          op: "upsert", noticeId: "test:webpush", kind: "agent_done", sticky: false,
+          title: "推送测试", body: "锁屏上能看到这条，就说明关屏也能收", open: "/",
+        }, { urgency: "high", ttlSec: 300 });
+        return json(200, {
+          ok: results.every((r) => r.ok),
+          results: results.map((r) => ({ ok: r.ok, status: r.status, error: r.error, gone: r.gone })),
+          subs: subs(),
+        }) && true;
+      }
+
+      return json(404, { error: "unknown webpush route" }) && true;
+    }
+
     if (p === "/api/notify/presence" && req.method === "POST") {
       // The cockpit telling us what it is showing. Operator-authenticated (the SPA has the
       // cookie); a missing report just means presence goes stale and quiet-when-watching stops
@@ -1037,17 +1161,13 @@ export class NotifyCenter {
         // taking a dead card off the screen is not an interruption, and gating it on a preference
         // would leave a card nobody can answer.
         this.dismiss(`perm:${evt.requestId}`);
-        this.onNoticeCb?.({
-          op: "dismiss", noticeId: `perm:${evt.requestId}`, kind: "approval", title: "", body: "", at: Date.now(),
-        });
+        this.emitNotice({ op: "dismiss", noticeId: `perm:${evt.requestId}`, kind: "approval", title: "", body: "" });
         return;
       case "turn-end": {
         // The running card goes away unconditionally — a zombie "still running" on the phone is worse
         // than no card at all, even when the frame that started it was suppressed.
         this.dismiss(`turn:${evt.sessionId}`);
-        this.onNoticeCb?.({
-          op: "dismiss", noticeId: `turn:${evt.sessionId}`, kind: "agent_running", title: "", body: "", at: Date.now(),
-        });
+        this.emitNotice({ op: "dismiss", noticeId: `turn:${evt.sessionId}`, kind: "agent_running", title: "", body: "" });
         // Both gates belong here and both were missing: `completion` was stored but never read, and
         // presence was only consulted for turn-start — so the completion card fired while the operator was watching
         // the very session (and, mid-call, with a sound: the reported bug).

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

@@ -0,0 +1,295 @@
+// Web Push — the third renderer of the same notification decision.
+//
+// The three channels and why they exist:
+//
+//   phone (WS)   — the Android companion holds one long connection; only works while the phone is awake.
+//   page         — the open tab draws a notification through the page's own Notification API.
+//   push (here)  — the ONLY channel that survives a locked screen: the page is frozen by iOS/Android
+//                  the moment it leaves the foreground, and no JS runs to notice anything. A push
+//                  service holds the message until the device is reachable, wakes the service worker,
+//                  and the worker draws the card. That is why this exists and the page renderer cannot
+//                  replace it.
+//
+// Nothing here decides WHAT is worth notifying — `center.ts` owns that (one decision, three renderers).
+// This module only knows how to hand bytes to a push service: encryption (RFC 8291 / aes128gcm) and
+// VAPID authorization (RFC 8292).
+//
+// No dependency on `web-push`: the whole job is ~120 lines of node:crypto, and a dependency here would
+// mean an npm install on a machine whose registry access is already the flakiest part of a release.
+// The RFC's own test vector is checked by `scripts/qa/webpush-crypto.mts` — see the note at encryptPush().
+import crypto from "node:crypto";
+import fs from "node:fs";
+import http from "node:http";
+import https from "node:https";
+import path from "node:path";
+
+/** One browser's subscription, as `pushManager.subscribe()` returned it. */
+export interface PushSubscriptionRecord {
+  endpoint: string;
+  /** base64url of the UA's uncompressed P-256 point (65 bytes) — the `keys.p256dh` the browser gave us. */
+  p256dh: string;
+  /** base64url of the 16-byte auth secret — `keys.auth`. */
+  auth: string;
+  ua?: string;
+  createdAt: number;
+  /** Last time a push was accepted by the push service (HTTP 201). */
+  lastOkAt?: number;
+  fails: number;
+  lastError?: string;
+}
+
+interface VapidFile {
+  /** base64url uncompressed point (65 bytes) — what the browser needs as applicationServerKey. */
+  publicKey: string;
+  /** The private half, kept as a JWK because that is what createPrivateKey() eats. */
+  jwk: { kty: string; crv: string; x: string; y: string; d: string };
+  subject: string;
+}
+
+interface SubscriptionFile {
+  subs: PushSubscriptionRecord[];
+}
+
+// ---- base64url ----------------------------------------------------------------
+
+export const b64u = (buf: Buffer): string => buf.toString("base64").replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
+
+export const unb64u = (str: string): Buffer => Buffer.from(str.replace(/-/g, "+").replace(/_/g, "/"), "base64");
+
+// ---- RFC 8291: encrypting one push message ------------------------------------
+
+/** The message body a push service carries for us: `aes128gcm` single record (RFC 8188 §2, RFC 8291 §4).
+ *
+ *  Layout of the body: 16-byte salt ‖ rs (u32 BE = 4096) ‖ idlen (u8 = 65) ‖ AS public key ‖ ciphertext.
+ *  The plaintext gets the padding delimiter 0x02 appended, because it is the last (only) record.
+ *
+ *  `opts` exists ONLY so the RFC 8291 §5 test vector can be reproduced byte-for-byte: it pins the salt
+ *  and the application-server keypair. Production calls always pass no salt and a fresh keypair — the
+ *  whole security property rests on both being random per message.
+ *
+ *  Verified against that vector (Appendix A gives every intermediate: ecdh_secret, PRK_key, IKM, PRK,
+ *  CEK, NONCE, and the final body). If this function and the vector disagree, the push is silently
+ *  undecryptable by the browser and nothing else in the system would tell us — hence a test, not hope. */
+export function encryptPush(
+  uaPublicRaw: Buffer,
+  authSecret: Buffer,
+  plaintext: Buffer,
+  opts: { salt?: Buffer; asKeys?: crypto.KeyObject[] } = {},
+): Buffer {
+  const salt = opts.salt ?? crypto.randomBytes(16);
+  const pair = opts.asKeys ?? (() => {
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+    return [privateKey, publicKey];
+  })();
+  const [asPrivate, asPublic] = pair;
+
+  const uaPublic = crypto.createPublicKey({
+    key: { kty: "EC", crv: "P-256", x: b64u(uaPublicRaw.subarray(1, 33)), y: b64u(uaPublicRaw.subarray(33, 65)) },
+    format: "jwk",
+  });
+  const ecdhSecret = crypto.diffieHellman({ privateKey: asPrivate, publicKey: uaPublic });
+  const asPoint = pointFromJwk(asPublic.export({ format: "jwk" }) as { x: string; y: string });
+
+  // IKM = HKDF-Extract(auth_secret, ecdh_secret) then Expand with "WebPush: info\0" ‖ ua ‖ as.
+  const keyInfo = Buffer.concat([Buffer.from("WebPush: info\0", "utf8"), uaPublicRaw, asPoint]);
+  const ikm = Buffer.from(crypto.hkdfSync("sha256", ecdhSecret, authSecret, keyInfo, 32));
+
+  // CEK/NONCE come from RFC 8188's HKDF with the per-message salt.
+  const cek = Buffer.from(crypto.hkdfSync("sha256", ikm, salt, Buffer.from("Content-Encoding: aes128gcm\0", "utf8"), 16));
+  const nonce = Buffer.from(crypto.hkdfSync("sha256", ikm, salt, Buffer.from("Content-Encoding: nonce\0", "utf8"), 12));
+
+  const record = Buffer.concat([plaintext, Buffer.from([0x02])]);
+  const cipher = crypto.createCipheriv("aes-128-gcm", cek, nonce);
+  const ct = Buffer.concat([cipher.update(record), cipher.final(), cipher.getAuthTag()]);
+
+  const rs = Buffer.alloc(4);
+  rs.writeUInt32BE(4096, 0);
+  return Buffer.concat([salt, rs, Buffer.from([asPoint.length]), asPoint, ct]);
+}
+
+function pointFromJwk(jwk: { x: string; y: string }): Buffer {
+  return Buffer.concat([Buffer.from([0x04]), unb64u(jwk.x), unb64u(jwk.y)]);
+}
+
+// ---- VAPID + delivery ---------------------------------------------------------
+
+export interface SendResult { ok: boolean; status: number; error?: string; gone?: boolean }
+
+export class WebPushService {
+  private readonly dir: string;
+  private readonly subject: string;
+  private readonly log: (line: string) => void;
+  private vapidCache: VapidFile | null = null;
+  private subsCache: PushSubscriptionRecord[] | null = null;
+
+  constructor(dataDir: string, opts: { subject?: string; log?: (line: string) => void } = {}) {
+    this.dir = path.join(dataDir, "notify");
+    this.subject = opts.subject ?? process.env.AGENTUS_VAPID_SUBJECT ?? "mailto:agentus@localhost";
+    this.log = opts.log ?? ((l) => console.log(l));
+  }
+
+  private get vapidFile(): string { return path.join(this.dir, "vapid.json"); }
+  private get subsFile(): string { return path.join(this.dir, "webpush.json"); }
+
+  /** The server's identity to push services. Generated on first use and then never rotated by itself:
+   *  rotating the VAPID key invalidates every existing subscription, so that must stay a deliberate act. */
+  private vapid(): VapidFile {
+    if (this.vapidCache) return this.vapidCache;
+    try {
+      this.vapidCache = JSON.parse(fs.readFileSync(this.vapidFile, "utf8")) as VapidFile;
+      return this.vapidCache;
+    } catch { /* first boot */ }
+    const { publicKey, privateKey } = crypto.generateKeyPairSync("ec", { namedCurve: "P-256" });
+    const jwk = privateKey.export({ format: "jwk" }) as VapidFile["jwk"];
+    const record: VapidFile = { publicKey: b64u(pointFromJwk(jwk)), jwk, subject: this.subject };
+    fs.mkdirSync(this.dir, { recursive: true });
+    fs.writeFileSync(this.vapidFile, JSON.stringify(record, null, 1), { mode: 0o600 });
+    this.log(`[notify] generated a VAPID keypair (${this.vapidFile}) — back it up with the rest of <data>`);
+    this.vapidCache = record;
+    return record;
+  }
+
+  /** `applicationServerKey` for `pushManager.subscribe()`. */
+  publicKey(): string { return this.vapid().publicKey; }
+
+  subscriptions(): PushSubscriptionRecord[] {
+    if (this.subsCache) return this.subsCache;
+    try {
+      const raw = JSON.parse(fs.readFileSync(this.subsFile, "utf8")) as SubscriptionFile;
+      this.subsCache = Array.isArray(raw.subs) ? raw.subs : [];
+    } catch {
+      this.subsCache = [];
+    }
+    return this.subsCache;
+  }
+
+  private save(): void {
+    fs.mkdirSync(this.dir, { recursive: true });
+    fs.writeFileSync(this.subsFile, JSON.stringify({ subs: this.subsCache ?? [] }, null, 1), { mode: 0o600 });
+  }
+
+  /** Idempotent by endpoint: re-subscribing the same browser replaces its keys instead of piling up rows.
+   *  A browser re-subscribes on every page load in some engines, so this must not grow. */
+  subscribe(input: { endpoint?: unknown; keys?: { p256dh?: unknown; auth?: unknown }; ua?: unknown }): PushSubscriptionRecord | { error: string } {
+    const endpoint = typeof input.endpoint === "string" ? input.endpoint : "";
+    const p256dh = typeof input.keys?.p256dh === "string" ? input.keys.p256dh : "";
+    const auth = typeof input.keys?.auth === "string" ? input.keys.auth : "";
+    if (!/^https?:\/\//.test(endpoint)) return { error: "endpoint must be an https URL from the browser" };
+    if (unb64u(p256dh).length !== 65) return { error: "keys.p256dh must be an uncompressed P-256 point (65 bytes)" };
+    if (unb64u(auth).length !== 16) return { error: "keys.auth must be 16 bytes" };
+    const subs = this.subscriptions();
+    const prior = subs.find((s) => s.endpoint === endpoint);
+    const rec: PushSubscriptionRecord = {
+      endpoint, p256dh, auth,
+      ua: typeof input.ua === "string" ? input.ua.slice(0, 200) : undefined,
+      createdAt: prior?.createdAt ?? Date.now(),
+      lastOkAt: prior?.lastOkAt,
+      fails: 0,
+    };
+    this.subsCache = [...subs.filter((s) => s.endpoint !== endpoint), rec];
+    this.save();
+    return rec;
+  }
+
+  unsubscribe(endpoint: string): boolean {
+    const subs = this.subscriptions();
+    const next = subs.filter((s) => s.endpoint !== endpoint);
+    if (next.length === subs.length) return false;
+    this.subsCache = next;
+    this.save();
+    return true;
+  }
+
+  /** ES256 JWT over the endpoint's own origin (RFC 8292 §2). `aud` is per-endpoint on purpose: a token
+   *  minted for one push service must not be replayable at another. */
+  private vapidAuth(endpoint: string, now = Date.now()): string {
+    const { publicKey, jwk } = this.vapid();
+    const header = b64u(Buffer.from(JSON.stringify({ typ: "JWT", alg: "ES256" })));
+    const claims = b64u(Buffer.from(JSON.stringify({
+      aud: new URL(endpoint).origin,
+      exp: Math.floor(now / 1000) + 12 * 3600,
+      sub: this.subject,
+    })));
+    const signingInput = `${header}.${claims}`;
+    const key = crypto.createPrivateKey({ key: jwk, format: "jwk" });
+    // ieee-p1363 = raw R‖S; JWS wants exactly that, DER would be rejected.
+    const sig = crypto.sign("sha256", Buffer.from(signingInput), { key, dsaEncoding: "ieee-p1363" });
+    return `vapid t=${signingInput}.${b64u(sig)}, k=${publicKey}`;
+  }
+
+  /** Hand one message to one push service. `urgency` maps to the RFC 8030 header the platforms honour:
+   *  a lock-screen approval is `high` (deliver immediately, wake the device), a "finished" is `normal`,
+   *  and taking a stale card back is `very-low` (do not wake anything for it). */
+  async send(
+    rec: PushSubscriptionRecord,
+    payload: unknown,
+    opts: { ttlSec?: number; urgency?: "very-low" | "low" | "normal" | "high"; timeoutMs?: number } = {},
+  ): Promise<SendResult> {
+    let body: Buffer;
+    try {
+      body = encryptPush(unb64u(rec.p256dh), unb64u(rec.auth), Buffer.from(JSON.stringify(payload), "utf8"));
+    } catch (e) {
+      return { ok: false, status: 0, error: `encrypt: ${(e as Error).message}` };
+    }
+    let auth: string;
+    try {
+      auth = this.vapidAuth(rec.endpoint);
+    } catch (e) {
+      return { ok: false, status: 0, error: `vapid: ${(e as Error).message}` };
+    }
+    const url = new URL(rec.endpoint);
+    const mod = url.protocol === "http:" ? http : https;
+    return await new Promise<SendResult>((resolve) => {
+      const req = mod.request({
+        protocol: url.protocol,
+        hostname: url.hostname,
+        port: url.port || (url.protocol === "http:" ? 80 : 443),
+        path: `${url.pathname}${url.search}`,
+        method: "POST",
+        headers: {
+          authorization: auth,
+          "content-encoding": "aes128gcm",
+          "content-type": "application/octet-stream",
+          "content-length": String(body.length),
+          ttl: String(opts.ttlSec ?? 3600),
+          urgency: opts.urgency ?? "normal",
+        },
+        timeout: opts.timeoutMs ?? 8000,
+      }, (res) => {
+        const chunks: Buffer[] = [];
+        res.on("data", (c) => chunks.push(Buffer.from(c)));
+        res.on("end", () => {
+          const status = res.statusCode ?? 0;
+          const ok = status >= 200 && status < 300;
+          const text = Buffer.concat(chunks).toString("utf8").slice(0, 300);
+          const gone = status === 404 || status === 410;
+          if (ok) {
+            rec.lastOkAt = Date.now();
+            rec.fails = 0;
+            rec.lastError = undefined;
+            this.save();
+          } else {
+            rec.fails += 1;
+            rec.lastError = `${status} ${text}`.trim();
+            // 404/410 = the browser threw the subscription away (app uninstalled, permission reset).
+            // Keeping it would retry a dead endpoint forever and log a failure on every notification.
+            if (gone) this.unsubscribe(rec.endpoint);
+            else this.save();
+          }
+          resolve({ ok, status, error: ok ? undefined : `${status} ${text}`.trim(), gone });
+        });
+      });
+      req.on("timeout", () => { req.destroy(new Error("push service timed out")); });
+      req.on("error", (e) => resolve({ ok: false, status: 0, error: e.message }));
+      req.end(body);
+    });
+  }
+
+  /** Send the same payload to every subscription. Returns one result per device so the settings card can
+   *  say "2 台设备都收到了" or which one is dead — a silent broadcast would hide a broken device. */
+  async broadcast(payload: unknown, opts: { ttlSec?: number; urgency?: "very-low" | "low" | "normal" | "high" } = {}): Promise<SendResult[]> {
+    const subs = this.subscriptions();
+    if (!subs.length) return [];
+    return await Promise.all(subs.map((s) => this.send(s, payload, opts)));
+  }
+}

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/server/src/store/store.ts

@@ -924,6 +924,56 @@ export class Store {
     return { ...m, seq };
   }
 
+  /**
+   * 一条「状态行」落库（操作者 2026-10-18）：回忆了几条记忆、上下文压缩了、有警告。
+   *
+   * 为什么它不是 `notes` 表而是一行 `messages`（kind `note`）：状态行的位置信息就是 seq ——
+   * 「在用户那句话之后、在回复之前」。单独一张表要么丢掉这个位置，要么在客户端重建锚点，
+   * 而消息流本来就已经按 seq 排队、分页、回放，复用它是这里最省也最不容易错的做法。
+   *
+   * 为什么必须在这里折叠，而不是留给前端（前端 state.ts 原来是自己折的）：压缩是「开始 → 每几秒
+   * 一个心跳 → 完成」，provider 等待也是十来秒一条。客户端折只解决"屏幕上的噪音"，库里照样会
+   * 长出一串心跳。规则只有一条 —— **位置没变就折**：本会话最后一条消息如果是同类的状态行
+   * （说明这中间没有别的消息落下），就更新它，而不是再加一行；位置变了（新消息进来了）就另起一行。
+   * 于是「压缩中 → 完成」收敛成一行（保留开始时间），一个回合一次回忆也只留一行。
+   */
+  appendNote(sessionId: string, note: { category: string; text: string; createdAt?: number }): StoredMessage {
+    const createdAt = note.createdAt ?? Date.now();
+    const edge = this.#db
+      .prepare("select coalesce(max(seq),0) as seq from messages where session_id = ?")
+      .get(sessionId) as { seq: number };
+    const last = this.#db
+      .prepare("select seq, payload, created_at from messages where session_id = ? and kind = 'note' order by seq desc limit 1")
+      .get(sessionId) as { seq: number; payload: string; created_at: number } | undefined;
+    if (last && last.seq === edge.seq) {
+      const prev = JSON.parse(last.payload) as { category?: string; text?: string; hits?: number };
+      if (prev.category === note.category) {
+        const payload = { category: note.category, text: note.text, hits: (prev.hits ?? 1) + 1 };
+        // `created_at` stays: it answers "这一轮什么时候开始回忆/压缩的", and the heartbeat is not news.
+        this.#db
+          .prepare("update messages set payload = ? where session_id = ? and seq = ?")
+          .run(JSON.stringify(payload), sessionId, last.seq);
+        return {
+          seq: last.seq, sessionId, kind: "note", payload, createdAt: last.created_at,
+        };
+      }
+    }
+    const row = this.appendMessage({
+      sessionId, kind: "note", payload: { category: note.category, text: note.text, hits: 1 }, createdAt,
+    });
+    // Bounded: a session left open for weeks must not keep every recall it ever did. 80 is well past
+    // what any transcript page shows, and a note is ~120 bytes.
+    const over = this.#db
+      .prepare("select seq from messages where session_id = ? and kind = 'note' order by seq desc limit -1 offset 80")
+      .all(sessionId) as { seq: number }[];
+    if (over.length) {
+      const del = this.#db.prepare("delete from messages where session_id = ? and seq = ?");
+      for (const r of over) del.run(sessionId, r.seq);
+    }
+    return row;
+  }
+
+
   /**
    * The streaming half of the transcript: one logical message, one row.
    *

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";
@@ -403,7 +424,11 @@ export type ClientCommand =
 export interface StoredMessage {
   seq: number; // monotonic per session — reconnect dedup anchor
   sessionId: string;
-  kind: "user" | "agent" | "thought" | "tool" | "plan" | "meta";
+  /** `note` = a 「状态行」 that is not a message: 「recalled 8 memories」 / 「compacting」 / a warning.
+   *  Deliberately a transcript row (not a separate table): its position IS the seq — after the
+   *  operator's sentence, before the reply — and the page already orders, pages and replays by seq.
+   *  `meta` stays what it was: a line the HOST says (a rejected send), never persisted. */
+  kind: "user" | "agent" | "thought" | "tool" | "plan" | "meta" | "note";
   payload: unknown; // raw ACP content/update fragment (kept lossless)
   toolCallId?: string; // set for kind=tool; upsert key
   createdAt: number;