agentus 0.3.3 → 0.3.5

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

@@ -36,6 +36,7 @@ import type {
   TurnTrace,
 } from "../../../shared/src/index.js";
 import { acceptsToolWrite, acceptsWriteFrom, clampExplanation, demoteInProgress, foldPlanUpdate, hasUnfinished, normalizeItems, v2PlanEnabled } from "../plan/plan.js";
+import type { PlanHintSettings } from "../settings.js";
 
 // Permission prompts must not hang a session forever (design.md §8-4).
 // Env-tunable so QA can exercise the timeout path in seconds instead of minutes.
@@ -108,6 +109,14 @@ const TITLE_FORK_TIMEOUT_MS = Number(process.env.AGENTUS_TITLE_TIMEOUT_MS || 90_
 // (an agent that ignores session/cancel must not hang the operator's next sentence forever).
 const TURN_SETTLE_TIMEOUT_MS = Number(process.env.AGENTUS_SETTLE_TIMEOUT_MS || 15_000);
 
+/** How long a close/archive waits for a slot's in-flight handshake before killing it anyway.
+ *
+ *  `#stop` waits because the agent-side session id only exists once the handshake lands, and a row
+ *  closed without it can never be resumed (see `#stop`). The wait is bounded so a spawn that never
+ *  answers cannot hold the operator's click open forever: past this, the slot closes with whatever it
+ *  has — a broken agent is not made worse by a row we cannot wake. */
+const CLOSE_STARTUP_WAIT_MS = Number(process.env.AGENTUS_CLOSE_WAIT_MS || 30_000);
+
 /** A cold slot the agent cannot adopt, and why — the only two answers there are.
  *
  *  Resuming has to *ask* the agent: `session/load` is "do you still have this session?", and the
@@ -159,6 +168,14 @@ interface LiveSession {
    *  so a second interrupting utterance that already started its own turn is not mistaken for
    *  "the one I cancelled is still running". */
   turnSeq: number;
+  /** The spawn-time handshake, while it is still running.
+   *
+   *  `create()` no longer waits for it (that wait is what made 「新建会话」 feel broken), so the slot
+   *  exists — and can be closed, archived or reaped — before the agent has answered. This handle is
+   *  how the teardown waits for the one thing only the handshake can tell us: the agent-side session
+   *  id. Killing the child before it arrives leaves a row with `acpSessionId: null` that `resume()`
+   *  refuses forever (「was never handed to an agent」) — see `#stop`. */
+  startup?: Promise<void>;
   /** When the operator last USED this slot — he opened it, or his page reported it as the one on
    *  screen. In memory on purpose: this is the half of the idle rule that says "he was just here",
    *  and the store's message clock (which survives restarts) is the other half. Reading only the
@@ -203,12 +220,22 @@ export class SessionManager {
   #sessions = new Map<string, LiveSession>();
   #store: Store;
   #emit: Emitter;
+  /** How the operator wants the plan-tool hint injected into a prompt — read on EVERY prompt, like
+   *  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 = () => ({ on: true, everyTurn: false });
 
   constructor(store: Store, emit: Emitter) {
     this.#store = store;
     this.#emit = emit;
   }
 
+  /** 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 {
+    this.#planHint = read;
+  }
+
   list(): SessionInfo[] {
     // Most recently CHATTED first — the cockpit's left rail is a launch pad, not a log file, and
     // creation order is the wrong key for that: the session you talked to a minute ago is the
@@ -268,14 +295,33 @@ export class SessionManager {
     return s.stderrBuf.slice(-lines).join("\n  ");
   }
 
+  /**
+   * Drop every pending approval of one slot, and TELL THE WIRE each one is gone.
+   *
+   * The client has exactly two ways to take an approval off the screen: the `permission-resolved`
+   * event, or a fresh `sessions` snapshot that no longer lists it. A bare `clear()` therefore
+   * leaves the popup, the transcript card, the ⚿ badge — and the phone's 待你确认 activity — for a
+   * request that does not exist any more; the operator clicks it, the server logs 「answer dropped」
+   * and answers `permission-expired`, and he reads his own cockpit as broken (measured 2026-10-11:
+   * `kill -9` the child with an approval up and the dialog is still there 4s later). So: every path
+   * that resolves these promises from the SERVER side goes through here.
+   *
+   * The decision is `cancelled` — what the agent would have received had nobody ever answered.
+   */
+  #dropPending(live: LiveSession, decision: PermissionDecision = { outcome: "cancelled" }): void {
+    if (!live.pendingPermissions.size) return;
+    for (const [requestId, { resolve, timer }] of live.pendingPermissions) {
+      clearTimeout(timer);
+      resolve({ outcome: decision });
+      this.#emit({ t: "permission-resolved", requestId, decision });
+    }
+    live.pendingPermissions.clear();
+  }
+
   /** Graceful shutdown: SIGTERM every live child before server exit. */
   async shutdown(): Promise<void> {
     const kills = [...this.#sessions.values()].map(async (s) => {
-      for (const { resolve, timer } of s.pendingPermissions.values()) {
-        clearTimeout(timer);
-        resolve({ outcome: { outcome: "cancelled" } });
-      }
-      s.pendingPermissions.clear();
+      this.#dropPending(s);
       s.child?.kill("SIGTERM");
     });
     await Promise.allSettled(kills);
@@ -398,6 +444,33 @@ export class SessionManager {
     });
     child.on("exit", (code, sig) => this.#onChildExit(live, code, sig));
 
+    // The row is complete and already persisted with `status: "starting"` — hand it back to the
+    // caller NOW and let the handshake finish OFF the request. See `#startup`.
+    // Kept on the slot (not dropped with `void`) so a close during the window can wait for the
+    // agent-side id instead of orphaning the session — see `#stop`.
+    live.startup = this.#startup(live, backend, spec, cwd, spawnStarted);
+    void live.startup.catch(() => {}); // `#startup` reports failure on the slot; nobody is awaiting
+    return live.info;
+  }
+
+  /** The spawn-time handshake — `initialize` + `newSession` + the row's default permission mode.
+   *
+   *  Deliberately NOT awaited by `create()`. Holding the HTTP response open for the whole handshake
+   *  is what made 「新建会话」 feel broken: hermes boots a python process and answers in 10–40 s, the
+   *  page sat on a busy dialog with no progress to show and a 120 s timeout behind it (measured; the
+   *  old `state.ts` comment said so in as many words). The row is born `starting` — the rail can
+   *  draw it, the page can open it and file the first message — and when this resolves,
+   *  `#updateSession` broadcasts `ready`, which is also the signal the client drains that queued
+   *  first message on (`state.ts`, `case "session"`).
+   *
+   *  Failure is reported INSIDE the session, never to a caller that has long since answered: the
+   *  status goes `error` with `lastError` (the reason + the agent's stderr tail, delivered while the
+   *  slot is still in the live map so the frame carries it), then the slot is dropped and the row is
+   *  closed. That is what makes 「启动失败 → 因为什么 → 再试一次」 possible at all. */
+  async #startup(live: LiveSession, backend: BackendId, spec: BackendSpec, cwd: string, spawnStarted: number): Promise<void> {
+    const id = live.info.id;
+    const child = live.child;
+    if (!child) return; // the slot was torn down between `create()` returning and this line
     try {
       const conn = new ClientSideConnection(
         () => ({
@@ -439,18 +512,19 @@ export class SessionManager {
       // this method — that is exactly what keeps a per-session pick from being silently undone.
       await this.#applyDefaultMode(live);
       this.#updateSession(live);
-      return live.info;
     } catch (err) {
       child.kill("SIGKILL");
       live.info.status = "error";
       live.info.lastError = errMessage(err) + stderrTail(live);
-      this.#sessions.delete(id); // failed handshake => don't keep zombie session rows
+      // Announce the failure WHILE the slot is still live: `{t:"session"}` is the only frame that
+      // carries `lastError`, and the page needs it to say why nothing came up.
+      this.#updateSession(live);
+      this.#sessions.delete(id); // failed handshake => don't keep a zombie slot
       this.#store.upsertSession({ ...sessionRow(live.info), closedAt: Date.now() });
       this.#noteBackendCheck(String(backend), {
         ok: false, error: live.info.lastError, errorCode: classifyError(err),
         latencyMs: Date.now() - spawnStarted,
       });
-      throw err instanceof Error ? err : new Error(String(err));
     }
   }
 
@@ -690,11 +764,7 @@ export class SessionManager {
     // operator watched their slot flicker into the archive for a second — measured on :8901).
     // Mark the swap BEFORE the signal, so the exit we are causing is not read as a dead agent.
     live.replacing = true;
-    for (const { resolve, timer } of live.pendingPermissions.values()) {
-      clearTimeout(timer);
-      resolve({ outcome: { outcome: "cancelled" } });
-    }
-    live.pendingPermissions.clear();
+    this.#dropPending(live);
     live.busy = false;
     // show the swap honestly: "starting" with no pid, not a pid that is already gone
     live.info.status = "starting";
@@ -826,10 +896,24 @@ export class SessionManager {
     if (!blocks.length) throw new Error("empty prompt");
     // The plan hand-over, owed once per agent process (§7): a restarted agent never knew about the
     // plan, and nothing else on this wire would tell it (ACP has no server->agent state channel).
-    if (s.planReminderPending) {
+    //
+    // It carries a second thing the agent cannot learn on its own: that this session HAS a plan
+    // tool. Its own description says "prefer this over any todo tool", but a runtime that keeps MCP
+    // tools in a lazy-loaded catalog (Hermes) never shows that text to the model unless the model
+    // goes looking — so the plan card stayed empty while the agent kept a todo list only its own
+    // process could see. The nudge therefore has to come from the wire; Studio does the same
+    // (its `task-plan-runs.ts` appends a template to the latest input every turn).
+    //
+    // Read per prompt, and only CONSUME the hand-over when it is actually injected: an operator who
+    // turns the hint off and later back on gets the plan hand-over then, rather than losing it.
+    const hint = this.#planHint();
+    if (hint.on) {
+      const owed = Boolean(s.planReminderPending);
       s.planReminderPending = false;
-      const reminder = this.#planReminder(s);
-      if (reminder) blocks.push(reminder);
+      if (owed || hint.everyTurn) {
+        const reminder = this.#planReminder(s, !owed);
+        if (reminder) blocks.push(reminder);
+      }
     }
     s.turnSeq += 1;
     s.busy = true;
@@ -1166,46 +1250,78 @@ export class SessionManager {
   /** The plan, handed to an agent that just (re)started, as an ACP `resource` content block: a
    *  stable URI plus the steps still owed. The card is fed by the plan OBJECT, but the AGENT's own
    *  copy died with its process — this block is the only thing that tells it the plan exists
-   *  (design-plan-service.md §7). Returns null when there is nothing to hand over: no plan at all,
-   *  or one whose steps are all closed (spending context to say "you are done" is worse than
-   *  saying nothing). */
-  #planReminder(s: LiveSession): unknown | null {
+   *  (design-plan-service.md §7).
+   *
+   *  `perTurn` = this is a mid-conversation nudge (the 每回合 setting), not the once-per-process
+   *  hand-over. It changes only what is worth SAYING: with no plan on the card there is nothing to
+   *  hand over and repeating the introduction every turn would be the noise the operator asked to
+   *  avoid, so a per-turn call with nothing to show returns null. Returns null too when a plan
+   *  exists but every step is closed — spending context to say "you are done" is worse than saying
+   *  nothing. */
+  #planReminder(s: LiveSession, perTurn = false): unknown | null {
     const plan = this.#store.getPlan(s.info.id);
-    if (!plan) return null;
-    const open = plan.items.filter((i) => i.status !== "completed" && i.status !== "cancelled");
-    if (!open.length) return null;
-    const lines = open.map((i) => `- [${i.status}] ${i.content}`).join("\n");
+    const open = plan
+      ? plan.items.filter((i) => i.status !== "completed" && i.status !== "cancelled")
+      : [];
+    if (plan && !open.length) return null;
+    if (!open.length && perTurn) return null;
+
     // How the agent keeps it current depends on which channel it actually has: an agent whose row
     // opted into native frames must use its own todo tool (those frames are what feed the card),
     // while an MCP-driven agent — which is every backend by default, Hermes included — was handed
     // `update_plan` in this very handshake, and its own todo tool does NOT reach the card.
     const mcpDriven = nativePlanSourceOf(this.#specFor(s.info.backend)) === "none";
-    const closing = mcpDriven
-      ? [
-          "Carry on with it, and keep it updated with the `update_plan` tool as you go — that list is",
-          "the ONLY one the cockpit shows the operator, so a built-in todo/checklist tool of yours will",
-          "not be seen there. Mark a step completed once its work is actually verified, and drop or",
-          "cancel what you are no longer doing. If you disagree with an item, change it rather than",
-          "quietly skipping it.",
-        ]
-      : [
-          "Carry on with it, and keep it updated with your own plan/todo tool as you go: mark a step",
-          "completed only once its work is actually verified, and drop or cancel what you are no",
-          "longer doing. If you disagree with an item, change it rather than quietly skipping it.",
-        ];
+    const body: string[] = [];
+
+    if (open.length) {
+      body.push(
+        "This session has an unfinished plan. It is kept by the cockpit and survives your",
+        "restarts; your own in-memory task list does not.",
+        "",
+        ...open.map((i) => `- [${i.status}] ${i.content}`),
+        "",
+      );
+    }
+
+    if (mcpDriven && open.length) {
+      body.push(
+        "Carry on with it, and keep it updated with the `update_plan` tool as you go — that list is",
+        "the ONLY one the cockpit shows the operator, so a built-in todo/checklist tool of yours will",
+        "not be seen there. Mark a step completed once its work is actually verified, and drop or",
+        "cancel what you are no longer doing. If you disagree with an item, change it rather than",
+        "quietly skipping it.",
+      );
+    } else if (mcpDriven) {
+      // No plan yet. This is the case the cockpit used to say NOTHING about — which is exactly why
+      // an agent reached for its own todo list and the card stayed empty: `update_plan`'s own
+      // description ("prefer this over any todo tool") lives on a tool a lazy-loaded MCP catalog
+      // never puts in front of the model. Keep it short; it rides on every first prompt.
+      body.push(
+        "This session has an `update_plan` tool mounted on it (MCP server `agentus_plan`), and the",
+        "plan it holds is the one the operator sees — a todo list of your own is invisible there and",
+        "dies with your process. For anything with more than one step, publish the steps with",
+        "`update_plan` and update it as you go: mark a step completed only once its work is actually",
+        "verified, and drop or cancel what you are no longer doing. If `update_plan` is not in your",
+        "tool list it is deferred — search for `agentus_plan update_plan` to find it, then call it by",
+        "that exact name. A one-step request needs no plan.",
+      );
+    } else if (open.length) {
+      body.push(
+        "Carry on with it, and keep it updated with your own plan/todo tool as you go: mark a step",
+        "completed only once its work is actually verified, and drop or cancel what you are no",
+        "longer doing. If you disagree with an item, change it rather than quietly skipping it.",
+      );
+    } else {
+      // A native-frames backend with nothing to hand over: nothing worth saying.
+      return null;
+    }
+
     return {
       type: "resource",
       resource: {
         uri: `agentus://plan/${s.info.id}`,
         mimeType: "text/plain",
-        text: [
-          "This session has an unfinished plan. It is kept by the cockpit and survives your",
-          "restarts; your own in-memory task list does not.",
-          "",
-          lines,
-          "",
-          ...closing,
-        ].join("\n"),
+        text: body.join("\n"),
       },
       // ACP reserves `_meta` for the client: tagging our own blocks is what lets us tell them from
       // the operator's words later (and strip them from anything we echo back).
@@ -1215,7 +1331,10 @@ export class SessionManager {
 
   async closeSession(sessionId: string): Promise<void> {
     const s = this.#need(sessionId);
-    this.#stop(s, "closed");
+    // Awaited, not fired and forgotten: the row has to be settled (and carry the agent-side id) by the
+    // time the DELETE that asked for this answers, or the page loads a slot the store still calls
+    // `starting`.
+    await this.#stop(s, "closed");
     this.#emitSessions();
   }
 
@@ -1230,7 +1349,7 @@ export class SessionManager {
     const live = this.#sessions.get(id);
     const row = this.#store.getSession(id);
     if (!row) throw new Error(`no such session: ${id}`);
-    if (on && live) this.#stop(live, "archived");
+    if (on && live) await this.#stop(live, "archived");
     this.#store.setArchived(id, on ? Date.now() : null);
     this.#emitSessions();
     return this.#sessions.get(id)?.info ?? this.#coldInfo(id);
@@ -1242,15 +1361,30 @@ export class SessionManager {
    *  `reaped` is its own status on purpose — 「它怎么变冷了」 has three different answers (I closed
    *  it / it crashed / the cockpit reclaimed it for being idle) and a rail that shows one word for
    *  all three teaches the operator to distrust the column. */
-  #stop(live: LiveSession, why: "closed" | "archived" | "reaped"): void {
-    for (const { resolve, timer } of live.pendingPermissions.values()) {
-      clearTimeout(timer);
-      resolve({ outcome: { outcome: "cancelled" } });
+  async #stop(live: LiveSession, why: "closed" | "archived" | "reaped"): Promise<void> {
+    this.#dropPending(live);
+    // A slot can be closed while its handshake is still in flight — `create()` no longer waits for it
+    // (see there). Killing the child on the spot was WRONG in a way the operator would eventually hit:
+    // the agent had already created a session, but the row was written with `acpSessionId: null`, and
+    // `resume()` refuses such a row outright (「was never handed to an agent」) — the slot became a
+    // transcript nobody could ever wake again. So let the startup land first: it is the only thing that
+    // knows the agent-side id, and the child it spawned is the one really there to kill.
+    //
+    // The slot stays in the live map for the duration, on purpose: the child IS alive and about to be
+    // `ready`, and calling it cold while it boots is the mirror-image lie (a cold row that wakes up by
+    // itself). The wait is bounded — see `CLOSE_STARTUP_WAIT_MS`.
+    if (live.startup && live.info.status === "starting") {
+      await Promise.race([
+        live.startup.catch(() => {}),
+        new Promise<void>((r) => { setTimeout(r, CLOSE_STARTUP_WAIT_MS).unref?.(); }),
+      ]);
     }
-    live.pendingPermissions.clear();
-    live.child?.kill("SIGTERM");
-    live.info.status = why === "reaped" ? "reaped" : "closed";
+    // Applied LAST, and only over a non-terminal status: `#startup` writes `ready` when the handshake
+    // lands and `error` (with `lastError`) when it fails — and a handshake that failed on its own has a
+    // better answer than 「closed」, so it keeps it.
+    if (live.info.status !== "error") live.info.status = why === "reaped" ? "reaped" : "closed";
     live.info.pid = null;
+    live.child?.kill("SIGTERM");
     const row = this.#store.getSession(live.info.id);
     if (row) {
       this.#store.upsertSession({
@@ -1371,7 +1505,9 @@ export class SessionManager {
             `[agentus] idle reap: ${s.info.id} (${Math.round(age / 60_000)} min idle, limit ${Math.round(idleMs / 60_000)} min)`,
           );
         }
-        this.#stop(s, "reaped");
+        // Fire and forget: the reaper skips `starting` slots, so there is no in-flight handshake to
+        // wait for here and nothing downstream needs the row settled in this tick.
+        void this.#stop(s, "reaped");
         reaped += 1;
       }
       // Only speak when something changed: a frame every tick would be noise on the socket (and on
@@ -1647,11 +1783,7 @@ export class SessionManager {
     // …and if we are REPLACING this slot's process (restart), the exit is the one we asked for: the
     // slot has not failed, it is coming back on a new child.
     if (live.replacing) return;
-    for (const { resolve, timer } of live.pendingPermissions.values()) {
-      clearTimeout(timer);
-      resolve({ outcome: { outcome: "cancelled" } });
-    }
-    live.pendingPermissions.clear();
+    this.#dropPending(live);
     live.busy = false;
     live.info.status = "error";
     live.info.lastError = `agent process exited (code=${code} sig=${sig})` + stderrTail(live);

package/packages/server/src/index.ts

@@ -1,7 +1,6 @@
 // Agentus server entry: HTTP (REST + static web build) + WebSocket relay.
 // The browser never talks to CLI subprocesses directly (design.md §1).
 import { createServer, type IncomingMessage, type ServerResponse } from "node:http";
-import { createServer as createHttpsServer } from "node:https";
 import type { Duplex } from "node:stream";
 import { createHash, randomUUID } from "node:crypto";
 import { homedir } from "node:os";
@@ -20,7 +19,7 @@ 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, publicSettings, saveAgent, saveCall, savePrefs, saveSettings, saveTheme } from "./settings.js";
+import { agentSettings, initSettings, planHintSettings, publicSettings, saveAgent, saveCall, savePrefs, saveSettings, saveTheme } from "./settings.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";
@@ -31,7 +30,7 @@ const PORT = Number(process.env.AGENTUS_PORT ?? 8788);
 // cwd-relative path would silently open a second database (the operator's slots would
 // "disappear"). Both entry points must land on the same store.
 const HERE = path.dirname(fileURLToPath(import.meta.url)); // …/packages/server/src
-// WHERE STATE LIVES — sqlite, credentials.json, auth.token, tls/, settings.json.
+// WHERE STATE LIVES — sqlite, credentials.json, auth.token, settings.json.
 //   1. `AGENTUS_DATA` when it is set. Every launcher and dev/QA instance pins it, so the
 //      rules below can never move a running install's data out from under it.
 //   2. `~/.agentus` once it holds something, or when there is no repo-side data yet.
@@ -41,7 +40,7 @@ const HERE = path.dirname(fileURLToPath(import.meta.url)); // …/packages/serve
 //      directory won and how to move).
 // NOTHING may write inside node_modules: for an installed package
 // `<pkg>/packages/server/.data` is deleted by the next `npm i -g agentus`, taking the
-// transcript, the login and the TLS key with it.
+// transcript and the login with it.
 const DEFAULT_DATA_DIR = path.join(homedir(), ".agentus");
 const REPO_DATA_DIR = path.resolve(HERE, "../.data");
 const hasData = (dir: string): boolean => {
@@ -69,19 +68,6 @@ const APK_FILE = process.env.AGENTUS_APK
     path.join(DATA_DIR, "agentus-companion.apk"),
   ].find((p) => fs.existsSync(p))
   ?? path.resolve(HERE, "../../../android/artifacts/agentus-companion.apk");
-// Optional second listener, TLS (see the block right before listen). Declared up here
-// because the request handler also serves the public cert — a phone that has to trust a
-// self-signed issuer needs to fetch the cert from somewhere, and that somewhere should
-// not require already trusting it.
-//   AGENTUS_TLS_PORT=0  -> off;  no cert on disk -> off (the LAN listener is unaffected).
-const TLS_PORT = Number(process.env.AGENTUS_TLS_PORT ?? 8443);
-const TLS_CERT = process.env.AGENTUS_TLS_CERT ?? path.join(DATA_DIR, "tls", "cert.pem");
-const TLS_KEY = process.env.AGENTUS_TLS_KEY ?? path.join(DATA_DIR, "tls", "key.pem");
-// The issuer a device installs once (make-cert.sh: long-lived root + short-lived leaf).
-// Falls back to the leaf itself for a single self-signed cert from an older setup.
-const TLS_CA = process.env.AGENTUS_TLS_CA ?? path.join(DATA_DIR, "tls", "ca.pem");
-const TLS_READY = TLS_PORT > 0 && fs.existsSync(TLS_CERT) && fs.existsSync(TLS_KEY);
-
 // `agentus --where` (bin/agentus.mjs) asks the ONE place that decides these paths to say
 // what it decided, then exits — before any listener, store or subprocess exists. Print and
 // exit here rather than re-deriving the same rules in the CLI: "where is my data" must not
@@ -92,12 +78,11 @@ if (process.env.AGENTUS_PRINT_PATHS) {
   console.log(`[agentus] data dir      ${DATA_DIR}  (${DATA_DIR_SOURCE})`);
   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] tls listener  ${TLS_READY ? `on :${TLS_PORT} (${TLS_CERT})` : `off (AGENTUS_TLS_PORT=${TLS_PORT}, cert ${has(TLS_CERT)})`}`);
   console.log(`[agentus] http port     ${PORT}`);
   process.exit(0);
 }
 
-fs.mkdirSync(DATA_DIR, { recursive: true, mode: 0o700 }); // 0700: credentials + TLS key live here
+fs.mkdirSync(DATA_DIR, { recursive: true, mode: 0o700 }); // 0700: credentials live here
 const store = new Store(path.join(DATA_DIR, "agentus.sqlite"));
 // M6: an existing cockpit must behave exactly as before, so the registry starts as a copy of
 // the builtin (env-driven) rows and the operator edits from there. Seeding is one-shot: an
@@ -223,16 +208,25 @@ notify.onAction(({ ref, action, activity, device }) => {
   console.log(`[notify] action device=${device.name} activity=${activity.activityId} action=${action.actionId} type=${ref?.type ?? "none"}`);
   if (!ref) return; // the button existed but nobody claimed it: log and drop, never guess
   switch (ref.type) {
-    case "permission":
+    case "permission": {
       // The lock screen answering an agent's permission prompt — the whole point of the channel.
-      mgr.respondPermission(String(ref.sessionId), String(ref.requestId), {
+      const applied = mgr.respondPermission(String(ref.sessionId), String(ref.requestId), {
         outcome: "selected",
         optionId: String(ref.optionId),
       }, {
         optionKind: typeof ref.optionKind === "string" ? ref.optionKind : undefined,
         signature: typeof ref.signature === "string" ? ref.signature : undefined,
       });
+      // The request is gone (our timeout, the agent gave up, its process died). Take the card off
+      // the phone instead of leaving a 「待你确认」 that no longer has a request behind it — the
+      // browser gets `permission-expired` for the same click, and a phone that keeps a dead button
+      // is the same defect one device over.
+      if (!applied) {
+        console.log(`[notify] permission answer dropped for ${ref.requestId}: card dismissed`);
+        notify.dismiss(`perm:${ref.requestId}`);
+      }
       return;
+    }
     case "open":
       return; // the app already opened the deeplink; nothing to do server-side
     default:
@@ -240,6 +234,19 @@ notify.onAction(({ ref, action, activity, device }) => {
   }
 });
 
+// The page channel of the same decision: one `notify` frame to every cockpit websocket.
+//
+// No cursor, no replay, and no per-client state — deliberately unlike the device socket above. The
+// phone replays because it was PAIRED and may have been asleep in a pocket; a browser tab that missed
+// frames has a transcript to catch up in, and a wall of stale cards after a reload is worse than none.
+// Every gate that matters (which kinds, whether the channel is on) was applied in the notify centre.
+notify.onNotice((notice) => {
+  const wire = JSON.stringify({ t: "notify", notice });
+  for (const { ws } of clients.values()) {
+    if (ws.readyState === WebSocket.OPEN) ws.send(wire);
+  }
+});
+
 // Operator settings (voice, theme, call knobs, talk-to-agent prefs) live in the store's
 // `settings` table: the UI owns them and env only bootstraps them (settings.ts). Read
 // before anything asks.
@@ -291,6 +298,9 @@ setHotwordSource((sessionId) => hotwordsFor(store, sessionId).map((h) => h.word)
       envWarmTtlMs != null ? envWarmTtlMs / 3_600_000 : agentSettings().warmTtlHours
     } h untouched (${envWarm != null || envWarmTtlMs != null ? "AGENTUS_WARM_*" : "settings.agent"}), 0 = off / never`,
   );
+  // 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);
   mgr.startIdleReaper({
     idleMs: () => envIdleMs ?? agentSettings().idleKillMin * 60_000,
     warmSlots: () => envWarm ?? agentSettings().warmSlots,
@@ -408,9 +418,10 @@ function serveStatic(req: IncomingMessage, res: ServerResponse): void {
   fs.createReadStream(file).pipe(res);
 }
 
-// One request handler, two listeners: plain HTTP on PORT (LAN, loopback, curl/scripts)
-// and TLS on TLS_PORT (the port a public tunnel points at). Shared on purpose — auth,
-// routes and static serving must not drift between the two.
+// One request handler, plain HTTP on PORT (LAN, loopback, curl/scripts).
+// TLS is NOT terminated in-process: put a TLS-terminating reverse proxy (or a tunnel that
+// does its own `public_tls`) in FRONT of this port. That keeps the LAN path warning-free
+// and `curl`/scripts byte-identical, and keeps cert lifecycle out of the app.
 const handleRequest = async (req: IncomingMessage, res: ServerResponse) => {
   const url = new URL(req.url ?? "/", "http://x");
   try {
@@ -452,24 +463,6 @@ const handleRequest = async (req: IncomingMessage, res: ServerResponse) => {
       return res.end("Agentus: authentication required\n");
     }
 
-    // GET /cert.crt — the ISSUER to install into a phone's trust store (the "proceed
-    // anyway" click, once per device, is the whole cost of TOFU; this makes it a download).
-    // With make-cert.sh's root+leaf setup this is the root, so the leaf can be rotated
-    // yearly without every device having to re-install.
-    // PUBLIC material only: the key never leaves <DATA>/tls/.
-    if (url.pathname === "/cert.crt") {
-      if (!TLS_READY) return send(res, 404, { error: "tls is off on this server" });
-      const der = fs.readFileSync(fs.existsSync(TLS_CA) ? TLS_CA : TLS_CERT);
-      res.writeHead(200, {
-        // Apple's installer claims this type and opens the profile flow directly;
-        // Android/Chrome just downloads the file.
-        "content-type": "application/x-x509-ca-cert",
-        "content-disposition": 'attachment; filename="agentus.crt"',
-        "content-length": String(der.length),
-      });
-      return res.end(der);
-    }
-
     // ---- the phone's onboarding page + the APK, both behind the operator login ----------
     // The pairing code lives on this page, so it is NOT public: an unauthenticated visitor is
     // sent to the login screen (the SPA at /) and comes back with a session cookie.
@@ -1250,7 +1243,14 @@ async function post(path){const r=await fetch(path,{method:'POST'});alert(r.ok?'
         const html = fs.readFileSync(path.join(WEB_DIST, "index.html"), "utf8");
         asset = html.match(/\/assets\/index-([A-Za-z0-9_-]+)\.js/)?.[1] ?? null;
       } catch { /* no build on disk (dev server without dist) */ }
-      return send(res, 200, { asset });
+      // …and `dev`: WHICH INSTANCE this is. Only two things in the UI care, and both are about
+      // keeping a QA backend out of the operator's way — the mock agent shows up in the new-session
+      // form on a dev instance only. The marker is the dev runner's own environment (`DEV_TREE`,
+      // written by scripts/dev.sh; also AGENTUS_DEV=1 for a launcher of one's own); the live
+      // launcher sets neither, so live answers false. An instance-level fact, so it rides the
+      // endpoint that already describes the instance rather than every backend row.
+      const dev = Boolean(process.env.DEV_TREE) || process.env.AGENTUS_DEV === "1";
+      return send(res, 200, { asset, dev });
     }
     if (url.pathname.startsWith("/api/")) return send(res, 404, { error: "not_found" });
     return serveStatic(req, res);
@@ -1269,8 +1269,7 @@ const httpServer = createServer(handleRequest);
 // it becomes a socket. A browser cannot set headers on a WS handshake, so auth
 // rides on the cookie (sent automatically, same-origin) — or ?token= for scripts.
 const wss = new WebSocketServer({ noServer: true });
-// Bound to BOTH listeners (see the TLS block before listen): a browser on the TLS port
-// needs its wss sockets too, and this handler reads the cookie / ?token=, never the scheme.
+// Bound to the single HTTP listener; this handler reads the cookie / ?token=, never the scheme.
 const handleUpgrade = (req: IncomingMessage, socket: Duplex, head: Buffer) => {
   const url = new URL(req.url ?? "/", "http://x");
   // The companion's socket carries its own device token in the query — a phone cannot set
@@ -1596,25 +1595,6 @@ httpServer.listen(PORT, "0.0.0.0", () => {
     );
   }
 });
-// ---- optional TLS listener (self-signed) ----
-// A tunnel that terminates on the public internet must NOT be plain HTTP: the login
-// password and the session cookie would cross it in the clear. SEPARATE from PORT on
-// purpose, so the LAN path stays plain HTTP — no cert warning in the house, curl
-// unchanged. (Config constants live at the top, next to the other paths.)
-if (TLS_READY) {
-  const httpsServer = createHttpsServer({ cert: fs.readFileSync(TLS_CERT), key: fs.readFileSync(TLS_KEY) }, handleRequest);
-  httpsServer.on("upgrade", handleUpgrade);
-  httpsServer.listen(TLS_PORT, "0.0.0.0", () => {
-    console.log(`[agentus-server] https://0.0.0.0:${TLS_PORT} (self-signed, SAN ${TLS_CERT} — point a public tunnel at THIS port; ${PORT} stays for the LAN)`);
-  });
-  // A busy TLS port must not take the LAN listener down with it: log, keep serving.
-  httpsServer.on("error", (err) => {
-    console.error(`[agentus-server] tls listener failed on ${TLS_PORT}: ${(err as Error).message}`);
-  });
-} else if (TLS_PORT > 0) {
-  console.log(`[agentus-server] tls off: no cert at ${TLS_CERT} (create it with scripts/make-cert.sh, or set AGENTUS_TLS_PORT=0)`);
-}
-
 httpServer.on("error", (err) => {
   console.error(`[agentus] cannot listen on ${PORT}: ${(err as Error).message}`);
   process.exit(1); // fail fast: never linger as a listener-less zombie