@capybara-hq/kernel 0.1.0-rc.3 → 0.1.0-rc.4

package/dist/background/launch.js

@@ -0,0 +1,70 @@
+import { randomBytes } from "node:crypto";
+/**
+ * Launching a background Bash task (spec 2026-11-05-background-bash-design §4.2): the task id, the
+ * one short exec that starts the command detached from the exec, and the model-visible result.
+ * Every path is relative to `/workspace` (the launch exec's `cwd`), so a provider that maps
+ * `/workspace` needs no rewriting inside the script.
+ */
+/** The launch exec's own time limit: it only writes a file and forks. */
+export const LAUNCH_EXEC_TIMEOUT_MS = 30_000;
+/**
+ * The longest a background task may run, in seconds: `sandbox.background.maxSeconds`, at most
+ * `sandbox.limits.maxCommandSeconds`. It is also a task's default `timeout`.
+ */
+export const backgroundMaxSeconds = (cfg) => Math.min(cfg.sandbox.background.maxSeconds, cfg.sandbox.limits.maxCommandSeconds);
+/** The directory of the task files, relative to `/workspace`. */
+export const TASKS_DIR = ".capybara/tasks";
+/** A task's output file, relative to `/workspace` (`output_path`). */
+export const taskOutputPath = (id) => `${TASKS_DIR}/${id}.out`;
+/** The file the launch writes the session id to, relative to `/workspace`. */
+export const taskSidPath = (id) => `${TASKS_DIR}/${id}.sid`;
+const BASE32 = "abcdefghijklmnopqrstuvwxyz234567";
+/** A new task id: `bt_` plus 6 lowercase base32 characters. */
+export function newTaskId() {
+    const bytes = randomBytes(6);
+    let out = "bt_";
+    for (const b of bytes)
+        out += BASE32[b & 31];
+    return out;
+}
+/** The programs the launch and the later polls and stops need inside the sandbox. */
+const REQUIRED = ["bash", "setsid", "nohup", "timeout", "pgrep", "pkill", "base64"];
+/** A task id ({@link newTaskId}). */
+export const TASK_ID_RE = /^bt_[a-z2-7]{6}$/;
+/**
+ * The shell of the launch exec: writes `command` (base64 in the script, so nothing is quoted by
+ * hand) to `.capybara/tasks/<id>.sh` and starts it with bash (the shell a foreground `Bash` call
+ * runs its command in) in a session of its own under `timeout -s KILL <seconds>`, with its exit
+ * status written to `<id>.exit` and its output to `<id>.out`; writes the session id (`$!`, the pid
+ * `setsid` started) to `<id>.sid` and prints it. A sandbox without one of the needed programs fails with a readable error on
+ * stderr and exit code 127, before anything starts. `id` must be a task id and `seconds` a
+ * positive integer (both go into the script unquoted).
+ */
+export function launchScript(id, command, seconds) {
+    if (!TASK_ID_RE.test(id))
+        throw new Error(`invalid background task id: ${JSON.stringify(id)}`);
+    if (!Number.isSafeInteger(seconds) || seconds < 1) {
+        throw new Error(`invalid background task seconds: ${seconds}`);
+    }
+    const b64 = Buffer.from(command, "utf8").toString("base64");
+    const t = `${TASKS_DIR}/${id}`;
+    return [
+        "set -e",
+        `for c in ${REQUIRED.join(" ")}; do command -v "$c" >/dev/null 2>&1 || { echo "Background tasks need ${REQUIRED.join(", ")} in the sandbox; $c is missing." >&2; exit 127; }; done`,
+        `mkdir -p ${TASKS_DIR}`,
+        `printf '%s' '${b64}' | base64 -d > ${t}.sh`,
+        `setsid nohup sh -c 'timeout -s KILL ${seconds} bash ${t}.sh; echo $? > ${t}.exit' > ${t}.out 2>&1 < /dev/null &`,
+        // the session id goes to a file first: a launch that ends before its output comes back
+        // (aborted, timed out) still leaves the id of what it started
+        `echo $! > ${t}.sid`,
+        `cat ${t}.sid`,
+    ].join("\n");
+}
+/** The model-visible result of a launch (spec §2.1). */
+export function startedText(id, description) {
+    return [
+        `Started background task ${id} ("${description}").`,
+        `Output: /workspace/${taskOutputPath(id)}`,
+        "Read it with TaskOutput (or Read), stop it with TaskStop. You will be told when it finishes.",
+    ].join("\n");
+}

package/dist/background/poll.job.d.ts

@@ -0,0 +1,53 @@
+import type { KernelConfig } from "../config/schema.js";
+import { EventLog } from "../conversations/event-log.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import type { KernelLogger } from "../log.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { BackgroundTaskFinisher } from "./finish.js";
+import { BackgroundTaskStore } from "./store.js";
+/** The poll of the running background tasks (`@LockedInterval`, every `pollSeconds`). */
+export declare const BACKGROUND_POLL_JOB = "background-task-poll";
+/** The daily prune of finished background tasks older than `tools.outputRetentionDays`. */
+export declare const BACKGROUND_PRUNE_JOB = "background-task-prune";
+/**
+ * A reservation (`sid` null) older than this has lost its launch. The slowest legitimate launch
+ * is the pipeline's own limit for a background `Bash` call ({@link LAUNCH_EXEC_TIMEOUT_MS} plus
+ * {@link sandboxBaseTimeoutMs}: the tool timeout, `sandbox.lockWaitSeconds` and the setup margin),
+ * so twice that (never under 2 minutes) leaves a wide margin: only a launching process that died
+ * leaves a reservation this old.
+ */
+export declare const launchAbandonedAfterMs: (cfg: KernelConfig) => number;
+/**
+ * The worker's background task jobs (spec 2026-11-05-background-bash-design §4.3), each once per
+ * tick across replicas:
+ * - `background-task-poll` (every `sandbox.background.pollSeconds`): for every sandbox with
+ *   running tasks, one exec through `SandboxService.ifRunning` (which never creates or resumes a
+ *   sandbox) reports each task's exit file and liveness; ended tasks finish through
+ *   {@link BackgroundTaskFinisher}. Each poll takes and releases a lease, so `last_used_at` stays
+ *   fresh and a sandbox with running tasks is never idle-suspended;
+ * - `background-task-prune` (daily): deletes finished tasks older than `tools.outputRetentionDays`.
+ */
+export declare class BackgroundTaskPollJob {
+    private readonly store;
+    private readonly finisher;
+    private readonly eventLog;
+    private readonly sandbox;
+    readonly config: KernelConfigService;
+    readonly lockService: LockService;
+    readonly log: KernelLogger;
+    constructor(store: Pick<BackgroundTaskStore, "runningStarted" | "pruneFinished" | "failAbandonedLaunches">, finisher: BackgroundTaskFinisher, eventLog: Pick<EventLog, "publishChanged">, sandbox: Pick<SandboxService, "available" | "ifRunning">, config: KernelConfigService, lockService: LockService, log: KernelLogger);
+    poll(signal?: AbortSignal): Promise<void>;
+    /**
+     * One poll of every running task (the body of {@link poll}); returns how many tasks finished.
+     * A sandbox whose poll fails (busy, a provider error) is logged and tried again next tick.
+     * First, reservations abandoned by a launch that died ({@link launchAbandonedAfterMs}) are
+     * failed, so they stop holding a slot of `sandbox.background.maxTasks` (not counted in the
+     * result: they never started), with a `changed: "background"` frame to their conversations.
+     */
+    pollOnce(signal?: AbortSignal): Promise<number>;
+    /** Polls the tasks of one sandbox instance; returns how many finished. */
+    private pollSandbox;
+    /** Deletes the finished tasks older than `tools.outputRetentionDays` (their rows only). */
+    prune(): Promise<void>;
+}

package/dist/background/poll.job.js

@@ -0,0 +1,182 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __param = (this && this.__param) || function (paramIndex, decorator) {
+    return function (target, key) { decorator(target, key, paramIndex); }
+};
+import { Inject, Injectable } from "@nestjs/common";
+import { EventLog } from "../conversations/event-log.js";
+import { KernelConfigService } from "../infra/config/kernel-config.service.js";
+import { LockService } from "../infra/lock/lock.service.js";
+import { LockedCron } from "../infra/schedule/locked-cron.decorator.js";
+import { LockedInterval } from "../infra/schedule/locked-interval.js";
+import { KERNEL_LOGGER } from "../infra/tokens.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { sandboxBaseTimeoutMs } from "../tools/builtins/sandbox/common.js";
+import { BackgroundTaskFinisher } from "./finish.js";
+import { LAUNCH_EXEC_TIMEOUT_MS } from "./launch.js";
+import { parsePollOutput, polledAs, pollScript } from "./status.js";
+import { notRunningAs, RECREATED } from "./stop.js";
+import { BackgroundTaskStore } from "./store.js";
+/** The poll of the running background tasks (`@LockedInterval`, every `pollSeconds`). */
+export const BACKGROUND_POLL_JOB = "background-task-poll";
+/** The daily prune of finished background tasks older than `tools.outputRetentionDays`. */
+export const BACKGROUND_PRUNE_JOB = "background-task-prune";
+/** The least age at which a reservation counts as abandoned, whatever the config. */
+const LAUNCH_ABANDONED_FLOOR_MS = 120_000;
+/**
+ * A reservation (`sid` null) older than this has lost its launch. The slowest legitimate launch
+ * is the pipeline's own limit for a background `Bash` call ({@link LAUNCH_EXEC_TIMEOUT_MS} plus
+ * {@link sandboxBaseTimeoutMs}: the tool timeout, `sandbox.lockWaitSeconds` and the setup margin),
+ * so twice that (never under 2 minutes) leaves a wide margin: only a launching process that died
+ * leaves a reservation this old.
+ */
+export const launchAbandonedAfterMs = (cfg) => Math.max(LAUNCH_ABANDONED_FLOOR_MS, 2 * (LAUNCH_EXEC_TIMEOUT_MS + sandboxBaseTimeoutMs(cfg)));
+/** The time limit of one sandbox's poll exec. */
+const POLL_EXEC_TIMEOUT_MS = 30_000;
+/** The most output one poll exec keeps (a line per task, with a tail when it ended). */
+const POLL_MAX_OUTPUT_BYTES = 4 * 1024 * 1024;
+/**
+ * The worker's background task jobs (spec 2026-11-05-background-bash-design §4.3), each once per
+ * tick across replicas:
+ * - `background-task-poll` (every `sandbox.background.pollSeconds`): for every sandbox with
+ *   running tasks, one exec through `SandboxService.ifRunning` (which never creates or resumes a
+ *   sandbox) reports each task's exit file and liveness; ended tasks finish through
+ *   {@link BackgroundTaskFinisher}. Each poll takes and releases a lease, so `last_used_at` stays
+ *   fresh and a sandbox with running tasks is never idle-suspended;
+ * - `background-task-prune` (daily): deletes finished tasks older than `tools.outputRetentionDays`.
+ */
+let BackgroundTaskPollJob = class BackgroundTaskPollJob {
+    store;
+    finisher;
+    eventLog;
+    sandbox;
+    config;
+    lockService;
+    log;
+    constructor(store, finisher, eventLog, sandbox, config, lockService, log) {
+        this.store = store;
+        this.finisher = finisher;
+        this.eventLog = eventLog;
+        this.sandbox = sandbox;
+        this.config = config;
+        this.lockService = lockService;
+        this.log = log;
+    }
+    async poll(signal) {
+        await this.pollOnce(signal);
+    }
+    /**
+     * One poll of every running task (the body of {@link poll}); returns how many tasks finished.
+     * A sandbox whose poll fails (busy, a provider error) is logged and tried again next tick.
+     * First, reservations abandoned by a launch that died ({@link launchAbandonedAfterMs}) are
+     * failed, so they stop holding a slot of `sandbox.background.maxTasks` (not counted in the
+     * result: they never started), with a `changed: "background"` frame to their conversations.
+     */
+    async pollOnce(signal = new AbortController().signal) {
+        const abandoned = await this.store.failAbandonedLaunches(new Date(Date.now() - launchAbandonedAfterMs(this.config.get())));
+        if (abandoned.length > 0) {
+            this.log.warn("abandoned background launches failed", { count: abandoned.length });
+            // a client that listed the reservation as running refreshes (the owner and, for a
+            // sub-agent's task, the conversation that owns the sandbox); a failed publish only logs
+            const conversations = new Set(abandoned.flatMap((t) => [t.conversationId, t.sandboxConversationId]));
+            for (const c of conversations)
+                await this.eventLog.publishChanged(c, "background");
+        }
+        if (!this.sandbox.available)
+            return 0;
+        const groups = new Map();
+        for (const t of await this.store.runningStarted()) {
+            if (t.sid === null || t.sandboxCreatedAt === null)
+                continue;
+            const key = `${t.sandboxConversationId} ${t.sandboxCreatedAt.getTime()}`;
+            groups.set(key, [...(groups.get(key) ?? []), t]);
+        }
+        let finished = 0;
+        for (const tasks of groups.values()) {
+            if (signal.aborted)
+                break;
+            try {
+                finished += await this.pollSandbox(tasks, signal);
+            }
+            catch (err) {
+                if (signal.aborted)
+                    break;
+                this.log.warn("cannot poll background tasks; retrying next tick", {
+                    conversationId: tasks[0]?.sandboxConversationId,
+                    err,
+                });
+            }
+        }
+        if (finished > 0)
+            this.log.info("background tasks finished", { count: finished });
+        return finished;
+    }
+    /** Polls the tasks of one sandbox instance; returns how many finished. */
+    async pollSandbox(tasks, signal) {
+        const [first] = tasks;
+        const r = await this.sandbox.ifRunning(first.sandboxConversationId, { createdAt: first.sandboxCreatedAt }, async (p, h, sig) => {
+            const res = await p.exec(h, {
+                command: pollScript(tasks.map((t) => ({ id: t.id, sid: t.sid }))),
+                cwd: "/workspace",
+                timeoutMs: POLL_EXEC_TIMEOUT_MS,
+                maxOutputBytes: POLL_MAX_OUTPUT_BYTES,
+                signal: sig,
+            });
+            if (res.exitCode !== 0 || res.truncated) {
+                throw new Error(`the poll exec failed (exit ${res.exitCode}${res.truncated ? ", truncated" : ""}): ${res.stderr.slice(0, 500)}`);
+            }
+            return parsePollOutput(res.stdout);
+        }, signal);
+        const now = new Date();
+        let n = 0;
+        for (const t of tasks) {
+            let to;
+            let lastLines = "";
+            if (r.kind === "ran") {
+                const report = r.value.get(t.id);
+                // a task the exec did not report is checked again next tick
+                to = report ? polledAs(t, report, now) : null;
+                lastLines = report?.lastLines ?? "";
+            }
+            else if (r.kind === "not_running") {
+                // a suspended sandbox may keep the processes (E2B's pause): killed after its next resume
+                to = notRunningAs(r.status, r.status === "suspended");
+            }
+            else {
+                to = RECREATED;
+            }
+            // a stop that claimed the task after the read above finishes it itself
+            if (to && (await this.finisher.finish(t, to, lastLines, false, { unclaimed: true })))
+                n++;
+        }
+        return n;
+    }
+    /** Deletes the finished tasks older than `tools.outputRetentionDays` (their rows only). */
+    async prune() {
+        const days = this.config.get().tools.outputRetentionDays;
+        const n = await this.store.pruneFinished(new Date(Date.now() - days * 86_400_000));
+        if (n > 0)
+            this.log.info("finished background tasks pruned", { count: n });
+    }
+};
+__decorate([
+    LockedInterval(BACKGROUND_POLL_JOB, (cfg) => cfg.sandbox.background.pollSeconds * 1000)
+], BackgroundTaskPollJob.prototype, "poll", null);
+__decorate([
+    LockedCron("30 3 * * *", { name: BACKGROUND_PRUNE_JOB })
+], BackgroundTaskPollJob.prototype, "prune", null);
+BackgroundTaskPollJob = __decorate([
+    Injectable(),
+    __param(0, Inject(BackgroundTaskStore)),
+    __param(1, Inject(BackgroundTaskFinisher)),
+    __param(2, Inject(EventLog)),
+    __param(3, Inject(SandboxService)),
+    __param(4, Inject(KernelConfigService)),
+    __param(5, Inject(LockService)),
+    __param(6, Inject(KERNEL_LOGGER))
+], BackgroundTaskPollJob);
+export { BackgroundTaskPollJob };

package/dist/background/render.d.ts

@@ -0,0 +1,23 @@
+import type { EventPayload } from "../conversations/events.js";
+/** `42s`, `2m05s`, `1h02m05s`. */
+export declare function formatElapsed(ms: number): string;
+/** Why a task was lost, as the model reads it (an unknown reason as is). */
+export declare const lostReasonText: (reason: string) => string;
+type Finished = EventPayload<"background_task_finished">;
+/**
+ * The model-visible text of a `background_task_finished` event, rendered as a system message (spec
+ * 2026-11-05-background-bash-design §2.4):
+ *
+ * ```
+ * Background task bt_k3f9a2 ("Run the test suite") completed with exit code 1 after 4m12s.
+ * Last lines:
+ * …
+ * Full output: /workspace/.capybara/tasks/bt_k3f9a2.out
+ * ```
+ *
+ * Without an exit code the first line has no "with exit code"; without output the last lines are
+ * `Last lines: (none)`. A finish a tool call already reported (`reported`) is one short line.
+ * Read only from the payload, so a replay renders it identically.
+ */
+export declare function renderBackgroundFinished(p: Finished): string;
+export {};

package/dist/background/render.js

@@ -0,0 +1,48 @@
+/** `42s`, `2m05s`, `1h02m05s`. */
+export function formatElapsed(ms) {
+    const s = Math.max(0, Math.floor(ms / 1000));
+    const pad = (n) => String(n).padStart(2, "0");
+    if (s < 60)
+        return `${s}s`;
+    if (s < 3600)
+        return `${Math.floor(s / 60)}m${pad(s % 60)}s`;
+    return `${Math.floor(s / 3600)}h${pad(Math.floor((s % 3600) / 60))}m${pad(s % 60)}s`;
+}
+const LOST_REASONS = {
+    sandbox_suspended: "the sandbox was suspended",
+    sandbox_gone: "the sandbox is gone",
+    sandbox_recreated: "the sandbox was recreated",
+    process_gone: "its processes ended without an exit code",
+    launch_abandoned: "its launch was interrupted",
+};
+/** Why a task was lost, as the model reads it (an unknown reason as is). */
+export const lostReasonText = (reason) => LOST_REASONS[reason] ?? reason;
+const statusWord = (status) => status === "timed_out" ? "timed out" : status;
+/**
+ * The model-visible text of a `background_task_finished` event, rendered as a system message (spec
+ * 2026-11-05-background-bash-design §2.4):
+ *
+ * ```
+ * Background task bt_k3f9a2 ("Run the test suite") completed with exit code 1 after 4m12s.
+ * Last lines:
+ * …
+ * Full output: /workspace/.capybara/tasks/bt_k3f9a2.out
+ * ```
+ *
+ * Without an exit code the first line has no "with exit code"; without output the last lines are
+ * `Last lines: (none)`. A finish a tool call already reported (`reported`) is one short line.
+ * Read only from the payload, so a replay renders it identically.
+ */
+export function renderBackgroundFinished(p) {
+    const head = `Background task ${p.taskId} (${JSON.stringify(p.description)}) ${statusWord(p.status)}`;
+    if (p.reported)
+        return `${head}; already reported.`;
+    const lost = p.lostReason === undefined ? "" : ` (${lostReasonText(p.lostReason)})`;
+    const exit = p.exitCode === null ? "" : ` with exit code ${p.exitCode}`;
+    const lines = p.lastLines.replace(/\n+$/, "");
+    return [
+        `${head}${lost}${exit} after ${formatElapsed(p.elapsedMs)}.`,
+        lines === "" ? "Last lines: (none)" : `Last lines:\n${lines}`,
+        `Full output: ${p.outputPath}`,
+    ].join("\n");
+}

package/dist/background/session.d.ts

@@ -0,0 +1,37 @@
+import type { SandboxHandle, SandboxProvider } from "@capybara-hq/plugin-sdk";
+/**
+ * A background task's session inside the sandbox (spec 2026-11-05-background-bash-design §4.2):
+ * every process of a task is in the session `setsid` started, so liveness is `pgrep -s <sid>` and
+ * stopping is `pkill -s <sid>` (never `kill -0` or `/proc`, which disagree between sandbox-fake and
+ * Linux).
+ */
+/** A session id (the pid `setsid` started). */
+export declare const SID_RE: RegExp;
+/** The time limit of one kill of a session ({@link killSession}). */
+export declare const KILL_SESSION_TIMEOUT_MS = 10000;
+/** Throws unless `id` is a task id and `sid` a session id (both go into scripts unquoted). */
+export declare function assertTaskRef(id: string, sid: string): void;
+/**
+ * A shell fragment that kills every process of the session `sid` with SIGKILL, repeated until the
+ * session is empty (pkill exits 1: no process left): a process may fork between pkill's listing
+ * and its signals, and the child would live on. Sets `ks` to 0 when the session was confirmed
+ * empty, else to pkill's failing status (3 when it was still not empty after 10 tries). Uses only
+ * the variables `ks`, `kc` and `ki`. `sid` must be a session id.
+ */
+export declare function killSessionScript(sid: string): string;
+/**
+ * Kills every process of the session `sid` ({@link killSessionScript}) in an exec of its own. Any
+ * pkill status other than 0 and 1 is a failure. Runs with a fresh signal of its own (a command
+ * must be killed even when the caller was just aborted). True when the session was confirmed
+ * empty; false when it could not be (an error is never thrown).
+ */
+export declare function killSession(p: SandboxProvider, h: SandboxHandle, sid: string): Promise<boolean>;
+/** The longest `lastLines` of a finished task (spec §2.4). */
+export declare const LAST_LINES_MAX_CHARS = 4000;
+/**
+ * A shell pipeline printing the last 20 lines of task `id`'s output (at most {@link TAIL_BYTES}),
+ * base64 on one line (empty when there is no output file). Relative to `/workspace`.
+ */
+export declare function tailCommand(id: string): string;
+/** Decodes a {@link tailCommand} result into `lastLines`: its end, at most 4 000 characters. */
+export declare function decodeTail(b64: string): string;

package/dist/background/session.js

@@ -0,0 +1,66 @@
+import { TASK_ID_RE, TASKS_DIR } from "./launch.js";
+/**
+ * A background task's session inside the sandbox (spec 2026-11-05-background-bash-design §4.2):
+ * every process of a task is in the session `setsid` started, so liveness is `pgrep -s <sid>` and
+ * stopping is `pkill -s <sid>` (never `kill -0` or `/proc`, which disagree between sandbox-fake and
+ * Linux).
+ */
+/** A session id (the pid `setsid` started). */
+export const SID_RE = /^[1-9][0-9]*$/;
+/** The time limit of one kill of a session ({@link killSession}). */
+export const KILL_SESSION_TIMEOUT_MS = 10_000;
+/** Throws unless `id` is a task id and `sid` a session id (both go into scripts unquoted). */
+export function assertTaskRef(id, sid) {
+    if (!TASK_ID_RE.test(id))
+        throw new Error(`invalid background task id: ${JSON.stringify(id)}`);
+    if (!SID_RE.test(sid))
+        throw new Error(`invalid background task session: ${JSON.stringify(sid)}`);
+}
+/**
+ * A shell fragment that kills every process of the session `sid` with SIGKILL, repeated until the
+ * session is empty (pkill exits 1: no process left): a process may fork between pkill's listing
+ * and its signals, and the child would live on. Sets `ks` to 0 when the session was confirmed
+ * empty, else to pkill's failing status (3 when it was still not empty after 10 tries). Uses only
+ * the variables `ks`, `kc` and `ki`. `sid` must be a session id.
+ */
+export function killSessionScript(sid) {
+    if (!SID_RE.test(sid))
+        throw new Error(`invalid background task session: ${JSON.stringify(sid)}`);
+    return `ks=3; for ki in 1 2 3 4 5 6 7 8 9 10; do pkill -KILL -s ${sid}; kc=$?; if [ "$kc" -eq 1 ]; then ks=0; break; fi; if [ "$kc" -ne 0 ]; then ks=$kc; break; fi; sleep 0.2; done`;
+}
+/**
+ * Kills every process of the session `sid` ({@link killSessionScript}) in an exec of its own. Any
+ * pkill status other than 0 and 1 is a failure. Runs with a fresh signal of its own (a command
+ * must be killed even when the caller was just aborted). True when the session was confirmed
+ * empty; false when it could not be (an error is never thrown).
+ */
+export async function killSession(p, h, sid) {
+    if (!SID_RE.test(sid))
+        return false;
+    const r = await p
+        .exec(h, {
+        command: `${killSessionScript(sid)}; exit "$ks"`,
+        cwd: "/workspace",
+        timeoutMs: KILL_SESSION_TIMEOUT_MS,
+        maxOutputBytes: 4096,
+        signal: AbortSignal.timeout(KILL_SESSION_TIMEOUT_MS),
+    })
+        .catch(() => undefined);
+    return r?.exitCode === 0;
+}
+/** The most bytes of a task's output end a tail reads (the event keeps at most 4 000 characters). */
+const TAIL_BYTES = 12_000;
+/** The longest `lastLines` of a finished task (spec §2.4). */
+export const LAST_LINES_MAX_CHARS = 4000;
+/**
+ * A shell pipeline printing the last 20 lines of task `id`'s output (at most {@link TAIL_BYTES}),
+ * base64 on one line (empty when there is no output file). Relative to `/workspace`.
+ */
+export function tailCommand(id) {
+    return `{ tail -n 20 ${TASKS_DIR}/${id}.out 2>/dev/null | tail -c ${TAIL_BYTES} | base64 | tr -d '\\n'; }`;
+}
+/** Decodes a {@link tailCommand} result into `lastLines`: its end, at most 4 000 characters. */
+export function decodeTail(b64) {
+    const text = Buffer.from(b64.trim(), "base64").toString("utf8");
+    return text.length > LAST_LINES_MAX_CHARS ? text.slice(-LAST_LINES_MAX_CHARS) : text;
+}

package/dist/background/status.d.ts

@@ -0,0 +1,35 @@
+import type { BackgroundFinish } from "./finish.js";
+import type { BackgroundTaskRow } from "./store.js";
+/** What the poll exec reports for one task. */
+export interface TaskReport {
+    /** The exit file's code; null while there is none. */
+    exitCode: number | null;
+    /**
+     * Whether the session still has a process: `pgrep -s <sid>`, or, for a task whose command
+     * exited, whether its leftover processes could not be confirmed killed.
+     */
+    alive: boolean;
+    /** The last lines (decoded), read when the task exited or no process was left. */
+    lastLines: string;
+}
+/**
+ * The poll exec of one sandbox: for every task one line `<id> <exit code or -> <1|0> <tail or ->`.
+ * Liveness is asked before the exit file: a task ending in between is seen by its exit file, never
+ * as a task without process and exit file. A task whose command exited while its session still has
+ * processes (it left `server &` running) has the session killed in the same exec (so under the
+ * caller's lease), and is reported without a process once the session was confirmed empty: the
+ * task ends when its command exits, and nothing of it runs on untracked. The tail (base64) is read
+ * only for a task that exited or has no process left. Relative to `/workspace`.
+ */
+export declare function pollScript(tasks: {
+    id: string;
+    sid: string;
+}[]): string;
+/** Parses {@link pollScript}'s output; a task missing from it is absent from the map. */
+export declare function parsePollOutput(stdout: string): Map<string, TaskReport>;
+/**
+ * How a polled task ends, or null while it runs (spec §4.3). A task whose command exited but whose
+ * leftover processes could not be confirmed killed ({@link pollScript}) stays running: the next
+ * poll kills them again before it finishes.
+ */
+export declare function polledAs(task: BackgroundTaskRow, r: TaskReport, now: Date): BackgroundFinish | null;

package/dist/background/status.js

@@ -0,0 +1,57 @@
+import { TASK_ID_RE, TASKS_DIR } from "./launch.js";
+import { decodeTail, killSessionScript, SID_RE, tailCommand } from "./session.js";
+import { exitedAs } from "./stop.js";
+/**
+ * The poll exec of one sandbox: for every task one line `<id> <exit code or -> <1|0> <tail or ->`.
+ * Liveness is asked before the exit file: a task ending in between is seen by its exit file, never
+ * as a task without process and exit file. A task whose command exited while its session still has
+ * processes (it left `server &` running) has the session killed in the same exec (so under the
+ * caller's lease), and is reported without a process once the session was confirmed empty: the
+ * task ends when its command exits, and nothing of it runs on untracked. The tail (base64) is read
+ * only for a task that exited or has no process left. Relative to `/workspace`.
+ */
+export function pollScript(tasks) {
+    const lines = tasks.map(({ id, sid }) => {
+        if (!TASK_ID_RE.test(id) || !SID_RE.test(sid)) {
+            throw new Error(`invalid background task ${JSON.stringify(id)} / ${JSON.stringify(sid)}`);
+        }
+        const f = `${TASKS_DIR}/${id}`;
+        return [
+            `if pgrep -s ${sid} >/dev/null 2>&1; then a=1; else a=0; fi`,
+            `if [ -s ${f}.exit ]; then c=$(tr -dc '0-9-' < ${f}.exit); else c=-; fi`,
+            `[ -n "$c" ] || c=-`,
+            `if [ "$c" != - ] && [ "$a" = 1 ]; then ${killSessionScript(sid)}; [ "$ks" = 0 ] && a=0; fi`,
+            `if [ "$c" != - ] || [ "$a" = 0 ]; then t=$(${tailCommand(id)}); else t=; fi`,
+            `echo "${id} $c $a \${t:--}"`,
+        ].join("\n");
+    });
+    return lines.join("\n");
+}
+/** Parses {@link pollScript}'s output; a task missing from it is absent from the map. */
+export function parsePollOutput(stdout) {
+    const out = new Map();
+    for (const line of stdout.split("\n")) {
+        const m = /^(bt_[a-z2-7]{6}) (-?[0-9]+|-) ([01]) (\S+)$/.exec(line.trim());
+        if (!m)
+            continue;
+        const [, id, code, alive, tail] = m;
+        out.set(id, {
+            exitCode: code === "-" ? null : Number(code),
+            alive: alive === "1",
+            lastLines: tail === "-" ? "" : decodeTail(tail),
+        });
+    }
+    return out;
+}
+/**
+ * How a polled task ends, or null while it runs (spec §4.3). A task whose command exited but whose
+ * leftover processes could not be confirmed killed ({@link pollScript}) stays running: the next
+ * poll kills them again before it finishes.
+ */
+export function polledAs(task, r, now) {
+    if (r.exitCode !== null)
+        return r.alive ? null : exitedAs(task, r.exitCode, now);
+    if (r.alive)
+        return null;
+    return { status: "lost", lostReason: "process_gone", killPending: false };
+}

package/dist/background/stop.d.ts

@@ -0,0 +1,62 @@
+import { KernelDb } from "../infra/database/kernel-db.js";
+import type { KernelLogger } from "../log.js";
+import { SandboxService } from "../sandbox/sandbox.service.js";
+import { type BackgroundFinish, BackgroundTaskFinisher } from "./finish.js";
+import { type BackgroundTaskRow, BackgroundTaskStore } from "./store.js";
+/** Why a task is stopped. */
+export type StopReason = "tool" | "person" | "subagent_end" | "conversation_deleted";
+/** How long a stop waits after SIGTERM before SIGKILL (spec §2.3). */
+export declare const STOP_GRACE_MS = 5000;
+/** How a task that exited by itself ends (spec §4.3): exit 137 past its deadline timed out. */
+export declare function exitedAs(task: BackgroundTaskRow, code: number, now: Date): BackgroundFinish;
+/** How a task whose sandbox is not running ends (`ifRunning`'s `not_running` status). */
+export declare function notRunningAs(status: string, killPending: boolean): BackgroundFinish;
+/** A task found in another sandbox instance (a rebuild): its processes are gone with the old one. */
+export declare const RECREATED: BackgroundFinish;
+/**
+ * Stops background tasks (spec 2026-11-05-background-bash-design §2.3, §4.3): SIGTERM to the
+ * task's session, up to 5 s for it to empty, then SIGKILL until it is empty, all through
+ * `SandboxService.ifRunning` (it never creates or resumes a sandbox); the task then finishes as
+ * `stopped` with its last 20 lines. A task that had already exited finishes as its exit says. When
+ * the sandbox is not running the task finishes as `lost` with `kill_pending` (killed right after a
+ * resume); in a rebuilt sandbox as `lost` (`sandbox_recreated`). Processes a task that had
+ * already exited left running are killed as well.
+ */
+export declare class BackgroundTaskStopper {
+    private readonly store;
+    private readonly finisher;
+    private readonly sandbox;
+    private readonly db;
+    private readonly log;
+    constructor(store: Pick<BackgroundTaskStore, "get" | "runningOwnedBy" | "runningIn" | "claimStop" | "releaseStop">, finisher: BackgroundTaskFinisher, sandbox: Pick<SandboxService, "ifRunning">, db: KernelDb, log: Pick<KernelLogger, "warn">);
+    /**
+     * Stops `task` and returns its row afterwards. A task that is no longer running, or that another
+     * live stop already claimed, is returned as it is now.
+     *
+     * The stop first claims the task (`stopping_at`), so the poller leaves it alone while the
+     * signals take effect and the stop's finish is its only one. A reservation whose launch has not
+     * started the command yet (no `sid`) is only claimed: the launch then kills what it starts and
+     * finishes the row `stopped`. When the stop fails while the sandbox runs (busy, a provider
+     * error, a session that could not be confirmed empty), the claim is given up, the task stays
+     * `running` and the error is thrown.
+     */
+    stop(task: BackgroundTaskRow, why: StopReason, signal?: AbortSignal): Promise<BackgroundTaskRow>;
+    /**
+     * After the sub-agent run `runId` ended (spec §4.3): stops the running tasks that run started in
+     * `conversationId` when it is a sub-agent's conversation (nobody can read or stop them through
+     * that run's model after that); any other conversation is left alone. Only that run's tasks: a
+     * follow-up run of the same child keeps its own when an older run's end is handled late. Never
+     * throws (see {@link stopAll}).
+     */
+    stopSubagentTasks(conversationId: string, runId: string): Promise<void>;
+    /**
+     * Before a conversation is deleted: stops every running task in its sandbox (its own and its
+     * sub-agents'). Never throws (see {@link stopAll}).
+     */
+    stopForDeletedConversation(conversationId: string): Promise<void>;
+    /**
+     * Stops `tasks` side by side. A stop that fails while the sandbox runs leaves its task running
+     * (logged): the poller still checks it and it ends at its own deadline at the latest.
+     */
+    private stopAll;
+}