@myclaw163/clawclaw-cli 0.6.54

package/src/commands/hub.test.ts

@@ -0,0 +1,96 @@
+// src/commands/hub.test.ts
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { mkdtempSync, rmSync } from 'fs';
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { createHubCommand } from './hub.js';
+import type { ResourceListResult, ResourceDetail } from '../lib/hub-client.js';
+
+let ws: string;
+let logs: string[];
+let errs: string[];
+beforeEach(() => {
+  ws = mkdtempSync(join(tmpdir(), 'ccl-cmd-'));
+  process.env.CLAWCLAW_WORKSPACE_DIR = ws;
+  logs = []; errs = [];
+  vi.spyOn(console, 'log').mockImplementation((...a) => { logs.push(a.join(' ')); });
+  vi.spyOn(console, 'error').mockImplementation((...a) => { errs.push(a.join(' ')); });
+});
+afterEach(() => {
+  delete process.env.CLAWCLAW_WORKSPACE_DIR;
+  vi.restoreAllMocks();
+  rmSync(ws, { recursive: true, force: true });
+});
+
+function fakeClient(over: any = {}) {
+  return {
+    list: vi.fn(async (): Promise<ResourceListResult> => ({
+      items: [{
+        id: 'ab12', type: 'strategy', title: 'Aggressive Kill', description: '贴脸抢刀',
+        creator: 'alice', creatorType: 'clawkey', creatorDisplayName: 'Alice', creatorAvatarUrl: null,
+        fileName: 'kill.ts', stats: { downloadCount: 42, starCount: 7, commentCount: 0 },
+        downloadUrl: '/dl', likedByMe: false, createdAt: '', updatedAt: '',
+      }], total: 1,
+      pagination: { mode: 'page', page: 1, limit: 20, hasMore: false },
+    })),
+    getResource: vi.fn(async (): Promise<ResourceDetail> => ({
+      id: 'ab12', type: 'strategy', title: 'Aggressive Kill', description: '贴脸抢刀',
+      creator: 'alice', creatorType: 'clawkey', creatorDisplayName: 'Alice', creatorAvatarUrl: null,
+      fileName: 'kill.ts', stats: { downloadCount: 42, starCount: 7, commentCount: 0 },
+      downloadUrl: '/dl', likedByMe: false, createdAt: '', updatedAt: '',
+      artifact: { fileName: 'kill.ts', downloadUrl: '/dl' },
+    })),
+    downloadArtifact: vi.fn(async () => Buffer.from('export const strategy = {};')),
+    ...over,
+  };
+}
+
+async function run(client: any, argv: string[]) {
+  const cmd = createHubCommand({ clientFactory: () => client as any });
+  await cmd.parseAsync(['node', 'ccl', ...argv]);
+}
+
+describe('hub search', () => {
+  it('emits JSON with --json', async () => {
+    const c = fakeClient();
+    await run(c, ['search', '抢刀', '--type', 'strategy', '--json']);
+    expect(c.list).toHaveBeenCalledWith(expect.objectContaining({ q: '抢刀', type: 'strategy' }));
+    const out = JSON.parse(logs.join('\n'));
+    expect(out.items[0].id).toBe('ab12');
+    expect(out.items[0].type).toBe('strategy');
+  });
+});
+
+describe('hub info', () => {
+  it('prints the copy-paste install command', async () => {
+    await run(fakeClient(), ['info', 'strategy/ab12']);
+    expect(logs.join('\n')).toContain('ccl hub install strategy/ab12');
+  });
+});
+
+describe('hub install', () => {
+  it('downloads + places the package and prints the path', async () => {
+    await run(fakeClient(), ['install', 'strategy/ab12']);
+    const out = logs.join('\n');
+    expect(out).toMatch(/strategies[\\/]aggressive-kill__ab12\.ts/);
+  });
+  it('emits JSON with --json', async () => {
+    await run(fakeClient(), ['install', 'strategy/ab12', '--json']);
+    const out = JSON.parse(logs.join('\n'));
+    expect(out.ref).toBe('strategy/ab12');
+    expect(out.installedPath).toMatch(/strategies[\\/]aggressive-kill__ab12\.ts/);
+  });
+});
+
+describe('hub installed / uninstall', () => {
+  it('lists then removes an installed package', async () => {
+    await run(fakeClient(), ['install', 'strategy/ab12']);
+    logs.length = 0;
+    await run(fakeClient(), ['installed', '--json']);
+    const listed = JSON.parse(logs.join('\n'));
+    expect(listed.items.map((e: any) => e.type + '/' + e.id)).toContain('strategy/ab12');
+    logs.length = 0;
+    await run(fakeClient(), ['uninstall', 'strategy/ab12']);
+    expect(logs.join('\n')).toMatch(/Removed strategy\/ab12/);
+  });
+});

package/src/commands/hub.ts

@@ -0,0 +1,234 @@
+// src/commands/hub.ts
+import { Command } from 'commander';
+import { spawnSync } from 'child_process';
+import { existsSync, readdirSync, statSync } from 'fs';
+import { join } from 'path';
+import { createRequire } from 'module';
+import { ApiError, formatApiError } from '../lib/http-transport.js';
+import { HubClient, parseResourceRef } from '../lib/hub-client.js';
+import type { ListOptions } from '../lib/hub-client.js';
+import { installResource, uninstallResource, listInstalled, readLockfile } from '../lib/hub-install.js';
+import { getWorkspaceDir } from '../lib/init-command.js';
+
+const require = createRequire(import.meta.url);
+
+export interface HubCommandDeps {
+  clientFactory?: () => HubClient;
+}
+
+function getClient(deps: HubCommandDeps): HubClient {
+  return (deps.clientFactory ?? (() => HubClient.fromAuth()))();
+}
+
+function fail(payload: Record<string, unknown>): never {
+  console.error(JSON.stringify(payload, null, 2));
+  process.exit(1);
+}
+
+function handleError(err: unknown): never {
+  if (err instanceof ApiError) {
+    fail({ error: 'api_error', status: err.status, message: formatApiError(err) });
+  }
+  fail({ error: 'hub_error', message: (err as any)?.message ?? String(err) });
+}
+
+/** Find the real skill root: if SKILL.md is not at root but a single subdirectory contains it, use that. */
+function findSkillRoot(absPath: string): string {
+  if (existsSync(join(absPath, 'SKILL.md'))) return absPath;
+  let entries: string[];
+  try { entries = readdirSync(absPath); } catch { return absPath; }
+  const dirs = entries.filter(e => {
+    try { return statSync(join(absPath, e)).isDirectory() && !e.startsWith('.'); } catch { return false; }
+  });
+  if (dirs.length === 1 && existsSync(join(absPath, dirs[0], 'SKILL.md'))) {
+    return join(absPath, dirs[0]);
+  }
+  return absPath;
+}
+
+/** Best-effort skill registration via the skills CLI. Returns true on success; false means manual ccl skill install is needed. */
+async function registerSkill(absPath: string): Promise<boolean> {
+  try {
+    const root = findSkillRoot(absPath);
+    // Guard against a hub skill overwriting the built-in clawclaw skill.
+    const { readSkillName } = await import('./skill.js');
+    if (readSkillName(root) === 'clawclaw') {
+      console.error('warning: this skill is named "clawclaw" which would overwrite the built-in clawclaw skill; install manually if intended.');
+      return false;
+    }
+    const bin = require.resolve('skills/bin/cli.mjs');
+    const result = spawnSync(process.execPath, [bin, 'add', root, '-y', '-g'], {
+      stdio: 'pipe',
+      timeout: 30_000,
+    });
+    // Forward CLI output to stderr so --json stdout stays clean.
+    if (result.stdout?.length) process.stderr.write(result.stdout);
+    if (result.stderr?.length) process.stderr.write(result.stderr);
+    return result.status === 0 && !result.error;
+  } catch {
+    return false;
+  }
+}
+
+export function createHubCommand(deps: HubCommandDeps = {}): Command {
+  const hub = new Command('hub').description('Browse and install ClawClaw strategies and skills from clawclawhub');
+
+  // search
+  hub.command('search [query]')
+    .description('Search/browse the hub (no query = top packages)')
+    .option('--type <type>', 'skill | strategy')
+    .option('--sort <sort>', 'latest | downloads | stars', 'latest')
+    .option('--limit <n>', 'max results', '20')
+    .option('--page <n>', 'page number', '1')
+    .option('--json', 'machine-readable output')
+    .action(async (query: string | undefined, opts: any) => {
+      try {
+        const search: ListOptions = {
+          q: query,
+          type: opts.type,
+          sort: opts.sort,
+          limit: Number(opts.limit),
+          page: Number(opts.page),
+        };
+        const res = await getClient(deps).list(search);
+        if (opts.json) {
+          console.log(JSON.stringify(res, null, 2));
+          return;
+        }
+        if (res.items.length === 0) {
+          console.log('No packages found.');
+          return;
+        }
+        for (const p of res.items) {
+          const isStrategy = p.type === 'strategy';
+          const code = isStrategy ? ' ⚠code' : '';
+          console.log(p.type + '/' + p.id + '  [' + p.type + code + ']  ↓' + p.stats.downloadCount + ' ★' + p.stats.starCount);
+          console.log('    ' + p.title + ' — ' + p.description);
+          if (p.creatorDisplayName) console.log('    by ' + p.creatorDisplayName + ' (' + p.creator + ')');
+        }
+        console.log('\n' + res.items.length + ' of ' + res.total + '. Install: ccl hub install <type>/<id>');
+      } catch (err) { handleError(err); }
+    });
+
+  // info
+  hub.command('info <type/id>')
+    .description('Show package detail and the install command')
+    .option('--json', 'machine-readable output')
+    .action(async (ref: string, opts: any) => {
+      try {
+        const { type, id } = parseResourceRef(ref);
+        const d = await getClient(deps).getResource(type, id);
+        if (opts.json) {
+          console.log(JSON.stringify(d, null, 2));
+          return;
+        }
+        const codeStr = d.type === 'strategy' ? ' ⚠code' : '';
+        console.log(d.type + '/' + d.id + '  [' + d.type + codeStr + ']  ↓' + d.stats.downloadCount + ' ★' + d.stats.starCount);
+        console.log(d.title);
+        console.log(d.description);
+        if (d.creatorDisplayName) console.log('by ' + d.creatorDisplayName + ' (' + d.creator + ')');
+        if (d.fileName) console.log('file: ' + d.fileName);
+        if (d.type === 'strategy') console.log('⚠ contains executable code — source: ' + (d.creatorDisplayName || d.creator));
+        console.log('\nInstall:  ccl hub install ' + d.type + '/' + d.id);
+      } catch (err) { handleError(err); }
+    });
+
+  // install
+  hub.command('install <type/id>')
+    .description('Download and install a package (strategy → strategies/, skill → skills/)')
+    .option('--force', 'overwrite an existing untracked file/dir')
+    .option('--json', 'machine-readable output')
+    .action(async (raw: string, opts: any) => {
+      try {
+        const { type, id } = parseResourceRef(raw);
+        const client = getClient(deps);
+        const detail = await client.getResource(type, id);
+        const artifact = await client.downloadArtifact(type, id);
+        const res = installResource(detail, artifact, { force: opts.force });
+        // Reload strategy loader so the new file is picked up immediately,
+        // then extract the exported id from source to tell the user what to run.
+        let strategyId: string | undefined;
+        if (res.type === 'strategy') {
+          const { reload } = await import('../strategies/loader.js');
+          await reload();
+          const m = artifact.toString('utf8').match(/id\s*:\s*['"]([^'"]+)['"]/);
+          strategyId = m ? m[1] : undefined;
+        }
+
+        // For skills: auto-register with the agent via `ccl skill install`.
+        let skillRegistered = false;
+        if (res.type === 'skill') {
+          skillRegistered = await registerSkill(res.installedPath);
+        }
+
+        if (opts.json) {
+          console.log(JSON.stringify({ ...res, strategyId: strategyId ?? null, skillRegistered }, null, 2));
+          return;
+        }
+        console.log('Installed ' + res.ref + '  "' + res.title + '"  [' + res.type + ']');
+        console.log('  → ' + res.installedPath);
+        if (strategyId) {
+          console.log('Run with: ccl strategy ' + strategyId);
+        } else if (res.type === 'strategy') {
+          console.log('Run with: ccl strategy <id>  (see: ccl strategy --list)');
+        }
+        if (skillRegistered) {
+          console.log('Skill registered with agent.');
+        } else if (res.type === 'skill') {
+          console.log('Register manually: ccl skill install ' + res.installedPath);
+        }
+      } catch (err) { handleError(err); }
+    });
+
+  // uninstall
+  hub.command('uninstall <type/id>')
+    .description('Remove a hub-installed package')
+    .action(async (ref: string) => {
+      try {
+        // For skills: auto-unregister from the agent before deleting files.
+        const { type } = parseResourceRef(ref);
+        if (type === 'skill') {
+          const lock = readLockfile();
+          const entry = lock[ref];
+          if (entry) {
+            const { readSkillName } = await import('./skill.js');
+            const skillDir = join(getWorkspaceDir(), entry.path);
+            const name = readSkillName(skillDir);
+            if (name) {
+              const bin = require.resolve('skills/bin/cli.mjs');
+              const r2 = spawnSync(process.execPath, [bin, 'remove', name, '-y', '-g'], { timeout: 30_000 });
+              if (r2.status !== 0 || r2.error) {
+                console.error('warning: skills remove failed (status=' + (r2.status ?? 'error') + '); files will still be deleted');
+              }
+            }
+          }
+        }
+
+        const r = uninstallResource(ref);
+        if (!r.removed) { console.log(ref + ' is not installed.'); return; }
+        // Reload the strategy map so the removed strategy disappears immediately.
+        if (r.path && (r.path.startsWith('strategies/') || r.path.startsWith('strategies\\'))) {
+          const { reload } = await import('../strategies/loader.js');
+          await reload();
+        }
+        console.log('Removed ' + ref + '\n  → ' + r.path);
+      } catch (err) { handleError(err); }
+    });
+
+  // installed
+  hub.command('installed')
+    .description('List locally installed hub packages')
+    .option('--type <type>', 'filter: skill | strategy')
+    .option('--json', 'machine-readable output')
+    .action(async (opts: any) => {
+      try {
+        let items = listInstalled();
+        if (opts.type) items = items.filter(e => e.type === opts.type);
+        if (opts.json) { console.log(JSON.stringify({ items }, null, 2)); return; }
+        if (items.length === 0) { console.log('No hub packages installed' + (opts.type ? ' for type "' + opts.type + '"' : '') + '.'); return; }
+        for (const e of items) console.log(e.type + '/' + e.id + '  "' + e.title + '"  [' + e.type + ']  ' + e.path);
+      } catch (err) { handleError(err); }
+    });
+
+  return hub;
+}

package/src/commands/knowledge.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it } from 'vitest';
+import { normalizeLegacySuspectVerdict, normalizePlayerMark } from './knowledge.js';
+
+describe('knowledge player marks', () => {
+  it('accepts only the three canonical mark names', () => {
+    expect(normalizePlayerMark('suspect')).toBe('suspect');
+    expect(normalizePlayerMark('hostile')).toBe('hostile');
+    expect(normalizePlayerMark('trusted')).toBe('trusted');
+    expect(normalizePlayerMark('impostor')).toBeNull();
+    expect(normalizePlayerMark('avoid')).toBeNull();
+  });
+
+  it('keeps old suspect command verdicts as compatibility aliases', () => {
+    expect(normalizeLegacySuspectVerdict()).toBe('suspect');
+    expect(normalizeLegacySuspectVerdict('impostor')).toBe('hostile');
+    expect(normalizeLegacySuspectVerdict('cleared')).toBe('trusted');
+    expect(normalizeLegacySuspectVerdict('typo')).toBeNull();
+  });
+});

package/src/commands/knowledge.ts

@@ -0,0 +1,168 @@
+import { Command } from 'commander';
+import { KnowledgeStore, type KnowledgeSetInput, type PlayerMark } from '../lib/knowledge-store.js';
+
+const PLAYER_MARKS = new Set<PlayerMark>(['suspect', 'hostile', 'trusted']);
+const LEGACY_MARK_TAGS = ['avoid', 'kill_if_armed', 'cleared', 'protected', 'do_not_kill'];
+
+const LEGACY_SUSPECT_VERDICTS: Record<string, PlayerMark> = {
+  suspect: 'suspect', suspicious: 'suspect', avoid: 'suspect',
+  hostile: 'hostile', impostor: 'hostile', bad: 'hostile',
+  trusted: 'trusted', cleared: 'trusted', clear: 'trusted', innocent: 'trusted', safe: 'trusted',
+};
+
+export function normalizePlayerMark(mark?: string): PlayerMark | null {
+  const normalized = mark?.trim().toLowerCase() as PlayerMark | undefined;
+  return normalized && PLAYER_MARKS.has(normalized) ? normalized : null;
+}
+
+export function normalizeLegacySuspectVerdict(verdict?: string): PlayerMark | null {
+  return LEGACY_SUSPECT_VERDICTS[(verdict ?? 'suspect').trim().toLowerCase()] ?? null;
+}
+
+/** "true"/"false"/数字 自动转类型，其余按字符串。 */
+function coerceValue(raw: string | undefined): unknown {
+  if (raw == null) return true;
+  if (raw === 'true') return true;
+  if (raw === 'false') return false;
+  if (raw !== '' && !Number.isNaN(Number(raw))) return Number(raw);
+  return raw;
+}
+
+function collectTag(value: string, prev: string[]): string[] {
+  return [...prev, value];
+}
+
+function print(data: unknown): void {
+  console.log(JSON.stringify(data, null, 2));
+}
+
+function fail(error: string, message: string): never {
+  console.error(JSON.stringify({ error, message }, null, 2));
+  process.exit(1);
+}
+
+function setPlayerMark(store: KnowledgeStore, player: string, mark: PlayerMark, opts: { confidence?: number; note?: string }) {
+  const removeTags = [
+    ...[...PLAYER_MARKS].filter(candidate => candidate !== mark),
+    ...LEGACY_MARK_TAGS,
+  ];
+  return store.set({
+    type: 'player',
+    selector: player,
+    tags: [mark],
+    removeTags,
+    confidence: opts.confidence,
+    note: opts.note,
+  });
+}
+
+export function createKnowledgeCommand(): Command {
+  const cmd = new Command('knowledge')
+    .alias('kn')
+    .description('Per-game structured knowledge that a running strategy can query (no restart needed)');
+
+  cmd
+    .command('set [type] [selector] [key] [value]')
+    .description('Advanced: upsert arbitrary facts/tags. Use `knowledge mark` for player strategy behavior.')
+    .option('--tag <tag>', 'Custom tag, repeatable', collectTag, [])
+    .option('--confidence <n>', 'Confidence 0..1', parseFloat)
+    .option('--note <text>', 'Free-text reason')
+    .option('--json <json>', 'Provide the whole input object as JSON instead of positional args')
+    .action((type: string | undefined, selector: string | undefined, key: string | undefined, value: string | undefined, opts: {
+      tag: string[]; confidence?: number; note?: string; json?: string;
+    }) => {
+      try {
+        const store = KnowledgeStore.forActiveAccount();
+        let input: KnowledgeSetInput;
+        if (opts.json) {
+          input = JSON.parse(opts.json) as KnowledgeSetInput;
+        } else {
+          if (!type || !selector) {
+            fail('missing_args', 'Usage: ccl knowledge set <type> <selector> [key] [value] [--tag ...]  —  or:  ccl knowledge set --json "{...}"');
+          }
+          input = {
+            type,
+            selector,
+            key,
+            value: key != null ? coerceValue(value) : undefined,
+            tags: opts.tag.length > 0 ? opts.tag : undefined,
+            confidence: opts.confidence,
+            note: opts.note,
+          };
+        }
+        const entry = store.set(input);
+        print({ ok: true, gameId: store.gameId ?? null, subject: entry });
+      } catch (e) {
+        fail('knowledge_set_failed', e instanceof Error ? e.message : String(e));
+      }
+    });
+
+  cmd
+    .command('mark <player> <mark>')
+    .description('Set the strategy mark for a player: suspect | hostile | trusted')
+    .option('--confidence <n>', 'Confidence 0..1', parseFloat)
+    .option('--note <text>', 'Free-text reason')
+    .action((player: string, rawMark: string, opts: { confidence?: number; note?: string }) => {
+      const mark = normalizePlayerMark(rawMark);
+      if (!mark) fail('invalid_mark', `Unknown mark '${rawMark}'. Use: suspect | hostile | trusted.`);
+      try {
+        const store = KnowledgeStore.forActiveAccount();
+        const entry = setPlayerMark(store, player, mark, opts);
+        print({ ok: true, gameId: store.gameId ?? null, mark, subject: entry });
+      } catch (e) {
+        fail('knowledge_mark_failed', e instanceof Error ? e.message : String(e));
+      }
+    });
+
+  cmd
+    .command('suspect <player> [verdict]')
+    .description('Legacy alias for `knowledge mark`: suspect(default) | impostor/hostile | cleared/trusted')
+    .option('--confidence <n>', 'Confidence 0..1', parseFloat)
+    .option('--note <text>', 'Free-text reason')
+    .action((player: string, verdict: string | undefined, opts: { confidence?: number; note?: string }) => {
+      const mark = normalizeLegacySuspectVerdict(verdict);
+      if (!mark) fail('invalid_verdict', `Unknown verdict '${verdict}'. Prefer: ccl knowledge mark <player> suspect|hostile|trusted.`);
+      try {
+        const store = KnowledgeStore.forActiveAccount();
+        const entry = setPlayerMark(store, player, mark, opts);
+        print({ ok: true, gameId: store.gameId ?? null, mark, subject: entry, deprecated_command: 'suspect' });
+      } catch (e) {
+        fail('knowledge_set_failed', e instanceof Error ? e.message : String(e));
+      }
+    });
+
+  cmd
+    .command('get [type] [selector]')
+    .description('Read knowledge: all, all of a type, or one subject')
+    .action((type: string | undefined, selector: string | undefined) => {
+      const store = KnowledgeStore.forActiveAccount();
+      const file = store.list();
+      if (type && selector) {
+        print({ gameId: file.gameId ?? null, subject: file.subjects[`${type}:${selector}`] ?? null });
+        return;
+      }
+      const subjects = Object.values(file.subjects).filter((s) => !type || s.type === type);
+      print({ gameId: file.gameId ?? null, count: subjects.length, subjects });
+    });
+
+  cmd
+    .command('del <type> <selector> [key]')
+    .description('Delete a subject, or just one fact (key) / tag (--tag)')
+    .option('--tag <tag>', 'Delete only this tag')
+    .action((type: string, selector: string, key: string | undefined, opts: { tag?: string }) => {
+      const store = KnowledgeStore.forActiveAccount();
+      const removed = store.del(type, selector, { key, tag: opts.tag });
+      print({ ok: removed, gameId: store.gameId ?? null });
+    });
+
+  cmd
+    .command('clear')
+    .description('Clear all knowledge for the current game')
+    .action(() => {
+      const store = KnowledgeStore.forActiveAccount();
+      store.clear();
+      print({ ok: true, gameId: store.gameId ?? null });
+    });
+
+  return cmd;
+}

package/src/commands/load.test.ts

@@ -0,0 +1,51 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../lib/load-context.js', () => ({
+  loadContext: vi.fn(() => ({ persona: { exists: true }, memory: { exists: false } })),
+}));
+
+vi.mock('../runtime/auto-upgrade.js', () => ({
+  runAutoUpgradeOnLoad: vi.fn(),
+}));
+
+import { runAutoUpgradeOnLoad } from '../runtime/auto-upgrade.js';
+import { createLoadCommand } from './load.js';
+
+describe('load command', () => {
+  let logSpy: ReturnType<typeof vi.spyOn>;
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    vi.mocked(runAutoUpgradeOnLoad).mockClear();
+    logSpy = vi.spyOn(console, 'log').mockImplementation(() => {});
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+
+  afterEach(() => {
+    logSpy.mockRestore();
+    errorSpy.mockRestore();
+  });
+
+  it('runs auto-upgrade check before printing JSON load context', async () => {
+    const cmd = createLoadCommand();
+    await cmd.parseAsync(['node', 'load'], { from: 'node' });
+
+    expect(runAutoUpgradeOnLoad).toHaveBeenCalledOnce();
+    expect(logSpy).toHaveBeenCalledOnce();
+    expect(JSON.parse(String(logSpy.mock.calls[0][0]))).toEqual({
+      persona: { exists: true },
+      memory: { exists: false },
+    });
+  });
+
+  it('routes auto-upgrade notifications to stderr', async () => {
+    vi.mocked(runAutoUpgradeOnLoad).mockImplementation(({ notify }: any) => {
+      notify('[clawclaw-cli] auto-upgrade installed 0.6.39');
+    });
+
+    const cmd = createLoadCommand();
+    await cmd.parseAsync(['node', 'load'], { from: 'node' });
+
+    expect(errorSpy).toHaveBeenCalledWith('[clawclaw-cli] auto-upgrade installed 0.6.39');
+  });
+});

package/src/commands/load.ts

@@ -0,0 +1,13 @@
+import { Command } from 'commander';
+import { loadContext } from '../lib/load-context.js';
+import { runAutoUpgradeOnLoad } from '../runtime/auto-upgrade.js';
+
+export function createLoadCommand(): Command {
+  return new Command('load')
+    .description('Read active account persona and memory files')
+    .action(() => {
+      runAutoUpgradeOnLoad({ notify: (message) => console.error(message) });
+      const snapshot = loadContext();
+      console.log(JSON.stringify(snapshot, null, 2));
+    });
+}