Auto-pause and stop Codegraff-started localhost servers after inactivity

[yxlyx]

User problem

When Codegraff starts a localhost development/demo server, that server can remain alive for days after the user has stopped looking at it. It is easy to forget because it runs silently in an old terminal/session. Over time, multiple dev servers, file watchers, HMR workers, and related descendants can accumulate and consume memory, CPU, battery, ports, and thermal headroom without the user realizing it.

This was observed during the investigation in #198: a Next.js server on port 3002 had been alive for more than three days. It was mostly CPU-idle, but still retained memory, workers, file watchers, open browser connections, and a port. The broader machine had accumulated many other stale session-owned processes as well.

Feature request

Codegraff should supervise localhost servers that it starts and apply an explicit idle lifecycle, for example:

1. Running while the server is actively being used.
2. Paused/sleeping after a configurable period with no meaningful user traffic or interaction.
3. Stopped after a longer configurable idle period.

The exact defaults and pause mechanism are open to design, but the default should prevent forgotten localhost servers from running indefinitely and invisibly.

Important behavior

• Track the complete process group/tree, not only the initial npm/shell PID.
• Record the command, cwd, detected listening ports, owning Codegraff session, start time, and last meaningful activity.
• Do not treat HMR/WebSocket keepalives from a forgotten browser tab as meaningful user activity forever.
• Warn visibly before pausing/stopping and log what happened.
• Provide an easy resume/restart action using the original command.
• Allow users to pin/keep alive a server that intentionally needs to run indefinitely.
• Make pause and stop thresholds configurable globally and per server/project.
• On Codegraff/session exit, either stop the server tree or explicitly transfer/retain it with user confirmation.
• Only manage processes launched and owned by Codegraff. Never stop an unrelated service merely because it listens on localhost.

UI/CLI visibility

There should be a place to see managed background resources, such as:

localhost:3002  my-website  next dev  idle 42m  [Resume] [Stop] [Keep alive]

A CLI equivalent such as graff processes, graff servers, or graff cleanup would help users discover and clean up forgotten work.

Design note: “pause”

A raw SIGSTOP would retain memory and the port and cannot itself detect a new request. Alternatives could include:

• suspend and require manual/UI resume;
• terminate the real server while a lightweight supervisor retains metadata and offers one-click restart; or
• keep a lightweight port proxy that restarts the server on the next request.

The implementation should make the state clear rather than claiming a process is paused while it still consumes substantial resources.

Acceptance criteria

• A Codegraff-started localhost server is registered with its full process tree and listening port(s).
• After configurable inactivity, it transitions according to the idle policy and the user is notified.
• After the longer timeout, the full server process tree is gone and its resources/port are released.
• The original command can be restarted easily.
• A keep-alive/pin option disables idle cleanup for intentional long-running servers.
• Existing unrelated localhost services are never affected.
• Tests cover HMR child processes, stale browser WebSockets, session interruption, and process-tree cleanup.

Related lifecycle/process-leak report: #198.

[yxlyx]

Stronger current evidence from the same class of failure:

A Next.js dev-server tree started from a Graff-owned process group is still alive after 1 day 13 hours:

• Graff PID/PGID: 2137
• npm run dev -p 3002 and all descendants share PGID 2137 and the same terminal
• server start: five minutes after the affected Graff turn began
• next-server sampled repeatedly at 118–164% CPU
• resident memory fluctuated around 6.0–7.5 GiB
• about 3,288 open files
• .next had zero files modified in the prior 10 minutes, so this was not a legitimate active rebuild burst
• fseventsd simultaneously remained near 100% CPU across repeated samples

The owning trajectory's final report claimed browser/server cleanup was complete, but the process tree survived and is still consuming substantial resources. This makes server supervision more than an idle battery feature: the harness needs ownership tracking and end-of-turn/session cleanup verification. A server that remains hot without meaningful traffic should be detected as unhealthy and surfaced immediately.

[yxlyx]

Cleanup postmortem: launcher exited, server tree remained in Graff's process group

The surviving Lawplain server was inspected and terminated after explicit user authorization. By cleanup time it had continued running for 3 days 4 hours.

Immediately before termination:

Graff:      PID/PGID 2137
npm:        PID 2168, PPID 1, PGID 2137, npm run dev -p 3002
node:       PID 2185, PGID 2137
next-server PID 2186, PGID 2137, 118.9% CPU, RSS 13,565,072 KiB

13,565,072 KiB is approximately 12.9 GiB / 13.9 GB resident memory. The npm process having PPID 1 proves that its launching tool/shell had exited while the background descendant tree survived. The entire server tree still shared the root Graff process group, so a blanket process-group kill would also have killed the active Graff session.

A targeted SIGTERM of the verified npm/Next descendant tree succeeded; no SIGKILL was required. Post-cleanup verification showed:

• port 3002 listeners: 0
• next-server processes: 0
• active Graff PID 2137: preserved

This suggests the supervisor should not let background servers inherit an undifferentiated root-agent process group. It needs a recorded job identity and a dedicated child process group/session, plus descendant-tree cleanup and post-cleanup verification. The ownership record should survive the launching shell's exit and expose PID, port, age, and health to the user.