switchroom 0.14.91 → 0.14.93

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

@@ -23781,7 +23781,7 @@ var init_dist = __esm(() => {
 });
 
 // ../src/config/schema.ts
-var CodeRepoEntrySchema, AgentBindMountSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReleaseBlock, NetworkIsolationSchema, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, HostdConfigSchema, SwitchroomConfigSchema;
+var CodeRepoEntrySchema, AgentBindMountSchema, HttpDiffPollSchema, TelegramReactionsPollSchema, PollSpecSchema, ScheduleEntrySchema, AgentSoulSchema, AgentToolsSchema, AgentMemorySchema, HookEntrySchema, AgentHooksSchema, SubagentSchema, SessionSchema, SessionContinuitySchema, TelegramChannelSchema, ChannelsSchema, TIMEZONE_REGEX, ApproverIdSchema, GoogleWorkspaceTierSchema, GoogleWorkspaceConfigSchema, MicrosoftWorkspaceConfigSchema, NotionWorkspaceConfigSchema, AgentGoogleWorkspaceConfigSchema, AgentMicrosoftWorkspaceConfigSchema, AgentNotionWorkspaceConfigSchema, ReactionsSchema, ReleaseBlock, NetworkIsolationSchema, profileFields, ProfileSchema, _omitExtends, defaultsFields, AgentDefaultsSchema, AgentSchema, TelegramConfigSchema, MemoryBackendConfigSchema, VaultConfigSchema, QuotaConfigSchema, AutoReleaseCheckSchema, HostControlConfigSchema, WebServiceConfigSchema, HostdConfigSchema, CronEgressSchema, CronConfigSchema, SwitchroomConfigSchema;
 var init_schema = __esm(() => {
   init_zod();
   CodeRepoEntrySchema = exports_external.object({
@@ -23794,15 +23794,54 @@ var init_schema = __esm(() => {
     target: exports_external.string().optional().describe("Container path the source mounts to. Must be absolute. Defaults to " + "the same path as `source` (matches switchroom's existing dual-mount " + "convention so absolute paths in scaffolded scripts Just Work)."),
     mode: exports_external.enum(["ro", "rw"]).optional().describe("Read-only (default) or read-write. Use `rw` only when the agent " + "must mutate the host path (e.g. editing switchroom source). " + "Default: 'ro'.")
   });
+  HttpDiffPollSchema = exports_external.object({
+    type: exports_external.literal("http-diff"),
+    url: exports_external.string().url().describe("Poll target. Host MUST match the operator egress allowlist (\u00a76.1) \u2014 " + "loopback/private/link-local/non-https are rejected; the IP is " + "resolve-then-pinned against DNS-rebind. Not agent-writable without " + "operator commit."),
+    method: exports_external.enum(["GET", "POST"]).default("GET"),
+    headers: exports_external.record(exports_external.string()).optional(),
+    secrets: exports_external.array(exports_external.string().regex(/^[a-zA-Z0-9_\-/]+$/, "Secret key names must contain only alphanumeric characters, underscores, hyphens, and forward slashes")).default([]).describe("Vault keys this poll may inject into request headers. Each is " + "HOST-PINNED (\u00a76.1): a secret may only be sent to the host it is bound " + "to in operator config, so an approved poll cannot exfil it elsewhere."),
+    diff_jsonpath: exports_external.string().describe("JSONPath into the response; the extracted value is compared to state_key."),
+    state_key: exports_external.string().describe("Key under /state/agent/poll-state.json holding the last-seen value.")
+  });
+  TelegramReactionsPollSchema = exports_external.object({
+    type: exports_external.literal("telegram-reactions"),
+    chat_id: exports_external.union([exports_external.string().min(1), exports_external.number().int()]).describe("Chat to scan for reactions (model-free internal gateway query)."),
+    emoji: exports_external.string().min(1).describe("Reaction emoji that marks a message for capture (e.g. \uD83D\uDC68\u200d\uD83D\uDCBB)."),
+    lookback: exports_external.number().int().positive().max(200).default(40),
+    state_key: exports_external.string().describe("Key under poll-state.json holding the last-processed message id.")
+  });
+  PollSpecSchema = exports_external.discriminatedUnion("type", [
+    HttpDiffPollSchema,
+    TelegramReactionsPollSchema
+  ]);
   ScheduleEntrySchema = exports_external.object({
     cron: exports_external.string().describe("Cron expression (e.g., '0 8 * * *')"),
-    prompt: exports_external.string().describe("Prompt to send at the scheduled time"),
-    model: exports_external.string().optional().describe("DEPRECATED / IGNORED. Pre-v0.8 the singleton scheduler ran each " + "task as an isolated headless invocation and could set --model per " + "task. Post cron-fold-in (v0.8) the fire is injected into the agent's " + "running session, so it always uses the agent's configured model " + "\u2014 this field has no effect. Accepted (optional) only so existing " + "configs keep validating; set the model at the agent level instead. " + "See docs/scheduling.md."),
+    prompt: exports_external.string().describe("Prompt to send at the scheduled time (the escalation prompt when kind=poll; templated with {{diff}})."),
+    kind: exports_external.enum(["poll", "prompt"]).optional().describe("Tier-0 routing (docs/rfcs/cheap-cron-sessions.md). 'prompt' (default) " + "fires a model turn every tick (Tier 1/2 per `context`). 'poll' runs a " + "model-free deterministic check (requires `poll`) and only escalates to " + "a model fire on a hit. Honoured only when SWITCHROOM_CHEAP_CRON is on."),
+    poll: PollSpecSchema.optional().describe("Required iff kind=poll. The declarative poll spec."),
+    model: exports_external.string().optional().describe("Cron model hint. Reactivated by SWITCHROOM_CHEAP_CRON (was DEPRECATED/" + "IGNORED in v0.8). A known-cheap id (sonnet/haiku family) routes the " + "fire to a fresh cheap cron session (Tier 1, `context: fresh`); 'opus', " + "a custom id, or unset routes to the agent's live session (Tier 2, " + "`context: agent`) \u2014 the conservative default that preserves pre-v0.8 " + "behaviour. Note: a live session's model is fixed at launch, so on Tier " + "2 this is informational. See docs/scheduling.md."),
+    context: exports_external.enum(["fresh", "agent"]).optional().describe("Does this cron need the agent, or just a model? 'fresh' \u2192 a minimal-" + "context cheap cron session (Tier 1). 'agent' \u2192 the agent's live " + "session with full persona/memory (Tier 2). Unset \u2192 inferred from " + "`model` (cheap\u2192fresh, else agent). Honoured only when " + "SWITCHROOM_CHEAP_CRON is on."),
     secrets: exports_external.array(exports_external.string().regex(/^[a-zA-Z0-9_\-/]+$/, "Secret key names must contain only alphanumeric characters, underscores, hyphens, and forward slashes")).default([]).describe("Vault key names this cron task may read via the vault-broker daemon. " + "Empty by default \u2014 broker requests for unlisted keys are denied. " + "Note: this is misconfiguration protection (a typo in cron-A doesn't " + "accidentally read cron-B's keys) rather than a security boundary \u2014 " + "anyone who can edit cron scripts can also edit switchroom.yaml, and " + "anyone with the vault passphrase can read the vault file directly. " + "See docs/configuration.md for the full framing."),
     topic: exports_external.union([
       exports_external.string().min(1, "topic alias must be non-empty"),
       exports_external.number().int().positive("topic ID must be a positive integer")
     ]).optional().describe("Forum topic this cron fires into when the owning agent is in " + "supergroup-owned mode (channels.telegram.chat_id set). Either a " + 'string alias resolved against `topic_aliases` (e.g. "planning") ' + "or a numeric topic ID. Falls back to the agent's `default_topic_id` " + "when unset. Ignored for agents in fleet-shared or dm_only mode. " + "Alias-resolution happens at config-load \u2014 typos surface immediately. " + "See docs/rfcs/supergroup-mode.md.")
+  }).superRefine((entry, ctx) => {
+    const kind = entry.kind ?? "prompt";
+    if (kind === "poll" && !entry.poll) {
+      ctx.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        path: ["poll"],
+        message: "kind: poll requires a `poll` spec (http-diff or telegram-reactions)."
+      });
+    }
+    if (kind === "prompt" && entry.poll) {
+      ctx.addIssue({
+        code: exports_external.ZodIssueCode.custom,
+        path: ["poll"],
+        message: "`poll` is only valid when kind: poll."
+      });
+    }
   });
   AgentSoulSchema = exports_external.object({
     name: exports_external.string().describe("Agent persona name (e.g., 'Coach', 'Sage')"),
@@ -24249,6 +24288,13 @@ var init_schema = __esm(() => {
     config_edit_enabled: exports_external.boolean().default(false).describe("Opt-in toggle for the `config_propose_edit` hostd verb (RFC " + "admin-agent-config-edit \u00a73). Default false \u2014 the verb returns " + "`E_CONFIG_EDIT_DISABLED` until the operator explicitly flips " + "this to true. When true (and once PR 1c lands the apply path), " + "admin agents can propose unified-diff patches against " + "`/state/config/switchroom.yaml`, gated by an operator approval " + "card in the primary chat. Same trust posture as `update_apply` " + "and `agent_restart`: the human-in-the-loop tap is the security " + "boundary, not the agent's judgement."),
     config_edit_rate_per_hour: exports_external.number().int().min(1).max(20).default(3).describe("Per-requesting-agent rate cap for `config_propose_edit` cards " + "(RFC admin-agent-config-edit \u00a75). Default 3 cards/hour; min 1, " + "max 20. Implemented as a sqlite token bucket in PR 1c; the " + "field is wired here in PR 1a so operators can pin it before the " + "limiter is live. Above the cap, the verb returns " + "`E_RATE_LIMITED` without raising a card.")
   });
+  CronEgressSchema = exports_external.object({
+    allowed_hosts: exports_external.array(exports_external.string().min(1)).default([]).describe("Hosts a poll may reach (exact, https-only). loopback/private/IP-literal are always rejected."),
+    secret_bindings: exports_external.record(exports_external.string(), exports_external.string().min(1)).default({}).describe("secretName \u2192 the single host it may be sent to. A poll carrying a secret to any other host is rejected.")
+  });
+  CronConfigSchema = exports_external.object({
+    egress: CronEgressSchema.optional().describe("SSRF/exfil fence for http-diff polls.")
+  });
   SwitchroomConfigSchema = exports_external.object({
     switchroom: exports_external.object({
       version: exports_external.literal(1).describe("Config schema version"),
@@ -24297,7 +24343,8 @@ var init_schema = __esm(() => {
     profiles: exports_external.record(exports_external.string(), ProfileSchema).optional().describe("Named profile definitions. Agents reference via `extends: <name>`. " + "Inline profiles declared here take priority over filesystem " + "profiles/<name>/ directories when both exist."),
     agents: exports_external.record(exports_external.string().regex(/^[a-z0-9][a-z0-9_-]{0,50}$/, {
       message: "Agent name must start with a letter/digit, contain only lowercase letters/digits/hyphens/underscores, and be at most 51 characters (Telegram callback_data byte limit)"
-    }), AgentSchema).describe("Map of agent name to agent configuration")
+    }), AgentSchema).describe("Map of agent name to agent configuration"),
+    cron: CronConfigSchema.optional().describe("Cheap-cron settings (docs/rfcs/cheap-cron-sessions.md). Operator-owned " + "egress allowlist + host-pinned secret bindings for Tier-0 http-diff " + "polls (\u00a76.1). Required to enable any http-diff poll; not agent-writable.")
   });
 });
 
@@ -47522,6 +47569,18 @@ function createPendingInboundBuffer(opts = {}) {
   };
 }
 
+// gateway/cron-session.ts
+var CRON_IDENTITY_SUFFIX = "-cron";
+function cronIdentity(agent) {
+  return `${agent}${CRON_IDENTITY_SUFFIX}`;
+}
+function isCronIdentity(name) {
+  return typeof name === "string" && name.endsWith(CRON_IDENTITY_SUFFIX);
+}
+function resolveInjectTarget(agentName3, meta) {
+  return meta?.session === "cron" ? cronIdentity(agentName3) : agentName3;
+}
+
 // gateway/obligation-ledger.ts
 class ObligationLedger {
   maxRepresents;
@@ -47578,18 +47637,21 @@ class ObligationLedger {
     return best;
   }
   decideAtIdle(opts) {
-    const o = opts != null && opts.graceMs > 0 ? this.oldestEligible(opts.now, opts.graceMs) : this.oldest();
+    const useEligible = opts != null && (opts.graceMs > 0 || opts.backgroundWorkActive === true);
+    const o = useEligible ? this.oldestEligible(opts.now, opts.graceMs, opts.backgroundWorkActive === true, opts.backgroundGraceMs ?? 0) : this.oldest();
     if (o === undefined)
       return { action: "none" };
     if (o.representCount >= this.maxRepresents)
       return { action: "escalate", obligation: o };
     return { action: "represent", obligation: o };
   }
-  oldestEligible(now, graceMs) {
+  oldestEligible(now, graceMs, backgroundWorkActive, backgroundGraceMs) {
     let best;
     for (const o of this.open.values()) {
       if (o.lastTurnEndedAt != null && now - o.lastTurnEndedAt < graceMs)
         continue;
+      if (backgroundWorkActive && backgroundGraceMs > 0 && now - o.openedAt < backgroundGraceMs)
+        continue;
       if (best === undefined || o.openedAt < best.openedAt)
         best = o;
     }
@@ -52898,13 +52960,22 @@ function sweepStaleTurnActiveMarker(stateDir, opts) {
     return false;
   }
 }
+function readTurnActiveMarkerAgeMs(stateDir, now) {
+  const path = join32(stateDir, TURN_ACTIVE_MARKER_FILE2);
+  try {
+    const st = statSync10(path);
+    return (now ?? Date.now()) - st.mtimeMs;
+  } catch {
+    return null;
+  }
+}
 
 // ../src/build-info.ts
-var VERSION = "0.14.91";
-var COMMIT_SHA = "e938daab";
-var COMMIT_DATE = "2026-06-09T03:14:21Z";
-var LATEST_PR = 2241;
-var COMMITS_AHEAD_OF_TAG = 0;
+var VERSION = "0.14.93";
+var COMMIT_SHA = "87b62902";
+var COMMIT_DATE = "2026-06-10T08:22:44+10:00";
+var LATEST_PR = null;
+var COMMITS_AHEAD_OF_TAG = 3;
 
 // gateway/boot-version.ts
 function formatRelativeAgo(iso) {
@@ -54129,6 +54200,14 @@ var OBLIGATION_ESCALATE_GRACE_MS = (() => {
   const n = Number(raw);
   return Number.isFinite(n) && n >= 0 ? n : 45000;
 })();
+var OBLIGATION_BACKGROUND_WORK_GRACE_MS = (() => {
+  const raw = process.env.SWITCHROOM_OBLIGATION_BACKGROUND_WORK_GRACE_MS;
+  if (raw == null || raw === "")
+    return 1200000;
+  const n = Number(raw);
+  return Number.isFinite(n) && n >= 0 ? n : 1200000;
+})();
+var TURN_ACTIVE_MARKER_FRESH_MS = 90000;
 var AUTOCLASSIFY_MIDTURN_SHADOW = process.env.SWITCHROOM_AUTOCLASSIFY_MIDTURN_SHADOW !== "0";
 var lastAgentOutputAt = new Map;
 var LAST_OUTPUT_MAX_KEYS = 512;
@@ -55646,6 +55725,13 @@ var inboundSpool = STATIC ? undefined : createInboundSpool({
   }
 });
 var pendingInboundBuffer = createPendingInboundBuffer({ spool: inboundSpool });
+function agentHasInFlightBackgroundWork(now) {
+  if (countRunningWorkers() > 0)
+    return true;
+  const ageMs = readTurnActiveMarkerAgeMs(STATE_DIR, now);
+  return ageMs != null && ageMs < TURN_ACTIVE_MARKER_FRESH_MS;
+}
+var lastBgWorkDeferLogMs = 0;
 function obligationSweep() {
   if (!OBLIGATION_LEDGER_ENABLED)
     return;
@@ -55654,10 +55740,23 @@ function obligationSweep() {
   if (turnInFlightForGate())
     return;
   const agent = process.env.SWITCHROOM_AGENT_NAME ?? "";
-  const decision = obligationLedger.decideAtIdle(OBLIGATION_ESCALATE_GRACE_MS > 0 ? { now: Date.now(), graceMs: OBLIGATION_ESCALATE_GRACE_MS } : undefined);
+  const now = Date.now();
+  const backgroundWorkActive = OBLIGATION_BACKGROUND_WORK_GRACE_MS > 0 && agentHasInFlightBackgroundWork(now);
+  const decision = obligationLedger.decideAtIdle(OBLIGATION_ESCALATE_GRACE_MS > 0 || backgroundWorkActive ? {
+    now,
+    graceMs: OBLIGATION_ESCALATE_GRACE_MS,
+    backgroundWorkActive,
+    backgroundGraceMs: OBLIGATION_BACKGROUND_WORK_GRACE_MS
+  } : undefined);
   const o = decision.obligation;
-  if (decision.action === "none" || o == null)
+  if (decision.action === "none" || o == null) {
+    if (backgroundWorkActive && obligationLedger.hasOpen() && now - lastBgWorkDeferLogMs > 60000) {
+      lastBgWorkDeferLogMs = now;
+      process.stderr.write(`telegram gateway: obligation sweep deferred \u2014 in-flight autonomous sub-agent work ` + `(${obligationLedger.size()} open, bounded ${Math.round(OBLIGATION_BACKGROUND_WORK_GRACE_MS / 60000)}m from receipt)
+`);
+    }
     return;
+  }
   if (decision.action === "represent") {
     if (pendingInboundBuffer.depth(agent) > 0)
       return;
@@ -55718,6 +55817,16 @@ var ipcServer = createIpcServer({
   onClientRegistered(client3) {
     process.stderr.write(`telegram gateway: bridge registered \u2014 agent=${client3.agentName}
 `);
+    if (isCronIdentity(client3.agentName)) {
+      client3.send({ type: "status", status: "agent_connected" });
+      const pending2 = pendingInboundBuffer.drain(client3.agentName ?? "");
+      for (const m of pending2) {
+        try {
+          client3.send(m);
+        } catch {}
+      }
+      return;
+    }
     const bridgeUpEffects = client3.agentName != null ? shadowEmit({ kind: "bridgeUp", at: Date.now() }) : [];
     client3.send({ type: "status", status: "agent_connected" });
     if (client3.agentName != null) {
@@ -55840,6 +55949,11 @@ var ipcServer = createIpcServer({
     }
   },
   onClientDisconnected(client3) {
+    if (isCronIdentity(client3.agentName)) {
+      process.stderr.write(`telegram gateway: cron-session bridge disconnected \u2014 agent=${client3.agentName}
+`);
+      return;
+    }
     if (client3.agentName != null) {
       process.stderr.write(`telegram gateway: bridge disconnected \u2014 agent=${client3.agentName}
 `);
@@ -55887,7 +56001,9 @@ var ipcServer = createIpcServer({
       };
     }
   },
-  onSessionEvent(_client, msg) {
+  onSessionEvent(client3, msg) {
+    if (isCronIdentity(client3.agentName))
+      return;
     if (msg.activeFile)
       lastSessionActiveFile = msg.activeFile;
     const ev = msg.event;
@@ -55987,7 +56103,9 @@ var ipcServer = createIpcServer({
       firstSeenAt: new Date
     });
   },
-  onPtyPartial(_client, msg) {
+  onPtyPartial(client3, msg) {
+    if (isCronIdentity(client3.agentName))
+      return;
     handlePtyPartial(msg.text);
   },
   async onRequestDriveApproval(client3, msg) {
@@ -56212,13 +56330,15 @@ var ipcServer = createIpcServer({
   onInjectInbound(_client, msg) {
     const promptKey = typeof msg.inbound.meta?.prompt_key === "string" ? msg.inbound.meta.prompt_key : "unknown";
     const source = typeof msg.inbound.meta?.source === "string" ? msg.inbound.meta.source : "unknown";
-    const delivered = ipcServer.sendToAgent(msg.agentName, msg.inbound);
-    if (delivered)
+    const target = resolveInjectTarget(msg.agentName, msg.inbound.meta);
+    const toCron = target !== msg.agentName;
+    const delivered = ipcServer.sendToAgent(target, msg.inbound);
+    if (delivered && !toCron)
       markClaudeBusyForInbound(msg.inbound);
-    process.stderr.write(`telegram gateway: inject_inbound agent=${msg.agentName} source=${source} prompt_key=${promptKey} delivered=${delivered}
+    process.stderr.write(`telegram gateway: inject_inbound agent=${msg.agentName} target=${target} source=${source} prompt_key=${promptKey} delivered=${delivered}
 `);
     if (!delivered) {
-      pendingInboundBuffer.push(msg.agentName, msg.inbound);
+      pendingInboundBuffer.push(target, msg.inbound);
     }
   },
   onQuotaWallDetected(_client, msg) {

package/telegram-plugin/gateway/cron-session.ts

@@ -0,0 +1,45 @@
+/**
+ * Cheap-cron session identity — docs/rfcs/cheap-cron-sessions.md §3.3.
+ *
+ * Rather than rekey the gateway's hardened single-bridge machinery
+ * (agentIndex / pendingInboundBuffer / handleRegister, each carrying
+ * subtle race fixes), a Tier-1 cron fire is routed to a SECOND bridge
+ * that registers under a DERIVED identity `<agent>-cron`. To the IPC
+ * layer it is "just another agent", so routing, buffering, disconnect,
+ * and heartbeat all work unchanged. The gateway gates its SINGLETON
+ * status machinery (shadow bridge-state, boot card, currentTurn /
+ * progress card / silence-poke) off the cron identity — which IS the
+ * §2.4 "cron session is status-silent" requirement, so it is one change,
+ * not two.
+ *
+ * The cron session's bridge sets SWITCHROOM_AGENT_NAME=`<agent>-cron`;
+ * the scheduler emits `meta.session='cron'` and the gateway derives the
+ * target via `cronIdentity()`. Pure string fns — pinned in cron-session.test.ts.
+ */
+
+/** Suffix that distinguishes a cron-session bridge from the main agent bridge. */
+export const CRON_IDENTITY_SUFFIX = "-cron";
+
+/** Derive the cron-session bridge identity for an agent. */
+export function cronIdentity(agent: string): string {
+  return `${agent}${CRON_IDENTITY_SUFFIX}`;
+}
+
+/** True iff `name` is a cron-session bridge identity (not a main agent bridge). */
+export function isCronIdentity(name: string | null | undefined): boolean {
+  return typeof name === "string" && name.endsWith(CRON_IDENTITY_SUFFIX);
+}
+
+/** The real agent name behind a (possibly cron) identity. */
+export function baseAgent(name: string): string {
+  return isCronIdentity(name) ? name.slice(0, -CRON_IDENTITY_SUFFIX.length) : name;
+}
+
+/**
+ * Resolve the IPC routing target for an inject_inbound. When the fire
+ * carries `meta.session='cron'` it goes to the derived cron bridge; every
+ * other fire (and all of today's callers) goes to the agent unchanged.
+ */
+export function resolveInjectTarget(agentName: string, meta: Record<string, string> | undefined): string {
+  return meta?.session === "cron" ? cronIdentity(agentName) : agentName;
+}

package/telegram-plugin/gateway/gateway.ts

@@ -287,6 +287,7 @@ import { handleRequestDriveApproval } from './drive-write-approval.js'
 import { handleRequestMs365Approval } from './ms365-write-approval.js'
 import { buildDiffPreviewCard } from './diff-preview-card.js'
 import { createPendingInboundBuffer, redeliverBufferedInbound, idleDrainTick } from './pending-inbound-buffer.js'
+import { isCronIdentity, resolveInjectTarget } from './cron-session.js'
 import {
   ObligationLedger,
   buildObligationRepresentInbound,
@@ -428,6 +429,7 @@ import {
   touchTurnActiveMarker,
   removeTurnActiveMarker,
   sweepStaleTurnActiveMarker,
+  readTurnActiveMarkerAgeMs,
   TURN_ACTIVE_MARKER_FILE,
 } from './turn-active-marker.js'
 import {
@@ -1467,6 +1469,34 @@ const OBLIGATION_ESCALATE_GRACE_MS = (() => {
   return Number.isFinite(n) && n >= 0 ? n : 45_000
 })()
 
+// Background-work escalate-grace ceiling. The 45s grace above is far too short
+// for extended-autonomous sub-agent work: an agent that ack-firsts ("on it")
+// then delegates to a background worker OR an orphaned foreground sub-agent ends
+// its FOREGROUND turn in seconds, but the real answer lands minutes later. The
+// turn-in-flight machine (turn already ended) doesn't see that work, so the
+// sweep would re-present/escalate a false "⚠️ I may have missed this — re-send"
+// while the agent is genuinely researching (the gymbro liven-research case,
+// 2026-06-10). While `agentHasInFlightBackgroundWork()` holds, an open
+// obligation younger than THIS ceiling (from openedAt) is skipped. Bounded BY
+// CONSTRUCTION — a hard wall-clock ceiling, so even a stuck/leaked worker can't
+// suppress escalation forever; the obligation FSM still terminates. This also
+// preserves the represent budget across a restart that kills the work: with the
+// false represents suppressed, the hydrated obligation re-presents (resumes the
+// research) instead of prematurely escalating. Kill switch: =0 → pre-fix
+// behaviour (no background-work grace).
+const OBLIGATION_BACKGROUND_WORK_GRACE_MS = (() => {
+  const raw = process.env.SWITCHROOM_OBLIGATION_BACKGROUND_WORK_GRACE_MS
+  if (raw == null || raw === '') return 20 * 60_000 // 20 min — generous for real research, still bounded
+  const n = Number(raw)
+  return Number.isFinite(n) && n >= 0 ? n : 20 * 60_000
+})()
+// Marker-freshness window for the orphaned-foreground signal. The turn-active
+// marker is touched on every foreground tool_use and on foreground sub-agent
+// JSONL growth, so an mtime younger than this means a sub-agent is touching it
+// RIGHT NOW; older ⇒ the work stopped (or the marker leaked) ⇒ not active.
+// Comfortably exceeds the sub-agent poll cadence so it doesn't flap.
+const TURN_ACTIVE_MARKER_FRESH_MS = 90_000
+
 // ─── Mid-turn auto-classify (steer-vs-queue), SHADOW mode ─────────────────────
 // Today a no-prefix mid-turn message always QUEUES. autoClassifyMidTurnInbound
 // (auto-classify-mid-turn.ts) is the basis for a smarter default using
@@ -5323,24 +5353,72 @@ const pendingInboundBuffer = createPendingInboundBuffer({ spool: inboundSpool })
 //       disconnect (disconnect-flush.ts), and by the 300s silence-poke watchdog;
 //   (3) the escalation send settles — bounded BY CONSTRUCTION via withDeadline
 //       below (grammy has no request timeout, so an unbounded send was the one
-//       way an obligation could get stuck OPEN forever — now closed).
+//       way an obligation could get stuck OPEN forever — now closed);
+//   (4) the background-work grace releases — an obligation skipped because
+//       agentHasInFlightBackgroundWork() is true is bounded by
+//       OBLIGATION_BACKGROUND_WORK_GRACE_MS (a hard wall-clock ceiling from
+//       openedAt). Even a permanently-stuck/leaked worker signal cannot suppress
+//       the act past the ceiling, so this adds NO unbounded liveness dependency:
+//       decideAtIdle ignores the work signal once now ≥ openedAt + ceiling, μ
+//       resumes decreasing, and termination still holds.
 // The only residual liveness assumption is the bridge eventually reconnecting /
 // the process restarting, which the entire gateway's inbound delivery already
 // depends on and which durable spool + boot-replay make self-healing.
+// True when the agent has in-flight autonomous sub-agent work the turn-in-flight
+// gate does NOT see: a running background worker (countRunningWorkers — its row
+// is INSERTed status='running' at dispatch, before the parent turn ends), OR an
+// orphaned/extended-autonomous FOREGROUND sub-agent that outlived its turn and is
+// still touching the turn-active marker (#2240; background activity deliberately
+// does NOT touch the parent marker, so the two signals are complementary).
+// Used ONLY by the obligation sweep to bound a false escalation during genuine
+// post-turn work. The caller already established the turn machine is idle (the
+// `turnInFlightForGate()` early-return), so a fresh marker here means orphaned
+// sub-agent activity (or a just-ended turn within the freshness window — a
+// harmless small extra grace, bounded by the ceiling either way).
+function agentHasInFlightBackgroundWork(now: number): boolean {
+  if (countRunningWorkers() > 0) return true
+  const ageMs = readTurnActiveMarkerAgeMs(STATE_DIR, now)
+  return ageMs != null && ageMs < TURN_ACTIVE_MARKER_FRESH_MS
+}
+// Throttle for the background-work defer diagnostic (the 5s sweep would otherwise
+// log every tick across a multi-minute research window).
+let lastBgWorkDeferLogMs = 0
 function obligationSweep(): void {
   if (!OBLIGATION_LEDGER_ENABLED) return
   if (!obligationLedger.hasOpen()) return
   if (turnInFlightForGate()) return // a turn is running — let it finish/answer
   const agent = process.env.SWITCHROOM_AGENT_NAME ?? ''
+  const now = Date.now()
+  // Background-work grace: while genuine autonomous sub-agent work is in flight
+  // (a running worker, or an orphaned foreground sub-agent — neither visible to
+  // the turn machine), an obligation younger than the ceiling is NOT re-presented
+  // /escalated. Bounded by OBLIGATION_BACKGROUND_WORK_GRACE_MS so escalation
+  // always eventually fires. =0 disables it.
+  const backgroundWorkActive =
+    OBLIGATION_BACKGROUND_WORK_GRACE_MS > 0 && agentHasInFlightBackgroundWork(now)
   // Grace window: skip an obligation whose handling turn ended < grace ago — its
   // trailing slow/worker answer may still be landing (over-escalation fix).
   const decision = obligationLedger.decideAtIdle(
-    OBLIGATION_ESCALATE_GRACE_MS > 0
-      ? { now: Date.now(), graceMs: OBLIGATION_ESCALATE_GRACE_MS }
+    OBLIGATION_ESCALATE_GRACE_MS > 0 || backgroundWorkActive
+      ? {
+          now,
+          graceMs: OBLIGATION_ESCALATE_GRACE_MS,
+          backgroundWorkActive,
+          backgroundGraceMs: OBLIGATION_BACKGROUND_WORK_GRACE_MS,
+        }
       : undefined,
   )
   const o = decision.obligation
-  if (decision.action === 'none' || o == null) return
+  if (decision.action === 'none' || o == null) {
+    if (backgroundWorkActive && obligationLedger.hasOpen() && now - lastBgWorkDeferLogMs > 60_000) {
+      lastBgWorkDeferLogMs = now
+      process.stderr.write(
+        `telegram gateway: obligation sweep deferred — in-flight autonomous sub-agent work ` +
+          `(${obligationLedger.size()} open, bounded ${Math.round(OBLIGATION_BACKGROUND_WORK_GRACE_MS / 60_000)}m from receipt)\n`,
+      )
+    }
+    return
+  }
   if (decision.action === 'represent') {
     // Re-present goes through the bridge → buffer. Only the represent path is
     // gated on an empty buffer (let the existing drain run first, avoid
@@ -5474,6 +5552,19 @@ const ipcServer: IpcServer = createIpcServer({
 
   onClientRegistered(client: IpcClient) {
     process.stderr.write(`telegram gateway: bridge registered — agent=${client.agentName}\n`)
+    // Cheap-cron (§2.4/§3.3): a `<agent>-cron` bridge is the Tier-1 cheap
+    // session. It is STATUS-SILENT — it must NOT drive the gateway's
+    // singleton machinery (shadow bridge-state, warmup, boot card, which all
+    // track the MAIN agent's liveness). Drain any buffered cron fire to it
+    // (so a fire that triggered a lazy spawn lands), then return early.
+    if (isCronIdentity(client.agentName)) {
+      client.send({ type: 'status', status: 'agent_connected' })
+      const pending = pendingInboundBuffer.drain(client.agentName ?? '')
+      for (const m of pending) {
+        try { client.send(m) } catch { /* cron fire drop — best-effort, like today's cron */ }
+      }
+      return
+    }
     // Phase 2b shadow: ONLY emit bridgeUp for the REAL bridge sidecar
     // (with an agent name). Anonymous IPC clients (recall.py, mcp
     // handshakes, etc.) connect briefly without a name and would
@@ -5652,6 +5743,17 @@ const ipcServer: IpcServer = createIpcServer({
   },
 
   onClientDisconnected(client: IpcClient) {
+    // Cheap-cron §2.4: a `<agent>-cron` bridge is the status-silent cron
+    // session. Its disconnect (e.g. B3 lazy idle-teardown) must NOT touch
+    // the MAIN agent's singleton state — emitting bridgeDown (the shadow
+    // state is unkeyed) or flushOnAgentDisconnect (flushes the main agent's
+    // active reactions / disposes its progress driver mid-turn) would be the
+    // "premature 👍" bug for the main session. Symmetric to the cron gate in
+    // onClientRegistered / onSessionEvent / onPtyPartial.
+    if (isCronIdentity(client.agentName)) {
+      process.stderr.write(`telegram gateway: cron-session bridge disconnected — agent=${client.agentName}\n`)
+      return
+    }
     // ONLY log "bridge disconnected" + emit bridgeDown for the REAL
     // bridge sidecar (matching the bridgeUp gate above). Anonymous IPC
     // clients — e.g. recall.py's one-shot legacy update_placeholder
@@ -5722,7 +5824,13 @@ const ipcServer: IpcServer = createIpcServer({
     }
   },
 
-  onSessionEvent(_client: IpcClient, msg: SessionEventForward) {
+  onSessionEvent(client: IpcClient, msg: SessionEventForward) {
+    // Cheap-cron §2.4: the cron session is status-silent — its session
+    // events must not drive the main agent's progress card, transcript
+    // tail, currentTurn, or silence-poke. Its reply still flows (onToolCall
+    // is not gated). currentTurn was never set for a cron fire (onInjectInbound
+    // skips markClaudeBusy), so the card machinery has nothing to attach to.
+    if (isCronIdentity(client.agentName)) return
     // Track the session-tail's attached file for the proactive-
     // compaction occupancy read (see maybeProactiveCompact).
     if (msg.activeFile) lastSessionActiveFile = msg.activeFile
@@ -5954,7 +6062,10 @@ const ipcServer: IpcServer = createIpcServer({
    * `handlePtyPartial` does its own buffering for the
    * partial-before-enqueue race.
    */
-  onPtyPartial(_client: IpcClient, msg: PtyPartialForward) {
+  onPtyPartial(client: IpcClient, msg: PtyPartialForward) {
+    // Cheap-cron §2.4: cron session is status-silent — no visible reply
+    // stream from its PTY tail (it would edit a card the main session owns).
+    if (isCronIdentity(client.agentName)) return
     handlePtyPartial(msg.text)
   },
 
@@ -6291,16 +6402,28 @@ const ipcServer: IpcServer = createIpcServer({
     const source = typeof msg.inbound.meta?.source === 'string'
       ? msg.inbound.meta.source
       : 'unknown'
-    const delivered = ipcServer.sendToAgent(msg.agentName, msg.inbound)
-    if (delivered) markClaudeBusyForInbound(msg.inbound)
+    // Cheap-cron (docs/rfcs/cheap-cron-sessions.md §3.3): a Tier-1 fire
+    // carries meta.session='cron' → route to the derived `<agent>-cron`
+    // bridge (a 2nd interactive Sonnet session in the same container).
+    // Every other fire (and all of today's callers) routes to the agent
+    // unchanged. Route+buffer share the same target so a fire that lands
+    // mid cron-session-spawn buffers under the cron identity and drains to
+    // it on register.
+    const target = resolveInjectTarget(msg.agentName, msg.inbound.meta)
+    const toCron = target !== msg.agentName
+    const delivered = ipcServer.sendToAgent(target, msg.inbound)
+    // Status-silent (§2.4): a cron fire must NOT set the MAIN agent's
+    // currentTurn (progress card / silence-poke). The cron session is
+    // fire-and-forget; its reply is its only Telegram surface.
+    if (delivered && !toCron) markClaudeBusyForInbound(msg.inbound)
     process.stderr.write(
-      `telegram gateway: inject_inbound agent=${msg.agentName} source=${source} prompt_key=${promptKey} delivered=${delivered}\n`,
+      `telegram gateway: inject_inbound agent=${msg.agentName} target=${target} source=${source} prompt_key=${promptKey} delivered=${delivered}\n`,
     )
     // #1150: same buffer-on-failure pattern as vault_grant_approved.
     // Cron fires use this path too — if a cron-driven wake-up lands
     // mid bridge-reconnect, buffer it for the next register.
     if (!delivered) {
-      pendingInboundBuffer.push(msg.agentName, msg.inbound)
+      pendingInboundBuffer.push(target, msg.inbound)
     }
   },
 

package/telegram-plugin/gateway/obligation-ledger.ts

@@ -187,22 +187,61 @@ export class ObligationLedger {
    * genuinely-stale one is still acted on while a freshly-ended one waits. Pure
    * (clock injected via opts.now, mirroring the builder convention). With no opts
    * (or graceMs<=0) this is the pre-grace behaviour exactly.
+   *
+   * BACKGROUND-WORK GRACE (opts.backgroundWorkActive): the 45s `graceMs` above is
+   * far too short for extended-autonomous sub-agent work — an agent that
+   * ack-firsts ("on it") then delegates to a background worker or an orphaned
+   * foreground sub-agent ends its FOREGROUND turn in seconds, but the real answer
+   * lands minutes later. The in-flight machine (turn already ended) does not see
+   * that work, so the sweep would re-present/escalate a false "did I miss this?
+   * re-send" while the agent is genuinely researching (the gymbro liven case,
+   * 2026-06-10). When the gateway reports `backgroundWorkActive` (a running worker
+   * or a freshly-touched turn-active marker), an obligation younger than
+   * `backgroundGraceMs` (measured from openedAt) is SKIPPED. Bounded BY
+   * CONSTRUCTION: `backgroundGraceMs` is a hard wall-clock ceiling, so even a
+   * pathologically-stuck/leaked worker cannot suppress the escalation forever —
+   * once openedAt+backgroundGraceMs passes, the obligation is acted on regardless
+   * of work state, and the FSM still terminates.
    */
-  decideAtIdle(opts?: { now: number; graceMs: number }): LedgerDecision {
-    const o =
-      opts != null && opts.graceMs > 0 ? this.oldestEligible(opts.now, opts.graceMs) : this.oldest()
+  decideAtIdle(opts?: {
+    now: number
+    graceMs: number
+    backgroundWorkActive?: boolean
+    backgroundGraceMs?: number
+  }): LedgerDecision {
+    const useEligible = opts != null && (opts.graceMs > 0 || opts.backgroundWorkActive === true)
+    const o = useEligible
+      ? this.oldestEligible(
+          opts!.now,
+          opts!.graceMs,
+          opts!.backgroundWorkActive === true,
+          opts!.backgroundGraceMs ?? 0,
+        )
+      : this.oldest()
     if (o === undefined) return { action: 'none' }
     if (o.representCount >= this.maxRepresents) return { action: 'escalate', obligation: o }
     return { action: 'represent', obligation: o }
   }
 
-  /** The oldest open obligation whose handling turn ended at least `graceMs` ago
-   *  (or never ended — a still-queued obligation has no lastTurnEndedAt and is
-   *  always eligible; it can't have a trailing answer in flight). */
-  private oldestEligible(now: number, graceMs: number): Obligation | undefined {
+  /** The oldest open obligation that is currently ELIGIBLE to act on — i.e. NOT
+   *  within either grace window:
+   *   - trailing-answer grace: its handling turn ended < `graceMs` ago (a queued
+   *     obligation with no lastTurnEndedAt can't have a trailing answer, so it is
+   *     always eligible on this axis); AND
+   *   - background-work grace: when `backgroundWorkActive`, it was opened <
+   *     `backgroundGraceMs` ago (genuine in-flight autonomous work — bounded by
+   *     the ceiling so a stale/leaked worker can't suppress escalation forever). */
+  private oldestEligible(
+    now: number,
+    graceMs: number,
+    backgroundWorkActive: boolean,
+    backgroundGraceMs: number,
+  ): Obligation | undefined {
     let best: Obligation | undefined
     for (const o of this.open.values()) {
-      if (o.lastTurnEndedAt != null && now - o.lastTurnEndedAt < graceMs) continue // within grace
+      if (o.lastTurnEndedAt != null && now - o.lastTurnEndedAt < graceMs) continue // trailing-answer grace
+      if (backgroundWorkActive && backgroundGraceMs > 0 && now - o.openedAt < backgroundGraceMs)
+        continue // in-flight autonomous work, bounded by the ceiling
       if (best === undefined || o.openedAt < best.openedAt) best = o
     }
     return best