prime-agent-dsh 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), and this project intends to follow [Semantic Versioning](https://semver.org/spec/v2.0.0.html) once its public API stabilizes.
+
+## Unreleased
+
+### Documentation
+
+- Added production-oriented installation, support, contribution, conduct, roadmap, and release documentation.
+
+## 0.2.0 - 2026-09-21
+
+### Added
+
+- Per-root and per-native-RLM-child context scopes.
+- Immutable branch snapshots, bounded transcript reads and search, private artifacts, and explicit durable admission through the `dsh-context` Python skill.
+- Automatic bounded parent-to-child evidence capsules and explicit expiring context grants.
+- Provider-reported turn and session cache metrics in a native Prime widget.
+- Incremental append-only Prime JSONL reference indexing with verified rebuild and recovery paths.
+- Optional diagnostic-only shadow telemetry.
+
+### Changed
+
+- Reworked the integration as a fail-open context sidecar around Prime's native `AgentSession`.
+- Made Prime JSONL the sole canonical full-content history and Prime the sole model, tool, session, branching, deletion, and compaction authority.
+- Reduced user commands to `/dsh`, `/dsh on`, and `/dsh off`; these control display only.
+- Pinned DeepSeek Harness dependencies to `0.1.6-alpha.2` and set the runtime target to Prime Agent 0.9.5 or newer.
+
+### Removed
+
+- DSH-driven compaction and warm-prefix compaction behavior.
+- Alternate DSH agent loops, provider wrappers, ACP delegation, and independent conversation authority from the supported design.
+
+### Security
+
+- Added bounded stores, verified locators and digests, restrictive file modes, quota/free-space checks, grant expiry, and fail-open handling.
+- Clarified that same-OS-user processes remain outside the filesystem threat boundary.
+
+## 0.1.0 - 2026-09-01
+
+### Added
+
+- Initial experimental Prime Agent and DeepSeek Harness integration.
+
+### Notes
+
+- The 0.1.x line explored routing, shadow context, persistence, and compaction approaches. Those experiments are not the authority model supported by 0.2.0.
+- No npm release is asserted for this version; repository history is the source of record.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 prime-agent-dsh contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,121 @@
+# prime-agent-dsh
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+[![Node.js](https://img.shields.io/badge/node-%5E22.19.0%20%7C%7C%20%3E%3D24-339933.svg)](package.json)
+[![Status: developer preview](https://img.shields.io/badge/status-developer%20preview-orange.svg)](#project-status)
+
+A context sidecar for Prime Agent. It turns the active Prime branch into a searchable, rebuildable DeepSeek Harness (DSH) projection, exposes bounded context tools in Python, and reports provider cache use. Prime remains the only agent loop and the only session authority.
+
+> **Not published to npm.** Install from this GitHub repository or a local checkout. The pinned DeepSeek Harness `0.1.6-alpha.2` dependencies are also developer previews.
+
+## Why use it?
+
+- Search and inspect a long Prime session without placing the whole transcript in the next request.
+- Pin immutable views, create private artifacts, and explicitly admit selected evidence.
+- Give native RLM descendants bounded inherited evidence or an explicit expiring grant.
+- See provider-reported turn and session cache rates in a native Prime widget.
+- Keep failures non-blocking: projection errors leave the Prime request unchanged.
+
+## Quick start
+
+Requirements, source installation, verification, upgrades, removal, and troubleshooting are in **[Getting started](docs/getting-started.md)**.
+
+```bash
+git clone https://github.com/moreWax/prime-agent-dsh.git
+cd prime-agent-dsh
+npm install
+npm run release:check
+prime-agent package install "$PWD"
+```
+
+Restart Prime Agent after installation. Then run `/dsh` and try `dsh_context.current()` in IPython.
+
+## Architecture invariants
+
+1. **Prime owns inference.** Prime selects models, streams responses, authenticates, retries, and controls approvals.
+2. **Prime owns execution.** Tools, IPython, skills, MCP, native `rlm.spawn`, and goals stay in Prime's loop.
+3. **Prime owns content and lifecycle.** Prime JSONL is the only full-content session authority. Prime alone branches, compacts, and deletes sessions.
+4. **DSH is derived and fail-open.** Its per-session projection and indexes are bounded, content-addressed, and rebuildable. DSH does not compact Prime context.
+5. **Scopes stay isolated.** Each root and native RLM child gets its own scope. Sharing uses a bounded capsule or explicit grant, never a live transcript or parent authority.
+6. **Admission is explicit.** Reading DSH data does not silently add it to model context. Printed or returned `ctx.inject(...)` output becomes a normal Prime tool result.
+
+The package does not ship a DSH `AgentLoop`, provider wrapper, ACP delegation path, custom model loop, or independent conversation store. See [Single-window cache architecture](docs/single-window-cache-architecture.md).
+
+## Feature status
+
+| Capability | Status | Notes |
+|---|---|---|
+| Active-branch projection | Available | Append/no-op/rebuild tracking; Prime JSONL stays canonical. |
+| Transcript reads and search | Available | Bounded Python API over immutable session snapshots. |
+| Snapshots and private artifacts | Available | Content-addressed and stored in the matching session artifacts. |
+| Explicit context admission | Available | Use `ctx.inject(...)`; Prime records the resulting tool output. |
+| Native RLM inheritance | Available | Bounded untrusted evidence through Prime 0.9.5 lifecycle hooks. |
+| Explicit parent-to-child grants | Available | Bounded, read-only, expiring capabilities. |
+| Provider cache metrics | Available when reported | No cache hit is inferred if the provider omits usage fields. |
+| `/dsh` display toggle | Available | Changes widget visibility only; indexing continues. |
+| Shadow telemetry | Optional | Diagnostic only; never changes provider context. |
+| DSH-driven compaction | Not included | Prime alone decides and performs compaction. |
+| DSH agent loop or tools | Not included | Would create a second execution authority. |
+| npm installation | Not available | Source installation only for this release. |
+
+## Python API at a glance
+
+```python
+ctx = dsh_context.current()
+ctx.entries(last=10)
+ctx.messages(last=10)
+ctx.search("authentication", limit=20)
+ctx.metrics
+
+snapshot = ctx.snapshot()
+selection = ctx.search("migration decision", limit=8)
+artifact = ctx.artifact(selection, label="Migration evidence")
+print(ctx.inject(selection, label="Relevant migration decisions"))
+```
+
+For grants and API rules, see [Getting started](docs/getting-started.md#use-the-python-context-skill) and the [`dsh-context` skill reference](skills/dsh-context/SKILL.md).
+
+## Configuration
+
+| Variable | Default | Purpose |
+|---|---:|---|
+| `PRIME_DSH_CACHE_DISPLAY` | `on` | Initial cache-rate widget visibility. Set `off` to hide it. |
+| `PRIME_DSH_SHADOW_MODE` | `off` | Enable a second diagnostic-only round-trip mirror. |
+| `PRIME_DSH_SHADOW_MAX_MESSAGES` | `500` | Bound shadow work by message count. |
+| `PRIME_DSH_SHADOW_MAX_BYTES` | `4194304` | Bound shadow work by serialized bytes. |
+
+## Documentation
+
+- [Getting started](docs/getting-started.md)
+- [Single-window cache architecture](docs/single-window-cache-architecture.md)
+- [Durable context query](docs/durable-context-query.md)
+- [Context spill](docs/context-spill.md)
+- [Shadow telemetry validation](docs/shadow-telemetry-validation.md)
+- [Contributing](CONTRIBUTING.md)
+- [Support](SUPPORT.md)
+- [Roadmap](ROADMAP.md)
+- [Changelog](CHANGELOG.md)
+- [Code of Conduct](CODE_OF_CONDUCT.md)
+
+## Project status
+
+`0.2.0` is a developer preview. The Prime integration, storage formats, and Python API may change before a stable release. The test suite covers the documented core paths, but this package is not a security boundary against another process running as the same OS user.
+
+The current runtime target is Prime Agent `0.9.5` or newer (`@earendil-works/pi-coding-agent >=0.86.1`). See the [roadmap](ROADMAP.md) for direction rather than release promises.
+
+## Development and validation
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run test:python
+npm run package:smoke
+npm run release:check
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) before proposing a change. Preserve the Prime-only authority model.
+
+## License
+
+[MIT](LICENSE). Bundled dependency notices are in [THIRD_PARTY_NOTICES.md](THIRD_PARTY_NOTICES.md).

package/SECURITY.md

@@ -0,0 +1,27 @@
+# Security policy
+
+## Supported versions
+
+Security fixes are released on the current minor line. Upgrade to the newest patch before reporting a problem.
+
+| Version | Supported |
+| --- | --- |
+| 0.2.x | Yes |
+| 0.1.x and earlier | No |
+
+Support for a release also requires a Node.js version allowed by that release's `engines` field and supported Prime peer dependencies.
+
+## Report a vulnerability
+
+Please report vulnerabilities privately with [GitHub Security Advisories](https://github.com/moreWax/prime-agent-dsh/security/advisories/new). Do not open a public issue, discussion, or pull request for an unpatched vulnerability. Include the affected version, platform, impact, reproduction steps or a minimal proof of concept, and any suggested mitigation. Remove real credentials and private transcripts.
+
+We aim to acknowledge a report within five business days and provide a status update within ten business days. These are targets, not guarantees or an SLA. Timing depends on severity, reproducibility, maintainer availability, and coordinated disclosure needs. We will work with the reporter on disclosure after a fix or practical mitigation is available.
+
+## Security model
+
+Read the full [security and operations guide](docs/security.md) before deploying the package. Important limits are:
+
+- Prime's session JSONL is the sole authority for transcript content. DSH indexes and projections are derived and rebuildable.
+- DSH protects against accidental traversal, symlink substitution, corruption, and cross-session reuse. It is not a sandbox against another process running as the same OS user.
+- Session artifacts contain sensitive metadata and can contain selected context, exact task prompts, user-created artifacts, grants, and attachments. Treat the whole session tree as confidential.
+- DSH does not replace Prime's provider, retention, deletion, authentication, backup, or secret-management controls.

package/THIRD_PARTY_NOTICES.md

@@ -0,0 +1,3 @@
+# Third-party notices
+
+This package uses DeepSeek Harness context, session, and attachment components and Prime Agent packages under their respective licenses. See the installed dependency packages for their license texts and notices.

package/docs/context-spill.md

@@ -0,0 +1,7 @@
+# Durable context spill and generic attachments
+
+`src/durable-file-attachments.ts` uses the verbatim file primitives added in `@deepseek-ai/dsh-attachment` and `@deepseek-ai/dsh-attachment-local` **0.1.6** (this package currently pins `0.1.6-alpha.2`). It needs those versions or a later compatible release. Files are provider-neutral, content-addressed, atomically published with private modes, and verified during every read.
+
+`spillContextText()` stores an oversized UTF-8 value and returns a bounded preview plus a serializable locator. If storage or quota enforcement fails it returns the exact value inline. Keep locators in durable session data. A later process can reconstruct `DurableFileAttachments` with the same absolute `dshHome` and call `resolveContextSpill()`.
+
+Set `maxObjectBytes`, `maxTotalBytes`, and `maxObjects` at construction. Call `cleanup(liveReferences)` only with a complete set of live generic-file references. Cleanup does not touch images.

package/docs/durable-context-query.md

@@ -0,0 +1,34 @@
+# Durable context query adapter
+
+`src/durable-context-query.ts` is a read-only query layer for
+`DurableContextStore` commits. Prime's JSONL is the only full-content authority. The
+publication store and every search view are derived and can be deleted and
+rebuilt from Prime through the publisher.
+
+The adapter intentionally has no new runtime dependency. Version
+`0.1.6-alpha.2` of `@deepseek-ai/dsh-session-query` queries DSH Session event
+logs through a Cordis service, while these records are Prime-derived context
+checkpoints with content-addressed commit provenance. Its SQLite provider has
+the same Session-event schema and therefore is not a safe direct index for this
+format. If a future persistent FTS index is added, it should be an optional
+cache keyed by `bindingDigest`, `commitDigest`, `objectDigest`, entry digest,
+and extractor version. It must never become query or recovery authority.
+
+## Guarantees
+
+- The constructor verifies `BINDING` against both the session ID and canonical
+  Prime file path. A store cannot be opened through another session binding.
+- Every head, commit, object, locator, source-entry digest, and source aggregate
+  digest is checked before use. Effective hashes are provenance metadata; an
+  effective entry is returned only when it can be reconstructed losslessly.
+  A bad checkpoint is skipped and counted.
+- Literal matching is case-insensitive and whitespace-flexible. Regex patterns
+  and flags are bounded. Full-text ranking uses deterministic BM25-style scores
+  and stable tie breaks.
+- Cursors bind the complete query and a maximum generation. Later publications
+  do not change pages already in progress. Cursors remain usable after process
+  restart because their authority is immutable commits, not process memory.
+- Checkpoint count, query bytes, scanned entries, page size, and cursor bytes
+  have explicit bounds.
+- V3 source hits are dereferenced from the bound Prime JSONL and verify locator, ID, and digest. Effective hits are reconstructed only when a source mapping exists; `trace.exactBody` says whether reconstruction is byte-semantically exact.
+- V3-reference is the sole supported derived-store format. Old cache schemas are discarded and rebuilt from Prime JSONL, not migrated or maintained.

package/docs/getting-started.md

@@ -0,0 +1,253 @@
+# Getting started
+
+This guide installs `prime-agent-dsh` from source. Version 0.2.0 is **not published to npm**.
+
+## Requirements
+
+- Prime Agent `0.9.5` or newer.
+- Node.js `^22.19.0` or `>=24.0.0`.
+- npm and Git.
+- A Prime provider that reports cache usage if you want cache-rate values. The context features do not require those metrics.
+- Write access to the Prime configuration and session-artifact locations used by your installation.
+
+Check the tools that are on your path:
+
+```bash
+prime-agent --version
+node --version
+npm --version
+git --version
+```
+
+The package declares `@earendil-works/pi-coding-agent >=0.86.1` and related Prime packages as peer dependencies. `npm install` installs the pinned DSH runtime dependencies and development tools.
+
+## Install from GitHub
+
+Clone the repository, validate the exact checkout, and register that checkout with Prime:
+
+```bash
+git clone https://github.com/moreWax/prime-agent-dsh.git
+cd prime-agent-dsh
+npm install
+npm run release:check
+prime-agent package install "$PWD"
+```
+
+Use a tagged release or reviewed commit when one is available. The default branch can contain unreleased work. Do not use `npm install -g prime-agent-dsh` or `npm install prime-agent-dsh`; no npm package is published for this release.
+
+## Install for one project
+
+If you already have a trusted checkout and want activation only in the current project, run this **from the project that should use the package**:
+
+```bash
+prime-agent package install --local /absolute/path/to/prime-agent-dsh
+```
+
+Without `--local`, Prime registers the package in the user configuration. With `--local`, Prime registers it in the current project's configuration. The source checkout still needs its dependencies:
+
+```bash
+cd /absolute/path/to/prime-agent-dsh
+npm install
+npm run release:check
+```
+
+For extension development without registration, Prime also supports:
+
+```bash
+cd /absolute/path/to/prime-agent-dsh
+prime-agent -e ./extensions/index.ts
+```
+
+Use that command only for a development run. Do not also activate the installed copy in the same run.
+
+## Restart and verify
+
+Package registration does not change an already running Prime process. Exit all Prime Agent processes that should load the package, then start Prime again. A new process loads the extension and installs the `dsh-context` skill into its Python kernel.
+
+First verify package registration:
+
+```bash
+prime-agent package list
+```
+
+Confirm that the output includes the source you installed. In the restarted Prime session:
+
+1. Run `/dsh`. Prime should report the resulting display and indexing state.
+2. Open IPython and evaluate:
+
+   ```python
+   ctx = dsh_context.current()
+   ctx
+   ctx.entries(last=3)
+   ctx.metrics
+   ```
+
+3. Continue the conversation for at least one completed assistant request. `ctx.entries(...)` should reflect the active Prime branch.
+
+Cache rates can remain `—` when the provider does not report enough usage data. That does not mean projection failed. If the session has no publishable history yet, make a normal turn and retry.
+
+## Control the cache display
+
+```text
+/dsh
+/dsh on
+/dsh off
+```
+
+- `/dsh` toggles the native cache-rate text and reports the resulting state.
+- `/dsh on` shows it.
+- `/dsh off` hides it.
+
+The command controls display only. Projection, indexing, and provider cache measurement continue while the display is hidden. A typical provider-reported value is:
+
+```text
+DSH cache · turn 99.7% · session 97.1%
+```
+
+`turn` covers the latest completed assistant request. `session` aggregates the canonical active Prime branch. Both use `cacheRead / (input + cacheRead)`. Prime controls where its native widget appears.
+
+Set `PRIME_DSH_CACHE_DISPLAY=off` before starting Prime to make hidden the initial state.
+
+## Use the Python context skill
+
+Inspect bounded values without changing model context:
+
+```python
+ctx = dsh_context.current()
+ctx.entries(last=10)
+ctx.messages(last=10)
+ctx.search("authentication", limit=20)
+ctx.metrics
+```
+
+Pin the current immutable view and save selected material as a private artifact:
+
+```python
+snapshot = ctx.snapshot()
+selection = ctx.search("migration decision", limit=8)
+artifact = ctx.artifact(selection, label="Migration evidence")
+```
+
+Reading or searching does not silently add data to the next model request. Explicitly admit a bounded selection by printing or returning it from the IPython cell:
+
+```python
+print(ctx.inject(selection, label="Relevant migration decisions"))
+```
+
+Prime records that output in its canonical JSONL before a later request can use it. `ctx.admit(...)` is an alias.
+
+To share a larger selected value with a native RLM child:
+
+```python
+selection = ctx.search("authentication design", limit=12)
+grant = ctx.grant(selection, label="Authentication evidence")
+child = await rlm.spawn(
+    "Review the design. " + grant.instruction,
+    name="auth-review",
+)
+```
+
+The child follows the instruction or opens the URI directly:
+
+```python
+evidence = dsh_context.open_grant("dsh-context-grant:...")
+evidence.value
+```
+
+Grants are bounded, read-only, and expiring. They share selected evidence, not the parent's tools or live session. Native children also receive a small automatic evidence capsule through Prime lifecycle hooks.
+
+## Update
+
+Updates are source updates, not npm upgrades. Stop Prime, then update the same checkout and validate it:
+
+```bash
+cd /absolute/path/to/prime-agent-dsh
+git fetch --all --tags
+git checkout <reviewed-tag-or-commit>
+npm install
+npm run release:check
+prime-agent package install "$PWD"
+```
+
+If the package was registered locally, run the last command from the target project with `--local` and the absolute checkout path. Restart Prime afterward. `prime-agent package update [source]` exists for package sources that Prime can update, but a manual checkout update makes the reviewed revision explicit.
+
+No manual data migration is required for 0.2.0. On first publication, it removes legacy rebuildable snapshot layouts and prunes old derived generations under the writer lock. It does not change Prime JSONL, user artifacts, grants, or inheritance data.
+
+## Uninstall
+
+First identify the registered source:
+
+```bash
+prime-agent package list
+```
+
+Remove the same source value used at installation:
+
+```bash
+prime-agent package remove <source>
+```
+
+For a project-local registration, run from that project and include `--local`:
+
+```bash
+prime-agent package remove --local <source>
+```
+
+Restart Prime. Removal stops future extension loading. It does not delete source checkouts or existing Prime sessions and artifacts. Remove a checkout separately only after unregistering it.
+
+## Delete a session
+
+DSH adds no deletion command. Use Prime's native **Agents** view:
+
+1. Select the session.
+2. Press `Ctrl+X` twice to confirm.
+
+Prime deletes the matching session artifact directory. Do not manually remove individual DSH files from a live session. Prime alone owns session deletion and compaction.
+
+## Troubleshooting
+
+### The command or Python module is missing
+
+- Run `prime-agent package list` and confirm the expected source is registered.
+- Restart every Prime process after install or update.
+- Run `npm install` in the checkout.
+- Do not load both the installed package and `-e ./extensions/index.ts`.
+- Confirm Prime and Node meet the versions above.
+
+### Cache rates show `—`
+
+The provider did not report enough cache usage data for that request or branch. This is expected for some providers. It does not disable indexing or context objects.
+
+### Entries look stale
+
+Make a normal Prime turn, then call `dsh_context.current()` again. Handles point to immutable snapshots, so create a new handle to observe a newer publication. If publication stopped because of its storage safety limits, free disk space and restart Prime to re-arm it.
+
+### Validation fails
+
+Run individual checks to locate the failing layer:
+
+```bash
+npm run typecheck
+npm run lint
+npm test
+npm run test:python
+npm run package:smoke
+```
+
+Keep the complete command and output when requesting support. Do not include secrets or an unredacted session log.
+
+### Prime still works but DSH data is unavailable
+
+This is the intended fail-open behavior. Projection errors leave Prime's request unchanged. Review the Prime process output, available disk space, checkout dependencies, and file permissions. The derived store stops publishing before it would exceed its 64 MiB quota or the 128 MiB free-space reserve; restart after correcting the condition.
+
+## Privacy and data handling
+
+- Prime JSONL is the only full-content history. DSH reads the active branch and creates derived, rebuildable indexes and immutable objects under the matching Prime session artifact directory.
+- New index roots store locators, IDs, offsets, lengths, and digests rather than a second full message-body store.
+- User-created artifacts and grants can contain the selected content you give them. They are not removed by derived-generation pruning.
+- Automatic child capsules can contain bounded user, assistant, and summary evidence. They exclude system/developer text, tool inputs/results, credentials, provider state, and synthetic inherited messages.
+- Shadow telemetry is off by default. When enabled, it performs a second diagnostic-only round trip and therefore can send bounded mirrored context to the configured provider. Review [shadow telemetry validation](shadow-telemetry-validation.md) before enabling it.
+- Directories use mode `0700`; files use `0600`. These permissions are not a hostile same-user sandbox. Another process running as your OS user can generally access or replace your files.
+- Context sent in normal requests, explicit admissions, and shadow diagnostics remains subject to your Prime provider's data handling terms.
+
+Before sharing logs or artifacts, inspect and redact them. Use separate OS identities or a sandbox for mutually hostile agents.

package/docs/security.md

@@ -0,0 +1,78 @@
+# Security and operations guide
+
+This guide describes the security boundary of `prime-agent-dsh` 0.2.x. It supplements, but does not replace, the controls of Prime Agent, the operating system, the selected model provider, and your backup system.
+
+## Trust boundaries
+
+Prime owns the agent loop, tool execution, provider request, canonical session JSONL, compaction, and session lifecycle. DSH observes committed Prime history and creates local, derived state. **The Prime JSONL is the sole content authority.** A DSH manifest, `CURRENT` file, index, object, commit, or shadow trace must never be treated as a replacement transcript. Reference projections are rebuilt and checked against the canonical JSONL.
+
+The installation assumes that Prime, this package, its configured dependencies, and native parent/child sessions are cooperative. DSH rejects unsafe paths and corrupt objects, but it is not a hostile multi-tenant boundary. A process with the same OS user ID can generally read or modify session files, inspect process memory, race checks, or debug the Prime process. File modes do not stop that process. Run mutually hostile agents under separate OS identities, containers, or stronger sandboxes, and isolate their session and attachment roots.
+
+DSH is not an authorization layer for Prime tools. A tool that can read a file or environment variable can still place its value in the canonical transcript or send it through Prime's normal model request.
+
+## Data inventory and metadata
+
+The normal derived context store contains content-free references into Prime JSONL, content digests, offsets, lengths, line and entry identifiers, branch/session identifiers, absolute canonical file paths, timestamps, token counts, roles, and publication diagnostics. It does not copy message bodies into derived objects or the incremental index. Queries resolve references by reading and validating Prime JSONL.
+
+This metadata is still sensitive. Paths and identifiers reveal host layout and activity. Sizes, timings, roles, token counts, and equality or prefix relationships can reveal usage patterns. SHA-256 digests can confirm guesses about low-entropy content. Do not publish manifests, indexes, fingerprints, traces, or error logs merely because they omit message bodies.
+
+Other DSH state can contain content:
+
+- `dsh-inheritance/` generations contain bounded, selected parent text after best-effort secret redaction, generated capsules, and the child's **exact task prompt**. Task prompts are not redacted.
+- `dsh-context/artifacts/` contains exact values explicitly saved by the user.
+- `dsh-context/grants/` contains exact bounded values and capability tokens created for descendants.
+- local attachment storage can contain verbatim files or images admitted by the attachment backend.
+- Prime JSONL remains a complete source of any sensitive content committed by Prime.
+
+Treat the full Prime session tree, DSH artifact tree, attachment store, diagnostic output, and backups as confidential.
+
+## Local files and integrity controls
+
+On POSIX systems DSH creates or tightens its managed directories to mode `0700` and creates managed files with mode `0600`. Host ACLs, mount options, backup agents, copied/restored files, and the permissions of ancestor directories remain operator responsibilities. Check them after migration or restore. Do not place session state on a shared or untrusted filesystem.
+
+The durable store binds a session ID to the canonical real path of its Prime JSONL. It rejects store-root symlinks and symlinks within managed paths, rejects traversal outside the bound root, validates file type and size, uses exclusive temporary files and atomic rename, and fsyncs publication boundaries where the platform supports it. Content-addressed commits and objects, heads, source locators, attachment references, and inheritance artifacts are checked with digests and session bindings before use. `CURRENT` and compatibility manifests are hints, not recovery authority. Corrupt, stale, mismatched, or incomplete generations are rejected or ignored.
+
+These controls reduce accidental substitution and corruption. They do not eliminate time-of-check/time-of-use races by a same-UID attacker, protect a compromised Prime process, or provide authenticity against an attacker who can rewrite all bound state. SHA-256 here is an integrity and content-addressing mechanism, not encryption or a secret MAC.
+
+## Provider and telemetry boundary
+
+Prime sends the active request to the selected remote model provider under Prime's configuration and that provider's policy. DSH does not add a provider or make an additional model request. `PRIME_DSH_SHADOW_MODE=on` performs a bounded local conversion round trip and passively observes the provider payload that Prime is already preparing; it does not transmit that mirror itself.
+
+Shadow telemetry is process-local and retains counters, byte lengths, timestamps, truncated display fingerprints, and full SHA-256 fingerprints/chunk fingerprints needed for prefix comparison. It temporarily serializes observed content in memory but does not retain provider request bodies or credentials as plaintext telemetry. Credential-shaped object keys are replaced before fingerprinting. This redaction is defense in depth, not a complete secret detector: secrets in ordinary message strings still influence one-way fingerprints. Process exit clears process-local shadow traces; shadow mode is off by default. Provider-reported cache token counts are copied into local manifests and status data; DSH cannot verify provider accounting.
+
+Review Prime and provider logging, training, residency, retention, and incident policies separately. Disabling DSH telemetry does not stop Prime's normal provider request.
+
+## Retention, deletion, and backup
+
+The derived publication store normally retains the two newest complete generations. Its quota and pruning apply to rebuildable commits, objects, heads, indexes, and compatibility manifests. They do **not** collect user `artifacts/`, `grants/`, inheritance generations, Prime JSONL, or all attachment objects. Grant expiry prevents a grant from being opened through the API; it does not erase the grant file. An artifact has no automatic expiry.
+
+Use Prime's native Agents view to delete a session (`Ctrl+X` twice to confirm in the supported UI). DSH has no separate session-deletion or secure-erasure command. Prime is expected to remove the matching session artifact directory. Verify deletion of the canonical JSONL, matching `session-artifacts/<session>/`, descendant/inheritance directories, attachment objects that are no longer referenced, exported diagnostics, and applicable backups according to your Prime version and local layout. Filesystems, snapshots, SSD wear levelling, remote sync, and backups can retain copies; ordinary deletion is not guaranteed secure erasure.
+
+Back up the canonical Prime JSONL and any user artifacts that must survive. The `dsh-context` projection is disposable and can be rebuilt; backing it up is optional. If DSH state is backed up, preserve its association with the matching canonical JSONL and session directory rather than restoring it under a different session. Stop writes or use a filesystem-consistent snapshot. Encrypt backups, restrict access, test restores, and apply the same retention policy as for transcripts. After a partial or uncertain restore, discard the derived projection and allow DSH to rebuild it from Prime JSONL.
+
+## Secret handling
+
+Do not put API keys, cookies, passwords, private keys, connection URLs, or production customer data in prompts, task text, artifacts, grant values, filenames, labels, or transcripts. Use the platform's secret store or environment injection and pass opaque references where possible. Scope credentials narrowly and use short-lived values.
+
+Inheritance applies best-effort pattern redaction to eligible parent text. It cannot identify every secret, and the exact child task prompt is persisted for binding and resume checks. Canonical history, explicit artifacts, grants, and attachments are not general-purpose redaction services. Never rely on hash-only metadata or redaction to make a secret safe after exposure. Avoid placing secrets in low-entropy content because fingerprints can permit guess confirmation.
+
+Before sharing a bug report, archive, screenshot, trace, or test fixture, replace real session IDs, paths, capability tokens, transcript text, and credentials. Never send live secrets in a GitHub Security Advisory.
+
+## Operational checks
+
+- Install only expected package versions and review lockfile changes. Run with a supported Node.js release and supported Prime peer dependencies.
+- Keep session and attachment roots on local, access-controlled storage. Verify ownership, `0700` directories, `0600` files, and restrictive ancestor permissions.
+- Leave `PRIME_DSH_SHADOW_MODE=off` unless local diagnostics are needed. Clear traces and restart after diagnostics.
+- Monitor DSH warnings, disabled publication, integrity failures, unexpected permission changes, storage quota failures, and unfamiliar session descendants.
+- Use separate OS users or sandboxes for different trust domains. Do not grant untrusted agents access to another agent's session tree or capability URI.
+- Test Prime-native session deletion and encrypted backup restore in the actual deployment.
+
+## Incident response
+
+1. Stop affected Prime processes and isolate the host or session storage. Preserve read-only copies if forensic evidence is required.
+2. Assume exposed transcript text, task prompts, artifacts, grants, attachments, environment-derived values, and backups are compromised. Revoke and rotate credentials and provider tokens; invalidate or remove grants.
+3. Record package, Prime, Node.js, provider, and OS versions. Preserve relevant canonical JSONL and file metadata without publishing them.
+4. Remove untrusted derived state. After the canonical JSONL and host are known-good, let DSH rebuild its projection. Do not use a clean rebuild as proof that the canonical transcript is safe.
+5. Review provider and Prime audit data for unexpected requests. Follow their incident procedures for remote disclosure or account compromise.
+6. Report a suspected package vulnerability privately through the process in [`SECURITY.md`](../SECURITY.md). Coordinate public disclosure with the maintainers.
+7. After containment, verify permissions, session deletion behavior, backup copies, dependency integrity, and separation between trust domains.

package/docs/shadow-telemetry-validation.md

@@ -0,0 +1,18 @@
+# Shadow telemetry validation
+
+Staging implementation observes Prime `context` and `before_provider_request` events without returning replacements or mutating event values.
+
+## Data retained
+
+- SHA-256 fingerprint of canonical, credential-redacted payload
+- byte size and previous-payload byte size
+- byte-level longest common prefix and ratio
+- request number, timestamp, stage, session ID, branch leaf ID, and change classification
+- bounded in-memory trace (128 entries); no payload or message content
+
+## Commands
+
+
+## Validation
+
+`npm run check` runs typechecking, lint, the Prime-native sidecar tests, and Python context-object tests. Coverage includes canonical fingerprints, credential redaction, UTF-8 byte LCP, append/rewrite classification, branch/session isolation, bounded traces, no payload mutation/content retention, and fail-open cyclic-payload handling.

package/docs/single-window-cache-architecture.md

@@ -0,0 +1,24 @@
+# Projection and provider-cache architecture
+
+Prime is the only owner of model requests, active context, canonical session JSONL, and compaction. DSH never plans, requests, summarizes, prunes, or commits compaction. It does not interpret history changes as compaction events.
+
+DSH observes Prime lifecycle events and indexes the resulting JSONL into a rebuildable, reference-only projection. The `session_compact` hook is passive: after Prime has replaced history, it triggers the same resynchronization used by other lifecycle events.
+
+## Publication diagnostics
+
+A publication reports only structural facts:
+
+- source mode: `append`, `rebuild`, or `noop`;
+- source entries reused, new, and reindexed;
+- effective entries reused, new, and reindexed;
+- a generic effective rebuild reason.
+
+These facts do not assign semantic meaning to a history replacement. Prime entries such as `compaction` and `compactionSummary` remain ordinary canonical data that converters and RLM inheritance may read.
+
+## Provider cache metrics
+
+Provider-reported input, cache-read, and cache-write token counts are collected as a generic request series. Aggregate counts, efficiency, and percentiles describe only what the provider reported. DSH does not create cache epochs, mark compaction boundaries, or classify first-after-compaction and summary requests.
+
+## Safety
+
+DSH does not edit Prime JSONL or active request context. Derived state can be deleted and rebuilt from Prime's canonical files. Publication and telemetry failures fail open and leave Prime inference unchanged.