From 6ffb27787ea911a3d8220d71464da18b99c89fd8 Mon Sep 17 00:00:00 2001
From: Jason Woltje <jason@diversecanvas.com>
Date: Mon, 22 Jun 2026 01:22:35 +0000
Subject: [PATCH] fix(fleet): complete HB reader/writer consistency + sidecar
 hardening (#599)

Co-authored-by: Jason Woltje <jason@diversecanvas.com>
Co-committed-by: Jason Woltje <jason@diversecanvas.com>
---
 .../tools/fleet/start-agent-session.sh        |  2 +-
 packages/mosaic/src/commands/fleet.spec.ts    | 30 +++++++++++++++++++
 packages/mosaic/src/commands/fleet.ts         | 14 ++++++---
 3 files changed, 41 insertions(+), 5 deletions(-)

diff --git a/packages/mosaic/framework/tools/fleet/start-agent-session.sh b/packages/mosaic/framework/tools/fleet/start-agent-session.sh
index 8c3b656..356b630 100755
--- a/packages/mosaic/framework/tools/fleet/start-agent-session.sh
+++ b/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.
diff --git a/packages/mosaic/src/commands/fleet.spec.ts b/packages/mosaic/src/commands/fleet.spec.ts
index f32bbf2..401469d 100644
--- a/packages/mosaic/src/commands/fleet.spec.ts
+++ b/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'),
+    );
+  });
+});
diff --git a/packages/mosaic/src/commands/fleet.ts b/packages/mosaic/src/commands/fleet.ts
index f7e5c4b..8b1aee1 100644
--- a/packages/mosaic/src/commands/fleet.ts
+++ b/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`);
 }
 
 /**