fix(continuum): singleton-guard auto-save, drop Start-Job

[CosminRadu]

Summary

The client-attached hook in plugin.conf and the Start-Job spawn in psmux-continuum.ps1 each launched a fresh persistent pwsh loop on every re-attach / plugin load with no de-duplication. Over days this accumulated long-running ~100 MB pwsh processes whose memory continued to grow. The misleading plugin.conf comment even acknowledged the duplication ("multiple loops may start — this is harmless since saves are idempotent") — but each loop is a persistent background process consuming real memory.

After running locally for ~8 days my session had 5 zombie auto_save.ps1 loops totaling ~580 MB; the oldest had been alive for over a week and grown from ~100 MB to 124 MB.

What changed

Singleton enforcement

auto_save.ps1 now claims a PID file at %LOCALAPPDATA%\psmux-continuum\auto_save.pid:

• On launch, if a live pwsh / powershell PID owns the file, exit 0 immediately. The client-attached hook is now safe to re-fire on every attach.
• Stale PID detection: if the recorded PID isn't a live pwsh, the new launch claims the slot.
• The loop releases the slot via try { … } finally { … } and self-exits gracefully if superseded (per-iteration check that the PID file still points at us).
• Periodic [GC]::Collect() every 4 iterations bounds long-run memory growth.

Single-process spawn

Replaced Start-Job with Start-Process -WindowStyle Hidden. Start-Job spawned an outer scriptblock-host pwsh that itself spawned the inner pwsh -File auto_save.ps1, so every plugin load created two pwsh processes that never reaped (you could see this in the zombie list — the outer was the parent of the inner). Start-Process gives a single detached pwsh; the singleton guard inside the loop makes repeat launches safe.

Diagnosable logging

Start-Process -WindowStyle Hidden has no console attached, so the loop's Write-Host output was previously discarded. Added a Log helper that timestamps each line with [INF] / [WRN] / [ERR] and appends to %LOCALAPPDATA%\psmux-continuum\auto_save.log, with 256 KB rotation to a .old sibling file. Per-write Add-Content keeps file locks brief, so concurrent ephemeral pwshs (the singleton-rejected ones) don't corrupt each other's writes. The & pwsh -File save.ps1 invocation now redirects all six PowerShell streams (*>> \$logFile), so save.ps1 errors land in the log too.

Sample log output:

[2026-05-02 14:30:01] [INF] [PID 1234] claimed singleton slot; interval=15m
[2026-05-02 14:45:01] [INF] [PID 1234] auto-saved.
[2026-05-02 15:00:01] [WRN] [PID 1234] psmux server not running, stopping auto-save.
[2026-05-02 15:00:01] [INF] [PID 1234] exiting; releasing singleton slot.

Conventions

• All three regenerated helper scripts (`auto_save.ps1`, `auto_restore.ps1`, `boot.ps1`) now carry a `# DO NOT EDIT — regenerated from psmux-continuum.ps1 on plugin load` header so contributors edit the heredoc, not the artifact.
• The misleading `plugin.conf` comment is corrected to describe the new singleton behavior.
• Heredoc and standalone artifact are byte-identical (regeneration is a no-op against this checkout).

Test plan

• Both `psmux-continuum.ps1` and `scripts/auto_save.ps1` parse (verified via `PSParser::Tokenize`).
• All three heredoc bodies in `psmux-continuum.ps1` match their `scripts/*.ps1` artifact byte-for-byte (verified via AST extraction + string compare).
• Start a psmux session, reattach a client 3+ times, then check process list — expect exactly one `auto_save.ps1` pwsh.
• Wait ~16 minutes; verify `%LOCALAPPDATA%\psmux-continuum\auto_save.log` contains an `[INF] auto-saved.` entry.
• Stop the psmux server; expect the loop to log `[WRN] psmux server not running, stopping auto-save.` and exit, releasing the PID file.
• Confirm no `auto_save.ps1` zombies remain across logout/login cycles.

🤖 Generated with Claude Code

[Copilot]

Pull request overview

Fixes a memory-leak / process-accumulation bug in psmux-continuum where the client-attached hook and the Start-Job–based spawn in psmux-continuum.ps1 each created a fresh persistent pwsh loop on every re-attach or plugin reload, with no de-duplication. The fix adds a PID-file singleton guard inside auto_save.ps1, replaces Start-Job with a single detached Start-Process, and adds a file-based logger since the hidden process has no console.

Changes:

• Add per-user singleton guard (PID file at %LOCALAPPDATA%\psmux-continuum\auto_save.pid) with stale-PID detection, periodic supersede check, and graceful slot release in finally.
• Replace Start-Job with Start-Process -WindowStyle Hidden so only one pwsh is spawned per launch; capture all PowerShell streams from the save invocation into a rotated log file (256 KB → .old).
• Refresh the misleading plugin.conf comment, add a "DO NOT EDIT — regenerated" header to all three artifact scripts, and bound long-run memory with periodic [GC]::Collect().

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 1 comment.

Show a summary per file

File	Description
psmux-continuum/psmux-continuum.ps1	Updates the auto-save heredoc with singleton/logging logic, replaces Start-Job with Start-Process, and adds regeneration headers to all three heredocs.
psmux-continuum/scripts/auto_save.ps1	Regenerated artifact mirroring the new singleton-guarded loop with logging and try/finally slot release.
psmux-continuum/scripts/auto_restore.ps1	Adds the "DO NOT EDIT — regenerated" header to match the new convention.
psmux-continuum/scripts/boot.ps1	Adds the "DO NOT EDIT — regenerated" header to match the new convention.
psmux-continuum/plugin.conf	Rewrites the stale "multiple loops may start" comment to describe the new singleton behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[tarikguney]

@CosminRadu Can you please review this comment from CoPilot?

[tarikguney]

PR Review Follow-up

Thank you for this thorough fix, @CosminRadu. The transition to a singleton pattern and the move away from Start-Job significantly improves the resource management of the plugin.

Regarding the Copilot comment, it identifies a potential Time-of-Check to Time-of-Use (TOCTOU) race condition during the PID file claim. While the current implementation is a major step forward, please consider the suggested refinement—either performing a secondary check at the top of the loop or utilizing an exclusive file-creation method—to ensure the singleton guarantee is strictly enforced.

[MattKotsenas]

Hi! I hit this race on my machine today. Adding the log evidence in case it's useful for deciding whether to ship the secondary-check / exclusive-create refinement now vs. as a follow-up.

From %LOCALAPPDATA%\psmux-continuum\auto_save.log:

[2026-05-17 03:45:02] [INF] [PID 17692] auto-saved.
[2026-05-17 03:59:28] [INF] [PID 20696] claimed singleton slot; interval=15m
[2026-05-17 03:59:28] [INF] [PID 20552] claimed singleton slot; interval=15m
[2026-05-17 04:03:47] [INF] [PID 25068] claimed singleton slot; interval=15m
[2026-05-17 04:14:29] [INF] [PID 20552] superseded, exiting.
[2026-05-17 04:14:29] [INF] [PID 20552] exiting; releasing singleton slot.
[2026-05-17 04:14:29] [INF] [PID 20696] exiting; releasing singleton slot.
psmux-resurrect: Saved to C:\Users\matt\.psmux\resurrect\psmux_resurrect_20260517_041851.json

Both PIDs (20696, 20552) claimed the slot at the same second (03:59:28) and ran concurrently as two auto-save loops for ~15 minutes until the supersede check at the next cycle (04:14:29) caught it. A third PID (25068) also claimed the slot at 04:03:47 between those two, suggesting the window is wide enough to hit repeatedly under realistic pwsh startup load (this happened during a normal "open new shell, attach to existing session" workflow, nothing pathological).

The save at 04:18:51 succeeded, but during the 15-minute overlap two auto-save loops were running, doubling the work and racing on file output.

Happy to test a follow-up if helpful; otherwise just leaving this here as the deciding evidence.

[tarikguney]

Thanks for the thorough analysis here, @MattKotsenas and @CosminRadu — really appreciate both the fix and the follow-up validation.

Matt’s log evidence appears to confirm the TOCTOU concern from Copilot: multiple processes can still claim the singleton in the same startup window and run concurrently until the next interval check.

@CosminRadu, would you be open to tightening this before merge (for example, an atomic/exclusive PID-file claim or equivalent) so the singleton guarantee is strict?

Given the reproduced race in normal workflow, I’d prefer we land that hardening in this PR if possible.

[psmux]

Hey @CosminRadu, I want to close this one out but not without saying clearly that your investigation is what put this problem on the map. Five zombie loops totaling about 580 MB after 8 days running, with the oldest having grown from 100 MB to 124 MB, is exactly the kind of concrete, measured evidence that makes a bug report actionable. Thank you for doing that work and writing it up so clearly.

Where things ended up: the singleton enforcement idea you had here is right, and it landed, just via a different mechanism. 0f46ccc added a named mutex in auto_save.ps1 rather than the PID file approach in this PR, so WaitOne(0) on a named mutex decides ownership instead of reading and validating a PID file by hand. Then #28 (merged today, 2e79d2aff075e8a84cadd0266735817644f2ec92) hardened that further, it turned out the mutex fix had a gap where a plugin reload would regenerate auto_save.ps1 from a stale here-string that never got the mutex, silently reverting the fix, and separately the loop still never noticed when the server itself had died. Both of those are closed now, so the process accumulation you measured shouldn't recur, and the loop that remains actually terminates when its server goes away instead of running forever.

Your Start-Job versus Start-Process finding is real too, Start-Job doubling the process count with an outer scriptblock host is a legitimate waste even with singleton enforcement in place, but that's independent of the data-loss and duplication issues that took priority, so it didn't ride along with the mutex fix.

The one idea from this PR that's still genuinely open is the logging piece, writing diagnosable output somewhere durable instead of just a hidden window. Nothing landed on that yet. If you'd like to pick that up as its own focused PR against current main it would be welcome, it's a clean, standalone improvement now that the underlying singleton and lifecycle bugs are handled elsewhere. Closing this one as superseded, but genuinely appreciate the work that went into it.