feat(workspace): reuse checkout opens and trim repeated bootstrap

.github/workflows/ci.yml

@@ -7,8 +7,8 @@ on:
   pull_request:
 
 jobs:
-  smoke:
-    name: Smoke (${{ matrix.os }})
+  verify:
+    name: Verify (${{ matrix.os }})
     runs-on: ${{ matrix.os }}
     strategy:
       fail-fast: false

docs/chatgpt-coding-workflow.md

@@ -17,12 +17,28 @@ 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 sends an opaque conversation identifier in `_meta["openai/session"]`.
+DevSpace stores that value locally and uses it only as a correlation scope:
+if checkout mode is called again for the same canonical project path in the same
+ChatGPT conversation, DevSpace returns the existing checkout `workspaceId`.
+Worktree mode is deliberately different: every call creates a new managed
+worktree and a new workspace session, even for the same path and base ref.
+
+Project bootstrap delivery is tracked separately from workspace reuse. The first
+open for a canonical project path in a ChatGPT conversation returns project
+instructions, skills, subagent metadata, and diagnostics. Later checkout or
+worktree opens for that project omit those fields from the model response, even
+when a new worktree workspace is created. This state is persisted across MCP
+reconnects and DevSpace restarts. The workspace card still receives the complete
+hidden display payload, so every call renders full workspace details without
+adding the bootstrap fields to the model transcript again.
+
+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 +72,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.

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/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit"
   },
   "keywords": [],

src/db/migrations.ts

@@ -22,6 +22,16 @@ const migrations: Migration[] = [
     name: "local-agent-sessions",
     up: migrateLocalAgentSessions,
   },
+  {
+    version: 4,
+    name: "workspace-conversation-bindings",
+    up: migrateWorkspaceConversationBindings,
+  },
+  {
+    version: 5,
+    name: "workspace-conversation-bootstraps",
+    up: migrateWorkspaceConversationBootstraps,
+  },
 ];
 
 export function migrateDatabase(sqlite: Database.Database): void {
@@ -174,6 +184,79 @@ 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 migrateWorkspaceConversationBootstraps(sqlite: Database.Database): void {
+  sqlite.exec(`
+    create table if not exists workspace_conversation_bootstraps (
+      conversation_scope_id text not null,
+      project_key text not null,
+      created_at text not null,
+      last_used_at text not null,
+      primary key (conversation_scope_id, project_key)
+    );
+  `);
+
+  const bindings = sqlite.prepare(`
+    select conversation_scope_id, target_key, created_at, last_used_at
+    from workspace_conversation_bindings
+    order by created_at asc, target_key asc
+  `).all() as Array<{
+    conversation_scope_id: string;
+    target_key: string;
+    created_at: string;
+    last_used_at: string;
+  }>;
+  const insertBootstrap = sqlite.prepare(`
+    insert or ignore into workspace_conversation_bootstraps (
+      conversation_scope_id,
+      project_key,
+      created_at,
+      last_used_at
+    ) values (?, ?, ?, ?)
+  `);
+
+  for (const binding of bindings) {
+    const projectKey = projectKeyFromConversationTarget(binding.target_key);
+    if (!projectKey) continue;
+    insertBootstrap.run(
+      binding.conversation_scope_id,
+      projectKey,
+      binding.created_at,
+      binding.last_used_at,
+    );
+  }
+}
+
+// Historical target keys are JSON tuples of [mode, projectKey, baseRef].
+// This migration intentionally parses that frozen shape rather than importing the current producer.
+function projectKeyFromConversationTarget(targetKey: string): string | undefined {
+  try {
+    const parsed = JSON.parse(targetKey) as unknown;
+    if (!Array.isArray(parsed)) return undefined;
+    return typeof parsed[1] === "string" && parsed[1].length > 0 ? parsed[1] : undefined;
+  } catch {
+    return undefined;
+  }
+}
+
 function addColumnIfMissing(
   sqlite: Database.Database,
   table: "workspace_sessions" | "local_agent_sessions",

src/db/schema.ts

@@ -38,6 +38,36 @@ 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 workspaceConversationBootstraps = sqliteTable(
+  "workspace_conversation_bootstraps",
+  {
+    conversationScopeId: text("conversation_scope_id").notNull(),
+    projectKey: text("project_key").notNull(),
+    createdAt: text("created_at").notNull(),
+    lastUsedAt: text("last_used_at").notNull(),
+  },
+  (table) => [
+    primaryKey({ columns: [table.conversationScopeId, table.projectKey] }),
+  ],
+);
+
 export const oauthClients = sqliteTable(
   "oauth_clients",
   {
@@ -101,5 +131,9 @@ 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 WorkspaceConversationBootstrapRow = typeof workspaceConversationBootstraps.$inferSelect;
+export type NewWorkspaceConversationBootstrapRow = typeof workspaceConversationBootstraps.$inferInsert;
 export type LocalAgentSessionRow = typeof localAgentSessions.$inferSelect;
 export type NewLocalAgentSessionRow = typeof localAgentSessions.$inferInsert;

src/oauth-store.test.ts

@@ -7,6 +7,7 @@ import { InvalidGrantError, InvalidTokenError } from "@modelcontextprotocol/sdk/
 import { databasePath, openDatabase } from "./db/client.js";
 import { SingleUserOAuthProvider } from "./oauth-provider.js";
 import { SqliteOAuthClientsStore, SqliteOAuthStore } from "./oauth-store.js";
+import { SqliteWorkspaceStore } from "./workspace-store.js";
 
 const root = await mkdtemp(join(tmpdir(), "devspace-oauth-test-"));
 const oauthConfig = {
@@ -21,6 +22,7 @@ const redirectUri = "https://chatgpt.com/connector_platform_oauth_redirect";
 
 try {
   await testDatabaseConfiguration(join(root, "database-configuration"));
+  testConversationBootstrapMigration(join(root, "bootstrap-migration"));
   testPersistenceAndTokenHashing(join(root, "persistence"));
   testExpiredTokenCleanup(join(root, "expiration"));
   testTransactionalTokenRotation(join(root, "rotation"));
@@ -29,6 +31,56 @@ try {
   await rm(root, { recursive: true, force: true });
 }
 
+function testConversationBootstrapMigration(stateDir: string): void {
+  const initial = openDatabase(stateDir);
+  try {
+    initial.sqlite.prepare(`
+      insert into workspace_sessions (
+        id, root, status, mode, managed, created_at, last_used_at
+      ) values (?, ?, 'active', 'worktree', 'true', ?, ?)
+    `).run("ws_existing", "/tmp/project-worktree", "2026-01-01T00:00:00.000Z", "2026-01-02T00:00:00.000Z");
+    initial.sqlite.prepare(`
+      insert into workspace_conversation_bindings (
+        conversation_scope_id, target_key, workspace_session_id, created_at, last_used_at
+      ) values (?, ?, ?, ?, ?)
+    `).run(
+      "chat-existing",
+      JSON.stringify(["worktree", "/tmp/project", "HEAD"]),
+      "ws_existing",
+      "2026-01-01T00:00:00.000Z",
+      "2026-01-02T00:00:00.000Z",
+    );
+    initial.sqlite.exec(`
+      drop table workspace_conversation_bootstraps;
+      delete from devspace_schema_migrations where version = 5;
+    `);
+  } finally {
+    initial.close();
+  }
+
+  const migrated = new SqliteWorkspaceStore(stateDir);
+  try {
+    assert.deepEqual(
+      {
+        existingProjectAlreadyClaimed: migrated.claimConversationBootstrap(
+          "chat-existing",
+          "/tmp/project",
+        ),
+        newProjectCanClaim: migrated.claimConversationBootstrap(
+          "chat-existing",
+          "/tmp/other-project",
+        ),
+      },
+      {
+        existingProjectAlreadyClaimed: false,
+        newProjectCanClaim: true,
+      },
+    );
+  } finally {
+    migrated.close();
+  }
+}
+
 async function testDatabaseConfiguration(stateDir: string): Promise<void> {
   const database = openDatabase(stateDir);
   try {
@@ -44,6 +96,8 @@ 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" },
+      { version: 5, name: "workspace-conversation-bootstraps" },
     ]);
   } finally {
     database.close();

src/request-meta.test.ts

@@ -0,0 +1,25 @@
+import assert from "node:assert/strict";
+import test from "node:test";
+import { openAiConversationScopeId } from "./request-meta.js";
+
+test("OpenAI session metadata supplies the opaque conversation scope", () => {
+  assert.equal(
+    openAiConversationScopeId({
+      "openai/session": "chat-1",
+      "openai/subject": "user-1",
+      "openai/organization": "org-1",
+    }),
+    "chat-1",
+  );
+});
+
+test("missing or empty OpenAI session metadata has no conversation scope", () => {
+  assert.deepEqual(
+    [
+      openAiConversationScopeId(undefined),
+      openAiConversationScopeId({}),
+      openAiConversationScopeId({ "openai/session": "" }),
+    ],
+    [undefined, undefined, undefined],
+  );
+});

src/request-meta.ts

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