@open-everywhere/core 0.1.0

package/dist/agent/hooks/memory.js

@@ -0,0 +1,1191 @@
+// Lifecycle memory sync: session.started materialises each READ silo into the sandbox under /workspace/memory, and persistMemoryNow writes each WRITE silo back at the flush points below.
+// Best-effort throughout — a missing sandbox or a failed step degrades to a logged warning and never fails the user's task.
+import { createHash } from "node:crypto";
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { defineHook } from "eve/hooks";
+import { defineState } from "eve/context";
+import { resolvePartition } from "../memory/partition.js";
+import { bindFrom, currentTurnId, isSubagentChildContext } from "../identity/binding.js";
+import { writeMemoryTier } from "../memory/write-road.js";
+import { planFor } from "../memory/resolve.js";
+import { providerById } from "../memory/provider.js";
+import { renderMemoryIndex } from "../memory/listing.js";
+import { tierId, storeRoot } from "../memory/store.js";
+import { seedFor } from "../memory/layout.js";
+import { syncTierIntoSandbox, readTierFromSandbox, removeTierFiles, removeTierDir, tierSandboxDir, writeTierFile } from "../memory/sandbox-sync.js";
+import { baselineOf, markAddedBullets, renderProvenanceWording } from "../memory/provenance-mark.js";
+import { untrustedIngestedThisTurn, taintKindsThisTurn } from "../access/taint-signal.js";
+// Read from the pure leaf, not from hooks/settlement-flush.ts: that file imports this one, so importing it back would make the two hook modules circular.
+import { liveTaskIds } from "../access/live-delegated-tasks.js";
+import { taintEnabled } from "../access/taint-enforcement.js";
+import { readOnlyBanner, hasReadOnlyBanner, lockCommand, unlockCommand } from "../memory/readonly.js";
+import { lockMemoryRoot, memoryRootUnlockCommand } from "../memory/root-fence.js";
+import { removedLineDigests } from "../memory/purge-redaction.js";
+import { consumeWriteIntent, noteUnservedPost, noteWriteIntent, writeIntentArmed } from "../memory/write-intent.js";
+import { factStoredThisTurn } from "../memory/write-evidence.js";
+import { startMemorySyncTiming, emitMemorySyncTiming, byteSize } from "../memory/sync-timing.js";
+import { appendAudit } from "../audit/audit.js";
+import { isSupervisorSession } from "../model/routing.js";
+import { windowTopologyEnabled } from "../access/capabilities.js";
+import { HOST_OWNED_FILES } from "../memory/host-owned-files.js";
+const sessionLog = defineState("open-everywhere.memory.sessionLog", () => ({}));
+// Per-write-tier hash of the host store's files AT SESSION START, keyed by tierId. It lets persistMemoryNow tell our own edit from another session's concurrent write, so neither is silently clobbered.
+const writeBaseline = defineState("open-everywhere.memory.writeBaseline", () => ({}));
+// Last-synced store version per READ silo, keyed by tierId. The supervisor turn.started re-sync re-pulls a silo only when its current version differs from this.
+// Populated for ARMED sessions only; an unarmed session never touches it.
+const readSyncVersions = defineState("open-everywhere.memory.readSyncVersions", () => ({}));
+// Silo names that FAILED to materialise at session.started, keyed by tierId, so a mid-session re-sync that heals one can drop it from the unavailable list and refresh the MEMORY.md index.
+// ARMED sessions only; empty for every other session.
+const failedReadSilos = defineState("open-everywhere.memory.failedReadSilos", () => ({}));
+// Which tiers are MATERIALISED in this session's sandbox, keyed by tierId. The re-sync diffs the current plan against this, so a tier that falls out of the plan also leaves the sandbox instead of merely going unrefreshed.
+// ARMED sessions only.
+const materialisedTiers = defineState("open-everywhere.memory.materialisedTiers", () => ({}));
+// Per writable tier, the digests of every line the tier held at the last capture, keyed by tierId.
+// The armed flag records that a capture ran at all: an unarmed session marks nothing.
+const provenanceBaseline = defineState("open-everywhere.memory.provenanceBaseline", () => ({}));
+function log(msg) {
+    console.log(`[open-everywhere:memory] ${msg}`);
+}
+function hashContent(s) {
+    return createHash("sha1").update(s).digest("hex");
+}
+export function hashFiles(files) {
+    const out = {};
+    for (const [rel, content] of Object.entries(files))
+        out[rel] = hashContent(content);
+    return out;
+}
+function siblingName(rel, marker, sessionId) {
+    const sid = sessionId.replace(/[^A-Za-z0-9_-]/g, "").slice(0, 8) || "session";
+    const dot = rel.lastIndexOf(".");
+    const slash = rel.lastIndexOf("/");
+    if (dot > slash && dot !== -1)
+        return `${rel.slice(0, dot)}.${marker}-${sid}${rel.slice(dot)}`;
+    return `${rel}.${marker}-${sid}`;
+}
+export function conflictName(rel, sessionId) {
+    return siblingName(rel, "conflict", sessionId);
+}
+export function rejectedName(rel, sessionId) {
+    return siblingName(rel, "rejected", sessionId);
+}
+/**
+ * hooks/learn.ts writes these files host-direct at session end, so the sandbox holds only a stale session-start snapshot of them. The host copy always wins and is never filed as a concurrent conflict.
+ * The set itself lives in memory/host-owned-files.ts, so a lower layer can assert against the same one.
+ */
+function isHostOwnedFile(rel) {
+    return HOST_OWNED_FILES.has(rel);
+}
+/**
+ * Merge the agent's sandbox edits over the host store's CURRENT state, preserving any file another session changed while we ran.
+ * A file BOTH sides changed is a genuine conflict: the agent's version lands and the concurrent host version is written to a .conflict-<sid> sibling, so nothing is lost.
+ */
+export function mergePreservingConflicts(hostCurrent, fromSandbox, baseline, sessionId) {
+    const merged = { ...hostCurrent, ...fromSandbox };
+    const conflicts = [];
+    for (const [rel, sandboxContent] of Object.entries(fromSandbox)) {
+        if (rel.includes(".conflict-"))
+            continue; // don't nest conflict-of-conflict
+        if (isHostOwnedFile(rel)) {
+            if (rel in hostCurrent)
+                merged[rel] = hostCurrent[rel];
+            continue;
+        }
+        const hostContent = hostCurrent[rel];
+        if (hostContent === undefined)
+            continue; // new file we're adding — no clobber
+        const hostChangedSinceStart = hashContent(hostContent) !== baseline[rel];
+        const weChangedIt = sandboxContent !== hostContent;
+        if (hostChangedSinceStart && weChangedIt) {
+            merged[conflictName(rel, sessionId)] = hostContent; // preserve the concurrent version
+            conflicts.push(rel);
+        }
+    }
+    return { files: merged, conflicts };
+}
+// The destructive-write floor (OPE-245): a persist that subtracts most of a host file's lines is refused, and the agent's version is parked as a .rejected-<sid> sibling rather than discarded.
+// Fail-closed — any error deciding the verdict counts as destruction.
+/** More than this share of a host file's lines disappearing in one persist is destruction. */
+export const MEMORY_DROP_RATIO_FLOOR = 0.5;
+/** …and at least this many lines must go, so a small file's ordinary edit never trips it. */
+export const MEMORY_DROP_MIN_LINES = 3;
+/** A sibling this hook itself minted — never guarded, never parked again (no infinite nesting). */
+function isHostMintedSibling(rel) {
+    return rel.includes(".conflict-") || rel.includes(".rejected-");
+}
+function contentLines(s) {
+    return s
+        .split("\n")
+        .map((l) => l.trim())
+        .filter((l) => l.length > 0);
+}
+/** null ⇒ the overwrite is an edit and may land; otherwise the counts that make it destruction. */
+function destructionVerdict(host, next) {
+    // A non-string on either side is undecidable, not benign (a provider handing back a null/blob
+    // for a file must not read as "no lines dropped"). Throw so the caller's catch fails closed.
+    if (typeof host !== "string" || typeof next !== "string")
+        throw new TypeError("memory floor: non-string file content");
+    const before = contentLines(host);
+    if (before.length === 0)
+        return null; // an empty/blank file has nothing to destroy
+    const kept = new Set(contentLines(next));
+    const dropped = before.filter((l) => !kept.has(l)).length;
+    if (dropped < MEMORY_DROP_MIN_LINES)
+        return null;
+    if (dropped / before.length <= MEMORY_DROP_RATIO_FLOOR)
+        return null;
+    return { hostLines: before.length, droppedLines: dropped };
+}
+/**
+ * Applies the floor against the host's CURRENT bytes, never the session-start baseline, which can be missing when a write silo's baseline read failed.
+ * A refused file keeps its host content and the agent's version is parked as a .rejected-<sid> sibling; files the host never had, and the siblings this hook mints, are skipped.
+ */
+export function guardDestructiveWrites(hostCurrent, merged, sessionId) {
+    const files = { ...merged };
+    const rejected = [];
+    for (const [rel, hostContent] of Object.entries(hostCurrent)) {
+        if (isHostMintedSibling(rel))
+            continue;
+        const next = files[rel];
+        if (next === undefined || next === hostContent)
+            continue; // absent (union kept host) or unchanged
+        let verdict;
+        try {
+            verdict = destructionVerdict(hostContent, next);
+        }
+        catch {
+            verdict = { hostLines: -1, droppedLines: -1 }; // FAIL CLOSED — an undecidable diff is destruction
+        }
+        if (!verdict)
+            continue;
+        const parkedAs = rejectedName(rel, sessionId);
+        files[rel] = hostContent; // the host's memory survives
+        // Coerced because the fail-closed branch above is reachable with a non-string, and a parked file must still be a file.
+        files[parkedAs] = typeof next === "string" ? next : String(next);
+        rejected.push({ rel, hostLines: verdict.hostLines, droppedLines: verdict.droppedLines, parkedAs });
+    }
+    return { files, rejected };
+}
+// The deletion audit records a sha256 and a length per removed line, never the line: the audit log is append-only and sits outside the erasure path, so it must never preserve what a purge removed.
+// Bounded by MAX_AUDITED_DELETIONS; past the cap the row keeps the count and marks itself truncated.
+const MAX_AUDITED_DELETIONS = 50;
+function deletionDigests(hostCurrent, files) {
+    const perFile = [];
+    let total = 0;
+    for (const [rel, hostContent] of Object.entries(hostCurrent)) {
+        if (isHostMintedSibling(rel))
+            continue;
+        const next = files[rel];
+        if (next === undefined || next === hostContent)
+            continue; // absent (union kept host) or unchanged
+        let removed;
+        try {
+            removed = removedLineDigests(hostContent, next);
+        }
+        catch {
+            continue; // an undecidable diff is the FLOOR's problem, not the audit's — never fail persist
+        }
+        if (removed.length === 0)
+            continue;
+        total += removed.length;
+        perFile.push({ file: rel, removed });
+    }
+    return { perFile, total };
+}
+function deletionDetail(hostCurrent, files) {
+    const { perFile, total } = deletionDigests(hostCurrent, files);
+    if (total === 0)
+        return null;
+    let budget = MAX_AUDITED_DELETIONS;
+    const rendered = [];
+    for (const entry of perFile) {
+        if (budget <= 0)
+            break;
+        const take = entry.removed.slice(0, budget);
+        budget -= take.length;
+        rendered.push({ file: entry.file, lines: take.map((l) => ({ sha256: l.sha256, chars: l.chars })) });
+    }
+    return {
+        deletedLines: total,
+        deleted: rendered,
+        ...(total > MAX_AUDITED_DELETIONS ? { deletedTruncated: true } : {}),
+    };
+}
+/**
+ * THE MEMORY SINGLE-WRITER RULE (OPE-393): an eve subagent child SHARES the parent's sandbox, so it neither materialises nor persists. Either half would overwrite, or file as a conflict, the parent's un-persisted edits in the one shared tree.
+ * The parent stays the only writer for any number of children, and a child's own edits go out through the parent's persist.
+ */
+/**
+ * The stable marker in the skip log line, exported so a test can COUNT the skips instead of matching prose a later edit could change.
+ * One wake on a standing seat that delegates starts two sessions, so the line is EXPECTED once per wake from the child — attribute it to a session before reading it as the seat skipping.
+ */
+export const SUBAGENT_SKIP_MARKER = "SKIPPED — this is an eve subagent child";
+function skipAsSubagentChild(ctx, phase) {
+    let child = false;
+    try {
+        child = isSubagentChildContext(ctx);
+    }
+    catch {
+        child = false; // unreadable ⇒ behave exactly as before; the parent-owned tree is the common case
+    }
+    if (child)
+        log(`${phase}: ${SUBAGENT_SKIP_MARKER}; the parent owns the shared sandbox's memory tree`);
+    return child;
+}
+const PERSIST_WHERE = {
+    completed: "session.completed",
+    failed: "session.failed",
+    settled: "delegation settlement",
+    edited: "turn-end tree edit",
+    "write-intent": "in-turn remember-ask",
+};
+const NOTHING_PERSISTED = { silos: 0, persisted: 0, changed: 0, failed: 0 };
+/**
+ * Read the session's sandbox memory tree back and persist it to every WRITE silo.
+ * IDEMPOTENT BY CONSTRUCTION, which is what lets several callers run it: every write is diff-based against the host's CURRENT bytes, a provider's writeTier is a no-op when nothing changed, and the memory.write row is emitted only when it was not.
+ */
+export async function persistMemoryNow(ctx, outcome) {
+    const where = PERSIST_WHERE[outcome] ?? String(outcome);
+    if (skipAsSubagentChild(ctx, where))
+        return NOTHING_PERSISTED;
+    const binding = bindFrom(ctx);
+    const p = resolvePartition(ctx);
+    const plan = planFor(binding, p);
+    if (plan.writes.length === 0) {
+        log(`${where}: nothing to persist — ${plan.reason}`);
+        return NOTHING_PERSISTED;
+    }
+    // Mark BEFORE the tree is read. A flush can run INSIDE a turn, so a mark applied only at turn.completed would land after this persist had carried the bytes away.
+    // A no-op unless this session has a writable tier and the turn is tainted.
+    await markProvenanceForTurn(ctx, `persist:${outcome}`);
+    const sessionId = ctx.session?.id ?? "";
+    const principalId = binding.principalId; // WHO, for the audit trail
+    const request = sessionLog.get().firstMessage?.trim().replace(/\n+/g, " ").slice(0, 200); // WHY
+    // The session's continuation token is stamped so the wake-time memory-delta push (memory/wake-delta.ts) can recognise and EXCLUDE a supervisor's own writes.
+    // It keys that exclusion because eve's session.id is not known at webhook-dispatch time.
+    const continuationToken = ctx.channel?.continuationToken;
+    let sandbox = null;
+    try {
+        sandbox = ctx.getSandbox ? await ctx.getSandbox() : null;
+    }
+    catch {
+        log(`sandbox unavailable at ${where}; persisting host-store state only`);
+    }
+    const baselines = writeBaseline.get();
+    let persisted = 0;
+    let changed = 0;
+    // PER-SILO ISOLATION: each write is independently try/caught, so one failing silo (a provider outage, a bad credential) can never drop another silo's edits.
+    const failed = [];
+    for (const rm of plan.writes) {
+        try {
+            const provider = providerById(rm.silo.provider);
+            const hostCurrent = await provider.readTier(p, rm.tier, rm.silo, rm.access);
+            let files = hostCurrent;
+            let conflicts = [];
+            let rejected = [];
+            if (sandbox) {
+                const fromSandbox = await readTierFromSandbox(sandbox, rm.tier);
+                if (Object.keys(fromSandbox).length > 0) {
+                    const baseline = baselines[tierId(rm.tier)] ?? {};
+                    const merged = mergePreservingConflicts(hostCurrent, fromSandbox, baseline, sessionId);
+                    conflicts = merged.conflicts;
+                    ({ files, rejected } = guardDestructiveWrites(hostCurrent, merged.files, sessionId));
+                }
+            }
+            // Audited BEFORE the write and in its OWN row: the memory.write row below is emitted only when the write changed something, so a refusal must not depend on it to be seen.
+            // Names and counts only — never the refused content.
+            if (rejected.length > 0) {
+                log(`REFUSED ${rejected.length} destructive overwrite(s) in ${tierId(rm.tier)} → ${rm.silo.name}: ` +
+                    rejected.map((r) => `${r.rel} (-${r.droppedLines}/${r.hostLines} lines, parked as ${r.parkedAs})`).join(", "));
+                try {
+                    await appendAudit({
+                        org: p.org,
+                        platform: p.platform,
+                        workspace: p.workspace,
+                        surface: p.surface,
+                        principalId,
+                        action: "memory.write_refused",
+                        detail: {
+                            tier: tierId(rm.tier),
+                            silo: rm.silo.name,
+                            provider: rm.silo.provider,
+                            outcome,
+                            sessionId,
+                            request,
+                            ...(continuationToken ? { continuationToken } : {}),
+                            refused: rejected.map((r) => ({ file: r.rel, hostLines: r.hostLines, droppedLines: r.droppedLines, parkedAs: r.parkedAs })),
+                        },
+                    });
+                }
+                catch (err) {
+                    log(`memory.write_refused audit skipped (the overwrite was still refused): ${String(err)}`);
+                }
+            }
+            // Computed BEFORE the write (the host bytes are still the pre-write truth) but audited
+            // only when the write actually landed — digests + counts, never the removed lines.
+            const deleted = deletionDetail(hostCurrent, files);
+            // THE ONE ROAD (OPE-1873): the provider write and its `memory.write` row are one call, so a
+            // persist can no longer land bytes and leave no row. The detail this road adds is the same set
+            // the row always carried; the road adds the canonical `road`/`kind`/`tier`/`silo`/`provider`/
+            // `files`/`version` fields in front of it.
+            const { version: sha } = await writeMemoryTier({
+                provider,
+                partition: p,
+                tier: rm.tier,
+                files,
+                message: `session ${sessionId} (${outcome}) [${tierId(rm.tier)}]`,
+                silo: rm.silo,
+                access: rm.access,
+                road: "session-persist",
+                principalId,
+                turnId: currentTurnId(ctx),
+                extra: {
+                    outcome,
+                    sessionId,
+                    request,
+                    ...(continuationToken ? { continuationToken } : {}),
+                    ...(conflicts.length ? { conflicts } : {}),
+                    ...(rejected.length ? { refused: rejected.map((r) => r.rel) } : {}),
+                    ...(deleted ?? {}),
+                },
+            });
+            persisted += Object.keys(files).length;
+            if (sha)
+                changed++;
+            // THE BASELINE ADVANCE: once this session has itself written the host, the session-start baseline reads our OWN bytes as another session's concurrent write, so a later pass would mint a .conflict- sibling of our own write. Move it forward to the state we just persisted.
+            // Its own try/catch: the write LANDED, so a state-container blip must not re-file the silo as failed.
+            try {
+                writeBaseline.update((b) => ({ ...b, [tierId(rm.tier)]: hashFiles(files) }));
+            }
+            catch (err) {
+                log(`write-baseline advance skipped for ${tierId(rm.tier)} (the persist itself landed; a later pass may re-file our own write as a conflict): ${String(err)}`);
+            }
+            log(`persisted ${tierId(rm.tier)} → ${rm.silo.name}/${rm.silo.provider}: ${Object.keys(files).length} file(s)` +
+                `${sha ? ` @ ${sha}` : ""}${conflicts.length ? ` (preserved ${conflicts.length} concurrent-write conflict(s): ${conflicts.join(", ")})` : ""}` +
+                `${rejected.length ? ` (REFUSED ${rejected.length} destructive overwrite(s): ${rejected.map((r) => r.rel).join(", ")})` : ""}`);
+        }
+        catch (err) {
+            failed.push(rm.silo.name);
+            log(`PERSIST FAILED for ${tierId(rm.tier)} → ${rm.silo.name}/${rm.silo.provider} (other silos unaffected): ${String(err)}`);
+        }
+    }
+    log(`session ${sessionId} ${outcome}: ${persisted} file(s) for ${p.key} (${plan.reason}) -> ${storeRoot()}` +
+        `${failed.length ? ` — ${failed.length} silo(s) FAILED to persist: ${failed.join(", ")}` : ""}`);
+    return { silos: plan.writes.length, persisted, changed, failed: failed.length };
+}
+function withReadOnlyBanner(files, silo) {
+    const md = files["MEMORY.md"];
+    if (md && !hasReadOnlyBanner(md))
+        return { ...files, "MEMORY.md": readOnlyBanner(silo) + md };
+    return files;
+}
+async function loadSource(p, rm) {
+    const provider = providerById(rm.silo.provider);
+    if (rm.readOnly) {
+        // Never write to a read-only source. If it's empty, give the agent the seed
+        // skeleton in-sandbox (so it has structure to read) WITHOUT persisting it.
+        const files = await provider.readTier(p, rm.tier, rm.silo, rm.access);
+        return withReadOnlyBanner(Object.keys(files).length > 0 ? files : seedFor(p, rm.tier), rm.silo);
+    }
+    return provider.ensureTier(p, rm.tier, rm.silo, rm.access);
+}
+/**
+ * Make a materialised path read-only IN THE SANDBOX so the agent's edits fail loud with EACCES instead of being dropped silently at session end.
+ * Best-effort: a chmod failure degrades to the advisory banner and never breaks the session.
+ */
+async function lock(sandbox, path) {
+    try {
+        await sandbox.run({ command: lockCommand(path) });
+    }
+    catch (err) {
+        log(`read-only lock for ${path} failed (advisory banner still applies): ${String(err)}`);
+    }
+}
+// Supervisor-only mid-session re-materialisation: on each wake, re-pull only the READ silos whose durable store version advanced, probed through provider.tierVersion.
+// The gate is the org-wide window-topology capability, not a per-channel one — a re-sync only re-reads silos the session's own plan already grants, so it changes freshness, never entitlement.
+/** Whether this session gets mid-session memory re-materialisation. Fail-soft false. */
+function resyncArmed(ctx) {
+    try {
+        // BELT on the single-writer rule: a re-sync writes silo files, and propagates deletes, into the sandbox — which for a subagent child is the PARENT's tree.
+        // A child cannot reach this today, but deleting a standing seat's unpersisted memory mid-turn is too expensive a hazard to rest on a token-shape coincidence.
+        if (isSubagentChildContext(ctx))
+            return false;
+        if (!isSupervisorSession(ctx))
+            return false;
+        return windowTopologyEnabled();
+    }
+    catch {
+        return false; // odd ctx / no config → not armed, never throws
+    }
+}
+/**
+ * A git-backed READ silo whose durable store has no .git can never report a version advance, so its mid-session re-sync NEVER fires and the silo stays stale until session end without the operator knowing.
+ * Warned once, at session.started; the other providers' probes are unaffected.
+ */
+function warnGitlessReadSilos(reads) {
+    if (existsSync(join(storeRoot(), ".git")))
+        return;
+    const gitSilos = reads.filter((r) => r.silo.provider === "git").map((r) => r.silo.name);
+    if (gitSilos.length === 0)
+        return;
+    log(`⚠ git-backed read silo(s) [${gitSilos.join(", ")}] but the memory store has no .git — ` +
+        `tierVersion can't detect upstream writes, so mid-session re-sync will NEVER fire for them ` +
+        `(a degraded-git self-host store stays stale until session end). Initialise git in the store ` +
+        `(${storeRoot()}) or use the sqlite/postgres memory provider.`);
+}
+/**
+ * Record each successfully-synced READ silo's current store version — the skip-unchanged baseline.
+ * A provider with no tierVersion probe records nothing and is never re-pulled mid-session; a probe FAILURE also records nothing, which makes the next turn.started re-pull that silo.
+ */
+async function recordReadVersions(p, reads) {
+    const versions = {};
+    for (const rm of reads) {
+        try {
+            const provider = providerById(rm.silo.provider);
+            if (provider.tierVersion)
+                versions[tierId(rm.tier)] = await provider.tierVersion(p, rm.tier, rm.silo, rm.access);
+        }
+        catch {
+            /* unrecorded → re-pulled next turn */
+        }
+    }
+    readSyncVersions.update(() => versions);
+}
+/**
+ * Refresh a WRITABLE tier from the host without clobbering the agent's un-persisted edits: a file the agent has not diverged from takes the host version and moves its baseline forward, while a diverged file is kept and its genuine conflict is still resolved at persist time.
+ * A sandbox file ABSENT from host is removed only when hash(sandbox) equals its baseline entry — agent-untouched, so it was deleted upstream; an agent-edited or agent-created file is kept.
+ */
+async function refreshWritableTier(sandbox, p, rm) {
+    const provider = providerById(rm.silo.provider);
+    const host = await provider.readTier(p, rm.tier, rm.silo, rm.access);
+    const fromSandbox = await readTierFromSandbox(sandbox, rm.tier);
+    const tid = tierId(rm.tier);
+    const baseline = { ...(writeBaseline.get()[tid] ?? {}) };
+    const dir = tierSandboxDir(rm.tier);
+    for (const [rel, content] of Object.entries(host)) {
+        const sandboxContent = fromSandbox[rel];
+        const agentChanged = sandboxContent !== undefined && hashContent(sandboxContent) !== baseline[rel];
+        if (agentChanged && sandboxContent !== content)
+            continue; // divergent un-persisted edit — keep it
+        if (sandboxContent !== content)
+            await sandbox.writeTextFile({ path: `${dir}/${rel}`, content });
+        baseline[rel] = hashContent(content);
+    }
+    const toDelete = [];
+    for (const [rel, sandboxContent] of Object.entries(fromSandbox)) {
+        if (rel in host)
+            continue; // still upstream — handled by the update loop
+        if (hashContent(sandboxContent) === baseline[rel]) {
+            toDelete.push(rel);
+            delete baseline[rel];
+        }
+        // else: agent-edited or agent-created (no/other baseline) → KEEP the un-persisted work
+    }
+    if (toDelete.length > 0)
+        await removeTierFiles(sandbox, rm.tier, toDelete);
+    writeBaseline.update((b) => ({ ...b, [tid]: baseline }));
+}
+/**
+ * Refresh a READ-ONLY tier from its source: UNLOCK, rewrite, propagate deletes (a stale file absent from the fresh source was removed upstream), then RE-LOCK.
+ * The re-lock runs in a finally, so a mid-refresh sandbox or transport error can never leave the tier writable for the rest of a multi-day session.
+ */
+async function refreshReadOnlyTier(sandbox, p, rm) {
+    const files = await loadSource(p, rm);
+    const dir = tierSandboxDir(rm.tier);
+    // Read (allowed while locked) BEFORE unlocking so a failure can't lose the stale set.
+    const before = await readTierFromSandbox(sandbox, rm.tier);
+    const stale = Object.keys(before).filter((rel) => !(rel in files));
+    try {
+        await sandbox.run({ command: unlockCommand(dir) });
+        await syncTierIntoSandbox(sandbox, rm.tier, files);
+        if (stale.length > 0)
+            await removeTierFiles(sandbox, rm.tier, stale);
+    }
+    finally {
+        await lock(sandbox, dir); // ALWAYS restore fail-loud, even on a mid-refresh throw
+    }
+}
+/**
+ * UN-MATERIALISE the tiers that dropped OUT of the plan, so an un-vouched surface or a silo dropped from a domain stops being readable — and, for a writable tier, stops riding the persist path — in a session that can run for days.
+ * Read-only tiers are UNLOCKED first: the lock takes write off the tier dir, and rm needs write on a directory to unlink what is inside it.
+ */
+async function unmaterialiseDroppedTiers(sandbox, dropped) {
+    const removed = [];
+    for (const d of dropped) {
+        const dir = tierSandboxDir(d.tier);
+        try {
+            // Remove the named files first, then the dir itself: an empty or unreadable listing on a locked tier still has to leave nothing behind.
+            const present = await readTierFromSandbox(sandbox, d.tier);
+            if (d.readOnly)
+                await sandbox.run({ command: unlockCommand(dir) });
+            const rels = Object.keys(present);
+            if (rels.length > 0)
+                await removeTierFiles(sandbox, d.tier, rels);
+            await removeTierDir(sandbox, d.tier);
+            removed.push(d.tierId);
+        }
+        catch (err) {
+            log(`turn.started UN-MATERIALISE FAILED for ${d.tierId} ← ${d.silo} (other tiers unaffected): ${String(err)}`);
+        }
+    }
+    return removed;
+}
+async function resyncSupervisorReads(ctx) {
+    // THE ROOT FENCE: adding or removing an entry under memory/ needs write on the root that the session-start fence took away, so the re-sync unlocks it once and re-locks once in the finally — no failure path leaves the root writable for the rest of a multi-day session.
+    // No race here: turn.started is awaited BEFORE the turn's model step, so no agent tool call can run while the root is open.
+    let sandbox = null;
+    let rootUnlocked = false;
+    const openSandbox = async () => {
+        sandbox ??= await ctx.getSandbox();
+        if (!rootUnlocked) {
+            try {
+                await sandbox.run({ command: memoryRootUnlockCommand() });
+                rootUnlocked = true;
+            }
+            catch (err) {
+                log(`turn.started memory root unlock failed (a gained/dropped tier may not apply this turn): ${String(err)}`);
+            }
+        }
+        return sandbox;
+    };
+    try {
+        return await runSupervisorResync(ctx, openSandbox);
+    }
+    finally {
+        if (rootUnlocked && sandbox)
+            await lockMemoryRoot(sandbox);
+    }
+}
+/** The re-sync itself. `openSandbox` yields the session sandbox with the memory ROOT unlocked — see
+ *  {@link resyncSupervisorReads}, which owns the re-lock. */
+async function runSupervisorResync(ctx, openSandbox) {
+    const binding = bindFrom(ctx);
+    const p = resolvePartition(ctx);
+    const plan = planFor(binding, p);
+    // The drop diff runs BEFORE the early-out, deliberately: a plan that collapses to EMPTY is the sharpest case this exists for, and returning early on an empty read list would leave those files in place.
+    const planned = new Set(plan.reads.map((r) => tierId(r.tier)));
+    const known = materialisedTiers.get();
+    const dropped = Object.entries(known)
+        .filter(([tid]) => !planned.has(tid))
+        .map(([tid, v]) => ({ tierId: tid, ...v }));
+    if (plan.reads.length === 0 && dropped.length === 0)
+        return [];
+    const last = readSyncVersions.get();
+    const next = { ...last };
+    let sandbox = null;
+    const resynced = [];
+    const healed = []; // tierIds that were FAILED at start and now materialised
+    const stillFailed = { ...failedReadSilos.get() };
+    // REMOVAL half FIRST, so a turn that both drops one silo and refreshes another still narrows before it refreshes.
+    let removed = [];
+    const removedNames = [];
+    if (dropped.length > 0) {
+        sandbox = await openSandbox();
+        removed = await unmaterialiseDroppedTiers(sandbox, dropped);
+        if (removed.length > 0) {
+            const gone = new Set(removed);
+            for (const tid of removed) {
+                removedNames.push(known[tid].silo);
+                delete next[tid];
+                delete stillFailed[tid];
+            }
+            // Drop the persist baseline too: a tier the session may no longer read must not sit on the write path either.
+            writeBaseline.update((b) => Object.fromEntries(Object.entries(b).filter(([tid]) => !gone.has(tid))));
+            materialisedTiers.update((m) => Object.fromEntries(Object.entries(m).filter(([tid]) => !gone.has(tid))));
+            log(`turn.started UN-MATERIALISED ${removed.length} dropped tier(s) [${removed.join(", ")}] for ${p.key}`);
+        }
+    }
+    // Same per-silo isolation as session.started: one failing silo never blocks another.
+    for (const rm of plan.reads) {
+        const tid = tierId(rm.tier);
+        try {
+            const provider = providerById(rm.silo.provider);
+            if (!provider.tierVersion)
+                continue; // no cheap probe → never re-pull (cost floor)
+            const version = await provider.tierVersion(p, rm.tier, rm.silo, rm.access);
+            const lastSynced = last[tid];
+            if (lastSynced !== undefined && version === lastSynced)
+                continue; // UNCHANGED — skip
+            sandbox = await openSandbox();
+            if (rm.readOnly)
+                await refreshReadOnlyTier(sandbox, p, rm);
+            else
+                await refreshWritableTier(sandbox, p, rm);
+            next[tid] = version;
+            resynced.push(tid);
+            // A silo the plan gained MID-SESSION materialises here (no baseline ⇒ the version gate lets it
+            // through), so record it — otherwise the removal diff above could never see it drop again.
+            materialisedTiers.update((m) => ({ ...m, [tid]: { tier: rm.tier, silo: rm.silo.name, readOnly: rm.readOnly === true } }));
+            if (stillFailed[tid]) {
+                delete stillFailed[tid]; // a silo that FAILED at session.started just healed
+                healed.push(tid);
+            }
+        }
+        catch (err) {
+            log(`turn.started RE-SYNC FAILED for ${tid} ← ${rm.silo.name}/${rm.silo.provider} (other silos unaffected): ${String(err)}`);
+        }
+    }
+    if (resynced.length > 0) {
+        readSyncVersions.update(() => next);
+        log(`turn.started re-materialised ${resynced.length} advanced silo(s) [${resynced.join(", ")}] for ${p.key}`);
+    }
+    else if (removed.length > 0) {
+        readSyncVersions.update(() => next); // the removal alone still changed the baseline set
+    }
+    // The index follows the plan: the on-disk memory/MEMORY.md is rewritten when a failed silo HEALED or a tier was REMOVED, so the agent stops reading a map to silos that are not there.
+    // The memory.index_change row then carries the wake-delta push, which is the only signal this session gets on its next wake that the index moved.
+    if ((healed.length > 0 || removed.length > 0) && sandbox) {
+        failedReadSilos.update(() => stillFailed);
+        try {
+            const okReads = plan.reads.filter((r) => !stillFailed[tierId(r.tier)]);
+            const failedNames = plan.reads.filter((r) => stillFailed[tierId(r.tier)]).map((r) => r.silo.name);
+            const healedNames = plan.reads.filter((r) => healed.includes(tierId(r.tier))).map((r) => r.silo.name);
+            await sandbox.run({ command: unlockCommand("memory/MEMORY.md") });
+            await sandbox.writeTextFile({ path: "memory/MEMORY.md", content: renderMemoryIndex(okReads, failedNames) });
+            await lock(sandbox, "memory/MEMORY.md");
+            log(`turn.started refreshed the memory index for ${p.key}` +
+                `${healed.length ? ` — healed ${healed.length} previously-failed silo(s) [${healed.join(", ")}]` : ""}` +
+                `${removed.length ? ` — dropped ${removed.length} un-planned tier(s) [${removed.join(", ")}]` : ""}`);
+            // The PUSH breadcrumb — silo NAMES only (the taint rule), stamped with this session's own
+            // continuation token so the delta surfaces it to THIS session and no other. Best-effort.
+            try {
+                await appendAudit({
+                    org: p.org,
+                    platform: p.platform,
+                    workspace: p.workspace,
+                    surface: p.surface,
+                    principalId: binding.principalId,
+                    action: "memory.index_change",
+                    detail: {
+                        healed: healedNames,
+                        ...(removedNames.length ? { removed: removedNames } : {}),
+                        ...(ctx.channel?.continuationToken ? { continuationToken: ctx.channel.continuationToken } : {}),
+                    },
+                });
+            }
+            catch (err) {
+                log(`turn.started index_change audit skipped (index already refreshed on disk): ${String(err)}`);
+            }
+        }
+        catch (err) {
+            log(`turn.started index refresh failed (silo materialisation itself already applied): ${String(err)}`);
+        }
+    }
+    // Returns the tiers whose sandbox bytes this pass REPLACED: the provenance baseline must advance over them before the turn runs, or every line the re-sync pulled in reads as one this turn added.
+    return resynced;
+}
+// THE DURABLE PROVENANCE MARK: a baseline of line digests is captured once per session and diffed at every turn end, and a bullet the baseline did not hold takes an external-provenance mark when the turn ingested untrusted content.
+// It arms on the WRITE PLAN — a writable tier plus a sandbox — and never on the window grain, because the sandbox write tools can mount on a seat that is not task grain.
+/**
+ * Is the marking POSTURE on at all? With taint.mode off the whole path is disarmed, so an opted-out deployment does not even take the baseline read.
+ * This is the session-independent half of the arm; the write-plan half lives in provenanceTargets.
+ */
+function provenanceArmed() {
+    try {
+        return taintEnabled(); // OPE-399 — no marking posture, so not even a baseline read
+    }
+    catch {
+        return false; // unreadable posture ⇒ no mark, which is the direction that never over-claims
+    }
+}
+/** One preamble for both edges, so the arm rule, the write plan and the sandbox handle cannot drift apart between the capture and the diff. Null means this session marks nothing at all. */
+async function provenanceTargets(ctx) {
+    if (!provenanceArmed())
+        return null;
+    const p = resolvePartition(ctx);
+    const binding = bindFrom(ctx);
+    const plan = planFor(binding, p);
+    if (plan.writes.length === 0 || ctx.getSandbox === undefined)
+        return null;
+    return { p, principalId: binding.principalId, writes: plan.writes, sandbox: await ctx.getSandbox() };
+}
+/**
+ * Capture the baseline ONCE, at the first turn boundary and not at session.started: that handler materialises the tier itself, so a baseline taken there can hold the pre-materialisation empty tree and would mark every bullet the silo already holds.
+ * Fail-soft in one direction: any failure leaves the session UNARMED, and an unarmed session marks nothing.
+ */
+async function captureProvenanceBaseline(ctx) {
+    try {
+        if (provenanceBaseline.get().armed === true)
+            return; // already captured this session
+        const target = await provenanceTargets(ctx);
+        if (target === null)
+            return;
+        const tiers = {};
+        for (const rm of target.writes)
+            tiers[tierId(rm.tier)] = baselineOf(await readTierFromSandbox(target.sandbox, rm.tier));
+        provenanceBaseline.update(() => ({ armed: true, tiers }));
+        log(`provenance baseline captured for ${target.writes.length} writable tier(s)`);
+    }
+    catch (err) {
+        log(`provenance baseline capture SKIPPED — no bullet this session adds takes a mark: ${String(err)}`);
+    }
+}
+/**
+ * Advance the baseline over any writable tier the mid-session re-sync just re-materialised: those bytes are what other sessions persisted between turns, and without this the diff re-casts another session's fact as this turn's unverified claim.
+ * A tier whose re-read FAILS is dropped from the baseline instead, so it takes no mark this turn — under-marking is the smaller defect.
+ */
+async function rebaseProvenanceAfterResync(ctx, resynced) {
+    if (resynced.length === 0)
+        return;
+    const touched = new Set(resynced);
+    let target = null;
+    try {
+        // Not yet armed ⇒ the capture below reads the POST-re-sync tree anyway, so there is nothing stale
+        // to advance and no reason to pay a read.
+        if (provenanceBaseline.get().armed !== true)
+            return;
+        target = await provenanceTargets(ctx);
+        if (target === null)
+            return;
+    }
+    catch (err) {
+        log(`provenance re-base preamble failed, nothing advanced: ${String(err)}`);
+        return;
+    }
+    const advanced = [];
+    const dropped = [];
+    for (const rm of target.writes) {
+        const tid = tierId(rm.tier);
+        if (!touched.has(tid))
+            continue;
+        try {
+            const fresh = baselineOf(await readTierFromSandbox(target.sandbox, rm.tier));
+            provenanceBaseline.update((cur) => ({ ...cur, armed: true, tiers: { ...(cur.tiers ?? {}), [tid]: fresh } }));
+            advanced.push(tid);
+        }
+        catch (err) {
+            provenanceBaseline.update((cur) => ({ ...cur, armed: true, tiers: Object.fromEntries(Object.entries(cur.tiers ?? {}).filter(([k]) => k !== tid)) }));
+            dropped.push(tid);
+            log(`provenance re-base could not read ${tid}, so it takes NO mark this turn: ${String(err)}`);
+        }
+    }
+    if (advanced.length > 0 || dropped.length > 0) {
+        log(`provenance baseline re-based over ${advanced.length} re-synced tier(s)${dropped.length > 0 ? `, ${dropped.length} dropped` : ""}`);
+    }
+}
+/**
+ * Mark the bullets this turn ADDED when the turn ingested external content, then advance the baseline — which happens on EVERY turn, tainted or not, so a bullet added on a clean turn cannot take a mark on the next tainted one.
+ * Answers the tier ids whose sandbox bytes changed. Never throws: a failure answers nothing-changed, which withholds the turn-end persist rather than firing one on a guess.
+ */
+async function markProvenanceForTurn(ctx, where) {
+    const edited = [];
+    try {
+        const state = provenanceBaseline.get();
+        if (state.armed !== true)
+            return edited; // not a worker, or the baseline capture failed — nothing to diff
+        const target = await provenanceTargets(ctx);
+        if (target === null)
+            return edited;
+        const tainted = untrustedIngestedThisTurn();
+        const kinds = [...taintKindsThisTurn()];
+        const wording = tainted ? renderProvenanceWording(kinds) : { mark: "", attribution: "" };
+        const tiers = {};
+        const markedFiles = [];
+        let marked = 0;
+        for (const rm of target.writes) {
+            const tid = tierId(rm.tier);
+            const files = await readTierFromSandbox(target.sandbox, rm.tier);
+            let current = files;
+            // A tier the baseline never held — one that joined the plan mid-session — is RECORDED and not
+            // marked. Diffing it against `{}` would mark every bullet the silo already holds.
+            const held = state.tiers?.[tid];
+            if (held !== undefined && !sameBaseline(held, baselineOf(files)))
+                edited.push(tid);
+            if (tainted && held !== undefined) {
+                const pass = markAddedBullets(held, files, wording);
+                for (const [rel, content] of Object.entries(pass.files)) {
+                    await writeTierFile(target.sandbox, rm.tier, rel, content);
+                    markedFiles.push(`${tid}/${rel}`);
+                }
+                if (pass.marked > 0) {
+                    current = { ...files, ...pass.files };
+                    marked += pass.marked;
+                }
+            }
+            tiers[tid] = baselineOf(current);
+        }
+        provenanceBaseline.update((cur) => ({ ...cur, armed: true, tiers }));
+        if (marked === 0)
+            return edited;
+        log(`${where}: marked ${marked} added bullet(s) with external provenance in ${markedFiles.join(", ")}`);
+        // Names and counts only — never a marked LINE, which is memory content (the taint rule every
+        // other row on this plane follows).
+        try {
+            await appendAudit({
+                org: target.p.org,
+                platform: target.p.platform,
+                workspace: target.p.workspace,
+                surface: target.p.surface,
+                principalId: target.principalId,
+                action: "memory.provenance_marked",
+                detail: {
+                    where,
+                    bullets: marked,
+                    files: markedFiles,
+                    kinds,
+                    ...(ctx.session?.id ? { sessionId: ctx.session.id } : {}),
+                },
+            });
+        }
+        catch (err) {
+            log(`memory.provenance_marked audit skipped (the marks are already in the sandbox): ${String(err)}`);
+        }
+    }
+    catch (err) {
+        log(`${where}: provenance marking skipped (the turn is unaffected): ${String(err)}`);
+        // Report NO edit, however far the loop got. A throw part-way through leaves the baseline un-advanced, so a partly-filled report would fire the same persist on every following turn while that tier keeps failing.
+        // The edit is not lost: the next pass that completes sees it.
+        return [];
+    }
+    return edited;
+}
+/**
+ * Compares BASELINES, not bytes, so it UNDER-reports in two narrow shapes: deleting one copy of a duplicated line, and a change only in leading or trailing whitespace.
+ * It never OVER-reports, which is the direction that would put a provider write on a turn that changed nothing.
+ */
+function sameBaseline(a, b) {
+    const names = Object.keys(a);
+    if (names.length !== Object.keys(b).length)
+        return false;
+    for (const rel of names) {
+        const left = a[rel];
+        const right = b[rel];
+        if (left === undefined || right === undefined || left.length !== right.length)
+            return false;
+        for (let i = 0; i < left.length; i++)
+            if (left[i] !== right[i])
+                return false;
+    }
+    return true;
+}
+/**
+ * Tier ids this session EDITED and did not persist, because the fan-out guard held the flush closed.
+ *
+ * 🔴 IT EXISTS BECAUSE THE SKIP USED TO LOSE THE EDIT (OPE-1873). `markProvenanceForTurn` advances
+ * the provenance baseline for every tier it reports, and it runs BEFORE the flush decision — so once
+ * the guard skipped, the next turn's diff compared the edited bytes against themselves, found no
+ * change, and the edit had no route to the store left on this road at all. A seat that edited its
+ * tree on a turn holding a live delegated task therefore wrote nothing, audited nothing, and said
+ * nothing about it. That is one of the two shapes S-MEM-READ's "found 0" can take.
+ */
+const unflushedEdits = defineState("open-everywhere.memory.unflushedEdits", () => ({ tiers: [] }));
+/**
+ * Persist a tree this session edited ITSELF, at its own turn end, armed on an OBSERVED byte change so a turn that changed no tier pays no provider write.
+ * It skips while any delegated task is live (persisting mid-write publishes a torn file); a skipped edit is REMEMBERED in {@link unflushedEdits} and re-offered on the next turn, because the baseline has already advanced and no later diff would find it again.
+ */
+async function persistEditedTreeAtTurnEnd(ctx, where, editedThisTurn) {
+    // A tier skipped on an earlier turn is still edited, so it re-enters here until a persist RUNS.
+    let carried = [];
+    try {
+        carried = unflushedEdits.get().tiers;
+    }
+    catch {
+        /* an unreadable container costs the carry, never the turn */
+    }
+    const edited = [...new Set([...carried, ...editedThisTurn])];
+    if (edited.length === 0)
+        return;
+    try {
+        if (skipAsSubagentChild(ctx, where))
+            return;
+        const live = liveTaskIds();
+        if (live.length > 0) {
+            log(`${where}: tree edit in ${edited.join(", ")} NOT persisted — ${live.length} delegated task(s) may be mid-write [${live.join(", ")}]`);
+            // REMEMBER it. Dropping it here is what made the skip a silent lost write.
+            try {
+                unflushedEdits.update(() => ({ tiers: edited }));
+            }
+            catch (err) {
+                log(`${where}: 🔴 the skipped edit in ${edited.join(", ")} could NOT be remembered — no later turn re-offers it: ${String(err)}`);
+            }
+            return;
+        }
+        const flush = await persistMemoryNow(ctx, "edited");
+        // Cleared only once a persist RAN: a throw above leaves the carry in place, which is the
+        // direction that keeps the edit reachable.
+        try {
+            unflushedEdits.update(() => ({ tiers: [] }));
+        }
+        catch {
+            /* an unreadable container costs at most one extra no-op persist next turn */
+        }
+        log(`${where}: persisted this session's OWN edit to ${edited.join(", ")} — ${flush.persisted} file(s) across ${flush.silos} silo(s), ${flush.changed} changed`);
+        if (flush.failed > 0) {
+            log(`${where}: 🔴 ${flush.failed} silo(s) FAILED this persist — those bytes stay in the sandbox and NO later turn re-reports this edit (see the residual note)`);
+        }
+    }
+    catch (err) {
+        log(`${where}: the turn-end persist of this session's own edit failed (the bytes stay in the sandbox): ${String(err)}`);
+    }
+}
+/**
+ * Persist this session's memory tree NOW, inside the turn, because a member explicitly asked the
+ * agent to remember something (OPE-1915). Called immediately before a POST, at TWO doors: the two
+ * `reply` tool variants (`tools/reply.ts`), which are its only callers. Two terminal-prose planes
+ * used to carry an answer past it, and both are deleted: the addressed-mention bridge in
+ * `channels/unified.ts` (OPE-1982) and `postTerminalProse` (OPE-2006). On EITHER seat shape a
+ * delegated ask's settlement answer now leaves by one of the two doors (OPE-2013), and a per-surface
+ * turn's closing prose is dropped rather than posted — the residual `memory/write-intent.ts` states
+ * in full.
+ *
+ * 🔴 THE RESIDUAL, NAMED: `tools/message_thread_seat.ts`'s MIRROR POST also calls
+ * `postUnifiedReply`, it carries a `replyAuditFor` bag with a `turnId`, so the claim guard IS live
+ * on it — and no flush runs there. A remember-ask answered by a seat mirroring its own text into a
+ * thread seat therefore still meets the honest denial. It is left as it is rather than fixed here
+ * because that door posts a copy of text another door already delivered, so closing it is a
+ * question about the mirror, not about this road.
+ *
+ * 🔴 IT ADDS NO ROAD. It runs `persistMemoryNow` — `session-persist`, the same `memory.write` row,
+ * the same `turnId` stamp — at an earlier moment, so the row exists when
+ * `channels/memory-claim-guard.ts` reads the turn's write evidence. Before it, a seat's own edit had
+ * no in-turn route at all and the guard correctly struck a save the deployment had not yet made.
+ * The guard still decides on the LEDGER, never on the intent flag, so this can make an honest ack
+ * possible and can never make a false one pass.
+ *
+ * 🔴 THE FAN-OUT GUARD STILL HOLDS, and a held flush LEAVES THE INTENT ARMED. Persisting while a
+ * delegated child may be mid-write publishes a torn file to every other session on the silo
+ * (`hooks/settlement-flush.ts` states the same rule for its own edge). A skip therefore defers to the
+ * settlement flush or the `turn.completed` backstop, exactly as today, and the next reply re-offers
+ * the intent — dropping it here would be the lost-write shape {@link unflushedEdits} exists to stop.
+ * A persist whose silos all FAILED leaves it armed for the same reason, and there the re-offer is
+ * the only route left: see the note on the clear itself.
+ *
+ * Never throws: it runs on the reply path, and no memory persist may cost a member their answer.
+ */
+export async function flushWriteIntentMemory(ctx) {
+    if (!writeIntentArmed())
+        return null;
+    const live = liveTaskIds();
+    if (live.length > 0) {
+        log(`write-intent: NOT persisted before the reply — ${live.length} delegated task(s) may be mid-write [${live.join(", ")}]; the intent stays armed`);
+        return null;
+    }
+    try {
+        const flush = await persistMemoryNow(ctx, "write-intent");
+        // 🔴 CLEARED ONLY WHEN A DURABLE WRITE REALLY LANDED FOR THIS TURN, and the ledger is the judge.
+        // `factStoredThisTurn` is the exact read `channels/memory-claim-guard.ts` makes at the door, so
+        // the intent is spent by the same fact that earns the seat its sentence — never by the weaker
+        // "a persist ran" (OPE-2013). A delegated ask's FIRST post runs this persist over a tree the
+        // worker has not written yet: it changes nothing, writes no row, and clearing there is what
+        // left the settlement answer with no write in front of it.
+        //
+        // 🔴 A THROW ABOVE, AND A PERSIST WHOSE SILOS ALL FAILED, BOTH LEAVE THE INTENT ARMED. A failed
+        // provider write is the one case where nothing else re-offers the edit: `persistMemoryNow`
+        // advances the provenance baseline BEFORE it reads the tree, so `turn.completed`'s
+        // `persistEditedTreeAtTurnEnd` then sees no edited tier and the note stays in the sandbox for
+        // ever. Re-offering recovers it, because this flush re-reads the tree rather than the baseline.
+        // An idempotent second persist costs one no-op provider write.
+        const landed = factStoredThisTurn(currentTurnId(ctx));
+        if (flush.failed === 0 && landed)
+            consumeWriteIntent();
+        // …and a post that RAN the persist and landed nothing spends ONE of the ask's bounded attempts,
+        // so an ask the seat never writes anything for stops paying for a persist on every post.
+        // `memory/write-intent.ts` `MAX_UNSERVED_POSTS` carries the bound and its reasoning.
+        //
+        // 🔴 A FAILED OR THROWN PERSIST IS EXEMPT FROM THE BOUND, DELIBERATELY. Neither branch reaches
+        // this call, so such an ask stays armed with no attempt spent and does persist before every post
+        // for the session's life. That is the price of the paragraph above: on a failed provider write
+        // the re-offer is the ONLY route left to those bytes, and a bound that retired the ask would
+        // lose them. A silo that keeps failing costs one read per post; a silo that recovers spends the
+        // ask on the first post that lands.
+        else if (flush.failed === 0)
+            noteUnservedPost();
+        log(`write-intent: persisted before the reply — ${flush.persisted} file(s) across ${flush.silos} silo(s), ${flush.changed} changed, ${flush.failed} failed` +
+            `${flush.failed > 0 || !landed ? " — the intent STAYS ARMED (or retires on its bound), so the next post re-offers the write" : ""}`);
+        return flush;
+    }
+    catch (err) {
+        log(`write-intent: the in-turn persist failed (the turn-end backstop still persists this tree, and the reply will say the save is not recorded): ${String(err)}`);
+        return null;
+    }
+}
+export default defineHook({
+    events: {
+        "session.started": async (_event, ctx) => {
+            if (skipAsSubagentChild(ctx, "session.started"))
+                return;
+            // MEASUREMENT (memory/sync-timing.ts): null unless OE_MEMORY_SYNC_TIMING=1, so with the flag off nothing below allocates, reads a clock, counts bytes or adds an await.
+            // Constructed FIRST, so hookMs covers the binding, partition and plan resolution too.
+            const timing = startMemorySyncTiming();
+            try {
+                const binding = bindFrom(ctx);
+                const p = resolvePartition(ctx);
+                const plan = planFor(binding, p);
+                // Audit the trust GATE firing: a fail-closed external binding is a governance action the deployment took, recorded ONCE per session and never per wake.
+                // Taint-clean — only the mode, the read count, the composed reason and the session id, never memory CONTENT. Local sessions are exempt, and the audit never blocks.
+                if (binding.trust === "external" && binding.platform !== "local") {
+                    try {
+                        await appendAudit({
+                            org: p.org,
+                            platform: p.platform,
+                            workspace: p.workspace,
+                            surface: p.surface,
+                            principalId: binding.principalId,
+                            action: "memory.trust_gate",
+                            detail: { mode: binding.mode, reads: plan.reads.length, reason: plan.reason, ...(ctx.session?.id ? { sessionId: ctx.session.id } : {}) },
+                        });
+                    }
+                    catch (err) {
+                        log(`session.started trust_gate audit skipped: ${String(err)}`);
+                    }
+                }
+                if (plan.reads.length === 0) {
+                    log(`session.started: no memory synced — ${plan.reason}`);
+                    // Record the empty case too: an empty plan means this hook never calls getSandbox, so such a session's bootMs measures something else entirely.
+                    if (timing)
+                        await emitMemorySyncTiming(p, binding.principalId, timing.finish(ctx.session?.id ?? null));
+                    return;
+                }
+                if (plan.writes.length > 0) {
+                    const tBaseline = timing ? timing.now() : 0;
+                    const baselines = {};
+                    for (const rm of plan.writes) {
+                        // PER-SILO ISOLATION here too: one write silo whose provider is down must not throw past the read loop and leave the session with no silo materialised and no MEMORY.md index.
+                        // An unrecorded baseline is fail-soft in the SAFE direction — at persist time every host file then looks changed-since-start, so a genuine concurrent edit is preserved as a .conflict- sibling rather than clobbered.
+                        try {
+                            const provider = providerById(rm.silo.provider);
+                            baselines[tierId(rm.tier)] = hashFiles(await provider.readTier(p, rm.tier, rm.silo, rm.access));
+                        }
+                        catch (err) {
+                            log(`write-baseline FAILED for ${tierId(rm.tier)} ← ${rm.silo.name}/${rm.silo.provider} (sync continues; persist will treat every file as concurrently-changed): ${String(err)}`);
+                        }
+                    }
+                    writeBaseline.update(() => baselines);
+                    timing?.mark("baseline", tBaseline);
+                }
+                const tSandbox = timing ? timing.now() : 0;
+                const sandbox = await ctx.getSandbox();
+                timing?.mark("sandbox", tSandbox);
+                let synced = 0;
+                // PER-SOURCE ISOLATION: each silo loads independently, so one failing source degrades to THAT silo being absent instead of aborting the loop and skipping the MEMORY.md index write.
+                // Failures are named in the index, so the agent knows the silo is MISSING, not empty.
+                const okReads = [];
+                const failedReads = [];
+                const failedTiers = {}; // tierId → silo name (for the heal-refresh)
+                for (const rm of plan.reads) {
+                    const tLoad = timing ? timing.now() : 0;
+                    let tSync = 0;
+                    let tLock = 0;
+                    try {
+                        const files = await loadSource(p, rm);
+                        tSync = timing ? timing.now() : 0;
+                        await syncTierIntoSandbox(sandbox, rm.tier, files);
+                        tLock = timing ? timing.now() : 0;
+                        synced += Object.keys(files).length;
+                        if (rm.readOnly)
+                            await lock(sandbox, tierSandboxDir(rm.tier));
+                        // Names + counts + sizes + durations. `byteSize` measures the materialised set; the
+                        // contents are not retained past this line (memory/sync-timing.ts taint rule).
+                        timing?.silo({
+                            silo: rm.silo.name,
+                            tier: tierId(rm.tier),
+                            provider: rm.silo.provider,
+                            readOnly: rm.readOnly === true,
+                            loadMs: tSync - tLoad,
+                            syncMs: tLock - tSync,
+                            lockMs: rm.readOnly ? timing.now() - tLock : null,
+                            files: Object.keys(files).length,
+                            bytes: byteSize(files),
+                            ok: true,
+                        });
+                        okReads.push(rm);
+                    }
+                    catch (err) {
+                        failedReads.push(rm.silo.name);
+                        failedTiers[tierId(rm.tier)] = rm.silo.name;
+                        // A silo that FAILS still spent boot time, so record what is known. NO error text — a provider error can quote a response body, which a timing row may not carry.
+                        // Minus one marks never-reached.
+                        timing?.silo({
+                            silo: rm.silo.name,
+                            tier: tierId(rm.tier),
+                            provider: rm.silo.provider,
+                            readOnly: rm.readOnly === true,
+                            loadMs: (tSync || timing.now()) - tLoad,
+                            syncMs: tSync ? timing.now() - tSync : -1,
+                            lockMs: null,
+                            files: 0,
+                            bytes: 0,
+                            ok: false,
+                        });
+                        log(`SYNC FAILED for ${tierId(rm.tier)} ← ${rm.silo.name}/${rm.silo.provider} (other silos unaffected): ${String(err)}`);
+                    }
+                }
+                // The top-level index is host-generated and never agent-edited, so it is locked read-only too.
+                const tIndex = timing ? timing.now() : 0;
+                await sandbox.writeTextFile({ path: "memory/MEMORY.md", content: renderMemoryIndex(okReads, failedReads) });
+                await lock(sandbox, "memory/MEMORY.md");
+                timing?.mark("index", tIndex);
+                // THE ROOT FENCE, LAST — every planned tier and the index exist by now, so taking write off memory/ costs the agent nothing it is allowed to do. A new entry under the root then fails with EACCES instead of landing where persistMemoryNow never reads.
+                // See memory/root-fence.ts for why this is not recursive and is a fail-loud guardrail, not a security boundary.
+                if (!(await lockMemoryRoot(sandbox)))
+                    log("memory root fence NOT applied (chmod failed) — a shell write into an unowned silo would be dropped silently, as before OPE-999");
+                if (resyncArmed(ctx)) {
+                    const tVersions = timing ? timing.now() : 0;
+                    await recordReadVersions(p, okReads);
+                    failedReadSilos.update(() => failedTiers);
+                    // Record only the silos that actually materialised: a silo that FAILED to sync has no files to remove, and listing it here would make its first successful heal look like a removal.
+                    materialisedTiers.update(() => Object.fromEntries(okReads.map((r) => [tierId(r.tier), { tier: r.tier, silo: r.silo.name, readOnly: r.readOnly === true }])));
+                    warnGitlessReadSilos(plan.reads);
+                    timing?.mark("versions", tVersions);
+                }
+                log(`synced ${synced} file(s) across [${okReads.map((r) => tierId(r.tier)).join(", ")}] for ${p.key} (${plan.reason})` +
+                    `${failedReads.length ? ` — ${failedReads.length} silo(s) FAILED to sync: ${failedReads.join(", ")}` : ""}`);
+                // LAST, so hookMs covers everything above. The row's own insert sits inside the boot window, which is why this measurement is flag-gated and not always on.
+                if (timing)
+                    await emitMemorySyncTiming(p, binding.principalId, timing.finish(ctx.session?.id ?? null));
+            }
+            catch (err) {
+                log(`session.started sync skipped: ${String(err)}`);
+            }
+        },
+        // Supervisor-only mid-session re-materialisation; an unarmed session returns before any provider, sandbox or state touch.
+        // eve awaits this BEFORE the turn's model step, so the refreshed files are what the agent greps this very turn.
+        "turn.started": async (_event, ctx) => {
+            let resynced = [];
+            if (resyncArmed(ctx)) {
+                try {
+                    resynced = await resyncSupervisorReads(ctx);
+                }
+                catch (err) {
+                    log(`turn.started re-sync skipped: ${String(err)}`);
+                }
+            }
+            // AFTER the re-sync and BEFORE the capture below, and the order is the whole point: the re-sync replaces a writable tier's sandbox bytes, so an already-armed session's baseline is stale the instant it returns.
+            // A no-op, not one sandbox call, whenever nothing re-synced.
+            try {
+                await rebaseProvenanceAfterResync(ctx, resynced);
+            }
+            catch (err) {
+                log(`provenance re-base skipped: ${String(err)}`);
+            }
+            await captureProvenanceBaseline(ctx);
+        },
+        "message.received": (event, _ctx) => {
+            const current = sessionLog.get();
+            if (!current.firstMessage && typeof event.data?.message === "string") {
+                sessionLog.update((s) => ({ ...s, firstMessage: event.data.message }));
+            }
+            // OPE-1915 — an explicit remember-ask arms the in-turn persist {@link flushWriteIntentMemory}
+            // runs at the reply door. EVERY inbound message is read, not only the session's first: a member
+            // asks the agent to remember something mid-conversation far more often than on the opening line.
+            noteWriteIntent(typeof event.data?.message === "string" ? event.data.message : undefined);
+        },
+        // session.completed fires for NO session on this build (measured on prod over 36 h, 9 sessions and 67 turns), so these two arms are unreachable today. They stay because an eve change makes them fire again, and keeping them costs one idempotent no-op persist.
+        // Ordering against another hook file's own turn.completed backstop needs no guarantee: persistMemoryNow marks BEFORE it reads the tree, so whichever handler runs first, no persist carries unmarked bytes away.
+        "turn.completed": async (_event, ctx) => {
+            await persistEditedTreeAtTurnEnd(ctx, "turn.completed", await markProvenanceForTurn(ctx, "turn.completed"));
+        },
+        // A turn that FAILED may still have written the file before it failed, so it takes both the mark and the persist.
+        "turn.failed": async (_event, ctx) => {
+            await persistEditedTreeAtTurnEnd(ctx, "turn.failed", await markProvenanceForTurn(ctx, "turn.failed"));
+        },
+        "session.completed": async (_event, ctx) => {
+            await persistMemoryNow(ctx, "completed");
+        },
+        "session.failed": async (_event, ctx) => {
+            await persistMemoryNow(ctx, "failed");
+        },
+    },
+});
+//# sourceMappingURL=memory.js.map