@capybara-hq/kernel 0.1.0-rc.22 → 0.1.0-rc.24

package/dist/admin/overview.service.d.ts

@@ -9,6 +9,8 @@ import { AccountsService } from "../identity/accounts.js";
 import { PlatformInboxService } from "../inbox/platform-inbox.service.js";
 import { OrgsService } from "../orgs/orgs.service.js";
 import { ProviderRegistry, type ProviderStatus } from "../runtime/providers.js";
+import { QueueLostJobs } from "../runtime/queue-lost-jobs.js";
+import { OutboxDeadService } from "./outbox-dead.service.js";
 /** The most rows each attention list returns; the rest are counted in `more`. */
 export declare const ATTENTION_LIST_MAX = 20;
 /** The admin overview's numbers (`GET /api/v1/admin/overview`): counts only. */
@@ -17,7 +19,8 @@ export interface AdminOverviewStats {
     accounts: number;
     /**
      * What waits for a super admin: the platform inbox total plus the extensions, plugin updates and
-     * model providers of {@link AdminAttention} (each counted in full, not capped).
+     * model providers of {@link AdminAttention} (each counted in full, not capped), every dead
+     * outbox row and the run queue's lost-jobs item.
      */
     attentionTotal: number;
     /** An attention source could not be read: `attentionTotal` leaves its items out. */
@@ -33,7 +36,7 @@ export type AttentionExtensionReason = "config" | "load_failed" | "approval" | "
 /** What is wrong with a model provider: its model list failed, or it lists no usable chat model. */
 export type AttentionProviderProblem = "list_failed" | "no_chat_model";
 /** An attention list a source failed to read (it is then empty, the others intact). */
-export type AttentionSource = "extensions" | "updates" | "providers";
+export type AttentionSource = "extensions" | "updates" | "providers" | "outbox" | "queue";
 export interface AttentionExtension {
     name: string;
     displayName: LocalizedName | null;
@@ -61,6 +64,27 @@ export interface AttentionProvider {
     icon: string | null;
     problem: AttentionProviderProblem;
 }
+/**
+ * Background work the kernel could not queue (transactional outbox spec §3.4): how many outbox
+ * rows are dead and the oldest one's `dead_at`. One item for all of them; the rows themselves are
+ * `GET /api/v1/admin/outbox/dead`.
+ */
+export interface AttentionOutboxDead {
+    kind: "outbox_dead";
+    count: number;
+    oldestAt: string;
+}
+/**
+ * The run queue lost background jobs (transactional outbox spec §8.3): the `run-orphan-check`
+ * found queued runs whose job was neither in the queue nor owed, which only Redis losing data
+ * explains. Their jobs were added again; the item says Redis durability needs a look, how many
+ * jobs were lost and when last (it stays a week after the last loss).
+ */
+export interface AttentionQueueLostJobs {
+    kind: "queue_lost_jobs";
+    count: number;
+    lastAt: string;
+}
 /**
  * `GET /api/v1/admin/overview/attention` (spec §5.2, §9): what needs a super admin besides the
  * inbox, each list at most {@link ATTENTION_LIST_MAX} rows with the rest counted in `more`, and
@@ -71,6 +95,10 @@ export interface AdminAttention {
     extensions: AttentionExtension[];
     updates: AttentionUpdate[];
     providers: AttentionProvider[];
+    /** System items: at most one, `outbox_dead`, when some outbox rows are dead. */
+    outbox: AttentionOutboxDead[];
+    /** System items: at most one, `queue_lost_jobs`, when the run queue lost jobs this week. */
+    queue: AttentionQueueLostJobs[];
     more: Record<AttentionSource, number>;
     unavailable: AttentionSource[];
 }
@@ -81,8 +109,9 @@ export declare function providerProblem(p: ProviderStatus): AttentionProviderPro
 /**
  * The admin overview (spec §4.1, §5.2): its numbers and the 待处理 lists, read live from the
  * sources the admin pages read (`ExtensionAdmin`, the catalog, the provider registry's cached
- * lists). Each source is read on its own: a failing one is reported in `unavailable`. Reads are not
- * audited (decision D5) and not cached further (every source is PG or already Redis-cached).
+ * lists, the dead outbox rows, the run queue's lost-jobs canary). Each source is read on its own: a failing one is reported in
+ * `unavailable`. Reads are not audited (decision D5) and not cached further (every source is PG
+ * or already Redis-cached).
  */
 export declare class AdminOverviewService {
     private readonly extensions;
@@ -94,10 +123,16 @@ export declare class AdminOverviewService {
     private readonly orgs;
     private readonly accounts;
     private readonly marketplaces;
+    private readonly outboxDead;
+    private readonly lostJobs;
     private readonly log;
-    constructor(extensions: ExtensionAdmin, catalog: CatalogService, registry: ProviderRegistry, displayNames: ExtensionDisplayNames, icons: PluginIcons, inbox: PlatformInboxService, orgs: OrgsService, accounts: AccountsService, marketplaces: MarketplacesService, log: Logger);
+    constructor(extensions: ExtensionAdmin, catalog: CatalogService, registry: ProviderRegistry, displayNames: ExtensionDisplayNames, icons: PluginIcons, inbox: PlatformInboxService, orgs: OrgsService, accounts: AccountsService, marketplaces: MarketplacesService, outboxDead: OutboxDeadService, lostJobs: Pick<QueueLostJobs, "summary">, log: Logger);
     stats(): Promise<AdminOverviewStats>;
     attention(): Promise<AdminAttention>;
+    /** The `queue_lost_jobs` item when the run queue lost jobs this week, else none. */
+    private queueRows;
+    /** The `outbox_dead` item when some outbox rows are dead, else none. */
+    private outboxRows;
     /**
      * The extensions needing a look, but not one pending approval whose plugin waits in the platform
      * inbox (a permission confirmation or an org upload: the inbox already lists and counts it). A

package/dist/admin/overview.service.js

@@ -18,6 +18,8 @@ import { PlatformInboxService } from "../inbox/platform-inbox.service.js";
 import { KERNEL_LOGGER } from "../infra/tokens.js";
 import { OrgsService } from "../orgs/orgs.service.js";
 import { ProviderRegistry } from "../runtime/providers.js";
+import { QueueLostJobs } from "../runtime/queue-lost-jobs.js";
+import { OutboxDeadService } from "./outbox-dead.service.js";
 /** The most rows each attention list returns; the rest are counted in `more`. */
 export const ATTENTION_LIST_MAX = 20;
 /** The reason an extension is listed, or null when it needs nothing. */
@@ -53,8 +55,9 @@ export function providerProblem(p) {
 /**
  * The admin overview (spec §4.1, §5.2): its numbers and the 待处理 lists, read live from the
  * sources the admin pages read (`ExtensionAdmin`, the catalog, the provider registry's cached
- * lists). Each source is read on its own: a failing one is reported in `unavailable`. Reads are not
- * audited (decision D5) and not cached further (every source is PG or already Redis-cached).
+ * lists, the dead outbox rows, the run queue's lost-jobs canary). Each source is read on its own: a failing one is reported in
+ * `unavailable`. Reads are not audited (decision D5) and not cached further (every source is PG
+ * or already Redis-cached).
  */
 let AdminOverviewService = class AdminOverviewService {
     extensions;
@@ -66,8 +69,10 @@ let AdminOverviewService = class AdminOverviewService {
     orgs;
     accounts;
     marketplaces;
+    outboxDead;
+    lostJobs;
     log;
-    constructor(extensions, catalog, registry, displayNames, icons, inbox, orgs, accounts, marketplaces, log) {
+    constructor(extensions, catalog, registry, displayNames, icons, inbox, orgs, accounts, marketplaces, outboxDead, lostJobs, log) {
         this.extensions = extensions;
         this.catalog = catalog;
         this.registry = registry;
@@ -77,6 +82,8 @@ let AdminOverviewService = class AdminOverviewService {
         this.orgs = orgs;
         this.accounts = accounts;
         this.marketplaces = marketplaces;
+        this.outboxDead = outboxDead;
+        this.lostJobs = lostJobs;
         this.log = log;
     }
     async stats() {
@@ -87,10 +94,17 @@ let AdminOverviewService = class AdminOverviewService {
             this.attention(),
         ]);
         const listed = (s) => attention[s].length + attention.more[s];
+        // each dead row waits for a super admin, not the one item that counts them
+        const dead = attention.outbox.reduce((n, o) => n + o.count, 0);
         return {
             orgs: orgs.length,
             accounts,
-            attentionTotal: inbox + listed("extensions") + listed("updates") + listed("providers"),
+            attentionTotal: inbox +
+                listed("extensions") +
+                listed("updates") +
+                listed("providers") +
+                dead +
+                attention.queue.length,
             partial: attention.unavailable.length > 0,
         };
     }
@@ -98,16 +112,20 @@ let AdminOverviewService = class AdminOverviewService {
         // the catalog is read once: the update rows, and the plugins the inbox already lists
         const items = this.catalogItems();
         items.catch(() => { }); // awaited (and reported) by updateRows
-        const [extensions, updates, providers] = await Promise.allSettled([
+        const [extensions, updates, providers, outbox, queue] = await Promise.allSettled([
             this.extensionRows(items),
             this.updateRows(items),
             this.providerRows(),
+            this.outboxRows(),
+            this.queueRows(),
         ]);
         const out = {
             extensions: [],
             updates: [],
             providers: [],
-            more: { extensions: 0, updates: 0, providers: 0 },
+            outbox: [],
+            queue: [],
+            more: { extensions: 0, updates: 0, providers: 0, outbox: 0, queue: 0 },
             unavailable: [],
         };
         /** The rows of a source that answered (capped), or none and its name in `unavailable`. */
@@ -127,8 +145,22 @@ let AdminOverviewService = class AdminOverviewService {
         out.extensions = take("extensions", extensions);
         out.updates = take("updates", updates);
         out.providers = take("providers", providers);
+        out.outbox = take("outbox", outbox);
+        out.queue = take("queue", queue);
         return out;
     }
+    /** The `queue_lost_jobs` item when the run queue lost jobs this week, else none. */
+    async queueRows() {
+        const lost = await this.lostJobs.summary();
+        return lost === null ? [] : [{ kind: "queue_lost_jobs", ...lost }];
+    }
+    /** The `outbox_dead` item when some outbox rows are dead, else none. */
+    async outboxRows() {
+        const { count, oldestAt } = await this.outboxDead.summary();
+        if (count === 0 || oldestAt === null)
+            return [];
+        return [{ kind: "outbox_dead", count, oldestAt: oldestAt.toISOString() }];
+    }
     /**
      * The extensions needing a look, but not one pending approval whose plugin waits in the platform
      * inbox (a permission confirmation or an org upload: the inbox already lists and counts it). A
@@ -218,6 +250,8 @@ AdminOverviewService = __decorate([
     __param(6, Inject(OrgsService)),
     __param(7, Inject(AccountsService)),
     __param(8, Inject(MarketplacesService)),
-    __param(9, Inject(KERNEL_LOGGER))
+    __param(9, Inject(OutboxDeadService)),
+    __param(10, Inject(QueueLostJobs)),
+    __param(11, Inject(KERNEL_LOGGER))
 ], AdminOverviewService);
 export { AdminOverviewService };

package/dist/agents/from-template.js

@@ -329,7 +329,7 @@ export async function planFromTemplate(db, orgId, row, opts) {
         }
         if (describesSubagents)
             listed.add(AGENT_TOOL);
-        // `TaskOutput` / `TaskStop` follow `Bash`
+        // `TaskOutput` / `TaskStop` / `TaskList` follow `Bash`
         for (const name of AGENT_BUILTIN_NAMES)
             if (!listed.has(name))
                 offBuiltin(name);

package/dist/background/finish.d.ts

@@ -1,6 +1,7 @@
 import { EventLog } from "../conversations/event-log.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
 import { type BackgroundTaskRow, BackgroundTaskStore } from "./store.js";
 /** Where a task ends (as {@link BackgroundTaskStore.finish} takes it). */
 export type BackgroundFinish = Parameters<BackgroundTaskStore["finish"]>[1];
@@ -19,7 +20,8 @@ export declare const finishedEventKey: (taskId: string) => string;
  * task (two pollers, a poll and a stop) exactly one writes it. After the commit: the log's notify,
  * the `changed: "background"` frame (to the owner and, for a sub-agent's task, the conversation
  * that owns the sandbox, whose panel lists it too) and the `background_task.finished` domain event
- * (`BackgroundWake` wakes an idle conversation; it lives in the runtime, above this module).
+ * (`BackgroundWake` wakes an idle conversation; it lives in the runtime, above this module). A
+ * finish that may wake the conversation also owes the ensure-run backstop in the transaction.
  *
  * Holds no lock and runs no sandbox command: the caller reads `lastLines` before.
  */
@@ -28,7 +30,8 @@ export declare class BackgroundTaskFinisher {
     private readonly eventLog;
     private readonly events;
     readonly txHost: TransactionHost;
-    constructor(store: Pick<BackgroundTaskStore, "finish">, eventLog: EventLog, events: KernelEvents, txHost: TransactionHost);
+    private readonly outbox;
+    constructor(store: Pick<BackgroundTaskStore, "finish">, eventLog: EventLog, events: KernelEvents, txHost: TransactionHost, outbox: Pick<OutboxService, "add">);
     /**
      * Finishes `task` as `to` with its last output lines (cut to their last 4 000 characters);
      * `reported` when a tool call already told the model in its run. False (nothing written) when the

package/dist/background/finish.js

@@ -13,6 +13,8 @@ import { afterCommit } from "../infra/database/after-commit.js";
 import { TransactionHost } from "../infra/database/transaction-host.js";
 import { Transactional } from "../infra/database/transactional.decorator.js";
 import { KernelEvents } from "../infra/events/kernel-events.js";
+import { OutboxService } from "../infra/outbox/outbox.service.js";
+import { oweEnsureRun } from "../runtime/run-jobs.js";
 import { taskOutputFile } from "./launch.js";
 import { LAST_LINES_MAX_CHARS } from "./session.js";
 import { BackgroundTaskStore } from "./store.js";
@@ -25,7 +27,8 @@ export const finishedEventKey = (taskId) => `background_task_finished:${taskId}`
  * task (two pollers, a poll and a stop) exactly one writes it. After the commit: the log's notify,
  * the `changed: "background"` frame (to the owner and, for a sub-agent's task, the conversation
  * that owns the sandbox, whose panel lists it too) and the `background_task.finished` domain event
- * (`BackgroundWake` wakes an idle conversation; it lives in the runtime, above this module).
+ * (`BackgroundWake` wakes an idle conversation; it lives in the runtime, above this module). A
+ * finish that may wake the conversation also owes the ensure-run backstop in the transaction.
  *
  * Holds no lock and runs no sandbox command: the caller reads `lastLines` before.
  */
@@ -34,11 +37,13 @@ let BackgroundTaskFinisher = class BackgroundTaskFinisher {
     eventLog;
     events;
     txHost;
-    constructor(store, eventLog, events, txHost) {
+    outbox;
+    constructor(store, eventLog, events, txHost, outbox) {
         this.store = store;
         this.eventLog = eventLog;
         this.events = events;
         this.txHost = txHost;
+        this.outbox = outbox;
     }
     /**
      * Finishes `task` as `to` with its last output lines (cut to their last 4 000 characters);
@@ -71,6 +76,11 @@ let BackgroundTaskFinisher = class BackgroundTaskFinisher {
                 },
             },
         ]);
+        // a finish that may wake the conversation owes the ensure-run backstop with its event: the
+        // wake after the commit (`BackgroundWake`) may never happen (transactional outbox spec §6)
+        if (event && !reported && opts.stoppedBy === undefined) {
+            await oweEnsureRun(this.outbox, task.conversationId, event.seq, task.orgId);
+        }
         const conversations = [...new Set([task.conversationId, task.sandboxConversationId])];
         afterCommit(async () => {
             if (event)
@@ -90,6 +100,7 @@ BackgroundTaskFinisher = __decorate([
     __param(0, Inject(BackgroundTaskStore)),
     __param(1, Inject(EventLog)),
     __param(2, Inject(KernelEvents)),
-    __param(3, Inject(TransactionHost))
+    __param(3, Inject(TransactionHost)),
+    __param(4, Inject(OutboxService))
 ], BackgroundTaskFinisher);
 export { BackgroundTaskFinisher };

package/dist/background/launch.d.ts

@@ -28,14 +28,53 @@ export declare const taskSidPath: (id: string) => string;
 export declare function newTaskId(): string;
 /** A task id ({@link newTaskId}). */
 export declare const TASK_ID_RE: RegExp;
+/**
+ * A shell fragment that sets how a task's processes are found and signalled by its sid, defining
+ * `tk_alive <sid>` (status 0 while the task has a process) and `tk_kill <SIGNAL> <sid>` (0: sent,
+ * 1: no process left, anything else: a failure), and `pg` to the mode:
+ * - `-s`, the session, where `pgrep` has `-s` (Linux procps and busybox, the sandbox-fake shims:
+ *   `pgrep -s 0`, the own session, exits 0 or 1): `pgrep -s` and `pkill -s`;
+ * - `-g`, the process group, elsewhere (macOS). Its `pgrep` has no `-s`, and inside the OS sandbox
+ *   (Seatbelt) a command can neither list processes nor signal those of another command. So the
+ *   task's process group (its id is the sid) is watched by its launcher ({@link GROUP_LAUNCHER}),
+ *   which signals it on request: `tk_kill` appends the signal to `.capybara/tasks/g<sid>.ctl`, and
+ *   `tk_alive` asks `kill(0, -sid)`, where "not permitted" (another command's group) still means
+ *   the group exists. A group signal is one system call, so it misses no process forked meanwhile.
+ * Relative to the workspace root. Every script that asks for or signals a task's processes starts
+ * with it; the launch picks its launcher with the same test.
+ */
+export declare const SESSION_MODE_SCRIPT: string;
+/**
+ * The process group launcher (macOS: {@link SESSION_MODE_SCRIPT}'s `-g`), a perl program run as
+ * `perl -e <this> <seconds> <task path>` from the workspace root. It makes a session of its own
+ * (leaving the launch exec's process group), starts `bash <task>.sh` as the leader of a new process
+ * group (the task; its id, the sid, goes to `<task>.sid` through a rename) and watches it every
+ * 0.1 s, outside the group:
+ * - the command exits: its status as the shell gives it (`128 + signal` when killed) goes to
+ *   `<task>.exit`, and what it left running in the group is SIGKILLed (the task ends when its
+ *   command exits, as the poll does on Linux);
+ * - the time limit passes: 137 goes to `<task>.exit`, then the group is SIGKILLed (as
+ *   `timeout -s KILL`);
+ * - a signal is requested in `g<sid>.ctl` ({@link SESSION_MODE_SCRIPT}'s `tk_kill`, read through
+ *   a rename): the group gets it, and no exit file is written any more (a stop, as on Linux).
+ * It exits once the group is empty. Contains no single quote (it goes between single quotes).
+ */
+export declare const GROUP_LAUNCHER: string;
 /**
  * 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. An environment 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).
+ * runs its command in), detached from the exec under a hard time limit of `seconds` that SIGKILLs
+ * every process of the task, with its exit status written to `<id>.exit` and its output to
+ * `<id>.out`; the task's sid goes to `<id>.sid` and is printed. Where `pgrep` has `-s`
+ * ({@link SESSION_MODE_SCRIPT}) the command runs in a session of its own under
+ * `setsid nohup sh -c 'timeout -s KILL <seconds> …'` and the sid is `$!`, the pid `setsid` started;
+ * elsewhere (macOS: no `setsid`, no `timeout`, no `pgrep -s`) {@link GROUP_LAUNCHER} runs it in a
+ * process group of its own, watched by the launcher, and writes the sid (the group id) itself,
+ * which the launch waits for (up to 10 s). The script starts with `BACKGROUND_LAUNCH_LINE`, so a
+ * local device, which kills what any other exec leaves running, leaves the task alone. An
+ * environment 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. */

package/dist/background/launch.js

@@ -1,5 +1,5 @@
 import { randomBytes } from "node:crypto";
-import { DEFAULT_SANDBOX_ROOTS } from "@capybara-hq/plugin-sdk";
+import { BACKGROUND_LAUNCH_LINE, 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.
@@ -34,18 +34,89 @@ export function newTaskId() {
         out += BASE32[b & 31];
     return out;
 }
-/** The programs the launch and the later polls and stops need in the environment. */
-const REQUIRED = ["bash", "setsid", "nohup", "timeout", "pgrep", "pkill", "base64"];
+/** The programs a session launch and the later polls and stops need (Linux, sandbox-fake). */
+const REQUIRED_SESSION = ["bash", "setsid", "nohup", "timeout", "pgrep", "pkill", "base64"];
+/** The programs a process group launch and the later polls and stops need (macOS). */
+const REQUIRED_GROUP = ["bash", "perl", "nohup", "base64"];
 /** A task id ({@link newTaskId}). */
 export const TASK_ID_RE = /^bt_[a-z2-7]{6}$/;
+/**
+ * A shell fragment that sets how a task's processes are found and signalled by its sid, defining
+ * `tk_alive <sid>` (status 0 while the task has a process) and `tk_kill <SIGNAL> <sid>` (0: sent,
+ * 1: no process left, anything else: a failure), and `pg` to the mode:
+ * - `-s`, the session, where `pgrep` has `-s` (Linux procps and busybox, the sandbox-fake shims:
+ *   `pgrep -s 0`, the own session, exits 0 or 1): `pgrep -s` and `pkill -s`;
+ * - `-g`, the process group, elsewhere (macOS). Its `pgrep` has no `-s`, and inside the OS sandbox
+ *   (Seatbelt) a command can neither list processes nor signal those of another command. So the
+ *   task's process group (its id is the sid) is watched by its launcher ({@link GROUP_LAUNCHER}),
+ *   which signals it on request: `tk_kill` appends the signal to `.capybara/tasks/g<sid>.ctl`, and
+ *   `tk_alive` asks `kill(0, -sid)`, where "not permitted" (another command's group) still means
+ *   the group exists. A group signal is one system call, so it misses no process forked meanwhile.
+ * Relative to the workspace root. Every script that asks for or signals a task's processes starts
+ * with it; the launch picks its launcher with the same test.
+ */
+export const SESSION_MODE_SCRIPT = [
+    'if pgrep -s 0 >/dev/null 2>&1 || [ "$?" -eq 1 ]; then pg=-s',
+    'tk_alive() { pgrep -s "$1" >/dev/null 2>&1; }',
+    'tk_kill() { pkill -"$1" -s "$2"; }',
+    "else pg=-g",
+    `tk_alive() { perl -e 'exit((kill(0, -$ARGV[0]) || $!{EPERM}) ? 0 : 1)' "$1"; }`,
+    `tk_kill() { tk_alive "$2" || return 1; echo "$1" >> ${TASKS_DIR}/g"$2".ctl || return 2; }`,
+    "fi",
+].join("\n");
+/**
+ * The process group launcher (macOS: {@link SESSION_MODE_SCRIPT}'s `-g`), a perl program run as
+ * `perl -e <this> <seconds> <task path>` from the workspace root. It makes a session of its own
+ * (leaving the launch exec's process group), starts `bash <task>.sh` as the leader of a new process
+ * group (the task; its id, the sid, goes to `<task>.sid` through a rename) and watches it every
+ * 0.1 s, outside the group:
+ * - the command exits: its status as the shell gives it (`128 + signal` when killed) goes to
+ *   `<task>.exit`, and what it left running in the group is SIGKILLed (the task ends when its
+ *   command exits, as the poll does on Linux);
+ * - the time limit passes: 137 goes to `<task>.exit`, then the group is SIGKILLed (as
+ *   `timeout -s KILL`);
+ * - a signal is requested in `g<sid>.ctl` ({@link SESSION_MODE_SCRIPT}'s `tk_kill`, read through
+ *   a rename): the group gets it, and no exit file is written any more (a stop, as on Linux).
+ * It exits once the group is empty. Contains no single quote (it goes between single quotes).
+ */
+export const GROUP_LAUNCHER = [
+    "use POSIX;",
+    "my ($n, $t) = @ARGV;",
+    "my ($d) = $t =~ m{^(.*)/};",
+    'sub put { my ($f, $v) = @_; open(my $h, ">", "$f.tmp") or return; print $h "$v\\n"; close($h); rename("$f.tmp", $f) }',
+    'POSIX::setsid() or die "setsid: $!\\n";',
+    "my $c = fork();",
+    'defined $c or die "fork: $!\\n";',
+    'if ($c == 0) { setpgid(0, 0); exec("bash", "$t.sh") or POSIX::_exit(127) }',
+    "setpgid($c, $c);",
+    'put("$t.sid", $c);',
+    'my $ctl = "$d/g$c.ctl";',
+    "my $end = time() + $n;",
+    "my ($code, $done);",
+    'sub fin { put("$t.exit", $_[0]) unless $done; $done = 1 }',
+    "while (1) {",
+    '  if (rename($ctl, "$ctl.$$")) { open(my $h, "<", "$ctl.$$"); my @s = grep { /^[A-Z0-9]+$/ } map { s/\\s+//gr } <$h>; close($h); unlink("$ctl.$$"); $done = 1; kill($_, -$c) for @s }',
+    '  if (!defined $code && waitpid($c, WNOHANG) == $c) { $code = ($? & 127) ? 128 + ($? & 127) : $? >> 8; fin($code); kill("KILL", -$c) }',
+    '  if (!defined $code && time() >= $end) { fin(137); kill("KILL", -$c) }',
+    "  last if defined $code && !kill(0, -$c);",
+    "  select(undef, undef, undef, 0.1);",
+    "}",
+].join(" ");
 /**
  * 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. An environment 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).
+ * runs its command in), detached from the exec under a hard time limit of `seconds` that SIGKILLs
+ * every process of the task, with its exit status written to `<id>.exit` and its output to
+ * `<id>.out`; the task's sid goes to `<id>.sid` and is printed. Where `pgrep` has `-s`
+ * ({@link SESSION_MODE_SCRIPT}) the command runs in a session of its own under
+ * `setsid nohup sh -c 'timeout -s KILL <seconds> …'` and the sid is `$!`, the pid `setsid` started;
+ * elsewhere (macOS: no `setsid`, no `timeout`, no `pgrep -s`) {@link GROUP_LAUNCHER} runs it in a
+ * process group of its own, watched by the launcher, and writes the sid (the group id) itself,
+ * which the launch waits for (up to 10 s). The script starts with `BACKGROUND_LAUNCH_LINE`, so a
+ * local device, which kills what any other exec leaves running, leaves the task alone. An
+ * environment 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))
@@ -55,15 +126,27 @@ export function launchScript(id, command, seconds) {
     }
     const b64 = Buffer.from(command, "utf8").toString("base64");
     const t = `${TASKS_DIR}/${id}`;
+    const need = (list) => `for c in ${list.join(" ")}; do command -v "$c" >/dev/null 2>&1 || { echo "Background tasks need ${list.join(", ")} in this environment; $c is missing." >&2; exit 127; }; done`;
     return [
+        // first: a local device kills what an exec leaves running, except a launch's detached task
+        BACKGROUND_LAUNCH_LINE,
         "set -e",
-        `for c in ${REQUIRED.join(" ")}; do command -v "$c" >/dev/null 2>&1 || { echo "Background tasks need ${REQUIRED.join(", ")} in this environment; $c is missing." >&2; exit 127; }; done`,
+        SESSION_MODE_SCRIPT,
+        `if [ "$pg" = -s ]; then ${need(REQUIRED_SESSION)}; else ${need(REQUIRED_GROUP)}; fi`,
         `mkdir -p ${TASKS_DIR}`,
         `printf '%s' '${b64}' | base64 -d > ${t}.sh`,
+        `if [ "$pg" = -s ]; then`,
         `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`,
+        "else",
+        `rm -f ${t}.sid`,
+        `nohup perl -e '${GROUP_LAUNCHER}' ${seconds} ${t} > ${t}.out 2>&1 < /dev/null &`,
+        // the launcher writes the group id once the group exists
+        `i=0; while [ ! -s ${t}.sid ] && [ "$i" -lt 200 ]; do sleep 0.05; i=$((i+1)); done`,
+        `[ -s ${t}.sid ] || { echo "The background task did not start: no process group id after 10 s." >&2; exit 1; }`,
+        "fi",
         `cat ${t}.sid`,
     ].join("\n");
 }

package/dist/background/session.d.ts

@@ -4,7 +4,8 @@ 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).
+ * Linux). macOS has no `setsid` and its `pgrep` / `pkill` no `-s`: there the task is the process
+ * group the launch made (`launchScript`), signalled with `kill -- -<sid>` ({@link SESSION_MODE_SCRIPT}).
  */
 /**
  * `p` with every `exec` carrying `actor` (`SandboxService.ifRunning` tags execs but leaves the
@@ -27,7 +28,8 @@ export declare function assertTaskRef(id: string, sid: string): void;
  * 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.
+ * the variables and functions of {@link SESSION_MODE_SCRIPT} (it starts with it), `ks`, `kc` and `ki`. `sid` must be
+ * a session id.
  */
 export declare function killSessionScript(sid: string): string;
 /**
@@ -37,6 +39,16 @@ export declare function killSessionScript(sid: string): string;
  * 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>;
+/** How long a stop waits after SIGTERM before SIGKILL (spec §2.3). */
+export declare const STOP_GRACE_MS = 5000;
+/** The time limit of the SIGTERM exec: the grace period plus some room. */
+export declare const TERM_EXEC_TIMEOUT_MS: number;
+/**
+ * Exit code 0 with `exited <code>` when the task had already finished (its exit file exists),
+ * else sends SIGTERM to the session and waits up to {@link STOP_GRACE_MS} for it to empty, then
+ * prints `term`. Relative to the workspace root.
+ */
+export declare function termScript(id: string, sid: string): string;
 /** The longest `lastLines` of a finished task (spec §2.4). */
 export declare const LAST_LINES_MAX_CHARS = 4000;
 /**

package/dist/background/session.js

@@ -1,10 +1,11 @@
 import { rootsOf } from "@capybara-hq/plugin-sdk";
-import { TASK_ID_RE, TASKS_DIR } from "./launch.js";
+import { SESSION_MODE_SCRIPT, 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).
+ * Linux). macOS has no `setsid` and its `pgrep` / `pkill` no `-s`: there the task is the process
+ * group the launch made (`launchScript`), signalled with `kill -- -<sid>` ({@link SESSION_MODE_SCRIPT}).
  */
 /**
  * `p` with every `exec` carrying `actor` (`SandboxService.ifRunning` tags execs but leaves the
@@ -35,12 +36,13 @@ export function assertTaskRef(id, sid) {
  * 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.
+ * the variables and functions of {@link SESSION_MODE_SCRIPT} (it starts with it), `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`;
+    return `${SESSION_MODE_SCRIPT}\nks=3; for ki in 1 2 3 4 5 6 7 8 9 10; do tk_kill KILL ${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
@@ -62,6 +64,26 @@ export async function killSession(p, h, sid) {
         .catch(() => undefined);
     return r?.exitCode === 0;
 }
+/** How long a stop waits after SIGTERM before SIGKILL (spec §2.3). */
+export const STOP_GRACE_MS = 5000;
+/** The time limit of the SIGTERM exec: the grace period plus some room. */
+export const TERM_EXEC_TIMEOUT_MS = STOP_GRACE_MS + 5000;
+/**
+ * Exit code 0 with `exited <code>` when the task had already finished (its exit file exists),
+ * else sends SIGTERM to the session and waits up to {@link STOP_GRACE_MS} for it to empty, then
+ * prints `term`. Relative to the workspace root.
+ */
+export function termScript(id, sid) {
+    const f = `${TASKS_DIR}/${id}`;
+    const tries = Math.ceil(STOP_GRACE_MS / 200);
+    return [
+        `if [ -s ${f}.exit ]; then echo "exited $(cat ${f}.exit)"; exit 0; fi`,
+        SESSION_MODE_SCRIPT,
+        `tk_kill TERM ${sid} >/dev/null 2>&1`,
+        `i=0; while [ "$i" -lt ${tries} ] && tk_alive ${sid}; do sleep 0.2; i=$((i+1)); done`,
+        "echo term",
+    ].join("\n");
+}
 /** 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). */

package/dist/background/status.d.ts

@@ -5,7 +5,7 @@ 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
+     * Whether the session still has a process: `pgrep -s <sid>` (`-g` on macOS), or, for a task whose command
      * exited, whether its leftover processes could not be confirmed killed.
      */
     alive: boolean;

package/dist/background/status.js

@@ -1,4 +1,4 @@
-import { TASK_ID_RE, TASKS_DIR } from "./launch.js";
+import { SESSION_MODE_SCRIPT, TASK_ID_RE, TASKS_DIR } from "./launch.js";
 import { decodeTail, killSessionScript, SID_RE, tailCommand } from "./session.js";
 import { exitedAs } from "./stop.js";
 /**
@@ -17,7 +17,7 @@ export function pollScript(tasks) {
         }
         const f = `${TASKS_DIR}/${id}`;
         return [
-            `if pgrep -s ${sid} >/dev/null 2>&1; then a=1; else a=0; fi`,
+            `if tk_alive ${sid}; 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`,
@@ -25,7 +25,7 @@ export function pollScript(tasks) {
             `echo "${id} $c $a \${t:--}"`,
         ].join("\n");
     });
-    return lines.join("\n");
+    return [SESSION_MODE_SCRIPT, ...lines].join("\n");
 }
 /** Parses {@link pollScript}'s output; a task missing from it is absent from the map. */
 export function parsePollOutput(stdout) {

package/dist/background/stop.d.ts

@@ -5,8 +5,6 @@ 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). */