open-research-protocol 0.4.19 → 0.4.21

package/packages/orp-workspace-launcher/README.md

@@ -1,6 +1,6 @@
 # orp-workspace-launcher
 
-Manage a durable ORP workspace ledger of project paths plus saved `codex resume ...` or `claude --resume ...` commands.
+Manage a durable ORP workspace ledger of project paths plus saved `codex resume ...` or `claude --resume ...` commands, optional remote git URLs, bootstrap commands, and per-machine workspace identity.
 
 The package no longer automates iTerm or Terminal.app. The workspace ledger is the source of truth, and you use Terminal however you want.
 
@@ -11,6 +11,7 @@ Create a local workspace ledger with no hosted account required:
 ```bash
 orp workspace create main-cody-1
 orp workspace create research-lab --path /absolute/path/to/research-lab --resume-tool claude --resume-session-id 469d99b2-2997-42bf-a8f5-3812c808ef29
+orp workspace create mac-main --machine-label "Mac Studio" --path /absolute/path/to/orp --remote-url git@github.com:SproutSeeds/orp.git --bootstrap-command "npm install"
 ```
 
 Inspect the saved ledger:
@@ -32,6 +33,7 @@ Add a new saved tab manually:
 ```bash
 orp workspace ledger add main --path /absolute/path/to/frg-site --resume-command "codex resume 019d348d-5031-78e1-9840-a66deaac33ae"
 orp workspace add-tab main --path /absolute/path/to/anthropic-lab --resume-tool claude --resume-session-id claude-456
+orp workspace add-tab main --path /absolute/path/to/orp-web-app --remote-url git@github.com:SproutSeeds/orp-web-app.git --bootstrap-command "pnpm install"
 ```
 
 Remove a saved tab manually:
@@ -75,8 +77,24 @@ orp workspace slot set offhand research-lab
 - `--orp-command <path-or-command>`: override the ORP CLI binary used to fetch hosted idea JSON
 - `--path <absolute-path>`: add or match a saved project path
 - `--title <text>`: set or match a saved tab title
+- `--remote-url <git-url>`: remember where to clone the repo on another machine
+- `--remote-branch <branch>`: remember the branch to clone by default
+- `--bootstrap-command <text>`: remember the setup command for another machine, like `npm install`, `pnpm install`, or `uv sync`
 - `--resume-command <text>`: save or match an exact `codex resume ...` or `claude --resume ...` command
 - `--resume-tool <codex|claude>`: build or narrow the resume command by tool
 - `--resume-session-id <id>`: build or match a specific session id
 - `--index <n>`: remove a saved tab by 1-based index
 - `--all`: remove every matching saved tab
+
+## Cross-machine idea
+
+The local `path` is still the machine-specific working directory. The optional `remoteUrl`, `remoteBranch`, and `bootstrapCommand` fields are the portable part that an agent or user can carry to another rig.
+
+That means one workspace can remember:
+
+- where the repo lives on this machine
+- which git remote should be cloned on the next machine
+- which setup command should be run after clone
+- which `codex resume ...` or `claude --resume ...` line is valid on this machine
+
+Resume session ids are still machine-local/runtime-local. The remote and bootstrap metadata are what make the ledger portable.

package/packages/orp-workspace-launcher/src/core-plan.js

@@ -64,6 +64,41 @@ function normalizeOptionalString(value) {
   return trimmed.length > 0 ? trimmed : null;
 }
 
+function normalizeOptionalCommand(value) {
+  return normalizeOptionalString(value);
+}
+
+function normalizeOptionalUrl(value, label) {
+  const normalized = normalizeOptionalString(value);
+  if (!normalized) {
+    return null;
+  }
+  if (/^[a-z][a-z0-9+.-]*:\/\//i.test(normalized) || /^[^@\s]+@[^:\s]+:[^\s]+$/i.test(normalized)) {
+    return normalized;
+  }
+  throw new Error(`${label} must look like a git remote URL`);
+}
+
+function normalizeMachineMetadata(rawMachine) {
+  if (rawMachine == null) {
+    return null;
+  }
+  if (!rawMachine || typeof rawMachine !== "object" || Array.isArray(rawMachine)) {
+    throw new Error("workspace manifest machine metadata must be an object");
+  }
+
+  const machine = Object.fromEntries(
+    Object.entries({
+      machineId: normalizeOptionalString(rawMachine.machineId),
+      machineLabel: normalizeOptionalString(rawMachine.machineLabel),
+      platform: normalizeOptionalString(rawMachine.platform),
+      host: normalizeOptionalString(rawMachine.host),
+    }).filter(([, value]) => value != null),
+  );
+
+  return Object.keys(machine).length > 0 ? machine : null;
+}
+
 function normalizeResumeTool(value) {
   const trimmed = normalizeOptionalString(value)?.toLowerCase() || null;
   return trimmed && SUPPORTED_RESUME_TOOLS.has(trimmed) ? trimmed : null;
@@ -241,6 +276,9 @@ function normalizeStructuredTab(rawTab, index) {
     resumeTool: resume.resumeTool,
     title,
     tmuxSessionName,
+    remoteUrl: normalizeOptionalUrl(rawTab.remoteUrl, `workspace tab ${index + 1} remoteUrl`),
+    remoteBranch: normalizeOptionalString(rawTab.remoteBranch),
+    bootstrapCommand: normalizeOptionalCommand(rawTab.bootstrapCommand),
   };
 }
 
@@ -254,8 +292,8 @@ export function normalizeWorkspaceManifest(rawManifest) {
     throw new Error(`unsupported workspace manifest version: ${version}`);
   }
 
-  if (!Array.isArray(rawManifest.tabs) || rawManifest.tabs.length === 0) {
-    throw new Error("workspace manifest must include a non-empty tabs array");
+  if (!Array.isArray(rawManifest.tabs)) {
+    throw new Error("workspace manifest must include a tabs array");
   }
 
   const tabs = rawManifest.tabs.map((tab, index) => normalizeStructuredTab(tab, index));
@@ -264,6 +302,7 @@ export function normalizeWorkspaceManifest(rawManifest) {
     workspaceId: normalizeOptionalString(rawManifest.workspaceId),
     title: normalizeOptionalString(rawManifest.title),
     tmuxPrefix: normalizeOptionalString(rawManifest.tmuxPrefix),
+    machine: normalizeMachineMetadata(rawManifest.machine),
     capture: normalizeCaptureMetadata(rawManifest.capture),
     tabs,
   };
@@ -401,6 +440,37 @@ export function buildDirectCommand(entry, options = {}) {
   return commands.join(" && ");
 }
 
+export function buildCloneCommand(entry, options = {}) {
+  const remoteUrl = normalizeOptionalUrl(entry?.remoteUrl, "workspace tab remoteUrl");
+  if (!remoteUrl) {
+    return null;
+  }
+  const repoDir = options.repoDir || path.basename(normalizeDisplayPath(entry.path));
+  const branch = normalizeOptionalString(entry?.remoteBranch);
+  const parts = ["git", "clone"];
+  if (branch) {
+    parts.push("--branch", shellQuote(branch));
+  }
+  parts.push(shellQuote(remoteUrl));
+  if (repoDir) {
+    parts.push(shellQuote(repoDir));
+  }
+  return parts.join(" ");
+}
+
+export function buildSetupCommand(entry, options = {}) {
+  const cloneCommand = buildCloneCommand(entry, options);
+  const bootstrapCommand = normalizeOptionalCommand(entry?.bootstrapCommand);
+  if (!cloneCommand && !bootstrapCommand) {
+    return null;
+  }
+  if (cloneCommand && bootstrapCommand) {
+    const repoDir = options.repoDir || path.basename(normalizeDisplayPath(entry.path));
+    return `${cloneCommand} && cd ${shellQuote(repoDir)} && ${bootstrapCommand}`;
+  }
+  return cloneCommand || bootstrapCommand;
+}
+
 export function buildTmuxPresentationCommands(entry, options = {}) {
   const sessionName = options.sessionName || deriveTmuxSessionName(entry, options);
   const quotedSession = shellQuote(sessionName);

package/packages/orp-workspace-launcher/src/hosted-state.js

@@ -59,6 +59,9 @@ function normalizePreviousHostedTabs(workspace) {
       tabId: normalizeOptionalString(tab.tab_id ?? tab.tabId),
       title: normalizeOptionalString(tab.title),
       path: normalizeOptionalString(tab.project_root ?? tab.projectRoot),
+      remoteUrl: normalizeOptionalString(tab.remote_url ?? tab.remoteUrl),
+      remoteBranch: normalizeOptionalString(tab.remote_branch ?? tab.remoteBranch),
+      bootstrapCommand: normalizeOptionalString(tab.bootstrap_command ?? tab.bootstrapCommand),
       repoLabel: normalizeOptionalString(tab.repo_label ?? tab.repoLabel),
       terminalTitle: normalizeOptionalString(tab.terminal_title ?? tab.terminalTitle),
       resumeCommand: resume.resumeCommand,
@@ -149,6 +152,9 @@ export function buildHostedWorkspaceState(manifest, options = {}) {
         order_index: index,
         title: title || undefined,
         project_root: projectRoot,
+        remote_url: normalizeOptionalString(tab.remoteUrl) || previous?.remoteUrl || undefined,
+        remote_branch: normalizeOptionalString(tab.remoteBranch) || previous?.remoteBranch || undefined,
+        bootstrap_command: normalizeOptionalString(tab.bootstrapCommand) || previous?.bootstrapCommand || undefined,
         repo_label: repoLabel || undefined,
         resume_command: resumeCommand,
         resume_tool: resumeTool,
@@ -172,6 +178,9 @@ export function buildHostedWorkspaceState(manifest, options = {}) {
       source_app: "terminal-ledger",
       mode: "manual",
       host: os.hostname(),
+      machine_id: normalizeOptionalString(manifest.machine?.machineId) || undefined,
+      machine_label: normalizeOptionalString(manifest.machine?.machineLabel) || undefined,
+      platform: normalizeOptionalString(manifest.machine?.platform) || process.platform,
       terminal_frontend: "terminal",
       durable_backend: options.durableBackend || "manual-ledger",
     }).filter(([, value]) => value !== undefined && value !== null),

package/packages/orp-workspace-launcher/src/index.js

@@ -1,6 +1,8 @@
 export {
+  buildCloneCommand,
   buildDirectCommand,
   buildLaunchPlan,
+  buildSetupCommand,
   getResumeCommand,
   deriveBaseTitle,
   deriveWorkspaceId,

package/packages/orp-workspace-launcher/src/ledger.js

@@ -1,4 +1,5 @@
 import fs from "node:fs/promises";
+import os from "node:os";
 import path from "node:path";
 import process from "node:process";
 
@@ -36,6 +37,16 @@ function normalizeOptionalString(value) {
   return trimmed.length > 0 ? trimmed : null;
 }
 
+function buildCurrentMachineMetadata(options = {}) {
+  const machineId = normalizeOptionalString(options.machineId) || `${os.hostname().trim() || "machine"}:${process.platform}`;
+  return {
+    machineId,
+    machineLabel: normalizeOptionalString(options.machineLabel) || os.hostname().trim() || "This Machine",
+    platform: normalizeOptionalString(options.platform) || process.platform,
+    host: os.hostname().trim() || undefined,
+  };
+}
+
 function validateAbsolutePath(value, label) {
   const normalized = normalizeOptionalString(value);
   if (!normalized || !normalized.startsWith("/")) {
@@ -65,6 +76,9 @@ function materializeWorkspaceTab(tab) {
     Object.entries({
       title: normalizeOptionalString(tab.title) || undefined,
       path: tab.path,
+      remoteUrl: normalizeOptionalString(tab.remoteUrl) || undefined,
+      remoteBranch: normalizeOptionalString(tab.remoteBranch) || undefined,
+      bootstrapCommand: normalizeOptionalString(tab.bootstrapCommand) || undefined,
       resumeCommand: resume.resumeCommand || undefined,
       resumeTool: resume.resumeTool || undefined,
       resumeSessionId: resume.resumeSessionId || undefined,
@@ -101,6 +115,7 @@ function materializeWorkspaceManifest(manifest) {
       version: normalized.version,
       workspaceId: normalized.workspaceId || undefined,
       title: normalized.title || undefined,
+      machine: normalized.machine || undefined,
       capture: normalized.capture || undefined,
       tabs: normalized.tabs.map((tab) => materializeWorkspaceTab(tab)),
     }).filter(([, value]) => value !== undefined),
@@ -113,6 +128,7 @@ function normalizeEditableManifest(source, parsed) {
         version: parsed.manifest.version,
         workspaceId: parsed.manifest.workspaceId,
         title: parsed.manifest.title,
+        machine: parsed.manifest.machine,
         capture: parsed.manifest.capture,
         tabs: parsed.manifest.tabs.map((entry) => {
           const resume = resolveResumeMetadata(entry);
@@ -120,6 +136,9 @@ function normalizeEditableManifest(source, parsed) {
             Object.entries({
               title: normalizeOptionalString(entry.title) || undefined,
               path: entry.path,
+              remoteUrl: normalizeOptionalString(entry.remoteUrl) || undefined,
+              remoteBranch: normalizeOptionalString(entry.remoteBranch) || undefined,
+              bootstrapCommand: normalizeOptionalString(entry.bootstrapCommand) || undefined,
               resumeCommand: resume.resumeCommand || undefined,
               resumeTool: resume.resumeTool || undefined,
               resumeSessionId: resume.resumeSessionId || undefined,
@@ -133,6 +152,7 @@ function normalizeEditableManifest(source, parsed) {
         version: "1",
         workspaceId: source.workspaceManifest?.workspaceId || source.title || "workspace",
         title: source.workspaceManifest?.title || source.title || null,
+        machine: source.workspaceManifest?.machine || null,
         capture: source.workspaceManifest?.capture || null,
         tabs: parsed.entries.map((entry) => {
           const resume = resolveResumeMetadata(entry);
@@ -140,6 +160,9 @@ function normalizeEditableManifest(source, parsed) {
             Object.entries({
               title: normalizeOptionalString(entry.title) || deriveBaseTitle(entry),
               path: entry.path,
+              remoteUrl: normalizeOptionalString(entry.remoteUrl) || undefined,
+              remoteBranch: normalizeOptionalString(entry.remoteBranch) || undefined,
+              bootstrapCommand: normalizeOptionalString(entry.bootstrapCommand) || undefined,
               resumeCommand: resume.resumeCommand || undefined,
               resumeTool: resume.resumeTool || undefined,
               resumeSessionId: resume.resumeSessionId || undefined,
@@ -216,6 +239,12 @@ function parseLedgerSelectorArgs(
         options.resumeTool = next;
       } else if (arg === "--resume-session-id") {
         options.resumeSessionId = next;
+      } else if (arg === "--remote-url") {
+        options.remoteUrl = next;
+      } else if (arg === "--remote-branch") {
+        options.remoteBranch = next;
+      } else if (arg === "--bootstrap-command") {
+        options.bootstrapCommand = next;
       } else if (arg === "--index") {
         options.index = next;
       } else {
@@ -312,6 +341,18 @@ export function parseWorkspaceCreateArgs(argv = []) {
         options.resumeTool = next;
       } else if (arg === "--resume-session-id") {
         options.resumeSessionId = next;
+      } else if (arg === "--remote-url") {
+        options.remoteUrl = next;
+      } else if (arg === "--remote-branch") {
+        options.remoteBranch = next;
+      } else if (arg === "--bootstrap-command") {
+        options.bootstrapCommand = next;
+      } else if (arg === "--machine-id") {
+        options.machineId = next;
+      } else if (arg === "--machine-label") {
+        options.machineLabel = next;
+      } else if (arg === "--platform") {
+        options.platform = next;
       } else {
         throw new Error(`unknown option: ${arg}`);
       }
@@ -392,6 +433,13 @@ export function addTabToManifest(manifest, options = {}) {
       Object.entries({
         title: normalizedTitle || normalizeOptionalString(existingTab?.title) || undefined,
         path: normalizedPath,
+        remoteUrl: normalizeOptionalString(options.remoteUrl) || normalizeOptionalString(existingTab?.remoteUrl) || undefined,
+        remoteBranch:
+          normalizeOptionalString(options.remoteBranch) || normalizeOptionalString(existingTab?.remoteBranch) || undefined,
+        bootstrapCommand:
+          normalizeOptionalString(options.bootstrapCommand) ||
+          normalizeOptionalString(existingTab?.bootstrapCommand) ||
+          undefined,
         resumeCommand: chosenResume.resumeCommand || undefined,
         resumeTool: chosenResume.resumeTool || undefined,
         resumeSessionId: chosenResume.resumeSessionId || undefined,
@@ -607,7 +655,7 @@ function printWorkspaceAddTabHelp() {
   console.log(`ORP workspace add-tab
 
 Usage:
-  orp workspace add-tab <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
+  orp workspace add-tab <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--remote-url <git-url>] [--remote-branch <branch>] [--bootstrap-command <text>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
   orp workspace add-tab --hosted-workspace-id <workspace-id> (--path <absolute-path> | --here) [--json]
   orp workspace add-tab --workspace-file <path> (--path <absolute-path> | --here) [--json]
 
@@ -615,6 +663,9 @@ Options:
   --path <absolute-path> Add this local project path to the saved workspace
   --here                 Use the current working directory as the saved path
   --title <title>        Optional saved tab title
+  --remote-url <git-url> Optional git remote URL for cross-machine setup
+  --remote-branch <branch> Optional default branch to clone on another machine
+  --bootstrap-command <text> Optional setup command like \`npm install\` or \`uv sync\`
   --resume-command <text> Exact saved resume command, like \`codex resume ...\` or \`claude --resume ...\`
   --resume-tool <tool>   Build the resume command from \`codex\` or \`claude\`
   --resume-session-id <id> Resume session id to save with the tab
@@ -630,6 +681,7 @@ Examples:
   orp workspace add-tab main --here --current-codex
   orp workspace add-tab main --path /absolute/path/to/new-project --resume-command "codex resume 019d..."
   orp workspace add-tab main --path /absolute/path/to/new-project --resume-tool claude --resume-session-id claude-456
+  orp workspace add-tab main --path /absolute/path/to/new-project --remote-url git@github.com:org/new-project.git --bootstrap-command "npm install"
 `);
 }
 
@@ -637,13 +689,19 @@ function printWorkspaceCreateHelp() {
   console.log(`ORP workspace create
 
 Usage:
-  orp workspace create <title-slug> [--workspace-file <path>] [--slot <main|offhand>] [--path <absolute-path>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id>] [--json]
+  orp workspace create <title-slug> [--workspace-file <path>] [--slot <main|offhand>] [--machine-id <id>] [--machine-label <label>] [--platform <platform>] [--path <absolute-path>] [--remote-url <git-url>] [--remote-branch <branch>] [--bootstrap-command <text>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id>] [--json]
 
 Options:
   <title-slug>           Required local workspace title using lowercase letters, numbers, and dashes only
   --workspace-file <path> Create the workspace manifest at an explicit local path instead of the managed ORP workspace directory
   --slot <main|offhand>  Optionally assign the created workspace to a named slot
+  --machine-id <id>      Optional stable machine id for this workspace ledger (defaults to this machine)
+  --machine-label <label> Optional human label for the current machine
+  --platform <platform>  Optional platform label like darwin, linux, or win32
   --path <absolute-path> Optionally seed the workspace with one saved path immediately
+  --remote-url <git-url> Optional git remote URL for the first saved tab
+  --remote-branch <branch> Optional default branch to clone on another machine
+  --bootstrap-command <text> Optional setup command like \`npm install\` or \`uv sync\`
   --resume-command <text> Exact saved resume command, like \`codex resume ...\` or \`claude --resume ...\`
   --resume-tool <tool>   Build the resume command from \`codex\` or \`claude\`
   --resume-session-id <id> Resume session id to save with the first tab
@@ -655,6 +713,7 @@ Examples:
   orp workspace create main-cody-1 --slot main
   orp workspace create research-lab --path /absolute/path/to/research-lab
   orp workspace create research-lab --path /absolute/path/to/research-lab --resume-tool claude --resume-session-id 469d99b2-2997-42bf-a8f5-3812c808ef29
+  orp workspace create mac-main --machine-label "Mac Studio" --path /absolute/path/to/research-lab --remote-url git@github.com:org/research-lab.git --bootstrap-command "npm install"
 `);
 }
 
@@ -697,6 +756,12 @@ function summarizeWorkspaceLedgerMutation(result) {
   if (result.action === "add-tab") {
     lines.push(`Tab: ${result.tab?.title || path.basename(result.tab?.path || "") || result.tab?.path}`);
     lines.push(`Path: ${result.tab?.path}`);
+    if (result.tab?.remoteUrl) {
+      lines.push(`Remote: ${result.tab.remoteUrl}`);
+    }
+    if (result.tab?.bootstrapCommand) {
+      lines.push(`Bootstrap: ${result.tab.bootstrapCommand}`);
+    }
     if (result.tab?.resumeCommand && result.tab?.restartCommand) {
       lines.push(`Resume: ${result.tab.restartCommand}`);
     }
@@ -792,6 +857,9 @@ export async function runWorkspaceCreate(argv = process.argv.slice(2)) {
         Object.entries({
           title: deriveBaseTitle({ path: options.path }),
           path: options.path,
+          remoteUrl: normalizeOptionalString(options.remoteUrl) || undefined,
+          remoteBranch: normalizeOptionalString(options.remoteBranch) || undefined,
+          bootstrapCommand: normalizeOptionalString(options.bootstrapCommand) || undefined,
           resumeCommand: resume.resumeCommand || undefined,
           resumeTool: resume.resumeTool || undefined,
           resumeSessionId: resume.resumeSessionId || undefined,
@@ -806,6 +874,7 @@ export async function runWorkspaceCreate(argv = process.argv.slice(2)) {
     version: "1",
     workspaceId: options.title,
     title: options.title,
+    machine: buildCurrentMachineMetadata(options),
     tabs,
   });
 
@@ -869,6 +938,9 @@ export async function runWorkspaceCreate(argv = process.argv.slice(2)) {
     `Saved tabs: ${result.tabCount}`,
     `Saved file: ${result.manifestPath}`,
   ];
+  if (result.manifest?.machine?.machineLabel) {
+    lines.push(`Machine: ${result.manifest.machine.machineLabel}${result.manifest.machine.platform ? ` (${result.manifest.machine.platform})` : ""}`);
+  }
   if (result.slot?.slot) {
     lines.push(`Slot: ${result.slot.slot}`);
   }

package/packages/orp-workspace-launcher/src/list.js

@@ -52,6 +52,10 @@ function buildHostedWorkspaceSummary(workspace) {
   return {
     workspaceId: normalizeOptionalString(workspace?.workspace_id ?? workspace?.id),
     title: normalizeOptionalString(workspace?.title),
+    machineId: normalizeOptionalString(workspace?.state?.capture_context?.machine_id ?? workspace?.state?.captureContext?.machineId),
+    machineLabel:
+      normalizeOptionalString(workspace?.state?.capture_context?.machine_label ?? workspace?.state?.captureContext?.machineLabel),
+    platform: normalizeOptionalString(workspace?.state?.capture_context?.platform ?? workspace?.state?.captureContext?.platform),
     visibility: normalizeOptionalString(workspace?.visibility),
     ideaId: normalizeOptionalString(linkedIdea.idea_id ?? linkedIdea.ideaId),
     tabCount:
@@ -66,6 +70,9 @@ function buildLocalWorkspaceSummary(workspace) {
   return {
     workspaceId: normalizeOptionalString(workspace?.workspaceId),
     title: normalizeOptionalString(workspace?.title),
+    machineId: normalizeOptionalString(workspace?.machineId),
+    machineLabel: normalizeOptionalString(workspace?.machineLabel),
+    platform: normalizeOptionalString(workspace?.platform),
     status: normalizeOptionalString(workspace?.status) || "ok",
     manifestPath: normalizeOptionalString(workspace?.manifestPath),
     tabCount: Number.isInteger(workspace?.tabCount) ? workspace.tabCount : 0,
@@ -244,6 +251,9 @@ export function buildWorkspaceInventory({ localResult, hostedResult, hostedError
       availability:
         entry.hosted && entry.local ? "hosted+local" : entry.hosted ? "hosted" : "local",
       syncStatus: inferSyncStatus(entry),
+      machineId: entry.local?.machineId || entry.hosted?.machineId || null,
+      machineLabel: entry.local?.machineLabel || entry.hosted?.machineLabel || null,
+      platform: entry.local?.platform || entry.hosted?.platform || null,
       sources: entry.sources,
       hosted: entry.hosted || null,
       local: entry.local || null,
@@ -308,6 +318,11 @@ export function summarizeWorkspaceInventory(result) {
         `Slots: ${workspace.slots.join(", ")}${workspace.implicitMain ? " (main inferred because this is the only workspace)" : ""}`,
       );
     }
+    if (workspace.machineLabel || workspace.machineId) {
+      lines.push(
+        `Machine: ${workspace.machineLabel || workspace.machineId}${workspace.platform ? ` (${workspace.platform})` : ""}`,
+      );
+    }
     lines.push(`Availability: ${workspace.availability}`);
     lines.push(`Sync: ${workspace.syncStatus}`);
     if (workspace.hosted) {
@@ -400,6 +415,9 @@ export function summarizeTrackedWorkspaces(result) {
     lines.push(`Status: ${workspace.status}`);
     lines.push(`File: ${workspace.manifestPath}`);
     lines.push(`Saved tabs: ${workspace.tabCount || 0}`);
+    if (workspace.machineLabel || workspace.machineId) {
+      lines.push(`Machine: ${workspace.machineLabel || workspace.machineId}${workspace.platform ? ` (${workspace.platform})` : ""}`);
+    }
 
     if (workspace.captureMode) {
       lines.push(`Capture mode: ${workspace.captureMode}`);

package/packages/orp-workspace-launcher/src/orp-command.js

@@ -8,18 +8,18 @@ function printWorkspaceHelp() {
   console.log(`ORP workspace
 
 Usage:
-  orp workspace create <title-slug> [--workspace-file <path>] [--slot <main|offhand>] [--path <absolute-path>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id>] [--json]
+  orp workspace create <title-slug> [--workspace-file <path>] [--slot <main|offhand>] [--machine-id <id>] [--machine-label <label>] [--platform <platform>] [--path <absolute-path>] [--remote-url <git-url>] [--remote-branch <branch>] [--bootstrap-command <text>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id>] [--json]
   orp workspace list [--json]
   orp workspace tabs <name-or-id> [--json]
   orp workspace tabs --hosted-workspace-id <workspace-id> [--json]
   orp workspace tabs --notes-file <path> [--json]
   orp workspace tabs --workspace-file <path> [--json]
-  orp workspace add-tab <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
+  orp workspace add-tab <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--remote-url <git-url>] [--remote-branch <branch>] [--bootstrap-command <text>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
   orp workspace remove-tab <name-or-id> (--index <n> | --path <absolute-path> | --title <title> | --resume-session-id <id> | --resume-command <text>) [--all] [--json]
   orp workspace slot <list|set|clear> ...
   orp workspace sync <name-or-id> [--workspace-file <path> | --notes-file <path>] [--dry-run] [--json]
   orp workspace ledger <name-or-id> [--json]
-  orp workspace ledger add <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
+  orp workspace ledger add <name-or-id> (--path <absolute-path> | --here) [--title <title>] [--remote-url <git-url>] [--remote-branch <branch>] [--bootstrap-command <text>] [--resume-command <text> | --resume-tool <codex|claude> --resume-session-id <id> | --current-codex] [--append] [--json]
   orp workspace ledger remove <name-or-id> (--index <n> | --path <absolute-path> | --title <title> | --resume-session-id <id> | --resume-command <text>) [--all] [--json]
   orp workspace -h
 
@@ -36,7 +36,9 @@ Commands:
 Notes:
   - Local-only usage works: create a workspace with \`orp workspace create <title-slug>\`, then use \`orp workspace tabs ...\`, \`orp workspace add-tab ...\`, and \`orp workspace remove-tab ...\` without authenticating.
   - Use \`orp workspace list\` for the combined hosted + local workspace inventory.
-  - Use \`orp workspace tabs <workspace>\` when you want saved paths plus copyable \`cd ... && codex resume ...\` / \`claude --resume ...\` recovery lines.
+  - Use \`orp workspace tabs <workspace>\` when you want saved paths plus copyable \`cd ... && codex resume ...\` / \`claude --resume ...\` recovery lines, along with optional remote repo and bootstrap metadata for another machine.
+  - Use \`orp workspace create ... --machine-label ...\` when you want the workspace ledger to stay clearly tied to one rig.
+  - Use \`orp workspace add-tab ... --remote-url ... --bootstrap-command ...\` when you want ORP to remember how to recreate the repo on another machine.
   - Use \`orp workspace add-tab ...\` and \`orp workspace remove-tab ...\` when you want to edit the saved workspace ledger explicitly from Terminal.app or any other shell.
   - If you prefer the older ledger-prefixed wording, \`orp workspace ledger\`, \`orp workspace ledger add\`, and \`orp workspace ledger remove\` stay available as aliases.
   - \`main\` and \`offhand\` are reserved slot selectors; use \`orp workspace slot set ...\` to assign them.
@@ -46,10 +48,12 @@ Notes:
 Examples:
   orp workspace create main-cody-1
   orp workspace create main-cody-1 --slot main
+  orp workspace create mac-main --machine-label "Mac Studio" --path /absolute/path/to/orp --remote-url git@github.com:SproutSeeds/orp.git --bootstrap-command "npm install"
   orp workspace list
   orp workspace tabs main-cody-1
   orp workspace add-tab main --here --current-codex
   orp workspace add-tab main --path /absolute/path/to/new-project --resume-command "codex resume 019d..."
+  orp workspace add-tab main --path /absolute/path/to/new-project --remote-url git@github.com:org/new-project.git --bootstrap-command "npm install"
   orp workspace remove-tab main --path /absolute/path/to/frg-site --resume-session-id 019d348d-5031-78e1-9840-a66deaac33ae
   orp workspace slot set main main-cody-1
   orp workspace slot set offhand research-lab

package/packages/orp-workspace-launcher/src/orp.js

@@ -627,6 +627,16 @@ export function buildWorkspaceManifestFromHostedWorkspacePayload(payload) {
     version: "1",
     workspaceId: getTextValue(workspace, "workspace_id", "id"),
     title: getTextValue(workspace, "title"),
+    machine: captureContext
+      ? Object.fromEntries(
+          Object.entries({
+            machineId: getTextValue(captureContext, "machine_id", "machineId"),
+            machineLabel: getTextValue(captureContext, "machine_label", "machineLabel"),
+            platform: getTextValue(captureContext, "platform"),
+            host: getTextValue(captureContext, "host"),
+          }).filter(([, value]) => value !== undefined && value !== null),
+        )
+      : undefined,
     capture: captureContext
       ? Object.fromEntries(
           Object.entries({
@@ -671,6 +681,9 @@ export function buildWorkspaceManifestFromHostedWorkspacePayload(payload) {
             path.basename(String(getTextValue(tab, "project_root", "projectRoot") || "").replace(/\/+$/, "")) ||
             undefined,
           path: getTextValue(tab, "project_root", "projectRoot"),
+          remoteUrl: getTextValue(tab, "remote_url", "remoteUrl"),
+          remoteBranch: getTextValue(tab, "remote_branch", "remoteBranch"),
+          bootstrapCommand: getTextValue(tab, "bootstrap_command", "bootstrapCommand"),
           resumeCommand: getTextValue(tab, "resume_command", "resumeCommand"),
           resumeTool: getTextValue(tab, "resume_tool", "resumeTool"),
           resumeSessionId: getTextValue(tab, "resume_session_id", "resumeSessionId"),

package/packages/orp-workspace-launcher/src/registry.js

@@ -78,6 +78,9 @@ function normalizeRegistryEntry(rawEntry) {
       manifestPath,
       workspaceId: normalizeOptionalString(rawEntry.workspaceId) ?? undefined,
       title: normalizeOptionalString(rawEntry.title) ?? undefined,
+      machineId: normalizeOptionalString(rawEntry.machineId) ?? undefined,
+      machineLabel: normalizeOptionalString(rawEntry.machineLabel) ?? undefined,
+      platform: normalizeOptionalString(rawEntry.platform) ?? undefined,
       host: normalizeOptionalString(rawEntry.host) ?? undefined,
       captureMode: normalizeOptionalString(rawEntry.captureMode) ?? undefined,
       capturedAt: normalizeOptionalString(rawEntry.capturedAt) ?? undefined,
@@ -312,6 +315,9 @@ export function summarizeManifestForRegistry(manifestPath, manifest) {
       manifestPath: normalizedPath,
       workspaceId: normalizeOptionalString(manifest.workspaceId) ?? undefined,
       title: normalizeOptionalString(manifest.title) ?? undefined,
+      machineId: normalizeOptionalString(manifest.machine?.machineId) ?? undefined,
+      machineLabel: normalizeOptionalString(manifest.machine?.machineLabel) ?? undefined,
+      platform: normalizeOptionalString(manifest.machine?.platform) ?? undefined,
       host: normalizeOptionalString(manifest.capture?.host) ?? undefined,
       captureMode: normalizeOptionalString(manifest.capture?.mode) ?? undefined,
       capturedAt: normalizeOptionalString(manifest.capture?.capturedAt) ?? undefined,
@@ -337,6 +343,9 @@ function serializeManagedWorkspaceManifest(manifest) {
           Object.entries({
             title: normalizeOptionalString(tab.title) ?? undefined,
             path: normalizeOptionalString(tab.path) ?? undefined,
+            remoteUrl: normalizeOptionalString(tab.remoteUrl) ?? undefined,
+            remoteBranch: normalizeOptionalString(tab.remoteBranch) ?? undefined,
+            bootstrapCommand: normalizeOptionalString(tab.bootstrapCommand) ?? undefined,
             resumeCommand: resumeCommand ?? undefined,
             resumeTool: resumeTool ?? undefined,
             resumeSessionId: resumeSessionId ?? undefined,
@@ -353,6 +362,7 @@ function serializeManagedWorkspaceManifest(manifest) {
         version: normalized.version,
         workspaceId: normalizeOptionalString(normalized.workspaceId) ?? undefined,
         title: normalizeOptionalString(normalized.title) ?? undefined,
+        machine: normalized.machine || undefined,
         capture: normalized.capture || undefined,
         tabs,
       }).filter(([, value]) => value !== undefined),

package/packages/orp-workspace-launcher/src/sync.js

@@ -191,6 +191,9 @@ function serializeWorkspaceManifest(manifest) {
       Object.entries({
         title: normalizeOptionalString(entry.title) ?? undefined,
         path: String(entry.path).trim(),
+        remoteUrl: normalizeOptionalString(entry.remoteUrl) ?? undefined,
+        remoteBranch: normalizeOptionalString(entry.remoteBranch) ?? undefined,
+        bootstrapCommand: normalizeOptionalString(entry.bootstrapCommand) ?? undefined,
         resumeCommand: normalizeOptionalString(entry.resumeCommand) ?? undefined,
         resumeTool: normalizeOptionalString(entry.resumeTool) ?? undefined,
         resumeSessionId: normalizeOptionalString(entry.resumeSessionId ?? entry.sessionId) ?? undefined,
@@ -211,6 +214,7 @@ function serializeWorkspaceManifest(manifest) {
       version: WORKSPACE_SCHEMA_VERSION,
       workspaceId: normalizeOptionalString(manifest.workspaceId) ?? undefined,
       title: normalizeOptionalString(manifest.title) ?? undefined,
+      machine: manifest.machine ?? undefined,
       tabs,
     }).filter(([, value]) => value !== undefined),
   );
@@ -231,9 +235,13 @@ export function buildWorkspaceSyncPreview({ source, parsed, targetIdea, workspac
         version: parsed.manifest.version || WORKSPACE_SCHEMA_VERSION,
         workspaceId: parsed.manifest.workspaceId || workspaceTitle || deriveWorkspaceId(source, parsed),
         title: workspaceTitle || parsed.manifest.title || null,
+        machine: parsed.manifest.machine || null,
         tabs: parsed.manifest.tabs.map((entry) => ({
           title: entry.title || deriveBaseTitle(entry),
           path: entry.path,
+          remoteUrl: entry.remoteUrl || null,
+          remoteBranch: entry.remoteBranch || null,
+          bootstrapCommand: entry.bootstrapCommand || null,
           resumeCommand: entry.resumeCommand || null,
           resumeTool: entry.resumeTool || null,
           resumeSessionId: entry.sessionId || null,
@@ -245,9 +253,13 @@ export function buildWorkspaceSyncPreview({ source, parsed, targetIdea, workspac
         version: WORKSPACE_SCHEMA_VERSION,
         workspaceId: workspaceTitle || deriveWorkspaceId(source, parsed),
         title: workspaceTitle || null,
+        machine: null,
         tabs: parsed.entries.map((entry) => ({
           title: deriveBaseTitle(entry),
           path: entry.path,
+          remoteUrl: entry.remoteUrl || null,
+          remoteBranch: entry.remoteBranch || null,
+          bootstrapCommand: entry.bootstrapCommand || null,
           resumeCommand: getResumeCommand(entry),
           resumeTool: resolveResumeMetadata(entry).resumeTool,
           resumeSessionId: resolveResumeMetadata(entry).resumeSessionId,