@sema-agent/core 7.24.3 → 7.25.0

package/dist/core/gate-lanes.js

@@ -11,7 +11,7 @@ import { catalogRuleFaceOf } from "./tool-registry.js";
 import { ORG_ADJUDICATION_TIMEOUT_MS, ORG_RULE_DECISION_REASON, ORG_UNAVAILABLE_DECISION_REASON, settleOrgVerdictWithin } from "./permission-rule-org.js";
 import { exitGate } from "./runner/gate-exit.js";
 import { traceHookCrash } from "./gate-crash-trace.js";
-import { createGateDeadline, awaitWriteProtectionJudgment } from "./gate-bounded-await.js";
+import { createGateDeadline, awaitWriteProtectionJudgment, withGateTimeout } from "./gate-bounded-await.js";
 import { thrownText } from "./thrown-value.js";
 function isPlainOwnRecord(x) {
     try {
@@ -691,6 +691,28 @@ export async function runGateLanes(pass) {
                         pass.deniedBy = "write_protection";
                     }
                 }
+                if (editDenied === undefined && input.shellReadCheck !== undefined) {
+                    const station = input.shellReadCheck;
+                    const judged = station.judge(toolName, editArgs, input.trackedCwd?.(), callSignal ?? input.abortSignal, { seat: "rejudge", toolCallId });
+                    if (judged !== null) {
+                        let verdict;
+                        try {
+                            verdict = await withGateTimeout(judged, boundedAwaitDeadlineMs(), callSignal ?? input.abortSignal, "shellReadStation");
+                        }
+                        catch {
+                            verdict = station.unanswered(toolName, "the read station could not answer");
+                        }
+                        if (verdict.disposition !== "vouch") {
+                            editDenied = {
+                                action: "deny",
+                                message: verdict.sentence ?? `the approved edit for "${toolName}" reads where the read boundary does not vouch — denied fail-closed; re-submit the command as a fresh call and answer its card`,
+                            };
+                            pass.deniedBy = "read_boundary";
+                            if (verdict.details !== undefined)
+                                pass.denyDetails = verdict.details;
+                        }
+                    }
+                }
                 pass.decision = editDenied ?? { ...pass.decision, updatedInput: editArgs };
             }
             else if (pass.decision.action === "allow" && pass.decision.updatedInput === undefined && resolved.presentedInput !== undefined) {

package/dist/core/gate-outcome.d.ts

@@ -154,8 +154,11 @@ export type SettlementRefusalTableCoversEveryKind = AssertAllKeysHandled<Exclude
  *    path that no approval covers.
  *  - `ask_resolution` — the ask's own settlement is the refusal (a person said no, a window elapsed,
  *    nobody could be asked…); the detail is on {@link GateOutcome.settlement}.
+ *  - `read_boundary` — the shell read station refused: a deny-listed read (refused on every seat, with no
+ *    ask), a read the read-only shell face may not make, or a rewritten / re-established command whose reads
+ *    no longer are what a person approved.
  */
-export declare const DENIED_BY_VALUES: readonly ["policy", "hook", "org", "persisted_rule", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution"];
+export declare const DENIED_BY_VALUES: readonly ["policy", "hook", "org", "persisted_rule", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution", "read_boundary"];
 export type DeniedBy = (typeof DENIED_BY_VALUES)[number];
 /** Membership test for {@link DeniedBy}. */
 export declare function isDeniedBy(v: unknown): v is DeniedBy;
@@ -165,7 +168,8 @@ export declare function isDeniedBy(v: unknown): v is DeniedBy;
  *  classifier, plan mode and compliance run before any ask exists, and `ask_resolution` IS the
  *  settlement, not a veto of it. `persisted_rule` = a person's own standing DENY row (their settings'
  *  deny list, imported) — the personal-store sibling of `org`, and like it re-judged on an edited
- *  command. */
+ *  command. `read_boundary` vetoes too: the rewrite re-judge and the pre-spawn re-establishment run after
+ *  the person's yes, on bytes or targets the person never saw. */
 export declare const DENIED_BY_MAY_VETO: {
     readonly policy: true;
     readonly hook: true;
@@ -176,6 +180,7 @@ export declare const DENIED_BY_MAY_VETO: {
     readonly compliance: false;
     readonly write_protection: true;
     readonly ask_resolution: false;
+    readonly read_boundary: true;
 };
 /** Compile-time fence: `never` while every deny layer has a veto row. */
 export type VetoTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedBy, keyof typeof DENIED_BY_MAY_VETO>>;
@@ -209,6 +214,7 @@ export declare const DENIED_BY_MAY_CARRY_CAUSE: {
     readonly compliance: false;
     readonly write_protection: false;
     readonly ask_resolution: false;
+    readonly read_boundary: false;
 };
 /** Compile-time fence: `never` while every deny layer has a cause row. */
 export type CauseTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedBy, keyof typeof DENIED_BY_MAY_CARRY_CAUSE>>;

package/dist/core/gate-outcome.js

@@ -39,7 +39,7 @@ export const SETTLEMENT_IS_REFUSAL = {
     blanket_allow_refused: true,
     task_aborted: true,
 };
-export const DENIED_BY_VALUES = ["policy", "hook", "org", "persisted_rule", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution"];
+export const DENIED_BY_VALUES = ["policy", "hook", "org", "persisted_rule", "classifier", "plan_mode", "compliance", "write_protection", "ask_resolution", "read_boundary"];
 const DENIED_BY_SET = new Set(DENIED_BY_VALUES);
 export function isDeniedBy(v) {
     return DENIED_BY_SET.has(v);
@@ -54,6 +54,7 @@ export const DENIED_BY_MAY_VETO = {
     compliance: false,
     write_protection: true,
     ask_resolution: false,
+    read_boundary: true,
 };
 export const CLASSIFIER_DENY_CAUSES = ["unavailable", "parse_error"];
 const CLASSIFIER_DENY_CAUSE_SET = new Set(CLASSIFIER_DENY_CAUSES);
@@ -70,6 +71,7 @@ export const DENIED_BY_MAY_CARRY_CAUSE = {
     compliance: false,
     write_protection: false,
     ask_resolution: false,
+    read_boundary: false,
 };
 export function screenGateOutcome(g) {
     const defects = [];

package/dist/core/hooks.d.ts

@@ -732,6 +732,16 @@ export interface HookInvocationIdentity {
      *  UNTRUSTED display text (model-chosen) — already single-line-bounded at mint (same
      *  `inlineUntrusted` treatment as the `task_progress` name lane); never an identity key. */
     readonly agentName?: string;
+    /** The EXPLICIT `Agent({name})` spawn identity, when the spawn carried one — sema's teammate key
+     *  (validated at spawn: `^[A-Za-z0-9][A-Za-z0-9_-]{0,63}$`, never `main`). The same string the
+     *  child's roster row, its uplink `from` label and its `task_progress.spawnName` carry, so a hook
+     *  seat binds "which teammate" by string equality. ABSENT = an unnamed delegation (not a
+     *  teammate); {@link agentName} above stays the DISPLAY label and is never an identity key. */
+    readonly spawnName?: string;
+    /** The RESOLVED subagent type the leg was spawned as (`"general-purpose"` / `"fork"` / a roster
+     *  definition's name — the fleet row's `agentType` word, never the description). Absent on a
+     *  top-level run and on a leg whose spawner threaded no type (a workflow-lane agent). */
+    readonly agentType?: string;
     /** The spawning Agent tool call's own id, when this leg runs under one — the delegation-chain
      *  position anchor ({@link import("./types.js").TaskEvent}'s `parentToolCallId` twin). Absent on
      *  a top-level run and on a directly-started workflow child (no launching tool call — no id is
@@ -919,6 +929,11 @@ export interface ToolGateResult {
     gate?: GateOutcome;
     /** Rewritten args to execute with (re-validated by the loop); omitted when nothing rewrote. */
     updatedInput?: unknown;
+    /** A blocking refusal's structured details, when the refusing station minted any (the shell read station's
+     *  `read_path_denied` / `readonly_out_of_root` cards): the loop attaches them to the error result it mints
+     *  from `reason`, so the refusal reaches `tool_end.structured` / `errorCode` exactly as the tool's own
+     *  refusal of the same finding did. Absent on every other block. */
+    details?: unknown;
     /**
      * design/45: the gate routed a policy `ask` to a **durable suspension** (no synchronous approver).
      * `suspendAsk` already persisted the checkpoint and aborted the run; the caller records this so the
@@ -1362,6 +1377,20 @@ export interface ToolGateInput {
      * point there), a promise for a covered write. Absent ⇒ no table (`[]`) and the decision path is byte-identical.
      */
     writeProtectionCheck?: import("./write-protect.js").WriteProtectionCheck;
+    /**
+     * The shell READ STATION — ENGINE-BUILT by the hands phase (`createShellReadStation`,
+     * `src/tools/fs/shell-read-check.ts`) for the shell-running tools of this leg, never a deployment callback.
+     * Judges the FINAL args of a shell call: ONE parse of the command into its read candidates, each
+     * established against the execution environment (symlinks resolved, patterns expanded, traversal roots
+     * enumerated, within a bound) and judged by the leg's read deny seat and its containment roots. A
+     * POLICY-class member of the fold: a deny-listed read is REFUSED (`deniedBy: "read_boundary"`, composing
+     * under `deny > ask > allow`), an out-of-root or unestablishable read tightens a surviving allow to a
+     * MANDATED ask (or marks an existing ask mandated), a read the station declined to judge tightens to an
+     * ordinary ask on the classify seat and a mandated one on the off seat, and a vouched call is untouched.
+     * `null` SYNCHRONOUSLY for a call it does not cover (no suspension point there), a promise for a shell
+     * call. Absent ⇒ no station (no shell mounted) and the decision path is byte-identical.
+     */
+    shellReadCheck?: import("../tools/fs/shell-read-check.js").ShellReadCheck;
     /**
      * design/143 批2 (A, CC 2.1.207 auto mode): when present, a surviving `ask` is routed to the
      * small-model policy CLASSIFIER before any human/durable resolution:

package/dist/core/hooks.js

@@ -167,6 +167,8 @@ export function mintHookInvocationIdentity(facts) {
         isDelegatedChild: facts.isDelegatedChild,
         ...(facts.insideFork === true ? { insideFork: true } : {}),
         ...(facts.agentName !== undefined ? { agentName: inlineUntrusted(facts.agentName.slice(0, 320), IDENTITY_AGENT_NAME_MAX) } : {}),
+        ...(facts.spawnName !== undefined ? { spawnName: inlineUntrusted(facts.spawnName.slice(0, 320), IDENTITY_AGENT_NAME_MAX) } : {}),
+        ...(facts.agentType !== undefined ? { agentType: inlineUntrusted(facts.agentType.slice(0, 320), IDENTITY_AGENT_NAME_MAX) } : {}),
         ...(facts.parentToolCallId !== undefined ? { parentToolCallId: facts.parentToolCallId } : {}),
     }));
 }

package/dist/core/mailbox-store.d.ts

@@ -25,6 +25,11 @@ export interface MailboxMessage {
 export interface MailboxPeerMeta {
     /** The sending session's id (reply routing). */
     fromSession?: string;
+    /** The delegation-tree ROOT the sender belongs to, stamped by the park seat of a session that
+     *  received the frame through its own child uplink — never by the sender. A recipient whose
+     *  session IS this root reads the record as a teammate's words (same tree = same admission as the
+     *  live uplink: the admission gate runs, the cross-session parity hold does not). */
+    fromRoot?: string;
     /** The sender's permission-mode class at send time — the drain judges parity against the RECEIVER. */
     fromMode?: MailboxPeerFromMode;
     /** The admission gate's sender key (rate/dedup axis). */

package/dist/core/mailbox-store.js

@@ -4,7 +4,7 @@ export const MAILBOX_PEER_RECORD_KINDS = ["peer_message", "idle_notice", "delive
 export const MAILBOX_PEER_NOTICE_STATES = ["held", "denied", "expired", "delivered", "refused", "dropped", "idle", "exited", "unavailable"];
 export const MAILBOX_INVALID_PEER_META_CODE = "mailbox.invalid_peer_meta";
 export const MAILBOX_CROSS_PROCESS_UNSAFE_CODE = "mailbox.cross_process_unsafe";
-const PEER_META_STRING_KEYS = ["fromSession", "senderKey", "fromScope", "gateReceiptId"];
+const PEER_META_STRING_KEYS = ["fromSession", "fromRoot", "senderKey", "fromScope", "gateReceiptId"];
 export function readMailboxPeerMeta(raw) {
     if (raw === undefined)
         return undefined;

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

@@ -9,10 +9,11 @@
  * 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 { Hooks } from "./hooks.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" | "memory">;
+export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "clientContext" | "onQuestion" | "hooks" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "memory">;
 /**
  * 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
@@ -22,6 +23,10 @@ export type ParentSpecSeatFields = Pick<TaskSpec, "principal" | "oneShot" | "cli
  *  · `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.
+ *  · `hooks` — the parent's SPEC-level hook seams (`spec.hooks`, the request-level lifecycle hooks a host mounts from
+ *    the user's settings). A deployment's `RunnerDeps.hooks` already serve every leg; the spec-level seams did not,
+ *    so a `stop` seat a user wired ran for the leader and never for its teammates (CC runs `SubagentStop` from the
+ *    same settings). Same law as `onQuestion`: a child's own value wins, the seat fills an unset one.
  *  · `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),
@@ -34,6 +39,7 @@ export interface ParentSpecSeat {
     readonly oneShot?: true;
     readonly clientContext?: TaskSpec["clientContext"];
     readonly onQuestion?: OnQuestion;
+    readonly hooks?: Hooks;
     readonly additionalDirectories?: readonly string[];
     readonly additionalReadDirectories?: readonly string[];
     readonly envFacts?: TaskSpec["envFacts"];

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

@@ -4,6 +4,7 @@ export function parentSpecSeatOf(spec, frozenOnQuestion) {
         ...(spec.oneShot === true ? { oneShot: true } : {}),
         ...(spec.clientContext !== undefined ? { clientContext: spec.clientContext } : {}),
         ...(frozenOnQuestion !== undefined ? { onQuestion: frozenOnQuestion } : {}),
+        ...(spec.hooks !== undefined ? { hooks: spec.hooks } : {}),
         ...(spec.additionalDirectories !== undefined ? { additionalDirectories: Object.freeze([...spec.additionalDirectories]) } : {}),
         ...(spec.additionalReadDirectories !== undefined ? { additionalReadDirectories: Object.freeze([...spec.additionalReadDirectories]) } : {}),
         ...(spec.envFacts !== undefined ? { envFacts: Object.freeze({ ...spec.envFacts }) } : {}),
@@ -20,6 +21,7 @@ export function applyParentSpecSeat(child, seat) {
         ...fill("principal", seat.principal),
         ...fill("clientContext", seat.clientContext),
         ...fill("onQuestion", seat.onQuestion),
+        ...fill("hooks", seat.hooks),
         ...fill("additionalDirectories", (seat.additionalDirectories !== undefined ? [...seat.additionalDirectories] : undefined)),
         ...fill("additionalReadDirectories", (seat.additionalReadDirectories !== undefined ? [...seat.additionalReadDirectories] : undefined)),
         ...fill("envFacts", (seat.envFacts !== undefined ? { ...seat.envFacts } : undefined)),

package/dist/core/permission-rule-consent.js

@@ -1,7 +1,7 @@
 import { randomBytes } from "node:crypto";
 import { escapeForDisclosure, hasUnrenderableCharacters, parseRuleText, ruleAdmitsCommand, ruleBreadthWarningsOf, segmentCoverageOf, suggestRulesForCommand, RULE_BEHAVIORS, RULE_BEHAVIOR_PRECEDENCE, isRuleBehavior, } from "./permission-rule-model.js";
 import { effectiveOrThrow } from "./permission-rule-provider.js";
-import { errText, isValidConsentScope, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
+import { errText, isValidConsentScope, landRuleAdd, sameRuleOwner, sameScope, writerOf } from "./permission-rule-store.js";
 export class InMemoryRuleApprovalRecordStore {
     rows = new Map();
     async get(id) {
@@ -600,7 +600,6 @@ export async function redeemRuleTicket(opts) {
     }
     return await applyRedemption({ deps: opts.deps, owner: caller, candidate, parsedRule: parsedRule.rule, dot, recordId: rec.id, kind: rec.kind, replay: known !== undefined, ...(siblingsOf !== undefined ? { siblingsOf } : {}) });
 }
-const REDEEM_MAX_ATTEMPTS = 8;
 async function tighteningSiblingsStand(rec, offer, index, store, durableSnapshot) {
     for (const member of offerMembersOf(offer)) {
         if (member === index)
@@ -630,52 +629,35 @@ async function applyRedemption(args) {
     if (writer === undefined)
         return { status: "refused", reason: "the resolved permission-rule store has no write face" };
     const origin = originOfRecordKind(args.kind);
-    for (let attempt = 0; attempt < REDEEM_MAX_ATTEMPTS; attempt++) {
-        let rev;
-        try {
-            const snapshot = await effectiveOrThrow(store);
-            rev = snapshot.rev;
-            if (args.siblingsOf !== undefined && !(await tighteningSiblingsStand(args.siblingsOf.rec, args.siblingsOf.offer, args.siblingsOf.index, store, snapshot))) {
-                return {
-                    status: "refused",
-                    reason: "withheld: this allow belongs to a batch whose deny/ask members do not all stand in the store — an allow must not stand wider than the list that was confirmed; redeem the batch (redeemRuleBatch) so the tightening members land first, or draw a fresh card",
-                };
+    const siblings = args.siblingsOf;
+    const landing = await landRuleAdd({
+        store,
+        writer,
+        delta: {
+            kind: "redemption-add",
+            behavior: args.parsedRule.behavior,
+            rule: args.parsedRule.rule,
+            scope: args.candidate.scope,
+            tool: args.parsedRule.tool,
+            match: args.parsedRule.match,
+            command: args.parsedRule.command,
+            add: { dot: args.dot, origin, createdAt: nowIso(args.deps) },
+            redemption: {
+                recordId: args.recordId,
+                ...(args.owner.kind === "principal" ? { principal: args.owner.principal } : { owner: args.owner }),
+            },
+        },
+        ...(siblings !== undefined
+            ? {
+                preflight: async (snapshot) => (await tighteningSiblingsStand(siblings.rec, siblings.offer, siblings.index, store, snapshot))
+                    ? undefined
+                    : "withheld: this allow belongs to a batch whose deny/ask members do not all stand in the store — an allow must not stand wider than the list that was confirmed; redeem the batch (redeemRuleBatch) so the tightening members land first, or draw a fresh card",
             }
-        }
-        catch (err) {
-            return { status: "refused", reason: `could not read the permission-rule store: ${errText(err)}` };
-        }
-        let res;
-        try {
-            res = await writer.apply({
-                kind: "redemption-add",
-                behavior: args.parsedRule.behavior,
-                rule: args.parsedRule.rule,
-                scope: args.candidate.scope,
-                tool: args.parsedRule.tool,
-                match: args.parsedRule.match,
-                command: args.parsedRule.command,
-                add: { dot: args.dot, origin, createdAt: nowIso(args.deps) },
-                redemption: {
-                    recordId: args.recordId,
-                    ...(args.owner.kind === "principal" ? { principal: args.owner.principal } : { owner: args.owner }),
-                },
-            }, { expectedRev: rev });
-        }
-        catch (err) {
-            return { status: "refused", reason: `the permission-rule store refused the write: ${errText(err)}` };
-        }
-        if ("refused" in res) {
-            return {
-                status: "refused",
-                reason: "the session this authorization targets has ended — a session rule dies with its session, and a late or replayed redemption cannot revive it (re-trigger the command in a live session for a fresh card)",
-            };
-        }
-        if (!("conflict" in res)) {
-            return { status: "redeemed", behavior: args.parsedRule.behavior, rule: args.parsedRule.rule, scope: args.candidate.scope, dot: args.dot, rev: res.rev, alreadyRedeemed: args.replay };
-        }
-    }
-    return { status: "refused", reason: `optimistic-concurrency retries exhausted after ${REDEEM_MAX_ATTEMPTS} attempts` };
+            : {}),
+    });
+    if (!landing.landed)
+        return { status: "refused", reason: landing.reason };
+    return { status: "redeemed", behavior: args.parsedRule.behavior, rule: args.parsedRule.rule, scope: args.candidate.scope, dot: args.dot, rev: landing.rev, alreadyRedeemed: args.replay };
 }
 function originOfRecordKind(kind) {
     return kind === "import" ? "imported-cc" : kind === "starter" ? "starter" : "user";

package/dist/core/permission-rule-provider.js

@@ -111,11 +111,12 @@ function routingWriter(durable, session) {
         nextDot: () => durable.nextDot(),
         readRaw: () => durable.readRaw(),
         apply: async (delta, opts) => {
-            const scope = delta.kind === "redemption-add" ? structuredClone(delta.scope) : undefined;
-            if (delta.kind !== "redemption-add" || scope?.kind !== "session")
+            const isAdd = delta.kind === "redemption-add" || delta.kind === "tighten-add";
+            const scope = isAdd ? structuredClone(delta.scope) : undefined;
+            if (!isAdd || scope?.kind !== "session")
                 return durable.apply(delta, opts);
             if (session === undefined) {
-                const e = new Error("a session-scope rule has nowhere to land — this deployment configured no session rule partition (createPermissionRuleStoreProvider({ session })); refusing the redemption-add");
+                const e = new Error(`a session-scope rule has nowhere to land — this deployment configured no session rule partition (createPermissionRuleStoreProvider({ session })); refusing the ${delta.kind}`);
                 e.code = "unsupported.session_scope_store";
                 throw e;
             }

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

@@ -150,6 +150,30 @@ export interface RuleAddDelta {
     add: RuleAdd;
     redemption: RedemptionAuthorization;
 }
+/**
+ * The TIGHTENING add — the true dual of {@link RuleDeleteDelta}, and the reason it is a separate arm
+ * rather than a `redemption-add` with the authorization left out: a delta named for a redemption that
+ * carries no redemption is a name that lies. This arm carries NO authorization block at all, exactly as
+ * `tighten-delete` does, because it needs none: a host may narrow on a person's behalf, it may not
+ * widen — so `behavior` excludes `allow` IN THE TYPE and the widening direction cannot reach this door.
+ * Minting a standing approval still takes a person's consent record, which is what `redemption-add` is.
+ *
+ * The QUARANTINE fence ({@link assertRedemptionNotQuarantined}) applies to `redemption-add` only, and
+ * not because it was forgotten here: the fence exists to stop a REPLAYED approval record from reviving
+ * an add its dot was quarantined for. A tightening add has no record and is never replayed — its dot is
+ * minted once, at the call — so there is no replay for the fence to catch.
+ */
+export interface RuleTightenAddDelta {
+    kind: "tighten-add";
+    /** The tightening members only. `allow` is not in the type: see this interface's doc. */
+    behavior: Exclude<RuleBehavior, "allow">;
+    rule: string;
+    scope: RuleScope;
+    tool: PersistedRule["tool"];
+    match: PersistedRule["match"];
+    command: string;
+    add: RuleAdd;
+}
 /** The delete half: appending one tombstone, and nothing else. */
 export interface RuleDeleteDelta {
     kind: "tighten-delete";
@@ -196,7 +220,7 @@ export interface RuleSyncJoinDelta {
  * again AT THE BACKEND: the fifth door of design/179 §4's validator list closes here, not at the
  * calling layer, and closes identically for every caller.
  */
-export type RuleWriteDelta = RuleAddDelta | RuleDeleteDelta | RuleSyncJoinDelta;
+export type RuleWriteDelta = RuleAddDelta | RuleTightenAddDelta | RuleDeleteDelta | RuleSyncJoinDelta;
 /**
  * The backend write face. Exported as part of the BACKEND CONTRACT (ruled 2026-08-10) so an
  * out-of-repo store implementation hangs the same face the file backend does, instead of mirroring the
@@ -269,7 +293,7 @@ export declare function sameRuleIdentity(a: {
 export declare function applyTombstones(rules: readonly PersistedRule[], tombstones: readonly RuleTombstone[]): PersistedRule[];
 /** Fold one delta into a raw rule set, returning the new set. Pure — the backends share it so the file and
  *  in-memory forms cannot drift in what a delta MEANS. */
-export declare function foldDelta(rules: readonly PersistedRule[], delta: RuleAddDelta): PersistedRule[];
+export declare function foldDelta(rules: readonly PersistedRule[], delta: RuleAddDelta | RuleTightenAddDelta): PersistedRule[];
 /** Every add dot present in a rule set. */
 export declare function addDotsOf(rules: readonly PersistedRule[]): RuleDot[];
 /**
@@ -307,7 +331,7 @@ export declare function assertDeleteDeltaCarriesNoAdd(delta: RuleDeleteDelta): v
  * any lane — host-side import doors included — that writes rows into a persisted store carries the
  * durable two-member face.
  */
-export declare function assertWriteDeltaScopeDurable(delta: RuleAddDelta | RuleDeleteDelta): void;
+export declare function assertWriteDeltaScopeDurable(delta: RuleAddDelta | RuleTightenAddDelta | RuleDeleteDelta): void;
 /**
  * The state one sync round exchanges: raw adds (tombstoned dots NOT pre-filtered) plus tombstones.
  * The live view is always DERIVED (`applyTombstones`); the join below never deletes anything.
@@ -497,6 +521,16 @@ export declare function applySyncJoin(cur: RuleSyncJoinBase, delta: RuleSyncJoin
 export declare function assertRedemptionNotQuarantined(quarantined: readonly QuarantinedRuleAdd[], delta: RuleAddDelta): void;
 /** Integrity fingerprint over a store's own facts. Corruption detection, not tamper-proofing. */
 export declare function ruleStoreChecksum(payload: unknown): Promise<string>;
+/**
+ * What a removal may say about the rule identity it just tombstoned. THREE words, not a boolean, for the
+ * same reason {@link RuleAddLanding} has `committed: "no" | "unknown"`: the answer comes from a read-back,
+ * and a read-back can fail. `yes` and `no` are things the store said; `unknown` is the honest word for a
+ * look that did not happen — reporting `no` there would render "we could not see it" as "it is not there",
+ * which is the one sentence this domain refuses to say anywhere else ("we cannot see the rules" is never
+ * "there are none").
+ */
+export declare const REMOVAL_LIVENESS_WORDS: readonly ["yes", "no", "unknown"];
+export type RemovalLiveness = (typeof REMOVAL_LIVENESS_WORDS)[number];
 /**
  * The result of a removal.
  *
@@ -506,19 +540,26 @@ export declare function ruleStoreChecksum(payload: unknown): Promise<string>;
 export type RemoveResult = 
 /** The tombstone landed and none of the observed dots survive. `stillLive` reports whether an approval
  *  that landed DURING this call keeps the rule alive anyway (add-wins) — a real outcome with a name,
- *  not an anomaly. */
+ *  not an anomaly — or {@link RemovalLiveness} `unknown` when the read-back that answers it could not be
+ *  taken. A consumer reading `unknown` as "removed" has re-introduced the very over-claim the third word
+ *  exists to prevent: the tombstone landed, the rule's liveness is UNOBSERVED, reconcile with `list()`. */
 {
     status: "removed";
     rev: number;
-    stillLive: boolean;
+    stillLive: RemovalLiveness;
 }
 /** Nothing to remove — including a repeated delete. No empty tombstone is minted. */
  | {
     status: "no-op";
     rev: number;
 }
-/** Terminal failure, confirmed by read-back to have written NOTHING. When the read-back itself failed,
- *  `error` says so and the caller reconciles with `list()`. */
+/** Terminal failure, in one of two strengths the `error` text distinguishes — word for word the dual of
+ *  {@link AddResult}'s. When the STORE answered every attempt (the compare-and-set simply lost), the
+ *  read-back confirms nothing was written and the text says so plainly. When the apply THREW, a missing
+ *  tombstone cannot tell a write that never landed from one whose evidence a paired collection erased
+ *  (`collectBelowFrontier` recycles a tombstone together with the adds it covered), so that outcome is
+ *  reported INDETERMINATE and the caller reconciles with `list()` rather than retrying blind. When the
+ *  read-back itself failed, `error` says so and the caller reconciles with `list()` too. */
  | {
     status: "failed";
     error: string;
@@ -544,6 +585,101 @@ export declare function removePersistedRule(opts: {
     principal: string | RuleOwner;
     provider: import("./permission-rule-provider.js").PermissionRuleStoreProvider;
 }): Promise<RemoveResult>;
+/**
+ * What the ONE add-write path answered. `landed` carries the revision the add committed at; every other
+ * terminal state is a single refusal string, which each door renders in its own vocabulary (the consent
+ * protocol says `refused`, the record-less entry says `failed`) — one mechanism, two spellings, never
+ * two mechanisms.
+ */
+export type RuleAddLanding = {
+    landed: true;
+    rev: number;
+}
+/** `committed` is what the caller may CLAIM afterwards. `"no"` means the store itself answered — a
+ *  read that failed before any write, a refused preflight, an epoch seal, or a compare-and-set that
+ *  lost every attempt: each of those is the store saying nothing landed. `"unknown"` means the apply
+ *  THREW, which proves nothing either way: a backend can commit and then lose its acknowledgement. */
+ | {
+    landed: false;
+    reason: string;
+    committed: "no" | "unknown";
+};
+/**
+ * Land ONE add — the terminal write both doors take (the consent protocol's redemption and the
+ * record-less tightening entry below). Optimistic: every attempt re-reads the store, anchors the
+ * compare-and-set to that revision, and retries a conflict without rebuilding the add (the dot is the
+ * add's identity and is minted once, by the caller, so a retry can never mint a second).
+ *
+ * The scope routing is the writer's ({@link writerOf}): a session-scope add lands in the session
+ * partition, everything else in the durable one — one path, so the two doors cannot disagree about
+ * where a rule goes.
+ */
+export declare function landRuleAdd(args: {
+    store: import("./permission-rule-provider.js").PermissionRuleStore;
+    writer: PermissionRuleWriter;
+    /** Either add arm, whole. The kinds are dispatched EXHAUSTIVELY below, so a third add arm cannot be
+     *  added to the union without this function being told what it means. */
+    delta: RuleAddDelta | RuleTightenAddDelta;
+    /** Judged on EVERY attempt's snapshot — the very revision the write below is anchored to, so a fact
+     *  that changed in between conflicts the write and is re-judged. A returned string refuses. */
+    preflight?: (snapshot: import("./permission-rule-provider.js").EffectivePermissionRules) => Promise<string | undefined>;
+}): Promise<RuleAddLanding>;
+/**
+ * The result of an add — the dual of {@link RemoveResult}, word for word where the two mean the same
+ * thing. `conflict` is not a member for the same reason: the retry loop is inside.
+ */
+export type AddResult = 
+/** The add landed; `dot` is its audit identity (the same value a removal's tombstone will name).
+ *  Deliberately WITHOUT a `stillLive` twin of {@link RemoveResult}: a removal's twin reports the
+ *  semilattice's own add-wins resolution, a structural outcome of the write; a fresh dot has no such
+ *  resolution to report, and a removal that lands afterwards is an ordinary later event `list()`
+ *  answers. */
+{
+    status: "added";
+    rev: number;
+    dot: RuleDot;
+}
+/** An equivalent rule is already live in this bucket — the instruction is already in effect, and no
+ *  second dot is minted. Repeating the call is a no-op, exactly as repeating a delete is. */
+ | {
+    status: "no-op";
+    rev: number;
+}
+/** Terminal failure, in one of two strengths the `error` text distinguishes. When the STORE answered
+ *  (a read that failed before any write, a refused preflight, an epoch seal, a compare-and-set that
+ *  lost every attempt) nothing landed and the text says so plainly. When the apply THREW, the write
+ *  may have committed and lost its acknowledgement: the read-back asks the raw face, where an add
+ *  survives the tombstone a concurrent removal laid on it — but a sync collection can erase even
+ *  that, so a dot it cannot find is reported INDETERMINATE rather than as a confirmed nothing, and
+ *  the caller reconciles with `list()` instead of retrying blind (a blind retry mints a fresh dot and
+ *  can reinstate a restriction somebody had just removed). */
+ | {
+    status: "failed";
+    error: string;
+};
+/**
+ * Add a persisted rule in ONE step, with no approval record.
+ *
+ * The dual of {@link removePersistedRule}, and bounded by the same asymmetry: a host may narrow on a
+ * person's behalf, it may not widen. So this entry writes the TIGHTENING direction only — `deny` and
+ * `ask` — and `allow` is not spellable here at all (minting a standing approval still takes a person's
+ * consent record: prepare → confirm → redeem). A JS caller that spells it anyway meets a loud refusal.
+ *
+ * The provenance is MINTED HERE as `user`: this entry takes no origin argument, so a host cannot claim
+ * a rule came from an import or a starter set. Before it existed, the only way to land a rule was to
+ * borrow the approval-record legs, which stamped the borrowed record's kind onto a write nobody had
+ * approved — a second, unverified story about where a rule came from.
+ */
+export declare function addPersistedRule(opts: {
+    /** The identity's behavior member. `allow` is deliberately not in the type — see the entry's doc. */
+    behavior: Exclude<RuleBehavior, "allow">;
+    rule: string;
+    scope: RuleScope;
+    /** Whose bucket — the same two spellings {@link removePersistedRule} takes: a bare string is the
+     *  principal shorthand, the structural {@link RuleOwner} adds the local-owner bucket. */
+    principal: string | RuleOwner;
+    provider: import("./permission-rule-provider.js").PermissionRuleStoreProvider;
+}): Promise<AddResult>;
 export declare function errText(err: unknown): string;
 /** A durable partition that always reports zero rules — what an unauthenticated principal resolves to. */
 export declare const EMPTY_DURABLE_RULE_PARTITION: DurableRulePartition;