AGENTS.md@packages/sessions git:20261009.95ca1efA

Immutable. This exact content never changes and is served at /api/v1/blob/1da8b829103b6927.

# @shadowclone/sessions

Reads consented agent transcripts into an event index and derives learning signals. Learning, changes, and the MCP server use it to read session text.

<!-- package-facts:start -->

(generated by `bun run guides`; do not edit by hand)

- Package name: `@shadowclone/sessions`
- Workspace dependencies: `@shadowclone/core`, `@shadowclone/redact`
- External dependencies: none
- Export subpaths: `.`, `./testing`

<!-- package-facts:end -->

## Owns

- `src/observe/`: one adapter per source in `adapters/`, plus `observeAll`, `resolveRedacted`, and `captureRoots`.
- `src/eventIndex/`: the SQLite index of event metadata and text references. Use `openEventIndex` and `ingestSources`.
- `src/signal/`: corrections, steering episodes, and repository origin binding. Use `deriveSignals` and `isOriginBlocked`.

## Rules

- `observeAll` reads only the sources that the effective config enables.
- The index stores a `TextRef` pointer and event metadata. It never stores transcript text.
- `resolveRedacted` is the only way to turn a `TextRef` into text. It checks the root and the file identity, and then calls `redactSecrets`.
- Adapters set no `textRef` on thinking blocks or tool results. Only user text is learning evidence.
- Assistant text, plans, and questions appear only as labeled context next to a user correction.
- The Git remote is read only when `git-metadata` is on. Otherwise the origin stays isolated.
- A working directory keeps the owner that it first resolved to.

## Tests

Run `bun test` in this folder, or `bun test packages/sessions` from the root. The `./testing` export gives `signalCorpus` and `signalEvents`. Adapter tests use synthetic transcripts and synthetic secrets.

Update this file in the same commit when you change the package purpose, public exports, dependencies, or a rule above.