@bubblebrain-ai/bubble 0.0.36 → 0.0.38

package/dist/agent/internal-reminder-sanitizer.js

@@ -167,6 +167,8 @@ const INTERNAL_REASONING_REFERENCE_PATTERNS = [
     /Subagent lifecycle truth/i,
     /Count unique agent_id values only/i,
     /Do not describe a subagent as running or still working/i,
+    /Background task truth/i,
+    /Never re-run work a finished task already did/i,
 ];
 function consumeInternalBlockAtStart(text, final) {
     if (text.startsWith(INTERNAL_TAG_PREFIX)) {

package/dist/agent/task-lifecycle-reminder.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Background-task lifecycle reminder (background-tasks design §2.3a).
+ *
+ * Emission is STATE-CHANGE gated, never per-model-call: the reminder channel
+ * is append-only (each injection is a persistent meta message that survives
+ * pruning and compaction), so the caller compares the manager's task state
+ * version and builds a reminder only when the owned task set changed since
+ * the last emission. This mirrors the subagent lifecycle reminder's activity
+ * gate rather than firing while tasks are merely alive.
+ *
+ * Because compaction preserves meta messages but drops session markers, this
+ * reminder is also how the model recovers task ids after /compact.
+ */
+import type { BackgroundTaskInfo } from "../tasks/manager.js";
+export interface TaskReminderInput {
+    tasks: BackgroundTaskInfo[];
+    outputTail: (id: string) => string | undefined;
+    /**
+     * The task tools are already unlocked (the spawn path calls
+     * unlockDeferredTools). When true the tool_search hint is dropped — field
+     * test 2026-07-19 showed the unconditional hint makes the model burn a
+     * tool_search call for tools it already has.
+     */
+    toolsAvailable?: boolean;
+}
+export declare function buildTaskLifecycleReminder({ tasks, outputTail, toolsAvailable }: TaskReminderInput): string | undefined;

package/dist/agent/task-lifecycle-reminder.js

@@ -0,0 +1,59 @@
+/**
+ * Background-task lifecycle reminder (background-tasks design §2.3a).
+ *
+ * Emission is STATE-CHANGE gated, never per-model-call: the reminder channel
+ * is append-only (each injection is a persistent meta message that survives
+ * pruning and compaction), so the caller compares the manager's task state
+ * version and builds a reminder only when the owned task set changed since
+ * the last emission. This mirrors the subagent lifecycle reminder's activity
+ * gate rather than firing while tasks are merely alive.
+ *
+ * Because compaction preserves meta messages but drops session markers, this
+ * reminder is also how the model recovers task ids after /compact.
+ */
+const OUTPUT_TAIL_CHARS = 2000;
+export function buildTaskLifecycleReminder({ tasks, outputTail, toolsAvailable }) {
+    if (tasks.length === 0)
+        return undefined;
+    const running = tasks.filter((task) => task.status === "running");
+    const finishedUndelivered = tasks.filter((task) => task.status !== "running" && task.deliveredAt === undefined);
+    const finishedDelivered = tasks.filter((task) => task.status !== "running" && task.deliveredAt !== undefined);
+    if (running.length === 0 && finishedUndelivered.length === 0 && finishedDelivered.length === 0) {
+        return undefined;
+    }
+    const lines = ["Background task truth:"];
+    for (const task of running) {
+        const elapsed = Math.round((Date.now() - task.startedAt) / 1000);
+        lines.push(`- running: ${task.id} (${label(task)}, ${elapsed}s elapsed)`);
+    }
+    for (const task of finishedUndelivered) {
+        const elapsed = Math.round(((task.endedAt ?? Date.now()) - task.startedAt) / 1000);
+        lines.push(`- finished since last update: ${task.id} (${label(task)}) ${task.status}${task.exitCode != null ? ` exit ${task.exitCode}` : ""} in ${elapsed}s`);
+        const tail = outputTail(task.id)?.trim();
+        if (tail) {
+            lines.push(`  output tail:`);
+            lines.push(...clampTail(tail).split("\n").map((line) => `    ${line}`));
+            lines.push("  Call task_output only if you need more of the output.");
+        }
+    }
+    // Delivered final results already reached the model in full — id + status
+    // only, never the output again (mirrors the subagent delivered demotion).
+    for (const task of finishedDelivered) {
+        lines.push(`- delivered: ${task.id} ${task.status}${task.exitCode != null ? ` (exit ${task.exitCode})` : ""}`);
+    }
+    lines.push(toolsAvailable
+        ? "- Check tasks with task_output; stop them with kill_task. Both are already in your tool list — do NOT call tool_search for them."
+        : "- Check tasks with task_output; stop them with kill_task (deferred: load via tool_search with query 'select:task_output,kill_task' if not yet available).");
+    lines.push("- Never re-run work a finished task already did; never poll with foreground sleep.");
+    return lines.join("\n");
+}
+function label(task) {
+    return task.description?.trim() || truncate(task.command, 60);
+}
+function clampTail(tail) {
+    return tail.length <= OUTPUT_TAIL_CHARS ? tail : `…${tail.slice(-OUTPUT_TAIL_CHARS)}`;
+}
+function truncate(value, max) {
+    const oneLine = value.replace(/\s+/g, " ").trim();
+    return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 1)}…`;
+}

package/dist/agent.d.ts

@@ -101,6 +101,17 @@ export declare class Agent {
     messages: Message[];
     private provider;
     private sessionID?;
+    /**
+     * Bridge to the unified process manager's background tasks, wired by the
+     * host (main.ts) when the host supports them (background-tasks design
+     * §2.3a). list() is pre-filtered to the agent's bound session.
+     */
+    backgroundTasks?: {
+        list: () => import("./tasks/manager.js").BackgroundTaskInfo[];
+        version: () => number;
+        outputTail: (id: string) => string | undefined;
+    };
+    private lastTaskReminderVersion;
     private _providerId;
     private _model;
     private tools;
@@ -165,6 +176,21 @@ export declare class Agent {
      * the prompt's tool list.
      */
     injectDeferredToolsReminder(): void;
+    /**
+     * Rebinds the agent to a new session (TUI session switch). Keeps
+     * ownerSessionId on newly spawned background tasks and managed servers
+     * accurate (background-tasks design §2.2c).
+     */
+    setSessionID(sessionID: string | undefined): void;
+    getSessionID(): string | undefined;
+    /**
+     * Background-task reminder, state-change gated (design §2.3a): returns a
+     * reminder only when the owned task set changed since the last emission
+     * (started/finished/killed). The reminder channel is append-only, so
+     * emitting on every model call while tasks are merely alive would stack
+     * persistent duplicates that neither pruning nor compaction removes.
+     */
+    consumeBackgroundTaskReminder(): string | undefined;
     private runExternalHook;
     private injectHookModelContext;
     /** Whether a tool is registered on this agent (e.g. delegation tools on parents). */

package/dist/agent.js

@@ -19,6 +19,7 @@ import { buildDeferredToolsReminder, buildToolFreezeReminder, reminderForMode }
 import { HookBus } from "./orchestrator/hooks.js";
 import { normalizeHookInput, truncateHookText, } from "./hooks/index.js";
 import { createDefaultHooks } from "./orchestrator/default-hooks.js";
+import { buildTaskLifecycleReminder } from "./agent/task-lifecycle-reminder.js";
 import { mergeAgentCategories, parseThinkingLevel, resolveModelRoute, resolveSubagentRoute } from "./agent/categories.js";
 import { DEFAULT_AGENT_ROUTING, nearModelMatches, sanitizeAgentRouting, tierContextFromSnapshot } from "./agent/routing-catalog.js";
 import { buildModelRoutingPrompt } from "./prompt/routing.js";
@@ -100,6 +101,13 @@ export class Agent {
     messages = [];
     provider;
     sessionID;
+    /**
+     * Bridge to the unified process manager's background tasks, wired by the
+     * host (main.ts) when the host supports them (background-tasks design
+     * §2.3a). list() is pre-filtered to the agent's bound session.
+     */
+    backgroundTasks;
+    lastTaskReminderVersion = -1;
     _providerId;
     _model;
     tools = new Map();
@@ -261,6 +269,37 @@ export class Agent {
             this.injectSystemReminder(buildDeferredToolsReminder(deferredNames));
         }
     }
+    /**
+     * Rebinds the agent to a new session (TUI session switch). Keeps
+     * ownerSessionId on newly spawned background tasks and managed servers
+     * accurate (background-tasks design §2.2c).
+     */
+    setSessionID(sessionID) {
+        this.sessionID = sessionID;
+    }
+    getSessionID() {
+        return this.sessionID;
+    }
+    /**
+     * Background-task reminder, state-change gated (design §2.3a): returns a
+     * reminder only when the owned task set changed since the last emission
+     * (started/finished/killed). The reminder channel is append-only, so
+     * emitting on every model call while tasks are merely alive would stack
+     * persistent duplicates that neither pruning nor compaction removes.
+     */
+    consumeBackgroundTaskReminder() {
+        if (!this.backgroundTasks)
+            return undefined;
+        const version = this.backgroundTasks.version();
+        if (version === this.lastTaskReminderVersion)
+            return undefined;
+        this.lastTaskReminderVersion = version;
+        return buildTaskLifecycleReminder({
+            tasks: this.backgroundTasks.list(),
+            outputTail: (id) => this.backgroundTasks?.outputTail(id),
+            toolsAvailable: this.unlockedDeferred?.has("task_output") ?? false,
+        });
+    }
     async runExternalHook(request, abortSignal) {
         const events = [];
         if (!this.externalHooks) {

package/dist/approval/controller.d.ts

@@ -33,7 +33,9 @@ export interface ApprovalControllerOptions {
  *
  *   deny rule match              → reject (applies even under bypassPermissions)
  *   bypassPermissions            → auto-approve, no prompt
- *   default + edit|write         → auto-approve
+ *   default + edit|write         → auto-approve (workspace paths only; a
+ *                                  path outside the workspace falls through
+ *                                  to allow rules / the interactive prompt)
  *   plan                         → reject with instructions to use exit_plan_mode
  *   allow rule match             → auto-approve
  *   bash in session allowlist    → auto-approve

package/dist/approval/controller.js

@@ -5,7 +5,9 @@ import { truncateHookText } from "../hooks/index.js";
  *
  *   deny rule match              → reject (applies even under bypassPermissions)
  *   bypassPermissions            → auto-approve, no prompt
- *   default + edit|write         → auto-approve
+ *   default + edit|write         → auto-approve (workspace paths only; a
+ *                                  path outside the workspace falls through
+ *                                  to allow rules / the interactive prompt)
  *   plan                         → reject with instructions to use exit_plan_mode
  *   allow rule match             → auto-approve
  *   bash in session allowlist    → auto-approve
@@ -46,7 +48,8 @@ export class PermissionAwareApprovalController {
         if (mode === "bypassPermissions") {
             return finalize({ action: "approve" });
         }
-        if (mode === "default" && (req.type === "edit" || req.type === "write" || req.type === "patch")) {
+        const outsideWorkspace = (req.type === "edit" || req.type === "write") && req.outsideWorkspace === true;
+        if (mode === "default" && !outsideWorkspace && (req.type === "edit" || req.type === "write" || req.type === "patch")) {
             return finalize({ action: "approve" });
         }
         // Project profile trust is a user decision, not a destructive action:

package/dist/approval/tool-helper.js

@@ -16,7 +16,16 @@ export async function gateToolAction(approval, req) {
     const message = feedback
         ? `${label} was rejected by the user. User feedback: ${feedback}`
         : `${label} was rejected by the user.`;
-    return { approved: false, result: { content: message, isError: true } };
+    return {
+        approved: false,
+        result: {
+            content: message,
+            isError: true,
+            // Surfaces the rejection reason in subagent tool notes (which prefer
+            // metadata.reason over the truncated first content line).
+            metadata: { kind: "security", reason: feedback || message },
+        },
+    };
 }
 function approvalRequestLabel(req) {
     switch (req.type) {

package/dist/approval/types.d.ts

@@ -12,6 +12,12 @@ export interface EditApprovalRequest {
     /** Unified patch (with context lines) to show the user. */
     diff: string;
     fileExists: boolean;
+    /**
+     * The path resolves outside the session workspace. Escalates the request
+     * past default-mode auto-approval so the user explicitly confirms it
+     * (bypassPermissions still auto-approves, consistent with bash).
+     */
+    outsideWorkspace?: boolean;
 }
 export interface WriteApprovalRequest {
     type: "write";
@@ -21,6 +27,8 @@ export interface WriteApprovalRequest {
     /** Unified patch from existing contents to pending contents. */
     diff?: string;
     fileExists: boolean;
+    /** See EditApprovalRequest.outsideWorkspace. */
+    outsideWorkspace?: boolean;
 }
 export interface PatchApprovalRequest {
     type: "patch";
@@ -39,6 +47,13 @@ export interface BashApprovalRequest {
     type: "bash";
     command: string;
     cwd: string;
+    /**
+     * The command will run as a background task that outlives the turn
+     * (background-tasks design §2.4). Shown in the approval dialog and passed
+     * to permission hooks so org policy can discriminate; allow rules, the
+     * session allowlist, and bypass approve it like foreground by design.
+     */
+    background?: boolean;
 }
 export interface LspApprovalRequest {
     type: "lsp";

package/dist/config.d.ts

@@ -35,6 +35,10 @@ export interface UserConfigData {
     /** Subagent model-routing knobs: autoTier (default true), allowCrossProvider (default true). */
     agentRouting?: Partial<AgentRoutingConfig>;
     subagents?: SubagentsUserConfig;
+    /** Background tasks (design §2.3b): autoResume defaults ON; false keeps notices + reminders only. */
+    tasks?: {
+        autoResume?: boolean;
+    };
 }
 export interface SubagentsUserConfig {
     /** Global cap on concurrently running children. Default 8. */
@@ -50,6 +54,8 @@ export declare class UserConfig {
     getDefaultThinkingLevel(): ThinkingLevel | undefined;
     setDefaultThinkingLevel(level: ThinkingLevel): void;
     getRecentModels(): string[];
+    /** Auto-resume on background-task completion (design §2.3b). Default ON. */
+    getTasksAutoResume(): boolean;
     pushRecentModel(model: string): void;
     getApiKey(): string | undefined;
     setApiKey(key: string): void;

package/dist/config.js

@@ -139,6 +139,10 @@ export class UserConfig {
     getRecentModels() {
         return sanitizeRecentModels(this.data.recentModels)?.slice() ?? [];
     }
+    /** Auto-resume on background-task completion (design §2.3b). Default ON. */
+    getTasksAutoResume() {
+        return this.data.tasks?.autoResume !== false;
+    }
     pushRecentModel(model) {
         if (isHiddenProviderId(modelProviderId(model))) {
             return;

package/dist/loop/engine.d.ts

@@ -0,0 +1,29 @@
+/**
+ * /loop — recurring prompts (background-tasks design §2.6).
+ *
+ * Pure decision logic kept out of the TUI, mirroring goal/engine.ts: the TUI
+ * owns a 1s ticker and calls decideLoopFiring per loop; this module owns
+ * parsing, caps, and the defer-not-stack rule (a firing due while a turn is
+ * running reschedules with a notice instead of piling up).
+ */
+export interface LoopState {
+    id: number;
+    prompt: string;
+    intervalMs: number;
+    nextFireAt: number;
+    fires: number;
+}
+export declare const MAX_ACTIVE_LOOPS = 5;
+export declare const MIN_LOOP_INTERVAL_MS = 60000;
+export interface ParsedLoopCommand {
+    action: "start" | "list" | "stop" | "help";
+    intervalMs?: number;
+    prompt?: string;
+    stopId?: number;
+    error?: string;
+}
+export declare function parseLoopCommand(raw: string): ParsedLoopCommand;
+export type LoopFiringDecision = "fire" | "defer" | "wait";
+export declare function decideLoopFiring(loop: LoopState, now: number, turnRunning: boolean): LoopFiringDecision;
+export declare function formatLoopList(loops: LoopState[], now: number): string;
+export declare function formatInterval(intervalMs: number): string;

package/dist/loop/engine.js

@@ -0,0 +1,63 @@
+/**
+ * /loop — recurring prompts (background-tasks design §2.6).
+ *
+ * Pure decision logic kept out of the TUI, mirroring goal/engine.ts: the TUI
+ * owns a 1s ticker and calls decideLoopFiring per loop; this module owns
+ * parsing, caps, and the defer-not-stack rule (a firing due while a turn is
+ * running reschedules with a notice instead of piling up).
+ */
+export const MAX_ACTIVE_LOOPS = 5;
+export const MIN_LOOP_INTERVAL_MS = 60_000;
+export function parseLoopCommand(raw) {
+    const rest = raw.trim().replace(/^\/loop\s*/, "").trim();
+    if (!rest)
+        return { action: "help" };
+    if (rest === "list")
+        return { action: "list" };
+    const stop = rest.match(/^stop(?:\s+(\d+))?$/);
+    if (stop) {
+        return { action: "stop", stopId: stop[1] ? Number(stop[1]) : undefined };
+    }
+    const match = rest.match(/^(\d+)([smh])\s+(.+)$/s);
+    if (!match) {
+        return {
+            action: "start",
+            error: "Usage: /loop <interval> <prompt> — interval like 90s, 5m, 1h (min 60s). Also: /loop list, /loop stop [id].",
+        };
+    }
+    const value = Number(match[1]);
+    const unit = match[2];
+    const multiplier = unit === "s" ? 1000 : unit === "m" ? 60_000 : 3_600_000;
+    const intervalMs = Math.max(MIN_LOOP_INTERVAL_MS, value * multiplier);
+    const prompt = match[3].trim();
+    if (!prompt) {
+        return { action: "start", error: "Usage: /loop <interval> <prompt> — the prompt is required." };
+    }
+    return { action: "start", intervalMs, prompt };
+}
+export function decideLoopFiring(loop, now, turnRunning) {
+    if (now < loop.nextFireAt)
+        return "wait";
+    return turnRunning ? "defer" : "fire";
+}
+export function formatLoopList(loops, now) {
+    if (loops.length === 0)
+        return "No active loops. Start one with /loop <interval> <prompt>.";
+    return loops
+        .map((loop) => {
+        const nextIn = Math.max(0, Math.round((loop.nextFireAt - now) / 1000));
+        return `#${loop.id} every ${formatInterval(loop.intervalMs)} · fired ${loop.fires}x · next in ${nextIn}s · ${truncate(loop.prompt, 60)}`;
+    })
+        .join("\n");
+}
+export function formatInterval(intervalMs) {
+    if (intervalMs % 3_600_000 === 0)
+        return `${intervalMs / 3_600_000}h`;
+    if (intervalMs % 60_000 === 0)
+        return `${intervalMs / 60_000}m`;
+    return `${Math.round(intervalMs / 1000)}s`;
+}
+function truncate(value, max) {
+    const oneLine = value.replace(/\s+/g, " ").trim();
+    return oneLine.length <= max ? oneLine : `${oneLine.slice(0, max - 1)}…`;
+}

package/dist/main.js

@@ -18,6 +18,8 @@ import { createRoutableModelIndex, createRoutingSnapshotAccessor } from "./agent
 import { buildModelRoutingPrompt } from "./prompt/routing.js";
 import { SkillRegistry } from "./skills/registry.js";
 import { buildToolPromptOptions, createAllTools } from "./tools/index.js";
+import { getProcessManager } from "./tasks/manager.js";
+import { PromotionChannel } from "./tasks/promotion.js";
 import { FileStateTracker } from "./tools/file-state.js";
 import { GoalStore } from "./goal/store.js";
 import { PermissionAwareApprovalController } from "./approval/controller.js";
@@ -165,6 +167,13 @@ async function main() {
     // Shared between the goal tool (model-facing update_goal) and the
     // TUI's auto-continuation engine / status-line indicator.
     const goalStore = new GoalStore();
+    // Background tasks are TUI-only (design §2.0): print mode exits (and reaps)
+    // right after the single run, so a backgrounded command would be killed
+    // immediately after the model was told it started. Feishu/desktop hosts
+    // never reach this call site and stay off until they wire wake seams.
+    const processManager = getProcessManager();
+    const allowBackgroundTasks = !printMode;
+    const promotionChannel = new PromotionChannel();
     const tools = createAllTools(args.cwd, skillRegistry, {
         todoStore,
         planController,
@@ -174,6 +183,9 @@ async function main() {
         lspService,
         fileStateTracker,
         goalStore,
+        processManager,
+        allowBackgroundTasks,
+        promotionChannel,
         // Lazy: sessionManager is resolved after tools are created.
         checkpoints: () => sessionManager?.getCheckpoints(),
     });
@@ -222,6 +234,9 @@ async function main() {
         }
     };
     const shutdownSidecars = async () => {
+        // Signal path (design §2.2b layer 2): kill-only, no escalation wait —
+        // the process is about to exit and shutdownRuntime never runs here.
+        processManager.reapTasksSync();
         await Promise.allSettled([shutdownMcp(), shutdownExternalRuntime()]);
     };
     process.once("SIGINT", () => { void shutdownSidecars().then(() => process.exit(130)); });
@@ -433,6 +448,15 @@ async function main() {
         externalHooks: hookController,
     });
     agentRef = agent;
+    if (allowBackgroundTasks) {
+        // Reminder bridge (design §2.3a): list() is owner-filtered at call time so
+        // the reminder never leaks another session's tasks after a switch.
+        agent.backgroundTasks = {
+            list: () => processManager.listTasks(agent.getSessionID()),
+            version: () => processManager.getTaskStateVersion(),
+            outputTail: (id) => processManager.taskOutputTail(id, 2000),
+        };
+    }
     if (sessionManager) {
         sessionTitleUpdater = createSessionTitleUpdater({
             sessionManager,
@@ -486,6 +510,8 @@ async function main() {
             shutdownMcp(),
             shutdownExternalRuntime(),
             lspService.shutdown(),
+            // Graceful task reaping (design §2.2b layer 1): SIGTERM → SIGKILL.
+            processManager.shutdownTasks(),
         ]);
         for (const result of results) {
             if (result.status === "rejected") {
@@ -653,6 +679,9 @@ async function main() {
             runMemoryCompaction,
             runMemorySummary,
             runMemoryRefresh,
+            processManager,
+            tasksAutoResume: userConfig.getTasksAutoResume(),
+            promotionChannel,
         };
         // Grok Subscription is a first-class interactive provider target. Manager
         // construction is deliberately lazy: it does not inspect, spawn, or reach

package/dist/orchestrator/default-hooks.js

@@ -53,6 +53,14 @@ export function createDefaultHooks() {
                     ctx.state.workflowPhase = "investigate";
                     ctx.state.workflowKey = "";
                 }
+                // Background-task truth at turn start: completions that landed while
+                // the agent was idle (or during another session's turn) reach the
+                // model here; the same state-change gate prevents duplicates with the
+                // beforeContinuation emission (background-tasks design §2.3a).
+                const backgroundTaskReminder = ctx.agent.consumeBackgroundTaskReminder?.();
+                if (backgroundTaskReminder) {
+                    ctx.queueReminder(backgroundTaskReminder);
+                }
                 for (const reminder of ctx.state.governor.consumePendingReminders()) {
                     ctx.queueReminder(reminder);
                 }
@@ -167,6 +175,14 @@ export function createDefaultHooks() {
                         ctx.queueReminder(reminder);
                     }
                 }
+                // Background-task truth: state-change gated inside the agent (a task
+                // started/finished/killed since the last emission), so a mid-turn
+                // completion reaches the model without stacking per-call duplicates
+                // (background-tasks design §2.3a).
+                const taskReminder = ctx.agent.consumeBackgroundTaskReminder?.();
+                if (taskReminder) {
+                    ctx.queueReminder(taskReminder);
+                }
                 // Routing detector note (model-routing design §6): rides the same
                 // channel as the lifecycle reminder, once per session. Consuming also
                 // closes the per-fan-out counting window.

package/dist/session-types.d.ts

@@ -31,7 +31,7 @@ export interface SessionMetadata {
      */
     externalRuntime?: ExternalRuntimeSessionMetadata;
 }
-export type SessionMarkerKind = "model_switch" | "provider_switch" | "thinking_level_switch" | "skill_activated" | "mode_switch" | "runtime_switch" | "conversation_clear";
+export type SessionMarkerKind = "model_switch" | "provider_switch" | "thinking_level_switch" | "skill_activated" | "mode_switch" | "runtime_switch" | "conversation_clear" | "task_started" | "task_finished" | "task_killed";
 interface BaseSessionLogEntry {
     id: string;
     timestamp: number;

package/dist/tasks/manager.d.ts

@@ -0,0 +1,136 @@
+/**
+ * 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 { type ChildProcess } from "node:child_process";
+export type ManagedServerPurpose = "preview" | "verification";
+export type ManagedServerLifecycle = "auto" | "keep_alive";
+export type ManagedServerStatus = "starting" | "ready" | "running" | "exited" | "failed" | "stopped";
+export interface ManagedServerInfo {
+    id: string;
+    command: string;
+    cwd: string;
+    port?: number;
+    url?: string;
+    ownerSessionId?: string;
+    ownerRunId?: string;
+    purpose: ManagedServerPurpose;
+    lifecycle: ManagedServerLifecycle;
+    startedAt: number;
+    lastUsedAt: number;
+    status: ManagedServerStatus;
+    pid?: number;
+    exitCode?: number | null;
+}
+export interface StartManagedServerInput {
+    command: string;
+    cwd: string;
+    port?: number;
+    readinessUrl?: string;
+    timeoutSec?: number;
+    ownerSessionId?: string;
+    ownerRunId?: string;
+    purpose?: ManagedServerPurpose;
+    lifecycle?: ManagedServerLifecycle;
+}
+export type BackgroundTaskStatus = "running" | "completed" | "failed" | "killed";
+export interface BackgroundTaskInfo {
+    kind: "task";
+    id: string;
+    command: string;
+    description?: string;
+    cwd: string;
+    pid?: number;
+    status: BackgroundTaskStatus;
+    exitCode?: number | null;
+    startedAt: number;
+    endedAt?: number;
+    outputTruncated: boolean;
+    /** Wake fired or model read the task via task_output (design §2.3a). */
+    deliveredAt?: number;
+    ownerSessionId?: string;
+}
+export interface StartBackgroundTaskInput {
+    command: string;
+    description?: string;
+    cwd: string;
+    ownerSessionId?: string;
+}
+export interface AdoptBackgroundTaskInput extends StartBackgroundTaskInput {
+    /** Already-running child handed over by Ctrl+G promotion (design §2.5). */
+    child: ChildProcess;
+    /** Output accumulated before promotion, seeds the ring buffer. */
+    outputSoFar?: string;
+    startedAt?: number;
+}
+export type TaskEventListener = (task: BackgroundTaskInfo) => void;
+export declare class ProcessManager {
+    private readonly registry;
+    private nextServerId;
+    private nextTaskId;
+    /** Bumped on task start/finish/kill — the reminder's state-change gate (design §2.3a). */
+    private taskStateVersion;
+    private readonly changeListeners;
+    private readonly finishListeners;
+    getTaskStateVersion(): number;
+    startTask(input: StartBackgroundTaskInput): BackgroundTaskInfo;
+    /** Ctrl+G promotion: adopt a child the bash tool already spawned (§2.5). */
+    adoptTask(input: AdoptBackgroundTaskInput): BackgroundTaskInfo;
+    private reserveTaskSlot;
+    private registerTaskChild;
+    private finalizeTask;
+    getTask(id: string): BackgroundTaskInfo | undefined;
+    listTasks(ownerSessionId?: string): BackgroundTaskInfo[];
+    taskOutputTail(id: string, maxChars?: number): string | undefined;
+    markTaskDelivered(id: string): void;
+    waitTasks(ids: string[], options?: {
+        timeoutMs?: number;
+        mode?: "any" | "all";
+    }): Promise<BackgroundTaskInfo[]>;
+    killTask(id: string): Promise<BackgroundTaskInfo | undefined>;
+    /** Graceful reaping for shutdownRuntime (design §2.2b layer 1). */
+    shutdownTasks(): Promise<void>;
+    /** SIGKILL-only reaping for synchronous signal/exit paths (§2.2b layers 2-3). */
+    reapTasksSync(): void;
+    onTaskFinished(listener: TaskEventListener): () => void;
+    onChange(listener: TaskEventListener): () => void;
+    private bumpTaskState;
+    private evictFinishedTasks;
+    private taskRecords;
+    private publicTask;
+    startManagedServer(input: StartManagedServerInput): Promise<ManagedServerInfo>;
+    listManagedServers(): ManagedServerInfo[];
+    getManagedServer(id: string): ManagedServerInfo | undefined;
+    getManagedServerLogs(id: string, maxChars?: number): string | undefined;
+    stopManagedServer(id: string): Promise<ManagedServerInfo | undefined>;
+    stopAutoServersForSession(sessionID?: string): Promise<void>;
+    /** process.once("exit") backstop (§2.2b layer 3). */
+    reapOnExit(): void;
+    private serverRecords;
+}
+export declare function getProcessManager(): ProcessManager;
+export declare const startManagedServer: (input: StartManagedServerInput) => Promise<ManagedServerInfo>;
+export declare const listManagedServers: () => ManagedServerInfo[];
+export declare const getManagedServer: (id: string) => ManagedServerInfo | undefined;
+export declare const getManagedServerLogs: (id: string, maxChars?: number) => string | undefined;
+export declare const stopManagedServer: (id: string) => Promise<ManagedServerInfo | undefined>;
+export declare const stopAutoServersForSession: (sessionID?: string) => Promise<void>;