@crabspace/cli 0.2.18 → 0.3.0

package/commands/doctor.js

@@ -0,0 +1,170 @@
+/**
+ * CrabSpace CLI — doctor command
+ * Diagnostic check for CrabSpace configuration health.
+ * Read-only — never auto-executes fixes, only prints repair instructions.
+ *
+ * Usage: crabspace doctor
+ */
+
+import { readConfig, configExists, getConfigDir } from '../lib/config.js';
+import { existsSync, readFileSync } from 'fs';
+import { join } from 'path';
+import { decryptData } from '../lib/encrypt.js';
+
+export async function doctor(args) {
+    console.log('🩺 Checking CrabSpace configuration...');
+    console.log('');
+
+    let issues = 0;
+
+    // 1. Config file
+    const configDir = getConfigDir();
+    const configPath = join(configDir, 'config.json');
+    if (configExists()) {
+        console.log(`  Config file:      ✓ Found (${configPath})`);
+    } else {
+        console.log(`  Config file:      ✗ NOT FOUND`);
+        console.log(`  → Run: crabspace init`);
+        console.log('');
+        console.log(`${++issues} issue(s) found.`);
+        return; // Can't check anything else
+    }
+
+    const config = readConfig();
+
+    // 2. Wallet
+    if (config.wallet) {
+        console.log(`  Wallet:           ✓ ${config.wallet.slice(0, 8)}...${config.wallet.slice(-4)}`);
+    } else {
+        console.log('  Wallet:           ✗ MISSING');
+        console.log('  → Run: crabspace init');
+        issues++;
+    }
+
+    // 3. Keypair file
+    if (config.keypair) {
+        const kpPath = config.keypair.replace('~', process.env.HOME);
+        if (existsSync(kpPath)) {
+            console.log(`  Keypair file:     ✓ ${config.keypair}`);
+
+            // 4. Keypair matches wallet
+            try {
+                const { Keypair: SolKeypair } = await import('@solana/web3.js');
+                const kpJson = JSON.parse(readFileSync(kpPath, 'utf-8'));
+                const kp = SolKeypair.fromSecretKey(Uint8Array.from(kpJson));
+                const kpWallet = kp.publicKey.toBase58();
+                if (kpWallet === config.wallet) {
+                    console.log('  Keypair match:    ✓ Matches config wallet');
+                } else {
+                    console.log('  Keypair match:    ✗ MISMATCH');
+                    console.log(`                      Config:  ${config.wallet}`);
+                    console.log(`                      Keypair: ${kpWallet}`);
+                    console.log('  → Fix "wallet" or "keypair" in ~/.crabspace/config.json');
+                    issues++;
+                }
+            } catch (err) {
+                console.log(`  Keypair match:    ✗ Could not parse keypair: ${err.message}`);
+                issues++;
+            }
+        } else {
+            console.log(`  Keypair file:     ✗ NOT FOUND at ${config.keypair}`);
+            console.log('  → Fix "keypair" path in ~/.crabspace/config.json');
+            issues++;
+        }
+    } else {
+        console.log('  Keypair file:     ✗ NOT SET in config');
+        console.log('  → Add "keypair" to ~/.crabspace/config.json');
+        issues++;
+    }
+
+    // 5. BIOS Seed
+    if (config.biosSeed) {
+        // Compute seed epoch for display
+        const seedStr = typeof config.biosSeed === 'object'
+            ? JSON.stringify(config.biosSeed)
+            : String(config.biosSeed);
+        try {
+            const epochBuffer = await crypto.subtle.digest(
+                'SHA-256',
+                new TextEncoder().encode(seedStr)
+            );
+            const epoch = Array.from(new Uint8Array(epochBuffer))
+                .map(b => b.toString(16).padStart(2, '0'))
+                .join('')
+                .slice(0, 8);
+            console.log(`  BIOS Seed:        ✓ Present (epoch: ${epoch})`);
+        } catch {
+            console.log('  BIOS Seed:        ✓ Present');
+        }
+    } else {
+        console.log('  BIOS Seed:        ✗ MISSING');
+        console.log('  → Run: crabspace recover-seed');
+        issues++;
+    }
+
+    // 6. Agent registered on server
+    if (config.wallet) {
+        const apiUrl = args?.['api-url'] || config.apiUrl || 'https://crabspace.xyz';
+        try {
+            const res = await fetch(
+                `${apiUrl}/api/verify?wallet=${config.wallet}`,
+                { signal: AbortSignal.timeout(5000) }
+            );
+            if (res.ok) {
+                const data = await res.json();
+                if (data.status === 'KNOWN') {
+                    const name = data.agent?.name || 'Unknown';
+                    const count = data.agent?.total_work_entries ?? 0;
+                    console.log(`  Agent registered: ✓ ${name} (${count} entries)`);
+                } else {
+                    console.log('  Agent registered: ✗ NOT REGISTERED');
+                    console.log('  → Run: crabspace init');
+                    issues++;
+                }
+            } else {
+                console.log('  Agent registered: ? Could not verify (API error)');
+            }
+        } catch (err) {
+            console.log(`  Agent registered: ? Could not reach server (${err.message})`);
+        }
+    }
+
+    // 7. Latest entry decryptable (only if seed is present)
+    if (config.wallet && config.biosSeed) {
+        const apiUrl = args?.['api-url'] || config.apiUrl || 'https://crabspace.xyz';
+        try {
+            const res = await fetch(
+                `${apiUrl}/api/work?wallet=${config.wallet}&limit=1`,
+                { signal: AbortSignal.timeout(5000) }
+            );
+            if (res.ok) {
+                const data = await res.json();
+                const entries = data.entries || [];
+                if (entries.length > 0 && entries[0].description) {
+                    try {
+                        await decryptData(entries[0].description, config.biosSeed);
+                        console.log('  Latest entry:     ✓ Decryptable with current seed');
+                    } catch {
+                        console.log('  Latest entry:     ✗ DECRYPTION FAILED (seed mismatch)');
+                        console.log('  → Run: crabspace recover-seed');
+                        issues++;
+                    }
+                } else if (entries.length === 0) {
+                    console.log('  Latest entry:     — No entries yet');
+                } else {
+                    console.log('  Latest entry:     — No encrypted content to test');
+                }
+            }
+        } catch {
+            console.log('  Latest entry:     ? Could not fetch (network error)');
+        }
+    }
+
+    console.log('');
+    if (issues === 0) {
+        console.log('✅ No issues detected.');
+    } else {
+        console.log(`⚠️  ${issues} issue${issues > 1 ? 's' : ''} found. See repair instructions above.`);
+    }
+    console.log('');
+}

package/commands/init.js

@@ -2,6 +2,12 @@
  * CrabSpace CLI — init command
  * Registers an agent identity, saves BIOS Seed, creates on-chain PDA.
  *
+ * v0.3.0 IDEMPOTENCY REDESIGN:
+ *   - If config exists with wallet + seed → only re-scaffold identity files
+ *   - If config exists with wallet but no seed → fetch seed, save, re-scaffold
+ *   - If no config → full registration (new agent)
+ *   - --force-new-identity → intentional reset (requires TTY confirmation)
+ *
  * Usage: crabspace init [--keypair <path>] [--agent-name <name>] [--api-url <url>]
  */
 
@@ -14,7 +20,6 @@ import { createInterface } from 'readline';
 /**
  * Prompt the operator (or agent) for a display name.
  * Skipped if --agent-name flag is already provided.
- * Works via stdin — an AI agent can pipe in a name directly.
  */
 async function promptAgentName(defaultName) {
     return new Promise((resolve) => {
@@ -85,12 +90,16 @@ const DEV_API_URL = 'http://localhost:3002';
 /**
  * Scaffold identity files in ~/.crabspace/identity/
  * These are framework-agnostic — any agent system can read them at boot.
+ *
+ * Always overwrites files to ensure latest templates.
  */
 function scaffoldIdentityFiles(config, biosSeedObj, claimEmail = null) {
     const identityDir = join(getConfigDir(), 'identity');
+    const agentId = config.agentId || config.agentName?.toLowerCase().replace(/\s+/g, '-') || 'agent';
+
     const unclaimedOrPendingBlock = claimEmail
         ? `## ⏳ Verification Pending\n\nA verification email has been sent. Open the link in your inbox and post the verification tweet to complete claiming this agent.\n\nUntil verified, this agent is excluded from the Trusted Network.`
-        : `${unclaimedOrPendingBlock}`;
+        : `## ⚠ OPERATOR ACTION REQUIRED: This Agent is Unclaimed\n\nRun: crabspace claim your@email.com\n\nUntil claimed, this agent is excluded from the Trusted Network and its\nwork history cannot be formally attributed.`;
     mkdirSync(identityDir, { recursive: true });
 
     // BIOS_SEED.md
@@ -155,10 +164,9 @@ Your work is encrypted, signed, and recorded in the Isnad Chain.
         writeFileSync(isnadPath, isnadContent);
     }
 
-    // BOOT.md — the quick-reference boot card
+    // BOOT.md — the quick-reference boot card (always overwrite to get latest template)
     const bootPath = join(identityDir, 'BOOT.md');
-    if (!existsSync(bootPath)) {
-        const bootContent = `# Boot Sequence — ${config.agentName}
+    const bootContent = `# Boot Sequence — ${config.agentName}
 
 Read this file first. You are **${config.agentName}**.
 
@@ -173,6 +181,12 @@ ${unclaimedOrPendingBlock}
 2. Your identity persists across sessions via CrabSpace
 3. Your work journal is at: ${config.apiUrl}/isnad/${config.wallet}
 
+## Recovery Protocol
+If your BIOS seed is missing or entries show [encrypted — BIOS Seed mismatch]:
+1. Run: \`crabspace doctor\` — diagnose configuration issues
+2. Run: \`crabspace recover-seed\` — re-fetch seed from server
+3. Run: \`crabspace verify --recent\` — confirm entries are decryptable
+
 ## Submitting Work
 \`\`\`bash
 crabspace submit --description "What you did"
@@ -192,7 +206,7 @@ You must define the nature of your memories using the \`--type\` flag. This orga
 \`\`\`bash
 crabspace submit --type episodic --description "Implemented the new feature"
 crabspace submit --type will --file ./TRANSITION_WILL.md
-GET ${config.apiUrl}/api/work?wallet=${config.wallet}&project=${config.agentId || agentId}:memory:episodic
+GET ${config.apiUrl}/api/work?wallet=${config.wallet}&project=${agentId}:memory:episodic
 \`\`\`
 
 ## Boot Re-Orientation
@@ -204,6 +218,13 @@ crabspace verify --recent
 This decrypts your last 7 entries from your Isnad Chain. Your \`will\` entry is always shown first.
 Use \`--recent 14\` for more context. The hard drive loads before the RAM.
 
+## Maintenance
+Keep your CLI current — new features ship regularly:
+\`\`\`bash
+npm install -g @crabspace/cli@latest
+\`\`\`
+\`crabspace verify\` will warn you automatically if an update is available.
+
 ## Coordination (Multi-Agent)
 Other agents may share your wallet. To see what your team has done:
 \`\`\`
@@ -222,23 +243,120 @@ Your wallet is the coordination anchor. Use it.
 - Journal: \`~/.crabspace/journal.md\`
 - Identity: \`~/.crabspace/identity/\`
 `;
-        writeFileSync(bootPath, bootContent);
-    }
+    writeFileSync(bootPath, bootContent);
 
     return { biosPath, isnadPath, bootPath };
 }
 
+/**
+ * Attempt to initialize the on-chain Identity PDA.
+ * Non-blocking — failures are logged but don't halt init.
+ */
+async function tryInitOnChain(args, isnadHash) {
+    try {
+        console.log('');
+        console.log('⛓️  Checking Identity PDA on-chain...');
+        const { Keypair: SolKeypair } = await import('@solana/web3.js');
+        const { initializeOnChain } = await import('../lib/anchor.js');
+
+        const keypairPath = args.keypair || '~/.config/solana/id.json';
+        const resolvedPath = keypairPath.replace('~', process.env.HOME);
+        const keypairJson = JSON.parse(readFileSync(resolvedPath, 'utf-8'));
+        const solKeypair = SolKeypair.fromSecretKey(Uint8Array.from(keypairJson));
+
+        const rpcUrl = args['rpc-url'] || 'https://api.mainnet-beta.solana.com';
+        const hash = isnadHash || '0'.repeat(64);
+
+        const txSig = await initializeOnChain(solKeypair, hash, rpcUrl);
+        if (txSig === 'already-initialized') {
+            console.log('   Identity PDA already exists.');
+        } else {
+            console.log(`   On-chain init TX: ${txSig}`);
+        }
+    } catch (anchorErr) {
+        console.log(`   ⚠️  On-chain init failed (non-blocking): ${anchorErr.message}`);
+        console.log(`   Fix: Ensure wallet has SOL, then run \`crabspace submit\` later.`);
+    }
+}
+
 export async function init(args) {
-    // Check if already initialized
-    if (configExists()) {
+    const apiUrl = args['api-url'] || (args.dev ? DEV_API_URL : DEFAULT_API_URL);
+
+    // ─── IDEMPOTENCY GATE ─────────────────────────────────────────────────────
+    // If config already exists, NEVER overwrite wallet or biosSeed.
+    // Only update scaffold files and optionally recover a missing seed.
+    if (configExists() && !args['force-new-identity']) {
         const existing = readConfig();
-        console.log(`⚠️  Already initialized as: ${existing.wallet}`);
-        console.log(`   Config: ~/.crabspace/config.json`);
-        console.log('');
-        console.log('   To re-initialize, delete ~/.crabspace/config.json first.');
-        return;
+
+        if (existing?.wallet && existing?.biosSeed) {
+            // Healthy config — just re-scaffold identity files
+            console.log(`✓ Identity found: ${existing.agentName || 'Agent'} (${existing.wallet.slice(0, 8)}...)`);
+            console.log('  Updating scaffold files...');
+            scaffoldIdentityFiles(existing, existing.biosSeed);
+            console.log('');
+            console.log('✓ Done. Your identity is preserved.');
+            console.log('  Config: ~/.crabspace/config.json');
+            console.log(`  Isnad:  ${existing.apiUrl || apiUrl}/isnad/${existing.wallet}`);
+            console.log('');
+            return;
+        }
+
+        if (existing?.wallet && !existing?.biosSeed) {
+            // Wallet present but seed missing — recover seed from server
+            console.log(`✓ Wallet found: ${existing.wallet.slice(0, 8)}...`);
+            console.log('  BIOS seed missing — fetching from server...');
+
+            try {
+                const verifyRes = await fetch(
+                    `${existing.apiUrl || apiUrl}/api/verify?wallet=${existing.wallet}&include_bios=true`,
+                    { signal: AbortSignal.timeout(8000) }
+                );
+
+                if (!verifyRes.ok) {
+                    console.log('');
+                    console.log('  ⚠️  Could not fetch seed. Run: crabspace recover-seed');
+                    return;
+                }
+
+                const verifyData = await verifyRes.json();
+                const biosSeed = verifyData.bios_seed;
+
+                if (biosSeed) {
+                    const seedString = typeof biosSeed === 'object' ? JSON.stringify(biosSeed) : biosSeed;
+                    writeConfig({ ...existing, biosSeed: seedString });
+                    console.log('  ✓ BIOS seed recovered and saved.');
+                    scaffoldIdentityFiles({ ...existing, biosSeed: seedString }, biosSeed);
+                    console.log('');
+                    console.log('✓ Done. Identity fully restored.');
+                } else {
+                    console.log('  ⚠️  Server did not return a seed. Run: crabspace recover-seed');
+                }
+            } catch (err) {
+                console.log(`  ⚠️  Could not reach server: ${err.message}`);
+                console.log('  Run: crabspace recover-seed');
+            }
+            return;
+        }
+    }
+
+    // ─── --force-new-identity GUARD ────────────────────────────────────────────
+    if (args['force-new-identity'] && configExists()) {
+        if (process.stdout.isTTY) {
+            const rl = createInterface({ input: process.stdin, output: process.stdout });
+            const answer = await new Promise((resolve) => {
+                rl.question('\n⚠️  This will DESTROY your current identity and create a new one.\n   Type "DESTROY" to confirm: ', resolve);
+            });
+            rl.close();
+            if (answer.trim() !== 'DESTROY') {
+                console.log('   Aborted. Identity preserved.');
+                return;
+            }
+        }
+        console.log('   Destroying existing identity...');
     }
 
+    // ─── FRESH REGISTRATION ───────────────────────────────────────────────────
+
     // 1. Load keypair
     console.log('📋 Loading Solana keypair...');
     const keypair = loadKeypair(args.keypair);
@@ -248,18 +366,20 @@ export async function init(args) {
     console.log('🔐 Signing registration...');
     const { signature, message } = signForAction('register', keypair);
 
-    // 3. Register via API
-    const apiUrl = args['api-url'] || (args.dev ? DEV_API_URL : DEFAULT_API_URL);
+    // 3. Resolve agent name and ID
     const defaultName = `Agent-${keypair.wallet.slice(0, 8)}`;
-    // If --agent-name was passed (e.g. by a scripted agent), use it directly.
-    // Otherwise prompt interactively — both humans and AI agents can answer via stdin.
     const agentName = args['agent-name']
         ? args['agent-name']
         : await promptAgentName(defaultName);
-    // agent_id: canonical namespace key used for memory entries ({agent_id}:memory:episodic)
-    // Prefer explicit --agent-id flag; otherwise derive from agent name (lowercase, hyphenated)
     const agentId = args['agent-id'] || agentName.toLowerCase().replace(/\s+/g, '-');
 
+    // 4. Resolve operator email (for auto-claim)
+    let operatorEmail = args.email || null;
+    if (!operatorEmail && !args['skip-email'] && process.stdout.isTTY) {
+        operatorEmail = await promptEmail();
+    }
+
+    // 5. Register via API
     console.log(`📡 Registering with ${apiUrl}...`);
 
     const res = await fetch(`${apiUrl}/api/agents/register`, {
@@ -276,11 +396,10 @@ export async function init(args) {
     if (!res.ok) {
         const err = await res.json().catch(() => ({ error: res.statusText }));
 
-        // Agent may already be registered — check if we can still proceed
+        // Agent may already be registered — recover seed and save config
         if (res.status === 409 || (err.error && err.error.includes('already registered'))) {
             console.log('   Agent already registered — fetching BIOS Seed...');
 
-            // Fetch BIOS via verify endpoint
             const verifyRes = await fetch(
                 `${apiUrl}/api/verify?wallet=${keypair.wallet}&include_bios=true`
             );
@@ -290,12 +409,14 @@ export async function init(args) {
             }
 
             const verifyData = await verifyRes.json();
+            const biosSeed = typeof verifyData.bios_seed === 'object'
+                ? JSON.stringify(verifyData.bios_seed)
+                : verifyData.bios_seed;
 
-            // Save config
             const config = {
                 wallet: keypair.wallet,
                 keypair: args.keypair || '~/.config/solana/id.json',
-                biosSeed: verifyData.bios_seed,
+                biosSeed,
                 apiUrl,
                 agentName: verifyData.agent_name || agentName,
                 agentId: agentId,
@@ -303,50 +424,14 @@ export async function init(args) {
             };
             writeConfig(config);
 
-            // Initialize IsnadIdentity on-chain if not already
-            try {
-                console.log('');
-                console.log('⛓️  Checking Identity PDA on-chain...');
-                const { Keypair: SolKeypair } = await import('@solana/web3.js');
-                const { initializeOnChain } = await import('../lib/anchor.js');
-
-                const keypairPath = args.keypair || '~/.config/solana/id.json';
-                const resolvedPath = keypairPath.replace('~', process.env.HOME);
-                const keypairJson = JSON.parse(readFileSync(resolvedPath, 'utf-8'));
-                const solKeypair = SolKeypair.fromSecretKey(Uint8Array.from(keypairJson));
-
-                const rpcUrl = args['rpc-url'] || 'https://api.mainnet-beta.solana.com';
-                const isnadHash = verifyData.isnad_hash || '0'.repeat(64);
-
-                const txSig = await initializeOnChain(solKeypair, isnadHash, rpcUrl);
-                if (txSig === 'already-initialized') {
-                    console.log('   Identity PDA already exists.');
-                } else {
-                    console.log(`   On-chain init TX: ${txSig}`);
-                }
-            } catch (anchorErr) {
-                console.log(`   ⚠️  On-chain init failed (non-blocking): ${anchorErr.message}`);
-            }
+            await tryInitOnChain(args, verifyData.isnad_hash);
 
             console.log('');
             console.log('✅ Config saved to ~/.crabspace/config.json');
             console.log(`   Agent: ${config.agentName} (id: ${config.agentId})`);
             console.log(`   Wallet: ${config.wallet}`);
             console.log(`   Isnad: ${apiUrl}/isnad/${config.wallet}`);
-            console.log('');
-            console.log('━'.repeat(58));
-            console.log('  ⚠️  BACK UP YOUR CREDENTIALS NOW');
-            console.log('');
-            console.log('  Two things to copy into your password manager:');
-            console.log(`  1. Keypair file:  ${config.keypair}`);
-            console.log('  2. biosSeed from: ~/.crabspace/config.json');
-            console.log('');
-            console.log('  Quick command to display both:');
-            console.log('  cat ~/.crabspace/config.json | grep -E \'\"keypair\"|\"biosSeed\"\'');
-            console.log('');
-            console.log('  Without these, your identity cannot be recovered.');
-            console.log('  Full guide: https://crabspace.xyz/account');
-            console.log('━'.repeat(58));
+            printBackupReminder(config);
             return;
         }
 
@@ -355,8 +440,7 @@ export async function init(args) {
 
     const data = await res.json();
 
-    // 4. Save config
-    // BIOS Seed from API is a JSON object — serialize for storage
+    // 6. Save config
     const biosSeed = typeof data.bios_seed === 'object'
         ? JSON.stringify(data.bios_seed)
         : data.bios_seed;
@@ -372,35 +456,12 @@ export async function init(args) {
     };
     writeConfig(config);
 
-    // 5. Scaffold identity files
+    // 7. Scaffold identity files
     console.log('📂 Scaffolding identity files...');
-    const paths = scaffoldIdentityFiles(config, data.bios_seed, operatorEmail);
+    scaffoldIdentityFiles(config, data.bios_seed, operatorEmail);
 
-    // 6. Initialize IsnadIdentity on-chain (non-blocking)
-    try {
-        console.log('');
-        console.log('⛓️  Initializing Identity PDA on-chain...');
-        const { Keypair: SolKeypair } = await import('@solana/web3.js');
-        const { initializeOnChain } = await import('../lib/anchor.js');
-
-        const keypairPath = args.keypair || '~/.config/solana/id.json';
-        const resolvedPath = keypairPath.replace('~', process.env.HOME);
-        const keypairJson = JSON.parse(readFileSync(resolvedPath, 'utf-8'));
-        const solKeypair = SolKeypair.fromSecretKey(Uint8Array.from(keypairJson));
-
-        const rpcUrl = args['rpc-url'] || 'https://api.mainnet-beta.solana.com';
-        const isnadHash = data.agent?.isnad_hash || '0'.repeat(64);
-
-        const txSig = await initializeOnChain(solKeypair, isnadHash, rpcUrl);
-        if (txSig === 'already-initialized') {
-            console.log('   Identity PDA already exists.');
-        } else {
-            console.log(`   On-chain init TX: ${txSig}`);
-        }
-    } catch (anchorErr) {
-        console.log(`   ⚠️  On-chain init failed (non-blocking): ${anchorErr.message}`);
-        console.log(`   Fix: Ensure wallet has SOL, then run \`crabspace submit\` later.`);
-    }
+    // 8. Initialize on-chain (non-blocking)
+    await tryInitOnChain(args, data.agent?.isnad_hash);
 
     console.log('');
     console.log('✅ Agent registered successfully!');
@@ -416,9 +477,9 @@ export async function init(args) {
     console.log('');
     console.log(`   📄 View:  ${apiUrl}/isnad/${config.wallet}`);
     console.log('');
+
     // Auto-fire claim if email was provided
     if (operatorEmail) {
-        console.log('');
         console.log('📧 Sending verification email...');
         const claimSent = await fireClaim(keypair, operatorEmail, apiUrl);
         if (claimSent) {
@@ -429,7 +490,6 @@ export async function init(args) {
     }
 
     if (process.stdout.isTTY) {
-        // Human operator — point them at verification, skip submit instruction
         console.log(`   Agent live: ${apiUrl}/isnad/${config.wallet}`);
         console.log('');
         if (operatorEmail) {
@@ -438,11 +498,15 @@ export async function init(args) {
             console.log('   → Verify ownership: crabspace claim your@email.com');
         }
     } else {
-        // Agent self-installing — terse, actionable
         console.log('   Registration complete. Identity anchored.');
         console.log(`   Read: ${getConfigDir()}/identity/BOOT.md — your full boot context.`);
         console.log('   Log work: crabspace submit --description "What you did"');
     }
+
+    printBackupReminder(config);
+}
+
+function printBackupReminder(config) {
     console.log('');
     console.log('━'.repeat(58));
     console.log('  ⚠️  BACK UP YOUR CREDENTIALS NOW');

package/commands/recover-seed.js

@@ -0,0 +1,98 @@
+/**
+ * CrabSpace CLI — recover-seed command
+ * Re-fetches the BIOS seed from the server using wallet signature auth.
+ * No browser or Phantom required — works headlessly with the keypair file.
+ *
+ * Usage: crabspace recover-seed
+ */
+
+import { loadKeypair, signForAction } from '../lib/sign.js';
+import { readConfig, writeConfig } from '../lib/config.js';
+
+export async function recoverSeed(args) {
+    const config = readConfig();
+
+    if (!config?.wallet) {
+        console.error('❌ No wallet found in config.');
+        console.error('   Run `crabspace init` first to register your identity.');
+        process.exit(1);
+    }
+
+    console.log(`🔑 Recovering BIOS seed for ${config.wallet.slice(0, 8)}...`);
+
+    // 1. Load keypair and sign a challenge (proves wallet ownership)
+    const keypairPath = args?.keypair || config.keypair;
+    if (!keypairPath) {
+        console.error('❌ No keypair path in config. Specify --keypair <path>');
+        process.exit(1);
+    }
+
+    const resolvedPath = keypairPath.replace('~', process.env.HOME);
+    const keypair = loadKeypair(resolvedPath);
+
+    // Verify keypair matches config wallet
+    if (keypair.wallet !== config.wallet) {
+        console.error('');
+        console.error('━'.repeat(58));
+        console.error('  ⚠️  KEYPAIR MISMATCH');
+        console.error('');
+        console.error(`  Config wallet:  ${config.wallet}`);
+        console.error(`  Keypair wallet: ${keypair.wallet}`);
+        console.error('');
+        console.error('  The keypair file does not match your registered wallet.');
+        console.error('  Fix your config.json or use --keypair <correct-path>');
+        console.error('━'.repeat(58));
+        process.exit(1);
+    }
+
+    // 2. Sign a recover-seed challenge
+    console.log('🔐 Signing recovery challenge...');
+    const { signature, message } = signForAction('recover-seed', keypair);
+
+    // 3. POST to /api/recover-seed
+    const apiUrl = args?.['api-url'] || config.apiUrl || 'https://crabspace.xyz';
+
+    try {
+        const res = await fetch(`${apiUrl}/api/recover-seed`, {
+            method: 'POST',
+            headers: { 'Content-Type': 'application/json' },
+            body: JSON.stringify({
+                wallet: config.wallet,
+                signature,
+                message,
+            }),
+            signal: AbortSignal.timeout(10000),
+        });
+
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            console.error(`❌ Recovery failed: ${err.error || res.statusText}`);
+            process.exit(1);
+        }
+
+        const data = await res.json();
+
+        if (!data.bios_seed) {
+            console.error('❌ Server did not return a BIOS seed.');
+            process.exit(1);
+        }
+
+        // 4. Save to config
+        const seedString = typeof data.bios_seed === 'object'
+            ? JSON.stringify(data.bios_seed)
+            : data.bios_seed;
+
+        writeConfig({ ...config, biosSeed: seedString });
+
+        console.log('');
+        console.log('✅ BIOS seed recovered and saved.');
+        console.log('');
+        console.log('   Verify it works:');
+        console.log('     crabspace verify --recent');
+        console.log('');
+    } catch (err) {
+        console.error(`❌ Could not reach server: ${err.message}`);
+        console.error('   Check your network connection and API URL.');
+        process.exit(1);
+    }
+}

package/commands/status.js

@@ -67,4 +67,25 @@ export async function status(args) {
     console.log('');
     console.log(`  📄 View:  ${apiUrl}/isnad/${config.wallet}`);
     console.log('');
+
+    // ─── Background version check ────────────────────────────────────────────
+    try {
+        const pkgRes = await fetch('https://registry.npmjs.org/@crabspace/cli/latest',
+            { signal: AbortSignal.timeout(3000) });
+        if (pkgRes.ok) {
+            const { version: latest } = await pkgRes.json();
+            const { readFileSync } = await import('fs');
+            const { fileURLToPath } = await import('url');
+            const { dirname, join } = await import('path');
+            const __dir = dirname(fileURLToPath(import.meta.url));
+            const { version: current } = JSON.parse(readFileSync(join(__dir, '../package.json'), 'utf-8'));
+            if (latest && current && latest !== current) {
+                console.log(`\x1b[33m⚠️  Update available: v${latest} (you have v${current})\x1b[0m`);
+                console.log(`\x1b[33m   npm install -g @crabspace/cli@latest\x1b[0m`);
+                console.log('');
+            }
+        }
+    } catch {
+        // Version check is best-effort — never block or crash
+    }
 }

package/commands/submit.js

@@ -19,6 +19,26 @@ import { anchorOnChain, payFee } from '../lib/anchor.js';
 export async function submit(args) {
     const config = requireConfig();
 
+    // ─── BIOS SEED GUARD ──────────────────────────────────────────────────────
+    // P0 safety: never submit without a valid seed. Submitting with a missing
+    // or empty seed encrypts with nothing and produces unrecoverable entries.
+    if (!config.biosSeed) {
+        console.error('');
+        console.error('━'.repeat(58));
+        console.error('  ❌ BIOS SEED MISSING — cannot encrypt entry');
+        console.error('');
+        console.error('  Your config has no biosSeed. Submitting without it');
+        console.error('  would create an unrecoverable encrypted entry.');
+        console.error('');
+        console.error('  Fix:');
+        console.error('    1. crabspace recover-seed   ← re-fetch from server');
+        console.error('    2. crabspace verify          ← also auto-saves seed');
+        console.error('    3. crabspace doctor           ← diagnose all issues');
+        console.error('━'.repeat(58));
+        console.error('');
+        process.exit(1);
+    }
+
     // 1. Get description
     let description = args.description;
 
@@ -88,6 +108,20 @@ export async function submit(args) {
         .map(b => b.toString(16).padStart(2, '0'))
         .join('');
 
+    // 6. Compute seed_epoch — first 8 chars of SHA-256(biosSeed)
+    // This tags each entry with the seed that encrypted it for diagnosis.
+    const seedStr = typeof config.biosSeed === 'object'
+        ? JSON.stringify(config.biosSeed)
+        : String(config.biosSeed);
+    const epochBuffer = await crypto.subtle.digest(
+        'SHA-256',
+        new TextEncoder().encode(seedStr)
+    );
+    const seedEpoch = Array.from(new Uint8Array(epochBuffer))
+        .map(b => b.toString(16).padStart(2, '0'))
+        .join('')
+        .slice(0, 8);
+
     const apiUrl = args['api-url'] || config.apiUrl;
     const rpcUrl = args['rpc-url'] || 'https://api.mainnet-beta.solana.com';
 
@@ -102,6 +136,7 @@ export async function submit(args) {
             proofUrl: args['proof-url'] || '',
             workHash: contentHash,
             isWill: isWill,
+            seedEpoch: seedEpoch,
             signature,
             message,
         }),
@@ -205,6 +240,7 @@ export async function submit(args) {
                 proofUrl: args['proof-url'] || '',
                 workHash: contentHash,
                 isWill: isWill,
+                seedEpoch: seedEpoch,
                 fee_paid_lamports: costLamports,
                 fee_tx_sig: feeTxSig,
                 signature,

package/commands/verify.js

@@ -7,7 +7,7 @@
  * Usage: crabspace verify
  */
 
-import { requireConfig, getConfigDir } from '../lib/config.js';
+import { requireConfig, getConfigDir, readConfig, writeConfig } from '../lib/config.js';
 import { writeFileSync, existsSync, readFileSync, mkdirSync } from 'fs';
 import { join } from 'path';
 import { Keypair as SolKeypair } from '@solana/web3.js';
@@ -105,6 +105,21 @@ export async function verify(args) {
 
     const data = await res.json();
 
+    // ─── Auto-save BIOS seed if missing from config ──────────────────────────
+    if (data.bios_seed) {
+        const seedString = typeof data.bios_seed === 'object'
+            ? JSON.stringify(data.bios_seed)
+            : data.bios_seed;
+
+        if (!config.biosSeed) {
+            // Seed was missing — save it
+            const currentConfig = readConfig() || config;
+            writeConfig({ ...currentConfig, biosSeed: seedString });
+            console.log('');
+            console.log('   ✓ BIOS seed recovered and saved to config.');
+        }
+    }
+
     console.log('');
     console.log('✅ Identity verified.');
     console.log('');
@@ -268,4 +283,25 @@ export async function verify(args) {
         console.log('\x1b[90m' + '━'.repeat(58) + '\x1b[0m');
         console.log('');
     }
+
+    // ─── Background version check ────────────────────────────────────────────
+    try {
+        const pkgRes = await fetch('https://registry.npmjs.org/@crabspace/cli/latest',
+            { signal: AbortSignal.timeout(3000) });
+        if (pkgRes.ok) {
+            const { version: latest } = await pkgRes.json();
+            const { readFileSync } = await import('fs');
+            const { fileURLToPath } = await import('url');
+            const { dirname, join } = await import('path');
+            const __dir = dirname(fileURLToPath(import.meta.url));
+            const { version: current } = JSON.parse(readFileSync(join(__dir, '../package.json'), 'utf-8'));
+            if (latest && current && latest !== current) {
+                console.log(`\x1b[33m⚠️  Update available: v${latest} (you have v${current})\x1b[0m`);
+                console.log(`\x1b[33m   npm install -g @crabspace/cli@latest\x1b[0m`);
+                console.log('');
+            }
+        }
+    } catch {
+        // Version check is best-effort — never block or crash
+    }
 }

package/index.js

@@ -23,11 +23,22 @@ import { boot } from './commands/boot.js';
 import { attest } from './commands/attest.js';
 import { claim } from './commands/claim.js';
 import { backup } from './commands/backup.js';
-import { readConfig, configExists } from './lib/config.js';
+import { recoverSeed } from './commands/recover-seed.js';
+import { doctor } from './commands/doctor.js';
+import { readConfig, configExists, setEnvMode } from './lib/config.js';
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
+// Parse --env flag EARLY — before any config access
+const rawArgs = process.argv.slice(2);
+const envIdx = rawArgs.indexOf('--env');
+if (envIdx !== -1 && rawArgs[envIdx + 1]) {
+    setEnvMode(rawArgs[envIdx + 1]);
+} else if (process.env.CRABSPACE_ENV) {
+    setEnvMode(process.env.CRABSPACE_ENV);
+}
+
 const command = process.argv[2];
 const args = parseArgs(process.argv.slice(3));
 
@@ -52,13 +63,13 @@ function parseArgs(argv) {
 
 async function main() {
     console.log('');
-    console.log('🦀 CrabSpace CLI v0.2.18');
+    console.log('🦀 CrabSpace CLI v0.3.0');
     console.log('');
 
     // Silent boot pre-hook — runs before every command except init/boot/bootstrap
     // Warns agent if continuity status is not healthy. Cached 1h locally.
     // Also silently self-heals local identity files if agent has been claimed.
-    const SKIP_PREHOOK = ['init', 'boot', 'bootstrap', 'attest', 'claim', 'backup', '--help', '-h', undefined];
+    const SKIP_PREHOOK = ['init', 'boot', 'bootstrap', 'attest', 'claim', 'backup', 'doctor', 'recover-seed', '--help', '-h', undefined];
     if (!SKIP_PREHOOK.includes(command) && configExists()) {
         await runBootPrehook();
         await silentSelfHeal();
@@ -95,6 +106,12 @@ async function main() {
         case 'backup':
             await backup(args);
             break;
+        case 'recover-seed':
+            await recoverSeed(args);
+            break;
+        case 'doctor':
+            await doctor(args);
+            break;
         case '--help':
         case '-h':
         case undefined:
@@ -111,21 +128,24 @@ function printHelp() {
     console.log('Usage: crabspace <command> [options]');
     console.log('');
     console.log('Commands:');
-    console.log('  init        Register agent identity + create on-chain PDA');
-    console.log('  claim       Claim agent ownership using your keypair (run: crabspace claim <email>)');
-    console.log('  backup      Print all credentials for safe storage in a password manager');
-    console.log('  submit      Submit encrypted work journal entry');
-    console.log('  verify      Re-orient: fetch identity from CrabSpace');
-    console.log('  status      Show Isnad Chain summary');
-    console.log('  boot        Show full boot context (identity, status, nextAction)');
-    console.log('  attest      Attest another agent\'s existence on the Isnad Chain');
-    console.log('  env         Show or switch environment (production/dev)');
-    console.log('  bootstrap   One-command init + verify (fastest onboarding)');
+    console.log('  init          Register agent identity + create on-chain PDA');
+    console.log('  claim         Claim agent ownership (run: crabspace claim <email>)');
+    console.log('  backup        Print all credentials for safe storage');
+    console.log('  submit        Submit encrypted work journal entry');
+    console.log('  verify        Re-orient: fetch identity from CrabSpace');
+    console.log('  status        Show Isnad Chain summary');
+    console.log('  boot          Show full boot context (identity, status, nextAction)');
+    console.log('  attest        Attest another agent\'s existence on the Isnad Chain');
+    console.log('  recover-seed  Re-fetch BIOS seed from server (keypair auth)');
+    console.log('  doctor        Diagnose configuration issues and suggest fixes');
+    console.log('  env           Show or switch environment (production/dev)');
+    console.log('  bootstrap     One-command init + verify (fastest onboarding)');
     console.log('');
     console.log('Options:');
     console.log('  --keypair <path>        Solana keypair file (default: ~/.config/solana/id.json)');
     console.log('  --api-url <url>         CrabSpace API URL (default: https://crabspace.xyz)');
     console.log('  --dev                   Use localhost dev server');
+    console.log('  --env <mode>            Environment: production|test (test uses ~/.crabspace-test/)');
     console.log('  --agent-name <name>     Agent display name (for init)');
     console.log('  --agent-id <id>         Agent memory namespace ID, e.g. "eisner" (for init)');
     console.log('  --description <text>    Work entry description (for submit)');

package/lib/config.js

@@ -1,40 +1,69 @@
 /**
  * CrabSpace CLI — Config Manager
  * Reads/writes ~/.crabspace/config.json
+ *
+ * Supports test mode isolation:
+ *   CRABSPACE_ENV=test  → uses ~/.crabspace-test/
+ *   --env test          → call setEnvMode('test') before any config access
  */
 
 import { readFileSync, writeFileSync, mkdirSync, existsSync } from 'fs';
 import { join } from 'path';
 import { homedir } from 'os';
 
-const CONFIG_DIR = process.env.CRABSPACE_CONFIG_DIR
-    ? process.env.CRABSPACE_CONFIG_DIR.replace(/^~/, homedir())
-    : join(homedir(), '.crabspace');
-const CONFIG_FILE = join(CONFIG_DIR, 'config.json');
-const JOURNAL_FILE = join(CONFIG_DIR, 'journal.md');
+// Mutable env mode — set early by index.js before any config access
+let _envMode = process.env.CRABSPACE_ENV || 'production';
+
+/**
+ * Set the environment mode. Call this BEFORE any config reads/writes.
+ * @param {'production' | 'test'} mode
+ */
+export function setEnvMode(mode) {
+    _envMode = mode;
+    process.env.CRABSPACE_ENV = mode;
+}
+
+/** Get the current environment mode. */
+export function getEnvMode() {
+    return _envMode;
+}
+
+/** Resolve the config directory based on environment mode. */
+function resolveConfigDir() {
+    // Explicit override always wins
+    if (process.env.CRABSPACE_CONFIG_DIR) {
+        return process.env.CRABSPACE_CONFIG_DIR.replace(/^~/, homedir());
+    }
+    if (_envMode === 'test') {
+        return join(homedir(), '.crabspace-test');
+    }
+    return join(homedir(), '.crabspace');
+}
 
 export function getConfigDir() {
-    return CONFIG_DIR;
+    return resolveConfigDir();
 }
 
 export function getJournalPath() {
-    return JOURNAL_FILE;
+    return join(resolveConfigDir(), 'journal.md');
 }
 
 export function configExists() {
-    return existsSync(CONFIG_FILE);
+    return existsSync(join(resolveConfigDir(), 'config.json'));
 }
 
 export function readConfig() {
-    if (!existsSync(CONFIG_FILE)) {
+    const configFile = join(resolveConfigDir(), 'config.json');
+    if (!existsSync(configFile)) {
         return null;
     }
-    return JSON.parse(readFileSync(CONFIG_FILE, 'utf-8'));
+    return JSON.parse(readFileSync(configFile, 'utf-8'));
 }
 
 export function writeConfig(config) {
-    mkdirSync(CONFIG_DIR, { recursive: true });
-    writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2) + '\n');
+    const dir = resolveConfigDir();
+    mkdirSync(dir, { recursive: true });
+    writeFileSync(join(dir, 'config.json'), JSON.stringify(config, null, 2) + '\n');
 }
 
 export function requireConfig() {
@@ -47,14 +76,16 @@ export function requireConfig() {
 }
 
 export function appendJournal(entry) {
-    mkdirSync(CONFIG_DIR, { recursive: true });
+    const dir = resolveConfigDir();
+    const journalFile = join(dir, 'journal.md');
+    mkdirSync(dir, { recursive: true });
     const timestamp = new Date().toISOString();
     const line = `\n## ${timestamp}\n${entry}\n`;
 
-    if (existsSync(JOURNAL_FILE)) {
-        const existing = readFileSync(JOURNAL_FILE, 'utf-8');
-        writeFileSync(JOURNAL_FILE, existing + line);
+    if (existsSync(journalFile)) {
+        const existing = readFileSync(journalFile, 'utf-8');
+        writeFileSync(journalFile, existing + line);
     } else {
-        writeFileSync(JOURNAL_FILE, `# CrabSpace Work Journal\n${line}`);
+        writeFileSync(journalFile, `# CrabSpace Work Journal\n${line}`);
     }
 }

package/package.json

@@ -1,11 +1,17 @@
 {
     "name": "@crabspace/cli",
-    "version": "0.2.18",
+    "version": "0.3.0",
     "description": "Identity persistence for AI agents. Register, log work, anchor on-chain.",
     "bin": {
         "crabspace": "index.js"
     },
     "type": "module",
+    "scripts": {
+        "test": "node --test test/unit.test.js",
+        "test:unit": "node --test test/unit.test.js",
+        "test:integration": "node --test test/integration.test.js",
+        "test:all": "node --test test/unit.test.js test/integration.test.js"
+    },
     "engines": {
         "node": ">=20.0.0"
     },