@sema-agent/core 7.13.0 → 7.15.0

package/dist/core/runner/prepare-hands-readface.js

@@ -2,7 +2,7 @@ import { emitTrace } from "../trace.js";
 import { StubExecutionEnv } from "../stub-env.js";
 import { hasBackgroundShell } from "../background-shell.js";
 import { defaultTaskRegistry } from "../task-registry.js";
-import { bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, pdfModelCapabilitiesOf, resolveReadDenyBuiltins, inheritSessionReadFileState, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
+import { bashReadBoundaryProbe, bashReversibilityProbe, compileReadDeny, createHandsToolkit, deploymentReadFaceClampNotice, pdfModelCapabilitiesOf, resolveReadDenyBuiltins, inheritSessionReadFileState, resolveReadFace, seedReadFileStateFromContext, seedReadFileStateFromTranscript, } from "../../tools/fs/index.js";
 import { resolveKey, sha256 } from "../../tools/fs/safety.js";
 import { normalizeFileText } from "../../tools/fs/encoding.js";
 import { wholeFileRecordsFromTranscript } from "./session-file-state-replay.js";
@@ -117,14 +117,13 @@ export function resolveHandsLessReadFace(input) {
         attachmentRootCanonical: undefined,
         readDenyMatcher: undefined,
         envHandToolNames: new Set(),
-        shellGatedBash: false,
-        shellGatedMonitor: false,
+        shellGatedTools: new Set(),
         sealReadStateSeat: undefined,
     };
 }
 export async function prepareHandsMount(input) {
     const envHandToolNames = new Set();
-    const { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, firstPartyOffload, roster, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes } = input;
+    const { handsEnabled, executionEnv, taskRootFinal, rebaseRestoredPath, resume, session, sessionId, hostTaskId, taskScope, fullShellReachable, effectiveShellGate, toolFaceSnapshot, model, spec, deps, internals, memoryWriteGateRef, advertisedWritableDirs, firstPartyOffload, roster, egressTools, irreversibilityTier, irreversibleTools, reversibilityProbes } = input;
     assertStringArraySeat(spec.additionalDirectories, "TaskSpec.additionalDirectories", "strings");
     assertStringArraySeat(spec.additionalReadDirectories, "TaskSpec.additionalReadDirectories", "strings");
     assertStringArraySeat(deps.readDenyPatterns, "RunnerDeps.readDenyPatterns", "compiler-owned");
@@ -140,8 +139,7 @@ export async function prepareHandsMount(input) {
     let resolvedReadFace;
     let readDenyAdditionsNormalized = [];
     let handsLessResolvedFace;
-    let shellGatedBash = false;
-    let shellGatedMonitor = false;
+    const shellGatedTools = new Set();
     const additionalRootsCanonical = [];
     const additionalReadRootsCanonical = [];
     let attachmentRootCanonical;
@@ -178,19 +176,10 @@ export async function prepareHandsMount(input) {
         };
         await canonicalizeExtraDirs(spec.additionalDirectories, "additionalDirectories", additionalRootsCanonical);
         await canonicalizeExtraDirs(spec.additionalReadDirectories, "additionalReadDirectories", additionalReadRootsCanonical);
-        if (spec.envFacts?.scratchpadDir) {
-            let c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
-            if (!c.ok && c.error.code === "not_found") {
-                const marker = await executionEnv.joinPath([spec.envFacts.scratchpadDir, ".sema-scratchpad"]);
-                const exclusiveCreate = executionEnv.writeFileExclusive?.bind(executionEnv);
-                if (marker.ok && exclusiveCreate) {
-                    const w = await exclusiveCreate(marker.value, "");
-                    if (w.ok || w.error.code === "already_exists")
-                        c = await executionEnv.canonicalPath(spec.envFacts.scratchpadDir);
-                }
-            }
-            if (c.ok)
-                additionalRootsCanonical.push(c.value);
+        if (advertisedWritableDirs !== undefined) {
+            if (spec.envFacts?.scratchpadDir)
+                await advertisedWritableDirs.admit({ path: spec.envFacts.scratchpadDir, advertiser: "scratchpad", materializeMarker: ".sema-scratchpad" });
+            additionalRootsCanonical.push(...advertisedWritableDirs.roots);
         }
         for (const a of [additionalRootsCanonical, additionalReadRootsCanonical])
             a.splice(0, a.length, ...new Set(a));
@@ -354,34 +343,35 @@ export async function prepareHandsMount(input) {
         }
         roster.mountAll(band.map((t) => (envHandToolNames.add(t.name), firstPartyOffload(t))), { source: "builtin", mountedBy: "hands" });
         const shellGate = effectiveShellGate;
-        if (shellGate === "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
-            deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — no shell safety-axis ` +
-                `fold applies to this run (commands are adjudicated by the ordinary policy/hook chain only). ` +
-                `Set spec.shellGate to "classify" or "always" if this deployment expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
-        }
-        if (shellGate !== "off" && !(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
-            const bashTierBefore = irreversibilityTier.get("Bash");
-            shellGatedBash = !egressTools.has("Bash") && bashTierBefore !== "always" && bashTierBefore !== "maybe";
-            const bashEffectiveTier = shellGate === "always" || bashTierBefore === "always" ? "always" : "maybe";
-            irreversibilityTier.set("Bash", bashEffectiveTier);
-            irreversibleTools.add("Bash");
+        if (!(executionEnv instanceof StubExecutionEnv) && spec.handsReadOnly !== true) {
+            if (shellGate === "off") {
+                deps.onError?.(new Error(`shell gate doctrine is "off" while a real writable shell (Bash) is mounted — the read boundary is ` +
+                    `still judged on every command (a deny-listed or out-of-root read asks; the ask is mandated), but no ` +
+                    `residual shell-risk classifier is installed: writes, egress and unknown commands are adjudicated by ` +
+                    `the ordinary policy/hook chain only. Set spec.shellGate to "classify" or "always" if this deployment ` +
+                    `expects doctrine-gated shell behavior.`), { phase: "config", sessionId, classification: "shell-gate-off" });
+            }
             const shellReadBoundary = () => ({
                 roots: [rootCanonical, ...additionalRootsCanonical, ...additionalReadRootsCanonical],
                 ...(handsCwdRef?.current !== undefined ? { cwd: handsCwdRef.current } : {}),
                 denyMatch: (p) => readDenyMatcher?.matchPath(p)?.pattern ?? null,
                 ...(resolvedReadFace !== undefined ? { face: resolvedReadFace } : {}),
             });
-            if (shellGate === "classify" && shellGatedBash)
-                reversibilityProbes.set("Bash", bashReversibilityProbe(undefined, shellReadBoundary));
-            if (backgroundTaskToolsActive) {
-                const monitorTierBefore = irreversibilityTier.get("Monitor");
-                shellGatedMonitor = !egressTools.has("Monitor") && monitorTierBefore !== "always" && monitorTierBefore !== "maybe";
-                const monitorEffectiveTier = shellGate === "always" || monitorTierBefore === "always" ? "always" : "maybe";
-                irreversibilityTier.set("Monitor", monitorEffectiveTier);
-                irreversibleTools.add("Monitor");
-                if (shellGate === "classify" && shellGatedMonitor)
-                    reversibilityProbes.set("Monitor", bashReversibilityProbe(undefined, shellReadBoundary));
-            }
+            const installShellSeat = (name) => {
+                const tierBefore = irreversibilityTier.get(name);
+                const seatOwned = !egressTools.has(name) && tierBefore !== "always" && tierBefore !== "maybe";
+                if (seatOwned)
+                    shellGatedTools.add(name);
+                const tier = shellGate === "always" || tierBefore === "always" ? "always" : "maybe";
+                irreversibilityTier.set(name, tier);
+                irreversibleTools.add(name);
+                if (seatOwned && tier === "maybe") {
+                    reversibilityProbes.set(name, shellGate === "classify" ? bashReversibilityProbe(undefined, shellReadBoundary) : bashReadBoundaryProbe(shellReadBoundary));
+                }
+            };
+            installShellSeat("Bash");
+            if (backgroundTaskToolsActive)
+                installShellSeat("Monitor");
         }
     }
     return {
@@ -400,8 +390,7 @@ export async function prepareHandsMount(input) {
         attachmentRootCanonical,
         readDenyMatcher,
         envHandToolNames,
-        shellGatedBash,
-        shellGatedMonitor,
+        shellGatedTools,
         sealReadStateSeat,
     };
 }

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

@@ -43,7 +43,7 @@ import type { DelegationContentSafety } from "../memory-engine/delegation-proven
 import type { SessionPermissionRules } from "../session-policy-store.js";
 import type { SessionStore } from "../session.js";
 import { type OnAsk } from "../tool-policy.js";
-import type { RunnerDeps, RuntimeCaps, TaskEvent, TaskSpec, ToolExecuteContext } from "../types.js";
+import type { RunnerDeps, RuntimeCaps, ShellGateDoctrine, TaskEvent, TaskSpec, ToolExecuteContext } from "../types.js";
 import type { ActiveSkillScope } from "./active-skill-scope.js";
 import type { InheritedGate, Prepared, PrepareResume, RunInternals, ToolFaceSnapshot } from "./contracts.js";
 import { type StopForDenialLimit } from "./denial-limit-arms.js";
@@ -51,9 +51,11 @@ export interface PrepareInheritedGateInput {
     /** borrowed-readonly — the REBOUND spec. Read: `shellGate` (the own doctrine the chain fold tightens), `durableApproval`
      *  (the mandate tests + the children's copy), `onAsk`/`onQuestion` (the frozen seats), `handsReadOnly` / `interactiveTools`
      *  / `oneShot` / `clientContext` / `principal` / `additionalDirectories` / `additionalReadDirectories` / `envFacts` /
-     *  `memoryPersistenceCapable` / `getApiKeyAndHeaders` / `checkpointStore` / `backgroundScope` / `enablePlanMode` (the ctx
-     *  enrichment's trusted seats). Never mutated. */
-    spec: Pick<TaskSpec, "shellGate" | "durableApproval" | "onAsk" | "onQuestion" | "handsReadOnly" | "interactiveTools" | "oneShot" | "clientContext" | "principal" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "getApiKeyAndHeaders" | "checkpointStore" | "backgroundScope" | "enablePlanMode" | "excludeAllTools">;
+     *  `memoryPersistenceCapable` / `getApiKeyAndHeaders` / `backgroundScope` / `enablePlanMode` (the ctx enrichment's
+     *  trusted seats). Never mutated. */
+    spec: Pick<TaskSpec, "shellGate" | "durableApproval" | "onAsk" | "onQuestion" | "handsReadOnly" | "interactiveTools" | "oneShot" | "clientContext" | "principal" | "additionalDirectories" | "additionalReadDirectories" | "envFacts" | "memoryPersistenceCapable" | "getApiKeyAndHeaders" | "backgroundScope" | "enablePlanMode" | "excludeAllTools">;
+    /** borrowed-readonly — the seat this run hands its children (`checkpointSeatOf`, minted once by the driver after the config doors): the ctx's `checkpointStoreForChildren`, absent when the run has no seat. */
+    checkpointSeat: import("../checkpoint-seat.js").CheckpointSeat | undefined;
     /** borrowed-readonly — the deployment seats: `autoMode.denialLimit` (the rebuilt trackers' bounds), `memoryScopeAdmission` /
      *  `deploymentMemoryScopes` / `compliancePostureResolver` (the governed-provenance bit), `onError` (the screening-face crash
      *  lane), `onNotice` (the stop seat's notice), `executionEnv` (the hook-env identity predicate), `delegationEntryCaps` (resolved
@@ -192,7 +194,7 @@ export interface PrepareInheritedGateResult {
     /** owned — the monotonic governed-provenance bit for this leg. */
     orgGovernedProvenance: boolean;
     /** owned — the spec's own shellGate tightened by the inherited doctrine. */
-    effectiveShellGate: "off" | "classify" | "always";
+    effectiveShellGate: ShellGateDoctrine;
     /** borrowed-mutable — THIS task's own session-rule snapshot for its children's chain. Writers (R-3): the policy-chain
      *  station's session-policy read, once per leg, when a store is wired and the task carries its own sessionId. Read by
      *  `inheritedGateForChildren` at spawn time. */

package/dist/core/runner/prepare-inherited-gate.js

@@ -222,7 +222,7 @@ export function prepareInheritedGate(input) {
             delegationSettlement: delegationSettlementForChildren,
             ...(autoModeDecider ? { autoModeReview: { decider: autoModeDecider } } : {}),
             ...(spec.durableApproval !== undefined ? { durableApprovalForChildren: { ...spec.durableApproval } } : {}),
-            ...(spec.checkpointStore === "disabled" ? { checkpointStoreDisabledForChildren: true } : {}),
+            ...(input.checkpointSeat !== undefined ? { checkpointStoreForChildren: input.checkpointSeat } : {}),
             taskId: hostTaskId,
             ...(internals?.parentTaskId !== undefined ? { parentTaskId: internals.parentTaskId } : {}),
             ...(internals?.parentSessionId !== undefined ? { parentSessionId: internals.parentSessionId } : {}),

package/dist/core/runner/prepare-memory.d.ts

@@ -1,6 +1,7 @@
 import type { BeforeWriteHook, EffectiveMemoryScopes, RunnerDeps, TaskSpec, ToolSpec } from "../types.js";
 import { type CaptureEntitlementInput, type MemoryCapturePosture } from "./memory-capture-optout.js";
 import type { Prepared } from "./contracts.js";
+import type { AdvertisedWritableDirs } from "./advertised-writable-dirs.js";
 export interface PrepareMemoryInput {
     /** borrowed-readonly — the REBOUND spec. Read: `memory` (the scope declaration this phase
      *  normalizes) and `principal` (the org-admission subject). Never mutated. */
@@ -33,23 +34,23 @@ export interface PrepareMemoryInput {
      * arms — a hands-less run that mounts its own `Write` counts, and an `excludeTools: ["Write"]`
      * run reads as unmounted whatever the hands band did. Threaded into `engine.inject` so a run with
      * a writable memory scope but no write channel is not instructed to call a tool that is not on
-     * its roster (or cannot reach the store); the RB-276 index seed follows the same gate.
+     * its roster (or cannot reach the store); the RB-276 index seed follows the same gate. Since #691 this is
+     * the FIRST conjunct of the write channel; the second is the root fence's admission of the write plane's
+     * root through {@link advertisedWritableDirs} — the channel is open only when both hold.
      */
     writeToolsMounted: boolean;
+    /**
+     * borrowed-mutable — #691: the root fence's advertised-writable-directory seat (its module header carries the
+     * one rule). Present iff the hands band mounts this run (a fence exists between the roster's `Write` and the
+     * store); absent ⇒ a `Write` on the roster is a caller tool running in the host process, which no fence
+     * stands before, so admission holds trivially. This phase admits the WRITE plane's root when the channel's
+     * first conjunct holds (`writeToolsMounted`) and a write face exists; a read-only layering admits nothing.
+     */
+    advertisedWritableDirs?: AdvertisedWritableDirs;
     /** borrowed-readonly — design/319 (A ticket): the run's reminder provenance mark: the memory engine's announcement
      *  block is an engine-authored `<system-reminder>`, so its open tag must carry the same mark the
      *  system-prompt declaration names. Threaded into every `engine.inject` call this phase builds. */
     reminderMark: string;
-    /**
-     * borrowed-readonly — the session-wide persistence verdict: `TaskSpec.memoryPersistenceCapable` (the deployment's own
-     * statement — the only honest channel for a custom memory writer persisting through its closure,
-     * which no inference can see) when set, else the KNOWN-store-path inference: a mounted,
-     * non-excluded file-write tool (Write/Edit/NotebookEdit) or a write-capable shell. A generic
-     * write-effect tool does NOT count — a mail sender's side effect is not a memory store, and
-     * counting it re-opened the silent-confabulation hole. `false` ⇒ this phase mounts
-     * {@link MEMORY_READONLY_NOTICE} where the engine is silent.
-     */
-    rosterCanPersist: boolean;
     /**
      * borrowed-readonly — the raw `TaskSpec.memoryPersistenceCapable` DECLARATION, kept separate from the composed
      * {@link rosterCanPersist} verdict because the two drive different arms:
@@ -184,35 +185,31 @@ export interface PrepareMemoryInput {
         governedProvenance: boolean;
     };
 }
-export interface PrepareMemoryResult {
-    memoryEngineSession: Prepared["memoryEngineSession"];
+/** #691 — what {@link PrepareMemoryResult.composeInjection} hands back: the composed `# Memory` block (undefined
+ *  when nothing mounts), the recall-discipline segment EXACTLY as appended (prepare-task's retraction strips this
+ *  returned string — #493 单铸), and the RB-276 index seed files whose full disk text rides in the block. */
+export interface MemoryInjectionComposition {
     memoryBlock: string | undefined;
-    /**
-     * design/178 ②-1 — the `memory_search`/`memory_get` pair's ToolSpecs, present iff the engine
-     * session mounted AND `memorySearchToolsPlanned` was true. Built HERE because this phase owns the
-     * planes (backend + mounted scopes + per-plane retrieved-account recorder); prepare-task mounts
-     * them (atomic pair) and runs the remaining conjuncts.
-     */
-    memoryTools?: ToolSpec[];
-    /**
-     * #493 单铸 — the recall-discipline segment EXACTLY as this phase appended it to
-     * {@link memoryBlock} (present iff {@link memoryTools} is). prepare-task's support-name
-     * retraction strips THIS string: the segment's composition now depends on the marked-presence
-     * signal only this phase holds, so a strip-site re-composition could mint a string that was
-     * never appended and leave the real one standing.
-     */
     recallDisciplineSegment?: string;
-    /**
-     * RB-276 — engine-materialized files whose FULL disk text rides in {@link memoryBlock}, for the
-     * caller to pre-mark READ through the parity-204 seeding lane (`prepare-task`'s `seedContextFiles`,
-     * which applies the SAME containment as a real Read — a memory dir outside the task root is simply
-     * skipped, exactly as the Write tool would refuse it there). Today this is the materialized
-     * MEMORY.md index; see `MemoryInjection.indexSeed` for the conditions that qualify it.
-     */
     seedFiles?: ReadonlyArray<{
         path: string;
         content: string;
     }>;
+}
+export interface PrepareMemoryResult {
+    memoryEngineSession: Prepared["memoryEngineSession"];
+    memoryTools?: ToolSpec[];
+    /**
+     * owned — #691: the injection's COMPOSITION step, run by the driver AFTER the hands phase (the mount above runs
+     * BEFORE it). It performs the one destructive read this phase has — `inject()` drains the announcement queue —
+     * so a hands-phase refusal cannot consume announcements a later prepare should deliver, and it takes the
+     * roster-wide persistence verdict the driver can only read off the MOUNTED roster (`rosterCanPersist`: the
+     * `TaskSpec.memoryPersistenceCapable` declaration when set, else the known-store-path inference over the
+     * assembled tools). Call exactly once per prepare.
+     */
+    composeInjection: (facts: {
+        rosterCanPersist: boolean;
+    }) => MemoryInjectionComposition;
     /**
      * The FROZEN org-admission verdict of this prepare: every org scope the task actually mounts
      * (deployment-origin kept + request-origin admitted). Threaded into the run's child chain

package/dist/core/runner/prepare-memory.js

@@ -74,6 +74,7 @@ export async function prepareMemory(input) {
     let captureLineageIndeterminate = false;
     let memoryEngineSession;
     let memoryTools;
+    let writeChannelOpen = false;
     let memoryMarkedEntriesServed = false;
     let effectiveMemoryScopes;
     const originOf = (scope) => scopeOriginsSnapshot !== undefined
@@ -373,7 +374,7 @@ export async function prepareMemory(input) {
                 writeHandle = writeIsPersonal ? personalHandle : projectHandle;
                 readOnlyEngine = writeIsPersonal ? projectEngine : personalEngine;
                 readOnlyHandle = writeIsPersonal ? projectHandle : personalHandle;
-                injectFn = () => mergeInjections(projectEngine.inject(projectHandle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark }), personalEngine.inject(personalHandle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark }));
+                injectFn = () => mergeInjections(projectEngine.inject(projectHandle, { writeToolMounted: writeChannelOpen, reminderMark: input.reminderMark }), personalEngine.inject(personalHandle, { writeToolMounted: writeChannelOpen, reminderMark: input.reminderMark }));
                 toolPlanes = [
                     {
                         backend: retrievalBackend(backend, adoptionRestricted || captureOptedOut || captureIndeterminate || p.writePlane !== "project"),
@@ -417,7 +418,7 @@ export async function prepareMemory(input) {
                 memoryMarkedEntriesServed = handle.markedEntriesPresent === true;
                 writeEngine = personalEngine;
                 writeHandle = handle;
-                injectFn = () => personalEngine.inject(handle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark });
+                injectFn = () => personalEngine.inject(handle, { writeToolMounted: writeChannelOpen, reminderMark: input.reminderMark });
                 harvestBoth = async () => personalEngine.harvest(handle, { ...pollutedOpts(personalEngine), sessionId, ...(await admitNothingOptsNow()) });
                 toolPlanes = [
                     {
@@ -445,7 +446,7 @@ export async function prepareMemory(input) {
                 memoryMarkedEntriesServed = handle.markedEntriesPresent === true;
                 writeEngine = engine;
                 writeHandle = handle;
-                injectFn = () => engine.inject(handle, { writeToolMounted: input.writeToolsMounted, reminderMark: input.reminderMark });
+                injectFn = () => engine.inject(handle, { writeToolMounted: writeChannelOpen, reminderMark: input.reminderMark });
                 harvestBoth = async () => engine.harvest(handle, { ...pollutedOpts(engine), sessionId, ...(await admitNothingOptsNow()) });
                 toolPlanes = [
                     {
@@ -457,6 +458,22 @@ export async function prepareMemory(input) {
                     },
                 ];
             }
+            const foreignUnderRoot = [];
+            if (input.writeToolsMounted && writeHandle.writeScope !== null && input.advertisedWritableDirs !== undefined) {
+                for (const d of [...writeEngine.readonlyDirNamesUnderRoot(writeHandle)].sort())
+                    foreignUnderRoot.push(`another scope's directory ${d}`);
+                const controlPlane = canonicalize(writeEngine.controlPlaneDir);
+                if (isContainedIn(writeHandle.writableRoot, controlPlane))
+                    foreignUnderRoot.push(`the engine's control plane ${controlPlane}`);
+            }
+            if (foreignUnderRoot.length > 0) {
+                deps.onError?.(new Error(`memory advertised writable directory refused: the write scope's root ${writeHandle.writableRoot} contains what is not the model's to touch (${foreignUnderRoot.join("; ")}) — the file tools' root fence is directory-granular, so admitting it would expose those files; memory writes through the file tools stay closed this session and the write instruction is not taught.`), { phase: "config", sessionId });
+            }
+            writeChannelOpen =
+                input.writeToolsMounted &&
+                    writeHandle.writeScope !== null &&
+                    foreignUnderRoot.length === 0 &&
+                    (input.advertisedWritableDirs === undefined || (await input.advertisedWritableDirs.admit({ path: writeHandle.writableRoot, advertiser: "memory", expectCanonical: writeHandle.writableRoot })));
             memoryWriteGateRef.current = async (w) => {
                 if (readOnlyEngine !== undefined && readOnlyHandle !== undefined) {
                     const ro = readOnlyEngine.gateWrite(readOnlyHandle, w.key, w.content);
@@ -690,56 +707,63 @@ export async function prepareMemory(input) {
             }
         }
     }
-    let memoryBlock;
-    let seedFiles;
-    let recallDisciplineSegment;
     if (memorySpec && memorySpec.enabled && !useMemoryEngine) {
         const detail = "TaskSpec.memory is enabled but RunnerDeps.memoryBackend is not configured; memory is inactive for this task (the legacy memoryStore fallback was retired in design/138 S4 and the dep was removed in design/157 B19).";
         deps.onError?.(new Error(detail), { phase: "config", sessionId });
     }
-    if (memoryEngineSession) {
-        const injection = memoryEngineSession.inject();
-        let blockBody = injection.block;
-        if (captureOptedOut) {
-            blockBody = [MEMORY_CAPTURE_OPTOUT_NOTICE, injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
-        }
-        else if (captureIndeterminate && input.rosterCanPersist) {
-            blockBody = [MEMORY_CAPTURE_INDETERMINATE_NOTICE, injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
-        }
-        else if (!input.rosterCanPersist && injection.instruction === "" && injection.readOnlyNotice === undefined) {
-            blockBody = blockBody.trim() ? `${MEMORY_READONLY_NOTICE}\n\n${blockBody}` : MEMORY_READONLY_NOTICE;
-        }
-        else if (!input.rosterCanPersist && injection.instruction !== "") {
-            blockBody = [MEMORY_READONLY_NOTICE, injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
-        }
-        else if (input.memoryPersistenceDeclared === true && injection.readOnlyNotice !== undefined) {
-            blockBody = [injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
-        }
-        if (!input.rosterCanPersist &&
-            (injection.announceBlock?.trim() ?? "") !== "" &&
-            blockBody.includes(injection.announceBlock) &&
-            !blockBody.trimEnd().endsWith(MEMORY_ANNOUNCEMENT_READONLY_CODA)) {
-            blockBody = `${blockBody}\n\n${MEMORY_ANNOUNCEMENT_READONLY_CODA}`;
-        }
-        if (captureOptedOut &&
-            input.rosterCanPersist &&
-            (injection.announceBlock?.trim() ?? "") !== "" &&
-            blockBody.includes(injection.announceBlock) &&
-            !blockBody.trimEnd().endsWith(MEMORY_ANNOUNCEMENT_CAPTURE_OPTOUT_CODA)) {
-            blockBody = `${blockBody}\n\n${MEMORY_ANNOUNCEMENT_CAPTURE_OPTOUT_CODA}`;
-        }
-        if (blockBody.trim())
-            memoryBlock = blockBody;
-        if (memoryTools !== undefined) {
-            recallDisciplineSegment = memoryRecallDisciplineSegment(input.memoryProvenance, { markedEntriesServed: memoryMarkedEntriesServed });
-            memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${recallDisciplineSegment}` : recallDisciplineSegment;
-        }
-        if (memoryEngineSession.handle.writeScope !== null && input.writeToolsMounted && input.rosterCanPersist && !captureOptedOut && !captureIndeterminate) {
-            memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${MEMORY_PREFERENCE_DISCIPLINE}` : MEMORY_PREFERENCE_DISCIPLINE;
+    const composeInjection = (facts) => {
+        let memoryBlock;
+        let seedFiles;
+        let recallDisciplineSegment;
+        if (memoryEngineSession) {
+            const injection = memoryEngineSession.inject();
+            let blockBody = injection.block;
+            if (captureOptedOut) {
+                blockBody = [MEMORY_CAPTURE_OPTOUT_NOTICE, injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+            }
+            else if (captureIndeterminate && facts.rosterCanPersist) {
+                blockBody = [MEMORY_CAPTURE_INDETERMINATE_NOTICE, injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+            }
+            else if (!facts.rosterCanPersist && injection.instruction === "" && injection.readOnlyNotice === undefined) {
+                blockBody = blockBody.trim() ? `${MEMORY_READONLY_NOTICE}\n\n${blockBody}` : MEMORY_READONLY_NOTICE;
+            }
+            else if (!facts.rosterCanPersist && injection.instruction !== "") {
+                blockBody = [MEMORY_READONLY_NOTICE, injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+            }
+            else if (input.memoryPersistenceDeclared === true && injection.readOnlyNotice !== undefined) {
+                blockBody = [injection.index, injection.announceBlock].filter((s) => Boolean(s && s.trim())).join("\n\n");
+            }
+            if (!facts.rosterCanPersist &&
+                (injection.announceBlock?.trim() ?? "") !== "" &&
+                blockBody.includes(injection.announceBlock) &&
+                !blockBody.trimEnd().endsWith(MEMORY_ANNOUNCEMENT_READONLY_CODA)) {
+                blockBody = `${blockBody}\n\n${MEMORY_ANNOUNCEMENT_READONLY_CODA}`;
+            }
+            if (captureOptedOut &&
+                facts.rosterCanPersist &&
+                (injection.announceBlock?.trim() ?? "") !== "" &&
+                blockBody.includes(injection.announceBlock) &&
+                !blockBody.trimEnd().endsWith(MEMORY_ANNOUNCEMENT_CAPTURE_OPTOUT_CODA)) {
+                blockBody = `${blockBody}\n\n${MEMORY_ANNOUNCEMENT_CAPTURE_OPTOUT_CODA}`;
+            }
+            if (blockBody.trim())
+                memoryBlock = blockBody;
+            if (memoryTools !== undefined) {
+                recallDisciplineSegment = memoryRecallDisciplineSegment(input.memoryProvenance, { markedEntriesServed: memoryMarkedEntriesServed });
+                memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${recallDisciplineSegment}` : recallDisciplineSegment;
+            }
+            if (memoryEngineSession.handle.writeScope !== null && writeChannelOpen && facts.rosterCanPersist && !captureOptedOut && !captureIndeterminate) {
+                memoryBlock = memoryBlock !== undefined ? `${memoryBlock}\n\n${MEMORY_PREFERENCE_DISCIPLINE}` : MEMORY_PREFERENCE_DISCIPLINE;
+            }
+            if (memoryBlock !== undefined && injection.indexSeed !== undefined && facts.rosterCanPersist && !captureOptedOut && !captureIndeterminate)
+                seedFiles = [injection.indexSeed];
         }
-        if (memoryBlock !== undefined && injection.indexSeed !== undefined && input.rosterCanPersist && !captureOptedOut && !captureIndeterminate)
-            seedFiles = [injection.indexSeed];
-    }
+        return {
+            memoryBlock,
+            ...(recallDisciplineSegment !== undefined ? { recallDisciplineSegment } : {}),
+            ...(seedFiles !== undefined ? { seedFiles } : {}),
+        };
+    };
     if (effectiveMemoryScopes === undefined) {
         effectiveMemoryScopes = memorySpec
             ? memorySpec.enabled
@@ -749,12 +773,10 @@ export async function prepareMemory(input) {
     }
     return {
         memoryEngineSession,
-        memoryBlock,
         admittedOrgScopes,
         ownOrgVerdict,
         effectiveMemoryScopes,
         ...(memoryTools !== undefined ? { memoryTools } : {}),
-        ...(recallDisciplineSegment !== undefined ? { recallDisciplineSegment } : {}),
-        ...(seedFiles !== undefined ? { seedFiles } : {}),
+        composeInjection,
     };
 }

package/dist/core/runner/prepare-park-ask.d.ts

@@ -25,7 +25,7 @@ import { type CheckpointStore } from "../checkpoint-store.js";
 import type { SessionStore } from "../session.js";
 import { type OnAsk, type ToolCallRequest, type ToolPolicy } from "../tool-policy.js";
 import { type ToolResultStore } from "../tool-result-store.js";
-import type { RunnerDeps, RuntimeCaps, TaskSpec } from "../types.js";
+import type { RunnerDeps, RuntimeCaps, ShellGateDoctrine, TaskSpec } from "../types.js";
 import type { CwdRef } from "../../tools/fs/fs-shared.js";
 import { type ContentAskBinding } from "./content-ask-bindings.js";
 import type { AskLane, ParkAsk, Prepared, SuspendSaga } from "./contracts.js";
@@ -108,12 +108,11 @@ export interface PrepareParkAskInput {
     maxSuspends: number;
     /** borrowed-mutable — the run-scoped remote-lifecycle failure log. Writer here: a refused `suspendVM` (`push`). */
     remoteEnvFailures: Prepared["remoteEnvFailures"];
-    /** borrowed-readonly — whether Bash is coarsely shell-gated (the risk descriptor's `shellGated`). */
-    shellGatedBash: boolean;
-    /** borrowed-readonly — whether Monitor is coarsely shell-gated (same). */
-    shellGatedMonitor: boolean;
+    /** borrowed-readonly — the shell-seat provenance set: the shell-running tools whose tier is the engine's shell seat's, not a
+     *  deployment mark (the risk descriptor's `shellGated` is the gated tool's membership). */
+    shellGatedTools: ReadonlySet<string>;
     /** borrowed-readonly — the effective shell-gate doctrine persisted on the descriptor. */
-    effectiveShellGate: "off" | "classify" | "always";
+    effectiveShellGate: ShellGateDoctrine;
     /** borrowed-readonly — the EFFECTIVE durable-approval opt-in (the caller's, or the synthesized mandate scope): picks the
      *  gate kind, the scope and the ttl. */
     durableApproval: TaskSpec["durableApproval"];

package/dist/core/runner/prepare-park-ask.js

@@ -22,7 +22,7 @@ class ParkRefusal extends Error {
     }
 }
 export function prepareParkAsk(input) {
-    const { askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedBash, shellGatedMonitor, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef } = input;
+    const { askLane, saga, spec, deps, sessionId, checkpointStore, toolRosterDeltas, parkLaneArmed, contentAskRoutable, liveQuestionFace, mountedQuestionTool, contentAskBindings, lateStrandedAnswers, discloseStrandedAnswers, onAsk, runtimeCaps, inheritedUnavailableAsks, basePolicyForResumeEdit, budgetSnapshot, handsCwdRef, offloadStore, ownedEnv, incompleteSuspendAdapter, session, sessions, suspendChainBase, maxSuspends, remoteEnvFailures, shellGatedTools, effectiveShellGate, durableApproval, priorLedger, liveSpendRef, resourceTotal, faceCheckpointState, f012CheckpointState, orgAdmissionCheckpointState, ruleOffersOf, now, humanReviewRef, abortController, harness, pausedRef } = input;
     if (askLane === undefined || saga === undefined)
         return { parkAsk: undefined };
     const { composedCallSignal, approvalPreviewOf } = askLane;
@@ -232,8 +232,8 @@ export function prepareParkAsk(input) {
                     ...(shadowedRule !== undefined ? { shadowedRule } : {}),
                     ...(probeReason !== undefined ? { probeReason } : {}),
                     ...(probeCause !== undefined ? { probeCause } : {}),
-                    shellGated: (req.toolName === "Bash" && shellGatedBash) || (req.toolName === "Monitor" && shellGatedMonitor),
-                    ...(effectiveShellGate !== "off" ? { shellGateDoctrine: effectiveShellGate } : {}),
+                    shellGated: shellGatedTools.has(req.toolName),
+                    shellGateDoctrine: effectiveShellGate,
                 });
                 gate =
                     safety !== undefined || realApproval !== undefined

package/dist/core/runner/prepare-policy-chain.d.ts

@@ -78,8 +78,8 @@ export interface PreparePolicyChainInput {
     /** borrowed-readonly — the caller tools' names, the first-await snapshot (the sandbox boundary predicate: a caller tool
      *  is never contained by the hand tools' env). */
     ownToolNames: ReadonlySet<string>;
-    /** borrowed-readonly — whether the shell tool is under an operator `shellGate:"always"` (the offer factory's mandate term). */
-    shellGatedBash: boolean;
+    /** borrowed-readonly — the shell-seat provenance set (the offer factory's `shellGated` mandate term, read per call). */
+    shellGatedTools: ReadonlySet<string>;
     /** borrowed-readonly — the tracked-cwd seat, read per call by the lanes and the offer factory (never written here). */
     handsCwdRef: CwdRef | undefined;
     /** borrowed-readonly — the compiled read-deny judge, or undefined (the offer factory's directory negative control). */

package/dist/core/runner/prepare-policy-chain.js

@@ -5,7 +5,7 @@ import { resolveCheckpointStore } from "../checkpoint-store.js";
 import { cloneObserverInput, resolveHookTimeoutMs } from "../hooks.js";
 import { isNamespacedCoveringRuleName, namespacedRuleNameCovers } from "../permission-rules.js";
 import { isIsolated } from "../remote-env.js";
-import { askApproverIdentity, checkToolPolicyProjection, combinePolicies, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, isLiveApproverSeat, resolveAsk, toolPolicyNameSets } from "../tool-policy.js";
+import { askApproverIdentity, carryEngineAttestations, carryPrecedingSettlement, checkToolPolicyProjection, combinePolicies, createTranscriptIntegrityPolicy, createUnverifiableDeletePolicy, isLiveApproverSeat, resolveAsk, toolPolicyNameSets } from "../tool-policy.js";
 import { RETIRED_TOOL_NAMES } from "../tool-name-aliases.js";
 import { NAMESPACED_NAME_SHAPES, protocolOf } from "../protocol-table.js";
 import { emitTrace } from "../trace.js";
@@ -16,7 +16,7 @@ import { askGrantShapeOf } from "./inherited-ask-grants.js";
 import { createPermissionRuleLanes, inheritedAskRuleEvidence, createRuleOffersOf } from "./permission-rule-lanes.js";
 import { createSessionRulePolicy } from "./session-rule-policy.js";
 export async function preparePolicyChain(input) {
-    const { spec, deps, internals, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, lockedPreflight, tools, harnessTools, toolEffects, egressTools, irreversibilityTier, axisExplicitNegatives, ownToolNames, shellGatedBash, handsCwdRef, readDenyMatcher, questionToolMounted, runtimeCaps, inheritedAncestorRules, inheritedParentConstraints, seedInheritedGate, hasSkillManifest, skillScope, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, autoModeDecider, stopForDenialLimit, delegation, abortController, now, ownSessionRulesRef } = input;
+    const { spec, deps, internals, sessionId, runId, hostTaskId, taskRootFinal, executionEnv, lockedPreflight, tools, harnessTools, toolEffects, egressTools, irreversibilityTier, axisExplicitNegatives, ownToolNames, shellGatedTools, handsCwdRef, readDenyMatcher, questionToolMounted, runtimeCaps, inheritedAncestorRules, inheritedParentConstraints, seedInheritedGate, hasSkillManifest, skillScope, frozenOnAsk, hookEnvSource, notifyOwnHookCrash, autoModeDecider, stopForDenialLimit, delegation, abortController, now, ownSessionRulesRef } = input;
     const policy = lockedPreflight.toolPolicy;
     const auditPolicyNames = (auditee) => {
         const nameGroups = toolPolicyNameSets(auditee);
@@ -265,7 +265,7 @@ export async function preparePolicyChain(input) {
         localOwnerDeclared: deps.localOwnerRules === true,
         egressTools,
         irreversibilityTier,
-        shellGatedBash,
+        shellGatedTools,
         taskRoot: taskRootFinal,
         cwdRef: handsCwdRef,
         deniesDirectoryRead: readDenyMatcher !== undefined ? (d) => readDenyMatcher.matchPath(d) !== null : undefined,
@@ -557,7 +557,10 @@ export async function preparePolicyChain(input) {
                     for (const layer of recheckLayers) {
                         const d = await layer.check(finalReq, signal);
                         if (d.action === "deny") {
-                            return { ...d, updatedInput: decision.updatedInput };
+                            const carried = { ...d, updatedInput: decision.updatedInput };
+                            carryEngineAttestations(d, carried);
+                            carryPrecedingSettlement(decision, carried);
+                            return carried;
                         }
                         if (d.updatedInput !== undefined) {
                             return {

package/dist/core/runner/prepare-prompt-inputs.d.ts

@@ -28,6 +28,7 @@ import type { MaterializedMcp } from "../mcp.js";
 import type { ResolvedRole } from "../roles.js";
 import type { RunnerDeps, TaskSpec } from "../types.js";
 import type { PrepareResume, PromptFeatureFlags, RunInternals, ToolFaceSnapshot } from "./contracts.js";
+import type { AdvertisedWritableDirs } from "./advertised-writable-dirs.js";
 import { type GitStatusLaneRef } from "./git-status-frame.js";
 export interface PreparePromptInputsInput {
     /** borrowed-readonly — the REBOUND spec (`spec′`). Read: `promptProvider`, `hooks` (flag), `systemPrompt`
@@ -90,6 +91,9 @@ export interface PreparePromptInputsInput {
     additionalRootsCanonical: readonly string[];
     /** borrowed-readonly — the canonical extra read-only roots (copied into the env facts). */
     additionalReadRootsCanonical: readonly string[];
+    /** borrowed-readonly — #691: the advertised-writable-directory seat (hands only). The scratchpad section is
+     *  rendered only when the seat did not SKIP the scratchpad — a directory the fence refused is not advertised. */
+    advertisedWritableDirs?: AdvertisedWritableDirs;
     /** borrowed-readonly — the acquired session's id (operator-line context). */
     sessionId: string;
 }

package/dist/core/runner/prepare-prompt-inputs.js

@@ -4,7 +4,7 @@ import { probeGitStatusLane } from "./git-status-frame.js";
 import { fenceMcpServerInstructions } from "./turn-attachments.js";
 const ULTRA_REASONING_TIERS = new Set(["xhigh", "max"]);
 export async function preparePromptInputs(input) {
-    const { spec, deps, failClosedReason, lockedPreflight, selfOrchestrationActive, executionEnv, reminderMark, resolvedReadFace, toolFaceSnapshot, promptProfile, fableMitigations, internals, thinking, ownedEnv, delegation, resolvedRole, mcp, model, externalContentTargetActive, resume, handsEnabled, taskRootFinal, additionalRootsCanonical, additionalReadRootsCanonical, sessionId } = input;
+    const { spec, deps, failClosedReason, lockedPreflight, selfOrchestrationActive, executionEnv, reminderMark, resolvedReadFace, toolFaceSnapshot, promptProfile, fableMitigations, internals, thinking, ownedEnv, delegation, resolvedRole, mcp, model, externalContentTargetActive, resume, handsEnabled, taskRootFinal, additionalRootsCanonical, additionalReadRootsCanonical, sessionId, advertisedWritableDirs } = input;
     const provider = spec.promptProvider ?? deps.promptProvider ?? defaultPromptProvider;
     const promptPolicyEnabled = Boolean(lockedPreflight.toolPolicy);
     const promptHooks = spec.hooks ?? deps.hooks;
@@ -51,7 +51,7 @@ export async function preparePromptInputs(input) {
         envFacts.sandboxPkgSource = spec.envFacts.pkgSource;
     if (spec.envFacts?.egress === "none" || spec.envFacts?.egress === "allowlist" || spec.envFacts?.egress === "full")
         envFacts.sandboxEgress = spec.envFacts.egress;
-    if (spec.envFacts?.scratchpadDir)
+    if (spec.envFacts?.scratchpadDir && advertisedWritableDirs?.verdictOf("scratchpad") !== "skipped")
         envFacts.scratchpadDir = spec.envFacts.scratchpadDir;
     if (externalContentTargetActive)
         envFacts.externalContentTarget = true;