feat(capture): automatic session finalization on sessionstart and close by plind-junior · Pull Request #304 · vouchdev/vouch

plind-junior · 2026-07-01T10:14:47Z

Summary

Automatically finalize session capture buffers without user action:

SessionStart: Clean up old, orphaned buffers (>1 hour) from previous sessions
SessionEnd: Finalize current session when VS Code window closes

Buffers are rolled into PENDING proposals for review—the review gate is preserved.

What Changed

is_stale_buffer() & finalize_all_except() functions in capture.py for bulk cleanup
vouch capture finalize-all CLI command (called by SessionStart hook)
SessionStart hook wired to clean up old buffers before banner/recall
Adapter README documented for users
Comprehensive unit + integration tests (9 capture tests)
Data integrity fix: old buffers don't inherit current working directory's git diff

Testing

Tested end-to-end in VS Code Claude Code extension:

✅ Old buffers from previous sessions cleaned up on new session start
✅ Current session finalized to proposal when window closes
✅ Two sessions produce two separate proposals with correct session IDs
✅ Git context only attributed to sessions with known origin

Commits

5933700 feat(capture): add finalize_all_except() for old buffer cleanup
f6cb506 feat(capture): add 'vouch capture finalize-all' CLI command
6ec0fe7 feat(adapter): wire capture finalize-all into sessionstart hook
d68a376 docs(adapter): document windowclose fallback behavior
2d76811 docs(adapter): explain session capture auto-proposal behavior
b2955f0 test(capture): add e2e test for sessionstart cleanup + finalize flow
2a5d2d2 fix(capture): skip git context when finalizing buffers with unknown origin

Design

See: docs/superpowers/specs/2026-07-01-vscode-session-autoproposal-design.md
See: docs/superpowers/plans/2026-07-01-vscode-session-autoproposal.md

All tests pass (805 tests). Review gate preserved. No Co-Authored-By trailers.

Summary by CodeRabbit

New Features
- Added automatic session capture that turns agent tool usage into reviewable session summaries.
- Added session-start recall so approved knowledge can be injected into new sessions, with size limits and opt-out support.
- Updated installation behavior to merge new agent hooks and permissions into existing settings.
Bug Fixes
- Lists and pending views now skip unreadable/corrupted artifacts instead of stopping.
- Improved text handling so non-ASCII content is preserved reliably across files and reports.

design: automatic finalization of old buffers on sessionstart, and current session on window close. plan: 8-task breakdown covering capture.py functions, cli command, adapter hooks, comprehensive unit tests, integration test, and documentation.

implement is_stale_buffer() to check file age, and finalize_all_except() to bulk-finalize capture buffers older than a threshold. this enables sessionstart cleanup of orphaned buffers from previous sessions. includes 9 unit tests covering single/multiple buffers, age boundaries, and current session exclusion.

new command finalizes all capture buffers except the given session, if they are older than max_age_seconds (default 3600s). silently succeeds if no kb found. used by sessionstart hook to clean up orphaned buffers from previous sessions. includes 3 unit tests covering option parsing, env fallback, and graceful degradation.

run 'vouch capture finalize-all' as the first sessionstart hook to clean up orphaned buffers from previous sessions before banner and recall commands. ensures old sessions are finalized automatically on next session start.

add comment to sessionstart hook explaining that current session finalization happens on next session start (fallback behavior when windowclose event is not supported by the vs code extension).

add section describing how capture works, configuration options, and the fallback behavior if windowclose event is not available.

verify that old buffers are cleaned up on new session start and current session is finalized on window close (or manual finalize), resulting in two separate proposals.

…rigin when finalize_all_except() cleans up orphaned buffers, those old sessions have unknown origin (no cwd), so we should not attribute the current working directory's git diff to them. this prevents data corruption where old sessions' summaries get current repo changes, and avoids spurious proposals that cross min_observations due to misattributed file counts. added explicit cwd check: if cwd is None (unknown origin), skip git changes. normal finalize calls with explicit cwd still get git context. also fix typo: unfinalzed -> unfinalized in adapter README.

coderabbitai · 2026-07-01T10:15:20Z

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 996ec2ac-7c90-4f58-bd6d-2a1ab4e9b641

📥 Commits

Reviewing files that changed from the base of the PR and between 94e84b1 and 2a5d2d2.

📒 Files selected for processing (58)

CHANGELOG.md
CLAUDE.md
Makefile
README.md
SPEC.md
adapters/claude-code/.claude/settings.json
adapters/claude-code/README.md
adapters/claude-code/install.yaml
docs/getting-started.md
docs/img/examples/render.py
docs/superpowers/plans/2026-07-01-vouch-session-autocapture.md
docs/superpowers/plans/2026-07-01-vscode-session-autoproposal.md
docs/superpowers/specs/2026-07-01-vouch-session-autocapture-design.md
docs/superpowers/specs/2026-07-01-vscode-session-autoproposal-design.md
docs/transports.md
docs/tutorials/README.md
docs/tutorials/connect-coding-agent.md
docs/tutorials/edit-in-obsidian.md
docs/tutorials/first-knowledge-base.md
docs/tutorials/share-a-knowledge-base.md
openclaw.plugin.json
pyproject.toml
scripts/smoke-capture.sh
scripts/smoke-recall.sh
src/vouch/__init__.py
src/vouch/__main__.py
src/vouch/auto_pr.py
src/vouch/capture.py
src/vouch/cli.py
src/vouch/context.py
src/vouch/embeddings/scorer.py
src/vouch/embeddings/similarity.py
src/vouch/health.py
src/vouch/http_server.py
src/vouch/index_db.py
src/vouch/install_adapter.py
src/vouch/jsonl_server.py
src/vouch/migrations/_legacy.py
src/vouch/migrations/journal.py
src/vouch/migrations/manifest.py
src/vouch/migrations/runner.py
src/vouch/migrations/schema.py
src/vouch/openclaw/context_engine.py
src/vouch/page_kinds.py
src/vouch/pr_cache.py
src/vouch/proposals.py
src/vouch/recall.py
src/vouch/scoping.py
src/vouch/server.py
src/vouch/stats.py
src/vouch/storage.py
src/vouch/sync.py
src/vouch/volunteer_context.py
src/vouch/web/server.py
tests/test_capture.py
tests/test_install_adapter.py
tests/test_recall.py
tests/test_storage.py

📝 Walkthrough

Walkthrough

This PR adds a Claude session auto-capture pipeline that harvests tool-use into review-gated proposals, a session-start recall hook injecting approved knowledge digests, JSON-merge semantics for adapter settings installation, storage resilience against corrupt YAML, and consistent UTF-8 encoding across file I/O, alongside version bumps and extensive documentation.

Changes

Session Auto-Capture Feature

Layer / File(s)	Summary
Capture core: config, buffer, observe `src/vouch/capture.py`, `src/vouch/storage.py`	Adds `CaptureConfig`, `load_config`, buffer path helpers, dedup-aware observation writing, and tool summarization; extends starter config with `capture` namespace.
Session finalize and summary generation `src/vouch/capture.py`	Adds `build_summary_body`, `_git_changes`, `finalize` (creates PENDING page proposal, deletes buffer), and `pending_count`.
Stale buffer detection and bulk finalize `src/vouch/capture.py`	Adds `is_stale_buffer` and `finalize_all_except` to clean up old session buffers without aborting on errors.
CLI capture group `src/vouch/cli.py`	Adds `capture observe`, `finalize`, `finalize-all`, and `banner` subcommands.
Adapter hook wiring `adapters/claude-code/.claude/settings.json`, `adapters/claude-code/install.yaml`, `adapters/claude-code/README.md`	Wires PostToolUse/SessionEnd/SessionStart hooks to capture commands and documents T4 behavior.
Tests, smoke scripts, and design docs `tests/test_capture.py`, `scripts/smoke-capture.sh`, `Makefile`, `README.md`, `CHANGELOG.md`, `docs/superpowers/...`	Adds test coverage, an end-to-end smoke test, make targets, and implementation plan/design documents.

Session-Start Recall Feature

Layer / File(s)	Summary
Recall digest builder `src/vouch/recall.py`	Adds `RecallConfig`, `load_config`, and `build_digest` that produces a size-guarded knowledge block of approved claims/pages.
CLI/adapter wiring, tests, and docs `tests/test_recall.py`, `scripts/smoke-recall.sh`, `Makefile`, `README.md`, `docs/transports.md`, `CHANGELOG.md`	Wires recall into SessionStart, adds tests and a smoke script, documents end-to-end MCP flow.

JSON-Merge Install Behavior

Layer / File(s)	Summary
Merge implementation `src/vouch/install_adapter.py`, `adapters/claude-code/install.yaml`	Adds `InstallResult.merged`, `_FileEntry.json_merge`, and `_merge_settings`/`_install_json_merge` to deep-merge hooks/permissions into existing settings.json.
Merge tests `tests/test_install_adapter.py`	Covers merge, idempotency, fresh write, and malformed-JSON handling.

Storage Resilience

Layer / File(s)	Summary
Skip unreadable artifacts `src/vouch/storage.py`, `tests/test_storage.py`	Adds `_load_or_skip` used across `list_*` methods so corrupt YAML files are skipped with a warning.

UTF-8 Encoding Hardening

Layer / File(s)	Summary
storage.py encoding `src/vouch/storage.py`	Adds explicit UTF-8 encoding to bootstrap and artifact I/O.
Other modules encoding `src/vouch/auto_pr.py`, `src/vouch/context.py`, `src/vouch/embeddings/`, `src/vouch/health.py`, `src/vouch/http_server.py`, `src/vouch/index_db.py`, `src/vouch/jsonl_server.py`, `src/vouch/migrations/`, `src/vouch/openclaw/context_engine.py`, `src/vouch/page_kinds.py`, `src/vouch/pr_cache.py`, `src/vouch/proposals.py`, `src/vouch/scoping.py`, `src/vouch/server.py`, `src/vouch/stats.py`, `src/vouch/sync.py`, `src/vouch/volunteer_context.py`, `src/vouch/web/server.py`	Adds explicit UTF-8 to text reads/writes across config, migration, and reporting code.

Release Metadata and General Documentation

Layer / File(s)	Summary
Version bump `pyproject.toml`, `src/vouch/__init__.py`, `src/vouch/__main__.py`, `openclaw.plugin.json`, `SPEC.md`	Bumps version to 1.0.0 and adds `python -m vouch` entrypoint.
Docs and tutorials `CLAUDE.md`, `docs/getting-started.md`, `docs/img/examples/render.py`, `docs/tutorials/*`	Updates guidance and adds new tutorial pages.

Estimated code review effort: 4 (Complex) | ~75 minutes

Possibly related PRs

vouchdev/vouch#87: Overlaps on package version bump metadata (src/vouch/__init__.py, pyproject.toml, CHANGELOG.md).
vouchdev/vouch#136: Overlaps with UTF-8 decoding change in expire_pending_after_days proposal expiry logic.
vouchdev/vouch#295: Overlaps on CLAUDE.md sidebar metadata guidance for _meta.vouch_salience vs _meta.vouch_hot_memory.

Suggested labels: enhancement, refactor, docs

✨ Finishing Touches

📝 Generate docstrings

Create stacked PR
Commit on current branch

🧪 Generate unit tests (beta)

Create PR with unit tests
Commit unit tests in branch feat/session-autocapture

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

_{Comment @coderabbitai help to get the list of available commands.}

finalize-all resolved the current session id from --session-id or VOUCH_SESSION_ID only. the shipped SessionStart hook passes neither, and nothing in the adapter or runtime exports VOUCH_SESSION_ID, so sid was always "" and the sweep returned empty on every session start. that made the vouchdev#304 backstop dead: buffers orphaned by sessions that ended without SessionEnd accumulated in .vouch/captures/ and never rolled up into pending proposals, so the session never reached the review queue. the id now comes off the stdin payload the same way capture finalize reads it at SessionEnd, with --session-id and VOUCH_SESSION_ID kept as fallbacks. a malformed payload still no-ops rather than failing the host's turn. the adapter hook test asserted observe/finalize/banner but never finalize-all, which is why the shipped wiring went unexercised; it now covers it.

The SessionStart finalize-all backstop (vouchdev#304) never fires: the shipped hook passes no --session-id and sets no VOUCH_SESSION_ID, so the command always saw an empty session id and silently no-op'd, letting orphaned buffers accumulate in .vouch/captures/ indefinitely instead of rolling up into pending proposals. - Read the session id off the stdin hook payload, mirroring how capture_finalize_cmd already does it at SessionEnd - Keep --session-id and VOUCH_SESSION_ID as fallbacks for direct/ manual invocation - Assert finalize-all is actually wired to SessionStart in test_adapter_settings_wires_capture_hooks (the gap that let this ship unnoticed) - Add regression tests for stdin-payload precedence, option-overrides- payload, and the genuinely-session-less no-op case Closes vouchdev#492

plind-junior added 8 commits July 1, 2026 17:40

feat(adapter): wire capture finalize-all into sessionstart hook

6ec0fe7

run 'vouch capture finalize-all' as the first sessionstart hook to clean up orphaned buffers from previous sessions before banner and recall commands. ensures old sessions are finalized automatically on next session start.

docs(adapter): document windowclose fallback behavior

d68a376

add comment to sessionstart hook explaining that current session finalization happens on next session start (fallback behavior when windowclose event is not supported by the vs code extension).

docs(adapter): explain session capture auto-proposal behavior

2d76811

add section describing how capture works, configuration options, and the fallback behavior if windowclose event is not available.

test(capture): add e2e test for sessionstart cleanup + finalize flow

b2955f0

verify that old buffers are cleaned up on new session start and current session is finalized on window close (or manual finalize), resulting in two separate proposals.

plind-junior changed the base branch from main to test July 1, 2026 10:16

github-actions Bot removed auto-pr auto-pr orchestration review-ui browser review ui openclaw openclaw integration mcp mcp, jsonl, and http surfaces storage kb storage, migrations, schemas, and proposals retrieval context, search, synthesis, and evaluation labels Jul 1, 2026

github-actions Bot added size: M 200-499 changed non-doc lines and removed embeddings embedding-backed retrieval sync sync, vault mirror, and diff flows packaging packaging, build metadata, and make targets size: XL 1000 or more changed non-doc lines labels Jul 1, 2026

plind-junior merged commit 63a1ee6 into test Jul 1, 2026
11 of 12 checks passed

coderabbitai Bot mentioned this pull request Jul 2, 2026

Merge test branch to main #337

Merged

3 tasks

This was referenced Jul 15, 2026

fix(capture): the SessionStart finalize-all backstop never fires #492

Open

fix(capture): read the session id off the SessionStart hook payload #493

Closed

coderabbitai Bot mentioned this pull request Jul 17, 2026

feat(review): receipt auto-approve on by default, duplicate-safe drain #522

Merged

Tet-9 mentioned this pull request Jul 18, 2026

fix(capture): read session id from stdin payload in finalize-all #524

Open

5 tasks

This was referenced Jul 19, 2026

feat(hub): kb identity, machine registry, hijack-proof resolution #530

Merged

feat(admission): gate knowledge-shaped garbage at the proposal funnel #546

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

feat(capture): automatic session finalization on sessionstart and close#304

feat(capture): automatic session finalization on sessionstart and close#304
plind-junior merged 8 commits into
testfrom
feat/session-autocapture

plind-junior commented Jul 1, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

coderabbitai Bot commented Jul 1, 2026 •

edited

Loading

Review failed

Walkthrough

Changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

Uh oh!

Conversation

plind-junior commented Jul 1, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

What Changed

Testing

Commits

Design

Summary by CodeRabbit

Uh oh!

coderabbitai Bot commented Jul 1, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Review failed

Walkthrough

Changes

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

1 participant

plind-junior commented Jul 1, 2026 •

edited by coderabbitai Bot

Loading

coderabbitai Bot commented Jul 1, 2026 •

edited

Loading