Multiplexer Phase 5: default-on, update survival, windowless agents, remote picker, release

[benyblack]

Multiplexer Phase 5. Local shells now keep running by default, survive app updates, and agents can reach them without a window. "Attach to session…" and ntilde mux ls --all reach remote hosts, and persistent native SSH tabs get Remote Files and SFTP. Includes the 13 review items from the Phase 5 brief, a single user-manual chapter, a CHANGELOG, and the bump to 0.12.0.

It builds on the sync PR #510, already merged into dev-mux.

• Spec: docs/superpowers/specs/2026-10-08-ntilde-mux-phase5.md. This is the brief plus §R: rulings R1–R30, made while the work was done.
• Plan (31 tasks): docs/superpowers/plans/2026-10-08-ntilde-mux-phase5.md.
• User manual: chapter 12, Persistent sessions and the multiplexer.
• Manual checklist: docs/superpowers/plans/2026-10-08-ntilde-mux-phase5-manual-checklist.md.

Every task went through an implementer, a task review and fix rounds with scoped re-reviews. A whole-branch review followed, with one fix round of its own (see Final review below).

By brief section

§4: the review items (Part A)

Each item landed with a test that failed first.

Brief item	Commit(s)	Pinning test
Sends from the UI thread never block on a full outbound queue. This covers the local close kill, detach and leave, the faulted session's kill on reconnect, input, and resize.	6f82d3c	MuxClientNonBlockingSendTests, MuxLocalCloseStalledLinkTests
No vault password is offered to a prompt a jump host could send (OpenSSH askpass, interactive)	3b39e5a, d6919ff	SshAskPassVaultPolicyTests, RemoteMuxHostFactoryTests, OpenSshExecCommandLineTests
Native known hosts: one store per file, an atomic TrustHost, and a store that cannot be read is never overwritten	403de65, 5b9c8b0	NativeKnownHostsStoreTests
RemoteMuxCommand quotes a recorded path that has spaces or non-ASCII characters, instead of replacing it	6e516a3, da6a4a6	RemoteMuxCommandTests
The askpass marker folder is 0700; control and bidi characters are stripped from server text in toasts; the native response payload is zeroed	5bc3050	SshAskPassVaultOnlyTests, RemoteMuxFailureClassifierTests, NativeSshPromptResponderTests
The install directory honours $XDG_DATA_HOME	fcd1120	RemoteMuxInstallCommandsTests, RemoteMuxCommandTests
CI runs the remote-persistence E2E when only its tests change	5681207	scripts/tests/aot_gate_paths_tests.py
Remote shells get a stable SSH_AUTH_SOCK link. The proxy repoints it on connect, and the target must be a live socket owned by this user.	8a6fd8a, cec9520	AgentSocketLinkTests, MuxProxyTests, LocalShellSessionFactoryTests
Native exec waits for events instead of sleeping 10 ms	cc734f1, d86bd41	NativeSshExecTransportTests, Rust event_wait_tests
ntilde-mux on macOS is signed and notarized, with the notarization status checked; the App pins the ntilde-mux SHA-256s	fad1d08, 70d137d	MuxAssetSourceTests, MuxAssetPinsTests

§3: the agent host sees windowless sessions (Part B)

• The daemon gains readScreen as an optional protocol method. A v1 daemon answers "unsupported", and the agent tools say so.
• The window publishes the sessions no pane shows. list_sessions marks them windowless. read_screen, read_scrollback, get_session_status, capture_screen (render), send_input and close_session take their ids. Every read appears in the activity journal.

§1: the default (Part C)

• SessionPersistence is KeepOnClose by default for local shells. Off behaves exactly as before Phase 5.
• Closing the window: the first close asks Keep running / Close them, with Don't ask again.
• Quit and close all: Session: Quit and Close All Shells, plus a link under the setting.
• After a reboot, tabs start fresh shells quietly. The boundary is the later of the boot time and, on Windows, the logon time. If the boundary can't be read, the change is announced.
• Tests and the designer windows pin persistence Off, so a test can never start a daemon.

§2: sessions survive app updates (Part D)

• The daemon reports its build on the wire and in its descriptor. Both fields are optional.
• On a Windows Velopack install the daemon runs from a copy at <app-data>\bin\<version>\. Velopack's apply kills every process whose image is under the install root, so this copy is what keeps it alive (measured, R9). Old copies are pruned. Uninstall stops the daemon and removes its copies.
• A compatible daemon is kept when an update is applied. Releases carry <!-- ntilde-mux-protocol: <min>-<max> --> in their notes, and the App keeps the daemon when the ranges overlap. An incompatible update asks first and closes the sessions. Startup auto-apply is vetoed only when the daemon runs from inside the install root, or with persistence Off.
• A daemon from another build raises a notice: "Multiplexer is from the previous build" (or a newer one, or a different one), with Restart multiplexer now. Panes are let go before the shutdown and reconnect to the new daemon.
• Evidence: a real Velopack update, applied with the daemon live, in a sandboxed NtildeSurvival install (scripts/mux-update-survival.ps1 / .sh). The daemon kept its pid and both heartbeat shells.

§5: remote endpoints (Part E)

• "Attach to session…" lists local and remote sessions. Each profile that keeps sessions but isn't connected gets a row Connect to user@host…, which shows Connecting to user@host… while it works. Unreachable hosts show a reason taken from a fixed cause list.
• Shared remote tabs stay shared through drops. A share whose sharing can't be confirmed right now detaches on close and never queues a kill.
• ntilde mux ls --all lists this computer and every profile that keeps sessions:
  • it runs in parallel, with 15 s per host;
  • it never prompts, and never pushes off a GUI connection;
  • it has a HOST column and --json;
  • on Linux and macOS it skips OpenSSH profiles that go through a jump host or proxy (R28b).

§6: SFTP and remote files on persistent tabs (Part F)

• Native persistent tabs register with a per-host password scope, so Remote Files, path completion and transfers work as they do on plain native tabs. Only a password the user typed, in an attempt that got in, is kept:
  • never one filled from the vault;
  • never an empty one;
  • never on a jump-host profile (R7, R30).
• OpenSSH persistent tabs get palette transfers.
• Retargeted hosts: once the profile's host has been changed since the tab opened, the sidebar and transfers are refused.
• Deferred: port forwards, and OpenSSH ControlMaster reuse (R8).

§7: release (Part G)

• The user manual gets chapter 12, plus a README bullet and subsection.
• ARCHITECTURE and MODULE_OWNERSHIP are updated.
• New CHANGELOG.md, and a release-notes draft in docs/announcements/2026-10-09-persistent-sessions.md.
• The version is now 0.12.0 (release: 0.12.0). Tagging is the maintainer's step.

Tests

On 0887ad2, the head before the final fix round (both App.Tests lanes were run again on the final head; see Final review):

Suite	Passed	Failed	Skipped
VT	860	0	0
Rendering	114	0	0
Architecture	113	0	0
Platform	632	0	32
McpServer	202	0	0
Mux	957	0	41
App main lane	6069	0	29
App PlatformBoot lane	59	0	4
rusty_ssh cargo test	135	0	0

Update survival (Windows), re-run at the head on fresh AOT builds: 34 of 34 checks passed. Velopack 1.2.0 applied .1 → .2 in 2.0 s while the daemon ran from its copy. The daemon's pid stayed the same, both heartbeat shells kept advancing, and ntilde mux ls listed the same ids. The new GUI offered the restart. The uninstall hook stopped the daemon, and the user PATH came back byte-identical. An earlier Linux run in Docker (AppImage, FUSE, Xvfb) passed 15 of 15.

Manual checklist (159 cells):

• 13 PASS, run by the implementer: Windows CLI and ls --all, plus Linux CLI, ls --all, the jump-host skip, the agent's windowless session, and the GUI kill under Xvfb.
• 0 FAIL.
• 136 OPEN for the maintainer: the GUI steps on Windows and Linux, and all of macOS.
• 10 N/A.

Final review

A whole-branch review ran on the most capable model, over f529f6c..0887ad2. It found no Critical issues, one Important and six Minor, and ruled on each of the roughly 75 items parked during the tasks. Every hard constraint held:

• the credential path adds no replay, vault or empty-password behaviour;
• the protocol change is additive and checked against the base daemon;
• layering is unchanged;
• with persistence Off, both update paths behave as before Phase 5;
• every kill path re-checks its target.

Fixed in one fix round, plus a residual round after its scoped re-review:

Finding	Fix	Commit
I1. The remote "previous version" notice and its Restart compared the running ntilde-mux with the app's version. After every app update this nagged on every host, and Restart killed the host's shells only to start the same old binary again.	Restart is offered only when the version recorded as installed on the host is newer than the running one. When the host's ntilde-mux is simply older than the app, the notice offers Update ntilde-mux on {host}… instead. Once a remote shutdown has been sent, the host is not offered a restart again in that launch. After an install, the restart is offered straight away.	8022c2f, ec21b7f
M2. The MCP footnote said a windowless id "works with every session tool".	It now names the six tools that take one.	650fc27
M1. Two new off-thread reads of Dispatcher.UIThread (the #81 hang mechanism).	Both go through the window's own dispatcher.	adaaf36
M3. "Close them" and the first-close count missed the shells of restored tabs not shown yet.	These are counted and ended, except shares. The list is taken again just before ending. The close hold is released on every path.	259d00c, 990d458, 869218f
M5. A nonsense boot time could crash startup.	It now reads as "no boundary", which is the loud side.	3b19cd4
A manual paragraph described a toggle that does not exist.	Corrected.	d379582

Both App.Tests lanes passed on the final head: main 6112 passed, 0 failed (29 skipped), PlatformBoot 59 passed, 0 failed (4 skipped).

PR review round

The review round fixed Greptile's three findings and a maintainer heads-up about the default and startup updates. A scoped re-review checked each fix, and a residual round followed.

Finding	Fix	Commits
Greptile P1: "Close them" missed startup tabs not built yet, because their saved shells live in the placeholder's tree.	The hold, the count, the re-list and the kill pass all include placeholder ids. Shares, quiet-lost ids and remote ids are excluded. A null child in a hand-edited file is skipped.	01ce6a5, cbfc799, 1e9d258
Greptile P2: stopping the whole daemon (quit and close all, or an update that cannot keep it) left unvisited tabs' ids in the session file, so those tabs reported "previous session lost".	Those ids are dropped from the save. The quit drops them only once they are known gone: the stop went through, or each shell was killed by name. Otherwise they stay named and reopen in their tabs.	c6f8efd, cbfc799
Greptile P2: an agent listing windowless sessions did not light the window's activity indicator.	A listing that returns windowless rows lights it.	3ca832f
Heads-up: turning the default on would stop updates installing at startup unless the update-survival work ships too.	In this PR both ship. The startup gate holds an update back only for a daemon whose image is inside the install folder, or when persistence is Off. The re-run at the head proved the startup apply goes through with the daemon live. A test now pins it: default settings and a daemon image outside the root do not block, and an image inside the root does. The residual case is the daemon falling back to the install folder because its own copy could not be staged. There, debug.log now says why the startup apply was held. The "Restart to update" question names the real reason ("running from the install folder") instead of the protocol one. The two boolean wrappers that only tests called are gone.	3c1c2eb, b98f7cb, 041082d, 5c2147b

Both App.Tests lanes passed on the final head: main 6149 passed, 0 failed (29 skipped), PlatformBoot 59 passed, 0 failed (4 skipped). Architecture 113 passed, 0 failed. McpServer passed 202/0 on 041082d.

Codex review round

Codex reviewed 5c2147b and raised three findings. All three were valid, all in code from this phase, and all are fixed.

Finding	Fix	Commit
P1: rerunning a published release breaks macOS installs. A rerun for an already-published tag signs the macOS ntilde-mux again. The new timestamp gives new bytes, and the upload overwrites the asset. Installed apps pin the original hash, so they reject it.	Reruns of a tag that already has ntilde-mux assets are refused. scripts/ci/mux-release-guard.sh preflight runs in release_metadata, before anything is built, signed or uploaded, and fails closed on any unexpected gh answer. The upload uses overwrite_files: false. At the pinned action version that setting skips an existing asset rather than failing, so the job then fails unless both of its assets were really uploaded. A run that stopped partway is finished with "Re-run failed jobs". Tests: 26 cases with a fake gh, plus ReleaseWorkflowTests.	d9ae916
P1: a refused password stays in the transfer scope. The host's SFTP and listing connections kept offering a password the server had refused, for example after a password rotation, which could pile up failed logins.	A remembered password the host forgets as refused also leaves the host's scope, under the server it was offered to. It is removed only while the scope still holds that same value, and under the same generation check as the write.	131c827
P2: an existing askpass folder is not owner-only after an upgrade.	The askpass writer tightens an existing folder to 0700 before writing any marker. If that fails (not ours, or a link), it writes nothing and askpass takes its no-evidence path. PrivateDirectory's rule for the daemon's socket folder is unchanged. Spec R14 is amended to match.	752e2fc, d733bdc

Results on d733bdc:

Suite	Passed	Failed	Skipped
App.Tests main lane	6163	0	32
App.Tests PlatformBoot lane	59	0	4
Platform	632	0	32
Mux	957	0	41
Architecture	115	0	0

The askpass POSIX tests passed 132/132 in the Linux Docker image.

Notes for the maintainer

• The default needs the update-survival work (Part D). Never ship 5756680 (the flip) without Tasks 20-22. With shells kept and no daemon copy, a daemon would nearly always run from the install folder, and every startup update would be held back. In history the flip comes before Part D, so don't cherry-pick it on its own.
• Dropping the default. If you decide against the on-by-default flip, drop 5756680 (the flip) and 80fdeb0 (the docs lines that state the default). Both drop cleanly; a trial rebase --onto checked that. Then reword three commit-1 sentences that read as default behaviour: the README "Why Ntilde?" bullet, CHANGELOG.md:10, and the announcement's line 27. The remaining docs will be neutral rather than saying "off by default".
• Before dev-mux → main:
  • run the macOS update-survival run (scripts/mux-update-survival.sh), which has not been run anywhere;
  • run the no-overlap in-app apply path (checklist step 38);
  • go through the OPEN checklist cells.
• macOS Cmd+Q never asks (R19). Mac users who quit the usual way are never told their shells keep running.
• ls --all in a script loop. Each run is a new attempt with no memory of a refusal. A loop with a stale saved password offers it once per run, which fail2ban-style lockouts may count.
• A slow remote host delays list_sessions for windowless sessions, by up to about 4 s per hung host (7 s in all).
• Startup auto-apply ends other Ntilde windows. Velopack's apply kills every process whose image is under the install root, so any other Ntilde process running from the install goes too. This is unchanged from before Phase 5; the daemon is safe because it runs from its copy.
• CHANGELOG.md is not wired into the release body. release.yml still uses GitHub's generated notes plus the protocol marker. This is a follow-up.

Follow-ups (not blocking)

These were triaged by the final review. None blocks the merge into dev-mux.

UX

• Restart and quit
  • A restart shows no progress feedback (about 12 s).
  • A new tab or split during a local restart can land on the old daemon. A host-level restart flag would cover it.
  • Enter on a focused Close them button still answers Keep running.
  • Cmd+Q with a remembered "Close them" leaves the shells of tabs not yet shown running. Nothing is lost: they come back as restored tabs.
  • Quit-and-close-all, and an update that cannot keep the daemon, leave the ids of tabs not yet shown in the session file. Those tabs then show "previous session lost" at the next launch.
• Remote
  • Cancelling an SSH prompt from a Connect to… row shows "Could not connect". RemoteFailureKind has no "cancelled" cause.
  • The transfer dialog's path completion is not checked against a changed (retargeted) host. It only lists; no transfer starts.
  • When a pinned profile's host has changed, the connector's record of the installed version can lag (it errs toward no restart).
• Restore after logout: on macOS, and on Linux hosts with KillUserProcesses=yes, the quiet-restore boundary misses a logout without a reboot. It errs on the loud side.

Hardening

• When the daemon cannot stage its own copy, it runs from the install folder, and with shells kept every startup update is held back. debug.log and the update question say why, but no notice says so when it happens. A once-per-launch notice needs about 60 lines of plumbing from the spawner to the window.

• A Task 23 local restart marks no ended ids, so a shell that outlives a failed stop is still reopened. After a successful restart, unvisited tabs therefore say "previous session lost".

• The accepted corner of the update path: a daemon whose image cannot be checked (UnknownImage), that really runs outside the root, and that survives a failed shutdown. It is documented in ARCHITECTURE.

• Copy the daemon image in Velopack's install/update callback instead of inside the first pane's connect wait, and cache the image's hash. On a slow disk with Defender scanning, the first tab could otherwise fall back to a non-persistent shell.

• Plain ntilde mux ls and ntilde-mux ls print session titles uncleaned. Ntilde.Mux needs its own Clean.

• The offline Copy install command still trusts the release's own .sha256. Embed the pinned hash.

• RustPtySession prepends /k chcp 65001 to any shell whose path ends in cmd.exe, so mycmd.exe gets it too. Compare the file name instead.

• ntilde mux attach disconnects on a paste over about 9 MiB (send overflow). It needs a blocking-send variant for producers that aren't on the UI thread.

• Host normalisation is asymmetric for a bracketed or ported target against an identical hop ([::1], :port). This is contrived, but it is on the credential path.

• CaptureLiveAsync has an older off-thread Dispatcher.UIThread.InvokeAsync read. It predates this phase but is the same mechanism.

• kill-server counts a zombie daemon as running, in containers without an init process.

• SFTP and listing refusals clear nothing. An SFTP or listing connection's own refusal does not clear the scope, and plain native tabs keep a typed password until the tab closes. Only the mux host's refusal clears it (Codex round).

Docs and tests

• Connect CHANGELOG.md to the release body.
• The MCP SettingsTools text quotes the checkbox without "(ntilde-mux)". This was left alone so that dropping the flip stays clean.
• The ls --all --json endpoint id uses the N-format GUID (no dashes); the manual doesn't say which form.
• Remaining test-strength and doc-wording nits are listed per task in the review's triage table.
• The VT throughput benchmark floor flakes under full-suite load.

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: defaults
• Review profile: CHILL
• Plan: Advanced
• Run ID: 24da4b33-7946-4306-a5a1-beabaff89ef7

---

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

---

_{Comment @coderabbitai help to get the list of available commands.}

[greptile-apps]

Confidence Score: 4/5

[Critical impact] Multiplexer Phase 5: persistent sessions, daemon lifecycle, remote mux, and release infrastructure.

Fix the upload guard’s source before merging so manual releases of older commits can finish.

Findings

1.  Older releases stop halfway ▶

Summary

This PR turns local persistence on by default and adds update survival, windowless agent access, remote session picking, and transfers on persistent SSH tabs.

• Local shells keep running by default when their window closes.
• Compatible app updates can leave the multiplexer and its shells running.
• Agents can reach sessions that no window pane shows.
• The session picker and command-line list now reach remote hosts.
• Persistent remote tabs can use Remote Files and SSH transfers.
• Release materials and checks now describe the multiplexer in version 0.12.0.

Diagram

%%{init: {'theme': 'neutral'}}%%
flowchart LR
  A[Workflow ref] --> B[Preflight guard]
  B --> C[Checkout selected release commit]
  C --> D[Build and upload daemon]
  D --> E[Run guard from release checkout]
  E -->|Script exists| F[Pass checksum to app builds]
  E -->|Older commit lacks script| G[Release stops]

Loading

_{Reviews (3) · Last reviewed commit: "docs(spec): R14 - an existing askpass fo..." · Reviewed by Greptile}

[benyblack]

@codex review

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	✅ Completed 2026-10-09T13:13:38.840133Z	5c2147b	Manual request

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 5c2147b69f

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[sonarqubecloud]

Quality Gate passed

Issues
74 New issues
0 Accepted issues

Measures
0 Security Hotspots
0.0% Coverage on New Code
0.0% Duplication on New Code

See analysis details on SonarQube Cloud