@nemus-cli/nemus 0.15.2 → 0.17.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nemus-cli/nemus",
-  "version": "0.15.2",
+  "version": "0.17.0",
   "workspaces": [
     "packages/*"
   ],
@@ -83,6 +83,6 @@
     "@types/react": "^19.2.2",
     "ts-node": "^10.9.1",
     "typescript": "^5.9.3",
-    "vitest": "^4.1.11"
+    "vitest": "^5.0.0"
   }
 }

package/skills/nemus/SKILL.md

@@ -46,6 +46,7 @@ Global flags: `-f/--force-refresh` (skip repo cache), `-y/--yes` (skip prompts),
 | Pull latest (git sync) | [workspace-sync](references/workspace-sync.md) | `nemus sync [name]` | `s` |
 | Show diff summary | [workspace-diff](references/workspace-diff.md) | `nemus diff [name]` | `di` |
 | Run shell command across repos | [run-command](references/run-command.md) | `nemus run [name] <cmd>` | `r` |
+| Start all repos' dev servers together | [dev](references/dev.md) | `nemus dev [name]` | — |
 | Health check | [workspace-doctor](references/workspace-doctor.md) | `nemus doctor [name]` | `doc` |
 | Clean node_modules / artifacts | [workspace-cleanup](references/workspace-cleanup.md) | `nemus cleanup <name>` | `cl` |
 | Remove repo from workspace | [remove-repo](references/remove-repo.md) | `nemus remove-repo` | `rr` |
@@ -72,6 +73,18 @@ Global flags: `-f/--force-refresh` (skip repo cache), `-y/--yes` (skip prompts),
 | Import suite(s) from JSON | [suite-import](references/suite-import.md) | `nemus suite import <file>` |
 | Create workspace from suite | [suite-use](references/suite-use.md) | `nemus suite use` |
 
+### Portable Workspaces (lock / restore)
+
+| Intent | Reference | CLI |
+|---|---|---|
+| Snapshot a workspace to a committable `nemus.lock` | [lock](references/lock.md) | `nemus lock [ws] [-o file\|-]` |
+| Recreate a workspace from a `nemus.lock` | [restore](references/restore.md) | `nemus restore [file\|-] [-w name] [--pin]` |
+
+`lock`/`restore` is portable and recreates repos from scratch (vs. `snapshot`,
+which is local time-travel within an existing workspace; vs. `suite`, a reusable
+repo *template*). The lockfile records repos + owner + each repo's branch + HEAD
+commit; it holds no secrets (only what `git remote -v` exposes).
+
 ### Cache & Repo Discovery
 
 | Intent | Reference | CLI |

package/skills/nemus/references/dev.md

@@ -0,0 +1,46 @@
+# dev
+
+Start every repo's dev server in a workspace at once, streaming their output into
+one terminal with a color-coded, aligned per-repo prefix. A single Ctrl-C stops
+them all cleanly (process-group kill, so child trees die too).
+
+## CLI
+
+```bash
+nemus dev [workspace] [options]
+```
+
+- `[workspace]` — workspace name; omitted, resolves the current/default one.
+- `--only <repos>` — comma-separated subset of repos to start.
+- `--script <name>` — npm script to prefer (default: `dev` → `develop` → `start` → `serve`).
+- `--command "<cmd>"` — run this exact command in every selected repo instead of a script.
+- `--exit-on-failure` — tear everything down if any service exits non-zero.
+- `--kill-timeout <seconds>` — grace period before SIGKILL on shutdown (default 5).
+
+## Command selection (per repo)
+
+1. `--command` if given.
+2. Else the first `package.json` script that exists (`--script` → `dev` →
+   `develop` → `start` → `serve`), run with the repo's own package manager
+   (pnpm/yarn/npm, detected from its lockfile).
+3. A repo with no runnable script is **skipped with a notice** — so a library in
+   the workspace doesn't block the services. If nothing is runnable, `dev` errors.
+
+## Examples
+
+```bash
+nemus dev                          # every runnable repo in the current workspace
+nemus dev payments --only web,api   # just a subset
+nemus dev payments --command "make run"
+nemus dev payments --exit-on-failure
+```
+
+## Notes
+
+- Long-running: it stays in the foreground hosting the servers until they exit or
+  you Ctrl-C. Not for scripting — use `nemus run` for one-shot commands.
+- Each service runs in its own process group; shutdown SIGTERMs the group, then
+  SIGKILLs stragglers after `--kill-timeout`, so nothing is orphaned.
+- **Platform:** clean process-group teardown is POSIX (macOS/Linux). On Windows
+  it falls back to `taskkill /T /F` (force-kill the tree, no graceful phase).
+- `--kill-timeout 0` is honored (immediate SIGKILL after the SIGTERM).

package/skills/nemus/references/lock.md

@@ -0,0 +1,38 @@
+# lock
+
+Snapshot a workspace into a committable `nemus.lock` — the repos, each repo's
+owner + directory name + clone URL, the branch it's currently on, and its HEAD
+commit. Share the file (commit it, drop it in a ticket) and anyone recreates the
+exact workspace with [`restore`](restore.md).
+
+## CLI
+
+```bash
+nemus lock [workspace] [options]
+```
+
+- `[workspace]` — workspace name; omitted, resolves the current/default one.
+- `-o, --output <file>` — write to `<file>` instead of `<workspace>/nemus.lock`.
+  Use `-o -` to print the lockfile JSON to stdout (pipe/redirect it anywhere).
+- `--all` — write a `nemus.lock` into **every** workspace (makes a whole machine
+  portable in one shot). Skips workspaces that already have a lockfile unless
+  `--force` is given. Cannot be combined with `--output`. This is the explicit
+  alternative to a hidden snapshot side effect in `migrate`.
+
+## Examples
+
+```bash
+nemus lock                       # write ./nemus.lock into the current workspace
+nemus lock checkout-flow          # snapshot a named workspace
+nemus lock checkout-flow -o cf.lock
+nemus lock checkout-flow -o - | pbcopy   # copy the manifest to the clipboard
+nemus lock --all                 # lock every workspace (skips existing lockfiles)
+nemus lock --all --force          # …and overwrite existing ones
+```
+
+## Notes
+
+- Repos whose original clone failed are skipped.
+- A repo on a detached HEAD records only its commit (no branch).
+- The lockfile contains only what `git remote -v` already exposes — safe to commit.
+- Distinct from `snapshot` (local time-travel) and `suite` (reusable template).

package/skills/nemus/references/mcp.md

@@ -28,4 +28,6 @@ nemus mcp status
 
 When installed, Claude Code gains access to Nemus tools:
 - `create-workspace`, `list-workspaces`, `workspace-status`, etc.
+- `lock-workspace` / `restore-workspace` — snapshot a workspace to a portable
+  `nemus.lock` and recreate it elsewhere (accepts the manifest inline).
 - Enables natural language workspace management via `nemus -- <prompt>`

package/skills/nemus/references/restore.md

@@ -0,0 +1,39 @@
+# restore
+
+Recreate a workspace from a `nemus.lock` (see [`lock`](lock.md)) on any machine:
+clones every repo and checks out the recorded branch, then writes metadata +
+agent context exactly like `create`.
+
+## CLI
+
+```bash
+nemus restore [lockfile] [options]
+```
+
+- `[lockfile]` — path to a `nemus.lock`; omitted, uses `./nemus.lock`. Use `-`
+  to read the lockfile from stdin.
+- `-w, --workspace <name>` — override the workspace name baked into the lockfile
+  (also used to resolve a name clash).
+- `--pin` — check out the exact recorded commit for each repo instead of the
+  branch tip.
+- `-y, --yes` — non-interactive (skips the post-restore agent launch).
+
+## Examples
+
+```bash
+nemus restore                          # from ./nemus.lock
+nemus restore cf.lock                    # from a specific file
+nemus restore cf.lock -w experiment      # into a differently-named workspace
+nemus restore cf.lock --pin              # reproduce exact commits, not branch tips
+cat cf.lock | nemus restore -            # from stdin
+```
+
+## Notes
+
+- URLs are rebuilt for the restorer's `cloneProtocol` (https/ssh) using the
+  locked host + owner + name, so an ssh-locked workspace restores fine for an
+  https user.
+- If a recorded branch no longer exists on the remote, restore falls back to the
+  recorded commit and warns.
+- Name clashes auto-resolve to a suffixed name (same as `create`).
+- Needs GitHub auth for private repos (warns if `gh` is unauthenticated).

package/src/commands/dev.ts

@@ -0,0 +1,98 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import { WORKSPACES_DIR } from '../utils/config';
+import { loadMetadata } from '../utils/workspace-meta';
+import { resolveWorkspace, getGlobalOpts, parseList } from '../utils/command-helpers';
+import { resolveDevCommand, runDev, type DevService } from '../utils/dev-orchestrator';
+import { logError, logInfo, logWarning } from '../utils/logger';
+import { colorize } from '../utils/colors';
+
+export function registerDevCommand(parent: Command) {
+  parent
+    .command('dev [workspace]')
+    .description('Start every repo\'s dev server together, with unified color-coded logs (Ctrl-C stops all)')
+    .option('--only <repos>', 'Comma-separated subset of repos to start')
+    .option('--script <name>', 'npm script to prefer (default: dev → develop → start → serve)')
+    .option('--command <cmd>', 'Run this exact command in every selected repo instead of a script')
+    .option('--exit-on-failure', 'Tear everything down if any service exits non-zero')
+    .option('--kill-timeout <seconds>', 'Grace period before SIGKILL on shutdown', '5')
+    .action(async (workspace, opts, cmd) => {
+      const globalOpts = getGlobalOpts(cmd);
+      await handleDev({ workspace, ...opts, ...globalOpts });
+    });
+}
+
+async function handleDev(opts: {
+  workspace?: string;
+  only?: string;
+  script?: string;
+  command?: string;
+  exitOnFailure?: boolean;
+  killTimeout?: string;
+}) {
+  try {
+    const workspaceName = await resolveWorkspace(opts.workspace);
+    const workspacePath = path.join(WORKSPACES_DIR, workspaceName);
+
+    const metadata = await loadMetadata(workspacePath);
+    if (!metadata) {
+      logError(`Workspace not found: ${workspaceName}`);
+      process.exit(1);
+    }
+
+    let repos = metadata.repositories.filter(r => r.status === 'success');
+
+    if (opts.only) {
+      const wanted = new Set(parseList(opts.only));
+      repos = repos.filter(r => wanted.has(r.directoryName) || wanted.has(r.name));
+      if (repos.length === 0) {
+        logError(`No repos in "${workspaceName}" matched --only ${opts.only}`);
+        process.exit(1);
+      }
+    }
+
+    const services: DevService[] = [];
+    const skipped: string[] = [];
+    for (const repo of repos) {
+      const cwd = path.join(workspacePath, repo.directoryName);
+      const command = resolveDevCommand(cwd, { commandOverride: opts.command, script: opts.script });
+      if (!command) {
+        skipped.push(repo.directoryName);
+        continue;
+      }
+      services.push({ label: repo.directoryName, cwd, command });
+    }
+
+    if (services.length === 0) {
+      logError(`Nothing to run in "${workspaceName}".`);
+      logInfo(opts.script
+        ? `No repo has a "${opts.script}" script.`
+        : 'No repo has a dev/develop/start/serve script. Pass --command "<cmd>" to run something explicitly.');
+      process.exit(1);
+    }
+
+    if (skipped.length > 0) {
+      logWarning(`Skipped (no runnable script): ${skipped.join(', ')}`);
+    }
+
+    console.log('\n' + colorize('Starting dev servers', 'bright') + colorize(` · ${workspaceName}`, 'cyan'));
+    for (const s of services) {
+      console.log(`  ${colorize(s.label, 'cyan')}  ${colorize(s.command.command, 'gray')} ${colorize(`(${s.command.source})`, 'gray')}`);
+    }
+    console.log(colorize('  Ctrl-C to stop all.\n', 'gray'));
+
+    // NaN check (not `|| 5`) so an explicit --kill-timeout 0 (immediate SIGKILL)
+    // is honored rather than coerced back to the default.
+    const parsedTimeout = Number(opts.killTimeout);
+    const killTimeoutMs = Math.max(0, Number.isFinite(parsedTimeout) ? parsedTimeout : 5) * 1000;
+    const code = await runDev(services, {
+      exitOnFailure: opts.exitOnFailure,
+      killTimeoutMs,
+    });
+    process.exit(code);
+  } catch (error) {
+    logError('Failed to start dev servers');
+    if (error instanceof Error) logError(error.message);
+    process.exit(1);
+  }
+}

package/src/commands/lock.ts

@@ -0,0 +1,129 @@
+import { Command } from 'commander';
+import * as path from 'path';
+import * as fs from 'fs/promises';
+import { WORKSPACES_DIR } from '../utils/config';
+import { loadMetadata, listWorkspaces } from '../utils/workspace-meta';
+import { resolveWorkspace, getGlobalOpts } from '../utils/command-helpers';
+import { buildLock, serializeLock, writeLock, LOCK_FILENAME } from '../utils/workspace-lock';
+import { logError, logInfo, logSuccess, logWarning } from '../utils/logger';
+import { colorize } from '../utils/colors';
+
+export function registerLockCommand(parent: Command) {
+  parent
+    .command('lock [workspace]')
+    .description('Snapshot a workspace into a committable nemus.lock (repos + branches)')
+    .option('-o, --output <file>', 'Write the lockfile to <file> ("-" for stdout) instead of the workspace root')
+    .option('--all', 'Write a nemus.lock into every workspace (skips ones that already have one)')
+    .option('--force', 'With --all, overwrite an existing nemus.lock')
+    .action(async (workspace, opts, cmd) => {
+      const globalOpts = getGlobalOpts(cmd);
+      await handleLock({ workspace, ...opts, ...globalOpts });
+    });
+}
+
+async function fileExists(p: string): Promise<boolean> {
+  try {
+    await fs.access(p);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function handleLock(opts: {
+  workspace?: string;
+  output?: string;
+  all?: boolean;
+  force?: boolean;
+}) {
+  if (opts.all) {
+    await handleLockAll(opts);
+    return;
+  }
+
+  try {
+    const workspaceName = await resolveWorkspace(opts.workspace);
+    const workspacePath = path.join(WORKSPACES_DIR, workspaceName);
+
+    const metadata = await loadMetadata(workspacePath);
+    if (!metadata) {
+      logError(`Workspace not found: ${workspaceName}`);
+      process.exit(1);
+    }
+
+    const lock = await buildLock(workspacePath, metadata);
+
+    // `-o -`: emit only the lockfile JSON so it can be piped/redirected cleanly.
+    if (opts.output === '-') {
+      process.stdout.write(serializeLock(lock));
+      return;
+    }
+
+    const outPath = opts.output
+      ? path.resolve(opts.output)
+      : path.join(workspacePath, LOCK_FILENAME);
+    await writeLock(outPath, lock);
+
+    logSuccess(`Wrote ${colorize(LOCK_FILENAME, 'cyan')} (${lock.repositories.length} repos) → ${outPath}`);
+    logInfo('Commit or share it, then recreate the workspace with: nemus restore');
+  } catch (error) {
+    logError(error instanceof Error ? error.message : 'Failed to write lockfile');
+    process.exit(1);
+  }
+}
+
+/**
+ * Bulk mode: drop a nemus.lock into every workspace so a whole machine's
+ * workspaces become portable in one shot. Existing lockfiles are left alone
+ * (they may be hand-edited / committed) unless --force is given — this is the
+ * explicit, discoverable alternative to burying a snapshot side effect inside
+ * `migrate`, which is meant to be re-run freely.
+ */
+async function handleLockAll(opts: { output?: string; force?: boolean }) {
+  if (opts.output) {
+    logError('--all writes one nemus.lock per workspace and cannot be combined with --output.');
+    process.exit(1);
+  }
+
+  const workspaces = await listWorkspaces(false);
+  if (workspaces.length === 0) {
+    logInfo('No workspaces found. Nothing to lock.');
+    return;
+  }
+
+  let written = 0;
+  let skipped = 0;
+  let errors = 0;
+
+  for (const ws of workspaces) {
+    const metadata = ws.metadata ?? (await loadMetadata(ws.path));
+    if (!metadata) {
+      logWarning(`  ${ws.name}: no metadata — skipped (run 'nemus migrate' first)`);
+      skipped++;
+      continue;
+    }
+
+    const outPath = path.join(ws.path, LOCK_FILENAME);
+    if (!opts.force && (await fileExists(outPath))) {
+      logInfo(`  ${colorize(ws.name, 'cyan')}: ${LOCK_FILENAME} already exists — skipped (use --force to overwrite)`);
+      skipped++;
+      continue;
+    }
+
+    try {
+      const lock = await buildLock(ws.path, metadata);
+      await writeLock(outPath, lock);
+      logSuccess(`  ${colorize(ws.name, 'cyan')}: wrote ${LOCK_FILENAME} (${lock.repositories.length} repos)`);
+      written++;
+    } catch (error) {
+      logError(`  ${ws.name}: ${error instanceof Error ? error.message : 'failed to write lockfile'}`);
+      errors++;
+    }
+  }
+
+  console.log('');
+  logInfo('Bulk lock complete:');
+  console.log(`  ${colorize(String(written), 'green')} written`);
+  if (skipped > 0) console.log(`  ${colorize(String(skipped), 'yellow')} skipped`);
+  if (errors > 0) console.log(`  ${colorize(String(errors), 'red')} errors`);
+}

package/src/commands/restore.ts

@@ -0,0 +1,219 @@
+import { Command } from 'commander';
+import { execFile } from 'child_process';
+import { promisify } from 'util';
+import * as path from 'path';
+import { getGlobalOpts } from '../utils/command-helpers';
+import { readLockFile, parseLock, reconstructRepo, LOCK_FILENAME, type WorkspaceLock, type LockRepo } from '../utils/workspace-lock';
+import { cloneRepositories, reportCloneResults } from '../utils/git-operations';
+import { warnIfGhqMissing } from '../utils/ghq-integration';
+import { createMetadata, saveMetadata } from '../utils/workspace-meta';
+import { generateClaudeContext } from '../utils/claude-integration';
+import { verifyGhAuth } from '../utils/github';
+import { validateWorkspaceName, checkWorkspaceExists, sanitizeWorkspaceName, resolveWorkspaceNameConflict, safeWorkspacePath } from '../utils/validation';
+import { logError, logInfo, logSuccess, logStep, logWarning } from '../utils/logger';
+import { colorize } from '../utils/colors';
+import { printBanner } from '../utils/banner';
+import type { CloneResult } from '../types';
+
+export interface RestoreResult {
+  workspaceName: string;
+  workspacePath: string;
+  results: CloneResult[];
+}
+
+const execFileAsync = promisify(execFile);
+const GIT_TIMEOUT = 30000;
+
+export function registerRestoreCommand(parent: Command) {
+  parent
+    .command('restore [lockfile]')
+    .description('Recreate a workspace from a nemus.lock (defaults to ./nemus.lock, "-" for stdin)')
+    .option('-w, --workspace <name>', 'Override the workspace name baked into the lockfile')
+    .option('--pin', 'Check out the exact recorded commit instead of the branch tip')
+    .action(async (lockfile, opts, cmd) => {
+      const globalOpts = getGlobalOpts(cmd);
+      await handleRestore({ lockfile, ...opts, ...globalOpts });
+    });
+}
+
+async function readStdin(): Promise<string> {
+  const chunks: Buffer[] = [];
+  for await (const chunk of process.stdin) chunks.push(chunk as Buffer);
+  return Buffer.concat(chunks).toString('utf-8');
+}
+
+// `branch`/`commit` come from an untrusted lockfile (already ref-validated in
+// parseLock); the `--end-of-options` guard is defense-in-depth so a ref can
+// never be reparsed as a git option even if validation is bypassed.
+/** Check out `branch` in a freshly-cloned repo, creating a tracking branch if needed. */
+async function checkoutBranch(repoPath: string, branch: string): Promise<boolean> {
+  try {
+    await execFileAsync('git', ['checkout', '--end-of-options', branch], { cwd: repoPath, timeout: GIT_TIMEOUT });
+    return true;
+  } catch {
+    try {
+      await execFileAsync('git', ['checkout', '-b', branch, '--end-of-options', `origin/${branch}`], { cwd: repoPath, timeout: GIT_TIMEOUT });
+      return true;
+    } catch {
+      return false;
+    }
+  }
+}
+
+async function checkoutCommit(repoPath: string, commit: string): Promise<boolean> {
+  try {
+    await execFileAsync('git', ['checkout', '--end-of-options', commit], { cwd: repoPath, timeout: GIT_TIMEOUT });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Core restore: clone every repo in a (already-validated) lock and check out the
+ * recorded branch (or the exact commit with `pin`), then write metadata + agent
+ * context — exactly like `create`. Throws on fatal errors (no process.exit) and
+ * logs progress via the logger (stderr), so both the CLI and the MCP tool can
+ * call it. Callers own presentation (final message, shell-CD hook).
+ */
+export async function restoreWorkspace(
+  lock: WorkspaceLock,
+  opts: { workspace?: string; pin?: boolean } = {}
+): Promise<RestoreResult> {
+  if (lock.repositories.length === 0) {
+    throw new Error('Lockfile has no repositories to restore');
+  }
+
+  // Resolve the target workspace name
+  let workspaceName = sanitizeWorkspaceName(opts.workspace || lock.workspace);
+  const nameError = validateWorkspaceName(workspaceName);
+  if (nameError !== true) {
+    throw new Error(typeof nameError === 'string' ? nameError : 'Invalid workspace name');
+  }
+  if (await checkWorkspaceExists(workspaceName)) {
+    const resolved = await resolveWorkspaceNameConflict(
+      workspaceName,
+      lock.repositories.map(r => r.directoryName)
+    );
+    logInfo(`Workspace "${workspaceName}" already exists — using "${colorize(resolved, 'cyan')}" instead.`);
+    workspaceName = resolved;
+  }
+
+  const workspacePath = safeWorkspacePath(workspaceName);
+  logInfo(`Restoring ${colorize(String(lock.repositories.length), 'cyan')} repos into workspace "${colorize(workspaceName, 'cyan')}"`);
+
+  // Clone every repo (reuses the create pipeline: ghq, concurrency, dedup)
+  logStep(1, 3, 'Cloning repositories...');
+  const { mkdir } = await import('fs/promises');
+  await mkdir(workspacePath, { recursive: true });
+  await warnIfGhqMissing();
+
+  const entries = lock.repositories.map(r => ({
+    repo: reconstructRepo(r),
+    directoryName: r.directoryName,
+  }));
+  const results = await cloneRepositories(entries, workspacePath);
+  reportCloneResults(results);
+
+  // Check out the recorded branch (or pinned commit) per repo
+  logStep(2, 3, opts.pin ? 'Checking out pinned commits...' : 'Checking out recorded branches...');
+  const byDir = new Map<string, LockRepo>(lock.repositories.map(r => [r.directoryName, r]));
+  for (const result of results) {
+    if (result.status !== 'success') continue;
+    const entry = byDir.get(result.directoryName);
+    if (!entry) continue;
+    const repoPath = path.join(workspacePath, result.directoryName);
+    const display = colorize(result.directoryName, 'cyan');
+
+    if (opts.pin && entry.commit) {
+      if (!(await checkoutCommit(repoPath, entry.commit))) {
+        logWarning(`${display}: could not check out pinned commit ${entry.commit} — left on the default branch`);
+      }
+    } else if (entry.branch) {
+      if (await checkoutBranch(repoPath, entry.branch)) {
+        logInfo(`${display} → ${entry.branch}`);
+      } else if (entry.commit && (await checkoutCommit(repoPath, entry.commit))) {
+        logWarning(`${display}: branch "${entry.branch}" not found — checked out commit ${entry.commit} instead`);
+      } else {
+        logWarning(`${display}: could not check out "${entry.branch}" — left on the default branch`);
+      }
+    } else if (entry.commit) {
+      // No branch was recorded (detached HEAD at lock time) — restore the commit
+      // so that state isn't silently lost even without --pin.
+      if (await checkoutCommit(repoPath, entry.commit)) {
+        logInfo(`${display} → ${entry.commit} (detached)`);
+      } else {
+        logWarning(`${display}: could not check out commit ${entry.commit} — left on the default branch`);
+      }
+    }
+  }
+
+  // Metadata + agent context (same as create)
+  logStep(3, 3, 'Saving workspace metadata...');
+  const metadata = createMetadata(workspaceName, results, { prompt: `Restored from ${LOCK_FILENAME}` });
+  await saveMetadata(workspacePath, metadata);
+
+  const successfulRepos = results.filter(r => r.status === 'success').map(r => r.repo);
+  if (successfulRepos.length > 0) {
+    await generateClaudeContext(workspacePath, workspaceName, successfulRepos, metadata);
+  }
+
+  return { workspaceName, workspacePath, results };
+}
+
+async function handleRestore(opts: {
+  lockfile?: string;
+  workspace?: string;
+  pin?: boolean;
+  yes: boolean;
+}) {
+  printBanner();
+
+  try {
+    // Step 1: Load + validate the lockfile
+    let lock: WorkspaceLock;
+    if (opts.lockfile === '-') {
+      lock = parseLock(await readStdin());
+    } else {
+      const lockPath = path.resolve(opts.lockfile || LOCK_FILENAME);
+      try {
+        lock = await readLockFile(lockPath);
+      } catch (error) {
+        logError(`Could not read lockfile at ${lockPath}`);
+        if (error instanceof Error) logError(error.message);
+        logInfo('Pass a path (nemus restore path/to/nemus.lock) or pipe one with: nemus restore -');
+        process.exit(1);
+      }
+    }
+
+    if (lock.repositories.length === 0) {
+      logError('Lockfile has no repositories to restore');
+      process.exit(1);
+    }
+
+    // gh auth (soft — private repos need it, public/other creds may not)
+    if (!(await verifyGhAuth())) {
+      logWarning('GitHub CLI not authenticated — private repositories may fail to clone.');
+    }
+
+    const { workspaceName, workspacePath } = await restoreWorkspace(lock, {
+      workspace: opts.workspace,
+      pin: opts.pin,
+    });
+
+    logSuccess(`Workspace "${colorize(workspaceName, 'cyan')}" restored!`);
+
+    // Shell-integration auto-CD (same hook create uses)
+    try {
+      const { writeFile } = await import('fs/promises');
+      const os = await import('os');
+      await writeFile(path.join(os.homedir(), '.workspace-last-created'), workspacePath, 'utf-8');
+    } catch {
+      // non-critical
+    }
+  } catch (error) {
+    logError('Failed to restore workspace');
+    if (error instanceof Error) logError(error.message);
+    process.exit(1);
+  }
+}

package/src/mcp/server.ts

@@ -41,6 +41,8 @@ import {
   handleSuiteImport,
   handleSuiteUse,
   handleSaveContext,
+  handleLockWorkspace,
+  handleRestoreWorkspace,
 } from './tools';
 
 import { getPackageVersion } from '../utils/config';
@@ -567,6 +569,44 @@ server.tool(
   }
 );
 
+server.tool(
+  'lock-workspace',
+  'Snapshot a workspace into a committable nemus.lock manifest (repos + owner + the branch each repo is on + its HEAD commit) so it can be shared and recreated elsewhere with restore-workspace. Writes nemus.lock to the workspace root by default and returns the manifest.',
+  {
+    workspace: wsName.describe('Name of the workspace to lock'),
+    output: z.string().optional().describe('Optional path to write the lockfile to instead of <workspace>/nemus.lock'),
+  },
+  async ({ workspace, output }) => {
+    try {
+      const result = await handleLockWorkspace(workspace, output);
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : 'Unknown error';
+      return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    }
+  }
+);
+
+server.tool(
+  'restore-workspace',
+  'Recreate a workspace from a nemus.lock manifest: clone every repo and check out the recorded branch (or the exact commit with pin). Provide the manifest inline via lockContent, or a path via lockfile (defaults to ./nemus.lock).',
+  {
+    lockContent: z.string().optional().describe('The nemus.lock manifest JSON, inline (preferred for agents)'),
+    lockfile: z.string().optional().describe('Path to a nemus.lock file (used when lockContent is not given; defaults to ./nemus.lock)'),
+    workspace: wsName.optional().describe('Override the workspace name baked into the lockfile'),
+    pin: z.boolean().optional().describe('Check out the exact recorded commit instead of the branch tip'),
+  },
+  async ({ lockContent, lockfile, workspace, pin }) => {
+    try {
+      const result = await handleRestoreWorkspace({ lockContent, lockfile, workspace, pin });
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (error) {
+      const msg = error instanceof Error ? error.message : 'Unknown error';
+      return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
+    }
+  }
+);
+
 async function main() {
   const transport = new StdioServerTransport();
   await server.connect(transport);