@sema-agent/core 7.16.0 → 7.17.1

package/dist/core/mcp.js

@@ -1,5 +1,6 @@
 import { redactSecrets } from "./untrusted-egress.js";
-import { announceEnvKnob, __resetEnvKnobAnnouncements } from "./env-knob-announce.js";
+import { __resetEnvKnobAnnouncements } from "./env-knob-announce.js";
+import { resolveEnvBudget } from "./env-budget.js";
 import { MCP_NAMESPACE } from "./protocol-table.js";
 import { findNamespacePrefixCollision, mintNamespacePrefix, mintNamespacedToolName, normalizeNameSegment } from "./protocol-naming.js";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
@@ -31,18 +32,7 @@ export function resolveMcpDeclaredResultSize(meta) {
     return Math.min(declared, MCP_META_RESULT_SIZE_CAP);
 }
 function mcpMaxOutputTokens() {
-    const rawEnv = process.env.MAX_MCP_OUTPUT_TOKENS;
-    if (rawEnv === undefined)
-        return MCP_OUTPUT_TOKENS_DEFAULT;
-    const raw = rawEnv.trim();
-    if (raw === "")
-        return MCP_OUTPUT_TOKENS_DEFAULT;
-    const n = parseWholeNumber(raw);
-    if (n === undefined || n <= 0) {
-        announceEnvKnob(`MAX_MCP_OUTPUT_TOKENS=${rawEnv} was ignored — it is not a positive whole number of tokens. Using ${MCP_OUTPUT_TOKENS_DEFAULT} instead.`);
-        return MCP_OUTPUT_TOKENS_DEFAULT;
-    }
-    return n;
+    return resolveEnvBudget(process.env.MAX_MCP_OUTPUT_TOKENS, { name: "MAX_MCP_OUTPUT_TOKENS", unit: "tokens", default: MCP_OUTPUT_TOKENS_DEFAULT });
 }
 function mcpTruncationNote(limitTokens) {
     return (`\n\n[OUTPUT TRUNCATED - exceeded ${limitTokens} token limit]\n\n` +
@@ -114,45 +104,11 @@ export function truncateMcpErrorText(s) {
 export const MCP_TOOL_TIMEOUT_DEFAULT_MS = 100_000_000;
 export const MCP_ENV_MS_MIN = 1_000;
 export const MCP_ENV_MS_MAX = 2_147_483_647;
-const ENV_SCIENTIFIC_RE = /^[+-]?(\d+(\.\d*)?|\.\d+)[eE][+-]?\d+$/;
-const ENV_GROUPED_RE = /^[+-]?\d{1,3}([_,\u00A0\u202F ])\d{3}(?:\1\d{3})*$/;
-const ENV_GROUP_SEPARATORS_RE = /[_,\u00A0\u202F ]/g;
-const ENV_NUMERIC_MAX_LEN = 32;
-function parseWholeNumber(raw) {
-    if (/^[+-]?\d+$/.test(raw)) {
-        const n = Number(raw);
-        return Number.isSafeInteger(n) ? n : undefined;
-    }
-    if (raw.length > ENV_NUMERIC_MAX_LEN)
-        return undefined;
-    if (ENV_SCIENTIFIC_RE.test(raw)) {
-        const n = Number(raw);
-        return Number.isSafeInteger(n) ? n : undefined;
-    }
-    if (ENV_GROUPED_RE.test(raw))
-        return parseInt(raw.replace(ENV_GROUP_SEPARATORS_RE, ""), 10);
-    return undefined;
-}
 export function __resetMcpEnvAnnouncements() {
     __resetEnvKnobAnnouncements();
 }
 function parseEnvMs(name) {
-    const rawEnv = process.env[name];
-    if (rawEnv === undefined)
-        return undefined;
-    const raw = rawEnv.trim();
-    if (raw === "")
-        return undefined;
-    const n = parseWholeNumber(raw);
-    if (n === undefined || n <= 0) {
-        announceEnvKnob(`${name}=${rawEnv} was ignored — it is not a positive whole number of milliseconds. Using the built-in default instead.`);
-        return undefined;
-    }
-    const clamped = Math.min(Math.max(n, MCP_ENV_MS_MIN), MCP_ENV_MS_MAX);
-    if (clamped !== n) {
-        announceEnvKnob(`${name}=${rawEnv} is outside the range this runtime can honor (${MCP_ENV_MS_MIN}..${MCP_ENV_MS_MAX} ms). Using ${clamped}ms instead.`);
-    }
-    return clamped;
+    return resolveEnvBudget(process.env[name], { name, unit: "milliseconds", default: undefined, min: MCP_ENV_MS_MIN, max: MCP_ENV_MS_MAX });
 }
 export function mcpToolTimeoutMs() {
     return parseEnvMs("MCP_TOOL_TIMEOUT") ?? MCP_TOOL_TIMEOUT_DEFAULT_MS;

package/dist/core/memory-engine/engine.js

@@ -4444,7 +4444,8 @@ export class MemoryEngine {
             let wrote = false;
             try {
                 mkdirSync(dirname(indexPath), { recursive: true });
-                writeFileNoFollow(indexPath, text);
+                if (readNoFollowSafe(indexPath) !== text)
+                    writeFileNoFollow(indexPath, text);
                 wrote = true;
             }
             catch {

package/dist/core/memory-engine/layout.d.ts

@@ -1,5 +1,6 @@
 import { type MemoryAnnouncement } from "./types.js";
 import type { AssertAllKeysHandled } from "../ask-origin.js";
+import { physicalPathOfExisting } from "../physical-path.js";
 /** Cursor sidecar for the design/84 Seam B pair on the FileBackend (`{ [scope]: cursor }`). B3: control plane. */
 export declare const CURSORS_FILE = "cursors.json";
 /** The control-plane subdir name under a key dir — ONE spelling for every derivation and for the
@@ -32,10 +33,11 @@ export declare class ControlPlaneCorruptError extends Error {
  * Its input is the HOST-declared repo root; a model-reachable directory is keyed by
  * {@link deriveDirKey} instead, and that asymmetry is deliberate (see there).
  *
- * Known limit, registered rather than fixed (ruled 2026-08-03): on a case-INSENSITIVE volume two
- * spellings that differ only in case still mint two keys — realpath does not case-fold, and folding
- * here would MERGE two genuinely distinct repos on a case-SENSITIVE volume. This round closes the
- * symlink axis only; the case axis predates it and is unchanged.
+ * The case axis (once a known limit here) closes with the same call: the mint answers with the ON-DISK
+ * spelling, so two case-variant spellings name ONE key on a case-INSENSITIVE volume, while on a
+ * case-SENSITIVE volume they are two distinct directories and keep two (FOLDING would merge that pair).
+ * Registered, not fixed: the PREVIOUS key was this realpath with the CALLER's casing = `deriveDirKey`'s
+ * spelling, which the arm below adopts, EXCEPT under a case-varying symlink on a non-folding library.
  */
 export declare function deriveRepoKey(repoRoot: string): string;
 /** Sink for the mount-time partition-key incidents (`memory.partition_split` /
@@ -48,6 +50,9 @@ export type MemoryPartitionIncidentSink = (err: Error & {
  *  when the two mints differ its `memory/` + `.engine/` + siblings live under {@link deriveDirKey}'s
  *  dir. Move the whole partition onto the canonical key (see {@link migrateKeyedPartition}). */
 export declare function adoptLegacyRepoDirs(configRoot: string, repoRoot: string, onIncident?: MemoryPartitionIncidentSink): void;
+/** Every spelling an earlier release keyed this repo's partition by, minus today's: the resolve-only key and the
+ *  link-resolved, caller-cased key (`/var/TMP` keyed `-private-var-TMP`; today `-private-var-tmp`). */
+export declare function earlierRepoKeysOf(repoRoot: string): string[];
 /**
  * The REVERSE one-shot migration (ruled 2026-08-03): for the width of ONE release the control-plane
  * key canonicalized like the repo key does, which put a directory-pinned mount's `.engine` under the
@@ -248,8 +253,10 @@ export declare function layoutNeedsAdoption(root: string, controlDir: string): b
  *   6. commit B: the marker removed; `memory.layout_migrated` disclosed.
  */
 export declare function adoptRootScopeLayout(rootPath: string, controlDir: string, opts?: AdoptRootScopeLayoutOptions): void;
-/** Canonicalize a path for containment checks (resolves symlinks on the EXISTING prefix). */
-export declare function canonicalize(p: string): string;
+/** The memory layout's name for the tree's one physical-path mint (symlinks on the EXISTING prefix
+ *  resolved, the missing tail rejoined). ONE implementation behind both names — a second canonicalizer
+ *  here is what let a key minted by this layout name a directory the fence resolved differently. */
+export declare const canonicalize: typeof physicalPathOfExisting;
 /** True iff `child` (canonicalized) is `root` or inside it. */
 export declare function isContainedIn(root: string, child: string): boolean;
 /** mkdir -p convenience used by the engine/backend (0o700 like the file stores). */
@@ -976,4 +983,9 @@ export declare function writeAllSync(fd: number, data: string): void;
  *  or re-derived); do not route data that can't through here. Throws on failure (fail-closed: a
  *  sidecar that cannot be written must not be silently skipped). */
 export declare function atomicWriteFileSync(path: string, data: string): void;
+/** Content-gated {@link atomicWriteFileSync} for a DERIVED/control-plane file: a byte-identical
+ *  rewrite (the common case on a repeat mount over an unchanged store) is skipped entirely, so the
+ *  file's mtime stays put. ONLY for files whose mtime carries no meaning of its own — a lock or a
+ *  heartbeat file's mtime IS its signal and must keep calling {@link atomicWriteFileSync} directly. */
+export declare function writeIfChanged(path: string, data: string): void;
 export {};

package/dist/core/memory-engine/layout.js

@@ -1,9 +1,10 @@
-import { chmodSync, closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, realpathSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs";
+import { chmodSync, closeSync, constants as fsConstants, copyFileSync, existsSync, fstatSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, readdirSync, renameSync, rmSync, rmdirSync, statSync, unlinkSync, utimesSync, writeFileSync, writeSync } from "node:fs";
 const { O_WRONLY, O_CREAT, O_TRUNC, O_NOFOLLOW, O_EXCL } = fsConstants;
 import { homedir } from "node:os";
 import { createHash } from "node:crypto";
 import { basename, dirname, isAbsolute, join, resolve, sep } from "node:path";
 import { MEMORY_ORIGIN_CAUSES } from "./types.js";
+import { physicalPathOfExisting, priorCallerCasedPathOf } from "../physical-path.js";
 const SCOPES_FILE = "scopes.json";
 export const CURSORS_FILE = "cursors.json";
 export const CONTROL_PLANE_DIR = ".engine";
@@ -84,7 +85,7 @@ function migrateKeyedPartition(m) {
     };
     const splitText = `memory partition split detected for ${m.subject}: BOTH ${m.fromDir} and ${m.toDir} hold content. This session uses ${m.toDir}; the other dir is left untouched (never merged — CAS baselines would collide). If it holds the newer memory, move its rows by hand and remove it.`;
     try {
-        if (m.fromDir === m.toDir)
+        if (m.fromDir === m.toDir || canonicalize(m.fromDir) === canonicalize(m.toDir))
             return;
         if (!existsSync(m.fromDir))
             return;
@@ -113,12 +114,20 @@ function migrateKeyedPartition(m) {
     }
 }
 export function adoptLegacyRepoDirs(configRoot, repoRoot, onIncident) {
-    migrateKeyedPartition({
-        fromDir: join(configRoot, deriveDirKey(repoRoot)),
-        toDir: join(configRoot, deriveRepoKey(repoRoot)),
-        subject: repoRoot,
-        onIncident,
-    });
+    const toDir = join(configRoot, deriveRepoKey(repoRoot));
+    for (const key of earlierRepoKeysOf(repoRoot)) {
+        migrateKeyedPartition({ fromDir: join(configRoot, key), toDir, subject: repoRoot, onIncident });
+    }
+}
+export function earlierRepoKeysOf(repoRoot) {
+    const today = deriveRepoKey(repoRoot);
+    const keys = [deriveDirKey(repoRoot)];
+    try {
+        keys.push(slugifyPath(priorCallerCasedPathOf(resolve(repoRoot))));
+    }
+    catch {
+    }
+    return [...new Set(keys)].filter((k) => k !== today);
 }
 export function adoptCanonicalKeyedControlDir(configRoot, dir, onIncident) {
     migrateKeyedPartition({
@@ -403,6 +412,15 @@ function commitScopesRecord(controlDir, lock, token, next) {
     const data = `${JSON.stringify(next, null, 2)}\n`;
     const fence = () => assertSidecarLockOwnership(lock, token, "scope registry", "strict");
     fence();
+    let current;
+    try {
+        current = readFileSync(file, "utf8");
+    }
+    catch {
+        current = undefined;
+    }
+    if (current === data)
+        return;
     atomicWriteFileSync(journal, data);
     fence();
     atomicWriteFileSync(file, data);
@@ -701,18 +719,7 @@ function moveLooseContent(root, controlDir, rec, owner, label, renew, sink, resu
     writeIndexRevs(controlDir, {});
     discloseLayoutIncident(sink, "memory.layout_migrated", `memory layout adopted at ${root}: ${moved} loose entr${moved === 1 ? "y" : "ies"} moved into the home of ${JSON.stringify(owner)} (${label})${resumed ? " — an interrupted move was finished" : ""}`);
 }
-export function canonicalize(p) {
-    try {
-        return realpathSync(p);
-    }
-    catch {
-        const parent = resolve(p, "..");
-        if (parent === p)
-            return p;
-        const rest = p.slice(parent.endsWith(sep) ? parent.length : parent.length + 1);
-        return join(canonicalize(parent), rest);
-    }
-}
+export const canonicalize = physicalPathOfExisting;
 export function isContainedIn(root, child) {
     const r = canonicalize(root);
     const c = canonicalize(child);
@@ -1034,7 +1041,7 @@ export function readIndexRevs(controlDir) {
 export function writeIndexRevs(controlDir, revs) {
     try {
         ensureDirExists(controlDir);
-        atomicWriteFileSync(join(controlDir, INDEX_REVS_FILE), `${JSON.stringify(revs, null, 2)}\n`);
+        writeIfChanged(join(controlDir, INDEX_REVS_FILE), `${JSON.stringify(revs, null, 2)}\n`);
     }
     catch {
     }
@@ -2056,3 +2063,15 @@ export function atomicWriteFileSync(path, data) {
         throw err;
     }
 }
+export function writeIfChanged(path, data) {
+    let current;
+    try {
+        current = readFileSync(path, "utf8");
+    }
+    catch {
+        current = undefined;
+    }
+    if (current === data)
+        return;
+    atomicWriteFileSync(path, data);
+}

package/dist/core/memory-recall.d.ts

@@ -177,14 +177,6 @@ export declare function composeSelectiveBody(manifestText: string, selected: Mem
  *  widen the public surface (and invite callers to parse the opaque format) for zero consumer. Treat the key
  *  as an opaque token: persist it, feed it back, compare for equality — never split it. */
 export declare function encodeSurfacedKey(scope: string, id: string): string;
-/** A manifest header tagged with the scope it came from (design/84 Seam A decision 5). */
-export interface ScopedNoteHeader extends MemoryNoteHeader {
-    scope: string;
-}
-/** A full record tagged with its scope (for cross-scope getByIds). */
-export interface ScopedNoteRecord extends MemoryNoteRecord {
-    scope: string;
-}
 export interface LayeredRecallOptions {
     store: MemoryStore;
     /** Ordered scopes (design/84 Seam A): list order = priority; the last is highest. */

package/dist/core/memory.d.ts

@@ -233,7 +233,7 @@ export type ConsolidationCapableStore = MemoryStore & Required<Pick<MemoryStore,
  * (design/41): {@link MemoryStore.searchScored}/{@link MemoryStore.update}/{@link MemoryStore.delete}.
  * When false, the Runner skips consolidation entirely (graceful no-op).
  *
- * RB-436-g: a TYPE PREDICATE, so the guard's conclusion travels to the call sites. A bare boolean left
+ * A TYPE PREDICATE, so the guard's conclusion travels to the call sites. A bare boolean left
  * every post-guard call site writing `store.update!(…)`, and a guard that later forgot one of the three
  * would have been invisible — the `!`s keep compiling. Now dropping a method from the check turns the
  * call sites red.

package/dist/core/oracle-isolation.js

@@ -1,5 +1,5 @@
 import { isRemoteExecutionEnv, isIsolated } from "./remote-env.js";
-import { canonicalizeTarget } from "../tools/fs/safety.js";
+import { canonicalizeTarget, pathFamilyOf } from "../tools/fs/safety.js";
 function probeCommand(canonOraclePath) {
     const q = `'${canonOraclePath.replace(/'/g, `'\\''`)}'`;
     return `touch -- ${q}/.oracle-isolation-probe 2>/dev/null`;
@@ -31,7 +31,7 @@ export async function assertOracleIsolation(workerEnv, grader, opts) {
         }
         let writable;
         try {
-            const canon = await canonicalizeTarget(workerEnv, oraclePath, opts?.signal);
+            const canon = await canonicalizeTarget(workerEnv, oraclePath, opts?.signal, pathFamilyOf({ root: oraclePath }));
             if (!canon.ok) {
                 return { protected: false, isolationClass, reason: `cannot canonicalize oracle path "${oraclePath}": ${canon.message}` };
             }

package/dist/core/parent-spec-seat.d.ts

@@ -0,0 +1,66 @@
+/**
+ * The parent SPEC seat a run hands its children — the projection of the fields of the parent's own REBOUND spec
+ * that inherit copy-at-spawn (identity, process facts, deployment facts, the frozen question face) onto ONE value
+ * both delegation lanes copy onto a child spec: `ToolExecuteContext.parentSpecSeat` on the Task lane,
+ * `RunWorkflowToolDeps.parentSpecSeat` → `RunWorkflowOptions.parentSpecSeat` on the workflow lane. Minted once per
+ * prepare (the inherited-gate phase); applied by ONE function ({@link applyParentSpecSeat}) so the two lanes
+ * cannot drift on which fields travel or on the priority between a child's own value and the parent's.
+ *
+ * The checkpoint seat (`./checkpoint-seat.ts`) is the same shape for one field; this seat carries the rest.
+ */
+import type { OnQuestion } from "./ask-question.js";
+import type { ToolExecuteContext } from "./tool-spec.js";
+import type { TaskSpec } from "./types.js";
+/** The fields of a spec the seat carries — one `Pick`, shared by the mint's input and the apply's target. */
+export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "clientContext" | "onQuestion" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable">;
+/**
+ * The seat a run hands its children. Every member is the parent's own value, frozen at mint (arrays copied and
+ * frozen; the facts object copied). Members present iff the parent carries them — an absent member is "nothing to
+ * inherit", never a value.
+ *  · `principal` — the end-user identity (design/62: inherits verbatim, a worker cannot delegate under another).
+ *  · `oneShot` — the process fact ("no later turn"): only `true` travels; it is a REMOVAL (see the apply law).
+ *  · `clientContext` — the user's TZ/email facts (the child's environment block localizes the same way).
+ *  · `onQuestion` — the parent's FROZEN question face (`spec.onQuestion ?? deps.onQuestion`, the value the parent's
+ *    own AskUserQuestion resolves at): the child's question tool MOUNTS on it, so without it the child has no tool.
+ *  · `additionalDirectories` / `additionalReadDirectories` — the fs-fence widening (deployment property).
+ *  · `envFacts` — the sandbox facts (profile / egress / scratchpad).
+ *  · `memoryPersistenceCapable` — the deployment's DECLARED persistence statement: `false` is a REMOVAL (floor),
+ *    `true` a default a child's own declaration may narrow.
+ */
+export interface ParentSpecSeat {
+    readonly principal?: string;
+    readonly oneShot?: true;
+    readonly clientContext?: TaskSpec["clientContext"];
+    readonly onQuestion?: OnQuestion;
+    readonly additionalDirectories?: readonly string[];
+    readonly additionalReadDirectories?: readonly string[];
+    readonly envFacts?: TaskSpec["envFacts"];
+    readonly memoryPersistenceCapable?: boolean;
+}
+/** Mint the seat off the parent's REBOUND spec and its frozen question face (spec over deps — the caller resolves it once,
+ *  the same value the parent's own question routing reads). Absent fields stay absent; `oneShot` only when `true`. */
+export declare function parentSpecSeatOf(spec: Omit<ParentSpecSeatFields, "onQuestion">, frozenOnQuestion: OnQuestion | undefined): ParentSpecSeat;
+/**
+ * Apply the seat to a child spec — ONE law for every member, both lanes:
+ *   a value the child spec already carries WINS; the seat FILLS an unset one; the two REMOVAL values
+ *   (`oneShot: true`, `memoryPersistenceCapable: false`) land UNCONDITIONALLY.
+ * "Already carries" is the child's own authorship — a deployment baseline, a trusted script, an agent definition's
+ * fold (the Task lane folds the definition's `memoryPersistenceCapable` before applying; the workflow lane applies at
+ * the launch site AFTER the agentType fold) — so a definition may narrow a parent `true` to `false`, a baseline-pinned
+ * principal stands, and nothing a child can author lifts a removal. Arrays and the facts object are copied per child
+ * (a retained child's frozen snapshot must not alias the parent's seat). Returns a NEW object; `child` is not mutated.
+ * No seat (a tool running outside a Runner task) ⇒ the child spec is returned as is.
+ */
+export declare function applyParentSpecSeat<S extends ParentSpecSeatFields>(child: S, seat: ParentSpecSeat | undefined): S;
+/** The ctx keys that restate a seat member as THIS run's own fact (tools read them for scope / receipts / clamps). */
+declare const SEAT_FACTS_ON_CTX: readonly ["principal", "oneShot", "onQuestion", "memoryPersistenceCapable"];
+/**
+ * The seat a delegation boundary reads off a trusted ctx — ONE reader for both delegation tools. A Runner-filled ctx
+ * always carries the seat beside the run's own facts, and the two agree by construction (one mint). A HAND-BUILT ctx
+ * (a caller invoking a delegation tool's `execute` directly) that carries any of those facts WITHOUT the seat, or with
+ * a seat that disagrees with them, is REFUSED (`config.parent_spec_seat_missing`): spawning a principal-less child from a
+ * principal-bearing caller would offload into the shared namespace and re-key its journal — a silent tenant narrowing,
+ * never a fallback. A ctx with neither (a tool running outside a Runner task) hands down no seat.
+ */
+export declare function parentSpecSeatOfCtx(ctx: Pick<ToolExecuteContext, "parentSpecSeat" | (typeof SEAT_FACTS_ON_CTX)[number]>): ParentSpecSeat | undefined;
+export {};

package/dist/core/parent-spec-seat.js

@@ -0,0 +1,47 @@
+export function parentSpecSeatOf(spec, frozenOnQuestion) {
+    return Object.freeze({
+        ...(spec.principal !== undefined ? { principal: spec.principal } : {}),
+        ...(spec.oneShot === true ? { oneShot: true } : {}),
+        ...(spec.clientContext !== undefined ? { clientContext: spec.clientContext } : {}),
+        ...(frozenOnQuestion !== undefined ? { onQuestion: frozenOnQuestion } : {}),
+        ...(spec.additionalDirectories !== undefined ? { additionalDirectories: Object.freeze([...spec.additionalDirectories]) } : {}),
+        ...(spec.additionalReadDirectories !== undefined ? { additionalReadDirectories: Object.freeze([...spec.additionalReadDirectories]) } : {}),
+        ...(spec.envFacts !== undefined ? { envFacts: Object.freeze({ ...spec.envFacts }) } : {}),
+        ...(spec.memoryPersistenceCapable !== undefined ? { memoryPersistenceCapable: spec.memoryPersistenceCapable } : {}),
+    });
+}
+export function applyParentSpecSeat(child, seat) {
+    if (seat === undefined)
+        return child;
+    const fill = (key, value) => child[key] === undefined && value !== undefined ? { [key]: value } : {};
+    return {
+        ...child,
+        ...fill("principal", seat.principal),
+        ...fill("clientContext", seat.clientContext),
+        ...fill("onQuestion", seat.onQuestion),
+        ...fill("additionalDirectories", (seat.additionalDirectories !== undefined ? [...seat.additionalDirectories] : undefined)),
+        ...fill("additionalReadDirectories", (seat.additionalReadDirectories !== undefined ? [...seat.additionalReadDirectories] : undefined)),
+        ...fill("envFacts", (seat.envFacts !== undefined ? { ...seat.envFacts } : undefined)),
+        ...(seat.oneShot === true ? { oneShot: true } : {}),
+        ...(seat.memoryPersistenceCapable === false ? { memoryPersistenceCapable: false } : fill("memoryPersistenceCapable", seat.memoryPersistenceCapable)),
+    };
+}
+const SEAT_FACTS_ON_CTX = ["principal", "oneShot", "onQuestion", "memoryPersistenceCapable"];
+export function parentSpecSeatOfCtx(ctx) {
+    const seat = ctx.parentSpecSeat;
+    const facts = SEAT_FACTS_ON_CTX.filter((k) => ctx[k] !== undefined);
+    if (seat === undefined) {
+        if (facts.length === 0)
+            return undefined;
+        throw seatRefusal(`the tool context carries ${facts.join(" / ")} but no \`parentSpecSeat\` — a delegating caller hands its children the seat it was minted (a Runner-filled ctx always carries it); spawning without it would silently drop the identity`);
+    }
+    const disagree = facts.filter((k) => (k === "oneShot" ? (ctx.oneShot === true) !== (seat.oneShot === true) : ctx[k] !== seat[k]));
+    if (disagree.length > 0)
+        throw seatRefusal(`the tool context's ${disagree.join(" / ")} disagree with its \`parentSpecSeat\` — one mint, one value`);
+    return seat;
+}
+function seatRefusal(message) {
+    const e = new Error(`parentSpecSeat: ${message}`);
+    e.code = "config.parent_spec_seat_missing";
+    return e;
+}

package/dist/core/permission-rule-model.d.ts

@@ -73,6 +73,8 @@
  * `Bash(git status:*)`) — the last two are strict-side divergences from upstream, registered as such.
  */
 import type { AssertAllKeysHandled } from "./ask-origin.js";
+import { type PathFamily, type PathIdentity } from "../tools/fs/safety.js";
+import type { PathTargetReading } from "./effective-path-target.js";
 /**
  * The closed set of rule BEHAVIORS — what a matching rule says about the call. The upstream vocabulary
  * verbatim (`allow` / `deny` / `ask`, the three settings lists), in PRECEDENCE order: when rules of more
@@ -538,7 +540,7 @@ export type PathRuleBaseLabelCoversEveryBase = AssertAllKeysHandled<Exclude<Path
 export declare function ruleBasesNeeded(rule: Pick<PersistedRule, "match" | "command">): readonly PathRuleBase[];
 /** Is this base usable by {@link resolvePathPattern} — an absolute path with a lexical normal form? A rule
  *  compiler asks this at compile time so a pattern is refused rather than compiled inert. */
-export declare function isUsablePathBase(base: string | undefined): boolean;
+export declare function isUsablePathBase(base: string | undefined, family: PathFamily | undefined): boolean;
 /**
  * The PATH family's tightening reach — three-valued like the command family's ({@link programRunReachOf}):
  * does this deny/ask rule reach the call's target path? The target is the caller's ALREADY-RESOLVED
@@ -555,7 +557,7 @@ export declare function isUsablePathBase(base: string | undefined): boolean;
  * defect (a `~/` deny falling back to the engine host's home guarded the wrong directory; a `/…` deny with
  * no root reached nothing at all).
  */
-export declare function pathRuleReachOf(rule: Pick<PersistedRule, "match" | "command" | "behavior">, target: string, bases: PathRuleBases): ProgramRunReachOutcome;
+export declare function pathRuleReachOf(rule: Pick<PersistedRule, "match" | "command" | "behavior">, target: PathIdentity, bases: PathRuleBases): ProgramRunReachOutcome;
 /**
  * Does this rule's command pattern admit `command`?
  *
@@ -692,7 +694,7 @@ export declare function pathWithinRoot(path: string, root: string): boolean;
  * bodies never come through here (their canonical spelling is unique and non-normal spellings are
  * refused at the validator); this is for the comparison INPUT a caller derives from a live call.
  */
-export declare function lexicalNormalAbsolutePathOf(path: string): string | undefined;
+export declare function lexicalNormalAbsolutePathOf(path: string, family: PathFamily | undefined, anchor?: string): PathIdentity | undefined;
 /**
  * design/382 §2.5 — the ONE admission predicate of the Read directory rule family, beside
  * {@link ruleAdmitsCommand} as its path-lane sibling. Four consumers share it (the minting round
@@ -715,7 +717,10 @@ export declare function lexicalNormalAbsolutePathOf(path: string): string | unde
  * there is nothing here for it to clear). As a DENY/ASK the same containment refuses or questions every
  * path under the directory, on whichever path tool the rule names.
  */
-export declare function directoryRuleAdmits(rule: Pick<PersistedRule, "match" | "command">, path: string): boolean;
+export declare function directoryRuleAdmits(rule: Pick<PersistedRule, "match" | "command">, path: PathIdentity, bases: PathRuleBases): boolean;
+/** The identity of a directory SPELLING (the cd resolver's `/`-rooted output) under the call's tree, for the
+ *  consumers that hand {@link directoryRuleAdmits} a spelling; a rule minted from it stores this form. */
+export declare function directoryIdentityOf(spelling: string, bases: PathRuleBases): PathIdentity | undefined;
 /** Does a rule's scope cover a task running in `cwd` (and, for the session dimension, in the session
  *  named by `sessionId`)? A project rule needs a cwd to compare against; without one it covers nothing
  *  (fail-closed). A session rule (design/382 §4.3) covers a call iff the call's `sessionId` equals the
@@ -872,8 +877,8 @@ export declare function adjudicatePersistedPathRules(rules: readonly PersistedRu
     cwd: string | undefined;
     sessionId?: string;
 }, targets: {
-    readonly tighten?: string;
-    readonly allow?: string;
+    readonly tighten?: PathTargetReading;
+    readonly allow?: PathTargetReading;
 }, bases: PathRuleBases): PersistedRuleVerdict | undefined;
 /**
  * design/375 §5.2 — the per-segment coverage table for `command`: which segments an eligible rule