switchroom 0.19.32 → 0.19.34

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "switchroom",
   "//version": "NOT the release version — source of truth is the git tag, resolved by scripts/build.mjs:resolveVersion() (see CLAUDE.md > Standard release process). This field is stale by design and only the Layer-4 dev/non-tag fallback for build.mjs + src/cli/resolve-version.ts; do NOT bump it expecting a release to pick it up. npm-pack tarball naming needs a real version — do that as an UNCOMMITTED pack-time bump (see release step 6), never a committed one.",
-  "version": "0.19.32",
+  "version": "0.19.34",
   "description": "Run Claude Code 24/7 on your Claude Pro/Max subscription over Telegram. Open-source alternative to OpenClaw and NanoClaw — no API keys.",
   "type": "module",
   "bin": {

package/telegram-plugin/dist/gateway/gateway.js

@@ -21972,6 +21972,7 @@ var init_schema = __esm(() => {
   }).describe("Per-operation LLM override. Every field optional; an unset field (or " + "an omitted op block) inherits the global `hindsight.llm.*`, which is " + "already the engine's fallback \u2014 switchroom emits only the vars set.");
   HindsightConfigSchema = exports_external.object({
     gpu: exports_external.boolean().optional().describe("Force GPU passthrough for the hindsight container on (`true`) or off " + "(`false`), overriding host autodetection in BOTH directions. Absent " + "(the default) \u2192 autodetect from the persisted host-capabilities " + "verdict (`~/.switchroom/host-capabilities.json`), which enables " + "`--gpus all` only when that file proves BOTH a GPU and the nvidia " + "container toolkit. Set `true` when that verdict is wrong or unreadable " + "and you know the host has a working toolkit \u2014 switchroom cannot verify " + "it for you, and `docker run --gpus all` hard-fails container create on " + "a host without one. Set `false` to pin the container to CPU on a GPU " + "host. This is also the declarative opt-out for the recreate-time GPU " + "drop guard (`switchroom memory setup --recreate` refuses to silently " + "turn a GPU container into a CPU one). `--gpu`/`--no-gpu` on `memory " + "setup` override this for a single run."),
+    cp_access_key: exports_external.string().min(1).optional().describe("Access key for the hindsight control-plane DASHBOARD (upstream " + "`HINDSIGHT_CP_ACCESS_KEY`, port 9999). Literal or \u2014 strongly preferred " + "\u2014 a `vault:` reference such as `vault:hindsight_cp_access_key`, read " + "through the broker at container-launch time. This is the ONLY thing " + "that arms the dashboard's login: upstream's middleware short-circuits " + "to `next()` when the var is unset, so an unset key means the dashboard " + "has no authentication at all, not weak authentication. Because of that, " + "leaving it unset is FAIL-CLOSED: switchroom pins " + "`HINDSIGHT_CP_HOSTNAME=127.0.0.1` so the loginless dashboard is " + "reachable only from the host, and warns. Set this to serve the " + "dashboard on the LAN/tailnet."),
     llm: exports_external.object({
       provider: exports_external.string().min(1).optional().describe("Hindsight LLM provider (upstream `HINDSIGHT_API_LLM_PROVIDER`). " + "Defaults to `claude-code` (subscription-honest, broker-fed OAuth). " + "Any litellm-routable provider the upstream image supports is valid. " + "Serves as the GLOBAL default for every op absent a per-op override."),
       model: exports_external.string().min(1).optional().describe("Hindsight LLM model (upstream `HINDSIGHT_API_LLM_MODEL`). Defaults " + "to HINDSIGHT_DEFAULT_MODEL. Any model your LiteLLM proxy can route " + "is valid, e.g. `openrouter/z-ai/glm-5.2` when routing through the " + "fleet proxy. With provider=claude-code this value is ALSO exported " + "as `ANTHROPIC_MODEL` to the claude subprocess. Serves as the GLOBAL " + "default for every op absent a per-op override."),
@@ -44732,7 +44733,7 @@ async function handleVoiceMessage(ctx, deps) {
 }
 
 // gateway/status-pin-store.ts
-var SNAPSHOT_VERSIONS = new Set([1, 2, 3, 4]);
+var SNAPSHOT_VERSION = 4;
 function isPinRow(x) {
   if (x == null || typeof x !== "object")
     return false;
@@ -44757,12 +44758,12 @@ function loadStatusPins(path, fs2) {
   if (parsed == null || typeof parsed !== "object")
     return [];
   const env = parsed;
-  if (typeof env.v !== "number" || !SNAPSHOT_VERSIONS.has(env.v) || !Array.isArray(env.pins))
+  if (!Number.isInteger(env.v) || env.v < 1 || !Array.isArray(env.pins))
     return [];
   return env.pins.filter(isPinRow);
 }
 function persistStatusPins(path, fs2, snapshot, log = (l) => process.stderr.write(l)) {
-  const env = { v: 4, pins: [...snapshot] };
+  const env = { v: SNAPSHOT_VERSION, pins: [...snapshot] };
   const tmp = path + ".tmp";
   try {
     fs2.writeFileSync(tmp, JSON.stringify(env));
@@ -84574,12 +84575,12 @@ init_paths();
 var _warnedReads2 = new Set;
 
 // ../src/setup/hindsight-pg-defaults.ts
-var HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION = 8 * 1024;
+var HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION = 16 * 1024;
 var HINDSIGHT_PG_APP_ANON_MIB = 2560;
 var HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB = 2048;
 var HINDSIGHT_PG_SHARED_BUFFERS_BUDGET_MIB = HINDSIGHT_PG_MEM_LIMIT_MIB_FOR_DERIVATION - HINDSIGHT_PG_APP_ANON_MIB - HINDSIGHT_PG_PAGE_CACHE_FLOOR_MIB;
-var HINDSIGHT_PG_DEFAULT_SHARED_BUFFERS_MIB = 1536;
-var HINDSIGHT_PG_DEFAULT_EFFECTIVE_CACHE_SIZE_MIB = 4096;
+var HINDSIGHT_PG_DEFAULT_SHARED_BUFFERS_MIB = 3072;
+var HINDSIGHT_PG_DEFAULT_EFFECTIVE_CACHE_SIZE_MIB = 7168;
 function pgMib(mib) {
   return `${mib}MB`;
 }
@@ -84752,9 +84753,21 @@ var HINDSIGHT_RETAIN_CLIENT_DEADLINE_S = hindsightRetainClientTimeoutSeconds() +
 var HINDSIGHT_HEALTHCHECK_PY = 'import urllib.request,sys; sys.exit(0 if urllib.request.urlopen("http://localhost:8888/health",timeout=4).getcode()==200 else 1)';
 var HINDSIGHT_HEALTHCHECK_CMD = `python3 -c '${HINDSIGHT_HEALTHCHECK_PY}'`;
 var DOCKER_PROBE_TIMEOUT_MS = 60 * 1000;
+var HINDSIGHT_CP_UNAUTHENTICATED_BIND_ADDR = "127.0.0.1";
+var HINDSIGHT_CP_NO_ACCESS_KEY_WARNING = "hindsight: no `hindsight.cp_access_key` configured \u2014 the control-plane " + "dashboard has NO login (the access-key middleware is inert when " + "HINDSIGHT_CP_ACCESS_KEY is unset), so it is pinned to " + `${HINDSIGHT_CP_UNAUTHENTICATED_BIND_ADDR} and will NOT be reachable from ` + "the LAN or tailnet. Set `hindsight.cp_access_key: vault:<key>` in " + "switchroom.yaml to arm the login and open it up.";
 
 // ../src/memory/hindsight.ts
-var DEFAULT_RETAIN_MISSION = `Extract durable facts that will still be true and useful weeks from now: user preferences and standing rules, ongoing projects and recurring commitments, technical and architectural decisions with their rationale, and people/tool relationships. A preference revealed by a request is durable \u2014 record the preference (what the user likes, wants, or always does), not the request itself.
+var DEFAULT_RETAIN_MISSION = `Extract durable facts that will still be true and useful weeks from now, once this session is forgotten.
+` + `
+` + `DURABILITY GATE. Emit a candidate ONLY if it is one of these five classes:
+` + `- PREFERENCE \u2014 what the user likes, wants, or always does; a standing rule or correction.
+` + `- DECISION \u2014 a settled choice that changes how future work is done, including a choice NOT to do something. A decision about the mechanics of the CURRENT task (which worker to dispatch, which branch to rebase, which PR to merge now, what to do next) is process narration, not a durable decision \u2014 drop it unless it establishes a standing rule or permanently changes a system.
+` + `- FINDING \u2014 a root cause, a measurement, or verified behaviour of a system. Include the number.
+` + `- OUTCOME \u2014 a completed result that changed the world: what shipped, what a thing turned out to be. Not the act of shipping it.
+` + `- RELATIONSHIP \u2014 who a person is, what a project or tool is, and how they connect.
+` + `If a candidate fits none of the five, it is not a memory. Drop it; do not reword it into one.
+` + `
+` + `A preference revealed by a request is durable \u2014 record the preference (what the user likes, wants, or always does), not the request itself.
 ` + `
 ` + `A TOOL RESULT IS NOT A FACT. Before extracting, ask: is the subject of this
 ` + `candidate a file path, a command/process/agent/session id, a temp directory, or
@@ -84771,6 +84784,9 @@ var DEFAULT_RETAIN_MISSION = `Extract durable facts that will still be true and
 ` + `- Anything mentioning a path under /tmp, a scratchpad directory, or a .tmp file.
 ` + `- Agent tool-use traces or narration of what the assistant did (e.g. "the
 ` + `  assistant used X to query Y", "ran a search", "sent the message").
+` + `- The act of delegating, dispatching, spawning, launching, steering or merging
+` + `  work \u2014 including when it succeeded. "X was dispatched and completed" is the
+` + `  session describing itself. Record only what the work LEARNED or CHANGED.
 ` + `- In-flight workflow/process narration (a sub-task started, paused, or is still
 ` + `  running) \u2014 retain the outcome only once the task completes or a decision is made.
 ` + `- Operation, request, batch, agent, command or session IDs, UUIDs, hashes, or error codes.
@@ -84793,8 +84809,12 @@ var DEFAULT_RETAIN_MISSION = `Extract durable facts that will still be true and
 ` + `  the fact is explicitly dated, in which case record it as a dated observation.
 ` + `- Greetings, acknowledgements, and routine operational chatter.
 ` + `
+` + `Write each fact so it stands alone: name the thing, the number, and the date. A
+` + `sentence that only makes sense while reading this transcript is not durable.
+` + `
 ` + `If a candidate fact matches an exclusion, drop it rather than rewording it. If
-` + "nothing durable remains, return an empty facts list.";
+` + `nothing durable remains, return an empty facts list.
+`;
 var SUPERSEDED_RETAIN_MISSIONS = [
   "Extract technical decisions, architectural choices, user preferences, project context, and people/tool relationships. Ignore routine greetings and transient operational details.",
   "Extract user preferences, ongoing projects, recurring commitments, " + "important context, and durable facts that should help across future " + "conversations. Skip one-off chatter and temporary task noise.",
@@ -84841,7 +84861,96 @@ var SUPERSEDED_RETAIN_MISSIONS = [
 ` + `- Greetings, acknowledgements, and routine operational chatter.
 ` + `
 ` + `If a candidate fact matches an exclusion, drop it rather than rewording it. If
-` + "nothing durable remains, return an empty facts list."
+` + "nothing durable remains, return an empty facts list.",
+  `Extract durable facts that will still be true and useful weeks from now: user preferences and standing rules, ongoing projects and recurring commitments, technical and architectural decisions with their rationale, and people/tool relationships. A preference revealed by a request is durable \u2014 record the preference (what the user likes, wants, or always does), not the request itself.
+` + `
+` + `A TOOL RESULT IS NOT A FACT. Before extracting, ask: is the subject of this
+` + `candidate a file path, a command/process/agent/session id, a temp directory, or
+` + `the location where some output was written? If yes, drop it \u2014 it is transcript
+` + `exhaust, not memory.
+` + `
+` + `NEVER extract:
+` + `- Tool results verbatim or paraphrased. Concretely, never produce a fact whose
+` + `  text resembles any of these: "File created successfully at /path/to/file",
+` + `  "A background command with ID bctz4yskm is running, and its output will be
+` + `  written to /tmp/...", "Async agent a745598ba84e71df1 was launched successfully
+` + `  and is running in the background", "User executed a Bash command to sleep for
+` + `  200 seconds", "The assistant used grep to locate 'truncateSync' in src/foo.ts".
+` + `- Anything mentioning a path under /tmp, a scratchpad directory, or a .tmp file.
+` + `- Agent tool-use traces or narration of what the assistant did (e.g. "the
+` + `  assistant used X to query Y", "ran a search", "sent the message").
+` + `- In-flight workflow/process narration (a sub-task started, paused, or is still
+` + `  running) \u2014 retain the outcome only once the task completes or a decision is made.
+` + `- Operation, request, batch, agent, command or session IDs, UUIDs, hashes, or error codes.
+` + `- Slash commands the user typed and their effects (e.g. "User issued /clear to
+` + `  reset assistant state").
+` + `- Hindsight's own errors, retries, backlogs, or internal state \u2014 the memory
+` + `  system's self-reports are not memories.
+` + `- Restatements of the user's current request or the task in progress.
+` + `- Volatile state written as a timeless assertion. A version, count, size,
+` + `  backlog, status, or any "X is running Y" / "X is at Y" / "X is currently Y"
+` + `  claim is true only at the instant it was said. Concretely, never produce a
+` + `  fact whose text resembles any of these: "Switchroom fleet is running image
+` + `  version v0.18.19", "The switchroom repo is at /path/to/fleet, version
+` + `  v0.19.5", "Bank overlord has 43155 pending consolidations", "The build is
+` + `  currently green". If the claim is worth keeping, put the date INSIDE the
+` + `  fact text ("As of 2026-07-19 the fleet was running v0.18.19"); if you
+` + `  cannot date it, drop it. An undated one is recalled forever as though it
+` + `  were still true, which is worse than not remembering it at all.
+` + `- Transient state (unread counts, build status, what is running right now) unless
+` + `  the fact is explicitly dated, in which case record it as a dated observation.
+` + `- Greetings, acknowledgements, and routine operational chatter.
+` + `
+` + `If a candidate fact matches an exclusion, drop it rather than rewording it. If
+` + "nothing durable remains, return an empty facts list.",
+  `Extract durable facts that will still be true and useful weeks from now, once this session is forgotten.
+` + `
+` + `DURABILITY GATE. Emit a candidate ONLY if it is one of these five classes:
+` + `- PREFERENCE \u2014 what the user likes, wants, or always does; a standing rule or correction.
+` + `- DECISION \u2014 a settled choice that changes how future work is done, including a choice NOT to do something. A decision about the mechanics of the CURRENT task (which worker to dispatch, which branch to rebase, which PR to merge now, what to do next) is process narration, not a durable decision \u2014 drop it unless it establishes a standing rule or permanently changes a system.
+` + `- FINDING \u2014 a root cause, a measurement, or verified behaviour of a system. Include the number.
+` + `- OUTCOME \u2014 a completed result that changed the world: what shipped, what a thing turned out to be. Not the act of shipping it.
+` + `- RELATIONSHIP \u2014 who a person is, what a project or tool is, and how they connect.
+` + `If a candidate fits none of the five, it is not a memory. Drop it; do not reword it into one.
+` + `
+` + `A preference revealed by a request is durable \u2014 record the preference (what the user likes, wants, or always does), not the request itself.
+` + `
+` + `A TOOL RESULT IS NOT A FACT. Before extracting, ask: is the subject of this
+` + `candidate a file path, a command/process/agent/session id, a temp directory, or
+` + `the location where some output was written? If yes, drop it \u2014 it is transcript
+` + `exhaust, not memory.
+` + `
+` + `NEVER extract:
+` + `- Tool results verbatim or paraphrased. Concretely, never produce a fact whose
+` + `  text resembles any of these: "File created successfully at /path/to/file",
+` + `  "A background command with ID bctz4yskm is running, and its output will be
+` + `  written to /tmp/...", "Async agent a745598ba84e71df1 was launched successfully
+` + `  and is running in the background", "User executed a Bash command to sleep for
+` + `  200 seconds", "The assistant used grep to locate 'truncateSync' in src/foo.ts".
+` + `- Anything mentioning a path under /tmp, a scratchpad directory, or a .tmp file.
+` + `- Agent tool-use traces or narration of what the assistant did (e.g. "the
+` + `  assistant used X to query Y", "ran a search", "sent the message").
+` + `- The act of delegating, dispatching, spawning, launching, steering or merging
+` + `  work \u2014 including when it succeeded. "X was dispatched and completed" is the
+` + `  session describing itself. Record only what the work LEARNED or CHANGED.
+` + `- In-flight workflow/process narration (a sub-task started, paused, or is still
+` + `  running) \u2014 retain the outcome only once the task completes or a decision is made.
+` + `- Operation, request, batch, agent, command or session IDs, UUIDs, hashes, or error codes.
+` + `- Slash commands the user typed and their effects (e.g. "User issued /clear to
+` + `  reset assistant state").
+` + `- Hindsight's own errors, retries, backlogs, or internal state \u2014 the memory
+` + `  system's self-reports are not memories.
+` + `- Restatements of the user's current request or the task in progress.
+` + `- Transient state (unread counts, build status, what is running right now) unless
+` + `  the fact is explicitly dated, in which case record it as a dated observation.
+` + `- Greetings, acknowledgements, and routine operational chatter.
+` + `
+` + `Write each fact so it stands alone: name the thing, the number, and the date. A
+` + `sentence that only makes sense while reading this transcript is not durable.
+` + `
+` + `If a candidate fact matches an exclusion, drop it rather than rewording it. If
+` + `nothing durable remains, return an empty facts list.
+`
 ];
 var DEFAULT_OBSERVATIONS_MISSION = `Synthesise durable, standing knowledge about the people, projects, and systems this agent works with: preferences and standing rules, roles and relationships, skills and recurring patterns, technical and operational decisions with their rationale, and the state of long-running work once it lands.
 ` + `
@@ -86523,7 +86632,7 @@ function shouldSweepChatAtBoot(chatId) {
 
 // gateway/stale-pin-sweep-store.ts
 var SWEEP_MAX_ATTEMPTS = 8;
-var SWEEP_ENVELOPE_VERSIONS = new Set([1]);
+var SWEEP_ENVELOPE_VERSION = 1;
 function sweepTargetKey(chatId, threadId) {
   return `${chatId}:${threadId ?? "-"}`;
 }
@@ -86551,13 +86660,13 @@ function loadSweepCursors(path2, fs2) {
   if (parsed == null || typeof parsed !== "object")
     return [];
   const env = parsed;
-  if (typeof env.v !== "number" || !SWEEP_ENVELOPE_VERSIONS.has(env.v) || !Array.isArray(env.cursors)) {
+  if (!Number.isInteger(env.v) || env.v < 1 || !Array.isArray(env.cursors)) {
     return [];
   }
   return env.cursors.filter(isCursorRow);
 }
 function persistSweepCursors(path2, fs2, cursors, log = (l) => process.stderr.write(l)) {
-  const env = { v: 1, cursors: [...cursors] };
+  const env = { v: SWEEP_ENVELOPE_VERSION, cursors: [...cursors] };
   try {
     fs2.writeFileSync(path2, JSON.stringify(env));
   } catch (err) {
@@ -86978,11 +87087,13 @@ function createStalePinSweeper(deps) {
   const repinUnpinLoop = async (target, kind, cursor) => {
     const gate = gateFor(kind);
     let popped = 0;
+    let issued = 0;
     let consecutiveFloods = 0;
     let lastRetryAfter = null;
     let noProgressAtSameRetryAfter = 0;
     let lastObservedTop = null;
     let unverifiedPop = false;
+    const out = (r) => ({ ...r, issued });
     const creditPop = () => {
       popped++;
       cursor.popped++;
@@ -86991,29 +87102,29 @@ function createStalePinSweeper(deps) {
     };
     for (let i = 0;i < gate.maxPopsPerChatPerSweep; i++) {
       if (circuitOpen) {
-        return { status: "aborted-circuit-breaker", popped, detail: "breaker open" };
+        return out({ status: "aborted-circuit-breaker", popped, detail: "breaker open" });
       }
       const observed = await readTopVerified(target.chatId);
       if (observed == null) {
-        return { status: "incomplete", popped, detail: "pin-stack read unverifiable" };
+        return out({ status: "incomplete", popped, detail: "pin-stack read unverifiable" });
       }
       if (unverifiedPop) {
         if (observed.top != null && observed.top === lastObservedTop) {
-          return {
+          return out({
             status: "incomplete",
             popped,
             detail: `no progress: message ${observed.top} still on top after a repin+unpin`
-          };
+          });
         }
         creditPop();
         unverifiedPop = false;
       }
       if (observed.top == null) {
-        return { status: "drained", popped };
+        return out({ status: "drained", popped });
       }
       lastObservedTop = observed.top;
       if (!await awaitWriteSlot(kind)) {
-        return { status: "deferred-budget", popped, detail: "per-minute pin-op budget spent" };
+        return out({ status: "deferred-budget", popped, detail: "per-minute pin-op budget spent" });
       }
       try {
         await deps.pinSilent(target.chatId, observed.top);
@@ -87021,10 +87132,10 @@ function createStalePinSweeper(deps) {
         const d = classify(err);
         if (d.kind === "breaker") {
           circuitOpen = true;
-          return { status: "aborted-circuit-breaker", popped, detail: d.detail };
+          return out({ status: "aborted-circuit-breaker", popped, detail: d.detail });
         }
         if (d.kind === "rights")
-          return { status: "skipped-no-rights", popped };
+          return out({ status: "skipped-no-rights", popped });
         if (d.kind === "flood") {
           consecutiveFloods++;
           if (lastRetryAfter === d.seconds)
@@ -87033,19 +87144,19 @@ function createStalePinSweeper(deps) {
             noProgressAtSameRetryAfter = 1;
           lastRetryAfter = d.seconds;
           if (consecutiveFloods >= MAX_CONSECUTIVE_FLOOD_WAITS || noProgressAtSameRetryAfter >= MAX_IDENTICAL_RETRY_AFTER_NO_PROGRESS) {
-            return {
+            return out({
               status: "deferred-flood",
               popped,
               detail: `flood: ${consecutiveFloods} consecutive 429s, retry_after=${d.seconds}s`
-            };
+            });
           }
           await deps.sleep(d.seconds * 1000 * Math.pow(FLOOD_BACKOFF_FACTOR, consecutiveFloods - 1));
           continue;
         }
-        return { status: "error", popped, detail: d.detail };
+        return out({ status: "error", popped, detail: d.detail });
       }
       if (!await awaitWriteSlot(kind)) {
-        return { status: "deferred-budget", popped, detail: "per-minute pin-op budget spent" };
+        return out({ status: "deferred-budget", popped, detail: "per-minute pin-op budget spent" });
       }
       try {
         await deps.unpin(target.chatId, observed.top);
@@ -87053,12 +87164,12 @@ function createStalePinSweeper(deps) {
         const d = classify(err);
         if (d.kind === "breaker") {
           circuitOpen = true;
-          return { status: "aborted-circuit-breaker", popped, detail: d.detail };
+          return out({ status: "aborted-circuit-breaker", popped, detail: d.detail });
         }
         if (d.kind === "rights")
-          return { status: "skipped-no-rights", popped };
+          return out({ status: "skipped-no-rights", popped });
         if (isNothingToUnpinError(err))
-          return { status: "drained", popped };
+          return out({ status: "drained", popped });
         if (d.kind === "flood") {
           consecutiveFloods++;
           if (lastRetryAfter === d.seconds)
@@ -87067,30 +87178,31 @@ function createStalePinSweeper(deps) {
             noProgressAtSameRetryAfter = 1;
           lastRetryAfter = d.seconds;
           if (consecutiveFloods >= MAX_CONSECUTIVE_FLOOD_WAITS || noProgressAtSameRetryAfter >= MAX_IDENTICAL_RETRY_AFTER_NO_PROGRESS) {
-            return {
+            return out({
               status: "deferred-flood",
               popped,
               detail: `flood: ${consecutiveFloods} consecutive 429s, retry_after=${d.seconds}s`
-            };
+            });
           }
           await deps.sleep(d.seconds * 1000 * Math.pow(FLOOD_BACKOFF_FACTOR, consecutiveFloods - 1));
           continue;
         }
-        return { status: "error", popped, detail: d.detail };
+        return out({ status: "error", popped, detail: d.detail });
       }
       consecutiveFloods = 0;
+      issued++;
       unverifiedPop = true;
     }
     const finalRead = await readTopVerified(target.chatId);
     if (unverifiedPop && finalRead != null && finalRead.top !== lastObservedTop)
       creditPop();
     if (finalRead != null && finalRead.top == null)
-      return { status: "drained", popped };
-    return {
+      return out({ status: "drained", popped });
+    return out({
       status: "deferred-budget",
       popped,
       detail: `hit the ${gate.maxPopsPerChatPerSweep}-pop cap for this chat; yielding to next boot`
-    };
+    });
   };
   const targetedUnpinDrain = async (target, kind, cursor, ids) => {
     const alreadyDone = new Set(cursor.doneIds ?? []);
@@ -87187,10 +87299,21 @@ function createStalePinSweeper(deps) {
   const forumTopicDrain = async (target, cursor) => {
     const threadId = target.threadId;
     if (threadId == null) {
-      return { status: "skipped-nothing-recorded", popped: 0, detail: "no message_thread_id" };
+      return {
+        status: "skipped-nothing-recorded",
+        popped: 0,
+        issued: 0,
+        detail: "no message_thread_id"
+      };
     }
+    const before = await readTopVerified(target.chatId);
     if (!await awaitWriteSlot("forum-topic")) {
-      return { status: "deferred-budget", popped: 0, detail: "per-minute pin-op budget spent" };
+      return {
+        status: "deferred-budget",
+        popped: 0,
+        issued: 0,
+        detail: "per-minute pin-op budget spent"
+      };
     }
     try {
       await deps.unpinAllForumTopicMessages(target.chatId, threadId);
@@ -87198,39 +87321,59 @@ function createStalePinSweeper(deps) {
       const d = classify(err);
       if (d.kind === "breaker") {
         circuitOpen = true;
-        return { status: "aborted-circuit-breaker", popped: 0, detail: d.detail };
+        return { status: "aborted-circuit-breaker", popped: 0, issued: 0, detail: d.detail };
       }
       if (d.kind === "rights")
-        return { status: "skipped-no-rights", popped: 0 };
+        return { status: "skipped-no-rights", popped: 0, issued: 0 };
       if (d.kind === "flood") {
         return {
           status: "deferred-flood",
           popped: 0,
+          issued: 0,
           detail: `unpinAllForumTopicMessages pegged at retry_after=${d.seconds}s; not looping`
         };
       }
-      return { status: "error", popped: 0, detail: d.detail };
+      return { status: "error", popped: 0, issued: 0, detail: d.detail };
     }
-    cursor.popped++;
-    cursor.updatedAt = deps.now();
-    commit(cursor);
     const observed = await readTopVerified(target.chatId);
-    if (observed != null && observed.top == null)
-      return { status: "drained", popped: 1 };
-    return { status: "drained", popped: 1, detail: "topic drained; chat-wide stack may hold other topics" };
+    const topMoved = before != null && observed != null && observed.top !== before.top ? 1 : 0;
+    if (topMoved > 0) {
+      cursor.popped += topMoved;
+      cursor.updatedAt = deps.now();
+      commit(cursor);
+    }
+    if (observed != null && observed.top == null) {
+      return { status: "drained", popped: topMoved, issued: 1 };
+    }
+    return {
+      status: "drained",
+      popped: topMoved,
+      issued: 1,
+      detail: "topic drained; chat-wide stack may hold other topics"
+    };
   };
   const sweepOnce = async (target) => {
     if (!deps.eligible())
-      return { status: "skipped-not-eligible", popped: 0 };
+      return { status: "skipped-not-eligible", popped: 0, issued: 0 };
     if (circuitOpen) {
-      return { status: "aborted-circuit-breaker", popped: 0, detail: "breaker already open" };
+      return {
+        status: "aborted-circuit-breaker",
+        popped: 0,
+        issued: 0,
+        detail: "breaker already open"
+      };
     }
     const kind = classifyChatForSweep(target);
     const cursor = loadCursor(target, kind);
     if (cursor.done)
-      return { status: "already-drained", popped: 0 };
+      return { status: "already-drained", popped: 0, issued: 0 };
     if (cursor.attempts >= SWEEP_MAX_ATTEMPTS) {
-      return { status: "forfeited", popped: 0, detail: `${cursor.attempts} attempts exhausted` };
+      return {
+        status: "forfeited",
+        popped: 0,
+        issued: 0,
+        detail: `${cursor.attempts} attempts exhausted`
+      };
     }
     if (kind !== "dm") {
       let allowed = false;
@@ -87244,7 +87387,7 @@ function createStalePinSweeper(deps) {
         cursor.lastStatus = "skipped-no-rights";
         cursor.updatedAt = deps.now();
         commit(cursor);
-        return { status: "skipped-no-rights", popped: 0 };
+        return { status: "skipped-no-rights", popped: 0, issued: 0 };
       }
     }
     cursor.attempts++;
@@ -87273,7 +87416,7 @@ function createStalePinSweeper(deps) {
         } : await targetedUnpinDrain(target, kind, cursor, ids);
       }
     } catch (err) {
-      result = { status: "error", popped: 0, detail: err.message };
+      result = { status: "error", popped: 0, issued: 0, detail: err.message };
     }
     if (result.status === "drained" || result.status === "skipped-nothing-recorded") {
       cursor.done = true;
@@ -87306,10 +87449,12 @@ function createStalePinSweeper(deps) {
     const running = inFlight.get(key);
     if (running != null)
       return running;
-    if (!deps.eligible())
-      return Promise.resolve({ status: "skipped-not-eligible", popped: 0 });
-    if (attempted.has(key))
-      return Promise.resolve({ status: "already-attempted", popped: 0 });
+    if (!deps.eligible()) {
+      return Promise.resolve({ status: "skipped-not-eligible", popped: 0, issued: 0 });
+    }
+    if (attempted.has(key)) {
+      return Promise.resolve({ status: "already-attempted", popped: 0, issued: 0 });
+    }
     attempted.add(key);
     const p = sweepOnce(target).finally(() => inFlight.delete(key));
     inFlight.set(key, p);
@@ -90214,7 +90359,7 @@ function createCapturedResumeDispatcher(ports) {
 
 // gateway/status-pin-store.ts
 var BOOT_UNPIN_MAX_ATTEMPTS = 5;
-var SNAPSHOT_VERSIONS2 = new Set([1, 2, 3, 4]);
+var SNAPSHOT_VERSION2 = 4;
 function isPinRow2(x) {
   if (x == null || typeof x !== "object")
     return false;
@@ -90239,12 +90384,12 @@ function loadStatusPins2(path3, fs3) {
   if (parsed == null || typeof parsed !== "object")
     return [];
   const env = parsed;
-  if (typeof env.v !== "number" || !SNAPSHOT_VERSIONS2.has(env.v) || !Array.isArray(env.pins))
+  if (!Number.isInteger(env.v) || env.v < 1 || !Array.isArray(env.pins))
     return [];
   return env.pins.filter(isPinRow2);
 }
 function persistStatusPins2(path3, fs3, snapshot, log = (l) => process.stderr.write(l)) {
-  const env = { v: 4, pins: [...snapshot] };
+  const env = { v: SNAPSHOT_VERSION2, pins: [...snapshot] };
   const tmp = path3 + ".tmp";
   try {
     fs3.writeFileSync(tmp, JSON.stringify(env));
@@ -96545,6 +96690,12 @@ function parseAuditLine(line) {
     entry.m = o.m;
   if (typeof o.prior_pin === "string")
     entry.prior_pin = o.prior_pin;
+  if (Array.isArray(o.prior_pin_observed) && o.prior_pin_observed.every((v) => typeof v === "string")) {
+    entry.prior_pin_observed = o.prior_pin_observed;
+  }
+  if (typeof o.prior_pin_source === "string") {
+    entry.prior_pin_source = o.prior_pin_source;
+  }
   return entry;
 }
 function filterEntries(entries, filters) {
@@ -99169,10 +99320,10 @@ function startOutboxSweep(deps) {
 }
 
 // ../src/build-info.ts
-var VERSION2 = "0.19.32";
-var COMMIT_SHA = "5ccce0a7";
-var COMMIT_DATE = "2026-07-28T23:48:52Z";
-var LATEST_PR = 3962;
+var VERSION2 = "0.19.34";
+var COMMIT_SHA = "73a1b218";
+var COMMIT_DATE = "2026-07-29T05:33:45Z";
+var LATEST_PR = 3981;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts

package/telegram-plugin/gateway/stale-pin-sweep-store.ts

@@ -102,12 +102,20 @@ export interface SweepStoreFsSeam {
   existsSync: (path: string) => boolean
 }
 
+/**
+ * Envelope. Same bump rule as `status-pin-store.ts` (#3957): every field added
+ * after v1 is OPTIONAL, and the reader is version-TOLERANT so a row written by
+ * a newer build survives a downgrade rather than being discarded. Discarding is
+ * not "do nothing" for an obligation ledger — it forgets an obligation, which
+ * is precisely the orphaned-pin failure this module exists to close.
+ */
 interface SweepEnvelope {
-  v: 1
+  v: number
   cursors: SweepCursor[]
 }
 
-const SWEEP_ENVELOPE_VERSIONS = new Set([1])
+/** The version THIS build writes. Only the writer is pinned; see above. */
+const SWEEP_ENVELOPE_VERSION = 1
 
 /** Stable identity of a sweep target: chat plus topic (topic-less = `-`). */
 export function sweepTargetKey(chatId: string, threadId?: number): string {
@@ -153,11 +161,9 @@ export function loadSweepCursors(path: string, fs: SweepStoreFsSeam): SweepCurso
   }
   if (parsed == null || typeof parsed !== 'object') return []
   const env = parsed as Record<string, unknown>
-  if (
-    typeof env.v !== 'number' ||
-    !SWEEP_ENVELOPE_VERSIONS.has(env.v) ||
-    !Array.isArray(env.cursors)
-  ) {
+  // Version-TOLERANT, structurally strict — see {@link SweepEnvelope}. An
+  // unknown `v` still yields the cursor rows that validate.
+  if (!Number.isInteger(env.v) || (env.v as number) < 1 || !Array.isArray(env.cursors)) {
     return []
   }
   return env.cursors.filter(isCursorRow)
@@ -174,7 +180,7 @@ export function persistSweepCursors(
   cursors: readonly SweepCursor[],
   log: (line: string) => void = (l) => process.stderr.write(l),
 ): void {
-  const env: SweepEnvelope = { v: 1, cursors: [...cursors] }
+  const env: SweepEnvelope = { v: SWEEP_ENVELOPE_VERSION, cursors: [...cursors] }
   try {
     fs.writeFileSync(path, JSON.stringify(env))
   } catch (err) {