# Agent Session Uploads

ctx.cat v0.1 treats agent sessions as encrypted snapshots. It does not live-tail
active sessions yet.

The public `@synthlabs/ctx-cat-client@0.3.1` package bytes are MIT-licensed;
the source repository remains private. Commands below describe the supported
registry interface.

## CLI

```bash
ctxcat sessions scan --json
RECOVERY_DIR="$HOME/.local/share/ctxcat/$(date +%s)-$$-$RANDOM-$RANDOM"
install -d -m 700 "$RECOVERY_DIR"
ctxcat sessions upload --latest --capability-output "$RECOVERY_DIR/latest-session.recovery.json"
ctxcat sessions upload --path ~/.codex/sessions/2026/05/12/rollout-example.jsonl --capability-output "$RECOVERY_DIR/codex-2026-05-12.recovery.json"
ctxcat sessions upload --path ./trace.jsonl --strip-tool-output --capability-output "$RECOVERY_DIR/stripped-trace.recovery.json"
```

Each upload requires a fresh, non-existing recovery path. Its file contains the
reader and owner lifecycle capabilities, so keep it in a private user-controlled
directory and out of agent context, output, and logs. Never overwrite or reuse a
recovery file for another upload.

By default, uploads preserve the full selected transcript. There is no generic
redaction pass. `--strip-tool-output` is an explicit **viewer-only** JSONL mode
for a deliberate share where tool output should not be included. It does not
produce a native continuation artifact.

The preview is the exact policy and byte identity of the pending upload. A new
CLI upload records bounded policy facts in its encrypted metadata: full versus
tool-output-stripped content, prepared byte count and hash, point-in-time scope,
external workspace-file exclusion, and the possibility that workspace data
already embedded in the transcript remains present. The hosted viewer shows
that label after decrypting a current share; older shares may say that the
policy is unavailable.

External workspace files, attachments, bundles, and snapshots are not uploaded
by this command. Browser creation remains disabled: use the recovery-safe CLI
for every new share. The browser continues to open, edit, comment on, and use
existing owner links.

For a current verified viewer-only share, an owner edit creates a new
point-in-time viewer snapshot and recomputes both source and prepared byte/hash
identities. It does not create or mutate a provider-native continuation.

## Sources

The scanner looks for:

- Claude Code: `~/.claude/projects/**/*.jsonl`
- Codex: `~/.codex/sessions/YYYY/MM/DD/rollout-*.jsonl`
- Structured chat JSONL: `chat.jsonl` exports with `role` and `parts` records
- OpenCode: `~/.local/share/opencode/opencode*.db`

OpenCode SQLite files can be uploaded privately as binary snapshots. Rich
timeline rendering needs a JSON/JSONL export.

The client resolves these paths locally. A share must not expose the sender's
absolute source path.

## Snapshot Semantics

Coding CLIs append records while a session is active. The safe default is an
immutable snapshot taken when the user invokes share:

- a later snapshot creates a new reader link;
- mutation capability is retained only for lifecycle operations;
- hidden background tailing is not part of snapshot sharing;
- live mirroring requires a separate design with explicit failure and privacy
  behavior.

## Encrypted Metadata

For supported JSON and JSONL sessions, clients add encrypted trace metadata:

- agent
- format
- source hint
- message count
- user prompt count
- tool call count
- per-record SHA-256 hashes
- schema validity
- completeness

## Browser Viewer

The hosted viewer decrypts recognized JSON/JSONL sessions locally and renders a
read-only trace timeline with roles, record metadata, search/filter, and copy
controls. The source bytes remain the import authority; the rendered model is
not a provider-native continuation artifact.

Provider-specific reasoning/tool folding, complete provenance states, and
large-trace acceptance remain active work. The repository feature catalog and
acceptance snapshot distinguish that target behavior from current proof.

## Implementation References

- `coder/mux`: compacted `chat.jsonl` sharing behavior.
- `pugliatechs/polpo`: multi-agent discovery and history adapters.
- `getagentseal/codeburn`: provider discovery and Codex/OpenCode parsing.
- `daaain/claude-code-log`: Claude Code tool models and renderers.
- `simonw/claude-code-transcripts`: compact transcript HTML with pagination.