@nemus-cli/nemus 0.15.1 → 0.16.0

package/CHANGELOG.md

@@ -7,6 +7,51 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [0.16.0] - 2026-09-09
+
+### Added
+
+- **Portable workspaces: `nemus lock` & `nemus restore`.** `nemus lock` writes a
+  small, committable `nemus.lock` capturing every repo (owner, directory, clone
+  URL), the branch each repo is currently on, and its HEAD commit; `-o <file>`
+  writes elsewhere and `-o -` prints it to stdout. `nemus restore` recreates the
+  workspace from a lockfile (defaults to `./nemus.lock`, or `-` for stdin) on any
+  machine — it clones every repo and checks out the recorded branch, then writes
+  metadata + agent context exactly like `create`. `--pin` checks out the exact
+  recorded commit instead of the branch tip, and `-w/--workspace` overrides the
+  name baked into the lockfile. `nemus lock --all` drops a lockfile into every
+  workspace at once (skipping existing ones unless `--force`) — the explicit way
+  to make a whole machine portable, rather than a hidden side effect in
+  `migrate`. The MCP server gains matching `lock-workspace` / `restore-workspace`
+  tools (restore accepts the manifest inline via `lockContent`) so agents have
+  the same portability as `create`/`update`/`delete`. Restore rebuilds https/ssh URLs for the
+  restorer's `cloneProtocol` from the locked host+owner+name (falling back to the
+  stored URL), so an ssh-locked workspace restores fine for an https user. The
+  lockfile holds only what `git remote -v` already exposes — no secrets — so it's
+  safe to commit. Unlike a local `snapshot` (time-travel within an existing
+  workspace) or a `suite` (reusable repo template), a lockfile pins one
+  workspace's exact repos + branch state and recreates it from nothing.
+
+## [0.15.2] - 2026-09-04
+
+### Fixed
+
+- **First-run setup now runs for global installs via yarn and pnpm too — without
+  re-introducing the hang for their transient runners.** 0.15.1 gated postinstall
+  setup on `npm_config_global`, which only npm sets, so `yarn global add` /
+  `pnpm add -g` silently skipped `configure` + shell integration (the auto-cd /
+  `nemgo` feature). The gate now classifies the install context: it recognizes a
+  global yarn/pnpm install from `npm_config_user_agent`, but detects transient
+  one-off runners (`npx`, `pnpm dlx`, `yarn dlx`) by the per-run cache path they
+  stage into (`.../_npx/...`, `.../dlx/...`, the OS temp dir, with the macOS
+  `/private` symlink normalized) — because `pnpm dlx`/`yarn dlx` set *neither*
+  `npm_command` *nor* `npm_config_global`, so a user-agent check alone would
+  misclassify them as a global install. Hang-safety itself comes from a separate
+  guard — the interactive `configure` only fires for a confirmed npm `-g`
+  install, so yarn/pnpm globals get the non-interactive shell integration plus a
+  hint and can never hang; the transient path detection's job is to stop a
+  throwaway `dlx` run from spuriously writing the shell RC. (#92)
+
 ## [0.15.1] - 2026-09-04
 
 ### Fixed

package/README.md

@@ -354,6 +354,34 @@ nemus snapshot save ws        # (ss) capture exact branches/commits/dirty state
 nemus snapshot restore <id>   # (sr)
 ```
 
+### Portable workspaces — `lock` & `restore`
+
+Share the *exact* workspace you're in. `nemus lock` writes a small, committable
+`nemus.lock` (repos + owner + the branch each repo is on + its HEAD commit);
+`nemus restore` recreates that workspace from scratch on any machine — clones
+every repo and checks out the recorded branch.
+
+```bash
+nemus lock                    # write ./nemus.lock for the current workspace
+nemus lock my-ws -o my-ws.lock   # or a named workspace, to a file
+nemus lock my-ws -o -            # print the lockfile to stdout (pipe it anywhere)
+nemus lock --all [--force]     # drop a nemus.lock into every workspace at once
+
+nemus restore                 # recreate from ./nemus.lock
+nemus restore my-ws.lock       # from a specific file (or `-` to read stdin)
+nemus restore my-ws.lock -w exp --pin   # new name; pin exact commits, not branch tips
+```
+
+Commit `nemus.lock` next to a design doc or drop it in a ticket, and a teammate
+runs `nemus restore` to land in the identical multi-repo setup. It contains only
+what `git remote -v` already exposes — no secrets — so it's safe to commit.
+
+> **`lock`/`restore` vs. `snapshot`:** a *snapshot* is local time-travel for a
+> workspace that already exists on your machine; `lock`/`restore` is portable —
+> it recreates the workspace (repos and all) from nothing, on any machine.
+> **vs. `suite`:** a *suite* is a reusable repo *template*; a lockfile pins one
+> workspace's *exact* repos and branch state.
+
 ### Reflect — improve your setup over time
 
 ```bash

package/dist/commands/lock.js

@@ -0,0 +1,148 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerLockCommand = registerLockCommand;
+const path = __importStar(require("path"));
+const fs = __importStar(require("fs/promises"));
+const config_1 = require("../utils/config");
+const workspace_meta_1 = require("../utils/workspace-meta");
+const command_helpers_1 = require("../utils/command-helpers");
+const workspace_lock_1 = require("../utils/workspace-lock");
+const logger_1 = require("../utils/logger");
+const colors_1 = require("../utils/colors");
+function registerLockCommand(parent) {
+    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 = (0, command_helpers_1.getGlobalOpts)(cmd);
+        await handleLock({ workspace, ...opts, ...globalOpts });
+    });
+}
+async function fileExists(p) {
+    try {
+        await fs.access(p);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function handleLock(opts) {
+    if (opts.all) {
+        await handleLockAll(opts);
+        return;
+    }
+    try {
+        const workspaceName = await (0, command_helpers_1.resolveWorkspace)(opts.workspace);
+        const workspacePath = path.join(config_1.WORKSPACES_DIR, workspaceName);
+        const metadata = await (0, workspace_meta_1.loadMetadata)(workspacePath);
+        if (!metadata) {
+            (0, logger_1.logError)(`Workspace not found: ${workspaceName}`);
+            process.exit(1);
+        }
+        const lock = await (0, workspace_lock_1.buildLock)(workspacePath, metadata);
+        // `-o -`: emit only the lockfile JSON so it can be piped/redirected cleanly.
+        if (opts.output === '-') {
+            process.stdout.write((0, workspace_lock_1.serializeLock)(lock));
+            return;
+        }
+        const outPath = opts.output
+            ? path.resolve(opts.output)
+            : path.join(workspacePath, workspace_lock_1.LOCK_FILENAME);
+        await (0, workspace_lock_1.writeLock)(outPath, lock);
+        (0, logger_1.logSuccess)(`Wrote ${(0, colors_1.colorize)(workspace_lock_1.LOCK_FILENAME, 'cyan')} (${lock.repositories.length} repos) → ${outPath}`);
+        (0, logger_1.logInfo)('Commit or share it, then recreate the workspace with: nemus restore');
+    }
+    catch (error) {
+        (0, logger_1.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) {
+    if (opts.output) {
+        (0, logger_1.logError)('--all writes one nemus.lock per workspace and cannot be combined with --output.');
+        process.exit(1);
+    }
+    const workspaces = await (0, workspace_meta_1.listWorkspaces)(false);
+    if (workspaces.length === 0) {
+        (0, logger_1.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 (0, workspace_meta_1.loadMetadata)(ws.path));
+        if (!metadata) {
+            (0, logger_1.logWarning)(`  ${ws.name}: no metadata — skipped (run 'nemus migrate' first)`);
+            skipped++;
+            continue;
+        }
+        const outPath = path.join(ws.path, workspace_lock_1.LOCK_FILENAME);
+        if (!opts.force && (await fileExists(outPath))) {
+            (0, logger_1.logInfo)(`  ${(0, colors_1.colorize)(ws.name, 'cyan')}: ${workspace_lock_1.LOCK_FILENAME} already exists — skipped (use --force to overwrite)`);
+            skipped++;
+            continue;
+        }
+        try {
+            const lock = await (0, workspace_lock_1.buildLock)(ws.path, metadata);
+            await (0, workspace_lock_1.writeLock)(outPath, lock);
+            (0, logger_1.logSuccess)(`  ${(0, colors_1.colorize)(ws.name, 'cyan')}: wrote ${workspace_lock_1.LOCK_FILENAME} (${lock.repositories.length} repos)`);
+            written++;
+        }
+        catch (error) {
+            (0, logger_1.logError)(`  ${ws.name}: ${error instanceof Error ? error.message : 'failed to write lockfile'}`);
+            errors++;
+        }
+    }
+    console.log('');
+    (0, logger_1.logInfo)('Bulk lock complete:');
+    console.log(`  ${(0, colors_1.colorize)(String(written), 'green')} written`);
+    if (skipped > 0)
+        console.log(`  ${(0, colors_1.colorize)(String(skipped), 'yellow')} skipped`);
+    if (errors > 0)
+        console.log(`  ${(0, colors_1.colorize)(String(errors), 'red')} errors`);
+}

package/dist/commands/restore.js

@@ -0,0 +1,232 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.registerRestoreCommand = registerRestoreCommand;
+exports.restoreWorkspace = restoreWorkspace;
+const child_process_1 = require("child_process");
+const util_1 = require("util");
+const path = __importStar(require("path"));
+const command_helpers_1 = require("../utils/command-helpers");
+const workspace_lock_1 = require("../utils/workspace-lock");
+const git_operations_1 = require("../utils/git-operations");
+const ghq_integration_1 = require("../utils/ghq-integration");
+const workspace_meta_1 = require("../utils/workspace-meta");
+const claude_integration_1 = require("../utils/claude-integration");
+const github_1 = require("../utils/github");
+const validation_1 = require("../utils/validation");
+const logger_1 = require("../utils/logger");
+const colors_1 = require("../utils/colors");
+const banner_1 = require("../utils/banner");
+const execFileAsync = (0, util_1.promisify)(child_process_1.execFile);
+const GIT_TIMEOUT = 30000;
+function registerRestoreCommand(parent) {
+    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 = (0, command_helpers_1.getGlobalOpts)(cmd);
+        await handleRestore({ lockfile, ...opts, ...globalOpts });
+    });
+}
+async function readStdin() {
+    const chunks = [];
+    for await (const chunk of process.stdin)
+        chunks.push(chunk);
+    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, branch) {
+    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, commit) {
+    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).
+ */
+async function restoreWorkspace(lock, opts = {}) {
+    if (lock.repositories.length === 0) {
+        throw new Error('Lockfile has no repositories to restore');
+    }
+    // Resolve the target workspace name
+    let workspaceName = (0, validation_1.sanitizeWorkspaceName)(opts.workspace || lock.workspace);
+    const nameError = (0, validation_1.validateWorkspaceName)(workspaceName);
+    if (nameError !== true) {
+        throw new Error(typeof nameError === 'string' ? nameError : 'Invalid workspace name');
+    }
+    if (await (0, validation_1.checkWorkspaceExists)(workspaceName)) {
+        const resolved = await (0, validation_1.resolveWorkspaceNameConflict)(workspaceName, lock.repositories.map(r => r.directoryName));
+        (0, logger_1.logInfo)(`Workspace "${workspaceName}" already exists — using "${(0, colors_1.colorize)(resolved, 'cyan')}" instead.`);
+        workspaceName = resolved;
+    }
+    const workspacePath = (0, validation_1.safeWorkspacePath)(workspaceName);
+    (0, logger_1.logInfo)(`Restoring ${(0, colors_1.colorize)(String(lock.repositories.length), 'cyan')} repos into workspace "${(0, colors_1.colorize)(workspaceName, 'cyan')}"`);
+    // Clone every repo (reuses the create pipeline: ghq, concurrency, dedup)
+    (0, logger_1.logStep)(1, 3, 'Cloning repositories...');
+    const { mkdir } = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+    await mkdir(workspacePath, { recursive: true });
+    await (0, ghq_integration_1.warnIfGhqMissing)();
+    const entries = lock.repositories.map(r => ({
+        repo: (0, workspace_lock_1.reconstructRepo)(r),
+        directoryName: r.directoryName,
+    }));
+    const results = await (0, git_operations_1.cloneRepositories)(entries, workspacePath);
+    (0, git_operations_1.reportCloneResults)(results);
+    // Check out the recorded branch (or pinned commit) per repo
+    (0, logger_1.logStep)(2, 3, opts.pin ? 'Checking out pinned commits...' : 'Checking out recorded branches...');
+    const byDir = new Map(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 = (0, colors_1.colorize)(result.directoryName, 'cyan');
+        if (opts.pin && entry.commit) {
+            if (!(await checkoutCommit(repoPath, entry.commit))) {
+                (0, logger_1.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)) {
+                (0, logger_1.logInfo)(`${display} → ${entry.branch}`);
+            }
+            else if (entry.commit && (await checkoutCommit(repoPath, entry.commit))) {
+                (0, logger_1.logWarning)(`${display}: branch "${entry.branch}" not found — checked out commit ${entry.commit} instead`);
+            }
+            else {
+                (0, logger_1.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)) {
+                (0, logger_1.logInfo)(`${display} → ${entry.commit} (detached)`);
+            }
+            else {
+                (0, logger_1.logWarning)(`${display}: could not check out commit ${entry.commit} — left on the default branch`);
+            }
+        }
+    }
+    // Metadata + agent context (same as create)
+    (0, logger_1.logStep)(3, 3, 'Saving workspace metadata...');
+    const metadata = (0, workspace_meta_1.createMetadata)(workspaceName, results, { prompt: `Restored from ${workspace_lock_1.LOCK_FILENAME}` });
+    await (0, workspace_meta_1.saveMetadata)(workspacePath, metadata);
+    const successfulRepos = results.filter(r => r.status === 'success').map(r => r.repo);
+    if (successfulRepos.length > 0) {
+        await (0, claude_integration_1.generateClaudeContext)(workspacePath, workspaceName, successfulRepos, metadata);
+    }
+    return { workspaceName, workspacePath, results };
+}
+async function handleRestore(opts) {
+    (0, banner_1.printBanner)();
+    try {
+        // Step 1: Load + validate the lockfile
+        let lock;
+        if (opts.lockfile === '-') {
+            lock = (0, workspace_lock_1.parseLock)(await readStdin());
+        }
+        else {
+            const lockPath = path.resolve(opts.lockfile || workspace_lock_1.LOCK_FILENAME);
+            try {
+                lock = await (0, workspace_lock_1.readLockFile)(lockPath);
+            }
+            catch (error) {
+                (0, logger_1.logError)(`Could not read lockfile at ${lockPath}`);
+                if (error instanceof Error)
+                    (0, logger_1.logError)(error.message);
+                (0, logger_1.logInfo)('Pass a path (nemus restore path/to/nemus.lock) or pipe one with: nemus restore -');
+                process.exit(1);
+            }
+        }
+        if (lock.repositories.length === 0) {
+            (0, logger_1.logError)('Lockfile has no repositories to restore');
+            process.exit(1);
+        }
+        // gh auth (soft — private repos need it, public/other creds may not)
+        if (!(await (0, github_1.verifyGhAuth)())) {
+            (0, logger_1.logWarning)('GitHub CLI not authenticated — private repositories may fail to clone.');
+        }
+        const { workspaceName, workspacePath } = await restoreWorkspace(lock, {
+            workspace: opts.workspace,
+            pin: opts.pin,
+        });
+        (0, logger_1.logSuccess)(`Workspace "${(0, colors_1.colorize)(workspaceName, 'cyan')}" restored!`);
+        // Shell-integration auto-CD (same hook create uses)
+        try {
+            const { writeFile } = await Promise.resolve().then(() => __importStar(require('fs/promises')));
+            const os = await Promise.resolve().then(() => __importStar(require('os')));
+            await writeFile(path.join(os.homedir(), '.workspace-last-created'), workspacePath, 'utf-8');
+        }
+        catch {
+            // non-critical
+        }
+    }
+    catch (error) {
+        (0, logger_1.logError)('Failed to restore workspace');
+        if (error instanceof Error)
+            (0, logger_1.logError)(error.message);
+        process.exit(1);
+    }
+}

package/dist/mcp/server.js

@@ -387,6 +387,34 @@ server.tool('save-context', 'Save a progress summary to the workspace. Use this
         return { content: [{ type: 'text', text: `Error: ${msg}` }], isError: true };
     }
 });
+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: zod_1.z.string().optional().describe('Optional path to write the lockfile to instead of <workspace>/nemus.lock'),
+}, async ({ workspace, output }) => {
+    try {
+        const result = await (0, tools_1.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: zod_1.z.string().optional().describe('The nemus.lock manifest JSON, inline (preferred for agents)'),
+    lockfile: zod_1.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: zod_1.z.boolean().optional().describe('Check out the exact recorded commit instead of the branch tip'),
+}, async ({ lockContent, lockfile, workspace, pin }) => {
+    try {
+        const result = await (0, tools_1.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 stdio_js_1.StdioServerTransport();
     await server.connect(transport);

package/dist/mcp/tools.js

@@ -65,6 +65,8 @@ exports.handleSuiteExport = handleSuiteExport;
 exports.handleSuiteImport = handleSuiteImport;
 exports.handleSuiteUse = handleSuiteUse;
 exports.handleSaveContext = handleSaveContext;
+exports.handleLockWorkspace = handleLockWorkspace;
+exports.handleRestoreWorkspace = handleRestoreWorkspace;
 const fs = __importStar(require("fs/promises"));
 const path = __importStar(require("path"));
 const os = __importStar(require("os"));
@@ -87,6 +89,8 @@ const branch_operations_1 = require("../utils/branch-operations");
 const cleanup_operations_1 = require("../utils/cleanup-operations");
 const hooks_1 = require("../utils/hooks");
 const validation_1 = require("../utils/validation");
+const workspace_lock_1 = require("../utils/workspace-lock");
+const restore_1 = require("../commands/restore");
 /**
  * Redirects stdout to stderr for the duration of a function call.
  * MCP uses stdout exclusively for JSON-RPC, so any console.log from
@@ -920,3 +924,60 @@ async function handleSaveContext(workspace, content, append) {
         };
     });
 }
+// ── Portable workspaces: lock / restore ─────────────────────────────────────
+/**
+ * Snapshot a workspace into a nemus.lock manifest (repos + branch + commit).
+ * Writes it to the workspace root by default and also returns the manifest so
+ * an agent can share/commit it.
+ */
+async function handleLockWorkspace(workspace, output) {
+    return withStdoutProtection(async () => {
+        if (!workspace || workspace.trim().length === 0) {
+            throw new Error('Workspace name is required');
+        }
+        const workspacePath = (0, validation_1.safeWorkspacePath)((0, validation_1.sanitizeWorkspaceName)(workspace));
+        const metadata = await (0, workspace_meta_1.loadMetadata)(workspacePath);
+        if (!metadata) {
+            throw new Error(`Workspace not found: ${workspace}`);
+        }
+        const lock = await (0, workspace_lock_1.buildLock)(workspacePath, metadata);
+        const outPath = output ? path.resolve(output) : path.join(workspacePath, workspace_lock_1.LOCK_FILENAME);
+        await (0, workspace_lock_1.writeLock)(outPath, lock);
+        return {
+            workspace: metadata.workspaceName,
+            lockfilePath: outPath,
+            repoCount: lock.repositories.length,
+            lock,
+        };
+    });
+}
+/**
+ * Recreate a workspace from a nemus.lock. Accepts either inline `lockContent`
+ * (the manifest JSON) or a `lockfile` path (defaults to ./nemus.lock). Clones
+ * every repo and checks out the recorded branch (or exact commit with `pin`).
+ */
+async function handleRestoreWorkspace(opts) {
+    return withStdoutProtection(async () => {
+        const lock = opts.lockContent
+            ? (0, workspace_lock_1.parseLock)(opts.lockContent)
+            : await (0, workspace_lock_1.readLockFile)(path.resolve(opts.lockfile || workspace_lock_1.LOCK_FILENAME));
+        const { workspaceName, workspacePath, results } = await (0, restore_1.restoreWorkspace)(lock, {
+            workspace: opts.workspace,
+            pin: opts.pin,
+        });
+        const cloned = results.filter(r => r.status === 'success');
+        const failed = results.filter(r => r.status === 'failed');
+        return {
+            workspace: workspaceName,
+            path: workspacePath,
+            cloned: cloned.length,
+            failed: failed.length,
+            repositories: results.map(r => ({
+                name: r.repo.name,
+                directoryName: r.directoryName,
+                status: r.status,
+                ...(r.error ? { error: r.error } : {}),
+            })),
+        };
+    });
+}

package/dist/program.js

@@ -95,6 +95,8 @@ const migrate_1 = require("./commands/migrate");
 const report_bug_1 = require("./commands/report-bug");
 const completion_1 = require("./commands/completion");
 const reflect_1 = require("./commands/reflect");
+const lock_1 = require("./commands/lock");
+const restore_1 = require("./commands/restore");
 (0, create_1.registerCreateCommand)(exports.program);
 (0, list_1.registerListCommand)(exports.program);
 (0, update_1.registerUpdateCommand)(exports.program);
@@ -122,6 +124,8 @@ const reflect_1 = require("./commands/reflect");
 (0, report_bug_1.registerReportBugCommand)(exports.program);
 (0, completion_1.registerCompletionCommand)(exports.program);
 (0, reflect_1.registerReflectCommand)(exports.program);
+(0, lock_1.registerLockCommand)(exports.program);
+(0, restore_1.registerRestoreCommand)(exports.program);
 // Register TUI (delegates to existing Ink/React implementation)
 exports.program
     .command('tui')