@sema-agent/core 7.12.0 → 7.14.0

package/dist/core/runner/prepare-caps-and-workflow.d.ts

@@ -25,28 +25,33 @@ import type { PromptEpochArtifact } from "../../prompt-assembly/artifact.js";
 import { type WorkflowSizeGuideline } from "../../orchestration/workflow-size-guideline.js";
 import { type AutoModeArmingRecipe } from "../auto-mode-arming.js";
 import { type AutoModeDecider, type AutoModeDenialTracker } from "../auto-mode.js";
+import { type CheckpointSeat } from "../checkpoint-seat.js";
 import { type ComplianceCapability } from "../compliance.js";
 import type { LockedPreflight } from "../locked-config.js";
 import type { StoredSession } from "../session.js";
 import type { OnAsk } from "../tool-policy.js";
 import type { RunnerDeps, RuntimeCaps, TaskEvent, TaskSpec, ToolExecuteContext } from "../types.js";
-import type { AutoModeArmReason } from "../wiring-manifest.js";
+import type { AutoModeArmFact } from "../wiring-manifest.js";
+import type { AssertAllKeysHandled } from "../ask-origin.js";
 import type { ReadFace } from "../../tools/fs/index.js";
 import type { InheritedGate, Prepared, RunInternals, RunnerSelfSeat, ToolFaceSnapshot } from "./contracts.js";
 import { type BlockedRef } from "./synthetic-tools.js";
 import { RosterBuilder } from "../tool-roster.js";
 export interface PrepareCapsAndWorkflowInput {
     /** borrowed-readonly — the REBOUND spec, whole: the roster map reads `tools`; the mounts read `enableBlockedReport`,
-     *  `enablePlanMode`, `interactiveTools`, `checkpointStore`; the caps/compliance stations read `principal`, `selfOrchestration`,
+     *  `enablePlanMode`, `interactiveTools`; the caps/compliance stations read `principal`, `selfOrchestration`,
      *  `enableFork`, `getApiKeyAndHeaders`; the Workflow mount forwards `oneShot`, `handsReadOnly`, `interactiveTools`. The
      *  self-orchestration predicate takes the whole spec. Never mutated. */
     spec: TaskSpec;
     /** borrowed-readonly — the deployment seats, whole: `runtimeCapsResolver`, `compliancePostureResolver`, `onError`, `onNotice`,
-     *  `autoMode`, `brain`, `models`, `checkpointStore` (the plan-pair face), and the Workflow mount's dozen deps (`workflowScriptRunner`,
+     *  `autoMode`, `brain`, `models`, and the Workflow mount's dozen deps (`workflowScriptRunner`,
      *  `workflowGovernanceBaseline`, `workflowRunStore`, `workflowJournalStore`, `workflowScriptStore`, `builtinWorkflows`,
      *  `onWorkflowAgentSpawn`, `workflowCompletionNotifier`, `workflowLimits`, `agents`, `builtinAgents`, `onBackgroundChildEvent`).
      *  The self-orchestration predicate takes the whole record. */
     deps: RunnerDeps;
+    /** borrowed-readonly — the seat this run hands its children (`checkpointSeatOf`, minted once by the driver right after the
+     *  config doors): the plan-pair face reads the store it names, the Workflow mount hands the seat itself to its children. */
+    checkpointSeat: CheckpointSeat | undefined;
     /** borrowed-readonly — the trusted spawn-side channel; the Workflow mount forwards `rootSessionId`, `placementRoot`,
      *  `onTaskNotification`, `workflowDepth`, and the capture-floor getter reads `memoryCaptureAncestors`. */
     internals: Pick<RunInternals, "rootSessionId" | "placementRoot" | "onTaskNotification" | "workflowDepth" | "memoryCaptureAncestors" | "workflowParkedResume"> | undefined;
@@ -145,7 +150,8 @@ export interface PrepareCapsAndWorkflowResult {
     /** owned — the observers grant (`allowObservers === true`, explicit opt-in). */
     observersActive: boolean;
     /** owned — the arming outcome as a closed reason (the manifest's auto-mode face). */
-    autoModeArmReason: AutoModeArmReason;
+    /** #529 / #692 C-d — the leg's auto-mode arming fact (`armed` ⇔ `reason === "armed"`; `deniedSource` only beside a STATED `denied`). */
+    autoModeArmReason: AutoModeArmFact;
     /** owned — the armed classifier, or undefined when any arming arm failed. */
     autoModeDecider: AutoModeDecider | undefined;
     /** owned — the denial tracker built beside the decider (same face, same arming). */
@@ -162,5 +168,29 @@ export interface PrepareCapsAndWorkflowResult {
         current: () => WorkflowSizeGuideline;
     } | undefined;
 }
+/**
+ * The resolved-caps value screen (the caps-side twin of `refuseInvalidAutoModeSeat`): the arming arm reads
+ * `autoMode !== false`, so a resolver that returns a MARSHALLED value — a non-boolean member (`"false"`,
+ * `0`, `null`) or a non-record container (`false`, `"false"`, `[]`; the resolver is an HTTP-backed seam the
+ * type system does not validate at runtime) — would pass a value meant as a denial straight into arming.
+ * Either shape is treated as a disclosed resolver fault: announced through onError (phase config), and
+ * coined fail-closed — a bad MEMBER to `autoMode:false` (the rest of the record kept), a bad CONTAINER to
+ * the same degrade object the resolver-throw arm uses (every `!== false`-gated cap denied), with
+ * `faulted` raised so the posture-keyed consumers read it as an outage, not as a verdict. `undefined`, or
+ * a record whose `autoMode` is `undefined`/`true`/`false`, passes untouched (byte-identical).
+ */
+/** The supported capability keys, fenced total over {@link RuntimeCaps}: a key added to the type without a row here
+ *  is a red build, so the snapshot below can never silently drop a new restriction. */
+declare const RUNTIME_CAP_KEYS: {
+    readonly allowWorkflows: true;
+    readonly allowFork: true;
+    readonly allowObservers: true;
+    readonly forceDurableGate: true;
+    readonly autoMode: true;
+    readonly autoModeDenySource: true;
+    readonly allowMemoryOptOut: true;
+};
+export type RuntimeCapKeysCoverEveryCap = AssertAllKeysHandled<Exclude<keyof RuntimeCaps, keyof typeof RUNTIME_CAP_KEYS>>;
 /** The M4 phase body — prepareTask's caps-and-workflow stretch, verbatim (see the module header). */
 export declare function prepareCapsAndWorkflow(input: PrepareCapsAndWorkflowInput): Promise<PrepareCapsAndWorkflowResult>;
+export {};

package/dist/core/runner/prepare-caps-and-workflow.js

@@ -10,7 +10,7 @@ import { autoModeArmingRecipeOf } from "../auto-mode-arming.js";
 import { AUTO_MODE_CLASSIFIER_LOW_REASONING_BUDGET_TOKENS, AUTO_MODE_CLASSIFIER_MAX_TOKENS } from "../auto-mode-defaults.js";
 import { buildAutoModePrompt, renderAutoModeAction, renderAutoModeWindow } from "../auto-mode-prompt.js";
 import { createAutoModeDecider, createAutoModeDenialTracker } from "../auto-mode.js";
-import { resolveCheckpointStore } from "../checkpoint-store.js";
+import { checkpointStoreOfSeat } from "../checkpoint-seat.js";
 import { COMPLIANCE_CAPABILITIES, WEB_FETCH_TOOL_NAME, resolveComplianceDenies } from "../compliance.js";
 import { createPresentPlanTool, createEnterPlanModeTool } from "../present-plan-tool.js";
 import { resolveTaskModel } from "../roles.js";
@@ -19,6 +19,7 @@ import { defaultTaskRegistry } from "../task-registry.js";
 import { emitTrace } from "../trace.js";
 import { defineTool, isDefineToolProduct, rebindDefineToolCtx } from "../tools.js";
 const MOUNT_REMEDY = "author it as a plain-object ToolSpec (own `name` and `execute`), hand the defineTool product itself, or wrap a product through the supported wrapper form (a fresh object re-stamped with `stampDefineToolBrand` whose rebind re-wraps the rebound product)";
+import { AUTO_MODE_DENY_SOURCES, isAutoModeDenySource } from "../runtime-caps.js";
 import { derivedRouteFallsBack } from "./derived-route-fallback.js";
 import { REPORT_FINDINGS_TOOL_NAME, createReportBlockedTool, createReportFindingsTool } from "./synthetic-tools.js";
 function classifierReplyText(reply) {
@@ -42,6 +43,24 @@ function assembleParentCaptureState(o, i, ctl, ancestors) {
     });
     return o instanceof Promise || i instanceof Promise ? Promise.all([o, i]).then(([ov, iv]) => build(ov, iv)) : build(o, i);
 }
+const RUNTIME_CAP_KEYS = {
+    allowWorkflows: true,
+    allowFork: true,
+    allowObservers: true,
+    forceDurableGate: true,
+    autoMode: true,
+    autoModeDenySource: true,
+    allowMemoryOptOut: true,
+};
+function snapshotRuntimeCaps(record) {
+    const out = {};
+    for (const key of Object.keys(RUNTIME_CAP_KEYS)) {
+        const v = record[key];
+        if (v !== undefined)
+            out[key] = v;
+    }
+    return out;
+}
 function screenAutoModeCap(caps, onError, sessionId) {
     if (caps === undefined)
         return { caps, faulted: false };
@@ -49,7 +68,20 @@ function screenAutoModeCap(caps, onError, sessionId) {
         onError?.(new Error(`runtimeCapsResolver returned a non-record value (${JSON.stringify(caps)}) — read as a resolver fault: every per-principal capability is DENIED for this run (auto mode is not armed; asks flow the original chain). Return a RuntimeCaps object or undefined.`), { phase: "config", sessionId });
         return { caps: { allowWorkflows: false, allowFork: false, autoMode: false }, faulted: true };
     }
-    const record = caps;
+    let record;
+    try {
+        record = snapshotRuntimeCaps(caps);
+    }
+    catch (err) {
+        onError?.(new Error(`runtimeCapsResolver's record threw while being read (${err instanceof Error ? err.message : String(err)}) — read as a resolver fault: every per-principal capability is DENIED for this run (auto mode is not armed; asks flow the original chain).`), { phase: "config", sessionId });
+        return { caps: { allowWorkflows: false, allowFork: false, autoMode: false }, faulted: true };
+    }
+    const { autoMode, autoModeDenySource } = record;
+    if (autoModeDenySource !== undefined && (!isAutoModeDenySource(autoModeDenySource) || autoMode !== false)) {
+        onError?.(new Error(`runtimeCapsResolver returned autoModeDenySource=${JSON.stringify(autoModeDenySource)} beside autoMode=${JSON.stringify(autoMode)} — read as a resolver fault: auto mode is DENIED for this run (the classifier is not armed; asks flow the original chain). Name a source only beside autoMode:false, and only one of ${AUTO_MODE_DENY_SOURCES.join("|")}.`), { phase: "config", sessionId });
+        const { autoModeDenySource: _refused, ...rest } = record;
+        return { caps: { ...rest, autoMode: false }, faulted: true };
+    }
     if (record.autoMode === undefined || typeof record.autoMode === "boolean")
         return { caps: record, faulted: false };
     onError?.(new Error(`runtimeCapsResolver returned a non-boolean autoMode (${JSON.stringify(record.autoMode)}) — read as a resolver fault: auto mode is DENIED for this run (the classifier is not armed; asks flow the original chain). Return true, false, or omit the key.`), { phase: "config", sessionId });
@@ -67,17 +99,20 @@ function mintPersistedArming(am, laneRule, classifierSystemPrompt, onError, sess
     }
     return arming;
 }
-function autoModeArmReasonOf(intent, facePresent, capsAutoMode, capsFaulted) {
+function autoModeArmReasonOf(intent, facePresent, caps, capsFaulted) {
     if (!intent)
-        return "no_intent";
+        return { armed: false, reason: "no_intent" };
     if (!facePresent)
-        return "no_face";
-    if (capsAutoMode === false)
-        return capsFaulted ? "resolver_fault" : "denied";
-    return "armed";
+        return { armed: false, reason: "no_face" };
+    if (caps?.autoMode === false) {
+        if (capsFaulted)
+            return { armed: false, reason: "resolver_fault" };
+        return { armed: false, reason: "denied", ...(caps.autoModeDenySource !== undefined ? { deniedSource: caps.autoModeDenySource } : {}) };
+    }
+    return { armed: true, reason: "armed" };
 }
 export async function prepareCapsAndWorkflow(input) {
-    const { spec, deps, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, carrierReadFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf } = input;
+    const { spec, deps, checkpointSeat, internals, session, sessionId, runId, hostTaskId, taskScope, taskRootFinal, model, thinking, lockedPreflight, toolEffects, toolFaceSnapshot, promptProfile, resolvedInteractionPosture, harnessRef, frozenOnAsk, carrierReadFace, forwardEvent, inheritedGateForChildren, enrichSpecToolCtx, maybeOffload, requestReview, enterPlanMode, autoModeIntent, peerLaneActive, peerSendMessageBuiltIn, runnerSelf } = input;
     const roster = new RosterBuilder(toolEffects);
     for (const t of spec.tools ?? []) {
         const mounted = mountCallerTool(t);
@@ -112,7 +147,7 @@ export async function prepareCapsAndWorkflow(input) {
         roster.mount(createReportFindingsTool(), { source: "builtin", mountedBy: "always" });
     }
     if (spec.enablePlanMode === true && spec.interactiveTools !== false) {
-        const planReviewFace = resolveCheckpointStore(spec, deps) !== undefined;
+        const planReviewFace = checkpointStoreOfSeat(checkpointSeat) !== undefined;
         if (spec.interactiveTools === true || planReviewFace) {
             roster.mount(defineTool(createPresentPlanTool(requestReview)), { source: "builtin", mountedBy: "optional" });
             if (planReviewFace) {
@@ -173,7 +208,7 @@ export async function prepareCapsAndWorkflow(input) {
     let autoModeDecider;
     let autoModeDenialTracking;
     let autoModeArming;
-    const autoModeArmReason = autoModeArmReasonOf(autoModeIntent, deps.autoMode !== undefined, runtimeCaps?.autoMode, runtimeCapsFaulted);
+    const autoModeArmReason = autoModeArmReasonOf(autoModeIntent, deps.autoMode !== undefined, runtimeCaps, runtimeCapsFaulted);
     if (autoModeIntent && deps.autoMode !== undefined && runtimeCaps?.autoMode !== false) {
         const am = deps.autoMode;
         let classifierModel;
@@ -297,7 +332,7 @@ export async function prepareCapsAndWorkflow(input) {
             },
             ...(spec.handsReadOnly === true ? { parentHandsReadOnly: true } : {}), ...(spec.interactiveTools === false ? { parentInteractiveTools: false } : {}),
             onNotice: deps.onNotice,
-            parentCheckpointStoreDisabled: spec.checkpointStore === "disabled",
+            ...(checkpointSeat !== undefined ? { parentCheckpointStore: checkpointSeat } : {}),
             parentCenterArtifactDigest: () => input.centerAdoption()?.artifact.artifactDigest,
             parentCenterSourceRevision: () => input.centerAdoption()?.sourceRevision,
             ...(forwardEvent ? { forwardEvent } : {}),

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

@@ -19,7 +19,7 @@
  * gate-machinery block, kept as the block's one guard here); the `tool_result` station keys off the hook record alone, as
  * it always did.
  *
- * Every station this file holds is a `denySource` / settlement WRITE site the decomposition's next slice maps onto one
+ * Every station this file holds is a `deniedBy` / settlement WRITE site the decomposition's next slice maps onto one
  * gate outcome; nothing here changes a word, a source or an order — the stations are moved, not re-adjudicated.
  */
 import type { AgentHarness, AgentTool } from "../../internal/harness.js";

package/dist/core/runner/prepare-hands-readface.d.ts

@@ -3,6 +3,7 @@ import { type ReadFileState } from "../../tools/fs/safety.js";
 import type { RunnerDeps, TaskSpec } from "../types.js";
 import type { Model } from "../../internal/llm.js";
 import type { AgentTool, ExecutionEnv, WorkspaceState } from "../../internal/harness.js";
+import type { AdvertisedWritableDirs } from "./advertised-writable-dirs.js";
 import type { StoredSession } from "../session.js";
 import type { IrreversibilityTier, PrepareResume, ReversibilityProbes, RunInternals, ToolFaceSnapshot } from "./contracts.js";
 import { RosterBuilder } from "../tool-roster.js";
@@ -161,13 +162,18 @@ export interface PrepareHandsReadFaceInput {
      *  when no file restore ran. Fail-closed by construction — dropping a read record only ever
      *  produces refusals. */
     restoredFilePaths?: readonly string[];
-    /** borrowed-readonly — (ref cell; the REF itself is never replaced) design/138 S2-C late-bound memory
-     *  write gate: the band's beforeWrite closure reads `.current` call-time; prepareMemory (driver,
-     *  after this phase) installs the gate — the one writer; this phase only reads. Declared in the driver because the SAME ref feeds
-     *  prepareMemory. */
+    /** borrowed-readonly — (ref cell; the REF itself is never replaced) design/138 S2-C memory write gate:
+     *  the band's beforeWrite closure reads `.current` call-time; prepareMemory (driver, BEFORE this phase
+     *  since #691 — the memory root must be known before the toolkit compiles) installs the gate — the one
+     *  writer; this phase only reads. Declared in the driver because the SAME ref feeds prepareMemory. */
     memoryWriteGateRef: {
         current?: BeforeWriteHook;
     };
+    /** borrowed-mutable — #691: the advertised-writable-directory seat (see its module header for the one
+     *  rule). Present on the hands leg only (a fence exists). The memory phase, which runs BEFORE this one,
+     *  has already admitted its write root through it; this phase admits the deployment's scratchpad and
+     *  folds `roots` into the write-capable containment allowlist before the toolkit compiles. */
+    advertisedWritableDirs?: AdvertisedWritableDirs;
     /** borrowed-readonly — the driver's per-tool offload wrapper (design/158 posture + policy); the
      *  band rides through it exactly as caller/MCP tools do. */
     firstPartyOffload: (tool: AgentTool) => AgentTool;

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

@@ -124,7 +124,7 @@ export function resolveHandsLessReadFace(input) {
 }
 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");
@@ -178,19 +178,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));

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

@@ -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

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,
     };
 }