@edspencer/paddock 0.68.1 → 0.70.0

package/package.json

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

package/packages/server/dist/agent-errors.js

@@ -44,8 +44,14 @@ const KNOWN_CAUSES = [
         // Anchored to `claude` specifically. A bare /ENOENT/ would claim a missing
         // CLI for any file the engine failed to open, which is a confident wrong
         // answer — worse than the raw error it replaces.
+        //
+        // Name only what actually reads PATH (#771): the CLI runtime. The sweeper
+        // is always on it; triggers and chat turns only on `driveMode: batch`. An
+        // earlier wording said "the sweeper and triggers", which sent an operator
+        // on the default `session` mode to check the wrong thing.
         pattern: /ENOENT[^\n]{0,40}claude|claude: (command )?not found/i,
-        cause: "the `claude` CLI is not on PATH (needed by the sweeper and triggers)",
+        cause: "the `claude` CLI is not on PATH (needed by the sweeper, and by " +
+            "triggers/turns on `driveMode: batch`)",
     },
 ];
 /**

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/cli/paddock.js

@@ -78,14 +78,19 @@ function readVersion() {
 /**
  * Put our bundled `claude` on PATH for child processes.
  *
- * Chat turns do NOT need this: they run herdctl's SDK runtime, which resolves
- * the binary from the Claude Agent SDK's own platform package via
- * `require.resolve` and never consults PATH. But the post-turn sweeper and all
- * triggers are one-shot `trigger()` calls on the CLI runtime, which does
- * `execa("claude", …)` — by name, without execa's `preferLocal`, so a local
- * install is invisible to it unless PATH says otherwise.
+ * Chat turns do NOT need this on the default `driveMode: session`: they run
+ * herdctl's SDK runtime, which resolves the binary from the Claude Agent SDK's
+ * own platform package via `require.resolve` and never consults PATH. The
+ * post-turn sweeper is the one unconditional user: always a one-shot
+ * `trigger()` call on the CLI runtime, which does `execa("claude", …)` — by
+ * name, without execa's `preferLocal`, so a local install is invisible to it
+ * unless PATH says otherwise. Triggers join it there only on `driveMode:
+ * batch`: a trigger resolves its drive mode exactly like a chat does
+ * (per-project override else `cfg.driveMode` — `resolveDriveMode` in
+ * ws-triggers.ts), so on a stock instance no trigger consults PATH either.
  *
- * Without this, chats work and every sweep/trigger fails (logged, non-fatal).
+ * Without this, chats work and every sweep fails (logged, non-fatal) — plus
+ * every trigger and turn on `driveMode: batch`.
  */
 function addBundledBinsToPath() {
     const owner = findUp(path.join("node_modules", ".bin"));

package/packages/server/dist/config.d.ts

@@ -386,11 +386,14 @@ export interface PaddockConfig {
         warnings: string[];
     };
     /**
-     * Instance default for the hook-management MCP (Epic G / G5, GG-4) — the
-     * `mcp__paddock_manage__{list,set,remove}_hook` tools that let a project agent
-     * declare/edit/delete its own event hooks. A sibling of {@link selfMcpWriteEnabled}:
+     * Instance default for the hook-management MCP (Epic G / G5, GG-4) — now the
+     * unified TRIGGER tools `mcp__paddock_manage__{list_triggers,set_trigger,
+     * remove_trigger,run_trigger}` that let a project agent declare/edit/delete/fire
+     * its own triggers. Epic T / T3 collapsed the former `*_hook` and `*_schedule`
+     * verbs into these; the flag and its env var kept the `hooks` spelling.
+     * A sibling of {@link selfMcpWriteEnabled}:
      * OFF by default (opt-in), and only surfaces when the self-MCP write tools are also
-     * present (the hook tools live on the same injected server, appended in the write
+     * present (the trigger tools live on the same injected server, appended in the write
      * block). Driven by `PADDOCK_HOOKS_MCP`; accepts 1/true/yes. A per-project
      * `hooksMcpEnabled` override wins at dispatch (resolved via
      * {@link import("./hook-config.js").resolveHooksMcpEnabled}), the same
@@ -580,7 +583,6 @@ export interface PaddockConfigFile {
         autoReDrive?: boolean | string;
         debounceMs?: number | string;
         maxRetries?: number | string;
-        limboTimeoutMs?: number | string;
     };
     /**
      * Inbound composer-attachment config (issue #328). Every field optional; a

package/packages/server/dist/config.js

@@ -456,7 +456,6 @@ function loadRecoveryConfig(file) {
         autoReDrive: loadRecoveryBool("PADDOCK_RECOVERY_AUTODRIVE", f.autoReDrive, DEFAULT_RECOVERY.autoReDrive),
         debounceMs: loadRecoveryInt("PADDOCK_RECOVERY_DEBOUNCE_MS", f.debounceMs, DEFAULT_RECOVERY.debounceMs),
         maxRetries: loadRecoveryInt("PADDOCK_RECOVERY_MAX_RETRIES", f.maxRetries, DEFAULT_RECOVERY.maxRetries),
-        limboTimeoutMs: loadRecoveryInt("PADDOCK_RECOVERY_LIMBO_MS", f.limboTimeoutMs, DEFAULT_RECOVERY.limboTimeoutMs),
     };
 }
 /**

package/packages/server/dist/instance-config.js

@@ -254,7 +254,7 @@ export const FIELDS = [
     { key: "environmentPrompt", group: "capabilities", label: "Environment prompt", help: "Appended to every keeper turn's system prompt: what the agent should know about rendering into Paddock rather than a terminal. Clear it to append nothing.", type: "text", envVars: ["PADDOCK_ENVIRONMENT_PROMPT"], envShadowWhenDefined: true, default: DEFAULT_ENVIRONMENT_PROMPT, editable: true, coerce: promptText },
     { key: "selfMcpEnabled", group: "capabilities", label: "Self-management MCP (read)", help: "Let keepers list/read projects and other chats.", type: "boolean", envVars: ["PADDOCK_SELF_MCP"], default: false, editable: true, coerce: asBool },
     { key: "selfMcpWriteEnabled", group: "capabilities", label: "Self-management MCP (write)", help: "Let keepers create/fork/message chats (needs read enabled too).", type: "boolean", envVars: ["PADDOCK_SELF_MCP_WRITE"], default: false, editable: true, coerce: asBool },
-    { key: "selfMcpProjectsEnabled", group: "capabilities", label: "Self-management MCP (projects)", help: "Let keepers create whole new projects, cloning a repo when repo-backed (needs self-MCP write).", type: "boolean", envVars: ["PADDOCK_SELF_MCP_PROJECTS"], default: false, editable: true, coerce: asBool },
+    { key: "selfMcpProjectsEnabled", group: "capabilities", label: "Self-management MCP (projects)", help: "Let keepers create new projects and promote existing ones — including a git clone of a repo URL the agent supplies (needs self-MCP write).", type: "boolean", envVars: ["PADDOCK_SELF_MCP_PROJECTS"], default: false, editable: true, coerce: asBool },
     { key: "maxSpawnDepth", group: "capabilities", label: "Max spawn depth", help: "How deep a spawn tree may grow before children lose the self-MCP.", type: "number", envVars: ["PADDOCK_MAX_SPAWN_DEPTH"], default: DEFAULT_MAX_SPAWN_DEPTH, editable: true, coerce: spawnDepth },
     { key: "scheduleMutationEnabled", group: "capabilities", label: "Schedule mutation", help: "Allow programmatic schedule add/remove at runtime.", type: "boolean", envVars: ["PADDOCK_SCHEDULE_MUTATION"], default: false, editable: true, coerce: asBool },
     { key: "hooksMcpEnabled", group: "capabilities", label: "Hooks MCP", help: "Let agents declare/edit their own event hooks (needs self-MCP write).", type: "boolean", envVars: ["PADDOCK_HOOKS_MCP"], default: false, editable: true, coerce: asBool },
@@ -264,7 +264,6 @@ export const FIELDS = [
     { key: "recovery.autoReDrive", group: "recovery", label: "Auto re-drive", type: "boolean", envVars: ["PADDOCK_RECOVERY_AUTODRIVE"], default: DEFAULT_RECOVERY.autoReDrive, editable: true, coerce: asBool },
     { key: "recovery.debounceMs", group: "recovery", label: "Debounce (ms)", type: "number", envVars: ["PADDOCK_RECOVERY_DEBOUNCE_MS"], default: DEFAULT_RECOVERY.debounceMs, editable: true, coerce: nonNegInt },
     { key: "recovery.maxRetries", group: "recovery", label: "Max retries", type: "number", envVars: ["PADDOCK_RECOVERY_MAX_RETRIES"], default: DEFAULT_RECOVERY.maxRetries, editable: true, coerce: nonNegInt },
-    { key: "recovery.limboTimeoutMs", group: "recovery", label: "Limbo timeout (ms)", type: "number", envVars: ["PADDOCK_RECOVERY_LIMBO_MS"], default: DEFAULT_RECOVERY.limboTimeoutMs, editable: true, coerce: nonNegInt },
     // Attachments (issue #328).
     { key: "attachments.enabled", group: "attachments", label: "Enabled", type: "boolean", envVars: ["PADDOCK_ATTACHMENTS_ENABLED"], default: DEFAULT_ATTACHMENTS.enabled, editable: true, coerce: asBool },
     { key: "attachments.maxFileSizeMb", group: "attachments", label: "Max file size (MB)", type: "number", envVars: ["PADDOCK_ATTACHMENTS_MAX_FILE_SIZE_MB"], default: DEFAULT_ATTACHMENTS.maxFileSizeMb, editable: true, coerce: posInt },

package/packages/server/dist/recovery-config.d.ts

@@ -67,12 +67,6 @@ export interface RecoveryConfig {
      * `PADDOCK_RECOVERY_MAX_RETRIES`.
      */
     maxRetries: number;
-    /**
-     * Layer 2 backstop — if a kept-alive keeper session shows no activity for this
-     * many ms after a killed-task notification, surface it as stuck. `0` disables
-     * the backstop (the default). Env `PADDOCK_RECOVERY_LIMBO_MS`.
-     */
-    limboTimeoutMs: number;
 }
 /**
  * A per-project recovery override as stored in `project.yaml` — every field

package/packages/server/dist/recovery-config.js

@@ -43,7 +43,6 @@ export const DEFAULT_RECOVERY = Object.freeze({
     autoReDrive: false,
     debounceMs: 5000,
     maxRetries: 1,
-    limboTimeoutMs: 0,
 });
 /** The `<status>` values a killed-at-turn-boundary task notification carries. */
 const TERMINATED_STATUSES = new Set(["killed", "stopped"]);
@@ -81,8 +80,6 @@ export function sanitizeRecoveryOverride(value) {
         out.debounceMs = o.debounceMs;
     if (isNonNegativeInt(o.maxRetries))
         out.maxRetries = o.maxRetries;
-    if (isNonNegativeInt(o.limboTimeoutMs))
-        out.limboTimeoutMs = o.limboTimeoutMs;
     return Object.keys(out).length > 0 ? out : undefined;
 }
 /**
@@ -100,6 +97,5 @@ export function resolveRecoveryConfig(override, instanceDefault) {
         autoReDrive: clean.autoReDrive ?? instanceDefault.autoReDrive,
         debounceMs: clean.debounceMs ?? instanceDefault.debounceMs,
         maxRetries: clean.maxRetries ?? instanceDefault.maxRetries,
-        limboTimeoutMs: clean.limboTimeoutMs ?? instanceDefault.limboTimeoutMs,
     };
 }

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) {