feat(workspace): reuse checkout sessions per ChatGPT conversation

docs/chatgpt-coding-workflow.md

@@ -17,12 +17,36 @@ ChatGPT should call `open_workspace` once for a project folder:
 The result includes a `workspaceId`. All later file, search, edit, show-changes,
 and shell calls should reuse that same `workspaceId`.
 
-Do not reopen the same folder unless:
+ChatGPT may support automatic checkout recovery through optional host
+conversation metadata. This is an OpenAI-host adapter detail, not a standard MCP
+conversation field. When that optional context is available, opening the same
+checkout project again in the same conversation can continue in the existing
+workspace, and the context already provided for that reused checkout is not
+repeated. The portable workflow remains the same: keep using the `workspaceId`
+returned by `open_workspace` for later operations. Hosts without supported
+conversation context receive a normal new workspace and continue with that
+explicit `workspaceId` workflow.
+The model receives actionable workspace instructions; automatic-reuse
+bookkeeping is not a model-facing choice.
+
+Worktree mode is deliberately different: every call creates a new managed
+worktree and a new workspace session with complete context, even for the same
+path and base ref.
+
+The first successful open of a checkout provides complete instructions and
+coding context. A repeated open that reuses the same checkout workspace does
+not repeat the model-visible context, but the workspace UI continues to show the
+complete details. Every new worktree establishes and returns its own complete
+context, even when the same project was already opened in checkout or another
+worktree. Opening checkout after a worktree therefore provides the checkout's
+own context.
+
+Do not call `open_workspace` again for the same checkout folder unless:
 
 - the `workspaceId` is rejected as unknown
-- the user switches to another folder
-- the user switches between checkout and worktree mode
-- the user explicitly asks to reopen
+- work moves to a different project folder
+- work switches between checkout and worktree mode
+- the user asks for a new isolated worktree
 
 ## Checkout Mode
 
@@ -56,6 +80,11 @@ Managed worktrees are created under:
 Worktree mode requires a Git repository with at least one commit. It starts from
 `HEAD` unless `baseRef` is provided.
 
+Each worktree-mode call creates a new managed worktree and returns a new
+`workspaceId`. Reuse that ID for work inside that worktree; call
+`open_workspace` in worktree mode again only when another isolated worktree is
+actually required.
+
 Uncommitted source checkout changes are not copied into the managed worktree.
 DevSpace reports when the source checkout was dirty so the model can decide how
 to proceed with the user.
@@ -158,10 +187,10 @@ and shell tools. The aggregate `show_changes` tool is not exposed by default.
 Use `DEVSPACE_WIDGETS=off` to disable widget UI, or `DEVSPACE_WIDGETS=changes`
 to expose the aggregate show-changes flow.
 
-When `show_changes` is exposed, models should call it exactly once after the
-final file modification in any turn that changes files. The tool only requires
-the `workspaceId`; DevSpace automatically compares against the last shown
-checkpoint and advances that checkpoint after rendering the aggregate diff.
+When `show_changes` is exposed, call it exactly once after the final file
+modification in any turn that changes files. It shows the combined changes for
+that turn and advances the review point automatically. Reusing a workspace does
+not change this workflow.
 
 ## Shell Use
 

docs/gotchas.md

@@ -136,8 +136,23 @@ npx @waishnav/devspace init --force
 client receives an unknown workspace error, call `open_workspace` again for that
 project.
 
-Workspace session metadata is persisted, but clients should still treat
-`open_workspace` as the way to begin a fresh working session.
+Workspace session metadata is persisted. ChatGPT may provide optional
+conversation metadata that lets DevSpace resume the same checkout workspace for
+the same project in that conversation; repeated opens reuse the `workspaceId`
+and do not repeat context already provided for that reused checkout. Worktree
+mode always creates a new isolated workspace with its own complete context.
+Hosts without supported conversation metadata receive a normal new workspace.
+In all cases, continue passing the `workspaceId` returned by `open_workspace` to
+later tools. Other MCP hosts use this explicit workspace workflow as well.
+
+To review work, call `show_changes` once after the final related file change. It
+shows the combined changes and advances the review point automatically.
+
+## Data Retention
+
+DevSpace does not currently prune workspace sessions, conversation bindings,
+or review refs. A future product retention policy will define safe cleanup for
+these records; no automatic deletion is performed today.
 
 ## Workspace Path Rejected
 

package.json

@@ -28,7 +28,7 @@
     "dev": "node scripts/dev-server.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "tsx src/config.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/review-checkpoints.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "tsx src/config.test.ts && tsx src/request-meta.test.ts && tsx src/incoming-artifacts.test.ts && tsx src/artifact-download.test.ts && tsx src/ui/card-types.test.ts && tsx src/ui/patch-display.test.ts && tsx src/ui/tool-display.test.ts && tsx src/apply-patch.test.ts && tsx src/process-platform.test.ts && tsx src/process-sessions.test.ts && tsx src/mcp-sessions.test.ts && tsx src/server-shutdown.test.ts && tsx src/local-agent-runtime.test.ts && tsx src/local-agent-adapters.test.ts && tsx src/local-agent-availability.test.ts && tsx src/local-agent-profiles.test.ts && tsx src/local-agent-targets.test.ts && tsx src/local-agent-store.test.ts && tsx src/roots.test.ts && tsx src/skills.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "keywords": [],

src/db/migrations.ts

@@ -22,6 +22,11 @@ const migrations: Migration[] = [
     name: "local-agent-sessions",
     up: migrateLocalAgentSessions,
   },
+  {
+    version: 4,
+    name: "workspace-conversation-bindings",
+    up: migrateWorkspaceConversationBindings,
+  },
 ];
 
 export function migrateDatabase(sqlite: Database.Database): void {
@@ -174,6 +179,25 @@ function migrateLocalAgentSessions(sqlite: Database.Database): void {
   addColumnIfMissing(sqlite, "local_agent_sessions", "thinking", "text");
 }
 
+function migrateWorkspaceConversationBindings(sqlite: Database.Database): void {
+  sqlite.exec(`
+    create table if not exists workspace_conversation_bindings (
+      conversation_scope_id text not null,
+      target_key text not null,
+      workspace_session_id text not null,
+      created_at text not null,
+      last_used_at text not null,
+      primary key (conversation_scope_id, target_key),
+      foreign key (workspace_session_id)
+        references workspace_sessions(id)
+        on delete cascade
+    );
+
+    create index if not exists workspace_conversation_bindings_workspace_idx
+      on workspace_conversation_bindings(workspace_session_id);
+  `);
+}
+
 function addColumnIfMissing(
   sqlite: Database.Database,
   table: "workspace_sessions" | "local_agent_sessions",

src/db/schema.ts

@@ -38,6 +38,23 @@ export const loadedAgentFiles = sqliteTable(
   ],
 );
 
+export const workspaceConversationBindings = sqliteTable(
+  "workspace_conversation_bindings",
+  {
+    conversationScopeId: text("conversation_scope_id").notNull(),
+    targetKey: text("target_key").notNull(),
+    workspaceSessionId: text("workspace_session_id")
+      .notNull()
+      .references(() => workspaceSessions.id, { onDelete: "cascade" }),
+    createdAt: text("created_at").notNull(),
+    lastUsedAt: text("last_used_at").notNull(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.conversationScopeId, table.targetKey] }),
+    index("workspace_conversation_bindings_workspace_idx").on(table.workspaceSessionId),
+  ],
+);
+
 export const oauthClients = sqliteTable(
   "oauth_clients",
   {
@@ -101,5 +118,7 @@ export type WorkspaceSessionRow = typeof workspaceSessions.$inferSelect;
 export type NewWorkspaceSessionRow = typeof workspaceSessions.$inferInsert;
 export type LoadedAgentFileRow = typeof loadedAgentFiles.$inferSelect;
 export type NewLoadedAgentFileRow = typeof loadedAgentFiles.$inferInsert;
+export type WorkspaceConversationBindingRow = typeof workspaceConversationBindings.$inferSelect;
+export type NewWorkspaceConversationBindingRow = typeof workspaceConversationBindings.$inferInsert;
 export type LocalAgentSessionRow = typeof localAgentSessions.$inferSelect;
 export type NewLocalAgentSessionRow = typeof localAgentSessions.$inferInsert;

src/oauth-store.test.ts

@@ -44,6 +44,7 @@ async function testDatabaseConfiguration(stateDir: string): Promise<void> {
       { version: 1, name: "workspace-state" },
       { version: 2, name: "oauth-state" },
       { version: 3, name: "local-agent-sessions" },
+      { version: 4, name: "workspace-conversation-bindings" },
     ]);
   } finally {
     database.close();

src/request-meta.test.ts

@@ -0,0 +1,38 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { openAiConversationScopeId } from "./request-meta.js";
+
+test("undefined request metadata has no conversation scope", () => {
+  assert.equal(openAiConversationScopeId(undefined), undefined);
+});
+
+test("missing session metadata has no conversation scope", () => {
+  assert.equal(openAiConversationScopeId({}), undefined);
+});
+
+test("an empty session string has no conversation scope", () => {
+  assert.equal(openAiConversationScopeId({ "openai/session": "" }), undefined);
+});
+
+test("a non-string session value has no conversation scope", () => {
+  assert.equal(openAiConversationScopeId({ "openai/session": 42 }), undefined);
+  assert.equal(openAiConversationScopeId({ "openai/session": {} }), undefined);
+});
+
+test("valid OpenAI session metadata returns the raw opaque session value", () => {
+  assert.equal(
+    openAiConversationScopeId({ "openai/session": "chat-session-opaque-value" }),
+    "chat-session-opaque-value",
+  );
+});
+
+test("unrelated metadata fields do not alter the selected conversation scope", () => {
+  assert.equal(
+    openAiConversationScopeId({
+      "openai/session": "chat-session-opaque-value",
+      "openai/subject": "user-1",
+      "openai/organization": "org-1",
+    }),
+    "chat-session-opaque-value",
+  );
+});

src/request-meta.ts

@@ -0,0 +1,14 @@
+function metadataString(
+  meta: unknown,
+  key: string,
+): string | undefined {
+  if (typeof meta !== "object" || meta === null) return undefined;
+  const value = (meta as Record<string, unknown>)[key];
+  return typeof value === "string" && value.length > 0 ? value : undefined;
+}
+
+export function openAiConversationScopeId(
+  meta: unknown,
+): string | undefined {
+  return metadataString(meta, "openai/session");
+}