agentus 0.3.9 → 0.4.1

package/packages/server/src/index.ts

@@ -10,7 +10,7 @@ import fs from "node:fs";
 import { WebSocketServer, WebSocket } from "ws";
 import { Store } from "./store/store.js";
 import { exportFilename, renderJson, renderMarkdown, type ExportSessionHeader } from "./store/export.js";
-import { SessionManager, SessionUnavailable } from "./acp/session-manager.js";
+import { IMAGE_UNSUPPORTED, SessionManager, SessionUnavailable } from "./acp/session-manager.js";
 import { describeAcpError } from "./acp/errors.js";
 import { BACKENDS } from "./acp/backends.js";
 import { classifyError, checkedHealth, coerceRow, inspectRow, planFor, rowWarnings, seedRows, startupCheck } from "./acp/registry.js";
@@ -19,12 +19,27 @@ import { terms } from "./term.js";
 import { VoiceError, listVoiceModels, setHotwordSource, synthesize, transcribe, voiceCapabilities } from "./voice.js";
 import { hotwordsFor, vocabularyOf } from "./hotwords.js";
 import { openDashscopeStream } from "./dashscope.js";
-import { agentSettings, initSettings, planHintSettings, publicSettings, saveAgent, saveCall, savePrefs, saveSettings, saveTheme } from "./settings.js";
+import {
+  agentSettings, getSettings, initSettings, observerSettings, planHintSettings, publicSettings,
+  saveAgent, saveCall, saveObserver, savePrefs, saveSettings, saveTheme,
+} from "./settings.js";
+import { ObserverHub } from "./observer/hub.js";
 import * as auth from "./auth.js";
 import { NotifyCenter } from "./notify/center.js";
-import type { BackendId, ClientCommand, PermissionDecision, PromptAttachment, ServerEvent } from "../../shared/src/index.js";
+import type { BackendId, ClientCommand, PermissionDecision, PromptAttachment, ServerEvent, SessionInfo } from "../../shared/src/index.js";
+import {
+  COCKPIT_ERRORS, COCKPIT_SCHEMA_VERSION, MESSAGES_TAIL_DEFAULT, capabilities, listSessions, parseSince,
+  sendAllowed, sessionRow, tailMessages, type ListQuery,
+} from "./cockpit/api.js";
 
 const PORT = Number(process.env.AGENTUS_PORT ?? 8788);
+
+// The INSTANCE's own name (issue #19). One person runs several cockpits — live, a pre-release box,
+// the one at home — and every tab plus every home-screen icon said "Agentus", so the only way to
+// tell them apart was the domain. The name is not a build input: the HTML is already served
+// no-store and names the hashed bundle, so renaming it here costs nothing and needs no rebuild.
+// Unset keeps "Agentus" byte for byte, so an install that never set it is unchanged.
+const TITLE = (process.env.AGENTUS_TITLE ?? "").trim() || "Agentus";
 // 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
@@ -79,6 +94,7 @@ if (process.env.AGENTUS_PRINT_PATHS) {
   console.log(`[agentus] web bundle    ${WEB_DIST}  (${has(path.join(WEB_DIST, "index.html"))})`);
   console.log(`[agentus] companion apk ${APK_FILE}  (${has(APK_FILE)})`);
   console.log(`[agentus] http port     ${PORT}`);
+  console.log(`[agentus] instance name ${TITLE}`);
   process.exit(0);
 }
 
@@ -140,6 +156,9 @@ function sessionRoot(sessionId: string): { path: string; workspace: string | nul
 }
 
 function emit(evt: ServerEvent): void {
+  // Older builds below get the plain fan-out. The hub reads the SAME frames the page reads, and may
+  // emit a `speak` of its own — which lands back here one level deep and is then broadcast normally.
+  if (evt.t !== "speak") hub?.onEvent(evt);
   const wire = JSON.stringify(evt);
   for (const { ws } of clients.values()) {
     if (ws.readyState === WebSocket.OPEN) ws.send(wire);
@@ -152,6 +171,11 @@ function emit(evt: ServerEvent): void {
 
 const mgr = new SessionManager(store, emit);
 
+/** 工作播报 (issue #16). Constructed AFTER the manager so it can spawn observers through it, and
+ *  wired into `emit` above through this mutable handle — the hub itself is not in the broadcast
+ *  path, it only OBSERVES the same event stream the browser sees (one source of truth). */
+let hub: ObserverHub | null = null;
+
 /** The session list every client stays current with: the rows PLUS what is already waiting for
  *  an answer. Pending approvals are STATE, not just an event — a page that connects or refreshes
  *  after the request was raised still has to be able to show it.
@@ -169,6 +193,43 @@ const sessionsEvent = (): ServerEvent => ({
   pending: mgr.pendingPermissions(),
 });
 
+// 工作播报 (issue #16): one long-lived observer per watched session, in its own scratch home under
+// `~/.hermes/agentus/observers/<sid>` — never the observed session's cwd (an observer that can write
+// into the project is an observer that changes what it is watching, and the rail groups by cwd: the
+// ghost row next to the real one is issue #13 all over again).
+hub = new ObserverHub({
+  home: path.join(homedir(), ".hermes", "agentus"),
+  settings: observerSettings,
+  // 工作播报 is the operator's third speaker position; in the other two the cockpit says nothing, so
+  // no observer is spawned and no tokens are spent.
+  speakEnabled: () => getSettings().prefs.speakMode === "brief",
+  createSession: async (backend, cwd, title) => (await mgr.create(backend, cwd, title, { system: true })).id,
+  prompt: (id, text) => mgr.prompt(id, text, []),
+  waitReady: (id, ms) => mgr.awaitReady(id, ms).then(() => undefined),
+  titleOf: (id) => store.getSession(id)?.title ?? null,
+  backendOf: (id) => store.getSession(id)?.backend ?? null,
+  planTitleOf: (id) => store.getPlan(id)?.title?.trim() || null,
+  // Read-only is a SECOND line of defence behind the scratch directory: a runtime that offers a
+  // read-only (or plan) mode should not be able to accept a write from an observer at all. Modes
+  // arrive with the handshake, so this is a bounded poll; if the backend offers nothing matching,
+  // the observer simply runs in its default mode — inside a directory that holds nothing.
+  preferReadonly: (id) => {
+    const started = Date.now();
+    const pick = (): void => {
+      const modes = mgr.modesOf(id);
+      const options = modes?.availableModes ?? [];
+      if (!options.length && Date.now() - started < 20_000) {
+        setTimeout(pick, 500).unref?.();
+        return;
+      }
+      const wanted = options.find((m) => /read[-_ ]?only|readonly|plan/i.test(m.id) || /只读|规划/.test(m.name));
+      if (wanted) void mgr.setMode(id, wanted.id).catch(() => {});
+    };
+    pick();
+  },
+  emit,
+});
+
 // ---- notify channel (docs/android-notify-contract.md) ----------------------------
 // Owns pairing, the device websocket, the activity lifecycle and the button callbacks.
 // It holds no agent logic: what an event MEANS is decided in notify/center.ts §ACP mapping,
@@ -177,6 +238,9 @@ const notify = new NotifyCenter({
   dataDir: DATA_DIR,
   log: (line: string) => console.log(line),
   sessionTitle: (id: string) => mgr.list().find((s) => s.id === id)?.title ?? store.getSession(id)?.title ?? null,
+  // The completion card's task line (#11). Read straight from the plan OBJECT — the same row the
+  // card renders — so the notification and the screen can never disagree about what finished.
+  sessionPlan: (id: string) => store.getPlan(id),
   // Operator credential = whatever already unlocks the cockpit (session cookie or machine token).
   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.
@@ -339,10 +403,23 @@ function runPrompt(
     const msg = describeAcpError(e);
     const tail = mgr.stderrTail(sessionId);
     console.error(`[agentus] prompt failed for ${sessionId}: ${msg}${tail ? `\n  agent stderr tail:\n  ${tail}` : ""}`);
+    // `rejectedPrompt` is the operator's own sentence, handed back with the refusal so the client can
+    // put it back in line instead of losing it with the red bubble (see state.ts, case "message").
+    // Only for the refusals that mean 「你的话我还没收到，不是它失败了」: a busy agent, and an agent that
+    // cannot take the picture the operator just attached (issue #17) — there the sentence is still
+    // worth keeping, it is the image that has to go.
+    const lost = msg === "turn already running" || msg === IMAGE_UNSUPPORTED;
     emit({ t: "message", message: {
-      seq: -1, sessionId, kind: "meta", payload: { text: `turn failed: ${msg}` }, createdAt: Date.now(),
+      seq: -1, sessionId, kind: "meta",
+      payload: { text: `turn failed: ${msg}`, ...(lost ? { rejectedPrompt: text } : {}) },
+      createdAt: Date.now(),
     } });
-    emit({ t: "turn-end", sessionId, error: msg });
+    // `turn-end` is the frame that says A TURN IS OVER. For the two "nothing left the client" refusals
+    // there was no turn to end: the busy case still has the operator's ORIGINAL turn running (its own
+    // turn-end will come), and a refused image never started one. Emitting one anyway flipped the page
+    // to idle mid-turn — the stop button vanished while the agent was still working (measured 2026-10-17
+    // in `attachment-capability`, on the busy branch).
+    if (!lost) emit({ t: "turn-end", sessionId, error: msg });
   });
 }
 
@@ -391,6 +468,33 @@ function send(res: ServerResponse, code: number, body: unknown): void {
   res.end(JSON.stringify(body));
 }
 
+/** Escape the one instance name that reaches HTML — an operator's `AGENTUS_TITLE` is not markup. */
+function htmlEscape(s: string): string {
+  return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
+}
+
+/** Put the instance name in the tab title. A body without a `<title>` is left alone rather than
+ *  guessed at: a release that changes index.html will fail the sweep, not silently ship a title. */
+function withTitle(html: string): string {
+  if (TITLE === "Agentus") return html; // never set → the built file is the answer, byte for byte
+  return html.replace(/<title>[^<]*<\/title>/i, `<title>${htmlEscape(TITLE)}</title>`);
+}
+
+/** Put the instance name on the home screen. `name` is the install dialog and the launcher label in
+ *  most launchers; `short_name` is what actually fits under the icon, and Android truncates it
+ *  itself — inventing our own abbreviation produced names nobody chose. */
+function withManifestName(text: string): string {
+  if (TITLE === "Agentus") return text;
+  try {
+    const j = JSON.parse(text) as Record<string, unknown>;
+    j.name = TITLE;
+    j.short_name = TITLE;
+    return JSON.stringify(j, null, 2);
+  } catch {
+    return text; // an unparseable manifest is not worth failing a page load over
+  }
+}
+
 function serveStatic(req: IncomingMessage, res: ServerResponse): void {
   // SPA fallback for web build; only GET
   if (!fs.existsSync(WEB_DIST)) {
@@ -408,6 +512,29 @@ function serveStatic(req: IncomingMessage, res: ServerResponse): void {
     ".svg": "image/svg+xml", ".png": "image/png", ".webmanifest": "application/manifest+json",
     ".json": "application/json", ".ico": "image/x-icon",
   };
+  // The two bodies this server EDITS on the way out are the two that carry the instance's name
+  // (issue #19): the tab title lives in index.html, the home-screen label in the manifest. Every
+  // other file is streamed untouched — the hashed assets are immutable and must stay byte-exact.
+  if (ext === ".html" || ext === ".webmanifest") {
+    let body: string;
+    try {
+      body = fs.readFileSync(file, "utf8");
+    } catch {
+      res.writeHead(500); res.end("web build unreadable"); return;
+    }
+    if (ext === ".html") body = withTitle(body);
+    else body = withManifestName(body);
+    res.writeHead(200, {
+      "content-type": types[ext] ?? "text/plain",
+      // Same rule as below: the HTML names the hashed bundle, so it must never be cached. The
+      // manifest carries the instance name, which an operator changes by restarting with a new
+      // AGENTUS_TITLE — a cached copy would keep the old label on the home screen for a year.
+      "cache-control": "no-cache, must-revalidate",
+      "content-length": String(Buffer.byteLength(body)),
+    });
+    res.end(body);
+    return;
+  }
   res.writeHead(200, {
     "content-type": types[ext] ?? "application/octet-stream",
     // The HTML must never be cached: it names the hashed bundle, so a cached index.html keeps serving
@@ -437,6 +564,162 @@ const handleRequest = async (req: IncomingMessage, res: ServerResponse) => {
     // minted per agent process and delivered through the ACP handshake (§4) — plus a loopback-only
     // rule, so the token never crosses a network. The blast radius of a leaked token is one session's
     // plan, which is the object the operator is already looking at.
+    // The cockpit CLI's data plane (issue #15). AHEAD of the operator gate for the same reason the
+    // plan tool is: its caller is an AGENT CHILD process with no browser session, and handing it
+    // operator credentials would put them in every agent's environment. It carries a token minted per
+    // agent process (env, never argv) plus the same loopback rule, so the token cannot cross a network.
+    if (url.pathname.startsWith("/api/cockpit/")) {
+      const ip = clientIp(req);
+      if (!LOOPBACK_IPS.has(ip)) return send(res, 403, { error: "the cockpit channel is loopback-only" });
+      const caller = mgr.cockpitCaller(String(req.headers["x-agentus-cockpit-token"] ?? ""));
+      // Operator mode: the machine token in <DATA>/auth.token is already the credential that lets
+      // scripts act as the operator, so a human at a shell can use the same CLI. `caller` stays the
+      // empty string — there is no agent to attribute to, so `self` is null and a rename this way
+      // records no author (NULL title_by = the operator), which is exactly right.
+      const isOperator = !caller && auth.verifyMachineToken(/^Bearer\s+(.+)$/i.exec(String(req.headers.authorization ?? ""))?.[1] ?? undefined);
+      if (!caller && !isOperator) return send(res, 403, { error: COCKPIT_ERRORS.badToken });
+      // Scope: what the operator can see. 已归档 is out, on purpose — see `cockpitRows`.
+      const rows = mgr.cockpitRows();
+      const rowOf = (id: string): SessionInfo | null => rows.find((s) => s.id === id) ?? null;
+      const summarize = (s: SessionInfo) => sessionRow(s, {
+        plan: store.getPlan(s.id),
+        permissions: mgr.pendingFor(s.id).length,
+      });
+      const sendOk = sendAllowed(agentSettings().cockpitSend);
+
+      if (url.pathname === "/api/cockpit/capabilities" && req.method === "GET") {
+        return send(res, 200, capabilities(sendOk));
+      }
+      if (url.pathname === "/api/cockpit/context" && req.method === "GET") {
+        const sp = url.searchParams;
+        const self = caller ? rowOf(caller) : null; // operator mode: no session, so no `self`
+        // `--all` is the ONE way archived rows enter this channel, and it is opt-in per call: the
+        // product rule (an archive is a statement that the work is closed) still holds by default.
+        const pool = sp.get("all") === "1" || sp.get("all") === "true"
+          ? [...rows, ...mgr.archived()]
+          : rows;
+        // `--here`: the CALLER's own workspace, resolved here because only the server knows the
+        // canonical path the rail groups by.
+        const here = sp.get("here") === "1" || sp.get("here") === "true";
+        const by = sp.get("by") ?? undefined;
+        if (by && by !== "workspace") {
+          return send(res, 400, { error: COCKPIT_ERRORS.badRequest, message: `--by wants workspace, got "${by}"` });
+        }
+        const query: ListQuery = {
+          workspace: here ? (self ? self.workspace || self.cwd : undefined) : sp.get("workspace") ?? undefined,
+          status: sp.get("status") ?? undefined,
+          waiting: sp.get("waiting") === "1" || sp.get("waiting") === "true",
+          since: sp.get("since") ?? undefined,
+          createdSince: sp.get("created_since") ?? undefined,
+          grep: sp.get("grep") ?? undefined,
+          sort: (sp.get("sort") as ListQuery["sort"] | null) ?? undefined,
+          limit: sp.get("limit") ? Number(sp.get("limit")) : undefined,
+          all: sp.get("all") === "1" || sp.get("all") === "true",
+          includeSelf: sp.get("include_self") === "1" || sp.get("include_self") === "true",
+          by: by as ListQuery["by"],
+        };
+        if (query.sort && !["last", "created", "name"].includes(query.sort)) {
+          return send(res, 400, { error: COCKPIT_ERRORS.badRequest, message: `--sort wants last|created|name, got "${query.sort}"` });
+        }
+        // A window that cannot be parsed is REFUSED. Silently ignoring it would answer a different
+        // question than the one asked, and the caller would believe the empty list.
+        for (const [field, raw] of [["since", query.since], ["created_since", query.createdSince]] as const) {
+          if (!raw) continue;
+          const parsed = parseSince(raw);
+          if (!parsed.ok) return send(res, 400, { error: COCKPIT_ERRORS.badRequest, message: parsed.why });
+        }
+        // Mark the caller's own row: it stays visible (you are part of the cockpit) but it is never a
+        // send target, and saying so in the data is cheaper than making every reader remember.
+        const marked = pool.map((s) => ({ ...summarize(s), ...(s.id === caller ? { self: true } : {}) }));
+        const listed = listSessions(marked, query);
+        return send(res, 200, {
+          schema_version: COCKPIT_SCHEMA_VERSION,
+          self: self ? summarize(self) : null,
+          sessions: listed.rows,
+          ...(listed.groups ? { groups: listed.groups } : {}),
+          meta: {
+            ...listed.meta,
+            scope: query.all ? "live+cold+archived (--all)" : "live+cold, archived excluded",
+          },
+        });
+      }
+      if (url.pathname === "/api/cockpit/rename" && req.method === "POST") {
+        const body = await readJson(req);
+        const id = String(body.id ?? "");
+        if (!id) return send(res, 400, { error: COCKPIT_ERRORS.badRequest });
+        if (!rowOf(id)) return send(res, 404, { error: COCKPIT_ERRORS.outOfScope });
+        // Recorded as THIS session's doing (titleBy), so the operator can tell an agent-named
+        // conversation from one they named. `auto` clears back to the generated title.
+        const title = body.auto === true ? null : String(body.title ?? "").trim();
+        if (body.auto !== true && !title) return send(res, 400, { error: COCKPIT_ERRORS.badRequest });
+        try {
+          const info = mgr.rename(id, title, caller);
+          return send(res, 200, {
+            schema_version: COCKPIT_SCHEMA_VERSION,
+            renamed: true,
+            id,
+            name: info.title,
+            titleBy: info.titleBy ?? null,
+          });
+        } catch (e) {
+          return send(res, 404, { error: COCKPIT_ERRORS.outOfScope, message: String((e as Error)?.message ?? e) });
+        }
+      }
+      if (url.pathname === "/api/cockpit/session" && req.method === "GET") {
+        const id = url.searchParams.get("id") ?? "";
+        const info = rowOf(id);
+        if (!info) return send(res, 404, { error: COCKPIT_ERRORS.noSuchSession });
+        const waiting = mgr.pendingFor(id).map((p) => ({
+          requestId: p.requestId, title: p.toolCallTitle ?? p.kind ?? "请求",
+          options: (p.options ?? []).map((o) => ({ id: o.optionId, name: o.name, kind: o.kind })),
+        }));
+        return send(res, 200, {
+          schema_version: COCKPIT_SCHEMA_VERSION,
+          session: summarize(info),
+          plan: store.getPlan(id),
+          pending: waiting,
+          messages: tailMessages(mgr.messages(id, -1, 500), 0).meta,
+        });
+      }
+      if (url.pathname === "/api/cockpit/messages" && req.method === "GET") {
+        const id = url.searchParams.get("id") ?? "";
+        if (!rowOf(id)) return send(res, 404, { error: COCKPIT_ERRORS.noSuchSession });
+        const tail = Number(url.searchParams.get("tail") ?? MESSAGES_TAIL_DEFAULT);
+        const out = tailMessages(mgr.messages(id, -1, 2000), tail);
+        return send(res, 200, { schema_version: COCKPIT_SCHEMA_VERSION, messages: out.rows, meta: out.meta });
+      }
+      if (url.pathname === "/api/cockpit/plan" && req.method === "GET") {
+        const id = url.searchParams.get("id") ?? "";
+        if (!rowOf(id)) return send(res, 404, { error: COCKPIT_ERRORS.noSuchSession });
+        return send(res, 200, { schema_version: COCKPIT_SCHEMA_VERSION, plan: store.getPlan(id) });
+      }
+      if (url.pathname === "/api/cockpit/send" && req.method === "POST") {
+        const body = await readJson(req);
+        const to = String(body.to ?? "");
+        const message = String(body.message ?? "").trim();
+        if (!to || !message) return send(res, 400, { error: COCKPIT_ERRORS.badRequest });
+        if (!sendOk) return send(res, 403, { error: COCKPIT_ERRORS.sendsDisabled });
+        const target = rowOf(to);
+        if (!target) return send(res, 404, { error: COCKPIT_ERRORS.outOfScope });
+        if (target.cold) return send(res, 409, { error: COCKPIT_ERRORS.targetCold });
+        // Deliberately NOT `interrupt`: a cross-session message must never take the floor from a turn
+        // the OPERATOR started. A busy target answers `target_busy` and the caller reports it as such.
+        try {
+          // `origin` is not decoration: without it the target's page shows this as a message the
+          // OPERATOR typed. With it the bubble says which session it came from.
+          await mgr.prompt(to, message, [], {
+            interrupt: false,
+            origin: caller ? { sessionId: caller, title: rows.find((s) => s.id === caller)?.title ?? null } : undefined,
+          });
+        } catch (e) {
+          const why = String((e as Error)?.message ?? e);
+          return send(res, 409, { error: why.includes("turn already running") ? COCKPIT_ERRORS.targetBusy : why });
+        }
+        return send(res, 200, { delivered: true, to, code: "delivered" });
+      }
+      return send(res, 404, { error: "unknown cockpit command" });
+    }
+
     if (url.pathname === "/api/plan/mcp" && req.method === "POST") {
       const ip = clientIp(req);
       if (!LOOPBACK_IPS.has(ip)) return send(res, 403, { error: "the plan tool is loopback-only" });
@@ -448,7 +731,9 @@ const handleRequest = async (req: IncomingMessage, res: ServerResponse) => {
         return out.ok ? send(res, 200, { plan: out.plan }) : send(res, 403, { error: out.error });
       }
       if (body.op === "update") {
-        const out = mgr.writePlanFromMcp(sessionId, token, { items: body.items, explanation: body.explanation });
+        const out = mgr.writePlanFromMcp(sessionId, token, {
+          items: body.items, title: body.title, explanation: body.explanation,
+        });
         if (!out.ok) return send(res, 403, { error: out.error });
         return send(res, 200, { accepted: out.accepted, reason: out.reason, plan: out.plan });
       }
@@ -892,7 +1177,8 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         if (body.call && typeof body.call === "object") saveCall(body.call as Record<string, unknown>);
         if (body.prefs && typeof body.prefs === "object") savePrefs(body.prefs as Record<string, unknown>);
         if (body.agent && typeof body.agent === "object") saveAgent(body.agent as Record<string, unknown>);
-        if (!body.voice && !body.theme && !body.call && !body.prefs && !body.agent) saveSettings(body);
+        if (body.observer && typeof body.observer === "object") saveObserver(body.observer as Record<string, unknown>);
+        if (!body.voice && !body.theme && !body.call && !body.prefs && !body.agent && !body.observer) saveSettings(body);
         return send(res, 200, publicSettings());
       } catch (e) {
         return send(res, 400, { error: String((e as Error)?.message ?? e) });

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

@@ -15,7 +15,7 @@ import { randomBytes, timingSafeEqual } from "node:crypto";
 import type { IncomingMessage, ServerResponse } from "node:http";
 import type { Duplex } from "node:stream";
 import { WebSocketServer, WebSocket } from "ws";
-import type { PermissionRequestView, ServerEvent } from "../../../shared/src/index.js";
+import type { PermissionRequestView, PlanSnapshot, ServerEvent } from "../../../shared/src/index.js";
 import { DEFAULT_NOTIFY_RULES } from "./types.js";
 import type {
   ActionCallback,
@@ -41,6 +41,9 @@ export interface NotifyCenterOptions {
   credentials?: (username: string, password: string, ip: string) => { ok: boolean; reason?: string };
   /** Session title lookup, for activity subtitles. */
   sessionTitle?: (sessionId: string) => string | null;
+  /** The session's plan OBJECT (`Store.getPlan`), for the one line that says WHAT finished. Read-only
+   *  and optional: a center built without it produces exactly the pre-#11 cards. */
+  sessionPlan?: (sessionId: string) => PlanSnapshot | 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
@@ -121,6 +124,12 @@ function nameAndDetail(name: string, ...detail: Array<string | undefined | null>
   return [name, ...detail.filter((d): d is string => Boolean(d && d.trim()))].join(" · ");
 }
 
+/** Trim a fallback line to the body's budget. The `…` is the honest part: it says the sentence was
+ *  longer, where a silent cut reads as the writer having written exactly that. */
+function clip(text: string, max: number): string {
+  return text.length > max ? `${text.slice(0, max - 1)}…` : text;
+}
+
 /** The agent's own tool title, split at its first ": ".
  *
  *  The head goes on the state line (short — the Xiaomi island clips a title at 20 chars), and the
@@ -141,6 +150,7 @@ export class NotifyCenter {
   private readonly operator: ((req: IncomingMessage, url: URL) => boolean) | null;
   private readonly credentials: ((username: string, password: string, ip: string) => { ok: boolean; reason?: string }) | null;
   private readonly sessionTitle: ((sessionId: string) => string | null) | null;
+  private readonly sessionPlan: ((sessionId: string) => PlanSnapshot | 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. */
@@ -265,6 +275,7 @@ export class NotifyCenter {
     this.operator = opts.operator ?? null;
     this.credentials = opts.credentials ?? null;
     this.sessionTitle = opts.sessionTitle ?? null;
+    this.sessionPlan = opts.sessionPlan ?? null;
     this.apkPath = opts.apkPath ?? null;
     this.onFocus = opts.onFocus ?? null;
     this.state = this.loadState();
@@ -386,6 +397,12 @@ export class NotifyCenter {
     const name = String(body.deviceName ?? "device").slice(0, 60);
     const prior = this.state.devices.find((d) => d.name === name);
     if (prior) this.revoke(prior.deviceId);
+    // A re-pair is the SAME phone logging in again, not a new device: it inherits the old row's read
+    // position. Starting at 0 made `attach` replay the whole stored window as brand-new notifications
+    // — a re-pair (or the app's own 401 self-heal) put on a stack of 「已完成」 banners with a sound
+    // each (issue #12). A genuinely new phone has no prior row and still starts at 0, so a reinstall
+    // keeps getting the full STATE rebuild it needs.
+    const inheritCursor = prior?.cursor ?? 0;
     const device: NotifyDevice = {
       deviceId: `dev_${randomBytes(4).toString("hex")}`,
       token: randomBytes(24).toString("hex"),
@@ -397,7 +414,7 @@ export class NotifyCenter {
       capabilities: Array.isArray(caps) ? caps.map(String) : [],
       createdAt: Date.now(),
       lastSeenAt: null,
-      cursor: 0,
+      cursor: inheritCursor,
     };
     this.state.devices.push(device);
     this.save();
@@ -797,8 +814,11 @@ export class NotifyCenter {
     // passes since=0 and must get everything, one that already saw seq N passes N.
     const cursor = since >= 0 ? Math.max(since, row.cursor) : row.cursor;
     this.send(ws, { t: "hello", deviceId: row.deviceId, serverTime: Date.now(), cursor, live: since < 0 });
+    // `replayed: true` marks catch-up (issue #12): the phone applies the same activity object — it
+    // has to, or a turn that is still running and an approval that is still open would never reach
+    // the screen — but it knows not to announce a FINISHED turn as news again.
     for (const rec of this.replaySince(cursor)) {
-      this.send(ws, { t: "activity", seq: rec.seq, activity: this.degrade(rec.activity, row) });
+      this.send(ws, { t: "activity", seq: rec.seq, activity: this.degrade(rec.activity, row), replayed: true });
     }
     this.log(`[notify] ${row.name} connected (cursor ${cursor} -> replay ${this.replaySince(cursor).length})`);
 
@@ -1037,7 +1057,8 @@ export class NotifyCenter {
           kind: failed ? "error" : "agent_done", priority: "high", ongoing: false, promotable: false,
           title: failed ? "执行失败" : "已完成",
           body: nameAndDetail(title(evt.sessionId),
-            failed ? String(evt.error).slice(0, 140) : durationText(evt.durationMs)),
+            failed ? String(evt.error).slice(0, 140) : this.taskLine(evt.sessionId),
+            failed ? null : durationText(evt.durationMs)),
           channel: {
             id: failed ? "agent_error" : "agent_done",
             name: failed ? "任务出错" : "任务完成",
@@ -1075,6 +1096,36 @@ export class NotifyCenter {
     }
   }
 
+  /** WHAT this turn was about, for the completion card's body (issue #11).
+   *
+   *  The card reads `会话名 · <这句> · 用时 1m12s`. The session name is a PLACE, not a task — on a
+   *  phone 「已完成 · hello」 says nothing about what finished, and the operator's own complaint was
+   *  exactly that. The plan already knows, in three descending levels of quality, and every one of
+   *  them is a string a WRITER put there (nothing is invented or summarised here — the server holds
+   *  no intelligence):
+   *
+   *    1. `title` — the action phrase the writer set for this job (≤40 chars, its own budget);
+   *    2. the first sentence of `explanation` — the writer's remark about scope or why it changed;
+   *    3. the last step this plan shows as completed — the thing it just got done.
+   *
+   *  No plan, or nothing usable in it → null, and the card degrades to the pre-#11 shape
+   *  (`会话名 · 用时`). A one-step turn has no task line to give, and a fabricated one would be worse
+   *  than the silence. */
+  private taskLine(sessionId: string): string | null {
+    const plan = this.sessionPlan?.(sessionId) ?? null;
+    const title = plan?.title?.trim();
+    if (title) return title;
+    const remark = plan?.explanation?.trim();
+    if (remark) {
+      // first sentence only: a remark is prose, and the body line has one line to spend
+      const first = remark.split(/[。.!?！？;；\n]/).map((s) => s.trim()).find(Boolean);
+      if (first) return clip(first, 24);
+    }
+    const closed = [...(plan?.items ?? [])].reverse().find((i) => i.status === "completed");
+    const content = closed?.content?.trim();
+    return content ? clip(content, 24) : null;
+  }
+
   /** The approval card, built but not published: the phone's activity and the page's notice are two
    *  renderings of ONE object, so the wording lives here and nowhere else. */
   private approvalActivity(request: PermissionRequestView, sessionTitle: string, link: string): {

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

@@ -174,7 +174,12 @@ export interface ActionCallback {
 /** Server -> device WS frames. */
 export type NotifyFrame =
   | { t: "hello"; deviceId: string; serverTime: number; cursor: number; live: boolean }
-  | { t: "activity"; seq: number; activity: ActivityObject }
+  /** `replayed: true` = this frame is CATCH-UP sent on attach (the device's cursor was behind), not
+   *  news that just happened. The two need different treatment on the far side: a reconnecting phone
+   *  must rebuild STATE (a turn still running, an approval still waiting) but must not fire a banner
+   *  and a sound for every turn that finished while it was away (issue #12). The flag is additive and
+   *  optional — an older app simply ignores it and behaves as it does today. */
+  | { t: "activity"; seq: number; activity: ActivityObject; replayed?: boolean }
   | { t: "bye"; reason: string };
 
 /** Server-side record: what was published + how to interpret its actions. */