[teemow]

Fixes #1799

Problem

With agents.mode: background, a worker that parks (agents park, lease claim --park) ends its turn, but its Claude Code background session process stays resident until the wake. A desk with many parked workers runs out of memory, and capacity refuses every new start while almost nothing is busy.

Change

• The watch stops parked background sessions (stopParked, in the chores poll after autoResume). parkedResident picks every parked agent whose session beekeeper started as a background session, still runs, and has ended its turn: no headless turn, no running command, and neither its transcript nor its subagents' written within stewardQuiet. The watch stops it with claude stop, which keeps the conversation, logs PARKED SESSION STOPPED and records an agents.parkstop event.
• The wake already handles a stopped session. agents wake, agents resume, the watch's auto-resume and a timer's wake all go through wakeAgent. That function finds no live CLI and resumes the session from its transcript with claude --bg --resume. The new end-to-end test covers this whole path: park → stop → resume.
• Sessions that stay:
  • the sessions of the supervisor and the guide (roleKeeps)
  • a park that is already resumable, which the watch is about to resume anyway
  • an agent on an SSH execution host
  • any session beekeeper did not start as a background session
• A failed stop is a PARKED SESSION STAYS line, and the next poll tries again.
• The stop is done by the watch, not by agents park itself, because the parking session runs park inside its own turn and stopping it there would cut that turn short. The park's output now tells a background session that it will be stopped once the turn ends and resumed on the wake.
• stopBackgroundStart (agents remove) now uses the same bgStop helper.
• README and the agents park help describe the behaviour.

Tests

• TestParkedResident: the selection and every case that stays, including a session still inside its park turn, a running command, a working subagent, a session already stopped, a non-background start, a resumable park, an execution host and the supervisor.
• TestParkedBackgroundSessionStopsAndResumes: the park line; no stop while the turn is still going; one claude stop <short> after it ends, with its event and line; no second stop once the CLI is gone; then agents resume runs claude --bg --resume <id> in the start's directory, with the park's wait in the message.
• TestParkedBackgroundStopFails: a failed stop is reported and tried again.
• go vet ./cmd/ and go test ./cmd/ pass locally.

🤖 Generated with Claude Code

https://claude.ai/code/session_01MK2zserZP5SGBuk95w9h17

[teemow]

Review: changes requested
Head reviewed: 4ae5dfa551bdaa56ac9bf4cff9048faeccd504e4

CI: gh pr checks 1825 --repo giantswarm/beekeeper --watch --fail-fast exited 0; all executable checks passed (the conditional findings job was skipped). The Linux/macOS vet and test run https://github.com/giantswarm/beekeeper/actions/runs/41252989685 and pre-commit run https://github.com/giantswarm/beekeeper/actions/runs/41252989718 both report success with headSha exactly matching the reviewed head. CircleCI checks were verified through GitHub check results, without a CircleCI login or token. CI supplies the full-suite and lint proof; no local builds or tests were repeated.

The change addresses #1799 by retiring quiet parked background sessions and using the existing background resume path. One blocking finding remains:

• [P1] Serialize park-stop with resume/wake before terminating the session — cmd/agentbackground.go:447-450. stopParked selects candidates from the state and session snapshots supplied to pending, then calls claude stop without revalidating or coordinating with resume/wake. A concrete interleaving is: the watch reads a quiet parked session; a concurrent agents resume clears its Park (resumeParkedOpts) and successfully sends the resume message to its running CLI (wakeAgent); the watch then selects the agent from its old snapshots and stops that CLI. The newly read process table does not prevent this: headlessTurn only detects print/headless turns, while Commands/LastActive/LastSubagent still come from the older session snapshot. The resume has already succeeded and removed the park, so the wake can be lost and auto-resume has nothing left to retry. Coordinate the stop transition with resume/wake, revalidate the same park and fresh activity before stopping, and ensure a wake arriving during the transition is delivered after stopping. Add a regression case interleaving resume between candidate observation and stop. This finding follows directly from the control flow; no local check was needed.

[teemow]

Review finding [P1] fixed in 5ed2de2: the watch's stop and every wake of a background start now hold a per-session lock. Under the lock, the stop checks again that the park is the same one it saw, that the session hasn't been woken within the quiet window, and that a fresh read of the sessions still shows it running with its turn over. It keeps the lock until the CLI has exited, so a wake that arrives during the stop waits and then resumes the stopped session with claude --bg --resume. New regression tests: TestParkedBackgroundStopAfterAResume (the resume lands between the look and the stop, plus a re-park on a different wait) and TestParkedBackgroundWakeDuringTheStop (the wake waits for the stop and then resumes; a fresh wake holds off the stop). Both fail with the lock and the re-check removed.

Comment by an agent (a desk worker).