@edspencer/paddock 0.68.0 → 0.69.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@edspencer/paddock",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "description": "Project-first launchpad for Claude Code: server-hosted, persistent, resumable sessions organized by project.",
   "keywords": [
     "claude",

package/packages/server/dist/background-live.d.ts

@@ -0,0 +1,124 @@
+/**
+ * Live background-work registry (#604).
+ *
+ * Paddock's only notion of "this chat is busy" is `SessionHub`'s single `Turn`
+ * per session. That is wrong for background work in two directions: a turn ends
+ * while its background tasks keep running (this issue), and a background task
+ * outlives the `Turn` record entirely, so the task set cannot live on it.
+ *
+ * The Claude Agent SDK already publishes the set we need. This module is the
+ * server-side landing point for it:
+ *
+ *   - `system/background_tasks_changed` — a LEVEL signal carrying every live
+ *     task after a membership change. Consumed with REPLACE semantics, per the
+ *     SDK's own guidance: "consumers that only need 'is background work
+ *     running' should replace their set with each payload rather than pairing
+ *     edges, so a missed bookend cannot wedge a stale running indicator."
+ *     #528 was exactly such a wedge, so this is load-bearing, not stylistic.
+ *
+ *   - `system/task_started` / `system/task_progress` — EDGE signals carrying the
+ *     detail the level payload omits (`tool_use_id`, `subagent_type`,
+ *     `workflow_name`, `last_tool_name`, step counts). Folded onto the level set
+ *     as enrichment only: an edge NEVER adds a task the level has not shown us,
+ *     because the edges are not guaranteed to pair and a leaked edge would
+ *     resurrect a finished task.
+ *
+ *   - `system/task_notification` / `system/task_updated` — terminal edges. These
+ *     evict eagerly rather than waiting for the next level, so a completed task
+ *     leaves the bar promptly; a level signal that still lists it will simply
+ *     put it back.
+ *
+ * Per-process caveat, straight from the SDK: the level is "per-process: nothing
+ * is emitted at startup, so consumers must reset to the empty set whenever the
+ * session's CLI process (re)starts". {@link BackgroundRegistry.clear} is that
+ * reset. Nothing here tries to reconstruct a set from disk — an empty bar after
+ * a restart is correct, because Paddock stops the fleet with
+ * `waitForJobs: false` and the tasks are genuinely dead.
+ */
+/**
+ * One live background task, as broadcast to clients.
+ *
+ * `type` is the SDK's friendly label (`shell` | `subagent` | `monitor` |
+ * `workflow`), falling back to the raw discriminant for kinds we do not know
+ * about yet — deliberately a plain `string` rather than a union so a new SDK
+ * task type renders as an unlabelled row instead of being dropped.
+ */
+export interface LiveBackgroundTask {
+    id: string;
+    type: string;
+    description: string;
+    /** Epoch-ms this task was first observed. Stamped here; the SDK sends no start time. */
+    startedAt: number;
+    /** Links the task to its launching tool card, when an edge has told us. */
+    toolUseId?: string;
+    /** `subagent` only. */
+    agentType?: string;
+    /** `shell` only. */
+    command?: string;
+    /** `workflow` only. */
+    workflowName?: string;
+    /** `monitor` / MCP-task only. */
+    server?: string;
+    tool?: string;
+    /** Latest tool the task ran, from `task_progress`. */
+    lastToolName?: string;
+    /** Steps the task has taken, from `task_progress.usage.tool_uses`. */
+    toolUses?: number;
+    /**
+     * Ambient/housekeeping work. The SDK asks consumers to hide these from the
+     * inline transcript while still allowing a tasks panel to show them, so it is
+     * carried on the wire and filtered at the point of display.
+     */
+    skipTranscript?: boolean;
+}
+export type BackgroundChangeListener = (projectSlug: string, sessionId: string, tasks: LiveBackgroundTask[]) => void;
+/**
+ * The registry. One instance per server, owned by the WS layer so it can
+ * broadcast, and fed by the turn engine from both the foreground and background
+ * message lanes.
+ */
+export declare class BackgroundRegistry {
+    private now;
+    private bySession;
+    /** Fired whenever a session's live set changes. Set by the WS layer. */
+    onChange: BackgroundChangeListener | null;
+    /** Injectable clock, so tests can assert `startedAt` without sleeping. */
+    constructor(now?: () => number);
+    /** Live tasks for a session, newest last. Empty array when idle or unknown. */
+    list(sessionId: string): LiveBackgroundTask[];
+    /** Every session with at least one live task — the connect-time snapshot. */
+    snapshot(): {
+        projectSlug: string;
+        sessionId: string;
+        tasks: LiveBackgroundTask[];
+    }[];
+    /** Does this session have live background work? The #604 predicate. */
+    isBusy(sessionId: string): boolean;
+    /**
+     * Forget a session's set. Called when the session's process restarts or its
+     * stream ends — see the per-process caveat in the module header.
+     */
+    clear(sessionId: string): void;
+    /**
+     * Feed one raw SDK message. Returns true when the live set changed, so the
+     * caller can avoid re-broadcasting on the overwhelming majority of messages
+     * (assistant text, tool calls) that are not task lifecycle at all.
+     */
+    observe(projectSlug: string, m: unknown): boolean;
+    /**
+     * REPLACE the session's set from a level signal, preserving the enrichment we
+     * have already folded onto tasks that survive. Without the merge, every level
+     * signal would blank the `tool_use_id` and step counts that only the edges
+     * carry, making rows flicker between detailed and bare.
+     */
+    private replace;
+    /**
+     * Fold edge detail onto an EXISTING task. Deliberately a no-op for an unknown
+     * id: the level signal is the sole authority on membership, so an edge can
+     * never create a row (and a late edge can never resurrect a finished one).
+     */
+    private enrich;
+    /** Drop a task on a terminal edge, ahead of the level that will confirm it. */
+    private evict;
+    private emit;
+}

package/packages/server/dist/background-live.js

@@ -0,0 +1,226 @@
+/**
+ * Live background-work registry (#604).
+ *
+ * Paddock's only notion of "this chat is busy" is `SessionHub`'s single `Turn`
+ * per session. That is wrong for background work in two directions: a turn ends
+ * while its background tasks keep running (this issue), and a background task
+ * outlives the `Turn` record entirely, so the task set cannot live on it.
+ *
+ * The Claude Agent SDK already publishes the set we need. This module is the
+ * server-side landing point for it:
+ *
+ *   - `system/background_tasks_changed` — a LEVEL signal carrying every live
+ *     task after a membership change. Consumed with REPLACE semantics, per the
+ *     SDK's own guidance: "consumers that only need 'is background work
+ *     running' should replace their set with each payload rather than pairing
+ *     edges, so a missed bookend cannot wedge a stale running indicator."
+ *     #528 was exactly such a wedge, so this is load-bearing, not stylistic.
+ *
+ *   - `system/task_started` / `system/task_progress` — EDGE signals carrying the
+ *     detail the level payload omits (`tool_use_id`, `subagent_type`,
+ *     `workflow_name`, `last_tool_name`, step counts). Folded onto the level set
+ *     as enrichment only: an edge NEVER adds a task the level has not shown us,
+ *     because the edges are not guaranteed to pair and a leaked edge would
+ *     resurrect a finished task.
+ *
+ *   - `system/task_notification` / `system/task_updated` — terminal edges. These
+ *     evict eagerly rather than waiting for the next level, so a completed task
+ *     leaves the bar promptly; a level signal that still lists it will simply
+ *     put it back.
+ *
+ * Per-process caveat, straight from the SDK: the level is "per-process: nothing
+ * is emitted at startup, so consumers must reset to the empty set whenever the
+ * session's CLI process (re)starts". {@link BackgroundRegistry.clear} is that
+ * reset. Nothing here tries to reconstruct a set from disk — an empty bar after
+ * a restart is correct, because Paddock stops the fleet with
+ * `waitForJobs: false` and the tasks are genuinely dead.
+ */
+/** Terminal task statuses — a task in one of these is no longer live. */
+const TERMINAL_STATUSES = new Set(["completed", "failed", "stopped", "killed"]);
+const str = (v) => (typeof v === "string" && v ? v : undefined);
+const num = (v) => (typeof v === "number" && Number.isFinite(v) ? v : undefined);
+/**
+ * Is this an SDK system message we care about? Structural rather than a typed
+ * narrow, because the SDK's `SDKMessage` union gains subtypes faster than we
+ * pin its version, and an unknown subtype must be ignored, not crash the turn.
+ */
+function systemSubtype(m) {
+    if (!m || typeof m !== "object")
+        return null;
+    const o = m;
+    if (o.type !== "system")
+        return null;
+    return typeof o.subtype === "string" ? o.subtype : null;
+}
+/**
+ * The registry. One instance per server, owned by the WS layer so it can
+ * broadcast, and fed by the turn engine from both the foreground and background
+ * message lanes.
+ */
+export class BackgroundRegistry {
+    now;
+    bySession = new Map();
+    /** Fired whenever a session's live set changes. Set by the WS layer. */
+    onChange = null;
+    /** Injectable clock, so tests can assert `startedAt` without sleeping. */
+    constructor(now = Date.now) {
+        this.now = now;
+    }
+    /** Live tasks for a session, newest last. Empty array when idle or unknown. */
+    list(sessionId) {
+        const e = this.bySession.get(sessionId);
+        return e ? [...e.tasks.values()] : [];
+    }
+    /** Every session with at least one live task — the connect-time snapshot. */
+    snapshot() {
+        const out = [];
+        for (const [sessionId, e] of this.bySession) {
+            if (e.tasks.size > 0)
+                out.push({ projectSlug: e.projectSlug, sessionId, tasks: [...e.tasks.values()] });
+        }
+        return out;
+    }
+    /** Does this session have live background work? The #604 predicate. */
+    isBusy(sessionId) {
+        const e = this.bySession.get(sessionId);
+        return !!e && e.tasks.size > 0;
+    }
+    /**
+     * Forget a session's set. Called when the session's process restarts or its
+     * stream ends — see the per-process caveat in the module header.
+     */
+    clear(sessionId) {
+        const e = this.bySession.get(sessionId);
+        if (!e || e.tasks.size === 0)
+            return;
+        e.tasks.clear();
+        this.emit(sessionId, e);
+    }
+    /**
+     * Feed one raw SDK message. Returns true when the live set changed, so the
+     * caller can avoid re-broadcasting on the overwhelming majority of messages
+     * (assistant text, tool calls) that are not task lifecycle at all.
+     */
+    observe(projectSlug, m) {
+        const subtype = systemSubtype(m);
+        if (!subtype)
+            return false;
+        const o = m;
+        const sessionId = str(o.session_id);
+        if (!sessionId)
+            return false;
+        switch (subtype) {
+            case "background_tasks_changed":
+                return this.replace(projectSlug, sessionId, Array.isArray(o.tasks) ? o.tasks : []);
+            case "task_started":
+                return this.enrich(sessionId, str(o.task_id), {
+                    toolUseId: str(o.tool_use_id),
+                    agentType: str(o.subagent_type),
+                    workflowName: str(o.workflow_name),
+                    description: str(o.description),
+                    skipTranscript: o.skip_transcript === true ? true : undefined,
+                });
+            case "task_progress": {
+                const usage = (o.usage ?? {});
+                return this.enrich(sessionId, str(o.task_id), {
+                    toolUseId: str(o.tool_use_id),
+                    agentType: str(o.subagent_type),
+                    lastToolName: str(o.last_tool_name),
+                    toolUses: num(usage.tool_uses),
+                });
+            }
+            case "task_notification":
+                // Always terminal — the SDK only emits this on completed/failed/stopped.
+                return this.evict(sessionId, str(o.task_id));
+            case "task_updated": {
+                const patch = (o.patch ?? {});
+                const status = str(patch.status);
+                if (status && TERMINAL_STATUSES.has(status))
+                    return this.evict(sessionId, str(o.task_id));
+                // A non-terminal patch (e.g. paused) is still enrichment.
+                return this.enrich(sessionId, str(o.task_id), { description: str(patch.description) });
+            }
+            default:
+                return false;
+        }
+    }
+    /**
+     * REPLACE the session's set from a level signal, preserving the enrichment we
+     * have already folded onto tasks that survive. Without the merge, every level
+     * signal would blank the `tool_use_id` and step counts that only the edges
+     * carry, making rows flicker between detailed and bare.
+     */
+    replace(projectSlug, sessionId, raw) {
+        const prev = this.bySession.get(sessionId);
+        const next = new Map();
+        for (const t of raw) {
+            const rt = (t ?? {});
+            const id = str(rt.task_id);
+            if (!id)
+                continue;
+            const existing = prev?.tasks.get(id);
+            next.set(id, {
+                ...existing,
+                id,
+                type: str(rt.task_type) ?? existing?.type ?? "task",
+                description: str(rt.description) ?? existing?.description ?? "",
+                startedAt: existing?.startedAt ?? this.now(),
+            });
+        }
+        if (prev && sameSet(prev.tasks, next)) {
+            // Membership and detail unchanged — keep the projectSlug fresh but stay quiet.
+            prev.projectSlug = projectSlug;
+            return false;
+        }
+        const entry = { projectSlug, tasks: next };
+        this.bySession.set(sessionId, entry);
+        this.emit(sessionId, entry);
+        return true;
+    }
+    /**
+     * Fold edge detail onto an EXISTING task. Deliberately a no-op for an unknown
+     * id: the level signal is the sole authority on membership, so an edge can
+     * never create a row (and a late edge can never resurrect a finished one).
+     */
+    enrich(sessionId, taskId, patch) {
+        if (!taskId)
+            return false;
+        const e = this.bySession.get(sessionId);
+        const cur = e?.tasks.get(taskId);
+        if (!e || !cur)
+            return false;
+        const defined = Object.fromEntries(Object.entries(patch).filter(([, v]) => v !== undefined));
+        const keys = Object.keys(defined);
+        if (keys.length === 0 || keys.every((k) => cur[k] === defined[k]))
+            return false;
+        e.tasks.set(taskId, { ...cur, ...defined });
+        this.emit(sessionId, e);
+        return true;
+    }
+    /** Drop a task on a terminal edge, ahead of the level that will confirm it. */
+    evict(sessionId, taskId) {
+        if (!taskId)
+            return false;
+        const e = this.bySession.get(sessionId);
+        if (!e || !e.tasks.delete(taskId))
+            return false;
+        this.emit(sessionId, e);
+        return true;
+    }
+    emit(sessionId, e) {
+        this.onChange?.(e.projectSlug, sessionId, [...e.tasks.values()]);
+    }
+}
+/** Do two task maps carry the same ids AND the same rendered detail? */
+function sameSet(a, b) {
+    if (a.size !== b.size)
+        return false;
+    for (const [id, ta] of a) {
+        const tb = b.get(id);
+        if (!tb)
+            return false;
+        if (ta.type !== tb.type || ta.description !== tb.description)
+            return false;
+    }
+    return true;
+}

package/packages/server/dist/ws-protocol.d.ts

@@ -408,6 +408,22 @@ export interface ChatActiveMessage {
          * a client built against an older server still parses the frame.
          */
         startedAt?: number;
+        /**
+         * Whether a MODEL TURN is in flight, as distinct from `running`, which since
+         * #604 also counts background work the turn left behind.
+         *
+         * The two answer different questions and must not be conflated. `running`
+         * drives status readouts — the sidebar dot, the fleet strip, the Home badge,
+         * the running-only filter — where background work genuinely means "this chat
+         * is busy". `turnRunning` drives the composer lock and the working indicator,
+         * where it does not: a `Monitor` can run for an hour, and locking the
+         * composer for that hour would make the chat unusable while telling the user
+         * the model was still thinking.
+         *
+         * Optional on the wire so an older client still parses the frame; such a
+         * client falls back to `running` and behaves as it did before.
+         */
+        turnRunning?: boolean;
     };
 }
 /**
@@ -539,6 +555,50 @@ export interface ChatKilledTaskMessage {
         timestamp: string;
     };
 }
+/**
+ * One live background task on a session (#604). Mirrors the SDK's
+ * `BackgroundTaskSummary` plus the detail its edge signals carry.
+ */
+export interface LiveBackgroundTaskWire {
+    id: string;
+    /** `shell` | `subagent` | `monitor` | `workflow`, or a raw discriminant we do not know. */
+    type: string;
+    description: string;
+    startedAt: number;
+    toolUseId?: string;
+    agentType?: string;
+    command?: string;
+    workflowName?: string;
+    server?: string;
+    tool?: string;
+    lastToolName?: string;
+    toolUses?: number;
+    skipTranscript?: boolean;
+}
+/**
+ * A session's live background work (#604) — the tasks still running after the
+ * turn that launched them has returned.
+ *
+ * A LEVEL frame with REPLACE semantics: `tasks` is the complete set, and an
+ * empty array means "nothing running". Clients must swap their set rather than
+ * pair start/stop edges, so a dropped frame cannot wedge a stale indicator —
+ * the same contract the SDK states for `background_tasks_changed` upstream, and
+ * the reason #528's permanent "running" state cannot recur here.
+ *
+ * Broadcast on every membership change and replayed to a newly-connected socket,
+ * so a remount or reload learns what is in flight without polling. Nothing is
+ * reconstructed from disk: the signal is per-process, so after a server restart
+ * the set is empty until the next change — which is correct, because Paddock
+ * stops the fleet with `waitForJobs: false` and those tasks are dead.
+ */
+export interface ChatBackgroundMessage {
+    type: "chat:background";
+    payload: {
+        projectSlug: string;
+        sessionId: string;
+        tasks: LiveBackgroundTaskWire[];
+    };
+}
 /**
  * A keeper turn dead-ended without a normal reply (issue #329): a synthetic
  * subscription/usage-limit hit, the max-turns cap, or an error (network / API
@@ -556,6 +616,6 @@ export interface ChatNoticeMessage {
 export interface PongMessage {
     type: "pong";
 }
-export type ServerMessage = ChatResponseMessage | ChatToolCallMessage | ChatToolStartMessage | ChatMessageBoundaryMessage | ChatCompleteMessage | ChatErrorMessage | ChatResyncMessage | ChatActiveMessage | ChatQueuedFlushedMessage | ChatQueuedStateMessage | ChatQueuedReturnedMessage | ChatKilledTaskMessage | ChatNoticeMessage | PongMessage;
+export type ServerMessage = ChatResponseMessage | ChatToolCallMessage | ChatToolStartMessage | ChatMessageBoundaryMessage | ChatCompleteMessage | ChatErrorMessage | ChatResyncMessage | ChatActiveMessage | ChatQueuedFlushedMessage | ChatQueuedStateMessage | ChatQueuedReturnedMessage | ChatKilledTaskMessage | ChatBackgroundMessage | ChatNoticeMessage | PongMessage;
 export declare function isClientMessage(data: unknown): data is ClientMessage;
 export {};

package/packages/server/dist/ws-turn.d.ts

@@ -3,6 +3,7 @@ import type { Project } from "./projects.js";
 import { SessionHub } from "./session-hub.js";
 import { createWakeInjectionCache, type InjectedMcpBuildArgs } from "./wake-injection.js";
 import { RecoveryEngine } from "./recovery.js";
+import type { BackgroundRegistry } from "./background-live.js";
 import type { ChatHandlerDeps, StartAgentTurn, ChatHandlerContext } from "./ws-context.js";
 /**
  * The recovery nudge injected by a manual Continue (issue #301, Layer 2) — and,
@@ -70,4 +71,5 @@ export interface TurnEngine {
 export declare function makeTurnEngine(engine: {
     deps: ChatHandlerDeps;
     hub: SessionHub;
+    background: BackgroundRegistry;
 }): TurnEngine;

package/packages/server/dist/ws-turn.js

@@ -72,7 +72,7 @@ export function isSidechainMessage(m) {
  * the herdctl schedule/wake resolvers and the trigger event listeners.
  */
 export function makeTurnEngine(engine) {
-    const { deps, hub } = engine;
+    const { deps, hub, background } = engine;
     // Trigger / schedule / event firing (ws-triggers.ts, #403). Built here so it can
     // close over the shared startAgentTurn engine (a hoisted declaration below) and
     // wire its herdctl schedule handler + onArchive/afterTurn listeners. ws.ts consumes
@@ -277,6 +277,10 @@ export function makeTurnEngine(engine) {
             });
         };
         const onMessage = async (m) => {
+            // #604: observe task lifecycle before the sidechain filter — see the note on
+            // the foreground path. This lane is where a background task most often
+            // finishes, since the turn that launched it has already returned.
+            background.observe(projectSlug, m);
             // (1) Skip sidechain sub-agent nested steps from rendering (see header). The
             // attribution lives on the top-level SDK message OR its nested `message`.
             if (isSidechainMessage(m))
@@ -316,6 +320,12 @@ export function makeTurnEngine(engine) {
                 deps.herdctl.unregisterBackgroundTurn(bgJobId);
             bgJobId = null;
             registeredSession = null;
+            // #604: the stream ending IS the reap — the session's process is gone, so
+            // its background set can no longer change and anything still listed is dead.
+            // The SDK's level signal is per-process and emits nothing at startup, so
+            // this reset is what stops a stale row surviving into the next session.
+            if (resolvedSession)
+                background.clear(resolvedSession);
             if (!turn)
                 return;
             turn.emit({
@@ -533,6 +543,12 @@ export function makeTurnEngine(engine) {
                 // SAME `session_id` as the main chat (verified against on-disk transcripts),
                 // and the launching `tool_use` message is itself main-stream, so it always
                 // resolves the id before any sidechain step arrives.
+                //
+                // #604: the SDK's task-lifecycle system messages are session-level rather
+                // than rendered transcript, so they are observed BEFORE this filter — the
+                // registry must see a sub-agent's own lifecycle even though its steps are
+                // deliberately not rendered here.
+                background.observe(projectSlug, m);
                 if (isSidechainMessage(m))
                     return;
                 if (m.session_id) {

package/packages/server/dist/ws.js

@@ -57,6 +57,7 @@ import { keeperAgentName, keeperSlugFromAgent, } from "./herdctl.js";
 import { consumeResumedTurn } from "./resume-drain.js";
 import { isKnownModel, getContextLimit, DEFAULT_MODEL, isKnownDriveMode, } from "./models.js";
 import { SessionHub } from "./session-hub.js";
+import { BackgroundRegistry } from "./background-live.js";
 import { hasQueuedContent, partsOf, } from "./queued-message.js";
 import { resolveAttachmentsConfig } from "./attachments-config.js";
 import { wrapAttachments, inferAttachmentKind } from "./attachments-hint.js";
@@ -208,18 +209,13 @@ export function makeChatHandler(deps) {
     // broadcast to all clients — powering the per-chat sidebar streaming dots that
     // must update even for chats whose pane isn't mounted (issue #53).
     const clients = new Set();
-    const activeFrame = (info) => ({
-        type: "chat:active",
-        payload: {
-            projectSlug: info.projectSlug,
-            sessionId: info.sessionId,
-            jobId: info.jobId,
-            running: info.running,
-            startedAt: info.startedAt,
-        },
-    });
-    hub.onActive = (info) => {
-        const data = JSON.stringify(activeFrame(info));
+    /**
+     * Live background work per session (#604). Owned here because this is the
+     * layer that can broadcast; fed by the turn engine from both message lanes.
+     */
+    const background = new BackgroundRegistry();
+    const broadcast = (frame) => {
+        const data = JSON.stringify(frame);
         for (const c of clients) {
             if (c.readyState === c.OPEN) {
                 try {
@@ -231,6 +227,57 @@ export function makeChatHandler(deps) {
             }
         }
     };
+    /**
+     * #604: a session is busy while it holds background work, even though the
+     * turn that launched it has returned. `SessionHub` tracks one turn and cannot
+     * know this, so the join happens here — the only place that sees both. Every
+     * consumer of `chat:active.running` (sidebar dots, the Home in-flight badge,
+     * the running-only filter, the client's own `streaming` gate) then reads the
+     * truth instead of "the primary turn ended".
+     */
+    const activeFrame = (info) => ({
+        type: "chat:active",
+        payload: {
+            projectSlug: info.projectSlug,
+            sessionId: info.sessionId,
+            jobId: info.jobId,
+            running: info.running || background.isBusy(info.sessionId),
+            startedAt: info.startedAt,
+            turnRunning: info.running,
+        },
+    });
+    /**
+     * Last `running` we published per session, so a background-set change only
+     * re-emits `chat:active` when it actually flips the answer. Without this every
+     * task start/stop would broadcast a redundant frame to every socket.
+     */
+    const lastPublishedRunning = new Map();
+    hub.onActive = (info) => {
+        const frame = activeFrame(info);
+        lastPublishedRunning.set(info.sessionId, frame.payload.running);
+        broadcast(frame);
+    };
+    background.onChange = (projectSlug, sessionId, tasks) => {
+        broadcast({ type: "chat:background", payload: { projectSlug, sessionId, tasks } });
+        // The set changing can flip a session between idle and busy while the hub's
+        // own turn state is unchanged — that transition is exactly #604.
+        const info = hub.activeInfo(sessionId);
+        const running = (info?.running ?? false) || tasks.length > 0;
+        if (lastPublishedRunning.get(sessionId) === running)
+            return;
+        lastPublishedRunning.set(sessionId, running);
+        broadcast({
+            type: "chat:active",
+            payload: {
+                projectSlug,
+                sessionId,
+                jobId: info?.jobId ?? null,
+                running,
+                startedAt: info?.startedAt,
+                turnRunning: info?.running ?? false,
+            },
+        });
+    };
     // Drive scheduler-fired session wakes onto the hub (Paddock#111 gap 3). When a
     // keeper scheduled a `ScheduleWakeup` / `/loop`, herdctl reaps the idle session
     // and later resumes it at fire time, handing us the live (managed) session with
@@ -332,6 +379,8 @@ export function makeChatHandler(deps) {
         };
         const onWakeMessage = async (m) => {
             // A sub-agent's nested steps never render top-level ({@link isSidechainMessage}).
+            // #604: task lifecycle is session-level — observe before the filter.
+            background.observe(slug, m);
             if (isSidechainMessage(m))
                 return;
             if (messageProducedReply(m))
@@ -395,7 +444,7 @@ export function makeChatHandler(deps) {
     // wake cache, the shared startAgentTurn engine, and Layer-2/3 recovery. Relocated
     // as one scope so its cross-references stay intact; the socket layer below
     // consumes the returned surface.
-    const engine = makeTurnEngine({ deps, hub });
+    const engine = makeTurnEngine({ deps, hub, background });
     const { startAgentTurn, wakeInjection, selfMcpCtx, injectRecoveryNudge, recoveryEngine, emitAfterTurn, composePreloadedPrompt, fireTrigger, makeBackgroundTurnSink, } = engine;
     /**
      * Build the chat operations for ONE connection: the handlers behind every
@@ -942,6 +991,9 @@ export function makeChatHandler(deps) {
                         // human `chat:send` path, so it is where the duplication was actually
                         // seen. Skipping also keeps a sub-agent's context out of the parent's
                         // live meter (`foldTurnUsage` below would latch its max — the #398 shape).
+                        // #604: task lifecycle is session-level, not rendered transcript —
+                        // observe it before the sidechain filter.
+                        background.observe(slug, m);
                         if (isSidechainMessage(m))
                             return;
                         // Capture the session id as it arrives mid-stream (the translator
@@ -1182,6 +1234,9 @@ export function makeChatHandler(deps) {
                     onMessage: async (m) => {
                         // A slash-command turn can spawn a Task too; its nested steps never
                         // render top-level ({@link isSidechainMessage}).
+                        // #604: task lifecycle is session-level, not rendered transcript —
+                        // observe it before the sidechain filter.
+                        background.observe(slug, m);
                         if (isSidechainMessage(m))
                             return;
                         if (m.session_id) {
@@ -1384,6 +1439,10 @@ export function makeChatHandler(deps) {
         clients.add(socket);
         for (const info of hub.runningSessions())
             send(activeFrame(info));
+        // #604: and on what background work is in flight, so a remounted pane's
+        // pinned bar is populated from the first paint rather than after a poll.
+        for (const s of background.snapshot())
+            send({ type: "chat:background", payload: { ...s } });
         // Heartbeat: browsers auto-answer protocol ping frames with a pong, so a
         // client whose TCP has silently died (idle drop, sleep) fails to pong and is
         // terminated on the next tick — freeing server resources and letting the

package/packages/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@paddock/server",
-  "version": "0.68.0",
+  "version": "0.69.0",
   "private": true,
   "type": "module"
 }