@cursor/july 0.2.0 → 0.2.1

package/dist/internal/store-api-protocol.js

@@ -0,0 +1,126 @@
+/**
+ * Domain-call wire contract for the factory store API:
+ * `POST /internal/agentsdk/store/api/<call>` carrying a versioned JSON
+ * envelope `{ v, call, payload }`. This is the lane where the **server** owns
+ * the storage pattern (journal sharding, rotation, compaction), so a
+ * pathological pattern is fixable in a backend deploy instead of a July
+ * release plus a rebake of every deployment. The verb lane (`/flush`,
+ * `/read`, `/list`) keeps carrying bulk presigned file IO.
+ *
+ * Deliberately duplicated on the backend
+ * (`backend/server/src/factory/agent-sdk/agentsdkStoreApiProtocol.ts`): this
+ * package is published to npm, so the backend cannot depend on it and it
+ * cannot depend on backend packages. A backend drift test compares the two
+ * sources — same shape as the hosted-delivery protocol twins — which is why
+ * every exported constant here stays a single `export const NAME = <literal>;`
+ * line and every schema field stays on its own line.
+ *
+ * Evolution rules (the compat contract): additive optional fields only; no
+ * renames, no retypes, no semantic reuse of an old field; unknown fields are
+ * ignored, never rejected; removing a field means deprecating it in place
+ * forever. A breaking change means a new `v`, and the server keeps serving
+ * every previous `v`.
+ */
+import { z } from "zod";
+export const STORE_API_PROTOCOL_VERSION = 1;
+/** Path family on the factory surface; one segment per call. */
+export const STORE_API_PATH = "/internal/agentsdk/store/api";
+export const STORE_API_MEMORY_APPEND_CALL = "memory.append";
+/**
+ * Semantic cap on one serialized memory record. Text fields are truncated
+ * client-side (`memoryHook` default 2000 chars per field), so a well-formed
+ * record is a few KiB; 16 KiB is generous headroom, not a target. The cap is
+ * part of the wire contract but rides the layers, not the schema: the
+ * backend's store controller enforces it as a typed 4xx, and the store API
+ * client (`cursor/store-api-client.ts`) pre-checks it before spending a
+ * doomed request.
+ */
+export const MEMORY_APPEND_MAX_RECORD_BYTES = 16 * 1024;
+/** Serialized size of a record, as counted against the byte cap. */
+export function serializedRecordBytes(record) {
+    return new TextEncoder().encode(JSON.stringify(record)).byteLength;
+}
+/**
+ * Wire schema for {@link TurnMemoryRecordWire}. Per-field caps are
+ * deliberately absent: the client truncates text at authoring time and
+ * {@link MEMORY_APPEND_MAX_RECORD_BYTES} bounds the whole record.
+ */
+export const turnMemoryRecordWireSchema = z
+    .object({
+    at: z.string().min(1),
+    sessionId: z.string().min(1),
+    channelId: z.string().min(1),
+    status: z.enum(["completed", "failed"]),
+    title: z.string().optional(),
+    sdkAgentId: z.string().optional(),
+    userMessage: z.string().optional(),
+    result: z.string().optional(),
+    usage: z.object({}).passthrough().optional(),
+})
+    .passthrough();
+/**
+ * `memory.append` payload shape. The agent name becomes a store key segment
+ * on the server, so it must be exactly one segment. Unknown payload fields
+ * are stripped (= ignored), per the evolution rules. The byte cap is
+ * semantics, not shape — the backend's store controller owns it.
+ */
+export const memoryAppendPayloadSchema = z.object({
+    agent: z
+        .string()
+        .min(1)
+        .max(256)
+        .refine(name => !name.includes("/") &&
+        !name.includes("\\") &&
+        name !== "." &&
+        name !== "..", { message: "agent must be a single store key segment" }),
+    record: turnMemoryRecordWireSchema,
+});
+/** The whole request body. Unknown envelope fields are stripped (= ignored). */
+export const memoryAppendEnvelopeSchema = z.object({
+    v: z.literal(STORE_API_PROTOCOL_VERSION),
+    call: z.literal(STORE_API_MEMORY_APPEND_CALL),
+    payload: memoryAppendPayloadSchema,
+});
+/**
+ * Success body. Failures answer the store surface's standard error JSON
+ * (`{ code, error }`) with a matching HTTP status.
+ */
+export const memoryAppendResponseSchema = z.object({
+    v: z.literal(STORE_API_PROTOCOL_VERSION),
+    ok: z.literal(true),
+});
+export const STORE_API_MEMORY_READ_CALL = "memory.read";
+/**
+ * `memory.read` payload shape — the same single-segment agent name rule as
+ * `memory.append`, since the name addresses the same journal key family.
+ */
+export const memoryReadPayloadSchema = z.object({
+    agent: z
+        .string()
+        .min(1)
+        .max(256)
+        .refine(name => !name.includes("/") &&
+        !name.includes("\\") &&
+        name !== "." &&
+        name !== "..", { message: "agent must be a single store key segment" }),
+});
+/** The whole request body. Unknown envelope fields are stripped (= ignored). */
+export const memoryReadEnvelopeSchema = z.object({
+    v: z.literal(STORE_API_PROTOCOL_VERSION),
+    call: z.literal(STORE_API_MEMORY_READ_CALL),
+    payload: memoryReadPayloadSchema,
+});
+/**
+ * Success body. Failures answer the store surface's standard error JSON
+ * (`{ code, error }`) with a matching HTTP status.
+ */
+export const memoryReadResponseSchema = z.object({
+    v: z.literal(STORE_API_PROTOCOL_VERSION),
+    ok: z.literal(true),
+    journal: z
+        .object({
+        url: z.string().min(1),
+        expiresAt: z.string().min(1),
+    })
+        .nullable(),
+});

package/dist/memory.d.ts

@@ -18,11 +18,16 @@
  *
  * On Cursor-managed hosting the default is {@link agentStoreMemoryBackend}:
  * the journal lives on the deployment's Agent Store (survives deploys,
- * visible on cloud VMs under the store mount) and is mirrored to
- * `<stateRoot>/memory/journal.jsonl` so the workspace symlink read path
- * keeps working for local-runtime turns.
+ * visible on cloud VMs under the store mount), written exclusively through
+ * the `memory.append` domain call — the server owns the journal pattern —
+ * and mirrored to `<stateRoot>/memory/journal.jsonl` (hydrated per session
+ * via `memory.read`, appended locally per turn) so the workspace symlink
+ * read path keeps working for local-runtime turns. The
+ * `factory-api-v1` pin file exists only on hosted pods — plain local dev
+ * runs {@link fileMemoryBackend} and never sees the hosted lane.
  */
-import { type FileSink } from "./files.js";
+import { type CursorHostedFilesOptions } from "./files-backends/cursor-hosted.js";
+import { type StoreApiClient } from "./internal/cursor/store-api-client.js";
 import type { HookDefinition, TurnUsage } from "./types.js";
 /** Name of the shared memory directory under the agent state root. */
 export declare const MEMORY_DIR_NAME = "memory";
@@ -49,6 +54,16 @@ export interface MemoryBackend {
         stateRoot: string;
         agentName: string;
     }): Promise<void>;
+    /**
+     * Optional session-start hook: bring the backend's local read path up to
+     * date before the session's first turn reads it. A freshness upgrade, not
+     * a correctness gate — implementations soft-fail and keep whatever read
+     * state already exists.
+     */
+    prepareSession?(ctx: {
+        stateRoot: string;
+        agentName: string;
+    }): Promise<void>;
 }
 export interface FileMemoryBackendOptions {
     /**
@@ -64,20 +79,40 @@ export interface FileMemoryBackendOptions {
  */
 export declare function fileMemoryBackend(options?: FileMemoryBackendOptions): MemoryBackend;
 export interface AgentStoreMemoryBackendOptions {
-    /** Sink override (tests). Defaults to the deployment's Agent Store. */
-    sink?: FileSink;
-    /** Rotation threshold, same meaning as {@link FileMemoryBackendOptions}. */
+    /**
+     * Local mirror rotation threshold, same meaning as
+     * {@link FileMemoryBackendOptions}. The durable journal's rotation is the
+     * server's (`memory.append` controller), not this.
+     */
     maxJournalBytes?: number;
-    /** Backoff sleep override (tests). */
-    sleep?: (ms: number) => Promise<void>;
-    /** Jitter source override (tests). Returns [0, 1). */
-    random?: () => number;
+    /**
+     * Cursor-hosted transport overrides (tests): base URL, credential, store
+     * source id, protocol pin, fetch. Feeds the default
+     * {@link storeApiClient} and the lane-availability check.
+     */
+    hosted?: CursorHostedFilesOptions;
+    /**
+     * Domain-lane client override (tests). Defaults to
+     * {@link createStoreApiClient} over {@link hosted} — the module that owns
+     * the `memory.append` / `memory.read` transport, typed errors, and
+     * bounded backoff.
+     */
+    storeApiClient?: StoreApiClient;
 }
 /**
  * Journal on the deployment's Agent Store — durable across deploys, visible
- * on cloud VMs under the store mount. Appends are read-modify-write with
- * etag preconditions (retried on a lost race), then mirrored to
- * `<stateRoot>/memory/journal.jsonl` for the workspace symlink read path.
+ * on cloud VMs under the store mount, written exclusively through the
+ * `memory.append` domain call: the server owns the journal's storage
+ * pattern (Redis-buffered flush, rotation), so a pathological pattern is
+ * fixable in a backend deploy instead of a July release plus a rebake.
+ *
+ * There is no client-composed fallback. The read-modify-write CAS lane that
+ * predated the domain call (and caused the 2026-09-18 Agent Store read
+ * storm) was removed in 0.2.1 together with v2 hosting binding the
+ * `factory-api-v1` pin unconditionally and refusing artifacts frozen on an
+ * older July. A hosted pod without the pin is therefore a misconfiguration
+ * (a server predating the pin change, or a local env naming a hosted store
+ * without one): records are dropped loudly, never written client-side.
  */
 export declare function agentStoreMemoryBackend(options?: AgentStoreMemoryBackendOptions): MemoryBackend;
 export interface MemoryHookOptions {

package/dist/memory.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAKH,OAAO,EAAqC,KAAK,QAAQ,EAAE,MAAM,YAAY,CAAC;AAM9E,OAAO,KAAK,EAAe,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzE,sEAAsE;AACtE,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,UAAU,CACR,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAC5C,OAAO,CAAC,IAAI,CAAC,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,aAAa,CAgCf;AAED,MAAM,WAAW,8BAA8B;IAC7C,uEAAuE;IACvE,IAAI,CAAC,EAAE,QAAQ,CAAC;IAChB,4EAA4E;IAC5E,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,sCAAsC;IACtC,KAAK,CAAC,EAAE,CAAC,EAAE,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtC,sDAAsD;IACtD,MAAM,CAAC,EAAE,MAAM,MAAM,CAAC;CACvB;AAsBD;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,8BAAmC,GAC3C,aAAa,CAgFf;AAqBD,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CA0F1E"}
+{"version":3,"file":"memory.d.ts","sourceRoot":"","sources":["../src/memory.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2BG;AAMH,OAAO,EACL,KAAK,wBAAwB,EAE9B,MAAM,mCAAmC,CAAC;AAE3C,OAAO,EAGL,KAAK,cAAc,EACpB,MAAM,uCAAuC,CAAC;AAC/C,OAAO,KAAK,EAAe,cAAc,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzE,sEAAsE;AACtE,eAAO,MAAM,eAAe,WAAW,CAAC;AAExC,gDAAgD;AAChD,MAAM,MAAM,gBAAgB,GAAG;IAC7B,+CAA+C;IAC/C,EAAE,EAAE,MAAM,CAAC;IACX,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,WAAW,GAAG,QAAQ,CAAC;IAC/B,+CAA+C;IAC/C,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4EAA4E;IAC5E,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,KAAK,CAAC,EAAE,SAAS,CAAC;CACnB,CAAC;AAEF,kFAAkF;AAClF,MAAM,WAAW,aAAa;IAC5B,UAAU,CACR,MAAM,EAAE,gBAAgB,EACxB,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAC5C,OAAO,CAAC,IAAI,CAAC,CAAC;IACjB;;;;;OAKG;IACH,cAAc,CAAC,CAAC,GAAG,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,SAAS,EAAE,MAAM,CAAA;KAAE,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;CAC/E;AAED,MAAM,WAAW,wBAAwB;IACvC;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,iBAAiB,CAC/B,OAAO,GAAE,wBAA6B,GACrC,aAAa,CAgCf;AAED,MAAM,WAAW,8BAA8B;IAC7C;;;;OAIG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB;;;;OAIG;IACH,MAAM,CAAC,EAAE,wBAAwB,CAAC;IAClC;;;;;OAKG;IACH,cAAc,CAAC,EAAE,cAAc,CAAC;CACjC;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,uBAAuB,CACrC,OAAO,GAAE,8BAAmC,GAC3C,aAAa,CAiMf;AAqBD,MAAM,WAAW,iBAAiB;IAChC,+DAA+D;IAC/D,OAAO,CAAC,EAAE,aAAa,CAAC;IACxB,yEAAyE;IACzE,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAMD;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,OAAO,GAAE,iBAAsB,GAAG,cAAc,CA4G1E"}

package/dist/memory.js

@@ -18,9 +18,13 @@
  *
  * On Cursor-managed hosting the default is {@link agentStoreMemoryBackend}:
  * the journal lives on the deployment's Agent Store (survives deploys,
- * visible on cloud VMs under the store mount) and is mirrored to
- * `<stateRoot>/memory/journal.jsonl` so the workspace symlink read path
- * keeps working for local-runtime turns.
+ * visible on cloud VMs under the store mount), written exclusively through
+ * the `memory.append` domain call — the server owns the journal pattern —
+ * and mirrored to `<stateRoot>/memory/journal.jsonl` (hydrated per session
+ * via `memory.read`, appended locally per turn) so the workspace symlink
+ * read path keeps working for local-runtime turns. The
+ * `factory-api-v1` pin file exists only on hosted pods — plain local dev
+ * runs {@link fileMemoryBackend} and never sees the hosted lane.
  */
 var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
     function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
@@ -34,9 +38,10 @@ var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, ge
 import { randomUUID } from "node:crypto";
 import { appendFile, mkdir, rename, stat, writeFile } from "node:fs/promises";
 import { join } from "node:path";
-import { agentStoreKeys, FileConflictError } from "./files.js";
-import { cursorHostedFiles, isCursorHostedFilesAvailable, } from "./files-backends/cursor-hosted.js";
+import { agentStoreKeys } from "./files.js";
+import { isCursorHostedFilesAvailable, } from "./files-backends/cursor-hosted.js";
 import { defineHook } from "./hooks.js";
+import { createStoreApiClient, isStoreApiLaneEnabled, } from "./internal/cursor/store-api-client.js";
 /** Name of the shared memory directory under the agent state root. */
 export const MEMORY_DIR_NAME = "memory";
 /**
@@ -80,93 +85,189 @@ export function fileMemoryBackend(options = {}) {
         },
     };
 }
-/**
- * CAS attempts per append. The journal is one deployment-wide key written by
- * every engine pod, so under concurrent turn traffic the etag precondition
- * loses races routinely; each retry needs headroom to land.
- */
-const MEMORY_CAS_MAX_ATTEMPTS = 5;
-/**
- * Jittered exponential backoff between CAS attempts. Retrying immediately is
- * a fleet-wide stampede: every losing pod re-GETs the full journal and
- * re-PUTs in lockstep, which multiplied reads ~65x on one deployment during
- * the 2026-09-18 Agent Store read storm and tripped the store's
- * per-service-account read limit (every pod shares the deployment
- * credential). Jitter desynchronizes the writers so most retries land on the
- * first or second attempt.
- */
-function memoryCasBackoffMs(attempt, random) {
-    return 100 * Math.pow(2, attempt) * (0.5 + random());
-}
 /**
  * Journal on the deployment's Agent Store — durable across deploys, visible
- * on cloud VMs under the store mount. Appends are read-modify-write with
- * etag preconditions (retried on a lost race), then mirrored to
- * `<stateRoot>/memory/journal.jsonl` for the workspace symlink read path.
+ * on cloud VMs under the store mount, written exclusively through the
+ * `memory.append` domain call: the server owns the journal's storage
+ * pattern (Redis-buffered flush, rotation), so a pathological pattern is
+ * fixable in a backend deploy instead of a July release plus a rebake.
+ *
+ * There is no client-composed fallback. The read-modify-write CAS lane that
+ * predated the domain call (and caused the 2026-09-18 Agent Store read
+ * storm) was removed in 0.2.1 together with v2 hosting binding the
+ * `factory-api-v1` pin unconditionally and refusing artifacts frozen on an
+ * older July. A hosted pod without the pin is therefore a misconfiguration
+ * (a server predating the pin change, or a local env naming a hosted store
+ * without one): records are dropped loudly, never written client-side.
  */
 export function agentStoreMemoryBackend(options = {}) {
-    var _a, _b, _c, _d;
-    const sink = (_a = options.sink) !== null && _a !== void 0 ? _a : cursorHostedFiles();
+    var _a, _b, _c;
+    const hosted = (_a = options.hosted) !== null && _a !== void 0 ? _a : {};
     const maxJournalBytes = (_b = options.maxJournalBytes) !== null && _b !== void 0 ? _b : 5 * 1024 * 1024;
-    const sleep = (_c = options.sleep) !== null && _c !== void 0 ? _c : ((ms) => new Promise(resolve => setTimeout(resolve, ms)));
-    const random = (_d = options.random) !== null && _d !== void 0 ? _d : Math.random;
-    // Appends are chained per journal key (same shape as fileMemoryBackend);
-    // a failed append must not poison the chain for later turns. The chain
-    // serializes appends within this pod only — pods race each other on the
-    // shared key, which is what the CAS retry (with backoff) absorbs.
+    // Mirror work is chained per journal key (same shape as
+    // fileMemoryBackend): hydration and appends on one agent's mirror never
+    // interleave, and a failed step must not poison the chain for later turns.
     const appendChains = new Map();
-    const append = (record, ctx) => __awaiter(this, void 0, void 0, function* () {
-        const key = agentStoreKeys.memoryJournal(ctx.agentName);
-        const line = Buffer.from(`${JSON.stringify(record)}\n`, "utf8");
-        for (let attempt = 0; attempt < MEMORY_CAS_MAX_ATTEMPTS; attempt += 1) {
-            const current = yield sink.get(key);
-            const currentBody = current === undefined
-                ? new Uint8Array(0)
-                : current instanceof Uint8Array
-                    ? current
-                    : current.body;
-            const etag = current === undefined || current instanceof Uint8Array
-                ? undefined
-                : current.etag;
-            let next;
-            let rotatedStamp;
-            if (currentBody.byteLength >= maxJournalBytes) {
-                rotatedStamp = `${Date.now()}-${randomUUID().slice(0, 8)}`;
-                yield sink.put(agentStoreKeys.memoryJournalRotated(ctx.agentName, rotatedStamp), currentBody, { ifMatch: null });
-                next = line;
-            }
-            else {
-                next = Buffer.concat([currentBody, line]);
-            }
-            try {
-                yield sink.put(key, next, {
-                    ifMatch: current === undefined ? null : etag,
+    // Transport, envelope, typed errors, and bounded backoff all live in the
+    // client; this module only decides which lane an append takes.
+    const storeApiClient = (_c = options.storeApiClient) !== null && _c !== void 0 ? _c : createStoreApiClient(hosted);
+    /**
+     * The domain lane still owes local-runtime sessions their read path:
+     * cloud-runtime turns read the journal through the store mount, but
+     * local-runtime turns on hosted pods (the default `runtime: "local"`)
+     * read `<stateRoot>/memory/journal.jsonl` via the workspace symlink, and
+     * on hosting the only writer of that file is this backend. So the lane
+     * keeps the mirror live without reintroducing the CAS read pattern:
+     * hydrate it once from the store when the file is absent (a fresh pod
+     * after a deploy), then append each successfully posted record locally,
+     * rotating at {@link maxJournalBytes} like {@link fileMemoryBackend}.
+     * Server-buffered records not yet flushed when a pod hydrates are the
+     * lane's documented staleness window (~30 s / 64 KiB), and other pods'
+     * appends surface on the next hydration — advisory memory, same envelope
+     * as the server side.
+     */
+    const hydratedMirrors = new Set();
+    let mirrorRotationSeq = 0;
+    const maintainLocalMirror = (record, ctx) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b;
+        const dir = join(ctx.stateRoot, MEMORY_DIR_NAME);
+        const path = join(dir, "journal.jsonl");
+        if (!hydratedMirrors.has(path)) {
+            // Appends are chained per journal key, so this guard never races
+            // itself for one agent. Backstop for a session that appended before
+            // any prepareSession hydration ran (e.g. a custom hook ordering).
+            hydratedMirrors.add(path);
+            const existing = yield stat(path).catch(() => undefined);
+            if (existing === undefined) {
+                const content = yield storeApiClient.memoryReadContent({
+                    agent: ctx.agentName,
                 });
-            }
-            catch (error) {
-                if (error instanceof FileConflictError &&
-                    attempt < MEMORY_CAS_MAX_ATTEMPTS - 1) {
-                    yield sleep(memoryCasBackoffMs(attempt, random));
-                    continue;
+                if (content !== undefined) {
+                    yield mirrorJournalLocally(ctx.stateRoot, content);
                 }
-                throw error;
-            }
-            yield mirrorJournalLocally(ctx.stateRoot, next);
-            if (rotatedStamp !== undefined) {
-                // Rotated segments sit beside the live journal locally too, so the
-                // workspace symlink read path keeps pre-rotation history.
-                yield writeFile(join(ctx.stateRoot, MEMORY_DIR_NAME, `journal-${rotatedStamp}.jsonl`), currentBody);
             }
+        }
+        yield mkdir(dir, { recursive: true });
+        const size = (_b = (_a = (yield stat(path).catch(() => undefined))) === null || _a === void 0 ? void 0 : _a.size) !== null && _b !== void 0 ? _b : 0;
+        if (size >= maxJournalBytes) {
+            mirrorRotationSeq += 1;
+            yield rename(path, join(dir, `journal-${Date.now()}-${mirrorRotationSeq}.jsonl`));
+        }
+        yield appendFile(path, `${JSON.stringify(record)}\n`, "utf8");
+    });
+    /**
+     * One `memory.append` domain call; the server appends to the server-owned
+     * journal. On success the record is also appended to the local mirror so
+     * the workspace symlink read path stays live (see
+     * {@link maintainLocalMirror}).
+     *
+     * Failure policy: log and give up for this record. Memory is advisory and
+     * the hook runner treats an append failure as non-fatal to the turn;
+     * falling back to the CAS path per-record would reintroduce the write
+     * storm under exactly the server brownout that makes this call fail. A
+     * failed POST also skips the mirror — the mirror must never show a record
+     * the durable journal will not have.
+     */
+    const appendViaStoreApi = (record, ctx) => __awaiter(this, void 0, void 0, function* () {
+        try {
+            yield storeApiClient.memoryAppend({ agent: ctx.agentName, record });
+        }
+        catch (error) {
+            console.warn(`[agent-serve] memory.append dropped one record for "${ctx.agentName}": ${error instanceof Error ? error.message : String(error)}`);
             return;
         }
+        try {
+            yield maintainLocalMirror(record, ctx);
+        }
+        catch (error) {
+            console.warn(`[agent-serve] memory mirror update failed for "${ctx.agentName}" (journal record is durable): ${error instanceof Error ? error.message : String(error)}`);
+        }
+    });
+    /**
+     * Session-start hydration: one `memory.read` (flush-on-read server-side,
+     * so the pending buffer — including a burst another pod appended — lands
+     * first) and the mirror is rewritten to global state; the session then
+     * reads everything appended before it started. Soft-fail: a failed
+     * hydration keeps the existing mirror.
+     */
+    const hydrateMirror = (ctx) => __awaiter(this, void 0, void 0, function* () {
+        var _a;
+        var _b;
+        const path = join(ctx.stateRoot, MEMORY_DIR_NAME, "journal.jsonl");
+        try {
+            const content = yield storeApiClient.memoryReadContent({
+                agent: ctx.agentName,
+            });
+            if (content !== undefined) {
+                // Never regress the read path: every mirrored record was
+                // server-acked before it was written locally, so a download SHORTER
+                // than the mirror means the server's flush-on-read was degraded (a
+                // busy lock, a Redis outage — the acked tail is still buffered) or
+                // the journal rotated. Keeping the richer mirror loses nothing;
+                // rewriting would hide records the agent has already seen.
+                const mirroredBytes = (_b = (_a = (yield stat(path).catch(() => undefined))) === null || _a === void 0 ? void 0 : _a.size) !== null && _b !== void 0 ? _b : 0;
+                if (content.byteLength >= mirroredBytes) {
+                    yield mirrorJournalLocally(ctx.stateRoot, content);
+                }
+            }
+            // Either way the read answered: skip the append path's absent-file
+            // hydration for the rest of this process.
+            hydratedMirrors.add(path);
+        }
+        catch (error) {
+            console.warn(`[agent-serve] memory hydration failed for "${ctx.agentName}" (keeping the existing mirror): ${error instanceof Error ? error.message : String(error)}`);
+        }
     });
+    /**
+     * Hosted pods carry the pin and a provisioned store by construction (v2
+     * hosting binds `factory-api-v1` unconditionally and refuses pre-0.2.1
+     * artifacts). Reaching this without them means a misconfigured
+     * environment; there is no client-side write to fall back to.
+     */
+    const refuseMisconfiguredLane = (agentName, verb) => {
+        console.error(`[agent-serve] memory ${verb} for "${agentName}" dropped: the store API lane is unavailable (missing/foreign AGENT_SERVE_STORE_PROTOCOL pin or no provisioned store). This July has no client-side journal fallback; fix the hosting pin.`);
+    };
     return {
+        prepareSession(ctx) {
+            return __awaiter(this, void 0, void 0, function* () {
+                var _a;
+                // Chained on the same per-journal key as appends, so hydration never
+                // interleaves with an append's mirror write.
+                const key = agentStoreKeys.memoryJournal(ctx.agentName);
+                const prior = (_a = appendChains.get(key)) !== null && _a !== void 0 ? _a : Promise.resolve();
+                const next = prior
+                    .catch(() => { })
+                    .then(() => __awaiter(this, void 0, void 0, function* () {
+                    if (!isStoreApiLaneEnabled(hosted)) {
+                        refuseMisconfiguredLane(ctx.agentName, "hydration");
+                        return;
+                    }
+                    yield hydrateMirror(ctx);
+                }));
+                appendChains.set(key, next);
+                yield next;
+            });
+        },
         appendTurn(record, ctx) {
             return __awaiter(this, void 0, void 0, function* () {
                 var _a;
+                // Soft-fail by construction (appendViaStoreApi never throws), but
+                // still chained per journal key: the local mirror's hydrate-then-
+                // append must not interleave with itself. Lane availability is
+                // re-resolved lazily per append, so a pin bound after serve start
+                // takes effect without a restart.
                 const key = agentStoreKeys.memoryJournal(ctx.agentName);
                 const prior = (_a = appendChains.get(key)) !== null && _a !== void 0 ? _a : Promise.resolve();
-                const next = prior.catch(() => { }).then(() => append(record, ctx));
+                const next = prior
+                    .catch(() => { })
+                    .then(() => __awaiter(this, void 0, void 0, function* () {
+                    if (!isStoreApiLaneEnabled(hosted)) {
+                        refuseMisconfiguredLane(ctx.agentName, "append");
+                        return;
+                    }
+                    yield appendViaStoreApi(record, ctx);
+                }));
                 appendChains.set(key, next);
                 yield next;
             });
@@ -254,6 +355,24 @@ export function memoryHook(options = {}) {
     };
     return defineHook({
         events: {
+            "session.started"(_event, ctx) {
+                return __awaiter(this, void 0, void 0, function* () {
+                    var _a;
+                    // Bring the mirror (the workspace symlink read path) up to date
+                    // before the session's first turn reads it. Backends without a
+                    // prepareSession (plain files) have nothing to freshen. Soft-fail:
+                    // hydration is a freshness upgrade, never a turn blocker.
+                    try {
+                        yield (_a = backend.prepareSession) === null || _a === void 0 ? void 0 : _a.call(backend, {
+                            stateRoot: ctx.stateRoot,
+                            agentName: ctx.agent.name,
+                        });
+                    }
+                    catch (error) {
+                        console.warn(`[agent-serve] memory hydration at session start failed: ${error instanceof Error ? error.message : String(error)}`);
+                    }
+                });
+            },
             "message.received"(event, ctx) {
                 return __awaiter(this, void 0, void 0, function* () {
                     pendingMessages.set(pendingKey(ctx, event.turnId), truncate(event.data.text, maxTextLength));