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

package/dist/background/launch-lock.js

@@ -12,9 +12,10 @@ import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { XactLock } from "../infra/database/xact-lock.js";
 /**
- * The launch lock of one sandbox (decision R9: one provider per transaction-scoped lock):
- * serializes background task reservations in a sandbox, so the count of running tasks checked
- * against `sandbox.background.maxTasks` and the insert of the new row are one step. Joins the
+ * The launch lock of one root conversation (decision R9: one provider per transaction-scoped
+ * lock): serializes background task reservations in its tree, so the count of running tasks
+ * checked against `sandbox.background.maxTasks` (per root conversation, whatever environment it
+ * works in) and the insert of the new row are one step. Joins the
  * caller's transaction (`mandatory`), which holds it until it ends.
  */
 let BackgroundLaunchLock = class BackgroundLaunchLock {

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

@@ -21,11 +21,12 @@ 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-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 {
@@ -46,8 +47,10 @@ export declare class BackgroundTaskPollJob {
      * 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. */
+    /** 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

@@ -14,10 +14,11 @@ 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 { 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";
@@ -42,11 +43,12 @@ 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-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 {
@@ -92,7 +94,8 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
         for (const t of await this.store.runningStarted()) {
             if (t.sid === null || t.sandboxCreatedAt === null)
                 continue;
-            const key = `${t.sandboxConversationId} ${t.sandboxCreatedAt.getTime()}`;
+            // 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;
@@ -106,7 +109,7 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
                 if (signal.aborted)
                     break;
                 this.log.warn("cannot poll background tasks; retrying next tick", {
-                    conversationId: tasks[0]?.sandboxConversationId,
+                    environmentId: tasks[0]?.environmentId,
                     err,
                 });
             }
@@ -115,22 +118,13 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
             this.log.info("background tasks finished", { count: finished });
         return finished;
     }
-    /** Polls the tasks of one sandbox instance; returns how many finished. */
+    /** Polls the tasks of one environment 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);
+        // 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) {
@@ -155,6 +149,20 @@ let BackgroundTaskPollJob = class BackgroundTaskPollJob {
         }
         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: "/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;

package/dist/background/session.d.ts

@@ -1,10 +1,21 @@
-import type { SandboxHandle, SandboxProvider } from "@capybara-hq/plugin-sdk";
+import type { SandboxActor, 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}). */
@@ -25,7 +36,7 @@ export declare function killSessionScript(sid: string): string;
  * 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>;
+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;
 /**

package/dist/background/session.js

@@ -5,6 +5,19 @@ import { TASK_ID_RE, TASKS_DIR } from "./launch.js";
  * 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}). */

package/dist/background/stop.d.ts

@@ -42,13 +42,19 @@ export declare class BackgroundTaskStopper {
      */
     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}).
+     * SIGTERM, the grace period, SIGKILL until the session is empty, then the last lines: in the
+     * task's own instance only (`ifRunning`); a task from before environments has none.
      */
-    stopSubagentTasks(conversationId: string, runId: string): Promise<void>;
+    private signalTask;
+    /**
+     * After a sub-agent run ended (spec §4.3): stops the running tasks of `conversationId` when it
+     * is a sub-agent's conversation; any other conversation is left alone. With `runId`, only the
+     * tasks that run started (a fork child's run: a later run of the same child keeps its own when
+     * an older run's end is handled late); without, all of them (a stopped background child, agent
+     * map spec §6). Their finish is marked `stoppedBy: "subagent_end"`, so it never wakes the child.
+     * 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}).

package/dist/background/stop.js

@@ -13,7 +13,7 @@ import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { BackgroundTaskFinisher, } from "./finish.js";
 import { TASKS_DIR } from "./launch.js";
-import { assertTaskRef, decodeTail, killSession, tailCommand } from "./session.js";
+import { actingAs, assertTaskRef, decodeTail, killSession, tailCommand, taskActor, } from "./session.js";
 import { BackgroundTaskStore } from "./store.js";
 /** How long a stop waits after SIGTERM before SIGKILL (spec §2.3). */
 export const STOP_GRACE_MS = 5000;
@@ -100,45 +100,23 @@ let BackgroundTaskStopper = class BackgroundTaskStopper {
         const cur = (await this.store.get(task.id)) ?? task;
         if (cur.status !== "running" || cur.sid === null || cur.sandboxCreatedAt === null)
             return cur;
+        const started = { ...cur, sandboxCreatedAt: cur.sandboxCreatedAt };
         const sid = cur.sid;
         assertTaskRef(cur.id, sid);
         const reported = why === "tool";
         // a person's stop never wakes the conversation (background Bash §3, fix round 1), nor does
-        // the stop of a conversation being deleted
-        const stoppedBy = why === "person" ? "person" : why === "conversation_deleted" ? "deletion" : undefined;
+        // the stop of a conversation being deleted or of a sub-agent that ended (agent map spec §5.3)
+        const stoppedBy = why === "person"
+            ? "person"
+            : why === "conversation_deleted"
+                ? "deletion"
+                : why === "subagent_end"
+                    ? "subagent_end"
+                    : undefined;
         const opts = stoppedBy === undefined ? {} : { stoppedBy };
         let r;
         try {
-            r = await this.sandbox.ifRunning(cur.sandboxConversationId, { createdAt: cur.sandboxCreatedAt }, async (p, h, sig) => {
-                const term = await p.exec(h, {
-                    command: termScript(cur.id, sid),
-                    cwd: "/workspace",
-                    timeoutMs: TERM_EXEC_TIMEOUT_MS,
-                    maxOutputBytes: 4096,
-                    signal: sig,
-                });
-                const exited = /^exited (-?[0-9]+)$/.exec(term.stdout.trim());
-                if (term.exitCode !== 0 || (!exited && term.stdout.trim() !== "term")) {
-                    throw new Error(`the stop of background task ${cur.id} failed (${term.exitCode})`);
-                }
-                // also after an exit: processes the command left running are stopped with the task
-                if (!(await killSession(p, h, sid))) {
-                    throw new Error(`background task ${cur.id} could not be confirmed stopped`);
-                }
-                const tail = await p.exec(h, {
-                    command: tailCommand(cur.id),
-                    cwd: "/workspace",
-                    timeoutMs: TAIL_EXEC_TIMEOUT_MS,
-                    maxOutputBytes: 64 * 1024,
-                    signal: sig,
-                });
-                const lastLines = tail.exitCode === 0 ? decodeTail(tail.stdout) : "";
-                // a task that had exited before the signal ends as its exit says
-                const to = exited
-                    ? exitedAs(cur, Number(exited[1]), new Date())
-                    : { status: "stopped" };
-                return { to, lastLines };
-            }, signal);
+            r = await this.signalTask(started, sid, signal);
         }
         catch (err) {
             await this.store
@@ -158,11 +136,51 @@ let BackgroundTaskStopper = class BackgroundTaskStopper {
         return (await this.store.get(cur.id)) ?? cur;
     }
     /**
-     * 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}).
+     * SIGTERM, the grace period, SIGKILL until the session is empty, then the last lines: in the
+     * task's own instance only (`ifRunning`); a task from before environments has none.
+     */
+    async signalTask(cur, sid, signal) {
+        if (cur.environmentId === null)
+            return { kind: "not_running", status: "gone" };
+        return this.sandbox.ifRunning(cur.environmentId, { createdAt: cur.sandboxCreatedAt }, async (tp, h, sig) => {
+            const p = actingAs(tp, taskActor(cur));
+            const term = await p.exec(h, {
+                command: termScript(cur.id, sid),
+                cwd: "/workspace",
+                timeoutMs: TERM_EXEC_TIMEOUT_MS,
+                maxOutputBytes: 4096,
+                signal: sig,
+            });
+            const exited = /^exited (-?[0-9]+)$/.exec(term.stdout.trim());
+            if (term.exitCode !== 0 || (!exited && term.stdout.trim() !== "term")) {
+                throw new Error(`the stop of background task ${cur.id} failed (${term.exitCode})`);
+            }
+            // also after an exit: processes the command left running are stopped with the task
+            if (!(await killSession(p, h, sid))) {
+                throw new Error(`background task ${cur.id} could not be confirmed stopped`);
+            }
+            const tail = await p.exec(h, {
+                command: tailCommand(cur.id),
+                cwd: "/workspace",
+                timeoutMs: TAIL_EXEC_TIMEOUT_MS,
+                maxOutputBytes: 64 * 1024,
+                signal: sig,
+            });
+            const lastLines = tail.exitCode === 0 ? decodeTail(tail.stdout) : "";
+            // a task that had exited before the signal ends as its exit says
+            const to = exited
+                ? exitedAs(cur, Number(exited[1]), new Date())
+                : { status: "stopped" };
+            return { to, lastLines };
+        }, signal);
+    }
+    /**
+     * After a sub-agent run ended (spec §4.3): stops the running tasks of `conversationId` when it
+     * is a sub-agent's conversation; any other conversation is left alone. With `runId`, only the
+     * tasks that run started (a fork child's run: a later run of the same child keeps its own when
+     * an older run's end is handled late); without, all of them (a stopped background child, agent
+     * map spec §6). Their finish is marked `stoppedBy: "subagent_end"`, so it never wakes the child.
+     * Never throws (see {@link stopAll}).
      */
     async stopSubagentTasks(conversationId, runId) {
         try {
@@ -173,7 +191,7 @@ let BackgroundTaskStopper = class BackgroundTaskStopper {
                 .executeTakeFirst();
             if (conv?.kind !== "subagent")
                 return;
-            const tasks = (await this.store.runningOwnedBy(conversationId)).filter((t) => t.runId === runId);
+            const tasks = (await this.store.runningOwnedBy(conversationId)).filter((t) => runId === undefined || t.runId === runId);
             await this.stopAll(tasks, "subagent_end");
         }
         catch (err) {

package/dist/background/store.d.ts

@@ -8,8 +8,16 @@ export interface BackgroundTaskRow {
     orgId: string;
     /** The owner: the child conversation for a sub-agent. */
     conversationId: string;
-    /** The root conversation that owns the sandbox. */
+    /**
+     * The root conversation of the owner's tree: `sandbox.background.maxTasks` counts per root
+     * conversation.
+     */
     sandboxConversationId: string;
+    /**
+     * The environment the task runs in (the root conversation's when it was launched): its instance
+     * is where the task's processes are. Null only for tasks from before environments (all finished).
+     */
+    environmentId: string | null;
     runId: string;
     callId: string;
     triggerAccountId: string;
@@ -64,9 +72,9 @@ export declare class BackgroundTaskStore {
     private readonly launchLock;
     constructor(db: KernelDb, txHost: TransactionHost, launchLock: BackgroundLaunchLock);
     /**
-     * Reserves a launch: under the sandbox's launch lock, counts the running tasks of
+     * Reserves a launch: under the root conversation's launch lock, counts the running tasks of
      * `row.sandboxConversationId` and inserts `row` as `running` (no `sid`) when fewer than
-     * `maxTasks` run. False (nothing written) when the sandbox already runs `maxTasks`.
+     * `maxTasks` run. False (nothing written) when that conversation tree already runs `maxTasks`.
      */
     reserve(row: BackgroundTaskReservation, maxTasks: number): Promise<boolean>;
     /**
@@ -114,7 +122,7 @@ export declare class BackgroundTaskStore {
     }[]>;
     insert(row: BackgroundTaskInsert): Promise<void>;
     get(id: string): Promise<BackgroundTaskRow | undefined>;
-    /** The running tasks of one sandbox, oldest first. */
+    /** The running tasks of one root conversation's tree, oldest first. */
     runningIn(sandboxConversationId: string): Promise<BackgroundTaskRow[]>;
     /**
      * Every running task that has started (its `sid` is set) and no live stop claimed, across
@@ -124,6 +132,7 @@ export declare class BackgroundTaskStore {
     runningStarted(): Promise<BackgroundTaskRow[]>;
     /** The running tasks one conversation owns (not those of its sub-agents), oldest first. */
     runningOwnedBy(conversationId: string): Promise<BackgroundTaskRow[]>;
+    /** The running tasks of one root conversation's tree (what `maxTasks` limits). */
     countRunning(sandboxConversationId: string): Promise<number>;
     /** The tasks owned by any of the conversations, newest first. */
     listFor(conversationIds: string[]): Promise<BackgroundTaskRow[]>;
@@ -142,8 +151,11 @@ export declare class BackgroundTaskStore {
     }): Promise<boolean>;
     /** Moves the read offset forward only (a concurrent reader never moves it back). */
     advanceOffset(id: string, to: number): Promise<void>;
-    /** Finished tasks of a sandbox whose process may still exist. */
-    pendingKills(sandboxConversationId: string): Promise<BackgroundTaskRow[]>;
+    /**
+     * Finished tasks of an environment whose process may still exist (any conversation's: they
+     * share the instance).
+     */
+    pendingKills(environmentId: string): Promise<BackgroundTaskRow[]>;
     clearKill(ids: string[]): Promise<void>;
     /** Deletes finished tasks that ended before `before`; a running one is never deleted. */
     pruneFinished(before: Date): Promise<number>;

package/dist/background/store.js

@@ -18,6 +18,7 @@ const toRow = (r) => ({
     orgId: r.org_id,
     conversationId: r.conversation_id,
     sandboxConversationId: r.sandbox_conversation_id,
+    environmentId: r.environment_id,
     runId: r.run_id,
     callId: r.call_id,
     triggerAccountId: r.trigger_account_id,
@@ -66,9 +67,9 @@ let BackgroundTaskStore = class BackgroundTaskStore {
         this.launchLock = launchLock;
     }
     /**
-     * Reserves a launch: under the sandbox's launch lock, counts the running tasks of
+     * Reserves a launch: under the root conversation's launch lock, counts the running tasks of
      * `row.sandboxConversationId` and inserts `row` as `running` (no `sid`) when fewer than
-     * `maxTasks` run. False (nothing written) when the sandbox already runs `maxTasks`.
+     * `maxTasks` run. False (nothing written) when that conversation tree already runs `maxTasks`.
      */
     async reserve(row, maxTasks) {
         await this.launchLock.lock(row.sandboxConversationId);
@@ -190,6 +191,7 @@ let BackgroundTaskStore = class BackgroundTaskStore {
             org_id: row.orgId,
             conversation_id: row.conversationId,
             sandbox_conversation_id: row.sandboxConversationId,
+            environment_id: row.environmentId,
             run_id: row.runId,
             call_id: row.callId,
             trigger_account_id: row.triggerAccountId,
@@ -211,7 +213,7 @@ let BackgroundTaskStore = class BackgroundTaskStore {
             .executeTakeFirst();
         return r === undefined ? undefined : toRow(r);
     }
-    /** The running tasks of one sandbox, oldest first. */
+    /** The running tasks of one root conversation's tree, oldest first. */
     async runningIn(sandboxConversationId) {
         const rows = await this.db
             .selectFrom("background_tasks")
@@ -252,6 +254,7 @@ let BackgroundTaskStore = class BackgroundTaskStore {
             .execute();
         return rows.map(toRow);
     }
+    /** The running tasks of one root conversation's tree (what `maxTasks` limits). */
     async countRunning(sandboxConversationId) {
         const r = await this.db
             .selectFrom("background_tasks")
@@ -306,12 +309,15 @@ let BackgroundTaskStore = class BackgroundTaskStore {
             .where(sql `read_offset < ${to}`)
             .execute();
     }
-    /** Finished tasks of a sandbox whose process may still exist. */
-    async pendingKills(sandboxConversationId) {
+    /**
+     * Finished tasks of an environment whose process may still exist (any conversation's: they
+     * share the instance).
+     */
+    async pendingKills(environmentId) {
         const rows = await this.db
             .selectFrom("background_tasks")
             .selectAll()
-            .where("sandbox_conversation_id", "=", sandboxConversationId)
+            .where("environment_id", "=", environmentId)
             .where("kill_pending", "=", true)
             .orderBy("started_at", "asc")
             .execute();

package/dist/background/tasks.service.d.ts

@@ -1,5 +1,6 @@
 import { ConversationAccess } from "../conversations/access.js";
 import { EventLog } from "../conversations/event-log.js";
+import { ConversationEnvironments } from "../environments/conversation-environments.js";
 import { KernelDb } from "../infra/database/kernel-db.js";
 import { SandboxService } from "../sandbox/sandbox.service.js";
 import { BackgroundTaskStopper } from "./stop.js";
@@ -33,7 +34,7 @@ export interface BackgroundTaskOutput {
 /**
  * The HTTP side of background tasks (spec 2026-11-05-background-bash-design §5): the tasks of a
  * conversation and of its sub-agents, stopping one, reading its output. A task is reachable
- * through the conversation that owns it or through that conversation's parent, and only by a
+ * through the conversation that owns it or through any conversation above it, and only by a
  * person who may see the conversation (`ConversationAccess`, the rule of `GET :id`, which is also
  * what `POST :id/abort` checks: the owner).
  */
@@ -44,8 +45,12 @@ export declare class BackgroundTasks {
     private readonly sandbox;
     private readonly eventLog;
     private readonly db;
-    constructor(access: Pick<ConversationAccess, "isAccessible">, store: Pick<BackgroundTaskStore, "listFor" | "get">, stopper: Pick<BackgroundTaskStopper, "stop">, sandbox: Pick<SandboxService, "available" | "ifRunning">, eventLog: Pick<EventLog, "findByIdem">, db: KernelDb);
-    /** The conversation and its sub-agents' conversations; `conversation.not_found` when not visible. */
+    private readonly environments;
+    constructor(access: Pick<ConversationAccess, "isAccessible">, store: Pick<BackgroundTaskStore, "listFor" | "get">, stopper: Pick<BackgroundTaskStopper, "stop">, sandbox: Pick<SandboxService, "available" | "ifRunning">, eventLog: Pick<EventLog, "findByIdem">, db: KernelDb, environments: Pick<ConversationEnvironments, "forTool">);
+    /**
+     * The conversation and every sub-agent conversation below it (grandchildren too: their tasks run
+     * in the root's sandbox, agent map spec §6); `conversation.not_found` when not visible.
+     */
     private scope;
     private view;
     private owned;
@@ -58,8 +63,13 @@ export declare class BackgroundTasks {
      */
     stop(orgId: string, conversationId: string, accountId: string, taskId: string, actorTokenId?: string): Promise<BackgroundTaskView>;
     /**
-     * The end of the task's output, at most `tail` bytes. Read live when the task's sandbox instance
-     * runs (never resuming a suspended sandbox); a finished task whose sandbox does not run answers
+     * Whether the task's environment may still be used by its conversation's owner (the access
+     * re-check every sandbox tool call makes); when it may not, the live read is skipped.
+     */
+    private environmentUsable;
+    /**
+     * The end of the task's output, at most `tail` bytes. Read live when the task's environment
+     * instance runs (never resuming a suspended one); a finished task whose sandbox does not run answers
      * with the last lines its finished event kept. Anything else is
      * `background_task.output_unavailable` (409).
      */