@bubblebrain-ai/bubble 0.0.37 → 0.0.38

package/dist/tasks/manager.js

@@ -0,0 +1,530 @@
+/**
+ * Unified process manager: background tasks + managed servers
+ * (docs/background-tasks-design.md §2.2).
+ *
+ * One registry owns every child process Bubble manages, discriminated by
+ * `kind: "task" | "server"` — NOT `purpose`, which is a shipped model-facing
+ * server field (preview|verification). Server semantics (port conflict scan,
+ * readiness probe, lifecycle, lastUsedAt touch-on-read) are preserved
+ * verbatim from the absorbed src/tools/server-manager.ts; that module remains
+ * as a re-export shim so server tools, agent.ts, and their tests are
+ * untouched.
+ *
+ * State is per-process (as the old server registry was). main.ts fetches the
+ * instance via getProcessManager() and passes it explicitly to createAllTools
+ * and the TUI App — the TUI bridge is subscription-based (onChange /
+ * onTaskFinished), never a hidden import (design §2.2a).
+ *
+ * Task children are spawned detached (own process group, killable as a tree)
+ * but NOT unref'd — unlike servers, a task must never outlive the parent
+ * process, so the event loop keeps owning it (design §2.2a). Reaping is
+ * three-layered (design §2.2b): graceful shutdownTasks() with escalation, a
+ * SIGKILL-only path for signal handlers, and a process.once("exit") backstop.
+ */
+import { spawn } from "node:child_process";
+import { existsSync } from "node:fs";
+import net from "node:net";
+import { platform } from "node:os";
+import { appendTailCapped, killProcessTree, stripAnsi, tail } from "./process-utils.js";
+const MAX_LOG_BYTES = 96 * 1024;
+const STOP_FORCE_AFTER_MS = 1000;
+const MAX_RUNNING_TASKS_PER_SESSION = 8;
+const MAX_FINISHED_TASKS = 20;
+// ---------------------------------------------------------------------------
+// Manager
+// ---------------------------------------------------------------------------
+export class ProcessManager {
+    registry = new Map();
+    nextServerId = 1;
+    nextTaskId = 1;
+    /** Bumped on task start/finish/kill — the reminder's state-change gate (design §2.3a). */
+    taskStateVersion = 0;
+    changeListeners = new Set();
+    finishListeners = new Set();
+    // -- tasks ----------------------------------------------------------------
+    getTaskStateVersion() {
+        return this.taskStateVersion;
+    }
+    startTask(input) {
+        if (!existsSync(input.cwd)) {
+            throw new Error(`Working directory does not exist: ${input.cwd}`);
+        }
+        const command = input.command.trim();
+        if (!command)
+            throw new Error("command is required");
+        // Atomic reserve (design §2.2d): the cap check and record insertion are
+        // synchronous with no await between them; spawn failures roll back below.
+        this.reserveTaskSlot(input.ownerSessionId);
+        const shell = platform() === "win32" ? "cmd.exe" : "bash";
+        const shellArgs = platform() === "win32" ? ["/c", command] : ["-c", command];
+        let child;
+        try {
+            child = spawn(shell, shellArgs, {
+                cwd: input.cwd,
+                stdio: ["ignore", "pipe", "pipe"],
+                env: process.env,
+                detached: platform() !== "win32",
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            throw error instanceof Error ? error : new Error(String(error));
+        }
+        return this.registerTaskChild(child, { ...input, command });
+    }
+    /** Ctrl+G promotion: adopt a child the bash tool already spawned (§2.5). */
+    adoptTask(input) {
+        this.reserveTaskSlot(input.ownerSessionId);
+        return this.registerTaskChild(input.child, input, {
+            outputSoFar: input.outputSoFar,
+            startedAt: input.startedAt,
+        });
+    }
+    reserveTaskSlot(ownerSessionId) {
+        const running = this.taskRecords().filter((task) => task.status === "running" && task.ownerSessionId === ownerSessionId);
+        if (running.length >= MAX_RUNNING_TASKS_PER_SESSION) {
+            throw new Error(`Background task limit reached (${MAX_RUNNING_TASKS_PER_SESSION} running). `
+                + "Wait for one to finish with task_output, or kill one with kill_task.");
+        }
+    }
+    registerTaskChild(child, input, seed) {
+        const id = `task_${String(this.nextTaskId++).padStart(4, "0")}`;
+        const record = {
+            kind: "task",
+            id,
+            command: input.command,
+            description: input.description,
+            cwd: input.cwd,
+            pid: child.pid,
+            status: "running",
+            startedAt: seed?.startedAt ?? Date.now(),
+            output: seed?.outputSoFar ?? "",
+            outputTruncated: false,
+            ownerSessionId: input.ownerSessionId,
+            child,
+        };
+        this.registry.set(id, record);
+        const append = (data) => {
+            const before = record.output;
+            record.output = appendTailCapped(record.output, data.toString(), MAX_LOG_BYTES);
+            if (!record.outputTruncated && before.length + data.length > record.output.length) {
+                record.outputTruncated = true;
+            }
+        };
+        child.stdout?.on("data", append);
+        child.stderr?.on("data", append);
+        child.once("error", (error) => {
+            record.output = appendTailCapped(record.output, `\n[task failed to start: ${error.message}]\n`, MAX_LOG_BYTES);
+            this.finalizeTask(record, "failed", null);
+        });
+        child.once("exit", (code) => {
+            if (record.status === "running") {
+                this.finalizeTask(record, code === 0 ? "completed" : "failed", code);
+            }
+        });
+        this.bumpTaskState(record);
+        return this.publicTask(record);
+    }
+    finalizeTask(record, status, exitCode) {
+        if (record.status !== "running")
+            return;
+        record.status = status;
+        record.exitCode = exitCode;
+        record.endedAt = Date.now();
+        record.child = undefined;
+        this.evictFinishedTasks();
+        this.bumpTaskState(record);
+        const snapshot = this.publicTask(record);
+        for (const listener of this.finishListeners) {
+            try {
+                listener(snapshot);
+            }
+            catch {
+                // Listener failures must never break task lifecycle.
+            }
+        }
+    }
+    getTask(id) {
+        const record = this.registry.get(id);
+        if (!record || record.kind !== "task")
+            return undefined;
+        return this.publicTask(record);
+    }
+    listTasks(ownerSessionId) {
+        return this.taskRecords()
+            .filter((task) => ownerSessionId === undefined || task.ownerSessionId === ownerSessionId)
+            .map((task) => this.publicTask(task));
+    }
+    taskOutputTail(id, maxChars = 12000) {
+        const record = this.registry.get(id);
+        if (!record || record.kind !== "task")
+            return undefined;
+        // Single choke point for every task-output consumer (wake, reminder,
+        // task_output tool, inspector): strip ANSI color noise before tailing.
+        return tail(stripAnsi(record.output), maxChars);
+    }
+    markTaskDelivered(id) {
+        const record = this.registry.get(id);
+        if (!record || record.kind !== "task")
+            return;
+        if (record.deliveredAt === undefined) {
+            record.deliveredAt = Date.now();
+            // Delivered tasks drop their output to bound memory (design §2.2d);
+            // keep the metadata line for the transcript/reminder demotion.
+            if (record.status !== "running")
+                record.output = "";
+        }
+    }
+    async waitTasks(ids, options = {}) {
+        const timeoutMs = options.timeoutMs ?? 30000;
+        const mode = options.mode ?? "any";
+        const wanted = new Set(ids);
+        const satisfied = () => {
+            const finished = ids.filter((id) => {
+                const task = this.registry.get(id);
+                return task?.kind === "task" && task.status !== "running";
+            });
+            return mode === "all" ? finished.length === wanted.size : finished.length > 0;
+        };
+        if (!satisfied() && timeoutMs > 0) {
+            await new Promise((resolve) => {
+                let settled = false;
+                const finish = () => {
+                    if (settled)
+                        return;
+                    settled = true;
+                    this.finishListeners.delete(onFinish);
+                    clearTimeout(timer);
+                    resolve();
+                };
+                const onFinish = (task) => {
+                    if (wanted.has(task.id) && satisfied())
+                        finish();
+                };
+                const timer = setTimeout(finish, timeoutMs);
+                timer.unref?.();
+                this.finishListeners.add(onFinish);
+            });
+        }
+        return ids
+            .map((id) => this.getTask(id))
+            .filter((task) => task !== undefined);
+    }
+    async killTask(id) {
+        const record = this.registry.get(id);
+        if (!record || record.kind !== "task")
+            return undefined;
+        if (record.status !== "running")
+            return this.publicTask(record);
+        const pid = record.child?.pid ?? record.pid;
+        // Mark first so the exit listener does not double-finalize as failed.
+        this.finalizeTask(record, "killed", null);
+        if (pid) {
+            killProcessTree(pid, "SIGTERM");
+            const forceTimer = setTimeout(() => killProcessTree(pid, "SIGKILL"), STOP_FORCE_AFTER_MS);
+            forceTimer.unref?.();
+        }
+        return this.publicTask(record);
+    }
+    /** Graceful reaping for shutdownRuntime (design §2.2b layer 1). */
+    async shutdownTasks() {
+        const running = this.taskRecords().filter((task) => task.status === "running");
+        if (running.length === 0)
+            return;
+        for (const task of running) {
+            const pid = task.child?.pid ?? task.pid;
+            if (pid)
+                killProcessTree(pid, "SIGTERM");
+        }
+        await new Promise((resolve) => setTimeout(resolve, STOP_FORCE_AFTER_MS));
+        for (const task of running) {
+            const pid = task.child?.pid ?? task.pid;
+            if (pid)
+                killProcessTree(pid, "SIGKILL");
+            if (task.status === "running")
+                this.finalizeTask(task, "killed", null);
+        }
+    }
+    /** SIGKILL-only reaping for synchronous signal/exit paths (§2.2b layers 2-3). */
+    reapTasksSync() {
+        for (const task of this.taskRecords()) {
+            if (task.status !== "running")
+                continue;
+            const pid = task.child?.pid ?? task.pid;
+            if (pid)
+                killProcessTree(pid, "SIGKILL");
+            task.status = "killed";
+            task.endedAt = Date.now();
+            task.child = undefined;
+        }
+    }
+    onTaskFinished(listener) {
+        this.finishListeners.add(listener);
+        return () => this.finishListeners.delete(listener);
+    }
+    onChange(listener) {
+        this.changeListeners.add(listener);
+        return () => this.changeListeners.delete(listener);
+    }
+    bumpTaskState(record) {
+        this.taskStateVersion += 1;
+        const snapshot = this.publicTask(record);
+        for (const listener of this.changeListeners) {
+            try {
+                listener(snapshot);
+            }
+            catch {
+                // Listener failures must never break task lifecycle.
+            }
+        }
+    }
+    evictFinishedTasks() {
+        const finished = this.taskRecords()
+            .filter((task) => task.status !== "running")
+            .sort((a, b) => (a.endedAt ?? 0) - (b.endedAt ?? 0));
+        // Evict oldest DELIVERED first; fall back to oldest finished overall.
+        while (finished.length > MAX_FINISHED_TASKS) {
+            const victim = finished.find((task) => task.deliveredAt !== undefined) ?? finished[0];
+            finished.splice(finished.indexOf(victim), 1);
+            this.registry.delete(victim.id);
+        }
+    }
+    taskRecords() {
+        return [...this.registry.values()].filter((record) => record.kind === "task");
+    }
+    publicTask(record) {
+        const { child: _child, output: _output, ...info } = record;
+        return { ...info };
+    }
+    // -- servers (moved verbatim from server-manager.ts, kind-filtered) --------
+    async startManagedServer(input) {
+        if (!existsSync(input.cwd)) {
+            throw new Error(`Working directory does not exist: ${input.cwd}`);
+        }
+        const command = input.command.trim();
+        if (!command) {
+            throw new Error("command is required");
+        }
+        if (input.port !== undefined) {
+            const managed = this.serverRecords().find((server) => server.port === input.port && isActiveStatus(server.status));
+            if (managed) {
+                throw new Error(`Port ${input.port} is already managed by ${managed.id}. Stop it before starting another server.`);
+            }
+            if (await isPortOpen(input.port)) {
+                throw new Error(`Port ${input.port} is already in use by an unmanaged process.`);
+            }
+        }
+        const shell = platform() === "win32" ? "cmd.exe" : "bash";
+        const shellArgs = platform() === "win32" ? ["/c", command] : ["-c", command];
+        const child = spawn(shell, shellArgs, {
+            cwd: input.cwd,
+            stdio: ["ignore", "pipe", "pipe"],
+            env: process.env,
+            detached: platform() !== "win32",
+            windowsHide: true,
+        });
+        child.unref();
+        unrefStream(child.stdout);
+        unrefStream(child.stderr);
+        const now = Date.now();
+        const id = `server_${String(this.nextServerId++).padStart(4, "0")}`;
+        const readinessUrl = input.readinessUrl ?? (input.port ? `http://localhost:${input.port}` : undefined);
+        const record = {
+            kind: "server",
+            id,
+            command,
+            cwd: input.cwd,
+            ...(input.port !== undefined ? { port: input.port } : {}),
+            ...(readinessUrl ? { url: readinessUrl } : {}),
+            ownerSessionId: input.ownerSessionId,
+            ownerRunId: input.ownerRunId,
+            purpose: input.purpose ?? "preview",
+            lifecycle: input.lifecycle ?? "keep_alive",
+            startedAt: now,
+            lastUsedAt: now,
+            status: "starting",
+            pid: child.pid,
+            child,
+            logs: "",
+        };
+        this.registry.set(id, record);
+        child.stdout.on("data", (data) => appendServerLog(record, data.toString()));
+        child.stderr.on("data", (data) => appendServerLog(record, data.toString()));
+        child.once("error", (error) => {
+            record.status = "failed";
+            appendServerLog(record, `\n[server failed: ${error.message}]\n`);
+        });
+        child.once("exit", (code) => {
+            record.exitCode = code;
+            if (record.status !== "stopped") {
+                record.status = code === 0 ? "exited" : "failed";
+            }
+            record.child = undefined;
+        });
+        const timeoutSec = input.timeoutSec ?? 30;
+        const ready = readinessUrl
+            ? await waitForReadiness(record, readinessUrl, timeoutSec)
+            : await waitForProcessToStayAlive(record, Math.min(timeoutSec, 2));
+        if (!ready) {
+            const logs = record.logs.trim();
+            await this.stopManagedServer(id);
+            throw new Error(`Server ${id} did not become ready within ${timeoutSec}s.${logs ? `\n\nLogs:\n${tail(logs, 4000)}` : ""}`);
+        }
+        record.status = readinessUrl ? "ready" : "running";
+        record.lastUsedAt = Date.now();
+        return publicServerInfo(record);
+    }
+    listManagedServers() {
+        return this.serverRecords().map(publicServerInfo);
+    }
+    getManagedServer(id) {
+        const server = this.registry.get(id);
+        if (!server || server.kind !== "server")
+            return undefined;
+        server.lastUsedAt = Date.now();
+        return publicServerInfo(server);
+    }
+    getManagedServerLogs(id, maxChars = 12000) {
+        const server = this.registry.get(id);
+        if (!server || server.kind !== "server")
+            return undefined;
+        server.lastUsedAt = Date.now();
+        return tail(server.logs, maxChars);
+    }
+    async stopManagedServer(id) {
+        const server = this.registry.get(id);
+        if (!server || server.kind !== "server")
+            return undefined;
+        server.status = "stopped";
+        server.lastUsedAt = Date.now();
+        const child = server.child;
+        if (child?.pid) {
+            killProcessTree(child.pid, "SIGTERM");
+            await new Promise((resolve) => setTimeout(resolve, STOP_FORCE_AFTER_MS));
+            killProcessTree(child.pid, "SIGKILL");
+        }
+        server.child = undefined;
+        return publicServerInfo(server);
+    }
+    async stopAutoServersForSession(sessionID) {
+        if (!sessionID)
+            return;
+        const owned = this.serverRecords().filter((server) => server.ownerSessionId === sessionID && server.lifecycle === "auto" && isActiveStatus(server.status));
+        await Promise.all(owned.map((server) => this.stopManagedServer(server.id)));
+    }
+    /** process.once("exit") backstop (§2.2b layer 3). */
+    reapOnExit() {
+        for (const record of this.registry.values()) {
+            if (record.kind === "task") {
+                if (record.status === "running") {
+                    const pid = record.child?.pid ?? record.pid;
+                    if (pid)
+                        killProcessTree(pid, "SIGKILL");
+                }
+                continue;
+            }
+            if (record.child?.pid && record.lifecycle !== "keep_alive") {
+                killProcessTree(record.child.pid, "SIGKILL");
+            }
+        }
+    }
+    serverRecords() {
+        return [...this.registry.values()].filter((record) => record.kind === "server");
+    }
+}
+// ---------------------------------------------------------------------------
+// Process-wide instance + compatibility surface
+// ---------------------------------------------------------------------------
+// One registry per process (exactly the scope the old module-level server Map
+// had). main.ts passes this instance down explicitly; the server-manager shim
+// delegates to it so existing imports keep working.
+const defaultManager = new ProcessManager();
+export function getProcessManager() {
+    return defaultManager;
+}
+export const startManagedServer = defaultManager.startManagedServer.bind(defaultManager);
+export const listManagedServers = defaultManager.listManagedServers.bind(defaultManager);
+export const getManagedServer = defaultManager.getManagedServer.bind(defaultManager);
+export const getManagedServerLogs = defaultManager.getManagedServerLogs.bind(defaultManager);
+export const stopManagedServer = defaultManager.stopManagedServer.bind(defaultManager);
+export const stopAutoServersForSession = defaultManager.stopAutoServersForSession.bind(defaultManager);
+process.once("exit", () => {
+    defaultManager.reapOnExit();
+});
+// ---------------------------------------------------------------------------
+// Server internals (moved verbatim)
+// ---------------------------------------------------------------------------
+function publicServerInfo(server) {
+    return {
+        id: server.id,
+        command: server.command,
+        cwd: server.cwd,
+        port: server.port,
+        url: server.url,
+        ownerSessionId: server.ownerSessionId,
+        ownerRunId: server.ownerRunId,
+        purpose: server.purpose,
+        lifecycle: server.lifecycle,
+        startedAt: server.startedAt,
+        lastUsedAt: server.lastUsedAt,
+        status: server.status,
+        pid: server.pid,
+        exitCode: server.exitCode,
+    };
+}
+function appendServerLog(server, chunk) {
+    server.logs = appendTailCapped(server.logs, chunk, MAX_LOG_BYTES);
+}
+function unrefStream(stream) {
+    stream.unref?.();
+}
+async function waitForReadiness(server, url, timeoutSec) {
+    const deadline = Date.now() + timeoutSec * 1000;
+    while (Date.now() < deadline) {
+        if (!isActiveStatus(server.status))
+            return false;
+        if (await canFetch(url))
+            return true;
+        await new Promise((resolve) => setTimeout(resolve, 250));
+    }
+    return false;
+}
+async function waitForProcessToStayAlive(server, timeoutSec) {
+    const deadline = Date.now() + timeoutSec * 1000;
+    while (Date.now() < deadline) {
+        if (!isActiveStatus(server.status))
+            return false;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    return isActiveStatus(server.status);
+}
+async function canFetch(url) {
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), 1000);
+    try {
+        const response = await fetch(url, { signal: controller.signal });
+        return response.status < 500;
+    }
+    catch {
+        return false;
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
+function isActiveStatus(status) {
+    return status === "starting" || status === "ready" || status === "running";
+}
+async function isPortOpen(port) {
+    return await new Promise((resolve) => {
+        const socket = net.createConnection({ host: "127.0.0.1", port });
+        const done = (open) => {
+            socket.removeAllListeners();
+            socket.destroy();
+            resolve(open);
+        };
+        socket.once("connect", () => done(true));
+        socket.once("error", () => done(false));
+        socket.setTimeout(250, () => done(false));
+    });
+}

package/dist/tasks/process-utils.d.ts

@@ -0,0 +1,10 @@
+/**
+ * Shared child-process mechanics for the unified process manager (background
+ * tasks + managed servers) and the bash tool: process-tree kill with Windows
+ * fallback, tail-keeping capped log buffers.
+ */
+export declare function killProcessTree(pid: number, signal: NodeJS.Signals): void;
+/** Keep the LAST maxBytes of a growing log (ring-buffer semantics). */
+export declare function appendTailCapped(current: string, chunk: string, maxBytes: number): string;
+export declare function tail(value: string, maxChars: number): string;
+export declare function stripAnsi(value: string): string;

package/dist/tasks/process-utils.js

@@ -0,0 +1,49 @@
+/**
+ * Shared child-process mechanics for the unified process manager (background
+ * tasks + managed servers) and the bash tool: process-tree kill with Windows
+ * fallback, tail-keeping capped log buffers.
+ */
+import { spawn } from "node:child_process";
+import { platform } from "node:os";
+export function killProcessTree(pid, signal) {
+    if (platform() === "win32") {
+        try {
+            spawn("taskkill", ["/pid", String(pid), "/f", "/t"], {
+                stdio: "ignore",
+                windowsHide: true,
+            });
+        }
+        catch {
+            // Process may already be gone or taskkill may be unavailable.
+        }
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    }
+    catch {
+        try {
+            process.kill(pid, signal);
+        }
+        catch {
+            // Process already exited.
+        }
+    }
+}
+/** Keep the LAST maxBytes of a growing log (ring-buffer semantics). */
+export function appendTailCapped(current, chunk, maxBytes) {
+    const next = current + chunk;
+    if (Buffer.byteLength(next, "utf-8") <= maxBytes)
+        return next;
+    return Buffer.from(next, "utf-8").subarray(-maxBytes).toString("utf-8");
+}
+export function tail(value, maxChars) {
+    return value.length <= maxChars ? value : value.slice(-maxChars);
+}
+// Test runners color their output; raw escape sequences in a model-facing
+// tail are token noise (observed with vitest in the first field test).
+// eslint-disable-next-line no-control-regex
+const ANSI_PATTERN = /\u001b\[[0-9;?]*[a-zA-Z]|\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?/g;
+export function stripAnsi(value) {
+    return value.replace(ANSI_PATTERN, "");
+}

package/dist/tasks/promotion.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Ctrl+G send-to-background promotion channel (background-tasks design §2.5).
+ *
+ * A running foreground bash tool call registers a promotion handler keyed by
+ * its toolCall id at spawn; the TUI requests promotion when the user presses
+ * Ctrl+G. The handler returns the new task id on success, or undefined when
+ * it is too late (the command already reached a terminal state — exit,
+ * timeout, cancel — a benign race, not an error).
+ */
+export type PromotionHandler = () => string | undefined;
+export declare class PromotionChannel {
+    private readonly handlers;
+    register(toolCallId: string, handler: PromotionHandler): () => void;
+    /** Returns the promoted task id, or undefined when nothing was promotable. */
+    requestPromotion(toolCallId: string): string | undefined;
+    hasPromotable(toolCallId: string): boolean;
+}

package/dist/tasks/promotion.js

@@ -0,0 +1,30 @@
+/**
+ * Ctrl+G send-to-background promotion channel (background-tasks design §2.5).
+ *
+ * A running foreground bash tool call registers a promotion handler keyed by
+ * its toolCall id at spawn; the TUI requests promotion when the user presses
+ * Ctrl+G. The handler returns the new task id on success, or undefined when
+ * it is too late (the command already reached a terminal state — exit,
+ * timeout, cancel — a benign race, not an error).
+ */
+export class PromotionChannel {
+    handlers = new Map();
+    register(toolCallId, handler) {
+        this.handlers.set(toolCallId, handler);
+        return () => {
+            if (this.handlers.get(toolCallId) === handler) {
+                this.handlers.delete(toolCallId);
+            }
+        };
+    }
+    /** Returns the promoted task id, or undefined when nothing was promotable. */
+    requestPromotion(toolCallId) {
+        const handler = this.handlers.get(toolCallId);
+        if (!handler)
+            return undefined;
+        return handler();
+    }
+    hasPromotable(toolCallId) {
+        return this.handlers.has(toolCallId);
+    }
+}

package/dist/tasks/wake.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Auto-resume wake decision + coalescing (background-tasks design §2.3b).
+ *
+ * Kept pure and out of the TUI so the guard rails are unit-testable:
+ * - debounce-before-fire coalescing (the idle input queue drains in ~0ms, so
+ *   merging can only happen BEFORE the wake is submitted);
+ * - user preemption (queued user input or a running turn suppresses the wake
+ *   — the state-change reminder covers the completion on the next turn);
+ * - config kill switch (tasks.auto_resume = false);
+ * - killed tasks never wake (killing is an explicit decision, not news).
+ */
+import type { BackgroundTaskInfo } from "./manager.js";
+export interface TaskWakeGateInput {
+    autoResume: boolean;
+    turnRunning: boolean;
+    queuedInputs: number;
+    exiting?: boolean;
+}
+export declare function shouldFireTaskWake(input: TaskWakeGateInput): boolean;
+export declare function taskEligibleForWake(task: BackgroundTaskInfo): boolean;
+export declare function formatTaskWakeSummary(tasks: BackgroundTaskInfo[], outputTail: (id: string) => string | undefined): string;
+export interface DanglingTaskStart {
+    id: string;
+    pid?: number;
+    startedAt?: number;
+    command?: string;
+    description?: string;
+}
+/**
+ * Resume-time orphan detection (design §2.2c): task_started markers with no
+ * matching task_finished/task_killed belong to a previous process. The caller
+ * probes pid liveness before reporting.
+ */
+export declare function findDanglingTaskStarts(entries: Array<{
+    type: string;
+    kind?: string;
+    value?: string;
+}>): DanglingTaskStart[];
+export declare function isPidAlive(pid: number | undefined): boolean;
+/**
+ * Debounce-then-fire coalescer: the first eligible completion arms a timer;
+ * completions inside the window fold into one wake payload.
+ */
+export declare class TaskWakeCoalescer {
+    private readonly delayMs;
+    private readonly fire;
+    private pending;
+    private timer;
+    constructor(delayMs: number, fire: (tasks: BackgroundTaskInfo[]) => void);
+    add(task: BackgroundTaskInfo): void;
+    /** Drop everything armed (session switch / exit). Returns what was pending. */
+    cancel(): BackgroundTaskInfo[];
+}