open-research-protocol 0.4.14 → 0.4.15

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

@@ -0,0 +1,82 @@
+# orp-workspace-launcher
+
+Manage a durable ORP workspace ledger of project paths plus saved `codex resume ...` or `claude --resume ...` commands.
+
+The package no longer automates iTerm or Terminal.app. The workspace ledger is the source of truth, and you use Terminal however you want.
+
+## Core flow
+
+Create a local workspace ledger with no hosted account required:
+
+```bash
+orp workspace create main-cody-1
+orp workspace create research-lab --path /Volumes/Code_2TB/code/research-lab --resume-tool claude --resume-session-id 469d99b2-2997-42bf-a8f5-3812c808ef29
+```
+
+Inspect the saved ledger:
+
+```bash
+orp workspace ledger main
+orp workspace tabs main
+```
+
+Print copyable recovery commands:
+
+```bash
+orp workspace tabs main
+orp workspace tabs main --json
+```
+
+Add a new saved tab manually:
+
+```bash
+orp workspace ledger add main --path /Volumes/Code_2TB/code/frg-site --resume-command "codex resume 019d348d-5031-78e1-9840-a66deaac33ae"
+orp workspace add-tab main --path /Volumes/Code_2TB/code/anthropic-lab --resume-tool claude --resume-session-id claude-456
+```
+
+Remove a saved tab manually:
+
+```bash
+orp workspace ledger remove main --path /Volumes/Code_2TB/code/frg-site
+orp workspace remove-tab main --resume-session-id claude-456 --resume-tool claude
+```
+
+Work directly with a local manifest file:
+
+```bash
+orp workspace add-tab --workspace-file ./workspace.json --path /Volumes/Code_2TB/code/orp
+orp workspace tabs --workspace-file ./workspace.json
+orp workspace tabs --workspace-file ./workspace.json --json
+```
+
+Sync a local manifest back to the hosted canonical workspace:
+
+```bash
+orp workspace sync main --workspace-file ./workspace.json
+orp workspace sync main --workspace-file ./workspace.json --dry-run
+```
+
+List saved workspaces:
+
+```bash
+orp workspace list
+orp workspace slot list
+orp workspace slot set main main-cody-1
+orp workspace slot set offhand research-lab
+```
+
+## Options
+
+- `--json`: print agent-friendly JSON
+- `--notes-file <path>`: read a local notes file instead of ORP
+- `--hosted-workspace-id <id>`: read or update a first-class hosted workspace instead of an idea-backed bridge
+- `--workspace-file <path>`: read or update a structured workspace manifest JSON file
+- `--base-url <url>`: override the ORP hosted base URL
+- `--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
+- `--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

package/packages/orp-workspace-launcher/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "orp-workspace-launcher",
+  "version": "0.1.0",
+  "description": "Manage ORP workspace ledgers with saved paths and Codex or Claude resume commands.",
+  "author": "Fractal Research Group <cody@frg.earth>",
+  "homepage": "https://github.com/SproutSeeds/orp/tree/main/packages/orp-workspace-launcher",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/SproutSeeds/orp.git",
+    "directory": "packages/orp-workspace-launcher"
+  },
+  "bugs": {
+    "url": "https://github.com/SproutSeeds/orp/issues"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "bin",
+    "src",
+    "README.md"
+  ],
+  "scripts": {
+    "test": "node --test"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "keywords": [
+    "codex",
+    "open-research-protocol",
+    "orp",
+    "workspace",
+    "ledger",
+    "claude"
+  ],
+  "license": "MIT"
+}

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

@@ -0,0 +1,77 @@
+import process from "node:process";
+
+import {
+  buildWorkspaceTabsReport,
+  parseWorkspaceTabsArgs,
+  summarizeWorkspaceTabs,
+} from "./tabs.js";
+import { loadWorkspaceSource } from "./orp.js";
+import { parseWorkspaceSource } from "./core-plan.js";
+
+export function parseWorkspaceCommandsArgs(argv = []) {
+  return parseWorkspaceTabsArgs(argv);
+}
+
+export function buildWorkspaceCommandsReport(source, parsed, options = {}) {
+  const report = buildWorkspaceTabsReport(source, parsed, options);
+  return {
+    ...report,
+    commandCount: report.tabCount,
+  };
+}
+
+export function summarizeWorkspaceCommands(report) {
+  return summarizeWorkspaceTabs({
+    ...report,
+    tabCount: report.commandCount ?? report.tabCount,
+  });
+}
+
+function printWorkspaceCommandsHelp() {
+  console.log(`ORP workspace commands
+
+Usage:
+  orp workspace commands <name-or-id> [--json]
+  orp workspace commands --hosted-workspace-id <workspace-id> [--json]
+  orp workspace commands --notes-file <path> [--json]
+  orp workspace commands --workspace-file <path> [--json]
+
+Options:
+  --json                  Print saved recovery commands as JSON
+  --hosted-workspace-id <id> Read a first-class hosted workspace instead of an idea
+  --notes-file <path>     Read a local notes file instead of ORP
+  --workspace-file <path> Read a structured workspace manifest JSON file
+  --base-url <url>        Override the ORP hosted base URL
+  --orp-command <cmd>     Override the ORP CLI executable used for hosted fetches
+  -h, --help              Show this help text
+
+Notes:
+  - This is now a compatibility alias for \`orp workspace tabs ...\`.
+  - Use \`orp workspace tabs ...\` as the main read command for saved paths plus copyable resume lines.
+  - The selector can be \`main\`, \`offhand\`, a hosted idea id, a hosted workspace id, a local workspace id, or a saved workspace title/slug.
+`);
+}
+
+export async function runWorkspaceCommands(argv = process.argv.slice(2)) {
+  const options = parseWorkspaceCommandsArgs(argv);
+  if (options.help) {
+    printWorkspaceCommandsHelp();
+    return 0;
+  }
+
+  const source = await loadWorkspaceSource(options);
+  const parsed = parseWorkspaceSource(source);
+  const report = buildWorkspaceCommandsReport(source, parsed, options);
+
+  if (report.commandCount === 0) {
+    throw new Error("No saved workspace commands were found in the provided workspace source.");
+  }
+
+  if (options.json) {
+    process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+    return 0;
+  }
+
+  process.stdout.write(`${summarizeWorkspaceCommands(report)}\n`);
+  return 0;
+}

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

@@ -0,0 +1,506 @@
+import path from "node:path";
+
+export const WORKSPACE_SCHEMA_VERSION = "1";
+
+const SUPPORTED_RESUME_TOOLS = new Set(["codex", "claude"]);
+const CODEX_RESUME_PATTERN = /^\s*codex\s+resume\s+([^\s]+)(?:\s+.*)?$/i;
+const CLAUDE_LEGACY_RESUME_PATTERN = /^\s*claude\s+resume\s+([^\s]+)(?:\s+.*)?$/i;
+const CLAUDE_FLAG_RESUME_PATTERN = /^\s*claude\s+(?:--resume|-r)(?:=|\s+)([^\s]+)(?:\s+.*)?$/i;
+const STRUCTURED_WORKSPACE_PATTERN = /```orp-workspace\s*([\s\S]*?)```/i;
+
+function partitionOnColon(value) {
+  const index = value.indexOf(":");
+  if (index === -1) {
+    return [value, ""];
+  }
+  return [value.slice(0, index), value.slice(index + 1)];
+}
+
+function shellQuote(value) {
+  const text = String(value);
+  if (text.length === 0) {
+    return "''";
+  }
+  return `'${text.replace(/'/g, `'\"'\"'`)}'`;
+}
+
+function normalizeDisplayPath(value) {
+  const trimmed = String(value).trim();
+  if (trimmed === "/") {
+    return trimmed;
+  }
+  return trimmed.replace(/\/+$/, "");
+}
+
+function hashText(value) {
+  let hash = 0;
+  for (let index = 0; index < value.length; index += 1) {
+    hash = (hash * 31 + value.charCodeAt(index)) >>> 0;
+  }
+  return hash.toString(36);
+}
+
+function slugify(value) {
+  const normalized = String(value || "")
+    .trim()
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+  return normalized || "workspace";
+}
+
+function validateAbsolutePath(value, label) {
+  if (typeof value !== "string" || !value.trim().startsWith("/")) {
+    throw new Error(`${label} must be an absolute path`);
+  }
+  return value.trim();
+}
+
+function normalizeOptionalString(value) {
+  if (value == null) {
+    return null;
+  }
+  const trimmed = String(value).trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function normalizeResumeTool(value) {
+  const trimmed = normalizeOptionalString(value)?.toLowerCase() || null;
+  return trimmed && SUPPORTED_RESUME_TOOLS.has(trimmed) ? trimmed : null;
+}
+
+export function buildCanonicalResumeCommand(tool, sessionId) {
+  const resumeTool = normalizeResumeTool(tool);
+  const resumeSessionId = normalizeOptionalString(sessionId);
+  if (!resumeTool || !resumeSessionId) {
+    return null;
+  }
+  if (resumeTool === "claude") {
+    return `claude --resume ${resumeSessionId}`;
+  }
+  return `${resumeTool} resume ${resumeSessionId}`;
+}
+
+export function parseResumeCommandText(value) {
+  const trimmed = normalizeOptionalString(value);
+  if (!trimmed) {
+    return {
+      resumeCommand: null,
+      resumeTool: null,
+      resumeSessionId: null,
+    };
+  }
+
+  const codexMatch = trimmed.match(CODEX_RESUME_PATTERN);
+  if (codexMatch) {
+    return {
+      resumeCommand: trimmed,
+      resumeTool: "codex",
+      resumeSessionId: normalizeOptionalString(codexMatch[1]),
+    };
+  }
+
+  const claudeFlagMatch = trimmed.match(CLAUDE_FLAG_RESUME_PATTERN);
+  if (claudeFlagMatch) {
+    return {
+      resumeCommand: trimmed,
+      resumeTool: "claude",
+      resumeSessionId: normalizeOptionalString(claudeFlagMatch[1]),
+    };
+  }
+
+  const claudeLegacyMatch = trimmed.match(CLAUDE_LEGACY_RESUME_PATTERN);
+  if (!claudeLegacyMatch) {
+    return {
+      resumeCommand: null,
+      resumeTool: null,
+      resumeSessionId: null,
+    };
+  }
+
+  return {
+    resumeCommand: trimmed,
+    resumeTool: "claude",
+    resumeSessionId: normalizeOptionalString(claudeLegacyMatch[1]),
+  };
+}
+
+export function resolveResumeMetadata(raw = {}) {
+  const parsedCommand = parseResumeCommandText(raw.resumeCommand ?? raw.remainder);
+  const explicitTool = normalizeResumeTool(raw.resumeTool);
+  const explicitResumeSessionId = normalizeOptionalString(raw.resumeSessionId ?? raw.sessionId);
+  const legacyCodexSessionId = normalizeOptionalString(raw.codexSessionId);
+  const legacyClaudeSessionId = normalizeOptionalString(raw.claudeSessionId);
+
+  const resumeTool =
+    parsedCommand.resumeTool ||
+    explicitTool ||
+    (explicitResumeSessionId ? "codex" : null) ||
+    (legacyCodexSessionId ? "codex" : null) ||
+    (legacyClaudeSessionId ? "claude" : null);
+
+  const resumeSessionId =
+    parsedCommand.resumeSessionId ||
+    explicitResumeSessionId ||
+    (resumeTool === "codex" ? legacyCodexSessionId : null) ||
+    (resumeTool === "claude" ? legacyClaudeSessionId : null) ||
+    legacyCodexSessionId ||
+    legacyClaudeSessionId ||
+    null;
+
+  const resumeCommand =
+    parsedCommand.resumeCommand ||
+    buildCanonicalResumeCommand(resumeTool, resumeSessionId);
+
+  return {
+    resumeCommand,
+    resumeTool,
+    resumeSessionId,
+  };
+}
+
+export function getResumeCommand(entry) {
+  return resolveResumeMetadata(entry).resumeCommand;
+}
+
+function normalizeOptionalPositiveInteger(value, label) {
+  if (value == null || value === "") {
+    return null;
+  }
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed < 1) {
+    throw new Error(`${label} must be a positive integer`);
+  }
+  return parsed;
+}
+
+function normalizeOptionalNonNegativeInteger(value, label) {
+  if (value == null || value === "") {
+    return null;
+  }
+  const parsed = Number.parseInt(String(value), 10);
+  if (!Number.isInteger(parsed) || parsed < 0) {
+    throw new Error(`${label} must be a non-negative integer`);
+  }
+  return parsed;
+}
+
+function normalizeOptionalPositiveNumber(value, label) {
+  if (value == null || value === "") {
+    return null;
+  }
+  const parsed = Number(String(value));
+  if (!Number.isFinite(parsed) || parsed <= 0) {
+    throw new Error(`${label} must be a positive number`);
+  }
+  return parsed;
+}
+
+function normalizeCaptureMetadata(rawCapture) {
+  if (rawCapture == null) {
+    return null;
+  }
+  if (!rawCapture || typeof rawCapture !== "object" || Array.isArray(rawCapture)) {
+    throw new Error("workspace manifest capture metadata must be an object");
+  }
+
+  const capture = Object.fromEntries(
+    Object.entries({
+      sourceApp: normalizeOptionalString(rawCapture.sourceApp),
+      mode: normalizeOptionalString(rawCapture.mode),
+      host: normalizeOptionalString(rawCapture.host),
+      windowId: normalizeOptionalPositiveInteger(rawCapture.windowId, "workspace manifest capture.windowId"),
+      windowIndex: normalizeOptionalPositiveInteger(rawCapture.windowIndex, "workspace manifest capture.windowIndex"),
+      tabCount: normalizeOptionalNonNegativeInteger(rawCapture.tabCount, "workspace manifest capture.tabCount"),
+      capturedAt: normalizeOptionalString(rawCapture.capturedAt),
+      trackingStartedAt: normalizeOptionalString(rawCapture.trackingStartedAt),
+      pollSeconds: normalizeOptionalPositiveNumber(rawCapture.pollSeconds, "workspace manifest capture.pollSeconds"),
+    }).filter(([, value]) => value != null),
+  );
+
+  return Object.keys(capture).length > 0 ? capture : null;
+}
+
+function normalizeStructuredTab(rawTab, index) {
+  if (!rawTab || typeof rawTab !== "object" || Array.isArray(rawTab)) {
+    throw new Error(`workspace tab ${index + 1} must be an object`);
+  }
+
+  const pathValue = validateAbsolutePath(rawTab.path, `workspace tab ${index + 1} path`);
+  const title = normalizeOptionalString(rawTab.title);
+  const resume = resolveResumeMetadata(rawTab);
+  const tmuxSessionName = normalizeOptionalString(rawTab.tmuxSessionName);
+
+  return {
+    lineNumber: index + 1,
+    rawLine: JSON.stringify(rawTab),
+    path: pathValue,
+    remainder: resume.resumeCommand || "",
+    sessionId: resume.resumeSessionId,
+    resumeCommand: resume.resumeCommand,
+    resumeTool: resume.resumeTool,
+    title,
+    tmuxSessionName,
+  };
+}
+
+export function normalizeWorkspaceManifest(rawManifest) {
+  if (!rawManifest || typeof rawManifest !== "object" || Array.isArray(rawManifest)) {
+    throw new Error("workspace manifest must be a JSON object");
+  }
+
+  const version = String(rawManifest.version ?? WORKSPACE_SCHEMA_VERSION);
+  if (version !== WORKSPACE_SCHEMA_VERSION) {
+    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");
+  }
+
+  const tabs = rawManifest.tabs.map((tab, index) => normalizeStructuredTab(tab, index));
+  return {
+    version,
+    workspaceId: normalizeOptionalString(rawManifest.workspaceId),
+    title: normalizeOptionalString(rawManifest.title),
+    tmuxPrefix: normalizeOptionalString(rawManifest.tmuxPrefix),
+    capture: normalizeCaptureMetadata(rawManifest.capture),
+    tabs,
+  };
+}
+
+export function extractStructuredWorkspaceFromNotes(notes) {
+  const match = String(notes || "").match(STRUCTURED_WORKSPACE_PATTERN);
+  if (!match) {
+    return null;
+  }
+
+  let parsed;
+  try {
+    parsed = JSON.parse(match[1]);
+  } catch (error) {
+    throw new Error(
+      `failed to parse \`\`\`orp-workspace\`\`\` JSON: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+
+  return normalizeWorkspaceManifest(parsed);
+}
+
+export function deriveBaseTitle(entry) {
+  if (entry.title && String(entry.title).trim().length > 0) {
+    return String(entry.title).trim();
+  }
+  const normalized = normalizeDisplayPath(entry.path);
+  return path.basename(normalized) || normalized;
+}
+
+export function deriveTmuxSessionName(entry, options = {}) {
+  if (entry.tmuxSessionName && String(entry.tmuxSessionName).trim().length > 0) {
+    return String(entry.tmuxSessionName).trim();
+  }
+
+  const prefix = (options.tmuxPrefix || "orp").trim() || "orp";
+  const base = deriveBaseTitle(entry)
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "") || "workspace";
+  const entropy = hashText(`${entry.path}:${getResumeCommand(entry) || entry.sessionId || ""}:${entry.lineNumber || 0}`).slice(
+    0,
+    6,
+  );
+  return `${prefix}-${base}-${entropy}`.slice(0, 64);
+}
+
+export function deriveWorkspaceId(source, parsed) {
+  if (parsed.manifest?.workspaceId) {
+    return parsed.manifest.workspaceId;
+  }
+
+  if (source.sourceType === "hosted-idea" && source.idea?.id) {
+    return `idea-${source.idea.id}`;
+  }
+
+  if (source.sourceType === "workspace-file" && source.sourcePath) {
+    return `file-${slugify(path.basename(source.sourcePath, path.extname(source.sourcePath)))}-${hashText(source.sourcePath).slice(0, 6)}`;
+  }
+
+  if (source.sourcePath) {
+    return `file-${hashText(source.sourcePath).slice(0, 8)}`;
+  }
+
+  return `workspace-${hashText(`${source.sourceType}:${source.sourceLabel}`).slice(0, 8)}`;
+}
+
+export function parseCorePlanNotes(notes) {
+  const entries = [];
+  const skipped = [];
+
+  for (const [index, rawLine] of String(notes || "").split(/\r?\n/).entries()) {
+    const lineNumber = index + 1;
+    const line = rawLine.trim();
+    if (!line) {
+      continue;
+    }
+    if (!line.startsWith("/")) {
+      skipped.push({ lineNumber, rawLine });
+      continue;
+    }
+
+    const [rawPath, rawRemainder] = partitionOnColon(line);
+    const workspacePath = rawPath.trim();
+    const remainder = rawRemainder.trim();
+    const resume = resolveResumeMetadata({ resumeCommand: remainder });
+
+    entries.push({
+      lineNumber,
+      rawLine,
+      path: workspacePath,
+      remainder,
+      sessionId: resume.resumeSessionId,
+      resumeCommand: resume.resumeCommand,
+      resumeTool: resume.resumeTool,
+      title: null,
+      tmuxSessionName: null,
+    });
+  }
+
+  return { entries, skipped, manifest: null, parseMode: "notes" };
+}
+
+export function parseWorkspaceSource(source) {
+  if (source.workspaceManifest) {
+    const manifest = normalizeWorkspaceManifest(source.workspaceManifest);
+    return {
+      entries: manifest.tabs,
+      skipped: [],
+      manifest,
+      parseMode: "manifest",
+    };
+  }
+
+  const structuredManifest = extractStructuredWorkspaceFromNotes(source.notes || "");
+  if (structuredManifest) {
+    return {
+      entries: structuredManifest.tabs,
+      skipped: [],
+      manifest: structuredManifest,
+      parseMode: "manifest",
+    };
+  }
+
+  return parseCorePlanNotes(source.notes || "");
+}
+
+export function buildDirectCommand(entry, options = {}) {
+  const commands = [`cd ${shellQuote(entry.path)}`];
+  const resumeCommand = options.resume !== false ? getResumeCommand(entry) : null;
+  if (resumeCommand) {
+    commands.push(resumeCommand);
+  }
+  return commands.join(" && ");
+}
+
+export function buildTmuxPresentationCommands(entry, options = {}) {
+  const sessionName = options.sessionName || deriveTmuxSessionName(entry, options);
+  const quotedSession = shellQuote(sessionName);
+  const targetWindow = `${quotedSession}:0`;
+  const title = options.displayTitle || entry.displayTitle || deriveBaseTitle(entry);
+
+  return [
+    `tmux set-option -t ${quotedSession} set-titles on`,
+    `tmux set-option -t ${quotedSession} set-titles-string ${shellQuote(title)}`,
+    `tmux set-window-option -t ${targetWindow} automatic-rename off`,
+    `tmux set-window-option -t ${targetWindow} allow-rename off`,
+    `tmux rename-window -t ${targetWindow} ${shellQuote(title)}`,
+  ];
+}
+
+export function buildTmuxCommand(entry, options = {}) {
+  const sessionName = options.sessionName || deriveTmuxSessionName(entry, options);
+  const sessionNameQuoted = shellQuote(sessionName);
+  const loginShell = options.loginShell || process.env.SHELL || "/bin/zsh";
+  const bootstrapCommand = `cd ${shellQuote(entry.path)} && exec ${shellQuote(loginShell)} -l`;
+  const presentationCommands = buildTmuxPresentationCommands(entry, { ...options, sessionName });
+  const createParts = [
+    `tmux new-session -d -s ${sessionNameQuoted} ${shellQuote(bootstrapCommand)}`,
+    ...presentationCommands,
+  ];
+
+  const resumeCommand = options.resume !== false ? getResumeCommand(entry) : null;
+  if (resumeCommand) {
+    createParts.push(
+      `tmux send-keys -t ${sessionNameQuoted} ${shellQuote(resumeCommand)} C-m`,
+    );
+  }
+
+  return [
+    `if tmux has-session -t ${sessionNameQuoted} 2>/dev/null; then`,
+    `${presentationCommands.join(" && ")} && tmux attach-session -t ${sessionNameQuoted};`,
+    "else",
+    `${createParts.join(" && ")} && tmux attach-session -t ${sessionNameQuoted};`,
+    "fi",
+  ].join(" ");
+}
+
+export function buildLaunchPlan(entries, options = {}) {
+  const titleCounts = new Map();
+
+  return entries.map((entry) => {
+    const baseTitle = deriveBaseTitle(entry);
+    const occurrence = (titleCounts.get(baseTitle) || 0) + 1;
+    titleCounts.set(baseTitle, occurrence);
+
+    const title = occurrence === 1 ? baseTitle : `${baseTitle} (${occurrence})`;
+    const sessionName = options.tmux ? deriveTmuxSessionName(entry, options) : null;
+    // iTerm already appends "(tmux)" when a tab is backed by a tmux session,
+    // so the title we push into tmux should stay clean.
+    const displayTitle = title;
+    const command = options.tmux
+      ? buildTmuxCommand(entry, { ...options, sessionName, displayTitle })
+      : buildDirectCommand(entry, options);
+
+    return {
+      ...entry,
+      title,
+      displayTitle,
+      sessionName,
+      command,
+      mode: options.tmux ? "tmux" : "direct",
+    };
+  });
+}
+
+export function summarizeLaunchPlan(plan) {
+  const terminalLabel = plan.terminalApp === "terminal" ? "Terminal.app" : "iTerm";
+  const lines = [
+    `Source: ${plan.sourceLabel}`,
+    `Workspace ID: ${plan.workspaceId}`,
+    `Tabs: ${plan.tabs.length}`,
+    `Mode: ${plan.tmux ? `${terminalLabel} + tmux` : `${terminalLabel} direct`}`,
+    `Parse mode: ${plan.parseMode}`,
+    "",
+  ];
+
+  for (const [index, tab] of plan.tabs.entries()) {
+    lines.push(`${String(index + 1).padStart(2, "0")}. ${tab.title}`);
+    lines.push(`    path: ${tab.path}`);
+    if (tab.resumeCommand) {
+      lines.push(`    resume: ${tab.resumeCommand}`);
+    }
+    if (tab.sessionName) {
+      lines.push(`    tmux: ${tab.sessionName}`);
+    }
+    lines.push(`    command: ${tab.command}`);
+  }
+
+  if (plan.skipped.length > 0) {
+    lines.push("");
+    lines.push("Skipped lines:");
+    for (const skipped of plan.skipped) {
+      lines.push(`  line ${skipped.lineNumber}: ${skipped.rawLine}`);
+    }
+  }
+
+  return lines.join("\n");
+}