open-research-protocol 0.4.23 → 0.4.25

package/docs/AGENT_RUNTIME_BORROWING_NOTES.md

@@ -0,0 +1,68 @@
+# Agent Runtime Borrowing Notes
+
+ORP should watch fast-moving personal-agent runtimes such as Hermes Agent and
+OpenClaw as design references, not as replacements for the ORP state model.
+Their strongest lesson is that users want one reachable assistant surface across
+CLI, mobile, messaging, schedulers, and remote machines. ORP's role is to make
+that assistant surface durable, governable, and recoverable.
+
+The architectural boundary is:
+
+```text
+Clawdad = entry point and operator surface
+ORP = durable workspace state, routing ledger, agenda, governance, packets, and checkpoints
+Agent runtimes = execution backends, gateways, sandboxes, schedulers, or transports
+Project artifacts = evidence
+```
+
+Hermes/OpenClaw-style systems can inspire ORP features, but they should not
+become parallel ledgers. ORP remains the canonical place for workspace tabs,
+linked sessions, runner state, operating agendas, opportunities, connections,
+repo governance, checkpoints, and research packets.
+
+## Ideas Worth Borrowing
+
+- Gateway ergonomics: simplify setup for phone, chat, and always-on entrypoints
+  while preserving ORP's local-first and hosted-linked records.
+- Skills and capability packs: expose small, auditable ORP command groups that
+  agents can load for specific jobs instead of handing them the whole machine.
+- Background process signals: let long-running builds, scans, and research jobs
+  notify the current agent/session when they finish or hit watched output.
+- Model and provider routing: study runtime-level provider switching while
+  keeping ORP's routing records independent of any one model vendor.
+- Subagent isolation: borrow fresh-context worker patterns, but record only the
+  resulting task state, evidence paths, and handoff summaries in ORP.
+- Local dashboards: use dashboards as visibility layers over ORP state, not as
+  a second source of workspace truth.
+- Backup/import flows: make ORP's machine state, linked sessions, and local
+  workspace ledgers easier to inspect, export, and restore.
+- Security hardening: preserve strict boundaries for remote control, including
+  allowlists, sandboxed command execution, explicit secret scoping, and clear
+  approval points.
+
+## Design Guardrails
+
+- ORP files are process-only and remain separate from evidence.
+- Messaging platforms must not own the durable agenda or project ledger.
+- Agent memories may summarize preferences or conversation context, but ORP owns
+  project routing, governance, and operational state.
+- Any borrowed gateway or scheduler behavior should write back to ORP through
+  explicit commands, not mutate hidden state.
+- A new surface is acceptable only if an operator can still recover the work
+  from ORP without knowing which agent runtime handled it.
+
+## First Useful Adapter
+
+A good borrowing experiment is an ORP skill or bridge for an external agent
+runtime with read-first commands:
+
+- `orp home --json`
+- `orp agenda focus`
+- `orp workspace tabs main`
+- `orp runner status --json`
+- `orp link status --json`
+- `orp youtube inspect <url> --json`
+
+The next layer can add carefully scoped writes such as registering a session,
+emitting a checkpoint, or dispatching through Clawdad, but only after the read
+surface proves useful and safe.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-research-protocol",
-  "version": "0.4.23",
+  "version": "0.4.25",
   "description": "ORP CLI (Open Research Protocol): workspace ledgers, secrets, scheduling, governed execution, and agent-friendly research workflows.",
   "license": "MIT",
   "author": "Fractal Research Group <cody@frg.earth>",
@@ -28,6 +28,7 @@
     "spec/",
     "templates/",
     "AGENT_INTEGRATION.md",
+    "CHANGELOG.md",
     "INSTALL.md",
     "LICENSE",
     "PROTOCOL.md",

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

@@ -44,10 +44,13 @@ export { runWorkspaceSlot } from "./slot.js";
 export { buildWorkspaceTabsReport, parseWorkspaceTabsArgs, runWorkspaceTabs, summarizeWorkspaceTabs } from "./tabs.js";
 export {
   buildWorkspaceManifestFromHostedWorkspacePayload,
+  createHostedWorkspaceForIdea,
   fetchHostedWorkspacePayload,
   fetchIdeaPayload,
   fetchIdeasPayload,
   fetchHostedWorkspacesPayload,
+  findHostedWorkspaceByLinkedIdea,
+  findHostedWorkspaceLinkedToIdea,
   loadWorkspaceSource,
   pushHostedWorkspaceState,
   chooseImplicitMainCandidate,

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

@@ -14,12 +14,12 @@ import {
 import { buildHostedWorkspaceState } from "./hosted-state.js";
 import {
   buildWorkspaceManifestFromHostedWorkspacePayload,
-  fetchIdeaPayload,
+  createHostedWorkspaceForIdea,
   fetchHostedWorkspacePayload,
+  findHostedWorkspaceByLinkedIdea,
   loadWorkspaceSource,
   pushHostedWorkspaceState,
   resolveWorkspaceWatchTargets,
-  updateIdeaPayload,
 } from "./orp.js";
 import {
   cacheManagedWorkspaceManifest,
@@ -28,7 +28,7 @@ import {
   registerWorkspaceManifest,
   setWorkspaceSlot,
 } from "./registry.js";
-import { buildWorkspaceSyncPreview, resolveWorkspaceSyncTargetIdeaId, validateWorkspaceTitle } from "./sync.js";
+import { validateWorkspaceTitle } from "./sync.js";
 
 function normalizeOptionalString(value) {
   if (value == null) {
@@ -125,6 +125,103 @@ function materializeWorkspaceManifest(manifest) {
   );
 }
 
+function getObjectValue(record, ...keys) {
+  for (const key of keys) {
+    const value = record?.[key];
+    if (value && typeof value === "object" && !Array.isArray(value)) {
+      return value;
+    }
+  }
+  return null;
+}
+
+function getHostedWorkspaceId(workspace) {
+  return normalizeOptionalString(workspace?.workspace_id ?? workspace?.workspaceId ?? workspace?.id);
+}
+
+function getHostedWorkspaceTitle(workspace) {
+  return normalizeOptionalString(workspace?.title) || getHostedWorkspaceId(workspace);
+}
+
+function buildHostedWorkspaceSlotAssignment(workspace) {
+  const workspaceId = getHostedWorkspaceId(workspace);
+  if (!workspaceId) {
+    return null;
+  }
+  const title = getHostedWorkspaceTitle(workspace);
+  return {
+    kind: "hosted-workspace",
+    selector: title || workspaceId,
+    workspaceId,
+    title: title || undefined,
+    hostedWorkspaceId: workspaceId,
+  };
+}
+
+function buildWorkspaceFileSlotAssignment(manifest, manifestPath) {
+  const workspaceId = normalizeOptionalString(manifest?.workspaceId);
+  const title = normalizeOptionalString(manifest?.title) || workspaceId || undefined;
+  return {
+    kind: "workspace-file",
+    selector: title || workspaceId || manifestPath,
+    workspaceId: workspaceId || undefined,
+    title,
+    manifestPath,
+  };
+}
+
+async function assignMatchingWorkspaceSlots(source, manifest, assignment, options = {}) {
+  if (!assignment) {
+    return {};
+  }
+
+  const slotNames = new Set();
+  if (source.resolvedSlotName) {
+    slotNames.add(source.resolvedSlotName);
+  }
+
+  const sourceWorkspaceIds = new Set(
+    [
+      manifest?.workspaceId,
+      source.workspaceManifest?.workspaceId,
+      getHostedWorkspaceId(source.hostedWorkspace),
+      source.hostedWorkspaceId,
+    ]
+      .map((value) => normalizeOptionalString(value))
+      .filter(Boolean),
+  );
+  const sourcePaths = new Set(
+    [source.sourcePath, assignment.manifestPath]
+      .map((value) => normalizeOptionalString(value))
+      .filter(Boolean)
+      .map((value) => path.resolve(value)),
+  );
+
+  const slotsResult = await loadWorkspaceSlots(options).catch(() => ({ slots: {} }));
+  for (const [slotName, slot] of Object.entries(slotsResult.slots || {})) {
+    if (!slot || typeof slot !== "object" || Array.isArray(slot)) {
+      continue;
+    }
+    const slotIds = [
+      slot.workspaceId,
+      slot.hostedWorkspaceId,
+      slot.selector,
+    ]
+      .map((value) => normalizeOptionalString(value))
+      .filter(Boolean);
+    const slotPath = normalizeOptionalString(slot.manifestPath);
+    if (slotIds.some((value) => sourceWorkspaceIds.has(value)) || (slotPath && sourcePaths.has(path.resolve(slotPath)))) {
+      slotNames.add(slotName);
+    }
+  }
+
+  const assignedSlots = {};
+  for (const slotName of slotNames) {
+    assignedSlots[slotName] = (await setWorkspaceSlot(slotName, assignment, options)).slot;
+  }
+  return assignedSlots;
+}
+
 function normalizeEditableManifest(source, parsed) {
   const baseManifest = parsed.manifest
     ? {
@@ -179,6 +276,51 @@ function normalizeEditableManifest(source, parsed) {
   return normalizeWorkspaceManifest(baseManifest);
 }
 
+async function findOrCreateHostedWorkspaceForIdea(ideaId, source, manifest, options = {}) {
+  const existingWorkspace = await findHostedWorkspaceByLinkedIdea(ideaId, options);
+  if (existingWorkspace) {
+    return {
+      workspace: existingWorkspace,
+      created: false,
+    };
+  }
+
+  const linkedIdea =
+    source.sourceType === "hosted-idea"
+      ? source.idea
+      : getObjectValue(source.hostedWorkspace, "linked_idea", "linkedIdea");
+  const title =
+    manifest.title ||
+    manifest.workspaceId ||
+    source.title ||
+    normalizeOptionalString(linkedIdea?.idea_title ?? linkedIdea?.ideaTitle) ||
+    normalizeOptionalString(linkedIdea?.title) ||
+    ideaId;
+  const created = await createHostedWorkspaceForIdea({ title, ideaId }, options);
+  return {
+    workspace: created.workspace,
+    created: true,
+    createdPayload: created,
+  };
+}
+
+async function persistIdeaBackedWorkspaceToLocalCache(ideaId, source, manifest, reason, options = {}) {
+  const managedCache = await cacheManagedWorkspaceManifest(manifest, options);
+  const assignment = buildWorkspaceFileSlotAssignment(manifest, managedCache.manifestPath);
+  const assignedSlots = await assignMatchingWorkspaceSlots(source, manifest, assignment, options);
+  return {
+    persistedTo: "workspace-file",
+    ideaId,
+    promotedFromIdeaId: ideaId,
+    hostedMigrationSkippedReason: reason instanceof Error ? reason.message : String(reason || "Hosted workspace API unavailable."),
+    manifestPath: managedCache.manifestPath,
+    registryPath: managedCache.registryPath,
+    assignedSlots,
+    managedCache,
+    manifest,
+  };
+}
+
 function parseLedgerSelectorArgs(
   argv = [],
   { commandName, requirePath = false, requireSelector = true, allowAppend = false, allowHere = false, allowCurrentCodex = false } = {},
@@ -593,40 +735,46 @@ async function persistWorkspaceManifest(source, manifest, options = {}) {
   }
 
   if (watchTargets.syncIdeaSelector) {
-    const targetSource = await loadWorkspaceSource({
-      ...options,
-      ideaId: watchTargets.syncIdeaSelector,
-    });
-    const targetIdeaId = resolveWorkspaceSyncTargetIdeaId(targetSource);
-    if (!targetIdeaId) {
-      throw new Error(`Workspace source does not resolve to a syncable hosted idea: ${watchTargets.syncIdeaSelector}`);
+    const ideaId = watchTargets.syncIdeaSelector;
+    let promoted;
+    try {
+      promoted = await findOrCreateHostedWorkspaceForIdea(ideaId, source, manifest, options);
+    } catch (error) {
+      return persistIdeaBackedWorkspaceToLocalCache(ideaId, source, manifest, error, options);
     }
-    const targetPayload =
-      targetSource.sourceType === "hosted-idea" && targetSource.idea?.id === targetIdeaId
-        ? targetSource.payload
-        : await fetchIdeaPayload(targetIdeaId, options);
-    const liveSource = {
-      sourceType: "workspace-file",
-      sourceLabel: `edited-workspace:${watchTargets.syncIdeaSelector}`,
-      title: manifest.title || manifest.workspaceId || source.title || watchTargets.syncIdeaSelector,
-      workspaceManifest: manifest,
-      notes: "",
-    };
-    const parsed = parseWorkspaceSource(liveSource);
-    const preview = buildWorkspaceSyncPreview({
-      source: liveSource,
-      parsed,
-      targetIdea: targetPayload.idea,
-      workspaceTitle: manifest.title || manifest.workspaceId || undefined,
+    const workspaceId = getHostedWorkspaceId(promoted.workspace);
+    if (!workspaceId) {
+      throw new Error(`Hosted workspace for idea ${ideaId} did not include a workspace id.`);
+    }
+
+    const previousWorkspace = promoted.created
+      ? promoted.workspace
+      : (await fetchHostedWorkspacePayload(workspaceId, options)).workspace;
+    const state = buildHostedWorkspaceState(manifest, {
+      previousWorkspace,
+      capturedAt: manifest.capture?.capturedAt,
+      updatedAt: new Date().toISOString(),
     });
-    const updatedIdea = await updateIdeaPayload(targetIdeaId, { notes: preview.nextNotes }, options);
-    const managedCache = await cacheManagedWorkspaceManifest(preview.manifest, options);
+    const pushResult = await pushHostedWorkspaceState(workspaceId, state, options);
+    const cachedManifest = buildWorkspaceManifestFromHostedWorkspacePayload(pushResult);
+    const managedCache = await cacheManagedWorkspaceManifest(cachedManifest, options);
+    const workspaceForSlot = pushResult.workspace || promoted.workspace;
+    const assignedSlots = await assignMatchingWorkspaceSlots(
+      source,
+      cachedManifest,
+      buildHostedWorkspaceSlotAssignment(workspaceForSlot),
+      options,
+    );
     return {
-      persistedTo: "hosted-idea",
-      ideaId: targetIdeaId,
-      updatedIdea,
+      persistedTo: "hosted-workspace",
+      ideaId,
+      promotedFromIdeaId: ideaId,
+      createdHostedWorkspace: promoted.created,
+      workspaceId,
+      pushResult,
+      assignedSlots,
       managedCache,
-      manifest: preview.manifest,
+      manifest: cachedManifest,
     };
   }
 
@@ -780,8 +928,14 @@ function summarizeWorkspaceLedgerMutation(result) {
     lines.push(`Canonical source: ORP idea ${result.ideaId}`);
   } else if (result.persistedTo === "hosted-workspace") {
     lines.push(`Canonical source: hosted workspace ${result.workspaceId}`);
+    if (result.promotedFromIdeaId) {
+      lines.push(`Linked idea: ${result.promotedFromIdeaId}`);
+    }
   } else if (result.persistedTo === "workspace-file") {
     lines.push(`Saved file: ${result.manifestPath}`);
+    if (result.hostedMigrationSkippedReason) {
+      lines.push(`Hosted migration skipped: ${result.hostedMigrationSkippedReason}`);
+    }
   }
 
   if (result.managedCachePath) {
@@ -809,9 +963,14 @@ async function runWorkspaceLedgerMutation(options, mutate, action) {
     removedTabs: (mutated.removedTabs || []).map((tab) => buildWorkspaceResultTab(tab)),
     persistedTo: persisted.persistedTo,
     ideaId: persisted.ideaId || null,
+    promotedFromIdeaId: persisted.promotedFromIdeaId || null,
+    createdHostedWorkspace: persisted.createdHostedWorkspace || false,
+    hostedMigrationSkippedReason: persisted.hostedMigrationSkippedReason || null,
     workspaceSourceId: persisted.workspaceId || null,
     manifestPath: persisted.manifestPath || null,
     managedCachePath: persisted.managedCache?.manifestPath || null,
+    assignedSlot: persisted.assignedSlot || Object.values(persisted.assignedSlots || {})[0] || null,
+    assignedSlots: persisted.assignedSlots || null,
     manifest: finalManifest,
   };
 

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

@@ -197,6 +197,59 @@ export async function fetchHostedWorkspacesPayload(options = {}) {
   };
 }
 
+export function findHostedWorkspaceLinkedToIdea(workspaces = [], ideaId) {
+  const targetIdeaId = normalizeOptionalString(ideaId);
+  if (!targetIdeaId || !Array.isArray(workspaces)) {
+    return null;
+  }
+
+  return (
+    workspaces.find((workspace) => {
+      if (!workspace || typeof workspace !== "object" || Array.isArray(workspace)) {
+        return false;
+      }
+      const sourceKind = normalizeOptionalString(workspace.source_kind ?? workspace.sourceKind) || "hosted";
+      if (sourceKind === "idea_bridge") {
+        return false;
+      }
+      const linkedIdea = getObjectValue(workspace, "linked_idea", "linkedIdea");
+      return getTextValue(linkedIdea, "idea_id", "ideaId") === targetIdeaId;
+    }) || null
+  );
+}
+
+export async function findHostedWorkspaceByLinkedIdea(ideaId, options = {}) {
+  const payload = await fetchHostedWorkspacesPayload(options);
+  return findHostedWorkspaceLinkedToIdea(payload.workspaces, ideaId);
+}
+
+export async function createHostedWorkspaceForIdea({ title, ideaId, description = null, visibility = null } = {}, options = {}) {
+  const workspaceTitle = slugify(title) || (ideaId ? `workspace-${String(ideaId).slice(0, 8).toLowerCase()}` : "workspace");
+  const invocation = resolveOrpInvocation(options);
+  const args = [...invocation.prefixArgs, "workspaces", "add", "--title", workspaceTitle];
+  if (description != null) {
+    args.push("--description", String(description));
+  }
+  if (visibility != null) {
+    args.push("--visibility", String(visibility));
+  }
+  const linkedIdeaId = normalizeOptionalString(ideaId);
+  if (linkedIdeaId) {
+    args.push("--idea-id", linkedIdeaId);
+  }
+  if (options.baseUrl) {
+    args.push("--base-url", options.baseUrl);
+  }
+  args.push("--json");
+
+  const result = await runCommand(invocation.command, args, options);
+  const payload = parseOrpJsonResult(result, "Failed to create ORP hosted workspace.");
+  if (!payload || payload.ok !== true || !payload.workspace) {
+    throw new Error("ORP returned an unexpected hosted workspace creation payload.");
+  }
+  return payload;
+}
+
 function buildWorkspaceTitleFromIdea(idea, manifest) {
   return normalizeOptionalString(manifest?.title) || normalizeOptionalString(idea?.title) || null;
 }
@@ -857,12 +910,19 @@ export async function loadWorkspaceSource(options = {}) {
   const selector = options.ideaId;
   const slotTarget = await resolveWorkspaceSlotTarget(selector, options);
   if (slotTarget?.target) {
-    return loadWorkspaceSource({
+    const resolvedSource = await loadWorkspaceSource({
       ...options,
       ideaId: slotTarget.target.ideaId,
       workspaceFile: slotTarget.target.workspaceFile,
       hostedWorkspaceId: slotTarget.target.hostedWorkspaceId,
     });
+    return {
+      ...resolvedSource,
+      resolvedSlotName: slotTarget.slotName,
+      resolvedSlotMode: slotTarget.mode,
+      resolvedSlot: slotTarget.slot || null,
+      resolvedSlotCandidate: slotTarget.candidate || null,
+    };
   }
   if (slotTarget?.slotName && slotTarget.mode === "unset") {
     throw new Error(

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

@@ -1,3 +1,6 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
 import process from "node:process";
 
 import {
@@ -12,6 +15,144 @@ import {
 } from "./core-plan.js";
 import { loadWorkspaceSource } from "./orp.js";
 
+const SESSION_ID_PATTERN = /[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}/gi;
+
+function normalizeOptionalString(value) {
+  if (value == null) {
+    return null;
+  }
+  const trimmed = String(value).trim();
+  return trimmed.length > 0 ? trimmed : null;
+}
+
+function resolveCodexHome(options = {}) {
+  return (
+    normalizeOptionalString(options.codexHome) ||
+    normalizeOptionalString(process.env.CODEX_HOME) ||
+    path.join(os.homedir(), ".codex")
+  );
+}
+
+function collectCodexSessionIds(tabs = []) {
+  return new Set(
+    tabs
+      .filter((tab) => tab.resumeTool === "codex")
+      .map((tab) => normalizeOptionalString(tab.sessionId))
+      .map((sessionId) => sessionId?.toLowerCase())
+      .filter(Boolean),
+  );
+}
+
+function sessionIdsInFilename(filename, wantedSessionIds) {
+  const matches = new Set();
+  for (const match of filename.matchAll(SESSION_ID_PATTERN)) {
+    const sessionId = match[0].toLowerCase();
+    if (wantedSessionIds.has(sessionId)) {
+      matches.add(sessionId);
+    }
+  }
+
+  if (matches.size > 0) {
+    return matches;
+  }
+
+  for (const sessionId of wantedSessionIds) {
+    if (filename.includes(sessionId)) {
+      matches.add(sessionId);
+    }
+  }
+  return matches;
+}
+
+function rememberActivity(activityBySessionId, sessionId, filePath, stat) {
+  const current = activityBySessionId.get(sessionId);
+  if (!current || stat.mtimeMs > current.mtimeMs) {
+    activityBySessionId.set(sessionId, {
+      mtimeMs: stat.mtimeMs,
+      filePath,
+    });
+  }
+}
+
+function scanActivityDirectory(rootDir, wantedSessionIds, activityBySessionId) {
+  let entries;
+  try {
+    entries = fs.readdirSync(rootDir, { withFileTypes: true });
+  } catch {
+    return;
+  }
+
+  for (const entry of entries) {
+    const entryPath = path.join(rootDir, entry.name);
+    if (entry.isDirectory()) {
+      scanActivityDirectory(entryPath, wantedSessionIds, activityBySessionId);
+      continue;
+    }
+    if (!entry.isFile()) {
+      continue;
+    }
+
+    const matchingSessionIds = sessionIdsInFilename(entry.name, wantedSessionIds);
+    if (matchingSessionIds.size === 0) {
+      continue;
+    }
+
+    let stat;
+    try {
+      stat = fs.statSync(entryPath);
+    } catch {
+      continue;
+    }
+    for (const sessionId of matchingSessionIds) {
+      rememberActivity(activityBySessionId, sessionId, entryPath, stat);
+    }
+  }
+}
+
+function buildCodexActivityIndex(tabs = [], options = {}) {
+  const wantedSessionIds = collectCodexSessionIds(tabs);
+  if (wantedSessionIds.size === 0) {
+    return new Map();
+  }
+
+  const activityBySessionId = new Map();
+  const codexHome = resolveCodexHome(options);
+  scanActivityDirectory(path.join(codexHome, "sessions"), wantedSessionIds, activityBySessionId);
+  scanActivityDirectory(path.join(codexHome, "shell_snapshots"), wantedSessionIds, activityBySessionId);
+  return activityBySessionId;
+}
+
+function orderTabsByRecentActivity(tabs = [], options = {}) {
+  const activityBySessionId = buildCodexActivityIndex(tabs, options);
+  const rankedTabs = tabs.map((tab, originalIndex) => {
+    const sessionActivity =
+      tab.resumeTool === "codex" && tab.sessionId ? activityBySessionId.get(String(tab.sessionId).toLowerCase()) : null;
+    return {
+      tab,
+      originalIndex,
+      activityMs: sessionActivity?.mtimeMs || 0,
+    };
+  });
+
+  const projectActivity = new Map();
+  for (const ranked of rankedTabs) {
+    const current = projectActivity.get(ranked.tab.path) || 0;
+    projectActivity.set(ranked.tab.path, Math.max(current, ranked.activityMs));
+  }
+
+  return rankedTabs
+    .sort((left, right) => {
+      const leftProjectActivity = projectActivity.get(left.tab.path) || 0;
+      const rightProjectActivity = projectActivity.get(right.tab.path) || 0;
+      return (
+        rightProjectActivity - leftProjectActivity ||
+        right.activityMs - left.activityMs ||
+        left.originalIndex - right.originalIndex
+      );
+    })
+    .map((ranked) => ranked.tab);
+}
+
 export function parseWorkspaceTabsArgs(argv = []) {
   const options = {
     json: false,
@@ -64,7 +205,8 @@ export function buildWorkspaceTabsReport(source, parsed, options = {}) {
     tmux: false,
     resume: true,
   });
-  const projectGroups = buildWorkspaceProjectGroups(launchTabs);
+  const orderedLaunchTabs = orderTabsByRecentActivity(launchTabs, options);
+  const projectGroups = buildWorkspaceProjectGroups(orderedLaunchTabs);
 
   return {
     sourceType: source.sourceType,
@@ -73,7 +215,7 @@ export function buildWorkspaceTabsReport(source, parsed, options = {}) {
     workspaceId: deriveWorkspaceId(source, parsed),
     machine: parsed.manifest?.machine || null,
     parseMode: parsed.parseMode,
-    tabCount: launchTabs.length,
+    tabCount: orderedLaunchTabs.length,
     projectCount: projectGroups.length,
     skippedCount: parsed.skipped.length,
     projects: projectGroups.map((project) => ({
@@ -92,7 +234,7 @@ export function buildWorkspaceTabsReport(source, parsed, options = {}) {
         ),
       })),
     })),
-    tabs: launchTabs.map((tab, index) => ({
+    tabs: orderedLaunchTabs.map((tab, index) => ({
       index: index + 1,
       title: tab.title,
       path: tab.path,
@@ -191,7 +333,8 @@ Options:
   -h, --help              Show this help text
 
 Notes:
-  - This shows the saved tab order plus any stored local path, remote repo, bootstrap command, and \`codex resume ...\` / \`claude --resume ...\` metadata.
+  - This shows activity-ranked saved tabs plus any stored local path, remote repo, bootstrap command, and \`codex resume ...\` / \`claude --resume ...\` metadata.
+  - Codex-backed tabs are ranked by the latest matching local session or shell snapshot activity; ties keep the saved ledger order.
   - JSON output includes grouped \`projects[].sessions[]\` so duplicate project paths can be reviewed and sunset together.
   - 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.