refactor(session): exclude live-session registry foundation
This commit is contained in:
Turtle
@@ -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 .agents/notes/implemented/feature/2026-07-28-cross-workspace-resume.md
|
||||
2026-07-28-cross-workspace-resume.md: d559b73a5ba0f8136d20ef6dcf7c62989d1527e9
|
||||
2026-07-28-cross-workspace-resume.zh.md: 404b81cbc07a455e5553a9c227d663e491456c9e
|
||||
2026-07-28-cross-workspace-resume.md: be455496346b9242585c1aace18f4f55cba905c0
|
||||
2026-07-28-cross-workspace-resume.zh.md: 0384cf204e51e4086b05c75e691f59d6b60a7d11
|
||||
|
||||
@@ -43,7 +43,6 @@ The shared base states that precedence in the row itself: `apps/cli/base.cordis.
|
||||
## Consequences
|
||||
|
||||
- Sessions already stored under a project-local `./.sessions` disappear from `/resume`. This is the accepted cost of no migration.
|
||||
- One shared root makes the pre-existing absence of a cross-process session lock reachable in one step: colliding used to require two terminals in the same directory, and is now one Tab away. `record.live` comes from the in-process `SessionQueryService`, so preflight rejects only sessions live in *this* runtime, while the JSONL backend takes no lock and two processes appending one log with independent `seq` counters would interleave. Closing this is no longer speculative hardening: `SessionRegistry.list()` already publishes live sessions cross-process under the same Harness home for `dsh list-sessions`, so consulting it in `summarizeResumeCandidate` is a small follow-up. It stays out of this change as pre-existing scope.
|
||||
- A resumed session can change the process's working directory, so a foreign resume is not a pure transcript restoration — every path-resolving tool moves with it.
|
||||
- The Harness home now holds session logs for every project on the machine. Its growth is no longer bounded by one checkout, and no retention policy is introduced here.
|
||||
|
||||
|
||||
@@ -43,7 +43,6 @@ dsh 启动器通过启动槽位提供其 Harness home 下的同一个会话根
|
||||
## Consequences
|
||||
|
||||
- 已经存放在项目本地 `./.sessions` 下的会话会从 `/resume` 中消失。这是不做迁移所接受的代价。
|
||||
- 同一个共享根目录让原本就缺失的跨进程会话锁一步之内即可触达：过去要造成冲突需要在同一个目录里开两个终端，如今只差一次 Tab。`record.live` 来自进程内的 `SessionQueryService`，因此预检只会拒绝在*本*运行时中处于活跃状态的会话，而 JSONL 后端不加任何锁，两个进程用各自独立的 `seq` 计数器追加同一份日志会互相交错。解决这一点已不再是投机性加固：`SessionRegistry.list()` 已经为 `dsh list-sessions` 在同一个 Harness home 下跨进程发布活跃会话，因此在 `summarizeResumeCandidate` 中查询它是一项小的后续工作。它作为既有范围之外的问题不纳入本次改动。
|
||||
- 恢复一个会话可以改变进程的工作目录，因此恢复外部会话不是单纯的 transcript 还原——每个解析路径的工具都会随之移动。
|
||||
- Harness home 现在保存着这台机器上每个项目的会话日志。它的增长不再受单个 checkout 约束，而本记录也没有引入任何保留策略。
|
||||
|
||||
|
||||
@@ -1,6 +0,0 @@
|
||||
# Bilingual-pair consistency record (docs/i18n/README.md): the git blob hash of each
|
||||
# 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 .agents/notes/implemented/feature/2026-07-28-live-session-registry-and-dsh-ls.md
|
||||
2026-07-28-live-session-registry-and-dsh-ls.md: 02343c83ccee7b67e3b3e4c72de842415d4a9f6e
|
||||
2026-07-28-live-session-registry-and-dsh-ls.zh.md: 722ac45f2eb07256f196d2828b8969ae9f4965b8
|
||||
@@ -1,65 +0,0 @@
|
||||
# Agent Note: live-session registry and `dsh list-sessions`
|
||||
|
||||
Status: implemented
|
||||
|
||||
English | [中文](2026-07-28-live-session-registry-and-dsh-ls.zh.md)
|
||||
|
||||
## Problem
|
||||
|
||||
Nothing could answer "which dsh sessions am I running right now". A user with sessions across several projects had no way to enumerate them, and no way to recover the id needed for `--resume` except the exit line of the terminal that printed it. Session persistence records every session that ever existed, so it cannot answer the question: it has no notion of liveness, and no `process.pid` appeared anywhere in the session, persistence, or storage packages.
|
||||
|
||||
## Decision
|
||||
|
||||
`dsh list-sessions` (alias `dsh ps`) lists the sessions running right now — session id, pid, uptime, workspace, title — newest first, across every workspace, with `--json` for machines. Three packages back it, as a capability seam.
|
||||
|
||||
[`dsh-session-registry`](../../../../packages/session-registry/session-registry/README.md) (`ctx.sessionRegistry`) is the seam: the abstract service contract and record vocabulary, so the medium can later move to a database without touching consumers. [`dsh-session-registry-file`](../../../../packages/session-registry/session-registry-file/README.md) implements it over one lock-guarded JSON file under the Harness home. [`dsh-session-registry-live`](../../../../packages/session-registry/session-registry-live/README.md) follows `session/created`, `session/disposed`, and `session/title` and keeps the registry in step. `apps/cli` mounts both on every launcher surface — the TUI, `dsh meta`, headless, and web — and `dsh list-sessions` mounts only the service, booting no agent tree. No surface label is recorded: a launcher's mode is not a property of the session, and the workspace column already distinguishes a `dsh meta` session from a project one.
|
||||
|
||||
### Liveness is derived, never stored
|
||||
|
||||
`list()` probes each record's pid with `kill(pid, 0)` and drops the dead ones, writing the pruned result back. A process killed without running its disposer leaves a record that the next read removes, so there is no daemon, no heartbeat, and no permanent phantom. A per-process `bootId` distinguishes a recycled pid, so deregistration cannot delete a namesake record from a different incarnation. `EPERM` counts as alive: a live session owned by another user must not be dropped.
|
||||
|
||||
### Two independent concurrency layers
|
||||
|
||||
The file is written by every dsh process and by several sessions inside one process, and the two cases need different mechanisms.
|
||||
|
||||
Across processes, each read-modify-write holds a [`proper-lockfile`](https://github.com/moxystudio/node-proper-lockfile) advisory lock. Within one process, calls queue on an internal chain, because the advisory lock is tracked per process: overlapping same-process callers contend for its bounded retry budget rather than queueing, and past roughly a dozen concurrent calls that budget runs out and a registration rejects. Since publication is fire-and-forget, such a rejection silently drops a live session from the listing — the exact "listing that lies" failure this feature exists to avoid. Both layers are load-bearing and each is pinned by a test that fails without it.
|
||||
|
||||
### Records carry their own title
|
||||
|
||||
The title is the one mutable field, replaced through `retitle` as `session/title` events arrive. It lives in the record rather than being read from the session log because the log's location, format, and compression are per-deployment backend choices: the TUI writes project-local zstd-compressed JSONL, the web and headless surfaces write to a global root, a user profile overrides either, and SQLite has no per-session file at all. An independent reader cannot portably parse that, so `dsh list-sessions` opens no log and assumes no backend.
|
||||
|
||||
### Subagents are invisible by construction
|
||||
|
||||
Only top-level launcher surfaces mount the publisher. In-process subagents (`spawn`, `fork`) have no process of their own, and the out-of-process backends spawn `dsh-jsonrpc-agent` rather than this CLI. No filter flag is needed, and no subagent package changed.
|
||||
|
||||
## Alternatives considered
|
||||
|
||||
**One file per session under `~/.dsh/run/`.** No lock at all, since each process only writes and deletes its own file. Rejected in favour of the single file the user chose, which then made a real advisory lock mandatory rather than optional.
|
||||
|
||||
**A domain over the `storage-json` backend.** The obvious reuse, and wrong: that backend documents "no cross-process write locking … last write wins" and names single-host-process as its assumption, and the [domain KV storage note](../../proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md) puts multi-process explicitly out of scope. A registry written concurrently by every launcher is precisely that excluded case. Widening the backend's contract would have changed a shipped guarantee for one consumer; a separate package owns the multi-process medium instead.
|
||||
|
||||
**Hand-rolled `O_EXCL` lock directory.** Rejected under the [dependencies-over-hand-rolling policy](../process/2026-07-26-dependencies-over-hand-rolling.md): stale-lock detection, retry backoff, and compromise handling are exactly the surface a maintained dependency should own.
|
||||
|
||||
**Accept last-write-wins on the single file.** Cheapest to build, and it silently omits real running sessions when two start close together. A listing tool that lies is worse than no listing tool.
|
||||
|
||||
**Read the title from the session log in `dsh list-sessions`.** Implemented first, then verified live: the shipped TUI writes `session.jsonl.zstd`, whose frame helpers are internal to the jsonl backend. Exporting them would have hard-coded one backend's file format into the CLI and still shown nothing for SQLite.
|
||||
|
||||
**Register the web server itself with a placeholder session id.** `dsh web` owns no session — its sessions are created later by browser clients — so a server row would have put a fake id in a session table. Following session lifecycle instead makes browser sessions appear and disappear as they are opened, which also subsumed the TUI's launcher-side registration and deleted that separate path.
|
||||
|
||||
**A `--here`/`--workspace` filter.** Dropped on request: the listing is always global, and narrowing is the user's `grep`.
|
||||
|
||||
## Consequences
|
||||
|
||||
The registry is an observability aid, so every write is best-effort: a registry fault warns and never fails a working agent session. The cost is that a listing can lag reality by one failed write, healed by the next.
|
||||
|
||||
Title mirroring costs one locked read-modify-write per revision, so an aggressive retitling cadence pays that write each time.
|
||||
|
||||
`bootId` bounds pid reuse only for records this process wrote. A foreign record whose pid the operating system has reassigned to an unrelated live process is reported alive until its owner removes it — accepted because the portable alternative, reading real process start times, is `/proc`-only.
|
||||
|
||||
Liveness is pid existence, not health: a hung process still lists as running. The registry deliberately makes no progress judgement.
|
||||
|
||||
## Testing
|
||||
|
||||
Unit coverage pins durable-format validation (torn text, foreign version, per-row damage that must not hide siblings), pid pruning against a genuinely reaped pid, `EPERM`-is-alive, incarnation-scoped deregistration, and `retitle` scoping. Both concurrency layers have a regression test verified to fail when its mechanism is removed: 8 real processes for the cross-process lock, 24 overlapping in-process calls for the chain. The publisher is tested over the real `SessionStore` rather than a hand-built emitter, because publication depends on the store's actual lifecycle dispatch.
|
||||
|
||||
Verified live in tmux against the assembled application: two concurrent TUI sessions in different workspaces both listed, a title appeared after the first turn, clean exit deregistered, and `SIGKILL` left a stale record that the next `dsh list-sessions` pruned and durably rewrote.
|
||||
@@ -1,65 +0,0 @@
|
||||
# Agent Note: 活跃会话注册表与 `dsh list-sessions`
|
||||
|
||||
Status: implemented
|
||||
|
||||
[English](2026-07-28-live-session-registry-and-dsh-ls.md) | 中文
|
||||
|
||||
## 问题
|
||||
|
||||
没有任何东西能回答「我此刻正在运行哪些 dsh 会话」。会话散落在多个项目中的用户既无法枚举它们，也无法找回 `--resume` 所需的 id，唯一的来源是打印过它的那个终端的退出行。会话持久化记录了曾经存在过的每个会话，因此它答不了这个问题：它没有存活状态的概念，而且 session、persistence、storage 这几个包里任何位置都没有出现过 `process.pid`。
|
||||
|
||||
## 决策
|
||||
|
||||
`dsh list-sessions`（别名 `dsh ps`）列出此刻正在运行的会话（会话 id、pid、运行时长、工作区、标题），最新的排在最前，覆盖所有工作区，并提供面向机器的 `--json`。背后由三个包（package）以能力 seam 的形式支撑。
|
||||
|
||||
[`dsh-session-registry`](../../../../packages/session-registry/session-registry/README.md)（`ctx.sessionRegistry`）是 seam：抽象服务契约与记录词汇，使介质将来可以换成数据库而不触及消费方。[`dsh-session-registry-file`](../../../../packages/session-registry/session-registry-file/README.md) 在 Harness home 下的一个加锁保护的 JSON 文件上实现它。[`dsh-session-registry-live`](../../../../packages/session-registry/session-registry-live/README.md) 跟随 `session/created`、`session/disposed` 和 `session/title`，让注册表保持同步。`apps/cli` 在每个启动方接口（TUI、`dsh meta`、headless、web）上都挂载这两个包，而 `dsh list-sessions` 只挂载该服务，不启动任何 agent（智能体）树。不记录任何接口标签：启动方的模式并不是会话的属性，而工作区那一列已经能把 `dsh meta` 会话和项目会话区分开。
|
||||
|
||||
### 存活状态是推导出来的，绝不存储
|
||||
|
||||
`list()` 用 `kill(pid, 0)` 探测每条记录的 pid，剪除已消亡的记录，并把剪除后的结果写回。未运行 disposer（资源释放）就被杀掉的进程留下的记录，会被下一次读取移除，因此不需要 daemon，不需要心跳，也不会有永久残留的幽灵记录。每个进程独有的 `bootId` 用于区分被复用的 pid，因此注销不会删除属于另一个 incarnation 的同名记录。`EPERM` 算作存活：归属于另一个用户的存活会话绝不能被丢掉。
|
||||
|
||||
### 两层相互独立的并发机制
|
||||
|
||||
该文件既被每个 dsh 进程写入，也被同一进程内的多个会话写入，这两种情形需要不同的机制。
|
||||
|
||||
跨进程时，每次读-改-写都持有一个 [`proper-lockfile`](https://github.com/moxystudio/node-proper-lockfile) 咨询锁。进程内则由各次调用在内部链上排队，因为咨询锁是按进程跟踪的：同一进程中重叠的调用方会争抢它有界的重试预算，而不是排队等待；大约超过十几次并发调用后，该预算耗尽，某次注册就会被拒绝。由于发布采用 fire-and-forget 方式，这样一次拒绝会静默地把一个存活会话从列表中丢掉——而这正是本功能要避免的「列表说谎」故障。两层机制都是必需的，且各有一个测试固定它：移除该机制，对应测试就会失败。
|
||||
|
||||
### 记录自带标题
|
||||
|
||||
标题是唯一的可变字段，随 `session/title` 事件到达，通过 `retitle` 替换。它存放在记录里，而不是从会话日志读取，因为日志的位置、格式和压缩都是逐部署的后端选择：TUI 写入项目本地的 zstd 压缩 JSONL，web 与 headless 界面写入全局根目录，用户配置文件可以覆盖二者，而 SQLite 根本没有逐会话的文件。独立读取方无法以可移植的方式解析这些内容，因此 `dsh list-sessions` 不打开任何日志，也不假定任何后端。
|
||||
|
||||
### subagent 在设计上就不可见
|
||||
|
||||
只有顶层启动方接口才挂载发布方。进程内 subagent（`spawn`、`fork`）没有自己的进程，而进程外后端 spawn 的是 `dsh-jsonrpc-agent` 而不是本 CLI（命令行界面）。不需要任何过滤开关，也没有改动任何 subagent 包。
|
||||
|
||||
## 考虑过的替代方案
|
||||
|
||||
**在 `~/.dsh/run/` 下每个会话一个文件。** 完全不需要锁，因为每个进程只写入和删除自己的文件。不予采纳，改用用户选定的单文件方案，而这也使真正的咨询锁从可选变为必需。
|
||||
|
||||
**在 `storage-json` 后端之上做一个 domain。** 这是最显而易见的复用，但它是错的：该后端明确记载「无跨进程写锁……最后写入者胜出」，并把单一宿主进程列为自身前提，而[domain KV 存储 note](../../proposed/architecture/2026-07-24-domain-kv-storage-and-workspace.md)明确把多进程排除在范围之外。被每个启动方并发写入的注册表恰恰就是这个被排除的场景。放宽该后端的契约，等于为一个消费方改动一项已上线的保证；改由一个独立的包拥有这套多进程介质。
|
||||
|
||||
**手写 `O_EXCL` 锁目录。** 依据[优先使用依赖而非手写政策](../process/2026-07-26-dependencies-over-hand-rolling.md)不予采纳：陈旧锁检测、重试退避和受损处理，恰恰是应当由一个有人维护的依赖拥有的那部分工作。
|
||||
|
||||
**在单文件上接受最后写入者胜出。** 这是最省事的实现，但当两个会话相近时间启动时，它会静默漏掉真实运行中的会话。一个会说谎的列表工具比没有列表工具更糟。
|
||||
|
||||
**在 `dsh list-sessions` 中从会话日志读取标题。** 该方案先落地实现，随后经实机验证否决：上线的 TUI 写入 `session.jsonl.zstd`，其帧处理辅助函数是 jsonl 后端的内部实现。把它们导出，等于把某一个后端的文件格式硬编码进 CLI，而且对 SQLite 仍然什么都显示不出来。
|
||||
|
||||
**用占位会话 id 注册 web 服务器本身。** `dsh web` 不拥有任何会话（它的会话由浏览器客户端稍后创建），因此一行服务器记录会把一个假 id 放进会话表。改为跟随会话生命周期后，浏览器会话会随打开与关闭而出现和消失，这同时也涵盖了 TUI 启动方一侧的注册，并删除了那条独立路径。
|
||||
|
||||
**加一个 `--here`/`--workspace` 过滤开关。** 按要求放弃：列表始终是全局的，收窄范围交给用户自己的 `grep`。
|
||||
|
||||
## 后果
|
||||
|
||||
注册表是一项可观测性辅助设施，因此每次写入都是尽力而为：注册表故障只发出警告，绝不让正常工作的 agent 会话失败。代价是列表可能因一次失败的写入而落后于现实一步，并由下一次写入修复。
|
||||
|
||||
标题镜像每次修订都要付出一次加锁的读-改-写，因此改名节奏激进时，每次改名都要付出这一次写入。
|
||||
|
||||
`bootId` 只对本进程写入的记录约束 pid 复用。如果一条外来记录的 pid 已被操作系统重新分配给一个无关的存活进程，那么在其所有者移除它之前，该记录会被报告为存活——之所以接受，是因为可移植的替代方案（读取进程真实启动时间）仅在 `/proc` 上可用。
|
||||
|
||||
存活状态只表示 pid 存在，不表示健康：挂死的进程仍会被列为正在运行。注册表刻意不对进展作出判断。
|
||||
|
||||
## 测试
|
||||
|
||||
单元覆盖固定了持久格式校验（截断文本、外来版本、不得遮蔽同级记录的单条损坏）、针对真正已回收 pid 的剪除、`EPERM` 算存活、按 incarnation 限定范围的注销，以及 `retitle` 的作用范围。两层并发机制各有一个回归测试，且都已验证在移除对应机制后会失败：跨进程锁用 8 个真实进程，进程内链用 24 次重叠调用。发布方在真实的 `SessionStore` 上测试，而非手搭的事件发射器，因为发布依赖该 store 实际的生命周期派发。
|
||||
|
||||
已在 tmux 中针对组装后的应用实机验证：位于不同工作区的两个并发 TUI 会话都被列出，第一轮之后出现标题，正常退出完成注销，而 `SIGKILL` 留下的陈旧记录被下一次 `dsh list-sessions` 剪除并持久重写。
|
||||
Reference in New Issue
Block a user