@dsh-cc/handoff-store 0.6.2

package/LICENSE

@@ -0,0 +1,201 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

package/README.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 check:readme --write
+README.md: c12d42fa4fa8cfcb3357d1256b81f579f9bd1ccd
+README.zh.md: a8b1737a9a3836c0263896fe34b7cde52da0da6b

package/README.md

@@ -0,0 +1,35 @@
+# @dsh-cc/handoff-store
+
+English | [中文](README.zh.md)
+
+Subagent handoff store: the `handoff_put` / `handoff_get` tool pair lets a sandboxed or read-only subagent park a large artifact (a long review, plan, or report) in a durable store and hand back a short summary embedding a `handoff://<id>` handle; the orchestrator or a follow-up child resolves the handle with `handoff_get`. This closes the residual-bulk gap in dsh-cc's delegation discipline — a critic (no Write) cannot put its report in a repo file, and the parent's only other channel is the full final-message text.
+
+## Store
+
+`$DSH_HOME/handoff/<projectKey>/<id>.md`, flat per project (no per-session subdir; the session lives in the ledger). `projectKey = sha256(session cwd)` first 16 hex, derived from the FETCHING session's cwd (CCR `context_retrieve` precedent). `id = sha256(content utf8)` first 16 hex + a 4-hex random suffix — identical content stored twice yields distinct ids. Files are plain UTF-8 JSON envelopes `{v, ts, text, label?, agent?}`, written atomically (temp + rename).
+
+**Same-cwd requirement**: a handle only resolves for sessions whose cwd hashes to the same projectKey. Cross-project fetch is intentionally `unknown_id`. **Git-worktree caveat**: two worktrees of one repo are different keys — a child spawned in a different worktree cannot fetch a handle parked elsewhere.
+
+## Retention
+
+TTL 24 h (checked against the stored envelope `ts` on every read; expired → typed `expired` error and a lazy delete) plus a 500-entry LRU per project. Both sweeps are DISK-BASED (`readdir` + envelope/mtime over the projectKey dir, run on put) — deliberately no in-memory LRU, because spawned children are separate processes and a fresh store instance must see the same eviction state. Reads bump mtime (LRU touch); the sweep's TTL pass uses mtime as a cheap proxy while the envelope `ts` stays authoritative on read.
+
+## Ledger
+
+`$DSH_HOME/handoff/ledger.jsonl`, append-only rows `{ts, project, sessionId, id, label?, agent?, chars}`. A rebuildable observability index, never on the read path; interleaved appends from sibling children are tolerated. All ledger I/O errors are swallowed.
+
+## Settings
+
+Namespace `cc-handoff` (settings overlay, re-read on every put — CCR settings pattern):
+
+| Key | Default | Meaning |
+|---|---|---|
+| `enabled` | `true` | Master flag; `false` disables `handoff_put`. |
+| `threshold-chars` | `8192` | Advisory size threshold referenced in the tool description. ADVISORY ONLY: put never enforces or rejects on it. |
+
+## Tools
+
+- `handoff_put({ content, label?, agent? })` → summary text including `handoff://<id>` and the char count (plus an advisory note when over the threshold). Keyed by the putting session's cwd.
+- `handoff_get({ id, maxChars? })` → the content, head-truncated with a trailing truncation note when `maxChars` is given. Typed errors `unknown_id` / `expired` / `corrupt`. Fail-closed: the id must match `^[0-9a-f]{20}$` and resolves only inside the current projectKey directory — never outside the store root.
+
+The plugin is a plain cordis plugin (publishes no Service, memory pattern); it no-ops when the tools service, fs seam, or `dshHomePath` is absent.

package/README.zh.md

@@ -0,0 +1,35 @@
+# @dsh-cc/handoff-store
+
+[English](README.md) | 中文
+
+子代理交接存储：`handoff_put` / `handoff_get` 工具对让被沙箱化或只读的子代理把大体量产物（长评审、计划、报告）存入持久存储，并回传一个内嵌 `handoff://<id>` 句柄的简短摘要；编排者或后续子代理用 `handoff_get` 取回全文。这补上了 dsh-cc 委派纪律下的残余体量缺口——critic（无 Write）无法把评审写进仓库文件，而父级唯一的另一通道是完整最终消息文本。
+
+## 存储
+
+`$DSH_HOME/handoff/<projectKey>/<id>.md`，每个项目平铺（无每会话子目录；会话只进台账）。`projectKey = sha256(会话 cwd)` 前 16 位，取自【取回方】会话的 cwd（CCR `context_retrieve` 先例）。`id = sha256(内容 utf8)` 前 16 位 + 4 位十六进制随机后缀——相同内容存两次得到不同 id。文件是纯 UTF-8 JSON 信封 `{v, ts, text, label?, agent?}`，原子写入（temp + rename）。
+
+**同 cwd 要求**：句柄只对 cwd 哈希到同一 projectKey 的会话可解析。跨项目取回刻意返回 `unknown_id`。**git worktree 注意**：同一仓库的两个 worktree 是不同的键——在不同 worktree 中生成的子代理无法取回别处存入的句柄。
+
+## 保留策略
+
+TTL 24 小时（每次读取依据信封内存储的 `ts` 校验；过期 → 类型化 `expired` 错误并惰性删除），加上每项目 500 条的 LRU。两次清扫都基于磁盘（对 projectKey 目录 `readdir` + 信封/mtime，在 put 时运行）——刻意不做内存 LRU，因为派生的子进程是独立进程，新建的 store 实例必须看到相同的逐出状态。读取会 bump mtime（LRU touch）；清扫的 TTL 判定用 mtime 作廉价代理，信封 `ts` 仍是读取路径上的权威判据。
+
+## 台账
+
+`$DSH_HOME/handoff/ledger.jsonl`，只追加行 `{ts, project, sessionId, id, label?, agent?, chars}`。可重建的观测索引，绝不在读取路径上；容忍兄弟子进程交错追加。所有台账 I/O 错误都被吞掉。
+
+## 设置
+
+命名空间 `cc-handoff`（每次 put 重读——CCR settings 模式）：
+
+| 键 | 默认 | 含义 |
+|---|---|---|
+| `enabled` | `true` | 总开关；`false` 禁用 `handoff_put`。 |
+| `threshold-chars` | `8192` | 工具描述引用的建议尺寸阈值。仅供参考：put 永不据此强制或拒绝。 |
+
+## 工具
+
+- `handoff_put({ content, label?, agent? })` → 含 `handoff://<id>` 与字符数的摘要文本。以存入方会话的 cwd 为键。
+- `handoff_get({ id, maxChars? })` → 内容；给定 `maxChars` 时按头部截断并附截断说明。类型化错误 `unknown_id` / `expired` / `corrupt`。封闭失败：id 必须匹配 `^[0-9a-f]{20}$`，且只在当前 projectKey 目录内解析——绝不读出存储根之外。
+
+本插件是普通 cordis 插件（不发布 Service，memory 模式）；宿主缺少 tools 服务、fs 缝隙或 `dshHomePath` 时整体 no-op。

package/lib/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Subagent handoff store: the `handoff_put` / `handoff_get` tool pair plus a
+ * disk-based content-addressed store under `$DSH_HOME/handoff/<projectKey>/`.
+ *
+ * A sandboxed or read-only subagent (e.g. critic, no Write) cannot put a long
+ * report in a repo file; the parent's only channel back would otherwise be
+ * the full final-message text. handoff_put parks the artifact and returns a
+ * short summary embedding `handoff://<id>`; the orchestrator or a follow-up
+ * child resolves it with handoff_get. Cross-session and cross-project
+ * transfer follow the CCR precedent: the project bucket is keyed by the
+ * session cwd, so fetches only resolve within the SAME working directory
+ * (two git worktrees of one repo are different projects — caveat documented
+ * in the package README).
+ *
+ * Plain cordis plugin (publishes no Service — mirror of @dsh-cc/memory): it
+ * no-ops when the tools service, fs seam, or dshHomePath is absent. State is
+ * entirely on disk (TTL 24 h + 500-entry disk-based LRU swept on put), so
+ * spawned children in separate processes see the same store.
+ *
+ * @module @dsh-cc/handoff-store
+ */
+import type { Context } from '@deepseek-ai/cordis';
+export { HandoffStore, MAX_ENTRIES, TTL_MS, projectKeyOf } from './store.ts';
+export { HandoffLedger } from './ledger.ts';
+export { registerSettings, SETTINGS_NAMESPACE, SettingsSchema, DEFAULTS, resolveHandoffConfig } from './settings.ts';
+export { defineHandoffPutTool, defineHandoffGetTool, HANDOFF_PUT_TOOL, HANDOFF_GET_TOOL, THRESHOLD_NOTE, HandoffToolError, applyMaxChars, cwdProjectKey, } from './tools.ts';
+export type { HandoffDeps } from './tools.ts';
+export type { HandoffConfig, HandoffError, HandoffLedgerRow, HandoffMeta } from './types.ts';
+declare module '@deepseek-ai/cordis' {
+    interface Context {
+        /** Harness-home path resolver, provided by @deepseek-ai/dsh-app-boot at boot. Optional in tests. */
+        dshHomePath?: (...segments: string[]) => string;
+    }
+}
+/**
+ * Mount the handoff tools. No-op when the host has no tools service, no fs
+ * seam, or no dshHomePath (a providerless host keeps no handoff surface).
+ * @param ctx - the plug context.
+ * @returns the tools-registration disposer, or `undefined` when not registered.
+ */
+export declare function apply(ctx: Context): (() => void) | undefined;
+/** Cordis plugin id. */
+export declare const name = "cc-handoff";
+//# sourceMappingURL=index.d.ts.map

package/lib/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAEH,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAOlD,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACpH,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,YAAY,CAAA;AACnB,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAC7C,YAAY,EAAE,aAAa,EAAE,YAAY,EAAE,gBAAgB,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAK5F,OAAO,QAAQ,qBAAqB,CAAC;IACnC,UAAU,OAAO;QACf,oGAAoG;QACpG,WAAW,CAAC,EAAE,CAAC,GAAG,QAAQ,EAAE,MAAM,EAAE,KAAK,MAAM,CAAA;KAChD;CACF;AAcD;;;;;GAKG;AACH,wBAAgB,KAAK,CAAC,GAAG,EAAE,OAAO,GAAG,CAAC,MAAM,IAAI,CAAC,GAAG,SAAS,CAqB5D;AAED,wBAAwB;AACxB,eAAO,MAAM,IAAI,eAAe,CAAA"}

package/lib/index.js

@@ -0,0 +1,71 @@
+/**
+ * Subagent handoff store: the `handoff_put` / `handoff_get` tool pair plus a
+ * disk-based content-addressed store under `$DSH_HOME/handoff/<projectKey>/`.
+ *
+ * A sandboxed or read-only subagent (e.g. critic, no Write) cannot put a long
+ * report in a repo file; the parent's only channel back would otherwise be
+ * the full final-message text. handoff_put parks the artifact and returns a
+ * short summary embedding `handoff://<id>`; the orchestrator or a follow-up
+ * child resolves it with handoff_get. Cross-session and cross-project
+ * transfer follow the CCR precedent: the project bucket is keyed by the
+ * session cwd, so fetches only resolve within the SAME working directory
+ * (two git worktrees of one repo are different projects — caveat documented
+ * in the package README).
+ *
+ * Plain cordis plugin (publishes no Service — mirror of @dsh-cc/memory): it
+ * no-ops when the tools service, fs seam, or dshHomePath is absent. State is
+ * entirely on disk (TTL 24 h + 500-entry disk-based LRU swept on put), so
+ * spawned children in separate processes see the same store.
+ *
+ * @module @dsh-cc/handoff-store
+ */
+import { HandoffLedger } from "./ledger.js";
+import { registerSettings } from "./settings.js";
+import { HandoffStore } from "./store.js";
+import { defineHandoffGetTool, defineHandoffPutTool } from "./tools.js";
+export { HandoffStore, MAX_ENTRIES, TTL_MS, projectKeyOf } from "./store.js";
+export { HandoffLedger } from "./ledger.js";
+export { registerSettings, SETTINGS_NAMESPACE, SettingsSchema, DEFAULTS, resolveHandoffConfig } from "./settings.js";
+export { defineHandoffPutTool, defineHandoffGetTool, HANDOFF_PUT_TOOL, HANDOFF_GET_TOOL, THRESHOLD_NOTE, HandoffToolError, applyMaxChars, cwdProjectKey, } from "./tools.js";
+function dshHomeFn(ctx) {
+    try {
+        return ctx.dshHomePath;
+    }
+    catch {
+        return undefined;
+    }
+}
+function sessionIdOf(agent) {
+    return agent === undefined ? '' : String(agent.session.id);
+}
+/**
+ * Mount the handoff tools. No-op when the host has no tools service, no fs
+ * seam, or no dshHomePath (a providerless host keeps no handoff surface).
+ * @param ctx - the plug context.
+ * @returns the tools-registration disposer, or `undefined` when not registered.
+ */
+export function apply(ctx) {
+    const tools = ctx.get('tools');
+    const fs = ctx.get('fs');
+    const home = dshHomeFn(ctx);
+    if (tools === undefined || fs === undefined || home === undefined)
+        return undefined;
+    const store = new HandoffStore(home('handoff'));
+    const ledger = new HandoffLedger(home('handoff', 'ledger.jsonl'));
+    const readSettings = registerSettings(ctx);
+    const deps = {
+        store,
+        ledger,
+        readSettings,
+        sessionIdOf,
+    };
+    const offPut = tools.register(defineHandoffPutTool(deps));
+    const offGet = tools.register(defineHandoffGetTool(deps));
+    return () => {
+        offPut();
+        offGet();
+    };
+}
+/** Cordis plugin id. */
+export const name = 'cc-handoff';
+//# sourceMappingURL=index.js.map

package/lib/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;GAoBG;AAIH,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAA;AAChD,OAAO,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AACzC,OAAO,EAAE,oBAAoB,EAAE,oBAAoB,EAAoB,MAAM,YAAY,CAAA;AAEzF,OAAO,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,YAAY,CAAA;AAC5E,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAC3C,OAAO,EAAE,gBAAgB,EAAE,kBAAkB,EAAE,cAAc,EAAE,QAAQ,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAA;AACpH,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,gBAAgB,EAChB,aAAa,EACb,aAAa,GACd,MAAM,YAAY,CAAA;AAcnB,SAAS,SAAS,CAAC,GAAY;IAC7B,IAAI,CAAC;QACH,OAAO,GAAG,CAAC,WAAW,CAAA;IACxB,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,SAAS,CAAA;IAClB,CAAC;AACH,CAAC;AAED,SAAS,WAAW,CAAC,KAAa;IAChC,OAAO,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;AAC5D,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,KAAK,CAAC,GAAY;IAChC,MAAM,KAAK,GAAG,GAAG,CAAC,GAAG,CAAC,OAAO,CAAuD,CAAA;IACpF,MAAM,EAAE,GAAG,GAAG,CAAC,GAAG,CAAC,IAAI,CAAC,CAAA;IACxB,MAAM,IAAI,GAAG,SAAS,CAAC,GAAG,CAAC,CAAA;IAC3B,IAAI,KAAK,KAAK,SAAS,IAAI,EAAE,KAAK,SAAS,IAAI,IAAI,KAAK,SAAS;QAAE,OAAO,SAAS,CAAA;IAEnF,MAAM,KAAK,GAAG,IAAI,YAAY,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC,CAAA;IAC/C,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,IAAI,CAAC,SAAS,EAAE,cAAc,CAAC,CAAC,CAAA;IACjE,MAAM,YAAY,GAAG,gBAAgB,CAAC,GAAG,CAAC,CAAA;IAC1C,MAAM,IAAI,GAAgB;QACxB,KAAK;QACL,MAAM;QACN,YAAY;QACZ,WAAW;KACZ,CAAA;IACD,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAA;IACzD,MAAM,MAAM,GAAG,KAAK,CAAC,QAAQ,CAAC,oBAAoB,CAAC,IAAI,CAAC,CAAC,CAAA;IACzD,OAAO,GAAG,EAAE;QACV,MAAM,EAAE,CAAA;QACR,MAAM,EAAE,CAAA;IACV,CAAC,CAAA;AACH,CAAC;AAED,wBAAwB;AACxB,MAAM,CAAC,MAAM,IAAI,GAAG,YAAY,CAAA"}

package/lib/ledger.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Append-only handoff ledger (`<dshHome>/handoff/ledger.jsonl`).
+ *
+ * One `appendFile` per row (rows are small; appends are atomic enough even
+ * when sibling children interleave rows). The ledger is a rebuildable
+ * observability index, NOT on the read path — `handoff_get` never touches it.
+ * All I/O errors are swallowed: a failed row must never degrade a put.
+ *
+ * @module @dsh-cc/handoff-store/ledger
+ */
+import type { HandoffLedgerRow } from './types.ts';
+export declare class HandoffLedger {
+    private readonly filePath;
+    constructor(filePath: string);
+    /** Append one row; never throws. */
+    append(row: HandoffLedgerRow): Promise<void>;
+}
+//# sourceMappingURL=ledger.d.ts.map

package/lib/ledger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.d.ts","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAElD,qBAAa,aAAa;IACZ,OAAO,CAAC,QAAQ,CAAC,QAAQ;gBAAR,QAAQ,EAAE,MAAM;IAE7C,oCAAoC;IAC9B,MAAM,CAAC,GAAG,EAAE,gBAAgB,GAAG,OAAO,CAAC,IAAI,CAAC;CAQnD"}

package/lib/ledger.js

@@ -0,0 +1,29 @@
+/**
+ * Append-only handoff ledger (`<dshHome>/handoff/ledger.jsonl`).
+ *
+ * One `appendFile` per row (rows are small; appends are atomic enough even
+ * when sibling children interleave rows). The ledger is a rebuildable
+ * observability index, NOT on the read path — `handoff_get` never touches it.
+ * All I/O errors are swallowed: a failed row must never degrade a put.
+ *
+ * @module @dsh-cc/handoff-store/ledger
+ */
+import { appendFile, mkdir } from 'node:fs/promises';
+import { dirname } from 'node:path';
+export class HandoffLedger {
+    filePath;
+    constructor(filePath) {
+        this.filePath = filePath;
+    }
+    /** Append one row; never throws. */
+    async append(row) {
+        try {
+            await mkdir(dirname(this.filePath), { recursive: true });
+            await appendFile(this.filePath, `${JSON.stringify(row)}\n`, 'utf8');
+        }
+        catch {
+            // Best-effort observability; never surface into the tool waterfall.
+        }
+    }
+}
+//# sourceMappingURL=ledger.js.map

package/lib/ledger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ledger.js","sourceRoot":"","sources":["../src/ledger.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAEH,OAAO,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AACpD,OAAO,EAAE,OAAO,EAAE,MAAM,WAAW,CAAA;AAGnC,MAAM,OAAO,aAAa;IACK;IAA7B,YAA6B,QAAgB;QAAhB,aAAQ,GAAR,QAAQ,CAAQ;IAAG,CAAC;IAEjD,oCAAoC;IACpC,KAAK,CAAC,MAAM,CAAC,GAAqB;QAChC,IAAI,CAAC;YACH,MAAM,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC,QAAQ,CAAC,EAAE,EAAE,SAAS,EAAE,IAAI,EAAE,CAAC,CAAA;YACxD,MAAM,UAAU,CAAC,IAAI,CAAC,QAAQ,EAAE,GAAG,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,MAAM,CAAC,CAAA;QACrE,CAAC;QAAC,MAAM,CAAC;YACP,oEAAoE;QACtE,CAAC;IACH,CAAC;CACF"}

package/lib/settings.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Settings namespace registration for the `cc-handoff` overlay.
+ * CCR settings.ts pattern: the namespace is registered once at mount; the
+ * live scope is re-read on EVERY put so a settings write applies immediately.
+ * @module @dsh-cc/handoff-store/settings
+ */
+import z from '@deepseek-ai/schemastery';
+import type { Context } from '@deepseek-ai/cordis';
+import type { SettingsNamespace } from '@deepseek-ai/dsh-settings';
+import type { HandoffConfig } from './types.ts';
+/** The settings namespace carrying the live handoff overlay. */
+export declare const SETTINGS_NAMESPACE: SettingsNamespace;
+/** Defaults, also the documented advisory contract. */
+export declare const DEFAULTS: {
+    enabled: boolean;
+    thresholdChars: number;
+};
+/** Settings namespace schema. */
+export declare const SettingsSchema: z<HandoffConfig>;
+/**
+ * Register the settings namespace and return a per-use reader. Graceful
+ * without a settings provider: the reader resolves `undefined` and callers
+ * fall back to {@link DEFAULTS}.
+ * @param ctx - the plug context.
+ * @returns the live scope reader.
+ */
+export declare function registerSettings(ctx: Context): () => HandoffConfig | undefined;
+/** Effective configuration for one use: defaults overlaid by the live scope. */
+export declare function resolveHandoffConfig(scope: HandoffConfig | undefined): {
+    enabled: boolean;
+    thresholdChars: number;
+};
+//# sourceMappingURL=settings.d.ts.map

package/lib/settings.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.d.ts","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AACxC,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,qBAAqB,CAAA;AAClD,OAAO,KAAK,EAAE,iBAAiB,EAAoB,MAAM,2BAA2B,CAAA;AAEpF,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,YAAY,CAAA;AAE/C,gEAAgE;AAChE,eAAO,MAAM,kBAAkB,EAAmB,iBAAiB,CAAA;AAEnE,uDAAuD;AACvD,eAAO,MAAM,QAAQ;;;CAGnB,CAAA;AAEF,iCAAiC;AACjC,eAAO,MAAM,cAAc,EAAE,CAAC,CAAC,aAAa,CAG1C,CAAA;AAEF;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,GAAG,MAAM,aAAa,GAAG,SAAS,CAI9E;AAED,gFAAgF;AAChF,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,aAAa,GAAG,SAAS,GAAG;IACtE,OAAO,EAAE,OAAO,CAAA;IAChB,cAAc,EAAE,MAAM,CAAA;CACvB,CAKA"}

package/lib/settings.js

@@ -0,0 +1,40 @@
+/**
+ * Settings namespace registration for the `cc-handoff` overlay.
+ * CCR settings.ts pattern: the namespace is registered once at mount; the
+ * live scope is re-read on EVERY put so a settings write applies immediately.
+ * @module @dsh-cc/handoff-store/settings
+ */
+import z from '@deepseek-ai/schemastery';
+import { deepFreeze } from '@deepseek-ai/dsh-util-values';
+/** The settings namespace carrying the live handoff overlay. */
+export const SETTINGS_NAMESPACE = 'cc-handoff';
+/** Defaults, also the documented advisory contract. */
+export const DEFAULTS = deepFreeze({
+    enabled: true,
+    thresholdChars: 8192,
+});
+/** Settings namespace schema. */
+export const SettingsSchema = z.object({
+    enabled: z.boolean(),
+    'threshold-chars': z.number().step(1).min(1),
+});
+/**
+ * Register the settings namespace and return a per-use reader. Graceful
+ * without a settings provider: the reader resolves `undefined` and callers
+ * fall back to {@link DEFAULTS}.
+ * @param ctx - the plug context.
+ * @returns the live scope reader.
+ */
+export function registerSettings(ctx) {
+    const settings = ctx.get('settings');
+    const scope = settings?.register(SETTINGS_NAMESPACE, SettingsSchema);
+    return () => scope?.get?.();
+}
+/** Effective configuration for one use: defaults overlaid by the live scope. */
+export function resolveHandoffConfig(scope) {
+    return {
+        enabled: scope?.enabled ?? DEFAULTS.enabled,
+        thresholdChars: scope?.['threshold-chars'] ?? DEFAULTS.thresholdChars,
+    };
+}
+//# sourceMappingURL=settings.js.map

package/lib/settings.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"settings.js","sourceRoot":"","sources":["../src/settings.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,CAAC,MAAM,0BAA0B,CAAA;AAGxC,OAAO,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAA;AAGzD,gEAAgE;AAChE,MAAM,CAAC,MAAM,kBAAkB,GAAG,YAAiC,CAAA;AAEnE,uDAAuD;AACvD,MAAM,CAAC,MAAM,QAAQ,GAAG,UAAU,CAAC;IACjC,OAAO,EAAE,IAAI;IACb,cAAc,EAAE,IAAI;CACrB,CAAC,CAAA;AAEF,iCAAiC;AACjC,MAAM,CAAC,MAAM,cAAc,GAAqB,CAAC,CAAC,MAAM,CAAC;IACvD,OAAO,EAAE,CAAC,CAAC,OAAO,EAAE;IACpB,iBAAiB,EAAE,CAAC,CAAC,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,CAAC,CAAC;CAC7C,CAAC,CAAA;AAEF;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,GAAY;IAC3C,MAAM,QAAQ,GAAG,GAAG,CAAC,GAAG,CAAC,UAAU,CAAiC,CAAA;IACpE,MAAM,KAAK,GAAG,QAAQ,EAAE,QAAQ,CAAC,kBAAkB,EAAE,cAAc,CAAC,CAAA;IACpE,OAAO,GAAG,EAAE,CAAC,KAAK,EAAE,GAAG,EAAE,EAA+B,CAAA;AAC1D,CAAC;AAED,gFAAgF;AAChF,MAAM,UAAU,oBAAoB,CAAC,KAAgC;IAInE,OAAO;QACL,OAAO,EAAE,KAAK,EAAE,OAAO,IAAI,QAAQ,CAAC,OAAO;QAC3C,cAAc,EAAE,KAAK,EAAE,CAAC,iBAAiB,CAAC,IAAI,QAAQ,CAAC,cAAc;KACtE,CAAA;AACH,CAAC"}

package/lib/store.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Content-addressed, project-keyed store for subagent handoff artifacts.
+ *
+ * Layout: `<root>/<projectKey>/<id>.md` where id = sha256(content
+ * utf8).slice(0,16) + a 4-hex random suffix (globally unique even when two
+ * children store identical content — the suffix makes every put a NEW
+ * artifact), and projectKey = sha256(session cwd).slice(0,16). Flat per
+ * project: no per-session subdir (session lives only in the ledger). Files
+ * are plain UTF-8 JSON envelopes `{v, ts, text, label?, agent?}`; writes are
+ * atomic (temp file + rename). TTL 24 h (authoritative on READ, via the
+ * stored envelope ts) and an LRU cap of 500 entries — both DISK-BASED: the
+ * sweep runs readdir + mtime over the projectKey dir, so a freshly spawned
+ * child process (a new store instance) sees the same eviction state; there is
+ * deliberately no in-memory LRU map. The sweep's TTL pass uses mtime as a
+ * cheap proxy (get() bumps mtime on access); the strict ts check stays on
+ * the read path. Sweep is per-project (the putting session's own bucket).
+ *
+ * @module @dsh-cc/handoff-store/store
+ */
+import type { HandoffError, HandoffMeta } from './types.ts';
+export declare const MAX_ENTRIES = 500;
+export declare const TTL_MS: number;
+/** sha256 hex, first 16 chars. */
+export declare function projectKeyOf(cwd: string): string;
+/** Injectable clock signature (tests pass a fake; never sleep in tests). */
+export type NowFn = () => number;
+export type HandoffResult = {
+    ok: true;
+    text: string;
+    label?: string;
+    agent?: string;
+} | {
+    ok: false;
+    error: HandoffError;
+};
+/**
+ * The handoff store. One instance per mounted plugin; `root` is
+ * `dshHomePath('handoff')`. State is entirely on disk — two instances
+ * (separate child processes) observe the same TTL/LRU behavior. Retrieve
+ * errors are typed, never thrown; sweep never throws.
+ */
+export declare class HandoffStore {
+    readonly root: string;
+    private readonly now;
+    constructor(root: string, now?: NowFn);
+    /** Persist one artifact atomically; returns its 20-hex id. */
+    put(projectKey: string, text: string, meta?: HandoffMeta): Promise<string>;
+    /**
+     * Retrieve one artifact, failing closed on unknown/expired/corrupt. An
+     * expired entry is also deleted lazily. `id` must be exactly 20 hex and
+     * resolves ONLY inside this projectKey's directory — the tool layer keys
+     * projectKey off the fetching session's cwd, so a malformed or
+     * cross-project id can never read outside the store root.
+     */
+    get(projectKey: string, id: string): Promise<HandoffResult>;
+    /**
+     * Disk-based hygiene for one project bucket: readdir + mtime (NO in-memory
+     * bookkeeping — spawned children are separate processes). Drops entries
+     * whose mtime is past the TTL (mtime is bumped on access; the strict
+     * envelope-ts check remains authoritative on read), then LRU-evicts the
+     * oldest by mtime beyond {@link MAX_ENTRIES}. Never throws.
+     */
+    sweep(projectKey: string): Promise<void>;
+}
+//# sourceMappingURL=store.d.ts.map

package/lib/store.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAMH,OAAO,KAAK,EAAE,YAAY,EAAE,WAAW,EAAE,MAAM,YAAY,CAAA;AAE3D,eAAO,MAAM,WAAW,MAAM,CAAA;AAC9B,eAAO,MAAM,MAAM,QAAgB,CAAA;AAKnC,kCAAkC;AAClC,wBAAgB,YAAY,CAAC,GAAG,EAAE,MAAM,GAAG,MAAM,CAEhD;AAED,4EAA4E;AAC5E,MAAM,MAAM,KAAK,GAAG,MAAM,MAAM,CAAA;AAQhC,MAAM,MAAM,aAAa,GACrB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,IAAI,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,GAC1D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,KAAK,EAAE,YAAY,CAAA;CAAE,CAAA;AAEtC;;;;;GAKG;AACH,qBAAa,YAAY;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAA;IACrB,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAO;gBAEf,IAAI,EAAE,MAAM,EAAE,GAAG,GAAE,KAAgB;IAK/C,8DAA8D;IACxD,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,GAAE,WAAgB,GAAG,OAAO,CAAC,MAAM,CAAC;IAcpF;;;;;;OAMG;IACG,GAAG,CAAC,UAAU,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,OAAO,CAAC,aAAa,CAAC;IA2CjE;;;;;;OAMG;IACG,KAAK,CAAC,UAAU,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;CAgC/C"}

package/lib/store.js

@@ -0,0 +1,160 @@
+/**
+ * Content-addressed, project-keyed store for subagent handoff artifacts.
+ *
+ * Layout: `<root>/<projectKey>/<id>.md` where id = sha256(content
+ * utf8).slice(0,16) + a 4-hex random suffix (globally unique even when two
+ * children store identical content — the suffix makes every put a NEW
+ * artifact), and projectKey = sha256(session cwd).slice(0,16). Flat per
+ * project: no per-session subdir (session lives only in the ledger). Files
+ * are plain UTF-8 JSON envelopes `{v, ts, text, label?, agent?}`; writes are
+ * atomic (temp file + rename). TTL 24 h (authoritative on READ, via the
+ * stored envelope ts) and an LRU cap of 500 entries — both DISK-BASED: the
+ * sweep runs readdir + mtime over the projectKey dir, so a freshly spawned
+ * child process (a new store instance) sees the same eviction state; there is
+ * deliberately no in-memory LRU map. The sweep's TTL pass uses mtime as a
+ * cheap proxy (get() bumps mtime on access); the strict ts check stays on
+ * the read path. Sweep is per-project (the putting session's own bucket).
+ *
+ * @module @dsh-cc/handoff-store/store
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { readdirSync, rmSync, statSync, utimesSync } from 'node:fs';
+import { mkdir, readFile, rename, writeFile } from 'node:fs/promises';
+import { join } from 'node:path';
+export const MAX_ENTRIES = 500;
+export const TTL_MS = 24 * 3600_000;
+const ID_RE = /^[0-9a-f]{20}$/;
+/** sha256 hex, first 16 chars — the shared project-key shape (CCR store.ts). */
+const KEY_LEN = 16;
+/** sha256 hex, first 16 chars. */
+export function projectKeyOf(cwd) {
+    return createHash('sha256').update(cwd, 'utf8').digest('hex').slice(0, KEY_LEN);
+}
+/**
+ * The handoff store. One instance per mounted plugin; `root` is
+ * `dshHomePath('handoff')`. State is entirely on disk — two instances
+ * (separate child processes) observe the same TTL/LRU behavior. Retrieve
+ * errors are typed, never thrown; sweep never throws.
+ */
+export class HandoffStore {
+    root;
+    now;
+    constructor(root, now = Date.now) {
+        this.root = root;
+        this.now = now;
+    }
+    /** Persist one artifact atomically; returns its 20-hex id. */
+    async put(projectKey, text, meta = {}) {
+        const id = `${createHash('sha256').update(text, 'utf8').digest('hex').slice(0, KEY_LEN)}${randomBytes(2).toString('hex')}`;
+        const dir = join(this.root, projectKey);
+        const file = join(dir, `${id}.md`);
+        const envelope = { v: 1, ts: this.now(), text, ...meta };
+        await mkdir(dir, { recursive: true });
+        // Atomic write: same-directory temp file + rename (CCR store pattern).
+        const tmp = `${file}.tmp-${randomBytes(6).toString('hex')}`;
+        await writeFile(tmp, JSON.stringify(envelope), 'utf8');
+        await rename(tmp, file);
+        void this.sweep(projectKey); // sweep-on-put, fire-and-forget
+        return id;
+    }
+    /**
+     * Retrieve one artifact, failing closed on unknown/expired/corrupt. An
+     * expired entry is also deleted lazily. `id` must be exactly 20 hex and
+     * resolves ONLY inside this projectKey's directory — the tool layer keys
+     * projectKey off the fetching session's cwd, so a malformed or
+     * cross-project id can never read outside the store root.
+     */
+    async get(projectKey, id) {
+        if (!ID_RE.test(id))
+            return { ok: false, error: 'unknown_id' };
+        const file = join(this.root, projectKey, `${id}.md`);
+        // Belt-and-suspenders against future shape changes: the id must name a
+        // direct child of the project directory, never anything outside it.
+        if (join(file) !== join(this.root, projectKey, `${id}.md`))
+            return { ok: false, error: 'unknown_id' };
+        let body;
+        try {
+            body = await readFile(file, 'utf8');
+        }
+        catch {
+            return { ok: false, error: 'unknown_id' };
+        }
+        let envelope;
+        try {
+            const parsed = JSON.parse(body);
+            if (typeof parsed !== 'object' || parsed === null
+                || parsed.v !== 1 || typeof parsed.ts !== 'number'
+                || typeof parsed.text !== 'string')
+                throw new Error('shape');
+            envelope = parsed;
+        }
+        catch {
+            return { ok: false, error: 'corrupt' };
+        }
+        if (this.now() - envelope.ts > TTL_MS) {
+            try {
+                rmSync(file, { force: true }); // lazy TTL delete
+            }
+            catch {
+                // best-effort
+            }
+            return { ok: false, error: 'expired' };
+        }
+        // LRU touch on disk: bump mtime so the sweep keeps hot entries.
+        try {
+            const t = this.now() / 1000;
+            utimesSync(file, t, t);
+        }
+        catch {
+            // best-effort
+        }
+        const { label, agent } = envelope;
+        return (label === undefined && agent === undefined)
+            ? { ok: true, text: envelope.text }
+            : { ok: true, text: envelope.text, ...(label === undefined ? {} : { label }), ...(agent === undefined ? {} : { agent }) };
+    }
+    /**
+     * Disk-based hygiene for one project bucket: readdir + mtime (NO in-memory
+     * bookkeeping — spawned children are separate processes). Drops entries
+     * whose mtime is past the TTL (mtime is bumped on access; the strict
+     * envelope-ts check remains authoritative on read), then LRU-evicts the
+     * oldest by mtime beyond {@link MAX_ENTRIES}. Never throws.
+     */
+    async sweep(projectKey) {
+        try {
+            const dir = join(this.root, projectKey);
+            const now = this.now();
+            const aged = [];
+            for (const name of readdirSync(dir)) {
+                if (!name.endsWith('.md') || !ID_RE.test(name.slice(0, -3)))
+                    continue;
+                try {
+                    const mtime = statSync(join(dir, name)).mtimeMs;
+                    if (now - mtime > TTL_MS) {
+                        rmSync(join(dir, name), { force: true });
+                        continue;
+                    }
+                    aged.push({ name, mtime });
+                }
+                catch {
+                    // lost a race with a sibling sweep; skip
+                }
+            }
+            // ponytail: full sort of ≤500 entries per put — fine at this scale;
+            // heap only if the cap grows orders of magnitude.
+            aged.sort((a, b) => a.mtime - b.mtime);
+            for (const entry of aged.slice(0, Math.max(0, aged.length - MAX_ENTRIES))) {
+                try {
+                    rmSync(join(dir, entry.name), { force: true });
+                }
+                catch {
+                    // best-effort
+                }
+            }
+        }
+        catch {
+            // Sweep is best-effort hygiene; a failure must never reach the tool.
+        }
+    }
+}
+//# sourceMappingURL=store.js.map

package/lib/store.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"store.js","sourceRoot":"","sources":["../src/store.ts"],"names":[],"mappings":"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"}

package/lib/tools.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The `handoff_put` / `handoff_get` agent tools over the handoff store.
+ *
+ * `handoff_put` parks a large artifact (review body, long plan, bulk
+ * findings) in the store and returns a short summary embedding the
+ * `handoff://<id>` handle; the orchestrator or a follow-up child resolves it
+ * with `handoff_get({ id })` — the sibling-transfer path. The threshold in
+ * the description is the ADVISORY contract only (see cc-handoff.threshold-chars):
+ * put never enforces or rejects on size. `handoff_get` derives the project
+ * bucket from the FETCHING session's cwd (CCR `context_retrieve` precedent),
+ * so only sessions in the SAME working directory can fetch — two git
+ * worktrees of one repo are different projects by design.
+ *
+ * @module @dsh-cc/handoff-store/tools
+ */
+import type { Agent } from '@deepseek-ai/dsh-agent';
+import { HandoffLedger } from './ledger.ts';
+import { HandoffStore } from './store.ts';
+import type { HandoffConfig } from './types.ts';
+export declare const HANDOFF_PUT_TOOL = "handoff_put";
+export declare const HANDOFF_GET_TOOL = "handoff_get";
+/** Advisory-threshold sentence shared by the put description and the tool note. */
+export declare const THRESHOLD_NOTE: string;
+/** A model-visible handoff failure (maps to an isError tool result). */
+export declare class HandoffToolError extends Error {
+}
+export interface HandoffDeps {
+    store: HandoffStore;
+    ledger: HandoffLedger;
+    readSettings: () => HandoffConfig | undefined;
+    sessionIdOf(agent?: Agent): string;
+}
+/** sha256(session cwd), 16 hex — or undefined when the cwd is unavailable. */
+export declare function cwdProjectKey(agent: Agent | undefined): string | undefined;
+/** Head-truncate with a trailing note when `maxChars` cuts the text. */
+export declare function applyMaxChars(text: string, maxChars: number | undefined): string;
+export declare function defineHandoffPutTool(deps: HandoffDeps): import("@dsh-cc/tools").ToolDefinition;
+export declare function defineHandoffGetTool(deps: HandoffDeps): import("@dsh-cc/tools").ToolDefinition;
+//# sourceMappingURL=tools.d.ts.map

package/lib/tools.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.d.ts","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG;AAEH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,wBAAwB,CAAA;AAGnD,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAA;AAE3C,OAAO,EAAE,YAAY,EAAgB,MAAM,YAAY,CAAA;AACvD,OAAO,KAAK,EAAE,aAAa,EAAe,MAAM,YAAY,CAAA;AAE5D,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAC7C,eAAO,MAAM,gBAAgB,gBAAgB,CAAA;AAE7C,mFAAmF;AACnF,eAAO,MAAM,cAAc,QAE0B,CAAA;AAErD,wEAAwE;AACxE,qBAAa,gBAAiB,SAAQ,KAAK;CAAG;AAE9C,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,YAAY,CAAA;IACnB,MAAM,EAAE,aAAa,CAAA;IACrB,YAAY,EAAE,MAAM,aAAa,GAAG,SAAS,CAAA;IAC7C,WAAW,CAAC,KAAK,CAAC,EAAE,KAAK,GAAG,MAAM,CAAA;CACnC;AAED,8EAA8E;AAC9E,wBAAgB,aAAa,CAAC,KAAK,EAAE,KAAK,GAAG,SAAS,GAAG,MAAM,GAAG,SAAS,CAO1E;AAED,wEAAwE;AACxE,wBAAgB,aAAa,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,GAAG,SAAS,GAAG,MAAM,CAKhF;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,0CAwErD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,0CA+BrD"}

package/lib/tools.js

@@ -0,0 +1,153 @@
+/**
+ * The `handoff_put` / `handoff_get` agent tools over the handoff store.
+ *
+ * `handoff_put` parks a large artifact (review body, long plan, bulk
+ * findings) in the store and returns a short summary embedding the
+ * `handoff://<id>` handle; the orchestrator or a follow-up child resolves it
+ * with `handoff_get({ id })` — the sibling-transfer path. The threshold in
+ * the description is the ADVISORY contract only (see cc-handoff.threshold-chars):
+ * put never enforces or rejects on size. `handoff_get` derives the project
+ * bucket from the FETCHING session's cwd (CCR `context_retrieve` precedent),
+ * so only sessions in the SAME working directory can fetch — two git
+ * worktrees of one repo are different projects by design.
+ *
+ * @module @dsh-cc/handoff-store/tools
+ */
+import { defineTool } from '@dsh-cc/tools';
+import { getSessionCwd } from '@dsh-cc/session-cwd';
+import { resolveHandoffConfig } from "./settings.js";
+import { projectKeyOf } from "./store.js";
+export const HANDOFF_PUT_TOOL = 'handoff_put';
+export const HANDOFF_GET_TOOL = 'handoff_get';
+/** Advisory-threshold sentence shared by the put description and the tool note. */
+export const THRESHOLD_NOTE = 'Default 8192 (see cc-handoff.threshold-chars). The threshold is advisory: '
+    + 'handoff_put never rejects or truncates on size.';
+/** A model-visible handoff failure (maps to an isError tool result). */
+export class HandoffToolError extends Error {
+}
+/** sha256(session cwd), 16 hex — or undefined when the cwd is unavailable. */
+export function cwdProjectKey(agent) {
+    if (agent === undefined)
+        return undefined;
+    try {
+        return projectKeyOf(getSessionCwd(agent));
+    }
+    catch {
+        return undefined;
+    }
+}
+/** Head-truncate with a trailing note when `maxChars` cuts the text. */
+export function applyMaxChars(text, maxChars) {
+    if (maxChars === undefined || !Number.isFinite(maxChars) || maxChars < 1 || text.length <= maxChars) {
+        return text;
+    }
+    return `${text.slice(0, maxChars)}\n\n[dsh-cc handoff truncated at ${maxChars} of ${text.length} chars; full text: use handoff_get]`;
+}
+export function defineHandoffPutTool(deps) {
+    return defineTool({
+        name: HANDOFF_PUT_TOOL,
+        description: 'Park a large artifact (a long review, plan, or report that would flood the parent context) in the '
+            + 'durable handoff store and return a short summary with a `handoff://<id>` handle. Use it BEFORE '
+            + 'writing a big report into your final message: return the summary (at most ~2 KB) and embed the '
+            + 'handle; the orchestrator or a follow-up child fetches the full text with handoff_get. '
+            + 'Retention 24 h; visible to sessions in the SAME working directory only. '
+            + `Threshold: ${THRESHOLD_NOTE}`,
+        parameters: {
+            content: {
+                type: 'string',
+                required: true,
+                description: 'The full artifact text to store. Stored verbatim; never truncated by the tool.',
+            },
+            label: {
+                type: 'string',
+                description: 'Short one-line label describing the artifact (e.g. "review of PR #12").',
+            },
+            agent: {
+                type: 'string',
+                description: 'Originating agent name, when known (defaults to the calling agent, if it has one).',
+            },
+        },
+        output: {
+            schema: {
+                type: 'object',
+                additionalProperties: false,
+                properties: {
+                    id: { type: 'string', required: true },
+                    message: { type: 'string', required: true },
+                },
+            },
+            render: (_args, value) => [{ type: 'text', text: value.message }],
+        },
+        async execute(args, exec) {
+            const cfg = resolveHandoffConfig(deps.readSettings());
+            if (!cfg.enabled)
+                throw new HandoffToolError('handoff_put unavailable: cc-handoff.enabled is false');
+            const projectKey = cwdProjectKey(exec.agent);
+            if (projectKey === undefined)
+                throw new HandoffToolError('handoff_put unavailable: no session cwd');
+            const content = args.content;
+            if (typeof content !== 'string' || content.length === 0) {
+                throw new HandoffToolError('handoff_put: content must be a non-empty string');
+            }
+            const agentName = args.agent ?? (exec.agent === undefined ? undefined : exec.agent.name);
+            const meta = {
+                ...(args.label === undefined ? {} : { label: args.label }),
+                ...(agentName === undefined ? {} : { agent: agentName }),
+            };
+            const id = await deps.store.put(projectKey, content, meta);
+            const chars = content.length;
+            await deps.ledger.append({
+                ts: new Date().toISOString(),
+                project: projectKey,
+                sessionId: deps.sessionIdOf(exec.agent),
+                id,
+                ...(meta.label === undefined ? {} : { label: meta.label }),
+                ...(meta.agent === undefined ? {} : { agent: meta.agent }),
+                chars,
+            });
+            // Advisory note only — the threshold is never enforced (design decision 5).
+            const over = chars > cfg.thresholdChars
+                ? ` Over the ${cfg.thresholdChars}-char advisory threshold: your final message should carry only a short summary (≤2 KB) plus the handoff://<id> handle below.`
+                : '';
+            return {
+                id,
+                message: `Stored handoff artifact ${id} (${chars} chars, retention 24h). Reference: handoff://${id}`
+                    + `${over} Fetch it with handoff_get({ id: "${id}" }) — same working directory only.`,
+            };
+        },
+    });
+}
+export function defineHandoffGetTool(deps) {
+    return defineTool({
+        name: HANDOFF_GET_TOOL,
+        description: 'Fetch the FULL text of an artifact a subagent parked with handoff_put, using the 20-hex id from its '
+            + '`handoff://<id>` handle. Only sessions in the SAME working directory as the putting session can '
+            + 'resolve a handle. Pass maxChars to read a head-truncated prefix when you only need an overview. '
+            + 'Artifacts expire after 24 hours.',
+        parameters: {
+            id: {
+                type: 'string',
+                required: true,
+                description: 'The 20-hex id from a `handoff://<id>` handle.',
+            },
+            maxChars: {
+                type: 'number',
+                description: 'Head-truncate the returned text to this many chars, with a trailing truncation note. Omit for the full text.',
+            },
+        },
+        output: {
+            schema: { type: 'object', additionalProperties: false, properties: { text: { type: 'string', required: true } } },
+            render: (_args, value) => [{ type: 'text', text: value.text }],
+        },
+        async execute(args, exec) {
+            const projectKey = cwdProjectKey(exec.agent);
+            if (projectKey === undefined)
+                throw new HandoffToolError('handoff_get unavailable: no session cwd');
+            const outcome = await deps.store.get(projectKey, args.id);
+            if (!outcome.ok)
+                throw new HandoffToolError(`handoff_get failed: ${outcome.error}`);
+            return { text: applyMaxChars(outcome.text, args.maxChars) };
+        },
+    });
+}
+//# sourceMappingURL=tools.js.map

package/lib/tools.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"tools.js","sourceRoot":"","sources":["../src/tools.ts"],"names":[],"mappings":"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"}

package/lib/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Types for the subagent handoff store.
+ * @module @dsh-cc/handoff-store/types
+ */
+/** Optional metadata attached to one handoff artifact. */
+export interface HandoffMeta {
+    /** Short human/model-facing label (e.g. "critic review of plan X"). */
+    readonly label?: string;
+    /** Originating agent name, when known (e.g. "critic"). */
+    readonly agent?: string;
+}
+/**
+ * Live settings scope shape for the `cc-handoff` namespace. Kebab keys match
+ * the settings keys exactly.
+ */
+export interface HandoffConfig {
+    /** Master flag. Defaults to `true`. */
+    enabled?: boolean;
+    /**
+     * Advisory size threshold in chars: reports/artifacts above it should be
+     * handed off with a summary. ADVISORY ONLY — `handoff_put` never enforces
+     * or rejects on it.
+     */
+    'threshold-chars'?: number;
+}
+/** One append-only handoff-ledger row (`handoff/ledger.jsonl`). */
+export interface HandoffLedgerRow {
+    readonly ts: string;
+    /** Project bucket key (sha256 of the putting session's cwd, 16 hex). */
+    readonly project: string;
+    readonly sessionId: string;
+    readonly id: string;
+    readonly label?: string;
+    readonly agent?: string;
+    readonly chars: number;
+}
+/** Typed retrieval failure for one handoff lookup. */
+export type HandoffError = 'unknown_id' | 'expired' | 'corrupt';
+//# sourceMappingURL=types.d.ts.map

package/lib/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,uEAAuE;IACvE,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,0DAA0D;IAC1D,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CACxB;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,uCAAuC;IACvC,OAAO,CAAC,EAAE,OAAO,CAAA;IACjB;;;;OAIG;IACH,iBAAiB,CAAC,EAAE,MAAM,CAAA;CAC3B;AAED,mEAAmE;AACnE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,wEAAwE;IACxE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;IAC1B,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAA;IACnB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAA;IACvB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CACvB;AAED,sDAAsD;AACtD,MAAM,MAAM,YAAY,GAAG,YAAY,GAAG,SAAS,GAAG,SAAS,CAAA"}

package/lib/types.js

@@ -0,0 +1,6 @@
+/**
+ * Types for the subagent handoff store.
+ * @module @dsh-cc/handoff-store/types
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/lib/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;GAGG"}

package/package.json

@@ -0,0 +1,49 @@
+{
+  "name": "@dsh-cc/handoff-store",
+  "description": "Subagent handoff store: handoff_put/handoff_get let sandboxed subagents park large artifacts in a content-addressed store and hand back a handoff://<id> handle",
+  "version": "0.6.2",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/dsh-cc/dsh-cc.git",
+    "directory": "packages/subagent/handoff-store"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./lib/index.d.ts",
+      "default": "./lib/index.js"
+    },
+    "./store": {
+      "types": "./lib/store.d.ts",
+      "default": "./lib/store.js"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "lib"
+  ],
+  "license": "Apache-2.0",
+  "peerDependencies": {
+    "@deepseek-ai/cordis": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-settings": ">=0.1.2-rc.1",
+    "@deepseek-ai/schemastery": "^3.18.1",
+    "@deepseek-ai/dsh-util-values": ">=0.1.2-rc.1",
+    "@deepseek-ai/dsh-agent": ">=0.1.2-rc.1",
+    "@dsh-cc/tools": "^0.6.2",
+    "@dsh-cc/session-cwd": "^0.6.2"
+  },
+  "devDependencies": {
+    "@deepseek-ai/cordis": "link:../../../../deepseek-harness/vendor/cordis",
+    "@deepseek-ai/dsh-agent": "link:../../../../deepseek-harness/packages/core/agent",
+    "@deepseek-ai/dsh-settings": "link:../../../../deepseek-harness/packages/settings/settings",
+    "@deepseek-ai/schemastery": "link:../../../../deepseek-harness/vendor/schemastery",
+    "@deepseek-ai/dsh-util-values": "link:../../../../deepseek-harness/packages/util/values",
+    "vitest": "^4.1.8",
+    "@dsh-cc/session-cwd": "^0.6.2",
+    "@dsh-cc/tools": "^0.6.2"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}