@engramx/client 0.16.0-rc.2 → 0.16.0-rc.21

package/dist/cli.js

@@ -3,14 +3,17 @@ import { parseArgs } from 'node:util';
 import * as readline from 'readline';
 import * as fs from 'fs';
 import { pair, PairError } from './pair.js';
-import { NPX_CLIENT, pairCommand } from './version.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 { checkEvidence } from './evidence.js';
+import { IC_MAINNET_ROOT_KEY_HEX } from './certifiedAudit.js';
+import { fetchSealedRows } from './publicRecord.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,12 +257,15 @@ 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
 // owner's ruling of that date pins the pairing command to the build's version, and the lines below it
 // run the same package, so they carry the same prefix.
+// ⟨2026-10-06⟩ The owner kit's line under open-engram is pinned the same way: the packages share one
+// version, and a bare `npx @engramx/owner` during a release candidate's soak installs 0.15.0, whose
+// `--connect` still spawns a first engram for a key that owns nothing.
 function printUsage() {
     console.log(`
 ${bold('Usage:')}
@@ -268,10 +274,9 @@ ${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>
+  ${NPX_CLIENT} verify <bundle.json> [--offline] [--host <url>] [--ic-root-key <hex>]
 
 ${bold('Commands:')}
   pair        Pair this agent with an engram: a fresh key for it, enrolled under your lasting key
@@ -280,10 +285,12 @@ ${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
+  verify      Check an evidence bundle against the network's signature: the bytes, the record
+              entry, the walk to a certified head, and the time the subnet signed it. Needs no
+              key, no account and no owner
 
 ${bold('Options (pair):')}
   --engram <id>          Engram canister ID (required)
@@ -296,7 +303,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)
@@ -308,25 +318,28 @@ ${bold('Options (open-engram):')}
 
   What is attached to open it is the agent's from the moment it exists (approving is giving).
   Afterwards the owner kit acts as its owner with the same file:
-    npx @engramx/owner --connect --key-file <the lasting key's file> --registry <id>
+    npx @engramx/owner@${VERSION} --connect --key-file <the lasting key's file> --registry <id>
   (open-engram prints that line with both filled in.)
 
 ${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 (verify):')}
+  --offline              Use only the rows in the bundle; never fetch from the network
+  --host <url>           Where to fetch missing hash-only rows from (default: https://icp-api.io)
+  --ic-root-key <hex>    Check against this root key instead of the pinned IC mainnet key (a local
+                         replica's, for testing only; the result says so)
+
+  A bundle is what EngramClient.captureEvidence() writes after a write (format engramx-evidence/1).
+  Exit status 0: every link held. 1: a link broke, and the line marked ✗ names it. 2: no bundle.
+
 ${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
 `);
@@ -339,16 +352,17 @@ 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 },
+            offline: { type: 'boolean', default: false },
+            'ic-root-key': { type: 'string' },
             help: { type: 'boolean', default: false },
         },
     });
@@ -367,11 +381,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) {
@@ -382,25 +408,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}`);
@@ -408,6 +417,58 @@ async function main() {
         }
         return;
     }
+    // ── verify command ────────────────────────────────────────────
+    // ⟨2026-10-15, the owner's ruling 6B of 2026-10-14⟩ The public check. It runs on a machine with no
+    // identity: the bundle carries the bytes, the entry, the certificate and (usually) the hash-only
+    // rows; any rows it lacks are fetched anonymously from the canister's public record read. The
+    // certificate is checked at any age against the PINNED mainnet root key — never one fetched from
+    // the network it is checking. evidence.ts names each link; this prints them.
+    if (command === 'verify') {
+        const file = positionals[1];
+        if (!file) {
+            fail(`Usage: ${NPX_CLIENT} verify <bundle.json> [--offline] [--host <url>]`);
+            process.exit(2);
+        }
+        let bundle;
+        try {
+            bundle = JSON.parse(fs.readFileSync(file, 'utf8'));
+        }
+        catch (err) {
+            fail(`Cannot read the bundle ${file}: ${err.message}`);
+            process.exit(2);
+        }
+        let rootKey;
+        if (values['ic-root-key']) {
+            const h = values['ic-root-key'].trim().toLowerCase();
+            if (!/^([0-9a-f]{2})+$/.test(h)) {
+                fail('--ic-root-key must be hex');
+                process.exit(2);
+            }
+            rootKey = Uint8Array.from(h.match(/../g), (b) => parseInt(b, 16));
+            if (h !== IC_MAINNET_ROOT_KEY_HEX) {
+                warn('Checking against a root key that is NOT the IC mainnet key — nothing below is a proof to anyone else.');
+            }
+        }
+        const host = values.host || 'https://icp-api.io';
+        const result = await checkEvidence(bundle, {
+            rootKey,
+            fetchRows: values.offline
+                ? undefined
+                : (fromId) => fetchSealedRows(host, bundle.canisterId, fromId, rootKey),
+        });
+        for (const l of result.links)
+            (l.ok ? ok : fail)(`${l.link}: ${l.detail}`);
+        if (!result.ok) {
+            fail(`NOT VERIFIED — ${result.why}`);
+            process.exit(1);
+        }
+        console.log();
+        ok(bold('VERIFIED'));
+        info(`entry ${bundle.entry.id} was in ${bundle.canisterId}'s record when the subnet signed at`);
+        console.log(`  ${bold(new Date(Number(result.signedTimeNs / 1000000n)).toISOString())}  (${result.signedTimeNs} ns)`);
+        info(`distance walked: ${result.distance} entr${result.distance === 1n ? 'y' : 'ies'}; the certified head covers ${result.entriesCovered} entries`);
+        return;
+    }
     // ── rollback command ──────────────────────────────────────────
     if (command === 'rollback') {
         const checkpoints = listCheckpoints();
@@ -471,79 +532,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 {
@@ -586,62 +587,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' });
@@ -657,7 +609,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...');
@@ -697,11 +649,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...');
@@ -728,15 +675,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']) {
@@ -771,7 +715,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;
     }
@@ -780,7 +724,9 @@ async function main() {
     // drive it with a stub engram; this block only parses and passes the terminal in.
     if (command === 'open-engram') {
         if (!values.engram) {
-            fail('Missing --engram <canister-id>. Usage: npx @engramx/client open-engram --engram <id>');
+            // ⟨2026-10-06⟩ Pinned like the help's usage lines: a bare npx during a release candidate's
+            // soak installs 0.15.0, which has no open-engram.
+            fail(`Missing --engram <canister-id>. Usage: ${NPX_CLIENT} open-engram --engram <id>`);
             process.exit(1);
         }
         const result = await openEngram({
@@ -809,7 +755,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];
@@ -832,6 +778,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)`);
@@ -892,14 +855,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 {
@@ -1072,11 +1052,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,
@@ -1094,20 +1098,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);
 });