open-research-protocol 0.4.34 → 0.4.35

package/CHANGELOG.md

@@ -6,6 +6,32 @@ There was no prior in-repo changelog file, so the first formal entry starts
 with the currently shipped `v0.4.4` release and summarizes the full release
 delta reflected in this repo.
 
+## v0.4.35 - 2026-04-30
+
+This release makes the hosted workspace sync contract canonical from the ORP
+CLI side, so hosted ORP can render the same projects, resume sessions, plans,
+and tasks that local workspace tooling sees.
+
+### Added
+
+- Added local workspace inventory reconciliation for `orp workspace sync`,
+  starting from the selected workspace ledger and refreshing known projects
+  from ORP startup state, Clawdad state, and recent Codex session metadata.
+- Added hosted workspace state push support that carries per-project sync
+  metadata, linked ORP idea/feature ids, plan summaries, and task lists.
+- Added a hosted workspace sync contract document covering the canonical
+  source order and required hosted payload fields.
+
+### Changed
+
+- `orp workspace sync main` now bridges a local managed workspace file to the
+  matching hosted workspace by durable `workspaceId` before pushing state.
+- Hosted workspace sync skips the idea-note compatibility mirror when the
+  hosted workspace state can be written directly, avoiding stale or truncated
+  plan/task payloads.
+- Workspace manifests now round-trip activity timestamps, sync timestamps,
+  sync source labels, plan data, tasks, and linked ORP project references.
+
 ## v0.4.34 - 2026-04-30
 
 This release connects ORP frontier plans to hosted ORP ideas/features and lets

package/docs/ORP_HOSTED_WORKSPACE_CONTRACT.md

@@ -27,6 +27,45 @@ The canonical hosted source of truth should be one hosted workspace record:
 
 Idea notes are a compatibility bridge only after this contract lands.
 
+## CLI Sync Contract
+
+`orp workspace sync <selector>` is the canonical local-to-hosted sync path.
+The web app should render the hosted workspace state produced by this command,
+not reconstruct a competing workspace model.
+
+The local canonical input is a reconciled workspace snapshot:
+
+1. Start with the selected ORP workspace ledger, usually
+   `orp workspace tabs main`.
+2. If that selector resolves to a local workspace file, match a hosted
+   workspace by the same `workspaceId` before writing hosted state.
+3. Reconcile known local projects from ORP project startup state
+   (`orp/state.json`, including historical startup result manifests).
+4. Use Clawdad state only to refresh projects already known from the ledger or
+   ORP startup manifests, unless a caller explicitly opts into Clawdad-only
+   projects.
+5. Use recent Codex session metadata to refresh known project paths with the
+   newest local `codex resume ...` session. Codex-only paths are not added by
+   default.
+
+The pushed hosted state must include, for every project/tab where available:
+
+- `title`
+- `project_root` / local `path`
+- resume command plus structured `resume_tool` and `resume_session_id`
+- `last_activity_at_utc`
+- `last_synced_at_utc`
+- `linked_idea_id`
+- `linked_feature_id`
+- `plan`
+- `tasks`
+
+Idea notes are only a compatibility mirror. When sync can write the matched
+hosted workspace state directly, the hosted workspace `state` is authoritative
+and the idea-note mirror may be skipped to avoid truncating or conflicting with
+the full payload. If no hosted workspace target exists, sync may still write a
+compact ` ```orp-workspace ` block to the linked idea.
+
 ## Resource Model
 
 ### Hosted Workspace

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "open-research-protocol",
-  "version": "0.4.34",
+  "version": "0.4.35",
   "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>",

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

@@ -267,6 +267,12 @@ function normalizeStructuredTab(rawTab, index) {
   const tmuxSessionName = normalizeOptionalString(rawTab.tmuxSessionName);
   const plan = rawTab.plan && typeof rawTab.plan === "object" && !Array.isArray(rawTab.plan) ? rawTab.plan : null;
   const tasks = Array.isArray(rawTab.tasks) ? rawTab.tasks : [];
+  const lastActivityAt = normalizeOptionalString(
+    rawTab.lastActivityAt ?? rawTab.last_activity_at_utc ?? rawTab.lastActivityAtUtc,
+  );
+  const lastSyncedAt = normalizeOptionalString(
+    rawTab.lastSyncedAt ?? rawTab.last_synced_at_utc ?? rawTab.lastSyncedAtUtc,
+  );
 
   return {
     lineNumber: index + 1,
@@ -285,6 +291,9 @@ function normalizeStructuredTab(rawTab, index) {
     linkedFeatureId: normalizeOptionalString(rawTab.linkedFeatureId ?? rawTab.linked_feature_id),
     plan,
     tasks,
+    lastActivityAt,
+    lastSyncedAt,
+    syncSource: normalizeOptionalString(rawTab.syncSource ?? rawTab.sync_source),
   };
 }
 
@@ -321,6 +330,21 @@ function normalizeStructuredProject(rawProject, projectIndex) {
           rawProject.linked_feature_id,
         plan: rawSession.plan ?? rawProject.plan,
         tasks: rawSession.tasks ?? rawProject.tasks,
+        lastActivityAt:
+          rawSession.lastActivityAt ??
+          rawSession.last_activity_at_utc ??
+          rawSession.lastActivityAtUtc ??
+          rawProject.lastActivityAt ??
+          rawProject.last_activity_at_utc ??
+          rawProject.lastActivityAtUtc,
+        lastSyncedAt:
+          rawSession.lastSyncedAt ??
+          rawSession.last_synced_at_utc ??
+          rawSession.lastSyncedAtUtc ??
+          rawProject.lastSyncedAt ??
+          rawProject.last_synced_at_utc ??
+          rawProject.lastSyncedAtUtc,
+        syncSource: rawSession.syncSource ?? rawSession.sync_source ?? rawProject.syncSource ?? rawProject.sync_source,
       },
       sessionIndex,
     );
@@ -399,6 +423,8 @@ export function buildWorkspaceProjectGroups(entries = []) {
         linkedFeatureId: normalizeOptionalString(entry.linkedFeatureId),
         plan: entry.plan && typeof entry.plan === "object" && !Array.isArray(entry.plan) ? entry.plan : null,
         tasks: Array.isArray(entry.tasks) && entry.tasks.length > 0 ? entry.tasks : [],
+        lastActivityAt: normalizeOptionalString(entry.lastActivityAt ?? entry.last_activity_at_utc),
+        lastSyncedAt: normalizeOptionalString(entry.lastSyncedAt ?? entry.last_synced_at_utc),
         sessions: [],
       });
     }
@@ -412,6 +438,8 @@ export function buildWorkspaceProjectGroups(entries = []) {
     project.plan =
       project.plan ||
       (entry.plan && typeof entry.plan === "object" && !Array.isArray(entry.plan) ? entry.plan : null);
+    project.lastActivityAt = project.lastActivityAt || normalizeOptionalString(entry.lastActivityAt ?? entry.last_activity_at_utc);
+    project.lastSyncedAt = project.lastSyncedAt || normalizeOptionalString(entry.lastSyncedAt ?? entry.last_synced_at_utc);
     if ((!Array.isArray(project.tasks) || project.tasks.length === 0) && Array.isArray(entry.tasks) && entry.tasks.length > 0) {
       project.tasks = entry.tasks;
     }
@@ -426,6 +454,8 @@ export function buildWorkspaceProjectGroups(entries = []) {
           resumeSessionId: resume.resumeSessionId || undefined,
           codexSessionId: resume.resumeTool === "codex" ? resume.resumeSessionId || undefined : undefined,
           claudeSessionId: resume.resumeTool === "claude" ? resume.resumeSessionId || undefined : undefined,
+          lastActivityAt: normalizeOptionalString(entry.lastActivityAt ?? entry.last_activity_at_utc) || undefined,
+          lastSyncedAt: normalizeOptionalString(entry.lastSyncedAt ?? entry.last_synced_at_utc) || undefined,
         }).filter(([, value]) => value !== undefined),
       ),
     );
@@ -443,6 +473,8 @@ export function buildWorkspaceProjectGroups(entries = []) {
         linkedFeatureId: project.linkedFeatureId || undefined,
         plan: project.plan || undefined,
         tasks: Array.isArray(project.tasks) && project.tasks.length > 0 ? project.tasks : undefined,
+        lastActivityAt: project.lastActivityAt || undefined,
+        lastSyncedAt: project.lastSyncedAt || undefined,
         sessionCount: project.sessions.length,
         sessions: project.sessions,
       }).filter(([, value]) => value !== undefined),

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

@@ -72,6 +72,7 @@ function normalizePreviousHostedTabs(workspace) {
       focusSummary: normalizeOptionalString(tab.focus_summary ?? tab.focusSummary),
       trajectorySummary: normalizeOptionalString(tab.trajectory_summary ?? tab.trajectorySummary),
       lastActivityAt: normalizeOptionalString(tab.last_activity_at_utc ?? tab.lastActivityAtUtc),
+      lastSyncedAt: normalizeOptionalString(tab.last_synced_at_utc ?? tab.lastSyncedAtUtc),
       linkedIdeaId: normalizeOptionalString(tab.linked_idea_id ?? tab.linkedIdeaId),
       linkedFeatureId: normalizeOptionalString(tab.linked_feature_id ?? tab.linkedFeatureId),
       plan: tab.plan && typeof tab.plan === "object" && !Array.isArray(tab.plan) ? tab.plan : null,
@@ -116,6 +117,8 @@ function buildHostedProjectGroups(tabs) {
         bootstrap_command: normalizeOptionalString(tab.bootstrap_command),
         linked_idea_id: normalizeOptionalString(tab.linked_idea_id),
         linked_feature_id: normalizeOptionalString(tab.linked_feature_id),
+        last_activity_at_utc: normalizeOptionalString(tab.last_activity_at_utc),
+        last_synced_at_utc: normalizeOptionalString(tab.last_synced_at_utc),
         plan: tab.plan && typeof tab.plan === "object" && !Array.isArray(tab.plan) ? tab.plan : undefined,
         tasks: Array.isArray(tab.tasks) ? tab.tasks : undefined,
         sessions: [],
@@ -127,6 +130,8 @@ function buildHostedProjectGroups(tabs) {
     project.bootstrap_command = project.bootstrap_command || normalizeOptionalString(tab.bootstrap_command);
     project.linked_idea_id = project.linked_idea_id || normalizeOptionalString(tab.linked_idea_id);
     project.linked_feature_id = project.linked_feature_id || normalizeOptionalString(tab.linked_feature_id);
+    project.last_activity_at_utc = project.last_activity_at_utc || normalizeOptionalString(tab.last_activity_at_utc);
+    project.last_synced_at_utc = project.last_synced_at_utc || normalizeOptionalString(tab.last_synced_at_utc);
     project.plan = project.plan || (tab.plan && typeof tab.plan === "object" && !Array.isArray(tab.plan) ? tab.plan : undefined);
     if ((!Array.isArray(project.tasks) || project.tasks.length === 0) && Array.isArray(tab.tasks) && tab.tasks.length > 0) {
       project.tasks = tab.tasks;
@@ -143,6 +148,8 @@ function buildHostedProjectGroups(tabs) {
           claude_session_id: normalizeOptionalString(tab.claude_session_id),
           status: normalizeOptionalString(tab.status),
           current_task: normalizeOptionalString(tab.current_task),
+          last_activity_at_utc: normalizeOptionalString(tab.last_activity_at_utc),
+          last_synced_at_utc: normalizeOptionalString(tab.last_synced_at_utc),
         }).filter(([, value]) => value !== undefined && value !== null),
       ),
     );
@@ -158,6 +165,8 @@ function buildHostedProjectGroups(tabs) {
         bootstrap_command: project.bootstrap_command || undefined,
         linked_idea_id: project.linked_idea_id || undefined,
         linked_feature_id: project.linked_feature_id || undefined,
+        last_activity_at_utc: project.last_activity_at_utc || undefined,
+        last_synced_at_utc: project.last_synced_at_utc || undefined,
         plan: project.plan || undefined,
         tasks: Array.isArray(project.tasks) && project.tasks.length > 0 ? project.tasks : undefined,
         session_count: project.sessions.length,
@@ -448,7 +457,7 @@ export function buildHostedWorkspaceState(manifest, options = {}) {
     const title = normalizeOptionalString(tab.title) || previous?.title || null;
     const projectRoot = normalizeOptionalString(tab.path);
     const projectContext = readProjectFrontierContext(projectRoot, projectContextCache);
-    const repoLabel = previous?.repoLabel || path.basename(String(projectRoot).replace(/\/+$/, "")) || projectRoot;
+    const repoLabel = title || previous?.repoLabel || path.basename(String(projectRoot).replace(/\/+$/, "")) || projectRoot;
     const terminalTitle = previous?.terminalTitle || title || repoLabel;
     const resume = resolveResumeMetadata({
       resumeCommand: tab.resumeCommand,
@@ -475,6 +484,27 @@ export function buildHostedWorkspaceState(manifest, options = {}) {
       title,
       orderIndex: index,
     });
+    const plan =
+      tab.plan && typeof tab.plan === "object" && !Array.isArray(tab.plan)
+        ? tab.plan
+        : projectContext?.plan || previous?.plan || undefined;
+    const tasks =
+      Array.isArray(tab.tasks) && tab.tasks.length > 0
+        ? tab.tasks
+        : Array.isArray(projectContext?.tasks) && projectContext.tasks.length > 0
+          ? projectContext.tasks
+          : Array.isArray(previous?.tasks) && previous.tasks.length > 0
+            ? previous.tasks
+            : undefined;
+    const lastActivityAt =
+      normalizeOptionalString(tab.lastActivityAt ?? tab.last_activity_at_utc ?? tab.lastActivityAtUtc) ||
+      previous?.lastActivityAt ||
+      undefined;
+    const lastSyncedAt =
+      normalizeOptionalString(tab.lastSyncedAt ?? tab.last_synced_at_utc ?? tab.lastSyncedAtUtc) ||
+      previous?.lastSyncedAt ||
+      updatedAt ||
+      undefined;
 
     return Object.fromEntries(
       Object.entries({
@@ -496,7 +526,9 @@ export function buildHostedWorkspaceState(manifest, options = {}) {
         current_task: previous?.currentTask || undefined,
         focus_summary: previous?.focusSummary || undefined,
         trajectory_summary: previous?.trajectorySummary || undefined,
-        last_activity_at_utc: previous?.lastActivityAt || undefined,
+        last_activity_at_utc: lastActivityAt,
+        last_synced_at_utc: lastSyncedAt,
+        sync_source: normalizeOptionalString(tab.syncSource ?? tab.sync_source) || undefined,
         linked_feature_id:
           normalizeOptionalString(tab.linkedFeatureId ?? tab.linked_feature_id) ||
           projectContext?.link?.activeFeatureId ||
@@ -507,13 +539,8 @@ export function buildHostedWorkspaceState(manifest, options = {}) {
           projectContext?.link?.ideaId ||
           previous?.linkedIdeaId ||
           undefined,
-        plan: projectContext?.plan || previous?.plan || undefined,
-        tasks:
-          Array.isArray(projectContext?.tasks) && projectContext.tasks.length > 0
-            ? projectContext.tasks
-            : Array.isArray(previous?.tasks) && previous.tasks.length > 0
-              ? previous.tasks
-              : undefined,
+        plan,
+        tasks,
       }).filter(([, value]) => value !== undefined && value !== null),
     );
   });
@@ -531,6 +558,10 @@ export function buildHostedWorkspaceState(manifest, options = {}) {
       durable_backend: options.durableBackend || "manual-ledger",
     }).filter(([, value]) => value !== undefined && value !== null),
   );
+  const sourceContract =
+    options.localInventory?.contract && typeof options.localInventory.contract === "object" && !Array.isArray(options.localInventory.contract)
+      ? options.localInventory.contract
+      : undefined;
 
   const stateVersion = Math.max(1, (getHostedIntegerValue(previousState, "state_version", "stateVersion") || 0) + 1);
   const snapshotSeed = JSON.stringify({
@@ -558,6 +589,7 @@ export function buildHostedWorkspaceState(manifest, options = {}) {
       tab_count: tabs.length,
       project_count: projects.length,
       capture_context: Object.keys(captureContext).length > 0 ? captureContext : undefined,
+      source_contract: sourceContract,
       projects,
       tabs,
     }).filter(([, value]) => value !== undefined && value !== null),

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

@@ -63,6 +63,7 @@ export {
   fetchIdeaPayload,
   fetchIdeasPayload,
   fetchHostedWorkspacesPayload,
+  findHostedWorkspaceByWorkspaceId,
   findHostedWorkspaceByLinkedIdea,
   findHostedWorkspaceLinkedToIdea,
   loadWorkspaceSource,
@@ -72,6 +73,11 @@ export {
   resolveWorkspaceSelectorFromCollections,
   updateIdeaPayload,
 } from "./orp.js";
+export {
+  buildLocalProjectInventory,
+  inferLocalProjectRoots,
+  mergeLocalProjectInventoryIntoManifest,
+} from "./local-inventory.js";
 export {
   cacheManagedWorkspaceManifest,
   clearWorkspaceSlot,