switchroom 0.17.5 → 0.17.10

package/telegram-plugin/uat/scenarios/jtbd-liveness-narration-dm.test.ts

@@ -0,0 +1,148 @@
+/**
+ * Narrated mid-turn work still shows words on the card (Phase 4a,
+ * `deterministic-turn-liveness.md`) — DM.
+ *
+ * The Phase-1 climb fills the GAPS the model leaves; it must never regress
+ * the pre-existing narration path (session-tail → gateway `case 'text'` →
+ * `stagePendingNarrative` → `showNarrativeStep` → `appendActivityLabel`).
+ * This scenario proves the model's own narrated steps still land on the
+ * card mid-turn, chronologically interleaved with the climb, when the model
+ * DOES talk (the complement of `jtbd-liveness-climb-dm`, which forces the
+ * model silent).
+ *
+ * IMPORTANT: switchroom has no streaming REPLY path. The words asserted here
+ * land on the pre-existing activity/liveness card (a card-edit surface), not
+ * a streamed reply — the final reply is still sent whole.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+import { isActivityFeedMessage, isFrameworkFallbackText } from "../assertions.js";
+import type { ObservedMessage } from "../driver.js";
+
+/**
+ * Extract the narration/tool body lines of an activity card, dropping the
+ * two-line header (`🤖 Agent` / `<elapsed> · <N> tools`) and the bare
+ * `Working…` placeholder the 0-label climb paints. Whatever remains is
+ * model-authored narration or tool labels — the content this scenario proves
+ * still lands on the card mid-turn.
+ */
+function narratedBodyLines(text: string): string[] {
+  return text
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l.length > 0)
+    // strip glyphs so a `→ Working…` placeholder compares as `Working…`
+    .map((l) => l.replace(/^[→✓↳]+\s*/u, "").trim())
+    .filter(
+      (l) =>
+        l.length > 0 &&
+        // header line 1 (emoji + label, optional description)
+        !/^(?:🤖|🛠[️]?|⚙[️]?)\s/u.test(l) &&
+        // header line 2 (elapsed · tools, running or done)
+        !/^(?:(?:\d+m)?\d+s\s*·\s*\d+\s+tools?|(?:done|failed)\s*·)/iu.test(l) &&
+        // the bare climb placeholder is NOT narration
+        !/^Working(?:\s*[·…]|$)/i.test(l) &&
+        // rolling-overflow header is not narration
+        !/^\+?\d+\s+earlier/i.test(l),
+    );
+}
+
+const OVERALL_BUDGET_MS = 130_000;
+
+const NARRATED_WORK_PROMPT =
+  "Do four short steps, ONE AT A TIME. Before EACH step, write a brief " +
+  'one-sentence narration of what you are about to do (e.g. "Checking the ' +
+  'hostname now.") — this is not a reply, just your normal narration — then ' +
+  "run the step via Bash (`sleep 3` is fine as the step body). After all " +
+  "four steps, send a one-line final summary reply.";
+
+describe("uat: deterministic turn liveness — narration lands mid-turn (DM)", () => {
+  it(
+    "the model's own words appear on the activity card mid-turn (narration not regressed)",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        const iter = sc.driver
+          .observeMessages(sc.botUserId)
+          [Symbol.asyncIterator]();
+
+        await sc.sendDM(NARRATED_WORK_PROMPT);
+        const sentAt = Date.now();
+        console.log("[liveness-narration-dm] prompt sent; watching for narrated card content…");
+
+        const narrationSamples: string[] = [];
+        let answer: ObservedMessage | null = null;
+        let otherLoudMessage: ObservedMessage | null = null;
+
+        const deadline = Date.now() + 90_000;
+        while (Date.now() < deadline) {
+          if (answer) break;
+          const remaining = deadline - Date.now();
+          const next = await Promise.race([
+            iter.next(),
+            new Promise<{ done: true; value: undefined }>((r) =>
+              setTimeout(() => r({ done: true, value: undefined }), Math.max(0, remaining)),
+            ),
+          ]);
+          if (next.done || next.value == null) break;
+          const m = next.value as ObservedMessage;
+          if (m.senderUserId === sc.driverUserId) continue;
+
+          if (isActivityFeedMessage(m)) {
+            // The card carries the two-line header + (climb placeholder |
+            // narrated body). Any body line that ISN'T the header or the bare
+            // "Working…" placeholder is model narration landing mid-turn.
+            const narrated = narratedBodyLines(m.text);
+            if (narrated.length > 0) {
+              narrationSamples.push(narrated.join(" | "));
+              console.log(
+                `[liveness-narration-dm] narrated card content at +${Date.now() - sentAt}ms: ` +
+                  JSON.stringify(narrated.join(" | ").slice(0, 140)),
+              );
+            }
+            if (m.edited && m.silent === false) otherLoudMessage = otherLoudMessage ?? m;
+            continue;
+          }
+          if (m.edited) continue;
+          // A framework fallback TEXT send is a mid-turn erosion, not the
+          // answer — reject it from the answer lane so it trips the assertion.
+          if (isFrameworkFallbackText(m.text)) {
+            otherLoudMessage = otherLoudMessage ?? m;
+            continue;
+          }
+          if (!answer && m.text.trim().length > 0) {
+            answer = m;
+            continue;
+          }
+          if (m.silent === false) otherLoudMessage = otherLoudMessage ?? m;
+        }
+        await iter.return?.();
+
+        expect(
+          otherLoudMessage,
+          `a mid-turn message pinged the user's device: ${JSON.stringify(otherLoudMessage?.text?.slice(0, 120))}`,
+        ).toBeNull();
+
+        if (narrationSamples.length === 0) {
+          console.warn(
+            "[liveness-narration-dm] INCONCLUSIVE — no narrated content observed on the " +
+              "card (model may have batched steps or the turn was too fast). Not " +
+              "necessarily a regression — but worth a human look if this recurs.",
+          );
+        }
+        // (No tautological `expect(narrationSamples.length).toBeGreaterThan(0)`
+        //  in the else-branch — it was asserting a condition the branch already
+        //  guarantees. The meaningful signals are the ping-free assertion above
+        //  and the answer-arrived assertion below; narration presence is
+        //  logged, not force-asserted, since a live model may legitimately
+        //  batch its steps.)
+
+        expect(answer, "FAIL — no answer arrived within budget; the turn may be wedged.").not.toBeNull();
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    OVERALL_BUDGET_MS,
+  );
+});

package/telegram-plugin/uat/scenarios/jtbd-memory-legibility-channel.test.ts

@@ -0,0 +1,66 @@
+/**
+ * Sparse chat-legible memory in a SUPERGROUP (#2849, hindsight Phase 4) — UAT.
+ *
+ * Channel twin of `jtbd-memory-legibility-dm`. A directive stored while the
+ * conversation is happening in a supergroup must surface its `📌 remembered:`
+ * line IN the supergroup — never the operator DM (the known status-routing
+ * bug class). Proves the memory-legibility status surface has DM/channel
+ * parity: it routes on the ORIGINATING topic (`turn.sessionChatId` /
+ * `sessionThreadId`), not the owner DM.
+ *
+ * Self-skips green when no test supergroup is wired (SWITCHROOM_UAT_CHAT_ID
+ * unset or not resolvable). Uses the General topic (mtcute here has no
+ * forum-topic create API).
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+import { expectMessage } from "../assertions.js";
+
+const AGENT = "test-harness";
+const SUPERGROUP_ID = Number.parseInt(process.env.SWITCHROOM_UAT_CHAT_ID ?? "", 10);
+
+const REMEMBER_PROMPT =
+  `Persist this as a standing directive using the ` +
+  `mcp__hindsight__create_directive tool, with the directive content set ` +
+  `to exactly: "Always greet me as Captain at the start of a reply". ` +
+  `Name the directive "greeting-captain". After creating it, send a brief ` +
+  `one-line confirmation.`;
+
+const REMEMBERED_RE = /📌\s*remembered/i;
+
+describe("uat: sparse chat-legible memory in a supergroup (#2849 channel parity)", () => {
+  it(
+    "surfaces the 📌 remembered line IN the supergroup, not the DM",
+    async () => {
+      if (!Number.isFinite(SUPERGROUP_ID)) {
+        console.warn("[memory-legibility channel UAT] SWITCHROOM_UAT_CHAT_ID unset — skipping");
+        return;
+      }
+      const sc = await spinUp({ agent: AGENT, settleMs: 0 });
+      try {
+        await sc.driver.primeDialogs();
+        if (!(await sc.driver.canResolve(SUPERGROUP_ID))) {
+          console.warn(`[memory-legibility channel UAT] supergroup ${SUPERGROUP_ID} not resolvable — skipping`);
+          return;
+        }
+        await sc.driver.sendText(SUPERGROUP_ID, REMEMBER_PROMPT);
+
+        const line = await expectMessage(sc.driver, SUPERGROUP_ID, REMEMBERED_RE, {
+          timeout: 90_000,
+          senderFilter: { notUserId: sc.driverUserId },
+        });
+        console.log(
+          `[memory-legibility channel UAT] remembered line (id=${line.messageId}, chat=${line.chatId}): ${JSON.stringify(line.text)}`,
+        );
+        expect(line.chatId).toBe(SUPERGROUP_ID); // parity proof: in the channel, not the DM
+        expect(line.fromBot).toBe(true);
+        expect(line.messageId).toBeGreaterThan(0);
+        expect(line.text).toMatch(/Captain/i);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    180_000,
+  );
+});

package/telegram-plugin/uat/scenarios/jtbd-memory-legibility-dm.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Sparse chat-legible memory (#2849, hindsight Phase 4) — DM UAT.
+ *
+ * Serves the `remember-across-sessions` job. When the interactive session
+ * stores a new standing directive, ONE terse line must surface in the
+ * originating chat: `📌 remembered: "<directive>"`. It's a REAL message
+ * (sendMessage, not a draft/reaction) so mtcute can observe it. The line
+ * is sparse + material-only — ordinary recall never surfaces one — and is
+ * ON by default (kill-switch SWITCHROOM_MEMORY_LEGIBILITY=0).
+ *
+ * This scenario asks the agent to persist an explicit standing rule via
+ * the create_directive tool, then asserts the 📌 remembered line appears
+ * from the bot in the DM.
+ *
+ * Note: the model must actually call `mcp__hindsight__create_directive`.
+ * The prompt names the tool + the rule verbatim to make the tool call
+ * deterministic. Requires the test-harness agent running an image that
+ * includes #2849.
+ */
+
+import { describe, expect, it } from "vitest";
+import { spinUp } from "../harness.js";
+
+const REMEMBER_PROMPT =
+  `Persist this as a standing directive using the ` +
+  `mcp__hindsight__create_directive tool, with the directive content set ` +
+  `to exactly: "Always greet me as Captain at the start of a reply". ` +
+  `Name the directive "greeting-captain". After creating it, send a brief ` +
+  `one-line confirmation.`;
+
+// The legibility line: `📌 remembered: "<directive body, truncated>"`.
+const REMEMBERED_RE = /📌\s*remembered/i;
+
+describe("uat: sparse chat-legible memory — remembered line (#2849)", () => {
+  it(
+    "surfaces a 📌 remembered line in the DM when a directive is created",
+    async () => {
+      const sc = await spinUp({ agent: "test-harness" });
+      try {
+        await sc.sendDM(REMEMBER_PROMPT);
+
+        // The 📌 remembered line — a real bot message in this DM. May arrive
+        // alongside/near the agent's confirmation reply; generous budget for
+        // the tool round-trip + transcript flush.
+        const line = await sc.expectMessage(REMEMBERED_RE, {
+          from: "bot",
+          timeout: 90_000,
+        });
+        console.log(
+          `[memory-legibility UAT] remembered line (id=${line.messageId}): ${JSON.stringify(line.text)}`,
+        );
+        expect(line.messageId).toBeGreaterThan(0);
+        // The directive body should ride along in the line.
+        expect(line.text).toMatch(/Captain/i);
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    180_000,
+  );
+});

package/telegram-plugin/uat/scenarios/silent-end-recovery-channel.test.ts

@@ -0,0 +1,136 @@
+/**
+ * Silent-end recovery — CHANNEL twin of `silent-end-recovery-dm.test.ts`
+ * (Phase 4a, `deterministic-turn-liveness.md`: the dark-turn guard must
+ * deliver exactly one fallback message on the real surface, in a DM AND a
+ * forum topic alike).
+ *
+ * Phase 2 (already shipped) hardens `recordUndeliveredTurnEnd` /
+ * `SILENT_END_FALLBACK_TEXT` as the ONE deterministic guard for a turn that
+ * ends having delivered no reply. This scenario proves it fires — at most
+ * once — for the same tool-heavy prompt shape, in a supergroup, AND that no
+ * mid-turn device ping is emitted before the terminal reply/fallback (the
+ * ping-free invariant the RFC/job spec claim is inline in every scenario).
+ * The terminal dark-turn fallback itself is a sanctioned loud unwedge send, so
+ * only pings STRICTLY BEFORE the terminal message count as erosion.
+ *
+ * Self-skips green when no test supergroup is wired.
+ */
+
+import { describe, it, expect } from "vitest";
+import { spinUp } from "../harness.js";
+import { expectMessage, isActivityFeedMessage } from "../assertions.js";
+import type { ObservedMessage } from "../driver.js";
+
+const AGENT = "test-harness";
+const SUPERGROUP_ID = Number.parseInt(process.env.SWITCHROOM_UAT_CHAT_ID ?? "", 10);
+
+const TOOL_HEAVY_PROMPT =
+  "Pick a directory under /tmp that doesn't exist yet. Create it. " +
+  "List its contents (should be empty). Write a small file in it. " +
+  "List again. Then report what you did in a one-line reply.";
+
+describe("uat: silent-end recovery (channel parity)", () => {
+  it(
+    "user asks in a supergroup → agent replies exactly once via the fallback ladder if needed, no mid-turn ping",
+    async () => {
+      if (!Number.isFinite(SUPERGROUP_ID)) {
+        console.warn("[silent-end-recovery-channel] SWITCHROOM_UAT_CHAT_ID unset — skipping");
+        return;
+      }
+      const sc = await spinUp({ agent: AGENT, settleMs: 0 });
+      try {
+        await sc.driver.primeDialogs();
+        if (!(await sc.driver.canResolve(SUPERGROUP_ID))) {
+          console.warn(`[silent-end-recovery-channel] supergroup ${SUPERGROUP_ID} not resolvable — skipping`);
+          return;
+        }
+
+        const iter = sc.driver
+          .observeMessages(SUPERGROUP_ID)
+          [Symbol.asyncIterator]();
+
+        await sc.driver.sendText(SUPERGROUP_ID, TOOL_HEAVY_PROMPT);
+        const sentAt = Date.now();
+
+        // Same budget rationale as the DM twin: covers normal latency, one
+        // Stop-hook re-prompt cycle, and the worst-case 300s framework
+        // fallback. We observe the whole window so we can assert the ping-free
+        // invariant BEFORE the terminal reply, not just wait for the reply.
+        let reply: ObservedMessage | null = null;
+        let midTurnPing: ObservedMessage | null = null;
+
+        const deadline = Date.now() + 320_000;
+        while (Date.now() < deadline) {
+          if (reply) break;
+          const remaining = deadline - Date.now();
+          const next = await Promise.race([
+            iter.next(),
+            new Promise<{ done: true; value: undefined }>((r) =>
+              setTimeout(() => r({ done: true, value: undefined }), Math.max(0, remaining)),
+            ),
+          ]);
+          if (next.done || next.value == null) break;
+          const m = next.value as ObservedMessage;
+          if (m.senderUserId === sc.driverUserId) continue;
+
+          // Card edits are the sanctioned mid-turn liveness surface (silent by
+          // construction) — skip them from the ping accounting.
+          if (isActivityFeedMessage(m)) {
+            if (m.edited && m.silent === false) midTurnPing = midTurnPing ?? m;
+            continue;
+          }
+          if (m.edited) continue;
+          // First substantive non-card bot message is the terminal reply
+          // (model answer OR the dark-turn fallback — both terminal, both may
+          // legitimately ping).
+          if (m.text.trim().length > 0) {
+            reply = m;
+            continue;
+          }
+        }
+
+        expect(
+          midTurnPing,
+          `a mid-turn message pinged the device BEFORE the terminal reply in the supergroup: ` +
+            JSON.stringify(midTurnPing?.text?.slice(0, 120)),
+        ).toBeNull();
+
+        expect(reply, "FAIL — no reply arrived within budget; the silent-end guard may have regressed.").not.toBeNull();
+        expect(reply!.text.length).toBeGreaterThan(0);
+        expect(reply!.chatId).toBe(SUPERGROUP_ID);
+        console.log(`[silent-end-recovery-channel] reply at +${Date.now() - sentAt}ms.`);
+
+        if (/no update from agent|didn't send a reply/i.test(reply!.text)) {
+          console.warn(
+            "[silent-end-recovery-channel] reply was the framework/dark-turn fallback — " +
+              `model never replied on its own. Reply text: ${JSON.stringify(reply!.text.slice(0, 200))}`,
+          );
+
+          // Exactly-once proof: no SECOND fallback-shaped message should
+          // follow within a short window (the `exhausted` latch).
+          let secondFallback: ObservedMessage | null = null;
+          try {
+            secondFallback = await expectMessage(
+              sc.driver,
+              SUPERGROUP_ID,
+              /no update from agent|didn't send a reply/i,
+              { timeout: 15_000, senderFilter: { notUserId: sc.driverUserId } },
+            );
+          } catch {
+            // Timeout is the expected/good outcome — no second fallback fired.
+          }
+          expect(
+            secondFallback,
+            "the dark-turn/framework fallback fired MORE than once for the same turn " +
+              "(the `exhausted` latch should give fire-once)",
+          ).toBeNull();
+        }
+
+        await iter.return?.();
+      } finally {
+        await sc.tearDown();
+      }
+    },
+    360_000,
+  );
+});

package/telegram-plugin/uat/scenarios/silent-end-recovery-dm.test.ts

@@ -34,6 +34,7 @@
 
 import { describe, it, expect } from "vitest";
 import { spinUp } from "../harness.js";
+import type { ObservedMessage } from "../driver.js";
 
 // The prompt pushes the model into a tool-heavy state where it has
 // produced "an answer" internally but hasn't yet realised it must
@@ -77,12 +78,33 @@ describe("uat: silent-end recovery", () => {
         // fallback wording ("still working… (no update from agent
         // in N min)") that means the silent-end loop fired AND the
         // model didn't recover. Acceptable outcome — the user got
-        // something — but a design-health alarm. Log it.
-        if (/no update from agent/i.test(reply.text)) {
+        // something — but a design-health alarm. Log it AND assert the
+        // `exhausted` latch gave fire-once (transport-side), matching the
+        // channel twin exactly — the job-spec Prove-it claim is
+        // "asserted transport-side in a DM AND a supergroup alike", so the
+        // DM twin must make the same exactly-once assertion, not just warn.
+        if (/no update from agent|didn't send a reply/i.test(reply.text)) {
           console.warn(
             `[silent-end-recovery] reply was the framework fallback — `
             + `model never replied on its own. Reply text: ${JSON.stringify(reply.text.slice(0, 200))}`,
           );
+
+          // No SECOND fallback-shaped message should follow within a short
+          // window (the `exhausted` latch gives fire-once).
+          let secondFallback: ObservedMessage | null = null;
+          try {
+            secondFallback = await sc.expectMessage(
+              /no update from agent|didn't send a reply/i,
+              { from: "bot", timeout: 15_000 },
+            );
+          } catch {
+            // Timeout is the expected/good outcome — no second fallback fired.
+          }
+          expect(
+            secondFallback,
+            "the dark-turn/framework fallback fired MORE than once for the same turn "
+            + "(the `exhausted` latch should give fire-once)",
+          ).toBeNull();
         }
       } finally {
         await sc.tearDown();

package/telegram-plugin/worktree-watch-cwds.ts

@@ -0,0 +1,60 @@
+/**
+ * Ownership filter for the worktree-isolated cwds the subagent-watcher should
+ * additionally watch (deterministic-turn-liveness.md Known Gap 2 + the #2893
+ * ownership-predicate review fix).
+ *
+ * A sub-agent dispatched into a `switchroom worktree claim` cwd runs under a
+ * different project-dir slug than the agent's own `agentCwd`, so the #1116
+ * foreign-slug filter would skip it forever unless the watcher also watches
+ * the slugs of worktrees THIS agent owns. This helper derives that set from
+ * the host-global worktree registry, and it is deliberately fail-CLOSED:
+ *
+ *   - Unset/empty identity ⇒ contribute NOTHING. `ownerAgent` is optional in
+ *     the registry, so a naive `r.ownerAgent === process.env.SWITCHROOM_AGENT_NAME`
+ *     with the env var unset becomes `undefined === undefined` and matches
+ *     every OWNERLESS record in the host-global registry — including other
+ *     agents' worktrees. That is precisely the #1116 leak the filter exists to
+ *     prevent, reintroduced by failing OPEN. With no identity we cannot prove
+ *     ownership of anything, so we return `[]`.
+ *   - A registry read failure ⇒ `[]` (best-effort; never disturb the base
+ *     agentCwd watch).
+ *   - Owner match ⇒ include, realpath'd. Claude Code mints the project slug off
+ *     the process's PHYSICAL cwd, so a symlinked base (macOS `/tmp` →
+ *     `/private/tmp`) would otherwise derive a slug that misses the physical
+ *     one; realpath best-effort, falling back to the raw path.
+ */
+import { realpathSync } from "node:fs";
+
+export interface WorktreeOwnershipRecord {
+  path: string;
+  ownerAgent?: string;
+}
+
+export interface OwnedWorktreeCwdsOptions {
+  /** The agent's identity — `process.env.SWITCHROOM_AGENT_NAME`. */
+  self: string | undefined;
+  /** The host-global registry read (`listRecords` from src/worktree/registry). */
+  listRecords: () => WorktreeOwnershipRecord[];
+  /** Injectable for tests; defaults to `fs.realpathSync`. */
+  realpath?: (p: string) => string;
+}
+
+export function ownedWorktreeCwds(opts: OwnedWorktreeCwdsOptions): string[] {
+  const { self } = opts;
+  if (self == null || self === "") return [];
+  const rp = opts.realpath ?? realpathSync;
+  try {
+    return opts
+      .listRecords()
+      .filter((r) => r.ownerAgent === self)
+      .map((r) => {
+        try {
+          return rp(r.path);
+        } catch {
+          return r.path;
+        }
+      });
+  } catch {
+    return [];
+  }
+}

package/vendor/hindsight-memory/hooks/hooks.json

@@ -23,6 +23,15 @@
       }
     ],
     "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "python3 \"${CLAUDE_PLUGIN_ROOT}/scripts/directive_verify.py\"",
+            "timeout": 10
+          }
+        ]
+      },
       {
         "hooks": [
           {