@akira-tl/forgerelay 0.3.5 → 0.3.6

package/CHANGELOG.md

@@ -4,6 +4,18 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.3.6] - 2026-08-10
+
+### Added
+
+- `open_workspace(action="list")` now provides paginated logical-workspace inventory without adding a tenth Core tool. Inventory entries include a compact `project/workspaceId` label, persisted status, derived lifecycle state, checkout/worktree backing metadata, creation/last-used timestamps, idle duration, root validity, current-conversation selection, and filters for workspace ID, status, state, mode, root, and stale-only views.
+
+### Changed
+
+- Workspace bootstrap context is now deduplicated by conversation scope, canonical workspace target, and a content fingerprint instead of by logical `workspaceId`. `context="auto"` remains the default, `context="full"` forces a refresh, and `context="none"` opens or resumes a workspace without returning the full AGENTS/Skills/guide/profile bootstrap.
+- Context-delivery state is persisted independently from logical-workspace selection, so switching or closing one logical handle does not make the same conversation forget already-delivered project context. Changes to loaded instruction contents or relevant Skill, guide, profile, diagnostic, or nested-instruction metadata change the fingerprint and cause `auto` to deliver the refreshed context again.
+- Workspace inventory is read-only with respect to workspace activity timestamps and runs the existing idle-session GC before listing. Persisted `status="active"` continues to mean the session has not been explicitly closed, while the derived `state` distinguishes currently active, stale-but-valid, invalid/missing-root, and closed records.
+
 ## [0.3.5] - 2026-08-10
 
 ### Changed

package/dist/db/migrations.js

@@ -29,6 +29,11 @@ const migrations = [
         name: "local-agent-hook-reports",
         up: migrateLocalAgentHookReports,
     },
+    {
+        version: 7,
+        name: "workspace-context-deliveries",
+        up: migrateWorkspaceContextDeliveries,
+    },
 ];
 export function migrateDatabase(sqlite) {
     const migrate = sqlite.transaction(() => {
@@ -189,6 +194,20 @@ function migrateWorkspaceWorktreeBranches(sqlite) {
 function migrateLocalAgentHookReports(sqlite) {
     addColumnIfMissing(sqlite, "local_agent_sessions", "hook_reports_json", "text");
 }
+function migrateWorkspaceContextDeliveries(sqlite) {
+    sqlite.exec(`
+    create table if not exists workspace_context_deliveries (
+      conversation_scope_id text not null,
+      target_key text not null,
+      context_fingerprint text not null,
+      delivered_at text not null,
+      primary key (conversation_scope_id, target_key)
+    );
+
+    create index if not exists workspace_context_deliveries_delivered_idx
+      on workspace_context_deliveries(delivered_at desc);
+  `);
+}
 function addColumnIfMissing(sqlite, table, column, definition) {
     const columns = sqlite.prepare(`pragma table_info(${table})`).all();
     if (columns.some((existingColumn) => existingColumn.name === column))

package/dist/db/schema.js

@@ -41,6 +41,15 @@ export const workspaceConversationBindings = sqliteTable("workspace_conversation
     primaryKey({ columns: [table.conversationScopeId, table.targetKey] }),
     index("workspace_conversation_bindings_workspace_idx").on(table.workspaceSessionId),
 ]);
+export const workspaceContextDeliveries = sqliteTable("workspace_context_deliveries", {
+    conversationScopeId: text("conversation_scope_id").notNull(),
+    targetKey: text("target_key").notNull(),
+    contextFingerprint: text("context_fingerprint").notNull(),
+    deliveredAt: text("delivered_at").notNull(),
+}, (table) => [
+    primaryKey({ columns: [table.conversationScopeId, table.targetKey] }),
+    index("workspace_context_deliveries_delivered_idx").on(table.deliveredAt),
+]);
 export const oauthClients = sqliteTable("oauth_clients", {
     clientId: text("client_id").primaryKey(),
     clientJson: text("client_json").notNull(),

package/dist/server.js

@@ -164,6 +164,36 @@ const workspaceLocalAgentProviderOutputSchema = z.object({
 const workspaceAvailableAgentsFileOutputSchema = z.object({
     path: z.string(),
 });
+const workspaceInventoryEntryOutputSchema = z.object({
+    label: z.string(),
+    workspaceId: z.string(),
+    root: z.string(),
+    status: z.string(),
+    state: z.enum(["active", "stale", "invalid", "closed"]),
+    mode: z.enum(["checkout", "worktree"]),
+    sourceRoot: z.string().optional(),
+    branch: z.string().optional(),
+    targetBranch: z.string().optional(),
+    managed: z.boolean(),
+    createdAt: z.string(),
+    lastUsedAt: z.string(),
+    idleMs: z.number().nonnegative(),
+    rootValid: z.boolean(),
+    current: z.boolean(),
+});
+const workspaceInventorySummaryOutputSchema = z.object({
+    total: z.number().int().nonnegative(),
+    matching: z.number().int().nonnegative(),
+    active: z.number().int().nonnegative(),
+    stale: z.number().int().nonnegative(),
+    invalid: z.number().int().nonnegative(),
+    closed: z.number().int().nonnegative(),
+});
+const workspaceInventoryPageOutputSchema = z.object({
+    offset: z.number().int().nonnegative(),
+    limit: z.number().int().positive(),
+    hasMore: z.boolean(),
+});
 const reviewFileOutputSchema = z.object({
     path: z.string(),
     previousPath: z.string().optional(),
@@ -775,20 +805,24 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     }, async (uri, _variables, extra) => readWorkspaceAppResource(config, uri.toString(), extra.sessionId));
     registerAppTool(server, "open_workspace", {
         title: "Open workspace",
-        description: "Open or resume a local coding workspace. Reuse the returned workspaceId for later calls. Default to checkout; use mode=\"worktree\" only when the user explicitly requests isolated or parallel Git work. Every call returns a capability fingerprint; bootstrap calls also expose project context, skills, and capability guides when needed.",
+        description: "Open or resume a local coding workspace. Reuse the returned workspaceId for later calls. Default to checkout; use mode=\"worktree\" only when the user explicitly requests isolated or parallel Git work. Every call returns lightweight workspace metadata; bootstrap context is delivered automatically only when needed and can be explicitly suppressed or refreshed.",
         inputSchema: {
+            action: z
+                .enum(["open", "list"])
+                .optional()
+                .describe("Defaults to open. Use list only when you need to inspect or choose logical workspaces before resuming or cleaning them up."),
             path: z
                 .string()
                 .optional()
-                .describe("Project path to open. Required unless workspaceId is supplied. With mode=\"worktree\", this may also be a managed worktree path previously returned by ForgeRelay."),
+                .describe("Project path to open. Required for action=open unless workspaceId is supplied. With mode=\"worktree\", this may also be a managed worktree path previously returned by ForgeRelay."),
             workspaceId: z
                 .string()
                 .optional()
-                .describe("Existing logical workspace ID to resume in this conversation. When supplied, ForgeRelay resumes that workspace rather than allocating another ID."),
+                .describe("For action=open, an existing logical workspace ID to resume in this conversation. For action=list, filters inventory to one workspace ID."),
             mode: z
                 .enum(["checkout", "worktree"])
                 .optional()
-                .describe("Defaults to checkout, which works in the actual directory. Use worktree only when the user explicitly requests isolated or parallel Git work."),
+                .describe("For action=open, defaults to checkout and uses the actual directory unless worktree isolation is explicitly requested. For action=list, filters by workspace mode."),
             baseRef: z
                 .string()
                 .optional()
@@ -801,11 +835,45 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 .boolean()
                 .optional()
                 .describe("When true, allocate a fresh logical workspaceId for the same physical checkout or worktree and bind this conversation to it. Use only after the user explicitly requests a new logical workspace."),
+            context: z
+                .enum(["auto", "full", "none"])
+                .optional()
+                .describe("Bootstrap context policy for action=open. auto (default) sends full project context only when this conversation has not received the current context fingerprint; full forces a refresh; none opens/resumes without returning the full bootstrap context."),
+            root: z
+                .string()
+                .optional()
+                .describe("For action=list, filter by canonical workspace root or source root."),
+            status: z
+                .string()
+                .optional()
+                .describe("For action=list, filter by persisted workspace status such as active or closed."),
+            state: z
+                .enum(["active", "stale", "invalid", "closed"])
+                .optional()
+                .describe("For action=list, filter by derived lifecycle state."),
+            staleOnly: z
+                .boolean()
+                .optional()
+                .describe("For action=list, return only active logical workspaces idle for more than two days."),
+            offset: z
+                .number()
+                .int()
+                .nonnegative()
+                .optional()
+                .describe("For action=list, zero-based inventory offset. Defaults to 0."),
+            limit: z
+                .number()
+                .int()
+                .min(1)
+                .max(100)
+                .optional()
+                .describe("For action=list, maximum records to return. Defaults to 50; maximum 100."),
         },
         outputSchema: {
-            workspaceId: z.string(),
-            root: z.string(),
-            mode: z.enum(["checkout", "worktree"]),
+            action: z.enum(["open", "list"]),
+            workspaceId: z.string().optional(),
+            root: z.string().optional(),
+            mode: z.enum(["checkout", "worktree"]).optional(),
             sourceRoot: z.string().optional(),
             worktree: z
                 .object({
@@ -828,7 +896,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 targetBranch: z.string().optional(),
                 managed: z.boolean(),
                 current: z.boolean(),
-            })),
+            })).optional(),
             staleWorkspaces: z.array(z.object({
                 workspaceId: z.string(),
                 root: z.string(),
@@ -838,9 +906,10 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 branch: z.string().optional(),
                 targetBranch: z.string().optional(),
                 managed: z.boolean(),
-            })),
-            capabilityFingerprint: capabilityFingerprintOutputSchema,
-            capabilityCatalog: z.array(capabilityCatalogOutputSchema),
+            })).optional(),
+            capabilityFingerprint: capabilityFingerprintOutputSchema.optional(),
+            contextFingerprint: z.string().optional(),
+            capabilityCatalog: z.array(capabilityCatalogOutputSchema).optional(),
             capabilityGuides: z.array(capabilityGuideOutputSchema).optional(),
             agentsFiles: z.array(workspaceAgentsFileOutputSchema).optional(),
             availableAgentsFiles: z.array(workspaceAvailableAgentsFileOutputSchema).optional(),
@@ -848,6 +917,9 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             agentProviders: z.array(workspaceLocalAgentProviderOutputSchema).optional(),
             agents: z.array(workspaceLocalAgentOutputSchema).optional(),
             skillDiagnostics: z.array(z.unknown()).optional(),
+            workspaces: z.array(workspaceInventoryEntryOutputSchema).optional(),
+            summary: workspaceInventorySummaryOutputSchema.optional(),
+            page: workspaceInventoryPageOutputSchema.optional(),
             instruction: z.string(),
         },
         ...toolWidgetDescriptorMeta(config, "workspace"),
@@ -857,11 +929,62 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             idempotentHint: false,
             openWorldHint: false,
         },
-    }, async ({ path, workspaceId, mode, baseRef, newWorktree, newWorkspace }, { _meta, sessionId }) => {
+    }, async ({ action = "open", path, workspaceId, mode, baseRef, newWorktree, newWorkspace, context, root, status, state, staleOnly, offset, limit, }, { _meta, sessionId }) => {
         const startedAt = performance.now();
-        const { workspace, agentsFiles, availableAgentsFiles, hookReports, workspaceReused, includeBootstrapContext, } = await workspaces.openWorkspace({ path, workspaceId, mode, baseRef, newWorktree, newWorkspace }, {
-            conversationScopeId: openAiConversationScopeId(_meta),
-            protectedWorkspaceIds: processSessions.activeWorkspaceIds(),
+        const conversationScopeId = openAiConversationScopeId(_meta);
+        const protectedWorkspaceIds = processSessions.activeWorkspaceIds();
+        if (action === "list") {
+            if (path !== undefined || baseRef !== undefined || newWorktree !== undefined ||
+                newWorkspace !== undefined || context !== undefined) {
+                throw new Error("open_workspace action=list does not accept path, baseRef, newWorktree, newWorkspace, or context. Use root/workspaceId/mode/status/state/staleOnly for inventory filters.");
+            }
+            const inventory = await workspaces.listWorkspaces({ workspaceId, mode, root, status, state, staleOnly, offset, limit }, { conversationScopeId, protectedWorkspaceIds });
+            const nextOffset = inventory.page.offset + inventory.page.limit;
+            const instruction = [
+                "Resume a selected workspaceId with open_workspace(action=\"open\", workspaceId=...).",
+                "Use close_workspace only after the user chooses cleanup; never close inventory entries automatically.",
+                inventory.page.hasMore
+                    ? `More matching workspaces are available; continue with offset=${nextOffset}.`
+                    : undefined,
+            ].filter(Boolean).join(" ");
+            const result = [
+                `Logical workspace inventory: ${inventory.summary.matching} matching of ${inventory.summary.total} stored records.`,
+                `States: active=${inventory.summary.active}, stale=${inventory.summary.stale}, invalid=${inventory.summary.invalid}, closed=${inventory.summary.closed}.`,
+                ...inventory.workspaces.map((entry) => [
+                    entry.label,
+                    `state=${entry.state}`,
+                    `status=${entry.status}`,
+                    `mode=${entry.mode}`,
+                    entry.managed ? "managed" : undefined,
+                    entry.current ? "current" : undefined,
+                    `root=${entry.root}`,
+                    `last-used=${entry.lastUsedAt}`,
+                ].filter(Boolean).join(" ")),
+                instruction,
+            ].join("\n");
+            logToolCall(config, {
+                tool: "open_workspace",
+                action: "list",
+                path: root,
+                success: true,
+                durationMs: Math.round(performance.now() - startedAt),
+            });
+            return {
+                content: [textBlock(result)],
+                structuredContent: {
+                    action: "list",
+                    ...inventory,
+                    instruction,
+                },
+            };
+        }
+        if (root !== undefined || status !== undefined || state !== undefined ||
+            staleOnly !== undefined || offset !== undefined || limit !== undefined) {
+            throw new Error("open_workspace inventory filters root, status, state, staleOnly, offset, and limit are only valid with action=list.");
+        }
+        const { workspace, agentsFiles, availableAgentsFiles, hookReports, workspaceReused, includeBootstrapContext, contextFingerprint, } = await workspaces.openWorkspace({ path, workspaceId, mode, baseRef, newWorktree, newWorkspace, context }, {
+            conversationScopeId,
+            protectedWorkspaceIds,
         });
         const knownWorktrees = await workspaces.listKnownWorktrees(workspace);
         const staleWorkspaces = await workspaces.listStaleWorkspaces(workspace);
@@ -911,20 +1034,26 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         const visibleAgents = includeBootstrapContext ? cardAgents : [];
         const loadedAgentsFiles = includeBootstrapContext ? cardAgentsFiles : [];
         const availableAgentsFileOutputs = includeBootstrapContext ? cardAvailableAgentsFiles : [];
+        const workspaceContextInstruction = "For later open_workspace calls, context=\"auto\" avoids repeating unchanged bootstrap context; use context=\"none\" when only the workspace handle/metadata is needed, or context=\"full\" to force a refresh.";
+        const workspaceManagementInstruction = "When you need to continue an earlier logical workspace or organize workspace state, use open_workspace(action=\"list\") to inspect candidates, then resume a selected workspaceId or ask the user before close_workspace cleanup.";
         const cardInstruction = config.skillsEnabled
-            ? "Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches an available skill or capability guide, read its advertised path before proceeding."
-            : "Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches a capability guide, read its advertised path before proceeding.";
+            ? `Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches an available skill or capability guide, read its advertised path before proceeding. ${workspaceContextInstruction} ${workspaceManagementInstruction}`
+            : `Use this workspaceId in all subsequent tool calls for this project. Follow loaded agentsFiles instructions. Read an availableAgentsFiles path before working under it. When a task matches a capability guide, read its advertised path before proceeding. ${workspaceContextInstruction} ${workspaceManagementInstruction}`;
         const instruction = workspaceReused
             ? includeBootstrapContext
                 ? [
                     `Workspace already exists as ${workspace.id} for this directory.`,
                     "Reuse this workspaceId for subsequent tool calls.",
                     "The complete project context is included because it has not yet been provided in this conversation or host context.",
+                    workspaceContextInstruction,
+                    workspaceManagementInstruction,
                 ].join("\n\n")
                 : [
                     `Workspace already open as ${workspace.id}.`,
                     "Reuse this workspaceId for subsequent tool calls. This is the same directory previously opened in this conversation.",
                     "Continue following the project instructions, nested instruction files, skills, capability guides, agent profiles, and diagnostics previously provided for this workspace. They remain active and are not repeated here.",
+                    workspaceContextInstruction,
+                    workspaceManagementInstruction,
                 ].join("\n\n")
             : workspace.mode === "worktree"
                 ? "Use this workspaceId for subsequent tool calls. Follow the project instructions, nested instruction files, skills, agent profiles, and diagnostics returned for this isolated worktree."
@@ -998,6 +1127,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     worktrees: knownWorktrees,
                     staleWorkspaces,
                     capabilityFingerprint,
+                    contextFingerprint,
                     capabilityCatalog,
                     agentsFiles: cardAgentsFiles,
                     availableAgentsFiles: cardAvailableAgentsFiles,
@@ -1017,6 +1147,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 },
             },
             structuredContent: {
+                action: "open",
                 workspaceId: workspace.id,
                 root: workspace.root,
                 mode: workspace.mode,
@@ -1025,6 +1156,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                 worktrees: knownWorktrees,
                 staleWorkspaces,
                 capabilityFingerprint,
+                contextFingerprint,
                 capabilityCatalog,
                 ...(includeBootstrapContext
                     ? {

package/dist/workspace-store.js

@@ -1,6 +1,6 @@
 import { and, desc, eq } from "drizzle-orm";
 import { openDatabase } from "./db/client.js";
-import { workspaceConversationBindings, workspaceSessions, } from "./db/schema.js";
+import { workspaceContextDeliveries, workspaceConversationBindings, workspaceSessions, } from "./db/schema.js";
 export class SqliteWorkspaceStore {
     database;
     constructor(stateDir) {
@@ -141,6 +141,49 @@ export class SqliteWorkspaceStore {
             .where(and(eq(workspaceConversationBindings.conversationScopeId, conversationScopeId), eq(workspaceConversationBindings.targetKey, targetKey)))
             .run();
     }
+    listContextDeliveries() {
+        return this.database.db
+            .select()
+            .from(workspaceContextDeliveries)
+            .orderBy(desc(workspaceContextDeliveries.deliveredAt))
+            .all()
+            .map(rowToWorkspaceContextDelivery);
+    }
+    getContextDelivery(conversationScopeId, targetKey) {
+        const row = this.database.db
+            .select()
+            .from(workspaceContextDeliveries)
+            .where(and(eq(workspaceContextDeliveries.conversationScopeId, conversationScopeId), eq(workspaceContextDeliveries.targetKey, targetKey)))
+            .get();
+        return row ? rowToWorkspaceContextDelivery(row) : undefined;
+    }
+    setContextDelivery(input) {
+        const deliveredAt = new Date().toISOString();
+        const row = this.database.db
+            .insert(workspaceContextDeliveries)
+            .values({ ...input, deliveredAt })
+            .onConflictDoUpdate({
+            target: [
+                workspaceContextDeliveries.conversationScopeId,
+                workspaceContextDeliveries.targetKey,
+            ],
+            set: {
+                contextFingerprint: input.contextFingerprint,
+                deliveredAt,
+            },
+        })
+            .returning()
+            .get();
+        if (!row)
+            throw new Error("Workspace context delivery upsert returned no row.");
+        return rowToWorkspaceContextDelivery(row);
+    }
+    deleteContextDelivery(conversationScopeId, targetKey) {
+        this.database.db
+            .delete(workspaceContextDeliveries)
+            .where(and(eq(workspaceContextDeliveries.conversationScopeId, conversationScopeId), eq(workspaceContextDeliveries.targetKey, targetKey)))
+            .run();
+    }
     close() {
         this.database.close();
     }
@@ -173,3 +216,11 @@ function rowToWorkspaceConversationBinding(row) {
         lastUsedAt: row.lastUsedAt,
     };
 }
+function rowToWorkspaceContextDelivery(row) {
+    return {
+        conversationScopeId: row.conversationScopeId,
+        targetKey: row.targetKey,
+        contextFingerprint: row.contextFingerprint,
+        deliveredAt: row.deliveredAt,
+    };
+}

package/dist/workspaces.js

@@ -1,4 +1,4 @@
-import { randomBytes } from "node:crypto";
+import { createHash, randomBytes } from "node:crypto";
 import { mkdir, opendir, readFile, realpath, stat } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { basename, dirname, join, relative, resolve, sep } from "node:path";
@@ -27,8 +27,9 @@ export class WorkspaceRegistry {
     async openWorkspace(input, openOptions = {}) {
         this.pruneIdleWorkspaceSessions(openOptions.protectedWorkspaceIds ?? new Set());
         const workspaceInput = typeof input === "string" ? { path: input } : input;
+        const bootstrapContext = workspaceInput.context ?? "auto";
         if (workspaceInput.workspaceId) {
-            return this.resumeWorkspace(workspaceInput.workspaceId, openOptions.conversationScopeId);
+            return this.resumeWorkspace(workspaceInput.workspaceId, openOptions.conversationScopeId, bootstrapContext);
         }
         if (!workspaceInput.path) {
             throw new Error("open_workspace requires either path or workspaceId.");
@@ -37,24 +38,138 @@ export class WorkspaceRegistry {
         if (mode === "worktree") {
             return this.openReusableWorktree(workspaceInput, openOptions.conversationScopeId);
         }
-        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId, workspaceInput.newWorkspace ?? false);
+        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId, workspaceInput.newWorkspace ?? false, bootstrapContext);
     }
-    async resumeWorkspace(workspaceId, conversationScopeId) {
+    async listWorkspaces(input = {}, openOptions = {}) {
+        this.pruneIdleWorkspaceSessions(openOptions.protectedWorkspaceIds ?? new Set());
+        const now = Date.now();
+        const sessions = this.store
+            ? this.store.listSessions()
+            : [...this.workspaces.values()].map((workspace) => ({
+                id: workspace.id,
+                root: workspace.root,
+                status: "active",
+                mode: workspace.mode,
+                sourceRoot: workspace.sourceRoot,
+                baseRef: workspace.worktree?.baseRef,
+                baseSha: workspace.worktree?.baseSha,
+                branch: workspace.worktree?.branch,
+                targetBranch: workspace.worktree?.targetBranch,
+                managed: workspace.worktree?.managed ?? false,
+                createdAt: "",
+                lastUsedAt: "",
+            }));
+        const currentWorkspaceIds = new Set(openOptions.conversationScopeId && this.store
+            ? this.store
+                .listConversationBindings()
+                .filter((binding) => binding.conversationScopeId === openOptions.conversationScopeId)
+                .map((binding) => binding.workspaceSessionId)
+            : []);
+        const rootKey = input.root
+            ? await canonicalPath(assertAllowedPath(input.root, [...this.config.allowedRoots, this.config.worktreeRoot]))
+            : undefined;
+        const entries = await Promise.all(sessions.map(async (session) => {
+            const rootValid = await this.validSessionRoot(session) !== undefined;
+            const lastUsedAt = Date.parse(session.lastUsedAt);
+            const idleMs = Number.isFinite(lastUsedAt) ? Math.max(0, now - lastUsedAt) : 0;
+            const state = session.status !== "active"
+                ? "closed"
+                : !rootValid
+                    ? "invalid"
+                    : idleMs >= WORKSPACE_STALE_REMINDER_MS
+                        ? "stale"
+                        : "active";
+            const projectRoot = session.sourceRoot ?? session.root;
+            return {
+                label: `${basename(resolve(projectRoot)) || "workspace"}/${session.id}`,
+                workspaceId: session.id,
+                root: session.root,
+                status: session.status,
+                state,
+                mode: session.mode,
+                sourceRoot: session.sourceRoot,
+                branch: session.branch,
+                targetBranch: session.targetBranch,
+                managed: session.managed,
+                createdAt: session.createdAt,
+                lastUsedAt: session.lastUsedAt,
+                idleMs,
+                rootValid,
+                current: currentWorkspaceIds.has(session.id),
+            };
+        }));
+        const filtered = [];
+        for (let index = 0; index < sessions.length; index += 1) {
+            const session = sessions[index];
+            const entry = entries[index];
+            if (!session || !entry)
+                continue;
+            if (input.workspaceId && entry.workspaceId !== input.workspaceId)
+                continue;
+            if (input.status && entry.status !== input.status)
+                continue;
+            if (input.state && entry.state !== input.state)
+                continue;
+            if (input.mode && entry.mode !== input.mode)
+                continue;
+            if (input.staleOnly && entry.state !== "stale")
+                continue;
+            if (rootKey) {
+                const sessionRootKey = await canonicalPath(session.root);
+                const sourceRootKey = session.sourceRoot ? await canonicalPath(session.sourceRoot) : undefined;
+                if (sessionRootKey !== rootKey && sourceRootKey !== rootKey)
+                    continue;
+            }
+            filtered.push(entry);
+        }
+        const summary = filtered.reduce((counts, entry) => {
+            counts[entry.state] += 1;
+            return counts;
+        }, { active: 0, stale: 0, invalid: 0, closed: 0 });
+        const offset = Math.max(0, input.offset ?? 0);
+        const limit = Math.min(100, Math.max(1, input.limit ?? 50));
+        return {
+            workspaces: filtered.slice(offset, offset + limit),
+            summary: {
+                total: entries.length,
+                matching: filtered.length,
+                ...summary,
+            },
+            page: {
+                offset,
+                limit,
+                hasMore: offset + limit < filtered.length,
+            },
+        };
+    }
+    async resumeWorkspace(workspaceId, conversationScopeId, bootstrapContext = "auto") {
         const workspace = this.getWorkspace(workspaceId);
         const context = await this.reusedWorkspaceContext(workspace);
         if (!conversationScopeId || !this.store) {
-            return { ...context, includeBootstrapContext: true };
+            return {
+                ...context,
+                includeBootstrapContext: bootstrapContext !== "none",
+            };
         }
         const targetKeys = await this.workspaceTargetKeys(workspace);
-        const alreadyBound = targetKeys.some((targetKey) => this.store?.getConversationBinding(conversationScopeId, targetKey)?.workspaceSessionId === workspace.id);
+        const contextAlreadyDelivered = targetKeys.some((targetKey) => this.store?.getContextDelivery(conversationScopeId, targetKey)?.contextFingerprint ===
+            context.contextFingerprint);
+        const includeBootstrapContext = resolveBootstrapContextVisibility(bootstrapContext, contextAlreadyDelivered);
         for (const targetKey of targetKeys) {
             this.store.setConversationBinding({
                 conversationScopeId,
                 targetKey,
                 workspaceSessionId: workspace.id,
             });
+            if (includeBootstrapContext) {
+                this.store.setContextDelivery({
+                    conversationScopeId,
+                    targetKey,
+                    contextFingerprint: context.contextFingerprint,
+                });
+            }
         }
-        return { ...context, includeBootstrapContext: !alreadyBound };
+        return { ...context, includeBootstrapContext };
     }
     async listStaleWorkspaces(workspace) {
         if (!this.store)
@@ -206,12 +321,12 @@ export class WorkspaceRegistry {
         }
         return { ...result, hookReports };
     }
-    async openReusableCheckout(path, conversationScopeId, newWorkspace) {
+    async openReusableCheckout(path, conversationScopeId, newWorkspace, bootstrapContext) {
         const allowedPath = assertAllowedPath(path, this.config.allowedRoots);
         const projectKey = await canonicalPath(allowedPath);
         const targetKey = JSON.stringify(["checkout", projectKey, null]);
         if (!newWorkspace) {
-            const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "checkout", async (session, root) => session.mode === "checkout" && await canonicalPath(root) === projectKey);
+            const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "checkout", async (session, root) => session.mode === "checkout" && await canonicalPath(root) === projectKey, bootstrapContext);
             if (boundContext)
                 return boundContext;
         }
@@ -220,7 +335,7 @@ export class WorkspaceRegistry {
             const freshContext = reusableWorkspace
                 ? await this.cloneWorkspaceContext(reusableWorkspace)
                 : await this.openCheckoutWorkspace(path);
-            return this.withConversationContext(freshContext, conversationScopeId, targetKey);
+            return this.withConversationContext(freshContext, conversationScopeId, targetKey, bootstrapContext);
         }
         const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
         const context = await this.openOnce(operationKey, async () => {
@@ -231,18 +346,19 @@ export class WorkspaceRegistry {
                 ? this.cloneWorkspaceContext(reusableWorkspace)
                 : this.reusedWorkspaceContext(reusableWorkspace);
         });
-        return this.withConversationContext(context, conversationScopeId, targetKey);
+        return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
     async openReusableWorktree(input, conversationScopeId) {
         const path = input.path;
         if (!path)
             throw new Error("Worktree mode requires path.");
+        const bootstrapContext = input.context ?? "auto";
         const managedPath = this.tryManagedWorktreePath(path);
         if (managedPath) {
             const worktreeKey = await canonicalPath(managedPath);
             const targetKey = JSON.stringify(["worktree-path", worktreeKey]);
             if (!input.newWorkspace) {
-                const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session, root) => session.mode === "worktree" && await canonicalPath(root) === worktreeKey);
+                const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session, root) => session.mode === "worktree" && await canonicalPath(root) === worktreeKey, bootstrapContext);
                 if (boundContext)
                     return boundContext;
             }
@@ -251,7 +367,7 @@ export class WorkspaceRegistry {
                 if (!reusableWorkspace) {
                     throw new Error(`Managed worktree is not registered as an active ForgeRelay workspace: ${managedPath}. Open the source project in worktree mode to create or recover a managed worktree first.`);
                 }
-                return this.withConversationContext(await this.cloneWorkspaceContext(reusableWorkspace), conversationScopeId, targetKey);
+                return this.withConversationContext(await this.cloneWorkspaceContext(reusableWorkspace), conversationScopeId, targetKey, bootstrapContext);
             }
             const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
             const context = await this.openOnce(operationKey, async () => {
@@ -263,7 +379,7 @@ export class WorkspaceRegistry {
                     ? this.cloneWorkspaceContext(reusableWorkspace)
                     : this.reusedWorkspaceContext(reusableWorkspace);
             });
-            return this.withConversationContext(context, conversationScopeId, targetKey);
+            return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
         }
         const resolvedBase = await resolveManagedWorktreeBase({
             sourcePath: path,
@@ -274,13 +390,13 @@ export class WorkspaceRegistry {
         const targetKey = JSON.stringify(["worktree", sourceKey, resolvedBase.targetBranch]);
         if (input.newWorktree) {
             const context = await this.openWorktreeWorkspace(path, input.baseRef);
-            return this.withConversationContext(context, conversationScopeId, targetKey);
+            return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
         }
         if (!input.newWorkspace) {
             const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session) => session.mode === "worktree" &&
                 session.sourceRoot !== undefined &&
                 await canonicalPath(session.sourceRoot) === sourceKey &&
-                session.targetBranch === resolvedBase.targetBranch);
+                session.targetBranch === resolvedBase.targetBranch, bootstrapContext);
             if (boundContext)
                 return boundContext;
         }
@@ -289,7 +405,7 @@ export class WorkspaceRegistry {
             const freshContext = reusableWorkspace
                 ? await this.cloneWorkspaceContext(reusableWorkspace)
                 : await this.openWorktreeWorkspace(path, input.baseRef);
-            return this.withConversationContext(freshContext, conversationScopeId, targetKey);
+            return this.withConversationContext(freshContext, conversationScopeId, targetKey, bootstrapContext);
         }
         const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
         const context = await this.openOnce(operationKey, async () => {
@@ -300,7 +416,7 @@ export class WorkspaceRegistry {
                 ? this.cloneWorkspaceContext(reusableWorkspace)
                 : this.reusedWorkspaceContext(reusableWorkspace);
         });
-        return this.withConversationContext(context, conversationScopeId, targetKey);
+        return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
     async openOnce(operationKey, open) {
         const pending = this.pendingOpens.get(operationKey);
@@ -338,7 +454,7 @@ export class WorkspaceRegistry {
             ? JSON.stringify(["conversation", conversationScopeId, targetKey])
             : targetKey;
     }
-    async boundConversationContext(conversationScopeId, targetKey, mode, matches) {
+    async boundConversationContext(conversationScopeId, targetKey, mode, matches, bootstrapContext) {
         if (!conversationScopeId || !this.store)
             return undefined;
         const binding = this.store.getConversationBinding(conversationScopeId, targetKey);
@@ -359,24 +475,30 @@ export class WorkspaceRegistry {
             return undefined;
         }
         const context = await this.reusedWorkspaceContext(this.getWorkspace(session.id));
-        this.store.touchConversationBinding(conversationScopeId, targetKey);
-        return { ...context, includeBootstrapContext: false };
+        return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
-    withConversationContext(context, conversationScopeId, targetKey) {
+    withConversationContext(context, conversationScopeId, targetKey, bootstrapContext) {
         if (!conversationScopeId || !this.store) {
-            return { ...context, includeBootstrapContext: true };
-        }
-        const binding = this.store.getConversationBinding(conversationScopeId, targetKey);
-        if (binding?.workspaceSessionId === context.workspace.id) {
-            this.store.touchConversationBinding(conversationScopeId, targetKey);
-            return { ...context, includeBootstrapContext: false };
+            return {
+                ...context,
+                includeBootstrapContext: bootstrapContext !== "none",
+            };
         }
+        const delivery = this.store.getContextDelivery(conversationScopeId, targetKey);
+        const includeBootstrapContext = resolveBootstrapContextVisibility(bootstrapContext, delivery?.contextFingerprint === context.contextFingerprint);
         this.store.setConversationBinding({
             conversationScopeId,
             targetKey,
             workspaceSessionId: context.workspace.id,
         });
-        return { ...context, includeBootstrapContext: true };
+        if (includeBootstrapContext) {
+            this.store.setContextDelivery({
+                conversationScopeId,
+                targetKey,
+                contextFingerprint: context.contextFingerprint,
+            });
+        }
+        return { ...context, includeBootstrapContext };
     }
     pruneIdleWorkspaceSessions(protectedWorkspaceIds, force = false) {
         if (!this.store)
@@ -397,6 +519,13 @@ export class WorkspaceRegistry {
                 this.store.deleteConversationBinding(binding.conversationScopeId, binding.targetKey);
             }
         }
+        for (const delivery of this.store.listContextDeliveries()) {
+            const deliveredAt = Date.parse(delivery.deliveredAt);
+            if (Number.isFinite(deliveredAt) &&
+                now - deliveredAt >= WORKSPACE_SESSION_IDLE_TTL_MS) {
+                this.store.deleteContextDelivery(delivery.conversationScopeId, delivery.targetKey);
+            }
+        }
         const boundWorkspaceIds = new Set(this.store.listConversationBindings().map((binding) => binding.workspaceSessionId));
         const worktreeAnchors = new Map();
         for (const session of activeSessions) {
@@ -499,13 +628,17 @@ export class WorkspaceRegistry {
         });
     }
     async reusedWorkspaceContext(workspace) {
+        Object.assign(workspace, this.loadSkillsForWorkspace(workspace.root));
+        workspace.capabilityGuides = loadCapabilityGuides(this.config);
         workspace.agentProfiles = await loadLocalAgentProfiles(this.config, workspace.root);
         const agentsFiles = await this.loadInitialAgentsFiles(workspace.root);
         const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace.root, agentsFiles);
+        const contextFingerprint = bootstrapContextFingerprint(workspace, agentsFiles, availableAgentsFiles);
         return {
             workspace,
             agentsFiles,
             availableAgentsFiles,
+            contextFingerprint,
             hookReports: [],
             workspaceReused: true,
             includeBootstrapContext: true,
@@ -676,10 +809,12 @@ export class WorkspaceRegistry {
         });
         const agentsFiles = await this.loadInitialAgentsFiles(workspace.root);
         const availableAgentsFiles = await this.findAvailableAgentsFiles(workspace.root, agentsFiles);
+        const contextFingerprint = bootstrapContextFingerprint(workspace, agentsFiles, availableAgentsFiles);
         return {
             workspace,
             agentsFiles,
             availableAgentsFiles,
+            contextFingerprint,
             hookReports,
             workspaceReused: false,
             includeBootstrapContext: true,
@@ -761,6 +896,51 @@ export class WorkspaceRegistry {
         return discovered.sort((a, b) => a.path.localeCompare(b.path));
     }
 }
+function resolveBootstrapContextVisibility(mode, contextAlreadyDelivered) {
+    if (mode === "full")
+        return true;
+    if (mode === "none")
+        return false;
+    return !contextAlreadyDelivered;
+}
+function bootstrapContextFingerprint(workspace, agentsFiles, availableAgentsFiles) {
+    const payload = {
+        agentsFiles: agentsFiles
+            .map((file) => ({ path: resolve(file.path), content: file.content }))
+            .sort((left, right) => left.path.localeCompare(right.path)),
+        availableAgentsFiles: availableAgentsFiles
+            .map((file) => resolve(file.path))
+            .sort((left, right) => left.localeCompare(right)),
+        skills: workspace.skills
+            .map((skill) => ({
+            name: skill.name,
+            description: skill.description,
+            filePath: resolve(skill.filePath),
+            disableModelInvocation: skill.disableModelInvocation ?? false,
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name) || left.filePath.localeCompare(right.filePath)),
+        skillDiagnostics: workspace.skillDiagnostics,
+        capabilityGuides: workspace.capabilityGuides
+            .map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            filePath: resolve(guide.filePath),
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name)),
+        agentProfiles: workspace.agentProfiles
+            .map((profile) => ({
+            name: profile.name,
+            description: profile.description,
+            provider: profile.provider,
+            model: profile.model,
+            thinking: profile.thinking,
+            filePath: resolve(profile.filePath),
+        }))
+            .sort((left, right) => left.name.localeCompare(right.name)),
+    };
+    return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
+}
 async function canonicalPath(path) {
     const missingSegments = [];
     let candidate = path;

package/docs/chatgpt-coding-workflow.md

@@ -18,6 +18,60 @@ existing ID explicitly when the user wants to resume that logical workspace.
 A Git worktree directory is a separate physical workspace target from its source
 checkout, and each conversation can still have its own logical handle for it.
 
+### Bootstrap context and workspace inventory
+
+Normal coding still starts with the shortest path:
+
+```text
+open_workspace(path="~/project")
+```
+
+The default `context="auto"` keeps the first useful bootstrap while avoiding
+replay. ForgeRelay tracks delivered context by conversation plus canonical
+workspace target and a content fingerprint, not by logical `workspaceId`. If the
+same conversation opens or resumes another logical handle for the same physical
+project and the fingerprint is unchanged, the response keeps only lightweight
+workspace metadata. If loaded instruction contents or relevant Skill, Capability
+guide, profile, diagnostic, or nested-instruction metadata changes, the next
+automatic open returns the refreshed bootstrap.
+
+Two explicit controls are available for exceptional cases:
+
+```text
+open_workspace(workspaceId="ws_...", context="full")
+open_workspace(workspaceId="ws_...", context="none")
+```
+
+`full` forces a bootstrap refresh. `none` opens/resumes the workspace without
+returning the full project context and does not record the current fingerprint as
+already delivered. Context-delivery state is independent from logical-workspace
+selection, so closing or switching one handle does not make the conversation
+forget unchanged project context it already received.
+
+Do not enumerate workspace state on every normal open. When the user wants to
+continue an earlier task, choose among logical workspaces, or clean up accumulated
+state, use the same Core tool in inventory mode:
+
+```text
+open_workspace(action="list")
+open_workspace(action="list", root="~/project")
+open_workspace(action="list", staleOnly=true)
+```
+
+Inventory is paginated, defaults to 50 entries, and caps each page at 100. It can
+filter by `workspaceId`, persisted `status`, derived `state`, `mode`, canonical
+root/source root, or stale-only state. Entries include a compact label such as
+`project/ws_...`, checkout/worktree backing metadata, timestamps, idle duration,
+root validity, and whether that logical workspace is currently selected by this
+conversation. Listing is observational and does not refresh `lastUsedAt`.
+
+Treat persisted status and derived state separately. `status="active"` means the
+record has not been explicitly closed. A valid recent record has `state="active"`;
+a valid active record idle for more than two days has `state="stale"`; an active
+record whose root is missing or unusable has `state="invalid"`; and an explicitly
+finalized persisted record has `state="closed"`. Ask the user before cleanup, then
+use the existing `close_workspace` lifecycle on the selected `workspaceId`.
+
 ## Checkout-first behavior
 
 Checkout mode is the default:
@@ -131,8 +185,9 @@ worktrees, subagents, artifact/change-review workflows, Host/OAuth/MCP App
 integration, and long-running shell/PTY/process behavior. Optional guides are
 advertised only when their feature is enabled; for example, disabled subagents
 and artifact/change-review features do not add those descriptors to bootstrap
-context. Reopening a workspace in the same Host context does not repeat the
-descriptors, but the previously advertised guides remain valid.
+context. Bootstrap replay follows the conversation/canonical-target context
+fingerprint described above, so changing logical `workspaceId` alone does not
+repeat unchanged descriptors; previously advertised guides remain valid.
 
 The fingerprint is also a stale-Host-schema diagnostic. If `open_workspace`
 reports a capability such as `filesystem.rename-move` but the Host's current
@@ -223,12 +278,14 @@ Workspace IDs are logical conversation handles rather than physical-directory
 identities. The same conversation keeps a stable ID for a project, while another
 conversation normally receives a different ID pointing at the same checkout or
 worktree. `open_workspace` can explicitly resume a known `workspaceId`, and a
-fresh logical ID is created only when the user asks for one. When a project has
-other logical workspaces idle for more than two days, `open_workspace` reports
-all of them so the user can choose to resume or clean them up. `close_workspace`
-is the single public close operation: checkout-backed workspaces release the logical
-handle, while managed-worktree-backed workspaces require `commitMessage` and run the
-safe commit / fast-forward-only integration / cleanup lifecycle.
+fresh logical ID is created only when the user asks for one. The normal open path
+may still include `staleWorkspaces` as a passive reminder for same-target handles
+idle for more than two days; use `open_workspace(action="list")` for complete,
+filtered inventory when continuation or cleanup actually requires it.
+`close_workspace` is the single public close operation: checkout-backed workspaces
+release the logical handle, while managed-worktree-backed workspaces require
+`commitMessage` and run the safe commit / fast-forward-only integration / cleanup
+lifecycle.
 
 Shell commands are allowed to modify ordinary project files when that is a
 natural part of the user's requested development task; ForgeRelay does not apply

package/docs/configuration.md

@@ -163,12 +163,35 @@ receives a different ID for the same physical checkout/worktree. Pass
 `workspaceId` to `open_workspace` to explicitly resume an existing handle in the
 current conversation. `newWorkspace: true` allocates a new logical handle without
 creating another checkout or Git worktree and should be used only on explicit user
-request. Logical workspaces idle for more than two days are returned in `staleWorkspaces` so
-the user can choose whether to resume or release them. `close_workspace` removes a
-checkout-backed logical handle without deleting checkout files. For a managed-worktree-backed
-workspace, `close_workspace` requires `commitMessage` and runs the existing safe
-worktree finalize lifecycle: close Hooks, commit when needed, fast-forward-only
-integration, cleanup, and alias invalidation.
+request.
+
+Bootstrap delivery is tracked separately from the selected logical workspace.
+`open_workspace` defaults to `context="auto"`: ForgeRelay fingerprints the current
+project context and returns the full AGENTS/Skills/Capability-guide/profile bootstrap
+only when that conversation has not already received the current fingerprint for
+the canonical workspace target. `context="full"` forces a refresh;
+`context="none"` opens or resumes the logical workspace without returning the full
+bootstrap and does not mark the current fingerprint as delivered. Closing or
+switching a logical workspace therefore does not by itself cause unchanged project
+context to be injected again, while changed context produces a new fingerprint and
+is delivered on the next `auto` open.
+
+Use `open_workspace(action="list")` only when the Agent needs to continue an older
+logical workspace, choose among multiple handles, or organize workspace state. The
+inventory is paginated (50 records by default, at most 100) and can filter by
+workspace ID, persisted status, derived state, mode, canonical root/source root, or
+stale-only state. Reading inventory does not refresh `lastUsedAt`. Persisted
+`status="active"` means the record has not been explicitly closed; the derived
+`state` distinguishes `active`, `stale`, `invalid`, and `closed`. A missing checkout
+or externally removed managed-worktree root can therefore remain diagnostically
+`status="active"` while appearing as `state="invalid"`. The existing
+`staleWorkspaces` field remains a passive same-workspace reminder for old handles;
+`action="list"` is the formal on-demand inventory path.
+
+`close_workspace` removes a checkout-backed logical handle without deleting checkout
+files. For a managed-worktree-backed workspace, `close_workspace` requires
+`commitMessage` and runs the existing safe worktree finalize lifecycle: close Hooks,
+commit when needed, fast-forward-only integration, cleanup, and alias invalidation.
 
 Regular `bash` has no execution-timeout input. `action="run"` (the default) waits
 in the foreground for at most 300 seconds; if the process is still alive, the

package/docs/roadmap.md

@@ -170,7 +170,18 @@ capability
 - 删除已经完成迁移的 dedicated low-frequency tool aliases，确保新增 Capability 不再扩大常驻 tool count；
 - 简化 fingerprint，使其用于版本/运行时能力摘要与 stale-Host 诊断，而不是重新枚举 tool implementation；
 - 对 `open_workspace → catalog → capability describe/read/run`、managed worktree close、长进程 interaction、review/artifact capability、MCP App 与 stale-schema 情况做 7677 acceptance 和新 Host 会话验收；
-- 0.3.5 通过后，0.3 的 MCP progressive-disclosure 主题视为完成，0.4 回到原定 LSP code intelligence v1。
+- 0.3.5 完成 canonical MCP surface 与 fresh-Host 主验收后，0.3 的 progressive-disclosure 主体设计视为稳定；后续 0.3.x 只接收验收暴露出的兼容性或 lifecycle 补丁，0.4 仍回到原定 LSP code intelligence v1。
+
+### 0.3.6 — Workspace bootstrap 与 inventory 补丁
+
+0.3.6 处理 0.3.5 fresh-Host 验收后暴露的 Workspace 上下文与 logical-workspace 管理问题，不增加新的常驻 MCP tool，也不改变 0.4 的 LSP 主路线：
+
+- `open_workspace` 的 bootstrap 去重从 logical `workspaceId` 身份提升为 conversation scope + canonical workspace target + context fingerprint；同一 conversation 切换到同一物理 checkout/worktree 的其他 logical workspace 时，只要 AGENTS、Skills、Capability guide/profile 等相关上下文没有变化，就不重复注入完整 bootstrap；
+- `open_workspace` 提供 `context="auto" | "full" | "none"`。`auto` 默认只在当前 fingerprint 尚未交付或已变化时返回完整上下文，`full` 强制刷新，`none` 只取得 workspace handle/metadata 且不会把该 fingerprint 标记为已交付；
+- context-delivery 状态与 conversation 当前绑定的 logical workspace 分离持久化，因此关闭或切换 logical handle 不会让 Agent 在同一 conversation 中忘记已经收到的项目上下文；delivery 状态继续服从有限生命周期清理，而不是永久缓存；
+- `open_workspace(action="list")` 成为按需 logical-workspace inventory 入口，不增加 `list_workspaces`/`workspace.list` 第十个 Core tool；普通开发仍直接使用默认 `action="open"`，只有续接旧任务、选择 workspace 或整理状态时才读取 inventory；
+- inventory 区分持久化 `status` 与派生 `state`：`status="active"` 表示尚未显式关闭，`state` 再区分 active、stale、invalid 与 closed；missing root 或外部删除的 managed worktree 可以保持可诊断的 active record，同时显示为 invalid；
+- inventory 查看本身不刷新 workspace `lastUsedAt`，支持过滤与分页，并继续让现有 `close_workspace` 承担用户确认后的实际清理/finalize lifecycle。
 
 必要安全语义始终留在 Core tool interface、Capability contract 或自动 Hook report 中；渐进式披露不能成为隐藏权限、隐式 autonomous workflow 或绕过 allowed roots/auth 的机制。`rename` 继续作为文件和目录 move/rename 的统一 primitive。
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.3.5",
+  "version": "0.3.6",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",

package/scripts/debug/accept.mjs

@@ -223,13 +223,16 @@ try {
   assert.equal(historicalTemplate.text, template.text);
   pass("MCP app template", `${templateUri} + legacy/history compatibility -> ${scriptUrl}`);
 
+  const workspaceConversationMeta = { "openai/session": "acceptance-workspace" };
   const opened = callTool(oauth.accessToken, sessionId, 3, "open_workspace", {
     path: checkoutWorkspace,
-  });
+  }, workspaceConversationMeta);
   const workspaceId = opened.structuredContent.workspaceId;
   assert.match(workspaceId, /^ws_/);
+  assert.equal(opened.structuredContent.action, "open");
   assert.equal(opened.structuredContent.root, checkoutWorkspace);
   assert.equal(opened.structuredContent.mode, "checkout");
+  assert.equal(typeof opened.structuredContent.contextFingerprint, "string");
   assert.deepEqual(opened.structuredContent.capabilityFingerprint, {
     version: packageJson.version,
     toolMode: "full",
@@ -254,6 +257,56 @@ try {
   ]);
   assert.equal(capabilityCatalog[0].available, true);
   assert.equal(capabilityCatalog[0].guide.name, "lifecycle-hooks");
+
+  const freshLogical = callTool(oauth.accessToken, sessionId, 84, "open_workspace", {
+    path: checkoutWorkspace,
+    newWorkspace: true,
+  }, workspaceConversationMeta);
+  const freshLogicalId = freshLogical.structuredContent.workspaceId;
+  assert.notEqual(freshLogicalId, workspaceId);
+  assert.equal(freshLogical.structuredContent.action, "open");
+  assert.equal(
+    freshLogical.structuredContent.contextFingerprint,
+    opened.structuredContent.contextFingerprint,
+  );
+  assert.equal(freshLogical.structuredContent.agentsFiles, undefined);
+  assert.equal(freshLogical.structuredContent.capabilityGuides, undefined);
+
+  const workspaceInventory = callTool(oauth.accessToken, sessionId, 85, "open_workspace", {
+    action: "list",
+    root: checkoutWorkspace,
+  }, workspaceConversationMeta);
+  assert.equal(workspaceInventory.structuredContent.action, "list");
+  assert.equal(workspaceInventory.structuredContent.summary.matching, 2);
+  const inventoryEntries = workspaceInventory.structuredContent.workspaces;
+  assert.equal(inventoryEntries.length, 2);
+  assert.equal(
+    inventoryEntries.find((entry) => entry.workspaceId === freshLogicalId)?.current,
+    true,
+  );
+  assert.equal(
+    inventoryEntries.find((entry) => entry.workspaceId === workspaceId)?.current,
+    false,
+  );
+
+  const closedFreshLogical = callTool(oauth.accessToken, sessionId, 86, "close_workspace", {
+    workspaceId: freshLogicalId,
+  });
+  assert.equal(closedFreshLogical.isError, undefined);
+  const resumedOriginal = callTool(oauth.accessToken, sessionId, 87, "open_workspace", {
+    workspaceId,
+  }, workspaceConversationMeta);
+  assert.equal(resumedOriginal.structuredContent.workspaceId, workspaceId);
+  assert.equal(resumedOriginal.structuredContent.agentsFiles, undefined);
+  assert.equal(
+    resumedOriginal.structuredContent.contextFingerprint,
+    opened.structuredContent.contextFingerprint,
+  );
+  pass(
+    "workspace context + inventory",
+    `${workspaceId} -> ${freshLogicalId} -> list -> close -> resume without bootstrap replay`,
+  );
+
   const directCapability = callTool(oauth.accessToken, sessionId, 79, "capability", {
     workspaceId,
     name: "hooks.check",
@@ -590,12 +643,16 @@ function mcpRequest(accessToken, sessionId, request) {
   return { response, message: parseMcpMessage(response.body, request.id) };
 }
 
-function callTool(accessToken, sessionId, id, name, args) {
+function callTool(accessToken, sessionId, id, name, args, meta) {
   const message = mcpRequest(accessToken, sessionId, {
     jsonrpc: "2.0",
     id,
     method: "tools/call",
-    params: { name, arguments: args },
+    params: {
+      name,
+      arguments: args,
+      ...(meta ? { _meta: meta } : {}),
+    },
   }).message;
   assert.equal(message.id, id);
   assert.ok(message.result, `tool ${name} did not return a result`);