switchroom 0.17.6 → 0.17.10

package/telegram-plugin/memory-legibility.ts

@@ -0,0 +1,217 @@
+/**
+ * Sparse, chat-legible memory surface — hindsight Phase 4 (#2849).
+ *
+ * When the interactive `claude` session materially changes what it
+ * remembers during a turn — stores a new standing directive, or
+ * invalidates / demotes an existing memory — this module surfaces ONE
+ * terse line in the ORIGINATING Telegram chat/topic:
+ *
+ *   📌 <i>remembered:</i> "Always prefer TypeScript for this user"
+ *   ✂️ <i>forgot:</i> superseded deploy runbook
+ *
+ * Why so sparse: the `remember-across-sessions` job spec lists
+ * "regurgitating old facts unprompted just to prove it remembered" as a
+ * top anti-pattern. A per-turn line would *become* that anti-pattern, so
+ * this surface fires ONLY on a genuine store/correct — never on ordinary
+ * recall, and never on routine consolidation. Detection is a
+ * deterministic tool-call observation (no model call, no polling): we
+ * watch the main-agent turn stream for the specific hindsight memory
+ * tools that represent a material change.
+ *
+ * Design notes / references:
+ *   - RFC Phase 4: `reference/rfcs/hindsight-synthesis-layers.md`
+ *   - Job spec: `reference/jobs/remember-across-sessions.md`
+ *   - The `consolidation.completed` webhook the RFC names as the poll-free
+ *     driver for the "updated what I know about Y" side does NOT exist in
+ *     the pinned hindsight image (v0.8.4) — it is RFC-only. This v1 ships
+ *     the tool-observation path; the webhook stays a follow-up.
+ *
+ * Reuse: `classifyMemoryToolCall` / `detectMemoryLegibilityEvent` are the
+ * single, reusable "did a directive-create / invalidate happen in this
+ * turn?" primitive on the TypeScript gateway side. Phase 3 Stage B (#2848)
+ * runs as a vendored Python hook (`recall.py`) and CANNOT import this TS
+ * module — it mirrors the same hindsight tool-name matching independently.
+ * Keep the two in sync by hand when the tool surface changes.
+ */
+
+import { stripMarkdown, truncate } from './card-format.js'
+
+/** ON by default; an operator opts out with SWITCHROOM_MEMORY_LEGIBILITY=0.
+ *  Mirrors the SWITCHROOM_WORKER_ACTIVITY_FEED convention (only the literal
+ *  string '0' disables; unset / anything else → enabled). */
+export function isMemoryLegibilityEnabled(envVal: string | undefined): boolean {
+  return envVal !== '0'
+}
+
+/**
+ * The material memory operations we surface. Deliberately narrow — an
+ * ordinary `recall` / `reflect` / benign `update_memory` (a non-demote
+ * edit) is NOT material and returns null from the classifier.
+ */
+export type MemoryToolClass = 'directive-create' | 'memory-invalidate'
+
+/** The two hindsight tools that represent a material store / correct.
+ *  Fully-qualified names as they appear in the turn stream (`ev.toolName`). */
+export const CREATE_DIRECTIVE_TOOL = 'mcp__hindsight__create_directive'
+export const INVALIDATE_MEMORY_TOOL = 'mcp__hindsight__invalidate_memory'
+/** The demote path (`switchroom memory demote`) adds this client-side tag
+ *  via the `update_memory` tool; that specific tagging is the "forgot"
+ *  signal, whereas a plain `update_memory` edit is not material. */
+export const UPDATE_MEMORY_TOOL = 'mcp__hindsight__update_memory'
+export const DEMOTE_FROM_RECALL_MARKER = 'demote-from-recall'
+
+export type MemoryLegibilityKind = 'remembered' | 'forgot'
+
+export interface MemoryLegibilityEvent {
+  kind: MemoryLegibilityKind
+  /** Best-effort human detail (directive body / invalidate reason). May be
+   *  empty when the tool carries no legible detail — the render then falls
+   *  back to a bare "forgot a memory" line. Raw (unescaped, unstripped);
+   *  `renderMemoryLegibilityLine` does the cleanup. */
+  detail: string
+}
+
+function asString(v: unknown): string {
+  return typeof v === 'string' ? v : ''
+}
+
+/** True when an `update_memory` call's tags carry the demote-from-recall
+ *  marker — the only shape of `update_memory` that is a material correction.
+ *  Bracket- and case-tolerant (`[demote-from-recall]` / `demote-from-recall`). */
+function hasDemoteTag(input: Record<string, unknown> | undefined): boolean {
+  if (input == null) return false
+  const pools: unknown[] = []
+  for (const key of ['add_tags', 'tags']) {
+    const val = input[key]
+    if (Array.isArray(val)) pools.push(...val)
+    else if (typeof val === 'string') pools.push(val)
+  }
+  return pools.some(
+    (t) => typeof t === 'string' && t.toLowerCase().includes(DEMOTE_FROM_RECALL_MARKER),
+  )
+}
+
+/**
+ * Classify a single tool call as a material memory operation, or null if
+ * it isn't one. This is the reusable detection primitive: it answers "did a
+ * directive-create / invalidate happen in this turn?" with no rendering
+ * concern. #2848 Stage B (the vendored Python `recall.py` hook) mirrors this
+ * matching independently — it cannot import this TS module.
+ */
+export function classifyMemoryToolCall(
+  toolName: string,
+  input: Record<string, unknown> | undefined,
+): MemoryToolClass | null {
+  if (toolName === CREATE_DIRECTIVE_TOOL) return 'directive-create'
+  if (toolName === INVALIDATE_MEMORY_TOOL) return 'memory-invalidate'
+  // `update_memory` is material ONLY when it applies the demote-from-recall
+  // tag; any other edit is routine and must not surface a line.
+  if (toolName === UPDATE_MEMORY_TOOL && hasDemoteTag(input)) return 'memory-invalidate'
+  return null
+}
+
+/**
+ * Detect a surfaceable memory-legibility event from one tool call, or null.
+ * Pure — no I/O. Extracts the best-available human detail from the tool
+ * input so the caller can render + route it.
+ */
+export function detectMemoryLegibilityEvent(
+  toolName: string,
+  input: Record<string, unknown> | undefined,
+): MemoryLegibilityEvent | null {
+  const klass = classifyMemoryToolCall(toolName, input)
+  if (klass == null) return null
+  if (klass === 'directive-create') {
+    // The live server requires `content` (directive body); the profile
+    // guidance example writes `create_directive(text)`, so tolerate both,
+    // then fall back to the directive `name`.
+    const detail =
+      asString(input?.content).trim() ||
+      asString(input?.text).trim() ||
+      asString(input?.name).trim()
+    return { kind: 'remembered', detail }
+  }
+  // memory-invalidate: prefer a human `reason`; the opaque memory_id is not
+  // user-legible, so omit it and let the render use the bare fallback.
+  const detail = asString(input?.reason).trim()
+  return { kind: 'forgot', detail }
+}
+
+/**
+ * Confirm-before-legibility stager (Fix 1.3, #2903).
+ *
+ * A material memory op is detected on the `tool_use` event, but the write is
+ * not yet confirmed — the hindsight `tools/call` can still fail (engine down,
+ * `isError` envelope) and return an error `tool_result`. Sending the 📌/✂️ line
+ * on the tool_use would claim "remembered" for a write that then failed.
+ *
+ * This stager holds detected events keyed by `toolUseId`. `confirm` returns the
+ * event to send ONLY on a successful result; a failed result (`isError`) drops
+ * it and returns null. Pure and I/O-free so the send/no-send decision is unit-
+ * testable independent of the gateway's Telegram plumbing.
+ *
+ * `M` is caller-side routing metadata (chat/thread) carried opaquely.
+ */
+export class MemoryLegibilityStager<M> {
+  private pending = new Map<string, { event: MemoryLegibilityEvent; meta: M }>()
+  /** Bound the map so a turn that never emits a matching tool_result (crash
+   *  mid-tool) can't leak entries unboundedly. */
+  constructor(private readonly cap = 256) {}
+
+  /** Stage a detected event awaiting result confirmation. */
+  stage(toolUseId: string, event: MemoryLegibilityEvent, meta: M): void {
+    if (this.pending.size >= this.cap) {
+      const oldest = this.pending.keys().next().value
+      if (oldest != null) this.pending.delete(oldest)
+    }
+    this.pending.set(toolUseId, { event, meta })
+  }
+
+  /**
+   * Resolve a staged event on its matching tool_result. Returns the event +
+   * meta to send on CONFIRMED success; returns null when the write errored,
+   * when nothing was staged for this id, or when the id is empty. Always
+   * consumes the staged entry.
+   */
+  confirm(
+    toolUseId: string | null | undefined,
+    isError: boolean | undefined,
+  ): { event: MemoryLegibilityEvent; meta: M } | null {
+    if (toolUseId == null || toolUseId.length === 0) return null
+    const staged = this.pending.get(toolUseId)
+    if (staged == null) return null
+    this.pending.delete(toolUseId)
+    if (isError === true) return null
+    return staged
+  }
+
+  /** Test/introspection helper: number of currently-staged events. */
+  get size(): number {
+    return this.pending.size
+  }
+}
+
+/** HTML-escape for parse_mode:'HTML' (escape the 3 entity-significant chars). */
+function escapeHtml(s: string): string {
+  return s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;')
+}
+
+/** Max chars of directive/reason detail shown on the one-liner. */
+const DETAIL_MAX = 160
+
+/**
+ * Render the terse one-line surface (Telegram HTML). Callers send this as a
+ * real `sendMessage` (not a draft/reaction) so it's observable + durable.
+ *
+ *   📌 <i>remembered:</i> "<directive, cleaned + truncated>"
+ *   ✂️ <i>forgot:</i> <reason>            (or "✂️ <i>forgot a memory.</i>")
+ */
+export function renderMemoryLegibilityLine(ev: MemoryLegibilityEvent): string {
+  const clean = truncate(stripMarkdown(ev.detail).replace(/\s+/g, ' ').trim(), DETAIL_MAX)
+  if (ev.kind === 'remembered') {
+    if (clean.length === 0) return `📌 <i>remembered a new directive.</i>`
+    return `📌 <i>remembered:</i> "${escapeHtml(clean)}"`
+  }
+  if (clean.length === 0) return `✂️ <i>forgot a memory.</i>`
+  return `✂️ <i>forgot:</i> ${escapeHtml(clean)}`
+}

package/telegram-plugin/node_modules/.vite/vitest/da39a3ee5e6b4b0d3255bfef95601890afd80709/results.json

@@ -0,0 +1 @@
+{"version":"3.2.4","results":[[":tests/worker-activity-feed.test.ts",{"duration":604.6399409999995,"failed":true}]]}

package/telegram-plugin/scoped-approval.ts

@@ -214,6 +214,65 @@ export function sweepScopedGrants(store: ScopedGrantStore, now: number): void {
   }
 }
 
+/** Total number of live-or-not grant entries across all agents. Cheap change
+ *  signal for "did a sweep remove anything?" (sweeps only ever remove). */
+export function countScopedGrants(store: ScopedGrantStore): number {
+  let n = 0;
+  for (const list of store.values()) n += list.length;
+  return n;
+}
+
+/**
+ * A single grant flattened for on-disk persistence. Carries the agent it
+ * belongs to (the store is keyed by agent), the narrow rule/signature, and
+ * the ABSOLUTE wall-clock expiry — never a relative TTL, so a reload can
+ * never extend a window (the restart-doesn't-extend invariant). No grant
+ * time is stored because nothing needs it: expiry is the only gate.
+ */
+export interface SerializedScopedGrant {
+  readonly agent: string;
+  readonly rule: string;
+  readonly expiresAt: number;
+}
+
+/** Flatten the per-agent store to a plain array for JSON persistence. */
+export function serializeScopedGrants(store: ScopedGrantStore): SerializedScopedGrant[] {
+  const out: SerializedScopedGrant[] = [];
+  for (const [agent, list] of store) {
+    for (const g of list) out.push({ agent, rule: g.rule, expiresAt: g.expiresAt });
+  }
+  return out;
+}
+
+/**
+ * Rebuild the store from persisted entries at gateway boot. Entries already
+ * at/past `now` are DROPPED (expiry is absolute — a restart never revives or
+ * extends a window). Malformed rows are skipped defensively (fail-closed:
+ * an unparseable grant simply doesn't exist → the action re-cards). A
+ * duplicate rule for one agent collapses to the latest expiry, mirroring
+ * `recordScopedGrant`'s replace-not-accumulate behaviour.
+ */
+export function deserializeScopedGrants(
+  data: readonly unknown[],
+  now: number,
+): ScopedGrantStore {
+  const store: ScopedGrantStore = new Map();
+  if (!Array.isArray(data)) return store;
+  for (const raw of data) {
+    if (!raw || typeof raw !== "object") continue;
+    const entry = raw as Partial<SerializedScopedGrant>;
+    if (typeof entry.agent !== "string" || entry.agent.length === 0) continue;
+    if (typeof entry.rule !== "string" || entry.rule.length === 0) continue;
+    if (typeof entry.expiresAt !== "number" || !Number.isFinite(entry.expiresAt)) continue;
+    if (entry.expiresAt <= now) continue; // absolute expiry already elapsed → drop
+    const list = store.get(entry.agent) ?? [];
+    const others = list.filter((g) => g.rule !== entry.rule);
+    others.push({ rule: entry.rule, expiresAt: entry.expiresAt });
+    store.set(entry.agent, others);
+  }
+  return store;
+}
+
 /**
  * Heuristic destructive/irreversible-command detector. FAIL-CLOSED: when
  * a command can't be read or looks risky, return `true` so it is never

package/telegram-plugin/silent-end.ts

@@ -49,6 +49,17 @@ export interface SilentEndDeps {
   stateDir?: string
   /** stderr writer (defaults to `process.stderr.write`). */
   log?: (line: string) => void
+  /**
+   * Has a genuine assistant reply been delivered to this chat (optionally
+   * scoped to thread) at or after `sinceMs`? Same predicate shape as
+   * `history.hasOutboundDeliveredSince` / the represent-guard's dep
+   * (`gateway/represent-guard.ts`) — injected here so the exhaustion check
+   * below is a pure, testable decision. When omitted (history unavailable,
+   * or callers that don't wire it), the check is skipped and the guard
+   * falls back to the pre-existing turnKey/retryCount bookkeeping only —
+   * never suppress on doubt.
+   */
+  hasOutboundDeliveredSince?: (chatId: string, sinceMs: number, threadId?: number | null) => boolean
 }
 
 /**
@@ -69,6 +80,35 @@ export interface SilentEndDeps {
  */
 export const SILENT_END_MAX_RETRIES = 2
 
+/**
+ * User-facing fallback text delivered when a user-message turn ends with no
+ * final answer AND the deterministic Stop-hook re-prompt has already been
+ * exhausted (#1161). Without this the user only sees the progress card
+ * vanish; silence must never be the failure mode.
+ *
+ * PR #2892 (reference/rfcs/deterministic-turn-liveness.md Phase 2
+ * hardening): include the turn's elapsed so the fallback is honest about
+ * how long the user actually waited, instead of a generic apology with no
+ * timing. A degenerate/unknown duration (missing, non-finite, or <= 0 —
+ * e.g. a turn whose `startedAt` was never stamped) omits the waited clause
+ * rather than printing a nonsensical "(waited 0s)".
+ *
+ * Lives here (not gateway.ts) so the transport-boundary tests exercise the
+ * REAL string (tests/silent-end-transport.test.ts), not a hand-maintained
+ * copy — gateway.ts is not importable in tests.
+ */
+export function silentEndFallbackText(turnDurationMs: number | undefined): string {
+  const elapsed =
+    typeof turnDurationMs === 'number' && Number.isFinite(turnDurationMs) && turnDurationMs > 0
+      ? ` (waited ${Math.round(turnDurationMs / 1000)}s)`
+      : ''
+  return (
+    '⚠️ The agent finished working but didn’t send a reply' +
+    elapsed +
+    ' — your last message may not have been answered. Please try asking again.'
+  )
+}
+
 function resolveStateDir(deps?: SilentEndDeps): string {
   if (deps?.stateDir != null) return deps.stateDir
   const env = process.env.TELEGRAM_STATE_DIR
@@ -255,6 +295,44 @@ export function recordSilentTurnEnd(
     prev.turnKey === args.turnKey &&
     prev.retryCount >= SILENT_END_MAX_RETRIES
   ) {
+    // Staleness guard (mirrors the represent-guard's #2472 fix,
+    // `gateway/represent-guard.ts:shouldSuppressRepresent`): `turnKey` here
+    // is `statusKey(chatId, threadId)` — stable across every turn on the
+    // same chat/thread, NOT a per-turn nonce (unlike the obligation
+    // ledger's `originTurnId`). The whole mechanism depends on a reply
+    // ALWAYS clearing this state file via `clearSilentEndState` at the
+    // send-site. `clearSilentEndState` is fail-silent by design (state
+    // corruption / a write race must never crash the gateway), so if a
+    // clear is ever missed, a stale `retryCount >= MAX_RETRIES` record
+    // from an OLD, already-answered turn would be misread as "this
+    // brand-new dark turn already exhausted its re-prompt budget" —
+    // firing the user-facing fallback immediately, without the turn ever
+    // going through the Stop-hook re-prompt ladder. Before trusting that
+    // reading, verify against real delivery history: has a genuine reply
+    // landed on this chat/thread since the stale record was last written?
+    // If so, the record is satisfied-but-misdetected — drop it silently
+    // and let this dark turn start its OWN fresh retry cycle instead of
+    // inheriting someone else's spent budget.
+    if (deps?.hasOutboundDeliveredSince?.(args.chatId, prev.timestamp, args.threadId)) {
+      emitLog(
+        deps,
+        `silent-end: stale exhausted record for turnKey=${args.turnKey} ` +
+          `(retryCount=${prev.retryCount}) but a reply was delivered since ` +
+          `${prev.timestamp} — treating as satisfied-but-misdetected, not exhausted\n`,
+      )
+      // MUST clear before writing (adversarial review of #2892):
+      // writeSilentEndState re-inherits retryCount whenever the on-disk
+      // turnKey matches — which it ALWAYS does here, since turnKey is the
+      // stable statusKey(chatId, threadId). Writing over the stale record
+      // directly would start the "fresh" ladder at retryCount=MAX: the
+      // Stop hook would see retryCount >= MAX_RETRIES and never re-prompt,
+      // while this call just returned exhausted:false so no fallback fires
+      // either — pure silence, strictly worse than the pre-fix behaviour.
+      // Clearing first makes the new record genuinely start at retryCount=0.
+      clearSilentEndState(args.turnKey, deps)
+      writeSilentEndState(args, deps)
+      return { exhausted: false }
+    }
     clearSilentEndState(args.turnKey, deps)
     emitLog(
       deps,

package/telegram-plugin/subagent-watcher.ts

@@ -211,6 +211,24 @@ export interface SubagentWatcherConfig {
    * an agent's home pollutes the watcher with phantom registrations).
    */
   agentCwd?: string
+  /**
+   * Additional cwds (beyond `agentCwd`) whose Claude-Code project-dir slug
+   * should also be watched. Gap 2 of `deterministic-turn-liveness.md`: a
+   * sub-agent dispatched with worktree isolation (`switchroom worktree
+   * claim`) runs with a *different* cwd than the parent agent, so its
+   * `agent-*.jsonl` lands under a different `.claude/projects/<slug>/`
+   * tree than `expectedProjectSlug` — the #1116 foreign-slug filter then
+   * silently skips it forever (no activity stamp, no `🛠 Worker` feed).
+   *
+   * Called fresh on every rescan tick (cheap — reads a handful of small
+   * JSON records from the worktree registry) so a worktree claimed or
+   * released mid-run is picked up/dropped without a watcher restart.
+   * Deterministic guarantee this preserves: only cwds this agent's own
+   * sub-agents can legitimately run in are ever added — a worktree record
+   * not owned by this agent is never included, so this does not widen the
+   * #1116 foreign-project protection into a wildcard watch.
+   */
+  extraWatchCwdsProvider?: () => string[]
   /**
    * How often to re-scan for new subagent dirs (ms). Default 1000.
    */
@@ -1173,6 +1191,7 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
   const expectedProjectSlug = config.agentCwd != null
     ? sanitizeCwdToProjectName(config.agentCwd)
     : null
+  const extraWatchCwdsProvider = config.extraWatchCwdsProvider ?? null
   // One-shot logging: warn the first time a foreign slug is observed
   // so silent regressions are visible without re-running with debug.
   const warnedForeignSlugs = new Set<string>()
@@ -1706,17 +1725,52 @@ export function startSubagentWatcher(config: SubagentWatcherConfig): SubagentWat
       projectDirs = fs.readdirSync(projectsRoot) as string[]
     } catch { return }
 
+    // Gap 2 (deterministic-turn-liveness.md): re-derive the set of
+    // worktree-isolated slugs this agent's own sub-agents may legitimately
+    // run in, fresh on every tick. Best-effort — a registry read hiccup
+    // (e.g. the worktree dir not existing on an agent that never uses
+    // worktrees) must never break the tail loop, so it just yields no
+    // extra slugs for this tick.
+    let allowedSlugs: Set<string> | null = null
+    // Did the extra-cwd provider run cleanly this tick? A transient failure
+    // (registry read hiccup) must NOT permanently mislabel an owned worktree
+    // slug as "foreign": we still skip it this tick (it isn't provably ours
+    // right now), but we do NOT latch the one-shot warning, so the next clean
+    // tick re-includes and re-derives it instead of staying silently excluded.
+    let providerOk = true
+    if (expectedProjectSlug != null) {
+      allowedSlugs = new Set([expectedProjectSlug])
+      if (extraWatchCwdsProvider != null) {
+        try {
+          for (const cwd of extraWatchCwdsProvider()) {
+            allowedSlugs.add(sanitizeCwdToProjectName(cwd))
+          }
+        } catch (err) {
+          providerOk = false
+          log?.(`subagent-watcher: extraWatchCwdsProvider error: ${(err as Error).message}`)
+        }
+      }
+    }
+
     for (const pDir of projectDirs) {
-      // Issue #1116: filter to the agent's own slug. Skip foreign
-      // project dirs so their stale subagent JSONLs (which Claude
-      // Code reaps mid-session) don't pollute the watcher's registry.
-      if (expectedProjectSlug != null && pDir !== expectedProjectSlug) {
-        if (!warnedForeignSlugs.has(pDir)) {
+      // Issue #1116: filter to the agent's own slug (plus, per Gap 2, any
+      // worktree-isolated slugs this agent's own sub-agents may run in).
+      // Skip foreign project dirs so their stale subagent JSONLs (which
+      // Claude Code reaps mid-session) don't pollute the watcher's registry.
+      if (allowedSlugs != null && !allowedSlugs.has(pDir)) {
+        // A slug that is now allowed must clear any stale "foreign" latch, so a
+        // slug that was transiently excluded (or later genuinely goes foreign)
+        // re-warns rather than staying mislabeled forever.
+        if (providerOk && !warnedForeignSlugs.has(pDir)) {
           warnedForeignSlugs.add(pDir)
-          log?.(`subagent-watcher: skipping foreign project dir ${pDir} (expected ${expectedProjectSlug})`)
+          const allowed = [...allowedSlugs].join(', ')
+          log?.(`subagent-watcher: skipping foreign project dir ${pDir} (allowed: ${allowed})`)
         }
         continue
       }
+      // Owned/allowed this tick — drop any prior foreign latch so a future
+      // genuine foreign appearance of the same slug re-warns.
+      warnedForeignSlugs.delete(pDir)
       const projectPath = join(projectsRoot, pDir)
       let sessionDirs: string[]
       try {