@deepseek-ai/dsh-workspace 0.1.6-alpha.2 → 0.1.7-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: 8ac3bdbf0a69c031f1ddd5cdadb98f9cc4d55084
-README.zh.md: 225a24cc8fbedafe8e3ae6f64a849525eeb92067
+README.md: 59b314a7302c5cf83314d08f6e8bdfe2dccba37f
+README.zh.md: 78d563ee59048d5b1b6f976ac26f64907174645d

package/README.md

@@ -33,7 +33,7 @@ Use it when the product shows a persistent workspace surface — a sidebar, sess
 
 ### Setting up
 
-The package takes no configuration of its own; it needs a session store, a session persistence backend, and the storage rows that keep its records. A minimal composition:
+The package needs a session store, a session persistence backend, and the storage rows that keep its records. A minimal composition:
 
 ```yaml
 - name: '@deepseek-ai/dsh-session'
@@ -59,13 +59,22 @@ await project.setTitle('Renamed')
 ctx.workspaceRegistry.list() // shows the project, newest first
 ```
 
+<a id="first-use-workspace"></a>
+### First-use Workspace
+
+`initializeDefault(resolveDirectory)` initializes the default Workspace without creating a Session. Initial creation requires an empty Workspace registry and no live, persisted, or archived Session, including Sessions without a working directory. The registry checks persistent history directly; an empty visible sidebar is insufficient.
+
+The directory resolver runs inside the mutation queue only when creation is eligible. It returns an absolute path and initial title; the registry creates missing parent directories, canonicalizes the path, rechecks Session history, and commits the Workspace with its initialization marker. An existing directory is reused; a file conflict or directory failure rejects initialization. The [Host controller](../../api/workspace-controller/README.md#first-use-workspace) supplies the Documents path policy.
+
+The first successful registration records its identity durably. Repeated calls return it without resolving a directory again; renaming keeps that identity, and deleting its registration does not permit another automatic creation. Directory or registration failure leaves initialization unset for retry. Directories created before a later failure remain on disk. Once directory resolution succeeds, caller cancellation does not roll back directory creation or registration. The [first-use decision](../../../.agents/notes/implemented/feature/2026-09-20-default-workspace.md) explains this lifetime.
+
 ### Grouping sessions under a project
 
 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 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. 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.
+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. A session with running work — its own turn, a running subagent, a background job, or an active reminder — is not hidden underneath that work: the registry refuses with the list of what runs, and a caller that asks to stop the work first has it stopped the way the user's own stop actions do, then hidden. 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, and continues the conversation from a regularly ended log. 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 +96,9 @@ 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, 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).
+The API has two owners: `WorkspaceRegistry` creates, orders, and deletes projects, manages their Session accounting, and pins, unpins, archives, or restores Sessions; the `Workspace` entity exposes the display title, directory status, and Session projection. Pinning requires a known, unarchived Session; archiving clears its pin in the same durable write, and restoring does not restore that pin. Per-method contracts live in [src/index.ts](src/index.ts) and [src/entity.ts](src/entity.ts).
+
+Archive admission is a capability seam over two Host events this package declares and dispatches: `workspace/session-activity` (waterfall) asks the composed providers what still runs for a Session, and `workspace/session-stop` (parallel) asks them to stop it. `archiveSession(sessionId)` asks the activity waterfall once and rejects a non-empty answer with `WorkspaceActiveSessionError`, whose `activity` lists each family with its items — the keys are the providers' own, merged into `SessionActivityKindMap`, which this package leaves empty; `archiveSession(sessionId, { stopActivity: true })` skips the activity check, writes the archive, and then dispatches the stop event, so the durable archive set already gates every wake the stops induce; a rejecting provider is logged and the archive stays. The call resolves once every provider's stop request was issued, while the stopped work settles on its own. Both questions come after the existence check and never for an already archived id. The shipped providers are the Agent registry (the running turn), the job registry seam (owned jobs), the Subagent runtime (running descendants), and the Schedule plugin (active reminders); a composition without providers archives freely.
 
 ### Source map
 
@@ -102,7 +113,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. 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.
+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`, `pinnedSessionIds`, the optional `defaultWorkspaceId` first-use identity, and the optional `pendingMutation` marker. Archive and pin sets contain Session id strings, default to empty, and carry no per-entry objects or timestamps; the pin array keeps the most recently pinned id first. Archiving clears the pin in the same global-state write without changing Workspace membership. 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
 
@@ -161,6 +172,7 @@ These limits define when the project list is a poor fit or needs special operati
 - **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.
 - **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.
+- **The activity check and the archive write are not one atomic step** — a turn that starts between the providers' answer and the durable write is hidden while running, and every model step whose `agent/pre-step` precedes the write still runs with its tool calls; the API Session Controller's gate ends the first step proposed after the write as `blocked`, so the exposure is bounded by that write's latency, in practice one model step.
 - **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

@@ -33,7 +33,7 @@ kind: "package-reference"
 
 ### 设置
 
-此包本身不声明任何配置；它需要会话存储、会话持久化后端，以及保存其记录的存储行。最小组合如下：
+此包需要会话存储、会话持久化后端，以及保存其记录的存储行。最小组合如下：
 
 ```yaml
 - name: '@deepseek-ai/dsh-session'
@@ -59,13 +59,22 @@ await project.setTitle('Renamed')
 ctx.workspaceRegistry.list() // shows the project, newest first
 ```
 
+<a id="first-use-workspace"></a>
+### 首次使用工作区
+
+`initializeDefault(resolveDirectory)` 初始化默认 Workspace，不创建 Session。首次创建要求 Workspace 注册表为空，且不存在运行时、持久化或已归档 Session，包括没有工作目录的 Session。注册表直接检查持久化历史；仅凭可见侧边栏为空不足以判断。
+
+目录解析器仅在允许创建时于变更队列内运行。它返回绝对路径和初始标题；注册表创建缺失的父目录、规范化路径、重新检查 Session 历史，再一起提交 Workspace 和初始化标记。已存在的目录直接复用；文件冲突或目录操作失败时拒绝初始化。[Host 控制器](../../api/workspace-controller/README.zh.md#first-use-workspace)提供 Documents 路径策略。
+
+首次成功登记会持久保存工作区身份。重复调用直接返回它，不再解析目录；改名保留该身份，删除登记也不会允许再次自动创建。目录或登记失败时，初始化状态保持未设置，可以重试。后续步骤失败前已创建的目录会保留在磁盘上。目录解析成功后，调用方取消操作不会回滚目录创建或登记。[首次使用决策](../../../.agents/notes/implemented/feature/2026-09-20-default-workspace.zh.md)说明这一生命周期。
+
 ### 将会话归入项目
 
 会话加入它运行目录所在的项目：在项目目录中创建会话，它就会出现在该项目下，新到旧排列。一个会话只能属于一个项目。目录无法校验的会话——没有记录目录，或目录被移动、删除——无法加入，保持 Ungrouped。
 
 ### 隐藏、恢复会话与移除项目
 
-当会话不应再出现在分组中时隐藏它：它会从可见列表中消失，但其会话、历史与在项目中的位置都保持不变。当被隐藏的会话应重新出现时恢复它：它会回到其项目下记录的位置；不属于任何项目时则回到 Ungrouped。项目不再需要时移除它：它离开列表，而其文件夹、文件与会话历史绝不受影响——这些会话变成 Ungrouped。之后再次添加同一目录会从空项目开始，不会带回旧会话。
+当会话不应再出现在分组中时隐藏它：它会从可见列表中消失，但其会话、历史与在项目中的位置都保持不变。仍有工作在跑的会话——它自己的回合、运行中的子代理、后台任务或活跃提醒——不会被藏在这些工作之下：注册表会拒绝并列出还在跑的内容；调用方若要求先停止这些工作，注册表会按用户自己的停止操作同样的方式停掉它们，然后再隐藏。当被隐藏的会话应重新出现时恢复它：它会回到其项目下记录的位置；不属于任何项目时则回到 Ungrouped，并从一份正常收尾的日志继续对话。项目不再需要时移除它：它离开列表，而其文件夹、文件与会话历史绝不受影响——这些会话变成 Ungrouped。之后再次添加同一目录会从空项目开始，不会带回旧会话。
 
 -----
 
@@ -85,9 +94,12 @@ ctx.workspaceRegistry.list() // shows the project, newest first
 - **两次写入的变更带显式标记。** 创建与删除在记录/顺序对可能分叉之前先持久化 `pendingMutation` 标记，因此启动只补全被中断的操作，未标记的分叉作为损坏明确报错。
 - **串行化写入。** 注册表操作跑在同一条操作链上；实体变更通过领域写链上的 `table.update` 执行，写入 `updatedAt`，并在其所在的链位置决定成员资格。
 
+<a id="api-behavior"></a>
 ### API 行为
 
-该 API 是一个由两个所有者构成的小家族：`WorkspaceRegistry` 负责创建、排序与删除项目、管理其会话记账，以及归档或恢复单个会话；`Workspace` 实体暴露显示标题、目录状态与会话投影。各方法的精确约定在代码中，而非本 README——参见 [src/index.ts](src/index.ts) 与 [src/entity.ts](src/entity.ts)。
+该 API 由两个对象负责：`WorkspaceRegistry` 创建、排序与删除项目，管理会话记账，并置顶、取消置顶、归档或恢复会话；`Workspace` 实体暴露显示标题、目录状态与会话投影。置顶要求会话已知且未归档；归档在同一次持久化写入中清除置顶，恢复会话不会恢复置顶。各方法的精确约定见 [src/index.ts](src/index.ts) 与 [src/entity.ts](src/entity.ts)。
+
+归档准入是本包声明并派发的两个宿主事件之上的能力接缝：`workspace/session-activity`（waterfall）向已组合的提供方询问某会话还有什么在跑，`workspace/session-stop`（parallel）请它们停止这些工作。`archiveSession(sessionId)` 只询问一次活动 waterfall，对非空答案以 `WorkspaceActiveSessionError` 拒绝，其 `activity` 按族列出各项——键由各提供方自己合并进本包留空的 `SessionActivityKindMap`；`archiveSession(sessionId, { stopActivity: true })` 跳过活动检查，先写入归档，再派发停止事件，因此持久化的归档集合已经拦住停止所引发的每一次唤醒；提供方抛错只记日志，归档保留。调用在每个提供方的停止请求都已发出后返回，被停止的工作自行收敛。两种询问都在存在性检查之后进行，对已归档 id 从不发生。随附的提供方是 Agent 注册表（运行中的回合）、任务注册表接缝（所属任务）、Subagent runtime（运行中的子孙）与 Schedule 插件（活跃提醒）；没有提供方的组合可自由归档。
 
 ### 源码地图
 
@@ -102,7 +114,7 @@ ctx.workspaceRegistry.list() // shows the project, newest first
 
 ### 持久形态
 
-注册表打开 `workspace` 领域（版本 2）：一张以 `WorkspaceId` 为键的 `workspaces` 表，加上一个持有 `workspaceIds`（权威显示顺序）、`archivedSessionIds` 与可选 `pendingMutation` 标记的全局状态。在 `archivedSessionIds` 存在之前写入的记录会通过 schema 默认值解析为空集合。归档与取消归档都只重写该全局状态，因此恢复就是对同一字段的一次过滤写入；取消归档不做会话存在性探测，因为从集合中移除 id 不可能引入未知 id，而归档会在加入前校验会话。
+注册表打开 `workspace` 领域（版本 2）：一张以 `WorkspaceId` 为键的 `workspaces` 表，加上一个持有 `workspaceIds`（权威显示顺序）、`archivedSessionIds`、`pinnedSessionIds`、可选的首次使用身份 `defaultWorkspaceId` 与可选 `pendingMutation` 标记的全局状态。归档与置顶集合存储会话 id 字符串，默认值为空，不包含逐项对象或时间戳；置顶数组把最近置顶的 id 放在前面。归档在同一次全局状态写入中清除置顶，但不改变 Workspace 成员关系。取消归档不做会话存在性探测，因为从集合中移除 id 不可能引入未知 id，而归档会在加入前校验会话。
 
 ### 生命周期
 
@@ -161,6 +173,7 @@ ctx.workspaceRegistry.list() // shows the project, newest first
 - **只有带记录目录的会话才能加入**——只有记录中带有可解析为项目路径的目录的会话才属于项目；没有目录的会话保持 Ungrouped，来自其他目录的会话无法移入。
 - **外部变更延迟可见**——如果另一进程删除或损坏目录，项目只能在下次刷新或重启后反映出来。
 - **归档与取消归档执行不同的会话校验**——恢复只是从归档集合中移除 id，因此会话已不存在的条目仍能取消归档，也不会留下未知引用；对未归档 id 执行恢复不写盘即完成，而 `archiveSession` 会拒绝既非实时也未持久化的会话。
+- **活动检查与归档写入不是一个原子步骤**——在提供方作答与持久化写入之间开始的回合会在隐藏状态下运行，`agent/pre-step` 先于该写入的每个模型步连同其工具调用照常执行；API Session Controller 的门禁把写入之后提出的第一步以 `blocked` 收口，因此暴露面以该写入的时延为界，实际上是一个模型步。
 - **重新添加目录从空开始**——移除后再次添加同一目录会创建空会话列表的新项目；旧会话不会自动回来。
 
 <a id="dev-note"></a>

package/lib/index.js

@@ -1,5 +1,5 @@
 import { randomUUID } from "node:crypto";
-import { realpath, stat } from "node:fs/promises";
+import { mkdir, realpath, stat } from "node:fs/promises";
 import { Service } from "@deepseek-ai/cordis";
 import { posix, win32 } from "node:path";
 import { z } from "zod";
@@ -200,6 +200,7 @@ var WorkspaceEntity = class {
 */
 /** Workspace id schema at the durable boundary; branding has no runtime representation. */
 const workspaceId = z.string().transform((value) => value);
+const sessionId = z.string().transform((value) => brandString(value));
 /**
 * Durable shape of one workspace record. `path` is the `fs.realpath` canon
 * stamped at create; `sessionIds` is the ordered ownership account (array
@@ -208,7 +209,7 @@ const workspaceId = z.string().transform((value) => value);
 const workspaceRecord = z.object({
 	path: z.string(),
 	title: z.string(),
-	sessionIds: z.array(z.string().transform((value) => brandString(value))),
+	sessionIds: z.array(sessionId),
 	createdAt: z.string(),
 	updatedAt: z.string()
 });
@@ -231,12 +232,18 @@ const workspacePendingMutation = z.discriminatedUnion("operation", [z.object({
 * the registry-global archive set layered over workspace accounting: an
 * archived session keeps its `sessionIds` slot (unarchiving must restore the
 * position), so the set never participates in the one-owner accounting
-* invariant. Defaulted so records written before the field parse unchanged.
+* invariant. `pinnedSessionIds` is the registry-global pin set in pin order
+* (most recently pinned first); pinning and archival are mutually
+* exclusive, so archiving drops the session's pin. Both session sets are
+* defaulted so records written before the fields parse unchanged.
 */
 const workspaceDomainState = z.object({
 	initialized: z.boolean(),
+	/** First-use Workspace identity, retained after its registration is deleted. */
+	defaultWorkspaceId: workspaceId.optional(),
 	workspaceIds: z.array(workspaceId),
-	archivedSessionIds: z.array(z.string().transform((value) => brandString(value))).default([]),
+	archivedSessionIds: z.array(sessionId).default([]),
+	pinnedSessionIds: z.array(sessionId).default([]),
 	pendingMutation: workspacePendingMutation.optional()
 });
 /**
@@ -253,7 +260,8 @@ const workspaceDomainSpec = defineDomain({
 		initial: {
 			initialized: false,
 			workspaceIds: [],
-			archivedSessionIds: []
+			archivedSessionIds: [],
+			pinnedSessionIds: []
 		}
 	},
 	tables: { workspaces: domainTable(workspaceRecord) }
@@ -275,20 +283,53 @@ function WorkspaceId(id) {
 	return id;
 }
 /**
-* An archiveSession request named a session neither live nor in session
-* persistence — a definite miss only; storage faults propagate as themselves.
+* An archiveSession or pinSession request named a session neither live nor in
+* session persistence — a definite miss only; storage faults propagate as
+* themselves.
 */
 var WorkspaceUnknownSessionError = class extends Error {
 	sessionId;
 	/**
 	* @param sessionId - The unknown session id.
+	* @param verb - The registry operation that named the session.
 	*/
-	constructor(sessionId) {
-		super(`cannot archive session '${sessionId}': live sessions and session persistence hold no such session`);
+	constructor(sessionId, verb) {
+		super(`cannot ${verb} session '${sessionId}': live sessions and session persistence hold no such session`);
 		this.sessionId = sessionId;
 		this.name = "WorkspaceUnknownSessionError";
 	}
 };
+/**
+* An archiveSession request named a session that at least one
+* `workspace/session-activity` listener reported active. Nothing was written;
+* `activity` names what must stop before the session can be archived.
+*/
+var WorkspaceActiveSessionError = class extends Error {
+	sessionId;
+	activity;
+	/**
+	* @param sessionId - The active session id.
+	* @param activity - The reported activity, in listener order.
+	*/
+	constructor(sessionId, activity) {
+		super(`cannot archive session '${sessionId}': the session is active (${activity.map((entry) => entry.kind).join(", ")})`);
+		this.sessionId = sessionId;
+		this.activity = activity;
+		this.name = "WorkspaceActiveSessionError";
+	}
+};
+/** A pinSession request named a session currently in the archive set; pinning and archival are mutually exclusive. */
+var WorkspaceArchivedSessionPinError = class extends Error {
+	sessionId;
+	/**
+	* @param sessionId - The archived session id.
+	*/
+	constructor(sessionId) {
+		super(`cannot pin session '${sessionId}': the session is archived`);
+		this.sessionId = sessionId;
+		this.name = "WorkspaceArchivedSessionPinError";
+	}
+};
 /** A workspace reorder named a source or anchor absent from the durable registry order. */
 var WorkspaceOrderInvalidError = class extends Error {
 	workspaceId;
@@ -368,6 +409,31 @@ var WorkspaceRegistry = class extends Service {
 		return await this.enqueueOperation(() => this.createCanonical(canonical, title));
 	}
 	/**
+	* Initialize the default Workspace only while both the registry and Session
+	* history are empty. Repeated requests reuse its durable identity; deleting
+	* that registration permanently disables automatic creation.
+	* @param resolveDirectory - resolve the absolute directory and initial title;
+	* called only for eligible creation, inside the registry mutation queue.
+	* Missing directories are created recursively before registration.
+	* After resolution, caller cancellation does not roll back creation or registration.
+	* @returns the initialized Workspace, or undefined when automatic creation is ineligible.
+	*/
+	initializeDefault(resolveDirectory) {
+		return this.enqueueOperation(async () => {
+			const state = this.requireState();
+			if (state.defaultWorkspaceId !== void 0) return this.entities.get(state.defaultWorkspaceId);
+			const sessions = this.ctx.get("sessions");
+			if (sessions === void 0) throw new Error("default Workspace initialization requires the Session store");
+			if (state.workspaceIds.length > 0 || state.archivedSessionIds.length > 0 || sessions.list().length > 0 || (await this.listStoredHeaders()).length > 0) return void 0;
+			const { path, title } = await resolveDirectory();
+			if (!fullyQualifiedWorkspacePath(path)) throw new TypeError(`Workspace path is not fully qualified: '${path}'`);
+			await mkdir(path, { recursive: true });
+			const canonical = await realpathNormalize(path);
+			if ((await this.listStoredHeaders()).length > 0 || sessions.list().length > 0) return void 0;
+			return this.createCanonical(canonical, title, true);
+		});
+	}
+	/**
 	* Look up a workspace by id.
 	* @param id - Workspace id.
 	* @returns the workspace, or `undefined` when unknown.
@@ -439,19 +505,35 @@ var WorkspaceRegistry = class extends Service {
 	/**
 	* Archive one session durably. The session must exist (live or in session
 	* persistence); its workspace accounting — or lack of one — is irrelevant.
-	* An already archived id resolves without writing.
+	* Without `stopActivity` the session must also be inactive: the
+	* `workspace/session-activity` waterfall is asked once, and any reported
+	* activity rejects with {@link WorkspaceActiveSessionError} before anything
+	* is written. With `stopActivity` the archive is written without an
+	* activity check, and the `workspace/session-stop` providers are then asked
+	* to stop the session's work: the durable archive set is what a provider's
+	* `agent/pre-step` gate reads, so every wake the stops induce is already
+	* blocked. Archiving drops the session's pin in the same durable write
+	* (pinning and archival are mutually exclusive). An already archived id
+	* resolves without writing, asking, or stopping.
 	* @param sessionId - The session to archive.
-	* @returns resolution after durability.
+	* @param options - Whether running work is stopped instead of refusing.
+	* @returns resolution after durability and, with `stopActivity`, after every stop request was issued.
 	*/
-	archiveSession(sessionId) {
+	archiveSession(sessionId, options = {}) {
 		return this.enqueueOperation(async () => {
 			if (this.requireState().archivedSessionIds.includes(sessionId)) return;
-			if (!await this.sessionKnown(sessionId)) throw new WorkspaceUnknownSessionError(sessionId);
+			if (!await this.sessionKnown(sessionId)) throw new WorkspaceUnknownSessionError(sessionId, "archive");
+			if (options.stopActivity !== true) {
+				const activity = await this.ctx.waterfall("workspace/session-activity", { sessionId }, () => Promise.resolve([]));
+				if (activity.length > 0) throw new WorkspaceActiveSessionError(sessionId, activity);
+			}
 			const state = this.requireState();
 			await this.setState({
 				...state,
-				archivedSessionIds: [...state.archivedSessionIds, sessionId]
+				archivedSessionIds: [...state.archivedSessionIds, sessionId],
+				pinnedSessionIds: state.pinnedSessionIds.filter((id) => id !== sessionId)
 			});
+			if (options.stopActivity === true) await this.stopSessionActivity(sessionId);
 		});
 	}
 	/**
@@ -475,6 +557,51 @@ var WorkspaceRegistry = class extends Service {
 		});
 	}
 	/**
+	* The registry-global pin set: sessions surfaced ahead of every unpinned
+	* session on grouping surfaces. Pinning never touches workspace accounting.
+	* @returns Session ids in pin order (most recently pinned first).
+	*/
+	get pinnedSessionIds() {
+		return this.requireState().pinnedSessionIds;
+	}
+	/**
+	* Pin one session durably, prepending it to the registry-global pin set.
+	* The session must exist (live or in session persistence) and must not be
+	* archived. An already pinned id resolves without writing or reordering.
+	* @param sessionId - The session to pin.
+	* @returns resolution after durability.
+	*/
+	pinSession(sessionId) {
+		return this.enqueueOperation(async () => {
+			if (this.requireState().pinnedSessionIds.includes(sessionId)) return;
+			if (this.requireState().archivedSessionIds.includes(sessionId)) throw new WorkspaceArchivedSessionPinError(sessionId);
+			if (!await this.sessionKnown(sessionId)) throw new WorkspaceUnknownSessionError(sessionId, "pin");
+			const state = this.requireState();
+			await this.setState({
+				...state,
+				pinnedSessionIds: [sessionId, ...state.pinnedSessionIds]
+			});
+		});
+	}
+	/**
+	* Unpin one session durably by dropping it from the registry-global pin
+	* set. Unpinning 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 pinned resolves without writing.
+	* @param sessionId - The session to unpin.
+	* @returns resolution after durability.
+	*/
+	unpinSession(sessionId) {
+		return this.enqueueOperation(async () => {
+			const state = this.requireState();
+			if (!state.pinnedSessionIds.includes(sessionId)) return;
+			await this.setState({
+				...state,
+				pinnedSessionIds: state.pinnedSessionIds.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
@@ -486,6 +613,16 @@ var WorkspaceRegistry = class extends Service {
 		await this.indexHeaders(await this.listStoredHeaders());
 		return this.headers.has(id);
 	}
+	/** Request every provider's stop; a failing provider is logged, never a reason to keep the session visible. */
+	async stopSessionActivity(sessionId) {
+		try {
+			await this.ctx.parallel("workspace/session-stop", { sessionId });
+		} catch (error) {
+			/* v8 ignore next -- the plain arm guards a rethrowing dispatcher. */
+			const failures = error instanceof AggregateError ? error.errors : [error];
+			for (const failure of failures) this.ctx.logger.warn(`workspace: stopping session '${sessionId}' for archive failed: ${String(failure)}`);
+		}
+	}
 	/**
 	* Resolve by canonical directory path without creating or mutating a
 	* workspace. A missing path rejects during `realpath`; an existing unowned
@@ -497,7 +634,7 @@ var WorkspaceRegistry = class extends Service {
 		const canonical = await realpathNormalize(path);
 		for (const entity of this.entities.values()) if (entity.path === canonical) return entity;
 	}
-	async createCanonical(canonical, title) {
+	async createCanonical(canonical, title, firstUse = false) {
 		for (const entity of this.entities.values()) if (entity.path === canonical) return entity;
 		const workspaceName = title ?? defaultWorkspaceTitle(canonical);
 		const table = this.requireTable();
@@ -539,9 +676,11 @@ var WorkspaceRegistry = class extends Service {
 		}
 		try {
 			await this.setState({
+				...state,
+				pendingMutation: void 0,
 				initialized: true,
-				workspaceIds: [id, ...state.workspaceIds],
-				archivedSessionIds: state.archivedSessionIds
+				...firstUse ? { defaultWorkspaceId: id } : {},
+				workspaceIds: [id, ...state.workspaceIds]
 			});
 		} catch (error) {
 			this.entities.delete(id);
@@ -564,9 +703,10 @@ var WorkspaceRegistry = class extends Service {
 		if (entity === void 0) return false;
 		const state = this.requireState();
 		const nextState = {
+			...state,
+			pendingMutation: void 0,
 			initialized: true,
-			workspaceIds: state.workspaceIds.filter((workspaceId) => workspaceId !== id),
-			archivedSessionIds: state.archivedSessionIds
+			workspaceIds: state.workspaceIds.filter((workspaceId) => workspaceId !== id)
 		};
 		await this.setState({
 			...nextState,
@@ -607,9 +747,8 @@ var WorkspaceRegistry = class extends Service {
 		if (state.workspaceIds.includes(pending.workspaceId)) throw new Error(`workspace domain is inconsistent: pending ${pending.operation} workspace '${pending.workspaceId}' is still present in registry order`);
 		await this.requireTable().delete(pending.workspaceId);
 		await this.setState({
-			initialized: state.initialized,
-			workspaceIds: state.workspaceIds,
-			archivedSessionIds: state.archivedSessionIds
+			...state,
+			pendingMutation: void 0
 		});
 	}
 	async bootstrap(headers) {
@@ -677,12 +816,14 @@ var WorkspaceRegistry = class extends Service {
 		if (!sameIds(state.workspaceIds, workspaceIds)) await this.setState({
 			initialized: false,
 			workspaceIds,
-			archivedSessionIds: state.archivedSessionIds
+			archivedSessionIds: state.archivedSessionIds,
+			pinnedSessionIds: state.pinnedSessionIds
 		});
 		await this.setState({
 			initialized: true,
 			workspaceIds,
-			archivedSessionIds: state.archivedSessionIds
+			archivedSessionIds: state.archivedSessionIds,
+			pinnedSessionIds: state.pinnedSessionIds
 		});
 	}
 	validateStoredState(state) {
@@ -802,4 +943,4 @@ var WorkspaceRegistry = class extends Service {
 };
 const sameSessionIds = (left, right) => left.length === right.length && left.every((id, index) => id === right[index]);
 //#endregion
-export { WorkspaceId, WorkspaceMoveInvalidError, WorkspaceOrderInvalidError, WorkspaceRegistry, WorkspaceRegistry as default, WorkspaceUnknownSessionError, realpathNormalize, workspaceDomainSpec, workspaceDomainState, workspaceRecord };
+export { WorkspaceActiveSessionError, WorkspaceArchivedSessionPinError, WorkspaceId, WorkspaceMoveInvalidError, WorkspaceOrderInvalidError, WorkspaceRegistry, WorkspaceRegistry as default, WorkspaceUnknownSessionError, realpathNormalize, workspaceDomainSpec, workspaceDomainState, workspaceRecord };

package/lib/invariant.js

@@ -15,6 +15,7 @@ import { defineDomain, domainTable } from "@deepseek-ai/dsh-storage-domain";
 */
 /** Workspace id schema at the durable boundary; branding has no runtime representation. */
 const workspaceId = z.string().transform((value) => value);
+const sessionId = z.string().transform((value) => brandString(value));
 /**
 * Durable shape of one workspace record. `path` is the `fs.realpath` canon
 * stamped at create; `sessionIds` is the ordered ownership account (array
@@ -23,7 +24,7 @@ const workspaceId = z.string().transform((value) => value);
 const workspaceRecord = z.object({
 	path: z.string(),
 	title: z.string(),
-	sessionIds: z.array(z.string().transform((value) => brandString(value))),
+	sessionIds: z.array(sessionId),
 	createdAt: z.string(),
 	updatedAt: z.string()
 });
@@ -45,14 +46,18 @@ defineDomain({
 	global: {
 		schema: z.object({
 			initialized: z.boolean(),
+			/** First-use Workspace identity, retained after its registration is deleted. */
+			defaultWorkspaceId: workspaceId.optional(),
 			workspaceIds: z.array(workspaceId),
-			archivedSessionIds: z.array(z.string().transform((value) => brandString(value))).default([]),
+			archivedSessionIds: z.array(sessionId).default([]),
+			pinnedSessionIds: z.array(sessionId).default([]),
 			pendingMutation: workspacePendingMutation.optional()
 		}),
 		initial: {
 			initialized: false,
 			workspaceIds: [],
-			archivedSessionIds: []
+			archivedSessionIds: [],
+			pinnedSessionIds: []
 		}
 	},
 	tables: { workspaces: domainTable(workspaceRecord) }

package/lib/types/index.d.ts

@@ -7,8 +7,8 @@
 import { Context, Service } from '@deepseek-ai/cordis';
 import type { SessionId } from '@deepseek-ai/dsh-session';
 export { WorkspaceMoveInvalidError } from './entity.ts';
-import type { Workspace, WorkspaceId as WorkspaceIdBrand } from './types.ts';
-export type { Workspace } from './types.ts';
+import type { SessionActivity, Workspace, WorkspaceId as WorkspaceIdBrand } from './types.ts';
+export type { SessionActivity, SessionActivityItem, SessionActivityKind, SessionActivityKindMap, Workspace, } from './types.ts';
 export { workspaceDomainState, workspaceRecord, workspaceDomainSpec } from './spec.ts';
 export type { WorkspaceDomainState, WorkspaceRecord } from './spec.ts';
 export { realpathNormalize } from './paths.ts';
@@ -21,13 +21,37 @@ export type WorkspaceId = WorkspaceIdBrand;
  */
 export declare function WorkspaceId(id: string): WorkspaceId;
 /**
- * An archiveSession request named a session neither live nor in session
- * persistence — a definite miss only; storage faults propagate as themselves.
+ * An archiveSession or pinSession request named a session neither live nor in
+ * session persistence — a definite miss only; storage faults propagate as
+ * themselves.
  */
 export declare class WorkspaceUnknownSessionError extends Error {
     readonly sessionId: SessionId;
     /**
      * @param sessionId - The unknown session id.
+     * @param verb - The registry operation that named the session.
+     */
+    constructor(sessionId: SessionId, verb: 'archive' | 'pin');
+}
+/**
+ * An archiveSession request named a session that at least one
+ * `workspace/session-activity` listener reported active. Nothing was written;
+ * `activity` names what must stop before the session can be archived.
+ */
+export declare class WorkspaceActiveSessionError extends Error {
+    readonly sessionId: SessionId;
+    readonly activity: readonly SessionActivity[];
+    /**
+     * @param sessionId - The active session id.
+     * @param activity - The reported activity, in listener order.
+     */
+    constructor(sessionId: SessionId, activity: readonly SessionActivity[]);
+}
+/** A pinSession request named a session currently in the archive set; pinning and archival are mutually exclusive. */
+export declare class WorkspaceArchivedSessionPinError extends Error {
+    readonly sessionId: SessionId;
+    /**
+     * @param sessionId - The archived session id.
      */
     constructor(sessionId: SessionId);
 }
@@ -39,10 +63,52 @@ export declare class WorkspaceOrderInvalidError extends Error {
      */
     constructor(workspaceId: WorkspaceId);
 }
+/** The session an archive request is about to write into the archive set. */
+export interface SessionActivityRequest {
+    readonly sessionId: SessionId;
+}
+/** Caller choices for {@link WorkspaceRegistry.archiveSession}. */
+export interface ArchiveSessionOptions {
+    /**
+     * Ask the composed providers to stop the session's running work instead of
+     * refusing the archive because of it. The archive is written first, then
+     * the stops are requested; running work is never awaited to settlement, and
+     * a provider failure is logged without undoing the archive.
+     */
+    readonly stopActivity?: boolean;
+}
 declare module '@deepseek-ai/cordis' {
     interface Context {
         workspaceRegistry: WorkspaceRegistry;
     }
+    interface Events {
+        /**
+         * Ask the composed providers what still runs for a session before it is
+         * archived. A listener prepends its own {@link SessionActivity} entries to
+         * the result of `next()`; the registry's innermost callback returns an
+         * empty list, so a composition without providers archives freely. Any
+         * non-empty result refuses the archive without a write.
+         * @param request - the session about to be archived.
+         * @param next - delegate to the remaining providers.
+         * @mode waterfall
+         */
+        'workspace/session-activity'(request: SessionActivityRequest, next: () => Promise<readonly SessionActivity[]>): Promise<readonly SessionActivity[]>;
+        /**
+         * Stop a session's running work because the caller archived it with
+         * `stopActivity`; the archive set is durable when this dispatches. Each
+         * provider stops its own families — cancelling a turn, its subagent
+         * descendants, owned jobs, or active schedules — through the same cancel
+         * paths the user's own stop actions use, so the session log ends every
+         * open turn regularly and a later unarchive can continue the
+         * conversation. Listeners issue their stop requests without waiting for
+         * running work to settle; a listener may await its own durability
+         * barrier. A rejection is logged by the registry and does not undo the
+         * archive.
+         * @param request - the session being archived.
+         * @mode parallel
+         */
+        'workspace/session-stop'(request: SessionActivityRequest): Promise<void> | void;
+    }
 }
 /**
  * Durable workspace registry. Startup waits for `sessionPersistence`, builds
@@ -77,6 +143,20 @@ export declare class WorkspaceRegistry extends Service {
      * @returns the existing or newly durable workspace.
      */
     create(path: string, title?: string): Promise<Workspace>;
+    /**
+     * Initialize the default Workspace only while both the registry and Session
+     * history are empty. Repeated requests reuse its durable identity; deleting
+     * that registration permanently disables automatic creation.
+     * @param resolveDirectory - resolve the absolute directory and initial title;
+     * called only for eligible creation, inside the registry mutation queue.
+     * Missing directories are created recursively before registration.
+     * After resolution, caller cancellation does not roll back creation or registration.
+     * @returns the initialized Workspace, or undefined when automatic creation is ineligible.
+     */
+    initializeDefault(resolveDirectory: () => Promise<{
+        path: string;
+        title: string;
+    }>): Promise<Workspace | undefined>;
     /**
      * Look up a workspace by id.
      * @param id - Workspace id.
@@ -117,11 +197,21 @@ export declare class WorkspaceRegistry extends Service {
     /**
      * Archive one session durably. The session must exist (live or in session
      * persistence); its workspace accounting — or lack of one — is irrelevant.
-     * An already archived id resolves without writing.
+     * Without `stopActivity` the session must also be inactive: the
+     * `workspace/session-activity` waterfall is asked once, and any reported
+     * activity rejects with {@link WorkspaceActiveSessionError} before anything
+     * is written. With `stopActivity` the archive is written without an
+     * activity check, and the `workspace/session-stop` providers are then asked
+     * to stop the session's work: the durable archive set is what a provider's
+     * `agent/pre-step` gate reads, so every wake the stops induce is already
+     * blocked. Archiving drops the session's pin in the same durable write
+     * (pinning and archival are mutually exclusive). An already archived id
+     * resolves without writing, asking, or stopping.
      * @param sessionId - The session to archive.
-     * @returns resolution after durability.
+     * @param options - Whether running work is stopped instead of refusing.
+     * @returns resolution after durability and, with `stopActivity`, after every stop request was issued.
      */
-    archiveSession(sessionId: SessionId): Promise<void>;
+    archiveSession(sessionId: SessionId, options?: ArchiveSessionOptions): Promise<void>;
     /**
      * Unarchive one session durably by dropping it from the registry-global
      * archive set; the accounting slot was never touched, so the session
@@ -133,6 +223,29 @@ export declare class WorkspaceRegistry extends Service {
      * @returns resolution after durability.
      */
     unarchiveSession(sessionId: SessionId): Promise<void>;
+    /**
+     * The registry-global pin set: sessions surfaced ahead of every unpinned
+     * session on grouping surfaces. Pinning never touches workspace accounting.
+     * @returns Session ids in pin order (most recently pinned first).
+     */
+    get pinnedSessionIds(): readonly SessionId[];
+    /**
+     * Pin one session durably, prepending it to the registry-global pin set.
+     * The session must exist (live or in session persistence) and must not be
+     * archived. An already pinned id resolves without writing or reordering.
+     * @param sessionId - The session to pin.
+     * @returns resolution after durability.
+     */
+    pinSession(sessionId: SessionId): Promise<void>;
+    /**
+     * Unpin one session durably by dropping it from the registry-global pin
+     * set. Unpinning 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 pinned resolves without writing.
+     * @param sessionId - The session to unpin.
+     * @returns resolution after durability.
+     */
+    unpinSession(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
@@ -140,6 +253,8 @@ export declare class WorkspaceRegistry extends Service {
      * masquerade as an unknown session.
      */
     private sessionKnown;
+    /** Request every provider's stop; a failing provider is logged, never a reason to keep the session visible. */
+    private stopSessionActivity;
     /**
      * Resolve by canonical directory path without creating or mutating a
      * workspace. A missing path rejects during `realpath`; an existing unowned

package/lib/types/index.js

@@ -5,11 +5,11 @@
  * @module @deepseek-ai/dsh-workspace
  */
 import { randomUUID } from 'node:crypto';
-import { stat } from 'node:fs/promises';
+import { mkdir, stat } from 'node:fs/promises';
 import { Service } from '@deepseek-ai/cordis';
 import { WorkspaceEntity } from "./entity.js";
 export { WorkspaceMoveInvalidError } from "./entity.js";
-import { defaultWorkspaceTitle, realpathNormalize } from "./paths.js";
+import { defaultWorkspaceTitle, fullyQualifiedWorkspacePath, realpathNormalize } from "./paths.js";
 import { workspaceDomainSpec } from "./spec.js";
 export { workspaceDomainState, workspaceRecord, workspaceDomainSpec } from "./spec.js";
 export { realpathNormalize } from "./paths.js";
@@ -22,20 +22,53 @@ export function WorkspaceId(id) {
     return id;
 }
 /**
- * An archiveSession request named a session neither live nor in session
- * persistence — a definite miss only; storage faults propagate as themselves.
+ * An archiveSession or pinSession request named a session neither live nor in
+ * session persistence — a definite miss only; storage faults propagate as
+ * themselves.
  */
 export class WorkspaceUnknownSessionError extends Error {
     sessionId;
     /**
      * @param sessionId - The unknown session id.
+     * @param verb - The registry operation that named the session.
      */
-    constructor(sessionId) {
-        super(`cannot archive session '${sessionId}': live sessions and session persistence hold no such session`);
+    constructor(sessionId, verb) {
+        super(`cannot ${verb} session '${sessionId}': live sessions and session persistence hold no such session`);
         this.sessionId = sessionId;
         this.name = 'WorkspaceUnknownSessionError';
     }
 }
+/**
+ * An archiveSession request named a session that at least one
+ * `workspace/session-activity` listener reported active. Nothing was written;
+ * `activity` names what must stop before the session can be archived.
+ */
+export class WorkspaceActiveSessionError extends Error {
+    sessionId;
+    activity;
+    /**
+     * @param sessionId - The active session id.
+     * @param activity - The reported activity, in listener order.
+     */
+    constructor(sessionId, activity) {
+        super(`cannot archive session '${sessionId}': the session is active (${activity.map(entry => entry.kind).join(', ')})`);
+        this.sessionId = sessionId;
+        this.activity = activity;
+        this.name = 'WorkspaceActiveSessionError';
+    }
+}
+/** A pinSession request named a session currently in the archive set; pinning and archival are mutually exclusive. */
+export class WorkspaceArchivedSessionPinError extends Error {
+    sessionId;
+    /**
+     * @param sessionId - The archived session id.
+     */
+    constructor(sessionId) {
+        super(`cannot pin session '${sessionId}': the session is archived`);
+        this.sessionId = sessionId;
+        this.name = 'WorkspaceArchivedSessionPinError';
+    }
+}
 /** A workspace reorder named a source or anchor absent from the durable registry order. */
 export class WorkspaceOrderInvalidError extends Error {
     workspaceId;
@@ -124,6 +157,38 @@ export class WorkspaceRegistry extends Service {
         }
         return await this.enqueueOperation(() => this.createCanonical(canonical, title));
     }
+    /**
+     * Initialize the default Workspace only while both the registry and Session
+     * history are empty. Repeated requests reuse its durable identity; deleting
+     * that registration permanently disables automatic creation.
+     * @param resolveDirectory - resolve the absolute directory and initial title;
+     * called only for eligible creation, inside the registry mutation queue.
+     * Missing directories are created recursively before registration.
+     * After resolution, caller cancellation does not roll back creation or registration.
+     * @returns the initialized Workspace, or undefined when automatic creation is ineligible.
+     */
+    initializeDefault(resolveDirectory) {
+        return this.enqueueOperation(async () => {
+            const state = this.requireState();
+            if (state.defaultWorkspaceId !== undefined)
+                return this.entities.get(state.defaultWorkspaceId);
+            const sessions = this.ctx.get('sessions');
+            if (sessions === undefined)
+                throw new Error('default Workspace initialization requires the Session store');
+            if (state.workspaceIds.length > 0 || state.archivedSessionIds.length > 0
+                || sessions.list().length > 0 || (await this.listStoredHeaders()).length > 0)
+                return undefined;
+            const { path, title } = await resolveDirectory();
+            if (!fullyQualifiedWorkspacePath(path))
+                throw new TypeError(`Workspace path is not fully qualified: '${path}'`);
+            await mkdir(path, { recursive: true });
+            const canonical = await realpathNormalize(path);
+            // A Session can start outside the registry queue while directory preparation awaits I/O.
+            if ((await this.listStoredHeaders()).length > 0 || sessions.list().length > 0)
+                return undefined;
+            return this.createCanonical(canonical, title, true);
+        });
+    }
     /**
      * Look up a workspace by id.
      * @param id - Workspace id.
@@ -196,21 +261,42 @@ export class WorkspaceRegistry extends Service {
     /**
      * Archive one session durably. The session must exist (live or in session
      * persistence); its workspace accounting — or lack of one — is irrelevant.
-     * An already archived id resolves without writing.
+     * Without `stopActivity` the session must also be inactive: the
+     * `workspace/session-activity` waterfall is asked once, and any reported
+     * activity rejects with {@link WorkspaceActiveSessionError} before anything
+     * is written. With `stopActivity` the archive is written without an
+     * activity check, and the `workspace/session-stop` providers are then asked
+     * to stop the session's work: the durable archive set is what a provider's
+     * `agent/pre-step` gate reads, so every wake the stops induce is already
+     * blocked. Archiving drops the session's pin in the same durable write
+     * (pinning and archival are mutually exclusive). An already archived id
+     * resolves without writing, asking, or stopping.
      * @param sessionId - The session to archive.
-     * @returns resolution after durability.
+     * @param options - Whether running work is stopped instead of refusing.
+     * @returns resolution after durability and, with `stopActivity`, after every stop request was issued.
      */
-    archiveSession(sessionId) {
+    archiveSession(sessionId, options = {}) {
         return this.enqueueOperation(async () => {
             // The chain slot serializes against every other registry write, so this
             // check-then-write pair cannot interleave with another archive.
             if (this.requireState().archivedSessionIds.includes(sessionId))
                 return;
             if (!(await this.sessionKnown(sessionId))) {
-                throw new WorkspaceUnknownSessionError(sessionId);
+                throw new WorkspaceUnknownSessionError(sessionId, 'archive');
+            }
+            if (options.stopActivity !== true) {
+                const activity = await this.ctx.waterfall('workspace/session-activity', { sessionId }, () => Promise.resolve([]));
+                if (activity.length > 0)
+                    throw new WorkspaceActiveSessionError(sessionId, activity);
             }
             const state = this.requireState();
-            await this.setState({ ...state, archivedSessionIds: [...state.archivedSessionIds, sessionId] });
+            await this.setState({
+                ...state,
+                archivedSessionIds: [...state.archivedSessionIds, sessionId],
+                pinnedSessionIds: state.pinnedSessionIds.filter(id => id !== sessionId),
+            });
+            if (options.stopActivity === true)
+                await this.stopSessionActivity(sessionId);
         });
     }
     /**
@@ -236,6 +322,61 @@ export class WorkspaceRegistry extends Service {
             });
         });
     }
+    /**
+     * The registry-global pin set: sessions surfaced ahead of every unpinned
+     * session on grouping surfaces. Pinning never touches workspace accounting.
+     * @returns Session ids in pin order (most recently pinned first).
+     */
+    get pinnedSessionIds() {
+        return this.requireState().pinnedSessionIds;
+    }
+    /**
+     * Pin one session durably, prepending it to the registry-global pin set.
+     * The session must exist (live or in session persistence) and must not be
+     * archived. An already pinned id resolves without writing or reordering.
+     * @param sessionId - The session to pin.
+     * @returns resolution after durability.
+     */
+    pinSession(sessionId) {
+        return this.enqueueOperation(async () => {
+            // The chain slot serializes against every other registry write, so this
+            // check-then-write pair cannot interleave with another pin or archive.
+            if (this.requireState().pinnedSessionIds.includes(sessionId))
+                return;
+            if (this.requireState().archivedSessionIds.includes(sessionId)) {
+                throw new WorkspaceArchivedSessionPinError(sessionId);
+            }
+            if (!(await this.sessionKnown(sessionId))) {
+                throw new WorkspaceUnknownSessionError(sessionId, 'pin');
+            }
+            const state = this.requireState();
+            await this.setState({
+                ...state,
+                pinnedSessionIds: [sessionId, ...state.pinnedSessionIds],
+            });
+        });
+    }
+    /**
+     * Unpin one session durably by dropping it from the registry-global pin
+     * set. Unpinning 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 pinned resolves without writing.
+     * @param sessionId - The session to unpin.
+     * @returns resolution after durability.
+     */
+    unpinSession(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 pin.
+            const state = this.requireState();
+            if (!state.pinnedSessionIds.includes(sessionId))
+                return;
+            await this.setState({
+                ...state,
+                pinnedSessionIds: state.pinnedSessionIds.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
@@ -250,6 +391,20 @@ export class WorkspaceRegistry extends Service {
         await this.indexHeaders(await this.listStoredHeaders());
         return this.headers.has(id);
     }
+    /** Request every provider's stop; a failing provider is logged, never a reason to keep the session visible. */
+    async stopSessionActivity(sessionId) {
+        try {
+            await this.ctx.parallel('workspace/session-stop', { sessionId });
+        }
+        catch (error) {
+            // ctx.parallel settles every listener and rejects with one AggregateError.
+            /* v8 ignore next -- the plain arm guards a rethrowing dispatcher. */
+            const failures = error instanceof AggregateError ? error.errors : [error];
+            for (const failure of failures) {
+                this.ctx.logger.warn(`workspace: stopping session '${sessionId}' for archive failed: ${String(failure)}`);
+            }
+        }
+    }
     /**
      * Resolve by canonical directory path without creating or mutating a
      * workspace. A missing path rejects during `realpath`; an existing unowned
@@ -265,7 +420,7 @@ export class WorkspaceRegistry extends Service {
         }
         return undefined;
     }
-    async createCanonical(canonical, title) {
+    async createCanonical(canonical, title, firstUse = false) {
         for (const entity of this.entities.values()) {
             if (entity.path === canonical)
                 return entity;
@@ -310,9 +465,11 @@ export class WorkspaceRegistry extends Service {
         }
         try {
             await this.setState({
+                ...state,
+                pendingMutation: undefined,
                 initialized: true,
+                ...(firstUse ? { defaultWorkspaceId: id } : {}),
                 workspaceIds: [id, ...state.workspaceIds],
-                archivedSessionIds: state.archivedSessionIds,
             });
         }
         catch (error) {
@@ -339,9 +496,10 @@ export class WorkspaceRegistry extends Service {
             return false;
         const state = this.requireState();
         const nextState = {
+            ...state,
+            pendingMutation: undefined,
             initialized: true,
             workspaceIds: state.workspaceIds.filter(workspaceId => workspaceId !== id),
-            archivedSessionIds: state.archivedSessionIds,
         };
         await this.setState({
             ...nextState,
@@ -391,11 +549,7 @@ export class WorkspaceRegistry extends Service {
                 + `'${pending.workspaceId}' is still present in registry order`);
         }
         await this.requireTable().delete(pending.workspaceId);
-        await this.setState({
-            initialized: state.initialized,
-            workspaceIds: state.workspaceIds,
-            archivedSessionIds: state.archivedSessionIds,
-        });
+        await this.setState({ ...state, pendingMutation: undefined });
     }
     async bootstrap(headers) {
         const table = this.requireTable();
@@ -478,9 +632,19 @@ export class WorkspaceRegistry extends Service {
         })
             .map(([id]) => id);
         if (!sameIds(state.workspaceIds, workspaceIds)) {
-            await this.setState({ initialized: false, workspaceIds, archivedSessionIds: state.archivedSessionIds });
+            await this.setState({
+                initialized: false,
+                workspaceIds,
+                archivedSessionIds: state.archivedSessionIds,
+                pinnedSessionIds: state.pinnedSessionIds,
+            });
         }
-        await this.setState({ initialized: true, workspaceIds, archivedSessionIds: state.archivedSessionIds });
+        await this.setState({
+            initialized: true,
+            workspaceIds,
+            archivedSessionIds: state.archivedSessionIds,
+            pinnedSessionIds: state.pinnedSessionIds,
+        });
     }
     validateStoredState(state) {
         const table = this.requireTable();

package/lib/types/spec.d.ts

@@ -28,12 +28,17 @@ export type WorkspaceRecord = z.infer<typeof workspaceRecord>;
  * the registry-global archive set layered over workspace accounting: an
  * archived session keeps its `sessionIds` slot (unarchiving must restore the
  * position), so the set never participates in the one-owner accounting
- * invariant. Defaulted so records written before the field parse unchanged.
+ * invariant. `pinnedSessionIds` is the registry-global pin set in pin order
+ * (most recently pinned first); pinning and archival are mutually
+ * exclusive, so archiving drops the session's pin. Both session sets are
+ * defaulted so records written before the fields parse unchanged.
  */
 export declare const workspaceDomainState: z.ZodObject<{
     initialized: z.ZodBoolean;
+    defaultWorkspaceId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<WorkspaceId, string>>>;
     workspaceIds: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<WorkspaceId, string>>>;
     archivedSessionIds: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<SessionId, string>>>>;
+    pinnedSessionIds: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<SessionId, string>>>>;
     pendingMutation: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
         operation: z.ZodLiteral<"create">;
         workspaceId: z.ZodPipe<z.ZodString, z.ZodTransform<WorkspaceId, string>>;
@@ -56,8 +61,10 @@ export declare const workspaceDomainSpec: {
     global: {
         schema: z.ZodObject<{
             initialized: z.ZodBoolean;
+            defaultWorkspaceId: z.ZodOptional<z.ZodPipe<z.ZodString, z.ZodTransform<WorkspaceId, string>>>;
             workspaceIds: z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<WorkspaceId, string>>>;
             archivedSessionIds: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<SessionId, string>>>>;
+            pinnedSessionIds: z.ZodDefault<z.ZodArray<z.ZodPipe<z.ZodString, z.ZodTransform<SessionId, string>>>>;
             pendingMutation: z.ZodOptional<z.ZodDiscriminatedUnion<[z.ZodObject<{
                 operation: z.ZodLiteral<"create">;
                 workspaceId: z.ZodPipe<z.ZodString, z.ZodTransform<WorkspaceId, string>>;
@@ -70,6 +77,7 @@ export declare const workspaceDomainSpec: {
             initialized: boolean;
             workspaceIds: never[];
             archivedSessionIds: never[];
+            pinnedSessionIds: never[];
         };
     };
     tables: {

package/lib/types/spec.js

@@ -9,6 +9,7 @@ import { brandString } from '@deepseek-ai/dsh-brand';
 import { defineDomain, domainTable } from '@deepseek-ai/dsh-storage-domain';
 /** Workspace id schema at the durable boundary; branding has no runtime representation. */
 const workspaceId = z.string().transform(value => value);
+const sessionId = z.string().transform(value => brandString(value));
 /**
  * Durable shape of one workspace record. `path` is the `fs.realpath` canon
  * stamped at create; `sessionIds` is the ordered ownership account (array
@@ -17,7 +18,7 @@ const workspaceId = z.string().transform(value => value);
 export const workspaceRecord = z.object({
     path: z.string(),
     title: z.string(),
-    sessionIds: z.array(z.string().transform(value => brandString(value))),
+    sessionIds: z.array(sessionId),
     createdAt: z.string(),
     updatedAt: z.string(),
 });
@@ -37,12 +38,18 @@ const workspacePendingMutation = z.discriminatedUnion('operation', [
  * the registry-global archive set layered over workspace accounting: an
  * archived session keeps its `sessionIds` slot (unarchiving must restore the
  * position), so the set never participates in the one-owner accounting
- * invariant. Defaulted so records written before the field parse unchanged.
+ * invariant. `pinnedSessionIds` is the registry-global pin set in pin order
+ * (most recently pinned first); pinning and archival are mutually
+ * exclusive, so archiving drops the session's pin. Both session sets are
+ * defaulted so records written before the fields parse unchanged.
  */
 export const workspaceDomainState = z.object({
     initialized: z.boolean(),
+    /** First-use Workspace identity, retained after its registration is deleted. */
+    defaultWorkspaceId: workspaceId.optional(),
     workspaceIds: z.array(workspaceId),
-    archivedSessionIds: z.array(z.string().transform(value => brandString(value))).default([]),
+    archivedSessionIds: z.array(sessionId).default([]),
+    pinnedSessionIds: z.array(sessionId).default([]),
     pendingMutation: workspacePendingMutation.optional(),
 });
 /**
@@ -56,7 +63,7 @@ export const workspaceDomainSpec = defineDomain({
     version: 2,
     global: {
         schema: workspaceDomainState,
-        initial: { initialized: false, workspaceIds: [], archivedSessionIds: [] },
+        initial: { initialized: false, workspaceIds: [], archivedSessionIds: [], pinnedSessionIds: [] },
     },
     tables: { workspaces: domainTable(workspaceRecord) },
 });

package/lib/types/types.d.ts

@@ -19,6 +19,35 @@ declare module '@deepseek-ai/dsh-typert-protocol' {
         };
     }
 }
+/**
+ * Activity families a `workspace/session-activity` listener may report. This
+ * package declares none: each provider merges its own key from a module both
+ * its Host and Client faces import, so a consumer that renders the families
+ * sees exactly the keys its program compiled and falls through to a generic
+ * description for any other. The shipped providers merge `turn` (the Agent
+ * registry), `job` (the job registry seam), `subagent` (the Subagent
+ * runtime), and `schedule` (the Schedule plugin).
+ */
+export interface SessionActivityKindMap {
+}
+/** One activity family key. */
+export type SessionActivityKind = keyof SessionActivityKindMap;
+/** One active item of a family that has per-item identity. */
+export interface SessionActivityItem {
+    /** Family-specific identity: a session id, a job id, or a schedule id. */
+    readonly id: string;
+    /** Display label when the family carries one (a job label, a subagent label). */
+    readonly label?: string;
+}
+/**
+ * One reason a session counts as active for archive admission. Families with
+ * per-item identity list their items so a caller can name what must stop.
+ */
+export interface SessionActivity {
+    readonly kind: SessionActivityKind;
+    /** Active items of the family; absent for a family without per-item identity (`turn`). */
+    readonly items?: readonly SessionActivityItem[];
+}
 /**
  * One workspace: a stable id over an existing directory, a display title, and
  * an ordered candidate account of sessions. Membership requires both an id in

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.6-alpha.2",
+  "version": "0.1.7-alpha.1",
   "publishConfig": {
     "access": "public"
   },
@@ -37,25 +37,25 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-storage": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-invariants": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-storage": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.7-alpha.1"
   },
   "dependencies": {
     "zod": "^4.4.3",
-    "@deepseek-ai/dsh-brand": "^0.1.6-alpha.2"
+    "@deepseek-ai/dsh-brand": "^0.1.7-alpha.1"
   },
   "devDependencies": {
-    "@deepseek-ai/cordis": "^4.0.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-session-persistence": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-storage": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-storage-domain": "^0.1.6-alpha.2",
-    "@deepseek-ai/dsh-typert-protocol": "^0.1.6-alpha.2"
+    "@deepseek-ai/cordis": "^4.0.3",
+    "@deepseek-ai/dsh-session-persistence": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-storage": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-storage-domain": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-typert-protocol": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-invariants": "^0.1.7-alpha.1",
+    "@deepseek-ai/dsh-session": "^0.1.7-alpha.1"
   }
 }