@sema-agent/core 7.54.1 → 7.55.0

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

@@ -9,6 +9,7 @@
  */
 import { type AskClass, type AskOrigin, type AssertAllKeysHandled, type ModeReleaseReason, type PermissionMode, type PersistedRuleMandate } from "./ask-origin.js";
 import { type AutoModeClassifierRound, type AutoModeFallbackCause } from "./auto-mode.js";
+import { type AllowRuleClearance } from "./allow-rule-shadow.js";
 /**
  * How the wait an ask was in ENDED — the closed set. One word per way a wait can end; the `who` on the
  * record says which party ended it and is fixed BY the word (see {@link Settlement}).
@@ -302,9 +303,9 @@ export type VetoTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedBy
  * deny came through the classifier station. The classifier ends a round three ways, and until this
  * member the wire carried the three as one layer word plus prose:
  *  - `unavailable` — the classifier could not run (the model leg threw / rejected / ran past the cap):
- *    a fail-closed refusal that SAYS SO — the call may simply be retried later (CC 2.1.250 `x1t`);
+ *    a fail-closed refusal that SAYS SO — the call may simply be retried later;
  *  - `parse_error` — the classifier answered outside its verdict contract: blocked for safety, counted by
- *    the denial limit like a ruling (CC 2.1.250 `Ure`);
+ *    the denial limit like a ruling;
  *  - ABSENT beside `deniedBy: "classifier"` — the classifier's own RULING (a `<block>yes` verdict).
  * The WHY behind an `unavailable` (error vs timeout) is not a branching fact: the deny sentence spells it
  * and the `auto_mode.classified` trace frame carries it (`cause: "error" | "timeout"`).
@@ -350,11 +351,19 @@ export type CauseTableCoversEveryDeniedBy = AssertAllKeysHandled<Exclude<DeniedB
  *  candidate ladder and can name no model (a hand-built decider; a parked ancestor's cross-process rebuild,
  *  whose single fresh leg has none); or one did not rule (it could not run, or replied with no verdict) and
  *  handed the question to the approval seat, whose settlement then names the resolution that ask reached.
- *  Additive. Invariant I6 ({@link screenGateOutcome}) screens its shape. */
+ *  Additive. Invariant I6 ({@link screenGateOutcome}) screens its shape.
+ *
+ *  `clearedBy` — the allow layer's account of a call it let run without asking: which member's allow rule cleared the ask
+ *  (`hook` / `deployment` / `persisted` / `skill` / `request`) and the entries it stood on, sanitized and capped as a shadow
+ *  record is, with `positions` for a list member (the indices of those entries in the list the run received — a host maps them
+ *  onto the declaration it sent for this run). Present exactly when an allow member cleared a standing ask and nobody answered
+ *  it: absent on a call nothing asked about, a mode's release or acceptance, the read-only arm's, the classifier's or the
+ *  sandbox's allow, and a person's yes. Additive. Invariant I9 ({@link screenGateOutcome}) screens its shape. */
 export type GateDisposition = {
     kind: "allowed";
     classifier?: AutoModeClassifierRound;
     released?: ModeRelease;
+    clearedBy?: AllowRuleClearance;
 } | {
     kind: "denied";
     deniedBy: DeniedBy;
@@ -415,7 +424,11 @@ export interface ModeRefusal {
  *      record outlives the policy of its day), every member of `classes` is an ask class, `origin` / `mandate` / `reason`,
  *      when present, are members of their closed sets, and `reason` names a member of `classes` (the mint takes it from
  *      that set) — a mode releases nothing a person answered;
- *  I8  `deniedBy === "mode"` ⇔ `mode` present (`bypassPermissions` | `dontAsk`) with `askClass` and `classes`.
+ *  I8  `deniedBy === "mode"` ⇔ `mode` present (`bypassPermissions` | `dontAsk`) with `askClass` and `classes`;
+ *  I9  `disposition.clearedBy` present ⇒ `kind === "allowed"`, no settlement and no release (an allow member cleared the ask
+ *      before anyone answered it), `member` one of the allow layer's members, `entries` a list of strings, `omitted` a positive
+ *      whole number when present, and `positions` — only on a list member (`request`, `deployment`) — a list of non-negative
+ *      whole numbers.
  * Nothing here is read out of an ABSENCE: an ordinary allow with no ask is `{ disposition: { kind: "allowed" } }`,
  * a direct policy deny is `{ disposition: { kind: "denied", deniedBy: "policy" } }`, and neither carries a
  * settlement because neither settled one.

package/dist/core/gate-outcome.js

@@ -1,5 +1,6 @@
 import { isAskClass, isAskOrigin, isModeReleaseReason, isPermissionMode, isPersistedRuleMandate, ASK_FACES, releasableAskClassesFor } from "./ask-origin.js";
 import { isAutoModeFallbackCause } from "./auto-mode.js";
+import { ALLOW_RULE_MEMBERS } from "./allow-rule-shadow.js";
 export const SETTLEMENT_KINDS = Object.freeze([
     "human_allowed",
     "human_refused",
@@ -153,6 +154,31 @@ export function releasePolicyDefects(g) {
     const held = [askClass, ...classes];
     return ASK_FACES.some((face) => held.every((c) => releasableAskClassesFor(face).includes(c))) ? [] : [`I7: released.classes ${JSON.stringify(classes)} is not a set one face of this engine's table releases`];
 }
+const LIST_MEMBERS = new Set(["request", "deployment"]);
+const ALLOW_MEMBER_SET = new Set(ALLOW_RULE_MEMBERS);
+function clearanceDefects(v, settled, released) {
+    const c = objectOf(v);
+    if (c === undefined)
+        return [`I9: disposition.clearedBy is not an object (${shapeOf(v)})`];
+    const out = [];
+    if (settled)
+        out.push("I9: a clearance carries no settlement — an allow rule cleared the ask before anyone answered it");
+    if (released)
+        out.push("I9: a clearance stands beside no mode release — the ask it cleared never reached the mode");
+    if (!ALLOW_MEMBER_SET.has(c.member))
+        out.push(`I9: clearedBy.member ${spelled(c.member)} is not one of the allow layer's members (${ALLOW_RULE_MEMBERS.join(", ")})`);
+    if (!Array.isArray(c.entries) || !c.entries.every((e) => typeof e === "string"))
+        out.push("I9: clearedBy.entries must be a list of strings");
+    if (c.omitted !== undefined && !(typeof c.omitted === "number" && Number.isInteger(c.omitted) && c.omitted > 0))
+        out.push(`I9: clearedBy.omitted ${spelled(c.omitted)} is not a positive whole number`);
+    if (c.positions !== undefined) {
+        if (!LIST_MEMBERS.has(c.member))
+            out.push(`I9: clearedBy.positions stands only on a list member (request, deployment), not ${spelled(c.member)}`);
+        if (!Array.isArray(c.positions) || !c.positions.every((p) => typeof p === "number" && Number.isInteger(p) && p >= 0))
+            out.push("I9: clearedBy.positions must be a list of non-negative whole numbers");
+    }
+    return out;
+}
 const DENY_ONLY_MEMBERS = Object.freeze(["deniedBy", "cause", "mode", "askClass", "classes"]);
 function objectOf(v) {
     return typeof v === "object" && v !== null && !Array.isArray(v) ? v : undefined;
@@ -252,6 +278,10 @@ export function screenGateOutcome(g, opts) {
                 defects.push(`I7: released.reason "${String(r.reason)}" is not a member of released.classes`);
         }
     }
+    if (denied !== undefined && denied.clearedBy !== undefined)
+        defects.push("I9: disposition.clearedBy stands only on an allowed disposition");
+    if (d !== undefined && d.clearedBy !== undefined)
+        defects.push(...clearanceDefects(d.clearedBy, settled, d.released !== undefined));
     if (denied !== undefined) {
         const modeRefusal = denied.deniedBy === "mode";
         if (modeRefusal !== (denied.mode !== undefined))

package/dist/core/governance-codes.d.ts

@@ -1,7 +1,13 @@
 import type { AssertAllKeysHandled } from "./ask-origin.js";
-/** Retry class of a governance code: `transient` = a later retry can self-heal (control-plane
- *  absence/outage); `terminal` = policy adjudicated, re-issuing changes nothing. */
+/** The engine's one retry vocabulary, defined here and nowhere else — can repeating the same request succeed?
+ *  `transient` = a later retry can succeed with nothing changed first (the cause clears by itself, with no stated
+ *  horizon: a control plane briefly absent, contention, an interrupted call); `terminal` = repeating it changes
+ *  nothing until something named changes first — a verdict (a policy, or a usage window until the `retryAfterMs` it
+ *  states), the deployment, the store or the input. Governance codes and file-history faults answer in it. */
 export type GovernanceRetryClass = "transient" | "terminal";
+/** Is `value` one of the two words — the one membership reading (keyed by the type: a word added there is a missing
+ *  row here, at compile time). */
+export declare function isGovernanceRetryClass(value: unknown): value is GovernanceRetryClass;
 /**
  * The closed governance-code registry. tsc forces every entry to a valid class; the gate test
  * forces the naming convention and pack-family completeness. Adding a code = one deliberate row.
@@ -139,7 +145,7 @@ export type NoticeAudience = "user" | "operator";
  * the union's catalog ({@link EngineNotice.code}). The groups below say only which family a row joins,
  * so the catalog is not written a second time here and the two cannot drift.
  */
-export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.read_deny_swapped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.path_view_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "config.credential_not_withheld", "config.cross_boundary_posture_undeclared", "config.cross_boundary_record_unwritten", "config.permission_mode_unavailable", "permission.ask_released_by_mode", "permission.read_deny_unapplied", "permission.rule_store_unavailable", "permission.rule_row_dropped", "config.session_rules_earlier_grammar", "permission.allowed_tool_not_granted", "mods.registration_refused", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "classifier.unavailable", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.credential_origin_mismatch", "route.response_model_mismatch", "route.tool_call_id_folded", "route.finish_reason_unknown", "route.stream_end_ignored", "route.extra_body_reserved_dropped", "context.tool_turn_repaired", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "task.tool_turn_incomplete", "approval.read_root_granted", "approval.read_root_grant_rejected", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed", "tool_result.media_refused", "instructions.source_changed", "session.records_skipped", "memory.layer_locked_legacy", "server.model_unreachable", "permission.entry_mode_clamped"];
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.read_deny_swapped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.path_view_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "config.credential_not_withheld", "config.cross_boundary_posture_undeclared", "config.cross_boundary_record_unwritten", "config.permission_mode_unavailable", "permission.ask_released_by_mode", "permission.read_deny_unapplied", "permission.rule_store_unavailable", "permission.rule_row_dropped", "config.session_rules_earlier_grammar", "permission.allowed_tool_not_granted", "mods.registration_refused", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "classifier.unavailable", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.seat_detached", "advisor.not_attached", "route.credential_origin_mismatch", "route.response_model_mismatch", "route.tool_call_id_folded", "route.finish_reason_unknown", "route.stream_end_ignored", "route.extra_body_reserved_dropped", "context.tool_turn_repaired", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "task.tool_turn_incomplete", "approval.read_root_granted", "approval.read_root_grant_rejected", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed", "tool_result.media_refused", "instructions.source_changed", "session.records_skipped", "memory.layer_locked_legacy", "server.model_unreachable", "permission.entry_mode_clamped"];
 /** A catalogued code (see {@link ENGINE_NOTICE_CODES}); {@link NOTICE_MINTER} says who mints it. NOT the type of
  *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
  *  sink is a supported shape, and narrowing that field would break it. */
@@ -242,6 +248,8 @@ declare const NOTICE_AUDIENCE_TABLE: {
     readonly "memory.project_scope_absent": "operator";
     readonly "route.fallback_to_primary": "operator";
     readonly "route.classifier_unroutable": "operator";
+    readonly "route.seat_detached": "operator";
+    readonly "advisor.not_attached": "user";
     readonly "route.response_model_mismatch": "operator";
     readonly "route.tool_call_id_folded": "operator";
     readonly "route.extra_body_reserved_dropped": "operator";
@@ -351,6 +359,8 @@ declare const NOTICE_MINTER_TABLE: {
     readonly "memory.project_scope_absent": "engine";
     readonly "route.fallback_to_primary": "engine";
     readonly "route.classifier_unroutable": "engine";
+    readonly "route.seat_detached": "engine";
+    readonly "advisor.not_attached": "engine";
     readonly "route.credential_origin_mismatch": "engine";
     readonly "route.response_model_mismatch": "engine";
     readonly "route.tool_call_id_folded": "engine";

package/dist/core/governance-codes.js

@@ -1,3 +1,7 @@
+const RETRY_CLASS_WORDS = Object.freeze({ transient: true, terminal: true });
+export function isGovernanceRetryClass(value) {
+    return typeof value === "string" && Object.hasOwn(RETRY_CLASS_WORDS, value);
+}
 export const GOVERNANCE_CODES = {
     "usage.window_exhausted": "terminal",
     "memory.admission_required": "transient",
@@ -189,6 +193,8 @@ export const ENGINE_NOTICE_CODES = Object.freeze([
     "memory.project_scope_absent",
     "route.fallback_to_primary",
     "route.classifier_unroutable",
+    "route.seat_detached",
+    "advisor.not_attached",
     "route.credential_origin_mismatch",
     "route.response_model_mismatch",
     "route.tool_call_id_folded",
@@ -303,6 +309,8 @@ const NOTICE_AUDIENCE_TABLE = {
     "memory.project_scope_absent": "operator",
     "route.fallback_to_primary": "operator",
     "route.classifier_unroutable": "operator",
+    "route.seat_detached": "operator",
+    "advisor.not_attached": "user",
     "route.response_model_mismatch": "operator",
     "route.tool_call_id_folded": "operator",
     "route.extra_body_reserved_dropped": "operator",
@@ -393,6 +401,8 @@ const NOTICE_MINTER_TABLE = {
     "memory.project_scope_absent": "engine",
     "route.fallback_to_primary": "engine",
     "route.classifier_unroutable": "engine",
+    "route.seat_detached": "engine",
+    "advisor.not_attached": "engine",
     "route.credential_origin_mismatch": "engine",
     "route.response_model_mismatch": "engine",
     "route.tool_call_id_folded": "engine",

package/dist/core/hands-band.d.ts

@@ -110,7 +110,7 @@ export interface HandsBandOptions {
     /** Deployment write gate — COMPOSED with (never replacing) the engine's MemoryEngine write-scan gate:
      *  this hook judges first (a rejection short-circuits), the engine gate then still runs in full. */
     beforeWrite?: BeforeWriteHook;
-    /** RB-198 F1 (CC 220 `Zry`/`WZi.#m` parity): on a foreground Bash command's OWN timeout, an eligible
+    /** RB-198 F1: on a foreground Bash command's OWN timeout, an eligible
      *  command (see `canAutoBackground` — no `git` anywhere in the command, not a `sleep`-first-word wait) is
      *  adopted as a background task instead of being killed — CC's own posture ("received no response for
      *  Nms" would otherwise force a wasteful blind re-run of a non-idempotent long command). Default `false`

package/dist/core/hooks.d.ts

@@ -295,7 +295,7 @@ export interface StopHookResult {
      * more turn.
      *
      * **It DOES count toward the consecutive-block cap, and it never resets it.** This sentence used to
-     * say the opposite ("the cap is driven by `block` alone", cited to CC 2.1.201), and it was wrong on
+     * say the opposite ("the cap is driven by `block` alone"), and it was wrong on
      * both halves. Re-read against CC: the `additionalContext` branch pushes into the SAME array as the
      * blocking-error branch, the loop counts that array's length against the cap, and CC never resets
      * mid-run. The engine was fixed to match; the sentence here was not, so the module that DEFINES this
@@ -971,7 +971,7 @@ export interface ToolGateInput extends PermissionSeatInputs, SkillGateSeats, All
      */
     shellGated?: boolean;
     /**
-     * design/276 (CC 2.1.233 P11 arm 4): true when the called tool is the peer-message verb — a message
+     * design/276 (P11 arm 4): true when the called tool is the peer-message verb — a message
      * to another agent (`SendMessage`). ENGINE-FILLED from the wire name at the caller, never a
      * configuration knob; a caller's same-named shadow tool is keyed too (for a tighten, over-asking is
      * the fail-safe direction). Under an armed {@link autoMode} the gate tightens a surviving `allow` to
@@ -1009,7 +1009,7 @@ export interface ToolGateInput extends PermissionSeatInputs, SkillGateSeats, All
      */
     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
+     * design/143 批2 (A, auto mode): when present, a surviving `ask` is routed to the
      * small-model policy CLASSIFIER before any human/durable resolution:
      *  - verdict `allow` → the ask resolves to allow (`decisionReason:"classifier"`) — no suspend, no onAsk;
      *  - verdict `block` → deny (`decisionReason:"classifier"`, `source:"classifier"`; CC `automode-blocked`); `parse_error` too;
@@ -1033,7 +1033,7 @@ export interface ToolGateInput extends PermissionSeatInputs, SkillGateSeats, All
     autoMode?: {
         decider: import("./auto-mode.js").AutoModeDecider;
         /**
-         * The per-run DENIAL-LIMIT tracker beside the decider (CC 2.1.250 `FO`/`Wie`; same owner,
+         * The per-run DENIAL-LIMIT tracker beside the decider (same owner,
          * same lifetime). Absent ⇒ the pre-#548 chain byte for byte: every block is a deny, without bound.
          * Present ⇒ a block first counts, then judges; the block that reaches a bound becomes the fallback
          * ask (`requiresRealApproval: true` + `denialLimitFallback`), and a classifier allow or a person's

package/dist/core/host-target.d.ts

@@ -0,0 +1,49 @@
+/**
+ * The HOST vocabulary, one home for how a host is spelled and read:
+ *  · {@link hostOfSpelling} — the RULE side: the host a `<Tool>(domain:<host>)` rule names;
+ *  · {@link hostOfUrl} — the CALL side: the host a URL names, which every host-rule judge reads as the call's subject and the
+ *    engine's fetch tool reads as the host it connects to (one reading, two readers);
+ *  · {@link callHostTargetOf} — which argument of a call carries that URL: the host face's protective and declared readings.
+ * Both sides go through the URL parser (lower case, IDN in its ASCII form, a full-width dot folded, an IPv4 shorthand expanded)
+ * and read trailing dots off; a call's host that does not read back as itself through the rule side's reader names no host a rule
+ * can be judged on, so a rule and a call that name one host always name it in one spelling.
+ *
+ * Leaf module: it reads the catalog's host slots (the protective floor) and the name-reading seat, nothing else.
+ */
+import { type ToolCallLike } from "./tool-registry.js";
+/** The host a spelling names as the URL parser reads it (trailing dots read off), or undefined when the spelling is more or
+ *  less than a host: empty, carrying whitespace or a separator a URL reads as something else, a port (a `:` outside an
+ *  address's brackets), credentials, a path. */
+export declare function hostOfSpelling(spelled: string): string | undefined;
+/** Is this host (as {@link hostOfUrl} reads it) an address — the URL parser's IPv4 form or a bracketed IPv6? */
+export declare function isAddressHost(host: string): boolean;
+/** Why a URL names no host a rule can be judged on — the closed set the fetch tool maps to its own refusal sentences:
+ *  not a string; not a URL; not http(s); credentials in it; a host that does not read back as itself once its trailing dots
+ *  are read off (`https://2130706433../` — the parser keeps the name, the rule side reads `127.0.0.1`). */
+export declare const HOST_UNREADABLE_REASONS: readonly ["not_text", "not_url", "not_http", "credentials", "unstable"];
+export type HostUnreadableReason = (typeof HOST_UNREADABLE_REASONS)[number];
+/** The host a URL names, or why it names none. */
+export type HostReading = {
+    readonly host: string;
+} | {
+    readonly unreadable: HostUnreadableReason;
+};
+/** The words a refusal states for each unreadable reason. */
+export declare const HOST_UNREADABLE_SENTENCE: Readonly<Record<HostUnreadableReason, string>>;
+/** THE call-side reading of a URL: the host it names (lower case, IDN in its ASCII form, trailing dots read off), or why it
+ *  names none ({@link HostUnreadableReason}). */
+export declare function hostOfUrl(value: unknown): HostReading;
+/** Which reading a judge takes: `tighten` for a deny, an ask and the unreadable law; `grant` for an allow. */
+export type HostReadingDirection = "tighten" | "grant";
+/**
+ * The host a call reaches as every host-rule judge reads it — the rule policy's host lane, a person's stored rows, the entry
+ * lists, the approval card's offer — or undefined when the call has no URL slot in that direction:
+ *  · `tighten` — the PROTECTIVE reading: the call face's own slot, else the catalog's slot under the first name the call
+ *    answers to that declares one (a bare request, or a face that declares none). Borrowing a slot can only add a host to
+ *    judge, so a deny or an ask keeps reaching a same-name tool;
+ *  · `grant` — the DECLARED reading: the call face's own slot only. A tool that declares none (a caller's tool that merely took
+ *    the fetch tool's name, a bare request) is not the tool the catalog describes, and no allow by host reaches it.
+ * The slot's value is read by {@link hostOfUrl}; a value that names no host answers `{ unreadable }`, and each judge's law
+ * says what that means for its direction.
+ */
+export declare function callHostTargetOf(call: ToolCallLike, direction: HostReadingDirection): HostReading | undefined;

package/dist/core/host-target.js

@@ -0,0 +1,59 @@
+import { hostTargetOf } from "./tool-registry.js";
+import { seatOf } from "./tool-name-readings.js";
+export function hostOfSpelling(spelled) {
+    if (spelled === "" || /[\s/\\@?#%]/.test(spelled) || (spelled.includes(":") && !/^\[[^\]]+\]$/.test(spelled)))
+        return undefined;
+    let url;
+    try {
+        url = new URL(`https://${spelled}/`);
+    }
+    catch {
+        return undefined;
+    }
+    if (url.port !== "" || url.username !== "" || url.password !== "" || url.pathname !== "/" || url.search !== "" || url.hash !== "")
+        return undefined;
+    const host = url.hostname.replace(/\.+$/, "");
+    return host === "" ? undefined : host;
+}
+export function isAddressHost(host) {
+    return host.startsWith("[") || /^\d+\.\d+\.\d+\.\d+$/.test(host);
+}
+export const HOST_UNREADABLE_REASONS = Object.freeze(["not_text", "not_url", "not_http", "credentials", "unstable"]);
+export const HOST_UNREADABLE_SENTENCE = Object.freeze({
+    not_text: "the URL argument is not a string",
+    not_url: "the URL does not parse",
+    not_http: "the URL is not http(s)",
+    credentials: "the URL carries credentials",
+    unstable: "the URL's host does not read back as one host",
+});
+export function hostOfUrl(value) {
+    if (typeof value !== "string")
+        return { unreadable: "not_text" };
+    let url;
+    try {
+        url = new URL(value);
+    }
+    catch {
+        return { unreadable: "not_url" };
+    }
+    if (url.protocol !== "http:" && url.protocol !== "https:")
+        return { unreadable: "not_http" };
+    if (url.username !== "" || url.password !== "")
+        return { unreadable: "credentials" };
+    const host = url.hostname.replace(/\.+$/, "");
+    return host !== "" && hostOfSpelling(host) === host ? { host } : { unreadable: "unstable" };
+}
+export function callHostTargetOf(call, direction) {
+    const slot = hostSlotOf(call, direction);
+    if (slot === undefined)
+        return undefined;
+    const args = call.args;
+    const own = typeof args === "object" && args !== null && !Array.isArray(args) && Object.hasOwn(args, slot.param);
+    return hostOfUrl(own ? args[slot.param] : undefined);
+}
+function hostSlotOf(call, direction) {
+    const declared = call.face?.hostTarget;
+    if (declared !== undefined || direction === "grant")
+        return declared;
+    return seatOf("floor.protectiveHostTarget", { get: hostTargetOf }, call)?.value;
+}

package/dist/core/image-downsample.d.ts

@@ -7,7 +7,7 @@
  * `core/types.ts`) needed no changes on this car.
  */
 /**
- * design/116 W5-1 — the max base64 size of ONE inline image (5MB). Value = CC 2.1.187
+ * design/116 W5-1 — the max base64 size of ONE inline image (5MB). Value =
  * `API_IMAGE_MAX_BASE64_SIZE` (constants/apiLimits.ts:22, "5 * 1024 * 1024 // 5 MB" — the hard Anthropic API
  * limit on a base64 image block; CC resizes/compresses down to fit UNDER it, imageResizer.ts). An MCP server
  * returning a bigger image previously passed straight through = a context/API bomb.

package/dist/core/lsp-diagnostics.d.ts

@@ -83,7 +83,7 @@ export declare class LspDiagnosticsRegistry {
  *  the map; a judgment that fails withholds them all). The run's drain already marked them delivered, so they do not come back. */
 export declare function withholdListedDiagnostics(files: LspFileDiagnostics[], withheldOf: (uris: readonly string[]) => Promise<ReadonlyMap<string, unknown>>): Promise<LspFileDiagnostics[]>;
 /**
- * CC 198 `formatDiagnosticsSummary` (198:320480-320499), verbatim shape:
+ * `formatDiagnosticsSummary` shape:
  * ```
  * {basename}:
  *   {symbol} [Line {line+1}:{col+1}] {message}[ [{code}]][ ({source})]
@@ -96,16 +96,16 @@ export declare function withholdListedDiagnostics(files: LspFileDiagnostics[], w
  * repository. They land inside the `<new-diagnostics>` envelope, and (since this block is now
  * delivered inside a marked reminder shell) inside an authority-marked reminder too, so a diagnostic
  * message carrying `</new-diagnostics>` closed the envelope and placed server text at the top level
- * of engine-authored authority. CC 223 does not neutralize here either — a deliberate, disclosed
+ * of engine-authored authority. The reference does not neutralize here either — a deliberate, disclosed
  * hardening divergence: CC ships the same block inside the same reminder shell, so the hole exists on
  * both sides and only the fix is ours. Neutralization runs BEFORE the join, so the 4000-char cap
  * still bounds the FINAL text and can never cut inside a neutralized marker's own bytes.
  */
 export declare function formatDiagnosticsSummary(files: LspFileDiagnostics[]): string;
-/** CC 198 model-facing injection block (198:320500-320503), verbatim framing.
+/** Model-facing injection block.
  *
  *  DELIVERY (design/319 sibling work): the runner shells this block in a MARKED `<system-reminder>`
- *  before steering it — CC 223 `case "diagnostics"` does the same (`ih([Vr({content: …})])` → the
+ *  before steering it — the reference's `case "diagnostics"` does the same (`ih([Vr({content: …})])` → the
  *  reminder wrap), and until that was matched this was the engine's only authority text reaching the
  *  model as a bare block with no provenance mark at all. The block's own bytes are unchanged; the
  *  shell is applied at the delivery site (runtask), not baked in here, so this exported renderer keeps

package/dist/core/lsp.d.ts

@@ -58,8 +58,8 @@ export interface LspSymbolInfo {
  * answered null/[] — today's behavior byte-for-byte, and what an external manager returning bare
  * `{kind:"none"}` keeps getting). The failure reasons exist because one literal "No results." used to cover
  * both real emptiness and every transport-level fault — a findReferences that TIMED OUT read as "no
- * references, safe to delete" (CC 2.1.220 keeps these apart: `Error performing ${operation}: ...` vs the
- * plain empty-result strings, (pretty220.js:474840, historical; not relocated in 250 — see cc-250 anchors)).
+ * references, safe to delete" (the reference keeps these apart: `Error performing ${operation}: ...` vs the
+ * plain empty-result strings).
  */
 export type LspNoneReason = "unsupported_operation" | "server_error" | "timeout" | "cancelled" | "server_terminated" | "no_call_hierarchy_item"
 /** HRD-LSP-7: the QUERIED file could not be read for the didOpen/didChange re-sync (deleted between the
@@ -246,7 +246,7 @@ export interface LspTransport {
  *  gate (no read face) only; a gated read is the admitted held object's ({@link LspReadAdmission}). TOC = local fs; TOB =
  *  the sandbox ExecutionEnv. */
 export type LspReadText = (filePath: string, signal?: AbortSignal) => Promise<string>;
-/** CC 2.1.220's LSP file cap (10MB — `File too large for LSP analysis`, (pretty220.js:474745, historical; not relocated in 250 — see cc-250 anchors)). Single-sourced
+/** The LSP file cap (10MB — `File too large for LSP analysis`). Single-sourced
  *  in core: the TOOL-layer check in {@link createLspTool} (the model-visible enforcement, CC-parity) and the
  *  defense-in-depth throw in the engine's `defaultLspReadText` must agree on one number. */
 export declare const MAX_LSP_FILE_BYTES: number;

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

@@ -221,6 +221,10 @@ export interface MailboxStore {
      *  (the in-memory reference); absent = undeclared (the CC inbox adapter). Read by
      *  {@link mailboxCrossProcessMountVerdict}; any other value is a malformed declaration and refuses. */
     readonly crossProcessSafe?: boolean;
+    /** WHICH boxes this store serves, as an opaque word: two store objects with the same identity read and write
+     *  the same boxes (one backing directory, one database), in whichever process they live. Absent = the store
+     *  cannot say — and then no peer may assume that a box it appends to here is one another session drains. */
+    readonly identity?: string;
     /** Durably park one message. Refuses `"mailbox.recipient_tombstoned"` when the backend can see
      *  that its recipient is in the deployment's pre-delete state (see the interface notes above). */
     append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;

package/dist/core/mcp-connection-pool.d.ts

@@ -18,6 +18,7 @@
  * answer to its questions belongs to the leg that is waiting on it.
  */
 import type { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { ConnectionListing, type LenientListedTool } from "./mcp-server-link.js";
 import type { McpServerSpec } from "./mcp-server-spec.js";
 /** The slice of a listed tool the SDK client caches per connection (its output validator, its task-support flags). */
 export interface McpToolMeta {
@@ -31,6 +32,8 @@ export type McpListingWriter = (tools: ReadonlyArray<McpToolMeta>, apply: (all:
 /** One leg's hold on a pooled connection. */
 export interface McpLease {
     readonly client: Client;
+    /** The connection's listing, one record shared by every holder (mcp-server-link.ts `ConnectionListing`). */
+    readonly listing: ConnectionListing<LenientListedTool>;
     /**
      * Open a `tools/list` round trip on the connection — call it BEFORE the request. The returned writer records the result twice over:
      * as the connection's metadata for each listed tool, at this listing's version (its place in the order listings were opened on the
@@ -65,13 +68,26 @@ export declare class McpConnectionPool {
      * Lease the connection for `key`, dialling it with `dial` when none is live. `fresh` replaces the pool's current connection with a new
      * dial (a re-dial): the connection it replaces lives on until its other holders release it. Resolves `undefined` once the pool is
      * closed — the caller dials for itself. A dial that rejects rejects every waiter of that dial, and the pool keeps nothing of it.
+     *
+     * `signal` is the CALLER's abort, and it is that caller's alone: it ends this caller's wait (rejecting with its reason) and leaves the dial
+     * to the legs still waiting on it. The dial belongs to the pool: it is given a stop of its own, fired when the last leg waiting on it has
+     * walked away, so a leg's abort neither holds nor cancels a dial another leg still needs.
      */
-    acquire(key: string, dial: () => Promise<Client>, opts?: {
+    acquire(key: string, dial: (stop: AbortSignal) => Promise<Client>, opts?: {
         fresh?: boolean;
+        signal?: AbortSignal;
     }): Promise<McpLease | undefined>;
+    /**
+     * Wait for a dial as one of its legs; this leg's abort ends only this leg's wait. The last leg to walk away abandons the dial in the
+     * same step as its abort (see {@link abandon}) — the table holds only dials some leg still waits on, so a leg that asks next dials afresh
+     * instead of joining a stopped dial and failing with another leg's abort.
+     */
+    private waitOn;
+    /** A dial nobody waits on any more: out of the table and stopped, and — had it landed already — the connection nobody leased is let go, so such a dial leaves no connection behind. */
+    private abandon;
     /** Make the next lease of `key` dial a new connection. */
     detach(key: string): void;
-    /** No lease is granted after this; the connections still held stay open until their holders release them. */
+    /** No lease is granted after this; the connections still held stay open until their holders release them — one nobody holds is closed now. */
     close(): void;
     /** How many connections the pool holds open right now (for the lifecycle pins). */
     get live(): number;

package/dist/core/mcp-connection-pool.js

@@ -1,4 +1,5 @@
 import { canonicalize } from "./canonical-json.js";
+import { ConnectionListing } from "./mcp-server-link.js";
 export class McpConnectionPool {
     entries = new Map();
     dialing = new Map();
@@ -17,25 +18,67 @@ export class McpConnectionPool {
     async acquire(key, dial, opts) {
         if (this.shut)
             return undefined;
+        opts?.signal?.throwIfAborted();
         if (opts?.fresh === true)
             this.detach(key);
         let entry = this.entries.get(key);
         if (entry === undefined || entry.closed) {
             let pending = this.dialing.get(key);
             if (pending === undefined) {
-                const started = this.dialNew(key, this.generation.get(key) ?? 0, dial);
-                pending = started;
-                this.dialing.set(key, started);
+                const stop = new AbortController();
+                const started = this.dialNew(key, this.generation.get(key) ?? 0, () => dial(stop.signal));
+                const own = { promise: started, waiters: 0, stop };
+                pending = own;
+                this.dialing.set(key, own);
                 const settled = () => {
-                    if (this.dialing.get(key) === started)
+                    if (this.dialing.get(key) === own)
                         this.dialing.delete(key);
                 };
                 void started.then(settled, settled);
             }
-            entry = await pending;
+            entry = await this.waitOn(key, pending, opts?.signal);
         }
         return this.lease(entry);
     }
+    async waitOn(key, dial, signal) {
+        dial.waiters++;
+        let waiting = true;
+        const stopWaiting = () => {
+            if (waiting)
+                dial.waiters--;
+            waiting = false;
+        };
+        try {
+            if (signal === undefined)
+                return await dial.promise;
+            return await new Promise((resolve, reject) => {
+                const walkAway = () => {
+                    stopWaiting();
+                    if (dial.waiters === 0)
+                        this.abandon(key, dial, signal.reason);
+                    reject(signal.reason);
+                };
+                signal.addEventListener("abort", walkAway, { once: true });
+                dial.promise.then(resolve, reject).finally(() => signal.removeEventListener("abort", walkAway));
+            });
+        }
+        finally {
+            stopWaiting();
+        }
+    }
+    abandon(key, dial, reason) {
+        if (this.dialing.get(key) === dial)
+            this.dialing.delete(key);
+        dial.stop.abort(reason);
+        dial.promise.then((entry) => {
+            if (entry.refs > 0 || entry.closed)
+                return;
+            entry.current = false;
+            if (this.entries.get(key) === entry)
+                this.entries.delete(key);
+            void entry.client.close().catch(() => undefined);
+        }, () => undefined);
+    }
     detach(key) {
         this.generation.set(key, (this.generation.get(key) ?? 0) + 1);
         const e = this.entries.get(key);
@@ -47,6 +90,9 @@ export class McpConnectionPool {
     }
     close() {
         this.shut = true;
+        for (const e of [...this.entries.values()])
+            if (e.refs === 0 && !e.closed)
+                void e.client.close().catch(() => undefined);
     }
     get live() {
         let n = 0;
@@ -57,7 +103,7 @@ export class McpConnectionPool {
     }
     async dialNew(key, generation, dial) {
         const client = await dial();
-        const entry = { client, refs: 0, listeners: new Set(), holders: new Map(), meta: new Map(), nextVersion: 0, current: true, closed: false };
+        const entry = { client, listing: new ConnectionListing(), refs: 0, listeners: new Set(), holders: new Map(), meta: new Map(), nextVersion: 0, current: true, closed: false };
         client.onclose = () => {
             entry.closed = true;
             if (this.entries.get(key) === entry)
@@ -86,6 +132,7 @@ export class McpConnectionPool {
         };
         const lease = {
             client: entry.client,
+            listing: entry.listing,
             onClose: (fn) => {
                 mine.add(fn);
                 entry.listeners.add(fn);

package/dist/core/mcp-failure.d.ts

@@ -120,14 +120,17 @@ export type McpExchangeOutcome = McpFailureKind | "completed";
  *  mint of the record — no two sites can disagree about the word, about which words may carry
  *  `errorCode`, or about what a completed exchange proves. */
 export declare function livenessOf(outcome: McpExchangeOutcome, observedAt: number): McpServerLiveness | undefined;
+/** A request over an established connection; `session` when the request carried the session id the server issued at the handshake. */
+export type McpRequestSite = {
+    phase: "request";
+    session?: true;
+};
 /** Where the failure was judged: at the dial (connect + initial listing), where an errno on a stdio
  *  transport is the child process failing to spawn, or on a request over an established connection. */
 export type McpFailureSite = {
     phase: "connect";
     transport: "stdio" | "http" | undefined;
-} | {
-    phase: "request";
-};
+} | McpRequestSite;
 /**
  * The one MCP failure record. Both fields are always present; `httpStatus` rides only with
  * `kind === "http_status"`.
@@ -213,4 +216,20 @@ export interface HttpTransportFailure {
     delivered: McpDelivered;
     httpStatus?: number;
 }
-export declare function describeHttpTransportFailure(err: unknown): HttpTransportFailure | undefined;
+export declare function describeHttpTransportFailure(err: unknown, at?: McpRequestSite): HttpTransportFailure | undefined;
+/**
+ * The one reading of a lost session: a request that carried the session id the server issued at the handshake (`at.session`) was
+ * answered 404 by the HTTP endpoint — the protocol's word for a session it no longer knows (a restart, a reaped session). It is the
+ * server's REPORT, not a proof that nothing ran: the call lane sends the request again once on a fresh session, and every face that
+ * renders the failure names it ({@link LOST_SESSION}), while its record stays the table's (`http_status`, `delivered: "unknown"`) — a
+ * server that executed the request and then answered 404 ran it. Read from the thrown value's structure and the site, never from the
+ * body's text. Nothing else qualifies: a 5xx, a timeout or a lost pipe leave the outcome unknown, a protocol error or a tool's own error
+ * means the server processed the call, a 400 is the protocol's word for a request that lacked its session header (a server that answers
+ * an unknown session 400 with words saying so is not read by its words), and a 404 on a connection that holds no session id is an
+ * endpoint answering, not a session ending.
+ */
+export declare function sessionGone(err: unknown, at: McpFailureSite): boolean;
+/** What every face says of a lost session ({@link sessionGone}). */
+export declare const LOST_SESSION = "the server reported the session the request was sent on gone (its HTTP endpoint answered 404 to the session id it issued)";
+/** A failure's text, with a lost session ({@link sessionGone}) named ahead of it — for a face that renders the failure as one line. */
+export declare function namingLostSession(err: unknown, at: McpRequestSite, text: string): string;