switchroom 0.20.11 → 0.20.12

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

@@ -22036,7 +22036,7 @@ var init_schema = __esm(() => {
       reflect: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `reflect` LLM op (synthesis / mental-model " + "refresh). Emits `HINDSIGHT_API_REFLECT_LLM_*`. Absent \u2192 uses global."),
       consolidation: HindsightPerOpLlmSchema.optional().describe("Per-op override for the `consolidation` LLM op (background memory " + "merge). Emits `HINDSIGHT_API_CONSOLIDATION_LLM_*`. Absent \u2192 global.")
     }).optional().describe("LLM knob for the hindsight container. The flat `provider`/`model` set " + "the global default (backward-compatible); optional `retain`/`reflect`/" + "`consolidation` blocks override individual ops. All fields optional; " + "unset fields fall back to the hard-coded defaults."),
-    env: exports_external.record(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()])).optional().describe("Operator overrides for switchroom's capability-gated Hindsight " + "performance defaults. Only the keys switchroom actually manages are " + "honoured (`HINDSIGHT_PERF_ENV_KEYS` in " + "src/setup/hindsight-perf-defaults.ts: RERANKER_LOCAL_FP16, " + "RERANKER_LOCAL_BATCH_SIZE, LLM_MAX_CONCURRENT, " + "RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, LLM_STRICT_SCHEMA, " + "LLM_MAX_RETRIES, CONSOLIDATION_LLM_PARALLELISM, " + "MAX_OBSERVATIONS_PER_SCOPE, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT, " + "RERANKER_LOCAL_BUCKET_BATCHING, RERANKER_MAX_CANDIDATES, " + "RERANKER_LOCAL_MAX_CONCURRENT, RECALL_MAX_CONCURRENT, " + "REFLECT_WALL_TIMEOUT, WORKER_CONSOLIDATION_RESERVED_SLOTS, " + "WORKER_CONSOLIDATION_SLOT_LIMIT, " + "CONSOLIDATION_MAX_MEMORIES_PER_ROUND, GRAPH_SEED_MIN_SIMILARITY, " + "LLM_SUPPORTS_MAX_ITEMS, RECENCY_DECAY_FUNCTION, " + "RECENCY_DECAY_HALFLIFE_DAYS \u2014 switchroom defaults recall's recency " + "curve to `exponential` with a 30-day half-life so a fact retained " + "today outranks a stale one, instead of upstream's near-flat " + "linear/365-day window), the override-only keys " + "switchroom manages but ships NO default for " + "(`HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS`: " + "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY \u2014 a per-deployment " + "`bank-pattern:priority,...` map; unset means upstream's flat " + "created_at FIFO across banks; and " + "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP \u2014 the rollback knob for " + "switchroom's CE-saturation damping patch, a float; >= ~0.65 backs the " + "damping out entirely, unset means the patch's own derived gap; and " + "HINDSIGHT_API_RECENCY_DECAY_LINEAR_WINDOW_DAYS \u2014 only read when the " + "decay function is `linear`, so switchroom ships no default for it but " + "still honours an operator who flips the function back; and " + "HINDSIGHT_API_WORKER_MAX_SLOTS \u2014 the worker poller's TOTAL in-flight " + "task budget, the pool WORKER_CONSOLIDATION_RESERVED_SLOTS reserves out of; " + "unset means upstream's own default; and " + "HINDSIGHT_API_WORKER_RETAIN_RESERVED_SLOTS \u2014 the reserved slot FLOOR for the " + "retain (memory write) lane, carved from that same total; unset means " + "upstream's own 0, i.e. no floor and retain competes for the shared " + "pool; and " + "the pre-0.8.6 name HINDSIGHT_API_WORKER_<TYPE>_MAX_SLOTS is still " + "accepted for every operation type and normalised to " + "..._RESERVED_SLOTS on the way in, because setting both names for " + "one type is a hard boot failure in the engine and switchroom " + "therefore emits only the canonical name; and " + "HINDSIGHT_API_SEMANTIC_MIN_SIMILARITY \u2014 the cosine-similarity floor a " + "candidate must reach to be returned by the semantic retrieval arm at " + "all (0..1); unset means upstream's own 0.3, and where it should sit " + "depends on the bank's embedding model and phrasing diversity, so " + "switchroom ships no opinion; and " + "HINDSIGHT_MCP_RECALL_BUDGET_MODE \u2014 the rollback knob for switchroom's " + "mcp-recall-token-budget image patch; `legacy` restores upstream's " + "exact pre-patch recall returns, anything else or unset is the " + "honest-envelope mode; and " + "HINDSIGHT_API_LLM_TEMPERATURE_REFLECT \u2014 upstream's own per-op reflect " + "temperature knob, made live by switchroom's reflect-temperature image " + "patch; a float, or `none` to omit the kwarg (provider default, " + "upstream's accidental pre-patch behaviour); unset means the image's " + "baked default 0.1; and " + "HINDSIGHT_API_CONSOLIDATION_RECALL_MAX_CONCURRENT \u2014 the background " + "half of switchroom's recall-admission split (#3660): of the " + "RECALL_MAX_CONCURRENT admission slots, at most this many may be held " + "by background consolidation recalls at once, so foreground per-turn " + "recall always keeps the remainder; must be >= 1 and strictly less " + "than RECALL_MAX_CONCURRENT or the engine refuses to boot; unset " + "means the image's derived default min(2, RECALL_MAX_CONCURRENT - 1); " + "1 biases hard toward the interactive lane while a consolidation " + "backlog drains; and " + "HINDSIGHT_MM_REFRESH_MIN_INTERVAL_S \u2014 the rollback/tuning knob for " + "switchroom's MM-refresh-debounce image patch: the minimum seconds " + "between consolidation-triggered refreshes of one mental model; unset " + "means the image's baked 3600, 0 restores upstream's " + "refresh-every-round behaviour; explicit and cron-scheduled refreshes " + "are never debounced; and " + "HINDSIGHT_API_TEMPORAL_LANGUAGES \u2014 the language set dateparser is " + "restricted to during temporal query analysis, made live by switchroom's " + "temporal-language image patch (which ended a 200+-locale auto-detection " + "pass that blocked the shared asyncio loop on every recall); " + "comma-separated, unset means the image's baked `en`, set e.g. `en,es` to " + "restore i18n parsing; and " + "HINDSIGHT_API_TEMPORAL_MAX_QUERY_CHARS \u2014 the max chars of query text " + "dateparser.search_dates() is handed during temporal analysis (0 = " + "unlimited), made live by switchroom's temporal-offload image patch " + "(which moved the synchronous extraction off the shared asyncio loop onto " + "a single-worker thread and bounds its input, ending multi-second loop " + "stalls on multi-KB consolidation queries); unset means the image's baked " + "2000, set 0 to restore an unbounded full scan), plus the " + "embedded-PostgreSQL (pg0) sizing keys switchroom manages in " + "src/setup/hindsight-pg-defaults.ts (`HINDSIGHT_PG_ENV_KEYS`: " + "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE, " + "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS \u2014 a postgres size string such " + "as `4GB`, or the sentinel `off` to leave pg0's own default for that " + "one knob). A value set here " + "REPLACES switchroom's default and is emitted even when the gating " + "capability is absent, so an operator can always force a knob. Other " + "`HINDSIGHT_API_*` keys are deliberately IGNORED \u2014 a blanket " + "passthrough would collide with the vars startHindsight() derives " + "itself (HINDSIGHT_API_PORT, the retain token/deadline budget).")
+    env: exports_external.record(exports_external.union([exports_external.string(), exports_external.number(), exports_external.boolean()])).optional().describe("Operator overrides for switchroom's capability-gated Hindsight " + "performance defaults. Only the keys switchroom actually manages are " + "honoured (`HINDSIGHT_PERF_ENV_KEYS` in " + "src/setup/hindsight-perf-defaults.ts: RERANKER_LOCAL_FP16, " + "RERANKER_LOCAL_BATCH_SIZE, LLM_MAX_CONCURRENT, " + "RETAIN/CONSOLIDATION_LLM_MAX_CONCURRENT, LLM_STRICT_SCHEMA, " + "LLM_MAX_RETRIES, CONSOLIDATION_LLM_PARALLELISM, " + "MAX_OBSERVATIONS_PER_SCOPE, " + "RECALL_MAX_CANDIDATES_PER_SOURCE, LINK_EXPANSION_PER_ENTITY_LIMIT, " + "LINK_EXPANSION_TIMEOUT, LLM_REASONING_EFFORT, " + "RERANKER_LOCAL_BUCKET_BATCHING, RERANKER_MAX_CANDIDATES, " + "RERANKER_LOCAL_MAX_CONCURRENT, RECALL_MAX_CONCURRENT, " + "REFLECT_WALL_TIMEOUT, WORKER_CONSOLIDATION_RESERVED_SLOTS, " + "WORKER_CONSOLIDATION_SLOT_LIMIT, " + "CONSOLIDATION_MAX_MEMORIES_PER_ROUND, GRAPH_SEED_MIN_SIMILARITY, " + "LLM_SUPPORTS_MAX_ITEMS, RECENCY_DECAY_FUNCTION, " + "RECENCY_DECAY_HALFLIFE_DAYS \u2014 switchroom defaults recall's recency " + "curve to `exponential` with a 30-day half-life so a fact retained " + "today outranks a stale one, instead of upstream's near-flat " + "linear/365-day window), the override-only keys " + "switchroom manages but ships NO default for " + "(`HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS`: " + "HINDSIGHT_API_WORKER_CONSOLIDATION_BANK_PRIORITY \u2014 a per-deployment " + "`bank-pattern:priority,...` map; unset means upstream's flat " + "created_at FIFO across banks; and " + "HINDSIGHT_CE_DECISIVE_RELATIVE_GAP \u2014 the rollback knob for " + "switchroom's CE-saturation damping patch, a float; >= ~0.65 backs the " + "damping out entirely, unset means the patch's own derived gap; and " + "HINDSIGHT_API_RECENCY_DECAY_LINEAR_WINDOW_DAYS \u2014 only read when the " + "decay function is `linear`, so switchroom ships no default for it but " + "still honours an operator who flips the function back; and " + "HINDSIGHT_API_WORKER_MAX_SLOTS \u2014 the worker poller's TOTAL in-flight " + "task budget, the pool WORKER_CONSOLIDATION_RESERVED_SLOTS reserves out of; " + "unset means upstream's own default; and " + "HINDSIGHT_API_WORKER_RETAIN_RESERVED_SLOTS \u2014 the reserved slot FLOOR for the " + "retain (memory write) lane, carved from that same total; unset means " + "upstream's own 0, i.e. no floor and retain competes for the shared " + "pool; and " + "the pre-0.8.6 name HINDSIGHT_API_WORKER_<TYPE>_MAX_SLOTS is still " + "accepted for every operation type and normalised to " + "..._RESERVED_SLOTS on the way in, because setting both names for " + "one type is a hard boot failure in the engine and switchroom " + "therefore emits only the canonical name; and " + "HINDSIGHT_API_SEMANTIC_MIN_SIMILARITY \u2014 the cosine-similarity floor a " + "candidate must reach to be returned by the semantic retrieval arm at " + "all (0..1); unset means upstream's own 0.3, and where it should sit " + "depends on the bank's embedding model and phrasing diversity, so " + "switchroom ships no opinion; and " + "HINDSIGHT_MCP_RECALL_BUDGET_MODE \u2014 the rollback knob for switchroom's " + "mcp-recall-token-budget image patch; `legacy` restores upstream's " + "exact pre-patch recall returns, anything else or unset is the " + "honest-envelope mode; and " + "HINDSIGHT_API_LLM_TEMPERATURE_REFLECT \u2014 upstream's own per-op reflect " + "temperature knob, made live by switchroom's reflect-temperature image " + "patch; a float, or `none` to omit the kwarg (provider default, " + "upstream's accidental pre-patch behaviour); unset means the image's " + "baked default 0.1; and " + "HINDSIGHT_API_CONSOLIDATION_RECALL_MAX_CONCURRENT \u2014 the background " + "half of switchroom's recall-admission split (#3660): of the " + "RECALL_MAX_CONCURRENT admission slots, at most this many may be held " + "by background consolidation recalls at once, so foreground per-turn " + "recall always keeps the remainder; must be >= 1 and strictly less " + "than RECALL_MAX_CONCURRENT or the engine refuses to boot; unset " + "means the image's derived default min(2, RECALL_MAX_CONCURRENT - 1); " + "1 biases hard toward the interactive lane while a consolidation " + "backlog drains; and " + "HINDSIGHT_MM_REFRESH_MIN_INTERVAL_S \u2014 the rollback/tuning knob for " + "switchroom's MM-refresh-debounce image patch: the minimum seconds " + "between consolidation-triggered refreshes of one mental model; unset " + "means the image's baked 3600, 0 restores upstream's " + "refresh-every-round behaviour; explicit and cron-scheduled refreshes " + "are never debounced; and " + "HINDSIGHT_API_TEMPORAL_LANGUAGES \u2014 the language set dateparser is " + "restricted to during temporal query analysis, made live by switchroom's " + "temporal-language image patch (which ended a 200+-locale auto-detection " + "pass that blocked the shared asyncio loop on every recall); " + "comma-separated, unset means the image's baked `en`, set e.g. `en,es` to " + "restore i18n parsing; and " + "HINDSIGHT_API_TEMPORAL_MAX_QUERY_CHARS \u2014 the max chars of query text " + "dateparser.search_dates() is handed during temporal analysis (0 = " + "unlimited), made live by switchroom's temporal-offload image patch " + "(which moved the synchronous extraction off the shared asyncio loop onto " + "a single-worker thread and bounds its input, ending multi-second loop " + "stalls on multi-KB consolidation queries); unset means the image's baked " + "2000, set 0 to restore an unbounded full scan); and " + "HINDSIGHT_API_TEXT_SEARCH_EXTENSION_NATIVE_LANGUAGE \u2014 the Postgres " + "text-search regconfig the native BM25 arms and the search_vector index " + "write run to_tsvector/to_tsquery against; unset means upstream's " + "always-safe `english`, set `hindsight_english` to use switchroom's " + "junk-stopping config (dict + stopword file provisioned durably by the " + "image entrypoint, recall degrading to semantic-only if it is ever " + "missing); plus the " + "embedded-PostgreSQL (pg0) sizing keys switchroom manages in " + "src/setup/hindsight-pg-defaults.ts (`HINDSIGHT_PG_ENV_KEYS`: " + "SWITCHROOM_HINDSIGHT_PG_EFFECTIVE_CACHE_SIZE, " + "SWITCHROOM_HINDSIGHT_PG_SHARED_BUFFERS \u2014 a postgres size string such " + "as `4GB`, or the sentinel `off` to leave pg0's own default for that " + "one knob). A value set here " + "REPLACES switchroom's default and is emitted even when the gating " + "capability is absent, so an operator can always force a knob. Other " + "`HINDSIGHT_API_*` keys are deliberately IGNORED \u2014 a blanket " + "passthrough would collide with the vars startHindsight() derives " + "itself (HINDSIGHT_API_PORT, the retain token/deadline budget).")
   });
   MicrosoftWorkspaceConfigSchema = exports_external.object({
     microsoft_client_id: exports_external.string().min(1).optional().describe("Microsoft OAuth application (client) ID from Entra portal " + "(literal string or vault reference e.g. " + "'vault:microsoft-oauth-client-id'). OPTIONAL \u2014 omit it to use " + "switchroom's shipped default Microsoft app (zero-config). " + "Set it only to bring your own Entra app (BYO)."),
@@ -22489,7 +22489,9 @@ var init_schema = __esm(() => {
     path: exports_external.string().regex(/^[a-zA-Z0-9~._\-/]+$/, "config_repo.path must not contain shell-special characters ($, `, \", ', \\, etc.)").default("~/.switchroom-config").describe("Filesystem path to the operator's private config repo. Must be a git " + "repo (else `switchroom doctor` FAILs). Tilde-expanded at read time."),
     push: exports_external.boolean().default(true).describe("When true, `config-repo sync` pushes after committing (subject to the " + "`require_private` gate). When false, it commits locally only \u2014 useful " + "for offline hosts or a review-before-push workflow."),
     remote: exports_external.string().min(1).default("origin").describe("Git remote name to push to. Default `origin`."),
-    require_private: exports_external.boolean().default(true).describe("Refuse to PUSH unless the GitHub API confirms the remote repo is " + "private. On a public remote \u2014 or when the API is unreachable \u2014 the " + "push is skipped (commits still land locally) and a WARN is emitted. " + "Fail-safe against exfiltrating memory files / workspace state to a " + "repo that has been flipped public. Default true.")
+    require_private: exports_external.boolean().default(true).describe("Refuse to PUSH unless the GitHub API confirms the remote repo is " + "private. On a public remote \u2014 or when the API is unreachable \u2014 the " + "push is skipped (commits still land locally) and a WARN is emitted. " + "Fail-safe against exfiltrating memory files / workspace state to a " + "repo that has been flipped public. Default true."),
+    interval_minutes: exports_external.number().int().min(5).max(59).default(30).describe("Cadence (minutes) of the scheduled `config-repo sync` tick installed " + "by `switchroom config-repo --install-cron`. Rendered as a cron " + "`*/N * * * *` minute field, so it must be 5..59 (the 5-min floor " + "matches the rest of the fleet's cron floor). Default 30 (Ken's " + "approved cadence). Changing it takes effect on the next " + "`--install-cron` / `switchroom update` reconcile."),
+    include_vault_backup: exports_external.enum(["off", "daily", "every_tick"]).default("daily").describe("Whether the scheduled tick also runs `switchroom vault backup` " + "(an encrypted vault/memory snapshot into <path>/vault-backups/) " + "before the sync. `off`: sync only. `daily`: an extra once-per-day " + "cron leg runs `vault backup && config-repo sync` (the 30-min legs " + "stay sync-only). `every_tick`: every tick runs the backup first. " + "Default `daily` \u2014 the first automated vault backup on this host.")
   });
   SwitchroomConfigSchema = exports_external.object({
     switchroom: exports_external.object({
@@ -49357,7 +49359,7 @@ function createWorkerActivityFeed(opts) {
   const floodWaitRemainingMs = opts.floodWaitRemainingMs ?? (() => 0);
   const minEditInterval = opts.minEditIntervalMs ?? 2500;
   const elapsedRefreshMs = Math.max(minEditInterval, Math.floor(opts.elapsedRefreshMs ?? 15000));
-  const firstPaintMin = opts.firstPaintMinMs ?? 8000;
+  const firstPaintMin = opts.firstPaintMinMs ?? 4000;
   const heartbeatTickMs = opts.heartbeatTickMs ?? 6000;
   const maxRows = Math.max(1, Math.floor(opts.maxRows ?? 8));
   const staleWorkerTtlMs = Math.max(1, Math.floor(opts.staleWorkerTtlMs ?? 50 * 60000));
@@ -79336,7 +79338,6 @@ function isStructuralNarration(text4, followedByToolUse) {
 var EPHEMERAL_TOOLS = new Set([
   "react",
   "send_typing",
-  "pin_message",
   "delete_message",
   "edit_message"
 ]);
@@ -82650,6 +82651,12 @@ function decideTurnEndGate(snapshot) {
 }
 
 // gateway/turn-record-status.ts
+function computeTurnDurationMs(startedAt, now) {
+  if (typeof startedAt !== "number" || !Number.isFinite(startedAt) || startedAt <= 0) {
+    return 0;
+  }
+  return Math.max(0, now - startedAt);
+}
 function backstopSendOutcomeGated(args) {
   if (args.threw)
     return "failed";
@@ -83605,7 +83612,7 @@ function handleSessionEvent(deps, ev) {
               chatId,
               threadId,
               turnId: turn.turnId,
-              turnDurationMs: turn.startedAt > 0 ? Date.now() - turn.startedAt : 0,
+              turnDurationMs: computeTurnDurationMs(turn.startedAt, Date.now()),
               reactionCount: reactionTransitionCounts.get(tKey) ?? 0
             });
           }
@@ -83623,7 +83630,7 @@ function handleSessionEvent(deps, ev) {
           finalizeStatusReaction(chatId, threadId, "done");
           {
             const sKey = streamKey2(chatId, threadId);
-            const turnDurationMs = turn.startedAt > 0 ? Date.now() - turn.startedAt : 0;
+            const turnDurationMs = computeTurnDurationMs(turn.startedAt, Date.now());
             logStreamingEvent2({
               kind: "turn_end",
               chatId,
@@ -83857,7 +83864,7 @@ function handleSessionEvent(deps, ev) {
         finalizeStatusReaction(chatId, threadId, terminalReason);
         {
           const sKey = streamKey2(chatId, threadId);
-          const turnDurationMs = turn.startedAt > 0 ? Date.now() - turn.startedAt : 0;
+          const turnDurationMs = computeTurnDurationMs(turn.startedAt, Date.now());
           logStreamingEvent2({
             kind: "turn_end",
             chatId,
@@ -87743,6 +87750,27 @@ init_peercred();
 // ../src/agents/scaffold.ts
 init_generation_stamp();
 
+// ../src/setup/hindsight-recall-passthrough.ts
+var HINDSIGHT_RECALL_TAG_WEIGHT_SEED = Object.freeze({ sidechain: 0.8 });
+var HINDSIGHT_RECALL_PROMPT_PREAMBLE_DEFAULT = "Relevant memories from past conversations (prioritize recent when " + "conflicting). Only use memories that are directly useful to continue " + "this conversation; ignore the rest:";
+var RECALL_PASSTHROUGH_DEFAULTS = Object.freeze({
+  budget: "low",
+  maxTokens: 1024,
+  preferObservations: true,
+  contextTurns: 2,
+  roles: ["user", "assistant"],
+  promptPreamble: HINDSIGHT_RECALL_PROMPT_PREAMBLE_DEFAULT,
+  tags: [],
+  tagsMatch: "any",
+  tagGroups: {},
+  tagWeights: HINDSIGHT_RECALL_TAG_WEIGHT_SEED,
+  additionalBankFilters: {},
+  transcriptFallback: true,
+  transcriptTailBytes: 262144,
+  maxQueryChars: 800,
+  parallel: true
+});
+
 // ../src/setup/hindsight-recall-tunables.ts
 var RECALL_DEADLINE_HEADROOM_SECONDS = 2;
 var MIN_RECALL_HOOK_TIMEOUT_SECONDS = RECALL_DEADLINE_HEADROOM_SECONDS + 1;
@@ -88018,7 +88046,8 @@ var HINDSIGHT_PERF_OVERRIDE_ONLY_KEYS = new Set([
   "HINDSIGHT_API_CONSOLIDATION_RECALL_MAX_CONCURRENT",
   "HINDSIGHT_MM_REFRESH_MIN_INTERVAL_S",
   "HINDSIGHT_API_TEMPORAL_LANGUAGES",
-  "HINDSIGHT_API_TEMPORAL_MAX_QUERY_CHARS"
+  "HINDSIGHT_API_TEMPORAL_MAX_QUERY_CHARS",
+  "HINDSIGHT_API_TEXT_SEARCH_EXTENSION_NATIVE_LANGUAGE"
 ]);
 var HINDSIGHT_WORKER_SLOT_TYPES = [
   "consolidation",
@@ -88440,27 +88469,6 @@ init_vault();
 // ../src/setup/onboarding.ts
 init_paths();
 
-// ../src/setup/hindsight-recall-passthrough.ts
-var HINDSIGHT_RECALL_TAG_WEIGHT_SEED = Object.freeze({ sidechain: 0.8 });
-var HINDSIGHT_RECALL_PROMPT_PREAMBLE_DEFAULT = "Relevant memories from past conversations (prioritize recent when " + "conflicting). Only use memories that are directly useful to continue " + "this conversation; ignore the rest:";
-var RECALL_PASSTHROUGH_DEFAULTS = Object.freeze({
-  budget: "low",
-  maxTokens: 1024,
-  preferObservations: true,
-  contextTurns: 2,
-  roles: ["user", "assistant"],
-  promptPreamble: HINDSIGHT_RECALL_PROMPT_PREAMBLE_DEFAULT,
-  tags: [],
-  tagsMatch: "any",
-  tagGroups: {},
-  tagWeights: HINDSIGHT_RECALL_TAG_WEIGHT_SEED,
-  additionalBankFilters: {},
-  transcriptFallback: true,
-  transcriptTailBytes: 262144,
-  maxQueryChars: 800,
-  parallel: true
-});
-
 // ../src/repos/bare-clone.ts
 init_paths();
 
@@ -95142,6 +95150,12 @@ function maybeRotate(path3, fs3, maxBytes = TURNS_JSONL_MAX_BYTES) {
 }
 
 // gateway/turn-record-status.ts
+function computeTurnDurationMs2(startedAt, now) {
+  if (typeof startedAt !== "number" || !Number.isFinite(startedAt) || startedAt <= 0) {
+    return 0;
+  }
+  return Math.max(0, now - startedAt);
+}
 function computeTurnStatus(turn) {
   switch (turn.deliveryOutcome) {
     case "failed":
@@ -95170,7 +95184,7 @@ function buildTurnRecord(turn, endedAt) {
   return {
     ts: Math.floor(endedAt / 1000),
     agent: turn.agent,
-    duration_ms: turn.startedAt > 0 ? endedAt - turn.startedAt : 0,
+    duration_ms: computeTurnDurationMs2(turn.startedAt, endedAt),
     tools: turn.toolCallCount ?? 0,
     status: computeTurnStatus(turn),
     turn_id: turn.turnId,
@@ -96933,7 +96947,7 @@ function buildSilencePokeOptions(deps) {
       const tearsDownLiveTurn = turnMatchesFallback && wedgedTurn != null && turnLiveForItsTopic(wedgedTurn);
       const turnStartedAt = activeTurnStartedAt.get(fbKey);
       if (turnStartedAt != null) {
-        const turnDurationMs = Date.now() - turnStartedAt;
+        const turnDurationMs = computeTurnDurationMs(turnStartedAt, Date.now());
         const outboundMetrics = getOutboundMetrics2(fbKey);
         emitRuntimeMetric2({
           kind: "turn_ended",
@@ -103323,10 +103337,10 @@ function startOutboxSweep(deps) {
 }
 
 // ../src/build-info.ts
-var VERSION2 = "0.20.11";
-var COMMIT_SHA = "e083a99d";
-var COMMIT_DATE = "2026-08-06T04:35:43Z";
-var LATEST_PR = 4449;
+var VERSION2 = "0.20.12";
+var COMMIT_SHA = "298e1e15";
+var COMMIT_DATE = "2026-08-06T12:14:41Z";
+var LATEST_PR = 4468;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -108773,10 +108787,6 @@ function clearQueuedCard(key, messageId) {
 }
 var bannerPinPersistEnabled = !STATIC;
 var toolPinPersistEnabled = !STATIC;
-var TOOL_PIN_TTL_MS = (() => {
-  const v = Number(process.env.SWITCHROOM_TOOL_PIN_TTL_MS);
-  return Number.isFinite(v) && v > 0 ? v : 604800000;
-})();
 function statusPinApi() {
   return createStatusPinApi(() => lockedBot, robustApiCall);
 }
@@ -110377,7 +110387,6 @@ var ALLOWED_TOOLS = new Set([
   "download_attachment",
   "edit_message",
   "send_typing",
-  "pin_message",
   "delete_message",
   "forward_message",
   "get_recent_messages",
@@ -110411,8 +110420,6 @@ async function executeToolCall(tool, args, callerAgentName = null) {
       return executeEditMessage(args);
     case "send_typing":
       return executeSendTyping(args);
-    case "pin_message":
-      return executePinMessage(args);
     case "delete_message":
       return executeDeleteMessage(args);
     case "forward_message":
@@ -111218,27 +111225,6 @@ async function executeSendTyping(args) {
   }
   return { content: [{ type: "text", text: `${action} indicator sent (auto-refreshes every 4s, stops after 30s or next reply)` }] };
 }
-async function executePinMessage(args) {
-  if (!args.chat_id)
-    throw new Error("pin_message: chat_id is required");
-  if (!args.message_id)
-    throw new Error("pin_message: message_id is required");
-  const pinChatId = String(args.chat_id ?? "");
-  assertAllowedChat(pinChatId);
-  const pinMsgId = Number(args.message_id);
-  await robustApiCall(() => lockedBot.api.pinChatMessage(pinChatId, pinMsgId), { chat_id: pinChatId, verb: "pin_message" });
-  statusPinRightsCache.clear(pinChatId);
-  if (toolPinPersistEnabled) {
-    const toolPinKey = `tool:${pinChatId}:${pinMsgId}`;
-    mutateStatusPinRow(STATUS_PIN_STORE_PATH, statusPinStoreFs, toolPinKey, {
-      pinKey: toolPinKey,
-      chatId: pinChatId,
-      messageId: pinMsgId,
-      expiresAt: Date.now() + TOOL_PIN_TTL_MS
-    });
-  }
-  return { content: [{ type: "text", text: `pinned message ${args.message_id}` }] };
-}
 async function executeDeleteMessage(args) {
   if (!args.chat_id)
     throw new Error("delete_message: chat_id is required");
@@ -117137,6 +117123,10 @@ async function startGateway() {
               const raw = Number(process.env.SWITCHROOM_TG_WORKER_FEED_MAX_ROWS);
               return Number.isInteger(raw) && raw > 0 ? raw : undefined;
             })();
+            const workerFeedFirstPaintMs = (() => {
+              const raw = Number(process.env.SWITCHROOM_TG_WORKER_FEED_FIRST_PAINT_MS);
+              return Number.isInteger(raw) && raw > 0 ? raw : undefined;
+            })();
             const foregroundNestingEnabled = process.env.SWITCHROOM_FOREGROUND_SUBAGENT_NESTING !== "0";
             const orphanStatusEnabled = isOrphanSubagentStatusEnabled(process.env.SWITCHROOM_ORPHAN_SUBAGENT_STATUS);
             if (workerActivityFeed != null) {
@@ -117159,6 +117149,7 @@ async function startGateway() {
               },
               floodWaitRemainingMs: probeFloodWaitRemainingMs,
               maxRows: workerFeedMaxRows,
+              firstPaintMinMs: workerFeedFirstPaintMs,
               staleWorkerTtlMs: resolveInflightTerminalCapMs() + WORKER_FEED_STALE_TTL_MARGIN_MS,
               absoluteRowLifetimeCapMs: resolveInflightTerminalCapMs() * WORKER_FEED_ABSOLUTE_ROW_LIFETIME_CAP_MULTIPLE,
               groupMessageLifetimeCapMs: WORKER_FEED_GROUP_MESSAGE_LIFETIME_CAP_MS,

package/telegram-plugin/dist/server.js

@@ -24962,18 +24962,6 @@ var init_bridge = __esm(async () => {
         required: ["chat_id"]
       }
     },
-    {
-      name: "pin_message",
-      description: "Pin a message in a Telegram chat. Useful for important outputs the user wants to find later. Requires admin rights in groups.",
-      inputSchema: {
-        type: "object",
-        properties: {
-          chat_id: { type: "string" },
-          message_id: { type: "string" }
-        },
-        required: ["chat_id", "message_id"]
-      }
-    },
     {
       name: "delete_message",
       description: "Delete a message the bot previously sent. Prefer edit_message if you just want to update text \u2014 delete_message is for true removal.",

package/telegram-plugin/gateway/gateway.ts

@@ -8370,8 +8370,7 @@ const statusPinClaims = new Map<string, StatusPinClaim>()
 // Rights-aware negative cache (#3024): chats where an auto status-pin attempt
 // failed with the permanent "not enough rights to manage pinned messages" 400.
 // Per-process only — a restart clears it so a later-granted pin right re-enables
-// auto-pin. The explicit `pin_message` MCP tool deliberately does NOT consult
-// this cache (it always attempts and surfaces the error to the agent).
+// auto-pin.
 const statusPinRightsCache = new PinRightsCache()
 
 // Durable snapshot of the pin claim set on the persistent per-agent volume
@@ -8466,21 +8465,16 @@ const BANNER_PIN_KEY = 'banner:owner'
 // run → no-op). The boot-cleanup gate below is widened to cover this.
 const bannerPinPersistEnabled = !STATIC
 
-// `pin_message` MCP-tool pin registration (#3001). Tool pins ride the same
-// shared status-pins.json store under `tool:<chatId>:<messageId>` keys, but
-// with a TTL row (`expiresAt`): a tool pin is a deliberate agent action with
-// no "work finished" event, so a restart does NOT reset it — boot cleanup
-// keeps unexpired tool rows and only unpins them once the TTL lapses (the
-// backstop against agent-pinned messages accumulating forever). Independent
-// of PIN_STATUS_WHILE_WORKING (it gates the auto status pin, not the tool).
+// LEGACY `tool:` pin drain (#3001; the `pin_message` MCP tool was retired in
+// #4452). No new `tool:<chatId>:<messageId>` rows are ever written now that the
+// tool is gone, but rows an earlier build persisted may still sit in the shared
+// status-pins.json with a TTL (`expiresAt`). This flag keeps the boot cleanup /
+// stale-pin sweep aware of those legacy rows so they are still expired and
+// drained correctly on upgrade — an unexpired legacy row is preserved across
+// boots (never reaped as if it were a work-scoped card), then unpinned once its
+// TTL lapses, exactly as before. Independent of PIN_STATUS_WHILE_WORKING.
+// Self-clears within one TTL window since nothing writes new tool rows.
 const toolPinPersistEnabled = !STATIC
-// 7 days: generous — an agent-pinned message the operator still cares about
-// after a week has usually been re-pinned or acted on; anything older is the
-// stale-pin long tail this issue exists to clear. Override for tuning.
-const TOOL_PIN_TTL_MS = (() => {
-  const v = Number(process.env.SWITCHROOM_TOOL_PIN_TTL_MS)
-  return Number.isFinite(v) && v > 0 ? v : 7 * 24 * 60 * 60_000
-})()
 
 // Persist (or drop) the slot-banner's pin row into the shared store. Routes
 // through mutateStatusPinRow: a read-modify-write for ONLY the banner:owner key,
@@ -8950,8 +8944,7 @@ async function reconcileStatusPin(
   // "not enough rights to manage pinned messages" 400 in a supergroup took the
   // whole gateway down (marko, 2026-07-01). Auto status-pin is cosmetic; it
   // must NEVER be able to crash the gateway. Any throw here is logged and
-  // absorbed. (The `pin_message` MCP tool still surfaces failures to the agent
-  // as a normal tool-error — that path is `executePinMessage`, not this one.)
+  // absorbed.
   try {
     // Serialize per pinKey (F2): reconcileStatusPinInner reads `prev` from the
     // in-memory claim map at its top, so overlapping same-key reconciles must
@@ -11808,7 +11801,7 @@ if (isGatewayMain && !STATIC) {
  *  bridge from calling arbitrary functions by name. */
 const ALLOWED_TOOLS = new Set([
   'reply', 'progress_update', 'react', 'download_attachment',
-  'edit_message', 'send_typing', 'pin_message', 'delete_message',
+  'edit_message', 'send_typing', 'delete_message',
   'forward_message', 'get_recent_messages',
   'send_checklist', 'update_checklist',
   'ask_user',
@@ -11844,8 +11837,6 @@ async function executeToolCall(
       return executeEditMessage(args)
     case 'send_typing':
       return executeSendTyping(args)
-    case 'pin_message':
-      return executePinMessage(args)
     case 'delete_message':
       return executeDeleteMessage(args)
     case 'forward_message':
@@ -13195,44 +13186,6 @@ async function executeSendTyping(args: Record<string, unknown>): Promise<unknown
   return { content: [{ type: 'text', text: `${action} indicator sent (auto-refreshes every 4s, stops after 30s or next reply)` }] }
 }
 
-async function executePinMessage(args: Record<string, unknown>): Promise<unknown> {
-  if (!args.chat_id) throw new Error('pin_message: chat_id is required')
-  if (!args.message_id) throw new Error('pin_message: message_id is required')
-  const pinChatId = String(args.chat_id ?? '')
-  assertAllowedChat(pinChatId)
-  // #1075: wrap through robustApiCall so flood-wait / transient network
-  // errors are retried. THREAD_NOT_FOUND on a stale topic surfaces to the
-  // agent as a tool-error — pinning a vanished message is genuinely a
-  // failure the agent should see.
-  const pinMsgId = Number(args.message_id)
-  await robustApiCall(
-    () => lockedBot.api.pinChatMessage(pinChatId, pinMsgId), // allow-raw-pin: MCP `pin_message` tool — an explicit, agent-requested pin of an arbitrary message, not a progress surface with a claim.
-    { chat_id: pinChatId, verb: 'pin_message' },
-  )
-  // An explicit pin succeeded here, so the bot demonstrably HAS pin rights in
-  // this chat now — clear any auto-pin negative-cache entry (#3024) so the auto
-  // status-pin path resumes immediately rather than waiting for a restart. The
-  // explicit tool itself never consults the cache; a failure above still
-  // surfaces to the agent as a normal tool error (robustApiCall rethrows).
-  statusPinRightsCache.clear(pinChatId)
-  // #3001: register the tool pin in the shared status-pin store under a
-  // `tool:` key so it is no longer fire-and-forget. Unlike work-scoped
-  // fg:/wk: rows a tool pin has no "work finished" event, so a restart does
-  // NOT reset it — boot cleanup keeps the row until its TTL, then unpins the
-  // (likely long-forgotten) message. Best-effort fire-and-forget: a store
-  // failure must never fail the tool call the pin already landed for.
-  if (toolPinPersistEnabled) {
-    const toolPinKey = `tool:${pinChatId}:${pinMsgId}`
-    void mutateStatusPinRow(STATUS_PIN_STORE_PATH, statusPinStoreFs, toolPinKey, { // allow-raw-pin-store: records the TTL-scoped `tool:` row for the explicit pin above so the boot sweep can expire it.
-      pinKey: toolPinKey,
-      chatId: pinChatId,
-      messageId: pinMsgId,
-      expiresAt: Date.now() + TOOL_PIN_TTL_MS,
-    })
-  }
-  return { content: [{ type: 'text', text: `pinned message ${args.message_id}` }] }
-}
-
 async function executeDeleteMessage(args: Record<string, unknown>): Promise<unknown> {
   if (!args.chat_id) throw new Error('delete_message: chat_id is required')
   if (!args.message_id) throw new Error('delete_message: message_id is required')
@@ -23874,6 +23827,14 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
               const raw = Number(process.env.SWITCHROOM_TG_WORKER_FEED_MAX_ROWS)
               return Number.isInteger(raw) && raw > 0 ? raw : undefined
             })()
+            // First-paint hold for a prose-silent sub-agent card. Unset /
+            // non-positive → the feed's built-in default (4000ms). Operator
+            // override (SWITCHROOM_TG_WORKER_FEED_FIRST_PAINT_MS) lets first
+            // paint be retuned/reverted (e.g. back to 8000) without a redeploy.
+            const workerFeedFirstPaintMs = (() => {
+              const raw = Number(process.env.SWITCHROOM_TG_WORKER_FEED_FIRST_PAINT_MS)
+              return Number.isInteger(raw) && raw > 0 ? raw : undefined
+            })()
             // Model A — foreground sub-agent nesting in the parent's live
             // activity draft. ON by default; this edits the SAME activity-
             // summary message the tool_label feed already owns (not the
@@ -23947,6 +23908,10 @@ async function startGateway(): Promise<void> {  // #2996 P0c: the boot IIFE, now
               // channels.telegram.worker_feed.max_rows via the config cascade
               // (scaffold emits SWITCHROOM_TG_WORKER_FEED_MAX_ROWS); unset → 8.
               maxRows: workerFeedMaxRows,
+              // First-paint hold for a prose-silent worker's initial card.
+              // Unset → the feed's built-in default (4000ms); the operator
+              // override SWITCHROOM_TG_WORKER_FEED_FIRST_PAINT_MS retunes it.
+              firstPaintMinMs: workerFeedFirstPaintMs,
               // Backstop TTL for the feed's stale-row reaper, DERIVED in code
               // from the watcher's effective in-flight terminal cap (same env /
               // default the watcher itself resolves) plus a margin — NOT a

package/telegram-plugin/gateway/liveness-wiring.ts

@@ -21,6 +21,7 @@ import * as silencePoke from '../silence-poke.js'
 import * as signalTracker from '../turn-signal-tracker.js'
 import * as pendingProgress from '../pending-work-progress.js'
 import { emitRuntimeMetric } from '../runtime-metrics.js'
+import { computeTurnDurationMs } from './turn-record-status.js'
 import { logStreamingEvent } from '../streaming-metrics.js'
 import { clearSilentEndState } from '../silent-end.js'
 import { purgeStaleTurnsForChat } from './turn-state-purge.js'
@@ -377,7 +378,11 @@ export function buildSilencePokeOptions(deps: LivenessWiringDeps): Parameters<ty
       turnMatchesFallback && wedgedTurn != null && turnLiveForItsTopic(wedgedTurn)
     const turnStartedAt = activeTurnStartedAt.get(fbKey)
     if (turnStartedAt != null) {
-      const turnDurationMs = Date.now() - turnStartedAt
+      // Guard shared with buildTurnRecord + the stream-render turn_ended paths:
+      // a 0 / bogus start must never emit `Date.now() - 0` (an absolute epoch
+      // value) as a duration. This path previously did a bare subtraction and
+      // poisoned the turn_ended dataset when `activeTurnStartedAt` held 0.
+      const turnDurationMs = computeTurnDurationMs(turnStartedAt, Date.now())
       const outboundMetrics = signalTracker.getOutboundMetrics(fbKey)
       emitRuntimeMetric({
         kind: 'turn_ended',

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

@@ -352,9 +352,10 @@ export function collectSweepTargets(input: {
 
 /**
  * The messageIds in `chatId` that must SURVIVE a drain because they belong to
- * deliberately-retained store rows: unexpired time-scoped `tool:` pins (the
- * `pin_message` MCP tool, #3001), which `runStatusPinBootCleanup` intentionally
- * KEEPS across restarts. Work-scoped rows (no `expiresAt`) are stale by
+ * deliberately-retained store rows: unexpired time-scoped `tool:` pins (legacy
+ * rows from the retired `pin_message` MCP tool, #3001 / #4452 — no new ones are
+ * written), which `runStatusPinBootCleanup` intentionally KEEPS across restarts
+ * until they expire. Work-scoped rows (no `expiresAt`) are stale by
  * definition after a restart and are NOT re-pin candidates; expired
  * time-scoped rows are due for sweeping.
  */

package/telegram-plugin/gateway/status-pin-store.ts

@@ -17,7 +17,8 @@
  * — the turn it represented is over or crashed), dropping rows only after a
  * successful unpin (failed ones are retained with an attempt counter for a
  * next-boot retry — see runStatusPinBootCleanup). Time-scoped `tool:` rows
- * (the `pin_message` MCP tool, #3001) survive boots until their `expiresAt`.
+ * (legacy pins from the retired `pin_message` MCP tool, #3001 / #4452 — no new
+ * ones are written) survive boots until their `expiresAt`.
  * It does NOT re-adopt or re-pin — it only cleans up.
  *
  * Shape choice — SNAPSHOT, not append-log, mirroring obligation-store.ts. The
@@ -78,10 +79,10 @@ export interface PersistedStatusPin {
   /** Wall-clock ms after which this pin is stale and boot cleanup unpins it.
    *  Rows WITHOUT this field are work-scoped (fg:/wk:/banner:) — stale the
    *  moment their owning session dies, so boot cleanup unpins them
-   *  unconditionally. Rows WITH it (the `tool:` pins written by the
-   *  `pin_message` MCP tool, #3001) represent deliberate agent pins that have
-   *  no "work finished" event: they SURVIVE restarts and are only swept once
-   *  expired. */
+   *  unconditionally. Rows WITH it (legacy `tool:` pins from the retired
+   *  `pin_message` MCP tool, #3001 / #4452 — no new ones are written)
+   *  represented deliberate agent pins with no "work finished" event: they
+   *  SURVIVE restarts and are only swept once expired. */
   expiresAt?: number
   /** Boot-cleanup unpin retry counter (#3001). Incremented each boot the
    *  unpin fails (flood-wait exhausted / transient 5xx); the row is retained
@@ -282,10 +283,10 @@ export function pinnedMessageIsOurs(
  * record whose pin MAY have landed in Telegram, so we must treat it exactly
  * like a confirmed one and unpin it.
  *
- * TIME-SCOPED rows (`tool:` pins from the `pin_message` MCP tool, carrying
- * `expiresAt`) have no "work finished" event, so a restart does NOT reset
- * them: an unexpired row is RETAINED untouched across boots and only unpinned
- * once `now >= expiresAt`.
+ * TIME-SCOPED rows (legacy `tool:` pins from the retired `pin_message` MCP
+ * tool, #4452, carrying `expiresAt`) have no "work finished" event, so a
+ * restart does NOT reset them: an unexpired row is RETAINED untouched across
+ * boots and only unpinned once `now >= expiresAt`.
  *
  * RETRY-SAFETY (#3001): a row is dropped only AFTER its unpin resolves. A
  * failing unpin (flood-wait exhausted / transient 5xx) retains the row with an

package/telegram-plugin/gateway/stream-render.ts

@@ -90,7 +90,7 @@ import { formatTurnLifecycle } from './status-surface-log.js'
 import { removeTurnActiveMarker, touchTurnActiveMarker, writeTurnActiveMarker } from './turn-active-marker.js'
 import { withTurnEndGateBackstop } from './turn-end-gate-backstop.js'
 import { decideTurnEndGate } from './turn-end-gate.js'
-import { finalizeBackstopSendGated } from './turn-record-status.js'
+import { finalizeBackstopSendGated, computeTurnDurationMs } from './turn-record-status.js'
 import type { SilentEndDeps } from '../silent-end.js'
 import type { ChatKey as _ChatKey } from './inbound-delivery-machine.js'
 import type { SessionEvent } from '../session-tail.js'
@@ -2174,7 +2174,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
             chatId,
             threadId,
             turnId: turn.turnId,
-            turnDurationMs: turn.startedAt > 0 ? Date.now() - turn.startedAt : 0,
+            turnDurationMs: computeTurnDurationMs(turn.startedAt, Date.now()),
             reactionCount: reactionTransitionCounts.get(tKey) ?? 0,
           })
         }
@@ -2214,7 +2214,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
         // still appear in turn-duration graphs.
         {
           const sKey = streamKey(chatId, threadId)
-          const turnDurationMs = turn.startedAt > 0 ? Date.now() - turn.startedAt : 0
+          const turnDurationMs = computeTurnDurationMs(turn.startedAt, Date.now())
           logStreamingEvent({
             kind: 'turn_end',
             chatId,
@@ -2799,7 +2799,7 @@ export function handleSessionEvent(deps: StreamRenderDeps, ev: SessionEvent): vo
       finalizeStatusReaction(chatId, threadId, terminalReason)
       {
         const sKey = streamKey(chatId, threadId)
-        const turnDurationMs = turn.startedAt > 0 ? Date.now() - turn.startedAt : 0
+        const turnDurationMs = computeTurnDurationMs(turn.startedAt, Date.now())
         logStreamingEvent({
           kind: 'turn_end',
           chatId,

package/telegram-plugin/gateway/turn-record-status.ts

@@ -24,6 +24,37 @@
  */
 export type DeliveryOutcome = 'delivered' | 'failed' | 'suppressed'
 
+/**
+ * The ONE way a turn's `duration_ms` is computed, shared by every emitter
+ * (`buildTurnRecord` → turns.jsonl, and all three `turn_ended` runtime-metric
+ * sites: the two stream-render turn-end paths + the liveness framework_fallback).
+ *
+ * Why a single helper: the three `turn_ended` emitters each hand-rolled the
+ * subtraction, and one drifted. `stream-render.ts` guarded with
+ * `startedAt > 0 ? now - startedAt : 0`; the framework_fallback path in
+ * `liveness-wiring.ts` did a bare `Date.now() - turnStartedAt` with only a
+ * `!= null` presence check. When `activeTurnStartedAt` held `0` (or any
+ * non-positive / non-finite value), that path emitted `duration_ms = now - 0`,
+ * i.e. the absolute Unix-epoch-ms — a ~56,000-year "duration". This poisoned the
+ * analysed turn_ended dataset (observed: 110 rows where `duration_ms === ts`),
+ * making every latency aggregate unusable.
+ *
+ * The invariant this helper enforces: a `duration_ms` is ALWAYS a non-negative
+ * elapsed-milliseconds value derived from a positive, finite start stamp — never
+ * an absolute epoch value, never negative (clock step back), never NaN. A start
+ * that is missing / zero / bogus yields `0` (a bounded, filterable sentinel)
+ * instead of a value that destroys aggregates.
+ */
+export function computeTurnDurationMs(
+  startedAt: number | null | undefined,
+  now: number,
+): number {
+  if (typeof startedAt !== 'number' || !Number.isFinite(startedAt) || startedAt <= 0) {
+    return 0
+  }
+  return Math.max(0, now - startedAt)
+}
+
 /** The status strings written to turns.jsonl. `send_failed` is new in PR B. */
 export type TurnStatus = 'complete' | 'no_reply' | 'send_failed'
 
@@ -261,7 +292,7 @@ export function buildTurnRecord(
   return {
     ts: Math.floor(endedAt / 1000),
     agent: turn.agent,
-    duration_ms: turn.startedAt > 0 ? endedAt - turn.startedAt : 0,
+    duration_ms: computeTurnDurationMs(turn.startedAt, endedAt),
     tools: turn.toolCallCount ?? 0,
     status: computeTurnStatus(turn),
     turn_id: turn.turnId,