switchroom 0.18.20 → 0.18.21

package/dist/cli/switchroom.js

@@ -2120,7 +2120,7 @@ var init_esm = __esm(() => {
 });
 
 // src/build-info.ts
-var VERSION = "0.18.20", COMMIT_SHA = "f82e440f";
+var VERSION = "0.18.21", COMMIT_SHA = "c237ff59";
 
 // src/cli/resolve-version.ts
 import { existsSync, readFileSync } from "node:fs";
@@ -23799,6 +23799,14 @@ function renderDevProtocolFragment(context = {}, profilesRoot = PROFILES_ROOT) {
   const template = import_handlebars.default.compile(source, { noEscape: true });
   return template(context).trimEnd();
 }
+function renderDelegationGoldenRuleFragment(context = {}, profilesRoot = PROFILES_ROOT) {
+  const fragPath = join4(resolve4(profilesRoot, "_shared"), "delegation-golden-rule.md.hbs");
+  if (!existsSync7(fragPath))
+    return "";
+  const source = readFileSync7(fragPath, "utf-8");
+  const template = import_handlebars.default.compile(source, { noEscape: true });
+  return template(context).trimEnd();
+}
 function renderReplyDisciplineFragment(context = {}, profilesRoot = PROFILES_ROOT) {
   const fragPath = join4(resolve4(profilesRoot, "_shared"), "reply-discipline.md.hbs");
   if (!existsSync7(fragPath))
@@ -27579,6 +27587,13 @@ function scaffoldAgent(name, agentConfigRaw, agentsDir, telegramConfig, switchro
             rendered = rendered.trimEnd() + `
 
 ` + devProtocol + `
+`;
+          }
+          const delegationGoldenRule = renderDelegationGoldenRuleFragment(context);
+          if (delegationGoldenRule) {
+            rendered = rendered.trimEnd() + `
+
+` + delegationGoldenRule + `
 `;
           }
         }
@@ -28462,6 +28477,13 @@ ${baseAppend}` : TELEGRAM_FORMATTING_FLOOR_CARD;
         rendered = rendered.trimEnd() + `
 
 ` + devProtocol + `
+`;
+      }
+      const delegationGoldenRule = renderDelegationGoldenRuleFragment(claudeContext);
+      if (delegationGoldenRule) {
+        rendered = rendered.trimEnd() + `
+
+` + delegationGoldenRule + `
 `;
       }
       if (agentConfig.claude_md_raw) {
@@ -78779,6 +78801,7 @@ function applySubagentsSchema(db) {
     db.exec("ALTER TABLE subagents ADD COLUMN model TEXT");
   }
   db.exec("CREATE INDEX IF NOT EXISTS subagents_jsonl_id ON subagents(jsonl_agent_id)");
+  db.exec("CREATE INDEX IF NOT EXISTS subagents_parent_agent ON subagents(parent_agent_id)");
 }
 function mapSubagentRow(row) {
   return {

package/dist/host-control/main.js

@@ -26605,7 +26605,7 @@ import { existsSync as existsSync9, readFileSync as readFileSync7 } from "node:f
 import { dirname as dirname4, join as join7 } from "node:path";
 
 // src/build-info.ts
-var VERSION = "0.18.20";
+var VERSION = "0.18.21";
 
 // src/cli/resolve-version.ts
 function readPackageVersion() {

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.18.20",
+  "version": "0.18.21",
   "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/profiles/_shared/delegation-golden-rule.md.hbs

@@ -0,0 +1,9 @@
+## Delegation — the last word
+
+This is the tail reminder on purpose: whatever the grounding, execution-bias, and development-protocol guidance above told you to *do*, the default way to do execution-class work is to **delegate it, not to run it inline.**
+
+- **Golden rule: when in doubt, delegate.** Any code change, research spanning 3+ file reads, file/report generation, build/deploy, or a task needing 3+ sequential tool calls without user input goes to a sub-agent (`@worker` for changes, `@researcher` for research, `@reviewer` for review) — per the Sub-Agent Delegation section. Unnecessary delegation costs a few tokens; a blocked foreground session costs the user's attention.
+- **The main session is for conversation.** Keep your own turns short — dispatch and acknowledge. The user should never wait more than 10 seconds for a response. "Act in-turn" is satisfied by dispatching the worker, not by doing the work yourself.
+- **Anti-pattern:** starting a task inline "because it's almost done", then racking up 5+ tool calls in the foreground. If it's execution-class, hand it off at the first tool call, not the fifth.
+
+If no sub-agents are configured, do the work yourself.

package/profiles/_shared/dev-protocol.md.hbs

@@ -2,6 +2,8 @@
 
 How development work gets done here — orient, clarify, align, ship, communicate. These are procedural rules for any substantive coding, infra, or debugging task. For the long-form playbook (design reports, adversarial review structure, re-review verdicts), load the bundled `dev-protocol` skill before starting substantive development work.
 
+**This protocol governs HOW delegated work is done, not a license to do it inline.** Substantive dev work is execution-class — per the Sub-Agent Delegation section it is dispatched to `@worker`/sub-agents so the foreground session stays free for the user. The orient / clarify / design-align / pipeline / communicate rules below bind that delegated work (and the sub-agent doing it); they are not an invitation for the main session to start editing, building, and testing in-turn instead of delegating.
+
 ### Orient — ground before you build
 
 - **Validate, don't assume.** Read the actual code, config, and system state before forming a theory. Never assert a fact you haven't checked this turn.

package/profiles/_shared/execution-discipline.md.hbs

@@ -14,5 +14,5 @@ When you genuinely can't verify something this turn, say so plainly ("I haven't
 
 How you should decide what to do next. These are procedural rules, not vibe.
 
-- **Act in-turn.** If the request is actionable, do it this turn. Don't finish with a plan or promise when tools can move it forward.
-- **Non-final turn:** use tools to advance, or ask the one clarifying question that unblocks safe progress. One question, not five.
+- **Act in-turn.** If the request is actionable, move it forward this turn. Don't finish with a plan or promise when tools can advance it. **But "act" composes with the Sub-Agent Delegation rules — it does not override them:** for an execution-class task (any code change, research spanning 3+ file reads, multi-step infra, report generation — see that section), the in-turn act IS dispatching the sub-agent, not doing the work inline. Acting immediately and delegating are the same move here; keep your own turn short and let the worker execute.
+- **Non-final turn:** use tools to advance (dispatch the worker when the task is execution-class), or ask the one clarifying question that unblocks safe progress. One question, not five.

package/profiles/coding/CLAUDE.md.hbs

@@ -49,7 +49,7 @@ Save proactively: architecture decisions, codebase patterns, conventions, known
 
 ## Sub-Agent Delegation
 
-If sub-agents are configured, delegate implementation to `@worker` (background, own worktree) and research to `@researcher` (background). Keep your turns short — dispatch and acknowledge quickly so you stay available for the user.
+**Golden rule: when in doubt, delegate.** The main session is for conversation; execution belongs in sub-agents. If sub-agents are configured, delegate implementation to `@worker` (background, own worktree), research spanning 3+ file reads to `@researcher` (background), and review to `@reviewer`. Unnecessary delegation costs a few tokens; a blocked foreground session costs the user's attention. Keep your turns short — dispatch and acknowledge quickly so you stay available for the user; the user should never wait more than 10 seconds for a response. Acting in-turn on an execution-class task means dispatching the worker, not doing the work inline.
 
 If the user amends in-flight delegated work mid-turn, steer the running worker now (`SendMessage` to the worker by name, or by the agent id from its spawn result) instead of holding the update for handback — and say in your reply whether you folded the update into the running worker or queued it as a separate task; never classify silently. If unsure whether a message amends in-flight work, queue it and say so — queue is the default. If the steer lands too late (worker effectively done), say so and apply the update yourself.
 

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

@@ -77259,6 +77259,9 @@ function decideSubagentProgress(input) {
   if (isEnvFlagOn(input.disableEnvValue)) {
     return { deliver: false, reason: "env-disabled" };
   }
+  if (input.skeleton === true) {
+    return { deliver: false, reason: "skeleton-liveness" };
+  }
   if (!input.isBackground) {
     return { deliver: false, reason: "foreground" };
   }
@@ -79121,8 +79124,40 @@ function readSubTail(entry, tail, now, onDescriptionUpdate, fs2, log, db2, paren
       tail.cursor = 0;
       tail.pendingPartial = "";
     }
-    if (stat.size === tail.cursor)
+    if (stat.size === tail.cursor) {
+      if (onProgress != null && entry.state === "running" && !entry.historical) {
+        let hasChild = false;
+        if (db2 != null) {
+          try {
+            const kid = db2.prepare("SELECT 1 FROM subagents WHERE parent_agent_id = ? LIMIT 1").get(entry.agentId);
+            hasChild = kid != null;
+          } catch (kidErr) {
+            log?.(`subagent-watcher: skeleton child-check error ${entry.agentId}: ${kidErr.message}`);
+          }
+        }
+        if (!hasChild) {
+          try {
+            onProgress({
+              agentId: entry.agentId,
+              description: entry.description,
+              latestSummary: "",
+              elapsedMs: now - entry.dispatchedAt,
+              prevBucketIdx: entry.lastProgressBucketIdx,
+              setBucketIdx: (b) => {
+                entry.lastProgressBucketIdx = b;
+              },
+              lastTool: entry.lastTool,
+              toolCount: entry.toolCount,
+              model: entry.currentModel,
+              skeleton: true
+            });
+          } catch (cbErr) {
+            log?.(`subagent-watcher: onProgress (skeleton) callback error ${entry.agentId}: ${cbErr.message}`);
+          }
+        }
+      }
       return;
+    }
     const buf = Buffer.alloc(stat.size - tail.cursor);
     const fd = fs2.openSync(entry.filePath, "r");
     try {
@@ -82723,10 +82758,10 @@ function readTurnActiveMarkerAgeMs(stateDir, now) {
 }
 
 // ../src/build-info.ts
-var VERSION = "0.18.20";
-var COMMIT_SHA = "f82e440f";
-var COMMIT_DATE = "2026-07-13T22:44:46+10:00";
-var LATEST_PR = 3230;
+var VERSION = "0.18.21";
+var COMMIT_SHA = "c237ff59";
+var COMMIT_DATE = "2026-07-14T01:11:18+10:00";
+var LATEST_PR = 3234;
 var COMMITS_AHEAD_OF_TAG = 0;
 
 // gateway/boot-version.ts
@@ -84414,6 +84449,7 @@ function applySubagentsSchema(db2) {
     db2.exec("ALTER TABLE subagents ADD COLUMN model TEXT");
   }
   db2.exec("CREATE INDEX IF NOT EXISTS subagents_jsonl_id ON subagents(jsonl_agent_id)");
+  db2.exec("CREATE INDEX IF NOT EXISTS subagents_parent_agent ON subagents(parent_agent_id)");
 }
 function mapSubagentRow(row) {
   return {
@@ -99333,7 +99369,7 @@ var didOneTimeSetup = false;
                 process.stderr.write(`telegram gateway: subagent-handback queued agent=${agentId} outcome=${outcome} chat=${decision.chatId} resultChars=${resultText.length}
 `);
               },
-              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount, progressLine, model }) => {
+              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount, progressLine, model, skeleton }) => {
                 let fleetChatId = "";
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? [];
@@ -99376,6 +99412,8 @@ var didOneTimeSetup = false;
                   }
                   if (surface !== "nest")
                     return;
+                  if (skeleton)
+                    return;
                   const turn = currentTurn;
                   if (turn == null)
                     return;
@@ -99435,6 +99473,7 @@ var didOneTimeSetup = false;
                 }
                 const progressOrigin = resolveSubagentOriginChat(agentId);
                 const decision = decideSubagentProgress({
+                  skeleton: skeleton === true,
                   disableEnvValue: process.env.SWITCHROOM_DISABLE_SUBAGENT_PROGRESS,
                   isBackground,
                   fleetChatId: progressOrigin?.chatId || fleetChatId,

package/telegram-plugin/gateway/gateway.ts

@@ -30542,7 +30542,7 @@ void (async () => {
               // suppresses stale-after-restart delivery (a 4-h-old
               // "still working (5m)" would be a lie). Sweep on handback
               // lives in the `onFinish` block just above.
-              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount, progressLine, model }) => {
+              onProgress: ({ agentId, description, latestSummary, elapsedMs, prevBucketIdx, setBucketIdx, lastTool, toolCount, progressLine, model, skeleton }) => {
                 let fleetChatId = ''
                 try {
                   const fleets = progressDriver?.peekAllFleets() ?? []
@@ -30632,6 +30632,15 @@ void (async () => {
                     return
                   }
                   if (surface !== 'nest') return // 'skip' — orphan-status off
+                  // #3233: a skeleton liveness cue carries NO step content by
+                  // construction (empty latestSummary/progressLine) — it exists
+                  // ONLY to create/keep-alive the orphan worker-feed row handled
+                  // just above. Branch EXPLICITLY on the `skeleton` discriminator
+                  // rather than inferring "no content" from an empty step line:
+                  // a skeleton cue must never nest into the parent's live turn
+                  // card (there is nothing to render, and the parent's own card
+                  // already owns the turn). Deterministic, controls-in-code.
+                  if (skeleton) return
                   const turn = currentTurn
                   if (turn == null) return // defensive: 'nest' implies a live turn
                   // Render regardless of `replyCalled` — a foreground Task
@@ -30777,8 +30786,17 @@ void (async () => {
                   return
                 }
 
+                // #3233: with the worker feed DISABLED, the legacy bucket relay
+                // below injects a synthesized "still working" inbound turn. A
+                // skeleton liveness cue carries an EMPTY latestSummary, so
+                // letting it reach the relay would queue a blank/contentless
+                // progress card. The `skeleton` discriminator is threaded into
+                // the pure decision (gate 1b → 'skeleton-liveness'), which drops
+                // it deterministically (controls-in-code, unit-tested) rather
+                // than an opaque inline return here.
                 const progressOrigin = resolveSubagentOriginChat(agentId)
                 const decision = decideSubagentProgress({
+                  skeleton: skeleton === true,
                   disableEnvValue: process.env.SWITCHROOM_DISABLE_SUBAGENT_PROGRESS,
                   isBackground,
                   // Prefer the conversation the Task was dispatched from over

package/telegram-plugin/gateway/subagent-progress-inbound-builder.ts

@@ -176,12 +176,20 @@ export interface SubagentProgressDecisionInput {
    *  passes it in; the decision returns the new bucket idx on
    *  `deliver: true` so the caller can update its tracker. */
   lastBucketIdx: number | null
+  /** #3233: true for a growth-independent SKELETON liveness cue (empty
+   *  `latestSummary`, no step content). It exists ONLY to first-paint /
+   *  keep-alive the in-message worker-feed row; the legacy bucket relay would
+   *  turn it into a synthesized "still working" inbound with no content — a
+   *  blank card. Suppressed deterministically here so the worker-feed-DISABLED
+   *  path degrades to a no-op rather than a blank envelope. */
+  skeleton?: boolean
   /** Deterministic clock for tests. */
   nowMs?: number
 }
 
 export type SubagentProgressSkipReason =
   | 'env-disabled'
+  | 'skeleton-liveness'
   | 'foreground'
   | 'no-chat'
   | 'bucket-already-fired'
@@ -199,6 +207,8 @@ export type SubagentProgressDecision =
  *
  * Gates, in order:
  *   1. kill-switch — `SWITCHROOM_DISABLE_SUBAGENT_PROGRESS=1` disables.
+ *   1b. skeleton-liveness (#3233) — a contentless skeleton cue is never
+ *       relayed as a synthesized inbound (worker-feed row only).
  *   2. foreground — foreground sub-agents stream natively.
  *   3. no-chat    — nowhere to deliver.
  *   4. missing-jsonl-id — the dedup key. Without it we'd lose
@@ -233,6 +243,13 @@ export function decideSubagentProgress(
   if (isEnvFlagOn(input.disableEnvValue)) {
     return { deliver: false, reason: 'env-disabled' }
   }
+  // #3233: a skeleton liveness cue carries no step content — never relay it as
+  // a synthesized progress inbound (that would be a blank card). Its whole job
+  // is the in-message worker-feed row; when that surface is off, degrade to a
+  // no-op. Checked before bucketing so it can never advance the bucket tracker.
+  if (input.skeleton === true) {
+    return { deliver: false, reason: 'skeleton-liveness' }
+  }
   if (!input.isBackground) {
     return { deliver: false, reason: 'foreground' }
   }

package/telegram-plugin/registry/subagents-schema.ts

@@ -277,6 +277,12 @@ export function applySubagentsSchema(db: SqliteDatabase): void {
   // column is guaranteed to exist (either created with the table or added by
   // the migration above).
   db.exec('CREATE INDEX IF NOT EXISTS subagents_jsonl_id ON subagents(jsonl_agent_id)')
+  // Same deferred-index rationale as jsonl_agent_id above: parent_agent_id is
+  // added by the ALTER migration for pre-existing tables, so its index must be
+  // created here (after the column is guaranteed to exist), not in the base SQL.
+  // Backs the per-poll child-existence probe in subagent-watcher.ts
+  // (`SELECT 1 FROM subagents WHERE parent_agent_id = ? LIMIT 1`).
+  db.exec('CREATE INDEX IF NOT EXISTS subagents_parent_agent ON subagents(parent_agent_id)')
 }
 
 // ---------------------------------------------------------------------------

package/telegram-plugin/subagent-watcher.ts

@@ -628,6 +628,12 @@ export interface SubagentWatcherConfig {
      *  assistant line — the gateway then falls back to the registry's
      *  dispatch-time model. */
     model?: string
+    /** True for a growth-INDEPENDENT skeleton liveness cue (#3231): fired on a
+     *  no-growth poll for a running entry so the card can first-paint / stay
+     *  alive without waiting for JSONL growth. Carries the entry's real state
+     *  but an EMPTY `latestSummary`/`progressLine` — never fabricated content.
+     *  Consumers that count real narrative/tool cues must exclude it. */
+    skeleton?: boolean
   }) => void
   /** `Date.now` override for tests. */
   now?: () => number
@@ -1088,6 +1094,9 @@ export function readSubTail(
     progressLine?: string
     /** Live model this worker is running (see SubagentWatcherConfig.onProgress). */
     model?: string
+    /** Growth-independent skeleton liveness cue (#3231). See the identically
+     *  named field on SubagentWatcherConfig.onProgress. */
+    skeleton?: boolean
   }) => void,
 ): void {
   try {
@@ -1103,7 +1112,83 @@ export function readSubTail(
       tail.cursor = 0
       tail.pendingPartial = ''
     }
-    if (stat.size === tail.cursor) return
+    if (stat.size === tail.cursor) {
+      // First-paint independence (#3231): the worker card is otherwise driven
+      // ONLY by growth-triggered progress cues below, so a running worker whose
+      // JSONL is not currently growing surfaces NOTHING. That is the ~90-205s
+      // invisible-card bug observed live (a57fbf, 2026-07-13): an async
+      // foreground sub-agent did two Bash calls, then its first tool BLOCKED for
+      // ~99s (no JSONL growth → no cue), and — because its spawning turn had
+      // already ended — no nest and no worker-feed row existed to paint. Its
+      // card did not appear until 205s after registration, on the next growth
+      // event that happened to be classified to the feed. Fire a growth-INDEPENDENT
+      // skeleton liveness cue on every no-growth poll for a live entry so the
+      // gateway can paint (and keep alive) the card from registration onward,
+      // uniformly across ALL spawn origins/nesting levels. The cue carries the
+      // entry's REAL current state (lastTool/toolCount/model) but an EMPTY step
+      // line — no fabricated content: it is inert on the foreground-nest path
+      // (empty child → no-op, the parent's own card owns the live turn) and
+      // creates/refreshes the orphan/background worker-feed row (→ "starting…",
+      // whose first paint the feed's own firstPaintMin + heartbeat then owns).
+      if (onProgress != null && entry.state === 'running' && !entry.historical) {
+        // Child-aware suppression (#3233): the skeleton cue exists to paint a
+        // LEAF worker whose card would otherwise be invisible (the 205s
+        // blackout). A pure-ORCHESTRATOR parent — one that has dispatched a
+        // descendant of its own — must NOT earn a redundant "starting…"
+        // liveness row: the child surfaces its own live row in the same worker
+        // feed, so an extra skeleton row for the parent is pure feed clutter
+        // (fails the no-noise / never-storm bar). The discriminator is
+        // deliberately NOT "0 own tools" — a leaf that registers and BLOCKS on
+        // its very first tool has 0 completed tools and MUST still paint.
+        // Instead, suppress when THIS entry has EVER dispatched a child (any
+        // child registry row keyed by parent_agent_id = this entry's jsonl
+        // agentId; recordNestedSubagentDispatch stamps it). "Ever", not "a
+        // currently-running child": the skeleton cue is only the NO-GROWTH
+        // fallback, so suppressing it for an orchestrator never hides real
+        // work — if the parent does its own tools, those fire real growth
+        // cues and paint the row; if it only orchestrates, its children carry
+        // the liveness. Using "currently running" instead would re-paint a
+        // spurious orchestrator "starting…" the moment its child finished. A
+        // genuine leaf has no child row at all, so it keeps firing the
+        // skeleton cue and paints promptly — the 205s-blackout class is intact.
+        let hasChild = false
+        if (db != null) {
+          try {
+            const kid = db
+              .prepare(
+                'SELECT 1 FROM subagents WHERE parent_agent_id = ? LIMIT 1',
+              )
+              .get(entry.agentId)
+            hasChild = kid != null
+          } catch (kidErr) {
+            // Best-effort: an absent/failed linkage read is treated as "leaf"
+            // so we never suppress a genuine blackout paint on a DB hiccup.
+            log?.(`subagent-watcher: skeleton child-check error ${entry.agentId}: ${(kidErr as Error).message}`)
+          }
+        }
+        if (!hasChild) {
+          try {
+            onProgress({
+              agentId: entry.agentId,
+              description: entry.description,
+              latestSummary: '',
+              elapsedMs: now - entry.dispatchedAt,
+              prevBucketIdx: entry.lastProgressBucketIdx,
+              setBucketIdx: (b: number) => {
+                entry.lastProgressBucketIdx = b
+              },
+              lastTool: entry.lastTool,
+              toolCount: entry.toolCount,
+              model: entry.currentModel,
+              skeleton: true,
+            })
+          } catch (cbErr) {
+            log?.(`subagent-watcher: onProgress (skeleton) callback error ${entry.agentId}: ${(cbErr as Error).message}`)
+          }
+        }
+      }
+      return
+    }
 
     const buf = Buffer.alloc(stat.size - tail.cursor)
     const fd = fs.openSync(entry.filePath, 'r')

package/telegram-plugin/tests/nested-worker-visibility-harness.test.ts

@@ -267,6 +267,26 @@ describe('nested (depth-2+) worker — end-to-end visibility harness', () => {
     expect(lastChild.text).not.toContain('starting…')
     expect(lastChild.text).toContain('index.ts')
 
+    // #3233 — DELIBERATE orchestrator-suppression behaviour. The depth-1
+    // 'depth-1 orchestrator' parent ran ZERO tools of its own: it only
+    // DISPATCHED the nested child. The skeleton first-paint cue (#3231) fires
+    // on every no-growth poll, so a naive implementation gives that pure
+    // orchestrator its OWN persistent "starting…" worker-feed row — redundant
+    // clutter, because the child's row already carries the liveness. The
+    // watcher suppresses the skeleton cue for any entry that has dispatched a
+    // child (parent_agent_id linkage), so the orchestrator NEVER earns a
+    // "starting…" row while its child provides the live signal. This is NOT a
+    // "0 own tools" rule (that would re-break the 205s-blackout incident this
+    // PR fixes — a leaf that blocks on its FIRST tool also has 0 completed
+    // tools and MUST still paint); it keys strictly on the parent/child link.
+    const allFeed = [...h.bot.sent, ...h.bot.edits]
+    const orchestratorStartingRows = allFeed.filter(
+      (m) => m.text.includes('depth-1 orchestrator') && m.text.includes('starting…'),
+    )
+    expect(orchestratorStartingRows.length).toBe(0)
+    // …while the child (a genuine leaf) DID surface real, live tool activity.
+    expect(childMsgs.some((m) => m.text.includes('index.ts'))).toBe(true)
+
     // More tool activity → climbing tool count, still live.
     h.appendWorker('child01', toolUse('t2', 'Bash', { command: 'ls -la /repo' }))
     h.advance(1000)

package/telegram-plugin/tests/subagent-progress-inbound-builder.test.ts

@@ -264,6 +264,36 @@ describe('decideSubagentProgress', () => {
     if (!d.deliver) expect(d.reason).toBe('foreground')
   })
 
+  // #3233 — worker-feed-DISABLED legacy path: a contentless skeleton liveness
+  // cue must NOT be relayed as a synthesized "still working" inbound (that
+  // would be a blank card). It degrades to a no-op, deterministically, BEFORE
+  // bucketing so it can never advance the bucket tracker.
+  it('skeleton liveness cue is dropped (no blank card) even when every other gate would pass', () => {
+    // Same input that DELIVERS in the happy-path test above (bucket 1, chat
+    // resolves) — only `skeleton` flips it off. Empty summary mirrors the real
+    // skeleton cue.
+    const d = decideSubagentProgress(baseInput({ skeleton: true, latestSummary: '' }))
+    expect(d.deliver).toBe(false)
+    if (!d.deliver) expect(d.reason).toBe('skeleton-liveness')
+  })
+
+  it('skeleton suppression fires before bucketing — a background skeleton at bucket>=1 never delivers', () => {
+    // ≤1 relay per interval is trivially satisfied: skeleton cues deliver ZERO
+    // inbounds regardless of how many no-growth polls fire within a bucket.
+    for (const elapsedMs of [7 * 60 * 1000, 8 * 60 * 1000, 9 * 60 * 1000]) {
+      const d = decideSubagentProgress(baseInput({ skeleton: true, latestSummary: '', elapsedMs }))
+      expect(d.deliver, `elapsedMs=${elapsedMs}`).toBe(false)
+    }
+  })
+
+  it('a NON-skeleton cue with identical inputs still delivers (guard is skeleton-scoped, not summary-scoped)', () => {
+    // Red-on-regression companion: proves the drop keys on `skeleton`, not on
+    // the empty summary — a real tool-only cue (empty prose summary) still
+    // delivers, so the guard cannot silently swallow genuine progress.
+    const d = decideSubagentProgress(baseInput({ skeleton: false, latestSummary: '' }))
+    expect(d.deliver).toBe(true)
+  })
+
   it('falls back to owner chat when fleet chat is empty', () => {
     const d = decideSubagentProgress(baseInput({ fleetChatId: '' }))
     expect(d.deliver).toBe(true)

package/telegram-plugin/tests/subagent-watcher-first-paint-independence.test.ts

@@ -0,0 +1,171 @@
+/**
+ * First-paint independence (#3231) regression.
+ *
+ * LIVE BUG (a57fbf, 2026-07-13): an async foreground sub-agent registered at
+ * 13:17:27, did two Bash calls, then its first tool BLOCKED for ~99s (no JSONL
+ * growth). Its spawning turn ended at 13:17:48 while it kept running, so there
+ * was neither a live parent turn to nest into NOR a worker-feed row to paint —
+ * and because the worker card is driven ONLY by growth-triggered onProgress
+ * cues, NOTHING surfaced. The card did not appear until 13:20:52, 205s after
+ * registration, on the next growth event that happened to route to the feed.
+ *
+ * The watcher's contract fix: a running, non-historical entry must emit a
+ * growth-INDEPENDENT skeleton liveness cue on every no-growth poll — an empty
+ * step line carrying the entry's real current state — so the gateway can paint
+ * (and keep alive) the card from registration onward, regardless of whether the
+ * worker's JSONL is currently growing. The gateway routes it: inert on the
+ * foreground-nest path (empty child), row-creating on the orphan/background
+ * worker-feed path.
+ *
+ * These assert OUTCOMES on the onProgress cue stream with an INJECTED clock.
+ * A skeleton cue is identified by its explicit `skeleton: true` discriminator
+ * (it also carries an empty `latestSummary` and no `progressLine`).
+ *
+ * RED-ON-REGRESSION: before the fix, readSubTail early-returns on a no-growth
+ * poll BEFORE firing any onProgress cue, so ZERO skeleton cues are emitted and
+ * every assertion below fails — reproducing the invisible-card window.
+ */
+
+import { describe, it, expect, afterEach } from 'vitest'
+import { mkdtempSync, mkdirSync, writeFileSync, appendFileSync, rmSync } from 'fs'
+import { tmpdir } from 'os'
+import { join } from 'path'
+import { startSubagentWatcher } from '../subagent-watcher.js'
+
+function buildJSONL(...lines: object[]): string {
+  return lines.map((l) => JSON.stringify(l)).join('\n') + '\n'
+}
+function subAgentUserMsg(promptText: string) {
+  return { type: 'user', message: { content: [{ type: 'text', text: promptText }] } }
+}
+function subAgentToolUse(name: string, id: string) {
+  return { type: 'assistant', message: { content: [{ type: 'tool_use', name, id, input: {} }] } }
+}
+
+interface Cue { agentId: string; progressLine?: string; latestSummary: string; elapsedMs: number; skeleton?: boolean }
+
+describe('sub-agent card first-paint independence (#3231)', () => {
+  let tmpRoot = ''
+  const started: Array<ReturnType<typeof startSubagentWatcher>> = []
+
+  afterEach(() => {
+    while (started.length) {
+      try { started.pop()?.stop() } catch { /* ignore */ }
+    }
+    if (tmpRoot) {
+      try { rmSync(tmpRoot, { recursive: true, force: true }) } catch { /* ignore */ }
+      tmpRoot = ''
+    }
+  })
+
+  const RESCAN_MS = 1000
+
+  function startWatcher(agentDir: string) {
+    let currentTime = 100_000
+    const cues: Cue[] = []
+    const intervals: Array<{ fn: () => void; ref: number }> = []
+    let nextRef = 1
+    const watcher = startSubagentWatcher({
+      agentDir,
+      onFinish: () => {},
+      onProgress: ({ agentId, progressLine, latestSummary, elapsedMs, skeleton }) => {
+        cues.push({ agentId, progressLine, latestSummary, elapsedMs, skeleton })
+      },
+      stallThresholdMs: 600_000,
+      silentSynthesisStallThresholdMs: 600_000,
+      rescanMs: RESCAN_MS,
+      now: () => currentTime,
+      setInterval: (fn) => { const ref = nextRef++; intervals.push({ fn, ref }); return { ref } },
+      clearInterval: (handle) => {
+        const { ref } = handle as { ref: number }
+        const idx = intervals.findIndex((i) => i.ref === ref)
+        if (idx !== -1) intervals.splice(idx, 1)
+      },
+      setTimeout: () => ({ ref: nextRef++ }),
+      clearTimeout: () => {},
+      log: () => {},
+    })
+    started.push(watcher)
+    return {
+      watcher,
+      cues,
+      poll: () => intervals[0]?.fn(),
+      advance: (ms: number) => { currentTime += ms },
+      now: () => currentTime,
+    }
+  }
+
+  const skeletonCues = (cues: Cue[]): Cue[] =>
+    cues.filter((c) => c.skeleton === true)
+
+  function makeSubagentDir(root: string): string {
+    const agentDir = join(root, 'agent')
+    const subagentsDir = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents')
+    mkdirSync(subagentsDir, { recursive: true })
+    return agentDir
+  }
+
+  it('emits a growth-independent skeleton cue on the first no-growth poll after registration', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-firstpaint-'))
+    const agentDir = makeSubagentDir(tmpRoot)
+    const jsonlPath = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents', 'agent-deadbeef.jsonl')
+
+    // Start the watcher on an empty subagents dir, THEN the worker spawns — the
+    // real async Agent-tool path (the JSONL appears post-boot, so the entry is
+    // live/non-historical, not a boot-time rediscovery). Only its prompt is on
+    // disk, no assistant output yet (it is "thinking"): the pre-content window
+    // the user stares at.
+    const h = startWatcher(agentDir)
+    h.poll() // boot scan over the empty dir
+    writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
+    h.advance(RESCAN_MS)
+    h.poll() // discover + register as a live worker
+
+    // Next poll: the JSONL has NOT grown. Pre-fix, readSubTail early-returns and
+    // NO cue fires — the card is invisible. Post-fix, a skeleton cue surfaces so
+    // the gateway can paint the card without waiting for the worker's output.
+    h.advance(RESCAN_MS)
+    h.poll()
+
+    const skel = skeletonCues(h.cues)
+    expect(skel.length, 'a skeleton cue must fire on a no-growth poll').toBeGreaterThanOrEqual(1)
+    // Tight bound vs the ~205s live behaviour: first cue is within a couple polls
+    // of registration, NOT minutes.
+    expect(skel[0].elapsedMs).toBeLessThanOrEqual(2 * RESCAN_MS)
+  })
+
+  it('keeps surfacing skeleton cues while a worker is silent after an early tool burst (blocked first tool)', () => {
+    tmpRoot = mkdtempSync(join(tmpdir(), 'sr-firstpaint-silent-'))
+    const agentDir = makeSubagentDir(tmpRoot)
+    const jsonlPath = join(agentDir, '.claude', 'projects', 'p1', 'session-abc', 'subagents', 'agent-a57fbf00.jsonl')
+
+    const h = startWatcher(agentDir)
+    h.poll() // boot scan over the empty dir
+    writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Debug delegation regression')))
+    h.advance(RESCAN_MS)
+    h.poll() // discover + register as a live worker
+
+    // The worker does two quick Bash calls (the a57fbf shape) …
+    appendFileSync(jsonlPath, buildJSONL(subAgentToolUse('Bash', 'b1')))
+    h.advance(RESCAN_MS)
+    h.poll()
+    appendFileSync(jsonlPath, buildJSONL(subAgentToolUse('Bash', 'b2')))
+    h.advance(RESCAN_MS)
+    h.poll()
+
+    // … then its tool BLOCKS: no JSONL growth for a long stretch (~30 polls).
+    // The card must NOT go dark — a skeleton cue must fire on essentially every
+    // no-growth poll so the feed row is created/kept-alive and the heartbeat can
+    // climb the elapsed. Pre-fix, zero cues fire across the entire silent window.
+    const before = h.cues.length
+    for (let i = 0; i < 30; i++) {
+      h.advance(RESCAN_MS)
+      h.poll()
+    }
+    const duringSilence = h.cues.slice(before)
+    const skel = duringSilence.filter((c) => c.skeleton === true)
+    expect(skel.length, 'silent worker must keep emitting skeleton cues').toBeGreaterThanOrEqual(20)
+    // No skeleton cue ever fabricates content — the step line stays empty.
+    for (const c of skel) expect(c.latestSummary).toBe('')
+  })
+})

package/telegram-plugin/tests/subagent-watcher-narrative-early-paint.test.ts

@@ -39,7 +39,7 @@ function subAgentToolUse(name: string, id: string) {
   return { type: 'assistant', message: { content: [{ type: 'tool_use', name, id, input: {} }] } }
 }
 
-interface Cue { progressLine?: string; latestSummary: string }
+interface Cue { progressLine?: string; latestSummary: string; skeleton?: boolean }
 
 describe('worker/sub-agent opening-narration early paint (Residual A)', () => {
   let tmpRoot = ''
@@ -64,8 +64,8 @@ describe('worker/sub-agent opening-narration early paint (Residual A)', () => {
     const watcher = startSubagentWatcher({
       agentDir,
       onFinish: () => {},
-      onProgress: ({ agentId, progressLine, latestSummary }) => {
-        cues.push({ agentId, progressLine, latestSummary })
+      onProgress: ({ agentId, progressLine, latestSummary, skeleton }) => {
+        cues.push({ agentId, progressLine, latestSummary, skeleton })
       },
       stallThresholdMs: 600_000,
       silentSynthesisStallThresholdMs: 600_000,
@@ -91,8 +91,10 @@ describe('worker/sub-agent opening-narration early paint (Residual A)', () => {
   }
 
   function narrativeCues(cues: Cue[]): string[] {
-    // Narrative cues carry NO progressLine; tool-label cues do.
-    return cues.filter((c) => c.progressLine == null).map((c) => c.latestSummary)
+    // Narrative cues carry NO progressLine; tool-label cues do. Skeleton
+    // liveness cues (#3231) also carry no progressLine but an empty summary —
+    // exclude them here so this counts only real narrative content.
+    return cues.filter((c) => !c.skeleton && c.progressLine == null).map((c) => c.latestSummary)
   }
 
   it('paints a parked opening narration after the flush window with NO tool event', () => {

package/telegram-plugin/tests/subagent-watcher.test.ts

@@ -584,9 +584,10 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
           // Narrative ticks carry NO progressLine (tool ticks do); record them.
-          if (progressLine == null) narrativeCues.push(latestSummary)
+          // Skeleton liveness cues (#3231) are not narrative — exclude them.
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo path')))
@@ -614,8 +615,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo')))
@@ -647,8 +648,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          allCues.push({ progressLine, latestSummary })
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton) allCues.push({ progressLine, latestSummary })
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Find the repo')))
@@ -698,8 +699,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Do the task')))
@@ -728,8 +729,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Summarise the diff')))
@@ -761,8 +762,8 @@ describe('startSubagentWatcher', () => {
       const jsonlPath = join(subagentsDir, 'agent-deadbeef.jsonl')
       const h = startWatcherSync({
         agentDir,
-        onProgress: ({ progressLine, latestSummary }) => {
-          if (progressLine == null) narrativeCues.push(latestSummary)
+        onProgress: ({ progressLine, latestSummary, skeleton }) => {
+          if (!skeleton && progressLine == null) narrativeCues.push(latestSummary)
         },
       })
       writeFileSync(jsonlPath, buildJSONL(subAgentUserMsg('Summarise the diff')))

package/telegram-plugin/tests/worker-feed-terminal-state-truthful.test.ts

@@ -87,6 +87,46 @@ describe('worker terminal state is truthful for reaped workers (Residual B)', ()
     expect(last).not.toContain('incomplete')
   })
 
+  // #3233 terminal-window race: the skeleton first-paint cue fires on EVERY
+  // no-growth poll, so one can land on a row that `finish()` just finalized
+  // (watcher poll cadence ≈ seconds). The `finalized` latch must absorb it —
+  // a late skeleton `update()` must NOT resurrect a fresh `running` card on an
+  // already-done worker. This exercises that path with a skeleton-shaped cue
+  // (empty step line, running state) arriving after finish.
+  it('a late skeleton update() after finish() is absorbed by the finalized latch (no resurrection)', async () => {
+    let clock = 1000
+    const { feed, edits } = makeFeed(() => clock)
+    await feed.update('w', 'chat', runningView('background job', 'doing work', 1000))
+    await drain()
+    clock = 2000
+    await feed.finish('w', {
+      description: 'background job',
+      lastTool: null,
+      toolCount: 5,
+      latestSummary: 'the delivered result paragraph',
+      elapsedMs: 2000,
+      state: 'done',
+    })
+    await drain()
+    const editsAfterFinish = edits.length
+    // Late skeleton cue (empty latestSummary, running state) — the shape the
+    // watcher emits on a no-growth poll — lands AFTER finalization.
+    clock = 2500
+    await feed.update('w', 'chat', {
+      description: 'background job',
+      lastTool: null,
+      toolCount: 5,
+      latestSummary: '',
+      elapsedMs: 2500,
+      state: 'running',
+    })
+    await drain()
+    // No further edit, no resurrection: the terminal card stays `done`.
+    expect(edits.length).toBe(editsAfterFinish)
+    expect(edits[edits.length - 1].text).toContain('done')
+    expect(feed.has('w')).toBe(false)
+  })
+
   it('renderWorkerActivity renders the `incomplete` state as a finished card without a fabricated result', () => {
     const card = renderWorkerActivity({
       description: 'background job',