@lorekit/cli 1.51.0 → 1.52.1

package/README.md

@@ -597,7 +597,7 @@ erases your cross-repo home lesson.
 > sharing comes from the account/token, so remote needs no second location.
 > Different mechanism, same concept.
 
-### `lorekit migrate` — relocation / rename tool
+### `lorekit migrate` — relocate a store, or push one to the hosted store
 
 Moved or renamed a local store (e.g. an old `.lore/`)? `migrate` re-writes its
 entries into the current two-tier layout so lessons are never stranded:
@@ -612,6 +612,80 @@ Dry-run (preview) by default; `--yes` (or `--apply`) applies. Idempotent — a
 re-run is a no-op. It reads LoreKit's own on-disk format only (it does **not**
 import persistent-memory's `~/.agent-memory/<bucket>/` format).
 
+#### `--to remote` — bring your local lessons up
+
+Started offline and later connected a token? `--to remote` pushes the whole
+local store to the hosted one in a single command, instead of the agent
+re-writing lessons one at a time in remote mode:
+
+```bash
+lorekit migrate --from .lorekit --to remote         # dry-run: the plan, per scope
+lorekit migrate --from .lorekit --to remote --yes   # push it
+```
+
+The connection and token come from the same place every other command reads
+them (`.mcp.json` / `.lorekit.json` / `LOREKIT_MCP_URL` + `LOREKIT_TOKEN`), so
+a `deny: remote` constraint still wins. Everything is checked **before** the
+first request rather than mid-push:
+
+| Condition | Result |
+|---|---|
+| No usable connection | Fails with the `lorekit install` command to run |
+| Read-only `lk_ro_*` token | Fails — a migration writes |
+| Write-only `lk_wo_*` token | Warns, then pushes without reading: its reads are denied, so the destination is not classified at all and every entry reports as `add` (the hosted upsert is idempotent either way) |
+| Unrecognized token prefix | Warns and proceeds, so a self-hosted or custom token still works |
+| `deny: remote` | Fails, naming the config source that denied it |
+
+**What transfers, and what the server owns.** `scope`, `key`, `value`,
+`source_agent` and `trigger` travel as the source states them (`value` is
+trimmed server-side), and the original creation date travels as `created_at` —
+so a migrated lesson keeps the recency its ranking depends on. The rest is not
+verbatim, and every departure is reported per entry, in the dry run as well as
+the apply:
+
+| Field | What happens |
+|---|---|
+| `updated` | Re-stamped at the write instant — there is no parameter for it |
+| `seen_count` | Starts at 1 for a key the hosted store has never seen; one it already holds lands at ITS count plus one (the RPC treats a write as a sighting, migration 00059). A local tally of 12 never transfers |
+| `tags` | **Replace** the hosted row's labels, so an untagged local entry clears them |
+| `origin_*` | **Sticky** — the RPC coalesces provenance, so an entry carrying none leaves whatever the hosted row already had |
+| `created` | Honoured only when the lesson is new to the hosted store (the RPC's update clause omits it, so one already there keeps its hosted date); an unusable or future-dated value is dropped for the write instant, and the entry is named |
+| `expires_at` | Converted to the remaining whole `ttl_days`; anything beyond the API's 365-day cap lands shortened |
+
+**Archived and expired entries are skipped** and reported as such. Neither can
+be represented: a write against an archived key inserts a second, live row
+beside it rather than reviving it, and any TTL would re-date an expired row
+into the future — so pushing them would resurrect lore you retired.
+
+Idempotent, with one nuance: a re-run compares only what a hosted write can
+change, and compares it the way the server stores it — trimmed `value`, only
+the provenance the source carries, and an expiry that still honours the local
+intent (the hosted one is fixed at push time while the local one is measured
+from now, so it is judged on whether at least half the intended life remains —
+matching them instant-for-instant could never converge). Comparing the server-owned fields
+directly would report a change forever and re-push the whole store on every
+run. A remote `unchanged` therefore means "the hosted lesson already says
+this", not "byte-identical row".
+
+Rate limits and transient failures are handled rather than surfaced as
+failures. The run paces itself under the hosted 120 req/min limit (and says so
+the first time it has to wait), and retries a `429` on the server's own
+`Retry-After` — plus a 5xx or a dropped connection, which on a push of
+thousands of requests is the likeliest failure and the least worth losing an
+entry to. Any other 4xx is a decision, not a blip, and is never retried.
+
+Retrying is bounded, so none of this should be read as "it never fails": an
+entry that exhausts its attempts is reported and the run exits non-zero, and
+five CONSECUTIVE failures of any kind stop the run early with a
+partial-progress report — an outage is not worth grinding a whole store through
+the retry budget for. Every one of those exits is safe to re-run. The memory cap ([5,000 active memories on the
+free plan](../../docs/limits.md)) is returned as a `429` too but is terminal —
+the run stops, reports how many entries landed, and exits non-zero, so you can
+archive or upgrade and re-run to resume.
+
+Not in v1: `--org <slug>` org-owned writes (a migration lands as your personal
+lore) and the reverse remote → local direction.
+
 ### The control model — two layers, deny-wins
 
 Two config layers decide the mode:
@@ -870,7 +944,7 @@ also returns their headroom against the plan's memory cap.
 | `--mode <mode>` | Memory mode override for `doctor`: `off` / `local` / `remote` |
 | `--store <path>` | Local project-tier store directory (default `.lorekit`) |
 | `--from <path>` | Source store to migrate from (`migrate`) |
-| `--to <tier>` | Migration destination tier: `home` / `project` (`migrate`; default routes by scope) |
+| `--to <dest>` | Migration destination: `home` / `project` / `remote` (`migrate`; default routes 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`; `none` removes any already wired) |

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.51.0",
+  "version": "1.52.1",
   "description": "Install the LoreKit shared-memory skill and run health checks for the LoreKit MCP server.",
   "license": "MIT",
   "repository": {

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/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

@@ -46,6 +46,41 @@ export class StoreReadError extends Error {
   }
 }
 
+/**
+ * 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"
@@ -423,20 +458,11 @@ class RemoteStore {
     if (ttl === 'expired') {
       return refuse('expired', 'expired entries cannot be written remotely — any TTL would re-date them into the future');
     }
-    // The same validation the server applies (`_shared/created-at.ts`, mirrored
-    // here), run BEFORE the request rather than discovered as a 400. A local
-    // file can hold a hand-edited or clock-skewed `created`, and losing the
-    // whole lesson over its creation date is the wrong trade: drop the
-    // override, let the server stamp now, and report the loss so the caller
-    // can say which entries were re-dated.
-    let createdAt;
-    let createdAtDropped = false;
-    try {
-      createdAt = normalizeCreatedAt(entry?.created ?? null, now) ?? undefined;
-    } catch {
-      createdAt = undefined;
-      createdAtDropped = Boolean(entry?.created);
-    }
+    // 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,
@@ -462,7 +488,7 @@ class RemoteStore {
     return {
       ...result,
       unsupported: null,
-      ttlClamped: Boolean(result.ok) && ttl === 365 && remoteTtlDaysExact(entry?.expires_at, now) > 365,
+      ttlClamped: Boolean(result.ok) && ttlClamped,
       createdAtDropped: Boolean(result.ok) && createdAtDropped,
     };
   }

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) {