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

package/dist/admin/admin.controller.d.ts

@@ -5,7 +5,7 @@ import { PluginIcons } from "../extensions/plugin-icons.js";
 import { type Account, AccountsService } from "../identity/accounts.js";
 import { type Principal } from "../identity/principal.js";
 import { SessionService } from "../identity/sessions.js";
-import { type DeploymentSettings, SettingsService } from "../identity/settings.js";
+import { type DeploymentSettingsView, SettingsService } from "../identity/settings.js";
 import { KernelConfigService } from "../infra/config/kernel-config.service.js";
 import { type ModelDisabledPatch, type ModelProviderParams } from "../models/enablement.controller.js";
 import { type ModelDisableResult, ModelEnablement } from "../models/enablement.js";
@@ -67,8 +67,8 @@ export declare class AdminController {
     orgMembers({ orgId }: z.infer<typeof AdminOrgParams>): Promise<{
         members: Member[];
     }>;
-    getSettings(): Promise<DeploymentSettings>;
-    putSettings(principal: Principal, body: z.infer<typeof DeploymentSettingsBody>): Promise<DeploymentSettings>;
+    getSettings(): Promise<DeploymentSettingsView>;
+    putSettings(principal: Principal, body: z.infer<typeof DeploymentSettingsBody>): Promise<DeploymentSettingsView>;
     /**
      * 模型供应商与模型（后台「模型」页）：每个供应商带状态，列模型失败的标 `error`，不影响其他供应商；
      * 一并返回价格表与币种（改价仍走 `PUT /admin/model-prices`）。Each provider carries its extension's

package/dist/admin/admin.controller.js

@@ -142,11 +142,15 @@ let AdminController = class AdminController {
         return { members: await this.members.list(orgId) };
     }
     async getSettings() {
-        return this.settings.get();
+        return this.settings.view();
     }
     async putSettings(principal, body) {
         const actor = requireUser(principal);
-        return this.settings.update(body, actor.account.id, patTokenId(actor));
+        const tokenId = patTokenId(actor);
+        // an API token may lower the platform's sandbox tiers, never raise them (dev tiers spec §2)
+        return this.settings.update(body, actor.account.id, tokenId, undefined, {
+            onlyNarrows: tokenId !== undefined,
+        });
     }
     /**
      * 模型供应商与模型（后台「模型」页）：每个供应商带状态，列模型失败的标 `error`，不影响其他供应商；

package/dist/admin/admin.schemas.d.ts

@@ -58,6 +58,19 @@ export declare const DeploymentSettingsBody: z.ZodObject<{
         enabled: z.ZodOptional<z.ZodBoolean>;
         disabled: z.ZodOptional<z.ZodArray<z.ZodString>>;
     }, z.core.$strict>>;
+    sandboxTiers: z.ZodOptional<z.ZodObject<{
+        max: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            dev: "dev";
+            open: "open";
+            strict: "strict";
+        }>>>;
+        default: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+            dev: "dev";
+            open: "open";
+            strict: "strict";
+        }>>>;
+        allowUnsandboxed: z.ZodOptional<z.ZodNullable<z.ZodBoolean>>;
+    }, z.core.$strict>>;
 }, z.core.$strict>;
 export declare const PurposeParams: z.ZodObject<{
     purpose: z.ZodString;

package/dist/background/launch.d.ts

@@ -28,14 +28,52 @@ 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). 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

@@ -34,18 +34,88 @@ 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). 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 +125,25 @@ 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 [
         "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). */

package/dist/background/stop.js

@@ -13,30 +13,10 @@ import { KernelDb } from "../infra/database/kernel-db.js";
 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 { actingAs, assertTaskRef, decodeTail, killSession, tailCommand, taskActor, } from "./session.js";
+import { actingAs, assertTaskRef, decodeTail, killSession, TERM_EXEC_TIMEOUT_MS, tailCommand, taskActor, termScript, } 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;
-/** The time limit of the SIGTERM exec: the grace period plus some room. */
-const TERM_EXEC_TIMEOUT_MS = STOP_GRACE_MS + 5000;
 /** The time limit of reading the last lines after a stop. */
 const TAIL_EXEC_TIMEOUT_MS = 10_000;
-/**
- * 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.
- */
-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`,
-        `pkill -TERM -s ${sid} >/dev/null 2>&1`,
-        `i=0; while [ "$i" -lt ${tries} ] && pgrep -s ${sid} >/dev/null 2>&1; do sleep 0.2; i=$((i+1)); done`,
-        "echo term",
-    ].join("\n");
-}
 /** How a task that exited by itself ends (spec §4.3): exit 137 past its deadline timed out. */
 export function exitedAs(task, code, now) {
     if (code === 0)

package/dist/catalog/catalog-content.d.ts

@@ -72,6 +72,11 @@ export interface OrgCatalogTemplate {
     editableEndpoint: string[];
     auth: Record<string, unknown>;
     ownership: "org" | "personal" | null;
+    /**
+     * The template file says `defaultEnabled: false`: it starts switched off in every org, so the
+     * install wizard does not ask for it (an org admin sets it up when switching it on).
+     */
+    defaultOff: boolean;
     /**
      * The template's setup guide in the item's latest version (`GET …/catalog/:itemId/guides/
      * :guideId`), null without one (spec 2026-11-09-setup-guides-v2-design.md §9.3).

package/dist/catalog/catalog-content.js

@@ -29,6 +29,7 @@ export function orgTemplateView(id, file, guide = null) {
         auth: t.auth,
         ownership: t.ownership ??
             (typeof t.auth.ownership === "string" ? t.auth.ownership : null),
+        defaultOff: file.defaultEnabled === false,
         guide,
     };
 }

package/dist/catalog/marketplaces.service.d.ts

@@ -188,7 +188,7 @@ export declare function headsToResolve(entries: readonly MarketplaceEntry[], imp
 /** The host versions (an entry's `minKernel` is judged against them). */
 export declare const HOST_VERSIONS: {
     readonly kernel: string;
-    readonly sdk: "0.1.0-rc.16";
+    readonly sdk: "0.1.0-rc.17";
 };
 /** Whether this deployment satisfies the entry's `minKernel`. */
 export declare const entryCompatible: (e: Pick<MarketplaceEntry, "minKernel">) => boolean;

package/dist/catalog/requests.service.js

@@ -201,7 +201,7 @@ let CatalogRequestsService = class CatalogRequestsService {
         const t = this.db;
         await this.orgLock.lockAndAuthorize(orgId, actor, "catalog.request");
         const hosts = [...new Set(input.hosts.map((h) => h.toLowerCase()))].sort();
-        const deployment = this.orgSettings.deployment().sandboxEgress;
+        const deployment = (await this.orgSettings.deployment()).sandboxEgress;
         if (deployment.mode === "none")
             throw deploymentEgressNone();
         const settings = await readOrgSettings(t, orgId);
@@ -621,7 +621,7 @@ let CatalogRequestsService = class CatalogRequestsService {
      */
     async approveNetwork(orgId, actor, requestId, detail, opts) {
         const hosts = detail?.hosts ?? [];
-        const deployment = this.orgSettings.deployment().sandboxEgress;
+        const deployment = (await this.orgSettings.deployment()).sandboxEgress;
         if (deployment.mode === "none")
             throw deploymentEgressNone();
         const current = (await readOrgSettings(this.db, orgId)).sandboxEgress;

package/dist/config/schema.d.ts

@@ -228,17 +228,17 @@ export declare const KernelConfigSchema: z.ZodObject<{
             devHosts: z.ZodDefault<z.ZodArray<z.ZodString>>;
         }, z.core.$strip>>;
         tiers: z.ZodPrefault<z.ZodObject<{
-            max: z.ZodDefault<z.ZodEnum<{
+            max: z.ZodOptional<z.ZodEnum<{
                 dev: "dev";
                 open: "open";
                 strict: "strict";
             }>>;
-            default: z.ZodDefault<z.ZodEnum<{
+            default: z.ZodOptional<z.ZodEnum<{
                 dev: "dev";
                 open: "open";
                 strict: "strict";
             }>>;
-            allowUnsandboxed: z.ZodDefault<z.ZodBoolean>;
+            allowUnsandboxed: z.ZodOptional<z.ZodBoolean>;
         }, z.core.$strip>>;
     }, z.core.$strip>>;
     devices: z.ZodPrefault<z.ZodObject<{

package/dist/config/schema.js

@@ -1246,27 +1246,29 @@ export const KernelConfigSchema = z.object({
             .object({
             max: z
                 .enum(["strict", "dev", "open"])
-                .default("dev")
+                .optional()
                 .meta(meta({
                 hot: true,
-                description: "Highest sandbox tier any organization may reach: strict (the allowlist only), dev (adds devHosts and local development affordances) or open (any public host); organizations and devices choose at most this",
+                description: "Highest sandbox tier any organization may reach: strict (the allowlist only), dev (adds devHosts and local development affordances) or open (any public host); organizations and devices choose at most this. Unset: the super admin's choice in the admin console, else dev; set here, it is read-only there",
             })),
             default: z
                 .enum(["strict", "dev", "open"])
-                .default("dev")
+                .optional()
                 .meta(meta({
                 hot: true,
-                description: "Sandbox tier of a device whose owner chose none, unless its organization sets its own default; at most sandbox.tiers.max",
+                description: "Sandbox tier of a device whose owner chose none, unless its organization sets its own default; at most sandbox.tiers.max. Unset: the super admin's choice in the admin console, else dev; set here, it is read-only there",
             })),
             allowUnsandboxed: z
                 .boolean()
-                .default(true)
+                .optional()
                 .meta(meta({
                 hot: true,
-                description: "Whether a local device may run commands without a sandbox (its owner's local choice); it only applies where the organization's ceiling is open, and an organization may forbid it",
+                description: "Whether a local device may run commands without a sandbox (its owner's local choice); it only applies where the organization's ceiling is open, and an organization may forbid it. Unset: the super admin's choice in the admin console, else true; set here, it is read-only there",
             })),
         })
-            .refine((t) => tierAtMost(t.default, t.max), {
+            // both set here: the default may not be above the max (a max from the admin console
+            // caps a default set here instead, see sandbox/platform-tiers.ts)
+            .refine((t) => t.default === undefined || t.max === undefined || tierAtMost(t.default, t.max), {
             message: "sandbox.tiers.default must not be above sandbox.tiers.max",
             path: ["default"],
         })

package/dist/devices/devices.service.js

@@ -29,7 +29,7 @@ import { readOrgSettings } from "../orgs/settings.service.js";
 import { SandboxJobs } from "../sandbox/jobs.js";
 import { isInternalProvider, LOCAL_PROVIDER, SandboxProviders } from "../sandbox/providers.js";
 import { deviceNotFound, SandboxService } from "../sandbox/sandbox.service.js";
-import { effectiveSandboxPolicy } from "../sandbox/tiers.js";
+import { effectiveSandboxPolicy, readDeploymentSandboxPolicy, } from "../sandbox/tiers.js";
 import { unattendedTierOf } from "../schedules/unattended.js";
 import { DeviceAccess, demotedProvider, deviceProvider, deviceUnavailable, inUseForDefault, } from "./access.js";
 /** How many recent sandbox changes a device view lists. */
@@ -293,7 +293,11 @@ let DevicesService = class DevicesService {
     }
     /** The org's sandbox policy for a device choosing `tier` (null: the org's default). */
     async policyFor(orgId, tier) {
-        return effectiveSandboxPolicy(this.config.get().sandbox, await readOrgSettings(this.db.db, orgId), tier);
+        const [deployment, settings] = await Promise.all([
+            readDeploymentSandboxPolicy(this.db.db, this.config),
+            readOrgSettings(this.db.db, orgId),
+        ]);
+        return effectiveSandboxPolicy(deployment, settings, tier);
     }
     /**
      * The sandbox level a sandbox call in the device runs at now, for the model (`device_paths`,
@@ -318,11 +322,12 @@ let DevicesService = class DevicesService {
             .executeTakeFirst();
         if (row === undefined)
             return null;
-        const [settings, unattended] = await Promise.all([
+        const [deployment, settings, unattended] = await Promise.all([
+            readDeploymentSandboxPolicy(this.db.db, this.config),
             readOrgSettings(this.db.db, orgId),
             runId === undefined ? null : unattendedTierOf(this.db.db, runId, deviceId),
         ]);
-        const policyOf = (tier) => effectiveSandboxPolicy(this.config.get().sandbox, settings, tier);
+        const policyOf = (tier) => effectiveSandboxPolicy(deployment, settings, tier);
         const summary = localPolicyOf(row.local_policy);
         const s = sandboxStateOf(policyOf, {
             source: row.source,
@@ -807,12 +812,13 @@ let DevicesService = class DevicesService {
         const demotedProviders = [
             ...new Set(rows.flatMap((r) => (demoted.get(r.id) ? [demoted.get(r.id)] : []))),
         ];
-        const [names, recent, settings] = await Promise.all([
+        const [names, recent, settings, deployment] = await Promise.all([
             this.displayNames.many(demotedProviders),
             this.recentSandboxChanges(orgId, rows.map((r) => r.id)),
             readOrgSettings(this.db.db, orgId),
+            readDeploymentSandboxPolicy(this.db.db, this.config),
         ]);
-        const policyOf = (tier) => effectiveSandboxPolicy(this.config.get().sandbox, settings, tier);
+        const policyOf = (tier) => effectiveSandboxPolicy(deployment, settings, tier);
         // each device's limits (a cloud device's own tier) and its instance's pending change
         const perDevice = new Map(await Promise.all(rows.map(async (r) => {
             const policy = policyOf(r.source === "cloud" ? r.tier : null);

package/dist/errors.d.ts

@@ -36,6 +36,10 @@ export declare const ERROR_CODES: {
     readonly "org.owner_required": 403;
     readonly "org.sandbox_egress_not_allowed": 400;
     readonly "org.sandbox_tier_not_allowed": 400;
+    /** A deployment setting set in the startup config (file, Nacos or env): read-only in the admin console. */
+    readonly "deployment.setting_readonly": 409;
+    /** Raising the platform's sandbox tiers through an API token or the Platform tool (only narrowing). */
+    readonly "deployment.sandbox_tier_not_allowed": 400;
     readonly "member.not_found": 404;
     readonly "member.already_exists": 409;
     readonly "member.anonymous_guest": 409;

package/dist/errors.js

@@ -36,6 +36,10 @@ export const ERROR_CODES = {
     "org.owner_required": 403,
     "org.sandbox_egress_not_allowed": 400,
     "org.sandbox_tier_not_allowed": 400,
+    /** A deployment setting set in the startup config (file, Nacos or env): read-only in the admin console. */
+    "deployment.setting_readonly": 409,
+    /** Raising the platform's sandbox tiers through an API token or the Platform tool (only narrowing). */
+    "deployment.sandbox_tier_not_allowed": 400,
     "member.not_found": 404,
     "member.already_exists": 409,
     "member.anonymous_guest": 409,