open-research-protocol 0.4.19 → 0.4.20

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

@@ -1,6 +1,14 @@
 import process from "node:process";
 
-import { buildDirectCommand, buildLaunchPlan, deriveWorkspaceId, getResumeCommand, parseWorkspaceSource } from "./core-plan.js";
+import {
+  buildCloneCommand,
+  buildDirectCommand,
+  buildLaunchPlan,
+  buildSetupCommand,
+  deriveWorkspaceId,
+  getResumeCommand,
+  parseWorkspaceSource,
+} from "./core-plan.js";
 import { loadWorkspaceSource } from "./orp.js";
 
 export function parseWorkspaceTabsArgs(argv = []) {
@@ -61,6 +69,7 @@ export function buildWorkspaceTabsReport(source, parsed, options = {}) {
     sourceLabel: source.sourceLabel,
     title: parsed.manifest?.title || source.title,
     workspaceId: deriveWorkspaceId(source, parsed),
+    machine: parsed.manifest?.machine || null,
     parseMode: parsed.parseMode,
     tabCount: launchTabs.length,
     skippedCount: parsed.skipped.length,
@@ -68,10 +77,16 @@ export function buildWorkspaceTabsReport(source, parsed, options = {}) {
       index: index + 1,
       title: tab.title,
       path: tab.path,
+      remoteUrl: tab.remoteUrl || null,
+      remoteBranch: tab.remoteBranch || null,
+      bootstrapCommand: tab.bootstrapCommand || null,
       resumeCommand: getResumeCommand(tab),
       restartCommand: buildDirectCommand(
         {
           path: tab.path,
+          remoteUrl: tab.remoteUrl || null,
+          remoteBranch: tab.remoteBranch || null,
+          bootstrapCommand: tab.bootstrapCommand || null,
           resumeCommand: tab.resumeCommand || null,
           resumeTool: tab.resumeTool || null,
           resumeSessionId: tab.sessionId || null,
@@ -79,6 +94,8 @@ export function buildWorkspaceTabsReport(source, parsed, options = {}) {
         },
         { resume: true },
       ),
+      cloneCommand: buildCloneCommand(tab),
+      setupCommand: buildSetupCommand(tab),
       resumeTool: tab.resumeTool || null,
       resumeSessionId: tab.sessionId || null,
       codexSessionId: tab.resumeTool === "codex" ? tab.sessionId || null : null,
@@ -92,6 +109,13 @@ export function summarizeWorkspaceTabs(report) {
   const lines = [
     `Source: ${report.sourceLabel}`,
     `Workspace ID: ${report.workspaceId}`,
+    ...(report.machine?.machineLabel
+      ? [
+          `Machine: ${report.machine.machineLabel}${
+            report.machine.platform ? ` (${report.machine.platform})` : ""
+          }${report.machine.machineId ? ` [${report.machine.machineId}]` : ""}`,
+        ]
+      : []),
     `Saved tabs: ${report.tabCount}`,
     `Parse mode: ${report.parseMode}`,
     "",
@@ -100,6 +124,18 @@ export function summarizeWorkspaceTabs(report) {
   for (const tab of report.tabs) {
     lines.push(`${String(tab.index).padStart(2, "0")}. ${tab.title}`);
     lines.push(`    path: ${tab.path}`);
+    if (tab.remoteUrl) {
+      lines.push(`    remote: ${tab.remoteUrl}${tab.remoteBranch ? ` [branch ${tab.remoteBranch}]` : ""}`);
+    }
+    if (tab.cloneCommand) {
+      lines.push(`    clone: ${tab.cloneCommand}`);
+    }
+    if (tab.bootstrapCommand) {
+      lines.push(`    bootstrap: ${tab.bootstrapCommand}`);
+    }
+    if (tab.setupCommand) {
+      lines.push(`    setup: ${tab.setupCommand}`);
+    }
     if (tab.resumeCommand) {
       lines.push(`    resume: ${tab.restartCommand}`);
     }
@@ -135,8 +171,9 @@ Options:
   -h, --help              Show this help text
 
 Notes:
-  - This shows the saved tab order plus any stored \`codex resume ...\` or \`claude --resume ...\` command metadata.
+  - This shows the saved tab order plus any stored local path, remote repo, bootstrap command, and \`codex resume ...\` / \`claude --resume ...\` metadata.
   - The human-readable \`resume:\` line is already copyable and includes the saved \`cd ... && resume ...\` recovery command.
+  - When a tab also has \`remote:\` or \`setup:\` lines, those are the portable cross-machine clues for cloning and preparing the repo on another rig.
   - The selector can be \`main\`, \`offhand\`, a hosted idea id, a hosted workspace id, a local workspace id, or a saved workspace title/slug.
 `);
 }

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

@@ -118,14 +118,23 @@ test("normalizeWorkspaceManifest keeps ledger fields and strips nothing importan
     version: "1",
     workspaceId: "terminal-paths",
     title: "Terminal Paths",
+    machine: {
+      machineId: "mac-studio:darwin",
+      machineLabel: "Mac Studio",
+      platform: "darwin",
+    },
     tabs: [
       {
         title: "orp",
         path: "/Volumes/Code_2TB/code/orp",
+        remoteUrl: "git@github.com:SproutSeeds/orp.git",
+        bootstrapCommand: "npm install",
       },
       {
         title: "lab",
         path: "/Volumes/Code_2TB/code/anthropic-lab",
+        remoteUrl: "git@github.com:anthropic/lab.git",
+        remoteBranch: "main",
         resumeTool: "claude",
         resumeSessionId: "claude-456",
       },
@@ -134,8 +143,12 @@ test("normalizeWorkspaceManifest keeps ledger fields and strips nothing importan
 
   assert.equal(manifest.workspaceId, "terminal-paths");
   assert.equal(manifest.title, "Terminal Paths");
+  assert.equal(manifest.machine?.machineLabel, "Mac Studio");
   assert.equal(manifest.tabs[0]?.title, "orp");
+  assert.equal(manifest.tabs[0]?.remoteUrl, "git@github.com:SproutSeeds/orp.git");
+  assert.equal(manifest.tabs[0]?.bootstrapCommand, "npm install");
   assert.equal(manifest.tabs[1]?.resumeTool, "claude");
+  assert.equal(manifest.tabs[1]?.remoteBranch, "main");
 });
 
 test("extractWorkspaceNarrativeNotes removes structured workspace blocks and legacy path lines", () => {

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

@@ -83,6 +83,10 @@ test("parseWorkspaceAddTabArgs accepts explicit resume metadata", () => {
     "main",
     "--path",
     "/Volumes/Code_2TB/code/new-project",
+    "--remote-url",
+    "git@github.com:org/new-project.git",
+    "--bootstrap-command",
+    "npm install",
     "--resume-tool",
     "claude",
     "--resume-session-id",
@@ -92,6 +96,8 @@ test("parseWorkspaceAddTabArgs accepts explicit resume metadata", () => {
 
   assert.equal(parsed.ideaId, "main");
   assert.equal(parsed.path, "/Volumes/Code_2TB/code/new-project");
+  assert.equal(parsed.remoteUrl, "git@github.com:org/new-project.git");
+  assert.equal(parsed.bootstrapCommand, "npm install");
   assert.equal(parsed.resumeTool, "claude");
   assert.equal(parsed.resumeSessionId, "claude-456");
   assert.equal(parsed.json, true);
@@ -128,8 +134,12 @@ test("parseWorkspaceCreateArgs validates slug titles and optional seed metadata"
     "main-cody-1",
     "--slot",
     "main",
+    "--machine-label",
+    "Mac Studio",
     "--path",
     "/Volumes/Code_2TB/code/orp",
+    "--remote-url",
+    "git@github.com:SproutSeeds/orp.git",
     "--resume-tool",
     "claude",
     "--resume-session-id",
@@ -139,7 +149,9 @@ test("parseWorkspaceCreateArgs validates slug titles and optional seed metadata"
 
   assert.equal(parsed.title, "main-cody-1");
   assert.equal(parsed.slotName, "main");
+  assert.equal(parsed.machineLabel, "Mac Studio");
   assert.equal(parsed.path, "/Volumes/Code_2TB/code/orp");
+  assert.equal(parsed.remoteUrl, "git@github.com:SproutSeeds/orp.git");
   assert.equal(parsed.resumeTool, "claude");
   assert.equal(parsed.resumeSessionId, "claude-456");
   assert.equal(parsed.json, true);
@@ -157,6 +169,8 @@ test("addTabToManifest canonicalizes Claude resume commands from tool plus sessi
   const result = addTabToManifest(sampleManifest(), {
     path: "/Volumes/Code_2TB/code/anthropic-lab",
     title: "anthropic-lab",
+    remoteUrl: "git@github.com:anthropic/anthropic-lab.git",
+    bootstrapCommand: "uv sync",
     resumeTool: "claude",
     resumeSessionId: "claude-456",
   });
@@ -165,6 +179,8 @@ test("addTabToManifest canonicalizes Claude resume commands from tool plus sessi
   assert.equal(result.manifest.tabs.length, 3);
   assert.equal(result.manifest.tabs[2]?.path, "/Volumes/Code_2TB/code/anthropic-lab");
   assert.equal(result.manifest.tabs[2]?.title, "anthropic-lab");
+  assert.equal(result.manifest.tabs[2]?.remoteUrl, "git@github.com:anthropic/anthropic-lab.git");
+  assert.equal(result.manifest.tabs[2]?.bootstrapCommand, "uv sync");
   assert.equal(result.manifest.tabs[2]?.resumeCommand, "claude --resume claude-456");
   assert.equal(result.manifest.tabs[2]?.resumeTool, "claude");
   assert.equal(result.manifest.tabs[2]?.sessionId, "claude-456");
@@ -250,6 +266,10 @@ test("runWorkspaceAddTab updates a local workspace manifest file", async () => {
         manifestPath,
         "--path",
         "/Volumes/Code_2TB/code/anthropic-lab",
+        "--remote-url",
+        "git@github.com:anthropic/anthropic-lab.git",
+        "--bootstrap-command",
+        "uv sync",
         "--resume-tool",
         "claude",
         "--resume-session-id",
@@ -263,8 +283,11 @@ test("runWorkspaceAddTab updates a local workspace manifest file", async () => {
     assert.equal(code, 0);
     assert.equal(payload.action, "add-tab");
     assert.equal(payload.tabCount, 3);
+    assert.equal(payload.tab.remoteUrl, "git@github.com:anthropic/anthropic-lab.git");
+    assert.equal(payload.tab.bootstrapCommand, "uv sync");
     assert.equal(payload.tab.resumeCommand, "claude --resume claude-456");
     assert.equal(saved.tabs.length, 3);
+    assert.equal(saved.tabs[2]?.remoteUrl, "git@github.com:anthropic/anthropic-lab.git");
     assert.equal(saved.tabs[2]?.resumeCommand, "claude --resume claude-456");
   });
 });
@@ -339,8 +362,14 @@ test("runWorkspaceCreate creates a local managed workspace and auto-assigns main
     const { code, stdout } = await captureStdout(() =>
       runWorkspaceCreate([
         "main-cody-1",
+        "--machine-label",
+        "Mac Studio",
         "--path",
         "/Volumes/Code_2TB/code/orp",
+        "--remote-url",
+        "git@github.com:SproutSeeds/orp.git",
+        "--bootstrap-command",
+        "npm install",
         "--resume-tool",
         "claude",
         "--resume-session-id",
@@ -357,7 +386,28 @@ test("runWorkspaceCreate creates a local managed workspace and auto-assigns main
     assert.equal(payload.workspaceTitle, "main-cody-1");
     assert.equal(payload.tabCount, 1);
     assert.equal(saved.title, "main-cody-1");
+    assert.equal(saved.machine.machineLabel, "Mac Studio");
+    assert.equal(saved.tabs[0]?.remoteUrl, "git@github.com:SproutSeeds/orp.git");
+    assert.equal(saved.tabs[0]?.bootstrapCommand, "npm install");
     assert.equal(saved.tabs[0]?.resumeCommand, "claude --resume claude-456");
     assert.equal(slots.slots.main.title, "main-cody-1");
   });
 });
+
+test("runWorkspaceCreate allows an empty local ledger before any tabs are added", async () => {
+  await withTempConfigHome(async () => {
+    const { code, stdout } = await captureStdout(() =>
+      runWorkspaceCreate([
+        "empty-ledger",
+        "--json",
+      ]),
+    );
+    const payload = JSON.parse(stdout);
+    const saved = JSON.parse(await fs.readFile(payload.manifestPath, "utf8"));
+
+    assert.equal(code, 0);
+    assert.equal(payload.workspaceTitle, "empty-ledger");
+    assert.equal(payload.tabCount, 0);
+    assert.deepEqual(saved.tabs, []);
+  });
+});

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

@@ -39,6 +39,11 @@ test("registerWorkspaceManifest and listTrackedWorkspaces expose tracked saved r
     version: "1",
     workspaceId: "orp-main",
     title: "ORP Main",
+    machine: {
+      machineId: "mac-studio:darwin",
+      machineLabel: "Mac Studio",
+      platform: "darwin",
+    },
     capture: {
       sourceApp: "iTerm",
       mode: "watch",
@@ -74,6 +79,9 @@ test("registerWorkspaceManifest and listTrackedWorkspaces expose tracked saved r
     manifestPath: path.resolve(manifestPath),
     workspaceId: "orp-main",
     title: "ORP Main",
+    machineId: "mac-studio:darwin",
+    machineLabel: "Mac Studio",
+    platform: "darwin",
     host: "local-macbook",
     captureMode: "watch",
     capturedAt: "2026-03-28T12:00:00.000Z",
@@ -100,6 +108,7 @@ test("registerWorkspaceManifest and listTrackedWorkspaces expose tracked saved r
   const summary = summarizeTrackedWorkspaces(result);
   assert.match(summary, /Local tracked workspaces: 1/);
   assert.match(summary, /ORP Main \[orp-main\]/);
+  assert.match(summary, /Machine: Mac Studio \(darwin\)/);
   assert.match(summary, /Saved resume sessions: 1/);
   assert.match(summary, /web: claude resume claude-999/);
 });
@@ -172,6 +181,9 @@ test("buildWorkspaceInventory merges hosted and local workspace state", () => {
           manifestPath: "/Users/example/.config/orp/workspaces/idea-123-deadbeef.json",
           workspaceId: "idea-123",
           title: "Main Cody 1",
+          machineId: "mac-studio:darwin",
+          machineLabel: "Mac Studio",
+          platform: "darwin",
           tabCount: 2,
           codexSessionCount: 1,
           updatedAt: "2026-03-30T12:00:00.000Z",
@@ -198,6 +210,11 @@ test("buildWorkspaceInventory merges hosted and local workspace state", () => {
           linkedIdea: { ideaId: "ef86" },
           metrics: { tabCount: 2 },
           state: {
+            capture_context: {
+              machine_id: "mac-studio:darwin",
+              machine_label: "Mac Studio",
+              platform: "darwin",
+            },
             tabs: [
               { project_root: "/Volumes/Code_2TB/code/orp", codex_session_id: "abc-123" },
               { project_root: "/Volumes/Code_2TB/code/orp-web-app" },
@@ -211,6 +228,7 @@ test("buildWorkspaceInventory merges hosted and local workspace state", () => {
 
   assert.equal(result.workspaces.length, 2);
   assert.equal(result.workspaces[0]?.workspaceId, "idea-123");
+  assert.equal(result.workspaces[0]?.machineLabel, "Mac Studio");
   assert.equal(result.workspaces[0]?.availability, "hosted+local");
   assert.equal(result.workspaces[0]?.syncStatus, "synced");
   assert.equal(result.workspaces[1]?.workspaceId, "local-only");
@@ -220,6 +238,7 @@ test("buildWorkspaceInventory merges hosted and local workspace state", () => {
   assert.match(summary, /Workspace inventory: 2/);
   assert.match(summary, /Hosted available: 1/);
   assert.match(summary, /Local available: 2/);
+  assert.match(summary, /Machine: Mac Studio \(darwin\)/);
   assert.match(summary, /Sync: synced/);
 });
 

package/packages/orp-workspace-launcher/test/tabs.test.js

@@ -50,11 +50,35 @@ test("buildWorkspaceTabsReport keeps duplicate titles unique and exposes generic
     sourceType: "hosted-idea",
     sourceLabel: "Workspace idea",
     title: "Workspace idea",
-    notes: `
-/Volumes/Code_2TB/code/collaboration: codex resume abc-123
-/Volumes/Code_2TB/code/anthropic-lab: claude resume claude-456
-/Volumes/Code_2TB/code/collaboration
-`,
+    workspaceManifest: {
+      version: "1",
+      workspaceId: "workspace-idea",
+      machine: {
+        machineId: "mac-studio:darwin",
+        machineLabel: "Mac Studio",
+        platform: "darwin",
+      },
+      tabs: [
+        {
+          path: "/Volumes/Code_2TB/code/collaboration",
+          title: "collaboration",
+          remoteUrl: "git@github.com:org/collaboration.git",
+          bootstrapCommand: "npm install",
+          resumeCommand: "codex resume abc-123",
+        },
+        {
+          path: "/Volumes/Code_2TB/code/anthropic-lab",
+          title: "anthropic-lab",
+          remoteUrl: "git@github.com:anthropic/anthropic-lab.git",
+          remoteBranch: "main",
+          resumeCommand: "claude resume claude-456",
+        },
+        {
+          path: "/Volumes/Code_2TB/code/collaboration",
+        },
+      ],
+    },
+    notes: "",
   });
 
   const report = buildWorkspaceTabsReport(
@@ -66,9 +90,17 @@ test("buildWorkspaceTabsReport keeps duplicate titles unique and exposes generic
     parsed,
   );
 
-  assert.match(report.workspaceId, /^workspace-/);
+  assert.equal(report.workspaceId, "workspace-idea");
+  assert.equal(report.machine?.machineLabel, "Mac Studio");
   assert.equal(report.tabCount, 3);
   assert.equal(report.tabs[0]?.title, "collaboration");
+  assert.equal(report.tabs[0]?.remoteUrl, "git@github.com:org/collaboration.git");
+  assert.equal(report.tabs[0]?.bootstrapCommand, "npm install");
+  assert.equal(report.tabs[0]?.cloneCommand, "git clone 'git@github.com:org/collaboration.git' 'collaboration'");
+  assert.equal(
+    report.tabs[0]?.setupCommand,
+    "git clone 'git@github.com:org/collaboration.git' 'collaboration' && cd 'collaboration' && npm install",
+  );
   assert.equal(report.tabs[0]?.resumeCommand, "codex resume abc-123");
   assert.equal(
     report.tabs[0]?.restartCommand,
@@ -77,6 +109,7 @@ test("buildWorkspaceTabsReport keeps duplicate titles unique and exposes generic
   assert.equal(report.tabs[0]?.codexSessionId, "abc-123");
   assert.equal(report.tabs[1]?.title, "anthropic-lab");
   assert.equal(report.tabs[1]?.resumeCommand, "claude resume claude-456");
+  assert.equal(report.tabs[1]?.remoteBranch, "main");
   assert.equal(
     report.tabs[1]?.restartCommand,
     "cd '/Volumes/Code_2TB/code/anthropic-lab' && claude resume claude-456",
@@ -96,10 +129,17 @@ test("runWorkspaceTabs prints JSON without launch commands", async () => {
         version: "1",
         workspaceId: "orp-main",
         title: "ORP Main",
+        machine: {
+          machineId: "mac-studio:darwin",
+          machineLabel: "Mac Studio",
+          platform: "darwin",
+        },
         tabs: [
           {
             title: "orp",
             path: "/Volumes/Code_2TB/code/orp",
+            remoteUrl: "git@github.com:SproutSeeds/orp.git",
+            bootstrapCommand: "npm install",
             resumeCommand: "claude resume claude-999",
             resumeTool: "claude",
             resumeSessionId: "claude-999",
@@ -121,8 +161,11 @@ test("runWorkspaceTabs prints JSON without launch commands", async () => {
 
   assert.equal(code, 0);
   assert.equal(parsed.workspaceId, "orp-main");
+  assert.equal(parsed.machine.machineLabel, "Mac Studio");
   assert.equal(parsed.tabCount, 2);
   assert.equal(parsed.tabs[0]?.title, "orp");
+  assert.equal(parsed.tabs[0]?.remoteUrl, "git@github.com:SproutSeeds/orp.git");
+  assert.equal(parsed.tabs[0]?.bootstrapCommand, "npm install");
   assert.equal(parsed.tabs[0]?.resumeCommand, "claude resume claude-999");
   assert.equal(parsed.tabs[0]?.restartCommand, "cd '/Volumes/Code_2TB/code/orp' && claude resume claude-999");
   assert.equal(parsed.tabs[0]?.claudeSessionId, "claude-999");
@@ -142,6 +185,7 @@ test("buildWorkspaceTabsReport canonicalizes Claude resume commands from tool an
         {
           title: "anthropic-lab",
           path: "/Volumes/Code_2TB/code/anthropic-lab",
+          remoteUrl: "git@github.com:anthropic/anthropic-lab.git",
           resumeTool: "claude",
           resumeSessionId: "claude-456",
         },
@@ -160,6 +204,7 @@ test("buildWorkspaceTabsReport canonicalizes Claude resume commands from tool an
   );
 
   assert.equal(report.tabs[0]?.resumeCommand, "claude --resume claude-456");
+  assert.equal(report.tabs[0]?.cloneCommand, "git clone 'git@github.com:anthropic/anthropic-lab.git' 'anthropic-lab'");
   assert.equal(
     report.tabs[0]?.restartCommand,
     "cd '/Volumes/Code_2TB/code/anthropic-lab' && claude --resume claude-456",

package/spec/v1/workspace.schema.json

@@ -2,7 +2,7 @@
   "$schema": "https://json-schema.org/draft/2020-12/schema",
   "$id": "https://orp.dev/spec/v1/workspace.schema.json",
   "title": "ORP Workspace Manifest",
-  "description": "Structured workspace launcher manifest for ORP iTerm/tmux workspace restoration.",
+  "description": "Structured workspace ledger manifest for ORP local and hosted workspace recovery across machines.",
   "type": "object",
   "required": ["version", "tabs"],
   "properties": {
@@ -18,6 +18,28 @@
       "type": "string",
       "minLength": 1
     },
+    "machine": {
+      "type": "object",
+      "properties": {
+        "machineId": {
+          "type": "string",
+          "minLength": 1
+        },
+        "machineLabel": {
+          "type": "string",
+          "minLength": 1
+        },
+        "platform": {
+          "type": "string",
+          "minLength": 1
+        },
+        "host": {
+          "type": "string",
+          "minLength": 1
+        }
+      },
+      "additionalProperties": false
+    },
     "tmuxPrefix": {
       "type": "string",
       "minLength": 1
@@ -66,7 +88,7 @@
     },
     "tabs": {
       "type": "array",
-      "minItems": 1,
+      "minItems": 0,
       "items": {
         "type": "object",
         "required": ["path"],
@@ -79,6 +101,18 @@
             "type": "string",
             "pattern": "^/"
           },
+          "remoteUrl": {
+            "type": "string",
+            "minLength": 1
+          },
+          "remoteBranch": {
+            "type": "string",
+            "minLength": 1
+          },
+          "bootstrapCommand": {
+            "type": "string",
+            "minLength": 1
+          },
           "resumeCommand": {
             "type": "string",
             "minLength": 1