@capybara-hq/kernel 0.1.0-rc.0 → 0.1.0-rc.10

package/dist/background/launch.d.ts

@@ -0,0 +1,42 @@
+import type { KernelConfig } from "../config/schema.js";
+/**
+ * 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 the instance's workspace root (the launch exec's `cwd`), so the
+ * script is the same whatever the instance's roots are.
+ */
+/** The launch exec's own time limit: it only writes a file and forks. */
+export declare const LAUNCH_EXEC_TIMEOUT_MS = 30000;
+/**
+ * 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 declare const backgroundMaxSeconds: (cfg: Pick<KernelConfig, "sandbox">) => number;
+/** The directory of the task files, relative to the workspace root. */
+export declare const TASKS_DIR = ".capybara/tasks";
+/** A task's output file, relative to the workspace root (`output_path` while reserved). */
+export declare const taskOutputPath: (id: string) => string;
+/**
+ * The absolute output file of a task from its `output_path`: absolute once the task started (the
+ * launch records `<workspace>/.capybara/tasks/<id>.out` of its instance); a reservation's relative
+ * path is read under the default workspace.
+ */
+export declare const taskOutputFile: (outputPath: string) => string;
+/** The file the launch writes the session id to, relative to the workspace root. */
+export declare const taskSidPath: (id: string) => string;
+/** A new task id: `bt_` plus 6 lowercase base32 characters. */
+export declare function newTaskId(): string;
+/** A task id ({@link newTaskId}). */
+export declare const TASK_ID_RE: RegExp;
+/**
+ * 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 declare function launchScript(id: string, command: string, seconds: number): string;
+/** The model-visible result of a launch (spec §2.1); `workspace`: the instance's workspace root. */
+export declare function startedText(id: string, description: string, workspace?: string): string;

package/dist/background/launch.js

@@ -0,0 +1,77 @@
+import { randomBytes } from "node:crypto";
+import { DEFAULT_SANDBOX_ROOTS } from "@capybara-hq/plugin-sdk";
+/**
+ * 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 the instance's workspace root (the launch exec's `cwd`), so the
+ * script is the same whatever the instance's roots are.
+ */
+/** 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 the workspace root. */
+export const TASKS_DIR = ".capybara/tasks";
+/** A task's output file, relative to the workspace root (`output_path` while reserved). */
+export const taskOutputPath = (id) => `${TASKS_DIR}/${id}.out`;
+/**
+ * The absolute output file of a task from its `output_path`: absolute once the task started (the
+ * launch records `<workspace>/.capybara/tasks/<id>.out` of its instance); a reservation's relative
+ * path is read under the default workspace.
+ */
+export const taskOutputFile = (outputPath) => outputPath.startsWith("/") ? outputPath : `${DEFAULT_SANDBOX_ROOTS.workspace}/${outputPath}`;
+/** The file the launch writes the session id to, relative to the workspace root. */
+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); `workspace`: the instance's workspace root. */
+export function startedText(id, description, workspace = DEFAULT_SANDBOX_ROOTS.workspace) {
+    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,56 @@
+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 environment
+ *   instance with running tasks (of any conversation using it), one exec through
+ *   `SandboxService.ifRunning` (which never creates or resumes an instance) 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 an instance 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, "cloudAvailable" | "availableFor" | "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 environment instance; returns how many finished. */
+    private pollSandbox;
+    /** The poll exec of one instance: each task's report by id. */
+    private pollExec;
+    /** Deletes the finished tasks older than `tools.outputRetentionDays` (their rows only). */
+    prune(): Promise<void>;
+}

package/dist/background/poll.job.js

@@ -0,0 +1,195 @@
+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 { rootsOf } from "@capybara-hq/plugin-sdk";
+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 { actingAs, taskActor } from "./session.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 environment
+ *   instance with running tasks (of any conversation using it), one exec through
+ *   `SandboxService.ifRunning` (which never creates or resumes an instance) 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 an instance 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");
+        }
+        const groups = new Map();
+        for (const t of await this.store.runningStarted()) {
+            if (t.sid === null || t.sandboxCreatedAt === null)
+                continue;
+            // one exec per instance: the tasks of every conversation sharing the environment
+            const key = `${t.environmentId} ${t.sandboxCreatedAt.getTime()}`;
+            groups.set(key, [...(groups.get(key) ?? []), t]);
+        }
+        let finished = 0;
+        for (const tasks of groups.values()) {
+            if (signal.aborted)
+                break;
+            try {
+                // the environment's provider is not there (no cloud provider, `@device` not served):
+                // its tasks stay as they are until it is
+                const env = tasks[0]?.environmentId ?? null;
+                if (env === null ? !this.sandbox.cloudAvailable : !(await this.sandbox.availableFor(env))) {
+                    continue;
+                }
+                finished += await this.pollSandbox(tasks, signal);
+            }
+            catch (err) {
+                if (signal.aborted)
+                    break;
+                this.log.warn("cannot poll background tasks; retrying next tick", {
+                    environmentId: tasks[0]?.environmentId,
+                    err,
+                });
+            }
+        }
+        if (finished > 0)
+            this.log.info("background tasks finished", { count: finished });
+        return finished;
+    }
+    /** Polls the tasks of one environment instance; returns how many finished. */
+    async pollSandbox(tasks, signal) {
+        const [first] = tasks;
+        // a task from before environments has no instance any more
+        const r = first.environmentId === null
+            ? { kind: "not_running", status: "gone" }
+            : await this.sandbox.ifRunning(first.environmentId, { createdAt: first.sandboxCreatedAt }, (p, h, sig) => this.pollExec(actingAs(p, taskActor(first)), h, tasks, sig), 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;
+    }
+    /** The poll exec of one instance: each task's report by id. */
+    async pollExec(p, h, tasks, signal) {
+        const res = await p.exec(h, {
+            command: pollScript(tasks.map((t) => ({ id: t.id, sid: t.sid }))),
+            cwd: rootsOf(h).workspace,
+            timeoutMs: POLL_EXEC_TIMEOUT_MS,
+            maxOutputBytes: POLL_MAX_OUTPUT_BYTES,
+            signal,
+        });
+        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);
+    }
+    /** 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,48 @@
+import { type SandboxActor, type SandboxHandle } from "@capybara-hq/plugin-sdk";
+import type { HeldProvider, TaggedProvider } from "../sandbox/sandbox.service.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).
+ */
+/**
+ * `p` with every `exec` carrying `actor` (`SandboxService.ifRunning` tags execs but leaves the
+ * actor to the caller): the provider then reads like a `withSandbox` holder's.
+ */
+export declare function actingAs(p: TaggedProvider, actor: SandboxActor): HeldProvider;
+/** Who a background task's own execs (poll, stop, reads) act for: its trigger and its owner. */
+export declare const taskActor: (task: {
+    triggerAccountId: string;
+    conversationId: string;
+}) => SandboxActor;
+/** 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: Pick<HeldProvider, "exec">, 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 the workspace root.
+ */
+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,80 @@
+import { rootsOf } from "@capybara-hq/plugin-sdk";
+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).
+ */
+/**
+ * `p` with every `exec` carrying `actor` (`SandboxService.ifRunning` tags execs but leaves the
+ * actor to the caller): the provider then reads like a `withSandbox` holder's.
+ */
+export function actingAs(p, actor) {
+    const wrapped = Object.create(p);
+    Object.defineProperty(wrapped, "exec", {
+        value: (h, args) => p.exec(h, { ...args, actor }),
+    });
+    return wrapped;
+}
+/** Who a background task's own execs (poll, stop, reads) act for: its trigger and its owner. */
+export const taskActor = (task) => ({ accountId: task.triggerAccountId, conversationId: task.conversationId });
+/** 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: rootsOf(h).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 the workspace root.
+ */
+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 the workspace root.
+ */
+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;