@deepseek-ai/dsh-spill-local 0.1.1-rc.2 → 0.1.2-alpha.2

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/spill/spill-local/README.md
-README.md: 2270a65d9270e1549a9e48d6a36b821e48c29070
-README.zh.md: b3e4999d8f2d982ef01637199299f79d06e12c4b
+README.md: 840e1dff3bf541636354e3a8dc3be619e0dd4cf4
+README.zh.md: 1f4ddf911ea11301c9ccb5520197debb95b02352

package/README.md

@@ -1,28 +1,117 @@
+---
+description: "The local filesystem spill backend: how spilled tool output is saved to private session-scoped files and retrieved with read or grep."
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-spill-local
 
 English | [中文](README.zh.md)
 
-The **local-filesystem** implementation of the [`@deepseek-ai/dsh-spill`](../spill) storage seam. Registers as `ctx.spillStore` and persists a tool's oversized text to a private, session-scoped file; its locator is the file path and its retrieval hint tells the model to use `read` or `grep` on that path.
+## Summary
+
+`dsh-spill-local` saves a tool's oversized text to a private, session-scoped file on the host filesystem and returns that file's path as the locator, with retrieval guidance telling the model to read or grep it. Mount it whenever a composition needs spill storage on the same machine the agent runs on. Files are private to the current user, names are unpredictable, and each session's files group under a stable directory, so a shared root cannot leak output or be redirected by a planted symlink. Configuration selects the root and the startup-cleanup retention period; previews and spill decisions live in other packages.
+
+## Table of Contents
+
+- [Use this package](#use-this-package)
+- [Understand the implementation](#understand-the-implementation)
+- [Further Exploration](#further-exploration)
+- [Model Experience](#model-experience)
+- [Known Limitations and Deferred Work](#known-limitations-and-deferred-work)
+- [Dev Note](#dev-note)
+
+-----
 
-## Storage layout
+<a id="use-this-package"></a>
+## Use this package
 
-Files land at `<root>/session-<hash>/​<random>-<safeName>`:
+Mount this backend in a composition that spills tool output to the local filesystem. It registers as the `ctx.spillStore` service that the `dsh-spill-policy` plugin and other callers use.
 
-- **`root`** — the config `root` (resolved to absolute), or a lazily-created private (0700) per-process directory under the OS temp dir when omitted. A predictable, world-readable root would let other local users read spilled tool output or plant symlinks.
-- **`session-<hash>`** — a short `sha256(sessionId)` prefix, so a session's spill files group together and a future cleanup can drop them per session.
-- **`<random>-<safeName>`** — an unpredictable hex prefix (defeats symlink planting in a shared root) plus the caller's `suggestedName` sanitized to one safe path segment (traversal-proof; mirrors the JSONL persistence backend's `encodeSegment`). The write is exclusive + owner-only (`open(path, 'wx', 0o600)`): it fails on any pre-existing path, symlink or not, so a planted target cannot redirect it.
+### Minimal configuration
 
-## Config
+Loading the plugin with no config is safe: files land in a lazily-created private (0700) per-process directory under the OS temp directory. Set `root` when the files must live under a known location.
 
-| Key | Default | Meaning |
+```yaml
+- name: '@deepseek-ai/dsh-spill-local'
+  config:
+    root: /absolute/path/to/spill
+    cleanupPeriodDays: 30
+```
+
+| Field | Default | Meaning |
 |---|---|---|
-| `root` | private 0700 temp dir | Root directory for spill files. Set to keep them under a known location. |
+| `root` | private 0700 temp dir | Root directory for spill files; set to keep them under a known location |
+| `cleanupPeriodDays` | `30` | File age in days before the one-shot startup cleanup may delete it; `0` disables cleanup |
+
+The generated [configuration catalog](../../../docs/config-catalog.md#deepseek-aidsh-spill-local) is the exhaustive source for every accepted field.
+
+### What you get back
+
+Each `saveText` call writes the full text to a fresh file and returns three fields: `locator` (the file path), `bytes` (the exact UTF-8 byte count), and `retrievalHint` — "Use read with offset/limit, or grep this path to search within it." A consumer shows that hint to the model, which can then read or search the file with its ordinary file tools.
+
+### Where files land
+
+Files are stored at `<root>/session-<hash>/<random>-<safeName>`, where `session-<hash>` is a short hash of the owning session id (so one session's files group together) and `<random>-<safeName>` pairs an unpredictable hex prefix with the caller's suggested name sanitized to one safe path segment. A relative `root` resolves from the process working directory.
+
+### Startup cleanup
+
+One best-effort sweep starts after activation without delaying service availability. It scans the configured root and prior default `dsh-spill-*` roots under the OS temp directory, deletes regular files whose modification time is strictly older than the configured cutoff, prunes empty session directories, and removes only empty prior-default roots. A long-lived process does not sweep again until restart. Disposal waits for the sweep, and a concurrent write recreates a session directory if cleanup removes it.
+
+The sweep resolves filesystem identities, never follows or deletes symlinks, and skips unrelated entries. On POSIX it admits only roots and session directories owned by the current user, not writable by group or others, and protected from replacement through their ancestor path; writable sticky temporary directories such as `/tmp` are permitted. Unsafe paths produce a warning and remain untouched. Filesystem and warning-sink failures are contained, so cleanup cannot fail activation or a concurrent spill write.
+
+### Failures and recovery
+
+A real storage failure — permissions, no space left, an unwritable root — rejects the `saveText` call; the caller decides how to degrade. The shipped policy treats the rejection as best-effort and keeps the original inline result.
+
+-----
+
+<a id="understand-the-implementation"></a>
+## Understand the implementation
+
+<details>
+<summary>Implementation internals — click to expand</summary>
+
+This section explains the design decisions behind the backend; the observable behavior is fully covered in [Use this package](#use-this-package).
 
-`saveText` rejects on a real storage failure (permissions, ENOSPC); the spill policy treats a rejection as best-effort and keeps the inline result. See the seam README for the vocabulary and the [tool output spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) for the design.
+### Design philosophy
 
+The backend owns storage details only, on one principle: **a spilled tool result must be private and unredirectable**. The root is private (0700), the session directory is a stable hash, the leaf name is unpredictable, and the write is exclusive and owner-only. The storage mechanics live in a Cordis-free module so they are unit-testable without a context.
+
+### Source map
+
+| File | Role |
+|---|---|
+| [`src/index.ts`](src/index.ts) | Plugin entry: `Config`, the `LocalSpillStore` service, cleanup lifecycle, locator and retrieval-hint assembly |
+| [`src/cleanup.ts`](src/cleanup.ts) | One-shot age sweep, filesystem-identity checks, symlink and ownership safeguards |
+| [`src/store.ts`](src/store.ts) | Cordis-free storage mechanics: private root, session directory, safe-name encoding, exclusive write |
+| [`src/invariant.ts`](src/invariant.ts) | Invariant companion (no runtime invariant; contracts are enforced at the seam) |
+
+### File naming and write
+
+`suggestedName` is untrusted input, so `encodeSegment` escapes every character outside `[A-Za-z0-9._-]` (and `~` itself) into a `~XXXX` form, making the mapping injective over all JS strings: separators, `../`, NUL, and absolute paths can never escape one segment, and the whole-segment tokens `.`/`..` are escaped too. The write is `open(path, 'wx', 0o600)` — it fails on any existing path, symlink or not, so a pre-planted target cannot redirect it. Two saves of the same suggested name get distinct random prefixes.
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## Further Exploration
+
+Read these pages when the package-level contract is not enough.
+
+- [Spill storage service](../spill/README.md) — the `saveText` contract and vocabulary this backend implements.
+- [Spill package map](../README.md) — the three-package family and each role.
+- [dsh-spill-policy](../spill-policy/README.md) — the policy that calls this backend when a result is too large.
+- [Spill subsystem](../../../docs/subsystems/spill.md) — the exhaustive vocabulary and ownership.
+- [Tool output spill decision](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.md) — the capability boundary and design rationale.
+- [Local spill startup cleanup](../../../.agents/notes/implemented/architecture/2026-07-17-local-spill-startup-cleanup.md) — retention, race handling, and safe deletion rules.
+
+-----
+
+<a id="model-experience"></a>
 ## Model Experience
 
-Indirectly, through spill consumers that render the local path and `read`/`grep` retrieval guidance.
+Indirectly, through spill consumers, which render the saved file path and read/grep retrieval guidance to the model.
 
 #### KV Cache effect
 
@@ -30,5 +119,24 @@ No direct invalidation; the named consumer owns any request-prefix changes.
 
 ## Known Limitations and Deferred Work
 
-- **Local spill files persist until external cleanup** — the backend has no session-lifecycle deletion or age-based retention policy, because persisted, resumed, and forked sessions may still reference a path.
+<a id="known-limitations-and-deferred-work"></a>
+
+
+These limits define when the local backend is a poor fit or needs operational care. They are current package constraints.
+
+- **A long-lived deployment is not swept until restart** — the one-shot sweep runs only after activation, so files that cross the age cutoff during a run are reclaimed on the next start.
 - **Locators require a co-located filesystem consumer** — a remote or virtual deployment needs another `SpillStore` backend whose locator and retrieval hint are meaningful there.
+
+<a id="dev-note"></a>
+### Dev Note
+
+<details>
+<summary>Working context for maintainers — click to expand</summary>
+
+This Dev Note is working context for maintainers: open directions. It is explicitly non-authoritative.
+
+#### Future: workspace-confinement interplay
+
+The retrieval model assumes the model's `read`/`grep` tools can inspect the returned path even when the spill directory is outside the session working directory. A future workspace-confinement policy must either allow local spill paths explicitly or use a non-file spill backend.
+
+</details>

package/README.zh.md

@@ -1,34 +1,142 @@
+---
+description: "本地文件系统 spill 后端：spill 工具输出如何保存到私有会话级文件，并用 read 或 grep 取回。"
+kind: "package-reference"
+---
+
 # @deepseek-ai/dsh-spill-local
 
 [English](README.md) | 中文
 
-[`@deepseek-ai/dsh-spill`](../spill) 存储 seam 的**本地文件系统**实现。它注册为 `ctx.spillStore`，将工具产生的过大文本持久化到私有的会话级文件；定位信息是文件路径，取回指引会告诉模型对该路径使用 `read` 或 `grep`。
+## 概述
+
+`dsh-spill-local` 把工具的超大文本保存到宿主文件系统中私有的会话级文件，并以该文件路径作为定位信息返回，同时给出告诉模型读取或搜索它的取回指引。只要组合需要在与 agent 相同的机器上进行 spill 存储，就挂载它。文件对当前用户私有、名称不可预测，且每个会话的文件归入稳定的目录，因此共享根目录既不会泄露输出，也不会被预置的符号链接重定向。配置选择根目录与启动清理保留期；预览与 spill 决策由其他包负责。
+
+## 目录
+
+- [使用本包](#use-this-package)
+- [理解实现](#understand-the-implementation)
+- [进一步探索](#further-exploration)
+- [模型体验](#model-experience)
+- [已知限制与延期工作](#known-limitations-and-deferred-work)
+- [开发备注](#dev-note)
+
+-----
 
-## 存储布局
+<a id="use-this-package"></a>
+## 使用本包
 
-文件存放在 `<root>/session-<hash>/​<random>-<safeName>`：
+在需要把工具输出 spill 到本地文件系统的组合中挂载此后端。它注册为 `dsh-spill-policy` 插件与其他调用方使用的 `ctx.spillStore` 服务。
 
-- **`root`**：使用配置中的 `root`（解析为绝对路径）；如果省略，则在操作系统临时目录下延迟创建每进程私有（0700）目录。可预测且任何用户均可读取的根目录会让其他本地用户读取 spill 工具输出，或在其中预置符号链接。
-- **`session-<hash>`**：截短的 `sha256(sessionId)` 前缀，用于将同一会话的 spill 文件归在一起，以便未来的清理操作可按会话删除。
-- **`<random>-<safeName>`**：不可预测的十六进制前缀（防止在共享根目录中预置符号链接），加上经过清理的调用方 `suggestedName`，使其成为单个安全路径段（防路径遍历；与 JSONL 持久化后端的 `encodeSegment` 一致）。写入操作采用排他方式，且权限仅限所有者（`open(path, 'wx', 0o600)`）：如果路径已经存在，无论是否为符号链接，操作都会失败，因此预置的目标无法重定向写入。
+### 最小配置
 
-## 配置
+不带配置加载插件是安全的：文件会落在操作系统临时目录下延迟创建的私有（0700）每进程目录中。当文件必须位于已知位置时，设置 `root`。
 
-| 键 | 默认值 | 含义 |
+```yaml
+- name: '@deepseek-ai/dsh-spill-local'
+  config:
+    root: /absolute/path/to/spill
+    cleanupPeriodDays: 30
+```
+
+| 字段 | 默认值 | 含义 |
 |---|---|---|
-| `root` | 私有 0700 临时目录 | spill 文件的根目录。设置后可将这些文件保存在已知位置。 |
+| `root` | 私有 0700 临时目录 | spill 文件的根目录；设置后可将文件保存在已知位置 |
+| `cleanupPeriodDays` | `30` | 文件在一次性启动清理中可被删除前需经过的天数；`0` 禁用清理 |
+
+生成的[配置目录](../../../docs/config-catalog.zh.md#deepseek-aidsh-spill-local)是每个受支持字段的穷尽式真源。
+
+### 你会得到什么
+
+每次 `saveText` 调用都会把完整文本写入一个新文件，并返回三个字段：`locator`（文件路径）、`bytes`（精确的 UTF-8 字节数）与 `retrievalHint`——"Use read with offset/limit, or grep this path to search within it."。消费方把该提示展示给模型，模型随后可以用其常规文件工具读取或搜索该文件。
+
+### 文件存放位置
+
+文件存放在 `<root>/session-<hash>/<random>-<safeName>`：`session-<hash>` 是所属会话 id 的短哈希（让同一会话的文件归在一起），`<random>-<safeName>` 把不可预测的十六进制前缀与清理为单个安全路径段的调用方建议名配对。相对 `root` 从进程工作目录解析。
+
+### 启动清理
+
+一次尽力而为的扫描会在激活后启动，不延迟服务可用性。它扫描配置的根目录和操作系统临时目录下先前的默认 `dsh-spill-*` 根目录，删除修改时间严格早于配置截止时间的常规文件，修剪空会话目录，并只删除已经变空的先前默认根目录。长期运行的进程要到重启时才会再次扫描。dispose 会等待扫描结束；如果清理移除了会话目录，并发写入会重新创建它。
+
+扫描会解析文件系统身份，绝不跟随或删除符号链接，并跳过无关条目。在 POSIX 上，它只接受当前用户拥有、组用户和其他用户不可写、且祖先路径能防止替换的根目录与会话目录；`/tmp` 等带 sticky 位的可写临时目录仍然允许使用。不安全路径会产生警告并保持不变。文件系统和警告接收方故障都会被兜底，因此清理无法使激活或并发 spill 写入失败。
+
+### 故障与恢复
+
+真实存储故障——权限不足、磁盘已满、根目录不可写——会让 `saveText` 调用以拒绝结束；由调用方决定如何降级。随附策略把拒绝当作尽力而为处理并保留原始内联结果。
+
+-----
+
+<a id="understand-the-implementation"></a>
+## 理解实现
+
+<details>
+<summary>实现细节——点击展开</summary>
+
+本节解释此后端背后的设计决策；可观察行为已在[使用本包](#use-this-package)中完整说明。
 
-`saveText` 在发生真实存储故障（权限、ENOSPC）时返回拒绝；spill 策略会按尽力而为原则处理该拒绝，并保留内联结果。词汇见 seam README，设计见[工具输出 spill Agent Note](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md)。
+### 设计理念
 
+后端只负责存储细节，建立在一个原则之上：**spill 工具结果必须私有且不可重定向**。根目录私有（0700）、会话目录是稳定哈希、文件名不可预测、写入采用排他且仅所有者模式。存储机制放在与 Cordis 无关的模块中，以便无需上下文即可单元测试。
+
+### 源码地图
+
+| 文件 | 职责 |
+|---|---|
+| [`src/index.ts`](src/index.ts) | 插件入口：`Config`、`LocalSpillStore` 服务、清理生命周期、定位信息与取回提示的组装 |
+| [`src/cleanup.ts`](src/cleanup.ts) | 一次性按年龄扫描、文件系统身份检查、符号链接和所有权保护 |
+| [`src/store.ts`](src/store.ts) | 与 Cordis 无关的存储机制：私有根目录、会话目录、安全名称编码、排他写入 |
+| [`src/invariant.ts`](src/invariant.ts) | 不变式伴生插件（无运行时不变式；约定在 seam 处强制执行） |
+
+### 文件命名与写入
+
+`suggestedName` 是不可信输入，因此 `encodeSegment` 会把 `[A-Za-z0-9._-]`（以及 `~` 本身）之外的每个字符转义成 `~XXXX` 形式，使映射对所有 JS 字符串都是单射：分隔符、`../`、NUL 与绝对路径永远无法逃出单个路径段，整段 token `.`/`..` 也会被转义。写入采用 `open(path, 'wx', 0o600)`——任何已存在路径（无论是否符号链接）都会失败，因此预置目标无法重定向写入。对同一建议名的两次保存会得到不同的随机前缀。
+
+</details>
+
+-----
+
+<a id="further-exploration"></a>
+## 进一步探索
+
+当包级约定不够用时阅读以下页面。
+
+- [spill 存储服务](../spill/README.zh.md)——此后端实现的 `saveText` 约定与词汇。
+- [spill 包映射](../README.zh.md)——三包家族与各自职责。
+- [dsh-spill-policy](../spill-policy/README.zh.md)——结果过大时调用此后端的策略。
+- [spill 子系统](../../../docs/subsystems/spill.zh.md)——穷尽式词汇与归属。
+- [工具输出 spill 决策](../../../.agents/notes/implemented/architecture/2026-07-08-tool-output-spill-files.zh.md)——能力边界与设计依据。
+- [本地 spill 启动清理](../../../.agents/notes/implemented/architecture/2026-07-17-local-spill-startup-cleanup.zh.md)——保留期、竞态处理与安全删除规则。
+
+-----
+
+<a id="model-experience"></a>
 ## 模型体验
 
-通过渲染本地路径以及 `read`/`grep` 取回指引的 spill 消费方间接影响模型。
+间接地，通过把已保存文件路径与 read/grep 取回指引渲染给模型的 spill 消费方。
 
 #### KV Cache 影响
 
-不会直接导致 KV Cache 失效；请求前缀变更由上述消费方负责。
+无直接失效；请求前缀变更由上述消费方负责。
+
+## 已知限制与延期工作
+
+<a id="known-limitations-and-deferred-work"></a>
+
+
+这些限制说明本地后端何时不合适或需要特别的运维注意。它们是当前的包约束。
+
+- **长期运行的部署要等到重启才会被扫描**——一次性扫描只在激活后运行，因此运行期间超过年龄截止值的文件会在下次启动时回收。
+- **定位信息需要与其位于同一文件系统的消费方**——远程或虚拟部署需要另一个 `SpillStore` 后端，其定位信息与取回提示在该环境中有明确含义。
+
+<a id="dev-note"></a>
+### 开发备注
+
+<details>
+<summary>维护者的工作上下文——点击展开</summary>
+
+本开发备注是维护者的工作上下文：开放方向。它明确不具权威性。
+
+#### 未来：工作区隔离的交互
 
-## 已知限制与暂缓事项
+取回模型假定模型的 `read`/`grep` 工具可以检查返回的路径，即使 spill 目录在会话工作目录之外。未来的工作区隔离策略必须显式允许本地 spill 路径，或者改用非文件 spill 后端。
 
-- **本地 spill 文件会持续存在，直到外部清理为止**：该后端不提供会话生命周期删除或按时间保留的策略，因为已持久化、已恢复和 fork 后的会话可能仍在引用某个路径。
-- **定位信息需要与其位于同一文件系统的消费方**：远程或虚拟部署需要另一个 `SpillStore` 后端，其定位信息和取回指引在该环境中有明确含义。
+</details>

package/lib/index.js

@@ -1,31 +1,38 @@
-import { join, resolve } from "node:path";
+import { dirname, join, resolve } from "node:path";
+import { tmpdir } from "node:os";
 import z from "@deepseek-ai/schemastery";
 import { SpillLocator, SpillStore } from "@deepseek-ai/dsh-spill";
+import { lstat, mkdir, open, readdir, realpath, rmdir, unlink } from "node:fs/promises";
 import { createHash, randomBytes } from "node:crypto";
 import { mkdtempSync } from "node:fs";
-import { mkdir, open } from "node:fs/promises";
-import { tmpdir } from "node:os";
 //#region lib/types/store.js
 /**
 * Cordis-free storage mechanics for the local spill backend: private
 * session-scoped directory selection, safe-name derivation, path-traversal
-* protection, and the exclusive owner-only write. Kept out of the service class
-* (like `dsh-bash-local`'s `run.ts`) so the filesystem behavior is unit-testable
-* without a `ctx` and without the OS temp dir.
+* protection, and the exclusive owner-only write.
 *
 * @module @deepseek-ai/dsh-spill-local/store
 */
+/** Prefix shared by default-root creation and startup discovery. */
+const DEFAULT_ROOT_PREFIX = "dsh-spill-";
+/**
+* Test a caught value for a Node system error code.
+*
+* @param error The caught value.
+* @param code The expected system error code.
+* @returns Whether the code matches.
+*/
+function isErrno(error, code) {
+	return error instanceof Error && error.code === code;
+}
 let defaultRoot;
 /**
-* The default spill root: a private (0700) per-process directory under the OS
-* tmpdir, created lazily. Predictable world-readable paths would let other
-* local users read spilled tool output or pre-create symlinks; `mkdtemp` gives
-* an unpredictable suffix and 0700 semantics.
+* Return the lazily-created private per-process spill root.
 *
-* @returns The lazily-created private spill root.
+* @returns The private root path.
 */
 function privateRoot() {
-	defaultRoot ??= mkdtempSync(join(tmpdir(), "dsh-spill-"));
+	defaultRoot ??= mkdtempSync(join(tmpdir(), DEFAULT_ROOT_PREFIX));
 	return defaultRoot;
 }
 /**
@@ -36,10 +43,9 @@ function privateRoot() {
 * as `~XXXX`; `~` is itself escaped, so the mapping is reversible and distinct
 * inputs never collide. The whole-segment tokens `.`/`..` are escaped so they
 * can never traverse. An empty string encodes to `~` (never an empty segment).
-* (Mirrors the JSONL persistence backend's `encodeSegment`.)
 *
-* @param raw The untrusted string to encode as one safe path segment.
-* @returns An injective, filesystem-safe single path segment.
+* @param raw Untrusted text.
+* @returns One injective filesystem-safe path segment.
 */
 function encodeSegment(raw) {
 	if (raw.length === 0) return "~";
@@ -49,42 +55,44 @@ function encodeSegment(raw) {
 	for (let i = 0; i < raw.length; i++) {
 		const code = raw.charCodeAt(i);
 		const ch = String.fromCharCode(code);
-		if (ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch)) out += ch;
-		else out += "~" + code.toString(16).toUpperCase().padStart(4, "0");
+		out += ch !== "~" && /^[A-Za-z0-9._-]$/.test(ch) ? ch : "~" + code.toString(16).toUpperCase().padStart(4, "0");
 	}
 	return out;
 }
 /**
-* The session-scoped directory: `<root>/session-<hash(sessionId)>`, a short stable hash.
+* Derive the stable session-scoped directory under a spill root.
 *
-* @param root The spill root directory.
-* @param sessionId The owning session id to hash into a stable directory name.
-* @returns The absolute session-scoped spill directory path.
+* @param root The spill root.
+* @param sessionId The owning session id.
+* @returns The stable session-scoped directory.
 */
 function sessionDir(root, sessionId) {
 	return join(root, `session-${createHash("sha256").update(sessionId).digest("hex").slice(0, 12)}`);
 }
 /**
-* Write `content` to a fresh file under the session-scoped directory and return
-* its path + byte length. The filename is a random hex prefix plus the
-* sanitized `suggestedName`, so it is unpredictable (defeats symlink planting in
-* a shared root) AND stays readable. The open is exclusive + owner-only
-* (`'wx', 0o600`): it fails on any existing path — symlink or not — so a
-* pre-planted target cannot redirect the write.
-*
-* @param options The resolved root and request fields required to save the file.
-* @returns The written file path and UTF-8 byte length.
+* Write text to a fresh 0600 file below its private session directory.
+* @param options The save request.
+* @returns The saved path and UTF-8 byte length.
 */
 async function saveTextFile(options) {
 	const dir = sessionDir(options.root, options.sessionId);
-	await mkdir(dir, {
-		recursive: true,
-		mode: 448
-	});
-	const safeName = encodeSegment(options.suggestedName);
-	const path = join(dir, `${randomBytes(6).toString("hex")}-${safeName}`);
-	const bytes = Buffer.byteLength(options.content, "utf8");
-	const handle = await open(path, "wx", 384);
+	const path = join(dir, `${randomBytes(6).toString("hex")}-${encodeSegment(options.suggestedName)}`);
+	let handle;
+	for (;;) {
+		await mkdir(dir, {
+			recursive: true,
+			mode: 448
+		});
+		try {
+			handle = await open(path, "wx", 384);
+			break;
+		} catch (error) {
+			/* v8 ignore start -- requires another process to remove the directory
+			between mkdir and open, or an external permission/IO race. */
+			if (isErrno(error, "ENOENT")) continue;
+			throw error;
+		}
+	}
 	try {
 		await handle.writeFile(options.content);
 	} finally {
@@ -92,9 +100,359 @@ async function saveTextFile(options) {
 	}
 	return {
 		path,
-		bytes
+		bytes: Buffer.byteLength(options.content, "utf8")
+	};
+}
+//#endregion
+//#region lib/types/cleanup.js
+/** Startup cleanup mechanics for local spill roots. */
+/**
+* A backend-generated default root name: `dsh-spill-` plus the 6-character
+* suffix `mkdtemp` appends. Discovery matches this
+* EXACT shape, not the bare prefix, so an unrelated `dsh-spill-test-*` fixture
+* or a foreign tool's differently-shaped `dsh-spill-…` directory is never
+* mistaken for a backend root to sweep.
+*/
+const DEFAULT_ROOT_RE = new RegExp(`^${DEFAULT_ROOT_PREFIX}[A-Za-z0-9]{6}$`);
+/**
+* A backend-generated session directory name: `session-` plus the 12 lowercase
+* hex characters {@link sessionDir} derives from `sha256(sessionId)`. The sweep
+* only descends into entries of this EXACT shape, so an unrelated
+* `session-backup` directory under a shared configured root is never swept.
+*/
+const SESSION_DIR_RE = /^session-[0-9a-f]{12}$/;
+/** Report a best-effort sweep failure without allowing the warning sink to reject cleanup. */
+function warnSafely(warn, message) {
+	try {
+		warn(message);
+	} catch {}
+}
+/** Whether another local OS user cannot replace children of this directory. */
+function isTrustedDirectory(stats) {
+	if (!stats.isDirectory()) return false;
+	/* v8 ignore next -- POSIX ownership and mode bits have no Windows equivalent. */
+	if (process.platform === "win32" || process.geteuid === void 0) return true;
+	/* v8 ignore start -- Windows takes the return above; POSIX tests exercise
+	owner and mode rejection. */
+	return stats.uid === process.geteuid() && (stats.mode & 18) === 0;
+	/* v8 ignore stop */
+}
+/** Stable identity for de-duplicating aliases of one root. */
+function rootIdentity(path, stats) {
+	/* v8 ignore next -- Windows file indexes are not portable inode identities. */
+	if (process.platform === "win32") return path.toLowerCase();
+	/* v8 ignore start -- Windows uses the canonical path identity above; POSIX
+	tests exercise device and inode identity. */
+	return `${String(stats.dev)}:${String(stats.ino)}`;
+	/* v8 ignore stop */
+}
+/**
+* Check that no ancestor permits another local OS user to replace the selected
+* child. A sticky writable ancestor is safe because the child is owned by the
+* current user; this admits normal per-process roots below `/tmp`.
+*/
+async function hasProtectedAncestors(path) {
+	/* v8 ignore next -- POSIX ancestry checks have no Windows ACL equivalent. */
+	if (process.platform === "win32" || process.geteuid === void 0) return true;
+	/* v8 ignore start -- Windows takes the return above; POSIX tests exercise
+	the ancestor ownership and mode policy. */
+	const currentUid = process.geteuid();
+	let child = path;
+	let childStats = await lstat(child);
+	for (;;) {
+		const parent = dirname(child);
+		if (parent === child) return true;
+		const stats = await lstat(parent);
+		/* v8 ignore next -- every ancestor of a successfully resolved path is a directory. */
+		if (!stats.isDirectory()) return false;
+		const writableByOthers = (stats.mode & 18) !== 0;
+		const sticky = (stats.mode & 512) !== 0;
+		if (writableByOthers && !sticky) return false;
+		/* v8 ignore next -- requires an ancestor owned by another OS account inside
+		a writable sticky parent; ordinary test fixtures cannot change uid. */
+		if (writableByOthers && childStats.uid !== currentUid) return false;
+		child = parent;
+		childStats = stats;
+	}
+	/* v8 ignore stop */
+}
+/**
+* Resolve one existing root without admitting a directory another local user
+* can replace during the path-based sweep. A configured root may be a symlink;
+* discovery passes `false` so a symlink cannot impersonate a default root.
+*
+* @param path Candidate root path.
+* @param allowSymlink Whether the candidate itself may be a configured symlink.
+* @param warn Sink for skipped or failed inspection.
+* @returns The trusted canonical root, or `undefined` when it is absent or unsafe.
+*/
+async function resolveRoot(path, allowSymlink, warn) {
+	let initial;
+	try {
+		initial = await lstat(path);
+	} catch (error) {
+		/* v8 ignore start -- non-ENOENT inspection failures depend on host ACL or
+		an entry racing away and cannot be reproduced portably. */
+		if (!isErrno(error, "ENOENT")) warnSafely(warn, `spill-local: failed to inspect root ${path}: ${String(error)}`);
+		return;
+	}
+	if (initial.isSymbolicLink()) {
+		if (!allowSymlink) return void 0;
+	} else if (!isTrustedDirectory(initial)) {
+		warnSafely(warn, `spill-local: skipped unsafe root ${path}: expected a directory owned by the current user and not writable by group or others`);
+		return;
+	}
+	let canonical;
+	let stats;
+	try {
+		canonical = await realpath(path);
+		stats = await lstat(canonical);
+	} catch (error) {
+		/* v8 ignore start -- a root lstat'd above reaches this only by racing away
+		or by a host-specific realpath failure. */
+		if (!isErrno(error, "ENOENT")) warnSafely(warn, `spill-local: failed to resolve root ${path}: ${String(error)}`);
+		return;
+	}
+	let protectedAncestors = false;
+	try {
+		protectedAncestors = await hasProtectedAncestors(canonical);
+	} catch (error) {
+		/* v8 ignore start -- a canonical ancestor disappears only through a race;
+		other failures depend on host ACLs. */
+		if (!isErrno(error, "ENOENT")) warnSafely(warn, `spill-local: failed to inspect ancestors of root ${canonical}: ${String(error)}`);
+		return;
+	}
+	/* v8 ignore start -- Windows has no POSIX ownership or mode rejection path;
+	POSIX tests exercise both unsafe-directory conditions. */
+	if (!isTrustedDirectory(stats) || !protectedAncestors) {
+		warnSafely(warn, `spill-local: skipped unsafe root ${canonical}: expected a current-user-owned directory with protected write and ancestor permissions`);
+		return;
+	}
+	/* v8 ignore stop */
+	return {
+		path: canonical,
+		identity: rootIdentity(canonical, stats)
 	};
 }
+/**
+* Delete a single path, treating a concurrent-race disappearance as success.
+* A parallel process (or another sweep) may `unlink` the same file between our
+* scan and our own `unlink` — ENOENT then means the goal (file gone) already
+* holds, so it is not a failure. Any other error is reported and swallowed.
+*
+* @param path The absolute file path to remove.
+* @param warn Sink for a non-ENOENT failure message.
+* @returns Resolves once the removal was attempted (never rejects).
+*/
+async function unlinkIdempotent(path, warn) {
+	try {
+		await unlink(path);
+	} catch (error) {
+		/* v8 ignore start -- reached only when a file selected for deletion (a
+		regular file that passed lstat) then fails to unlink: either it raced away
+		(ENOENT) or a permission/IO fault struck between the stat and the unlink.
+		Neither is deterministically reproducible in-process. */
+		if (isErrno(error, "ENOENT")) return;
+		warnSafely(warn, `spill-local: failed to delete ${path}: ${String(error)}`);
+	}
+}
+/**
+* Sweep one spill session directory: delete expired regular files, skip
+* everything else, and report the directory empty afterward so the caller can
+* prune it. The `dir` entry MUST be a real directory — the caller `lstat`s it
+* first and skips a symlink, so this never follows a `session-*` symlink into a
+* foreign tree. Inside, a symlink or any non-regular entry (socket, fifo, nested
+* dir) is left untouched — `lstat` never follows a link, so a planted symlink
+* can neither be deleted nor redirect the age check. Every per-entry failure is
+* contained: one unreadable file does not abort the directory.
+*
+* @param dir The absolute session directory to scan (already confirmed a real dir).
+* @param cutoffMs Files with `mtime` strictly older than this are deleted.
+* @param warn Sink for contained filesystem failures.
+* @returns `true` when the directory holds no entries after the sweep (a prune candidate).
+*/
+async function sweepSessionDir(dir, cutoffMs, warn) {
+	let names;
+	try {
+		names = await readdir(dir);
+	} catch (error) {
+		/* v8 ignore start -- the caller lstat'd this entry and confirmed a real
+		directory just before the call, so readdir fails only when the dir races
+		away (ENOENT) or a permission/IO fault strikes in that window; not
+		deterministically reproducible. False keeps it out of the prune step. */
+		warnSafely(warn, `spill-local: failed to read ${dir}: ${String(error)}`);
+		return false;
+	}
+	let remaining = names.length;
+	for (const name of names) {
+		const path = join(dir, name);
+		let stats;
+		try {
+			stats = await lstat(path);
+		} catch (error) {
+			/* v8 ignore start -- an entry that readdir just returned then fails to
+			lstat only by racing away (ENOENT) or a permission/IO fault; keep it out
+			of the deterministic test surface. */
+			if (isErrno(error, "ENOENT")) {
+				remaining--;
+				continue;
+			}
+			warnSafely(warn, `spill-local: failed to stat ${path}: ${String(error)}`);
+			continue;
+		}
+		if (!stats.isFile()) continue;
+		if (stats.mtimeMs >= cutoffMs) continue;
+		await unlinkIdempotent(path, warn);
+		remaining--;
+	}
+	return remaining === 0;
+}
+/**
+* Best-effort one-shot cleanup: across each root, delete expired regular files
+* under its `session-*` directories and prune every empty session directory.
+* Only a discovered prior-default root is itself removed. Writes recreate a
+* session directory when pruning races a local write. Every filesystem and
+* warning-sink failure is contained, so a caller can await this during
+* activation/disposal without it ever rejecting.
+*
+* @param options The roots to sweep, the age cutoff, and the failure sink.
+* @returns Resolves when the sweep finishes (never rejects).
+*/
+async function sweepSpillRoots(options) {
+	const { cutoffMs, warn } = options;
+	const roots = /* @__PURE__ */ new Map();
+	for (const candidate of options.roots) {
+		const resolved = await resolveRoot(candidate.path, false, warn);
+		if (resolved === void 0) continue;
+		const existing = roots.get(resolved.identity);
+		roots.set(resolved.identity, {
+			path: resolved.path,
+			pruneWhenEmpty: (existing?.pruneWhenEmpty ?? true) && candidate.pruneWhenEmpty
+		});
+	}
+	for (const root of roots.values()) {
+		let entries;
+		try {
+			entries = await readdir(root.path);
+		} catch (error) {
+			/* v8 ignore start -- the trusted root was resolved immediately above; a
+			read failure now requires a race or host-specific ACL fault. */
+			if (!isErrno(error, "ENOENT")) warnSafely(warn, `spill-local: failed to read root ${root.path}: ${String(error)}`);
+			continue;
+		}
+		let rootEmptiable = true;
+		for (const name of entries) {
+			if (!SESSION_DIR_RE.test(name)) {
+				rootEmptiable = false;
+				continue;
+			}
+			const dir = join(root.path, name);
+			let stats;
+			try {
+				stats = await lstat(dir);
+			} catch (error) {
+				/* v8 ignore start -- an entry readdir just returned fails to lstat only
+				by racing away (ENOENT) or a permission/IO fault; not deterministically
+				reproducible. */
+				if (!isErrno(error, "ENOENT")) warnSafely(warn, `spill-local: failed to stat ${dir}: ${String(error)}`);
+				continue;
+			}
+			if (!isTrustedDirectory(stats)) {
+				warnSafely(warn, `spill-local: skipped unsafe session directory ${dir}`);
+				rootEmptiable = false;
+				continue;
+			}
+			if (!await sweepSessionDir(dir, cutoffMs, warn)) {
+				rootEmptiable = false;
+				continue;
+			}
+			try {
+				await rmdir(dir);
+			} catch (error) {
+				/* v8 ignore start -- prune runs only on a dir observed empty; a failure
+				here means a concurrent writer added a file (ENOTEMPTY) or a
+				permission/IO fault struck — both are races outside deterministic
+				in-process testing. */
+				rootEmptiable = false;
+				if (!isErrno(error, "ENOENT") && !isErrno(error, "ENOTEMPTY")) warnSafely(warn, `spill-local: failed to prune ${dir}: ${String(error)}`);
+			}
+		}
+		if (root.pruneWhenEmpty && rootEmptiable) try {
+			await rmdir(root.path);
+		} catch (error) {
+			/* v8 ignore start -- prune runs only on a root whose every child was
+			reclaimed; a failure here means a concurrent writer added a fresh
+			spill after our scan (ENOTEMPTY) or removed the root already (ENOENT)
+			or a permission/IO fault struck — all races outside deterministic
+			in-process testing. */
+			if (!isErrno(error, "ENOENT") && !isErrno(error, "ENOTEMPTY")) warnSafely(warn, `spill-local: failed to prune root ${root.path}: ${String(error)}`);
+		}
+	}
+}
+/**
+* Discover prior default spill roots: the `dsh-spill-<6 chars>` directories
+* directly under `base` (the OS tmpdir) that earlier default-root runs created.
+* A long-lived deployment
+* with a configured root will find none; a series of default-root runs
+* accumulates one per process, so the startup sweep reclaims them all. Matching
+* is the EXACT `mkdtemp` shape (see {@link DEFAULT_ROOT_RE}), not the bare
+* prefix, so an unrelated `dsh-spill-test-*` fixture or a foreign
+* differently-shaped directory is never swept; symlinks and non-directories are
+* excluded too — only real directories the backend could have created.
+*
+* @param warn Sink for a failure reading `base` (returns `[]` on failure).
+* @param base The directory to scan; defaults to the OS tmpdir (a test seam).
+* @returns Absolute paths of the discovered default roots (possibly empty).
+*/
+async function discoverDefaultRootRecords(warn, base) {
+	let entries;
+	try {
+		entries = await readdir(base);
+	} catch (error) {
+		warnSafely(warn, `spill-local: failed to scan ${base} for default roots: ${String(error)}`);
+		return [];
+	}
+	const roots = [];
+	for (const name of entries) {
+		if (!DEFAULT_ROOT_RE.test(name)) continue;
+		const resolved = await resolveRoot(join(base, name), false, warn);
+		if (resolved !== void 0) roots.push(resolved);
+	}
+	return roots;
+}
+/**
+* Discover trusted prior default roots below the OS temporary directory.
+*
+* @param warn Sink for contained discovery failures.
+* @param base Directory to scan; defaults to the OS temporary directory.
+* @returns Canonical paths of trusted default roots.
+*/
+async function discoverDefaultRoots(warn, base = tmpdir()) {
+	return (await discoverDefaultRootRecords(warn, base)).map((root) => root.path);
+}
+/**
+* Gather and de-duplicate the trusted roots for one startup sweep. The active
+* configured path may be a symlink; its resolved identity overrides a matching
+* discovered root so the live target is never marked prunable.
+*
+* @param activeRoot Active configured root.
+* @param warn Sink for contained inspection failures.
+* @param defaultRootsBase Directory holding prior default roots.
+* @returns Trusted roots with the active identity marked non-prunable.
+*/
+async function gatherSweepRoots(activeRoot, warn, defaultRootsBase = tmpdir()) {
+	const [discovered, active] = await Promise.all([discoverDefaultRootRecords(warn, defaultRootsBase), resolveRoot(activeRoot, true, warn)]);
+	const roots = /* @__PURE__ */ new Map();
+	for (const root of discovered) roots.set(root.identity, {
+		path: root.path,
+		pruneWhenEmpty: true
+	});
+	if (active !== void 0) roots.set(active.identity, {
+		path: active.path,
+		pruneWhenEmpty: false
+	});
+	return [...roots.values()];
+}
 //#endregion
 //#region lib/types/index.js
 /**
@@ -102,23 +460,98 @@ async function saveTextFile(options) {
 * `@deepseek-ai/dsh-spill` storage seam. Persists a tool's oversized text to a
 * private, session-scoped file (see `./store.ts` for the traversal-safe naming
 * and exclusive owner-only write) and returns a path locator plus local
-* read/grep retrieval guidance.
+* read/grep retrieval guidance. After activation it runs one best-effort
+* startup sweep that reclaims spill files older than `cleanupPeriodDays`.
 *
 * @module @deepseek-ai/dsh-spill-local
 */
+/** Milliseconds in one day — converts the `cleanupPeriodDays` config to the sweep cutoff. */
+const MS_PER_DAY = 1440 * 60 * 1e3;
 /**
 * Local-filesystem spill backend. Files land under `<root>/session-<hash>/…`
 * with unpredictable names, an exclusive owner-only (0600) write, and a private
 * (0700) root — a spilled tool result must not be readable by other local users
 * or redirectable via a planted symlink.
+*
+* After activation it launches ONE best-effort cleanup sweep (see
+* {@link cleanupPeriodDays}) that reclaims expired spill files without delaying
+* service availability; the sweep is owned by the plugin fiber and awaited
+* during disposal, so a fiber unload never returns before it quiesces.
 */
 var LocalSpillStore = class extends SpillStore {
-	static Config = z.object({ root: z.string() });
+	static Config = z.object({
+		root: z.string(),
+		cleanupPeriodDays: z.number().step(1).min(0).default(30)
+	});
 	/** Resolved absolute spill root (config `root`, else the private default), fixed at construction. */
 	root;
+	/** Validated config (schemastery applied the `cleanupPeriodDays` default before construction). */
+	config;
+	/**
+	* The in-flight (or settled) startup cleanup sweep. Held so disposal can await
+	* it; `undefined` when cleanup is disabled (`cleanupPeriodDays === 0`).
+	*/
+	cleanup;
 	constructor(ctx, config) {
 		super(ctx);
+		this.config = config;
 		this.root = config.root !== void 0 ? resolve(config.root) : privateRoot();
+		ctx.effect(function* () {
+			if (this.config.cleanupPeriodDays > 0) {
+				const warn = (message) => {
+					this.ctx.logger.warn(message);
+				};
+				this.cleanup = this.runCleanup(warn);
+			}
+			yield async () => {
+				await this.cleanup;
+			};
+		}.bind(this), "spill-local cleanup sweep");
+	}
+	/**
+	* Run the one-shot cleanup: gather the roots to sweep (see {@link gatherRoots})
+	* and sweep all of them at the age cutoff. Best-effort —
+	* {@link sweepSpillRoots} contains every filesystem failure, so this never
+	* rejects and cannot fail activation or a concurrent spill write.
+	*
+	* @param warn - sink for a contained filesystem failure.
+	* @returns Resolves when the sweep finishes (never rejects).
+	*/
+	async runCleanup(warn) {
+		const cutoffMs = Date.now() - this.config.cleanupPeriodDays * MS_PER_DAY;
+		await sweepSpillRoots({
+			roots: await this.gatherRoots(warn),
+			cutoffMs,
+			warn
+		});
+	}
+	/**
+	* The roots the startup sweep covers: each discovered prior-default
+	* `dsh-spill-*` temp root (see {@link discoverDefaultRoots}), pruned when
+	* emptied, plus the active/configured root, which is never itself pruned while
+	* the live process may write into it. Empty session directories are pruned in
+	* every root. Filesystem identity de-duplicates aliases before the active root
+	* overrides a discovered match as non-prunable. A test overrides this to
+	* inject an isolated root set — and, being the sweep's one async gather point,
+	* to hold the sweep open across a disposal for the quiescence check; it is a
+	* test seam, not a deployment knob.
+	*
+	* @param warn - sink for a contained discovery failure.
+	* @returns The roots to sweep, each flagged for prune-when-empty.
+	*/
+	async gatherRoots(warn) {
+		return gatherSweepRoots(this.root, warn, this.defaultRootsBase());
+	}
+	/**
+	* The directory scanned for prior default `dsh-spill-*` roots — the OS tmpdir,
+	* where {@link privateRoot} creates them (accumulation only happens there). A
+	* test overrides this to point discovery at an isolated fixture instead of the
+	* real tmpdir; it is a test seam, not a deployment knob.
+	*
+	* @returns The base directory to scan for default spill roots.
+	*/
+	defaultRootsBase() {
+		return tmpdir();
 	}
 	async saveText(input) {
 		const saved = await saveTextFile({
@@ -135,4 +568,4 @@ var LocalSpillStore = class extends SpillStore {
 	}
 };
 //#endregion
-export { LocalSpillStore, LocalSpillStore as default, encodeSegment, privateRoot, saveTextFile, sessionDir };
+export { DEFAULT_ROOT_PREFIX, LocalSpillStore, LocalSpillStore as default, discoverDefaultRoots, encodeSegment, isErrno, privateRoot, saveTextFile, sessionDir, sweepSpillRoots };

package/lib/types/cleanup.d.ts

@@ -0,0 +1,60 @@
+/** A one-argument warning sink — the sweep's only side effect on failure (never throws). */
+export type WarnFn = (message: string) => void;
+/** One root to sweep, plus whether the root itself may be pruned once empty. */
+export interface SweepRoot {
+    /** Absolute spill root to sweep. */
+    path: string;
+    /**
+     * When `true`, remove the root after its empty `session-*` children are
+     * pruned. Set for DISCOVERED prior-default `dsh-spill-*` roots (one per past
+     * process — otherwise they accumulate empty forever), never for the active
+     * root the live process is still writing into. Every root prunes empty session
+     * directories; writes retry if that races their removal.
+     */
+    pruneWhenEmpty: boolean;
+}
+/** Options for {@link sweepSpillRoots} — the roots to scan, the age cutoff, and a failure sink. */
+export interface SweepOptions {
+    /** Roots to sweep (configured/active root and/or discovered prior-default roots). */
+    roots: SweepRoot[];
+    /**
+     * Epoch-millis cutoff: a regular file is deleted when its `mtime` is strictly
+     * older than this. The caller derives it from `now - cleanupPeriodDays`, so a
+     * file written exactly at the boundary is kept (only strictly-older expires).
+     */
+    cutoffMs: number;
+    /** Where a contained filesystem failure is reported; the sweep itself never throws. */
+    warn: WarnFn;
+}
+/**
+ * Best-effort one-shot cleanup: across each root, delete expired regular files
+ * under its `session-*` directories and prune every empty session directory.
+ * Only a discovered prior-default root is itself removed. Writes recreate a
+ * session directory when pruning races a local write. Every filesystem and
+ * warning-sink failure is contained, so a caller can await this during
+ * activation/disposal without it ever rejecting.
+ *
+ * @param options The roots to sweep, the age cutoff, and the failure sink.
+ * @returns Resolves when the sweep finishes (never rejects).
+ */
+export declare function sweepSpillRoots(options: SweepOptions): Promise<void>;
+/**
+ * Discover trusted prior default roots below the OS temporary directory.
+ *
+ * @param warn Sink for contained discovery failures.
+ * @param base Directory to scan; defaults to the OS temporary directory.
+ * @returns Canonical paths of trusted default roots.
+ */
+export declare function discoverDefaultRoots(warn: WarnFn, base?: string): Promise<string[]>;
+/**
+ * Gather and de-duplicate the trusted roots for one startup sweep. The active
+ * configured path may be a symlink; its resolved identity overrides a matching
+ * discovered root so the live target is never marked prunable.
+ *
+ * @param activeRoot Active configured root.
+ * @param warn Sink for contained inspection failures.
+ * @param defaultRootsBase Directory holding prior default roots.
+ * @returns Trusted roots with the active identity marked non-prunable.
+ */
+export declare function gatherSweepRoots(activeRoot: string, warn: WarnFn, defaultRootsBase?: string): Promise<SweepRoot[]>;
+//# sourceMappingURL=cleanup.d.ts.map

package/lib/types/index.d.ts

@@ -3,7 +3,8 @@
  * `@deepseek-ai/dsh-spill` storage seam. Persists a tool's oversized text to a
  * private, session-scoped file (see `./store.ts` for the traversal-safe naming
  * and exclusive owner-only write) and returns a path locator plus local
- * read/grep retrieval guidance.
+ * read/grep retrieval guidance. After activation it runs one best-effort
+ * startup sweep that reclaims spill files older than `cleanupPeriodDays`.
  *
  * @module @deepseek-ai/dsh-spill-local
  */
@@ -11,7 +12,10 @@ import { Context } from '@deepseek-ai/cordis';
 import z from '@deepseek-ai/schemastery';
 import { SpillStore } from '@deepseek-ai/dsh-spill';
 import type { SaveTextSpill, SpillRef } from '@deepseek-ai/dsh-spill';
-export { encodeSegment, privateRoot, saveTextFile, sessionDir } from './store.ts';
+import type { SweepRoot, WarnFn } from './cleanup.ts';
+export { discoverDefaultRoots, sweepSpillRoots } from './cleanup.ts';
+export type { SweepOptions, SweepRoot, WarnFn } from './cleanup.ts';
+export { DEFAULT_ROOT_PREFIX, encodeSegment, isErrno, privateRoot, saveTextFile, sessionDir } from './store.ts';
 export type { SavedText, SaveTextOptions } from './store.ts';
 /** Plugin config (all optional — `static Config` supplies the defaults). */
 export interface Config {
@@ -21,18 +25,77 @@ export interface Config {
      * a local deployment. Set it to keep spill files under a known location.
      */
     root?: string;
+    /**
+     * Age in days after which a spill file is eligible for the one-shot startup
+     * cleanup sweep. Defaults to `30`; `0` disables cleanup entirely. Files whose
+     * `mtime` is strictly older than the cutoff are deleted and emptied
+     * directories are pruned; fresh files, symlinks, and unrelated entries are
+     * left untouched. On POSIX, cleanup skips roots and session directories that
+     * another local user could modify or replace. Retention is deliberate — a
+     * resumed or forked session may still reference an older locator until it
+     * ages out.
+     */
+    cleanupPeriodDays?: number;
 }
+/** The shape after schemastery applied the defaults. */
+type ResolvedConfig = Required<Omit<Config, 'root'>> & Pick<Config, 'root'>;
 /**
  * Local-filesystem spill backend. Files land under `<root>/session-<hash>/…`
  * with unpredictable names, an exclusive owner-only (0600) write, and a private
  * (0700) root — a spilled tool result must not be readable by other local users
  * or redirectable via a planted symlink.
+ *
+ * After activation it launches ONE best-effort cleanup sweep (see
+ * {@link cleanupPeriodDays}) that reclaims expired spill files without delaying
+ * service availability; the sweep is owned by the plugin fiber and awaited
+ * during disposal, so a fiber unload never returns before it quiesces.
  */
 export declare class LocalSpillStore extends SpillStore {
     static Config: z<Config>;
     /** Resolved absolute spill root (config `root`, else the private default), fixed at construction. */
     readonly root: string;
+    /** Validated config (schemastery applied the `cleanupPeriodDays` default before construction). */
+    readonly config: ResolvedConfig;
+    /**
+     * The in-flight (or settled) startup cleanup sweep. Held so disposal can await
+     * it; `undefined` when cleanup is disabled (`cleanupPeriodDays === 0`).
+     */
+    private cleanup;
     constructor(ctx: Context, config: Config);
+    /**
+     * Run the one-shot cleanup: gather the roots to sweep (see {@link gatherRoots})
+     * and sweep all of them at the age cutoff. Best-effort —
+     * {@link sweepSpillRoots} contains every filesystem failure, so this never
+     * rejects and cannot fail activation or a concurrent spill write.
+     *
+     * @param warn - sink for a contained filesystem failure.
+     * @returns Resolves when the sweep finishes (never rejects).
+     */
+    private runCleanup;
+    /**
+     * The roots the startup sweep covers: each discovered prior-default
+     * `dsh-spill-*` temp root (see {@link discoverDefaultRoots}), pruned when
+     * emptied, plus the active/configured root, which is never itself pruned while
+     * the live process may write into it. Empty session directories are pruned in
+     * every root. Filesystem identity de-duplicates aliases before the active root
+     * overrides a discovered match as non-prunable. A test overrides this to
+     * inject an isolated root set — and, being the sweep's one async gather point,
+     * to hold the sweep open across a disposal for the quiescence check; it is a
+     * test seam, not a deployment knob.
+     *
+     * @param warn - sink for a contained discovery failure.
+     * @returns The roots to sweep, each flagged for prune-when-empty.
+     */
+    protected gatherRoots(warn: WarnFn): Promise<SweepRoot[]>;
+    /**
+     * The directory scanned for prior default `dsh-spill-*` roots — the OS tmpdir,
+     * where {@link privateRoot} creates them (accumulation only happens there). A
+     * test overrides this to point discovery at an isolated fixture instead of the
+     * real tmpdir; it is a test seam, not a deployment knob.
+     *
+     * @returns The base directory to scan for default spill roots.
+     */
+    protected defaultRootsBase(): string;
     saveText(input: SaveTextSpill): Promise<SpillRef>;
 }
 export default LocalSpillStore;

package/lib/types/store.d.ts

@@ -1,19 +1,24 @@
 /**
  * Cordis-free storage mechanics for the local spill backend: private
  * session-scoped directory selection, safe-name derivation, path-traversal
- * protection, and the exclusive owner-only write. Kept out of the service class
- * (like `dsh-bash-local`'s `run.ts`) so the filesystem behavior is unit-testable
- * without a `ctx` and without the OS temp dir.
+ * protection, and the exclusive owner-only write.
  *
  * @module @deepseek-ai/dsh-spill-local/store
  */
+/** Prefix shared by default-root creation and startup discovery. */
+export declare const DEFAULT_ROOT_PREFIX = "dsh-spill-";
 /**
- * The default spill root: a private (0700) per-process directory under the OS
- * tmpdir, created lazily. Predictable world-readable paths would let other
- * local users read spilled tool output or pre-create symlinks; `mkdtemp` gives
- * an unpredictable suffix and 0700 semantics.
+ * Test a caught value for a Node system error code.
  *
- * @returns The lazily-created private spill root.
+ * @param error The caught value.
+ * @param code The expected system error code.
+ * @returns Whether the code matches.
+ */
+export declare function isErrno(error: unknown, code: string): boolean;
+/**
+ * Return the lazily-created private per-process spill root.
+ *
+ * @returns The private root path.
  */
 export declare function privateRoot(): string;
 /**
@@ -24,46 +29,41 @@ export declare function privateRoot(): string;
  * as `~XXXX`; `~` is itself escaped, so the mapping is reversible and distinct
  * inputs never collide. The whole-segment tokens `.`/`..` are escaped so they
  * can never traverse. An empty string encodes to `~` (never an empty segment).
- * (Mirrors the JSONL persistence backend's `encodeSegment`.)
  *
- * @param raw The untrusted string to encode as one safe path segment.
- * @returns An injective, filesystem-safe single path segment.
+ * @param raw Untrusted text.
+ * @returns One injective filesystem-safe path segment.
  */
 export declare function encodeSegment(raw: string): string;
 /**
- * The session-scoped directory: `<root>/session-<hash(sessionId)>`, a short stable hash.
+ * Derive the stable session-scoped directory under a spill root.
  *
- * @param root The spill root directory.
- * @param sessionId The owning session id to hash into a stable directory name.
- * @returns The absolute session-scoped spill directory path.
+ * @param root The spill root.
+ * @param sessionId The owning session id.
+ * @returns The stable session-scoped directory.
  */
 export declare function sessionDir(root: string, sessionId: string): string;
-/** Options for {@link saveTextFile} — the resolved root and the request fields the store needs. */
+/** Inputs needed to save a local spill file. */
 export interface SaveTextOptions {
-    /** The spill root directory (configured or the lazy private default). */
+    /** Spill root. */
     root: string;
-    /** The owning session id (scopes the directory). */
+    /** Owning session id. */
     sessionId: string;
-    /** Caller-suggested base name; sanitized to one safe segment before use. */
+    /** Caller-suggested filename. */
     suggestedName: string;
-    /** The full text to persist. */
+    /** Full text to persist. */
     content: string;
 }
 /** A written spill file. */
 export interface SavedText {
+    /** Absolute saved path. */
     path: string;
+    /** UTF-8 content length. */
     bytes: number;
 }
 /**
- * Write `content` to a fresh file under the session-scoped directory and return
- * its path + byte length. The filename is a random hex prefix plus the
- * sanitized `suggestedName`, so it is unpredictable (defeats symlink planting in
- * a shared root) AND stays readable. The open is exclusive + owner-only
- * (`'wx', 0o600`): it fails on any existing path — symlink or not — so a
- * pre-planted target cannot redirect the write.
- *
- * @param options The resolved root and request fields required to save the file.
- * @returns The written file path and UTF-8 byte length.
+ * Write text to a fresh 0600 file below its private session directory.
+ * @param options The save request.
+ * @returns The saved path and UTF-8 byte length.
  */
 export declare function saveTextFile(options: SaveTextOptions): Promise<SavedText>;
 //# sourceMappingURL=store.d.ts.map

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@deepseek-ai/dsh-spill-local",
   "description": "Local-filesystem implementation of the DeepSeek Harness spill storage seam (private session-scoped files)",
-  "version": "0.1.1-rc.2",
+  "version": "0.1.2-alpha.2",
   "publishConfig": {
     "access": "public"
   },
@@ -32,19 +32,21 @@
   ],
   "license": "MIT",
   "peerDependencies": {
-    "@deepseek-ai/dsh-spill": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1"
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-spill": "^0.1.2-alpha.2"
   },
   "dependencies": {
-    "@deepseek-ai/schemastery": "^3.18.1"
+    "@deepseek-ai/schemastery": "^3.18.2"
   },
   "devDependencies": {
-    "@deepseek-ai/dsh-brand": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-invariants": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-llm": "^0.1.1-rc.2",
-    "@deepseek-ai/dsh-session": "^0.1.1-rc.2",
-    "@deepseek-ai/cordis": "^4.0.1",
-    "@deepseek-ai/dsh-spill": "^0.1.1-rc.2"
+    "@deepseek-ai/cordis-plugin-include": "^1.0.7",
+    "@deepseek-ai/cordis-plugin-loader": "^1.0.3",
+    "@deepseek-ai/dsh-brand": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-invariants": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-llm": "^0.1.2-alpha.2",
+    "@deepseek-ai/dsh-session": "^0.1.2-alpha.2",
+    "@deepseek-ai/cordis": "^4.0.2",
+    "@deepseek-ai/dsh-spill": "^0.1.2-alpha.2"
   }
 }