Add an always-continue auto-compaction setting

[m-aebrer]

Closes #492

Adds an opt-in persistent setting that keeps long-running agents moving after every successful automatic compaction, exposed in both the terminal and web dashboard while leaving manual compaction unchanged.

Implementation plan posted as a comment below.

[m-aebrer]

Implementation Plan

Problem analysis

Automatic compaction has two successful continuation paths today: overflow recovery continues because willRetry is true, while threshold compaction continues only when agent.hasQueuedMessages() is true. A normal threshold compaction with no queued agent messages therefore leaves long-running autonomous work idle. Manual compact() is a separate path and must remain non-continuing.

The new behavior should be an opt-in persistent default, disabled when absent so existing users retain current behavior. A single setting, named consistently as compaction.continueAfterAutoCompaction in persisted JSON and continueAfterAutoCompaction on settings RPC/dashboard contracts, will be exposed in both settings interfaces. When enabled, the successful automatic-compaction path will schedule one agent.continue() without consulting willRetry or queued-message state. Unsuccessful, cancelled, and manual compactions will not use it.

Deliverables

1. Persistent compaction setting

   • Extend CompactionSettings and SettingsManager with a default-false getter, global persistence setter, and inclusion in the effective compaction settings snapshot.
   • Preserve normal global/project merge behavior and existing auto-compaction enablement semantics.

2. Automatic-compaction continuation behavior

   • Apply the setting only after an automatic compaction has completed successfully and installed the rebuilt context.
   • When enabled, continue exactly once without asking willRetry or agent.hasQueuedMessages() to decide.
   • When disabled, retain overflow retry and queued-message continuation exactly as they work now, including overflow error-message cleanup and visible continuation failures.
   • Leave manual compact() behavior unchanged.

3. Terminal settings control

   • Add a clearly labelled “continue after auto-compaction” on/off item to /settings, with text explaining that it starts another model turn after every successful automatic compaction.
   • Wire the current effective value and persistence callback through interactive mode.

4. RPC and dashboard settings control

   • Add the boolean to the persistent get_settings snapshot and partial set_settings update contract, including unknown-key/type validation and durable writes.
   • Mirror the field in dashboard shared DTOs and add an off-by-default OnOffSelect row beside the existing compaction settings.
   • Keep this a persistent default rather than a new live-session state command; the automatic-compaction path reads the effective setting when it runs.

5. Documentation

   • Document the JSON key, default, interface availability, successful-auto-compaction semantics, and explicit manual-compaction exclusion across the public README, package README, settings schema, compaction guide, RPC settings contract, and dashboard documentation.

Files to create or modify

Core and interfaces

• packages/coding-agent/src/core/settings-manager.ts — add the persisted field, default-false getter/setter, and effective compaction-settings projection.
• packages/coding-agent/src/core/agent-session.ts — make successful automatic compaction honor unconditional continuation while preserving disabled-state behavior and manual separation.
• packages/coding-agent/src/modes/interactive/components/settings-selector.ts — add TUI config/callback fields, setting row, and input dispatch.
• packages/coding-agent/src/modes/interactive/interactive-mode.ts — supply the effective value and persist TUI changes.
• packages/coding-agent/src/modes/rpc/rpc-types.ts — extend persistent settings snapshot/update types.
• packages/coding-agent/src/modes/rpc/rpc-mode.ts — project, validate, and persist the RPC field.
• packages/dashboard/src/shared/protocol.ts — mirror the setting in dashboard snapshot/update DTOs.
• packages/dashboard/src/client/screens/settings.tsx — render and save the dashboard toggle.

Tests

• packages/coding-agent/test/agent-session-auto-compaction-queue.test.ts — extend focused automatic/manual continuation coverage.
• packages/coding-agent/test/settings-manager.test.ts — verify default, persistence, reload, and effective setting projection.
• packages/coding-agent/test/settings-selector-compaction.test.ts — add focused TUI rendering/value/callback coverage.
• packages/coding-agent/test/settings-selector-thinking-display.test.ts — update shared complete config/callback fixtures for the expanded selector contract.
• packages/coding-agent/test/rpc-settings-commands.test.ts — cover snapshot defaults, boolean validation, persistence, and round-trip projection.
• packages/dashboard/test/client/screens.test.tsx — verify the new dashboard control reflects durable state and sends the expected update.

Documentation

• README.md — advertise uninterrupted automatic-compaction continuation and link to detailed configuration.
• packages/coding-agent/README.md — explain the option in compaction/settings guidance.
• packages/coding-agent/docs/settings.md — add the persisted schema row and example.
• packages/coding-agent/docs/compaction.md — document automatic continuation behavior and manual exclusion.
• packages/coding-agent/docs/rpc.md — add the field to settings snapshots, updates, examples, and validation table.
• packages/coding-agent/docs/dashboard.md — describe the dashboard control.
• packages/dashboard/README.md — keep the dashboard package’s Settings inventory accurate.

Testing approach

• Core behavior: use fake timers and spies around _runAutoCompaction() to verify enabled threshold compaction with no queue continues once; enabled behavior does not call hasQueuedMessages() to make the decision; both automatic reasons remain valid; failed/aborted automatic compaction does not continue; and disabled behavior still distinguishes overflow, queued threshold, and empty threshold paths.
• Manual isolation: enable the setting, invoke the manual compact() path with the existing compaction mocks, and assert agent.continue() is not called.
• Persistence: assert the absent default is false, a setter writes the nested global key, reload preserves it, and getCompactionSettings() exposes the effective value.
• TUI: render the selector with each value, locate the new item through its search/input behavior, and assert changing it invokes the dedicated callback with the selected boolean.
• RPC: extend complete snapshot expectations; verify true/false writes survive flush/reload; reject non-booleans atomically; and include the key in valid-update coverage.
• Dashboard: mount SettingsScreen with enabled, disabled, and absent snapshots; assert the correct selection/default; change it and verify saveSettings receives the new field.
• Validation: run focused Vitest files during development, then npm run build, npm run verify-workspace-links, and the full npm test suite. Run Biome on changed source, tests, and docs as applicable before completion.

Acceptance criteria

• The absent setting defaults to disabled and persists under compaction.continueAfterAutoCompaction when changed.
• Both /settings and dashboard Settings expose and save the option.
• Every successful automatic compaction schedules exactly one continuation when enabled, including threshold compaction with no queued messages.
• Enabled continuation does not inspect or depend on willRetry or agent.hasQueuedMessages() for its decision.
• Failed, cancelled, or otherwise incomplete automatic compactions do not continue because of the setting.
• Manual /compact never continues because of the setting.
• With the setting disabled, overflow recovery and queued-message continuation remain unchanged, and empty threshold compaction still settles.
• Public settings, compaction, RPC, and dashboard documentation agree on the key, default, and scope.
• Focused tests, build, workspace-link verification, and the full test suite pass.

Risks and open questions

• Intentional unbounded work: enabling this option can keep producing model turns and cost indefinitely. UI copy and docs must describe that consequence plainly; defaulting off preserves existing safety.
• Continuation duplication: the enabled branch must short-circuit legacy queue/retry decision logic and schedule only one continuation, while retaining overflow-specific context cleanup.
• Auto/manual boundary: the setting must remain inside the successful _runAutoCompaction() path rather than shared compaction code, so extension-provided successful auto-compactions participate but manual and cancelled compactions do not.
• Merged settings: project settings can override global values under existing merge rules, while TUI/RPC/dashboard setters write global defaults. Tests and docs should reflect the established settings model rather than introducing a separate scope.
• No unresolved product decision blocks implementation; the issue’s updated scope fixes the automatic/manual distinction and unconditional behavior.

---

Plan created by mach6

[github-actions]

Vitest coverage

Metric	Covered	Total	Coverage
Statements	40662	56570	71.87%
Branches	22048	35595	61.94%
Functions	8624	11866	72.67%
Lines	29396	40690	72.24%

View full coverage run

[m-aebrer]

Progress Update

Implemented the always-continue auto-compaction setting across the complete stack:

• Added persistent compaction.continueAfterAutoCompaction configuration, defaulting to off.
• Successful automatic threshold and overflow compactions now continue exactly once when enabled, without consulting queued-message state for the enabled decision.
• Preserved existing overflow retry and queued-message behavior when disabled.
• Kept failed, cancelled, and manual compaction non-continuing.
• Added terminal /settings, persistent RPC, and dashboard Settings controls with explicit unbounded-turn/cost guidance.
• Added focused coverage for core continuation paths, manual/cancelled/failed behavior, persistence, RPC validation and round trips, TUI controls, and dashboard controls.
• Updated the root README, coding-agent README, compaction/settings/RPC/dashboard docs, and dashboard package README.

Validation completed:

• npm run check
• npm run build
• npm run verify-workspace-links
• focused Vitest suite: 458 tests passed
• full non-live suite (DREB_SKIP_LIVE_API=1 npm test): 5,944 tests passed, 720 skipped

A separate raw npm test attempt reached credential-enabled live provider tests and was blocked by the configured ChatGPT enterprise usage limit; the repository-standard non-live suite passed completely.

Commit: 516d532

---

Progress tracked by mach6

[m-aebrer]

Unverified Review Candidates — Pending Assessment

Review round: 1
Reviewed commit: 516d532

These are unverified candidates. Severity reflects reviewer confidence; do not treat any item as a merge blocker until the assessment comment is posted.

Critical

None.

Important

1. Overflow recovery cleanup is not exercised by the focused overflow tests — packages/coding-agent/test/agent-session-auto-compaction-queue.test.ts:146-172 directly invokes _runAutoCompaction("overflow", true) without placing an overflow error assistant message in session state, so it proves continuation but not the retained cleanup in packages/coding-agent/src/core/agent-session.ts:2852-2857. Confidence: 96.

2. Extension-provided successful auto-compaction lacks continuation coverage — packages/coding-agent/src/core/agent-session.ts:2780-2863 shares the new continuation tail with extension-provided compactions, but focused tests cover only extension cancellation, not a valid extension compaction result with the setting enabled. Confidence: 94.

Suggestions

3. Extract the repeated private-method binding in the compaction test setup — packages/coding-agent/test/agent-session-auto-compaction-queue.test.ts:115-216 repeats the same _runAutoCompaction cast and bind across six tests. A beforeEach helper would remove roughly 30 lines of duplication. Confidence: 88.

4. Put the auto-compaction selector tests in a discoverable test module — packages/coding-agent/test/settings-selector-thinking-display.test.ts:232-258 now contains compaction tests alongside unrelated concurrency, arbiter, and thinking-display groups. A focused settings-selector-compaction.test.ts or broader accurate filename would improve navigation. Confidence: 83.

Strengths

• The unified continuation gate is concise and preserves disabled behavior while short-circuiting queue inspection when the setting is enabled.
• Failure, cancellation, and manual-compaction paths return before the new continuation gate, and continuation errors remain visible in-session.
• Persistence, RPC validation, TUI/dashboard wiring, and documentation are consistent and default the setting off.
• The completeness review found every authoritative acceptance criterion implemented.

Agents run: code-reviewer, error-auditor, test-reviewer, completeness-checker, simplifier

---

Reviewed by mach6

[m-aebrer]

Review Assessment

#493 (comment)

Classifications

Finding	Classification	Reasoning
Finding 1: Overflow cleanup test weakness	useful follow-up	Factual: The focused overflow tests do not seed a trailing overflow error, so they do not execute the cleanup slice. Scope: Cleanup preservation is called out in the plan, but the cleanup implementation is pre-existing and remains intact. Practical: No PR-introduced regression was identified; stronger coverage could guard this behavior later but is not required to ship this implementation.
Finding 2: No successful extension-provided compaction continuation test	discarded observation	Factual: There is no extension-success variant. Scope: Extension and built-in compactions merge into the same successful tail before the new continuation gate, while the extension-specific cancellation branch is tested. Practical: The proposed test would exercise the same gate already covered and adds negligible protection against a current defect.
Finding 3: Repeated private-method binding	nitpick	Factual: The cast-and-bind boilerplate repeats across six tests. Scope: This is test-only organization, not required behavior. Practical: Extracting a helper would reduce repetition but would not improve correctness or supported-use outcomes.
Finding 4: Selector tests in an inaccurately named module	nitpick	Factual: Auto-compaction tests live in a file named for thinking display alongside several unrelated groups. Scope: The plan suggested a focused file, but the tests themselves are present and valid. Practical: This affects discoverability only and creates no shipping risk.

Action Plan

No merge blockers. No changes are required before merge.

---

Assessment by mach6