open-research-protocol 0.4.24 → 0.4.26

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/docs/RESEARCH_COUNCIL.md

@@ -0,0 +1,123 @@
+# ORP Research Council
+
+ORP research council runs turn one question into a durable, tool-callable research artifact. The default profile is OpenAI-only right now, so one saved ORP key can power the full loop:
+
+```bash
+orp research ask "Where should this system live?" --json
+```
+
+By default this is a dry run. ORP writes the decomposition, profile, lane plan, lane JSON files, synthesized planning answer, and summary under:
+
+```text
+orp/research/<run_id>/
+```
+
+Live provider calls require an explicit flag:
+
+```bash
+orp research ask "Where should this system live?" --execute --json
+```
+
+## Lanes
+
+The built-in `openai-council` profile defines three OpenAI API lanes:
+
+- `openai_reasoning_high`: `gpt-5.4` with `reasoning.effort=high` for the deliberate thinking pass.
+- `openai_web_synthesis`: `gpt-5.4` with high reasoning plus Responses API web search for current public evidence and citations.
+- `openai_deep_research`: `o3-deep-research-2025-06-26` with background execution and web search preview for Pro/Deep Research style investigation.
+
+This follows OpenAI's current model guidance: `gpt-5.4` is the default for general-purpose, coding, reasoning, and agentic workflows; web search is enabled through the Responses API `tools` array when current information is needed; and Deep Research is available through the Responses endpoint with `o3-deep-research-2025-06-26`.
+
+## API Call Moments
+
+ORP records when API keys are intended to be used:
+
+- `plan`: local decomposition only. No API key is resolved.
+- `thinking_reasoning_high`: resolve `openai-primary` immediately before the `openai_reasoning_high` lane.
+- `web_synthesis`: resolve `openai-primary` immediately before the `openai_web_synthesis` lane.
+- `pro_deep_research`: resolve `openai-primary` immediately before the `openai_deep_research` lane.
+
+Dry runs write every lane with `api_call.called=false`. Live runs require `--execute`; even then, secret values are read only at the lane call moment and are not written to artifacts.
+
+Secret values are read from environment variables first. If an env var is missing and a matching ORP Keychain secret is available, ORP can use it at execution time. Secret values are not persisted in artifacts.
+
+The default live profile expects this ORP secret alias or env var:
+
+- `openai-primary` / `OPENAI_API_KEY`
+
+Store a local machine copy without the hosted secret API like this:
+
+```bash
+printf '%s' '<openai-key>' | orp secrets keychain-add \
+  --alias openai-primary \
+  --label "OpenAI Primary" \
+  --provider openai \
+  --value-stdin \
+  --json
+```
+
+## Fixtures
+
+Provider outputs can be attached without spending live calls:
+
+```bash
+orp research ask "Where should this live?" \
+  --lane-fixture openai_reasoning_high=reports/reasoning.json \
+  --lane-fixture openai_web_synthesis=reports/web.txt \
+  --json
+```
+
+Fixtures are useful when an OpenAI run happened outside ORP, when you are comparing model settings manually, or when tests need deterministic lane outputs.
+
+## OpenAI API Notes
+
+ORP uses the Responses API for these lanes. Useful knobs in profile JSON:
+
+- `model`: for example `gpt-5.4` or `o3-deep-research-2025-06-26`.
+- `call_moment`: the named research-loop moment when this lane may resolve a key.
+- `reasoning_effort`: `none`, `low`, `medium`, `high`, or `xhigh` for supported models.
+- `reasoning_summary`: `auto` or `detailed` for Deep Research reasoning summaries.
+- `text_verbosity`: `low`, `medium`, or `high`.
+- `web_search`: `true` to add the Responses API web-search tool.
+- `search_context_size`: `low`, `medium`, or `high` for web search.
+- `background`: `true` for long-running Deep Research calls.
+- `max_output_tokens`: hard cap for a lane response.
+
+The default profile deliberately avoids Anthropic, xAI, and local-model lanes so a single OpenAI key is enough.
+
+## Project Context Timing
+
+`orp init` creates `orp/project.json`, a process-only project context lens for the current directory. It records the authority surfaces ORP can see, the directory signals it should route on, and the default research timing policy:
+
+- decompose locally first
+- use high-reasoning API calls when a decision gate or ambiguous next action needs outside reasoning
+- use web synthesis when current public facts, docs, papers, project status, or citations matter
+- use Deep Research only after reasoning/web lanes expose a research-heavy gap, disagreement, source-quality issue, or literature-scale synthesis need
+
+Run `orp project refresh --json` after adding or changing roadmap, spec, agent-guidance, docs, manifest, or command-surface files. Refreshing project context does not call a provider; live provider calls remain explicit through `orp research ask --execute`.
+
+## Follow-Up Commands
+
+```bash
+orp project show --json
+orp project refresh --json
+orp research status latest --json
+orp research show latest --json
+```
+
+## Codex MCP Tool
+
+ORP also ships a tiny stdio MCP wrapper for the research commands:
+
+```toml
+[mcp_servers.orp-research]
+command = "/path/to/orp/scripts/orp-mcp"
+```
+
+It exposes:
+
+- `orp_research_ask`
+- `orp_research_status`
+- `orp_research_show`
+
+Research council files are ORP process artifacts. They record decomposition, provider lane outputs, and synthesis. Canonical evidence still belongs in source repositories, linked reports, cited URLs, datasets, papers, or other primary artifacts.

package/docs/START_HERE.md

@@ -43,6 +43,7 @@ orp home
 orp agents root set /absolute/path/to/projects
 orp init
 orp agents audit
+orp project show --json
 orp workspace create main-cody-1
 orp workspace tabs main
 orp agenda refresh --json
@@ -64,6 +65,7 @@ That gets you:
 - an optional umbrella projects root for parent/child agent guidance
 - repo governance initialized
 - repo-level AGENTS.md and CLAUDE.md scaffolded or refreshed
+- `orp/project.json` created as the local project context lens
 - a local workspace ledger
 - the main recovery surface
 - a local operating agenda
@@ -73,6 +75,8 @@ That gets you:
 - a clean repo-governance read
 - a first intentional checkpoint
 
+`orp/project.json` records the current directory's authority surfaces, directory signals, and default research call timing. It is refreshed by `orp init` and can evolve with the directory through `orp project refresh --json`, especially after adding or changing roadmap, spec, agent-guidance, docs, manifest, or command-surface files.
+
 ## Beginner Flow
 
 This is the zero-assumption path for a new user.

package/package.json

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