@sema-agent/core 5.38.0 → 5.39.0

package/dist/core/store-contracts/mailbox-store-contract.js

@@ -1,4 +1,5 @@
 import { strict as assert } from "node:assert";
+import { MAILBOX_TOMBSTONED_RECIPIENT_CODE } from "../mailbox-store.js";
 import { beginContract } from "./contract-harness.js";
 export const MAILBOX_CONTRACT_SCOPE = "default";
 const msg = (content, sentAt = 1000) => ({ content, sentAt });
@@ -191,3 +192,80 @@ export async function mailboxBundledOnlyContract(mk, runAssertion) {
     });
     await settle();
 }
+export async function mailboxTombstonedRecipientContract(mk, hooks) {
+    const { run: runRaw, settle } = beginContract(hooks.runAssertion);
+    const run = (name, fn) => runRaw(name, () => withStores(mk, fn));
+    const S = MAILBOX_CONTRACT_SCOPE;
+    const codeOf = (e) => e?.code;
+    run("预删除态的收件人:append 响亮拒且带码(既不静默收下级联即将删掉的消息,也不裸抛)", async (make) => {
+        const s = make();
+        await hooks.tombstone(s, S, "a1");
+        let thrown;
+        try {
+            await s.append(S, "a1", msg("m1"));
+        }
+        catch (e) {
+            thrown = e;
+        }
+        assert.notEqual(thrown, undefined, "静默收下 = 给发件人一张级联马上撕掉的回执");
+        assert.equal(codeOf(thrown), MAILBOX_TOMBSTONED_RECIPIENT_CODE, "裸抛与拒同形:消费方要能按码分诊");
+        let again;
+        try {
+            await s.append(S, "a1", msg("m2"));
+        }
+        catch (e) {
+            again = e;
+        }
+        assert.equal(codeOf(again), MAILBOX_TOMBSTONED_RECIPIENT_CODE);
+    });
+    run("拒的粒度是收件人,不是开关:同 scope 下另一个活收件人照常收信", async (make) => {
+        const s = make();
+        await hooks.tombstone(s, S, "a1");
+        assert.equal(await s.append(S, "a2", msg("still-live")), 1, "活收件人不受邻居的删除级联牵连");
+        assert.equal(await s.peekCount(S, "a2"), 1);
+    });
+    run("收件人身份是 (scope, handle) 整体:A 租户的删除级联不得拒掉 B 租户的同名收件人", async (make) => {
+        const s = make();
+        await hooks.tombstone(s, "tenant-a", "a1");
+        assert.equal(await s.append("tenant-b", "a1", msg("other-tenant")), 1, "同名 handle 在另一个租户下是另一个收件人");
+        assert.equal(await s.peekCount("tenant-b", "a1"), 1);
+    });
+    run("两件套还得是单射的:把 (scope, handle) 拼成一个字符串记态,不得让两个不同收件人撞成一个", async (make) => {
+        const s = make();
+        await hooks.tombstone(s, "tenant a", "b");
+        assert.equal(await s.append("tenant", "a b", msg("distinct-recipient")), 1, "拼键歧义不得把另一个收件人一起拒掉");
+        assert.equal(await s.peekCount("tenant", "a b"), 1);
+    });
+    run("副作用轴 · 活租约:被拒的 append 不得动别人手上的租约(单消费者围栏不因删除窗口松开)", async (make) => {
+        const s = make();
+        await s.append(S, "a1", msg("in-flight"));
+        const held = await s.claimLease(S, "a1", "consumer-A", 60_000, 10_000);
+        assert.equal(held?.messages.length, 1);
+        await hooks.tombstone(s, S, "a1");
+        await assert.rejects(s.append(S, "a1", msg("after-tombstone", 2_000)), "预删除态下的 append 必须拒");
+        assert.equal(await s.claimLease(S, "a1", "rival", 60_000, 11_000), null, "A 的活租约必须仍然 fence 住别人");
+        await s.ack(S, "a1", "consumer-A", held.maxSeq);
+        assert.equal(await s.peekCount(S, "a1"), 0);
+    });
+    run("拒的是入口,不是清仓:被拒的 append 零副作用,已入箱的消息按原 seq/内容原封不动", async (make) => {
+        const s = make();
+        const seq = await s.append(S, "a1", msg("parked-before"));
+        await hooks.tombstone(s, S, "a1");
+        let thrown;
+        let refused = false;
+        try {
+            await s.append(S, "a1", msg("after-tombstone", 2_000));
+        }
+        catch (e) {
+            refused = true;
+            thrown = e;
+        }
+        assert.equal(refused, true, "预删除态下的 append 必须拒");
+        assert.equal(codeOf(thrown), MAILBOX_TOMBSTONED_RECIPIENT_CODE, "箱非空时的拒同样要带码");
+        assert.equal(await s.peekCount(S, "a1"), 1, "被拒的 append 不得入箱(幽灵投递),也不得清箱");
+        const lease = await s.claimLease(S, "a1", "w1", 60_000, 10_000);
+        assert.deepEqual(lease?.messages.map((m) => m.seq), [seq]);
+        assert.deepEqual(lease?.messages.map((m) => m.content), ["parked-before"], "取到的仍是拒之前那一条");
+    });
+    await settle();
+}

package/dist/core/types.d.ts

@@ -4785,6 +4785,27 @@ export interface RunnerDeps {
      * ignored). Same deployment-only seat, clamp argument and checkpoint posture as the tiers key.
      */
     readDenyBuiltinExclude?: readonly string[];
+    /**
+     * backlog #286 (#279 — CC 2.1.233 `DANGEROUS_FILES`/`DANGEROUS_DIRECTORIES`/
+     * `DANGEROUS_DIRECTORY_PATHS` parity): the WRITE-protection table. DEFAULT-ON: a path-confinable
+     * write (Write/Edit/NotebookEdit) whose target lands on a table row has a surviving `allow`
+     * demoted to `ask` at the tool gate (`decisionReason: "safety"`; a deny/ask verdict is untouched;
+     * approval flows the ordinary ask-resolution chain — classifier, blanket `onAsk`, durable park —
+     * with no `requiresRealApproval` mandate). Absent =
+     * {@link import("./write-protect.js").WRITE_PROTECTED_DEFAULT_TABLE} (the CC triple verbatim +
+     * the two argued sema rows). This key IS the whole-table escape hatch, deployment seat ONLY (no
+     * TaskSpec twin, no governed-workflow channel): `[]` = no table (explicit and legal); a non-empty
+     * list REPLACES the built-in table whole (compose additions as
+     * `[...WRITE_PROTECTED_DEFAULT_TABLE, …]`; drop rows by filtering the exported table — the
+     * visible/deletable admin face). Bad values refuse loudly at prepare (#123): garbage shapes,
+     * glob metacharacters (the table speaks LITERAL names — glob semantics live in
+     * `createSensitivePathPolicy`), unknown kinds, impossible kind/name combinations. Matching is
+     * lexical over the spelled target with one case fold (ı/ſ included) — a symlink alias evades it
+     * by construction; the canonicalizing opt-in deny policy remains the hard layer. Not frozen into
+     * checkpoints: a resumed task follows the CURRENT deployment table (an approved parked call
+     * bypasses the gate as always — the human already adjudicated it).
+     */
+    writeProtectedPaths?: readonly import("./write-protect.js").WriteProtectedEntry[];
     /**
      * design/199 件A — the DEPLOYMENT's read-face declaration
      * ({@link import("../tools/fs/read-face.js").ReadFace}; see {@link TaskSpec.readFace} for the

package/dist/core/write-protect.d.ts

@@ -0,0 +1,93 @@
+/**
+ * How one table row matches the judged path:
+ *  · `"basename"`     — the target's last segment equals the row name (CC `DANGEROUS_FILES` form);
+ *  · `"segment"`      — ANY path segment equals the row name (CC `DANGEROUS_DIRECTORIES` form);
+ *  · `"segment-run"`  — a CONSECUTIVE run of segments equals the row's `/`-separated segments
+ *                       (CC `DANGEROUS_DIRECTORY_PATHS` form, e.g. `.config/git`).
+ */
+export type WriteProtectedKind = "basename" | "segment" | "segment-run";
+/** One row of the write-protection table: a LITERAL name and how it matches. The `name` is also the
+ *  row's stable identity — the string a refusal/ask message cites. */
+export interface WriteProtectedRow {
+    readonly name: string;
+    readonly kind: WriteProtectedKind;
+}
+/**
+ * One deployment-authored entry for the replacement seat (`RunnerDeps.writeProtectedPaths`).
+ * String shorthand: a bare name ≡ `{ name, kind: "segment" }` (the WIDER single-segment kind —
+ * over-matching is the fail-safe direction for a tighten); a name containing `/` ≡
+ * `{ name, kind: "segment-run" }`. Spell `kind: "basename"` explicitly when last-segment-only
+ * matching is the intent.
+ */
+export type WriteProtectedEntry = string | WriteProtectedRow;
+/** A table hit: which row matched (the row's canonical name + kind). */
+export interface WriteProtectedHit {
+    readonly name: string;
+    readonly kind: WriteProtectedKind;
+}
+/**
+ * WRITE_PROTECTED_DEFAULT_TABLE — the default-active table (the material basis of the deployment
+ * admin face: what an unconfigured deployment demotes to `ask`; visible here, deletable by
+ * replacing the seat with a filtered copy). CC 2.1.233 triple VERBATIM first, then the sema rows,
+ * each with its argument.
+ *
+ * NOT listed, deliberately (each a ruled-out candidate, recorded so the next reader does not
+ * re-litigate silently):
+ *  · `.env` / `.env.*` — CC's own table excludes them too (only `.envrc`, the direnv AUTO-EXECUTION
+ *    vector, is in): a plain `.env` is application config and routine workspace material for the
+ *    tasks this engine runs (the read deny set rules it out on the same grounds); the opt-in write
+ *    DENY (`RECOMMENDED_SENSITIVE_PATTERNS`) covers deployments that want it guarded.
+ *  · key-material FILE patterns (`id_rsa*`, `*.pem`, …) — they are glob-shaped, and this table
+ *    speaks literals; the opt-in deny policy owns that vocabulary.
+ *  · cloud credential dirs (`.aws`, `.kube`, `.azure`, `.config/gcloud`) — writing cloud config IS
+ *    the routine "configure this environment" action tasks are asked to perform, so a default ask
+ *    on every such write is recurring friction without CC precedent; the opt-in deny policy covers
+ *    them, and the READ side already default-refuses them (reading credentials exfiltrates; writing
+ *    a fresh config file does not).
+ */
+export declare const WRITE_PROTECTED_DEFAULT_TABLE: readonly WriteProtectedRow[];
+/**
+ * The ONE case fold of this module, applied to BOTH sides of every comparison (table names at
+ * compile, path segments at match) — `toLowerCase` plus the two confusable letters CC's fold maps
+ * (U+0131 dotless ı → i, U+017F long ſ → s). Deliberately NOT full Unicode confusable folding:
+ * that would be a different, wider claim than the one made (the read deny set's ASCII-contract doc
+ * states the same boundary for its own fold).
+ */
+export declare function foldWriteProtectCase(s: string): string;
+/**
+ * Resolve the ACTIVE table under the deployment seat (validated, loud — #123's bad-value states all
+ * throw and name the knob). `undefined` = the default table; `[]` = NO table (an explicit, legal
+ * posture — the whole-table escape hatch's empty end); a non-empty list REPLACES the default table
+ * whole (compose additions as `[...WRITE_PROTECTED_DEFAULT_TABLE, …]`, drop rows by filtering the
+ * exported table — the visible/deletable admin face). Exact duplicates fold (idempotent, not one of
+ * #123's bad-value states). Exported so an admin face can preview the effective table under a
+ * candidate configuration with the engine's own rules.
+ */
+export declare function resolveWriteProtectedTable(entries?: readonly WriteProtectedEntry[]): readonly WriteProtectedRow[];
+/** The compiled judge over one resolved table. Pure and synchronous — literal folded comparisons,
+ *  no filesystem access (see the module header for the declared lexical scope). */
+export interface WriteProtectionMatcher {
+    /** The resolved rows this judge was compiled from (canonical names — the disclosure face). */
+    readonly rows: readonly WriteProtectedRow[];
+    /** Judge ONE path spelling. Returns the first matching row (basename rows first, then segment,
+     *  then segment-run — deterministic), or null. */
+    matchPath(path: string): WriteProtectedHit | null;
+}
+/**
+ * Compile the write-protection judge for a deployment configuration. Returns `undefined` when the
+ * resolved table is EMPTY (`[]` replacement) — the caller then mounts no tighten at all, keeping an
+ * opted-out deployment's decision path byte-identical to a build without this layer.
+ */
+export declare function compileWriteProtection(entries?: readonly WriteProtectedEntry[]): WriteProtectionMatcher | undefined;
+/**
+ * Build the ENGINE-FILLED gate input (`ToolGateInput.writeProtectionCheck`): covered tools are the
+ * path-confinable write set (Write/Edit/NotebookEdit — the shared spelling), the judged target is
+ * the SAME string the tool itself will resolve (`writeTargetPath`, the shared single source with
+ * the sensitive-path guard and the fs-write gate), and the verdict is the table judge's. A covered
+ * write with NO resolvable target returns null here — this layer is ADDITIVE friction on a named
+ * set of targets, not a containment boundary (a target-less call cannot land on a named row, and
+ * the tool's own schema validation refuses it before any write); the fail-closed treatment of the
+ * unresolvable case belongs to the containment gates (fs-write-gate-policy documents that split).
+ * Returns `undefined` when the resolved table is empty — nothing to judge, mount nothing.
+ */
+export declare function createWriteProtectionCheck(entries?: readonly WriteProtectedEntry[]): ((toolName: string, args: unknown) => WriteProtectedHit | null) | undefined;

package/dist/core/write-protect.js

@@ -0,0 +1,194 @@
+import { writeTargetPath } from "../tools/fs/safety.js";
+import { PATH_CONFINABLE_WRITE_TOOLS } from "./runner/session-rule-policy.js";
+export const WRITE_PROTECTED_DEFAULT_TABLE = [
+    { name: ".gitconfig", kind: "basename" },
+    { name: ".gitmodules", kind: "basename" },
+    { name: ".bashrc", kind: "basename" },
+    { name: ".bash_profile", kind: "basename" },
+    { name: ".zshrc", kind: "basename" },
+    { name: ".zprofile", kind: "basename" },
+    { name: ".profile", kind: "basename" },
+    { name: ".zshenv", kind: "basename" },
+    { name: ".zlogin", kind: "basename" },
+    { name: ".zlogout", kind: "basename" },
+    { name: ".bash_login", kind: "basename" },
+    { name: ".bash_aliases", kind: "basename" },
+    { name: ".bash_logout", kind: "basename" },
+    { name: ".envrc", kind: "basename" },
+    { name: ".ripgreprc", kind: "basename" },
+    { name: ".mcp.json", kind: "basename" },
+    { name: ".claude.json", kind: "basename" },
+    { name: ".npmrc", kind: "basename" },
+    { name: ".yarnrc", kind: "basename" },
+    { name: ".yarnrc.yml", kind: "basename" },
+    { name: ".pnp.cjs", kind: "basename" },
+    { name: ".pnp.loader.mjs", kind: "basename" },
+    { name: ".pnpmfile.cjs", kind: "basename" },
+    { name: "bunfig.toml", kind: "basename" },
+    { name: ".bunfig.toml", kind: "basename" },
+    { name: ".bazelrc", kind: "basename" },
+    { name: ".bazelversion", kind: "basename" },
+    { name: ".bazeliskrc", kind: "basename" },
+    { name: ".pre-commit-config.yaml", kind: "basename" },
+    { name: "lefthook.yml", kind: "basename" },
+    { name: ".lefthook.yml", kind: "basename" },
+    { name: "lefthook.yaml", kind: "basename" },
+    { name: ".lefthook.yaml", kind: "basename" },
+    { name: "gradle-wrapper.properties", kind: "basename" },
+    { name: "maven-wrapper.properties", kind: "basename" },
+    { name: ".devcontainer.json", kind: "basename" },
+    { name: "pyrightconfig.json", kind: "basename" },
+    { name: ".git", kind: "segment" },
+    { name: ".vscode", kind: "segment" },
+    { name: ".idea", kind: "segment" },
+    { name: ".claude", kind: "segment" },
+    { name: ".husky", kind: "segment" },
+    { name: ".cargo", kind: "segment" },
+    { name: ".devcontainer", kind: "segment" },
+    { name: ".yarn", kind: "segment" },
+    { name: ".mvn", kind: "segment" },
+    { name: ".config/git", kind: "segment-run" },
+    { name: ".ssh", kind: "segment" },
+    { name: ".gnupg", kind: "segment" },
+];
+export function foldWriteProtectCase(s) {
+    return s.toLowerCase().replace(/ı/g, "i").replace(/ſ/g, "s");
+}
+const KINDS = ["basename", "segment", "segment-run"];
+function describeEntryValue(v) {
+    try {
+        return JSON.stringify(v) ?? String(v);
+    }
+    catch {
+        return String(v);
+    }
+}
+function normalizeWriteProtectedEntry(entry) {
+    const shape = typeof entry === "string" ? { name: entry, kind: entry.includes("/") ? "segment-run" : "segment" } : entry;
+    if (typeof shape !== "object" || shape === null || typeof shape.name !== "string") {
+        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(entry)} is not a name string or { name, kind } row.`);
+    }
+    const name = shape.name;
+    if (!KINDS.includes(shape.kind)) {
+        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(entry)} has kind ${describeEntryValue(shape.kind)} — known kinds: ${KINDS.join(", ")}.`);
+    }
+    const kind = shape.kind;
+    if (name.includes("*") || name.includes("?")) {
+        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} contains a wildcard metacharacter — this table speaks LITERAL names only (a silently-literal "*" would guard less than it reads); pattern semantics live in createSensitivePathPolicy.`);
+    }
+    if (name.includes("\\")) {
+        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} contains a backslash — names are "/"-separated (both path families are matched); spell the segments with "/".`);
+    }
+    const segments = name.split("/").filter((s) => s.length > 0);
+    if (segments.length === 0) {
+        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} contains no path segments and would protect nothing — remove the entry or spell the name.`);
+    }
+    if (segments.some((s) => s === "." || s === "..")) {
+        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} contains a "." or ".." segment — the judge folds dot segments lexically before matching, so such a row could never match anything; spell the real name.`);
+    }
+    if (segments.length > 1 && kind !== "segment-run") {
+        throw new Error(`writeProtectedPaths: entry ${describeEntryValue(name)} spans ${segments.length} segments but declares kind "${kind}" — multi-segment names match as kind "segment-run".`);
+    }
+    return { name: segments.join("/"), kind };
+}
+export function resolveWriteProtectedTable(entries) {
+    if (entries === undefined)
+        return WRITE_PROTECTED_DEFAULT_TABLE;
+    if (!Array.isArray(entries)) {
+        throw new Error(`writeProtectedPaths: expected an array of entries (whole-table replacement; [] = no write-protection table), got ${describeEntryValue(entries)}.`);
+    }
+    const out = [];
+    const seen = new Set();
+    for (const entry of entries) {
+        const row = normalizeWriteProtectedEntry(entry);
+        const key = `${row.kind}:${foldWriteProtectCase(row.name)}`;
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        out.push(row);
+    }
+    return out;
+}
+export function compileWriteProtection(entries) {
+    const rows = resolveWriteProtectedTable(entries);
+    if (rows.length === 0)
+        return undefined;
+    const basenames = new Map();
+    const segments = new Map();
+    const runs = [];
+    for (const row of rows) {
+        const folded = foldWriteProtectCase(row.name);
+        if (row.kind === "basename") {
+            if (!basenames.has(folded))
+                basenames.set(folded, row.name);
+        }
+        else if (row.kind === "segment") {
+            if (!segments.has(folded))
+                segments.set(folded, row.name);
+        }
+        else {
+            runs.push({ name: row.name, parts: folded.split("/").filter((s) => s.length > 0) });
+        }
+    }
+    return {
+        rows,
+        matchPath(path) {
+            const viewOf = (win32) => {
+                const segs = [];
+                for (const raw of path.split(/[\\/]/)) {
+                    if (raw.length === 0)
+                        continue;
+                    const dot = !win32 || /^\.{1,2}$/.test(raw) ? raw : raw.replace(/ +$/, "");
+                    if (dot === ".")
+                        continue;
+                    if (dot === "..") {
+                        const last = segs[segs.length - 1];
+                        if (segs.length > 0 && last !== "..")
+                            segs.pop();
+                        else
+                            segs.push("..");
+                        continue;
+                    }
+                    const stripped = win32 ? raw.replace(/[. ]+$/, "") : raw;
+                    segs.push(foldWriteProtectCase(stripped.length > 0 ? stripped : raw));
+                }
+                return segs;
+            };
+            const judge = (segs) => {
+                if (segs.length === 0)
+                    return null;
+                const base = basenames.get(segs[segs.length - 1] ?? "");
+                if (base !== undefined)
+                    return { name: base, kind: "basename" };
+                for (const s of segs) {
+                    const hit = segments.get(s);
+                    if (hit !== undefined)
+                        return { name: hit, kind: "segment" };
+                }
+                for (const run of runs) {
+                    const n = run.parts.length;
+                    for (let i = 0; i + n <= segs.length; i++) {
+                        if (run.parts.every((p, j) => segs[i + j] === p))
+                            return { name: run.name, kind: "segment-run" };
+                    }
+                }
+                return null;
+            };
+            const posix = viewOf(false);
+            return judge(posix) ?? judge(viewOf(true));
+        },
+    };
+}
+export function createWriteProtectionCheck(entries) {
+    const matcher = compileWriteProtection(entries);
+    if (matcher === undefined)
+        return undefined;
+    return (toolName, args) => {
+        if (!PATH_CONFINABLE_WRITE_TOOLS.has(toolName))
+            return null;
+        const path = writeTargetPath(toolName, args);
+        if (typeof path !== "string" || path.length === 0)
+            return null;
+        return matcher.matchPath(path);
+    };
+}

package/dist/index.d.ts

@@ -91,6 +91,7 @@ export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, ty
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, type ReadDenyEntry, type ReadDenyMatcher, type NormalizedReadDenyEntry, type ReadDenyBuiltinTier, type ReadDenyBuiltinRow, type ReadDenyBuiltinConfig, } from "./tools/fs/index.js";
 export { deploymentReadFaceClampNotice, resolveReadFace, type ReadFace, type ReadFaceInputs } from "./tools/fs/index.js";
+export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, type WriteProtectedEntry, type WriteProtectedRow, type WriteProtectedKind, type WriteProtectedHit, type WriteProtectionMatcher, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, type ToolResultProvenance, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, type ToolResultStore, type ToolResultSlice, type ToolResultDeletionReport, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, type ActorAssertion, type PendingSteerEntry, type PendingSteerInput, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, type RiskDescriptor, type ProbeCause, type ProbeCauseOperands, type CheckpointStore, type CheckpointSummary, type Checkpoint, type CheckpointToken, type CheckpointGate, type CheckpointState, type SerializedCheckpointState, type CheckpointFaultMode, type PendingAction, type ResumeOutcome, type ResolvedOutcome, type ReopenReason, type ResolveExpectation, type SafetyAxis, type RealApprovalGateBit, type ResourceLedger, type ResourceLimitReason, type PlatformLimitReason, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, type UsageWindow, type UsageWindowStore, type UsageWindowReading, type UsageWindowRecord, type UsageSlot, type UsageBucketRow, } from "./core/usage-window-store.js";
@@ -114,7 +115,7 @@ export { type StoreDurability } from "./core/checkpoint-store.js";
 export { type StoreFidelity } from "./core/checkpoint-store.js";
 export { projectHumanInput, buildHumanInputEvent, type HumanInputSource, type HumanInputFrame, type HumanInputEvent, type HumanInputDelivery, } from "./core/human-input-projection.js";
 export { TaskRegistry, defaultTaskRegistry, createTaskOutputTool, createTaskStopTool, type SemaTaskType, type SemaTaskStatus, type SemaTaskHandle, type ParkedClaimTicket, type TaskAccess, type UnifiedTaskOutput, type TaskRetrievalStatus, type StopSource, type RegisterMonitorInput, type MonitorTimers, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccessWorkflowRun, DURABLE_AGENT_HANDLE_RE, } from "./core/task-registry.js";
-export { InMemoryMailboxStore, type MailboxStore, type MailboxMessage, type MailboxLease } from "./core/mailbox-store.js";
+export { InMemoryMailboxStore, type MailboxStore, type MailboxMessage, type MailboxLease, MailboxStoreError, MAILBOX_TOMBSTONED_RECIPIENT_CODE, } from "./core/mailbox-store.js";
 export { FileMailboxStore, type FileMailboxStoreOptions } from "./stores/file/mailbox-store.js";
 export { createFileTaskListStore } from "./stores/file/task-list-store.js";
 export { createCcFileTaskListStore } from "./stores/cc/task-list-store.js";
@@ -217,7 +218,7 @@ export { sessionRepoContract } from "./core/store-contracts/session-repo-contrac
 export { toolResultStoreContract } from "./core/store-contracts/tool-result-store-contract.js";
 export { fileSnapshotStoreContract } from "./core/store-contracts/file-snapshot-store-contract.js";
 export { permissionRuleSyncContract, type PermissionRuleSyncContractHooks } from "./core/store-contracts/permission-rule-sync-contract.js";
-export { MAILBOX_CONTRACT_SCOPE, mailboxStoreContract, mailboxAckOwnershipContract, mailboxBundledOnlyContract, } from "./core/store-contracts/mailbox-store-contract.js";
+export { MAILBOX_CONTRACT_SCOPE, mailboxStoreContract, mailboxAckOwnershipContract, mailboxBundledOnlyContract, mailboxTombstonedRecipientContract, type MailboxTombstonedRecipientContractHooks, } from "./core/store-contracts/mailbox-store-contract.js";
 export { BACKGROUND_AGENT_CONTRACT_SCOPE, backgroundAgentStoreContract, backgroundAgentStoreScopesContract, } from "./core/store-contracts/background-agent-store-contract.js";
 export { type BackgroundAgentStore, type BackgroundAgentRecord, type BackgroundAgentRowSummary, type BackgroundAgentUsage, canAccessAgentRecord, STALE_RUNNING_REAP_ATTRIBUTION, BackgroundAgentStoreError, InMemoryBackgroundAgentStore, reconcileParkedAgents, queryBackgroundAgents, type BackgroundAgentQuery, } from "./core/background-agent-store.js";
 export { serveDurableAgentRowLane, buildAgentPollDetails, type AgentPollDetailsInput, } from "./core/task-registry-agent.js";

package/dist/index.js

@@ -71,6 +71,7 @@ export { classifyCompoundReadonlyDetailed, formatOutOfRootReadApprovalOption, }
 export { resolveBashTimeoutCaps } from "./tools/fs/index.js";
 export { READ_FACE_DEFAULT_DENY_ENTRIES, READ_FACE_BUILTIN_DENY_TABLE, READ_DENY_BUILTIN_TIERS, READ_DENY_DEFAULT_TIERS, resolveReadDenyBuiltins, compileReadDeny, } from "./tools/fs/index.js";
 export { deploymentReadFaceClampNotice, resolveReadFace } from "./tools/fs/index.js";
+export { WRITE_PROTECTED_DEFAULT_TABLE, resolveWriteProtectedTable, compileWriteProtection, } from "./core/write-protect.js";
 export { InMemoryToolResultStore, OFFLOAD_TOOL_NAME, DEFAULT_TOOL_RESULT_THRESHOLD_CHARS, assertSafeToolResultRef, buildToolResultRef, toolResultContentSegment, MAX_MINTED_TOOL_RESULT_REF_CHARS, assertToolResultProvenanceMatch, normalizeToolResultProvenance, toolResultProvenanceOf, ToolResultRefConflictError, TOOL_RESULT_REF_CONFLICT_CODE, } from "./core/tool-result-store.js";
 export { InMemoryCheckpointStore, CheckpointError, mintCheckpointToken, checkpointVersionOf, CURRENT_CHECKPOINT_VERSION, MAX_SUPPORTED_CHECKPOINT_VERSION, ORG_ADMISSION_CHECKPOINT_VERSION, F012_CHECKPOINT_VERSION, REAL_APPROVAL_CHECKPOINT_VERSION, RESOURCE_CHECKPOINT_VERSION, TOKEN_CHECKPOINT_VERSION, debitLedger, remainingBudgetMicroUsd, remainingTokens, winnerFromOutcome, validatePendingSteer, readPendingSteerQueue, appendPendingSteer, MAX_PENDING_STEER_CHARS, MAX_PENDING_STEER_ENTRIES, PENDING_STEER_QUEUE_BYTE_BUDGET_BYTES, PENDING_STEER_FROZEN_FIELDS, ACTOR_ASSERTION_FROZEN_FIELDS, MAX_ACTOR_FIELD_CHARS, MAX_STEER_INPUT_ID_CHARS, LEGACY_PENDING_STEER_INPUT_ID, riskSeverity, buildRiskDescriptor, summarizeCheckpoint, } from "./core/checkpoint-store.js";
 export { InMemoryUsageWindowStore, GLOBAL_USAGE_KEY, EMPTY_USAGE_WINDOW_RECORD, chargeUsageRecord, readUsageRecord, usageRetryAfterMs, resolveUsageWindows, } from "./core/usage-window-store.js";
@@ -93,7 +94,7 @@ export {} from "./core/checkpoint-store.js";
 export {} from "./core/checkpoint-store.js";
 export { projectHumanInput, buildHumanInputEvent, } from "./core/human-input-projection.js";
 export { TaskRegistry, defaultTaskRegistry, createTaskOutputTool, createTaskStopTool, MONITOR_BATCH_WINDOW_MS, MONITOR_DEFAULT_TIMEOUT_MS, MONITOR_MAX_TIMEOUT_MS, MONITOR_MAX_BATCHES_PER_MINUTE, canAccessWorkflowRun, DURABLE_AGENT_HANDLE_RE, } from "./core/task-registry.js";
-export { InMemoryMailboxStore } from "./core/mailbox-store.js";
+export { InMemoryMailboxStore, MailboxStoreError, MAILBOX_TOMBSTONED_RECIPIENT_CODE, } from "./core/mailbox-store.js";
 export { FileMailboxStore } from "./stores/file/mailbox-store.js";
 export { createFileTaskListStore } from "./stores/file/task-list-store.js";
 export { createCcFileTaskListStore } from "./stores/cc/task-list-store.js";
@@ -178,7 +179,7 @@ export { sessionRepoContract } from "./core/store-contracts/session-repo-contrac
 export { toolResultStoreContract } from "./core/store-contracts/tool-result-store-contract.js";
 export { fileSnapshotStoreContract } from "./core/store-contracts/file-snapshot-store-contract.js";
 export { permissionRuleSyncContract } from "./core/store-contracts/permission-rule-sync-contract.js";
-export { MAILBOX_CONTRACT_SCOPE, mailboxStoreContract, mailboxAckOwnershipContract, mailboxBundledOnlyContract, } from "./core/store-contracts/mailbox-store-contract.js";
+export { MAILBOX_CONTRACT_SCOPE, mailboxStoreContract, mailboxAckOwnershipContract, mailboxBundledOnlyContract, mailboxTombstonedRecipientContract, } from "./core/store-contracts/mailbox-store-contract.js";
 export { BACKGROUND_AGENT_CONTRACT_SCOPE, backgroundAgentStoreContract, backgroundAgentStoreScopesContract, } from "./core/store-contracts/background-agent-store-contract.js";
 export { canAccessAgentRecord, STALE_RUNNING_REAP_ATTRIBUTION, BackgroundAgentStoreError, InMemoryBackgroundAgentStore, reconcileParkedAgents, queryBackgroundAgents, } from "./core/background-agent-store.js";
 export { serveDurableAgentRowLane, buildAgentPollDetails, } from "./core/task-registry-agent.js";

package/dist/orchestration/governance-baseline-validity.d.ts

@@ -0,0 +1,44 @@
+/**
+ * design/98 §6.3 — the ONE reading of "is this governance baseline usable", shared by the deployment
+ * CAPABILITY predicate (`workflowsCapability`, which drives the surfaced `/workflows` affordance AND
+ * the orchestration-prompt injection) and the MOUNT-time validator (`createRunWorkflowTool`, which
+ * refuses loudly with a code).
+ *
+ * Why one function rather than two agreeing predicates: this seam split three times inside one
+ * release window, each time one level deeper. First the capability tested `!== undefined` while the
+ * mount tested truthiness (a JSON `null` announced workflows the tool never mounted). Then both
+ * tested the container while the mount refused an unusable `base` SLOT (`{ base: null }` announced
+ * workflows that hard-failed every opted-in task). Then the slot readings agreed but the mount
+ * additionally refused a malformed `worktreeBase` and malformed face lists — the same split again,
+ * one field further in. Two predicates that must "stay in agreement" are a standing invitation to
+ * drift; the only shape that cannot drift is a single function both call.
+ *
+ * The contract: {@link governanceBaselineProblem} returns `null` when the mount would SUCCEED, and
+ * a describable problem when the mount would REFUSE. Every mount-time refusal must be reachable
+ * from here, so a deployment is never told it has workflows it cannot actually run.
+ */
+export interface GovernanceBaselineProblem {
+    /** Which slot/field is wrong, in the spelling a deployment configures (`base.excludeTools`). */
+    readonly where: string;
+    /** What was found there, for the operator-facing message (`null`, `a string`, `an array`). */
+    readonly found: string;
+    /** The coded refusal the mount raises for this problem. */
+    readonly code: "config.invalid_governance_baseline" | "config.invalid_tool_name_set";
+}
+/** Name a bad value WITHOUT throwing on it (a bigint / cyclic object / poisoned `toJSON` must not
+ *  crash the describer and cost the refusal its name). */
+export declare function describeBaselineValue(v: unknown): string;
+/**
+ * The single validity reading. `null` ⇒ the mount would succeed ⇒ the capability may be announced.
+ *
+ * `base` is the control plane every script-spawned child inherits, so a non-object there refuses:
+ * ungoverned is spelled by not configuring `workflowGovernanceBaseline` at all, never by an
+ * unusable anchor. `worktreeBase` is the optional overlay whose documented absence means "base
+ * governs every child" — `null`/absent is that absence, any other non-object is garbage and refuses
+ * rather than impersonating either absence or an overlay.
+ */
+export declare function governanceBaselineProblem(baseline: unknown): GovernanceBaselineProblem | null;
+/** The mount's refusal, minted from the shared reading so the message and the code have one home. */
+export declare function governanceBaselineError(p: GovernanceBaselineProblem): Error & {
+    code: string;
+};

package/dist/orchestration/governance-baseline-validity.js

@@ -0,0 +1,55 @@
+const FACE_LIST_FIELDS = ["excludeTools", "deferTools", "alwaysLoadTools"];
+export function describeBaselineValue(v) {
+    return v === null ? "null" : Array.isArray(v) ? "an array" : `a ${typeof v}`;
+}
+function isSpecObject(v) {
+    return v !== null && v !== undefined && typeof v === "object" && !Array.isArray(v);
+}
+function faceListProblem(slot, where) {
+    for (const field of FACE_LIST_FIELDS) {
+        const v = slot[field];
+        if (v === undefined || v === null)
+            continue;
+        if (!Array.isArray(v)) {
+            return { where: `${where}.${field}`, found: describeBaselineValue(v), code: "config.invalid_tool_name_set" };
+        }
+        for (const [i, entry] of v.entries()) {
+            if (typeof entry !== "string") {
+                return {
+                    where: `${where}.${field}`,
+                    found: `entry ${i} is ${describeBaselineValue(entry)}`,
+                    code: "config.invalid_tool_name_set",
+                };
+            }
+        }
+    }
+    return null;
+}
+export function governanceBaselineProblem(baseline) {
+    if (!isSpecObject(baseline)) {
+        return { where: "workflowGovernanceBaseline", found: describeBaselineValue(baseline), code: "config.invalid_governance_baseline" };
+    }
+    const base = baseline.base;
+    if (!isSpecObject(base)) {
+        return { where: "base", found: describeBaselineValue(base), code: "config.invalid_governance_baseline" };
+    }
+    const baseFaces = faceListProblem(base, "base");
+    if (baseFaces !== null)
+        return baseFaces;
+    const wt = baseline.worktreeBase;
+    if (wt === null || wt === undefined)
+        return null;
+    if (!isSpecObject(wt)) {
+        return { where: "worktreeBase", found: describeBaselineValue(wt), code: "config.invalid_governance_baseline" };
+    }
+    return faceListProblem(wt, "worktreeBase");
+}
+export function governanceBaselineError(p) {
+    const detail = p.code === "config.invalid_tool_name_set"
+        ? `must be an array of tool names (got ${p.found}) — refusing to mount rather than govern children with a roster nobody can read.`
+        : `is ${p.found}, not a spec object — refusing to mount rather than launch children under no governance ` +
+            `(to run ungoverned, leave workflowGovernanceBaseline unconfigured).`;
+    const e = new Error(`createRunWorkflowTool: the workflow governance baseline's ${p.where} ${detail}`);
+    e.code = p.code;
+    return e;
+}

package/dist/orchestration/run-workflow-tool.js

@@ -1,5 +1,6 @@
 import { Type } from "typebox";
 import { defineTool, errorResult } from "../core/tools.js";
+import { governanceBaselineError, governanceBaselineProblem } from "./governance-baseline-validity.js";
 import { redactSecrets, redactHostLeaks, boundedRedactedSummary } from "../core/untrusted-egress.js";
 import { startWorkflow } from "./workflow.js";
 import { buildWorkflowPrimitives } from "./workflow-primitives.js";
@@ -167,16 +168,40 @@ export async function createRunWorkflowTool(d) {
         childMaxTokens: lim.childMaxTokens,
         childMaxTurns: lim.childMaxTurns,
     };
+    const problem = governanceBaselineProblem(d.governanceBaseline);
+    if (problem !== null)
+        throw governanceBaselineError(problem);
+    const FACE_LIST_FIELDS = ["excludeTools", "deferTools", "alwaysLoadTools"];
+    const dropNullFaces = (slot) => {
+        let out = slot;
+        for (const field of FACE_LIST_FIELDS) {
+            if (slot[field] !== null)
+                continue;
+            out = { ...out };
+            delete out[field];
+        }
+        return out;
+    };
+    const sanitizedBaseline = (() => {
+        const wt = d.governanceBaseline.worktreeBase;
+        const { worktreeBase: _absentOverlay, ...rest } = d.governanceBaseline;
+        return {
+            ...rest,
+            base: dropNullFaces(d.governanceBaseline.base),
+            ...(wt === null || wt === undefined ? {} : { worktreeBase: dropNullFaces(wt) }),
+        };
+    })();
+    const unionFaceList = (own, parent) => own === undefined ? [...new Set(parent)] : [...new Set([...own, ...parent])];
     const withParentFace = (base, inherit) => ({
         ...base,
         ...(d.parentExcludeTools?.length
-            ? { excludeTools: [...new Set([...(base.excludeTools ?? inherit?.excludeTools ?? []), ...d.parentExcludeTools])] }
+            ? { excludeTools: unionFaceList(base.excludeTools ?? inherit?.excludeTools, d.parentExcludeTools) }
             : {}),
         ...(d.parentDeferTools?.length
-            ? { deferTools: [...new Set([...(base.deferTools ?? inherit?.deferTools ?? []), ...d.parentDeferTools])] }
+            ? { deferTools: unionFaceList(base.deferTools ?? inherit?.deferTools, d.parentDeferTools) }
             : {}),
         ...(d.parentAlwaysLoadTools?.length
-            ? { alwaysLoadTools: [...new Set([...(base.alwaysLoadTools ?? inherit?.alwaysLoadTools ?? []), ...d.parentAlwaysLoadTools])] }
+            ? { alwaysLoadTools: unionFaceList(base.alwaysLoadTools ?? inherit?.alwaysLoadTools, d.parentAlwaysLoadTools) }
             : {}),
         ...(() => {
             const parent = d.parentRestoreGatedTools;
@@ -197,13 +222,13 @@ export async function createRunWorkflowTool(d) {
     const withParentProfile = (base) => d.parentPromptProfile !== undefined && base.promptProfile === undefined ? { ...base, promptProfile: d.parentPromptProfile } : base;
     const baselineWithParentFace = (d.parentExcludeTools?.length ?? 0) > 0 || (d.parentDeferTools?.length ?? 0) > 0 || (d.parentAlwaysLoadTools?.length ?? 0) > 0 || d.parentPromptProfile !== undefined || d.parentRestoreGatedTools !== undefined
         ? {
-            ...d.governanceBaseline,
-            base: withParentProfile(withParentFace(d.governanceBaseline.base)),
-            ...(d.governanceBaseline.worktreeBase !== undefined
-                ? { worktreeBase: withParentFace(d.governanceBaseline.worktreeBase, d.governanceBaseline.base) }
+            ...sanitizedBaseline,
+            base: withParentProfile(withParentFace(sanitizedBaseline.base)),
+            ...(sanitizedBaseline.worktreeBase !== undefined
+                ? { worktreeBase: withParentFace(sanitizedBaseline.worktreeBase, sanitizedBaseline.base) }
                 : {}),
         }
-        : d.governanceBaseline;
+        : sanitizedBaseline;
     const governance = { baseline: baselineWithParentFace, models: d.models, caps: childCaps, onNotice: d.onNotice };
     const builtinsEnabled = d.builtinWorkflows !== false;
     const namedWorkflowSection = renderNamedWorkflowListing(await collectNamedWorkflowListings(d.scriptStore, builtinsEnabled));