@nathapp/nax-agent 0.91.7 → 0.91.8-canary.2

package/dist/memory/support.js

@@ -0,0 +1,98 @@
+import { errorMessage } from "#src/infra/errors";
+import { NaxError } from "#src/infra/nax-error";
+import { MEMORY_PROBE_TIMEOUT_MS } from "./types.js";
+/** The stage every memory-origin log line carries. */
+const ERROR_STAGE = "memory";
+function isArmedTimer(id) {
+    return typeof id === "object" && id !== null && "handle" in id;
+}
+/**
+ * The timers an operation races against when the caller injects none: the process
+ * globals, read at call time so a substituted global is still observed. The handle
+ * is handed back boxed — `MemoryTimers` keeps the timer id opaque precisely so a
+ * fake clock can stand in for the real one, and a box clears the handle this race
+ * armed without ever casting one.
+ */
+export const GLOBAL_MEMORY_TIMERS = {
+    setTimeout: (callback, ms) => ({ handle: globalThis.setTimeout(callback, ms) }),
+    clearTimeout: (id) => {
+        if (isArmedTimer(id))
+            globalThis.clearTimeout(id.handle);
+    },
+};
+function timedOut(ms) {
+    return new NaxError(`memory operation did not settle within ${ms}ms`, "MEMORY_TIMEOUT", {
+        stage: ERROR_STAGE,
+        timeoutMs: ms,
+    });
+}
+/**
+ * `promise`'s value if it settles within `ms`, and a `MEMORY_TIMEOUT` rejection if it does not.
+ *
+ * The timer is armed when the race starts and cleared the moment either side
+ * settles, so a race that finished leaves nothing armed behind it — the property
+ * a fake clock reads as `pending() === 0`. `setTimeout` is the cancellable kind
+ * here on purpose (the `forbidden-patterns-source` exception): `Bun.sleep` cannot
+ * be cancelled, and a sleep that outlives the answer is exactly the leak this
+ * clears.
+ *
+ * A timer race does not cancel the work it raced: the provider call keeps running
+ * after a timeout, because nothing on that side of the seam accepts a signal. Its
+ * late rejection is therefore claimed here rather than left to surface as an
+ * unhandled rejection in whatever process this library runs in.
+ */
+export async function raceTimeout(promise, ms, timers) {
+    promise.catch(() => undefined);
+    const deadline = Promise.withResolvers();
+    const armed = timers.setTimeout(() => deadline.reject(timedOut(ms)), ms);
+    try {
+        return await Promise.race([promise, deadline.promise]);
+    }
+    finally {
+        timers.clearTimeout(armed);
+    }
+}
+/** Ask the provider whether it answers within the probe deadline: a throw and a timeout are `false`. */
+export async function providerAnswers(provider, timers) {
+    try {
+        return await raceTimeout(provider.reachable(), MEMORY_PROBE_TIMEOUT_MS, timers);
+    }
+    catch {
+        // A provider that threw and one that never answered are the same fact here:
+        // neither can be delivered to.
+        return false;
+    }
+}
+/**
+ * Report a failure without letting the reporting fail the caller.
+ *
+ * The logger is an input, not a guarantee: a host logger that throws would
+ * otherwise turn the never-throws contract into a rejection at exactly the
+ * moment a result is owed, so a logger failure is discarded on purpose. Shared
+ * with the save path, whose rollback is also reported rather than thrown.
+ */
+export function warnQuietly(logger, message, data) {
+    try {
+        logger.warn(ERROR_STAGE, message, data);
+    }
+    catch {
+        // Nothing left to report it to: the outcome the caller is owed still returns.
+    }
+}
+/**
+ * Run one bookkeeping step whose failure must not become the caller's answer.
+ *
+ * A provider's refusal is the error the caller is owed, and what follows it — taking the
+ * refused write back off the queue, putting back the note the mirror held — is a consequence
+ * of that error, not an alternative to it. A step that throws is reported and the rest still
+ * runs: a mirror left missing a note it holds, because a queue file could not be removed, is
+ * worse than an entry surviving to be refused again.
+ */
+export async function bookkeeping(logger, message, data, step) {
+    try {
+        await step();
+    }
+    catch (error) {
+        warnQuietly(logger, message, { ...data, error: errorMessage(error) });
+    }
+}

package/dist/memory/sync-flight.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Claim the mirror at `lockPath` for a sync in this process: `false` when one already
+ * holds it, in which case the caller has nothing to do.
+ */
+export declare function claimSync(lockPath: string): boolean;
+/** Give the claim back. A claim left behind is a mirror this process can never sync again. */
+export declare function releaseSync(lockPath: string): void;
+/** Whether this process has a sync in flight for the mirror at `lockPath`. */
+export declare function syncInFlight(lockPath: string): boolean;
+/**
+ * Claim the mirror at `lockPath` for as long as a write operation of this process owns its
+ * lock file. Claims nest rather than contend — the operations of one mirror are ordered by
+ * the per-store chain before they reach a lock — so this records ownership, it does not win it.
+ */
+export declare function claimOperation(lockPath: string): void;
+/** Give the claim back, whether the operation delivered, refused or threw. */
+export declare function releaseOperation(lockPath: string): void;
+/**
+ * Whether a write operation of this process owns the mirror at `lockPath` right now.
+ *
+ * A sync reads this before it asks the lock protocol for the file: the protocol would see our
+ * own pid, call it `own`, and rename a running approval's lock aside in the middle of its
+ * read-modify-write.
+ */
+export declare function operationInFlight(lockPath: string): boolean;

package/dist/memory/sync-flight.js

@@ -0,0 +1,65 @@
+/**
+ * Which mirrors this process owns right now, by lock path — and by which kind of owner.
+ *
+ * `acquireSessionLock` is a cross-process protocol, and it classifies the caller's own pid
+ * as `own` rather than `live` — so it cannot tell a second caller in this process from the
+ * first, and a second acquisition takes the file over from the first. Two callers in one
+ * process therefore need a guard of their own, and this module is it: a sync claims its mirror
+ * before its first `await` (a claim taken after a yield is one two callers both pass) and gives
+ * it back in its `finally`, and a write operation claims it for as long as it holds the lock
+ * file.
+ *
+ * The two claims are kept apart because they answer different questions, and both readers ask
+ * both. A lock file naming this very pid is normally a sync that is still writing the mirror,
+ * and a save must not take it over; a file naming this pid with no claim here is a release that
+ * failed, which the next save reclaims so a leaked lock cannot wedge every later save. That is
+ * why the sync claim is read by the operations. The reverse matters just as much: an approval
+ * holds the lock file for a read-modify-write, and a sync that starts while it does would be
+ * handed that same file — `own` pid — so the operation claim is what the sync reads to refuse.
+ * Without it, two writers of this process run on one mirror at once.
+ *
+ * Both facts belong to one registry, which is why it lives beside neither caller.
+ */
+const syncs = new Set();
+/** The write operations of this process — saves, forgets and approvals — holding their mirror. */
+const operations = new Set();
+/**
+ * Claim the mirror at `lockPath` for a sync in this process: `false` when one already
+ * holds it, in which case the caller has nothing to do.
+ */
+export function claimSync(lockPath) {
+    if (syncs.has(lockPath))
+        return false;
+    syncs.add(lockPath);
+    return true;
+}
+/** Give the claim back. A claim left behind is a mirror this process can never sync again. */
+export function releaseSync(lockPath) {
+    syncs.delete(lockPath);
+}
+/** Whether this process has a sync in flight for the mirror at `lockPath`. */
+export function syncInFlight(lockPath) {
+    return syncs.has(lockPath);
+}
+/**
+ * Claim the mirror at `lockPath` for as long as a write operation of this process owns its
+ * lock file. Claims nest rather than contend — the operations of one mirror are ordered by
+ * the per-store chain before they reach a lock — so this records ownership, it does not win it.
+ */
+export function claimOperation(lockPath) {
+    operations.add(lockPath);
+}
+/** Give the claim back, whether the operation delivered, refused or threw. */
+export function releaseOperation(lockPath) {
+    operations.delete(lockPath);
+}
+/**
+ * Whether a write operation of this process owns the mirror at `lockPath` right now.
+ *
+ * A sync reads this before it asks the lock protocol for the file: the protocol would see our
+ * own pid, call it `own`, and rename a running approval's lock aside in the middle of its
+ * read-modify-write.
+ */
+export function operationInFlight(lockPath) {
+    return operations.has(lockPath);
+}

package/dist/memory/sync.d.ts

@@ -0,0 +1,82 @@
+/**
+ * One sync: the guarded lifecycle around the mirror's exchange with a provider.
+ *
+ * Two guards, because ownership has two shapes. The lock files are the cross-process ones —
+ * one for the project mirror and, when the store has a user directory, one for the user mirror
+ * every project shares. `acquireSessionLock` classifies the caller's own pid as `own` — it
+ * cannot tell a second caller in this process from the first — so a module-level in-flight set
+ * keyed by the lock paths is what stops the same process syncing twice at once. Both are taken
+ * before the first `await`: a check that yields first is a check two callers pass.
+ *
+ * `syncMemory` never throws and never rejects. A live holder is `locked`, an
+ * unreachable provider is `unreachable`, anything unexpected is `failed` with
+ * its message — and the lock and the in-flight key are released on every path,
+ * including the failing ones, because a guard left behind is a store that can
+ * never sync again. A cleanup that fails is logged, never thrown: it must not
+ * turn a reportable outcome into a rejection.
+ *
+ * Step 2 asks the provider whether it answers, and asks it through
+ * `raceTimeout`: an answer that never arrives must not hold the run open, so the
+ * probe is bounded by `MEMORY_PROBE_TIMEOUT_MS` on the injected timers. `false`,
+ * a throw and a timeout are one outcome — `unreachable` — and it is recorded in
+ * `sync.json` over the cursors a failed probe learned nothing about.
+ *
+ * Step 3 delivers what the agent already wrote. Each `queued` entry is pushed in
+ * `seq` order through the same kind of race, and the provider's answer is applied
+ * to the mirror before the entry is removed: a `save` carries the returned id and
+ * status into its note, a `forget` removes the note only when the provider says it
+ * is `deleted`. The two failures are not the same fact. `MEMORY_PUSH_REJECTED` is
+ * permanent — retrying would repeat it — so the entry is marked with the reason and
+ * the drain continues. Anything else, a timeout included, is transient: the drain
+ * stops, the entry stays `queued` for the next run, `sync.json` records why, and
+ * the run ends `failed` — after the index is refreshed, so a forget still waiting
+ * is visible as `(forget pending)`.
+ *
+ * Step 4 asks the provider for what changed elsewhere, one page at a time. The cursor
+ * each page hands back is checkpointed before the next page is asked for, so the disk
+ * always names the last page that arrived: a page that throws, times out or never comes
+ * leaves the run resuming there rather than from the beginning. `done` is the provider's
+ * answer about the sequence, not a budget, so a sequence that ends on the last page one
+ * run may drain has finished; only one with more behind it is a page-limit failure.
+ *
+ * What a page *means* is decided one entry at a time. A note the schema refuses — a slug
+ * outside `MEMORY_SLUG_RE`, a field missing or over its model limit — is skipped and
+ * reported once, never thrown: one unreadable entry must not cost the page its cursor. A
+ * key the outbox still holds is left exactly as the local mirror has it and is not counted,
+ * because the local write is the newer fact. A tombstone deletes. `decisions` replace
+ * `decisions.jsonl` on a project page only. The held set is read after each page, and the
+ * page's scope — not the payload's `scope` field — decides where a note lands.
+ */
+import type { AgentLogger } from "#src/infra/agent-logger";
+import type { MemoryOutbox } from "./outbox.ts";
+import type { MemoryProvider } from "./provider-types.ts";
+import type { MemoryStore } from "./store.ts";
+import { type MemoryTimers } from "./types.ts";
+/** Everything one sync needs: the mirror, the queue and the provider it talks to. */
+export interface MemorySyncInput {
+    readonly store: MemoryStore;
+    readonly outbox: MemoryOutbox;
+    readonly provider: MemoryProvider;
+    readonly logger: AgentLogger;
+    /** The clock the lock protocol stamps with; default `() => new Date()`. */
+    readonly now?: () => Date;
+    /** The timer seam the step timeouts race against; default the globals. */
+    readonly timers?: MemoryTimers;
+    /** The pid this process claims in the lock; default `process.pid`. */
+    readonly pid?: number;
+    /** The liveness probe a lock holder is judged by; default `isProcessAlive`. */
+    readonly isAlive?: (pid: number) => boolean;
+    /** How many notes one pull asks for; default `MEMORY_PULL_PAGE_SIZE`. */
+    readonly pageSize?: number;
+}
+/** What one run did, and how it ended. */
+export interface MemorySyncResult {
+    readonly outcome: "synced" | "unreachable" | "locked" | "failed";
+    readonly pushed: number;
+    readonly rejected: number;
+    readonly pulled: number;
+    readonly skipped: number;
+    /** The message of the failure that ended the run, when it ended in one. */
+    readonly error?: string;
+}
+export declare function syncMemory(input: MemorySyncInput): Promise<MemorySyncResult>;

package/dist/memory/sync.js

@@ -0,0 +1,344 @@
+import { errorMessage } from "#src/infra/errors";
+import { applyPushed } from "./delivery.js";
+import { refreshMemoryIndex } from "./index-render.js";
+import { acquireMirrorLocks, storeLockTargets } from "./mirror-lock.js";
+import { isMemoryPushRejected, parseMemoryNoteRecord } from "./note.js";
+import { GLOBAL_MEMORY_TIMERS, providerAnswers, raceTimeout, warnQuietly } from "./support.js";
+import { claimSync, releaseSync } from "./sync-flight.js";
+import { MEMORY_OP_TIMEOUT_MS, MEMORY_PULL_MAX_PAGES, MEMORY_PULL_PAGE_SIZE, MEMORY_SLUG_RE, } from "./types.js";
+/** What `sync.json` records when the provider did not answer this run. */
+const UNREACHABLE = "unreachable";
+/** What `sync.json` records when a provider had more pages than one run may drain. */
+const PAGE_LIMIT_REACHED = "pull page limit reached";
+/** What a run holds when it took no lock: releasing nothing is releasing successfully. */
+const NO_RELEASE = async () => undefined;
+function noCounts() {
+    return { pushed: 0, rejected: 0, pulled: 0, skipped: 0 };
+}
+/** A run that stopped before it moved anything. */
+function stopped(outcome, error) {
+    return { outcome, ...noCounts(), ...(error === undefined ? {} : { error }) };
+}
+/** The clock a run stamps with: the caller's, or the process clock. */
+function clockOf(input) {
+    return input.now ?? (() => new Date());
+}
+/**
+ * Take every lock this store's mirrors need, or `null` when another writer holds one.
+ *
+ * The set is what a store with a user directory needs: the project's lock alone leaves two
+ * projects staging the same user note at once. `acquireMirrorLocks` takes them in the one
+ * canonical order, maps a live holder to `null` and hands back what it already took.
+ */
+async function takeLock(input) {
+    return await acquireMirrorLocks(input, storeLockTargets(input.store));
+}
+/**
+ * Step 2's failing arm: record why this run could not reach the provider, and stop.
+ *
+ * Only `lastError` changes — a probe that failed learned nothing about the cursors
+ * or the last pull, so whatever the previous sync left carries over untouched — and
+ * the outbox is not read, so the queued writes stay exactly as they were.
+ */
+async function recordUnreachable(input) {
+    await recordLastError(input, UNREACHABLE);
+    return stopped("unreachable");
+}
+/** Note why a run could not finish, leaving every other field of the state as it was. */
+async function recordLastError(input, message) {
+    const state = await input.store.readSyncState();
+    await input.store.writeSyncState({ ...state, lastError: message });
+}
+/**
+ * The write an entry stands for, as the provider takes it.
+ *
+ * The entry carries the queue's own bookkeeping — its sequence, when it was taken,
+ * whether it is still queued — and none of that is the provider's to read, so the
+ * request is projected from the fields the two shapes share rather than forwarded.
+ */
+function requestOf(entry) {
+    return {
+        kind: entry.kind,
+        clientId: entry.clientId,
+        scope: entry.scope,
+        slug: entry.slug,
+        writeMode: entry.writeMode,
+        ...(entry.note === undefined ? {} : { note: entry.note }),
+        ...(entry.reason === undefined ? {} : { reason: entry.reason }),
+    };
+}
+/**
+ * One entry, pushed through the operation race.
+ *
+ * `MEMORY_PUSH_REJECTED` is the provider saying it will never accept this write, so
+ * it is separated here from every other throw and from the `MEMORY_TIMEOUT` the race
+ * raises: only the first is worth keeping on the entry, and only the others are worth
+ * another attempt.
+ */
+async function pushEntry(input, entry, timers) {
+    try {
+        const pushed = input.provider.push(requestOf(entry));
+        return { kind: "pushed", result: await raceTimeout(pushed, MEMORY_OP_TIMEOUT_MS, timers) };
+    }
+    catch (error) {
+        const reason = errorMessage(error);
+        return isMemoryPushRejected(error) ? { kind: "rejected", reason } : { kind: "failed", reason };
+    }
+}
+/**
+ * Step 3: deliver every queued write, oldest first.
+ *
+ * `list()` answers with the rejected entries too — they are the record of a refusal —
+ * so only `queued` entries are pushed: nothing here retries a permanent one.
+ */
+async function drainOutbox(input) {
+    const timers = input.timers ?? GLOBAL_MEMORY_TIMERS;
+    let pushed = 0;
+    let rejected = 0;
+    for (const entry of await input.outbox.list()) {
+        if (entry.state !== "queued")
+            continue;
+        const outcome = await pushEntry(input, entry, timers);
+        if (outcome.kind === "failed")
+            return { pushed, rejected, failure: outcome.reason };
+        if (outcome.kind === "rejected") {
+            await input.outbox.markRejected(entry.clientId, outcome.reason);
+            rejected += 1;
+            continue;
+        }
+        await applyPushed(input, entry, outcome.result);
+        await input.outbox.remove(entry.clientId);
+        pushed += 1;
+    }
+    return { pushed, rejected };
+}
+/** The cursor pair with one scope moved: the other scope's cursor is carried over untouched. */
+function cursorWith(cursor, scope, next) {
+    return scope === "user" ? { ...cursor, user: next } : { ...cursor, project: next };
+}
+/**
+ * After each page: record where this scope's pull got to.
+ *
+ * The page is the checkpoint, so it is written before the next one is asked for. A page
+ * that throws, times out or never arrives therefore leaves the disk naming the last page
+ * that did arrive, and the next run resumes there instead of from the beginning. The
+ * `lastError` a previous run left is cleared here: this pull reached the provider.
+ */
+async function checkpointPull(input, scope, cursor) {
+    const state = await input.store.readSyncState();
+    await input.store.writeSyncState({
+        provider: input.provider.id,
+        cursor: cursorWith(state.cursor, scope, cursor),
+        lastPullAt: clockOf(input)().toISOString(),
+        lastError: null,
+    });
+}
+/** The statuses a pull applies as a deletion: the note is retired wherever it came from. */
+const TOMBSTONES = new Set(["superseded", "rejected", "deleted"]);
+/**
+ * One entry of a page read as a note the mirror may hold.
+ *
+ * The slug is checked first, so `Bad Slug` is refused as a slug and not as an opaque shape
+ * error; `parseMemoryNoteRecord` is then the schema a mirror read applies, so a pulled note
+ * and a stored one are held to one contract. Both refusals are a skip, never a throw.
+ */
+function readPulledEntry(entry) {
+    const slug = typeof entry === "object" && entry !== null && "slug" in entry ? entry.slug : undefined;
+    if (typeof slug !== "string" || !MEMORY_SLUG_RE.test(slug)) {
+        const reason = typeof slug === "string" ? `slug "${slug}" is not a valid note slug` : "slug is missing";
+        return { kind: "invalid", ...(typeof slug === "string" ? { slug } : {}), reason };
+    }
+    try {
+        return { kind: "note", note: parseMemoryNoteRecord(entry) };
+    }
+    catch (error) {
+        return { kind: "invalid", slug, reason: errorMessage(error) };
+    }
+}
+/** One entry the mirror could not take: reported once, at warn, naming the scope and the entry. */
+function warnInvalidEntry(logger, scope, entry) {
+    warnQuietly(logger, "skipping a pulled note that is not a valid memory note", {
+        scope,
+        ...(entry.slug === undefined ? {} : { slug: entry.slug }),
+        error: entry.reason,
+    });
+}
+/**
+ * Step 4's mirror half: one page applied to its scope's mirror.
+ *
+ * The held set is read here, after the page arrived, not once per run: a write enqueued
+ * while the page was in flight is one this page must not overwrite, and the local copy is
+ * the newer fact — so a held key is left exactly as the mirror has it, and is not counted,
+ * because nothing was skipped: the write is still on its way. The page's scope, not the
+ * payload's own `scope` field, says where a note lands. A tombstone deletes rather than
+ * counts: a retired note is not a pull. Decisions and the cursor checkpoint follow both.
+ */
+async function applyPulledPage(input, scope, answer) {
+    const held = await input.outbox.heldKeys();
+    let pulled = 0;
+    let skipped = 0;
+    for (const entry of answer.notes) {
+        const parsed = readPulledEntry(entry);
+        if (parsed.kind === "invalid") {
+            skipped += 1;
+            warnInvalidEntry(input.logger, scope, parsed);
+            continue;
+        }
+        const { note } = parsed;
+        if (held.has(`${scope}/${note.slug}`))
+            continue;
+        if (TOMBSTONES.has(note.status)) {
+            await input.store.deleteNote(scope, note.slug);
+            continue;
+        }
+        await input.store.writeNote({ ...note, scope });
+        pulled += 1;
+    }
+    // The project mirror owns `decisions.jsonl`: a user page's decisions are not the mirror's to write.
+    if (scope === "project" && answer.decisions !== undefined)
+        await input.store.writeDecisions(answer.decisions);
+    return { pulled, skipped };
+}
+/**
+ * One scope's pages, one at a time, each checkpointed before the next is asked for.
+ *
+ * A page fails the pull wherever it goes wrong — the provider not answering, timing out, or
+ * the mirror refusing what it carried — and all three leave the cursor at the last page that
+ * was applied. Applying a page sits in the same catch as the race so its reason reaches
+ * `lastError`, and not only the run's never-throws shell. The limit is a budget on this run,
+ * not a claim about the sequence: a page that says `done` finished whatever page it is, so
+ * reaching the limit is a failure only when the provider still has more to give.
+ */
+async function pullScope(input, scope, timers) {
+    const take = input.pageSize ?? MEMORY_PULL_PAGE_SIZE;
+    let cursor = (await input.store.readSyncState()).cursor[scope];
+    let pulled = 0;
+    let skipped = 0;
+    for (let page = 0; page < MEMORY_PULL_MAX_PAGES; page += 1) {
+        try {
+            const answer = await raceTimeout(input.provider.pull({ scope, cursor, take }), MEMORY_OP_TIMEOUT_MS, timers);
+            const applied = await applyPulledPage(input, scope, answer);
+            pulled += applied.pulled;
+            skipped += applied.skipped;
+            cursor = answer.nextCursor ?? cursor;
+            await checkpointPull(input, scope, cursor);
+            if (answer.done)
+                return { pulled, skipped };
+        }
+        catch (error) {
+            return { pulled, skipped, failure: errorMessage(error) };
+        }
+    }
+    return { pulled, skipped, failure: PAGE_LIMIT_REACHED };
+}
+/** The scopes a run pulls, in order: the project mirror, then the user's when the store has one. */
+function pullScopes(store) {
+    return store.paths.userDir === null ? ["project"] : ["project", "user"];
+}
+/**
+ * Step 4: ask the provider for every page of every scope.
+ *
+ * The first failure ends the pull and the other scope is not asked: a cursor that did
+ * not advance is where the next run resumes, and reading past it would record progress
+ * this run never made.
+ */
+async function pullAll(input) {
+    const timers = input.timers ?? GLOBAL_MEMORY_TIMERS;
+    let pulled = 0;
+    let skipped = 0;
+    for (const scope of pullScopes(input.store)) {
+        const result = await pullScope(input, scope, timers);
+        pulled += result.pulled;
+        skipped += result.skipped;
+        if (result.failure !== undefined)
+            return { pulled, skipped, failure: result.failure };
+    }
+    return { pulled, skipped };
+}
+/**
+ * A run that stopped after it moved something: record why, refresh the index, report failed.
+ *
+ * The index is still refreshed, because what the run did move is what the next session
+ * has to see — a forget left queued renders as `(forget pending)` — and the counters are
+ * the work that was done before the step that failed.
+ */
+async function failRun(input, counts, failure) {
+    await recordLastError(input, failure);
+    return await finish(input, counts, failure);
+}
+/**
+ * Step 5: regenerate the index the next session reads, and report what the run did.
+ *
+ * `failure` is the step that stopped early, if any: the counters are what did move
+ * before it stopped.
+ */
+async function finish(input, counts, failure) {
+    const heldForgets = await input.outbox.heldKeys("forget");
+    await refreshMemoryIndex(input.store, { heldForgets });
+    return failure === undefined ? { outcome: "synced", ...counts } : { outcome: "failed", ...counts, error: failure };
+}
+/** Hand the lock back if this run took it; a failed release is logged, never thrown. */
+async function releaseQuietly(input, release) {
+    try {
+        await release();
+    }
+    catch (error) {
+        warnQuietly(input.logger, "memory sync could not release the lock", {
+            path: input.store.paths.lock,
+            error: errorMessage(error),
+        });
+    }
+}
+export async function syncMemory(input) {
+    const lock = input.store.paths.lock;
+    // Every lock this run takes is claimed here, synchronously and before the first await: a
+    // guard taken after a yield is one two callers both pass. Nothing has touched the
+    // filesystem on this path. Only the claims *this* run won are recorded, so a run that loses
+    // contention on the second mirror gives back the first — and never the claim of the sync
+    // that is already running, which would let a third caller in behind it.
+    const claimed = [];
+    const won = storeLockTargets(input.store).every((target) => {
+        if (!claimSync(target.path))
+            return false;
+        claimed.push(target.path);
+        return true;
+    });
+    if (!won) {
+        for (const path of claimed)
+            releaseSync(path);
+        return stopped("locked");
+    }
+    let release = NO_RELEASE;
+    try {
+        const acquired = await takeLock(input);
+        if (acquired === null)
+            return stopped("locked");
+        release = acquired;
+        const timers = input.timers ?? GLOBAL_MEMORY_TIMERS;
+        if (!(await providerAnswers(input.provider, timers)))
+            return await recordUnreachable(input);
+        const drain = await drainOutbox(input);
+        const counts = { ...noCounts(), pushed: drain.pushed, rejected: drain.rejected };
+        // A drain that stopped early says nothing about the provider's own changes: no pull.
+        if (drain.failure !== undefined)
+            return await failRun(input, counts, drain.failure);
+        const pull = await pullAll(input);
+        counts.pulled = pull.pulled;
+        counts.skipped = pull.skipped;
+        if (pull.failure !== undefined)
+            return await failRun(input, counts, pull.failure);
+        return await finish(input, counts);
+    }
+    catch (error) {
+        const message = errorMessage(error);
+        warnQuietly(input.logger, "memory sync failed", { path: lock, error: message });
+        return stopped("failed", message);
+    }
+    finally {
+        await releaseQuietly(input, release);
+        // Cleared whatever the cleanup did: a lock we could not release ages into
+        // stale recovery, but this process must not be wedged until then.
+        for (const path of claimed)
+            releaseSync(path);
+    }
+}