@t4r71/dsh-dual-axis 0.1.0

package/lib/read-guard.js

@@ -0,0 +1,1812 @@
+import { resolve, sep } from "node:path";
+import z from "@deepseek-ai/schemastery";
+import { canonicalPath, writableRoots } from "@deepseek-ai/dsh-sandbox";
+//#region lib/types/axis.js
+/**
+* The read/write ACCESS AXES of the file sandbox: the per-axis vocabulary a
+* session selects and the lossless mapping onto the legacy single `mode`.
+*
+* This is the 0.1.7 port of the algebra upstream deleted. 0.1.6 shipped it as
+* `@deepseek-ai/dsh-sandbox/access` (152 lines) and
+* `@deepseek-ai/dsh-sandbox/scope` (152 lines); 0.1.7 has neither symbol nor
+* file, so the package carries its own copy and keeps the 0.1.6 semantics
+* verbatim: four kinds, `custom` = base + allow - deny with deny winning.
+*
+* One axis answers "which absolute paths may this execution touch". `deny`
+* permits nothing, `workspace` permits the calling session's workspace root
+* plus the platform temp areas, `all` is the whole host filesystem, and
+* `custom` names a BASE kind plus absolute path ADDITIONS and REMOVALS —
+* path lists, not patterns.
+*
+* `mode` REMAINS the write axis's persistence spelling. The session-format
+* whitelist pins its literal values, so this module keeps `mode` derivable
+* from the write scope in both directions instead of replacing it:
+* {@link scopeOfMode} and {@link modeOfScope} are the two halves of that
+* bijection, and `custom` maps onto the mode implied by its own base.
+*
+* @module @t4r71/dsh-dual-axis/axis
+*/
+/** Every {@link AxisScopeKind}, for option advertisement and untrusted-value validation. */
+const AXIS_KINDS = [
+	"deny",
+	"workspace",
+	"all",
+	"custom"
+];
+/** Every {@link AxisBase}, for option advertisement and untrusted-value validation. */
+const AXIS_BASES = [
+	"deny",
+	"workspace",
+	"all"
+];
+/** The default READ axis: every mode permitted reading before the axes existed, so the whole host. */
+const DEFAULT_READ_SCOPE = { kind: "all" };
+/** The default WRITE axis: the session workspace plus the platform temp areas. */
+const DEFAULT_WRITE_SCOPE = { kind: "workspace" };
+//#endregion
+//#region lib/types/scope.js
+/**
+* The shared path-range ALGEBRA behind both access axes: one pure evaluation
+* from an {@link AxisScope} to the canonical allow and deny root sets the
+* fence consumes.
+*
+* This is the 0.1.7 port of 0.1.6's `@deepseek-ai/dsh-sandbox/scope`
+* (152 lines), reduced to what a fence needs and made source-agnostic:
+*
+* - `workspace` derives its roots from 0.1.7's own
+*   `writableRoots(policy)` (`@deepseek-ai/dsh-sandbox`, re-exported from
+*   `packages/sandbox/sandbox/src/roots.ts:52`), so the fence agrees with
+*   the Seatbelt profile and the write fence by construction.
+* - Containment itself is NOT evaluated here. 0.1.6 took the enforcement
+*   layer's `contains` predicate as a parameter; this port keeps that shape
+*   but narrows it to the SYNCHRONOUS lexical predicate the pure tests use,
+*   and the filesystem-identity fallback lives in the fence
+*   (`fs-fence.ts`), which is where the canonical target key exists.
+*
+* `resolveScope` returns the sets; the fence applies them with deny-wins
+* precedence through {@link scopeContains}.
+*
+* @module @t4r71/dsh-dual-axis/scope
+*/
+/** Thrown when a configured `custom` scope entry cannot name an absolute path. */
+var ScopeConfigError = class extends Error {
+	entry;
+	value;
+	constructor(entry, value) {
+		super(`sandbox scope: \`${entry}\` entry ${JSON.stringify(value)} must be a non-empty absolute path`);
+		this.entry = entry;
+		this.value = value;
+		this.name = "ScopeConfigError";
+	}
+};
+/** Canonicalize one configured custom entry, failing closed on anything that cannot name an absolute host path. */
+function canonicalEntry(value, entry) {
+	if (value.trim().length === 0 || !isAbsoluteSpelling(value)) throw new ScopeConfigError(entry, value);
+	return canonicalPath(value);
+}
+/**
+* Whether a configured path is spelled absolutely on this host. Both POSIX
+* (`/x`) and Windows (`C:\\x`, `\\\\server\\share`) spellings are accepted
+* because a policy may be authored for one world and resolved in another; the
+* canonical resolution that follows is what actually binds it to this host.
+* @param path - the configured path spelling.
+* @returns whether the spelling is absolute.
+*/
+function isAbsoluteSpelling(path) {
+	return path.startsWith("/") || /^[A-Za-z]:[\\/]/.test(path) || path.startsWith("\\\\");
+}
+/**
+* Evaluate one axis against a workspace root. `deny` permits nothing;
+* `workspace` yields the shared writable roots; `all` is unbounded;
+* `custom` yields its base plus its own additions, with its removals listed
+* separately so the fence can apply them with precedence.
+*
+* A `custom` scope whose base is `all` stays unbounded: "everything except
+* these directories" is still everything-except, so its removals must survive
+* into {@link ResolvedScope.deny} rather than being flattened into an allow
+* list that could not express them.
+* @param scope - the axis value.
+* @param policy - the workspace root `workspace` and `custom` scopes resolve against.
+* @returns the evaluated range.
+* @throws {ScopeConfigError} when a `custom` entry is not a non-empty absolute path.
+*/
+function resolveScope(scope, policy) {
+	if (scope.kind !== "custom") return resolveBase(scope.kind, policy);
+	const base = resolveBase(scope.base, policy);
+	const allow = [...base.allow, ...scope.allow.map((entry) => canonicalEntry(entry, "allow"))];
+	const deny = scope.deny.map((entry) => canonicalEntry(entry, "deny"));
+	return {
+		unbounded: base.unbounded,
+		allow: dedupe(allow),
+		deny: dedupe(deny)
+	};
+}
+/** Evaluate a base (or closed) kind — the shared half of {@link resolveScope}. */
+function resolveBase(base, policy) {
+	switch (base) {
+		case "deny": return {
+			unbounded: false,
+			allow: [],
+			deny: []
+		};
+		case "workspace": return {
+			unbounded: false,
+			allow: dedupe(writableRoots({
+				mode: "workspace-write",
+				workspaceRoot: policy.workspaceRoot
+			})),
+			deny: []
+		};
+		case "all": return {
+			unbounded: true,
+			allow: [],
+			deny: []
+		};
+	}
+}
+/** Stable-order dedupe: keeps the first spelling of each value. */
+function dedupe(values) {
+	return [...new Set(values)];
+}
+/**
+* Whether `target` is the root itself or lies beneath it, by canonical
+* spelling. Case-insensitive on Windows, matching that filesystem's
+* convention.
+* @param target - canonical target path.
+* @param root - canonical root path.
+* @param caseSensitive - whether lexical comparison preserves case; defaults to the host convention.
+* @returns whether the target is the root or a descendant of it.
+*/
+function isLexicallyUnder(target, root, caseSensitive = process.platform !== "win32") {
+	const comparableTarget = caseSensitive ? target : target.toLowerCase();
+	const comparableRoot = caseSensitive ? root : root.toLowerCase();
+	if (comparableTarget === comparableRoot) return true;
+	const prefix = comparableRoot.endsWith(sep) ? comparableRoot : comparableRoot + sep;
+	return comparableTarget.startsWith(prefix);
+}
+/**
+* Whether `targetKey` is permitted by an evaluated scope. Removal wins over
+* addition: a deny root containing the target refuses it even when an allow
+* root — or an unbounded axis — would otherwise permit it.
+* @param scope - the evaluated scope.
+* @param targetKey - the target's canonical identity key (the resolved path).
+* @param contains - the containment predicate; defaults to {@link isLexicallyUnder}.
+* @returns whether the scope permits the target.
+*/
+function scopeContains(scope, targetKey, contains = isLexicallyUnder) {
+	for (const root of scope.deny) if (contains(targetKey, root)) return false;
+	if (scope.unbounded) return true;
+	for (const root of scope.allow) if (contains(targetKey, root)) return true;
+	return false;
+}
+//#endregion
+//#region lib/types/config.js
+/**
+* The dual-axis settings surface: the 0.1.7 spelling of the section 0.1.6
+* registered through `ctx.settings.installSection`.
+*
+* 0.1.7 removed both `installSection` and `settings.register(ns, schema)`:
+* `SettingsForms.describe()` projects exactly the Config schemas of LOADED
+* Loader entries (`packages/settings/settings/src/index.ts:302-340`) and
+* `write()` refuses a namespace with no matching entry
+* (`:382-384`, `No configurable plugin entry`). The namespace IS the entry
+* id, so this package's own row id in `cordis.patch.yml` — `dual-axis` — is
+* the settings namespace. 0.1.6's separate `sandbox-axis` namespace name is
+* therefore retired.
+*
+* 0.1.7 also added the volatile gate: a field that is not beneath a
+* `.volatile()` node is neither projected into the form
+* (`packages/settings/settings/src/schema.ts:37-47`) nor writable
+* (`:74-78`), and an entry with no volatile field at all is refused outright
+* (`index.ts:385-386`). Both axes are marked volatile here.
+*
+* The schema is deliberately `z.any()` per axis, exactly as in 0.1.6:
+* schemastery's union types strip the `custom` branch's `base/allow/deny`
+* payload, which would silently degrade a configured custom axis into an axis
+* carrying no paths. Shape validation is {@link normalizeScope}'s job.
+*
+* @module @t4r71/dsh-dual-axis/config
+*/
+/**
+* This package's row id in `cordis.patch.yml`. It doubles as the 0.1.7
+* settings namespace (the Loader entry id) and, prefixed with the package
+* name, as the `plugins.row.config` slot entry key the client half uses.
+*/
+const DUAL_AXIS_ROW_ID = "dual-axis";
+z.object({
+	read: z.any().volatile(),
+	write: z.any().volatile(),
+	groups: z.array(z.any()).default([]).volatile(),
+	defaultGroups: z.array(z.string()).default([]).volatile()
+});
+/**
+* Collect one `custom` axis's path list: every entry must be a non-empty
+* absolute path.
+* @param label - the axis name used in the error message.
+* @param entry - the list name used in the error message (`allow` or `deny`).
+* @param value - the untrusted list value.
+* @returns the validated path list.
+* @throws When the value is not a string array, or holds a non-absolute path.
+*/
+function pathList(label, entry, value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string")) throw new Error(`dual-axis: ${label} ${entry} must be an array of absolute path strings`);
+	for (const item of value) if (item.length === 0 || !isAbsoluteSpelling(item)) throw new Error(`dual-axis: ${label} ${entry} entry ${JSON.stringify(item)} must be an absolute path`);
+	return [...value];
+}
+/**
+* Coerce one axis value from a config document (which a human may have edited)
+* into a legal {@link AxisScope}, throwing rather than guessing.
+*
+* An unreadable axis must not become some other, wider or narrower grant:
+* throwing fails the row's mount or the settings write on the spot instead of
+* proceeding under an invented boundary. This is 0.1.6's `normalizeScope`,
+* unchanged.
+* @param label - the axis name used in error messages (`read` or `write`).
+* @param value - the untrusted axis value.
+* @returns the validated axis value.
+* @throws When the value is not one of the four kinds, or a custom entry is not absolute.
+*/
+function normalizeScope(label, value) {
+	if (typeof value !== "object" || value === null) throw new Error(`dual-axis: ${label} must be an access-axis object, received ${JSON.stringify(value)}`);
+	const candidate = value;
+	if (typeof candidate.kind !== "string" || !AXIS_KINDS.includes(candidate.kind)) throw new Error(`dual-axis: ${label} carries unknown kind ${JSON.stringify(candidate.kind)} (expected: ${AXIS_KINDS.join(", ")})`);
+	if (candidate.kind !== "custom") return { kind: candidate.kind };
+	if (typeof candidate.base !== "string" || !AXIS_BASES.includes(candidate.base)) throw new Error(`dual-axis: ${label} custom base must be ${AXIS_BASES.join(", ")}, received ${JSON.stringify(candidate.base)}`);
+	return {
+		kind: "custom",
+		base: candidate.base,
+		groups: groupIds(label, candidate.groups),
+		allow: pathList(label, "allow", candidate.allow),
+		deny: pathList(label, "deny", candidate.deny)
+	};
+}
+/**
+* Collect one `custom` axis's rule-group references. Only the speaker matters
+* here — an id is a name the settings page resolves, so this checks that the
+* list is a list of non-empty names and nothing more; whether the name exists is
+* decided at the moment of use ({@link resolveEffectiveAxes}), where a missing
+* one can be refused instead of quietly dropped.
+* @param label - the axis name used in the error message.
+* @param value - the untrusted `groups` value.
+* @returns the validated id list.
+* @throws When the value is not an array of non-empty strings.
+*/
+function groupIds(label, value) {
+	if (value === void 0) return [];
+	if (!Array.isArray(value) || value.some((item) => typeof item !== "string" || item.length === 0)) throw new Error(`dual-axis: ${label} groups must be an array of non-empty rule-group ids`);
+	return [...new Set(value)];
+}
+/**
+* Read both axes out of one settings/config value.
+*
+* The parameter is UNTRUSTED on purpose: the same function serves the
+* composition layer's parsed Config, the settings service's projected
+* descriptor (an `unknown` on the wire between two packages), and a
+* hand-edited document, and none of those three is guaranteed to carry the
+* declared shape. Both axes therefore pass through {@link normalizeScope},
+* which is where an illegal value becomes a throw instead of an invented
+* boundary; a missing side falls back to the built-in default axis.
+* @param section - the section's current resolved value, whatever carries it.
+* @returns both axes.
+* @throws When either axis's shape is illegal.
+*/
+function axesOf(section) {
+	const declared = section === null || typeof section !== "object" ? {} : section;
+	return {
+		read: normalizeScope("read", unwrapVolatile(declared.read) ?? DEFAULT_READ_SCOPE),
+		write: normalizeScope("write", unwrapVolatile(declared.write) ?? DEFAULT_WRITE_SCOPE)
+	};
+}
+/**
+* Unwrap one config field's value.
+*
+* A `.volatile()` field is handed to the plugin as a cordis `Volatile<T>`
+* **accessor**, not as `T`: the schema's `get()` re-reads the stored value on
+* every call so an edit applies without remounting the entry. Reading the
+* property directly therefore yields the accessor object, whose `kind` is
+* `undefined` — which {@link normalizeScope} correctly refuses, failing the
+* whole row at mount. The upstream volatile Config
+* (`packages/core/agent-default-model/src/index.ts:68-71`) unwraps the same way.
+*
+* A hand-written config document may also carry the plain value, so both
+* spellings are accepted.
+* @param value - the configured field, as the accessor, as a plain value, or as
+*   whatever an untrusted document put under the key.
+* @returns the underlying value, or `undefined` when this field is unset.
+*/
+function unwrapVolatile(value) {
+	if (value === void 0) return void 0;
+	if (typeof value.get === "function") return value.get();
+	return value;
+}
+/**
+* This row's current value on the settings page, or `undefined` when no
+* settings service is mounted.
+*
+* This is the ONE read path to that row. It goes through `describe()` rather
+* than the config the plugin instance captured at mount because the loader does
+* not commit a later save back to that instance
+* (`vendor/loader/src/config/entry.ts:162-195`); `describe()` re-projects
+* `entry.fiber.config` and unwraps the volatile accessors on every call
+* (`packages/settings/settings/src/index.ts:319-323` +
+* `packages/settings/settings/src/schema.ts:11`), which is the same path the
+* settings page renders from. A save therefore applies without a restart.
+* @param ctx - host context; the service is looked up, never injected.
+* @returns the row's current value, or `undefined` when unavailable.
+*/
+function declaredSection(ctx) {
+	return ctx.get("settings")?.describe().find((row) => row.ns === DUAL_AXIS_ROW_ID)?.value;
+}
+/**
+* The group library a decision path may read, and the ONLY part of the settings
+* row one may read for a decision.
+*
+* The row's `read`, `write` and `defaultGroups` fields are seeds for
+* NEWLY CREATED sessions and carry no authority over an existing one; a
+* decision path that read them would let the settings page silently re-scope a
+* running session, which is the drift this package exists to prevent.
+* @param section - the row's current value, as {@link declaredSection} returns it.
+* @returns the untrusted `groups` value, for {@link resolveEffectiveAxes}.
+*/
+function groupLibraryValue(section) {
+	return section === null || typeof section !== "object" ? void 0 : unwrapVolatile(section.groups);
+}
+/**
+* The group ids a newly created session starts out referencing.
+* @param section - the row's current value, as {@link declaredSection} returns it.
+* @returns the ids, deduplicated; empty when the row declares none.
+* @throws When a declared id is not a non-empty string.
+*/
+function defaultGroupIds(section) {
+	return groupIds("defaultGroups", section === null || typeof section !== "object" ? void 0 : unwrapVolatile(section.defaultGroups));
+}
+//#endregion
+//#region lib/types/content.js
+/**
+* Whether a session has been USED yet — the one predicate that decides when its
+* axis pair freezes.
+*
+* A session the workspace picker reopens in the same workspace is the same
+* session id with the same stored record, so the axes it was seeded with at
+* creation are what its two dropdowns show for the rest of its life. That is
+* correct for a session someone has actually worked in; for one nobody has ever
+* exchanged a turn with it is wrong, because the settings row is a live default
+* and the person changing it expects the next conversation to follow.
+*
+* So the record is written when the session is used, not when it is created:
+*
+* - nothing appended beyond the loop's runtime-context snapshot → no record; the
+*   seed recomputed from the CURRENT settings row answers every read, so the
+*   dropdown follows the settings page in real time;
+* - one real user turn, or an assistant reply → the record is written and the
+*   pair freezes;
+* - `/axis` → {@link SessionAxesStore.set} writes unconditionally, so a manual
+*   pick always freezes, on an empty session too.
+*
+* ## What counts as "content"
+*
+* Everything except a message whose source is the loop's own runtime-context
+* snapshot. That snapshot is appended by the agent loop on EVERY turn
+* (`packages/core/agent-loop/src/runtime-context.ts`), including the very first
+* one, and it is present before any human input exists — the four events a
+* freshly created session carries are the header, the preset, the mode, and the
+* approval policy. Counting it would make every session look used the moment
+* anything rendered its prompt, which is exactly the state this predicate has to
+* tell apart.
+*
+* The snapshot is identified by its `source.kind`, the discriminant the loop
+* writes and reads back (`isOwned` in that module requires `kind === 'plugin'`;
+* the system-prompt renderer stamps `kind: 'runtime-context'`). Matching on the
+* kind is cheaper and more robust than matching the rendered text, which is
+* localized prose that changes with every contribution.
+*
+* Every other message counts, the skill catalogue and the compaction markers
+* included: each of them means the session has entered a turn, and a session
+* that has entered a turn is one somebody is using.
+*
+* @module @t4r71/dsh-dual-axis/content
+*/
+/**
+* The `source.kind` of the loop's per-turn runtime-context snapshot.
+*
+* @see `packages/core/agent-loop/src/runtime-context.ts` — `RuntimeContextProjection.project`
+*   builds the message, and the renderer in
+*   `packages/core/system-prompt/src/index.ts` stamps this kind on it.
+*/
+const RUNTIME_CONTEXT_KIND = "runtime-context";
+/**
+* Whether a session has content beyond the loop's own runtime-context snapshots.
+*
+* Cheap by construction: it walks the session's existing event array, which is
+* already materialized and cached, without copying, parsing, or allocating per
+* event. It is called on every `ensure` for a session that has no record, and
+* that set is exactly the sessions nobody has used — so the scan is short.
+* @param session - the session to judge.
+* @returns whether this session has been used.
+*/
+function hasContent(session) {
+	for (const event of session.snapshotEvents()) {
+		if (event.type === "user/message") {
+			if (event.data.source?.kind === RUNTIME_CONTEXT_KIND) continue;
+			return true;
+		}
+		if (event.type === "assistant/message" || event.type === "system/message") return true;
+	}
+	return false;
+}
+//#endregion
+//#region lib/types/groups.js
+/**
+* RULE GROUPS and THE ONE resolution from a session's axis preset to the ranges
+* actually in force.
+*
+* A rule group is a named fragment of path rules owned by the settings page
+* (`dual-axis`'s `groups` Config field). A session references groups BY ID and
+* never stores their content: ten sessions selecting one group must not become
+* ten copies of it, because copies drift. Resolving an id against the CURRENT
+* library is therefore the only place a group's rules enter a decision, and
+* editing a group takes effect on every session referencing it without a
+* restart.
+*
+* This module is that place, for both axes and for both invariants that ride on
+* them:
+*
+* - **deny wins over allow**, with session-level entries and every selected
+*   group merged into ONE allow list and ONE deny list first
+*   ({@link resolveEffectiveAxes}), so a group's removal cannot be overridden by
+*   a session-level addition.
+* - **write never exceeds read**: the effective write range is the write axis's
+*   range INTERSECTED with the read axis's range. A write outside the read range
+*   would let an agent overwrite a file it cannot read back, so the intersection
+*   is computed here — in the resolution — and never in a user interface.
+*
+* Both the fence and the model-facing prompt call {@link resolveEffectiveAxes},
+* so the range the model is told about and the range it is held to are the same
+* computation over the same inputs: the session's own preset (read and write
+* axes, their own additions and removals, and the group ids they selected) plus
+* the current definitions of those ids. The settings page's `read` / `write`
+* defaults and its `defaultGroups` seed are NOT among those inputs: they are
+* read once, when a session is created.
+*
+* A reference to an id the library does not define is refused, never treated as
+* an empty group: "I excluded it and nothing happened" is the worst failure this
+* surface can have.
+*
+* @module @t4r71/dsh-dual-axis/groups
+*/
+/** The narrowing that removed nothing. Exported: it is the stored record's absent value. */
+const NO_NARROWING = {
+	narrowed: false,
+	droppedRoots: [],
+	lostUnbounded: false
+};
+/**
+* Read one stored narrowing report, or throw naming the member that is
+* unreadable.
+*
+* An absent member is the legal "nothing was ever published for this record"
+* state and yields {@link NO_NARROWING}: that is exactly what the fence enforced
+* before this member existed, so the surface shows no narrowing rather than
+* inventing one. Anything PRESENT must be well formed — a report whose root list
+* cannot be read would otherwise be displayed as "nothing was removed".
+* @param value - the untrusted `narrowing` member of a stored record.
+* @returns the validated report.
+* @throws When the member is present and not a well-formed report.
+*/
+function parseNarrowing(value) {
+	if (value === void 0) return NO_NARROWING;
+	if (value === null || typeof value !== "object" || Array.isArray(value)) throw new Error("dual-axis: a stored narrowing report must be an object");
+	const candidate = value;
+	if (typeof candidate.narrowed !== "boolean" || typeof candidate.lostUnbounded !== "boolean") throw new Error("dual-axis: a stored narrowing report needs boolean narrowed and lostUnbounded");
+	return {
+		narrowed: candidate.narrowed,
+		droppedRoots: pathList("stored narrowing", "droppedRoots", candidate.droppedRoots),
+		lostUnbounded: candidate.lostUnbounded
+	};
+}
+/**
+* Parse one group's rules for one axis.
+* @param label - the group and axis, as the error message should name them.
+* @param value - the untrusted `read` or `write` member.
+* @returns the validated rules, or `undefined` when the member is absent.
+* @throws When the member is neither absent nor an object of absolute path lists.
+*/
+function axisRules(label, value) {
+	if (value === void 0) return void 0;
+	if (value === null || typeof value !== "object") throw new Error(`dual-axis: ${label} must be an object carrying allow and/or deny`);
+	const candidate = value;
+	return {
+		allow: pathList(label, "allow", candidate.allow),
+		deny: pathList(label, "deny", candidate.deny)
+	};
+}
+/**
+* Read one group entry out of the library.
+* @param index - the entry's position, used in error messages.
+* @param value - the untrusted entry.
+* @returns the validated group.
+* @throws When the entry carries no usable id.
+*/
+function groupAt(index, value) {
+	if (value === null || typeof value !== "object") throw new Error(`dual-axis: rule group #${String(index)} must be an object`);
+	const candidate = value;
+	if (typeof candidate.id !== "string" || candidate.id.length === 0) throw new Error(`dual-axis: rule group #${String(index)} needs a non-empty string id`);
+	const label = "rule group " + JSON.stringify(candidate.id);
+	const read = candidate.read === void 0 ? void 0 : axisRules(label + " read", candidate.read);
+	const write = candidate.write === void 0 ? void 0 : axisRules(label + " write", candidate.write);
+	return {
+		id: candidate.id,
+		name: typeof candidate.name === "string" && candidate.name.length > 0 ? candidate.name : candidate.id,
+		...read === void 0 ? {} : { read },
+		...write === void 0 ? {} : { write }
+	};
+}
+/**
+* Parse the settings page's group library. An unset or null library is the
+* legal "no groups configured" state; anything else must be a well-formed
+* library, because a half-read library would silently drop a removal.
+* @param value - the untrusted `groups` Config value.
+* @returns the parsed library by id, or the sentence explaining why it is unusable.
+*/
+function parseLibrary(value) {
+	if (value === void 0 || value === null) return {
+		ok: true,
+		byId: /* @__PURE__ */ new Map()
+	};
+	if (!Array.isArray(value)) return {
+		ok: false,
+		problem: "the rule-group library must be an array of groups"
+	};
+	const byId = /* @__PURE__ */ new Map();
+	try {
+		for (let index = 0; index < value.length; index += 1) {
+			const group = groupAt(index, value[index]);
+			if (byId.has(group.id)) return {
+				ok: false,
+				problem: "the rule-group library defines " + JSON.stringify(group.id) + " more than once"
+			};
+			byId.set(group.id, group);
+		}
+	} catch (error) {
+		return {
+			ok: false,
+			problem: error instanceof Error ? error.message : String(error)
+		};
+	}
+	return {
+		ok: true,
+		byId
+	};
+}
+/**
+* The group ids a preset references, in first-seen order and without repeats.
+* Callers use this to skip reading the settings page at all for the sessions
+* that reference no groups.
+* @param preset - the session's own axis preset.
+* @returns the referenced ids.
+*/
+function referencedGroupIds(preset) {
+	const ids = [];
+	for (const axis of [preset.read, preset.write]) {
+		if (axis.kind !== "custom") continue;
+		for (const id of axis.groups ?? []) if (!ids.includes(id)) ids.push(id);
+	}
+	return ids;
+}
+/**
+* Expand one axis: its own additions and removals first, then those of every
+* group it references, merged into one allow list and one deny list. The result
+* carries no group ids — expansion is the resolution, and a resolved value that
+* still referenced groups could be expanded a second time.
+* @param axis - the axis preset.
+* @param side - which of a group's two rule sets applies.
+* @param byId - the parsed library.
+* @returns the expanded axis.
+*/
+function expandAxis(axis, side, byId) {
+	if (axis.kind !== "custom") return axis;
+	const ids = axis.groups ?? [];
+	if (ids.length === 0) return axis;
+	const allow = [...axis.allow];
+	const deny = [...axis.deny];
+	for (const id of ids) {
+		const rules = byId.get(id)?.[side];
+		if (rules === void 0) continue;
+		allow.push(...rules.allow ?? []);
+		deny.push(...rules.deny ?? []);
+	}
+	return {
+		kind: "custom",
+		base: axis.base,
+		allow: [...new Set(allow)],
+		deny: [...new Set(deny)]
+	};
+}
+/**
+* Attach the group ids a NEW session starts out referencing to the axes that are
+* `custom`, leaving every other axis exactly as declared.
+*
+* The rule is judged per axis, and only an axis whose OWN kind is `custom` can
+* carry a reference: checking the settings row instead (a tick that is not
+* tied to an axis) promoted `read: all` to `read: { kind: 'custom', base: 'all' }`
+* even though no axis was ever set to custom. An axis of one of the three closed
+* kinds has nowhere to put an id and is seeded verbatim — promoting it would
+* report a custom scope the settings page never showed.
+*
+* A group may carry rules for either axis or both, and the session selected it
+* once, so the same list goes on both `custom` axes; the group's `read` rules
+* then apply where they exist and its `write` rules where they exist. Two axes
+* are therefore independent: one may take the references while the other keeps
+* its closed kind.
+* @param axes - the pair a new session is seeded with.
+* @param ids - the settings page's `defaultGroups`.
+* @returns the pair carrying those references.
+*/
+function seedGroupReferences(axes, ids) {
+	if (ids.length === 0) return axes;
+	const attach = (axis) => axis.kind === "custom" ? {
+		...axis,
+		groups: [.../* @__PURE__ */ new Set([...axis.groups ?? [], ...ids])]
+	} : axis;
+	return {
+		read: attach(axes.read),
+		write: attach(axes.write)
+	};
+}
+/**
+* The intersection of two evaluated ranges, as an evaluated range. Exact for
+* canonical directory roots: two roots are either nested — the deeper one is
+* their intersection — or disjoint, and a union of directories intersected with
+* a union of directories is the union of those pairwise intersections.
+* @param left - one evaluated range.
+* @param right - the other evaluated range.
+* @returns the range permitting exactly what both permit.
+*/
+function intersectResolved(left, right) {
+	const deny = [.../* @__PURE__ */ new Set([...left.deny, ...right.deny])];
+	if (left.unbounded && right.unbounded) return {
+		unbounded: true,
+		allow: [],
+		deny
+	};
+	if (left.unbounded) return {
+		unbounded: false,
+		allow: [...right.allow],
+		deny
+	};
+	if (right.unbounded) return {
+		unbounded: false,
+		allow: [...left.allow],
+		deny
+	};
+	const allow = [];
+	for (const one of left.allow) for (const other of right.allow) if (isLexicallyUnder(one, other) && !allow.includes(one)) allow.push(one);
+	else if (isLexicallyUnder(other, one) && !allow.includes(other)) allow.push(other);
+	return {
+		unbounded: false,
+		allow,
+		deny
+	};
+}
+/**
+* Spell an evaluated range as an axis value that evaluates back to it. The
+* `deny` base plus the roots themselves is the exact spelling: a `workspace`
+* base would re-add the platform temp areas this range may never have had.
+* @param resolved - the evaluated range.
+* @returns the equivalent axis value.
+*/
+function scopeOfResolved(resolved) {
+	return resolved.unbounded ? {
+		kind: "custom",
+		base: "all",
+		allow: [],
+		deny: [...resolved.deny]
+	} : {
+		kind: "custom",
+		base: "deny",
+		allow: [...resolved.allow],
+		deny: [...resolved.deny]
+	};
+}
+/**
+* The removals in a range that remove something, so two ranges that differ only
+* in irrelevant removals compare equal.
+* @param scope - the evaluated range.
+* @returns the deny roots that would otherwise be permitted.
+*/
+function relevantDenies(scope) {
+	const permitAll = {
+		unbounded: scope.unbounded,
+		allow: scope.allow,
+		deny: []
+	};
+	return scope.deny.filter((root) => scopeContains(permitAll, root, isLexicallyUnder));
+}
+/** Whether two evaluated ranges permit exactly the same paths. */
+function sameRange(left, right) {
+	const sameSet = (one, other) => one.length === other.length && one.every((value) => other.includes(value));
+	if (left.unbounded !== right.unbounded) return false;
+	if (left.unbounded) return sameSet(relevantDenies(left), relevantDenies(right));
+	return sameSet(left.allow, right.allow) && sameSet(relevantDenies(left), relevantDenies(right));
+}
+/**
+* What the intersection removed: every root the write axis permitted that the
+* effective range does not, counting both roots dropped from the allow list and
+* roots the read axis newly denies.
+* @param before - the write axis's own range.
+* @param after - the effective write range.
+* @returns the narrowing report.
+*/
+function narrowingOf(before, after) {
+	const lostUnbounded = before.unbounded && !after.unbounded;
+	const droppedRoots = [...before.allow.filter((root) => !scopeContains(after, root, isLexicallyUnder)), ...after.deny.filter((root) => !before.deny.includes(root) && scopeContains(before, root, isLexicallyUnder))];
+	const unique = [...new Set(droppedRoots)];
+	return {
+		narrowed: lostUnbounded || unique.length > 0,
+		droppedRoots: unique,
+		lostUnbounded
+	};
+}
+/**
+* Expand one axis against the library, reporting the ids it references and the
+* library does not define.
+* @param axis - the axis preset.
+* @param side - which of a group's two rule sets applies.
+* @param byId - the parsed library.
+* @param missing - collects the undefined ids, in reference order.
+* @returns the expanded axis.
+*/
+function expandChecked(axis, side, byId, missing) {
+	if (axis.kind === "custom") {
+		for (const id of axis.groups ?? []) if (!byId.has(id) && !missing.includes(id)) missing.push(id);
+	}
+	return expandAxis(axis, side, byId);
+}
+/** The sentence naming the ids a preset references and the library does not define. */
+function missingGroupsProblem(ids) {
+	return "this session references rule group(s) " + ids.map((id) => JSON.stringify(id)).join(", ") + " that the rule-group library does not define";
+}
+/**
+* THE resolution: one session's axis preset plus the current group library into
+* the read and write ranges actually in force.
+*
+* The write member of the result is the intersection of the write axis's range
+* with the read axis's. The write axis keeps its own spelling whenever the
+* intersection changed nothing, so a session that references no groups and needs
+* no narrowing is described and enforced exactly as before groups existed.
+*
+* An unresolvable reference or an unusable library returns `ok: false` and no
+* axes: the caller refuses, because resolving a missing id to an empty group
+* would silently drop rules the user configured.
+* @param preset - the session's own axis preset, group ids included.
+* @param library - the settings page's current `groups` value, untrusted.
+* @param policy - the workspace root a `workspace` base resolves against.
+* @returns the effective pair, or the sentence explaining why there is none.
+*/
+function resolveEffectiveAxes(preset, library, policy) {
+	const parsed = parseLibrary(library);
+	if (!parsed.ok) return {
+		ok: false,
+		problem: parsed.problem
+	};
+	const missing = [];
+	const read = expandChecked(preset.read, "read", parsed.byId, missing);
+	const write = expandChecked(preset.write, "write", parsed.byId, missing);
+	if (missing.length > 0) return {
+		ok: false,
+		problem: missingGroupsProblem(missing)
+	};
+	let readRange;
+	let writeRange;
+	try {
+		readRange = resolveScope(read, policy);
+		writeRange = resolveScope(write, policy);
+	} catch (error) {
+		return {
+			ok: false,
+			problem: error instanceof Error ? error.message : String(error)
+		};
+	}
+	const intersected = intersectResolved(writeRange, readRange);
+	if (sameRange(writeRange, intersected)) return {
+		ok: true,
+		axes: {
+			read,
+			write,
+			narrowing: NO_NARROWING
+		}
+	};
+	return {
+		ok: true,
+		axes: {
+			read,
+			write: scopeOfResolved(intersected),
+			narrowing: narrowingOf(writeRange, intersected)
+		}
+	};
+}
+//#endregion
+//#region lib/types/session-store.js
+/**
+* THE per-session axis store, outside the session log.
+*
+* The axes cannot live in a session's own log: this package's own event type is
+* not in 0.1.7's `KNOWN_SESSION_EVENT_TYPES`, and `Session.append` takes no
+* envelope option, so the event cannot be marked `ignorable` and a log carrying
+* it is refused WHOLE by `validateStoredEvents`
+* (`packages/session/session-persistence/src/storage-contract.ts:75-77`).
+* A session this package had written to could therefore not be opened at all
+* after a restart.
+*
+* The axes live instead in this package's OWN settings namespace,
+* `dual-axis-sessions`, partitioned by session id. That namespace is a
+* separate Loader entry from `dual-axis` because the row's namespace carries the
+* settings page's read/write/defaultGroups form: an undeclared field inside that
+* row would be projected into the row's form. This namespace declares exactly one
+* field and the settings page never renders it.
+*
+* `sandbox/mode` REMAINS the write axis's legal landing place in the log — see
+* `./session-axes.ts`, which mirrors the write base onto it. The log therefore
+* still records the containment the operating-system layer enforces; what it no
+* longer records is the path-level axis pair, which is this module's.
+*
+* A session with NO record is neither an error state nor a reason to hide a
+* control: every live decision path reads through {@link SessionAxesStore.ensure},
+* which answers {@link seedAxesFor} — the deployment seed a newly created session
+* is pinned with — and hands that SAME value to the ONE repair write it
+* schedules. Such a session therefore runs under the deployment's seed from its
+* first read, not under {@link DEFAULT_AXES} until the record lands, and the pair
+* a picker shows before the record exists is the pair the fence and the prompt
+* are already enforcing (the client half recomputes that seed from the same row —
+* see `sessionAxesSeed` in `@t4r71/dsh-dual-axis-ui`).
+* {@link DEFAULT_AXES} is now only the answer {@link SessionAxesStore.getOr} gives
+* a caller that holds no session to build a seed from.
+*
+* A session with no record that has ALSO never been used is a different case, and
+* it is the one the workspace picker creates every time: reopening the same
+* workspace reopens the same session id, so freezing it at creation would pin the
+* axes of a conversation nobody has had to whatever the settings row said that
+* day. Its record is therefore written when it is USED ({@link hasContent}), not
+* when it is created: until then every read recomputes the seed from the row as
+* it stands NOW, and the dropdown follows the settings page in real time.
+*
+* @module @t4r71/dsh-dual-axis/session-store
+*/
+/**
+* The settings namespace holding every session's axis pair. It is a Loader entry
+* id (`cordis.patch.yml`), which is what `SettingsForms.write` looks up.
+*/
+const SESSION_AXES_NAMESPACE = "dual-axis-sessions";
+/** The single Config field: session id -> axis pair. */
+const SESSION_AXES_FIELD = "axes";
+/**
+* This entry's composition config. The field is `.volatile()` because 0.1.7
+* refuses an entry with no volatile field outright
+* (`packages/settings/settings/src/index.ts:385-386`) and because path writes
+* are refused for every non-volatile path (`:387-389`).
+*
+* `z.dict(z.any())` rather than a per-session object schema: the keys are session
+* ids, which no schema can enumerate, and the VALUES are validated by
+* {@link parseSessionAxesField}, where an unreadable axis becomes a throw rather
+* than an invented boundary — the same rule the row's own axes follow.
+*
+* Annotated rather than inferred: `z.dict`'s output names `Dict` from
+* `@deepseek-ai/cosmokit`, and declaration emit refuses a type it can only reach
+* through a nested `node_modules` path (TS2883). The annotation states the same
+* type through that package's own entry.
+*/
+const Config$1 = z.object({ axes: z.dict(z.any()).default({}).volatile() });
+/**
+* The pair {@link SessionAxesStore.getOr} answers for a session with no stored
+* record, and nothing else.
+*
+* It is deliberately NOT what a session with no record is held to any more:
+* every live read goes through {@link SessionAxesStore.ensure}, which answers the
+* deployment's seed ({@link seedAxesFor}), so the pair in force is the pair the
+* session was created with rather than the built-in one. Reaching for this
+* constant on a decision path would hold a session to a boundary the settings
+* page never chose — narrower than an `all` default, wider than a `deny` one.
+* @see SessionAxesStore.getOr
+*/
+const DEFAULT_AXES = {
+	read: DEFAULT_READ_SCOPE,
+	write: DEFAULT_WRITE_SCOPE
+};
+/**
+* The axis pair a session with no stored record is REPAIRED to — the same seed a
+* newly created session is pinned with.
+*
+* Repairing to the standing pair instead (`DEFAULT_AXES`) would be narrower but wrong: a
+* session whose creation-time write was lost would keep the built-in defaults
+* for the rest of its life, and the settings page's seed would never reach it.
+* Repairing to the seed keeps `pin`'s retry semantics intact — the retry just
+* happens on the next touch of the session instead of only at creation.
+*
+* The seed is computed from two synchronous reads: the settings row's
+* `read`/`write`/`defaultGroups` (seeds for a session that has none of its own)
+* and, for a subagent child, the parent's pair AS IT STANDS NOW. A parent with
+* no record of its own yields `undefined` from {@link inheritedAxes}, which is
+* the same answer `pin` gets, so parent and child agree in that case too.
+* @param ctx - host context; carries the settings service the seed is read from.
+* @param session - the session to seed.
+* @param fallback - the composing plugin's own config, used only when no settings
+*   service is mounted (where the namespace cannot be written anyway).
+* @returns the pair a newly created session would have been pinned with.
+*/
+function seedAxesFor(ctx, session, fallback) {
+	const section = declaredSection(ctx);
+	const inherited = inheritedAxes(ctx, session);
+	if (section === void 0) return seedGroupReferences(inherited ?? fallback?.axes ?? DEFAULT_AXES, fallback?.groups ?? []);
+	return seedPair(section, inherited);
+}
+/**
+* The pure core of {@link seedAxesFor}: one settings row value, plus the pair a
+* subagent child inherits, into the pair a session with no record is seeded with.
+*
+* It is TOTAL on purpose, and the client half mirrors it step for step
+* (`sessionAxesSeed` in `@t4r71/dsh-dual-axis-ui`, pinned by
+* `tests/seed-parity.spec.ts`): an unreadable row, and an unreadable inherited
+* pair, answer {@link DEFAULT_AXES}. That is also what a live read answers — see
+* {@link SessionAxesStore.ensure} — so the pair a picker shows for a session with
+* no record and the pair the host enforces are one value rather than two.
+* @param row - the settings row's value, untrusted: a human may have edited it.
+* @param inherited - the parent's pair for a subagent child, or `undefined`.
+* @returns the seed pair.
+*/
+function seedPair(row, inherited) {
+	try {
+		return seedGroupReferences(inherited === void 0 ? axesOf(row) : pairOf(inherited), defaultGroupIds(row));
+	} catch {
+		return DEFAULT_AXES;
+	}
+}
+/**
+* Re-normalize a pair another reader produced.
+*
+* A pair this package stored is already normalized; a hand-edited document's is
+* not, and the inherited pair the client half reads comes straight off the wire.
+* Running both through the same validation is what makes the two halves agree on
+* the bytes, not merely on the kinds.
+* @param pair - the untrusted pair.
+* @returns the normalized pair.
+* @throws When either member is not a legal axis value.
+*/
+function pairOf(pair) {
+	return {
+		read: normalizeScope("read", pair.read),
+		write: normalizeScope("write", pair.write)
+	};
+}
+/**
+* The pair a **subagent child session** inherits, or `undefined` when this is not
+* a child or its parent holds no record.
+*
+* A child does not read the settings page: 0.1.7 deliberately seeds a child with
+* its parent's explicit per-session override, and the parent's STORED pair is the
+* only copy of that override this package has. Returning `undefined` (rather than
+* inventing one) leaves the caller on the settings seed, which is what the child
+* would have received had the parent never overridden anything — and is exactly
+* the pair an un-recorded parent is itself held to.
+*
+* The record is looked up by the id the child's header names. The parent's own
+* Session object is NOT required: requiring it made the answer depend on whether
+* the parent happened to be resident in this process, and the client half — which
+* reads the same document by the same id — cannot observe residency, so the two
+* would disagree for a child whose parent is not materialized.
+* @param ctx - host context carrying the axis store.
+* @param session - the session whose parent to read.
+* @returns the parent's pair, or `undefined`.
+*/
+function inheritedAxes(ctx, session) {
+	if (session.header.origin !== "subagent") return void 0;
+	const parentId = session.header.parentSession;
+	if (parentId === void 0) return void 0;
+	return sessionAxesStore(ctx).get(String(parentId));
+}
+/** Milliseconds before attempt N is issued, N counted from zero. */
+const AXES_WRITE_BACKOFF_MS = [
+	0,
+	25,
+	75,
+	200
+];
+/**
+* A whole-document write was refused because another writer moved the settings
+* document between this writer's read and its write.
+*
+* It is thrown, never swallowed: the axis a person just picked is not in force
+* unless it was stored, and reporting success for a lost write would leave the
+* fence enforcing a range the picker does not show.
+*/
+var SessionAxesConflictError = class extends Error {
+	/** Stable machine code for callers that map failures to their own taxonomy. */
+	code = "DUAL_AXIS_AXES_CONFLICT";
+	/** The namespace whose write was refused. */
+	ns = SESSION_AXES_NAMESPACE;
+	/** Attempts made before giving up. */
+	attempts;
+	/**
+	* @param cause - the last conflict the settings service raised.
+	* @param attempts - attempts made before giving up.
+	*/
+	constructor(cause, attempts) {
+		super("dual-axis: the settings document changed under this writer " + String(attempts) + " times while storing a session axis pair; nothing was written", { cause });
+		this.name = "SessionAxesConflictError";
+		this.attempts = attempts;
+	}
+};
+/**
+* Whether two narrowing reports say the same thing, so a republish that changes
+* nothing does not write the document.
+* @param left - one report, absent when nothing was ever published.
+* @param right - the other, absent under the same condition.
+* @returns whether both report the same removal.
+*/
+function sameNarrowing(left, right) {
+	if (left === void 0 || right === void 0) return false;
+	return left.narrowed === right.narrowed && left.lostUnbounded === right.lostUnbounded && left.droppedRoots.length === right.droppedRoots.length && left.droppedRoots.every((root) => right.droppedRoots.includes(root));
+}
+/**
+* Whether a value is a plain data object.
+* @param value - the candidate.
+* @returns whether it is an object that is not null and not an array.
+*/
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Read one stored record into an axis pair, or throw naming the member that is
+* unreadable.
+* @param id - the session id the record belongs to, for the error message.
+* @param value - the untrusted record.
+* @returns the validated pair.
+* @throws When either member is not a legal axis value.
+*/
+function parseSessionAxesRecord(id, value) {
+	if (!isRecord(value)) throw new Error("dual-axis: the stored axes of session " + JSON.stringify(id) + " must be an object");
+	const narrowing = parseNarrowing(value.narrowing);
+	return {
+		read: normalizeScope("read", value.read ?? DEFAULT_READ_SCOPE),
+		write: normalizeScope("write", value.write ?? DEFAULT_WRITE_SCOPE),
+		...narrowing.narrowed ? { narrowing } : {}
+	};
+}
+/**
+* Read the whole stored field. A human may have edited the settings document, so
+* an unreadable entry throws instead of being dropped: dropping it would silently
+* widen that session back to the deployment defaults.
+* @param value - the untrusted `axes` field.
+* @returns every stored pair, by session id.
+* @throws When the field is not an object of readable records.
+*/
+function parseSessionAxesField(value) {
+	if (value === void 0 || value === null) return {};
+	if (!isRecord(value)) throw new Error("dual-axis: the stored session axes field must be an object");
+	const parsed = {};
+	for (const [id, record] of Object.entries(value)) parsed[id] = parseSessionAxesRecord(id, record);
+	return parsed;
+}
+/**
+* The stored pair as this package spells it everywhere else. The stored record is
+* already a pair; this exists so the store's return type is the shared one and a
+* caller cannot start depending on the record's identity.
+* @param record - the stored pair.
+* @returns the same pair.
+*/
+function scopesOf(record) {
+	return {
+		read: record.read,
+		write: record.write
+	};
+}
+/**
+* The read and write face of {@link SESSION_AXES_NAMESPACE}, plus the sweep that
+* keeps it from growing with the sessions that no longer exist.
+*
+* Reads go through `settings.describe()`, the same projection the settings page
+* renders from, and are memoized on the namespace's `revision` — which 0.1.7 bumps
+* exactly when that entry's stored profile override changes
+* (`packages/settings/settings/src/index.ts:311-317`). A decision path therefore
+* pays one `describe()` per document change, not one per tool dispatch.
+*/
+var SessionAxesStore = class {
+	ctx;
+	options;
+	cachedRevision;
+	cachedRecords = {};
+	/** Parsed records by the JSON spelling that produced them. */
+	bySpelling = /* @__PURE__ */ new Map();
+	/**
+	* Session ids with a repair write outstanding (or already landed) since the
+	* record was found missing. Prevents one repair per tool dispatch while the
+	* whole-document write is in flight; cleared when a write FAILS so the next
+	* touch retries instead of leaving the session on the defaults forever.
+	*/
+	repairing = /* @__PURE__ */ new Set();
+	/**
+	* The last narrowing report this store handed to a write, by session id. A
+	* decision path re-resolves on every touch, so this is what keeps it from
+	* queueing the same document write over and over; it is cleared when a write
+	* lands (or fails), never on a read.
+	*/
+	narrowingMemo = /* @__PURE__ */ new Map();
+	/** Sessions with a narrowing write outstanding right now. */
+	narrowingWriting = /* @__PURE__ */ new Set();
+	/**
+	* @param ctx - host context; the settings service is looked up, never injected,
+	*   so a composition without settings still loads this package's fence.
+	* @param options - retry policy and the sleep used between attempts.
+	*/
+	constructor(ctx, options = {}) {
+		this.ctx = ctx;
+		this.options = {
+			attempts: options.attempts ?? 4,
+			backoffMs: options.backoffMs ?? AXES_WRITE_BACKOFF_MS,
+			sleep: options.sleep ?? ((ms) => new Promise((resolve) => {
+				setTimeout(resolve, ms);
+			}))
+		};
+	}
+	/**
+	* This namespace's current settings row, or `undefined` when no settings
+	* service is mounted or the entry is not composed.
+	* @returns the descriptor carrying the value and the revision.
+	*/
+	descriptor() {
+		const settings = this.ctx.get("settings");
+		if (settings === void 0) return void 0;
+		return settings.describe().find((row) => row.ns === SESSION_AXES_NAMESPACE);
+	}
+	/**
+	* Every stored pair, by session id.
+	* @returns the parsed field.
+	* @throws When the document carries an unreadable record.
+	*/
+	records() {
+		const descriptor = this.descriptor();
+		if (descriptor === void 0) return {};
+		if (descriptor.revision === this.cachedRevision) return this.cachedRecords;
+		const value = isRecord(descriptor.value) ? descriptor.value[SESSION_AXES_FIELD] : void 0;
+		const spelling = JSON.stringify(value ?? null);
+		let records = this.bySpelling.get(spelling);
+		if (records === void 0) {
+			records = parseSessionAxesField(value);
+			this.bySpelling.set(spelling, records);
+		}
+		this.cachedRevision = descriptor.revision;
+		this.cachedRecords = records;
+		return records;
+	}
+	/**
+	* One session's stored pair.
+	* @param sessionId - the session whose axes to read.
+	* @returns the pair, or `undefined` when this session has no record yet.
+	*/
+	get(sessionId) {
+		const record = this.records()[sessionId];
+		return record === void 0 ? void 0 : scopesOf(record);
+	}
+	/**
+	* One session's stored pair, or the built-in defaults.
+	*
+	* The answer for a caller that has no session to build a seed from, and the only
+	* remaining reader of {@link DEFAULT_AXES}. Every live path reads {@link ensure}
+	* instead, whose un-recorded answer is the session's own seed.
+	* @param sessionId - the session whose axes to read.
+	* @returns the pair in force.
+	*/
+	getOr(sessionId) {
+		return this.get(sessionId) ?? DEFAULT_AXES;
+	}
+	/**
+	* One session's pair, with an un-recorded session scheduled for repair.
+	*
+	* This is the read every LIVE touch point uses (the model-facing prompt, the
+	* read fence, and `/axis`). A session that has a record answers it; a session
+	* that has none answers {@link seedAxesFor} — the pair `pin` writes for a newly
+	* created session — and that ONE value is both this read's answer and what the
+	* scheduled repair stores. The answer and the write therefore cannot disagree,
+	* and a session created under a saved default runs under that default from its
+	* FIRST turn instead of waiting for the record to land. The record is what
+	* answers from the moment it lands.
+	*
+	* An un-recorded session is only REPAIRED when it has been used
+	* ({@link hasContent}). Until then the seed is recomputed on every read, so the
+	* settings row stays live: a session the workspace picker reopens before anyone
+	* has sent anything follows the settings page, which is the whole point of not
+	* having a record yet. The moment a turn lands, the next read repairs the
+	* session and it freezes — the same seed it answered with, computed from the row
+	* as it then stood.
+	*
+	* The seed is a thunk because only the caller can build it (it needs the
+	* session, and the composing plugin's config for a settings-less host). It is
+	* evaluated exactly once per un-recorded read — those reads are a prompt
+	* assembly, a tool dispatch and a pick, never a hot loop — and it must have no
+	* side effect, because its value IS this read's answer.
+	* @param sessionId - the session whose axes to read.
+	* @param seed - builds the pair a repair persists AND this read answers; never
+	*   called when a record exists.
+	* @param frozen - whether the session has been used, so its pair must be
+	*   written rather than recomputed. Defaults to `true`: a caller that cannot
+	*   judge the session's content keeps the pre-existing freeze-on-first-touch
+	*   behaviour, which is the safe direction — it never widens a live session's
+	*   axes behind the person's back.
+	* @returns the pair in force right now.
+	*/
+	ensure(sessionId, seed, frozen = true) {
+		const standing = this.get(sessionId);
+		if (standing !== void 0) return standing;
+		let seeded;
+		try {
+			seeded = seed();
+		} catch {
+			if (frozen) this.scheduleRepair(sessionId, seed);
+			return DEFAULT_AXES;
+		}
+		if (frozen) this.scheduleRepair(sessionId, () => seeded);
+		return seeded;
+	}
+	/**
+	* Publish the narrowing a live read just resolved, when the record does not
+	* already carry it.
+	*
+	* This is how the client half learns what the read axis removed from the write
+	* range without re-implementing the path algebra: it reads this member out of
+	* the same document its two dropdowns already read. The value comes from the
+	* very resolution the prompt and the fence used, so the surfaced narrowing and
+	* the enforced one are one computation rather than two that must agree.
+	*
+	* Called on every touch of a session that references groups, so an edit to a
+	* group's rules is republished by the next touch instead of waiting for the
+	* record to be rewritten for another reason. A session with no record is left
+	* alone: its axes are recomputed from the settings row on every read, and a
+	* store of its own would freeze that. Writes are fire-and-forget — a caller is
+	* a synchronous decision path and its answer must not depend on a document
+	* write.
+	* @param sessionId - the session whose narrowing to publish.
+	* @param narrowing - the value {@link resolveEffectiveAxes} returned for it.
+	*/
+	refreshNarrowing(sessionId, narrowing) {
+		const record = this.records()[sessionId];
+		if (record === void 0) return;
+		const stored = record.narrowing;
+		if (stored === void 0 && !narrowing.narrowed) return;
+		if (sameNarrowing(stored, narrowing)) {
+			this.narrowingMemo.delete(sessionId);
+			return;
+		}
+		if (sameNarrowing(this.narrowingMemo.get(sessionId), narrowing)) return;
+		this.narrowingMemo.set(sessionId, narrowing);
+		this.writeNarrowing(sessionId, narrowing);
+	}
+	/**
+	* Store one narrowing report for a session that already has a record, at most
+	* once per value.
+	*
+	* A failed write only forgets what was attempted: the next touch republishes
+	* the same report, and the dropdowns keep showing the last stored one instead
+	* of nothing. It never touches the axes, so a refresh that loses its race
+	* cannot revert a pick.
+	* @param sessionId - the session to update.
+	* @param narrowing - the report to store.
+	*/
+	writeNarrowing(sessionId, narrowing) {
+		if (this.narrowingWriting.has(sessionId)) return;
+		this.narrowingWriting.add(sessionId);
+		Promise.resolve().then(async () => {
+			const record = this.records()[sessionId];
+			if (record === void 0) return;
+			const stored = record.narrowing;
+			if (stored === void 0 && !narrowing.narrowed) return;
+			if (sameNarrowing(stored, narrowing)) return;
+			const { narrowing: _retired, ...axes } = record;
+			await this.replaceRecords({
+				...this.records(),
+				[sessionId]: {
+					...axes,
+					...narrowing.narrowed ? { narrowing } : {}
+				}
+			});
+		}).catch((error) => {
+			this.ctx.logger?.warn("dual-axis: could not store the narrowing of session \"%s\"; the dropdowns keep the last stored report", sessionId);
+			this.ctx.logger?.warn(error);
+		}).finally(() => {
+			this.narrowingWriting.delete(sessionId);
+			this.narrowingMemo.delete(sessionId);
+		});
+	}
+	/**
+	* Store one session's pair, whole-document, and report a lost write loudly.
+	*
+	* A single `replace` of the field: removal needs the whole map anyway, and a
+	* per-id path write cannot prune. Every attempt re-reads the revision, so an
+	* edit that landed between the read and the write is retried against the value
+	* it produced instead of being overwritten from a stale snapshot.
+	* @param sessionId - the session the pair belongs to.
+	* @param axes - the pair to store.
+	* @throws {SessionAxesConflictError} when every attempt lost the revision race.
+	* @throws When no settings service serves this namespace.
+	*/
+	async set(sessionId, axes, narrowing) {
+		await this.replaceRecords({
+			...this.records(),
+			[sessionId]: {
+				read: axes.read,
+				write: axes.write,
+				...narrowing === void 0 || !narrowing.narrowed ? {} : { narrowing }
+			}
+		});
+		if (narrowing !== void 0) this.narrowingMemo.set(sessionId, narrowing);
+	}
+	/**
+	* Persist one un-recorded session's seed, at most once until it lands.
+	*
+	* Fire-and-forget on purpose: every caller is a synchronous decision path
+	* (a tool dispatch, a prompt assembly) that cannot await a whole-document
+	* write, and none of them may fail because the repair could not be stored —
+	* the answer that read already gave stands either way. A failed repair is
+	* logged and re-armed.
+	* @param sessionId - the session to repair.
+	* @param seed - builds the pair to persist; may throw on an unreadable document.
+	*/
+	scheduleRepair(sessionId, seed) {
+		if (this.repairing.has(sessionId)) return;
+		this.repairing.add(sessionId);
+		Promise.resolve().then(async () => {
+			if (this.get(sessionId) !== void 0) return;
+			await this.set(sessionId, seed());
+			this.repairing.delete(sessionId);
+		}).catch((error) => {
+			this.repairing.delete(sessionId);
+			this.ctx.logger?.warn("dual-axis: could not store the axes of session \"%s\"; it stays on the default pair", sessionId);
+			this.ctx.logger?.warn(error);
+		});
+	}
+	/**
+	* Prune records whose session no longer exists.
+	*
+	* The deletion signal is the persistence layer itself: a session whose id is
+	* absent from `sessionPersistence.list()` has no stored log. `session/disposed`
+	* is NOT that signal — residency churn disposes a session whose file is still on
+	* disk, and dropping its axes there would silently reset a session that is about
+	* to be resumed.
+	* @returns the ids dropped, or `undefined` when the sweep cannot judge (no
+	*   persistence service mounted, or a listing failed): an unjudgeable sweep
+	*   removes nothing.
+	*/
+	async sweep() {
+		const records = this.records();
+		const ids = Object.keys(records);
+		if (ids.length === 0) return {
+			removed: [],
+			before: 0
+		};
+		const persistence = this.ctx.get("sessionPersistence");
+		if (persistence === void 0) return void 0;
+		let live;
+		try {
+			const listed = await persistence.list();
+			live = new Set(listed.map((snapshot) => String(snapshot.header.id)));
+		} catch (error) {
+			this.ctx.logger?.warn("dual-axis: could not list stored sessions, keeping every axis record");
+			this.ctx.logger?.warn(error);
+			return;
+		}
+		const kept = {};
+		const removed = [];
+		for (const id of ids) {
+			const record = records[id];
+			if (record === void 0) continue;
+			if (live.has(id)) kept[id] = record;
+			else removed.push(id);
+		}
+		if (removed.length === 0) return {
+			removed: [],
+			before: ids.length
+		};
+		await this.replaceRecords(kept);
+		return {
+			removed,
+			before: ids.length
+		};
+	}
+	/**
+	* Replace the whole field, retrying while the revision fence refuses it.
+	* @param records - the complete next field.
+	* @throws {SessionAxesConflictError} when every attempt was refused.
+	*/
+	async replaceRecords(records) {
+		const settings = this.ctx.get("settings");
+		const entryExists = this.descriptor() !== void 0;
+		if (settings === void 0 || !entryExists) throw new Error("dual-axis: no configurable plugin entry \"dual-axis-sessions\"; the session axis store cannot be written");
+		let conflict;
+		for (let attempt = 0; attempt < this.options.attempts; attempt += 1) {
+			const backoff = this.options.backoffMs[attempt] ?? this.options.backoffMs[this.options.backoffMs.length - 1] ?? 0;
+			if (backoff > 0) await this.options.sleep(backoff);
+			const revision = this.descriptor()?.revision;
+			try {
+				await settings.replace(SESSION_AXES_NAMESPACE, { [SESSION_AXES_FIELD]: records }, revision);
+				return;
+			} catch (error) {
+				conflict = error;
+			}
+		}
+		throw new SessionAxesConflictError(conflict, this.options.attempts);
+	}
+};
+/** Stores by host context, so every consumer of one process shares one cache. */
+const stores = /* @__PURE__ */ new WeakMap();
+/**
+* The store of one host context. Consumers hold no service of their own: the
+* fence and the prompt must keep working in a composition that never mounted the
+* settings service, where the store simply has nothing to read.
+* @param ctx - host context.
+* @returns the shared store.
+*/
+function sessionAxesStore(ctx) {
+	const existing = stores.get(ctx);
+	if (existing !== void 0) return existing;
+	const created = new SessionAxesStore(ctx);
+	stores.set(ctx, created);
+	return created;
+}
+/**
+* This entry's plugin body.
+*
+* The entry exists for its Config: `SettingsForms.describe` projects the schemas
+* of LOADED entries, so the session axis store has no namespace to live in until
+* a Loader row activates with this plugin. The body itself does nothing — every
+* read and write goes through {@link SessionAxesStore}, which the composing
+* plugin owns.
+* @returns nothing.
+*/
+async function apply$1() {}
+Object.assign(apply$1, { Config: Config$1 });
+Object.defineProperty(apply$1, "name", {
+	value: "dual-axis-sessions",
+	configurable: true
+});
+//#endregion
+//#region lib/types/scope-prompt.js
+/**
+* The model-facing text of the two access axes: ONE source for both the
+* runtime-context paragraph the model reads before it acts and the refusal a
+* fence returns when it acts anyway.
+*
+* Why one module: the paragraph and the refusal must state the same range. Two
+* hand-written copies drift, and the drift is invisible — the model would plan
+* against one boundary in its context and be denied by a different one. Both
+* callers therefore call {@link renderAxisRange} for the range sentence and
+* share {@link NO_BYPASS} and {@link WIDENING_EXIT} verbatim; neither string is
+* spelled anywhere else in this package.
+*
+* Both callers feed it only session-log facts plus the group definitions the
+* log's ids resolve against: the axis preset is the `dual-axis/scopes` fold (the
+* projection unit), the workspace root is the session header's `cwd`, and the
+* group library is the settings row's `groups` field. Nothing here reads ambient
+* state of its own, so the rendered text is reconstructable from the log and
+* that library.
+*
+* @module @t4r71/dsh-dual-axis/scope-prompt
+*/
+/** Render one path list for the model; an empty list is stated, never left blank. */
+function renderRoots(roots) {
+	return roots.length === 0 ? "(none)" : JSON.stringify(roots);
+}
+/**
+* Render one axis as the concrete places it permits and forbids, with the
+* configured entries already resolved to canonical absolute roots.
+*
+* A model plans against directories, not at mode names: `workspace` alone
+* leaves it guessing whether the platform temp areas count, and `custom`
+* leaves it guessing which paths were added or removed. {@link resolveScope}
+* answers both, so this prints its result instead of the axis value.
+*
+* A `custom` axis whose entries cannot be resolved (a foreign or hand-edited
+* log carrying a relative path, which `ScopeConfigError` refuses) is stated as
+* permitting nothing rather than throwing: the paragraph must not fail the
+* whole assembly, and a range that cannot be evaluated must never read as a
+* wider one.
+* @param axis - the axis value in force.
+* @param workspaceRoot - the session workspace root a `workspace` and `custom` axis resolve against.
+* @returns the range sentence, e.g. `kind custom; allowed roots: ["C:\\ws"]; denied roots: ["C:\\ws\\secret"] (a denied path always wins)`.
+*/
+function renderAxisRange(axis, workspaceRoot) {
+	let resolved;
+	try {
+		resolved = resolveScope(axis, { workspaceRoot });
+	} catch (error) {
+		const reason = error instanceof Error ? error.message : String(error);
+		return `kind ${axis.kind}; the configured entries could not be resolved (${reason}), so no path is known to be allowed`;
+	}
+	const allowed = resolved.unbounded ? "every path on this host except the denied roots below" : renderRoots(resolved.allow);
+	const denied = resolved.deny.length === 0 ? renderRoots(resolved.deny) : `${renderRoots(resolved.deny)} (a denied path always wins)`;
+	return `kind ${axis.kind}; allowed roots: ${allowed}; denied roots: ${denied}`;
+}
+/**
+* The sentence reporting what the write-never-exceeds-read invariant removed.
+*
+* Stated because the removal is otherwise invisible: a rule group that grants
+* write access to a directory the read axis does not cover grants nothing, and a
+* user who cannot see that concludes the rule was ignored. Empty when the
+* intersection removed nothing, so a session that narrowed nothing is not
+* warned about a narrowing that did not happen.
+* @param narrowing - what the resolution removed from the write axis.
+* @returns the sentence, or the empty string when nothing was removed.
+*/
+function renderNarrowing(narrowing) {
+	if (!narrowing.narrowed) return "";
+	const parts = [];
+	if (narrowing.droppedRoots.length > 0) parts.push(`the read axis removed ${renderRoots(narrowing.droppedRoots)} from it`);
+	if (narrowing.lostUnbounded) parts.push("it was unbounded, and the read range is now its entire bound");
+	return "The read axis narrowed this write range: " + parts.join(", and ") + ". A write axis or rule group naming a path outside the read range grants nothing there — the write is refused, not silently allowed.";
+}
+/**
+* The notice stating that a session's axis preset could not be resolved, so no
+* path is known to be allowed.
+*
+* Rendered both into the prompt and into a refusal, from this one source: an
+* unresolvable reference — a rule group deleted while a session still references
+* it — must fail closed everywhere it is met, and must say which id is missing
+* rather than behaving like a group that allows nothing in particular.
+* @param problem - the resolution failure, naming the offending id.
+* @returns the model-facing notice.
+*/
+function unresolvedAxesNotice(problem) {
+	return "This session's file access axes could not be resolved, so no path is known to be allowed: " + problem + ". The reference is refused rather than read as an empty rule group, because a rule that silently does nothing is worse than a refusal. The only compliant moves are: (1) complete the task inside the allowed range above, or (2) ask the user to widen that axis for this session — the settings page lists the dual-axis row, and the two dropdowns above the composer switch the same two axes.";
+}
+/**
+* The refusal a fence returns for one path, built from the same range sentence
+* the prompt uses.
+* @param input - the refused path, the axis that refused it, and the root it resolves against.
+* @returns the model-facing refusal text.
+*/
+function scopeRefusal(input) {
+	const narrowing = input.axis === "write" && input.narrowing !== void 0 ? renderNarrowing(input.narrowing) : "";
+	return `Access denied: ${JSON.stringify(input.displayPath)} is outside this session's ${input.axis} axis. ${input.axis} axis in force — ${renderAxisRange(input.scope, input.workspaceRoot)}. ` + (narrowing === "" ? "" : narrowing + " ") + "This is not a limitation of the tool you called: switching to another tool, spawning a child process, writing a script, or calling a command tool does not make the path allowed — reaching it by any other route is still a violation of the session rule. The fence is also not one layer, but the layers differ per axis: the read axis, and the allow/deny PATH entries of the effective write range, are enforced at the tool layer, and bind only the tools that layer sees. The BASE tier of the effective write range — the narrower of the two axes' bases — is enforced a second time below the tool layer: it is mirrored onto the session sandbox mode that the command tools themselves run under, so a \"workspace\" or \"deny\" base keeps holding for a shell command. An effective write range based on \"all\" mirrors to no sandbox restriction at all, so nothing below the tool layer holds it. The only compliant moves are: (1) complete the task inside the allowed range above, or (2) ask the user to widen that axis for this session — the settings page lists the dual-axis row, and the two dropdowns above the composer switch the same two axes.";
+}
+//#endregion
+//#region lib/types/read-guard.js
+/**
+* 读轴围栏，作为独立入口 `@t4r71/dsh-dual-axis/read-guard`。
+*
+* 为什么读轴需要这一层：0.1.7 的文件系统读路径根本不带会话（`dsh-fs-sandbox` 的读方法只有
+* target 与 signal，只有 writeText / editText 收 per-call policy），所以本包的
+* `DualAxisFileSystem` 即使挂上去，也永远拿不到要判的那条会话的轴，只能退回部署默认。
+* 工具派发层是唯一同时拿得到「这次要动的路径」与「当前会话」的地方：
+*
+*  1. `tools/pre-execute`：异步 waterfall，拿得到 `exec.agent.session` 与 `exec.arguments`，
+*     用 `ctx.fs.resolve` 解析真实身份再做包含判定，返回 `{ kind: 'deny', reason }` 短路，
+*     模型收到的是一条 `Error: <reason>` 的工具结果。
+*  2. `ctx.tools.guard(fn)`：单调同步兜底，在全部 pre-execute 监听器之后、工具体之前运行，
+*     只能把调用判得更严。同步因此只有词法判定，只对 deny 列表判否 —— 显式排除的目录，
+*     身份判定只会把它判得更严，不会判松，所以词法命中 deny 即拒不会误伤。
+*
+* 两轴的执行分工，与 0.1.7 已有的执行点不重叠：
+*  - 读轴：没有任何既有执行点，本模块全量执行（deny 优先，再有界 allow）。
+*  - 写轴：三档封闭取值已由本体沙箱按 `sandbox/mode` 执行（镜像的是两根轴 base 里更窄
+*    的那个，见 `./groups.ts` 的 `narrowerBase`），本模块执行**交集本身的完整范围** ——
+*    交集由读轴带来的那部分收窄是路径级的，那条 mode 事件装不下，只有本层能让它对它看得
+*    见的工具成真。
+*
+* 判定路径的输入只有三样：这条会话按 id 存在本包存储里的轴预设（base + 自己追加的
+* allow/deny + 选中的组 id）、按那些 id 现取的组定义，以及这次调用的目标路径。设置页那一行
+* 的 read/write 默认值与 defaultGroups 是**种子**，本模块一概不读（`./config.ts` 的
+* `groupLibraryValue` 是唯一的读取出口）。轴读的是 `./session-store.ts` 的存储，
+* 不是会话投影 —— 轴已经不在会话日志里。
+*
+* @module @t4r71/dsh-dual-axis/read-guard
+*/
+/** 插件名，loader 诊断用。 */
+const name = "dual-axis-read-guard";
+/** 构造期就要用的服务：缺一个就装载失败，而不是运行期静默放行。 */
+const inject = ["fs", "tools"];
+/** 读入口：参数里的目标路径会被当成读取对象检查。 */
+const READ_TOOLS = {
+	read: "file_path",
+	read_image: "file_path",
+	grep: "path",
+	glob: "path"
+};
+/**
+* 写入口：只补写轴排除表。写的基础档位由本体沙箱按 mode 执行，重复执行它会与本体
+* 对临时区、平台可写根的既有让步打架。
+*/
+const WRITE_TOOLS = {
+	write: "file_path",
+	edit: "file_path",
+	str_replace_editor: "path"
+};
+/** 装载期校验的配置。 */
+const Config = z.object({
+	enabled: z.boolean().default(true),
+	readTools: z.array(z.string()).default(Object.keys(READ_TOOLS)),
+	writeTools: z.array(z.string()).default(Object.keys(WRITE_TOOLS))
+});
+/**
+* 一条会话自己的轴预设：读本包自有的会话轴存储（`./session-store.ts`），
+* 存储里没有这条会话时用这条会话的**种子**（设置页那一行 + 父会话当刻的记录）——
+* 与新会话被钉下的、以及记录缺席时被补写的都是同一份计算。预设里带着组 id，组体不在这里
+* —— 组定义按 id 现取，见 {@link boundaryOf}。
+* @param ctx - 插件上下文，承载设置服务（存储的读路径）。
+* @param session - 发起这次调用的会话。
+* @returns 该会话的轴预设。
+*/
+function presetOf(ctx, session) {
+	return sessionAxesStore(ctx).ensure(String(session.header.id), () => seedAxesFor(ctx, session), hasContent(session));
+}
+/**
+* 一次判定的实际生效范围：会话预设 + 按 id 现取的组定义 → 展开 → 写轴 ∩ 读轴。
+*
+* 组定义只在预设真的引用了组时才去读设置页：引用不到组的会话（绝大多数）因此每次判定
+* 都不碰设置服务，而引用到的会话每次判定都读当刻那一份，改一个组立刻作用于所有引用它的
+* 会话，不需要重启也不需要重开会话。
+*
+* 解算失败（引用了库中不存在的组 id、组库本身读不懂）返回 `ok: false`，由调用方拒绝这次
+* 访问：既不能当成空组放行，也不能抛出去把工具派发整条链打断。
+* @param ctx - 插件上下文，承载轴存储与设置服务。
+* @param session - 发起这次调用的会话。
+* @param root - 这条会话的工作区根，`workspace` 基档按它解析。
+* @returns 实际生效的那一对轴，或失败原因。
+*/
+function boundaryOf(ctx, session, root) {
+	const preset = presetOf(ctx, session);
+	const resolved = resolveEffectiveAxes(preset, referencedGroupIds(preset).length === 0 ? void 0 : groupLibraryValue(declaredSection(ctx)), { workspaceRoot: root });
+	return resolved.ok ? {
+		ok: true,
+		axes: resolved.axes
+	} : {
+		ok: false,
+		problem: resolved.problem
+	};
+}
+/**
+* 从一次调用的参数里取出目标路径拼写。
+* @param tool - 工具名。
+* @param args - 工具参数。
+* @param table - 被检查的工具表。
+* @param allowed - 配置里启用的工具名集合。
+* @returns 目标路径拼写，表外工具或字段缺失时为 undefined（=不检查）。
+*/
+function spelledPath(tool, args, table, allowed) {
+	if (!allowed.has(tool)) return void 0;
+	const field = table[tool];
+	if (field === void 0) return void 0;
+	if (args === null || typeof args !== "object") return void 0;
+	const value = args[field];
+	if (typeof value !== "string" || value.trim().length === 0) return void 0;
+	return value;
+}
+/**
+* 异步包含判定：词法快路径命中的直接用，拼写不同时回落到 provider 自己的 `ctx.fs.contains`
+* —— 它按真实文件系统身份比较，认 Windows 8.3 别名与大小写。
+* @param ctx - 插件上下文。
+* @param targetKey - 目标的规范化身份键。
+* @param root - 参与比较的根。
+* @returns 目标是否落在根之下。
+*/
+async function contained(ctx, targetKey, root) {
+	if (isLexicallyUnder(targetKey, root)) return true;
+	const rootTarget = await ctx.fs.resolve(root);
+	const target = await ctx.fs.resolve(targetKey);
+	return ctx.fs.contains(rootTarget, target);
+}
+/**
+* deny 优先于 allow，unbounded 只是「没有上界」，不豁免 deny —— 与 scopeContains 同序。
+* @param ctx - 插件上下文。
+* @param scope - 已解析的轴取值。
+* @param targetKey - 目标的规范化身份键。
+* @returns 该轴是否放行这个目标。
+*/
+async function permitted(ctx, scope, targetKey) {
+	for (const root of scope.deny) if (await contained(ctx, targetKey, root)) return false;
+	if (scope.unbounded) return true;
+	for (const root of scope.allow) if (await contained(ctx, targetKey, root)) return true;
+	return false;
+}
+/**
+* The refusal one dispatch returns for one target. The text itself lives in
+* `./scope-prompt.ts` and is the SAME source the runtime-context paragraph
+* renders from, so the range the model read before it acted and the range it is
+* denied by cannot disagree.
+* @param target - the refused target, with the axis that refused it.
+* @param displayPath - the path as the model should see it.
+* @param scope - the refusing axis's value.
+* @param narrowing - what the read axis removed from the write range, for a write refusal.
+* @returns the model-facing refusal text.
+*/
+function refusal(target, displayPath, scope, narrowing) {
+	return scopeRefusal({
+		displayPath,
+		axis: target.axis,
+		scope,
+		workspaceRoot: target.root,
+		...narrowing === void 0 ? {} : { narrowing }
+	});
+}
+/**
+* 取出这次调用的目标，表外工具返回 undefined。
+* @param execution - 一次工具执行。
+* @param readAllowed - 启用的读入口。
+* @param writeAllowed - 启用的写入口。
+* @returns 目标，或 undefined。
+*/
+function targetOf(execution, readAllowed, writeAllowed) {
+	const session = execution.agent?.session;
+	if (session === void 0) return void 0;
+	const root = session.header.cwd;
+	if (root === void 0) return void 0;
+	const read = spelledPath(execution.name, execution.arguments, READ_TOOLS, readAllowed);
+	if (read !== void 0) return {
+		axis: "read",
+		spelled: read,
+		session,
+		root
+	};
+	const write = spelledPath(execution.name, execution.arguments, WRITE_TOOLS, writeAllowed);
+	if (write !== void 0) return {
+		axis: "write",
+		spelled: write,
+		session,
+		root
+	};
+}
+/**
+* 注册两层的轴围栏。
+* @param ctx - 插件上下文；两个注册都挂在它上面，随它一起卸载。
+* @param config - 装载期已校验的配置。
+*/
+async function apply(ctx, config = {}) {
+	if (!(config.enabled ?? true)) return;
+	const readAllowed = new Set(config.readTools ?? Object.keys(READ_TOOLS));
+	const writeAllowed = new Set(config.writeTools ?? Object.keys(WRITE_TOOLS));
+	ctx.on("tools/pre-execute", async (exec, next) => {
+		const target = targetOf(exec, readAllowed, writeAllowed);
+		if (target === void 0) return next();
+		const boundary = boundaryOf(ctx, target.session, target.root);
+		if (!boundary.ok) return {
+			kind: "deny",
+			reason: unresolvedAxesNotice(boundary.problem)
+		};
+		const axis = boundary.axes[target.axis];
+		const scope = resolveScope(axis, { workspaceRoot: target.root });
+		if (scope.unbounded && scope.deny.length === 0) return next();
+		const resolved = await ctx.fs.resolve(target.spelled, {
+			cwd: target.root,
+			signal: exec.signal
+		});
+		if (await permitted(ctx, scope, resolved.targetKey)) return next();
+		return {
+			kind: "deny",
+			reason: refusal(target, resolved.displayPath, axis, boundary.axes.narrowing)
+		};
+	});
+	const guard = (execution) => {
+		const target = targetOf(execution, readAllowed, writeAllowed);
+		if (target === void 0) return void 0;
+		const boundary = boundaryOf(ctx, target.session, target.root);
+		if (!boundary.ok) return unresolvedAxesNotice(boundary.problem);
+		const axis = boundary.axes[target.axis];
+		const scope = resolveScope(axis, { workspaceRoot: target.root });
+		if (scope.deny.length === 0) return void 0;
+		const targetKey = resolve(target.root, target.spelled);
+		for (const denyRoot of scope.deny) if (isLexicallyUnder(targetKey, denyRoot)) return refusal(target, target.spelled, axis, boundary.axes.narrowing);
+	};
+	ctx.tools.guard(guard);
+}
+/**
+* 默认导出必须自带 inject / Config / name：Loader.unwrapExports 返回 exports.default 并丢掉
+* 兄弟具名导出（vendor/loader/src/index.ts:201-208），而 registry 只读 plugin.inject
+* （vendor/cordis/src/registry.ts:330）—— 挂不上就会不等服务先激活，首次读 ctx.tools 抛错。
+*/
+var read_guard_default = Object.assign(apply, {
+	inject,
+	Config
+});
+Object.defineProperty(apply, "name", {
+	value: name,
+	configurable: true
+});
+//#endregion
+export { Config, read_guard_default as default, inject, name };