@sema-agent/settings-schema 14.5.0 → 14.7.0

package/dist/sandbox-git.d.ts

@@ -0,0 +1,64 @@
+/**
+ * 沙箱 git 平面的 **origin 形** 与 **有效配置块 `sandboxGit`**(14.7.0)。纯、浏览器安全。
+ *
+ * ## 律(一条)
+ * **一个 origin 就是它自己的 WHATWG origin**:串等于 `new URL(串).origin`,且 scheme ∈ {http, https}。规范形 ——
+ * 小写 host、去缺省端口(https 的 443、http 的 80)、无尾斜杠、无 userinfo / 路径 / 查询 / 片段 —— 不是一张手写规则表,而是这一个等式的推论:
+ * 凡 WHATWG 会改写的串(大写、缺省端口、IPv4 简写、百分号编码的 host、串内制表符、前后空白、反斜杠……)都不等于自己的 origin,所以都不是规范形。
+ * 判官只有 {@link isSandboxGitOrigin} 一只;请求体的 `origins`、应答行的 `origin`、有效配置块的 `origin` 全读它(经 {@link SandboxGitOrigin})。
+ * 「这个串是不是 http(s) URL」归包内唯一的 URL 形判官 `httpUrlFlaws`(`./url-shape`),本模块只加「等于自己的 origin」这一格。
+ * origin 不表达子路径部署(`https://host/gitea` 不是 origin)—— 规范化器不存在:把带路径的串静默削成 origin 会把凭据送到运维没写的地方。
+ *
+ * ## 有效配置块 `sandboxGit`
+ * `/effective` 载荷上的**非域顶层键**(web-admin 按部署登记册投影,不是存储域):可选、无默认 —— 缺席 = 这个部署没有投影这一块。
+ * `readEffectiveWire` 对它走 open-world 逐字承运(从不校验、从不丢,`EffectiveWire.sandboxGit` 是 `unknown`);**判它的座位只有 {@link SandboxGitConfig}**,由消费方在用之前判。
+ *
+ *  · `origins[i].origin` —— 本部署代理哪些 origin(规范形,见上);≤ {@link SANDBOX_GIT_MAX_ORIGINS} 项、两两不同。
+ *  · `origins[i].connectUrl` —— 控制台「连接 Gitea(git)」页的绝对 https URL(非秘密:{@link SandboxGitConnectUrl})。
+ *
+ * 🔴 **块里 http origin 可读**:它为什么送不出凭据(传输不加密)是逐 origin 应答里的一个词(`insecure_transport`,`./api/credentials` 的判定序表第 1 行)
+ * 与能力读数里的一个词,不是块的校验拒。块若因一个 http origin 整块不可读,同块里的 https origin 一并失效,「逐 origin 说拒因」就无从谈起;
+ * http origin 只配路由、永不取值,是消费方的事。
+ *
+ * 解析剥未知键(与 `SessionMirrorPolicy` 同律:加字段恒为加性)。
+ */
+import { z } from "zod";
+/** 一次最多代理的 origin 数(请求体、应答、有效配置块同一个上界)。 */
+export declare const SANDBOX_GIT_MAX_ORIGINS = 16;
+/**
+ * 判:`raw` 是不是规范形的 http(s) origin。合格 ⇔ 它是层级式 http(s) URL 且**逐字等于**自己的 WHATWG origin。
+ * 纯函数、不抛;非串由 {@link SandboxGitOrigin} 的 zod 形先拒。
+ */
+export declare function isSandboxGitOrigin(raw: string): boolean;
+/** 一个规范形的 origin(`scheme://host[:port]`,scheme ∈ {http, https})。判官 {@link isSandboxGitOrigin};拒句是定句,不回显值。 */
+export declare const SandboxGitOrigin: z.ZodString;
+export type SandboxGitOrigin = z.infer<typeof SandboxGitOrigin>;
+/**
+ * 一张 origin 表:每项是规范形、两两不同、至多 {@link SANDBOX_GIT_MAX_ORIGINS} 项。**空表合法**(有效配置块可以没有 origin);要求至少一项的座位(申领请求)自己 `.min(1)`。
+ * 重复的那一项被点名(坐标 = 第二次出现的下标)。
+ */
+export declare const SandboxGitOriginList: z.ZodArray<z.ZodString>;
+export type SandboxGitOriginList = z.infer<typeof SandboxGitOriginList>;
+/**
+ * 控制台「连接 Gitea(git)」页的绝对 URL:**https**,且是 {@link NON_SECRET_URL_NO_MIGRATION} 那一类(层级式 URL、无 userinfo、无片段、路径与查询里没有秘密形的值)。
+ * 它是 wire 输入,不是存量文档里的值,所以走「无迁移指路」那一只。
+ */
+export declare const SandboxGitConnectUrl: z.ZodString;
+export type SandboxGitConnectUrl = z.infer<typeof SandboxGitConnectUrl>;
+/** 有效配置块里的一个 origin 条目。 */
+export declare const SandboxGitOriginEntry: z.ZodObject<{
+    origin: z.ZodString;
+    connectUrl: z.ZodString;
+}, z.core.$strip>;
+export type SandboxGitOriginEntry = z.infer<typeof SandboxGitOriginEntry>;
+/**
+ * 有效配置块 `sandboxGit`(`/effective` 载荷的非域顶层键,可选、无默认)。判它的**唯一座位**:消费方在用之前对 `wire.sandboxGit` 跑 `safeParse`。
+ * `origins` ≤ {@link SANDBOX_GIT_MAX_ORIGINS} 项,按 `origin` 两两不同(重复的那一项的 `origin` 字段被点名);空表合法。
+ */
+export declare const SandboxGitConfig: z.ZodObject<{
+    origins: z.ZodArray<z.ZodObject<{
+        origin: z.ZodString;
+        connectUrl: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type SandboxGitConfig = z.infer<typeof SandboxGitConfig>;

package/dist/sandbox-git.js

@@ -0,0 +1,89 @@
+/**
+ * 沙箱 git 平面的 **origin 形** 与 **有效配置块 `sandboxGit`**(14.7.0)。纯、浏览器安全。
+ *
+ * ## 律(一条)
+ * **一个 origin 就是它自己的 WHATWG origin**:串等于 `new URL(串).origin`,且 scheme ∈ {http, https}。规范形 ——
+ * 小写 host、去缺省端口(https 的 443、http 的 80)、无尾斜杠、无 userinfo / 路径 / 查询 / 片段 —— 不是一张手写规则表,而是这一个等式的推论:
+ * 凡 WHATWG 会改写的串(大写、缺省端口、IPv4 简写、百分号编码的 host、串内制表符、前后空白、反斜杠……)都不等于自己的 origin,所以都不是规范形。
+ * 判官只有 {@link isSandboxGitOrigin} 一只;请求体的 `origins`、应答行的 `origin`、有效配置块的 `origin` 全读它(经 {@link SandboxGitOrigin})。
+ * 「这个串是不是 http(s) URL」归包内唯一的 URL 形判官 `httpUrlFlaws`(`./url-shape`),本模块只加「等于自己的 origin」这一格。
+ * origin 不表达子路径部署(`https://host/gitea` 不是 origin)—— 规范化器不存在:把带路径的串静默削成 origin 会把凭据送到运维没写的地方。
+ *
+ * ## 有效配置块 `sandboxGit`
+ * `/effective` 载荷上的**非域顶层键**(web-admin 按部署登记册投影,不是存储域):可选、无默认 —— 缺席 = 这个部署没有投影这一块。
+ * `readEffectiveWire` 对它走 open-world 逐字承运(从不校验、从不丢,`EffectiveWire.sandboxGit` 是 `unknown`);**判它的座位只有 {@link SandboxGitConfig}**,由消费方在用之前判。
+ *
+ *  · `origins[i].origin` —— 本部署代理哪些 origin(规范形,见上);≤ {@link SANDBOX_GIT_MAX_ORIGINS} 项、两两不同。
+ *  · `origins[i].connectUrl` —— 控制台「连接 Gitea(git)」页的绝对 https URL(非秘密:{@link SandboxGitConnectUrl})。
+ *
+ * 🔴 **块里 http origin 可读**:它为什么送不出凭据(传输不加密)是逐 origin 应答里的一个词(`insecure_transport`,`./api/credentials` 的判定序表第 1 行)
+ * 与能力读数里的一个词,不是块的校验拒。块若因一个 http origin 整块不可读,同块里的 https origin 一并失效,「逐 origin 说拒因」就无从谈起;
+ * http origin 只配路由、永不取值,是消费方的事。
+ *
+ * 解析剥未知键(与 `SessionMirrorPolicy` 同律:加字段恒为加性)。
+ */
+import { z } from "zod";
+import { buildQuotedIssue } from "./quoted-issue.js";
+import { NON_SECRET_URL_NO_MIGRATION } from "./types.js";
+import { httpUrlFlaws } from "./url-shape.js";
+/** 一次最多代理的 origin 数(请求体、应答、有效配置块同一个上界)。 */
+export const SANDBOX_GIT_MAX_ORIGINS = 16;
+/**
+ * 判:`raw` 是不是规范形的 http(s) origin。合格 ⇔ 它是层级式 http(s) URL 且**逐字等于**自己的 WHATWG origin。
+ * 纯函数、不抛;非串由 {@link SandboxGitOrigin} 的 zod 形先拒。
+ */
+export function isSandboxGitOrigin(raw) {
+    if (httpUrlFlaws(raw, []).length > 0)
+        return false;
+    return new URL(raw).origin === raw;
+}
+/** 一个规范形的 origin(`scheme://host[:port]`,scheme ∈ {http, https})。判官 {@link isSandboxGitOrigin};拒句是定句,不回显值。 */
+export const SandboxGitOrigin = z
+    .string()
+    .refine(isSandboxGitOrigin, buildQuotedIssue `must be a canonical http(s) origin — scheme://host[:port] equal to its own WHATWG origin: lowercase host, no default port, no userinfo, path, query, fragment or trailing slash`);
+/** 给定下标的 origin 在它之前已经出现过 ⇒ 下标。重复判在**规范形**之上(两个都是规范形的串,相等即同一个 origin)。 */
+function repeatedAt(origins) {
+    const seen = new Set();
+    const repeats = [];
+    origins.forEach((o, i) => {
+        if (seen.has(o))
+            repeats.push(i);
+        seen.add(o);
+    });
+    return repeats;
+}
+/**
+ * 一张 origin 表:每项是规范形、两两不同、至多 {@link SANDBOX_GIT_MAX_ORIGINS} 项。**空表合法**(有效配置块可以没有 origin);要求至少一项的座位(申领请求)自己 `.min(1)`。
+ * 重复的那一项被点名(坐标 = 第二次出现的下标)。
+ */
+export const SandboxGitOriginList = z
+    .array(SandboxGitOrigin)
+    .max(SANDBOX_GIT_MAX_ORIGINS)
+    .superRefine((origins, ctx) => {
+    for (const i of repeatedAt(origins))
+        ctx.addIssue({ code: "custom", ...buildQuotedIssue `duplicate origin`, path: [i] });
+});
+/**
+ * 控制台「连接 Gitea(git)」页的绝对 URL:**https**,且是 {@link NON_SECRET_URL_NO_MIGRATION} 那一类(层级式 URL、无 userinfo、无片段、路径与查询里没有秘密形的值)。
+ * 它是 wire 输入,不是存量文档里的值,所以走「无迁移指路」那一只。
+ */
+export const SandboxGitConnectUrl = NON_SECRET_URL_NO_MIGRATION.refine((u) => URL.canParse(u) && new URL(u).protocol === "https:", buildQuotedIssue `must be an https URL — the connect page is opened by a person and carries their session`);
+/** 有效配置块里的一个 origin 条目。 */
+export const SandboxGitOriginEntry = z.object({
+    /** 本部署代理的 origin(规范形)。http 在这里可读(见模块头注)。 */
+    origin: SandboxGitOrigin,
+    /** 该 origin 的「连接」页,绝对 https URL。 */
+    connectUrl: SandboxGitConnectUrl,
+});
+/**
+ * 有效配置块 `sandboxGit`(`/effective` 载荷的非域顶层键,可选、无默认)。判它的**唯一座位**:消费方在用之前对 `wire.sandboxGit` 跑 `safeParse`。
+ * `origins` ≤ {@link SANDBOX_GIT_MAX_ORIGINS} 项,按 `origin` 两两不同(重复的那一项的 `origin` 字段被点名);空表合法。
+ */
+export const SandboxGitConfig = z
+    .object({
+    origins: z.array(SandboxGitOriginEntry).max(SANDBOX_GIT_MAX_ORIGINS),
+})
+    .superRefine((block, ctx) => {
+    for (const i of repeatedAt(block.origins.map((e) => e.origin)))
+        ctx.addIssue({ code: "custom", ...buildQuotedIssue `duplicate origin`, path: ["origins", i, "origin"] });
+});

package/dist/scheduler-store.js

@@ -1,21 +1,30 @@
+import { ownDeclaredValueOf } from './own-key-read.js';
+import { isJsonArray, isPlainJsonObject } from './plain-json-object.js';
 import { isSessionLifetime } from './scheduler-lifetime.js';
 import { migrateSchedulerRecords } from './scheduler-store-migration.js';
 /** Structural validation of one record (required fields + a well-formed `when`). Unknown fields are allowed. */
 export function isSchedulerRecord(v) {
-    if (typeof v !== 'object' || v === null)
+    if (!isPlainJsonObject(v))
         return false;
-    const r = v;
-    if (typeof r.id !== 'string' || typeof r.scope !== 'string' || typeof r.prompt !== 'string' || typeof r.createdMs !== 'number')
+    // a type guard, so every field is read STRICTLY from the record's own keys (own, enumerable, data — the kernel's `ownDeclaredValueOf`): an inherited field is absent
+    // (a polluted `Object.prototype.prompt` is not a prompt the record carries); an accessor / hidden field, or one that cannot be read ⇒ not a record — no getter is called,
+    // so what the caller reads from the record next is what was judged
+    const field = (o, key) => {
+        const read = ownDeclaredValueOf(o, key);
+        return read.ok ? read.value : undefined;
+    };
+    if (typeof field(v, 'id') !== 'string' || typeof field(v, 'scope') !== 'string' || typeof field(v, 'prompt') !== 'string' || typeof field(v, 'createdMs') !== 'number')
         return false;
-    const w = r.when;
-    if (typeof w !== 'object' || w === null)
+    const w = field(v, 'when');
+    if (!isPlainJsonObject(w))
         return false;
-    if (w.kind === 'cron')
-        return typeof w.expr === 'string';
-    if (w.kind === 'at')
-        return typeof w.atMs === 'number';
-    if (w.kind === 'delay')
-        return typeof w.delaySec === 'number';
+    const kind = field(w, 'kind');
+    if (kind === 'cron')
+        return typeof field(w, 'expr') === 'string';
+    if (kind === 'at')
+        return typeof field(w, 'atMs') === 'number';
+    if (kind === 'delay')
+        return typeof field(w, 'delaySec') === 'number';
     return false;
 }
 /** 一条会话链上的记录过期多久算「永驻孤儿」:`lifetime: "session"` ∧ `sessionId` 在场 ∧ `nextRunMs` 已过去这么久 ⇒ 读口丢弃并告警(7 天)。 */
@@ -37,7 +46,7 @@ export function parseSchedulerStore(text, opts) {
     catch {
         return { records: [], warnings: [{ kind: 'unreadable-file', why: 'not-json' }] };
     }
-    if (!Array.isArray(parsed))
+    if (!isJsonArray(parsed))
         return { records: [], warnings: [{ kind: 'unreadable-file', why: 'not-an-array' }] };
     const warnings = [];
     const kept = [];

package/dist/settings-units.d.ts

@@ -0,0 +1,85 @@
+import { type TightenRule } from "./safety-merge-spec.js";
+/** The settings-document units (see the file header). `path` is the unit's place in a settings document. */
+export declare const SETTINGS_UNITS: {
+    readonly permissions: {
+        readonly path: readonly ["permissions"];
+        readonly category: "permissions";
+        readonly reads: "members";
+    };
+    readonly permissionMode: {
+        readonly path: readonly ["permissions", "defaultMode"];
+        readonly category: "permissionMode";
+        readonly reads: "whole";
+        readonly reading: "permissionMode";
+    };
+    readonly additionalDirectories: {
+        readonly path: readonly ["permissions", "additionalDirectories"];
+        readonly category: "sandboxNetwork";
+        readonly reads: "whole";
+        readonly reading: "stringList";
+    };
+    readonly sandbox: {
+        readonly path: readonly ["sandbox"];
+        readonly category: "sandboxNetwork";
+        readonly reads: "members";
+    };
+    readonly disableBypassPermissionsMode: {
+        readonly path: readonly ["permissions", "disableBypassPermissionsMode"];
+        readonly category: "killSwitches";
+        readonly reads: "member";
+        readonly member: "disableBypassPermissionsMode";
+        readonly reading: "killSwitch";
+    };
+    readonly disableAutoMode: {
+        readonly path: readonly ["permissions", "disableAutoMode"];
+        readonly category: "killSwitches";
+        readonly reads: "member";
+        readonly member: "disableAutoMode";
+        readonly reading: "killSwitch";
+    };
+    readonly hooks: {
+        readonly path: readonly ["hooks"];
+        readonly category: "hooks";
+        readonly reads: "whole";
+        readonly reading: "hooks";
+    };
+    readonly env: {
+        readonly path: readonly ["env"];
+        readonly category: "env";
+        readonly reads: "whole";
+        readonly reading: "envMap";
+    };
+    readonly model: {
+        readonly path: readonly ["model"];
+        readonly category: "model";
+        readonly reads: "whole";
+        readonly reading: "nonEmptyString";
+    };
+    readonly outputStyle: {
+        readonly path: readonly ["outputStyle"];
+        readonly category: "ui";
+        readonly reads: "whole";
+        readonly reading: "nonEmptyString";
+    };
+};
+export type SettingsUnitName = keyof typeof SETTINGS_UNITS;
+/** The comparator of one unit — or, for a `members` unit, of one DECLARED member of it: `whole` ⇒ the category's `tighten`;
+ *  `member` ⇒ that member's comparator; `members` ⇒ the named member's comparator ({@link resolveMemberTighten}). Compare two values
+ *  with `tightenVerdict`. A `members` unit without a member (its whole value), an undeclared member (e.g. `sandbox`'s
+ *  `failIfUnavailable`), a `whole` unit given a member, a `member` unit given another one, an unknown unit ⇒ RangeError. */
+export declare function unitTighten(unit: SettingsUnitName, member?: string): TightenRule;
+/**
+ * Read one unit's raw value out of a settings document (14.6.0) — the settings half of "how an existing value is normalized
+ * before it is compared". The reading of every unit is the file header's table; anything outside it is `unreadable`, and
+ * `undefined` / `null` are `unreadable` for every unit. An accepted value is returned as is (same reference) — the only rewrites
+ * are `"manual"` ⇒ `"default"` (permissionMode) and `"disable"` ⇒ `true` (kill-switches); `"bypassPermissions"` is `launch_only`.
+ * The last step of every reading is the unit comparator's own domain: whatever reads, compares (file header).
+ * Addressing is {@link unitTighten}'s (same RangeErrors: a `members` unit needs a declared member, …).
+ */
+export declare function readSettingsUnit(unit: SettingsUnitName, raw: unknown, member?: string): {
+    readonly ok: true;
+    readonly value: unknown;
+} | {
+    readonly ok: false;
+    readonly reason: "unreadable" | "launch_only";
+};

package/dist/settings-units.js

@@ -0,0 +1,177 @@
+/**
+ * SETTINGS UNITS (14.6.0) — the settings-document unit table: which keys of a settings file carry a merge contract, where each
+ * sits in the document, which {@link SAFETY_MERGE_SPEC} category it maps into, and how its raw value READS. Every resolver of a
+ * settings file (the shell reads it for each of its sources; a profile loader is a second projection) reads THIS table instead of
+ * keeping a key→category map of its own for these ten units. Unit names are the shell's established ten; the two permission-mode
+ * kill-switches map to their own `killSwitches` member rows (the table has no managed-only floor for them).
+ *
+ * NOT in this table: the two http-hook allowlist keys (`allowedHttpHookUrls` / `httpHookAllowedEnvVars`). They carry a merge contract
+ * too (the `httpHookAllowlists` category of {@link SAFETY_MERGE_SPEC}) but are keyed and read by `./http-hook-allowlists` on its own
+ * (`HTTP_HOOK_ALLOWLIST_KEYS`, `readHttpHookAllowlistLayer`), and read a malformed value differently: there it is `[]` plus a
+ * `malformed` mark (the failure direction is "no hook may run"), while a unit reading answers `unreadable`. Folding the two tables
+ * into one is a design question (which reading is right), not a drive-by — until it is settled a consumer that wants the allowlist
+ * layers reads that module, not this table.
+ *
+ * How a unit is addressed (`reads`):
+ *  · `whole`   — the unit's value is one value under its category: compared by the category's `tighten`
+ *                (the only thing a category's `tighten` answers — safety-merge-spec header);
+ *  · `member`  — the unit IS one declared member of its category (the two kill-switches): compared by that member's comparator;
+ *  · `members` — the unit is an object of declared members (`permissions`, `sandbox`): every question names ONE declared member,
+ *                compared and read by that member's row ({@link memberTighten}; its value class `boolPole` / `list`). The unit's whole
+ *                value and its undeclared members have no comparator and no reading here — asking is a RangeError.
+ *
+ * How a unit READS (`reading`, on every `whole` / `member` row; a `members` unit reads each member by the member row's value class):
+ *  · `stringList`     — an array whose every element is a non-empty string (`[]` reads); a bare string is NOT wrapped into an array;
+ *  · `permissionMode` — a word of the `permissionMode` category's order other than `bypassPermissions`; `"manual"` reads as
+ *                       `"default"` (the alias); `"bypassPermissions"` is `launch_only` — a launch flag, never a settings-file value;
+ *  · `killSwitch`     — a boolean; `"disable"` (CC's spelling of ON) reads as `true`; `false` is the loose pole — a value, not absence;
+ *  · `hooks`          — what the one hooks judge (`classifyHooksConfig`) classifies as `loaded`;
+ *  · `envMap`         — a plain object whose keys are non-empty and whose values are all strings;
+ *  · `nonEmptyString` — a non-empty string;
+ *  and a member's value class: `boolPole` ⇒ a boolean, `list` ⇒ the `stringList` reading.
+ * Everything else is `unreadable` — no default arm. Two laws for every unit: `undefined` and JSON `null` are `unreadable` (absence
+ * is not a value; "an absent landing spot takes the write" is the loader's business, before it calls the reader), and the reader
+ * only recognizes a shape, never rewrites it — an accepted value comes back as the same reference; the only rewrites are the two
+ * spellings above (`"manual"` ⇒ `"default"`, `"disable"` ⇒ `true`).
+ * WHATEVER READS, COMPARES: a reading has two halves — its shape / spelling half (the table above) and, as its last step, the
+ * unit comparator's OWN domain (`tightenVerdict(unitTighten(unit, member), value, value)` must be `equal`). The domain has one
+ * owner, the comparator; a reading only adds what it needs on top (non-empty list elements, the hooks judge, …). So a value the
+ * shape half accepts but the comparator cannot place — a hooks document the hooks judge loads while a key it strips hides data
+ * nested deeper than `MAX_HASH_DEPTH`, or an `undefined` — is `unreadable`, never "read but not comparable".
+ * The env DOCUMENT's literal grammar (boolean words, csv + empty-set sentinel, a "≤ 0 means off" cap) is not here: it belongs to
+ * the engine's env catalog, whose one implementation is the server's.
+ */
+import { classifyHooksConfig } from "./hooks-config.js";
+import { captureJson, captureStringArray, ownEntriesOf } from "./own-key-read.js";
+import { isPlainJsonObject } from "./plain-json-object.js";
+import { SAFETY_MERGE_SPEC, resolveMemberTighten, tightenVerdict } from "./safety-merge-spec.js";
+/** The settings-document units (see the file header). `path` is the unit's place in a settings document. */
+export const SETTINGS_UNITS = {
+    permissions: { path: ["permissions"], category: "permissions", reads: "members" },
+    permissionMode: { path: ["permissions", "defaultMode"], category: "permissionMode", reads: "whole", reading: "permissionMode" },
+    additionalDirectories: { path: ["permissions", "additionalDirectories"], category: "sandboxNetwork", reads: "whole", reading: "stringList" },
+    sandbox: { path: ["sandbox"], category: "sandboxNetwork", reads: "members" },
+    disableBypassPermissionsMode: { path: ["permissions", "disableBypassPermissionsMode"], category: "killSwitches", reads: "member", member: "disableBypassPermissionsMode", reading: "killSwitch" },
+    disableAutoMode: { path: ["permissions", "disableAutoMode"], category: "killSwitches", reads: "member", member: "disableAutoMode", reading: "killSwitch" },
+    hooks: { path: ["hooks"], category: "hooks", reads: "whole", reading: "hooks" },
+    env: { path: ["env"], category: "env", reads: "whole", reading: "envMap" },
+    model: { path: ["model"], category: "model", reads: "whole", reading: "nonEmptyString" },
+    outputStyle: { path: ["outputStyle"], category: "ui", reads: "whole", reading: "nonEmptyString" },
+};
+/** The one place a unit + optional member resolves to what is being asked about — the row and its comparator. Fail-closed
+ *  and loud on every misaddressing: an unknown unit (own-property lookup — `"__proto__"` is unknown, not Object.prototype),
+ *  a `members` unit without a member, a `whole` unit with one, a `member` unit given another one, an undeclared member
+ *  (refused by the member row lookup in {@link resolveMemberTighten}). */
+function unitTarget(unit, member) {
+    if (!Object.hasOwn(SETTINGS_UNITS, unit)) {
+        throw new RangeError(`SETTINGS_UNITS: unknown unit '${unit}' (units: ${Object.keys(SETTINGS_UNITS).join(", ")})`);
+    }
+    const row = SETTINGS_UNITS[unit];
+    const spec = SAFETY_MERGE_SPEC[row.category];
+    switch (row.reads) {
+        case "whole":
+            if (member !== undefined)
+                throw new RangeError(`SETTINGS_UNITS: unit '${unit}' is read whole — it has no member '${member}'`);
+            return { row, rule: spec.tighten };
+        case "member":
+            if (member !== undefined)
+                throw new RangeError(`SETTINGS_UNITS: unit '${unit}' already names its member ('${row.member}' of '${row.category}') — pass no member`);
+            return { row, rule: resolveMemberTighten(spec, row.member, row.category) };
+        case "members":
+            if (member === undefined) {
+                throw new RangeError(`SETTINGS_UNITS: unit '${unit}' is read per declared member of '${row.category}' (members: ${Object.keys(spec.members ?? {}).join(", ")}) — its whole value and its undeclared members have no comparator`);
+            }
+            return { row, rule: resolveMemberTighten(spec, member, row.category) };
+        default: {
+            const unknown = row;
+            throw new RangeError(`SETTINGS_UNITS: unit '${unit}' has an unknown addressing '${String(unknown.reads)}'`);
+        }
+    }
+}
+/** The comparator of one unit — or, for a `members` unit, of one DECLARED member of it: `whole` ⇒ the category's `tighten`;
+ *  `member` ⇒ that member's comparator; `members` ⇒ the named member's comparator ({@link resolveMemberTighten}). Compare two values
+ *  with `tightenVerdict`. A `members` unit without a member (its whole value), an undeclared member (e.g. `sandbox`'s
+ *  `failIfUnavailable`), a `whole` unit given a member, a `member` unit given another one, an unknown unit ⇒ RangeError. */
+export function unitTighten(unit, member) {
+    return unitTarget(unit, member).rule;
+}
+const UNREADABLE = { ok: false, reason: "unreadable" };
+const LAUNCH_ONLY = { ok: false, reason: "launch_only" };
+/** `stringList`: an array whose every element is a non-empty string (a hole reads as `undefined`, so a sparse array is not one). */
+function isNonEmptyStringList(v) {
+    const list = captureStringArray(v, "strict"); // the package's one string-array reading, strict: the value is handed back as is, so an accessor / hidden index ⇒ not a list (no getter is called)
+    return list !== undefined && list.every((x) => x.length > 0);
+}
+/** `envMap`: a plain object (prototype `Object.prototype` or `null`), non-empty keys, string values. The value is handed back AS IS, so its members are read strictly —
+ *  the package's one whole-container read, strict (`ownEntriesOf`: one `ownKeys`, each own string key's descriptor asked once — symbol keys never; never `[[Get]]`, never a
+ *  proxy's `get` trap): an accessor member or a non-enumerable member ⇒ not an env map (no getter is called — what the caller reads next is what was judged); unreadable ⇒ not one. */
+function isEnvMap(v) {
+    if (!isPlainJsonObject(v))
+        return false;
+    const members = ownEntriesOf(v);
+    return members.ok && members.value.every(([k, x]) => k.length > 0 && typeof x === "string");
+}
+/** What a declared member's value class adds on top of its comparator's domain — read through the comparator
+ *  {@link resolveMemberTighten} derived from the row, so the seat is interpreted in one place: `list` ⇒ setUnion / setNarrower,
+ *  whose domain takes any strings, so the `stringList` reading adds "every element non-empty"; `boolPole` ⇒ boolStricter, whose
+ *  domain IS the boolean — nothing to add. A member comparator is only ever one of those three. */
+function memberShapeReads(unit, rule, value) {
+    switch (rule.rule) {
+        case "boolStricter":
+            return true;
+        case "setUnion":
+        case "setNarrower":
+            return isNonEmptyStringList(value);
+        default:
+            throw new RangeError(`SETTINGS_UNITS: unit '${unit}' resolved to the comparator '${rule.rule}', which no member value class derives`);
+    }
+}
+/** A reading's shape / spelling half (the file header's table): the value the raw input reads as, or a refusal. The domain half
+ *  is the unit comparator's, applied by {@link readSettingsUnit} after this. */
+function shapedReading(unit, row, rule, raw) {
+    if (row.reads === "members")
+        return memberShapeReads(unit, rule, raw) ? { ok: true, value: raw } : UNREADABLE;
+    switch (row.reading) {
+        case "stringList":
+            return isNonEmptyStringList(raw) ? { ok: true, value: raw } : UNREADABLE;
+        case "permissionMode":
+            // the words are the category's order (the comparator's enumRank domain); the reading owns the two spellings around it
+            if (raw === "bypassPermissions")
+                return LAUNCH_ONLY;
+            return { ok: true, value: raw === "manual" ? "default" : raw };
+        case "killSwitch":
+            // CC spells ON "disable"; the boolean itself is the member comparator's domain
+            return { ok: true, value: raw === "disable" ? true : raw };
+        case "hooks": {
+            // the value is handed back AS IS, so it is read strictly (as every unit is): the whole tree is snapshotted by the kernel's strict whole-container read first —
+            // an accessor anywhere or a non-enumerable member ⇒ not readable (no getter is called) — and the classifier judges the snapshot, not the caller's object
+            const snapshot = captureJson(raw);
+            return snapshot.ok && classifyHooksConfig({ hooks: snapshot.value }).outcome === "loaded" ? { ok: true, value: raw } : UNREADABLE;
+        }
+        case "envMap":
+            return isEnvMap(raw) ? { ok: true, value: raw } : UNREADABLE;
+        case "nonEmptyString":
+            return typeof raw === "string" && raw.length > 0 ? { ok: true, value: raw } : UNREADABLE;
+        default: {
+            const unknown = row.reading;
+            throw new RangeError(`SETTINGS_UNITS: unit '${unit}' has an unknown reading '${String(unknown)}'`);
+        }
+    }
+}
+/**
+ * Read one unit's raw value out of a settings document (14.6.0) — the settings half of "how an existing value is normalized
+ * before it is compared". The reading of every unit is the file header's table; anything outside it is `unreadable`, and
+ * `undefined` / `null` are `unreadable` for every unit. An accepted value is returned as is (same reference) — the only rewrites
+ * are `"manual"` ⇒ `"default"` (permissionMode) and `"disable"` ⇒ `true` (kill-switches); `"bypassPermissions"` is `launch_only`.
+ * The last step of every reading is the unit comparator's own domain: whatever reads, compares (file header).
+ * Addressing is {@link unitTighten}'s (same RangeErrors: a `members` unit needs a declared member, …).
+ */
+export function readSettingsUnit(unit, raw, member) {
+    const t = unitTarget(unit, member);
+    if (raw === undefined || raw === null)
+        return UNREADABLE;
+    const shaped = shapedReading(unit, t.row, t.rule, raw);
+    if (!shaped.ok)
+        return shaped;
+    return tightenVerdict(t.rule, shaped.value, shaped.value) === "equal" ? shaped : UNREADABLE;
+}

package/dist/types.d.ts

@@ -1830,11 +1830,11 @@ export interface SkillsManifest {
  *  legal hash scheme. */
 export declare const SkillsManifestSchema: z.ZodObject<{
     skills: z.ZodPrefault<z.ZodArray<z.ZodObject<{
+        description: z.ZodDefault<z.ZodString>;
         name: z.ZodString;
         enabled: z.ZodDefault<z.ZodBoolean>;
         notes: z.ZodOptional<z.ZodString>;
         rosters: z.ZodPrefault<z.ZodArray<z.ZodString>>;
-        description: z.ZodDefault<z.ZodString>;
         scenarios: z.ZodPrefault<z.ZodArray<z.ZodString>>;
         allowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
         disallowedTools: z.ZodOptional<z.ZodArray<z.ZodString>>;
@@ -3219,10 +3219,14 @@ export type EffectiveKey = z.infer<typeof EffectiveKey>;
  *  `prompts` is the second wire divergence: on the wire it is {@link EffectivePromptsWire} (`{schemaVersion: 2, artifact}` — the one
  *  artifact {@link promptArtifactFor} selected for the pulling worker, stamped with its publish provenance), carried verbatim by the
  *  read leg and judged by the consumer (that shape, then the engine's verify) — optional (absent = nothing published, or the publish
- *  gate is closed), never the storage shape. */
+ *  gate is closed), never the storage shape.
+ *  `sandboxGit` (14.7.0) is the third wire-only key and the third carried verbatim: the sandbox git plane's origin block — web-admin projects it from the
+ *  deployment's registry, it is NOT a stored domain, so `buildEffective` never produces it and `readEffectiveWire` neither validates nor drops it. Optional with
+ *  no default (absent = the deployment projects no such block); the ONE seat that judges it is `SandboxGitConfig` (`./sandbox-git`), run by the consumer before use. */
 export type EffectiveWire = Omit<EffectiveConfig, "skills" | "prompts"> & {
     skills: SkillsManifest;
     prompts?: unknown;
+    sandboxGit?: unknown;
 };
 /** Reserved audit "domain" for RBAC/user-management events (not a config domain → no snapshot, not
  *  rollback-able). Lets user changes share the one audit stream the Audit page already renders. */