memoir-cli 3.6.0 → 3.7.1

package/bin/memoir.js

@@ -22,6 +22,19 @@ import { projectsListCommand, projectsTodoCommand } from '../src/commands/projec
 import { upgradeCommand } from '../src/commands/upgrade.js';
 import { activateCommand, deactivateCommand } from '../src/commands/activate.js';
 import { consolidateCommand } from '../src/commands/consolidate.js';
+import {
+  goalCommand,
+  nextCommand,
+  doneCommand,
+  noteCommand,
+  askCommand,
+  sessionShowCommand,
+  sessionClearCommand,
+} from '../src/commands/session.js';
+import { autopushCommand } from '../src/commands/autopush.js';
+import { whyCommand } from '../src/commands/why.js';
+import { autoRefreshCommand } from '../src/commands/auto-refresh.js';
+import { hooksInstallCommand, hooksUninstallCommand, hooksStatusCommand } from '../src/commands/hooks.js';
 import { createRequire } from 'module';
 
 const require = createRequire(import.meta.url);
@@ -153,6 +166,106 @@ program
     }
   });
 
+// ── Session continuity ──────────────────────────────────────────
+program
+  .command('goal <text...>')
+  .description('Set your current goal (pinned into CLAUDE.md, syncs across machines)')
+  .action(async (text) => {
+    try { await goalCommand(text.join(' ')); }
+    catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
+program
+  .command('next <text...>')
+  .description('Add a next action')
+  .action(async (text) => {
+    try { await nextCommand(text.join(' ')); }
+    catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
+program
+  .command('done <text...>')
+  .description('Mark a next action complete (substring match)')
+  .action(async (text) => {
+    try { await doneCommand(text.join(' ')); }
+    catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
+program
+  .command('note <text...>')
+  .description('Record a decision with rationale (--why) and rejected alternative (--rejected)')
+  .option('--why <rationale>', 'Why this decision was made')
+  .option('--rejected <alternative>', 'The alternative you considered and rejected')
+  .action(async (text, options) => {
+    try { await noteCommand(text.join(' '), options); }
+    catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
+program
+  .command('ask <text...>')
+  .description('Capture an open question for later')
+  .action(async (text) => {
+    try { await askCommand(text.join(' ')); }
+    catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
+program
+  .command('why [query...]')
+  .description('Look up decisions by keyword — returns what was decided + why + what was rejected')
+  .action(async (query) => {
+    try { await whyCommand((query || []).join(' ')); }
+    catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
+program
+  .command('session')
+  .description('Show the current session state')
+  .action(async () => {
+    try { await sessionShowCommand(); }
+    catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
+program
+  .command('session-clear')
+  .description('Clear the current session (history retained)')
+  .action(async () => {
+    try { await sessionClearCommand(); }
+    catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
+// ── Hooks + auto-sync (called by Claude Code hooks or the user) ─────
+program
+  .command('autopush')
+  .description('Debounced auto-push — called by the Claude Code Stop hook')
+  .option('--debounce <seconds>', 'Minimum seconds between auto-pushes', '30')
+  .option('-v, --verbose', 'Print debounce state')
+  .action(async (options) => {
+    try { await autopushCommand(options); }
+    catch (err) { if (options.verbose) console.error(chalk.red(err.message)); /* silent by default */ }
+  });
+
+program
+  .command('auto-refresh')
+  .description('Re-render the pinned session block — called by the SessionStart hook')
+  .option('-v, --verbose', 'Print what changed')
+  .action(async (options) => {
+    try { await autoRefreshCommand(options); }
+    catch (err) { if (options.verbose) console.error(chalk.red(err.message)); }
+  });
+
+program
+  .command('hooks')
+  .description('Manage Claude Code hooks (install | uninstall | status)')
+  .argument('[subcommand]', 'install, uninstall, or status', 'status')
+  .option('-y, --yes', 'Skip confirmation prompts')
+  .action(async (subcommand, options) => {
+    try {
+      if (subcommand === 'install') await hooksInstallCommand(options);
+      else if (subcommand === 'uninstall') await hooksUninstallCommand(options);
+      else await hooksStatusCommand();
+    } catch (err) { console.error(chalk.red('\n✖ Error:'), err.message); process.exit(1); }
+  });
+
 program
   .command('doctor')
   .alias('diagnose')

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "memoir-cli",
-  "version": "3.6.0",
+  "version": "3.7.1",
   "mcpName": "io.github.camgitt/memoir",
   "description": "MCP server that gives Claude, Cursor, and Gemini long-term memory across sessions. Your AI remembers your codebase, decisions, and preferences — across tools and machines.",
   "main": "src/index.js",
@@ -9,6 +9,15 @@
     "memoir": "bin/memoir.js",
     "memoir-mcp": "src/mcp.js"
   },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
   "repository": {
     "type": "git",
     "url": "https://github.com/camgitt/memoir.git"
@@ -19,7 +28,9 @@
   },
   "scripts": {
     "start": "node bin/memoir.js",
-    "test": "bash test-local.sh",
+    "test": "node run-tests.mjs",
+    "test:legacy": "bash test-local.sh",
+    "prepublishOnly": "npm test",
     "postinstall": "node -e \"try{const c='\\x1b[36m',r='\\x1b[0m',g='\\x1b[90m';console.log('\\n  '+c+'memoir'+r+' installed.\\n  Run '+c+'memoir activate'+r+' in any project to give your AI long-term memory.\\n  '+g+'https://memoir.sh'+r+'\\n')}catch{}\""
   },
   "keywords": [

package/src/adapters/restore.js

@@ -14,9 +14,19 @@ export function detectLocalHomeKey(adapterSource) {
   if (!fs.existsSync(localProjectsDir)) return null;
 
   const entries = fs.readdirSync(localProjectsDir)
+    .filter(e => !e.startsWith('.'))
     .filter(e => fs.statSync(path.join(localProjectsDir, e)).isDirectory());
   if (entries.length === 0) return null;
 
+  // Prefer the key that matches this machine's homedir encoding.
+  // Stale foreign dirs (from older memoir versions) can have newer mtimes,
+  // so mtime alone is unreliable — the encoded homedir is the ground truth.
+  const home = os.homedir();
+  const expectedKey = process.platform === 'win32'
+    ? home.replace(/\\/g, '-').replace(/:/g, '-')
+    : '-' + home.replace(/^\//, '').replace(/\//g, '-');
+  if (entries.includes(expectedKey)) return expectedKey;
+
   // Find dirs with a memory/ subfolder that aren't sub-projects of another dir
   const candidates = entries.filter(entry => {
     const hasMemory = fs.existsSync(path.join(localProjectsDir, entry, 'memory'));
@@ -143,6 +153,57 @@ function remapProjectPaths(backupDir, adapterSource) {
   return remaps;
 }
 
+// Scan local ~/.claude/projects/ for foreign home-key dirs left behind by older
+// memoir versions (when remap was unreliable). Merge their memory/ into the local
+// home key and move the stale dir into .memoir-archived-{ts}/ so nothing is lost.
+export async function cleanupLocalForeignKeys(adapterSource) {
+  const projectsDir = path.join(adapterSource, 'projects');
+  if (!await fs.pathExists(projectsDir)) return { archived: [], merged: 0 };
+
+  const localHomeKey = detectLocalHomeKey(adapterSource);
+  if (!localHomeKey) return { archived: [], merged: 0 };
+
+  const home = os.homedir();
+  const localUsername = path.basename(home).toLowerCase();
+
+  const entries = (await fs.readdir(projectsDir, { withFileTypes: true }))
+    .filter(e => e.isDirectory() && !e.name.startsWith('.'))
+    .map(e => e.name);
+
+  const foreignKeys = [];
+  for (const entry of entries) {
+    if (entry === localHomeKey) continue;
+    if (entry.startsWith(localHomeKey + '-')) continue;
+    // Leave alt encodings of THIS machine alone (contain local username)
+    if (entry.toLowerCase().includes(localUsername)) continue;
+    // Must have memory/ — dirs without it are project dirs that Claude won't read anyway
+    if (!await fs.pathExists(path.join(projectsDir, entry, 'memory'))) continue;
+    foreignKeys.push(entry);
+  }
+
+  if (foreignKeys.length === 0) return { archived: [], merged: 0 };
+
+  const ts = new Date().toISOString().replace(/[:.]/g, '-').slice(0, 19);
+  const archiveDir = path.join(projectsDir, `.memoir-archived-${ts}`);
+  await fs.ensureDir(archiveDir);
+
+  const localMemDir = path.join(projectsDir, localHomeKey, 'memory');
+  await fs.ensureDir(localMemDir);
+
+  let merged = 0;
+  for (const key of foreignKeys) {
+    const foreignMemDir = path.join(projectsDir, key, 'memory');
+    if (await fs.pathExists(foreignMemDir)) {
+      const before = (await fs.readdir(localMemDir)).length;
+      await mergeMemoryDirs(foreignMemDir, localMemDir);
+      merged += (await fs.readdir(localMemDir)).length - before;
+    }
+    await fs.move(path.join(projectsDir, key), path.join(archiveDir, key));
+  }
+
+  return { archived: foreignKeys, merged };
+}
+
 // Merge memory dirs from a foreign machine — copies files that don't exist locally,
 // and for files that exist on both, keeps the newer version.
 async function mergeMemoryDirs(src, dest) {
@@ -291,6 +352,21 @@ export async function restoreMemories(sourceDir, spinner, onlyFilter = null, aut
       if (confirm) {
         const changes = { added: [], updated: [], skipped: [] };
 
+        // Clean up stale foreign home-key dirs left on this machine by older
+        // memoir versions. Must run before remap so detectLocalHomeKey sees a
+        // clean local state.
+        if (adapter.name === 'Claude CLI') {
+          try {
+            const { archived, merged } = await cleanupLocalForeignKeys(adapter.source);
+            if (archived.length > 0) {
+              spinner.stop();
+              console.log(chalk.gray(`  Cleaned up ${archived.length} stale foreign dir(s) on this machine${merged > 0 ? ` (merged ${merged} new file(s))` : ''}`));
+              for (const k of archived) console.log(chalk.gray(`    archived: ${k}`));
+              spinner.start();
+            }
+          } catch {}
+        }
+
         // Remap Claude project paths from source machine to this machine
         if (adapter.name === 'Claude CLI') {
           const remaps = remapProjectPaths(backupDir, adapter.source);

package/src/commands/auto-refresh.js

@@ -0,0 +1,31 @@
+// Auto-refresh — called by the Claude Code SessionStart hook.
+// Reads current session.json (local) and re-injects the pinned block into
+// CLAUDE.md. Instant, no network, no side effects beyond that file.
+//
+// For cross-machine pull-on-start, that's a separate concern — handled by
+// periodic auto-restore or explicit `memoir restore`. This hook only ensures
+// the pinned block matches the current local session state.
+
+import { readSession } from '../session/state.js';
+import { renderSession } from '../session/render.js';
+import { injectInto, detectAvailableTargets } from '../session/inject.js';
+
+export async function autoRefreshCommand(options = {}) {
+  const verbose = !!options.verbose;
+  try {
+    const state = await readSession();
+    const rendered = renderSession(state);
+    const targets = detectAvailableTargets();
+    for (const [tool, target] of Object.entries(targets)) {
+      try {
+        const res = await injectInto(target, rendered);
+        if (verbose) console.log(`memoir auto-refresh: ${res.replaced ? 'updated' : 'created'} ${tool} → ${res.path}`);
+      } catch (err) {
+        if (verbose) console.error(`memoir auto-refresh: ${tool} failed: ${err.message}`);
+      }
+    }
+  } catch (err) {
+    if (verbose) console.error(`memoir auto-refresh: ${err.message}`);
+    // Never fail the hook — session start must proceed.
+  }
+}

package/src/commands/autopush.js

@@ -0,0 +1,57 @@
+// Auto-push command — called by the Claude Code Stop hook after every response.
+//
+// Rules of engagement:
+//   - Debounced: won't run more than once per DEBOUNCE_SECONDS.
+//   - Non-blocking: detaches a background subprocess and exits immediately
+//     so Claude's response pipeline is never held up.
+//   - Silent: no stdout unless --verbose is passed.
+//
+// The actual push work happens in a fully detached child — the hook process
+// itself just records a timestamp and returns.
+
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import { spawn } from 'child_process';
+
+const home = os.homedir();
+const STAMP_FILE = path.join(home, '.config', 'memoir', 'last-autopush.timestamp');
+const DEBOUNCE_SECONDS_DEFAULT = 30;
+
+export async function autopushCommand(options = {}) {
+  const debounce = parseInt(options.debounce || DEBOUNCE_SECONDS_DEFAULT, 10);
+  const verbose = !!options.verbose;
+
+  try {
+    await fs.ensureDir(path.dirname(STAMP_FILE));
+  } catch {}
+
+  const now = Date.now();
+  let last = 0;
+  try {
+    const raw = await fs.readFile(STAMP_FILE, 'utf8');
+    last = parseInt(raw.trim(), 10) || 0;
+  } catch {}
+
+  const elapsed = (now - last) / 1000;
+  if (last && elapsed < debounce) {
+    if (verbose) console.log(`memoir autopush: skipped (${Math.floor(elapsed)}s since last, debounce=${debounce}s)`);
+    return;
+  }
+
+  // Stamp BEFORE spawning so rapid repeat calls don't all race through.
+  try {
+    await fs.writeFile(STAMP_FILE, String(now));
+  } catch {}
+
+  // Detach a background push. Parent exits immediately so Claude isn't blocked.
+  const memoirBin = process.argv[1]; // path to this same memoir CLI
+  const child = spawn(process.execPath, [memoirBin, 'push'], {
+    detached: true,
+    stdio: verbose ? 'inherit' : 'ignore',
+    env: { ...process.env, MEMOIR_AUTOPUSH: '1' },
+  });
+  child.unref();
+
+  if (verbose) console.log('memoir autopush: triggered (background)');
+}

package/src/commands/hooks.js

@@ -0,0 +1,171 @@
+// Install / uninstall / status for Claude Code hooks.
+//
+// Hooks are configured in ~/.claude/settings.json under the `hooks` object:
+//   {
+//     "hooks": {
+//       "Stop":         [{ "matcher": "", "hooks": [{ "type": "command", "command": "..." }] }],
+//       "SessionStart": [{ "matcher": "", "hooks": [{ "type": "command", "command": "..." }] }]
+//     }
+//   }
+//
+// We merge into any existing hooks the user has — never clobber. Our entries
+// are identified by a marker in the command string so we can find and remove
+// them on uninstall.
+
+import fs from 'fs-extra';
+import path from 'path';
+import os from 'os';
+import chalk from 'chalk';
+import boxen from 'boxen';
+import inquirer from 'inquirer';
+
+const home = os.homedir();
+const CLAUDE_SETTINGS = path.join(home, '.claude', 'settings.json');
+const MARKER = 'memoir'; // any command containing this is ours
+
+const OUR_HOOKS = {
+  Stop: {
+    type: 'command',
+    command: 'memoir autopush --debounce 30',
+  },
+  SessionStart: {
+    type: 'command',
+    command: 'memoir auto-refresh',
+  },
+};
+
+async function readSettings() {
+  if (!await fs.pathExists(CLAUDE_SETTINGS)) return {};
+  try {
+    return JSON.parse(await fs.readFile(CLAUDE_SETTINGS, 'utf8'));
+  } catch {
+    return {};
+  }
+}
+
+async function writeSettings(settings) {
+  await fs.ensureDir(path.dirname(CLAUDE_SETTINGS));
+  const tmp = `${CLAUDE_SETTINGS}.tmp-${process.pid}`;
+  await fs.writeFile(tmp, JSON.stringify(settings, null, 2));
+  await fs.move(tmp, CLAUDE_SETTINGS, { overwrite: true });
+}
+
+function findOurEntry(hookList) {
+  // hookList is array of { matcher, hooks: [{type, command}] }
+  return (hookList || []).findIndex(entry =>
+    (entry.hooks || []).some(h => h.type === 'command' && (h.command || '').includes(MARKER))
+  );
+}
+
+function ensureOurHook(settings, eventName, hook) {
+  settings.hooks = settings.hooks || {};
+  settings.hooks[eventName] = settings.hooks[eventName] || [];
+  const list = settings.hooks[eventName];
+
+  const existing = findOurEntry(list);
+  if (existing >= 0) {
+    // Replace (idempotent — same shape every time)
+    list[existing] = { matcher: '', hooks: [hook] };
+  } else {
+    list.push({ matcher: '', hooks: [hook] });
+  }
+}
+
+function removeOurHook(settings, eventName) {
+  if (!settings?.hooks?.[eventName]) return false;
+  const list = settings.hooks[eventName];
+  const idx = findOurEntry(list);
+  if (idx < 0) return false;
+  list.splice(idx, 1);
+  if (list.length === 0) delete settings.hooks[eventName];
+  return true;
+}
+
+export async function hooksInstallCommand(options = {}) {
+  const settings = await readSettings();
+  const fresh = JSON.parse(JSON.stringify(settings)); // snapshot for diff
+
+  ensureOurHook(fresh, 'Stop', OUR_HOOKS.Stop);
+  ensureOurHook(fresh, 'SessionStart', OUR_HOOKS.SessionStart);
+
+  const isNoop = JSON.stringify(settings) === JSON.stringify(fresh);
+  if (isNoop) {
+    console.log('\n' + chalk.green('  ✓ Hooks already installed — nothing to do.\n'));
+    return;
+  }
+
+  // Show what will change
+  console.log('\n' + boxen(
+    chalk.cyan('memoir will add these hooks to ') + chalk.white.bold('~/.claude/settings.json') + chalk.cyan(':') + '\n\n' +
+    chalk.gray('  Stop:         ') + chalk.white(OUR_HOOKS.Stop.command) + '\n' +
+    chalk.gray('                fires after every response; auto-pushes (debounced 30s)') + '\n\n' +
+    chalk.gray('  SessionStart: ') + chalk.white(OUR_HOOKS.SessionStart.command) + '\n' +
+    chalk.gray('                fires at session open; refreshes pinned block from session.json') + '\n\n' +
+    chalk.gray('  Your existing settings (including other hooks) will be preserved.'),
+    { padding: 1, borderStyle: 'round', borderColor: 'cyan', dimBorder: true }
+  ) + '\n');
+
+  if (!options.yes) {
+    const { confirm } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'confirm',
+      message: 'Install hooks?',
+      default: true,
+    }]);
+    if (!confirm) {
+      console.log(chalk.yellow('\n  Cancelled.\n'));
+      return;
+    }
+  }
+
+  await writeSettings(fresh);
+  console.log('\n' + chalk.green('  ✓ Hooks installed. Restart Claude Code to activate.\n'));
+}
+
+export async function hooksUninstallCommand(options = {}) {
+  const settings = await readSettings();
+  const fresh = JSON.parse(JSON.stringify(settings));
+  const removedStop = removeOurHook(fresh, 'Stop');
+  const removedStart = removeOurHook(fresh, 'SessionStart');
+
+  if (!removedStop && !removedStart) {
+    console.log('\n' + chalk.gray('  No memoir hooks installed.\n'));
+    return;
+  }
+
+  if (!options.yes) {
+    const { confirm } = await inquirer.prompt([{
+      type: 'confirm',
+      name: 'confirm',
+      message: 'Remove memoir hooks from ~/.claude/settings.json?',
+      default: true,
+    }]);
+    if (!confirm) {
+      console.log(chalk.yellow('\n  Cancelled.\n'));
+      return;
+    }
+  }
+
+  await writeSettings(fresh);
+  console.log('\n' + chalk.green('  ✓ memoir hooks removed.\n'));
+}
+
+export async function hooksStatusCommand() {
+  const settings = await readSettings();
+  const hasStop = (settings.hooks?.Stop || []).some(entry =>
+    (entry.hooks || []).some(h => (h.command || '').includes(MARKER))
+  );
+  const hasStart = (settings.hooks?.SessionStart || []).some(entry =>
+    (entry.hooks || []).some(h => (h.command || '').includes(MARKER))
+  );
+
+  const mark = (b) => b ? chalk.green('  ✓ ') : chalk.gray('  ✗ ');
+  console.log('\n' + boxen(
+    chalk.cyan.bold('memoir hooks status') + '\n\n' +
+    mark(hasStop) + chalk.white('Stop hook') + chalk.gray(' (auto-push)') + '\n' +
+    mark(hasStart) + chalk.white('SessionStart hook') + chalk.gray(' (auto-refresh)') + '\n\n' +
+    chalk.gray('  Settings: ') + chalk.white(CLAUDE_SETTINGS) + '\n' +
+    chalk.gray('  Run ') + chalk.cyan('memoir hooks install') + chalk.gray(' to add missing hooks.'),
+    { padding: 1, borderStyle: 'round', borderColor: 'cyan', dimBorder: true }
+  ) + '\n');
+}

package/src/commands/push.js

@@ -15,6 +15,9 @@ import { encryptDirectory, createVerifyToken } from '../security/encryption.js';
 import { getRawConfig, saveConfig, migrateConfigToV2 } from '../config.js';
 import { scanWorkspace } from '../workspace/tracker.js';
 import { promptActivate } from './activate.js';
+import { paths as sessionPaths, readSession, addNote, recordSessionEnd } from '../session/state.js';
+import { renderSession } from '../session/render.js';
+import { injectInto, detectAvailableTargets } from '../session/inject.js';
 
 export async function pushCommand(options = {}) {
   let config = await getConfig(options.profile);
@@ -93,6 +96,54 @@ export async function pushCommand(options = {}) {
             } catch {}
           }
 
+          // Also feed structured decisions into session.json so they appear in
+          // the pinned block and sync cross-machine. Dedupe against anything
+          // the AI already captured via MCP tools or the user via `memoir note`.
+          try {
+            const current = await readSession();
+            const existingTexts = new Set(
+              current.current.decisions.map(d => (d.text || '').trim().toLowerCase())
+            );
+            // Quality filter: auto-extracted decisions come from regex patterns
+            // that sometimes catch table cells or prose fragments. Keep only
+            // substantive-looking entries.
+            const isQuality = (text) => {
+              if (!text) return false;
+              if (text.length < 15) return false;                // too short to be a real decision
+              if (text.length > 200) return false;               // probably a snippet, not a decision
+              if (/\|/.test(text)) return false;                 // markdown table fragment
+              if (/[_*`]{3,}/.test(text)) return false;          // markdown formatting leaked in
+              if (!/[a-zA-Z]/.test(text)) return false;          // no actual words
+              const words = text.split(/\s+/).length;
+              if (words < 3) return false;                       // less than 3 words isn't a decision
+              return true;
+            };
+            for (const d of parsed.decisions.slice(0, 10)) {
+              const text = String(d.value || '').trim();
+              if (!isQuality(text)) continue;
+              if (existingTexts.has(text.toLowerCase())) continue;
+              await addNote(text, { why: d.context ? `auto-captured: ${d.context.slice(0, 80)}` : undefined });
+            }
+            // Record a session summary in history for "recent sessions" section
+            const filesList = Array.from(parsed.filesWritten || []).slice(0, 10);
+            const durationMin = (parsed.firstTimestamp && parsed.lastTimestamp)
+              ? Math.floor((new Date(parsed.lastTimestamp) - new Date(parsed.firstTimestamp)) / 60000)
+              : null;
+            const summary = parsed.slug ? `Worked on ${parsed.slug}` : `${filesList.length} file(s) touched`;
+            await recordSessionEnd({ summary, filesTouched: filesList, durationMin });
+            // Re-render into every detected tool so the pinned block reflects
+            // what was just auto-captured from the .jsonl
+            try {
+              const state = await readSession();
+              const rendered = renderSession(state);
+              for (const target of Object.values(detectAvailableTargets())) {
+                try { await injectInto(target, rendered); } catch {}
+              }
+            } catch {}
+          } catch {
+            // Session.json capture is best-effort
+          }
+
           contextCaptured = true;
           sessionInfo = {
             slug: parsed.slug,
@@ -128,6 +179,17 @@ export async function pushCommand(options = {}) {
       // Workspace scan is best-effort
     }
 
+    // Include session.json (continuity state) so it syncs across machines
+    let sessionIncluded = false;
+    try {
+      if (await fs.pathExists(sessionPaths.session)) {
+        await fs.copy(sessionPaths.session, path.join(stagingDir, 'session.json'));
+        sessionIncluded = true;
+      }
+    } catch {
+      // Best-effort — don't fail the push over this
+    }
+
     // Count what was found
     const found = [];
     for (const adapter of adapters) {

package/src/commands/restore.js

@@ -14,6 +14,9 @@ import { restoreWorkspace } from '../workspace/tracker.js';
 import { getSession } from '../cloud/auth.js';
 import { unbundleToDir } from '../cloud/storage.js';
 import { SUPABASE_URL, SUPABASE_ANON_KEY, STORAGE_BUCKET } from '../cloud/constants.js';
+import { readSession, writeSession, mergeSessions, paths as sessionPaths } from '../session/state.js';
+import { renderSession } from '../session/render.js';
+import { injectInto, detectAvailableTargets } from '../session/inject.js';
 
 const home = os.homedir();
 
@@ -119,6 +122,39 @@ export async function restoreCommand(options = {}) {
 
     spinner.stop();
 
+    // Merge session.json (continuity state) from backup into local
+    let sessionMerged = false;
+    let sessionNewMachine = false;
+    try {
+      const remoteSessionPath = path.join(stagingDir, 'session.json');
+      if (await fs.pathExists(remoteSessionPath)) {
+        const remote = JSON.parse(await fs.readFile(remoteSessionPath, 'utf8'));
+        const local = await readSession();
+        const beforeMachines = Object.keys(local.machines || {}).length;
+        const merged = mergeSessions(local, remote);
+        await writeSession(merged);
+        // Re-render + inject into every detected tool so the pinned block
+        // reflects the merged state right away across Claude/Cursor/Windsurf/Gemini
+        try {
+          const rendered = renderSession(merged);
+          for (const target of Object.values(detectAvailableTargets())) {
+            try { await injectInto(target, rendered); } catch {}
+          }
+        } catch {}
+        sessionMerged = true;
+        sessionNewMachine = Object.keys(merged.machines || {}).length > beforeMachines;
+      }
+    } catch {
+      // Best-effort — don't fail the restore over this
+    }
+
+    if (sessionMerged) {
+      const msg = sessionNewMachine
+        ? chalk.cyan('  🔄 Session state merged from another machine')
+        : chalk.gray('  ✔ Session state up to date');
+      console.log(msg);
+    }
+
     // Auto-inject session handoff if available
     let handoffInjected = false;
     let handoffInfo = null;