refactor(persistence): group sessions in project directories

.agents/notes/implemented/architecture/2026-07-24-project-session-directories.i18n.yaml

@@ -0,0 +1,6 @@
+# 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
+2026-07-24-project-session-directories.md: f65045419d5c749525ebdefcd1875dfc8ea69182
+2026-07-24-project-session-directories.zh.md: 1b4320d925c85b9b42a6c3ec9ee4ec52f4600786

.agents/notes/implemented/architecture/2026-07-24-project-session-directories.md

@@ -0,0 +1,48 @@
+# Agent Note: Project-grouped session directories
+
+Status: implemented
+
+English | [中文](2026-07-24-project-session-directories.zh.md)
+
+## Problem
+
+A persistence root may be local to one project, shared by several projects, temporary, or centralized. The hashed cwd buckets kept all deployments functional but made a shared root difficult to navigate because a developer could not recognize a project from its directory name.
+
+Each JSONL session also occupied one file directly inside the project bucket. That shape had no ownership directory for additional session artifacts such as metadata, attachments, spill files, or coordination state.
+
+## Decision
+
+The JSONL backend stores sessions under a readable project key and gives every session its own directory:
+
+```text
+<configured-root>/
+  --<normalized-cwd>--<hash>/
+    <encoded-session-id>/
+      session.jsonl.zstd
+```
+
+Raw mode uses `session.jsonl`, and sessions without a cwd use `_no-cwd`. Filesystem and drive separators become `-`, unsafe code units use `~XXXX`, and the readable prefix is bounded to keep the component within filesystem limits. A short SHA-256 suffix distinguishes project paths whose readable forms collide or truncate alike.
+
+The configured root remains a deployment choice. The layout neither selects a global root nor requires projects to share one. When a deployment does centralize storage, project paths remain recognizable; a project-local root uses the same deterministic structure.
+
+The encoded session id names an ownership directory rather than the transcript itself. `SessionPersistence.locate()` continues to return the fixed transcript path, preserving hook `transcript_path` and `DSH_SESSION_JSONL` semantics. Discovery ignores other entries inside the session directory so the backend can add session-owned artifacts without another layout change.
+
+Lazy materialization remains tied to the transcript: `create()` performs no filesystem I/O, and the first append creates the project/session directories before collision-safe transcript publication. Empty directories are not listed as sessions. The backend rejects flat `<project>/<id>.jsonl*` artifacts with an explicit layout error; the pre-release format provides no automatic data migration.
+
+## Alternatives considered
+
+**Keep opaque cwd hashes.** This preserved short names but defeated the requested navigation by project path when several projects share a persistence root.
+
+**Put session files directly in each project directory.** This matched Claude Code and pi's basic file organization but left no session-level ownership boundary for future artifacts.
+
+**Replace separators without a collision suffix.** This is readable but lossy: paths containing literal `-` can collide with paths where `-` represents a separator. Retaining a short hash suffix preserves readable navigation without merging distinct projects.
+
+**Mandate a centralized root.** Rejected because storage placement belongs to deployment configuration. Project grouping is useful when roots are shared and harmless when they are not.
+
+**Load both flat and directory layouts.** Rejected under the pre-release no-compatibility stance. One accepted layout keeps identity checks and discovery deterministic.
+
+## Consequences
+
+Shared stores can be navigated by recognizable project names, while local and custom roots keep their existing configuration freedom. Every session has a directory available for future backend-owned artifacts, and existing transcript consumers still receive a file path.
+
+Project directory names are longer than the former 12-hex cwd hashes. Very long paths show only a bounded prefix plus their distinguishing hash, and moving a project still selects a different directory because the absolute cwd remains part of storage identity.

.agents/notes/implemented/architecture/2026-07-24-project-session-directories.zh.md

@@ -0,0 +1,48 @@
+# Agent Note: 按项目分组的会话目录
+
+Status: implemented
+
+[English](2026-07-24-project-session-directories.md) | 中文
+
+## 问题
+
+持久化根目录可以只供一个项目使用，也可以由多个项目共享，还可以是临时目录或集中式目录。对 cwd 进行哈希得到的分桶目录能适用于所有这些部署方式，但开发者无法从目录名辨认项目，因此共享根目录难以浏览。
+
+每个 JSONL 会话也直接以单个文件的形式放在项目分桶目录中。这种布局没有为元数据、附件、溢写文件或协调状态等其他会话产物提供归属目录。
+
+## 决策
+
+JSONL 后端按可读的项目键存储会话，并为每个会话提供独立目录：
+
+```text
+<configured-root>/
+  --<normalized-cwd>--<hash>/
+    <encoded-session-id>/
+      session.jsonl.zstd
+```
+
+原始模式使用 `session.jsonl`，没有 cwd 的会话使用 `_no-cwd`。文件系统路径分隔符和驱动器分隔符会转换为 `-`，不安全的代码单元使用 `~XXXX`，可读前缀则限制长度，以确保目录项不超过文件系统限制。短 SHA-256 后缀用于区分可读形式发生冲突或被截断成相同形式的项目路径。
+
+根目录由部署配置决定。这种布局既不选择全局根目录，也不要求项目共享根目录。部署选择集中存储时，目录名仍能让项目路径易于辨认；使用项目本地根目录时，也采用同样的确定性结构。
+
+编码后的会话 id 用于命名归属目录，而不是 transcript（文本记录）文件本身。`SessionPersistence.locate()` 仍返回固定的 transcript 路径，从而保持钩子 `transcript_path` 和 `DSH_SESSION_JSONL` 的语义不变。发现过程会忽略会话目录中的其他条目，因此后端以后添加会话自有产物时无需再次改变布局。
+
+延迟物化仍以 transcript 为界：`create()` 不执行文件系统 I/O，首次追加会先创建项目目录和会话目录，再以无冲突方式发布 transcript。空目录不会被列为会话。后端会显式报告布局错误并拒绝扁平的 `<project>/<id>.jsonl*` 产物；预发布格式不提供自动数据迁移。
+
+## 考虑过的替代方案
+
+**保留不透明的 cwd 哈希。** 这可以保持目录名简短，但当多个项目共享一个持久化根目录时，无法满足按项目路径浏览的需求。
+
+**把会话文件直接放入各项目目录。** 这与 Claude Code 和 pi 的基本文件组织一致，但没有为未来产物提供会话级归属边界。
+
+**替换分隔符但不添加冲突后缀。** 这种方式可读但有损：路径中的字面 `-` 可能与用 `-` 表示分隔符的路径发生冲突。保留短哈希后缀，既能让不同项目保持区分，又不会牺牲可读的浏览体验。
+
+**强制使用集中式根目录。** 不予采纳，因为存储位置属于部署配置。项目分组在根目录共享时有用，在不共享时也没有负面影响。
+
+**同时加载扁平布局和目录布局。** 按照预发布阶段不提供兼容性的原则，不予采纳。只接受一种布局，可以让身份检查和发现过程保持确定性。
+
+## 后果
+
+共享存储可以通过易于辨认的项目名进行浏览，本地根目录和自定义根目录则继续保有现有的配置自由。每个会话都有一个可供后端未来存放自有产物的目录，而现有 transcript 消费方仍会收到文件路径。
+
+项目目录名比原先由 12 个十六进制字符组成的 cwd 哈希更长。路径很长时，目录名只显示长度受限的前缀和用于区分的哈希；移动项目仍会选择不同的目录，因为绝对 cwd 仍是存储身份的一部分。