[onevcat]

Closes #573

Terminal layout restore has shipped since 2026-04. Live checks confirm that it works, and they found two problems that would hurt new users if it were on by default. This PR fixes both and promotes the feature.

Changes

• Default on: the setting now defaults to true, and it turns on once for existing users (see below).
• Settings: the toggle and the clear button move from Advanced to General, in a Terminal Layout section. The "(experimental)" label is gone.
• Missing worktree: a saved worktree that is gone at launch is now always skipped. Before, one worktree removed outside Prowl dropped the whole layout and showed an "invalid" warning. allowsMissingWorktrees is removed. A layout that cannot be applied still resets with a warning.
• Empty selection: a restore that names no worktree now selects the last focused worktree, then the first available worktree or plain folder. Before, a quit with no open tabs led to an empty detail view on the next launch.
• Canvas focus: launching into Canvas now focuses the selected tab of the anchor worktree, without zooming the board. Before, keyboard input could go to a restored terminal whose card was not highlighted.
• Focus retries: a newer surface focus request now cancels older requests that are still waiting for a window. Before, a request from restore could land late and take first responder from the highlighted card. This affected about one launch in five in the test below.
• Canvas with folders: Canvas now accepts a plain folder as its entry target, as Shelf does. Before, a setup with only plain folders stayed in Normal view.

Existing users

The setting turns on once for every existing settings file, including for users who turned it off on purpose. Those files store false for anyone who kept the old default, and that cannot be told apart from an explicit choice.

The stored key changes from restoreTerminalLayoutOnLaunch to restoreTerminalLayout, so no migration state is needed. The old key is ignored and is removed on the next save, and a later off stays off. The release notes should mention this change.

If a user enabled the feature in the past and then turned it off, the snapshot file from that time is still on disk. The first launch after the upgrade restores that old layout once. Worktrees that no longer exist are skipped.

Verification

• make check and make test pass. The regression tests failed before the fix.
• Live checks in an isolated Debug instance:

Scenario	Result
New install	Settings file has true; first launch has no warning
Old settings file with false	Turns on, the new key is saved, and the layout is restored on the next launch
Setting turned off after the migration	Stays off, and the layout is not restored
Tabs, splits, selected tab and worktree	Saved layout is identical after a quit and relaunch
Pane folder in a subfolder	Restored
Pane folder outside the worktree	Falls back to the worktree root
Previous commands	Do not run again
Forced kill after Prowl lost focus	Layout is restored
Forced kill with no focus change since the last edit	That edit is lost, as documented
Repository folder gone	Other repositories are restored
Worktree removed outside Prowl	Other worktrees are restored, with no warning (fixed)
No open tabs at quit	Last focused worktree is selected (fixed)
Unreadable file	Removed; the app starts normally with no message
Layout that cannot be applied	Reset with a warning; a worktree is still selected
Default Canvas, two tabs in the selected worktree, second tab selected	Second tab has the highlight and the reported focus, and it is the first responder (AX)
Canvas quit and relaunch, repeated (nil saved selection, two worktrees)	Before the fix, 1 of 5 launches had first responder in the wrong terminal. After it, 20 of 20 match across two builds
Normal and Shelf relaunch, repeated	First responder matches the reported focus in all 10 launches
Default Canvas, plain folder only, nothing saved	Enters Canvas with one focused card
Plain folder only, Normal view, nothing saved	Folder is selected with one focused pane
Clear button	File is removed and stays removed through a focus change and a quit

Not checked: a full cold launch through prowl open auto-launch. The reviewer exercised the launch argument in an isolated instance, and reducer tests cover the path. Real typed input on the final commit is not verified: automation could not deliver keys. Real typing was confirmed only on the earlier commit a797423, and only for a launch where the first responder was already correct. To check by hand, set the default view to Canvas, keep two projects open, quit from Canvas, relaunch several times, and type without clicking. The text must appear in the highlighted card.

Known limit

If a repository fails to load, the next save no longer holds its layout, so its tabs do not return when the folder comes back. This behavior is not new, and it is now documented.

[onevcat]

Review round 1: one finding, fixed in a4657ef. A launch with only plain folders and no saved layout stayed empty, because the selection fallback did not consider plain folders. It now does, after worktrees.

[onevcat]

Review round 2: R1 confirmed fixed. Two new P2 findings in the default Canvas path were fixed in a797423. R2: keyboard input could go to a terminal whose card was not highlighted. R3: a setup with only plain folders could not enter Canvas.

[onevcat]

Review round 3: R1 and R3 confirmed fixed. R2 still reproduced as a race after a Canvas quit and relaunch, because a late retry from restore could take first responder. Fixed in a2b6596: the newest focus request now cancels older ones.

[onevcat]

Review round 4 (last): no new code defects. The fix for R2 passed code review and deterministic tests, but real typed input on the final commit is not verified, because neither the reviewer's tool nor my key events could reach the app. The review ends as not clean for that reason. The PR body has a manual check.