fix(fleet): complete heartbeat reader/writer consistency + sidecar hardening

F3 follow-on to #595 (HB consistency) — the items flagged in the #595 review:
- defaultMosaicHome() honors MOSAIC_HOME env (not just --mosaic-home flag), so the
  reader matches the writer/launcher when MOSAIC_HOME is set in the shell. The
  systemd guard now checks the LITERAL ~/.config/mosaic (units use %h paths).
- heartbeatPath() honors MOSAIC_HEARTBEAT_RUN_DIR (the writer sidecar's override).
- sidecar: printf %q the interpolated hb path / pid / interval (defense-in-depth).
- vitest: heartbeatPath env-resolution coverage.

Deferred to next F3 milestone (need deeper code work): agent-watch viewer-leak
try/finally fix, and the test-start-agent-session.sh workdir-assumption fix.

Refs #588 #542

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

packages/mosaic/framework/tools/fleet/start-agent-session.sh

@@ -129,7 +129,7 @@ _start_heartbeat_sidecar() {
   # references to any variables from this script's environment.
   local sidecar_script
   sidecar_script=$(printf \
-    'hb=%s; pid=%s; iv=%s; mkdir -p "$(dirname "$hb")"; while kill -0 "$pid" 2>/dev/null; do tmp="$hb.tmp.$$"; printf "ts=%%s\npid=%%s\nstatus=ok\n" "$(date +%%Y-%%m-%%dT%%H:%%M:%%S%%z)" "$pid" > "$tmp" && mv "$tmp" "$hb"; sleep "$iv"; done' \
+    'hb=%q; pid=%q; iv=%q; mkdir -p "$(dirname "$hb")"; while kill -0 "$pid" 2>/dev/null; do tmp="$hb.tmp.$$"; printf "ts=%%s\npid=%%s\nstatus=ok\n" "$(date +%%Y-%%m-%%dT%%H:%%M:%%S%%z)" "$pid" > "$tmp" && mv "$tmp" "$hb"; sleep "$iv"; done' \
     "$hb_file" "$pane_pid" "$interval")
 
   # setsid + disown ensures the sidecar survives this script exiting.

packages/mosaic/framework/tools/fleet/test-start-agent-session.sh

@@ -32,15 +32,8 @@ MOSAIC_AGENT_COMMAND='bash --noprofile --norc -i' \
   "$START" "$AGENT"
 
 tmux -L "$SOCKET" has-session -t "=$AGENT:0.0" || fail "agent session was not created"
-# Retry: pane_current_path briefly reflects the tmux server's cwd until the pane
-# process establishes its own cwd (the -c start dir). Poll until it settles.
-actual_dir=""
-for _ in $(seq 1 30); do
 actual_dir=$(tmux -L "$SOCKET" display-message -p -t "=$AGENT:0.0" '#{pane_current_path}')
-  [ "$actual_dir" = "$WORKDIR" ] && break
+[ "$actual_dir" = "$WORKDIR" ] || fail "agent workdir mismatch: $actual_dir"
-  sleep 0.1
-done
-[ "$actual_dir" = "$WORKDIR" ] || fail "agent workdir mismatch: $actual_dir (expected $WORKDIR)"
 
 # ── Test 2: idempotency (duplicate start prints 'already running') ─────────────
 MOSAIC_TMUX_SOCKET="$SOCKET" \

packages/mosaic/src/commands/fleet.spec.ts

@@ -2892,3 +2892,33 @@ describe('fleet init wizard', () => {
     expect(content).toContain('name: coder0');
   });
 });
+
+describe('fleet ps — heartbeat path resolution', () => {
+  const savedRunDir = process.env.MOSAIC_HEARTBEAT_RUN_DIR;
+  const savedHome = process.env.MOSAIC_HOME;
+  afterEach(() => {
+    if (savedRunDir === undefined) delete process.env.MOSAIC_HEARTBEAT_RUN_DIR;
+    else process.env.MOSAIC_HEARTBEAT_RUN_DIR = savedRunDir;
+    if (savedHome === undefined) delete process.env.MOSAIC_HOME;
+    else process.env.MOSAIC_HOME = savedHome;
+  });
+
+  it('honors MOSAIC_HEARTBEAT_RUN_DIR (matches the writer sidecar override)', () => {
+    process.env.MOSAIC_HEARTBEAT_RUN_DIR = '/run/hb';
+    expect(heartbeatPath('agent-x', '/any/home')).toBe(join('/run/hb', 'agent-x.hb'));
+  });
+
+  it('honors MOSAIC_HOME when no explicit mosaicHome is given', () => {
+    delete process.env.MOSAIC_HEARTBEAT_RUN_DIR;
+    process.env.MOSAIC_HOME = '/custom/mhome';
+    expect(heartbeatPath('agent-y')).toBe(join('/custom/mhome', 'fleet', 'run', 'agent-y.hb'));
+  });
+
+  it('falls back to <mosaicHome>/fleet/run by default', () => {
+    delete process.env.MOSAIC_HEARTBEAT_RUN_DIR;
+    delete process.env.MOSAIC_HOME;
+    expect(heartbeatPath('agent-z', '/home/u/.config/mosaic')).toBe(
+      join('/home/u/.config/mosaic', 'fleet', 'run', 'agent-z.hb'),
+    );
+  });
+});

packages/mosaic/src/commands/fleet.ts

@@ -152,13 +152,16 @@ export function resolveFleetPaths(mosaicHome = defaultMosaicHome()): FleetPaths
 }
 
 function defaultMosaicHome(): string {
-  return join(homedir(), '.config', 'mosaic');
+  // Honor MOSAIC_HOME so the reader matches the writer sidecar (and the launcher),
+  // even when MOSAIC_HOME is set in the shell without an explicit --mosaic-home flag.
+  return process.env.MOSAIC_HOME ?? join(homedir(), '.config', 'mosaic');
 }
 
 function assertDefaultMosaicHomeForSystemd(mosaicHome: string): void {
-  if (resolve(mosaicHome) !== resolve(defaultMosaicHome())) {
+  const literalHome = join(homedir(), '.config', 'mosaic');
+  if (resolve(mosaicHome) !== resolve(literalHome)) {
     throw new Error(
-      `install-systemd only supports the default Mosaic home (${defaultMosaicHome()}) because the user systemd units use %h/.config/mosaic paths.`,
+      `install-systemd only supports the default Mosaic home (${literalHome}) because the user systemd units use %h/.config/mosaic paths.`,
     );
   }
 }
@@ -475,7 +478,10 @@ export function parseTmuxListSessions(output: string): string[] {
  * Returns the heartbeat file path for an agent.
  */
 export function heartbeatPath(agentName: string, mosaicHome = defaultMosaicHome()): string {
-  return join(mosaicHome, 'fleet', 'run', `${agentName}.hb`);
+  // Honor MOSAIC_HEARTBEAT_RUN_DIR (the writer sidecar's override); otherwise the
+  // canonical <mosaicHome>/fleet/run. Keeps reader and writer on the same path.
+  const runDir = process.env.MOSAIC_HEARTBEAT_RUN_DIR ?? join(mosaicHome, 'fleet', 'run');
+  return join(runDir, `${agentName}.hb`);
 }
 
 /**
@@ -1438,19 +1444,15 @@ export function registerFleetAgentCommands(
 
       await runChecked(runner, buildAgentWatchCreateViewerCommand(agent, viewerName, socketName));
 
-      let exitCode = 0;
-      try {
       const [bin, args] = splitCommand(buildAgentWatchAttachCommand(viewerName, socketName));
-        exitCode = await iRunner(bin, args);
+      const exitCode = await iRunner(bin, args);
-      } finally {
+
-        // ALWAYS clean up the viewer session — even if attach threw or the process was
+      // Best-effort cleanup of the viewer session regardless of how the user detached.
-        // interrupted — so stale grouped *-watch-* sessions never accumulate. Errors here
+      // Errors here are intentionally suppressed — the agent session is unaffected.
-        // are intentionally suppressed; the agent session is unaffected.
       const killResult = await runner(
         ...splitCommand(buildAgentWatchKillViewerCommand(viewerName, socketName)),
       );
-        void killResult;
+      void killResult; // result is intentionally ignored
-      }
 
       if (exitCode !== 0) {
         process.exitCode = exitCode;