SubMiner/backlog/tasks/task-88 - Fix-second-instance-start-handling-when-overlay-runtime-is-already-initialized.md

id, title, status, assignee, created_date, updated_date, labels, dependencies, references, priority

id	title	status	assignee	created_date	updated_date	labels	dependencies	references	priority
TASK-88	Fix second-instance --start handling when overlay runtime is already initialized	Done	codex	2026-03-06 07:30	2026-03-06 07:31			/home/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.ts /home/sudacode/projects/japanese/SubMiner/src/core/services/cli-command.test.ts	medium

Description

Restore the CLI command guard so a second-instance --start request does not reconnect or reinitialize overlay work when the overlay runtime is already active, while preserving other second-instance commands.

Acceptance Criteria

• #1 Second-instance --start logs that the app is already running when the overlay runtime is initialized.
• #2 Second-instance --start does not reconnect the MPV client when the overlay runtime is already initialized.
• #3 Second-instance commands that include non-start actions still execute those actions.
• #4 Regression coverage documents the guarded second-instance behavior.

Implementation Plan

1. Reproduce the failing handleCliCommand second-instance --start regression in src/core/services/cli-command.test.ts.
2. Update src/core/services/cli-command.ts so second-instance --start is ignored when the overlay runtime is already initialized, while still allowing non-start actions in the same invocation.
3. Run focused CLI command tests, then rerun the core test target if practical, and record acceptance criteria/results.

Implementation Notes

Reproduced the failing second-instance --start regression in src/core/services/cli-command.test.ts before editing.

Restored a guard in src/core/services/cli-command.ts that ignores second-instance --start when the overlay runtime is already initialized, but still allows other flags in the same invocation to run.

Verification: bun test src/core/services/cli-command.test.ts, bun run test:core:src, and bun run test all pass; the six immersion tracker tests remain skipped as before.

Final Summary

Restored the missing second-instance --start guard in src/core/services/cli-command.ts.

• Added an ignoreSecondInstanceStart check so handleCliCommand logs Ignoring --start because SubMiner is already running. when a second-instance --start arrives after the overlay runtime is already initialized.
• Updated start gating so pure duplicate --start requests no longer reconnect the MPV client, while combined commands such as --start --toggle-visible-overlay still execute their non-start behavior and can connect through those paths.
• Verified the regression with existing CLI command coverage and reran the broader test targets.

Tests run:

• bun test src/core/services/cli-command.test.ts
• bun run test:core:src
• bun run test

Notes:

• The six skipped immersion tracker tests are unchanged from the pre-fix baseline.