@akira-tl/forgerelay 0.7.2 → 0.8.0

package/CHANGELOG.md

@@ -4,6 +4,28 @@ All notable ForgeRelay changes are documented here.
 
 ## [Unreleased]
 
+## [0.8.0] - 2026-08-30
+
+### Changed
+
+- Workspace identity is now canonical per physical checkout or managed worktree, so different Host conversations reuse one persistent `workspaceId`; legacy duplicate IDs remain compatible aliases, and `newWorkspace` no longer creates same-target duplicates.
+
+### Fixed
+
+- Composite member bootstrap now preserves capability guides and subagent provider/profile context exposed by the underlying Workspace.
+- Composite member `context="none"` now truthfully reports suppressed bootstrap instead of claiming it was already delivered.
+
+## [0.7.4] - 2026-08-30
+
+### Added
+
+- Subagent Run restart reconciliation now preserves live owners and marks stale active Runs `interrupted` without replaying the old prompt.
+- First-class Subagent Sessions now work through Workspace Relay and Composite explicit-member routing while keeping Session state on the Execution ForgeRelay.
+
+### Fixed
+
+- Composite Capability result remapping now preserves the declared output schema during relayed Subagent operations.
+
 ## [0.7.2] - 2026-08-30
 
 ### Added

package/capabilities/subagents/GUIDE.md

@@ -103,6 +103,8 @@ Run 完成后：
 - 成功领取后 mailbox 条目立即删除，同一个 completion 不重复交付；
 - 未领取 completion 可以跨正常 ForgeRelay 进程重启保留。
 
+ForgeRelay 只为 active Run 持久化最小 execution-owner 元数据（owner identity / PID），不保存 delegated prompt。后续 Session 操作会先做 restart reconciliation：能够证明 owner 仍存活的 Run 保持 `running`；无法证明仍有执行 owner 的 Run 一次性转为 `interrupted`，Session 回到 `idle`。ForgeRelay 绝不自动 replay 被中断 Run 的旧 prompt；如果 provider continuation 仍有效，由 Host 显式 `resume` 新 prompt。
+
 如果需要等待结果，使用 `status` 进行有节制的后续查询；不要高频短轮询。
 
 ## 数据所有权

package/dist/cli.js

@@ -580,7 +580,8 @@ function createCliSubagentSessionManager(config = loadConfig()) {
     return new SubagentSessionManager(config, {
         launch(request) {
             const promptFile = writeSubagentPromptFile(request.prompt);
-            spawnSubagentWorker(request.sessionId, promptFile);
+            const pid = spawnSubagentWorker(request.sessionId, promptFile);
+            return pid === undefined ? undefined : { id: `subagent-worker-${request.runId}`, pid };
         },
     });
 }
@@ -599,6 +600,7 @@ function spawnSubagentWorker(sessionId, promptFile) {
         env: process.env,
     });
     child.unref();
+    return child.pid;
 }
 function writeSubagentPromptFile(prompt) {
     const directory = mkdtempSync(join(tmpdir(), "forgerelay-agent-prompt-"));

package/dist/db/migrations.js

@@ -69,6 +69,16 @@ const migrations = [
         name: "subagent-session-coordination",
         up: migrateSubagentSessionCoordination,
     },
+    {
+        version: 15,
+        name: "subagent-run-ownership",
+        up: migrateSubagentRunOwnership,
+    },
+    {
+        version: 16,
+        name: "workspace-session-aliases",
+        up: migrateWorkspaceSessionAliases,
+    },
 ];
 export function migrateDatabase(sqlite) {
     const migrate = sqlite.transaction(() => {
@@ -358,6 +368,25 @@ function migrateSubagentSessionCoordination(sqlite) {
     addColumnIfMissing(sqlite, "local_agent_sessions", "latest_run_outcome", "text");
     addColumnIfMissing(sqlite, "local_agent_sessions", "latest_run_finished_at", "text");
 }
+function migrateSubagentRunOwnership(sqlite) {
+    migrateSubagentSessionCoordination(sqlite);
+    addColumnIfMissing(sqlite, "local_agent_sessions", "active_owner_id", "text");
+    addColumnIfMissing(sqlite, "local_agent_sessions", "active_owner_pid", "integer");
+}
+function migrateWorkspaceSessionAliases(sqlite) {
+    sqlite.exec(`
+    create table if not exists workspace_session_aliases (
+      alias_id text primary key,
+      workspace_session_id text not null,
+      foreign key (workspace_session_id)
+        references workspace_sessions(id)
+        on delete cascade
+    );
+
+    create index if not exists workspace_session_aliases_workspace_idx
+      on workspace_session_aliases(workspace_session_id);
+  `);
+}
 function migrateActivityHostTurnWorkspace(sqlite) {
     migrateActivityHostTurns(sqlite);
     addColumnIfMissing(sqlite, "activity_host_turns", "workspace_id", "text");

package/dist/db/schema.js

@@ -16,6 +16,14 @@ export const workspaceSessions = sqliteTable("workspace_sessions", {
     index("workspace_sessions_root_idx").on(table.root, table.lastUsedAt),
     index("workspace_sessions_status_idx").on(table.status, table.lastUsedAt),
 ]);
+export const workspaceSessionAliases = sqliteTable("workspace_session_aliases", {
+    aliasId: text("alias_id").primaryKey(),
+    workspaceSessionId: text("workspace_session_id")
+        .notNull()
+        .references(() => workspaceSessions.id, { onDelete: "cascade" }),
+}, (table) => [
+    index("workspace_session_aliases_workspace_idx").on(table.workspaceSessionId),
+]);
 export const loadedAgentFiles = sqliteTable("loaded_agent_files", {
     workspaceSessionId: text("workspace_session_id")
         .notNull()
@@ -155,6 +163,8 @@ export const localAgentSessions = sqliteTable("local_agent_sessions", {
     activeRunId: text("active_run_id"),
     activeActivityId: text("active_activity_id"),
     activeRunStartedAt: text("active_run_started_at"),
+    activeOwnerId: text("active_owner_id"),
+    activeOwnerPid: integer("active_owner_pid"),
     latestRunId: text("latest_run_id"),
     latestRunOutcome: text("latest_run_outcome"),
     latestRunFinishedAt: text("latest_run_finished_at"),

package/dist/server.js

@@ -1362,6 +1362,22 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         const skills = workspace.skills
             .filter((skill) => !skill.disableModelInvocation)
             .map((skill) => ({ name: skill.name, description: skill.description }));
+        const capabilityGuides = workspace.capabilityGuides.map((guide) => ({
+            name: guide.name,
+            description: guide.description,
+            whenToRead: guide.whenToRead,
+            path: formatPathForPrompt(guide.filePath),
+        }));
+        const agentProviders = config.subagents ? subagentProviders : [];
+        const agents = workspace.agentProfiles.map((profile) => {
+            const summary = summarizeSubagentProfile(profile);
+            const availability = agentProviders.find((provider) => provider.name === summary.provider);
+            return {
+                ...summary,
+                providerAvailable: availability?.available,
+                providerUnavailableReason: availability?.reason,
+            };
+        });
         return {
             member: memberName,
             workspaceId: compositeWorkspaceId,
@@ -1373,15 +1389,20 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             includeBootstrapContext: opened.includeBootstrapContext,
             ...(opened.includeBootstrapContext
                 ? {
+                    capabilityGuides,
                     agentsFiles,
                     availableAgentsFiles,
                     skills,
+                    agentProviders,
+                    agents,
                     skillDiagnostics: redactSkillDiagnosticPaths(workspace.skillDiagnostics),
                 }
                 : {}),
             instruction: opened.includeBootstrapContext
                 ? `Bootstrap context for Composite member ${memberName}. Keep using Composite workspaceId ${compositeWorkspaceId} and pass member=${memberName} for work operations.`
-                : `Composite member ${memberName} context was already delivered for this Host context; keep using Composite workspaceId ${compositeWorkspaceId} with member=${memberName}.`,
+                : contextPolicy === "none"
+                    ? `Bootstrap context for Composite member ${memberName} was intentionally suppressed by context=none. Keep using Composite workspaceId ${compositeWorkspaceId} with member=${memberName}; request context=auto or context=full when member bootstrap is needed.`
+                    : `Composite member ${memberName} context was already delivered for this Host context; keep using Composite workspaceId ${compositeWorkspaceId} with member=${memberName}.`,
         };
     };
     const coreOperations = createCoreOperationExecutor({
@@ -1960,7 +1981,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             action: z
                 .enum(["open", "list", "member"])
                 .optional()
-                .describe("Defaults to open. Use list to inspect logical workspaces. Use member to add/remove a named execution member on an existing Composite Workspace."),
+                .describe("Defaults to open. Use list to inspect known Workspaces. Use member to add/remove a named execution member on an existing Composite Workspace."),
             memberAction: z
                 .enum(["add", "update", "remove"])
                 .optional()
@@ -2000,7 +2021,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             workspaceId: z
                 .string()
                 .optional()
-                .describe("For action=open, an existing logical workspace ID to resume in this conversation. For action=list, filters inventory to one workspace ID."),
+                .describe("For action=open, an existing Workspace ID to resume or reuse. Historical duplicate IDs from earlier ForgeRelay versions may resolve to the canonical Workspace ID. For action=list, filters inventory to one Workspace ID."),
             mode: z
                 .enum(["checkout", "worktree"])
                 .optional()
@@ -2016,7 +2037,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             newWorkspace: z
                 .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."),
+                .describe("Deprecated compatibility flag. It no longer creates another Workspace identity for the same physical checkout or managed worktree; ForgeRelay reuses that target's canonical Workspace. Use newWorktree=true when the user explicitly needs separate Git isolation."),
             context: z
                 .enum(["auto", "full", "none"])
                 .optional()
@@ -2036,7 +2057,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
             staleOnly: z
                 .boolean()
                 .optional()
-                .describe("For action=list, return only active logical workspaces idle for more than two days."),
+                .describe("For action=list, return only active Workspaces idle for more than two days."),
             offset: z
                 .number()
                 .int()
@@ -2570,7 +2591,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         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 workspaceManagementInstruction = "When you need to inspect known Workspaces, continue earlier work, 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, load it with read(path=\"skills://<name>\") before proceeding. When a task matches a 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}`;
@@ -2632,7 +2653,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                         ? `Known worktrees: ${knownWorktrees.map((worktree) => `${worktree.path} [${worktree.workspaceId}]${worktree.branch ? ` branch=${worktree.branch}` : ""}${worktree.targetBranch ? ` target=${worktree.targetBranch}` : ""}${worktree.current ? " (current)" : ""}`).join(", ")}`
                         : undefined,
                     staleWorkspaces.length > 0
-                        ? `Idle logical workspaces for this same physical workspace (>2 days): ${staleWorkspaces.map((stale) => `${stale.workspaceId} last-used=${stale.lastUsedAt}`).join(", ")}. Tell the user these are available to resume or explicitly close; do not clean them up automatically.`
+                        ? `This Workspace has been idle for more than 2 days: ${staleWorkspaces.map((stale) => `${stale.workspaceId} last-used=${stale.lastUsedAt}`).join(", ")}. It remains available to resume or explicitly close; do not clean it up automatically.`
                         : undefined,
                     `ForgeRelay ${capabilityFingerprint.version} capabilities: ${capabilityFingerprint.capabilities.join(", ")}`,
                     instruction,
@@ -2764,6 +2785,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
         outputSchema: {
             name: z.string(),
             action: z.enum(["describe", "run"]),
+            member: z.string().optional(),
             capability: z.unknown().optional(),
             result: z.unknown().optional(),
             error: capabilityErrorOutputSchema.optional(),
@@ -2899,7 +2921,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
     });
     registerAppTool(server, toolNames.closeWorkspace, {
         title: "Close workspace",
-        description: "Close one workspace after the user chooses cleanup. Composite Workspaces dissolve here: only the Composite identity and member links are removed; member Workspaces, files, processes, worktrees, and relay routes remain intact. Checkout-backed workspaces release only the logical handle. Managed-worktree-backed workspaces run the safe finalize lifecycle (hooks, commit, fast-forward integration, cleanup) and require commitMessage. Running processes block ordinary Workspace closure.",
+        description: "Close one Workspace after the user chooses cleanup. In v0.8.0, Composite close still dissolves only the Composite identity/member links. Checkout close removes ForgeRelay state but never project files. Managed-worktree-backed Workspaces run the safe finalize lifecycle (hooks, commit, fast-forward integration, cleanup) and require commitMessage. Running processes block ordinary Workspace closure.",
         inputSchema: {
             workspaceId: z.string().describe("Workspace identifier to close."),
             commitMessage: z
@@ -2991,7 +3013,7 @@ export function createMcpServer(config, workspaces, reviewCheckpoints, processSe
                     const busyWorkspaceIds = physicalWorkspaceIds
                         .filter((id) => processSessions.activeWorkspaceIds().has(id));
                     if (busyWorkspaceIds.length > 0) {
-                        throw new Error(`Cannot close this worktree-backed workspace while logical workspace processes are still running: ${busyWorkspaceIds.join(", ")}.`);
+                        throw new Error(`Cannot close this worktree-backed Workspace while Workspace processes are still running: ${busyWorkspaceIds.join(", ")}.`);
                     }
                     const startedAt = performance.now();
                     const retirement = await codeIntelligence.retireWorkspaceRoot(workspace.root);

package/dist/subagents/sessions/capability.js

@@ -9,18 +9,23 @@ export class SubagentSessionCapability {
     activityLifecycle;
     mailbox;
     providerRunner;
+    ownerAliveOverride;
     activeRuns = new Map();
     constructor(config, activityLifecycle, options = {}) {
         this.config = config;
         this.activityLifecycle = activityLifecycle;
         this.mailbox = new SubagentDeliveryMailbox(config.stateDir);
         this.providerRunner = options.providerRunner ?? defaultProviderRunner;
+        this.ownerAliveOverride = options.ownerAlive;
     }
     async run(input, context, options) {
         const manager = new SubagentSessionManager(this.config, {
             launch: (request) => this.launch(request),
         });
         try {
+            const reconciled = manager.reconcile({ workspaceId: context.workspaceId }, (run) => this.ownerAlive(run));
+            for (const entry of reconciled)
+                this.recordInterruption(entry, options.activityId);
             switch (input.operation) {
                 case "start": {
                     const started = await manager.start({
@@ -118,17 +123,19 @@ export class SubagentSessionCapability {
         };
     }
     launch(request) {
+        const ownerId = `subagent-owner-${process.pid}-${request.runId}`;
         const controller = new AbortController();
         const completion = executeSubagentRun(this.config, { ...request, signal: controller.signal }, this.providerRunner).then((result) => {
             this.recordCompletion(result);
             return result;
         });
-        this.activeRuns.set(request.runId, { controller, completion });
+        this.activeRuns.set(request.runId, { ownerId, controller, completion });
         void completion.finally(() => {
             this.activeRuns.delete(request.runId);
         }).catch(() => {
             // Unexpected orchestration failures surface through later reconciliation.
         });
+        return { id: ownerId, pid: process.pid };
     }
     async stop(manager, sessionId, workspaceId) {
         let session = manager.get(sessionId, { workspaceId });
@@ -158,6 +165,58 @@ export class SubagentSessionCapability {
             ...(session.latestRun?.id === activeRun.id ? { run: publicRun(session.latestRun) } : {}),
         };
     }
+    ownerAlive(run) {
+        if (this.ownerAliveOverride)
+            return this.ownerAliveOverride(run);
+        if (!run.ownerId || run.ownerPid === undefined)
+            return false;
+        const active = this.activeRuns.get(run.id);
+        if (run.ownerPid === process.pid)
+            return active?.ownerId === run.ownerId;
+        try {
+            process.kill(run.ownerPid, 0);
+            return true;
+        }
+        catch (error) {
+            return error.code === "EPERM";
+        }
+    }
+    recordInterruption(entry, fallbackActivityId) {
+        const sourceActivityId = entry.run.activityId ?? fallbackActivityId;
+        if (!sourceActivityId)
+            return;
+        const record = () => this.activityLifecycle.recordLinked({
+            sourceActivityId,
+            tool: "subagent_result",
+            request: { sessionId: entry.session.id, runId: entry.run.id },
+            result: {
+                sessionId: entry.session.id,
+                runId: entry.run.id,
+                provider: entry.session.provider,
+                status: "interrupted",
+            },
+            outcome: { type: "failed", error: "Subagent Run interrupted." },
+        });
+        try {
+            record();
+        }
+        catch {
+            if (!fallbackActivityId || fallbackActivityId === sourceActivityId)
+                return;
+            this.activityLifecycle.recordLinked({
+                sourceActivityId: fallbackActivityId,
+                tool: "subagent_result",
+                request: { sessionId: entry.session.id, runId: entry.run.id },
+                result: {
+                    sessionId: entry.session.id,
+                    runId: entry.run.id,
+                    provider: entry.session.provider,
+                    status: "interrupted",
+                },
+                outcome: { type: "failed", error: "Subagent Run interrupted." },
+            });
+        }
+    }
     recordCompletion(completion) {
         if (!completion.activityId)
             return;

package/dist/subagents/sessions/manager.js

@@ -52,13 +52,16 @@ export class SubagentSessionManager {
         const run = session.activeRun;
         if (!run)
             throw new Error(`Subagent Session ${session.id} did not create an active Run.`);
-        this.launcher.launch({
+        const owned = this.assignOwner(session, run, this.launcher.launch({
             sessionId: session.id,
             runId,
             ...(input.activityId ? { activityId: input.activityId } : {}),
             prompt: input.prompt,
-        });
-        return { session, run };
+        }));
+        return {
+            session: owned,
+            run: owned.activeRun ?? (owned.latestRun?.id === run.id ? owned.latestRun : run),
+        };
     }
     resume(input, scope = {}) {
         const existing = this.store.getInScope(input.sessionId, scope);
@@ -90,13 +93,38 @@ export class SubagentSessionManager {
             status: "running",
             activeRun: run,
         });
-        this.launcher.launch({
+        const owned = this.assignOwner(session, run, this.launcher.launch({
             sessionId: session.id,
             runId,
             ...(input.activityId ? { activityId: input.activityId } : {}),
             prompt: input.prompt,
-        });
-        return { session, run };
+        }));
+        return {
+            session: owned,
+            run: owned.activeRun ?? (owned.latestRun?.id === run.id ? owned.latestRun : run),
+        };
+    }
+    reconcile(scope, ownerAlive) {
+        const reconciled = [];
+        for (const session of this.store.list(scope)) {
+            const run = session.activeRun;
+            if (!run || ownerAlive(run))
+                continue;
+            const interrupted = {
+                id: run.id,
+                status: "interrupted",
+                ...(run.activityId ? { activityId: run.activityId } : {}),
+                ...(run.startedAt ? { startedAt: run.startedAt } : {}),
+                finishedAt: new Date().toISOString(),
+            };
+            const updated = this.store.update(session.id, {
+                status: "idle",
+                activeRun: undefined,
+                latestRun: interrupted,
+            });
+            reconciled.push({ session: updated, run: interrupted });
+        }
+        return reconciled;
     }
     delete(sessionId, scope = {}) {
         const session = this.store.getInScope(sessionId, scope);
@@ -112,6 +140,11 @@ export class SubagentSessionManager {
     close() {
         this.store.close();
     }
+    assignOwner(session, run, owner) {
+        if (!owner)
+            return session;
+        return this.store.assignActiveRunOwner(session.id, run.id, owner);
+    }
 }
 function newRunId() {
     return `run_${randomUUID().replaceAll("-", "").slice(0, 12)}`;

package/dist/subagents/sessions/mcp/runtime.js

@@ -3,6 +3,7 @@ export function createSubagentMcpRuntime(config, activityLifecycle, options = {}
     const capability = config.subagents
         ? new SubagentSessionCapability(config, activityLifecycle, {
             providerRunner: options.subagentProviderRunner,
+            ownerAlive: options.subagentOwnerAlive,
         })
         : undefined;
     return {

package/dist/subagents/sessions/store.js

@@ -47,6 +47,8 @@ export class SubagentSessionStore {
                         status: "running",
                         ...(input.activeRun.activityId ? { activityId: input.activeRun.activityId } : {}),
                         startedAt: input.activeRun.startedAt,
+                        ...(input.activeRun.ownerId ? { ownerId: input.activeRun.ownerId } : {}),
+                        ...(input.activeRun.ownerPid !== undefined ? { ownerPid: input.activeRun.ownerPid } : {}),
                     },
                 }
                 : {}),
@@ -67,6 +69,8 @@ export class SubagentSessionStore {
           active_run_id,
           active_activity_id,
           active_run_started_at,
+          active_owner_id,
+          active_owner_pid,
           latest_run_id,
           latest_run_outcome,
           latest_run_finished_at,
@@ -75,8 +79,8 @@ export class SubagentSessionStore {
           hook_reports_json,
           created_at,
           updated_at
-        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, null, null, null, ?, ?)`)
-            .run(record.id, record.workspaceId ?? null, record.workspaceRoot, record.profileName, record.provider, record.model ?? null, record.thinking ?? null, null, record.status, record.activeRun?.id ?? null, record.activeRun?.activityId ?? null, record.activeRun?.startedAt ?? null, null, null, null, record.createdAt, record.updatedAt);
+        ) values (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, null, null, null, ?, ?)`)
+            .run(record.id, record.workspaceId ?? null, record.workspaceRoot, record.profileName, record.provider, record.model ?? null, record.thinking ?? null, null, record.status, record.activeRun?.id ?? null, record.activeRun?.activityId ?? null, record.activeRun?.startedAt ?? null, record.activeRun?.ownerId ?? null, record.activeRun?.ownerPid ?? null, null, null, null, record.createdAt, record.updatedAt);
         return record;
     }
     get(idOrPrefix) {
@@ -126,6 +130,8 @@ export class SubagentSessionStore {
           active_run_id = ?,
           active_activity_id = ?,
           active_run_started_at = ?,
+          active_owner_id = ?,
+          active_owner_pid = ?,
           latest_run_id = ?,
           latest_run_outcome = ?,
           latest_run_finished_at = ?,
@@ -134,9 +140,18 @@ export class SubagentSessionStore {
           hook_reports_json = null,
           updated_at = ?
          where id = ?`)
-            .run(updated.workspaceId ?? null, resolve(updated.workspaceRoot), updated.profileName, updated.provider, updated.model ?? null, updated.thinking ?? null, updated.providerSessionId ?? null, updated.status, updated.activeRun?.id ?? null, updated.activeRun?.activityId ?? null, updated.activeRun?.startedAt ?? null, updated.latestRun?.id ?? null, updated.latestRun && updated.latestRun.status !== "running" ? updated.latestRun.status : null, updated.latestRun?.finishedAt ?? null, updated.updatedAt, updated.id);
+            .run(updated.workspaceId ?? null, resolve(updated.workspaceRoot), updated.profileName, updated.provider, updated.model ?? null, updated.thinking ?? null, updated.providerSessionId ?? null, updated.status, updated.activeRun?.id ?? null, updated.activeRun?.activityId ?? null, updated.activeRun?.startedAt ?? null, updated.activeRun?.ownerId ?? null, updated.activeRun?.ownerPid ?? null, updated.latestRun?.id ?? null, updated.latestRun && updated.latestRun.status !== "running" ? updated.latestRun.status : null, updated.latestRun?.finishedAt ?? null, updated.updatedAt, updated.id);
         return updated;
     }
+    assignActiveRunOwner(id, runId, owner) {
+        this.database.sqlite.prepare(`update local_agent_sessions
+          set active_owner_id = ?, active_owner_pid = ?, updated_at = ?
+        where id = ? and active_run_id = ?`).run(owner.id, owner.pid ?? null, new Date().toISOString(), id, runId);
+        const current = this.getById(id);
+        if (!current)
+            throw new Error(`Unknown subagent id: ${id}`);
+        return current;
+    }
     delete(id) {
         this.database.sqlite.prepare("delete from local_agent_sessions where id = ?").run(id);
     }
@@ -160,6 +175,8 @@ function rowToSubagentSession(row) {
             status: "running",
             ...(row.active_activity_id ? { activityId: row.active_activity_id } : {}),
             ...(row.active_run_started_at ? { startedAt: row.active_run_started_at } : {}),
+            ...(row.active_owner_id ? { ownerId: row.active_owner_id } : {}),
+            ...(row.active_owner_pid !== null ? { ownerPid: row.active_owner_pid } : {}),
         }
         : undefined;
     const latestOutcome = readOutcome(row.latest_run_outcome);

package/dist/workspace-store.js

@@ -1,6 +1,6 @@
 import { and, desc, eq } from "drizzle-orm";
 import { openDatabase } from "./db/client.js";
-import { workspaceContextDeliveries, workspaceConversationBindings, workspaceSessions, } from "./db/schema.js";
+import { workspaceContextDeliveries, workspaceConversationBindings, workspaceSessionAliases, workspaceSessions, } from "./db/schema.js";
 const DEFAULT_TOUCH_FLUSH_INTERVAL_MS = 5 * 60 * 1_000;
 export class SqliteWorkspaceStore {
     database;
@@ -61,24 +61,33 @@ export class SqliteWorkspaceStore {
         return session;
     }
     getSession(id) {
+        const sessionId = this.resolveSessionId(id);
+        if (!sessionId)
+            return undefined;
         const row = this.database.db
             .select()
             .from(workspaceSessions)
-            .where(eq(workspaceSessions.id, id))
+            .where(eq(workspaceSessions.id, sessionId))
             .get();
         if (!row)
             return undefined;
-        return applySessionTouch(rowToWorkspaceSession(row), this.pendingSessionTouches.get(id));
+        return applySessionTouch(rowToWorkspaceSession(row), this.pendingSessionTouches.get(sessionId));
     }
     touchSession(id) {
-        this.pendingSessionTouches.set(id, this.now().toISOString());
+        const sessionId = this.resolveSessionId(id);
+        if (!sessionId)
+            return;
+        this.pendingSessionTouches.set(sessionId, this.now().toISOString());
     }
     setSessionStatus(id, status) {
-        this.pendingSessionTouches.delete(id);
+        const sessionId = this.resolveSessionId(id);
+        if (!sessionId)
+            return;
+        this.pendingSessionTouches.delete(sessionId);
         this.database.db
             .update(workspaceSessions)
             .set({ status, lastUsedAt: this.now().toISOString() })
-            .where(eq(workspaceSessions.id, id))
+            .where(eq(workspaceSessions.id, sessionId))
             .run();
     }
     listSessions(input = {}) {
@@ -100,11 +109,56 @@ export class SqliteWorkspaceStore {
             .map((session) => applySessionTouch(session, this.pendingSessionTouches.get(session.id)))
             .sort((left, right) => right.lastUsedAt.localeCompare(left.lastUsedAt));
     }
+    foldSessions(input) {
+        const aliases = input.aliasIds.filter((id) => id !== input.canonicalId);
+        if (aliases.length === 0)
+            return;
+        const fold = this.database.sqlite.transaction(() => {
+            this.database.sqlite.prepare(`
+        update workspace_sessions
+           set created_at = ?, last_used_at = ?, status = ?
+         where id = ?
+      `).run(input.createdAt, input.lastUsedAt, input.status, input.canonicalId);
+            const rebindConversation = this.database.sqlite.prepare(`
+        update workspace_conversation_bindings
+           set workspace_session_id = ?
+         where workspace_session_id = ?
+      `);
+            const rebindSubagents = this.database.sqlite.prepare(`
+        update local_agent_sessions
+           set workspace_id = ?
+         where workspace_id = ?
+      `);
+            const rebindAliases = this.database.sqlite.prepare(`
+        update workspace_session_aliases
+           set workspace_session_id = ?
+         where workspace_session_id = ?
+      `);
+            const deleteSession = this.database.sqlite.prepare("delete from workspace_sessions where id = ?");
+            const rememberAlias = this.database.sqlite.prepare(`
+        insert into workspace_session_aliases (alias_id, workspace_session_id)
+        values (?, ?)
+        on conflict(alias_id) do update set workspace_session_id = excluded.workspace_session_id
+      `);
+            for (const aliasId of aliases) {
+                rebindConversation.run(input.canonicalId, aliasId);
+                rebindSubagents.run(input.canonicalId, aliasId);
+                rebindAliases.run(input.canonicalId, aliasId);
+                deleteSession.run(aliasId);
+                rememberAlias.run(aliasId, input.canonicalId);
+                this.pendingSessionTouches.delete(aliasId);
+            }
+        });
+        fold.immediate();
+    }
     deleteSession(id) {
-        this.pendingSessionTouches.delete(id);
+        const sessionId = this.resolveSessionId(id);
+        if (!sessionId)
+            return;
+        this.pendingSessionTouches.delete(sessionId);
         this.database.db
             .delete(workspaceSessions)
-            .where(eq(workspaceSessions.id, id))
+            .where(eq(workspaceSessions.id, sessionId))
             .run();
     }
     listConversationBindings() {
@@ -212,6 +266,21 @@ export class SqliteWorkspaceStore {
             .where(and(eq(workspaceContextDeliveries.conversationScopeId, conversationScopeId), eq(workspaceContextDeliveries.targetKey, targetKey)))
             .run();
     }
+    resolveSessionId(id) {
+        const direct = this.database.db
+            .select({ id: workspaceSessions.id })
+            .from(workspaceSessions)
+            .where(eq(workspaceSessions.id, id))
+            .get();
+        if (direct)
+            return direct.id;
+        return this.database.db
+            .select({ workspaceSessionId: workspaceSessionAliases.workspaceSessionId })
+            .from(workspaceSessionAliases)
+            .where(eq(workspaceSessionAliases.aliasId, id))
+            .get()
+            ?.workspaceSessionId;
+    }
     get pendingTouchCount() {
         return this.pendingSessionTouches.size + this.pendingConversationTouches.size;
     }

package/dist/workspaces.js

@@ -1,4 +1,5 @@
 import { createHash, randomBytes } from "node:crypto";
+import { realpathSync } from "node:fs";
 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";
@@ -23,6 +24,7 @@ export class WorkspaceRegistry {
         this.config = config;
         this.store = store;
         this.hooks = new HookRunner(config.hooks, config.logging);
+        this.foldLegacyWorkspaceSessions();
         this.pruneIdleWorkspaceSessions(new Set(), true);
     }
     get cachedWorkspaceCount() {
@@ -42,7 +44,7 @@ export class WorkspaceRegistry {
         if (mode === "worktree") {
             return this.openReusableWorktree(workspaceInput, openOptions.conversationScopeId);
         }
-        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId, workspaceInput.newWorkspace ?? false, bootstrapContext);
+        return this.openReusableCheckout(workspaceInput.path, openOptions.conversationScopeId, bootstrapContext);
     }
     async listWorkspaces(input = {}, openOptions = {}) {
         this.pruneIdleWorkspaceSessions(openOptions.protectedWorkspaceIds ?? new Set());
@@ -205,22 +207,23 @@ export class WorkspaceRegistry {
     }
     closeWorkspace(workspaceId) {
         const workspace = this.getWorkspace(workspaceId);
+        const canonicalWorkspaceId = workspace.id;
         if (workspace.mode === "worktree") {
             const aliases = this.activeSessions("worktree")
                 .filter((session) => resolve(session.root) === resolve(workspace.root));
             if (aliases.length <= 1) {
-                throw new Error(`Workspace ${workspaceId} is the last active handle for a worktree. Use close_worktree to finalize and remove the physical worktree, or keep this handle as its anchor.`);
+                throw new Error(`Workspace ${canonicalWorkspaceId} is backed by a managed worktree. Use close_workspace with its managed-worktree finalize lifecycle instead of releasing the physical target as a separate handle.`);
             }
         }
         if (this.store) {
             for (const binding of this.store.listConversationBindings()) {
-                if (binding.workspaceSessionId === workspaceId) {
+                if (binding.workspaceSessionId === canonicalWorkspaceId) {
                     this.store.deleteConversationBinding(binding.conversationScopeId, binding.targetKey);
                 }
             }
-            this.store.deleteSession(workspaceId);
+            this.store.deleteSession(canonicalWorkspaceId);
         }
-        this.workspaces.delete(workspaceId);
+        this.workspaces.delete(canonicalWorkspaceId);
     }
     workspaceIdsForPhysicalWorkspace(workspace) {
         const root = resolve(workspace.root);
@@ -325,30 +328,18 @@ export class WorkspaceRegistry {
         }
         return { ...result, hookReports };
     }
-    async openReusableCheckout(path, conversationScopeId, newWorkspace, bootstrapContext) {
+    async openReusableCheckout(path, conversationScopeId, 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, bootstrapContext);
-            if (boundContext)
-                return boundContext;
-        }
-        if (newWorkspace) {
-            const reusableWorkspace = await this.findReusableWorkspaceByDirectory(projectKey, "checkout");
-            const freshContext = reusableWorkspace
-                ? await this.cloneWorkspaceContext(reusableWorkspace)
-                : await this.openCheckoutWorkspace(path);
-            return this.withConversationContext(freshContext, conversationScopeId, targetKey, bootstrapContext);
-        }
-        const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
-        const context = await this.openOnce(operationKey, async () => {
+        const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "checkout", async (session, root) => session.mode === "checkout" && await canonicalPath(root) === projectKey, bootstrapContext);
+        if (boundContext)
+            return boundContext;
+        const context = await this.openOnce(targetKey, async () => {
             const reusableWorkspace = await this.findReusableWorkspaceByDirectory(projectKey, "checkout");
             if (!reusableWorkspace)
                 return this.openCheckoutWorkspace(path);
-            return conversationScopeId && this.store
-                ? this.cloneWorkspaceContext(reusableWorkspace)
-                : this.reusedWorkspaceContext(reusableWorkspace);
+            return this.reusedWorkspaceContext(reusableWorkspace);
         });
         return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
@@ -361,27 +352,15 @@ export class WorkspaceRegistry {
         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, bootstrapContext);
-                if (boundContext)
-                    return boundContext;
-            }
-            if (input.newWorkspace) {
-                const reusableWorkspace = await this.findReusableWorkspaceByDirectory(worktreeKey, "worktree");
-                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, bootstrapContext);
-            }
-            const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
-            const context = await this.openOnce(operationKey, async () => {
+            const boundContext = await this.boundConversationContext(conversationScopeId, targetKey, "worktree", async (session, root) => session.mode === "worktree" && await canonicalPath(root) === worktreeKey, bootstrapContext);
+            if (boundContext)
+                return boundContext;
+            const context = await this.openOnce(targetKey, async () => {
                 const reusableWorkspace = await this.findReusableWorkspaceByDirectory(worktreeKey, "worktree");
                 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 conversationScopeId && this.store
-                    ? this.cloneWorkspaceContext(reusableWorkspace)
-                    : this.reusedWorkspaceContext(reusableWorkspace);
+                return this.reusedWorkspaceContext(reusableWorkspace);
             });
             return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
         }
@@ -396,29 +375,17 @@ export class WorkspaceRegistry {
             const context = await this.openWorktreeWorkspace(path, input.baseRef);
             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, bootstrapContext);
-            if (boundContext)
-                return boundContext;
-        }
-        if (input.newWorkspace) {
-            const reusableWorkspace = await this.findReusableWorktreeBySource(sourceKey, resolvedBase.targetBranch);
-            const freshContext = reusableWorkspace
-                ? await this.cloneWorkspaceContext(reusableWorkspace)
-                : await this.openWorktreeWorkspace(path, input.baseRef);
-            return this.withConversationContext(freshContext, conversationScopeId, targetKey, bootstrapContext);
-        }
-        const operationKey = this.conversationOpenKey(targetKey, conversationScopeId);
-        const context = await this.openOnce(operationKey, async () => {
+        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, bootstrapContext);
+        if (boundContext)
+            return boundContext;
+        const context = await this.openOnce(targetKey, async () => {
             const reusableWorkspace = await this.findReusableWorktreeBySource(sourceKey, resolvedBase.targetBranch);
             if (!reusableWorkspace)
                 return this.openWorktreeWorkspace(path, input.baseRef);
-            return conversationScopeId && this.store
-                ? this.cloneWorkspaceContext(reusableWorkspace)
-                : this.reusedWorkspaceContext(reusableWorkspace);
+            return this.reusedWorkspaceContext(reusableWorkspace);
         });
         return this.withConversationContext(context, conversationScopeId, targetKey, bootstrapContext);
     }
@@ -453,11 +420,6 @@ export class WorkspaceRegistry {
         }
         return keys;
     }
-    conversationOpenKey(targetKey, conversationScopeId) {
-        return conversationScopeId && this.store
-            ? JSON.stringify(["conversation", conversationScopeId, targetKey])
-            : targetKey;
-    }
     async boundConversationContext(conversationScopeId, targetKey, mode, matches, bootstrapContext) {
         if (!conversationScopeId || !this.store)
             return undefined;
@@ -550,10 +512,41 @@ export class WorkspaceRegistry {
                 worktreeAnchors.get(resolve(session.root))?.id === session.id) {
                 continue;
             }
-            this.store.deleteSession(session.id);
             this.workspaces.delete(session.id);
         }
     }
+    foldLegacyWorkspaceSessions() {
+        if (!this.store)
+            return;
+        const groups = new Map();
+        for (const session of this.store.listSessions()) {
+            const targetPath = canonicalPersistedWorkspacePath(session.root);
+            const key = JSON.stringify([session.mode, targetPath]);
+            const group = groups.get(key) ?? [];
+            group.push(session);
+            groups.set(key, group);
+        }
+        for (const sessions of groups.values()) {
+            if (sessions.length < 2)
+                continue;
+            const ordered = [...sessions].sort((left, right) => left.createdAt.localeCompare(right.createdAt) || left.id.localeCompare(right.id));
+            const canonical = ordered[0];
+            if (!canonical)
+                continue;
+            const createdAt = ordered.reduce((earliest, session) => session.createdAt < earliest ? session.createdAt : earliest, canonical.createdAt);
+            const lastUsedAt = ordered.reduce((latest, session) => session.lastUsedAt > latest ? session.lastUsedAt : latest, canonical.lastUsedAt);
+            const status = ordered.some((session) => session.status === "active")
+                ? "active"
+                : canonical.status;
+            this.store.foldSessions({
+                canonicalId: canonical.id,
+                aliasIds: ordered.slice(1).map((session) => session.id),
+                createdAt,
+                lastUsedAt,
+                status,
+            });
+        }
+    }
     async findReusableWorkspaceByDirectory(directoryKey, mode) {
         for (const session of this.activeSessions(mode)) {
             const root = await this.validSessionRoot(session);
@@ -623,14 +616,6 @@ export class WorkspaceRegistry {
             throw error;
         }
     }
-    async cloneWorkspaceContext(workspace) {
-        return this.createWorkspaceContext({
-            root: workspace.root,
-            mode: workspace.mode,
-            sourceRoot: workspace.sourceRoot,
-            worktree: workspace.worktree ? { ...workspace.worktree } : undefined,
-        });
-    }
     async reusedWorkspaceContext(workspace) {
         Object.assign(workspace, this.loadSkillsForWorkspace(workspace.root));
         workspace.capabilityGuides = loadCapabilityGuides(this.config);
@@ -1036,6 +1021,25 @@ function bootstrapContextFingerprint(workspace, agentsFiles, availableAgentsFile
     };
     return createHash("sha256").update(JSON.stringify(payload)).digest("hex");
 }
+function canonicalPersistedWorkspacePath(path) {
+    const missingSegments = [];
+    let candidate = path;
+    while (true) {
+        try {
+            return resolve(realpathSync(candidate), ...missingSegments.slice().reverse());
+        }
+        catch (error) {
+            if (!isErrnoException(error) || (error.code !== "ENOENT" && error.code !== "ENOTDIR")) {
+                return resolve(path);
+            }
+            const parent = dirname(candidate);
+            if (parent === candidate)
+                return resolve(path);
+            missingSegments.push(basename(candidate));
+            candidate = parent;
+        }
+    }
+}
 async function canonicalPath(path) {
     const missingSegments = [];
     let candidate = path;

package/docs/chatgpt-coding-workflow.md

@@ -9,14 +9,17 @@ checkout.
 `open_workspace` returns a `workspaceId`. Continue using that ID for later tools
 in the same directory.
 
-`workspaceId` is a logical conversation handle, not the physical-directory
-identity. Reopening the same checkout in the same conversation keeps that
-logical ID stable. A different conversation normally receives a different
-`workspaceId` even when it points at the same checkout or worktree; pass an
-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.
+`workspaceId` identifies a persistent ForgeRelay Workspace rather than a
+conversation-scoped handle. A canonical checkout path maps to one checkout
+Workspace, and a managed worktree path maps to one managed-worktree Workspace.
+Different Host conversations may bind to and reuse the same `workspaceId`; pass a
+known ID explicitly when the user wants to resume that Workspace. Historical
+duplicate IDs created by older ForgeRelay versions are accepted during migration
+and resolve to the canonical Workspace identity.
+
+A Git worktree directory is a separate physical Workspace target from its source
+checkout. Separate parallel identities require separate managed worktrees rather
+than multiple logical handles pointing at one physical target.
 
 ### Bootstrap context and workspace inventory
 
@@ -28,12 +31,11 @@ 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.
+Workspace target and a content fingerprint, independently from persistent
+Workspace identity. Different conversations may reuse the same `workspaceId` while
+each receives the current bootstrap once. 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:
 
@@ -42,15 +44,14 @@ open_workspace(workspaceId="ws_...", context="full")
 open_workspace(workspaceId="ws_...", context="none")
 ```
 
-`full` forces a bootstrap refresh. `none` opens/resumes the workspace without
+`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.
+already delivered. Context-delivery state remains conversation-scoped and does not
+change the persistent Workspace identity.
 
-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:
+Do not enumerate Workspace state on every normal open. When the user wants to
+continue earlier work, inspect known Workspaces, or clean up accumulated state, use
+the same Core tool in inventory mode:
 
 ```text
 open_workspace(action="list")
@@ -62,7 +63,7 @@ Inventory is paginated, defaults to 50 entries, and caps each page at 100. It ca
 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
+root validity, and whether that 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
@@ -278,18 +279,20 @@ surface, including direct `rename`/`delete` path mutations alongside `apply_patc
 unified move/rename primitive for both files and directories; ForgeRelay does not
 expose a separate `move` tool.
 
-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. 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.
+Workspace IDs are persistent ForgeRelay identities. The same canonical checkout
+or managed worktree is reused across conversations; older duplicate IDs remain
+compatibility aliases that resolve to the canonical Workspace. `newWorkspace` is
+deprecated and no longer allocates a second identity for the same physical target;
+use `newWorktree=true` when genuinely separate Git isolation is required. The
+normal open path may still include `staleWorkspaces` for an idle persistent
+Workspace; use `open_workspace(action="list")` for complete, filtered inventory
+when continuation or cleanup actually requires it.
+
+In v0.8.0, `close_workspace` is still the existing public close operation:
+checkout-backed Workspaces remove their ForgeRelay record without deleting project
+files, while managed-worktree-backed Workspaces require `commitMessage` and run the
+safe commit / fast-forward-only integration / cleanup lifecycle. Persistent
+closed/reopen semantics land in the following lifecycle stage.
 
 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

@@ -286,24 +286,27 @@ is no separate `move` MCP tool.
 Codex-mode commands run without a PTY by default. `tty: true` enables interactive
 programs when the optional `node-pty` dependency is available.
 
-Logical workspace IDs are conversation-scoped handles. Reopening the same project
-from the same conversation keeps its ID stable; a different conversation normally
-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.
-
-Bootstrap delivery is tracked separately from the selected logical workspace.
+Workspace IDs identify persistent ForgeRelay Workspaces rather than individual
+conversation handles. A canonical checkout path maps to one checkout Workspace, and
+a managed worktree path maps to one managed-worktree Workspace; different Host
+conversations can bind to and reuse the same `workspaceId`. Pass `workspaceId` to
+`open_workspace` to resume that known Workspace explicitly. Historical duplicate
+IDs created by older ForgeRelay versions remain accepted during migration and
+resolve to the canonical Workspace. `newWorkspace: true` is retained only as a
+deprecated compatibility input and no longer allocates another identity for the
+same physical target; use `newWorktree: true` for genuinely separate Git isolation.
+
+Bootstrap delivery is tracked separately from Workspace identity.
 `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.
+`context="none"` opens or resumes the Workspace without returning the full bootstrap
+and does not mark the current fingerprint as delivered. Conversation-scoped
+bootstrap delivery therefore remains independent from the persistent Workspace
+identity: another conversation may reuse the same Workspace while independently
+receiving the current bootstrap once, and changed context produces a new fingerprint
+for the next `auto` open.
 
 Composite Workspaces use the same `open_workspace` entry point with
 `kind="composite"` and a human-readable `name`. They have no filesystem root of
@@ -324,20 +327,21 @@ Hooks, Skills, language services, and Activity facts remain owned by the underly
 Workspace. The Composite Activity Panel only aggregates their presentation into one
 Host Turn.
 
-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
+Use `open_workspace(action="list")` only when the Agent needs to inspect known
+Workspaces, continue earlier work, 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.
+`status="active"` while appearing as `state="invalid"`. Canonical identity means
+ordinary same-target opens no longer accumulate duplicate inventory rows;
+`action="list"` remains 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
+In v0.8.0, `close_workspace` still removes a checkout-backed Workspace record without
+deleting checkout files; the persistent closed/reopen lifecycle is introduced by
+the next lifecycle stage. 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.
 For a Composite Workspace, the same tool means dissolve: it removes only the
@@ -366,7 +370,7 @@ the initial run request terminates a not-yet-handed-off process so ForgeRelay do
 not leave an orphan process whose `processId` the Agent never received.
 
 Completed background processes are delivered once with a later tool result for the
-same logical workspace ID. Full buffered completion output is retained for five
+same Workspace ID. Full buffered completion output is retained for five
 minutes; after that ForgeRelay compacts the completion to a bounded head/tail record
 and keeps it deliverable for up to 24 hours, still subject to the global completed
 process count bound. Completed processes no longer prevent `close_workspace`; the

package/docs/roadmap.md

@@ -284,6 +284,34 @@ Git state, processes, Hooks, Skills, Language services, Activity, and Audit fact
 Workspace Relay is not file synchronization or failover, and Composite Workspace
 never silently chooses a member.
 
+## 0.8 — Persistent Workspace lifecycle and Task Lists
+
+0.8 turns Workspace identity from a disposable logical handle into a persistent
+ForgeRelay work boundary, then layers lightweight Workspace-owned Task Lists and
+safe cross-Workspace inspection on top. Development is release-gated: each stage
+must be published successfully before work begins on the next stage.
+
+- **0.8.0** — fix Composite bootstrap correctness and establish one canonical,
+  persistent Workspace identity per physical checkout/worktree target, including
+  migration compatibility for legacy aliases;
+- **0.8.1** — make checkout close non-destructive and reversible, add explicit
+  Workspace deletion, and prevent GC from deleting persistent Workspace identity;
+- **0.8.2** — carry the persistent lifecycle through managed worktrees and Composite
+  Workspaces, preserving state across close/reopen while keeping safe worktree
+  finalize semantics;
+- **0.8.3** — add versioned file-backed Task Lists in ForgeRelay-owned Workspace
+  state, with mutations scoped to the current Workspace;
+- **0.8.4** — add progressive Task disclosure, forgotten-update reminders, and
+  allowlist-based read-only inspection of other Workspaces and their safe Task
+  projections;
+- **0.8.5** — verify the complete contract across Workspace Relay and publish the
+  accepted 0.8 lifecycle/Task model.
+
+The release boundary is part of the dependency graph, not just a documentation
+milestone: the next stage remains blocked until the previous version's tag-triggered
+release workflow has completed successfully. Runtime acceptance uses only the
+reserved 7677/7678 debug instances and never touches the normal 7676 installation.
+
 ## Later: first-class subagent MCP
 
 ForgeRelay already owns provider adapters and resumable local agent sessions. A
@@ -311,20 +339,20 @@ are ready:
 Checkpoint restore must protect concurrent/external user edits rather than
 blindly overwriting a working tree.
 
-## Later: task orchestration
+## Workspace Task Lists
 
-After first-class subagents are stable, ForgeRelay may add a small persistent
-task graph for parent/worker coordination:
+ForgeRelay may provide persistent, lightweight Task Lists owned by a Workspace for
+work that should survive Host Turns, conversation changes, and Workspace close.
+Task is a checklist/continuation primitive rather than an execution scheduler:
 
-- task identity/title/status;
-- dependencies;
-- assigned local-agent session;
-- workspace/worktree association;
-- structured result/error state.
+- one Workspace may own multiple named Task Lists;
+- a Task records a work requirement, lightweight progress state, and Agent-managed continuation text;
+- Task does not imply a Queue, Goal object, dependency graph, Subagent assignment, Run binding, or autonomous execution policy;
+- current-Workspace Task state may be mutated through a Capability, while information about another Workspace, including Task projections, is exposed only through the read-only Workspace inspection path;
+- Task state is durable Workspace-owned local state and is not deleted by ordinary Workspace close or GC.
 
-Start with DAG-style parent/child orchestration. Peer-to-peer agent-team messaging
-should only be added if real workflows demonstrate that the simpler task model is
-insufficient.
+Subagent coordination can reference Task content when useful, but ForgeRelay does
+not bind Tasks to Subagent Sessions or infer Task completion from execution facts.
 
 ## Compatibility policy
 

package/docs/security.md

@@ -144,10 +144,10 @@ process lifetime. When `bash` is still running after that window, ForgeRelay
 returns a canonical `processId` and leaves the process alive. Regular tool modes
 reuse `bash(action="process")` to poll, wait, write input, resize a PTY, or
 explicitly interrupt that process. An asynchronously completed process
-is reported on a later tool result for the same logical workspace ID, including
-error-result paths, and is never broadcast to another workspace ID. Explicitly
-resuming the same workspace ID in another conversation intentionally transfers
-that completion scope as well. Hook handlers keep their separate bounded timeout
+is reported on a later tool result for the same persistent Workspace ID, including
+error-result paths, and is never broadcast to another Workspace ID. Reusing that
+Workspace from another conversation intentionally shares the same completion scope
+as well. Hook handlers keep their separate bounded timeout
 policy because they are lifecycle gates rather than user-command execution.
 
 ## Lifecycle hooks

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akira-tl/forgerelay",
-  "version": "0.7.2",
+  "version": "0.8.0",
   "description": "Local development control plane for MCP coding agents.",
   "type": "module",
   "homepage": "https://github.com/Akira-TL/forgerelay#readme",
@@ -47,7 +47,7 @@
     "release:publish": "node scripts/release/publish.mjs",
     "postinstall": "node scripts/fix-node-pty-permissions.mjs",
     "start": "node dist/cli.js serve",
-    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/release-version.test.mjs && tsx src/oauth/router.test.ts && tsx src/remote-auth-cli.test.ts && tsx src/remote-ssh-auth-cli.test.ts && tsx src/remote-workspace-relay.test.ts && tsx src/remote-workspace-relay-process.test.ts && tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.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/workspace-lifecycle-app.test.ts && tsx src/ui/activity/model.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/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/operations/edit-preflight.test.ts && tsx src/skills.test.ts && tsx src/db/migrations.test.ts && tsx src/workspace-store.test.ts && tsx src/activity/audit-store.test.ts && tsx src/activity/bash-output-store.test.ts && tsx src/activity/lifecycle.test.ts && tsx src/activity/query-service.test.ts && tsx src/operations/core-operation-executor.test.ts && tsx src/operations/bulk-mutation.test.ts && tsx src/operations/batch/scheduler.test.ts && tsx src/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
+    "test": "node --test scripts/debug/runtime.test.mjs scripts/release-proof.test.mjs scripts/release/release-gate.test.mjs scripts/release/release-version.test.mjs && tsx src/oauth/router.test.ts && tsx src/remote-auth-cli.test.ts && tsx src/remote-ssh-auth-cli.test.ts && tsx src/remote-workspace-relay.test.ts && tsx src/remote-workspace-relay-process.test.ts && tsx src/config.test.ts && tsx src/lsp/language-server-config.test.ts && tsx src/lsp/normalization/hover.test.ts && tsx src/lsp/references.server.test.ts && tsx src/lsp/operations/document-symbols.server.test.ts && tsx src/lsp/operations/workspace-symbols.server.test.ts && tsx src/lsp/operations/diagnostics-push.server.test.ts && tsx src/lsp/operations/diagnostics-pull.server.test.ts && tsx src/lsp/operations/request-hardening.server.test.ts && tsx src/lsp/operations/recovery.server.test.ts && tsx src/lsp/operations/lifecycle.server.test.ts && tsx src/lsp/runtime/semantic-requests.test.ts && tsx src/logger.test.ts && tsx src/proxy-trust.test.ts && tsx src/mcp-app-template.test.ts && tsx src/hooks.test.ts && tsx src/capability-registry.test.ts && tsx src/mcp/server-instructions.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/workspace-lifecycle-app.test.ts && tsx src/ui/activity/model.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/subagents/providers/adapters/codex.test.ts && tsx src/subagents/providers/registry.test.ts && tsx src/subagents/providers/availability.test.ts && tsx src/subagents/profiles.test.ts && tsx src/subagents/cli-target.test.ts && tsx src/subagents/sessions/store.test.ts && tsx src/subagents/sessions/manager.test.ts && tsx src/subagents/sessions/mcp/capability.server.test.ts && tsx src/subagents/sessions/mcp/continuation.server.test.ts && tsx src/subagents/sessions/mcp/lifecycle.server.test.ts && tsx src/subagents/sessions/mcp/reconciliation.server.test.ts && tsx src/subagents/sessions/mcp/routing.server.test.ts && tsx src/roots.test.ts && tsx src/file-mutations.test.ts && tsx src/operations/edit-preflight.test.ts && tsx src/skills.test.ts && tsx src/db/migrations.test.ts && tsx src/workspace-store.test.ts && tsx src/activity/audit-store.test.ts && tsx src/activity/bash-output-store.test.ts && tsx src/activity/lifecycle.test.ts && tsx src/activity/query-service.test.ts && tsx src/operations/core-operation-executor.test.ts && tsx src/operations/bulk-mutation.test.ts && tsx src/operations/batch/scheduler.test.ts && tsx src/operations/batch/executor-policy.test.ts && tsx src/workspaces.test.ts && tsx src/workspace-conversation.test.ts && tsx src/review-checkpoints.test.ts && tsx src/lsp/code-intelligence.server.test.ts && npm run build:app && tsx src/server.test.ts && tsx src/oauth-store.test.ts && tsx src/cli.test.ts",
     "typecheck": "tsc -p tsconfig.json --noEmit",
     "release:check": "node scripts/release-version.mjs check",
     "release:tag-check": "node scripts/release-version.mjs tag",