@engramx/client 0.16.0-rc.11 → 0.16.0-rc.13

package/dist/claude-setup.js

@@ -1,37 +1,50 @@
 /**
  * Claude setup — generates MCP config for Claude Code and Claude Cowork.
+ *
+ * ⟨2026-10-13, the bloat audit⟩ ONE generator, ONE writer. This file built its own
+ * `mcpServers.engramx` entry while @engramx/mcp's `connect` built another (connect-config.ts), and
+ * the two had drifted: this path was macOS-only, the other per-OS; this one wrote atomically, the
+ * other did not; the mainnet spellings and the session-key variable differed. The entry now comes
+ * from connect-config.ts (`claudeDesktopConfig`), the Claude Desktop path is per-OS here, and
+ * `installMcpConfig` — atomic, refusing a config it cannot parse — is the one writer, which
+ * `@engramx/mcp connect --write` uses too.
  */
 import * as fs from 'fs';
+import * as os from 'os';
 import * as path from 'path';
 import { atomicWriteFileSync } from './path-utils.js';
+import { VERSION } from './version.js';
+import { claudeDesktopConfig } from './connect-config.js';
 /** Generate the MCP server config block for Claude. */
 export function generateMcpConfig(options) {
-    const env = {
-        ENGRAM_CANISTER_ID: options.canisterId,
-        ENGRAM_SESSION_KEY_PATH: options.sessionKeyPath,
-    };
-    if (options.host && options.host !== 'https://ic0.app') {
-        env['ENGRAM_HOST'] = options.host;
+    return claudeDesktopConfig({
+        canisterId: options.canisterId,
+        host: options.host,
+        clientVersion: options.version ?? VERSION,
+        sessionKeyPath: options.sessionKeyPath,
+    });
+}
+/** The default claude_desktop_config.json path for this OS. */
+function claudeDesktopConfigPath(home) {
+    switch (os.platform()) {
+        case 'darwin':
+            return path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json');
+        case 'win32':
+            return path.join(process.env['APPDATA'] || path.join(home, 'AppData', 'Roaming'), 'Claude', 'claude_desktop_config.json');
+        default:
+            return path.join(home, '.config', 'Claude', 'claude_desktop_config.json');
     }
-    return {
-        mcpServers: {
-            engramx: {
-                command: 'npx',
-                args: ['-y', '@engramx/mcp'],
-                env,
-            },
-        },
-    };
 }
 /** Return the config paths for each Claude product. */
 export function claudeConfigPaths() {
-    const home = process.env['HOME'] || '';
+    const home = process.env['HOME'] || os.homedir();
     return {
         // Claude Code reads user-scope MCP servers from ~/.claude.json (the file
         // `claude mcp add --scope user` writes). ~/.claude/settings.json does NOT
         // carry mcpServers — writing there is a silent no-op for the user.
         claudeCode: path.join(home, '.claude.json'),
-        claudeDesktop: path.join(home, 'Library', 'Application Support', 'Claude', 'claude_desktop_config.json'),
+        // ⟨2026-10-13⟩ Per-OS; it was the macOS path everywhere until the two generators merged.
+        claudeDesktop: claudeDesktopConfigPath(home),
     };
 }
 /**

package/dist/claude-setup.js.map

@@ -1 +1 @@
-{"version":3,"file":"claude-setup.js","sourceRoot":"","sources":["../src/claude-setup.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"claude-setup.js","sourceRoot":"","sources":["../src/claude-setup.ts"],"names":[],"mappings":"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"}

package/dist/cli.d.ts

@@ -1,2 +1,8 @@
 #!/usr/bin/env node
-export {};
+/**
+ * The run this module starts when it is loaded — the command line's whole life.
+ * ⟨2026-10-13⟩ Exported so a test can load the CLI with stubbed network modules and wait for the
+ * command to END (test/pair-migrate.test.ts); before, a test could only wait one tick, which is
+ * enough for --help and not for pair.
+ */
+export declare const finished: Promise<void>;

package/dist/cli.js

@@ -6,11 +6,11 @@ import { pair, PairError } from './pair.js';
 import { NPX_CLIENT, VERSION, pairCommand } from './version.js';
 import { execFileSync } from 'node:child_process';
 import * as path from 'path';
-import { setupOpenClaw, setupGitVersioning, OpenClawNotFoundError, getOpenClawDir, getMemoryDir, isGitRepo, } from './openclaw-setup.js';
+import { setupOpenClaw, setupGitVersioning, OpenClawNotFoundError, OpenClawPluginOutdatedError, OPENCLAW_PLUGIN, outdatedOpenClawPlugins, getOpenClawDir, getMemoryDir, isGitRepo, } from './openclaw-setup.js';
 import { generateMcpConfig, claudeConfigPaths, installMcpConfig } from './claude-setup.js';
-import { migrateOpenClawMemory, recoverOpenClaw, rollbackCheckpoint, listCheckpoints, hasValidPairing, findIncompleteCheckpoint, resumeMigration, } from './migrate.js';
+import { migrateOpenClawMemory, findOpenClawMemoryFiles, recoverOpenClaw, rollbackCheckpoint, listCheckpoints, hasValidPairing, findIncompleteCheckpoint, resumeMigration, } from './migrate.js';
 import { EngramClient } from './EngramClient.js';
-import { openEngram } from './openEngram.js';
+import { openEngram, shellWord } from './openEngram.js';
 import { Principal } from '@icp-sdk/core/principal';
 // Simple colored output helpers
 const green = (s) => `\x1b[32m${s}\x1b[0m`;
@@ -254,7 +254,7 @@ async function runResumeMigration(clientOptions) {
         fail(`Resume failed: ${err.message}`);
         process.exit(1);
     }
-    console.log(`\nTo undo: ${bold('npx @engramx/client rollback')}`);
+    console.log(`\nTo undo: ${bold(`${NPX_CLIENT} rollback`)}`);
 }
 // ── Help text ───────────────────────────────────────────────────
 // ⟨2026-10-03⟩ Every usage line names the version this help was built with (version.ts): the
@@ -271,10 +271,8 @@ ${bold('Usage:')}
   ${NPX_CLIENT} migrate --engram <id> [options]
   ${NPX_CLIENT} rollback [checkpoint-id]
   ${NPX_CLIENT} git-setup <remote-url>
-  ${NPX_CLIENT} git-log [file]
-  ${NPX_CLIENT} git-diff [ref] [--file <path>]
-  ${NPX_CLIENT} git-revert <ref> --engram <id> [--file <path>]
-  ${NPX_CLIENT} read <path> --engram <id> [--raw]
+  ${NPX_CLIENT} git-revert <ref> [--file <path>]
+  ${NPX_CLIENT} read <path> --engram <id>
 
 ${bold('Commands:')}
   pair        Pair this agent with an engram: a fresh key for it, enrolled under your lasting key
@@ -283,10 +281,9 @@ ${bold('Commands:')}
   migrate     Migrate local memory to engram (or recover with --recover)
   rollback    Restore files from a checkpoint
   git-setup   Initialize git versioning for the memory directory
-  git-log     Show commit history for the memory repo
-  git-diff    Show changes since a commit (or working tree diff)
-  git-revert  Revert memory to a previous commit and sync to canister
-  read        Read a memory file (use --raw to see raw stored bytes)
+  git-revert  Revert the local memory repo to a previous commit; prints the owner kit's command
+              that puts the reverted files back on the engram (an owner's act)
+  read        Read one memory file and print its text
 
 ${bold('Options (pair):')}
   --engram <id>          Engram canister ID (required)
@@ -299,7 +296,10 @@ ${bold('Options (pair):')}
                          (default: ~/.engramx/root.key; created on first use, never overwritten)
   --git-remote <url>     Enable git versioning and set remote
   --force                Overwrite an existing key for this engram (never the lasting key)
-  --yes, -y              Auto-confirm all prompts (non-interactive mode)
+  --migrate              Also move this machine's OpenClaw memory files into the engram: each
+                         is uploaded, then deleted here (undo with rollback). Without it, pair
+                         moves nothing and says what it found
+  --yes, -y              Auto-confirm all prompts (non-interactive mode); never adds --migrate
 
 ${bold('Options (open-engram):')}
   --engram <id>          The engram this agent works in, which opens the new one (required)
@@ -317,19 +317,13 @@ ${bold('Options (open-engram):')}
 ${bold('Options (migrate):')}
   --engram <id>      Engram canister ID (required)
   --recover          Recovery mode: download memory from engram to local
-  --resume           Resume an incomplete migration
   --dry-run          Show what would be migrated without uploading
   --host <url>       ICP host (default: https://ic0.app)
   --key-path <path>  The key for this engram (default: ~/.engramx/session.key)
 
 ${bold('Options (git-revert):')}
-  --engram <id>      Engram canister ID (required)
   --file <path>      Revert a single file instead of the entire memory dir
-  --host <url>       ICP host (default: https://ic0.app)
-  --key-path <path>  The key for this engram (default: ~/.engramx/session.key)
-
-${bold('Options (read):')}
-  --raw              Show raw stored bytes as hex instead of decoded text
+  (An incomplete migration is offered for resumption by a plain \`migrate\`.)
 
   --help             Show this help message
 `);
@@ -342,16 +336,15 @@ async function main() {
             target: { type: 'string' },
             install: { type: 'boolean', default: false },
             recover: { type: 'boolean', default: false },
-            resume: { type: 'boolean', default: false },
             'dry-run': { type: 'boolean', default: false },
             host: { type: 'string' },
             'key-path': { type: 'string' },
             'root-key': { type: 'string' },
             'git-remote': { type: 'string' },
             force: { type: 'boolean', default: false },
+            migrate: { type: 'boolean', default: false },
             yes: { type: 'boolean', short: 'y', default: false },
             file: { type: 'string' },
-            raw: { type: 'boolean', default: false },
             help: { type: 'boolean', default: false },
         },
     });
@@ -370,11 +363,23 @@ async function main() {
             process.exit(1);
         }
     }
-    // ── read command (debug) ─────────────────────────────────────
+    // ⟨2026-10-13, the bloat audit⟩ `read <path> [--raw]`, `git-log` and `git-diff` were removed: no doc
+    // described them and no test ran them, in this repo or the platform. `read --raw` also printed
+    // "[object Object]" for every refusal (`fail(result.Err)` on the six-arm error variant) and a
+    // "stored as plaintext" line that was false on an encrypted engram. `git log` and `git diff` in
+    // the memory directory do what the other two did.
+    // ── read command ──────────────────────────────────────────────
+    // ⟨RESTORED 2026-10-14⟩ engramx f1907dc3 removed `read` with git-log and git-diff as "undocumented,
+    // untested" (the bloat audit, the owner's answers of 2026-10-13). The premise was wrong for `read`:
+    // printUsage listed it, downstream end-to-end checks of the packaged CLI read through it, and the
+    // staging test plan sent to a design partner tells their agents to read back with it — those checks
+    // failed on exactly the four read cases. `read` comes back; its `--raw` option does not (it printed the raw stored bytes through the
+    // private actor, was in no doc and no test — the dead part the audit meant). git-log and git-diff stay
+    // removed. WHAT WOULD MAKE THIS WRONG: a later ruling that agents read only through the SDK or MCP.
     if (command === 'read') {
         const filePath = positionals[1];
         if (!filePath) {
-            fail('Usage: npx @engramx/client read <path> --engram <id> [--raw]');
+            fail(`Usage: ${NPX_CLIENT} read <path> --engram <id>`);
             process.exit(1);
         }
         if (!values.engram) {
@@ -385,25 +390,8 @@ async function main() {
         const host = values.host || 'https://ic0.app';
         const client = new EngramClient({ canisterId: values.engram, sessionKeyPath: keyPath, host });
         try {
-            if (values.raw) {
-                console.warn('WARNING: --raw shows the raw stored bytes (content is stored as plaintext).');
-                // Show raw stored bytes as hex (no decode)
-                const result = await client.actor.readMemory(filePath);
-                if ('Err' in result) {
-                    fail(result.Err);
-                    process.exit(1);
-                }
-                const raw = result.Ok;
-                const bytes = new Uint8Array(raw.content);
-                console.log(`Path: ${raw.path}`);
-                console.log(`Version: ${raw.version}`);
-                console.log(`Size: ${bytes.length} bytes (raw stored, plaintext)`);
-                console.log(`Hex: ${Buffer.from(bytes).toString('hex').slice(0, 200)}...`);
-            }
-            else {
-                const file = await client.readMemory(filePath);
-                console.log(file.content);
-            }
+            const file = await client.readMemory(filePath);
+            console.log(file.content);
         }
         catch (err) {
             fail(`Read failed: ${err.message}`);
@@ -474,79 +462,19 @@ async function main() {
         }
         return;
     }
-    // ── git-log command ──────────────────────────────────────────
-    if (command === 'git-log') {
-        const memoryDir = getMemoryDir();
-        if (!isGitRepo(memoryDir)) {
-            fail('Git versioning not set up. Run: npx @engramx/client git-setup <url>');
-            process.exit(1);
-        }
-        const filePath = positionals[1] || values.file;
-        const args = ['log', '--oneline', '--no-decorate', '-30'];
-        if (filePath)
-            args.push('--', filePath);
-        try {
-            const output = execFileSync('git', args, { cwd: memoryDir, stdio: 'pipe' }).toString().trim();
-            if (output) {
-                console.log(output);
-            }
-            else {
-                info('No commits yet.');
-            }
-        }
-        catch {
-            info('No commits yet.');
-        }
-        return;
-    }
-    // ── git-diff command ────────────────────────────────────────
-    if (command === 'git-diff') {
-        const memoryDir = getMemoryDir();
-        if (!isGitRepo(memoryDir)) {
-            fail('Git versioning not set up. Run: npx @engramx/client git-setup <url>');
-            process.exit(1);
-        }
-        const ref = positionals[1];
-        const filePath = values.file;
-        const args = ['diff'];
-        if (ref)
-            args.push(ref);
-        if (filePath)
-            args.push('--', filePath);
-        try {
-            const output = execFileSync('git', args, { cwd: memoryDir, stdio: 'pipe' }).toString().trim();
-            if (output) {
-                console.log(output);
-            }
-            else {
-                info('No changes.');
-            }
-        }
-        catch (err) {
-            fail(`git diff failed: ${err.message}`);
-            process.exit(1);
-        }
-        return;
-    }
     // ── git-revert command ──────────────────────────────────────
     if (command === 'git-revert') {
         const ref = positionals[1];
         if (!ref) {
-            fail('Usage: npx @engramx/client git-revert <commit-or-ref> --engram <id> [--file <path>]');
-            process.exit(1);
-        }
-        if (!values.engram) {
-            fail('Missing --engram <canister-id> (needed to sync reverted files to canister)');
+            fail(`Usage: ${NPX_CLIENT} git-revert <commit-or-ref> [--file <path>]`);
             process.exit(1);
         }
         const memoryDir = getMemoryDir();
         if (!isGitRepo(memoryDir)) {
-            fail('Git versioning not set up. Run: npx @engramx/client git-setup <url>');
+            fail(`Git versioning not set up. Run: ${NPX_CLIENT} git-setup <url>`);
             process.exit(1);
         }
         const filePath = values.file;
-        const keyPath = values['key-path'] || '~/.engramx/session.key';
-        const host = values.host || 'https://ic0.app';
         // 1. Git checkout to revert files
         step(`Reverting to ${ref}${filePath ? ` (file: ${filePath})` : ''}...`);
         try {
@@ -589,62 +517,13 @@ async function main() {
                 warn(`Git commit failed: ${msg}`);
             }
         }
-        // 3. Restore reverted files on the canister
-        step('Restoring reverted files on engram canister...');
-        const client = new EngramClient({ canisterId: values.engram, sessionKeyPath: keyPath, host });
-        let syncCount = 0;
-        let syncErrors = 0;
-        async function syncDir(dir) {
-            if (!fs.existsSync(dir))
-                return;
-            const entries = fs.readdirSync(dir, { withFileTypes: true });
-            for (const entry of entries) {
-                const fullPath = `${dir}/${entry.name}`;
-                if (entry.isDirectory()) {
-                    if (entry.name === '.git')
-                        continue;
-                    await syncDir(fullPath);
-                }
-                else if (entry.isFile() && entry.name.endsWith('.md')) {
-                    const relativePath = path.relative(memoryDir, fullPath);
-                    if (relativePath.startsWith('..'))
-                        continue; // skip files outside memoryDir
-                    const content = fs.readFileSync(fullPath, 'utf-8');
-                    try {
-                        // A revert must RESTORE the canister file to the reverted content —
-                        // appendMemory would stack the old content on top of the current, leaving
-                        // a doubled, self-contradictory memory. writeMemory overwrites; it is
-                        // OWNER-gated on the canister, so it respects the append-only invariant for
-                        // agents — a non-owner key is rejected here (a loud, honest failure)
-                        // rather than silently corrupting.
-                        // NOTE: writes plaintext bytes; a memory stored in framed-encrypted (Private)
-                        // mode would need an encryption-aware owner restore in the SDK core (the
-                        // deeper fix — out of scope for the CLI).
-                        const ciphertext = new TextEncoder().encode(content);
-                        const result = await client.actor.writeMemory(relativePath, ciphertext);
-                        if ('Err' in result)
-                            throw new Error(result.Err);
-                        ok(`  ${relativePath}`);
-                        syncCount++;
-                    }
-                    catch (err) {
-                        fail(`  ${relativePath}: ${err.message}`);
-                        syncErrors++;
-                    }
-                }
-            }
-        }
-        await syncDir(memoryDir);
-        if (syncErrors > 0) {
-            fail(`Restored ${syncCount} file(s) on engram, ${syncErrors} failed`);
-            info("Restore requires owner credentials — an agent's key cannot overwrite canister memory.");
-        }
-        else if (syncCount > 0) {
-            ok(`Restored ${syncCount} file${syncCount === 1 ? '' : 's'} on engram`);
-        }
-        else {
-            info('No .md files to restore');
-        }
+        // 3. ⟨2026-10-13, the owner's 5A⟩ The canister step MOVED to the owner kit. It wrote each file
+        //    back with writeMemory, which REPLACES a file and is owner-only on the engram — so from an
+        //    agent's key it always failed (and printed "[object Object]" for the refusal), and it wrote
+        //    plaintext into an engram that encrypts memory. An owner's act belongs in the owner kit:
+        //    `@engramx/owner --restore` (its owned.ts · restoreMemory says what changed on the way).
+        info('The files are reverted here. To put them back on the engram, its owner runs:');
+        console.log(`  ${bold(`npx @engramx/owner@${VERSION} --restore ${shellWord(memoryDir)}${filePath ? ` --file ${shellWord(filePath)}` : ''} --key-file <the owner's key file>`)}`);
         // 4. Push to remote if configured
         try {
             execFileSync('git', ['push'], { cwd: memoryDir, stdio: 'pipe' });
@@ -660,7 +539,7 @@ async function main() {
     if (command === 'git-setup') {
         const remoteUrl = positionals[1];
         if (!remoteUrl) {
-            fail('Missing remote URL. Usage: npx @engramx/client git-setup <remote-url>');
+            fail(`Missing remote URL. Usage: ${NPX_CLIENT} git-setup <remote-url>`);
             process.exit(1);
         }
         step('Setting up git versioning...');
@@ -700,11 +579,6 @@ async function main() {
                 process.exit(1);
             }
         }
-        // Flag validation
-        if (values.resume && values['dry-run']) {
-            fail('Cannot combine --resume with --dry-run');
-            process.exit(1);
-        }
         if (values.recover) {
             // ── Recovery mode ───────────────────────────────────────
             step('Recovering from engram...');
@@ -731,15 +605,12 @@ async function main() {
                 fail(`Recovery failed: ${err.message}`);
                 process.exit(1);
             }
-            console.log(`\nTo undo: ${bold('npx @engramx/client rollback')}`);
+            console.log(`\nTo undo: ${bold(`${NPX_CLIENT} rollback`)}`);
             console.log(`Restart OpenClaw \u2014 memory files will sync automatically.`);
             return;
         }
-        if (values.resume) {
-            // ── Resume mode ─────────────────────────────────────────
-            await runResumeMigration(clientOptions);
-            return;
-        }
+        // ⟨2026-10-13, the bloat audit⟩ The `--resume` flag went: it was a second door to what a plain
+        // `migrate` already does just below — find the incomplete checkpoint and offer to resume it.
         // ── Default: check for incomplete checkpoint ────────────
         const incomplete = findIncompleteCheckpoint();
         if (incomplete && !values['dry-run']) {
@@ -774,7 +645,7 @@ async function main() {
             process.exit(1);
         }
         if (!values['dry-run']) {
-            console.log(`\nTo undo: ${bold('npx @engramx/client rollback')}`);
+            console.log(`\nTo undo: ${bold(`${NPX_CLIENT} rollback`)}`);
         }
         return;
     }
@@ -814,7 +685,7 @@ async function main() {
     }
     // Error if --recover is passed to pair (moved to migrate)
     if (values.recover) {
-        fail('The --recover flag has moved to the migrate command. Use: npx @engramx/client migrate --engram <id> --recover');
+        fail(`The --recover flag has moved to the migrate command. Use: ${NPX_CLIENT} migrate --engram <id> --recover`);
         process.exit(1);
     }
     const inviteCode = positionals[1];
@@ -837,6 +708,23 @@ async function main() {
     info(`Key path:    ${keyPath}`);
     info(`Lasting key: ${rootKeyPath}`);
     info(`Target:      ${target}`);
+    // Before anything changes: an EngramX plugin for OpenClaw already on this machine must be this
+    // release's, or pair stops here.
+    // ⟨ADDED 2026-10-13, the second review of the owner's "fix the pairing migration"⟩ WHY. Step 2 left
+    // an older plugin in place and printed "Installed EngramX plugin for OpenClaw" over it, and one from
+    // 0.16.0-rc.11 or earlier deletes the local memory files the engram does not list when OpenClaw
+    // next starts — the files Step 4 now leaves where they are. Stopping HERE, before the invite is
+    // used, is what lets the same pair command run again once the plugin is upgraded; refused at Step
+    // 2 the pairing would already be done and the invite spent. openclaw-setup.ts ·
+    // outdatedOpenClawPlugins says the rest. Held by test/pair-migrate.test.ts.
+    if (target === 'openclaw') {
+        const outdated = outdatedOpenClawPlugins();
+        if (outdated.length > 0) {
+            fail(new OpenClawPluginOutdatedError(outdated).message);
+            info('Nothing was changed, and the invite is not used yet: upgrade the plugin, then run this pair command again.');
+            process.exit(1);
+        }
+    }
     // Step 1: Pair (keep the lasting key, generate a fresh key for this engram, enrol it, pairAgent)
     step('Generating a key for this engram, enrolling it under your lasting key, pairing...');
     info(`This will write: ${keyPath} (and ${rootKeyPath} if you have no lasting key yet)`);
@@ -897,14 +785,31 @@ async function main() {
                     sessionKeyPath: keyPath,
                     host: values.host,
                 });
-                ok(`Installed EngramX plugin for OpenClaw`);
+                // ⟨CHANGED 2026-10-13, the second review⟩ This printed "Installed EngramX plugin for OpenClaw"
+                // whatever setupOpenClaw reported — over a plugin already there at any version, and over no
+                // install at all when OpenClaw's gateway was not running. It now says what happened.
+                const where = setupResult.pluginNote ?? '';
+                switch (setupResult.pluginMethod) {
+                    case 'cli':
+                        ok(`Installed ${OPENCLAW_PLUGIN} through OpenClaw's plugin installer`);
+                        break;
+                    case 'manual-npm':
+                        ok(`Installed ${OPENCLAW_PLUGIN} with npm ${dim(`\u2192 ${where}`)}`);
+                        break;
+                    case 'current':
+                        ok(`The EngramX plugin is already ${OPENCLAW_PLUGIN} ${dim(`\u2192 ${where}`)}`);
+                        break;
+                    default:
+                        warn(`Did not install the EngramX plugin for OpenClaw: ${where}.`);
+                        info(`Install it with: openclaw plugins install ${OPENCLAW_PLUGIN}`);
+                }
                 ok(`Updated ${dim(setupResult.configPath)}`);
             }
             catch (err) {
                 if (err instanceof OpenClawNotFoundError) {
                     fail(err.message);
                     console.log(`\n${dim('Manual setup:')}`);
-                    console.log(dim('  1. npm install @engramx/openclaw'));
+                    console.log(dim(`  1. npm install @engramx/openclaw@${VERSION}`));
                     console.log(dim('  2. Add to openclaw.json: { "plugins": { "slots": { "memory": "memory-engramx" } } }'));
                 }
                 else {
@@ -1077,11 +982,35 @@ async function main() {
         }
         catch (err) {
             fail(`Git setup failed: ${err.message}`);
-            info('You can set this up manually later. See: npx @engramx/client git-setup <url>');
+            info(`You can set this up manually later. See: ${NPX_CLIENT} git-setup <url>`);
         }
     }
-    // Step 4: Migration
-    {
+    // Step 4: Migration — only when asked (--migrate).
+    // ⟨CHANGED 2026-10-13, the owner's ruling of that day: "fix the pairing migration"⟩ WHY. This step
+    // ran on every pair, for every --target (claude too), and under --yes it confirmed itself: it moved
+    // every OpenClaw memory file under OPENCLAW_CONFIG_DIR or ~/.openclaw into the engram and deleted
+    // the local originals (migrate.ts · migrateFiles → fs.unlinkSync, after a checkpoint copy). Pairing
+    // an agent for Claude on a machine that had once run OpenClaw moved that machine's OpenClaw memory
+    // into an engram nobody asked to fill, and an environment variable pointed elsewhere was the only
+    // guard. Now pairing migrates only on the explicit --migrate; --yes answers the prompts of what was
+    // asked and never asks for the migration itself. Without --migrate, pairing reads the file list the
+    // migration would start from, moves nothing, and prints one line: what it found and the command
+    // that moves it. The `migrate` command is unchanged. Held by test/pair-migrate.test.ts.
+    // WHAT WOULD MAKE THIS WRONG: a caller that relies on pair to move the files. None in this
+    // repository does: integrations/openclaw never runs pair, and its README gives `migrate` as the
+    // second of two commands.
+    // ⟨CORRECTED 2026-10-13, later, on review⟩ One did, without calling it: the OpenClaw plugin's sync
+    // deleted every local memory file the engram did not list, before pushing it, so the files in its
+    // memory folder that this step no longer moves were lost at OpenClaw's next start, unless more than
+    // five, and more than half the folder, would go. The plugin now deletes only what the engram had
+    // (integrations/openclaw/index.ts · knownPathsFile).
+    // ⟨CORRECTED 2026-10-13, the second review⟩ "The plugin now deletes only what the engram had" held
+    // for the plugin released with this kit, not for the one already installed: Step 2 left an older
+    // plugin in place and said it had installed one, so on such a machine the files this step leaves
+    // were still lost at OpenClaw's next start. pair now stops before pairing when the installed plugin
+    // is a different version (the check above Step 1), and the plugin's delete step reads the engram's
+    // whole listing (index.ts · readEngramListing).
+    if (values.migrate) {
         const clientOptions = {
             canisterId: values.engram,
             sessionKeyPath: keyPath,
@@ -1099,20 +1028,41 @@ async function main() {
                 fail(`Migration failed: ${err.message}`);
                 process.exit(1);
             }
-            console.log(`\nTo undo: ${bold('npx @engramx/client rollback')}`);
+            console.log(`\nTo undo: ${bold(`${NPX_CLIENT} rollback`)}`);
             if (gitRemoteUrl) {
                 console.log(`Memory changes will be auto-committed and pushed to GitHub.`);
             }
             else {
-                info('Tip: Add git versioning with npx @engramx/client git-setup <url>');
+                info(`Tip: Add git versioning with ${NPX_CLIENT} git-setup <url>`);
             }
         }
         else {
-            info(`Run 'npx @engramx/client migrate --engram ${values.engram}' to migrate later.`);
+            info(`Run '${NPX_CLIENT} migrate --engram ${values.engram}' to migrate later.`);
+        }
+    }
+    else {
+        let found;
+        try {
+            found = findOpenClawMemoryFiles();
+        }
+        catch (err) {
+            warn(`Could not look for OpenClaw memory files (none were moved): ${err.message}`);
+        }
+        const n = found?.files.length ?? 0;
+        if (found && n > 0) {
+            info(`Found ${n} OpenClaw memory file${n === 1 ? '' : 's'} in ${found.openclawDir} and left ${n === 1 ? 'it' : 'them'} there. ` +
+                `To move ${n === 1 ? 'it' : 'them'} into this engram (each is uploaded, then deleted here): ` +
+                `${NPX_CLIENT} migrate --engram ${values.engram}`);
         }
     }
 }
-main().catch((err) => {
+/**
+ * The run this module starts when it is loaded — the command line's whole life.
+ * ⟨2026-10-13⟩ Exported so a test can load the CLI with stubbed network modules and wait for the
+ * command to END (test/pair-migrate.test.ts); before, a test could only wait one tick, which is
+ * enough for --help and not for pair.
+ */
+export const finished = main().catch((err) => {
     fail(`Fatal: ${err.message}`);
     process.exit(1);
 });