switchroom 0.18.6 → 0.18.8

package/telegram-plugin/tests/gateway-session-model-relaunch.test.ts

@@ -1,13 +1,15 @@
 /**
- * Structural pins for the session-only model relaunch wiring in gateway.ts.
+ * Structural pins for the session-model stickiness wiring in gateway.ts
+ * (reference/rfcs/session-model-stickiness.md).
  *
  * The behaviour lives in un-exported inline closures (buildModelDeps's
- * scheduleModelRelaunch, the model-menu callback sr-* branch, and the boot
- * re-hydration / alert-sentinel block inside the startup IIFE), so — mirroring
- * the other gateway-*.test.ts source-pins — we assert on the source structure.
- * The end-to-end behaviour of the carrier itself is exercised in
- * tests/scaffold.session-model-override.test.ts (rendered start.sh) and the
- * handler contract in telegram-plugin/tests/model-command.test.ts.
+ * scheduleModelRelaunch/scheduleRestart, triggerSelfRestart, the /restart and
+ * /new handlers, the model-menu callback branches, and the boot re-hydration
+ * block inside the startup IIFE), so — mirroring the other gateway-*.test.ts
+ * source-pins — we assert on the source structure. The end-to-end behaviour
+ * of the boot resolver is exercised in tests/scaffold.session-model.test.ts
+ * (rendered start.sh), the file helpers in session-model-file.test.ts, and
+ * the handler contract in model-command.test.ts.
  */
 
 import { describe, it, expect } from 'vitest'
@@ -18,52 +20,199 @@ import { dirname, resolve } from 'node:path'
 const __dirname = dirname(fileURLToPath(import.meta.url))
 const GATEWAY_SRC = readFileSync(resolve(__dirname, '..', 'gateway', 'gateway.ts'), 'utf8')
 
-describe('gateway: scheduleModelRelaunch dep', () => {
-  it('writes the carrier with exact "<model>\\n" bytes', () => {
+describe('gateway: triggerSelfRestart stamps relaunch-model intent BEFORE the kill', () => {
+  it('docker branch: writeRelaunchModelIntent(intentForRestartReason(reason)) precedes the SIGTERM scheduling', () => {
+    const fnIdx = GATEWAY_SRC.indexOf('function triggerSelfRestart(')
+    expect(fnIdx).toBeGreaterThan(0)
+    const win = GATEWAY_SRC.slice(fnIdx, fnIdx + 3000)
+    const writeIdx = win.indexOf('writeRelaunchModelIntent(smDir, intentForRestartReason(reason), reason)')
+    const killIdx = win.indexOf("process.kill(1, 'SIGTERM')")
+    // Write-before-kill invariant: boot default is REVERT, so the intent must
+    // be on disk synchronously before the SIGTERM is even scheduled.
+    expect(writeIdx).toBeGreaterThan(0)
+    expect(killIdx).toBeGreaterThan(writeIdx)
+    // And before the setTimeout that schedules it.
+    const timeoutIdx = win.indexOf('setTimeout(')
+    expect(timeoutIdx).toBeGreaterThan(writeIdx)
+  })
+
+  it('legacy systemd branch stamps intent too (self-target only)', () => {
+    const fnIdx = GATEWAY_SRC.indexOf('function triggerSelfRestart(')
+    const win = GATEWAY_SRC.slice(fnIdx, fnIdx + 4200)
+    const legacyIdx = win.indexOf('// Legacy systemd path.')
+    expect(legacyIdx).toBeGreaterThan(0)
+    const legacyWin = win.slice(legacyIdx)
+    expect(legacyWin).toContain('writeRelaunchModelIntent(smDir, intentForRestartReason(reason), reason)')
+    expect(legacyWin.indexOf('writeRelaunchModelIntent')).toBeLessThan(legacyWin.indexOf('spawn('))
+  })
+})
+
+describe('gateway: scheduleModelRelaunch dep (durable .session-model)', () => {
+  it('writes the durable file via writeSessionModelFile before dispatching the restart', () => {
     const idx = GATEWAY_SRC.indexOf('scheduleModelRelaunch: async')
     expect(idx).toBeGreaterThan(0)
-    const win = GATEWAY_SRC.slice(idx, idx + 900)
-    expect(win).toMatch(/writeFileSync\(\s*join\(agentDir, '\.session-model-override'\),\s*`\$\{model\}\\n`/)
+    const win = GATEWAY_SRC.slice(idx, idx + 1800)
+    const writeIdx = win.indexOf('writeSessionModelFile(')
+    const restartIdx = win.indexOf('deps.scheduleRestart(reason)')
+    expect(writeIdx).toBeGreaterThan(0)
+    expect(restartIdx).toBeGreaterThan(writeIdx)
   })
 
-  it('sets the in-memory activeSessionModelOverride before dispatching the restart', () => {
+  it('sets the in-memory session-model override before dispatching the restart', () => {
     const idx = GATEWAY_SRC.indexOf('scheduleModelRelaunch: async')
-    const win = GATEWAY_SRC.slice(idx, idx + 900)
-    const setIdx = win.indexOf('activeSessionModelOverride = model')
+    const win = GATEWAY_SRC.slice(idx, idx + 1800)
+    const setIdx = win.indexOf('sessionModelSource.setOverride(model)')
     const restartIdx = win.indexOf('deps.scheduleRestart(reason)')
     expect(setIdx).toBeGreaterThan(0)
     expect(restartIdx).toBeGreaterThan(setIdx)
   })
 
+  it('rolls back the prior file content (not just deletion) on a non-in-flight dispatch failure', () => {
+    const idx = GATEWAY_SRC.indexOf('scheduleModelRelaunch: async')
+    const win = GATEWAY_SRC.slice(idx, idx + 1800)
+    expect(win).toContain('const prevFileRaw = readSessionModelFileRaw(agentDir)')
+    expect(win).toContain('restoreSessionModelFileRaw(agentDir, prevFileRaw)')
+    expect(win).toContain("!== 'restart_in_flight'")
+  })
+
+  it('the non-in-flight rollback ALSO clears the keep-intent (a live intent with no restart coming would wrongly KEEP across a crash)', () => {
+    const idx = GATEWAY_SRC.indexOf('scheduleModelRelaunch: async')
+    const win = GATEWAY_SRC.slice(idx, idx + 2400)
+    const inFlightIdx = win.indexOf("!== 'restart_in_flight'")
+    const clearIdx = win.indexOf('clearRelaunchModelIntent(agentDir)')
+    expect(inFlightIdx).toBeGreaterThan(0)
+    expect(clearIdx).toBeGreaterThan(inFlightIdx)
+  })
+
   it('reuses the same scheduleRestart dispatch (not a bespoke restart path)', () => {
     const idx = GATEWAY_SRC.indexOf('scheduleModelRelaunch: async')
-    const win = GATEWAY_SRC.slice(idx, idx + 900)
+    const win = GATEWAY_SRC.slice(idx, idx + 1800)
     expect(win).toContain('await deps.scheduleRestart(reason)')
   })
 })
 
-describe('gateway: model-menu sr-* target relaunches via the carrier', () => {
+describe('gateway: intent writers on the restart verbs', () => {
+  it('model-switch scheduleRestart stamps keep-intent before the hostd dispatch', () => {
+    const idx = GATEWAY_SRC.indexOf('scheduleRestart: async (reason: string)')
+    expect(idx).toBeGreaterThan(0)
+    const win = GATEWAY_SRC.slice(idx, idx + 3200)
+    const keepIdx = win.indexOf("writeRelaunchModelIntent(smDir, 'keep', reason)")
+    const dispatchIdx = win.indexOf("op: 'agent_restart'")
+    expect(keepIdx).toBeGreaterThan(0)
+    expect(dispatchIdx).toBeGreaterThan(keepIdx)
+  })
+
+  it('scheduleRestart clears the keep-intent when hostd refuses (failed dispatch → no live intent on disk)', () => {
+    const idx = GATEWAY_SRC.indexOf('scheduleRestart: async (reason: string)')
+    const win = GATEWAY_SRC.slice(idx, idx + 3200)
+    const failIdx = win.indexOf('hostd restart failed')
+    const clearIdx = win.indexOf('clearRelaunchModelIntent(smDir)')
+    expect(clearIdx).toBeGreaterThan(0)
+    expect(failIdx).toBeGreaterThan(clearIdx) // cleared before the throw's message
+    // And it sits in the same error branch as clearRestartMarker.
+    const markerIdx = win.indexOf('clearRestartMarker()')
+    expect(clearIdx).toBeGreaterThan(markerIdx)
+  })
+
+  it('/restart stamps an explicit revert intent (reason honesty) before dispatch', () => {
+    const idx = GATEWAY_SRC.indexOf("stampUserRestartReason('user: /restart from chat')")
+    expect(idx).toBeGreaterThan(0)
+    const win = GATEWAY_SRC.slice(idx, idx + 900)
+    const revertIdx = win.indexOf("writeRelaunchModelIntent(smDir, 'revert', 'user: /restart from chat')")
+    const dispatchIdx = win.indexOf("hostdRequestId('gw-restart')")
+    expect(revertIdx).toBeGreaterThan(0)
+    expect(dispatchIdx).toBeGreaterThan(revertIdx)
+  })
+
+  it('/new and /reset stamp keep-intent (fresh conversation, same model — contract row 7)', () => {
+    const idx = GATEWAY_SRC.indexOf('stampUserRestartReason(`user: /${kind} from chat`)')
+    expect(idx).toBeGreaterThan(0)
+    const win = GATEWAY_SRC.slice(idx, idx + 700)
+    const keepIdx = win.indexOf("writeRelaunchModelIntent(agentDir, 'keep', `user: /${kind} from chat`)")
+    const dispatchIdx = win.indexOf('tryHostdDispatch')
+    expect(keepIdx).toBeGreaterThan(0)
+    expect(dispatchIdx).toBeGreaterThan(keepIdx)
+  })
+})
+
+describe('gateway: model-menu callback persists the sticky override', () => {
+  it('a confirmed selection persists the canonical token (selectedModelToken), never the display label', () => {
+    const idx = GATEWAY_SRC.indexOf('const outcome = await handleModelMenuCallback(data, modelDeps)')
+    expect(idx).toBeGreaterThan(0)
+    const win = GATEWAY_SRC.slice(idx, idx + 1600)
+    expect(win).toContain('outcome.selectedModelToken')
+    expect(win).toMatch(/writeSessionModelFile\(\s*smDir,\s*outcome\.selectedModelToken/)
+  })
+
+  it('a confirmed "Default" selection CLEARS the sticky file', () => {
+    const idx = GATEWAY_SRC.indexOf('const outcome = await handleModelMenuCallback(data, modelDeps)')
+    const win = GATEWAY_SRC.slice(idx, idx + 1800)
+    expect(win).toContain('outcome.clearedDefault')
+    expect(win).toContain('clearSessionModelFile(smDir)')
+  })
+
   it('the sr-* callback branch calls scheduleModelRelaunch, not inject', () => {
     const idx = GATEWAY_SRC.indexOf('if (data.startsWith(MODEL_CALLBACK_SR))')
     expect(idx).toBeGreaterThan(0)
     const win = GATEWAY_SRC.slice(idx, idx + 1400)
     expect(win).toContain('modelDeps.scheduleModelRelaunch(srName')
-    // It must return before falling through to handleModelMenuCallback (which
-    // would inject an sr-* id claude's picker rejects).
     expect(win).toMatch(/scheduleModelRelaunch[\s\S]*?\n\s*return\n/)
   })
+
+  it('the sr-to-claude transition writes the durable file (and clears it on a Default tap)', () => {
+    const idx = GATEWAY_SRC.indexOf('isSrToClaudeTransition(prevSessionModel, outcome.selectedModel)')
+    expect(idx).toBeGreaterThan(0)
+    const win = GATEWAY_SRC.slice(idx, idx + 3600)
+    expect(win).toMatch(/writeSessionModelFile\(\s*agentDir,\s*token/)
+    expect(win).toContain('clearSessionModelFile(agentDir)')
+    // Restart rides triggerSelfRestart with a keep-classified reason.
+    expect(win).toContain("triggerSelfRestart(agentName, 'sr-to-claude-model-switch'")
+  })
 })
 
-describe('gateway boot: session-model re-hydration + LiteLLM-down alert', () => {
-  it('re-hydrates activeSessionModelOverride from .active-session-model', () => {
+describe('gateway: typed /model persists the REQUESTED canonical token', () => {
+  it('persists expandSrAlias(parsed.model), and `/model default` clears file + in-memory override', () => {
+    const idx = GATEWAY_SRC.indexOf("const requested = parsed.kind === 'set' ? expandSrAlias(parsed.model) : null")
+    expect(idx).toBeGreaterThan(0)
+    const win = GATEWAY_SRC.slice(idx, idx + 2400)
+    expect(win).toContain("requested?.toLowerCase() === 'default'")
+    expect(win).toContain('sessionModelSource.setOverride(null)')
+    expect(win).toContain('clearSessionModelFile(smDir)')
+    // Non-default: the requested token (shape-gated, non-sr) is what persists.
+    expect(win).toContain('isValidModelArg(requested) && !isSrModel(requested)')
+    expect(win).toMatch(/writeSessionModelFile\(\s*smDir,\s*requested/)
+  })
+
+  it('`/model default` file-clear is NOT gated on a positive confirmation (silent-switch path must not resurrect)', () => {
+    const idx = GATEWAY_SRC.indexOf("const requested = parsed.kind === 'set' ? expandSrAlias(parsed.model) : null")
+    const win = GATEWAY_SRC.slice(idx, idx + 2400)
+    // The default branch clears the file unconditionally, and only the
+    // in-memory override change is confirmation-gated inside it.
+    const clearIdx = win.indexOf('if (smDir) clearSessionModelFile(smDir)')
+    const gatedOverrideIdx = win.indexOf('if (reply.selectedModel) sessionModelSource.setOverride(null)')
+    expect(clearIdx).toBeGreaterThan(0)
+    expect(gatedOverrideIdx).toBeGreaterThan(clearIdx)
+    // And the whole default branch is not nested in an `if (reply.selectedModel)` block:
+    const between = win.slice(0, clearIdx)
+    expect(between).not.toContain('if (reply.selectedModel) {')
+  })
+
+  it('a persist failure is surfaced ON THE REPLY, not just stderr (typed + menu paths)', () => {
+    expect(GATEWAY_SRC.match(/won’t survive a relaunch/g)?.length ?? 0).toBeGreaterThanOrEqual(2)
+    const typedIdx = GATEWAY_SRC.indexOf('persistWarning =')
+    expect(typedIdx).toBeGreaterThan(0)
+    expect(GATEWAY_SRC).toContain('reply.text + persistWarning')
+    // Menu path appends onto the outgoing card text.
+    expect(GATEWAY_SRC).toContain('outcome.reply.text +=')
+  })
+})
+
+describe('gateway boot: session-model re-hydration + alert relay', () => {
+  it('re-hydrates the override from .active-session-model', () => {
     const idx = GATEWAY_SRC.indexOf("join(smAgentDir, '.active-session-model')")
     expect(idx).toBeGreaterThan(0)
     const win = GATEWAY_SRC.slice(idx - 200, idx + 1400)
-    // Only an override when the launched model differs from the configured one.
     expect(win).toMatch(/launched\.length > 0 && launched !== configured \? launched : null/)
-    // The configured value must be resolved through resolveMainModel (the SAME
-    // resolver start.sh's scaffold uses) so an unset/`default` model config does
-    // not get flagged as a phantom session override on an ordinary restart.
     expect(win).toContain('resolveMainModel(raw ?? undefined)')
   })
 
@@ -72,10 +221,15 @@ describe('gateway boot: session-model re-hydration + LiteLLM-down alert', () =>
     expect(idx).toBeGreaterThan(0)
     const win = GATEWAY_SRC.slice(idx, idx + 1100)
     expect(win).toContain('unlinkSync(alertPath)')
-    // Broadcasts to every operator in allowFrom, not just allowFrom[0].
     expect(win).toContain('const operators = loadAccess().allowFrom')
     expect(win).toContain('for (const operator of operators)')
     expect(win).toContain('lockedBot.api')
     expect(win).toContain('.sendMessage(operator')
   })
 })
+
+describe('gateway: the legacy one-shot carrier is no longer written', () => {
+  it('no gateway code writes .session-model-override anymore (start.sh migration shim only reads it)', () => {
+    expect(GATEWAY_SRC).not.toMatch(/writeFileSync\([^)]*\.session-model-override/)
+  })
+})

package/telegram-plugin/tests/ipc-server-query-pending-permission.test.ts

@@ -0,0 +1,157 @@
+/**
+ * Issue #2971 — gateway-side handler for `query_pending_permission`, the
+ * read-only wedge-watchdog probe that lets the permission-prompt branch
+ * defer to a live Telegram approval card instead of racing it with Esc.
+ *
+ * Exercises the REAL createIpcServer over a real (tmp) unix socket with a
+ * raw `net.createConnection` client — the same transport the sidecar's
+ * `permission-pending-query.ts` module uses (no bridge/register handshake
+ * required; this message can be sent by ANY process inside the container,
+ * same trust model as `quota_wall_detected`).
+ */
+import { describe, it, expect, afterEach } from "vitest";
+import { createConnection } from "node:net";
+import { mkdtempSync } from "node:fs";
+import { join } from "node:path";
+import { tmpdir } from "node:os";
+import { createIpcServer, type IpcServer, type IpcClient } from "../gateway/ipc-server.js";
+import { validateClientMessage } from "../gateway/ipc-server.js";
+import type { QueryPendingPermissionMessage } from "../gateway/ipc-protocol.js";
+
+function tmpSocket(): string {
+  const dir = mkdtempSync(join(tmpdir(), "ipc-qpp-test-"));
+  return join(dir, "test.sock");
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((r) => setTimeout(r, ms));
+}
+
+/** Send one query and collect every `pending_permission_status` reply line. */
+function queryOnce(socketPath: string, agentName: string, correlationId: string): Promise<any> {
+  return new Promise((resolve, reject) => {
+    const sock = createConnection(socketPath);
+    let buffer = "";
+    sock.on("connect", () => {
+      sock.write(JSON.stringify({ type: "query_pending_permission", agentName, correlationId } as QueryPendingPermissionMessage) + "\n");
+    });
+    sock.on("data", (chunk) => {
+      buffer += chunk.toString("utf8");
+      const idx = buffer.indexOf("\n");
+      if (idx >= 0) {
+        const line = buffer.slice(0, idx);
+        sock.end();
+        resolve(JSON.parse(line));
+      }
+    });
+    sock.on("error", reject);
+  });
+}
+
+describe("validateClientMessage — query_pending_permission (#2971)", () => {
+  it("accepts a well-formed query", () => {
+    expect(
+      validateClientMessage({ type: "query_pending_permission", agentName: "carrie", correlationId: "abc" }),
+    ).toBe(true);
+  });
+
+  it("rejects missing/malformed agentName", () => {
+    expect(validateClientMessage({ type: "query_pending_permission", correlationId: "abc" })).toBe(false);
+    expect(validateClientMessage({ type: "query_pending_permission", agentName: "", correlationId: "abc" })).toBe(false);
+    expect(validateClientMessage({ type: "query_pending_permission", agentName: "Bad Name", correlationId: "abc" })).toBe(false);
+  });
+
+  it("rejects missing/oversized correlationId", () => {
+    expect(validateClientMessage({ type: "query_pending_permission", agentName: "carrie" })).toBe(false);
+    expect(validateClientMessage({ type: "query_pending_permission", agentName: "carrie", correlationId: "" })).toBe(false);
+    expect(
+      validateClientMessage({ type: "query_pending_permission", agentName: "carrie", correlationId: "x".repeat(65) }),
+    ).toBe(false);
+  });
+});
+
+describe("ipc-server — onQueryPendingPermission handler (#2971)", () => {
+  const servers: IpcServer[] = [];
+
+  afterEach(async () => {
+    for (const s of servers) await s.close();
+    servers.length = 0;
+  });
+
+  it("fails CLOSED (pending:false) when no handler is wired — mixed-version-safe default", async () => {
+    const socketPath = tmpSocket();
+    const server = createIpcServer({
+      socketPath,
+      onClientRegistered: () => {},
+      onClientDisconnected: () => {},
+      onToolCall: async () => ({ type: "tool_call_result", id: "x", success: true }),
+      onSessionEvent: () => {},
+      onPermissionRequest: () => {},
+      onHeartbeat: () => {},
+      onScheduleRestart: () => {},
+      // onQueryPendingPermission intentionally omitted.
+    });
+    servers.push(server);
+    await wait(50);
+
+    const reply = await queryOnce(socketPath, "carrie", "corr-1");
+    expect(reply).toEqual({ type: "pending_permission_status", correlationId: "corr-1", pending: false });
+  });
+
+  it("invokes the wired handler with the query, and relays its reply", async () => {
+    const socketPath = tmpSocket();
+    let received: QueryPendingPermissionMessage | null = null;
+    const server = createIpcServer({
+      socketPath,
+      onClientRegistered: () => {},
+      onClientDisconnected: () => {},
+      onToolCall: async () => ({ type: "tool_call_result", id: "x", success: true }),
+      onSessionEvent: () => {},
+      onPermissionRequest: () => {},
+      onHeartbeat: () => {},
+      onScheduleRestart: () => {},
+      onQueryPendingPermission: (client: IpcClient, msg: QueryPendingPermissionMessage) => {
+        received = msg;
+        client.send({
+          type: "pending_permission_status",
+          correlationId: msg.correlationId,
+          pending: true,
+          requestId: "req-live-1",
+        });
+      },
+    });
+    servers.push(server);
+    await wait(50);
+
+    const reply = await queryOnce(socketPath, "carrie", "corr-2");
+    expect(received).toEqual({ type: "query_pending_permission", agentName: "carrie", correlationId: "corr-2" });
+    expect(reply).toEqual({
+      type: "pending_permission_status",
+      correlationId: "corr-2",
+      pending: true,
+      requestId: "req-live-1",
+    });
+  });
+
+  it("relays pending:false from a wired handler when nothing is live", async () => {
+    const socketPath = tmpSocket();
+    const server = createIpcServer({
+      socketPath,
+      onClientRegistered: () => {},
+      onClientDisconnected: () => {},
+      onToolCall: async () => ({ type: "tool_call_result", id: "x", success: true }),
+      onSessionEvent: () => {},
+      onPermissionRequest: () => {},
+      onHeartbeat: () => {},
+      onScheduleRestart: () => {},
+      onQueryPendingPermission: (client: IpcClient, msg: QueryPendingPermissionMessage) => {
+        client.send({ type: "pending_permission_status", correlationId: msg.correlationId, pending: false });
+      },
+    });
+    servers.push(server);
+    await wait(50);
+
+    const reply = await queryOnce(socketPath, "carrie", "corr-3");
+    expect(reply).toEqual({ type: "pending_permission_status", correlationId: "corr-3", pending: false });
+  });
+});

package/telegram-plugin/tests/mental-model-name-entity-corruption.test.ts

@@ -0,0 +1,119 @@
+/**
+ * Regression coverage for #2976 — HTML-entity corruption in mental-model
+ * fields, config-write-boundary layer.
+ *
+ * Reachability (stated plainly so these tests don't over-claim):
+ *   - `source_query` decode is the REACHABLE/load-bearing half: a proposal's
+ *     free-form query can carry escaped entities the model copied out of its
+ *     Telegram-HTML context, and undecoded it steers recall on `R&D`
+ *     instead of `R&D`.
+ *   - `name` decode is REDUNDANT with the gateway slug gate
+ *     (/^[a-zA-Z0-9][a-zA-Z0-9_-]{0,63}$/ rejects an entity-bearing name before
+ *     `buildMentalModelAppendDiff` ever runs). It's belt-and-suspenders; the
+ *     name-path tests here exercise the boundary directly (bypassing the gate)
+ *     to prove the normalization, NOT to imply the propose path could carry the
+ *     bug.
+ *   - The observed in-NAME corruption (`Nutrition Protocol & Deficit
+ *     Status`, klanker 2026-07-06) actually arrived via the DIRECT
+ *     `create_mental_model` Hindsight tool, which this PR does not touch — that
+ *     vector is out of scope (steering.ts / Dockerfile.hindsight follow-ups).
+ *
+ * These tests pin the switchroom-owned WRITE-BOUNDARY normalization: name +
+ * source_query are decoded to their literal characters BEFORE synthesis into
+ * the config diff. Each assertion below FAILS against the pre-fix code (which
+ * serialized `spec.name` / `spec.source_query` verbatim) and passes after.
+ */
+
+import { describe, it, expect } from "vitest";
+import { parseDocument } from "yaml";
+import {
+  buildMentalModelAppendDiff,
+  readDeclaredMentalModelNames,
+  decodeCanonicalEntities,
+} from "../gateway/mental-model-propose-diff.js";
+
+const BASE_CONFIG = `agents:
+  klanker:
+    memory:
+      backend: hindsight
+`;
+
+/** Pull the appended model node out of the synthesized `after` config. */
+function appendedModel(after: string, agent = "klanker"): { name?: unknown; source_query?: unknown } {
+  const js = parseDocument(after).toJS() as {
+    agents: Record<string, { memory: { mental_models: Array<Record<string, unknown>> } }>;
+  };
+  const models = js.agents[agent]!.memory.mental_models;
+  return models[models.length - 1]!;
+}
+
+describe("decodeCanonicalEntities — single-pass, canonical six only", () => {
+  it("decodes each canonical entity to its literal character", () => {
+    expect(decodeCanonicalEntities("R&amp;D")).toBe("R&D");
+    expect(decodeCanonicalEntities("a&lt;b&gt;c")).toBe("a<b>c");
+    expect(decodeCanonicalEntities("say &quot;hi&quot;")).toBe('say "hi"');
+    expect(decodeCanonicalEntities("Ken&apos;s")).toBe("Ken's");
+    expect(decodeCanonicalEntities("Ken&#39;s")).toBe("Ken's");
+  });
+
+  it("undoes exactly ONE layer of escaping (double-escaped → single-escaped)", () => {
+    // We only reverse the escaping switchroom applied when rendering the model's
+    // own prior output — never the user's literal intent.
+    expect(decodeCanonicalEntities("R&amp;amp;D")).toBe("R&amp;D");
+    expect(decodeCanonicalEntities("&amp;lt;")).toBe("&lt;");
+  });
+
+  it("leaves entity-free text untouched (idempotent on clean input)", () => {
+    expect(decodeCanonicalEntities("Nutrition Protocol & Deficit")).toBe("Nutrition Protocol & Deficit");
+  });
+});
+
+describe("#2976 — propose write-boundary normalizes the mental-model name", () => {
+  it("stores the LITERAL '&' name, not the escaped '&amp;' the model emitted", () => {
+    const built = buildMentalModelAppendDiff({
+      configText: BASE_CONFIG,
+      agentName: "klanker",
+      spec: { name: "Nutrition Protocol &amp; Deficit Status", source_query: "how is the deficit?" },
+    });
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    expect(appendedModel(built.after).name).toBe("Nutrition Protocol & Deficit Status");
+    // And there is no residual entity anywhere in the persisted config.
+    expect(built.after).not.toContain("&amp;");
+    // Reading the declared names back yields the decoded literal.
+    expect(readDeclaredMentalModelNames(built.after, "klanker")).toContain(
+      "Nutrition Protocol & Deficit Status",
+    );
+  });
+
+  it("normalizes the recall-steering source_query too (not just the name)", () => {
+    const built = buildMentalModelAppendDiff({
+      configText: BASE_CONFIG,
+      agentName: "klanker",
+      spec: { name: "rd-budget", source_query: "what is the user&apos;s R&amp;D budget?" },
+    });
+    expect(built.ok).toBe(true);
+    if (!built.ok) return;
+    expect(appendedModel(built.after).source_query).toBe("what is the user's R&D budget?");
+  });
+
+  it("rejects an entity-escaped re-propose of an already-declared literal name (dup guard on decoded name)", () => {
+    const configWithModel = `agents:
+  klanker:
+    memory:
+      backend: hindsight
+      mental_models:
+        - name: Q3 R&D Plan
+          source_query: what is the plan?
+`;
+    const built = buildMentalModelAppendDiff({
+      configText: configWithModel,
+      agentName: "klanker",
+      // Escaped variant of the same logical name — must collide, not create a twin.
+      spec: { name: "Q3 R&amp;D Plan", source_query: "different query" },
+    });
+    expect(built.ok).toBe(false);
+    if (built.ok) return;
+    expect(built.error).toBe("duplicate");
+  });
+});

package/telegram-plugin/tests/mental-model-propose-callback-gate.test.ts

@@ -41,16 +41,19 @@ describe('handleMentalModelProposeCallback — authorization gate', () => {
 })
 
 describe('handleMentalModelProposeCallback — TTL enforced at tap time', () => {
-  it('checks staged_at against MENTAL_MODEL_PROPOSE_TTL_MS at tap and edits the card away', () => {
+  it('checks staged_at against MENTAL_MODEL_PROPOSE_TTL_MS at tap and routes through the shared expiry path', () => {
     const block = proposeCallbackBlock()
     expect(block).toMatch(/Date\.now\(\) - pending\.staged_at > MENTAL_MODEL_PROPOSE_TTL_MS/)
-    // The expired branch deletes the pending entry and clears the keyboard so a
-    // stale card can't be tapped into an approval.
+    // The expired branch routes through expireMentalModelProposeCard, which
+    // deletes the pending entry, clears the durable store, edits the card away
+    // (keyboard stripped), AND wakes the parked agent with a timeout synthetic —
+    // so a stale card can't be tapped into an approval and the agent isn't left
+    // parked. (The helper's delete/clear/wake behavior is pinned in
+    // pending-card-durability-wiring.test.ts.)
     const ttlBranch =
       block.split('Date.now() - pending.staged_at > MENTAL_MODEL_PROPOSE_TTL_MS')[1]?.split('Single-shot')[0] ?? ''
-    expect(ttlBranch).toMatch(/pendingMentalModelProposes\.delete\(stageId\)/)
+    expect(ttlBranch).toMatch(/expireMentalModelProposeCard\(stageId, pending, Date\.now\(\)\)/)
     expect(ttlBranch).toMatch(/expired/)
-    expect(ttlBranch).toMatch(/inline_keyboard: \[\]/)
   })
 })