@deepseek-ai/dsh-workspace 0.1.5-rc.2 → 0.1.6-alpha.1

package/README.i18n.yaml

@@ -2,5 +2,5 @@
 # side as of the last confirmed-consistent state. Both languages carry equal authority;
 # after editing either side, bring the other along and re-record with:
 #   pnpm run verify-translation-pairing --write packages/workspace/workspace/README.md
-README.md: b5eaac5c68776c927cd464604f8d99d9290d9d54
-README.zh.md: 7d837251a3a20bdacd89a5d8160978a3f1a76b04
+README.md: 8ac3bdbf0a69c031f1ddd5cdadb98f9cc4d55084
+README.zh.md: 225a24cc8fbedafe8e3ae6f64a849525eeb92067

package/README.md

@@ -25,7 +25,7 @@ Use this package to keep an ordered, persistent list of project directories and
 <a id="use-this-package"></a>
 ## Use this package
 
-Use this package to give the product a project list: named directories the user works in, the sessions that ran in each, a stable order, and a way to hide sessions without losing them. The API contracts behind each action live in the implementation section.
+Use this package to give the product a project list: named directories the user works in, the sessions that ran in each, a stable order, and a way to hide sessions without losing them or bring them back. The API contracts behind each action live in the implementation section.
 
 ### When to use it
 
@@ -63,9 +63,9 @@ ctx.workspaceRegistry.list() // shows the project, newest first
 
 A session joins the project of the directory it runs in: create a session in a project's directory and it appears under that project, newest first. A session can only belong to one project. A session whose directory cannot be validated — no recorded directory, or a moved or deleted folder — cannot join and stays ungrouped.
 
-### Hiding sessions and removing projects
+### Hiding and restoring sessions, and removing projects
 
-Hide a session from the grouping when it should stop appearing there: it disappears from the visible list, while its session, history, and place in the project stay intact. Remove a project when it is no longer needed: it leaves the list, and its folder, files, and session histories are never touched — those sessions become ungrouped. Adding the same directory again afterwards starts a fresh project without the old sessions.
+Hide a session from the grouping when it should stop appearing there: it disappears from the visible list, while its session, history, and place in the project stay intact. Restore a hidden session when it should appear again: it returns to its recorded position under its project, or to the ungrouped sessions when it belongs to none. Remove a project when it is no longer needed: it leaves the list, and its folder, files, and session histories are never touched — those sessions become ungrouped. Adding the same directory again afterwards starts a fresh project without the old sessions.
 
 -----
 
@@ -87,7 +87,7 @@ This section explains the design decisions behind the feature and points at the
 
 ### API behavior
 
-The API is one small family with two owners: `WorkspaceRegistry` creates, orders, and deletes projects and manages their session accounting; the `Workspace` entity exposes the display title, directory status, and the session projection. Per-method contracts live in the code, not this README — see [src/index.ts](src/index.ts) and [src/entity.ts](src/entity.ts).
+The API is one small family with two owners: `WorkspaceRegistry` creates, orders, and deletes projects, manages their session accounting, and archives or restores single sessions; the `Workspace` entity exposes the display title, directory status, and the session projection. Per-method contracts live in the code, not this README — see [src/index.ts](src/index.ts) and [src/entity.ts](src/entity.ts).
 
 ### Source map
 
@@ -102,7 +102,7 @@ The API is one small family with two owners: `WorkspaceRegistry` creates, orders
 
 ### Durable shape
 
-The registry opens the `workspace` domain (version 2): a `workspaces` table keyed by `WorkspaceId` plus one global state holding `workspaceIds` (the authoritative display order), `archivedSessionIds`, and the optional `pendingMutation` marker. Records written before `archivedSessionIds` existed parse with an empty set through the schema default.
+The registry opens the `workspace` domain (version 2): a `workspaces` table keyed by `WorkspaceId` plus one global state holding `workspaceIds` (the authoritative display order), `archivedSessionIds`, and the optional `pendingMutation` marker. Records written before `archivedSessionIds` existed parse with an empty set through the schema default. Archiving and unarchiving both rewrite only that global state, so a restore is one filtered write of the same field; unarchive runs no session-existence probe, because dropping an id from the set cannot introduce an unknown one, while archive verifies the session before adding it.
 
 ### Lifecycle
 
@@ -160,7 +160,7 @@ These limits define when the project list is a poor fit or needs special operati
 - **Removal never deletes data** — removing a project leaves its folder, files, and session histories in place; those sessions become ungrouped, and session deletion or folder removal are separate, absent capabilities ([decision](../../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.md)).
 - **A session joins only with a recorded directory** — a session belongs to a project only when its record carries a directory that resolves to the project's path; sessions without one stay ungrouped, and a session from another directory cannot be moved in.
 - **External changes are seen late** — if another process deletes or damages a directory, the project reflects it only at the next refresh or restart.
-- **Archiving is one-way** — a hidden session keeps its history and its place, but no unarchive action exists yet; the archive set is a durable display filter.
+- **Archive and unarchive enforce different session checks** — a restore only drops an id from the archive set, so an entry whose session is gone still unarchives and leaves no unknown referent; a restore of an id that is not archived resolves without writing, while `archiveSession` rejects a session that is neither live nor persisted.
 - **Re-adding a directory starts fresh** — after removal, adding the same directory again creates a new project with an empty session list; the old sessions do not come back automatically.
 
 <a id="dev-note"></a>

package/README.zh.md

@@ -25,7 +25,7 @@ kind: "package-reference"
 <a id="use-this-package"></a>
 ## 使用本包
 
-使用此包为产品提供项目列表：用户工作的命名目录、每个目录中运行的会话、稳定顺序，以及在不丢失会话的前提下将其隐藏的能力。每项操作背后的 API 约定放在实现章节中。
+使用此包为产品提供项目列表：用户工作的命名目录、每个目录中运行的会话、稳定顺序，以及在不丢失会话的前提下将其隐藏或重新取回的能力。每项操作背后的 API 约定放在实现章节中。
 
 ### 何时使用
 
@@ -50,7 +50,7 @@ kind: "package-reference"
 
 ### 创建与排序项目
 
-从任何存在且完整限定的目录创建项目：`C:\` 等文件系统根目录和普通目录都有效。相对路径、`C:work` 等 Windows 盘符相对路径、不存在的路径和文件都会被拒绝，且不会创建项目；为已有项目的目录再次创建会原样返回现有项目。你可以随时重命名项目，并把它移动到列表中的任意位置：
+从任何已存在的绝对目录路径创建项目：`C:\` 等文件系统根目录和普通目录都有效。相对路径、`C:work` 等 Windows 盘符相对路径、不存在的路径和文件都会被拒绝，且不会创建项目；为已有项目的目录再次创建会原样返回现有项目。你可以随时重命名项目，并把它移动到列表中的任意位置：
 
 ```text
 // Host consumer code, after the composition above is loaded:
@@ -63,9 +63,9 @@ ctx.workspaceRegistry.list() // shows the project, newest first
 
 会话加入它运行目录所在的项目：在项目目录中创建会话，它就会出现在该项目下，新到旧排列。一个会话只能属于一个项目。目录无法校验的会话——没有记录目录，或目录被移动、删除——无法加入，保持 Ungrouped。
 
-### 隐藏会话与移除项目
+### 隐藏、恢复会话与移除项目
 
-当会话不应再出现在分组中时隐藏它：它会从可见列表中消失，但其会话、历史与在项目中的位置都保持不变。项目不再需要时移除它：它离开列表，而其文件夹、文件与会话历史绝不受影响——这些会话变成 Ungrouped。之后再次添加同一目录会从空项目开始，不会带回旧会话。
+当会话不应再出现在分组中时隐藏它：它会从可见列表中消失，但其会话、历史与在项目中的位置都保持不变。当被隐藏的会话应重新出现时恢复它：它会回到其项目下记录的位置；不属于任何项目时则回到 Ungrouped。项目不再需要时移除它：它离开列表，而其文件夹、文件与会话历史绝不受影响——这些会话变成 Ungrouped。之后再次添加同一目录会从空项目开始，不会带回旧会话。
 
 -----
 
@@ -79,15 +79,15 @@ ctx.workspaceRegistry.list() // shows the project, newest first
 
 ### 设计理念
 
-- **每个规范路径一条记录。** `fs.realpath` 是唯一的一套唯一性规范：路径以规范化形式存储，因此指向已被拥有目录的符号链接会与之冲突，唯一性即规范路径的字符串相等。
-- **成员资格是所有权加实时 cwd 事实。** 记录的 `sessionIds` 顺序是所有权真源；启动时的头部索引校验它，`sessionIds` 在读取时过滤，下一次变更持久剪除。
+- **每个规范路径一条记录。** `fs.realpath` 是唯一的一套唯一性规范：路径以规范化形式存储，因此指向已有记录目录的符号链接会与之冲突，唯一性即规范路径的字符串相等。
+- **成员资格是所有权加实时 cwd 事实。** 记录的 `sessionIds` 顺序是所有权真源；启动时的头部索引校验它，`sessionIds` 在读取时过滤，下一次变更会持久化剪除无效项。
 - **仅读取头部。** 引导与 attach 校验只读取 `SessionHeader` 字段；事件正文绝不加载。
 - **两次写入的变更带显式标记。** 创建与删除在记录/顺序对可能分叉之前先持久化 `pendingMutation` 标记，因此启动只补全被中断的操作，未标记的分叉作为损坏明确报错。
-- **串行化写入。** 注册表操作跑在同一条操作链上；实体变更通过领域写链上的 `table.update` 执行，盖上 `updatedAt` 并在其链槽决定成员资格。
+- **串行化写入。** 注册表操作跑在同一条操作链上；实体变更通过领域写链上的 `table.update` 执行，写入 `updatedAt`，并在其所在的链位置决定成员资格。
 
 ### API 行为
 
-该 API 是一个由两个所有者构成的小家族：`WorkspaceRegistry` 负责创建、排序与删除项目并管理其会话记账；`Workspace` 实体暴露显示标题、目录状态与会话投影。各方法的精确约定在代码中，而非本 README——参见 [src/index.ts](src/index.ts) 与 [src/entity.ts](src/entity.ts)。
+该 API 是一个由两个所有者构成的小家族：`WorkspaceRegistry` 负责创建、排序与删除项目、管理其会话记账，以及归档或恢复单个会话；`Workspace` 实体暴露显示标题、目录状态与会话投影。各方法的精确约定在代码中，而非本 README——参见 [src/index.ts](src/index.ts) 与 [src/entity.ts](src/entity.ts)。
 
 ### 源码地图
 
@@ -102,11 +102,11 @@ ctx.workspaceRegistry.list() // shows the project, newest first
 
 ### 持久形态
 
-注册表打开 `workspace` 领域（版本 2）：一张以 `WorkspaceId` 为键的 `workspaces` 表，加上一个持有 `workspaceIds`（权威显示顺序）、`archivedSessionIds` 与可选 `pendingMutation` 标记的全局状态。在 `archivedSessionIds` 存在之前写入的记录会通过 schema 默认值解析为空集合。
+注册表打开 `workspace` 领域（版本 2）：一张以 `WorkspaceId` 为键的 `workspaces` 表，加上一个持有 `workspaceIds`（权威显示顺序）、`archivedSessionIds` 与可选 `pendingMutation` 标记的全局状态。在 `archivedSessionIds` 存在之前写入的记录会通过 schema 默认值解析为空集合。归档与取消归档都只重写该全局状态，因此恢复就是对同一字段的一次过滤写入；取消归档不做会话存在性探测，因为从集合中移除 id 不可能引入未知 id，而归档会在加入前校验会话。
 
 ### 生命周期
 
-启动时，注册表打开领域、若存在标记则补全被标记的变更、校验已存状态——重复路径、重复会话账本与顺序漂移都会明确报错——并在尚未初始化时先凭持久化头部引导历史、最后写入已初始化标记，因此被中断的引导可以安全恢复。全新空注册表一旦初始化即为真，绝不会再次引导。
+启动时，注册表打开领域、若存在标记则补全被标记的变更、校验已存状态——重复路径、重复会话记账与顺序漂移都会明确报错——并在尚未初始化时先凭持久化头部引导历史、最后写入已初始化标记，因此被中断的引导可以安全恢复。全新空注册表一旦初始化即成为正式状态，绝不会再次引导。
 
 ### 失败与恢复
 
@@ -136,7 +136,7 @@ ctx.workspaceRegistry.list() // shows the project, newest first
 <a id="model-experience"></a>
 ## 模型体验
 
-### Workspace 记录与会话账本
+### Workspace 记录与会话记账
 
 #### 模型看到什么
 
@@ -160,7 +160,7 @@ ctx.workspaceRegistry.list() // shows the project, newest first
 - **移除绝不删除数据**——移除项目会保留其文件夹、文件与会话历史；这些会话变成 Ungrouped，而会话删除与文件夹移除是彼此独立且尚未提供的功能（参见[决策记录](../../../.agents/notes/implemented/feature/2026-07-27-workspace-registration-deletion.zh.md)）。
 - **只有带记录目录的会话才能加入**——只有记录中带有可解析为项目路径的目录的会话才属于项目；没有目录的会话保持 Ungrouped，来自其他目录的会话无法移入。
 - **外部变更延迟可见**——如果另一进程删除或损坏目录，项目只能在下次刷新或重启后反映出来。
-- **归档是单向的**——被隐藏的会话保留其历史与位置，但目前没有取消归档操作；归档集合是持久的显示过滤器。
+- **归档与取消归档执行不同的会话校验**——恢复只是从归档集合中移除 id，因此会话已不存在的条目仍能取消归档，也不会留下未知引用；对未归档 id 执行恢复不写盘即完成，而 `archiveSession` 会拒绝既非实时也未持久化的会话。
 - **重新添加目录从空开始**——移除后再次添加同一目录会创建空会话列表的新项目；旧会话不会自动回来。
 
 <a id="dev-note"></a>

package/lib/index.js

@@ -455,6 +455,26 @@ var WorkspaceRegistry = class extends Service {
 		});
 	}
 	/**
+	* Unarchive one session durably by dropping it from the registry-global
+	* archive set; the accounting slot was never touched, so the session
+	* returns to its recorded position. Unarchiving runs no session-existence
+	* check because removing an id cannot introduce an unknown one, so an
+	* entry whose session is gone still resolves. An id that is not archived
+	* resolves without writing.
+	* @param sessionId - The session to unarchive.
+	* @returns resolution after durability.
+	*/
+	unarchiveSession(sessionId) {
+		return this.enqueueOperation(async () => {
+			const state = this.requireState();
+			if (!state.archivedSessionIds.includes(sessionId)) return;
+			await this.setState({
+				...state,
+				archivedSessionIds: state.archivedSessionIds.filter((id) => id !== sessionId)
+			});
+		});
+	}
+	/**
 	* Whether a session is live, header-indexed, or present in a fresh
 	* persistence listing. Only a definite miss returns false — a failing
 	* `sessionPersistence.list()` propagates so storage faults never

package/lib/types/index.d.ts

@@ -122,6 +122,17 @@ export declare class WorkspaceRegistry extends Service {
      * @returns resolution after durability.
      */
     archiveSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Unarchive one session durably by dropping it from the registry-global
+     * archive set; the accounting slot was never touched, so the session
+     * returns to its recorded position. Unarchiving runs no session-existence
+     * check because removing an id cannot introduce an unknown one, so an
+     * entry whose session is gone still resolves. An id that is not archived
+     * resolves without writing.
+     * @param sessionId - The session to unarchive.
+     * @returns resolution after durability.
+     */
+    unarchiveSession(sessionId: SessionId): Promise<void>;
     /**
      * Whether a session is live, header-indexed, or present in a fresh
      * persistence listing. Only a definite miss returns false — a failing

package/lib/types/index.js

@@ -213,6 +213,29 @@ export class WorkspaceRegistry extends Service {
             await this.setState({ ...state, archivedSessionIds: [...state.archivedSessionIds, sessionId] });
         });
     }
+    /**
+     * Unarchive one session durably by dropping it from the registry-global
+     * archive set; the accounting slot was never touched, so the session
+     * returns to its recorded position. Unarchiving runs no session-existence
+     * check because removing an id cannot introduce an unknown one, so an
+     * entry whose session is gone still resolves. An id that is not archived
+     * resolves without writing.
+     * @param sessionId - The session to unarchive.
+     * @returns resolution after durability.
+     */
+    unarchiveSession(sessionId) {
+        return this.enqueueOperation(async () => {
+            // The chain slot serializes against every other registry write, so this
+            // check-then-write pair cannot interleave with a concurrent archive.
+            const state = this.requireState();
+            if (!state.archivedSessionIds.includes(sessionId))
+                return;
+            await this.setState({
+                ...state,
+                archivedSessionIds: state.archivedSessionIds.filter(id => id !== sessionId),
+            });
+        });
+    }
     /**
      * Whether a session is live, header-indexed, or present in a fresh
      * persistence listing. Only a definite miss returns false — a failing

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-workspace",
   "description": "Workspace entity registry (ctx.workspaceRegistry): durable workspace records with validated session attachment over the domain data form for the DeepSeek Harness",
-  "version": "0.1.5-rc.2",
+  "version": "0.1.6-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -37,25 +37,25 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.2",
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-storage": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-storage": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.1"
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-brand": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.1"
   },
   "devDependencies": {
     "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-storage": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.5-rc.2",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.5-rc.2"
+    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-storage": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.6-alpha.1"
   }
 }