# Session Vault

OpenCode Session Vault — discover, archive, catalog, and verify OpenCode sessions.

> **Non-restorable transcript snapshot.** Archives contain only `session`, `message`, and `part` rows from the OpenCode database. Restore, rehydration, and import are not supported. Baidu Netdisk upload and the narrow project MCP are available; live-account behavior remains an explicit acceptance gate.

## Quick Start

```bash
# Install
uv sync

# Optional Baidu support (run sync first, then install the pinned official source)
uv sync --extra baidu
powershell -ExecutionPolicy Bypass -File scripts/install_baidu_netdisk_dep.ps1
powershell -ExecutionPolicy Bypass -File scripts/install_baidu_netdisk_dep.ps1 -Status

# Create a minimal config (optional)
# session-vault.toml
# vault_id = "my-vault"
# allowed_project_roots = ["C:/Users/Me/Projects"]
# opencode_db_path = "C:/path/to/opencode.db"

# Verify setup
uv run session-vault doctor

# List projects
uv run session-vault projects list

# List sessions in a project
uv run session-vault sessions list --project "C:/Users/Me/Projects"

# Create an archive
uv run session-vault archive create \
  --session <session-id> \
  --label "My Archive" \
  --best-effort

# List archives
uv run session-vault archive list

# Verify an archive
uv run session-vault archive verify <archive-id-or-path>

# Upload a cataloged archive and inspect remote state
uv run session-vault remote upload <archive-id>
uv run session-vault remote copies --archive-id <archive-id>
```

## Configuration

Create `session-vault.toml` in the repository root (optional — all keys have defaults):

```toml
vault_id = "my-vault"
allowed_project_roots = ["C:/Users/Me/Projects"]

# Override OpenCode DB path (auto-detected otherwise)
# opencode_db_path = "C:/path/to/opencode.db"

# Session provider: "ocsm" (default) or "native" (explicit fallback)
# provider = "ocsm"

# Strict mode: require allowed roots (always enforced in MCP)
# strict_mode = true

# Tune limits
max_archive_members = 10000          # max sessions per archive
max_uncompressed_bytes = 524288000   # 500 MiB
max_compression_ratio = 100.0        # max inflated-to-compressed

[remote]
backend = "baidu"
app_name = "session-vault"
vault_id = "my-vault"
# subdir = "backups"
```

Environment overrides:

| Variable | Purpose |
|---|---|
| `SESSION_VAULT_OPENCODE_DB` | Override OpenCode DB path |
| `SESSION_VAULT_CONFIG` | Override config file path |
| `SESSION_VAULT_PROVIDER` | Override session provider (ocsm/native) |
| `BAIDU_NETDISK_ACCESS_TOKEN` | Baidu access token bootstrap |
| `BAIDU_NETDISK_REFRESH_TOKEN` | Optional refresh token |
| `BAIDU_NETDISK_CLIENT_ID` | Optional OAuth client ID |
| `BAIDU_NETDISK_CLIENT_SECRET` | Optional OAuth client secret |

State directory (catalog DB, archives) defaults to `%LOCALAPPDATA%\SessionVault\<vault-id>`.

## Session Provider

Session Vault reads project/session metadata through a pluggable **provider** abstraction:

- **`ocsm` (default)** — delegates read-only queries to the external [OpenCode Session Manager CLI](https://github.com/neuronalism/opencode-session-manager-cli), pinned by `uv.lock` to commit `b9d4d1c091161ecc320273948fa87f3d77f6f0fc`.
- **`native`** — standalone SQLite queries with identical semantics; must be explicitly selected (config or `SESSION_VAULT_PROVIDER=native`). Never falls back from OCSM silently.

Session Vault **owns** all policy enforcement (allowed-root validation, project/root uniqueness check, member limit, visited guard), coherent capture (snapshot + revision detection), archive packaging (digest filenames, ZIP building), hostile-archive verification, catalog durability, and idempotency. The provider is strictly read-only SELECT.

## Archive Contents (v1)

Each archive ZIP contains:

| File | Description |
|---|---|
| `manifest.json` | Metadata, member graph, `member_files` mapping, checksums |
| `data/<safe-digest>.json` | One file per session (filename is a SHA-256 digest, never a raw session ID) |
| `checksums.sha256` | SHA-256 of every internal file |

**Tables included:** `session`, `message`, `part` (non-restorable transcript snapshot).

Session IDs (including real `ses_*` identifiers) are opaque text; they are never used as filesystem paths. Only archive IDs are UUIDs.

## Baidu Netdisk

The adapter reuses the official `baidu-netdisk/mcp` source pinned to commit `b3983d330fea79c7b72e6b7014803e1830148d2c`. That upstream subproject is not directly buildable as a Git dependency, so `scripts/install_baidu_netdisk_dep.ps1` clones the exact commit into a temporary directory, adds packaging metadata only to that disposable copy, installs it, records non-secret provenance under `%LOCALAPPDATA%`, and removes the temporary source and wheel.

Remote archive payloads are committed before an immutable `.commit.json` sidecar. Catalog state distinguishes pending, committed, failed, and incomplete attempts. Permanent delete, move/recycle, and restore are not exposed.

## Project MCP

Start the stdio server with:

```bash
uv run session-vault-mcp
```

The server exposes ten `session_vault_*` tools for allowed project IDs, sessions, archives, remote copies, and tags. It requires non-empty `allowed_project_roots` and does not expose arbitrary filesystem/remote paths, credentials, download, rename, delete, move, or restore operations.

## Verification

```bash
python -m pytest -q -rs
python -m compileall -q src tests
```

Deterministic tests use an isolated filesystem remote. Real Baidu authentication, upload, download, quota, and rename behavior require manual validation with an account scoped to the configured `/apps/<app-name>/` directory.

## Attribution

Read-only session queries reuse the installed Git dependency from [neuronalism/opencode-session-manager-cli](https://github.com/neuronalism/opencode-session-manager-cli) at commit `b9d4d1c091161ecc320273948fa87f3d77f6f0fc`; no OCSM source is vendored here. Archive safety, verification, catalog, and policy logic remain Session Vault-owned because OCSM does not provide those contracts.

## Current Limitations

- Session restore/import is unsupported; archives are non-restorable transcripts.
- Permanent remote delete and unverified move/recycle operations are intentionally unavailable.
- Task Scheduler automation and repository-local OpenCode Agent/Skill/Command presets are not included yet.