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

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/admin-catalog.controller.d.ts

@@ -21,7 +21,6 @@ declare const ConfirmBody: z.ZodObject<{
         optional: "optional";
     }>>;
     orgs: z.ZodOptional<z.ZodArray<z.ZodString>>;
-    pinnedSuggestions: z.ZodOptional<z.ZodArray<z.ZodString>>;
 }, z.core.$strict>;
 declare const ConfirmPermissionsBody: z.ZodObject<{
     permissionsHash: z.ZodString;
@@ -105,9 +104,8 @@ export declare class AdminCatalogController {
      * by sha256). An unknown field (the removed `deployExtension`) -> 400 `validation_failed`. A foreseeable failure (a downgrade to a version with
      * unrun migrations) is a 409 `extension.downgrade_unsupported` before anything is written.
      * Staging missing or expired -> 404 `plugin.staging_not_found`; `reviewHash` differs or the
-     * extension on the deployment changed -> 409 `plugin.review_stale`. `pinnedSuggestions` (skill
-     * names of the review) replaces the plugin's suggested pinning; an unknown name -> 400
-     * `validation_failed`.
+     * extension on the deployment changed -> 409 `plugin.review_stale`. The removed `pinnedSuggestions`
+     * is an unknown field (400 `validation_failed`).
      */
     confirm(principal: Principal, stagingId: string, body: z.infer<typeof ConfirmBody>): Promise<PluginConfirmResult>;
     /**

package/dist/catalog/admin-catalog.controller.js

@@ -31,8 +31,6 @@ const ConfirmBody = z
     /** The new item's scope (default `optional`); `orgs` only with `named`. */
     scope: Scope.optional(),
     orgs: Orgs.optional(),
-    /** Skill names suggested as pinned (spec §9.1); omitted keeps the plugin's flags. */
-    pinnedSuggestions: z.array(z.string().min(1).max(64)).max(50).optional(),
 })
     .strict();
 const ConfirmPermissionsBody = z.object({ permissionsHash: Hash }).strict();
@@ -160,9 +158,8 @@ let AdminCatalogController = class AdminCatalogController {
      * by sha256). An unknown field (the removed `deployExtension`) -> 400 `validation_failed`. A foreseeable failure (a downgrade to a version with
      * unrun migrations) is a 409 `extension.downgrade_unsupported` before anything is written.
      * Staging missing or expired -> 404 `plugin.staging_not_found`; `reviewHash` differs or the
-     * extension on the deployment changed -> 409 `plugin.review_stale`. `pinnedSuggestions` (skill
-     * names of the review) replaces the plugin's suggested pinning; an unknown name -> 400
-     * `validation_failed`.
+     * extension on the deployment changed -> 409 `plugin.review_stale`. The removed `pinnedSuggestions`
+     * is an unknown field (400 `validation_failed`).
      */
     confirm(principal, stagingId, body) {
         const actor = requireUser(principal);
@@ -170,7 +167,6 @@ let AdminCatalogController = class AdminCatalogController {
             reviewHash: body.reviewHash,
             ...(body.scope !== undefined && { scope: body.scope }),
             ...(body.orgs !== undefined && { orgs: body.orgs }),
-            ...(body.pinnedSuggestions !== undefined && { pinnedSuggestions: body.pinnedSuggestions }),
         }, actorOpts(actor));
     }
     /**

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/catalog.module.js

@@ -9,6 +9,7 @@ import { ExtensionsModule } from "../extensions/extensions.module.js";
 import { SuperAdminLockModule } from "../identity/super-admin.js";
 import { QueueModule } from "../infra/queue/queue.module.js";
 import { OrgLockModule } from "../orgs/org-lock.js";
+import { OrgSettingsModule } from "../orgs/settings.service.js";
 import { MAINTENANCE_QUEUE_NAME } from "../runtime/maintenance-queue.js";
 import { SkillsModule } from "../skills/skills.module.js";
 import { StorageModule } from "../storage/storage.module.js";
@@ -46,6 +47,8 @@ CatalogModule = __decorate([
             ExtensionsModule,
             SuperAdminLockModule,
             OrgLockModule,
+            // approving a network request writes the org's sandboxEgress
+            OrgSettingsModule,
             StorageModule,
             SkillsModule,
             ToolsModule,

package/dist/catalog/claude/report.d.ts

@@ -27,7 +27,14 @@ export type TranslationCode = "skill_imported" | "agent_imported"
 /** Phase D: a command that cannot become a skill (`detail.problem`). */
  | "command_invalid"
 /** Phase B only (agents were not imported); no longer emitted, kept for stored reports. */
- | "agent_needs_subagents" | "agent_invalid" | "agent_field_ignored" | "hooks_not_run" | "hooks_module" | "mcp_unsupported_transport" | "mcp_invalid" | "skill_invalid" | "not_applicable" | "unknown_field" | "other_harness" | "skill_ignored_restrictions" | "skill_claude_variables" | "session_start_pin_hint" | "mcp_auth_none" | "mcp_type_assumed" | "connector_not_loaded" | "agent_tools_unmapped"
+ | "agent_needs_subagents" | "agent_invalid" | "agent_field_ignored" | "hooks_not_run" | "hooks_module" | "mcp_unsupported_transport" | "mcp_invalid" | "skill_invalid" | "not_applicable" | "unknown_field" | "other_harness" | "skill_ignored_restrictions" | "skill_claude_variables"
+/**
+ * The plugin runs a SessionStart hook (Capybara runs no hooks; its skills are in every agent's
+ * catalog; skills default-on spec §8).
+ */
+ | "session_start_hook"
+/** Before skills default-on (the pinned suggestion); no longer emitted, kept for stored reports. */
+ | "session_start_pin_hint" | "mcp_auth_none" | "mcp_type_assumed" | "connector_not_loaded" | "agent_tools_unmapped"
 /** A pattern in `disallowedTools` disallows its whole tool (narrower, never wider). */
  | "agent_tools_narrowed" | "agent_skills_truncated"
 /** Phase D: the body has `!`command`` / ```! shell injections, which stay text. */
@@ -55,7 +62,7 @@ export interface TranslationReport {
     format: "claude-code";
     /** `.claude-plugin/plugin.json`, or null when the tree has none. */
     manifestPath: string | null;
-    /** The plugin has a SessionStart hook: the pinned suggestion is expanded by default (§8.4). */
+    /** The plugin has a SessionStart hook (the report then has a `session_start_hook` item). */
     sessionStart: boolean;
     /** Items sorted by group order, then component, then name. At most {@link CLAUDE_REPORT_MAX_ITEMS} (then one "unknown_field" item named "…" with detail { more: n }). */
     items: TranslationItem[];

package/dist/catalog/claude/report.js

@@ -42,6 +42,7 @@ export const TRANSLATION_CODE_GROUP = {
     other_harness: "ignored",
     skill_ignored_restrictions: "warnings",
     skill_claude_variables: "warnings",
+    session_start_hook: "warnings",
     session_start_pin_hint: "warnings",
     mcp_auth_none: "warnings",
     mcp_type_assumed: "warnings",

package/dist/catalog/claude/translate.js

@@ -702,7 +702,7 @@ export function translateClaudePlugin(files, o) {
         add(item("hooks_not_run", "hook", "…", { detail: { more: moreHooks } }));
     const sessionStart = events.has("SessionStart");
     if (sessionStart)
-        add(item("session_start_pin_hint", "hook", "SessionStart"));
+        add(item("session_start_hook", "hook", "SessionStart"));
     // MCP servers: .mcp.json first, then each declaration; a later name replaces an earlier one.
     // A Map: an untrusted "__proto__" key must never touch an object's prototype.
     const servers = new Map();

package/dist/catalog/component-promotion.js

@@ -172,7 +172,7 @@ let ComponentPromotion = class ComponentPromotion {
         if (p.kind === "skill") {
             const v = await this.db
                 .selectFrom("skill_versions")
-                .select(["manifest", "source_format", "suggest_pinned", "created_by"])
+                .select(["manifest", "source_format", "created_by"])
                 .where("skill_id", "=", row.id)
                 .where("version", "=", row.version)
                 .executeTakeFirstOrThrow();
@@ -198,7 +198,6 @@ let ComponentPromotion = class ComponentPromotion {
                 object_prefix: p.prefix,
                 catalog_version: null,
                 source_format: v.source_format,
-                suggest_pinned: v.suggest_pinned,
                 created_by: v.created_by,
             })
                 .execute();

package/dist/catalog/component-state.d.ts

@@ -110,6 +110,15 @@ export declare function loadScopeState(db: KernelSchemaDb, kind: ComponentKind,
     id: string;
     itemId: string | null;
 }[]): Promise<ScopeState>;
+/**
+ * Whether a catalog item is builtin: marked so and owned by the platform. An org-owned item marked
+ * builtin (never so in practice) is an ordinary item: never on without an install, never locked,
+ * and its skills can be turned off (skills default-on spec §3).
+ */
+export declare const platformBuiltin: (item: {
+    builtin: boolean | null;
+    owner_org_id: string | null;
+}) => boolean;
 /** The plugin facts of `itemId` for one org from a {@link ScopeState} (null: no plugin). */
 export declare function pluginFactsOf(st: ScopeState, itemId: string | null, orgId: string): PluginFacts | null;
 /** The org's switch of a component from a {@link ScopeState}. */
@@ -123,7 +132,10 @@ export interface DefinitionRefs {
      * one of `orgConnectors` it does not turn off as a whole.
      */
     connectors: Set<string>;
-    /** `skills.orgSkills`, `skills.pinned` and the inline sub-agent templates' `skills`. */
+    /**
+     * The skills the agent names: the inline sub-agent templates' `skills`. Having a skill on by
+     * default is not using it (skills default-on spec §11), so a plugin update can remove it.
+     */
     skills: Set<string>;
     /** `subagents.templates`. */
     templates: Set<string>;

package/dist/catalog/component-state.js

@@ -193,12 +193,17 @@ export async function loadScopeState(db, kind, comps) {
     if (itemIds.length > 0) {
         const items = await db
             .selectFrom("catalog_items")
-            .select(["id", "scope", "builtin", "disabled"])
+            .select(["id", "scope", "builtin", "disabled", "owner_org_id"])
             .where("id", "in", itemIds)
             .where("deleted_at", "is", null)
             .execute();
-        for (const i of items)
-            state.plugins.set(i.id, i);
+        for (const i of items) {
+            state.plugins.set(i.id, {
+                scope: i.scope,
+                builtin: platformBuiltin(i),
+                disabled: i.disabled,
+            });
+        }
         const listed = await db
             .selectFrom("catalog_item_scope_orgs")
             .select(["item_id", "org_id"])
@@ -235,6 +240,12 @@ export async function loadScopeState(db, kind, comps) {
     }
     return state;
 }
+/**
+ * Whether a catalog item is builtin: marked so and owned by the platform. An org-owned item marked
+ * builtin (never so in practice) is an ordinary item: never on without an install, never locked,
+ * and its skills can be turned off (skills default-on spec §3).
+ */
+export const platformBuiltin = (item) => item.builtin === true && item.owner_org_id === null;
 /** The plugin facts of `itemId` for one org from a {@link ScopeState} (null: no plugin). */
 export function pluginFactsOf(st, itemId, orgId) {
     if (itemId === null)
@@ -287,8 +298,6 @@ export function definitionRefs(definition, orgConnectors = []) {
                 if (typeof x === "string")
                     into.add(x);
     };
-    strings(def?.skills?.orgSkills, skills);
-    strings(def?.skills?.pinned, skills);
     const inline = def?.subagents?.inline;
     if (Array.isArray(inline))
         for (const t of inline)

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.15";
+    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/marketplaces.service.js

@@ -31,6 +31,7 @@ import { expandGitUrl, GitSourceError, gitErrorDetails, gitLocationIdentity, git
 import { CatalogSourceLock } from "./locks.js";
 import { fetchMarketplaceManifest, MarketplaceFetchError, MarketplaceInvalidError, marketplaceNetPolicy, marketplaceUrlProblem, } from "./marketplace-fetch.js";
 import { checkMarketplaceIcon, fetchMarketplaceIcon, gitIconPaths, MARKETPLACE_ICON_CONCURRENCY, MARKETPLACE_ICON_FETCHES_MAX, MARKETPLACE_ICON_MAX_BYTES, MARKETPLACE_ICON_RETRY_MS, marketplaceIconUrl, wantedIcons, } from "./marketplace-icons.js";
+import { withoutRemovedManifestFields } from "./plugin-package.js";
 import { compareVersions, newestFirst, sameRelease } from "./versions.js";
 /** 官方清单来源的 id。 */
 export const OFFICIAL_MARKETPLACE_ID = "official";
@@ -925,7 +926,7 @@ let MarketplacesService = class MarketplacesService {
             const pj = files.get(PLUGIN_MANIFEST_FILE);
             let entry;
             if (pj !== undefined) {
-                const m = parsePluginManifest(dec(pj));
+                const m = parsePluginManifest(withoutRemovedManifestFields(dec(pj)));
                 if ("errors" in m) {
                     throw new MarketplaceInvalidError(`the repository is a single plugin, but its ${PLUGIN_MANIFEST_FILE} is invalid: ${m.errors.slice(0, 5).join("; ")}`, m.errors);
                 }

package/dist/catalog/org-catalog.controller.d.ts

@@ -7,7 +7,7 @@ import { type OrgContext } from "../orgs/org.guard.js";
 import type { ConnectorDetail, ToolIssue } from "../tools/connectors.service.js";
 import type { MarketplaceImportResult } from "./catalog.service.js";
 import type { CatalogIcon, OrgCatalogDetail, OrgCatalogItem, OrgInstallResult } from "./catalog-content.js";
-import { CatalogGuideQuery, CatalogMarketplaceRequestBody, CatalogRequestBody, CatalogRequestsListQuery, OrgPluginInstallBody, OrgPluginSwitchBody } from "./org-catalog.schemas.js";
+import { CatalogGuideQuery, CatalogMarketplaceRequestBody, CatalogRequestBody, CatalogRequestsListQuery, NetworkRequestBody, OrgPluginInstallBody, OrgPluginSwitchBody } from "./org-catalog.schemas.js";
 import { OrgCatalogService } from "./org-catalog.service.js";
 import { PluginInstaller, type PluginInstallView, type UninstallPreview, type UninstallReport } from "./plugin-install.js";
 import { CatalogRequestsService, type CatalogRequestView } from "./requests.service.js";
@@ -57,6 +57,8 @@ declare const DecideBody: z.ZodObject<{
  * - `POST catalog/:itemId/requests` (`catalog.request`; `access` needs an org admin): requests
  *   under plugin scope (spec §5.1), `enable` into the org admins' inbox, `access` to the super
  *   admin; `POST marketplace-requests` (org admins): an `import` request for a marketplace entry;
+ * - `POST catalog-requests/network` (`catalog.request`, web sessions only): a member asks the org
+ *   admins to allow hosts in the org's sandbox network (network ask-to-allow spec §5.3);
  * - `PUT catalog/:itemId/switch` (scope phase 1): `{ enabled: true, inputs? }` installs -> 200 `{ item }`;
  *   `{ enabled: false, confirm? }` -> 200 `{ preview, confirm }`, then with the hash 200 `{ item }`;
  * - `POST catalog/:itemId/install` (an alias of switching on, no longer creates requests): the route only requires `catalog.read`; the service re-checks
@@ -69,8 +71,8 @@ declare const DecideBody: z.ZodObject<{
  *   admin (`PUT /admin/catalog/items/:id/update`, ruling F2);
  * - `POST connector-templates/:templateId/connectors` (`connectors.manage`): one more connector
  *   from a platform connector template on in the org (ruling P4-T6-8);
- * - `POST catalog-requests/:id/decide` (`catalog.decide`, org admins; `enable` and
- *   `connector_setup` requests, `{ approve, reason? }`; a `connector_setup` request is only
+ * - `POST catalog-requests/:id/decide` (`catalog.decide`, org admins; `enable`,
+ *   `network_allowlist` and `connector_setup` requests, `{ approve, reason? }`; a `connector_setup` request is only
  *   rejected here, ruling P4-T6-6), `POST catalog-requests/:id/dismiss` (the requester, a decided
  *   request).
  */
@@ -156,6 +158,14 @@ export declare class OrgCatalogController {
         installs: PluginInstallView[];
     }>;
     uninstall(principal: Principal, org: OrgContext, installId: string): Promise<UninstallReport>;
+    /**
+     * A member asks the org admins to allow hosts in the org's sandbox egress (from a blocked
+     * command's card) -> 201 `{ request }` (an identical pending request of the member is returned).
+     * Web sessions only: a personal token, a service token or an agent never files one.
+     */
+    networkRequest(principal: Principal, org: OrgContext, body: z.infer<typeof NetworkRequestBody>): Promise<{
+        request: CatalogRequestView;
+    }>;
     decide(principal: Principal, org: OrgContext, id: string, body: z.infer<typeof DecideBody>): Promise<{
         request: CatalogRequestView;
     }>;