Doni/TermRemoteCtl
5
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
b460957bcf
TermRemoteCtl/docs/superpowers/plans/2026-04-10-terminal-truth-source-reset.md

7.3 KiB
Raw Blame History

Terminal Truth-Source Reset Implementation Plan

For agentic workers: REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Reset the terminal architecture so the mainline uses a single rendering truth source, while isolating backend-authoritative screen recovery into an explicit experiment path.

Architecture: Keep backend journal, restore, and output as the durable data path; keep frontend xterm as the visible rendering path; remove backend screen protocol from the default runtime path; quarantine the backend screen engine and related protocol into an experiment track.

Tech Stack: ASP.NET Core minimal APIs, C#, Flutter, xterm, websocket_channel, Flutter widget tests, .NET unit tests, Markdown specs and plans.

Task 1: Lock The Mainline Runtime Boundary With Failing Frontend Tests

Files:

  • Modify: apps/mobile_app/test/widget_test.dart

  • Modify: apps/mobile_app/test/features/terminal/terminal_page_input_test.dart

  • Test: apps/mobile_app/test/widget_test.dart

  • Test: apps/mobile_app/test/features/terminal/terminal_page_input_test.dart

  • Step 1: Add a failing widget test that proves TerminalPage ignores backend screen_snapshot by default and still renders legacy restore content

  • Step 2: Add or update a widget test that proves backend screen protocol only affects rendering when explicitly enabled

  • Step 3: Run C:\\tools\\flutter\\bin\\flutter.bat test test/widget_test.dart --plain-name "screen snapshot" from apps/mobile_app and confirm the new expectations fail before the implementation change

  • Step 4: Run C:\\tools\\flutter\\bin\\flutter.bat test test/features/terminal/terminal_page_input_test.dart to verify the terminal input baseline remains intact before refactoring

Task 2: Remove Backend Screen Protocol From The Default Mobile Path

Files:

  • Modify: apps/mobile_app/lib/features/terminal/terminal_page.dart

  • Modify: apps/mobile_app/lib/features/terminal/terminal_session_coordinator.dart

  • Modify: apps/mobile_app/lib/features/terminal/terminal_socket_session.dart

  • Modify: apps/mobile_app/test/widget_test.dart

  • Step 1: Add an explicit runtime flag on TerminalPage and TerminalSessionCoordinator so backend screen protocol is disabled on the default app path

  • Step 2: Ensure the default runtime path subscribes only to restore and output as rendering truth

  • Step 3: Keep screen protocol callbacks available only for explicit experiment wiring

  • Step 4: Re-run C:\\tools\\flutter\\bin\\flutter.bat test test/widget_test.dart --plain-name "screen snapshot" and confirm the default-path tests pass

  • Step 5: Re-run C:\\tools\\flutter\\bin\\flutter.bat test test/features/terminal/terminal_page_input_test.dart and confirm input behavior still passes

Task 3: Strip Mainline Rendering Dependency On Screen Models

Files:

  • Modify: apps/mobile_app/lib/features/terminal/terminal_page.dart

  • Modify: apps/mobile_app/lib/features/terminal/terminal_screen_snapshot.dart

  • Modify: apps/mobile_app/lib/features/terminal/terminal_screen_state.dart

  • Modify: apps/mobile_app/test/features/terminal/terminal_screen_state_test.dart

  • Step 1: Remove any mainline rendering assumptions that convert backend screen models into replay text for xterm

  • Step 2: Keep screen-model helpers only if they are clearly marked as experiment-only and are no longer part of the default runtime path

  • Step 3: Drop or relocate tests that currently validate screen-model replay as mainline terminal behavior

  • Step 4: Run the targeted Flutter tests that still belong to the mainline and confirm no mainline test depends on backend screen snapshot replay

Task 4: Simplify Backend Mainline Websocket Contract

Files:

  • Modify: apps/windows_agent/src/TermRemoteCtl.Agent/Realtime/TerminalWebSocketHandler.cs

  • Modify: apps/windows_agent/src/TermRemoteCtl.Agent/Sessions/SessionRegistry.cs

  • Modify: apps/windows_agent/tests/TermRemoteCtl.Agent.IntegrationTests/Realtime/TerminalWebSocketHandlerTests.cs

  • Step 1: Add failing backend tests that define the stable mainline websocket contract as attached + restore + output

  • Step 2: Remove default runtime emission of screen_snapshot, screen_patch, and screen_sync from the mainline websocket flow, or gate them behind an explicit experiment switch

  • Step 3: Keep sequence-aware restore and output semantics intact

  • Step 4: Run dotnet test apps/windows_agent/tests/TermRemoteCtl.Agent.IntegrationTests/TermRemoteCtl.Agent.IntegrationTests.csproj --filter "TerminalWebSocketHandlerTests" and verify the stable contract passes

Task 5: Isolate Backend Screen Engine Into An Experiment Track

Files:

  • Modify: apps/windows_agent/src/TermRemoteCtl.Agent/Terminal/Screen/TerminalScreenEngine.cs

  • Modify: apps/windows_agent/src/TermRemoteCtl.Agent/Terminal/Screen/TerminalScreenPatch.cs

  • Modify: apps/windows_agent/tests/TermRemoteCtl.Agent.Tests/Terminal/TerminalScreenEngineTests.cs

  • Modify: docs/superpowers/specs/2026-04-10-terminal-truth-source-reset-design.md

  • Step 1: Stop treating TerminalScreenEngine as a production-ready mainline dependency

  • Step 2: Rename, relocate, or clearly annotate screen-engine code and tests as experiment-only

  • Step 3: Keep the experiment test suite runnable in isolation, but do not let it define default product behavior

  • Step 4: Run dotnet test apps/windows_agent/tests/TermRemoteCtl.Agent.Tests/TermRemoteCtl.Agent.Tests.csproj --filter "TerminalScreenEngineTests" and verify the experiment suite remains green in isolation

Task 6: Clean Up Docs And Developer Guidance

Files:

  • Modify: docs/superpowers/specs/2026-04-10-terminal-truth-source-reset-design.md

  • Modify: docs/testing/manual-smoke-checklist.md

  • Modify: README.md

  • Step 1: Document that the stable product path is restore/output + xterm, not backend screen snapshots

  • Step 2: Document that backend-authoritative screen recovery is an experiment branch concern

  • Step 3: Update manual smoke checks to focus the mainline on stable shell input, reconnect, resize, and repeated command execution

  • Step 4: Add a short note in README.md or a developer-facing doc explaining the single-truth-source rule

Task 7: Final Verification

Files:

  • Verify only

  • Step 1: Run C:\\tools\\flutter\\bin\\flutter.bat test test/widget_test.dart test/features/terminal/terminal_page_input_test.dart from apps/mobile_app

  • Step 2: Run dotnet test apps/windows_agent/tests/TermRemoteCtl.Agent.IntegrationTests/TermRemoteCtl.Agent.IntegrationTests.csproj --filter "TerminalWebSocketHandlerTests"

  • Step 3: Run dotnet test apps/windows_agent/tests/TermRemoteCtl.Agent.Tests/TermRemoteCtl.Agent.Tests.csproj --filter "TerminalScreenEngineTests" only as experiment verification, not as a mainline gate

  • Step 4: Perform a manual smoke check with pwd -> ls -> pwd, reconnect once, resize once, and verify the prompt remains usable

  • Step 5: Summarize the final boundary in release notes or task output: mainline is stable-shell-first, experiment branch is backend-screen-first