@sema-agent/core 7.24.4 → 7.25.1

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;

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

@@ -56,19 +56,19 @@ export function assertDeleteDeltaCarriesNoAdd(delta) {
     }
 }
 export function assertWriteDeltaScopeDurable(delta) {
-    const scope = delta.kind === "redemption-add" ? delta.scope : delta.tombstone?.scope;
+    const scope = delta.kind === "tighten-delete" ? delta.tombstone?.scope : delta.scope;
     if (scope?.kind === "session") {
-        const e = new Error(delta.kind === "redemption-add"
-            ? "a session-scope rule cannot enter the persisted store — its home is the session's own overlay (design/382 §4.3); refusing the redemption-add"
-            : "a session-scope tombstone cannot enter the persisted store — session rows are not individually deletable and die with their session (design/382 §4.3/§10); refusing the tighten-delete");
+        const e = new Error(delta.kind === "tighten-delete"
+            ? "a session-scope tombstone cannot enter the persisted store — session rows are not individually deletable and die with their session (design/382 §4.3/§10); refusing the tighten-delete"
+            : `a session-scope rule cannot enter the persisted store — its home is the session's own overlay (design/382 §4.3); refusing the ${delta.kind}`);
         e.code = "unsupported.session_scope_store";
         throw e;
     }
     if (!isValidDurableScope(scope)) {
-        throw new Error(delta.kind === "redemption-add"
-            ? "a redemption-add whose scope is not a well-formed durable scope cannot enter the persisted store (design/382 §4.3: the face is {global, project-with-a-root}) — refusing the write"
-            :
-                "a tighten-delete must carry a tombstone whose scope is a well-formed durable scope (design/382 §4.3: the face is {global, project-with-a-root}) — refusing the write");
+        throw new Error(delta.kind === "tighten-delete"
+            ?
+                "a tighten-delete must carry a tombstone whose scope is a well-formed durable scope (design/382 §4.3: the face is {global, project-with-a-root}) — refusing the write"
+            : `a ${delta.kind} whose scope is not a well-formed durable scope cannot enter the persisted store (design/382 §4.3: the face is {global, project-with-a-root}) — refusing the write`);
     }
 }
 export function isValidConsentScope(scope) {
@@ -393,6 +393,7 @@ export async function ruleStoreChecksum(payload) {
     const { createHash } = await import("node:crypto");
     return `sha256:${createHash("sha256").update(canonicalize(payload), "utf8").digest("hex")}`;
 }
+export const REMOVAL_LIVENESS_WORDS = ["yes", "no", "unknown"];
 const REMOVE_MAX_ATTEMPTS = 8;
 export async function removePersistedRule(opts) {
     const behavior = opts.behavior;
@@ -435,6 +436,7 @@ export async function removePersistedRule(opts) {
     const tombstone = { behavior, rule, scope, removedDots, deletedBy: await writer.nextDot() };
     let expectedRev = snapshot.rev;
     let lastError = "";
+    let applyThrew = false;
     for (let attempt = 0; attempt < REMOVE_MAX_ATTEMPTS; attempt++) {
         try {
             const res = await writer.apply({ kind: "tighten-delete", tombstone }, { expectedRev });
@@ -442,37 +444,181 @@ export async function removePersistedRule(opts) {
                 return { status: "failed", error: `the store refused the tombstone (${res.refused}) — nothing was removed` };
             }
             if (!("conflict" in res)) {
-                let stillLive = false;
+                let stillLive;
                 try {
                     const after = await store.effective();
                     if (after.unreadable !== undefined)
                         throw new Error(after.unreadable);
-                    stillLive = after.rules.some((r) => sameRuleIdentity(r, identity) && isRuleLive(r));
+                    stillLive = after.rules.some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)) ? "yes" : "no";
                 }
                 catch {
-                    stillLive = false;
+                    stillLive = "unknown";
                 }
                 return { status: "removed", rev: res.rev, stillLive };
             }
             expectedRev = res.rev;
         }
         catch (err) {
+            applyThrew = true;
             lastError = errText(err);
             break;
         }
     }
-    const reason = lastError !== "" ? lastError : `optimistic-concurrency retries exhausted after ${REMOVE_MAX_ATTEMPTS} attempts`;
+    const reason = applyThrew
+        ? lastError !== ""
+            ? lastError
+            : "the permission-rule store threw while applying the tombstone, with no message"
+        : `optimistic-concurrency retries exhausted after ${REMOVE_MAX_ATTEMPTS} attempts`;
     try {
         const after = await writer.readRaw();
         const landed = after.tombstones.some((t) => t.deletedBy.actor === tombstone.deletedBy.actor && t.deletedBy.counter === tombstone.deletedBy.counter);
-        return landed
-            ? { status: "removed", rev: after.rev, stillLive: applyTombstones(after.rules, after.tombstones).some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)) }
-            : { status: "failed", error: `${reason} (read-back confirms no tombstone was written)` };
+        if (landed) {
+            return { status: "removed", rev: after.rev, stillLive: applyTombstones(after.rules, after.tombstones).some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)) ? "yes" : "no" };
+        }
+        return {
+            status: "failed",
+            error: applyThrew
+                ? `${reason}; the store retains no tombstone for this removal, which cannot tell a write that never landed from one whose evidence was collected — the outcome is indeterminate, reconcile with list()`
+                : `${reason} (read-back confirms no tombstone was written)`,
+        };
     }
     catch (err) {
         return { status: "failed", error: `${reason}; the read-back also failed (${errText(err)}) so this outcome is indeterminate — reconcile with list()` };
     }
 }
+const RULE_ADD_MAX_ATTEMPTS = 8;
+const SESSION_ENDED_REFUSAL = "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)";
+export async function landRuleAdd(args) {
+    switch (args.delta.kind) {
+        case "redemption-add":
+        case "tighten-add":
+            break;
+        default: {
+            const unreachable = args.delta;
+            throw new Error(`landRuleAdd: unhandled add delta ${JSON.stringify(unreachable)}`);
+        }
+    }
+    for (let attempt = 0; attempt < RULE_ADD_MAX_ATTEMPTS; attempt++) {
+        let rev;
+        try {
+            const snapshot = await args.store.effective();
+            if (snapshot.unreadable !== undefined)
+                throw new Error(snapshot.unreadable);
+            rev = snapshot.rev;
+            const refusal = await args.preflight?.(snapshot);
+            if (refusal !== undefined)
+                return { landed: false, reason: refusal, committed: "no" };
+        }
+        catch (err) {
+            return { landed: false, reason: `could not read the permission-rule store: ${errText(err)}`, committed: "no" };
+        }
+        let res;
+        try {
+            res = await args.writer.apply(args.delta, { expectedRev: rev });
+        }
+        catch (err) {
+            return { landed: false, reason: `the permission-rule store refused the write: ${errText(err)}`, committed: "unknown" };
+        }
+        if ("refused" in res)
+            return { landed: false, reason: SESSION_ENDED_REFUSAL, committed: "no" };
+        if (!("conflict" in res))
+            return { landed: true, rev: res.rev };
+    }
+    return { landed: false, reason: `optimistic-concurrency retries exhausted after ${RULE_ADD_MAX_ATTEMPTS} attempts`, committed: "no" };
+}
+export async function addPersistedRule(opts) {
+    const behavior = opts.behavior;
+    const ruleText = opts.rule;
+    const scope = structuredClone(opts.scope);
+    const target = opts.principal;
+    if (!isRuleBehavior(behavior)) {
+        return { status: "failed", error: `addPersistedRule: behavior ${escapeForDisclosure(behavior)} is not one of ${["deny", "ask", "allow"].join("/")} — refusing to name a rule identity nothing can carry` };
+    }
+    if (behavior === "allow") {
+        return {
+            status: "failed",
+            error: "addPersistedRule: an allow cannot be written through this entry — a standing approval is a person's yes and takes a consent record (prepare → confirm → redeem); this entry writes the tightening direction (deny/ask) only",
+        };
+    }
+    if (!isValidConsentScope(scope)) {
+        return { status: "failed", error: `addPersistedRule: ${escapeForDisclosure(JSON.stringify(scope))} is not a valid rule scope — refusing to write a row nothing can read back` };
+    }
+    const parsed = parseRuleText(ruleText, behavior);
+    if ("reject" in parsed)
+        return { status: "failed", error: `addPersistedRule: ${parsed.reject.code}: ${parsed.reject.message}` };
+    const identity = { behavior, rule: parsed.rule.rule, scope };
+    const owner = typeof target === "string" ? { kind: "principal", principal: target } : structuredClone(target);
+    const provider = opts.provider;
+    if (owner.kind === "local-owner" && provider.forLocalOwner === undefined) {
+        return { status: "failed", error: "this provider has no local-owner bucket (forLocalOwner is not implemented) — a local-owner rule cannot be added through it" };
+    }
+    const store = owner.kind === "local-owner" ? provider.forLocalOwner() : provider.forPrincipal(owner.principal);
+    const writer = writerOf(store);
+    if (writer === undefined) {
+        return { status: "failed", error: "the resolved permission-rule store has no write face — rules cannot be added through it" };
+    }
+    const query = scope.kind === "session" ? { sessionId: scope.sessionId } : undefined;
+    let snapshot;
+    try {
+        snapshot = await store.effective(query);
+    }
+    catch (err) {
+        return { status: "failed", error: `could not read the permission-rule store: ${errText(err)}` };
+    }
+    if (snapshot.unreadable !== undefined)
+        return { status: "failed", error: `could not read the permission-rule store: ${snapshot.unreadable}` };
+    if (snapshot.rules.some((r) => sameRuleIdentity(r, identity) && isRuleLive(r)))
+        return { status: "no-op", rev: snapshot.rev };
+    let dot;
+    try {
+        dot = await writer.nextDot();
+    }
+    catch (err) {
+        return { status: "failed", error: `could not mint the add's dot: ${errText(err)}` };
+    }
+    const landing = await landRuleAdd({
+        store,
+        writer,
+        delta: {
+            kind: "tighten-add",
+            behavior,
+            rule: parsed.rule.rule,
+            scope,
+            tool: parsed.rule.tool,
+            match: parsed.rule.match,
+            command: parsed.rule.command,
+            add: { dot, origin: "user", createdAt: new Date().toISOString() },
+        },
+    });
+    if (landing.landed)
+        return { status: "added", rev: landing.rev, dot };
+    if (landing.committed === "no")
+        return { status: "failed", error: landing.reason };
+    try {
+        let rev;
+        let rows;
+        let quarantinedRows = [];
+        if (scope.kind === "session") {
+            const view = await store.effective(query);
+            if (view.unreadable !== undefined)
+                throw new Error(view.unreadable);
+            ({ rev, rules: rows } = view);
+        }
+        else {
+            const raw = await writer.readRaw();
+            ({ rev, rules: rows } = raw);
+            quarantinedRows = raw.quarantined ?? [];
+        }
+        const stood = rows.some((r) => sameRuleIdentity(r, identity) && r.adds.some((a) => sameDot(a.dot, dot))) ||
+            quarantinedRows.some((q) => sameDot(q.add.dot, dot));
+        return stood
+            ? { status: "added", rev, dot }
+            : { status: "failed", error: `${landing.reason}; the store retains no trace of this add, which cannot tell a write that never landed from one whose evidence was collected — the outcome is indeterminate, reconcile with list()` };
+    }
+    catch (err) {
+        return { status: "failed", error: `${landing.reason}; the read-back also failed (${errText(err)}) so this outcome is indeterminate — reconcile with list()` };
+    }
+}
 export function errText(err) {
     return thrownText(err);
 }
@@ -525,6 +671,10 @@ export class InMemoryDurableRulePartition {
                 assertRedemptionNotQuarantined(this.quarantinedRows, delta);
                 this.rules = foldDelta(this.rules, delta);
             }
+            else if (delta.kind === "tighten-add") {
+                assertWriteDeltaScopeDurable(delta);
+                this.rules = foldDelta(this.rules, delta);
+            }
             else if (delta.kind === "tighten-delete") {
                 assertWriteDeltaScopeDurable(delta);
                 assertDeleteDeltaCarriesNoAdd(delta);

package/dist/core/runner/contracts.d.ts

@@ -382,6 +382,10 @@ export interface Prepared {
     /** The deployment's own caller policy, re-checked on a durable resume ONLY when the approver
      *  rewrote the pending call's args (see the composition site for why the edit case is special). */
     basePolicyForResumeEdit?: ToolPolicy;
+    /** The leg's shell READ STATION, re-run on a durable RESUME before an approved shell call executes: the parked leg's
+     *  admission died with that leg, so the resumed bytes are judged (and admitted for their pre-spawn re-establishment)
+     *  on THIS leg — a deny row found now vetoes, an operator's edit is judged on the `rejudge` seat. */
+    shellReadCheck?: import("../../tools/fs/shell-read-check.js").ShellReadCheck;
     /** The ORG adjudication face, re-resolved on a durable RESUME before an approved
      *  pending call executes. The resume path bypasses the harness gate by design (a human already
      *  adjudicated the checkpointed call), which is exactly where org policy skew is most likely: the
@@ -437,6 +441,14 @@ export interface Prepared {
      * leg always knows its identity.
      */
     hookIdentity: HookInvocationIdentity;
+    /**
+     * This session's DURABLE box, present iff this leg mounted the session-box drain (a top-level leg
+     * over a cross-process-safe mailbox with a grammatical session id). The notification lane binds it
+     * to the park seat ({@link import("../task-notification.js").PendingSessionNotifications.bindSessionBox})
+     * so a child's uplink frame parked for this session while it is idle lands in the box the next run
+     * drains — one mount judgment, the drain and the park read it alike. Absent ⇒ in-process parking.
+     */
+    sessionBox?: import("../task-notification.js").SessionBoxBinding;
     /**
      * The per-invocation TIME BOUND every hook seat of this leg runs under (`Hooks.timeoutMs`, already
      * validated — a garbage value was refused to the default and disclosed ONCE, here, rather than on
@@ -1252,6 +1264,7 @@ export interface InheritedGate {
         sessionId: string;
         principal?: string;
         rev: number;
+        gen?: number;
         rules: SessionPermissionRules;
     }>;
     /** The chain's effective shell-gate doctrine — the child folds it by max-rank with its own spec. */
@@ -1700,6 +1713,14 @@ export interface RunInternals {
      * every described child a "teammate" (clamp over-wide, addendum over-composed).
      */
     explicitAgentName?: string;
+    /**
+     * The RESOLVED subagent type this child was spawned as (`"general-purpose"` / `"fork"` / a roster
+     * definition's name — the same word the fleet row's `agentType` column carries; never the
+     * description). Read by the hook identity envelope (`identity.agentType`) so a process-level hook
+     * seat can tell WHAT kind of child it is serving without parsing display text. Trusted run-scoped
+     * channel (NOT a {@link TaskSpec} field); absent on a top-level run and on a workflow-lane agent.
+     */
+    spawnAgentType?: string;
     /**
      * The SPAWNING run's taskId, threaded at spawn (from the parent's
      * `ToolExecuteContext.taskId`) so this child's `task_progress` ticks carry `parentTaskId`. Lets a UI build the
@@ -1897,7 +1918,20 @@ export interface RunInternals {
      */
     parentNotify?: (notification: TaskNotificationPayload, opts?: {
         priority?: import("../task-notification.js").SystemInjectionPriority;
-    }) => void;
+    }) => unknown;
+    /**
+     * The ONE address `SendMessage("main")` names for this child — the session that hosts this child's
+     * lifecycle — paired with {@link parentNotify} at the same mint, three arms:
+     *  · a fresh spawn: the SPAWNER's session, whose live injector is `parentNotify`;
+     *  · a revival by that tree's ROOT (or any top-level session): the REVIVER's session, its injector;
+     *  · a revival by a SIBLING child, or by a host verb with no session: the row's ROOT session, and
+     *    NO `parentNotify` — a sibling is a peer the child addresses by name, not its main, and there is
+     *    no live callback into the root from either reviver. Such a child's "main" send reads the
+     *    honest not-deliverable text; its terminal still reaches the root through the root-anchor arm.
+     * The uplink receipt names this id so the model knows WHICH conversation "main" is. Absent on a
+     * top-level run. Trusted run-scoped channel (never a {@link TaskSpec} field).
+     */
+    uplinkSessionId?: string;
     /**
      * The PARENT run's subagent-retain ledger, threaded to a CHILD so its
      * SendMessage can continue a RETAINED SIBLING (the sibling's retain entry lives on the parent's
@@ -1917,7 +1951,7 @@ export interface RunInternals {
      */
     onNotifyInjectorReady?: (inject: (notification: TaskNotificationPayload, opts?: {
         priority?: import("../task-notification.js").SystemInjectionPriority;
-    }) => Promise<"queued" | "parked" | "dropped_duplicate">) => void;
+    }) => Promise<import("../task-notification.js").NotificationInjectionOutcome>) => void;
     /**
      * Per-task ISOLATION hint, a TRUSTED run-scoped channel filled ONLY by a core caller
      * (the workflow's `ctx.agent` when the SCRIPT passed `{ isolation: "worktree" }` as an OPTION) — NEVER a

package/dist/core/runner/gate-exit.d.ts

@@ -219,6 +219,15 @@ export interface GatePass {
      *  that ended as a refusal). The exit mints the outcome from it beside the ledger's `settled`; a refusal
      *  that reaches the exit without it is an engine defect and the mint throws. */
     deniedBy: DeniedBy | undefined;
+    /** borrowed-mutable — a refusing station's STRUCTURED details (the shell read station's refusal card), written
+     *  beside `deniedBy` by that station alone; the exit puts it on the gate result for the loop's error result.
+     *  OPTIONAL (the `probeUnanswered` form): the dispatch that builds the pass has nothing to declare here. */
+    denyDetails?: unknown;
+    /** borrowed-mutable — the shell read station's containment card behind a standing MANDATED ask (an out-of-root
+     *  or unestablishable read): when that ask ends as a refusal (a person's no, nobody to ask), the exit puts the
+     *  card on the gate result, so the refusal's `tool_end` still says WHAT was found (`readonly_out_of_root`) beside
+     *  WHO refused (`ask_resolution`). Writer: the fold's read station. */
+    shellReadDetails?: unknown;
     /** borrowed-mutable — the FORM of the classifier round behind a deny (`unavailable` / `parse_error`), written
      *  beside `deniedBy` by the gate's own classifier step (its attestation, read once) or by the fold / the
      *  re-check when an inherited station's attested deny arrives through the chain; undefined for a ruling
@@ -251,6 +260,11 @@ export interface GatePass {
      *  twin on the answered side, and narrower: the ask stays ordinary for every ANSWERER, and only the allow
      *  layer's read-only-command arm stands down. Writer: the fold. Reader: that arm, and nothing else. */
     probeBoundaryDeclined?: true;
+    /** borrowed-mutable — the shell read station minted the standing ask's directory-grant offer
+     *  (`probeReadRootCandidate`). Read by the classify seat's shape probe, which withdraws the offer when its
+     *  own objection stands beside the station's — the grant answers the station's finding, not the shape's.
+     *  Writer: the fold's read station. */
+    shellReadOffer?: true;
     /** borrowed-mutable — the write-protection judge covered this call and its table MATCHED: the allow
      *  layer must not clear the surviving ask, a live decider still may. Writer: the fold's fourth tighten,
      *  on BOTH its arms. Reader: the lanes' mandate. */

package/dist/core/runner/gate-exit.js

@@ -135,6 +135,10 @@ export async function exitGate(pass) {
             block: true,
             reason: formatHookFeedback(denyReason, input.reminderMark),
             gate,
+            ...(() => {
+                const details = pass.denyDetails ?? pass.shellReadDetails;
+                return details !== undefined ? { details } : {};
+            })(),
             preToolContext: pass.preToolContext,
         };
     }

package/dist/core/runner/prepare-delegation-surface.d.ts

@@ -1,7 +1,7 @@
 import type { AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
 import { type PeerLaneRefs } from "../../agents/peer-session-drain.js";
 import type { SubagentRetainLedger } from "../../agents/retain-ledger.js";
-import type { BashReadonlyRootBoundary } from "../../tools/fs/bash-readonly-classifier.js";
+import type { ShellReadAdmission } from "../../tools/fs/shell-read-check.js";
 import { type WorktreeSessionRef } from "../../tools/worktree.js";
 import type { CwdRef } from "../../tools/fs/index.js";
 import { type ToolResultStore } from "../tool-result-store.js";
@@ -19,7 +19,7 @@ export interface PrepareDelegationSurfaceInput {
     deps: Pick<RunnerDeps, "workflowRunStore" | "backgroundAgentStore" | "mailboxStore" | "rosterStore" | "peerAdmission" | "peerDirectory" | "onNotice" | "onBackgroundChildEvent" | "tracer">;
     /** borrowed-readonly — the trusted spawn-side channel: `parentNotify` (the delegated-child door), the uplink / sibling /
      *  identity seats the SendMessage mount forwards, `onTaskNotification`, `onSubagentSpawn`. Never mutated. */
-    internals: Pick<RunInternals, "parentNotify" | "parentPeerRef" | "parentRetainLedger" | "explicitAgentName" | "parentTaskId" | "parentSessionId" | "peerSelfRef" | "peerInboundChainRef" | "onTaskNotification" | "onSubagentSpawn"> | undefined;
+    internals: Pick<RunInternals, "parentNotify" | "parentPeerRef" | "uplinkSessionId" | "parentRetainLedger" | "explicitAgentName" | "parentTaskId" | "parentSessionId" | "peerSelfRef" | "peerInboundChainRef" | "onTaskNotification" | "onSubagentSpawn"> | undefined;
     /** borrowed-readonly — the resume leg, or undefined: `seed.activeWorktree` seeds the worktree session (checkpoint first). */
     resume: Pick<PrepareResume, "seed"> | undefined;
     /** borrowed-readonly — the acquired session id (the mounts' session axis). */
@@ -37,8 +37,8 @@ export interface PrepareDelegationSurfaceInput {
     runnerSelf: RunnerSelfSeat | undefined;
     /** borrowed-readonly — the background/workflow door's first half: the hands mount decided a real shell with write hands. */
     backgroundTaskToolsActive: boolean;
-    /** borrowed-readonly — this run's shell read boundary (declared at the hands phase), for `Monitor`: the only P11 face that spawns a shell command. */
-    shellReadBoundarySeat: (() => BashReadonlyRootBoundary | undefined) | undefined;
+    /** borrowed-readonly — this run's shell read station's pre-spawn ADMISSION (declared at the hands phase), for `Monitor`: the only P11 face that spawns a shell command. */
+    shellReadAdmission: ShellReadAdmission | undefined;
     /** borrowed-readonly — the door's second half: the Workflow tool is on the roster. */
     workflowToolsActive: boolean;
     /** borrowed-readonly — the peer lane's mount verdict for this leg. */

package/dist/core/runner/prepare-delegation-surface.js

@@ -56,6 +56,7 @@ export function prepareDelegationSurface(input) {
                 ...(internals?.parentNotify !== undefined
                     ? { uplink: internals.parentNotify, ...(internals.parentPeerRef !== undefined ? { uplinkRecipient: internals.parentPeerRef } : {}) }
                     : {}),
+                ...(internals?.uplinkSessionId !== undefined ? { uplinkSessionId: internals.uplinkSessionId } : {}),
                 ...(internals?.explicitAgentName !== undefined ? { senderName: internals.explicitAgentName } : {}),
                 ...(internals?.parentRetainLedger !== undefined ? { siblingRetain: internals.parentRetainLedger } : {}),
                 ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
@@ -103,7 +104,7 @@ export function prepareDelegationSurface(input) {
         envHandToolNames.add("Monitor");
         roster.mount(firstPartyOffload(createMonitorTool(executionEnv, {
             registry: defaultTaskRegistry,
-            ...(input.shellReadBoundarySeat !== undefined ? { readBoundary: input.shellReadBoundarySeat } : {}),
+            ...(input.shellReadAdmission !== undefined ? { shellReadAdmission: input.shellReadAdmission } : {}),
             owner: hostTaskId,
             scope: taskScope,
             ...(sessionId !== undefined ? { sessionId } : {}),

package/dist/core/runner/prepare-gate-stations.d.ts

@@ -31,6 +31,7 @@ import type { ToolPolicy } from "../tool-policy.js";
 import { type GateOutcome } from "../gate-outcome.js";
 import type { RunnerDeps, TaskSpec, ToolEffect } from "../types.js";
 import type { WriteProtectionCheck } from "../write-protect.js";
+import type { ShellReadCheck } from "../../tools/fs/shell-read-check.js";
 import type { CwdRef } from "../../tools/fs/fs-shared.js";
 import type { AskLane, IrreversibilityTier, ParkAsk, Prepared, ReversibilityProbes } from "./contracts.js";
 import type { StopForDenialLimit } from "./denial-limit-arms.js";
@@ -153,6 +154,9 @@ export interface PrepareGateStationsInput {
      *  emptied the table: no judge, and no tighten mounted at all. Carried rather than compiled a second time
      *  here — two compiles are two judges, free to disagree about the seats they were handed. */
     writeProtectionCheck: WriteProtectionCheck | undefined;
+    /** borrowed-readonly — the leg's shell READ STATION (`ToolGateInput.shellReadCheck`), mounted by the hands phase, or
+     *  undefined with no real shell: no station, nothing judged. */
+    shellReadCheck: ShellReadCheck | undefined;
     /** borrowed-readonly — the per-tool irreversibility tier handed to the gate per call. */
     irreversibilityTier: IrreversibilityTier;
     /** borrowed-readonly — the per-tool reversibility probes handed to the gate per call. */