@sema-agent/core 7.18.0 → 7.20.0

package/dist/core/engine-notice.d.ts

@@ -10,38 +10,62 @@ export interface EngineNotice {
      *    `autoCompactTokens` ABOVE its physical window; the trigger-side geometry was clamped to the
      *    physical window (an autocompact window only ever lowers the trigger) and the bad value is
      *    announced once per prepared task; `detail: { modelId, declaredAutoCompactTokens,
-     *    physicalWindow, sessionId, runId }` — `runId` (#499) is what makes the "once per prepared
-     *    task" claim checkable: the session id beside it is shared by every run of the session, so two
-     *    runs clamping the same model used to mint byte-identical lines.
+     *    physicalWindow, sessionId, runId }` — `runId` is what makes the "once per prepared task" claim
+     *    checkable, the session id beside it being shared by every run of the session.
      *  - `"config.env_timeout_discarded"` — a Bash timeout knob (option or env) held a value that is not
      *    the value in force; `detail: { knob, raw, usedMs }`.
      *  - `"config.materialize_env_discarded"` — `SEMA_TOOL_MATERIALIZE_STRATEGY` held a value outside the
      *    closed set in a seat where it is not in force; `detail: { raw, specStrategy? }`.
+     *  - `"config.task_root_not_canonical"` (#759) — the task root this run was handed is not its own
+     *    canonical path (a symlinked directory; `/var` → `/private/var` on macOS). Containment is judged
+     *    on the CANONICAL spelling, so the deployment and the engine reason about two different
+     *    directories: a target the host considers inside the root can be judged outside it. The run is
+     *    unchanged — announce, never narrow, never repair — and the fix is to hand the canonical path in.
+     *    Audience `operator` (a deployment wiring fact). `detail: { given, canonical, sessionId, runId }`
+     *    — both spellings, so a consumer can diff them without guessing which one it holds. Once per
+     *    prepared leg, and never for a root that already is its own canonical form (its absence is the
+     *    claim that the two agree).
      *  - `"config.tool_card_undeclared"` (design/388 L4) — a tool minted a `details.type` card its definition
      *    (or its caller declaration's `renderHints.resultCards`) never declared; the card was dropped from
      *    `tool_end.structured`; once per leg per type; `detail: { type, sessionId, runId }`.
      *  - `"config.tool_face_undeclared"` / `"config.tool_face_invalid"` (design/388 §2.7) — an MCP server's
      *    `toolFaces` overlay names a tool the listing does not carry / does not fit the tool's materialized
      *    schema (the tool mounts bare); once per leg per tool; `detail: { server, tool, problem?, sessionId, runId }`.
+     *  - `"agents.listing_truncated"` — the agent-type roster frame did not fit the same listing budget:
+     *    at least one type is listed name-only (`nameOnly`) or not at all (`dropped`). Audience `operator`.
+     *    `detail: { budgetBytes, total, kept, nameOnly: [name], dropped: [name], sessionId }`; the same
+     *    firing rule as its skills sibling below (once per delivered frame, on the carrying message's receipt).
+     *  - `"skills.listing_truncated"` — the `<skills>` disclosure block did not fit its byte budget, so
+     *    at least one skill is listed without its description (`nameOnly`) or, in the pathological case,
+     *    not listed at all (`dropped`); the `Skill` tool still serves every one of them. Audience
+     *    `operator` — raising `TaskSpec.skillListingBudgetFraction`, lowering `skillListingMaxDescChars`
+     *    or declaring fewer skills are all deployment acts. `detail: { budgetBytes, descMaxChars, total,
+     *    kept, nameOnly: [name], dropped: [name], sessionId }` — `budgetBytes` IS the budget in force;
+     *    no ceiling stands above the declared fraction, so no second number rides beside it.
+     *    Announced on the RECEIPT of the message that carried the frame — the leg's first user message, or
+     *    the boundary steer that a drift (or a resume leg's initial listing) rides — once per delivered
+     *    frame the budget actually degraded, and never for one that fit. Every count is read off that frame, so
+     *    `total` is the whole roster on an initial listing and the newly announced set on a drift frame.
+     *    A run whose deployment turned the listing off (`attachments.skillsListing: false`) emits nothing,
+     *    since nothing is rendered. There is NO dedup key: each notice is one delivered frame`s cost, and
+     *    a frame is delivered (and committed) once.
      *  - `"tool_result.offload_put_failed"` (#167) — a clear-with-offload persist's fire-and-forget put
      *    failed; THIS attempt stored nothing (the failure arm reports, it never re-inserts under the
      *    ref) — an earlier attempt of the same idempotent re-put may already have stored the row, so
      *    the notice claims a failed write, not an empty ref;
-     *    `detail: { ref, sessionId, cause, occurrenceId }`.
-     *    Per-occurrence, not per-process-deduplicated: each failed write is a distinct fact — and
-     *    `occurrenceId` (#495, uuidv7 minted at the failure) is what lets a consumer act on that:
-     *    `ref` names the ROW, and the same ref is attempted again on every later re-clear, so two
-     *    genuine losses of one ref were byte-identical notices. Dedup key: (code, occurrenceId).
+     *    `detail: { ref, sessionId, cause, occurrenceId }`. Per-occurrence, not
+     *    per-process-deduplicated: each failed write is a distinct fact, and `ref` names the ROW rather
+     *    than the attempt, so the uuidv7 `occurrenceId` minted at the failure is what tells two genuine
+     *    losses of one ref apart. Dedup key: (code, occurrenceId).
      *  - `"workflow.governance_key_stripped"` (#235) — the fields of an LLM-authored workflow `agent(spec)`
      *    that did NOT cross the governed default-deny whitelist: an unrecognized/control-plane field, or a
      *    `readFace` value that is not the containment-tightening one. The spawn PROCEEDS on the deployment
      *    baseline (the strip is not a refusal in this window), which is why the drop is announced;
      *    `detail: { total, stripped: [{ key, reason }], omitted?, occurrenceId }`, the rendered key list
      *    bounded in count and length because the names come from the untrusted script. One aggregated
-     *    notice per governed child build, not de-duplicated across builds: each spec is a distinct fact —
-     *    `occurrenceId` (#495, uuidv7 minted at the announcement) carries that claim to the consumer,
-     *    which otherwise saw two builds of the same spec as one repeated notice. Dedup key:
-     *    (code, occurrenceId).
+     *    notice per governed child build, not de-duplicated across builds: each spec is a distinct fact,
+     *    and the uuidv7 `occurrenceId` minted at the announcement is what carries that claim to a consumer
+     *    that would otherwise read two builds of one spec as one repeated notice. Dedup key: (code, occurrenceId).
      *  - `"workflow.agent_option_ignored"` (#505 ①) — the OPTIONS-object twin of the row above: keys of
      *    `agent(spec, opts)`'s SECOND argument that were not applied (unrecognized, or a known option
      *    whose value its type check rejected — `label: 42`). The spawn PROCEEDS without them, which is
@@ -51,6 +75,21 @@ export interface EngineNotice {
      *    key: (code, occurrenceId). NOT the whole family: a SPEC field written on the options object
      *    (`model`, `modelName`, `thinking`, …) is REFUSED at the membrane instead — a silently ignored
      *    `model` runs a different agent than the author asked for.
+     *  - `"config.forward_sink_failed"` — the deployment's opt-in subagent display sink
+     *    (`RunInternals.onForwardEvent`) failed and the frame it was handed was dropped: it threw, or —
+     *    since an `async` function satisfies that `=> void` seat — it returned a promise that rejected.
+     *    The run is untouched (forwarding is a render channel, and delivery is never awaited, so a sink
+     *    that never settles is not a failure and announces nothing). `detail: { site, cause }` — `site` is
+     *    the engine-owned site name the failures are counted under, `cause` the thrown value's message.
+     *    Audience `operator`: the sink is deployment wiring and nobody else can repair it. Dedup unit:
+     *    once per RUN (the counters ride `RunInternals.forwardScope`, which every copy of a run's
+     *    internals carries), later failures of the same run counted only — a sink that fails on every
+     *    frame therefore costs ONE line, not one per frame.
+     *  - `"memory.restore_withheld"` — a memory containment DID NOT write a committed baseline back: another
+     *    writer held the path when the restore reached it, and those newer bytes were left standing.
+     *    Containment is unaffected and the committed copy is still in the store, so reconciling the two is
+     *    the host's act (audience `operator`). `detail: { paths: [{ path, entryId?, rev? }], sessionId? }`,
+     *    `rev` = the declined generation. Dedup unit: once per containment PASS, never per path.
      *  - `"mcp.revocation_probe_failed"` (design/338) — the deployment's `mcpRevocations.isRevoked`
      *    probe threw; MCP dispatch FAILS OPEN (revocation is a tightening face) and this announces
      *    once per materialization (a resume re-materializes and may announce again).
@@ -74,10 +113,9 @@ export interface EngineNotice {
      *    { models, tiers, occurrenceId }` — key COUNTS only, never the catalog itself. In-flight tasks
      *    finish on the models they resolved at prepare (natural snapshot); every later prepare resolves
      *    against the new generation. A failed swap (illegal tier binding, a refused candidate) throws
-     *    atomically and mints nothing.
-     *    `occurrenceId` (#495, uuidv7 minted at the announcement): the verb carries no run and no
-     *    session, and the payload is a pair of counts, so two swaps of the same shape were byte-
-     *    identical lines. Dedup key: (code, occurrenceId).
+     *    atomically and mints nothing. The verb carries no run and no session and the payload is a pair
+     *    of counts, so the uuidv7 `occurrenceId` minted at the announcement is what tells two swaps of the
+     *    same shape apart. Dedup key: (code, occurrenceId).
      *  - `"config.read_face_swapped"` — `Runner.swapDeps` replaced the deployment's read-face
      *    declaration (`RunnerDeps.readFace`, the `readFace` seat of the swappable set) without a
      *    restart. `detail: { from, to, occurrenceId }` — the seat's previous and new value, each
@@ -86,8 +124,7 @@ export interface EngineNotice {
      *    read-only mount) still runs per prepare. In-flight legs keep the face they prepared under;
      *    every later prepare resolves against the new declaration. A candidate outside the value gate
      *    (`assertContainmentFaceValue`) throws atomically and mints nothing. Own `occurrenceId` for the same
-     *    reason as the catalog line (no run, no session, a two-word payload). Dedup key:
-     *    (code, occurrenceId).
+     *    reason as the catalog line (no run, no session, a two-word payload). Dedup key: (code, occurrenceId).
      *  - `"config.write_face_swapped"` — the same line for the WRITE seat (`RunnerDeps.writeFace`),
      *    same payload, same laws. A SEPARATE code rather than a face field on the line above: the audience
      *    table and every consumer table are keyed by code.
@@ -98,10 +135,9 @@ export interface EngineNotice {
      *    `detail: { seat, from, to, cause, fixHint, sessionId?, runId? }` — `cause` is the refusal code
      *    (`route.credential_mismatch` / `route.credential_missing`); `sessionId` (#433, additive)
      *    rides when the adjudicating seat knows its session, and `runId` (#499, additive) names the
-     *    INVOCATION whose seats were being resolved — both correlation keys only, the audience
-     *    stays `"operator"` (see the registry's entitlement-not-routability note). Two runs of one
-     *    session falling back on the same seat used to mint byte-identical lines; `runId` is what
-     *    tells one task falling back twice apart from two tasks falling back once each.
+     *    INVOCATION whose seats were being resolved — both correlation keys only, the audience stays
+     *    `"operator"` (see the registry's entitlement-not-routability note), and `runId` is what tells one
+     *    task falling back twice apart from two tasks falling back once each.
      *    Explicitly-named models never mint this: they refuse at the brain's request gate instead.
      *  - `"route.classifier_unroutable"` (same pre-flight, the other POSTURE) — the derived classifier seat
      *    failed the same pairing pre-flight while the deployment had declared NO fallback
@@ -118,6 +154,20 @@ export interface EngineNotice {
      *    `detail: { from, to, cause, sessionId?, runId? }` — `cause` is the `AutoModeFallbackCause` word, the
      *    two ids are the rungs. Dedup key: (code, from, cause) PER RUN; a second CAUSE on the same rung is
      *    its own line.
+     *  - `"classifier.role_defaulted"` (`src/core/runner/classifier-ladder.ts`, the seat resolver) — no
+     *    `classifier` role names a model, so another model STANDS IN for the seat. `detail: { model, reason,
+     *    thinkingOffSpelled, sessionId?, runId? }` — `reason` ∈ `tier_below_main` (the nearest directly-bound
+     *    tier below the run's main model) / `tier_table` (the static `flash` row, a main bound to no tier) /
+     *    `role_fallback` (the `summarize → default` chain, no tiers) / `main_only` (the main model is the only
+     *    model there is) / `role_unresolvable` (the role named a model the catalog cannot resolve; the main
+     *    stands in); `thinkingOffSpelled` = whether that model's wire can carry a disable key. Minted
+     *    AFTER the route pre-flight, so it names the seat actually used. Once per run.
+     *  - `"classifier.contract_broken"` (same file, the round observer) — ONE model answered
+     *    `AUTO_MODE_CLASSIFIER_CONTRACT_BROKEN_AFTER` CONSECUTIVE classifications without a verdict (each already
+     *    re-asked once by the leg). `detail: { model, rung, consecutive, sessionId?, runId? }` — `rung` is the
+     *    ladder position (0 the seat, 1 the model behind it), since two rungs may share an id. A ruling from
+     *    that rung resets its count; an `unavailable` round neither counts nor resets. Once per run per rung,
+     *    and by construction before the denial limit's third block hands the user its card.
      *  - `"route.base_url_changed_key_unchanged"` (key↔URL pairing) — `Runner.swapDeps` moved a
      *    same-name entry's `baseUrl` while its Model-visible credential half (auth-bearing headers)
      *    did not change: legal (a provider changing domains), but worth one loud line — if the
@@ -125,10 +175,9 @@ export interface EngineNotice {
      *    refusal; per-model-hook credentials are invisible to the catalog swap, so the notice is
      *    deliberately conservative (it may fire when a hook-side credential DID change in lockstep).
      *    One aggregated notice per swap; `detail: { entries: [{ modelId, from, to }], total,
-     *    occurrenceId }` (rendered list bounded, total always exact). `occurrenceId` (#495, uuidv7
-     *    minted at the announcement, independent of the `config.models_swapped` line's own): the
-     *    bounded render makes two swaps moving the same first entries byte-identical.
-     *    Dedup key: (code, occurrenceId).
+     *    occurrenceId }` (rendered list bounded, total always exact); the `occurrenceId` is minted at this
+     *    announcement, independently of the `config.models_swapped` line's own, because the bounded render
+     *    makes two swaps moving the same first entries identical. Dedup key: (code, occurrenceId).
      *  - `"config.read_face_deployment_clamped"` (#237) — a deployment-wide `readFace: "open"` is not
      *    in force beside a read-only (verifier) mount: it clamps to "roots" without throwing
      *    (stricter-wins; the clamp verdict stands, only its occurrence was undisclosed). Announced
@@ -164,14 +213,17 @@ export interface EngineNotice {
      *    threw: the `Artifact` tool is not mounted for the task and this is the loud half (an absent seat
      *    is silent; a broken one must not look the same). Once per prepared leg;
      *    `detail: { problem, sessionId, runId }`.
+     *  - `"config.execution_env_capability_invalid"` — a remote env DECLARES a boolean capability key
+     *    (`isolation`, `suspendable`, `canonicalPathAuthoritative`) with a non-boolean value; ABSENCE is a
+     *    supported reading of each and stays silent. Once per key per run; `detail: { key, valueType }`.
      *  - `"config.durable_gate_unavailable"` — a durable-approval MANDATE is in force on a leg with NO
      *    checkpoint store: the per-principal `forceDurableGate` entitlement, or the task's own
      *    `durableApproval` opt-in with no live approver seat (`durableMandateSourceOf`, the predicate the
      *    leg's children inherit). A mandate with no park facility cannot be honored: no ask of the leg can suspend, so each one resolves on the LIVE
      *    chain — a live approver / question face answers in-stream, and with none the ask is denied
      *    fail-closed — and NO durable approval record is written. The ask routing itself is not
-     *    changed by the notice (a store-less leg never could park); the notice is the loud half of a
-     *    posture that used to degrade silently, disclosed before the first ask of the leg. Audience
+     *    changed by the notice (a store-less leg never could park); the notice is its loud half,
+     *    disclosed before the first ask of the leg. Audience
      *    `"user"` (the person whose asks will not be recorded is entitled to that; the operator hears
      *    it through the sink as always). Once per prepared task leg — a resume or a delegated child
      *    is its own leg and says so again; `detail: { sessionId, runId, principal?, cause, source,
@@ -194,12 +246,10 @@ export interface EngineNotice {
      *    (`sessionId` = #433's routing half for these two `"user"`-audience rows; `runId` = #499's
      *    per-run identity, the key this account is actually about — see
      *    {@link undrainedUserInputNotices}; all omitted when the caller has none, never fabricated).
-     *    Per-run, at most once per family (the terminal sweep is a single site) — which is exactly why
-     *    `taskId`/`sessionId` cannot key it: both answer the same value for two runs of one session,
-     *    so two runs each stranding one steer folded into one indistinguishable row.
-     *    **#389 (two corrections).** ① The family now fires on the INTERRUPT path too: `abort()` used
-     *    to empty both queues before agent_end could count them, so the one loss path an operator most
-     *    needs to hear about was the one path that stayed silent. ② On a DURABLE PARK the verdict is
+     *    Per-run, at most once per family (the terminal sweep is a single site) — which is why
+     *    `taskId`/`sessionId` cannot key it: both answer the same value for two runs of one session.
+     *    ① The family fires on the INTERRUPT path too, `abort()` being barred from emptying either queue
+     *    before agent_end can count it. ② On a DURABLE PARK the verdict is
      *    settled at the run tail instead of at agent_end, because the tail first carries the still-
      *    undelivered input onto the committed checkpoint's parked-steer queue (the resume delivers it)
      *    — what is announced is the remainder that could NOT be carried, so a fully-migrated park says
@@ -230,10 +280,9 @@ export interface EngineNotice {
      *        the other question (was the halt CONSUMED), see that seat.
      *    In both lanes: one notice per REAL cut (a `now` that found nothing in flight or whose frame
      *    already rode the imminent boundary, and a halt with nothing in flight, announce nothing — no
-     *    false interrupt claims); `runId` (#499) is the INVOCATION that was cut (the other two ids are
-     *    shared by every run of the session); every cut turn counts toward `maxTurns`, so an interrupt
-     *    storm's cost is bounded and each of its cuts is on the record. Audience `"user"`: the person
-     *    who forced the boundary is the one entitled to see that it landed.
+     *    false interrupt claims); `runId` is the INVOCATION that was cut; every cut turn counts toward
+     *    `maxTurns`, so an interrupt storm's cost is bounded and each of its cuts is on the record.
+     *    Audience `"user"`: the person who forced the boundary is the one entitled to see that it landed.
      *    RETIRED here (BREAKING, named): `"task.injection_priority_unimplemented"` — the ladder is
      *    implemented, so the unhonored-knob disclosure it carried has no referent; consumers must
      *    judge ladder support by VERSION, never by that code's absence.
@@ -320,9 +369,8 @@ export interface EngineNotice {
      *    the inputId, so "accepted at park, screened at redelivery" is auditable end to end. Audience
      *    `"user"` (the person whose instruction was withheld is the one entitled to re-issue it);
      *    `detail: { inputId?, sessionId, runId, taskId? }` — `inputId` is the parked entry's stored
-     *    correlation key (OPTIONAL: a row parked without one exists), and `runId` (#499) names the
-     *    resume leg that withheld it, so a session resumed twice does not report two withholdings as
-     *    one.
+     *    correlation key (OPTIONAL: a row parked without one exists), and `runId` names the resume leg
+     *    that withheld it, so a session resumed twice does not report two withholdings as one.
      *
      *  - `"memory.session_polluted"` (design/178 §3, #324a; message mode-aware since design/336) —
      *    this session's memory crossed into the one-way externally-exposed state (a tool classified

package/dist/core/fs-write-gate-policy.d.ts

@@ -20,7 +20,12 @@ export interface FsWriteGatePolicyOptions {
     acceptDirs?: readonly string[];
     /** Writes whose canonical target lands inside one of these dirs are ALLOWED and never asked
      *  (auto-approved working areas: the scratchpad dir, plan files). Checked before `acceptDirs`
-     *  (same verdict — the split is intent/observability, exemptions are structural not session-won). */
+     *  (same verdict — the split is intent/observability, exemptions are structural not session-won).
+     *  An entry that RESOLVES onto `rootPath` — or above it — grants nothing: a domain that holds the
+     *  root is not a working area but the whole workspace, and a symlinked scratchpad is all it takes.
+     *  Same rule, same predicate as the prompt's advertised writable directories; say "every write here
+     *  is pre-approved" with `defaultWrite: "allow"` instead. `acceptDirs` is NOT judged by it (a person
+     *  may grant the whole root for a session — see the module header). */
     exemptDirs?: readonly string[];
     /** Verdict for a covered write OUTSIDE every domain: `"ask"` (the manual-mode default) routes it
      *  to the ask-resolution chain (live onAsk / durable park / headless deny); `"allow"` is the
@@ -55,17 +60,20 @@ export interface FsWriteGatePolicyOptions {
      * deployment's gate options, not in core-global state: core stays lane-agnostic (no device concept
      * here); the deployment that runs guarded-capable envs arms it.
      *
-     * WHAT ARMED DOES AND DOES NOT CLOSE (honesty boundary, codex r1-1): armed guarantees every covered
-     * write lands through an ATOMIC precondition-verified backend step — the tool's own
-     * canonicalize→write window is closed. It does NOT yet bind THIS GATE's adjudicated canonical key
-     * across an approval wait: the tool re-canonicalizes at execute time, so a symlink swapped between
-     * this gate's verdict and the tool's execution is re-resolved (and then atomically verified against
-     * the NEW resolution). Closing that remaining window needs the adjudicated key carried through a
-     * trusted approval receipt into tool execution — a separate seat, deliberately not smuggled into
-     * this knob.
+     * WHAT ARMED DOES AND DOES NOT CLOSE (honesty boundary): armed guarantees every covered write lands
+     * through an ATOMIC precondition-verified backend step, closing the tool's own canonicalize→write
+     * window. It does NOT bind THIS GATE's adjudicated canonical key across an approval wait: the tool
+     * re-canonicalizes at execute time, so a symlink swapped between this gate's verdict and the tool's
+     * execution is re-resolved (then atomically verified against the NEW resolution). Closing that
+     * remaining window needs the adjudicated key carried through a trusted approval receipt into tool
+     * execution — a separate seat, deliberately not smuggled into this knob.
      */
     requireGuardedWrite?: boolean;
 }
+/** The coded refusal a gate wired with a root-covering exempt domain throws at CONSTRUCTION — the
+ *  `config.*` prepare-refusal family (one exported spelling per member, thrown so the task never
+ *  starts), so a deployment can compare against this constant instead of matching message text. */
+export declare const WRITE_EXEMPT_DIR_COVERS_ROOT_CODE = "config.write_exempt_dir_covers_root";
 /**
  * Build the file-write approval gate policy. Mount via `combinePolicies` alongside the deployment's
  * other layers (sensitive-path deny, session rules, caller policy) — see the module header for the

package/dist/core/fs-write-gate-policy.js

@@ -1,12 +1,37 @@
-import { canonicalizeTarget, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
+import { canonicalizeTarget, lexicalViewOf, pathFamilyOf, writeTargetPath } from "../tools/fs/safety.js";
 import { isWithin } from "./runner/session-rule-policy.js";
+import { swallowedFenceRoot } from "./runner/advertised-writable-dirs.js";
 import { declaredPathTargetOf, isProtectedWrite } from "./tool-registry.js";
 import { pathTargetBaseOf } from "./effective-path-target.js";
 const ask = (message) => ({ action: "ask", message, decisionReason: "rule" });
+function absoluteRootOf(rootPath, envCwd) {
+    return rootPath === undefined ? undefined : lexicalViewOf(rootPath, envCwd);
+}
+export const WRITE_EXEMPT_DIR_COVERS_ROOT_CODE = "config.write_exempt_dir_covers_root";
+function assertExemptDirsDoNotCoverRoot(exemptDirs, rootLexical) {
+    if (exemptDirs === undefined || rootLexical === undefined)
+        return;
+    for (const raw of exemptDirs) {
+        if (!raw)
+            continue;
+        const dirLexical = lexicalViewOf(raw, rootLexical);
+        const swallowed = swallowedFenceRoot(dirLexical, [rootLexical]);
+        if (swallowed === undefined)
+            continue;
+        const e = new Error(`createFsWriteGatePolicy: exemptDirs entry "${raw}" resolves to ${dirLexical}, which covers this gate's root ${swallowed} — ` +
+            `an exemption that holds the root auto-approves every write under it, which is the whole workspace, so the gate refuses to be built rather than run with write governance silently off. ` +
+            `If that IS what this deployment wants, say it with the knob that means it: defaultWrite: "allow", an open write face, or a permission rule.`);
+        e.code = WRITE_EXEMPT_DIR_COVERS_ROOT_CODE;
+        e.detail = { exemptDir: raw, exemptDirResolved: dirLexical, root: swallowed };
+        throw e;
+    }
+}
 export function createFsWriteGatePolicy(opts) {
     const { env, rootPath, defaultWrite } = opts;
     const acceptDirs = opts.acceptDirs && opts.acceptDirs.length > 0 ? opts.acceptDirs : undefined;
     const exemptDirs = opts.exemptDirs && opts.exemptDirs.length > 0 ? opts.exemptDirs : undefined;
+    const rootLexical = absoluteRootOf(rootPath, env.cwd);
+    assertExemptDirsDoNotCoverRoot(exemptDirs, rootLexical);
     const guardedCapable = env.writeFileGuarded !== undefined;
     const advisory = guardedCapable
         ? ""
@@ -35,12 +60,34 @@ export function createFsWriteGatePolicy(opts) {
                 if (isWithin(root, canon.key))
                     return { action: "allow" };
             }
-            for (const dirs of [exemptDirs, acceptDirs]) {
+            let fenceRootsCanonical;
+            let refusedDomain;
+            for (const [dirs, structural] of [
+                [exemptDirs, true],
+                [acceptDirs, false],
+            ]) {
                 if (!dirs)
                     continue;
                 for (const raw of dirs) {
                     const dir = await canonicalizeTarget(env, raw, signal, pathFamilyOf({ root: rootPath ?? env.cwd }), rootPath);
-                    if (dir.ok && isWithin(dir.key, canon.key))
+                    if (!dir.ok)
+                        continue;
+                    if (structural) {
+                        if (fenceRootsCanonical === undefined) {
+                            const r = rootPath === undefined ? undefined : await canonicalizeTarget(env, rootPath, signal, pathFamilyOf({ root: rootPath }), undefined);
+                            fenceRootsCanonical = r === undefined ? [] : r.ok ? [r.key] : "unresolved";
+                        }
+                        if (fenceRootsCanonical === "unresolved") {
+                            refusedDomain ??= `"${raw}" (this task's root ${rootPath} could not be resolved, so a structural domain that may cover it grants nothing)`;
+                            continue;
+                        }
+                        const swallowed = swallowedFenceRoot(dir.key, fenceRootsCanonical);
+                        if (swallowed !== undefined) {
+                            refusedDomain ??= `"${raw}" (resolves to ${dir.key}, which contains this task's root ${swallowed})`;
+                            continue;
+                        }
+                    }
+                    if (isWithin(dir.key, canon.key))
                         return { action: "allow" };
                 }
             }
@@ -62,7 +109,7 @@ export function createFsWriteGatePolicy(opts) {
             }
             if (defaultWrite === "allow")
                 return { action: "allow" };
-            return ask(`approve write to "${path}"?${advisory}`);
+            return ask(`approve write to "${path}"?${advisory}${refusedDomain === undefined ? "" : ` — note: the configured write domain ${refusedDomain} was not honored; a domain that holds the root would exempt every write under it`}`);
         },
     };
 }

package/dist/core/gate-bounded-await.d.ts

@@ -0,0 +1,38 @@
+import { traceHookCrash } from "./runner/gate-exit.js";
+import type { WriteProtectionVerdict } from "./write-protect.js";
+/**
+ * design/77 §4: resolve `p`, but REJECT (so the caller catches and fails closed) if it hasn't settled within
+ * `ms` OR the `signal` aborts first (the task timed out / was cancelled — its real deadline). A rejection of
+ * `p` propagates with its true cause. Both `ms` and `signal` undefined ⇒ no deadline (await `p`) — the
+ * helper stays generic; every gate call site supplies a finite `ms` ({@link createGateDeadline}), so the
+ * no-deadline arm is unreachable from the gate. Mirrors `tool-policy.ts withTimeout`, but REJECTS on
+ * timeout (no bounded await here has a safe fallback VALUE — the gate's only safe action on an unsettled
+ * one is its own fail-closed arm). `label` names the wait in the rejection, so the arm that catches it can
+ * say which one elapsed.
+ */
+export declare function withGateTimeout<T>(p: Promise<T>, ms: number | undefined, signal?: AbortSignal, label?: string): Promise<T>;
+/**
+ * The deadline used when the caller supplies no `approvalTimeoutMs`. The wait must be bounded EVERYWHERE:
+ * the engine's own assembly never passes `approvalTimeoutMs`, and its only other bound is the task abort
+ * signal, which a task with no walltime limit and no external cancel never fires — so a host driving the
+ * public `runToolGate` with neither knob had NO bound at all and one hung probe froze the call forever. A
+ * probe is an args inspection and a judgment is a path resolution, not an approval wait: 30s is generous
+ * for any legitimate one, and an elapse simply takes the caller's own fail-closed arm.
+ */
+export declare const DEFAULT_GATE_AWAIT_TIMEOUT_MS = 30000;
+/**
+ * The gate's ONE deadline seat, resolved LAZILY and at most once per gate pass: a pass that makes no
+ * bounded await must not sound about a seat it never read. A garbage value (NaN/Infinity/negative, or
+ * above setTimeout's 2^31-1 ceiling, which it would silently clamp to ~1ms — an instant fail-closed the
+ * deployment never asked for) is refused LOUDLY to the default rather than silently reinterpreted
+ * (bad-value loudness discipline; the same ceiling the approve-wait seat refuses).
+ */
+export declare function createGateDeadline(input: {
+    approvalTimeoutMs?: number;
+}, notifier: Parameters<typeof traceHookCrash>[2]): () => number;
+/**
+ * The write-protection judge's wait, at both of its call sites. An elapsed or aborted judgment is the
+ * judge's own `unresolvable` verdict — which the fold denies and the approved-edit arm denies — because a
+ * wait that did not finish IS a target nobody could resolve, and an unjudged target is never vouched.
+ */
+export declare function awaitWriteProtectionJudgment(judged: Promise<WriteProtectionVerdict>, ms: number, signal?: AbortSignal): Promise<WriteProtectionVerdict>;

package/dist/core/gate-bounded-await.js

@@ -0,0 +1,53 @@
+import { traceHookCrash } from "./runner/gate-exit.js";
+export function withGateTimeout(p, ms, signal, label = "reversibilityProbe") {
+    if (ms === undefined && signal === undefined)
+        return p;
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        const done = (fn, v) => {
+            if (settled)
+                return;
+            settled = true;
+            if (timer !== undefined)
+                clearTimeout(timer);
+            signal?.removeEventListener("abort", onAbort);
+            fn(v);
+        };
+        const onAbort = () => done(reject, new Error(`${label} aborted (task ended)`));
+        const timer = ms !== undefined
+            ? setTimeout(() => done(reject, new Error(`${label} timed out after ${ms}ms`)), ms)
+            : undefined;
+        p.then((v) => done(resolve, v), (err) => done(reject, err));
+        if (signal?.aborted) {
+            onAbort();
+            return;
+        }
+        signal?.addEventListener("abort", onAbort);
+    });
+}
+export const DEFAULT_GATE_AWAIT_TIMEOUT_MS = 30_000;
+export function createGateDeadline(input, notifier) {
+    let resolved;
+    return () => {
+        if (resolved !== undefined)
+            return resolved;
+        const supplied = input.approvalTimeoutMs;
+        if (supplied === undefined)
+            resolved = DEFAULT_GATE_AWAIT_TIMEOUT_MS;
+        else if (Number.isFinite(supplied) && supplied >= 0 && supplied <= 2_147_483_647)
+            resolved = supplied;
+        else {
+            resolved = DEFAULT_GATE_AWAIT_TIMEOUT_MS;
+            traceHookCrash(input, new Error(`approvalTimeoutMs must be a non-negative finite number no greater than 2147483647 (got ${String(supplied)}) — the gate's bounded awaits fall back to the ${DEFAULT_GATE_AWAIT_TIMEOUT_MS}ms default`), notifier);
+        }
+        return resolved;
+    };
+}
+export async function awaitWriteProtectionJudgment(judged, ms, signal) {
+    try {
+        return await withGateTimeout(judged, ms, signal, "writeProtectionJudge");
+    }
+    catch (err) {
+        return { kind: "unresolvable", cause: err instanceof Error ? err.message : String(err), unresolvedSymlink: false };
+    }
+}

package/dist/core/gate-fold.js

@@ -1,35 +1,12 @@
 import { inlineUntrusted } from "./untrusted-text.js";
 import { PROBE_REASON_MAX, normalizeProbeCause } from "./checkpoint-store.js";
+import { normalizeReadRootCandidate } from "./read-root-candidate.js";
 import { traceHookCrash } from "./runner/gate-exit.js";
-function withProbeTimeout(p, ms, signal) {
-    if (ms === undefined && signal === undefined)
-        return p;
-    return new Promise((resolve, reject) => {
-        let settled = false;
-        const done = (fn, v) => {
-            if (settled)
-                return;
-            settled = true;
-            if (timer !== undefined)
-                clearTimeout(timer);
-            signal?.removeEventListener("abort", onAbort);
-            fn(v);
-        };
-        const onAbort = () => done(reject, new Error("reversibilityProbe aborted (task ended)"));
-        const timer = ms !== undefined
-            ? setTimeout(() => done(reject, new Error(`reversibilityProbe timed out after ${ms}ms`)), ms)
-            : undefined;
-        if (signal?.aborted) {
-            onAbort();
-            return;
-        }
-        signal?.addEventListener("abort", onAbort);
-        p.then((v) => done(resolve, v), (err) => done(reject, err));
-    });
-}
-const DEFAULT_PROBE_TIMEOUT_MS = 30_000;
+import { writeProtectionTightenDecision } from "./write-protect.js";
+import { createGateDeadline, awaitWriteProtectionJudgment, withGateTimeout } from "./gate-bounded-await.js";
 export async function runGateFold(pass) {
     const { input, toolName, toolCallId, callSignal, ledger, notifier, adjudicate } = pass;
+    const boundedAwaitDeadlineMs = createGateDeadline(input, notifier);
     pass.req = { toolName, args: pass.currentInput, toolCallId, ...(pass.req.face !== undefined ? { face: pass.req.face } : {}) };
     pass.decision = adjudicate ? await (callSignal !== undefined ? adjudicate(pass.req, callSignal) : adjudicate(pass.req)) : { action: "allow" };
     {
@@ -38,6 +15,9 @@ export async function runGateFold(pass) {
             pass.deniedBy = refusedBy;
         if (refusedBy !== undefined)
             pass.denyCause = ledger.causeOf(pass.decision);
+        const attributed = ledger.classifierRoundOf(pass.decision);
+        if (attributed !== undefined)
+            pass.classifierRound = attributed;
     }
     if ((pass.decision.action === "allow" || pass.decision.action === "ask") && pass.decision.updatedInput !== undefined) {
         pass.policyRewrite = pass.decision.updatedInput;
@@ -80,23 +60,13 @@ export async function runGateFold(pass) {
         let probeReason;
         let probeCause;
         let probeMandated;
+        let probeReadRootCandidate;
         if (input.irreversibility === "maybe" && input.reversibilityProbe) {
             let reversible = false;
             const probeArgs = pass.policyRewrite !== undefined ? pass.policyRewrite : pass.currentInput;
-            const suppliedProbeMs = input.approvalTimeoutMs;
-            let probeTimeoutMs;
-            if (suppliedProbeMs === undefined) {
-                probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS;
-            }
-            else if (Number.isFinite(suppliedProbeMs) && suppliedProbeMs >= 0 && suppliedProbeMs <= 2_147_483_647) {
-                probeTimeoutMs = suppliedProbeMs;
-            }
-            else {
-                probeTimeoutMs = DEFAULT_PROBE_TIMEOUT_MS;
-                traceHookCrash(input, new Error(`approvalTimeoutMs must be a non-negative finite number no greater than 2147483647 (got ${String(suppliedProbeMs)}) — the reversibilityProbe deadline falls back to the ${DEFAULT_PROBE_TIMEOUT_MS}ms default`), notifier);
-            }
+            const probeTimeoutMs = boundedAwaitDeadlineMs();
             try {
-                const verdict = await withProbeTimeout(Promise.resolve(input.reversibilityProbe(probeArgs)), probeTimeoutMs, input.abortSignal);
+                const verdict = await withGateTimeout(Promise.resolve(input.reversibilityProbe(probeArgs)), probeTimeoutMs, input.abortSignal);
                 reversible = verdict?.reversible === true;
                 if (!reversible) {
                     const raw = verdict?.reason;
@@ -105,6 +75,7 @@ export async function runGateFold(pass) {
                     probeCause = normalizeProbeCause(verdict?.cause);
                     if (verdict?.mandated === true)
                         probeMandated = true;
+                    probeReadRootCandidate = normalizeReadRootCandidate(verdict?.readRootCandidate);
                 }
             }
             catch (err) {
@@ -123,6 +94,7 @@ export async function runGateFold(pass) {
                 ...(probeReason !== undefined ? { probeReason } : {}),
                 ...(probeCause !== undefined ? { probeCause } : {}),
                 ...(probeMandated === true ? { probeMandated: true } : {}),
+                ...(probeReadRootCandidate !== undefined ? { probeReadRootCandidate } : {}),
             };
             pass.tightenedBy = input.shellGated === true ? "shell_gate" : "safety";
         }
@@ -139,14 +111,14 @@ export async function runGateFold(pass) {
         pass.tightenedBy = "safety";
     }
     if (pass.decision.action === "allow" && input.writeProtectionCheck !== undefined) {
-        const writeProtectedHit = input.writeProtectionCheck(toolName, pass.policyRewrite !== undefined ? pass.policyRewrite : pass.currentInput, pass.req.face);
-        if (writeProtectedHit !== null) {
-            pass.decision = {
-                action: "ask",
-                message: `tool "${toolName}" writes to a write-protected path (table entry "${writeProtectedHit.name}") — explicit approval required`,
-                decisionReason: "safety",
-            };
-            pass.tightenedBy = "safety";
+        const judged = input.writeProtectionCheck(toolName, pass.policyRewrite !== undefined ? pass.policyRewrite : pass.currentInput, pass.req.face, input.trackedCwd?.(), pass.callSignal ?? input.abortSignal);
+        const decision = judged === null ? undefined : writeProtectionTightenDecision(toolName, await awaitWriteProtectionJudgment(judged, boundedAwaitDeadlineMs(), pass.callSignal ?? input.abortSignal));
+        if (decision !== undefined) {
+            pass.decision = decision;
+            if (decision.action === "ask")
+                pass.tightenedBy = "safety";
+            else
+                pass.deniedBy = "write_protection";
         }
     }
     return await pass.afterFold(pass);