TermRemoteCtl/docs/superpowers/plans/2026-03-29-terminal-next-steps.md

Terminal Next Steps 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: Finish the terminal feature from "developer-ready" to "stable for manual product testing" by closing emulator-local transport gaps, shrinking TerminalPage, and fixing issues found during smoke testing.

Architecture: Keep the helper-backed ConPTY backend and the current HTTP/HTTPS + WebSocket protocol. Continue moving terminal UI state out of TerminalPage into focused controllers/coordinators, while preserving the current live attach, reconnect, resize, and history behavior.

Tech Stack: Flutter, Riverpod, Dio, xterm, ASP.NET Core, WebSocket, helper-backed ConPTY.

---

Task 1: Stabilize Local Emulator Test Mode

Files:

• Modify: apps/mobile_app/android/app/src/main/AndroidManifest.xml

• Modify: apps/windows_agent/src/TermRemoteCtl.Agent/appsettings.json

• Modify: apps/windows_agent/src/TermRemoteCtl.Agent/Configuration/AgentOptions.cs

• Modify: apps/windows_agent/src/TermRemoteCtl.Agent/Configuration/AgentOptionsValidator.cs

• Modify: apps/windows_agent/src/TermRemoteCtl.Agent/Configuration/AgentOptionsServiceCollectionExtensions.cs

• Modify: apps/windows_agent/src/TermRemoteCtl.Agent/Configuration/AgentEndpointConfiguration.cs

• Test: apps/windows_agent/tests/TermRemoteCtl.Agent.Tests/Configuration/AgentOptionsValidatorTests.cs

• Test: apps/windows_agent/tests/TermRemoteCtl.Agent.Tests/Configuration/AgentOptionsPipelineTests.cs

• Verify the current local-test path still works with http://10.0.2.2:5067. Run: Invoke-WebRequest -UseBasicParsing 'http://127.0.0.1:5067/health' Expected: {"status":"ok"}

• Run the configuration-focused .NET tests. Run: dotnet test apps/windows_agent/tests/TermRemoteCtl.Agent.Tests/TermRemoteCtl.Agent.Tests.csproj --filter "AgentOptionsValidatorTests|AgentOptionsPipelineTests" Expected: PASS

• Rebuild the Android release APK used for local emulator testing. Run: C:\tools\flutter\bin\flutter.bat build apk --release Expected: Built build\app\outputs\flutter-apk\app-release.apk

Task 2: Finish Extracting TerminalPage Orchestration

Files:

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

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

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

• Create or modify as needed: apps/mobile_app/lib/features/terminal/terminal_session_coordinator.dart

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

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

• Move reconnect scheduling, history loading window size, and socket attach lifecycle out of TerminalPage and into a focused coordinator/controller.

• Keep TerminalPage primarily responsible for widget composition and command callbacks.

• Preserve existing behaviors:

  • attach waits for ack
  • resize sends immediately after attach
  • scrollback mode can load older lines
  • new live output while browsing history shows a return-to-live affordance

• Run Flutter tests after each extraction step. Run: C:\tools\flutter\bin\flutter.bat test test/features/terminal/terminal_interaction_controller_test.dart test/widget_test.dart Expected: PASS

Task 3: Improve User-Facing Error Guidance

Files:

• Modify: apps/mobile_app/lib/features/sessions/session_list_page.dart

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

• Modify: apps/mobile_app/lib/core/network/agent_api_client.dart

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

• Replace raw Dio/socket exception dumps in the UI with actionable messages for the main local-test cases:

  • agent unreachable
  • HTTPS certificate rejected
  • session history failed but live attach may still recover

• Add copy that explicitly tells emulator users to try http://10.0.2.2:5067 when relevant.

• Verify widget coverage still passes. Run: C:\tools\flutter\bin\flutter.bat test test/widget_test.dart Expected: PASS

Task 4: Run Manual Smoke and Fix What Breaks

Files:

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

• Modify: terminal/mobile/agent files only as required by issues discovered in smoke testing

• Run the current manual smoke checklist against the emulator-local HTTP setup.

• Record which steps fail and fix them one by one.

• After each fix, re-run the smallest relevant automated test set before re-testing manually.

• Final verification set for this phase: Run: C:\tools\flutter\bin\flutter.bat test test/widget_test.dart test/features/terminal/terminal_interaction_controller_test.dart test/features/terminal/terminal_controller_test.dart test/features/terminal/terminal_socket_session_test.dart test/core/network/agent_api_client_test.dart Expected: PASS

• Final backend verification set for this phase: Run: dotnet test apps/windows_agent/tests/TermRemoteCtl.Agent.Tests/TermRemoteCtl.Agent.Tests.csproj Expected: PASS

Run: dotnet test apps/windows_agent/tests/TermRemoteCtl.Agent.IntegrationTests/TermRemoteCtl.Agent.IntegrationTests.csproj --filter "SessionHistoryApiTests|SessionFlowTests|TerminalWebSocketHandlerTests" Expected: PASS