@lorekit/cli 1.50.0 → 1.52.0

package/bin/lorekit.mjs

@@ -94,7 +94,8 @@ ${c.bold('Commands')}
   bootstrap   Apply the BYOD schema to a user-supplied Supabase database.
               Only needed when using LOREKIT_STORAGE_URL / LOREKIT_STORAGE_ANON_KEY.
               See docs/byod.md for setup instructions.
-  migrate     Relocate a LoreKit-format local store into the current layout.
+  migrate     Relocate a LoreKit-format local store into the current layout,
+              or push it up to the hosted store with --to remote.
               Dry-run by default; pass --yes to apply. Idempotent.
   hook        Hook engine for Claude Code / Cursor / Codex. Reads the host's
               JSON on stdin and injects memories or a retrospective nudge.
@@ -121,8 +122,8 @@ ${c.bold('Options')}
       --base <url>        Dashboard base URL for deep links (link / --link; else LOREKIT_APP_URL, default https://lorekit.io)
       --threshold <0..1>  Duplicate-similarity cutoff (dedupe; default 0.8)
       --from <path>       Source store to migrate from (migrate)
-      --to <tier>         Migration destination tier: home | project (migrate;
-                          default routes each entry by scope)
+      --to <dest>         Migration destination: home | project | remote (migrate;
+                          default routes each entry by scope across the local tiers)
       --apply             Apply the migration (alias of --yes) (migrate)
   -y, --yes               Non-interactive / apply; never prompt
       --hooks <mode>      Lifecycle hooks to wire: all | read-only | none (install)
@@ -158,6 +159,7 @@ ${c.bold('Examples')}
   npx @lorekit/cli doctor --deep
   npx @lorekit/cli migrate --from .lore                 # preview a rename
   npx @lorekit/cli migrate --from .lore --to project --yes
+  npx @lorekit/cli migrate --from .lorekit --to remote --yes  # push local lore up
 
 Run ${c.cyan('lorekit <command> --help')} for command-specific options.
 `;
@@ -603,7 +605,7 @@ ${c.bold('Examples')}
   npx @lorekit/cli url --q "flaky test" --owner personal # search + ownership filter
   npx @lorekit/cli link global --tags "perf,ci"          # Explorer filtered to labels
 `,
-  migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store into the current layout
+  migrate: `${c.bold('lorekit migrate')} — relocate a LoreKit-format local store, or push it to the hosted store
 
 ${c.bold('Usage')}
   npx @lorekit/cli migrate --from <path> [options]
@@ -613,13 +615,34 @@ Dry-run by default; pass --yes (or --apply) to write. Idempotent.
 ${c.bold('Options')}
   -d, --dir <path>        Target project root (default: current directory)
       --from <path>       Source store to migrate from (required)
-      --to <tier>         Destination tier: home | project (default routes by scope)
+      --to <dest>         Destination: home | project | remote (default routes by
+                          scope across the local tiers)
       --apply             Apply the migration (alias of --yes)
   -y, --yes               Apply the migration; never prompt
 
+${c.bold('--to remote')}
+Pushes every entry in the source store up to the hosted store, over the
+connection and token \`lorekit install\` configured (\`--endpoint\` / \`--token\`
+override both). A read-only \`lk_ro_*\` token is rejected before anything is
+written; an unrecognized prefix only warns and proceeds, so a self-hosted or
+custom token still works.
+
+What the hosted store does NOT take verbatim:
+  - archived and expired entries are skipped — a write would insert a second,
+    live row beside the archived one, and any TTL would re-date an expired one
+  - \`tags\` REPLACE the hosted row's labels, so an untagged local entry clears
+    them
+  - a creation date is honoured only when the lesson is new to the hosted
+    store, and an unusable one is dropped for the write instant
+  - \`updated\` and the \`seen_count\` tally are re-derived by the server, and a
+    TTL beyond 365 days is shortened
+Every one of those is reported per entry, in the dry run as well as the apply.
+
 ${c.bold('Examples')}
   npx @lorekit/cli migrate --from .lore                 # preview a rename
   npx @lorekit/cli migrate --from .lore --to project --yes
+  npx @lorekit/cli migrate --from .lorekit --to remote        # preview the push
+  npx @lorekit/cli migrate --from .lorekit --to remote --yes  # push local lore up
 `,
   hook: `${c.bold('lorekit hook')} — hook engine for Claude Code / Cursor / Codex
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lorekit/cli",
-  "version": "1.50.0",
+  "version": "1.52.0",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

package/src/mcp.mjs

@@ -158,6 +158,30 @@ export function normalizeRunEnvironment(raw) {
   return /^[A-Za-z0-9_.\-:]+$/.test(t) ? t : null;
 }
 
+/**
+ * The retry delay a failed response advertised, in whole seconds, or null.
+ *
+ * Prefers the JSON body's `retryAfterSeconds` over the `Retry-After` header:
+ * both are set by the same `tooManyRequests()` helper, and the body value is
+ * the number the rate-limit RPC actually returned, while the header is its
+ * stringified copy that an intermediary may rewrite.
+ *
+ * TOTAL over any input. `headers` is read through optional calls because a
+ * test double (and a hand-rolled Response-alike) may not implement the Headers
+ * interface, and a missing retry hint must never be able to throw on an error
+ * path — the caller is already handling a failure.
+ */
+export function retryAfterFrom(data, headers) {
+  const raw = data?.retryAfterSeconds ?? (typeof headers?.get === 'function' ? headers.get('retry-after') : null);
+  if (raw == null || raw === '') return null;
+  const n = Number(raw);
+  // A `Retry-After` may also be an HTTP-date; a non-numeric value is reported
+  // as "no hint" so the caller falls back to its own backoff rather than
+  // waiting on NaN.
+  if (!Number.isFinite(n) || n < 0) return null;
+  return Math.ceil(n);
+}
+
 export async function restFetch(baseUrl, token, path, { method = 'GET', body, timeoutMs = 10000, traceparent } = {}) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), timeoutMs);
@@ -203,6 +227,12 @@ export async function restFetch(baseUrl, token, path, { method = 'GET', body, ti
       return {
         ok: false,
         httpStatus: res.status,
+        // How long the server asked the caller to wait, in seconds, or null when
+        // it did not say. Only a 429 carries one today (`tooManyRequests` sets
+        // BOTH a `retryAfterSeconds` body field and the `Retry-After` header),
+        // but this is read on every failure so a future 503 needs no change
+        // here. Additive: existing callers ignore the extra key.
+        retryAfter: retryAfterFrom(data, res.headers),
         error: data?.error ? { message: data.error, code: data.code } : { code: res.status, message: text.slice(0, 200) || res.statusText },
       };
     }

package/src/migrate.mjs

@@ -1,22 +1,36 @@
-// `lorekit migrate --from <path> [--to home|project] [--yes|--apply]`
+// `lorekit migrate --from <path> [--to home|project|remote] [--yes|--apply]`
 //
 // Relocation / rename tool — NOT a persistent-memory importer. It reads a
 // LoreKit-format local store at <path> (e.g. an old `.lore/` directory, or a
 // store that was moved elsewhere) and re-writes its entries into the resolved
 // current-layout store(s), so lessons are never stranded by a rename or a move.
 //
+// `--to remote` is the one destination that leaves the machine: it pushes the
+// source store up to the hosted store, which is the local→remote transition a
+// user who started offline and then connected a token had no bulk path for.
+// Everything else about the command is unchanged by it — same dry-run default,
+// same per-scope report, same idempotency — because the destination is just
+// another store behind the same `getEntry`/`putEntry` pair.
+//
 // Dry-run (preview) by default: it prints what would move, per scope, and
 // changes nothing. Only `--yes` (or `--apply`) mutates. Idempotent: entries are
 // upserted verbatim by scope+key, so a re-run is all NOOP.
 //
 // Out of scope: reading persistent-memory's `~/.agent-memory/<bucket>/INDEX.md`
 // + `entries/` format. This tool only understands LoreKit's own on-disk format.
+// Also out of scope: the reverse direction (remote → local) and `--org <slug>`
+// org-owned writes; a v1 migration always lands as the caller's personal lore.
 import fs from 'node:fs';
 import path from 'node:path';
-import { resolveProjectRoot } from './config.mjs';
-import { localStoreDirs } from './control.mjs';
-import { createLocalStore, createTwoTierStore } from './store/index.mjs';
+import { resolveProjectRoot, tokenKind } from './config.mjs';
+import { localStoreDirs, loadControl } from './control.mjs';
+import { createLocalStore, createTwoTierStore, createRemoteStore } from './store/index.mjs';
 import { parseEntry } from './store/format.mjs';
+import { isLive, TTL_MAX_DAYS } from './store/ttl.mjs';
+import { remoteWriteLosses } from './store/remote.mjs';
+import {
+  createPacer, withRetry, isMemoryCap, sleep, DEFAULT_CONSECUTIVE_FAILURE_LIMIT,
+} from './store/rate-limit.mjs';
 import { log, heading, status, err, c } from './util.mjs';
 
 // Recursively collect every parseable LoreKit entry under a base dir. The
@@ -65,7 +79,206 @@ function sameEntry(a, b) {
   return norm(a) === norm(b);
 }
 
-export async function migrate(args) {
+// The remote counterpart of `sameEntry`, and deliberately a DIFFERENT one —
+// not weaker, but mirrored against what the hosted write actually stores.
+//
+// It compares only the fields a hosted write can actually change. Everything
+// else the row carries is server-owned, and including any of it would make the
+// command permanently non-idempotent rather than more accurate:
+//
+//   `created_at`  is honoured on INSERT only, so a row that already exists with
+//                 a different creation date can never be made to match — every
+//                 re-run would report UPDATE and re-push the whole store.
+//   `updated_at`  is stamped at the write instant, so it differs by definition
+//                 the moment the comparison runs.
+//   `expires_at`  is recomputed from `ttl_days` at write time, so the two
+//                 instants drift apart the moment they agree. What is
+//                 comparable is whether the hosted expiry SATISFIES the local
+//                 one — see `sameRemoteTtl`.
+//
+// A remote NOOP therefore means "the hosted lesson already says this", not
+// "the two rows are byte-identical". That is the honest guarantee, and it is
+// the one that makes a second `--yes` a no-op.
+function sameRemoteEntry(current, entry, now = new Date()) {
+  if (!current || !entry) return false;
+  // The hosted write TRIMS `value` (`MemoryWriteSchema`), so comparing the
+  // untrimmed local text against the trimmed hosted one would report UPDATE
+  // for a padded entry on every single run and re-push it forever.
+  const value = (e) => (e.value == null ? '' : String(e.value)).trim();
+  const scalar = (e) =>
+    JSON.stringify({
+      tags: [...(e.tags || [])].sort(),
+      source_agent: e.source_agent ?? null,
+      trigger: e.trigger ?? null,
+      value: value(e),
+    });
+  if (scalar(current) !== scalar(entry)) return false;
+
+  // Provenance is COALESCED server-side, so a local entry that knows nothing
+  // about a field can never make the hosted row forget it. Comparing the two
+  // directly would report UPDATE forever; the honest question is whether the
+  // fields this entry DOES carry already match.
+  for (const f of ['origin_repo', 'origin_branch', 'origin_commit', 'origin_pr']) {
+    if (entry[f] == null) continue;
+    if (String(current[f] ?? '') !== String(entry[f])) return false;
+  }
+
+  return sameRemoteTtl(current.expires_at, entry.expires_at, now);
+}
+
+// Whether the hosted row's expiry still honours the local entry's intent.
+//
+// The instants cannot be compared. A push recomputes `expires_at` from
+// `ttl_days` at the write instant and it then stays fixed, while the local
+// intent is always measured from NOW — so the two drift apart the moment they
+// agree, and any test for equality (or for "hosted >= what I would write
+// today") re-pushes the entry on every run forever. An over-365-day entry is
+// the worst case: its hosted row is capped at the API maximum and can never
+// catch up with the local date at all.
+//
+// So the question is not "do these match" but "has the hosted lesson lost
+// enough of its intended life to be worth rewriting":
+//
+//   both permanent          → honoured.
+//   one permanent, one not  → different intent, re-push.
+//   both expiring           → honoured while the hosted row still has at least
+//                             HALF the life the local entry asks for (the ask
+//                             itself capped at the API maximum, since that is
+//                             the longest a write can request). A fresh push
+//                             leaves the two equal and the entry then coasts
+//                             for half its TTL before one re-push refreshes
+//                             it — bounded and convergent, never a loop.
+//
+// The threshold is what makes it converge, and it is deliberately generous in
+// both directions: a hosted row expiring in 7 days does NOT honour a 300-day
+// lesson, and one expiring within the hour does NOT honour a one-day lesson,
+// so a genuinely shortened TTL still migrates.
+const TTL_HONOURED_FRACTION = 0.5;
+
+function sameRemoteTtl(currentExpiry, entryExpiry, now = new Date()) {
+  if (!currentExpiry && !entryExpiry) return true;
+  if (!currentExpiry || !entryExpiry) return false;
+  const hosted = Date.parse(currentExpiry);
+  const local = Date.parse(entryExpiry);
+  // An unparseable value on either side is not a difference we can act on —
+  // `putEntry` leaves the hosted expiry alone in that case, so re-pushing
+  // would change nothing.
+  if (Number.isNaN(hosted) || Number.isNaN(local)) return true;
+  const at = now.getTime();
+  // What a write could actually ask for, from now: the local intent, capped at
+  // the API's maximum.
+  const asked = Math.min(local - at, TTL_MAX_DAYS * 86_400_000);
+  if (asked <= 0) return true; // the local entry is expiring anyway
+  return hosted - at >= asked * TTL_HONOURED_FRACTION;
+}
+
+// The global connection flags, folded into the environment the resolver reads.
+// A COPY of the shim `doctor.mjs` and `mcp-server.mjs` use (kept local for the
+// same reason theirs are: `resolveControl` is a pure resolver that takes an
+// env object, and threading flags through it is each command's own business).
+function withOverrides(args) {
+  const env = { ...process.env };
+  if (args.endpoint) env.LOREKIT_MCP_URL = args.endpoint;
+  if (args.token) env.LOREKIT_TOKEN = args.token;
+  if (args.store) env.LOREKIT_STORE = args.store;
+  return env;
+}
+
+// Name the entries a remote write altered, then tally them. A bare count tells
+// a user something was changed without telling them what — and these are
+// silent changes, so they are the ones most worth naming.
+function reportAltered(keys, apply, what) {
+  if (!keys.length) return;
+  for (const key of keys.slice(0, ALTERED_LIST_CAP)) status('warn', key, what);
+  if (keys.length > ALTERED_LIST_CAP) {
+    log(`  ${c.dim(`… and ${keys.length - ALTERED_LIST_CAP} more`)}`);
+  }
+  log(`  ${keys.length} entr${keys.length === 1 ? 'y' : 'ies'}: ${apply ? '' : 'would have '}${what}.`);
+}
+
+// How many altered entries to name before summarising the rest. A migration
+// can carry thousands; naming every one would bury the summary it belongs to.
+const ALTERED_LIST_CAP = 10;
+
+// Resolve the hosted store to push to, or the reason we cannot.
+//
+// Every check here is a PREFLIGHT: it runs once, before the first entry, so a
+// misconfigured run fails in one line instead of halfway through a push with
+// an unknown amount already written.
+//
+// Returns `{ error }` when the destination is unusable, else
+// `{ store, endpoint, warnings, classify }` — where `classify` is false when
+// the token cannot READ, so the caller must not try to.
+export function resolveRemoteDestination(control, args = {}) {
+  const denied = (control.denies || []).find((d) => d.mode === 'remote');
+  if (denied) {
+    return { error: `remote mode is denied by ${denied.source} — a migration cannot override a deny` };
+  }
+
+  // The global `-e/--endpoint` and `-t/--token` outrank the resolved
+  // connection. `withOverrides` alone is not enough for these two:
+  // `resolveProjectConnection` reads `process.env` directly rather than the
+  // injected env, so a flag that never touches `process.env` would be silently
+  // ignored — which is exactly what happened before.
+  const resolved = control.connection || {};
+  const endpoint = (typeof args.endpoint === 'string' && args.endpoint.trim()) || resolved.endpoint || null;
+  const token = (typeof args.token === 'string' && args.token.trim()) || resolved.token || null;
+  const conn = {
+    endpoint,
+    token,
+    usable: Boolean(endpoint && token && !String(endpoint).includes('<project-ref>')),
+  };
+  if (!conn.usable) {
+    return {
+      error: 'no usable remote connection is configured.\n'
+        + `  Run ${c.cyan('lorekit install --endpoint <url> --token lk_rw_...')}, or set `
+        + 'LOREKIT_MCP_URL + LOREKIT_TOKEN.',
+    };
+  }
+
+  // The token's PREFIX is a local, offline claim about its permissions, which
+  // is exactly what a preflight needs: a read-only token is rejected before a
+  // single request rather than 403-ing on the first write, mid-run.
+  const kind = tokenKind(conn.token);
+  if (kind === 'read-only') {
+    return {
+      error: 'the configured token is read-only (lk_ro_*) — a migration to remote writes.\n'
+        + `  Create a read+write token (${c.cyan('lk_rw_*')}) in the dashboard and re-run.`,
+    };
+  }
+
+  const warnings = [];
+  // Whether the destination can be READ to classify ADD / UPDATE / NOOP. A
+  // write-only token's reads are denied outright, so asking would 403 every
+  // entry — see `classify: false` below.
+  let classify = true;
+  if (kind === 'write-only') {
+    // A write-only token is legitimate here — the writes will succeed — but the
+    // classifying READ will 403, so every entry looks new. Say so up front
+    // rather than presenting a plan that silently overstates the work.
+    classify = false;
+    warnings.push(
+      'token is write-only (lk_wo_*) — reads are denied, so the destination is not read at all: '
+      + 'every entry is reported as "add" and pushed. The writes are still idempotent server-side.',
+    );
+  } else if (kind === 'unknown') {
+    warnings.push(
+      'token has an unrecognized prefix (expected lk_rw_* / lk_ro_* / lk_wo_*) — proceeding anyway; '
+      + 'a token without write permission will fail on the first write.',
+    );
+  }
+
+  return {
+    store: createRemoteStore({ endpoint: conn.endpoint, token: conn.token }),
+    endpoint: conn.endpoint,
+    warnings,
+    classify,
+  };
+}
+
+// `options` is a test seam, not a user-facing surface: `sleepFn` lets the
+// rate-limit tests exercise the backoff without actually waiting out a window.
+export async function migrate(args, options = {}) {
   const root = resolveProjectRoot(args.dir);
 
   const from = typeof args.from === 'string' ? args.from : null;
@@ -80,8 +293,8 @@ export async function migrate(args) {
   }
 
   const to = typeof args.to === 'string' ? args.to.toLowerCase() : null;
-  if (to && to !== 'home' && to !== 'project') {
-    err(`${c.red('migrate:')} --to must be "home" or "project"`);
+  if (to && to !== 'home' && to !== 'project' && to !== 'remote') {
+    err(`${c.red('migrate:')} --to must be "home", "project" or "remote"`);
     return 1;
   }
   const apply = Boolean(args.apply || args.yes);
@@ -93,7 +306,24 @@ export async function migrate(args) {
   // repo/branch → project when opted-in, else home).
   let targetFor;
   let destLabel;
-  if (to === 'home') {
+  const remote = to === 'remote';
+  let remoteWarnings = [];
+  let classifyRemote = true;
+  if (remote) {
+    // `withOverrides` so the global `-t/--token` and `-e/--endpoint` reach the
+    // resolver, exactly as `doctor` and the stdio MCP server do. Without it a
+    // user who passed both on the command line still failed the preflight.
+    const control = loadControl(root, { env: withOverrides(args) });
+    const dest = resolveRemoteDestination(control, args);
+    if (dest.error) {
+      err(`${c.red('migrate:')} ${dest.error}`);
+      return 1;
+    }
+    remoteWarnings = dest.warnings;
+    classifyRemote = dest.classify !== false;
+    targetFor = () => dest.store;
+    destLabel = `remote (${dest.endpoint})`;
+  } else if (to === 'home') {
     const store = createLocalStore(dirs.home);
     targetFor = () => store;
     destLabel = `home (${dirs.home})`;
@@ -108,30 +338,148 @@ export async function migrate(args) {
     destLabel = 'resolved layout (global→home, repo/branch→project-if-opted-in)';
   }
 
-  const entries = collectEntries(src);
+  // ONE clock for the run: the TTL comparison, the lossiness preview and the
+  // conversion inside `putEntry` must not disagree about what "now" is.
+  const now = options.now instanceof Date ? options.now : new Date();
+
+  const collected = collectEntries(src);
+  // A remote destination cannot represent an archived or an expired entry
+  // (see `RemoteStore.putEntry`), so they are filtered here and counted rather
+  // than pushed and silently revived. A local destination keeps taking them —
+  // `LocalStore.putEntry` writes them verbatim, hidden state included, which is
+  // the whole point of a relocation.
+  const entries = remote ? collected.filter((e) => isLive(e)) : collected;
+  const skipped = collected.length - entries.length;
 
   heading('LoreKit migrate');
   log(`  from: ${c.dim(src)}`);
   log(`  to:   ${c.dim(destLabel)}`);
   log(`  mode: ${apply ? c.bold('apply') : 'dry-run — pass --yes to apply'}`);
-  log(`  found: ${entries.length} entr${entries.length === 1 ? 'y' : 'ies'}\n`);
+  log(`  found: ${collected.length} entr${collected.length === 1 ? 'y' : 'ies'}\n`);
+  for (const w of remoteWarnings) status('warn', 'token', w);
+  if (skipped > 0) {
+    status('warn', 'skipped', `${skipped} archived or expired entr${skipped === 1 ? 'y' : 'ies'} — not representable remotely`);
+  }
+
+  // Stay under the hosted 120 req/min ceiling proactively, and survive a 429
+  // reactively. Both are no-ops for a local destination, which issues no
+  // requests at all — `pace()` never fills its window and `withRetry` never
+  // sees a rate-limited result.
+  let pacedOnce = false;
+  const pace = remote
+    ? createPacer({
+      // The pacer's wait is deliberately NOT `options.sleepFn`. That seam
+      // exists so a retry test does not wait out a backoff, and a sleep that
+      // returns without the clock advancing would spin this window forever.
+      // Pacing is bounded by real time, always.
+      sleepFn: async (ms) => {
+        // Say it once. A few-thousand-entry store otherwise sits silent for
+        // minutes after the header and looks hung.
+        if (!pacedOnce) {
+          pacedOnce = true;
+          status('info', 'pacing', 'staying under the hosted rate limit — this run will take longer');
+        }
+        return sleep(ms);
+      },
+      ...(options.maxPerWindow ? { maxPerWindow: options.maxPerWindow } : {}),
+      ...(options.windowMs ? { windowMs: options.windowMs } : {}),
+    })
+    : async () => {};
+  const call = async (fn) => {
+    if (!remote) return fn();
+    // `pace()` is INSIDE the retried function, so every attempt is counted
+    // against the window. Pacing only the first one would leave the ceiling
+    // unenforced during exactly the 429 episodes it exists to prevent.
+    return withRetry(async () => { await pace(); return fn(); }, {
+      sleepFn: options.sleepFn,
+      onRetry: ({ attempt, delayMs }) =>
+        status('warn', 'rate limit', `retrying in ${Math.round(delayMs / 1000)}s (attempt ${attempt})`),
+    });
+  };
 
   const totals = { add: 0, update: 0, noop: 0 };
   const byScope = new Map();
+  let capped = null;
+  let failed = 0;
+  // Named, not merely counted — the same courtesy the failure list gets, so a
+  // user knows WHICH lessons were altered rather than how many.
+  const clamped = [];
+  const redated = [];
+  // A blip is worth retrying; an outage is not. Once this many entries fail
+  // back to back the destination is not having a bad moment, it is down — and
+  // continuing means every remaining entry pays the full retry budget before
+  // failing anyway. Reset by any entry that succeeds.
+  const failureLimit = options.consecutiveFailureLimit ?? DEFAULT_CONSECUTIVE_FAILURE_LIMIT;
+  let consecutiveFailures = 0;
+  let abandoned = false;
   for (const entry of entries) {
     const store = targetFor(entry.scope);
-    const current = store.getEntry({ scope: entry.scope, key: entry.key });
+    // Awaited so the loop is destination-agnostic: LocalStore.getEntry is
+    // synchronous and awaiting its plain return value is a no-op, while a
+    // remote destination's is a REST round-trip. One code path, both stores.
+    //
+    // A remote read that FAILS throws rather than answering null (see
+    // `RemoteStore.getEntry`), precisely so it cannot be mistaken for "not
+    // there" and overwrite a hosted lesson. Report that entry and move on: one
+    // unreadable key must not abort a migration, and it must not be counted as
+    // migrated either. The local store never throws here.
+    let current;
+    try {
+      // A write-only token's reads are denied, so asking would 403 every entry
+      // and fail a run the preflight just promised would work. Skip straight
+      // to the write; the hosted upsert is idempotent either way.
+      current = classifyRemote
+        ? await call(() => store.getEntry({ scope: entry.scope, key: entry.key }))
+        : null;
+    } catch (e) {
+      failed++;
+      status('fail', entry.scope, `${entry.key}: ${e?.message || 'read failed'}`);
+      if (++consecutiveFailures >= failureLimit) { abandoned = true; break; }
+      continue;
+    }
     let verdict;
     if (!current) verdict = 'add';
-    else if (sameEntry(current, entry)) verdict = 'noop';
+    else if (remote ? sameRemoteEntry(current, entry, now) : sameEntry(current, entry)) verdict = 'noop';
     else verdict = 'update';
 
+    // What this entry WOULD lose, computed from the entry itself so a DRY RUN
+    // warns about exactly what an apply would do — reporting it only on the
+    // write made the preview quietly less informative than the thing it
+    // previews. Recorded only once the outcome is known, though: a write that
+    // failed shortened nothing.
+    const losses = remote && verdict !== 'noop'
+      ? remoteWriteLosses(entry, now)
+      : { ttlClamped: false, createdAtDropped: false };
+    const recordLosses = () => {
+      if (losses.ttlClamped) clamped.push(`${entry.scope}::${entry.key}`);
+      if (losses.createdAtDropped) redated.push(`${entry.scope}::${entry.key}`);
+    };
+    if (!apply) recordLosses();
+
+    if (apply && verdict !== 'noop') {
+      const res = await call(() => store.putEntry(entry, { now }));
+      if (res && res.ok === false) {
+        // The memory cap is terminal for the whole run, not just this entry:
+        // every remaining write would hit the same ceiling. Stop, and report
+        // what did land — a partial migration the user can resume after
+        // archiving or upgrading is far more useful than a stack trace.
+        if (isMemoryCap(res)) {
+          capped = res.error?.message || 'memory cap reached';
+          break;
+        }
+        failed++;
+        status('fail', entry.scope, `${entry.key}: ${res.error?.message || res.networkError || 'write failed'}`);
+        if (++consecutiveFailures >= failureLimit) { abandoned = true; break; }
+        continue; // not counted as migrated — the report must not claim it
+      }
+      recordLosses(); // the write landed, so the loss actually happened
+    }
+    consecutiveFailures = 0;
+
     totals[verdict]++;
     const s = byScope.get(entry.scope) || { add: 0, update: 0, noop: 0 };
     s[verdict]++;
     byScope.set(entry.scope, s);
-
-    if (apply && verdict !== 'noop') await store.putEntry(entry);
   }
 
   for (const [scope, s] of byScope) {
@@ -144,6 +492,38 @@ export async function migrate(args) {
     `  ${apply ? 'migrated' : 'would migrate'} ${moved} entr${moved === 1 ? 'y' : 'ies'} ` +
       `(${totals.add} new, ${totals.update} updated), ${totals.noop} unchanged.`,
   );
+  if (skipped > 0) log(`  ${skipped} skipped (archived or expired).`);
+  reportAltered(clamped, apply, 'TTL shortened to the hosted maximum of 365 days');
+  reportAltered(redated, apply, 'unusable created date dropped — the server stamps the write instant');
+
+  // A cap can fire after an entry has already failed, so the failure count is
+  // reported on BOTH exits — it used to be lost whenever the cap won the race.
+  const reportFailures = () => {
+    if (failed > 0) {
+      // "failed", not "failed to write" — an entry lands here from an
+      // unreadable classification as well as from a rejected write.
+      err(`${c.red('migrate:')} ${failed} entr${failed === 1 ? 'y' : 'ies'} failed (listed above).`);
+    }
+  };
+  if (abandoned) {
+    err(`\n${c.red('migrate:')} stopped after ${failureLimit} consecutive failures — the destination looks unavailable.`);
+    log(`  ${moved} entr${moved === 1 ? 'y' : 'ies'} migrated before it gave up.`);
+    log(`  ${c.dim('Re-run when it is healthy — the migration resumes where it stopped.')}`);
+    reportFailures();
+    return 1;
+  }
+  if (capped) {
+    err(`\n${c.red('migrate:')} ${capped}`);
+    log(`  ${moved} entr${moved === 1 ? 'y' : 'ies'} migrated before the cap was reached.`);
+    log(`  ${c.dim('Archive unused memories or raise the plan limit, then re-run — the migration resumes where it stopped.')}`);
+    reportFailures();
+    return 1;
+  }
+  if (failed > 0) {
+    err('');
+    reportFailures();
+    return 1;
+  }
   if (!apply && moved > 0) log(`  ${c.dim('Re-run with --yes to apply.')}`);
   return 0;
 }

package/src/store/format.mjs

@@ -29,7 +29,7 @@ export const FIELDS = [
   // columns: a file written before this existed simply decodes it as absent.
   'expires_at',
   // Recurrence — how many times this lesson has been written, mirroring the
-  // hosted `memories.seen_count` column (migration 00058) so an offline store
+  // hosted `memories.seen_count` column (migration 00059) so an offline store
   // carries the same salience signal a remote one does. Appended like the
   // columns above: a file written before this existed decodes it as absent,
   // which the read projection reports as 0 rather than inventing a count.

package/src/store/local.mjs

@@ -134,7 +134,7 @@ class LocalStore {
       archived_at: null,
       expires_at,
       // Recurrence, counted the way the hosted `memory_write` RPC counts it
-      // (migration 00058): a write against a key this store already holds IS
+      // (migration 00059): a write against a key this store already holds IS
       // the next sighting. `seenCountOf` floors an absent/hand-edited value to
       // 0, so a file written before this column existed resumes at 1 on its
       // next write rather than throwing or restarting the tally at 2.

package/src/store/rate-limit.mjs

@@ -0,0 +1,149 @@
+// Client-side rate-limit handling for a bulk REST push (`migrate --to remote`).
+//
+// The hosted API allows 120 requests/min/user (docs/limits.md), enforced by a
+// Postgres fixed-window counter. A migration is the one CLI flow that can
+// exceed that on its own: it issues up to two requests per entry (a read to
+// classify, a write to apply), so a few hundred lessons blow the window in
+// seconds. Two independent guards, because either alone is wrong:
+//
+//   `createPacer`  — PROACTIVE. Keeps the client under a self-imposed ceiling
+//                    below the server's, so a normal run never trips the limit
+//                    and never pays a retry.
+//   `withRetry`    — REACTIVE. The ceiling is a guess (the limit is per USER,
+//                    not per process — a concurrent agent shares it, and a
+//                    per-user override can move it), so a 429 must still be
+//                    survivable rather than a failed migration.
+//
+// Both take their clock and sleep as parameters, so the tests are instant and
+// deterministic rather than actually waiting out a window.
+//
+// Zero-dependency.
+
+export const DEFAULT_MAX_PER_WINDOW = 100; // under the 120/min server limit
+export const WINDOW_MS = 60_000;
+export const DEFAULT_MAX_ATTEMPTS = 5;
+// After this many entries fail in a row, stop retrying and let the caller
+// abort. Retrying is worth it for a blip; a systematic outage just turns a
+// 2,000-entry push into hours of backoff before failing anyway.
+export const DEFAULT_CONSECUTIVE_FAILURE_LIMIT = 5;
+export const DEFAULT_RETRY_DELAY_MS = 1_000;
+export const MAX_RETRY_DELAY_MS = 60_000;
+
+export function sleep(ms) {
+  return new Promise((resolve) => setTimeout(resolve, Math.max(0, ms)));
+}
+
+/**
+ * A sliding-window pacer: `await pace()` before each request.
+ *
+ * Returns immediately while fewer than `maxPerWindow` requests were issued in
+ * the last `windowMs`; otherwise waits exactly until the oldest one falls out
+ * of the window. A small migration therefore runs at full speed and pays
+ * nothing for this, and a large one self-throttles instead of being throttled.
+ */
+export function createPacer({
+  maxPerWindow = DEFAULT_MAX_PER_WINDOW,
+  windowMs = WINDOW_MS,
+  now = () => Date.now(),
+  sleepFn = sleep,
+} = {}) {
+  const issued = [];
+  return async function pace() {
+    for (;;) {
+      const cutoff = now() - windowMs;
+      while (issued.length && issued[0] <= cutoff) issued.shift();
+      if (issued.length < maxPerWindow) {
+        issued.push(now());
+        return;
+      }
+      // Wait out the oldest request, then re-check: the clock moved, so the
+      // window has to be re-evaluated rather than assumed clear.
+      await sleepFn(issued[0] + windowMs - now() + 1);
+    }
+  };
+}
+
+/**
+ * Whether a store result is a retryable rate-limit rejection.
+ *
+ * `memory_cap` is the reason this is a function and not a status comparison:
+ * the memory-cap trigger (LK001) is ALSO translated to HTTP 429
+ * (supabase/functions/_shared/api/errors.ts), and it is terminal — retrying it
+ * just burns the user's rate budget on a write that can never succeed.
+ */
+export function isRateLimited(res) {
+  return Boolean(res && res.httpStatus === 429 && res.error?.code !== 'memory_cap');
+}
+
+/**
+ * Whether a store result is worth trying again at all.
+ *
+ * Wider than `isRateLimited` on purpose. This module exists for a BULK push of
+ * potentially thousands of requests, which is precisely the shape of run where
+ * a single transient 5xx or a dropped connection is likeliest — and failing
+ * one entry out of two thousand for a blip the next attempt would sail through
+ * is a bad trade. So a 5xx and a transport error retry too.
+ *
+ * What does NOT retry is anything the server has decided: a 4xx is a rejection
+ * (bad scope, denied permission), and `memory_cap` is terminal even though it
+ * arrives as a 429. Retrying either just burns the user's rate budget.
+ */
+export function isRetryable(res) {
+  if (!res || isMemoryCap(res)) return false;
+  if (res.networkError) return true;
+  if (isRateLimited(res)) return true;
+  return typeof res.httpStatus === 'number' && res.httpStatus >= 500;
+}
+
+/** Whether a store result is the terminal memory-cap rejection. */
+export function isMemoryCap(res) {
+  return Boolean(res && res.error?.code === 'memory_cap');
+}
+
+/**
+ * Run `fn` and retry it while it comes back retryable (see `isRetryable`).
+ *
+ * Honours the server's own `Retry-After` when it sent one — it knows when its
+ * window rolls over and the client does not — and falls back to exponential
+ * backoff otherwise. Returns the last result once the attempts are spent, so
+ * the caller reports a real error rather than a synthesised one; `onRetry` is
+ * for progress output.
+ */
+export async function withRetry(fn, {
+  maxAttempts = DEFAULT_MAX_ATTEMPTS,
+  baseDelayMs = DEFAULT_RETRY_DELAY_MS,
+  sleepFn = sleep,
+  onRetry = null,
+} = {}) {
+  let res;
+  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
+    // A read reports a rate limit by THROWING (`RemoteStore.getEntry` refuses
+    // to let a failed read look like an absence), so the rejection has to be
+    // classified here too — otherwise only writes would ever be retried and a
+    // 429 on the classifying read would fail the entry outright. Anything that
+    // is not a rate limit propagates untouched.
+    try {
+      res = await fn();
+    } catch (e) {
+      if (!isRetryable(e?.result) || attempt === maxAttempts) throw e;
+      await sleepFn(retryDelay(e.result, attempt, baseDelayMs, onRetry));
+      continue;
+    }
+    if (!isRetryable(res) || attempt === maxAttempts) return res;
+    await sleepFn(retryDelay(res, attempt, baseDelayMs, onRetry));
+  }
+  return res;
+}
+
+// How long to wait before the next attempt: the server's own hint when it sent
+// one — it knows when its window rolls over and the client does not — else
+// exponential backoff. Shared by the resolved and the thrown path so the two
+// cannot drift.
+function retryDelay(res, attempt, baseDelayMs, onRetry) {
+  const hinted = Number(res?.retryAfter);
+  const delayMs = Number.isFinite(hinted) && hinted > 0
+    ? Math.min(hinted * 1000, MAX_RETRY_DELAY_MS)
+    : Math.min(baseDelayMs * 2 ** (attempt - 1), MAX_RETRY_DELAY_MS);
+  if (onRetry) onRetry({ attempt, delayMs });
+  return delayMs;
+}

package/src/store/remote.mjs

@@ -21,6 +21,7 @@
 import { restFetch, mcpToRestBase } from '../mcp.mjs';
 import { getActiveTraceparent } from '../telemetry.mjs';
 import { withReadFields } from './entry-fields.mjs';
+import { normalizeCreatedAt } from './created-at.mjs';
 
 // Drop undefined/null args so JSON payloads stay tidy.
 function stripUndefined(obj) {
@@ -29,6 +30,90 @@ function stripUndefined(obj) {
   return out;
 }
 
+/**
+ * A read that could not be answered — a transport failure or a non-2xx status,
+ * as opposed to "the lesson is not there".
+ *
+ * Exported so a caller can tell it from a programming error and degrade
+ * per-entry (report this one, keep going) instead of aborting a whole run.
+ * `result` carries the raw store envelope for the message the caller shows.
+ */
+export class StoreReadError extends Error {
+  constructor(message, result) {
+    super(message);
+    this.name = 'StoreReadError';
+    this.result = result;
+  }
+}
+
+/**
+ * What a remote write of `entry` would lose, without performing it.
+ *
+ * Exported because a DRY RUN has to be able to say the same thing the apply
+ * will: a preview that omits "this entry's expiry will be shortened" is a
+ * preview of a different operation. `putEntry` calls it too, so the two
+ * cannot drift.
+ *
+ *   `ttlClamped`        the entry's TTL exceeds the API's 365-day maximum and
+ *                       will land shortened.
+ *   `createdAtDropped`  the entry's `created` is unusable (unparseable or
+ *                       future-dated), so the override is dropped and the
+ *                       server stamps the write instant instead.
+ *
+ * Total over any input: a malformed entry reports no losses rather than
+ * throwing, because this runs on the preview path where an exception would
+ * cost the user the whole plan.
+ */
+export function remoteWriteLosses(entry, now = new Date()) {
+  const exact = remoteTtlDaysExact(entry?.expires_at, now);
+  return {
+    ttlClamped: typeof exact === 'number' && exact > 365,
+    createdAtDropped: Boolean(entry?.created) && safeCreatedAt(entry?.created, now) === null,
+  };
+}
+
+// `normalizeCreatedAt`, but an invalid value yields null instead of throwing.
+function safeCreatedAt(created, now) {
+  try {
+    return normalizeCreatedAt(created ?? null, now);
+  } catch {
+    return null;
+  }
+}
+
+// An absolute `expires_at` expressed as the hosted write's relative `ttl_days`.
+//
+// Three outcomes, and the third exists because "no expiry" and "I cannot tell"
+// must not collapse into one answer:
+//
+//   `undefined`  no expiry — the caller states that positively with
+//                `clear_ttl: true`, so a permanent lesson stops being expiring.
+//   `'expired'`  already elapsed; the caller must refuse (see `putEntry`).
+//   `'unknown'`  an unparseable value. The caller then sends NEITHER TTL field,
+//                leaving the RPC on its `'keep'` branch, because the safe
+//                reading of a corrupt frontmatter field is "do not touch the
+//                expiry" — the same fail-safe posture as `isExpired`. Treating
+//                it as no expiry would let one bad character wipe a live remote
+//                TTL.
+//
+//   else         the remaining WHOLE days, clamped to the schema's 1–365.
+function remoteTtlDays(expiresAt, now = new Date()) {
+  const exact = remoteTtlDaysExact(expiresAt, now);
+  if (typeof exact !== 'number') return exact;
+  return Math.min(365, Math.max(1, exact));
+}
+
+// The same conversion WITHOUT the 1–365 clamp, so a caller can see that the
+// clamp bound and report the loss. Same three non-numeric outcomes.
+function remoteTtlDaysExact(expiresAt, now = new Date()) {
+  if (!expiresAt) return undefined;
+  const ms = Date.parse(expiresAt);
+  if (Number.isNaN(ms)) return 'unknown';
+  const remaining = ms - now.getTime();
+  if (remaining <= 0) return 'expired';
+  return Math.ceil(remaining / 86_400_000);
+}
+
 export function createRemoteStore({ endpoint, token } = {}) {
   return new RemoteStore(endpoint, token);
 }
@@ -151,7 +236,24 @@ class RemoteStore {
     // scope+key is unique, so one row is all there can be — don't pull the default page of 50.
     p.set('limit', '1');
     const res = await this._rest(`/memories?${p}`);
-    if (!res.ok) return { ok: false, error: res.error, networkError: res.networkError };
+    // `unusable` is passed through: `_rest` short-circuits an unconfigured
+    // store with that flag and NOTHING else, so a caller that drops it is left
+    // with a failure carrying no error and no networkError — a blank failure it
+    // can only report generically. Additive; every existing caller branches on
+    // `ok` and ignores the extra key.
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: res.error ?? null,
+        // Carried for the same reason `write` carries them: a read can be
+        // rate-limited too, and a caller that retries needs to tell a 429 it
+        // should wait out from one it must not.
+        httpStatus: res.httpStatus ?? null,
+        retryAfter: res.retryAfter ?? null,
+        networkError: res.networkError ?? null,
+        unusable: res.unusable ?? false,
+      };
+    }
     const entries = res.data?.entries ?? [];
     // Same projection as list/search — a single read must not answer with a
     // different shape than the listing the caller found the key in.
@@ -181,7 +283,214 @@ class RemoteStore {
     if (origin_commit !== undefined) body.origin_commit = origin_commit;
     if (origin_pr !== undefined) body.origin_pr = origin_pr;
     const res = await this._rest('/memories', { method: 'POST', body });
-    return { ok: res.ok, error: res.error, networkError: res.networkError };
+    // `httpStatus` and `retryAfter` are passed through so a caller can tell the
+    // two 429s apart and honour the server's own backoff. They are DIFFERENT
+    // failures wearing one status code: `code: 'rate_limited'` is transient and
+    // must be retried, `code: 'memory_cap'` is terminal (translateDbError maps
+    // the LK001 cap trigger to 429 as well) and must not be. Additive — the
+    // existing `{ ok, error, networkError }` keys are unchanged.
+    // Every field is coalesced, not just the retry hint: a caller comparing
+    // `httpStatus` must not get `null` from a refusal and `undefined` from the
+    // network-error or `unusable` branch, which is the exact split the shape
+    // exists to remove.
+    return {
+      ok: res.ok,
+      error: res.error ?? null,
+      httpStatus: res.httpStatus ?? null,
+      retryAfter: res.retryAfter ?? null,
+      networkError: res.networkError ?? null,
+      // `_rest` short-circuits an unconfigured store with `{ ok:false,
+      // unusable:true }` and no error at all, so without this the caller sees
+      // a failure with every field null and no reason. Passed through the way
+      // `listScopes` already does.
+      unusable: res.unusable ?? false,
+    };
+  }
+
+  // ── Migrate-destination parity with LocalStore ────────────────────────────
+  //
+  // `migrate` classifies each source entry ADD / UPDATE / NOOP with a read and
+  // then upserts it, against whatever store it was handed. LocalStore answers
+  // that with `getEntry` + `putEntry`; these are the remote halves, so the
+  // migrate loop stays ONE code path instead of branching per destination.
+  //
+  // The local pair is lossless (`putEntry` writes every field verbatim,
+  // archived rows included). The remote pair CANNOT be, because the hosted
+  // write is an RPC with a fixed parameter list, not a file write:
+  //
+  //   preserved  scope, key, source_agent, trigger, and `created` —
+  //              sent as `created_at`, which memory_write honours on INSERT
+  //              only, so a migrated lesson keeps its original creation date
+  //              and its ranking recency with it. `value` survives too but is
+  //              TRIMMED: `MemoryWriteSchema` applies `.transform(s =>
+  //              s.trim())`, so surrounding whitespace does not make the trip.
+  //   re-stamped `updated` — the server sets it to the write instant. There is
+  //              no parameter for it, and inventing one would let a client
+  //              backdate an edit it did not make.
+  //   derived    `seen_count` — the RPC owns the tally (migration 00059: a
+  //              write against an existing key IS the next sighting). A lesson
+  //              the hosted store has never seen lands at 1; one it already
+  //              holds lands at ITS count plus one, not the local one. Either
+  //              way the local history does not transfer.
+  //   converted  `expires_at` → `ttl_days`, the remaining whole days, clamped
+  //              to the schema's 1–365 (a longer-lived TTL is clamped, not
+  //              dropped — the alternative is silently making it permanent).
+  //              A clamp IS lossy, so it is reported: the result carries
+  //              `ttlClamped: true` and the caller can list the entry as
+  //              shortened rather than leaving the user to discover it.
+  //              A PERMANENT entry sends `clear_ttl: true` rather than simply
+  //              omitting `ttl_days`: omission is the RPC's `'keep'` branch
+  //              (migration 00031), which leaves an existing remote
+  //              `expires_at` in place, so a permanent local lesson would
+  //              land on an expiring remote row and still die.
+  //   authoritative
+  //              `tags`. The conflict clause is `tags = excluded.tags`, so the
+  //              source entry's list REPLACES the hosted one — an untagged
+  //              local entry sends `[]` and clears whatever labels the hosted
+  //              row carried. That is what a verbatim upsert means here (the
+  //              local file is the thing being migrated), but it is the one
+  //              field where "verbatim" can remove hosted data, so it is
+  //              called out rather than filed under preserved.
+  //   sticky     `origin_*`. The RPC's conflict clause coalesces provenance
+  //              (`coalesce(excluded.origin_repo, memories.origin_repo)`, and
+  //              likewise for branch/commit/pr) so a write that does not know
+  //              a field cannot erase what an earlier one recorded. A migrated
+  //              entry with NO provenance therefore leaves whatever the hosted
+  //              row already had; it cannot clear it, by design, and there is
+  //              no parameter that would. `source_agent` and `trigger` are NOT
+  //              coalesced (`= excluded.*`), so an absent one still CLEARS the
+  //              hosted value — not because a null is sent (`stripUndefined`
+  //              drops nulls before the request) but because the REST handler
+  //              substitutes `?? null` for the missing field and the RPC
+  //              writes that. Omitted and null are the same instruction here,
+  //              which is the opposite of what they mean for `origin_*`. `kind` and `host` are coalesced the same
+  //              way, and this store never sends them at all — the server
+  //              infers both from the `loop::` tag (`resolveKindHost`), which
+  //              the tags carry, so a migrated lesson classifies itself.
+  //
+  // Two states have no remote representation at all and are REFUSED rather
+  // than silently rewritten, because writing them would resurrect a lesson the
+  // user retired: an archived entry (every conflict predicate on `memories` is
+  // partial on `archived_at is null`, so the hosted write does not revive the
+  // archived row — it INSERTS a second, live one beside it, leaving the store
+  // with both) and
+  // an already-expired one (any `ttl_days` re-dates it into the future). Both
+  // come back as `{ ok:false, unsupported }` so the caller can report them as
+  // skipped. `migrate` does NOT filter them today — adding that filter is the
+  // job of the PR that makes a remote destination reachable — so until then
+  // this refusal is the only thing standing between an archived lesson and
+  // resurrection, which is why it lives in the store and not in the caller.
+
+  // Raw lookup by scope+key, mirroring `LocalStore.getEntry` — the entry or
+  // null. The ROW is each store's own: this answers a REST `MemoryEntry`
+  // (`created_at`/`updated_at`) and the local one answers parsed frontmatter
+  // (`created`/`updated`), both through `withReadFields`. That is deliberate —
+  // the pair exists so a caller can ASK either store whether a key is there,
+  // not so it can compare two rows field-by-field without knowing which store
+  // produced them. A caller that compares has to speak the destination's
+  // spelling; that is what the remote comparison in the migrate loop does. LocalStore's is synchronous and this one cannot be, so callers must
+  // `await` it; awaiting the local store's plain return value is a no-op.
+  //
+  // One semantic difference the caller has to know about: LocalStore.getEntry
+  // sees archived rows and this cannot — `GET /memories` filters them out — so
+  // a remote destination classifies an archived counterpart as ADD, and the
+  // write then lands as a NEW live row beside the archived one (the conflict
+  // predicates are partial on `archived_at is null`). That is what the hosted
+  // `memory_write` does for any write against an archived key, not a
+  // migrate-specific quirk — and it is why `putEntry` refuses an archived
+  // source entry outright rather than relying on this classification.
+  //
+  // A FAILED read THROWS rather than answering null. Null is the answer to "no
+  // such lesson", and a caller that classifies ADD / UPDATE / NOOP acts on it:
+  // returning null for a transient 500 or a dropped connection would quietly
+  // reclassify an existing hosted lesson as new and overwrite it. The local
+  // store never throws here (a file read that fails is genuinely a miss), so
+  // this widens the contract only where the failure mode exists.
+  async getEntry({ scope, key } = {}) {
+    const res = await this.read({ scope, key });
+    if (!res.ok) {
+      // An unconfigured store carries no error at all, so name that case
+      // rather than reporting the generic failure text for it.
+      const reason = res.unusable
+        ? 'the remote store is not configured (missing endpoint or token)'
+        : (res.networkError || res.error?.message || 'read failed');
+      throw new StoreReadError(`remote read failed for ${scope}::${key}: ${reason}`, res);
+    }
+    return res.entry ?? null;
+  }
+
+  // Upsert one entry, as close to verbatim as the hosted write allows. See the
+  // fidelity table above for exactly which fields survive.
+  //
+  // EVERY branch answers with the SAME key set — `write`'s
+  // `{ ok, error, httpStatus, retryAfter, networkError, unusable }` plus
+  // Unlike `LocalStore.putEntry`, no `entry` comes back: the hosted write
+  // returns an id and derives the rest server-side, so echoing the request as
+  // if it were the stored row would be a fabrication. A caller that needs the
+  // stored row reads it back.
+  //
+  // `unsupported` (the refusal reason, else null), `ttlClamped` (the entry
+  // landed with a shortened life) and `createdAtDropped` (its `created` was
+  // unusable, so the server stamped the write instant instead). The last two
+  // report what HAPPENED, so both are false when the write did not succeed. A refusal fills the transport fields
+  // with null rather than omitting them, so a caller reading any one key never
+  // gets a value from one branch and `undefined` from another.
+  async putEntry(entry = {}, { now = new Date() } = {}) {
+    const refuse = (unsupported, message) => ({
+      ok: false,
+      unsupported,
+      // Carries a `code` like every real failure, so a caller can branch on
+      // one field instead of matching prose.
+      error: { message, code: 'unsupported' },
+      httpStatus: null,
+      retryAfter: null,
+      networkError: null,
+      // Every key any putEntry branch answers with, so a caller reading one
+      // never gets a value from one branch and `undefined` from another.
+      unusable: false,
+      ttlClamped: false,
+      createdAtDropped: false,
+    });
+    if (entry?.archived_at) {
+      return refuse('archived', 'archived entries cannot be written remotely — the hosted write would insert a second, live row beside the archived one');
+    }
+    const ttl = remoteTtlDays(entry?.expires_at, now);
+    if (ttl === 'expired') {
+      return refuse('expired', 'expired entries cannot be written remotely — any TTL would re-date them into the future');
+    }
+    // What this write will lose, decided by the same pure function a DRY RUN
+    // calls — so a preview cannot promise something the apply then silently
+    // does differently.
+    const { ttlClamped, createdAtDropped } = remoteWriteLosses(entry, now);
+    const createdAt = createdAtDropped ? undefined : (safeCreatedAt(entry?.created, now) ?? undefined);
+    const result = await this.write(stripUndefined({
+      scope: entry.scope,
+      key: entry.key,
+      value: entry.value == null ? '' : String(entry.value),
+      tags: Array.isArray(entry.tags) ? entry.tags : [],
+      source_agent: entry.source_agent,
+      trigger: entry.trigger,
+      created_at: createdAt,
+      // `'unknown'` sends neither field, leaving the RPC on its `'keep'`
+      // branch. A real TTL sends only `ttl_days`; no TTL says so explicitly
+      // with `clear_ttl` rather than by omission — see the fidelity note above.
+      ttl_days: typeof ttl === 'number' ? ttl : undefined,
+      clear_ttl: ttl === undefined ? true : undefined,
+      origin_repo: entry.origin_repo,
+      origin_branch: entry.origin_branch,
+      origin_commit: entry.origin_commit,
+      origin_pr: entry.origin_pr,
+    }));
+    // Always present, like every other key in this envelope — a caller must
+    // not have to know which branch produced the result to read it.
+    // Both flags describe what HAPPENED, so they are false on a write that did
+    // not happen — a failed request shortened nothing and re-dated nothing.
+    return {
+      ...result,
+      unsupported: null,
+      ttlClamped: Boolean(result.ok) && ttlClamped,
+      createdAtDropped: Boolean(result.ok) && createdAtDropped,
+    };
   }
 
   // Natural-key DELETE. Without `force` the server soft-archives (stamps

package/src/util.mjs

@@ -21,12 +21,32 @@ export const sym = {
   info: useColor ? c.cyan('•') : '-',
 };
 
+// Where `log` and `err` send their output. Indirected through a mutable pair
+// so a test can capture a command's output WITHOUT hijacking
+// `process.stdout.write` — which is not a private channel: `node --test` runs
+// each file in a child process and reports results over that same stdout, so a
+// global hijack silently swallows the runner's own result lines and a failing
+// test can go unreported. Production behaviour is unchanged; the default
+// writers are the streams themselves.
+let writers = {
+  out: (s) => process.stdout.write(s),
+  err: (s) => process.stderr.write(s),
+};
+
+// Redirect `log`/`err` (and therefore `heading`/`status`, which build on them).
+// Returns the restore function, so a caller cannot forget what it replaced.
+export function setWriters(next = {}) {
+  const previous = writers;
+  writers = { ...writers, ...next };
+  return () => { writers = previous; };
+}
+
 export function log(msg = '') {
-  process.stdout.write(`${msg}\n`);
+  writers.out(`${msg}\n`);
 }
 
 export function err(msg = '') {
-  process.stderr.write(`${msg}\n`);
+  writers.err(`${msg}\n`);
 }
 
 export function heading(title) {