Skip to content

feat: add optimistic V8 garbage collection proposal and design#170

Closed
avoidwork wants to merge 2 commits into
mainfrom
feat/optimistic-v8-gc
Closed

feat: add optimistic V8 garbage collection proposal and design#170
avoidwork wants to merge 2 commits into
mainfrom
feat/optimistic-v8-gc

Conversation

@avoidwork

@avoidwork avoidwork commented Jun 11, 2026

Copy link
Copy Markdown
Owner

Description

Add OpenSpec change proposal for optimistic V8 garbage collection. Proactively triggers global.gc() during TUI idle periods or when heap usage exceeds a configurable threshold (default: 80%).

Type of Change

  • Bugfix (non-breaking change which fixes an issue)
  • New feature (non-breaking change which adds functionality)
  • Breaking change (fix or feature that would cause existing functionality to not work as expected)
  • Documentation update
  • Refactor (no functional changes)
  • Performance improvement
  • CI / build / tooling

Testing

Proposal only — no code changes yet. Full test suite will be added during implementation (see tasks.md).

Coverage

  • 100% line coverage maintained

Checklist

  • npm run lint passes
  • Tests pass with 100% line coverage
  • No forbidden patterns used
  • Conventional Commit style applied

Related Design

See openspec/changes/optimistic-gc/design.md for architecture:

  • GC Manager checks heap + idle state on configurable interval
  • TUI idle detection via streaming state callbacks
  • Graceful degradation when --expose-gc is unavailable
  • Dockerfile updated to pass --expose-gc flag

…nd heap thresholds

- Add OpenSpec change artifacts for optimistic-gc
- proposal.md: defines why (heap pressure during long sessions), what (global.gc()
  triggered by idle state or heap threshold), and scope
- design.md: architecture with GC Manager, TUI idle detection, config schema,
  and Dockerfile --expose-gc integration
- specs/memory-gc/spec.md: requirements for GC triggers, graceful degradation,
  and configurable parameters
- tasks.md: 6-phase implementation checklist (config schema, GC manager module,
  TUI integration, Dockerfile, tests, verification)
@avoidwork avoidwork changed the title proposal: add optimistic V8 garbage collection proposal: add optimistic V8 garbage collection via global.gc() Jun 11, 2026
@avoidwork avoidwork self-assigned this Jun 11, 2026
@avoidwork avoidwork changed the title proposal: add optimistic V8 garbage collection via global.gc() feat: add optimistic V8 garbage collection proposal and design Jun 11, 2026
Address all 10 audit findings:

- Mark tasks 1.1/1.2 as complete (already implemented in schemas.js)
- Add idle timeout check (lastActivityTime) to design check logic
- Simplify Dockerfile task: add --expose-gc to package.json start script
- Add timer cleanup task (stop() on shutdown)
- Tighten heapThreshold bounds to [0.01, 0.99] to prevent degenerate configs
- Make TUI callback wiring explicit in tasks
- Add note about non-streaming TUI activity tradeoff
- Move graceful degradation check to constructor (not first _check())
- Consolidate test file references (1.3 and 5.2)
- Add positive scenario: GC triggers after sustained idle period

Also: add gc schema and defaults to schemas.js + DEFAULT_CONFIG,
and add --expose-gc to package.json start script.
@avoidwork avoidwork closed this Jun 11, 2026
@avoidwork avoidwork deleted the feat/optimistic-v8-gc branch June 11, 2026 03:49
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant