@morlay/session-rdb 0.0.21-alpha.5 → 0.0.21-alpha.7

package/README.md

@@ -7,31 +7,26 @@ SQLite 或 PostgreSQL 后端。表结构、原样存储与各条流程的设计
 
 ## 配置
 
-配置写在 `${DSH_HOME}/settings.yaml`，settings namespace 为插件短名
-`session-rdb`（与 cordis 插件 `name` 一致）：
+配置**就是这一行的 config**（`cordis.patch.yml` 的 `session-rdb` 行，或 profile patch /
+设置页改的那份 entry config）：
 
 ```yaml
-session-rdb:
-  type: sqlite
-  # path 省略时回落 cordis.patch.yml 的默认（$DSH_HOME/sessions/sessions.sqlite，
-  # 由 bundle patch 的 !!js 表达式求值）；自定义路径请用绝对路径字符串。
-  path: /absolute/path/to/sessions.sqlite
-  journalMode: wal
-  busyTimeout: 5000
+- id: session-rdb
+  name: "@morlay/session-rdb"
+  config:
+    type: sqlite
+    # path 省略时回落 bundle patch 的默认（$DSH_HOME/sessions/sessions.sqlite，
+    # 由 patch 的 !!js 表达式求值）；自定义路径请用绝对路径字符串。
+    path: /absolute/path/to/sessions.sqlite
+    journalMode: wal
+    busyTimeout: 5000
 ```
 
-> settings.yaml 是纯 YAML（settings-local 用 `yaml` 库解析），**不支持 `!!js`
-> JS 表达式**——`!!js dshHomePath(...)` 会被当作字面字符串。`!!js` 只在
-> `cordis.patch.yml`（bundle patch 层，loader 求值）有效。
+PostgreSQL 同理：`type: postgres` + `connectionString`。
 
-字段即 Config 判别联合（见下）；未写出的字段回落到 bundle patch / cordis.yml 的
-config 默认值。PostgreSQL：
-
-```yaml
-session-rdb:
-  type: postgres
-  connectionString: postgres://user:pass@localhost:5432/sessions
-```
+> 上游 0.1.7 取消了「settings namespace 覆盖插件 config」那套机制（settings 现在只做
+> volatile 字段的表单编辑，持久化落回 profile patch）。老库的 `settings.yaml` 由上游在
+> 启动时**一次性导入**到同 id 的行 config，内容不丢；此后要改就改行 config 或设置页。
 
 Config 类型：
 
@@ -45,6 +40,8 @@ type Config =
       journalMode?: "wal" | "delete" | "truncate" | "persist";
       /** 写锁竞争等待毫秒数（默认 5000）。 */
       busyTimeout?: number;
+      /** 投影 checkpoint 的写入节奏（`writeEveryEvents` / `writeIntervalMs`）。 */
+      projectionCache?: ProjectionCacheOptions;
     }
   | {
       type: "postgres";
@@ -52,6 +49,8 @@ type Config =
       connectionString: string;
       /** 目标 schema（默认 public，必须已存在）。 */
       schema?: string;
+      /** 投影 checkpoint 的写入节奏（`writeEveryEvents` / `writeIntervalMs`）。 */
+      projectionCache?: ProjectionCacheOptions;
     };
 ```
 
@@ -79,6 +78,24 @@ web 模式经 `POST /api/session.delete`（body `{ sessionId }`）暴露，状
 [ADR-会话删除仅限已归档且硬删](.agents/adrs/20260917-会话删除仅限已归档且硬删.md) 与
 [ADR-删除不再清孤儿与vacuum独立成gc通道](.agents/adrs/20260918-删除不再清孤儿与vacuum独立成gc通道.md)。
 
+## 会话列表（两条路）
+
+| 用途                  | 接缝                                                                                                            | 内容                                             |
+| --------------------- | --------------------------------------------------------------------------------------------------------------- | ------------------------------------------------ |
+| 官方 UI（上游 `ui-*`）| `session/list` → `ctx.sessionQuery.listSessions`（本包接管，**默认排除已归档**）                                 | 未归档的可见语料，标题走投影（`projections.title`） |
+| 我们自己的管理面      | `POST /api/session.rows`（本包路由）                                                                            | **完整语料（含归档）** + 标题 + 最后活动时间 + 工作区归属，**搜索 / 子代理过滤 / 分页都在后端** |
+
+排除归档是本部署的策略：归档是「收起来」的会话，不该混进日常列表与搜索。管理动作（取消归档 / 删除 /
+导入）需要完整集合，所以另给一条自有路由，两条路不混。决策与取舍见
+[ADR-会话列表两条路](.agents/adrs/20260922-会话列表两条路.md)。
+
+`session.rows` 的请求体是 `{ query?, includeSubagents?, page?, pageSize? }`（`pageSize` 默认 20、上限 200），
+响应是 `{ items, total, page, pageSize }`——**搜索与分页都在后端**：前端分页等于每次拉全量，数据一多就崩。
+
+排序键是会话行的 **`f_last_event_at`**（由写路径维护、老数据由迁移一次性回填、没有事件的会话回落
+`f_created_at`）。早先这里对每行算一次「该会话最后事件时间」的相关子查询：真实库 243 行要 **4.2s**，
+加 `LIMIT` 也救不了（排序要求全表先算出来）；物化之后同一条分页查询是 **0.2ms**。
+
 ## 导出
 
 `POST /api/session.export`（body `{ sessionId }`）直接把会话日志打成 zip **响应体**：
@@ -109,6 +126,13 @@ subagent 会话**（`origin = 'subagent'`、父不在表里；有 open handle /
 孤儿行不计），GC 顺带回收不再有事件行的用量行。口径与取舍见
 [ADR-用量统计走专用用量日志表](.agents/adrs/20260918-用量统计走专用用量日志表.md)。
 
+## 查询接管（`ctx.sessionQuery`）
+
+官方 `session-query-sqlite` 由 `@morlay/better-session` 的 patch 禁用，本包注册 `ctx.sessionQuery`：
+精确读 / 过滤 / 血缘复用上游 `SessionQueryEngine` 基类，**全文检索恒 disabled**
+（抛 `SESSION_QUERY_SEARCH_DISABLED`，不引入派生索引库）。决策见
+[ADR-接管会话查询服务所有权](.agents/adrs/20260917-接管会话查询服务所有权.md)。
+
 ## storages 接管（workspace 与投影缓存）
 
 `$DSH_HOME/storages` 不再产生文件：官方 `storage-json` 与
@@ -118,15 +142,17 @@ subagent 会话**（`origin = 'subagent'`、父不在表里；有 open handle /
 [表结构](.agents/designs/20260917-表结构.md)，决策见
 [ADR-接管storages到rdb语义表](.agents/adrs/20260917-接管storages到rdb语义表.md)。
 
-写节流参数（默认 200 / 5000，与官方 base 装配一致）可经 settings 覆盖：
+写节流参数（默认 200 / 5000，与官方 base 装配一致）同样写在行 config 里：
 
 ```yaml
-session-rdb:
-  type: sqlite
-  path: /absolute/path/to/sessions.sqlite
-  projectionCache:
-    writeEveryEvents: 200
-    writeIntervalMs: 5000
+- id: session-rdb
+  name: "@morlay/session-rdb"
+  config:
+    type: sqlite
+    path: /absolute/path/to/sessions.sqlite
+    projectionCache:
+      writeEveryEvents: 200
+      writeIntervalMs: 5000
 ```
 
 旧 `storages` JSON 的导入是**包内 API**（先停掉 dsh，旧文件保留不删）——没有 CLI

package/dist/artifact.d.mts

@@ -1,4 +1,4 @@
-import { a as SessionRow, i as EventRow } from "./backend-a0xDrUFG.mjs";
+import { i as EventRow, s as SessionRow } from "./backend-E0bmTXpz.mjs";
 import { SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, parseImportZip, parseJsonlArtifact, persistImport, registerSessionImport } from "./import.mjs";
 import { SessionStorageMetadata } from "@deepseek-ai/dsh-session-persistence";
 import { SessionEvent, SessionHeader } from "@deepseek-ai/dsh-session";
@@ -15,6 +15,7 @@ declare function sessionInsertRow(storage: SessionStorageMetadata, incarnation:
   fSeedLength: number | null;
   fOrigin: string | null;
   fDelegationDepth: number | null;
+  fAgentPreset: string | null;
   fIncarnation: string;
   fRevision: number;
 };
@@ -26,6 +27,7 @@ declare function sessionConflictRow(storage: SessionStorageMetadata): {
   fSeedLength: number | null;
   fOrigin: string | null;
   fDelegationDepth: number | null;
+  fAgentPreset: string | null;
 };
 declare function rowToEvent(row: EventRow): SessionEvent;
 declare function recomputeReplaceProvenance(events: SessionEvent[]): void;
@@ -40,6 +42,29 @@ declare function repairAssistantSettlement(events: SessionEvent[]): void;
 declare function repairRequestHeaders(events: SessionEvent[]): void;
 declare function syncMeteringRanges(events: SessionEvent[]): void;
 declare function renameLegacyPtcEvents(events: SessionEvent[]): void;
+/**
+ * 把**旧代（v3 及更早）的消息形状**归一到当前格式（v4）：迁移链（严格）拒绝那些形状时，读路径仍要
+ * 能把它们读出来——只动字段与标记，不改坐标、不改内容。
+ *
+ * 三件事：
+ * - `system/message` 的 source：`{ kind: 'plugin', plugin: '@deepseek-ai/dsh-system-prompt' }` → `{ kind: 'system-prompt' }`
+ *   （v4 起 system 消息只认这个 kind）；
+ * - `tool/result` 的消息：v3 是 user 角色、结果块包在 `content[0]`；v4 是 `role: 'tool'` + 顶层
+ *   `toolCallId` + `content` 就是结果块；
+ * - 本仓库自己写过、上游已删除的事件类型（见 `LEGACY_OWN_EVENT_TYPES`）标 `ignorable: true`——v4 的
+ *   校验对未知类型只接受可忽略信封。
+ *
+ * 只认这张白名单：**其它未知类型保持 fail loud**（那是「数据来自更新的 harness」的信号，不能吞掉）。
+ */
+declare function normalizeToCurrentShape(events: SessionEvent[]): void;
+/**
+ * 本仓库写过、后来连同机制一起删除的事件类型：读的时候标 `ignorable: true` 让校验跳过它们。
+ * 新增历史类型时登记到这里——**不要**用「所有未知类型」代替（那会掩盖更新版本的未知事件）。
+ */
+declare const LEGACY_OWN_EVENT_TYPES: ReadonlySet<string>;
+/** 行里是否还带着旧代消息形状（`session-branch/version` 这类自造事件也算）——写路径曾把回退视图的结果
+ * 以当前版本号落库，所以**版本号不可信**，读之前要按内容判一次。 */
+declare function hasLegacyShape(events: readonly SessionEvent[]): boolean;
 declare function repairReadView(events: SessionEvent[]): void;
 declare function orphanInboxSpliceSeqs(events: readonly SessionEvent[]): Set<number>;
 declare function repairOrphanInboxSplices(events: SessionEvent[]): void;
@@ -74,4 +99,4 @@ declare function usageRowOf(event: {
   fData: string;
 }): EventUsageRow | undefined;
 //#endregion
-export { EventUsageRow, SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact, usageRowOf };
+export { EventUsageRow, LEGACY_OWN_EVENT_TYPES, SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, hasLegacyShape, normalizeToCurrentShape, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact, usageRowOf };

package/dist/artifact.mjs

@@ -1,3 +1,3 @@
-import { _ as toJsonlArtifact, a as repairAssistantSettlement, c as repairRequestHeaders, d as rowToMeta, f as scanRows, g as titleOfEventData, h as syncMeteringRanges, i as renameLegacyPtcEvents, l as repairSurfaceOps, m as sessionInsertRow, n as orphanInboxSpliceSeqs, o as repairOrphanInboxSplices, p as sessionConflictRow, r as recomputeReplaceProvenance, s as repairReadView, t as findSurfaceRepairs, u as rowToEvent, v as usageRowOf } from "./log-C-rbdFwK.mjs";
+import { _ as sessionInsertRow, a as orphanInboxSpliceSeqs, b as toJsonlArtifact, c as repairAssistantSettlement, d as repairRequestHeaders, f as repairSurfaceOps, g as sessionConflictRow, h as scanRows, i as normalizeToCurrentShape, l as repairOrphanInboxSplices, m as rowToMeta, n as findSurfaceRepairs, o as recomputeReplaceProvenance, p as rowToEvent, r as hasLegacyShape, s as renameLegacyPtcEvents, t as LEGACY_OWN_EVENT_TYPES, u as repairReadView, v as syncMeteringRanges, x as usageRowOf, y as titleOfEventData } from "./log-qCNkDjh5.mjs";
 import { SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, parseImportZip, parseJsonlArtifact, persistImport, registerSessionImport } from "./import.mjs";
-export { SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact, usageRowOf };
+export { LEGACY_OWN_EVENT_TYPES, SESSION_IMPORT_PATH, SESSION_LOG_ARTIFACT_FILENAME, findSurfaceRepairs, hasLegacyShape, normalizeToCurrentShape, orphanInboxSpliceSeqs, parseImportZip, parseJsonlArtifact, persistImport, recomputeReplaceProvenance, registerSessionImport, renameLegacyPtcEvents, repairAssistantSettlement, repairOrphanInboxSplices, repairReadView, repairRequestHeaders, repairSurfaceOps, rowToEvent, rowToMeta, scanRows, sessionConflictRow, sessionInsertRow, syncMeteringRanges, titleOfEventData, toJsonlArtifact, usageRowOf };

package/dist/{backend-a0xDrUFG.d.mts → backend-E0bmTXpz.d.mts}

@@ -2917,20 +2917,24 @@ declare class SessionProjectionCache extends Service {
   private recordFor;
   /**
    * The zero-I/O listing read: whole values viewed straight from the stored
-   * rows (version-matching keys only), each cut carried with its watermark so
-   * a client value store can seed under its higher-seq-wins rule — as stale
-   * as the last durable checkpoint but never wrong, and never from an
-   * unrelated log (the caller's header is the identity witness). Fresher
-   * paths (the history tail baseline) supersede these values whenever a
-   * session is actually opened.
+   * rows (version-matching keys only) of the record bound to the caller's
+   * lifecycle. The header is the only identity witness a listing holds, so
+   * this face matches the lifecycle identity (`formatVersion`, `createdAt`,
+   * `cwd`, `isSeeded`) and not the inherited cut: within one format
+   * generation the cut is fixed at fork time, so it distinguishes no
+   * lifecycle the other fields do not, and a viewed value never seeds a fold.
+   * The view is as stale as the last durable checkpoint but never wrong and
+   * never from an unrelated log. Its `asOfSeq` is the lowest watermark among
+   * the served rows: the stored record's own position, which the header
+   * cannot relate to the log the caller later opens. The Session list
+   * therefore labels the block as cached, and the client lets every value the
+   * connected Session produces supersede it whatever this number says.
    * @param meta - the listed session's header (identity witness; no log read).
-   * @param inheritedEventCount - exact inherited prefix length that completes
-   * the checkpoint identity.
    * @param keys - optional projection keys required by the caller's audience.
-   * @returns the cut (`asOfSeq` = lowest served-row watermark), or
-   *   `undefined` when no usable row exists for this lifecycle.
+   * @returns the viewed block, or `undefined` when no usable row exists for
+   *   this lifecycle at the current Session format.
    */
-  cachedSnapshot(meta: SessionHeader, inheritedEventCount: SessionLogOffset, keys?: readonly Extract<keyof SessionProjectionMap, string>[]): ProjectionSnapshot | undefined;
+  cachedSnapshot(meta: SessionHeader, keys?: readonly Extract<keyof SessionProjectionMap, string>[]): ProjectionSnapshot | undefined;
   /**
    * Read only a predecessor checkpoint's title as a zero-I/O listing hint.
    *
@@ -2940,16 +2944,20 @@ declare class SessionProjectionCache extends Service {
    * fact from this Session. The registry still requires the current title
    * projection's row version and schema. No other predecessor projection is
    * exposed: format normalization can change their current meaning, and the
-   * strict {@link cachedSnapshot} / hydration paths continue to reject them.
+   * {@link cachedSnapshot} / hydration paths continue to reject them.
    * @param meta - authoritative listed Session header.
-   * @param inheritedEventCount - exact inherited cut completing the lifecycle identity.
-   * @returns a title-only checkpoint view with `asOfSeq: -1`, or `undefined`
-   *   when the record is current, newer, unrelated, missing, or incompatible
-   *   with the title unit. The sentinel avoids reusing a sequence that a
-   *   cardinality-changing Session migration may have remapped.
-   */
-  cachedPredecessorTitle(meta: SessionHeader, inheritedEventCount: SessionLogOffset): ProjectionSnapshot | undefined;
-  /** View selected wire rows and bind them to their lowest served watermark. */
+   * @returns a title-only block at the stored title row's watermark, or
+   *   `undefined` when the record is current, newer, unrelated, missing, or
+   *   incompatible with the title unit.
+   */
+  cachedPredecessorTitle(meta: SessionHeader): ProjectionSnapshot | undefined;
+  /**
+   * View selected wire rows as one block bound to the lowest served
+   * watermark: the seq every served value has folded through at least. The
+   * number is the record's own; whether a consumer may compare it with a
+   * live Session's seqs is decided by the face that serves the block, not
+   * here.
+   */
   private viewRecord;
   /**
    * Hydrate projection cells for an already-prepared Session without another
@@ -3033,6 +3041,34 @@ 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).
+ */
+interface SessionActivityKindMap {}
+/** One activity family key. */
+type SessionActivityKind = keyof SessionActivityKindMap;
+/** One active item of a family that has per-item identity. */
+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.
+ */
+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
@@ -3134,12 +3170,17 @@ type WorkspaceRecord = output<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.
  */
 declare const workspaceDomainState: ZodObject<{
   initialized: ZodBoolean;
+  defaultWorkspaceId: ZodOptional<ZodPipe<ZodString, ZodTransform<WorkspaceId$1, string>>>;
   workspaceIds: ZodArray<ZodPipe<ZodString, ZodTransform<WorkspaceId$1, string>>>;
   archivedSessionIds: ZodDefault<ZodArray<ZodPipe<ZodString, ZodTransform<SessionId, string>>>>;
+  pinnedSessionIds: ZodDefault<ZodArray<ZodPipe<ZodString, ZodTransform<SessionId, string>>>>;
   pendingMutation: ZodOptional<ZodDiscriminatedUnion<[ZodObject<{
     operation: ZodLiteral<"create">;
     workspaceId: ZodPipe<ZodString, ZodTransform<WorkspaceId$1, string>>;
@@ -3160,10 +3201,52 @@ type WorkspaceId = WorkspaceId$1;
  * @returns the same string, branded at compile time.
  */
 declare function WorkspaceId(id: string): WorkspaceId;
+/** The session an archive request is about to write into the archive set. */
+interface SessionActivityRequest {
+  readonly sessionId: SessionId;
+}
+/** Caller choices for {@link WorkspaceRegistry.archiveSession}. */
+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
@@ -3198,6 +3281,20 @@ 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.
@@ -3238,11 +3335,21 @@ 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
@@ -3254,6 +3361,29 @@ 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
@@ -3261,6 +3391,8 @@ 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
@@ -3326,6 +3458,8 @@ interface StorageRepository {
 declare class WriteGuard {
   private readonly headSeqs;
   confirmHead(id: SessionId, head: number): void;
+  /** 本实例有没有这条会话的 head 记录（迁移重写用它决定是"登记基准"还是"严格比较"）。 */
+  has(id: SessionId): boolean;
   assertNoConcurrentWriter(id: SessionId, storedHead: number): void;
 }
 //#endregion
@@ -3359,6 +3493,36 @@ declare function eventDimensions(event: SessionEvent): {
   actionId: string;
 };
 //#endregion
+//#region src/rows.d.ts
+/**
+ * 管理面的会话列表：**我们自己的**一条路由（完整语料，含归档），与官方 `session/list` 分开。
+ *
+ * 官方那条（`session/list` → `ctx.sessionQuery.listSessions`）按部署策略默认排除已归档——那是给上游
+ * UI 用的。归档集的管理动作要有完整列表，所以这里单独给一条：标题直接从会话列取，最后活动时间用
+ * 该会话最后一个事件的时间。
+ */
+declare const SESSION_ROWS_PATH = "/api/session.rows";
+interface SessionRowsItem {
+  sessionId: string;
+  title: string | null;
+  /** 会话 header 的 origin（`subagent` 表示子代理会话）。 */
+  origin: string | null;
+  cwd: string | null;
+  createdAt: number;
+  /** 最后一个事件的时间（无事件时等于 `createdAt`）。 */
+  updatedAt: number;
+  archived: boolean;
+  /** 所属工作区标题；不属于任何工作区时为 null。 */
+  workspace: string | null;
+}
+interface SessionRowsValue {
+  items: SessionRowsItem[];
+  /** 过滤后的总数（分页前），前端据此算页数。 */
+  total: number;
+  page: number;
+  pageSize: number;
+}
+//#endregion
 //#region src/branch.d.ts
 declare function locateTurnEnd(events: readonly SessionEvent[], atSeq?: number, mode?: BranchAnchorMode): number;
 interface LiveSessionHooks {
@@ -3434,6 +3598,8 @@ interface SessionPersistenceRdbInternals {
   listSnapshots(signal?: AbortSignal): Promise<SessionPersistenceSnapshot[]>;
   readStoredRevision(id: SessionId, signal?: AbortSignal): Promise<import("@deepseek-ai/dsh-session-persistence").SessionPersistenceRevision | undefined>;
   registerReuseEventIds(childId: SessionId, map: ReadonlyMap<number, string>): void;
+  /** fork 失败时丢弃还没被消费的映射。 */
+  dropReuseEventIds(childId: SessionId): void;
 }
 interface ProjectionCacheOptions {
   writeEveryEvents?: number;
@@ -3527,7 +3693,6 @@ declare class SessionPersistenceRdb extends SessionPersistence {
   config: Config$1;
   static inject: string[];
   static Config: z<Config$1>;
-  static readonly settingsNs = "session-rdb";
   readonly name = "session-rdb";
   readonly tracker: RdbBackendTracker;
   private readonly backend;
@@ -3598,6 +3763,8 @@ declare class SessionPersistenceRdb extends SessionPersistence {
   }>;
   close(): Promise<void>;
   registerReuseEventIds(childId: SessionId, map: ReadonlyMap<number, string>): void;
+  /** 丢弃一个还没被消费的复用映射（fork 失败时）：留着会让同一个 childId 之后的落写复用父会话的事件行。 */
+  dropReuseEventIds(childId: SessionId): void;
   internals(): SessionPersistenceRdbInternals;
   private rowRevision;
   private readonly liveFailures;
@@ -3666,9 +3833,12 @@ interface SessionRow {
   fSeedLength: number | null;
   fOrigin: string | null;
   fDelegationDepth: number | null;
+  fAgentPreset: string | null;
   fIncarnation: string;
   fRevision: number;
   fArchivedAt: number | null;
+  fPinnedSeq: number | null;
+  fLastEventAt: number | null;
 }
 interface EventInsert {
   fEventId: string;
@@ -3708,7 +3878,8 @@ interface BackendTx {
     fSurfaceOp: string | null;
   }>): Promise<void>;
   updateHead(id: SessionId, headEventId: string, headSequence: number): Promise<void>;
-  bumpRevision(id: SessionId): Promise<void>;
+  /** 写批次提交时递增 revision；给了 `lastEventAt` 就一并把「最后活动时间」往前推（只增不减）。 */
+  bumpRevision(id: SessionId, lastEventAt?: number): Promise<void>;
   deleteBridgeTail(id: SessionId, fromSequence: number): Promise<void>;
   getPrevBridge(id: SessionId, sequence: number): Promise<{
     fEventId: string;
@@ -3718,6 +3889,39 @@ interface BackendTx {
   /** 批量删除整条会话：桥接行、workspace 归属行、投影行与会话行。 */
   deleteSessions(ids: SessionId[]): Promise<number>;
 }
+/**
+ * 「会话行」列表项：管理面自己的列表用（完整语料，含归档）+ 标题 + 最后活动时间。
+ *
+ * 与官方列表（`session/list` → `ctx.sessionQuery.listSessions`）的区别：那条按部署策略**默认排除归档**，
+ * 这里给的是完整集合，标题也直接带出来（官方那条的标题走投影缓存）。
+ */
+interface SessionListRowRecord {
+  sessionId: string;
+  title: string | null;
+  origin: string | null;
+  cwd: string | null;
+  createdAt: number;
+  /** 该会话最后一个事件的时间（没有事件时回落 `createdAt`）。 */
+  updatedAt: number;
+  archived: boolean;
+  subagent: boolean;
+  /** 所属工作区标题；不属于任何工作区时为 null。 */
+  workspace: string | null;
+}
+/** 会话行列表的查询条件：搜索、子代理过滤与分页都在后端做（前端分页等于每次拉全量）。 */
+interface SessionListRowsQuery {
+  /** 匹配标题或所属工作区标题（大小写不敏感）；空串即不过滤。 */
+  query?: string;
+  /** 是否连子代理派生会话一起返回（默认不含）。 */
+  includeSubagents?: boolean;
+  limit?: number;
+  offset?: number;
+}
+interface SessionListRowsPage {
+  items: SessionListRowRecord[];
+  /** 过滤后的总数（分页前的），前端据此算页数。 */
+  total: number;
+}
 /** 活动计数的一个桶：本地日 + 事件类型 + 计数。 */
 interface EventCountBucket {
   day: string;
@@ -3745,6 +3949,8 @@ interface Backend {
    * @param sinceMs - 只算该时刻（含）之后的事件行；省略即全量。
    */
   usageReport(sinceMs?: number): Promise<UsageAggregate>;
+  /** 管理面的会话行列表：完整语料（含归档）+ 标题 + 最后活动时间，按活动倒序分页。 */
+  listSessionRows(query?: SessionListRowsQuery): Promise<SessionListRowsPage>;
   /**
    * 活动计数**旁路累加**（派生表 `t_event_counts`，不参与写事务、失败可丢——表可销毁重建）：
    * 每个 (会话, 本地日, 事件类型) 记一行计数。
@@ -3764,4 +3970,4 @@ interface Backend {
   close(): Promise<void>;
 }
 //#endregion
-export { tSessionEvents as A, SESSION_PERSISTENCE_SQLITE_APPLICATION_ID as C, tEvents as D, tEventUsage as E, tWorkspaceState as F, tWorkspaces as I, WriteGuard as L, tSessions as M, tStorageUnits as N, tPersistenceState as O, tWorkspaceSessions as P, StorageRepository as R, SCHEMA_VERSION as S, eventKind as T, DEFAULT_BUSY_TIMEOUT_MS as _, SessionRow as a, EventRole as b, ProjectionCacheOptions as c, SessionPersistenceRdb as d, SessionPersistenceRdbInternals as f, truncateLiveSession as g, locateTurnEnd as h, EventRow as i, tSessionProjcacheRows as j, tSchemaMeta as k, SessionDeletionError as l, SessionBranchRdbProvider as m, BackendTx as n, UsageAggregate as o, SessionBranchRdb as p, EventCountBucket as r, Config$1 as s, Backend as t, SessionDeletionErrorCode as u, EVENT_ENCODING as v, eventDimensions as w, JournalMode as x, EventKind as y };
+export { eventKind as A, tWorkspaceState as B, EVENT_ENCODING as C, SCHEMA_VERSION as D, JournalMode as E, tSessionEvents as F, WriteGuard as H, tSessionProjcacheRows as I, tSessions as L, tEvents as M, tPersistenceState as N, SESSION_PERSISTENCE_SQLITE_APPLICATION_ID as O, tSchemaMeta as P, tStorageUnits as R, DEFAULT_BUSY_TIMEOUT_MS as S, EventRole as T, StorageRepository as U, tWorkspaces as V, locateTurnEnd as _, SessionListRowsPage as a, SessionRowsItem as b, UsageAggregate as c, SessionDeletionError as d, SessionDeletionErrorCode as f, SessionBranchRdbProvider as g, SessionBranchRdb as h, EventRow as i, tEventUsage as j, eventDimensions as k, Config$1 as l, SessionPersistenceRdbInternals as m, BackendTx as n, SessionListRowsQuery as o, SessionPersistenceRdb as p, EventCountBucket as r, SessionRow as s, Backend as t, ProjectionCacheOptions as u, truncateLiveSession as v, EventKind as w, SessionRowsValue as x, SESSION_ROWS_PATH as y, tWorkspaceSessions as z };