@sema-agent/core 7.31.0 → 7.32.0

package/dist/core/background-shell.d.ts

@@ -111,6 +111,19 @@ export interface BackgroundShellCapability {
     pollBackground(shellId: BackgroundShellId): Promise<Result<BackgroundPoll, BackgroundShellError>>;
     /** 杀一个后台进程(幂等:杀已死的是 no-op,返回 ok)。`shellId` 同 {@link pollBackground} 的越界校验。 */
     killBackground(shellId: BackgroundShellId): Promise<Result<void, BackgroundShellError>>;
+    /**
+     * OPTIONAL — the SYNCHRONOUS hard kill for an exit boundary with no later tick, where a ladder-style
+     * {@link killBackground} (TERM, then a timer-driven KILL) never finishes a shell that ignores SIGTERM.
+     * Contract (docs/background-process-lifetime.md): complete the kill before returning — POSIX one
+     * `kill(-pgid, SIGKILL)` over the shell's process group (an env with no synchronous hard kill, e.g. win32,
+     * answers `no_pgid` and the registry falls back to the ordinary kill); no TERM, no timer,
+     * no await; never signal a pid the env cannot prove is still its own; never throw; idempotent; the pid never
+     * leaves the env. Outcomes: `killed` (delivered now), `already_gone` (exited, or this seat already delivered
+     * its kill, or the id is not its shell any more), `no_pgid` (no synchronous kill landed — nothing host-local
+     * to signal, or the signal was refused; nothing claimed, retryable). Without this seat the registry's hard
+     * face reads `no_pgid` for every shell.
+     */
+    killBackgroundNow?(shellId: BackgroundShellId): BackgroundHardKillOutcome;
     /**
      * 杀掉并清理**本 env 的所有**后台进程。Runner 在每条退出路径调:finish/abort/throw 在 run-loop tail finally,**suspend/
      * review 必须在 `suspendVM` 之前**(design/103 §3.7;detached job 不在 suspendVM in-flight 契约内,不能指望 adapter 隐式处理)。
@@ -125,6 +138,28 @@ export interface BackgroundShellCapability {
         except?: readonly BackgroundShellId[];
     }): Promise<void>;
 }
+/** The closed outcome set of {@link BackgroundShellCapability.killBackgroundNow}. */
+export type BackgroundHardKillOutcome = "killed" | "already_gone" | "no_pgid";
+/** The retain lanes a face can see (absent = not declared). */
+export interface BackgroundRetainLanes {
+    /** The env's own declaration: `backgroundCapabilities.retainBackgroundProcesses`. */
+    readonly env?: boolean;
+    /** The task's declaration: `TaskSpec.retainBackgroundProcesses` of the run whose face is asking. */
+    readonly task?: boolean;
+    /** The row's `retained` mark (stamped at registration; see the registry row). */
+    readonly marked?: boolean;
+    /** The owning ISOLATED env is destroyed with this run: retention there is illusory; overrides every lane. */
+    readonly envDying?: boolean;
+}
+/**
+ * THE retain predicate — "is this background process kept alive past the automatic reaps?" Every face that
+ * answers it calls this function (Bash description + receipts, Monitor receipt, the row stamp, teardown settle
+ * and dispose, park-only sweeps, session reap, the exit hard face, the listing). Any declared lane retains,
+ * unless the owning isolated env is being destroyed. Contract: docs/background-process-lifetime.md.
+ */
+export declare function retainsBackgroundProcesses(lanes: BackgroundRetainLanes): boolean;
+/** The env lane of {@link BackgroundRetainLanes}, read off an env (false for an env without the capability). */
+export declare function envDeclaresRetain(env: ExecutionEnv): boolean;
 /**
  * 结构 + 语义检测:`env` 是否暴露后台 shell 能力且声明 `supported:true`。挂载门控用此(对齐 `hasDestroy`)。
  *
@@ -156,3 +191,13 @@ export interface EnvSweepAttribution {
 export declare function sweepBackgroundShells(env: ExecutionEnv & BackgroundShellCapability, attribution: EnvSweepAttribution | undefined, opts?: {
     except?: readonly string[];
 }): Promise<void>;
+/**
+ * The park-only sweep (a durable park that does not pause the env), one entry point for every park lane:
+ * nothing is swept when this run's task or the env declares retain; otherwise every row already retained on
+ * this env (an earlier run's delivered service) is spared.
+ */
+export declare function sweepParkOnlyBackgroundShells(env: ExecutionEnv & BackgroundShellCapability, registry: EnvSweepAttribution & {
+    retainedShellIds(env: unknown): readonly string[];
+}, lanes: {
+    task: boolean;
+}): Promise<void>;

package/dist/core/background-shell.js

@@ -8,6 +8,13 @@ export class BackgroundShellError extends Error {
         this.name = "BackgroundShellError";
     }
 }
+export function retainsBackgroundProcesses(lanes) {
+    return (lanes.env === true || lanes.task === true || lanes.marked === true) && lanes.envDying !== true;
+}
+export function envDeclaresRetain(env) {
+    const caps = env.backgroundCapabilities;
+    return typeof caps === "object" && caps !== null && caps.retainBackgroundProcesses === true;
+}
 export function hasBackgroundShell(env) {
     const e = env;
     return (typeof e.spawnBackground === "function" &&
@@ -26,3 +33,9 @@ export async function sweepBackgroundShells(env, attribution, opts) {
     }
     await env.disposeBackgroundShells(opts?.except !== undefined ? { except: opts.except } : undefined);
 }
+export async function sweepParkOnlyBackgroundShells(env, registry, lanes) {
+    if (retainsBackgroundProcesses({ env: envDeclaresRetain(env), task: lanes.task }))
+        return;
+    const except = registry.retainedShellIds(env);
+    await sweepBackgroundShells(env, registry, except.length > 0 ? { except } : undefined);
+}

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

@@ -816,6 +816,9 @@ export type PendingAction = {
      *  when a person's rule also speaks — never a substitute for this one). Display metadata: no gate, CAS or
      *  resume path reads it. */
     mandated?: true;
+    /** The PARK twin of `AskRequest.mandate` (same derivation, same precedent): the table word the bit stands on,
+     *  present only when it is the whole reason. Written only as a member of the closed set. */
+    mandate?: import("./ask-origin.js").PersistedRuleMandate;
     /** The PARK twin of `AskRequest.denialLimitFallback`: present
      *  ⇔ this parked ask is the classifier DENIAL-LIMIT fallback, carrying the counts that tripped
      *  the bound. Its `autoDenyAfterMs` is ALWAYS `0` on a row: the window is a fact of the ask's
@@ -1947,6 +1950,8 @@ export interface CheckpointSummary {
      *  OMITTED (the {@link toolCallId} absence-shape contract), screened to the literal `true` — a pre-#1079 row
      *  reads absent (unreported). ECHO-ONLY; nothing gates on it. */
     mandated?: true;
+    /** The row's `PendingAction.tool_approval.mandate`, echoed ONLY as a member of the closed set. ECHO-ONLY. */
+    mandate?: import("./ask-origin.js").PersistedRuleMandate;
     /** The row's `PendingAction.tool_approval.denialLimitFallback`, projected BESIDE the preview
      *  for the same one-call reason: a card that shows the fallback's counts and limit must not re-open
      *  the row to learn them (`autoDenyAfterMs` is `0` on every row — see the row member). Pure echo;

package/dist/core/checkpoint-store.js

@@ -3,7 +3,7 @@ import { uuidv7 } from "../internal/harness.js";
 import { PROBE_CAUSE_PATH_MAX, PROBE_REASON_MAX, inlineUntrusted, sanitizeUntrustedText } from "./untrusted-text.js";
 import { carriesBidiControls } from "./tool-policy.js";
 import { readDenialLimitFallback } from "./auto-mode.js";
-import { isAskOrigin, isRuleStoreUnreadable } from "./ask-origin.js";
+import { isAskOrigin, isPersistedRuleMandate, isRuleStoreUnreadable } from "./ask-origin.js";
 import { checkpointExecutionRecorded, executionRecordDisposition, ExecutionOutcomeConflictError, } from "./checkpoint-execution-record.js";
 import { renderUntrustedCommandText, stripFormatCharacters } from "./permission-rule-model.js";
 import { redactSecrets } from "./untrusted-egress.js";
@@ -305,7 +305,8 @@ export function summarizeCheckpoint(cp) {
         ...(() => {
             const origin = tool?.origin;
             const ruleStoreUnreadable = tool?.ruleStoreUnreadable;
-            return { ...(isAskOrigin(origin) ? { origin } : {}), ...(isRuleStoreUnreadable(ruleStoreUnreadable) ? { ruleStoreUnreadable } : {}) };
+            const mandate = tool?.mandate;
+            return { ...(isAskOrigin(origin) ? { origin } : {}), ...(isRuleStoreUnreadable(ruleStoreUnreadable) ? { ruleStoreUnreadable } : {}), ...(isPersistedRuleMandate(mandate) ? { mandate } : {}) };
         })(),
         ...(hasBidi ? { hasBidiControls: true } : {}),
     };

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

@@ -400,6 +400,15 @@ export interface EngineNotice {
      *    AFTER the loop's end is refused typed (`steering.not_running`, every verb alike) and mints
      *    nothing: the refusal itself is the loud answer.
      *
+     *  - `"approval.read_root_granted"` / `"approval.read_root_grant_rejected"` — an approver's `readRootGrant`
+     *    (`AskOutcome`). GRANTED: it equalled the card's `readRootCandidate.dir` beside `allow: true`; this run's READ
+     *    directories now include it (never the write roots; this run only); `detail: { dir, covers?, root, toolName,
+     *    toolCallId, sessionId, runId, taskId? }`, `root` = the canonical spelling held. REJECTED: nothing changed,
+     *    the verdict stands; `detail: { reason, offered?, requested?, …same ids }`, `reason` ∈ `on_refusal` |
+     *    `not_a_string` | `no_candidate` | `mismatch` | `unresolvable` | `resolves_elsewhere` | `admits_artifact_store`
+     *    (the directory contains the wired local artifact store, lies inside it or is it) | `no_read_roots`. Once per
+     *    answered ask. Audience `"user"`.
+     *
      *  - `"checkpoint.execution_outcome_unrecorded"` — the resumed leg's pending-call resolver disposed
      *    the decided action (executed it, delivered the refusal, or vetoed the person's yes) and filed
      *    the frame's record through `CheckpointStore.recordExecutionOutcome`, and the store answered

package/dist/core/gate-lanes.js

@@ -467,7 +467,7 @@ export async function runGateLanes(pass) {
             ...(d.action === "ask" && d.denialLimitFallback !== undefined ? { denialLimitFallback: unarmedWindow(d.denialLimitFallback) } : {}),
             ...(d.action === "ask" && d.origin !== undefined ? { origin: d.origin } : {}),
             ...(d.action === "ask" && d.ruleStoreUnreadable !== undefined ? { ruleStoreUnreadable: d.ruleStoreUnreadable } : {}),
-            ...(d.action === "ask" && d.mandated === true ? { mandated: true } : {}),
+            ...(d.action === "ask" && d.mandated === true ? { mandated: true, ...(d.mandate !== undefined ? { mandate: d.mandate } : {}) } : {}),
         });
         if (suspendAsk && pass.decision.action === "ask") {
             const parkArgs = [pass.req, pass.currentInput, safety, undefined, realApprovalOf(pass.decision), pass.decision.action === "ask" ? pass.decision.persistedRuleShadowed : undefined, pass.decision.action === "ask" ? pass.decision.decisionReason : undefined, pass.decision.action === "ask" ? pass.decision.probeReason : undefined, pass.decision.action === "ask" ? pass.decision.probeCause : undefined, pass.decision.action === "ask" ? pass.decision.segmentCoverage : undefined, pass.decision.action === "ask" ? pass.decision.matchedAskRule : undefined, pass.decision.action === "ask" ? pass.decision.probeMandated : undefined];

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

@@ -119,7 +119,7 @@ export type NoticeAudience = "user" | "operator";
  * the union's catalog ({@link EngineNotice.code}). The groups below say only which family a row joins,
  * so the catalog is not written a second time here and the two cannot drift.
  */
-export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.write_protection_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "route.response_model_mismatch", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed"];
+export declare const ENGINE_NOTICE_CODES: readonly ["config.autocompact_window_clamped", "config.env_timeout_discarded", "config.materialize_env_discarded", "config.models_swapped", "config.context_settings_swapped", "config.read_face_swapped", "config.read_face_deployment_clamped", "config.write_face_swapped", "config.write_face_deployment_clamped", "config.tool_model_gate_removed", "config.tool_model_gate_unknown_class", "config.tool_model_gate_env_invalid", "config.artifact_host_invalid", "config.task_root_not_canonical", "config.write_protection_target_view_absent", "config.write_protection_unresolved", "config.execution_env_capability_invalid", "config.tool_card_undeclared", "config.tool_face_undeclared", "config.tool_face_invalid", "config.forward_sink_failed", "config.durable_gate_unavailable", "config.peer_admission_out_of_range", "config.peer_lane_unmounted", "config.secret_env_scrubbed", "peer.inbound_disposition", "peer.held_settled", "peer.idle_subscription", "classifier.denial_limit", "classifier.fallback", "classifier.role_defaulted", "classifier.contract_broken", "checkpoint.execution_outcome_unrecorded", "delegation.transcript_integrity", "delegation.ask_unresolvable", "mcp.injection_dropped", "mcp.revocation_probe_failed", "mcp.server_redialed", "workflow.governance_key_stripped", "workflow.agent_option_ignored", "memory.session_polluted", "memory.harvest_quarantined", "memory.delegation_static_mark_waived", "memory.content_class_declared", "memory.hold_opened", "memory.hold_released", "memory.hold_disposed", "memory.consolidation_recommended", "memory.consolidation_committed", "memory.consolidation_conflict", "memory.consolidation_incomplete", "memory.consolidation_refused", "memory.consolidation_withheld", "memory.restore_withheld", "memory.project_scope_absent", "route.fallback_to_primary", "route.classifier_unroutable", "route.base_url_changed_key_unchanged", "route.response_model_mismatch", "task.user_steer_undrained", "task.user_followup_undrained", "steering.parked_input_blocked", "task.turn_interrupted", "task.halt_unconsumed", "task.late_approval", "task.interrupt_unconsumed", "approval.read_root_granted", "approval.read_root_grant_rejected", "memory.capture_opted_out", "memory.capture_optout_unpersisted", "skills.listing_truncated", "agents.listing_truncated", "tool_result.offload_put_failed"];
 /** A code this engine mints (see {@link ENGINE_NOTICE_CODES}). NOT the type of
  *  `EngineNotice.code`, which stays `string` — a host forwarding its own notices through the same
  *  sink is a supported shape, and narrowing that field would break it. */

package/dist/core/governance-codes.js

@@ -83,6 +83,7 @@ export const NON_GOVERNANCE_MEMORY_CODES = new Set([
     "memory.capture_optout_unpersisted",
     "memory.capture_optout_unavailable",
     "memory.capture_optout_sweep_failed",
+    "memory.target_outside_store",
 ]);
 export function governanceRetryClass(code) {
     if (Object.prototype.hasOwnProperty.call(GOVERNANCE_CODES, code)) {
@@ -168,6 +169,8 @@ export const ENGINE_NOTICE_CODES = [
     "task.halt_unconsumed",
     "task.late_approval",
     "task.interrupt_unconsumed",
+    "approval.read_root_granted",
+    "approval.read_root_grant_rejected",
     "memory.capture_opted_out",
     "memory.capture_optout_unpersisted",
     "skills.listing_truncated",
@@ -192,6 +195,8 @@ const NOTICE_AUDIENCE_TABLE = {
     "task.halt_unconsumed": "user",
     "task.late_approval": "user",
     "task.interrupt_unconsumed": "user",
+    "approval.read_root_granted": "user",
+    "approval.read_root_grant_rejected": "user",
     "config.durable_gate_unavailable": "user",
     "memory.capture_opted_out": "user",
     "memory.capture_optout_unpersisted": "user",

package/dist/core/hooks.d.ts

@@ -1714,6 +1714,8 @@ export interface AskCarry {
     /** The stamped mandate ({@link import("./tool-policy.js").AskRequest.mandated}) — the park site's
      *  rule-offer facts read it, so a parked mandated ask offers no rule, like the live card. */
     readonly mandated?: true;
+    /** The table word stamped beside it ({@link import("./tool-policy.js").AskRequest.mandate}), for the row's twin. */
+    readonly mandate?: import("./ask-origin.js").PersistedRuleMandate;
 }
 /** What a durable row persists of an {@link AskCarry}: the fallback member COPIED (the row never aliases
  *  the gate's object; its window is already `0` — the gate's carry mint is the one writer of that

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

@@ -833,6 +833,8 @@ export interface SessionMemoryStatus {
 export declare class MemoryEngine {
     private readonly backend;
     private readonly memoryDir;
+    /** {@link memoryDir}'s physical form as this engine first mounted it; every later mount compares, never re-resolves. */
+    private mountedRoot;
     private readonly controlDir;
     private readonly now;
     private readonly perScopeBudgetBytes;
@@ -1776,10 +1778,17 @@ export declare class MemoryEngine {
      * @returns the rejection to report, or `undefined` when the index is clean/absent.
      */
     private gateDerivedIndex;
+    /** The file backend's verdict at an act the engine itself performs on a store path ({@link
+     *  storeTargetEscape}): throws `memory.target_outside_store` when `path` would land outside `root`;
+     *  each caller's existing failure lane reports it. `root` is the mount's canonical root where a
+     *  handle exists, so a root re-pointed after the mount is judged against the one it mounted. */
+    private refuseOutsideStore;
     /** Projection write: reads the target to skip a no-op, then writes — the same check-then-use shape
      *  as the containment restores, so it takes the same no-follow write. A link at a projection path
      *  is never a supported layout (the harvest scan refuses symlinked entry files outright), and this
-     *  site already reports write failures by throwing, so ELOOP joins the failures it already had. */
+     *  site already reports write failures by throwing, so ELOOP joins the failures it already had. A
+     *  target whose directory resolves outside `root` (a directory on the path is a link) is refused
+     *  the same way, before anything is read or written ({@link storeTargetEscape}). */
     private writeIfChanged;
     /** Persist the canonical projection back to the session file (id minting / frontmatter completion).
      *  C-F6 (S2-0): called ONLY after the backend transaction committed — never ahead of the journal

package/dist/core/memory-engine/engine.js

@@ -17,7 +17,7 @@ import { landedUndecided, layerDigest, layerObservationLookup, readOnlyLayerCand
 import { markOriginClearanceTombstoned, openOriginClearance, readOriginClearances, settleOriginClearance } from "./origin-clearance.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, canonicalJsonStringify, captureErasureInput, erasureRequestInvalid, erasureSelectHash, scanEntryFiles, } from "./file-backend.js";
 import { assembleMemoryExportBundle, computeMemoryBundleHash, memoryBundleInvalid, } from "./export-bundle.js";
-import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, restoreContainedBaseline, readIndexRevs, writeIndexRevs, bumpScanFuse, scanFuseKey, canonicalize, adoptRootScopeLayout, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, markSessionPolluted, readSessionPollution, fileSessionCaptureRecordStore, recordRetrievedAccount, writeFileNoFollow, withPermissionRemedy, permissionRemedyOf, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, } from "./layout.js";
+import { QUARANTINE_DIR, SCAN_FUSE_THRESHOLD, quarantineAndTombstone, restoreContainedBaseline, readIndexRevs, writeIndexRevs, bumpScanFuse, scanFuseKey, canonicalize, landingPathOf, storeTargetEscape, TARGET_OUTSIDE_STORE, adoptRootScopeLayout, clearScanFuse, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, drainMemoryAnnouncements, enqueueMemoryAnnouncement, ensureDirExists, markSessionPolluted, readSessionPollution, fileSessionCaptureRecordStore, recordRetrievedAccount, writeFileNoFollow, withPermissionRemedy, permissionRemedyOf, readRetrievedAccount, registerScope, registeredScopes, resolveMemoryEngineRoot, scopeDirFor, appendChallengeEvents, appendLineageAudit, rebuildStrictControlPlaneLedger, isStrictControlPlaneLedgerCorrupt, CHALLENGE_LEDGER_MAX_EVENTS, adjudicateLineagePending, challengedEntryIds, clearLineageForEntries, discardLineagePending, lineageAccountOfEntry, lineageContributionsOfSession, lineageLatchedIds, promoteLineagePending, readChallengeEvents, readChallengedHistory, readLineageRecord, recordChallengedHistory, recordLineageCredential, reconcileLineage, readProjectionDebts, resolveChallengeEvent, settleProjectionDebts, stageLineagePending, stageProjectionDebts, } from "./layout.js";
 import { createSessionIncarnationSeat, recalledForAnyIdentity, recalledForIdentity, rememberForIdentity } from "./session-incarnation.js";
 import { scanMemoryFileName, scanMemoryWrite, scanRemediation } from "./scan.js";
 import { writableRootOf } from "./types.js";
@@ -310,6 +310,7 @@ const STALE_LEG_NOTE = "memory session account: this harvest belongs to an earli
 export class MemoryEngine {
     backend;
     memoryDir;
+    mountedRoot;
     controlDir;
     now;
     perScopeBudgetBytes;
@@ -427,7 +428,7 @@ export class MemoryEngine {
         }
         return this.backend.readCommittedShadow?.(id) ?? readSafe(join(this.controlDir, "shadow", `${id}.md`));
     }
-    async restoreReadOnlyLayers(candidates, report, selfLeg) {
+    async restoreReadOnlyLayers(candidates, report, selfLeg, root) {
         let writers;
         for (const c of candidates) {
             const text = readSafe(c.path);
@@ -450,6 +451,7 @@ export class MemoryEngine {
                 continue;
             }
             try {
+                this.refuseOutsideStore(root, c.path, "restoring the read-only layer file");
                 writeFileNoFollow(c.path, committed);
                 report.restored.push(c.relPath);
             }
@@ -755,6 +757,7 @@ export class MemoryEngine {
             const indexPath = join(writableRoot, MEMORY_INDEX_FILENAME);
             const baseline = handle.planeBaseline !== undefined ? handle.planeBaseline.index : handle.indexText;
             try {
+                this.refuseOutsideStore(handle.memoryDir, indexPath, "sweeping the index");
                 const first = existsSync(indexPath) ? readSafe(indexPath) : undefined;
                 if (first !== undefined && first !== baseline) {
                     const onDisk = readSafe(indexPath);
@@ -1088,6 +1091,7 @@ export class MemoryEngine {
                 if (kept.length === lines.length)
                     continue;
                 try {
+                    this.refuseOutsideStore(landingPathOf(this.memoryDir), indexPath, "rewriting the index");
                     writeFileNoFollow(indexPath, kept.join("\n"));
                 }
                 catch {
@@ -1409,6 +1413,13 @@ export class MemoryEngine {
     }
     async materializeCore(scopes, writeScope, opts, legSeat) {
         ensureDirExists(this.memoryDir);
+        const physicalRoot = landingPathOf(this.memoryDir);
+        this.mountedRoot ??= physicalRoot;
+        if (physicalRoot !== this.mountedRoot) {
+            const e = new Error(`${TARGET_OUTSIDE_STORE}: the memory dir ${this.memoryDir} now resolves to ${physicalRoot}, not ${this.mountedRoot} where this engine first mounted it — refused; open a new engine on the directory you mean`);
+            e.code = TARGET_OUTSIDE_STORE;
+            throw e;
+        }
         ensureDirExists(this.controlDir);
         await this.adoptLayoutBeforeMount(writeScope);
         const restricted = opts?.adoptionRestricted === true;
@@ -1593,6 +1604,7 @@ export class MemoryEngine {
         if (handle.writableRoot !== null)
             ensureDirExists(handle.writableRoot);
         const zeroCopy = this.backendPinnedRoot !== undefined && canonicalize(this.backendPinnedRoot) === canonicalize(this.memoryDir);
+        const projectionRoot = zeroCopy ? undefined : this.mountedRoot;
         for (const [scope, dir] of scopeDirs) {
             const scopeEntries = (byScope.get(scope) ?? []).slice();
             scopeEntries.sort((a, b) => (mtimeById.get(b.id) ?? 0) - (mtimeById.get(a.id) ?? 0));
@@ -1614,8 +1626,8 @@ export class MemoryEngine {
                 const { deleted: _stubDrop, ...stubFm } = entry.frontmatter;
                 const text = stub ? serializeEntryFile({ id: entry.id, frontmatter: stubFm, body: STUB_ARCHIVED_LINE }) : fullText;
                 const target = join(dir, `${entry.slug}.md`);
-                if (!zeroCopy)
-                    this.writeIfChanged(target, text);
+                if (projectionRoot !== undefined)
+                    this.writeIfChanged(target, text, projectionRoot);
                 const onDiskRev = stub ? revOfText(text, entry.id) : entry.rev;
                 const path = canonicalize(target);
                 handle.materialized.push({
@@ -2176,7 +2188,7 @@ export class MemoryEngine {
                 signalContainment((c) => (c.indexRolledBack = true));
             report.warnings.push(`memory harvest refused by an incident while this session is marked externally exposed — no entries were committed; instruction-form files were withheld and the derived index rolled back: ${inlineUntrusted(pollutedReason, 200)}`);
         };
-        await this.restoreReadOnlyLayers(readOnlyRestorable, report, handle.accountLeg);
+        await this.restoreReadOnlyLayers(readOnlyRestorable, report, handle.accountLeg, handle.memoryDir);
         const missingWritable = writable.filter((m) => !recordByPath.has(m.path) && !existsSync(m.path) && !presentIds.has(m.id));
         report.missing.push(...missingWritable.map((m) => m.relPath));
         if (writable.length > 0 && missingWritable.length / writable.length > MASS_DELETION_FUSE_RATIO) {
@@ -2203,6 +2215,7 @@ export class MemoryEngine {
             if (content === undefined)
                 continue;
             try {
+                this.refuseOutsideStore(handle.memoryDir, m.path, "restoring");
                 mkdirSync(dirname(m.path), { recursive: true });
                 writeFileNoFollow(m.path, content);
                 report.restored.push(m.relPath);
@@ -4818,6 +4831,7 @@ export class MemoryEngine {
         if (opts.write) {
             let wrote = false;
             try {
+                this.refuseOutsideStore(handle.memoryDir, indexPath, "writing the index");
                 mkdirSync(dirname(indexPath), { recursive: true });
                 if (readNoFollowSafe(indexPath) !== text)
                     writeFileNoFollow(indexPath, text);
@@ -4908,6 +4922,7 @@ export class MemoryEngine {
         }
         let cleared = false;
         try {
+            this.refuseOutsideStore(handle.memoryDir, indexPath, "clearing the index");
             writeFileNoFollow(indexPath, "");
             cleared = true;
         }
@@ -4927,7 +4942,16 @@ export class MemoryEngine {
             contained: cleared,
         };
     }
-    writeIfChanged(target, text) {
+    refuseOutsideStore(root, path, act) {
+        const escape = storeTargetEscape(root, path);
+        if (escape === undefined)
+            return;
+        const e = new Error(`${TARGET_OUTSIDE_STORE}: ${act} ${path} was refused — ${escape}; not performed`);
+        e.code = TARGET_OUTSIDE_STORE;
+        throw e;
+    }
+    writeIfChanged(target, text, root) {
+        this.refuseOutsideStore(root, target, "the projection write of");
         const current = readNoFollowSafe(target);
         if (current === text)
             return;

package/dist/core/memory-engine/file-backend.d.ts

@@ -353,6 +353,8 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  NEVER under {@link directoryRoot}, always on the config-root side even for an in-repo memory dir.
      *  The engine picks this up (like `directoryRoot`) so both sides share ONE control plane. */
     readonly controlPlaneRoot: string;
+    /** {@link directoryRoot}'s physical form at construction — the root every act on a store path is judged against. */
+    private readonly physicalRoot;
     /** Injected clock (opus 1.258 LOW: match the engine's `this.now` determinism discipline). */
     private readonly now;
     /** The construction-time incident sink (partition adoption, layout adoption on the standalone faces). */
@@ -679,6 +681,19 @@ export declare class FileMemoryEngineBackend implements MemoryBackend {
      *  §3.1 ⓪ (r5-①): "no lock" is ENOENT-only — a stat FAILURE folded into "nobody is committing"
      *  let a transient EIO run the unlocked recovery (and its staged sweep) over a live transaction. */
     private txnInFlight;
+    /**
+     * The act gate for store paths ({@link storeTargetEscape}) over `ops`' writes and deletes — shadow
+     * ops name control-plane files, not store paths. Refuses with `memory.target_outside_store` at the
+     * first op that would land outside the store, naming the op and where it resolves. Runs over a
+     * whole batch before its commit marker (no journal is written; a caller that staged files removes
+     * them) and per op at the act itself; past the marker a refusal keeps the journal, which replays
+     * once the path resolves inside the store again.
+     */
+    private refuseEscapingTargets;
+    /** At the head of every face (both recovery legs, the lock-free faces' layout seat, the adoption face):
+     *  the store root still resolves to the directory this backend opened. A root re-pointed since would
+     *  carry every read, adoption, sweep and restore — not only the journal's acts — into another directory. */
+    private assertRootIntact;
     /** Remove orphaned `.stage-*` files (a crash BEFORE the journal rename = clean rollback: nothing
      *  was committed, the staged tmps are litter). Dotfiles are invisible to entry scans regardless. */
     private sweepStagedFiles;

package/dist/core/memory-engine/file-backend.js

@@ -1,4 +1,4 @@
-import { existsSync, linkSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, openSync, fsyncSync, closeSync, utimesSync } from "node:fs";
+import { existsSync, fstatSync, linkSync, lstatSync, mkdirSync, readdirSync, readFileSync, renameSync, rmSync, statSync, openSync, fsyncSync, closeSync, utimesSync } from "node:fs";
 import { createHash, randomUUID } from "node:crypto";
 import { dirname, join, relative } from "node:path";
 import { jaccardDistance, termSet } from "../memory-vector.js";
@@ -8,7 +8,7 @@ import { ambiguousOriginRepresentation, committedDistilledOf, committedOriginOf,
 import { convertV1SidecarKeys } from "./delegation-settlement.js";
 import { layerObservationLookup, observedDivergenceNotice } from "./layer-observations.js";
 import { DEFAULT_MAX_ENTRY_DEPTH, MEMORY_INDEX_FILENAME, scanEntryFiles } from "./entry-scan.js";
-import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, CHALLENGES_FILE, IMPORT_RECEIPTS_DIR, LINEAGE_FILE, SESSION_POLLUTION_DIR, appendChallengeEvents, atomicWriteFileSync, quarantineAndTombstone, captureAndClearLineageForEntries, adoptRootScopeLayout, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, importLatchTxnId, importLineageCommitted, importSessionPollution, isContainedIn, permissionRemedyOf, withPermissionRemedy, lineageContributionsOfSession, listSessionPollution, readChallengeEvents, readLineageRecord, registerScope, registeredScopes, releaseImportLatch, layoutNeedsAdoption, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, scopeRegistryShape, stageImportLatch, writeAllSync, } from "./layout.js";
+import { ControlPlaneCorruptError, CURSORS_FILE, QUARANTINE_DIR, CHALLENGES_FILE, IMPORT_RECEIPTS_DIR, LINEAGE_FILE, SESSION_POLLUTION_DIR, appendChallengeEvents, atomicWriteFileSync, quarantineAndTombstone, captureAndClearLineageForEntries, adoptRootScopeLayout, adoptCanonicalKeyedControlDir, deriveControlPlaneDir, ensureDirExists, enqueueMemoryAnnouncement, importLatchTxnId, importLineageCommitted, importSessionPollution, isContainedIn, permissionRemedyOf, withPermissionRemedy, lineageContributionsOfSession, listSessionPollution, readChallengeEvents, readLineageRecord, registerScope, registeredScopes, releaseImportLatch, layoutNeedsAdoption, resolveMemoryEngineRoot, scopeDirFor, scopeDirName, scopeRegistryShape, stageImportLatch, landingPathOf, storeTargetEscape, TARGET_OUTSIDE_STORE, writeAllSync, } from "./layout.js";
 import { screenInboundEntries } from "./data-plane.js";
 import { scanMemoryFileName, scanMemoryWrite } from "./scan.js";
 import { thrownText } from "../thrown-value.js";
@@ -522,6 +522,7 @@ function probeProjection(absPath, id) {
 export class FileMemoryEngineBackend {
     directoryRoot;
     controlPlaneRoot;
+    physicalRoot;
     now;
     onIncident;
     ledger;
@@ -545,6 +546,7 @@ export class FileMemoryEngineBackend {
             adoptCanonicalKeyedControlDir(resolveMemoryEngineRoot(), dir, opts.onIncident);
         this.controlPlaneRoot = opts.controlDir ?? deriveControlPlaneDir(resolveMemoryEngineRoot(), dir);
         ensureDirExists(dir);
+        this.physicalRoot = landingPathOf(dir);
         ensureDirExists(this.controlPlaneRoot);
         this.recoverJournal({ unlocked: true });
         try {
@@ -577,6 +579,7 @@ export class FileMemoryEngineBackend {
         });
     }
     ensureLayout(ownerCandidate) {
+        this.assertRootIntact();
         if (!layoutNeedsAdoption(this.directoryRoot, this.controlPlaneRoot))
             return;
         const lock = this.tryAcquireTxnLockSync();
@@ -591,6 +594,7 @@ export class FileMemoryEngineBackend {
         }
     }
     async adoptRootScopeLayout(opts = {}) {
+        this.assertRootIntact();
         if (!layoutNeedsAdoption(this.directoryRoot, this.controlPlaneRoot))
             return;
         const lock = await this.acquireTxnLock();
@@ -1211,6 +1215,7 @@ export class FileMemoryEngineBackend {
         }
     }
     recoverJournal(fence) {
+        this.assertRootIntact();
         if (fence.token === undefined) {
             if (this.txnInFlight())
                 return;
@@ -1399,7 +1404,10 @@ export class FileMemoryEngineBackend {
                 }
             }
             this.assertTxnLockOwnership(fenceToken);
+            const replayAt = `the journal replay (journal kept at ${jp})`;
+            this.refuseEscapingTargets(journal.ops, replayAt);
             for (const op of journal.ops) {
+                this.refuseEscapingTargets([op], replayAt);
                 try {
                     if (op.kind === "write" && op.content !== undefined) {
                         atomicWriteFileSync(op.target, op.content);
@@ -1457,6 +1465,24 @@ export class FileMemoryEngineBackend {
             throw new ControlPlaneCorruptError(`txn lock state could not be probed (${code ?? "io error"}) at ${this.txnLockDir()} — a probe failure is not "no writer" (fail-closed)`);
         }
     }
+    refuseEscapingTargets(ops, at) {
+        for (const op of ops) {
+            if (op.kind !== "write" && op.kind !== "delete")
+                continue;
+            for (const path of op.staged === undefined ? [op.target] : [op.target, op.staged]) {
+                const escape = storeTargetEscape(this.physicalRoot, path);
+                if (escape === undefined)
+                    continue;
+                throw erasureCodedError(`${TARGET_OUTSIDE_STORE}: ${at} refused a ${op.kind} of ${op.target}${path === op.target ? "" : ` (its staged file ${path})`} — ${escape}; not performed`, TARGET_OUTSIDE_STORE);
+            }
+        }
+    }
+    assertRootIntact() {
+        const now = landingPathOf(this.directoryRoot);
+        if (now === this.physicalRoot)
+            return;
+        throw erasureCodedError(`${TARGET_OUTSIDE_STORE}: the store root ${this.directoryRoot} now resolves to ${now}, not ${this.physicalRoot} where this backend opened it — refused; open a new backend on the directory you mean`, TARGET_OUTSIDE_STORE);
+    }
     sweepStagedFiles() {
         const walk = (d, depth) => {
             let names;
@@ -2366,16 +2392,37 @@ export class FileMemoryEngineBackend {
             return report;
         }
         const txn = `${Date.now()}-${Math.random().toString(36).slice(2, 8)}`;
+        const stagedFiles = [];
+        const refuseUnstaging = (batch, at) => {
+            try {
+                this.refuseEscapingTargets(batch, at);
+            }
+            catch (err) {
+                for (const f of stagedFiles) {
+                    try {
+                        const st = lstatSync(f.path);
+                        if (st.dev === f.dev && st.ino === f.ino)
+                            rmSync(f.path, { force: true });
+                    }
+                    catch {
+                    }
+                }
+                throw err;
+            }
+        };
         let n = 0;
         for (const op of ops) {
             if (op.kind !== "write" || op.content === undefined)
                 continue;
+            refuseUnstaging([op], "applyPatches (staging)");
             const staged = join(dirname(op.target), `.stage-${txn}-${n++}`);
             mkdirSync(dirname(op.target), { recursive: true });
             const fd = openSync(staged, "w", 0o600);
             try {
                 writeAllSync(fd, op.content);
                 fsyncSync(fd);
+                const st = fstatSync(fd);
+                stagedFiles.push({ path: staged, dev: st.dev, ino: st.ino });
             }
             finally {
                 closeSync(fd);
@@ -2393,8 +2440,10 @@ export class FileMemoryEngineBackend {
         if (coherentTransfers.length > 0)
             this.precheckTransfersAppendable();
         const journal = { txn, ops, ledger2: ledgerEnvelope(rows, this.envelopeExtras), ...(coherentTransfers.length > 0 ? { transfers: coherentTransfers } : {}) };
+        refuseUnstaging(ops, "applyPatches (commit point)");
         atomicWriteFileSync(join(this.controlPlaneRoot, JOURNAL_FILE), JSON.stringify(journal));
         for (const op of ops) {
+            this.refuseEscapingTargets([op], "applyPatches (after the commit point; the journal is kept)");
             if (op.kind === "write" && op.staged) {
                 renameSync(op.staged, op.target);
             }
@@ -2819,8 +2868,10 @@ export class FileMemoryEngineBackend {
                 this.assertTxnLockOwnership(lock.token);
                 this.precheckTransfersAppendable();
                 const journal = { txn, ops, ledger2: ledgerEnvelope(rows, this.envelopeExtras), transfers };
+                this.refuseEscapingTargets(ops, "eraseWithEvidence (commit point)");
                 atomicWriteFileSync(join(this.controlPlaneRoot, JOURNAL_FILE), JSON.stringify(journal));
                 for (const op of ops) {
+                    this.refuseEscapingTargets([op], "eraseWithEvidence (after the commit point; the journal is kept)");
                     if (op.kind === "delete") {
                         rmSync(op.target, { force: true });
                     }

package/dist/core/memory-engine/layout.d.ts

@@ -259,6 +259,28 @@ export declare function adoptRootScopeLayout(rootPath: string, controlDir: strin
 export declare const canonicalize: typeof physicalPathOfExisting;
 /** True iff `child` (canonicalized) is `root` or inside it. */
 export declare function isContainedIn(root: string, child: string): boolean;
+/** The code an act on a store path is refused with when it would land outside the store ({@link storeTargetEscape}). */
+export declare const TARGET_OUTSIDE_STORE = "memory.target_outside_store";
+/** Where an act at `p` lands: the physical path of its normalized spelling (the spelling a child path
+ *  joined under it carries), a MISSING tail rejoined under the deepest existing directory (what the act
+ *  creates). Any other resolution fault (EACCES, ELOOP, ENOTDIR) is THROWN as itself: an act that
+ *  cannot be placed is not performed — a failed resolution never implies the act would fail too
+ *  (a link whose own mode refuses `realpath` is still followed by `unlink` and `rename`). */
+export declare function landingPathOf(p: string): string;
+/**
+ * Where a write, rename or delete at `target` would physically LAND, judged against the store's
+ * `physicalRoot`: `undefined` = inside, otherwise the reason. The target's directory, resolved through
+ * every link on its existing prefix (a missing tail is what the act creates, under the deepest existing
+ * directory), must be the root or inside it. `physicalRoot` is the root's physical form as the store
+ * was opened and is not re-resolved here: a store mounted through a link is judged by what the link
+ * resolved to, and a root spelling re-pointed after opening moves the acts, not the store. The final
+ * component is not judged: `rename` and `unlink` act on it and never through it, and the engine's
+ * writes open it no-follow — a link there is replaced, removed or refused, and what it points at is
+ * untouched. A lexical spelling under the root proves nothing: a directory under it replaced by a link
+ * keeps the spelling while the act follows the link out. A directory that cannot be resolved throws its
+ * fault ({@link landingPathOf}).
+ */
+export declare function storeTargetEscape(physicalRoot: string, target: string): string | undefined;
 /** mkdir -p convenience used by the engine/backend (0o700 like the file stores). */
 export declare function ensureDirExists(dir: string): void;
 /** The one remedy every surfaced permission refusal carries — `undefined` unless `err` is a write
@@ -324,10 +346,13 @@ export interface QuarantineOutcome {
  * without native bindings. What this buys is the leaf variant, which is the cheap one; the ancestor
  * variant stays open and is recorded with the rest of the family rather than papered over.
  *
- * Throws like `writeFileSync`, including ELOOP when the final component IS a symlink. The write
- * itself goes through `writeFileSync` on the open descriptor, which writes every byte or throws —
- * a bare `writeSync` may short-write, and reporting a truncated restore as contained (after
- * `O_TRUNC` already destroyed the destination) is the failure this guard exists to prevent.
+ * Throws like `writeFileSync`, including ELOOP when the final component IS a symlink. A HARD link is the
+ * same tamper by other means — the file's bytes live under a second name, possibly outside the store, and
+ * an in-place write would change them there too — so an opened file with more than one name is refused
+ * the same way, before anything is truncated (the check reads the opened descriptor: no window). The
+ * write itself goes through `writeFileSync` on the open descriptor, which writes every byte or throws —
+ * a bare `writeSync` may short-write, and reporting a truncated restore as contained (after the
+ * truncation already destroyed the destination) is the failure this guard exists to prevent.
  */
 export declare function writeFileNoFollow(path: string, content: string): void;
 /** {@link writeFileNoFollow}'s NO-REPLACE twin: write `content` only if nothing is at `path`. `"written"`