pi-async-bash 0.1.0

package/src/output.ts

@@ -0,0 +1,132 @@
+// src/output.ts
+import { closeSync, fstatSync, openSync, readSync, statSync } from "node:fs";
+import { FOREGROUND_TAIL_BYTES } from "./types.ts";
+
+/**
+ * Read the tail of a log file, bounded by maxChars. Only the last maxChars
+ * bytes are read (O(maxChars), not O(fileSize)). Opens once and fstats the
+ * descriptor — no separate path-stat, so no stat-then-read race.
+ */
+export function readBoundedTail(logPath: string, maxChars: number): string {
+    let fd: number;
+    try {
+        fd = openSync(logPath, "r");
+    } catch {
+        return "(no output yet)";
+    }
+    try {
+        const { size } = fstatSync(fd);
+        if (size === 0) return "(no output yet)";
+        const toRead = Math.min(size, maxChars);
+        const buf = Buffer.alloc(toRead);
+        readSync(fd, buf, 0, toRead, Math.max(0, size - toRead));
+        const body = buf.toString("utf-8");
+        return size > maxChars
+            ? `...[truncated, showing last ${maxChars} chars]\n${body}`
+            : body;
+    } catch {
+        return "(no output yet)";
+    } finally {
+        closeSync(fd);
+    }
+}
+
+// Terminal escape/control sequences stripped from a progress line so the
+// sidebar shows clean text and crafted job output cannot inject escapes. The
+// leading \u001b (ESC) is essential — without it these would eat literal
+// `[...]`/`]...` like JSON.
+const ANSI_CSI = /\u001b\[[0-9;?]*[ -/]*[@-~]/g;
+const ANSI_OSC = /\u001b\][\s\S]*?(?:\u0007|\u001b\\)/g;
+// Remaining C0/C1 control chars and DEL (newlines handled by the split).
+const CONTROL_CHARS = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g;
+
+/**
+ * The last non-empty line of a log's tail, ANSI-stripped — used to show live
+ * progress in the sidebar. Reads only the trailing bytes (cheap per tick), and
+ * collapses `\r` progress-bar redraws to their final segment. Returns "" when
+ * there's no output yet.
+ */
+export function readLastLine(logPath: string, scanBytes = 2_048): string {
+    const tail = readBoundedTail(logPath, scanBytes);
+    if (tail === "(no output yet)") return "";
+    const lines = tail.replace(ANSI_CSI, "").replace(ANSI_OSC, "").split(/[\r\n]+/);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i].replace(CONTROL_CHARS, "").replace(/\t/g, " ").trim();
+        if (line.length > 0) return line;
+    }
+    return "";
+}
+
+/**
+ * Poll a log file tail at `intervalMs` (default 1000ms). Calls `onUpdate`
+ * only when content changes. Returns a handle with `stop()`.
+ *
+ * This is the Claude Code pattern: the file is written to by the child
+ * process via file descriptor. We poll the tail for progress display.
+ */
+export function pollFileTail(
+    logPath: string,
+    onUpdate: (text: string) => void,
+    intervalMs = 1_000
+): { stop: () => void } {
+    let lastSize = 0;
+    let lastContent = "";
+    let stopped = false;
+
+    const timer = setTimeout(function tick() {
+        if (stopped) return;
+        try {
+            const { size } = statSync(logPath);
+            if (size === lastSize) {
+                timer.refresh();
+                return;
+            }
+            lastSize = size;
+            const fd = openSync(logPath, "r");
+            try {
+                const readStart = Math.max(0, size - FOREGROUND_TAIL_BYTES);
+                const toRead = Math.min(size, FOREGROUND_TAIL_BYTES);
+                const buf = Buffer.alloc(toRead);
+                readSync(fd, buf, 0, toRead, readStart);
+                const content = buf.toString("utf-8", 0, toRead);
+                if (content && content !== lastContent) {
+                    lastContent = content;
+                    onUpdate(content);
+                }
+            } finally {
+                closeSync(fd);
+            }
+        } catch {
+            // File not yet created or locked — retry next tick.
+        }
+        if (!stopped) timer.refresh();
+    }, intervalMs);
+    (timer as NodeJS.Timeout).unref();
+
+    return {
+        stop() {
+            stopped = true;
+            clearTimeout(timer);
+        },
+    };
+}
+
+/** A tool's streaming-update callback (text-only partial results). */
+export type ToolTextUpdate = (update: {
+    content: { type: "text"; text: string }[];
+    details: undefined;
+}) => void;
+
+/**
+ * Stream a log file's live tail into a tool's onUpdate callback — the shared
+ * "show live output while a job runs" mechanic shared by `bash` and
+ * `bash_async_list attach`. Returns the poller's stop handle.
+ */
+export function streamLog(
+    logPath: string,
+    onUpdate: ToolTextUpdate | undefined
+): { stop: () => void } {
+    return pollFileTail(logPath, (text) => {
+        onUpdate?.({ content: [{ type: "text", text }], details: undefined });
+    });
+}

package/src/registry.ts

@@ -0,0 +1,343 @@
+/**
+ * The job registry — the single point of truth for every running or
+ * recently-terminal background job. All CRUD operations live here.
+ *
+ * On top of the data store, this module renders the in-session sidebar
+ * pill bar (`renderSidebar`) and aggregates stats (`getStats`).
+ */
+
+import { randomInt } from "node:crypto";
+import { statSync, unlinkSync } from "node:fs";
+import { formatDuration, jobLabel } from "./format.ts";
+import {
+    isTerminalStatus,
+    JOB_ID_PREFIX,
+    MAX_CONCURRENT_JOBS,
+    PREVIEW_CHARS,
+    RECENT_TERMINAL_KEEP,
+    type Job,
+    type JobKind,
+    type UiContext,
+} from "./types.ts";
+import type { BackgroundRegistry } from "./state.ts";
+import { readBoundedTail, readLastLine } from "./output.ts";
+
+// --- ID generation -------------------------------------------------------
+
+const ID_ALPHABET = "0123456789abcdefghijklmnopqrstuvwxyz";
+
+/**
+ * Typed task ids: a one-letter kind prefix, spawning process identifier, and
+ * eight random base36 characters (for example, `b1234-7f3k9a2x`).
+ */
+export function newJobId(kind: JobKind, reg?: BackgroundRegistry): string {
+    let id: string;
+    do {
+        let suffix = "";
+        for (let i = 0; i < 8; i++) {
+            suffix += ID_ALPHABET[randomInt(0, ID_ALPHABET.length)];
+        }
+        id = `${JOB_ID_PREFIX[kind]}${process.pid}-${suffix}`;
+    } while (reg?.jobs.has(id));
+    return id;
+}
+
+/** Dedicated log directory. Keeping logs in their own dir (not loose in /tmp)
+ *  keeps the stale-log sweep bounded — it lists only our files. */
+export const LOG_DIR = "/tmp/pi-bg";
+
+export function logPathFor(jobId: string): string {
+    return `${LOG_DIR}/${jobId}.log`;
+}
+
+/** Sibling stderr-capture path for a monitor's split output. Keeps the
+ *  `.log`/`.err` naming convention in one place. */
+export function errPathFor(jobId: string): string {
+    return `${LOG_DIR}/${jobId}.err`;
+}
+
+/**
+ * Build a fresh running Job. Centralizes the Job shape so the new `kind`/`stop`
+ * fields (and any future additions) don't drift across the bash/bash_async/
+ * bash_async_watch construction sites.
+ */
+export function createRunningJob(args: {
+    id: string;
+    command: string;
+    pid: number;
+    logPath: string;
+    toolCallId: string;
+    name?: string;
+    kind?: JobKind;
+    isBackgrounded?: boolean;
+}): Job {
+    return {
+        id: args.id,
+        name: args.name,
+        command: args.command,
+        pid: args.pid,
+        startTime: Date.now(),
+        status: "running",
+        logPath: args.logPath,
+        toolCallId: args.toolCallId,
+        isBackgrounded: args.isBackgrounded ?? true,
+        kind: args.kind,
+    };
+}
+
+// --- Registry mutations --------------------------------------------------
+
+/** Record that a job has started (lifetime counter). */
+export function markStarted(reg: BackgroundRegistry): void {
+    reg.totalStarted++;
+}
+
+/** Add a brand-new running job and count it as started. */
+export function add(reg: BackgroundRegistry, job: Job): Job {
+    reg.jobs.set(job.id, job);
+    markStarted(reg);
+    return job;
+}
+
+/** True once the running-job count has reached the concurrency cap. Counts with
+ *  a short-circuit so it stops at the cap instead of scanning the whole map. */
+export function atConcurrencyLimit(reg: BackgroundRegistry): boolean {
+    let n = 0;
+    for (const job of reg.jobs.values()) {
+        if (job.status === "running" && ++n >= MAX_CONCURRENT_JOBS) return true;
+    }
+    return false;
+}
+
+/**
+ * Remove a terminal job from the live map and update lifetime counters.
+ * Returns the removed job (or undefined if it wasn't in the map).
+ */
+export function forget(reg: BackgroundRegistry, job: Job): Job | undefined {
+    if (!reg.jobs.delete(job.id)) return undefined;
+    if (job.status === "completed") {
+        reg.completedCount++;
+        reg.totalDurationMs += terminalDurationMs(job);
+    } else if (job.status === "failed") {
+        reg.failedCount++;
+        reg.totalDurationMs += terminalDurationMs(job);
+    } else if (job.status === "killed") {
+        reg.killedCount++;
+    }
+    reg.recentTerminal.push(job);
+    if (reg.recentTerminal.length > RECENT_TERMINAL_KEEP) {
+        reg.recentTerminal.shift();
+    }
+    return job;
+}
+
+/** Look up a job by ID — first the live registry, then the recent-terminal ring
+ *  for jobs that already finished and were evicted. */
+export function findJob(reg: BackgroundRegistry, jobId: string): Job | undefined {
+    return (
+        reg.jobs.get(jobId) ??
+        reg.recentTerminal.find((j) => j.id === jobId)
+    );
+}
+
+/** Purge all terminal jobs from in-memory state and delete their log files. */
+export function cleanupTerminal(reg: BackgroundRegistry): {
+    purged: number;
+    bytesReclaimed: number;
+} {
+    let purged = 0;
+    let bytes = 0;
+    const deletedLogs = new Set<string>();
+    const deleteOnce = (logPath: string): number => {
+        if (deletedLogs.has(logPath)) return 0;
+        deletedLogs.add(logPath);
+        return deleteLogFile(logPath);
+    };
+
+    const idsToRemove: string[] = [];
+    for (const [id, job] of reg.jobs.entries()) {
+        if (isTerminalStatus(job.status)) {
+            idsToRemove.push(id);
+            bytes += deleteOnce(job.logPath);
+            purged++;
+        }
+    }
+    for (const id of idsToRemove) {
+        reg.jobs.delete(id);
+    }
+    // The recent-terminal ring is all terminal jobs too — sweep their logs.
+    for (const job of reg.recentTerminal) {
+        bytes += deleteOnce(job.logPath);
+        purged++;
+    }
+    reg.recentTerminal.length = 0;
+    return { purged, bytesReclaimed: bytes };
+}
+
+function deleteLogFile(logPath: string): number {
+    try {
+        const { size } = statSync(logPath);
+        unlinkSync(logPath);
+        return size;
+    } catch {
+        return 0;
+    }
+}
+
+// ─── Sidebar rendering ───────────────────────────────────────────────────
+
+/**
+ * Render the pill-bar status widget and aggregate status-bar text, and keep a
+ * 1 Hz ticker running while any job is alive so the durations stay live (the
+ * widget isn't redrawn on a timer otherwise). Re-renders only when the content
+ * actually changes. Call after any state change that affects running jobs.
+ */
+export function renderSidebar(reg: BackgroundRegistry, ctx: UiContext): void {
+    const pills: string[] = [];
+    let runningCount = 0;
+    const runningLogs = new Set<string>();
+
+    for (const job of reg.jobs.values()) {
+        // Terminal jobs render no pill: their outcome is always surfaced by a
+        // <task-notification>, a kill, or a read — there is no unread state.
+        if (isTerminalStatus(job.status)) continue;
+        runningCount++;
+        runningLogs.add(job.logPath);
+        const duration = formatDuration(Date.now() - job.startTime);
+        const glyph = job.kind === "monitor" ? "◉" : "▶";
+        // Show the job's latest output line as live progress; fall back to the
+        // command until there's any output. Re-read each tick by the ticker.
+        const progress = sidebarLastLine(job.logPath) || job.command;
+        pills.push(
+            `${glyph} ${jobLabel(job)}: ${progress.slice(0, PREVIEW_CHARS.progress)} (${duration})`
+        );
+    }
+
+    // Drop progress-cache entries for logs no longer tracked.
+    for (const key of sidebarLineCache.keys()) {
+        if (!runningLogs.has(key)) sidebarLineCache.delete(key);
+    }
+
+    if (pills.length === 0) {
+        stopSidebarTicker(reg);
+        if (reg.lastSidebarContent !== undefined) {
+            reg.lastSidebarContent = undefined;
+            ctx.ui.setWidget("background-jobs", undefined);
+            ctx.ui.setStatus("background-jobs", undefined);
+        }
+        return;
+    }
+
+    const parts = [`${runningCount} running`];
+    if (reg.completedCount > 0) parts.push(`${reg.completedCount} done`);
+    if (reg.failedCount > 0) parts.push(`${reg.failedCount} failed`);
+    const statusText = `▶ ${parts.join(", ")}`;
+    const key = `${pills.join("\n")}|${statusText}`;
+
+    if (key !== reg.lastSidebarContent) {
+        reg.lastSidebarContent = key;
+        ctx.ui.setWidget("background-jobs", pills);
+        ctx.ui.setStatus("background-jobs", ctx.ui.theme.fg("accent", statusText));
+    }
+
+    // The 1 Hz ticker exists to keep running-job durations live; with no
+    // running jobs there is nothing to tick.
+    if (runningCount > 0) ensureSidebarTicker(reg, ctx);
+    else stopSidebarTicker(reg);
+}
+
+/** Per-log cache for the sidebar's live progress line: the 1 Hz ticker would
+ *  otherwise re-read every running job's tail every tick even when output is
+ *  static. statSync first; skip the read when the size is unchanged. */
+const sidebarLineCache = new Map<string, { size: number; lastLine: string }>();
+
+function sidebarLastLine(logPath: string): string {
+    let size: number;
+    try {
+        size = statSync(logPath).size;
+    } catch {
+        sidebarLineCache.delete(logPath);
+        return "";
+    }
+    const cached = sidebarLineCache.get(logPath);
+    if (cached && cached.size === size) return cached.lastLine;
+    const lastLine = readLastLine(logPath);
+    sidebarLineCache.set(logPath, { size, lastLine });
+    return lastLine;
+}
+
+/** Start the live-duration ticker if not already running. */
+function ensureSidebarTicker(reg: BackgroundRegistry, ctx: UiContext): void {
+    if (reg.sidebarTimer) return;
+    const t = setInterval(() => {
+        try {
+            renderSidebar(reg, ctx);
+        } catch {
+            // The captured ctx went stale (session reload/fork/switch) — stop
+            // ticking rather than throw an uncaught exception in the interval.
+            stopSidebarTicker(reg);
+        }
+    }, 1000);
+    t.unref();
+    reg.sidebarTimer = t;
+}
+
+/** Stop the live-duration ticker (no running jobs, or on shutdown). */
+export function stopSidebarTicker(reg: BackgroundRegistry): void {
+    if (reg.sidebarTimer) {
+        clearInterval(reg.sidebarTimer);
+        reg.sidebarTimer = undefined;
+    }
+}
+
+// ─── Stats ───────────────────────────────────────────────────────────────
+
+export interface JobStats {
+    totalStarted: number;
+    running: number;
+    completed: number;
+    failed: number;
+    killed: number;
+    recentTerminal: number;
+    averageDurationMs: number;
+    totalDurationMs: number;
+}
+
+export function getStats(reg: BackgroundRegistry): JobStats {
+    let running = 0;
+    for (const job of reg.jobs.values()) {
+        if (job.status === "running") running++;
+    }
+    const terminalCount = reg.completedCount + reg.failedCount;
+    return {
+        totalStarted: reg.totalStarted,
+        running,
+        completed: reg.completedCount,
+        failed: reg.failedCount,
+        killed: reg.killedCount,
+        recentTerminal: reg.recentTerminal.length,
+        averageDurationMs:
+            terminalCount > 0
+                ? Math.round(reg.totalDurationMs / terminalCount)
+                : 0,
+        totalDurationMs: reg.totalDurationMs,
+    };
+}
+
+// ─── Internal helpers ──────────────────────────────────────────────────
+
+function terminalDurationMs(job: Job): number {
+    return Date.now() - job.startTime;
+}
+
+// ─── Status helpers (used by tools and shortcuts) ───────────────────────────────────────────
+
+/** True when the job is currently in the running state. */
+export function isRunning(job: Job): boolean {
+    return job.status === "running";
+}
+
+/** Read only the tail of a job's log file — O(maxChars) even for large files. */
+export function readLogTail(job: Job, maxChars: number): string {
+    return readBoundedTail(job.logPath, maxChars);
+}

package/src/render.ts

@@ -0,0 +1,56 @@
+import { Text, type Component } from "@earendil-works/pi-tui";
+
+type CallArgs = Record<string, unknown>;
+
+type RenderTheme = {
+    fg(color: "muted" | "toolTitle", text: string): string;
+    bold(text: string): string;
+};
+
+type RenderContext = {
+    lastComponent?: Component;
+};
+
+export function renderBashAsyncCall(
+    args: unknown,
+    theme: RenderTheme,
+    context: RenderContext,
+): Text {
+    const values = asCallArgs(args);
+    const command = nonEmptyString(values.command);
+    const commandDisplay = command === undefined
+        ? styledTitle("$ ", theme) + theme.fg("muted", "...")
+        : styledTitle(`$ ${command}`, theme);
+    const timeoutSuffix = renderTimeout(values.timeout, theme);
+
+    return renderCall(commandDisplay + timeoutSuffix, context);
+}
+
+function renderCall(content: string, context: RenderContext): Text {
+    const previousComponent = context.lastComponent;
+    const text = previousComponent instanceof Text
+        ? previousComponent
+        : new Text("", 0, 0);
+    text.setText(content);
+    return text;
+}
+
+function renderTimeout(value: unknown, theme: RenderTheme): string {
+    return typeof value === "number" && Number.isFinite(value) && value > 0
+        ? theme.fg("muted", ` (timeout ${value}s)`)
+        : "";
+}
+
+function styledTitle(title: string, theme: RenderTheme): string {
+    return theme.fg("toolTitle", theme.bold(title));
+}
+
+function nonEmptyString(value: unknown): string | undefined {
+    return typeof value === "string" && value.trim().length > 0
+        ? value
+        : undefined;
+}
+
+function asCallArgs(args: unknown): CallArgs {
+    return typeof args === "object" && args !== null ? args as CallArgs : {};
+}

package/src/spawn.ts

@@ -0,0 +1,141 @@
+// src/spawn.ts
+import { spawn } from "node:child_process";
+import { closeSync, mkdirSync, openSync, unlinkSync } from "node:fs";
+import { dirname } from "node:path";
+
+/** How the child ended: an exit code, or the signal that killed it. Node
+ *  reports `code === null` when the child died by signal (external kill, OOM),
+ *  so the signal half is what tells a crash apart from a clean exit. */
+export interface SpawnExit {
+    code: number | null;
+    signal: NodeJS.Signals | null;
+}
+
+export interface SpawnResult {
+    pid: number;
+    logPath: string;
+    exit: Promise<SpawnExit>;
+}
+
+/**
+ * Spawn a child with stdout+stderr written directly to a file descriptor — the
+ * Claude Code pattern: the kernel writes output to disk with zero JS in the
+ * data path. Progress is read back by polling the file tail separately.
+ *
+ * Pass `command` to run `bash -c <command>`, or `file` and `fileArgs` to run a
+ * binary directly. The child is detached so the whole process group can be
+ * signalled.
+ */
+export function spawnWithFileOutput(args: {
+    command?: string;
+    file?: string;
+    fileArgs?: string[];
+    cwd: string;
+    logPath: string;
+    /** When set, stderr is written here instead of merged into logPath. Used by
+     *  the bash_async_watch tool so stdout is a clean event stream and stderr is captured
+     *  separately (readable, but never emitted as an event). */
+    errPath?: string;
+    signal?: AbortSignal;
+}): SpawnResult {
+    ensureLogDir(args.logPath);
+    const outFd = openSync(args.logPath, "w");
+    let errFd: number;
+    try {
+        errFd = args.errPath ? openSync(args.errPath, "w") : outFd;
+    } catch (err) {
+        closeSync(outFd);
+        throw err;
+    }
+
+    const [bin, binArgs]: [string, string[]] = args.file
+        ? [args.file, args.fileArgs ?? []]
+        : ["bash", ["-c", args.command ?? ""]];
+
+    let proc;
+    try {
+        proc = spawn(bin, binArgs, {
+            stdio: ["ignore", outFd, errFd],
+            cwd: args.cwd,
+            detached: true,
+            env: { ...process.env },
+        });
+    } finally {
+        closeSync(outFd);
+        if (errFd !== outFd) closeSync(errFd);
+    }
+
+    // Build the exit promise and attach the 'error' listener BEFORE any throw,
+    // so an asynchronous spawn failure (ENOENT / EMFILE / EAGAIN) can never
+    // surface as an uncaught exception that takes pi down.
+    const exit = new Promise<SpawnExit>((resolve) => {
+        // Use 'exit' not 'close': 'close' waits for stdio to close, which
+        // includes grandchild processes that inherit file descriptors (e.g.
+        // `sleep 30 &`). 'exit' fires when the shell itself exits, returning
+        // control immediately. Output still flushes fine — the kernel writes
+        // directly to the file fd, no JS drain needed.
+        proc.on("exit", (code, signal) => resolve({ code, signal }));
+        proc.on("error", () => resolve({ code: 1, signal: null }));
+    });
+
+    if (!proc.pid) {
+        try { unlinkSync(args.logPath); } catch { /* best-effort */ }
+        if (args.errPath) {
+            try { unlinkSync(args.errPath); } catch { /* best-effort */ }
+        }
+        throw new Error("Failed to spawn process");
+    }
+    const pid = proc.pid;
+
+    // Kill the process group on abort. Most callers manage abort themselves and
+    // do not pass a signal; this is offered for direct/background spawns.
+    const onAbort = () => killProcessTree(pid);
+    if (args.signal) {
+        if (args.signal.aborted) onAbort();
+        else args.signal.addEventListener("abort", onAbort, { once: true });
+    }
+    void exit.finally(() => args.signal?.removeEventListener("abort", onAbort));
+
+    proc.unref();
+
+    return { pid, logPath: args.logPath, exit };
+}
+
+/** The log dir is a constant (registry.LOG_DIR), so create it once per process
+ *  instead of paying a recursive mkdir on every spawn. */
+let logDirCreated = false;
+function ensureLogDir(logPath: string): void {
+    if (logDirCreated) return;
+    mkdirSync(dirname(logPath), { recursive: true });
+    logDirCreated = true;
+}
+
+/**
+ * Kill an entire process group via negative PID signal.
+ * Falls back to direct PID kill if group kill fails.
+ */export function killProcessTree(
+    pid: number | undefined,
+    signal: NodeJS.Signals = "SIGTERM"
+): void {
+    if (typeof pid !== "number" || pid <= 0) return;
+    try {
+        process.kill(-pid, signal);
+    } catch {
+        try {
+            process.kill(pid, signal);
+        } catch {
+            /* already dead */
+        }
+    }
+}
+
+/** Cheap liveness probe via signal 0. */
+export function processExists(pid: number | undefined): boolean {
+    if (typeof pid !== "number" || pid <= 0) return false;
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch (err) {
+        return (err as NodeJS.ErrnoException).code === "EPERM";
+    }
+}

package/src/state.ts

@@ -0,0 +1,30 @@
+/**
+ * Shared mutable state for the background-tasks extension.
+ *
+ * One instance per session, threaded through every tool and helper.
+ */
+
+import type { Job, ForegroundSlot } from "./types.ts";
+
+export class BackgroundRegistry {
+    jobs = new Map<string, Job>();
+    foreground = new Map<string, ForegroundSlot>();
+    pendingDecisionJobId: string | undefined;
+
+    /** Per-job AbortController — abort() cancels all monitors/pollers for that job. */
+    jobAborts = new Map<string, AbortController>();
+
+    nonInteractive = false;
+
+    completedCount = 0;
+    failedCount = 0;
+    killedCount = 0;
+    totalStarted = 0;
+    totalDurationMs = 0;
+    recentTerminal: Job[] = [];
+
+    /** Live-duration ticker for the sidebar pills; runs while jobs are alive. */
+    sidebarTimer: NodeJS.Timeout | undefined = undefined;
+    /** Last rendered sidebar content — used to skip redundant widget updates. */
+    lastSidebarContent: string | undefined = undefined;
+}